fix(telemetry): instrument delta upgrade with spans and error capture

Delta upgrade failures were completely invisible in Sentry:
- No spans for the delta attempt (only DB queries visible in traces)
- Errors caught and logged at debug level (invisible without --verbose)
- No captureException — errors never reported to Sentry

This made it impossible to diagnose the ETXTBSY/SIGKILL issues
(PRs #339, #340, #343) from telemetry alone — they were found
through code analysis and local reproduction.

Changes:
- Wrap attemptDeltaUpgrade in withTracingSpan for a 'upgrade.delta' span
- Record delta.from_version, delta.to_version, delta.channel as attributes
- On success: record patch_bytes and sha256 prefix
- On unavailable (no patch): record delta.result='unavailable'
- On error: captureException with warning level + delta context tags,
  record delta.result='error' and delta.error message on span
- Upgrade log.debug to log.warn for failure messages so users see them

Now delta failures will appear as:
1. A span in the upgrade trace (with error status + attributes)
2. A warning-level exception in Sentry Issues (with delta context)
3. A visible stderr message to the user

Author: BYK

src/lib/bspatch.ts

@@ -6,7 +6,8 @@
  * minimal memory usage during CLI self-upgrades:
  *
  * - Old binary: copy-then-mmap for 0 JS heap (CoW on btrfs/xfs/APFS),
- *   falling back to `arrayBuffer()` (~100 MB heap) if mmap fails
+ *   with child-process probe for mmap safety (macOS AMFI sends uncatchable
+ *   SIGKILL on signed Mach-O), falling back to `arrayBuffer()` if unsafe
  * - Diff/extra blocks: streamed via `DecompressionStream('zstd')`
  * - Output: written incrementally to disk via `Bun.file().writer()`
  * - Integrity: SHA-256 computed inline via `Bun.CryptoHasher`
@@ -227,34 +228,88 @@ type OldFileHandle = {
   cleanup: () => void;
 };
 
+/**
+ * Probe whether `Bun.mmap()` works on a file by spawning a child process.
+ *
+ * macOS AMFI sends uncatchable SIGKILL when a process creates a writable
+ * memory mapping of a code-signed Mach-O binary — even a copy. Since
+ * SIGKILL terminates the process inside the syscall (before any catch
+ * block runs), we cannot detect the failure in-process.
+ *
+ * This probe spawns a minimal child that attempts `Bun.mmap()` on the
+ * target file. If the child exits 0, mmap is safe. If it's killed
+ * (SIGKILL) or exits non-zero, we fall back to `arrayBuffer()`.
+ *
+ * @param filePath - Path to the file to probe (should be the temp copy)
+ * @returns true if mmap is safe on this file, false otherwise
+ */
+async function probeMmapSafe(filePath: string): Promise<boolean> {
+  try {
+    const child = Bun.spawn(
+      [
+        process.execPath,
+        "-e",
+        `Bun.mmap(${JSON.stringify(filePath)}, { shared: false })`,
+      ],
+      { stdout: "ignore", stderr: "ignore" }
+    );
+    const exitCode = await child.exited;
+    return exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Load the old binary for read access during patching.
  *
- * Strategy: copy to temp file, then mmap the copy. This avoids `Bun.mmap()`
- * on the running binary (SIGKILL on macOS, ETXTBSY on Linux) while keeping
- * zero JS heap — the kernel manages the mapped pages. On CoW filesystems
+ * Strategy: copy to temp file, probe mmap safety via child process,
+ * then mmap the copy if safe. This avoids `Bun.mmap()` on files that
+ * would trigger uncatchable SIGKILL (macOS AMFI on signed Mach-O) while
+ * keeping zero JS heap on platforms where mmap works. On CoW filesystems
  * (btrfs, xfs, APFS) the copy is a metadata-only reflink (near-instant).
  *
- * Falls back to `Bun.file().arrayBuffer()` (~100 MB heap) if the copy or
- * mmap fails for any reason (permissions, disk space, unsupported FS).
+ * Falls back to `Bun.file().arrayBuffer()` (~100 MB heap) if the probe
+ * fails or if copy/mmap errors for any reason.
  */
 async function loadOldBinary(oldPath: string): Promise<OldFileHandle> {
   const tempCopy = join(tmpdir(), `sentry-patch-old-${process.pid}`);
   try {
     copyFileSync(oldPath, tempCopy);
-    const data = Bun.mmap(tempCopy, { shared: false });
+
+    // Probe mmap safety in a child process — macOS AMFI sends uncatchable
+    // SIGKILL on writable mappings of signed Mach-O, even for copies.
+    const mmapSafe = await probeMmapSafe(tempCopy);
+
+    if (mmapSafe) {
+      const data = Bun.mmap(tempCopy, { shared: false });
+      return {
+        data,
+        cleanup: () => {
+          try {
+            unlinkSync(tempCopy);
+          } catch {
+            // Best-effort cleanup — OS will reclaim on reboot
+          }
+        },
+      };
+    }
+
+    // mmap probe failed — read copy into JS heap, then clean up temp file
+    const data = new Uint8Array(await Bun.file(tempCopy).arrayBuffer());
+    try {
+      unlinkSync(tempCopy);
+    } catch {
+      // Best-effort cleanup
+    }
     return {
       data,
       cleanup: () => {
-        try {
-          unlinkSync(tempCopy);
-        } catch {
-          // Best-effort cleanup — OS will reclaim on reboot
-        }
+        // Data is in JS heap — no temp file to clean up
       },
     };
   } catch {
-    // Copy or mmap failed — fall back to reading into JS heap
+    // Copy failed — fall back to reading original directly into JS heap
     try {
       unlinkSync(tempCopy);
     } catch {
@@ -263,7 +318,7 @@ async function loadOldBinary(oldPath: string): Promise<OldFileHandle> {
     return {
       data: new Uint8Array(await Bun.file(oldPath).arrayBuffer()),
       cleanup: () => {
-        // No temp file to clean up — data is in JS heap
+        // Data is in JS heap — no temp file to clean up
       },
     };
   }

src/lib/delta-upgrade.ts

@@ -19,6 +19,8 @@
 
 import { unlinkSync } from "node:fs";
 
+import { captureException } from "@sentry/bun";
+
 import {
   GITHUB_RELEASES_URL,
   getPlatformBinaryName,
@@ -34,6 +36,7 @@ import {
   type OciManifest,
 } from "./ghcr.js";
 import { logger } from "./logger.js";
+import { withTracingSpan } from "./telemetry.js";
 
 /** Scoped logger for delta upgrade operations */
 const log = logger.withTag("delta-upgrade");
@@ -563,29 +566,76 @@ export async function resolveNightlyChain(
  * @param destPath - Path to write the patched binary
  * @returns Delta result with SHA-256 and size info, or null if delta is unavailable
  */
-export async function attemptDeltaUpgrade(
+export function attemptDeltaUpgrade(
   targetVersion: string,
   oldBinaryPath: string,
   destPath: string
 ): Promise<DeltaResult | null> {
   if (!canAttemptDelta(targetVersion)) {
-    return null;
+    return Promise.resolve(null);
   }
 
-  log.debug(`Attempting delta upgrade from ${CLI_VERSION} to ${targetVersion}`);
+  const channel = isNightlyVersion(targetVersion) ? "nightly" : "stable";
 
-  try {
-    if (isNightlyVersion(targetVersion)) {
-      return await resolveNightlyDelta(targetVersion, oldBinaryPath, destPath);
-    }
-    return await resolveStableDelta(targetVersion, oldBinaryPath, destPath);
-  } catch (error) {
-    // Any error during delta upgrade → fall back to full download.
-    // Log at debug so --verbose reveals the root cause (ETXTBSY, network, etc.)
-    const msg = error instanceof Error ? error.message : String(error);
-    log.debug(`Delta upgrade failed (${msg}), falling back to full download`);
-    return null;
-  }
+  return withTracingSpan(
+    "delta-upgrade",
+    "upgrade.delta",
+    async (span) => {
+      span.setAttribute("delta.from_version", CLI_VERSION);
+      span.setAttribute("delta.to_version", targetVersion);
+      span.setAttribute("delta.channel", channel);
+
+      log.debug(
+        `Attempting delta upgrade from ${CLI_VERSION} to ${targetVersion}`
+      );
+
+      try {
+        const result =
+          channel === "nightly"
+            ? await resolveNightlyDelta(targetVersion, oldBinaryPath, destPath)
+            : await resolveStableDelta(targetVersion, oldBinaryPath, destPath);
+
+        if (result) {
+          span.setAttribute("delta.patch_bytes", result.patchBytes);
+          span.setAttribute("delta.sha256", result.sha256.slice(0, 12));
+          span.setStatus({ code: 1 }); // OK
+        } else {
+          // No patch available — not an error, just unavailable
+          span.setAttribute("delta.result", "unavailable");
+          span.setStatus({ code: 1 }); // OK — graceful fallback
+        }
+        return result;
+      } catch (error) {
+        // Record the error in Sentry so we can see delta failures in telemetry.
+        // Marked non-fatal: the upgrade continues via full download.
+        captureException(error, {
+          level: "warning",
+          tags: {
+            "delta.from_version": CLI_VERSION,
+            "delta.to_version": targetVersion,
+            "delta.channel": channel,
+          },
+          contexts: {
+            delta_upgrade: {
+              from_version: CLI_VERSION,
+              to_version: targetVersion,
+              channel,
+              old_binary_path: oldBinaryPath,
+            },
+          },
+        });
+
+        const msg = error instanceof Error ? error.message : String(error);
+        log.warn(
+          `Delta upgrade failed (${msg}), falling back to full download`
+        );
+        span.setAttribute("delta.result", "error");
+        span.setAttribute("delta.error", msg);
+        return null;
+      }
+    },
+    { "delta.channel": channel }
+  );
 }
 
 /**