fix(producer): respect real disk headroom — compressed-format estimate + single-worker streaming fallback - #4061

diff --git a/packages/producer/src/services/render/stages/captureStage.test.ts b/packages/producer/src/services/render/stages/captureStage.test.ts
index 46d6ee16b..ec57dbb79 100644
--- a/packages/producer/src/services/render/stages/captureStage.test.ts
+++ b/packages/producer/src/services/render/stages/captureStage.test.ts
@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { DEFAULT_CONFIG, classifyCaptureFailure } from "@hyperframes/engine";
 import { createRenderJob, isTransientCaptureRetryEligible } from "../../renderOrchestrator.js";
 import { formatCaptureFrameName } from "../../../utils/paths.js";
+import { resolveCaptureImageFormat } from "../captureImageFormat.js";
 
 // Mock only the engine session primitives; `classifyCaptureFailure` stays
 // real so the retry decision is exercised.
@@ -318,6 +319,32 @@ describe("runCaptureStage measured disk projection (both branches)", () => {
       /measured from the first 10 frames/,
     );
   });
+
+  it("uses the resolved png format for motion blur frames without alpha", async () => {
+    const { workDir, framesDir } = makeDirs();
+    const format = resolveCaptureImageFormat({ needsAlpha: false, motionBlur: {} });
+    expect(format).toBe("png");
+    freeBytes.mockReturnValue({ bavail: 100_000_000, bsize: 1 });
+    executeParallelCapture.mockImplementation(async () => {
+      for (let index = 0; index < 20; index++) {
+        writeFileSync(join(framesDir, formatCaptureFrameName(index, "png")), "captured-frame");
+      }
+      return [];
+    });
+
+    await expect(
+      runCaptureStage({
+        ...makeInput(2, workDir, framesDir),
+        plan: { workerCount: 2, forceScreenshot: false, needsAlpha: false },
+        buildCaptureOptions: () => ({
+          width: 64,
+          height: 64,
+          fps: { num: 30, den: 1 },
+          format,
+        }),
+      }),
+    ).resolves.toMatchObject({ workerCount: 2 });
+  });
 });
 
 describe("runCaptureStage — sequential path transient Target-closed single retry (integration)", () => {
diff --git a/packages/producer/src/services/renderOrchestrator.test.ts b/packages/producer/src/services/renderOrchestrator.test.ts
index 221f47b80..da0153a55 100644
--- a/packages/producer/src/services/renderOrchestrator.test.ts
+++ b/packages/producer/src/services/renderOrchestrator.test.ts
@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication complexity
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join, win32 } from "node:path";
@@ -55,6 +56,7 @@ import {
   resolveAdaptersUsed,
   resolveDeShortBand,
   shouldClampDefaultDrawElement,
+  shouldDegradeDiskCaptureToStreaming,
   shouldPreferParallelDrawElement,
   shouldPreferSingleWorkerDrawElement,
   isCaptureParallelStreamRouterEnabled,
@@ -723,6 +725,74 @@ describe("explainStreamingEncodeGate", () => {
   });
 });
 
+describe("shouldDegradeDiskCaptureToStreaming", () => {
+  it("degrades a multi-worker disk plan when disk lacks headroom and streaming is eligible", () => {
+    expect(
+      shouldDegradeDiskCaptureToStreaming({
+        planKind: "sdr_disk",
+        workerCount: 4,
+        diskHeadroomAvailable: false,
+        streamingEligible: true,
+      }),
+    ).toBe(true);
+  });
+
+  it("keeps the disk plan when headroom is sufficient", () => {
+    expect(
+      shouldDegradeDiskCaptureToStreaming({
+        planKind: "sdr_disk",
+        workerCount: 4,
+        diskHeadroomAvailable: true,
+        streamingEligible: true,
+      }),
+    ).toBe(false);
+  });
+
+  it("never degrades streaming or layered plans", () => {
+    expect(
+      shouldDegradeDiskCaptureToStreaming({
+        planKind: "sdr_streaming",
+        workerCount: 4,
+        diskHeadroomAvailable: false,
+        streamingEligible: true,
+      }),
+    ).toBe(false);
+    expect(
+      shouldDegradeDiskCaptureToStreaming({
+        planKind: "hdr_layered",
+        workerCount: 4,
+        diskHeadroomAvailable: false,
+        streamingEligible: true,
+      }),
+    ).toBe(false);
+  });
+
+  it("keeps the disk plan when streaming is ineligible for a single worker", () => {
+    // Covers png-sequence/gif outputs, renders past the streaming duration
+    // cap, and enableStreamingEncode=false — all surfaced via the eligibility
+    // flag computed by shouldUseStreamingEncode(cfg, format, 1, duration).
+    expect(
+      shouldDegradeDiskCaptureToStreaming({
+        planKind: "sdr_disk",
+        workerCount: 4,
+        diskHeadroomAvailable: false,
+        streamingEligible: false,
+      }),
+    ).toBe(false);
+  });
+
+  it("ignores single-worker disk plans", () => {
+    expect(
+      shouldDegradeDiskCaptureToStreaming({
+        planKind: "sdr_disk",
+        workerCount: 1,
+        diskHeadroomAvailable: false,
+        streamingEligible: true,
+      }),
+    ).toBe(false);
+  });
+});
+
 describe("createCompiledFrameSrcResolver", () => {
   it("maps extracted frame paths under compiledDir to encoded server URLs", () => {
     const resolver = createCompiledFrameSrcResolver("/tmp/hf job/compiled");
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index 388192d6a..4836aa50f 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -1547,6 +1547,33 @@ export function shouldUseStreamingEncode(
   ).enabled;
 }
 
+/**
+ * Whether a disk capture plan that failed the disk-headroom gate should
+ * degrade to single-worker streaming instead of failing the render.
+ *
+ * The disk gate estimates worst-case temporary frame storage and refuses
+ * captures whose estimate crosses 90% of free disk, while auto-parallel
+ * renders always land on the disk path (ordered streaming would stall later
+ * workers). A machine with modest free disk therefore failed renders that
+ * single-worker streaming could finish. Degradation is only offered when
+ * streaming is genuinely eligible for this render at one worker (same gates
+ * as the normal streaming decision: format, duration cap,
+ * enableStreamingEncode, low-memory mode).
+ */
+export function shouldDegradeDiskCaptureToStreaming(args: {
+  planKind: CapturePlan["kind"];
+  workerCount: number;
+  diskHeadroomAvailable: boolean;
+  streamingEligible: boolean;
+}): boolean {
+  return (
+    args.planKind === "sdr_disk" &&
+    args.workerCount > 1 &&
+    !args.diskHeadroomAvailable &&
+    args.streamingEligible
+  );
+}
+
 /**
  * Integer tuning knob from the environment. Matches the convention the
  * surrounding DE thresholds already use: unset OR set-but-empty falls back to
@@ -4287,6 +4314,34 @@ async function executeRenderPipeline(input: {
       needsAlpha,
       routing: captureRouting,
     });
+    // Disk-headroom degradation (see shouldDegradeDiskCaptureToStreaming):
+    // rebuild the plan as single-worker streaming BEFORE capture and
+    // telemetry read it, so the degraded plan is indistinguishable from one
+    // the streaming gate chose up front.
+    if (
+      shouldDegradeDiskCaptureToStreaming({
+        planKind: capturePlan.kind,
+        workerCount: capturePlan.workerCount,
+        diskHeadroomAvailable: inspectDiskCaptureHeadroom(
+          framesDir,
+          totalFrames,
+          buildCaptureOptions(),
+        ).available,
+        streamingEligible: shouldUseStreamingEncode(cfg, outputFormat, 1, job.duration),
+      })
+    ) {
+      log.info(
+        `[Render] Disk capture lacks headroom for ~${totalFrames} frames at ${framesDir}; ` +
+          `degrading ${capturePlan.workerCount}-worker disk capture to single-worker streaming encode.`,
+      );
+      capturePlan = createCapturePlan({
+        ...capturePlan,
+        workerCount: 1,
+        useStreamingEncode: true,
+        useLayeredComposite: false,
+        forceParallelStream: false,
+      });
+    }
     const syncCapturePlan = (): void => {
       // Every route the render can end up on passes through here, including the ones a
       // replan lands on, so this is where motion blur's one supported-route answer belongs.