fix(localbox): improve deployment reliability — VHDX copy, VM verification, task trigger, RP polling, SYSTEM context

[nekdima]

Summary

While preparing LocalBox environments for MicroHack workshops (50+ participants, 3+ subscriptions), we hit repeated deployment failures. Colleagues have also reported random cluster deployment failures independently. The root causes were hard to diagnose — scripts continued past errors silently, and failures only surfaced much later as cryptic downstream errors.

Changes

Fix 1 — VHDX copy verification with retry (New-LocalBoxCluster.ps1)

The VHDX copy path could fail silently, allowing VM creation to continue without valid OS disks and later fail at Mount-VHD. Replaced the copy flow with source pre-check, try/catch + -ErrorAction Stop, post-copy size validation, and up to 3 retries with 10-second backoff.

Fix 2 — Node VM post-creation verification (New-LocalBoxCluster.ps1)

After New-AzLocalNodeVM, there was no validation that the Hyper-V VM and attached VHDX were actually present. Added explicit verification using Get-VM and Get-VMHardDiskDrive, plus null-check validation for the returned MAC address before continuing.

Fix 3 — Missing scheduled task trigger (Bootstrap.ps1)

LocalBoxLogonScript was registered without a trigger, so it never fired in headless deployments. Added the missing logon trigger (-AtLogOn) to align behavior with the existing task registration pattern.

Fix 4 — Resource provider registration polling (New-LocalBoxCluster.ps1)

az provider register --wait can return before registration fully propagates to HCI node context. Added explicit polling for 8 mandatory providers (15-second interval, 5-minute timeout) before the existing 600-second sleep, with non-blocking timeout fallback to preserve progress while improving reliability.

Fix 5 — SYSTEM context handling (LocalBoxLogonScript.ps1)

When the LocalBoxLogonScript scheduled task runs as SYSTEM (via the AtLogOn trigger in headless CI), it crashes at line 47 because $Env:USERPROFILE\Desktop does not exist for the SYSTEM profile, and code.exe (VS Code) is not in the SYSTEM PATH. These are non-critical UI setup steps (desktop shortcuts, VS Code extensions) that should not abort the entire bootstrap. Wrapped all UI-related setup blocks in try/catch and added a Get-Command code guard for VSCode extension install.

Files Modified

File	Lines	Fixes
New-LocalBoxCluster.ps1	+104 / -4	Fixes 1, 2, 4
Bootstrap.ps1	+3 / -1	Fix 3
LocalBoxLogonScript.ps1	+43 / -21	Fix 5

Testing

• Syntax validation: all three files parse cleanly
• Tested on Windows Server 2022 VM (Standard_D4s_v5) with Hyper-V in Azure (Sweden Central)
• VHDX copy (fix 1): copy + size verification ✅, source-missing throw ✅, size-mismatch detection ✅
• VM verification (fix 2): VM + VHDX verify via Get-VMHardDiskDrive ✅, missing VM throw ✅, no-VHD throw ✅, MAC null-check ✅
• Task trigger (fix 3): trigger registration confirmed ✅, task not auto-started ✅
• RP polling (fix 4): Select-Object -Unique returns scalar ✅, registered/unregistered comparison ✅, no System.Object[] in logs ✅
• SYSTEM context (fix 5): Desktop folder creation fallback ✅, VSCode skip when not in PATH ✅, script continues past UI errors ✅

Production Deployment Evidence

These fixes have been validated across 60+ GitHub Actions workflow runs deploying LocalBox to 3 Azure subscriptions simultaneously. The SYSTEM context fix (fix 5) was the final missing piece — without it, the scheduled task would crash before starting nested VMs in headless deployments.