From 29017940ed75d2172427d688dbbb3bf86ee3b48e Mon Sep 17 00:00:00 2001
From: Jonathan LoBue <jlobue10@gmail.com>
Date: Tue, 21 Jul 2026 22:18:09 -0700
Subject: [PATCH 01/10] Fix NFT video/audio playback in the GUI

Video and audio NFTs frequently render as a blank tile while images work.
The media pipeline had several defects that disproportionately hit video:

- The cache: scheme was never registered with registerSchemesAsPrivileged,
  so media elements expected a buffered response and stalled on the
  streamed body served by protocol.handle. Register it with stream: true
  (plus standard/secure/supportFetchAPI) before app ready.
- The cache protocol handler ignored Range requests, returning 200 with
  the full file. Seeking was broken for all media and MP4 files without
  faststart (moov atom at the end) could fail to start playing at all.
  Serve 206 partial content from the cached file with accept-ranges.
- The 30s download timeout was a total-transfer budget, so any video that
  could not be fully downloaded in 30s never displayed. Make it an
  inactivity timeout that resets on each received chunk.
- Aborts caused by the 100MB size cap surfaced as generic
  "Request aborted"/"Response aborted" errors, which are treated as
  transient, so oversized files were re-downloaded on every gallery
  visit. Report a distinct "Maximum file size exceeded" error, persist
  it, and only retry when the caller lifts the size limit.
- maxSize <= 0 now disables the size limit instead of aborting every
  download on the first chunk, fixing the ignoreSizeLimit path
  (useNFTVerifyHash passes maxSize: -1) and NFTPreview now forwards the
  same override to getURI so verification and display stay consistent.
- Drive-by: download progress used Math.max instead of Math.min and was
  pinned at 100%.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../gui/src/components/nfts/NFTPreview.tsx    |  14 ++-
 packages/gui/src/electron/CacheManager.ts     | 111 +++++++++++++++---
 packages/gui/src/electron/main.tsx            |  19 ++-
 .../gui/src/electron/utils/downloadFile.ts    |  34 ++++--
 4 files changed, 153 insertions(+), 25 deletions(-)

diff --git a/packages/gui/src/components/nfts/NFTPreview.tsx b/packages/gui/src/components/nfts/NFTPreview.tsx
index ccb8b805c2..4d790d1391 100644
--- a/packages/gui/src/components/nfts/NFTPreview.tsx
+++ b/packages/gui/src/components/nfts/NFTPreview.tsx
@@ -210,7 +210,7 @@ export default function NFTPreview(props: NFTPreviewProps) {
           }
         `;
 
-        const cachedURI = await getURI(preview.uri);
+        const cachedURI = await getURI(preview.uri, { maxSize: ignoreSizeLimit ? -1 : undefined });
         if (!cachedURI || !cachedURI.startsWith('cache://')) {
           setPreviewContent(undefined, signal);
           return;
@@ -237,7 +237,17 @@ export default function NFTPreview(props: NFTPreviewProps) {
         setError(e as Error, signal);
       }
     },
-    [preview, fit, getURI, previewFileType, disableInteractions, isDarkMode, setPreviewContent, setError],
+    [
+      preview,
+      fit,
+      getURI,
+      ignoreSizeLimit,
+      previewFileType,
+      disableInteractions,
+      isDarkMode,
+      setPreviewContent,
+      setError,
+    ],
   );
 
   useEffect(() => {
diff --git a/packages/gui/src/electron/CacheManager.ts b/packages/gui/src/electron/CacheManager.ts
index 8b6e1315f1..4db24639b8 100644
--- a/packages/gui/src/electron/CacheManager.ts
+++ b/packages/gui/src/electron/CacheManager.ts
@@ -1,8 +1,10 @@
-import { BrowserWindow, net, dialog, type Protocol } from 'electron';
+import { BrowserWindow, dialog, type Protocol } from 'electron';
 import { EventEmitter } from 'events';
 import crypto from 'node:crypto';
+import { createReadStream } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { Readable } from 'node:stream';
 
 import debug from 'debug';
 import isURL from 'validator/lib/isURL';
@@ -14,7 +16,7 @@ import CacheState from '../constants/CacheState';
 import limit from '../util/limit';
 
 import CacheAPI from './constants/CacheAPI';
-import downloadFile from './utils/downloadFile';
+import downloadFile, { MAX_FILE_SIZE_EXCEEDED_ERROR } from './utils/downloadFile';
 import ensureDirectoryExists from './utils/ensureDirectoryExists';
 import getChecksum from './utils/getChecksum';
 import ipcMainHandle from './utils/ipcMainHandle';
@@ -24,7 +26,51 @@ import sanitizeNumber from './utils/sanitizeNumber';
 
 const log = debug('chia-gui:CacheManager');
 
-const CACHE_PROTOCOL = 'cache';
+export const CACHE_PROTOCOL = 'cache';
+
+// A single-range `bytes=start-end` Range header, parsed against the file size.
+// 'ignore' means the header is absent or uses a form we do not support
+// (e.g. multiple ranges), in which case the full file is served with a 200.
+type ParsedRange = { start: number; end: number } | 'invalid' | 'ignore';
+
+function parseRangeHeader(rangeHeader: string | null, fileSize: number): ParsedRange {
+  if (!rangeHeader) {
+    return 'ignore';
+  }
+
+  const match = /^bytes=(\d*)-(\d*)$/.exec(rangeHeader.trim());
+  if (!match) {
+    return 'ignore';
+  }
+
+  const [, startString, endString] = match;
+
+  if (startString === '' && endString === '') {
+    return 'invalid';
+  }
+
+  if (startString === '') {
+    // suffix range: the last N bytes of the file
+    const suffixLength = Number.parseInt(endString, 10);
+    if (suffixLength === 0 || fileSize === 0) {
+      return 'invalid';
+    }
+
+    return { start: Math.max(fileSize - suffixLength, 0), end: fileSize - 1 };
+  }
+
+  const start = Number.parseInt(startString, 10);
+  if (start >= fileSize) {
+    return 'invalid';
+  }
+
+  const end = endString === '' ? fileSize - 1 : Math.min(Number.parseInt(endString, 10), fileSize - 1);
+  if (start > end) {
+    return 'invalid';
+  }
+
+  return { start, end };
+}
 
 async function safeUnlink(filePath: string) {
   try {
@@ -112,8 +158,11 @@ export default class CacheManager extends EventEmitter {
         });
       }
 
-      const response = await net.fetch(`file://${filePath}`);
-      if (!response.ok) {
+      let fileSize: number;
+      try {
+        const stats = await fs.stat(filePath);
+        fileSize = stats.size;
+      } catch (error) {
         return new Response('Not found', {
           status: 404,
           headers: {
@@ -122,18 +171,45 @@ export default class CacheManager extends EventEmitter {
         });
       }
 
-      const { headers } = cacheInfo;
-      const updatedHeaders = new Headers(response.headers);
+      const contentTypeHeader = cacheInfo.headers?.['content-type'];
+      const contentType =
+        (Array.isArray(contentTypeHeader) ? contentTypeHeader[0] : contentTypeHeader) || 'application/octet-stream';
 
-      if (headers['content-type']) {
-        const contentType = Array.isArray(headers['content-type'])
-          ? headers['content-type'][0]
-          : headers['content-type'];
-        updatedHeaders.set('content-type', contentType);
+      const responseHeaders: Record<string, string> = {
+        'content-type': contentType,
+        'accept-ranges': 'bytes',
+      };
+
+      // Media elements seek by sending Range requests. Without 206 responses
+      // seeking is broken and MP4 files with the moov atom at the end of the
+      // file never start playing.
+      const range = parseRangeHeader(request.headers.get('range'), fileSize);
+
+      if (range === 'invalid') {
+        return new Response('Range Not Satisfiable', {
+          status: 416,
+          headers: {
+            'content-type': 'text/plain',
+            'content-range': `bytes */${fileSize}`,
+          },
+        });
+      }
+
+      if (range !== 'ignore') {
+        responseHeaders['content-length'] = String(range.end - range.start + 1);
+        responseHeaders['content-range'] = `bytes ${range.start}-${range.end}/${fileSize}`;
+
+        const partialStream = createReadStream(filePath, { start: range.start, end: range.end });
+        return new Response(Readable.toWeb(partialStream) as unknown as ReadableStream, {
+          status: 206,
+          headers: responseHeaders,
+        });
       }
 
-      return new Response(response.body, {
-        headers: updatedHeaders,
+      responseHeaders['content-length'] = String(fileSize);
+
+      return new Response(Readable.toWeb(createReadStream(filePath)) as unknown as ReadableStream, {
+        headers: responseHeaders,
       });
     });
   }
@@ -332,7 +408,12 @@ export default class CacheManager extends EventEmitter {
 
         if (cacheInfo.state === CacheState.ERROR) {
           log(`Url already downloaded with error: ${cacheInfo.error}`, url);
-          if (!['Response aborted', 'Request aborted'].includes(cacheInfo.error)) {
+
+          const isTransientError = ['Response aborted', 'Request aborted'].includes(cacheInfo.error);
+          // A persisted size-limit error is only retried when the caller lifts
+          // the limit, so oversized files are not re-downloaded on every visit.
+          const isSizeLimitLifted = cacheInfo.error === MAX_FILE_SIZE_EXCEEDED_ERROR && maxSize <= 0;
+          if (!isTransientError && !isSizeLimitLifted) {
             return cacheInfo;
           }
 
diff --git a/packages/gui/src/electron/main.tsx b/packages/gui/src/electron/main.tsx
index c028d74567..fcf045b7d7 100644
--- a/packages/gui/src/electron/main.tsx
+++ b/packages/gui/src/electron/main.tsx
@@ -10,6 +10,7 @@ import {
   Notification,
   type MenuItemConstructorOptions,
   nativeTheme,
+  protocol,
 } from 'electron';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -29,7 +30,7 @@ import { WcError, WcErrorCode, encodeWcErrorForIpc } from '../@types/WcError';
 import AppIcon from '../assets/img/chia64x64.png';
 import { i18n } from '../config/locales';
 
-import CacheManager from './CacheManager';
+import CacheManager, { CACHE_PROTOCOL } from './CacheManager';
 import { checkNFTOwnership } from './api/checkNFTOwnership';
 import { getKeyDetails } from './api/getKeyDetails';
 import { getNetworkInfo } from './api/getNetworkInfo';
@@ -94,6 +95,22 @@ type ConfirmDialogResult = {
 app.disableHardwareAcceleration();
 app.commandLine.appendSwitch('disable-http-cache');
 
+// The cache: scheme serves NFT media to <img>/<video>/<audio> tags. Media
+// elements expect protocols to buffer their responses unless the scheme is
+// registered with stream: true, so without this video and audio playback
+// stalls. Must be called before the app ready event.
+protocol.registerSchemesAsPrivileged([
+  {
+    scheme: CACHE_PROTOCOL,
+    privileges: {
+      standard: true,
+      secure: true,
+      supportFetchAPI: true,
+      stream: true,
+    },
+  },
+]);
+
 const appIcon = nativeImage.createFromPath(path.join(__dirname, AppIcon));
 
 const prefs = readPrefs();
diff --git a/packages/gui/src/electron/utils/downloadFile.ts b/packages/gui/src/electron/utils/downloadFile.ts
index cefe94f24a..6201a0031f 100644
--- a/packages/gui/src/electron/utils/downloadFile.ts
+++ b/packages/gui/src/electron/utils/downloadFile.ts
@@ -63,10 +63,12 @@ class WriteStreamPromise {
   }
 }
 
+export const MAX_FILE_SIZE_EXCEEDED_ERROR = 'Maximum file size exceeded';
+
 type DownloadFileOptions = {
   timeout?: number;
   signal?: AbortSignal;
-  maxSize?: number;
+  maxSize?: number; // values <= 0 disable the size limit
   onProgress?: (progress: number, size: number, downloadedSize: number) => void;
   overrideFile?: boolean;
 };
@@ -84,12 +86,27 @@ export default async function downloadFile(
   const request = net.request(url);
   const outputStream = new WriteStreamPromise(tempFilePath, overrideFile);
 
+  // set when we abort the request ourselves, so abort events can be reported
+  // with the real reason instead of a generic aborted error
+  let abortError: Error | undefined;
+
   function abortRequest() {
     request.abort();
   }
 
   let timeoutId: NodeJS.Timeout | null = null;
 
+  // the timeout is an inactivity timeout - it is reset every time data
+  // arrives, so slow hosts serving large files (videos) are not cut off mid
+  // transfer while a stalled connection still fails fast
+  function resetTimeout() {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+
+    timeoutId = setTimeout(abortRequest, timeout);
+  }
+
   return new Promise<Headers>((resolve, reject) => {
     let downloadedSize = 0;
 
@@ -161,7 +178,8 @@ export default async function downloadFile(
         const size = Number.parseInt(contentLength, 10);
         if (!Number.isNaN(size)) {
           fileSize = size;
-          if (size > maxSize) {
+          if (maxSize > 0 && size > maxSize) {
+            abortError = new Error(MAX_FILE_SIZE_EXCEEDED_ERROR);
             request.abort();
             return;
           }
@@ -170,8 +188,10 @@ export default async function downloadFile(
 
       response.on('data', (chunk) => {
         downloadedSize += chunk.byteLength;
+        resetTimeout();
 
-        if (downloadedSize > maxSize) {
+        if (maxSize > 0 && downloadedSize > maxSize) {
+          abortError = new Error(MAX_FILE_SIZE_EXCEEDED_ERROR);
           request.abort();
           return;
         }
@@ -182,7 +202,7 @@ export default async function downloadFile(
 
         // send progress event only when we know the file size
         if (onProgress && fileSize !== undefined && fileSize > 0) {
-          const progress = Math.max((downloadedSize / fileSize) * 100, 100);
+          const progress = Math.min((downloadedSize / fileSize) * 100, 100);
           onProgress(progress, fileSize, downloadedSize);
         }
       });
@@ -192,7 +212,7 @@ export default async function downloadFile(
       });
 
       response.on('aborted', () => {
-        resolvePromise(false, new Error('Response aborted'));
+        resolvePromise(false, abortError ?? new Error('Response aborted'));
       });
 
       response.on('end', () => {
@@ -201,7 +221,7 @@ export default async function downloadFile(
     });
 
     request.on('abort', () => {
-      resolvePromise(false, new Error('Request aborted'));
+      resolvePromise(false, abortError ?? new Error('Request aborted'));
     });
 
     request.on('error', (error = new Error('Unknown request error')) => {
@@ -212,7 +232,7 @@ export default async function downloadFile(
       signal.addEventListener('abort', abortRequest);
     }
 
-    timeoutId = setTimeout(abortRequest, timeout);
+    resetTimeout();
 
     request.end();
   });

From 3f4730287fc6aacf29ef73f3585695df3c654bf1 Mon Sep 17 00:00:00 2001
From: Jonathan LoBue <jlobue10@gmail.com>
Date: Wed, 22 Jul 2026 06:53:15 -0700
Subject: [PATCH 02/10] Persist NFT cache size and folder across GUI restarts

The settings UI stored the cache size limit under the cacheLimitSize
preference key, but on startup the main process reads maxCacheSize - a
key nothing ever wrote - so a user-configured cache size silently
reverted to the 1GB default on every launch. Changing the cache folder
was never persisted at all.

Persist both values from CacheProvider when the corresponding change
events arrive from the main process. The renderer is the only safe
place to write them: prefs.yaml is rewritten from the renderer's full
preferences snapshot on every save, so a value written by the main
process would be clobbered by the next renderer preference change.

On startup the legacy cacheLimitSize key is still honored so existing
users keep their configured limit, and non-positive stored values are
ignored instead of crashing the CacheManager constructor.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../src/components/cache/CacheProvider.tsx    | 33 +++++++++++++++++--
 .../components/settings/LimitCacheSize.tsx    |  5 ---
 packages/gui/src/electron/main.tsx            |  9 ++++-
 3 files changed, 38 insertions(+), 9 deletions(-)

diff --git a/packages/gui/src/components/cache/CacheProvider.tsx b/packages/gui/src/components/cache/CacheProvider.tsx
index a034235cc9..b3aa55805e 100644
--- a/packages/gui/src/components/cache/CacheProvider.tsx
+++ b/packages/gui/src/components/cache/CacheProvider.tsx
@@ -1,3 +1,4 @@
+import { usePrefs } from '@chia-network/api-react';
 import React, { useMemo, useState, useEffect, useCallback, type ReactNode } from 'react';
 
 const { cacheAPI } = window;
@@ -15,6 +16,14 @@ export default function CacheProvider(props: CacheProviderProps) {
   const [cacheDirectory, setCacheDirectory] = useState<string | undefined>(undefined);
   const [cacheSize, setCacheSize] = useState<number | undefined>(undefined);
 
+  // The main process only reads these preferences at startup; changes made at
+  // runtime live in CacheManager's memory, so they are persisted here in the
+  // renderer where all other preferences are written (prefs.yaml is rewritten
+  // from the renderer's snapshot on every preference save - a main process
+  // write would be clobbered by the next renderer save).
+  const [, setMaxCacheSizePref] = usePrefs<number | undefined>('maxCacheSize', undefined);
+  const [, setCacheFolderPref] = usePrefs<string | undefined>('cacheFolder', undefined);
+
   const updateCacheSize = useCallback(async () => {
     const size = await cacheAPI.getCacheSize();
     setCacheSize(size);
@@ -30,9 +39,21 @@ export default function CacheProvider(props: CacheProviderProps) {
     setMaxCacheSize(size);
   }, []);
 
+  const handleCacheDirectoryChanged = useCallback(async () => {
+    const directory = await cacheAPI.getCacheDirectory();
+    setCacheDirectory(directory);
+    setCacheFolderPref(directory);
+  }, [setCacheFolderPref]);
+
+  const handleMaxCacheSizeChanged = useCallback(async () => {
+    const size = await cacheAPI.getMaxCacheSize();
+    setMaxCacheSize(size);
+    setMaxCacheSizePref(size);
+  }, [setMaxCacheSizePref]);
+
   useEffect(() => {
-    const unbindCacheDirectoryChanged = cacheAPI.subscribeToDirectoryChange(updateCacheDirectory);
-    const unbindMaxCacheSizeChanged = cacheAPI.subscribeToMaxSizeChange(updateMaxCacheSize);
+    const unbindCacheDirectoryChanged = cacheAPI.subscribeToDirectoryChange(handleCacheDirectoryChanged);
+    const unbindMaxCacheSizeChanged = cacheAPI.subscribeToMaxSizeChange(handleMaxCacheSizeChanged);
     const unbindSizeChanged = cacheAPI.subscribeToSizeChange(updateCacheSize);
 
     updateCacheSize();
@@ -44,7 +65,13 @@ export default function CacheProvider(props: CacheProviderProps) {
       unbindMaxCacheSizeChanged();
       unbindSizeChanged();
     };
-  }, [updateCacheSize, updateCacheDirectory, updateMaxCacheSize]);
+  }, [
+    updateCacheSize,
+    updateCacheDirectory,
+    updateMaxCacheSize,
+    handleCacheDirectoryChanged,
+    handleMaxCacheSizeChanged,
+  ]);
 
   const context = useMemo(() => {
     const { getCacheDirectory, getCacheSize, getMaxCacheSize, ...rest } = cacheAPI;
diff --git a/packages/gui/src/components/settings/LimitCacheSize.tsx b/packages/gui/src/components/settings/LimitCacheSize.tsx
index a06d33d876..9746ca2e6b 100644
--- a/packages/gui/src/components/settings/LimitCacheSize.tsx
+++ b/packages/gui/src/components/settings/LimitCacheSize.tsx
@@ -1,4 +1,3 @@
-import { usePrefs } from '@chia-network/api-react';
 import { AlertDialog, ButtonLoading, Flex, Form, TextField, useOpenDialog } from '@chia-network/core';
 import { Trans } from '@lingui/macro';
 import React, { useEffect } from 'react';
@@ -16,8 +15,6 @@ export default function LimitCacheSize() {
   const openDialog = useOpenDialog();
   const { maxCacheSize, setMaxCacheSize } = useCache();
 
-  const [, setCacheLimitSize] = usePrefs(`cacheLimitSize`, 0);
-
   const methods = useForm<FormData>({
     defaultValues: {
       maxCacheSize,
@@ -45,8 +42,6 @@ export default function LimitCacheSize() {
 
     const newValue = Number(values.maxCacheSize) * MB_SIZE;
 
-    // todo move it ti electron/main
-    setCacheLimitSize(newValue);
     await setMaxCacheSize(newValue);
 
     await openDialog(
diff --git a/packages/gui/src/electron/main.tsx b/packages/gui/src/electron/main.tsx
index fcf045b7d7..6bed0dc35a 100644
--- a/packages/gui/src/electron/main.tsx
+++ b/packages/gui/src/electron/main.tsx
@@ -118,9 +118,16 @@ const prefs = readPrefs();
 const defaultCacheFolder = path.join(app.getPath('cache'), app.getName());
 const cacheDirectory: string = prefs.cacheFolder || defaultCacheFolder;
 
+// `cacheLimitSize` is the legacy preference key older versions of the
+// settings UI stored the value under. Invalid values are ignored because the
+// CacheManager constructor throws on non-positive sizes.
+const storedMaxCacheSize: number | undefined = [prefs.maxCacheSize, prefs.cacheLimitSize].find(
+  (size) => typeof size === 'number' && Number.isFinite(size) && size > 0,
+);
+
 const cacheManager = new CacheManager({
   cacheDirectory,
-  maxCacheSize: prefs.maxCacheSize,
+  maxCacheSize: storedMaxCacheSize,
 });
 
 // Hoisted so IPC handlers registered below can close over them; assigned in

From ae15b9b0dfb03cb06d23ea77137102fc66a9f4ab Mon Sep 17 00:00:00 2001
From: Jonathan LoBue <jlobue10@gmail.com>
Date: Thu, 30 Jul 2026 06:31:34 -0700
Subject: [PATCH 03/10] Bound NFT downloads with an absolute 30-minute deadline
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The inactivity-based download timeout left transfers with no upper
bound: a host trickling one byte per interval could hold a download
concurrency slot indefinitely. Downloads now also have an absolute
30-minute deadline, reported as the same transient abort error so
legitimate retries still work.

(Split from "Harden NFT preview interactions and download bounds" —
the gallery multi-select interaction fix is in the video/UX PR.)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T88GQEqcbujpAKLZy3sKoq
---
 packages/gui/src/electron/utils/downloadFile.ts | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/packages/gui/src/electron/utils/downloadFile.ts b/packages/gui/src/electron/utils/downloadFile.ts
index 6201a0031f..733f3021ac 100644
--- a/packages/gui/src/electron/utils/downloadFile.ts
+++ b/packages/gui/src/electron/utils/downloadFile.ts
@@ -67,6 +67,7 @@ export const MAX_FILE_SIZE_EXCEEDED_ERROR = 'Maximum file size exceeded';
 
 type DownloadFileOptions = {
   timeout?: number;
+  maxDuration?: number; // absolute cap on the whole transfer
   signal?: AbortSignal;
   maxSize?: number; // values <= 0 disable the size limit
   onProgress?: (progress: number, size: number, downloadedSize: number) => void;
@@ -76,7 +77,14 @@ type DownloadFileOptions = {
 export default async function downloadFile(
   url: string,
   localPath: string,
-  { timeout = 30_000, signal, maxSize = 100 * 1024 * 1024, onProgress, overrideFile = false }: DownloadFileOptions = {},
+  {
+    timeout = 30_000,
+    maxDuration = 30 * 60 * 1000,
+    signal,
+    maxSize = 100 * 1024 * 1024,
+    onProgress,
+    overrideFile = false,
+  }: DownloadFileOptions = {},
 ): Promise<Headers> {
   if (!isValidURL(url)) {
     throw new Error('Invalid URL');
@@ -107,6 +115,10 @@ export default async function downloadFile(
     timeoutId = setTimeout(abortRequest, timeout);
   }
 
+  // absolute deadline for the whole transfer — the inactivity timeout alone
+  // would let a host trickling bytes hold a download slot forever
+  const maxDurationTimeoutId = setTimeout(abortRequest, maxDuration);
+
   return new Promise<Headers>((resolve, reject) => {
     let downloadedSize = 0;
 
@@ -132,6 +144,8 @@ export default async function downloadFile(
           timeoutId = null;
         }
 
+        clearTimeout(maxDurationTimeoutId);
+
         await outputStream.close();
 
         // resolve promise

From 72abd94a1686a0e2efd09b40bed831e729d9869a Mon Sep 17 00:00:00 2001
From: Codex <codex@openai.com>
Date: Thu, 30 Jul 2026 06:32:00 -0700
Subject: [PATCH 04/10] fix: harden cache eviction accounting and size handling
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cache-eviction portion of a hardening pass over the NFT media branch:

- Eviction after a completed download now evicts down to the configured
  total-size target while preserving the file that was just downloaded,
  instead of removing an ad-hoc amount that could include it.
- Eviction accounting includes each entry's info sidecar so it matches
  getCacheSize().
- setCacheInfo is awaited, so the cache info returned to callers is the
  saved state rather than a pending promise.
- sanitizeNumber accepts 0 (meaning unlimited) and rejects negative or
  non-finite sizes; the stored preference is accepted when >= 0.

(Split from "fix: harden NFT previews and cache eviction" — the preview
verification portion is in the preview-hardening PR.)
---
 .../gui/src/electron/CacheManager.test.ts     | 82 +++++++++++++++++++
 packages/gui/src/electron/CacheManager.ts     | 50 ++++++-----
 packages/gui/src/electron/main.tsx            |  4 +-
 .../gui/src/electron/utils/sanitizeNumber.ts  | 12 +--
 4 files changed, 118 insertions(+), 30 deletions(-)
 create mode 100644 packages/gui/src/electron/CacheManager.test.ts

diff --git a/packages/gui/src/electron/CacheManager.test.ts b/packages/gui/src/electron/CacheManager.test.ts
new file mode 100644
index 0000000000..57808618c8
--- /dev/null
+++ b/packages/gui/src/electron/CacheManager.test.ts
@@ -0,0 +1,82 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+type DownloadFile = typeof import('./utils/downloadFile').default;
+
+const mockDownloadFile = jest.fn<ReturnType<DownloadFile>, Parameters<DownloadFile>>();
+
+jest.mock('electron', () => ({
+  BrowserWindow: jest.fn(),
+  dialog: {
+    showOpenDialog: jest.fn(),
+  },
+}));
+
+jest.mock('./utils/downloadFile', () => ({
+  __esModule: true,
+  default: mockDownloadFile,
+  MAX_FILE_SIZE_EXCEEDED_ERROR: 'Maximum file size exceeded',
+}));
+
+jest.mock('./utils/ipcMainHandle', () => ({
+  __esModule: true,
+  default: jest.fn(),
+}));
+
+const CacheManager = jest.requireActual<typeof import('./CacheManager')>('./CacheManager').default;
+
+describe('CacheManager eviction', () => {
+  let cacheDirectory: string;
+
+  beforeEach(async () => {
+    mockDownloadFile.mockReset();
+    cacheDirectory = await fs.mkdtemp(path.join(os.tmpdir(), 'chia-cache-manager-'));
+  });
+
+  afterEach(async () => {
+    await fs.rm(cacheDirectory, { recursive: true, force: true });
+  });
+
+  it('does not evict a just-downloaded file that fits within the configured total size', async () => {
+    const payload = Buffer.alloc(600, 7);
+    mockDownloadFile.mockImplementation(async (_url, localPath) => {
+      await fs.writeFile(localPath, payload);
+      return {
+        'content-type': 'image/png',
+      };
+    });
+
+    const cacheManager = new CacheManager({
+      cacheDirectory,
+      maxCacheSize: 1024,
+    });
+    await cacheManager.init();
+
+    await expect(cacheManager.getContent('https://example.com/nft.png')).resolves.toEqual(payload);
+    await expect(cacheManager.getCacheSize()).resolves.toBeLessThanOrEqual(1024);
+  });
+
+  it('treats a zero cache limit as unlimited when updating the setting', async () => {
+    const payload = Buffer.from('cached payload');
+    mockDownloadFile.mockImplementation(async (_url, localPath) => {
+      await fs.writeFile(localPath, payload);
+      return {
+        'content-type': 'image/png',
+      };
+    });
+
+    const cacheManager = new CacheManager({
+      cacheDirectory,
+      maxCacheSize: 1024,
+    });
+    await cacheManager.init();
+    await cacheManager.getContent('https://example.com/nft.png');
+
+    await cacheManager.setMaxCacheSize(0);
+
+    expect(cacheManager.maxCacheSize).toBe(0);
+    await expect(cacheManager.getContent('https://example.com/nft.png')).resolves.toEqual(payload);
+    expect(mockDownloadFile).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/gui/src/electron/CacheManager.ts b/packages/gui/src/electron/CacheManager.ts
index 4db24639b8..f5284fdd4a 100644
--- a/packages/gui/src/electron/CacheManager.ts
+++ b/packages/gui/src/electron/CacheManager.ts
@@ -277,9 +277,6 @@ export default class CacheManager extends EventEmitter {
 
   public set maxCacheSize(newSize: number | string) {
     const value = sanitizeNumber(newSize);
-    if (value < 0) {
-      throw new Error('Cache size cannot be negative');
-    }
 
     this.#maxCacheSize = value;
 
@@ -439,7 +436,7 @@ export default class CacheManager extends EventEmitter {
           log('Checksum computed', url);
 
           // save headers to a local JSON file
-          const updatedCacheInfo = this.setCacheInfo(url, {
+          const updatedCacheInfo = await this.setCacheInfo(url, {
             state: CacheState.CACHED,
             headers,
             checksum,
@@ -448,10 +445,11 @@ export default class CacheManager extends EventEmitter {
           log('Cache info saved', url);
           // remove old files if the cache is full
           const currentCacheSize = await this.getCacheSize();
-          const stats = await fs.stat(cacheFilePath);
-          if (this.maxCacheSize && currentCacheSize + stats.size > this.maxCacheSize) {
-            const spaceNeeded = currentCacheSize + stats.size - this.maxCacheSize;
-            await this.removeOldestFiles(spaceNeeded);
+          if (this.maxCacheSize > 0 && currentCacheSize > this.maxCacheSize) {
+            // The current size already includes the file that was just
+            // downloaded. Keep that file available to the caller and evict
+            // older entries down to the configured total-size target.
+            await this.removeOldestFiles(this.maxCacheSize, cacheFilePath);
           }
           // todo just add size and save it locally
           this.emit('sizeChanged');
@@ -655,19 +653,27 @@ export default class CacheManager extends EventEmitter {
     this.cacheDirectory = newDirectory;
   }
 
-  private async removeOldestFiles(targetSize: number): Promise<void> {
+  private async removeOldestFiles(targetSize: number, preserveFilePath?: string): Promise<void> {
     const files = await fs.readdir(this.cacheDirectory);
     const filePaths = files
       .filter((file) => isChiaCacheFile(file) && !isChiaCacheInfoFile(file))
       .map((file) => path.join(this.cacheDirectory, file));
 
-    // get the file sizes
+    // Include the sidecar metadata in each entry's size so the eviction total
+    // uses the same accounting as getCacheSize().
     const fileStats = await Promise.all(
       filePaths.map(async (filePath) => {
         const stats = await fs.stat(filePath);
+        let infoSize = 0;
+        try {
+          infoSize = (await fs.stat(getInfoFilePath(filePath))).size;
+        } catch {
+          // A missing sidecar is cleaned up with the data file as usual.
+        }
+
         return {
           filePath,
-          size: stats.size,
+          size: stats.size + infoSize,
           mtime: stats.mtime,
         };
       }),
@@ -678,13 +684,17 @@ export default class CacheManager extends EventEmitter {
 
     // remove files until the total size is below the new max total size
     let totalSize = fileStats.reduce((sum, { size }) => sum + size, 0);
-    const filesToRemove = fileStats.filter(({ size }) => {
-      if (totalSize > targetSize) {
-        totalSize -= size;
-        return true;
+    const filesToRemove: typeof fileStats = [];
+    for (const fileStat of fileStats) {
+      if (totalSize <= targetSize) {
+        break;
       }
-      return false;
-    });
+
+      if (fileStat.filePath !== preserveFilePath) {
+        totalSize -= fileStat.size;
+        filesToRemove.push(fileStat);
+      }
+    }
 
     await Promise.all(
       filesToRemove.map(async ({ filePath }) => {
@@ -717,8 +727,10 @@ export default class CacheManager extends EventEmitter {
   }
 
   async setMaxCacheSize(maxCacheSize: number | string) {
-    this.maxCacheSize = sanitizeNumber(maxCacheSize);
-    await this.removeOldestFiles(this.maxCacheSize);
+    this.maxCacheSize = maxCacheSize;
+    if (this.maxCacheSize > 0) {
+      await this.removeOldestFiles(this.maxCacheSize);
+    }
   }
 
   async getCacheSize() {
diff --git a/packages/gui/src/electron/main.tsx b/packages/gui/src/electron/main.tsx
index 6bed0dc35a..0a2f0b6a86 100644
--- a/packages/gui/src/electron/main.tsx
+++ b/packages/gui/src/electron/main.tsx
@@ -120,9 +120,9 @@ const cacheDirectory: string = prefs.cacheFolder || defaultCacheFolder;
 
 // `cacheLimitSize` is the legacy preference key older versions of the
 // settings UI stored the value under. Invalid values are ignored because the
-// CacheManager constructor throws on non-positive sizes.
+// CacheManager constructor rejects negative sizes; zero means unlimited.
 const storedMaxCacheSize: number | undefined = [prefs.maxCacheSize, prefs.cacheLimitSize].find(
-  (size) => typeof size === 'number' && Number.isFinite(size) && size > 0,
+  (size) => typeof size === 'number' && Number.isFinite(size) && size >= 0,
 );
 
 const cacheManager = new CacheManager({
diff --git a/packages/gui/src/electron/utils/sanitizeNumber.ts b/packages/gui/src/electron/utils/sanitizeNumber.ts
index 3aff0fbc55..f7642d67c1 100644
--- a/packages/gui/src/electron/utils/sanitizeNumber.ts
+++ b/packages/gui/src/electron/utils/sanitizeNumber.ts
@@ -1,14 +1,8 @@
 export default function sanitizeNumber(input: number | string): number {
-  let size: number;
+  const size = typeof input === 'string' ? Number(input) : input;
 
-  if (typeof input === 'string') {
-    size = parseInt(input, 10);
-  } else {
-    size = input;
-  }
-
-  if (Number.isNaN(size) || size <= 0) {
-    throw new Error('Invalid maxTotalSize value. It must be a positive number.');
+  if ((typeof input === 'string' && input.trim() === '') || !Number.isFinite(size) || size < 0) {
+    throw new Error('Invalid maxTotalSize value. It must be a non-negative finite number.');
   }
 
   return size;

From a67357603028e7a171b00e790649b38824e717f6 Mon Sep 17 00:00:00 2001
From: Jonathan LoBue <jlobue10@gmail.com>
Date: Tue, 28 Jul 2026 19:48:26 -0700
Subject: [PATCH 05/10] Stop cache races from poisoning downloads and flooding
 the renderer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

NFT invalidations (driven by nft_coin_added events while the wallet
syncs) delete cache files concurrently with downloads. The cache-size
scan that runs after every download stats each file with no tolerance
for concurrent deletion, so one vanished file rejected the whole scan —
and the download's catch block then overwrote its just-saved CACHED
state with the unrelated ENOENT error. The gallery re-downloaded those
"failed" files, triggering more invalidations and gateway rate limiting
(HTTP 429/504) until the GUI became unusable.

Vanished files are now skipped by both the size and eviction scans,
post-download housekeeping failures are logged instead of replacing the
completed download's state, and per-file sizeChanged bursts coalesce
into one trailing renderer notification instead of a full directory
scan each.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T88GQEqcbujpAKLZy3sKoq
---
 .../gui/src/electron/CacheManager.test.ts     | 54 ++++++++++
 packages/gui/src/electron/CacheManager.ts     | 99 +++++++++++++------
 2 files changed, 125 insertions(+), 28 deletions(-)

diff --git a/packages/gui/src/electron/CacheManager.test.ts b/packages/gui/src/electron/CacheManager.test.ts
index 57808618c8..c475b660dc 100644
--- a/packages/gui/src/electron/CacheManager.test.ts
+++ b/packages/gui/src/electron/CacheManager.test.ts
@@ -57,6 +57,60 @@ describe('CacheManager eviction', () => {
     await expect(cacheManager.getCacheSize()).resolves.toBeLessThanOrEqual(1024);
   });
 
+  it('keeps a completed download cached when cache housekeeping fails', async () => {
+    const payload = Buffer.from('cached payload');
+    mockDownloadFile.mockImplementation(async (_url, localPath) => {
+      await fs.writeFile(localPath, payload);
+      return {
+        'content-type': 'image/png',
+      };
+    });
+
+    const cacheManager = new CacheManager({
+      cacheDirectory,
+      maxCacheSize: 1024,
+    });
+    await cacheManager.init();
+
+    // A concurrent invalidation can delete files mid-scan and make the
+    // post-download size check fail — that must not poison the download.
+    jest
+      .spyOn(cacheManager, 'getCacheSize')
+      .mockRejectedValueOnce(new Error("ENOENT: no such file or directory, stat '/cache/other-chiacache'"));
+
+    await expect(cacheManager.getContent('https://example.com/nft.png')).resolves.toEqual(payload);
+    await expect(cacheManager.getContent('https://example.com/nft.png')).resolves.toEqual(payload);
+    expect(mockDownloadFile).toHaveBeenCalledTimes(1);
+  });
+
+  it('ignores files that vanish while the cache size is being measured', async () => {
+    const cacheManager = new CacheManager({
+      cacheDirectory,
+      maxCacheSize: 1024,
+    });
+    await cacheManager.init();
+
+    await fs.writeFile(path.join(cacheDirectory, 'aaaa-chiacache'), Buffer.alloc(100));
+    // a broken symlink stats like a file deleted between readdir and stat
+    await fs.symlink(path.join(cacheDirectory, 'missing-target'), path.join(cacheDirectory, 'bbbb-chiacache'));
+
+    await expect(cacheManager.getCacheSize()).resolves.toBe(100);
+  });
+
+  it('evicts without failing when a file vanishes during the eviction scan', async () => {
+    const cacheManager = new CacheManager({
+      cacheDirectory,
+      maxCacheSize: 1024,
+    });
+    await cacheManager.init();
+
+    await fs.writeFile(path.join(cacheDirectory, 'aaaa-chiacache'), Buffer.alloc(200));
+    await fs.symlink(path.join(cacheDirectory, 'missing-target'), path.join(cacheDirectory, 'bbbb-chiacache'));
+
+    await expect(cacheManager.setMaxCacheSize(100)).resolves.toBeUndefined();
+    await expect(fs.stat(path.join(cacheDirectory, 'aaaa-chiacache'))).rejects.toThrow('ENOENT');
+  });
+
   it('treats a zero cache limit as unlimited when updating the setting', async () => {
     const payload = Buffer.from('cached payload');
     mockDownloadFile.mockImplementation(async (_url, localPath) => {
diff --git a/packages/gui/src/electron/CacheManager.ts b/packages/gui/src/electron/CacheManager.ts
index f5284fdd4a..33281dc014 100644
--- a/packages/gui/src/electron/CacheManager.ts
+++ b/packages/gui/src/electron/CacheManager.ts
@@ -246,8 +246,25 @@ export default class CacheManager extends EventEmitter {
       window.webContents.send(CacheAPI.ON_MAX_CACHE_SIZE_CHANGED, newSize);
     }
 
-    const onSizeChanged = async () => {
-      window.webContents.send(CacheAPI.ON_SIZE_CHANGED, await this.getCacheSize());
+    // 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.
+    let sizeChangedTimeout: NodeJS.Timeout | undefined;
+    const onSizeChanged = () => {
+      if (sizeChangedTimeout) {
+        return;
+      }
+      sizeChangedTimeout = setTimeout(async () => {
+        sizeChangedTimeout = undefined;
+        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
+        }
+      }, 500);
     };
 
     this.on('cacheDirectoryChanged', onCacheDirectoryChanged);
@@ -258,6 +275,10 @@ export default class CacheManager extends EventEmitter {
       this.off('cacheDirectoryChanged', onCacheDirectoryChanged);
       this.off('maxCacheSizeChanged', onMaxCacheSizeChanged);
       this.off('sizeChanged', onSizeChanged);
+      if (sizeChangedTimeout) {
+        clearTimeout(sizeChangedTimeout);
+        sizeChangedTimeout = undefined;
+      }
     };
 
     window.on('close', () => {
@@ -443,13 +464,19 @@ export default class CacheManager extends EventEmitter {
           });
 
           log('Cache info saved', url);
-          // remove old files if the cache is full
-          const currentCacheSize = await this.getCacheSize();
-          if (this.maxCacheSize > 0 && currentCacheSize > this.maxCacheSize) {
-            // The current size already includes the file that was just
-            // downloaded. Keep that file available to the caller and evict
-            // older entries down to the configured total-size target.
-            await this.removeOldestFiles(this.maxCacheSize, cacheFilePath);
+          try {
+            // remove old files if the cache is full
+            const currentCacheSize = await this.getCacheSize();
+            if (this.maxCacheSize > 0 && currentCacheSize > this.maxCacheSize) {
+              // The current size already includes the file that was just
+              // downloaded. Keep that file available to the caller and evict
+              // older entries down to the configured total-size target.
+              await this.removeOldestFiles(this.maxCacheSize, cacheFilePath);
+            }
+          } catch (housekeepingError) {
+            // The download and its cache info are already saved — a failure in
+            // cache bookkeeping must not overwrite that state with an error.
+            log(`Cache housekeeping failed: ${(housekeepingError as Error).message}`, url);
           }
           // todo just add size and save it locally
           this.emit('sizeChanged');
@@ -661,23 +688,30 @@ export default class CacheManager extends EventEmitter {
 
     // Include the sidecar metadata in each entry's size so the eviction total
     // uses the same accounting as getCacheSize().
-    const fileStats = await Promise.all(
-      filePaths.map(async (filePath) => {
-        const stats = await fs.stat(filePath);
-        let infoSize = 0;
-        try {
-          infoSize = (await fs.stat(getInfoFilePath(filePath))).size;
-        } catch {
-          // A missing sidecar is cleaned up with the data file as usual.
-        }
-
-        return {
-          filePath,
-          size: stats.size + infoSize,
-          mtime: stats.mtime,
-        };
-      }),
-    );
+    const fileStats = (
+      await Promise.all(
+        filePaths.map(async (filePath) => {
+          try {
+            const stats = await fs.stat(filePath);
+            let infoSize = 0;
+            try {
+              infoSize = (await fs.stat(getInfoFilePath(filePath))).size;
+            } catch {
+              // A missing sidecar is cleaned up with the data file as usual.
+            }
+
+            return {
+              filePath,
+              size: stats.size + infoSize,
+              mtime: stats.mtime,
+            };
+          } catch {
+            // Deleted by invalidation while scanning — nothing left to evict.
+            return undefined;
+          }
+        }),
+      )
+    ).filter((entry): entry is { filePath: string; size: number; mtime: Date } => entry !== undefined);
 
     // sort the file paths based on their last modified time (oldest first)
     fileStats.sort((a, b) => a.mtime.getTime() - b.mtime.getTime());
@@ -739,8 +773,17 @@ export default class CacheManager extends EventEmitter {
       .filter((filename) => isChiaCacheFile(filename))
       .map((filename) => path.join(this.cacheDirectory, filename));
 
-    // Get the file sizes and calculate the total size
-    const fileSizes = await Promise.all(filePaths.map(async (filePath) => (await fs.stat(filePath)).size));
+    // Invalidation and eviction delete files while this scan runs — a file
+    // that vanished between readdir and stat no longer occupies space.
+    const fileSizes = await Promise.all(
+      filePaths.map(async (filePath) => {
+        try {
+          return (await fs.stat(filePath)).size;
+        } catch {
+          return 0;
+        }
+      }),
+    );
     const totalSize = fileSizes.reduce((sum, size) => sum + size, 0);
 
     return totalSize;

From f82ca861550139641511c31b46d0b672e3b31089 Mon Sep 17 00:00:00 2001
From: Jonathan LoBue <jlobue10@gmail.com>
Date: Thu, 30 Jul 2026 06:32:45 -0700
Subject: [PATCH 06/10] Settle timed-out downloads instead of retrying them
 forever
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Download timeouts (inactivity and the absolute deadline) aborted the
request without recording a reason, so they persisted as the generic
"Request aborted" — which the cache treats as transient and retries on
every access. Dead hosts therefore stalled every gallery pass for the
full timeout, forever. Timeouts now settle as failed downloads with
their own message; genuine caller-driven aborts remain retryable.

(Split from "Unblock NFT verification from slow metadata and settle
timed-out downloads" — the verification-hook change is in the
preview-hardening PR.)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T88GQEqcbujpAKLZy3sKoq
---
 .../gui/src/electron/CacheManager.test.ts     | 34 +++++++++++++++++++
 .../gui/src/electron/utils/downloadFile.ts    | 18 ++++++++--
 2 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/packages/gui/src/electron/CacheManager.test.ts b/packages/gui/src/electron/CacheManager.test.ts
index c475b660dc..a68f4a8a70 100644
--- a/packages/gui/src/electron/CacheManager.test.ts
+++ b/packages/gui/src/electron/CacheManager.test.ts
@@ -111,6 +111,40 @@ describe('CacheManager eviction', () => {
     await expect(fs.stat(path.join(cacheDirectory, 'aaaa-chiacache'))).rejects.toThrow('ENOENT');
   });
 
+  it('does not retry a timed-out download on the next access', async () => {
+    mockDownloadFile.mockRejectedValue(new Error('Request timed out after 30000ms of inactivity'));
+
+    const cacheManager = new CacheManager({
+      cacheDirectory,
+      maxCacheSize: 1024,
+    });
+    await cacheManager.init();
+
+    await expect(cacheManager.getContent('https://example.com/nft.png')).rejects.toThrow('Request timed out');
+    await expect(cacheManager.getContent('https://example.com/nft.png')).rejects.toThrow('Request timed out');
+    expect(mockDownloadFile).toHaveBeenCalledTimes(1);
+  });
+
+  it('retries an aborted download on the next access', async () => {
+    const payload = Buffer.from('cached payload');
+    mockDownloadFile.mockRejectedValueOnce(new Error('Request aborted')).mockImplementation(async (_url, localPath) => {
+      await fs.writeFile(localPath, payload);
+      return {
+        'content-type': 'image/png',
+      };
+    });
+
+    const cacheManager = new CacheManager({
+      cacheDirectory,
+      maxCacheSize: 1024,
+    });
+    await cacheManager.init();
+
+    await expect(cacheManager.getContent('https://example.com/nft.png')).rejects.toThrow('Request aborted');
+    await expect(cacheManager.getContent('https://example.com/nft.png')).resolves.toEqual(payload);
+    expect(mockDownloadFile).toHaveBeenCalledTimes(2);
+  });
+
   it('treats a zero cache limit as unlimited when updating the setting', async () => {
     const payload = Buffer.from('cached payload');
     mockDownloadFile.mockImplementation(async (_url, localPath) => {
diff --git a/packages/gui/src/electron/utils/downloadFile.ts b/packages/gui/src/electron/utils/downloadFile.ts
index 733f3021ac..a6c2c974b4 100644
--- a/packages/gui/src/electron/utils/downloadFile.ts
+++ b/packages/gui/src/electron/utils/downloadFile.ts
@@ -102,6 +102,14 @@ export default async function downloadFile(
     request.abort();
   }
 
+  // Timeouts must not report the generic aborted error: the cache retries
+  // aborted downloads on every access, so a stalled host would be retried
+  // (and stall again) forever instead of settling as a failed download.
+  function abortWithError(error: Error) {
+    abortError = error;
+    request.abort();
+  }
+
   let timeoutId: NodeJS.Timeout | null = null;
 
   // the timeout is an inactivity timeout - it is reset every time data
@@ -112,12 +120,18 @@ export default async function downloadFile(
       clearTimeout(timeoutId);
     }
 
-    timeoutId = setTimeout(abortRequest, timeout);
+    timeoutId = setTimeout(
+      () => abortWithError(new Error(`Request timed out after ${timeout}ms of inactivity`)),
+      timeout,
+    );
   }
 
   // absolute deadline for the whole transfer — the inactivity timeout alone
   // would let a host trickling bytes hold a download slot forever
-  const maxDurationTimeoutId = setTimeout(abortRequest, maxDuration);
+  const maxDurationTimeoutId = setTimeout(
+    () => abortWithError(new Error(`Request exceeded the ${maxDuration}ms download deadline`)),
+    maxDuration,
+  );
 
   return new Promise<Headers>((resolve, reject) => {
     let downloadedSize = 0;

From 3bdeaaa128e40abb7abab07f2d876b7d395d73e3 Mon Sep 17 00:00:00 2001
From: Jonathan LoBue <jlobue10@gmail.com>
Date: Tue, 28 Jul 2026 20:30:41 -0700
Subject: [PATCH 07/10] Serve the newest cache downloads first so visible
 content is not starved
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The download queue was strictly FIFO, so anything the user opened while
a large backlog was queued — an offer preview, a detail page — waited
behind every earlier request. With a cold cache the gallery enqueues
thousands of downloads and dead hosts hold slots for the full timeout,
leaving on-demand previews stuck for many minutes.

The download limiter now runs the most recently requested task first
(per-URL deduplication makes ordering safe), so downloads for what the
user is currently viewing start on the next free slot. RPC paging users
of the limiter keep FIFO ordering.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T88GQEqcbujpAKLZy3sKoq
---
 packages/gui/src/electron/CacheManager.ts |  5 +-
 packages/gui/src/util/limit.test.ts       | 59 +++++++++++++++++++++++
 packages/gui/src/util/limit.ts            |  9 +++-
 3 files changed, 70 insertions(+), 3 deletions(-)
 create mode 100644 packages/gui/src/util/limit.test.ts

diff --git a/packages/gui/src/electron/CacheManager.ts b/packages/gui/src/electron/CacheManager.ts
index 33281dc014..c3d91c7b58 100644
--- a/packages/gui/src/electron/CacheManager.ts
+++ b/packages/gui/src/electron/CacheManager.ts
@@ -127,7 +127,10 @@ export default class CacheManager extends EventEmitter {
 
     this.cacheDirectory = cacheDirectory;
     this.maxCacheSize = maxCacheSize;
-    this.#downloadLimit = limit(concurrency);
+    // LIFO: downloads for what the user is currently viewing (an offer
+    // preview, a just-opened detail page) are requested last and must not
+    // wait behind a long gallery-wide rebuild of earlier requests.
+    this.#downloadLimit = limit(concurrency, { lifo: true });
 
     this.setMaxListeners(50);
 
diff --git a/packages/gui/src/util/limit.test.ts b/packages/gui/src/util/limit.test.ts
new file mode 100644
index 0000000000..caf30decc5
--- /dev/null
+++ b/packages/gui/src/util/limit.test.ts
@@ -0,0 +1,59 @@
+import limit from './limit';
+
+function deferred() {
+  let resolve!: () => void;
+  const promise = new Promise<void>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+}
+
+describe('limit', () => {
+  it('runs queued tasks in FIFO order by default', async () => {
+    const add = limit(1);
+    const first = deferred();
+    const order: string[] = [];
+
+    const tasks = [
+      add(async () => {
+        await first.promise;
+        order.push('a');
+      }),
+      add(async () => {
+        order.push('b');
+      }),
+      add(async () => {
+        order.push('c');
+      }),
+    ];
+
+    first.resolve();
+    await Promise.all(tasks);
+
+    expect(order).toEqual(['a', 'b', 'c']);
+  });
+
+  it('runs the most recently queued task first in LIFO mode', async () => {
+    const add = limit(1, { lifo: true });
+    const first = deferred();
+    const order: string[] = [];
+
+    const tasks = [
+      add(async () => {
+        await first.promise;
+        order.push('a');
+      }),
+      add(async () => {
+        order.push('b');
+      }),
+      add(async () => {
+        order.push('c');
+      }),
+    ];
+
+    first.resolve();
+    await Promise.all(tasks);
+
+    expect(order).toEqual(['a', 'c', 'b']);
+  });
+});
diff --git a/packages/gui/src/util/limit.ts b/packages/gui/src/util/limit.ts
index 980c42b638..1d0709a74f 100644
--- a/packages/gui/src/util/limit.ts
+++ b/packages/gui/src/util/limit.ts
@@ -1,4 +1,6 @@
-export default function limit(concurrency: number) {
+export default function limit(concurrency: number, options: { lifo?: boolean } = {}) {
+  const { lifo = false } = options;
+
   const queue: {
     func: Function;
     resolve: (value: any) => void;
@@ -13,7 +15,10 @@ export default function limit(concurrency: number) {
 
     active++;
 
-    const item = queue.shift();
+    // LIFO runs the most recently requested task first, so work triggered by
+    // what the user is currently looking at is not starved by a long backlog
+    // of earlier background requests.
+    const item = lifo ? queue.pop() : queue.shift();
     if (!item) {
       return;
     }

From 76f908bf0323e5c8fae4c2492364296f423684a8 Mon Sep 17 00:00:00 2001
From: Jonathan LoBue <jlobue10@gmail.com>
Date: Wed, 19 Aug 2026 19:50:42 -0700
Subject: [PATCH 08/10] Skip downloads that were aborted while queued

A download aborted by invalidation or a cache directory change while it
was still waiting in the concurrency limiter previously started anyway:
downloadFile only listened for future abort events and never checked
signal.aborted. The raced transfer held a download slot and, once the
inactivity or deadline timeout hit, could settle the URL with a
permanently persisted timeout error. Reject up front with the same
retryable 'Request aborted' error the mid-flight abort path reports.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016Q2tBCuePZJeeCkDDxu1m3
---
 .../src/electron/utils/downloadFile.test.ts   | 31 +++++++++++++++++++
 .../gui/src/electron/utils/downloadFile.ts    |  9 ++++++
 2 files changed, 40 insertions(+)
 create mode 100644 packages/gui/src/electron/utils/downloadFile.test.ts

diff --git a/packages/gui/src/electron/utils/downloadFile.test.ts b/packages/gui/src/electron/utils/downloadFile.test.ts
new file mode 100644
index 0000000000..fdeb9b5237
--- /dev/null
+++ b/packages/gui/src/electron/utils/downloadFile.test.ts
@@ -0,0 +1,31 @@
+import os from 'node:os';
+import path from 'node:path';
+
+const mockNetRequest = jest.fn();
+
+jest.mock('electron', () => ({
+  net: {
+    request: mockNetRequest,
+  },
+}));
+
+const downloadFile = jest.requireActual<typeof import('./downloadFile')>('./downloadFile').default;
+
+describe('downloadFile', () => {
+  beforeEach(() => {
+    mockNetRequest.mockReset();
+  });
+
+  it('does not start a transfer whose signal was aborted while queued', async () => {
+    const abortController = new AbortController();
+    abortController.abort();
+
+    await expect(
+      downloadFile('https://example.com/nft.png', path.join(os.tmpdir(), 'downloadFile-test-nft.png'), {
+        signal: abortController.signal,
+      }),
+    ).rejects.toThrow('Request aborted');
+
+    expect(mockNetRequest).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/gui/src/electron/utils/downloadFile.ts b/packages/gui/src/electron/utils/downloadFile.ts
index a6c2c974b4..7520fdb5ac 100644
--- a/packages/gui/src/electron/utils/downloadFile.ts
+++ b/packages/gui/src/electron/utils/downloadFile.ts
@@ -90,6 +90,15 @@ export default async function downloadFile(
     throw new Error('Invalid URL');
   }
 
+  // A queued download can be aborted (invalidation, cache directory change)
+  // before the concurrency limiter starts it. Without this check the transfer
+  // would still run, hold a download slot, and could settle the URL with a
+  // permanent timeout error. The error matches the mid-flight abort message so
+  // the cache treats it as retryable.
+  if (signal?.aborted) {
+    throw new Error('Request aborted');
+  }
+
   const tempFilePath = `${localPath}.tmp`;
   const request = net.request(url);
   const outputStream = new WriteStreamPromise(tempFilePath, overrideFile);

From 29fc2d31ceab15f934a3e3ecc565794ddd8f502e Mon Sep 17 00:00:00 2001
From: Jonathan LoBue <jlobue10@gmail.com>
Date: Wed, 19 Aug 2026 19:50:48 -0700
Subject: [PATCH 09/10] Keep the default cache limit for a stored legacy zero
 size

Older builds stored the cache limit under the legacy cacheLimitSize key
and rejected zero at startup, keeping the 1GB default. Accepting zero
from that key would silently turn those prefs files into an unlimited
cache after upgrade. Only the current maxCacheSize key may carry zero
(unlimited); a legacy zero falls through to the default.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016Q2tBCuePZJeeCkDDxu1m3
---
 packages/gui/src/electron/main.tsx            |  8 +---
 .../utils/resolveStoredMaxCacheSize.test.ts   | 37 +++++++++++++++++++
 .../utils/resolveStoredMaxCacheSize.ts        | 24 ++++++++++++
 3 files changed, 63 insertions(+), 6 deletions(-)
 create mode 100644 packages/gui/src/electron/utils/resolveStoredMaxCacheSize.test.ts
 create mode 100644 packages/gui/src/electron/utils/resolveStoredMaxCacheSize.ts

diff --git a/packages/gui/src/electron/main.tsx b/packages/gui/src/electron/main.tsx
index 0a2f0b6a86..80e442814b 100644
--- a/packages/gui/src/electron/main.tsx
+++ b/packages/gui/src/electron/main.tsx
@@ -80,6 +80,7 @@ import {
   addBypassCommand,
 } from './utils/pairStore';
 import * as privatePreferences from './utils/privatePreferences';
+import resolveStoredMaxCacheSize from './utils/resolveStoredMaxCacheSize';
 import toCamelCase from './utils/toCamelCase';
 import { setUserDataDir } from './utils/userData';
 import webSocketBridgeBindEvents from './utils/webSocketBridge';
@@ -118,12 +119,7 @@ const prefs = readPrefs();
 const defaultCacheFolder = path.join(app.getPath('cache'), app.getName());
 const cacheDirectory: string = prefs.cacheFolder || defaultCacheFolder;
 
-// `cacheLimitSize` is the legacy preference key older versions of the
-// settings UI stored the value under. Invalid values are ignored because the
-// CacheManager constructor rejects negative sizes; zero means unlimited.
-const storedMaxCacheSize: number | undefined = [prefs.maxCacheSize, prefs.cacheLimitSize].find(
-  (size) => typeof size === 'number' && Number.isFinite(size) && size >= 0,
-);
+const storedMaxCacheSize: number | undefined = resolveStoredMaxCacheSize(prefs);
 
 const cacheManager = new CacheManager({
   cacheDirectory,
diff --git a/packages/gui/src/electron/utils/resolveStoredMaxCacheSize.test.ts b/packages/gui/src/electron/utils/resolveStoredMaxCacheSize.test.ts
new file mode 100644
index 0000000000..61630a17ee
--- /dev/null
+++ b/packages/gui/src/electron/utils/resolveStoredMaxCacheSize.test.ts
@@ -0,0 +1,37 @@
+import resolveStoredMaxCacheSize from './resolveStoredMaxCacheSize';
+
+describe('resolveStoredMaxCacheSize', () => {
+  it('accepts a positive size from the current key', () => {
+    expect(resolveStoredMaxCacheSize({ maxCacheSize: 2048 })).toBe(2048);
+  });
+
+  it('accepts zero (unlimited) from the current key', () => {
+    expect(resolveStoredMaxCacheSize({ maxCacheSize: 0 })).toBe(0);
+  });
+
+  it('accepts a positive size from the legacy key', () => {
+    expect(resolveStoredMaxCacheSize({ cacheLimitSize: 1024 })).toBe(1024);
+  });
+
+  it('ignores a legacy zero so the default limit still applies after upgrade', () => {
+    // older builds rejected a stored zero at startup and kept the default
+    // limit, so a migrated zero must not silently become unlimited
+    expect(resolveStoredMaxCacheSize({ cacheLimitSize: 0 })).toBeUndefined();
+  });
+
+  it('prefers the current key over the legacy key', () => {
+    expect(resolveStoredMaxCacheSize({ maxCacheSize: 512, cacheLimitSize: 1024 })).toBe(512);
+  });
+
+  it('falls back to a valid legacy size when the current key is invalid', () => {
+    expect(resolveStoredMaxCacheSize({ maxCacheSize: -1, cacheLimitSize: 1024 })).toBe(1024);
+  });
+
+  it('ignores invalid values', () => {
+    expect(resolveStoredMaxCacheSize({})).toBeUndefined();
+    expect(resolveStoredMaxCacheSize({ maxCacheSize: -5 })).toBeUndefined();
+    expect(resolveStoredMaxCacheSize({ maxCacheSize: Number.NaN })).toBeUndefined();
+    expect(resolveStoredMaxCacheSize({ maxCacheSize: Number.POSITIVE_INFINITY })).toBeUndefined();
+    expect(resolveStoredMaxCacheSize({ maxCacheSize: '1024', cacheLimitSize: '2048' })).toBeUndefined();
+  });
+});
diff --git a/packages/gui/src/electron/utils/resolveStoredMaxCacheSize.ts b/packages/gui/src/electron/utils/resolveStoredMaxCacheSize.ts
new file mode 100644
index 0000000000..aa74a777e8
--- /dev/null
+++ b/packages/gui/src/electron/utils/resolveStoredMaxCacheSize.ts
@@ -0,0 +1,24 @@
+type StoredCacheSizePrefs = {
+  maxCacheSize?: unknown;
+  cacheLimitSize?: unknown;
+};
+
+const isStoredCacheSize = (size: unknown): size is number => typeof size === 'number' && Number.isFinite(size);
+
+// `cacheLimitSize` is the legacy preference key older versions of the
+// settings UI stored the value under. Invalid values are ignored because the
+// CacheManager constructor rejects negative sizes. Zero means unlimited, but
+// only under the current key: builds that wrote `cacheLimitSize` rejected
+// zero at startup and kept the default limit, so a stored legacy zero must
+// keep falling through to the default instead of disabling eviction.
+export default function resolveStoredMaxCacheSize(prefs: StoredCacheSizePrefs): number | undefined {
+  if (isStoredCacheSize(prefs.maxCacheSize) && prefs.maxCacheSize >= 0) {
+    return prefs.maxCacheSize;
+  }
+
+  if (isStoredCacheSize(prefs.cacheLimitSize) && prefs.cacheLimitSize > 0) {
+    return prefs.cacheLimitSize;
+  }
+
+  return undefined;
+}

From 89c9716c2c719b5b5c0140782d38598ef708f246 Mon Sep 17 00:00:00 2001
From: Jonathan LoBue <jlobue10@gmail.com>
Date: Wed, 19 Aug 2026 19:50:55 -0700
Subject: [PATCH 10/10] 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
---
 .../gui/src/electron/CacheManager.test.ts     | 51 +++++++++++++++++++
 packages/gui/src/electron/CacheManager.ts     | 20 +++++++-
 2 files changed, 70 insertions(+), 1 deletion(-)

diff --git a/packages/gui/src/electron/CacheManager.test.ts b/packages/gui/src/electron/CacheManager.test.ts
index a68f4a8a70..00a5371b25 100644
--- a/packages/gui/src/electron/CacheManager.test.ts
+++ b/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) => {
diff --git a/packages/gui/src/electron/CacheManager.ts b/packages/gui/src/electron/CacheManager.ts
index c3d91c7b58..745cd4899d 100644
--- a/packages/gui/src/electron/CacheManager.ts
+++ b/packages/gui/src/electron/CacheManager.ts
@@ -251,14 +251,25 @@ 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()) {
@@ -266,6 +277,12 @@ export default class CacheManager extends EventEmitter {
           }
         } 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;