fix(cli): surface HYPERFRAMES_BROWSER_PATH hint on macOS <13 chrome-headless-shell dyld crash

[vanceingalls]

What

Add a darwin-scoped launch-crash remediation to handleRenderError in packages/cli/src/commands/render.ts. When the pinned chrome-headless-shell binary fails to launch with dyld: Symbol not found: _kVTCompressionPropertyKey_ReferenceBufferCount from VideoToolbox, surface a scoped errorBox that names HYPERFRAMES_BROWSER_PATH (and its PRODUCER_HEADLESS_SHELL_PATH alias — see #2471) with a macOS-specific chrome-headless-shell@150 install command.

Why

Field feedback in #hyperframes-cli-feedback — message ts 1784227832, darwin/x64 macOS 12, HyperFrames CLI 0.7.60 — hit the exact error dyld: Symbol not found: _kVTCompressionPropertyKey_ReferenceBufferCount referenced from VideoToolbox when launching the bundled chrome-headless-shell mac-152.0.7928.2. The symbol was added in macOS 13; older hosts cannot resolve it, so the binary aborts at load before any browser process starts.

The reporter recovered by installing chrome-headless-shell@150 via @puppeteer/browsers and pointing PRODUCER_HEADLESS_SHELL_PATH at it. Their check/snapshot commands accepted the older cached shell (they call ensureBrowser() without preferManagedChrome, so any cached headless-shell is fine), but render requires the pinned v152 via preferManagedChrome: true and therefore couldn't fall back on its own. Their 49s 1080x1920 render then completed cleanly.

The CLI's generic post-render hint (Try --docker etc.) doesn't name any of the browser-path env vars, so the workaround is undiscoverable unaided.

This is the third platform-scoped sibling of #2443 (download-time hint):

• fix(cli): actionable remediation for chrome-headless-shell SIGTRAP on arm64 macOS [P2] #2078 — arm64 SIGTRAP at launch (macOS ARM, closed-with-invite)
• fix(cli): surface HYPERFRAMES_BROWSER_PATH hint on Windows chrome-headless-shell launch crashes #2481 — Windows STATUS_STACK_BUFFER_OVERRUN at launch (open)
• this PR — macOS <13 dyld Symbol-not-found at launch

Same remediation surface, different trigger and platform.

How

• New packages/cli/src/browser/macosOldChromeCrash.ts — exports isMacosOldChromeCrashError(errorMessage) and macosOldChromeCrashRemediation(errorMessage). The detector requires ALL of:
  1. Puppeteer wrapper text Failed to launch the browser process
  2. dyld Symbol not found: signal
  3. either the specific macOS-13-only symbol name _kVTCompressionPropertyKey_ReferenceBufferCount OR the VideoToolbox framework name
• macosOldChromeCrashRemediation returns undefined off darwin.
• render.ts handleRenderError invokes macosOldChromeCrashRemediation(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; the Windows detector proposed in fix(cli): surface HYPERFRAMES_BROWSER_PATH hint on Windows chrome-headless-shell launch crashes #2481 is untouched (different file).
• Why no os.release() gate. The symbol-name signal is macOS-version-specific by construction: _kVTCompressionPropertyKey_ReferenceBufferCount only exists on macOS 13+, so if a user's dyld cannot find it, their host is <13. A Darwin 22+ check would be redundant.
• The remediation intentionally names both HYPERFRAMES_BROWSER_PATH (canonical, per fix(cli): surface HYPERFRAMES_BROWSER_PATH hint on pinned browser download failures #2443/fix(cli): surface HYPERFRAMES_BROWSER_PATH hint on Windows chrome-headless-shell launch crashes #2481) and its PRODUCER_HEADLESS_SHELL_PATH alias (per fix(cli): honor PRODUCER_HEADLESS_SHELL_PATH in findFromEnv #2471) because the reporter reached for the alias first — matching the discovery path the docs already point at.

Net diff: +182 / -0 across 3 files (2 new, 1 modified).

Test plan

• Unit tests added — packages/cli/src/browser/macosOldChromeCrash.test.ts (11 vitest cases):
  • positive match on the exact reporter error text
  • positive match on VideoToolbox framework signal without the exact ReferenceBufferCount symbol name (future pinned builds may hit sibling VT symbols)
  • negative on Linux shared-lib launch failures (those hit chromeLaunchRemediation)
  • negative on darwin Symbol-not-found from unrelated frameworks (e.g. libc++.dylib) — needs different remediation
  • negative on the symbol name alone without the launch-failure wrapper
  • off-platform (non-darwin) short-circuits and non-launch short-circuits
• bunx vitest run src/browser/macosOldChromeCrash.test.ts — 11/11 passing, 4ms
• bunx oxlint packages/cli/src/browser/macosOldChromeCrash{,\.test}.ts packages/cli/src/commands/render.ts — 0 warnings 0 errors
• bunx oxfmt — clean on all three files
• Manual testing performed — n/a; requires a macOS 12 host to reproduce the dyld failure. The unit tests deterministically cover the detector, and the reporter's original recovery path (setting PRODUCER_HEADLESS_SHELL_PATH) confirms the escape hatch works.
• 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

• Signed-off-by: Via -

[miga-heygen]

Review — fix(cli): surface HYPERFRAMES_BROWSER_PATH hint on macOS <13 chrome-headless-shell dyld crash

Scope: 3 files (+182/−0) — new detector + remediation module, test file, one integration site in render.ts.

SSOT analysis

No violations. The detector is self-contained — no shared predicates with the Linux chromeLaunchRemediation. Different platforms, different error signals, different remediation content. The fallow-ignore-file code-duplication pragma is appropriate (structural similarity with the Linux detector, genuinely different content).

What I checked

1. Detector logic. Three-gate AND chain: Failed to launch the browser process → Symbol not found: → (_kVTCompressionPropertyKey_ReferenceBufferCount OR VideoToolbox). The first two gates prevent false positives from unrelated errors; the third scopes to the macOS-13+ framework family. The OR on the third gate is intentional — future pinned builds may hit sibling VT symbols from the same framework, and the remediation (install an older shell) is the same for all of them.

2. Platform gating. isMacosOldChromeCrashError is pure string matching (testable anywhere). macosOldChromeCrashRemediation gates on process.platform !== "darwin". Clean separation — the detector is logic, the remediation is action.

3. Integration cascade. In handleRenderError: Linux check → macOS check → generic fallback. Each detector is self-scoping (Linux won't fire on darwin, macOS won't fire on Linux), so the order is for readability, not correctness. Neither matching → generic errorBox("Render failed", ...).

4. Test coverage. 11 cases:

   • Positive: exact reporter error, VideoToolbox-only variant
   • Negative: non-launch error, unrelated framework (libc++.dylib), symbol without launch wrapper, generic unrelated error
   • Platform: off-darwin returns undefined, on-darwin returns remediation with both env vars named
   • Content: asserts HYPERFRAMES_BROWSER_PATH, PRODUCER_HEADLESS_SHELL_PATH, and chrome-headless-shell@150 are all present in the output

5. No os.release() gate needed. The symbol _kVTCompressionPropertyKey_ReferenceBufferCount is itself the version discriminator — it only exists on macOS 13+, so a dyld failure to find it IS the version proof. The PR description explains this well; the comment in the source explains it well. No redundant check needed.

6. Remediation path is x64-specific (cache path includes chrome-headless-shell-mac-x64). Reasonable — the field signal is from darwin/x64, and arm64 Macs shipped with macOS 11 but have been on 13+ since launch year. An arm64 user on macOS <13 would be extremely rare.

Verdict

Clean, well-scoped fix. Detector is tight (three-gate AND), platform-gated, and well-tested. Slots into the existing remediation cascade without touching Linux or Windows paths.

— Miga