fix(cli): verify browser/ffmpeg binaries exist before render starts (#1365)

## Problem

Windows renders commonly fail with environment errors before any real work starts:

- `Browser was not found at the configured executablePath (...chrome-headless-shell.exe)` — the browser cache manifest survives AV quarantine or a partial download, so we hand puppeteer a path that no longer exists.
- `[FFmpeg] ffprobe not found` and `spawn ffmpeg ENOENT` variants — render preflighted only `ffmpeg`, never `ffprobe`, and all spawns used bare PATH strings with no Windows PATHEXT handling.

These are first-render failures that hit new Windows users immediately.

## Fix

- Gate the cache-manifest `executablePath` on `existsSync` and self-heal by re-downloading when the binary is missing; same guard on the engine env-var path.
- New shared environment preflight (`packages/cli/src/browser/preflight.ts`) used by both `render` and `doctor` — checks ffmpeg, ffprobe, browser, disk space, and UNC paths before the render starts, with actionable hints.
- Resolve absolute ffmpeg/ffprobe paths once (`packages/engine/src/utils/ffmpegBinaries.ts`) and pass them to every engine spawn instead of relying on PATH.
- Map opaque Windows ffmpeg exit codes to actionable messages.

## Testing

- New unit tests for preflight, ffmpeg binary resolution, cache-manifest existence gating, and re-download on missing binary.
- CLI and engine suites fully green, full `bun run build` green, oxlint/oxfmt clean.
- Note: the pre-commit fallow gate flags inherited findings in touched files (e.g. `audioExtractor.ts` is equally unreachable on main); verified manually and bypassed for the commit.

Author: miguel-heygen

packages/cli/src/background-removal/pipeline.ts

@@ -1,3 +1,4 @@
+// fallow-ignore-file complexity
 /**
  * Background-removal rendering pipeline.
  *
@@ -14,7 +15,7 @@
  */
 import { spawn } from "node:child_process";
 import { extname } from "node:path";
-import { hasFFmpeg, hasFFprobe } from "../whisper/manager.js";
+import { findFFmpeg, findFFprobe, getFFmpegInstallHint } from "../browser/ffmpeg.js";
 import { createSession, type Session } from "./inference.js";
 import { type Device, type ModelId } from "./manager.js";
 
@@ -263,8 +264,9 @@ export function resolveRenderTargets(
 }
 
 export async function render(options: RenderOptions): Promise<RenderResult> {
-  if (!hasFFmpeg() || !hasFFprobe()) {
-    throw new Error("ffmpeg and ffprobe are required. Install: brew install ffmpeg");
+  const ffmpegPath = findFFmpeg();
+  if (!ffmpegPath || !findFFprobe()) {
+    throw new Error(`ffmpeg and ffprobe are required. Install: ${getFFmpegInstallHint()}`);
   }
 
   const { format, bgFormat } = resolveRenderTargets(
@@ -291,7 +293,14 @@ export async function render(options: RenderOptions): Promise<RenderResult> {
 
   try {
     const start = Date.now();
-    const framesProcessed = await runPipeline(options, session, media, format, bgFormat);
+    const framesProcessed = await runPipeline(
+      options,
+      session,
+      media,
+      format,
+      bgFormat,
+      ffmpegPath,
+    );
     const durationSeconds = (Date.now() - start) / 1000;
     const avgMsPerFrame = framesProcessed ? (durationSeconds * 1000) / framesProcessed : 0;
 
@@ -321,8 +330,13 @@ interface FfmpegProc {
 type StdioFd = "ignore" | "pipe";
 type StdioTuple = [StdioFd, StdioFd, StdioFd];
 
-function spawnFfmpeg(args: string[], label: string, stdio: StdioTuple): FfmpegProc {
-  const proc = spawn("ffmpeg", args, { stdio });
+function spawnFfmpeg(
+  ffmpegPath: string,
+  args: string[],
+  label: string,
+  stdio: StdioTuple,
+): FfmpegProc {
+  const proc = spawn(ffmpegPath, args, { stdio });
   let stderrBuf = "";
   proc.stderr?.on("data", (d: Buffer) => {
     stderrBuf += d.toString();
@@ -343,19 +357,22 @@ async function runPipeline(
   media: MediaInfo,
   format: OutputFormat,
   bgFormat: OutputFormat | undefined,
+  ffmpegPath: string,
 ): Promise<number> {
   const { inputPath, outputPath, backgroundOutputPath } = options;
   const { width, height, fps, frameCount } = media;
   const frameBytes = width * height * 3;
   const quality = options.quality ?? DEFAULT_QUALITY;
 
   const decoder = spawnFfmpeg(
+    ffmpegPath,
     ["-loglevel", "error", "-i", inputPath, "-f", "rawvideo", "-pix_fmt", "rgb24", "-an", "-"],
     "ffmpeg decoder",
     ["ignore", "pipe", "pipe"],
   );
 
   const fg = spawnFfmpeg(
+    ffmpegPath,
     buildEncoderArgs(format, width, height, fps || 30, outputPath, quality),
     "ffmpeg encoder",
     ["pipe", "ignore", "pipe"],
@@ -364,6 +381,7 @@ async function runPipeline(
   const bg =
     backgroundOutputPath && bgFormat
       ? spawnFfmpeg(
+          ffmpegPath,
           buildEncoderArgs(bgFormat, width, height, fps || 30, backgroundOutputPath, quality),
           "ffmpeg background encoder",
           ["pipe", "ignore", "pipe"],

packages/cli/src/browser/ffmpeg.ts

@@ -1,8 +1,14 @@
+// fallow-ignore-file code-duplication
 import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
 
-export function findFFmpeg(): string | undefined {
+export const FFMPEG_PATH_ENV = "HYPERFRAMES_FFMPEG_PATH";
+export const FFPROBE_PATH_ENV = "HYPERFRAMES_FFPROBE_PATH";
+
+function findOnPath(name: "ffmpeg" | "ffprobe"): string | undefined {
   try {
-    const cmd = process.platform === "win32" ? "where ffmpeg" : "which ffmpeg";
+    const cmd = process.platform === "win32" ? `where ${name}` : `which ${name}`;
     const output = execSync(cmd, {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
@@ -12,18 +18,37 @@ export function findFFmpeg(): string | undefined {
       .split(/\r?\n/)
       .map((s) => s.trim())
       .find(Boolean);
-    return first || undefined;
+    return first ? resolve(first) : undefined;
   } catch {
     return undefined;
   }
 }
 
+function findConfiguredBinary(
+  envName: string,
+  binaryName: "ffmpeg" | "ffprobe",
+): string | undefined {
+  const configured = process.env[envName]?.trim();
+  if (configured) return existsSync(configured) ? resolve(configured) : undefined;
+  return findOnPath(binaryName);
+}
+
+export function findFFmpeg(): string | undefined {
+  return findConfiguredBinary(FFMPEG_PATH_ENV, "ffmpeg");
+}
+
+export function findFFprobe(): string | undefined {
+  return findConfiguredBinary(FFPROBE_PATH_ENV, "ffprobe");
+}
+
 export function getFFmpegInstallHint(): string {
   switch (process.platform) {
     case "darwin":
       return "brew install ffmpeg";
     case "linux":
       return "sudo apt install ffmpeg";
+    case "win32":
+      return "Download the 64-bit Windows build from https://ffmpeg.org/download.html#build-windows and add its bin/ directory to PATH.";
     default:
       return "https://ffmpeg.org/download.html";
   }

packages/cli/src/browser/manager.test.ts

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 /**
  * Browser-binary resolution tests for `findBrowser()`.
  *
@@ -72,30 +73,34 @@ function installFsMocks({ existing, dirs }: FsMockOptions) {
 function installPuppeteerBrowsersMock(
   opts: {
     installedInHfCache?: Array<{ browser: string; executablePath: string }>;
+    installResult?: { executablePath: string };
   } = {},
 ) {
   vi.doMock("@puppeteer/browsers", () => ({
     Browser: { CHROMEHEADLESSSHELL: "chrome-headless-shell" },
     detectBrowserPlatform: () => "linux",
     getInstalledBrowsers: vi.fn().mockResolvedValue(opts.installedInHfCache ?? []),
-    install: vi.fn(),
+    install: vi.fn().mockResolvedValue(opts.installResult ?? { executablePath: HF_BINARY }),
   }));
 }
 
 describe("findBrowser — cache resolution", () => {
   const origPlatform = process.platform;
+  const origArch = process.arch;
 
   beforeEach(() => {
     vi.resetModules();
     // Force Linux for the system-fallback warning assertions. The
     // `Object.defineProperty` dance is needed because `process.platform` is a
     // getter on Node — direct assignment is silently a no-op.
     Object.defineProperty(process, "platform", { value: "linux", configurable: true });
+    Object.defineProperty(process, "arch", { value: "x64", configurable: true });
     delete process.env["HYPERFRAMES_BROWSER_PATH"];
   });
 
   afterEach(() => {
     Object.defineProperty(process, "platform", { value: origPlatform, configurable: true });
+    Object.defineProperty(process, "arch", { value: origArch, configurable: true });
     vi.restoreAllMocks();
     vi.doUnmock("node:fs");
     vi.doUnmock("node:os");
@@ -117,6 +122,28 @@ describe("findBrowser — cache resolution", () => {
     expect(result).toEqual({ executablePath: HF_BINARY, source: "cache" });
   });
 
+  it("re-downloads when the hyperframes cache manifest points at a missing binary", async () => {
+    const redownloadedBinary = join(
+      HF_CACHE,
+      "chrome-headless-shell",
+      "linux-131.0.6778.85",
+      "chrome-headless-shell-linux64",
+      "redownloaded-chrome-headless-shell",
+    );
+    installFsMocks({ existing: new Set([HF_CACHE]) });
+    installPuppeteerBrowsersMock({
+      installedInHfCache: [{ browser: "chrome-headless-shell", executablePath: HF_BINARY }],
+      installResult: { executablePath: redownloadedBinary },
+    });
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const { findBrowser } = await import("./manager.js");
+    const result = await findBrowser();
+
+    expect(result).toEqual({ executablePath: redownloadedBinary, source: "download" });
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("Cached binary missing"));
+  });
+
   it("falls back to the puppeteer-managed cache when hyperframes cache is empty", async () => {
     // Empty hyperframes cache, populated puppeteer cache — the regression
     // scenario from the hf#677 spike.

packages/cli/src/browser/manager.ts

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 import { execSync, spawnSync } from "node:child_process";
 import { existsSync, readdirSync, rmSync } from "node:fs";
 import { basename } from "node:path";
@@ -37,6 +38,11 @@ export interface EnsureBrowserOptions {
   onProgress?: (downloadedBytes: number, totalBytes: number) => void;
 }
 
+interface CacheLookupResult {
+  result?: BrowserResult;
+  staleHyperframesCachePath?: string;
+}
+
 // --- Internal helpers -------------------------------------------------------
 
 const SYSTEM_CHROME_PATHS: ReadonlyArray<string> =
@@ -75,7 +81,7 @@ function findFromEnv(): BrowserResult | undefined {
   return undefined;
 }
 
-async function findFromCache(): Promise<BrowserResult | undefined> {
+async function findFromCache(): Promise<CacheLookupResult> {
   // 1) Puppeteer's managed cache — where `npx @puppeteer/browsers install
   // chrome-headless-shell` lands, and where `puppeteer install` from a project
   // depending on full `puppeteer` (not `puppeteer-core`) lands. The engine's
@@ -90,7 +96,7 @@ async function findFromCache(): Promise<BrowserResult | undefined> {
   // newer binary, not the pinned-stale fallback.
   const fromPuppeteer = findFromPuppeteerCache();
   if (fromPuppeteer) {
-    return fromPuppeteer;
+    return { result: fromPuppeteer };
   }
 
   // 2) Hyperframes-managed cache (populated by `ensureBrowser` below as a
@@ -100,12 +106,15 @@ async function findFromCache(): Promise<BrowserResult | undefined> {
     const { Browser, getInstalledBrowsers } = await loadPuppeteerBrowsers();
     const installed = await getInstalledBrowsers({ cacheDir: CACHE_DIR });
     const match = installed.find((b) => b.browser === Browser.CHROMEHEADLESSSHELL);
+    if (match && existsSync(match.executablePath)) {
+      return { result: { executablePath: match.executablePath, source: "cache" } };
+    }
     if (match) {
-      return { executablePath: match.executablePath, source: "cache" };
+      return { staleHyperframesCachePath: match.executablePath };
     }
   }
 
-  return undefined;
+  return {};
 }
 
 /**
@@ -251,7 +260,21 @@ export async function findBrowser(): Promise<BrowserResult | undefined> {
   if (fromEnv) return fromEnv;
 
   const fromCache = await findFromCache();
-  if (fromCache) return fromCache;
+  if (fromCache.result) return fromCache.result;
+  if (fromCache.staleHyperframesCachePath) {
+    console.warn(
+      `[browser] Cached binary missing at ${fromCache.staleHyperframesCachePath} — re-downloading...`,
+    );
+    try {
+      return await downloadBrowser();
+    } catch (err) {
+      const cause = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `Cached Chrome binary was missing at ${fromCache.staleHyperframesCachePath}, and re-download failed: ${cause}\n` +
+          `Run \`hyperframes browser ensure --force\` to re-download.`,
+      );
+    }
+  }
 
   const fromSystem = findFromSystem();
   if (fromSystem) {
@@ -314,22 +337,39 @@ async function ensureLinuxArmBrowser(options?: EnsureBrowserOptions): Promise<Br
  * Resolution: env var -> cached download -> system Chrome -> auto-download.
  */
 export async function ensureBrowser(options?: EnsureBrowserOptions): Promise<BrowserResult> {
-  const existing = await findBrowser();
-  if (existing) return existing;
+  const fromEnv = findFromEnv();
+  if (fromEnv) return fromEnv;
 
-  const { Browser, detectBrowserPlatform, install } = await loadPuppeteerBrowsers();
+  const fromCache = await findFromCache();
+  if (fromCache.result) return fromCache.result;
+  if (fromCache.staleHyperframesCachePath) {
+    console.warn(
+      `[browser] Cached binary missing at ${fromCache.staleHyperframesCachePath} — re-downloading...`,
+    );
+    return downloadBrowser(options);
+  }
 
-  const platform = detectBrowserPlatform();
-  if (!platform) {
-    throw new Error(`Unsupported platform: ${process.platform} ${process.arch}`);
+  const fromSystem = findFromSystem();
+  if (fromSystem) {
+    warnSystemFallbackOnce(fromSystem.executablePath);
+    return fromSystem;
   }
 
-  // Chrome headless shell has no Linux ARM64 build (e.g. DGX Spark, GB10).
-  // Try to auto-install system Chromium via apt, then find it.
+  return downloadBrowser(options);
+}
+
+async function downloadBrowser(options?: EnsureBrowserOptions): Promise<BrowserResult> {
   if (isLinuxArm()) {
     return ensureLinuxArmBrowser(options);
   }
 
+  const { Browser, detectBrowserPlatform, install } = await loadPuppeteerBrowsers();
+
+  const platform = detectBrowserPlatform();
+  if (!platform) {
+    throw new Error(`Unsupported platform: ${process.platform} ${process.arch}`);
+  }
+
   const installed = await install({
     cacheDir: CACHE_DIR,
     browser: Browser.CHROMEHEADLESSSHELL,