fix(capture): hand libvips' worker pool back after the renders

`sharp.concurrency(1)` is process-global and was set once, for the whole life of
the process. The bound is right for the rasterize loop -- a native abort in
libvips cannot be caught, so the renders must not overlap -- but its scope was
every later sharp caller in the process, none of which asked for captioning, all
of them pinned to one thread from then on.

Now the host's value is read first and restored in a `finally` around the
rasterize loop, so a skipped SVG cannot cost the process its threads either. The
vision requests below are network work and gain nothing from a pinned pool.

The mock had to grow the getter half of sharp's API -- `concurrency()` with no
argument reports the current value -- since save-and-restore is untestable
without it. Verified as a real guard: dropping only the restore fails both new
cases.

Raised by Rames Jusso in review of #3561 and concurred by Magi.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: WaterrrForever

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

@@ -19,6 +19,10 @@ const { generateContentMock, clientOptions, sharpState } = vi.hoisted(() => ({
     inFlight: 0,
     maxInFlight: 0,
     concurrencyCalls: [] as number[],
+    // Stands in for the host core count sharp reports before anything touches it, so a failure
+    // to restore shows up as a wrong value rather than as a coincidental match with 1.
+    HOST_CONCURRENCY: 8,
+    concurrency: 8,
     renders: [] as string[],
   },
 }));
@@ -42,9 +46,15 @@ vi.mock("sharp", () => {
     return chain;
   };
   const sharp = Object.assign(pipeline, {
-    concurrency: (value: number) => {
-      sharpState.concurrencyCalls.push(value);
-      return value;
+    // Real `sharp.concurrency()` is a getter when called with no argument and a process-global
+    // setter otherwise. The mock has to be both, or code that saves and restores the host value
+    // cannot be tested at all.
+    concurrency: (value?: number) => {
+      if (typeof value === "number") {
+        sharpState.concurrencyCalls.push(value);
+        sharpState.concurrency = value;
+      }
+      return sharpState.concurrency;
     },
   });
   return { default: sharp };
@@ -623,6 +633,7 @@ describe("captionImagesWithGemini — SVG rasterization", () => {
     sharpState.inFlight = 0;
     sharpState.maxInFlight = 0;
     sharpState.concurrencyCalls.length = 0;
+    sharpState.concurrency = sharpState.HOST_CONCURRENCY;
     sharpState.renders.length = 0;
     clientOptions.length = 0;
   });
@@ -678,9 +689,11 @@ describe("captionImagesWithGemini — SVG rasterization", () => {
     expect(Object.keys(captions)).toHaveLength(6);
   });
 
-  it("bounds libvips' own worker pool as well", async () => {
+  it("bounds libvips' own worker pool for the renders, then hands it back", 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.
+    // loop alone still leaves one render fanning out across every core. But `sharp.concurrency`
+    // is process-global: leaving it at 1 pins every later sharp caller in this process, none of
+    // which asked for captioning, so the bound has to be given back when the renders are done.
     const dir = makeProjectWithSvgs(1);
     dirs.push(dir);
     vi.stubEnv("OPENROUTER_API_KEY", "or-key");
@@ -697,7 +710,33 @@ describe("captionImagesWithGemini — SVG rasterization", () => {
 
     await captionImagesWithGemini(dir, () => {}, []);
 
-    expect(sharpState.concurrencyCalls).toEqual([1]);
+    expect(sharpState.concurrencyCalls).toEqual([1, sharpState.HOST_CONCURRENCY]);
+    expect(sharpState.concurrency).toBe(sharpState.HOST_CONCURRENCY);
+  });
+
+  it("hands the worker pool back even when a rasterize throws", async () => {
+    // The restore is in a `finally`, because a skipped SVG must not cost the rest of the process
+    // its threads.
+    const dir = makeProjectWithSvgs(2);
+    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" },
+          }),
+      ),
+    );
+    // Unreadable, which is how an exotic SVG behaves through sharp.
+    rmSync(join(dir, "assets", "svgs", "logo-0.svg"));
+    mkdirSync(join(dir, "assets", "svgs", "logo-0.svg"));
+
+    await captionImagesWithGemini(dir, () => {}, []);
+
+    expect(sharpState.concurrency).toBe(sharpState.HOST_CONCURRENCY);
   });
 
   it("keeps captioning the rest when one SVG cannot be rasterized", async () => {

packages/cli/src/capture/contentExtractor.ts

@@ -509,10 +509,13 @@ export async function captionImagesWithGemini(
         reportOutcome();
         return geminiCaptions;
       }
-      // Bound libvips' worker pool. Left at its default it sizes itself to the host's core
-      // count, and several concurrent SVG renders then multiply that — the combination
-      // corrupted the heap in production (see the serialized rasterize loop below).
-      sharp.concurrency(1);
+      // libvips' worker pool sizes itself to the host's core count, and several concurrent SVG
+      // renders then multiply that — the combination corrupted the heap in production (see the
+      // serialized rasterize loop below). `sharp.concurrency` is process-global and outlives this
+      // function, so remember the host's value and bound the pool only around the renders that
+      // need it: captioning must not leave every later sharp caller in this process — none of
+      // which asked for captioning — pinned to a single thread for the rest of its life.
+      const hostConcurrency = sharp.concurrency();
       progress("design", `Rasterizing + captioning ${svgFiles.length} SVGs via vision API...`);
       const SVG_BATCH = 20;
       const SVG_RENDER_SIZE = 256; // px — enough resolution for Gemini to read wordmarks, small enough to keep payload sub-MB
@@ -534,38 +537,45 @@ export async function captionImagesWithGemini(
         // the concurrency has to go rather than be handled. Rasterizing is local and cheap;
         // the vision request is the slow leg and stays parallel, so throughput barely moves.
         const rasterized: { relPath: string; pngBase64: string | null }[] = [];
-        for (const { relPath } of batch) {
-          const filePath = join(assetsDir, relPath);
-          try {
-            // Flatten against a contrasting background — white-on-white SVGs render invisible to Vision.
-            const svgSource = readFileSync(filePath, "utf-8");
-            const lightFillHits = (
-              svgSource.match(/fill\s*=\s*["'](#fff(fff)?|white|#[ef][ef][ef]|#[ef]{6})["']/gi) ||
-              []
-            ).length;
-            const darkFillHits = (
-              svgSource.match(/fill\s*=\s*["'](#000(000)?|black|#[0-3]{6}|#[0-3]{3})["']/gi) || []
-            ).length;
-            const bg =
-              lightFillHits > darkFillHits
-                ? { r: 32, g: 32, b: 32 } // dark slate behind light glyphs
-                : { r: 255, g: 255, b: 255 }; // white behind dark glyphs (default)
-            const pngBuffer = await sharp(filePath)
-              .resize({
-                width: SVG_RENDER_SIZE,
-                height: SVG_RENDER_SIZE,
-                fit: "inside",
-                withoutEnlargement: false,
-              })
-              .flatten({ background: bg })
-              .png()
-              .toBuffer();
-            rasterized.push({ relPath, pngBase64: pngBuffer.toString("base64") });
-          } catch {
-            // exotic SVG features may break sharp; skip caption rather than block
-            svgsSkipped++;
-            rasterized.push({ relPath, pngBase64: null });
+        sharp.concurrency(1);
+        try {
+          for (const { relPath } of batch) {
+            const filePath = join(assetsDir, relPath);
+            try {
+              // Flatten against a contrasting background — white-on-white SVGs render invisible to Vision.
+              const svgSource = readFileSync(filePath, "utf-8");
+              const lightFillHits = (
+                svgSource.match(/fill\s*=\s*["'](#fff(fff)?|white|#[ef][ef][ef]|#[ef]{6})["']/gi) ||
+                []
+              ).length;
+              const darkFillHits = (
+                svgSource.match(/fill\s*=\s*["'](#000(000)?|black|#[0-3]{6}|#[0-3]{3})["']/gi) || []
+              ).length;
+              const bg =
+                lightFillHits > darkFillHits
+                  ? { r: 32, g: 32, b: 32 } // dark slate behind light glyphs
+                  : { r: 255, g: 255, b: 255 }; // white behind dark glyphs (default)
+              const pngBuffer = await sharp(filePath)
+                .resize({
+                  width: SVG_RENDER_SIZE,
+                  height: SVG_RENDER_SIZE,
+                  fit: "inside",
+                  withoutEnlargement: false,
+                })
+                .flatten({ background: bg })
+                .png()
+                .toBuffer();
+              rasterized.push({ relPath, pngBase64: pngBuffer.toString("base64") });
+            } catch {
+              // exotic SVG features may break sharp; skip caption rather than block
+              svgsSkipped++;
+              rasterized.push({ relPath, pngBase64: null });
+            }
           }
+        } finally {
+          // Hand the pool back even if a rasterize threw: the vision requests below are network
+          // work that gains nothing from a pinned pool, and the process outlives this capture.
+          sharp.concurrency(hostConcurrency);
         }
         const results = await Promise.allSettled(
           rasterized.map(async ({ relPath, pngBase64 }) => {