Serialize cache size scans behind the coalescing window

The sizeChanged coalescer cleared its pending flag when the timer
fired, so a burst arriving while a scan was still running scheduled
another scan that overlapped the in-flight one on large caches. Track
the running scan, mark it stale when events arrive mid-scan, and run a
single follow-up scan after it settles so scans never overlap and the
trailing notification still delivers a fresh size.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016Q2tBCuePZJeeCkDDxu1m3

Author: jlobue10

packages/gui/src/electron/CacheManager.test.ts

@@ -145,6 +145,57 @@ describe('CacheManager eviction', () => {
     expect(mockDownloadFile).toHaveBeenCalledTimes(2);
   });
 
+  it('does not overlap cache size scans when a scan outlives the coalescing window', async () => {
+    jest.useFakeTimers();
+    try {
+      const cacheManager = new CacheManager({
+        cacheDirectory,
+        maxCacheSize: 1024,
+      });
+      await cacheManager.init();
+
+      let runningScans = 0;
+      let maxConcurrentScans = 0;
+      const scanResolvers: Array<() => void> = [];
+      const getCacheSizeSpy = jest.spyOn(cacheManager, 'getCacheSize').mockImplementation(
+        () =>
+          new Promise<number>((resolve) => {
+            runningScans += 1;
+            maxConcurrentScans = Math.max(maxConcurrentScans, runningScans);
+            scanResolvers.push(() => {
+              runningScans -= 1;
+              resolve(0);
+            });
+          }),
+      );
+
+      const send = jest.fn();
+      const fakeWindow = {
+        webContents: { send },
+        isDestroyed: () => false,
+        on: jest.fn(),
+      } as any;
+      cacheManager.bindEvents(fakeWindow);
+
+      cacheManager.emit('sizeChanged');
+      jest.advanceTimersByTime(500); // the first scan starts and stays in flight
+
+      cacheManager.emit('sizeChanged'); // burst arriving mid-scan
+      jest.advanceTimersByTime(500); // previously this started an overlapping scan
+
+      expect(maxConcurrentScans).toBe(1);
+
+      scanResolvers.shift()?.();
+      await Promise.resolve(); // let the first scan settle and reschedule
+      jest.advanceTimersByTime(500); // the follow-up scan delivers the fresh size
+
+      expect(getCacheSizeSpy).toHaveBeenCalledTimes(2);
+      expect(maxConcurrentScans).toBe(1);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
   it('treats a zero cache limit as unlimited when updating the setting', async () => {
     const payload = Buffer.from('cached payload');
     mockDownloadFile.mockImplementation(async (_url, localPath) => {

packages/gui/src/electron/CacheManager.ts

@@ -251,21 +251,38 @@ export default class CacheManager extends EventEmitter {
 
     // Download and invalidation bursts emit sizeChanged per file, and every
     // notification triggers a full cache-directory scan (here and again in the
-    // renderer), so coalesce bursts into one trailing notification.
+    // renderer), so coalesce bursts into one trailing notification. Scans are
+    // also serialized: events arriving while a scan is running only mark it
+    // stale, and one follow-up scan is scheduled after it finishes, so a scan
+    // that outlives the coalescing window cannot overlap the next one.
     let sizeChangedTimeout: NodeJS.Timeout | undefined;
+    let sizeScanRunning = false;
+    let sizeChangedDuringScan = false;
+
     const onSizeChanged = () => {
       if (sizeChangedTimeout) {
         return;
       }
+      if (sizeScanRunning) {
+        sizeChangedDuringScan = true;
+        return;
+      }
       sizeChangedTimeout = setTimeout(async () => {
         sizeChangedTimeout = undefined;
+        sizeScanRunning = true;
         try {
           const size = await this.getCacheSize();
           if (!window.isDestroyed()) {
             window.webContents.send(CacheAPI.ON_SIZE_CHANGED, size);
           }
         } catch {
           // the next sizeChanged event delivers a fresh value
+        } finally {
+          sizeScanRunning = false;
+          if (sizeChangedDuringScan) {
+            sizeChangedDuringScan = false;
+            onSizeChanged();
+          }
         }
       }, 500);
     };
@@ -278,6 +295,7 @@ export default class CacheManager extends EventEmitter {
       this.off('cacheDirectoryChanged', onCacheDirectoryChanged);
       this.off('maxCacheSizeChanged', onMaxCacheSizeChanged);
       this.off('sizeChanged', onSizeChanged);
+      sizeChangedDuringScan = false;
       if (sizeChangedTimeout) {
         clearTimeout(sizeChangedTimeout);
         sizeChangedTimeout = undefined;