Files
hyperframes/packages/cli/src
Vance Ingalls 7563b644a2 fix(cli): surface HYPERFRAMES_BROWSER_PATH hint on Windows chrome-headless-shell launch crashes (#2481)
* fix(cli): surface HYPERFRAMES_BROWSER_PATH hint on Windows chrome-headless-shell launch crashes

Field feedback (#hyperframes-cli-feedback ts=1784116246, win32/x64, CLI 0.7.58) hit
`Failed to launch the browser process ... Code: 3221225595` with no stderr. Exit
code 3221225595 = 0xC0000409 = STATUS_STACK_BUFFER_OVERRUN, a Windows stack-
corruption fatal from the pinned chrome-headless-shell binary. The reporter
recovered by pointing HYPERFRAMES_BROWSER_PATH at system Chrome; render then
used the screenshot fallback and produced the MP4 cleanly.

The generic "Try --docker" hint the CLI already emits didn't name that env var,
so the workaround was undiscoverable. Add a Windows-scoped launch-crash
remediation sibling to `chromeLaunchRemediation` (Linux, `linuxDeps.ts`) and
`wrapDownloadFailureWithBrowserPathHint` (download-time, `manager.ts` — #2443).
Fresh concrete case for the #2078 lineage (closed with explicit invite to
resubmit on a concrete case).

- New `packages/cli/src/browser/windowsCrash.ts` — `isWindowsChromeCrashError`
  gates on Puppeteer's `Failed to launch the browser process` wrapper AND the
  specific crash code (decimal `3221225595`, hex `0xC0000409`, or symbol
  `STATUS_STACK_BUFFER_OVERRUN`), so unrelated Windows launch failures don't
  mis-fire this hint. `windowsChromeCrashRemediation` returns the actionable
  block scoped to win32.
- `render.ts` `handleRenderError` calls it after the existing
  `chromeLaunchRemediation` (Linux) check; both fall through to the generic
  errorBox if neither matches.
- Tests: 9 vitest cases covering positive matches on all three code forms,
  negative on Linux-shared-lib launch failures, negative on the code alone
  without the launch wrapper, and off-platform / non-launch short-circuits.

— Via

* fix(cli): fail the Windows crash branch through failCommand, not process.exit

`scripts/check-cli-process-ownership.mjs` AST-walks every non-test file
under `packages/cli/src` (bar `cli.ts`) and forbids direct process
termination — only the CLI entrypoint owns exit. The new Windows
chrome-headless-shell arm called `process.exit(1)` while both sibling arms
(Linux shared-lib, macOS) and the generic fallback call `failCommand()`,
so the required Lint job failed on that line and preview-regression failed
downstream of its preflight.

`failCommand()` carries the central failure-hook wiring, so this is the
behaviour the branch already wanted.
2026-08-20 23:38:58 -07:00
..