[Hendrik-code]

Model weights download automatically on first use, so this code path is the very first thing a new user
hits. It had three defects.

1. Four advertised model ids crashed

auto_download registers each semantic model twice, t2w and t2w_semantic, but download_names only
has the canonical key:

>>> [k for k in semantic if canonical_model_key(k) not in download_names]   # on main
['t2w_semantic', 't1w_semantic', 'vibe_semantic', 'ct_semantic']

These ids are listed to the user in the "Model 'x' does not exist. Available semantic models: [...]"
error message, so the obvious next step -- copy one of the listed names -- died with
RuntimeError: Failed to download model 't2w_semantic' ...: KeyError: 't2w_semantic'.

ct_semantic had a second problem: phase_to_version is keyed SEMANTIC_ct, so the alias missed the CT
override and resolved to a CT_semantic_v1.0.9 folder while downloading the v2.0.0 archive.

One canonical_model_key() maps *_semantic onto the id the weights are registered under, and
download_if_missing raises a readable KeyError for a genuinely unknown id instead of a bare lookup
failure.

2. A failed download reported success

# on main
>>> download_weights("http://localhost:1/nope.zip", out)      # prints "Download attempt failed"
None                                                          # ... and returns
>>> download_if_missing("t2w", url, SpinepsPhase.SEMANTIC)
PosixPath('/tmp/.../T2w_semantic_v1.0.9')                      # path does not exist

The caller then handed that non-existent folder to the model loader, and the user got a config-not-found
error with no mention of the network. It now raises a RuntimeError naming the URL, the underlying cause
and the manual-download fallback from the README.

3. An interrupted download poisoned the cache permanently

out_path existing is the "model is installed" check, and the archive was extracted straight into it:

# on main, Ctrl-C during extraction:
interrupted: user pressed ctrl-c mid-extract
out_path exists now: True contents: ['weights.ckpt.partial']
 -> next run sees 'if not out_path.exists()' as False and never downloads again

A truncated download left a stray T2w_semantic_v1.0.9.zip in the models directory and a raw
BadZipFile. Download and extraction now happen in a unique staging folder, which is moved into place
only after its contents are verified to contain an inference_config.json, and is removed on any
failure. The unique staging name also means concurrent SPINEPS processes (a job array all starting at
once) no longer overwrite each other's partial download.

Tests

unit_tests/test_auto_download.py: every registry id resolves to a download name; alias and canonical id
give the same folder at the right release version; unknown id raises a readable error; unreachable URL,
truncated archive and config-less archive each raise and leave the models directory empty; flat and
nested archives both install correctly; an existing folder is never re-downloaded.

Full suite: 233 passed, ruff clean.

🤖 Generated with Claude Code