fix(installer): bundle uv for win-x64; packaged Windows rescue installer by theonlychant · Pull Request #968 · amd/gaia

theonlychant · 2026-05-06T16:32:57Z

Summary

Bundle uv for Windows (x64) installers and update the installer flow to use the packaged binary, resolving failures during ensure-uv for users without uv on PATH.

Why

The Windows desktop installer currently fails at the ensure-uv step if uv is not already installed and available on the system PATH. This creates a broken first-run experience for new users. The root cause is that no uv binary is bundled for win-x64, so the installer cannot proceed in a clean environment. This change ensures the installer is self-contained and reliable across supported platforms.

Linked issue

Closes #966

Changes

Bundle uv binary for win-x64 and mac-arm64 in the installer artifacts
Update installer logic to reference bundled uv instead of relying on system PATH
Modify backend-installer.cjs to correctly resolve and invoke the packaged binary
Update backend-installer-progressdialogue.cjs to reflect improved installer flow and error handling
Update build-installers.yml to include uv in build outputs for supported targets

Test plan

Build installer for Windows (win-x64) and macOS (arm64)
Run installer on a clean system with no uv installed
Verify installation completes without ensure-uv failure
Confirm bundled uv is invoked correctly during setup
Validate no regression on systems where uv is already present
Run python util/lint.py --all
Run pytest tests/unit/

Checklist

I have linked a GitHub issue above (Closes #N / Fixes #N / Refs #N).
I have described why this change is being made, not just what changed.
I have run linting and tests locally (python util/lint.py --all, pytest tests/unit/).
I have updated documentation if user-visible behavior changed

… rescue installer and 'Install uv' UI

theonlychant · 2026-05-06T17:18:41Z

@itomek @kovtcharov-amd since it seems like you guys are working on your patch for mac should I edit the PR title for windows only or something and change the yml file?

itomek · 2026-05-06T17:23:30Z

@itomek @kovtcharov-amd since it seems like you guys are working on your patch for mac should I edit the PR title for windows only or something and change the yml file?

yes please; also I just tested this in the scenario where this is break and it definitely fixed the problem, so great work, and thank you!

One thing to note is is the Acceptance Criteria on the issue, we have to test this: #966

…anges for follow-up

theonlychant · 2026-05-06T17:46:21Z

@itomek @kovtcharov-amd since it seems like you guys are working on your patch for mac should I edit the PR title for windows only or something and change the yml file?

yes please; also I just tested this in the scenario where this is break and it definitely fixed the problem, so great work, and thank you!

One thing to note is is the Acceptance Criteria on the issue, we have to test this: #966

ok you can review the changes I did just now

itomek

Great work @theonlychant ! Thanks again!

kovtcharov-amd · 2026-05-06T19:07:39Z

@claude review this PR.

github-actions · 2026-05-06T19:10:07Z

Thanks @theonlychant — confirming this fixes the broken ensure-uv on a clean Windows box is genuinely valuable, and the dual approach (bundle + packaged-rescue + one-click "Install uv" button) is a good user experience. Review below; nothing scary, but a few things worth tightening before merge.

🟡 Important

1. No SHA256 verification for the bundled uv.exe (supply-chain regression).
The Linux step in .github/workflows/build-installers.yml:213-230 pins and verifies UV_SHA256 on download. The new Windows step at build-installers.yml:232-257 downloads the zip but does not verify its SHA — and the runtime then sees BUNDLED_UV_SHA256["win-x64"] = null in backend-installer.cjs:189 and explicitly skips verification at runtime too (backend-installer.cjs:704-712, 851-865). Net result: a packaged Windows installer can ship an unverified uv.exe. That conflicts with CLAUDE.md's "No Silent Fallbacks — Fail Loudly" rule and weakens the existing Linux story.

Suggested fix:

Pin a real UV_SHA256 in the workflow (verify on download with sha256sum -c, like the Linux step does).
Populate BUNDLED_UV_SHA256["win-x64"] in backend-installer.cjs with the SHA of the extracted uv.exe (not the zip), so the runtime check stays meaningful.
Drop the if (expected) { … } else { log warning } softening in installBundledUv and ensureUv — once the SHAs are populated, missing-checksum should remain a hard error like it was before.

2. CI step soft-fails on download error.
Fetch uv binary (Windows) uses || true after unzip/find and prints "continuing without bundling" on curl failure (build-installers.yml:244-256). This means a network blip during release builds silently produces an installer with no bundled uv.exe, which is exactly the regression #966 is fixing. The Linux step intentionally fails the build on download error — Windows should match. Drop the || true swallows and let set -euo pipefail do its job.

3. Indentation inconsistency in the rescue block.
The new packaged-Windows rescue path at backend-installer.cjs:944-988 is indented at 4 spaces while the surrounding function uses 2 spaces. Prettier/eslint in this repo is likely to flag it. Quick re-format will fix.

🟢 Minor

4. mac-arm64 key still present in BUNDLED_UV_SHA256.
The latest commit (e396416f) intentionally scopes this PR to Windows only, but backend-installer.cjs:192-193 still adds "mac-arm64": null. Since there's no mac fetch step and no mac runtime path being touched here, that key is dead weight — consider removing it and adding it back in the follow-up macOS PR with a real SHA, alongside the matching workflow step.

5. "Install uv (auto)" button actually runs the full backend install.
In backend-installer-progress-dialog.cjs:376-396 the case 0 handler calls installer.ensureBackend(...), which provisions uv plus lemonade, venv, and pip deps. The button label ("Install uv (auto)") understates what's happening — users may be confused if it takes minutes. Consider relabelling to "Retry install (auto)" or "Re-run install" so the label matches the action.

6. PR description out of date.
The body still says "Bundle uv for Windows (x64) and macOS (arm64)" and lists mac-arm64 in Changes, but commit e396416f restricted scope to Windows. Worth updating the description so reviewers/changelog readers don't get the wrong impression.

7. Test plan unchecked items.
The acceptance criteria on #966 specifically calls for an end-to-end test on a clean Windows machine. The four unchecked boxes ("Run installer on a clean system", "Confirm bundled uv is invoked correctly", "Validate no regression on systems where uv is already present", "Run linting/tests") are exactly the ones reviewers care about most. @itomek already confirmed the breaking-scenario repro is fixed — once linting and the no-regression case are checked, this is much easier to land.

✅ Things that look good

Loop-back failure dialog so Copy/Open log doesn't drop the user out of the flow — nice UX improvement.
Packaged-Windows PowerShell rescue with PATH augmentation for ~/.local/bin and ~/.cargo/bin is sensible defence-in-depth.
New error message at backend-installer.cjs:1001-1008 is much more actionable than the previous one (names what failed, what to do, and points at the in-app rescue).

Net: solid fix for a real first-run-broken bug. The main blocker IMO is the supply-chain weakening (item 1) — once SHAs are pinned and the soft-fail in CI is removed, this is ready. cc @kovtcharov-amd for sign-off on the supply-chain bits given the security implications.

theonlychant · 2026-05-06T19:58:40Z

@itomek @kovtcharov-amd recheck this when you're free

theonlychant · 2026-05-06T21:27:21Z

@itomek I resolved the conflicts on this branch just now

… smoke

theonlychant · 2026-05-07T07:28:34Z

@kovtcharov-amd you can merge this whenever you're available

itomek

@theonlychant — one blocker before this lands. The latest commit (d932c7d) adds a macOS uv fetch step + mac-arm64 SHA wiring, but I already shipped that work to main about an hour earlier via #967 (commit 7b13352, merged 21:13:30Z; your commit landed 22:10:57Z). PR #967 also adds a dmg-structural-smoke CI job + tests/electron/dmg-smoke.test.mjs (202 lines) + an installer-smoke.mjs helper (129 lines) — none of which this PR has — so the macOS coverage on main is materially more complete than what d932c7d adds.

Net effect today: this branch will conflict with main on build-installers.yml and backend-installer.cjs's BUNDLED_UV_SHA256 map, and even after a clean resolution we'd be choosing between two different macOS fixes for no benefit.

Ask

Rebase onto current main. git fetch origin && git rebase origin/main.
Drop the macOS changes from this PR — specifically the contents of d932c7d (the mac-arm64 entry in BUNDLED_UV_SHA256 and the macOS fetch step in the workflow). Those are now redundant with #967.
Keep this PR strictly Windows-only. The title already says bundle uv for win-x64; packaged Windows rescue installer, so dropping the mac additions also realigns title/description with the diff.
Update the description. The body still lists mac-arm64 under Changes — drop that bullet so reviewers aren't expecting mac work here.

The Windows portion of this PR (Windows fetch step, packaged Windows rescue installer, dialog UX improvements) is genuinely useful and not duplicative of anything on main — happy to re-review and approve that scope as soon as the rebase is in. Thanks for the work.

…md#975) ## Why this matters PR amd#968 landed with a stale comment in [build-installers.yml](.github/workflows/build-installers.yml) that claims the macOS uv fetch step was \"removed in this PR to keep changes Windows-only\" — but the step is sitting right above the comment. The comment is a leftover from PR amd#968's merge resolution: when main was merged into the PR branch, the macOS step came back (PR amd#967 had added it), but the orphan comment from an earlier Windows-only sub-commit survived. After the squash-merge it now lies on main. Before: workflow file contains a self-contradicting comment that misleads anyone touching this section in the future (\"why does the comment say it's removed when it's right there?\"). After: comment is gone, file matches reality. No functional change — comment-only edit. ## Test plan - [x] \`grep \"macOS uv fetch removed\" .github/workflows/build-installers.yml\` returns nothing - [x] Diff is comment-only (3 deletions, 0 functional changes)

@theonlychant

## Why this matters Ships the v0.17.6 patch: a new Email Triage Agent with Gmail (every email body stays on local Lemonade), the OAuth PKCE foundation that backs it, settings UI card layout, and a sweep of installer fixes that close the remaining first-launch failures uncovered after v0.17.5. Custom Python agents that follow the template's `super().__init__(**kwargs)` pattern no longer crash on the first message in the Agent UI. Full notes: `docs/releases/v0.17.6.mdx`. ## What's New - **Email Triage Agent with Gmail** ([amd#965](amd#965)) — `EmailTriageAgent` with 25 tools across read / organize / reply / delete / calendar mixins. Every email body processed locally on Lemonade; seven destructive tools confirmation-gated; three layers of prompt-injection defense; SQLite undo log via `DatabaseMixin`. - **OAuth PKCE foundation for Google connections** ([amd#926](amd#926)) — Self-contained `gaia.connections` module: refresh tokens in the OS keychain (Keychain / DPAPI / SecretService), per-agent grants in `~/.gaia/connections/grants.json`, async token cache with refresh rotation. Baseline for the v0.17.7 connectors framework. - **Settings UI card layout** ([amd#969](amd#969)) — Outlined cards with accent left-stripe replace margin-separated blocks across all settings sections; light + dark themes both updated. ## Bug Fixes - **Custom Python agents crashed on first message** ([amd#974](amd#974), closes [amd#973](amd#973)) — `python_factory` now introspects the target class's `__init__` chain and only forwards kwargs the chain accepts, so the bare `super().__init__(**kwargs)` template pattern no longer crashes with `unexpected keyword argument 'rag_documents'`. - **Windows installer failed at `ensure-uv`** ([amd#968](amd#968), closes [amd#966](amd#966)) — `uv` binary now bundled for `win-x64`; packaged Windows rescue installer included. - **macOS installer failed at `ensure-uv` on clean Apple Silicon** ([amd#967](amd#967), closes [amd#941](amd#941)) — Pinned `uv` v0.5.14 (`aarch64-apple-darwin`) shipped in the DMG; new `dmg-structural-smoke` CI job blocks future drift. - **AppImage users hit `gaia: command not found`** ([amd#942](amd#942), closes [amd#782](amd#782)) — Startup writes a `~/.local/bin/gaia` shim so `gaia` is on PATH after first launch (skips creation if already present). - **Windows fell back to Qwen instead of Gemma 4 default** ([amd#949](amd#949), closes [amd#948](amd#948)) — Model-resolution logic fixed so Gemma loads correctly on Windows. ## Tooling & Docs - **`gaia-release` skill** ([amd#939](amd#939)) — Phased release flow with hard gates before every irreversible step; encodes the manual pre-tag verification that caught two release-blocking bugs in v0.17.4. - **Internal-task issue template** ([amd#906](amd#906)) — Third issue template for agent-assignable internal work. - **Outlook via Power Automate plan** ([amd#954](amd#954)) — Enterprise-bypass spec for v0.17.7 Outlook integration. - **PR description guidance sharpened** ([amd#947](amd#947)) — `CLAUDE.md` "tight and value-focused" rule with anti-patterns. - **Stale `macOS uv fetch removed` orphan comment removed** ([amd#975](amd#975)). ## Thanks External contributors in this release: - [@theonlychant](https://github.com/theonlychant) — installer fixes ([amd#968](amd#968), [amd#942](amd#942), [amd#949](amd#949)) - [@BlueriteSoul](https://github.com/BlueriteSoul) — reported AppImage `gaia: command not found` ([amd#782](amd#782)) - [@nuts23](https://github.com/nuts23) — reported Windows Gemma/Qwen fallback ([amd#948](amd#948)) ## Release checklist - [x] `util/validate_release_notes.py docs/releases/v0.17.6.mdx --tag v0.17.6` passes - [x] `src/gaia/version.py` → `0.17.6` - [x] `src/gaia/apps/webui/package.json` → `0.17.6` - [x] Navbar label in `docs/docs.json` → `v0.17.6 · Lemonade 10.2.0` - [x] All 14 commits in the range (v0.17.5..HEAD) are represented in the notes - [ ] Review from @kovtcharov-amd addressed

fix(installer): bundle uv for win-x64/mac-arm64; add packaged Windows…

1eeb80a

… rescue installer and 'Install uv' UI

theonlychant requested a review from kovtcharov-amd as a code owner May 6, 2026 16:32

github-actions Bot added the devops DevOps/infrastructure changes label May 6, 2026

theonlychant mentioned this pull request May 6, 2026

Windows desktop installer fails at ensure-uv for any user without uv already on PATH (no bundled uv shipped for win-x64) #966

Closed

itomek added this to the v0.17.6 — Website launch and RAG/UX polish [OSS] milestone May 6, 2026

theonlychant changed the title ~~fix(installer): bundle uv for win-x64/mac-arm64; add packaged Windows…~~ fix(installer): bundle uv for win-x64; packaged Windows rescue installer May 6, 2026

ci(installer): restrict uv fetch to Windows in this PR; keep macOS ch…

e396416

…anges for follow-up

itomek self-assigned this May 6, 2026

itomek previously approved these changes May 6, 2026

View reviewed changes

fix(installer): bundle uv for win-x64 and enforce SHA256 verification

3c50182

theonlychant dismissed itomek’s stale review via 3c50182 May 6, 2026 19:58

theonlychant added 2 commits May 6, 2026 15:26

fix(installer): add uv.exe SHA256 verification for win-x64 bundle

1597742

ci(installer): pin Windows uv tarball SHA and embed extracted uv.exe SHA

4804fb0

github-actions Bot added tests Test changes electron Electron app changes labels May 6, 2026

theonlychant force-pushed the fix/windows-uv-bundling branch from bdcdd41 to 4804fb0 Compare May 6, 2026 21:29

theonlychant and others added 2 commits May 6, 2026 16:39

Merge branch 'main' into fix/windows-uv-bundling

6a5a8e3

ci(installer): add macOS uv fetch + set mac-arm64 bundled SHA for DMG…

d932c7d

… smoke

itomek enabled auto-merge May 6, 2026 23:17

itomek requested changes May 7, 2026

View reviewed changes

itomek approved these changes May 7, 2026

View reviewed changes

itomek added this pull request to the merge queue May 7, 2026

Merged via the queue into amd:main with commit 7df8f94 May 7, 2026
28 checks passed

This was referenced May 7, 2026

ci(installer): remove stale 'macOS uv fetch removed' orphan comment #975

Merged

Release v0.17.6 #980

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(installer): bundle uv for win-x64; packaged Windows rescue installer#968

fix(installer): bundle uv for win-x64; packaged Windows rescue installer#968
itomek merged 7 commits intoamd:mainfrom
theonlychant:fix/windows-uv-bundling

theonlychant commented May 6, 2026 •

edited

Loading

Uh oh!

theonlychant commented May 6, 2026

Uh oh!

itomek commented May 6, 2026

Uh oh!

theonlychant commented May 6, 2026

Uh oh!

itomek left a comment

Uh oh!

kovtcharov-amd commented May 6, 2026

Uh oh!

github-actions Bot commented May 6, 2026

Uh oh!

theonlychant commented May 6, 2026 •

edited

Loading

Uh oh!

theonlychant commented May 6, 2026

Uh oh!

theonlychant commented May 7, 2026 •

edited

Loading

Uh oh!

itomek left a comment •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

theonlychant commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why

Linked issue

Changes

Test plan

Checklist

Uh oh!

theonlychant commented May 6, 2026

Uh oh!

itomek commented May 6, 2026

Uh oh!

theonlychant commented May 6, 2026

Uh oh!

itomek left a comment

Choose a reason for hiding this comment

Uh oh!

kovtcharov-amd commented May 6, 2026

Uh oh!

github-actions Bot commented May 6, 2026

🟡 Important

🟢 Minor

✅ Things that look good

Uh oh!

theonlychant commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

theonlychant commented May 6, 2026

Uh oh!

theonlychant commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

itomek left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Ask

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

theonlychant commented May 6, 2026 •

edited

Loading

theonlychant commented May 6, 2026 •

edited

Loading

theonlychant commented May 7, 2026 •

edited

Loading

itomek left a comment •

edited

Loading