[noonghunna]

Three defects found by reproducing a Discord user's failure on a clean install. They are separate bugs but sit on one user journey — setup.sh then switch.sh for a gemma slug — and a new user hits all three in order. One commit each.

Fixes #1303
Fixes #1304
Fixes #1305

---

1. setup.sh gemma-4-26b-a4b downloaded 16 GB no slug can serve (#1303)

profiles/models/gemma-4-26b-a4b.yml carried default_weight_variant: awq against setup: primary: autoround-int4-mixed. That tier's composes had been moved to _archive/ and no registry entry references the variant, but the setup block was never repointed — so the obvious path downloaded the wrong 16 GB, skipped the 17 GB both slugs need, and failed at switch.sh time.

Dropped the override so setup falls back to the profile default. The weights entry itself stays registered (kv-calc and the arch_patches / profile_runtime evidence rows still name it).

setup.primary is a deliberate override mechanism, so the new gate is not "primary == default_weight_variant" — that would red the two models that override it correctly (qwen3.8-27b → fp8, deepseek-v4-flash-0731 → unsloth-iq2-xxs). It asserts the weaker invariant true of all three: whatever setup fetches, some registry entry must serve it. It is also status-agnostic — a deprecated entry still pins its variant, and three models' primaries are referenced only by deprecated slugs today, which is a different question.

2. The MTP drafter was opt-in behind a flag with no user-facing surface (#1304)

WITH_ASSISTANT_DRAFT=1 existed in the model profile, in setup.sh's implementation and in a test — and nowhere a user would look, while its siblings WITH_DFLASH_DRAFT and WITH_VISION were at least in the header comment. vllm/gemma-26ba4b-single defaults to SPEC_N=4, so a user who did not set it got a bare missing-config.json naming neither the cause nor either fix. The working escape hatch (SPEC_N=0, standardised across every vLLM compose by #1048) was not surfaced in the failure path either.

Three surfaces, working outward from the failure:

• The compose now refuses to boot when SPEC_N>0 and the drafter has no config.json, naming both routes — same fail-loud contract the deepseek moecache composes carry for their external GGUF ([bench] 2x A6000 - llamacpp-club3090/deepseek-flash-dual-q8-moecache #1054). Its header's Drafter: line now says how to obtain the file.
• setup.sh --help grows an "Optional extra downloads" section. The header comment was never the right surface: reading it means already having opened the script.
• The header comment gains the two flags it was missing.

WITH_PRISM_EAGLE3 turned out to be undocumented in both places too — the new gate found it, so it is documented here as well.

test-spec-toggle-contract needed one change to be able to see any of this: it runs entrypoints in a sandbox, and a fail-loud check on a path embedded in the entrypoint (rather than in command:, which it already stubs) made the compose exit before emitting argv. It now redirects the container HF cache into the sandbox. Confirmed load-bearing, not cosmetic: the old gate reds against the new compose.

3. One transient stall aborted a 17 GB download with a traceback (#1305)

_hf_download_repo called the hub CLI once. Under set -euo pipefail a single httpx.ConnectTimeout mid-transfer aborted the whole run with a ~40-line unhandled traceback. Re-running resumed cleanly — nothing said so.

Bounded retry (4 attempts, 8s doubling to 120s, both env-tunable), and a give-up message that is an instruction rather than a traceback. The env hardening was already correct and is untouched; no external wrapper is introduced, since a shipped setup.sh cannot depend on anything outside the repo.

Not implemented: the stall watchdog the issue raises as a third option. An idle-but-not-erroring transfer is a different failure than a non-zero exit and a plain retry will not catch it — left for a follow-up rather than half-built.

---

Validation

for t in scripts/tests/*.sh; do bash "$t"; done — 172 pass / 0 fail (master baseline was 168/0; four new test files).

Every new assertion was negative-controlled against the unfixed state first:

Gate	Against the unfixed tree
test-setup-primary-slug-backed	FAILS, naming gemma-4-26b-a4b and nothing else — the two legitimate overrides are not flagged
test-setup-optin-flags-documented	FAILS on all four WITH_* flags as undocumented in --help
test-compose-drafter-preflight	FAILS showing --speculative-config reaching vLLM pointed at a directory that does not exist
test-setup-download-retry	FAILS on case 2 with the reported shape — one attempt, a traceback, rc=1
test-spec-toggle-contract (edit)	The pre-change gate reds against the new compose, so the sandbox change is load-bearing

Each also has an in-test positive control, so a scanner that quietly matched nothing cannot pass.

Not verified: nothing was boot-tested. There are no gemma-4-26b-a4b weights on the rig that produced this, and no container was started. The compose entrypoint was exercised with a stubbed vllm, not in an image — so what is proven is the shell logic and the messages, not engine behaviour. Likewise the retry was driven against a stubbed CLI: the loop and the give-up message are tested, but not that a real stalled 17 GB transfer resumes (#1305 verified that half independently, 1.1 GB → 6.4 GB with three .incomplete markers).

One hardening found while testing rather than from the issues: a mistyped HF_DOWNLOAD_RETRIES used to die with foo: unbound variable, because (( attempt >= max )) resolves a non-numeric value as a variable name — a crash inside the code that handles crashes. It now errors clearly, and case 5 covers it.

🤖 Generated with Claude Code