fix(ci): bound the two unbounded network waits behind the ubuntu Prereqs hang

[LukasWodka]

Summary

Three times on 2026-08-04 (#525, #592) the Prereqs — ubuntu:* matrix jobs died at the 20-minute job timeout with nothing in the log but ⠼ Installing Docker… — and a fourth failure took 20 seconds with registry-1.docker.io … Client.Timeout exceeded (exit 125). Every other distro in the matrix passed every time; plain re-runs succeeded. Two unbounded network waits, one per layer:

Changes

Workflow (installer-tests.yaml) — docker run pulls the distro image implicitly with no timeout, so Docker Hub connectivity trouble either failed the job fast (exit 125) or stalled it until timeout-minutes killed it. Both container-matrix jobs (distro-prereqs, path-persist) now pre-pull with three bounded attempts (timeout 300 docker pull + backoff) and an honest error: "runner-to-registry connectivity, not this PR. Re-run this job."

setup-linux.sh — the get.docker.com convenience script's internal apt/download.docker.com fetches carry no timeout of their own, so a stalled connection hung silently behind the spinner (the fetch of the script itself already had retry + curl_secure bounds). The run is now bounded at 10 minutes (healthy installs take 1–3) and fails with a clear stalled-download message telling the operator to re-run — the installer resumes safely. Same shape as the existing dpkg-lock (#210) and kubectl-fetch bounds; timeout is coreutils, present on every distro this branch serves.

Test plan

• New bats test pins the timeout 600 bound on the get.docker.com branch — written || return 1-hardened so it stays green under test(bats): make every assertion enforce — 1240 were advisory #527's incoming bats-hygiene gate.
• setup-linux.bats 0 failures; actionlint clean; scripts/gen-manifest.sh regenerated (setup-linux.sh is manifested).
• The Prereqs/PATH persist matrix on this very PR exercises the new pre-pull path live.

Refs the 2026-08-04 incident runs (job ids 92054431018, 92073231942).

🤖 Generated with Claude Code

---

Note

Low Risk
Changes are timeout/retry wrappers around existing CI and installer paths; no auth, data, or cluster logic changes.

Overview
Addresses CI jobs that sat at Installing Docker… or hit the 20-minute timeout when Docker Hub or get.docker.com stalled—infra failures, not product regressions.

CI (installer-tests.yaml) — distro-prereqs and path-persist now pre-pull each matrix image with three bounded attempts (timeout 90 docker pull, backoff) before docker run, so implicit pulls can’t hang the job; failures surface as a clear “runner-to-registry connectivity” message.

Linux installer (setup-linux.sh) — The get.docker.com convenience script run is wrapped in spin_cmd_bounded (600s) instead of unbounded spin_cmd, with distinct errors for timeout (124) vs real install failure and prepare-host-aware re-run guidance.

Tests / supply chain — Bats pins the 600s bound; manifest.sha256 updated for the lib change.

^{Reviewed by Cursor Bugbot for commit 9b3d81e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[LukasWodka]

bugbot run

[LukasWodka]

Both findings fixed:

1. Stall error masked real failures — switched to the existing spin_cmd_bounded (which I'd bypassed): rc 124 → the stalled-download message; any other rc → an honest install-failed message pointing at the log tail the helper already prints. Fast real apt/script failures keep their own diagnosis now. Bats test re-pinned on the helper + 600s bound.
2. Pull retries exhausted the job budget — resized to 3 × timeout 90 with 10/20s backoff (~5.5 min worst case vs ~16), so a late-succeeding pull leaves the 20-minute job most of its budget for the actual install.

bugbot run

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d11047a. Configure here.}

[LukasWodka]

Fixed: the stall/failure errors now pick their re-run advice by mode — prepare-host when TB_PREPARE_HOST_MODE is set, the installer otherwise — matching the daemon-check errors later in the same function.

bugbot run

[shujaatTracebloc]

Reviewed. Correct and well-reasoned: bounded+retried docker pull in CI (primes the cache before the implicit docker run pull) and spin_cmd_bounded 600 on the get.docker.com run, with mode-aware error advice (prepare-host vs "the installer") so an admin isn't told to re-run a full self-provision. CI green, Bugbot clean, 0 unresolved. Optional non-blocking follow-up: a test for the rc-124/error-message + prepare-host _rerun branches. LGTM.