#569: on a restricted network the first-run install fails downloading the
~2.5 GB cu128 PyTorch wheel from download.pytorch.org, and the app won't launch.
Two problems: the error told users to "set UV_DEFAULT_INDEX to a mirror" — which
CANNOT redirect torch, because it comes from a *named, explicit* uv index
(uv 0.11 rejects index-name override values and `--frozen` pins the exact wheel
URLs); and there was no way to supply a manually-downloaded wheel.
- Detect a torch/pytorch-host `uv sync` failure and emit torch-specific guidance
(Clean & Retry → VPN → drop the wheel locally) instead of the wrong mirror
advice.
- Add a local wheel-drop dir `<env_root>/wheels` (survives Clean & Retry) wired
via `UV_FIND_LINKS`. On a frozen-sync torch-download failure WITH wheels
present, retry NON-frozen with find-links so uv re-resolves from the local
wheels. Verified empirically: a non-frozen find-links sync installs from a
local wheel fully offline, while a `--frozen` sync ignores find-links — so the
retry is the only mechanism that can consume a dropped wheel. Best-effort: if
it can't satisfy, it fails identically to before and the actionable error
still fires.
- docs/install/troubleshooting.md: new "#12 CUDA PyTorch wheel download fails"
entry (docs-sync) — the offline wheel-drop path + why a PyPI mirror can't fix
this index.
Note: an automatic mirror redirect for the cu128 index is intentionally NOT
shipped — uv provides no working override for a named explicit index, so it
couldn't be verified; the offline wheel path is the reliable escape hatch.
Test: sync_failure_is_torch_download host/keyword detection + negative guard.
Co-authored-by: mergetest <test@local>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
