feat(agents-desktop): wire electron-updater for update notifications (#4441)

## Summary

Phase 1 of desktop autoupdate — integrates
[`electron-updater`](https://www.electron.build/auto-update) so users
can be notified about new releases. Designed to be the first half of a
two-phase rollout:

- **Phase 1 (this PR):** notification + update download on
Windows/Linux; notify-only on macOS (no auto-install).
- **Phase 2 (follow-up):** Developer ID signing + notarization in CI,
then flip `MAC_AUTO_INSTALL_SUPPORTED = true` in `updater.ts` and macOS
upgrades become automatic too.

### What ships in this PR

- **`electron-updater` integration** in a new `src/app/updater.ts`
module.
- **"Check for Updates…" menu items** are now functional — the existing
disabled placeholder in the app-icon menu, plus new entries in the
Electric Agents menu (macOS) and Help menu (Windows/Linux).
- **Background check on launch** (10s after window comes up) and
unlimited manual checks via the menu.
- **Dock progress bar** during downloads on signed platforms so manual
download clicks give immediate feedback.

### macOS notify-only fallback (until phase 2)

Squirrel.Mac requires a Developer ID signature to swap the bundle, so on
unsigned macOS we behave as a notifier:
- "Check for Updates…" → dialog: "Version X available — Open releases
page / Later"
- Auto check stays silent so it doesn't pop dialogs while users are
mid-task
- **No download is performed** — the file would just be discarded, and
the user has to grab it from the browser anyway

When phase 2 lands, signed macOS users get the same full flow as
Windows/Linux without further code changes.

### Update channel topology

- **Switched publish provider from `github` to `generic`** pointed at
the moving `agents-desktop-latest` tag. The GitHub provider was picking
up the wrong release because `electric-sql/electric` publishes many
packages to the same Releases page (changesets-style) and GitHub's
"latest" marker tracks whichever package was published most recently —
which is rarely the desktop app.
- **Canary builds get full separation** — CI passes `-c.channel=beta`
and overrides `-c.publish.url=…agents-desktop-canary`. Canary builds
emit `beta-*.yml` metadata and ship apps that fetch from the canary tag,
so stable users never accidentally upgrade to canaries.
- **Canary asset publishing** also now uploads the `*.yml` and blockmap
metadata alongside the existing renamed predictable-name copies (the
renames break what the updater metadata references, so we need both).

### Files touched

| File | Change |
| --- | --- |
| `packages/agents-desktop/package.json` | adds
`electron-updater@^6.3.9` |
| `packages/agents-desktop/vite.config.ts` | externalizes
`electron-updater` |
| `packages/agents-desktop/src/app/updater.ts` *(new)* | full updater
module |
| `packages/agents-desktop/src/app/controller.ts` | instantiates
updater, exposes `initializeUpdater` + `checkForUpdates` |
| `packages/agents-desktop/src/main.ts` | calls `initializeUpdater()`
after window is up |
| `packages/agents-desktop/src/ui/application-menu.ts` | enables the
existing placeholder + adds Help menu entry |
| `packages/agents-desktop/electron-builder.yml` | switches publish
provider to `generic` |
| `.github/workflows/agents_desktop_build.yml` | canary channel
separation + metadata upload |

## Followups (not in this PR)

1. **Canary versioning.** Today every canary builds as `0.1.10` because
the workflow's `version: canary-${{ github.run_number }}-${{ github.sha
}}` input isn't injected into `package.json`. Auto-update version
compare won't trigger between canaries until we wire a real semver
prerelease version like `0.1.11-canary.N` into the build.
2. **Phase 2: signing + notarization.** Apple Developer ID cert,
notarization credentials, and GitHub Actions secrets (`CSC_LINK`,
`CSC_KEY_PASSWORD`, plus notarization). Then flip the
`MAC_AUTO_INSTALL_SUPPORTED` constant.

## Test plan

- [x] Local typecheck + production build pass
- [x] Smoke-tested end-to-end on macOS by temporarily downgrading
`package.json` version to `0.0.1` and rebuilding: the app correctly
fetched `latest-mac.yml` from the `agents-desktop-latest` tag, detected
`0.1.10` as available, showed the "Open releases page" dialog
(notify-only path), and re-checking shows the dialog again as expected
- [x] Background auto-check at +10s does not pop a duplicate dialog when
the manual dialog is dismissed (notifier-mode auto checks stay silent)
- [x] Windows installer build picks up `electron-updater` (CI will
exercise this)
- [ ] Linux AppImage build picks up `electron-updater` (CI will exercise
this)
- [ ] First post-merge stable release populates
`agents-desktop-latest/latest-mac.yml` and a subsequent stable upgrade
triggers the "update available" prompt for real users

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: kevin-dp

.changeset/desktop-autoupdate-notifications.md

@@ -0,0 +1,23 @@
+---
+"@electric-ax/agents-desktop": patch
+---
+
+Wire `electron-updater` so the desktop app can detect new releases. Phase
+one of two:
+
+* Adds a working **Check for Updates…** menu item (Electric Agents menu
+  on macOS, Help menu on Windows/Linux, plus the in-window app-icon
+  menu) and a quiet background check ~10s after launch.
+* On Windows/Linux, signed-platform flow is wired end-to-end: downloads
+  in the background with a dock/taskbar progress bar, then prompts
+  "Restart now" to apply via `quitAndInstall()`.
+* On macOS, ships as **notify-only** until Developer ID signing lands —
+  Squirrel.Mac can't swap an unsigned bundle, so we skip the download
+  entirely and prompt to open the GitHub releases page instead.
+* Switches the publish provider from `github` to `generic` pointed at
+  the moving `agents-desktop-latest` tag, because the repo's overall
+  "latest" release is shared across packages and the GitHub provider
+  was picking the wrong one.
+* Adds channel separation so canary builds publish to the `beta`
+  channel against an `agents-desktop-canary` URL — stable users never
+  auto-update to canaries.

.github/workflows/agents_desktop_build.yml

@@ -254,15 +254,29 @@ jobs:
           if [[ "${{ inputs.sign }}" != "true" ]]; then
             builder_args+=("-c.mac.identity=-")
           fi
+          if [[ "${{ inputs.channel }}" == "canary" ]]; then
+            builder_args+=("-c.channel=beta")
+            builder_args+=("-c.publish.url=https://github.com/electric-sql/electric/releases/download/agents-desktop-canary")
+          fi
 
           pnpm --filter @electric-ax/agents-desktop exec electron-builder "${builder_args[@]}" --publish never
 
       - name: Package desktop app
         if: ${{ matrix.id != 'macos' }}
+        shell: bash
         env:
           CSC_IDENTITY_AUTO_DISCOVERY: ${{ inputs.sign && 'true' || 'false' }}
           GH_TOKEN: ${{ github.token }}
-        run: pnpm --filter @electric-ax/agents-desktop exec electron-builder ${{ matrix.builder_args }} --publish never
+        run: |
+          set -euo pipefail
+
+          builder_args=(${{ matrix.builder_args }})
+          if [[ "${{ inputs.channel }}" == "canary" ]]; then
+            builder_args+=("-c.channel=beta")
+            builder_args+=("-c.publish.url=https://github.com/electric-sql/electric/releases/download/agents-desktop-canary")
+          fi
+
+          pnpm --filter @electric-ax/agents-desktop exec electron-builder "${builder_args[@]}" --publish never
 
       - name: Verify macOS app signatures
         if: ${{ matrix.id == 'macos' }}
@@ -539,6 +553,13 @@ jobs:
             exit 1
           }
 
+          # Always include the original artifacts + electron-updater metadata
+          # (latest*.yml / beta*.yml + .blockmap files). The updater expects
+          # the filenames referenced in the yml; renamed copies are added on
+          # top for canary so users get stable "latest canary" download URLs.
+          cp packages/agents-desktop/release/*.{dmg,zip,exe,AppImage,deb,blockmap,yml,yaml} \
+            packages/agents-desktop/publish-assets/ 2>/dev/null || true
+
           if [[ "$CHANNEL" == "canary" ]]; then
             case "$MATRIX_ID" in
               macos)
@@ -555,9 +576,6 @@ jobs:
                 copy_first "Electric-Agents-canary-linux-x64.deb" packages/agents-desktop/release/*.deb
                 ;;
             esac
-          else
-            cp packages/agents-desktop/release/*.{dmg,zip,exe,AppImage,deb,blockmap,yml,yaml} \
-              packages/agents-desktop/publish-assets/ 2>/dev/null || true
           fi
 
           assets=(packages/agents-desktop/publish-assets/*)

packages/agents-desktop/electron-builder.yml

@@ -73,6 +73,13 @@ linux:
         - x64
 
 publish:
-  provider: github
-  owner: electric-sql
-  repo: electric
+  # Using `generic` (not `github`) because the electric-sql/electric repo
+  # publishes many packages to the same Releases page (changesets-style).
+  # GitHub's "latest" marker tracks whichever release was most recently
+  # tagged across all packages, so the `github` provider grabs the wrong
+  # release and can't find latest-mac.yml.
+  # Instead we point at the moving `agents-desktop-latest` tag that the
+  # release workflow maintains specifically for desktop stable builds.
+  # Canary builds override `url` to `agents-desktop-canary` at build time.
+  provider: generic
+  url: 'https://github.com/electric-sql/electric/releases/download/agents-desktop-latest'

packages/agents-desktop/package.json

@@ -32,6 +32,7 @@
     "better-sqlite3": "^12.9.0",
     "dockerode": "^5.0.0",
     "e2b": ">=2.0.0",
+    "electron-updater": "^6.3.9",
     "fix-path": "^4.0.0",
     "jsdom": "^28.1.0",
     "pino": "^10.3.1",

packages/agents-desktop/src/app/controller.ts

@@ -2,6 +2,7 @@ import { BrowserWindow } from 'electron'
 import type { DesktopAppContext } from './context'
 import * as AppLifecycle from './lifecycle'
 import * as LoginItems from './login-items'
+import { createDesktopUpdater } from './updater'
 import * as CloudAuthInjection from '../cloud/auth-injection'
 import * as ServerFetch from '../cloud/server-fetch'
 import { createCredentialsController } from '../credentials/controller'
@@ -305,12 +306,20 @@ export function createDesktopMainController(ctx: DesktopAppContext) {
     AppLifecycle.applyNativeAppearance(ctx, appearance)
   }
 
+  const updater = createDesktopUpdater({
+    showOrCreateWindow,
+  })
+
+  const checkForUpdates = (): Promise<void> =>
+    updater.checkForUpdates({ triggeredManually: true })
+
   const applicationMenuDeps: ApplicationMenu.ApplicationMenuDeps = {
     windows,
     createWindow,
     sendCommand,
     quitApp,
     showAboutDialog,
+    checkForUpdates,
   }
 
   function showAboutDialog(): void {
@@ -345,7 +354,11 @@ export function createDesktopMainController(ctx: DesktopAppContext) {
     win: BrowserWindow,
     bounds: DesktopMenuPopupBounds
   ): void => {
-    ApplicationMenu.popupAppIconMenu({ showAboutDialog }, win, bounds)
+    ApplicationMenu.popupAppIconMenu(
+      { showAboutDialog, checkForUpdates },
+      win,
+      bounds
+    )
   }
 
   const desktopIpcDeps: DesktopIpc.RegisterDesktopIpcDeps = {
@@ -473,6 +486,7 @@ export function createDesktopMainController(ctx: DesktopAppContext) {
     syncLaunchAtLoginSetting,
     connectConfiguredServers,
     startDiscoveryLoop: localDiscovery.startDiscoveryLoop,
+    initializeUpdater: updater.initialize,
     quitApp,
   }
 }