@@ -422,18 +422,34 @@ export const _probeBeginFrameSupportForTests = probeBeginFrameSupport;
422422export const _closeBrowserAfterFailedProbeForTests = closeBrowserAfterFailedProbe ;
423423
424424/**
425- * Cached *in-flight or resolved* probe Promise for `resolveBrowserGpuMode("auto", ...)`.
425+ * Outcome of the one-shot WebGL probe.
426+ *
427+ * `cause` distinguishes the two ways a probe lands on `"software"`, because
428+ * they need OPPOSITE remediation:
429+ * - `"no-gpu"` — the probe ran and Chrome reported a software renderer
430+ * (SwiftShader / llvmpipe). Remediation: GPU passthrough.
431+ * - `"probe-error"` — the probe itself failed (Chrome couldn't launch, bad
432+ * executable path, sandbox denied). We have NO evidence
433+ * about the GPU either way; telling the operator to fix GPU
434+ * passthrough would send them chasing the wrong problem.
435+ */
436+ interface GpuProbeOutcome {
437+ mode : "software" | "hardware" ;
438+ cause ?: "no-gpu" | "probe-error" ;
439+ }
440+
441+ /**
442+ * Cached *in-flight or resolved* probe Promise, shared by BOTH the `"auto"`
443+ * and explicit `"hardware"` entry points of `resolveBrowserGpuMode`.
426444 *
427445 * Caching the Promise (rather than the resolved value) deduplicates concurrent
428446 * callers — the parallel coordinator runs N workers via `Promise.all`, so a
429447 * `--workers 4` render against a no-GPU host would otherwise fire 4
430448 * simultaneous probe Chromes. The first call assigns the Promise and every
431449 * other concurrent caller awaits the same one, paying the ~240 ms probe cost
432450 * exactly once per process lifetime.
433- *
434- * Exported for tests; production callers go through `resolveBrowserGpuMode`.
435451 */
436- let _autoBrowserGpuModeCache : Promise < "software" | "hardware" > | undefined ;
452+ let _autoBrowserGpuModeCache : Promise < GpuProbeOutcome > | undefined ;
437453
438454/** Test-only: reset the cached probe result. */
439455export function _resetAutoBrowserGpuModeCacheForTests ( ) : void {
@@ -479,15 +495,15 @@ async function probeAutoBrowserGpuMode(options: {
479495 chromePath ?: string ;
480496 browserTimeout ?: number ;
481497 platform ?: NodeJS . Platform ;
482- } ) : Promise < "software" | "hardware" > {
498+ } ) : Promise < GpuProbeOutcome > {
483499 const platform = options . platform ?? process . platform ;
484500 const browserTimeout = options . browserTimeout ?? DEFAULT_CONFIG . browserTimeout ;
485501 const executablePath = options . chromePath ?? resolveHeadlessShellPath ( { } ) ;
486502 const ppt = await getPuppeteerOrNull ( ) ;
487503
488504 if ( ppt === null ) {
489505 logResolvedBrowserGpuMode ( "software" , "puppeteer unavailable" ) ;
490- return "software" ;
506+ return { mode : "software" , cause : "probe-error" } ;
491507 }
492508
493509 try {
@@ -498,10 +514,10 @@ async function probeAutoBrowserGpuMode(options: {
498514 } ) ;
499515 const resolved = resolveWebGlProbeMode ( info ) ;
500516 logResolvedBrowserGpuMode ( resolved , describeWebGlProbe ( info ) ) ;
501- return resolved ;
517+ return resolved === "hardware" ? { mode : "hardware" } : { mode : "software" , cause : "no-gpu" } ;
502518 } catch ( err ) {
503519 logResolvedBrowserGpuMode ( "software" , formatProbeFailure ( err ) ) ;
504- return "software" ;
520+ return { mode : "software" , cause : "probe-error" } ;
505521 }
506522}
507523
@@ -542,32 +558,53 @@ export function resolveBrowserGpuMode(
542558 if ( mode === "software" ) return Promise . resolve ( mode ) ;
543559
544560 _autoBrowserGpuModeCache ??= probeAutoBrowserGpuMode ( options ) ;
545- if ( mode === "auto" ) return _autoBrowserGpuModeCache ;
561+ if ( mode === "auto" ) return _autoBrowserGpuModeCache . then ( ( probed ) => probed . mode ) ;
546562
547563 return _autoBrowserGpuModeCache . then ( ( probed ) => {
548- // Warn once per process , not once per caller: `createCaptureSession`
564+ // Warn once per cache lifetime , not once per caller: `createCaptureSession`
549565 // resolves the mode for the probe browser AND every parallel worker, so
550566 // an un-deduplicated warning prints N+1 times and buries itself.
551- if ( probed === "software" && ! _unverifiedHardwareGpuWarned ) {
567+ if ( probed . mode === "software" && ! _unverifiedHardwareGpuWarned ) {
552568 _unverifiedHardwareGpuWarned = true ;
553- console . warn ( buildUnverifiedHardwareGpuWarning ( options . platform ?? process . platform ) ) ;
569+ console . warn (
570+ buildUnverifiedHardwareGpuWarning ( options . platform ?? process . platform , probed . cause ) ,
571+ ) ;
554572 }
555573 return "hardware" ;
556574 } ) ;
557575}
558576
559- /** One-shot latch for the explicit-hardware-probed-to-software warning. */
577+ /**
578+ * Latch for the explicit-hardware-probed-to-software warning: fires once per
579+ * cache lifetime (re-armed by `_resetAutoBrowserGpuModeCacheForTests`).
580+ */
560581let _unverifiedHardwareGpuWarned = false ;
561582
562583/**
563- * Warning text for "you asked for hardware GPU, the probe found none ".
584+ * Warning text for "you asked for hardware GPU and we could not confirm it ".
564585 *
565- * Names the observable symptom (the render still completes, just on CPU) and
566- * the platform's actual remediation, so the operator doesn't have to infer it
567- * from Chrome's `Automatic fallback to software WebGL` warning. Exported for
568- * tests.
586+ * Splits on `cause` because the two failure shapes need opposite remediation.
587+ * A probe that RAN and saw SwiftShader is a GPU-passthrough problem. A probe
588+ * that could not run tells us nothing about the GPU — pointing that operator
589+ * at `--gpus all` would send them chasing a phantom while their Chrome
590+ * install is the actual fault.
569591 */
570- export function buildUnverifiedHardwareGpuWarning ( platform : NodeJS . Platform | string ) : string {
592+ function buildUnverifiedHardwareGpuWarning (
593+ platform : NodeJS . Platform | string ,
594+ cause : GpuProbeOutcome [ "cause" ] ,
595+ ) : string {
596+ if ( cause === "probe-error" ) {
597+ return (
598+ "[hyperframes] browserGpuMode=hardware was requested, but the GPU probe could not run, " +
599+ "so hardware acceleration is UNVERIFIED — if Chrome falls back to software WebGL the " +
600+ "capture will run at CPU speed. Honouring the explicit request anyway.\n" +
601+ " This is a probe failure, not evidence of a missing GPU: see the " +
602+ "`browserGpuMode probe → software (probe failed ...)` line above for the underlying " +
603+ "error, which usually means Chrome could not launch (bad HYPERFRAMES_BROWSER_PATH, " +
604+ "missing shared libraries, or a denied sandbox) rather than a GPU problem.\n" +
605+ " Run `hyperframes doctor` to check the Chrome install."
606+ ) ;
607+ }
571608 const remediation =
572609 platform === "linux"
573610 ? "Inside Docker, the container needs GPU passthrough: `--gpus all` with the NVIDIA " +
0 commit comments