PowerShell installer must never terminate ungracefully — always show the user a clean 'what happened'

[shujaatTracebloc]

Filed from a field install on a restricted corporate network. Companion issues: log-hygiene (no info leak) and network-resilience.

Problem statement

When the install fails, PowerShell must never terminate ungracefully. Today it dies with a raw terminating-error dump — stack, source line, PS>TerminatingError() — leaving the user with a scary crash and no idea what happened or what to do. The user should always see a clean, human explanation of what happened during the installation and the exact next step; the window/session should never just die on them.

Observed (the field log):

PS>TerminatingError(): "cosign signature verification FAILED for manifest.sha256 -- refusing to install."
+ & $cosign @cosignArgs 2>$null 1>$null
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 + CategoryInfo : NotSpecified: (...) [], RemoteException
 + FullyQualifiedErrorId : NativeCommandError

Explanation (root cause)

The installer's failure paths are bare throws (and unhandled native-command stderr) with no try/catch around main(). An unhandled terminating error makes PowerShell print the raw error and end the script. There is no graceful closer, no classification of fatal vs recoverable, and no guaranteed "here's your log / here's what to do" message. So a network hiccup surfaces as a crash instead of a diagnosis.

Proposed solution

1. A single top-level try / catch / finally (+ trap) in the bootstrap and the main installer. The catch renders one clean, branded block — what failed, why in plain terms, the exact next steps, and where the log is — then exit <code>. No stack, no source line, ever.
2. Classify failures fatal vs recoverable. Optional/recoverable steps warn and continue (the GPU-toolkit timeout already does this correctly — "GPU not set up, continuing in CPU mode"). Only a genuine can't-proceed stops — and stops cleanly. Apply that pattern consistently.
3. Every native call bounded + exit-code-checked (the installer already has Invoke-Bounded / Wait-ProcessWithDeadline; the raw & $cosign at line 360 was the one that slipped through and became a crash). A wedged or erroring tool becomes a handled condition, never a terminating error.
4. A guaranteed finally that always prints "Log saved to … — send it to support if you're stuck" and stops the transcript cleanly, so the window never just disappears.

This is the substrate the other two issues rely on: it's what converts a network block into "your network is blocking X — here's what to do" instead of a stack dump.
Severity: Tier 1 — UX / trust. Confidence: CONFIRMED.

[shujaatTracebloc]

Installer-robustness set: #576 log hygiene · #577 graceful failure (this) · #578 network resilience. This is the substrate the other two rely on — it turns a network block into a clean 'what happened' instead of a crash.

[LukasWodka]

@shujaatTracebloc — context + what I confirmed for the graceful-failure piece. This is the substrate the other two rely on, so it's the one I'd land first.

The bar

The installer must never terminate ungracefully. On any failure the user always gets one clean, branded block: what failed, why in plain words, the exact next step, and where the log is — then a clean exit. Never a stack, never a source line, and the window must never just die or dump a crash. A network hiccup should read as a diagnosis, not a crash.

This is a both-platforms requirement. When we ran the bash script it also disclosed raw failure output — so this isn't PowerShell-only. The title says PowerShell; the principle is cross-platform (see the bash note below).

What I confirmed in the code

• No top-level handler in PowerShell. The main flow in scripts/install-k8s.ps1 (Test-Preflight → Install-DockerDesktop → … → Print-Summary) is a bare call sequence — the only wrapper is the TB_PESTER test guard, not error handling. There are ~79 inner catches, but a genuine throw (the cosign one) propagates straight to the top → PowerShell renders the source line + stack, and Stop-Transcript never runs (the transcript stays open with the raw dump in it).
• Bootstrap prints the raw exception: scripts/install.ps1:477 → Err "$_".
• Bash has a clean closer but not clean failure. The EXIT trap install_cleanup (scripts/lib/common.sh:811) does print a friendly "Installation did not complete… safe to re-run… log at …" — good. But under set -euo pipefail the failing tool's raw stderr prints first, then the closer. So the user still sees the raw helm/kubectl/curl error before the friendly line. Same fix needed: capture tool stderr → translate to a curated line.

Acceptance

• PowerShell: one top-level try / catch / finally (+ trap) in both install.ps1 and install-k8s.ps1, mirroring bash's EXIT trap. The catch renders one clean branded block and exit <code> — no stack, no source line, ever.
• Classify fatal vs recoverable. Recoverable/optional steps warn and continue (the GPU-toolkit timeout already does this correctly — "GPU not set up, continuing in CPU mode"); only a genuine can't-proceed stops, and stops cleanly. Apply that pattern consistently.
• Every native call bounded + exit-code-checked. We already have Invoke-Bounded / Wait-ProcessWithDeadline; the raw & $cosign was the one that slipped through and became the crash. A wedged/erroring tool becomes a handled condition, never a terminating error.
• Guaranteed finally that always prints "Log saved to … — send it to support if you're stuck" and stops the transcript cleanly, so the window never just disappears.
• Bash symmetry: wrap the risky native steps so their raw stderr is captured and re-emitted as our curated line before the closer — so bash gives graceful failure, not just a graceful closer.

Copy/tone: same house style as #576 — plain language, lowercase tracebloc, feels one-to-one with the bash script.