fix: make doctor's Chrome check and browser path predict render's resolution

[miga-heygen]

Summary

doctor's Chrome check and hyperframes browser path both called the public findBrowser() (in packages/cli/src/browser/manager.ts) with no options, which resolves loosely: any puppeteer-cached chrome-headless-shell version, then the hyperframes-managed cache (exact CHROME_VERSION pin), then system Chrome. Render's actual resolution (ensureBrowser({ preferManagedChrome: true }), used by render/execute.ts, studioServer.ts, and browser ensure) is stricter — it only accepts the exact-pinned managed-cache build, skipping both the puppeteer-cache and system-Chrome fallbacks entirely.

So doctor/browser path could report a "cache hit" against a wrong-version puppeteer-cache build or system Chrome, while the very next render call doesn't honor that at all and re-downloads the full pinned build — a false "you're good" signal immediately before an unexpected multi-minute download.

Fix

Added an optional preferManagedChrome option to the previously zero-arg findBrowser(), mirroring ensureBrowser's existing internal conditional shape: when set, it checks only the exact-pin hyperframes-managed cache and returns undefined instead of falling back to system Chrome. doctor's underlying checkChrome() and browser path's lookup (including its own not-found ensureBrowser() fallback) now pass this option, so a reported hit actually predicts render's behavior.

The four other pre-existing findBrowser() call sites (three inside ensureLinuxArmBrowser in manager.ts and one in browser ensure's ARM64 branch) stay unqualified: they only run on Linux ARM64, where the option is a no-op anyway (see below).

Linux ARM64: Chrome for Testing publishes no linux-arm64 chrome-headless-shell, so there is no managed cache to check against — ensureBrowser({ preferManagedChrome: true }) reroutes to system Chromium there (ensureLinuxArmBrowser). An early version of this fix passed the option unconditionally from checkChrome(), which would have made doctor report "Chrome not found" on every ARM64 machine, even one with a correctly installed system Chromium. Rather than have each caller carry that exception, the decision now lives once in manager.ts (resolvesManagedOnly: preferManagedChrome && !isLinuxArm()), shared by findBrowser and ensureBrowser. doctor, browser path, and any future caller get the right answer with the plain option, and a preferManagedChrome render on ARM64 resolves system Chromium directly instead of taking the install lock and detouring through the download path to reach it.

Stale cache: findBrowser is documented as "find without downloading", but its stale-cache branch (manifest present, executable missing) used to trigger a full re-download — from doctor. It now reports that state as "not found" and leaves the re-download to ensureBrowser; browser path already falls through to ensureBrowser on a miss, and doctor points at hyperframes browser ensure.

Test plan

• manager.test.ts: preferManagedChrome ignores a puppeteer-cache hit and resolves to the pinned managed cache when both are populated; does not report a false hit against an off-pin puppeteer-cache build (the exact reported scenario); does not fall back to system Chrome; still resolves HYPERFRAMES_BROWSER_PATH first; still finds system Chromium on Linux ARM64 (both findBrowser and ensureBrowser, the latter asserting the install lock is never taken). ensureBrowser({ preferManagedChrome: true }) on x64 with both caches populated returns the pinned managed binary without calling install(), where the unqualified call returns the puppeteer-cache one. findBrowser reports a stale managed-cache entry as not found without calling install(); the existing stale-cache re-download test now exercises ensureBrowser, which owns that path.
• preflight.test.ts: checkChrome calls findBrowser with { preferManagedChrome: true }.
• commands/browser.test.ts (new): hyperframes browser path on Linux ARM64 prints the system Chromium path without entering ensureBrowser. On x64 with a puppeteer-cache binary present and an empty managed cache, browser path does not print the puppeteer-cache path; both findBrowser and ensureBrowser are called with { preferManagedChrome: true }.
• bunx tsc --noEmit -p packages/cli clean; oxlint / oxfmt --check clean on all touched files; manager.test.ts + preflight.test.ts + commands/browser.test.ts + doctor.test.ts — 94/94 pass.
• Mutation checks: dropping the !isLinuxArm() guard fails the ARM64 findBrowser test and the browser path test; bypassing resolvesManagedOnly in ensureBrowser alone fails its ARM64 test; ignoring the env var fails the env-first test (plus three pre-existing ones). Making either runPath resolution unqualified fails the x64 browser path test; keying ensureBrowser's first cache lookup off the unqualified path fails its x64 managed-only test; inverting lookupCache fails eight cache-resolution tests.

[miga-heygen]

Addressed in 0cb180f.

[miga-heygen]

Addressed in 24a611a.