@hyperframes/engine 0.6.94 → 0.6.96

package/src/services/parallelCoordinator.ts

@@ -5,7 +5,7 @@
  * Auto-detects optimal worker count based on CPU/memory.
  */
 
-import { cpus, freemem, totalmem } from "os";
+import { cpus, freemem } from "os";
 import { existsSync, mkdirSync, readdirSync } from "fs";
 import { copyFile, rename } from "fs/promises";
 import { join } from "path";
@@ -26,6 +26,7 @@ import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
 import { assertSwiftShader } from "../utils/assertSwiftShader.js";
 import { readWebGlVendorInfoFromCanvas } from "../utils/readWebGlVendorInfoFromCanvas.js";
 import { resolveHeadlessShellPath } from "./browserManager.js";
+import { getSystemTotalMb } from "./systemMemory.js";
 
 export interface WorkerTask {
   workerId: number;
@@ -153,7 +154,7 @@ export function calculateOptimalWorkers(
   // Use total memory instead of free memory — macOS reports misleadingly low
   // freemem() because it aggressively caches files in "inactive" memory that
   // is immediately reclaimable.
-  const totalMemoryMB = Math.round(totalmem() / (1024 * 1024));
+  const totalMemoryMB = getSystemTotalMb();
   const memoryBasedWorkers = Math.max(1, Math.floor((totalMemoryMB * 0.5) / MEMORY_PER_WORKER_MB));
 
   const frameBasedWorkers = Math.floor(totalFrames / MIN_FRAMES_PER_WORKER);
@@ -429,7 +430,7 @@ export function getSystemResources(): {
 } {
   return {
     cpuCores: cpus().length,
-    totalMemoryMB: Math.round(totalmem() / (1024 * 1024)),
+    totalMemoryMB: getSystemTotalMb(),
     freeMemoryMB: Math.round(freemem() / (1024 * 1024)),
     recommendedWorkers: calculateOptimalWorkers(1000),
   };

package/src/services/streamingEncoder.test.ts

@@ -418,6 +418,20 @@ const baseOptions: StreamingEncoderOptions = {
   useGpu: false,
 };
 
+async function resolveWithin<T>(promise: Promise<T>, ms = 100): Promise<T | "timeout"> {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<"timeout">((resolve) => {
+        timeout = setTimeout(() => resolve("timeout"), ms);
+      }),
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
 describe("spawnStreamingEncoder lifecycle and cleanup", () => {
   afterEach(() => {
     vi.resetModules();
@@ -556,7 +570,7 @@ describe("spawnStreamingEncoder lifecycle and cleanup", () => {
     const dir = mkdtempSync(join(tmpdir(), "se-writefail-"));
     const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
 
-    expect(encoder.writeFrame(Buffer.from([0]))).toBe(true);
+    expect(await encoder.writeFrame(Buffer.from([0]))).toBe(true);
 
     const proc = calls[0]!.proc;
     await new Promise<void>((resolve) => {
@@ -566,7 +580,136 @@ describe("spawnStreamingEncoder lifecycle and cleanup", () => {
       });
     });
 
-    expect(encoder.writeFrame(Buffer.from([0]))).toBe(false);
+    expect(await encoder.writeFrame(Buffer.from([0]))).toBe(false);
+  });
+
+  it("writeFrame waits for stdin drain when FFmpeg applies back-pressure", async () => {
+    const { spawn, calls } = createSpawnSpy();
+    vi.resetModules();
+    vi.doMock("child_process", () => ({ spawn }));
+
+    const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
+    const dir = mkdtempSync(join(tmpdir(), "se-drain-"));
+    const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
+
+    const proc = calls[0]!.proc;
+    proc.stdin.write = (_chunk: Buffer): boolean => false;
+
+    const writeResult = encoder.writeFrame(Buffer.from([1])) as unknown;
+    expect(writeResult).toBeInstanceOf(Promise);
+
+    const writePromise = writeResult as Promise<boolean>;
+    let settled = false;
+    void writePromise.then(() => {
+      settled = true;
+    });
+
+    await Promise.resolve();
+    expect(settled).toBe(false);
+    expect(proc.stdin.listenerCount("drain")).toBe(1);
+
+    proc.stdin.emit("drain");
+
+    await expect(writePromise).resolves.toBe(true);
+    expect(settled).toBe(true);
+    expect(proc.stdin.listenerCount("drain")).toBe(0);
+
+    process.nextTick(() => proc.emit("close", 0));
+    await encoder.close();
+  });
+
+  it("does not accumulate process close listeners across repeated back-pressured writes", async () => {
+    const { spawn, calls } = createSpawnSpy();
+    vi.resetModules();
+    vi.doMock("child_process", () => ({ spawn }));
+
+    const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
+    const dir = mkdtempSync(join(tmpdir(), "se-drain-listeners-"));
+    const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
+
+    const proc = calls[0]!.proc;
+    const baselineCloseListeners = proc.listenerCount("close");
+    const baselineDrainListeners = proc.stdin.listenerCount("drain");
+    proc.stdin.write = (_chunk: Buffer): boolean => false;
+
+    for (let i = 0; i < 12; i++) {
+      const writePromise = encoder.writeFrame(Buffer.from([i]));
+
+      await Promise.resolve();
+      expect(proc.stdin.listenerCount("drain")).toBe(baselineDrainListeners + 1);
+      expect(proc.listenerCount("close")).toBe(baselineCloseListeners + 1);
+
+      proc.stdin.emit("drain");
+
+      await expect(writePromise).resolves.toBe(true);
+      expect(proc.stdin.listenerCount("drain")).toBe(baselineDrainListeners);
+      expect(proc.listenerCount("close")).toBe(baselineCloseListeners);
+    }
+
+    process.nextTick(() => proc.emit("close", 0));
+    await encoder.close();
+  });
+
+  it("writeFrame resolves false instead of hanging when FFmpeg exits before drain", async () => {
+    const { spawn, calls } = createSpawnSpy();
+    vi.resetModules();
+    vi.doMock("child_process", () => ({ spawn }));
+
+    const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
+    const dir = mkdtempSync(join(tmpdir(), "se-drain-exit-"));
+    const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
+
+    const proc = calls[0]!.proc;
+    proc.stdin.write = (_chunk: Buffer): boolean => false;
+
+    const writeResult = encoder.writeFrame(Buffer.from([1])) as unknown;
+    expect(writeResult).toBeInstanceOf(Promise);
+
+    const writePromise = writeResult as Promise<boolean>;
+    let settled = false;
+    void writePromise.then(() => {
+      settled = true;
+    });
+
+    await Promise.resolve();
+    expect(settled).toBe(false);
+    expect(proc.stdin.listenerCount("drain")).toBe(1);
+
+    proc.emit("close", 1);
+
+    await expect(writePromise).resolves.toBe(false);
+    expect(settled).toBe(true);
+    expect(proc.stdin.listenerCount("drain")).toBe(0);
+
+    const result = await encoder.close();
+    expect(result.success).toBe(false);
+  });
+
+  it("writeFrame resolves false when close fires after write returns false before await attaches listeners", async () => {
+    const { spawn, calls } = createSpawnSpy();
+    vi.resetModules();
+    vi.doMock("child_process", () => ({ spawn }));
+
+    const { spawnStreamingEncoder } = await import("./streamingEncoder.js");
+    const dir = mkdtempSync(join(tmpdir(), "se-drain-already-closed-"));
+    const encoder = await spawnStreamingEncoder(join(dir, "out.mp4"), baseOptions);
+
+    const proc = calls[0]!.proc;
+    const baselineCloseListeners = proc.listenerCount("close");
+    proc.stdin.write = (_chunk: Buffer): boolean => {
+      proc.emit("close", 1);
+      return false;
+    };
+
+    const writePromise = encoder.writeFrame(Buffer.from([1]));
+
+    await expect(resolveWithin(writePromise)).resolves.toBe(false);
+    expect(encoder.getExitStatus()).toBe("error");
+    expect(proc.stdin.listenerCount("drain")).toBe(0);
+    expect(proc.listenerCount("close")).toBe(baselineCloseListeners);
+
+    const result = await encoder.close();
+    expect(result.success).toBe(false);
   });
 
   it("close() removes the abort listener so a post-close abort does not re-kill ffmpeg", async () => {
@@ -613,7 +756,7 @@ describe("spawnStreamingEncoder lifecycle and cleanup", () => {
       // progressing" capture the encoder must still be alive. The old total-
       // render timeout would have fired SIGTERM at ~1000ms.
       for (let i = 0; i < 9; i++) {
-        encoder.writeFrame(Buffer.from([i]));
+        await encoder.writeFrame(Buffer.from([i]));
         vi.advanceTimersByTime(900);
       }
       expect(proc.kill).not.toHaveBeenCalled();
@@ -647,14 +790,17 @@ describe("spawnStreamingEncoder lifecycle and cleanup", () => {
       const proc = calls[0]!.proc;
       proc.stdin.write = (_chunk: Buffer) => false;
 
-      // Pump 9 frames at 900ms intervals — all returning false. The reset
-      // should NOT fire (every write was buffered, not accepted), so the
-      // 1000ms timer (last reset on spawn) elapses near the start.
-      for (let i = 0; i < 9; i++) {
-        encoder.writeFrame(Buffer.from([i]));
-        vi.advanceTimersByTime(900);
-      }
+      // A buffered write should remain pending and must NOT reset the timer.
+      // The 1000ms timer (last reset on spawn) therefore elapses while the
+      // caller is correctly back-pressured on the first frame.
+      const writePromise = encoder.writeFrame(Buffer.from([0]));
+      await Promise.resolve();
+
+      vi.advanceTimersByTime(1100);
       expect(proc.kill).toHaveBeenCalledWith("SIGTERM");
+
+      proc.emit("close", null);
+      await expect(writePromise).resolves.toBe(false);
     } finally {
       vi.useRealTimers();
     }

package/src/services/streamingEncoder.ts

@@ -10,10 +10,11 @@
  *   1. Frame reorder buffer – ensures out-of-order parallel workers feed
  *      frames to FFmpeg stdin in sequential order.
  *   2. Streaming FFmpeg encoder – spawns FFmpeg with `-f image2pipe` and
- *      exposes a `writeFrame(buffer)` + `close()` API.
+ *      exposes an async `writeFrame(buffer)` + `close()` API.
  */
 
 import { spawn, type ChildProcess } from "child_process";
+import { once } from "events";
 import { trackChildProcess } from "../utils/processTracker.js";
 import { existsSync, mkdirSync, statSync } from "fs";
 import { dirname } from "path";
@@ -126,7 +127,14 @@ export interface StreamingEncoderResult {
 }
 
 export interface StreamingEncoder {
-  writeFrame: (buffer: Buffer) => boolean;
+  /**
+   * Write one frame to FFmpeg stdin, awaiting `drain` when the pipe is full
+   * so back-pressure propagates to the caller. Resolves `false` when FFmpeg
+   * is already gone. Callers must serialize calls — one in-flight writeFrame
+   * per encoder (the frame reorder buffer provides this ordering); concurrent
+   * calls would interleave frame bytes on the pipe and race the drain wait.
+   */
+  writeFrame: (buffer: Buffer) => Promise<boolean>;
   close: () => Promise<StreamingEncoderResult>;
   getExitStatus: () => "running" | "success" | "error";
 }
@@ -448,9 +456,45 @@ export async function spawnStreamingEncoder(
   };
   resetTimer();
 
+  const waitForDrainOrExit = async (
+    stdin: NonNullable<ChildProcess["stdin"]>,
+  ): Promise<"drain" | "exit"> => {
+    // Back-pressure can hit once per frame. Do not race `exitPromise.then(...)`
+    // here: V8 retains `.then` reaction-list entries on an unsettled promise,
+    // so a one-hour 30fps render under steady back-pressure can accumulate
+    // ~108K closures + AbortControllers. Use one-shot listeners for this write
+    // instead, then abort them in finally. `close` is the event that flips
+    // `exitStatus`; re-check after listener attachment so a close emitted
+    // between `stdin.write(false)` and this await cannot hang forever.
+    const abortController = new AbortController();
+    try {
+      const drainPromise = once(stdin, "drain", { signal: abortController.signal }).then(
+        () => "drain" as const,
+      );
+      const closePromise = once(ffmpeg, "close", { signal: abortController.signal }).then(
+        () => "exit" as const,
+      );
+      const racePromise = Promise.race([drainPromise, closePromise]).catch((err: unknown) => {
+        if (err instanceof Error && err.name === "AbortError") {
+          return "exit" as const;
+        }
+        throw err;
+      });
+
+      if (exitStatus !== "running") {
+        return "exit";
+      }
+
+      return await racePromise;
+    } finally {
+      abortController.abort();
+    }
+  };
+
   const encoder: StreamingEncoder = {
-    writeFrame: (buffer: Buffer): boolean => {
-      if (exitStatus !== "running" || !ffmpeg.stdin || ffmpeg.stdin.destroyed) {
+    writeFrame: async (buffer: Buffer): Promise<boolean> => {
+      const stdin = ffmpeg.stdin;
+      if (exitStatus !== "running" || !stdin || stdin.destroyed) {
         return false;
       }
       // Copy the buffer before writing — Node streams hold a reference to the
@@ -459,18 +503,28 @@ export async function spawnStreamingEncoder(
       // so without this copy the pipe would read partially-overwritten data
       // and flicker.
       const copy = Buffer.from(buffer);
-      const accepted = ffmpeg.stdin.write(copy);
-      // Reset inactivity timer ONLY on `accepted === true`. `true` means the
-      // write went through to the kernel pipe without buffering in Node —
-      // proof FFmpeg is actually consuming. `false` means Node's writable
-      // stream had to buffer (FFmpeg hasn't drained the pipe yet); we deliberately
-      // don't reset on `false` so a hung FFmpeg with a still-producing Chrome
-      // can't keep us alive forever while Node's stdin buffer grows to OOM. In
-      // steady state with a slower-but-alive FFmpeg, writes alternate between
-      // true and false as the buffer drains and refills; the trues are enough
-      // to keep the heartbeat ticking.
-      if (accepted) resetTimer();
-      return accepted;
+      const accepted = stdin.write(copy);
+      // Reset inactivity timer immediately ONLY on `accepted === true`. `true`
+      // means the write went through to the kernel pipe without buffering in
+      // Node — proof FFmpeg is actually consuming. `false` means Node's writable
+      // stream had to buffer (FFmpeg hasn't drained the pipe yet); we await
+      // `drain` before letting callers produce the next frame, and only reset
+      // after drain proves consumption. We deliberately don't reset before
+      // drain so a hung FFmpeg with a still-producing Chrome can't keep us
+      // alive forever while Node's stdin buffer grows to OOM. If FFmpeg exits
+      // before draining, waitForDrainOrExit returns "exit", removes its
+      // one-shot listeners, and callers see `false` instead of hanging.
+      if (accepted) {
+        resetTimer();
+        return true;
+      }
+
+      const drainResult = await waitForDrainOrExit(stdin);
+      if (drainResult !== "drain" || exitStatus !== "running") {
+        return false;
+      }
+      resetTimer();
+      return true;
     },
 
     close: async (): Promise<StreamingEncoderResult> => {

package/src/services/systemMemory.test.ts

@@ -1,5 +1,95 @@
-import { describe, it, expect } from "vitest";
-import { isLowMemorySystem, LOW_MEMORY_TOTAL_MB_THRESHOLD } from "./systemMemory.js";
+import { afterEach, beforeEach, describe, it, expect, vi } from "vitest";
+import {
+  _resetCgroupLimitCacheForTests,
+  isLowMemorySystem,
+  LOW_MEMORY_TOTAL_MB_THRESHOLD,
+  parseCgroupLimitMb,
+} from "./systemMemory.js";
+
+const BYTES_PER_MIB = 1024 * 1024;
+const CGROUP_V2_MEMORY_MAX_PATH = "/sys/fs/cgroup/memory.max";
+const CGROUP_V1_MEMORY_LIMIT_PATH = "/sys/fs/cgroup/memory/memory.limit_in_bytes";
+
+type SystemMemoryModule = typeof import("./systemMemory.js");
+
+type MockSystemMemoryOptions = {
+  files?: Record<string, string>;
+  hostTotalMb?: number;
+  platform?: NodeJS.Platform;
+  readErrors?: Record<string, NodeJS.ErrnoException>;
+  onRead?: (path: string) => void;
+  throwOnFileRead?: boolean;
+};
+
+function stubPlatform(platform: NodeJS.Platform): () => void {
+  const descriptor = Object.getOwnPropertyDescriptor(process, "platform");
+  Object.defineProperty(process, "platform", { value: platform });
+
+  return () => {
+    if (descriptor) {
+      Object.defineProperty(process, "platform", descriptor);
+    }
+  };
+}
+
+async function withSystemMemoryMocks(
+  options: MockSystemMemoryOptions,
+  run: (systemMemory: SystemMemoryModule) => void | Promise<void>,
+): Promise<void> {
+  const {
+    files = {},
+    hostTotalMb = 32768,
+    platform = "linux",
+    readErrors = {},
+    onRead,
+    throwOnFileRead = false,
+  } = options;
+  const restorePlatform = stubPlatform(platform);
+
+  vi.resetModules();
+  vi.doMock("os", () => ({
+    totalmem: () => hostTotalMb * BYTES_PER_MIB,
+  }));
+  vi.doMock("fs", () => ({
+    readFileSync: (path: string) => {
+      onRead?.(path);
+
+      if (throwOnFileRead) {
+        throw new Error(`/sys read should not happen: ${path}`);
+      }
+
+      if (path in readErrors) {
+        throw readErrors[path];
+      }
+
+      if (path in files) {
+        return files[path];
+      }
+
+      throw Object.assign(new Error("missing cgroup file"), { code: "ENOENT" });
+    },
+  }));
+
+  try {
+    const systemMemory = await import("./systemMemory.js");
+    systemMemory._resetCgroupLimitCacheForTests();
+    await run(systemMemory);
+  } finally {
+    vi.doUnmock("fs");
+    vi.doUnmock("os");
+    vi.resetModules();
+    restorePlatform();
+  }
+}
+
+beforeEach(() => {
+  _resetCgroupLimitCacheForTests();
+});
+
+afterEach(() => {
+  _resetCgroupLimitCacheForTests();
+  vi.restoreAllMocks();
+});
 
 describe("isLowMemorySystem", () => {
   it("treats sub-threshold RAM as low-memory", () => {
@@ -20,4 +110,215 @@ describe("isLowMemorySystem", () => {
     expect(isLowMemorySystem(16384)).toBe(false);
     expect(isLowMemorySystem(65536)).toBe(false);
   });
+
+  it("treats a 4 GiB cgroup v2 limit on a 32 GiB host as low-memory", async () => {
+    await withSystemMemoryMocks(
+      {
+        files: {
+          [CGROUP_V2_MEMORY_MAX_PATH]: `${4096 * BYTES_PER_MIB}`,
+        },
+      },
+      ({ getSystemTotalMb, isLowMemorySystem }) => {
+        expect(getSystemTotalMb()).toBe(4096);
+        expect(isLowMemorySystem()).toBe(true);
+      },
+    );
+  });
+});
+
+describe("parseCgroupLimitMb", () => {
+  it("parses cgroup v2 numeric limits", () => {
+    expect(parseCgroupLimitMb(`${4096 * BYTES_PER_MIB}`, null)).toBe(4096);
+  });
+
+  it('ignores cgroup v2 "max" limits', () => {
+    expect(parseCgroupLimitMb("max", null)).toBeNull();
+  });
+
+  it("parses cgroup v1 numeric limits and ignores no-limit sentinels", () => {
+    expect(parseCgroupLimitMb(null, `${6144 * BYTES_PER_MIB}`)).toBe(6144);
+    expect(parseCgroupLimitMb(null, "9223372036854771712")).toBeNull();
+  });
+
+  it("ignores absent and malformed limits", () => {
+    expect(parseCgroupLimitMb(null, null)).toBeNull();
+
+    for (const content of ["", "garbage", "-1", "0"]) {
+      expect(parseCgroupLimitMb(content, null)).toBeNull();
+      expect(parseCgroupLimitMb(null, content)).toBeNull();
+    }
+  });
+
+  it("uses cgroup v2 when both v2 and v1 contents are present", () => {
+    expect(parseCgroupLimitMb(`${4096 * BYTES_PER_MIB}`, `${2048 * BYTES_PER_MIB}`)).toBe(4096);
+  });
+});
+
+describe("getSystemTotalMb", () => {
+  it("caches cgroup probes until the test reset hook clears the cache", async () => {
+    const readCalls: string[] = [];
+    const files = {
+      [CGROUP_V2_MEMORY_MAX_PATH]: `${4096 * BYTES_PER_MIB}`,
+    };
+
+    await withSystemMemoryMocks(
+      {
+        files,
+        onRead: (path) => readCalls.push(path),
+      },
+      ({ _resetCgroupLimitCacheForTests, getSystemTotalMb }) => {
+        expect(getSystemTotalMb()).toBe(4096);
+        expect(getSystemTotalMb()).toBe(4096);
+        expect(readCalls).toEqual([CGROUP_V2_MEMORY_MAX_PATH]);
+
+        files[CGROUP_V2_MEMORY_MAX_PATH] = `${2048 * BYTES_PER_MIB}`;
+        _resetCgroupLimitCacheForTests();
+
+        expect(getSystemTotalMb()).toBe(2048);
+        expect(readCalls).toEqual([CGROUP_V2_MEMORY_MAX_PATH, CGROUP_V2_MEMORY_MAX_PATH]);
+      },
+    );
+  });
+
+  it('uses the host total when cgroup v2 reports "max"', async () => {
+    await withSystemMemoryMocks(
+      {
+        files: {
+          [CGROUP_V2_MEMORY_MAX_PATH]: "max",
+        },
+      },
+      ({ getSystemTotalMb, isLowMemorySystem }) => {
+        expect(getSystemTotalMb()).toBe(32768);
+        expect(isLowMemorySystem()).toBe(false);
+      },
+    );
+  });
+
+  it("honors cgroup v1 numeric limits when cgroup v2 is absent", async () => {
+    await withSystemMemoryMocks(
+      {
+        files: {
+          [CGROUP_V1_MEMORY_LIMIT_PATH]: `${6144 * BYTES_PER_MIB}`,
+        },
+      },
+      ({ getSystemTotalMb, isLowMemorySystem }) => {
+        expect(getSystemTotalMb()).toBe(6144);
+        expect(isLowMemorySystem()).toBe(true);
+      },
+    );
+  });
+
+  it("uses the host total when cgroup v1 reports a no-limit sentinel", async () => {
+    await withSystemMemoryMocks(
+      {
+        files: {
+          [CGROUP_V1_MEMORY_LIMIT_PATH]: "9223372036854771712",
+        },
+      },
+      ({ getSystemTotalMb, isLowMemorySystem }) => {
+        expect(getSystemTotalMb()).toBe(32768);
+        expect(isLowMemorySystem()).toBe(false);
+      },
+    );
+  });
+
+  it("uses the host total when cgroup files are absent", async () => {
+    await withSystemMemoryMocks({}, ({ getSystemTotalMb, isLowMemorySystem }) => {
+      expect(getSystemTotalMb()).toBe(32768);
+      expect(isLowMemorySystem()).toBe(false);
+    });
+  });
+
+  it("warns once and uses the host total when a cgroup file is unreadable", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    await withSystemMemoryMocks(
+      {
+        readErrors: {
+          [CGROUP_V2_MEMORY_MAX_PATH]: Object.assign(new Error("permission denied"), {
+            code: "EACCES",
+          }),
+        },
+      },
+      ({ getSystemTotalMb, isLowMemorySystem }) => {
+        expect(getSystemTotalMb()).toBe(32768);
+        expect(getSystemTotalMb()).toBe(32768);
+        expect(isLowMemorySystem()).toBe(false);
+        expect(warn).toHaveBeenCalledTimes(1);
+        expect(warn.mock.calls[0]?.[0]).toContain(
+          "[SystemMemory] Unable to read cgroup memory limit",
+        );
+        expect(warn.mock.calls[0]?.[0]).toContain("EACCES");
+      },
+    );
+  });
+
+  it("stays silent when cgroup files are absent", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    await withSystemMemoryMocks({}, ({ getSystemTotalMb }) => {
+      expect(getSystemTotalMb()).toBe(32768);
+      expect(getSystemTotalMb()).toBe(32768);
+      expect(warn).not.toHaveBeenCalled();
+    });
+  });
+
+  it.each(["", "garbage", "-1", "0"])(
+    "uses the host total for malformed cgroup v2 content %j",
+    async (content) => {
+      await withSystemMemoryMocks(
+        {
+          files: {
+            [CGROUP_V2_MEMORY_MAX_PATH]: content,
+          },
+        },
+        ({ getSystemTotalMb, isLowMemorySystem }) => {
+          expect(getSystemTotalMb()).toBe(32768);
+          expect(isLowMemorySystem()).toBe(false);
+        },
+      );
+    },
+  );
+
+  it.each(["", "garbage", "-1", "0"])(
+    "uses the host total for malformed cgroup v1 content %j",
+    async (content) => {
+      await withSystemMemoryMocks(
+        {
+          files: {
+            [CGROUP_V1_MEMORY_LIMIT_PATH]: content,
+          },
+        },
+        ({ getSystemTotalMb, isLowMemorySystem }) => {
+          expect(getSystemTotalMb()).toBe(32768);
+          expect(isLowMemorySystem()).toBe(false);
+        },
+      );
+    },
+  );
+
+  it("uses the host total when a cgroup limit is larger than host RAM", async () => {
+    await withSystemMemoryMocks(
+      {
+        files: {
+          [CGROUP_V2_MEMORY_MAX_PATH]: `${65536 * BYTES_PER_MIB}`,
+        },
+      },
+      ({ getSystemTotalMb, isLowMemorySystem }) => {
+        expect(getSystemTotalMb()).toBe(32768);
+        expect(isLowMemorySystem()).toBe(false);
+      },
+    );
+  });
+
+  it("does not read cgroup files on non-Linux platforms", async () => {
+    await withSystemMemoryMocks(
+      {
+        platform: "darwin",
+        throwOnFileRead: true,
+      },
+      ({ getSystemTotalMb, isLowMemorySystem }) => {
+        expect(getSystemTotalMb()).toBe(32768);
+        expect(isLowMemorySystem()).toBe(false);
+      },
+    );
+  });
 });