feat(desktop): background auto-download updates (#1020)

* feat(desktop): background auto-download updates on Mac and Windows

- Webview preload: expose nexuUpdater bridge so web app receives update
  events (fixes #1006, #1008)
- Windows: rewrite update driver for in-app download with progress
  events, rate limiting (1MB/s background), SHA256 verification, and
  exe-launch install
- UpdateManager: add background/foreground download mode — silently
  download after periodic check, only show UI when complete or when
  user manually checks
- Mac: enable electron-updater autoDownload for silent background
  download
- Fix quitAndInstall gate to allow external-installer apply mode
- Fix desktop shell and web app install guards for external-installer

* fix(desktop): fix checking state stuck when user-initiated check meets auto-download

The onAvailable and onError handlers suppressed all events when
autoDownload was enabled, but this also blocked user-initiated checks
from ever exiting the "checking" phase. Add a userInitiatedCheck flag
so manual checks always deliver events to the renderer while periodic
checks still suppress UI and download silently.

Also refine the background download surfacing: when user clicks "Check
for updates" during a background download, show the "available" state
(version + Install button) instead of immediately showing download
progress, letting the user decide whether to proceed.

* fix(desktop): enable periodic checks for local-test-feed and reduce Windows initial delay

- shouldStartDesktopPeriodicUpdateChecks now returns true for
  local-test-feed experience, so local validation builds with a
  configured feed URL also run periodic update checks
- Reduce Windows initial delay from 45s to 30s

* fix(desktop): hide duplicate UpdateBanner in immersive mode and add dismiss to ready state

- Hide UpdateBanner in immersive mode (packaged app) since the web
  app's UpdateFloatCard handles user-facing update UI
- Add close button and "Later" option to the UpdateFloatCard ready
  state so users can dismiss the notification

* feat(desktop): add update:get-status IPC so settings page reflects background download state

When the settings page mounts after a background download has already
completed, it now queries the current update status via the new
update:get-status IPC channel and immediately shows "Install" instead
of "Check now".

* chore(desktop): improve local auto-update validation

* fix(desktop): tighten background update flows

---------

Co-authored-by: mashu <chizblank@gmail.com>

Author: lefarcen

apps/desktop/main/index.ts

@@ -1755,7 +1755,8 @@ app.whenReady().then(async () => {
       const updateMgr = new UpdateManager(win, orchestrator, {
         channel: runtimeConfig.updates.channel,
         feedUrl: runtimeConfig.urls.updateFeed,
-        initialDelayMs: process.platform === "win32" ? 45_000 : 0,
+        autoDownload: true,
+        initialDelayMs: process.platform === "win32" ? 30_000 : 0,
         prepareForUpdateInstall: runtimeLifecycle.prepareForUpdateInstall
           ? async (args: PrepareForUpdateInstallArgs) => {
               await runtimeLifecycle.prepareForUpdateInstall?.(args);

apps/desktop/main/ipc.ts

@@ -744,7 +744,7 @@ export function registerIpcHandlers(
           if (!updateManager) {
             return { updateAvailable: false };
           }
-          return updateManager.checkNow();
+          return updateManager.checkNow({ userInitiated: true });
         }
 
         case "update:get-capability": {
@@ -781,6 +781,13 @@ export function registerIpcHandlers(
           return { version: app.getVersion() };
         }
 
+        case "update:get-status": {
+          if (!updateManager) {
+            return { phase: "idle", version: null };
+          }
+          return updateManager.getStatus();
+        }
+
         case "update:set-channel": {
           const typedPayload =
             payload as HostInvokePayloadMap["update:set-channel"];

apps/desktop/main/updater/update-manager.ts

@@ -22,6 +22,8 @@ import { UnsupportedUpdateDriver } from "./unsupported-update-driver";
 import type { PlatformUpdateDriver } from "./update-driver";
 import { WindowsUpdateDriver } from "./windows-update-driver";
 
+type DownloadMode = "idle" | "background" | "foreground";
+
 export interface UpdateManagerOptions {
   source?: UpdateSource;
   channel?: UpdateChannelName;
@@ -104,6 +106,14 @@ export class UpdateManager {
   private currentFeedUrl: string;
   private readonly platform: NodeJS.Platform;
   private readonly driver: PlatformUpdateDriver;
+  private readonly autoDownload: boolean;
+  private downloadMode: DownloadMode = "idle";
+  private pendingVersion: string | null = null;
+  private pendingReleaseDate: string | undefined = undefined;
+  private pendingReleaseNotes: string | undefined = undefined;
+  private pendingActionUrl: string | undefined = undefined;
+  private downloadComplete = false;
+  private userInitiatedCheck = false;
   private checkInProgress: Promise<{ updateAvailable: boolean }> | null = null;
   private lastProgressLogAt = 0;
   private lastProgressLogPercent: number | null = null;
@@ -125,6 +135,7 @@ export class UpdateManager {
     this.initialDelayMs = options?.initialDelayMs ?? 0;
     this.launchdCtx = options?.launchd;
     this.options = options;
+    this.autoDownload = options?.autoDownload ?? false;
     this.platform = options?.platform ?? process.platform;
     this.driver = createUpdateDriver(
       this.platform,
@@ -159,6 +170,22 @@ export class UpdateManager {
     return this.driver.capability;
   }
 
+  getStatus(): {
+    phase: "idle" | "downloading" | "ready";
+    version: string | null;
+  } {
+    if (this.downloadComplete) {
+      return { phase: "ready", version: this.pendingVersion };
+    }
+    if (
+      this.downloadMode === "background" ||
+      this.downloadMode === "foreground"
+    ) {
+      return { phase: "downloading", version: this.pendingVersion };
+    }
+    return { phase: "idle", version: null };
+  }
+
   private getDiagnostic(partial?: {
     remoteVersion?: string;
     remoteReleaseDate?: string;
@@ -197,6 +224,42 @@ export class UpdateManager {
           remoteReleaseDate: info.releaseDate,
         });
         this.logCheck("update event: update available", diagnostic);
+
+        // Always store pending info for later surfacing
+        this.pendingVersion = info.version;
+        this.pendingReleaseDate = info.releaseDate;
+        this.pendingReleaseNotes = info.releaseNotes;
+        this.pendingActionUrl = info.actionUrl;
+
+        if (this.autoDownload && !this.userInitiatedCheck) {
+          // Periodic check: suppress UI, start downloading silently
+          this.downloadMode = "background";
+          this.logCheck(
+            "auto-download: starting background download",
+            diagnostic,
+          );
+
+          // On Windows, trigger download manually (Mac electron-updater
+          // auto-downloads when autoDownload is true)
+          if (this.platform === "win32") {
+            void this.driver.downloadUpdate();
+          }
+          return;
+        }
+
+        // User-initiated check: always send the event so the renderer
+        // can exit "checking" state. Background download still proceeds.
+        if (this.autoDownload) {
+          this.downloadMode = "background";
+          this.logCheck(
+            "auto-download: user-initiated check, sending available event and starting background download",
+            diagnostic,
+          );
+          if (this.platform === "win32") {
+            void this.driver.downloadUpdate();
+          }
+        }
+
         this.send("update:available", {
           version: info.version,
           releaseNotes: info.releaseNotes,
@@ -228,6 +291,12 @@ export class UpdateManager {
             this.getDiagnostic(),
           );
         }
+
+        // Suppress progress events during background download
+        if (this.downloadMode === "background") {
+          return;
+        }
+
         this.send("update:progress", {
           percent: progress.percent,
           bytesPerSecond: progress.bytesPerSecond,
@@ -243,11 +312,29 @@ export class UpdateManager {
             remoteReleaseDate: info.releaseDate,
           }),
         );
+        this.downloadMode = "idle";
+        this.downloadComplete = true;
+        // Always notify renderer when download completes
         this.send("update:downloaded", { version: info.version });
       },
       onError: (error) => {
         const diagnostic = this.getDiagnostic();
         this.logCheck(`update error: ${error.message}`, diagnostic);
+
+        if (this.downloadMode === "background" && !this.userInitiatedCheck) {
+          // Suppress error UI during background-only download
+          this.logCheck(
+            "auto-download: background download failed, suppressing UI error",
+            diagnostic,
+          );
+          this.downloadMode = "idle";
+          return;
+        }
+
+        if (this.downloadMode === "background") {
+          this.downloadMode = "idle";
+        }
+
         this.send("update:error", { message: error.message, diagnostic });
       },
     });
@@ -267,9 +354,51 @@ export class UpdateManager {
     }
   }
 
-  async checkNow(): Promise<{ updateAvailable: boolean }> {
+  async checkNow(options?: {
+    userInitiated?: boolean;
+  }): Promise<{ updateAvailable: boolean }> {
     const startedAt = Date.now();
+    this.userInitiatedCheck = options?.userInitiated ?? false;
     this.logCheck("update check start", this.getDiagnostic());
+
+    // If background download already completed, surface it immediately
+    if (this.downloadComplete && this.pendingVersion) {
+      this.logCheck(
+        "update check: background download already complete, surfacing",
+        this.getDiagnostic(),
+      );
+      // Brief "checking" flash so the settings button shows a transition
+      this.send("update:checking", this.getDiagnostic());
+      this.send("update:downloaded", { version: this.pendingVersion });
+      return { updateAvailable: true };
+    }
+
+    // If background download is in progress, show "available" with version
+    // info but keep downloading in the background. User can decide whether
+    // to install — clicking Install will switch to foreground mode with
+    // visible progress.
+    if (this.downloadMode === "background" && this.pendingVersion) {
+      this.logCheck(
+        "update check: background download in progress, surfacing available state",
+        this.getDiagnostic(),
+      );
+
+      // Brief "checking" flash so the settings button shows a transition
+      this.send("update:checking", this.getDiagnostic());
+
+      const diagnostic = this.getDiagnostic({
+        remoteVersion: this.pendingVersion,
+        remoteReleaseDate: this.pendingReleaseDate,
+      });
+      this.send("update:available", {
+        version: this.pendingVersion,
+        releaseNotes: this.pendingReleaseNotes,
+        actionUrl: this.pendingActionUrl,
+        diagnostic,
+      });
+      return { updateAvailable: true };
+    }
+
     if (this.checkInProgress) {
       this.logCheck(
         "update check skipped: already in progress",
@@ -306,6 +435,7 @@ export class UpdateManager {
         return { updateAvailable: false };
       } finally {
         this.checkInProgress = null;
+        this.userInitiatedCheck = false;
       }
     })();
 
@@ -324,6 +454,15 @@ export class UpdateManager {
       return { ok: false };
     }
 
+    // Switch to foreground mode and remove rate limit
+    this.downloadMode = "foreground";
+    if (
+      this.platform === "win32" &&
+      this.driver instanceof WindowsUpdateDriver
+    ) {
+      this.driver.setRateLimit(null);
+    }
+
     return this.driver.downloadUpdate();
   }
 
@@ -404,63 +543,61 @@ export class UpdateManager {
 
     logStep("phase 1 cleanup end");
 
-    // --- Phase 2: Process verification ---
-    // Two sweeps of SIGKILL to clear all Nexu sidecar processes. Uses both
-    // authoritative sources (launchd labels, runtime-ports.json) and pgrep.
-    const firstSweepStartedAt = Date.now();
-    let { clean, remainingPids } = await ensureNexuProcessesDead({
-      timeoutMs: 8_000,
-      intervalMs: 200,
-    });
-    this.logCheck(
-      `quit-and-install: first sweep complete in ${Date.now() - firstSweepStartedAt}ms (${clean ? "clean" : `survivors: ${remainingPids.join(", ")}`})`,
-      this.getDiagnostic(),
-    );
-
-    if (!clean) {
-      const secondSweepStartedAt = Date.now();
-      ({ clean, remainingPids } = await ensureNexuProcessesDead({
-        timeoutMs: 5_000,
+    // --- Phase 2 & 3: macOS-only process verification and lock check ---
+    // On Windows, the NSIS installer handles process detection itself.
+    if (this.platform === "darwin") {
+      // Two sweeps of SIGKILL to clear all Nexu sidecar processes. Uses both
+      // authoritative sources (launchd labels, runtime-ports.json) and pgrep.
+      const firstSweepStartedAt = Date.now();
+      let { clean, remainingPids } = await ensureNexuProcessesDead({
+        timeoutMs: 8_000,
         intervalMs: 200,
-      }));
+      });
       this.logCheck(
-        `quit-and-install: second sweep complete in ${Date.now() - secondSweepStartedAt}ms (${clean ? "clean" : `survivors: ${remainingPids.join(", ")}`})`,
+        `quit-and-install: first sweep complete in ${Date.now() - firstSweepStartedAt}ms (${clean ? "clean" : `survivors: ${remainingPids.join(", ")}`})`,
         this.getDiagnostic(),
       );
-    }
 
-    // --- Phase 3: Evidence-based install decision ---
-    // Even with surviving processes, the update may be safe if those
-    // processes don't hold file handles to critical update paths. Use
-    // lsof to check whether the .app bundle or extracted sidecar dirs
-    // are actually locked.
-    const lockCheckStartedAt = Date.now();
-    const { locked, lockedPaths } = await checkCriticalPathsLocked();
-    this.logCheck(
-      `quit-and-install: critical-path lock check complete in ${Date.now() - lockCheckStartedAt}ms (${locked ? `locked: ${lockedPaths.join(", ")}` : "unlocked"})`,
-      this.getDiagnostic(),
-    );
+      if (!clean) {
+        const secondSweepStartedAt = Date.now();
+        ({ clean, remainingPids } = await ensureNexuProcessesDead({
+          timeoutMs: 5_000,
+          intervalMs: 200,
+        }));
+        this.logCheck(
+          `quit-and-install: second sweep complete in ${Date.now() - secondSweepStartedAt}ms (${clean ? "clean" : `survivors: ${remainingPids.join(", ")}`})`,
+          this.getDiagnostic(),
+        );
+      }
 
-    if (locked) {
-      // Critical paths are held open — installing now would fail or
-      // corrupt the app. Skip this attempt; electron-updater will
-      // re-detect the pending update on next launch.
+      // Evidence-based install decision: check if critical paths are locked.
+      const lockCheckStartedAt = Date.now();
+      const { locked, lockedPaths } = await checkCriticalPathsLocked();
       this.logCheck(
-        `quit-and-install: ABORTING — critical paths still locked: ${lockedPaths.join(", ")}`,
+        `quit-and-install: critical-path lock check complete in ${Date.now() - lockCheckStartedAt}ms (${locked ? `locked: ${lockedPaths.join(", ")}` : "unlocked"})`,
         this.getDiagnostic(),
       );
-      return;
-    }
 
-    if (!clean) {
-      // Processes alive but no critical file handles — safe to proceed.
-      this.logCheck(
-        "quit-and-install: residual processes exist but no critical path locks, proceeding",
-        this.getDiagnostic(),
-      );
+      if (locked) {
+        this.logCheck(
+          `quit-and-install: ABORTING — critical paths still locked: ${lockedPaths.join(", ")}`,
+          this.getDiagnostic(),
+        );
+        return;
+      }
+
+      if (!clean) {
+        this.logCheck(
+          "quit-and-install: residual processes exist but no critical path locks, proceeding",
+          this.getDiagnostic(),
+        );
+      }
     }
 
-    if (this.driver.capability.applyMode !== "in-app") {
+    if (
+      this.driver.capability.applyMode !== "in-app" &&
+      this.driver.capability.applyMode !== "external-installer"
+    ) {
       this.logCheck(
         "quit-and-install skipped: capability disabled on this platform",
         this.getDiagnostic(),
@@ -470,7 +607,7 @@ export class UpdateManager {
 
     // Set force-quit flag so window close handlers don't intercept the exit
     (app as unknown as Record<string, unknown>).__nexuForceQuit = true;
-    logStep("triggering autoUpdater.quitAndInstall");
+    logStep("triggering update apply");
     await this.driver.applyUpdate();
   }