fix(render): consolidate preflight and local recovery (#2403)

* fix(render): fall back when libx264 is unavailable

* fix(render): recover orphaned browsers before retry

* fix(render): check disk space on write volumes

* test(engine): accept resolved ffmpeg binary paths

* fix(render): harden H.264 capability fallback

* chore(ci): scope inherited Fallow findings

* fix(render): diagnose encoder probe failures

packages/cli/src/commands/render.test.ts

@@ -72,6 +72,15 @@ const preflightState = vi.hoisted(() => ({
   },
 }));
 
+const ffmpegEncoderState = vi.hoisted(() => ({
+  mode: "software" as "software" | "gpu",
+  error: null as Error | null,
+}));
+const orphanCleanupState = vi.hoisted(() => ({
+  calls: 0,
+  killed: 0,
+}));
+
 vi.mock("../utils/producer.js", () => ({
   loadProducer: vi.fn(async () => ({
     resolveConfig: vi.fn((overrides: Record<string, unknown>) => {
@@ -120,6 +129,10 @@ vi.mock("../telemetry/events.js", () => ({
 }));
 
 vi.mock("../browser/ffmpeg.js", () => ({
+  detectH264EncoderMode: vi.fn(() => {
+    if (ffmpegEncoderState.error) throw ffmpegEncoderState.error;
+    return ffmpegEncoderState.mode;
+  }),
   findFFmpeg: vi.fn(() => "/usr/bin/ffmpeg"),
   getFFmpegInstallHint: vi.fn(() => "brew install ffmpeg"),
 }));
@@ -128,6 +141,13 @@ vi.mock("../browser/preflight.js", () => ({
   runEnvironmentChecks: vi.fn(async () => preflightState.result),
 }));
 
+vi.mock("../utils/orphanCleanup.js", () => ({
+  killOrphanedProcesses: vi.fn(() => {
+    orphanCleanupState.calls += 1;
+    return orphanCleanupState.killed;
+  }),
+}));
+
 describe("renderLocal browser GPU config", () => {
   const savedEnv = new Map<string, string | undefined>();
   // Pre-resolve once. The first dynamic `import("./render.js")` in this file
@@ -173,6 +193,10 @@ describe("renderLocal browser GPU config", () => {
     configState.writeConfigCalls = [];
     trackingState.shouldTrack = true;
     trackingState.renderObservations = [];
+    ffmpegEncoderState.mode = "software";
+    ffmpegEncoderState.error = null;
+    orphanCleanupState.calls = 0;
+    orphanCleanupState.killed = 0;
     resetTrialState();
     savedEnv.clear();
     savedEnv.set("HYPERFRAMES_FFMPEG_PATH", process.env.HYPERFRAMES_FFMPEG_PATH);
@@ -185,6 +209,22 @@ describe("renderLocal browser GPU config", () => {
     delete process.env.HF_DE_PARALLEL_ROUTER;
   });
 
+  it("cleans orphaned browser trees before starting a local render", async () => {
+    orphanCleanupState.killed = 1;
+
+    await renderLocal("/tmp/project", "/tmp/out.mp4", {
+      fps: { num: 30, den: 1 },
+      quality: "standard",
+      format: "mp4",
+      gpu: false,
+      browserGpuMode: "software",
+      hdrMode: "auto",
+      quiet: true,
+    });
+
+    expect(orphanCleanupState.calls).toBe(1);
+  });
+
   afterEach(() => {
     for (const [key, value] of savedEnv) {
       if (value === undefined) {
@@ -323,6 +363,58 @@ describe("renderLocal browser GPU config", () => {
     expect(process.env.PRODUCER_HEADLESS_SHELL_PATH).toBe("/mock/chrome");
   });
 
+  it("falls back to hardware encoding when FFmpeg omits libx264", async () => {
+    ffmpegEncoderState.mode = "gpu";
+
+    await renderLocal("/tmp/project", "/tmp/out.mp4", {
+      fps: { num: 30, den: 1 },
+      quality: "high",
+      format: "mp4",
+      gpu: false,
+      browserGpuMode: "software",
+      hdrMode: "force-sdr",
+      quiet: true,
+    });
+
+    expect(producerState.createdJobs[0]?.useGpu).toBe(true);
+  });
+
+  it("lets the encoder surface its own error when capability detection fails", async () => {
+    ffmpegEncoderState.error = new Error("encoder probe timed out");
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+
+    await renderLocal("/tmp/project", "/tmp/out.mp4", {
+      fps: { num: 30, den: 1 },
+      quality: "high",
+      format: "mp4",
+      gpu: false,
+      browserGpuMode: "software",
+      hdrMode: "force-sdr",
+      quiet: true,
+    });
+
+    expect(producerState.createdJobs[0]?.useGpu).toBe(false);
+    expect(warn).not.toHaveBeenCalledWith(expect.stringContaining("encoder probe timed out"));
+  });
+
+  it("diagnoses advisory encoder probe failures unless quiet", async () => {
+    ffmpegEncoderState.error = new Error("encoder probe timed out");
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+
+    await renderLocal("/tmp/project", "/tmp/out.mp4", {
+      fps: { num: 30, den: 1 },
+      quality: "high",
+      format: "mp4",
+      gpu: false,
+      browserGpuMode: "software",
+      hdrMode: "force-sdr",
+      quiet: false,
+    });
+
+    expect(producerState.createdJobs[0]?.useGpu).toBe(false);
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining("encoder probe timed out"));
+  });
+
   it("resolves browser GPU from CLI flags, Docker mode, and env fallback", () => {
     // Default (no flag, no env): auto — engine probes and chooses.
     expect(resolveBrowserGpuForCli(false, undefined, undefined)).toBe("auto");