fix(cli): surface HYPERFRAMES_BROWSER_PATH hint on Windows chrome-headless-shell launch crashes

[vanceingalls]

What

Add a Windows-scoped launch-crash remediation to handleRenderError in packages/cli/src/commands/render.ts. When the pinned chrome-headless-shell binary fails to launch with STATUS_STACK_BUFFER_OVERRUN (exit 0xC0000409 / 3221225595), surface a scoped errorBox that names HYPERFRAMES_BROWSER_PATH with an actionable per-platform example — same remediation as the download-time hint (#2443) and the closed-with-invite arm64 macOS sibling (#2078), different trigger + platform.

Why

Field feedback in #hyperframes-cli-feedback — message ts 1784116246, win32/x64, HyperFrames CLI 0.7.58 — hit the exact error Failed to launch the browser process ... Code: 3221225595 with no stderr. Exit code 3221225595 == 0xC0000409 == STATUS_STACK_BUFFER_OVERRUN, a Windows stack-corruption fatal reported against the pinned chrome-headless-shell binary on some Win10/Win11 hosts (typically pre-24H2 or particular AV/EDR combinations). The reporter recovered by pointing HYPERFRAMES_BROWSER_PATH at their system Google Chrome; the render then used the screenshot fallback and produced a complete MP4.

The CLI's generic post-render hint (Try --docker, etc.) doesn't name that env var, so the workaround is undiscoverable unaided. Same discoverability issue #2443 solved for the download-time failure mode; this is its launch-time sibling on Windows.

#2078 is the arm64-macOS sibling, closed 2026-07-14 with an explicit invitation: "Please reopen or resubmit against current main if the need is still concrete." This report is that fresh concrete case — distinct platform (win32/x64 vs darwin/arm64), distinct exit code (0xC0000409 vs SIGTRAP/EXC_BREAKPOINT), same remediation surface.

How

• New packages/cli/src/browser/windowsCrash.ts — exports isWindowsChromeCrashError(errorMessage) and windowsChromeCrashRemediation(errorMessage). The detector requires BOTH the Puppeteer wrapper text (Failed to launch the browser process) AND the specific crash-code signal (decimal 3221225595, hex 0xC0000409, or symbol name STATUS_STACK_BUFFER_OVERRUN) so unrelated Windows launch failures — which need different remediation — don't mis-fire this hint. windowsChromeCrashRemediation returns undefined off Windows.
• render.ts handleRenderError invokes windowsChromeCrashRemediation(message) immediately after the existing chromeLaunchRemediation (Linux) check. Neither matching → fall through to the generic errorBox("Render failed", ...). Linux path is untouched; the download-time wrap in manager.ts (fix(cli): surface HYPERFRAMES_BROWSER_PATH hint on pinned browser download failures #2443) is untouched.
• Naming: kept linuxDeps.ts for the Linux launch-side; new file for Windows-side to preserve single-responsibility. Bikeshed name in a follow-up if a third platform arrives.

Net diff: +132 / -0 across 3 files.

Test plan

• Unit tests added — packages/cli/src/browser/windowsCrash.test.ts (9 vitest cases):
  • positive matches on all three code forms (decimal / hex / symbol name)
  • negative on Linux-shared-lib launch failures (those hit chromeLaunchRemediation)
  • negative on the crash code alone without the launch-failure wrapper
  • off-platform (non-win32) short-circuits and non-launch short-circuits
• bunx vitest run src/browser/windowsCrash.test.ts — 9 passed
• bunx oxlint packages/cli/src/browser/windowsCrash{,\.test}.ts packages/cli/src/commands/render.ts — 0 warnings 0 errors
• bunx oxfmt — clean on all three files
• Manual testing performed — n/a, the crash requires a specific Windows host that reproduced it (would need to be reproduced on the reporter's environment)
• Documentation updated — n/a; the hint IS the documentation

Enterprise release / feature flag holdout

• N/A — this PR doesn't touch enterprise-relevant surfaces
• Ships to all users on merge without feature-flag holdout

UX/Screenshot recording

• No UI impact — CLI error-message content only

— Via

[miga-heygen]

Review — #2481 fix(cli): surface HYPERFRAMES_BROWSER_PATH hint on Windows chrome-headless-shell launch crashes

Verdict: LGTM — clean, focused, well-tested sibling to #2443.

SSOT check

HYPERFRAMES_BROWSER_PATH remediation now surfaces from three distinct failure modes:

Trigger	File	Detection
Download failure	manager.ts (#2443)	installWithCorruptArchiveRecovery catch
Windows launch crash	windowsCrash.ts (this PR)	Puppeteer wrapper + STATUS_STACK_BUFFER_OVERRUN
Linux missing libs	linuxDeps.ts	Shared-lib error pattern

Each has genuinely different detection logic and platform-specific remediation text. No duplicated decisions.

Code review

• Detection gating — correctly requires BOTH the Puppeteer Failed to launch the browser process wrapper AND one of the three crash-code forms (decimal 3221225595, hex 0xC0000409, symbol STATUS_STACK_BUFFER_OVERRUN). Prevents mis-firing on unrelated Windows launch failures that need different remediation.
• Platform guard — windowsChromeCrashRemediation returns undefined off Windows. Uses set (Windows env syntax) instead of export. Consistent.
• Windows Chrome path — C:\Program Files\Google\Chrome\Application\chrome.exe matches browserPathHintForPlatform() from #2443. Consistent.
• Integration point — slotted immediately after the existing chromeLaunchRemediation (Linux) in handleRenderError. Clean ordering: Linux check → Windows check → generic fallback.
• File separation — windowsCrash.ts parallel to linuxDeps.ts. Single responsibility. The comment about bikeshedding when a third platform arrives is practical.

Tests

9 cases: all three positive forms (decimal/hex/symbol), three negatives (no crash code, no launch wrapper, unrelated error), three windowsChromeCrashRemediation negatives (off-platform, non-launch, missing code). Good coverage.

No blockers. Ship it.