Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
CI: trigger Studio smokes on what they observe, run install matrices as a PR subset, fold Chat UI shards (#10689)
Daniel Han9e8b747b3745
diff --git a/.github/actions/install-unsloth-local/action.yml b/.github/actions/install-unsloth-local/action.ymlindex 445de0ac3da..f14ba17848f 100644--- a/.github/actions/install-unsloth-local/action.yml+++ b/.github/actions/install-unsloth-local/action.yml@@ -57,41 +57,15 @@ inputs:runs:using: compositesteps:- # This step is the single largest cost in CI: 92s median across 39 job runs- # in one sample, which is more total time than any test. All of it is uv- # resolving and DOWNLOADING the same wheels, in every job, every run, because- # uv's cache is per-runner and nothing carried it between them.- #- # A download cache is the safest kind there is. uv's is content-addressed by- # URL and hash, so a stale entry cannot serve wrong content -- the worst it can- # do is miss. Nothing about which packages get installed changes; they just are- # not fetched twice. That is the difference between this and caching the venv,- # which would have to reason about an editable overlay, a moving- # `unsloth-zoo @ git+main`, and absolute paths baked into console scripts.- #- # UV_CACHE_DIR is set explicitly rather than relying on ~/.cache/uv, so the- # path is the same on Linux and macOS and one cache config covers both. It is- # exported into the environment so install.sh, studio/setup.sh and every uv- # call underneath inherit it.- - name: Point uv's cache somewhere cacheable- shell: bash- run: |- echo "UV_CACHE_DIR=${{ github.workspace }}/.uv-cache" >> "$GITHUB_ENV"- mkdir -p "${{ github.workspace }}/.uv-cache"-- # Keyed on what decides the resolution, with a prefix fallback: a near-miss- # still supplies almost every wheel, which is most of the win. A download cache- # wants restore-keys for exactly this reason, where a venv cache must not have- # them.+ # The uv download cache. Delegated, like the frontend dist below, so the key has+ # exactly one definition: the Windows jobs run install.ps1 from a hand-written pwsh+ # step and never come through here, and a second copy would drift silently. The+ # reasoning lives in .github/actions/uv-cache-restore, which folds the UV_CACHE_DIR+ # setter and the restore into this one step; tests/studio/test_uv_cache_discipline.py+ # inlines them again and still checks their order against the install.- name: Restore the uv download cacheid: uv-cache- uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0- continue-on-error: true- with:- path: ${{ github.workspace }}/.uv-cache- key: uv-${{ runner.os }}-${{ hashFiles('studio/backend/requirements/**', 'pyproject.toml') }}- restore-keys: |- uv-${{ runner.os }}-+ uses: ./.github/actions/uv-cache-restore# The frontend build is the other half of this step, and unlike the wheels it is# not a download at all. Measured over 13 distinct Linux jobs on main, using the@@ -170,10 +144,7 @@ runs:# `building frontend` line fails the job) for free, in the same place the eight# five Windows job-legs get it.#- # `uv cache prune --ci` further down: uv keeps built wheels AND unpacked source- # artifacts, and only the former are worth carrying between runners. Without it- # that key grows without bound across 39 jobs and re-opens the eviction thrash- # the GGUF caches were fixed for.+ # The uv save is delegated the same way, `uv cache prune --ci` included.- name: Save the built frontenduses: ./.github/actions/frontend-dist-savewith:@@ -181,18 +152,7 @@ runs:key: ${{ steps.fe-dist.outputs.key }}- name: Save the uv download cache- if: always() && github.ref == 'refs/heads/main' && steps.uv-cache.outputs.cache-hit != 'true'- shell: bash- run: |- # Best effort: an older uv without `prune --ci` must not fail the install- # that has already succeeded.- uv cache prune --ci 2> /dev/null || true- du -sh "${{ github.workspace }}/.uv-cache" 2> /dev/null || true-- - name: Save the uv download cache (upload)- if: always() && github.ref == 'refs/heads/main' && steps.uv-cache.outputs.cache-hit != 'true'- uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0- continue-on-error: true+ uses: ./.github/actions/uv-cache-savewith:- path: ${{ github.workspace }}/.uv-cache- key: uv-${{ runner.os }}-${{ hashFiles('studio/backend/requirements/**', 'pyproject.toml') }}+ cache-hit: ${{ steps.uv-cache.outputs.cache-hit }}+ key: ${{ steps.uv-cache.outputs.key }}diff --git a/.github/actions/uv-cache-restore/action.yml b/.github/actions/uv-cache-restore/action.ymlnew file mode 100644index 00000000000..42bf018574e--- /dev/null+++ b/.github/actions/uv-cache-restore/action.yml@@ -0,0 +1,50 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.++# The uv download cache, restore half. One definition of the key, for the same reason+# frontend-dist-restore has one: the Windows jobs run install.ps1 from a hand-written pwsh+# step and never go through install-unsloth-local, so a pasted copy would drift silently.+# A download cache is the safest kind: uv's is content-addressed by URL and hash, so a+# stale entry cannot serve wrong content, only miss. Caching the VENV instead would have to+# reason about an editable overlay, a moving `unsloth-zoo @ git+main` and absolute paths+# baked into console scripts; tests/studio/test_uv_cache_discipline.py pins that+# distinction and the cold-install lanes that must never adopt this.+# UV_CACHE_DIR is set explicitly so one config covers Linux, macOS and Windows, and+# exported so install.sh, install.ps1 and studio/setup.* inherit it; install.ps1 preserves+# a custom value. ROOT-CHECKOUT ONLY: the path below is workspace-relative.++name: Restore the uv download cache+description: >-+ Point UV_CACHE_DIR at a workspace directory and restore uv's download cache+ into it, keyed on what decides the resolution. Read-only: the save is a+ separate action and runs on the default branch only.++outputs:+ cache-hit:+ description: "'true' when the exact key was restored."+ value: ${{ steps.restore.outputs.cache-hit }}+ key:+ description: The full cache key, to hand to uv-cache-save.+ value: ${{ steps.restore.outputs.cache-primary-key }}++runs:+ using: composite+ steps:+ - name: Point uv's cache somewhere cacheable+ shell: bash+ run: |+ echo "UV_CACHE_DIR=${{ github.workspace }}/.uv-cache" >> "$GITHUB_ENV"+ mkdir -p "${{ github.workspace }}/.uv-cache"++ # Keyed on what decides the resolution, with a prefix fallback: a near-miss still+ # supplies almost every wheel. A download cache wants restore-keys for exactly that+ # reason, where a venv cache must not have them. runner.os: wheels differ per platform.+ - name: Restore the uv download cache+ id: restore+ uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0+ continue-on-error: true+ with:+ path: ${{ github.workspace }}/.uv-cache+ key: uv-${{ runner.os }}-${{ hashFiles('studio/backend/requirements/**', 'pyproject.toml') }}+ restore-keys: |+ uv-${{ runner.os }}-diff --git a/.github/actions/uv-cache-save/action.yml b/.github/actions/uv-cache-save/action.ymlnew file mode 100644index 00000000000..95dc9e1eee8--- /dev/null+++ b/.github/actions/uv-cache-save/action.yml@@ -0,0 +1,66 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.++# The uv download cache, save half. Paired with uv-cache-restore, which owns the key.+# Default branch only: a PR-scoped entry is restorable only by re-runs of that same PR,+# while every PR can restore from main, so saving on PRs spends a near-full budget to evict+# main's copy, the one everyone reads. A hit is not re-uploaded either.+# `uv cache prune --ci` first: uv keeps built wheels AND unpacked source artifacts, only the+# former worth carrying, so without it the entry grows without bound and re-opens the+# eviction thrash the GGUF caches were fixed for. Best effort: an older uv without `--ci`,+# or a uv off this step's PATH, must not fail an install that already succeeded.++name: Save the uv download cache+description: >-+ Prune uv's download cache to what is worth carrying, then save it under the+ restore step's key, on the default branch only.++inputs:+ cache-hit:+ description: >-+ uv-cache-restore's `cache-hit` output. 'true' skips the save: the key is+ already present and re-uploading it is pure cost.+ required: true+ key:+ description: uv-cache-restore's `key` output.+ required: true+ save:+ description: >-+ 'false' to skip the upload. For a workflow whose triggers cannot routinely+ put github.ref on refs/heads/main (no `push`, no `schedule`), where the save+ below could only fire if a human dispatched the workflow from main by hand.+ Such a workflow consumes the cache the producers fill and declares here that+ it is not one of them, rather than carrying a save that never runs.+ required: false+ default: 'true'++runs:+ using: composite+ steps:+ - name: Prune the uv download cache to what is worth carrying+ if: >-+ github.ref == 'refs/heads/main' && inputs.cache-hit != 'true'+ && inputs.save != 'false'+ shell: bash+ run: |+ uv_bin="$(command -v uv 2> /dev/null || true)"+ for candidate in "$HOME/.local/bin/uv" "$HOME/.local/bin/uv.exe" "$HOME/.cargo/bin/uv" "$HOME/.cargo/bin/uv.exe"; do+ [ -n "$uv_bin" ] && break+ [ -x "$candidate" ] && uv_bin="$candidate"+ done+ if [ -n "$uv_bin" ]; then+ "$uv_bin" cache prune --ci 2> /dev/null || true+ else+ echo "uv is not on PATH in this step; saving the cache unpruned"+ fi+ du -sh "${{ github.workspace }}/.uv-cache" 2> /dev/null || true++ - name: Save the uv download cache+ if: >-+ github.ref == 'refs/heads/main' && inputs.cache-hit != 'true'+ && inputs.save != 'false'+ uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0+ continue-on-error: true+ with:+ path: ${{ github.workspace }}/.uv-cache+ key: ${{ inputs.key }}diff --git a/.github/ci-preempt.json b/.github/ci-preempt.jsonindex 7975a1a773f..f566e7e2142 100644--- a/.github/ci-preempt.json+++ b/.github/ci-preempt.json@@ -15,7 +15,8 @@"way to reach one leg of a matrix. So a mixed-platform workflow filed under","one class only is invisible to a pause naming the others, and its jobs on","the class being held keep refilling the pool the pause is paying for.",- "clean-machine-install-ci.yml alone is 6 linux and 7 windows legs.",+ "clean-machine-install-ci.yml alone is 6 linux and 7 windows legs on its nightly",+ "(a PR runs 2 linux and 1 windows; see .github/ci/clean-machine-matrix.yml).","","The cost of the rule is the converse: a linux pause now also takes that","workflow's 7 macOS legs down. That is the right way round. Losing coverage",diff --git a/.github/ci/clean-machine-matrix.yml b/.github/ci/clean-machine-matrix.ymlnew file mode 100644index 00000000000..150717c20cb--- /dev/null+++ b/.github/ci/clean-machine-matrix.yml@@ -0,0 +1,128 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.++# The legs of .github/workflows/clean-machine-install-ci.yml, one list per matrix job.+# `pr: true` legs run on pull_request; everything runs nightly, on push to main and on+# workflow_dispatch. The `select` job strips `pr`, so a leg's other keys are exactly what+# the steps read as `matrix.<key>`. macOS is capped at five concurrent jobs account-wide+# and the full set (20 jobs, 7 macOS) never once finished on a PR before the next push+# cancelled it, so the subset keeps one leg per claim and defers OS/arch-only legs.+# tests/studio/test_install_matrix_selection.py pins the counts and the keys.++macos:+ # `overlay` decides whether this ref's Python is under test; the pipe legs stay on the+ # released package on purpose.+ # The reported failure, in the `curl | sh` shape users run, with torch as a consumer+ # gets: the only leg that can see a truncated script or a curl: (56) from an early exit.+ - {os: macos-15, mode: mask, delivery: pipe, flags: '', experimental: false, overlay: false, pr: true}+ - {os: macos-15, mode: mask, delivery: file, flags: '', experimental: false, overlay: true, pr: true}+ # What the desktop app runs: no tty, stdin closed, TAURI markers on, legacy ~/.unsloth.+ - {os: macos-15, mode: mask, delivery: tauri, flags: '', experimental: false, overlay: true, pr: false}+ # Toolchain present but logged: uv's managed-libpython self-ID patch is the one call+ # allowed. No overlay: setuptools-scm's editable build would call git itself.+ - {os: macos-15, mode: trace, delivery: file, flags: '', experimental: false, overlay: false, pr: true}+ # --no-torch is the one macOS path that can still want a compiler (no guaranteed cp313+ # arm64 sentencepiece wheel), so probe it apart from the default path.+ - {os: macos-15, mode: mask, delivery: file, flags: '--no-torch', experimental: true, overlay: true, pr: false}+ # The next macOS image, same asserts as the macos-15 file leg.+ - {os: macos-26, mode: mask, delivery: file, flags: '', experimental: true, overlay: true, pr: false}+ # Intel pins python 3.12 and its /usr/bin/git is not CLT-provided, so it survives+ # masking. Informational only.+ - {os: macos-15-intel, mode: mask, delivery: file, flags: '', experimental: true, overlay: true, allow_working: 'git', pr: false}++linux:+ # Root + apt: _smart_apt_install self-heals from an image with no curl, git, gcc or+ # cmake. Nightly only: the nonroot leg below proves everything this one does and more.+ - label: ubuntu2404-root+ image: ubuntu:24.04+ runner: ubuntu-latest+ experimental: false+ overlay: true+ pr: false+ # The arm64 dimension of the root leg.+ - label: ubuntu2404-arm-root+ image: ubuntu:24.04+ runner: ubuntu-24.04-arm+ experimental: false+ overlay: true+ pr: false+ # No elevation, but WITH the transport the one-liner needs: no elevation path anywhere+ # on the image, no toolchain, ca-certificates + curl and nothing else. Since #7547 the+ # optional set never escalates, so this must install end to end off prebuilt llama.cpp.+ # overlay: true because the RELEASED install_python_stack.py has no "skip triton kernels+ # when git is missing" guard and would die at the final step on release lag alone.+ - label: ubuntu2404-nonroot+ image: ubuntu:24.04+ runner: ubuntu-latest+ experimental: false+ overlay: true+ nonroot: true+ pr: true+ # The same premise with the OTHER transport. install.sh falls back to wget everywhere it+ # prefers curl (729-738, 1019-1027, 3064-3067) and calls the transport missing only when+ # BOTH are gone (2077-2079), so a wget-only box (Debian netinst default) is supported on+ # paper and had never been run: the row above provisions curl, which won every probe.+ - label: ubuntu2404-nonroot-wget+ image: ubuntu:24.04+ runner: ubuntu-latest+ experimental: false+ overlay: true+ nonroot: true+ wget_only: true+ pr: false+ # No elevation AND no transport, so failing is correct: pin the exact message and prove+ # it actionable rather than a bare `curl: (56)`. No overlay: it never reaches a venv.+ - label: ubuntu2404-nonroot-notransport+ image: ubuntu:24.04+ runner: ubuntu-latest+ experimental: false+ overlay: false+ nonroot: true+ no_transport: true+ pr: true+ # Non-apt: hard-fails at install.sh:2034 today. Tolerate the install STEP, not the job:+ # job-level continue-on-error would swallow the outcome assertion too.+ - label: fedora41+ image: fedora:41+ runner: ubuntu-latest+ experimental: false+ overlay: true+ tolerate_install_failure: true+ pr: false++windows:+ - os: windows-latest+ winget: 'visible'+ experimental: false+ overlay: true+ pr: true+ # The no-winget path (LTSC / Server / managed corporate) falls back to python.org ++ # astral.sh and is where Ensure-VCRedist silently does not run, leaving torch unable to+ # load: hence the explicit `import torch` assert below. #7549 relaxed setup.ps1's+ # unconditional git gate (1750-1759), and the assert proves it took the relaxed branch+ # rather than passing on git leaking back onto PATH.+ - os: windows-latest+ winget: 'masked'+ experimental: false+ overlay: true+ pr: false+ # Windows on ARM gets a native ARM64 CPython and torchaudio publishes no win_arm64 wheel+ # (nor do pyarrow and hf-transfer), so PyTorch could not resolve until #7549 made the+ # installer prefer an emulated x64 interpreter (install.ps1:1160-1253, 1335-1353). The+ # assert below checks that outcome, not the log line announcing it.+ - os: windows-11-arm+ winget: 'visible'+ experimental: false+ overlay: true+ pr: false++windows_container_install:+ # The consumer path: install.ps1 from this ref, unsloth from PyPI, so studio/setup.ps1+ # comes out of the RELEASED wheel rather than this ref's. Both rows gate.+ - overlay: false+ pr: false+ # This ref's studio/setup.ps1 and install_python_stack.py, via UNSLOTH_CI_SOURCE_OVERLAY+ # (install.ps1:2643); without it a branch changing setup.ps1 proves nothing. On PRs too:+ # the only environment with no preinstalled VC++ runtime.+ - overlay: true+ pr: truediff --git a/.github/ci/interrupted-install-matrix.yml b/.github/ci/interrupted-install-matrix.ymlnew file mode 100644index 00000000000..e147f3dfd3f--- /dev/null+++ b/.github/ci/interrupted-install-matrix.yml@@ -0,0 +1,42 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.++# The legs of .github/workflows/interrupted-install-ci.yml, one list per matrix job.+# `pr: true` legs run on pull_request; everything runs nightly and on workflow_dispatch.+# Every leg is a hard gate, with no continue-on-error cell: a leg allowed to fail is a+# warning wearing a red icon, and the claim here is that a killed install cannot report+# itself healthy. The PR subset (10 legs, 6 macOS, five concurrent macOS jobs account-wide)+# takes one leg per verdict family on different operating systems: `studio-deps`, a partial+# venv that reports HEALTHY, and `torch`, a complete venv with nothing in it where the+# re-run must repair rather than short-circuit on the version fast path.+# tests/studio/test_install_matrix_selection.py pins the counts and the keys.++interrupt:+ # A marker, never a delay: every label prints BEFORE its work, so the kill lands inside+ # the phase, while a timed wait bets on phase duration and twice turned a leg into a+ # duplicate of the next one. This one is the reported case, killed installing structlog.+ - {os: macos-15, label: studio-deps, marker: 'studio deps', pr: true}+ # Coarse phases, earliest to latest, each leaving a different partial venv. No venv leg:+ # "Creating virtual environment" runs ~0.1s, shorter than any poll, so its kill always+ # landed in the NEXT phase and the leg duplicated this one.+ - {os: macos-15, label: torch, marker: '\[TAURI:STEP\] Installing PyTorch', pr: false}+ - {os: macos-15, label: unsloth, marker: '\[TAURI:STEP\] Installing Unsloth', pr: false}+ # The latest phase, the closest to a complete-looking install.+ - {os: macos-15, label: setup, marker: '\[TAURI:STEP\] Running Unsloth setup', pr: false}+ # Other dependency-pass sub-steps around the named one. No pip-bootstrap leg (over before+ # a poll can see it) and no base-packages leg (--local sets skip_base, so it never prints+ # and the leg ran to completion, proving nothing).+ - {os: macos-15, label: unsloth-extras, marker: 'unsloth extras', pr: false}+ # Killed before install_python_stack.py writes the manifest.+ - {os: macos-15, label: data-designer, marker: 'data designer deps', pr: false}+ # Linux: same teardown path, different package manager and process semantics.+ - {os: ubuntu-latest, label: studio-deps, marker: 'studio deps', pr: false}+ - {os: ubuntu-latest, label: torch, marker: '\[TAURI:STEP\] Installing PyTorch', pr: true}++# Windows has no process groups, so the kill path differs. Both legs are nightly only:+# the verdict families are covered on PRs by the POSIX legs.+interrupt_windows:+ # install.ps1:121 parses `--no-torch`; `-SkipTorch` matches no case there and is+ # silently dropped. The torch leg must NOT skip torch or its marker never appears.+ - {label: studio-deps, marker: 'studio deps', installArgs: '--tauri --no-torch --local', pr: false}+ - {label: torch, marker: 'Installing PyTorch', installArgs: '--tauri --local', pr: false}diff --git a/.github/scripts/select_install_matrix.py b/.github/scripts/select_install_matrix.pynew file mode 100644index 00000000000..d05cfff2b3b--- /dev/null+++ b/.github/scripts/select_install_matrix.py@@ -0,0 +1,64 @@+#!/usr/bin/env python3+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.++"""Pick the legs of an install workflow for the event that triggered it.++Reads a matrix file (`.github/ci/*-matrix.yml`: one list of legs per matrix job, each+leg carrying a `pr` flag) and prints one `<job>={"include": [...]}` line plus a+`<job>_count=<n>` line per job, in the form `$GITHUB_OUTPUT` takes. On `pull_request` only the `pr: true` legs are+emitted; on every other event (schedule, push, workflow_dispatch) all of them are. The+`pr` key never reaches the workflow: what a job sees through `matrix.<key>` is exactly+what the leg declares, so the steps are unchanged by the selection.++The output is JSON on one line per job, which is what `fromJSON()` in the consuming+`strategy.matrix` needs, and it is a mapping with a single `include` key rather than a+bare list because `matrix:` must be a mapping.+"""++from __future__ import annotations++import argparse+import json+import sys+from pathlib import Path++import yaml+++def select(legs_by_job: dict, event_name: str) -> dict[str, dict]:+ """The `{"include": [...]}` mapping per job, `pr` stripped, for one event."""+ subset = event_name == "pull_request"+ picked: dict[str, dict] = {}+ for job, legs in legs_by_job.items():+ if not isinstance(legs, list):+ raise SystemExit(f"{job}: expected a list of legs, got {type(legs).__name__}")+ include = []+ for leg in legs:+ if not isinstance(leg, dict) or "pr" not in leg:+ raise SystemExit(f"{job}: every leg needs a `pr` flag: {leg!r}")+ if subset and not leg["pr"]:+ continue+ include.append({k: v for k, v in leg.items() if k != "pr"})+ picked[job] = {"include": include}+ return picked+++def main(argv: list[str] | None = None) -> int:+ parser = argparse.ArgumentParser(description = __doc__.splitlines()[0])+ parser.add_argument("--file", required = True, type = Path, help = "the matrix file")+ parser.add_argument("--event", required = True, help = "github.event_name")+ args = parser.parse_args(argv)+ legs_by_job = yaml.safe_load(args.file.read_text(encoding = "utf-8"))+ if not isinstance(legs_by_job, dict):+ raise SystemExit(f"{args.file}: expected a mapping of job -> legs")+ for job, matrix in select(legs_by_job, args.event).items():+ # One line per output: a newline inside the JSON would end the value early.+ print(f"{job}={json.dumps(matrix, separators = (',', ':'))}")+ # An empty matrix is a workflow error, so an all-nightly job gates on this count.+ print(f"{job}_count={len(matrix['include'])}")+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/.github/workflows/clean-machine-install-ci.yml b/.github/workflows/clean-machine-install-ci.ymlindex 8c8893d7ef4..7faa05c7644 100644--- a/.github/workflows/clean-machine-install-ci.yml+++ b/.github/workflows/clean-machine-install-ci.yml@@ -37,6 +37,14 @@name: Clean machine install+# The legs live in .github/ci/clean-machine-matrix.yml, each with a `pr` flag: a+# pull_request runs the `pr: true` subset (8 of 20), while the nightly schedule, a push to+# main and workflow_dispatch run all 20, picked by the `select` job below, so a leg's keys+# are the same on both paths. Installers only: pyproject.toml and requirements/** were+# dropped from the trigger because they are the two highest-churn files in the repo and+# every push touching them queued 20 jobs, 7 on the five-slot macOS pool. The nightly keeps+# that coverage, and the Update, Backend and Core workflows install this ref anyway.+on:pull_request:paths:@@ -44,22 +52,18 @@ on:- 'install.ps1'- 'studio/setup.sh'- 'studio/setup.ps1'+ - 'studio/setup.bat'- 'studio/install_python_stack.py'# setup.sh (727) and setup.ps1 (2343, 3630, 3916) call these directly and the# overlay makes them THIS ref's code, so they decide whether a clean machine gets# a native prebuilt or a toolchain-dependent fallback.- 'studio/install_*_prebuilt.py'- 'studio/prebuilt_core.py'+ - 'studio/install_manifest.py'- 'studio/node_prebuilt_pins.json'- # The overlay exists so a constraints or requirements change is exercised here- # (see the header). update-smoke cannot stand in: it starts from a preinstalled- # Python and full developer tooling.- - 'studio/backend/requirements/**'- # The overlay builds pyproject.toml and then reaches setup.sh / setup.ps1 through- # unsloth_cli/commands/studio.py (install.sh:4254, install.ps1:2801), so a change- # to either decides whether these legs install at all. No toolchain-equipped- # workflow covers that.- - 'pyproject.toml'+ # The overlay reaches setup.sh / setup.ps1 through unsloth_cli/commands/studio.py+ # (install.sh:4254, install.ps1:2801), so a change there decides whether these+ # legs install at all. No toolchain-equipped workflow covers that.- 'unsloth_cli/commands/studio.py'- '.github/scripts/clean-machine-*.sh'- '.github/scripts/assert-llama-loads.sh'@@ -67,6 +71,8 @@ on:- '.github/scripts/virgin-windows-*.ps1'- '.github/scripts/ensure-docker-daemon.ps1'- '.github/scripts/assert-nobuild.ps1'+ - '.github/scripts/select_install_matrix.py'+ - '.github/ci/clean-machine-matrix.yml'- '.github/workflows/clean-machine-install-ci.yml'push:branches: [main]@@ -77,19 +83,25 @@ on:- 'install.ps1'- 'studio/setup.sh'- 'studio/setup.ps1'+ - 'studio/setup.bat'- 'studio/install_python_stack.py'- 'studio/install_*_prebuilt.py'- 'studio/prebuilt_core.py'+ - 'studio/install_manifest.py'- 'studio/node_prebuilt_pins.json'- - 'studio/backend/requirements/**'- - 'pyproject.toml'- 'unsloth_cli/commands/studio.py'- '.github/scripts/clean-machine-*.sh'- '.github/scripts/assert-llama-loads.sh'- '.github/scripts/virgin-windows-*.ps1'- '.github/scripts/ensure-docker-daemon.ps1'- '.github/scripts/assert-nobuild.ps1'+ - '.github/scripts/select_install_matrix.py'+ - '.github/ci/clean-machine-matrix.yml'- '.github/workflows/clean-machine-install-ci.yml'+ schedule:+ # Nightly, all 20 legs, on this ref's installers: `inputs.installer_source` is empty+ # on schedule exactly as on pull_request and push, so the tree is under test.+ - cron: '23 9 * * *'workflow_dispatch:inputs:installer_source:@@ -99,7 +111,10 @@ on:default: treeconcurrency:- group: ${{ github.workflow }}-${{ github.ref }}-${{ github.ref == 'refs/heads/main' && github.sha || '' }}+ # The event is in the group so a scheduled run and a push to main, which share a ref,+ # cannot coalesce: only one run stays pending per group, and cancel-in-progress protects+ # the running run, never the pending one, so a merge burst would drop the nightly.+ group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}-${{ github.ref == 'refs/heads/main' && github.sha || '' }}# Latest-only on a PR branch. On main this does less than it reads like: it stops# a RUNNING main job being killed, but GitHub cancels any PENDING run in the group# the moment a newer one is queued, so a merge burst still leaves only the tip.@@ -119,9 +134,47 @@ env:UNSLOTH_VERBOSE: '1'jobs:+ select:+ name: select legs+ # arm64, not ubuntu-latest: this job fronts every leg, so its queue wait is added to+ # all of them, and the arm pool starts in minutes where ubuntu-latest queues for hours.+ runs-on: ubuntu-24.04-arm+ timeout-minutes: 5+ outputs:+ macos: ${{ steps.pick.outputs.macos }}+ linux: ${{ steps.pick.outputs.linux }}+ windows: ${{ steps.pick.outputs.windows }}+ windows_container_install: ${{ steps.pick.outputs.windows_container_install }}+ # The consumer container leg is nightly-only, and an empty matrix is a workflow error+ # rather than an empty job, so the probe and the install both gate on this count.+ windows_container_install_count: ${{ steps.pick.outputs.windows_container_install_count }}+ steps:+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ with:+ persist-credentials: false++ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0+ with:+ python-version: '3.12'++ # Pinned to the PyYAML the workflow guards run under, so the file parses the same+ # way here as in tests/studio/test_install_matrix_selection.py.+ - name: Install PyYAML+ run: pip install pyyaml==6.0.2++ - name: Pick the legs for this event+ id: pick+ env:+ MATRIX_FILE: .github/ci/clean-machine-matrix.yml+ EVENT_NAME: ${{ github.event_name }}+ run: |+ python3 .github/scripts/select_install_matrix.py \+ --file "$MATRIX_FILE" --event "$EVENT_NAME" | tee -a "$GITHUB_OUTPUT"+# ── macOS: the reported failure ────────────────────────────────────────────macos:name: mac ${{ matrix.os }} / ${{ matrix.mode }} / ${{ matrix.delivery }}${{ matrix.flags && format(' {0}', matrix.flags) || '' }}+ needs: selectruns-on: ${{ matrix.os }}timeout-minutes: 40continue-on-error: ${{ matrix.experimental }}@@ -132,32 +185,11 @@ jobs:UV_CACHE_DIR: ${{ github.workspace }}/.clean-machine/uv-cacheUV_PYTHON_INSTALL_DIR: ${{ github.workspace }}/.clean-machine/uv-python# Explicit legs, not a full cross-product: the interesting dimensions are (does- # the toolchain exist) x (how the script is delivered), not every pairing.+ # the toolchain exist) x (how the script is delivered), not every pairing. The legs+ # themselves are in .github/ci/clean-machine-matrix.yml.strategy:fail-fast: false- matrix:- include:- # `overlay` decides whether this ref's Python is under test at all; see the- # header. The pipe legs stay on the released package on purpose.- #- # The reported failure, in the shape users run it, with torch because that is- # what a consumer gets.- - {os: macos-15, mode: mask, delivery: pipe, flags: '', experimental: false, overlay: false}- - {os: macos-15, mode: mask, delivery: file, flags: '', experimental: false, overlay: true}- # What the desktop app runs: no tty, stdin closed, TAURI markers on.- - {os: macos-15, mode: mask, delivery: tauri, flags: '', experimental: false, overlay: true}- # Toolchain present but logged: uv may make exactly one kind of developer-tool- # call, its managed-libpython self-ID patch. No overlay: the editable build calls- # git itself (setuptools-scm), planting evidence unrelated to the consumer path.- - {os: macos-15, mode: trace, delivery: file, flags: '', experimental: false, overlay: false}- # --no-torch is the one macOS path that can still want a compiler- # (sentencepiece has no guaranteed cp313 arm64 wheel), so probe it apart from- # the default path rather than let it hide the gate under test.- - {os: macos-15, mode: mask, delivery: file, flags: '--no-torch', experimental: true, overlay: true}- - {os: macos-26, mode: mask, delivery: file, flags: '', experimental: true, overlay: true}- # Intel pins python 3.12 and its /usr/bin/git is not CLT-provided, so it- # survives masking. Informational only.- - {os: macos-15-intel, mode: mask, delivery: file, flags: '', experimental: true, overlay: true, allow_working: 'git'}+ matrix: ${{ fromJSON(needs.select.outputs.macos) }}steps:# checkout FIRST: it needs a working git, which masking then takes away.@@ -433,6 +465,7 @@ jobs:# ── Linux: genuinely clean, via containers ────────────────────────────────linux:name: linux ${{ matrix.label }}+ needs: selectruns-on: ${{ matrix.runner }}container: ${{ matrix.image }}timeout-minutes: 40@@ -444,76 +477,7 @@ jobs:shell: bashstrategy:fail-fast: false- matrix:- include:- # Root + apt: install.sh's _smart_apt_install should self-heal from a base- # image with no curl, git, gcc or cmake at all.- - label: ubuntu2404-root- image: ubuntu:24.04- runner: ubuntu-latest- experimental: false- overlay: true- - label: ubuntu2404-arm-root- image: ubuntu:24.04- runner: ubuntu-24.04-arm- experimental: false- overlay: true- # No elevation, but WITH the transport the advertised one-liner needs: not- # root, no sudo anywhere on the image, no toolchain, ca-certificates + curl and- # nothing else. Since #7547 the optional set (cmake, git, build-essential,- # libcurl4-openssl-dev) never escalates, so this must install end to end off- # prebuilt llama.cpp, and until now nothing proved it.- #- # Gating, and overlay: true for the reason fedora41 is: the RELEASED- # install_python_stack.py has no "skip triton kernels when git is missing"- # guard, so without the overlay the run reaches the final step and dies there- # on pure release lag (staging run 30421021166: venv, frontend, torch and- # extras all fine, then `Installing triton kernels (pip) failed`).- - label: ubuntu2404-nonroot- image: ubuntu:24.04- runner: ubuntu-latest- experimental: false- overlay: true- nonroot: true- # The same premise with the OTHER transport. install.sh's download() prefers- # curl and falls back to wget (729-738), _http_get does the same for the- # connectivity probe (1019-1027), the Radeon listing repeats it (3064-3067),- # and _check_linux_deps calls the transport missing only when BOTH are gone- # (2077-2079). So a box with wget and no curl -- a Debian netinst default, and- # every image where curl was deliberately removed -- is supported on paper and- # had never been run: the nonroot row above provisions ca-certificates AND- # curl, so curl won every probe and the wget branch was only ever reasoned from- # the code. This row asserts everything that one does, plus curl proved absent- # for the whole run rather than merely unused.- - label: ubuntu2404-nonroot-wget- image: ubuntu:24.04- runner: ubuntu-latest- experimental: false- overlay: true- nonroot: true- wget_only: true- # No elevation AND no transport. apt is the only way to get curl and reaching- # apt needs elevation, so failing is correct; the point is to pin the exact- # message and prove it is actionable rather than a bare `curl: (56)`. No- # overlay: it never reaches a venv to overlay into.- - label: ubuntu2404-nonroot-notransport- image: ubuntu:24.04- runner: ubuntu-latest- experimental: false- overlay: false- nonroot: true- no_transport: true- # Non-apt: today this hard-fails at install.sh:2034. Expected; forces the- # decision on whether dnf/pacman/zypper get supported. Tolerate the install- # step, not the job, exactly as the no-transport row does: job-level- # continue-on-error would swallow the outcome assertion too, leaving it- # unable to fail the run.- - label: fedora41- image: fedora:41- runner: ubuntu-latest- experimental: false- overlay: true- tolerate_install_failure: true+ matrix: ${{ fromJSON(needs.select.outputs.linux) }}steps:- name: Describe the container's starting state@@ -939,8 +903,12 @@ jobs:# Gating, deliberately: the only job that runs the real WSL branch, and the only one that# can catch a piped install being truncated (WSL shells out to Windows interop mid-script# and interop relays the stdin it inherited). #7548 is in main, so nothing to absorb.+ #+ # Off pull_request: a 50-minute windows-latest slot per push is too much for a branch+ # that changes rarely. Not a matrix job, so it gates here, not in the matrix file.wsl:name: wsl ubuntu-24.04+ if: github.event_name != 'pull_request'runs-on: windows-latesttimeout-minutes: 50@@ -1065,41 +1033,13 @@ jobs:# ── Windows ───────────────────────────────────────────────────────────────windows:name: win ${{ matrix.os }} / winget=${{ matrix.winget }}+ needs: selectruns-on: ${{ matrix.os }}timeout-minutes: 45continue-on-error: ${{ matrix.experimental }}strategy:fail-fast: false- matrix:- include:- - os: windows-latest- winget: 'visible'- experimental: false- overlay: true- # The no-winget path (LTSC / Server / managed corporate machines) falls back to- # python.org + astral.sh and is untested today. It is also where Ensure-VCRedist- # silently does not run, leaving torch unable to load, hence the explicit- # `import torch` assert below. It used to stop at setup.ps1's unconditional "Git- # is required but could not be installed automatically" gate -- no winget, no way- # to fetch git -- and was a pinned known failure until #7549 relaxed that gate to- # the --local and llama.cpp source paths that really use git (setup.ps1:1750-1759).- # The row now gates like any other; the assert below proves it took the relaxed- # branch rather than passing on git leaking back onto PATH.- - os: windows-latest- winget: 'masked'- experimental: false- overlay: true- # Windows on ARM gets a native ARM64 CPython, and torchaudio has never published a- # win_arm64 wheel (nor have pyarrow and hf-transfer, which datasets pulls in), so- # the PyTorch step could not resolve and install.ps1 stopped at "Failed to install- # PyTorch". Pinned until #7549 made the installer prefer an x64 interpreter on an- # ARM64 host and bootstrap one when only ARM64 exists (install.ps1:1160-1253,- # 1335-1353); x64 wheels run fine emulated. The row now gates, and the assert- # below checks the outcome that fix must produce, not the log line announcing it.- - os: windows-11-arm- winget: 'visible'- experimental: false- overlay: true+ matrix: ${{ fromJSON(needs.select.outputs.windows) }}steps:- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1@@ -1467,6 +1407,9 @@ jobs:# and caches no Windows images).windows_container_probe:name: virgin win container / probe+ needs: select+ # Only a gate for the install rows: skipped with them when none is selected.+ if: needs.select.outputs.windows_container_install_count != '0'runs-on: windows-2022timeout-minutes: 30env:@@ -1544,24 +1487,15 @@ jobs:windows_container_install:name: virgin win container / overlay=${{ matrix.overlay }}- needs: windows_container_probe+ needs: [select, windows_container_probe]+ if: needs.select.outputs.windows_container_install_count != '0'runs-on: windows-2022timeout-minutes: 90env:IMAGE: mcr.microsoft.com/windows/servercore:ltsc2022strategy:fail-fast: false- matrix:- include:- # The consumer path: install.ps1 from this ref, unsloth from PyPI, so- # studio/setup.ps1 comes out of the RELEASED wheel rather than this ref's. That is- # the difference from the overlay row below; both are expected to install end to- # end and both gate.- - overlay: false- # This ref's studio/setup.ps1 and install_python_stack.py, via- # UNSLOTH_CI_SOURCE_OVERLAY (install.ps1:2643). Without it a branch changing- # setup.ps1 gets a green run proving nothing about the change.- - overlay: true+ matrix: ${{ fromJSON(needs.select.outputs.windows_container_install) }}steps:- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1diff --git a/.github/workflows/interrupted-install-ci.yml b/.github/workflows/interrupted-install-ci.ymlindex 523468373ed..974b9514546 100644--- a/.github/workflows/interrupted-install-ci.yml+++ b/.github/workflows/interrupted-install-ci.yml@@ -16,6 +16,15 @@name: Interrupted install recovery+# The legs live in .github/ci/interrupted-install-matrix.yml, each with a `pr` flag: a+# pull_request runs the `pr: true` subset (2 of 10), while a push to main, the nightly+# schedule and workflow_dispatch run all 10, picked by the `select` job below. 6 of the 10+# are macOS on an account capped at five concurrent macOS jobs, and on every PR audited+# before the split the full set was cancelled by the next push before its macOS legs had+# started. Installers plus the ready/stale predicate the probes call: pyproject.toml and+# the Tauri preflight sources were dropped because neither is an installer and both change+# far more often than the kill path does.+on:pull_request:paths:@@ -24,16 +33,8 @@ on:- 'studio/setup.sh'- 'studio/setup.ps1'- 'studio/install_python_stack.py'- - 'studio/src-tauri/src/install.rs'- - 'studio/src-tauri/src/preflight.rs'- - 'studio/src-tauri/src/preflight/**'- 'unsloth_cli/commands/studio.py'- # Every leg installs the checkout with `--local`, so this file decides the console- # script and the core deps: `-h` and `desktop-capabilities` only survive a torn- # install because typer/click/rich are declared here, not in an extra.- - 'pyproject.toml'- # studio_install_ok and verify-install, the decisions the probe asserts on, live here,- # so an install_state() accepting a missing manifest would merge unrun.+ # install_state() decides ready vs stale for every probe (commands/studio.py:501).- 'unsloth_cli/_studio_deps.py'- 'studio/install_manifest.py'# The requirement files are the phases: studio.txt declares structlog, whose absence@@ -45,13 +46,45 @@ on:- '.github/scripts/interrupt-install.sh'- '.github/scripts/interrupt-install.ps1'- '.github/scripts/interrupted_install_probe.py'+ - '.github/scripts/select_install_matrix.py'+ - '.github/ci/interrupted-install-matrix.yml'- '.github/workflows/interrupted-install-ci.yml'- '.github/scripts/retry-with-apt-lock.sh'+ # Every push to main that touches an installer runs the full set, so a merge is+ # covered at merge time and not only by the nightly.+ push:+ branches: [main]+ paths:+ - 'install.sh'+ - 'install.ps1'+ - 'studio/setup.sh'+ - 'studio/setup.ps1'+ - 'studio/install_python_stack.py'+ - 'unsloth_cli/commands/studio.py'+ # install_state() decides ready vs stale for every probe (commands/studio.py:501).+ - 'unsloth_cli/_studio_deps.py'+ - 'studio/install_manifest.py'+ - 'studio/backend/requirements/**'+ - '.github/scripts/interrupt-install.sh'+ - '.github/scripts/interrupt-install.ps1'+ - '.github/scripts/interrupted_install_probe.py'+ - '.github/scripts/select_install_matrix.py'+ - '.github/ci/interrupted-install-matrix.yml'+ - '.github/workflows/interrupted-install-ci.yml'+ - '.github/scripts/retry-with-apt-lock.sh'+ schedule:+ # Nightly, all 10 legs. Offset from clean-machine-install-ci.yml's 09:23 so the two+ # do not race for the five macOS slots.+ - cron: '41 10 * * *'workflow_dispatch:concurrency:- group: ${{ github.workflow }}-${{ github.ref }}- cancel-in-progress: true+ # The event is in the group so a scheduled run and a push to main, which share a ref,+ # cannot cancel each other; the sha makes it unique per commit on main so a merge burst+ # cannot cancel a pending run (see studio-backend-ci.yml). On a PR branch the group is+ # the ref, so a new push cancels the run for the previous one.+ group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}-${{ github.ref == 'refs/heads/main' && github.sha || '' }}+ cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}permissions:contents: read@@ -60,9 +93,45 @@ env:UNSLOTH_STUDIO_DISABLE_PUBLIC_CHECK: '1'jobs:+ select:+ name: select legs+ # arm64, not ubuntu-latest: this job fronts every leg, so its queue wait is added to+ # all of them, and the arm pool starts in minutes where ubuntu-latest queues for hours.+ runs-on: ubuntu-24.04-arm+ timeout-minutes: 5+ outputs:+ interrupt: ${{ steps.pick.outputs.interrupt }}+ interrupt_windows: ${{ steps.pick.outputs.interrupt_windows }}+ # Both Windows legs are nightly-only, and an empty matrix is a workflow error rather+ # than an empty job, so the Windows job gates on this count.+ interrupt_windows_count: ${{ steps.pick.outputs.interrupt_windows_count }}+ steps:+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ with:+ persist-credentials: false++ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0+ with:+ python-version: '3.12'++ # Pinned to the PyYAML the workflow guards run under, so the file parses the same way+ # here as in tests/studio/test_install_matrix_selection.py.+ - name: Install PyYAML+ run: pip install pyyaml==6.0.2++ - name: Pick the legs for this event+ id: pick+ env:+ MATRIX_FILE: .github/ci/interrupted-install-matrix.yml+ EVENT_NAME: ${{ github.event_name }}+ run: |+ python3 .github/scripts/select_install_matrix.py \+ --file "$MATRIX_FILE" --event "$EVENT_NAME" | tee -a "$GITHUB_OUTPUT"+# ── macOS + Linux: kill at each phase ─────────────────────────────────────interrupt:name: ${{ matrix.os }} kill@${{ matrix.label }}+ needs: selectruns-on: ${{ matrix.os }}# Above the deadlines this leg actually configures, or a slow runner is cancelled# mid-assertion and the leg proves nothing: 25 min to the marker@@ -70,46 +139,10 @@ jobs:# --help checks, two 300s deep checks, a 300s backend wait) around a repair# install. Legs land in 6-10 min in practice; this is the ceiling, not the target.timeout-minutes: 90+ # The legs are in .github/ci/interrupted-install-matrix.yml; every one is a hard gate.strategy:fail-fast: false- matrix:- include:- # Only a marker: the driver signals the moment that line appears, and no leg waits- # first. Every label prints BEFORE its work, so the kill is inside the phase at- # detection, and a delay only bets on how long the phase runs. The bet lost twice,- # both times turning a leg into a duplicate of the next one: a flat 3s wait moved- # 5 of the 12 legs of staging run 30419729244, and in 30426111484 it carried the- # macOS torch leg into "Installing Unsloth" because the PyTorch step, called- # minutes long here, finished in under three seconds.- #- # Every leg is a hard gate, with no continue-on-error cell: a leg allowed to fail- # is a warning wearing a red icon, and this workflow's whole claim is that a- # killed install cannot report itself healthy.- #- # The exact reported case: killed during the sub-step that installs structlog.- - {os: macos-15, label: studio-deps, marker: 'studio deps'}- # Coarse phases, earliest to latest -- each leaves a different partial venv.- # No venv cell: "Creating virtual environment" ran 0.107s in staging run- # 30419729244 (03:31:07.371 -> 07.478 to "Installing PyTorch"), shorter than any- # poll watching the log, so the kill landed in the NEXT phase every time it was- # tried (30423181897 and 30424366953 both) and the leg was the torch leg under a- # different label. Lost with it: a venv caught half-written, not reachable by- # interruption at this resolution, and the only loss -- the torch leg lands at the- # top of the PyTorch step, so it leaves a complete venv with nothing in it.- - {os: macos-15, label: torch, marker: '\[TAURI:STEP\] Installing PyTorch'}- - {os: macos-15, label: unsloth, marker: '\[TAURI:STEP\] Installing Unsloth'}- - {os: macos-15, label: setup, marker: '\[TAURI:STEP\] Running Unsloth setup'}- # Other dependency-pass sub-steps around the named one. No pip-bootstrap cell, same- # reason as venv: "1/10 pip bootstrap" is over before a poll can see it, so in both- # 30419729244 and 30424366953 the signal landed in "2/10 unsloth extras", the next- # cell down. No base-packages cell either: --local sets skip_base, so- # install_python_stack returns before "base packages" prints and that leg ran to- # completion, proving nothing.- - {os: macos-15, label: unsloth-extras, marker: 'unsloth extras'}- - {os: macos-15, label: data-designer, marker: 'data designer deps'}- # Linux: same teardown path, different package manager and process semantics.- - {os: ubuntu-latest, label: studio-deps, marker: 'studio deps'}- - {os: ubuntu-latest, label: torch, marker: '\[TAURI:STEP\] Installing PyTorch'}+ matrix: ${{ fromJSON(needs.select.outputs.interrupt) }}steps:- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1@@ -287,16 +320,13 @@ jobs:# different root resolution, no bundled-file overlay). Worse, "Installing PyTorch" is# only printed by Write-TauriLog (install.ps1:2440), so the torch leg's marker could# never appear. The runner is ephemeral, so the default root is safe to install into.+ needs: select+ if: needs.select.outputs.interrupt_windows_count != '0'runs-on: windows-latesttimeout-minutes: 90strategy:fail-fast: false- matrix:- include:- # install.ps1:121 parses `--no-torch`; `-SkipTorch` matches no case there and is- # silently dropped. The torch leg must NOT skip torch or its marker never appears.- - {label: studio-deps, marker: 'studio deps', installArgs: '--tauri --no-torch --local'}- - {label: torch, marker: 'Installing PyTorch', installArgs: '--tauri --local'}+ matrix: ${{ fromJSON(needs.select.outputs.interrupt_windows) }}steps:- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1diff --git a/.github/workflows/local-agent-guides-ci.yml b/.github/workflows/local-agent-guides-ci.ymlindex 871026a7bfb..035ab6dc027 100644--- a/.github/workflows/local-agent-guides-ci.yml+++ b/.github/workflows/local-agent-guides-ci.yml@@ -47,8 +47,14 @@ on:push:branches: [main]paths:- - 'unsloth_cli/**'- - 'studio/backend/routes/**'+ # The import closure of `unsloth run` (studio.py:31-33, __init__.py:70-77) plus the+ # recipe files at the package root; only unsloth_cli/tests/** is left out.+ - 'unsloth_cli/*'+ - 'unsloth_cli/commands/*.py'+ # inference.py declares every endpoint the preflight curls (/v1/models,+ # /v1/chat/completions, /v1/messages, /v1/responses); routes/** made the other+ # twenty route modules pay the full matrix for edits never requested here.+ - 'studio/backend/routes/inference.py'- 'studio/backend/main.py'- 'studio/backend/core/inference/llama_cpp.py'- 'studio/backend/models/**'@@ -58,22 +64,25 @@ on:# The install step in this workflow is `uses:` on that composite action,# so an edit to the action changes what this workflow actually runs.- '.github/actions/install-unsloth-local/action.yml'- # The dist cache moved out of install-unsloth-local so the Windows jobs could- # share one definition of its key; a change to it still has to re-run the jobs- # that depend on it.+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.- '.github/actions/frontend-dist-restore/action.yml'- '.github/actions/frontend-dist-save/action.yml'+ - '.github/actions/uv-cache-restore/action.yml'+ - '.github/actions/uv-cache-save/action.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'+ # Every GGUF download in every job goes through it.+ - '.github/scripts/hf-download-with-retry.sh'- '.github/scripts/ci-connect-prompt.txt'- '.github/scripts/ci-min-system-prompt.txt'pull_request:paths:- - 'unsloth_cli/**'- - 'studio/backend/routes/**'- # Contracts this workflow asserts that live outside routes/**: the+ - 'unsloth_cli/*'+ - 'unsloth_cli/commands/*.py'+ - 'studio/backend/routes/inference.py'+ # 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'@@ -83,15 +92,16 @@ on:- '.github/workflows/local-agent-guides-ci.yml'- '.github/scripts/retry-with-apt-lock.sh'- '.github/actions/install-unsloth-local/action.yml'- # The dist cache moved out of install-unsloth-local so the Windows jobs could- # share one definition of its key; a change to it still has to re-run the jobs- # that depend on it.+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.- '.github/actions/frontend-dist-restore/action.yml'- '.github/actions/frontend-dist-save/action.yml'+ - '.github/actions/uv-cache-restore/action.yml'+ - '.github/actions/uv-cache-save/action.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/hf-download-with-retry.sh'- '.github/scripts/ci-connect-prompt.txt'- '.github/scripts/ci-min-system-prompt.txt'diff --git a/.github/workflows/startup-profile-ci.yml b/.github/workflows/startup-profile-ci.ymlindex 5fa3af2a52f..9084c33be99 100644--- a/.github/workflows/startup-profile-ci.yml+++ b/.github/workflows/startup-profile-ci.yml@@ -55,6 +55,8 @@ on:- 'install.ps1'- '.github/actions/frontend-dist-restore/action.yml'- '.github/actions/frontend-dist-save/action.yml'+ - '.github/actions/uv-cache-restore/action.yml'+ - '.github/actions/uv-cache-save/action.yml'- '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@@ -128,6 +130,12 @@ jobs:# tests/studio/test_frontend_dist_cache.py derives this from the `on:` block rather# than allowlisting the filename, so adding `push:` here without adding the save --# or adding the save without the trigger -- goes red.+ # The uv download cache the producers fill on main. No push and no schedule here,+ # so this workflow only ever consumes it (as the dist restore below argues).+ - name: Restore the uv download cache+ id: uv-cache+ uses: ./.github/actions/uv-cache-restore+- name: Restore the built frontendid: fe-distuses: ./.github/actions/frontend-dist-restore@@ -159,6 +167,14 @@ jobs:key: ${{ steps.fe-dist.outputs.key }}save: 'false'+ # No upload, for the reason the dist save above gives: nothing here runs on main.+ - name: Declare this job a uv cache consumer, not a producer+ uses: ./.github/actions/uv-cache-save+ with:+ cache-hit: ${{ steps.uv-cache.outputs.cache-hit }}+ key: ${{ steps.uv-cache.outputs.key }}+ save: 'false'+- name: Profile startupshell: bashrun: |diff --git a/.github/workflows/studio-api-smoke.yml b/.github/workflows/studio-api-smoke.ymlindex ad2fb97aaae..7984aea5d93 100644--- a/.github/workflows/studio-api-smoke.yml+++ b/.github/workflows/studio-api-smoke.yml@@ -20,12 +20,24 @@ name: Unsloth API CIon:pull_request:paths:- - 'studio/**'- - 'unsloth/**'+ # What the test boots: the FastAPI backend, the installer that lays it down and+ # the CLI that launches it. Not studio/** plus unsloth/**, which fired the job for+ # edits it cannot observe: the install is --no-torch, so nothing under unsloth/**+ # is importable here, the frontend is built but never served (UNSLOTH_API_ONLY),+ # and src-tauri never enters the picture.+ - 'studio/backend/**'+ - 'studio/setup.sh'+ - 'studio/install_*.py'+ # install_node_prebuilt.py trusts the archives pinned here (setup.sh:1243).+ - 'studio/node_prebuilt_pins.json'+ - 'studio/prebuilt_core.py'+ - 'studio/install_manifest.py'- 'unsloth_cli/**'- 'install.sh'- 'pyproject.toml'- - 'tests/studio/**'+ # Named, not globbed: the rest of tests/studio is Playwright drivers this+ # workflow never runs.+ - 'tests/studio/studio_api_smoke.py'- '.github/workflows/studio-api-smoke.yml'- '.github/scripts/retry-with-apt-lock.sh'# Every server boot in this workflow shells out to that script, so an edit@@ -33,14 +45,16 @@ on:- '.github/scripts/boot-studio-api-only.sh'# Same for the /api/health wait that runs after a boot.- '.github/scripts/wait-for-health.sh'+ # And for the GGUF download that primes HF_HOME.+ - '.github/scripts/hf-download-with-retry.sh'# The install step in this workflow is `uses:` on that composite action,# so an edit to the action changes what this workflow actually runs.- '.github/actions/install-unsloth-local/action.yml'- # The dist cache moved out of install-unsloth-local so the Windows jobs could- # share one definition of its key; a change to it still has to re-run the jobs- # that depend on it.+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.- '.github/actions/frontend-dist-restore/action.yml'- '.github/actions/frontend-dist-save/action.yml'+ - '.github/actions/uv-cache-restore/action.yml'+ - '.github/actions/uv-cache-save/action.yml'push:branches: [main]workflow_dispatch:diff --git a/.github/workflows/studio-inference-smoke.yml b/.github/workflows/studio-inference-smoke.ymlindex 9acf500645a..5f0c4aa8214 100644--- a/.github/workflows/studio-inference-smoke.yml+++ b/.github/workflows/studio-inference-smoke.yml@@ -35,8 +35,18 @@ name: Unsloth GGUF CIon:pull_request:paths:- - 'studio/**'- - 'unsloth/**'+ # What the three phases exercise: the backend's OpenAI and Anthropic surfaces over+ # a llama.cpp prebuilt, the installer that lays them down and the CLI that boots+ # them. Not studio/** plus unsloth/**: the install is --no-torch so the training+ # library is not importable here, the frontend is never served (UNSLOTH_API_ONLY),+ # and src-tauri is never touched.+ - 'studio/backend/**'+ - 'studio/setup.sh'+ - 'studio/install_*.py'+ # install_node_prebuilt.py trusts the archives pinned here (setup.sh:1243).+ - 'studio/node_prebuilt_pins.json'+ - 'studio/prebuilt_core.py'+ - 'studio/install_manifest.py'- 'unsloth_cli/**'- 'install.sh'- 'pyproject.toml'@@ -47,14 +57,18 @@ on:- '.github/scripts/boot-studio-api-only.sh'# Same for the /api/health wait that runs after a boot.- '.github/scripts/wait-for-health.sh'+ # Every model download in every phase goes through it.+ - '.github/scripts/hf-download-with-retry.sh'+ # Phase 1 drives both SDKs through this script.+ - '.github/scripts/studio_smoke/multi_turn_chat.py'# The install step in this workflow is `uses:` on that composite action,# so an edit to the action changes what this workflow actually runs.- '.github/actions/install-unsloth-local/action.yml'- # The dist cache moved out of install-unsloth-local so the Windows jobs could- # share one definition of its key; a change to it still has to re-run the jobs- # that depend on it.+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.- '.github/actions/frontend-dist-restore/action.yml'- '.github/actions/frontend-dist-save/action.yml'+ - '.github/actions/uv-cache-restore/action.yml'+ - '.github/actions/uv-cache-save/action.yml'push:branches: [main]# Manual trigger for pre-warming HF_HOME caches on main, or re-runningdiff --git a/.github/workflows/studio-mac-install-matrix.yml b/.github/workflows/studio-mac-install-matrix.ymlindex 0ef6e88bd30..2f8e817be37 100644--- a/.github/workflows/studio-mac-install-matrix.yml+++ b/.github/workflows/studio-mac-install-matrix.yml@@ -19,6 +19,9 @@ on:# The install step in this workflow is `uses:` on that composite action,# so an edit to the action changes what this workflow actually runs.- '.github/actions/install-unsloth-local/action.yml'+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.+ - '.github/actions/uv-cache-restore/action.yml'+ - '.github/actions/uv-cache-save/action.yml'# The dist cache moved out of install-unsloth-local so the Windows jobs could# share one definition of its key; a change to it still has to re-run the jobs# that depend on it.@@ -55,6 +58,9 @@ on:# The install step in this workflow is `uses:` on that composite action,# so an edit to the action changes what this workflow actually runs.- '.github/actions/install-unsloth-local/action.yml'+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.+ - '.github/actions/uv-cache-restore/action.yml'+ - '.github/actions/uv-cache-save/action.yml'# The dist cache moved out of install-unsloth-local so the Windows jobs could# share one definition of its key; a change to it still has to re-run the jobs# that depend on it.diff --git a/.github/workflows/studio-mac-ui-smoke.yml b/.github/workflows/studio-mac-ui-smoke.ymlindex 32804639c57..68235a247f8 100644--- a/.github/workflows/studio-mac-ui-smoke.yml+++ b/.github/workflows/studio-mac-ui-smoke.yml@@ -27,11 +27,22 @@ name: Mac Unsloth UI + API + Update + Inference CIon:pull_request:paths:- - 'studio/**'- - 'unsloth/**'+ # The two halves Playwright drives, the backend and the React bundle, plus the+ # installer and CLI that put them on the box. Not studio/** and unsloth/**: the+ # install is --no-torch, so unsloth/** cannot reach the venv under test, and+ # studio/src-tauri is never built here, and this pool is capped at five jobs.+ - 'studio/backend/**'+ - 'studio/frontend/**'+ - 'studio/setup.sh'+ - 'studio/install_*.py'+ # install_node_prebuilt.py trusts the archives pinned here (setup.sh:1243).+ - 'studio/node_prebuilt_pins.json'+ - 'studio/prebuilt_core.py'+ - 'studio/install_manifest.py'- 'unsloth_cli/**'- 'install.sh'- 'pyproject.toml'+ # The Playwright drivers and studio_api_smoke.py the phases run.- 'tests/studio/**'- '.github/scripts/run-studio-permission-browser.sh'- '.github/scripts/run-studio-indicator-browser.sh'@@ -45,17 +56,14 @@ on:# The install step in this workflow is `uses:` on that composite action,# so an edit to the action changes what this workflow actually runs.- '.github/actions/install-unsloth-local/action.yml'- # The dist cache moved out of install-unsloth-local so the Windows jobs could- # share one definition of its key; a change to it still has to re-run the jobs- # that depend on it.+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.- '.github/actions/frontend-dist-restore/action.yml'- '.github/actions/frontend-dist-save/action.yml'+ - '.github/actions/uv-cache-restore/action.yml'+ - '.github/actions/uv-cache-save/action.yml'# The absorbed update phase round-trips scripts/uninstall.sh, which none# of the entries above cover.- 'scripts/uninstall.sh'- # No new entries needed for the absorbed API phase: every path- # studio-mac-api-smoke.yml watched is already covered above, and- # tests/studio/** covers studio_api_smoke.py itself.# Executed directly by this workflow: the load assertion and every model# download.- '.github/scripts/assert-llama-loads.sh'@@ -73,8 +81,14 @@ on:# this workflow tests has nothing here to back up.# clean-machine-install-ci.yml and mlx-ci.yml already do exactly this.paths:- - 'studio/**'- - 'unsloth/**'+ - 'studio/backend/**'+ - 'studio/frontend/**'+ - 'studio/setup.sh'+ - 'studio/install_*.py'+ # install_node_prebuilt.py trusts the archives pinned here (setup.sh:1243).+ - 'studio/node_prebuilt_pins.json'+ - 'studio/prebuilt_core.py'+ - 'studio/install_manifest.py'- 'unsloth_cli/**'- 'install.sh'- 'pyproject.toml'@@ -91,17 +105,14 @@ on:# The install step in this workflow is `uses:` on that composite action,# so an edit to the action changes what this workflow actually runs.- '.github/actions/install-unsloth-local/action.yml'- # The dist cache moved out of install-unsloth-local so the Windows jobs could- # share one definition of its key; a change to it still has to re-run the jobs- # that depend on it.+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.- '.github/actions/frontend-dist-restore/action.yml'- '.github/actions/frontend-dist-save/action.yml'+ - '.github/actions/uv-cache-restore/action.yml'+ - '.github/actions/uv-cache-save/action.yml'# The absorbed update phase round-trips scripts/uninstall.sh, which none# of the entries above cover.- 'scripts/uninstall.sh'- # No new entries needed for the absorbed API phase: every path- # studio-mac-api-smoke.yml watched is already covered above, and- # tests/studio/** covers studio_api_smoke.py itself.# Executed directly by this workflow: the load assertion and every model# download.- '.github/scripts/assert-llama-loads.sh'diff --git a/.github/workflows/studio-ui-smoke.yml b/.github/workflows/studio-ui-smoke.ymlindex 32db4d3075f..b52b8ffeeef 100644--- a/.github/workflows/studio-ui-smoke.yml+++ b/.github/workflows/studio-ui-smoke.yml@@ -19,13 +19,24 @@ name: Unsloth UI CIon:pull_request:paths:- - 'studio/**'- - 'unsloth/**'+ # The two halves Playwright drives, the backend and the React bundle, plus the+ # installer and CLI that put them on the box. Not studio/** and unsloth/**: the+ # install is --no-torch, so unsloth/** cannot reach the venv under test, and+ # studio/src-tauri is never built here.+ - 'studio/backend/**'+ - 'studio/frontend/**'+ - 'studio/setup.sh'+ - 'studio/install_*.py'+ # install_node_prebuilt.py trusts the archives pinned here (setup.sh:1243).+ - 'studio/node_prebuilt_pins.json'+ - 'studio/prebuilt_core.py'+ - 'studio/install_manifest.py'- 'unsloth_cli/**'- 'install.sh'- 'pyproject.toml'# The Playwright test files themselves -- a PR that ONLY edits- # the test must still trigger UI CI.+ # the test must still trigger UI CI. Kept as a directory glob, which+ # test_stt_model_search_locator_contract.py asserts.- 'tests/studio/**'- '.github/scripts/run-studio-permission-browser.sh'- '.github/scripts/run-studio-indicator-browser.sh'@@ -35,17 +46,19 @@ on:- '.github/scripts/boot-studio-api-only.sh'# Same for the /api/health wait that runs after a boot.- '.github/scripts/wait-for-health.sh'+ # And for the GGUF download that primes HF_HOME in every shard.+ - '.github/scripts/hf-download-with-retry.sh'# Both apt steps in this workflow shell out to it, so an edit to it changes# what this workflow actually runs.- '.github/scripts/retry-with-apt-lock.sh'# The install step in this workflow is `uses:` on that composite action,# so an edit to the action changes what this workflow actually runs.- '.github/actions/install-unsloth-local/action.yml'- # The dist cache moved out of install-unsloth-local so the Windows jobs could- # share one definition of its key; a change to it still has to re-run the jobs- # that depend on it.+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.- '.github/actions/frontend-dist-restore/action.yml'- '.github/actions/frontend-dist-save/action.yml'+ - '.github/actions/uv-cache-restore/action.yml'+ - '.github/actions/uv-cache-save/action.yml'push:branches: [main]workflow_dispatch:@@ -73,7 +86,7 @@ jobs:ui-smoke:name: Chat UI Tests (${{ matrix.shard }})runs-on: ubuntu-latest- # Left at 30 even though each shard now carries a quarter of the work.+ # Left at 30 even though each shard carries about half of the work.## It was briefly cut to 20 on the reasoning that a quarter of the job needs a quarter# of the budget. Staging then cancelled three shards at 20m0s inside "Linux deps", an@@ -83,21 +96,22 @@ jobs:# catch a hang, not to police the mean.timeout-minutes: 30strategy:- # Four shards, split where the job already split itself.+ # Two shards, split where the job already split itself.## This is 11 Playwright scripts run one after another against four Unsloth instances booted# one after another, and at 22.1 minutes on average it was the largest job in the# repo. The setup every shard has to repeat is small -- checkout, Linux deps,- # Install Unsloth, Playwright browsers, about 2.6 minutes -- so splitting it is- # nearly all profit in wall-clock, which is the thing being optimised. Runner- # minutes go up. That is the trade, taken deliberately.+ # Install Unsloth, Playwright browsers, about 2.6 minutes -- so splitting it was+ # nearly all profit in wall-clock. Four shards went too far: the queue wait for an+ # ubuntu-latest runner dwarfs a six-minute shard, so `banner` is folded into `chat`+ # (both install the three engines) and `picker` into `extra` (both chromium only).## The boundaries are the Unsloth instances, not an even division of scripts: a# Unsloth boot, its health wait, its bootstrap password and the scripts that drive# it have to stay on one machine. So `chat` takes 18892 and the cross-browser- # permission pass, `extra` and `banner` each boot their own 18894 (the two banner- # engines alone were 7.25 of the 17.6 minutes, which is why they are a shard), and- # `picker` takes 18898 and 18896, which are small and adjacent.+ # permission pass, then boots 18894 for the two banner passes once 18892 is down;+ # `extra` boots its own 18894, then 18898 and 18896 for the picker suites. One+ # Unsloth at a time on each runner, on its own port.## In-machine parallelism is deliberately NOT used here. These are separate runners,# so each still boots one Unsloth at a time and nothing competes for RAM.@@ -106,35 +120,29 @@ jobs:# The shard list stays a list: test_chat_ui_shards_cover_everything reads it# to prove every Playwright step lands on some shard, and an include-only# matrix hides it from that guard.- shard: [chat, extra, banner, picker]+ shard: [chat, extra]# include: entries that match an existing combination ADD fields to it rather# than creating new jobs, which is how each shard gets the engines it drives# without changing the shard set.#- # `extra` and `picker` name no engine but chromium anywhere in their steps.- # Installing webkit's system libraries for them is 181 packages and 102 MB of- # apt, which is what timed this job out on 2026-08-19:+ # `extra` names no engine but chromium anywhere in its steps. Installing webkit's+ # system libraries for it is 181 packages and 102 MB of apt, which is what timed+ # this job out on 2026-08-19:## 0 upgraded, 181 newly installed# Need to get 102 MB/114 MB of archives# Get:2 .../fonts-wqy-zenhei [7472 kB] -> 4m51s, then the attempt died#- # Fonts, X fonts and a soundfont, fetched so that two shards which never- # launch webkit could fail to fetch them. test_ui_shard_engines.py keeps this- # honest against the steps rather than against this comment.+ # Fonts, X fonts and a soundfont, fetched so that a shard which never launches+ # webkit could fail to fetch them. test_ui_shard_engines.py keeps this honest+ # against the steps rather than against this comment.include:- - shard: chat # Cross-browser permission controls drives all three- engines: chromium firefox webkit- engine_key: cfw- - shard: banner # "other engines" step drives firefox and webkit+ - shard: chat # permission controls + banner "other engines" drive all threeengines: chromium firefox webkitengine_key: cfw- shard: extraengines: chromiumengine_key: c- - shard: picker- engines: chromium- engine_key: cenv:GGUF_REPO: unsloth/gemma-3-270m-it-GGUFGGUF_VARIANT: UD-Q4_K_XL@@ -515,19 +523,19 @@ jobs:# 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)- if: matrix.shard == 'extra' || matrix.shard == 'banner'+ if: matrix.shard == 'extra' || matrix.shard == 'chat'run: |bash .github/scripts/boot-studio-api-only.sh \--port 18894 --log logs/studio_extra.log --pid-var STUDIO_EXTRA_PID- name: Wait for /api/health on 18894- if: matrix.shard == 'extra' || matrix.shard == 'banner'+ if: matrix.shard == 'extra' || matrix.shard == 'chat'run: |bash .github/scripts/wait-for-health.sh \--port 18894 --log logs/studio_extra.log --tmp /tmp/health2.json- name: Pass bootstrap pw for extra UI test- if: matrix.shard == 'extra' || matrix.shard == 'banner'+ if: matrix.shard == 'extra' || matrix.shard == 'chat'run: |OLD=$(cat ~/.unsloth/studio/auth/.bootstrap_password)NEW="CIUiExtra-$(python -c 'import secrets; print(secrets.token_urlsafe(16))')"@@ -586,7 +594,7 @@ jobs:python tests/studio/playwright_ui_font_scale.py- name: Update banner layout regression (Playwright)- if: matrix.shard == 'banner'+ if: matrix.shard == 'chat'env:BASE_URL: http://127.0.0.1:18894STUDIO_OLD_PW: ${{ env.STUDIO_EXTRA_OLD_PW }}@@ -603,7 +611,7 @@ jobs:# this runner gets to Safari. Cut down to `spot` because a third full# pass would spend minutes re-answering the first pass's questions.- name: Update banner layout, other engines (Playwright)- if: matrix.shard == 'banner'+ if: matrix.shard == 'chat'env:BASE_URL: http://127.0.0.1:18894STUDIO_OLD_PW: ${{ env.STUDIO_EXTRA_OLD_PW }}@@ -684,7 +692,7 @@ jobs:python tests/studio/playwright_declared_polls.py- name: Stop second Unsloth- if: (always()) && (matrix.shard == 'extra' || matrix.shard == 'banner')+ if: (always()) && (matrix.shard == 'extra' || matrix.shard == 'chat')run: |kill "${STUDIO_EXTRA_PID}" 2>/dev/null || truesleep 2@@ -695,26 +703,26 @@ jobs:# 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)- if: matrix.shard == 'picker'+ if: matrix.shard == 'extra'run: |bash .github/scripts/boot-studio-api-only.sh \--port 18898 --log logs/studio_modelcfg.log --pid-var STUDIO_MODELCFG_PID- name: Wait for /api/health on 18898- if: matrix.shard == 'picker'+ if: matrix.shard == 'extra'run: |bash .github/scripts/wait-for-health.sh \--port 18898 --log logs/studio_modelcfg.log --tmp /tmp/health4.json- name: Pass bootstrap pw for model-config test- if: matrix.shard == 'picker'+ if: matrix.shard == 'extra'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- if: matrix.shard == 'picker'+ if: matrix.shard == 'extra'env:BASE_URL: http://127.0.0.1:18898STUDIO_NEW_PW: ${{ env.STUDIO_MODELCFG_NEW_PW }}@@ -741,7 +749,7 @@ jobs:# /change-password itself: the bootstrap password on this instance has already been# rotated by then, so there is no first-boot flow left to drive.- name: Estimated Memory Usage row (Playwright)- if: matrix.shard == 'picker'+ if: matrix.shard == 'extra'env:BASE_URL: http://127.0.0.1:18898STUDIO_LOGIN_PW: ${{ env.STUDIO_MODELCFG_NEW_PW }}@@ -754,7 +762,7 @@ jobs:python tests/studio/playwright_memory_estimate.py- name: Stop fourth Unsloth- if: (always()) && (matrix.shard == 'picker')+ if: (always()) && (matrix.shard == 'extra')run: |kill "${STUDIO_MODELCFG_PID}" 2>/dev/null || truesleep 2@@ -763,19 +771,19 @@ jobs:# 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)- if: matrix.shard == 'picker'+ if: matrix.shard == 'extra'run: |bash .github/scripts/boot-studio-api-only.sh \--port 18896 --log logs/studio_ime.log --pid-var STUDIO_IME_PID- name: Wait for /api/health on 18896- if: matrix.shard == 'picker'+ if: matrix.shard == 'extra'run: |bash .github/scripts/wait-for-health.sh \--port 18896 --log logs/studio_ime.log --tmp /tmp/health3.json- name: Pass bootstrap pw for IME / i18n test- if: matrix.shard == 'picker'+ if: matrix.shard == 'extra'# IME smoke does the change-password against the bootstrap that# Unsloth's frontend injects into the page, so it only needs the# NEW password.@@ -785,7 +793,7 @@ jobs:echo "STUDIO_IME_NEW_PW=$NEW" >> "$GITHUB_ENV"- name: Drive IME + multilingual paste regression with Playwright- if: matrix.shard == 'picker'+ if: matrix.shard == 'extra'env:BASE_URL: http://127.0.0.1:18896STUDIO_NEW_PW: ${{ env.STUDIO_IME_NEW_PW }}@@ -796,7 +804,7 @@ jobs:python tests/studio/playwright_chat_ime_i18n.py- name: Stop third Unsloth- if: (always()) && (matrix.shard == 'picker')+ if: (always()) && (matrix.shard == 'extra')run: |kill "${STUDIO_IME_PID}" 2>/dev/null || truesleep 2diff --git a/.github/workflows/studio-update-smoke.yml b/.github/workflows/studio-update-smoke.ymlindex 674ee163e40..6bc144d1af8 100644--- a/.github/workflows/studio-update-smoke.yml+++ b/.github/workflows/studio-update-smoke.yml@@ -29,11 +29,11 @@ on:# The install step in this workflow is `uses:` on that composite action,# so an edit to the action changes what this workflow actually runs.- '.github/actions/install-unsloth-local/action.yml'- # The dist cache moved out of install-unsloth-local so the Windows jobs could- # share one definition of its key; a change to it still has to re-run the jobs- # that depend on it.+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.- '.github/actions/frontend-dist-restore/action.yml'- '.github/actions/frontend-dist-save/action.yml'+ - '.github/actions/uv-cache-restore/action.yml'+ - '.github/actions/uv-cache-save/action.yml'push:branches: [main]workflow_dispatch:diff --git a/.github/workflows/studio-windows-api-smoke.yml b/.github/workflows/studio-windows-api-smoke.ymlindex d964ee83aec..94ae8d848bb 100644--- a/.github/workflows/studio-windows-api-smoke.yml+++ b/.github/workflows/studio-windows-api-smoke.yml@@ -15,20 +15,36 @@ name: Windows Unsloth API CIon:pull_request:paths:- - 'studio/**'- - 'unsloth/**'+ # What the test boots: the backend, the Windows installer chain and the CLI.+ # studio/frontend/** stays because install.ps1 builds the bundle and the dist cache+ # key hashes it. Not unsloth/** or studio/src-tauri/**: the install is --no-torch+ # and never touches the Tauri shell.+ - 'studio/backend/**'+ - 'studio/frontend/**'+ - 'studio/setup.ps1'+ - 'studio/install_*.py'+ # install_node_prebuilt.py trusts the archives pinned here (setup.sh:1243).+ - 'studio/node_prebuilt_pins.json'+ - 'studio/prebuilt_core.py'+ - 'studio/install_manifest.py'- 'unsloth_cli/**'- 'install.ps1'- '.github/actions/frontend-dist-restore/action.yml'- '.github/actions/frontend-dist-save/action.yml'+ - '.github/actions/uv-cache-restore/action.yml'+ - '.github/actions/uv-cache-save/action.yml'- 'pyproject.toml'- - 'tests/studio/**'+ # Named, not globbed: the rest of tests/studio is Playwright drivers and+ # PowerShell units this workflow never runs.+ - 'tests/studio/studio_api_smoke.py'- '.github/workflows/studio-windows-api-smoke.yml'# Every server boot in this workflow shells out to that script, so an edit# to it changes what this workflow actually runs.- '.github/scripts/boot-studio-api-only.sh'# Same for the /api/health wait that runs after a boot.- '.github/scripts/wait-for-health.sh'+ # And for the GGUF download that primes HF_HOME.+ - '.github/scripts/hf-download-with-retry.sh'push:branches: [main]workflow_dispatch:@@ -158,6 +174,13 @@ jobs:# inputs are byte-identical; the action's own reasoning, and the assertion that# a hit was actually REUSED rather than rebuilt, live in# .github/actions/frontend-dist-restore and -save.+ # The uv download cache, which install-unsloth-local restores for the Linux and+ # macOS jobs and this hand-written pwsh install never had. install.ps1 preserves the+ # UV_CACHE_DIR the action exports; the key lives in .github/actions/uv-cache-restore.+ - name: Restore the uv download cache+ id: uv-cache+ uses: ./.github/actions/uv-cache-restore+- name: Restore the built frontendid: fe-distuses: ./.github/actions/frontend-dist-restore@@ -200,6 +223,13 @@ jobs:cache-hit: ${{ steps.fe-dist.outputs.cache-hit }}key: ${{ steps.fe-dist.outputs.key }}+ # Paired with the uv restore above: pruned to built wheels, saved on main only.+ - name: Save the uv download cache+ uses: ./.github/actions/uv-cache-save+ with:+ cache-hit: ${{ steps.uv-cache.outputs.cache-hit }}+ key: ${{ steps.uv-cache.outputs.key }}+- name: Assert install.ps1 used the Windows llama.cpp prebuiltrun: |# Filesystem-based check: it does not depend on which processdiff --git a/.github/workflows/studio-windows-inference-smoke.yml b/.github/workflows/studio-windows-inference-smoke.ymlindex 16e86b23388..df03369edbc 100644--- a/.github/workflows/studio-windows-inference-smoke.yml+++ b/.github/workflows/studio-windows-inference-smoke.yml@@ -24,12 +24,26 @@ name: Windows Unsloth GGUF CIon:pull_request:paths:- - 'studio/**'- - 'unsloth/**'+ # What the phases exercise: the backend's OpenAI and Anthropic surfaces over the+ # Windows llama.cpp prebuilt, the installer chain and the CLI. studio/frontend/**+ # stays because install.ps1 builds the bundle and the dist cache key hashes it. Not+ # unsloth/** or studio/src-tauri: --no-torch, and the Tauri shell is never built.+ - 'studio/backend/**'+ - 'studio/frontend/**'+ - 'studio/setup.ps1'+ - 'studio/install_*.py'+ # install_node_prebuilt.py trusts the archives pinned here (setup.sh:1243).+ - 'studio/node_prebuilt_pins.json'+ - 'studio/prebuilt_core.py'+ - 'studio/install_manifest.py'- 'unsloth_cli/**'- 'install.ps1'+ # The pre-install gate parses it and runs its uninstall unit test.+ - 'scripts/uninstall.ps1'- '.github/actions/frontend-dist-restore/action.yml'- '.github/actions/frontend-dist-save/action.yml'+ - '.github/actions/uv-cache-restore/action.yml'+ - '.github/actions/uv-cache-save/action.yml'- 'pyproject.toml'- 'tests/studio_setup_ps1/**'# The PowerShell unit tests this workflow runs live here. Without this a@@ -37,12 +51,18 @@ on:# runs them. Scoped to *.ps1 so python-only changes under tests/studio do# not pull in the GGUF smoke jobs.- 'tests/studio/*.ps1'+ # The Pester phase runs this guard by name.+ - 'tests/studio/test_pester_bootstrap_hardening.py'- '.github/workflows/studio-windows-inference-smoke.yml'# Every server boot in this workflow shells out to that script, so an edit# to it changes what this workflow actually runs.- '.github/scripts/boot-studio-api-only.sh'# Same for the /api/health wait that runs after a boot.- '.github/scripts/wait-for-health.sh'+ # Every model download in every phase goes through it.+ - '.github/scripts/hf-download-with-retry.sh'+ # Phase 1 drives both SDKs through this script.+ - '.github/scripts/studio_smoke/multi_turn_chat.py'push:branches: [main]workflow_dispatch:@@ -207,6 +227,13 @@ jobs:# inputs are byte-identical; the action's own reasoning, and the assertion that# a hit was actually REUSED rather than rebuilt, live in# .github/actions/frontend-dist-restore and -save.+ # The uv download cache, which install-unsloth-local restores for the Linux and+ # macOS jobs and this hand-written pwsh install never had. install.ps1 preserves the+ # UV_CACHE_DIR the action exports; the key lives in .github/actions/uv-cache-restore.+ - name: Restore the uv download cache+ id: uv-cache+ uses: ./.github/actions/uv-cache-restore+- name: Restore the built frontendid: fe-distuses: ./.github/actions/frontend-dist-restore@@ -251,6 +278,13 @@ jobs:cache-hit: ${{ steps.fe-dist.outputs.cache-hit }}key: ${{ steps.fe-dist.outputs.key }}+ # Paired with the uv restore above: pruned to built wheels, saved on main only.+ - name: Save the uv download cache+ uses: ./.github/actions/uv-cache-save+ with:+ cache-hit: ${{ steps.uv-cache.outputs.cache-hit }}+ key: ${{ steps.uv-cache.outputs.key }}+- name: Assert install.ps1 used the Windows llama.cpp prebuiltid: assert-prebuiltif: ${{ !cancelled() && steps.install.outcome == 'success' }}diff --git a/.github/workflows/studio-windows-ui-smoke.yml b/.github/workflows/studio-windows-ui-smoke.ymlindex 4412b73266b..4f3c4cd72b5 100644--- a/.github/workflows/studio-windows-ui-smoke.yml+++ b/.github/workflows/studio-windows-ui-smoke.yml@@ -13,13 +13,25 @@ name: Windows Unsloth UI CIon:pull_request:paths:- - 'studio/**'- - 'unsloth/**'+ # The two halves the lanes drive, the backend and the React bundle, plus the+ # Windows installer chain and the CLI. Not unsloth/** or studio/src-tauri: the+ # install is --no-torch and never builds the Tauri shell.+ - 'studio/backend/**'+ - 'studio/frontend/**'+ - 'studio/setup.ps1'+ - 'studio/install_*.py'+ # install_node_prebuilt.py trusts the archives pinned here (setup.sh:1243).+ - 'studio/node_prebuilt_pins.json'+ - 'studio/prebuilt_core.py'+ - 'studio/install_manifest.py'- 'unsloth_cli/**'- 'install.ps1'- '.github/actions/frontend-dist-restore/action.yml'- '.github/actions/frontend-dist-save/action.yml'+ - '.github/actions/uv-cache-restore/action.yml'+ - '.github/actions/uv-cache-save/action.yml'- 'pyproject.toml'+ # The Playwright drivers the two lanes run.- 'tests/studio/**'- '.github/scripts/run-studio-permission-browser.sh'- '.github/scripts/run-studio-indicator-browser.sh'@@ -30,6 +42,8 @@ on:- '.github/scripts/run-studio-ui-lane.sh'# Same for the /api/health wait that runs after a boot.- '.github/scripts/wait-for-health.sh'+ # And for the GGUF download that primes HF_HOME.+ - '.github/scripts/hf-download-with-retry.sh'push:branches: [main]workflow_dispatch:@@ -191,6 +205,13 @@ jobs:# inputs are byte-identical; the action's own reasoning, and the assertion that# a hit was actually REUSED rather than rebuilt, live in# .github/actions/frontend-dist-restore and -save.+ # The uv download cache, which install-unsloth-local restores for the Linux and+ # macOS jobs and this hand-written pwsh install never had. install.ps1 preserves the+ # UV_CACHE_DIR the action exports; the key lives in .github/actions/uv-cache-restore.+ - name: Restore the uv download cache+ id: uv-cache+ uses: ./.github/actions/uv-cache-restore+- name: Restore the built frontendid: fe-distuses: ./.github/actions/frontend-dist-restore@@ -242,6 +263,13 @@ jobs:cache-hit: ${{ steps.fe-dist.outputs.cache-hit }}key: ${{ steps.fe-dist.outputs.key }}+ # Paired with the uv restore above: pruned to built wheels, saved on main only.+ - name: Save the uv download cache+ uses: ./.github/actions/uv-cache-save+ with:+ cache-hit: ${{ steps.uv-cache.outputs.cache-hit }}+ key: ${{ steps.uv-cache.outputs.key }}+- name: Assert install.ps1 used the Windows llama.cpp prebuiltrun: |# The filesystem is the authority here: setup.ps1's "prebuiltdiff --git a/.github/workflows/studio-windows-update-smoke.yml b/.github/workflows/studio-windows-update-smoke.ymlindex 7cf3c2e96fd..6b2416fd269 100644--- a/.github/workflows/studio-windows-update-smoke.yml+++ b/.github/workflows/studio-windows-update-smoke.yml@@ -25,6 +25,8 @@ on:- 'install.ps1'- '.github/actions/frontend-dist-restore/action.yml'- '.github/actions/frontend-dist-save/action.yml'+ - '.github/actions/uv-cache-restore/action.yml'+ - '.github/actions/uv-cache-save/action.yml'- 'scripts/uninstall.ps1'- 'tests/studio/test_uninstall_*.ps1'- 'tests/studio/test_psmodulepath_normalization.ps1'@@ -171,6 +173,13 @@ jobs:# inputs are byte-identical; the action's own reasoning, and the assertion that# a hit was actually REUSED rather than rebuilt, live in# .github/actions/frontend-dist-restore and -save.+ # The uv download cache, which install-unsloth-local restores for the Linux and+ # macOS jobs and this hand-written pwsh install never had. install.ps1 preserves the+ # UV_CACHE_DIR the action exports; the key lives in .github/actions/uv-cache-restore.+ - name: Restore the uv download cache+ id: uv-cache+ uses: ./.github/actions/uv-cache-restore+- name: Restore the built frontendid: fe-distuses: ./.github/actions/frontend-dist-restore@@ -213,6 +222,13 @@ jobs:cache-hit: ${{ steps.fe-dist.outputs.cache-hit }}key: ${{ steps.fe-dist.outputs.key }}+ # Paired with the uv restore above: pruned to built wheels, saved on main only.+ - name: Save the uv download cache+ uses: ./.github/actions/uv-cache-save+ with:+ cache-hit: ${{ steps.uv-cache.outputs.cache-hit }}+ key: ${{ steps.uv-cache.outputs.key }}+- name: Assert install.ps1 used the Windows llama.cpp prebuiltrun: |# Filesystem-based check: it does not depend on which processdiff --git a/.github/workflows/studiobench-ci.yml b/.github/workflows/studiobench-ci.ymlindex df7c2b040d5..b3d2baa3998 100644--- a/.github/workflows/studiobench-ci.yml+++ b/.github/workflows/studiobench-ci.yml@@ -44,6 +44,11 @@ on:- 'install.sh'- 'pyproject.toml'- '.github/actions/install-unsloth-local/action.yml'+ # Reached through install-unsloth-local, which uses the dist and uv cache pairs.+ - '.github/actions/frontend-dist-restore/action.yml'+ - '.github/actions/frontend-dist-save/action.yml'+ - '.github/actions/uv-cache-restore/action.yml'+ - '.github/actions/uv-cache-save/action.yml'- '.github/scripts/boot-studio-api-only.sh'- '.github/scripts/wait-for-health.sh'# The Chromium install step shells out to this, so an edit to it changes whatdiff --git a/.github/workflows/studiobench-ui-parity.yml b/.github/workflows/studiobench-ui-parity.ymlindex eb74e82eef4..6e8421bbbeb 100644--- a/.github/workflows/studiobench-ui-parity.yml+++ b/.github/workflows/studiobench-ui-parity.yml@@ -171,6 +171,8 @@ on:- '.github/scripts/boot-studio-api-only.sh'- '.github/scripts/wait-for-health.sh'- '.github/scripts/retry-with-apt-lock.sh'+ - '.github/actions/uv-cache-restore/action.yml'+ - '.github/actions/uv-cache-save/action.yml'# No `push:` trigger. This job compares a merge base against a head; a push to# main has no such pair. It therefore never SAVES a cache either, and does not@@ -289,23 +291,12 @@ jobs:git worktree add --detach "$RUNNER_TEMP/side_a" "${{ steps.refs.outputs.merge_base }}"git worktree add --detach "$RUNNER_TEMP/side_b" "${{ steps.refs.outputs.side_b }}"- # Same key and the same reasoning as .github/actions/install-unsloth-local,- # so this job starts from the entry main already saved. A download cache is- # content-addressed by URL and hash, so the worst a stale entry can do is- # miss. Restore only: this workflow never runs on main and so never writes.- - name: Point uv's cache somewhere cacheable- run: |- echo "UV_CACHE_DIR=${{ github.workspace }}/.uv-cache" >> "$GITHUB_ENV"- mkdir -p "${{ github.workspace }}/.uv-cache"-+ # The same uv download cache install-unsloth-local restores, through the action+ # that owns its key, so this job starts from the entry main saved. An inline copy+ # of that key is the drift tests/studio/test_uv_cache_discipline.py exists to stop.- name: Restore the uv download cache- uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0- continue-on-error: true- with:- path: ${{ github.workspace }}/.uv-cache- key: uv-${{ runner.os }}-${{ hashFiles('studio/backend/requirements/**', 'pyproject.toml') }}- restore-keys: |- uv-${{ runner.os }}-+ id: uv-cache+ uses: ./.github/actions/uv-cache-restore# No frontend-dist cache here, and that is not an oversight. Its key hashes# the ROOT checkout's frontend, and the two sides of this job are two@@ -327,6 +318,14 @@ jobs:HF_TOKEN: ${{ github.event_name != 'pull_request' && secrets.HF_TOKEN || '' }}run: bash .github/scripts/parity-install-side.sh "$RUNNER_TEMP/side_b" "$HOME_B" logs/install_b.log+ # No upload: nothing here runs on main, so this job only declares itself a consumer.+ - name: Declare this job a uv cache consumer, not a producer+ uses: ./.github/actions/uv-cache-save+ with:+ cache-hit: ${{ steps.uv-cache.outputs.cache-hit }}+ key: ${{ steps.uv-cache.outputs.key }}+ save: 'false'+- name: Pin the Playwright version so the browser cache has a keyid: pwrun: |diff --git a/.github/workflows/workflow-trigger-lint.yml b/.github/workflows/workflow-trigger-lint.ymlindex 97251cc7942..5a9799decd0 100644--- a/.github/workflows/workflow-trigger-lint.yml+++ b/.github/workflows/workflow-trigger-lint.yml@@ -146,6 +146,7 @@ jobs:tests/studio/test_gguf_smoke_phases_stay_independent.py \tests/studio/test_indicator_browsers_run_in_parallel.py \tests/studio/test_inference_smoke_http_diagnostics.py \+ tests/studio/test_install_matrix_selection.py \tests/studio/test_install_phase_timing.py \tests/studio/test_installer_av_shapes.py \tests/studio/test_mac_bundled_job_phases.py \@@ -160,6 +161,7 @@ jobs:tests/studio/test_short_job_absorption.py \tests/studio/test_smoke_workflows_share_one_script.py \tests/studio/test_stt_model_search_locator_contract.py \+ tests/studio/test_studio_smokes_do_not_trigger_on_the_training_library.py \tests/studio/test_uv_cache_discipline.py \tests/studio/test_version_compat_bundle.py \tests/studio/test_windows_small_checks_stay_on_their_image.py \diff --git a/tests/studio/test_cache_budget_discipline.py b/tests/studio/test_cache_budget_discipline.pyindex 0d94dca90f8..d1d9bed8757 100644--- a/tests/studio/test_cache_budget_discipline.py+++ b/tests/studio/test_cache_budget_discipline.py@@ -732,9 +732,9 @@ def _matrix_rows(job) -> list[dict]:"""One substitution map per job the matrix can actually produce.The base lists are expanded, not just `include`. `ui-smoke` declares its shards in a- base `shard: [chat, extra, banner, picker]` and uses `include` only to attach+ base `shard: [chat, extra]` and uses `include` only to attach`engines`/`engine_key` to each, so reading `include` alone happens to give the right- four rows today -- and would silently skip a shard added to the base list without a+ rows today -- and would silently skip a shard added to the base list without amatching include entry, which GitHub still runs, with those fields empty. The emptyengine set then trips the assertion in the caller, which is the point.diff --git a/tests/studio/test_chat_ui_shards_cover_everything.py b/tests/studio/test_chat_ui_shards_cover_everything.pyindex 7903301e07d..3d9a379cc1f 100644--- a/tests/studio/test_chat_ui_shards_cover_everything.py+++ b/tests/studio/test_chat_ui_shards_cover_everything.py@@ -4,12 +4,14 @@"""Every Playwright script in Chat UI Tests belongs to exactly one shard.The job used to run 11 scripts in sequence against four Unsloth instances, at 22.1 minutes on-average, the largest single job in the repo. It is now four shards split on the Unsloth-boundaries.+average, the largest single job in the repo. It was split into four shards on the Unsloth+boundaries, and is now two: `banner` folded into `chat` and `picker` into `extra`, because+four cells of 3 to 9 minutes each queued about two hours for a runner while the account ran+30 to 35 jobs at once. Two cells of about 12 minutes take half the slots.The failure mode that matters is not a broken shard, which is loud. It is a step whose`if:` names no shard, or names one that does not exist, or is dropped from the matrix: the-step then runs nowhere, the job is green on all four shards, and a Playwright regression+step then runs nowhere, the job is green on every shard, and a Playwright regressionsuite has silently stopped existing. Nothing else in CI would notice, because a test thatdoes not run cannot fail.diff --git a/tests/studio/test_install_matrix_selection.py b/tests/studio/test_install_matrix_selection.pynew file mode 100644index 00000000000..fb1abbe6e82--- /dev/null+++ b/tests/studio/test_install_matrix_selection.py@@ -0,0 +1,240 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""The install workflows run a PR subset of their legs and the whole set nightly.++clean-machine-install-ci.yml (20 legs, 7 on macOS) and interrupted-install-ci.yml (10+legs, 6 on macOS) used to run every leg on every pull_request that touched an installer,+against an account capped at five concurrent macOS jobs. On the 20 PRs audited before+the split not one of those runs finished: each was cancelled by the next push while its+macOS legs were still queued, and while they queued they held the macOS pool against+every other job in the org.++The legs now live in .github/ci/*-matrix.yml with a `pr` flag each, and a `select` job+hands every matrix job the `include` list for the event+(.github/scripts/select_install_matrix.py). This file pins what that split relies on:++* the matrix files parse and every leg has the keys its job's steps read, because a+ leg missing a key no longer fails at YAML time but at `matrix.<key>` time on a runner;+* the PR subset per job is what the workflow header says it is, and the clean-machine+ subset keeps a macOS leg, so tests/studio/test_macos_slots_per_commit.py still counts+ the file as a macOS workflow;+* the `select` job is the only producer, every matrix job takes its legs from it, and a+ job whose PR subset is empty gates on the `_count` output rather than expanding an+ empty matrix, which is a workflow error;+* the emitted JSON never carries the `pr` key, so what a job sees is exactly the leg.+"""++from __future__ import annotations++import json+import re+import subprocess+import sys+from pathlib import Path++import pytest+import yaml++REPO = Path(__file__).resolve().parents[2]+WORKFLOWS = REPO / ".github" / "workflows"+SELECTOR = REPO / ".github" / "scripts" / "select_install_matrix.py"++# workflow -> (matrix file, {job: (all legs, PR legs)})+EXPECTED = {+ "clean-machine-install-ci.yml": (+ ".github/ci/clean-machine-matrix.yml",+ {"macos": (7, 3), "linux": (6, 2), "windows": (3, 1), "windows_container_install": (2, 1)},+ ),+ "interrupted-install-ci.yml": (+ ".github/ci/interrupted-install-matrix.yml",+ {"interrupt": (8, 2), "interrupt-windows": (2, 0)},+ ),+}++# Keys every leg of a job must carry, stated here rather than derived from the legs: a+# leg that drops `overlay` renders `${{ matrix.overlay }}` empty and quietly tests the+# released package, so the list that catches that cannot be computed from the legs.+# Anything else a job reads (`nonroot`, `wget_only`, `allow_working`, ...) is an optional+# flag read with a truthiness test.+REQUIRED_KEYS = {+ "macos": {"os", "mode", "delivery", "flags", "experimental", "overlay"},+ "linux": {"label", "image", "runner", "experimental", "overlay"},+ "windows": {"os", "winget", "experimental", "overlay"},+ "windows_container_install": {"overlay"},+ "interrupt": {"os", "label", "marker"},+ "interrupt-windows": {"label", "marker", "installArgs"},+}++_SELECTED = re.compile(r"^\$\{\{\s*fromJSON\(needs\.select\.outputs\.([\w-]+)\)\s*\}\}$")+_MATRIX_KEY = re.compile(r"matrix\.([\w-]+)")+++def _key(jid: str) -> str:+ """The matrix-file key and select output for a job id: outputs cannot carry `-`."""+ return jid.replace("-", "_")+++def _doc(name: str) -> dict:+ return yaml.safe_load((WORKFLOWS / name).read_text(encoding = "utf-8"))+++def _legs(matrix_file: str) -> dict:+ legs = yaml.safe_load((REPO / matrix_file).read_text(encoding = "utf-8"))+ assert isinstance(legs, dict), f"{matrix_file}: expected a mapping of job -> legs"+ return legs+++def _select(matrix_file: str, event: str) -> dict[str, str]:+ """Run the selector the way the `select` job does and return its output lines."""+ out = subprocess.run(+ [sys.executable, str(SELECTOR), "--file", matrix_file, "--event", event],+ cwd = REPO,+ capture_output = True,+ text = True,+ check = True,+ ).stdout+ return dict(line.split("=", 1) for line in out.splitlines() if line)++[email protected]("name", sorted(EXPECTED))+def test_the_matrix_file_is_the_one_the_select_job_reads(name):+ matrix_file, jobs = EXPECTED[name]+ doc = _doc(name)+ select = doc["jobs"]["select"]+ files = [+ (s.get("env") or {}).get("MATRIX_FILE") for s in select["steps"] if isinstance(s, dict)+ ]+ assert matrix_file in files, f"{name}: the select job does not read {matrix_file}"+ assert set(_legs(matrix_file)) == {_key(j) for j in jobs}, (+ f"{name}: {matrix_file} lists jobs {sorted(_legs(matrix_file))}, "+ f"this test expects {sorted(jobs)}"+ )++[email protected]("name", sorted(EXPECTED))+def test_every_matrix_job_takes_its_legs_from_select_and_nothing_else_does(name):+ matrix_file, jobs = EXPECTED[name]+ doc = _doc(name)+ for jid, job in doc["jobs"].items():+ matrix = (job.get("strategy") or {}).get("matrix")+ if matrix is None:+ continue+ match = _SELECTED.match(str(matrix))+ assert match, f"{name}:{jid} carries a literal matrix; the legs belong in {matrix_file}"+ assert match.group(1) == _key(jid), (+ f"{name}:{jid} reads needs.select.outputs.{match.group(1)}; the output is "+ f"named after the job so the file and the workflow cannot drift"+ )+ assert jid in jobs, f"{name}:{jid} is a matrix job this test does not know"+ needs = job.get("needs")+ needs = needs if isinstance(needs, list) else [needs]+ assert "select" in needs, f"{name}:{jid} does not depend on the select job"+ for jid in jobs:+ assert jid in doc["jobs"], f"{name}: matrix job {jid} is gone but its legs are not"++[email protected]("name", sorted(EXPECTED))+def test_every_leg_has_the_keys_its_job_reads(name):+ """A key a step reads through `matrix.<key>` must be on every leg, or be optional.++ Keys the workflow reads with a truthiness test (`matrix.nonroot && ...`) are optional+ by construction; those read into a name, a label or an env value must be present,+ because an absent key renders as the empty string and the job runs with it.+ """+ matrix_file, jobs = EXPECTED[name]+ doc = _doc(name)+ legs = _legs(matrix_file)+ for jid in jobs:+ job = doc["jobs"][jid]+ read = set(_MATRIX_KEY.findall(json.dumps(job)))+ required = REQUIRED_KEYS[jid]+ assert required <= read, f"{name}:{jid} never reads {sorted(required - read)}"+ declared = [set(leg) - {"pr"} for leg in legs[_key(jid)]]+ for leg in legs[_key(jid)]:+ assert "pr" in leg and isinstance(+ leg["pr"], bool+ ), f"{matrix_file}:{jid}: {leg} has no bool `pr`"+ missing = required - set(leg)+ assert not missing, f"{matrix_file}:{jid}: {leg} lacks {sorted(missing)}"+ unknown = read - {k for leg in declared for k in leg}+ assert not unknown, f"{name}:{jid} reads matrix keys no leg declares: {sorted(unknown)}"++[email protected]("name", sorted(EXPECTED))+def test_the_pr_subset_and_the_full_set_are_the_sizes_the_headers_claim(name):+ matrix_file, jobs = EXPECTED[name]+ legs = _legs(matrix_file)+ for jid, (total, on_pr) in jobs.items():+ rows = legs[_key(jid)]+ assert len(rows) == total, f"{matrix_file}:{jid}: {len(rows)} legs, expected {total}"+ picked = [leg for leg in rows if leg["pr"]]+ assert len(picked) == on_pr, f"{matrix_file}:{jid}: {len(picked)} PR legs, expected {on_pr}"+++def test_the_clean_machine_pr_subset_keeps_a_macos_leg():+ """test_macos_slots_per_commit.py must keep counting the file as a macOS workflow."""+ legs = _legs(EXPECTED["clean-machine-install-ci.yml"][0])+ assert any(leg["pr"] and str(leg.get("os", "")).startswith("macos-") for leg in legs["macos"])++[email protected]("name", sorted(EXPECTED))+def test_a_job_whose_pr_subset_is_empty_gates_on_the_count(name):+ """An empty `include` is a workflow error, not a job with no legs."""+ matrix_file, jobs = EXPECTED[name]+ doc = _doc(name)+ outputs = doc["jobs"]["select"].get("outputs") or {}+ for jid, (_, on_pr) in jobs.items():+ if on_pr:+ continue+ job = doc["jobs"][jid]+ gate = f"needs.select.outputs.{_key(jid)}_count != '0'"+ assert gate in str(job.get("if", "")), f"{name}:{jid} has no PR legs and no `if: {gate}`"+ assert (+ f"{_key(jid)}_count" in outputs+ ), f"{name}: the select job does not expose {_key(jid)}_count"+ # The container probe exists only to gate the container install rows.+ if name == "clean-machine-install-ci.yml":+ probe = doc["jobs"]["windows_container_probe"]+ assert "windows_container_install_count != '0'" in str(probe.get("if", ""))++[email protected]("name", sorted(EXPECTED))[email protected]("event", ["pull_request", "schedule", "push", "workflow_dispatch"])+def test_the_selector_emits_the_legs_without_the_pr_flag(name, event):+ matrix_file, jobs = EXPECTED[name]+ out = _select(matrix_file, event)+ for jid, (total, on_pr) in jobs.items():+ matrix = json.loads(out[_key(jid)])+ assert list(matrix) == [+ "include"+ ], f"{jid}: the matrix must be a mapping with only `include`"+ expected = on_pr if event == "pull_request" else total+ assert (+ len(matrix["include"]) == expected+ ), f"{jid} on {event}: {len(matrix['include'])} legs"+ assert out[f"{_key(jid)}_count"] == str(expected)+ for leg in matrix["include"]:+ assert "pr" not in leg, f"{jid}: the `pr` flag leaked into the matrix: {leg}"+ assert "\n" not in out[_key(jid)], f"{jid}: multi-line JSON would truncate in GITHUB_OUTPUT"+++def test_the_wsl_leg_is_off_on_pull_requests():+ """Not a matrix job, so it gates on the event itself; the header says why."""+ doc = _doc("clean-machine-install-ci.yml")+ assert doc["jobs"]["wsl"].get("if") == "github.event_name != 'pull_request'"++[email protected]("name", sorted(EXPECTED))+def test_the_nightly_and_the_matrix_file_are_wired_into_the_trigger(name):+ """The full set has to run somewhere, and a matrix edit has to run the workflow."""+ matrix_file, _ = EXPECTED[name]+ doc = _doc(name)+ on = doc.get(True) if True in doc else doc.get("on")+ assert on.get("schedule"), f"{name}: no schedule, so the nightly-only legs never run"+ for trigger in ("pull_request", "push"):+ paths = (on.get(trigger) or {}).get("paths")+ if paths is None:+ continue+ for needed in (matrix_file, ".github/scripts/select_install_matrix.py"):+ assert needed in paths, f"{name}: {trigger} paths do not list {needed}"diff --git a/tests/studio/test_macos_slots_per_commit.py b/tests/studio/test_macos_slots_per_commit.pyindex ffba76b06ef..f89222ffc73 100644--- a/tests/studio/test_macos_slots_per_commit.py+++ b/tests/studio/test_macos_slots_per_commit.py@@ -43,7 +43,35 @@ def _on(doc):return doc.get(True) if True in doc else doc.get("on")-def _job_runs_on_macos(job) -> bool:+_SELECTED_MATRIX = re.compile(r"fromJSON\(\s*needs\.([\w-]+)\.outputs\.([\w-]+)\s*\)")+++def _matrix(job, doc) -> dict:+ """The matrix ``job`` expands, as a mapping, wherever its legs are written down.++ A literal `strategy.matrix` is returned as is. The install workflows instead take+ `matrix: ${{ fromJSON(needs.select.outputs.<job>) }}` from a `select` job that reads+ `.github/ci/*-matrix.yml` (see .github/scripts/select_install_matrix.py), so the legs+ are resolved from that file: the `MATRIX_FILE` env of the producing job's steps names+ it, and the output name is the key. Every leg is returned, PR subset or not, because+ this file asks which images a job CAN allocate.+ """+ matrix = (job.get("strategy") or {}).get("matrix") or {}+ if isinstance(matrix, dict):+ return matrix+ match = _SELECTED_MATRIX.search(str(matrix))+ if not match or not isinstance(doc, dict):+ return {}+ producer = (doc.get("jobs") or {}).get(match.group(1)) or {}+ for step in producer.get("steps") or []:+ matrix_file = ((step.get("env") or {}) if isinstance(step, dict) else {}).get("MATRIX_FILE")+ if matrix_file:+ legs = yaml.safe_load((REPO / matrix_file).read_text(encoding = "utf-8")) or {}+ return {"include": list(legs.get(match.group(2)) or [])}+ return {}+++def _job_runs_on_macos(job, doc = None) -> bool:"""Whether ``job`` schedules a macOS runner.Reads `runs-on` and, when that is a matrix expression, the matrix values it selects@@ -61,7 +89,7 @@ def _job_runs_on_macos(job) -> bool:return True# `runs-on: ${{ matrix.os }}` -- resolve against the matrix it names.for key in re.findall(r"matrix\.([\w-]+)", value):- matrix = (job.get("strategy") or {}).get("matrix") or {}+ matrix = _matrix(job, doc)candidates = list(matrix.get(key) or [])for entry in matrix.get("include") or []:if isinstance(entry, dict) and key in entry:@@ -78,7 +106,7 @@ def _macos_workflows():doc = yaml.safe_load(text)if not isinstance(doc, dict) or not isinstance(doc.get("jobs"), dict):continue- if any(_job_runs_on_macos(j) for j in doc["jobs"].values() if isinstance(j, dict)):+ if any(_job_runs_on_macos(j, doc) for j in doc["jobs"].values() if isinstance(j, dict)):yield path.name, doc, text@@ -315,8 +343,7 @@ def _macos_labels():# runs-on plus the matrix it may select from: a retired image hides in an `include:`# list just as easily as in a literal runs-on.blob = str(job.get("runs-on", ""))- strategy = job.get("strategy") or {}- blob += str((strategy.get("matrix") or {}) if isinstance(strategy, dict) else "")+ blob += str(_matrix(job, doc) if isinstance(job.get("strategy"), dict) else "")# Only things shaped like a GitHub image name. The loose MACOS pattern used elsewhere# in this file also matches build targets that merely contain "macos":# release-desktop's matrix carries `macos-aarch64`, which is a Rust triple's nicknamediff --git a/tests/studio/test_studio_smokes_do_not_trigger_on_the_training_library.py b/tests/studio/test_studio_smokes_do_not_trigger_on_the_training_library.pynew file mode 100644index 00000000000..82ba54ed08b--- /dev/null+++ b/tests/studio/test_studio_smokes_do_not_trigger_on_the_training_library.py@@ -0,0 +1,276 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""The Studio smoke workflows trigger on what they can observe, and nothing else.++Every Studio smoke in this repo installs with `--local --no-torch`: the venv under test+cannot import the training library, so an edit under `unsloth/**` cannot change what the+job sees. Seven of the nine smokes nonetheless listed `unsloth/**` in their `pull_request`+filter, and all nine listed `studio/**`, which also matches `studio/src-tauri` (never built+by a smoke) and `studio/docs`. Measured over the last 20 PRs, a push that touched only+`studio/backend` fired 19 to 25 workflows and 50 to 90 jobs against an account that runs+about 30 to 35 jobs at once, and a training-only PR paid every Studio runner, macOS+included, for nothing. The queue waits that produced (p50 128 minutes on ubuntu-latest,+213 on macos-15) were the whole cost of the CI, the tests themselves finish in minutes.++Three rules, each cheap to break silently and expensive to leave broken:++1. No Studio smoke lists `unsloth/**` or a bare `studio/**`. The narrow set is spelled out+ per workflow (`studio/backend/**`, `studio/frontend/**` where Playwright drives the+ bundle, the installer entry points) and the comment above each list says why.+2. A filter lists every `.github/scripts` and `.github/actions` path the workflow executes,+ and nothing under those directories that it does not. The second half is what retired+ the `frontend-dist-*` entries from six workflows that never `uses:` them: a listed+ action the job never runs is a trigger for nothing, and it hid the fact that the list+ was copied rather than derived.+3. `local-agent-guides-ci.yml` names the route modules that serve the endpoints its+ preflight curls, not `studio/backend/routes/**`. Its connection matrix is nine+ ubuntu-latest cells of up to 16 minutes, and it fired for every edit to the training,+ export and dataset routes it never requests.++`tests/studio/test_macos_slots_per_commit.py` already pins `push.paths == pull_request.paths`+for the macOS workflows; this module does not repeat that.+"""++import re+from pathlib import Path++import pytest+import yaml++REPO = Path(__file__).resolve().parents[2]+WORKFLOWS = REPO / ".github" / "workflows"++# Every workflow that installs Studio with --no-torch and boots it. The Update smokes are+# included because their filters were already narrow and must stay that way.+STUDIO_SMOKES = (+ "studio-api-smoke.yml",+ "studio-inference-smoke.yml",+ "studio-ui-smoke.yml",+ "studio-update-smoke.yml",+ "studio-windows-api-smoke.yml",+ "studio-windows-inference-smoke.yml",+ "studio-windows-ui-smoke.yml",+ "studio-windows-update-smoke.yml",+ "studio-mac-ui-smoke.yml",+)++AGENT_GUIDES = "local-agent-guides-ci.yml"++# Rule 2 applies to these on top of the smokes: they have the same shape of filter.+DERIVED_FILTERS = STUDIO_SMOKES + (AGENT_GUIDES,)++FORBIDDEN = {"unsloth/**", "studio/**"}++# A path under .github/scripts or .github/actions that a step runs, sources or `uses:`.+# `./.github/actions/x` and `.github/actions/x/action.yml` normalise to the same thing.+EXECUTED = re.compile(r"(?:\./)?(\.github/(?:scripts|actions)/[A-Za-z0-9_./-]+)")+++def _on(doc):+ """The `on:` mapping, which PyYAML parses as the boolean True."""+ return doc.get(True) if True in doc else doc.get("on")+++def _load(name: str):+ return yaml.safe_load((WORKFLOWS / name).read_text(encoding = "utf-8"))+++def _paths(doc, event: str) -> list[str]:+ trigger = _on(doc).get(event)+ if not isinstance(trigger, dict):+ return []+ return list(trigger.get("paths") or [])+++def _step_text(doc) -> str:+ """Everything a step can execute: run bodies, `uses:` targets, and `with:` values."""+ chunks = []+ for job in doc["jobs"].values():+ for step in job.get("steps") or []:+ for key in ("run", "uses"):+ if step.get(key):+ chunks.append(str(step[key]))+ for value in (step.get("with") or {}).values():+ chunks.append(str(value))+ for value in (step.get("env") or {}).values():+ chunks.append(str(value))+ return "\n".join(chunks)+++def _normalise(path: str) -> str:+ path = path.removeprefix("./")+ path = path.rstrip(".,;:)'\"")+ if path.startswith(".github/actions/") and not path.endswith(".yml"):+ path = path.rstrip("/") + "/action.yml"+ return path+++# A helper script reaching a sibling: `$SCRIPT_DIR/x.sh`, `"$(dirname "$0")/x.txt"`, or+# the repo-relative `.github/scripts/x.sh` form.+SIBLING = re.compile(+ r"(?:\$SCRIPT_DIR|\$\{SCRIPT_DIR\}|\$\(dirname \"?\$0\"?\)|\.github/scripts)/([A-Za-z0-9_.-]+)"+)+++def _executed_github_paths(doc) -> set[str]:+ """The .github/scripts and .github/actions files the steps reach.++ Indirection is followed: run-studio-ui-lane.sh boots Studio and drives the+ permission and indicator browsers through sibling scripts, agent-guides-drive.sh+ reads its prompts from sibling text files, and install-unsloth-local `uses:` the+ dist and uv cache actions. An edit to any of those changes what the job runs just+ as surely as an edit to the script or action the step names, so the filter has to+ list them too.+ """+ found = set()+ for match in EXECUTED.findall(_step_text(doc)):+ path = _normalise(match)+ if (REPO / path).is_file():+ found.add(path)+ # A local composite action that `uses:` another local action pulls that one in.+ pending = [p for p in found if p.startswith(".github/actions/")]+ while pending:+ text = (REPO / pending.pop()).read_text(encoding = "utf-8", errors = "replace")+ for match in EXECUTED.findall(text):+ nested = _normalise(match)+ if (+ nested.startswith(".github/actions/")+ and (REPO / nested).is_file()+ and nested not in found+ ):+ found.add(nested)+ pending.append(nested)+ for path in sorted(found):+ if not path.startswith(".github/scripts/"):+ continue+ text = (REPO / path).read_text(encoding = "utf-8", errors = "replace")+ for name in SIBLING.findall(text):+ sibling = f".github/scripts/{name}"+ if (REPO / sibling).is_file():+ found.add(sibling)+ return found+++def _listed_github_paths(paths: list[str]) -> set[str]:+ return {+ p for p in paths if p.startswith(".github/scripts/") or p.startswith(".github/actions/")+ }++[email protected]("name", STUDIO_SMOKES)+def test_no_studio_smoke_triggers_on_the_training_library_or_all_of_studio(name):+ doc = _load(name)+ for event in ("pull_request", "push"):+ offending = FORBIDDEN & set(_paths(doc, event))+ assert not offending, (+ f"{name} {event}.paths lists {sorted(offending)}. The install is --no-torch, so "+ "unsloth/** cannot reach the venv under test, and studio/** also matches the "+ "Tauri shell and docs the smoke never touches. Name the directories the job "+ "observes instead."+ )+ assert "studio/backend/**" in _paths(doc, "pull_request") or name.endswith(+ "update-smoke.yml"+ ), f"{name} must still trigger on the backend it boots"++[email protected]("name", STUDIO_SMOKES)+def test_every_smoke_still_names_the_workflow_file_and_the_apt_helper_it_runs(name):+ doc = _load(name)+ paths = set(_paths(doc, "pull_request"))+ assert f".github/workflows/{name}" in paths, f"{name} must re-run when it is edited"+ text = _step_text(doc)+ if "retry-with-apt-lock.sh" in text:+ assert (+ ".github/scripts/retry-with-apt-lock.sh" in paths+ ), f"{name} calls retry-with-apt-lock.sh but would not re-run when it changes"++[email protected]("name", DERIVED_FILTERS)+def test_the_filter_lists_exactly_the_github_paths_the_steps_execute(name):+ doc = _load(name)+ executed = _executed_github_paths(doc)+ for event in ("pull_request", "push"):+ paths = _paths(doc, event)+ if not paths:+ continue+ listed = _listed_github_paths(paths) - {f".github/workflows/{name}"}+ missing = sorted(executed - listed)+ assert not missing, (+ f"{name} {event}.paths does not list {missing}, which its steps execute; an edit "+ "to any of them changes what the job runs without running it"+ )+ dead = sorted(listed - executed)+ assert not dead, (+ f"{name} {event}.paths lists {dead}, which no step in the workflow runs, sources "+ "or `uses:`; a trigger for nothing means the list was copied, not derived"+ )+++def test_executed_path_detection_is_not_vacuous():+ """The scanner must find the helpers every smoke is known to call."""+ doc = _load("studio-ui-smoke.yml")+ executed = _executed_github_paths(doc)+ assert ".github/scripts/boot-studio-api-only.sh" in executed+ assert ".github/actions/install-unsloth-local/action.yml" in executed+ # Reached through install-unsloth-local, which `uses:` the dist and uv cache pairs.+ assert ".github/actions/frontend-dist-restore/action.yml" in executed+ assert ".github/actions/uv-cache-restore/action.yml" in executed+ windows = _executed_github_paths(_load("studio-windows-ui-smoke.yml"))+ assert ".github/actions/frontend-dist-restore/action.yml" in windows+++def _endpoints_curled(doc) -> set[str]:+ """The /v1 endpoints the workflow's own steps request."""+ return set(re.findall(r"/v1/(chat/completions|messages|responses|models)\b", _step_text(doc)))+++def _route_decorators(module: Path) -> set[str]:+ """The route suffixes a module declares, e.g. chat/completions for /v1/chat/completions."""+ text = module.read_text(encoding = "utf-8")+ found = set()+ for path in re.findall(r"@router\.(?:get|post|api_route)\(\s*\"/?([A-Za-z0-9_/{}:]+)\"", text):+ found.add(path.strip("/").removeprefix("v1/"))+ return found+++def test_agent_guides_lists_the_route_modules_that_serve_what_it_curls():+ doc = _load(AGENT_GUIDES)+ curled = _endpoints_curled(doc)+ assert {"chat/completions", "messages", "responses", "models"} <= curled, curled+ for event in ("pull_request", "push"):+ paths = _paths(doc, event)+ assert "studio/backend/routes/**" not in paths, (+ f"{AGENT_GUIDES} {event}.paths matches every route module; the preflight only "+ "requests the OpenAI and Anthropic surfaces"+ )+ routes = sorted(p for p in paths if p.startswith("studio/backend/routes/"))+ assert routes, f"{AGENT_GUIDES} {event}.paths names no route module at all"+ serving = set()+ for entry in routes:+ module = REPO / entry+ assert module.is_file(), f"{AGENT_GUIDES} lists {entry}, which does not exist"+ declared = _route_decorators(module)+ served = {e for e in curled if e in declared or e.rstrip("/") + "/" in declared}+ assert served, (+ f"{AGENT_GUIDES} lists {entry} but it declares none of {sorted(curled)}; "+ "either the endpoint moved or the entry is stale"+ )+ serving |= served+ assert curled <= serving, (+ f"{AGENT_GUIDES} {event}.paths covers {sorted(serving)} but the preflight also "+ f"requests {sorted(curled - serving)}; add the module that serves it"+ )+ # The contracts outside routes/ the docstring names must stay.+ for required in (+ "studio/backend/main.py",+ "studio/backend/core/inference/llama_cpp.py",+ "studio/backend/models/**",+ "unsloth_cli/*",+ "unsloth_cli/commands/*.py",+ ):+ assert required in paths, f"{AGENT_GUIDES} {event}.paths lost {required}"+ assert "unsloth_cli/**" not in paths, (+ f"{AGENT_GUIDES} {event}.paths matches the whole CLI package; the cells never run "+ "unsloth_cli/tests/**"+ )diff --git a/tests/studio/test_ui_shard_engines.py b/tests/studio/test_ui_shard_engines.pyindex 9adb973d8a6..7e04b65e74c 100644--- a/tests/studio/test_ui_shard_engines.py+++ b/tests/studio/test_ui_shard_engines.py@@ -3,18 +3,26 @@"""Each Chat UI shard must install exactly the browser engines its own steps drive.-The four shards used to install all three engines each. Two of them -- `extra` and-`picker` -- never open anything but chromium, and installing webkit's system-libraries for them is an apt transaction of 181 packages and 102 MB:+The shards used to install all three engines each. The chromium-only ones (`extra`,+which now also carries the former `picker` suites) never open anything but chromium,+and installing webkit's system libraries for them is an apt transaction of 181+packages and 102 MB:0 upgraded, 181 newly installed, 0 to removeNeed to get 102 MB/114 MB of archivesGet:2 .../noble/universe amd64 fonts-wqy-zenhei all 0.9.45-8 [7472 kB]-> 4m51s later: attempt 2/2 did not finish within 300s-Fonts, X fonts and a soundfont, fetched so that two shards which never launch webkit+Fonts, X fonts and a soundfont, fetched so that a shard which never launches webkitcould time out fetching them. That is what this file exists to stop coming back.+Two shards rather than four since the fold of `banner` into `chat` and `picker` into+`extra`: the four cells ran 5.3, 8.9, 6.5 and 2.8 minutes and each waited about two+hours for an ubuntu-latest runner, so two cells of about 12 minutes take half the+slots for the same wall-clock. The engine sets did not change, which is why the fold+was possible at all: `banner` already installed the three engines `chat` installs, and+`picker` was chromium-only like `extra`.+It is enforced in BOTH directions, and the second one is the dangerous one:* installing an engine no step drives is waste, and waste on a degraded mirror is@@ -24,7 +32,7 @@ It is enforced in BOTH directions, and the second one is the dangerous one:green, which reads as a flaky test rather than a missing package.Derived from the workflow, never from a hardcoded list: the whole point is that-adding a webkit step to `picker` fails HERE, at the edit, rather than in CI.+adding a webkit step to `extra` fails HERE, at the edit, rather than in CI."""from __future__ import annotations@@ -135,8 +143,8 @@ def test_the_detector_sees_the_cross_browser_steps() -> None:f"the chat shard drives {sorted(chat)}; it runs Cross-browser permission "f"controls, so the step scan is not seeing engine names any more")- picker = _engines_driven_by("picker")- assert "webkit" not in picker, (- f"the picker shard now appears to drive {sorted(picker)}; if that is real the "+ extra = _engines_driven_by("extra")+ assert "webkit" not in extra, (+ f"the extra shard now appears to drive {sorted(extra)}; if that is real the "f"matrix needs updating, and if it is not the scan is over-matching")diff --git a/tests/studio/test_uv_cache_discipline.py b/tests/studio/test_uv_cache_discipline.pyindex 87a9ac2bad8..05aa379b267 100644--- a/tests/studio/test_uv_cache_discipline.py+++ b/tests/studio/test_uv_cache_discipline.py@@ -205,3 +205,208 @@ def test_the_action_is_actually_used() -> None:if "install-unsloth-local" in p.read_text(encoding = "utf-8")]assert len(users) >= 5, f"only {len(users)} workflows use the action: {users}"+++# The Windows jobs run install.ps1 from a hand-written pwsh step and never come through+# install-unsloth-local, so the restore and the save are their own composite actions,+# which that composite delegates to and the Windows jobs call directly. What follows+# holds that shape: one key, every warm installer job restoring it, every restore paired+# with a save that reads its outputs, and the cold lanes untouched.++ACTIONS = REPO_ROOT / ".github" / "actions"+UV_RESTORE = ACTIONS / "uv-cache-restore" / "action.yml"+UV_SAVE = ACTIONS / "uv-cache-save" / "action.yml"++# Cold at JOB level, inside a workflow whose other jobs legitimately use the cache; the+# same list tests/studio/test_frontend_dist_cache.py keeps for the dist.+COLD_INSTALL_JOBS = (("studio-windows-inference-smoke.yml", "no-vs-cpu"),)++# An INVOCATION, not a mention: mlx-ci.yml explains in a comment why it does NOT run+# `install.sh --local`, and a bare substring match called that an uncached install.+_INSTALLER = re.compile(r"(?m)^\s*[^#\n]*?(?:^|[\s/&'\"])install\.(?:ps1|sh) --local")+_HELPER = re.compile(r"\.github/scripts/([A-Za-z0-9_.-]+\.sh)")+++def _runs_installer(step: dict) -> bool:+ """Whether ``step`` runs the installer itself or through a helper under .github/scripts.++ studiobench-ui-parity installs each side through parity-install-side.sh, so the+ invocation is one file away from the workflow; followed one level, like the smoke+ trigger guard does for its helpers.+ """+ run = str(step.get("run", ""))+ if _INSTALLER.search(run):+ return True+ for helper in _HELPER.findall(run):+ path = REPO_ROOT / ".github" / "scripts" / helper+ if path.is_file() and _INSTALLER.search(path.read_text(encoding = "utf-8", errors = "replace")):+ return True+ return False+++def _jobs():+ for f in sorted(WORKFLOWS.glob("*.yml")):+ doc = yaml.safe_load(f.read_text(encoding = "utf-8"))+ if isinstance(doc, dict) and isinstance(doc.get("jobs"), dict):+ for jid, job in doc["jobs"].items():+ if isinstance(job, dict):+ yield f.name, jid, job+++def _produces_on_main(name: str) -> bool:+ """Same rule as the dist guard: `push` to main or `schedule`, never `workflow_dispatch`."""+ doc = yaml.safe_load((WORKFLOWS / name).read_text(encoding = "utf-8"))+ on = doc.get("on", doc.get(True)) or {}+ if isinstance(on, str):+ on = {on: None}+ elif isinstance(on, list):+ on = dict.fromkeys(on)+ if "schedule" in on:+ return True+ if "push" not in on:+ return False+ push = on.get("push")+ branches = push.get("branches") if isinstance(push, dict) else None+ return branches is None or "main" in branches+++def test_the_uv_cache_key_has_exactly_one_definition() -> None:+ """A second copy agrees today and drifts silently, with the cache still hitting."""+ definers = []+ for path in sorted(list(ACTIONS.rglob("action.yml")) + list(WORKFLOWS.glob("*.yml"))):+ if re.search(r"key:\s*uv-\$\{\{", path.read_text(encoding = "utf-8")):+ definers.append(str(path.relative_to(REPO_ROOT)))+ assert definers == [+ ".github/actions/uv-cache-restore/action.yml"+ ], f"the uv cache key is defined in {definers}; it must have exactly one definition"+++def test_install_unsloth_local_delegates_the_uv_cache() -> None:+ uses = [str(s.get("uses", "")) for s in _own_steps()]+ assert "./.github/actions/uv-cache-restore" in uses, uses+ assert "./.github/actions/uv-cache-save" in uses, uses+ assert not any("actions/cache" in u for u in uses), (+ "install-unsloth-local carries its own cache step again; the key must stay in "+ "uv-cache-restore"+ )+++def test_the_uv_actions_nest_nothing() -> None:+ """`uses: ./...` inside a composite resolves from GITHUB_WORKSPACE and takes no expressions.++ install-unsloth-local nests these two and is root-checkout-only for it. The leaf+ actions must stay leaves, so a nested-checkout job can still call them directly.+ """+ for action in (UV_RESTORE, UV_SAVE):+ nested = [+ str(s.get("uses", ""))+ for s in _own_steps(action)+ if str(s.get("uses", "")).startswith("./")+ ]+ assert not nested, f"{action.relative_to(REPO_ROOT)} nests {nested}"+++def test_every_warm_installer_job_restores_the_uv_cache() -> None:+ """A job that runs the installer without the cache pays the full download every run.++ The cold lanes are the deliberate exception, named in COLD_INSTALL_WORKFLOWS and+ COLD_INSTALL_JOBS, and a new installer call site has to either restore the cache or+ be added to one of those lists in a diff someone reads.+ """+ offenders = []+ for name, jid, job in _jobs():+ if name in COLD_INSTALL_WORKFLOWS or (name, jid) in COLD_INSTALL_JOBS:+ continue+ steps = job.get("steps") or []+ runs_installer = any(_runs_installer(s) for s in steps)+ if not runs_installer:+ continue+ restores = any(+ "uv-cache-restore" in str(s.get("uses", ""))+ or "install-unsloth-local" in str(s.get("uses", ""))+ for s in steps+ )+ if not restores:+ offenders.append(f"{name}:{jid}")+ assert not offenders, (+ "these jobs run the installer with no uv download cache, so every run downloads "+ "every wheel again:\n " + "\n ".join(offenders)+ )+++def test_every_uv_restore_is_paired_with_a_save_wired_to_it() -> None:+ """A restore with no save fills nothing; a save reading the wrong id saves nothing.++ The upload half is derived from the workflow's triggers rather than allowlisted, as+ for the dist: a consumer-only lane (no `push`, no `schedule`) passes `save: 'false'`+ and a producer must not.+ """+ offenders = []+ for name, jid, job in _jobs():+ steps = job.get("steps") or []+ restore = next((s for s in steps if "uv-cache-restore" in str(s.get("uses", ""))), None)+ save = next((s for s in steps if "uv-cache-save" in str(s.get("uses", ""))), None)+ if restore is None and save is None:+ continue+ if restore is None or save is None:+ offenders.append(f"{name}:{jid}: restore={restore is not None} save={save is not None}")+ continue+ ident = restore.get("id")+ if not ident:+ offenders.append(f"{name}:{jid}: the restore step has no id")+ continue+ with_ = save.get("with") or {}+ for field in ("cache-hit", "key"):+ if f"steps.{ident}.outputs.{field}" not in str(with_.get(field, "")):+ offenders.append(f"{name}:{jid}: save does not take {field} from steps.{ident}")+ installs = [i for i, s in enumerate(steps) if _runs_installer(s)]+ if not installs:+ offenders.append(f"{name}:{jid}: restores the uv cache but never runs an installer")+ continue+ if steps.index(restore) > min(installs):+ offenders.append(f"{name}:{jid}: the restore runs after the install")+ if steps.index(save) < max(installs):+ offenders.append(f"{name}:{jid}: the save runs before the install")+ uploads = str(with_.get("save", "true")) != "false"+ if uploads and not _produces_on_main(name):+ offenders.append(+ f"{name}:{jid}: saves, but {name} never runs on main; pass save: 'false'"+ )+ if not uploads and _produces_on_main(name):+ offenders.append(f"{name}:{jid}: passes save: 'false', but {name} runs on main")+ assert not offenders, "\n ".join(["broken uv cache wiring:"] + offenders)++[email protected]("name", COLD_INSTALL_WORKFLOWS)+def test_cold_install_lanes_never_adopt_the_uv_actions(name: str) -> None:+ path = WORKFLOWS / name+ if not path.exists():+ pytest.skip(f"{name} no longer exists")+ assert "uv-cache-" not in path.read_text(+ encoding = "utf-8"+ ), f"{name} restores a warm uv cache; a cached cold-install test proves nothing"++[email protected]("name,jid", COLD_INSTALL_JOBS)+def test_cold_install_jobs_never_adopt_the_uv_actions(name: str, jid: str) -> None:+ doc = yaml.safe_load((WORKFLOWS / name).read_text(encoding = "utf-8"))+ job = (doc.get("jobs") or {}).get(jid)+ assert job is not None, f"{name} no longer has job {jid}; update COLD_INSTALL_JOBS"+ offenders = [+ str(s.get("uses", ""))+ for s in job.get("steps") or []+ if "uv-cache-" in str(s.get("uses", ""))+ ]+ assert not offenders, f"{name}:{jid} is a deliberate cold-install lane: {offenders}"+++def test_the_uv_actions_are_actually_used_directly() -> None:+ """The Windows jobs are the reason the pair exists; if none calls it, it is dead code."""+ direct = [+ p.name+ for p in WORKFLOWS.glob("*.yml")+ if "uv-cache-restore" in p.read_text(encoding = "utf-8")+ ]+ assert (+ len(direct) >= 4+ ), f"only {len(direct)} workflows call uv-cache-restore directly: {direct}"