[pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

.gitattributes

@@ -1,13 +1,2 @@
 # Normalize Python files to LF line endings
 *.py text eol=lf
-
-# Always check out shell scripts with LF endings. Without this rule a Windows
-# clone (core.autocrlf=true) rewrites them to CRLF, and the trailing \r breaks
-# them when run in WSL/Linux (e.g. `set -e` -> "set: Illegal option -").
-*.sh text eol=lf
-
-# Normalize Unsloth frontend sources to LF. Scoped to the frontend tree (rather
-# than repo-wide *.ts/*.tsx/... rules) so the policy can't force LF on files
-# elsewhere. text=auto lets Git detect and leave binary assets (logos, fonts)
-# untouched while text files (.ts/.tsx/.json/.html/.svg/...) are stored as LF.
-studio/frontend/** text=auto eol=lf

.github/CODEOWNERS

@@ -6,10 +6,10 @@
 /unsloth/models/rl_replacements.py @Datta0 @pluesclues @danielhanchen
 /unsloth/trainer.py @danielhanchen
 /unsloth/models/sentence_transformer.py @Etherll @danielhanchen
-/unsloth/save.py @danielhanchen
+/unsloth/save.py @rolandtannous @danielhanchen
 /unsloth/tokenizer_utils.py @mmathew23 @danielhanchen
-/unsloth/chat_templates.py @danielhanchen
-/unsloth/ollama_template_mappers.py @danielhanchen
+/unsloth/chat_templates.py @rolandtannous @danielhanchen
+/unsloth/ollama_template_mappers.py @rolandtannous @danielhanchen
 /unsloth/kernels/moe/*.py @Datta0
 /unsloth/import_fixes.py @danielhanchen
 /unsloth/device_type.py @danielhanchen
@@ -45,18 +45,11 @@
 /unsloth/utils/hf_hub.py @mmathew23
 /unsloth/utils/packing.py @mmathew23
 
-/cli/ @Manan17
-/studio/frontend/ @Shine1i @Manan17
+/cli/ @rolandtannous @Manan17
+/studio/frontend/ @Shine1i @rolandtannous @Manan17
 /studio/frontend/public/ @Shine1i
-/studio/backend/
-/studio/backend/core/data_recipe/
-/studio/backend/tests/ @danielhanchen
-/tests/ @danielhanchen
-/scripts/ @danielhanchen
-
-# Snapshot data for the notebook linter / Colab oracle. Drift in these
-# files changes the pin floor for every Unsloth notebook, so refreshes
-# must be reviewed by the notebook owners directly. CODEOWNERS later
-# wins, so this overrides the broader /scripts/ rule above.
-/scripts/data/colab_*.txt  @danielhanchen @shimmyshimmer
-/scripts/data/colab_*.json @danielhanchen @shimmyshimmer
+/studio/backend/ @rolandtannous
+/studio/backend/core/data_recipe/ @rolandtannous
+/studio/backend/tests/ @rolandtannous @danielhanchen
+/tests/ @rolandtannous @danielhanchen
+/scripts/ @rolandtannous @danielhanchen

.github/dependabot.yml

@@ -5,96 +5,23 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
-    cooldown:
-      # github-actions refs are git tags / SHAs, not semver -- the
-      # `semver-minor-days` / `semver-patch-days` knobs are rejected
-      # by Dependabot's validator for this ecosystem. Only the
-      # `default-days` floor applies.
-      default-days: 7
     groups:
       actions:
         patterns: ["*"]
-      actions-security:
-        applies-to: security-updates
-        patterns: ["*"]
 
-  # Removed a stray `package-ecosystem: "bun"` entry for
-  # /studio/frontend: that path has no bun.lock / bun.lockb, so
-  # Dependabot's bun ecosystem silently no-ops on it. The actual
-  # lockfile committed at /studio/frontend is package-lock.json
-  # (npm), and the npm entry further below already catches
-  # npm_and_yarn security advisories for that directory. Version
-  # updates for /studio/frontend stay suppressed (open-pull-
-  # requests-limit: 0 in that entry) -- security PRs flow through
-  # regardless. Add a real bun entry IF and WHEN bun.lock lands.
+  - package-ecosystem: "bun"
+    directory: "/studio/frontend"
+    schedule:
+      interval: "weekly"
+    groups:
+      bun-frontend:
+        patterns: ["*"]
 
   - package-ecosystem: "npm"
     directory: "/studio/backend/core/data_recipe/oxc-validator"
     schedule:
       interval: "weekly"
-    cooldown:
-      default-days: 7
-      semver-minor-days: 3
-      semver-patch-days: 3
     groups:
       npm-oxc-validator:
         patterns: ["*"]
-      npm-oxc-validator-security:
-        applies-to: security-updates
-        patterns: ["*"]
-
-  # pip + cargo grouped weekly; the *-security siblings batch
-  # advisories that would otherwise each open their own PR.
-  - package-ecosystem: "pip"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-    open-pull-requests-limit: 5
-    cooldown:
-      default-days: 7
-    groups:
-      python:
-        patterns: ["*"]
-      python-security:
-        applies-to: security-updates
-        patterns: ["*"]
-
-  - package-ecosystem: "cargo"
-    directory: "/studio/src-tauri"
-    schedule:
-      interval: "weekly"
-    cooldown:
-      default-days: 7
-      semver-minor-days: 3
-      semver-patch-days: 3
-    groups:
-      cargo-tauri:
-        patterns: ["*"]
-      cargo-tauri-security:
-        applies-to: security-updates
-        patterns: ["*"]
-
-  # /studio/frontend npm dependencies. Version-update PRs are
-  # deliberately suppressed (open-pull-requests-limit: 0) -- the
-  # frontend dep tree is large, the lockfile is the authoritative
-  # pin, and `min-release-age=7` in studio/frontend/.npmrc already
-  # blocks fresh tarballs at install time. Security advisories
-  # arrive via GitHub's npm_and_yarn channel and are NOT capped by
-  # `open-pull-requests-limit` per Dependabot's documented
-  # behaviour; they flow through this entry, group together, and
-  # still respect the cooldown below so we never ingest a tarball
-  # that was hot-published less than 3 days ago.
-  - package-ecosystem: "npm"
-    directory: "/studio/frontend"
-    schedule:
-      interval: "weekly"
-    open-pull-requests-limit: 0
-    cooldown:
-      default-days: 7
-      semver-minor-days: 3
-      semver-patch-days: 3
-    groups:
-      npm-frontend-security:
-        applies-to: security-updates
-        patterns: ["*"]
 ...

.github/scripts/agent-guides-drive.sh

@@ -1,699 +0,0 @@
-#!/usr/bin/env bash
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-#
-# Drive one coding agent against the running `unsloth run` server for the
-# Local Agent Guides CI. All failures from here are failure class (c)
-# "guide drift": the server preflight already passed and the agent CLI
-# already installed, so a failure here means the documented recipe in
-# unsloth_cli/commands/start.py no longer produces a working flow.
-#
-# Self-updating: for all six agents (claude, codex, hermes, openclaw,
-# opencode, pi) we obtain the exact env + command from
-# `unsloth start <agent> --no-launch` and run THAT, so a recipe change is
-# exercised automatically.
-#
-# Every agent invocation is wrapped in `timeout` so a headless-TTY prompt
-# can never hang the runner -- a timeout is reported as guide drift with a
-# distinct message.
-#
-# Usage:
-#   agent-guides-drive.sh connection     <agent>
-#   agent-guides-drive.sh file-edit      <agent>
-#   agent-guides-drive.sh attribution-ab claude
-#
-# Required env (exported by serve-unsloth-run.sh):
-#   UNSLOTH_BASE_URL UNSLOTH_API_KEY UNSLOTH_MODEL_ID
-#   UNSLOTH_LLAMA_LOG_DIR  AGENT_INVOKE_TIMEOUT  UNSLOTH_SEED
-set -uo pipefail
-
-MODE="${1:?usage: agent-guides-drive.sh <mode> <agent>}"
-AGENT="${2:?usage: agent-guides-drive.sh <mode> <agent>}"
-
-: "${UNSLOTH_BASE_URL:?serve step did not export UNSLOTH_BASE_URL}"
-: "${UNSLOTH_API_KEY:?serve step did not export UNSLOTH_API_KEY}"
-: "${UNSLOTH_MODEL_ID:?serve step did not export UNSLOTH_MODEL_ID}"
-# Determinism (seed/temp) is applied at the server level by
-# serve-unsloth-run.sh --extra; agents inherit it through the API.
-TIMEOUT="${AGENT_INVOKE_TIMEOUT:-180}"
-# opencode is the slow outlier. Unlike the print-mode agents (claude -p, codex
-# exec) it runs a full turn AND a separate small_model call to name the session,
-# so one connection reply takes ~8 min on a CPU-served 4B -- right at the shared
-# 600s cap, so the cell flaked when a run drifted past a ~480s success. Give it
-# headroom (still well under the 40-min job budget); the fast agents keep the
-# tight cap that still catches a real headless-TTY hang.
-case "$AGENT" in
-  opencode)
-    # Double it, but only for a bare-integer seconds value. A GNU timeout(1)
-    # duration suffix (s/m/h/d, including floats like 0.5s) is left unchanged so
-    # the arithmetic never sees a non-number; timeout(1) parses it directly.
-    case "$TIMEOUT" in
-      *[!0-9]*) ;;
-      *) TIMEOUT=$(( TIMEOUT * 2 )) ;;
-    esac
-    ;;
-esac
-
-# Claude refuses --dangerously-skip-permissions outside a sandbox; the CI runner
-# IS the sandbox, so declare it (mirrors unslothai/scripts launcher.sh). Harmless
-# to the other agents, which ignore it.
-export IS_SANDBOX=1
-
-# Absolute paths anchored at the repo root (this script lives in
-# .github/scripts/). Everything writes here regardless of the current working
-# directory, so the file-edit mode can `cd` into a scratch work dir without
-# breaking log/redaction writes.
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
-LOGS_DIR="$REPO_ROOT/logs"
-REDACTED_DIR="$REPO_ROOT/redacted-configs"
-WORKDIR_BASE="$REPO_ROOT/agent-workdir"
-CACHE_HELPER="$SCRIPT_DIR/assert-prompt-cache.sh"
-mkdir -p "$LOGS_DIR" "$REDACTED_DIR"
-CONNECT_REF="unsloth_cli/commands/start.py"
-
-# Prefill-shrinking flags for Claude Code. The heavyweight agents send
-# multi-thousand-token system prompts + full tool schemas, which on a CPU-only
-# runner is minutes of prefill per model round-trip (~16 tok/s for a 4B model).
-# Replacing the ~5.7k default system prompt with a tiny one (--system-prompt-file)
-# and restricting tools cuts the prefill to a few hundred tokens so it completes
-# quickly on CPU. These only shape the request size; the start.py recipe
-# (endpoint, auth, model) is still exercised end to end.
-#
-# The bulk of Claude Code's prompt is the built-in tool JSON schemas: measured
-# via `claude -p /context`, the default prompt is ~28k tokens of which ~18k is
-# "System tools" alone. --allowedTools/--disallowedTools only gate PERMISSION to
-# call a tool; they do NOT remove its schema from what is sent to the model, so
-# the earlier whitelist left the full ~18k in the prompt and CPU prefill
-# (~16 tok/s) overran claude's own request timeout into a retry loop. --tools is
-# the flag that restricts which schemas are sent. (The ~8k "Memory files" chunk
-# is auto-loaded CLAUDE.md; the unsloth repo ships none, so it is 0 in CI.)
-#
-# Connection probe: --tools "" sends ZERO tool schemas, leaving ~20 tokens total
-# (a one-line --system-prompt-file + the user turn), which prefills instantly.
-CLAUDE_CONNECT_FLAGS=(
-  --system-prompt-file "$SCRIPT_DIR/ci-connect-prompt.txt"
-  --tools ""
-)
-# File-edit: the task needs the file/shell tools, so send only those schemas
-# (~2.3k tokens vs ~18k for the full set).
-CLAUDE_EDIT_FLAGS=(
-  --system-prompt-file "$SCRIPT_DIR/ci-min-system-prompt.txt"
-  --tools "Bash,Edit,Write,Read"
-)
-
-guide_fail() {
-  echo "::error::[guide drift] agent=${AGENT}: $* (preflight passed + install OK, so the documented flow in ${CONNECT_REF} drifted)." >&2
-  exit 1
-}
-
-# Redact the API key from any file we are about to keep as an artifact.
-# Portable across GNU sed (Linux runners) and BSD sed (macOS), so the
-# redaction is never silently skipped.
-redact() {
-  local f
-  for f in "$@"; do
-    [ -f "$f" ] || continue
-    if sed --version >/dev/null 2>&1; then
-      sed -i "s#${UNSLOTH_API_KEY}#<REDACTED>#g" "$f" 2>/dev/null || true
-    else
-      sed -i '' "s#${UNSLOTH_API_KEY}#<REDACTED>#g" "$f" 2>/dev/null || true
-    fi
-  done
-}
-
-# Print a file to the log with the key scrubbed, without mutating it (the raw file is
-# still needed to parse the real env). Use this instead of `cat` for any transcript that
-# carries an `export UNSLOTH_API_KEY=...` line, so a live key never reaches Actions logs.
-cat_redacted() {
-  sed "s#${UNSLOTH_API_KEY}#<REDACTED>#g" "$1"
-}
-
-# A reply must be non-empty and free of connection/auth errors.
-assert_reply() {
-  local out="$1"
-  if [ ! -s "$out" ]; then
-    guide_fail "agent produced an EMPTY reply"
-  fi
-  if grep -qiE 'connection refused|connection error|econnrefused|fetch failed|http 4[0-9][0-9]|unauthorized|invalid api key|authentication failed' "$out"; then
-    guide_fail "agent reply contained a connection/auth error: $(grep -iE 'connection|unauthorized|auth|http 4' "$out" | head -1)"
-  fi
-  echo "[$AGENT] reply (first 20 lines):"
-  head -20 "$out"
-}
-
-# Run a command under a hard timeout; map 124 to a guide-drift hang message.
-run_timed() {  # $1=outfile, rest=command
-  local out="$1"; shift
-  timeout "$TIMEOUT" "$@" > "$out" 2>&1
-  local rc=$?
-  if [ "$rc" -eq 124 ]; then
-    redact "$out"  # guide_fail exits below, so scrub the transcript here too
-    echo "[$AGENT] last 40 lines before timeout:"; tail -40 "$out" 2>/dev/null || true
-    guide_fail "invoke timed out after ${TIMEOUT}s (headless-TTY hang -- the recipe likely needs a non-interactive/print flag)"
-  fi
-  return "$rc"
-}
-
-# Read a value from an `export VAR=...` line in the connect --no-launch output.
-# `unsloth start` writes each agent's session config off the user's ~ and points
-# at it through a relocation env var (CODEX_HOME / OPENCODE_CONFIG /
-# OPENCLAW_CONFIG_PATH), so the contract checks read the path from here.
-raw_env() {  # $1 = var name -> value (one shlex-quote layer stripped)
-  local raw="$LOGS_DIR/connect-${AGENT}.txt"
-  local v; v="$(sed -n "s/^export $1=//p" "$raw" | tail -1)"
-  v="${v#\'}"; v="${v%\'}"; printf '%s' "$v"
-}
-
-# ── 5-agent start.py path: parse env + command from --no-launch ─────────
-# Populates globals CONNECT_ENV (export/unset lines) and CONNECT_CMD (the
-# launch command on the last printed line), and runs start.py's config
-# writers as a side effect (it writes each agent's relocated session config).
-parse_connect() {
-  local raw="$LOGS_DIR/connect-${AGENT}.txt"
-  # CONNECT_YOLO=1 adds --yolo. opencode/openclaw gate tool approval through their
-  # config (which now prompts by default), so the file-edit test opts into auto-approval
-  # here, the same intent as claude/codex's per-call bypass flags.
-  local yolo=()
-  [ -n "${CONNECT_YOLO:-}" ] && yolo=(--yolo)
-  if ! unsloth start "$AGENT" --no-launch "${yolo[@]}" --api-key "$UNSLOTH_API_KEY" > "$raw" 2>&1; then
-    cat_redacted "$raw"
-    guide_fail "'unsloth start ${AGENT} --no-launch' exited non-zero"
-  fi
-  echo "[$AGENT] connect --no-launch printed:"; cat_redacted "$raw"
-  CONNECT_ENV="$(grep -E '^(export |unset )' "$raw" || true)"
-  # The launch command is the last non-export, non-status line. start.py
-  # prints "Unsloth <url> · model <id>" and "Updated ..." status lines first.
-  CONNECT_CMD="$(grep -vE '^(export |unset |Unsloth |Updated |Disabled |Warning|Loading)' "$raw" \
-    | grep -E '[^[:space:]]' | tail -1)"
-  [ -n "$CONNECT_CMD" ] || guide_fail "could not parse a launch command from connect --no-launch output"
-  redact "$raw"
-}
-
-# Cross-check the documented contract knobs so silent start.py changes
-# (env-var rename, wire_api flip, attribution setting drop) also fail/flag.
-crosscheck_contract() {
-  local raw="$LOGS_DIR/connect-${AGENT}.txt"
-  local cfg home
-  case "$AGENT" in
-    codex)
-      grep -q 'UNSLOTH_STUDIO_AUTH_TOKEN' "$raw" \
-        || guide_fail "Codex env key is no longer UNSLOTH_STUDIO_AUTH_TOKEN (start.py _CODEX_ENV_KEY)"
-      home="$(raw_env CODEX_HOME)"
-      # An empty relocation var would make cfg "/config.toml" and silently
-      # skip the [ -f ] contract check below; fail loudly instead.
-      [ -n "$home" ] || guide_fail "CODEX_HOME missing from connect output (start.py codex())"
-      cfg="$home/config.toml"
-      if [ -f "$cfg" ]; then
-        grep -q 'wire_api = "responses"' "$cfg" \
-          || guide_fail "Codex wire_api is no longer \"responses\" in \$CODEX_HOME/config.toml"
-        cp "$cfg" "$REDACTED_DIR/codex-config.toml"
-      fi
-      grep -q 'codex --oss --profile unsloth_api' "$raw" \
-        || echo "::warning::Codex launch command changed from 'codex --oss --profile unsloth_api'"
-      ;;
-    claude)
-      grep -q 'ANTHROPIC_AUTH_TOKEN' "$raw" \
-        || guide_fail "Claude no longer exports ANTHROPIC_AUTH_TOKEN (start.py claude())"
-      grep -q 'CLAUDE_CODE_ATTRIBUTION_HEADER' "$raw" \
-        || echo "::warning::CLAUDE_CODE_ATTRIBUTION_HEADER no longer set for the session (start.py claude())"
-      ;;
-    hermes)
-      grep -q 'UNSLOTH_API_KEY' "$raw" \
-        || guide_fail "Hermes env key is no longer UNSLOTH_API_KEY (start.py _HERMES_ENV_KEY)"
-      home="$(raw_env HERMES_HOME)"
-      [ -n "$home" ] || guide_fail "HERMES_HOME missing from connect output (start.py hermes())"
-      cfg="$home/config.yaml"
-      [ -f "$cfg" ] && cp "$cfg" "$REDACTED_DIR/hermes-config.yaml"
-      ;;
-    openclaw)
-      cfg="$(raw_env OPENCLAW_CONFIG_PATH)"
-      if [ -n "$cfg" ] && [ -f "$cfg" ]; then
-        grep -q '"openai-completions"' "$cfg" \
-          || echo "::warning::OpenClaw provider api is no longer 'openai-completions' (write_openclaw_config)"
-        cp "$cfg" "$REDACTED_DIR/openclaw.json"
-      fi
-      ;;
-    opencode)
-      cfg="$(raw_env OPENCODE_CONFIG)"
-      [ -n "$cfg" ] && [ -f "$cfg" ] && cp "$cfg" "$REDACTED_DIR/opencode.json"
-      ;;
-    pi)
-      # Pi has no config-dir env var; the session is HOME-relocated, and the
-      # provider config lives at $HOME/.pi/agent/models.json.
-      cfg="$(raw_env HOME)/.pi/agent/models.json"
-      if [ -f "$cfg" ]; then
-        grep -q '"openai-completions"' "$cfg" \
-          || echo "::warning::Pi provider api is no longer 'openai-completions' (write_pi_config)"
-        cp "$cfg" "$REDACTED_DIR/pi-models.json"
-      fi
-      ;;
-  esac
-  redact "$REDACTED_DIR"/* 2>/dev/null || true
-}
-
-# Heavyweight agents (hermes, openclaw) bake a large system prompt + tool JSON
-# schemas into every request, which a CPU runner cannot prefill before the invoke
-# timeout. As with claude's --tools, we shrink the request from the agent's own
-# config: zero tools for the connection probe collapses the prompt to a few
-# hundred tokens, since both CLIs gate the bulk of their prompt on having tools.
-
-# Hermes: an explicit empty cli toolset disables all tools (and drops the
-# tool-gated guidance blocks), so -z sends ~300 tokens instead of thousands.
-# Hermes enables its default cli toolset when the session config does not pin one,
-# so we must set platform_toolsets.cli explicitly to [] (not just append) to get
-# zero tools. That needs a YAML parser, and the runner's bare python3 has no
-# PyYAML -- but the venv that ships `unsloth` does (start.py imports yaml), so run
-# the patch with that interpreter. We patch the relocated $HERMES_HOME/config.yaml
-# that `unsloth start` printed, not the user's ~/.hermes.
-# (-z reads platform_toolsets.cli; --ignore-rules is a no-op under -z.)
-patch_hermes_tools() {  # $1 = none|default
-  # Check the raw var BEFORE appending /config.yaml: the joined path is never
-  # empty, so the old guard could not fire and the patcher would die on
-  # "/config.yaml" with a bare traceback instead of this clear failure.
-  local home; home="$(raw_env HERMES_HOME)"
-  [ -n "$home" ] || guide_fail "Hermes HERMES_HOME missing from connect output (start.py hermes())"
-  local cfg; cfg="$home/config.yaml"
-  # Find a python that can import yaml. The runner's bare python3 cannot, but the
-  # interpreter in the `unsloth` console-script shebang provably can (it runs
-  # start.py's write_hermes_config, which imports yaml). Try that first, then
-  # any python on PATH, then the venv sibling, picking the first with PyYAML.
-  local cand py="" shebang
-  shebang="$(head -1 "$(command -v unsloth)" 2>/dev/null | sed -n 's/^#![[:space:]]*//p' | awk '{print $1}')"
-  for cand in "$shebang" python3 python "$(dirname "$(command -v unsloth)")/python"; do
-    [ -n "$cand" ] || continue
-    { [ -x "$cand" ] || command -v "$cand" >/dev/null 2>&1; } || continue
-    if "$cand" -c 'import yaml' 2>/dev/null; then py="$cand"; break; fi
-  done
-  [ -n "$py" ] || guide_fail "could not find a python with PyYAML to patch the hermes session config"
-  echo "[hermes] patching $cfg with $py"
-  "$py" - "$1" "$cfg" <<'PY'
-import os, sys
-import yaml
-mode = sys.argv[1]
-p = sys.argv[2]
-cfg = (yaml.safe_load(open(p)) or {}) if os.path.exists(p) else {}
-ts = cfg.get("platform_toolsets")
-if not isinstance(ts, dict):
-    ts = cfg["platform_toolsets"] = {}
-if mode == "none":
-    ts["cli"] = []          # explicit empty list -> zero tools (not "defaults")
-else:
-    ts.pop("cli", None)     # file-edit needs real tools -> restore defaults
-with open(p, "w") as fh:
-    yaml.safe_dump(cfg, fh, sort_keys=False)
-print(f"[hermes] platform_toolsets.cli = {ts.get('cli', 'default')}")
-PY
-}
-
-# OpenClaw: 'openclaw agent' has no tool/prompt flags, so we define a 'ci' agent
-# in openclaw.json. tools.deny ["*"] sends zero tool schemas (deny always wins)
-# for the connection probe; contextInjection "never" + defaults.skipBootstrap
-# drop the auto-injected AGENTS.md/SOUL.md bootstrap (the bulk of the prompt) for
-# both modes. --agent must reference a defined agent, so write it before invoking.
-patch_openclaw_agent() {  # $1 = notools|tools
-  # OpenClaw reads its config from the relocated OPENCLAW_CONFIG_PATH that
-  # `unsloth start` printed, so patch THAT file (not the user's ~/.openclaw).
-  local cfg; cfg="$(raw_env OPENCLAW_CONFIG_PATH)"
-  [ -n "$cfg" ] || guide_fail "OpenClaw OPENCLAW_CONFIG_PATH missing from connect output (start.py openclaw())"
-  python3 - "$1" "$cfg" <<'PY'
-import os, sys, json
-mode = sys.argv[1]
-p = sys.argv[2]
-cfg = json.load(open(p)) if os.path.exists(p) else {}
-agents = cfg.setdefault("agents", {})
-agents.setdefault("defaults", {})["skipBootstrap"] = True
-lst = [a for a in agents.get("list", []) if a.get("id") != "ci"]
-agent = {"id": "ci", "contextInjection": "never"}
-if mode == "notools":
-    agent["tools"] = {"deny": ["*"]}
-lst.append(agent)
-agents["list"] = lst
-with open(p, "w") as fh:
-    json.dump(cfg, fh, indent=2)
-print(f"[openclaw] agent ci tools = {agent.get('tools', 'default')}")
-PY
-}
-
-# Build an invoke script that applies start.py's env then runs the launch
-# command (with extra args appended) under bash. We do NOT eval connect's env
-# into this shell; we write it into a one-shot script so the export/unset
-# semantics are exactly what start.py printed. The script path is absolute
-# so it is valid even when the caller has cd'd into a scratch work dir.
-invoke_via_connect() {  # $1=outfile, rest=extra args appended to the command
-  local out="$1"; shift
-  local script="$LOGS_DIR/invoke-${AGENT}.sh"
-  local real; real="$(mktemp)"
-  # CONNECT_ENV_EXTRA / CONNECT_CMD_OVERRIDE let a caller (attribution-ab) flip a
-  # session knob without editing the user's config; empty -> use what start.py emitted.
-  local cmd="${CONNECT_CMD_OVERRIDE:-$CONNECT_CMD}"
-  {
-    echo "set -uo pipefail"
-    echo "$CONNECT_ENV"
-    [ -n "${CONNECT_ENV_EXTRA:-}" ] && echo "$CONNECT_ENV_EXTRA"
-    # Append extra args (the prompt / flags) to the launch command verbatim.
-    printf '%s' "$cmd"
-    local a
-    for a in "$@"; do printf ' %q' "$a"; done
-    printf '\n'
-  } > "$real"
-  # Upload a REDACTED copy of the script, but EXECUTE the un-redacted one from a
-  # temp path outside the artifact dir. Redacting the script we run would turn
-  # the real `export TOKEN=sk-...` line into `export TOKEN=<REDACTED>`, which is
-  # invalid bash (the `<`/`>` are redirections) and silently breaks every agent.
-  # Writing the redacted copy up front keeps the key out of the artifact even if
-  # the run times out (run_timed exits before returning here).
-  cp "$real" "$script"; redact "$script"
-  # The connect one-liner now carries the key as an inline env assignment; scrub it on
-  # the way to the log (the executed $real keeps the live value).
-  echo "[$AGENT] invoking (timeout ${TIMEOUT}s): ${cmd//${UNSLOTH_API_KEY}/<REDACTED>} $*"
-  run_timed "$out" bash "$real"
-  local rc=$?
-  rm -f "$real"
-  redact "$out"  # the transcript can echo the token; scrub before upload
-  return "$rc"
-}
-
-# ═════════════════════════════════════════════════════════════════════════
-case "$MODE" in
-  # ── connection: trivial prompt, assert a non-empty, error-free reply ────
-  connection)
-    PROMPT='Reply with exactly the single word: pong'
-    OUT="$LOGS_DIR/${AGENT}-connection.txt"
-    parse_connect
-    crosscheck_contract
-    # claude/codex run in print mode via the flags start.py emits
-    # (claude -p / codex exec). For agents whose default subcommand prints
-    # to stdout we pass the prompt through ctx.args.
-    case "$AGENT" in
-      claude)   invoke_via_connect "$OUT" "${CLAUDE_CONNECT_FLAGS[@]}" -p "$PROMPT" ;;
-      codex)    invoke_via_connect "$OUT" exec --dangerously-bypass-approvals-and-sandbox "$PROMPT" ;;
-      opencode) invoke_via_connect "$OUT" run "$PROMPT" ;;
-      pi)       invoke_via_connect "$OUT" -p "$PROMPT" ;;
-      hermes)   patch_hermes_tools none
-                invoke_via_connect "$OUT" -z "$PROMPT" ;;
-      openclaw) patch_openclaw_agent notools
-                CONNECT_CMD_OVERRIDE=openclaw invoke_via_connect "$OUT" agent --local --agent ci \
-                  --model "unsloth/${UNSLOTH_MODEL_ID}" --message "$PROMPT" ;;
-      *)        invoke_via_connect "$OUT" "$PROMPT" ;;
-    esac
-    # A non-zero exit from the documented launch command is drift even if it
-    # printed something: a benign-looking "command not found" / usage dump would
-    # otherwise slip past assert_reply (which only flags empty/error-keyword text).
-    rc=$?
-    [ "$rc" -eq 0 ] || guide_fail "the documented launch command exited non-zero (rc=$rc) -- see the transcript above"
-    assert_reply "$OUT"
-    echo "[$AGENT] connection OK"
-    ;;
-
-  # ── file-edit: deterministic 2-turn hello.py test (Qwen3.5-2B) ──────────
-  file-edit)
-    WORK="$WORKDIR_BASE/${AGENT}"
-    rm -rf "$WORK"; mkdir -p "$WORK"
-    OUT1="$LOGS_DIR/${AGENT}-fileedit-turn1.txt"
-    OUT2="$LOGS_DIR/${AGENT}-fileedit-turn2.txt"
-    T1='Create a file named hello.py in the current directory whose entire contents are a single line: print("Hello"). Do not run it.'
-    T2='Run hello.py with python and show me the exact output.'
-
-    # The start.py recipe writers + crosscheck must see the repo; run them
-    # from the repo root BEFORE cd-ing into the scratch work dir. opencode/openclaw
-    # gate tool approval through their config (prompting by default), so file-edit
-    # opts them into auto-approval to run edits/commands headlessly.
-    case "$AGENT" in opencode|openclaw) CONNECT_YOLO=1 ;; esac
-    parse_connect
-    crosscheck_contract
-    # File-edit needs real tools, so we cannot zero them as in connection.
-    # hermes keeps default tools; openclaw still strips its AGENTS.md/SOUL.md
-    # bootstrap (the largest prompt chunk) via the 'ci' agent. The scratch work
-    # dir is empty, so no project context files are auto-loaded either.
-    case "$AGENT" in
-      hermes)   patch_hermes_tools default ;;
-      openclaw) patch_openclaw_agent tools ;;
-    esac
-
-    # Drive from inside the work dir so the agent edits files there. All log
-    # writes use absolute $LOGS_DIR, so cwd does not matter for them.
-    cd "$WORK" || guide_fail "could not enter work dir $WORK"
-
-    invoke_turn() {  # $1=outfile $2=continue? $3=prompt
-      local out="$1" cont="$2" prompt="$3"
-      case "$AGENT" in
-        pi)
-          # Pi continues the previous session with -c; provider/model come from
-          # the parsed `unsloth start pi` recipe (CONNECT_CMD), not hardcoded here.
-          if [ "$cont" = "continue" ]; then
-            invoke_via_connect "$out" -p --continue "$prompt"
-          else
-            invoke_via_connect "$out" -p "$prompt"
-          fi ;;
-        claude)
-          # --dangerously-skip-permissions lets headless claude actually use the
-          # Write/Bash tools (otherwise it blocks on an approval prompt and emits
-          # nothing). IS_SANDBOX=1 (exported above) authorizes it.
-          if [ "$cont" = "continue" ]; then
-            invoke_via_connect "$out" "${CLAUDE_EDIT_FLAGS[@]}" --dangerously-skip-permissions -p --continue "$prompt"
-          else
-            invoke_via_connect "$out" "${CLAUDE_EDIT_FLAGS[@]}" --dangerously-skip-permissions -p "$prompt"
-          fi ;;
-        codex)
-          # --dangerously-bypass-approvals-and-sandbox gives codex exec
-          # workspace-write (default is read-only -> cannot create hello.py) and
-          # skips the bubblewrap sandbox that the runner lacks.
-          if [ "$cont" = "continue" ]; then
-            invoke_via_connect "$out" exec --dangerously-bypass-approvals-and-sandbox resume --last "$prompt"
-          else
-            invoke_via_connect "$out" exec --dangerously-bypass-approvals-and-sandbox "$prompt"
-          fi ;;
-        opencode) invoke_via_connect "$out" run "$prompt" ;;
-        hermes)   invoke_via_connect "$out" -z "$prompt" ;;
-        openclaw) CONNECT_CMD_OVERRIDE=openclaw invoke_via_connect "$out" agent --local --agent ci \
-                    --model "unsloth/${UNSLOTH_MODEL_ID}" --message "$prompt" ;;
-        *)        invoke_via_connect "$out" "$prompt" ;;
-      esac
-    }
-
-    # Turn 1: create hello.py.
-    invoke_turn "$OUT1" fresh "$T1"
-    # Fail on a non-zero agent exit before trusting side effects: an agent can
-    # error out (API/tool failure) yet leave a plausible file/transcript behind,
-    # which would otherwise slip past the assertions below (mirrors connection).
-    rc=$?
-    [ "$rc" -eq 0 ] || { echo "[$AGENT] turn-1 transcript:"; tail -40 "$OUT1" 2>/dev/null || true; \
-      guide_fail "turn 1 (create hello.py) exited non-zero (rc=$rc)"; }
-
-    # Hard assertions on the side effect (the real test): file + content + run.
-    if [ ! -f hello.py ]; then
-      echo "[$AGENT] turn-1 transcript:"; tail -40 "$OUT1" 2>/dev/null || true
-      guide_fail "turn 1 did not create hello.py"
-    fi
-    grep -q 'Hello' hello.py || guide_fail "hello.py does not contain 'Hello'"
-    RUN_OUT="$(python3 hello.py 2>&1 || true)"
-    [ "$RUN_OUT" = "Hello" ] || guide_fail "python3 hello.py printed '$RUN_OUT', expected exactly 'Hello'"
-    echo "[$AGENT] turn 1 OK (file created, prints 'Hello')"
-
-    # Turn 2: same cwd + session continuation; assert the agent's run output
-    # contains Hello. Narration drift is WARN-only, missing output is a hard fail.
-    invoke_turn "$OUT2" continue "$T2"
-    rc=$?
-    [ "$rc" -eq 0 ] || { echo "[$AGENT] turn-2 transcript:"; tail -60 "$OUT2" 2>/dev/null || true; \
-      guide_fail "turn 2 (run hello.py) exited non-zero (rc=$rc)"; }
-    if grep -q 'Hello' "$OUT2"; then
-      echo "[$AGENT] turn 2 OK (run output contains 'Hello')"
-    else
-      echo "[$AGENT] turn-2 transcript:"; tail -60 "$OUT2" 2>/dev/null || true
-      guide_fail "turn 2 run/bash output did not contain 'Hello'"
-    fi
-    cd "$REPO_ROOT" || true
-    echo "[$AGENT] file-edit OK"
-    ;;
-
-  # ── attribution-ab: Claude Code KV-cache HIT vs MISS ────────────────────
-  attribution-ab)
-    [ "$AGENT" = "claude" ] || guide_fail "attribution-ab only applies to claude"
-    # The llama-server log filename uses the INTERNAL random llama.cpp port,
-    # not STUDIO_PORT, so we never glob by port: assert-prompt-cache.sh picks
-    # the newest llama-*.log and we slice it by a byte offset (`mark`) captured
-    # right before the measured turn, so an earlier turn's reuse can't leak in.
-    LLAMA_LOG_DIR="${UNSLOTH_LLAMA_LOG_DIR:-$HOME/.unsloth/studio/logs/llama-server}"
-    export LLAMA_LOG_DIR
-    parse_connect          # prints session env + suppression flags (no ~/.claude write)
-    crosscheck_contract
-    PROMPT='Reply with exactly the single word: pong'
-
-    # Phase A: the suppression start.py ships (CLAUDE_CODE_ATTRIBUTION_HEADER=0 +
-    # --exclude-dynamic-system-prompt-sections + --settings overlay) -> expect a
-    # HIT on the continued turn, since the system-prompt prefix is stable.
-    invoke_via_connect "$LOGS_DIR/claude-ab-hit-1.txt" -p "$PROMPT"        # turn 1 primes
-    FROM_HIT="$(bash "$CACHE_HELPER" mark)"                                # offset before turn 2
-    invoke_via_connect "$LOGS_DIR/claude-ab-hit-2.txt" -p --continue "$PROMPT again"
-    CACHE_LOG_FROM="$FROM_HIT" bash "$CACHE_HELPER" log HIT
-
-    # Phase B: vanilla Claude with the header ENABLED -> expect a MISS. We flip
-    # the env var to 1 and strip the suppression flags from the launch command
-    # (without them the dynamic attribution line is included and changes every
-    # turn, so the shared prefix moves and the KV cache is invalidated, ~90%
-    # slower). This is session-only: nothing is written to ~/.claude.
-    CONNECT_ENV_EXTRA='export CLAUDE_CODE_ATTRIBUTION_HEADER=1'
-    CONNECT_CMD_OVERRIDE="$(printf '%s' "$CONNECT_CMD" \
-      | sed -E "s/ --exclude-dynamic-system-prompt-sections//; s/ --settings '[^']*'//")"
-    invoke_via_connect "$LOGS_DIR/claude-ab-miss-1.txt" -p "$PROMPT"
-    FROM_MISS="$(bash "$CACHE_HELPER" mark)"
-    invoke_via_connect "$LOGS_DIR/claude-ab-miss-2.txt" -p --continue "$PROMPT again"
-    CACHE_LOG_FROM="$FROM_MISS" bash "$CACHE_HELPER" log MISS
-    unset CONNECT_ENV_EXTRA CONNECT_CMD_OVERRIDE
-    echo "[claude] attribution A/B OK (suppressed HIT, header=1 MISS)"
-    ;;
-
-  # ── resume: does a launched agent's session survive exit and resume? ────
-  # Unlike the other modes, this drives the real LAUNCH path (`unsloth start
-  # <agent> ...`, the interactive default), not the --no-launch recipe. That
-  # path relocates each agent's home to a throwaway temp dir wiped on exit, so
-  # a session cannot be resumed -- unless --persist routes it to the stable
-  # Unsloth agents dir instead. We run one headless turn per pass and check
-  # whether the turn left a session in a persistent store (deterministic, no
-  # reliance on the model recalling anything), for a baseline pass and a
-  # --persist pass, and assert the expected split for this agent.
-  resume)
-    CODEWORD="PLATYPUS7"
-    T1="Remember this codeword for later: ${CODEWORD}. Reply with just the word OK."
-    T2="What codeword did I ask you to remember? Reply with just that word."
-    WORK="$WORKDIR_BASE/${AGENT}-resume"
-
-    # STABLE_HOME: the stable dir that --no-launch (and --persist) relocate to.
-    # Read it from a --no-launch probe (which also writes the agent's config
-    # there). codex/pi relocate their whole home/HOME here; opencode/claude keep
-    # their session data in a fixed user dir, so STABLE_HOME stays empty for them.
-    parse_connect
-    case "$AGENT" in
-      codex)    STABLE_HOME="$(raw_env CODEX_HOME)" ;;
-      pi)       STABLE_HOME="$(raw_env HOME)" ;;
-      *)        STABLE_HOME="" ;;
-    esac
-
-    # The persistent stores a session would land in if it were NOT wiped. We
-    # count files here before/after each turn; a positive delta means the
-    # session persisted (is resumable), zero means it went to a wiped temp dir.
-    resume_tracked_dirs() {
-      case "$AGENT" in
-        codex)    printf '%s\n' "$HOME/.codex" ;;
-        opencode) printf '%s\n' "$HOME/.local/share/opencode" "$HOME/.config/opencode" ;;
-        claude)   printf '%s\n' "$HOME/.claude" ;;
-        pi)       printf '%s\n' "$HOME/.pi" ;;
-        *)        : ;;
-      esac
-      [ -n "$STABLE_HOME" ] && printf '%s\n' "$STABLE_HOME"
-    }
-    count_session_files() {
-      local total=0 d n
-      while IFS= read -r d; do
-        [ -n "$d" ] && [ -d "$d" ] || continue
-        n="$(find "$d" -type f 2>/dev/null | wc -l)"; total=$((total + n))
-      done < <(resume_tracked_dirs)
-      echo "$total"
-    }
-
-    # The headless first-turn subcommand per agent (mirrors file-edit's map),
-    # forwarded verbatim through the launch path as passthrough args.
-    set_t1_cmd() {
-      case "$AGENT" in
-        claude)   T1_CMD=("${CLAUDE_CONNECT_FLAGS[@]}" -p "$T1") ;;
-        codex)    T1_CMD=(exec "$T1") ;;
-        opencode) T1_CMD=(run "$T1") ;;
-        pi)       T1_CMD=(-p "$T1") ;;
-        *)        guide_fail "resume mode does not cover agent '$AGENT'" ;;
-      esac
-    }
-
-    # Run one headless turn through the launch path. $1=outfile, $2="" or
-    # "--persist", rest = the agent subcommand. --yolo auto-approves so no tool
-    # prompt can hang; --api-key attaches to the already-served CI model.
-    launch_turn() {
-      local out="$1" rflag="$2"; shift 2
-      local flag=(); [ -n "$rflag" ] && flag=("$rflag")
-      run_timed "$out" unsloth start "$AGENT" "${flag[@]}" --yolo \
-        --api-key "$UNSLOTH_API_KEY" "$@"
-      local rc=$?
-      redact "$out"
-      return "$rc"
-    }
-
-    # One pass: fresh work dir, one planting turn, set RESULT to PERSISTED/WIPED
-    # from the session-store delta. Runs in the main shell (not a command
-    # substitution) so a hang's guide_fail actually fails the job and the
-    # progress lines reach the CI log. $1 = "" (baseline) or "--persist".
-    RESULT=""
-    run_pass() {
-      local rflag="$1" label="baseline"
-      [ -n "$rflag" ] && label="resume"
-      rm -rf "$WORK"; mkdir -p "$WORK"
-      set_t1_cmd
-      local out="$LOGS_DIR/${AGENT}-resume-${label}.txt"
-      local before after rc
-      before="$(count_session_files)"
-      pushd "$WORK" >/dev/null || guide_fail "could not enter work dir $WORK"
-      launch_turn "$out" "$rflag" "${T1_CMD[@]}"; rc=$?
-      popd >/dev/null || true
-      after="$(count_session_files)"
-      echo "[$AGENT] ${label}: session files ${before} -> ${after} (rc=${rc})"
-      # The turn must succeed for the delta to mean anything: an agent that writes a
-      # session file then errors would otherwise be misread as PERSISTED. Mirror the
-      # file-edit mode and fail the pass on a non-zero launch (the flagship codex recall
-      # below stays WARN-only, driven by its own launch_turn calls).
-      [ "$rc" -eq 0 ] || { echo "[$AGENT] ${label} transcript (tail):"; tail -30 "$out" 2>/dev/null || true; \
-        guide_fail "resume ${label} turn for ${AGENT} exited non-zero (rc=${rc})"; }
-      if [ "$after" -gt "$before" ]; then RESULT="PERSISTED"; else RESULT="WIPED"; fi
-    }
-
-    run_pass ""; BASELINE="$RESULT"
-    # Only the temp-dir agents (codex/pi) need the --persist pass to prove the fix.
-    # opencode/claude persist either way, so the baseline already proves it and a
-    # second full CPU turn only risks a timeout; skip it for them.
-    case "$AGENT" in
-      codex|pi) run_pass "--persist"; RESUME="$RESULT" ;;
-      *)        RESUME="n/a (persists either way)" ;;
-    esac
-
-    # Expected: codex/pi relocate their whole home to the temp dir, so a plain
-    # launch is WIPED and only --persist PERSISTS. opencode/claude keep their
-    # session data in a fixed user dir, so the baseline already PERSISTS.
-    case "$AGENT" in
-      codex|pi)        EXPECT_BASELINE="WIPED" ;;
-      opencode|claude) EXPECT_BASELINE="PERSISTED" ;;
-    esac
-
-    echo "──────────────────────────────────────────────"
-    echo "[$AGENT] RESUME EXPERIMENT"
-    echo "  baseline (unsloth start ${AGENT}):                 ${BASELINE}  (expected ${EXPECT_BASELINE})"
-    echo "  with --persist (unsloth start ${AGENT} --persist): ${RESUME}"
-    echo "──────────────────────────────────────────────"
-
-    [ "$BASELINE" = "$EXPECT_BASELINE" ] \
-      || guide_fail "baseline resume behavior for ${AGENT} was ${BASELINE}, expected ${EXPECT_BASELINE}"
-    case "$AGENT" in
-      codex|pi)
-        [ "$RESUME" = "PERSISTED" ] \
-          || guide_fail "--persist did not persist ${AGENT}'s session (got ${RESUME}); the session dir is still not stable" ;;
-    esac
-
-    # Flagship behavioral proof (codex only, WARN-only): after a --persist plant,
-    # resume the session and check the model actually recalls the codeword. A
-    # miss is not a failure (the CI model is small); the mechanism gate above is
-    # the real assertion.
-    if [ "$AGENT" = "codex" ]; then
-      rm -rf "$WORK"; mkdir -p "$WORK"
-      ( cd "$WORK" && launch_turn "$LOGS_DIR/codex-resume-plant.txt" "--persist" exec "$T1" ) || true
-      ( cd "$WORK" && launch_turn "$LOGS_DIR/codex-resume-recall.txt" "--persist" exec resume --last "$T2" ) || true
-      if grep -q "$CODEWORD" "$LOGS_DIR/codex-resume-recall.txt" 2>/dev/null; then
-        echo "[codex] behavioral recall HIT: resumed session remembered ${CODEWORD}"
-      else
-        echo "::warning::[codex] behavioral recall MISS (small CI model); mechanism gate still passed"
-      fi
-    fi
-    echo "[$AGENT] resume OK"
-    ;;
-
-  *)
-    echo "agent-guides-drive.sh: unknown mode '$MODE'" >&2
-    exit 2
-    ;;
-esac

.github/scripts/agent-guides-install.sh

@@ -1,108 +0,0 @@
-#!/usr/bin/env bash
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-#
-# Install one coding-agent CLI for the Local Agent Guides CI. Isolated as
-# failure class (b) "agent package install failed": npm/curl flakiness here
-# is the single biggest source of false reds, so installs retry with
-# backoff and the only ::error:: this script can emit is class (b). The
-# install recipes mirror the install_hint strings in
-# unsloth_cli/commands/start.py at HEAD.
-#
-# Usage: agent-guides-install.sh <agent>
-#   agent in: claude codex hermes openclaw opencode pi
-set -uo pipefail
-
-AGENT="${1:?usage: agent-guides-install.sh <agent>}"
-mkdir -p logs
-LOG="logs/install-${AGENT}.log"
-
-install_fail() {
-  echo "::error::[agent install failed] agent=${AGENT}: $* (class (b): the agent CLI did not install; not a server or guide problem)." >&2
-  echo "---- tail $LOG ----" >&2
-  tail -60 "$LOG" 2>/dev/null || true
-  exit 1
-}
-
-# npm registry flakiness is common in CI; retry 3x with linear backoff.
-# Extra npm flags may precede the package (e.g. npm_retry --ignore-scripts pkg).
-npm_retry() {
-  local i
-  for i in 1 2 3; do
-    if npm install -g "$@" >> "$LOG" 2>&1; then
-      return 0
-    fi
-    echo "[install] npm install -g $* attempt $i failed; backing off $((i * 10))s" | tee -a "$LOG"
-    sleep "$((i * 10))"
-  done
-  return 1
-}
-
-# curl|bash installers, retried at the curl layer. We download to a temp file
-# first and only execute on a fully successful fetch, so a truncated download
-# (network hiccup mid-stream) can never run a half-written installer.
-curl_bash() {
-  local url="$1"; shift
-  local i tmp
-  tmp="$(mktemp)"
-  for i in 1 2 3; do
-    if curl -fsSL --retry 3 --retry-delay 5 "$url" -o "$tmp" 2>>"$LOG" \
-        && bash "$tmp" "$@" >> "$LOG" 2>&1; then
-      rm -f "$tmp"
-      return 0
-    fi
-    echo "[install] curl|bash $url attempt $i failed; backing off $((i * 10))s" | tee -a "$LOG"
-    sleep "$((i * 10))"
-  done
-  rm -f "$tmp"
-  return 1
-}
-
-echo "[install] agent=$AGENT (log=$LOG)"
-case "$AGENT" in
-  claude)
-    # start.py install_hint: curl -fsSL https://claude.ai/install.sh | bash
-    curl_bash "https://claude.ai/install.sh" || install_fail "claude installer failed"
-    # The installer drops the binary under ~/.local/bin.
-    echo "$HOME/.local/bin" >> "$GITHUB_PATH"
-    ;;
-  codex)
-    # start.py install_hint: npm install -g @openai/codex
-    npm_retry "@openai/codex" || install_fail "npm install -g @openai/codex failed"
-    ;;
-  opencode)
-    # start.py install_hint: npm install -g opencode-ai
-    npm_retry "opencode-ai" || install_fail "npm install -g opencode-ai failed"
-    ;;
-  openclaw)
-    # start.py install_hint: curl -fsSL https://openclaw.ai/install.sh | bash
-    # npm is the more deterministic path in CI and matches the agent's docs;
-    # fall back to the start.py curl installer if the npm tag is missing.
-    if ! npm_retry "openclaw@latest"; then
-      curl_bash "https://openclaw.ai/install.sh" || install_fail "openclaw install failed (npm + curl)"
-      echo "$HOME/.local/bin" >> "$GITHUB_PATH"
-    fi
-    ;;
-  hermes)
-    # start.py install_hint:
-    #   curl -fsSL .../NousResearch/hermes-agent/main/scripts/install.sh | bash
-    curl_bash "https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh" \
-      --non-interactive --skip-setup --skip-browser --no-skills \
-      || install_fail "hermes installer failed"
-    echo "$HOME/.local/bin" >> "$GITHUB_PATH"
-    ;;
-  pi)
-    # start.py install_hint: npm install -g --ignore-scripts @earendil-works/pi-coding-agent
-    # (--ignore-scripts matches Pi's documented recipe; exercising the exact hint
-    # catches guide drift). The CLI moved from the now-deprecated @mariozechner
-    # scope to @earendil-works (the old scope is frozen, so installing it would
-    # test a stale Pi against the API).
-    npm_retry --ignore-scripts "@earendil-works/pi-coding-agent" \
-      || install_fail "npm install -g --ignore-scripts @earendil-works/pi-coding-agent failed"
-    ;;
-  *)
-    install_fail "unknown agent '$AGENT'"
-    ;;
-esac
-
-echo "[install] OK for $AGENT"

.github/scripts/assert-llama-loads.sh

@@ -1,57 +0,0 @@
-#!/usr/bin/env bash
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-#
-# Assert Unsloth installed a llama.cpp that loads and runs on THIS macOS. Tests
-# the contract that matters (binaries load and their minimum-OS is <= this host)
-# instead of the old "did install.sh fall back to a source build?" grep, since a
-# source build with a correct deployment target is a valid outcome.
-set -uo pipefail
-
-UNSLOTH_HOME="${STUDIO_HOME:-$HOME/.unsloth}"
-LLAMA_DIR="${LLAMA_CPP_DIR:-$UNSLOTH_HOME/llama.cpp}"
-BIN_DIR="$LLAMA_DIR/build/bin"
-
-fail() {
-  echo "::error::$*"
-  if [ -f logs/install.log ]; then
-    echo "---- install.log (llama.cpp lines) ----"
-    grep -E "llama-prebuilt|llama\.cpp|macos prebuilt|falling back" logs/install.log | tail -80 || true
-  fi
-  exit 1
-}
-
-SERVER="$(find "$LLAMA_DIR" -type f -name 'llama-server' 2>/dev/null | head -1)"
-QUANT="$(find "$LLAMA_DIR" -type f -name 'llama-quantize' 2>/dev/null | head -1)"
-[ -n "$SERVER" ] || fail "llama-server not found under $LLAMA_DIR after install"
-[ -n "$QUANT" ]  || fail "llama-quantize not found under $LLAMA_DIR after install"
-
-HOST_VER="$(sw_vers -productVersion 2>/dev/null || echo '0')"
-HOST_MAJOR="${HOST_VER%%.*}"
-
-# Static minimum-OS check on every Mach-O we ship. vtool ships with the Xcode
-# command line tools, which GitHub macOS runners always have; if it is somehow
-# missing we skip the static check and rely on the runtime launch below.
-if command -v vtool >/dev/null 2>&1; then
-  while IFS= read -r macho; do
-    [ -n "$macho" ] || continue
-    minos="$(vtool -show-build "$macho" 2>/dev/null | awk '/minos/{print $2; exit}')"
-    [ -n "$minos" ] || continue
-    min_major="${minos%%.*}"
-    if [ "$min_major" -gt "$HOST_MAJOR" ] 2>/dev/null; then
-      fail "$(basename "$macho") is built for macOS $minos but this runner is macOS $HOST_VER (prebuilt is newer than the host)"
-    fi
-  done < <(find "$BIN_DIR" -type f \( -name '*.dylib' -o -name 'llama-server' -o -name 'llama-quantize' \) 2>/dev/null)
-fi
-
-# Runtime launch: --version forces dyld to load every linked dylib (including
-# libggml-metal.dylib). A missing Metal symbol or too-new binary fails here.
-if ! "$SERVER" --version >/tmp/llama-server-version.txt 2>&1; then
-  echo "---- llama-server --version output ----"
-  cat /tmp/llama-server-version.txt || true
-  fail "llama-server failed to launch on macOS $HOST_VER (dyld load / symbol error)"
-fi
-
-echo "llama.cpp load validation passed on macOS $HOST_VER"
-echo "  server: $SERVER"
-sed -n '1,4p' /tmp/llama-server-version.txt 2>/dev/null || true

.github/scripts/assert-prompt-cache.sh

@@ -1,238 +0,0 @@
-#!/usr/bin/env bash
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-#
-# Prompt-cache (KV-cache prefix reuse) detection, two strategies in one helper:
-#
-#   mode=api     A 2-turn /v1/chat/completions probe. Turn 2 prepends turn 1 +
-#                its reply, so the shared prefix must be served from llama.cpp's
-#                KV cache. Asserts usage.prompt_tokens_details.cached_tokens > 0
-#                on turn 2. This is the OpenAI-dialect server cache sanity.
-#                WHY this works on chat completions: the chat path forwards
-#                llama-server's real cached_tokens through
-#                studio/backend/routes/inference.py:482-489 (_prompt_tokens_details)
-#                into prompt_tokens_details (inference.py:519).
-#
-#   mode=log     Read the llama-server log and decide HIT vs MISS from the
-#                prompt-reprocessing trace. WHY the log (not the API field):
-#                the Anthropic /v1/messages path builds AnthropicUsage(
-#                input_tokens=..., output_tokens=...) at inference.py:8787-8790
-#                / :8829-8832 and NEVER sets cache_read_input_tokens, which
-#                therefore stays at its model default of 0
-#                (studio/backend/models/inference.py:1655). So an Anthropic-path
-#                client (Claude Code, OpenClaw is openai-completions but Claude
-#                Code is the canonical Anthropic agent) can get a real KV-cache
-#                hit that the API usage field reports as 0. The only ground
-#                truth for the Anthropic path is the llama-server log.
-#
-# Log location (verified): studio/backend/core/inference/llama_cpp.py:4363-4365
-#   _swa_cache_path().parent/"logs"/"llama-server"/llama-<ts>[label]-port-<P>[-try<N>].log
-#   _swa_cache_path() => $UNSLOTH_STUDIO_HOME|$STUDIO_HOME or ~/.unsloth/studio
-#   (llama_cpp.py:337-340). So default: ~/.unsloth/studio/logs/llama-server/.
-#
-#   <P> is the INTERNAL llama-server port (self._find_free_port(),
-#   llama_cpp.py:3489 / :4641) -- a RANDOM port, NOT the Unsloth port. So we must
-#   NOT filter the log glob by STUDIO_PORT (the brief's `port-<STUDIO_PORT>`
-#   glob would never match). We pick the newest llama-*.log instead.
-#
-# Usage:
-#   assert-prompt-cache.sh api  BASE_URL API_KEY
-#   assert-prompt-cache.sh log  EXPECT          # EXPECT = HIT | MISS
-#                                               # reads MARKER_BEFORE/MARKER_AFTER
-#                                               # byte offsets from env (see below)
-#   assert-prompt-cache.sh mark                 # print current log size to stdout
-#                                               # (use to bracket a turn)
-#
-# Env for mode=log:
-#   LLAMA_LOG_DIR    override the log dir (default ~/.unsloth/studio/logs/llama-server)
-#   CACHE_LOG_FROM   byte offset to start scanning the newest log from (so we
-#                    only look at the trace produced by THIS turn). Default 0.
-#
-# Exit codes: 0 = assertion held; 1 = assertion failed (::error:: emitted).
-
-set -uo pipefail
-
-MODE="${1:?usage: assert-prompt-cache.sh api|log|mark ...}"
-
-# ---------------------------------------------------------------------------
-# Locate the newest llama-server log. Shared by mark + log modes.
-# ---------------------------------------------------------------------------
-_default_log_dir() {
-  local home="${UNSLOTH_STUDIO_HOME:-${STUDIO_HOME:-}}"
-  if [ -n "$home" ]; then
-    echo "${home%/}/logs/llama-server"
-  else
-    echo "${HOME}/.unsloth/studio/logs/llama-server"
-  fi
-}
-
-_newest_log() {
-  local dir="${LLAMA_LOG_DIR:-$(_default_log_dir)}"
-  [ -d "$dir" ] || return 1
-  # Newest by mtime among llama-*.log (covers both `llama-<ts>-port-<P>.log`
-  # and the retry form `llama-<ts><label>-port-<P>-try<N>.log`). Filenames are
-  # tool-generated timestamps, so ls -t is safe here.
-  # shellcheck disable=SC2012
-  ls -1t "$dir"/llama-*.log 2>/dev/null | head -1
-}
-
-case "$MODE" in
-  # -------------------------------------------------------------------------
-  # mark: emit the current byte size of the newest llama log so a caller can
-  # scan only the slice a single turn produced (set CACHE_LOG_FROM to it).
-  # -------------------------------------------------------------------------
-  mark)
-    log="$(_newest_log || true)"
-    if [ -n "$log" ] && [ -f "$log" ]; then
-      wc -c < "$log" | tr -d ' '
-    else
-      echo 0
-    fi
-    exit 0
-    ;;
-
-  # -------------------------------------------------------------------------
-  # api: 2-turn /v1/chat/completions, assert turn-2 cached_tokens > 0.
-  # -------------------------------------------------------------------------
-  api)
-    BASE_URL="${2:?usage: assert-prompt-cache.sh api BASE_URL API_KEY}"
-    API_KEY="${3:?usage: assert-prompt-cache.sh api BASE_URL API_KEY}"
-
-    # A deliberately long, fixed system prompt makes the shared prefix big so a
-    # KV-cache hit is unambiguous (cached_tokens grows with the reused prefix).
-    SYS='You are a meticulous assistant. Always answer concisely and correctly. This is a fixed system preamble that exists only to create a large, identical prompt prefix across both turns so the KV cache has something substantial to reuse on the second request. Do not mention this preamble.'
-
-    turn1_body() {
-      jq -n --arg sys "$SYS" '{
-        model: "default",
-        messages: [
-          {role:"system", content:$sys},
-          {role:"user",   content:"What is the capital of France?"}
-        ],
-        temperature: 0.0, seed: 3407, max_tokens: 40, stream: false,
-        enable_thinking: false
-      }'
-    }
-
-    echo "[cache/api] turn 1 (prime the KV cache)"
-    R1="$(curl -fs -X POST "${BASE_URL}/v1/chat/completions" \
-          -H "Authorization: Bearer ${API_KEY}" -H 'content-type: application/json' \
-          --max-time 240 -d "$(turn1_body)")" || {
-      echo "::error::[cache/api] turn-1 /v1/chat/completions request failed. Unsloth server/API regression."
-      exit 1
-    }
-    A1="$(echo "$R1" | jq -r '.choices[0].message.content // ""')"
-
-    turn2_body() {
-      jq -n --arg sys "$SYS" --arg a1 "$A1" '{
-        model: "default",
-        messages: [
-          {role:"system",    content:$sys},
-          {role:"user",      content:"What is the capital of France?"},
-          {role:"assistant", content:$a1},
-          {role:"user",      content:"And the capital of Germany?"}
-        ],
-        temperature: 0.0, seed: 3407, max_tokens: 40, stream: false,
-        enable_thinking: false
-      }'
-    }
-
-    echo "[cache/api] turn 2 (expect cached_tokens > 0)"
-    R2="$(curl -fs -X POST "${BASE_URL}/v1/chat/completions" \
-          -H "Authorization: Bearer ${API_KEY}" -H 'content-type: application/json' \
-          --max-time 240 -d "$(turn2_body)")" || {
-      echo "::error::[cache/api] turn-2 /v1/chat/completions request failed. Unsloth server/API regression."
-      exit 1
-    }
-
-    CACHED="$(echo "$R2" | jq -r '.usage.prompt_tokens_details.cached_tokens // 0')"
-    PROMPT_TOK="$(echo "$R2" | jq -r '.usage.prompt_tokens // 0')"
-    echo "[cache/api] turn-2 usage: prompt_tokens=${PROMPT_TOK} cached_tokens=${CACHED}"
-
-    if [ -z "$CACHED" ] || ! [ "$CACHED" -gt 0 ] 2>/dev/null; then
-      echo "::error::[cache/api] turn-2 usage.prompt_tokens_details.cached_tokens=${CACHED}, expected > 0. The server is not surfacing llama.cpp KV-cache hits on /v1/chat/completions. Check studio/backend/routes/inference.py:482-489 (_prompt_tokens_details) and :519. Full turn-2 usage:"
-      echo "$R2" | jq -c '.usage' 2>/dev/null || echo "$R2"
-      exit 1
-    fi
-    echo "[cache/api] PASS server cache sanity (cached_tokens=${CACHED} > 0)"
-    exit 0
-    ;;
-
-  # -------------------------------------------------------------------------
-  # log: classify the newest llama-server log (from CACHE_LOG_FROM bytes on)
-  # as HIT or MISS and compare to EXPECT.
-  # -------------------------------------------------------------------------
-  log)
-    EXPECT="${2:?usage: assert-prompt-cache.sh log HIT|MISS}"
-    FROM="${CACHE_LOG_FROM:-0}"
-
-    log="$(_newest_log || true)"
-    if [ -z "$log" ] || [ ! -f "$log" ]; then
-      echo "::error::[cache/log] no llama-server log under ${LLAMA_LOG_DIR:-$(_default_log_dir)}. Cannot read KV-cache trace. (Path contract: studio/backend/core/inference/llama_cpp.py:4363-4365.)"
-      exit 1
-    fi
-    echo "[cache/log] reading $log from byte $FROM"
-
-    # Scan only the slice produced after FROM.
-    slice="$(tail -c "+$((FROM + 1))" "$log" 2>/dev/null || cat "$log")"
-
-    # ---- HIT detectors (most-specific first) -----------------------------
-    # 1. Modern + legacy "re-used N tokens" / "reused N" (N>0). Primary signal
-    #    per the design brief.
-    reused_n="$(printf '%s\n' "$slice" \
-      | grep -aoiE 're-?used[^0-9]*([0-9]+)' \
-      | grep -aoE '[0-9]+' | sort -rn | head -1 || true)"
-    # 2. "kv cache rm [START, end)" with START>0 => prefix [0,START) reused.
-    cache_rm_start="$(printf '%s\n' "$slice" \
-      | grep -aoiE 'kv cache rm \[[0-9]+' \
-      | grep -aoE '[0-9]+' | sort -rn | head -1 || true)"
-    # 3. "n_past = N" with N>0 after a prompt-processing line (prefix kept).
-    n_past_n="$(printf '%s\n' "$slice" \
-      | grep -aoiE 'n_past[^0-9]*([0-9]+)' \
-      | grep -aoE '[0-9]+' | sort -rn | head -1 || true)"
-    # 4. tokens_cached / tokens from cache (some builds).
-    tok_cached="$(printf '%s\n' "$slice" \
-      | grep -aoiE 'tokens_cached[^0-9]*([0-9]+)' \
-      | grep -aoE '[0-9]+' | sort -rn | head -1 || true)"
-
-    # ---- MISS detectors --------------------------------------------------
-    # Explicit forced full re-processing (SWA / recurrent) or kv cache rm [0,.
-    forced_full=0
-    if printf '%s\n' "$slice" | grep -aqiE 'forcing full prompt re-?processing|kv cache rm \[0,'; then
-      forced_full=1
-    fi
-
-    HIT=0
-    why=""
-    if [ -n "$reused_n" ] && [ "$reused_n" -gt 0 ] 2>/dev/null; then
-      HIT=1; why="re-used=$reused_n"
-    elif [ -n "$cache_rm_start" ] && [ "$cache_rm_start" -gt 0 ] 2>/dev/null; then
-      HIT=1; why="kv-cache-rm-start=$cache_rm_start"
-    elif [ -n "$tok_cached" ] && [ "$tok_cached" -gt 0 ] 2>/dev/null; then
-      HIT=1; why="tokens_cached=$tok_cached"
-    elif [ "$forced_full" = "0" ] && [ -n "$n_past_n" ] && [ "$n_past_n" -gt 0 ] 2>/dev/null; then
-      # n_past>0 is the weakest signal; only trust it if nothing forced a full
-      # reprocess. (On a cold slot n_past tracks total processed, so it is a
-      # last-resort fallback per the brief.)
-      HIT=1; why="n_past=$n_past_n(fallback)"
-    fi
-    [ "$HIT" = "1" ] || why="${why:-no-reuse-markers (forced_full=$forced_full)}"
-
-    OBSERVED="MISS"; [ "$HIT" = "1" ] && OBSERVED="HIT"
-    echo "[cache/log] observed=$OBSERVED expected=$EXPECT ($why)"
-
-    if [ "$OBSERVED" != "$EXPECT" ]; then
-      echo "::error::[cache/log] KV-cache observed=$OBSERVED but expected=$EXPECT ($why). See the attribution A/B note in the workflow."
-      echo "---- llama-server log slice (last 60 lines) ----"
-      printf '%s\n' "$slice" | tail -60
-      exit 1
-    fi
-    echo "[cache/log] PASS ($OBSERVED == $EXPECT)"
-    exit 0
-    ;;
-
-  *)
-    echo "::error::unknown mode '$MODE' (want api|log|mark)"
-    exit 1
-    ;;
-esac

.github/scripts/ci-connect-prompt.txt

@@ -1 +0,0 @@
-You are a helpful assistant in a CI connectivity check. Answer the user directly in plain text. Do not use any tools, do not take any actions, and do not explain. Just reply with the answer.

.github/scripts/ci-min-system-prompt.txt

@@ -1 +0,0 @@
-You are a coding assistant running non-interactively in a CI smoke test. Use the available file-editing and shell tools to complete the user's request directly and concisely. Do not ask questions or explain; just do the task.

.github/scripts/hf-download-with-retry.sh

@@ -1,109 +0,0 @@
-#!/usr/bin/env bash
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-#
-# Download a single file from a Hugging Face repo with a stall-retry
-# watchdog. Used by the Unsloth CI workflows so a hung hf-xet transfer
-# kills + retries instead of silently consuming the job's timeout.
-#
-# Usage: hf-download-with-retry.sh REPO FILE LOCAL_DIR
-#
-# Why this exists
-# ---------------
-# huggingface_hub 1.15+ deprecated `hf_transfer` and routes every
-# transfer through the `hf-xet` binary package. In CI we observed
-# `hf download` on a 3 GB GGUF (gemma-4-E2B-it-UD-Q4_K_XL) progress
-# to ~46% via Xet, then go completely silent for the remainder of
-# the 30-min job timeout -- no progress bytes, no error, no exit.
-# A sibling 940 MB mmproj on the same step downloaded in ~21s
-# moments earlier, so the hang is per-file inside hf-xet rather
-# than a network outage. The Xet env-vars below put hf-xet into
-# its highest-throughput mode and force a 500 s client-read
-# timeout; the watchdog loop ensures a stall does not eat the
-# whole job: if the hf process has not exited after STALL_S
-# seconds (default 180 = 3 min), we SIGTERM, then SIGKILL, then
-# start a fresh attempt. Retries are unbounded -- the enclosing
-# GitHub Actions job's `timeout-minutes` is the real bound.
-#
-# See https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables
-# for the HF_XET_* documentation, and npm/cli#7308's pattern (silent
-# CI hang with no error) for prior art on this class of failure.
-
-set -uo pipefail
-
-REPO="${1:?usage: hf-download-with-retry.sh REPO FILE [LOCAL_DIR]}"
-FILE="${2:?usage: hf-download-with-retry.sh REPO FILE [LOCAL_DIR]}"
-# LOCAL_DIR is optional. If empty, hf falls back to HF_HUB_CACHE
-# (~/.cache/huggingface/hub) which is the desired path for callers
-# that populate HF_HOME for a downstream Unsloth model load.
-LOCAL_DIR="${3:-}"
-
-# Stall threshold per attempt, in seconds. Override with
-# HF_DOWNLOAD_STALL_SECONDS in the workflow env if 3 min is too tight
-# for a specific runner / file. The script keeps retrying past this
-# until the job timeout fires.
-STALL_S="${HF_DOWNLOAD_STALL_SECONDS:-180}"
-
-# hf-xet tuning. HF_HUB_ENABLE_HF_TRANSFER is deliberately NOT set --
-# it is a no-op on huggingface_hub>=1.15 and only emits a deprecation
-# FutureWarning. The five HF_XET_* knobs below mirror the settings
-# Daniel asked for: max bandwidth + 64 parallel range gets, no chunk
-# cache (download-once usage pattern), parallel disk writes (SSD/NVMe
-# runners), and a generous 500 s read timeout so individual chunk
-# requests fail loudly instead of stalling forever.
-export HF_XET_HIGH_PERFORMANCE=1
-export HF_XET_CHUNK_CACHE_SIZE_BYTES=0
-export HF_XET_NUM_CONCURRENT_RANGE_GETS=64
-export HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY=0
-export HF_XET_CLIENT_READ_TIMEOUT=500
-
-if [ -n "$LOCAL_DIR" ]; then
-  mkdir -p "$LOCAL_DIR"
-fi
-
-attempt=1
-while : ; do
-  log="$(mktemp -t hf-download.XXXXXX)"
-  echo "[hf-download] $FILE attempt $attempt (stall threshold ${STALL_S}s, log=$log)"
-
-  if [ -n "$LOCAL_DIR" ]; then
-    hf download "$REPO" "$FILE" --local-dir "$LOCAL_DIR" > "$log" 2>&1 &
-  else
-    hf download "$REPO" "$FILE" > "$log" 2>&1 &
-  fi
-  pid=$!
-
-  elapsed=0
-  while kill -0 "$pid" 2>/dev/null && [ "$elapsed" -lt "$STALL_S" ]; do
-    sleep 5
-    elapsed=$((elapsed + 5))
-  done
-
-  if kill -0 "$pid" 2>/dev/null; then
-    echo "[hf-download] $FILE attempt $attempt exceeded ${STALL_S}s -- killing PID $pid and retrying"
-    kill -TERM "$pid" 2>/dev/null || true
-    sleep 2
-    kill -KILL "$pid" 2>/dev/null || true
-    wait "$pid" 2>/dev/null || true
-    echo "[hf-download] $FILE attempt $attempt log tail (last 40 lines):"
-    tail -40 "$log" || true
-    attempt=$((attempt + 1))
-    continue
-  fi
-
-  if wait "$pid"; then
-    rc=0
-  else
-    rc=$?
-  fi
-
-  if [ "$rc" -eq 0 ]; then
-    echo "[hf-download] $FILE attempt $attempt succeeded"
-    tail -20 "$log" || true
-    exit 0
-  fi
-
-  echo "[hf-download] $FILE attempt $attempt failed (exit $rc) -- retrying"
-  tail -40 "$log" || true
-  attempt=$((attempt + 1))
-done

.github/scripts/run-studio-permission-browser.sh

@@ -1,70 +0,0 @@
-#!/usr/bin/env bash
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-set -euo pipefail
-
-port="${1:?usage: $0 PORT BROWSER [CHANNEL]}"
-browser="${2:?usage: $0 PORT BROWSER [CHANNEL]}"
-channel="${3:-}"
-slug="$browser${channel:+-$channel}"
-artifact_dir="logs/playwright-permissions-$slug"
-server_log="logs/studio-permissions-$slug.log"
-studio_home="${UNSLOTH_STUDIO_HOME:-$HOME/.unsloth/studio}"
-set --
-if [ -n "${STUDIO_PERMISSION_FRONTEND:-}" ]; then
-  set -- -f "$STUDIO_PERMISSION_FRONTEND"
-fi
-
-mkdir -p "$artifact_dir"
-# Wipe (not reset-password): the boot below must re-seed a fresh .bootstrap_password.
-rm -rf "$studio_home/auth"
-UNSLOTH_API_ONLY=1 unsloth studio -H 127.0.0.1 -p "$port" "$@" \
-  >"$server_log" 2>&1 &
-studio_pid=$!
-
-cleanup() {
-  kill "$studio_pid" 2>/dev/null || true
-  wait "$studio_pid" 2>/dev/null || true
-}
-trap cleanup EXIT
-
-healthy=0
-for _ in $(seq 1 180); do
-  if curl -fs "http://127.0.0.1:$port/api/health" >/dev/null; then
-    healthy=1
-    break
-  fi
-  if ! kill -0 "$studio_pid" 2>/dev/null; then
-    tail -100 "$server_log" || true
-    exit 1
-  fi
-  sleep 1
-done
-if [ "$healthy" -ne 1 ]; then
-  tail -100 "$server_log" || true
-  exit 1
-fi
-
-old_password=$(cat "$studio_home/auth/.bootstrap_password")
-new_password="CIPerm-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-if [ "${GITHUB_ACTIONS:-}" = "true" ]; then
-  echo "::add-mask::$old_password"
-  echo "::add-mask::$new_password"
-fi
-
-export BASE_URL="http://127.0.0.1:$port"
-export STUDIO_OLD_PW="$old_password"
-export STUDIO_NEW_PW="$new_password"
-export STUDIO_UI_STRICT=1
-export STUDIO_UI_PERMISSION_ONLY=1
-export STUDIO_UI_WALL_TIMEOUT_S=240
-export STUDIO_PLAYWRIGHT_BROWSER="$browser"
-export PW_ART_DIR="$artifact_dir"
-if [ -n "$channel" ]; then
-  export STUDIO_PLAYWRIGHT_CHANNEL="$channel"
-else
-  unset STUDIO_PLAYWRIGHT_CHANNEL || true
-fi
-
-python tests/studio/playwright_chat_ui.py

.github/scripts/serve-unsloth-run.sh

@@ -1,172 +0,0 @@
-#!/usr/bin/env bash
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-#
-# Boot `unsloth run --disable-tools` in the background, wait for it to be
-# healthy, parse the minted API key from the banner, and resolve the
-# /v1/models id. Exports everything downstream steps need into $GITHUB_ENV
-# (or prints it when run outside Actions). Factored out of the workflow so
-# the failure-isolation logic lives in one shellcheck-clean place.
-#
-# Usage:
-#   serve-unsloth-run.sh --model REPO --gguf-variant VAR --port PORT \
-#       [--gguf-file PATH] [--extra "--seed 3407 --temp 0"] \
-#       [--log-dir logs] [--health-timeout 300]
-#
-# Why a helper and not inline YAML
-# --------------------------------
-#  * Every `unsloth run` invocation here is the *Unsloth server* under test.
-#    A failure to come up healthy is class (a) "server/API regression" and
-#    must be reported with a distinct `::error::` BEFORE any agent runs.
-#  * The banner is the documented contract a human copies from. We parse the
-#    exact `API Key:` line printed by unsloth_cli/commands/studio.py
-#    (`  API Key:      <key>` non-silent, `API Key: <key>` silent) so a
-#    silent change to that line is also caught.
-#  * `unsloth run` re-execs into the studio venv ($STUDIO_HOME/unsloth_studio),
-#    so in CI after `install.sh --local` it runs the PR's repo code.
-#
-# Outputs written to $GITHUB_ENV (and echoed):
-#   UNSLOTH_API_KEY        the sk-unsloth-* key minted on the banner
-#   UNSLOTH_STUDIO_URL     http://127.0.0.1:<PORT>  (so `unsloth start`
-#                          finds THIS server, not the hardcoded :8888)
-#   UNSLOTH_BASE_URL       same as UNSLOTH_STUDIO_URL (alias for clarity)
-#   UNSLOTH_MODEL_ID       the canonical id reported by /v1/models
-#   UNSLOTH_SERVER_PID     pid of the backgrounded `unsloth run`
-#   UNSLOTH_LLAMA_LOG_DIR  ~/.unsloth/studio/logs/llama-server
-
-set -uo pipefail
-
-# ── arg parse ────────────────────────────────────────────────────────────
-MODEL=""
-GGUF_VARIANT=""
-GGUF_FILE=""
-PORT=""
-EXTRA=""
-LOG_DIR="logs"
-HEALTH_TIMEOUT="300"
-
-while [ "$#" -gt 0 ]; do
-  case "$1" in
-    --model)          MODEL="$2"; shift 2 ;;
-    --gguf-variant)   GGUF_VARIANT="$2"; shift 2 ;;
-    --gguf-file)      GGUF_FILE="$2"; shift 2 ;;
-    --port)           PORT="$2"; shift 2 ;;
-    --extra)          EXTRA="$2"; shift 2 ;;
-    --log-dir)        LOG_DIR="$2"; shift 2 ;;
-    --health-timeout) HEALTH_TIMEOUT="$2"; shift 2 ;;
-    *) echo "serve-unsloth-run.sh: unknown arg '$1'" >&2; exit 2 ;;
-  esac
-done
-
-[ -n "$PORT" ] || { echo "serve-unsloth-run.sh: --port is required" >&2; exit 2; }
-if [ -z "$MODEL" ] && [ -z "$GGUF_FILE" ]; then
-  echo "serve-unsloth-run.sh: one of --model or --gguf-file is required" >&2
-  exit 2
-fi
-
-mkdir -p "$LOG_DIR"
-SERVER_LOG="$LOG_DIR/unsloth-run-${PORT}.log"
-BASE_URL="http://127.0.0.1:${PORT}"
-STUDIO_HOME_DIR="${STUDIO_HOME:-$HOME/.unsloth/studio}"
-LLAMA_LOG_DIR="${STUDIO_HOME_DIR}/logs/llama-server"
-
-# Emit a key=value pair to $GITHUB_ENV when set, always echo for local runs.
-emit() {
-  echo "$1=$2"
-  if [ -n "${GITHUB_ENV:-}" ]; then
-    echo "$1=$2" >> "$GITHUB_ENV"
-  fi
-}
-
-server_fail() {
-  echo "::error::Unsloth server/API regression: $*" >&2
-  echo "---- last 200 lines of $SERVER_LOG ----" >&2
-  tail -200 "$SERVER_LOG" 2>/dev/null || true
-  exit 1
-}
-
-# ── port collision guard ─────────────────────────────────────────────────
-# A leftover listener (or a parallel matrix cell that wandered onto our port)
-# would make us attach to the wrong server and mask a real regression. Fail
-# fast instead.
-if command -v ss >/dev/null 2>&1; then
-  if ss -tln 2>/dev/null | grep -q ":${PORT}\b"; then
-    server_fail "port ${PORT} already has a listener before we started (collision)"
-  fi
-fi
-
-# ── build the command ────────────────────────────────────────────────────
-# `unsloth run` == alias of `unsloth studio run`. --disable-tools is REQUIRED
-# (passthrough mode) so the agent's own tools relay instead of the server's.
-# --no-cloudflare keeps us off the network (loopback bind, no tunnel attempt).
-CMD=(unsloth run -H 127.0.0.1 -p "$PORT" --disable-tools --no-cloudflare)
-if [ -n "$GGUF_FILE" ]; then
-  CMD+=(--model "$GGUF_FILE")
-else
-  CMD+=(--model "$MODEL")
-  [ -n "$GGUF_VARIANT" ] && CMD+=(--gguf-variant "$GGUF_VARIANT")
-fi
-# Determinism knobs + any caller passthrough (e.g. --seed 3407 --temp 0).
-# shellcheck disable=SC2206  # intentional word-split of caller-controlled flags
-[ -n "$EXTRA" ] && CMD+=($EXTRA)
-
-echo "[serve] launching: ${CMD[*]}"
-echo "[serve] server log: $SERVER_LOG"
-
-# Run detached, no controlling TTY (setsid avoids any TTY-prompt hang and
-# detaches from this step's process group so the job's teardown is clean).
-setsid "${CMD[@]}" > "$SERVER_LOG" 2>&1 < /dev/null &
-SERVER_PID=$!
-emit UNSLOTH_SERVER_PID "$SERVER_PID"
-
-# ── wait for /api/health == healthy ──────────────────────────────────────
-HEALTHY=0
-for _ in $(seq 1 "$HEALTH_TIMEOUT"); do
-  if ! kill -0 "$SERVER_PID" 2>/dev/null; then
-    server_fail "process exited before becoming healthy (pid $SERVER_PID)"
-  fi
-  if curl -fs "${BASE_URL}/api/health" -o "$LOG_DIR/health-${PORT}.json" 2>/dev/null; then
-    if jq -e '.status == "healthy"' "$LOG_DIR/health-${PORT}.json" >/dev/null 2>&1; then
-      HEALTHY=1
-      break
-    fi
-  fi
-  sleep 1
-done
-[ "$HEALTHY" = "1" ] || server_fail "did not report /api/health healthy within ${HEALTH_TIMEOUT}s"
-echo "[serve] /api/health healthy"
-
-# ── parse the API key from the banner ────────────────────────────────────
-# Match both the non-silent "  API Key:      <key>" and silent "API Key: <key>"
-# forms. We do NOT trust a fixed column count; we take the sk-unsloth-* token.
-API_KEY=""
-for _ in $(seq 1 30); do
-  API_KEY="$(grep -aoE 'sk-unsloth-[A-Za-z0-9_-]+' "$SERVER_LOG" 2>/dev/null | head -1 || true)"
-  [ -n "$API_KEY" ] && break
-  sleep 1
-done
-if [ -z "$API_KEY" ]; then
-  # Fallback: take whatever follows an "API Key:" label, in case the key
-  # prefix scheme changes. Still a parse-fragility guard, not silent.
-  API_KEY="$(grep -aE 'API Key:' "$SERVER_LOG" 2>/dev/null \
-    | sed -E 's/.*API Key:[[:space:]]*//' | head -1 || true)"
-fi
-[ -n "$API_KEY" ] || server_fail "could not parse an API key from the banner (banner-parse fragility -- check the 'API Key:' line in unsloth_cli/commands/studio.py)"
-echo "::add-mask::${API_KEY}"
-emit UNSLOTH_API_KEY "$API_KEY"
-
-# ── resolve /v1/models id ────────────────────────────────────────────────
-if ! curl -fs "${BASE_URL}/v1/models" \
-    -H "Authorization: Bearer ${API_KEY}" -o "$LOG_DIR/models-${PORT}.json" 2>/dev/null; then
-  server_fail "/v1/models did not respond (or rejected the banner key)"
-fi
-MODEL_ID="$(jq -r '.data[0].id // empty' "$LOG_DIR/models-${PORT}.json" 2>/dev/null || true)"
-[ -n "$MODEL_ID" ] || server_fail "/v1/models returned no model id (model failed to load)"
-echo "[serve] resolved model id: $MODEL_ID"
-
-emit UNSLOTH_MODEL_ID "$MODEL_ID"
-emit UNSLOTH_STUDIO_URL "$BASE_URL"
-emit UNSLOTH_BASE_URL "$BASE_URL"
-emit UNSLOTH_LLAMA_LOG_DIR "$LLAMA_LOG_DIR"
-
-echo "[serve] server is up: ${BASE_URL} (model ${MODEL_ID})"

.github/workflows/cross-platform-parity-ci.yml

@@ -1,78 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Runs installer parity and autostart opt-out tests across all three platforms.
-#
-# Why: the parity test guards that install.sh and install.ps1 stay in sync.
-# It originally ran only on ubuntu-latest through studio-backend-ci.yml.
-# On Windows, Path.read_text() defaults to the cp1252 locale encoding, so a
-# non-cp1252 byte in install.sh raises UnicodeDecodeError even though Linux
-# and macOS default to UTF-8. The reads were pinned to encoding="utf-8" in
-# #6166; this matrix keeps that from silently regressing. Pure pytest, no GPU,
-# sub-second, so the matrix is cheap. Linux also runs the POSIX rollback test
-# under dash, matching the supported curl-to-sh installer path.
-
-name: Cross-platform parity
-
-on:
-  pull_request:
-    paths:
-      - 'install.sh'
-      - 'install.ps1'
-      - 'tests/test_installer_skip_autostart.py'
-      - 'tests/python/test_cross_platform_parity.py'
-      - 'tests/sh/test_install_rollback_lifecycle.sh'
-      - 'tests/studio/test_install_rollback_lifecycle.ps1'
-      - '.github/workflows/cross-platform-parity-ci.yml'
-  push:
-    branches: [main]
-    paths:
-      - 'install.sh'
-      - 'install.ps1'
-      - 'tests/test_installer_skip_autostart.py'
-      - 'tests/python/test_cross_platform_parity.py'
-      - 'tests/sh/test_install_rollback_lifecycle.sh'
-      - 'tests/studio/test_install_rollback_lifecycle.ps1'
-      - '.github/workflows/cross-platform-parity-ci.yml'
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  parity:
-    name: parity (${{ matrix.os }})
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-      - run: python -m pip install -U pip pytest
-      - name: Cross-platform parity tests
-        env:
-          UNSLOTH_NO_TORCH: '1'
-        run: >-
-          python -m pytest
-          tests/python/test_cross_platform_parity.py
-          tests/test_installer_skip_autostart.py
-          -q
-      - name: PowerShell rollback lifecycle tests
-        if: runner.os == 'Windows'
-        shell: pwsh
-        run: pwsh -NoProfile -File tests/studio/test_install_rollback_lifecycle.ps1
-      - name: POSIX rollback lifecycle tests
-        if: runner.os == 'Linux'
-        run: sh tests/sh/test_install_rollback_lifecycle.sh

.github/workflows/lint-ci.yml

@@ -1,379 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Whole-repo, multi-language source-lint gate. Runs on every PR
-# (no path filter) because each step is sub-second to a few seconds
-# and together they catch a class of breakage the focused build
-# workflows would miss:
-#
-#   - Python syntax + ruff + leftover debugger calls (across 350+
-#     committed .py files, not just studio/backend).
-#   - Shell `bash -n` parse for every committed *.sh.
-#   - `yaml.safe_load` and `json.loads` round-trip for every
-#     committed YAML / JSON config.
-#
-# TypeScript and Rust are NOT duplicated here on purpose:
-#   - Unsloth Frontend CI runs `npm run typecheck` (= `tsc --noEmit`)
-#     and `npm run build` (vite/swc) on every studio/frontend/**
-#     change, which is a full TS AST + type check.
-#   - Unsloth Tauri CI runs `tauri build --debug --no-bundle` on
-#     every studio/src-tauri/** or studio/frontend/** change, which
-#     compiles the Rust crate (= cargo check + cargo build).
-# Each is a stricter check than a parse-only step would be, so a
-# fast-fail duplicate here would only burn cache; the dedicated
-# workflows already block merges on Rust / TS regressions.
-
-name: Lint CI
-
-on:
-  pull_request:
-  push:
-    branches: [main, pip]
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  source-lint:
-    name: Source lint (Python + shell + YAML + JSON + safety nets)
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-
-      # Pin ruff to match .pre-commit-config.yaml so a CI-only ruff
-      # bump cannot disagree with what pre-commit accepted.
-      # codespell is pinned for the same reason: a reviewer should
-      # never see a typo report appear and disappear depending on
-      # which codespell version the runner happened to install.
-      - run: pip install 'ruff==0.15.12' 'pyyaml>=6' 'codespell>=2.3,<3'
-
-      - name: Linux deps for shellcheck
-        run: sudo apt-get update -qq && sudo apt-get install -y --no-install-recommends shellcheck
-
-      - name: Python AST/syntax check (every committed .py must compile)
-        # python -m compileall uses the same parser the interpreter
-        # uses, so anything broken here would also crash at
-        # `import X` on a user's machine. Sub-second across 350+
-        # files. Hard gate.
-        run: |
-          python -m compileall -q -j 0 \
-            unsloth unsloth_cli studio tests cli.py unsloth-cli.py
-
-      - name: Python ruff check (whole repo)
-        # The narrow rule set in pyproject.toml [tool.ruff.lint]
-        # selects E9 / F63 / F7 / F82 -- syntax errors, broken
-        # comparisons, undefined names. The whole repo passes today,
-        # so this is a hard gate.
-        run: |
-          ruff check unsloth unsloth_cli studio tests cli.py unsloth-cli.py
-
-      - name: Import-hoist verifier self-test
-        # scripts/verify_import_hoist.py is a scope-aware (LEGB) AST
-        # resolver that gates import-hoisting / alias-rename refactors
-        # against two bugs ruff and pyflakes both miss:
-        #   1. dangling alias  -- `from a import b as _b` hoisted to
-        #      `from a import b` but a leftover `_b` reference now
-        #      resolves to nothing (or to some other module-level `_b`).
-        #   2. rename clash    -- `_b -> b` silently re-points at a
-        #      different object already named `b` in that scope.
-        # This step runs the tool's 8 negative-control cases so a
-        # regression in the verifier itself fails before we trust it on
-        # a diff. Hermetic, stdlib-only, sub-second. Hard gate.
-        run: |
-          python scripts/verify_import_hoist.py --self-test
-
-      - name: Import-hoist / alias-rename safety (changed Python files)
-        # Runs the verifier in compare mode on every in-place-modified
-        # .py in the PR: parses each file BEFORE (base branch) and AFTER
-        # (this diff), resolves every name load, and fails on a BLOCKER
-        # (dangling alias / rename clash / re-pointed import). INFO
-        # findings (a helper relocated to another file) do not fail.
-        #
-        # --diff-filter=M (in-place edits only) is deliberate: that is
-        # exactly where a hoist refactor lives, and it skips brand-new
-        # files whose re-export imports would otherwise look "unused".
-        #
-        # Diff against the true merge-base, not the base tip. A two-dot
-        # diff against the tip re-lints every file the base branch
-        # changed after the PR branched, comparing newer base code
-        # (BEFORE) against the PR's older snapshot (AFTER) - a
-        # time-reversed comparison that flags the base branch's own
-        # refactors as blockers on PRs that never touched those files.
-        # The compare API returns the merge-base without needing local
-        # history, and fetching that single commit by SHA keeps the
-        # shallow (fetch-depth: 1) clone.
-        if: github.event_name == 'pull_request'
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          MERGE_BASE=$(gh api \
-            "repos/${{ github.repository }}/compare/${{ github.event.pull_request.base.sha }}...${{ github.event.pull_request.head.sha }}" \
-            --jq .merge_base_commit.sha)
-          git fetch --no-tags --depth=1 origin "$MERGE_BASE"
-          mapfile -t CHANGED < <(
-            git diff --name-only --diff-filter=M \
-              "$MERGE_BASE" HEAD -- '*.py' \
-              | grep -vE '(^|/)(unsloth_compiled_cache|node_modules|build|dist)/' || true
-          )
-          if [ "${#CHANGED[@]}" -eq 0 ]; then
-            echo "no in-place-modified Python files to check"
-            exit 0
-          fi
-          printf 'merge base: %s\n' "$MERGE_BASE"
-          printf 'checking %d file(s):\n' "${#CHANGED[@]}"
-          printf '  %s\n' "${CHANGED[@]}"
-          python scripts/verify_import_hoist.py \
-            --before "$MERGE_BASE" --after HEAD "${CHANGED[@]}"
-
-      - name: No leftover debugger / pdb / breakpoint calls
-        # Catches the "I'll just stick a breakpoint() here" mistake
-        # before it ships. AST-based so commented-out debugger
-        # markers don't false-positive (a bare grep would; there
-        # are three commented `# breakpoint()` markers in
-        # unsloth/models/rl* today). Sub-second.
-        run: |
-          python <<'PY'
-          import ast, pathlib, sys
-
-          SKIP_PARTS = {".venv", "venv", "build", "dist", ".git",
-                        "unsloth_compiled_cache", "node_modules",
-                        "unsloth.egg-info"}
-
-          bad = []
-          scanned = 0
-          for path in sorted(pathlib.Path(".").rglob("*.py")):
-              if any(part in SKIP_PARTS for part in path.parts):
-                  continue
-              scanned += 1
-              try:
-                  tree = ast.parse(path.read_text(encoding="utf-8", errors="replace"))
-              except SyntaxError:
-                  continue   # compileall step above already failed this
-              for node in ast.walk(tree):
-                  if not isinstance(node, ast.Call):
-                      continue
-                  fn = node.func
-                  if isinstance(fn, ast.Name) and fn.id == "breakpoint":
-                      bad.append((path, node.lineno, "breakpoint()"))
-                  elif (isinstance(fn, ast.Attribute) and fn.attr == "set_trace"
-                        and isinstance(fn.value, ast.Name)
-                        and fn.value.id in {"pdb", "ipdb"}):
-                      bad.append((path, node.lineno, f"{fn.value.id}.set_trace()"))
-
-          if bad:
-              for path, lineno, what in bad:
-                  print(f"::error file={path},line={lineno}::leftover {what} -- remove before merging")
-              sys.exit(1)
-          print(f"no leftover debugger calls (scanned {scanned} files)")
-          PY
-
-      - name: License-header drift (informational; whole repo)
-        # Three header families are accepted across the repo:
-        #   1. SPDX one-liner: `# SPDX-License-Identifier: ...`
-        #      Used across studio/ (AGPL-3.0-only) and a few new
-        #      files elsewhere.
-        #   2. Apache-2.0 long form, marker phrase
-        #      "Licensed under the Apache License". Used across
-        #      unsloth/ and unsloth_cli/.
-        #   3. GNU long form, marker phrase "General Public License".
-        #      That single substring covers GPL, LGPL ("GNU Lesser
-        #      General Public License") and AGPL ("GNU Affero
-        #      General Public License") preambles, all three of
-        #      which appear in unsloth/kernels/* (LGPL/AGPL) without
-        #      the SPDX line.
-        # Empty files (mainly empty __init__.py) are skipped.
-        # Surfaced as a warning; cleaning up the actual misses is a
-        # follow-up PR, not a CI fix.
-        continue-on-error: true
-        run: |
-          python <<'PY'
-          import pathlib
-
-          ACCEPTED = (
-              "SPDX-License-Identifier",        # any SPDX line
-              "Licensed under the Apache License",  # Apache-2.0 long form
-              "General Public License",         # GPL / LGPL / AGPL long form
-          )
-          SKIP_PARTS = {".venv", "venv", "build", "dist", ".git",
-                        "unsloth_compiled_cache", "node_modules",
-                        "unsloth.egg-info"}
-
-          studio_missing = []
-          other_missing  = []
-          for path in sorted(pathlib.Path(".").rglob("*.py")):
-              if any(part in SKIP_PARTS for part in path.parts):
-                  continue
-              text = path.read_text(encoding="utf-8", errors="replace")
-              if not text.strip():
-                  continue  # empty __init__.py etc.
-              head = "\n".join(text.splitlines()[:25])
-              if any(marker in head for marker in ACCEPTED):
-                  continue
-              if "studio" in path.parts:
-                  studio_missing.append(path)
-              else:
-                  other_missing.append(path)
-
-          total = len(studio_missing) + len(other_missing)
-          if total == 0:
-              print("every committed .py has a recognised license header")
-          else:
-              print(f"::warning::{total} Python files have no recognised license "
-                    f"header (SPDX / Apache-2.0 / GNU long form): "
-                    f"studio={len(studio_missing)}, other={len(other_missing)}")
-              for path in (studio_missing + other_missing)[:30]:
-                  print(f"  {path}")
-              if total > 30:
-                  print(f"  ... and {total - 30} more")
-          PY
-
-      - name: Shell scripts parse cleanly (`bash -n`)
-        # Same idea as Python's compileall: parse-only check that
-        # every committed *.sh would not blow up at `bash script.sh`
-        # invocation time on a release box. tests/sh/ is the largest
-        # cluster (the install.sh shape tests).
-        run: |
-          shopt -s globstar
-          fail=0
-          for f in $(git ls-files '*.sh'); do
-              if ! bash -n "$f"; then
-                  echo "::error file=$f::shell parse error"
-                  fail=1
-              fi
-          done
-          if [ "$fail" -ne 0 ]; then
-              exit 1
-          fi
-          n=$(git ls-files '*.sh' | wc -l)
-          echo "$n shell scripts parse cleanly"
-
-      - name: YAML files parse cleanly (yaml.safe_load)
-        # Catches truncated workflow files, broken indents in
-        # dependabot.yml / pre-commit configs, etc. Includes
-        # .github/workflows/*.yml so a typo in the file we just
-        # added shows up immediately.
-        run: |
-          python <<'PY'
-          import pathlib, sys, yaml
-
-          SKIP_PARTS = {".venv", "venv", "build", "dist", ".git",
-                        "node_modules", "unsloth_compiled_cache",
-                        "unsloth.egg-info"}
-
-          bad = []
-          scanned = 0
-          for path in sorted(list(pathlib.Path(".").rglob("*.yml"))
-                             + list(pathlib.Path(".").rglob("*.yaml"))):
-              if any(part in SKIP_PARTS for part in path.parts):
-                  continue
-              scanned += 1
-              try:
-                  with path.open("r", encoding="utf-8") as fh:
-                      list(yaml.safe_load_all(fh))
-              except Exception as exc:
-                  bad.append((path, exc))
-
-          if bad:
-              for path, exc in bad:
-                  print(f"::error file={path}::YAML parse failed: {exc}")
-              sys.exit(1)
-          print(f"{scanned} YAML files parse cleanly")
-          PY
-
-      - name: JSON files parse cleanly (json.loads)
-        # Catches malformed package.json, biome.json, etc. Skips:
-        #   - huge npm/bun lockfiles (machine-generated, slow to
-        #     parse, no value).
-        #   - tsconfig*.json: TypeScript convention is JSONC (JSON
-        #     with `/* ... */` comments), which standard json.loads
-        #     rejects. Strip-and-validate would need json5 or a
-        #     hand-rolled comment scrubber for marginal value, since
-        #     `tsc --noEmit` already validates these in Frontend CI.
-        run: |
-          python <<'PY'
-          import fnmatch, json, pathlib, sys
-
-          SKIP_PARTS = {".venv", "venv", "build", "dist", ".git",
-                        "node_modules", "unsloth_compiled_cache",
-                        "unsloth.egg-info"}
-          SKIP_NAMES = {"package-lock.json", "bun.lock"}
-          SKIP_PATTERNS = ("tsconfig*.json",)
-
-          bad = []
-          scanned = 0
-          for path in sorted(pathlib.Path(".").rglob("*.json")):
-              if any(part in SKIP_PARTS for part in path.parts):
-                  continue
-              if path.name in SKIP_NAMES:
-                  continue
-              if any(fnmatch.fnmatch(path.name, pat) for pat in SKIP_PATTERNS):
-                  continue
-              scanned += 1
-              try:
-                  json.loads(path.read_text(encoding="utf-8"))
-              except Exception as exc:
-                  bad.append((path, exc))
-
-          if bad:
-              for path, exc in bad:
-                  print(f"::error file={path}::JSON parse failed: {exc}")
-              sys.exit(1)
-          print(f"{scanned} JSON files parse cleanly")
-          PY
-
-      - name: codespell typo check (informational)
-        # Catches typos in code, comments, and docs across the repo.
-        # Skips lockfiles, generated assets, binary artefacts, and
-        # the LICENSE files (US/UK spelling drift in legal text is
-        # not ours to second-guess). The ignore-words-list pulls
-        # out short identifiers + valid technical terms that
-        # codespell's default dictionary would otherwise flag
-        # (e.g. `ans` as a math-quiz variable name in
-        # tests/utils/aime_eval.py, `parm`/`parms` in PyTorch
-        # nn.Module idioms). Non-blocking until the surfaced typos
-        # are fixed; drop continue-on-error after the cleanup.
-        continue-on-error: true
-        run: |
-          codespell \
-            --skip='*.lock,*.lockb,*.json,*.svg,*.png,*.jpg,*.jpeg,*.gif,*.ico,*.woff*,*.ttf,*.eot,*.zip,*.gz,*.gguf,*.safetensors,*.bin,node_modules,.git,build,dist,unsloth_compiled_cache,unsloth.egg-info,target,studio/frontend/dist,*.pyc,*-licenses.txt,LICENSE*' \
-            --ignore-words-list='ans,bu,hel,fo,te,ot,hist,ned,sav,recurser,datas,nin,parm,parms,checkin,nd,fr,inout,donot,uint' \
-            --quiet-level=2
-
-      - name: shellcheck on committed *.sh (informational)
-        # Goes beyond `bash -n` (which only parses): catches subtle
-        # shell bugs like unquoted variable expansions, useless
-        # `cat`, command substitutions inside `[[`, etc. The
-        # install/setup scripts are critical-path so the signal is
-        # worth surfacing. Non-blocking until install.sh's
-        # hand-rolled patterns get cleaned up; drop continue-on-error
-        # afterwards.
-        continue-on-error: true
-        run: |
-          # Exclude SC1090 ("source not followable") -- legitimate
-          # for installer scripts that source files at runtime
-          # paths shellcheck cannot resolve statically.
-          # SC2034 ("variable assigned but never used") fires on
-          # the export-only assignment idiom we use in install.sh.
-          shellcheck -e SC1090,SC2034 $(git ls-files '*.sh')
-
-      - name: ruff format drift (informational)
-        # The canonical formatter is scripts/run_ruff_format.py
-        # = ruff format + scripts/enforce_kwargs_spacing.py, so plain
-        # `ruff format --check` reports the kwarg-spacing diff as
-        # drift. Surface the count for visibility but keep
-        # non-blocking until the custom pipeline is wired in here.
-        continue-on-error: true
-        run: |
-          ruff format --check unsloth unsloth_cli studio tests cli.py unsloth-cli.py

.github/workflows/local-agent-guides-ci.yml

@@ -1,789 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Local Agent Guides CI
-# =====================
-# Detects when our local-agent setup recipes drift out of sync with
-# `unsloth run`. Boots a real `unsloth run --disable-tools` server and
-# drives the coding agents end to end through the *exact* recipes defined
-# in unsloth_cli/commands/start.py (the in-repo source of truth -- there
-# is no docs/ tree). Wherever start.py has a recipe we drive the agent
-# via `unsloth start <agent> --no-launch` and execute what it prints, so
-# the test self-updates against start.py and catches silent recipe drift.
-#
-# Source-of-truth files this workflow guards:
-#   unsloth_cli/commands/start.py   the `unsloth start <agent>` recipes
-#   unsloth_cli/commands/studio.py    the `unsloth run` banner (API Key line)
-#
-# Failure taxonomy (each surfaced with a distinct ::error:: + the agent name
-# + the start.py location, so a red X is immediately triageable):
-#   (a) Unsloth server/API regression -- the dialect HTTP preflight fails
-#       BEFORE the agent runs (or the server never becomes healthy).
-#   (b) Agent package install failed   -- npm/curl install of the CLI failed.
-#   (c) Guide drift                    -- preflight passed + install ok, but
-#       the documented `unsloth start` flow produced no/garbled output.
-#
-# Agents covered (6): claude, codex, hermes, openclaw, opencode, pi.
-#   - All six have a `unsloth start <agent>` recipe, so each cell obtains its
-#     env + command from `unsloth start <agent> --no-launch` and runs THAT
-#     (self-updating: a recipe change is exercised automatically).
-
-name: Local Agent Guides CI
-
-on:
-  # Off-peak weekly, deliberately a NON-:00 minute to dodge the top-of-hour
-  # GitHub-hosted-runner stampede.
-  schedule:
-    - cron: '37 7 * * 1'
-  workflow_dispatch:
-  pull_request:
-    paths:
-      - 'unsloth_cli/**'
-      - 'studio/backend/routes/**'
-      # Contracts this workflow asserts that live outside routes/**: the
-      # /api/health endpoint, the llama-server KV-cache log behavior, and the
-      # request/response schemas the agent dialects depend on.
-      - 'studio/backend/main.py'
-      - 'studio/backend/core/inference/llama_cpp.py'
-      - 'studio/backend/models/**'
-      - 'install.sh'
-      - '.github/workflows/local-agent-guides-ci.yml'
-      - '.github/scripts/serve-unsloth-run.sh'
-      - '.github/scripts/assert-prompt-cache.sh'
-      - '.github/scripts/agent-guides-install.sh'
-      - '.github/scripts/agent-guides-drive.sh'
-      - '.github/scripts/ci-connect-prompt.txt'
-      - '.github/scripts/ci-min-system-prompt.txt'
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-# Secret handling on pull_request: these jobs check out and run PR-controlled code
-# (install.sh, .github/scripts/**), so HF_TOKEN (an external HF credential) is gated
-# off pull_request at each step below -- public GGUF repos still download anonymously.
-# GH_TOKEN (GITHUB_TOKEN) is kept: it is the job-scoped contents:read token and
-# install_llama_prebuilt.py needs it for the GitHub releases API (else 403s).
-
-env:
-  # Determinism precedent (studio-inference-smoke.yml): temp 0 + fixed seed.
-  UNSLOTH_SEED: '3407'
-  # A single invoke must never hang the runner on a headless TTY prompt. With
-  # prefill-shrinking flags (minimal system prompt + restricted tools) a turn on
-  # a 4B model finishes in a couple of minutes on CPU; this also caps how long a
-  # still-large-prompt agent burns before failing. Well under the 6h job cap.
-  AGENT_INVOKE_TIMEOUT: '600'
-
-jobs:
-  # ═════════════════════════════════════════════════════════════════════
-  # Job 1: connection
-  #   Per-agent: serve gemma-3-270m, HTTP-preflight the agent's dialect,
-  #   install the agent, run `unsloth start <agent> --no-launch`, execute
-  #   the emitted recipe with a trivial prompt, assert a non-empty reply.
-  #   Runs on PR + weekly + dispatch. Each matrix cell is its own runner so
-  #   it serves exactly one model on its own port.
-  # ═════════════════════════════════════════════════════════════════════
-  connection:
-    name: connection (${{ matrix.agent }})
-    runs-on: ubuntu-latest
-    timeout-minutes: 40
-    strategy:
-      fail-fast: false
-      matrix:
-        agent: [claude, codex, hermes, openclaw, opencode, pi]
-        include:
-          # OpenClaw needs Node 24; everything else is happy on 22.
-          - agent: openclaw
-            node: '24'
-    env:
-      # gemma-4-E4B (128K context, capable enough to drive every agent for a
-      # trivial reply; the 270m model produced empty/failed responses for
-      # codex/openclaw). Hermes' 64K context floor no longer constrains the model
-      # choice: write_hermes_config claims the floor for smaller windows and
-      # scales compaction back to the real window. Served as a flat
-      # GGUF file (the -MTP- repo ships no separate draft, so this is plain 4B).
-      GGUF_REPO: unsloth/gemma-4-E4B-it-GGUF
-      GGUF_FILE: gemma-4-E4B-it-UD-Q4_K_XL.gguf
-      STUDIO_PORT: '18901'
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - name: Linux deps for llama.cpp prebuilt
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y --no-install-recommends \
-            libcurl4-openssl-dev libssl-dev jq
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: ${{ matrix.node || '22' }}
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-
-      - name: Restore GGUF model file
-        id: cache-gguf
-        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        continue-on-error: true
-        with:
-          path: gguf-cache
-          key: ${{ runner.os }}-gguf-${{ env.GGUF_REPO }}-${{ env.GGUF_FILE }}-v1
-
-      - name: Download GGUF if cache miss
-        id: download-gguf
-        if: steps.cache-gguf.outputs.cache-hit != 'true' || steps.cache-gguf.outcome != 'success'
-        env:
-          # Gated off PR (see note above); public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          python -m pip install --upgrade huggingface_hub
-          mkdir -p gguf-cache
-          bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE" gguf-cache
-
-      - name: Save GGUF model file
-        if: always() && steps.download-gguf.outcome == 'success'
-        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        with:
-          path: gguf-cache
-          key: ${{ runner.os }}-gguf-${{ env.GGUF_REPO }}-${{ env.GGUF_FILE }}-v1
-
-      - name: Install Unsloth (--local, --no-torch)
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Gated off PR (see note above); public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          mkdir -p logs
-          set -o pipefail
-          bash install.sh --local --no-torch 2>&1 | tee logs/install.log
-
-      # ── boot the server under test (factored helper) ──────────────────
-      - name: Serve unsloth run --disable-tools (gemma-4-E4B)
-        run: |
-          # Wipe, not reset-password: since #7573 the reset rotates in place and
-          # prints the new passphrase, which would land unmasked in the job log.
-          rm -rf ~/.unsloth/studio/auth
-          bash .github/scripts/serve-unsloth-run.sh \
-            --gguf-file "$GITHUB_WORKSPACE/gguf-cache/${GGUF_FILE}" \
-            --port "$STUDIO_PORT" --log-dir logs \
-            --extra "--seed $UNSLOTH_SEED --temp 0" \
-            --health-timeout 900
-
-      # ── (a) server/API preflight: prove the dialect works BEFORE the agent ─
-      # Distinct error class. If this step fails it is a SERVER regression,
-      # not the agent's or the guide's fault, and the agent steps never run.
-      - name: Preflight the agent's API dialect (class-a isolation)
-        env:
-          AGENT: ${{ matrix.agent }}
-        run: |
-          set -uo pipefail
-          B="$UNSLOTH_BASE_URL"; K="$UNSLOTH_API_KEY"
-          preflight_fail() {
-            echo "::error::[server/API regression] agent=$AGENT: $* (preflight failed BEFORE install/connect; this is class (a), not guide drift). Endpoint contract lives in studio/backend/routes/**.";
-            exit 1
-          }
-          code=$(curl -s -o /tmp/pf.json -w '%{http_code}' "$B/v1/models" \
-            -H "Authorization: Bearer $K") || true
-          [ "$code" = "200" ] || preflight_fail "/v1/models returned HTTP $code"
-          case "$AGENT" in
-            claude)
-              # Anthropic Messages dialect.
-              code=$(curl -s -o /tmp/pf.json -w '%{http_code}' "$B/v1/messages" \
-                -H "Authorization: Bearer $K" -H 'content-type: application/json' \
-                --max-time 120 \
-                -d "{\"model\":\"$UNSLOTH_MODEL_ID\",\"max_tokens\":16,\"messages\":[{\"role\":\"user\",\"content\":\"Hi\"}]}") || true
-              [ "$code" = "200" ] || preflight_fail "/v1/messages returned HTTP $code"
-              ;;
-            codex)
-              # Codex always streams /v1/responses.
-              code=$(curl -s -o /tmp/pf.json -w '%{http_code}' "$B/v1/responses" \
-                -H "Authorization: Bearer $K" -H 'content-type: application/json' \
-                --max-time 120 \
-                -d "{\"model\":\"$UNSLOTH_MODEL_ID\",\"input\":\"Hi\",\"max_output_tokens\":16,\"stream\":true}") || true
-              [ "$code" = "200" ] || preflight_fail "/v1/responses returned HTTP $code"
-              ;;
-            *)
-              # OpenAI Chat Completions dialect (hermes/opencode/pi/openclaw).
-              # OpenClaw's start.py recipe writes an "openai-completions"
-              # provider (write_openclaw_config), so it uses this path, not
-              # /v1/messages.
-              code=$(curl -s -o /tmp/pf.json -w '%{http_code}' "$B/v1/chat/completions" \
-                -H "Authorization: Bearer $K" -H 'content-type: application/json' \
-                --max-time 120 \
-                -d "{\"model\":\"$UNSLOTH_MODEL_ID\",\"max_tokens\":16,\"messages\":[{\"role\":\"user\",\"content\":\"Hi\"}]}") || true
-              [ "$code" = "200" ] || preflight_fail "/v1/chat/completions returned HTTP $code"
-              ;;
-          esac
-          echo "preflight OK for $AGENT"
-
-      # ── (b) install the agent CLI (hardened npm/curl, retried) ─────────
-      - name: Install agent CLI (class-b isolation)
-        env:
-          AGENT: ${{ matrix.agent }}
-        run: bash .github/scripts/agent-guides-install.sh "$AGENT"
-
-      # ── (c) drive the agent via start.py and assert a reply ──────────
-      # For the 5 agents with a start.py recipe we run
-      # `unsloth start <agent> --no-launch`, eval its env/unset exports,
-      # then run the printed command with a hard timeout (no headless-TTY
-      # hang). Pi has no connect recipe, so it is driven by hand and the
-      # cell asserts that absence is the (known) reason.
-      - name: Drive ${{ matrix.agent }} via unsloth start (class-c isolation)
-        env:
-          AGENT: ${{ matrix.agent }}
-        run: bash .github/scripts/agent-guides-drive.sh connection "$AGENT"
-
-      - name: Collect server logs (debug)
-        if: always()
-        run: |
-          mkdir -p logs/studio-logs
-          cp -r "$HOME/.unsloth/studio/logs/." logs/studio-logs/ 2>/dev/null || true
-          # Redact the key across the WHOLE logs/ tree, not just studio-logs:
-          # serve-unsloth-run.sh records the `unsloth run` banner (which prints
-          # `API Key: <key>`) into logs/unsloth-run-<port>.log, and the upload
-          # step publishes all of logs/, so scrubbing only studio-logs would leak
-          # the bearer token in the retained artifact.
-          # Sweep EVERY uploaded path, not just logs/ -- redacted-configs/ and
-          # agent-workdir/ are published by the same upload step.
-          if [ -n "${UNSLOTH_API_KEY:-}" ]; then
-            grep -rlF "$UNSLOTH_API_KEY" logs redacted-configs agent-workdir 2>/dev/null | while IFS= read -r f; do
-              sed -i "s#${UNSLOTH_API_KEY}#<REDACTED>#g" "$f" 2>/dev/null || true
-            done
-          fi
-
-      - name: Stop Unsloth
-        if: always()
-        run: |
-          # Guard the PID: an unset/zero UNSLOTH_SERVER_PID would make
-          # `kill 0` signal this step's whole process group and abort cleanup.
-          if [ -n "${UNSLOTH_SERVER_PID:-}" ] && [ "${UNSLOTH_SERVER_PID}" != "0" ]; then
-            kill "${UNSLOTH_SERVER_PID}" 2>/dev/null || true
-          fi
-          sleep 2
-          ss -tln 2>/dev/null | grep ":${STUDIO_PORT}" || true
-
-      - name: Upload logs
-        if: always()
-        continue-on-error: true
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: connection-${{ matrix.agent }}-log
-          path: |
-            logs/
-            redacted-configs/
-          retention-days: 7
-
-  # ═════════════════════════════════════════════════════════════════════
-  # Job 2: file-edit
-  #   The deterministic 2-turn hello.py test on Qwen3.5-4B (smaller models
-  #   can't reliably drive the heavyweight agents' edit flows). Weekly +
-  #   dispatch only -- it is the slow, model-heavy job and must not gate PRs.
-  # ═════════════════════════════════════════════════════════════════════
-  file-edit:
-    name: file-edit (${{ matrix.agent }})
-    if: github.event_name != 'pull_request'
-    runs-on: ubuntu-latest
-    timeout-minutes: 60
-    # hermes and openclaw drive a multi-turn tool loop that a CPU-only runner
-    # cannot finish in time (e.g. openclaw holds its 300s session-write-lock past
-    # expiry; each turn re-prefills the tool prompt at ~16 tok/s). Their endpoint
-    # wiring + generation are already hard-gated by the connection job, so the
-    # file-edit cell is best-effort here -- it still runs and uploads logs, but a
-    # timeout does not fail the workflow. Drop best_effort (or move e2e to a GPU
-    # runner) to make it blocking again.
-    continue-on-error: ${{ matrix.best_effort || false }}
-    strategy:
-      fail-fast: false
-      matrix:
-        agent: [claude, codex, hermes, openclaw, opencode, pi]
-        include:
-          - agent: openclaw
-            node: '24'
-            best_effort: true
-          - agent: hermes
-            best_effort: true
-    env:
-      # gemma-4-E4B served as a flat GGUF file (cache size tracks the .gguf 1:1,
-      # no xet-chunk inflation; the -MTP- repo ships no separate draft file).
-      GGUF_REPO: unsloth/gemma-4-E4B-it-GGUF
-      GGUF_FILE: gemma-4-E4B-it-UD-Q4_K_XL.gguf
-      STUDIO_PORT: '18902'
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - name: Linux deps for llama.cpp prebuilt
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y --no-install-recommends \
-            libcurl4-openssl-dev libssl-dev jq
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: ${{ matrix.node || '22' }}
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-
-      - name: Restore GGUF model file
-        id: cache-gguf
-        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        continue-on-error: true
-        with:
-          path: gguf-cache
-          key: ${{ runner.os }}-gguf-${{ env.GGUF_REPO }}-${{ env.GGUF_FILE }}-v1
-
-      - name: Download GGUF if cache miss
-        id: download-gguf
-        if: steps.cache-gguf.outputs.cache-hit != 'true' || steps.cache-gguf.outcome != 'success'
-        env:
-          # Gated off PR (see note above); public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          python -m pip install --upgrade huggingface_hub
-          mkdir -p gguf-cache
-          bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE" gguf-cache
-
-      - name: Save GGUF model file
-        if: always() && steps.download-gguf.outcome == 'success'
-        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        with:
-          path: gguf-cache
-          key: ${{ runner.os }}-gguf-${{ env.GGUF_REPO }}-${{ env.GGUF_FILE }}-v1
-
-      - name: Install Unsloth (--local, --no-torch)
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Gated off PR (see note above); public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          mkdir -p logs
-          set -o pipefail
-          bash install.sh --local --no-torch 2>&1 | tee logs/install.log
-
-      - name: Serve unsloth run --disable-tools (gemma-4-E4B)
-        run: |
-          rm -rf ~/.unsloth/studio/auth
-          bash .github/scripts/serve-unsloth-run.sh \
-            --gguf-file "$GITHUB_WORKSPACE/gguf-cache/${GGUF_FILE}" \
-            --port "$STUDIO_PORT" --log-dir logs \
-            --extra "--seed $UNSLOTH_SEED --temp 0" \
-            --health-timeout 900
-
-      - name: Preflight the agent's API dialect (class-a isolation)
-        env:
-          AGENT: ${{ matrix.agent }}
-        run: |
-          set -uo pipefail
-          B="$UNSLOTH_BASE_URL"; K="$UNSLOTH_API_KEY"
-          preflight_fail() {
-            echo "::error::[server/API regression] agent=$AGENT: $* (preflight failed BEFORE install/connect; this is class (a), not guide drift). Endpoint contract lives in studio/backend/routes/**.";
-            exit 1
-          }
-          code=$(curl -s -o /tmp/pf.json -w '%{http_code}' "$B/v1/models" \
-            -H "Authorization: Bearer $K") || true
-          [ "$code" = "200" ] || preflight_fail "/v1/models returned HTTP $code"
-          # Probe the same dialect the agent will use, so a streaming/messages
-          # regression in the weekly run is reported as class (a) here instead of
-          # surfacing later as guide drift (mirrors the connection job).
-          case "$AGENT" in
-            claude)
-              code=$(curl -s -o /tmp/pf.json -w '%{http_code}' "$B/v1/messages" \
-                -H "Authorization: Bearer $K" -H 'content-type: application/json' \
-                --max-time 120 \
-                -d "{\"model\":\"$UNSLOTH_MODEL_ID\",\"max_tokens\":16,\"messages\":[{\"role\":\"user\",\"content\":\"Hi\"}]}") || true
-              [ "$code" = "200" ] || preflight_fail "/v1/messages returned HTTP $code"
-              ;;
-            codex)
-              code=$(curl -s -o /tmp/pf.json -w '%{http_code}' "$B/v1/responses" \
-                -H "Authorization: Bearer $K" -H 'content-type: application/json' \
-                --max-time 120 \
-                -d "{\"model\":\"$UNSLOTH_MODEL_ID\",\"input\":\"Hi\",\"max_output_tokens\":16,\"stream\":true}") || true
-              [ "$code" = "200" ] || preflight_fail "/v1/responses returned HTTP $code"
-              ;;
-            *)
-              # OpenAI Chat Completions dialect (hermes/opencode/pi/openclaw).
-              code=$(curl -s -o /tmp/pf.json -w '%{http_code}' "$B/v1/chat/completions" \
-                -H "Authorization: Bearer $K" -H 'content-type: application/json' \
-                --max-time 120 \
-                -d "{\"model\":\"$UNSLOTH_MODEL_ID\",\"max_tokens\":16,\"messages\":[{\"role\":\"user\",\"content\":\"Hi\"}]}") || true
-              [ "$code" = "200" ] || preflight_fail "/v1/chat/completions returned HTTP $code"
-              ;;
-          esac
-          echo "preflight OK for $AGENT"
-
-      - name: Install agent CLI (class-b isolation)
-        env:
-          AGENT: ${{ matrix.agent }}
-        run: bash .github/scripts/agent-guides-install.sh "$AGENT"
-
-      - name: 2-turn hello.py test (class-c isolation)
-        env:
-          AGENT: ${{ matrix.agent }}
-        run: bash .github/scripts/agent-guides-drive.sh file-edit "$AGENT"
-
-      - name: Collect server logs (debug)
-        if: always()
-        run: |
-          mkdir -p logs/studio-logs
-          cp -r "$HOME/.unsloth/studio/logs/." logs/studio-logs/ 2>/dev/null || true
-          # Redact the key across the WHOLE logs/ tree, not just studio-logs:
-          # serve-unsloth-run.sh records the `unsloth run` banner (which prints
-          # `API Key: <key>`) into logs/unsloth-run-<port>.log, and the upload
-          # step publishes all of logs/, so scrubbing only studio-logs would leak
-          # the bearer token in the retained artifact.
-          # Sweep EVERY uploaded path, not just logs/ -- redacted-configs/ and
-          # agent-workdir/ are published by the same upload step.
-          if [ -n "${UNSLOTH_API_KEY:-}" ]; then
-            grep -rlF "$UNSLOTH_API_KEY" logs redacted-configs agent-workdir 2>/dev/null | while IFS= read -r f; do
-              sed -i "s#${UNSLOTH_API_KEY}#<REDACTED>#g" "$f" 2>/dev/null || true
-            done
-          fi
-
-      - name: Stop Unsloth
-        if: always()
-        run: |
-          # Guard the PID: an unset/zero UNSLOTH_SERVER_PID would make
-          # `kill 0` signal this step's whole process group and abort cleanup.
-          if [ -n "${UNSLOTH_SERVER_PID:-}" ] && [ "${UNSLOTH_SERVER_PID}" != "0" ]; then
-            kill "${UNSLOTH_SERVER_PID}" 2>/dev/null || true
-          fi
-          sleep 2
-          ss -tln 2>/dev/null | grep ":${STUDIO_PORT}" || true
-
-      - name: Upload logs
-        if: always()
-        continue-on-error: true
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: file-edit-${{ matrix.agent }}-log
-          path: |
-            logs/
-            agent-workdir/
-            redacted-configs/
-          retention-days: 7
-
-  # ═════════════════════════════════════════════════════════════════════
-  # Job: resume
-  #   Does a conversation started with `unsloth start <agent>` survive exit
-  #   and resume? This drives the REAL launch path (not the --no-launch
-  #   recipe the other jobs use). A plain launch relocates the agent home to
-  #   a temp dir wiped on exit, so codex/pi cannot resume; --persist routes the
-  #   session to the stable Unsloth agents dir so it persists. opencode/claude
-  #   keep their session data in a fixed user dir, so they persist either way.
-  #   Dispatch-only: it is an end-to-end experiment, not a PR gate.
-  # ═════════════════════════════════════════════════════════════════════
-  resume:
-    name: resume (${{ matrix.agent }})
-    if: github.event_name == 'workflow_dispatch'
-    runs-on: ubuntu-latest
-    timeout-minutes: 60
-    strategy:
-      fail-fast: false
-      matrix:
-        # codex/pi relocate their whole home (resume broken without --persist);
-        # opencode/claude keep session data in a fixed dir (resume already works).
-        # One agent from each class proves the split end to end; openclaw/hermes
-        # share codex's relocation mechanism and are covered by the unit tests.
-        agent: [codex, opencode, claude, pi]
-    env:
-      GGUF_REPO: unsloth/gemma-4-E4B-it-GGUF
-      GGUF_FILE: gemma-4-E4B-it-UD-Q4_K_XL.gguf
-      STUDIO_PORT: '18904'
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - name: Linux deps for llama.cpp prebuilt
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y --no-install-recommends \
-            libcurl4-openssl-dev libssl-dev jq
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: '22'
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-
-      - name: Restore GGUF model file
-        id: cache-gguf
-        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        continue-on-error: true
-        with:
-          path: gguf-cache
-          key: ${{ runner.os }}-gguf-${{ env.GGUF_REPO }}-${{ env.GGUF_FILE }}-v1
-
-      - name: Download GGUF if cache miss
-        id: download-gguf
-        if: steps.cache-gguf.outputs.cache-hit != 'true' || steps.cache-gguf.outcome != 'success'
-        env:
-          HF_TOKEN: ${{ secrets.HF_TOKEN }}
-        run: |
-          python -m pip install --upgrade huggingface_hub
-          mkdir -p gguf-cache
-          bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE" gguf-cache
-
-      - name: Save GGUF model file
-        if: always() && steps.download-gguf.outcome == 'success'
-        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        with:
-          path: gguf-cache
-          key: ${{ runner.os }}-gguf-${{ env.GGUF_REPO }}-${{ env.GGUF_FILE }}-v1
-
-      - name: Install Unsloth (--local, --no-torch)
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          HF_TOKEN: ${{ secrets.HF_TOKEN }}
-        run: |
-          mkdir -p logs
-          set -o pipefail
-          bash install.sh --local --no-torch 2>&1 | tee logs/install.log
-
-      - name: Serve unsloth run --disable-tools (gemma-4-E4B)
-        run: |
-          rm -rf ~/.unsloth/studio/auth
-          bash .github/scripts/serve-unsloth-run.sh \
-            --gguf-file "$GITHUB_WORKSPACE/gguf-cache/${GGUF_FILE}" \
-            --port "$STUDIO_PORT" --log-dir logs \
-            --extra "--seed $UNSLOTH_SEED --temp 0" \
-            --health-timeout 900
-
-      - name: Preflight the agent's API dialect (class-a isolation)
-        env:
-          AGENT: ${{ matrix.agent }}
-        run: |
-          set -uo pipefail
-          B="$UNSLOTH_BASE_URL"; K="$UNSLOTH_API_KEY"
-          preflight_fail() {
-            echo "::error::[server/API regression] agent=$AGENT: $* (preflight failed BEFORE install/connect). Endpoint contract lives in studio/backend/routes/**.";
-            exit 1
-          }
-          code=$(curl -s -o /tmp/pf.json -w '%{http_code}' "$B/v1/models" \
-            -H "Authorization: Bearer $K") || true
-          [ "$code" = "200" ] || preflight_fail "/v1/models returned HTTP $code"
-          case "$AGENT" in
-            claude)
-              code=$(curl -s -o /tmp/pf.json -w '%{http_code}' "$B/v1/messages" \
-                -H "Authorization: Bearer $K" -H 'content-type: application/json' \
-                --max-time 120 \
-                -d "{\"model\":\"$UNSLOTH_MODEL_ID\",\"max_tokens\":16,\"messages\":[{\"role\":\"user\",\"content\":\"Hi\"}]}") || true
-              [ "$code" = "200" ] || preflight_fail "/v1/messages returned HTTP $code"
-              ;;
-            codex)
-              code=$(curl -s -o /tmp/pf.json -w '%{http_code}' "$B/v1/responses" \
-                -H "Authorization: Bearer $K" -H 'content-type: application/json' \
-                --max-time 120 \
-                -d "{\"model\":\"$UNSLOTH_MODEL_ID\",\"input\":\"Hi\",\"max_output_tokens\":16,\"stream\":true}") || true
-              [ "$code" = "200" ] || preflight_fail "/v1/responses returned HTTP $code"
-              ;;
-            *)
-              code=$(curl -s -o /tmp/pf.json -w '%{http_code}' "$B/v1/chat/completions" \
-                -H "Authorization: Bearer $K" -H 'content-type: application/json' \
-                --max-time 120 \
-                -d "{\"model\":\"$UNSLOTH_MODEL_ID\",\"max_tokens\":16,\"messages\":[{\"role\":\"user\",\"content\":\"Hi\"}]}") || true
-              [ "$code" = "200" ] || preflight_fail "/v1/chat/completions returned HTTP $code"
-              ;;
-          esac
-          echo "preflight OK for $AGENT"
-
-      - name: Install agent CLI (class-b isolation)
-        env:
-          AGENT: ${{ matrix.agent }}
-        run: bash .github/scripts/agent-guides-install.sh "$AGENT"
-
-      - name: Resume experiment (launch path)
-        env:
-          AGENT: ${{ matrix.agent }}
-        run: bash .github/scripts/agent-guides-drive.sh resume "$AGENT"
-
-      - name: Collect server logs (debug)
-        if: always()
-        run: |
-          mkdir -p logs/studio-logs
-          cp -r "$HOME/.unsloth/studio/logs/." logs/studio-logs/ 2>/dev/null || true
-          if [ -n "${UNSLOTH_API_KEY:-}" ]; then
-            grep -rlF "$UNSLOTH_API_KEY" logs redacted-configs agent-workdir 2>/dev/null | while IFS= read -r f; do
-              sed -i "s#${UNSLOTH_API_KEY}#<REDACTED>#g" "$f" 2>/dev/null || true
-            done
-          fi
-
-      - name: Stop Unsloth
-        if: always()
-        run: |
-          if [ -n "${UNSLOTH_SERVER_PID:-}" ] && [ "${UNSLOTH_SERVER_PID}" != "0" ]; then
-            kill "${UNSLOTH_SERVER_PID}" 2>/dev/null || true
-          fi
-          sleep 2
-          ss -tln 2>/dev/null | grep ":${STUDIO_PORT}" || true
-
-      - name: Upload logs
-        if: always()
-        continue-on-error: true
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: resume-${{ matrix.agent }}-log
-          path: |
-            logs/
-            agent-workdir/
-            redacted-configs/
-          retention-days: 7
-
-  # ═════════════════════════════════════════════════════════════════════
-  # Job 3: prompt-cache
-  #   (a) curl 2-turn /v1/chat/completions: assert turn-2 cached_tokens > 0
-  #       (server prompt-cache sanity).
-  #   (b) Claude Code attribution A/B: with CLAUDE_CODE_ATTRIBUTION_HEADER=0
-  #       expect a llama-server KV-cache HIT on turn 2; without it expect a
-  #       MISS. If it inverts, the guide flag is stale.
-  #   PR + weekly + dispatch (cheap, gemma-3-270m).
-  # ═════════════════════════════════════════════════════════════════════
-  prompt-cache:
-    name: prompt-cache (gemma-3-270m)
-    runs-on: ubuntu-latest
-    timeout-minutes: 25
-    env:
-      GGUF_REPO: unsloth/gemma-3-270m-it-GGUF
-      GGUF_VARIANT: UD-Q4_K_XL
-      GGUF_FILE: gemma-3-270m-it-UD-Q4_K_XL.gguf
-      STUDIO_PORT: '18903'
-      HF_HOME: ${{ github.workspace }}/hf-cache
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - name: Linux deps for llama.cpp prebuilt
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y --no-install-recommends \
-            libcurl4-openssl-dev libssl-dev jq
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: '22'
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-
-      - name: Restore HF_HOME for ${{ env.GGUF_REPO }}
-        id: cache-hf
-        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        continue-on-error: true
-        with:
-          path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
-
-      - name: Prime HF_HOME with the GGUF
-        id: prime-hf
-        if: steps.cache-hf.outputs.cache-hit != 'true' || steps.cache-hf.outcome != 'success'
-        env:
-          # Gated off PR (see note above); public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          python -m pip install --upgrade huggingface_hub
-          mkdir -p hf-cache
-          bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
-
-      - name: Save HF_HOME for ${{ env.GGUF_REPO }}
-        if: always() && steps.prime-hf.outcome == 'success'
-        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        with:
-          path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
-
-      - name: Install Unsloth (--local, --no-torch)
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Gated off PR (see note above); public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          mkdir -p logs
-          set -o pipefail
-          bash install.sh --local --no-torch 2>&1 | tee logs/install.log
-
-      - name: Serve unsloth run --disable-tools (gemma-3-270m)
-        run: |
-          rm -rf ~/.unsloth/studio/auth
-          bash .github/scripts/serve-unsloth-run.sh \
-            --model "$GGUF_REPO" --gguf-variant "$GGUF_VARIANT" \
-            --port "$STUDIO_PORT" --log-dir logs \
-            --extra "--seed $UNSLOTH_SEED --temp 0"
-
-      # (a) server prompt-cache sanity on the OpenAI chat path. The helper runs
-      # the 2-turn probe internally (turn 2 reuses turn 1's prefix) and asserts
-      # turn-2 usage.prompt_tokens_details.cached_tokens > 0. This is the hard
-      # gate -- it proves llama.cpp KV reuse is surfaced on /v1/chat/completions.
-      - name: Server prompt-cache sanity (cached_tokens > 0)
-        run: bash .github/scripts/assert-prompt-cache.sh api "$UNSLOTH_BASE_URL" "$UNSLOTH_API_KEY"
-
-      - name: Install Claude Code (class-b isolation)
-        env:
-          AGENT: claude
-        run: bash .github/scripts/agent-guides-install.sh claude
-
-      # (b) Claude attribution A/B against the llama-server log. This is the most
-      # environment-sensitive check (it depends on the bundled llama.cpp's
-      # slot-reuse log wording and on claude --continue reusing the prefix), so
-      # it is non-blocking until calibrated on the first scheduled run; the
-      # server cache sanity above is the hard gate. The step still prints the
-      # observed HIT/MISS so drift is visible in the log + artifacts.
-      - name: Claude attribution A/B (HIT with header=0, MISS without)
-        continue-on-error: true
-        run: bash .github/scripts/agent-guides-drive.sh attribution-ab claude
-
-      - name: Collect server logs (debug)
-        if: always()
-        run: |
-          mkdir -p logs/studio-logs
-          cp -r "$HOME/.unsloth/studio/logs/." logs/studio-logs/ 2>/dev/null || true
-          # Redact the key across the WHOLE logs/ tree, not just studio-logs:
-          # serve-unsloth-run.sh records the `unsloth run` banner (which prints
-          # `API Key: <key>`) into logs/unsloth-run-<port>.log, and the upload
-          # step publishes all of logs/, so scrubbing only studio-logs would leak
-          # the bearer token in the retained artifact.
-          # Sweep EVERY uploaded path, not just logs/ -- redacted-configs/ and
-          # agent-workdir/ are published by the same upload step.
-          if [ -n "${UNSLOTH_API_KEY:-}" ]; then
-            grep -rlF "$UNSLOTH_API_KEY" logs redacted-configs agent-workdir 2>/dev/null | while IFS= read -r f; do
-              sed -i "s#${UNSLOTH_API_KEY}#<REDACTED>#g" "$f" 2>/dev/null || true
-            done
-          fi
-
-      - name: Stop Unsloth
-        if: always()
-        run: |
-          # Guard the PID: an unset/zero UNSLOTH_SERVER_PID would make
-          # `kill 0` signal this step's whole process group and abort cleanup.
-          if [ -n "${UNSLOTH_SERVER_PID:-}" ] && [ "${UNSLOTH_SERVER_PID}" != "0" ]; then
-            kill "${UNSLOTH_SERVER_PID}" 2>/dev/null || true
-          fi
-          sleep 2
-          ss -tln 2>/dev/null | grep ":${STUDIO_PORT}" || true
-
-      - name: Upload logs
-        if: always()
-        continue-on-error: true
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: prompt-cache-log
-          path: |
-            logs/
-            redacted-configs/
-          retention-days: 7

.github/workflows/lockfile-audit.yml

@@ -1,79 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-#
-# Fast, focused supply-chain audit of every checked-in lockfile.
-#
-# Runs scripts/lockfile_supply_chain_audit.py on PRs that touch any
-# npm or cargo lockfile, on push to main, and on a daily schedule so
-# newly-published IOCs surface even when no PR opens.
-#
-# Default behavior is "advisory": only public indicator-of-compromise
-# strings, known-malicious pinned versions, and structurally broken
-# lockfiles fail the build. Structural anomalies (missing integrity,
-# non-default registry, etc.) are emitted as GitHub Actions warnings
-# but do not block merges. This deliberately keeps the noise floor
-# low while still failing the moment a checked-in lockfile starts
-# pointing at known-bad bytes.
-#
-# This workflow is intentionally separate from security-audit.yml:
-#   - security-audit.yml is the umbrella job (pip-audit + npm audit +
-#     cargo audit + OSV + Semgrep + secret scanning + SBOM + ...);
-#     it takes ~25 minutes and runs only when dep manifests change.
-#   - lockfile-audit.yml is a ~30 second pure-Python parse + grep on
-#     the lockfiles themselves; it runs on every PR that even nudges
-#     a lockfile so reviewers always see the audit result inline.
-
-name: Lockfile supply-chain audit
-
-on:
-  pull_request:
-    paths:
-      - 'studio/frontend/package-lock.json'
-      - 'studio/backend/core/data_recipe/oxc-validator/package-lock.json'
-      - 'studio/package-lock.json'
-      - 'studio/src-tauri/Cargo.lock'
-      - 'scripts/lockfile_supply_chain_audit.py'
-      - '.github/workflows/lockfile-audit.yml'
-  push:
-    branches: [main]
-    paths:
-      - 'studio/frontend/package-lock.json'
-      - 'studio/backend/core/data_recipe/oxc-validator/package-lock.json'
-      - 'studio/package-lock.json'
-      - 'studio/src-tauri/Cargo.lock'
-      - 'scripts/lockfile_supply_chain_audit.py'
-      - '.github/workflows/lockfile-audit.yml'
-  schedule:
-    - cron: '37 5 * * *'
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  audit:
-    name: lockfile supply-chain audit
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
-        with:
-          persist-credentials: false
-
-      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6.3.0
-        with:
-          python-version: '3.12'
-
-      - name: Verify audit script parses
-        run: python3 -c "import ast; ast.parse(open('scripts/lockfile_supply_chain_audit.py').read())"
-
-      - name: Run lockfile supply-chain audit
-        # Default mode: only known-malicious pinned versions, known IOC
-        # strings, and structurally broken lockfiles fail the build.
-        # Missing-integrity and other structural anomalies are emitted
-        # as ::warning:: annotations and do not gate merges.
-        run: python3 scripts/lockfile_supply_chain_audit.py

.github/workflows/mlx-ci.yml

@@ -1,403 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Focused PR gate for the MLX dispatch surface, running on a real
-# Apple Silicon runner.
-#
-# Runner: macos-14 (M1, 3 vCPU / 7 GB / Apple Silicon standard runner
-# -- FREE for public repositories per the GitHub Actions billing
-# reference; larger variants like macos-14-large/-xlarge are paid so
-# we deliberately avoid those).
-#
-# Why a single Mac job (no Linux+spoof leg): the dispatch tests are
-# 100% spoofed monkeypatches and run identically on any host, so the
-# Linux leg was duplicating the matrix tests already covered on Mac
-# while missing everything Apple-specific. The Mac job runs the SAME
-# spoofed matrix PLUS three things only a real Apple Silicon host
-# can prove:
-#
-#   1. unsloth._IS_MLX flips True on Darwin+arm64 with mlx genuinely
-#      installed (no spoof).
-#   2. Every PR-A MLX-only unsloth_zoo module (mlx_loader, mlx_trainer,
-#      mlx_compile, mlx_utils, mlx_cce, gated_delta_vjp) imports
-#      against the real `mlx` + `mlx-lm` + `mlx-vlm` PyPI wheels --
-#      each does `import mlx.core as mx` at module top level, so this
-#      catches a future change that breaks the real wheels without
-#      needing a Mac developer in the loop.
-#   3. The hardware-dispatch spoofs do not collide with the real
-#      environment (the test fixture installs a MetaPathFinder that
-#      blocks `import mlx.core` for "no-mlx" profiles, faithfully
-#      simulating a Mac without mlx even when mlx IS installed).
-#   4. End-to-end MLX training + inference smoke test:
-#      run_real_mlx_smoke.py trains unsloth/gemma-3-270m-it for 7
-#      deterministic LoRA steps on a single repeated text row, then
-#      verifies the trained model can complete the prompt and that
-#      losses + grad norms are finite and well-behaved. This is the
-#      only place in CI that exercises a real MLX backward pass +
-#      optimizer step + inference call.
-#
-# Three dispatch test files documented in tests/studio/README.md:
-#   - test_hardware_dispatch_matrix.py    parametrized 7-profile matrix
-#                                         + 2 dispatch-priority canaries
-#   - test_is_mlx_dispatch_gate.py        AST + runtime guard on
-#                                         unsloth._IS_MLX
-#   - test_mlx_training_worker_behaviors.py  AST contract checks on
-#                                            studio/backend/core/training/worker.py
-#
-# Surfaces a single PR check ("MLX CI on Mac M1 / dispatch").
-#
-# Security audit footprint: every package this workflow installs is
-# already covered by .github/workflows/security-audit.yml -- the deps
-# come from studio/backend/requirements/studio.txt and unsloth-zoo's
-# pyproject (resolved transitively). The git+ install of unsloth-zoo
-# is intentionally skipped by the audit (pip-audit cannot resolve a
-# git URL through PyPI metadata; the audit comment in security-audit.yml
-# documents this). No new package is introduced solely by MLX CI.
-
-name: MLX CI on Mac M1
-
-on:
-  pull_request:
-    paths:
-      - 'unsloth/__init__.py'
-      - 'unsloth/_gpu_init.py'
-      - 'studio/backend/utils/hardware/**'
-      - 'studio/backend/core/training/worker.py'
-      - 'studio/backend/core/inference/mlx_inference.py'
-      - 'tests/studio/test_hardware_dispatch_matrix.py'
-      - 'tests/studio/test_is_mlx_dispatch_gate.py'
-      - 'tests/studio/test_mlx_training_worker_behaviors.py'
-      - 'tests/studio/run_real_mlx_smoke.py'
-      - 'tests/conftest.py'
-      - '.github/workflows/mlx-ci.yml'
-  push:
-    branches: [main, pip]
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  dispatch:
-    name: dispatch
-    runs-on: macos-14
-    # 25 min: dispatch + spoofed matrix + 7-step real LoRA training is
-    # under 2 min; GGUF export builds llama.cpp via cmake on Apple
-    # Silicon (~5-7 min), so we budget headroom.
-    timeout-minutes: 25
-    steps:
-      # harden-runner audit mode: macOS runners cannot use blocking mode
-      # today (eBPF egress enforcement is Linux-only), but audit mode is
-      # supported cross-platform and surfaces the egress destinations in
-      # the runner log. This produces the data needed to graduate this
-      # job to a block-mode allowlist once macOS support lands.
-      - name: Harden runner (audit)
-        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450  # v2.19.1
-        with:
-          egress-policy: audit
-
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-
-      # macOS install ladder, validated locally against a Linux
-      # mac-sim venv (platform spoofed + mlx_simulation shim + real
-      # datasets/transformers/structlog).
-      #
-      # 1. studio/backend/requirements/studio.txt brings structlog,
-      #    fastapi, etc. The hardware probe imports structlog at
-      #    module top level.
-      # 2. Same pytest / numpy / httpx stack the rest of the repo CI
-      #    uses.
-      # 3. torch is explicitly installed: unsloth-zoo's pyproject
-      #    deliberately excludes torch on darwin+arm64 (mlx replaces
-      #    it for runtime use), but the dispatch tests spoof
-      #    torch.cuda / torch.xpu / torch.backends.mps via monkeypatch
-      #    and so the test process needs torch importable. We pull
-      #    from the PyTorch CPU index so Apple Silicon gets the
-      #    explicit cpu+MPS arm64 wheel rather than something the
-      #    default PyPI resolver might pick up. The CPU index hosts
-      #    macosx_*_arm64 wheels alongside the Linux x86_64 ones.
-      # 4. unsloth-zoo from git main (NOT PyPI), WITH deps. PR-A's
-      #    MLX support landed after the most recent unsloth-zoo PyPI
-      #    release; the wheel still raises NotImplementedError on
-      #    Apple Silicon when device_type.get_device_type() runs
-      #    unguarded. Unsloth's own install.sh overlays unsloth-zoo
-      #    from git main for the same reason. Pulling deps lets pip
-      #    resolve the platform-conditional MLX-only wheels (mlx,
-      #    mlx-lm, mlx-vlm gated on darwin+arm64 in unsloth-zoo's
-      #    pyproject) AND the shared deps (datasets, transformers,
-      #    sentencepiece, ...) that unsloth's MLX branch loads via
-      #    dataprep/raw_text.py.
-      # 5. unsloth -e . --no-deps so the editable install does not
-      #    fight the unsloth-zoo dep set.
-      #
-      # All explicit pip installs are version-pinned to a single
-      # released version (the latest as of 2026-05-07 within each
-      # project's existing constraint range). bump alongside the rest
-      # of the security audit when a new release lands.
-      - name: Install deps
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r studio/backend/requirements/studio.txt
-          pip install \
-            'python-multipart==0.0.27' \
-            'aiofiles==25.1.0' \
-            'sqlalchemy==2.0.49' \
-            'cryptography==48.0.0' \
-            'pyyaml==6.0.3' \
-            'jinja2==3.1.6' \
-            'mammoth==1.12.0' \
-            'unpdf==1.0.0' \
-            'requests==2.33.1' \
-            'typer==0.25.1' \
-            'numpy==2.4.4' \
-            'pytest==9.0.3' \
-            'pytest-asyncio==1.3.0' \
-            'httpx==0.28.1'
-          pip install --index-url https://download.pytorch.org/whl/cpu --extra-index-url https://pypi.org/simple \
-            'torch==2.10.0'
-          # github.com occasionally 500s on the git fetch; retry the
-          # zoo install so a single upstream blip does not fail CI.
-          for attempt in 1 2 3; do
-            if pip install "unsloth_zoo @ git+https://github.com/unslothai/unsloth-zoo"; then
-              break
-            fi
-            if [ "$attempt" -eq 3 ]; then
-              echo "::error::pip install unsloth_zoo failed after 3 attempts"
-              exit 1
-            fi
-            delay=$((5 * attempt))
-            echo "::warning::unsloth_zoo install failed (attempt $attempt/3), retrying in ${delay}s..."
-            sleep "$delay"
-          done
-          pip install -e . --no-deps
-
-      # Real Apple Silicon sanity: confirm _IS_MLX activates on real
-      # hardware with no platform spoof.
-      - name: Verify _IS_MLX flips True on real Apple Silicon
-        run: |
-          python -c "
-          import platform
-          assert platform.system() == 'Darwin', platform.system()
-          assert platform.machine() == 'arm64', platform.machine()
-          import unsloth
-          assert unsloth._IS_MLX is True, f'expected _IS_MLX=True on real Apple Silicon, got {unsloth._IS_MLX}'
-          print('OK: _IS_MLX activated on real Apple Silicon')
-          "
-
-      # Real Apple Silicon sanity: confirm every PR-A MLX-only module
-      # loads against real mlx + mlx-lm + mlx-vlm wheels.
-      - name: Smoke-import every MLX-only unsloth_zoo module
-        run: |
-          python -c "
-          import importlib
-          for name in [
-              'unsloth_zoo.mlx_loader',
-              'unsloth_zoo.mlx_trainer',
-              'unsloth_zoo.mlx_compile',
-              'unsloth_zoo.mlx_utils',
-              'unsloth_zoo.mlx_cce',
-              'unsloth_zoo.gated_delta_vjp',
-          ]:
-              importlib.import_module(name)
-              print('OK:', name)
-          from unsloth_zoo.mlx_loader import FastMLXModel
-          from unsloth_zoo.mlx_trainer import MLXTrainer, MLXTrainingConfig
-          assert hasattr(FastMLXModel, 'from_pretrained')
-          print('OK: FastMLXModel + MLXTrainer surface present')
-          "
-
-      # Spoofed dispatch matrix. Runs on the real Mac too -- the
-      # test fixture installs a MetaPathFinder that blocks
-      # `import mlx.core` for "no-mlx" profiles, so the spoofs
-      # faithfully simulate every supported hardware combo regardless
-      # of whether mlx is installed for real.
-      - name: MLX dispatch tests (3 files, 36 tests)
-        env:
-          PYTHONPATH: ${{ github.workspace }}/studio
-          UNSLOTH_COMPILE_DISABLE: '1'
-        run: |
-          python -m pytest -v --tb=short \
-            tests/studio/test_hardware_dispatch_matrix.py \
-            tests/studio/test_is_mlx_dispatch_gate.py \
-            tests/studio/test_mlx_training_worker_behaviors.py
-
-      # Real MLX training + inference smoke test. Trains
-      # unsloth/gemma-3-270m-it for 7 deterministic LoRA steps
-      # (batch_size=2, gradient_accumulation_steps=3) on a single
-      # repeated row ("<<HELLO!!>> My name is Unsloth!"), then saves
-      # the trained model in 3 export formats. The `train` subcommand
-      # captures per-phase timing + peak GPU + peak RSS into
-      # train_metrics.json so we can detect regressions across CI runs.
-      - name: MLX export round-trip — TRAIN + SAVE 3 formats
-        env:
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-          UNSLOTH_COMPILE_DISABLE: '1'
-        run: |
-          mkdir -p mlx_workdir
-          # Authenticate llama.cpp's release-API lookup (anonymous 403s on rate-limit);
-          # read-only GITHUB_TOKEN scoped here only, never to steps that run binaries.
-          GH_TOKEN="${{ secrets.GITHUB_TOKEN }}" GITHUB_TOKEN="${{ secrets.GITHUB_TOKEN }}" \
-          python tests/studio/run_real_mlx_smoke.py train \
-            --workdir "$PWD/mlx_workdir"
-
-      # Each reload step runs in a FRESH Python process to confirm
-      # the cold-start path users would hit in production also works
-      # (not just the in-memory continuation of a still-running
-      # trainer). FastMLXModel.from_pretrained gets called from
-      # scratch; mx.random is re-seeded; per-step timing + peak
-      # memory are emitted to {format}_reload_metrics.json next to
-      # the saved dir.
-      - name: MLX export round-trip — RELOAD LoRA (fresh process)
-        env:
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-          UNSLOTH_COMPILE_DISABLE: '1'
-        run: |
-          python tests/studio/run_real_mlx_smoke.py reload \
-            --format lora \
-            --dir "$PWD/mlx_workdir/lora"
-
-      - name: MLX export round-trip — RELOAD merged_16bit (fresh process)
-        env:
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-          UNSLOTH_COMPILE_DISABLE: '1'
-        run: |
-          python tests/studio/run_real_mlx_smoke.py reload \
-            --format merged \
-            --dir "$PWD/mlx_workdir/merged_16bit"
-
-      # GGUF reload uses the llama-cli binary that save_pretrained_gguf
-      # built. If save_pretrained_gguf was skipped during train (e.g.
-      # llama.cpp's convert_hf_to_gguf asserts on the model's tokenizer
-      # vocab -- a downstream llama.cpp limitation, not an unsloth_zoo
-      # bug), this step emits a workflow warning and exits 0 so the
-      # LoRA + merged_16bit assertions remain the gating signal.
-      - name: MLX export round-trip — RELOAD GGUF via llama-cli (fresh process)
-        env:
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          if python -c "import json,sys; m=json.load(open('mlx_workdir/train_metrics.json')); sys.exit(0 if m.get('gguf_supported') else 1)"; then
-            python tests/studio/run_real_mlx_smoke.py reload \
-              --format gguf \
-              --dir "$PWD/mlx_workdir/gguf"
-          else
-            REASON=$(python -c "import json; m=json.load(open('mlx_workdir/train_metrics.json')); print(m.get('gguf_skip_reason') or 'unknown')")
-            echo "::warning title=GGUF round-trip skipped::${REASON}"
-            echo "GGUF export was skipped during the train phase. Reason:"
-            echo "  ${REASON}"
-            echo "Continuing without failing the job; the LoRA + merged_16bit"
-            echo "reload assertions are still gating this PR."
-          fi
-
-      # Print all metrics JSON files so regressions are visible in the
-      # job log. always() so we get telemetry even if a reload step
-      # asserted gibberish.
-      - name: MLX export round-trip — aggregate metrics
-        if: always()
-        run: |
-          for f in mlx_workdir/train_metrics.json \
-                   mlx_workdir/lora_reload_metrics.json \
-                   mlx_workdir/merged_reload_metrics.json \
-                   mlx_workdir/gguf_reload_metrics.json; do
-            echo "=== $f ==="
-            cat "$f" 2>/dev/null || echo "(missing)"
-            echo
-          done
-
-      # Validates the macOS prebuilt path Unsloth's setup.sh uses (#5963): install the
-      # unslothai/llama.cpp fork's latest release, download a small public GGUF, and
-      # check llama-server /completion end to end. Split and placed last so the
-      # untrusted binary runs only in the final smoke step, after every HF_TOKEN step,
-      # leaving no token-bearing step or shared workspace for a tampered prebuilt to
-      # corrupt. GH_TOKEN: releases API; HF_TOKEN (withheld on PR): probe + GGUF fetch.
-      - name: Unsloth prebuilt llama.cpp install + GGUF download (Mac M1)
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          set -euo pipefail
-          INSTALL_DIR="$HOME/.unsloth-studio-prebuilt-test/llama.cpp"
-          rm -rf "$INSTALL_DIR"
-          # Download only -- no llama-quantize / llama-server launch in this step.
-          python studio/install_llama_prebuilt.py \
-            --install-dir "$INSTALL_DIR" \
-            --published-repo unslothai/llama.cpp
-          mkdir -p /tmp/ggufs
-          bash .github/scripts/hf-download-with-retry.sh \
-            'unsloth/gemma-3-270m-it-GGUF' \
-            'gemma-3-270m-it-Q4_K_M.gguf' \
-            /tmp/ggufs
-
-      # Final step: runs the downloaded binaries with no secrets present, and clears
-      # the GitHub Actions command files so a tampered prebuilt cannot influence the job.
-      - name: Unsloth prebuilt llama.cpp GGUF inference smoke (Mac M1)
-        run: |
-          set -euo pipefail
-          unset GITHUB_ENV GITHUB_PATH GITHUB_OUTPUT GITHUB_STEP_SUMMARY
-          INSTALL_DIR="$HOME/.unsloth-studio-prebuilt-test/llama.cpp"
-          # Unsloth bundles only llama-server + llama-quantize (not llama-cli);
-          # inference goes through llama-server's HTTP /completion endpoint.
-          LLAMA_SERVER="$INSTALL_DIR/build/bin/llama-server"
-          LLAMA_QUANT="$INSTALL_DIR/build/bin/llama-quantize"
-          [ -x "$LLAMA_SERVER" ] || { echo "::error::llama-server missing at $LLAMA_SERVER"; find "$INSTALL_DIR/build" -type f | head -40; exit 1; }
-          [ -x "$LLAMA_QUANT" ]  || { echo "::error::llama-quantize missing at $LLAMA_QUANT"; exit 1; }
-          echo "llama-server : $LLAMA_SERVER"
-          echo "llama-quantize: $LLAMA_QUANT"
-          "$LLAMA_QUANT" --help >/dev/null && echo "  llama-quantize loads OK"
-
-          PORT=18080
-          echo "=== starting llama-server on 127.0.0.1:$PORT ==="
-          "$LLAMA_SERVER" \
-            -m /tmp/ggufs/gemma-3-270m-it-Q4_K_M.gguf \
-            --host 127.0.0.1 \
-            --port "$PORT" \
-            -c 256 \
-            -n 16 \
-            --no-warmup \
-            > /tmp/llama-server.log 2>&1 &
-          SERVER_PID=$!
-          trap 'kill "$SERVER_PID" 2>/dev/null || true' EXIT
-
-          # Wait for /health to come up
-          for i in $(seq 1 30); do
-            if curl -sf "http://127.0.0.1:$PORT/health" >/dev/null 2>&1; then
-              echo "  server up after ${i}s"
-              break
-            fi
-            sleep 1
-          done
-          if ! curl -sf "http://127.0.0.1:$PORT/health" >/dev/null 2>&1; then
-            echo "::error::llama-server never became healthy"
-            tail -40 /tmp/llama-server.log
-            exit 1
-          fi
-
-          PROMPT="Hello, my name is"
-          echo "=== POST /completion ==="
-          RESP=$(curl -sf -X POST "http://127.0.0.1:$PORT/completion" \
-            -H 'Content-Type: application/json' \
-            -d "{\"prompt\":\"$PROMPT\",\"n_predict\":16,\"temperature\":0,\"seed\":3407}")
-          echo "raw response (head): $(echo "$RESP" | head -c 600)"
-          CONTENT=$(echo "$RESP" | python -c "import json,sys; print(json.loads(sys.stdin.read()).get('content',''))")
-          echo "completion content: $CONTENT"
-
-          if [ -z "$CONTENT" ]; then
-            echo "::error::llama-server /completion returned empty content"
-            tail -40 /tmp/llama-server.log
-            exit 1
-          fi
-          echo "OK: Unsloth prebuilt llama.cpp on Mac M1 + GGUF /completion works"

.github/workflows/notebooks-ci.yml

@@ -1,448 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-#
-# Cross-repo notebook validator. Lives in unslothai/unsloth (this repo)
-# and inspects every notebook in unslothai/notebooks at HEAD (or the
-# ref dispatched in via repository_dispatch).
-#
-# Catches the bug classes that landed in:
-#   - unslothai/notebooks#258  Colab torchao 0.10 vs peft 0.19 floor
-#   - unslothai/notebooks#260  DONT_UPDATE_EXCEPTIONS coverage drift
-#   - unslothai/notebooks#261  torch/torchcodec ABI; --no-deps tokenizers
-#   - unslothai/notebooks#264  --no-deps transformers + Colab tokenizers drift
-#   - unslothai/notebooks#221  git+ HEAD installs in install cells
-#   - unslothai/notebooks  commit 51b1462  template/notebook drift
-#
-# CPU-only by design. Layer 2 (api-introspect) reuses the existing
-# tests/_zoo_aggressive_cuda_spoof.py harness so `import unsloth`
-# succeeds on a GPU-less ubuntu-latest runner.
-
-name: Notebooks CI
-
-on:
-  pull_request:
-    paths:
-      - 'unsloth/**'
-      - 'scripts/notebook_validator.py'
-      - 'scripts/notebook_to_python.py'
-      - 'scripts/data/colab_pip_freeze.gpu.txt'
-      - 'scripts/data/colab_to_cpu_pin.json'
-      - 'tests/notebooks/**'
-      - 'tests/_zoo_aggressive_cuda_spoof.py'
-      - '.github/workflows/notebooks-ci.yml'
-  schedule:
-    # Daily 06:17 UTC. Catches Colab preinstall bumps (the upstream image
-    # is rebuilt roughly weekly) without us waiting on a PR. Off the
-    # :00/:30 fleet-collision spots.
-    - cron: '17 6 * * *'
-  workflow_dispatch:
-    inputs:
-      notebooks_ref:
-        description: 'unslothai/notebooks ref to lint (branch / SHA / tag)'
-        default: 'main'
-      include_smoke:
-        description: 'Also run the install-cell smoke matrix (longer)'
-        type: boolean
-        default: false
-  repository_dispatch:
-    # Fired by a tiny companion workflow on unslothai/notebooks.
-    types: [notebooks_pr_opened, notebooks_main_pushed]
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-env:
-  NOTEBOOKS_REF: >-
-    ${{ github.event.inputs.notebooks_ref ||
-        github.event.client_payload.ref ||
-        'main' }}
-
-jobs:
-  static:
-    name: static (drift + lint + exceptions)
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      # Validate the dispatched ref before it reaches actions/checkout's `ref:`
-      # input. Reading via env (NOT direct ${{ ... }} interpolation in the
-      # regex test) closes the GitHub-Actions-injection class where a
-      # client_payload.ref like `main"; rm -rf / #` would be embedded into the
-      # shell command. NOTEBOOKS_REF defaults to 'main' on non-dispatch
-      # events, but only repository_dispatch can supply attacker-controlled
-      # values, so we gate this check on that event type.
-      - name: Validate client_payload.ref shape
-        if: github.event_name == 'repository_dispatch'
-        env:
-          NOTEBOOKS_REF: ${{ github.event.client_payload.ref }}
-        run: |
-          if ! printf '%s' "$NOTEBOOKS_REF" | grep -Eq '^[A-Za-z0-9._/-]+$'; then
-            echo "::error::client_payload.ref contains disallowed characters" >&2
-            exit 1
-          fi
-
-      - name: Checkout unsloth (this PR)
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          path: unsloth
-          persist-credentials: false
-
-      - name: Checkout unslothai/notebooks @ ${{ env.NOTEBOOKS_REF }}
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          repository: unslothai/notebooks
-          ref: ${{ env.NOTEBOOKS_REF }}
-          path: notebooks
-          fetch-depth: 0  # drift check needs git status / diff
-          persist-credentials: false
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-
-      - name: Install validator deps
-        run: |
-          python -m pip install --upgrade pip
-          # nbformat + nbconvert come from the converter's requirements;
-          # spellchecker + huggingface_hub are imported at module top of
-          # update_all_notebooks.py.
-          pip install \
-            'nbformat>=5.10' 'nbconvert>=7.16' 'pyspellchecker>=0.8' \
-            'huggingface_hub>=0.34' 'tqdm>=4.66'
-
-      - name: Refresh Colab pip-freeze (best-effort; falls back to snapshot)
-        run: |
-          python unsloth/scripts/notebook_validator.py refresh-colab \
-              --out unsloth/scripts/data/colab_pip_freeze.gpu.txt \
-            || echo "::warning::refresh-colab failed; using committed snapshot"
-
-      - name: Diff Colab oracle vs committed snapshots (advisory)
-        # Pulls pip-freeze.gpu.txt + apt-list-gpu.txt + os-info-gpu.txt
-        # from googlecolab/backend-info and prints NEW / REMOVED /
-        # CHANGED entries against scripts/data/colab_*.txt. Non-blocking
-        # on PRs; the daily cron job below runs the same step with
-        # --strict so upstream rotations surface within ~24h.
-        continue-on-error: true
-        working-directory: ${{ github.workspace }}
-        run: |
-          python unsloth/scripts/notebook_validator.py colab-diff \
-              --snapshot-dir unsloth/scripts/data
-
-      - name: Drift check (re-run update_all_notebooks.py + git diff)
-        working-directory: ${{ github.workspace }}
-        # Reported as non-blocking until the upstream `unslothai/notebooks`
-        # tree is regenerated. The first run on @main surfaces ~463 files
-        # of drift (7359 / 9634 line delta), which is a real backlog the
-        # notebooks-side maintainers need to clear in their own repo --
-        # this PR's role is to surface the count, not auto-fix it.
-        continue-on-error: true
-        run: |
-          python unsloth/scripts/notebook_validator.py drift \
-              --notebooks-dir notebooks
-
-      - name: Convert sanity (every nb / kaggle / original_template -> .py)
-        # Same rationale as Drift: a handful of upstream notebooks fail
-        # the converter (custom magics, malformed JSON, etc). Surface
-        # the count without blocking; the team triages in unslothai/notebooks.
-        continue-on-error: true
-        run: |
-          python unsloth/scripts/notebook_validator.py convert \
-              --notebooks-dir notebooks \
-              --out _converted
-
-      - name: Lint (install cells + AST scan, env-scoped)
-        # Reported as non-blocking (continue-on-error: true) until the
-        # backlog of pre-existing findings on unslothai/notebooks@main is
-        # cleared. Same pattern PR #5298 used for biome:check on the
-        # frontend. As of this commit the live tree surfaces 27 errors +
-        # 6 warnings, all real (peft/torchao floor missing in 6 nb/
-        # notebooks, 14 git+ HEAD installs in hand-tuned exception
-        # notebooks, 6 torch/torchcodec ABI mismatches, 1
-        # transformers/tokenizers --no-deps drift). The count surfaces
-        # in the PR check UI. Drop continue-on-error once it hits zero.
-        continue-on-error: true
-        run: |
-          python unsloth/scripts/notebook_validator.py lint \
-              --notebooks-dir notebooks \
-              --colab-pin unsloth/scripts/data/colab_pip_freeze.gpu.txt \
-              --no-pypi
-        # --no-pypi skips R-INST-002 (transitive resolve via PyPI metadata).
-        # Layer 1 keeps PR-time wall-clock predictable; the daily cron run
-        # below drops --no-pypi and refreshes the cache.
-
-      - name: DONT_UPDATE_EXCEPTIONS coverage
-        run: |
-          python unsloth/scripts/notebook_validator.py exceptions \
-              --notebooks-dir notebooks
-
-  static-with-pypi:
-    name: static + transitive resolve (cron / dispatch only)
-    if: ${{ github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' }}
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      # See `static.Validate client_payload.ref shape` for rationale. This
-      # job's `if:` excludes repository_dispatch today, so the validation
-      # step is a defence-in-depth no-op until that gate ever relaxes.
-      - name: Validate client_payload.ref shape
-        if: github.event_name == 'repository_dispatch'
-        env:
-          NOTEBOOKS_REF: ${{ github.event.client_payload.ref }}
-        run: |
-          if ! printf '%s' "$NOTEBOOKS_REF" | grep -Eq '^[A-Za-z0-9._/-]+$'; then
-            echo "::error::client_payload.ref contains disallowed characters" >&2
-            exit 1
-          fi
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-          path: unsloth
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          repository: unslothai/notebooks
-          ref: ${{ env.NOTEBOOKS_REF }}
-          path: notebooks
-          persist-credentials: false
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with: { python-version: '3.12', cache: 'pip' }
-      - name: Install
-        run: pip install -U pip
-      - name: Refresh Colab oracle
-        run: |
-          python unsloth/scripts/notebook_validator.py refresh-colab \
-              --out unsloth/scripts/data/colab_pip_freeze.gpu.txt
-      - name: Diff Colab oracle vs committed snapshots (--strict on cron)
-        # Cron-only escalation of the advisory PR-time check. Fails if
-        # any of pip-freeze.gpu.txt / apt-list-gpu.txt / os-info-gpu.txt
-        # has drifted from scripts/data/colab_*.txt; refresh the
-        # snapshots in this repo to acknowledge.
-        run: |
-          python unsloth/scripts/notebook_validator.py colab-diff \
-              --snapshot-dir unsloth/scripts/data --strict
-      - name: Lint with live PyPI metadata
-        run: |
-          python unsloth/scripts/notebook_validator.py lint \
-              --notebooks-dir notebooks \
-              --colab-pin unsloth/scripts/data/colab_pip_freeze.gpu.txt
-
-  api-introspect:
-    name: api surface (under CUDA spoof)
-    runs-on: ubuntu-latest
-    timeout-minutes: 12
-    steps:
-      - name: Validate client_payload.ref shape
-        if: github.event_name == 'repository_dispatch'
-        env:
-          NOTEBOOKS_REF: ${{ github.event.client_payload.ref }}
-        run: |
-          if ! printf '%s' "$NOTEBOOKS_REF" | grep -Eq '^[A-Za-z0-9._/-]+$'; then
-            echo "::error::client_payload.ref contains disallowed characters" >&2
-            exit 1
-          fi
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-          path: unsloth
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          repository: unslothai/notebooks
-          ref: ${{ env.NOTEBOOKS_REF }}
-          path: notebooks
-          persist-credentials: false
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with: { python-version: '3.12', cache: 'pip' }
-
-      - name: Install CPU torch + pinned unsloth + trl + converter deps
-        run: |
-          python -m pip install --upgrade pip
-          # CPU torch + torchvision. torchvision is required because
-          # unsloth_zoo.vision_utils imports PIL at module top, and the
-          # easiest way to get a torch-compatible PIL on a CPU runner is
-          # to let torchvision pull the right Pillow version.
-          pip install --index-url https://download.pytorch.org/whl/cpu --extra-index-url https://pypi.org/simple \
-                      'torch>=2.8,<2.11' 'torchvision<0.26'
-          # Pin to the same versions update_all_notebooks.py installs in
-          # generated notebooks. Keep these in lockstep with PIN_TRL /
-          # PIN_TRANSFORMERS in unslothai/notebooks/update_all_notebooks.py.
-          # `triton` is added because unsloth/_gpu_init.py:232 does an
-          # unconditional `import triton`; the PyPI wheel installs cleanly
-          # on Linux x86_64 even without CUDA (same rationale as
-          # consolidated-tests-ci.yml line 192-205).
-          # Pillow is listed explicitly as a defensive belt-and-braces
-          # next to torchvision (vision_utils crashes ModuleNotFoundError
-          # if torchvision skipped its Pillow dep for any reason).
-          pip install 'transformers>=4.56,<5.6' 'trl>=0.22,<0.26' 'accelerate>=1.0' \
-                      'datasets>=3.4,<5' 'peft>=0.15,<0.20' \
-                      'bitsandbytes>=0.43' 'sentencepiece' 'protobuf' triton \
-                      Pillow safetensors tqdm packaging psutil
-          # Converter deps (nbformat for notebook_to_python.py).
-          pip install 'nbformat>=5.10' 'nbconvert>=7.16'
-          # Install unsloth from the LOCAL checkout (the PR head), not PyPI.
-          # The PR-time CI must validate the code in this PR; PyPI unsloth
-          # may lag the in-repo CPU-torch fallback in unsloth/kernels/utils.py
-          # (lines 162-170) that handles missing torch._C._cuda_getCurrentRawStream.
-          # unsloth_zoo from git main mirrors every other CI (Core / MLX /
-          # install.sh) so PR-time validation sees the same zoo HEAD.
-          for attempt in 1 2 3; do
-            if pip install --no-deps "unsloth_zoo @ git+https://github.com/unslothai/unsloth-zoo"; then
-              break
-            fi
-            [ "$attempt" -eq 3 ] && { echo "::error::unsloth_zoo install failed after 3 attempts"; exit 1; }
-            sleep $((5 * attempt))
-          done
-          pip install --no-deps -e ./unsloth
-
-      - name: Convert notebooks for AST scan
-        # Same upstream-conversion-error tolerance as the static job.
-        continue-on-error: true
-        run: |
-          python unsloth/scripts/notebook_validator.py convert \
-              --notebooks-dir notebooks --out _converted
-
-      - name: Dump unsloth + trl API surface (under CUDA spoof)
-        run: |
-          PYTHONPATH=unsloth/tests python -u - <<'PY'
-          import sys, json, inspect
-          import _zoo_aggressive_cuda_spoof as _spoof
-          _spoof.apply()
-          import unsloth
-          import trl
-          surface = {}
-          for cls_name in ("FastLanguageModel", "FastVisionModel", "FastModel"):
-              cls = getattr(unsloth, cls_name, None)
-              if cls is None:
-                  continue
-              surface[cls_name] = sorted(n for n in dir(cls) if not n.startswith("_"))
-          surface["SFTConfig_kwargs"] = sorted(inspect.signature(trl.SFTConfig.__init__).parameters)
-          json.dump(surface, open("_api_surface.json", "w"), indent=2)
-          print("dumped surface for:", list(surface))
-          PY
-
-      - name: Run API rule against converted notebooks
-        run: |
-          python unsloth/scripts/notebook_validator.py api \
-              --converted-dir _converted \
-              --surface _api_surface.json
-
-  smoke-install:
-    name: smoke install (Colab-shaped venv, opt-in)
-    if: ${{ github.event.inputs.include_smoke == 'true' || github.event_name == 'schedule' }}
-    runs-on: ubuntu-latest
-    timeout-minutes: 25
-    strategy:
-      fail-fast: false
-      matrix:
-        # One representative notebook per installation_*_content template.
-        # Add rows when a new install template lands in update_all_notebooks.py.
-        notebook:
-          - 'nb/Llama3.1_(8B)-Alpaca.ipynb'           # installation_content
-          - 'nb/Gemma3_(4B)-Vision.ipynb'             # installation_content + vision
-          - 'nb/Llama3.1_(8B)-GRPO.ipynb'             # installation_extra_grpo_content
-          - 'nb/gpt-oss-(20B)-Fine-tuning.ipynb'      # installation_gpt_oss_content
-          - 'nb/Qwen3_5_(4B)_Vision.ipynb'            # installation_qwen3_5_content
-          - 'nb/Nemotron-3-Nano-30B-A3B_A100.ipynb'   # installation_nemotron_nano_content
-          - 'nb/Whisper.ipynb'                         # installation_whisper_content
-          - 'nb/Synthetic_Data_Hackathon.ipynb'        # installation_synthetic_data_content
-    steps:
-      - name: Validate client_payload.ref shape
-        if: github.event_name == 'repository_dispatch'
-        env:
-          NOTEBOOKS_REF: ${{ github.event.client_payload.ref }}
-        run: |
-          if ! printf '%s' "$NOTEBOOKS_REF" | grep -Eq '^[A-Za-z0-9._/-]+$'; then
-            echo "::error::client_payload.ref contains disallowed characters" >&2
-            exit 1
-          fi
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-          path: unsloth
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          repository: unslothai/notebooks
-          ref: ${{ env.NOTEBOOKS_REF }}
-          path: notebooks
-          persist-credentials: false
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with: { python-version: '3.12' }
-
-      - name: Seed Colab-shaped venv from pip-freeze (CPU-mapped)
-        run: |
-          # Strip cu128 local versions, route torch/torchvision to the CPU
-          # wheel index, drop CUDA-specific deps the runner can't use.
-          python -u - <<'PY' > /tmp/seed_pins.txt
-          import json, re
-          mapping = json.load(open("unsloth/scripts/data/colab_to_cpu_pin.json"))
-          rewrite = mapping["rewrite"]
-          skip = set(mapping["skip"])
-          spoof = set(mapping["module_spoof"])
-          out = []
-          for line in open("unsloth/scripts/data/colab_pip_freeze.gpu.txt"):
-              line = line.strip()
-              if not line or line.startswith("#"):
-                  continue
-              m = re.match(r"^([A-Za-z0-9._-]+)\s*==\s*(.+)$", line)
-              if not m:
-                  continue
-              name, ver = m.group(1).lower(), m.group(2)
-              if name in skip:
-                  continue
-              if name in spoof:
-                  continue
-              if name in rewrite:
-                  ver = re.sub(r"[+\-].+$", "", ver)
-                  out.append(f"{name}=={ver}")
-              else:
-                  ver = re.sub(r"[+\-].+$", "", ver)
-                  out.append(f"{name}=={ver}")
-          print("\n".join(out))
-          PY
-          head -5 /tmp/seed_pins.txt
-          wc -l /tmp/seed_pins.txt
-
-      - name: Install Colab-shaped venv
-        run: |
-          python -m pip install --upgrade pip
-          # Best-effort: any single line that fails to resolve on CPU is
-          # tolerated; the smoke contract is "the install cell + the unsloth
-          # import works", not "the entire Colab venv reproduces."
-          while IFS= read -r spec; do
-            pip install "$spec" --index-url https://download.pytorch.org/whl/cpu \
-              --extra-index-url https://pypi.org/simple || \
-              echo "::warning::pin failed: $spec"
-          done < /tmp/seed_pins.txt
-
-      - name: Run install cell
-        run: |
-          python unsloth/scripts/notebook_validator.py convert \
-              --notebooks-dir notebooks --out _converted
-          # Take the converted .py and run the install cell only.
-          BASE="$(basename '${{ matrix.notebook }}' .ipynb | tr -d '()' | tr -c '[:alnum:]_' _)"
-          PY="_converted/${BASE}.py"
-          [ -f "$PY" ] || { echo "::error::$PY not found"; ls _converted | head; exit 1; }
-          # Truncate at the first `from unsloth import` so we run install +
-          # core imports only.
-          awk '/^from unsloth import/ { print "import sys; sys.exit(0)"; exit } { print }' "$PY" > _smoke.py
-          PYTHONPATH=unsloth/tests python -u - <<'PY'
-          import _zoo_aggressive_cuda_spoof as _s; _s.apply()
-          # Stub torchcodec for cells that import it — no CPU wheel exists.
-          import sys, types
-          if "torchcodec" not in sys.modules:
-              sys.modules["torchcodec"] = types.ModuleType("torchcodec")
-          exec(open("_smoke.py").read(), {"__name__": "__main__"})
-          PY
-
-      - name: Verify imports under spoof
-        run: |
-          PYTHONPATH=unsloth/tests python -u - <<'PY'
-          import sys, types
-          if "torchcodec" not in sys.modules:
-              sys.modules["torchcodec"] = types.ModuleType("torchcodec")
-          import _zoo_aggressive_cuda_spoof as _s; _s.apply()
-          import unsloth, peft, torch, torchao, transformers, tokenizers
-          print("OK: imports pass under CUDA spoof")
-          PY

.github/workflows/ossf.yml

@@ -1,78 +0,0 @@
-# This workflow uses actions that are not certified by GitHub. They are provided
-# by a third-party and are governed by separate terms of service, privacy
-# policy, and support documentation.
-
-name: Scorecard supply-chain security
-on:
-  # For Branch-Protection check. Only the default branch is supported. See
-  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection
-  branch_protection_rule:
-  # To guarantee Maintained check is occasionally updated. See
-  # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained
-  schedule:
-    - cron: '21 20 * * 0'
-  push:
-    branches: [ "main" ]
-
-# Declare default permissions as read only.
-permissions: read-all
-
-jobs:
-  analysis:
-    name: Scorecard analysis
-    runs-on: ubuntu-latest
-    # `publish_results: true` only works when run from the default branch. conditional can be removed if disabled.
-    if: github.event.repository.default_branch == github.ref_name || github.event_name == 'pull_request'
-    permissions:
-      # Needed to upload the results to code-scanning dashboard.
-      security-events: write
-      # Needed to publish results and get a badge (see publish_results below).
-      id-token: write
-      # Uncomment the permissions below if installing in a private repository.
-      # contents: read
-      # actions: read
-
-    steps:
-      - name: "Checkout code"
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          persist-credentials: false
-
-      - name: "Run analysis"
-        uses: ossf/scorecard-action@f49aabe0b5af0936a0987cfb85d86b75731b0186 # v2.4.1
-        with:
-          results_file: results.sarif
-          results_format: sarif
-          # (Optional) "write" PAT token. Uncomment the `repo_token` line below if:
-          # - you want to enable the Branch-Protection check on a *public* repository, or
-          # - you are installing Scorecard on a *private* repository
-          # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action?tab=readme-ov-file#authentication-with-fine-grained-pat-optional.
-          # repo_token: ${{ secrets.SCORECARD_TOKEN }}
-
-          # Public repositories:
-          #   - Publish results to OpenSSF REST API for easy access by consumers
-          #   - Allows the repository to include the Scorecard badge.
-          #   - See https://github.com/ossf/scorecard-action#publishing-results.
-          # For private repositories:
-          #   - `publish_results` will always be set to `false`, regardless
-          #     of the value entered here.
-          publish_results: true
-
-          # (Optional) Uncomment file_mode if you have a .gitattributes with files marked export-ignore
-          # file_mode: git
-
-      # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
-      # format to the repository Actions tab.
-      - name: "Upload artifact"
-        uses: actions/upload-artifact@4cec3d8aa04e39d1a68397de0c4cd6fb9dce8ec1 # v4.6.1
-        with:
-          name: SARIF file
-          path: results.sarif
-          retention-days: 5
-
-      # Upload the results to GitHub's code scanning dashboard (optional).
-      # Commenting out will disable upload of results to your repo's Code Scanning dashboard
-      - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@v3
-        with:
-          sarif_file: results.sarif

.github/workflows/stale.yml

@@ -11,7 +11,7 @@ jobs:
       issues: write
 
     steps:
-      - uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f  # v10.2.0
+      - uses: actions/stale@v10
         with:
           # The message to post on stale issues.
           # This message will ping the issue author.

.github/workflows/startup-profile-ci.yml

@@ -1,156 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Measures where Studio's startup time goes, on each platform.
-#
-# Nothing recorded a number before: main.py logs "lifespan startup completed in X ms"
-# and studio_test_kit polls /healthz, but both throw the elapsed time away. A first
-# local run (Linux, warm cache, 18-core server) put `import main` at 5.7-6.6s BEFORE
-# the server can bind, dominated by eager module-level imports pulled in by routes:
-# torch ~1.9s self, unsloth_zoo ~0.8s, routes ~0.6s, transformers ~0.5s.
-#
-# Not a gate yet: --max-healthz-seconds exists, but a budget should come from
-# observed numbers rather than a guess.
-
-name: Startup profile
-
-on:
-  pull_request:
-    paths:
-      # The measured import graph is the whole backend tree: main.py imports auth,
-      # core, hub, loggers, models, picker, routes and utils at module scope.
-      - 'studio/backend/**'
-      - '!studio/backend/tests/**'
-      # The launch phase spawns `unsloth studio --api-only`, so the CLI counts too.
-      - 'unsloth_cli/**'
-      - 'studio/src-tauri/src/preflight**'
-      # The profiler hardcodes the desktop argv that process.rs::backend_args builds,
-      # so a change there must schedule a run or the two silently diverge.
-      - 'studio/src-tauri/src/process.rs'
-      - 'scripts/profile_startup.py'
-      - '.github/workflows/startup-profile-ci.yml'
-      # The job profiles whatever `install.sh --local` built: the installers pick the
-      # venv's Python and the dependency specs, and pyproject's include list is what
-      # makes --local overlay studio.backend*.
-      - 'install.sh'
-      - 'install.ps1'
-      - 'pyproject.toml'
-      # --local also runs the checkout's setup scripts (install.sh picks
-      # $_REPO_ROOT/studio/setup.sh, the editable install resolves setup.ps1 to the
-      # repo), and both call install_python_stack.py, which picks the dependencies.
-      - 'studio/setup.sh'
-      - 'studio/setup.ps1'
-      - 'studio/install_python_stack.py'
-  workflow_dispatch:
-    inputs:
-      repeats:
-        description: 'launch repeats per OS (median reported)'
-        type: string
-        default: '3'
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  profile:
-    name: startup ${{ matrix.os }}
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 60
-    continue-on-error: true
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-14, windows-latest]
-
-    env:
-      UNSLOTH_STUDIO_HOME: ${{ github.workspace }}/.studio-home
-      # A wildcard bind calls ifconfig.me on the startup path; loopback times our code.
-      UNSLOTH_STUDIO_DISABLE_PUBLIC_CHECK: '1'
-
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - name: Install Studio
-        shell: bash
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          set -o pipefail
-          mkdir -p logs
-          # --local is load-bearing: it overlays the checkout, so the profiled server
-          # is this diff. Without it install.sh resolves unsloth from PyPI.
-          if [ "${{ runner.os }}" = "Windows" ]; then
-            pwsh -NoProfile -File ./install.ps1 --local 2>&1 | tee logs/install.log
-          else
-            bash install.sh --local 2>&1 | tee logs/install.log
-          fi
-
-      - name: Profile startup
-        shell: bash
-        run: |
-          BIN="$UNSLOTH_STUDIO_HOME/unsloth_studio/bin/unsloth"
-          [ -x "$BIN" ] || BIN="$UNSLOTH_STUDIO_HOME/unsloth_studio/Scripts/unsloth.exe"
-          [ -x "$BIN" ] || BIN=""
-          # Profile imports with the INSTALLED interpreter: that venv is what launches.
-          PY="$UNSLOTH_STUDIO_HOME/unsloth_studio/bin/python"
-          [ -x "$PY" ] || PY="$UNSLOTH_STUDIO_HOME/unsloth_studio/Scripts/python.exe"
-          [ -x "$PY" ] || PY="$(command -v python3 || command -v python)"
-          python3 scripts/profile_startup.py \
-            --python "$PY" \
-            ${BIN:+--bin "$BIN"} \
-            --repeats "${{ inputs.repeats || '3' }}" \
-            --json "startup-${{ matrix.os }}.json" 2>&1 | tee logs/profile.log
-
-      - name: Summary
-        if: always()
-        shell: bash
-        run: |
-          f="startup-${{ matrix.os }}.json"
-          [ -f "$f" ] || { echo "no profile produced"; exit 0; }
-          python3 - "$f" >> "$GITHUB_STEP_SUMMARY" <<'PY'
-          import json, sys
-          d = json.load(open(sys.argv[1]))
-          print(f"### {d['platform']} / {d['machine']} (py {d['python']}, {d['cpu_count']} cpu)\n")
-          imp = d.get("imports", {})
-          # Gate on ok: a failed `import main` still leaves rows, so a total can lie.
-          if imp.get("ok"):
-              print(f"**`import main`: {imp['total_seconds']}s**\n")
-              print("| package | self ms |")
-              print("|---|---:|")
-              for k, v in list(imp.get("self_by_package_ms", {}).items())[:8]:
-                  print(f"| {k} | {v} |")
-              print()
-          else:
-              print("**`import main` failed - no valid import profile**\n")
-              print("```\n" + (imp.get("error") or "")[-1500:] + "\n```\n")
-          lau = d.get("launch") or {}
-          runs = len(lau.get("runs") or [])
-          failed = lau.get("failed_runs") or 0
-          if lau.get("healthz_median_seconds") is not None:
-              # The aggregates cover only the runs that reached healthz, so flag the
-              # failures: bare numbers would read as a normal fast startup.
-              note = f" _({runs - failed} of {runs} launches; {failed} never became healthy)_" if failed else ""
-              print(f"**time to a healthy port: {lau['healthz_median_seconds']}s median, "
-                    f"{lau['healthz_max_seconds']}s max**{note}\n")
-          elif lau.get("skipped"):
-              print(f"_launch phase skipped: {lau['skipped']}_\n")
-          elif runs:
-              print(f"**no launch measurement: all {runs} launches failed to become healthy**\n")
-          PY
-
-      - name: Upload profile
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: startup-profile-${{ matrix.os }}
-          path: |
-            startup-*.json
-            logs/
-          retention-days: 14
-          if-no-files-found: warn

.github/workflows/studio-api-smoke.yml

@@ -1,171 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Unsloth API & Auth Tests -- HTTP-level integration tests for the
-# FastAPI surface. No Playwright, no model UI; tests/studio/test_studio_api_smoke.py
-# runs ~30 s and asserts:
-#   - CORS hardening (no wildcard + credentials, no bootstrap leak)
-#   - /api/system + /api/system/hardware require auth
-#   - Auth state machine + JWT expiry
-#   - API key lifecycle E2E (create / list / use / delete / reject)
-#   - Auth file-mode hardening (Linux only)
-#   - Inference lifecycle (force reload, bogus variant, /v1/models, /v1/embeddings, /v1/responses)
-#   - Endpoint-by-endpoint auth audit
-#
-# Reuses the GGUF cache key from studio-ui-smoke.yml so the model
-# download is one cache-hit on the second job.
-
-name: Unsloth API CI
-
-on:
-  pull_request:
-    paths:
-      - 'studio/**'
-      - 'unsloth/**'
-      - 'unsloth_cli/**'
-      - 'install.sh'
-      - 'pyproject.toml'
-      - 'tests/studio/**'
-      - '.github/workflows/studio-api-smoke.yml'
-  push:
-    branches: [main, pip]
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  api-smoke:
-    name: Unsloth API & Auth Tests
-    runs-on: ubuntu-latest
-    timeout-minutes: 12
-    env:
-      GGUF_REPO: unsloth/gemma-3-270m-it-GGUF
-      GGUF_VARIANT: UD-Q4_K_XL
-      GGUF_FILE: gemma-3-270m-it-UD-Q4_K_XL.gguf
-      STUDIO_PORT: '18893'
-      HF_HOME: ${{ github.workspace }}/hf-cache
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - name: Linux deps
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y --no-install-recommends \
-            libcurl4-openssl-dev libssl-dev jq
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: '22'
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-
-      - name: Restore HF_HOME for ${{ env.GGUF_REPO }}
-        id: cache-hf
-        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        continue-on-error: true
-        with:
-          path: hf-cache
-          # Same key as studio-ui-smoke.yml so the two jobs share a
-          # single GGUF download across CI.
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
-
-      - name: Prime HF_HOME with the GGUF
-        id: prime-hf
-        if: steps.cache-hf.outputs.cache-hit != 'true' || steps.cache-hf.outcome != 'success'
-        env:
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          python -m pip install --upgrade huggingface_hub
-          mkdir -p hf-cache
-          bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
-          bash .github/scripts/hf-download-with-retry.sh ggml-org/models tinyllamas/stories260K.gguf
-
-      - name: Save HF_HOME for ${{ env.GGUF_REPO }}
-        if: always() && steps.prime-hf.outcome == 'success'
-        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        with:
-          path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
-
-      - name: Install Unsloth (--local, --no-torch)
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          mkdir -p logs
-          set -o pipefail
-          bash install.sh --local --no-torch 2>&1 | tee logs/install.log
-
-      - name: Install pyjwt for the JWT-expiry forge test
-        run: pip install 'pyjwt>=2.6'
-
-      - name: Reset auth + boot Unsloth (API-only)
-        run: |
-          # Wipe (not reset-password): the boot below must re-seed a fresh .bootstrap_password.
-          rm -rf ~/.unsloth/studio/auth
-          mkdir -p logs
-          UNSLOTH_API_ONLY=1 unsloth studio -H 127.0.0.1 -p "$STUDIO_PORT" \
-            > logs/studio.log 2>&1 &
-          echo "STUDIO_PID=$!" >> "$GITHUB_ENV"
-
-      - name: Wait for /api/health
-        run: |
-          for i in $(seq 1 180); do
-            if curl -fs "http://127.0.0.1:${STUDIO_PORT}/api/health" > /tmp/health.json; then
-              jq -e '.status == "healthy"' /tmp/health.json && break
-            fi
-            sleep 1
-          done
-          jq -e '.status == "healthy"' /tmp/health.json
-
-      - name: Pass bootstrap password + rotated targets to the test
-        # The test does its own bootstrap-login + rotation to exercise
-        # the auth state machine; we just pre-mint two random rotated
-        # passwords for it. Mask them so the log is clean.
-        run: |
-          OLD=$(cat ~/.unsloth/studio/auth/.bootstrap_password)
-          NEW="ApiSmoke-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-          NEW2="ApiSmoke-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-          echo "::add-mask::$OLD"
-          echo "::add-mask::$NEW"
-          echo "::add-mask::$NEW2"
-          echo "STUDIO_OLD_PW=$OLD"  >> "$GITHUB_ENV"
-          echo "STUDIO_NEW_PW=$NEW"  >> "$GITHUB_ENV"
-          echo "STUDIO_NEW2_PW=$NEW2" >> "$GITHUB_ENV"
-
-      - name: Run Unsloth API & Auth tests
-        # The script is named WITHOUT a `test_` prefix so it isn't
-        # auto-collected by pytest in Backend CI's `tests/` walk
-        # (which doesn't set BASE_URL and would crash at import).
-        env:
-          BASE_URL: http://127.0.0.1:18893
-          STUDIO_AUTH_DIR: /home/runner/.unsloth/studio/auth
-        run: python tests/studio/studio_api_smoke.py
-
-      - name: Stop Unsloth
-        if: always()
-        run: |
-          kill "${STUDIO_PID}" 2>/dev/null || true
-          sleep 2
-
-      - name: Upload API smoke logs
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: studio-api-smoke-log
-          path: |
-            logs/install.log
-            logs/studio.log
-          retention-days: 7

.github/workflows/studio-backend-ci.yml

@@ -1,265 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Runs the existing studio/backend/tests/ suite (~860 tests, all CPU-friendly)
-# on every PR that touches the backend or unsloth library. Until this lands,
-# none of those tests run automatically. Verified locally on Python 3.13 with
-# the surgical exclusions below: 861 pass, 4 skipped.
-#
-# Exclusions:
-#   - tests/test_studio_api.py: end-to-end against a live model + GGUF download,
-#     too heavy for free runners. Run separately when GPU CI is available.
-#   - -k 'not llama_cpp_load_progress_live': spawns a real llama.cpp process,
-#     not appropriate for CPU-only runners.
-#
-# Two jobs:
-#   - pytest matrix (3.10/3.11/3.12/3.13) over studio/backend/tests
-#   - repo-cpu-tests: auto-discovered tests/ + state-isolated spoof files
-#
-# Whole-repo Python lint (syntax + ruff + debugger-leftover scan)
-# moved to the dedicated `Lint CI` workflow (.github/workflows/lint-ci.yml)
-# so it fires on every PR rather than only on studio/unsloth/tests
-# path changes.
-
-name: Backend CI
-
-on:
-  pull_request:
-    paths:
-      - 'studio/**'
-      - 'unsloth/**'
-      - 'unsloth_cli/**'
-      - 'tests/**'
-      # The root installers: tests/sh/*.sh and tests/studio/install/* assert
-      # against these two files, so a change here must run the suite that
-      # covers it. Without them an install-only edit (the shape most AMD/ROCm
-      # routing fixes take) skipped Backend CI entirely.
-      - 'install.sh'
-      - 'install.ps1'
-      - 'scripts/**'
-      - 'pyproject.toml'
-      - '.github/workflows/studio-backend-ci.yml'
-  push:
-    branches: [main, pip]
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  pytest:
-    name: (Python ${{ matrix.python }})
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    strategy:
-      fail-fast: false
-      matrix:
-        python: ['3.10', '3.11', '3.12', '3.13']
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '${{ matrix.python }}'
-          cache: 'pip'
-
-      - name: Install backend test dependencies (CPU only)
-        run: |
-          python -m pip install --upgrade pip
-          # Unsloth's declared backend deps:
-          pip install -r studio/backend/requirements/studio.txt
-          # Extras that studio.txt does not list but the import chain needs
-          # (python-multipart for FastAPI form/file uploads, sqlalchemy/cryptography
-          #  for the auth DB, yaml/jinja2 for utils.models.model_config, psutil for
-          #  the orphan-cleanup process scan, etc.):
-          pip install \
-            python-multipart aiofiles sqlalchemy cryptography psutil \
-            pyyaml jinja2 mammoth unpdf requests \
-            'numpy<3' pytest pytest-asyncio httpx
-          # Torch CPU + transformers are required by a chunk of the backend test
-          # suite (gpu_selection, kv_cache_estimation, utils). CPU-only torch
-          # keeps the install ~250 MB / ~1 min on a clean runner.
-          pip install --index-url https://download.pytorch.org/whl/cpu --extra-index-url https://pypi.org/simple 'torch>=2.4,<2.11'
-          pip install 'transformers>=4.51,<5.5'
-
-      - name: Backend tests
-        working-directory: studio/backend
-        # Locally validated against this dep set: 831 passed, 5 skipped, 35 deselected.
-        # Deselections (all environment-specific, would never pass on a GPU-less
-        # `ubuntu-latest` runner regardless of code correctness):
-        #   - llama_cpp_load_progress_live: spawns a real llama.cpp process
-        #   - TestGpuAutoSelection / TestPreSpawnGpuResolution / TestPerGpuFitGuardAllCounts:
-        #       require live transformers config introspection on real GPUs
-        #   - TestTransformersIntrospection: same
-        #   - test_returns_cuda_when_cuda_available / test_calls_cuda_cache_when_cuda:
-        #       assume CUDA-capable GPU
-        run: |
-          python -m pytest tests/ -q --tb=short \
-            --ignore=tests/test_studio_api.py \
-            -k 'not llama_cpp_load_progress_live and not TestGpuAutoSelection and not TestPreSpawnGpuResolution and not TestPerGpuFitGuardAllCounts and not TestTransformersIntrospection and not test_returns_cuda_when_cuda_available and not test_calls_cuda_cache_when_cuda'
-
-  repo-cpu-tests:
-    # Auto-discover everything under tests/ that is not GPU-bound by
-    # design. New tests added in covered directories are picked up
-    # without a workflow edit. Locally validated: 760 passed, 1 skipped,
-    # 23 deselected. tests/conftest.py (mirroring unsloth-zoo PR #624)
-    # pre-loads unsloth_zoo.device_type and unsloth.device_type under a
-    # mocked torch.cuda.is_available so the unsloth import chain
-    # succeeds on CPU.
-    name: Repo tests (CPU)
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-
-      # node + uv unlock ~60 tests that previously skipped on CI:
-      #   - 9 tests in test_chat_preset_builtin_invariants.py need node to
-      #     compile a tiny TS harness against the frontend chat sources.
-      #   - tests/python/* spawn fresh `uv venv`s to verify the no-torch
-      #     install path; they self-skip when uv is missing.
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: '22'
-
-      - name: Install uv (for tests/python/* sandboxed venvs)
-        run: pip install uv
-
-      - name: Install deps (shared shape with backend pytest job)
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r studio/backend/requirements/studio.txt
-          pip install \
-            python-multipart aiofiles sqlalchemy cryptography psutil \
-            pyyaml jinja2 mammoth unpdf requests typer \
-            'numpy<3' pytest pytest-asyncio httpx
-          # torchvision: unsloth_zoo.vision_utils imports it at module scope.
-          pip install --index-url https://download.pytorch.org/whl/cpu --extra-index-url https://pypi.org/simple \
-            'torch>=2.4,<2.11' 'torchvision<0.26'
-          pip install 'transformers>=4.51,<5.5'
-          # bitsandbytes: hard import in unsloth/models/_utils.py. Recent
-          # versions ship a CPU build that imports cleanly on Linux.
-          pip install 'bitsandbytes>=0.45'
-          # unsloth.device_type imports unsloth_zoo.utils.Version at module
-          # scope, so the conftest preload needs unsloth_zoo. Pull from
-          # git main so this job sees the same zoo HEAD as Core / MLX /
-          # install.sh do (otherwise a fix on zoo main hides until release).
-          # No --no-deps: matches prior `pip install 'unsloth_zoo>=2026.5.1'`
-          # behaviour so triton etc. still come in for the Repo tests CPU
-          # collection imports.
-          for attempt in 1 2 3; do
-            if pip install "unsloth_zoo @ git+https://github.com/unslothai/unsloth-zoo"; then
-              break
-            fi
-            [ "$attempt" -eq 3 ] && { echo "::error::unsloth_zoo install failed after 3 attempts"; exit 1; }
-            sleep $((5 * attempt))
-          done
-          pip install -e . --no-deps
-
-      - name: Repo tests (CPU, auto-discovered)
-        env:
-          # tests/python/* import install_python_stack from studio/.
-          PYTHONPATH: ${{ github.workspace }}/studio
-          # Skip lazy compilation work the unsloth import chain wants to
-          # do at import time on a real GPU.
-          UNSLOTH_COMPILE_DISABLE: '1'
-        # --ignore: GPU-bound directories (qlora/saving need real weights;
-        #   tests/sh is the shell suite the next step handles; tests/utils
-        #   is a helpers folder); tests/vllm_compat + tests/version_compat
-        #   are dedicated multi-version drift canaries with their own job
-        #   in version-compat-ci.yml that installs the heavier dep set
-        #   (torchcodec, full transformers/peft/bnb pins) those tests need.
-        # State-sensitive hardware-spoofing files run in isolation in the
-        # next step because they mutate hardware.py module globals.
-        # -m: honour markers from tests/python/conftest.py (`server` =
-        #   needs studio venv, `e2e` = needs network).
-        # --deselect:
-        #   - test_model_registration / test_all_model_registration:
-        #     hit huggingface_hub for live model existence checks.
-        #   - test_autoconfig_works_with_no_torch_runtime / test_autoconfig_succeeds:
-        #     fail because no-torch-runtime.txt does not pin tokenizers
-        #     and the latest tokenizers (0.23.1) is incompatible with the
-        #     transformers it resolves to. Tracked separately; this is a
-        #     real bug in the no-torch install path, not a CI issue.
-        run: |
-          python -m pytest tests/ -q --tb=short \
-            --ignore=tests/qlora \
-            --ignore=tests/saving \
-            --ignore=tests/utils \
-            --ignore=tests/sh \
-            --ignore=tests/studio/test_hardware_dispatch_matrix.py \
-            --ignore=tests/studio/test_is_mlx_dispatch_gate.py \
-            --ignore=tests/studio/test_xpu_spoof_pipeline.py \
-            --ignore=tests/vllm_compat \
-            --ignore=tests/version_compat \
-            -m 'not server and not e2e' \
-            --deselect tests/test_model_registry.py::test_model_registration \
-            --deselect tests/test_model_registry.py::test_all_model_registration \
-            --deselect 'tests/python/test_tokenizers_and_torch_constraint.py::TestE2ETokenizersFix::test_autoconfig_works_with_no_torch_runtime' \
-            --deselect 'tests/python/test_tokenizers_and_torch_constraint.py::TestE2EFullNoTorchSandbox::test_autoconfig_succeeds'
-
-      - name: Hardware-spoof tests (state-sensitive, run in isolation)
-        env:
-          PYTHONPATH: ${{ github.workspace }}/studio
-          UNSLOTH_COMPILE_DISABLE: '1'
-        # These files mutate hardware.py module globals at runtime via the
-        # spoof fixtures (CUDA/ROCm/XPU/MLX/CPU), which leaks state into any
-        # other test that imports hardware. Run them in their own pytest
-        # invocation so the leak does not cross file boundaries.
-        run: |
-          python -m pytest -q --tb=short \
-            tests/studio/test_hardware_dispatch_matrix.py \
-            tests/studio/test_is_mlx_dispatch_gate.py \
-            tests/studio/test_xpu_spoof_pipeline.py
-
-      - name: CLI tests (unsloth_cli)
-        # unsloth_cli/tests had no CI at all: `unsloth_cli/**` was only a paths
-        # trigger and a ruff target, so 673 tests covering the studio launcher,
-        # the pre-exposure gate and the auth secret writers ran nowhere, and
-        # four of them had been failing on main unnoticed.
-        # Own step, not folded into the tests/ discovery above: pyproject's
-        # testpaths is tests/, and this suite needs no PYTHONPATH or CUDA spoof
-        # (it self-bootstraps sys.path and imports neither unsloth nor torch).
-        run: python -m pytest unsloth_cli/tests -q --tb=short
-
-      - name: Shell installer tests
-        # Auto-discovered rather than allowlisted. The old hardcoded list had
-        # silently fallen seven files behind tests/run_all.sh, including
-        # test_strixhalo_wsl_reroute.sh -- the only shell coverage of the ROCm
-        # WSL reroute -- so that suite never ran on a PR. Skips are explicit,
-        # each with a reason, and tests/studio/test_ci_shell_suite_coverage.py
-        # fails if this step stops discovering the directory or the skip list
-        # grows without one.
-        #
-        # Skipped:
-        #   test_install_host_defaults.sh: asserts an install.ps1 layout that
-        #     has drifted (separate followup).
-        #   test_install_rollback_lifecycle.sh: already runs on both platforms
-        #     in cross-platform-parity-ci.yml.
-        run: |
-          set -e
-          skip="test_install_host_defaults.sh test_install_rollback_lifecycle.sh"
-          found=0
-          for s in tests/sh/test_*.sh; do
-              case " $skip " in
-                  *" $(basename "$s") "*) echo "skipping $s (see workflow comment)"; continue ;;
-              esac
-              found=$((found + 1))
-              echo "::group::$s"
-              bash "$s"
-              echo "::endgroup::"
-          done
-          [ "$found" -gt 0 ] || { echo "::error::no shell tests discovered under tests/sh"; exit 1; }
-          echo "ran $found shell installer test files"
-

.github/workflows/studio-export-capability-ci.yml

@@ -1,76 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Runs studio/backend/tests/test_export_capability.py on Linux, Windows and macOS.
-#
-# export_capability() is per-OS (is_apple_silicon() and the PyTorch-import probe differ per
-# platform) and the export backend must import without PyTorch, so this confirms the gating and
-# import-safety on hosted Windows/macOS. Hosted runners have no GPU/MLX, so a real accelerator
-# export is validated separately. No GPU / model / llama.cpp: the tests mock the probes and block
-# torch/unsloth, so the job installs only a CPU PyTorch plus import deps.
-
-name: Unsloth export capability
-
-on:
-  pull_request:
-    paths:
-      - 'studio/backend/utils/hardware/hardware.py'
-      - 'studio/backend/core/export/export.py'
-      - 'studio/backend/routes/export.py'
-      - 'studio/backend/main.py'
-      - 'studio/backend/tests/test_export_capability.py'
-      - '.github/workflows/studio-export-capability-ci.yml'
-  push:
-    branches: [main]
-    paths:
-      - 'studio/backend/utils/hardware/hardware.py'
-      - 'studio/backend/core/export/export.py'
-      - 'studio/backend/routes/export.py'
-      - 'studio/backend/main.py'
-      - 'studio/backend/tests/test_export_capability.py'
-      - '.github/workflows/studio-export-capability-ci.yml'
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  capability:
-    name: capability (${{ matrix.os }})
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, windows-latest, macos-latest]
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 20
-    env:
-      # No accelerator on hosted runners; keep detection on the CPU path.
-      CUDA_VISIBLE_DEVICES: ""
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-      - name: Upgrade pip
-        run: python -m pip install --upgrade pip
-      - name: Install CPU PyTorch
-        # CPU wheel index so every OS gets a CPU build; keep PyPI as an extra index so torch's
-        # transitive deps still resolve (matching the other workflows in this repo).
-        run: python -m pip install --index-url https://download.pytorch.org/whl/cpu --extra-index-url https://pypi.org/simple "torch>=2.4,<2.13"
-      - name: Install backend import deps
-        # Enough to import utils.hardware and core.export.export; NOT unsloth (needs a GPU, and
-        # the import-safety test blocks it) or triton/llama.cpp (Linux-only / native builds).
-        run: python -m pip install
-          transformers peft accelerate safetensors huggingface_hub datasets
-          sentencepiece protobuf fastapi starlette structlog psutil
-          python-multipart pydantic httpx "numpy<3" pytest
-      - name: Export capability + import-safety tests
-        working-directory: studio/backend
-        run: python -m pytest tests/test_export_capability.py -q

.github/workflows/studio-frontend-ci.yml

@@ -1,178 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Frontend PR gate: lockfile freshness, typecheck, build, and a bundle grep
-# that catches the 2026.5.1 chat-history regression at the JS level.
-#
-# biome runs as non-blocking for now: the codebase currently has accumulated
-# ~470 errors and ~1650 warnings against the existing biome config. Surfacing
-# the count in CI lets us drive it down without forcing a fleet-wide cleanup
-# in the same PR. Drop `continue-on-error` once that number is zero.
-
-name: Frontend CI
-
-on:
-  pull_request:
-    paths:
-      - 'studio/frontend/**'
-      - 'scripts/check_frontend_dep_removal.py'
-      - 'tests/studio/test_frontend_dep_removal.py'
-      - 'scripts/sync_allow_scripts_pins.py'
-      - 'tests/studio/test_sync_allow_scripts_pins.py'
-      - '.github/workflows/studio-frontend-ci.yml'
-  push:
-    branches: [main, pip]
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  build:
-    name: Frontend build + bundle sanity
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    defaults:
-      run:
-        working-directory: studio/frontend
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      # FIXME: drop this step once @assistant-ui/* and assistant-stream
-      # leave 0.x -- on 1.x, caret ranges are conventional. Until then,
-      # every 0.minor on this surface is a SemVer-major (this is exactly
-      # how 2026.5.1 shipped a broken chat runtime: ^0.12.19 quietly
-      # resolved to 0.12.28).
-      - name: '@assistant-ui must be pinned exactly (no caret/tilde)'
-        working-directory: ${{ github.workspace }}
-        run: |
-          set -e
-          if grep -nE '"(@assistant-ui/[a-z-]+|assistant-stream)":[[:space:]]*"[\^~]' studio/frontend/package.json; then
-            echo "::error file=studio/frontend/package.json::These packages must be pinned to exact versions until they leave 0.x. Drop the leading ^ or ~."
-            exit 1
-          fi
-          echo "All assistant-ui packages are pinned exactly."
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: '22'
-
-      # node 22 bundles npm 10.x, which predates allowScripts. Move to the
-      # 11.x line and fail loudly if the gate is still missing, so the
-      # strict flag below can never silently degrade into a warning.
-      - name: Upgrade npm to 11.x (allowScripts enforcement)
-        working-directory: ${{ github.workspace }}
-        run: |
-          npm install -g npm@^11 --no-fund --no-audit
-          V=$(npm -v)
-          case "$V" in
-            11.1[6-9].*|11.[2-9][0-9].*|1[2-9].*) echo "npm $V has allowScripts" ;;
-            *) echo "::error::npm $V lacks allowScripts (need >=11.16)"; exit 1 ;;
-          esac
-
-      # Run the structural lockfile scan BEFORE npm ci. A compromised
-      # tarball runs its `prepare` / `postinstall` during `npm ci`,
-      # so any catch has to fire upstream of that. The scanner is
-      # pure-Python read-only; safe to call ahead of every install.
-      - name: Lockfile supply-chain audit (pre-install scan)
-        working-directory: ${{ github.workspace }}
-        run: python3 scripts/lockfile_supply_chain_audit.py
-
-      # Dependency bumps strand the version-pinned allowScripts entries.
-      # The paired pre-commit hook auto-fixes PRs; this is the backstop.
-      - name: allowScripts pins must match the lockfile
-        working-directory: ${{ github.workspace }}
-        run: |
-          python3 tests/studio/test_sync_allow_scripts_pins.py
-          python3 scripts/sync_allow_scripts_pins.py --check
-
-      - name: Lockfile must agree with package.json (npm ci is strict)
-        # The vite 8 chain (rolldown, lightningcss, tailwind oxide) ships napi
-        # binaries with no install scripts. The only script-bearing deps are
-        # covered by `allowScripts` in package.json (npm >=11.16, default in
-        # npm 12). The pre-install lockfile audit above stays the first line
-        # of defence -- it fires before any tarball can run code.
-        # --strict-allow-scripts: any unreviewed install script hard-fails
-        # the job; the sync hook keeps the pins fresh after bumps.
-        run: npm ci --strict-allow-scripts --no-fund --no-audit
-
-      - name: npm ci must not have modified the working tree
-        working-directory: ${{ github.workspace }}
-        run: |
-          if ! git diff --quiet -- studio/frontend; then
-            echo "::error::npm ci modified files; commit the updated lockfile"
-            git status -- studio/frontend
-            exit 1
-          fi
-
-      # Catch the common foot-gun: a dep dropped from package.json that is
-      # still imported somewhere. The script walks the lockfile dep graph
-      # from the new top-level deps and only counts top-level node_modules
-      # paths as valid resolution targets for bare src/ imports.
-      #
-      # actions/checkout uses fetch-depth: 1 by default, so the base branch
-      # is not available locally. Fetch the single base commit with an
-      # explicit refspec so origin/<base> is reliably created (a bare
-      # `git fetch origin <ref>` only updates FETCH_HEAD in some configs).
-      - name: Dependency removal safety check
-        if: github.event_name == 'pull_request'
-        working-directory: ${{ github.workspace }}
-        run: |
-          git fetch --no-tags --depth=1 origin \
-            "${{ github.base_ref }}:refs/remotes/origin/${{ github.base_ref }}"
-          python3 scripts/check_frontend_dep_removal.py \
-            --base "origin/${{ github.base_ref }}" \
-            --enumerate-dead
-          python3 tests/studio/test_frontend_dep_removal.py
-
-      - name: Typecheck
-        run: npm run typecheck
-
-      - name: Unit tests
-        run: npm test
-
-      - name: Build
-        run: npm run build
-
-      - name: Built bundle must not contain Unsloth's unstable_Provider call site
-        run: |
-          set -e
-          JS=$(ls dist/assets/index-*.js | head -1)
-          HITS=$(grep -c 'unstable_Provider:' "$JS" || echo 0)
-          echo "main bundle: $JS"
-          echo "unstable_Provider: hits=$HITS (assistant-ui internals contribute up to 3)"
-          if [ "$HITS" -gt 3 ]; then
-            echo "::error file=studio/frontend/src/features/chat/runtime-provider.tsx::Unsloth bundle still passes unstable_Provider through useRemoteThreadListRuntime; this is the 2026.5.1 chat-history regression. Pass adapters directly into useLocalRuntime instead."
-            exit 1
-          fi
-
-      - name: Bundle size budget (75 MB)
-        run: |
-          SIZE=$(du -sb dist | cut -f1)
-          BUDGET=$((75 * 1024 * 1024))
-          echo "dist size: $SIZE bytes ($((SIZE/1024/1024)) MB), budget: $BUDGET bytes (75 MB)"
-          if [ "$SIZE" -gt "$BUDGET" ]; then
-            echo "::error::studio/frontend/dist/ exceeded the 75 MB budget. Drop dead deps (e.g. the unused next dep) or split chunks."
-            exit 1
-          fi
-
-      - name: Biome (non-blocking until accumulated drift is cleared)
-        continue-on-error: true
-        run: npm run biome:check
-
-      - name: Upload built dist
-        # Always upload so a green run is reviewable too -- the dist
-        # output catches "tests passed but bundle changed unexpectedly"
-        # regressions that would be invisible if we only kept artifacts
-        # on failure.
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: studio-frontend-dist
-          path: studio/frontend/dist
-          retention-days: 3

.github/workflows/studio-load-orchestrator-ci.yml

@@ -1,68 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-#
-# Event-loop regression test for the Unsloth model-load orchestrator.
-# Pins down issue #5642 (Win10 UI freeze on model load): the /load
-# route calls LlamaCppBackend.detect_audio_type synchronously, blocking
-# the FastAPI event loop on a chain of sync httpx.Client.post() probes.
-#
-# The suite stands up a stdlib fake llama-server + a tiny FastAPI app
-# via uvicorn and asserts that detect_audio_type runs via
-# asyncio.to_thread so concurrent /api/inference/load-progress polling
-# stays responsive. CPU-only, no torch, no real llama.cpp binary, no
-# GPU -- the matching cross-OS staging proof lives on
-# danielhanchen/unsloth-staging-2 (Ubuntu / macOS / Windows all
-# green at PR time).
-
-name: Unsloth load-orchestrator CI
-
-on:
-  pull_request:
-    paths:
-      - 'studio/backend/routes/inference.py'
-      - 'studio/backend/core/inference/llama_cpp.py'
-      - 'tests/studio/load_freeze/**'
-      - '.github/workflows/studio-load-orchestrator-ci.yml'
-  push:
-    branches: [main]
-    paths:
-      - 'studio/backend/routes/inference.py'
-      - 'studio/backend/core/inference/llama_cpp.py'
-      - 'tests/studio/load_freeze/**'
-      - '.github/workflows/studio-load-orchestrator-ci.yml'
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-      - name: Install minimal deps (no torch, no unsloth)
-        # The test stubs `loggers` and `structlog`, imports
-        # core.inference.llama_cpp directly, and drives a small
-        # FastAPI app. Nothing here pulls torch or any GPU code,
-        # so the entire job typically completes in well under 60 s.
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install \
-            'pytest>=8' \
-            'httpx>=0.27,<1' \
-            'fastapi>=0.110,<1' \
-            'uvicorn>=0.30,<1' \
-            'anyio>=4'
-      - name: Run load-orchestrator tests
-        run: python -m pytest -v --tb=short tests/studio/load_freeze/

.github/workflows/studio-mac-api-smoke.yml

@@ -1,153 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Mac counterpart to studio-api-smoke.yml. Same tests/studio/
-# studio_api_smoke.py exercise (CORS hardening, auth state machine,
-# JWT expiry, API key lifecycle, /v1/models / /v1/embeddings /
-# /v1/responses, endpoint-by-endpoint auth audit) but on a real
-# Apple Silicon (macos-14, M1) runner. Drops the apt-get block;
-# GitHub-hosted macos-14 ships curl + jq.
-
-name: Mac Studio API CI
-
-on:
-  pull_request:
-    paths:
-      - 'studio/**'
-      - 'unsloth/**'
-      - 'unsloth_cli/**'
-      - 'install.sh'
-      - 'pyproject.toml'
-      - 'tests/studio/**'
-      - '.github/workflows/studio-mac-api-smoke.yml'
-  push:
-    branches: [main, pip]
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  api-smoke:
-    name: Unsloth API & Auth Tests
-    runs-on: macos-14
-    timeout-minutes: 25
-    env:
-      GGUF_REPO: unsloth/gemma-3-270m-it-GGUF
-      GGUF_VARIANT: UD-Q4_K_XL
-      GGUF_FILE: gemma-3-270m-it-UD-Q4_K_XL.gguf
-      STUDIO_PORT: '18895'
-      HF_HOME: ${{ github.workspace }}/hf-cache
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: '22'
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-
-      - name: Restore HF_HOME for ${{ env.GGUF_REPO }}
-        id: cache-hf
-        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        continue-on-error: true
-        with:
-          path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
-
-      - name: Prime HF_HOME with the GGUF
-        id: prime-hf
-        if: steps.cache-hf.outputs.cache-hit != 'true' || steps.cache-hf.outcome != 'success'
-        env:
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          python -m pip install --upgrade huggingface_hub
-          mkdir -p hf-cache
-          bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
-          bash .github/scripts/hf-download-with-retry.sh ggml-org/models tinyllamas/stories260K.gguf
-
-      - name: Save HF_HOME for ${{ env.GGUF_REPO }}
-        if: always() && steps.prime-hf.outcome == 'success'
-        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        with:
-          path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
-
-      - name: Install Unsloth (--local, --no-torch)
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          mkdir -p logs
-          set -o pipefail
-          bash install.sh --local --no-torch 2>&1 | tee logs/install.log
-
-      - name: Assert llama.cpp loads on this macOS
-        run: bash .github/scripts/assert-llama-loads.sh
-
-      - name: Install pyjwt for the JWT-expiry forge test
-        run: pip install 'pyjwt>=2.6'
-
-      - name: Reset auth + boot Unsloth (API-only)
-        run: |
-          # Wipe (not reset-password): the boot below must re-seed a fresh .bootstrap_password.
-          rm -rf ~/.unsloth/studio/auth
-          mkdir -p logs
-          UNSLOTH_API_ONLY=1 unsloth studio -H 127.0.0.1 -p "$STUDIO_PORT" \
-            > logs/studio.log 2>&1 &
-          echo "STUDIO_PID=$!" >> "$GITHUB_ENV"
-
-      - name: Wait for /api/health
-        run: |
-          for i in $(seq 1 180); do
-            if curl -fs "http://127.0.0.1:${STUDIO_PORT}/api/health" > /tmp/health.json; then
-              jq -e '.status == "healthy"' /tmp/health.json && break
-            fi
-            sleep 1
-          done
-          jq -e '.status == "healthy"' /tmp/health.json
-
-      - name: Pass bootstrap password + rotated targets to the test
-        run: |
-          OLD=$(cat ~/.unsloth/studio/auth/.bootstrap_password)
-          NEW="ApiSmoke-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-          NEW2="ApiSmoke-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-          echo "::add-mask::$OLD"
-          echo "::add-mask::$NEW"
-          echo "::add-mask::$NEW2"
-          echo "STUDIO_OLD_PW=$OLD"  >> "$GITHUB_ENV"
-          echo "STUDIO_NEW_PW=$NEW"  >> "$GITHUB_ENV"
-          echo "STUDIO_NEW2_PW=$NEW2" >> "$GITHUB_ENV"
-
-      - name: Run Unsloth API & Auth tests
-        env:
-          BASE_URL: http://127.0.0.1:18895
-          STUDIO_AUTH_DIR: /Users/runner/.unsloth/studio/auth
-        run: python tests/studio/studio_api_smoke.py
-
-      - name: Stop Unsloth
-        if: always()
-        run: |
-          kill "${STUDIO_PID}" 2>/dev/null || true
-          sleep 2
-
-      - name: Upload API smoke logs
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: mac-studio-api-smoke-log
-          path: |
-            logs/install.log
-            logs/studio.log
-          retention-days: 7

.github/workflows/studio-mac-install-matrix.yml

@@ -1,82 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Proves Unsloth's llama.cpp install loads on every supported macOS. The heavy
-# app smokes stay single-OS; this matrix covers the OS-version dimension cheaply
-# (install.sh + binary-load assert). Regression guard for the macOS-version
-# selection in studio/install_llama_prebuilt.py.
-
-name: Mac Studio Install Matrix CI
-
-on:
-  pull_request:
-    paths:
-      - 'studio/install_llama_prebuilt.py'
-      - 'studio/setup.sh'
-      - 'install.sh'
-      - '.github/scripts/assert-llama-loads.sh'
-      - '.github/workflows/studio-mac-install-matrix.yml'
-  push:
-    branches: [main, pip]
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  install-load:
-    name: Install + load (${{ matrix.os }})
-    runs-on: ${{ matrix.os }}
-    timeout-minutes: 25
-    continue-on-error: ${{ matrix.experimental }}
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - os: macos-14        # Apple Silicon, macOS 14 Sonoma
-            experimental: false
-          - os: macos-15        # Apple Silicon, macOS 15 Sequoia
-            experimental: false
-          - os: macos-26        # Apple Silicon, macOS 26 Tahoe
-            experimental: false
-          - os: macos-15-intel  # Intel x86_64, macOS 15 (informational)
-            experimental: true
-          - os: macos-26-intel  # Intel x86_64, macOS 26 (last Intel macOS)
-            experimental: true
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: '22'
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-
-      - name: Install Unsloth (--local, --no-torch)
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          mkdir -p logs
-          set -o pipefail
-          bash install.sh --local --no-torch 2>&1 | tee logs/install.log
-
-      - name: Assert llama.cpp loads on this macOS
-        run: bash .github/scripts/assert-llama-loads.sh
-
-      - name: Upload install log
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: mac-install-matrix-${{ matrix.os }}-log
-          path: logs/install.log
-          retention-days: 7

.github/workflows/studio-mac-ui-smoke.yml

@@ -1,355 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Mac counterpart to studio-ui-smoke.yml. Same Playwright + Chromium
-# end-to-end chat UI flow, but on macos-14 (M1) so we catch
-# Mac-specific frontend / backend wiring regressions that the Linux
-# job would miss (e.g. the Mac Tauri shell loading the same React
-# bundle, or the Mac llama.cpp prebuilt's HTTP layer behaving
-# differently from the Linux build).
-
-name: Mac Studio UI CI
-
-on:
-  pull_request:
-    paths:
-      - 'studio/**'
-      - 'unsloth/**'
-      - 'unsloth_cli/**'
-      - 'install.sh'
-      - 'pyproject.toml'
-      - 'tests/studio/**'
-      - '.github/scripts/run-studio-permission-browser.sh'
-      - '.github/workflows/studio-mac-ui-smoke.yml'
-  push:
-    branches: [main, pip]
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  ui-smoke:
-    name: Chat UI Tests
-    runs-on: macos-14
-    timeout-minutes: 35
-    env:
-      GGUF_REPO: unsloth/gemma-3-270m-it-GGUF
-      GGUF_VARIANT: UD-Q4_K_XL
-      GGUF_FILE: gemma-3-270m-it-UD-Q4_K_XL.gguf
-      STUDIO_PORT: '18896'
-      HF_HOME: ${{ github.workspace }}/hf-cache
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: '22'
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-
-      - name: Restore HF_HOME for ${{ env.GGUF_REPO }}
-        id: cache-hf
-        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        continue-on-error: true
-        with:
-          path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
-
-      - name: Prime HF_HOME with the GGUF
-        id: prime-hf
-        if: steps.cache-hf.outputs.cache-hit != 'true' || steps.cache-hf.outcome != 'success'
-        env:
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          python -m pip install --upgrade huggingface_hub
-          mkdir -p hf-cache
-          bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
-          bash .github/scripts/hf-download-with-retry.sh ggml-org/models tinyllamas/stories260K.gguf
-
-      - name: Save HF_HOME for ${{ env.GGUF_REPO }}
-        if: always() && steps.prime-hf.outcome == 'success'
-        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        with:
-          path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
-
-      - name: Install Unsloth (--local, --no-torch)
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          mkdir -p logs
-          set -o pipefail
-          bash install.sh --local --no-torch 2>&1 | tee logs/install.log
-
-      - name: Assert llama.cpp loads on this macOS
-        run: bash .github/scripts/assert-llama-loads.sh
-
-      - name: Install Playwright browsers
-        # No --with-deps on Mac: that flag installs Linux apt packages.
-        # GitHub-hosted macos-14 ships the system frameworks Chromium
-        # needs already.
-        # Pinned <1.58 because all 1.55-1.58 drivers ship Node 24 on
-        # macos-14 and intermittently hit 'SyntaxError: Unexpected end
-        # of JSON input' in pipeTransport.js. Run 25491698868 showed
-        # the crash hitting 100% of three retry attempts -- not a
-        # rare race but a hard reproduction. Belt-and-suspenders fix:
-        # the test scripts pass --single-process to Chromium (see
-        # tests/studio/playwright_chat_ui.py) AND we patch
-        # pipeTransport.js below to swallow JSON parse errors instead
-        # of crashing the driver Node process. Both together let the
-        # in-script retry recover from any residual flakes.
-        run: |
-          pip install 'playwright>=1.55,<1.58'
-          python -m playwright install chromium webkit
-
-      - name: Patch Playwright pipeTransport.js to tolerate malformed JSON
-        # In Playwright 1.55-1.58, pipeTransport.js does
-        # `JSON.parse(message)` with no try/catch; when Chromium dies
-        # mid-write the partial buffer crashes the driver Node
-        # process and the test script exits with 'Connection closed
-        # while reading from the driver'. Newer Playwright versions
-        # added a try/catch upstream. Backport that here.
-        run: |
-          python - <<'PY'
-          import os, re, sys
-          import playwright
-          driver_dir = os.path.join(os.path.dirname(playwright.__file__), "driver", "package", "lib", "server")
-          path = os.path.join(driver_dir, "pipeTransport.js")
-          src = open(path).read()
-          # Wrap both `this.onmessage.call(null, JSON.parse(...))` sites in try/catch.
-          patched = re.sub(
-              r"this\.onmessage\.call\(null, JSON\.parse\((message2?)\)\);",
-              r"try { this.onmessage.call(null, JSON.parse(\1)); } "
-              r"catch (e) { /* swallow malformed JSON from a crashing browser */ }",
-              src,
-          )
-          if patched == src:
-              # Already patched, or upstream changed -- either way, don't fail the build.
-              print(f"pipeTransport.js: no JSON.parse calls matched at {path}; skipping.")
-          else:
-              open(path, "w").write(patched)
-              print(f"pipeTransport.js: patched JSON.parse calls in {path}")
-          PY
-
-      - name: Reset auth + boot Unsloth
-        run: |
-          # Wipe (not reset-password): the boot below must re-seed a fresh .bootstrap_password.
-          rm -rf ~/.unsloth/studio/auth
-          mkdir -p logs
-          UNSLOTH_API_ONLY=1 unsloth studio -H 127.0.0.1 -p "$STUDIO_PORT" \
-            > logs/studio.log 2>&1 &
-          echo "STUDIO_PID=$!" >> "$GITHUB_ENV"
-
-      - name: Wait for /api/health
-        run: |
-          for i in $(seq 1 180); do
-            if curl -fs "http://127.0.0.1:${STUDIO_PORT}/api/health" > /tmp/health.json; then
-              jq -e '.status == "healthy"' /tmp/health.json && break
-            fi
-            sleep 1
-          done
-          jq -e '.status == "healthy"' /tmp/health.json
-
-      - name: Pass bootstrap password to the Playwright step
-        run: |
-          OLD=$(cat ~/.unsloth/studio/auth/.bootstrap_password)
-          NEW="CIUi-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-          NEW2="CIUi-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-          echo "::add-mask::$OLD"
-          echo "::add-mask::$NEW"
-          echo "::add-mask::$NEW2"
-          echo "STUDIO_OLD_PW=$OLD"   >> "$GITHUB_ENV"
-          echo "STUDIO_NEW_PW=$NEW"   >> "$GITHUB_ENV"
-          echo "STUDIO_NEW2_PW=$NEW2" >> "$GITHUB_ENV"
-
-      - name: Drive the chat UI with Playwright
-        env:
-          BASE_URL: http://127.0.0.1:18896
-          PW_ART_DIR: logs/playwright
-          STUDIO_UI_STRICT: '1'
-          # macos-14 free runner is 3 vCPU / 7 GB / no Metal-accel
-          # available to llama.cpp from CI; gemma-3-270m turn latency
-          # has been observed to crowd the 180s default. Triple it.
-          STUDIO_UI_TURN_TIMEOUT_MS: '540000'
-        # Retry up to 3 times to absorb known macos-14 free-runner
-        # flakes: (1) Playwright Node 24 pipeTransport.js 'Unexpected
-        # end of JSON input' crash when the Chromium browser process
-        # dies mid-test, (2) Chromium net::ERR_NO_BUFFER_SPACE when the
-        # runner's kernel briefly runs out of socket buffers, and (3) a
-        # goto 'interrupted by another navigation' when the SPA auth
-        # guard redirects mid-navigation. The retry FULLY resets Unsloth
-        # (kill, wipe auth, reboot, wait /api/health, re-export
-        # bootstrap pw) before re-running the script. A real test failure
-        # (assertion / timeout) does NOT match any pattern so it bypasses
-        # retry and surfaces immediately.
-        run: |
-          mkdir -p logs/playwright
-          attempt=1
-          max_attempts=3
-          while : ; do
-            set +e
-            python tests/studio/playwright_chat_ui.py 2>&1 | tee logs/playwright_attempt_${attempt}.log
-            rc=${PIPESTATUS[0]}
-            set -e
-            if [ "$rc" -eq 0 ]; then
-              break
-            fi
-            if { grep -q "Unexpected end of JSON input"       logs/playwright_attempt_${attempt}.log \
-                 || grep -q "ERR_NO_BUFFER_SPACE"             logs/playwright_attempt_${attempt}.log \
-                 || grep -q "interrupted by another navigation" logs/playwright_attempt_${attempt}.log; } \
-               && [ "$attempt" -lt "$max_attempts" ]; then
-              echo "::warning::Playwright flake on attempt ${attempt}; resetting Unsloth and retrying..."
-              kill "${STUDIO_PID}" 2>/dev/null || true
-              sleep 2
-              rm -rf ~/.unsloth/studio/auth
-              UNSLOTH_API_ONLY=1 unsloth studio -H 127.0.0.1 -p "$STUDIO_PORT" \
-                > "logs/studio_retry_${attempt}.log" 2>&1 &
-              STUDIO_PID=$!
-              echo "STUDIO_PID=$STUDIO_PID" >> "$GITHUB_ENV"
-              for i in $(seq 1 180); do
-                if curl -fs "http://127.0.0.1:${STUDIO_PORT}/api/health" > /tmp/health.json \
-                   && jq -e '.status == "healthy"' /tmp/health.json >/dev/null; then
-                  break
-                fi
-                sleep 1
-              done
-              STUDIO_OLD_PW=$(cat ~/.unsloth/studio/auth/.bootstrap_password)
-              STUDIO_NEW_PW="CIUi-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-              STUDIO_NEW2_PW="CIUi-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-              echo "::add-mask::$STUDIO_OLD_PW"
-              echo "::add-mask::$STUDIO_NEW_PW"
-              echo "::add-mask::$STUDIO_NEW2_PW"
-              export STUDIO_OLD_PW STUDIO_NEW_PW STUDIO_NEW2_PW
-              attempt=$((attempt + 1))
-              sleep 3
-              continue
-            fi
-            exit "$rc"
-          done
-
-      - name: Stop Unsloth (chat-ui ends with Shutdown click; this is belt-and-suspenders)
-        if: always()
-        run: |
-          kill "${STUDIO_PID}" 2>/dev/null || true
-          sleep 2
-
-      - name: Cross-browser permission controls
-        run: |
-          bash .github/scripts/run-studio-permission-browser.sh 18895 webkit
-
-      - name: Reset auth + boot Unsloth for extra UI tests (port 18897)
-        run: |
-          rm -rf ~/.unsloth/studio/auth
-          mkdir -p logs
-          UNSLOTH_API_ONLY=1 unsloth studio -H 127.0.0.1 -p 18897 \
-            > logs/studio_extra.log 2>&1 &
-          echo "STUDIO_EXTRA_PID=$!" >> "$GITHUB_ENV"
-
-      - name: Wait for /api/health on 18897
-        run: |
-          for i in $(seq 1 180); do
-            if curl -fs "http://127.0.0.1:18897/api/health" > /tmp/health2.json; then
-              jq -e '.status == "healthy"' /tmp/health2.json && break
-            fi
-            sleep 1
-          done
-          jq -e '.status == "healthy"' /tmp/health2.json
-
-      - name: Pass bootstrap pw for extra UI test
-        run: |
-          OLD=$(cat ~/.unsloth/studio/auth/.bootstrap_password)
-          NEW="CIUiExtra-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-          echo "::add-mask::$OLD"
-          echo "::add-mask::$NEW"
-          echo "STUDIO_EXTRA_OLD_PW=$OLD" >> "$GITHUB_ENV"
-          echo "STUDIO_EXTRA_NEW_PW=$NEW" >> "$GITHUB_ENV"
-
-      - name: Drive Compare/Recipes/Export/Unsloth/Settings with Playwright
-        env:
-          BASE_URL: http://127.0.0.1:18897
-          STUDIO_OLD_PW: ${{ env.STUDIO_EXTRA_OLD_PW }}
-          STUDIO_NEW_PW: ${{ env.STUDIO_EXTRA_NEW_PW }}
-          PW_ART_DIR: logs/playwright_extra
-          STUDIO_UI_STRICT: '1'
-          # See "Drive the chat UI" step.
-          STUDIO_UI_TURN_TIMEOUT_MS: '540000'
-          GGUF_REPO: ${{ env.GGUF_REPO }}
-          GGUF_VARIANT: ${{ env.GGUF_VARIANT }}
-        # Same flake-retry shape as "Drive the chat UI with Playwright" -- catches
-        # pipeTransport JSON crash, ERR_NO_BUFFER_SPACE, and nav interrupts.
-        run: |
-          mkdir -p logs/playwright_extra
-          attempt=1
-          max_attempts=3
-          while : ; do
-            set +e
-            python tests/studio/playwright_extra_ui.py 2>&1 | tee logs/playwright_extra_attempt_${attempt}.log
-            rc=${PIPESTATUS[0]}
-            set -e
-            if [ "$rc" -eq 0 ]; then
-              break
-            fi
-            if { grep -q "Unexpected end of JSON input"       logs/playwright_extra_attempt_${attempt}.log \
-                 || grep -q "ERR_NO_BUFFER_SPACE"             logs/playwright_extra_attempt_${attempt}.log \
-                 || grep -q "interrupted by another navigation" logs/playwright_extra_attempt_${attempt}.log; } \
-               && [ "$attempt" -lt "$max_attempts" ]; then
-              echo "::warning::Playwright flake on attempt ${attempt}; resetting Unsloth and retrying..."
-              kill "${STUDIO_EXTRA_PID}" 2>/dev/null || true
-              sleep 2
-              rm -rf ~/.unsloth/studio/auth
-              UNSLOTH_API_ONLY=1 unsloth studio -H 127.0.0.1 -p 18897 \
-                > "logs/studio_extra_retry_${attempt}.log" 2>&1 &
-              STUDIO_EXTRA_PID=$!
-              echo "STUDIO_EXTRA_PID=$STUDIO_EXTRA_PID" >> "$GITHUB_ENV"
-              for i in $(seq 1 180); do
-                if curl -fs "http://127.0.0.1:18897/api/health" > /tmp/health2.json \
-                   && jq -e '.status == "healthy"' /tmp/health2.json >/dev/null; then
-                  break
-                fi
-                sleep 1
-              done
-              STUDIO_OLD_PW=$(cat ~/.unsloth/studio/auth/.bootstrap_password)
-              STUDIO_NEW_PW="CIUiExtra-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-              echo "::add-mask::$STUDIO_OLD_PW"
-              echo "::add-mask::$STUDIO_NEW_PW"
-              export STUDIO_OLD_PW STUDIO_NEW_PW
-              attempt=$((attempt + 1))
-              sleep 3
-              continue
-            fi
-            exit "$rc"
-          done
-
-      - name: Stop second Unsloth
-        if: always()
-        run: |
-          kill "${STUDIO_EXTRA_PID}" 2>/dev/null || true
-          sleep 2
-
-      - name: Upload Playwright artifacts
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: mac-studio-ui-smoke-artifacts
-          path: |
-            logs/studio.log
-            logs/studio_extra.log
-            logs/install.log
-            logs/playwright
-            logs/playwright-permissions-*
-            logs/playwright_extra
-            logs/studio-permissions-*.log
-          retention-days: 7

.github/workflows/studio-mac-update-smoke.yml

@@ -1,177 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Mac counterpart to studio-update-smoke.yml. Verifies that on a real
-# Apple Silicon (macos-14, M1) runner:
-#
-#   1. install.sh --local --no-torch installs Unsloth AND auto-fetches
-#      the prebuilt llama.cpp Mac binary (llama-bNNNN-bin-macos-arm64
-#      from ggml-org/llama.cpp). Hitting the source-build fallback is
-#      treated as an Unsloth bug -- Unsloth must always pick the
-#      prebuilt on Mac.
-#   2. unsloth studio update --local is idempotent. Two consecutive
-#      runs both report "prebuilt up to date and validated", no
-#      source-build fallback.
-#   3. The installed Unsloth still boots and /api/health returns
-#      healthy after the update path.
-
-name: Mac Studio Update CI
-
-on:
-  pull_request:
-    paths:
-      - 'install.sh'
-      - 'scripts/uninstall.sh'
-      - 'studio/setup.sh'
-      - 'studio/install_python_stack.py'
-      - 'studio/install_llama_prebuilt.py'
-      - 'studio/backend/requirements/**'
-      - 'unsloth_cli/commands/studio.py'
-      - 'pyproject.toml'
-      - '.github/workflows/studio-mac-update-smoke.yml'
-  push:
-    branches: [main, pip]
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  update-idempotency:
-    name: Unsloth Updating Tests
-    runs-on: macos-14
-    timeout-minutes: 30
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: '22'
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-
-      - name: Install Unsloth (--local, --no-torch)
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          mkdir -p logs
-          set -o pipefail
-          bash install.sh --local --no-torch 2>&1 | tee logs/install.log
-
-      - name: Assert llama.cpp loads on this macOS
-        run: bash .github/scripts/assert-llama-loads.sh
-
-      - name: First update should be a no-op (prebuilt already validated)
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          set -o pipefail
-          unsloth studio update --local 2>&1 | tee logs/update.log
-          if grep -q "falling back to source build" logs/update.log; then
-            echo "::error::studio update fell back to source-build llama.cpp on Mac."
-            grep -E "llama-prebuilt|llama.cpp" logs/update.log | tail -60
-            exit 1
-          fi
-          if ! grep -qE "prebuilt up to date and validated|prebuilt installed and validated" logs/update.log; then
-            echo "::error::no prebuilt up-to-date marker in update.log."
-            grep -E "llama-prebuilt|llama.cpp" logs/update.log | tail -60
-            exit 1
-          fi
-          echo "update path took the prebuilt fast path"
-
-      - name: Second update must also be a no-op
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          set -o pipefail
-          unsloth studio update --local 2>&1 | tee logs/update2.log
-          grep -q "falling back to source build" logs/update2.log && {
-              echo "::error::second update fell back to source build on Mac"
-              tail -60 logs/update2.log; exit 1; } || true
-          grep -qE "prebuilt up to date and validated|prebuilt installed and validated" logs/update2.log
-          echo "second update was clean"
-
-      - name: Boot Unsloth briefly to confirm the install is still usable
-        run: |
-          mkdir -p logs
-          UNSLOTH_API_ONLY=1 unsloth studio -H 127.0.0.1 -p 18891 \
-            > logs/studio.log 2>&1 &
-          PID=$!
-          HEALTHY=""
-          for i in $(seq 1 60); do
-            if curl -fs http://127.0.0.1:18891/api/health > /tmp/health.json; then
-              if python3 -c "import json,sys; d=json.load(open('/tmp/health.json')); sys.exit(0 if d.get('status')=='healthy' else 1)"; then
-                HEALTHY=1
-                break
-              fi
-            fi
-            sleep 1
-          done
-          if [ -z "$HEALTHY" ]; then
-            echo "Unsloth failed to come up after \`update\`"
-            tail -200 logs/studio.log
-            kill "$PID" 2>/dev/null || true
-            exit 1
-          fi
-          kill "$PID" 2>/dev/null || true
-          echo "post-update Unsloth /api/health OK"
-
-      - name: Uninstall and verify clean
-        # Round-trip through scripts/uninstall.sh on real macOS. As a side
-        # effect this exercises the macOS-only .app bundle + Launch Services
-        # removal path (~/Applications/Unsloth Studio.app, lsregister -u)
-        # which is not testable from a Linux runner. Skips gracefully if
-        # scripts/uninstall.sh has not landed yet (lets this workflow merge
-        # before #5497).
-        run: |
-          set -o pipefail
-          if [ ! -f scripts/uninstall.sh ]; then
-            echo "scripts/uninstall.sh not present in this tree; skipping round-trip"
-            : > logs/uninstall.log
-            exit 0
-          fi
-          sh scripts/uninstall.sh 2>&1 | tee logs/uninstall.log
-          leak=0
-          for p in \
-            "$HOME/.unsloth/studio" \
-            "$HOME/.local/share/unsloth" \
-            "$HOME/Applications/Unsloth Studio.app" \
-            "$HOME/Desktop/Unsloth Studio.app" \
-            "$HOME/.local/bin/unsloth"; do
-            if [ -e "$p" ] || [ -L "$p" ]; then
-              echo "::error::leak: $p"
-              leak=$((leak + 1))
-            fi
-          done
-          [ "$leak" -eq 0 ] || exit 1
-          sh scripts/uninstall.sh 2>&1 | tail -5
-          sh scripts/uninstall.sh 2>&1 | tail -5
-          echo "PASS: mac install -> update -> uninstall round-trip clean"
-
-      - name: Upload update logs
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: mac-studio-update-log
-          path: |
-            logs/install.log
-            logs/update.log
-            logs/update2.log
-            logs/studio.log
-            logs/uninstall.log
-          retention-days: 7

.github/workflows/studio-tauri-smoke.yml

@@ -1,138 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# PR-time smoke for the Tauri desktop wrapper. Builds the frontend and the
-# Tauri Linux debug binary, with no codesigning. Catches:
-#   - tauri.conf.json drift
-#   - src-tauri Cargo.toml or rust source breakage
-#   - Tauri CLI version drift (we pin 2.10.1, matching release-desktop.yml)
-#   - frontend output not picked up by Tauri's distDir
-#
-# Linux-only on a free `ubuntu-latest` runner. Mac and Windows desktop builds
-# stay in release-desktop.yml (manual `workflow_dispatch`) because they need
-# code-signing secrets and ~30 min of runner time each.
-
-name: Unsloth Tauri CI
-
-on:
-  pull_request:
-    paths:
-      - 'studio/frontend/**'
-      - 'studio/src-tauri/**'
-      # CLI rename / signature change can break Tauri's spawned
-      # `unsloth studio` -- include unsloth_cli in the trigger set.
-      - 'unsloth_cli/**'
-      - '.github/workflows/studio-tauri-smoke.yml'
-  push:
-    branches: [main, pip]
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  linux-debug-build:
-    name: Tauri Linux debug build (no codesign)
-    runs-on: ubuntu-22.04
-    timeout-minutes: 25
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - name: Linux native deps for Tauri / WebKit2GTK
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y \
-            libwebkit2gtk-4.1-dev libappindicator3-dev \
-            librsvg2-dev libxdo-dev libssl-dev patchelf
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: '24'
-
-      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8  # stable @ 2026-03-27
-
-      - uses: swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32  # v2.9.1
-        with:
-          workspaces: studio/src-tauri -> target
-
-      - name: Install pinned Tauri CLI (matches release-desktop.yml)
-        # Lifecycle scripts (esbuild native-binary postinstall, etc.) are
-        # required for `vite build`. The pre-install lockfile structural
-        # audit (lockfile_supply_chain_audit.py) is the practical defence
-        # against the npm postinstall-dropper class -- it fires BEFORE any
-        # tarball runs, on the injection pattern itself rather than an
-        # advisory-DB lookup.
-        run: npm install --save-dev --prefix studio @tauri-apps/cli@2.10.1 --no-fund --no-audit
-
-      - name: Verify pinned Tauri CLI version
-        run: |
-          out="$(npx --prefix studio tauri --version)"
-          echo "$out"
-          [ "$out" = "tauri-cli 2.10.1" ] || { echo "::error::expected tauri-cli 2.10.1, got $out"; exit 1; }
-
-      - name: Lockfile supply-chain audit (pre-install scan)
-        run: python3 scripts/lockfile_supply_chain_audit.py
-
-      - name: Frontend build (npm ci, vite)
-        working-directory: studio/frontend
-        # Lifecycle scripts (esbuild native-binary postinstall, etc.) are
-        # required for `vite build`. The pre-install lockfile structural
-        # audit (lockfile_supply_chain_audit.py) is the practical defence
-        # against the npm postinstall-dropper class -- it fires BEFORE any
-        # tarball runs, on the injection pattern itself rather than an
-        # advisory-DB lookup.
-        run: |
-          npm ci --no-fund --no-audit
-          npm run build
-          test -f dist/index.html
-
-      # The crate carries ~100 unit tests (native_file_dialogs, preflight,
-      # install, desktop_auth, ...) that nothing ran until now: this workflow
-      # only ever built. Run them here, where the toolchain and the WebKit dev
-      # packages are already installed, so a broken assertion fails the PR
-      # instead of sitting unnoticed. `--no-fail-fast` reports every failing
-      # test in one run rather than stopping at the first.
-      - name: Rust unit tests (studio/src-tauri)
-        working-directory: studio/src-tauri
-        run: cargo test --no-fail-fast
-
-      - name: Tauri debug build (Linux, no bundle, no codesign)
-        # `--debug` + `--no-bundle` keeps this lean: compiles the Rust crate,
-        # confirms the frontend dist is wired into Tauri, but skips the AppImage
-        # / .deb production. Code signing is irrelevant because we never produce
-        # a distributable artifact.
-        env:
-          TAURI_SIGNING_PRIVATE_KEY: ''
-          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ''
-        run: npx --prefix studio tauri build --debug --no-bundle
-
-      - name: Inspect produced binary
-        run: |
-          BIN=$(find studio/src-tauri/target/debug -maxdepth 1 -type f -executable 2>/dev/null \
-                | grep -Ev '\.(d|so|dylib|dll)$' \
-                | grep -Ev '/(deps|build|examples)$' \
-                | head -1)
-          echo "binary: $BIN"
-          if [ -z "$BIN" ]; then
-            echo "::error::Tauri debug binary not produced"
-            ls -la studio/src-tauri/target/debug/ || true
-            exit 1
-          fi
-          file "$BIN"
-          du -h "$BIN"
-
-      - name: Upload Tauri debug build
-        # Always upload so a green run leaves the binary inspectable too.
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: tauri-debug-build
-          path: |
-            studio/src-tauri/target/debug
-            studio/frontend/dist
-          retention-days: 3

.github/workflows/studio-ui-smoke.yml

@@ -1,369 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# End-to-end Unsloth chat UI smoke via Playwright + Chromium against a
-# headless Linux runner. Boots Unsloth with the smallest GGUF
-# (gemma-3-270m-it UD-Q4_K_XL, ~254 MiB), drives the actual frontend
-# bundle, and asserts the full bootstrap-password / change-password /
-# send-message / persist-on-reload journey works end to end.
-#
-# This is the only workflow that catches regressions in the wiring
-# between the React frontend and the FastAPI backend, e.g. assistant-ui
-# version drift, /api/auth response shape changes, runtime-provider
-# regressions, or chat-history persistence breaking. Backend-only and
-# frontend-only CI happily pass while the actual user-visible UI is
-# broken (cf. the 2026.5.1 chat-history release).
-
-name: Unsloth UI CI
-
-on:
-  pull_request:
-    paths:
-      - 'studio/**'
-      - 'unsloth/**'
-      - 'unsloth_cli/**'
-      - 'install.sh'
-      - 'pyproject.toml'
-      # The Playwright test files themselves -- a PR that ONLY edits
-      # the test must still trigger UI CI.
-      - 'tests/studio/**'
-      - '.github/scripts/run-studio-permission-browser.sh'
-      - '.github/workflows/studio-ui-smoke.yml'
-  push:
-    branches: [main, pip]
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  ui-smoke:
-    name: Chat UI Tests
-    runs-on: ubuntu-latest
-    timeout-minutes: 25
-    env:
-      GGUF_REPO: unsloth/gemma-3-270m-it-GGUF
-      GGUF_VARIANT: UD-Q4_K_XL
-      GGUF_FILE: gemma-3-270m-it-UD-Q4_K_XL.gguf
-      STUDIO_PORT: '18892'
-      HF_HOME: ${{ github.workspace }}/hf-cache
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - name: Linux deps
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y --no-install-recommends \
-            libcurl4-openssl-dev libssl-dev jq
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: '22'
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-
-      - name: Restore HF_HOME for ${{ env.GGUF_REPO }}
-        id: cache-hf
-        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        continue-on-error: true
-        with:
-          path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
-
-      - name: Prime HF_HOME with the GGUF
-        id: prime-hf
-        if: steps.cache-hf.outputs.cache-hit != 'true' || steps.cache-hf.outcome != 'success'
-        env:
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          python -m pip install --upgrade huggingface_hub
-          mkdir -p hf-cache
-          bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
-          bash .github/scripts/hf-download-with-retry.sh ggml-org/models tinyllamas/stories260K.gguf
-
-      - name: Save HF_HOME for ${{ env.GGUF_REPO }}
-        if: always() && steps.prime-hf.outcome == 'success'
-        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        with:
-          path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
-
-      - name: Install Unsloth (--local, --no-torch)
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          mkdir -p logs
-          set -o pipefail
-          bash install.sh --local --no-torch 2>&1 | tee logs/install.log
-
-      - name: Install Playwright browsers
-        run: |
-          pip install 'playwright>=1.45'
-          python -m playwright install --with-deps chromium firefox webkit
-
-      - name: Reset auth + boot Unsloth
-        run: |
-          # Wipe (not reset-password): the boot below must re-seed a fresh .bootstrap_password.
-          rm -rf ~/.unsloth/studio/auth
-          mkdir -p logs
-          UNSLOTH_API_ONLY=1 unsloth studio -H 127.0.0.1 -p "$STUDIO_PORT" \
-            > logs/studio.log 2>&1 &
-          echo "STUDIO_PID=$!" >> "$GITHUB_ENV"
-
-      - name: Wait for /api/health
-        # 180 s -- a cold runner with venv warm-up + lazy imports has
-        # been seen to exceed 60 s. Failing the wait is more expensive
-        # than waiting an extra two minutes.
-        run: |
-          for i in $(seq 1 180); do
-            if curl -fs "http://127.0.0.1:${STUDIO_PORT}/api/health" > /tmp/health.json; then
-              jq -e '.status == "healthy"' /tmp/health.json && break
-            fi
-            sleep 1
-          done
-          jq -e '.status == "healthy"' /tmp/health.json
-
-      - name: Pass bootstrap password to the Playwright step
-        # The Playwright test does its OWN /change-password through the
-        # UI (Setup your account / Choose a new password), then loads
-        # the model via page.evaluate against /api/inference/load with
-        # the JWT it got from change-password. So the only thing we
-        # have to hand it is the bootstrap password (so it can verify
-        # post-rotation that the OLD bootstrap pw now returns 401).
-        #
-        # NEW + NEW2 are generated freshly per CI run via secrets.token_urlsafe
-        # rather than hardcoded. If a workflow gets compromised, the
-        # attacker can't replay a known-good rotated password against
-        # any future / parallel Unsloth install -- the rotated value
-        # only ever exists for the lifetime of this single job, masked
-        # in the log via ::add-mask::.
-        run: |
-          OLD=$(cat ~/.unsloth/studio/auth/.bootstrap_password)
-          NEW="CIUi-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-          NEW2="CIUi-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-          echo "::add-mask::$OLD"
-          echo "::add-mask::$NEW"
-          echo "::add-mask::$NEW2"
-          echo "STUDIO_OLD_PW=$OLD"   >> "$GITHUB_ENV"
-          echo "STUDIO_NEW_PW=$NEW"   >> "$GITHUB_ENV"
-          echo "STUDIO_NEW2_PW=$NEW2" >> "$GITHUB_ENV"
-
-      - name: Drive the chat UI with Playwright
-        env:
-          BASE_URL: http://127.0.0.1:18892
-          # The test file lives in the repo so it can be run locally
-          # against a freshly-installed Unsloth (BASE_URL=...; STUDIO_OLD_PW=
-          # $(cat ~/.unsloth/studio/auth/.bootstrap_password); python ...).
-          PW_ART_DIR: logs/playwright
-          # Strict mode: in CI a missing button / nav / dialog must
-          # FAIL the test. Locally the test still runs against partial
-          # Unsloth installs without STUDIO_UI_STRICT.
-          STUDIO_UI_STRICT: '1'
-        run: |
-          mkdir -p logs/playwright
-          python tests/studio/playwright_chat_ui.py
-
-      - name: Stop Unsloth (chat-ui ends with Shutdown click; this is belt-and-suspenders)
-        if: always()
-        run: |
-          kill "${STUDIO_PID}" 2>/dev/null || true
-          sleep 2
-
-      - name: Cross-browser permission controls
-        run: |
-          bash .github/scripts/run-studio-permission-browser.sh 18893 firefox
-          bash .github/scripts/run-studio-permission-browser.sh 18893 webkit
-          bash .github/scripts/run-studio-permission-browser.sh 18893 chromium chrome
-
-      # The chat UI test ends by clicking the Shutdown menuitem, which
-      # leaves the server dead. The extra UI test (Compare / Recipes /
-      # Export / Unsloth / Settings) needs a fresh Unsloth, so we boot a
-      # second one on a different port. Boot is fast (~3-5s on the
-      # warm install we already did) so this adds little wall time.
-      - name: Reset auth + boot Unsloth for extra UI tests (port 18894)
-        run: |
-          rm -rf ~/.unsloth/studio/auth
-          mkdir -p logs
-          UNSLOTH_API_ONLY=1 unsloth studio -H 127.0.0.1 -p 18894 \
-            > logs/studio_extra.log 2>&1 &
-          echo "STUDIO_EXTRA_PID=$!" >> "$GITHUB_ENV"
-
-      - name: Wait for /api/health on 18894
-        run: |
-          for i in $(seq 1 180); do
-            if curl -fs "http://127.0.0.1:18894/api/health" > /tmp/health2.json; then
-              jq -e '.status == "healthy"' /tmp/health2.json && break
-            fi
-            sleep 1
-          done
-          jq -e '.status == "healthy"' /tmp/health2.json
-
-      - name: Pass bootstrap pw for extra UI test
-        run: |
-          OLD=$(cat ~/.unsloth/studio/auth/.bootstrap_password)
-          NEW="CIUiExtra-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-          echo "::add-mask::$OLD"
-          echo "::add-mask::$NEW"
-          echo "STUDIO_EXTRA_OLD_PW=$OLD" >> "$GITHUB_ENV"
-          echo "STUDIO_EXTRA_NEW_PW=$NEW" >> "$GITHUB_ENV"
-
-      - name: Drive Compare/Recipes/Export/Unsloth/Settings with Playwright
-        env:
-          BASE_URL: http://127.0.0.1:18894
-          STUDIO_OLD_PW: ${{ env.STUDIO_EXTRA_OLD_PW }}
-          STUDIO_NEW_PW: ${{ env.STUDIO_EXTRA_NEW_PW }}
-          PW_ART_DIR: logs/playwright_extra
-          STUDIO_UI_STRICT: '1'
-          GGUF_REPO: ${{ env.GGUF_REPO }}
-          GGUF_VARIANT: ${{ env.GGUF_VARIANT }}
-        run: |
-          mkdir -p logs/playwright_extra
-          python tests/studio/playwright_extra_ui.py
-
-      - name: UI font size scaling regression (Playwright)
-        env:
-          BASE_URL: http://127.0.0.1:18894
-          STUDIO_PW: ${{ env.STUDIO_EXTRA_NEW_PW }}
-          PW_ART_DIR: logs/playwright_fontscale
-        run: |
-          mkdir -p logs/playwright_fontscale
-          python tests/studio/playwright_ui_font_scale.py
-
-      - name: Stop second Unsloth
-        if: always()
-        run: |
-          kill "${STUDIO_EXTRA_PID}" 2>/dev/null || true
-          sleep 2
-
-      # Model-picker per-model-config regression (PR #7207 re-land of #6647).
-      # Fourth Unsloth on its own port; loads the tiny GGUF and drives the
-      # picker's run-settings surface: Context Length persists across a reload,
-      # Reset clears the stored override (never pins it), and the infra models
-      # (RAG embedder + llama.cpp probe) stay hidden from the picker.
-      - name: Reset auth + boot Unsloth for model-config tests (port 18898)
-        run: |
-          rm -rf ~/.unsloth/studio/auth
-          mkdir -p logs
-          UNSLOTH_API_ONLY=1 unsloth studio -H 127.0.0.1 -p 18898 \
-            > logs/studio_modelcfg.log 2>&1 &
-          echo "STUDIO_MODELCFG_PID=$!" >> "$GITHUB_ENV"
-
-      - name: Wait for /api/health on 18898
-        run: |
-          for i in $(seq 1 180); do
-            if curl -fs "http://127.0.0.1:18898/api/health" > /tmp/health4.json; then
-              jq -e '.status == "healthy"' /tmp/health4.json && break
-            fi
-            sleep 1
-          done
-          jq -e '.status == "healthy"' /tmp/health4.json
-
-      - name: Pass bootstrap pw for model-config test
-        run: |
-          NEW="CIModelCfg-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-          echo "::add-mask::$NEW"
-          echo "STUDIO_MODELCFG_NEW_PW=$NEW" >> "$GITHUB_ENV"
-
-      - name: Drive model-picker per-model-config with Playwright
-        env:
-          BASE_URL: http://127.0.0.1:18898
-          STUDIO_NEW_PW: ${{ env.STUDIO_MODELCFG_NEW_PW }}
-          PW_ART_DIR: logs/playwright_modelcfg
-          STUDIO_UI_STRICT: '1'
-          GGUF_REPO: ${{ env.GGUF_REPO }}
-          GGUF_VARIANT: ${{ env.GGUF_VARIANT }}
-          STUDIO_MODEL_HINT: gemma-3-270m
-        run: |
-          mkdir -p logs/playwright_modelcfg
-          python tests/studio/playwright_model_config.py
-
-      - name: Stop fourth Unsloth
-        if: always()
-        run: |
-          kill "${STUDIO_MODELCFG_PID}" 2>/dev/null || true
-          sleep 2
-
-      # IME + multilingual paste regression (issue #5318 / PR #5327).
-      # Third Unsloth on its own port so a hang here cannot poison the
-      # earlier UI tests. No GGUF -- the bug surface is the composer.
-      - name: Reset auth + boot Unsloth for IME / i18n tests (port 18896)
-        run: |
-          rm -rf ~/.unsloth/studio/auth
-          mkdir -p logs
-          UNSLOTH_API_ONLY=1 unsloth studio -H 127.0.0.1 -p 18896 \
-            > logs/studio_ime.log 2>&1 &
-          echo "STUDIO_IME_PID=$!" >> "$GITHUB_ENV"
-
-      - name: Wait for /api/health on 18896
-        run: |
-          for i in $(seq 1 180); do
-            if curl -fs "http://127.0.0.1:18896/api/health" > /tmp/health3.json; then
-              jq -e '.status == "healthy"' /tmp/health3.json && break
-            fi
-            sleep 1
-          done
-          jq -e '.status == "healthy"' /tmp/health3.json
-
-      - name: Pass bootstrap pw for IME / i18n test
-        # IME smoke does the change-password against the bootstrap that
-        # Unsloth's frontend injects into the page, so it only needs the
-        # NEW password.
-        run: |
-          NEW="CIIme-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-          echo "::add-mask::$NEW"
-          echo "STUDIO_IME_NEW_PW=$NEW" >> "$GITHUB_ENV"
-
-      - name: Drive IME + multilingual paste regression with Playwright
-        env:
-          BASE_URL: http://127.0.0.1:18896
-          STUDIO_NEW_PW: ${{ env.STUDIO_IME_NEW_PW }}
-          PW_ART_DIR: logs/playwright_ime
-          STUDIO_UI_STRICT: '1'
-        run: |
-          mkdir -p logs/playwright_ime
-          python tests/studio/playwright_chat_ime_i18n.py
-
-      - name: Stop third Unsloth
-        if: always()
-        run: |
-          kill "${STUDIO_IME_PID}" 2>/dev/null || true
-          sleep 2
-          # Capture backend + llama-server logs (all three Studios share this
-          # dir) so a stray 500 has a server-side traceback.
-          mkdir -p logs/server-logs
-          cp -r ~/.unsloth/studio/logs/. logs/server-logs/ 2>/dev/null || true
-
-      - name: Upload Playwright artifacts
-        # Always upload so a green run's screenshots stay reviewable --
-        # catches "passed but the UI is silently broken" regressions.
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: studio-ui-smoke-artifacts
-          path: |
-            logs/studio.log
-            logs/studio_extra.log
-            logs/studio_modelcfg.log
-            logs/studio_ime.log
-            logs/install.log
-            logs/server-logs/
-            logs/playwright
-            logs/playwright-permissions-*
-            logs/playwright_extra
-            logs/playwright_fontscale
-            logs/playwright_modelcfg
-            logs/playwright_ime
-            logs/studio-permissions-*.log
-          retention-days: 7

.github/workflows/studio-update-smoke.yml

@@ -1,237 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Verifies that `unsloth studio update --local` is idempotent: a fresh
-# install via install.sh, followed by `unsloth studio update --local`,
-# succeeds and is a no-op for the llama.cpp prebuilt (it should report
-# "prebuilt up to date and validated", not re-run the source build).
-#
-# This catches regressions in setup.sh's update path that the existing
-# GGUF / wheel jobs would miss because they only invoke install.sh once.
-
-name: Unsloth Update CI
-
-on:
-  pull_request:
-    paths:
-      - 'install.sh'
-      - 'scripts/uninstall.sh'
-      - 'studio/setup.sh'
-      - 'studio/install_python_stack.py'
-      - 'studio/install_llama_prebuilt.py'
-      - 'studio/backend/requirements/**'
-      - 'unsloth_cli/commands/studio.py'
-      - 'pyproject.toml'
-      - '.github/workflows/studio-update-smoke.yml'
-  push:
-    branches: [main, pip]
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  update-idempotency:
-    name: Unsloth Updating Tests
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - name: Linux deps for llama.cpp prebuilt
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y --no-install-recommends \
-            libcurl4-openssl-dev libssl-dev jq
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: '22'
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          # Don't cache pip: this job runs `bash install.sh` and
-          # `unsloth studio update --local` which both go through
-          # `uv` and never populate ~/.cache/pip. setup-python's
-          # post-step then fatal-errors with "Cache folder path is
-          # retrieved for pip but doesn't exist on disk".
-
-      - name: Install Unsloth (--local, --no-torch)
-        # Pass the workflow token so the llama.cpp prebuilt installer's
-        # GitHub-API call to list releases isn't rate-limited (60/hr
-        # unauthenticated). Without this, three consecutive install +
-        # update + update calls in this job exceed the limit and the
-        # prebuilt path falls back to source build.
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          mkdir -p logs
-          set -o pipefail
-          bash install.sh --local --no-torch 2>&1 | tee logs/install.log
-
-      - name: First update should be a no-op (prebuilt already validated)
-        # `unsloth studio update --local` runs studio/setup.sh against
-        # the local repo. Right after install.sh the llama.cpp prebuilt
-        # has just been installed and validated, so the second run must
-        # take the "prebuilt up to date and validated" code path. Any
-        # source-build fallback or re-download here means setup.sh's
-        # idempotency regressed.
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          set -o pipefail
-          unsloth studio update --local 2>&1 | tee logs/update.log
-          if grep -q "falling back to source build" logs/update.log; then
-            echo "::error::studio update fell back to source-build llama.cpp on a fresh install. setup.sh idempotency regressed."
-            grep -E "llama-prebuilt|llama.cpp" logs/update.log | tail -60
-            exit 1
-          fi
-          if ! grep -qE "prebuilt up to date and validated|prebuilt installed and validated" logs/update.log; then
-            echo "::error::no prebuilt up-to-date marker in update.log. Did setup.sh skip the prebuilt path on update?"
-            grep -E "llama-prebuilt|llama.cpp" logs/update.log | tail -60
-            exit 1
-          fi
-          echo "update path took the prebuilt fast path"
-
-      - name: Second update must also be a no-op
-        # Two consecutive `update`s back-to-back is the usual desktop
-        # flow (auto-update, then user-triggered update). Asserting the
-        # second run is also clean rules out hidden state changes from
-        # the first one.
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          set -o pipefail
-          unsloth studio update --local 2>&1 | tee logs/update2.log
-          grep -q "falling back to source build" logs/update2.log && {
-              echo "::error::second update fell back to source build"
-              tail -60 logs/update2.log; exit 1; } || true
-          grep -qE "prebuilt up to date and validated|prebuilt installed and validated" logs/update2.log
-          echo "second update was clean"
-
-      - name: Boot Unsloth briefly to confirm the install is still usable
-        # If `update --local` accidentally broke the venv or wiped the
-        # llama-server binary, the server would fail to start here.
-        run: |
-          mkdir -p logs
-          UNSLOTH_API_ONLY=1 unsloth studio -H 127.0.0.1 -p 18891 \
-            > logs/studio.log 2>&1 &
-          PID=$!
-          for i in $(seq 1 60); do
-            if curl -fs http://127.0.0.1:18891/api/health > /tmp/health.json; then
-              jq -e '.status == "healthy"' /tmp/health.json
-              break
-            fi
-            sleep 1
-          done
-          if ! jq -e '.status == "healthy"' /tmp/health.json 2>/dev/null; then
-            echo "Unsloth failed to come up after `update`"
-            tail -200 logs/studio.log
-            kill "$PID" 2>/dev/null || true
-            exit 1
-          fi
-          kill "$PID" 2>/dev/null || true
-          echo "post-update Unsloth /api/health OK"
-
-      - name: A complete install reports itself complete
-        run: |
-          set -o pipefail
-          unsloth studio verify-install
-          unsloth studio desktop-capabilities --json | tee /tmp/caps.json
-          jq -e '.studio_install_ok == true' /tmp/caps.json
-          jq -e '.desktop_manageability_version >= 2' /tmp/caps.json
-
-      - name: An incomplete install must not report itself ready
-        # An installer killed part-way leaves a working CLI but no studio.txt
-        # deps, which the old preflight called ManagedReady. The manifest is
-        # written last, so removing it reproduces that state.
-        run: |
-          set -o pipefail
-          # install.sh's default root, resolved explicitly: `python` on PATH
-          # here is setup-python's, not the managed venv.
-          MANIFEST="$HOME/.unsloth/studio/unsloth_studio/unsloth_install_manifest.json"
-          test -f "$MANIFEST" || { echo "::error::installer never wrote $MANIFEST"; exit 1; }
-          rm -f "$MANIFEST"
-          unsloth studio desktop-capabilities --json | tee /tmp/caps_bad.json
-          jq -e '.studio_install_ok == false' /tmp/caps_bad.json
-          if unsloth studio verify-install; then
-            echo "::error::verify-install passed on an install with no manifest"
-            exit 1
-          fi
-          echo "incomplete install correctly reported not-ready"
-
-      - name: Update repairs an incomplete install
-        # `--local` bypasses setup.sh's PyPI version compare, so this asserts
-        # the repair OUTCOME. The non-local fast path the desktop Repair button
-        # uses is covered by tests/studio/install/test_setup_fast_path_guard.py.
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          set -o pipefail
-          unsloth studio update --local 2>&1 | tee logs/update_repair.log
-          unsloth studio verify-install
-          unsloth studio desktop-capabilities --json | jq -e '.studio_install_ok == true'
-          echo "update repaired the incomplete install"
-
-      - name: Uninstall and verify clean
-        # Round-trip the installer through scripts/uninstall.sh: confirms the
-        # uninstaller actually finds and removes everything install.sh +
-        # update wrote. Safety-guard scenarios (refuse-$HOME etc.) belong
-        # in a separate fast smoke job; this is the happy-path cleanup
-        # assertion that catches regressions where install.sh starts
-        # writing to a new location and scripts/uninstall.sh hasn't caught up.
-        # Skips gracefully if scripts/uninstall.sh has not landed yet (lets
-        # this workflow merge before #5497).
-        run: |
-          set -o pipefail
-          if [ ! -f scripts/uninstall.sh ]; then
-            echo "scripts/uninstall.sh not present in this tree; skipping round-trip"
-            : > logs/uninstall.log
-            exit 0
-          fi
-          sh scripts/uninstall.sh 2>&1 | tee logs/uninstall.log
-          leak=0
-          for p in \
-            "$HOME/.unsloth/studio" \
-            "$HOME/.local/share/unsloth" \
-            "$HOME/Desktop/Unsloth Studio.desktop" \
-            "$HOME/.local/bin/unsloth"; do
-            if [ -e "$p" ] || [ -L "$p" ]; then
-              echo "::error::leak: $p"
-              ls -la "$p" 2>&1 | head -3
-              leak=$((leak + 1))
-            fi
-          done
-          [ "$leak" -eq 0 ] || exit 1
-          # Idempotent: re-runs exit 0 on an empty $HOME.
-          sh scripts/uninstall.sh 2>&1 | tail -5
-          sh scripts/uninstall.sh 2>&1 | tail -5
-          echo "PASS: install -> update -> uninstall round-trip clean"
-
-      - name: Upload update logs
-        # Always upload so a green run still leaves the install + two
-        # update logs + uninstall log reviewable.
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: studio-update-log
-          path: |
-            logs/install.log
-            logs/update.log
-            logs/update2.log
-            logs/studio.log
-            logs/uninstall.log
-          retention-days: 7

.github/workflows/studio-windows-api-smoke.yml

@@ -1,237 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Windows counterpart to studio-api-smoke.yml / studio-mac-api-smoke.yml.
-# Same tests/studio/studio_api_smoke.py exercise (CORS hardening, auth
-# state machine, JWT expiry, API key lifecycle, /v1/models /
-# /v1/embeddings / /v1/responses, endpoint-by-endpoint auth audit) but
-# on the FREE windows-latest runner. The file-mode hardening section
-# (Section 6) is Linux-only and short-circuits on non-POSIX; the rest
-# is platform-portable.
-
-name: Windows Unsloth API CI
-
-on:
-  pull_request:
-    paths:
-      - 'studio/**'
-      - 'unsloth/**'
-      - 'unsloth_cli/**'
-      - 'install.ps1'
-      - 'pyproject.toml'
-      - 'tests/studio/**'
-      - '.github/workflows/studio-windows-api-smoke.yml'
-  push:
-    branches: [main, pip]
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  api-smoke:
-    name: Unsloth API & Auth Tests
-    runs-on: windows-latest
-    timeout-minutes: 30
-    defaults:
-      run:
-        shell: bash
-    env:
-      GGUF_REPO: unsloth/gemma-3-270m-it-GGUF
-      GGUF_VARIANT: UD-Q4_K_XL
-      GGUF_FILE: gemma-3-270m-it-UD-Q4_K_XL.gguf
-      STUDIO_PORT: '18895'
-      HF_HOME: ${{ github.workspace }}/hf-cache
-      # Force UTF-8 for stdio (Windows defaults to cp1252; hf
-      # download prints a "✓" checkmark and crashes otherwise).
-      PYTHONIOENCODING: utf-8
-      PYTHONUTF8: '1'
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: '22'
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-
-      - name: Restore HF_HOME for ${{ env.GGUF_REPO }}
-        id: cache-hf
-        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        continue-on-error: true
-        with:
-          path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
-
-      - name: Prime HF_HOME with the GGUF
-        id: prime-hf
-        if: steps.cache-hf.outputs.cache-hit != 'true' || steps.cache-hf.outcome != 'success'
-        env:
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          python -m pip install --upgrade huggingface_hub
-          mkdir -p hf-cache
-          bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
-          bash .github/scripts/hf-download-with-retry.sh ggml-org/models tinyllamas/stories260K.gguf
-
-      - name: Save HF_HOME for ${{ env.GGUF_REPO }}
-        if: always() && steps.prime-hf.outcome == 'success'
-        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        with:
-          path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
-
-      - name: Pre-install Windows tweaks (npm 11 + Defender exclusions)
-        shell: pwsh
-        # See studio-windows-update-smoke.yml for the full rationale.
-        # tl;dr: setup.ps1 needs npm >=11 to skip a 35 s winget Node
-        # reinstall, and Defender's real-time scan dominates the
-        # frontend / uv-pip-extract steps.
-        run: |
-          $ProgressPreference = 'SilentlyContinue'
-          Write-Host "npm version before upgrade: $(npm -v)"
-          npm install -g 'npm@^11' 2>&1 | Out-Host
-          Write-Host "npm version after upgrade: $(npm -v)"
-          # NOTE: do NOT pre-create these directories. See
-          # studio-windows-update-smoke.yml for the full rationale --
-          # creating an empty studio/frontend/dist trips setup.ps1's
-          # mtime-based staleness check into "frontend up to date, skip
-          # rebuild" and Unsloth boots with an empty dist directory.
-          # Add-MpPreference accepts paths that do not yet exist.
-          foreach ($p in @(
-            "$env:USERPROFILE\.unsloth",
-            "$env:USERPROFILE\AppData\Local\uv",
-            "$env:GITHUB_WORKSPACE\studio\frontend\node_modules",
-            "$env:GITHUB_WORKSPACE\studio\frontend\dist"
-          )) {
-            try {
-              Add-MpPreference -ExclusionPath $p -ErrorAction Stop
-              Write-Host "Defender exclusion added: $p"
-            } catch {
-              Write-Host "Defender exclusion skipped ($($_.Exception.Message)): $p"
-            }
-          }
-
-      - name: Install Unsloth (--local, --no-torch)
-        shell: pwsh
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          New-Item -ItemType Directory -Force -Path logs | Out-Null
-          # *>&1 captures Write-Host (Information stream) output;
-          # plain 2>&1 does not. setup.ps1 emits "prebuilt installed
-          # and validated" via Write-Host, and we grep for that.
-          $ProgressPreference = 'SilentlyContinue'
-          & ./install.ps1 --local --no-torch *>&1 | Tee-Object -FilePath logs/install.log
-
-      - name: Assert install.ps1 used the Windows llama.cpp prebuilt
-        run: |
-          # Filesystem-based check (setup.ps1's stream output isn't
-          # captured back through this parent step's pipeline; see
-          # studio-windows-ui-smoke.yml for full explanation).
-          LLAMA_DIR=~/.unsloth/llama.cpp
-          INFO="$LLAMA_DIR/UNSLOTH_PREBUILT_INFO.json"
-          BIN="$LLAMA_DIR/build/bin/Release/llama-server.exe"
-          if grep -q "falling back to source build" logs/install.log; then
-            echo "::error::install.ps1 fell back to source-build llama.cpp on Windows."
-            grep -E "llama-prebuilt|llama.cpp" logs/install.log | tail -60
-            exit 1
-          fi
-          if [ ! -f "$INFO" ]; then
-            echo "::error::no UNSLOTH_PREBUILT_INFO.json at $INFO."
-            ls -la "$LLAMA_DIR" || true
-            exit 1
-          fi
-          if [ ! -f "$BIN" ]; then
-            echo "::error::no llama-server.exe at $BIN."
-            ls -la "$LLAMA_DIR/build/bin" || true
-            exit 1
-          fi
-          echo "install.ps1 installed the Windows prebuilt llama.cpp:"
-          cat "$INFO"
-
-      - name: Add Unsloth shim to GITHUB_PATH
-        # install.ps1's User-PATH update doesn't propagate to a
-        # running Git Bash session; export the shim dir so the
-        # next `unsloth ...` invocation finds it.
-        run: |
-          SHIM_DIR=~/.unsloth/studio/bin
-          if [ ! -f "$SHIM_DIR/unsloth.exe" ]; then
-            echo "::error::unsloth.exe shim not found at $SHIM_DIR"
-            ls -la ~/.unsloth/studio/ || true
-            exit 1
-          fi
-          cygpath -w "$SHIM_DIR" >> "$GITHUB_PATH"
-
-      - name: Install pyjwt for the JWT-expiry forge test
-        run: python -m pip install 'pyjwt>=2.6'
-
-      - name: Reset auth + boot Unsloth (API-only)
-        run: |
-          # Wipe (not reset-password): the boot below must re-seed a fresh .bootstrap_password.
-          rm -rf ~/.unsloth/studio/auth
-          mkdir -p logs
-          UNSLOTH_API_ONLY=1 unsloth studio -H 127.0.0.1 -p "$STUDIO_PORT" \
-            > logs/studio.log 2>&1 &
-          echo "STUDIO_PID=$!" >> "$GITHUB_ENV"
-
-      - name: Wait for /api/health
-        run: |
-          for i in $(seq 1 180); do
-            if curl -fs "http://127.0.0.1:${STUDIO_PORT}/api/health" > /tmp/health.json; then
-              jq -e '.status == "healthy"' /tmp/health.json && break
-            fi
-            sleep 1
-          done
-          jq -e '.status == "healthy"' /tmp/health.json
-
-      - name: Pass bootstrap password + rotated targets to the test
-        run: |
-          OLD=$(cat ~/.unsloth/studio/auth/.bootstrap_password)
-          NEW="ApiSmoke-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-          NEW2="ApiSmoke-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-          echo "::add-mask::$OLD"
-          echo "::add-mask::$NEW"
-          echo "::add-mask::$NEW2"
-          echo "STUDIO_OLD_PW=$OLD"  >> "$GITHUB_ENV"
-          echo "STUDIO_NEW_PW=$NEW"  >> "$GITHUB_ENV"
-          echo "STUDIO_NEW2_PW=$NEW2" >> "$GITHUB_ENV"
-
-      - name: Run Unsloth API & Auth tests
-        # Do NOT pin STUDIO_AUTH_DIR here. The Mac/Linux mirrors
-        # hardcode runner-specific paths (/Users/runner/...,
-        # /home/runner/...), but on Windows the path is
-        # C:\Users\runneradmin\.unsloth\studio\auth and varies by
-        # runner image. studio_api_smoke.py defaults to
-        # Path.home()/".unsloth"/"studio"/"auth" when the env is
-        # unset, which is correct on every OS.
-        env:
-          BASE_URL: http://127.0.0.1:18895
-        run: python tests/studio/studio_api_smoke.py
-
-      - name: Stop Unsloth
-        if: always()
-        run: |
-          kill "${STUDIO_PID}" 2>/dev/null || true
-          sleep 2
-
-      - name: Upload API smoke logs
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: windows-studio-api-smoke-log
-          path: |
-            logs/install.log
-            logs/studio.log
-          retention-days: 7

.github/workflows/studio-windows-ui-smoke.yml

@@ -1,414 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Windows counterpart to studio-ui-smoke.yml / studio-mac-ui-smoke.yml.
-# Same Playwright + Chromium end-to-end chat UI flow + extra UI flow,
-# but on the FREE windows-latest runner so we catch Windows-specific
-# regressions in the install path (install.ps1), the Unsloth CLI's
-# Windows process-management branches, and the llama.cpp prebuilt's
-# Windows HTTP layer.
-
-name: Windows Unsloth UI CI
-
-on:
-  pull_request:
-    paths:
-      - 'studio/**'
-      - 'unsloth/**'
-      - 'unsloth_cli/**'
-      - 'install.ps1'
-      - 'pyproject.toml'
-      - 'tests/studio/**'
-      - '.github/scripts/run-studio-permission-browser.sh'
-      - '.github/workflows/studio-windows-ui-smoke.yml'
-  push:
-    branches: [main, pip]
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  ui-smoke:
-    name: Chat UI Tests
-    runs-on: windows-latest
-    timeout-minutes: 45
-    # Default every step's shell to Git Bash. windows-latest's default
-    # shell is pwsh; without this each curl / heredoc / `kill $PID`
-    # step would need its own `shell: bash`. Steps that genuinely
-    # need PowerShell (install.ps1 invocation) override per-step.
-    defaults:
-      run:
-        shell: bash
-    env:
-      GGUF_REPO: unsloth/gemma-3-270m-it-GGUF
-      GGUF_VARIANT: UD-Q4_K_XL
-      GGUF_FILE: gemma-3-270m-it-UD-Q4_K_XL.gguf
-      STUDIO_PORT: '18896'
-      HF_HOME: ${{ github.workspace }}/hf-cache
-      # Force UTF-8 for stdio so Python tools (hf download, Unsloth
-      # CLI, etc.) can print Unicode characters like the success
-      # checkmark "✓". Windows defaults to cp1252 / charmap and
-      # any tool that prints "OK ✓" hits a UnicodeEncodeError.
-      PYTHONIOENCODING: utf-8
-      PYTHONUTF8: '1'
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: '22'
-          # No `cache: 'npm'`. setup-node's npm cache restore silently
-          # aborts the entire job on Windows runners when the npm cache
-          # path (`C:\npm\cache` per `npm config get cache`) doesn't yet
-          # exist on a fresh runner -- the step exits without an error
-          # message and every following step gets skipped. See
-          # npm/cli#7308. The frontend `npm ci` is fast enough without
-          # the cache that the reliability gain is worth the ~30s.
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          # No `cache: 'pip'`. install.ps1 / setup.ps1 use uv and
-          # never populate ~/.cache/pip; setup-python's post-step
-          # then fatal-errors with "Cache folder path is retrieved
-          # for pip but doesn't exist on disk".
-
-      - name: Restore HF_HOME for ${{ env.GGUF_REPO }}
-        id: cache-hf
-        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        continue-on-error: true
-        with:
-          path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
-
-      - name: Prime HF_HOME with the GGUF
-        id: prime-hf
-        if: steps.cache-hf.outputs.cache-hit != 'true' || steps.cache-hf.outcome != 'success'
-        env:
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          python -m pip install --upgrade huggingface_hub
-          mkdir -p hf-cache
-          bash .github/scripts/hf-download-with-retry.sh "$GGUF_REPO" "$GGUF_FILE"
-          bash .github/scripts/hf-download-with-retry.sh ggml-org/models tinyllamas/stories260K.gguf
-
-      - name: Save HF_HOME for ${{ env.GGUF_REPO }}
-        if: always() && steps.prime-hf.outcome == 'success'
-        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
-        with:
-          path: hf-cache
-          key: ${{ runner.os }}-hf-${{ env.GGUF_REPO }}-${{ env.GGUF_VARIANT }}-v2
-
-      - name: Pre-install Windows tweaks (npm 11 + Defender exclusions)
-        shell: pwsh
-        # See studio-windows-update-smoke.yml for the full rationale.
-        # tl;dr: setup.ps1 needs npm >=11 to skip a 35 s winget Node
-        # reinstall, and Defender's real-time scan dominates the
-        # frontend / uv-pip-extract steps.
-        run: |
-          $ProgressPreference = 'SilentlyContinue'
-          Write-Host "npm version before upgrade: $(npm -v)"
-          npm install -g 'npm@^11' 2>&1 | Out-Host
-          Write-Host "npm version after upgrade: $(npm -v)"
-          # NOTE: do NOT pre-create these directories. See
-          # studio-windows-update-smoke.yml for the full rationale --
-          # creating an empty studio/frontend/dist trips setup.ps1's
-          # mtime-based staleness check into "frontend up to date, skip
-          # rebuild" and Unsloth boots with an empty dist directory.
-          # Add-MpPreference accepts paths that do not yet exist.
-          foreach ($p in @(
-            "$env:USERPROFILE\.unsloth",
-            "$env:USERPROFILE\AppData\Local\uv",
-            "$env:GITHUB_WORKSPACE\studio\frontend\node_modules",
-            "$env:GITHUB_WORKSPACE\studio\frontend\dist"
-          )) {
-            try {
-              Add-MpPreference -ExclusionPath $p -ErrorAction Stop
-              Write-Host "Defender exclusion added: $p"
-            } catch {
-              Write-Host "Defender exclusion skipped ($($_.Exception.Message)): $p"
-            }
-          }
-
-      - name: Seed a legacy launch-studio.vbs (upgrade-cleanup check)
-        # Simulate a pre-hardening install so the post-install assertion below
-        # proves the installer DELETES an existing launch-studio.vbs (the exact
-        # Kaspersky-flagged file), not merely stops generating it.
-        shell: pwsh
-        run: |
-          $appDir = Join-Path $env:LOCALAPPDATA 'Unsloth Studio'
-          New-Item -ItemType Directory -Force -Path $appDir | Out-Null
-          Set-Content -LiteralPath (Join-Path $appDir 'launch-studio.vbs') -Value 'WScript.Echo "legacy"' -Encoding Unicode
-          Write-Host "seeded legacy launch-studio.vbs at $appDir"
-
-      - name: Install Unsloth (--local, --no-torch)
-        # install.ps1 is the supported Windows installer. install.sh
-        # has no Windows branch (apt-get / brew calls). The PS1
-        # script's `Install-UnslothStudio @args` line at the bottom
-        # forwards `--local --no-torch` correctly.
-        shell: pwsh
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          New-Item -ItemType Directory -Force -Path logs | Out-Null
-          # *>&1 redirects ALL PowerShell streams (stdout, stderr,
-          # warning, verbose, debug, information) into the success
-          # stream so Tee-Object captures everything. install.ps1
-          # and setup.ps1 emit step/substep markers via Write-Host
-          # which lands on the Information stream (PS 5+); without
-          # the wildcard redirect, those markers (including
-          # "prebuilt installed and validated") never reach
-          # logs/install.log and the post-step grep asserter fails.
-          $ProgressPreference = 'SilentlyContinue'
-          & ./install.ps1 --local --no-torch *>&1 | Tee-Object -FilePath logs/install.log
-
-      - name: Assert install.ps1 used the Windows llama.cpp prebuilt
-        run: |
-          # install.ps1's setup.ps1 child writes "prebuilt installed
-          # and validated" to its own console host -- that output
-          # does NOT come back through this parent step's stdout
-          # pipeline (no matter how aggressively we redirect: *>&1,
-          # tee, etc.). Verify the install via the filesystem
-          # instead. setup.ps1 writes UNSLOTH_PREBUILT_INFO.json
-          # next to the install dir on success, and lays the
-          # binaries under build/bin/Release/ on Windows.
-          STUDIO_HOME=~/.unsloth/studio
-          LLAMA_DIR=~/.unsloth/llama.cpp
-          INFO="$LLAMA_DIR/UNSLOTH_PREBUILT_INFO.json"
-          BIN="$LLAMA_DIR/build/bin/Release/llama-server.exe"
-          # Source-build fallback grep stays as a fast bail-out.
-          if grep -q "falling back to source build" logs/install.log; then
-            echo "::error::install.ps1 fell back to source-build llama.cpp on Windows."
-            grep -E "llama-prebuilt|llama.cpp" logs/install.log | tail -60
-            exit 1
-          fi
-          if [ ! -f "$INFO" ]; then
-            echo "::error::no UNSLOTH_PREBUILT_INFO.json at $INFO; setup.ps1 didn't install the prebuilt."
-            ls -la "$LLAMA_DIR" || true
-            exit 1
-          fi
-          if [ ! -f "$BIN" ]; then
-            echo "::error::no llama-server.exe at $BIN; prebuilt extraction incomplete."
-            ls -la "$LLAMA_DIR/build/bin" || true
-            ls -la "$LLAMA_DIR/build/bin/Release" || true
-            exit 1
-          fi
-          echo "install.ps1 installed the Windows prebuilt llama.cpp:"
-          cat "$INFO"
-
-      - name: Assert Unsloth launcher chain (no VBS, hidden PowerShell shortcut)
-        # The shortcut launch path is otherwise untested here (the steps below
-        # boot `unsloth studio` directly). Guard against re-introducing the VBS
-        # that tripped Kaspersky HEUR:Trojan.VBS.Agent.gen and against the .lnk
-        # pointing anywhere other than hidden PowerShell over launch-studio.ps1.
-        shell: pwsh
-        run: |
-          $appDir = Join-Path $env:LOCALAPPDATA 'Unsloth Studio'
-          if (Test-Path -LiteralPath (Join-Path $appDir 'launch-studio.vbs')) {
-            throw "regression: launch-studio.vbs exists (the Kaspersky VBS-FP shape)"
-          }
-          if (-not (Test-Path -LiteralPath (Join-Path $appDir 'launch-studio.ps1'))) {
-            throw "missing launch-studio.ps1 in $appDir"
-          }
-          $lnk = Join-Path ([Environment]::GetFolderPath('Desktop')) 'Unsloth Studio.lnk'
-          if (-not (Test-Path -LiteralPath $lnk)) {
-            $lnk = Join-Path $env:APPDATA 'Microsoft\Windows\Start Menu\Programs\Unsloth Studio.lnk'
-          }
-          if (-not (Test-Path -LiteralPath $lnk)) { throw "no Unsloth Studio.lnk on Desktop or Start Menu" }
-          $sc = (New-Object -ComObject WScript.Shell).CreateShortcut($lnk)
-          Write-Host "shortcut target: $($sc.TargetPath)"
-          Write-Host "shortcut args:   $($sc.Arguments)"
-          if ($sc.TargetPath -match 'wscript\.exe$') { throw "shortcut still targets wscript.exe (VBS host)" }
-          if ($sc.TargetPath -notmatch 'powershell\.exe$') { throw "unexpected shortcut target: $($sc.TargetPath)" }
-          if ($sc.Arguments -notmatch '-WindowStyle Hidden') {
-            throw "shortcut must launch windowless (-WindowStyle Hidden)"
-          }
-          Write-Host "launcher chain OK (no VBS; hidden powershell over launch-studio.ps1)"
-
-      - name: Launch Unsloth via the shortcut and assert health
-        # Run the exact command the .lnk stores (hidden PowerShell over
-        # launch-studio.ps1) and confirm it brings the backend up. This is the
-        # only step that proves the shortcut launch is not silently broken.
-        # Default port range is 8888-8908; the later UI tests use 18896/18897, so
-        # there is no conflict, and we tear this server down before they boot.
-        shell: pwsh
-        run: |
-          $lnk = Join-Path ([Environment]::GetFolderPath('Desktop')) 'Unsloth Studio.lnk'
-          if (-not (Test-Path -LiteralPath $lnk)) {
-            $lnk = Join-Path $env:APPDATA 'Microsoft\Windows\Start Menu\Programs\Unsloth Studio.lnk'
-          }
-          $sc = (New-Object -ComObject WScript.Shell).CreateShortcut($lnk)
-          Write-Host "launching: $($sc.TargetPath) $($sc.Arguments)"
-          Start-Process -FilePath $sc.TargetPath -ArgumentList $sc.Arguments -WorkingDirectory $sc.WorkingDirectory
-          $foundPort = 0
-          foreach ($i in 1..180) {
-            foreach ($port in 8888..8908) {
-              try {
-                $r = Invoke-RestMethod -Uri "http://127.0.0.1:$port/api/health" -TimeoutSec 1
-                if ($r.status -eq 'healthy' -and $r.service -eq 'Unsloth UI Backend') { $foundPort = $port; break }
-              } catch {}
-            }
-            if ($foundPort) { break }
-            Start-Sleep -Seconds 1
-          }
-          # Tear down the shortcut-launched server before the main UI tests boot.
-          try {
-            $owner = (Get-NetTCPConnection -LocalPort $foundPort -State Listen -ErrorAction Stop | Select-Object -First 1).OwningProcess
-            if ($owner) { taskkill /PID $owner /T /F 2>$null | Out-Null }
-          } catch {}
-          if (-not $foundPort) { throw "Unsloth did not become healthy when launched via the shortcut" }
-          Write-Host "Unsloth healthy on port $foundPort (launched via the shortcut)"
-
-      - name: Add Unsloth shim to GITHUB_PATH
-        # install.ps1 puts unsloth.exe at $StudioHome\bin\unsloth.exe
-        # and adds that dir to the User PATH via the Windows registry.
-        # Registry-level PATH updates don't propagate to a running
-        # Git Bash session, so the next step's `unsloth ...` invocation
-        # would hit "command not found". Re-export the shim dir to
-        # GITHUB_PATH so every subsequent step in this job sees it.
-        run: |
-          SHIM_DIR=~/.unsloth/studio/bin
-          if [ ! -f "$SHIM_DIR/unsloth.exe" ]; then
-            echo "::error::unsloth.exe shim not found at $SHIM_DIR"
-            ls -la ~/.unsloth/studio/ || true
-            exit 1
-          fi
-          # GITHUB_PATH wants Windows-style paths; convert via cygpath.
-          cygpath -w "$SHIM_DIR" >> "$GITHUB_PATH"
-          echo "Added Unsloth shim dir to PATH: $(cygpath -w "$SHIM_DIR")"
-
-      - name: Install Playwright + Chromium
-        # No --with-deps on Windows: that flag installs Linux apt
-        # packages. windows-latest ships the system frameworks
-        # Chromium needs (Edge / WebView2) already.
-        run: |
-          python -m pip install 'playwright>=1.45'
-          python -m playwright install chromium
-
-      - name: Reset auth + boot Unsloth
-        run: |
-          # Wipe (not reset-password): the boot below must re-seed a fresh .bootstrap_password.
-          rm -rf ~/.unsloth/studio/auth
-          mkdir -p logs
-          UNSLOTH_API_ONLY=1 unsloth studio -H 127.0.0.1 -p "$STUDIO_PORT" \
-            > logs/studio.log 2>&1 &
-          echo "STUDIO_PID=$!" >> "$GITHUB_ENV"
-
-      - name: Wait for /api/health
-        run: |
-          for i in $(seq 1 180); do
-            if curl -fs "http://127.0.0.1:${STUDIO_PORT}/api/health" > /tmp/health.json; then
-              jq -e '.status == "healthy"' /tmp/health.json && break
-            fi
-            sleep 1
-          done
-          jq -e '.status == "healthy"' /tmp/health.json
-
-      - name: Pass bootstrap password to the Playwright step
-        run: |
-          OLD=$(cat ~/.unsloth/studio/auth/.bootstrap_password)
-          NEW="CIUi-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-          NEW2="CIUi-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-          echo "::add-mask::$OLD"
-          echo "::add-mask::$NEW"
-          echo "::add-mask::$NEW2"
-          echo "STUDIO_OLD_PW=$OLD"   >> "$GITHUB_ENV"
-          echo "STUDIO_NEW_PW=$NEW"   >> "$GITHUB_ENV"
-          echo "STUDIO_NEW2_PW=$NEW2" >> "$GITHUB_ENV"
-
-      - name: Drive the chat UI with Playwright
-        env:
-          BASE_URL: http://127.0.0.1:18896
-          PW_ART_DIR: logs/playwright
-          STUDIO_UI_STRICT: '1'
-          # windows-latest free runner is 4 vCPU / 16 GB; gemma-3-
-          # 270m turn latency under llama-server's CPU backend can
-          # crowd the 180s default (slower than ubuntu-latest on
-          # the same model). Keep the same generous budget the Mac
-          # job uses.
-          STUDIO_UI_TURN_TIMEOUT_MS: '540000'
-        run: |
-          mkdir -p logs/playwright
-          python tests/studio/playwright_chat_ui.py
-
-      - name: Stop Unsloth (chat-ui ends with Shutdown click; this is belt-and-suspenders)
-        if: always()
-        run: |
-          kill "${STUDIO_PID}" 2>/dev/null || true
-          sleep 2
-
-      - name: Edge permission controls
-        run: |
-          bash .github/scripts/run-studio-permission-browser.sh 18895 chromium msedge
-
-      - name: Reset auth + boot Unsloth for extra UI tests (port 18897)
-        run: |
-          rm -rf ~/.unsloth/studio/auth
-          mkdir -p logs
-          UNSLOTH_API_ONLY=1 unsloth studio -H 127.0.0.1 -p 18897 \
-            > logs/studio_extra.log 2>&1 &
-          echo "STUDIO_EXTRA_PID=$!" >> "$GITHUB_ENV"
-
-      - name: Wait for /api/health on 18897
-        run: |
-          for i in $(seq 1 180); do
-            if curl -fs "http://127.0.0.1:18897/api/health" > /tmp/health2.json; then
-              jq -e '.status == "healthy"' /tmp/health2.json && break
-            fi
-            sleep 1
-          done
-          jq -e '.status == "healthy"' /tmp/health2.json
-
-      - name: Pass bootstrap pw for extra UI test
-        run: |
-          OLD=$(cat ~/.unsloth/studio/auth/.bootstrap_password)
-          NEW="CIUiExtra-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"
-          echo "::add-mask::$OLD"
-          echo "::add-mask::$NEW"
-          echo "STUDIO_EXTRA_OLD_PW=$OLD" >> "$GITHUB_ENV"
-          echo "STUDIO_EXTRA_NEW_PW=$NEW" >> "$GITHUB_ENV"
-
-      - name: Drive Compare/Recipes/Export/Unsloth/Settings with Playwright
-        env:
-          BASE_URL: http://127.0.0.1:18897
-          STUDIO_OLD_PW: ${{ env.STUDIO_EXTRA_OLD_PW }}
-          STUDIO_NEW_PW: ${{ env.STUDIO_EXTRA_NEW_PW }}
-          PW_ART_DIR: logs/playwright_extra
-          STUDIO_UI_STRICT: '1'
-          STUDIO_UI_TURN_TIMEOUT_MS: '540000'
-          GGUF_REPO: ${{ env.GGUF_REPO }}
-          GGUF_VARIANT: ${{ env.GGUF_VARIANT }}
-        run: |
-          mkdir -p logs/playwright_extra
-          python tests/studio/playwright_extra_ui.py
-
-      - name: Stop second Unsloth
-        if: always()
-        run: |
-          kill "${STUDIO_EXTRA_PID}" 2>/dev/null || true
-          sleep 2
-
-      - name: Upload Playwright artifacts
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: windows-studio-ui-smoke-artifacts
-          path: |
-            logs/studio.log
-            logs/studio_extra.log
-            logs/install.log
-            logs/playwright
-            logs/playwright-permissions-*
-            logs/playwright_extra
-            logs/studio-permissions-*.log
-          retention-days: 7

.github/workflows/studio-windows-update-smoke.yml

@@ -1,320 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Windows counterpart to studio-update-smoke.yml /
-# studio-mac-update-smoke.yml. Verifies that on the FREE
-# windows-latest runner:
-#
-#   1. install.ps1 --local --no-torch installs Unsloth AND auto-fetches
-#      the prebuilt llama.cpp Windows binary (app-<tag>-windows-x64-cpu
-#      from unslothai/llama.cpp). Hitting the source-build fallback is
-#      treated as an Unsloth bug -- Unsloth must always pick the
-#      prebuilt on Windows.
-#   2. unsloth studio update --local is idempotent. Two consecutive
-#      runs both report "prebuilt up to date and validated", no
-#      source-build fallback. The CLI's _find_setup_script picks
-#      setup.ps1 on Windows automatically.
-#   3. The installed Unsloth still boots and /api/health returns
-#      healthy after the update path.
-
-name: Windows Unsloth Update CI
-
-on:
-  pull_request:
-    paths:
-      - 'install.ps1'
-      - 'scripts/uninstall.ps1'
-      - 'studio/setup.ps1'
-      - 'studio/setup.bat'
-      - 'studio/install_python_stack.py'
-      - 'studio/install_llama_prebuilt.py'
-      - 'studio/backend/requirements/**'
-      - 'unsloth_cli/commands/studio.py'
-      - 'pyproject.toml'
-      - '.github/workflows/studio-windows-update-smoke.yml'
-  push:
-    branches: [main, pip]
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  update-idempotency:
-    name: Unsloth Updating Tests
-    runs-on: windows-latest
-    timeout-minutes: 30
-    defaults:
-      run:
-        shell: bash
-    env:
-      # Force UTF-8 for stdio (Windows defaults to cp1252; hf
-      # download / Unsloth CLI print "✓" checkmarks and crash
-      # otherwise).
-      PYTHONIOENCODING: utf-8
-      PYTHONUTF8: '1'
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: '22'
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          # Don't cache pip: install.ps1 + setup.ps1 go through uv
-          # and never populate ~/.cache/pip; setup-python's post-step
-          # then fatal-errors with "Cache folder path is retrieved
-          # for pip but doesn't exist on disk".
-
-      - name: Pre-install Windows tweaks (npm 11 + Defender exclusions)
-        shell: pwsh
-        # Two surgical fixes against measured Windows-only install
-        # waste (vs Mac/Linux on the same SHA):
-        #
-        # (1) npm. setup.ps1's Get-NodeDecision requires Node 22.12+
-        #     (or 20.19+ / 23+) AND npm >=11 because Vite 8 needs both.
-        #     actions/setup-node@v4 with `node-version: '22'` lands
-        #     Node 22.22.2 + the npm 10.9.7 it bundles, so the decision
-        #     is "bundled" and setup.ps1 downloads an isolated Node (~30
-        #     MB) we don't need on a runner that already has a fine Node.
-        #     `npm install -g npm@^11` updates the runner's npm in-place
-        #     in ~5 s, flipping the decision to "system" so setup.ps1
-        #     reuses the existing Node with no download.
-        #
-        # (2) Defender. windows-latest's real-time scan opens / hashes
-        #     every file Unsloth writes during install (Vite output =
-        #     thousands of small chunks, uv pip = wheel-extraction =
-        #     thousands of small files). The latency dominates the
-        #     200 s frontend build and the 90 s deps install. Adding
-        #     ExclusionPath entries for the directories the install
-        #     writes to drops per-file open latency from ~ms to ~us.
-        #     Add-MpPreference needs admin; the runneradmin user has
-        #     it, but wrap in try/catch so a permission flake leaves
-        #     the install otherwise unaffected.
-        run: |
-          $ProgressPreference = 'SilentlyContinue'
-          Write-Host "npm version before upgrade: $(npm -v)"
-          npm install -g 'npm@^11' 2>&1 | Out-Host
-          Write-Host "npm version after upgrade: $(npm -v)"
-          # NOTE: do NOT pre-create these directories before adding the
-          # exclusion -- creating an empty studio/frontend/dist trips
-          # setup.ps1 line 1281-1296's mtime-based "is the frontend
-          # stale?" check into "up to date, skip rebuild", because the
-          # newly-created dist's mtime is younger than every source
-          # file. Unsloth then boots with an empty dist and 500s on
-          # GET / with FileNotFoundError: dist\index.html. See run
-          # 25546676715 / job 74984469728.
-          # Add-MpPreference accepts paths that do not yet exist; the
-          # exclusion is registered and applies when the path
-          # materialises.
-          foreach ($p in @(
-            "$env:USERPROFILE\.unsloth",
-            "$env:USERPROFILE\AppData\Local\uv",
-            "$env:GITHUB_WORKSPACE\studio\frontend\node_modules",
-            "$env:GITHUB_WORKSPACE\studio\frontend\dist"
-          )) {
-            try {
-              Add-MpPreference -ExclusionPath $p -ErrorAction Stop
-              Write-Host "Defender exclusion added: $p"
-            } catch {
-              Write-Host "Defender exclusion skipped ($($_.Exception.Message)): $p"
-            }
-          }
-
-      - name: Install Unsloth (--local, --no-torch)
-        shell: pwsh
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          New-Item -ItemType Directory -Force -Path logs | Out-Null
-          # *>&1 captures Write-Host (Information stream) output;
-          # plain 2>&1 does not. setup.ps1 emits "prebuilt installed
-          # and validated" via Write-Host, and we grep for that.
-          $ProgressPreference = 'SilentlyContinue'
-          & ./install.ps1 --local --no-torch *>&1 | Tee-Object -FilePath logs/install.log
-
-      - name: Assert install.ps1 used the Windows llama.cpp prebuilt
-        run: |
-          # Filesystem-based check (setup.ps1's stream output isn't
-          # captured back through the parent pipeline).
-          LLAMA_DIR=~/.unsloth/llama.cpp
-          INFO="$LLAMA_DIR/UNSLOTH_PREBUILT_INFO.json"
-          BIN="$LLAMA_DIR/build/bin/Release/llama-server.exe"
-          if grep -q "falling back to source build" logs/install.log; then
-            echo "::error::install.ps1 fell back to source-build llama.cpp on Windows."
-            grep -E "llama-prebuilt|llama.cpp" logs/install.log | tail -60
-            exit 1
-          fi
-          if [ ! -f "$INFO" ]; then
-            echo "::error::no UNSLOTH_PREBUILT_INFO.json at $INFO."
-            ls -la "$LLAMA_DIR" || true
-            exit 1
-          fi
-          if [ ! -f "$BIN" ]; then
-            echo "::error::no llama-server.exe at $BIN."
-            ls -la "$LLAMA_DIR/build/bin" || true
-            exit 1
-          fi
-          echo "install.ps1 installed the Windows prebuilt llama.cpp:"
-          cat "$INFO"
-
-      - name: Add Unsloth shim to GITHUB_PATH
-        run: |
-          SHIM_DIR=~/.unsloth/studio/bin
-          if [ ! -f "$SHIM_DIR/unsloth.exe" ]; then
-            echo "::error::unsloth.exe shim not found at $SHIM_DIR"
-            ls -la ~/.unsloth/studio/ || true
-            exit 1
-          fi
-          cygpath -w "$SHIM_DIR" >> "$GITHUB_PATH"
-
-      - name: First update should be a no-op (prebuilt already validated)
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          set -o pipefail
-          unsloth studio update --local 2>&1 | tee logs/update.log
-          if grep -q "falling back to source build" logs/update.log; then
-            echo "::error::studio update fell back to source-build llama.cpp on Windows."
-            grep -E "llama-prebuilt|llama.cpp" logs/update.log | tail -60
-            exit 1
-          fi
-          if ! grep -qE "prebuilt up to date and validated|prebuilt installed and validated" logs/update.log; then
-            echo "::error::no prebuilt up-to-date marker in update.log."
-            grep -E "llama-prebuilt|llama.cpp" logs/update.log | tail -60
-            exit 1
-          fi
-          echo "update path took the prebuilt fast path"
-
-      - name: Update must keep the --no-torch install GGUF-only
-        run: |
-          # `unsloth studio update` exports no UNSLOTH_NO_TORCH, so setup.ps1 has
-          # to recover the mode from the install manifest. Without that it reads
-          # the missing torch as a stale venv and tries to delete the venv it is
-          # running out of, and the shared dependency pass pulls torch back in.
-          # The skip line only prints when the dependency pass actually runs, so
-          # don't demand it if the fast path short-circuited that pass.
-          if grep -q "running ordered dependency installation" logs/update.log \
-             && ! grep -q "skipping direct PyTorch and Triton installation (no-torch mode)" logs/update.log; then
-            echo "::error::studio update left no-torch mode; it would reinstall PyTorch."
-            grep -iE "no-torch|stale venv|PyTorch" logs/update.log | tail -40
-            exit 1
-          fi
-          PY="$HOME/.unsloth/studio/unsloth_studio/Scripts/python.exe"
-          if [ ! -f "$PY" ]; then
-            echo "::error::studio venv interpreter missing at $PY"
-            exit 1
-          fi
-          if "$PY" -c "import torch" 2>/dev/null; then
-            echo "::error::torch was reinstalled into the --no-torch venv."
-            exit 1
-          fi
-          echo "update preserved no-torch mode"
-
-      - name: Second update must also be a no-op
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Withheld on PR: this step runs checked-out PR code; public GGUF still downloads.
-          HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}
-        run: |
-          set -o pipefail
-          unsloth studio update --local 2>&1 | tee logs/update2.log
-          grep -q "falling back to source build" logs/update2.log && {
-              echo "::error::second update fell back to source build on Windows"
-              tail -60 logs/update2.log; exit 1; } || true
-          grep -qE "prebuilt up to date and validated|prebuilt installed and validated" logs/update2.log
-          echo "second update was clean"
-
-      - name: Boot Unsloth briefly to confirm the install is still usable
-        run: |
-          mkdir -p logs
-          UNSLOTH_API_ONLY=1 unsloth studio -H 127.0.0.1 -p 18891 \
-            > logs/studio.log 2>&1 &
-          PID=$!
-          HEALTHY=""
-          # Use jq (a Git Bash builtin) instead of `python -c
-          # open('/tmp/health.json')` to read the saved health
-          # response. Bash on windows-latest is MSYS Git Bash, which
-          # resolves `/tmp/...` against the MSYS root, while the
-          # python interpreter is Windows-native and resolves it
-          # against the current drive's root. The two paths don't
-          # agree, so python never finds the file curl just wrote.
-          # jq reads through MSYS, so the path matches. Mirrors what
-          # studio-windows-api-smoke.yml and the other Windows smoke
-          # workflows already do.
-          for i in $(seq 1 60); do
-            if curl -fs http://127.0.0.1:18891/api/health > /tmp/health.json; then
-              if jq -e '.status == "healthy"' /tmp/health.json >/dev/null; then
-                HEALTHY=1
-                break
-              fi
-            fi
-            sleep 1
-          done
-          if [ -z "$HEALTHY" ]; then
-            echo "Unsloth failed to come up after \`update\`"
-            tail -200 logs/studio.log
-            kill "$PID" 2>/dev/null || true
-            exit 1
-          fi
-          kill "$PID" 2>/dev/null || true
-          echo "post-update Unsloth /api/health OK"
-
-      - name: Uninstall and verify clean
-        # Round-trip through scripts/uninstall.ps1 against the default
-        # install tree at %USERPROFILE%\.unsloth\studio. Catches
-        # regressions where install.ps1 starts writing under a new key
-        # (registry, Start Menu, %APPDATA%) and scripts/uninstall.ps1 has
-        # not been updated to match. Skips gracefully if
-        # scripts/uninstall.ps1 has not landed yet (lets this workflow
-        # merge before #5513).
-        shell: pwsh
-        run: |
-          New-Item -ItemType Directory -Force -Path logs | Out-Null
-          if (-not (Test-Path "$PWD\scripts\uninstall.ps1")) {
-            Write-Host "scripts/uninstall.ps1 not present in this tree; skipping round-trip"
-            "" | Set-Content logs/uninstall.log
-            exit 0
-          }
-          pwsh -NoProfile -File "$PWD\scripts\uninstall.ps1" *>&1 | Tee-Object -FilePath logs/uninstall.log
-          $leak = 0
-          foreach ($p in @(
-            "$env:USERPROFILE\.unsloth\studio",
-            "$env:USERPROFILE\.unsloth\studio\unsloth_studio",
-            "$env:USERPROFILE\.unsloth\studio\bin\unsloth.exe"
-          )) {
-            if (Test-Path -LiteralPath $p) {
-              Write-Host "::error::leak: $p"
-              $leak++
-            }
-          }
-          if ($leak -gt 0) { exit 1 }
-          # Idempotency.
-          pwsh -NoProfile -File "$PWD\scripts\uninstall.ps1" *>&1 | Select-Object -Last 5
-          pwsh -NoProfile -File "$PWD\scripts\uninstall.ps1" *>&1 | Select-Object -Last 5
-          Write-Host "PASS: windows install -> update -> uninstall round-trip clean"
-
-      - name: Upload update logs
-        if: always()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: windows-studio-update-log
-          path: |
-            logs/install.log
-            logs/update.log
-            logs/update2.log
-            logs/studio.log
-            logs/uninstall.log
-          retention-days: 7

.github/workflows/version-compat-ci.yml

@@ -1,398 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-#
-# Cross-version compat canary for the four upstream packages whose
-# release cadence regularly breaks unsloth + unsloth-zoo:
-#
-#   1. vLLM             (LoRA worker manager, BnB loader, cumem allocator)
-#   2. TRL / GRPO       (trainer source rewriters in unsloth.models.rl*)
-#   3. PEFT             (LoraConfig, get_peft_model, LoraLayer, bnb integration)
-#   4. sentence-transformers (Transformer/Pooling/Normalize, Trainer)
-#   5. bitsandbytes     (Linear4bit, dequantize_4bit)
-#
-# Strategy: GitHub raw-fetch + symbol grep against every tracked
-# version (no pip install, CPU-only). When upstream renames a symbol
-# we depend on, the matching test fails BEFORE a user hits it. The
-# `main` branch entries give us a few-day lead on PyPI releases.
-#
-# Cross-references:
-#   tests/vllm_compat/test_vllm_pinned_symbols.py     (vLLM symbols)
-#   tests/version_compat/test_trl_grpo_pinned_symbols.py
-#   tests/version_compat/test_peft_pinned_symbols.py
-#   tests/version_compat/test_sentence_transformers_pinned_symbols.py
-#   tests/version_compat/test_bitsandbytes_pinned_symbols.py
-
-name: Version Compat CI
-
-on:
-  pull_request:
-    # Trigger on any unsloth source change, not just the three previously
-    # named files. The symbol-existence tests verify that EVERY pinned
-    # upstream reference in unsloth still resolves; a new
-    # `from peft.foo import Bar` added in unsloth/kernels/whatever.py
-    # is just as much a compat regression risk as one added in
-    # unsloth/models/rl.py.
-    paths:
-      - 'unsloth/**'
-      - 'tests/vllm_compat/**'
-      - 'tests/version_compat/**'
-      - 'pyproject.toml'
-      - '.github/workflows/version-compat-ci.yml'
-  schedule:
-    # Daily 06:43 UTC. Catches upstream PyPI releases roughly within
-    # 24 h. Off the :00 / :30 fleet-collision spots.
-    - cron: '43 6 * * *'
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  vllm-pinned-symbols:
-    name: vLLM pinned-symbol matrix (≥ 0.9.0 + main)
-    runs-on: ubuntu-latest
-    timeout-minutes: 12
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-      - name: Install pytest only
-        # The test fetches from raw.githubusercontent.com and greps
-        # source. No pip install of vllm / torch / transformers is
-        # needed — that's the whole point of this canary.
-        run: |
-          python -m pip install --upgrade pip
-          pip install 'pytest>=8'
-      - name: Run vllm-compat suite
-        env:
-          # Authenticated requests get a 5000-req/h quota on raw
-          # fetches; unauthenticated is 60/h and trips on the matrix.
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          python -m pytest tests/vllm_compat/test_vllm_pinned_symbols.py -v --tb=short
-
-  trl-grpo-pinned-symbols:
-    name: TRL / GRPO pinned-symbol matrix
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-      - name: Install pytest only
-        run: |
-          python -m pip install --upgrade pip
-          pip install 'pytest>=8'
-      - name: Run trl-compat suite
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          # PYTHONPATH=. so `from tests.version_compat._fetch import …`
-          # works without an editable install of unsloth itself.
-          PYTHONPATH=. python -m pytest \
-            tests/version_compat/test_trl_grpo_pinned_symbols.py \
-            -v --tb=short
-
-  peft-pinned-symbols:
-    name: PEFT pinned-symbol matrix (pyproject window + main)
-    runs-on: ubuntu-latest
-    timeout-minutes: 8
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-      - name: Install pytest only
-        run: |
-          python -m pip install --upgrade pip
-          pip install 'pytest>=8'
-      - name: Run peft-compat suite
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          PYTHONPATH=. python -m pytest \
-            tests/version_compat/test_peft_pinned_symbols.py \
-            tests/version_compat/test_unsloth_zoo_save_merged_pinned_symbols.py \
-            -v --tb=short
-
-  st-pinned-symbols:
-    name: sentence-transformers pinned-symbol matrix
-    runs-on: ubuntu-latest
-    timeout-minutes: 8
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-      - name: Install pytest only
-        run: |
-          python -m pip install --upgrade pip
-          pip install 'pytest>=8'
-      - name: Run sentence-transformers compat suite
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          PYTHONPATH=. python -m pytest \
-            tests/version_compat/test_sentence_transformers_pinned_symbols.py \
-            -v --tb=short
-
-  bitsandbytes-pinned-symbols:
-    name: bitsandbytes pinned-symbol matrix
-    runs-on: ubuntu-latest
-    timeout-minutes: 8
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-      - name: Install pytest only
-        run: |
-          python -m pip install --upgrade pip
-          pip install 'pytest>=8'
-      - name: Run bitsandbytes compat suite
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          PYTHONPATH=. python -m pytest \
-            tests/version_compat/test_bitsandbytes_pinned_symbols.py \
-            -v --tb=short
-
-  transformers-pinned-symbols:
-    name: transformers pinned-symbol matrix (4.57.6 + 5.x + main)
-    runs-on: ubuntu-latest
-    timeout-minutes: 12
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-      - name: Install pytest only
-        run: |
-          python -m pip install --upgrade pip
-          pip install 'pytest>=8'
-      - name: Run transformers compat suite
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          PYTHONPATH=. python -m pytest \
-            tests/version_compat/test_transformers_pinned_symbols.py \
-            -v --tb=short
-
-  # Optional second layer: actually `pip install` ONE representative
-  # version of each package and verify unsloth + unsloth-zoo modules
-  # import on it under the existing CUDA spoof. CPU-only, runs on
-  # ubuntu-latest. Catches the small set of breakages that the static
-  # symbol check misses (e.g. import-time side effects).
-  zoo-imports-under-spoof:
-    name: unsloth_zoo vllm/grpo/peft/st modules import under CUDA spoof
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-          path: unsloth
-      - name: Clone unsloth-zoo @ main
-        run: |
-          # github.com occasionally 500s on the git fetch; retry so a
-          # single upstream blip does not fail CI.
-          for attempt in 1 2 3; do
-            rm -rf "$RUNNER_TEMP/unsloth-zoo"
-            if git clone --depth=1 https://github.com/unslothai/unsloth-zoo \
-                "$RUNNER_TEMP/unsloth-zoo"; then
-              break
-            fi
-            if [ "$attempt" -eq 3 ]; then
-              echo "::error::git clone unsloth-zoo failed after 3 attempts"
-              exit 1
-            fi
-            delay=$((5 * attempt))
-            echo "::warning::clone failed (attempt $attempt/3), retrying in ${delay}s..."
-            sleep "$delay"
-          done
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-      - name: Install CPU torch + supported pkg pins
-        run: |
-          python -m pip install --upgrade pip
-          # CPU torch (vllm/peft/st all depend on it).
-          pip install --index-url https://download.pytorch.org/whl/cpu --extra-index-url https://pypi.org/simple \
-            'torch>=2.4,<2.11' 'torchvision<0.26' 'torchcodec<0.10'
-          # torchcodec is a hard requirement on transformers 5.x:
-          # transformers/audio_utils.py:55 does
-          #   `importlib.metadata.version("torchcodec")` UNCONDITIONALLY,
-          # which raises PackageNotFoundError on a CPU runner that
-          # otherwise has no audio path -- and that error trickles up
-          # through every `import unsloth_zoo.<module>` because
-          # unsloth-zoo's vision_utils transitively pulls
-          # transformers.processing_utils (-> audio_utils). The 0.10
-          # cap mirrors the torch 2.10 / torchvision 0.26 ABI window
-          # we already pin above.
-          # Ladder of supported floor versions per pyproject.toml.
-          pip install \
-            'transformers>=4.56,<5.6' 'trl>=0.22,<0.26' \
-            'peft>=0.18.0' 'sentence-transformers>=5.0' \
-            'accelerate>=1.0' 'datasets>=3.4,<5' \
-            'bitsandbytes>=0.45.5' \
-            sentencepiece protobuf safetensors numpy 'pytest>=8' \
-            'huggingface_hub>=0.34' tqdm packaging psutil triton Pillow
-          # Editable-install both repos so the test imports the
-          # checkouts (not whatever stale PyPI version pip resolved).
-          pip install --no-deps -e "$RUNNER_TEMP/unsloth-zoo"
-          pip install --no-deps -e ./unsloth
-      - name: Run vllm_compat zoo-imports tests under spoof
-        env:
-          UNSLOTH_IS_PRESENT: '1'
-          UNSLOTH_COMPILE_DISABLE: '1'
-          PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION: python
-        run: |
-          cd unsloth
-          # tests/vllm_compat/test_unsloth_zoo_imports.py: narrow vllm/grpo
-          #   import gates (5 tests).
-          # tests/vllm_compat/test_extended_module_imports.py: full sweep
-          #   of unsloth_zoo + unsloth.models.* modules + RL dispatch
-          #   table population + FastModel API surface under spoof
-          #   (~30 tests). Catches transformers / peft / bnb symbol pin
-          #   drift at module-top BEFORE any runtime call.
-          PYTHONPATH=. python -m pytest \
-            tests/vllm_compat/test_unsloth_zoo_imports.py \
-            tests/vllm_compat/test_extended_module_imports.py \
-            -v --tb=short
-
-  # Fake-CUDA GRPO/SFT/DPO patch run against REAL TRL (latest + main). Unlike
-  # the static symbol/source greps above, this drives unsloth's actual
-  # source-transform patchers (models/rl.py + rl_replacements.py) on a CPU-only
-  # runner under the tests/conftest.py spoof harness -- no GPU, no training.
-  # Catches structural TRL drift the greps miss (e.g. TRL 1.7.0's 2->3-tuple
-  # per-token-logps return, restructured PEFT ref-adapter block) by asserting
-  # the generated Unsloth trainer still satisfies the transform contracts.
-  grpo-fake-run:
-    name: GRPO fake-run (latest + main TRL, CPU spoof)
-    runs-on: ubuntu-latest
-    timeout-minutes: 18
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-          path: unsloth
-      - name: Clone unsloth-zoo @ main
-        run: |
-          for attempt in 1 2 3; do
-            rm -rf "$RUNNER_TEMP/unsloth-zoo"
-            if git clone --depth=1 https://github.com/unslothai/unsloth-zoo \
-                "$RUNNER_TEMP/unsloth-zoo"; then
-              break
-            fi
-            if [ "$attempt" -eq 3 ]; then
-              echo "::error::git clone unsloth-zoo failed after 3 attempts"
-              exit 1
-            fi
-            delay=$((5 * attempt))
-            echo "::warning::clone failed (attempt $attempt/3), retrying in ${delay}s..."
-            sleep "$delay"
-          done
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-      - name: Install CPU torch + ecosystem + TRL latest
-        run: |
-          python -m pip install --upgrade pip
-          pip install --index-url https://download.pytorch.org/whl/cpu --extra-index-url https://pypi.org/simple \
-            'torch>=2.4,<2.11' 'torchvision<0.26' 'torchcodec<0.10'
-          # Ecosystem floors unsloth needs; TRL itself is installed last so it
-          # can pull the transformers/peft it requires.
-          pip install \
-            'transformers>=4.57' 'peft>=0.18.0' 'accelerate>=1.0' 'datasets>=3.4,<5' \
-            'bitsandbytes>=0.45.5' sentencepiece protobuf safetensors numpy 'pytest>=8' \
-            'huggingface_hub>=0.34' tqdm packaging psutil triton Pillow
-          pip install --upgrade trl
-          pip install --no-deps -e "$RUNNER_TEMP/unsloth-zoo"
-          pip install --no-deps -e ./unsloth
-      - name: Fake-run vs TRL latest
-        env:
-          UNSLOTH_IS_PRESENT: '1'
-          UNSLOTH_COMPILE_DISABLE: '1'
-          # Disable dynamo/inductor at the process level, before conftest.py's early
-          # `import unsloth`, so the GRPO hot path never compiles on the GPU-less runner
-          # (defense in depth; the CPU fake-train also flips this at runtime).
-          TORCHDYNAMO_DISABLE: '1'
-          TORCH_COMPILE_DISABLE: '1'
-          PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION: python
-        run: |
-          cd unsloth
-          python -c "import trl; print('Resolved TRL', trl.__version__)"
-          PYTHONPATH=. python -m pytest \
-            tests/version_compat/test_trl_grpo_fake_run.py \
-            tests/version_compat/test_trl_fake_train_cpu.py \
-            -v --tb=short
-      # `main` is scheduled/dispatch-only so PR jobs stay fast and a bleeding-edge
-      # TRL break does not red every PR. github.event_name is valid in a step if.
-      - name: Fake-run vs TRL main (scheduled / dispatch only)
-        if: ${{ github.event_name != 'pull_request' }}
-        env:
-          UNSLOTH_IS_PRESENT: '1'
-          UNSLOTH_COMPILE_DISABLE: '1'
-          TORCHDYNAMO_DISABLE: '1'
-          TORCH_COMPILE_DISABLE: '1'
-          PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION: python
-        run: |
-          pip install --upgrade "git+https://github.com/huggingface/trl"
-          cd unsloth
-          python -c "import trl; print('Resolved TRL', trl.__version__)"
-          PYTHONPATH=. python -m pytest \
-            tests/version_compat/test_trl_grpo_fake_run.py \
-            tests/version_compat/test_trl_fake_train_cpu.py \
-            -v --tb=short
-
-  # Daily-only: same suites but with --strict on importable upstream
-  # tags. Schedule-only so PR jobs stay fast; cron tolerates a flake.
-  daily-fresh-fetch:
-    name: daily fresh-fetch sweep (cron only)
-    if: ${{ github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' }}
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-          cache: 'pip'
-      - name: Install pytest
-        run: pip install 'pytest>=8'
-      - name: Run all version-compat suites in one process (no cache)
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          PYTHONPATH=. python -m pytest \
-            tests/vllm_compat/test_vllm_pinned_symbols.py \
-            tests/version_compat/ \
-            -v --tb=short

.github/workflows/wheel-smoke.yml

@@ -1,161 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-# Builds the PyPI wheel from the PR branch, then verifies the built wheel
-# actually contains what we expect to ship and does NOT contain the broken
-# Unsloth bundle that 2026.5.1 published. This is the single workflow that
-# would have blocked the 2026.5.1 release before twine upload.
-#
-# Verified locally end-to-end against this branch:
-#   - python -m build produces unsloth-<version>-py3-none-any.whl in 13s
-#   - wheel content sanity passes:
-#       lockfile shipped, frontend dist shipped,
-#       no node_modules in wheel, no bun.lock in wheel,
-#       main bundle has unstable_Provider hits=1 (assistant-ui internals only).
-#   - Unsloth backend imports cleanly from the installed wheel with the
-#     lightweight dep set below.
-
-name: Wheel CI
-
-on:
-  pull_request:
-    paths:
-      - 'pyproject.toml'
-      - 'studio/**'
-      - 'unsloth/**'
-      - 'unsloth_cli/**'
-      - '.github/workflows/wheel-smoke.yml'
-  push:
-    branches: [main, pip]
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  wheel:
-    name: Wheel build + content sanity + import smoke
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
-        with:
-          persist-credentials: false
-
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
-        with:
-          node-version: '22'
-
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
-        with:
-          python-version: '3.12'
-
-      - name: Lockfile supply-chain audit (pre-install scan)
-        run: python3 scripts/lockfile_supply_chain_audit.py
-
-      - name: Build frontend
-        # Lifecycle scripts (esbuild native-binary postinstall, etc.) are
-        # required for `vite build`. The pre-install lockfile structural
-        # audit (lockfile_supply_chain_audit.py) is the practical defence
-        # against the npm postinstall-dropper class -- it fires BEFORE any
-        # tarball runs, on the injection pattern itself rather than an
-        # advisory-DB lookup.
-        run: |
-          cd studio/frontend
-          npm ci --no-fund --no-audit
-          npm run build
-
-      - name: Build wheel + sdist
-        run: |
-          python -m pip install --upgrade pip build
-          rm -rf dist build ./*.egg-info
-          python -m build
-
-      - name: Wheel content sanity
-        run: |
-          python - <<'PY'
-          import zipfile, glob, sys
-          w = glob.glob("dist/unsloth-*.whl")
-          if not w:
-              print("FAIL: no wheel produced"); sys.exit(2)
-          w = w[0]
-          print(f"wheel: {w}")
-          with zipfile.ZipFile(w) as z:
-              n = z.namelist()
-              checks = {
-                "lockfile shipped":      any(s.endswith("studio/frontend/package-lock.json") for s in n),
-                "frontend dist shipped": any(s.endswith("studio/frontend/dist/index.html")    for s in n),
-                "no node_modules":       not any("studio/frontend/node_modules/" in s for s in n),
-                "no bun.lock":           not any(s.endswith("studio/frontend/bun.lock")       for s in n),
-              }
-              js = [s for s in n
-                    if "studio/frontend/dist/assets/" in s
-                    and s.endswith(".js")
-                    and "/index-" in s]
-              if not js:
-                  print("FAIL: no main bundle index-*.js in wheel"); sys.exit(2)
-              data = z.read(js[0]).decode("utf-8", "replace")
-              hits = data.count("unstable_Provider:")
-              print(f"main bundle: {js[0]}")
-              print(f"unstable_Provider hits: {hits} (>=4 indicates 2026.5.1 regression)")
-              checks["bundle has no Unsloth unstable_Provider call site"] = (hits < 4)
-
-              print()
-              for k, v in checks.items():
-                  print(f"  [{'PASS' if v else 'FAIL'}] {k}")
-              sys.exit(0 if all(checks.values()) else 1)
-          PY
-
-      - name: Unsloth backend import smoke
-        # Imports `studio.backend.main:app` from the freshly-installed wheel in
-        # a clean venv. This catches the class of bug that 2026.5.1 shipped with:
-        # frontend dist missing, package-lock.json missing, or the wheel's Python
-        # source tree broken in a way that surfaces only at app construction time.
-        run: |
-          python -m venv /tmp/v
-          /tmp/v/bin/pip install --upgrade pip
-          /tmp/v/bin/pip install -r studio/backend/requirements/studio.txt
-          /tmp/v/bin/pip install \
-            python-multipart aiofiles sqlalchemy cryptography \
-            pyyaml jinja2 mammoth unpdf requests \
-            'numpy<3'
-          /tmp/v/bin/pip install --no-deps dist/unsloth-*.whl
-          # Run from /tmp so Python imports the installed package, not the source tree.
-          cd /tmp
-          /tmp/v/bin/python -c "from studio.backend.main import app; print('Unsloth backend OK:', app.title)"
-
-      - name: CLI without the Studio stack guides instead of tracebacking
-        # The smoke above installs studio.txt first, so it cannot catch a wheel
-        # that ships studio/ without declaring what it imports (#4701, #5260,
-        # #7147). Drop only structlog to reuse that venv without a re-download.
-        run: |
-          set -eu
-          /tmp/v/bin/pip uninstall -y structlog >/dev/null
-          cd /tmp
-          status=0
-          for args in "export ./nope ./out" "list-checkpoints"; do
-            echo "--- unsloth $args"
-            out=$(/tmp/v/bin/unsloth $args 2>&1 || true)
-            printf '%s\n' "$out"
-            case "$out" in
-              *Traceback*)
-                echo "FAIL: raw traceback instead of guidance"; status=1 ;;
-            esac
-            case "$out" in
-              *'unsloth studio update'*) ;;
-              *) echo "FAIL: no remediation in the message"; status=1 ;;
-            esac
-          done
-          /tmp/v/bin/pip install -q structlog >/dev/null
-          exit "$status"
-
-      - name: Upload wheel on failure
-        if: failure()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
-        with:
-          name: unsloth-wheel
-          path: dist/
-          retention-days: 7

.gitignore

@@ -3,16 +3,12 @@ __pycache__/
 *.py[cod]
 *.class
 unsloth_compiled_cache/
-# Notebook-validator runtime PyPI metadata cache (CI repopulates).
-scripts/data/pypi_cache/
 # ML artifacts (large files)
 feature/
 outputs/
 exports/
 /datasets/
 studio/backend/assets/datasets/
-# Generated async worker / reviewer transcripts (never part of the product).
-studio/backend/async_task_outputs/
 unsloth_training_checkpoints/
 *.gguf
 *.safetensors
@@ -28,8 +24,8 @@ dist/
 downloads/
 eggs/
 .eggs/
-/lib/
-/lib64/
+lib/
+lib64/
 parts/
 sdist/
 var/
@@ -208,21 +204,6 @@ tmp/
 **/node_modules/
 auth.db
 
-# Packaging snapshot of the root CHANGELOG.md (written by build.sh)
-studio/CHANGELOG.md
-
-# Tauri local build/generated output
-studio/src-tauri/target/
-studio/src-tauri/gen/
-studio/src-tauri/artifacts/
-studio/src-tauri/icons/android/
-studio/src-tauri/icons/ios/
-studio/src-tauri/icons/128x128@2x.png
-studio/src-tauri/icons/64x64.png
-studio/src-tauri/icons/Square*Logo.png
-studio/src-tauri/icons/StoreLogo.png
-studio/src-tauri/icons/squarehq.png
-
 # Local working docs
 **/CLAUDE.md
 **/claude.md
@@ -234,12 +215,4 @@ log.txt
 setup_leo.sh
 server.pid
 *.log
-# Ignore stray lockfiles; real npm projects opt back in below (npm ci needs them).
 package-lock.json
-!studio/frontend/package-lock.json
-!studio/backend/core/data_recipe/oxc-validator/package-lock.json
-!studio/package-lock.json
-llama.cpp/
-# Stray "~" dir some tools create from a literal ~ TMPDIR; never part of the repo.
-~/
-/temp/

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.18
+    rev: v0.15.10
     hooks:
       - id: ruff
         args:
@@ -14,20 +14,5 @@ repos:
         entry: scripts/run_ruff_format.py
         language: python
         types: [python]
-        # Mirror ruff's [tool.ruff] extend-exclude so this hook does not
-        # half-process files ruff itself skips (which produced churn).
-        exclude: '(chat_templates|ollama_template_mappers|_auto_install|mapper)\.py$'
         additional_dependencies:
           - ruff==0.6.9
-      # Re-pins allowScripts entries after dependency bumps. pre-commit.ci
-      # pushes the fix to PR branches, Dependabot's included, so stale pins
-      # heal without a human in the loop.
-      - id: sync-allow-scripts-pins
-        name: Sync allowScripts pins with the frontend lockfile
-        # `python <script>` not a direct exec: autofix commits can drop the
-        # executable bit, which kills shebang-style entries.
-        entry: python scripts/sync_allow_scripts_pins.py
-        args: [--fix]
-        language: python
-        files: ^studio/frontend/(package\.json|package-lock\.json)$
-        pass_filenames: false

CHANGELOG.md

@@ -1,88 +0,0 @@
-# Changelog
-
-Release notes for Unsloth and Unsloth Studio.
-
-Unsloth Studio reads this file to show release notes inside the "New Unsloth
-version" update popup. Edit it here and the popup picks the change up on the
-next update check, with no release or rebuild required.
-
-## Format
-
-Every release is a level-2 heading whose first token is the version, optionally
-followed by a date:
-
-```md
-## 2026.7.6 - 2026-07-22
-```
-
-`## [2026.7.6] - 2026-07-22` and `## v2026.7.6` also work. Everything under a
-heading, up to the next level-2 heading, is that release's notes and renders as
-Markdown in the popup.
-
-Notes are matched to one exact version. When Studio offers an update to
-`2026.7.6` it renders the `2026.7.6` section and nothing else. If that section
-is missing, the popup links out to the online changelog rather than showing
-notes from an unrelated release, so a new version needs its own section here
-before its notes can appear.
-
-Keep the newest release at the top. Lead each bullet with the change itself:
-the collapsed popup highlights the first sentence and dims the rest.
-`## Unreleased` is ignored by the popup, so it is safe to stage notes there and
-rename the heading at release time.
-
-<!-- Add new releases directly below this line. -->
-
-## Unreleased
-
-## 2026.7.5
-
-### What's Changed
-
-- AMD support is here. Train, run RL, chat with and deploy 500+ models on
-  Radeon, Instinct, Ryzen and data center GPUs across Windows, WSL and Linux,
-  up to 2x faster with 70% less VRAM and no accuracy loss.
-- Intel XPU support lands in Studio, so Arc and Data Center GPUs run chat and
-  training alongside the NVIDIA, AMD and Apple paths.
-- Local speech to text dictation runs fully offline, with slim Whisper bundles
-  and a picker for custom models.
-- DoRA training is available in Studio, selectable next to LoRA and full
-  fine-tuning in the training tab.
-- The update popup previews release notes inline, pulled from this file and
-  matched to the exact version being offered.
-
-### AMD, 23 July update
-
-Our AMD collaboration, custom Triton kernels and math algorithms bring local
-training and inference to AMD hardware. The 23 July update builds on the
-[AMD release](https://github.com/unslothai/unsloth/releases/tag/v0.1.501-beta):
-
-- RDNA2 and Gorgon Halo are supported, and the installer no longer fails to
-  detect GPUs on Strix Halo and other AMD cards.
-- RDNA4 handling is better, and HIP and ROCm failures are caught and fixed
-  automatically instead of stopping the install.
-- Unified memory safetensors loading is 2x faster, with much faster gradient
-  checkpointing on unified memory devices.
-- Voice dictation through whisper.cpp has preliminary support.
-- Rollback environments left by installs no longer eat 5GB of disk. They are
-  cleaned up automatically.
-
-Optimized ROCm builds cover GGUF and safetensors inference, and ROCm
-compatibility is improved for MI300X and MI325X. Full guide:
-[unsloth.ai/docs/basics/amd](https://unsloth.ai/docs/basics/amd).
-
-### Running larger models
-
-- Automatic GPU placement, or pick exactly which GPUs and layers to use.
-- Move MoE expert layers into system memory so larger models fit.
-- Split a model across several GPUs, or use tensor parallelism.
-- Hardware settings are saved per model and quant.
-
-### Also in this release
-
-- Remote access with `unsloth studio --secure` over free HTTPS via Cloudflare.
-- Web search reads PDF papers and manuals, and parallel tool calls, reasoning
-  output and tool retries are more reliable.
-- The model download location is configurable, so weights can live on a second
-  drive instead of the default cache.
-- Stalled Hugging Face XET downloads retry over standard HTTP, and existing
-  GGUF files are reused instead of downloaded again.

CONTRIBUTING.md

@@ -27,9 +27,3 @@ Your support extends beyond code:
 Finally, please be mindful of our [Code of Conduct](https://github.com/unslothai/unsloth/blob/main/CODE_OF_CONDUCT.md) to ensure a welcoming and inclusive environment for everyone.
 
 Thank you so much for reading and we hope you have lots of fun using Unsloth! 🦥
-
-
-## Pull Request Guidelines
-- Keep PRs focused on a single change
-- Include a concise description and motivation
-- Link related issues when applicable

MANIFEST.in

@@ -1,2 +0,0 @@
-include _changelog_build.py
-include CHANGELOG.md

README.md

@@ -1,99 +1,46 @@
 <h1 align="center" style="margin:0;">
   <a href="https://unsloth.ai/docs"><picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/unslothai/unsloth/main/images/unsloth%20logo%20white%20text.png">
-    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/unslothai/unsloth/main/images/unsloth%20logo%20black%20text.png">
-    <img alt="Unsloth logo" src="https://raw.githubusercontent.com/unslothai/unsloth/main/images/unsloth%20logo%20black%20text.png" height="80" style="max-width:100%;">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/unslothai/unsloth/main/images/STUDIO%20WHITE%20LOGO.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/unslothai/unsloth/main/images/STUDIO%20BLACK%20LOGO.png">
+    <img alt="Unsloth logo" src="https://raw.githubusercontent.com/unslothai/unsloth/main/images/STUDIO%20BLACK%20LOGO.png" height="60" style="max-width:100%;">
   </picture></a>
 </h1>
 <h3 align="center" style="margin: 0; margin-top: 0;">
-Unsloth Studio lets you run and train models locally.
+Run and train AI models with a unified local interface.
 </h3>
 
 <p align="center">
   <a href="#-features">Features</a> •
-  <a href="#-unsloth-news">News</a> •
-  <a href="#-install">Quickstart</a> •
+  <a href="#-quickstart">Quickstart</a> •
   <a href="#-free-notebooks">Notebooks</a> •
-  <a href="https://unsloth.ai/docs">Documentation</a>
+  <a href="https://unsloth.ai/docs">Documentation</a> •
+  <a href="https://www.reddit.com/r/unsloth/">Reddit</a>
 </p>
-<br>
-<a href="https://unsloth.ai/docs/new/studio">
-<img alt="unsloth studio ui homepage" src="https://github.com/user-attachments/assets/53ae17a9-d975-44ef-9686-efb4ebd0454d" style="max-width: 100%; margin-bottom: 0;"></a>
+ <a href="https://unsloth.ai/docs/new/studio">
+<img alt="unsloth studio ui homepage" src="https://raw.githubusercontent.com/unslothai/unsloth/main/studio/frontend/public/studio%20github%20landscape%20colab%20display.png" style="max-width: 100%; margin-bottom: 0;"></a>
 
-## ⚡ Get started
-
-#### macOS, Linux, WSL:
-```bash
-curl -fsSL https://unsloth.ai/install.sh | sh
-```
-#### Windows:
-```powershell
-irm https://unsloth.ai/install.ps1 | iex
-```
-#### Community:
-
-- [Discord](https://discord.gg/unsloth)
-- [𝕏 (Twitter)](https://x.com/UnslothAI)
-- [Reddit](https://reddit.com/r/unsloth)
-
-## ⭐ Features
 Unsloth Studio (Beta) lets you run and train text, [audio](https://unsloth.ai/docs/basics/text-to-speech-tts-fine-tuning), [embedding](https://unsloth.ai/docs/new/embedding-finetuning), [vision](https://unsloth.ai/docs/basics/vision-fine-tuning) models on Windows, Linux and macOS.
 
+## ⭐ Features
+Unsloth provides several key features for both inference and training:
 ### Inference
 * **Search + download + run models** including GGUF, LoRA adapters, safetensors
 * **Export models**: [Save or export](https://unsloth.ai/docs/new/studio/export) models to GGUF, 16-bit safetensors and other formats.
 * **Tool calling**: Support for [self-healing tool calling](https://unsloth.ai/docs/new/studio/chat#auto-healing-tool-calling) and web search
 * **[Code execution](https://unsloth.ai/docs/new/studio/chat#code-execution)**: lets LLMs test code in Claude artifacts and sandbox environments
-* **[API inference endpoint](https://unsloth.ai/docs/basics/api)**: Deploy and run local LLMs in Claude Code, Codex tools with Unsloth
-* [Auto set inference settings](https://unsloth.ai/docs/new/studio/chat#auto-parameter-tuning) and customize chat templates.
-* We work directly with teams behind [gpt-oss](https://docs.unsloth.ai/new/gpt-oss-how-to-run-and-fine-tune#unsloth-fixes-for-gpt-oss), [Qwen3](https://www.reddit.com/r/LocalLLaMA/comments/1kaodxu/qwen3_unsloth_dynamic_ggufs_128k_context_bug_fixes/), [Llama 4](https://github.com/ggml-org/llama.cpp/pull/12889), [Mistral](https://huggingface.co/mistralai/Mistral-Medium-3.5-128B/discussions/18), [Gemma 1-3](https://news.ycombinator.com/item?id=39671146), and [Phi-4](https://unsloth.ai/blog/phi4), where we’ve fixed bugs that improve model accuracy.
-* Chat with images, audio, PDFs, code, DOCX and more. [Connect API providers](https://unsloth.ai/docs/integrations/connections) (OpenAI, Anthropic) or servers (vLLM, Ollama).
-* [**Compare any two models**](https://unsloth.ai/docs/new/studio/chat#model-arena) side by side with the same prompt.
-* **OpenAI/Anthropic-compatible APIs**: Serve local models through `/v1/chat/completions`, `/v1/responses` and `/v1/messages`.
-* **Connect local models to agents**: Use `unsloth start` with Claude Code, Codex, Hermes and more.
-* **Web/PDF search** can read PDF papers, manuals and other PDF results.
-* **GGUF hardware controls**: Choose GPUs/layers, offload MoE experts, use multi-GPU or Tensor Parallelism.
-* The opt-in **MCP control endpoint** lets AI clients manage models, training, recipes and exports.
+* [Auto-tune inference parameters](https://unsloth.ai/docs/new/studio/chat#auto-parameter-tuning) and customize chat templates.
+* We work directly with teams behind [gpt-oss](https://docs.unsloth.ai/new/gpt-oss-how-to-run-and-fine-tune#unsloth-fixes-for-gpt-oss), [Qwen3](https://www.reddit.com/r/LocalLLaMA/comments/1kaodxu/qwen3_unsloth_dynamic_ggufs_128k_context_bug_fixes/), [Llama 4](https://github.com/ggml-org/llama.cpp/pull/12889), [Mistral](models/tutorials/devstral-how-to-run-and-fine-tune.md), [Gemma 1-3](https://news.ycombinator.com/item?id=39671146), and [Phi-4](https://unsloth.ai/blog/phi4), where we’ve fixed bugs that improve model accuracy.
+* Upload images, audio, PDFs, code, DOCX and more file types to chat with.
 ### Training
-* Train and RL **500+ models** up to **2x faster** with **70% less VRAM**; MoE up to **12x faster**.
-* Train and run RL on [AMD GPUs](https://unsloth.ai/docs/basics/amd) across Windows, WSL and Linux.
+* Train and RL **500+ models** up to **2x faster** with up to **70% less VRAM**, with no accuracy loss.
+* Custom Triton and mathematical **kernels**. See some collabs we did with [PyTorch](https://unsloth.ai/docs/get-started/reinforcement-learning-rl-guide/fp8-reinforcement-learning) and [Hugging Face](https://unsloth.ai/docs/new/faster-moe).
 * **Data Recipes**: [Auto-create datasets](https://unsloth.ai/docs/new/studio/data-recipe) from **PDF, CSV, DOCX** etc. Edit data in a visual-node workflow.
-* **[Reinforcement Learning](https://unsloth.ai/docs/get-started/reinforcement-learning-rl-guide)** uses **80% less VRAM** for GRPO, FP8 and vision RL, with 7x longer contexts.
-* [**Long-context training**](https://unsloth.ai/docs/new/3x-faster-training-packing): **3x faster**, 30% less VRAM and 500K+ context.
-* Supports LoRA/QLoRA, full fine-tuning, RL, pretraining, 4-bit, 16-bit and FP8.
-* Custom Triton and mathematical **kernels** built with PyTorch and Hugging Face.
+* **[Reinforcement Learning](https://unsloth.ai/docs/get-started/reinforcement-learning-rl-guide)** (RL): The most efficient [RL](https://unsloth.ai/docs/get-started/reinforcement-learning-rl-guide) library, using **80% less VRAM** for GRPO, [FP8](https://unsloth.ai/docs/get-started/reinforcement-learning-rl-guide/fp8-reinforcement-learning) etc.
+* Supports full fine-tuning, RL, pretraining, 4-bit, 16-bit and, FP8 training.
 * **Observability**: Monitor training live, track loss and GPU usage and customize graphs.
 * [Multi-GPU](https://unsloth.ai/docs/basics/multi-gpu-training-with-unsloth) training is supported, with major improvements coming soon.
 
-## 🚀 Unsloth Start
-
-[Unsloth Start](https://unsloth.ai/docs/integrations/unsloth-start) connects [Claude Code](https://unsloth.ai/docs/basics/claude-code), [Codex](https://unsloth.ai/docs/basics/codex) and other agents to local models with one command.
-
-Start Unsloth, load a model, open your project folder, then run:
-
-```bash
-unsloth start claude
-```
-
-Replace `claude` with any supported agent:
-
-| Agent | Command |
-| --- | --- |
-| Claude Code | `unsloth start claude` |
-| OpenAI Codex | `unsloth start codex` |
-| Hermes Agent | `unsloth start hermes` |
-| OpenClaw | `unsloth start openclaw` |
-| OpenCode | `unsloth start opencode` |
-| Pi Coding Agent | `unsloth start pi` |
-
-Claude Code, Codex, OpenCode and Pi can keep their current model and use Unsloth as a local
-subagent:
-
-```bash
-unsloth start claude --as-subagent --model unsloth/model-GGUF:quant
-```
-
-## 📥 Install
+## ⚡ Quickstart
 Unsloth can be used in two ways: through **[Unsloth Studio](https://unsloth.ai/docs/new/studio/)**, the web UI, or through **Unsloth Core**, the code-based version. Each has different requirements.
 
 ### Unsloth Studio (web UI)
@@ -101,46 +48,30 @@ Unsloth Studio (Beta) works on **Windows, Linux, WSL** and **macOS**.
 
 * **CPU:** Supported for Chat and Data Recipes currently
 * **NVIDIA:** Training works on RTX 30/40/50, Blackwell, DGX Spark, Station and more
-* **macOS:** Training, MLX and GGUF inference are ALL supported.
-* **AMD:** Training, RL, chat and deployment work on Windows, WSL and Linux. [Read the AMD guide](https://unsloth.ai/docs/basics/amd).
-* **Vulkan:** GGUF inference is supported on [compatible GPUs, including Intel GPUs](https://github.com/unslothai/unsloth/pull/5819). Vulkan accelerates GGUF inference only; training still requires a supported PyTorch or MLX backend.
+* **macOS:** Currently supports chat and Data Recipes. **MLX training** is coming very soon
+* **AMD:** Chat + Data works. Train with [Unsloth Core](#unsloth-core-code-based). Studio support is out soon.
+* **Coming soon:** Training support for Apple MLX, AMD, and Intel.
 * **Multi-GPU:** Available now, with a major upgrade on the way
 
 #### macOS, Linux, WSL:
 ```bash
 curl -fsSL https://unsloth.ai/install.sh | sh
 ```
-Use the same command to update.
-
-To force the Vulkan llama.cpp backend, set `UNSLOTH_FORCE_VULKAN=1` **before installing or updating**. The setting selects the llama.cpp binary bundle, so setting it only when launching Studio cannot replace an existing CPU bundle:
-
-```bash
-export UNSLOTH_FORCE_VULKAN=1
-curl -fsSL https://unsloth.ai/install.sh | sh
-```
-
 #### Windows:
 ```powershell
 irm https://unsloth.ai/install.ps1 | iex
 ```
-Use the same command to update.
-
-To force the Vulkan llama.cpp backend, set the environment variable before running the installer or updater:
-
-```powershell
-$env:UNSLOTH_FORCE_VULKAN=1
-irm https://unsloth.ai/install.ps1 | iex
-```
-
-Re-running the current installer replaces a previously selected CPU bundle when the backend differs. A separate Vulkan SDK is not required; the GPU driver must provide a working Vulkan runtime.
 
 #### Launch
 ```bash
-unsloth studio -p 8888
+unsloth studio -H 0.0.0.0 -p 8888
 ```
-For LAN or cloud access, add `-H 0.0.0.0` (raw port only; add `--cloudflare` for a public URL). By default, Unsloth is accessible only locally.
 
-To reach Unsloth over HTTPS, use `unsloth studio --secure`. Unsloth stays bound to localhost and is reached only through a free Cloudflare tunnel, which publishes it at a public `https://*.trycloudflare.com` URL (it fails closed if the tunnel can't start, so the raw port is never exposed). This makes Unsloth reachable from the internet, so anyone with the link and API key can use it and run code: keep your API key private (see Remote access below).
+#### Update
+To update, use the same install commands as above. Or run (does not work on Windows):
+```bash
+unsloth studio update
+```
 
 #### Docker
 Use our [Docker image](https://hub.docker.com/r/unsloth/unsloth) ```unsloth/unsloth``` container. Run:
@@ -176,7 +107,7 @@ You can use the same Docker image as Unsloth Studio.
 
 #### AMD, Intel:
 For RTX 50x, B200, 6000 GPUs: `uv pip install unsloth --torch-backend=auto`. Read our guides for: [Blackwell](https://unsloth.ai/docs/blog/fine-tuning-llms-with-blackwell-rtx-50-series-and-unsloth) and [DGX Spark](https://unsloth.ai/docs/blog/fine-tuning-llms-with-nvidia-dgx-spark-and-unsloth). <br>
-To install Unsloth on **AMD** and **Intel** GPUs, follow our [AMD Guide](https://unsloth.ai/docs/basics/amd) and [Intel Guide](https://unsloth.ai/docs/get-started/install/intel).
+To install Unsloth on **AMD** and **Intel** GPUs, follow our [AMD Guide](https://unsloth.ai/docs/get-started/install/amd) and [Intel Guide](https://unsloth.ai/docs/get-started/install/intel).
 
 ## 📒 Free Notebooks
 
@@ -202,157 +133,77 @@ Read our [guide](https://unsloth.ai/docs/get-started/fine-tuning-llms-guide). Ad
 - See detailed documentation for Unsloth [here](https://unsloth.ai/docs)
 
 ## 🦥 Unsloth News
-- **AMD training**: Train, run RL, chat and deploy on AMD GPUs across Windows, WSL and Linux. [Guide](https://unsloth.ai/docs/basics/amd)
-- **GGUF hardware controls**: Choose GPU/layer placement, offload MoE experts and use multi-GPU or Tensor Parallelism. [#6414](https://github.com/unslothai/unsloth/pull/6414)
-- **Local models for any agent**: Use `unsloth start` with Claude Code, Codex, Hermes, OpenCode, OpenClaw, Pi and more through Unsloth's OpenAI- and Anthropic-compatible APIs. [Guide](https://unsloth.ai/docs/basics/api)
-- **MCP control endpoint**: Let compatible clients manage models, training, recipes, checkpoints and exports. [#7191](https://github.com/unslothai/unsloth/pull/7191)
-- **Local inference reliability**: Resume long chats faster, recover stalled downloads and reuse existing GGUF files. [#7204](https://github.com/unslothai/unsloth/pull/7204) • [#6858](https://github.com/unslothai/unsloth/pull/6858) • [#7209](https://github.com/unslothai/unsloth/pull/7209)
-- **New models**: [Qwen-AgentWorld](https://huggingface.co/unsloth/Qwen-AgentWorld-35B-A3B-GGUF), [Ornith](https://huggingface.co/unsloth/models?search=ornith), [Kimi K2.7 Code](https://unsloth.ai/docs/models/kimi-k2.7-code) and [MiniMax M3](https://unsloth.ai/docs/models/minimax-m3)
-- **GLM-5.2**: Run Z.ai's 744B-parameter, 1M-context open model locally with Unsloth Dynamic GGUFs. [Guide](https://unsloth.ai/docs/models/glm-5.2)
-- **DeepSeek-V4**: Run DeepSeek-V4-Flash locally with corrected multi-turn and tool-calling behavior. [Guide](https://unsloth.ai/docs/models/deepseek-v4)
-- **DiffusionGemma**: Run and fine-tune Google's diffusion language model with 1.8x faster inference in Unsloth Studio. [Guide](https://unsloth.ai/docs/models/diffusiongemma)
-- **Qwen3.6**: Run and train Qwen3.6 with MTP for 1.4-2.2x faster inference and NVFP4 quants for supported GPUs. [Guide](https://unsloth.ai/docs/models/qwen3.6)
-- **Gemma 4**: Run and train Gemma 4 text, image and audio models with QAT, MTP, GGUF and MLX support. [Guide](https://unsloth.ai/docs/models/gemma-4)
-- **MCP servers**: Connect local models to files, apps, databases and external tools through Model Context Protocol. [Guide](https://unsloth.ai/docs/basics/mcp)
-- **Connections**: Mix local models with API providers (OpenAI, Anthropic) or servers (vLLM, Ollama) in the same interface. [Guide](https://unsloth.ai/docs/integrations/connections)
+- **Gemma 4**: Run and train Google’s new models directly in Unsloth Studio! [Blog](https://unsloth.ai/docs/models/gemma-4)
 - **Introducing Unsloth Studio**: our new web UI for running and training LLMs. [Blog](https://unsloth.ai/docs/new/studio)
+- **Qwen3.5** - 0.8B, 2B, 4B, 9B, 27B, 35-A3B, 112B-A10B are now supported. [Guide + notebooks](https://unsloth.ai/docs/models/qwen3.5/fine-tune)
 - Train **MoE LLMs 12x faster** with 35% less VRAM - DeepSeek, GLM, Qwen and gpt-oss. [Blog](https://unsloth.ai/docs/new/faster-moe)
 - **Embedding models**: Unsloth now supports ~1.8-3.3x faster embedding fine-tuning. [Blog](https://unsloth.ai/docs/new/embedding-finetuning) • [Notebooks](https://unsloth.ai/docs/get-started/unsloth-notebooks#embedding-models)
 - New **7x longer context RL** vs. all other setups, via our new batching algorithms. [Blog](https://unsloth.ai/docs/new/grpo-long-context)
 - New RoPE & MLP **Triton Kernels** & **Padding Free + Packing**: 3x faster training & 30% less VRAM. [Blog](https://unsloth.ai/docs/new/3x-faster-training-packing)
 - **500K Context**: Training a 20B model with >500K context is now possible on an 80GB GPU. [Blog](https://unsloth.ai/docs/blog/500k-context-length-fine-tuning)
 - **FP8 & Vision RL**: You can now do FP8 & VLM GRPO on consumer GPUs. [FP8 Blog](https://unsloth.ai/docs/get-started/reinforcement-learning-rl-guide/fp8-reinforcement-learning) • [Vision RL](https://unsloth.ai/docs/get-started/reinforcement-learning-rl-guide/vision-reinforcement-learning-vlm-rl)
+- **gpt-oss** by OpenAI: Read our [RL blog](https://unsloth.ai/docs/models/gpt-oss-how-to-run-and-fine-tune/gpt-oss-reinforcement-learning), [Flex Attention](https://unsloth.ai/docs/models/gpt-oss-how-to-run-and-fine-tune/long-context-gpt-oss-training) blog and [Guide](https://unsloth.ai/docs/models/gpt-oss-how-to-run-and-fine-tune).
 
 ## 📥 Advanced Installation
 The below advanced instructions are for Unsloth Studio. For Unsloth Core advanced installation, [view our docs](https://unsloth.ai/docs/get-started/install/pip-install#advanced-pip-installation).
-#### Developer / Nightly / Experimental installs: macOS, Linux, WSL:
-The developer install builds from the `main` branch, which is the latest (nightly) source.
+#### Developer installs: macOS, Linux, WSL:
 ```bash
 git clone https://github.com/unslothai/unsloth
 cd unsloth
 ./install.sh --local
-unsloth studio -p 8888
-```
-To install into an isolated location (its own virtual env, `auth/`, `studio.db`, cache and llama.cpp build), set `UNSLOTH_STUDIO_HOME` and pass it again at launch:
-```bash
-UNSLOTH_STUDIO_HOME="$PWD/.studio" ./install.sh --local
-UNSLOTH_STUDIO_HOME="$PWD/.studio" unsloth studio -p 8888
+unsloth studio -H 0.0.0.0 -p 8888
 ```
 Then to update :
 ```bash
-cd unsloth && git pull
-./install.sh --local
-unsloth studio -p 8888
+unsloth studio update
 ```
 
-#### Developer / Nightly / Experimental installs: Windows PowerShell:
-The developer install builds from the `main` branch, which is the latest (nightly) source.
+#### Developer installs: Windows PowerShell:
 ```powershell
 git clone https://github.com/unslothai/unsloth.git
 cd unsloth
 Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
 .\install.ps1 --local
-unsloth studio -p 8888
-```
-To install into an isolated location (its own virtual env, `auth/`, `studio.db`, cache and llama.cpp build), set `UNSLOTH_STUDIO_HOME` and pass it again at launch:
-```powershell
-$env:UNSLOTH_STUDIO_HOME="$PWD\.studio"; .\install.ps1 --local
-$env:UNSLOTH_STUDIO_HOME="$PWD\.studio"; unsloth studio -p 8888
+unsloth studio -H 0.0.0.0 -p 8888
 ```
 Then to update :
-```powershell
-cd unsloth; git pull
-.\install.ps1 --local
-unsloth studio -p 8888
-```
-
-#### Remote access: `--secure` (HTTPS tunnel) vs raw port
-By default `unsloth studio` binds to `127.0.0.1` (this machine only). To reach it from another device, pick one of:
-
-- `--secure` (recommended): serve **only** through a free Cloudflare HTTPS link. Unsloth stays bound to localhost and the tunnel provides the public URL; it fails closed (does not start) if the tunnel can't come up, so the raw port is never exposed.
 ```bash
-unsloth studio --secure -p 8888
+unsloth studio update
 ```
-- `-H 0.0.0.0`: bind the raw port on all network interfaces, reachable from anywhere on the network (subject to your firewall). It does not create a public internet URL; add `--cloudflare` to also publish an internet-reachable `https://*.trycloudflare.com` link even behind a firewall. Only use this on a network you trust.
+
+#### Nightly: MacOS, Linux, WSL:
+```bash
+git clone https://github.com/unslothai/unsloth
+cd unsloth
+git checkout nightly
+./install.sh --local
+unsloth studio -H 0.0.0.0 -p 8888
+```
+Then to launch every time:
 ```bash
 unsloth studio -H 0.0.0.0 -p 8888
 ```
-The Cloudflare tunnel is **off by default**: `-H 0.0.0.0` exposes the raw port only, not a public internet URL. Pair the wildcard bind with `--cloudflare` (`unsloth studio -H 0.0.0.0 --cloudflare`) to also publish a public `https://*.trycloudflare.com` link, or prefer `--secure` (above), which keeps the raw port private. `--cloudflare` has no effect on a loopback bind.
-
-On a wildcard bind Unsloth works out the address to share by asking `ifconfig.me` for the public IP, then asks `check-host.net` whether that port is reachable so it can tell you if a firewall is in the way. Both contact a third party. Set `UNSLOTH_STUDIO_DISABLE_PUBLIC_CHECK=1` to skip them; the banner then shows the LAN address and no reachability line.
-
-The first time Unsloth is published on a public URL (`--secure` or `--cloudflare`) with the auto-generated admin password still in place, it asks for a new admin password in the terminal (masked input with confirmation) before the public link goes up. Without an attached terminal it warns instead and keeps the bootstrap deadline: Unsloth shuts down after `UNSLOTH_STUDIO_BOOTSTRAP_TIMEOUT` (default 1 hour) unless the password is changed in the web UI.
-
-For headless setups that cannot answer that prompt, set the initial admin password non-interactively with `--password` (only takes effect when no password is set yet; if one already exists it is a hard error, so rotate later with `unsloth studio reset-password`):
 
+#### Nightly: Windows:
+Run in Windows Powershell:
 ```bash
-unsloth studio --secure --password 'your-strong-password'        # visible in `ps`/history
-UNSLOTH_STUDIO_PASSWORD='your-strong-password' unsloth studio --secure   # via env var
-printf '%s\n' 'your-strong-password' | unsloth studio --secure --password -   # via stdin
+git clone https://github.com/unslothai/unsloth.git
+cd unsloth
+git checkout nightly
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
+.\install.ps1 --local
+unsloth studio -H 0.0.0.0 -p 8888
 ```
-
-A literal `--password VALUE` is visible in the process list and shell history, so prefer the `UNSLOTH_STUDIO_PASSWORD` env var or `--password -` (stdin) for automation. This applies to any launch (public or a headless `-H 0.0.0.0` bind), and the password is set in the parent before the server binds, so it never reaches a re-executed child process.
-
-Server-side tools (web search, Python and terminal code execution) run as your user and are on by default. Anyone who can reach the server with the API key can run code on this machine, so keep your API key private and pass `--disable-tools` when exposing Unsloth.
-
-#### Advanced launch options
-Installer options can be passed as environment variables. On macOS, Linux and WSL place the variable after the pipe so the shell passes it to `sh`; on Windows set it with `$env:` before piping to `iex`.
-
-Skip PyTorch (GGUF-only mode):
+Then to launch every time:
 ```bash
-curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_NO_TORCH=1 sh
+unsloth studio -H 0.0.0.0 -p 8888
 ```
-```powershell
-$env:UNSLOTH_NO_TORCH=1; irm https://unsloth.ai/install.ps1 | iex
-```
-
-Skip the post-install prompt that starts Unsloth (useful for automated installs):
-```bash
-curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_SKIP_AUTOSTART=1 sh
-```
-```powershell
-$env:UNSLOTH_SKIP_AUTOSTART=1; irm https://unsloth.ai/install.ps1 | iex
-```
-
-Pin the Python version:
-```bash
-curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_PYTHON=3.12 sh
-```
-```powershell
-$env:UNSLOTH_PYTHON='3.12'; irm https://unsloth.ai/install.ps1 | iex
-```
-
-Install to a custom location with `UNSLOTH_STUDIO_HOME`:
-```bash
-curl -fsSL https://unsloth.ai/install.sh | UNSLOTH_STUDIO_HOME=/abs/path sh
-```
-```powershell
-$env:UNSLOTH_STUDIO_HOME='C:\path'; irm https://unsloth.ai/install.ps1 | iex
-```
-
-On macOS, the installer defaults to the system certificate store (`UV_SYSTEM_CERTS=1`) so uv trusts the CAs in your Keychain, needed behind TLS-inspecting proxies (Cisco Umbrella, Zscaler, etc.). Opt out with:
-```bash
-curl -fsSL https://unsloth.ai/install.sh | UV_SYSTEM_CERTS=0 sh
-```
-
-Point the frontend build at a corporate npm mirror/proxy with `UNSLOTH_NPM_REGISTRY` (for the developer install behind a firewall that blocks `registry.npmjs.org`):
-```bash
-UNSLOTH_NPM_REGISTRY=https://artifactory.example.com/api/npm/npm/ ./install.sh --local
-```
-```powershell
-$env:UNSLOTH_NPM_REGISTRY='https://artifactory.example.com/api/npm/npm/'; .\install.ps1 --local
-```
-It is threaded as `--registry` into the Unsloth frontend `npm`/`bun` installs; the supply-chain locks (7-day `min-release-age`, exact version pins) stay in force.
-
-Cap Unsloth's native CPU thread pools on high-core hosts: `UNSLOTH_CPU_THREADS=8 unsloth studio -p 8888`.
 
 #### Uninstall
-The recommended way to fully remove Unsloth Studio is the matching uninstall script for your OS. It stops any running servers, removes the install dir, the launcher data dir, the desktop shortcut, and any platform-specific entries (macOS `.app` bundle + Launch Services on Mac; Start Menu, `HKCU\Software\Unsloth` registry key and user `PATH` entries on Windows):
+You can uninstall Unsloth Studio by deleting its install folder usually located under `$HOME/.unsloth/studio` on Mac/Linux/WSL and `%USERPROFILE%\.unsloth\studio` on Windows. Using the `rm -rf` commands will **delete everything**, including your history, cache:
 
-* ​ **MacOS, WSL, Linux:** `curl -fsSL https://raw.githubusercontent.com/unslothai/unsloth/main/scripts/uninstall.sh | sh`
-* ​ **Windows (PowerShell):** `irm https://raw.githubusercontent.com/unslothai/unsloth/main/scripts/uninstall.ps1 | iex`
-
-If you only want to drop the install dir and keep the launcher/shortcut for a later reinstall, you can instead run `rm -rf ~/.unsloth/studio` (Mac/Linux/WSL) or `Remove-Item -Recurse -Force "$HOME\.unsloth\studio"` (Windows). The model cache at `~/.cache/huggingface` is not touched by any of these.
+* ​ **MacOS, WSL, Linux:** `rm -rf ~/.unsloth/studio`
+* ​ **Windows (PowerShell):** `Remove-Item -Recurse -Force "$HOME\.unsloth\studio"`
 
 For more info, [see our docs](https://unsloth.ai/docs/new/studio/install#uninstall).
 

_changelog_build.py

@@ -1,36 +0,0 @@
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-"""Snapshot CHANGELOG.md into the studio package at build time.
-
-CHANGELOG.md at the repo root stays the one file to edit. Copying it here,
-rather than in build.sh, means every packaging path ships it, so release notes
-still render when the popup cannot reach GitHub."""
-
-from __future__ import annotations
-
-import shutil
-from pathlib import Path
-
-from setuptools.command.build_py import build_py as _build_py
-
-ROOT = Path(__file__).resolve().parent
-SOURCE = ROOT / "CHANGELOG.md"
-SNAPSHOT = ROOT / "studio" / "CHANGELOG.md"
-
-
-class build_py(_build_py):
-    def run(self) -> None:
-        # Beside the sources only if writable (PEP 517 may build an immutable
-        # checkout); into the staging directory always.
-        if SOURCE.is_file():
-            try:
-                shutil.copyfile(SOURCE, SNAPSHOT)
-            except OSError:
-                pass
-        super().run()
-        if not SOURCE.is_file():
-            return
-        staged = Path(self.build_lib) / "studio" / "CHANGELOG.md"
-        staged.parent.mkdir(parents = True, exist_ok = True)
-        shutil.copyfile(SOURCE, staged)

build.sh

@@ -1,13 +1,7 @@
 #!/usr/bin/env bash
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
 
 set -euo pipefail
 
-# PyPI/Unsloth release publishing must use `./build.sh publish` (or an
-# equivalent stamp -> build -> verify-dist -> upload flow) so packaged Unsloth
-# artifacts include the display-only Unsloth release version.
-
 # 1. Build frontend (Vite outputs to dist/)
 cd studio/frontend
 
@@ -35,19 +29,10 @@ _restore_gitignores() {
 }
 trap _restore_gitignores EXIT
 
-# Corporate-mirror / proxy escape hatch (#6491). When UNSLOTH_NPM_REGISTRY is set we
-# thread it as `--registry <url>` into the installs (overrides frontend/.npmrc's pinned
-# registry for both bun and npm; min-release-age / save-exact stay in force). Empty
-# array (the default) expands to nothing under `set -u`.
-_NPM_REGISTRY_ARGS=()
-if [ -n "${UNSLOTH_NPM_REGISTRY:-}" ]; then
-    _NPM_REGISTRY_ARGS=(--registry "$UNSLOTH_NPM_REGISTRY")
-fi
-
 # Use bun for install if available (faster), fall back to npm.
 _install_ok=false
 if command -v bun &>/dev/null; then
-    if bun install "${_NPM_REGISTRY_ARGS[@]+"${_NPM_REGISTRY_ARGS[@]}"}"; then
+    if bun install; then
         _install_ok=true
     else
         echo "⚠ bun install failed, falling back to npm"
@@ -55,10 +40,8 @@ if command -v bun &>/dev/null; then
     fi
 fi
 if [ "$_install_ok" != "true" ]; then
-    if ! npm install "${_NPM_REGISTRY_ARGS[@]+"${_NPM_REGISTRY_ARGS[@]}"}"; then
+    if ! npm install; then
         echo "❌ ERROR: package install failed" >&2
-        echo "   If you are behind a corporate firewall/proxy, set UNSLOTH_NPM_REGISTRY to your mirror and retry, e.g.:" >&2
-        echo "   UNSLOTH_NPM_REGISTRY=https://your-mirror.example/api/npm/ ./build.sh" >&2
         exit 1
     fi
 fi
@@ -87,37 +70,10 @@ cd ../..
 # 2. Clean old artifacts
 rm -rf build dist *.egg-info
 
-# 3. Stamp display-only Unsloth release metadata for packaged builds.
-_STUDIO_BUILD_INFO="studio/backend/utils/_studio_release_build.py"
-_STUDIO_BUILD_INFO_BACKUP="$(mktemp)"
-cp "$_STUDIO_BUILD_INFO" "$_STUDIO_BUILD_INFO_BACKUP"
-_restore_studio_build_info() {
-    cp "$_STUDIO_BUILD_INFO_BACKUP" "$_STUDIO_BUILD_INFO" 2>/dev/null || true
-    rm -f "$_STUDIO_BUILD_INFO_BACKUP"
-}
-trap _restore_studio_build_info EXIT
-
-if [ "${1:-}" = "publish" ]; then
-    STUDIO_STAMPED_VERSION="$(python scripts/stamp_studio_release.py --require-release)"
-else
-    STUDIO_STAMPED_VERSION="$(python scripts/stamp_studio_release.py)"
-fi
-
-# 4. Build wheel/sdist. _changelog_build.py snapshots CHANGELOG.md into the studio
-# package so release notes render offline.
+# 3. Build wheel
 python -m build
 
-# Drop the snapshot so a source checkout never serves a stale copy.
-rm -f studio/CHANGELOG.md
-
-if [ "${1:-}" = "publish" ]; then
-    python scripts/stamp_studio_release.py --verify-dist dist --expected "$STUDIO_STAMPED_VERSION"
-fi
-
-_restore_studio_build_info
-trap - EXIT
-
-# 5. Optionally publish
+# 4. Optionally publish
 if [ "${1:-}" = "publish" ]; then
     python -m twine upload dist/*
 fi

pyproject.toml

@@ -25,17 +25,10 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
 ]
 dependencies = [
-    "typer>=0.12.0",
-    "rich",
+    "typer",
     "pydantic",
     "pyyaml",
     "nest-asyncio",
-    # Every CLI command imports studio.backend.*, which reaches structlog at
-    # module level. The rest of the server stack lives in the studio extra.
-    "structlog>=24.1.0",
-    # unsloth_cli/__init__.py reaches click via commands/start.py, so every
-    # command needs it. typer supplied it until 0.27 dropped the dependency.
-    "click>=8.0",
 ]
 
 [project.scripts]
@@ -47,18 +40,11 @@ version = {attr = "unsloth.models._utils.__version__"}
 [tool.setuptools]
 include-package-data = true
 
-[tool.setuptools.cmdclass]
-# Snapshots CHANGELOG.md into studio/ so every build path ships it.
-build_py = "_changelog_build.build_py"
-
 [tool.setuptools.package-data]
-unsloth_cli = ["codex_fallback_prompt.md", "pi_subagent.ts"]
 studio = [
-    "CHANGELOG.md",
     "*.sh",
     "*.ps1",
     "*.bat",
-    "node_prebuilt_pins.json",
     "frontend/dist/**/*",
     "frontend/*.json",
     "frontend/*.ts",
@@ -67,9 +53,6 @@ studio = [
     "frontend/*.yaml",
     "frontend/.git*",
     "backend/requirements/**/*",
-    "backend/plugins/**/*",
-    "backend/assets/**/*.jinja",
-    "backend/assets/**/*.html",
     "backend/core/data_recipe/oxc-validator/*.json",
     "backend/core/data_recipe/oxc-validator/*.mjs",
 ]
@@ -79,40 +62,12 @@ include = ["unsloth*", "unsloth_cli*", "studio", "studio.backend*"]
 exclude = ["images*", "tests*", "*.node_modules", "*.node_modules.*"]
 
 [project.optional-dependencies]
-# Studio's server stack, mirroring studio/backend/requirements/studio.txt.
-# test_studio_extra_matches_requirements.py catches drift.
-studio = [
-    "typer",
-    "fastapi",
-    "uvicorn",
-    "pydantic",
-    "packaging",
-    "matplotlib==3.10.9",
-    "pandas",
-    "nest_asyncio",
-    "datasets==4.3.0",
-    "pyjwt",
-    "huggingface-hub==0.36.2",
-    "structlog>=24.1.0",
-    "diceware",
-    "ddgs",
-    "cryptography>=42.0.0",
-    "boto3>=1.34.0",
-    "httpx>=0.27.0",
-    "fastmcp>=3.0.2",
-    "sqlite-vec==0.1.9",
-    "pymupdf==1.27.2.3",
-    "pymupdf4llm==0.3.4",
-    "python-docx==1.2.0",
-]
-
 triton = [
     "triton>=3.0.0 ; ('linux' in sys_platform)",
     "triton-windows ; (sys_platform == 'win32') and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
 ]
 
 huggingfacenotorch = [
-    "unsloth_zoo>=2026.7.6",
     "wheel>=0.42.0",
     "packaging",
     "numpy",
@@ -131,25 +86,9 @@ huggingfacenotorch = [
     "trl>=0.18.2,!=0.19.0,<=0.24.0",
     "sentence-transformers",
 ]
-# torchcodec backend for Gemma audio / datasets>=4 (#7225).
-# Pick the audio-torch* pin matching your torch minor (see TORCH_TORCHCODEC).
-# torchcodec publishes no sdist and only manylinux_2_28_x86_64, macosx_*_arm64
-# and win_amd64 wheels, so Linux aarch64, Windows ARM64 and Intel Mac have
-# nothing to resolve and pip fails the whole install rather than skipping audio.
-# Gate on the platforms that have a wheel, matching
-# PLATFORM_LACKS_TORCHCODEC_WHEEL in studio/install_python_stack.py.
-audio-torch210 = [
-    "torchcodec>=0.10.0,<0.11.0 ; python_version >= '3.10' and (((sys_platform == 'linux' or sys_platform == 'win32') and (platform_machine == 'x86_64' or platform_machine == 'AMD64')) or (sys_platform == 'darwin' and platform_machine == 'arm64'))",
-]
-audio-torch290 = [
-    "torchcodec>=0.8.0,<0.10.0 ; python_version >= '3.10' and (((sys_platform == 'linux' or sys_platform == 'win32') and (platform_machine == 'x86_64' or platform_machine == 'AMD64')) or (sys_platform == 'darwin' and platform_machine == 'arm64'))",
-]
-audio-torch280 = [
-    "torchcodec>=0.6.0,<0.8.0 ; python_version >= '3.9' and (((sys_platform == 'linux' or sys_platform == 'win32') and (platform_machine == 'x86_64' or platform_machine == 'AMD64')) or (sys_platform == 'darwin' and platform_machine == 'arm64'))",
-]
 huggingface = [
     "unsloth[huggingfacenotorch]",
-    "unsloth_zoo>=2026.7.6",
+    "unsloth_zoo>=2026.4.8",
     "torchvision",
     "unsloth[triton]",
 ]
@@ -310,6 +249,10 @@ cu118onlytorch270 = [
     "xformers @ https://download.pytorch.org/whl/cu118/xformers-0.0.30-cp310-cp310-manylinux_2_28_x86_64.whl ; python_version=='3.10' and ('linux' in sys_platform)",
     "xformers @ https://download.pytorch.org/whl/cu118/xformers-0.0.30-cp311-cp311-manylinux_2_28_x86_64.whl ; python_version=='3.11' and ('linux' in sys_platform)",
     "xformers @ https://download.pytorch.org/whl/cu118/xformers-0.0.30-cp312-cp312-manylinux_2_28_x86_64.whl ; python_version=='3.12' and ('linux' in sys_platform)",
+    "xformers @ https://download.pytorch.org/whl/cu118/xformers-0.0.30-cp39-cp39-win_amd64.whl ; python_version=='3.9' and (sys_platform == 'win32')",
+    "xformers @ https://download.pytorch.org/whl/cu118/xformers-0.0.30-cp310-cp310-win_amd64.whl ; python_version=='3.10' and (sys_platform == 'win32')",
+    "xformers @ https://download.pytorch.org/whl/cu118/xformers-0.0.30-cp311-cp311-win_amd64.whl ; python_version=='3.11' and (sys_platform == 'win32')",
+    "xformers @ https://download.pytorch.org/whl/cu118/xformers-0.0.30-cp312-cp312-win_amd64.whl ; python_version=='3.12' and (sys_platform == 'win32')",
 ]
 cu126onlytorch270 = [
     "xformers @ https://download.pytorch.org/whl/cu126/xformers-0.0.30-cp39-cp39-manylinux_2_28_x86_64.whl ; python_version=='3.9' and ('linux' in sys_platform)",
@@ -333,6 +276,7 @@ cu128onlytorch270 = [
 ]
 cu118onlytorch271 = [
     "xformers @ https://download.pytorch.org/whl/cu118/xformers-0.0.31.post1-cp39-abi3-manylinux_2_28_x86_64.whl ; ('linux' in sys_platform)",
+    "xformers @ https://download.pytorch.org/whl/cu118/xformers-0.0.31.post1-cp39-abi3-win_amd64.whl ; (sys_platform == 'win32')",
 ]
 cu126onlytorch271 = [
     "xformers @ https://download.pytorch.org/whl/cu126/xformers-0.0.31.post1-cp39-abi3-manylinux_2_28_x86_64.whl ; ('linux' in sys_platform)",
@@ -586,19 +530,16 @@ cu126-torch2100 = [
     "unsloth[huggingface]",
     "bitsandbytes>=0.45.5,!=0.46.0,!=0.48.0",
     "unsloth[cu126onlytorch2100]",
-    "unsloth[audio-torch210]",
 ]
 cu128-torch2100 = [
     "unsloth[huggingface]",
     "bitsandbytes>=0.45.5,!=0.46.0,!=0.48.0",
     "unsloth[cu128onlytorch2100]",
-    "unsloth[audio-torch210]",
 ]
 cu130-torch2100 = [
     "unsloth[huggingface]",
     "bitsandbytes>=0.45.5,!=0.46.0,!=0.48.0",
     "unsloth[cu130onlytorch2100]",
-    "unsloth[audio-torch210]",
 ]
 kaggle = [
     "unsloth[huggingface]",
@@ -637,7 +578,7 @@ colab-ampere-torch220 = [
     "flash-attn>=2.6.3 ; ('linux' in sys_platform)",
 ]
 colab-new = [
-    "unsloth_zoo>=2026.7.6",
+    "unsloth_zoo>=2026.4.8",
     "packaging",
     "tyro",
     "transformers>=4.51.3,!=4.52.0,!=4.52.1,!=4.52.2,!=4.52.3,!=4.53.0,!=4.54.0,!=4.55.0,!=4.55.1,!=4.57.0,!=4.57.4,!=4.57.5,!=5.0.0,!=5.1.0,<=5.5.0",
@@ -888,19 +829,16 @@ cu126-ampere-torch2100 = [
     "unsloth[huggingface]",
     "bitsandbytes>=0.45.5,!=0.46.0,!=0.48.0",
     "unsloth[cu126onlytorch2100]",
-    "unsloth[audio-torch210]",
 ]
 cu128-ampere-torch2100 = [
     "unsloth[huggingface]",
     "bitsandbytes>=0.45.5,!=0.46.0,!=0.48.0",
     "unsloth[cu128onlytorch2100]",
-    "unsloth[audio-torch210]",
 ]
 cu130-ampere-torch2100 = [
     "unsloth[huggingface]",
     "bitsandbytes>=0.45.5,!=0.46.0,!=0.48.0",
     "unsloth[cu130onlytorch2100]",
-    "unsloth[audio-torch210]",
 ]
 flashattentiontorch260abiFALSEcu12x = [
     "flash-attn @ https://github.com/Dao-AILab/flash-attention/releases/download/v2.7.4.post1/flash_attn-2.7.4.post1+cu12torch2.6cxx11abiFALSE-cp39-cp39-linux_x86_64.whl ; ('linux' in sys_platform) and python_version == '3.9'",
@@ -935,12 +873,14 @@ flashattentiontorch240abiFALSEcu12x = [
     "flash-attn @ https://github.com/Dao-AILab/flash-attention/releases/download/v2.7.4.post1/flash_attn-2.7.4.post1+cu12torch2.4cxx11abiFALSE-cp310-cp310-linux_x86_64.whl ; ('linux' in sys_platform) and python_version == '3.10'",
     "flash-attn @ https://github.com/Dao-AILab/flash-attention/releases/download/v2.7.4.post1/flash_attn-2.7.4.post1+cu12torch2.4cxx11abiFALSE-cp311-cp311-linux_x86_64.whl ; ('linux' in sys_platform) and python_version == '3.11'",
     "flash-attn @ https://github.com/Dao-AILab/flash-attention/releases/download/v2.7.4.post1/flash_attn-2.7.4.post1+cu12torch2.4cxx11abiFALSE-cp312-cp312-linux_x86_64.whl ; ('linux' in sys_platform) and python_version == '3.12'",
+    "flash-attn @ https://github.com/Dao-AILab/flash-attention/releases/download/v2.7.4.post1/flash_attn-2.7.4.post1+cu12torch2.4cxx11abiFALSE-cp313-cp313-linux_x86_64.whl ; ('linux' in sys_platform) and python_version == '3.13'",
 ]
 flashattentiontorch240abiTRUEcu12x = [
     "flash-attn @ https://github.com/Dao-AILab/flash-attention/releases/download/v2.7.4.post1/flash_attn-2.7.4.post1+cu12torch2.4cxx11abiTRUE-cp39-cp39-linux_x86_64.whl ; ('linux' in sys_platform) and python_version == '3.9'",
     "flash-attn @ https://github.com/Dao-AILab/flash-attention/releases/download/v2.7.4.post1/flash_attn-2.7.4.post1+cu12torch2.4cxx11abiTRUE-cp310-cp310-linux_x86_64.whl ; ('linux' in sys_platform) and python_version == '3.10'",
     "flash-attn @ https://github.com/Dao-AILab/flash-attention/releases/download/v2.7.4.post1/flash_attn-2.7.4.post1+cu12torch2.4cxx11abiTRUE-cp311-cp311-linux_x86_64.whl ; ('linux' in sys_platform) and python_version == '3.11'",
     "flash-attn @ https://github.com/Dao-AILab/flash-attention/releases/download/v2.7.4.post1/flash_attn-2.7.4.post1+cu12torch2.4cxx11abiTRUE-cp312-cp312-linux_x86_64.whl ; ('linux' in sys_platform) and python_version == '3.12'",
+    "flash-attn @ https://github.com/Dao-AILab/flash-attention/releases/download/v2.7.4.post1/flash_attn-2.7.4.post1+cu12torch2.4cxx11abiTRUE-cp313-cp313-linux_x86_64.whl ; ('linux' in sys_platform) and python_version == '3.13'",
 ]
 intelgputorch260 = [
     "unsloth_zoo[intelgpu]",
@@ -1076,44 +1016,7 @@ intelgputorch290 = [
 intel-gpu-torch290 = [
     "unsloth[intelgputorch290]"
 ]
-intelgputorch271 = [
-    "unsloth_zoo[intelgpu]",
-    "unsloth[huggingfacenotorch]",
-
-    "pytorch_triton_xpu @ https://download.pytorch.org/whl/pytorch_triton_xpu-3.3.1-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl#sha256=663ce21364096b268c6687f26f22862cb1001cae0c4ec9f98a0998415f99e2b0 ; platform_system == 'Linux' and python_version == '3.10' and platform_machine == 'x86_64'",
-    "pytorch_triton_xpu @ https://download.pytorch.org/whl/pytorch_triton_xpu-3.3.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl#sha256=dd92cc17000bad19f213b6a877d7f10cd71341b703cd188513ce9fff8d42e3dd ; platform_system == 'Linux' and python_version == '3.11' and platform_machine == 'x86_64'",
-    "pytorch_triton_xpu @ https://download.pytorch.org/whl/pytorch_triton_xpu-3.3.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl#sha256=aa5c3ec21a89e967d1dfe61e3d5b1c1ae9620c871ed804771d3378d6a44066f2 ; platform_system == 'Linux' and python_version == '3.12' and platform_machine == 'x86_64'",
-    "pytorch_triton_xpu @ https://download.pytorch.org/whl/pytorch_triton_xpu-3.3.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl#sha256=d1c6f522e11112a311b1a61ba7b40b43ad8305675fa29153017ccb1ad0b6816d ; platform_system == 'Linux' and python_version == '3.13' and platform_machine == 'x86_64'",
-    "pytorch_triton_xpu @ https://download.pytorch.org/whl/pytorch_triton_xpu-3.3.1-cp310-cp310-win_amd64.whl#sha256=a5c16dcf449a9cb62bc3788f7ec45782bb3ead6edc2637a12b60ef0f8f45dc55 ; sys_platform == 'win32' and python_version == '3.10' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "pytorch_triton_xpu @ https://download.pytorch.org/whl/pytorch_triton_xpu-3.3.1-cp311-cp311-win_amd64.whl#sha256=bc2d76ffa4ceed5b38ae34b52dbff643442e1a44d52ca72d7cb520ca1950e9ae ; sys_platform == 'win32' and python_version == '3.11' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "pytorch_triton_xpu @ https://download.pytorch.org/whl/pytorch_triton_xpu-3.3.1-cp312-cp312-win_amd64.whl#sha256=b09ca59ce52d6d27b1510df783cde222b703a71857a6fa953f1f155f9f50811a ; sys_platform == 'win32' and python_version == '3.12' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "pytorch_triton_xpu @ https://download.pytorch.org/whl/pytorch_triton_xpu-3.3.1-cp313-cp313-win_amd64.whl#sha256=1260c4a4bad426b6cd3c8f3e1a21835381c6f217bf434bcb55fedec08a206dea ; sys_platform == 'win32' and python_version == '3.13' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.7.1%2Bxpu-cp310-cp310-linux_x86_64.whl#sha256=231c3fbd88a75d94de5ccbbb7f4f9a96cb3c58b3d891c2a1b469d38df95f9be6 ; platform_system == 'Linux' and python_version == '3.10' and platform_machine == 'x86_64'",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.7.1%2Bxpu-cp311-cp311-linux_x86_64.whl#sha256=78edcc27709dd819fc820f5eb9421bd10d3f3dcb14adb25ee60766c76f0e67f3 ; platform_system == 'Linux' and python_version == '3.11' and platform_machine == 'x86_64'",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.7.1%2Bxpu-cp312-cp312-linux_x86_64.whl#sha256=b443df40bc9cb7d648a9f8f9ed1d5c3a1203e561ebd0a61dd55fb8a58833d5ec ; platform_system == 'Linux' and python_version == '3.12' and platform_machine == 'x86_64'",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.7.1%2Bxpu-cp313-cp313-linux_x86_64.whl#sha256=412b58ffcceebea399c9a1bcdb22896aa10385c2650a8c4f8a677fb11c49b448 ; platform_system == 'Linux' and python_version == '3.13' and platform_machine == 'x86_64'",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.7.1%2Bxpu-cp310-cp310-win_amd64.whl#sha256=2591228dc2cb73c78daf24277c4449ba9474f94cd31938147249269fe89d05d6 ; sys_platform == 'win32' and python_version == '3.10' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.7.1%2Bxpu-cp311-cp311-win_amd64.whl#sha256=1aacb86e9a9684ffc8bde3db14b251d00df7019a9a434ec99a59076a2696325d ; sys_platform == 'win32' and python_version == '3.11' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.7.1%2Bxpu-cp312-cp312-win_amd64.whl#sha256=9b65dc8562521b60d77aa653132bc03a19da0291318fcf919faa3f03080d8f7e ; sys_platform == 'win32' and python_version == '3.12' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.7.1%2Bxpu-cp313-cp313-win_amd64.whl#sha256=cd3669fee311bc3ee5501d696bf989226a6f2bf957d120a04881a07af05526d6 ; sys_platform == 'win32' and python_version == '3.13' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-
-    "bitsandbytes @ https://github.com/bitsandbytes-foundation/bitsandbytes/releases/download/continuous-release_main/bitsandbytes-1.33.7.preview-py3-none-manylinux_2_24_x86_64.whl ; ('linux' in sys_platform) and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "bitsandbytes @ https://github.com/bitsandbytes-foundation/bitsandbytes/releases/download/continuous-release_main/bitsandbytes-1.33.7.preview-py3-none-win_amd64.whl ; (sys_platform == 'win32') and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.22.1%2Bxpu-cp310-cp310-manylinux_2_28_x86_64.whl#sha256=f8cdf6889c02b3166679eef661b68757ea7e99c314432c3d41dac3d2ed4a59d4 ; platform_system == 'Linux' and python_version == '3.10' and platform_machine == 'x86_64'",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.22.1%2Bxpu-cp311-cp311-manylinux_2_28_x86_64.whl#sha256=f7d15b65d52809745992e0001c25034f33ac01f2dff5248614e07b5d009a59b7 ; platform_system == 'Linux' and python_version == '3.11' and platform_machine == 'x86_64'",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.22.1%2Bxpu-cp312-cp312-manylinux_2_28_x86_64.whl#sha256=1ff1f98d70846352c7f56833bedab1a055ead27b11c120b8c719063ee0383554 ; platform_system == 'Linux' and python_version == '3.12' and platform_machine == 'x86_64'",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.22.1%2Bxpu-cp313-cp313-manylinux_2_28_x86_64.whl#sha256=f46945344ea911a70309231eaaf3b80c96f6646ce5515dc89aa94f94144e310e ; platform_system == 'Linux' and python_version == '3.13' and platform_machine == 'x86_64'",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.22.1%2Bxpu-cp310-cp310-win_amd64.whl#sha256=ecae9a02de769e2070d37388116beb407c3f0d60b8e65c1da1423f4eafee361a ; sys_platform == 'win32' and python_version == '3.10' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.22.1%2Bxpu-cp311-cp311-win_amd64.whl#sha256=2914e62782431bebd6ad9a3b98a2b7311e448e84a7534bb7f35874b9279a17de ; sys_platform == 'win32' and python_version == '3.11' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.22.1%2Bxpu-cp312-cp312-win_amd64.whl#sha256=5b462c156f4e2097e1e53649d3f298ce352fa4c5d1e6addd360375b10ebd6c67 ; sys_platform == 'win32' and python_version == '3.12' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.22.1%2Bxpu-cp313-cp313-win_amd64.whl#sha256=fa87b3677cd1af67ce423004283c1bde80e3571f391182a3e89b485e18e3c70f ; sys_platform == 'win32' and python_version == '3.13' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-]
-intel-gpu-torch271 = [
-    "unsloth[intelgputorch271]"
-]
-intelgputorch291 = [
+intelgputorch210 = [
     "unsloth_zoo[intelgpu]",
     "unsloth[huggingfacenotorch]",
 
@@ -1126,43 +1029,6 @@ intelgputorch291 = [
     "pytorch_triton_xpu @ https://download.pytorch.org/whl/pytorch_triton_xpu-3.5.0-cp312-cp312-win_amd64.whl#sha256=97337a47425f1963a723475bd61037460e84ba01db4f87a1d662c3718ff6c47e ; sys_platform == 'win32' and python_version == '3.12' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
     "pytorch_triton_xpu @ https://download.pytorch.org/whl/pytorch_triton_xpu-3.5.0-cp313-cp313-win_amd64.whl#sha256=2caf8138695f6abb023ecd02031a2611ba1bf8fff2f19802567cb2fadefe9e87 ; sys_platform == 'win32' and python_version == '3.13' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
 
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.9.1%2Bxpu-cp310-cp310-linux_x86_64.whl#sha256=fb7895c744132d6a8e56ce8434ae1d8355c9bda4e9f58832744ff742d6268eaf ; platform_system == 'Linux' and python_version == '3.10' and platform_machine == 'x86_64'",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.9.1%2Bxpu-cp311-cp311-linux_x86_64.whl#sha256=da2604a9114a28de71ce654819424d20a246adf644d191ae160837df9731b79e ; platform_system == 'Linux' and python_version == '3.11' and platform_machine == 'x86_64'",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.9.1%2Bxpu-cp312-cp312-linux_x86_64.whl#sha256=d5968d78d81c1d01efc1b3bf83d7da3d83161dcc3a9fcf91f500591db1c6c75d ; platform_system == 'Linux' and python_version == '3.12' and platform_machine == 'x86_64'",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.9.1%2Bxpu-cp313-cp313-linux_x86_64.whl#sha256=b56d6b0d65863f370527e971dbfa046a5dd2a1f61cc95071db26c764f36e4dce ; platform_system == 'Linux' and python_version == '3.13' and platform_machine == 'x86_64'",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.9.1%2Bxpu-cp310-cp310-win_amd64.whl#sha256=2f318fb6a4bf1101cc17f35a5371f7c1768b41fceed03628397834e85b3edfdd ; sys_platform == 'win32' and python_version == '3.10' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.9.1%2Bxpu-cp311-cp311-win_amd64.whl#sha256=c9cedc3fb099366b2e6c563df6578e323564b1b5d40ac27be73c674755343a1d ; sys_platform == 'win32' and python_version == '3.11' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.9.1%2Bxpu-cp312-cp312-win_amd64.whl#sha256=bee9623254d0f95a1ca115dbd17e9a9d966fdb8ae123e2ada4a9eb2fb8d38db8 ; sys_platform == 'win32' and python_version == '3.12' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.9.1%2Bxpu-cp313-cp313-win_amd64.whl#sha256=cd5c857da52a63c121561b30b0979e69ade70b575fd74e389787bc7c1ee2ac11 ; sys_platform == 'win32' and python_version == '3.13' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-
-    "bitsandbytes @ https://github.com/bitsandbytes-foundation/bitsandbytes/releases/download/continuous-release_main/bitsandbytes-1.33.7.preview-py3-none-manylinux_2_24_x86_64.whl ; ('linux' in sys_platform) and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "bitsandbytes @ https://github.com/bitsandbytes-foundation/bitsandbytes/releases/download/continuous-release_main/bitsandbytes-1.33.7.preview-py3-none-win_amd64.whl ; (sys_platform == 'win32') and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.24.1%2Bxpu-cp310-cp310-manylinux_2_28_x86_64.whl#sha256=cc5272da2cb4554edf059eedd6d1f5ef2859033b0fb79d5dcb8e99a0697f3325 ; platform_system == 'Linux' and python_version == '3.10' and platform_machine == 'x86_64'",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.24.1%2Bxpu-cp311-cp311-manylinux_2_28_x86_64.whl#sha256=3c80d6a068c32fc4ebddb27953e03a0141bd0f10ca8730417cbc0e0748158285 ; platform_system == 'Linux' and python_version == '3.11' and platform_machine == 'x86_64'",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.24.1%2Bxpu-cp312-cp312-manylinux_2_28_x86_64.whl#sha256=8cf640a867cf270b3fda7a10002c29d3fc2ad6dfbd76404a8cdd820489adb04c ; platform_system == 'Linux' and python_version == '3.12' and platform_machine == 'x86_64'",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.24.1%2Bxpu-cp313-cp313-manylinux_2_28_x86_64.whl#sha256=d9c59ee5ae3d0560f02401c8dfd8054d50813a8dbb5d33a8777de7d02f6fcb7b ; platform_system == 'Linux' and python_version == '3.13' and platform_machine == 'x86_64'",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.24.1%2Bxpu-cp310-cp310-win_amd64.whl#sha256=843ea7fcd8f5a22ebbc20d2d61d9eec7593821a0372eb8cabb73953d12ef6acf ; sys_platform == 'win32' and python_version == '3.10' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.24.1%2Bxpu-cp311-cp311-win_amd64.whl#sha256=e5ff8a31d3c700f8dbac59697c8e32298a43ec059609ebc6ea7bab3eff6384e1 ; sys_platform == 'win32' and python_version == '3.11' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.24.1%2Bxpu-cp312-cp312-win_amd64.whl#sha256=8bae6d4c042f8d20818da4a5aa9109c6fbd6ec11bc422be152ce8adf9a7095bf ; sys_platform == 'win32' and python_version == '3.12' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.24.1%2Bxpu-cp313-cp313-win_amd64.whl#sha256=47059e290fc2a41ba78666ffcde102c436abf7ff8a34d200268b48c4fa0f9c45 ; sys_platform == 'win32' and python_version == '3.13' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-]
-intel-gpu-torch291 = [
-    "unsloth[intelgputorch291]"
-]
-intelgputorch210 = [
-    "unsloth_zoo[intelgpu]",
-    "unsloth[huggingfacenotorch]",
-
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.6.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl ; platform_system == 'Linux' and python_version == '3.10' and platform_machine == 'x86_64'",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.6.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl ; platform_system == 'Linux' and python_version == '3.11' and platform_machine == 'x86_64'",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.6.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl ; platform_system == 'Linux' and python_version == '3.12' and platform_machine == 'x86_64'",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.6.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl ; platform_system == 'Linux' and python_version == '3.13' and platform_machine == 'x86_64'",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.6.0-cp310-cp310-win_amd64.whl ; sys_platform == 'win32' and python_version == '3.10' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.6.0-cp311-cp311-win_amd64.whl ; sys_platform == 'win32' and python_version == '3.11' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.6.0-cp312-cp312-win_amd64.whl ; sys_platform == 'win32' and python_version == '3.12' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.6.0-cp313-cp313-win_amd64.whl ; sys_platform == 'win32' and python_version == '3.13' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-
     "torch @ https://download.pytorch.org/whl/xpu/torch-2.10.0%2Bxpu-cp310-cp310-linux_x86_64.whl#sha256=abb1d1ec1ac672bac0ff35420c965f2df0c636ef9d94e2a830e34578489d0a57 ; platform_system == 'Linux' and python_version == '3.10' and platform_machine == 'x86_64'",
     "torch @ https://download.pytorch.org/whl/xpu/torch-2.10.0%2Bxpu-cp311-cp311-linux_x86_64.whl#sha256=71ad2f82da0f41eaec159f39fc85854e27c2391efa91b373e550648a6f4aaad3 ; platform_system == 'Linux' and python_version == '3.11' and platform_machine == 'x86_64'",
     "torch @ https://download.pytorch.org/whl/xpu/torch-2.10.0%2Bxpu-cp312-cp312-linux_x86_64.whl#sha256=b473571d478912f92881cc13f15fa18f8463fb0fb8a068c96ed47a7d45a4da0a ; platform_system == 'Linux' and python_version == '3.12' and platform_machine == 'x86_64'",
@@ -1185,93 +1051,15 @@ intelgputorch210 = [
     "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.25.0%2Bxpu-cp313-cp313-win_amd64.whl#sha256=1c4b44b36a557f7381e3076fb8843366742238648441d607c8d049c6da0f8886 ; sys_platform == 'win32' and python_version == '3.13' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
 ]
 intel-gpu-torch210 = [
-    "unsloth[intelgputorch210]",
-    "unsloth[audio-torch210]",
-]
-intelgputorch2110 = [
-    "unsloth_zoo[intelgpu]",
-    "unsloth[huggingfacenotorch]",
-
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.7.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl#sha256=2a1841138750f708ec017becbf8d357526f3fa350deee6553be5735ad66160a3 ; platform_system == 'Linux' and python_version == '3.10' and platform_machine == 'x86_64'",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.7.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl#sha256=e85378f1fc1ea002271de2a35475b75008fa554b86ef9d3bc55be9c513a63b51 ; platform_system == 'Linux' and python_version == '3.11' and platform_machine == 'x86_64'",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.7.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl#sha256=a6663ebe43e3c0d560ff774708632d7a75208ee64a291c1724ed5c16a92d1c72 ; platform_system == 'Linux' and python_version == '3.12' and platform_machine == 'x86_64'",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.7.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl#sha256=08c8d43b2831faf9d6799480df2b45dde58102257aebd810d07a2ce18cd4e5df ; platform_system == 'Linux' and python_version == '3.13' and platform_machine == 'x86_64'",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.7.0-cp310-cp310-win_amd64.whl#sha256=90fb8f767950a4ffca627faa7f86d9c697237ea4352d7e23505c5c9ed8e72216 ; sys_platform == 'win32' and python_version == '3.10' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.7.0-cp311-cp311-win_amd64.whl#sha256=aa7de82f4265089e74f25a2701b7532e5c47d74224d877b61da1d66156e3f0c1 ; sys_platform == 'win32' and python_version == '3.11' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.7.0-cp312-cp312-win_amd64.whl#sha256=5ba3a31c6e1b259ad2d924e1b50f72a78c6ebd7eb4f364473bbf93e144734e80 ; sys_platform == 'win32' and python_version == '3.12' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.7.0-cp313-cp313-win_amd64.whl#sha256=e8b4caba9b2399ea4c7f9a2777042564dea5d6f9e586a2dcb015a4ce20f000f7 ; sys_platform == 'win32' and python_version == '3.13' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.11.0%2Bxpu-cp310-cp310-linux_x86_64.whl ; platform_system == 'Linux' and python_version == '3.10' and platform_machine == 'x86_64'",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.11.0%2Bxpu-cp311-cp311-linux_x86_64.whl ; platform_system == 'Linux' and python_version == '3.11' and platform_machine == 'x86_64'",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.11.0%2Bxpu-cp312-cp312-linux_x86_64.whl ; platform_system == 'Linux' and python_version == '3.12' and platform_machine == 'x86_64'",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.11.0%2Bxpu-cp313-cp313-linux_x86_64.whl ; platform_system == 'Linux' and python_version == '3.13' and platform_machine == 'x86_64'",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.11.0%2Bxpu-cp310-cp310-win_amd64.whl ; sys_platform == 'win32' and python_version == '3.10' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.11.0%2Bxpu-cp311-cp311-win_amd64.whl ; sys_platform == 'win32' and python_version == '3.11' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.11.0%2Bxpu-cp312-cp312-win_amd64.whl ; sys_platform == 'win32' and python_version == '3.12' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.11.0%2Bxpu-cp313-cp313-win_amd64.whl ; sys_platform == 'win32' and python_version == '3.13' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-
-    "bitsandbytes @ https://github.com/bitsandbytes-foundation/bitsandbytes/releases/download/continuous-release_main/bitsandbytes-1.33.7.preview-py3-none-manylinux_2_24_x86_64.whl ; ('linux' in sys_platform) and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "bitsandbytes @ https://github.com/bitsandbytes-foundation/bitsandbytes/releases/download/continuous-release_main/bitsandbytes-1.33.7.preview-py3-none-win_amd64.whl ; (sys_platform == 'win32') and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.26.0%2Bxpu-cp310-cp310-manylinux_2_28_x86_64.whl#sha256=6e634354b752b7366e8ad16b84f3e7e5863776a7ab448bbabae4fd36668dee7a ; platform_system == 'Linux' and python_version == '3.10' and platform_machine == 'x86_64'",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.26.0%2Bxpu-cp311-cp311-manylinux_2_28_x86_64.whl#sha256=293169899f562ce473a58836dd024f0b1e72a347400278287ab393d1b04991e4 ; platform_system == 'Linux' and python_version == '3.11' and platform_machine == 'x86_64'",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.26.0%2Bxpu-cp312-cp312-manylinux_2_28_x86_64.whl#sha256=e204d14be6f0f84d5f0e6e9213556e80326c3ab682cac108bcbef340bf45297b ; platform_system == 'Linux' and python_version == '3.12' and platform_machine == 'x86_64'",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.26.0%2Bxpu-cp313-cp313-manylinux_2_28_x86_64.whl#sha256=f134344006f0989a2d771554b7905fb05bd93d63b195e64626fde3495ec6f287 ; platform_system == 'Linux' and python_version == '3.13' and platform_machine == 'x86_64'",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.26.0%2Bxpu-cp310-cp310-win_amd64.whl#sha256=7e52729cb9736c66dc79a7f42de6b31db93b9161d3357fd34cfa33f5fe32b8ea ; sys_platform == 'win32' and python_version == '3.10' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.26.0%2Bxpu-cp311-cp311-win_amd64.whl#sha256=83a6130100c6b6750d8aa9fd29e5d0c53b1c85b1153b8ed4139aea54fc1892cc ; sys_platform == 'win32' and python_version == '3.11' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.26.0%2Bxpu-cp312-cp312-win_amd64.whl#sha256=03788e0e5a5b85a2f09d11f0263d579fcb0cf5623d8810149be0e37836c2738c ; sys_platform == 'win32' and python_version == '3.12' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.26.0%2Bxpu-cp313-cp313-win_amd64.whl#sha256=cb1da1d378ce440f7d1e0ed8cf21bd280d904ab25a55c9453f8377825818df74 ; sys_platform == 'win32' and python_version == '3.13' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-]
-intel-gpu-torch2110 = [
-    "unsloth[intelgputorch2110]"
-]
-intelgputorch2120 = [
-    "unsloth_zoo[intelgpu]",
-    "unsloth[huggingfacenotorch]",
-
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.7.1-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl#sha256=81ff0eb0c4fc8e19d2510b28c3e1d9382a3c7d6fdaf6a9f9631a93a030d841cf ; platform_system == 'Linux' and python_version == '3.10' and platform_machine == 'x86_64'",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.7.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl#sha256=55574a68d275b85cd4d5cbf185084bae019ebf09c3f43b0bd2831b14935ec8e7 ; platform_system == 'Linux' and python_version == '3.11' and platform_machine == 'x86_64'",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.7.1-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl#sha256=a31c058c5c2e78ebe490a2e69f2f50caec6b1307ac096e944f116fdc06819d9a ; platform_system == 'Linux' and python_version == '3.12' and platform_machine == 'x86_64'",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.7.1-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl#sha256=e701a31efa0334775f357c98716f3821775aa944219f7888e13c2dfe2daabe2a ; platform_system == 'Linux' and python_version == '3.13' and platform_machine == 'x86_64'",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.7.1-cp310-cp310-win_amd64.whl#sha256=0d7730651c3e52fbf3a430cc201455f0c6600dc72e681aec495f131ea44f341a ; sys_platform == 'win32' and python_version == '3.10' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.7.1-cp311-cp311-win_amd64.whl#sha256=8f4a63de73e3d632098f93c8f0bd77244958a47d7c5f728b8ff35f8a91fdb983 ; sys_platform == 'win32' and python_version == '3.11' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.7.1-cp312-cp312-win_amd64.whl#sha256=6589ece3adc2b1ab88d90ff1267afc25df5c7b868f0b633e732cac70df36cbde ; sys_platform == 'win32' and python_version == '3.12' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "triton-xpu @ https://download.pytorch.org/whl/triton_xpu-3.7.1-cp313-cp313-win_amd64.whl#sha256=2fdf001a9b0575e8b1827127259bb9b13bf36e659882be74c2dfab46597d3e7a ; sys_platform == 'win32' and python_version == '3.13' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.12.0%2Bxpu-cp310-cp310-linux_x86_64.whl#sha256=e8923cd1fe560472904b1461b745d2f1826bb9c1bc0808225d5f28a450e4d553 ; platform_system == 'Linux' and python_version == '3.10' and platform_machine == 'x86_64'",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.12.0%2Bxpu-cp311-cp311-linux_x86_64.whl#sha256=f7c082b2fc9b61def594d30ea57762dc4a8bc7111a9a9593953ed948de242e28 ; platform_system == 'Linux' and python_version == '3.11' and platform_machine == 'x86_64'",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.12.0%2Bxpu-cp312-cp312-linux_x86_64.whl#sha256=f59decc04bec27862ed0197554a52370dbcba3e6892616d1fbce450e402bf2d5 ; platform_system == 'Linux' and python_version == '3.12' and platform_machine == 'x86_64'",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.12.0%2Bxpu-cp313-cp313-linux_x86_64.whl#sha256=56f74e7c6c096e1a7ac215eb79ee590b764be3fbba8f4febc145bca47194a083 ; platform_system == 'Linux' and python_version == '3.13' and platform_machine == 'x86_64'",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.12.0%2Bxpu-cp310-cp310-win_amd64.whl#sha256=b9779b71457b5a916ae052ed2467c10273cae4862d469b191359173b2038c53e ; sys_platform == 'win32' and python_version == '3.10' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.12.0%2Bxpu-cp311-cp311-win_amd64.whl#sha256=7ef8e776c992e4e3ae007ebc108eb4f36b1d1dd9da97ecb308ab7fded89a2659 ; sys_platform == 'win32' and python_version == '3.11' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.12.0%2Bxpu-cp312-cp312-win_amd64.whl#sha256=7f1d40febf2b8724adf4ff23866897d87478cc43de2a20f7776dc00be334c464 ; sys_platform == 'win32' and python_version == '3.12' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torch @ https://download.pytorch.org/whl/xpu/torch-2.12.0%2Bxpu-cp313-cp313-win_amd64.whl#sha256=32770e2613df26e2c81ae64ea001b2ca12b8d152231285caff9b5f963a21ad75 ; sys_platform == 'win32' and python_version == '3.13' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-
-    "bitsandbytes @ https://github.com/bitsandbytes-foundation/bitsandbytes/releases/download/continuous-release_main/bitsandbytes-1.33.7.preview-py3-none-manylinux_2_24_x86_64.whl ; ('linux' in sys_platform) and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "bitsandbytes @ https://github.com/bitsandbytes-foundation/bitsandbytes/releases/download/continuous-release_main/bitsandbytes-1.33.7.preview-py3-none-win_amd64.whl ; (sys_platform == 'win32') and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.27.0%2Bxpu-cp310-cp310-manylinux_2_28_x86_64.whl#sha256=0d517462caf6f5201c0d7c880f4ac431783c88fcc59b4587836da6c72a89509c ; platform_system == 'Linux' and python_version == '3.10' and platform_machine == 'x86_64'",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.27.0%2Bxpu-cp311-cp311-manylinux_2_28_x86_64.whl#sha256=4b6feada86aa0bd606904b05898b33538106120d8ed706ba11d0011046534cb8 ; platform_system == 'Linux' and python_version == '3.11' and platform_machine == 'x86_64'",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.27.0%2Bxpu-cp312-cp312-manylinux_2_28_x86_64.whl#sha256=e231819be0f87829c2344c909c1f0db9d6ae7d6faefe644a526a1a01d0c18d98 ; platform_system == 'Linux' and python_version == '3.12' and platform_machine == 'x86_64'",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.27.0%2Bxpu-cp313-cp313-manylinux_2_28_x86_64.whl#sha256=8bc7d37515cea18af4c389d5fde58b1a9d76b015f2d87e4a7dc62ad50b1cc200 ; platform_system == 'Linux' and python_version == '3.13' and platform_machine == 'x86_64'",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.27.0%2Bxpu-cp310-cp310-win_amd64.whl#sha256=65dbb041057dddfe369f29cfaab63f75563621779a23a7b1e2c0ff8a84d4376a ; sys_platform == 'win32' and python_version == '3.10' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.27.0%2Bxpu-cp311-cp311-win_amd64.whl#sha256=df647445365924d69fe3bb2a15a7edfe5b63ef91e4ae69af11d93582985237a4 ; sys_platform == 'win32' and python_version == '3.11' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.27.0%2Bxpu-cp312-cp312-win_amd64.whl#sha256=b0db3df0d0d154d18ba988ab420f1da2549f9372113ff54ff66e4ae3c7fe3bd0 ; sys_platform == 'win32' and python_version == '3.12' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "torchvision @ https://download.pytorch.org/whl/xpu/torchvision-0.27.0%2Bxpu-cp313-cp313-win_amd64.whl#sha256=c70850842068c43a0d50eaf139c25b6f6cc9b17a0dae70218c7e69edbee0bc80 ; sys_platform == 'win32' and python_version == '3.13' and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-]
-intel-gpu-torch2120 = [
-    "unsloth[intelgputorch2120]"
+    "unsloth[intelgputorch210]"
 ]
 intel = [
     "unsloth[intelgputorch280]",
 ]
 amd = [
     "unsloth[huggingfacenotorch]",
-    # 4-bit decode is unreliable on ROCm before 0.50.0, the first PyPI release
-    # carrying the full path: blocksize/warp decoupling (bnb #1887), fused SIMT
-    # GEMM on RDNA (#1979), RDNA3/4 workgroup fix (#2012).
-    "bitsandbytes>=0.50.0 ; ('linux' in sys_platform) and (platform_machine == 'AMD64' or platform_machine == 'x86_64' or platform_machine == 'aarch64')",
-    "bitsandbytes>=0.50.0 ; (sys_platform == 'win32') and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
+    "bitsandbytes>=0.49.1 ; ('linux' in sys_platform) and (platform_machine == 'AMD64' or platform_machine == 'x86_64' or platform_machine == 'aarch64')",
+    "bitsandbytes>=0.49.1 ; (sys_platform == 'win32') and (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
 ]
 rocm702-torch280 = [
     "unsloth[amd]",
@@ -1343,7 +1131,6 @@ rocm72-torch2100 = [
     "torchvision @ https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2/torchvision-0.25.0%2Brocm7.2.0.git82df5f59-cp311-cp311-linux_x86_64.whl ; platform_system == 'Linux' and python_version == '3.11' and platform_machine == 'x86_64'",
     "torchvision @ https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2/torchvision-0.25.0%2Brocm7.2.0.git82df5f59-cp312-cp312-linux_x86_64.whl ; platform_system == 'Linux' and python_version == '3.12' and platform_machine == 'x86_64'",
     "torchvision @ https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2/torchvision-0.25.0%2Brocm7.2.0.git82df5f59-cp313-cp313-linux_x86_64.whl ; platform_system == 'Linux' and python_version == '3.13' and platform_machine == 'x86_64'",
-    "unsloth[audio-torch210]",
 ]
 rocm711-torch2100 = [
     "unsloth[amd]",
@@ -1362,7 +1149,6 @@ rocm711-torch2100 = [
     "torchvision @ https://repo.radeon.com/rocm/manylinux/rocm-rel-7.1.1/torchvision-0.25.0%2Brocm7.1.1.git82df5f59-cp311-cp311-linux_x86_64.whl ; platform_system == 'Linux' and python_version == '3.11' and platform_machine == 'x86_64'",
     "torchvision @ https://repo.radeon.com/rocm/manylinux/rocm-rel-7.1.1/torchvision-0.25.0%2Brocm7.1.1.git82df5f59-cp312-cp312-linux_x86_64.whl ; platform_system == 'Linux' and python_version == '3.12' and platform_machine == 'x86_64'",
     "torchvision @ https://repo.radeon.com/rocm/manylinux/rocm-rel-7.1.1/torchvision-0.25.0%2Brocm7.1.1.git82df5f59-cp313-cp313-linux_x86_64.whl ; platform_system == 'Linux' and python_version == '3.13' and platform_machine == 'x86_64'",
-    "unsloth[audio-torch210]",
 ]
 
 [project.urls]
@@ -1372,7 +1158,6 @@ repository = "https://github.com/unslothai/unsloth"
 
 [tool.ruff]
 target-version = "py311"
-line-length = 100
 force-exclude = true
 extend-exclude = [
     "*chat_templates.py",
@@ -1399,10 +1184,3 @@ ignore = [
 ]
 
 [tool.ruff.format]
-
-[tool.pytest.ini_options]
-# Narrow the default test discovery so `pytest` from the repo root
-# does NOT pick up the GPU-heavy tests under tests/python, tests/qlora,
-# etc. The CI security job runs `pytest tests/security` explicitly.
-testpaths = ["tests/security"]
-pythonpath = ["."]

scripts/benchmarks/README.md

@@ -0,0 +1,252 @@
+# Qwen3-4B GRPO rollout engine benchmarks
+
+This directory holds the reproducible scripts behind the experiment
+documented in the accompanying PR: can Hugging Face transformers'
+continuous-batching API (`model.generate_batch`, backed by
+`PagedAttentionCache`) serve as a drop-in replacement for vLLM during GRPO
+rollouts on the Qwen3-4B notebook?
+
+The short answer on a single NVIDIA B200 with Unsloth Qwen3-4B-Base, LoRA
+rank 32, bf16: transformers continuous batching is functionally correct and
+integrates with TRL's `use_transformers_paged=True` path, but end-to-end
+throughput lands at around 7 to 10 percent of vLLM colocated even after
+wiring in Flash Attention 4 on Blackwell. Full numbers and per-step timings
+are in the PR description.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `unsloth_grpo_common.py` | Shared dataset loading, reward functions, and GRPO hyperparameters |
+| `qwen3_grpo_vllm.py` | vLLM baseline training entry (`fast_inference=True`, `use_vllm=True`, `vllm_mode="colocate"`) |
+| `qwen3_grpo_naive.py` | Naive TRL path (vanilla HF `model.generate`, no vLLM, no CB) matching https://huggingface.co/docs/trl/grpo_trainer |
+| `qwen3_grpo_tpaged.py` | Continuous-batching candidate (`fast_inference=False`, `use_transformers_paged=True`, vanilla HF + PEFT). Supports `--persistent_cb` |
+| `cb_vs_vllm_generation.py` | Standalone generation microbenchmark across both engines; supports `--attn_impl`, `--persistent_cb` |
+| `flash_attn_fa4_shim.py` | Installs two monkey-patches that let CB dispatch to FA4 when `--attn_impl flash_attention_2` is selected |
+| `persistent_cb.py` | Replaces `model.generate_batch` with a version that reuses a single `ContinuousBatchingManager` |
+
+## Flash Attention 4 on Blackwell (sm_100)
+
+The CB code path has three attention implementations: `eager_paged`,
+`sdpa_paged`, `flash_attention_2`. The last one requires the legacy
+`flash_attn` Python package, which does not install cleanly on B200 today:
+
+- `flash_attn==2.8.3+cu12torch2.8cxx11abiTRUE-cp313` from the Dao-AILab
+  releases hits `undefined symbol: _ZNK3c106SymInt6sym_neERKS0_` on torch
+  2.9.1 (ABI drift between torch 2.8 and 2.9).
+- `flash_attn_3-3.0.0-cp39-abi3-manylinux_2_28_x86_64.whl` from the PyTorch
+  wheel index installs but was built for sm_80 and sm_90a only. B200 is
+  sm_100. The kernel call fails with "no kernel image is available for
+  execution on the device".
+- `flash-attn-4==4.0.0b9` (pure Python CuTeDSL, Dao-AILab) works on B200.
+  It exposes `flash_attn.cute.flash_attn_varlen_func`.
+
+The recipe this repo uses:
+
+```bash
+uv pip install --no-deps flash-attn-4==4.0.0b9
+```
+
+plus a tiny site-packages shim that re-exports FA4 symbols under the
+FA2 `flash_attn` namespace so transformers' `is_flash_attn_2_available()` and
+`_lazy_imports("flash_attention_2")` succeed. The shim lives out of tree in
+`lib/python3.13/site-packages/flash_attn/__init__.py` +
+`flash_attn/bert_padding.py` + a `flash_attn-2.8.3.dist-info/` directory
+with enough metadata to satisfy `importlib.metadata.version("flash_attn")`.
+
+On top of that, `flash_attn_fa4_shim.py` monkey-patches two rough edges in
+the CB to FA integration that are unrelated to which FA version you use:
+
+1. `ContinuousBatchProcessor.return_attention_mask` returns `False` for
+   `flash_attention_2` / `flash_attention_3` so CB does not emit a 4-D paged
+   attention mask that breaks `_flash_attention_forward`'s `_upad_input`
+   branch.
+2. `_flash_attention_forward` accepts `max_seqlen_q` / `max_seqlen_k`
+   as aliases for `max_length_q` / `max_length_k`. Without this rename CB's
+   model kwargs never bind and FA is called with `max_seqlen_q=None`.
+
+## Install
+
+Prereqs: `torch >= 2.5` for `torch.nn.attention.flex_attention`. The
+Triton backend that flex_attention uses by default runs on Ampere,
+Hopper, and Blackwell -- no separate install.
+
+FA4 (CuTeDSL) targets Hopper and Blackwell only. `qwen3_flex_inference.py`
+auto-enables FA4 on supported GPUs and falls back to the Triton
+`flex_attention` backend elsewhere. `--fa4_prefill` forces on (warns +
+falls back if the GPU does not support it); `--no-fa4_prefill` forces off.
+
+CUDA 13 (recommended, used on B200 / RTX 50xx):
+
+    pip install --index-url https://download.pytorch.org/whl/cu130 torch
+    pip install "flash-attn-4[cu13]"
+
+CUDA 12 (H100 boxes still on cu12):
+
+    pip install torch  # default index is cu12
+    pip install flash-attn-4
+
+Pin `flash-attn-4==4.0.0b9` to match this benchmark. The `[cu13]`
+extra pulls in `nvidia-cutlass-dsl` built for CUDA 13.
+
+`qwen3_flex_inference.py` runs on both Qwen3 and Llama-3.2 (the only
+arch-specific branch is Qwen3's per-head QK RMSNorm; the rest of the
+flex_attention + paged KV + CUDA graphs stack is identical). Pass
+`--model_name unsloth/Llama-3.2-3B-Instruct` to target Llama, along with
+`--chat_template native` to use Llama's shipped Instruct template instead
+of the Qwen3 GRPO template.
+
+`gemma4_flex_inference.py` extends the engine to `unsloth/gemma-4-E2B-it`.
+Gemma-4 is not a drop-in: its text backbone has KV-sharing layers
+(layers 15-34 consume full-sequence K/V produced by a store layer), two
+attention regimes (`full_attention` with `head_dim=512` / rope_theta=1e6
+and `sliding_attention` with `head_dim=256` / sliding_window=512),
+per-layer input embeddings, four norms per block with double residuals,
+and a final logit softcap. The new file keeps the shared helpers
+(`PagedKVCache`, `PageTable`, LoRA double-copy, drift verification)
+imported from `qwen3_flex_inference.py` and adds:
+
+- a KV-sharing sidecar dict, sized `[max_batch, n_kv, max_seq, head_dim]`
+  per store layer, populated at prefill and read by the paired shared
+  layers through eager SDPA (shared layers don't fit the paged-cache
+  block-mask shape);
+- dual RoPE precomputation — `rotary_emb(x, pos, layer_type)` called once
+  per unique layer type, indexed by `self.layer_type`;
+- a walker that threads `per_layer_inputs` from
+  `get_per_layer_inputs` + `project_per_layer_inputs` into each layer
+  and applies the `layer_scalar` multiply at layer end;
+- `tanh(logits / final_logit_softcapping) * final_logit_softcapping`
+  applied on the lm_head output.
+
+Requires `transformers>=5.5.0` for the `gemma4` module; if absent the
+script exits with a clear install hint. Gemma-4 head_dim=256 exceeds FA4
+on sm_100 (B200), so pass `--no-fa4_prefill` and small Triton blocks:
+
+```bash
+CUDA_VISIBLE_DEVICES=6 python scripts/benchmarks/gemma4_flex_inference.py \
+    --model_name unsloth/gemma-4-E2B-it \
+    --n_prompts 64 --max_new_tokens 512 --capture_cudagraph \
+    --no-fa4_prefill \
+    --prefill_kernel_options '{"FORCE_USE_FLEX_ATTENTION": true, "BLOCK_M": 32, "BLOCK_N": 32}' \
+    --decode_kernel_options '{"BLOCK_M": 16, "BLOCK_N": 16}' \
+    --stats_path logs/flex_gemma4_bf16.json
+```
+
+| GPU          | arch      | sm    | Auto FA4 | Triton flex_attention |
+|--------------|-----------|-------|----------|------------------------|
+| A100         | Ampere    | sm_80 | off (uses Triton) | Works |
+| H100 / H200  | Hopper    | sm_90 | on | Works |
+| RTX 50xx     | Blackwell | sm_120 | on | Works |
+| B200 / GB200 | Blackwell | sm_100 | on | Works |
+
+The transformers continuous-batching path's FA4 wiring (the
+`flash_attn_fa4_shim.py` monkey-patches and the
+`site-packages/flash_attn/__init__.py` namespace shim that makes FA4
+visible under the FA2 import name) is covered below under "Known
+integration notes".
+
+## Reproduce
+
+```bash
+pip install unsloth "transformers>=4.57" "trl>=0.25" peft vllm
+
+# Generation microbenchmark (32 prompts, 512 new tokens each)
+CUDA_VISIBLE_DEVICES=2 python scripts/benchmarks/cb_vs_vllm_generation.py \
+    --backend vllm --stats_path logs/vllm_gen.json \
+    --n_prompts 32 --n_rounds 2 --max_new_tokens 512 \
+    --gpu_memory_utilization 0.6
+
+# CB variants
+CUDA_VISIBLE_DEVICES=6 python scripts/benchmarks/cb_vs_vllm_generation.py \
+    --backend tpaged --attn_impl sdpa \
+    --stats_path logs/cb_gen_sdpa.json \
+    --n_prompts 32 --n_rounds 2 --max_new_tokens 512
+
+CUDA_VISIBLE_DEVICES=6 python scripts/benchmarks/cb_vs_vllm_generation.py \
+    --backend tpaged --attn_impl flash_attention_2 \
+    --stats_path logs/cb_gen_fa.json \
+    --n_prompts 32 --n_rounds 2 --max_new_tokens 512
+
+# Full GRPO training (20 steps)
+CUDA_VISIBLE_DEVICES=2 python scripts/benchmarks/qwen3_grpo_vllm.py \
+    --max_steps 20 --num_generations 2 --per_device_train_batch_size 2 \
+    --output_dir outputs/grpo_vllm --stats_path logs/vllm_stats.json \
+    --gpu_memory_utilization 0.6
+
+CUDA_VISIBLE_DEVICES=7 python scripts/benchmarks/qwen3_grpo_naive.py \
+    --max_steps 20 --num_generations 2 --per_device_train_batch_size 2 \
+    --output_dir outputs/grpo_naive --stats_path logs/naive_stats.json
+
+CUDA_VISIBLE_DEVICES=6 python scripts/benchmarks/qwen3_grpo_tpaged.py \
+    --max_steps 20 --num_generations 2 --per_device_train_batch_size 2 \
+    --attn_impl flash_attention_2 \
+    --output_dir outputs/grpo_tpaged_fa --stats_path logs/tpaged_stats_fa.json \
+    --max_batch_tokens 16384 --num_blocks 16384
+```
+
+`qwen3_grpo_naive.py` and `qwen3_grpo_tpaged.py` accept an optional
+`--compile_mode {default,reduce-overhead,max-autotune-no-cudagraphs}` flag.
+When set, `trainer.model.forward` (and `trainer.ref_model.forward`, if present)
+are wrapped with `torch.compile` after trainer construction. The vLLM driver
+has no such flag because vLLM owns its own inference graph. `--compile_dynamic`
+(default on) toggles dynamic-shape compilation.
+
+## Known integration notes for transformers continuous batching + TRL + Unsloth
+
+These are the sharp edges you hit going down the continuous-batching path and
+how `qwen3_grpo_tpaged.py` handles them:
+
+1. **`top_k=-1` is not a valid value for transformers.** vLLM treats `-1` as
+   "disabled", but `TopKLogitsWarper` raises
+   `ValueError: top_k has to be a strictly positive integer`. The script
+   rewrites `top_k=None` on the shared GRPOConfig before handing it to
+   `GRPOConfig(use_transformers_paged=True, ...)`.
+
+2. **`PagedAttentionCache` default upper bounds are extremely conservative.**
+   `_upper_bound_max_batch_tokens=256` and `_upper_bound_num_blocks=4096`
+   choke decode throughput. The script passes
+   `generation_kwargs={"max_batch_tokens": 16384, "num_blocks": 16384}` which
+   TRL forwards to `GenerationConfig`, and the CB manager reads them when
+   sizing the paged cache.
+
+3. **Unsloth's `Qwen3Attention_fast_forward` bypasses the functional
+   attention interface.** Calling `model.generate_batch` on an
+   Unsloth-patched Qwen3 model fails inside
+   `unsloth.utils.attention_dispatch.run_attention` because Unsloth routes
+   through its own dispatcher rather than reading
+   `config._attn_implementation`. The benchmark script works around this by
+   loading a vanilla HF Qwen3 with PEFT LoRA for the tpaged and naive paths.
+   This costs the Unsloth training kernels but keeps the comparison clean.
+   A proper upstream fix is to detect `config._attn_implementation` being
+   `flash_attention_2` / `sdpa_paged` / `eager_paged` and delegate to the
+   stock transformers forward.
+
+4. **TRL imports `GuidedDecodingParams` from `vllm.sampling_params`.**
+   Newer vLLM releases (>= 0.13) have moved or removed that symbol, so
+   `trl.trainer.grpo_trainer` fails to import on a fresh vLLM install even
+   if you are not using vLLM. `qwen3_grpo_tpaged.py` installs a minimal
+   shim before importing TRL.
+
+5. **`UnslothGRPOTrainer` calls `model.for_training()` /
+   `for_inference()`.** Importing `unsloth` replaces
+   `trl.GRPOTrainer` with `UnslothGRPOTrainer`, which assumes the model has
+   these hooks. A vanilla HF model does not, so
+   `qwen3_grpo_tpaged.py` does not `import unsloth` at all.
+
+## Why continuous batching is still slower than vLLM on this workload
+
+- `ContinuousBatchingManager` does not yet implement CUDA graphs
+  (`use_cuda_graph=True` raises `NotImplementedError`). vLLM captures 100+
+  mixed prefill-decode and decode graphs during warmup.
+- CB re-allocates a fresh `PagedAttentionCache` on every `generate_batch`
+  call. For GRPO that is once per step. `--persistent_cb` (via
+  `persistent_cb.py`) keeps the cache warm across steps.
+- FA4 is a CuTeDSL package: first call per shape pays a one-time
+  JIT-compile.
+- vLLM uses its own colocated attention + FlashInfer / TRTLLM kernels
+  tuned for decode, which currently outperform everything a generic CB
+  path can do.
+
+These are all upstream transformers issues, not Unsloth issues. The scripts
+in this directory are intentionally simple so they are easy to port into a
+future upstream fix.

scripts/benchmarks/cb_sync_driver.py

@@ -0,0 +1,357 @@
+"""Main-thread synchronous driver for `ContinuousBatchProcessor`.
+
+`ContinuousBatchingManager.start()` spawns a background thread that owns the
+decode loop. That thread conflicts with two things we want to enable here:
+
+1. `torch.compile(mode="reduce-overhead")` which uses `cudagraph_trees` and
+   requires main-thread TLS.
+2. Raw `torch.cuda.CUDAGraph` capture / replay on the decode forward.
+
+The manager's dead `warmup()` path suggests CB was supposed to grow CUDA
+graph support upstream but `init_continuous_batching` raises
+`NotImplementedError` on `use_cuda_graph=True`. This driver side-steps the
+whole manager thread, so the cudagraph integration point is now available.
+
+Key fixed-shape invariant: with `slice_inputs=False`, the full pre-allocated
+tensor buffers (input_ids, position_ids, cu_seq_lens_*, attention_mask,
+read_index / write_index) are returned as views of the same storage every
+step, so their shapes are constant across iterations. That is the
+precondition for graph replay / cudagraph_trees to be safe.
+
+Greedy sampling only (`do_sample=False`). `torch.multinomial` is not
+graph-friendly.
+
+Usage:
+    driver = SyncCBDriver(model, gen_config, CBSyncConfig(compile_mode="reduce-overhead"))
+    # Reuse across many rollouts (cache / compiled forward stay warm):
+    for batch in batches:
+        driver.add_requests(batch)
+        out = driver.drive_until_empty()
+"""
+
+from __future__ import annotations
+
+import queue
+import time
+from dataclasses import dataclass, field
+from typing import Optional
+
+import torch
+from transformers.generation.configuration_utils import GenerationConfig
+from transformers.generation.continuous_batching import (
+    PagedAttentionCache,
+    RequestStatus,
+)
+from transformers.generation.continuous_batching.continuous_api import (
+    ContinuousBatchProcessor,
+    ContinuousBatchingManager,
+)
+from transformers.generation.continuous_batching.scheduler import FIFOScheduler
+
+
+@dataclass
+class CBSyncConfig:
+    """Tunables for the sync driver."""
+
+    max_new_tokens: int = 512
+    # torch.compile mode for the model forward. None = eager.
+    # "reduce-overhead" triggers cudagraph_trees, which captures a CUDA
+    # graph per unique input shape and replays it afterwards.
+    compile_mode: Optional[str] = None
+    do_sample: bool = False  # greedy only (graph-safe)
+    eos_token_id: Optional[int] = None
+    pad_token_id: Optional[int] = None
+    # `slice_inputs=False` would give fixed shapes every step (graph-friendly)
+    # but forces every decode step to do `max_batch_tokens` tokens of work,
+    # which at max_batch_tokens=8192 is ~256x more than the real decode batch.
+    # Prefer `slice_inputs=True` (natural shapes) and let torch.compile bucket
+    # per shape. Steady-state decode has one shape so most steps replay the
+    # same graph anyway.
+    slice_inputs: bool = True
+    # Paged cache upper bounds.
+    max_batch_tokens: int = 8192
+    num_blocks: int = 8192
+    # `torch._dynamo.config.cache_size_limit`: raise when varying shapes.
+    dynamo_cache_size_limit: int = 256
+    on_step: Optional[callable] = field(default = None)
+
+
+class SyncCBDriver:
+    """Main-thread driver that owns the PagedAttentionCache,
+    ContinuousBatchProcessor, and optionally a `torch.compile`-compiled
+    forward. Reusable across multiple `drive_until_empty` calls -- the cache
+    and compiled forward stay warm between rounds.
+    """
+
+    def __init__(
+        self,
+        model: torch.nn.Module,
+        generation_config: GenerationConfig,
+        cfg: CBSyncConfig,
+    ):
+        self.model = model.eval()
+        self.cfg = cfg
+        gc = GenerationConfig.from_dict(generation_config.to_dict())
+        gc.do_sample = cfg.do_sample
+        if cfg.max_new_tokens:
+            gc.max_new_tokens = cfg.max_new_tokens
+        if cfg.eos_token_id is not None:
+            gc.eos_token_id = cfg.eos_token_id
+        if cfg.pad_token_id is not None:
+            gc.pad_token_id = cfg.pad_token_id
+        gc.max_batch_tokens = cfg.max_batch_tokens
+        gc.num_blocks = cfg.num_blocks
+        self.generation_config = gc
+
+        self.manager = ContinuousBatchingManager(
+            model = self.model,
+            generation_config = gc,
+            manual_eviction = False,
+            streaming = False,
+            slice_inputs = cfg.slice_inputs,
+        )
+
+        self.cache = PagedAttentionCache(
+            self.model.config,
+            gc,
+            self.model.device,
+            self.model.dtype,
+            tp_size = getattr(self.model, "_tp_size", None),
+        )
+        self.batch_processor = ContinuousBatchProcessor(
+            self.cache,
+            self.model.config,
+            gc,
+            self.manager.input_queue,
+            self.manager.output_queue,
+            self.manager.stop_event,
+            self.model.device,
+            self.model.dtype,
+            FIFOScheduler(self.cache),
+            streaming = False,
+            manual_eviction = False,
+            slice_inputs = cfg.slice_inputs,
+        )
+        self.manager.batch_processor = self.batch_processor
+
+        # torch.compile on the model forward. With slice_inputs=True the
+        # forward sees varying shapes (prefill bursts + decode steady state);
+        # `dynamic=True` lets Inductor bucket per shape without re-tracing
+        # every call, and `mode="reduce-overhead"` wraps each bucket in a
+        # CUDA graph replay path.
+        if cfg.compile_mode:
+            import torch._dynamo
+
+            torch._dynamo.config.cache_size_limit = cfg.dynamo_cache_size_limit
+            # GRPO's `requires_grad_` issue doesn't apply here (eval mode).
+            try:
+                torch._dynamo.config.allow_unspec_int_on_nn_module = True
+            except AttributeError:
+                pass
+            print(
+                f"[cb_sync] torch.compile(model, mode='{cfg.compile_mode}', "
+                f"dynamic=True)"
+            )
+            self.model.forward = torch.compile(
+                self.model.forward,
+                mode = cfg.compile_mode,
+                dynamic = True,
+                fullgraph = False,
+            )
+        self._step_count = 0
+
+    def add_requests(self, prompt_ids_list: list[list[int]]) -> list[str]:
+        return [self.manager.add_request(ids) for ids in prompt_ids_list]
+
+    def drive_until_empty(self) -> dict[str, list[int]]:
+        """Run the decode loop until every request finishes. Returns a dict
+        {request_id: generated_token_ids}.
+
+        Reusable across calls on the same driver -- the paged cache and the
+        compiled forward stay warm.
+        """
+        results: dict[str, list[int]] = {}
+        while True:
+            if (
+                self.manager.input_queue.empty()
+                and not self.batch_processor.has_pending_requests()
+            ):
+                break
+            if not self.batch_processor.prepare_next_batch():
+                break
+            # With `reduce-overhead`, Inductor captures a CUDA graph on the
+            # first call with a given shape signature and replays it after.
+            # Our shapes are constant (slice_inputs=False), so the second call
+            # is already replaying. No per-step torch.cuda.synchronize() --
+            # the replay itself fences appropriately.
+            self.manager._generation_step(self.batch_processor)
+            self.batch_processor.update_batch()
+            self._step_count += 1
+            if self.cfg.on_step is not None:
+                self.cfg.on_step(self._step_count, 0)
+            # Drain output_queue as requests finish.
+            while True:
+                try:
+                    out = self.manager.output_queue.get_nowait()
+                except queue.Empty:
+                    break
+                if out.status == RequestStatus.FINISHED:
+                    results[out.request_id] = out.generated_tokens
+        while True:
+            try:
+                out = self.manager.output_queue.get_nowait()
+            except queue.Empty:
+                break
+            if out.status == RequestStatus.FINISHED:
+                results[out.request_id] = out.generated_tokens
+        return results
+
+    def close(self):
+        self.cache = None
+        self.batch_processor = None
+        self.manager.batch_processor = None
+
+
+# Simple microbench harness so the file is runnable standalone.
+if __name__ == "__main__":
+    import argparse
+    import json
+    import os
+    import sys
+    from pathlib import Path
+
+    HERE = Path(__file__).resolve().parent
+    sys.path.insert(0, str(HERE))
+
+    import flash_attn_fa4_shim  # noqa: E402
+
+    flash_attn_fa4_shim.apply()
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--model_name", default = "unsloth/Qwen3-4B-Base")
+    parser.add_argument("--n_prompts", type = int, default = 32)
+    parser.add_argument("--n_rounds", type = int, default = 2)
+    parser.add_argument("--max_new_tokens", type = int, default = 512)
+    parser.add_argument("--attn_impl", default = "paged_attention")
+    parser.add_argument(
+        "--compile_mode",
+        default = None,
+        choices = [
+            None,
+            "default",
+            "reduce-overhead",
+            "max-autotune",
+            "max-autotune-no-cudagraphs",
+        ],
+    )
+    parser.add_argument("--max_batch_tokens", type = int, default = 8192)
+    parser.add_argument("--num_blocks", type = int, default = 8192)
+    parser.add_argument("--lora_adapter", default = None)
+    parser.add_argument("--stats_path", required = True)
+    args = parser.parse_args()
+
+    from transformers import AutoModelForCausalLM, AutoTokenizer, GenerationConfig
+
+    tok = AutoTokenizer.from_pretrained(args.model_name)
+    if tok.pad_token is None:
+        tok.pad_token = tok.eos_token
+    model = AutoModelForCausalLM.from_pretrained(
+        args.model_name,
+        dtype = torch.bfloat16,
+        attn_implementation = args.attn_impl,
+    ).to("cuda")
+    model.eval()
+
+    if args.lora_adapter:
+        from peft import PeftModel
+
+        model = PeftModel.from_pretrained(
+            model, str(Path(args.lora_adapter).resolve()), is_trainable = False
+        )
+        model.eval()
+
+    from unsloth_grpo_common import (
+        SYSTEM_PROMPT,
+        apply_chat_template_to_tokenizer,
+    )
+    from datasets import load_dataset
+
+    apply_chat_template_to_tokenizer(tok)
+    ds = load_dataset("open-r1/DAPO-Math-17k-Processed", "en", split = "train")
+    ds = ds.shuffle(seed = 3407).select(range(args.n_prompts))
+    messages = [
+        [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": x["prompt"]},
+        ]
+        for x in ds
+    ]
+    prompt_ids = [
+        tok.apply_chat_template(m, add_generation_prompt = True, tokenize = True)
+        for m in messages
+    ]
+
+    gc_cfg = GenerationConfig(
+        max_new_tokens = args.max_new_tokens,
+        do_sample = False,
+        pad_token_id = tok.pad_token_id,
+        bos_token_id = tok.bos_token_id,
+        eos_token_id = tok.eos_token_id,
+        use_cache = True,
+    )
+
+    cfg = CBSyncConfig(
+        max_new_tokens = args.max_new_tokens,
+        compile_mode = args.compile_mode,
+        max_batch_tokens = args.max_batch_tokens,
+        num_blocks = args.num_blocks,
+        eos_token_id = tok.eos_token_id,
+        pad_token_id = tok.pad_token_id or tok.eos_token_id,
+    )
+
+    torch.cuda.reset_peak_memory_stats()
+
+    # One driver, multiple rounds -- cache + compiled forward stay warm.
+    driver = SyncCBDriver(model, gc_cfg, cfg)
+
+    # Warmup (first 16 prompts). With compile, this amortizes the capture.
+    print("[cb_sync] warmup...")
+    driver.add_requests(prompt_ids[:16])
+    _ = driver.drive_until_empty()
+    torch.cuda.synchronize()
+
+    wall_times = []
+    total_decoded = 0
+    for r in range(args.n_rounds):
+        torch.cuda.synchronize()
+        t0 = time.perf_counter()
+        driver.add_requests(prompt_ids)
+        results = driver.drive_until_empty()
+        torch.cuda.synchronize()
+        wall_times.append(time.perf_counter() - t0)
+        total_decoded = sum(len(v) for v in results.values())
+        print(
+            f"[cb_sync] round {r}: {wall_times[-1]:.2f}s, {total_decoded} tokens, "
+            f"{total_decoded / wall_times[-1]:.1f} tok/s"
+        )
+
+    med = sorted(wall_times)[len(wall_times) // 2]
+    out = {
+        "backend": "cb_sync_driver",
+        "compile_mode": args.compile_mode,
+        "attn_impl": args.attn_impl,
+        "lora_adapter": args.lora_adapter,
+        "n_prompts": args.n_prompts,
+        "n_decoded_tokens": total_decoded,
+        "wall_times_s": wall_times,
+        "median_wall_s": med,
+        "decode_tps": total_decoded / med if med else 0,
+        "max_new_tokens": args.max_new_tokens,
+        "peak_memory_gb": torch.cuda.max_memory_allocated() / 1024**3,
+    }
+    os.makedirs(os.path.dirname(os.path.abspath(args.stats_path)) or ".", exist_ok = True)
+    with open(args.stats_path, "w") as f:
+        json.dump(out, f, indent = 2)
+    print(json.dumps(out, indent = 2))
+    driver.close()
+    os._exit(0)

scripts/benchmarks/cb_vs_vllm_generation.py

@@ -0,0 +1,535 @@
+"""Standalone generation microbenchmark: vLLM vs transformers CB vs Unsloth.
+
+Backends (one per process; all engines are GPU-greedy):
+- `vllm`             : Unsloth `fast_inference=True` (vLLM colocated).
+- `tpaged`           : `model.generate_batch` on paged HF + `--attn_impl`.
+- `unsloth_fi_false` : Unsloth `fast_inference=False` with the custom HF
+                       inference kernels (cached fp16 LoRA).
+
+LoRA: pass `--lora_adapter PATH` to activate a PEFT-style rank-32 adapter on
+both vLLM (`LoRARequest`) and the HF paths (`peft.PeftModel.from_pretrained`,
+or for `unsloth_fi_false` `FastLanguageModel.get_peft_model` pointed at the
+same weights).
+
+Equivalence-friendly sampling defaults (`--temperature 0.1 --top_p 0.97
+--min_p 0.5 --top_k 5`) keep rollouts comparable across backends for the KL /
+reward diff checks done in Phase 2.
+
+Usage:
+    CUDA_VISIBLE_DEVICES=6 python scripts/benchmarks/cb_vs_vllm_generation.py \
+        --backend vllm --stats_path logs/lora_vllm_gen.json \
+        --lora_adapter outputs/lora_rank32_fresh
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+
+import torch  # noqa: E402
+
+# FA4 shim for the `tpaged` backend with paged_attention. No-op for vLLM /
+# unsloth_fi_false.
+import flash_attn_fa4_shim  # noqa: E402
+
+flash_attn_fa4_shim.apply()
+
+
+def build_prompts(tokenizer, n_prompts, chat_template = "auto", model_type_name = None):
+    from unsloth_grpo_common import (
+        apply_chat_template_to_tokenizer,
+        SYSTEM_PROMPT,
+    )
+    from datasets import load_dataset
+
+    if chat_template == "auto":
+        use_grpo = (model_type_name or "").startswith("Qwen3")
+    elif chat_template == "grpo":
+        use_grpo = True
+    else:  # "native"
+        use_grpo = False
+    if use_grpo:
+        apply_chat_template_to_tokenizer(tokenizer)
+        print("[bench] chat_template: GRPO")
+    else:
+        print("[bench] chat_template: tokenizer native")
+    ds = load_dataset("open-r1/DAPO-Math-17k-Processed", "en", split = "train")
+    ds = ds.shuffle(seed = 3407).select(range(n_prompts))
+    messages = [
+        [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": x["prompt"]},
+        ]
+        for x in ds
+    ]
+    prompts_text = [
+        tokenizer.apply_chat_template(m, add_generation_prompt = True, tokenize = False)
+        for m in messages
+    ]
+    prompt_ids = [
+        tokenizer.apply_chat_template(m, add_generation_prompt = True, tokenize = True)
+        for m in messages
+    ]
+    return prompts_text, prompt_ids
+
+
+def run_vllm(args):
+    os.environ.setdefault("UNSLOTH_VLLM_STANDBY", "1")
+    from unsloth import FastLanguageModel
+
+    fi_kwargs = dict(
+        model_name = args.model_name,
+        max_seq_length = args.max_seq_length,
+        load_in_4bit = args.load_in_4bit,
+        fast_inference = True,
+        max_lora_rank = 32,
+        gpu_memory_utilization = args.gpu_memory_utilization,
+    )
+    if args.enforce_eager:
+        # vLLM 0.19 + torch 2.10 hits `RuntimeError: Tried to erase Node
+        # size_1 but it still had 2 users` during split_graph. enforce_eager
+        # skips vLLM's torch.compile path entirely (still PagedAttention +
+        # FlashInfer decode, just no graph capture).
+        fi_kwargs["enforce_eager"] = True
+    model, tokenizer = FastLanguageModel.from_pretrained(**fi_kwargs)
+    prompts_text, prompt_ids = build_prompts(
+        tokenizer,
+        args.n_prompts,
+        chat_template = args.chat_template,
+        model_type_name = type(getattr(model, "model", model)).__name__,
+    )
+
+    lora_request = None
+    if args.lora_adapter:
+        from vllm.lora.request import LoRARequest
+
+        lora_request = LoRARequest("fresh", 1, str(Path(args.lora_adapter).resolve()))
+
+    from vllm import SamplingParams
+
+    sp = SamplingParams(
+        temperature = args.temperature,
+        top_p = args.top_p,
+        min_p = args.min_p,
+        top_k = args.top_k,
+        seed = 3407,
+        max_tokens = args.max_new_tokens,
+        stop = [tokenizer.eos_token],
+        include_stop_str_in_output = True,
+    )
+
+    # Warmup on 16 prompts then discard.
+    warmup_text = prompts_text[:16]
+    _ = model.fast_generate(warmup_text, sampling_params = sp, lora_request = lora_request)
+    torch.cuda.synchronize()
+
+    n_prompt_tokens = sum(len(p) for p in prompt_ids)
+    wall_times = []
+    total_decoded = None
+    last_outputs = None
+    for _ in range(args.n_rounds):
+        torch.cuda.synchronize()
+        t0 = time.perf_counter()
+        outputs = model.fast_generate(
+            prompts_text, sampling_params = sp, lora_request = lora_request
+        )
+        torch.cuda.synchronize()
+        wall_times.append(time.perf_counter() - t0)
+        total_decoded = sum(len(o.outputs[0].token_ids) for o in outputs)
+        last_outputs = outputs
+
+    med = sorted(wall_times)[len(wall_times) // 2]
+    sample_texts = (
+        [o.outputs[0].text[:200] for o in (last_outputs[:3] or [])]
+        if last_outputs
+        else []
+    )
+    return {
+        "backend": "vllm",
+        "lora_adapter": args.lora_adapter,
+        "n_prompts": args.n_prompts,
+        "n_prompt_tokens": n_prompt_tokens,
+        "n_decoded_tokens": total_decoded,
+        "wall_times_s": wall_times,
+        "median_wall_s": med,
+        "prompt_tps": n_prompt_tokens / med,
+        "decode_tps": (total_decoded or 0) / med,
+        "max_new_tokens": args.max_new_tokens,
+        "sample_completions": sample_texts,
+    }
+
+
+def run_tpaged(args):
+    """Vanilla HF + paged cache.
+
+    Unsloth's Qwen3Attention monkey-patch does not compose with the
+    `paged|<impl>` functional attention interface, so we use plain HF.
+    """
+    from transformers import AutoModelForCausalLM, AutoTokenizer, GenerationConfig
+
+    tokenizer = AutoTokenizer.from_pretrained(args.model_name)
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+    if args.load_in_4bit:
+        bnb_model_name = args.model_name_4bit or f"{args.model_name}-unsloth-bnb-4bit"
+        print(f"[tpaged] loading 4-bit base: {bnb_model_name}")
+        model = AutoModelForCausalLM.from_pretrained(
+            bnb_model_name,
+            attn_implementation = args.attn_impl,
+            device_map = "cuda:0",
+        )
+        # HF transformers logs "lm_head.weight newly initialized" for
+        # bnb-4bit shards of tied-embedding models. tie_word_embeddings is
+        # True in the config but the dequant path leaves lm_head unbound.
+        # Tie manually so we don't generate gibberish.
+        if getattr(model.config, "tie_word_embeddings", False):
+            model.lm_head.weight = model.model.embed_tokens.weight
+    else:
+        model = AutoModelForCausalLM.from_pretrained(
+            args.model_name,
+            dtype = torch.bfloat16,
+            attn_implementation = args.attn_impl,
+        ).to("cuda")
+    model.eval()
+
+    if args.lora_adapter:
+        from peft import PeftModel
+
+        # NOTE: no merge_adapter -- we measure LoRA-active inference.
+        model = PeftModel.from_pretrained(
+            model, str(Path(args.lora_adapter).resolve()), is_trainable = False
+        )
+        model.eval()
+
+    if args.persistent_cb:
+        from persistent_cb import install_for_model  # noqa: WPS433
+    prompts_text, prompt_ids = build_prompts(
+        tokenizer,
+        args.n_prompts,
+        chat_template = args.chat_template,
+        model_type_name = type(model).__name__,
+    )
+
+    gen_config = GenerationConfig(
+        max_new_tokens = args.max_new_tokens,
+        do_sample = True,
+        temperature = args.temperature,
+        top_p = args.top_p,
+        min_p = args.min_p,
+        top_k = args.top_k,
+        pad_token_id = tokenizer.pad_token_id or tokenizer.eos_token_id,
+        bos_token_id = tokenizer.bos_token_id,
+        eos_token_id = tokenizer.eos_token_id,
+        use_cache = True,
+    )
+    gen_config.max_batch_tokens = args.max_batch_tokens
+    gen_config.num_blocks = args.num_blocks
+
+    if args.persistent_cb:
+        install_for_model(model, gen_config)
+
+    warmup_ids = prompt_ids[:16]
+    with torch.inference_mode():
+        _ = model.generate_batch(
+            warmup_ids, generation_config = gen_config, progress_bar = False
+        )
+    torch.cuda.synchronize()
+
+    n_prompt_tokens = sum(len(p) for p in prompt_ids)
+    wall_times = []
+    total_decoded = None
+    last_outputs = None
+    for _ in range(args.n_rounds):
+        torch.cuda.synchronize()
+        t0 = time.perf_counter()
+        with torch.inference_mode():
+            outputs = model.generate_batch(
+                prompt_ids, generation_config = gen_config, progress_bar = False
+            )
+        torch.cuda.synchronize()
+        wall_times.append(time.perf_counter() - t0)
+        total_decoded = sum(len(v.generated_tokens) for v in outputs.values())
+        last_outputs = outputs
+
+    # Sample completions for coherence sanity check.
+    sample_texts = []
+    if last_outputs is not None:
+        for k in list(last_outputs.keys())[:3]:
+            toks = last_outputs[k].generated_tokens
+            sample_texts.append(tokenizer.decode(toks, skip_special_tokens = False)[:200])
+
+    med = sorted(wall_times)[len(wall_times) // 2]
+    return {
+        "backend": "tpaged",
+        "lora_adapter": args.lora_adapter,
+        "attn_impl": args.attn_impl,
+        "persistent_cb": args.persistent_cb,
+        "n_prompts": args.n_prompts,
+        "n_prompt_tokens": n_prompt_tokens,
+        "n_decoded_tokens": total_decoded,
+        "wall_times_s": wall_times,
+        "median_wall_s": med,
+        "prompt_tps": n_prompt_tokens / med,
+        "decode_tps": (total_decoded or 0) / med,
+        "max_new_tokens": args.max_new_tokens,
+        "sample_completions": sample_texts,
+    }
+
+
+def run_unsloth_fi_false(args):
+    """Unsloth `fast_inference=False` path with custom HF inference kernels.
+
+    This is the path that backs regular Unsloth training's sampling loop
+    (Triton RMSNorm/RoPE, cached fp16 LoRA copies in `fast_linear_forward`).
+    Previously only exercised through full GRPO runs -- isolating it lets us
+    compare it head-to-head against vLLM on the same workload.
+
+    LoRA is attached via `FastLanguageModel.get_peft_model`; if a PEFT adapter
+    path is provided we re-load its weights into the Unsloth-wrapped model so
+    every backend uses the *same* weights.
+    """
+    os.environ.setdefault("UNSLOTH_VLLM_STANDBY", "1")
+    from unsloth import FastLanguageModel
+
+    model, tokenizer = FastLanguageModel.from_pretrained(
+        model_name = args.model_name,
+        max_seq_length = args.max_seq_length,
+        load_in_4bit = False,
+        fast_inference = False,
+        max_lora_rank = 32,
+    )
+    # Attach LoRA rank 32 the same way the GRPO notebook does.
+    model = FastLanguageModel.get_peft_model(
+        model,
+        r = 32,
+        target_modules = [
+            "q_proj",
+            "k_proj",
+            "v_proj",
+            "o_proj",
+            "gate_proj",
+            "up_proj",
+            "down_proj",
+        ],
+        lora_alpha = 64,
+        use_gradient_checkpointing = "unsloth",
+        random_state = 3407,
+    )
+
+    # Optional: overlay a shared adapter so weights match other backends.
+    if args.lora_adapter:
+        from safetensors import safe_open
+
+        adapter_file = Path(args.lora_adapter).resolve() / "adapter_model.safetensors"
+        loaded_tensors = {}
+        with safe_open(str(adapter_file), framework = "pt") as f:
+            for key in f.keys():
+                loaded_tensors[key] = f.get_tensor(key)
+
+        # Both PEFT and Unsloth's `get_peft_model` produce parameter names with
+        # `base_model.model.` prefix plus `.lora_{A,B}.default.weight`. Build a
+        # normalized (core-path) -> param map, then match by core path only.
+        def _core(name: str) -> str:
+            n = name
+            for pref in ("base_model.model.", "model."):
+                if n.startswith(pref):
+                    n = n[len(pref) :]
+            n = n.replace(".lora_A.default.", ".lora_A.").replace(
+                ".lora_B.default.", ".lora_B."
+            )
+            return n
+
+        own_by_core = {}
+        for n, p in model.named_parameters():
+            if "lora_" in n:
+                own_by_core.setdefault(_core(n), []).append(p)
+        matched = 0
+        with torch.no_grad():
+            for name, tensor in loaded_tensors.items():
+                core = _core(name)
+                for own in own_by_core.get(core, []):
+                    if own.shape == tensor.shape:
+                        own.data.copy_(tensor.to(own.device, own.dtype))
+                        matched += 1
+                        break
+        print(
+            f"[unsloth_fi_false] LoRA weight sync matched {matched} tensors "
+            f"(out of {len(loaded_tensors)} adapter entries)."
+        )
+
+    FastLanguageModel.for_inference(model)
+
+    prompts_text, prompt_ids = build_prompts(
+        tokenizer,
+        args.n_prompts,
+        chat_template = args.chat_template,
+        model_type_name = type(model).__name__,
+    )
+
+    # `model.generate` accepts batched input_ids; pad to max length.
+    from transformers import GenerationConfig
+
+    if tokenizer.padding_side != "left":
+        tokenizer.padding_side = "left"  # decoder needs left padding
+    if tokenizer.pad_token_id is None:
+        tokenizer.pad_token = tokenizer.eos_token
+
+    gen_config = GenerationConfig(
+        max_new_tokens = args.max_new_tokens,
+        do_sample = True,
+        temperature = args.temperature,
+        top_p = args.top_p,
+        min_p = args.min_p,
+        top_k = args.top_k,
+        pad_token_id = tokenizer.pad_token_id,
+        bos_token_id = tokenizer.bos_token_id,
+        eos_token_id = tokenizer.eos_token_id,
+        use_cache = True,
+    )
+
+    def _batched_generate(texts):
+        batch = tokenizer(texts, return_tensors = "pt", padding = True).to("cuda")
+        with torch.inference_mode():
+            out = model.generate(**batch, generation_config = gen_config)
+        prompt_len = batch["input_ids"].shape[1]
+        return out, prompt_len
+
+    # Warmup on 16 prompts.
+    _ = _batched_generate(prompts_text[:16])
+    torch.cuda.synchronize()
+
+    n_prompt_tokens = sum(len(p) for p in prompt_ids)
+    wall_times = []
+    total_decoded = None
+    last_out_ids = None
+    last_prompt_len = None
+    for _ in range(args.n_rounds):
+        torch.cuda.synchronize()
+        t0 = time.perf_counter()
+        out_ids, prompt_len = _batched_generate(prompts_text)
+        torch.cuda.synchronize()
+        wall_times.append(time.perf_counter() - t0)
+        # Count generated tokens past prompt_len per sequence (subtract any
+        # trailing pad-only tail by comparing against EOS).
+        total_decoded = int(
+            (out_ids[:, prompt_len:] != tokenizer.pad_token_id).sum().item()
+        )
+        last_out_ids = out_ids
+        last_prompt_len = prompt_len
+
+    med = sorted(wall_times)[len(wall_times) // 2]
+    sample_texts = []
+    if last_out_ids is not None:
+        for i in range(min(3, last_out_ids.shape[0])):
+            sample_texts.append(
+                tokenizer.decode(
+                    last_out_ids[i, last_prompt_len:], skip_special_tokens = False
+                )[:200]
+            )
+
+    return {
+        "backend": "unsloth_fi_false",
+        "lora_adapter": args.lora_adapter,
+        "n_prompts": args.n_prompts,
+        "n_prompt_tokens": n_prompt_tokens,
+        "n_decoded_tokens": total_decoded,
+        "wall_times_s": wall_times,
+        "median_wall_s": med,
+        "prompt_tps": n_prompt_tokens / med,
+        "decode_tps": (total_decoded or 0) / med,
+        "max_new_tokens": args.max_new_tokens,
+        "sample_completions": sample_texts,
+    }
+
+
+def parse_args():
+    p = argparse.ArgumentParser()
+    p.add_argument(
+        "--backend", choices = ["vllm", "tpaged", "unsloth_fi_false"], required = True
+    )
+    p.add_argument("--model_name", default = "unsloth/Qwen3-4B-Base")
+    p.add_argument("--max_seq_length", type = int, default = 2048)
+    p.add_argument("--n_prompts", type = int, default = 32)
+    p.add_argument("--n_rounds", type = int, default = 2)
+    p.add_argument("--max_new_tokens", type = int, default = 512)
+    p.add_argument("--gpu_memory_utilization", type = float, default = 0.8)
+    p.add_argument("--attn_impl", default = "sdpa")
+    p.add_argument("--max_batch_tokens", type = int, default = 8192)
+    p.add_argument("--num_blocks", type = int, default = 16384)
+    p.add_argument("--persistent_cb", action = "store_true")
+    p.add_argument(
+        "--lora_adapter",
+        default = None,
+        help = "Path to a PEFT adapter (rank 32) applied in every backend.",
+    )
+    p.add_argument(
+        "--load_in_4bit",
+        action = "store_true",
+        help = "Load base as bitsandbytes 4-bit (Unsloth shard).",
+    )
+    p.add_argument(
+        "--model_name_4bit",
+        default = None,
+        help = "Override 4-bit shard name. Default `{model_name}-unsloth-bnb-4bit`.",
+    )
+    p.add_argument("--temperature", type = float, default = 0.1)
+    p.add_argument("--top_p", type = float, default = 0.97)
+    p.add_argument("--min_p", type = float, default = 0.5)
+    p.add_argument("--top_k", type = int, default = 5)
+    p.add_argument("--stats_path", required = True)
+    p.add_argument(
+        "--chat_template",
+        choices = ["auto", "grpo", "native"],
+        default = "auto",
+        help = (
+            "`auto`: GRPO for Qwen3, tokenizer native otherwise. "
+            "`grpo`: force GRPO template. `native`: force tokenizer's "
+            "built-in Instruct template (Llama-3.2-Instruct)."
+        ),
+    )
+    p.add_argument(
+        "--enforce_eager",
+        action = "store_true",
+        help = (
+            "vLLM only: skip the torch.compile + cudagraph path and run "
+            "eager. Useful when vLLM's compile regresses on the local "
+            "torch build."
+        ),
+    )
+    return p.parse_args()
+
+
+def main():
+    args = parse_args()
+    os.makedirs(os.path.dirname(os.path.abspath(args.stats_path)) or ".", exist_ok = True)
+
+    torch.cuda.reset_peak_memory_stats()
+    if args.backend == "vllm":
+        out = run_vllm(args)
+    elif args.backend == "unsloth_fi_false":
+        out = run_unsloth_fi_false(args)
+    else:
+        out = run_tpaged(args)
+
+    out["peak_memory_gb"] = torch.cuda.max_memory_allocated() / 1024**3
+    out["sampling"] = {
+        "temperature": args.temperature,
+        "top_p": args.top_p,
+        "min_p": args.min_p,
+        "top_k": args.top_k,
+    }
+    with open(args.stats_path, "w") as f:
+        json.dump(out, f, indent = 2)
+    print(json.dumps(out, indent = 2))
+    os._exit(0)
+
+
+if __name__ == "__main__":
+    main()

scripts/benchmarks/compare_grpo_runs.py

@@ -0,0 +1,80 @@
+"""Pairwise equivalence diff for GRPO backend runs.
+
+Runs `torch_debugging_utils.compare_training_runs` over the StatisticsCallback
+JSONs produced by `qwen3_grpo_unified.py`, plus reward / KL diffs which the
+base util doesn't track (it's loss/grad-focused).
+
+Usage:
+    python scripts/benchmarks/compare_grpo_runs.py \
+        --ref logs/grpo_vllm_30.json \
+        --candidate logs/grpo_unsloth_fi_false_30.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+WORKSPACE_ROOT = Path("/mnt/disks/unslothai/ubuntu/workspace_31")
+for p in (HERE, WORKSPACE_ROOT):
+    sys.path.insert(0, str(p))
+
+
+def _arrays(path: str):
+    with open(path) as f:
+        logs = json.load(f)
+    return {
+        "loss": [l.get("loss") for l in logs if "loss" in l],
+        "reward": [l.get("reward") for l in logs if "reward" in l],
+        "kl": [l.get("kl") for l in logs if "kl" in l],
+        "grad_norm": [l.get("grad_norm") for l in logs if "grad_norm" in l],
+        "time_ms": [l.get("time_ms") for l in logs if "time_ms" in l],
+    }
+
+
+def _diff(a, b):
+    if not a or not b:
+        return None
+    n = min(len(a), len(b))
+    diffs = [
+        abs(a[i] - b[i]) for i in range(n) if a[i] is not None and b[i] is not None
+    ]
+    if not diffs:
+        return None
+    return {
+        "n_compared": len(diffs),
+        "max_abs": max(diffs),
+        "mean_abs": sum(diffs) / len(diffs),
+    }
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--ref", required = True)
+    p.add_argument("--candidate", required = True)
+    args = p.parse_args()
+
+    from torch_debugging_utils import compare_training_runs
+
+    base = compare_training_runs(args.ref, args.candidate, loss_tol = 1e-3, grad_tol = 1e-3)
+
+    ref_a = _arrays(args.ref)
+    cand_a = _arrays(args.candidate)
+    extras = {k: _diff(ref_a[k], cand_a[k]) for k in ("reward", "kl", "time_ms")}
+
+    out = {
+        "ref": args.ref,
+        "candidate": args.candidate,
+        "compare_training_runs": base,
+        "reward_diff": extras["reward"],
+        "kl_diff": extras["kl"],
+        "time_diff_ms": extras["time_ms"],
+    }
+    print(json.dumps(out, indent = 2))
+
+
+if __name__ == "__main__":
+    main()

scripts/benchmarks/flash_attn_fa4_shim.py

@@ -0,0 +1,96 @@
+"""Make transformers' continuous batching dispatch to Flash Attention 4 on B200.
+
+Two integration gaps between transformers' continuous batching (CB) and the
+FA2 varlen path make `attn_implementation="flash_attention_2"` fail out of the
+box in transformers 4.57 even with a working FA varlen kernel:
+
+1. CB's `ContinuousBatchProcessor` creates a 4D paged attention mask of shape
+   `[1, 1, q_len, k_len]` for every attention implementation except
+   `"paged_attention"`. `_flash_attention_forward` then enters the
+   `if attention_mask is not None:` branch and calls `_upad_input`, which
+   expects a 2D mask and fails (the FA4 kernel ultimately asserts on
+   `cu_seqlens_k.shape`).
+
+2. CB passes `max_seqlen_q`/`max_seqlen_k` as model kwargs while
+   `_flash_attention_forward` names the parameters `max_length_q`/
+   `max_length_k`. The former therefore never bind and the varlen branch
+   inside `_flash_attention_forward` invokes the FA kernel with
+   `max_seqlen_q=None`.
+
+This module patches around both, and (via the sibling
+`site-packages/flash_attn/__init__.py` shim) points the FA2 varlen dispatch
+at FA4's Blackwell-capable kernel. Call `apply()` once, before
+`model.generate_batch` is invoked.
+"""
+
+from __future__ import annotations
+
+import functools
+
+
+_APPLIED = False
+
+
+def apply() -> None:
+    global _APPLIED
+    if _APPLIED:
+        return
+
+    import transformers  # noqa: F401  - force load
+    from transformers.generation.continuous_batching import continuous_api as _cb
+    from transformers import modeling_flash_attention_utils as _fa_utils
+
+    _patch_return_attention_mask(_cb)
+    _patch_flash_attention_forward(_fa_utils)
+
+    _APPLIED = True
+
+
+def _patch_return_attention_mask(cb_module) -> None:
+    """Don't materialise a 4D attention mask when the kernel is FA varlen.
+
+    The existing `return_attention_mask` only skips the mask for
+    `"paged_attention"`. We extend the skip set to `"flash_attention_2"`
+    (and `"flash_attention_3"` for future-proofing) because the varlen path
+    relies on `cu_seq_lens_*` and reads no mask.
+    """
+    _SKIP_MASK_IMPLS = {
+        "paged_attention",
+        "flash_attention_2",
+        "flash_attention_3",
+    }
+
+    def return_attention_mask(self) -> bool:
+        return self.config._attn_implementation not in _SKIP_MASK_IMPLS
+
+    cb_module.ContinuousBatchProcessor.return_attention_mask = return_attention_mask
+
+
+def _patch_flash_attention_forward(fa_utils_module) -> None:
+    """Accept CB's `max_seqlen_q`/`max_seqlen_k` kwargs as aliases.
+
+    transformers names the parameters `max_length_q`/`max_length_k`, but CB
+    (and most downstream call sites) name them `max_seqlen_q`/
+    `max_seqlen_k`. We rename at the boundary so callers on either side work
+    unchanged.
+    """
+    original = fa_utils_module._flash_attention_forward
+
+    @functools.wraps(original)
+    def wrapper(*args, **kwargs):
+        if kwargs.get("max_length_q") is None and "max_seqlen_q" in kwargs:
+            kwargs["max_length_q"] = kwargs.pop("max_seqlen_q")
+        if kwargs.get("max_length_k") is None and "max_seqlen_k" in kwargs:
+            kwargs["max_length_k"] = kwargs.pop("max_seqlen_k")
+        return original(*args, **kwargs)
+
+    fa_utils_module._flash_attention_forward = wrapper
+
+    # Some integration modules imported the function by name before we
+    # patched. Re-bind the most common consumers so they pick up the wrapper.
+    try:
+        from transformers.integrations import flash_attention as _flash_integration
+
+        _flash_integration._flash_attention_forward = wrapper
+    except Exception:
+        pass

scripts/benchmarks/flex_autotune_replay.py

@@ -0,0 +1,221 @@
+"""Autotune replay for flex_attention decode.
+
+Pattern from attention-gym/examples/flex_autotune_replay.py:
+
+1. Run once with `mode="max-autotune-no-cudagraphs"` and
+   `TORCHINDUCTOR_FLEX_ATTENTION_LOGGING_FILE` set. Inductor writes a JSON
+   log of every kernel config it tried, sorted by wall time per shape.
+2. Parse the log for the decode-shape entry (Q_LEN small, large KV).
+3. Emit the best fwd_* options as a JSON string that the main flex script
+   can accept via --decode_kernel_options.
+
+Usage:
+    CUDA_VISIBLE_DEVICES=7 python scripts/benchmarks/flex_autotune_replay.py \
+        --log_file logs/flex_autotune.json \
+        --max_batch_size 64 \
+        --n_prompts 16 \
+        --max_new_tokens 64
+
+Writes best decode kernel options to --output_opts (JSON), prints to stdout.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+HERE = Path(__file__).resolve().parent
+
+
+def run_autotune_pass(log_file: str, args) -> None:
+    env = os.environ.copy()
+    env["FLEX_COMPILE_MODE"] = "max-autotune-no-cudagraphs"
+    # Inductor appends `.json` to this env var value.
+    env["TORCHINDUCTOR_FLEX_ATTENTION_LOGGING_FILE"] = log_file.replace(".json", "")
+
+    cmd = [
+        sys.executable,
+        "-u",
+        str(HERE / "qwen3_flex_inference.py"),
+        "--n_prompts",
+        str(args.n_prompts),
+        "--n_rounds",
+        "1",
+        "--max_new_tokens",
+        str(args.max_new_tokens),
+        "--max_batch_size",
+        str(args.max_batch_size),
+        # NB: autotune in `max-autotune-no-cudagraphs` mode is incompatible with
+        # our raw CUDA graph capture path, so we skip --capture_cudagraph here.
+        # Goal is only to produce the log, not to benchmark.
+        "--stats_path",
+        str(HERE / "logs" / "flex_autotune_stats.json"),
+    ]
+    if args.lora_adapter:
+        cmd += ["--lora_adapter", args.lora_adapter]
+    print("[autotune] running:", " ".join(cmd))
+    print(f"[autotune] logging to {log_file}")
+    subprocess.run(cmd, env = env, check = True)
+
+
+class _SymStub:
+    """Pretend-symbolic value so eval() can handle SymPy-ish free vars like `s40`."""
+
+    def __init__(self, name):
+        self.name = name
+
+    def __repr__(self):
+        return f"Sym({self.name})"
+
+
+class _SymNamespace(dict):
+    """Any unknown name becomes a _SymStub instead of NameError."""
+
+    def __getitem__(self, key):
+        if key in self:
+            return super().__getitem__(key)
+        # Don't catch obvious builtins.
+        if key in ("True", "False", "None"):
+            return eval(key)
+        return _SymStub(key)
+
+    def __contains__(self, key):
+        return True  # satisfies eval's name resolution
+
+
+def parse_log(log_file: str) -> list[tuple[tuple, dict]]:
+    """Return list of (shape_tuple, best_fwd_options_dict) per shape entry."""
+    if not Path(log_file).exists():
+        raise FileNotFoundError(
+            f"Inductor log file missing: {log_file}. "
+            f"Did `TORCHINDUCTOR_FLEX_ATTENTION_LOGGING_FILE` fire?"
+        )
+    with open(log_file) as f:
+        data = json.load(f)
+
+    ns = _SymNamespace()
+    shapes = []
+    for entry in data:
+        key, choices = next(iter(entry.items()))
+        try:
+            parsed = eval(key, {"__builtins__": {}}, ns)
+        except Exception:
+            parsed = (key,)
+        kernel_type = None
+        if isinstance(parsed, (list, tuple)) and len(parsed) > 0:
+            first = parsed[0]
+            if isinstance(first, str):
+                kernel_type = first
+        best = choices[0]
+        opts = {k: v for k, v in best.items() if k not in ("type", "time")}
+        shapes.append((parsed, opts, best.get("time"), kernel_type, key))
+    return shapes
+
+
+def pick_decode_shape(shapes):
+    """Pick the decode-shape entry.
+
+    Decode has Q_LEN=1. Prefill has Q_LEN large. The shape tuple is
+    `('forward', B, H_q, H_kv, Q_LEN, KV_LEN, D_q, D_v)` — so Q_LEN is at
+    index 4. When B/KV_LEN are symbolic (`s0`, `s40`), the raw key string
+    is the form `('forward', s40, 32, 8, 1, s0, 128, 128)`.
+    """
+    import re
+
+    def q_len_of(shape_key, parsed):
+        # If we successfully parsed and there's a real int at index 4, use it.
+        if (
+            isinstance(parsed, (list, tuple))
+            and len(parsed) > 4
+            and isinstance(parsed[4], int)
+        ):
+            return parsed[4]
+        # Else extract from the raw string form, which is always
+        # `('forward', <B>, 32, 8, <Q_LEN>, <KV_LEN>, 128, 128)`.
+        m = re.match(r"\('forward',\s*[^,]+,\s*[^,]+,\s*[^,]+,\s*(\d+)", shape_key)
+        if m:
+            return int(m.group(1))
+        return 10**9
+
+    # (parsed, opts, time, kernel_type) -> plus we need the raw key string.
+    # Pass shape_key via _SymNamespace too — actually we'll redo parse_log to
+    # include the raw key. Simpler: re-read the file.
+    return min(shapes, key = lambda s: q_len_of(s[4] if len(s) > 4 else "", s[0]))
+
+
+def format_best_opts(best_opts: dict) -> dict:
+    """Filter Inductor log keys to those acceptable to FlexKernelOptions as
+    fwd_* prefix."""
+    from torch.nn.attention.flex_attention import FlexKernelOptions
+
+    annotations = FlexKernelOptions.__annotations__
+    out = {}
+    for k, v in best_opts.items():
+        if k in annotations:
+            out[f"fwd_{k}"] = v
+    return out
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument(
+        "--log_file",
+        default = "logs/flex_autotune.json",
+        help = "Inductor writes the autotune log here. Will have .json appended.",
+    )
+    p.add_argument(
+        "--output_opts",
+        default = "logs/flex_best_decode_opts.json",
+        help = "Extracted best kernel options go here.",
+    )
+    p.add_argument("--n_prompts", type = int, default = 16)
+    p.add_argument("--max_batch_size", type = int, default = 64)
+    p.add_argument("--max_new_tokens", type = int, default = 64)
+    p.add_argument("--lora_adapter", default = None)
+    p.add_argument(
+        "--skip_autotune",
+        action = "store_true",
+        help = "Skip autotune pass and just parse existing log.",
+    )
+    args = p.parse_args()
+
+    log_file = args.log_file
+    if not log_file.endswith(".json"):
+        log_file = log_file + ".json"
+
+    if not args.skip_autotune:
+        run_autotune_pass(log_file, args)
+
+    shapes = parse_log(log_file)
+    print(f"[autotune] parsed {len(shapes)} shapes from log:")
+    for shape, opts, t, kt, key in shapes:
+        print(f"  kernel_type={kt!r}  shape={shape}  time={t!r}  opts={opts}")
+        print(f"    raw key: {key}")
+
+    if not shapes:
+        raise SystemExit("no shapes found in autotune log")
+
+    decode_shape, decode_opts, decode_time, _, _ = pick_decode_shape(shapes)
+    print("\n[autotune] selected decode-ish shape:", decode_shape)
+    print("[autotune] best decode options:", decode_opts, f"(time={decode_time!r})")
+
+    best = format_best_opts(decode_opts)
+    # Always add tuned knobs we already confirmed helpful.
+    best.setdefault("PRESCALE_QK", True)
+    best.setdefault("USE_TMA", True)
+    best.setdefault("BLOCKS_ARE_CONTIGUOUS", True)
+    print("\n[autotune] final decode kernel_options:", json.dumps(best, indent = 2))
+
+    Path(args.output_opts).parent.mkdir(parents = True, exist_ok = True)
+    with open(args.output_opts, "w") as f:
+        json.dump(best, f, indent = 2)
+    print(f"[autotune] wrote {args.output_opts}")
+
+
+if __name__ == "__main__":
+    main()

scripts/benchmarks/flex_paged_attention.py

@@ -0,0 +1,502 @@
+# Adapted from attention-gym
+# Original source: https://github.com/pytorch-labs/attention-gym
+# License: BSD 3-Clause (see THIRD_PARTY_LICENSES.md)
+# Copyright (c) 2023, Driss Guessous
+
+# the original implementation has some bugs and has some feature that lives outside of the PageTable class
+
+from typing import Optional
+import torch
+from torch import Tensor
+from torch.nn.attention.flex_attention import (
+    _identity,
+    _mask_mod_signature,
+    _score_mod_signature,
+    BlockMask,
+    noop_mask,
+    create_block_mask,
+)
+
+create_block_mask = torch.compile(create_block_mask, dynamic = True)
+
+
+def _cdiv(x: int | float | torch.Tensor, multiple: int | float | torch.Tensor):
+    return (x + multiple - 1) // multiple
+
+
+class PagedKVCache(torch.nn.Module):
+    def __init__(self, page_table, n_heads, head_dim, dtype):
+        super().__init__()
+        cache_shape = (1, n_heads, page_table.n_pages * page_table.page_size, head_dim)
+        self.register_buffer("k_cache", torch.zeros(cache_shape, dtype = dtype))
+        self.register_buffer("v_cache", torch.zeros(cache_shape, dtype = dtype))
+
+        self.page_table = page_table
+
+    def update(self, input_pos, k_val, v_val, batch_idx = None):
+        assert (
+            batch_idx is not None
+        ), "batch_idx is required for paged kv cache, are you using non-paged attention?"
+
+        if batch_idx.ndim == 1:
+            # batch_idx should be [B] (decode)
+            return self.page_table.assign(
+                batch_idx, input_pos, k_val, v_val, self.k_cache, self.v_cache
+            )
+        else:
+            assert batch_idx.ndim == 2, "batch_idx must be 1D or 2D"
+            # batch_idx should be [1, L] (batch prefill)
+            return self.page_table.assign_prefill_no_paging(
+                batch_idx, input_pos, k_val, v_val, self.k_cache, self.v_cache
+            )
+
+
+class PageTable:
+    """
+    PageTable is a modified version of PagedAttention from attention-gym.
+
+    PageTable improves it by:
+    - maintaining a cpu copy of the page table, to avoid device-to-host transfers
+    - support batch prefill
+    - fix the bug in the original code in mask_mod and score_mod by mapping physical batch index to logical batch index
+    - subsuming the free_batch_idx into the page table, so we don't need to maintain it separately
+    """
+
+    def __init__(
+        self,
+        n_pages: int,
+        page_size: int,
+        max_batch_size: int,
+        device: str = "cuda",
+    ):
+        self.n_pages = n_pages
+        self.page_size = page_size
+        self.max_batch_size = max_batch_size
+        self.device = device
+
+        # page table: [logical_batch_idx, logical_block_idx] -> physical_page_idx
+        self.page_table = -torch.ones(
+            (max_batch_size, self.n_pages), dtype = torch.int64, device = device
+        )
+        self.page_table[0, :] = (
+            0  # page 0 is reserved for simpler code in assign_prefill_no_paging
+        )
+        self.page_table_cpu = [[] for _ in range(max_batch_size)]
+
+        self.capacity = [
+            0 for _ in range(max_batch_size)
+        ]  # capacity: batch_idx -> number of pages allocated * page size
+        self.free_pages = list(
+            reversed(range(1, n_pages))
+        )  # page 0 is reserved for simpler code in assign_prefill_no_paging
+        self.free_batch_idx = list(
+            reversed(range(1, max_batch_size))
+        )  # batch_idx 0 is reserved for no-op
+
+        # [logical_batch_idx, physical_page_idx] -> logical_page_idx
+        self.physical_to_logical = -torch.ones(
+            (max_batch_size, n_pages), dtype = torch.int64, device = device
+        )
+
+    def can_reserve(self, size: int, batch_idx_int: int | None = None) -> bool:
+        """check if we can reserve new pages for an existing request or a new request, without gpu operations"""
+        if batch_idx_int is None:
+            # check if we can schedule a new request
+            return (
+                self.pages_available * self.page_size >= size
+                and len(self.free_batch_idx) > 0
+            )
+        else:
+            # check if we can reserve new pages for an existing request
+            return self.reserve(batch_idx_int, None, size, dry_run = True)
+
+    def allocate(self) -> int:
+        """allocate a new batch"""
+        batch_idx = self.free_batch_idx.pop()
+
+        self.capacity[batch_idx] = 0
+        self.physical_to_logical[batch_idx, :] = -1
+        self.page_table[batch_idx, :] = -1
+        return batch_idx
+
+    @property
+    def pages_available(self) -> int:
+        return len(self.free_pages)
+
+    def reserve(
+        self,
+        batch_idx_int: int,
+        batch_idx: torch.Tensor,
+        seq_len: int,
+        dry_run: bool = False,
+    ) -> bool:
+        """
+        Requests the capacity of a given batch to be at least enough to
+        hold `seq_len` elements.
+
+        Args:
+            batch_idx_int (int): batch index to be reserved;
+            batch_idx (Tensor): batch index to be reserved; shape :math:`(1)`.
+            seq_len (Tensor): minimum capacity for the given batch; shape :math:`(1)`.
+
+        Returns:
+            bool: True if the reservation was successful, False if the reservation was not successful (no space, and in this case, no update is done)
+        """
+
+        if seq_len <= self.capacity[batch_idx_int]:
+            return True
+
+        num_pages_to_allocate = _cdiv(
+            seq_len - self.capacity[batch_idx_int], self.page_size
+        )
+
+        can_allocate = num_pages_to_allocate <= self.pages_available
+        if dry_run:
+            return can_allocate
+
+        if not can_allocate:
+            raise RuntimeError(
+                f"Cannot reserve {num_pages_to_allocate} pages for a sequence of length {seq_len} "
+                f"in batch {batch_idx_int}. Only {self.pages_available} pages available. "
+                f"Current capacity is {self.capacity[batch_idx_int]} tokens."
+            )
+
+        start_page_idx = self.capacity[batch_idx_int] // self.page_size
+        end_page_idx = start_page_idx + num_pages_to_allocate
+
+        # find empty physical pages
+        allocated_pages_list = self.free_pages[-num_pages_to_allocate:]
+        allocated_pages = torch.tensor(allocated_pages_list, device = self.device)
+        # update page table
+        self.page_table[batch_idx, start_page_idx:end_page_idx] = allocated_pages
+
+        # update metadata
+        self.physical_to_logical[batch_idx, allocated_pages] = torch.arange(
+            start_page_idx,
+            end_page_idx,
+            device = self.device,
+        )
+        # update cpu side metadata
+        self.page_table_cpu[batch_idx_int] += allocated_pages_list
+        self.free_pages = self.free_pages[:-num_pages_to_allocate]
+        self.capacity[batch_idx_int] += num_pages_to_allocate * self.page_size
+        return True
+
+    def erase(self, batch_idx: int) -> None:
+        """
+        Removes a single batch from paged attention.
+
+        Args:
+            batch_idx (int): batch index to be removed;
+        """
+        # NOTE: the GPU side data will only be reset/overwritten when we allocate it for a new batch
+        self.free_batch_idx.append(batch_idx)
+        allocated_pages_cpu = self.page_table_cpu[batch_idx]
+        self.free_pages.extend(reversed(allocated_pages_cpu))
+        self.page_table_cpu[batch_idx] = []
+
+    def assign(
+        self,
+        batch_idx: torch.Tensor,
+        input_pos: torch.Tensor,
+        k_val: torch.Tensor,
+        v_val: torch.Tensor,
+        k_cache: torch.Tensor,
+        v_cache: torch.Tensor,
+    ) -> None:
+        """
+        Assigns new contents `val` to the storage `cache` at the location
+        `batch_idx` and `input_pos`.
+
+        Args:
+            batch_idx (Tensor): batch index; shape :math:`(B)`.
+            input_pos (Tensor): input positions to be assigned for the given batch; shape :math:`(B, S)`.
+            val (Tensor): value to be assigned; shape :math:`(B, H, S, D)`
+            cache (Tensor): the cache to store the values; shape:`(1, H, MAX_S, D)`
+        """
+        if k_val.requires_grad:
+            raise RuntimeError("val must not require gradient")
+
+        B, H, S, K_D = k_val.shape
+        _, H_cache, MAX_S, D_cache = k_cache.shape
+        assert H_cache == H, "number of heads must match"
+        assert MAX_S >= S, "cache must have enough space"
+        assert D_cache == K_D, "hidden dim must match"
+        assert input_pos.shape == (B, S), "input_pos must have the same shape as val"
+        assert batch_idx.shape == (B,), "batch_idx must have one dimension only"
+
+        V_D = v_val.shape[3]
+        if B != batch_idx.shape[0]:
+            raise RuntimeError(
+                f"Expect val and batch_idx have the same batch size but got B={B} and B={batch_idx.shape[0]}."
+            )
+        if H != k_cache.shape[1]:
+            raise RuntimeError(
+                f"Expect val and cache has the same number of heads but got H={H} and H={k_cache.shape[1]}."
+            )
+        if S != input_pos.shape[1]:
+            raise RuntimeError(
+                f"Expect val and input_pos has the same length but got S={S} and S={input_pos.shape[0]}."
+            )
+        if K_D != k_cache.shape[3]:
+            raise RuntimeError(
+                f"Expect k_val and k_cache has the same hidden dim but got D={K_D} and D={k_cache.shape[3]}."
+            )
+        if V_D != v_cache.shape[3]:
+            raise RuntimeError(
+                f"Expect v_val and v_cache has the same hidden dim but got D={V_D} and D={v_cache.shape[3]}."
+            )
+
+        # find address
+        logical_block_idx = input_pos // self.page_size  # [B, S]
+        logical_block_offset = input_pos % self.page_size  # [B, S]
+
+        # NOTE: this code path is only used for decoding. For batch prefill, use assign_prefill_no_paging() instead
+        physical_block_idx = torch.gather(
+            self.page_table[batch_idx], 1, logical_block_idx.to(torch.int64)
+        ).to(torch.int32)  # [B, S]
+
+        addr = (physical_block_idx * self.page_size + logical_block_offset).view(
+            -1
+        )  # [B*S]
+
+        k_val = k_val.permute(1, 0, 2, 3).contiguous().view(1, H, B * S, K_D)
+        v_val = v_val.permute(1, 0, 2, 3).contiguous().view(1, H, B * S, V_D)
+
+        k_cache[:, :, addr, :] = k_val
+        v_cache[:, :, addr, :] = v_val
+
+        return k_cache, v_cache
+
+    def convert_logical_block_mask(
+        self,
+        block_mask: BlockMask,
+        batch_idx: Optional[torch.Tensor] = None,
+    ) -> BlockMask:
+        """
+        Converts a logical block mask by mapping its logical kv indices to the corresponding
+        physical kv indices.
+
+        Args:
+            block_mask (BlockMask): logical block mask;
+                kv_indices shape :math:`(B, H, ROWS, MAX_BLOCKS_IN_COL)`.
+            batch_idx (Tensor): batch index corresponding to the block_mask
+                batch dimension. This provides flexibility to convert a
+                block mask with smaller batch size than the page table;
+                shape :math:`(B)`.
+        """
+        B, H, ROWS, MAX_BLOCKS_IN_COL = block_mask.kv_indices.shape
+
+        if block_mask.BLOCK_SIZE[1] != self.page_size:
+            raise RuntimeError(
+                f"Expect block_mask has the same column block size as page_sizebut got size={block_mask.BLOCK_SIZE[1]} and size={self.page_size}"
+            )
+
+        device = block_mask.kv_num_blocks.device
+
+        if batch_idx is None:
+            batch_idx = torch.arange(B, device = device)
+
+        assert batch_idx.ndim == 1, "batch_idx must be a 1D tensor"
+        assert (
+            batch_idx.shape[0] == B
+        ), "batch_idx must have the same shape as block_mask"
+        assert (
+            B <= self.max_batch_size
+        ), "batch_idx must be less than or equal to max_batch_size"
+
+        page_table = self.page_table[batch_idx]
+
+        def transform(num_blocks, indices):
+            """
+            transform the block mask from [B, H, num_q_blocks, num_logical_kv_blocks]
+            to [B, H, num_q_blocks, num_physical_kv_blocks]
+
+            kv_num_blocks: [B, H, num_q_blocks] -> unchanged
+            kv_indices: [B, H, num_q_blocks, num_logical_kv_blocks] -> [B, H, num_q_blocks, num_physical_kv_blocks]
+            """
+            if num_blocks is None:
+                return None, None
+            new_kv_num_blocks = num_blocks.clone()
+            new_kv_indices = torch.zeros(
+                (B, H, ROWS, self.n_pages), dtype = torch.int32, device = device
+            )
+            new_kv_indices[:, :, :, :MAX_BLOCKS_IN_COL] = (
+                torch.gather(page_table, 1, indices.view(B, -1).to(torch.int64))
+                .view(block_mask.kv_indices.shape)
+                .to(torch.int32)
+            )
+            return new_kv_num_blocks, new_kv_indices
+
+        new_kv_num_blocks, new_kv_indices = transform(
+            block_mask.kv_num_blocks, block_mask.kv_indices
+        )
+        new_full_kv_num_blocks, new_full_kv_indices = transform(
+            block_mask.full_kv_num_blocks, block_mask.full_kv_indices
+        )
+
+        new_mask_mod = self.get_mask_mod(block_mask.mask_mod, batch_idx)
+
+        seq_lengths = (block_mask.seq_lengths[0], self.n_pages * self.page_size)
+        return BlockMask.from_kv_blocks(
+            new_kv_num_blocks,
+            new_kv_indices,
+            new_full_kv_num_blocks,
+            new_full_kv_indices,
+            block_mask.BLOCK_SIZE,
+            new_mask_mod,
+            seq_lengths = seq_lengths,
+        )
+
+    def get_logical_kv_idx(
+        self,
+        physical_batch_idx: torch.Tensor,
+        physical_kv_idx: torch.Tensor,
+        batch_idx: torch.Tensor,
+    ):
+        logical_batch_idx = batch_idx[physical_batch_idx]
+        physical_kv_block = physical_kv_idx // self.page_size
+        physical_kv_offset = physical_kv_idx % self.page_size
+        logical_block_idx = self.physical_to_logical[
+            logical_batch_idx, physical_kv_block
+        ]
+        logical_kv_idx = logical_block_idx * self.page_size + physical_kv_offset
+        is_valid = logical_block_idx >= 0
+        safe_logical_kv_idx = logical_kv_idx.clamp(min = 0)
+        return is_valid, safe_logical_kv_idx
+
+    def get_mask_mod(
+        self, mask_mod: Optional[_mask_mod_signature], batch_idx: torch.Tensor
+    ) -> _mask_mod_signature:
+        """
+        Converts a mask_mod based on mapping from the physical block index to the logical
+        block index.
+
+        Args:
+            mask_mod (_mask_mod_signature): mask_mod based on the logical block index.
+        """
+        if mask_mod is None:
+            mask_mod = noop_mask
+
+        def new_mask_mod(
+            b: torch.Tensor,
+            h: torch.Tensor,
+            q_idx: torch.Tensor,
+            physical_kv_idx: torch.Tensor,
+        ):
+            is_valid, safe_logical_kv_idx = self.get_logical_kv_idx(
+                b, physical_kv_idx, batch_idx
+            )
+            return torch.where(
+                is_valid, mask_mod(b, h, q_idx, safe_logical_kv_idx), False
+            )
+
+        return new_mask_mod
+
+    # NOTE: not used in the current codebase
+    def get_score_mod(
+        self, score_mod: Optional[_score_mod_signature], batch_idx: torch.Tensor
+    ) -> _score_mod_signature:
+        """
+        Converts a score_mod based on mapping from the physical block index to the logical
+        block index.
+
+        Args:
+            score_mod (_score_mod_signature): score_mod based on the logical block index.
+        """
+        if score_mod is None:
+            score_mod = _identity
+
+        def new_score_mod(
+            score: torch.Tensor,
+            b: torch.Tensor,
+            h: torch.Tensor,
+            q_idx: torch.Tensor,
+            physical_kv_idx: torch.Tensor,
+        ):
+            is_valid, safe_logical_kv_idx = self.get_logical_kv_idx(
+                b, physical_kv_idx, batch_idx
+            )
+            return torch.where(
+                is_valid,
+                score_mod(score, b, h, q_idx, safe_logical_kv_idx),
+                float("-inf"),
+            )
+
+        return new_score_mod
+
+    def create_causal_blockmask(self, B, L):
+        """A minimal, unoptimized causal block mask creation function"""
+
+        def causal(b, h, q_idx, kv_idx):
+            return q_idx >= kv_idx
+
+        return create_block_mask(
+            causal,
+            B = B,
+            H = None,
+            Q_LEN = L,
+            KV_LEN = L,
+            BLOCK_SIZE = self.page_size,
+            device = self.device,
+        )
+
+    def create_prefill_blockmask_no_paging(
+        self, batch_idx: Tensor, BLOCK_SIZE: int = 128
+    ):
+        """
+        there's no prefix sharing implemented, batch_idx is the document id, batch_idx is not guaranteed to be sorted
+        """
+        assert batch_idx.ndim == 2, "batch_idx must be a 2D tensor"
+        assert batch_idx.shape[0] == 1, "batch_idx must have batch size 1"
+        L = batch_idx.shape[1]
+        docs = batch_idx.view(-1)
+
+        def document_causal(b, h, q_idx, kv_idx):
+            causal_mask = q_idx >= kv_idx
+            document_mask = docs[q_idx] == docs[kv_idx]
+            return causal_mask & document_mask
+
+        return create_block_mask(
+            document_causal, B = 1, H = None, Q_LEN = L, KV_LEN = L, BLOCK_SIZE = BLOCK_SIZE
+        )
+
+    # we assign prefill to the cache, similar to assign(), except we don't return the k_cache, v_cache, we only return the k_val, v_val
+    def assign_prefill_no_paging(
+        self,
+        batch_idx: torch.Tensor,
+        input_pos: torch.Tensor,
+        k_val: torch.Tensor,
+        v_val: torch.Tensor,
+        k_cache: torch.Tensor,
+        v_cache: torch.Tensor,
+    ) -> None:
+        """
+        assigns kv and returns the original kv
+
+        batch_idx: [1, L]
+        input_pos: [1, L]
+        k_val: [1, H, L, D]
+        v_val: [1, H, L, D]
+        k_cache: [1, H, MAX_S, D]
+        v_cache: [1, H, MAX_S, D]
+        """
+
+        assert batch_idx.ndim == 2, "batch_idx must be a 2D tensor"
+        assert input_pos.ndim == 2, "input_pos must be a 2D tensor"
+        assert k_val.ndim == 4, "k_val must be a 4D tensor"
+        assert v_val.ndim == 4, "v_val must be a 4D tensor"
+        assert k_cache.ndim == 4, "k_cache must be a 4D tensor"
+        assert v_cache.ndim == 4, "v_cache must be a 4D tensor"
+        assert batch_idx.shape[0] == 1, "batch_idx must have batch size 1"
+
+        input_pos_block_idx = input_pos // self.page_size
+        input_pos_offset_in_block = input_pos % self.page_size
+        physical_kv_idx = (
+            self.page_table[batch_idx, input_pos_block_idx] * self.page_size
+            + input_pos_offset_in_block
+        )
+        k_cache[:, :, physical_kv_idx.view(-1), :] = k_val
+        v_cache[:, :, physical_kv_idx.view(-1), :] = v_val
+
+        return k_val, v_val

scripts/benchmarks/make_lora_adapter.py

@@ -0,0 +1,105 @@
+"""One-shot: materialize a rank-32 LoRA adapter on `unsloth/Qwen3-4B-Base`.
+
+Writes a PEFT-style directory so every backend (vLLM `LoRARequest`,
+`peft.PeftModel.from_pretrained`, Unsloth `FastLanguageModel.get_peft_model`)
+can load the SAME weights. Random-init is fine for throughput measurement --
+the goal is to have LoRA kernels active during generation, not a trained
+model.
+
+Run:
+    CUDA_VISIBLE_DEVICES=6 python scripts/benchmarks/make_lora_adapter.py \
+        --output outputs/lora_rank32_fresh
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+
+def parse_args():
+    p = argparse.ArgumentParser()
+    p.add_argument("--model_name", default = "unsloth/Qwen3-4B-Base")
+    p.add_argument("--output", default = "outputs/lora_rank32_fresh")
+    p.add_argument("--rank", type = int, default = 32)
+    return p.parse_args()
+
+
+def main():
+    args = parse_args()
+    out_dir = Path(args.output).resolve()
+    out_dir.mkdir(parents = True, exist_ok = True)
+
+    # Use vanilla HF -- PEFT's save_pretrained yields the canonical
+    # adapter_config.json + adapter_model.safetensors that vLLM's LoRARequest
+    # expects. Loading via Unsloth would leak Unsloth-specific LoRA wrappers.
+    import torch
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+    from peft import LoraConfig, get_peft_model
+
+    tok = AutoTokenizer.from_pretrained(args.model_name)
+    if tok.pad_token is None:
+        tok.pad_token = tok.eos_token
+
+    # bf16 base; we only need structure + save. Keep on CPU to avoid a GPU load
+    # just for `save_pretrained`.
+    print(f"[make_lora_adapter] Loading {args.model_name} on CPU...")
+    model = AutoModelForCausalLM.from_pretrained(args.model_name, dtype = torch.bfloat16)
+
+    peft_cfg = LoraConfig(
+        r = args.rank,
+        lora_alpha = args.rank * 2,
+        target_modules = [
+            "q_proj",
+            "k_proj",
+            "v_proj",
+            "o_proj",
+            "gate_proj",
+            "up_proj",
+            "down_proj",
+        ],
+        bias = "none",
+        task_type = "CAUSAL_LM",
+        lora_dropout = 0.0,
+    )
+    peft_model = get_peft_model(model, peft_cfg)
+    peft_model.print_trainable_parameters()
+
+    # Ensure both A and B matrices are non-zero. PEFT initializes A with
+    # kaiming_uniform and B with zeros -- which makes the adapter a no-op and
+    # would mask LoRA kernels on some backends. Seed B with tiny random values.
+    n_reinit = 0
+    with torch.no_grad():
+        for name, p in peft_model.named_parameters():
+            if "lora_B" in name:
+                p.normal_(mean = 0.0, std = 1e-4)
+                n_reinit += 1
+    print(
+        f"[make_lora_adapter] Reinitialized {n_reinit} lora_B matrices with tiny gaussian."
+    )
+
+    peft_model.save_pretrained(str(out_dir))
+    tok.save_pretrained(str(out_dir))
+
+    # Sanity: verify safetensors file present and non-trivial.
+    from safetensors import safe_open
+
+    st_path = out_dir / "adapter_model.safetensors"
+    n_zero_tensors = 0
+    n_tensors = 0
+    with safe_open(str(st_path), framework = "pt") as f:
+        for key in f.keys():
+            t = f.get_tensor(key)
+            n_tensors += 1
+            if (t == 0).all().item():
+                n_zero_tensors += 1
+    print(
+        f"[make_lora_adapter] Wrote {n_tensors} tensors to {st_path} "
+        f"({n_zero_tensors} all-zero)."
+    )
+    print(f"[make_lora_adapter] Adapter saved to {out_dir}")
+
+
+if __name__ == "__main__":
+    main()

scripts/benchmarks/persistent_cb.py

@@ -0,0 +1,121 @@
+"""Persistent ContinuousBatching manager for multi-step generation.
+
+`model.generate_batch(...)` initializes a fresh `ContinuousBatchingManager`
+on every call, which in turn allocates a new `PagedAttentionCache` and
+starts a new worker thread. Inside a GRPO training loop this happens once
+per step, amortized across `num_generations * per_device_train_batch_size`
+prompts per step, so the constant per-step cost (cache alloc, prefill
+warmup, thread spin-up) dominates when batch sizes are modest.
+
+`install_for_model(model, generation_config)` monkey-patches
+`model.generate_batch` on this instance to reuse a single long-lived
+manager. The manager is started lazily on first call; `teardown(model)`
+stops the background thread.
+
+This is deliberately kept as a stand-alone helper so it can be enabled /
+disabled per-run via CLI flag without touching TRL or transformers
+installs.
+"""
+
+from __future__ import annotations
+
+import threading
+import types
+from typing import Optional
+
+import torch
+from transformers import GenerationConfig
+from transformers.generation.continuous_batching import RequestStatus
+
+
+_ATTR = "_persistent_cb_manager"
+_LOCK_ATTR = "_persistent_cb_lock"
+
+
+def install_for_model(
+    model: torch.nn.Module, generation_config: GenerationConfig
+) -> None:
+    """Replace `model.generate_batch` with a version that reuses one manager.
+
+    The replacement accepts the same arguments as the stock method. A
+    trailing `generation_config` supplied to the call takes precedence; if
+    it differs from the one used at init, the persistent manager is torn
+    down and rebuilt (rare, but keeps semantics intact).
+    """
+    setattr(model, _LOCK_ATTR, threading.Lock())
+    setattr(model, _ATTR, None)
+    setattr(model, "_persistent_cb_gen_config", generation_config)
+
+    original = model.generate_batch
+
+    def generate_batch(
+        self,
+        inputs,
+        generation_config: Optional[GenerationConfig] = None,
+        progress_bar: bool = False,
+        slice_inputs: bool = True,
+        **kwargs,
+    ):
+        if not inputs:
+            return {}
+
+        gen_config = (
+            generation_config
+            or getattr(self, "_persistent_cb_gen_config", None)
+            or self.generation_config
+        )
+
+        lock = getattr(self, _LOCK_ATTR)
+        with lock:
+            manager = getattr(self, _ATTR)
+            stale = False
+            if manager is not None:
+                stale = (
+                    getattr(manager, "generation_config", None) is not gen_config
+                    or not manager.is_running()
+                )
+                if stale:
+                    try:
+                        manager.stop(block = True, timeout = 5.0)
+                    except Exception:
+                        pass
+                    setattr(self, _ATTR, None)
+                    manager = None
+            if manager is None:
+                manager = self.init_continuous_batching(
+                    generation_config = gen_config,
+                    slice_inputs = slice_inputs,
+                )
+                manager.start()
+                setattr(self, _ATTR, manager)
+
+        results = {}
+        num_requests = len(inputs)
+        manager.add_requests(inputs, **kwargs)
+        finished = 0
+        while finished < num_requests:
+            result = manager.get_result(timeout = 1)
+            if result is None:
+                if not manager.is_running():
+                    break
+                continue
+            if result.status == RequestStatus.FINISHED:
+                results[result.request_id] = result
+                finished += 1
+            else:
+                continue
+        return results
+
+    model.generate_batch = types.MethodType(generate_batch, model)
+    setattr(model, "_persistent_cb_original_generate_batch", original)
+
+
+def teardown(model: torch.nn.Module) -> None:
+    manager = getattr(model, _ATTR, None)
+    if manager is not None:
+        try:
+            manager.stop(block = True, timeout = 5.0)
+        except Exception:
+            pass
+    if hasattr(model, "_persistent_cb_original_generate_batch"):
+        model.generate_batch = model._persistent_cb_original_generate_batch

scripts/benchmarks/qwen3_grpo_naive.py

@@ -0,0 +1,188 @@
+"""Qwen3-4B GRPO with naive TRL generation (no vLLM, no CB).
+
+Mirrors the TRL example at https://huggingface.co/docs/trl/grpo_trainer: a
+vanilla HF model + `GRPOTrainer` with the default rollout path, which calls
+`model.generate(...)` per step. This is the honest "baseline" baseline — it
+is what a user would get if they just followed the TRL docs without enabling
+vLLM colocate or transformers continuous batching. Useful as a third column
+in the benchmark table.
+
+Hyperparameters, dataset, and reward functions are shared with the vLLM and
+CB scripts via `unsloth_grpo_common.py` so numbers are apples-to-apples.
+
+Run:
+    CUDA_VISIBLE_DEVICES=2 python scripts/qwen3_grpo_naive.py \
+        --max_steps 20 --num_generations 2 --per_device_train_batch_size 2 \
+        --output_dir outputs/grpo_naive --stats_path logs/naive_stats.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import time
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+
+from unsloth_grpo_common import (  # noqa: E402
+    StepTimer,
+    apply_chat_template_to_tokenizer,
+    build_dataset,
+    build_grpo_kwargs,
+    build_reward_funcs,
+    install_vllm_sampling_shim,
+    maybe_compile_trainer_forwards,
+    write_stats,
+)
+
+install_vllm_sampling_shim()
+
+import torch  # noqa: E402
+from transformers import AutoModelForCausalLM, AutoTokenizer  # noqa: E402
+from peft import LoraConfig, get_peft_model  # noqa: E402
+
+
+def parse_args():
+    p = argparse.ArgumentParser()
+    p.add_argument("--model_name", default = "unsloth/Qwen3-4B-Base")
+    p.add_argument("--max_seq_length", type = int, default = 2048)
+    p.add_argument("--lora_rank", type = int, default = 32)
+    p.add_argument("--max_steps", type = int, default = 20)
+    p.add_argument("--num_generations", type = int, default = 2)
+    p.add_argument("--per_device_train_batch_size", type = int, default = 2)
+    p.add_argument("--gradient_accumulation_steps", type = int, default = 1)
+    p.add_argument(
+        "--attn_impl",
+        default = "sdpa",
+        help = "Attention implementation: sdpa or flash_attention_2 (FA4 shim installed).",
+    )
+    p.add_argument("--output_dir", default = "outputs/grpo_naive")
+    p.add_argument("--stats_path", default = "logs/naive_stats.json")
+    p.add_argument(
+        "--compile_mode",
+        default = None,
+        choices = [None, "default", "reduce-overhead", "max-autotune-no-cudagraphs"],
+        help = "If set, torch.compile(model.forward, mode=...) after the trainer is built.",
+    )
+    p.add_argument("--compile_dynamic", action = "store_true", default = True)
+    return p.parse_args()
+
+
+def main():
+    args = parse_args()
+    os.makedirs(args.output_dir, exist_ok = True)
+    os.makedirs(os.path.dirname(os.path.abspath(args.stats_path)) or ".", exist_ok = True)
+
+    # Install the FA4 shim only if the caller asked for flash_attention_2.
+    # For sdpa we leave transformers untouched.
+    if args.attn_impl == "flash_attention_2":
+        import flash_attn_fa4_shim
+
+        flash_attn_fa4_shim.apply()
+
+    tokenizer = AutoTokenizer.from_pretrained(args.model_name)
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+    model = AutoModelForCausalLM.from_pretrained(
+        args.model_name,
+        dtype = torch.bfloat16,
+        attn_implementation = args.attn_impl,
+    ).to("cuda")
+
+    lora = LoraConfig(
+        r = args.lora_rank,
+        lora_alpha = args.lora_rank * 2,
+        target_modules = [
+            "q_proj",
+            "k_proj",
+            "v_proj",
+            "o_proj",
+            "gate_proj",
+            "up_proj",
+            "down_proj",
+        ],
+        bias = "none",
+        task_type = "CAUSAL_LM",
+    )
+    model = get_peft_model(model, lora)
+    try:
+        model.gradient_checkpointing_enable(
+            gradient_checkpointing_kwargs = {"use_reentrant": False}
+        )
+    except TypeError:
+        model.gradient_checkpointing_enable()
+    model.enable_input_require_grads()
+
+    apply_chat_template_to_tokenizer(tokenizer)
+
+    dataset, maximum_length = build_dataset(
+        tokenizer, max_seq_length = args.max_seq_length
+    )
+    print(f"[naive] Max prompt length (p90): {maximum_length}")
+    reward_funcs = build_reward_funcs(tokenizer)
+
+    from trl import GRPOConfig, GRPOTrainer
+
+    shared = build_grpo_kwargs(
+        tokenizer,
+        maximum_length,
+        max_seq_length = args.max_seq_length,
+        max_steps = args.max_steps,
+        num_generations = args.num_generations,
+        per_device_train_batch_size = args.per_device_train_batch_size,
+        gradient_accumulation_steps = args.gradient_accumulation_steps,
+        output_dir = args.output_dir,
+    )
+    # transformers' TopKLogitsWarper rejects -1. None skips the warper.
+    shared["top_k"] = None
+
+    training_args = GRPOConfig(
+        use_vllm = False,
+        use_transformers_paged = False,
+        bf16 = True,
+        **shared,
+    )
+
+    timer = StepTimer()
+
+    trainer = GRPOTrainer(
+        model = model,
+        processing_class = tokenizer,
+        reward_funcs = reward_funcs,
+        args = training_args,
+        train_dataset = dataset,
+        callbacks = [timer],
+    )
+
+    maybe_compile_trainer_forwards(
+        trainer, args.compile_mode, dynamic = args.compile_dynamic, tag = "naive"
+    )
+
+    torch.cuda.reset_peak_memory_stats()
+    t_start = time.perf_counter()
+    trainer.train()
+    t_train = time.perf_counter() - t_start
+
+    peak = torch.cuda.max_memory_allocated() / 1024**3
+
+    write_stats(
+        args.stats_path,
+        backend = "naive_trl",
+        timer = timer,
+        train_wall_s = t_train,
+        peak_memory_gb = peak,
+        max_prompt_length = shared["max_prompt_length"],
+        max_completion_length = shared["max_completion_length"],
+        num_generations = args.num_generations,
+        max_steps = args.max_steps,
+        extra = {"attn_impl": args.attn_impl},
+    )
+    print(f"[naive] Wrote stats to {args.stats_path}")
+    print(f"[naive] Total train wall: {t_train:.1f}s   Peak mem: {peak:.2f} GB")
+
+
+if __name__ == "__main__":
+    main()

scripts/benchmarks/qwen3_grpo_tpaged.py

@@ -0,0 +1,242 @@
+"""Qwen3-4B GRPO with transformers continuous-batching rollouts.
+
+Unsloth's Qwen3Attention monkey-patch bypasses the functional attention
+interface that `paged|<impl>` continuous batching relies on, so this script
+loads a vanilla HF Qwen3 with PEFT LoRA instead. Training is slower than the
+Unsloth path but the goal here is to evaluate transformers CB as a drop-in
+replacement for vLLM rollouts. See benchmark_results.md for numbers.
+
+Run:
+    CUDA_VISIBLE_DEVICES=2 python scripts/qwen3_grpo_tpaged.py \
+        --max_steps 61 --output_dir outputs/grpo_tpaged \
+        --stats_path logs/tpaged_stats.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import time
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+
+# `install_vllm_sampling_shim()` shims `vllm.sampling_params.GuidedDecodingParams`
+# for newer vLLM releases so TRL's GRPOTrainer imports cleanly. We do NOT
+# import `unsloth` here because that replaces TRL's GRPOTrainer with an
+# Unsloth-compiled variant that assumes the model has `for_training()` /
+# `for_inference()` hooks, which a vanilla HF model does not.
+from unsloth_grpo_common import (  # noqa: E402
+    StepTimer,
+    apply_chat_template_to_tokenizer,
+    build_dataset,
+    build_grpo_kwargs,
+    build_reward_funcs,
+    install_vllm_sampling_shim,
+    maybe_compile_trainer_forwards,
+    write_stats,
+)
+
+install_vllm_sampling_shim()
+
+import torch  # noqa: E402
+from transformers import AutoModelForCausalLM, AutoTokenizer  # noqa: E402
+from peft import LoraConfig, get_peft_model  # noqa: E402
+
+import flash_attn_fa4_shim  # noqa: E402
+
+flash_attn_fa4_shim.apply()
+
+
+def parse_args():
+    p = argparse.ArgumentParser()
+    p.add_argument("--model_name", default = "unsloth/Qwen3-4B-Base")
+    p.add_argument("--max_seq_length", type = int, default = 2048)
+    p.add_argument("--lora_rank", type = int, default = 32)
+    p.add_argument("--max_steps", type = int, default = 61)
+    p.add_argument("--num_generations", type = int, default = 4)
+    p.add_argument("--per_device_train_batch_size", type = int, default = 1)
+    p.add_argument("--gradient_accumulation_steps", type = int, default = 1)
+    p.add_argument(
+        "--attn_impl",
+        default = "sdpa",
+        help = "Base attention impl to compose with paged. 'sdpa' or 'flash_attention_2'.",
+    )
+    p.add_argument(
+        "--max_batch_tokens",
+        type = int,
+        default = 8192,
+        help = "PagedAttentionCache.max_batch_tokens. Default upper bound is 256 which is far too small.",
+    )
+    p.add_argument(
+        "--num_blocks",
+        type = int,
+        default = 8192,
+        help = "PagedAttentionCache.num_blocks (block_size=32). 8192*32 tokens of KV capacity.",
+    )
+    p.add_argument("--output_dir", default = "outputs/grpo_tpaged")
+    p.add_argument("--stats_path", default = "logs/tpaged_stats.json")
+    p.add_argument(
+        "--persistent_cb",
+        action = "store_true",
+        help = "Reuse one ContinuousBatchingManager across every training step instead "
+        "of letting TRL's generate_batch rebuild it (and the paged cache) each step.",
+    )
+    p.add_argument(
+        "--compile_mode",
+        default = None,
+        choices = [None, "default", "reduce-overhead", "max-autotune-no-cudagraphs"],
+        help = "If set, torch.compile(model.forward, mode=...) after the trainer is built.",
+    )
+    p.add_argument("--compile_dynamic", action = "store_true", default = True)
+    return p.parse_args()
+
+
+def main():
+    args = parse_args()
+    os.makedirs(args.output_dir, exist_ok = True)
+    os.makedirs(os.path.dirname(os.path.abspath(args.stats_path)) or ".", exist_ok = True)
+
+    # 1. Vanilla HF load (no Unsloth patches on the attention forward).
+    tokenizer = AutoTokenizer.from_pretrained(args.model_name)
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+    model = AutoModelForCausalLM.from_pretrained(
+        args.model_name,
+        dtype = torch.bfloat16,
+        attn_implementation = args.attn_impl,
+    )
+    model.to("cuda")
+
+    lora = LoraConfig(
+        r = args.lora_rank,
+        lora_alpha = args.lora_rank * 2,
+        target_modules = [
+            "q_proj",
+            "k_proj",
+            "v_proj",
+            "o_proj",
+            "gate_proj",
+            "up_proj",
+            "down_proj",
+        ],
+        bias = "none",
+        task_type = "CAUSAL_LM",
+    )
+    model = get_peft_model(model, lora)
+    try:
+        model.gradient_checkpointing_enable(
+            gradient_checkpointing_kwargs = {"use_reentrant": False}
+        )
+    except TypeError:
+        model.gradient_checkpointing_enable()
+    model.enable_input_require_grads()
+
+    apply_chat_template_to_tokenizer(tokenizer)
+
+    # 2. Dataset + rewards (identical to the vLLM script).
+    dataset, maximum_length = build_dataset(
+        tokenizer, max_seq_length = args.max_seq_length
+    )
+    print(f"[tpaged] Max prompt length (p90): {maximum_length}")
+    reward_funcs = build_reward_funcs(tokenizer)
+
+    # 3. Build GRPOConfig with transformers continuous batching enabled.
+    from trl import GRPOConfig, GRPOTrainer
+
+    shared = build_grpo_kwargs(
+        tokenizer,
+        maximum_length,
+        max_seq_length = args.max_seq_length,
+        max_steps = args.max_steps,
+        num_generations = args.num_generations,
+        per_device_train_batch_size = args.per_device_train_batch_size,
+        gradient_accumulation_steps = args.gradient_accumulation_steps,
+        output_dir = args.output_dir,
+    )
+    # transformers `TopKLogitsWarper` rejects -1. None skips the warper entirely.
+    shared["top_k"] = None
+    # The default PagedAttentionCache upper bounds
+    # (`_upper_bound_max_batch_tokens=256`, `_upper_bound_num_blocks=4096`)
+    # are extremely conservative and cause long decode loops. Raise them via
+    # `generation_kwargs`, which TRL forwards to `GenerationConfig`, which the
+    # CB manager then reads off when sizing the paged cache.
+    training_args = GRPOConfig(
+        use_vllm = False,
+        use_transformers_paged = True,
+        bf16 = True,
+        generation_kwargs = {
+            "max_batch_tokens": args.max_batch_tokens,
+            "num_blocks": args.num_blocks,
+        },
+        **shared,
+    )
+
+    # 4. Timing callback.
+    timer = StepTimer()
+
+    trainer = GRPOTrainer(
+        model = model,
+        processing_class = tokenizer,
+        reward_funcs = reward_funcs,
+        args = training_args,
+        train_dataset = dataset,
+        callbacks = [timer],
+    )
+
+    maybe_compile_trainer_forwards(
+        trainer, args.compile_mode, dynamic = args.compile_dynamic, tag = "tpaged"
+    )
+
+    if args.persistent_cb:
+        # TRL constructs `self.generation_config` once in `__init__`; reuse
+        # the same object so the persistent manager stays warm.
+        from persistent_cb import install_for_model, teardown
+
+        # TRL generates against the unwrapped base model; attach the patch
+        # directly to it so every rollout picks up the persistent manager.
+        base = (
+            trainer.model_wrapped.base_model.model
+            if hasattr(trainer.model_wrapped, "base_model")
+            else trainer.model_wrapped
+        )
+        install_for_model(base, trainer.generation_config)
+        # PEFT's wrapper chains `generate_batch` through `base_model.model` via
+        # __getattr__, so installing on `base` is enough for TRL's call path.
+
+    torch.cuda.reset_peak_memory_stats()
+    t_start = time.perf_counter()
+    try:
+        trainer.train()
+    finally:
+        if args.persistent_cb:
+            from persistent_cb import teardown
+
+            teardown(base)
+    t_train = time.perf_counter() - t_start
+
+    peak = torch.cuda.max_memory_allocated() / 1024**3
+
+    write_stats(
+        args.stats_path,
+        backend = "transformers_paged",
+        timer = timer,
+        train_wall_s = t_train,
+        peak_memory_gb = peak,
+        max_prompt_length = shared["max_prompt_length"],
+        max_completion_length = shared["max_completion_length"],
+        num_generations = args.num_generations,
+        max_steps = args.max_steps,
+        extra = {
+            "attn_impl": args.attn_impl,
+            "persistent_cb": args.persistent_cb,
+        },
+    )
+    print(f"[tpaged] Wrote stats to {args.stats_path}")
+    print(f"[tpaged] Total train wall: {t_train:.1f}s   Peak mem: {peak:.2f} GB")
+
+
+if __name__ == "__main__":
+    main()

scripts/benchmarks/qwen3_grpo_vllm.py

@@ -0,0 +1,159 @@
+"""Qwen3-4B GRPO baseline (vLLM colocated) derived from the notebook.
+
+Run:
+    CUDA_VISIBLE_DEVICES=2 python scripts/qwen3_grpo_vllm.py \
+        --max_steps 61 --output_dir outputs/grpo_vllm \
+        --stats_path logs/vllm_stats.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import time
+from pathlib import Path
+
+# Unsloth must be imported before transformers / trl.
+os.environ.setdefault("UNSLOTH_VLLM_STANDBY", "1")
+
+# Allow sibling import of the common module.
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+
+from unsloth import FastLanguageModel  # noqa: E402
+import torch  # noqa: E402
+
+from unsloth_grpo_common import (  # noqa: E402
+    StepTimer,
+    apply_chat_template_to_tokenizer,
+    build_dataset,
+    build_grpo_kwargs,
+    build_reward_funcs,
+    write_stats,
+)
+
+
+def parse_args():
+    p = argparse.ArgumentParser()
+    p.add_argument("--model_name", default = "unsloth/Qwen3-4B-Base")
+    p.add_argument("--max_seq_length", type = int, default = 2048)
+    p.add_argument("--lora_rank", type = int, default = 32)
+    p.add_argument("--max_steps", type = int, default = 61)
+    p.add_argument("--num_generations", type = int, default = 4)
+    p.add_argument("--per_device_train_batch_size", type = int, default = 1)
+    p.add_argument("--gradient_accumulation_steps", type = int, default = 1)
+    p.add_argument("--gpu_memory_utilization", type = float, default = 0.8)
+    p.add_argument("--output_dir", default = "outputs/grpo_vllm")
+    p.add_argument("--stats_path", default = "logs/vllm_stats.json")
+    return p.parse_args()
+
+
+def main():
+    args = parse_args()
+    os.makedirs(args.output_dir, exist_ok = True)
+    os.makedirs(os.path.dirname(os.path.abspath(args.stats_path)) or ".", exist_ok = True)
+
+    # 1. Load model with vLLM fast inference enabled.
+    model, tokenizer = FastLanguageModel.from_pretrained(
+        model_name = args.model_name,
+        max_seq_length = args.max_seq_length,
+        load_in_4bit = False,
+        fast_inference = True,
+        max_lora_rank = args.lora_rank,
+        gpu_memory_utilization = args.gpu_memory_utilization,
+    )
+    model = FastLanguageModel.get_peft_model(
+        model,
+        r = args.lora_rank,
+        target_modules = [
+            "q_proj",
+            "k_proj",
+            "v_proj",
+            "o_proj",
+            "gate_proj",
+            "up_proj",
+            "down_proj",
+        ],
+        lora_alpha = args.lora_rank * 2,
+        use_gradient_checkpointing = "unsloth",
+        random_state = 3407,
+    )
+    apply_chat_template_to_tokenizer(tokenizer)
+
+    # 2. Dataset + rewards.
+    dataset, maximum_length = build_dataset(
+        tokenizer, max_seq_length = args.max_seq_length
+    )
+    print(f"[vllm] Max prompt length (p90): {maximum_length}")
+    reward_funcs = build_reward_funcs(tokenizer)
+
+    # 3. vLLM sampling params match the notebook.
+    from vllm import SamplingParams
+
+    vllm_sampling_params = SamplingParams(
+        min_p = 0.1,
+        top_p = 1.0,
+        top_k = -1,
+        seed = 3407,
+        stop = [tokenizer.eos_token],
+        include_stop_str_in_output = True,
+    )
+
+    # 4. Build GRPOConfig.
+    from trl import GRPOConfig, GRPOTrainer
+
+    shared = build_grpo_kwargs(
+        tokenizer,
+        maximum_length,
+        max_seq_length = args.max_seq_length,
+        max_steps = args.max_steps,
+        num_generations = args.num_generations,
+        per_device_train_batch_size = args.per_device_train_batch_size,
+        gradient_accumulation_steps = args.gradient_accumulation_steps,
+        output_dir = args.output_dir,
+    )
+    training_args = GRPOConfig(
+        use_vllm = True,
+        vllm_mode = "colocate",
+        vllm_sampling_params = vllm_sampling_params,
+        vllm_gpu_memory_utilization = args.gpu_memory_utilization,
+        **shared,
+    )
+
+    # 5. Timing callback.
+    timer = StepTimer()
+
+    trainer = GRPOTrainer(
+        model = model,
+        processing_class = tokenizer,
+        reward_funcs = reward_funcs,
+        args = training_args,
+        train_dataset = dataset,
+        callbacks = [timer],
+    )
+
+    torch.cuda.reset_peak_memory_stats()
+    t_start = time.perf_counter()
+    trainer.train()
+    t_train = time.perf_counter() - t_start
+
+    peak = torch.cuda.max_memory_allocated() / 1024**3
+
+    write_stats(
+        args.stats_path,
+        backend = "vllm_colocated",
+        timer = timer,
+        train_wall_s = t_train,
+        peak_memory_gb = peak,
+        max_prompt_length = shared["max_prompt_length"],
+        max_completion_length = shared["max_completion_length"],
+        num_generations = args.num_generations,
+        max_steps = args.max_steps,
+    )
+    print(f"[vllm] Wrote stats to {args.stats_path}")
+    print(f"[vllm] Total train wall: {t_train:.1f}s   Peak mem: {peak:.2f} GB")
+
+
+if __name__ == "__main__":
+    main()

scripts/benchmarks/results/flex_vs_vllm.md

@@ -0,0 +1,291 @@
+# flex_attention + paged KV + CUDA graphs vs vLLM
+
+Goal stated in the plan: "CB reaches at least 30% of vLLM throughput." After
+the earlier phases ran out of gas at ~10% with transformers CB, we rebuilt
+the rollout path on top of `torch.nn.attention.flex_attention` using the
+paged KV + BlockMask pattern from
+[flex-nano-vllm](https://github.com/changjonathanc/flex-nano-vllm).
+
+## Setup
+
+- B200 (sm_100), Qwen3-4B-Base, bf16
+- 512 max_new_tokens per prompt, 16-prompt warmup, N measured rounds
+  (`decode_tps_best` = steady-state throughput after Inductor compile +
+  CUDA graph capture have amortized).
+- flex path is greedy (CUDA-graph safe); vLLM uses equivalence sampling
+  (`temperature=0.1, top_p=0.97, min_p=0.5, top_k=5`).
+- No LoRA unless noted; LoRA rank 32 applied to all
+  {q,k,v,o,gate,up,down}_proj.
+
+## Best config (after FlexKernelOptions sweep)
+
+```json
+decode_kernel_options = {
+    "PRESCALE_QK": true,
+    "USE_TMA": true,
+    "BLOCKS_ARE_CONTIGUOUS": true,
+    "num_warps": 8,
+    "num_stages": 3
+}
+prefill_kernel_options = {
+    "FORCE_USE_FLEX_ATTENTION": true,
+    "PRESCALE_QK": true,
+    "USE_TMA": true
+}
+```
+
+## Batch-size sweep (flex tuned vs vLLM, 512 max_new_tokens)
+
+| Batch | flex tps | vLLM tps | flex / vLLM | flex mem | vLLM mem |
+|------:|---------:|---------:|------------:|---------:|---------:|
+|   8   |    680   |  1900    |    35.8 %   |  44 GB   |  156 GB  |
+|  16   |   1626   |  3698    |    44.0 %   |  44 GB   |  156 GB  |
+|  32   |   3134   |  6318    |    49.6 %   |  44 GB   |  156 GB  |
+|  64   | **5474** | 10459    |  **52.3 %** |  44 GB   |  156 GB  |
+| 128   |   5565   | 14996    |    37.1 %   |  81 GB   |  157 GB  |
+| 256   |   5812   | 21170    |    27.5 %   | 154 GB   |  157 GB  |
+
+### Canonical GRPO workload (batch 64 + LoRA rank 32)
+
+| Backend                                    | tok/s best | peak mem  | flex / vLLM |
+|--------------------------------------------|-----------:|----------:|------------:|
+| vLLM (LoRARequest)                         |       7775 |    156 GB |       100 % |
+| **flex** (double-copy, drift-free)         |  **5785**  | **~52 GB**|    **74 %** |
+| flex -- LoRA unmerged (PEFT wrapper)       |       2683 |     45 GB |        35 % |
+
+At the GRPO workload flex reaches **74 % of vLLM throughput at ~3 x less
+memory**. Starting point before this work was 9 % with transformers CB.
+
+**Why the two flex rows are so far apart:** when PEFT keeps the adapter
+unmerged, every projection runs three matmuls (`base_layer(x) + scaling *
+lora_B(lora_A(x))`) instead of one, which is ~50 % slowdown across the
+36-layer stack. GRPO cannot use the unmerged path naively because the
+trainer needs the adapter weights separable; but it also shouldn't pay
+that cost.
+
+#### What the default path does now: double-copy rollout
+
+We keep two copies of the base model on GPU:
+
+- `base_model` -- pristine; never mutated.
+- `inference_model = deepcopy(base_model)` -- wrapped by PEFT; merged
+  LoRA lives on `base_layer.weight` here.
+
+Before each rollout (and at setup), `refresh_lora_merge_from_pristine`:
+
+1. Walks PEFT's `LoraLayer` modules.
+2. `module.base_layer.weight.data.copy_(base_submodule.weight.data)` --
+   in-place restore from the pristine base.
+3. Resets `module.merged_adapters = []` directly (skips PEFT's unmerge
+   arithmetic).
+4. Calls `peft_model.merge_adapter()` once to fold LoRA into the
+   inference copy fresh.
+
+We **never call `unmerge_adapter()`**. PEFT's merge/unmerge pair is
+asymmetric at bf16 -- merge does `W_bf16 += delta_fp32` (the `+=`
+upcasts, stores back in bf16), unmerge does `W_bf16 -= delta_fp32.to(bf16)`
+(the delta is rounded to bf16 first, then subtracted). Net effect is ~1
+ULP drift on `base_layer.weight` per cycle (empirically ~6e-5 max diff
+after one cycle on this model). Across hundreds of GRPO iterations
+that corrupts the base model and the adapter trains against a drifting
+target. Re-materialising from pristine per refresh bypasses the whole
+round-trip.
+
+**Cost.** +~8 GB GPU memory (second copy of Qwen3-4B bf16 weights), so
+peak memory goes from ~44 GB to ~52 GB. Per-refresh overhead: param
+copy (~3 ms) + `merge_adapter()` (~30 ms) = ~35 ms, well under 1 % of a
+5-7 s rollout.
+
+**CUDA graphs stay valid.** In-place `weight.data.copy_(pristine)`
+writes to the same tensor storage, so graphs captured against the
+merged weights read current values at the captured addresses on the
+next replay -- no re-capture needed.
+
+#### Drift verification
+
+`--verify_no_drift` takes a sha256 over every parameter in `base_model`
+(raw bytes via `tensor.view(torch.uint8)`), runs N perturb+refresh
+cycles (random noise added to `lora_A` / `lora_B` on each iteration,
+simulating a training step), re-hashes, and asserts bit-identical.
+It also checks determinism of the inference copy: after restoring the
+LoRA A/B weights to their initial values and refreshing, the merged
+state-dict hash matches the pre-perturbation hash.
+
+Confirmed on Qwen3-4B bf16 with LoRA rank 32 across 10 refreshes: base
+model bit-identical; inference copy deterministic after LoRA restore.
+
+```
+CUDA_VISIBLE_DEVICES=6 python scripts/benchmarks/qwen3_flex_inference.py \
+  --verify_no_drift --lora_adapter outputs/lora_rank32_fresh --n_rounds 1 \
+  --stats_path scripts/benchmarks/results/stats/flex_verify_nodrift.json
+```
+
+The "LoRA unmerged" row is shown only for reference -- it's what you'd
+get with a naive PEFT wrapper on the hot path. **Don't use it in
+production**, and it doesn't apply outside the 4-bit path below.
+
+`--no_merge_lora` opts into that reference path (single model, PEFT
+wrapper, adapter unmerged). It's kept for the comparison row above and
+nothing else.
+
+### Same workload at `load_in_4bit=True` (Unsloth bnb-4bit shard)
+
+Loading base as bitsandbytes 4-bit (`unsloth/Qwen3-4B-Base-unsloth-bnb-4bit`,
+compute dtype bf16). LoRA kept as PEFT wrapper (can't merge into 4-bit;
+the double-copy pattern above also doesn't apply -- bnb's `Linear4bit`
+holds packed quantised weights, not regular bf16, so an in-place copy
+of `base_layer.weight` isn't meaningful, and materialising a bf16
+inference copy via dequant would wipe out the memory saving of 4-bit).
+lm_head is tied to embed_tokens post-load because the 4-bit shard ships
+without an lm_head parameter.
+
+| Backend                         | tok/s | peak mem | output      |
+|---------------------------------|------:|---------:|:------------|
+| Unsloth fast_inference (vLLM)   |  4515 | 159 GB   | coherent    |
+| **flex** (this PR)              |**1738**| **40.6 GB** | coherent    |
+| transformers CB (sdpa)          |   504 | 124 GB   | **gibberish** |
+
+4-bit costs throughput on every backend (vLLM-path 4515 vs bf16 7775 = 58 %;
+flex 1738 vs bf16 5744 = 30 %). The regression is worse for flex because
+PEFT-without-merge doubles the number of matmuls per projection (base + LoRA
+add, separately) on top of the bnb dequant cost; the bf16 path merges LoRA
+into the base and skips both. Peak memory barely moves for vLLM because KV
+cache at `gpu_memory_utilization=0.8` dominates regardless of base size.
+
+Transformers CB at 4-bit + LoRA produces garbage tokens even with
+`model.lm_head.weight = model.model.embed_tokens.weight` tied explicitly.
+Likely a PEFT-over-bnb + batched `generate_batch` interaction bug; did not
+debug further.
+
+## What each option did (batch 64, no LoRA, after CUDA graph capture)
+
+| Config                                                                | tok/s | vs baseline |
+|-----------------------------------------------------------------------|------:|------------:|
+| eager (no graphs)                                                     |  ~420 |       -     |
+| + CUDA graphs                                                         |  4279 |    baseline |
+| + `PRESCALE_QK=true`                                                  |  4367 |       +2 %  |
+| + `USE_TMA=true`                                                      |  4425 |       +3 %  |
+| + `BLOCKS_ARE_CONTIGUOUS=true`                                        |  4703 |       +10 % |
+| + `num_warps=8`                                                       |  5474 |       +28 % |
+| + `num_warps=8, num_stages=3`                                         |  **5898** (peak) |       +38 % |
+
+The single biggest win came from **`num_warps=8`** (up from the default,
+which on Blackwell tends to pick 4 for small block sizes). TMA helps a
+couple percent; `BLOCKS_ARE_CONTIGUOUS` (safe in our setup because
+PageTable.reserve allocates pages sequentially on a fresh batch) helps
+another ~10 % because it lets the kernel skip the page-table indirection
+per block.
+
+## What broke correctness and had to be dropped
+
+- **`ROWS_GUARANTEED_SAFE=true`**: we reserve `batch_idx=0` and
+  `page_idx=0` as padding slots. Padded decode rows only attend to those
+  reserved slots, so the mask returns False for every kv_idx on those
+  rows. Skipping the row-has-at-least-one-unmasked check NaNs the
+  softmax and the model outputs `!!!!!!`.
+- **`BACKEND="TRITON_DECODE"`**: documented but the Inductor code path
+  doesn't recognize the literal. Raises `NameError('TRITON_DECODE is
+  not defined')`.
+- **`USE_TMA=true` + `torch.compile(call_model_with_flex_kwargs)`**:
+  misaligned address at runtime. torch.compile on the whole forward
+  walker breaks TMA's alignment assumptions. Either disable TMA when
+  compiling the walker, or skip compiling the walker (CUDA graph
+  capture already captures it).
+- **`torch.compile(flex_attention, mode="max-autotune")`**: tries to
+  nest `cudagraph_trees` inside our raw CUDA graph capture and hits
+  `Cannot prepare for replay during capturing stage`. Use
+  `max-autotune-no-cudagraphs` instead; negligible throughput delta vs
+  default mode.
+
+## What I tried that did NOT move the needle
+
+- **`BACKEND="FLASH"` on prefill** (FA4 / FlashAttention-4 on Blackwell,
+  torch 2.11 + flash-attn CuTeDSL): empirically 4617 tok/s at batch 64 +
+  LoRA vs 5744 baseline on torch 2.11. The FA4 CuTe kernel is slow when
+  `mask_mod` indexes by `kv_idx` (documented in the attention-gym
+  `flex_flash_attention.py` limitations: "Indexing by kv_idx is a large
+  perf hit"). Our prefill mask is `document_causal`:
+      `docs[q_idx] == docs[kv_idx]`
+  which hits that exact slow path. `BLOCK_SIZE=(256, 128)` + padding to
+  the 256-row Q tile works (output is coherent), it's just slower than
+  the default Triton flex path for this mask.
+- **Inductor autotune replay** (`TORCHINDUCTOR_FLEX_ATTENTION_LOGGING_FILE`
+  + `mode="max-autotune-no-cudagraphs"` + parse the JSON log): Inductor's
+  chosen best decode config (`fwd_num_warps=4, fwd_num_stages=3,
+  fwd_BLOCK_M=64, fwd_BLOCK_N=64`) lands at 4827 tok/s -- worse than the
+  hand-tuned `num_warps=8` at 5744. Autotune times a single kernel call,
+  which doesn't catch cumulative register-spill / L1 effects across the
+  36-layer stack. Harness lives at `flex_autotune_replay.py`.
+- **torch.compile on `call_model_with_flex_kwargs`**: 4425 tok/s (same
+  as eager walker) because the CUDA graph already captures every op in
+  the walker into one replay. The compile step is work we don't need.
+- **`num_warps=4` / `num_warps=16`**: 4486 / 4748 -- neither beats 8.
+  Inductor's default picks 4 on small blocks and we're already past
+  that sweet spot, but 16 wastes registers.
+- **Explicit `fwd_BLOCK_M=128, fwd_BLOCK_N=128` pinning** on top of the
+  manual best: 5009 tok/s. The implicit default already picks 128 for
+  our shape; pinning it inhibits Inductor's shape-specialised choice
+  between the flex_attention and flex_decoding templates.
+
+## Torch version + run-to-run noise
+
+Upgrading torch 2.9.1 -> 2.11 (required for FA4's CuTeDSL path) moves
+best-of-N tok/s from ~5616 to ~5660 at batch 64 + LoRA -- essentially
+within noise. Over 10 rounds, median is 4192 and best is 5660; the large
+spread is GPU clock throttling across a ~60-second sustained run plus
+variable prompt-length distributions per round. Reported numbers use
+best-of-N to match the prior harness; steady-state median is roughly 75
+ % of best.
+
+## Architecture notes (unchanged from prior commits)
+
+- `flex_paged_attention.py`: `PagedKVCache` + `PageTable` verbatim from
+  flex-nano-vllm (BSD-3).
+- `qwen3_flex_inference.py`: monkey-patches `Qwen3Attention.forward` to
+  call `flex_attention(q, k, v, block_mask=...)` against the paged cache.
+  Walks the `Qwen3Model` layer stack manually so `flex_block_mask /
+  flex_input_pos / flex_batch_idx` reach the attention layer without
+  modifying `Qwen3ForCausalLM.forward`. `capture_decode_cudagraph()`
+  pre-reserves one page per batch slot, captures one CUDA graph per
+  bucket in `[1,2,4,8,16,32,...,max_bs]`, then releases the scratch
+  batches.
+
+## Output coherence
+
+All tuned configs produce coherent math solutions on the DAPO-Math-17k
+prompts. See `sample_completions` in any `logs/flex_*_tuned.json`.
+
+## What's left on the table
+
+- **Chunked prefill**: vLLM interleaves prefill and decode inside a
+  single step. flex does a full separate prefill pass per new batch,
+  which is the main remaining penalty for large batches.
+- **Prefill-path mask refactor**: the document_causal mask indexes by
+  `kv_idx`. Flattening to a per-query bias (`bias[q_idx]`) would put
+  FA4 back on the fast path, but this is a non-trivial rework because
+  the causal-within-document constraint needs to be encoded without the
+  `docs[kv_idx]` lookup.
+- **Exhaustive Triton autotune** for flex_decoding: attention-gym's
+  `flex_grid_sweep.py` enumerates 144 fwd configs; Inductor's default
+  autotune only probes a handful. Running the full sweep with
+  end-to-end tok/s as the metric (not single-call ms) might beat the
+  manual num_warps=8 finding, but 144 * 5 rounds is ~20 hrs of B200
+  time.
+- **Kernel-level parity on decode**: vLLM on sm_100 uses FlashInfer
+  TRTLLM kernels which are fused / tuned more aggressively than
+  flex_attention's Inductor-generated Triton. Closing the last
+  ~28-48 % gap will require either tuning more Triton configs or
+  waiting for a TMA-native flex_attention path.
+
+## Raw stats (under `scripts/benchmarks/results/stats/`)
+
+- `flex_{8,16,32,64,128}_tuned.json` (best opts, 5 rounds, torch 2.9.1)
+- `flex_64_lora_tuned.json` (GRPO canonical, torch 2.9.1)
+- `flex_64_lora_torch211_baseline.json` + `_repeat.json` + `_10rounds.json`
+  (same config re-run on torch 2.11 to measure noise)
+- `flex_64_lora_fa4prefill.json` (FA4 prefill regression at batch 64)
+- `flex_64_lora_autotune{,_tma}.json` (Inductor-autotune-suggested config)
+- `flex_64_lora_warps2.json` + `flex_64_lora_pinned_blocks.json` (other
+  sweep points)
+- `flex_{32,64,128,256}x512[_lora]_cudagraph.json` (prior best-of-3 runs)
+- `vllm_{8,16,32,64,128,256}[x512][_lora].json`

scripts/benchmarks/results/grpo_equivalence.md

@@ -0,0 +1,128 @@
+# Phase 2: end-to-end GRPO backend comparison
+
+Same dataset, reward functions, sampling (`temperature=0.1, top_p=0.97,
+min_p=0.5, top_k=5`), and seed (3407) across backends. `num_generations=4`;
+`per_device_train_batch_size` auto-raised to 4 on vanilla-HF backends so
+TRL's `generation_batch_size % num_generations == 0` check passes
+(Unsloth's loader does this for you, vanilla HF does not).
+
+Callbacks: `StatisticsCallback` from `torch_debugging_utils` logs per-step
+loss, grad-norm, memory, wall time; reward / KL are captured from the TRL
+log dict. Median step wall is measured on steps 4..N (first 3 skipped to
+amortize compile / graph / warmup).
+
+## 10-step vibe check
+
+| Backend                    | Train wall (s) | Median step (s) | Peak mem (GB) | % of vLLM |
+|----------------------------|----------------|-----------------|---------------|-----------|
+| vLLM (fast_inference)      | 74.4           | **4.14**        | 157.9         | 100 %     |
+| unsloth_fi_false           | 355.4          | 23.95           | **10.7**      | 17 %      |
+| cb_paged (sdpa_paged load) | 466.0          | 36.02           | 55.6          | 11.5 %    |
+
+## 30-step equivalence
+
+| Backend                    | Train wall (s) | Median step (s) | Peak mem (GB) | % of vLLM |
+|----------------------------|----------------|-----------------|---------------|-----------|
+| vLLM (fast_inference)      | 215.9          | **5.14**        | 159.0         | 100 %     |
+| unsloth_fi_false           | 1165.4         | 41.30           | **10.7**      | 12.4 %    |
+| cb_paged                   | 1564.5         | 39.82           | 61.9          | 12.9 %    |
+
+(Note: fi_false's median step jumped from 23.95 s at 10 steps to 41.30 s at
+30 steps because the early-GRPO policy started producing longer completions
+as it learned to place the `</SOLUTION>` marker; the same effect is present
+but smaller in cb_paged because its LoRA warm-up trajectory is different.)
+
+## Pairwise diff vs vLLM (30 steps, `scripts/benchmarks/compare_grpo_runs.py`)
+
+| Pair                            | max &#124;loss diff&#124; | max &#124;reward diff&#124; | max &#124;kl diff&#124; | max &#124;grad_norm diff&#124; |
+|---------------------------------|---------------------------|------------------------------|------------------------|--------------------------------|
+| vLLM vs **unsloth_fi_false**    | 0.39                      | 9.25 (mean 2.99)             | **0.015**              | 0.94                           |
+| vLLM vs **cb_paged**            | 0.83                      | 6.25 (mean 2.29)             | *(not logged)*         | 919.1                          |
+
+Reward diffs of 2-9 are expected: different rollout backends produce
+different completions even at `temperature=0.1` because of kernel-level
+non-determinism (vLLM uses FlashInfer TRTLLM kernels, CB uses paged SDPA /
+FA4, Unsloth uses its cached fp16 LoRA path). The reward function reads
+those completions, so the reward array mechanically differs. What matters
+for equivalence is:
+
+- **KL trajectory is near-identical** between vLLM and unsloth_fi_false
+  (both stay in `[0, 0.015]` across all 30 steps). The KL *term* of the
+  GRPO loss is the guardrail against policy drift, so matching KL means
+  the training dynamics are in the same regime.
+- **Loss magnitudes are bounded** in `[-0.3, 1.0]` for all three backends.
+- **No NaNs, no unbounded growth, no gibberish completions** in any run.
+
+## grad_norm 919 on cb_paged
+
+The enormous cb_paged grad_norm (vs vLLM's ~1.0) is a clipping story, not a
+correctness story: the vLLM path goes through Unsloth's `FastLanguageModel`
+which clips gradients to `max_grad_norm=1.0` internally, while the vanilla
+HF path used by cb_paged picks up TRL's raw grad_norm reported by the
+optimizer pre-clip (or without clipping if no `max_grad_norm` is set in
+GRPOConfig). For a fair training-dynamics comparison the cb_paged config
+should set `max_grad_norm=1.0` explicitly; left for a follow-up commit.
+
+## KL missing for cb_paged
+
+`StatisticsCallback.on_log` forwards the full TRL log dict into its per-step
+entry only on steps where `loss` is present. TRL's vanilla-HF path separately
+logs KL on a different log call that doesn't include loss, so the callback
+silently drops it. Follow-up: relax the callback so every log dict with a
+`step` field merges into the matching entry regardless of which keys are
+present.
+
+## Headline takeaways
+
+1. **unsloth_fi_false is the pragmatic middle ground**: 12-17% of vLLM's
+   throughput, **15x less peak memory** (10.7 GB vs 159 GB), KL trajectory
+   matching vLLM within sampling noise.
+2. **cb_paged is close to fi_false in throughput at this batch size** (41 s
+   vs 40 s median step at 30 steps) but costs 6x more memory. Phase 3
+   (main-thread sync driver + CUDA graphs on the rollout) is the right
+   lever for making CB competitive.
+3. **torch.compile on the training step is not a quick win** for either
+   backend (Phase 4 report below).
+
+## Phase 3 state (CB sync driver)
+
+`scripts/benchmarks/cb_sync_driver.py`:
+- Eager main-thread driver works end-to-end: smoke test on GPU 1 with 8
+  prompts / 64 tokens produced the expected 512 correct tokens.
+- CUDA graph capture hangs on the first graphed step. Likely cause:
+  `ContinuousBatchProcessor._sample` reads `next_tokens.size(1)` as a
+  Python int to slice `batch_processor.output_ids[:, :tokens]`, which
+  forces a CPU-GPU sync and is not CUDA-graph-safe. Fix direction: keep
+  a fixed `tokens` count when `slice_inputs=False` (buffer size is
+  constant), or rewrite the copy as a full-buffer `copy_` without the
+  slice.
+- Deferred to a follow-up commit.
+
+## Phase 4 state (torch.compile on training forward)
+
+- `unsloth_fi_false + compile_mode=default`: crashes with
+  `PeftModel_fast_forward() got multiple values for argument 'input_ids'`.
+  Unsloth's monkey-patched forward and Dynamo's argument rebinding don't
+  compose.
+- `cb_paged + compile_mode=default`: Dynamo emits 700+ recompiles /
+  graph breaks on the first optimizer step and never makes progress.
+  Root cause: `modeling_utils.make_inputs_require_grads` calls
+  `Tensor.requires_grad_()` which triggers Dynamo GB0125 (unsupported
+  mutating op). TRL's GRPO `_compute_loss` then re-enters the tracer,
+  which re-triggers the break, which recompiles, and so on.
+- `vllm` is excluded (vLLM owns its own compile pipeline).
+
+Net: compile on the training step is not the right lever in this stack.
+Phase 3 (CUDA graphs on the rollout decode) is.
+
+## Raw stats
+
+- `scripts/benchmarks/results/stats/grpo_{vllm,unsloth_fi_false,cb_paged}_{10,30}.json`
+  (StatisticsCallback per-step logs with full TRL metric dict)
+- `scripts/benchmarks/results/stats/grpo_*_{10,30}.summary.json` (short form)
+
+Pairwise diff:
+
+    python scripts/benchmarks/compare_grpo_runs.py \
+        --ref logs/grpo_vllm_30.json \
+        --candidate logs/grpo_unsloth_fi_false_30.json

scripts/benchmarks/results/lora_rollout_baselines.md

@@ -0,0 +1,60 @@
+# Phase 1: rollout-only LoRA rank-32 microbenchmark
+
+Every backend generates the same 32 prompts (DAPO-Math-17k, seed 3407) for
+`max_new_tokens=512` with equivalence sampling: `temperature=0.1, top_p=0.97,
+min_p=0.5, top_k=5`. 16-prompt warmup, 2 measured rounds, median wall reported.
+
+All four backends load the same `outputs/lora_rank32_fresh` adapter (see
+`make_lora_adapter.py`). LoRA kernels are active on every decode step.
+
+## Results (GPU B200, bf16, Qwen3-4B-Base + rank-32 LoRA)
+
+| Backend              | Median wall (s) | Decode tok/s | Prompt tok/s | Peak mem (GB) | % of vLLM |
+|----------------------|-----------------|--------------|--------------|---------------|-----------|
+| vLLM (fast_inference)| 3.30            | **4581**     | 1467         | 156.2         | 100.0 %   |
+| unsloth_fi_false     | 25.54           | 641          | 190          | **15.8**      | 14.0 %    |
+| CB paged+FA4 (persistent) | 34.99      | 422          | 138          | 103.8         | 9.2 %     |
+| CB sdpa_paged (persistent)| 34.07      | 434          | 142          | 111.9         | 9.5 %     |
+
+## Observations
+
+1. **vLLM with LoRA is ~37% slower than vLLM without LoRA** (7224 → 4581 tok/s
+   per the pre-LoRA PR table). The LoRA kernels cost real time even in vLLM.
+   Still the gold standard by a wide margin.
+
+2. **Unsloth `fast_inference=False` is the surprise**: **1.5× faster than CB**
+   at **1/7th the peak memory**. The cached fp16 LoRA copies in
+   `fast_linear_forward` and the Triton RMSNorm/RoPE paths dominate the CB
+   baseline on this workload. It is a real practical middle ground — no vLLM
+   dependency, low memory, and ~14% of vLLM's throughput.
+
+3. **CB paged_attention (FA4 shim) and CB sdpa_paged are within noise**:
+   422 vs 434 tok/s. At this scale the attention kernel is not the bottleneck;
+   Python-side launch overhead on `_generation_step` dominates (confirmed by
+   prior profile: ~16k `cuLaunchKernelEx` for 371 decoded tokens). CUDA graph
+   replay (Phase 3) is the right lever.
+
+4. **Unsloth `fi_false` reached max_new_tokens on every prompt** (`n_decoded =
+   16384 = 32 × 512`) whereas vLLM / CB stopped some sequences on EOS
+   (`~15000 decoded`). Equivalence sampling + greedy-ish settings means most
+   completions are long, but the slight difference is worth noting when
+   reading the raw tok/s numbers.
+
+5. Completions are qualitatively coherent in every backend (see
+   `sample_completions` in the stats JSONs). vLLM and unsloth_fi_false produce
+   the *same* opening tokens on probe prompts (deterministic sampling lower
+   bound), which is a useful weak sanity check.
+
+## Raw stats
+
+- `scripts/benchmarks/results/stats/lora_vllm_gen.json`
+- `scripts/benchmarks/results/stats/lora_unsloth_fi_false_gen.json`
+- `scripts/benchmarks/results/stats/lora_cb_paged_fa4_gen.json`
+- `scripts/benchmarks/results/stats/lora_cb_sdpa_paged_gen.json`
+
+## Downstream implication
+
+Phase 2 (full GRPO training) will include `unsloth_fi_false` as a first-class
+backend — if throughput parity holds end-to-end, it may be the pragmatic
+default for teams that cannot take the vLLM memory footprint. Phase 3 (CB sync
+driver + CUDA graphs) targets the CB paths specifically.

scripts/benchmarks/results/notebook_ref_10.md

@@ -0,0 +1,54 @@
+# Phase 0 reference run: canonical Unsloth Qwen3-4B GRPO notebook (10 steps)
+
+Reproduction of `Qwen3_(4B)-GRPO.ipynb` with three deviations for the backend
+comparison downstream:
+
+1. `max_steps = 10` (vibe check; 30 and 100 follow in Phase 2).
+2. Equivalence-friendly sampling: `temperature=0.1, top_p=0.97, min_p=0.5,
+   top_k=5`. Low variance so KL / reward trajectories across backends can be
+   compared tightly.
+3. `StatisticsCallback` logs per-step loss, reward, KL, grad-norm, memory, and
+   wall time to `logs/notebook_ref_10.json`.
+
+SFT format-priming stage is skipped with `--skip_sft_pre_finetune` — this run
+is just the GRPO phase.
+
+Config:
+- GPU 6 (B200, bf16)
+- Model: `unsloth/Qwen3-4B-Base`, LoRA rank 32 on all proj layers
+- `num_generations=4`, `per_device_train_batch_size=1` (TRL enforces
+  `pdb * grad_accum * world = multiple of num_generations`, so effective batch
+  is 4 × 1)
+- `gpu_memory_utilization=0.85`
+
+## Per-step results
+
+| step | loss    | reward  | kl      | grad_norm | time(s) | mem(GB) |
+|------|---------|---------|---------|-----------|---------|---------|
+| 1    |  0.2423 | -0.875  | 0.00000 | 0.245     | 60.63   | 158.9   |
+| 2    |  0.1559 | -5.500  | 0.00000 | 0.767     |  3.89   | 157.0   |
+| 3    | -0.1650 | -0.500  | 0.00383 | 0.480     |  7.93   | 158.2   |
+| 4    |  0.3177 | -4.125  | 0.00591 | 0.379     | 11.08   | 158.9   |
+| 5    | -0.0200 |  3.125  | 0.01598 | 0.341     |  2.68   | 156.7   |
+| 6    |  0.0000 | -7.500  | 0.00396 | 0.000     | 10.65   | 158.9   |
+| 7    |  0.0000 | -7.500  | 0.00965 | 0.000     |  4.47   | 157.2   |
+| 8    |  0.0613 | -6.500  | 0.00319 | 0.172     |  5.81   | 157.6   |
+| 9    |  0.0060 | -0.500  | 0.00240 | 0.048     |  4.30   | 157.1   |
+| 10   |  0.1582 | -1.500  | 0.00485 | 0.394     |  6.78   | 157.9   |
+
+**Summary:**
+- Median step wall (steps 4-10): **5.80 s**
+- Total train wall: ~118 s
+- Peak memory: **158.9 GB**
+- KL trajectory: monotonic rise from 0 to ~0.016 by step 5, settles at
+  ~0.005 afterward — consistent with the policy drift being bounded by the KL
+  term.
+- Step 1 is ~60 s because it amortizes the vLLM CUDA-graph capture; the
+  post-warmup median is what Phase 2 will compare against.
+
+## Phase 2 use
+
+This is the gold reference. Every other backend's loss / reward / KL arrays
+will be diffed against this one (see `torch_debugging_utils.compare_training_runs`).
+Throughput numbers are on a separate axis: even an equivalence-passing backend
+that is 3x slower than this is useful information for the PR writeup.

scripts/benchmarks/unsloth_grpo_common.py

@@ -0,0 +1,381 @@
+"""Shared helpers for the Qwen3-4B GRPO comparison scripts.
+
+Exports:
+    REASONING_START, REASONING_END, SOLUTION_START, SOLUTION_END, SYSTEM_PROMPT
+    CHAT_TEMPLATE
+    build_dataset(tokenizer, max_seq_length=2048)
+    build_reward_funcs(tokenizer)
+    build_grpo_kwargs(tokenizer, maximum_length, max_seq_length)
+    StepTimer  (TrainerCallback recording per-step wall time, loss, reward)
+    write_stats(path, backend, timer, ...)
+    install_vllm_sampling_shim()
+
+Keeps dataset loading, chat template, formatting rewards, and GRPO hparams
+identical between the vLLM baseline script and the transformers-CB candidate.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+
+import numpy as np
+import pandas as pd
+from datasets import Dataset, load_dataset
+
+
+REASONING_START = "<start_working_out>"
+REASONING_END = "<end_working_out>"
+SOLUTION_START = "<SOLUTION>"
+SOLUTION_END = "</SOLUTION>"
+
+SYSTEM_PROMPT = (
+    "You are given a problem.\n"
+    "Think about the problem and provide your working out.\n"
+    f"Place it between {REASONING_START} and {REASONING_END}.\n"
+    f"Then, provide your solution between {SOLUTION_START}{SOLUTION_END}"
+)
+
+
+CHAT_TEMPLATE = (
+    "{% if messages[0]['role'] == 'system' %}"
+    "{{ messages[0]['content'] + eos_token }}"
+    "{% set loop_messages = messages[1:] %}"
+    "{% else %}"
+    "{{ '%%%SYSTEM_PROMPT%%%' + eos_token }}"
+    "{% set loop_messages = messages %}"
+    "{% endif %}"
+    "{% for message in loop_messages %}"
+    "{% if message['role'] == 'user' %}"
+    "{{ message['content'] }}"
+    "{% elif message['role'] == 'assistant' %}"
+    "{{ message['content'] + eos_token }}"
+    "{% endif %}"
+    "{% endfor %}"
+    "{% if add_generation_prompt %}{{ '%%%REASONING_START%%%' }}"
+    "{% endif %}"
+)
+
+
+def apply_chat_template_to_tokenizer(tokenizer):
+    tmpl = CHAT_TEMPLATE.replace("%%%SYSTEM_PROMPT%%%", SYSTEM_PROMPT)
+    tmpl = tmpl.replace("%%%REASONING_START%%%", REASONING_START)
+    tokenizer.chat_template = tmpl
+    return tokenizer
+
+
+def build_dataset(tokenizer, *, max_seq_length: int = 2048):
+    """Build the DAPO-Math-17k GRPO dataset with the prompt formatting from the
+    notebook. Returns `(dataset, maximum_prompt_length)`.
+    """
+    ds = load_dataset("open-r1/DAPO-Math-17k-Processed", "en", split = "train")
+
+    def _map_row(x):
+        return {
+            "prompt": [
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": x["prompt"]},
+            ],
+            "answer": x["solution"],
+        }
+
+    ds = ds.map(_map_row)
+
+    # Tokenize for length measurement (batched for speed).
+    def _tokenize(batch):
+        return {
+            "tokens": tokenizer.apply_chat_template(
+                batch["prompt"],
+                add_generation_prompt = True,
+                tokenize = True,
+            )
+        }
+
+    tokenized = ds.map(_tokenize, batched = True)
+    tokenized = tokenized.map(lambda x: {"L": len(x["tokens"])})
+    lengths = np.array(tokenized["L"])
+    maximum_length = int(np.quantile(lengths, 0.9))
+    ds = ds.select(np.where(lengths <= maximum_length)[0])
+    return ds, maximum_length
+
+
+def build_reward_funcs(tokenizer):
+    """Return the 4 reward functions used in the notebook, wired to `tokenizer`."""
+    solution_end_regex = (
+        r"</SOLUTION>[\s]{0,}" + "(?:" + re.escape(tokenizer.eos_token) + ")?"
+    )
+    match_format = re.compile(
+        rf"{REASONING_END}.*?"
+        rf"{SOLUTION_START}(.+?){solution_end_regex}"
+        rf"[\s]{{0,}}$",
+        flags = re.MULTILINE | re.DOTALL,
+    )
+    match_numbers = re.compile(
+        SOLUTION_START + r".*?[\s]{0,}([-]?[\d\.\,]{1,})",
+        flags = re.MULTILINE | re.DOTALL,
+    )
+
+    def match_format_exactly(completions, **kwargs):
+        scores = []
+        for completion in completions:
+            score = 0.0
+            response = completion[0]["content"]
+            if match_format.search(response) is not None:
+                score += 3.0
+            scores.append(score)
+        return scores
+
+    def match_format_approximately(completions, **kwargs):
+        scores = []
+        for completion in completions:
+            score = 0.0
+            response = completion[0]["content"]
+            score += 0.5 if response.count(REASONING_END) == 1 else -1.0
+            score += 0.5 if response.count(SOLUTION_START) == 1 else -1.0
+            score += 0.5 if response.count(SOLUTION_END) == 1 else -1.0
+            scores.append(score)
+        return scores
+
+    def check_answer(prompts, completions, answer, **kwargs):
+        responses = [c[0]["content"] for c in completions]
+        extracted = [
+            guess.group(1) if (guess := match_format.search(r)) is not None else None
+            for r in responses
+        ]
+        scores = []
+        for guess, true_answer in zip(extracted, answer):
+            score = 0.0
+            if guess is None:
+                scores.append(-2.0)
+                continue
+            if guess == true_answer:
+                score += 5.0
+            elif guess.strip() == true_answer.strip():
+                score += 3.5
+            else:
+                try:
+                    ratio = float(guess) / float(true_answer)
+                    if 0.9 <= ratio <= 1.1:
+                        score += 2.0
+                    elif 0.8 <= ratio <= 1.2:
+                        score += 1.5
+                    else:
+                        score -= 2.5
+                except Exception:
+                    score -= 4.5
+            scores.append(score)
+        return scores
+
+    _printed_state = {"n": 0, "every": 5}
+
+    def check_numbers(prompts, completions, answer, **kwargs):
+        question = prompts[0][-1]["content"]
+        responses = [c[0]["content"] for c in completions]
+        extracted = [
+            guess.group(1) if (guess := match_numbers.search(r)) is not None else None
+            for r in responses
+        ]
+        if _printed_state["n"] % _printed_state["every"] == 0:
+            print(
+                "*" * 20 + f"Question:\n{question}",
+                f"\nAnswer:\n{answer[0]}",
+                f"\nResponse:\n{responses[0]}",
+                f"\nExtracted:\n{extracted[0]}",
+            )
+        _printed_state["n"] += 1
+
+        scores = []
+        for guess, true_answer in zip(extracted, answer):
+            if guess is None:
+                scores.append(-2.5)
+                continue
+            try:
+                t = float(true_answer.strip())
+                g = float(guess.strip().replace(",", ""))
+                scores.append(3.5 if g == t else -1.5)
+            except Exception:
+                scores.append(0.0)
+        return scores
+
+    return [
+        match_format_exactly,
+        match_format_approximately,
+        check_answer,
+        check_numbers,
+    ]
+
+
+def build_grpo_kwargs(
+    tokenizer,
+    maximum_length: int,
+    *,
+    max_seq_length: int = 2048,
+    max_steps: int = 100,
+    num_generations: int = 4,
+    per_device_train_batch_size: int = 1,
+    gradient_accumulation_steps: int = 1,
+    output_dir: str = "outputs",
+):
+    """Return the shared dict of GRPOConfig kwargs used by both backends.
+
+    Caller adds backend-specific keys (use_vllm / use_transformers_paged / etc).
+    """
+    max_prompt_length = maximum_length + 1
+    max_completion_length = max_seq_length - max_prompt_length
+
+    return dict(
+        temperature = 1.0,
+        top_p = 1.0,
+        top_k = -1,
+        min_p = 0.1,
+        learning_rate = 5e-6,
+        weight_decay = 0.001,
+        warmup_ratio = 0.1,
+        lr_scheduler_type = "linear",
+        optim = "adamw_8bit",
+        logging_steps = 1,
+        per_device_train_batch_size = per_device_train_batch_size,
+        gradient_accumulation_steps = gradient_accumulation_steps,
+        num_generations = num_generations,
+        max_prompt_length = max_prompt_length,
+        max_completion_length = max_completion_length,
+        max_steps = max_steps,
+        save_steps = max_steps,
+        report_to = "none",
+        output_dir = output_dir,
+        seed = 3407,
+    )
+
+
+import torch
+from transformers import TrainerCallback
+
+
+class StepTimer(TrainerCallback):
+    """Per-step wall time / loss / reward recorder.
+
+    Shared verbatim across qwen3_grpo_{vllm,naive,tpaged}. Records step wall
+    time in `self.step_wall`, and picks up `loss` / `reward` from the TRL log
+    dict in `on_log`.
+    """
+
+    def __init__(self):
+        self.t0 = None
+        self.step_wall = []
+        self.loss = []
+        self.reward = []
+
+    def on_step_begin(self, _args, state, control, **kwargs):
+        torch.cuda.synchronize()
+        self.t0 = time.perf_counter()
+
+    def on_log(self, _args, state, control, logs = None, **kwargs):
+        if logs is None:
+            return
+        if "loss" in logs:
+            self.loss.append(float(logs["loss"]))
+        if "reward" in logs:
+            self.reward.append(float(logs["reward"]))
+
+    def on_step_end(self, _args, state, control, **kwargs):
+        if self.t0 is not None:
+            torch.cuda.synchronize()
+            self.step_wall.append(time.perf_counter() - self.t0)
+
+
+def write_stats(
+    path: str,
+    backend: str,
+    timer: StepTimer,
+    *,
+    train_wall_s: float,
+    peak_memory_gb: float,
+    max_prompt_length: int,
+    max_completion_length: int,
+    num_generations: int,
+    max_steps: int,
+    extra: dict | None = None,
+) -> None:
+    """Dump the per-step stats dict used by all three GRPO drivers.
+
+    Schema matches the pre-refactor output exactly: `backend`, `train_wall_s`,
+    `peak_memory_gb`, `step_wall_s`, `losses`, `rewards`, `max_prompt_length`,
+    `max_completion_length`, `num_generations`, `max_steps`, plus any
+    backend-specific keys passed in `extra` (e.g. `attn_impl`, `persistent_cb`).
+    """
+    stats = {
+        "backend": backend,
+        "train_wall_s": train_wall_s,
+        "peak_memory_gb": peak_memory_gb,
+        "step_wall_s": timer.step_wall,
+        "losses": timer.loss,
+        "rewards": timer.reward,
+        "max_prompt_length": max_prompt_length,
+        "max_completion_length": max_completion_length,
+        "num_generations": num_generations,
+        "max_steps": max_steps,
+    }
+    if extra:
+        stats.update(extra)
+    with open(path, "w") as f:
+        json.dump(stats, f, indent = 2)
+
+
+def maybe_compile_trainer_forwards(
+    trainer, compile_mode, *, dynamic: bool = True, tag: str = ""
+):
+    """torch.compile wrap `trainer.model.forward` and (if present)
+    `trainer.ref_model.forward`. No-op if `compile_mode` is falsy.
+
+    Ported from the old `qwen3_grpo_unified.py` compile path, minus the
+    out-of-tree `torch_debugging_utils` imports that were dev-only.
+    """
+    if not compile_mode:
+        return
+    import torch._dynamo
+
+    torch._dynamo.config.cache_size_limit = 128
+    try:
+        torch._dynamo.config.allow_unspec_int_on_nn_module = True
+    except AttributeError:
+        pass
+    prefix = f"[{tag}] " if tag else ""
+    print(
+        f"{prefix}Compiling trainer.model.forward (mode={compile_mode}, dynamic={dynamic})"
+    )
+    trainer.model.forward = torch.compile(
+        trainer.model.forward,
+        mode = compile_mode,
+        dynamic = dynamic,
+    )
+    ref = getattr(trainer, "ref_model", None)
+    if ref is not None:
+        ref.forward = torch.compile(
+            ref.forward,
+            mode = compile_mode,
+            dynamic = dynamic,
+        )
+
+
+def install_vllm_sampling_shim():
+    """Shim `vllm.sampling_params.GuidedDecodingParams` for newer vLLM releases.
+
+    TRL's `GRPOTrainer` imports `GuidedDecodingParams` from
+    `vllm.sampling_params`; newer vLLM versions have moved or removed it. Inject
+    a no-op class so the import succeeds even on the non-vLLM training paths
+    (naive, tpaged). No-op if vLLM is not installed or already exposes the
+    symbol.
+    """
+    try:
+        import vllm.sampling_params as _vllm_sp
+    except ImportError:
+        return
+    if hasattr(_vllm_sp, "GuidedDecodingParams"):
+        return
+
+    class _GuidedDecodingParamsShim:  # pragma: no cover - used only if TRL asks
+        def __init__(self, *a, **kw):
+            pass
+
+    _vllm_sp.GuidedDecodingParams = _GuidedDecodingParamsShim

scripts/benchmarks/verify_gemma4_numerics.py

@@ -0,0 +1,149 @@
+"""Compare first-token logits between `FlexGemma4Inference._prefill` and
+vanilla `Gemma4ForCausalLM.forward` on the same prompt. Intended as a
+one-shot correctness check; not part of the benchmark matrix.
+
+Run:
+    CUDA_VISIBLE_DEVICES=2 python scripts/benchmarks/verify_gemma4_numerics.py
+"""
+
+from __future__ import annotations
+
+import copy
+import sys
+from pathlib import Path
+
+import torch
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+
+from gemma4_flex_inference import (  # noqa: E402
+    FlexGemma4Inference,
+    Sequence,
+    _require_gemma4,
+)
+
+
+def main():
+    Gemma4ForCausalLM, Gemma4Config, Gemma4TextConfig = _require_gemma4()
+    from transformers.models.gemma4.modeling_gemma4 import (
+        Gemma4ForConditionalGeneration,
+    )
+    from transformers import AutoTokenizer
+
+    name = "unsloth/gemma-4-E2B-it"
+    tok = AutoTokenizer.from_pretrained(name)
+    if tok.pad_token is None:
+        tok.pad_token = tok.eos_token
+
+    full_cfg = Gemma4Config.from_pretrained(name)
+    text_cfg = full_cfg.text_config
+
+    # Untouched HF reference: `Gemma4ForConditionalGeneration.forward` --
+    # the same class everyone else would load via AutoModelForCausalLM
+    # for Gemma-4. No patching, no shell, no flex attention.
+    ref_raw = Gemma4ForConditionalGeneration.from_pretrained(
+        name, dtype = torch.bfloat16, attn_implementation = "eager"
+    ).to("cuda")
+    ref_raw.eval()
+
+    # Shell copy used by `gemma4_flex_inference.main()`: we deep-copy the
+    # loaded multimodal model, drop the vision + audio towers, and move
+    # the language_model into a Gemma4ForCausalLM wrapper so PEFT and
+    # state-dict hashing treat it as a decoder-only model. The flex path
+    # then patches its attention forwards on this shell. We keep the
+    # shell around both as (a) the model that gets flex-patched and
+    # (b) a sanity check that the shell itself matches the raw HF path.
+    full = Gemma4ForConditionalGeneration.from_pretrained(
+        name, dtype = torch.bfloat16, attn_implementation = "eager"
+    )
+    lang = full.model.language_model
+    full.model.vision_tower = None
+    full.model.audio_tower = None
+    full.model.embed_vision = None
+    full.model.embed_audio = None
+
+    shell = Gemma4ForCausalLM(text_cfg)
+    shell.model = lang
+    shell.lm_head.weight = lang.embed_tokens.weight
+    shell = shell.to(torch.bfloat16).to("cuda")
+    shell.eval()
+    del full
+
+    # Deep-copy so Flex's attention patching doesn't mutate the shell.
+    flex_model = copy.deepcopy(shell)
+
+    prompt = "The quick brown fox jumps over"
+    ids = tok(prompt, return_tensors = "pt")["input_ids"].to("cuda")
+    print(f"prompt len = {ids.shape[1]}")
+
+    with torch.inference_mode():
+        # `Gemma4ForConditionalGeneration.forward` applies
+        # `final_logit_softcapping` internally.
+        ref_logits = ref_raw(input_ids = ids, use_cache = False).logits[0, -1, :].float()
+        shell_logits = shell(ids, use_cache = False).logits[0, -1, :].float()
+    print(
+        f"raw   Gemma4ForConditionalGeneration: mean {ref_logits.mean():.4f}, "
+        f"std {ref_logits.std():.4f}, argmax {int(ref_logits.argmax())} "
+        f"({tok.decode([int(ref_logits.argmax())])!r})"
+    )
+    print(
+        f"shell Gemma4ForCausalLM(text_cfg)    : mean {shell_logits.mean():.4f}, "
+        f"std {shell_logits.std():.4f}, argmax {int(shell_logits.argmax())}"
+    )
+    # Dispose of the raw multimodal model before we build FlexGemma4Inference.
+    del ref_raw
+    torch.cuda.empty_cache()
+
+    # Flex path.
+    inf = FlexGemma4Inference(
+        flex_model,
+        tok,
+        max_batch_size = 4,
+        max_seq_length = 256,
+        n_pages = 64,
+        page_size = 64,
+        max_new_tokens = 1,
+        decode_kernel_options = {"BLOCK_M": 16, "BLOCK_N": 16},
+        prefill_kernel_options = {
+            "FORCE_USE_FLEX_ATTENTION": True,
+            "BLOCK_M": 32,
+            "BLOCK_N": 32,
+        },
+        fa4_prefill = False,
+    )
+    seq = Sequence(text = prompt, max_new_tokens = 1)
+    inf.tokenize([seq])
+    bi = inf.page_table.allocate()
+    inf.page_table.reserve(
+        bi,
+        torch.tensor([bi], device = "cuda", dtype = torch.long),
+        seq.total_length,
+    )
+    seq.batch_idx = bi
+    with torch.inference_mode():
+        flex_logits = inf._prefill([seq])[0].float()
+    print(
+        f"flex  last-token logits              : mean {flex_logits.mean():.4f}, "
+        f"std {flex_logits.std():.4f}, argmax {int(flex_logits.argmax())} "
+        f"({tok.decode([int(flex_logits.argmax())])!r})"
+    )
+
+    def report(tag, a, b):
+        diff = (a - b).abs()
+        top_a = set(a.topk(10).indices.tolist())
+        top_b = set(b.topk(10).indices.tolist())
+        print(
+            f"  {tag:14s} max {diff.max().item():.3e}  mean {diff.mean().item():.3e}  "
+            f"argmax={int(a.argmax()) == int(b.argmax())}  top-10={len(top_a & top_b)}/10"
+        )
+
+    print("vs raw Gemma4ForConditionalGeneration:")
+    report("shell vs raw", shell_logits, ref_logits)
+    report("flex  vs raw", flex_logits, ref_logits)
+    print("vs shell (Gemma4ForCausalLM wrapper):")
+    report("flex  vs shell", flex_logits, shell_logits)
+
+
+if __name__ == "__main__":
+    main()

scripts/benchmarks/verify_qwen3_numerics.py

@@ -0,0 +1,94 @@
+"""Compare first-token logits between FlexInference._prefill (qwen3 path)
+and vanilla model(input_ids) for Qwen3 and Llama-3.2.
+
+Run:
+    CUDA_VISIBLE_DEVICES=2 python scripts/benchmarks/verify_qwen3_numerics.py \
+        --model_name unsloth/Qwen3-4B-Base
+    CUDA_VISIBLE_DEVICES=2 python scripts/benchmarks/verify_qwen3_numerics.py \
+        --model_name unsloth/Llama-3.2-3B-Instruct
+"""
+
+from __future__ import annotations
+
+import argparse
+import copy
+import sys
+from pathlib import Path
+
+import torch
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+
+from qwen3_flex_inference import FlexInference, Sequence  # noqa: E402
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("--model_name", required = True)
+    p.add_argument("--prompt", default = "The quick brown fox jumps over")
+    args = p.parse_args()
+
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+
+    tok = AutoTokenizer.from_pretrained(args.model_name)
+    if tok.pad_token is None:
+        tok.pad_token = tok.eos_token
+
+    base = AutoModelForCausalLM.from_pretrained(
+        args.model_name, dtype = torch.bfloat16, attn_implementation = "eager"
+    ).to("cuda")
+    base.eval()
+
+    flex_model = copy.deepcopy(base)
+
+    ids = tok(args.prompt, return_tensors = "pt")["input_ids"].to("cuda")
+    print(f"prompt len = {ids.shape[1]}")
+
+    with torch.inference_mode():
+        out = base(ids, use_cache = False)
+        ref_logits = out.logits[0, -1, :].float()
+    print(
+        f"vanilla last-token logits: mean {ref_logits.mean().item():.4f}, "
+        f"std {ref_logits.std().item():.4f}, argmax {int(ref_logits.argmax())} "
+        f"({tok.decode([int(ref_logits.argmax())])!r})"
+    )
+
+    inf = FlexInference(
+        flex_model,
+        tok,
+        max_batch_size = 4,
+        max_seq_length = 256,
+        n_pages = 64,
+        page_size = 64,
+        max_new_tokens = 1,
+        fa4_prefill = False,
+    )
+    seq = Sequence(text = args.prompt, max_new_tokens = 1)
+    inf.tokenize([seq])
+    bi = inf.page_table.allocate()
+    inf.page_table.reserve(
+        bi,
+        torch.tensor([bi], device = "cuda", dtype = torch.long),
+        seq.total_length,
+    )
+    seq.batch_idx = bi
+    with torch.inference_mode():
+        flex_logits = inf._prefill([seq])[0].float()
+    print(
+        f"flex    last-token logits: mean {flex_logits.mean().item():.4f}, "
+        f"std {flex_logits.std().item():.4f}, argmax {int(flex_logits.argmax())} "
+        f"({tok.decode([int(flex_logits.argmax())])!r})"
+    )
+
+    diff = (flex_logits - ref_logits).abs()
+    print(f"max abs diff   = {diff.max().item():.4e}")
+    print(f"mean abs diff  = {diff.mean().item():.4e}")
+    print(f"argmax match   = {int(ref_logits.argmax()) == int(flex_logits.argmax())}")
+    top_ref = set(ref_logits.topk(10).indices.tolist())
+    top_flex = set(flex_logits.topk(10).indices.tolist())
+    print(f"top-10 overlap = {len(top_ref & top_flex)} / 10")
+
+
+if __name__ == "__main__":
+    main()

scripts/build_whisper_cpp.sh

@@ -1,71 +0,0 @@
-#!/bin/sh
-# Build whisper.cpp's whisper-server for Studio's GGUF dictation engine.
-#
-# Installs into the managed Studio home so the backend's binary discovery
-# (core/inference/stt_ggml_sidecar.py::find_whisper_server_binary) picks it up:
-#   <UNSLOTH_STUDIO_HOME>/whisper.cpp/build/bin/whisper-server   (custom home)
-#   ~/.unsloth/whisper.cpp/build/bin/whisper-server              (default)
-#
-# Usage:
-#   ./scripts/build_whisper_cpp.sh              # build the pinned tag
-#   WHISPER_CPP_TAG=v1.9.0 ./scripts/build_whisper_cpp.sh
-#
-# Requires: git, cmake, a C/C++ toolchain (the same prerequisites as a
-# llama.cpp source build). GPU backends are auto-detected by whisper.cpp's
-# CMake (Metal on macOS; set GGML_CUDA=1 to force a CUDA build on Linux).
-
-set -eu
-
-WHISPER_CPP_SOURCE="${WHISPER_CPP_SOURCE:-https://github.com/ggml-org/whisper.cpp}"
-WHISPER_CPP_TAG="${WHISPER_CPP_TAG:-v1.9.1}"
-
-STUDIO_HOME="${UNSLOTH_STUDIO_HOME:-${STUDIO_HOME:-}}"
-CUSTOM_STUDIO_HOME=false
-if [ -n "$STUDIO_HOME" ]; then
-    CUSTOM_STUDIO_HOME=true
-    INSTALL_DIR="$STUDIO_HOME/whisper.cpp"
-else
-    INSTALL_DIR="$HOME/.unsloth/whisper.cpp"
-fi
-
-command -v git >/dev/null 2>&1 || { echo "ERROR: git is required" >&2; exit 1; }
-command -v cmake >/dev/null 2>&1 || { echo "ERROR: cmake is required" >&2; exit 1; }
-
-# Same policy as studio/setup.sh's _assert_studio_owned_or_absent: never delete
-# a directory under a custom Studio home unless Studio itself created it (the
-# marker file below). Protects a user-managed whisper.cpp/src from rm -rf.
-STUDIO_OWNED_MARKER=".unsloth-studio-owned"
-if [ "$CUSTOM_STUDIO_HOME" = true ] && [ -e "$INSTALL_DIR" ] && \
-   [ ! -f "$INSTALL_DIR/$STUDIO_OWNED_MARKER" ]; then
-    echo "ERROR: $INSTALL_DIR already exists and is not marked as an Unsloth-owned whisper.cpp build tree." >&2
-    echo "       Move it aside or choose an empty UNSLOTH_STUDIO_HOME before re-running." >&2
-    exit 1
-fi
-
-echo "==> Building whisper.cpp ($WHISPER_CPP_TAG) into $INSTALL_DIR"
-mkdir -p "$INSTALL_DIR"
-: > "$INSTALL_DIR/$STUDIO_OWNED_MARKER"
-
-if [ ! -d "$INSTALL_DIR/src/.git" ]; then
-    rm -rf "$INSTALL_DIR/src"
-    git clone --depth 1 --branch "$WHISPER_CPP_TAG" "$WHISPER_CPP_SOURCE" "$INSTALL_DIR/src"
-else
-    git -C "$INSTALL_DIR/src" fetch --depth 1 origin "$WHISPER_CPP_TAG"
-    git -C "$INSTALL_DIR/src" checkout FETCH_HEAD
-fi
-
-CMAKE_FLAGS="-DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF"
-if [ "${GGML_CUDA:-0}" = "1" ]; then
-    CMAKE_FLAGS="$CMAKE_FLAGS -DGGML_CUDA=ON"
-fi
-
-# shellcheck disable=SC2086
-cmake -S "$INSTALL_DIR/src" -B "$INSTALL_DIR/src/build" $CMAKE_FLAGS
-NCPU="$(getconf _NPROCESSORS_ONLN 2>/dev/null || echo 4)"
-cmake --build "$INSTALL_DIR/src/build" --config Release --target whisper-server -j"$NCPU"
-
-mkdir -p "$INSTALL_DIR/build/bin"
-cp "$INSTALL_DIR/src/build/bin/whisper-server" "$INSTALL_DIR/build/bin/whisper-server"
-
-echo "==> Installed $INSTALL_DIR/build/bin/whisper-server"
-"$INSTALL_DIR/build/bin/whisper-server" --help >/dev/null 2>&1 && echo "==> Binary runs OK"

scripts/check_new_install_scripts.py

@@ -1,242 +0,0 @@
-#!/usr/bin/env python3
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-"""Diff two `package-lock.json` files and flag NEW install-script deps.
-
-A `"hasInstallScript": true` package runs preinstall/install/postinstall
-hooks on every `npm ci` -- the lever behind recent npm supply-chain
-compromises (attacker publishes a malicious version of a trusted dep).
-This refuses to land a newly-introduced install-script dep without a
-maintainer eyeball; pre-existing ones are not re-flagged.
-
-Supports lockfileVersion 1 (recursive `dependencies`) and 2/3 (flat
-`packages` with `node_modules/.../node_modules/...` nesting). For each
-new entry we best-effort fetch the registry metadata to recover the
-postinstall command body; the finding is still emitted if unreachable.
-
-Exit codes: 0 = none; 1 = one or more (on stderr); 2 = internal error.
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-import urllib.error
-import urllib.parse
-import urllib.request
-from pathlib import Path
-
-REGISTRY_BASE = "https://registry.npmjs.org/"
-REGISTRY_TIMEOUT_SECS = 5
-
-CRITICAL = "CRITICAL"
-HIGH = "HIGH"
-
-
-class Finding:
-    __slots__ = ("severity", "name", "version", "kind", "detail")
-
-    def __init__(self, severity: str, name: str, version: str, kind: str, detail: str) -> None:
-        self.severity = severity
-        self.name = name
-        self.version = version
-        self.kind = kind
-        self.detail = detail
-
-    def __str__(self) -> str:
-        return (
-            f"  [{self.severity}] {self.name}@{self.version}\n"
-            f"    kind:   {self.kind}\n"
-            f"    detail: {self.detail}"
-        )
-
-
-# Lockfile parsing.
-
-
-def _strip_nm_prefix(key: str) -> str:
-    """Convert a v2/v3 `packages` key into a bare package name (leaf after last `node_modules/`)."""
-    if not key:
-        return ""
-    # LAST node_modules/ segment so transitives map to their leaf name.
-    marker = "node_modules/"
-    idx = key.rfind(marker)
-    if idx == -1:
-        return key
-    return key[idx + len(marker) :]
-
-
-def _collect_install_script_entries(lock: dict) -> dict[str, str]:
-    """Return {name@version: name} for entries with hasInstallScript (v2/v3) or a lifecycle script (v1).
-
-    Keyed by name@version so dup copies at different versions aren't lost.
-    """
-    seen: dict[str, str] = {}
-    version = lock.get("lockfileVersion")
-
-    # v2 / v3: flat `packages` map.
-    packages = lock.get("packages") or {}
-    for key, entry in packages.items():
-        if key == "" or not isinstance(entry, dict):
-            continue
-        if entry.get("link"):
-            continue
-        if not entry.get("hasInstallScript"):
-            continue
-        name = _strip_nm_prefix(key)
-        if not name:
-            continue
-        ver = entry.get("version") or "<unversioned>"
-        seen[f"{name}@{ver}"] = name
-
-    # v1 has no hasInstallScript flag; detect lifecycle scripts directly.
-    def _walk_v1(deps: dict, depth: int = 0) -> None:
-        if depth > 64 or not isinstance(deps, dict):
-            return
-        for name, entry in deps.items():
-            if not isinstance(entry, dict):
-                continue
-            scripts = entry.get("scripts") or {}
-            lifecycle = any(
-                isinstance(scripts, dict) and scripts.get(hook)
-                for hook in ("preinstall", "install", "postinstall")
-            )
-            if lifecycle:
-                ver = entry.get("version") or "<unversioned>"
-                seen[f"{name}@{ver}"] = name
-            _walk_v1(entry.get("dependencies"), depth = depth + 1)
-
-    if version == 1 or "dependencies" in lock:
-        _walk_v1(lock.get("dependencies") or {})
-
-    return seen
-
-
-def _load_lockfile(path: Path) -> dict:
-    if not path.exists():
-        raise FileNotFoundError(f"lockfile not found: {path}")
-    try:
-        return json.loads(path.read_text(encoding = "utf-8"))
-    except json.JSONDecodeError as exc:
-        raise ValueError(f"{path}: not valid JSON: {exc}") from exc
-
-
-# Registry lookup for the postinstall command body (best-effort).
-
-
-def _fetch_registry_scripts(name: str, version: str) -> dict[str, str] | None:
-    """Return {hook: command} for lifecycle hooks in registry metadata; None on any error (never raises)."""
-    safe_name = urllib.parse.quote(name, safe = "@/")
-    url = f"{REGISTRY_BASE}{safe_name}/{urllib.parse.quote(version)}"
-    try:
-        with urllib.request.urlopen(url, timeout = REGISTRY_TIMEOUT_SECS) as resp:
-            body = resp.read()
-    except (urllib.error.URLError, OSError, ValueError, TimeoutError):
-        return None
-    try:
-        meta = json.loads(body)
-    except json.JSONDecodeError:
-        return None
-    scripts = meta.get("scripts") or {}
-    if not isinstance(scripts, dict):
-        return None
-    keep = {}
-    for hook in ("preinstall", "install", "postinstall"):
-        cmd = scripts.get(hook)
-        if isinstance(cmd, str) and cmd.strip():
-            keep[hook] = cmd
-    return keep or None
-
-
-# Diff.
-
-
-def diff_new_install_scripts(base_lock: dict, head_lock: dict) -> list[Finding]:
-    base = _collect_install_script_entries(base_lock)
-    head = _collect_install_script_entries(head_lock)
-    findings: list[Finding] = []
-    for key in sorted(head):
-        if key in base:
-            continue  # pre-existing install-script dep; not in scope
-        name = head[key]
-        version = key[len(name) + 1 :] if key.startswith(name + "@") else "<unversioned>"
-        scripts = _fetch_registry_scripts(name, version)
-        if scripts:
-            detail = "; ".join(f"{h}={cmd!r}" for h, cmd in scripts.items())
-        else:
-            detail = (
-                "newly added with hasInstallScript=true; registry "
-                "metadata unreachable -- inspect the package's "
-                "scripts.{preinstall,install,postinstall} manually"
-            )
-        findings.append(
-            Finding(
-                severity = CRITICAL,
-                name = name,
-                version = version,
-                kind = "new-install-script",
-                detail = detail,
-            )
-        )
-    return findings
-
-
-# CLI.
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(
-        description = (
-            "Diff two package-lock.json files and refuse any newly-added install-script dep."
-        ),
-    )
-    parser.add_argument(
-        "--base",
-        required = True,
-        help = "Path to the BASE package-lock.json (e.g. main branch).",
-    )
-    parser.add_argument(
-        "--head",
-        required = True,
-        help = "Path to the HEAD package-lock.json (this PR).",
-    )
-    args = parser.parse_args(argv)
-
-    try:
-        base_lock = _load_lockfile(Path(args.base))
-        head_lock = _load_lockfile(Path(args.head))
-    except (FileNotFoundError, ValueError) as exc:
-        print(f"[install-script-diff] ERROR: {exc}", file = sys.stderr)
-        return 2
-
-    findings = diff_new_install_scripts(base_lock, head_lock)
-    if not findings:
-        print(
-            "[install-script-diff] OK: no newly-added install-script "
-            "dependencies between base and head",
-            flush = True,
-        )
-        return 0
-
-    print(
-        f"\n[install-script-diff] FAIL: {len(findings)} newly-added "
-        f"install-script dependency(ies):\n",
-        file = sys.stderr,
-    )
-    for f in findings:
-        print(str(f), file = sys.stderr)
-        print(file = sys.stderr)
-    print(
-        "[install-script-diff] Refusing to proceed. Every new "
-        "install-script dep is a postinstall lifecycle hook that "
-        "would run on the next `npm ci`. Review each finding above, "
-        "confirm the maintainer + version, and re-run.",
-        file = sys.stderr,
-    )
-    return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

scripts/data/colab_os_info.gpu.txt

@@ -1,9 +0,0 @@
-# Do not modify this file directly; it is generated by extract_colabx_testing_tarballs.sh via
-#  $ (lsb_release -ds;python --version;) > os-info-gpu.txt
-# Be aware that this list does not necessarily reflect the current state of the
-# staging or production container, but rather the state as of the most recent
-# submitted CL where extract_colabx_testing_tarballs.sh was run.
-Ubuntu 22.04.5 LTS
-Python 3.12.13
-R version 4.5.3 (2026-03-11) -- "Reassured Reassurer"
-julia version 1.12.6

scripts/data/colab_pip_freeze.gpu.txt

@@ -1,731 +0,0 @@
-# Do not modify this file directly; it is generated by extract_colabx_testing_tarballs.sh via
-#  $ python3 -m pip freeze
-# Be aware that this list does not necessarily reflect the current state of the
-# staging or production container, but rather the state as of the most recent
-# submitted CL where extract_colabx_testing_tarballs.sh was run.
-absl-py==1.4.0
-accelerate==1.13.0
-access==1.1.10.post3
-affine==2.4.0
-aiofiles==24.1.0
-aiohappyeyeballs==2.6.1
-aiohttp==3.13.5
-aiosignal==1.4.0
-aiosqlite==0.22.1
-alabaster==1.0.0
-albucore==0.0.24
-albumentations==2.0.8
-ale-py==0.11.2
-alembic==1.18.4
-altair==5.5.0
-annotated-doc==0.0.4
-annotated-types==0.7.0
-antlr4-python3-runtime==4.9.3
-anyio==4.13.0
-anywidget==0.9.21
-apsw==3.53.0.0
-apswutils==0.1.2
-argon2-cffi==25.1.0
-argon2-cffi-bindings==25.1.0
-array_record==0.8.3
-arrow==1.4.0
-arviz==0.22.0
-astropy==7.2.0
-astropy-iers-data==0.2026.4.20.0.58.15
-astunparse==1.6.3
-atpublic==5.1
-attrs==26.1.0
-audioread==3.1.0
-Authlib==1.6.11
-autograd==1.8.0
-babel==2.18.0
-backcall==0.2.0
-beartype==0.22.9
-beautifulsoup4==4.13.5
-betterproto==2.0.0b6
-bigframes==2.39.0
-bigquery-magics==0.14.0
-bleach==6.3.0
-blinker==1.9.0
-blis==1.3.3
-blobfile==3.2.0
-blosc2==4.1.2
-bokeh==3.8.2
-Bottleneck==1.4.2
-bqplot==0.12.45
-branca==0.8.2
-brotli==1.2.0
-CacheControl==0.14.4
-cachetools==6.2.6
-catalogue==2.0.10
-certifi==2026.4.22
-cffi==2.0.0
-chardet==5.2.0
-charset-normalizer==3.4.7
-clarabel==0.11.1
-click==8.3.3
-click-plugins==1.1.1.2
-cligj==0.7.2
-cloudpathlib==0.23.0
-cloudpickle==3.1.2
-cmake==3.31.10
-cmdstanpy==1.3.0
-colorcet==3.1.0
-colorlover==0.3.0
-community==1.0.0b1
-confection==1.3.3
-cons==0.4.7
-contourpy==1.3.3
-cramjam==2.11.0
-cryptography==43.0.3
-cucim-cu12 @ https://pypi.nvidia.com/cucim-cu12/cucim_cu12-26.2.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
-cuda-bindings==12.9.4
-cuda-core==0.3.2
-cuda-pathfinder==1.5.3
-cuda-python==12.9.4
-cuda-toolkit==12.8.1
-cudf-cu12==26.2.1
-cudf-polars-cu12==26.2.1
-cufflinks==0.17.3
-cuml-cu12==26.2.0
-cupy-cuda12x==14.0.1
-curl_cffi==0.15.0
-cuvs-cu12 @ https://pypi.nvidia.com/cuvs-cu12/cuvs_cu12-26.2.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
-cvxopt==1.3.2
-cvxpy==1.6.7
-cycler==0.12.1
-cyipopt==1.5.0
-cymem==2.0.13
-Cython==3.0.12
-dask==2026.1.1
-dask-cuda==26.2.0
-dask-cudf-cu12==26.2.1
-dataproc-spark-connect==1.1.0
-datasets==4.0.0
-db-dtypes==1.5.1
-dbus-python==1.2.18
-debugpy==1.8.15
-decorator==4.4.2
-defusedxml==0.7.1
-deprecation==2.1.0
-diffusers==0.37.1
-dill==0.3.8
-distributed==2026.1.1
-distributed-ucxx-cu12==0.48.0
-distro==1.9.0
-dlib==19.24.6
-dm-tree==0.1.10
-docstring_parser==0.18.0
-docutils==0.21.2
-dopamine_rl==4.1.2
-duckdb==1.3.2
-earthengine-api==1.7.22
-easydict==1.13
-editdistance==0.8.1
-eerepr==0.1.2
-einops==0.8.2
-en_core_web_sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl#sha256=1932429db727d4bff3deed6b34cfc05df17794f4a52eeb26cf8928f7c1a0fb85
-entrypoints==0.4
-esda==2.9.0
-et_xmlfile==2.0.0
-etils==1.14.0
-etuples==0.3.10
-Farama-Notifications==0.0.4
-fastai==2.8.7
-fastapi==0.136.1
-fastcore==1.12.42
-fastdownload==0.0.7
-fastjsonschema==2.21.2
-fastlite==0.2.4
-fastprogress==1.1.5
-fasttransform==0.0.2
-ffmpy==1.0.0
-filelock==3.29.0
-fiona==1.10.1
-firebase-admin==6.9.0
-Flask==3.1.3
-flatbuffers==25.12.19
-flax==0.11.2
-folium==0.20.0
-fonttools==4.62.1
-fqdn==1.5.1
-frozendict==2.4.7
-frozenlist==1.8.0
-fsspec==2025.3.0
-future==1.0.0
-gast==0.7.0
-gcsfs==2025.3.0
-GDAL==3.8.4
-gdown==5.2.2
-geemap==0.37.2
-geocoder==1.38.1
-geographiclib==2.1
-geopandas==1.1.3
-geopy==2.4.1
-giddy==2.3.6
-gin-config==0.5.0
-gitdb==4.0.12
-GitPython==3.1.47
-glob2==0.7
-google==3.0.0
-google-adk==1.29.0
-google-ai-generativelanguage==0.6.15
-google-api-core==2.30.3
-google-api-python-client==2.194.0
-google-auth==2.47.0
-google-auth-httplib2==0.3.1
-google-auth-oauthlib==1.3.1
-google-cloud-aiplatform==1.148.1
-google-cloud-appengine-logging==1.9.0
-google-cloud-audit-log==0.5.0
-google-cloud-bigquery==3.41.0
-google-cloud-bigquery-connection==1.21.0
-google-cloud-bigquery-storage==2.37.0
-google-cloud-bigtable==2.36.0
-google-cloud-core==2.5.1
-google-cloud-dataplex==2.18.0
-google-cloud-dataproc==5.27.0
-google-cloud-datastore==2.24.0
-google-cloud-discoveryengine==0.13.12
-google-cloud-firestore==2.27.0
-google-cloud-functions==1.23.0
-google-cloud-iam==2.22.0
-google-cloud-language==2.20.0
-google-cloud-logging==3.15.0
-google-cloud-monitoring==2.30.0
-google-cloud-pubsub==2.37.0
-google-cloud-resource-manager==1.17.0
-google-cloud-secret-manager==2.27.0
-google-cloud-spanner==3.65.0
-google-cloud-speech==2.38.0
-google-cloud-storage==3.10.1
-google-cloud-trace==1.19.0
-google-cloud-translate==3.26.0
-google-colab @ file:///colabtools/dist/google_colab-1.0.0.tar.gz
-google-crc32c==1.8.0
-google-genai==1.68.0
-google-generativeai==0.8.6
-google-pasta==0.2.0
-google-resumable-media==2.8.2
-googleapis-common-protos==1.74.0
-googledrivedownloader==1.1.0
-gradio==5.50.0
-gradio_client==1.14.0
-grain==0.2.16
-graphviz==0.21
-greenlet==3.4.0
-groovy==0.1.2
-grpc-google-iam-v1==0.14.4
-grpc-interceptor==0.15.4
-grpcio==1.80.0
-grpcio-status==1.71.2
-grpclib==0.4.9
-gspread==6.2.1
-gspread-dataframe==4.0.0
-gym==0.25.2
-gym-notices==0.1.0
-gymnasium==1.3.0
-h11==0.16.0
-h2==4.3.0
-h5netcdf==1.8.1
-h5py==3.16.0
-hdbscan==0.8.42
-hf-xet==1.4.3
-highspy==1.14.0
-holidays==0.95
-holoviews==1.22.1
-hpack==4.1.0
-html5lib==1.1
-httpcore==1.0.9
-httpimport==1.4.1
-httplib2==0.31.2
-httptools==0.7.1
-httpx==0.28.1
-httpx-sse==0.4.3
-huggingface_hub==1.11.0
-humanize==4.15.0
-hyperframe==6.1.0
-hyperopt==0.2.7
-ibis-framework==9.5.0
-idna==3.13
-ImageIO==2.37.3
-imageio-ffmpeg==0.6.0
-imagesize==2.0.0
-imbalanced-learn==0.14.1
-immutabledict==4.3.1
-importlib_metadata==8.7.1
-importlib_resources==7.1.0
-imutils==0.5.4
-inequality==1.1.2
-inflect==7.5.0
-iniconfig==2.3.0
-intel-cmplr-lib-ur==2025.3.3
-intel-openmp==2025.3.3
-ipyevents==2.0.4
-ipyfilechooser==0.6.0
-ipykernel==6.17.1
-ipyleaflet==0.20.0
-ipyparallel==8.8.0
-ipython==7.34.0
-ipython-genutils==0.2.0
-ipython-sql==0.5.0
-ipywidgets==7.7.1
-isoduration==20.11.0
-itsdangerous==2.2.0
-jaraco.classes==3.4.0
-jaraco.context==6.1.2
-jaraco.functools==4.4.0
-jax==0.7.2
-jax-cuda12-pjrt==0.7.2
-jax-cuda12-plugin==0.7.2
-jaxlib==0.7.2
-jeepney==0.9.0
-jieba==0.42.1
-Jinja2==3.1.6
-jiter==0.14.0
-joblib==1.5.3
-jsonpatch==1.33
-jsonpickle==4.1.1
-jsonpointer==3.1.1
-jsonschema==4.26.0
-jsonschema-specifications==2025.9.1
-jupyter-console==6.6.3
-jupyter-events==0.12.1
-jupyter-leaflet==0.20.0
-jupyter_client==7.4.9
-jupyter_core==5.9.1
-jupyter_kernel_gateway @ git+https://github.com/googlecolab/kernel_gateway@b134e9945df25c2dcb98ade9129399be10788671
-jupyter_server==2.14.0
-jupyter_server_terminals==0.5.4
-jupyterlab_pygments==0.3.0
-jupyterlab_widgets==3.0.16
-jupytext==1.19.1
-kaggle==2.0.2
-kagglehub==1.0.0
-kagglesdk==0.1.20
-keras==3.13.2
-keras-hub==0.26.0
-keras-nlp==0.26.0
-keyring==25.7.0
-keyrings.google-artifactregistry-auth==1.1.2
-kiwisolver==1.5.0
-langchain==1.2.15
-langchain-core==1.3.1
-langgraph==1.1.9
-langgraph-checkpoint==4.0.2
-langgraph-prebuilt==1.0.10
-langgraph-sdk==0.3.13
-langsmith==0.7.34
-lark==1.3.1
-launchpadlib==1.10.16
-lazr.restfulclient==0.14.4
-lazr.uri==1.0.6
-lazy-loader==0.5
-libclang==18.1.1
-libcudf-cu12==26.2.1
-libcugraph-cu12==26.2.0
-libcuml-cu12==26.2.0
-libcuvs-cu12==26.2.0
-libkvikio-cu12==26.2.0
-libpysal==4.14.1
-libraft-cu12==26.2.0
-librmm-cu12==26.2.0
-librosa==0.11.0
-libucx-cu12==1.19.0
-libucxx-cu12==0.48.0
-lightgbm==4.6.0
-linkify-it-py==2.1.0
-llvmlite==0.43.0
-locket==1.0.0
-logical-unification==0.4.7
-lxml==6.1.0
-Mako==1.3.11
-mapclassify==2.10.0
-Markdown==3.10.2
-markdown-it-py==4.0.0
-MarkupSafe==3.0.3
-matplotlib==3.10.0
-matplotlib-inline==0.2.1
-matplotlib-venn==1.1.2
-mcp==1.27.0
-mdit-py-plugins==0.5.0
-mdurl==0.1.2
-mgwr==2.2.1
-miniKanren==1.0.5
-missingno==0.5.2
-mistune==3.2.0
-mizani==0.13.5
-mkl==2025.3.1
-ml_dtypes==0.5.4
-mlxtend==0.23.4
-mmh3==5.2.1
-momepy==0.11.0
-more-itertools==10.8.0
-moviepy==1.0.3
-mpmath==1.3.0
-msgpack==1.1.2
-multidict==6.7.1
-multipledispatch==1.0.0
-multiprocess==0.70.16
-multitasking==0.0.13
-murmurhash==1.0.15
-music21==9.9.1
-namex==0.1.0
-narwhals==2.20.0
-natsort==8.4.0
-nbclassic==1.3.3
-nbclient==0.10.4
-nbconvert==7.17.1
-nbformat==5.10.4
-ndindex==1.10.1
-nest-asyncio==1.6.0
-networkx==3.6.1
-nibabel==5.4.2
-nltk==3.9.1
-notebook==6.5.7
-notebook_shim==0.2.4
-numba==0.60.0
-numba-cuda==0.22.2
-numexpr==2.14.1
-numpy==2.0.2
-nvidia-cublas-cu12==12.8.4.1
-nvidia-cuda-cccl-cu12==12.9.27
-nvidia-cuda-cupti-cu12==12.8.90
-nvidia-cuda-nvcc-cu12==12.8.93
-nvidia-cuda-nvrtc-cu12==12.8.93
-nvidia-cuda-runtime-cu12==12.8.90
-nvidia-cudnn-cu12==9.10.2.21
-nvidia-cufft-cu12==11.3.3.83
-nvidia-cufile-cu12==1.13.1.3
-nvidia-curand-cu12==10.3.9.90
-nvidia-cusolver-cu12==11.7.3.90
-nvidia-cusparse-cu12==12.5.8.93
-nvidia-cusparselt-cu12==0.7.1
-nvidia-libnvcomp-cu12==5.1.0.21
-nvidia-ml-py==13.595.45
-nvidia-nccl-cu12==2.27.5
-nvidia-nvimgcodec-cu12==0.7.0.11
-nvidia-nvjitlink-cu12==12.8.93
-nvidia-nvshmem-cu12==3.4.5
-nvidia-nvtx-cu12==12.8.90
-nvtx==0.2.15
-nx-cugraph-cu12 @ https://pypi.nvidia.com/nx-cugraph-cu12/nx_cugraph_cu12-26.2.0-py3-none-any.whl
-oauth2client==4.1.3
-oauthlib==3.3.1
-omegaconf==2.3.0
-onemkl-license==2025.3.1
-openai==2.32.0
-opencv-contrib-python==4.13.0.92
-opencv-python==4.13.0.92
-opencv-python-headless==4.13.0.92
-openpyxl==3.1.5
-opentelemetry-api==1.38.0
-opentelemetry-exporter-gcp-logging==1.11.0a0
-opentelemetry-exporter-gcp-monitoring==1.11.0a0
-opentelemetry-exporter-gcp-trace==1.11.0
-opentelemetry-exporter-otlp-proto-common==1.38.0
-opentelemetry-exporter-otlp-proto-http==1.38.0
-opentelemetry-proto==1.38.0
-opentelemetry-resourcedetector-gcp==1.11.0a0
-opentelemetry-sdk==1.38.0
-opentelemetry-semantic-conventions==0.59b0
-opt_einsum==3.4.0
-optax==0.2.8
-optree==0.19.0
-orbax-checkpoint==0.11.36
-orjson==3.11.8
-ormsgpack==1.12.2
-osqp==1.1.1
-overrides==7.7.0
-packaging==26.1
-pandas==2.2.2
-pandas-datareader==0.10.0
-pandas-gbq==0.30.0
-pandas-stubs==2.2.2.240909
-pandocfilters==1.5.1
-panel==1.8.10
-param==2.3.3
-parso==0.8.6
-parsy==2.2
-partd==1.4.2
-patsy==1.0.2
-peewee==4.0.5
-peft==0.19.1
-pexpect==4.9.0
-pickleshare==0.7.5
-pillow==11.3.0
-pip==24.1.2
-platformdirs==4.9.6
-plotly==5.24.1
-plotnine==0.14.5
-pluggy==1.6.0
-plum-dispatch==2.8.0
-pointpats==2.5.5
-polars==1.35.2
-polars-runtime-32==1.35.2
-pooch==1.9.0
-portpicker==1.5.2
-preshed==3.0.13
-prettytable==3.17.0
-proglog==0.1.12
-progressbar2==4.5.0
-prometheus_client==0.25.0
-promise==2.3
-prompt_toolkit==3.0.52
-propcache==0.4.1
-prophet==1.3.0
-proto-plus==1.27.2
-protobuf==5.29.6
-psutil==5.9.5
-psycopg2==2.9.12
-psygnal==0.15.1
-ptyprocess==0.7.0
-PuLP==3.3.0
-py-cpuinfo==9.0.0
-py4j==0.10.9.9
-pyarrow==18.1.0
-pyasn1==0.6.3
-pyasn1_modules==0.4.2
-pycairo==1.29.0
-pycocotools==2.0.11
-pycparser==3.0
-pycryptodomex==3.23.0
-pydantic==2.12.3
-pydantic-settings==2.14.0
-pydantic_core==2.41.4
-pydata-google-auth==1.9.1
-pydot==4.0.1
-pydotplus==2.0.2
-PyDrive2==1.21.3
-pydub==0.25.1
-pyerfa==2.0.1.5
-pygame==2.6.1
-pygit2==1.19.2
-Pygments==2.20.0
-PyGObject==3.48.2
-pyiceberg==0.11.1
-PyJWT==2.12.1
-pylibcudf-cu12==26.2.1
-pylibcugraph-cu12==26.2.0
-pylibraft-cu12==26.2.0
-pymc==5.28.4
-pynndescent==0.6.0
-pyogrio==0.12.1
-pyomo==6.10.0
-PyOpenGL==3.1.10
-pyOpenSSL==24.2.1
-pyparsing==3.3.2
-pyperclip==1.11.0
-pyproj==3.7.2
-pyroaring==1.0.4
-pysal==25.7
-pyshp==3.0.3
-PySocks==1.7.1
-pyspark==4.0.2
-pytensor==2.38.2
-pytest==8.4.2
-python-apt==0.0.0
-python-box==7.4.1
-python-dateutil==2.9.0.post0
-python-dotenv==1.2.2
-python-fasthtml==0.12.50
-python-json-logger==4.1.0
-python-louvain==0.16
-python-multipart==0.0.26
-python-slugify==8.0.4
-python-snappy==0.7.3
-python-utils==3.9.1
-pytz==2025.2
-pyviz_comms==3.0.6
-PyWavelets==1.9.0
-PyYAML==6.0.3
-pyzmq==26.2.1
-quantecon==0.11.2
-raft-dask-cu12==26.2.0
-rapids-dask-dependency==26.2.0
-rapids-logger==0.2.3
-rasterio==1.5.0
-rasterstats==0.20.0
-ratelim==0.1.6
-referencing==0.37.0
-regex==2025.11.3
-requests==2.32.4
-requests-oauthlib==2.0.0
-requests-toolbelt==1.0.0
-requirements-parser==0.9.0
-rfc3339-validator==0.1.4
-rfc3986-validator==0.1.1
-rfc3987-syntax==1.1.0
-rich==13.9.4
-rmm-cu12==26.2.0
-roman-numerals==4.1.0
-roman-numerals-py==4.1.0
-rpds-py==0.30.0
-rpy2==3.5.17
-rsa==4.9.1
-rtree==1.4.1
-ruff==0.15.11
-safehttpx==0.1.7
-safetensors==0.7.0
-scikit-image==0.25.2
-scikit-learn==1.6.1
-scipy==1.16.3
-scooby==0.11.2
-scs==3.2.11
-seaborn==0.13.2
-SecretStorage==3.5.0
-segregation==2.5.4
-semantic-version==2.10.0
-Send2Trash==2.1.0
-sentence-transformers==5.4.1
-sentencepiece==0.2.1
-sentry-sdk==2.58.0
-setuptools==75.2.0
-shap==0.51.0
-shapely==2.1.2
-shellingham==1.5.4
-simple-parsing==0.1.8
-simplejson==4.1.0
-simsimd==6.5.16
-six==1.17.0
-sklearn-compat==0.1.5
-sklearn-pandas==2.2.0
-slicer==0.0.8
-smart_open==7.6.0
-smmap==5.0.3
-sniffio==1.3.1
-snowballstemmer==3.0.1
-sortedcontainers==2.4.0
-soundfile==0.13.1
-soupsieve==2.8.3
-soxr==1.0.0
-spacy==3.8.14
-spacy-legacy==3.0.12
-spacy-loggers==1.0.5
-spaghetti==1.7.6
-spanner-graph-notebook==1.1.10
-spglm==1.1.0
-Sphinx==8.2.3
-sphinxcontrib-applehelp==2.0.0
-sphinxcontrib-devhelp==2.0.0
-sphinxcontrib-htmlhelp==2.1.0
-sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-qthelp==2.0.0
-sphinxcontrib-serializinghtml==2.0.0
-spint==1.0.7
-splot==1.1.7
-spopt==0.7.0
-spreg==1.9.0
-SQLAlchemy==2.0.49
-sqlalchemy-spanner==1.17.3
-sqlglot==25.20.2
-sqlparse==0.5.5
-srsly==2.5.3
-sse-starlette==3.3.4
-stanio==0.5.1
-starlette==0.52.1
-statsmodels==0.14.6
-strictyaml==1.7.3
-stringzilla==4.6.0
-stumpy==1.13.0
-sympy==1.14.0
-tables==3.10.2
-tabulate==0.9.0
-tbb==2022.3.1
-tblib==3.2.2
-tcmlib==1.4.1
-tenacity==9.1.4
-tensorboard==2.20.0
-tensorboard-data-server==0.7.2
-tensorflow==2.20.0
-tensorflow-datasets==4.9.9
-tensorflow-hub==0.16.1
-tensorflow-metadata==1.17.3
-tensorflow-probability==0.25.0
-tensorflow-text==2.20.1
-tensorstore==0.1.82
-termcolor==3.3.0
-terminado==0.18.1
-text-unidecode==1.3
-textblob==0.19.0
-tf-slim==1.1.0
-tf_keras==2.20.0
-thinc==8.3.13
-threadpoolctl==3.6.0
-tifffile==2026.4.11
-tiktoken==0.12.0
-timm==1.0.26
-tinycss2==1.4.0
-tobler==0.14.0
-tokenizers==0.22.2
-toml==0.10.2
-tomlkit==0.13.3
-toolz==0.12.1
-torch==2.10.0+cu128
-torchao==0.10.0
-torchaudio==2.10.0+cu128
-torchcodec==0.10.0+cu128
-torchdata==0.11.0
-torchsummary==1.5.1
-torchtune==0.6.1
-torchvision==0.25.0+cu128
-tornado==6.5.1
-tqdm==4.67.3
-traitlets==5.7.1
-traittypes==0.2.3
-transformers==5.0.0
-treelite==4.7.0
-treescope==0.1.10
-triton==3.6.0
-tsfresh==0.21.1
-tweepy==4.16.0
-typeguard==4.5.1
-typer==0.24.2
-typer-slim==0.24.0
-types-pytz==2026.1.1.20260408
-types-setuptools==82.0.0.20260408
-typing-inspection==0.4.2
-typing_extensions==4.15.0
-tzdata==2026.1
-tzlocal==5.3.1
-uc-micro-py==2.0.0
-ucxx-cu12==0.48.0
-umap-learn==0.5.12
-umf==1.0.3
-uri-template==1.3.0
-uritemplate==4.2.0
-urllib3==2.5.0
-uuid_utils==0.14.1
-uvicorn==0.46.0
-uvloop==0.22.1
-vega-datasets==0.9.0
-wadllib==1.3.6
-wandb==0.26.1
-wasabi==1.1.3
-watchdog==6.0.0
-watchfiles==1.1.1
-wcwidth==0.6.0
-weasel==1.0.0
-webcolors==25.10.0
-webencodings==0.5.1
-websocket-client==1.9.0
-websockets==15.0.1
-Werkzeug==3.1.8
-wheel==0.47.0
-widgetsnbextension==3.6.10
-wordcloud==1.9.6
-wrapt==2.1.2
-xarray==2025.12.0
-xarray-einstats==0.10.0
-xgboost==3.2.0
-xlrd==2.0.2
-xxhash==3.6.0
-xyzservices==2026.3.0
-yarl==1.23.0
-ydf==0.15.0
-ydf_tf==2.20.0
-yellowbrick==1.5
-yfinance==0.2.66
-zict==3.0.0
-zipp==3.23.1
-zstandard==0.25.0

scripts/data/colab_to_cpu_pin.json

@@ -1,36 +0,0 @@
-{
-  "_comment": "Maps Colab GPU runtime pinned wheels to CPU equivalents for ubuntu-latest CI smoke jobs. The Colab GPU image ships +cu128 builds that won't install on a CPU-only runner; this map either rewrites the spec to a CPU wheel from https://download.pytorch.org/whl/cpu or falls back to module-spoof for packages with no CPU build.",
-  "rewrite": {
-    "torch": {
-      "from_local_version": "+cu128",
-      "to_index_url": "https://download.pytorch.org/whl/cpu"
-    },
-    "torchvision": {
-      "from_local_version": "+cu128",
-      "to_index_url": "https://download.pytorch.org/whl/cpu"
-    },
-    "torchaudio": {
-      "from_local_version": "+cu128",
-      "to_index_url": "https://download.pytorch.org/whl/cpu"
-    }
-  },
-  "module_spoof": {
-    "torchcodec": "no CPU wheel published; smoke job sys.modules-stubs torchcodec before importing unsloth"
-  },
-  "skip": [
-    "nvidia-cublas-cu12",
-    "nvidia-cuda-cupti-cu12",
-    "nvidia-cuda-nvrtc-cu12",
-    "nvidia-cuda-runtime-cu12",
-    "nvidia-cudnn-cu12",
-    "nvidia-cufft-cu12",
-    "nvidia-curand-cu12",
-    "nvidia-cusolver-cu12",
-    "nvidia-cusparse-cu12",
-    "nvidia-cusparselt-cu12",
-    "nvidia-nccl-cu12",
-    "nvidia-nvjitlink-cu12",
-    "nvidia-nvtx-cu12",
-    "triton"
-  ]
-}

scripts/enforce_kwargs_spacing.py

@@ -1,43 +1,17 @@
 #!/usr/bin/env python3
-"""Ensure keyword arguments use spaces around '=', prune redundant pass statements,
-drop the blank line after a short indented import block, merge adjacent same-line
-string literals, normalize def-signature magic commas (pre-ruff) so a def with
->= 3 params and a default goes one-per-line while everything else stays
-collapsible, and collapse a short multi-line assert onto one line (pre-ruff) by
-stripping the magic trailing comma that holds it open."""
+"""Ensure keyword arguments use spaces around '=', prune redundant pass statements."""
 
 from __future__ import annotations
 
 import ast
 import argparse
 import io
-import os
 import sys
-import tempfile
 import tokenize
 from collections import defaultdict
 from pathlib import Path
 
 
-def _atomic_write_text(path: Path, data: str, encoding: str) -> None:
-    """Write ``data`` to ``path`` atomically via same-dir tmp + fsync + os.replace,
-    so a crash mid-write leaves either the old or full new content, never a truncation."""
-    dirpath = str(path.parent) or "."
-    fd, tmp_path = tempfile.mkstemp(prefix=".kwargs_fix.", dir=dirpath)
-    try:
-        with os.fdopen(fd, "w", encoding=encoding) as handle:
-            handle.write(data)
-            handle.flush()
-            os.fsync(handle.fileno())
-        os.replace(tmp_path, path)
-    except Exception:
-        try:
-            os.unlink(tmp_path)
-        except OSError:
-            pass
-        raise
-
-
 def enforce_spacing(text: str) -> tuple[str, bool]:
     """Return updated text with keyword '=' padded by spaces, plus change flag."""
     lines = text.splitlines(keepends=True)
@@ -123,7 +97,9 @@ def remove_redundant_passes(text: str) -> tuple[str, bool]:
     lines = text.splitlines(keepends=True)
     changed = False
 
-    for node in sorted(redundant, key=lambda item: (item.lineno, item.col_offset), reverse=True):
+    for node in sorted(
+        redundant, key=lambda item: (item.lineno, item.col_offset), reverse=True
+    ):
         start = node.lineno - 1
         end = (node.end_lineno or node.lineno) - 1
         if start >= len(lines):
@@ -137,7 +113,7 @@ def remove_redundant_passes(text: str) -> tuple[str, bool]:
             lines[start] = segment if segment.strip() else ""
             continue
 
-        # Fall-back for unexpected multi-line 'pass'.
+        # Defensive fall-back for unexpected multi-line 'pass'.
         prefix = lines[start][: node.col_offset]
         lines[start] = prefix if prefix.strip() else ""
         for idx in range(start + 1, end):
@@ -158,441 +134,7 @@ def remove_redundant_passes(text: str) -> tuple[str, bool]:
     return "".join(result_lines), changed
 
 
-def remove_blank_after_short_import(text: str) -> tuple[str, bool]:
-    """Drop blank line(s) after an import block in a small nested suite.
-
-    In an indented suite of <= 3 statements (never module level), when consecutive
-    imports are followed across blank lines (nothing else) by another statement,
-    remove those blanks. A comment in the gap blocks the rule. Removing blank lines
-    never changes the AST.
-    """
-    try:
-        tree = ast.parse(text)
-    except SyntaxError:
-        return text, False
-
-    lines = text.splitlines(keepends=True)
-    import_types = (ast.Import, ast.ImportFrom)
-    drop: set[int] = set()  # 1-based physical line numbers to delete
-
-    def suites_of(node: ast.AST) -> list[list[ast.stmt]]:
-        if isinstance(node, ast.Module):
-            return []  # module-level import spacing is left alone
-        out: list[list[ast.stmt]] = []
-        for attr in ("body", "orelse", "finalbody"):
-            val = getattr(node, attr, None)
-            if isinstance(val, list) and val and all(isinstance(s, ast.stmt) for s in val):
-                out.append(val)
-        return out
-
-    for node in ast.walk(tree):
-        for suite in suites_of(node):
-            if len(suite) > 3:  # only small blocks
-                continue
-            i = 0
-            while i < len(suite):
-                if not isinstance(suite[i], import_types):
-                    i += 1
-                    continue
-                j = i
-                while j + 1 < len(suite) and isinstance(suite[j + 1], import_types):
-                    j += 1
-                if j + 1 < len(suite):  # an import block followed by another statement
-                    last_imp, nxt = suite[j], suite[j + 1]
-                    gap = range((last_imp.end_lineno or last_imp.lineno) + 1, nxt.lineno)
-                    nums = [n for n in gap if 1 <= n <= len(lines)]
-                    if nums and all(lines[n - 1].strip() == "" for n in nums):
-                        drop.update(nums)
-                i = j + 1
-
-    if not drop:
-        return text, False
-    kept = [ln for idx, ln in enumerate(lines, start=1) if idx not in drop]
-    return "".join(kept), True
-
-
-_STRING_TRIVIA = (tokenize.NL, tokenize.NEWLINE, tokenize.COMMENT, tokenize.INDENT, tokenize.DEDENT)
-
-
-_DEF_MIN_PARAMS_FOR_MULTILINE = 3  # signatures with < this many params stay one line
-
-
-def _def_specs_by_line(tree: ast.AST) -> dict[int, tuple[int, bool]]:
-    """Map each def keyword line to (param count, has-any-default).
-
-    ``*`` / ``/`` markers aren't counted. A default exists if any positional default
-    is present or any keyword-only default is not ``None`` (``None`` in ``kw_defaults``
-    means a required keyword-only arg).
-    """
-    out: dict[int, tuple[int, bool]] = {}
-    for node in ast.walk(tree):
-        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-            a = node.args
-            count = (
-                len(a.posonlyargs)
-                + len(a.args)
-                + len(a.kwonlyargs)
-                + (1 if a.vararg else 0)
-                + (1 if a.kwarg else 0)
-            )
-            has_default = bool(a.defaults) or any(d is not None for d in a.kw_defaults)
-            out[node.lineno] = (count, has_default)
-    return out
-
-
-def normalize_def_trailing_comma(text: str) -> tuple[str, bool]:
-    """Force a def signature one-per-line iff >= 3 params AND a default; else collapsible.
-
-    A qualifying signature gets a magic trailing comma added (ruff wraps it
-    one-per-line); every other signature has its trailing comma stripped so ruff
-    collapses it when it fits. Def parameter lists only, never call sites or
-    collection literals. Run BEFORE ruff format. Never changes the AST (re-checked).
-    """
-    try:
-        tree = ast.parse(text)
-        toks = list(tokenize.generate_tokens(io.StringIO(text).readline))
-    except (tokenize.TokenError, IndentationError, SyntaxError):
-        return text, False
-
-    specs = _def_specs_by_line(tree)
-    n = len(toks)
-    edits: list[tuple[int, int, str]] = []  # (row, col, "del" | "ins")
-    i = 0
-    while i < n:
-        t = toks[i]
-        if t.type == tokenize.NAME and t.string == "def" and t.start[0] in specs:
-            cnt, has_default = specs[t.start[0]]
-            force_multiline = cnt >= _DEF_MIN_PARAMS_FOR_MULTILINE and has_default
-            j = i + 1
-            while j < n and not (toks[j].type == tokenize.OP and toks[j].string == "("):
-                if toks[j].type == tokenize.NEWLINE:
-                    break
-                j += 1
-            if j < n and toks[j].type == tokenize.OP and toks[j].string == "(":
-                depth = 0
-                k = j
-                while k < n:
-                    tk = toks[k]
-                    if tk.type == tokenize.OP and tk.string == "(":
-                        depth += 1
-                    elif tk.type == tokenize.OP and tk.string == ")":
-                        depth -= 1
-                        if depth == 0:
-                            m = k - 1
-                            while m > j and toks[m].type in _STRING_TRIVIA:
-                                m -= 1
-                            last = toks[m]
-                            has_comma = last.type == tokenize.OP and last.string == ","
-                            empty = m == j  # nothing between ( and )
-                            if force_multiline and not has_comma and not empty:
-                                edits.append((last.end[0], last.end[1], "ins"))
-                            elif not force_multiline and has_comma:
-                                edits.append((last.start[0], last.start[1], "del"))
-                            break
-                    k += 1
-                i = k + 1
-                continue
-        i += 1
-
-    if not edits:
-        return text, False
-
-    lines = text.splitlines(keepends=True)
-    for row, col, kind in sorted(edits, reverse=True):
-        ln = lines[row - 1]
-        if kind == "del":
-            if col < len(ln) and ln[col] == ",":
-                lines[row - 1] = ln[:col] + ln[col + 1 :]
-        else:  # ins
-            lines[row - 1] = ln[:col] + "," + ln[col:]
-    out = "".join(lines)
-    try:
-        if ast.dump(ast.parse(out)) != ast.dump(ast.parse(text)):
-            return text, False
-    except SyntaxError:
-        return text, False
-    return out, True
-
-
-def _split_string_token(s: str) -> tuple[str, str, str] | None:
-    """Split a string literal source into (prefix, quote, body).
-
-    ``prefix`` is the letters before the opening quote, ``quote`` the delimiter,
-    ``body`` everything between. ``None`` if not a recognizable string literal.
-    """
-    i = 0
-    while i < len(s) and s[i] not in ("'", '"'):
-        i += 1
-    if i >= len(s):
-        return None
-    prefix, rest = s[:i], s[i:]
-    for q in ('"""', "'''", '"', "'"):
-        if rest.startswith(q) and rest.endswith(q) and len(rest) >= 2 * len(q):
-            return prefix, q, rest[len(q) : len(rest) - len(q)]
-    return None
-
-
-# A "piece" is one string literal in source: a plain STRING token, or a whole
-# f-string spanning FSTRING_START..FSTRING_END. (kind, (row, col0), (row, col1), raw)
-def _string_pieces(
-    toks: list[tokenize.TokenInfo], lines: list[str]
-) -> list[tuple[str, tuple[int, int], tuple[int, int], str | None]]:
-    pieces: list[tuple[str, tuple[int, int], tuple[int, int], str | None]] = []
-    n = len(toks)
-
-    def raw_of(start: tuple[int, int], end: tuple[int, int]) -> str | None:
-        if start[0] != end[0]:  # only single-physical-line pieces are mergeable
-            return None
-        return lines[start[0] - 1][start[1] : end[1]]
-
-    i = 0
-    while i < n:
-        t = toks[i]
-        if t.type == tokenize.STRING:
-            pieces.append(("str", t.start, t.end, raw_of(t.start, t.end)))
-            i += 1
-        elif t.type == tokenize.FSTRING_START:
-            depth = 0
-            j = i
-            while j < n:  # walk to the matching FSTRING_END (f-strings can nest)
-                if toks[j].type == tokenize.FSTRING_START:
-                    depth += 1
-                elif toks[j].type == tokenize.FSTRING_END:
-                    depth -= 1
-                    if depth == 0:
-                        break
-                j += 1
-            end = toks[j].end
-            pieces.append(("f", t.start, end, raw_of(t.start, end)))
-            i = j + 1
-        else:
-            pieces.append(("other", t.start, t.end, None))
-            i += 1
-    return pieces
-
-
-def _merge_string_run(pieces: list[tuple[str, str]]) -> str | None:
-    """Merge a run of adjacent string pieces into one literal's source text.
-
-    ``pieces`` is ``(kind, raw_source)`` with kind ``"str"`` or ``"f"``. Bytes are
-    left side-by-side (``None``); a run with no f-string merges plain/raw/unicode
-    sharing one prefix+quote by body concatenation; a run mixing an f-string with a
-    plain string (no bytes, no raw) folds into one f-string with plain braces escaped.
-    Runs of only f-strings are left alone. Caller re-checks the AST and drops a
-    differing change, so subtle cases are caught.
-    """
-    parsed = []
-    for kind, raw in pieces:
-        pqb = _split_string_token(raw)
-        if pqb is None:
-            return None
-        prefix, quote, body = pqb
-        if "b" in prefix.lower():
-            return None  # bytes: leave side-by-side
-        parsed.append((kind, prefix, quote, body))
-    if len({p[2] for p in parsed}) != 1:
-        return None  # mixed quote style: not a safe textual merge
-    quote = parsed[0][2]
-    if not any(p[0] == "f" for p in parsed):
-        # No f-string: merge plain/raw/unicode sharing one prefix by concatenation.
-        if len({p[1].lower() for p in parsed}) != 1:
-            return None
-        return f"{parsed[0][1]}{quote}{''.join(p[3] for p in parsed)}{quote}"
-    # f-string fold only when a plain string is glued onto an f-string; a run of
-    # only f-strings is left side-by-side (folding long ones would force ruff to
-    # re-wrap the surrounding statement).
-    if all(p[0] == "f" for p in parsed):
-        return None
-    # raw mixed with f is too subtle (backslash + brace escaping) -> skip.
-    if any("r" in p[1].lower() for p in parsed):
-        return None
-    body = "".join(
-        b if kind == "f" else b.replace("{", "{{").replace("}", "}}")
-        for kind, _pfx, _q, b in parsed
-    )
-    return f"f{quote}{body}{quote}"
-
-
-_LINE_LENGTH = 100  # ruff line-length; an f-fold must not push a statement past it
-
-
-def _enclosing_stmt(tree: ast.AST, row: int) -> ast.stmt | None:
-    """The innermost statement whose physical-line span contains ``row``."""
-    best: tuple[ast.stmt, int] | None = None
-    for node in ast.walk(tree):
-        if isinstance(node, ast.stmt):
-            lo = node.lineno
-            hi = node.end_lineno or lo
-            if lo <= row <= hi and (best is None or hi - lo < best[1]):
-                best = (node, hi - lo)
-    return best[0] if best else None
-
-
-def _fold_collapses(
-    tree: ast.AST, lines: list[str], row: int, c0: int, c1: int, merged: str
-) -> bool:
-    """Whether an f-string fold at ``row[c0:c1]`` -> ``merged`` is safe to apply.
-
-    Only ``assert`` wraps awkwardly when a message folds (ruff parenthesizes the
-    condition once it no longer fits one line); every other construct wraps
-    acceptably so is always allowed. An ``assert`` fold is allowed only if already
-    one line, or its estimated folded one-line length fits the line length.
-    """
-    stmt = _enclosing_stmt(tree, row)
-    if not isinstance(stmt, ast.Assert):
-        return True
-    lo, hi = stmt.lineno, stmt.end_lineno or stmt.lineno
-    if lo == hi:
-        return True
-    seg = []
-    for k in range(lo, hi + 1):
-        ln = lines[k - 1].rstrip("\n")
-        if k == row:
-            ln = ln[:c0] + merged + ln[c1:]
-        seg.append(ln)
-    indent = len(seg[0]) - len(seg[0].lstrip())
-    # Conservative over-estimate: join continuation lines with a single space
-    # (ruff joins bracketed wraps with none), so borderline cases skip the fold.
-    joined = " ".join(s.strip() for s in seg)
-    return indent + len(joined) <= _LINE_LENGTH
-
-
-def merge_adjacent_string_literals(text: str) -> tuple[str, bool]:
-    """Merge adjacent string literals on ONE physical line into a single literal.
-
-    Plain/raw/unicode runs merge by concatenation; an f-string + plain string folds
-    into one f-string (plain braces escaped) only while the statement still fits one
-    line. Runs of only f-strings, and bytes, are left side-by-side. The file AST is
-    re-checked and a differing change dropped, so meaning never changes.
-    """
-    try:
-        toks = list(tokenize.generate_tokens(io.StringIO(text).readline))
-        tree = ast.parse(text)
-    except (tokenize.TokenError, IndentationError, SyntaxError):
-        return text, False
-
-    lines = text.splitlines(keepends=True)
-    pieces = _string_pieces(toks, lines)
-
-    # Group consecutive mergeable pieces (str/f, single line, same physical line).
-    runs: list[list[tuple[str, tuple[int, int], tuple[int, int], str]]] = []
-    cur: list[tuple[str, tuple[int, int], tuple[int, int], str]] = []
-    for kind, start, end, raw in pieces:
-        if kind in ("str", "f") and raw is not None:
-            if cur and cur[-1][2][0] != start[0]:
-                if len(cur) >= 2:
-                    runs.append(cur)
-                cur = []
-            cur.append((kind, start, end, raw))
-        else:
-            if len(cur) >= 2:
-                runs.append(cur)
-            cur = []
-    if len(cur) >= 2:
-        runs.append(cur)
-    if not runs:
-        return text, False
-
-    edits = []
-    for run in runs:
-        merged = _merge_string_run([(kind, raw) for kind, _s, _e, raw in run])
-        if merged is None:
-            continue
-        row, c0, c1 = run[0][1][0], run[0][1][1], run[-1][2][1]
-        # An f-string fold must not push its statement onto extra lines; a plain
-        # concatenation always collapses cleanly so it skips this check.
-        if any(kind == "f" for kind, _s, _e, _r in run) and not _fold_collapses(
-            tree, lines, row, c0, c1, merged
-        ):
-            continue
-        edits.append((row, c0, c1, merged))
-    if not edits:
-        return text, False
-
-    for row, c0, c1, repl in sorted(edits, key=lambda e: (e[0], e[1]), reverse=True):
-        ln = lines[row - 1]
-        lines[row - 1] = ln[:c0] + repl + ln[c1:]
-    out = "".join(lines)
-    try:
-        if ast.dump(ast.parse(text)) != ast.dump(ast.parse(out)):
-            return text, False
-    except SyntaxError:
-        return text, False
-    return out, True
-
-
-def collapse_short_asserts(text: str) -> tuple[str, bool]:
-    """Collapse a multi-line ``assert`` onto one line when it would fit.
-
-    When the statement's estimated one-line length fits, strip the magic trailing
-    commas (comma before a closer) holding it open so ruff rejoins it. Run BEFORE
-    ruff format. Skips asserts with a comment (would oscillate). Stripping is
-    non-semantic except for a one-element tuple; AST is re-checked and changing
-    asserts left alone.
-    """
-    try:
-        tree = ast.parse(text)
-        toks = list(tokenize.generate_tokens(io.StringIO(text).readline))
-    except (tokenize.TokenError, IndentationError, SyntaxError):
-        return text, False
-
-    lines = text.splitlines(keepends=True)
-    multiline = [
-        (n.lineno, n.end_lineno)
-        for n in ast.walk(tree)
-        if isinstance(n, ast.Assert) and (n.end_lineno or n.lineno) > n.lineno
-    ]
-    if not multiline:
-        return text, False
-
-    comment_rows = {t.start[0] for t in toks if t.type == tokenize.COMMENT}
-
-    targets = []  # (lo, hi) spans whose one-line form fits and have no comment
-    for lo, hi in multiline:
-        if any(lo <= r <= hi for r in comment_rows):
-            continue  # a comment would keep ruff multi-line -> never collapses
-        seg = [lines[k].rstrip("\n") for k in range(lo - 1, hi)]
-        indent = len(seg[0]) - len(seg[0].lstrip())
-        # Over-estimate (join with a space; keep the comma) so a "fits" verdict
-        # is always at least as long as ruff's real one-line output -> no fight.
-        if indent + len(" ".join(s.strip() for s in seg)) <= _LINE_LENGTH:
-            targets.append((lo, hi))
-    if not targets:
-        return text, False
-
-    # Trailing commas (a ',' whose next significant token is a closer), grouped
-    # by the target assert they belong to.
-    sig = [t for t in toks if t.type not in _STRING_TRIVIA]
-    by_target: dict[tuple[int, int], list[tuple[int, int]]] = defaultdict(list)
-    for i, t in enumerate(sig):
-        if t.type == tokenize.OP and t.string == ",":
-            nxt = sig[i + 1] if i + 1 < len(sig) else None
-            if nxt and nxt.type == tokenize.OP and nxt.string in (")", "]", "}"):
-                for lo, hi in targets:
-                    if lo <= t.start[0] <= hi:
-                        by_target[(lo, hi)].append(t.start)
-                        break
-    if not by_target:
-        return text, False
-
-    base_dump = ast.dump(tree)
-    working = lines[:]
-    changed = False
-    for positions in by_target.values():  # apply per assert; skip any that break AST
-        trial = working[:]
-        for row, col in sorted(positions, reverse=True):
-            ln = trial[row - 1]
-            if col < len(ln) and ln[col] == ",":
-                trial[row - 1] = ln[:col] + ln[col + 1 :]
-        try:
-            if ast.dump(ast.parse("".join(trial))) == base_dump:
-                working, changed = trial, True
-        except SyntaxError:
-            pass
-    return ("".join(working), True) if changed else (text, False)
-
-
-def process_file(path: Path, pre: bool = False) -> bool:
+def process_file(path: Path) -> bool:
     try:
         with tokenize.open(path) as handle:
             original = handle.read()
@@ -601,24 +143,10 @@ def process_file(path: Path, pre: bool = False) -> bool:
         print(f"Failed to read {path}: {exc}", file=sys.stderr)
         return False
 
-    if pre:
-        # Pre-ruff: normalize def-signature magic commas (>=3 params + a default
-        # add so ruff forces one-per-line; everything else strips so ruff
-        # collapses), and strip the magic trailing comma from a short multi-line
-        # assert so ruff joins it onto one line. Everything else runs post-ruff.
-        updated, normalized = normalize_def_trailing_comma(original)
-        updated, collapsed = collapse_short_asserts(updated)
-        if normalized or collapsed:
-            _atomic_write_text(path, updated, encoding)
-            return True
-        return False
-
     updated, changed = enforce_spacing(original)
-    updated, blanked = remove_blank_after_short_import(updated)
-    updated, merged = merge_adjacent_string_literals(updated)
     updated, removed = remove_redundant_passes(updated)
-    if changed or blanked or merged or removed:
-        _atomic_write_text(path, updated, encoding)
+    if changed or removed:
+        path.write_text(updated, encoding=encoding)
         return True
     return False
 
@@ -626,11 +154,6 @@ def process_file(path: Path, pre: bool = False) -> bool:
 def main(argv: list[str]) -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("files", nargs="+", help="Python files to fix")
-    parser.add_argument(
-        "--pre",
-        action="store_true",
-        help="pre-ruff pass: normalize def-signature commas + collapse short multi-line asserts",
-    )
     args = parser.parse_args(argv)
 
     touched: list[Path] = []
@@ -643,7 +166,7 @@ def main(argv: list[str]) -> int:
             continue
         if not path.exists() or path.is_dir():
             continue
-        if process_file(path, pre=args.pre):
+        if process_file(path):
             touched.append(path)
 
     if touched:

scripts/install_gemma4_mlx.sh

@@ -1,17 +1,9 @@
 #!/bin/bash
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-set -euo pipefail
+set -e
 
 # ============================================================
 # Gemma 4 MLX — One-command setup + inference
 #
-# Supply-chain hardening: the uv installer payload is pinned by
-# SHA-256. Rotate by running:
-#   curl -sSLf https://astral.sh/uv/install.sh | shasum -a 256
-# and updating _UV_INSTALLER_SHA256 below.
-# ============================================================
-#
 # Usage:
 #   bash install_gemma4_mlx.sh [--venv-dir DIR]
 #
@@ -112,17 +104,10 @@ else
 fi
 
 # ── Install uv ───────────────────────────────────────────────
-_UV_INSTALLER_SHA256="48cd5aca5d5671a3b3d5f61538cc8622e4434af63319115159990d8b0dd02416"
-
 if ! command -v uv >/dev/null 2>&1; then
     step "uv" "installing uv package manager..."
     _uv_tmp=$(mktemp)
     curl -LsSf "https://astral.sh/uv/install.sh" -o "$_uv_tmp"
-    _uv_actual=$(shasum -a 256 "$_uv_tmp" | awk '{print $1}')
-    if [ "$_uv_actual" != "$_UV_INSTALLER_SHA256" ]; then
-        rm -f "$_uv_tmp"
-        fail "uv installer SHA-256 mismatch: got $_uv_actual expected $_UV_INSTALLER_SHA256 (refusing to execute)"
-    fi
     sh "$_uv_tmp" </dev/null >/dev/null 2>&1
     rm -f "$_uv_tmp"
     if [ -f "$HOME/.local/bin/env" ]; then

scripts/install_qwen3_6_mlx.sh

@@ -1,20 +1,9 @@
 #!/bin/bash
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-set -euo pipefail
+set -e
 
 # ============================================================
 # Qwen3.6 MLX — One-command setup + inference
 #
-# Supply-chain hardening:
-#   - All third-party downloads (uv installer, mlx_vlm qwen3_5
-#     patches) are pinned to an immutable git commit SHA and verified
-#     against a hardcoded SHA-256. Any mismatch aborts the install
-#     before the bytes are copied into site-packages.
-#   - To rotate any pin, fetch the new file with `curl`, run
-#     `shasum -a 256`, and update the corresponding constant below.
-# ============================================================
-#
 # Usage:
 #   bash install_qwen3_6_mlx.sh [--venv-dir DIR]
 #
@@ -115,21 +104,10 @@ else
 fi
 
 # ── Install uv ───────────────────────────────────────────────
-# Pin the uv installer payload by SHA-256. Rotate by running:
-#   curl -sSLf https://astral.sh/uv/install.sh | shasum -a 256
-# and updating the constant below. We fetch into a temp file, verify
-# the digest, and only then execute. Mismatch aborts.
-_UV_INSTALLER_SHA256="48cd5aca5d5671a3b3d5f61538cc8622e4434af63319115159990d8b0dd02416"
-
 if ! command -v uv >/dev/null 2>&1; then
     step "uv" "installing uv package manager..."
     _uv_tmp=$(mktemp)
     curl -LsSf "https://astral.sh/uv/install.sh" -o "$_uv_tmp"
-    _uv_actual=$(shasum -a 256 "$_uv_tmp" | awk '{print $1}')
-    if [ "$_uv_actual" != "$_UV_INSTALLER_SHA256" ]; then
-        rm -f "$_uv_tmp"
-        fail "uv installer SHA-256 mismatch: got $_uv_actual expected $_UV_INSTALLER_SHA256 (refusing to execute)"
-    fi
     sh "$_uv_tmp" </dev/null
     rm -f "$_uv_tmp"
     if [ -f "$HOME/.local/bin/env" ]; then
@@ -172,55 +150,21 @@ else
 fi
 
 # ── Apply patches for multi-turn image chat ──────────────────
-#
-# Pin every patch to an immutable commit SHA and verify the body
-# against a hardcoded SHA-256. The mlx_vlm_qwen3_5 patch tree
-# currently only exists on the upstream `fix/ui-fix` branch; we pin
-# to the branch HEAD commit, NOT the floating ref, so a forced push
-# on `fix/ui-fix` cannot swap the bytes under us.
-#
-# Rotate by:
-#   _PATCH_COMMIT=<new SHA>
-#   curl -sSLf "https://raw.githubusercontent.com/unslothai/unsloth/$_PATCH_COMMIT/unsloth/models/patches/mlx_vlm_qwen3_5/qwen3_5.py" | shasum -a 256
-#   curl -sSLf "https://raw.githubusercontent.com/unslothai/unsloth/$_PATCH_COMMIT/unsloth/models/patches/mlx_vlm_qwen3_5/generate.py" | shasum -a 256
-_PATCH_COMMIT="013c99e51bbb8c4b83d88f3b150a1e53251a19d2"
-_PATCH_BASE="https://raw.githubusercontent.com/unslothai/unsloth/${_PATCH_COMMIT}/unsloth/models/patches/mlx_vlm_qwen3_5"
-_PATCH_SHA_QWEN35="4b6fbbcc59b1d6b935e7204351aae1476836d25542a11c7885402b672d2efa64"
-_PATCH_SHA_GENERATE="50c4cbb8c3d94c0c74a4d209db6d2b23b102944c147c6421f2eded427b8edaf7"
-
+_PATCH_BASE="https://raw.githubusercontent.com/unslothai/unsloth/refs/heads/fix/ui-fix/unsloth/models/patches/mlx_vlm_qwen3_5"
 _SITE_PKGS=$("$_VENV_PY" -c "import site; print(site.getsitepackages()[0])")
 
 step "patch" "fixing multi-turn image chat..."
 
-# Stage all downloads in an isolated tmpdir; we only copy into
-# site-packages after every checksum has matched.
-_PATCH_TMP=$(mktemp -d)
-trap 'rm -rf "$_PATCH_TMP"' EXIT
-
-apply_pinned_patch() {
-    # apply_pinned_patch <remote_basename> <expected_sha256> <dest_abspath>
-    _name="$1"; _expected="$2"; _dest="$3"
-    _staged="$_PATCH_TMP/$_name"
-    if ! curl -sSLf "${_PATCH_BASE}/${_name}" -o "$_staged"; then
-        step "warning" "failed to download ${_name} patch — multi-turn image chat may not work" "$C_WARN"
-        return 1
-    fi
-    _actual=$(shasum -a 256 "$_staged" | awk '{print $1}')
-    if [ "$_actual" != "$_expected" ]; then
-        step "warning" "${_name} SHA-256 mismatch (got $_actual expected $_expected) — refusing to install patch" "$C_WARN"
-        return 1
-    fi
-    mkdir -p "$(dirname "$_dest")"
-    cp "$_staged" "$_dest"
-    return 0
-}
-
-if apply_pinned_patch "qwen3_5.py" "$_PATCH_SHA_QWEN35" "${_SITE_PKGS}/mlx_vlm/models/qwen3_5/qwen3_5.py"; then
+if curl -sSLf "${_PATCH_BASE}/qwen3_5.py" -o "${_SITE_PKGS}/mlx_vlm/models/qwen3_5/qwen3_5.py"; then
     substep "patched qwen3_5.py (MRoPE position reset)"
+else
+    step "warning" "failed to download qwen3_5.py patch — multi-turn image chat may not work" "$C_WARN"
 fi
 
-if apply_pinned_patch "generate.py" "$_PATCH_SHA_GENERATE" "${_SITE_PKGS}/mlx_vlm/generate.py"; then
+if curl -sSLf "${_PATCH_BASE}/generate.py" -o "${_SITE_PKGS}/mlx_vlm/generate.py"; then
     substep "patched generate.py (mask trim on cache reuse)"
+else
+    step "warning" "failed to download generate.py patch — multi-turn image chat may not work" "$C_WARN"
 fi
 
 # Clear pycache so patches take effect

scripts/install_rocm_wsl_strixhalo.sh

@@ -1,310 +0,0 @@
-#!/usr/bin/env bash
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-#
-# ──────────────────────────────────────────────────────────────────────────────
-# Enable ROCm-on-WSL for AMD GPUs (Strix Halo/Point APUs AND discrete Radeon RX
-# 7000/9000). Verified on gfx1151 (Radeon 8060S) and gfx1200 (Radeon RX 9060 XT).
-# ──────────────────────────────────────────────────────────────────────────────
-# install.sh routes the detected arch to the right ROCm wheels once a runtime exists;
-# what it does NOT do is install AMD's ROCm userspace + the WSL DXG bridge (librocdxg).
-# This helper does that Linux-side prerequisite on Ubuntu 24.04 WSL2, invoked by
-# install.sh when it sees an AMD GPU via /dev/dxg but no ROCm yet. Arch-agnostic: the
-# arch is auto-detected from rocminfo (override UNSLOTH_WSL_GFX=gfx1200). Idempotent.
-#
-# Manual, admin-gated Windows prerequisite: an AMD Adrenalin driver with
-# production ROCDXG/WSL support (26.2.2+). install.ps1 offers to update it. Once
-# installed + rebooted, /dev/dxg is exposed to WSL and this script builds the rest.
-#
-# HOW ROCDXG WORKS (and why older /usr/lib/wsl/lib notes are wrong): librocdxg.so
-# is AMD's user-mode bridge between the Linux HSA runtime and the Windows driver
-# over /dev/dxg. The STANDARD hsa-rocr runtime (NOT the gone "roc4wsl" package)
-# loads it when HSA_ENABLE_DXG_DETECTION=1. No hsa/rocm libs need injecting into
-# /usr/lib/wsl/lib (it holds only d3d12/dxcore), yet rocminfo enumerates gfx1151
-# fine -- so we gate on /dev/dxg, not on WSL lib injection.
-#
-# KNOWN CAVEAT (ROCm/ROCm#6022): librocdxg can cap usable ROCm VRAM at the WSL
-# VM's RAM (.wslconfig [wsl2] memory=) on some BIOS UMA layouts, and amd-smi
-# doesn't work in WSL. On OOM below capacity, raise memory= (then wsl --shutdown)
-# and watch GPU use from Windows. Large-UMA BIOS exposes the full pool regardless.
-#
-# Verified on Ryzen AI Max+ PRO 395 / Radeon 8060S (gfx1151) with ROCm 7.2.1 +
-# Ubuntu 24.04 + WSL2 + Adrenalin. These pins MOVE; bump + re-verify on newer ROCm.
-# ──────────────────────────────────────────────────────────────────────────────
-set -euo pipefail
-
-# ── Tunables (override via env) ──────────────────────────────────────────────
-ROCM_VER="${UNSLOTH_WSL_ROCM_VER:-7.2.1}"            # ROCm release to install
-# GPU arch: empty = auto-detect from rocminfo after install (override UNSLOTH_WSL_GFX=gfx1200).
-# The ROCm + librocdxg setup is arch-agnostic; only verify + the smoke test need the arch.
-GFX="${UNSLOTH_WSL_GFX:-}"
-LIBROCDXG_REF="${UNSLOTH_LIBROCDXG_REF:-develop}"    # ROCm/librocdxg git ref to build
-# AMD's wheel index for the (optional) smoke test; resolved after arch detection.
-TORCH_INDEX=""
-# Optional torch smoke test (throwaway venv). OFF by default: install.sh installs
-# torch itself into the real venv right after, so a duplicate download is wasteful.
-SMOKE_TEST="${UNSLOTH_WSL_SMOKE_TEST:-0}"
-# REQUIRED constraint -- without it pip prefers PyPI's newer CUDA torch over the
-# gfx1151 ROCm wheel. 2.11 carries AMD's real gfx1151 fix (matches install.sh).
-TORCH_CONSTRAINT="${UNSLOTH_WSL_TORCH_CONSTRAINT:-torch>=2.11.0,<2.12.0}"
-ROCM_DIR=""                                          # resolved after install
-
-say()  { printf '\n\033[1;36m== %s\033[0m\n' "$*"; }
-note() { printf '   %s\n' "$*"; }
-die()  { printf '\n\033[1;31m[BLOCKED] %s\033[0m\n' "$*" >&2; exit 1; }
-
-# sudo only if not already root (WSL distros often run as root)
-SUDO=""
-if [ "$(id -u)" -ne 0 ]; then
-    command -v sudo >/dev/null 2>&1 || die "Need root or sudo to install ROCm."
-    SUDO="sudo"
-fi
-
-# ── Windows 11 SDK (headers for the librocdxg build) ─────────────────────────
-# librocdxg's cmake build needs the Windows SDK 'shared' headers, which live on
-# the Windows HOST under C:\Program Files (x86)\Windows Kits\10\Include\<ver>\.
-_WIN_SDK_INC_BASE="/mnt/c/Program Files (x86)/Windows Kits/10/Include"
-
-# Print the newest installed SDK include dir with 'shared' headers, or nothing.
-# find + read loop (not `for ... in $(ls)`) since the base path has a space.
-_find_win_sdk() {
-    [ -d "$_WIN_SDK_INC_BASE" ] || return 0
-    while IFS= read -r _inc; do
-        [ -n "$_inc" ] || continue
-        if [ -d "$_inc/shared" ]; then printf '%s' "$_inc"; return 0; fi
-    done < <(find "$_WIN_SDK_INC_BASE" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | sort -Vr)
-    return 0
-}
-
-# Best-effort: install the Windows 11 SDK on the Windows HOST via winget so the
-# build has its headers with no manual step. Elevates -> ONE UAC prompt; headers
-# appear under /mnt/c immediately (no reboot). Never fatal -- failure falls
-# through to a manual-install message. Opt out: UNSLOTH_SKIP_WIN_SDK_INSTALL=1.
-_install_windows_sdk_via_winget() {
-    [ "${UNSLOTH_SKIP_WIN_SDK_INSTALL:-0}" = "1" ] && { note "Skipping Windows SDK auto-install (UNSLOTH_SKIP_WIN_SDK_INSTALL=1)."; return 0; }
-    command -v powershell.exe >/dev/null 2>&1 || return 0
-    # `command -v` succeeds even with WSL interop OFF (.exe on PATH but fails
-    # with "Exec format error"); verify it actually executes.
-    powershell.exe -NoProfile -Command "exit 0" >/dev/null 2>&1 || return 0
-    if ! powershell.exe -NoProfile -Command "if (Get-Command winget -ErrorAction SilentlyContinue) { exit 0 } else { exit 1 }" >/dev/null 2>&1; then
-        note "winget not available on the Windows host -- cannot auto-install the Windows SDK."
-        return 0
-    fi
-    say "Installing the Windows 11 SDK on the Windows host via winget"
-    note "librocdxg needs its headers. Approve the UAC prompt on the Windows desktop."
-    note "One-time (~1-3 GB download); opt out with UNSLOTH_SKIP_WIN_SDK_INSTALL=1."
-    # Newest SDK first, then a fallback. Header presence is the source of truth
-    # (re-check each attempt), not winget's exit code. </dev/null so winget never
-    # consumes a piped `curl | sh` stdin.
-    for _sdk_id in Microsoft.WindowsSDK.10.0.26100 Microsoft.WindowsSDK.10.0.22621; do
-        note "winget install ${_sdk_id} ..."
-        # --source winget: pin the community source so a broken default msstore
-        # source (the cert failure this PR fixes) can't abort SDK resolution.
-        powershell.exe -NoProfile -Command "winget install --id ${_sdk_id} -e --source winget --accept-source-agreements --accept-package-agreements --disable-interactivity" </dev/null || true
-        if [ -n "$(_find_win_sdk)" ]; then
-            note "Windows SDK headers present after install."
-            return 0
-        fi
-    done
-    note "Automatic Windows SDK install did not complete."
-    return 0
-}
-
-# ── PREFLIGHT ────────────────────────────────────────────────────────────────
-say "Preflight checks"
-
-# shellcheck disable=SC1091
-. /etc/os-release 2>/dev/null || true
-if [ "${VERSION_ID:-}" != "24.04" ]; then
-    die "This targets Ubuntu 24.04 (found '${VERSION_ID:-unknown}'). AMD's ROCm-on-WSL supports 24.04; create a dedicated distro:  wsl --install Ubuntu-24.04  (do not run on 26.04 -- ROCm 7.2 does not target it yet)."
-fi
-
-if [ ! -e /dev/dxg ]; then
-    die "/dev/dxg missing -- WSL GPU paravirtualization not present. Ensure this is WSL2 (not WSL1) on a recent Windows build, and that an AMD GPU + ROCDXG-capable Adrenalin driver is installed on the Windows host (then reboot)."
-fi
-note "Ubuntu 24.04 + /dev/dxg present."
-# Don't block on hsa/rocm libs in /usr/lib/wsl/lib: a working ROCDXG setup
-# doesn't need them (only d3d12/dxcore). Real readiness is checked via rocminfo.
-
-# ── Step 1: build/runtime prerequisites ──────────────────────────────────────
-say "Installing build prerequisites"
-export DEBIAN_FRONTEND=noninteractive
-$SUDO apt-get update -y
-# `make` is explicit: cmake shells out to it but Ubuntu only *recommends* it, so
-# minimal images lack it and the librocdxg `make -j` build would fail.
-$SUDO apt-get install -y cmake make gcc g++ git wget gpg ca-certificates python3-venv python3-pip
-
-# ── Step 2: ROCm ${ROCM_VER} userspace (no DKMS -- WSL uses the Windows driver) ─
-say "Installing ROCm ${ROCM_VER} userspace"
-if ! command -v rocminfo >/dev/null 2>&1 && [ ! -x /opt/rocm/bin/rocminfo ]; then
-    # Direct apt-repo install (leaner than amdgpu-install; repo is indexed by
-    # ROCm version, e.g. .../apt/7.2.1).
-    $SUDO mkdir -p /etc/apt/keyrings
-    wget -qO- https://repo.radeon.com/rocm/rocm.gpg.key \
-        | gpg --dearmor | $SUDO tee /etc/apt/keyrings/rocm.gpg >/dev/null
-    echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/rocm.gpg] https://repo.radeon.com/rocm/apt/${ROCM_VER} noble main" \
-        | $SUDO tee /etc/apt/sources.list.d/rocm.list >/dev/null
-    printf 'Package: *\nPin: release o=repo.radeon.com\nPin-Priority: 600\n' \
-        | $SUDO tee /etc/apt/preferences.d/rocm-pin-600 >/dev/null
-    $SUDO apt-get update -y
-    # rocm-libs pulls everything torch links at runtime (rocblas, hipblas,
-    # miopen-hip, rccl, ...); hsa-rocr + rocminfo come as deps. Large (~5 GB
-    # download / ~23 GB installed).
-    $SUDO apt-get install -y rocm-libs rocminfo hip-runtime-amd
-else
-    note "ROCm already present -- skipping apt install."
-fi
-
-# Resolve the real ROCm dir and ensure the canonical /opt/rocm symlink. apt lays
-# ROCm under /opt/rocm-<ver> and rocm-core symlinks /opt/rocm -> that; repair if
-# an earlier partial run left /opt/rocm as a real dir blocking the symlink.
-_real="$(ls -d /opt/rocm-* 2>/dev/null | sort -V | tail -1 || true)"
-if [ -n "$_real" ] && [ ! -L /opt/rocm ] && [ -d /opt/rocm ]; then
-    # /opt/rocm is a real dir blocking the symlink. Only treat it as a removable
-    # stray stub if it's NOT a real ROCm install (a real one has bin/rocminfo /
-    # bin/hipcc / .info/version) -- this protects a user's pre-existing ROCm. Even
-    # then we MOVE IT ASIDE, never rm -rf, so a wrong guess can't lose data.
-    if [ -e /opt/rocm/bin/rocminfo ] || [ -e /opt/rocm/bin/hipcc ] || [ -e /opt/rocm/.info/version ]; then
-        note "/opt/rocm is a real ROCm install -- leaving it untouched (will install librocdxg into it)."
-    else
-        note "Moving stray /opt/rocm stub aside -> $_real (not deleting it)"
-        $SUDO cp -an /opt/rocm/. "$_real"/ 2>/dev/null || true
-        $SUDO mv /opt/rocm "/opt/rocm.unsloth-stub-bak.$(date +%s)" 2>/dev/null || true
-        [ -e /opt/rocm ] || $SUDO ln -s "$_real" /opt/rocm
-    fi
-elif [ -n "$_real" ] && [ ! -e /opt/rocm ]; then
-    $SUDO ln -s "$_real" /opt/rocm
-fi
-if [ -L /opt/rocm ] || [ -d /opt/rocm ]; then ROCM_DIR="/opt/rocm"; else ROCM_DIR="$_real"; fi
-{ [ -n "$ROCM_DIR" ] && [ -d "$ROCM_DIR" ]; } || die "ROCm not found under /opt after install."
-note "ROCm at ${ROCM_DIR}"
-
-# ── Step 3: build librocdxg (DXG <-> HSA bridge; not yet an apt package) ──────
-say "Building librocdxg (${LIBROCDXG_REF})"
-if [ -e "${ROCM_DIR}/lib/librocdxg.so" ]; then
-    note "librocdxg already installed -- skipping build."
-else
-    # Discover the newest installed Win11 SDK (version differs per machine). If
-    # absent, auto-install via winget (one UAC prompt) and re-discover; only if
-    # that ALSO fails do we stop with manual instructions.
-    _win_sdk="$(_find_win_sdk)"
-    if [ -z "$_win_sdk" ]; then
-        note "Windows 11 SDK headers not found -- attempting automatic install..."
-        _install_windows_sdk_via_winget
-        _win_sdk="$(_find_win_sdk)"
-    fi
-    [ -n "$_win_sdk" ] || die "Windows 11 SDK headers not found under 'C:\\Program Files (x86)\\Windows Kits\\10\\Include\\*\\shared', and the automatic winget install did not complete. Install it on the Windows host (e.g. 'winget install Microsoft.WindowsSDK.10.0.26100') and re-run."
-    note "Windows SDK: ${_win_sdk}"
-    _src="${HOME}/.unsloth/librocdxg"
-    rm -rf "$_src"
-    git clone --depth 1 --branch "$LIBROCDXG_REF" https://github.com/ROCm/librocdxg.git "$_src" \
-        || git clone "https://github.com/ROCm/librocdxg.git" "$_src"
-    (
-        cd "$_src"
-        git checkout "$LIBROCDXG_REF" 2>/dev/null || true
-        mkdir -p build && cd build
-        cmake .. -DWIN_SDK="${_win_sdk}/shared"
-        make -j"$(nproc)"
-        $SUDO make install
-    )
-fi
-# Ensure soname symlinks resolve to whatever version was built (e.g. 1.2.0).
-_dxg_real="$(ls -1 "${ROCM_DIR}"/lib/librocdxg.so.*.* 2>/dev/null | sort -V | tail -1 || true)"
-if [ -n "$_dxg_real" ]; then
-    _dxg_base="$(basename "$_dxg_real")"                       # librocdxg.so.1.2.0
-    _dxg_major="$(printf '%s' "$_dxg_base" | sed -E 's/librocdxg\.so\.([0-9]+).*/\1/')"
-    $SUDO ln -sf "$_dxg_base" "${ROCM_DIR}/lib/librocdxg.so.${_dxg_major}"
-    $SUDO ln -sf "librocdxg.so.${_dxg_major}" "${ROCM_DIR}/lib/librocdxg.so"
-fi
-echo "${ROCM_DIR}/lib" | $SUDO tee /etc/ld.so.conf.d/rocm.conf >/dev/null
-$SUDO ldconfig
-
-# ── Step 4: persist environment (system-wide so Unsloth's worker inherits it) ──
-say "Persisting ROCm-on-WSL environment"
-_envfile="/etc/profile.d/unsloth-rocm-wsl.sh"
-$SUDO tee "$_envfile" >/dev/null <<EOF
-# >>> Unsloth ROCm-on-WSL >>>
-export HSA_ENABLE_DXG_DETECTION=1
-export TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1
-export PATH="${ROCM_DIR}/bin:\${PATH}"
-export LD_LIBRARY_PATH="${ROCM_DIR}/lib:\${LD_LIBRARY_PATH:-}"
-# <<< Unsloth ROCm-on-WSL <<<
-EOF
-# also drop into ~/.bashrc for interactive shells
-if [ -n "${HOME:-}" ] && ! grep -q "Unsloth ROCm-on-WSL" "${HOME}/.bashrc" 2>/dev/null; then
-    cat "$_envfile" >> "${HOME}/.bashrc"
-fi
-# export into the current process so verification below works immediately
-export HSA_ENABLE_DXG_DETECTION=1
-export PATH="${ROCM_DIR}/bin:${PATH}"
-export LD_LIBRARY_PATH="${ROCM_DIR}/lib:${LD_LIBRARY_PATH:-}"
-
-# ── Step 5: verify the runtime enumerates the GPU ────────────────────────────
-say "Verifying rocminfo enumerates the GPU over DXG"
-# Capture rocminfo into a var BEFORE grepping: piping into `grep -q` SIGPIPEs
-# rocminfo on first match, which under `set -o pipefail` turns a successful match
-# into a pipeline failure.
-_rocminfo_out="$(rocminfo 2>/dev/null || true)"
-# GPU agents advertise an ISA "Name: gfxNNNN". Match gfx[1-9] (excludes gfx000, the CPU
-# agent), drop the "gfx*-generic" fallback ISA, and take the first real GPU arch.
-_detected_gfx="$(printf '%s\n' "$_rocminfo_out" | grep -E 'Name:[[:space:]]*gfx[1-9]' | grep -v 'generic' | grep -oE 'gfx[1-9][0-9a-z]*' | head -1 || true)"
-if [ -z "$_detected_gfx" ]; then
-    printf '%s\n' "$_rocminfo_out" | head -25 >&2 || true
-    die "rocminfo did not enumerate any GPU agent. Most common cause: the Windows AMD driver predates production ROCDXG -- update Adrenalin (install.ps1 offers this), reboot, and re-run."
-fi
-# Honour a caller-pinned arch (sanity-check via a consuming grep, not grep -q: under
-# pipefail -q would SIGPIPE printf on large output and misreport the arch); else adopt.
-if [ -n "$GFX" ] && ! printf '%s\n' "$_rocminfo_out" | grep -E "Name:[[:space:]]*${GFX}([^0-9]|$)" >/dev/null; then
-    die "rocminfo enumerated '${_detected_gfx}' but not the requested UNSLOTH_WSL_GFX='${GFX}'."
-fi
-GFX="${GFX:-$_detected_gfx}"
-# Display-only summary: best-effort (|| true) so head's early pipe-close under
-# `set -o pipefail` can't fail the bootstrap after verification already passed.
-printf '%s\n' "$_rocminfo_out" | grep -E 'Marketing Name|Device Type|Compute Unit' | grep -iE "Radeon|GPU|Compute" | head -3 || true
-note "ROCm-on-WSL runtime is live for ${GFX}."
-
-# ── Step 6 (optional): torch smoke test from AMD's per-arch wheel index ───────
-if [ "$SMOKE_TEST" = "1" ]; then
-    say "Smoke-testing PyTorch on ${GFX} (throwaway venv)"
-    # Map the detected arch to AMD's repo.amd.com wheel family index.
-    case "$GFX" in
-        gfx1200|gfx1201)                 _fam="gfx120X-all" ;;
-        gfx1100|gfx1101|gfx1102|gfx1103) _fam="gfx110X-all" ;;
-        *)                               _fam="$GFX" ;;   # gfx1150/gfx1151/gfx90a: own index
-    esac
-    TORCH_INDEX="${UNSLOTH_AMD_ROCM_MIRROR:-https://repo.amd.com/rocm/whl}/${_fam}/"
-    _venv="${HOME}/.unsloth/rocm-smoketest"
-    rm -rf "$_venv"; python3 -m venv "$_venv"
-    "$_venv/bin/pip" install --quiet --upgrade pip
-    # AMD arch index is primary (torch + triton); PyPI only an extra for pure-py
-    # deps. The constraint keeps pip on the ROCm wheel, not a newer PyPI CUDA torch.
-    "$_venv/bin/pip" install --index-url "$TORCH_INDEX" \
-        --extra-index-url https://pypi.org/simple "$TORCH_CONSTRAINT" || \
-        die "torch install from ${TORCH_INDEX} failed."
-    # WSL: torch's bundled ROCr must load the DXG bridge -- drop librocdxg into torch/lib.
-    _tlib="$("$_venv/bin/python" -c 'import torch,os;print(os.path.join(os.path.dirname(torch.__file__),"lib"))' 2>/dev/null || true)"
-    [ -d "$_tlib" ] && cp -f "${ROCM_DIR}"/lib/librocdxg.so* "$_tlib"/ 2>/dev/null || true
-    "$_venv/bin/python" - <<'PY'
-import torch
-ok = torch.cuda.is_available()
-print("torch:", torch.__version__, "| cuda(rocm) available:", ok)
-if ok:
-    print("device:", torch.cuda.get_device_name(0))
-    free, total = torch.cuda.mem_get_info(0)
-    print(f"mem: free={free/1e9:.1f} GB total={total/1e9:.1f} GB")
-    import time
-    a = torch.randn(4096, 4096, device="cuda", dtype=torch.float16)
-    b = torch.randn(4096, 4096, device="cuda", dtype=torch.float16)
-    torch.cuda.synchronize(); t0 = time.time()
-    for _ in range(10): c = a @ b
-    torch.cuda.synchronize()
-    print(f"matmul ok ({(time.time()-t0)/10*1e3:.1f} ms/iter)")
-raise SystemExit(0 if ok else 1)
-PY
-    rm -rf "$_venv"
-fi
-
-say "Done."
-note "ROCm-on-WSL is ready for ${GFX}. If you ran this standalone, install Unsloth"
-note "in THIS distro and it will detect the GPU automatically:"
-note "  curl -fsSL https://unsloth.ai/install.sh | sh"

scripts/lint_workflow_triggers.py

@@ -1,150 +0,0 @@
-#!/usr/bin/env python3
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-"""Refuse dangerous GitHub Actions trigger patterns at PR time.
-
-Bans patterns behind the TanStack GHSA-g7cv-rxg3-hmpx compromise:
-
-1.  `pull_request_target` -- runs a fork's workflow against the base
-    repo's secrets/permissions; use `pull_request` instead.
-2.  `workflow_run` chained to a PR-triggered workflow -- same trust
-    boundary problem one hop later (poisoned artifacts/caches run with
-    elevated permissions).
-3.  Cache keys shared between PR-triggered and publish/release/push
-    workflows -- a fork PR could poison a cache the publish workflow
-    restores. Partition the key namespaces.
-
-Exit codes: 0 = no findings, 1 = findings (listed on stderr).
-Run from repo root: python3 scripts/lint_workflow_triggers.py
-"""
-
-from __future__ import annotations
-
-import argparse
-import re
-import sys
-from pathlib import Path
-
-try:
-    import yaml
-except ImportError:
-    print("ERROR: PyYAML is required. Install with 'pip install pyyaml'", file = sys.stderr)
-    sys.exit(2)
-
-REPO_ROOT = Path(__file__).resolve().parents[1]
-DEFAULT_WORKFLOWS_DIR = REPO_ROOT / ".github" / "workflows"
-
-BANNED_TRIGGERS: tuple[str, ...] = ("pull_request_target",)
-RESTRICTED_TRIGGERS: tuple[str, ...] = ("workflow_run",)
-PUBLISH_WORKFLOW_NAMES: tuple[str, ...] = ("release-desktop.yml",)
-
-
-def _normalise_on(on_field):
-    if isinstance(on_field, str):
-        return {on_field}
-    if isinstance(on_field, list):
-        return set(on_field)
-    if isinstance(on_field, dict):
-        return set(on_field.keys())
-    return set()
-
-
-def _load_workflow(path: Path):
-    try:
-        return yaml.safe_load(path.read_text(encoding = "utf-8"))
-    except Exception as exc:
-        print(f"ERROR: failed to parse {path}: {exc}", file = sys.stderr)
-        sys.exit(2)
-
-
-def _extract_cache_keys(path: Path) -> list[str]:
-    text = path.read_text(encoding = "utf-8")
-    keys: list[str] = []
-    for m in re.finditer(r"(?:^|\n)\s*key:\s*([^\n]+)", text):
-        keys.append(m.group(1).strip())
-    return keys
-
-
-def _trigger_set(yaml_doc) -> set[str]:
-    on = yaml_doc.get(True)
-    if on is None:
-        on = yaml_doc.get("on")
-    return _normalise_on(on)
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description = __doc__)
-    parser.add_argument(
-        "--workflows-dir",
-        type = Path,
-        default = DEFAULT_WORKFLOWS_DIR,
-        help = "Override the workflows directory (used by tests).",
-    )
-    args = parser.parse_args()
-    workflows_dir = args.workflows_dir
-
-    findings: list[str] = []
-    workflows = sorted(workflows_dir.glob("*.yml"))
-    pr_triggered: list[tuple[Path, list[str]]] = []
-    publish_triggered: list[tuple[Path, list[str]]] = []
-
-    for path in workflows:
-        doc = _load_workflow(path)
-        triggers = _trigger_set(doc)
-
-        for t in BANNED_TRIGGERS:
-            if t in triggers:
-                findings.append(
-                    f"{path.name}: BANNED trigger '{t}' (GHSA-g7cv-rxg3-hmpx "
-                    "pattern: fork PRs run in base-repo context). Switch to "
-                    "'pull_request' and use a deploy-on-merge workflow for "
-                    "any privileged step."
-                )
-
-        for t in RESTRICTED_TRIGGERS:
-            if t in triggers:
-                text = path.read_text(encoding = "utf-8")
-                if "lint:workflow_triggers-allow-workflow_run" not in text:
-                    findings.append(
-                        f"{path.name}: RESTRICTED trigger '{t}' requires an "
-                        "explicit `# lint:workflow_triggers-allow-workflow_run` "
-                        "comment somewhere in the file, with a justification."
-                    )
-
-        if "pull_request" in triggers:
-            pr_triggered.append((path, _extract_cache_keys(path)))
-        is_dispatch_only = "workflow_dispatch" in triggers and not (
-            "push" in triggers or "pull_request" in triggers
-        )
-        if path.name in PUBLISH_WORKFLOW_NAMES or is_dispatch_only:
-            publish_triggered.append((path, _extract_cache_keys(path)))
-
-    pr_keys = {key for _, keys in pr_triggered for key in keys}
-    for pub_path, pub_keys in publish_triggered:
-        for k in pub_keys:
-            if k in pr_keys:
-                findings.append(
-                    f"{pub_path.name}: cache key {k!r} is also declared in a "
-                    "PR-triggered workflow. A fork PR could poison this cache "
-                    "and the publish workflow would restore it on next run. "
-                    "Add a unique suffix (e.g. '-publish-only') to partition "
-                    "the namespaces."
-                )
-
-    if findings:
-        print("Workflow trigger lint failed with the following issues:", file = sys.stderr)
-        for f in findings:
-            print(f"  - {f}", file = sys.stderr)
-        return 1
-
-    print(
-        f"OK: scanned {len(workflows)} workflow file(s); "
-        f"no pull_request_target, no unjustified workflow_run, "
-        f"no PR/publish cache-key collision."
-    )
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

scripts/lockfile_supply_chain_audit.py

@@ -1,780 +0,0 @@
-#!/usr/bin/env python3
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
-
-"""Lockfile supply-chain audit for the Unsloth frontend and Tauri shell.
-
-Runs BEFORE `npm ci` / `cargo fetch` in CI. Refuses to proceed when a
-lockfile contains patterns indicating supply-chain injection (npm
-Shai-Hulud waves, cargo crates.io brand-squats).
-
-Checks package-lock.json (lockfileVersion 2/3): `resolved` URL must be
-the npm registry (direct git/github/file refs are the injection vector);
-`integrity` SHA must be present; known IOC substrings grepped from the
-body. Checks Cargo.lock: `source` must be the crates.io registry index;
-known cargo IOC substrings.
-
-Exit codes: 0 = clean (or skip env var set to a justification >=5 chars,
-not '1'/'true'); 1 = findings; 2 = internal error.
-
-Only PARSES the lockfiles, never executes or networks. Complements (not
-replaces) `npm audit` / OSV-Scanner / the advisory-DB pipeline. Fires
-before any third-party install script runs on the runner.
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import re
-import sys
-from pathlib import Path
-
-REPO_ROOT = Path(__file__).resolve().parents[1]
-
-
-# Known IOC strings (case-sensitive substring match). Each is tied to a
-# public advisory; speculative/generic patterns would false-positive on
-# upgrades.
-NPM_IOC_STRINGS: tuple[str, ...] = (
-    # Shai-Hulud TanStack wave -- May 11, 2026 (GHSA-g7cv-rxg3-hmpx).
-    "router_init.js",
-    "tanstack_runner.js",
-    "router_runtime.js",
-    "@tanstack/setup",
-    "github:tanstack/router#79ac49eedf774dd4b0cfa308722bc463cfe5885c",
-    # Exfiltration endpoints observed across both Shai-Hulud waves.
-    "filev2.getsession.org",
-    "getsession.org/file/",
-    # Campaign markers; the worm tarballs print this to stdout on run.
-    "A Mini Shai-Hulud has Appeared",
-    # Mini Shai-Hulud May-12 2026 wave.
-    "git-tanstack.com",
-    "transformers.pyz",
-    "/tmp/transformers.pyz",
-    "With Love TeamPCP",
-    # Aikido (May-12 wave): payload SHA-256 hashes + Bun marker.
-    "ab4fcadaec49c03278063dd269ea5eef82d24f2124a8e15d7b90f2fa8601266c",
-    "2ec78d556d696e208927cc503d48e4b5eb56b31abc2870c2ed2e98d6be27fc96",
-    "bun run tanstack_runner.js",
-    "We've been online over 2 hours",
-)
-
-# Hard pin-blocks for publicly confirmed malicious versions.
-# keep in sync with scripts/scan_npm_packages.py
-BLOCKED_NPM_VERSIONS: dict[str, set[str]] = {
-    # GHSA-g7cv-rxg3-hmpx -- TanStack May-11 2026 (84 versions).
-    "@tanstack/arktype-adapter": {"1.166.12", "1.166.15"},
-    "@tanstack/eslint-plugin-router": {"1.161.9", "1.161.12"},
-    "@tanstack/eslint-plugin-start": {"0.0.4", "0.0.7"},
-    "@tanstack/history": {"1.161.9", "1.161.12"},
-    "@tanstack/nitro-v2-vite-plugin": {"1.154.12", "1.154.15"},
-    "@tanstack/react-router": {"1.169.5", "1.169.8"},
-    "@tanstack/react-router-devtools": {"1.166.16", "1.166.19"},
-    "@tanstack/react-router-ssr-query": {"1.166.15", "1.166.18"},
-    "@tanstack/react-start": {"1.167.68", "1.167.71"},
-    "@tanstack/react-start-client": {"1.166.51", "1.166.54"},
-    "@tanstack/react-start-rsc": {"0.0.47", "0.0.50"},
-    "@tanstack/react-start-server": {"1.166.55", "1.166.58"},
-    "@tanstack/router-cli": {"1.166.46", "1.166.49"},
-    "@tanstack/router-core": {"1.169.5", "1.169.8"},
-    "@tanstack/router-devtools": {"1.166.16", "1.166.19"},
-    "@tanstack/router-devtools-core": {"1.167.6", "1.167.9"},
-    "@tanstack/router-generator": {"1.166.45", "1.166.48"},
-    "@tanstack/router-plugin": {"1.167.38", "1.167.41"},
-    "@tanstack/router-ssr-query-core": {"1.168.3", "1.168.6"},
-    "@tanstack/router-utils": {"1.161.11", "1.161.14"},
-    "@tanstack/router-vite-plugin": {"1.166.53", "1.166.56"},
-    "@tanstack/solid-router": {"1.169.5", "1.169.8"},
-    "@tanstack/solid-router-devtools": {"1.166.16", "1.166.19"},
-    "@tanstack/solid-router-ssr-query": {"1.166.15", "1.166.18"},
-    "@tanstack/solid-start": {"1.167.65", "1.167.68"},
-    "@tanstack/solid-start-client": {"1.166.50", "1.166.53"},
-    "@tanstack/solid-start-server": {"1.166.54", "1.166.57"},
-    "@tanstack/start-client-core": {"1.168.5", "1.168.8"},
-    "@tanstack/start-fn-stubs": {"1.161.9", "1.161.12"},
-    "@tanstack/start-plugin-core": {"1.169.23", "1.169.26"},
-    "@tanstack/start-server-core": {"1.167.33", "1.167.36"},
-    "@tanstack/start-static-server-functions": {"1.166.44", "1.166.47"},
-    "@tanstack/start-storage-context": {"1.166.38", "1.166.41"},
-    "@tanstack/valibot-adapter": {"1.166.12", "1.166.15"},
-    "@tanstack/virtual-file-routes": {"1.161.10", "1.161.13"},
-    "@tanstack/vue-router": {"1.169.5", "1.169.8"},
-    "@tanstack/vue-router-devtools": {"1.166.16", "1.166.19"},
-    "@tanstack/vue-router-ssr-query": {"1.166.15", "1.166.18"},
-    "@tanstack/vue-start": {"1.167.61", "1.167.64"},
-    "@tanstack/vue-start-client": {"1.166.46", "1.166.49"},
-    "@tanstack/vue-start-server": {"1.166.50", "1.166.53"},
-    "@tanstack/zod-adapter": {"1.166.12", "1.166.15"},
-    # Mini Shai-Hulud May-12 wave: OpenSearch JS client.
-    "@opensearch-project/opensearch": {"3.5.3", "3.6.2", "3.7.0", "3.8.0"},
-    # Mini Shai-Hulud May-12 wave: @squawk/* (22 packages, 5 versions each;
-    # https://safedep.io/mass-npm-supply-chain-attack-tanstack-mistral/).
-    "@squawk/airport-data": {"0.7.4", "0.7.5", "0.7.6", "0.7.7", "0.7.8"},
-    "@squawk/airports": {"0.6.2", "0.6.3", "0.6.4", "0.6.5", "0.6.6"},
-    "@squawk/airspace": {"0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5"},
-    "@squawk/airspace-data": {"0.5.3", "0.5.4", "0.5.5", "0.5.6", "0.5.7"},
-    "@squawk/airway-data": {"0.5.4", "0.5.5", "0.5.6", "0.5.7", "0.5.8"},
-    "@squawk/airways": {"0.4.2", "0.4.3", "0.4.4", "0.4.5", "0.4.6"},
-    "@squawk/fix-data": {"0.6.4", "0.6.5", "0.6.6", "0.6.7", "0.6.8"},
-    "@squawk/fixes": {"0.3.2", "0.3.3", "0.3.4", "0.3.5", "0.3.6"},
-    "@squawk/flight-math": {"0.5.4", "0.5.5", "0.5.6", "0.5.7", "0.5.8"},
-    "@squawk/flightplan": {"0.5.2", "0.5.3", "0.5.4", "0.5.5", "0.5.6"},
-    "@squawk/geo": {"0.4.4", "0.4.5", "0.4.6", "0.4.7", "0.4.8"},
-    "@squawk/icao-registry": {"0.5.2", "0.5.3", "0.5.4", "0.5.5", "0.5.6"},
-    "@squawk/icao-registry-data": {"0.8.4", "0.8.5", "0.8.6", "0.8.7", "0.8.8"},
-    "@squawk/mcp": {"0.9.1", "0.9.2", "0.9.3", "0.9.4", "0.9.5"},
-    "@squawk/navaid-data": {"0.6.4", "0.6.5", "0.6.6", "0.6.7", "0.6.8"},
-    "@squawk/navaids": {"0.4.2", "0.4.3", "0.4.4", "0.4.5", "0.4.6"},
-    "@squawk/notams": {"0.3.6", "0.3.7", "0.3.8", "0.3.9", "0.3.10"},
-    "@squawk/procedure-data": {"0.7.3", "0.7.4", "0.7.5", "0.7.6", "0.7.7"},
-    "@squawk/procedures": {"0.5.2", "0.5.3", "0.5.4", "0.5.5", "0.5.6"},
-    "@squawk/types": {"0.8.1", "0.8.2", "0.8.3", "0.8.4", "0.8.5"},
-    "@squawk/units": {"0.4.3", "0.4.4", "0.4.5", "0.4.6", "0.4.7"},
-    "@squawk/weather": {"0.5.6", "0.5.7", "0.5.8", "0.5.9", "0.5.10"},
-    # Mini Shai-Hulud May-12 wave: @uipath/* (64 packages, single version each;
-    # https://www.aikido.dev/blog/mini-shai-hulud-is-back-tanstack-compromised).
-    "@uipath/apollo-react": {"4.24.5"},
-    "@uipath/apollo-wind": {"2.16.2"},
-    "@uipath/cli": {"1.0.1"},
-    "@uipath/rpa-tool": {"0.9.5"},
-    "@uipath/apollo-core": {"5.9.2"},
-    "@uipath/filesystem": {"1.0.1"},
-    "@uipath/solutionpackager-tool-core": {"0.0.34"},
-    "@uipath/solution-tool": {"1.0.1"},
-    "@uipath/maestro-tool": {"1.0.1"},
-    "@uipath/codedapp-tool": {"1.0.1"},
-    "@uipath/agent-tool": {"1.0.1"},
-    "@uipath/orchestrator-tool": {"1.0.1"},
-    "@uipath/integrationservice-tool": {"1.0.2"},
-    "@uipath/rpa-legacy-tool": {"1.0.1"},
-    "@uipath/vertical-solutions-tool": {"1.0.1"},
-    "@uipath/flow-tool": {"1.0.2"},
-    "@uipath/codedagent-tool": {"1.0.1"},
-    "@uipath/common": {"1.0.1"},
-    "@uipath/resource-tool": {"1.0.1"},
-    "@uipath/auth": {"1.0.1"},
-    "@uipath/docsai-tool": {"1.0.1"},
-    "@uipath/case-tool": {"1.0.1"},
-    "@uipath/api-workflow-tool": {"1.0.1"},
-    "@uipath/test-manager-tool": {"1.0.2"},
-    "@uipath/robot": {"1.3.4"},
-    "@uipath/traces-tool": {"1.0.1"},
-    "@uipath/agent-sdk": {"1.0.2"},
-    "@uipath/integrationservice-sdk": {"1.0.2"},
-    "@uipath/maestro-sdk": {"1.0.1"},
-    "@uipath/data-fabric-tool": {"1.0.2"},
-    "@uipath/tasks-tool": {"1.0.1"},
-    "@uipath/insights-tool": {"1.0.1"},
-    "@uipath/insights-sdk": {"1.0.1"},
-    "@uipath/uipath-python-bridge": {"1.0.1"},
-    "@uipath/ap-chat": {"1.5.7"},
-    "@uipath/project-packager": {"1.1.16"},
-    "@uipath/packager-tool-case": {"0.0.9"},
-    "@uipath/packager-tool-workflowcompiler-browser": {"0.0.34"},
-    "@uipath/packager-tool-connector": {"0.0.19"},
-    "@uipath/packager-tool-workflowcompiler": {"0.0.16"},
-    "@uipath/packager-tool-webapp": {"1.0.6"},
-    "@uipath/packager-tool-apiworkflow": {"0.0.19"},
-    "@uipath/packager-tool-functions": {"0.1.1"},
-    "@uipath/widget.sdk": {"1.2.3"},
-    "@uipath/resources-tool": {"0.1.11"},
-    "@uipath/agent.sdk": {"0.0.18"},
-    "@uipath/codedagents-tool": {"0.1.12"},
-    "@uipath/aops-policy-tool": {"0.3.1"},
-    "@uipath/solution-packager": {"0.0.35"},
-    "@uipath/packager-tool-bpmn": {"0.0.9"},
-    "@uipath/packager-tool-flow": {"0.0.19"},
-    "@uipath/telemetry": {"0.0.7"},
-    "@uipath/tool-workflowcompiler": {"0.0.12"},
-    "@uipath/vss": {"0.1.6"},
-    "@uipath/solutionpackager-sdk": {"1.0.11"},
-    "@uipath/ui-widgets-multi-file-upload": {"1.0.1"},
-    "@uipath/access-policy-tool": {"0.3.1"},
-    "@uipath/context-grounding-tool": {"0.1.1"},
-    "@uipath/gov-tool": {"0.3.1"},
-    "@uipath/admin-tool": {"0.1.1"},
-    "@uipath/identity-tool": {"0.1.1"},
-    "@uipath/llmgw-tool": {"1.0.1"},
-    "@uipath/resourcecatalog-tool": {"0.1.1"},
-    "@uipath/functions-tool": {"1.0.1"},
-    "@uipath/access-policy-sdk": {"0.3.1"},
-    "@uipath/platform-tool": {"1.0.1"},
-    # Mini Shai-Hulud May-12 wave: @mistralai/* (npm) — separate from PyPI mistralai
-    # (https://www.aikido.dev/blog/mini-shai-hulud-is-back-tanstack-compromised).
-    "@mistralai/mistralai": {"2.2.2", "2.2.3", "2.2.4"},
-    "@mistralai/mistralai-gcp": {"1.7.1", "1.7.2", "1.7.3"},
-    "@mistralai/mistralai-azure": {"1.7.1", "1.7.2", "1.7.3"},
-    # Mini Shai-Hulud May-12 wave: @tallyui/* (30 entries, 10 packages)
-    # (Aikido enumeration).
-    "@tallyui/components": {"1.0.1", "1.0.2", "1.0.3"},
-    "@tallyui/connector-medusa": {"1.0.1", "1.0.2", "1.0.3"},
-    "@tallyui/connector-shopify": {"1.0.1", "1.0.2", "1.0.3"},
-    "@tallyui/connector-vendure": {"1.0.1", "1.0.2", "1.0.3"},
-    "@tallyui/connector-woocommerce": {"1.0.1", "1.0.2", "1.0.3"},
-    "@tallyui/core": {"0.2.1", "0.2.2", "0.2.3"},
-    "@tallyui/database": {"1.0.1", "1.0.2", "1.0.3"},
-    "@tallyui/pos": {"0.1.1", "0.1.2", "0.1.3"},
-    "@tallyui/storage-sqlite": {"0.2.1", "0.2.2", "0.2.3"},
-    "@tallyui/theme": {"0.2.1", "0.2.2", "0.2.3"},
-    # Mini Shai-Hulud May-12 wave: @beproduct/nestjs-auth (18 versions)
-    # (Aikido enumeration).
-    "@beproduct/nestjs-auth": {
-        "0.1.2",
-        "0.1.3",
-        "0.1.4",
-        "0.1.5",
-        "0.1.6",
-        "0.1.7",
-        "0.1.8",
-        "0.1.9",
-        "0.1.10",
-        "0.1.11",
-        "0.1.12",
-        "0.1.13",
-        "0.1.14",
-        "0.1.15",
-        "0.1.16",
-        "0.1.17",
-        "0.1.18",
-        "0.1.19",
-    },
-    # Mini Shai-Hulud May-12 wave: @draftlab/* + @draftauth/*
-    # (Aikido enumeration).
-    "@draftauth/client": {"0.2.1", "0.2.2"},
-    "@draftauth/core": {"0.13.1", "0.13.2"},
-    "@draftlab/auth": {"0.24.1", "0.24.2"},
-    "@draftlab/auth-router": {"0.5.1", "0.5.2"},
-    "@draftlab/db": {"0.16.1"},
-    # Mini Shai-Hulud May-12 wave: @taskflow-corp/cli + @tolka/cli
-    # (Aikido enumeration).
-    "@taskflow-corp/cli": {"0.1.24", "0.1.25", "0.1.26", "0.1.27", "0.1.28", "0.1.29"},
-    "@tolka/cli": {"1.0.2", "1.0.3", "1.0.4", "1.0.5", "1.0.6"},
-    # Mini Shai-Hulud May-12 wave: @ml-toolkit-ts/* + @mesadev/* + @dirigible-ai/sdk + @supersurkhet/*
-    # (Aikido enumeration).
-    "@dirigible-ai/sdk": {"0.6.2", "0.6.3"},
-    "@mesadev/rest": {"0.28.3"},
-    "@mesadev/saguaro": {"0.4.22"},
-    "@mesadev/sdk": {"0.28.3"},
-    "@ml-toolkit-ts/preprocessing": {"1.0.2", "1.0.3"},
-    "@ml-toolkit-ts/xgboost": {"1.0.3", "1.0.4"},
-    "@supersurkhet/cli": {"0.0.2", "0.0.3", "0.0.4", "0.0.5", "0.0.6", "0.0.7"},
-    "@supersurkhet/sdk": {"0.0.2", "0.0.3", "0.0.4", "0.0.5", "0.0.6", "0.0.7"},
-    # Mini Shai-Hulud May-12 wave: Unscoped packages (10 entries)
-    # (Aikido enumeration).
-    "safe-action": {"0.8.3", "0.8.4"},
-    "ts-dna": {"3.0.1", "3.0.2", "3.0.3", "3.0.4"},
-    "cross-stitch": {"1.1.3", "1.1.4", "1.1.5", "1.1.6"},
-    "cmux-agent-mcp": {"0.1.3", "0.1.4", "0.1.5", "0.1.6", "0.1.7", "0.1.8"},
-    "agentwork-cli": {"0.1.4", "0.1.5"},
-    "git-branch-selector": {"1.3.3", "1.3.4", "1.3.5", "1.3.6", "1.3.7"},
-    "wot-api": {"0.8.1", "0.8.2", "0.8.3", "0.8.4"},
-    "git-git-git": {"1.0.8", "1.0.9", "1.0.10", "1.0.11", "1.0.12"},
-    "nextmove-mcp": {"0.1.3", "0.1.4", "0.1.5", "0.1.6", "0.1.7"},
-    "ml-toolkit-ts": {"1.0.4", "1.0.5"},
-    # Cross-ecosystem Mini Shai-Hulud (Apr-30 wave): npm counterpart of
-    # PyPI lightning 2.6.2/2.6.3. Same threat actor (TeamPCP) per Semgrep,
-    # Aikido, OX Security, Resecurity. Safe version: 7.0.3 and earlier.
-    "intercom-client": {"7.0.4"},
-}
-
-CARGO_IOC_STRINGS: tuple[str, ...] = (
-    # Empty by default; the `source` origin check catches the structural
-    # pattern. Reserved for future cargo-side incidents.
-)
-
-
-# Allowed lockfile origins.
-NPM_REGISTRY_PREFIX = "https://registry.npmjs.org/"
-NPM_REGISTRY_PREFIXES_ALLOWED: tuple[str, ...] = (NPM_REGISTRY_PREFIX,)
-
-CARGO_REGISTRY_SOURCE = "registry+https://github.com/rust-lang/crates.io-index"
-
-
-# Cargo non-registry source allowlist: `(crate_name, exact_source_string)`.
-# Both must match verbatim; bumping the pinned SHA forces a re-review.
-# Unsloth's Tauri shell pulls `fix-path-env` from git because it is not
-# published to crates.io; commit c4c45d5 was reviewed when it landed.
-CARGO_SOURCE_ALLOWLIST: tuple[tuple[str, str], ...] = (
-    (
-        "fix-path-env",
-        "git+https://github.com/tauri-apps/fix-path-env-rs#"
-        "c4c45d503ea115a839aae718d02f79e7c7f0f673",
-    ),
-)
-
-
-class Finding:
-    __slots__ = ("path", "package", "kind", "detail")
-
-    def __init__(self, path: str, package: str, kind: str, detail: str) -> None:
-        self.path = path
-        self.package = package
-        self.kind = kind
-        self.detail = detail
-
-    def __str__(self) -> str:
-        return (
-            f"  [{self.kind}] {self.path}\n"
-            f"    package: {self.package}\n"
-            f"    detail:  {self.detail}"
-        )
-
-
-def _gha_escape(text: str) -> str:
-    """Escape a string for a GH Actions `::warning::`/`::error::` message.
-
-    GH Actions truncates at the first newline unless `\\n`/`\\r` are
-    escaped as `%0A`/`%0D`. `%` must be replaced first to avoid
-    double-encoding the subsequent escapes.
-    """
-    return text.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
-
-
-def audit_npm_lockfile(path: Path) -> list[Finding]:
-    findings: list[Finding] = []
-    if not path.exists():
-        # Missing lockfile is a config error, not a clean audit.
-        findings.append(
-            Finding(
-                path = str(path),
-                package = "<root>",
-                kind = "missing-lockfile",
-                detail = (
-                    "expected lockfile not found; refusing to silently "
-                    "report a clean audit for a path that was not scanned"
-                ),
-            )
-        )
-        return findings
-
-    try:
-        raw = path.read_text(encoding = "utf-8")
-    except OSError as exc:
-        # Surface as a finding instead of crashing CI with a traceback.
-        findings.append(
-            Finding(
-                path = str(path),
-                package = "<root>",
-                kind = "unreadable-lockfile",
-                detail = f"could not read file: {exc}",
-            )
-        )
-        return findings
-    try:
-        lock = json.loads(raw)
-    except json.JSONDecodeError as exc:
-        findings.append(
-            Finding(
-                path = str(path),
-                package = "<root>",
-                kind = "malformed-lockfile",
-                detail = f"could not parse as JSON: {exc}",
-            )
-        )
-        return findings
-
-    lockfile_version = lock.get("lockfileVersion")
-    if lockfile_version not in (2, 3):
-        findings.append(
-            Finding(
-                path = str(path),
-                package = "<root>",
-                kind = "unsupported-lockfile-version",
-                detail = (f"only lockfileVersion 2 or 3 audited; got {lockfile_version}"),
-            )
-        )
-
-    packages = lock.get("packages") or {}
-    for key, entry in packages.items():
-        # Empty key "" is the project root (no `resolved`); skip it.
-        if key == "":
-            continue
-        if entry.get("link"):
-            # Workspace symlink; no tarball to resolve.
-            continue
-
-        resolved = entry.get("resolved")
-        # Entries nested in another package's node_modules are bundled
-        # fold-ins covered by the parent's integrity; treat as transparent.
-        nested = key.count("/node_modules/") >= 1
-
-        # 1. resolved-URL origin.
-        if resolved is None:
-            if nested or entry.get("bundled"):
-                # Bundled / fold-in entry; covered by parent integrity.
-                pass
-            elif entry.get("version"):
-                # Top-level entry without a resolved URL is suspicious.
-                findings.append(
-                    Finding(
-                        path = str(path),
-                        package = key,
-                        kind = "missing-resolved-url",
-                        detail = (
-                            f"version={entry['version']!r} but no `resolved` "
-                            "field; lockfile is incomplete"
-                        ),
-                    )
-                )
-        else:
-            if not any(resolved.startswith(p) for p in NPM_REGISTRY_PREFIXES_ALLOWED):
-                findings.append(
-                    Finding(
-                        path = str(path),
-                        package = key,
-                        kind = "non-registry-resolved-url",
-                        detail = (
-                            f"resolved={resolved!r}; only "
-                            f"{NPM_REGISTRY_PREFIX} is permitted. Direct "
-                            "GitHub / git / file references are the "
-                            "Shai-Hulud injection vector."
-                        ),
-                    )
-                )
-
-        # 2. integrity-hash presence.
-        if resolved is not None and not entry.get("integrity"):
-            findings.append(
-                Finding(
-                    path = str(path),
-                    package = key,
-                    kind = "missing-integrity-hash",
-                    detail = (
-                        "no `integrity` field; npm cannot verify the "
-                        "tarball SHA against the registry-published hash"
-                    ),
-                )
-            )
-
-        # 3. Blocked malicious version list.
-        nm_prefix = "node_modules/"
-        pkg_name = key[len(nm_prefix) :] if key.startswith(nm_prefix) else key
-        version = entry.get("version")
-        blocked = BLOCKED_NPM_VERSIONS.get(pkg_name, set())
-        if version and version in blocked:
-            findings.append(
-                Finding(
-                    path = str(path),
-                    package = key,
-                    kind = "blocked-known-malicious",
-                    detail = (f"{pkg_name}@{version} is on the BLOCKED_NPM_VERSIONS list"),
-                )
-            )
-
-    # 4. Known IOC strings: scan the raw body to catch fields the
-    #    structural pass doesn't enumerate (scripts, optional deps, etc.).
-    for ioc in NPM_IOC_STRINGS:
-        if ioc in raw:
-            line_no = _first_line_containing(raw, ioc)
-            findings.append(
-                Finding(
-                    path = f"{path}:{line_no}" if line_no else str(path),
-                    package = "<ioc-match>",
-                    kind = "known-ioc-string",
-                    detail = (
-                        f"matched known IOC substring {ioc!r}; this is "
-                        "a public indicator of a recent supply-chain "
-                        "compromise. Refuse to install."
-                    ),
-                )
-            )
-
-    return findings
-
-
-def _first_line_containing(text: str, needle: str) -> int | None:
-    for i, line in enumerate(text.splitlines(), start = 1):
-        if needle in line:
-            return i
-    return None
-
-
-# Cargo.lock is TOML; parsed with stdlib tomllib (Python 3.11+).
-_PACKAGE_HEADER = re.compile(r"^\[\[package\]\]\s*$")
-
-
-def audit_cargo_lockfile(path: Path) -> list[Finding]:
-    findings: list[Finding] = []
-    if not path.exists():
-        # See audit_npm_lockfile: missing lockfile is a finding.
-        findings.append(
-            Finding(
-                path = str(path),
-                package = "<root>",
-                kind = "missing-lockfile",
-                detail = (
-                    "expected lockfile not found; refusing to silently "
-                    "report a clean audit for a path that was not scanned"
-                ),
-            )
-        )
-        return findings
-
-    try:
-        raw = path.read_text(encoding = "utf-8")
-    except OSError as exc:
-        findings.append(
-            Finding(
-                path = str(path),
-                package = "<root>",
-                kind = "unreadable-lockfile",
-                detail = f"could not read file: {exc}",
-            )
-        )
-        return findings
-    try:
-        import tomllib  # type: ignore[import-not-found]
-    except ImportError:
-        # Python <3.11; fall back to a tomli shim if importable.
-        try:
-            import tomli as tomllib  # type: ignore[no-redef]
-        except ImportError:
-            findings.append(
-                Finding(
-                    path = str(path),
-                    package = "<root>",
-                    kind = "missing-toml-parser",
-                    detail = (
-                        "Python 3.11+ tomllib or tomli is required to "
-                        "parse Cargo.lock; install tomli or upgrade "
-                        "Python before re-running this audit"
-                    ),
-                )
-            )
-            return findings
-
-    try:
-        lock = tomllib.loads(raw)
-    except Exception as exc:
-        findings.append(
-            Finding(
-                path = str(path),
-                package = "<root>",
-                kind = "malformed-lockfile",
-                detail = f"could not parse as TOML: {exc}",
-            )
-        )
-        return findings
-
-    for entry in lock.get("package", []):
-        name = entry.get("name") or "<unnamed>"
-        version = entry.get("version") or "<unversioned>"
-        source = entry.get("source")
-        # Workspace-local crates have no `source` field; skip them.
-        if source is None:
-            continue
-        if source != CARGO_REGISTRY_SOURCE:
-            if (name, source) in CARGO_SOURCE_ALLOWLIST:
-                # Pre-approved non-registry source pinned by SHA.
-                pass
-            else:
-                findings.append(
-                    Finding(
-                        path = str(path),
-                        package = f"{name}@{version}",
-                        kind = "non-registry-cargo-source",
-                        detail = (
-                            f"source={source!r}; only "
-                            f"{CARGO_REGISTRY_SOURCE!r} is permitted "
-                            "by default, and no allowlist entry covers "
-                            "this crate. If the source is legitimate, "
-                            "add `(name, source)` to "
-                            "CARGO_SOURCE_ALLOWLIST after reviewing the "
-                            "pinned commit."
-                        ),
-                    )
-                )
-        if not entry.get("checksum") and source == CARGO_REGISTRY_SOURCE:
-            findings.append(
-                Finding(
-                    path = str(path),
-                    package = f"{name}@{version}",
-                    kind = "missing-cargo-checksum",
-                    detail = (
-                        "registry crate without checksum; cargo cannot "
-                        "verify the downloaded source against the "
-                        "registry-published SHA"
-                    ),
-                )
-            )
-
-    for ioc in CARGO_IOC_STRINGS:
-        if ioc in raw:
-            line_no = _first_line_containing(raw, ioc)
-            findings.append(
-                Finding(
-                    path = f"{path}:{line_no}" if line_no else str(path),
-                    package = "<ioc-match>",
-                    kind = "known-ioc-string",
-                    detail = f"matched known IOC substring {ioc!r}",
-                )
-            )
-
-    return findings
-
-
-# Finding kinds split into BLOCKING vs ADVISORY for the default run mode.
-# Blocking = public attack indicators (known-malicious version, IOC
-# string). Advisory = structural anomalies that warn but don't block.
-# --strict makes every finding blocking.
-BLOCKING_KINDS: frozenset[str] = frozenset(
-    {
-        "blocked-known-malicious",
-        "known-ioc-string",
-        # A structurally broken lockfile might hide a real attack.
-        "malformed-lockfile",
-        "missing-lockfile",
-        "unreadable-lockfile",
-        "missing-toml-parser",
-    }
-)
-
-DEFAULT_NPM_LOCKFILES = (
-    "studio/frontend/package-lock.json",
-    "studio/backend/core/data_recipe/oxc-validator/package-lock.json",
-    "studio/package-lock.json",
-)
-DEFAULT_CARGO_LOCKFILES = ("studio/src-tauri/Cargo.lock",)
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(
-        description = "Pre-install lockfile supply-chain audit.",
-    )
-    parser.add_argument(
-        "--root",
-        default = str(REPO_ROOT),
-        help = "Repo root (default: parent of this script).",
-    )
-    parser.add_argument(
-        "--npm-lockfile",
-        action = "append",
-        default = None,
-        help = (
-            "Path to a package-lock.json (repeatable). "
-            "Default: studio/frontend/package-lock.json, "
-            "studio/backend/core/data_recipe/oxc-validator/package-lock.json, "
-            "and studio/package-lock.json (Tauri CLI for desktop release)."
-        ),
-    )
-    parser.add_argument(
-        "--cargo-lockfile",
-        action = "append",
-        default = None,
-        help = ("Path to a Cargo.lock (repeatable). Default: studio/src-tauri/Cargo.lock."),
-    )
-    parser.add_argument(
-        "--strict",
-        action = "store_true",
-        help = (
-            "Treat every finding as blocking (exit 1). "
-            "Default mode only blocks on known-malicious versions, "
-            "indicator-of-compromise strings, or structurally broken "
-            "lockfiles; everything else is printed as an advisory "
-            "warning with exit 0. CI should use the default; local "
-            "audits aiming for zero noise can opt in via --strict."
-        ),
-    )
-    args = parser.parse_args(argv)
-
-    # Require a real justification (>=5 chars, not a boolean-shaped token)
-    # for the skip env var. An invalid value warns and falls through to
-    # run the audit (fail-safe); a valid one warns and skips with rc=0.
-    _skip_raw = os.environ.get("UNSLOTH_LOCKFILE_AUDIT_SKIP")
-    if _skip_raw is not None:
-        _skip = _skip_raw.strip()
-        _invalid_tokens = {"", "1", "0", "true", "false", "yes", "no", "on", "off"}
-        if _skip.lower() in _invalid_tokens or len(_skip) < 5:
-            print(
-                "::warning::Lockfile audit skip REQUIRES a justification "
-                f"value (>=5 chars, not '{_skip_raw}'). Proceeding with "
-                "audit. Use e.g. UNSLOTH_LOCKFILE_AUDIT_SKIP=ticket-1234.",
-                file = sys.stderr,
-                flush = True,
-            )
-        else:
-            print(
-                f"::warning::Lockfile audit skipped: reason='{_skip}'",
-                file = sys.stderr,
-                flush = True,
-            )
-            return 0
-
-    root = Path(args.root).resolve()
-    # Explicit flags scope the scan; defaults apply only to no-args CI.
-    _user_explicit = args.npm_lockfile is not None or args.cargo_lockfile is not None
-    if _user_explicit:
-        npm_paths = [root / p for p in (args.npm_lockfile or ())]
-        cargo_paths = [root / p for p in (args.cargo_lockfile or ())]
-    else:
-        npm_paths = [root / p for p in DEFAULT_NPM_LOCKFILES]
-        cargo_paths = [root / p for p in DEFAULT_CARGO_LOCKFILES]
-
-    all_findings: list[Finding] = []
-    for p in npm_paths:
-        print(f"[lockfile-audit] npm: {p}", flush = True)
-        all_findings.extend(audit_npm_lockfile(p))
-    for p in cargo_paths:
-        print(f"[lockfile-audit] cargo: {p}", flush = True)
-        all_findings.extend(audit_cargo_lockfile(p))
-
-    if not all_findings:
-        print(
-            f"[lockfile-audit] OK: 0 findings across "
-            f"{len(npm_paths)} npm + {len(cargo_paths)} cargo lockfile(s)",
-            flush = True,
-        )
-        return 0
-
-    # Split into blocking (known-malicious / IOC / structurally broken)
-    # and advisory (everything else). Default mode prints advisories
-    # without changing the exit code; --strict makes all blocking.
-    blocking = [f for f in all_findings if f.kind in BLOCKING_KINDS]
-    advisory = [f for f in all_findings if f.kind not in BLOCKING_KINDS]
-
-    if args.strict:
-        blocking = list(all_findings)
-        advisory = []
-
-    if advisory:
-        print(
-            f"\n[lockfile-audit] {len(advisory)} advisory finding(s) "
-            "(non-blocking; pass --strict to fail the build on these):\n",
-            file = sys.stderr,
-        )
-        for f in advisory:
-            # GH Actions warning annotation; _gha_escape collapses the
-            # multi-line Finding onto one line so it renders fully in the UI.
-            print(f"::warning::{_gha_escape(str(f))}", file = sys.stderr)
-            print(file = sys.stderr)
-
-    if not blocking:
-        print(
-            f"[lockfile-audit] OK: {len(advisory)} advisory finding(s), "
-            "0 blocking. Run with --strict to escalate advisory findings.",
-            flush = True,
-        )
-        return 0
-
-    print(
-        f"\n[lockfile-audit] FAIL: {len(blocking)} blocking finding(s):\n",
-        file = sys.stderr,
-    )
-    for f in blocking:
-        # Same %-encoding rationale as the advisory branch above.
-        print(f"::error::{_gha_escape(str(f))}", file = sys.stderr)
-        print(file = sys.stderr)
-    print(
-        "[lockfile-audit] Refusing to proceed. Each blocking finding "
-        "above is either a public indicator-of-compromise, a known-"
-        "malicious pinned version, or a structurally broken lockfile. "
-        "Investigate before running `npm ci` or `cargo fetch`.",
-        file = sys.stderr,
-    )
-    return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

scripts/notebook_to_python.py

@@ -1,360 +0,0 @@
-#!/usr/bin/env python
-# coding: utf-8
-"""
-Convert Jupyter notebooks (.ipynb) to executable Python scripts (.py).
-
-Converts IPython magics to plain Python:
-    !command          -> subprocess.run('command', shell=True)
-    %cd path          -> os.chdir('path')
-    %env VAR=value    -> os.environ['VAR'] = 'value'
-    %%file filename   -> with open('filename', 'w') as f: f.write(...)
-    %%capture         -> (skipped)
-    /content/...      -> _WORKING_DIR + /...
-"""
-
-import nbformat
-import re
-import shlex
-import sys
-import os
-import urllib.request
-import urllib.parse
-from pathlib import Path
-
-
-# Allowlist of hosts for raw notebook fetches; anything else rejected before urlopen.
-_ALLOWED_NOTEBOOK_HOSTS = {
-    "raw.githubusercontent.com",
-    "gist.githubusercontent.com",
-}
-
-
-# Metacharacters that mean a `!cmd` line can't be a flat argv -> keep shell=True + review marker.
-_SHELL_METACHARS_RE = re.compile(r"\$\(|`|\|\||\||&&|>>?|<<?|\*|\?|;")
-
-
-def needs_fstring(cmd: str) -> bool:
-    """Check if command has Python variable interpolation like {var_name}."""
-    pattern = r"(?<!\$)\{([a-zA-Z_][a-zA-Z0-9_]*)\}"
-    return bool(re.search(pattern, cmd))
-
-
-def github_blob_to_raw(url: str) -> str:
-    """Convert GitHub blob URL to raw URL."""
-    # github.com/user/repo/blob/branch/path -> raw.githubusercontent.com/user/repo/branch/path
-    # Exact host match (not substring) so attacker.example.com/github.com/blob/... is not rewritten.
-    parsed = urllib.parse.urlparse(url)
-    if parsed.netloc != "github.com" or "/blob/" not in parsed.path:
-        return url
-    new_path = parsed.path.replace("/blob/", "/", 1)
-    return urllib.parse.urlunparse(
-        parsed._replace(netloc = "raw.githubusercontent.com", path = new_path)
-    )
-
-
-def download_notebook(url: str) -> tuple[str, str]:
-    """Download notebook from URL. Returns (content, filename)."""
-    raw_url = github_blob_to_raw(url)
-
-    parsed = urllib.parse.urlparse(raw_url)
-    filename = os.path.basename(urllib.parse.unquote(parsed.path))
-
-    # Host allowlist: refuse to fetch from anything we don't recognise.
-    host = parsed.hostname
-    if host not in _ALLOWED_NOTEBOOK_HOSTS:
-        raise ValueError(
-            f"Refused notebook fetch from {host!r}: not in allowlist "
-            f"{sorted(_ALLOWED_NOTEBOOK_HOSTS)}"
-        )
-
-    print(f"Downloading {url}...")
-    with urllib.request.urlopen(raw_url, timeout = 60) as response:
-        content = response.read().decode("utf-8")
-
-    return content, filename
-
-
-def is_url(path: str) -> bool:
-    """Check if path is a URL."""
-    return path.startswith("http://") or path.startswith("https://")
-
-
-def replace_colab_paths(source: str) -> str:
-    """Replace Colab-specific /content/ paths with current working directory."""
-    source = source.replace('"/content/', 'f"{_WORKING_DIR}/')
-    source = source.replace("'/content/", "f'{_WORKING_DIR}/")
-    return source
-
-
-def _emit_shell_command(indent: str, full_cmd: str, *, allow_shell: bool) -> list[str]:
-    """Render a `!cmd` notebook line as Python statements.
-
-    f-string interpolation, shell metacharacters, or multiline force
-    shell=True (shlex.split would drop operators), flagged with a
-    WARNING comment. Otherwise emit shell=False argv form. allow_shell
-    False makes shell=True emission a hard error.
-    """
-    needs_f = needs_fstring(full_cmd)
-    has_meta = bool(_SHELL_METACHARS_RE.search(full_cmd))
-    multiline = "\n" in full_cmd
-
-    must_use_shell = needs_f or has_meta or multiline
-
-    if must_use_shell:
-        if not allow_shell:
-            raise ValueError(
-                "Cell uses shell metacharacters / interpolation but "
-                "--no-allow-shell was set; refusing to emit shell=True"
-            )
-        warn = f"{indent}# WARNING: shell=True; reviewed for hostile input"
-        f_prefix = "f" if needs_f else ""
-        if multiline:
-            escaped_cmd = full_cmd.replace('"""', r"\"\"\"")
-            if escaped_cmd.rstrip().endswith('"'):
-                escaped_cmd = escaped_cmd.rstrip() + " "
-            stmt = f'{indent}subprocess.run({f_prefix}"""{escaped_cmd}""", shell=True)'
-        else:
-            stmt = f"{indent}subprocess.run({f_prefix}{full_cmd!r}, shell=True)"
-        return [warn, stmt]
-
-    return [f"{indent}subprocess.run(shlex.split({full_cmd!r}), shell=False)"]
-
-
-def convert_cell_to_python(source: str, *, allow_shell: bool = True) -> str:
-    """Convert a cell's IPython magics to plain Python."""
-    lines = source.split("\n")
-    result = []
-    i = 0
-
-    while i < len(lines):
-        line = lines[i]
-        stripped = line.strip()
-        indent = line[: len(line) - len(line.lstrip())]
-
-        if stripped.startswith("%%capture"):
-            i += 1
-            continue
-
-        if stripped.startswith("%%file "):
-            filename = stripped[7:].strip()
-            file_lines = []
-            i += 1
-            while i < len(lines):
-                file_lines.append(lines[i])
-                i += 1
-            file_content = "\n".join(file_lines)
-            file_content = file_content.replace('"""', r"\"\"\"")
-            result.append(f'{indent}with open({filename!r}, "w") as _f:')
-            result.append(f'{indent}    _f.write("""{file_content}""")')
-            continue
-
-        if stripped.startswith("!"):
-            cmd_lines = [stripped[1:]]
-            while cmd_lines[-1].rstrip().endswith("\\") and i + 1 < len(lines):
-                i += 1
-                cmd_lines.append(lines[i].strip())
-            full_cmd = "\n".join(cmd_lines)
-
-            result.extend(_emit_shell_command(indent, full_cmd, allow_shell = allow_shell))
-
-        # %cd path -> os.chdir(path)
-        elif stripped.startswith("%cd "):
-            path = stripped[4:].strip()
-            result.append(f"{indent}os.chdir({path!r})")
-
-        # %env VAR=value
-        elif stripped.startswith("%env ") and "=" in stripped:
-            match = re.match(r"%env\s+(\w+)=(.+)", stripped)
-            if match:
-                var, val = match.groups()
-                result.append(f"{indent}os.environ[{var!r}] = {val!r}")
-
-        # %env VAR
-        elif stripped.startswith("%env "):
-            var = stripped[5:].strip()
-            result.append(f"{indent}os.environ.get({var!r})")
-
-        # %pwd
-        elif stripped == "%pwd":
-            result.append(f"{indent}os.getcwd()")
-
-        else:
-            result.append(line)
-
-        i += 1
-
-    return "\n".join(result)
-
-
-def convert_notebook(
-    notebook_content: str,
-    source_name: str = "notebook",
-    *,
-    allow_shell: bool = True,
-) -> str:
-    """Convert notebook JSON content to Python script."""
-    # Parse notebook
-    if isinstance(notebook_content, str):
-        notebook = nbformat.reads(notebook_content, as_version = 4)
-    else:
-        notebook = notebook_content
-
-    lines = [
-        "#!/usr/bin/env python",
-        "# coding: utf-8",
-        f"# Converted from: {source_name}",
-        "",
-        "import shlex",
-        "import subprocess",
-        "import os",
-        "import sys",
-        "import re",
-        "",
-        "# Capture original packages before any installs",
-        "_original_packages = subprocess.run(",
-        "    [sys.executable, '-m', 'pip', 'freeze'],",
-        "    capture_output=True, text=True",
-        ").stdout",
-        "",
-        "# Working directory (replaces Colab's /content/)",
-        "_WORKING_DIR = os.getcwd()",
-        "",
-    ]
-
-    for cell in notebook.cells:
-        source = cell.source.strip()
-        if not source:
-            continue
-
-        if cell.cell_type == "code":
-            converted = convert_cell_to_python(source, allow_shell = allow_shell)
-            converted = replace_colab_paths(converted)
-            lines.append(converted)
-            lines.append("")
-
-        elif cell.cell_type == "markdown":
-            for line in source.split("\n"):
-                lines.append(f"# {line}")
-            lines.append("")
-
-    # Add package restoration at the end
-    lines.extend(
-        [
-            "",
-            "# Restore original packages (install one by one, skip failures)",
-            "for _pkg in _original_packages.strip().split('\\n'):",
-            "    if _pkg:",
-            "        subprocess.run([sys.executable, '-m', 'pip', 'install', _pkg, '-q'],",
-            "                       stderr=subprocess.DEVNULL)",
-            "",
-        ]
-    )
-
-    return "\n".join(lines)
-
-
-def convert_notebook_to_script(
-    source: str,
-    output_dir: str | None = None,
-    *,
-    allow_shell: bool = True,
-):
-    """
-    Convert a notebook to Python script.
-
-    Args:
-        source: Local file path or URL to notebook
-        output_dir: Output directory (optional, defaults to current directory)
-        allow_shell: When False, refuse to emit `shell=True` for any
-            `!cmd` cell that uses metacharacters / interpolation.
-    """
-    if is_url(source):
-        content, filename = download_notebook(source)
-        source_name = source
-    else:
-        filename = os.path.basename(source)
-        with open(source, "r", encoding = "utf-8") as f:
-            content = f.read()
-        source_name = source
-
-    output_filename = filename.replace(".ipynb", ".py")
-    output_filename = output_filename.replace("(", "").replace(")", "").replace("-", "_")
-
-    if output_dir:
-        output_path = os.path.join(output_dir, output_filename)
-    else:
-        output_path = output_filename
-
-    script = convert_notebook(content, source_name, allow_shell = allow_shell)
-
-    with open(output_path, "w", encoding = "utf-8") as f:
-        f.write(script)
-
-    print(f"Converted {source} -> {output_path}")
-    return output_path
-
-
-def main():
-    import argparse
-
-    class Formatter(argparse.ArgumentDefaultsHelpFormatter, argparse.RawDescriptionHelpFormatter):
-        pass
-
-    parser = argparse.ArgumentParser(
-        description = __doc__,
-        formatter_class = Formatter,
-        epilog = """
-Examples:
-  python notebook_to_python.py notebook.ipynb
-  python notebook_to_python.py -o scripts/ notebook1.ipynb notebook2.ipynb
-  python notebook_to_python.py --output ./converted https://github.com/user/repo/blob/main/notebook.ipynb
-  python notebook_to_python.py https://github.com/unslothai/notebooks/blob/main/nb/Oute_TTS_(1B).ipynb
-""",
-    )
-    parser.add_argument("notebooks", nargs = "+", help = "Notebook files or URLs to convert.")
-    parser.add_argument("-o", "--output", dest = "output_dir", default = ".", help = "Output directory.")
-    # Default True for backwards compat; pass --no-allow-shell for untrusted notebooks.
-    parser.add_argument(
-        "--allow-shell",
-        dest = "allow_shell",
-        action = "store_true",
-        default = True,
-        help = "Allow emitting subprocess.run(..., shell=True) for cells "
-        "that use shell metacharacters or interpolation (default).",
-    )
-    parser.add_argument(
-        "--no-allow-shell",
-        dest = "allow_shell",
-        action = "store_false",
-        help = "Refuse to emit shell=True; cells with metacharacters error out.",
-    )
-
-    args = parser.parse_args()
-
-    os.makedirs(args.output_dir, exist_ok = True)
-
-    # Track per-notebook failures; continue the loop and exit 1 if any failed.
-    failures: list[tuple[str, str]] = []
-    ok = 0
-    total = len(args.notebooks)
-    for source in args.notebooks:
-        try:
-            convert_notebook_to_script(
-                source,
-                output_dir = args.output_dir if args.output_dir != "." else None,
-                allow_shell = args.allow_shell,
-            )
-            ok += 1
-        except Exception as e:
-            print(f"ERROR converting {source}: {e}")
-            failures.append((source, f"{type(e).__name__}: {e}"))
-
-    print(
-        f"converted {ok}/{total}, {len(failures)} failed",
-        file = sys.stderr if failures else sys.stdout,
-    )
-    sys.exit(1 if failures else 0)
-
-
-if __name__ == "__main__":
-    main()

scripts/profile_startup.py

@@ -1,377 +0,0 @@
-#!/usr/bin/env python3
-# SPDX-License-Identifier: AGPL-3.0-only
-# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-
-"""Measure where Unsloth Studio's startup time goes, per platform.
-
-Nothing measured this before: the backend logs "lifespan startup completed in X ms"
-but no test or CI job asserted a budget, and studio_test_kit discards the elapsed
-time of its /healthz poll. A first local run (Linux, warm cache, fast server CPU)
-found `import main` alone costs 6.6s before the server can bind, dominated by eager
-module-level imports pulled in by the `routes` package:
-
-    torch          1930 ms self
-    unsloth_zoo     914 ms self
-    routes          779 ms self
-    transformers    524 ms self
-
-Phases measured:
-  import   `python -X importtime -c "import main"`, top cumulative + per-package self
-  spawn    process start -> first byte on stdout
-  healthz  process start -> /api/health (or /healthz) answers 200
-  lifespan the backend's own "lifespan startup completed in X ms" log line
-
-Usage:
-    python scripts/profile_startup.py --repeats 3 --json out.json
-    python scripts/profile_startup.py --import-only     # no server, no port needed
-
-Exit code is 0 unless --max-healthz-seconds is given and exceeded.
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import math
-import os
-import platform
-import re
-import shutil
-import socket
-import statistics
-import subprocess
-import sys
-import threading
-import time
-import urllib.error
-import urllib.request
-from pathlib import Path
-
-REPO_ROOT = Path(__file__).resolve().parents[1]
-BACKEND = REPO_ROOT / "studio" / "backend"
-
-_IMPORTTIME_RE = re.compile(r"import time:\s+(\d+)\s+\|\s+(\d+)\s+\|(\s*)(\S.*)")
-
-
-def _free_port() -> int:
-    with socket.socket() as s:
-        s.bind(("127.0.0.1", 0))
-        return int(s.getsockname()[1])
-
-
-def profile_imports(python: str, top: int = 15) -> dict:
-    """Cumulative and self import cost for the backend's module graph.
-
-    Run in a subprocess with -X importtime: the numbers are only meaningful for a
-    cold interpreter, and importing in-process would measure a warm sys.modules.
-    """
-    proc = subprocess.run(
-        [python, "-X", "importtime", "-c", "import sys; sys.path.insert(0, '.'); import main"],
-        cwd = BACKEND,
-        capture_output = True,
-        text = True,
-        timeout = 900,
-    )
-    rows = []
-    for line in proc.stderr.splitlines():
-        m = _IMPORTTIME_RE.match(line)
-        if m:
-            rows.append((int(m.group(1)), int(m.group(2)), m.group(4).strip()))
-    if not rows:
-        return {"ok": False, "error": (proc.stderr or proc.stdout)[-2000:]}
-    if proc.returncode != 0:
-        # Rows survive up to the failure, so any total from a partial graph is wrong.
-        return {
-            "ok": False,
-            "error": (proc.stderr or proc.stdout)[-2000:],
-            "partial_rows": len(rows),
-        }
-
-    by_cum = sorted(rows, key = lambda r: -r[1])
-    # Total comes from the `main` row, not by_cum[0]: -X importtime also prints the
-    # interpreter's own startup graph (`site`), which can outrank a trivial main.
-    main_row = next((r for r in reversed(rows) if r[2] == "main"), None)
-    if main_row is None:
-        return {
-            "ok": False,
-            "error": "no `import main` row in -X importtime output\n"
-            + (proc.stderr or proc.stdout)[-2000:],
-        }
-    self_by_pkg: dict[str, int] = {}
-    for self_us, _cum, name in rows:
-        pkg = name.split(".")[0]
-        self_by_pkg[pkg] = self_by_pkg.get(pkg, 0) + self_us
-
-    return {
-        "ok": True,
-        "total_seconds": round(main_row[1] / 1e6, 3),
-        "top_cumulative": [
-            {"module": n, "seconds": round(c / 1e6, 3)} for _s, c, n in by_cum[:top]
-        ],
-        "self_by_package_ms": {
-            k: round(v / 1000) for k, v in sorted(self_by_pkg.items(), key = lambda x: -x[1])[:top]
-        },
-    }
-
-
-def _terminate_tree(proc: subprocess.Popen) -> None:
-    """Stop the server AND its children, which on Windows are a separate process.
-
-    CI profiles `Scripts/unsloth.exe`, a distlib launcher stub that CreateProcess's
-    the venv python and waits, so terminate() reaps the stub only: the real backend
-    keeps the inherited stdout handle, the reader thread never sees EOF, and
-    --repeats strands one server per iteration on the shared UNSLOTH_STUDIO_HOME.
-    taskkill /T walks the tree, as unsloth_cli/commands/start.py already does.
-    """
-    if proc.poll() is not None:
-        return
-    if os.name == "nt":
-        try:
-            killed = subprocess.run(
-                ["taskkill", "/PID", str(proc.pid), "/T", "/F"],
-                capture_output = True,
-                timeout = 30,
-                check = False,
-            )
-            if killed.returncode == 0:
-                return
-        except Exception:
-            # taskkill missing or timed out; fall through so the stub still dies.
-            pass
-        # check=False: a nonzero taskkill does not raise, so fall through as well.
-    proc.terminate()
-
-
-def profile_launch(
-    bin_path: str,
-    port: int,
-    timeout_s: int = 300,
-) -> dict:
-    """Spawn the backend the way the desktop app does and time it to first 200."""
-    log_lines: list[str] = []
-    first_byte: list[float] = []
-    t0 = time.perf_counter()
-    proc = subprocess.Popen(
-        [bin_path, "studio", "--api-only", "-H", "127.0.0.1", "-p", str(port)],
-        cwd = REPO_ROOT,
-        stdout = subprocess.PIPE,
-        stderr = subprocess.STDOUT,
-        text = True,
-        bufsize = 1,
-    )
-
-    def _drain() -> None:
-        # Runs alongside the health polling: the first read timestamps the spawn
-        # phase, and an undrained pipe blocks the backend before it binds.
-        for line in proc.stdout:
-            if not first_byte:
-                first_byte.append(time.perf_counter() - t0)
-            log_lines.append(line.rstrip("\n"))
-
-    reader = threading.Thread(target = _drain, daemon = True)
-    reader.start()
-
-    t_healthz = None
-    deadline = t0 + timeout_s
-    try:
-        while time.perf_counter() < deadline:
-            if proc.poll() is not None:
-                break
-            if t_healthz is None:
-                for url in (
-                    f"http://127.0.0.1:{port}/api/health",
-                    f"http://127.0.0.1:{port}/healthz",
-                ):
-                    try:
-                        with urllib.request.urlopen(url, timeout = 2) as r:
-                            if r.status == 200:
-                                t_healthz = time.perf_counter() - t0
-                                break
-                    except (urllib.error.URLError, OSError, TimeoutError):
-                        pass
-            if t_healthz is not None:
-                break
-            time.sleep(0.25)
-    finally:
-        _terminate_tree(proc)
-        try:
-            # Safe: the reader drains the pipe, so the child cannot block on write().
-            proc.wait(timeout = 30)
-        except subprocess.TimeoutExpired:
-            proc.kill()
-            proc.wait()
-        reader.join(timeout = 10)
-
-    t_first_byte = first_byte[0] if first_byte else None
-    lifespan_ms = None
-    for line in log_lines:
-        m = re.search(r"lifespan startup completed in ([\d.]+)ms", line)
-        if m:
-            lifespan_ms = float(m.group(1))
-    return {
-        "spawn_seconds": round(t_first_byte, 3) if t_first_byte is not None else None,
-        "healthz_seconds": round(t_healthz, 3) if t_healthz is not None else None,
-        "lifespan_ms": lifespan_ms,
-        "reached_healthz": t_healthz is not None,
-        "log_tail": log_lines[-25:],
-    }
-
-
-def python_version_of(python: str) -> str:
-    """Version of the interpreter that runs the imports, not the one running us.
-
-    --python points at the installed Studio venv while this script runs under the
-    runner's system python, so platform.python_version() would label it wrong.
-    """
-    if python == sys.executable:
-        return platform.python_version()
-    try:
-        proc = subprocess.run(
-            [python, "-c", "import platform; print(platform.python_version())"],
-            capture_output = True,
-            text = True,
-            timeout = 60,
-        )
-        if proc.returncode == 0 and proc.stdout.strip():
-            return proc.stdout.strip()
-    except (OSError, subprocess.SubprocessError):
-        pass
-    return "unknown"
-
-
-def find_bin() -> str | None:
-    home = os.environ.get("UNSLOTH_STUDIO_HOME") or str(Path.home() / ".unsloth" / "studio")
-    names = ["unsloth.exe", "unsloth"] if platform.system() == "Windows" else ["unsloth"]
-    subdirs = ["unsloth_studio/Scripts", "unsloth_studio/bin", "bin", "Scripts"]
-    for sd in subdirs:
-        for n in names:
-            p = Path(home) / sd / n
-            if p.exists():
-                return str(p)
-    return shutil.which("unsloth")
-
-
-def main(argv: list[str]) -> int:
-    ap = argparse.ArgumentParser(
-        description = __doc__, formatter_class = argparse.RawDescriptionHelpFormatter
-    )
-    ap.add_argument(
-        "--repeats",
-        type = int,
-        default = 1,
-        help = "launch repeats; the median is reported (imports are measured once)",
-    )
-    ap.add_argument(
-        "--python",
-        default = sys.executable,
-        help = "interpreter used for the import profile (default: this one)",
-    )
-    ap.add_argument("--bin", help = "path to the unsloth CLI (default: autodetect)")
-    ap.add_argument(
-        "--import-only",
-        action = "store_true",
-        help = "skip the server phases (no install needed beyond the deps)",
-    )
-    ap.add_argument(
-        "--max-healthz-seconds",
-        type = float,
-        help = "fail if the median time to a healthy port exceeds this",
-    )
-    ap.add_argument("--json", help = "write the full report here")
-    a = ap.parse_args(argv)
-    # range(0) launches nothing, leaving the budget check with nothing to fail on.
-    if a.repeats < 1:
-        ap.error("--repeats must be at least 1")
-    # Same reason: --import-only never launches anything.
-    if a.import_only and a.max_healthz_seconds is not None:
-        ap.error("--max-healthz-seconds cannot be combined with --import-only")
-    # nan and inf parse fine as floats but `med > budget` is then always False,
-    # so the gate would report success without ever bounding anything.
-    if a.max_healthz_seconds is not None and not math.isfinite(a.max_healthz_seconds):
-        ap.error("--max-healthz-seconds must be a finite number")
-
-    report: dict = {
-        "platform": platform.system().lower(),
-        "machine": platform.machine(),
-        "python": python_version_of(a.python),
-        "cpu_count": os.cpu_count(),
-    }
-
-    print("== import graph ==")
-    report["imports"] = profile_imports(a.python)
-    imp = report["imports"]
-    if imp.get("ok"):
-        print(f"  import main: {imp['total_seconds']}s")
-        for row in imp["top_cumulative"][:8]:
-            print(f"    {row['seconds']:7.3f}s  {row['module']}")
-        print("  self time by package (ms):")
-        for k, v in list(imp["self_by_package_ms"].items())[:8]:
-            print(f"    {v:8} ms  {k}")
-    else:
-        print(f"  FAILED: {imp.get('error', '')[:400]}")
-
-    if not a.import_only:
-        bin_path = a.bin or find_bin()
-        if not bin_path:
-            print(
-                "== launch == skipped: no unsloth CLI found "
-                "(set UNSLOTH_STUDIO_HOME or pass --bin)"
-            )
-            report["launch"] = {"skipped": "no unsloth CLI found"}
-        else:
-            print(f"== launch == {bin_path}")
-            runs = []
-            for i in range(a.repeats):
-                r = profile_launch(bin_path, _free_port())
-                runs.append(r)
-                print(
-                    f"  run {i + 1}: healthz={r['healthz_seconds']}s "
-                    f"lifespan={r['lifespan_ms']}ms reached={r['reached_healthz']}"
-                )
-            got = [r["healthz_seconds"] for r in runs if r["healthz_seconds"] is not None]
-            report["launch"] = {
-                "runs": runs,
-                "failed_runs": sum(1 for r in runs if not r["reached_healthz"]),
-                "healthz_median_seconds": round(statistics.median(got), 3) if got else None,
-                "healthz_max_seconds": round(max(got), 3) if got else None,
-            }
-            if got:
-                print(
-                    f"  median time to healthy port: {report['launch']['healthz_median_seconds']}s"
-                )
-
-    if a.json:
-        Path(a.json).write_text(json.dumps(report, indent = 2), encoding = "utf-8")
-        print(f"\nwrote {a.json}")
-
-    if a.max_healthz_seconds is not None:
-        launch = report.get("launch") or {}
-        med = launch.get("healthz_median_seconds")
-        failed = launch.get("failed_runs") or 0
-        if failed:
-            # Failed launches fail the budget; dropping them would keep only the fast ones.
-            print(
-                f"::error::startup regression: {failed} of {len(launch.get('runs') or [])} "
-                f"launches never became healthy within the timeout"
-            )
-            return 1
-        if med is None:
-            # Nothing measured: exiting 0 would pass a requested budget without a
-            # single health request, so fail closed.
-            print(
-                "::error::startup regression: no healthz measurement, so the "
-                f"{a.max_healthz_seconds}s budget was never checked "
-                f"({launch.get('skipped') or 'launch phase produced no runs'})"
-            )
-            return 1
-        elif med > a.max_healthz_seconds:
-            print(
-                f"::error::startup regression: {med}s median to a healthy port "
-                f"exceeds the {a.max_healthz_seconds}s budget"
-            )
-            return 1
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main(sys.argv[1:]))

scripts/run_ruff_format.py

@@ -1,7 +1,5 @@
 #!/usr/bin/env python3
-"""Run a pre-pass (normalize def-signature magic commas + collapse short
-multi-line asserts), then `ruff format`, then the kwarg-spacing / import /
-string-merge post-pass."""
+"""Run `ruff format` followed by kwarg spacing enforcement."""
 
 from __future__ import annotations
 
@@ -17,20 +15,12 @@ def main(argv: list[str]) -> int:
     if not files:
         return 0
 
-    spacing_script = HERE / "enforce_kwargs_spacing.py"
-
-    # Pre-ruff: normalize def-signature magic commas and strip the magic comma
-    # from short multi-line asserts so ruff wraps/joins accordingly.
-    pre_cmd = [sys.executable, str(spacing_script), "--pre", *files]
-    pre_proc = subprocess.run(pre_cmd)
-    if pre_proc.returncode != 0:
-        return pre_proc.returncode
-
     ruff_cmd = [sys.executable, "-m", "ruff", "format", *files]
     ruff_proc = subprocess.run(ruff_cmd)
     if ruff_proc.returncode != 0:
         return ruff_proc.returncode
 
+    spacing_script = HERE / "enforce_kwargs_spacing.py"
     spacing_cmd = [sys.executable, str(spacing_script), *files]
     spacing_proc = subprocess.run(spacing_cmd)
     return spacing_proc.returncode

scripts/scan_npm_packages_baseline.json

@@ -1,5 +0,0 @@
-{
-  "_comment": "scan_npm_packages.py allowlist. Each entry is a HIGH/CRITICAL finding manually judged benign. Matched on (package, package-relative path, pattern, evidence hash); a new payload under an already-listed package/path/pattern reopens instead of riding the entry. severity is for review only. Regenerate with --write-baseline AFTER reviewing every line. EMPTY by design: a full scan of studio/frontend/package-lock.json (915 packages) produced 0 findings, so nothing needs suppressing and the CI gate can run enforcing (SCAN_ENFORCE=1) as-is. If a future dependency adds a reviewed-benign HIGH/CRITICAL, add it here rather than weakening a pattern.",
-  "version": 3,
-  "entries": []
-}