fix(installer): bundle uv binary for mac-arm64 (#967)

Before: installing the macOS DMG on a clean Apple-Silicon Mac with no
system `uv` on `PATH` hard-failed during `ensure-uv` —
`bundledUvPlatformKey()` claimed `mac-arm64` support, but no CI step
ever fetched the binary. First-launch error: `"No bundled uv available
for darwin-arm64 and no system uv found"`. After: the macOS build job
fetches the pinned `uv` v0.5.14 `aarch64-apple-darwin` binary, verifies
its archive SHA, and places it at `build/vendor/uv/mac-arm64/uv` so
`electron-builder` ships it inside
`Contents/Resources/vendor/uv/mac-arm64/uv`. A new
`dmg-structural-smoke` CI job mounts the built DMG, asserts the binary
is present + executable + SHA-pinned + actually runs (`uv --version`),
and is wired into the `build-complete` gate so future drift fails at
smoke time, not on a user's first launch.

Also bundled: the `pr-review` job in `.github/workflows/claude.yml` is
temporarily disabled (`if: false`) because the CI bot's Anthropic API
key is out of credits — auto-review will not run on this or any PR until
the credit balance is restored. Tracked for re-enable separately from
this fix.

Closes #941.

## Test plan

- [ ] Trigger `build-installers` workflow against this branch and
confirm `dmg-structural-smoke` and `build-complete` are both green
- [ ] On a clean Apple-Silicon Mac with no system `uv` (verify: `which
uv` → not found): download the DMG via browser (not `gh run download` —
browser sets the quarantine xattr that Gatekeeper checks), install,
launch GAIA, confirm it reaches `state: ready` with no `ensure-uv` error
and no `Killed: 9` on the spawned uv child
- [ ] Confirm `~/.gaia/bin/uv --version` works after install
- [ ] Test on macOS Sequoia (15.x) — Sequoia tightened CS checks for
child processes spawned by hardened-runtime apps

Author: itomek

.github/workflows/build-installers.yml

@@ -92,6 +92,12 @@ on:
       - 'src/gaia/apps/webui/main.cjs'
       - 'src/gaia/apps/webui/bin/**'
       - 'src/gaia/apps/webui/services/**'
+      # Cover the installer-smoke test tree (issue #941) so a PR that
+      # only touches the smoke-test layer still triggers structural smoke.
+      # Narrower than `tests/electron/**` so Jest-only edits to e.g.
+      # test_electron_chat_app.js don't re-run the multi-platform build.
+      - 'tests/electron/_helpers/**'
+      - 'tests/electron/*-smoke.test.mjs'
       - 'tests/electron/fixtures/**'
       - 'src/gaia/version.py'
 
@@ -229,6 +235,44 @@ jobs:
           chmod 0755 "${DEST_DIR}/uv"
           "${DEST_DIR}/uv" --version
 
+      # ─── Fetch uv binary for macOS DMG (issue #941) ─────────────────
+      # Mirror of the Linux step above. Without this, the macOS .app
+      # ships no bundled uv even though backend-installer.cjs claims
+      # support for darwin-arm64, so first-launch on a clean Mac (no
+      # system uv on PATH) hard-fails in ensure-uv. The runtime hashes
+      # the *extracted* binary against BUNDLED_UV_SHA256["mac-arm64"]
+      # in src/gaia/apps/webui/services/backend-installer.cjs — those
+      # two pins MUST be bumped in lockstep with this step.
+      - name: Fetch uv binary (macOS)
+        if: matrix.platform == 'macos'
+        shell: bash
+        run: |
+          set -euo pipefail
+          UV_VERSION="0.5.14"
+          UV_TARBALL="uv-aarch64-apple-darwin.tar.gz"
+          UV_SHA256="d548dffc256014c4c8c693e148140a3a21bcc2bf066a35e1d5f0d24c91d32112"
+          UV_URL="https://github.com/astral-sh/uv/releases/download/${UV_VERSION}/${UV_TARBALL}"
+          DEST_DIR="src/gaia/apps/webui/build/vendor/uv/mac-arm64"
+          mkdir -p "${DEST_DIR}"
+          tmpdir="$(mktemp -d)"
+          # --retry 3/5s matches the Lemonade MSI step below; survives
+          # transient GitHub Releases CDN flakes on hosted macOS runners.
+          curl -fsSL --retry 3 --retry-delay 5 -o "${tmpdir}/${UV_TARBALL}" "${UV_URL}"
+          # macOS shasum -a 256 -c accepts the GNU "hash  file" format.
+          echo "${UV_SHA256}  ${tmpdir}/${UV_TARBALL}" | shasum -a 256 -c -
+          tar -xzf "${tmpdir}/${UV_TARBALL}" -C "${tmpdir}"
+          cp "${tmpdir}/uv-aarch64-apple-darwin/uv" "${DEST_DIR}/uv"
+          chmod 0755 "${DEST_DIR}/uv"
+          "${DEST_DIR}/uv" --version
+          # Echo the extracted-binary SHA. This is the PRE-codesign digest
+          # (i.e., the upstream tarball's uv byte-for-byte), useful for
+          # confirming what feeds into electron-builder's codesign step.
+          # NOTE: this is NOT directly comparable to BUNDLED_UV_SHA256[mac-arm64],
+          # which is the POST-codesign digest — see backend-installer.cjs.
+          # To bump BUNDLED_UV_SHA256[mac-arm64], run the CI build and copy
+          # the SHA from the dmg-structural-smoke failure message.
+          shasum -a 256 "${DEST_DIR}/uv"
+
       - name: Build frontend (Vite)
         working-directory: src/gaia/apps/webui
         shell: bash
@@ -532,6 +576,46 @@ jobs:
           GAIA_APPIMAGE: ${{ steps.locate.outputs.appimage }}
         run: node --test tests/electron/appimage-smoke.test.mjs
 
+  # ─── DMG structural smoke (issue #941) ──────────────────────────────
+  # Mirrors appimage-structural-smoke for the macOS DMG. Catches the
+  # failure mode that bit v0.17.5: a darwin-arm64 install that hard-fails
+  # in ensure-uv on first launch because the bundled uv either was never
+  # shipped or has the wrong SHA256 against BUNDLED_UV_SHA256[mac-arm64]
+  # in backend-installer.cjs.
+  #
+  # MUST be present in build-complete `needs:` below — without that
+  # wiring, a failing DMG smoke does not block release-readiness.
+  dmg-structural-smoke:
+    name: DMG structural smoke
+    needs: build
+    if: always() && needs.build.result == 'success'
+    runs-on: macos-latest  # Apple Silicon (arm64) — matches build matrix
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Download macOS installer artifact
+        uses: actions/download-artifact@v6
+        with:
+          name: macos-installer  # ${{ matrix.platform }}-installer with platform=macos
+          path: ${{ runner.temp }}/macos-installer
+
+      - name: Locate DMG
+        id: locate
+        shell: bash
+        run: |
+          set -euo pipefail
+          DMG=$(ls "${RUNNER_TEMP}/macos-installer"/*.dmg | head -n1)
+          echo "Found DMG: ${DMG}"
+          echo "dmg=${DMG}" >> "$GITHUB_OUTPUT"
+
+      - name: Structural smoke (uv binary, mode, sha256, --version)
+        env:
+          GAIA_DMG: ${{ steps.locate.outputs.dmg }}
+        run: node --test tests/electron/dmg-smoke.test.mjs
+
   appimage-distro-matrix:
     name: AppImage distro matrix
     needs: build
@@ -971,6 +1055,7 @@ jobs:
       - appimage-structural-smoke
       - appimage-distro-matrix
       - appimage-userns-restricted
+      - dmg-structural-smoke
     if: always()
     steps:
       - name: Verify all platform builds and smoke tests succeeded
@@ -980,22 +1065,24 @@ jobs:
           structural_result="${{ needs.appimage-structural-smoke.result }}"
           distro_result="${{ needs.appimage-distro-matrix.result }}"
           userns_result="${{ needs.appimage-userns-restricted.result }}"
+          dmg_result="${{ needs.dmg-structural-smoke.result }}"
           echo "build:                       $build_result"
           echo "appimage-structural-smoke:   $structural_result"
           echo "appimage-distro-matrix:      $distro_result"
           echo "appimage-userns-restricted:  $userns_result"
+          echo "dmg-structural-smoke:        $dmg_result"
           fail=0
           if [ "$build_result" != "success" ]; then
             echo "::error::One or more platform installer builds failed"
             fail=1
           fi
-          for r in "$structural_result" "$distro_result" "$userns_result"; do
+          for r in "$structural_result" "$distro_result" "$userns_result" "$dmg_result"; do
             if [ "$r" != "success" ] && [ "$r" != "skipped" ]; then
-              echo "::error::AppImage smoke job failed (status: $r)"
+              echo "::error::Installer smoke job failed (status: $r)"
               fail=1
             fi
           done
           if [ "$fail" -eq 1 ]; then
             exit 1
           fi
-          echo "All platform installers built and AppImage smoke suite passed."
+          echo "All platform installers built and installer smoke suite passed."

.github/workflows/claude.yml

@@ -57,11 +57,16 @@ permissions:
 jobs:
   # Auto-review new PRs (including forks)
   pr-review:
-    if: |
-      github.repository == 'amd/gaia' &&
-      github.event_name == 'pull_request_target' &&
-      (github.event.pull_request.draft == false ||
-       contains(github.event.pull_request.labels.*.name, 'ready_for_ci'))
+    # Temporarily disabled 2026-05 — Anthropic credit balance exhausted
+    # (see commit a013e384). Tracked for re-enable in
+    # https://github.com/amd/gaia/issues/970. To re-enable, replace the
+    # `if: false` line below with this commented gate:
+    # if: |
+    #   github.repository == 'amd/gaia' &&
+    #   github.event_name == 'pull_request_target' &&
+    #   (github.event.pull_request.draft == false ||
+    #    contains(github.event.pull_request.labels.*.name, 'ready_for_ci'))
+    if: false
     runs-on: ubuntu-latest
     concurrency:
       group: claude-pr-review-${{ github.event.pull_request.number }}

src/gaia/apps/webui/services/backend-installer.cjs

@@ -77,10 +77,22 @@ const NETWORK_CHECK_TIMEOUT_MS = 5000;
 // archive against upstream's published .sha256, then extracts the `uv` binary
 // which is what `ensureUv()` hashes at runtime.
 //
-// Currently pinned: uv v0.5.14 linux-x64.
+// Currently pinned: uv v0.5.14 linux-x64, mac-arm64.
+// (win-x64 deferred to a follow-up issue — its SHA must ship together with an
+// NSIS structural-smoke verifier, not on its own; see the #849 lesson.)
+//
+// IMPORTANT: per-platform SHA origin differs:
+//   - linux-x64:  raw extracted-from-tarball digest (no post-build modification).
+//   - mac-arm64:  POST-CODESIGN digest. electron-builder code-signs the bundled
+//                 uv during packaging, so this hash matches what ensureUv() sees
+//                 at runtime, NOT the upstream tarball. Bumping this pin means
+//                 running the CI build, then copying the SHA from the
+//                 dmg-structural-smoke failure message — never from `shasum`
+//                 against the freshly downloaded tarball.
 const BUNDLED_UV_VERSION = "0.5.14";
 const BUNDLED_UV_SHA256 = {
   "linux-x64": "0e05d828b5708e8a927724124db3746396afddad6273c47283d7c562dc795bd6",
+  "mac-arm64": "6099aa8cd701f0c81227ee30c304777ce151e4d47c53a75ce53cd2243448d8c8",
 };
 
 const MANAGED_UV_DIR = path.join(GAIA_HOME, "bin");

tests/electron/_helpers/installer-smoke.mjs

@@ -0,0 +1,129 @@
+// Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved.
+// SPDX-License-Identifier: MIT
+//
+// Shared assertions for installer structural smoke tests (issue #941).
+//
+// One source of truth for:
+//   1. The in-resources path layout for the bundled `uv` binary
+//      (mirrors electron-builder.yml `extraResources.to: vendor/uv`).
+//   2. Parsing BUNDLED_UV_SHA256 out of backend-installer.cjs.
+//   3. The full existence + executable-bit + SHA256 check.
+//
+// Consumed by tests/electron/appimage-smoke.test.mjs and
+// tests/electron/dmg-smoke.test.mjs. A future NSIS smoke test should
+// also consume this module so all three installers stay in lockstep.
+
+import assert from "node:assert/strict";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Mirrors electron-builder.yml `extraResources.to: vendor/uv` — the single
+// source of truth for the in-resources layout. If electron-builder.yml
+// changes the `to:` path, every smoke test breaks here with the same
+// actionable diff: update UV_RESOURCE_SUBPATH.
+export const UV_RESOURCE_SUBPATH = ["vendor", "uv"];
+
+/**
+ * Build the runtime-equivalent path to the bundled uv binary inside an
+ * already-extracted resources directory.
+ *
+ * @param {string} resourcesDir
+ *   Absolute path to the extracted resources directory. Examples:
+ *     - AppImage:  <squashfs-root>/resources
+ *     - DMG:       <mountpoint>/<App>.app/Contents/Resources
+ * @param {"linux-x64"|"mac-arm64"|"win-x64"} platformKey
+ * @returns {string} absolute path to the bundled `uv`/`uv.exe`
+ */
+export function bundledUvPath(resourcesDir, platformKey) {
+  const binary = platformKey === "win-x64" ? "uv.exe" : "uv";
+  return path.join(resourcesDir, ...UV_RESOURCE_SUBPATH, platformKey, binary);
+}
+
+/**
+ * Parse `BUNDLED_UV_SHA256[platformKey]` from backend-installer.cjs source.
+ *
+ * The constant spans multiple lines once it has 2+ entries. `[^}]*?` spans
+ * newlines natively (character classes match `\n` without dotall) and the
+ * stop class on `}` is safe because SHA hex strings cannot contain `}`.
+ *
+ * @param {string} installerCjsPath  absolute path to backend-installer.cjs
+ * @param {string} platformKey       e.g. "linux-x64"
+ * @returns {string} the 64-character hex digest
+ */
+export function parseBundledUvSha(installerCjsPath, platformKey) {
+  const src = fs.readFileSync(installerCjsPath, "utf8");
+  // Defensive: escape regex metacharacters in the platform key, even
+  // though the keys we use have none today.
+  const escapedKey = platformKey.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(
+    `BUNDLED_UV_SHA256\\s*=\\s*\\{[^}]*?"${escapedKey}"\\s*:\\s*"([0-9a-f]{64})"`,
+  );
+  const m = src.match(re);
+  assert.ok(
+    m,
+    `could not parse BUNDLED_UV_SHA256["${platformKey}"] from ${installerCjsPath}`,
+  );
+  return m[1];
+}
+
+/**
+ * Existence + executable-bit (POSIX only) + SHA256-vs-pin check.
+ *
+ * Catches the failure mode that bit issue #849 and motivated #941:
+ * a packaged binary whose SHA does not match the pin in
+ * BUNDLED_UV_SHA256, which `ensureUv()` would reject at runtime with
+ * a hard SHA256 mismatch error on the user's first launch.
+ *
+ * @param {string} uvPath              absolute path to packaged `uv` binary
+ * @param {string} platformKey         e.g. "mac-arm64"
+ * @param {string} installerCjsPath    absolute path to backend-installer.cjs
+ */
+export function assertUvBinary(uvPath, platformKey, installerCjsPath) {
+  assert.ok(fs.existsSync(uvPath), `expected bundled uv at ${uvPath}`);
+  if (platformKey !== "win-x64") {
+    const st = fs.statSync(uvPath);
+    // Any execute bit on any class is enough; squashfs/HFS+/APFS all
+    // preserve 0o755 for the source mode set by the CI fetch step.
+    assert.ok(
+      (st.mode & 0o111) !== 0,
+      `uv binary should be executable; mode=${(st.mode & 0o777).toString(8)}`,
+    );
+  }
+  const expected = parseBundledUvSha(installerCjsPath, platformKey);
+  const actual = crypto
+    .createHash("sha256")
+    .update(fs.readFileSync(uvPath))
+    .digest("hex");
+  assert.equal(
+    actual,
+    expected,
+    `bundled uv binary SHA256 does not match BUNDLED_UV_SHA256["${platformKey}"]; ` +
+      `ensureUv() will reject this at runtime. ` +
+      `To fix: update BUNDLED_UV_SHA256["${platformKey}"] in ` +
+      `src/gaia/apps/webui/services/backend-installer.cjs to: ${actual}`,
+  );
+}
+
+/**
+ * Resolve the absolute path to backend-installer.cjs from a smoke test
+ * file located under tests/electron/. Centralised so a future move of
+ * either tree only updates one place.
+ *
+ * @param {string} testFileUrl  pass `import.meta.url` from the caller
+ * @returns {string}
+ */
+export function backendInstallerPath(testFileUrl) {
+  return path.resolve(
+    path.dirname(fileURLToPath(testFileUrl)),
+    "..",
+    "..",
+    "src",
+    "gaia",
+    "apps",
+    "webui",
+    "services",
+    "backend-installer.cjs",
+  );
+}