test(capture): pin the rasterization loop to one render at a time

The serialization fix shipped without a regression test on the grounds that native
heap corruption is not unit-testable. The corruption is not, but the property that
prevents it is: `sharp` is mocked to record how many renders are in flight, and a
six-SVG batch must never reach two. A deliberately slow caption stub makes
overlapping renders the faster path, so a future refactor that "optimises" the loop
back to `Promise.all` fails here instead of aborting in production.

Also covered: `sharp.concurrency(1)` is applied — serializing the loop while leaving
libvips' pool at the host core count still fans one render across every core — and an
unrasterizable SVG is skipped without breaking serialization for its siblings.

Verified as a real guard: reverting only contentExtractor.ts to origin/main fails 7 of
the 22 cases in this file.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: WaterrrForever

packages/cli/src/capture/contentExtractor.test.ts

@@ -8,13 +8,48 @@ import {
   type VisionCaptionOutcome,
 } from "./contentExtractor.js";
 
-const { generateContentMock, clientOptions } = vi.hoisted(() => ({
+const { generateContentMock, clientOptions, sharpState } = vi.hoisted(() => ({
   generateContentMock: vi.fn(),
   // How the SDK client was constructed is the whole difference between the Vertex and API-key
   // paths, so the Vertex cases assert on it rather than on the request.
   clientOptions: [] as Record<string, unknown>[],
+  // A native abort inside libvips cannot be caught, so the only defence is never running two
+  // renders at once. That is a property of the loop, and this records it.
+  sharpState: {
+    inFlight: 0,
+    maxInFlight: 0,
+    concurrencyCalls: [] as number[],
+    renders: [] as string[],
+  },
 }));
 
+vi.mock("sharp", () => {
+  const pipeline = (filePath: string) => {
+    const chain = {
+      resize: () => chain,
+      flatten: () => chain,
+      png: () => chain,
+      toBuffer: async () => {
+        sharpState.inFlight += 1;
+        sharpState.maxInFlight = Math.max(sharpState.maxInFlight, sharpState.inFlight);
+        sharpState.renders.push(filePath);
+        // Yield, so an overlapping caller would be observed rather than serialized by luck.
+        await new Promise((resolve) => setTimeout(resolve, 5));
+        sharpState.inFlight -= 1;
+        return Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+      },
+    };
+    return chain;
+  };
+  const sharp = Object.assign(pipeline, {
+    concurrency: (value: number) => {
+      sharpState.concurrencyCalls.push(value);
+      return value;
+    },
+  });
+  return { default: sharp };
+});
+
 vi.mock("@google/genai", () => ({
   GoogleGenAI: class {
     models = { generateContent: generateContentMock };
@@ -574,3 +609,113 @@ describe("captionImagesWithGemini — Vertex AI provider", () => {
     expect(generateContentMock).not.toHaveBeenCalled();
   });
 });
+
+describe("captionImagesWithGemini — SVG rasterization", () => {
+  const dirs: string[] = [];
+
+  beforeEach(() => {
+    sharpState.inFlight = 0;
+    sharpState.maxInFlight = 0;
+    sharpState.concurrencyCalls.length = 0;
+    sharpState.renders.length = 0;
+    clientOptions.length = 0;
+  });
+
+  afterEach(() => {
+    generateContentMock.mockReset();
+    vi.unstubAllGlobals();
+    vi.unstubAllEnvs();
+    for (const d of dirs) rmSync(d, { recursive: true, force: true });
+    dirs.length = 0;
+  });
+
+  function makeProjectWithSvgs(count: number): string {
+    const dir = mkdtempSync(join(tmpdir(), "hf-svg-"));
+    mkdirSync(join(dir, "assets", "svgs"), { recursive: true });
+    for (let i = 0; i < count; i++) {
+      writeFileSync(
+        join(dir, "assets", "svgs", `logo-${i}.svg`),
+        '<svg xmlns="http://www.w3.org/2000/svg"><path fill="#000" d="M0 0h8v8H0z"/></svg>',
+      );
+    }
+    return dir;
+  }
+
+  it("never runs two libvips renders at once", async () => {
+    // Production aborted here with `free(): unaligned chunk detected in tcache 2` (SIGABRT),
+    // twice in fourteen days, losing the whole capture. A native abort cannot be caught by the
+    // surrounding try/catch, so the concurrency has to be absent rather than handled — which
+    // makes "one at a time" the assertion, not "errors are reported".
+    const dir = makeProjectWithSvgs(6);
+    dirs.push(dir);
+    vi.stubEnv("OPENROUTER_API_KEY", "or-key");
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        // Slower than a render, so overlapping renders would be the easy way to go faster —
+        // the point is that the loop does not take it.
+        await new Promise((resolve) => setTimeout(resolve, 15));
+        return new Response(
+          JSON.stringify({ choices: [{ message: { content: "A dark glyph." } }] }),
+          {
+            status: 200,
+            headers: { "content-type": "application/json" },
+          },
+        );
+      }),
+    );
+
+    const captions = await captionImagesWithGemini(dir, () => {}, []);
+
+    expect(sharpState.renders).toHaveLength(6);
+    expect(sharpState.maxInFlight).toBe(1);
+    expect(Object.keys(captions)).toHaveLength(6);
+  });
+
+  it("bounds libvips' own worker pool as well", async () => {
+    // Left at its default the pool sizes itself to the host's core count, so serializing the
+    // loop alone still leaves one render fanning out across every core.
+    const dir = makeProjectWithSvgs(1);
+    dirs.push(dir);
+    vi.stubEnv("OPENROUTER_API_KEY", "or-key");
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(
+        async () =>
+          new Response(JSON.stringify({ choices: [{ message: { content: "A glyph." } }] }), {
+            status: 200,
+            headers: { "content-type": "application/json" },
+          }),
+      ),
+    );
+
+    await captionImagesWithGemini(dir, () => {}, []);
+
+    expect(sharpState.concurrencyCalls).toEqual([1]);
+  });
+
+  it("keeps captioning the rest when one SVG cannot be rasterized", async () => {
+    const dir = makeProjectWithSvgs(3);
+    dirs.push(dir);
+    vi.stubEnv("OPENROUTER_API_KEY", "or-key");
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(
+        async () =>
+          new Response(JSON.stringify({ choices: [{ message: { content: "A glyph." } }] }), {
+            status: 200,
+            headers: { "content-type": "application/json" },
+          }),
+      ),
+    );
+    // One file is unreadable, which is how an exotic SVG behaves through sharp.
+    rmSync(join(dir, "assets", "svgs", "logo-1.svg"));
+    mkdirSync(join(dir, "assets", "svgs", "logo-1.svg"));
+
+    const warnings: string[] = [];
+    const captions = await captionImagesWithGemini(dir, () => {}, warnings);
+
+    expect(Object.keys(captions).sort()).toEqual(["svgs/logo-0.svg", "svgs/logo-2.svg"]);
+    expect(sharpState.maxInFlight).toBe(1);
+  });
+});