fix(engine): force screenshot capture when GPU is software (broader than HDR-only guard)

[vanceingalls]

What

In packages/engine/src/services/browserManager.ts:acquireBrowser, resolve browserGpuMode (cheap — resolveBrowserGpuMode caches its probe Promise for the process lifetime) and force captureMode = "screenshot" whenever it resolves to "software", regardless of platform/binary. Strip BeginFrame-only chrome flags (--enable-begin-frame-control, --deterministic-mode, etc.) from the launch args when the guard kicks in. Mirror the same gate in packages/engine/src/services/frameCapture.ts's preMode computation so the chromeArgs are built without BeginFrame flags up front. Thread the already-resolved mode through to acquireBrowser via a new AcquireBrowserOptions.resolvedBrowserGpuMode so the call site does not re-resolve from raw config.

Why

On hosts with no hardware GPU (SwiftShader software rendering), Chrome's HeadlessExperimental.beginFrame stalls the compositor on shader-heavy frames — the CDP call hangs and the render eventually fails with beginFrame timed out at the protocolTimeout (default 5 min). This was reproduced during a recent BeginFrame spike on a CPU-only Linux sandbox.

This is an independent, defense-in-depth guard from the producer-side captureHdrStage.ts cfg.forceScreenshot = true:

• captureHdrStage.ts:211 already forces screenshot unconditionally for the HDR layered-composite path on main. That covers the HDR path on any host.
• This PR adds a separate guard at acquireBrowser for the SDR-render-on-software-host case — which captureHdrStage does not touch, and which is the load-bearing failure mode today (SDR renders on a software-renderer Linux host still hit the BeginFrame stall).
• Belt-and-braces: even when both paths land, having the GPU-mode guard at the launch site protects future code that might add new BeginFrame entry points (e.g. a future BeginFrame-alpha path) without remembering to gate on GPU presence.

Earlier framings of this PR described it as "broadening" a narrow compositeTransfer === "srgb" guard from PR #787. That framing was wrong — no such narrow guard exists on main; the HDR path's screenshot fallback is unconditional. The contribution stands on its own as the SDR-on-software-host fix.

How

1. acquireBrowser now accepts browserGpuMode in its config Pick and (optionally) a pre-resolved resolvedBrowserGpuMode via AcquireBrowserOptions. When the resolved mode is "software", the existing beginframe branch is skipped.
2. The launch args go through stripBeginFrameFlags whenever captureMode === "screenshot" — defensive against callers that built args before knowing the GPU resolution. (No-op when args are already clean.)
3. frameCapture.ts's preMode computation gets the same GPU gate so buildChromeArgs doesn't include BeginFrame flags up-front on software hosts; the resolved mode is then threaded into acquireBrowser to avoid a redundant re-resolve.
4. A one-time console.warn documents the resolution path for operators only when the guard actually changed the outcome — gated on !forceScreenshot && isSoftwareRenderer && headlessShell && isLinux, with a process-level latch so multi-worker renders don't spam.

resolveBrowserGpuMode caches the auto-probe Promise per process, so the threaded value is just a smell-removal — the underlying call would be free anyway after the first invocation.

Test plan

• Unit tests added (packages/engine/src/services/browserManager.test.ts, 8 new tests in acquireBrowser — software-renderer guard):
  • software → captureMode forced to screenshot + BeginFrame flags stripped
  • hardware + Linux + headless-shell → captureMode stays beginframe, flags preserved
  • forceScreenshot: true still wins regardless of GPU mode (regression guard for existing behavior)
  • one-time software-GPU console.warn fires when the guard changed the outcome
  • no warning on macOS (already screenshot anyway)
  • no warning when caller set forceScreenshot: true (guard did not change outcome)
  • no warning on Linux + hardware + headless-shell (positive control: the gate works in the right direction)
  • fallback launch retry: probeBeginFrameSupport failure → close + re-launch with stripBeginFrameFlags(chromeArgs) (covers the pre-existing defense-in-depth path)
• bun run --filter @hyperframes/engine typecheck — passes
• bun run --filter @hyperframes/engine build — passes
• bun run --filter @hyperframes/engine test — 596/599 passing (3 ffprobe.test.ts failures are pre-existing on origin/main, unrelated: PNG cICP metadata extraction + ffprobe binary handling)
• bun run --filter @hyperframes/producer typecheck — passes (consumer of the changed types)

— Vai