fix(installer): fail fast on k3d spawn failure; bound the create wait

[LukasWodka]

Summary

Fixes the infinite "Creating compute environment..." spinner observed live on a Windows test machine (2026-07-27), and bounds the create wait on top of it.

Bug 1 — null-process spin (#412): when Start-Process for k3d cluster create fails (e.g. a broken k3d.exe: %1 is not a valid Win32 application), the error is non-terminating, $k3dProc stays $null, and while (-not $null.HasExited) is always true → live spinner over a dead install, forever.

Bug 2 — unbounded wait (#426, Windows half): k3d cluster create --wait has no --timeout, so a stalled image pull (rate-limited registry, TLS-intercepting proxy) also spins forever — even with a healthy process object.

Change

• Spawn under -ErrorAction Stop + try/catch: temp logs and the proxy-config dir (contains proxy credentials) are cleaned up, then a real error with the exception text, install-log path, and remedy.
• New Wait-ProcessWithDeadline (spinner + deadline + best-effort kill, unit-testable): create wait bounded at 15 min (TB_CREATE_TIMEOUT_MIN override). On expiry: last 5 lines of k3d stderr, the install-log path, cleanup, loud failure.
• Pester: deadline/kill behavior on fake processes, spawn-fails-fast gate, and a regression gate asserting the unbounded HasExited loop stays gone.
• manifest.sha256 regenerated.

The bash half of #426 (same missing bounds in cluster.sh + install-client-helm.sh) comes as its own PR — different test framework, same pattern.

Stacked on #438 → #437 — merge in that order; this branch contains both.

Type

Bug fix

Test plan

Full Pester suite locally on pwsh 7.5 (CI invocation): 169 passed, 0 failed, 8 skipped (4 new). gen-manifest.sh --check clean.

🤖 Generated with Claude Code

---

Note

Low Risk
Changes are confined to the Windows install script’s k3d create/wait path with new unit tests; no auth, data, or production runtime behavior is affected.

Overview
Fixes two Windows installer hangs during k3d cluster create: a failed Start-Process left $k3dProc null and an infinite spinner (#412), and k3d cluster create --wait had no upper bound on stalled image pulls (#426).

Spawn path: Start-Process now uses -ErrorAction Stop with try/catch so a broken k3d.exe exits immediately after cleaning temp logs and proxy config, with a clear error instead of spinning forever.

Bounded wait: Cluster creation uses new Wait-ProcessWithDeadline (spinner, deadline, best-effort kill). Default timeout is 15 minutes, overridable via TB_CREATE_TIMEOUT_MIN. On timeout the installer surfaces the last lines of k3d stderr/stdout, cleans up, runs a 2-minute-bounded k3d cluster delete to avoid leaving a partial cluster that the next run would reuse (#439), then fails with remediation hints.

Pester covers deadline/kill behavior and script-level regression gates; manifest.sha256 is updated for install-k8s.ps1.

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

[LukasWodka]

bugbot run

[LukasWodka]

bugbot run

[LukasWodka]

bugbot run

[LukasWodka]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

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

[shujaatTracebloc]

Reviewed the code and ran the full Pester suite locally at HEAD (a8a38c41) with the exact CI invocation (TB_PESTER=1, whole scripts/tests dir) on pwsh 7.6.4 / Pester 6.0.1: 173 passed, 0 failed, 8 skipped (the 8 skips are Windows-only CIM/drive probes, unrelated to this change). All 5 new tests in the Bounded cluster-create wait (#412 / #426) block pass, and the manifest integrity gate re-confirms the regenerated manifest.sha256.

The change is sound:

• #412 fixed — spawn wrapped in try/catch + -ErrorAction Stop, fails fast instead of spinning over a null $k3dProc.
• #426 (Windows half) fixed — create wait bounded at 15 min via Wait-ProcessWithDeadline (TB_CREATE_TIMEOUT_MIN override).
• Bugbot 'Timeout orphans cluster on re-run' addressed — bounded k3d cluster delete on timeout, with a clear operator-warning fallback; thread resolved and latest Bugbot run clean.
• Cleanup of temp logs + the proxy-cred dir is consistent across all three exit branches.

Non-blocking nits (fine to defer): the timeout-path k3d cluster delete spawn doesn't redirect stdout/stderr, so its output can interleave with the spinner (cosmetic); TB_CREATE_TIMEOUT_MIN=0 is accepted → immediate timeout (no floor).

Merge note: land #438 → #439 in order (#438 should be retargeted to develop now that #437 is merged).

LGTM 🚀

[shujaatTracebloc]

Ran the full Pester suite locally at HEAD (a8a38c41) with the exact CI invocation (TB_PESTER=1, whole scripts/tests dir) on pwsh 7.6.4 / Pester 6.0.1:

Tests Passed: 173, Failed: 0, Skipped: 8, Inconclusive: 0

All 5 new tests in the Bounded cluster-create wait (#412 / #426) block pass, and the manifest integrity gate re-confirms the regenerated manifest.sha256. The 8 skips are Windows-only CIM/drive probes (Get-PfCpu/Get-PfMemGb/Get-PfVirtualization/Get-PfFsType), skipped on macOS and unrelated to this change — CI's windows-latest leg exercises them.

Note: the installer test suite doesn't run in CI here because this PR targets the fix/410-pin-k3d-helm feature branch (installer-tests.yaml only triggers on PRs to main/develop/openshift), so this is the local stand-in for that coverage. ✅