fix(#425): stuck image pulls — classify and tell the truth

[shujaatTracebloc]

#425 — stuck image pulls: classify and tell the truth

helm upgrade --install runs with no --wait, so helm "succeeds" before any image is pulled. The pull-progress helper then waited TB_PULL_TIMEOUT and, on expiry, always printed "Services are still downloading — they'll finish starting in the background." — even when the pulls had permanently failed (x509, blocked registry, auth). A hard failure was reported in success-flavored copy; the user walked away believing the install would complete.

Bash — scripts/lib/install-client-helm.sh

• _pull_failure_detail — on a visible ImagePullBackOff/ErrImagePull/InvalidImageName, prints the failing pod line + the matching failed to pull … event (bounded, non-fatal, self-contained so no cross-lib sourcing).
• _progress_end_message (pure) — maps (pulled, total, max_pulled, has_fail) → done | failed | downloading | stalled. A permanent failure never maps to downloading, so it can't be sold as background progress.
• _download_services_progress now tracks max_pulled and, on timeout, classifies: a failure warns loudly with the event text; the "downloading in the background" copy prints only when pulls demonstrably progressed; otherwise a neutral "not pulling yet — see the diagnosis".

Windows — scripts/install-k8s.ps1

Wait-ForClientReady → Get-NotReadyState already classified pull failures into honest red-X summary branches (image_pull/image_pull_ca/crash); the "downloading" copy only ever shows for a genuine starting state. This PR also makes the failure copy carry the event text: Get-NotReadyState captures the pull event (or the failing pod line) into $script:NotReadyDetail, and the failure branches print it via the new Write-NotReadyDetail — matching the acceptance on both platforms.

Acceptance

• A permanently failing pull is never described as background progress.
• The failure copy contains the pod event text (both bash and Windows).

Tests

bats: _progress_end_message (all four outcomes; failure wins over partial progress), _pull_failure_detail (failing → detail + rc 0; healthy → nothing + rc 1), and a guard that the end copy routes through the selector. Pester: Get-NotReadyState detail capture (x509 / non-x509 / no-event fallback) + Write-NotReadyDetail (labelled block; no-op when empty). Full suites: bats install-client-helm green (one unrelated pre-existing _extract_yaml_value failure exists on develop, macOS-bash-specific — out of scope), Pester 333 passed / 0 failed; shellcheck + check-style + check-drift clean; scripts/manifest.sha256 regenerated (R8).

Closes #425

---

Note

Low Risk
Installer UX and messaging only; bounded kubectl reads with no change to cluster install or auth behavior.

Overview
Fixes #425: permanent image pull failures were often reported as "still downloading in the background" even when pulls had already failed (x509, registry, auth).

On bash, _download_services_progress now uses _pull_failure_detail and the pure _progress_end_message selector (done / failed / downloading / stalled) so timeouts warn with pod/event lines instead of implying background progress when nothing will recover.

On Windows, Get-NotReadyState fills $script:NotReadyDetail from scoped pull events or pod status (including crash loops), and failure summaries call Write-NotReadyDetail under "What the cluster reported:".

Adds bats and Pester coverage; scripts/manifest.sha256 updated.

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

[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 97db9e1. Configure here.}

[saadqbal]

Nice fix — the classifier is clean and the pure _progress_end_message is exactly the right seam to unit-test. Approving. Two small non-blockers inline: the failed copy can now over-claim in the opposite direction on a transient backoff, and bad prints unbounded despite the "Bounded" comment.

[LukasWodka]

/fr-pass