Fixes #9120.

Note on approach. The original commit on this branch fixed the race by retrying the failing import. That approach is superseded here — the reasoning is in the "Why not retry the import" section below and in the replacing commit's message. The diagnosis in #9120, which this branch started from, is unchanged and is what made the real fix findable.

The bug

On Apple Silicon, Train/Export is gated on the MLX stack being usable. Hardware detection runs as the torch warm's first stage, early enough that another startup thread can still be part-way through the same first import of transformers. CPython hands the second thread a partially initialised module rather than deadlock, so from transformers import AutoTokenizer — reached inside mlx_lm's own import chain — raises ImportError: cannot import name ... on a perfectly healthy install.

detect_hardware() caches that verdict for the process's lifetime, so one lost race at boot greys out Train/Export behind a "run unsloth studio update" tooltip that correctly reports nothing to fix. The reporter lost the race on 3 of 3 consecutive launches.

Root cause, and why the fix is this small

start_mlx_autorepair_if_needed() already re-measures the stack, one statement after join_background_warm() in the post-warm worker, at if mlx_stack_available(): return False. That measurement happens once the warm has finished importing, so it is not the one that raced — and the gate was throwing it away in exactly the case where it contradicted the cached verdict. The self-heal saw a healthy stack, declined to reinstall, and left the wrong verdict latched with nothing else that would ever revisit it.

So the gate now acts on both answers of that single measurement rather than only one: a usable stack means the verdict was measured during the race, and it re-detects.

Why not retry the import

The first approach on this branch retried when isinstance(exc, ImportError) and "cannot import name" in str(exc). That signature cannot separate the race from a genuinely broken install: it is also what a resolver backtrack produces, which is the failure this module exists to repair. tests/test_mlx_stack_blockers.py::test_an_import_that_raises_is_reported_with_its_error already pinned exactly that shape, under the comment "which is what a mlx-vlm built against a different transformers looks like from here" — and the retry made that test spend 1.5s per detection pass sleeping before reporting a verdict it was always going to reach.

Retrying also leaves the underlying problem in place. The verdict is cached for the process's lifetime, so a race that outlasts the backoff still greys out Train/Export for the session. The disagreement between two independent measurements is evidence that a substring match is not.

What changed

• utils/hardware/hardware.py gains overturn_the_mlx_verdict(epoch), which re-detects while the published verdict still blames the MLX stack, and verdict_blames_the_mlx_stack().
• utils/mlx_repair.py calls the overturn on the measurement it already took, and moves the UNSLOTH_DISABLE_MLX_AUTOREPAIR check after it.
• main.py is untouched.

Details worth a reviewer's attention:

• The re-detect is epoch-scoped. The epoch is read before the measurement, so a shutdown landing inside it discards the pass instead of republishing for a lifespan that has ended — the same guard _run_repair_and_redetect already carries, and without it the next lifespan would find DEVICE set and skip its own detection. The repair worker now shares that epoch instead of reading its own, later one.
• The verdict read and the re-detect are one locked section, so a forced pass landing between them does not lose its fresh answer to this one.
• UNSLOTH_DISABLE_MLX_AUTOREPAIR=1 no longer skips the overturn. It declines a reinstall, not a correct verdict, and re-detecting mutates nothing. Such a user reaches the measurement only when a verdict is actually waiting on it, so the opt-out still imports nothing on a host with nothing to overturn — which matters because the torch warm has its own kill switch, and under it this would otherwise be the process's first MLX import.
• The success message reflects the outcome, not the attempt. A pass can decline on a retired epoch or be discarded under one, so the answer is the same three-part settled read /api/health makes.

Cost

Nothing on a healthy boot, and nothing on a genuinely broken stack: the measurement is the one the gate already took. Where the verdict is overturned, the re-detect's own stack check is served from sys.modules — measured on an Apple Silicon host at 3010 ms for the first measurement and 1.3 ms for the second.

Known limitation

The overturn reaches only a verdict published before the post-warm handoff, which is the warm's. Under the warm's own kill switch (UNSLOTH_STUDIO_DISABLE_TORCH_WARM=1) detection is deferred to the first request that needs it, and a verdict landing after this point stands unreconciled for the session. That is the behaviour on main today as well; closing it means moving where the self-heal is scheduled, which is a larger change than this bug and is left as follow-up. The limitation is stated in the code.

Validation

python -m pytest tests/test_mlx_repair.py tests/test_startup_defers_stack_dependent_work.py \
    tests/test_warm_window_review_fixes.py tests/test_health_holds_verdict_during_mlx_repair.py \
    tests/test_mlx_stack_blockers.py -q
# 200 passed

A broader sweep (-k "mlx or hardware or warm or startup or health or detect") gives 1654 passed with 5 failures that reproduce identically on a clean main checkout under the same command.

Every added test was mutation-checked: each production line was reverted in turn and exactly the intended test failed — dropping the overturn, ignoring which gate produced the verdict, checking the opt-out before the measurement, dropping the epoch scope, reading the epoch after the measurement, reading the worker's epoch at spawn, measuring the stack twice, overturning regardless of the measurement, and announcing an overturn that never published.