feat(release): verify Windows automatic updates end to end (#3240)

Add a loopback-only update-feed override and end-to-end Windows evidence for discovering, downloading, installing, and relaunching an automatic update.

Generated-by: Claude Fable 5

Author: liugddx

.github/workflows/release-desktop.yml

@@ -25,7 +25,7 @@ jobs:
             runner: windows-2025
     runs-on: ${{ matrix.runner }}
     environment: release
-    timeout-minutes: 45
+    timeout-minutes: 60
     defaults:
       run:
         # Windows runners default to pwsh; the release steps are written once,
@@ -153,6 +153,19 @@ jobs:
             "${{ steps.release.outputs.exe }}" \
             "${{ steps.previous.outputs.exe }}"
 
+      - name: Build the version-bumped autoupdate installer
+        if: matrix.platform == 'windows'
+        run: npm run package:windows-autoupdate-next
+
+      # The fake-versioned artifacts live outside apps/desktop/release, so the
+      # upload globs below can never pick them up.
+      - name: Verify automatic update end to end
+        if: matrix.platform == 'windows'
+        run: |
+          npm run verify:windows-autoupdate -- \
+            "${{ steps.release.outputs.exe }}" \
+            apps/desktop/release-autoupdate-next
+
       - name: Upload the verified release assets
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:

.github/workflows/release-windows-check.yml

@@ -21,6 +21,12 @@ on:
       - 'scripts/verify-windows-x64.mjs'
       - 'scripts/verify-windows-sandbox-e2e.mjs'
       - 'scripts/verify-windows-installer-lifecycle.mjs'
+      - 'scripts/verify-windows-autoupdate.mjs'
+      - 'scripts/package-windows-autoupdate-next.mjs'
+      # The packaged updater's feed behavior — and the boot wiring that hands
+      # MAKA_UPDATE_TEST_FEED to it — is only observable on this path.
+      - 'apps/desktop/src/main/app-update-service.ts'
+      - 'apps/desktop/src/main/runtime-host-boot.ts'
       - 'scripts/prepare-windows-upgrade-baseline.mjs'
       - 'scripts/windows-upgrade-baseline.json'
       - 'scripts/verify-packaged-app.mjs'
@@ -47,7 +53,7 @@ concurrency:
 jobs:
   package:
     runs-on: windows-2025
-    timeout-minutes: 60
+    timeout-minutes: 75
     defaults:
       run:
         shell: bash
@@ -89,3 +95,13 @@ jobs:
           npm run verify:windows-installer -- \
             "apps/desktop/release/Maka-${version}-win-x64.exe" \
             "${{ steps.previous.outputs.exe }}"
+
+      - name: Build the version-bumped autoupdate installer
+        run: npm run package:windows-autoupdate-next
+
+      - name: Verify automatic update end to end
+        run: |
+          version="$(node -p "require('./apps/desktop/package.json').version")"
+          npm run verify:windows-autoupdate -- \
+            "apps/desktop/release/Maka-${version}-win-x64.exe" \
+            apps/desktop/release-autoupdate-next

apps/desktop/src/main/__tests__/app-update-service.test.ts

@@ -4,6 +4,7 @@ import { describe, test } from 'node:test';
 import type { AppUpdater } from 'electron-updater';
 import {
   createAppUpdateService,
+  resolveUpdateFeedOverride,
   type AppUpdateInstallRequest,
   type AppUpdateStatus,
 } from '../app-update-service.js';
@@ -106,6 +107,7 @@ function createHarness(input: {
   >;
   mockLatestVersion?: string;
   mockState?: 'available' | 'downloading' | 'downloaded';
+  testFeedUrl?: string;
 } = {}) {
   const updater = input.updater ?? new FakeUpdater();
   const clock = input.clock ?? new FakeClock();
@@ -121,6 +123,7 @@ function createHarness(input: {
         : { kind: 'prepared', rollback() {} }),
     mockLatestVersion: input.mockLatestVersion,
     mockState: input.mockState,
+    testFeedUrl: input.testFeedUrl,
   });
   return { clock, service, updater };
 }
@@ -150,6 +153,56 @@ describe('AppUpdateService', () => {
     assert.equal(clock.pending().length, 0);
   });
 
+  test('routes the feed to a loopback generic provider when the test override is set', () => {
+    const { updater } = createHarness({ testFeedUrl: 'http://127.0.0.1:8443/feed' });
+    assert.deepEqual(updater.feed, {
+      provider: 'generic',
+      url: 'http://127.0.0.1:8443/feed',
+    });
+  });
+
+  test('rejects a non-loopback test feed instead of falling back to production', () => {
+    // A mistyped override must never silently install from the real GitHub
+    // feed: construction fails closed.
+    assert.throws(
+      () => createHarness({ testFeedUrl: 'https://evil.example/feed' }),
+      TypeError,
+    );
+  });
+
+  test('resolveUpdateFeedOverride accepts exactly loopback http URLs', () => {
+    assert.equal(resolveUpdateFeedOverride(undefined), undefined);
+    assert.equal(resolveUpdateFeedOverride(''), undefined);
+    assert.deepEqual(resolveUpdateFeedOverride('http://127.0.0.1:1'), {
+      provider: 'generic',
+      url: 'http://127.0.0.1:1/',
+    });
+    assert.deepEqual(resolveUpdateFeedOverride('http://127.0.0.1:65535/updates'), {
+      provider: 'generic',
+      url: 'http://127.0.0.1:65535/updates',
+    });
+    const rejected = [
+      'not-a-url',
+      'file:///C:/feed',
+      'https://127.0.0.1:1', // https is not loopback-harness shaped
+      'http://localhost:1', // alias resolution is not identity
+      'http://127.0.0.2:1', // other loopback addresses stay rejected
+      'http://[::1]:1', // IPv6 loopback stays rejected: one accepted shape only
+      'http://127.0.0.1', // no port: cannot be an ephemeral harness server
+      'http://u:p@127.0.0.1:1', // userinfo confusion
+      'http://127.0.0.1.evil.example:1', // hostname prefix confusion
+      'http://127.0.0.1:1/x?y=1', // query smuggling
+      'http://127.0.0.1:1/x#frag',
+    ];
+    for (const raw of rejected) {
+      assert.throws(
+        () => resolveUpdateFeedOverride(raw),
+        TypeError,
+        `expected rejection: ${raw}`,
+      );
+    }
+  });
+
   test('does not overlap checks and cannot re-arm after disposal', async () => {
     const updater = new FakeUpdater();
     let settleCheck!: (value: unknown) => void;

apps/desktop/src/main/app-update-service.ts

@@ -67,6 +67,11 @@ interface AppUpdateServiceDeps {
   currentVersion: string;
   isPackaged: boolean;
   updater?: AppUpdater;
+  /**
+   * Harness-only feed override (`MAKA_UPDATE_TEST_FEED`); see
+   * {@link resolveUpdateFeedOverride} for the exact accepted shape.
+   */
+  testFeedUrl?: string;
   mockLatestVersion?: string;
   mockState?: 'available' | 'downloading' | 'downloaded';
   onStatusChange?: (status: AppUpdateStatus) => void;
@@ -93,6 +98,58 @@ const UPDATE_CHECK_INTERVAL_MS = 4 * 60 * 60 * 1000;
  */
 const UPDATE_CHECK_ON_FOCUS_MIN_INTERVAL_MS = 15 * 60 * 1000;
 
+/**
+ * Harness-only override for the update feed (`MAKA_UPDATE_TEST_FEED`).
+ *
+ * Accepts exactly `http://127.0.0.1:<port>[/path]` and maps it to a generic
+ * provider so the end-to-end Windows auto-update verification can serve a
+ * candidate installer plus `latest.yml` from a loopback HTTP server. Anything
+ * else set — a remote host, `localhost`, another loopback alias, HTTPS,
+ * userinfo, a query string, or a malformed URL — throws: a mistyped override
+ * must never silently fall back to the production GitHub feed, because a test
+ * run quietly installing a real release is exactly the failure this shape
+ * exists to prevent.
+ *
+ * Security posture (this is not an update-hijack vector): setting an
+ * environment variable on the app's process already requires code execution
+ * as the same user, and the per-user NSIS install model means that user can
+ * rewrite the installation directory directly — the override grants no
+ * capability across any privilege boundary. Loopback-only keeps even that
+ * same-user surface minimal: the feed must be a process listening on this
+ * machine. With the variable unset the feed configuration is byte-identical
+ * to production, and update signature verification (once a certificate
+ * exists) applies to overridden feeds exactly as it does to the GitHub feed —
+ * nothing here relaxes it.
+ */
+export function resolveUpdateFeedOverride(
+  raw: string | undefined,
+): { provider: 'generic'; url: string } | undefined {
+  if (raw === undefined || raw === '') return undefined;
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new TypeError(
+      `MAKA_UPDATE_TEST_FEED is not a URL: ${JSON.stringify(raw)}`,
+    );
+  }
+  if (
+    url.protocol !== 'http:' ||
+    url.hostname !== '127.0.0.1' ||
+    url.port === '' ||
+    url.username !== '' ||
+    url.password !== '' ||
+    url.search !== '' ||
+    url.hash !== ''
+  ) {
+    throw new TypeError(
+      'MAKA_UPDATE_TEST_FEED must be http://127.0.0.1:<port>[/path] ' +
+        `(got ${JSON.stringify(raw)})`,
+    );
+  }
+  return { provider: 'generic', url: url.toString() };
+}
+
 function normalizeVersion(version: string): string {
   return version.trim().replace(/^v/i, '');
 }
@@ -241,11 +298,16 @@ export function createAppUpdateService(deps: AppUpdateServiceDeps): AppUpdateSer
   updater.autoInstallOnAppQuit = false;
   updater.allowPrerelease = false;
   updater.logger = null;
-  updater.setFeedURL({
-    provider: 'github',
-    owner: 'Maka-Agent',
-    repo: 'maka-agent',
-  });
+  // The override changes the feed URL and nothing else: every other updater
+  // setting and the whole status machine behave identically under it, so what
+  // the loopback harness verifies is what production runs.
+  updater.setFeedURL(
+    resolveUpdateFeedOverride(deps.testFeedUrl) ?? {
+      provider: 'github',
+      owner: 'Maka-Agent',
+      repo: 'maka-agent',
+    },
+  );
 
   updater.on('checking-for-update', () => {
     publish({ state: 'checking', currentVersion: deps.currentVersion });

apps/desktop/src/main/runtime-host-boot.ts

@@ -420,6 +420,7 @@ const updateMockState =
 const updateService = createAppUpdateService({
   currentVersion: app.getVersion(),
   isPackaged: app.isPackaged,
+  testFeedUrl: process.env.MAKA_UPDATE_TEST_FEED,
   mockLatestVersion: process.env.MAKA_UPDATE_MOCK_VERSION,
   mockState: updateMockState,
   onStatusChange: (status) =>

docs/windows-support.md

@@ -1,6 +1,6 @@
 # Windows support baseline
 
-Windows is an active enablement target, not a fully supported Maka platform yet. The CLI and Electron desktop application can run from source, and release workflows produce a verified unsigned Windows x64 preview. The x64 package includes an AppContainer sandbox for restricted managed execution; signing, the complete adversarial sandbox matrix, automatic updates, and computer-use guarantees remain incomplete. Progress is tracked in [GitHub issue #2142](https://github.com/maka-agent/maka-agent/issues/2142).
+Windows is an active enablement target, not a fully supported Maka platform yet. The CLI and Electron desktop application can run from source, and release workflows produce a verified unsigned Windows x64 preview. The x64 package includes an AppContainer sandbox for restricted managed execution, and automatic updates are verified end to end in CI on the unsigned preview channel; signing, the complete adversarial sandbox matrix, and computer-use guarantees remain incomplete. Progress is tracked in [GitHub issue #2142](https://github.com/maka-agent/maka-agent/issues/2142).
 
 ## Install the Windows x64 preview
 
@@ -25,8 +25,15 @@ Only use Windows assets attached to a Maka GitHub Release. The NSIS installer is
 
 The release gate installs a pinned v0.1.9 build, fully smokes it, upgrades the same installation to
 the candidate, fully smokes the candidate, waits for installed processes to exit, and runs the real
-uninstaller. This proves a closed-app upgrade and uninstall path. It does not prove automatic update,
-running-app upgrade, persisted business-data migration, or rollback after a mid-install failure.
+uninstaller. A second gate proves the automatic, running-app upgrade path: the installed candidate,
+running, discovers a newer build through its packaged electron-updater against a loopback test feed,
+downloads it in the background, hands off to the NSIS installer, relaunches as the new version, and
+passes the full packaged smoke — with the feed requests (including the differential-download probe),
+the `downloaded` state and its exact version pair, and the final installed version asserted
+individually; transient states such as `checking` and `downloading` are not individually asserted. What is still not proven: update signature verification (no Authenticode
+certificate yet — the feed configuration for the production GitHub channel is pinned by unit tests
+and exercised routinely on real releases instead), persisted business-data migration, and rollback
+after a mid-install failure.
 
 To uninstall, use **Settings → Apps → Installed apps → Maka → Uninstall**. Back up any important
 workspace data first; the preview does not yet claim installer rollback or migration guarantees.
@@ -51,8 +58,12 @@ workspace data first; the preview does not yet claim installer rollback or migra
    `winget install BurntSushi.ripgrep.MSVC`，并在 `PATH` 更新后重启 Maka。
 
 发布门禁会安装固定的 v0.1.9、执行完整 smoke、在同一目录升级候选版本、再次完整 smoke、等待安装目录内
-进程退出，并运行真实卸载器。这证明关闭应用后的升级与卸载路径，不证明自动更新、运行中升级、业务数据迁移，
-也不证明安装中途失败后的 rollback。
+进程退出，并运行真实卸载器。另一个门禁证明**运行中的自动更新路径**：已安装且正在运行的候选版本通过打包的
+electron-updater 从 loopback 测试 feed 发现新版本、后台下载、交接给 NSIS 安装器、以新版本自动重启并通过
+完整打包 smoke——feed 请求（含差量下载探测）、`downloaded` 状态及其精确版本对、最终安装版本均逐项断言；
+`checking`/`downloading` 等瞬态不逐项断言。仍未证明的是：更新签名校验（尚无
+Authenticode 证书；生产 GitHub 通道的 feed 配置由单测钉死，并在每次真实 release 中例行使用）、业务数据
+迁移，以及安装中途失败后的 rollback。
 
 卸载入口为 **设置 → 应用 → 已安装的应用 → Maka → 卸载**。预览版尚未承诺安装器 rollback 或数据迁移，
 请先备份重要 workspace 数据。
@@ -69,7 +80,7 @@ The initial target is a native Windows 11 x64 development environment with:
 - WebView/runtime components installed by a current Windows 11 installation;
 - Windows Developer Mode or elevation only for tests that create file symlinks. Normal CLI and desktop startup must not require either.
 
-Windows 10, Windows on Arm, automatic updates, the final sandbox support declaration, and computer-use are not covered by the current support target. Packaged installation is available only as the unsigned Windows 11 x64 preview described above.
+Windows 10, Windows on Arm, signed automatic updates, the final sandbox support declaration, and computer-use are not covered by the current support target. Packaged installation is available only as the unsigned Windows 11 x64 preview described above; its automatic-update path is CI-verified but unsigned.
 
 ## Reproducible checks
 
@@ -148,6 +159,9 @@ The root test timeout is tracked separately from individual test failures. Phase
 - Restricted managed profiles use the packaged AppContainer broker when available and fail closed
   when the native capability or requested policy is unavailable.
 - Computer-use has no Windows backend.
-- The Windows x64 NSIS installer is unsigned and there is no supported automatic-update channel.
+- The Windows x64 NSIS installer is unsigned. The in-app automatic-update path (electron-updater →
+  NSIS handoff → relaunch) is verified end to end in CI against a loopback feed; the production
+  GitHub feed configuration is pinned by unit tests. Updates are not signature-verified until an
+  Authenticode certificate lands.
 
 Do not describe Windows as released or fully supported until the support criteria in issue #2142 are complete for the claimed support tier.

package.json

@@ -53,6 +53,8 @@
     "package:windows-x64": "node scripts/package-windows-x64.mjs",
     "verify:windows-x64": "node scripts/verify-windows-x64.mjs",
     "verify:windows-installer": "node scripts/verify-windows-installer-lifecycle.mjs",
+    "package:windows-autoupdate-next": "node scripts/package-windows-autoupdate-next.mjs",
+    "verify:windows-autoupdate": "node scripts/verify-windows-autoupdate.mjs",
     "astryx:theme": "node scripts/build-astryx-theme.mjs",
     "astryx:surface-inventory": "node scripts/check-astryx-surface-inventory.mjs",
     "astryx:surface-inventory:write": "node scripts/generate-astryx-surface-inventory.mjs",