perf(delta-upgrade): lazy chain walk, GHCR retry, parallel I/O, offline cache

Four performance optimizations for the delta upgrade system:

## Lazy chain resolution (replaces eager graph build)

Replace buildNightlyPatchGraph + walkNightlyChain with a lazy approach
in resolveNightlyChain:

- List all patch tags (1 HTTP call, kept)
- Filter tags to only those between currentVersion and targetVersion
  using Bun.semver.order() — since patches are sequential, this gives
  the exact chain without fetching any manifests
- Sort filtered tags by version
- Fetch only the 1-2 manifests in the chain (instead of all N)

This reduces manifest fetches from ~14 to 1-2 for typical upgrades.

## Retry with timeout for GHCR requests

Add fetchWithRetry helper in ghcr.ts:
- 10s timeout per request (AbortSignal.timeout)
- 1 retry on transient errors (timeout, network, connection reset)
- Applied to getAnonymousToken, fetchManifest, fetchTagPage
- downloadNightlyBlob gets 30s timeout (no retry — large downloads)

## Parallel I/O

fetchManifest(targetTag) and listTags() run concurrently via Promise.all
after token acquisition — both only depend on the token, not each other.

## Patch pre-fetch for offline upgrades

New file-based cache in ~/.sentry/patch-cache/ enables fully offline
delta upgrades for both nightly and stable channels:

- Background version check now pre-fetches delta patches (~50-80KB)
  after discovering a new version
- Patches accumulate across runs: skip 3 versions, all 3 patches are
  cached, multi-hop upgrade is fully offline
- resolveStableDelta/resolveNightlyDelta check cache before network
- delta.source span attribute tracks cache vs network for telemetry
- 7-day TTL with opportunistic cleanup during version checks
- Two-pass cleanup preserves shared patches referenced by live chains

Author: BYK

AGENTS.md

@@ -20,6 +20,82 @@
 import { getUserAgent } from "./constants.js";
 import { UpgradeError } from "./errors.js";
 
+/** Default timeout for GHCR HTTP requests (10 seconds) */
+const GHCR_REQUEST_TIMEOUT = 10_000;
+
+/** Maximum number of retry attempts for transient failures */
+const GHCR_MAX_RETRIES = 1;
+
+/** Timeout for large blob downloads (30 seconds) */
+const GHCR_BLOB_TIMEOUT = 30_000;
+
+/**
+ * Check if an error is a transient network/timeout failure worth retrying.
+ *
+ * Matches timeout/abort errors from `AbortSignal.timeout()`, connection
+ * resets, and generic network failures. Does NOT match HTTP-level errors
+ * (those are handled by the caller after receiving a Response).
+ */
+function isRetryableError(error: Error): boolean {
+  // AbortSignal.timeout() throws a TimeoutError DOMException — check by name
+  // rather than relying on error message content (which varies across runtimes)
+  if (error.name === "TimeoutError" || error.name === "AbortError") {
+    return true;
+  }
+  const msg = error.message.toLowerCase();
+  return (
+    msg.includes("timeout") ||
+    msg.includes("econnreset") ||
+    msg.includes("econnrefused") ||
+    msg.includes("network") ||
+    msg.includes("fetch failed")
+  );
+}
+
+/**
+ * Fetch with timeout and retry for GHCR requests.
+ *
+ * GHCR exhibits cold-start latency spikes (126ms → 30s for identical
+ * requests). A short timeout + retry keeps the worst case at ~20s instead
+ * of 30s, and helps when the first request hits a cold instance.
+ *
+ * @param url - Request URL
+ * @param init - Fetch init options (signal will be added/overridden)
+ * @param context - Human-readable context for error messages
+ * @param timeout - Per-request timeout in milliseconds
+ * @returns Response from a successful fetch
+ * @throws {UpgradeError} On all attempts exhausted
+ */
+async function fetchWithRetry(
+  url: string,
+  init: RequestInit,
+  context: string,
+  timeout = GHCR_REQUEST_TIMEOUT
+): Promise<Response> {
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt <= GHCR_MAX_RETRIES; attempt++) {
+    try {
+      const response = await fetch(url, {
+        ...init,
+        signal: AbortSignal.timeout(timeout),
+      });
+      return response;
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      // Only retry on timeout or network errors — not HTTP errors
+      if (attempt >= GHCR_MAX_RETRIES || !isRetryableError(lastError)) {
+        break;
+      }
+    }
+  }
+
+  throw new UpgradeError(
+    "network_error",
+    `${context}: ${lastError?.message ?? "unknown error"}`
+  );
+}
+
 /** GHCR repository for CLI distribution */
 export const GHCR_REPO = "getsentry/cli";
 
@@ -81,18 +157,11 @@ export type OciManifest = {
  */
 export async function getAnonymousToken(): Promise<string> {
   const url = `${GHCR_REGISTRY}/token?scope=repository:${GHCR_REPO}:pull`;
-  let response: Response;
-  try {
-    response = await fetch(url, {
-      headers: { "User-Agent": getUserAgent() },
-    });
-  } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    throw new UpgradeError(
-      "network_error",
-      `Failed to connect to GHCR: ${msg}`
-    );
-  }
+  const response = await fetchWithRetry(
+    url,
+    { headers: { "User-Agent": getUserAgent() } },
+    "Failed to connect to GHCR"
+  );
 
   if (!response.ok) {
     throw new UpgradeError(
@@ -125,22 +194,17 @@ export async function fetchManifest(
   tag: string
 ): Promise<OciManifest> {
   const url = `${GHCR_REGISTRY}/v2/${GHCR_REPO}/manifests/${tag}`;
-  let response: Response;
-  try {
-    response = await fetch(url, {
+  const response = await fetchWithRetry(
+    url,
+    {
       headers: {
         Authorization: `Bearer ${token}`,
         Accept: OCI_MANIFEST_TYPE,
         "User-Agent": getUserAgent(),
       },
-    });
-  } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    throw new UpgradeError(
-      "network_error",
-      `Failed to connect to GHCR: ${msg}`
-    );
-  }
+    },
+    `Failed to fetch manifest for tag "${tag}"`
+  );
 
   if (!response.ok) {
     throw new UpgradeError(
@@ -244,6 +308,7 @@ export async function downloadNightlyBlob(
         "User-Agent": getUserAgent(),
       },
       redirect: "manual",
+      signal: AbortSignal.timeout(GHCR_BLOB_TIMEOUT),
     });
   } catch (error) {
     const msg = error instanceof Error ? error.message : String(error);
@@ -275,6 +340,11 @@ export async function downloadNightlyBlob(
     // Step 2: Follow the redirect WITHOUT the Authorization header.
     // Azure rejects requests that include a Bearer token alongside its own
     // signed query-string credentials (returns 404).
+    // No AbortSignal.timeout here: this fetch covers both connection AND
+    // body streaming. For full nightly binaries (~30 MB), a 30s timeout
+    // would require sustained ~8 Mbps throughput and fail on slow connections.
+    // The GHCR step 1 timeout above guards against GHCR-side latency;
+    // Azure Blob Storage has reliable latency characteristics.
     let redirectResponse: Response;
     try {
       redirectResponse = await fetch(redirectUrl, {
@@ -324,18 +394,16 @@ async function fetchTagPage(
     url += `&last=${encodeURIComponent(lastTag)}`;
   }
 
-  let response: Response;
-  try {
-    response = await fetch(url, {
+  const response = await fetchWithRetry(
+    url,
+    {
       headers: {
         Authorization: `Bearer ${token}`,
         "User-Agent": getUserAgent(),
       },
-    });
-  } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    throw new UpgradeError("network_error", `Failed to list GHCR tags: ${msg}`);
-  }
+    },
+    "Failed to list GHCR tags"
+  );
 
   if (!response.ok) {
     throw new UpgradeError(