fix(desktop): wait for native update staging and verify installation

apps/desktop/README.md

@@ -194,6 +194,8 @@ Raw local file bytes are never exposed through the preload bridge and cannot be
 
 - `electron-updater` reads the deployment's `/api/desktop/update` feed; production resolves stable releases from `simstudioai/sim`, while dev/staging resolve prereleases from `simstudioai/sim-desktop-releases`. Artifact downloads go directly to GitHub and deltas use `.zip.blockmap`. Sim validates every candidate before starting its download. Developer ID builds installed under `/Applications` use a prompt (Restart and update / Later; Later installs on quit); other packaged builds offer a validated installer download — never forced mid-session. A staged or offered update keeps being re-checked on the normal cadence, and a newer release replaces it, so a shell left running across several releases installs the latest build in one restart instead of the stale one followed by another prompt.
 - Streams: production follows stable `X.Y.Z` releases, dev follows `-dev.N`, and staging follows `-staging.N`. The feed still recognizes legacy `-alpha.N`/`-beta.N` releases during migration.
+- Restart becomes available only after Squirrel confirms native staging. Replacing a staged update returns the UI to downloading; a failed transfer can retain the previous staged build, but a failure after the native feed is replaced requires a retry. Diagnostics record `update_downloaded` after native staging, `update_install` when an explicit restart is committed, and `update_install_result` on the next launch with the expected and installed versions. The staging checkpoint also covers updates installed on a normal quit.
+- `bun run test:e2e e2e/updater.spec.ts` exercises the real Electron process, MacUpdater, downloads, retries, and installation checkpoints. Native verification and bundle replacement are simulated. Set `DESKTOP_UPDATER_REPORT_PATH` to choose the JSON report path; by default it is included in Playwright's test results and uploaded by CI on failure.
 - Staged rollout: after publishing, edit `stagingPercentage: 10` into the release's `latest-mac.yml`, then raise as crash metrics stay clean.
 - Rollback: a pulled release must be superseded by a **higher** version — users on the broken build will not reinstall an equal one. (A blocked-versions kill-switch was removed as unwired dead code; reintroduce it in `updater.ts` if a remote config source ever exists to feed it.)
 - Ship the DMG and tell users to install to `/Applications` — App Translocation breaks Squirrel.Mac updates from quarantined paths.

apps/desktop/e2e/fixtures/updater.ts

@@ -0,0 +1,83 @@
+import { writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, relative } from 'node:path'
+import type { DesktopUpdateState } from '@sim/desktop-bridge'
+import { app, autoUpdater as nativeUpdater, net } from 'electron'
+import { MacUpdater } from 'electron-updater'
+import { initUpdater } from '@/main/updater'
+
+declare global {
+  var desktopUpdaterFixture: {
+    check(): void
+    install(): void
+    finishStaging(): void
+    failStaging(): void
+    read(): {
+      state: DesktopUpdateState
+      nativeArchive: string | null
+      installed: string[]
+      events: { name: string; data: unknown }[]
+    }
+  }
+}
+
+const directory = process.env.SIM_UPDATER_FIXTURE_DIR
+const origin = process.env.SIM_UPDATER_FIXTURE_ORIGIN
+if (!directory || !origin) throw new Error('Updater fixture configuration is missing')
+app.setPath('userData', join(directory, 'user-data'))
+
+void app.whenReady().then(() => {
+  const configPath = join(directory, 'updater.yml')
+  const cache = relative(join(homedir(), 'Library', 'Caches'), join(directory, 'cache'))
+  writeFileSync(configPath, `updaterCacheDirName: ${JSON.stringify(cache)}\n`)
+
+  let feed: Electron.FeedURLOptions | undefined
+  let nativeArchive: string | null = null
+  const installed: string[] = []
+  const events: { name: string; data: unknown }[] = []
+
+  /** Native verification and installation are simulated; MacUpdater and both HTTP transfers run. */
+  nativeUpdater.setFeedURL = (options) => {
+    feed = options
+    nativeArchive = null
+  }
+  nativeUpdater.checkForUpdates = () => {
+    void (async () => {
+      if (!feed) throw new Error('Native feed was not configured')
+      const response = await net.fetch(feed.url, { headers: feed.headers })
+      const manifest: { url: string } = await response.json()
+      const archive = await net.fetch(manifest.url)
+      nativeArchive = await archive.text()
+    })().catch((error) => nativeUpdater.emit('error', error))
+  }
+  nativeUpdater.quitAndInstall = () => {
+    if (nativeArchive === null) throw new Error('Cannot install before native staging')
+    installed.push(nativeArchive)
+  }
+
+  const updater = new MacUpdater()
+  updater.forceDevUpdateConfig = true
+  updater.disableDifferentialDownload = true
+  updater.updateConfigPath = configPath
+  updater.setFeedURL({ provider: 'generic', url: origin })
+  const handle = initUpdater({
+    getWindow: () => null,
+    events: { filePath: '', record: (name, data) => events.push({ name, data }) },
+    appOrigin: () => origin,
+    loadAutoUpdater: () => updater,
+    canSelfUpdate: async () => true,
+    probeOriginFeed: async () => false,
+    installStatePath: join(directory, 'update-install.json'),
+  })
+
+  globalThis.desktopUpdaterFixture = {
+    check: () => handle.check(),
+    install: () => handle.install(),
+    finishStaging: () => {
+      if (nativeArchive === null) throw new Error('Native transfer has not finished')
+      nativeUpdater.emit('update-downloaded', {}, '', nativeArchive, new Date(), '')
+    },
+    failStaging: () => nativeUpdater.emit('error', new Error('Native verification failed')),
+    read: () => ({ state: handle.getState(), nativeArchive, installed, events }),
+  }
+})

apps/desktop/e2e/updater.spec.ts

@@ -0,0 +1,209 @@
+import { createHash } from 'node:crypto'
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { createServer } from 'node:http'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { _electron as electron, expect, test } from '@playwright/test'
+import { getErrorMessage } from '@sim/utils/errors'
+import { build } from 'esbuild'
+
+const DESKTOP_DIR = fileURLToPath(new URL('..', import.meta.url))
+
+test('the real MacUpdater waits for native staging, replaces old builds, and retries failed staging', async () => {
+  test.skip(process.platform !== 'darwin', 'Squirrel.Mac lifecycle')
+  const directory = mkdtempSync(join(tmpdir(), 'sim-updater-e2e-'))
+  const reportPath =
+    process.env.DESKTOP_UPDATER_REPORT_PATH ?? test.info().outputPath('updater.json')
+  let app: Awaited<ReturnType<typeof electron.launch>> | undefined
+  let offeredVersion = '2.0.0'
+  const requests: { path: string; status: number }[] = []
+  const checks: {
+    name: string
+    status: 'passed' | 'failed'
+    durationMs: number
+    error?: string
+  }[] = []
+  const check = async (name: string, run: () => Promise<void>) => {
+    const started = Date.now()
+    try {
+      await run()
+      checks.push({ name, status: 'passed', durationMs: Date.now() - started })
+    } catch (error) {
+      checks.push({
+        name,
+        status: 'failed',
+        durationMs: Date.now() - started,
+        error: getErrorMessage(error),
+      })
+      throw error
+    }
+  }
+  let snapshot: unknown
+  const server = createServer((request, response) => {
+    const path = new URL(request.url ?? '/', 'http://127.0.0.1').pathname
+    requests.push({ path, status: 200 })
+    if (path === '/latest-mac.yml') {
+      const archive = Buffer.from(offeredVersion)
+      response.end(
+        `version: ${offeredVersion}\nfiles:\n  - url: Sim-${offeredVersion}-universal.zip\n    sha512: ${createHash('sha512').update(archive).digest('base64')}\n    size: ${archive.length}\n`
+      )
+    } else {
+      response.end(/^\/Sim-(.+)-universal.zip$/.exec(path)?.[1] ?? '')
+    }
+  })
+
+  try {
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+    const address = server.address()
+    if (!address || typeof address === 'string') throw new Error('Missing fixture address')
+    mkdirSync(join(directory, 'user-data'))
+    writeFileSync(
+      join(directory, 'package.json'),
+      JSON.stringify({ name: 'sim-updater-fixture', version: '1.0.0', main: 'main.cjs' })
+    )
+    await build({
+      entryPoints: [join(DESKTOP_DIR, 'e2e/fixtures/updater.ts')],
+      outfile: join(directory, 'main.cjs'),
+      bundle: true,
+      platform: 'node',
+      format: 'cjs',
+      external: ['electron'],
+      tsconfig: join(DESKTOP_DIR, 'tsconfig.json'),
+      plugins: [
+        {
+          name: 'approve-fixture-restart',
+          setup(builder) {
+            builder.onResolve({ filter: /^@\/main\/dialogs$/ }, () => ({
+              path: 'dialog',
+              namespace: 'fixture',
+            }))
+            builder.onLoad({ filter: /.*/, namespace: 'fixture' }, () => ({
+              contents:
+                'export async function showShellDialog() { return { response: 1, checkboxChecked: false } }',
+            }))
+          },
+        },
+      ],
+    })
+    app = await electron.launch({
+      args: [directory, '--use-mock-keychain'],
+      env: {
+        ...process.env,
+        SIM_UPDATER_FIXTURE_DIR: directory,
+        SIM_UPDATER_FIXTURE_ORIGIN: `http://127.0.0.1:${address.port}`,
+      },
+    })
+    const shell = app
+    const read = () => shell.evaluate(() => globalThis.desktopUpdaterFixture.read())
+    await expect
+      .poll(() => shell.evaluate(() => Boolean(globalThis.desktopUpdaterFixture)))
+      .toBe(true)
+
+    await check('first download waits for native staging', async () => {
+      await shell.evaluate(() => globalThis.desktopUpdaterFixture.check())
+      await expect.poll(async () => (await read()).nativeArchive).toBe('2.0.0')
+      expect((await read()).state).toEqual({
+        status: 'downloading',
+        version: '2.0.0',
+        percent: 100,
+      })
+      await shell.evaluate(() => globalThis.desktopUpdaterFixture.install())
+      expect((await read()).installed).toEqual([])
+      await shell.evaluate(() => globalThis.desktopUpdaterFixture.finishStaging())
+      expect((await read()).state).toEqual({ status: 'ready', version: '2.0.0' })
+    })
+
+    await check('replacement cannot restart into stale native update', async () => {
+      offeredVersion = '2.1.0'
+      await shell.evaluate(() => globalThis.desktopUpdaterFixture.check())
+      await expect.poll(async () => (await read()).nativeArchive).toBe('2.1.0')
+      expect((await read()).state).toEqual({
+        status: 'downloading',
+        version: '2.1.0',
+        percent: 100,
+      })
+      await shell.evaluate(() => globalThis.desktopUpdaterFixture.install())
+      expect((await read()).installed).toEqual([])
+      await shell.evaluate(() => globalThis.desktopUpdaterFixture.failStaging())
+      expect((await read()).state).toEqual({ status: 'error', version: '2.1.0' })
+    })
+
+    await check('cached retry installs only the verified replacement', async () => {
+      await shell.evaluate(() => globalThis.desktopUpdaterFixture.check())
+      await expect
+        .poll(async () => (await read()).state)
+        .toEqual({ status: 'downloading', version: '2.1.0', percent: 100 })
+      await expect.poll(async () => (await read()).nativeArchive).toBe('2.1.0')
+      await shell.evaluate(() => globalThis.desktopUpdaterFixture.finishStaging())
+      expect((await read()).state).toEqual({ status: 'ready', version: '2.1.0' })
+      await shell.evaluate(() => globalThis.desktopUpdaterFixture.install())
+      await expect.poll(async () => (await read()).installed).toEqual(['2.1.0'])
+    })
+    snapshot = await read()
+    await check(
+      'the next process distinguishes an incomplete update from a successful install',
+      async () => {
+        const checkpoint = readFileSync(join(directory, 'update-install.json'), 'utf8')
+        await app?.close()
+        app = await electron.launch({
+          args: [directory, '--use-mock-keychain'],
+          env: {
+            ...process.env,
+            SIM_UPDATER_FIXTURE_DIR: directory,
+            SIM_UPDATER_FIXTURE_ORIGIN: `http://127.0.0.1:${address.port}`,
+          },
+        })
+        await expect
+          .poll(() => app?.evaluate(() => globalThis.desktopUpdaterFixture?.read().events))
+          .toContainEqual({
+            name: 'update_install_result',
+            data: { expected: '2.1.0', installed: '1.0.0', success: false },
+          })
+        await app.close()
+        writeFileSync(join(directory, 'update-install.json'), checkpoint)
+        writeFileSync(
+          join(directory, 'package.json'),
+          JSON.stringify({ name: 'sim-updater-fixture', version: '2.1.0', main: 'main.cjs' })
+        )
+        app = await electron.launch({
+          args: [directory, '--use-mock-keychain'],
+          env: {
+            ...process.env,
+            SIM_UPDATER_FIXTURE_DIR: directory,
+            SIM_UPDATER_FIXTURE_ORIGIN: `http://127.0.0.1:${address.port}`,
+          },
+        })
+        await expect
+          .poll(() => app?.evaluate(() => globalThis.desktopUpdaterFixture?.read().events))
+          .toContainEqual({
+            name: 'update_install_result',
+            data: { expected: '2.1.0', installed: '2.1.0', success: true },
+          })
+      }
+    )
+  } finally {
+    if (!snapshot && app)
+      snapshot = await app
+        .evaluate(() => globalThis.desktopUpdaterFixture?.read())
+        .catch(() => undefined)
+    mkdirSync(dirname(reportPath), { recursive: true })
+    writeFileSync(
+      reportPath,
+      JSON.stringify(
+        {
+          passed: checks.length === 4 && checks.every((check) => check.status === 'passed'),
+          checks,
+          requests,
+          snapshot,
+        },
+        null,
+        2
+      )
+    )
+    await app?.close()
+    server.closeAllConnections()
+    await new Promise<void>((resolve) => server.close(() => resolve()))
+    rmSync(directory, { recursive: true, force: true })
+  }
+})

apps/desktop/src/main/index.ts

@@ -866,6 +866,7 @@ function main(): void {
     updater = initUpdater({
       getWindow: getMainWindow,
       events,
+      installStatePath: join(userDataPath, 'update-install.json'),
       appOrigin,
       autoDownload: () => config.get('autoDownloadUpdates') ?? true,
       setRelaunchPending: (pending) => {

apps/desktop/src/main/observability.ts

@@ -33,6 +33,8 @@ export type DesktopEventName =
   | 'update_check'
   | 'update_feed'
   | 'update_downloaded'
+  | 'update_install'
+  | 'update_install_result'
   | 'update_error'
   | 'update_blocked_version'
   | 'update_manual_mode'