🤖 feat: let mux server update itself under a restart supervisor

docs/config/server-access.mdx

@@ -78,6 +78,22 @@ Equivalent CLI options:
 - `--ssh-host <host>`
 - `--add-project <path>`
 
+## Updating the server
+
+Open **About** (or use the **Check for Updates**, **Download Update**, **Install Update and Restart**, and **Update Channel** command palette actions) to check for updates, download, then choose **Install & restart**. The server uses the saved update channel, or infers Nightly from an installed `-next.` version when no channel is saved. Stable follows the npm `latest` tag; Nightly follows `next`. Switching channels can install an older version. Checks and restarts are manual. The registry must be reachable over HTTPS without credentials (`XUM_UPDATE_REGISTRY_URL` or `npm_config_registry` override the default) and must answer metadata and tarball requests itself: redirects are refused, and registries that require authentication for metadata report the registry error at check time. The server downloads the release tarball and verifies it against the registry's published sha512 digest before the package manager installs it and its dependencies. After the install, every dependency recorded in the staged lockfile is checked against the digest the registry publishes for that exact version, so a dependency the package manager fetched through a redirect or from a tampered mirror is refused. Every request validates the registry certificate, ignoring `strict-ssl=false` and `NODE_TLS_REJECT_UNAUTHORIZED`; trust a private CA by starting the server with `NODE_EXTRA_CA_CERTS`, which the server and the package manager both honor (`cafile` is not consulted).
+
+Self-update requires a supervisor that restarts the server after it exits, an external launcher symlink pointing to an installed `@coder/xum` CLI with a bun, npm, or pnpm lockfile, and a stable auth token (`MUX_SERVER_AUTH_TOKEN`, `--auth-token`, or `--no-auth`). A generated token dies with the process, so the relaunched server would lock every browser session out. Set `XUM_BINARY` to that symlink and `XUM_SERVER_SUPERVISED=true` only when a supervisor is configured. The `coder/mux` registry module with `restart_on_kill=true` already declares these through its launcher environment. Unsupported installations show a reason instead of offering an update.
+
+Downloads install an exact package version in a sibling staging directory without changing the running installation. Restart is blocked by active streams, pending turns, workspaces still initializing or being archived, removed, renamed, forked, or staged, workflow runs, project clones and creations, any other request still in flight, queued messages, pending auto-retries, open or starting terminals, live desktop sessions, and running background processes. Finish or stop that work, then retry. There is no automatic restart-when-idle in this version.
+
+After activation, the server exits gracefully and the supervisor relaunches it. Browser clients reconnect and reload when the server build changes. If reconnection takes longer than about 45 seconds, use **Retry**.
+
+<Warning>
+  The registry module counts self-updates toward `max_restart_attempts`, just like other exits. The
+  server cannot read the remaining restart budget. Ensure the supervisor has restarts available, or
+  configure unlimited restarts (`max_restart_attempts=0`) before relying on self-update.
+</Warning>
+
 ## Related
 
 - [CLI reference](/reference/cli)

src/browser/App.tsx

@@ -99,7 +99,7 @@ import { SCRATCH_PROJECT_CONFIG_KEY } from "@/common/constants/scratch";
 import { ProjectPage } from "@/browser/components/ProjectPage/ProjectPage";
 
 import { SettingsProvider, useSettings } from "./contexts/SettingsContext";
-import { AboutDialogProvider } from "./contexts/AboutDialogContext";
+import { AboutDialogProvider, useAboutDialog } from "./contexts/AboutDialogContext";
 import { ConfirmDialogProvider, useConfirmDialog } from "./contexts/ConfirmDialogContext";
 import { AboutDialog } from "./features/About/AboutDialog";
 import { SettingsPage } from "@/browser/features/Settings/SettingsPage";
@@ -184,6 +184,7 @@ function AppInner() {
   } = useRouter();
   const { themePreference, setTheme, toggleTheme } = useTheme();
   const { open: openSettings, isOpen: isSettingsOpen } = useSettings();
+  const { open: openAboutDialog } = useAboutDialog();
   const { confirm: confirmDialog } = useConfirmDialog();
   const setThemePreference = useCallback(
     (nextTheme: ThemePreference) => {
@@ -1019,6 +1020,7 @@ function AppInner() {
     onToggleTheme: toggleTheme,
     onSetTheme: setThemePreference,
     onOpenSettings: openSettings,
+    onOpenAbout: openAboutDialog,
     layoutPresets,
     onApplyLayoutSlot: (workspaceId, slot) => {
       void applySlotToWorkspace(workspaceId, slot).catch(() => {

src/browser/contexts/API.test.tsx

@@ -1,5 +1,6 @@
+import { VERSION } from "@/version";
 import { act, cleanup, render, waitFor } from "@testing-library/react";
-import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, mock, spyOn, test } from "bun:test";
 import { GlobalWindow } from "happy-dom";
 import type { RecursivePartial } from "@/browser/testUtils";
 
@@ -240,6 +241,67 @@ describe("API reconnection", () => {
     expect(MockWebSocket.instances).toHaveLength(0);
   });
 
+  test.each(["changed", "rebuilt", "same", "unreachable", "malformed", "cross-origin"])(
+    "checks the server version on reconnect: %s",
+    async (scenario) => {
+      if (scenario === "cross-origin") process.env.VITE_BACKEND_URL = "https://api.example.com";
+      const reload = spyOn(window.location, "reload").mockImplementation(() => undefined);
+      const requests: string[] = [];
+      fetchImpl = (input) => {
+        requests.push(
+          typeof input === "string" ? input : input instanceof URL ? input.href : input.url
+        );
+        if (scenario === "unreachable") return Promise.reject(new Error("offline"));
+        return Promise.resolve(
+          new Response(
+            JSON.stringify(
+              scenario === "malformed"
+                ? {}
+                : {
+                    git_commit:
+                      scenario === "changed" ? "different-server-commit" : VERSION.git_commit,
+                    git_describe: scenario === "rebuilt" ? "v9.9.9-rebuilt" : VERSION.git_describe,
+                  }
+            ),
+            { status: 200 }
+          )
+        );
+      };
+      window.location.href = "https://coder.example.com/@u/ws/apps/mux/";
+      let latestState: UseAPIResult | null = null;
+      render(
+        <APIProvider createWebSocket={createMockWebSocket}>
+          <APIStateObserver
+            onState={(s) => {
+              latestState = s.apiState;
+            }}
+          />
+        </APIProvider>
+      );
+      await act(async () => {
+        MockWebSocket.lastInstance()!.simulateOpen();
+        await Promise.resolve();
+      });
+      expect(latestState!.status).toBe("connected");
+      expect(requests).toEqual([]);
+      act(() => {
+        latestState!.retry();
+      });
+      await act(async () => {
+        MockWebSocket.lastInstance()!.simulateOpen();
+        await Promise.resolve();
+      });
+      expect(requests).toEqual(
+        scenario === "cross-origin" ? [] : ["https://coder.example.com/@u/ws/apps/mux/version"]
+      );
+      const reloads = scenario === "changed" || scenario === "rebuilt" ? 1 : 0;
+      expect(reload).toHaveBeenCalledTimes(reloads);
+      if (reloads === 0) expect(latestState!.status).toBe("connected");
+      reload.mockRestore();
+      delete process.env.VITE_BACKEND_URL;
+    }
+  );
+
   test("reconnects on close without showing auth_required when previously connected", async () => {
     const states: string[] = [];
 

src/browser/contexts/API.tsx

@@ -1,3 +1,5 @@
+import { SERVER_VERSION_CHECK_TIMEOUT_MS } from "@/constants/serverUpdate";
+import { VERSION } from "@/version";
 import {
   createContext,
   useContext,
@@ -148,6 +150,33 @@ function createBrowserClient(
   };
 }
 
+async function reloadIfServerBuildChanged(
+  backendBaseUrl: string,
+  isCurrentConnection: () => boolean
+): Promise<void> {
+  try {
+    const response = await fetch(`${backendBaseUrl}/version`, {
+      cache: "no-store",
+      signal: AbortSignal.timeout(SERVER_VERSION_CHECK_TIMEOUT_MS),
+    });
+    const version: unknown = response.ok ? await response.json() : null;
+    if (
+      isCurrentConnection() &&
+      version &&
+      typeof version === "object" &&
+      "git_commit" in version &&
+      typeof version.git_commit === "string" &&
+      version.git_commit.length > 0 &&
+      (version.git_commit !== VERSION.git_commit ||
+        ("git_describe" in version && version.git_describe !== VERSION.git_describe))
+    ) {
+      window.location.reload();
+    }
+  } catch {
+    // Version discovery must not disturb an already reconnected client.
+  }
+}
+
 function ManagedAPIProvider(props: Omit<APIProviderProps, "client">) {
   const [state, setState] = useState<ConnectionState>({ status: "connecting" });
   const [authToken, setAuthToken] = useState<string | null>(() => {
@@ -261,6 +290,7 @@ function ManagedAPIProvider(props: Omit<APIProviderProps, "client">) {
               return;
             }
 
+            const reconnected = hasConnectedRef.current;
             authRequiredRef.current = false;
             hasConnectedRef.current = true;
             reconnectAttemptRef.current = 0;
@@ -269,6 +299,17 @@ function ManagedAPIProvider(props: Omit<APIProviderProps, "client">) {
             window.__ORPC_CLIENT__ = client;
             cleanupRef.current = cleanup;
             setState({ status: "connected", client, cleanup });
+            // A reconnected socket may belong to a newer server than this loaded bundle. The probe
+            // runs after the client is published so a slow /version never delays reconnection, and
+            // only a bundle served by that server can be refreshed by reloading, so split-origin
+            // setups (VITE_BACKEND_URL, extension webviews) skip it.
+            const backendBaseUrl = getBrowserBackendBaseUrl();
+            if (reconnected && new URL(backendBaseUrl).origin === window.location.origin) {
+              void reloadIfServerBuildChanged(
+                backendBaseUrl,
+                () => connectionId === connectionIdRef.current
+              );
+            }
           })
           .catch((err: unknown) => {
             if (connectionId !== connectionIdRef.current) {

src/browser/features/About/AboutDialog.stories.tsx

@@ -0,0 +1,100 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent, within } from "@storybook/test";
+import type { UpdateStatus } from "@/common/orpc/types";
+import { APIProvider } from "@/browser/contexts/API";
+import { AboutDialogProvider, useAboutDialog } from "@/browser/contexts/AboutDialogContext";
+import { Button } from "@/browser/components/Button/Button";
+import { lightweightMeta } from "@/browser/stories/meta";
+import { createMockORPCClient } from "@/browser/stories/mocks/orpc";
+import { AboutDialog } from "./AboutDialog";
+
+function OpenAbout() {
+  const about = useAboutDialog();
+  return (
+    <>
+      <Button onClick={about.open}>Open About</Button>
+      <AboutDialog />
+    </>
+  );
+}
+
+function ServerUpdateStory(props: { status: UpdateStatus }) {
+  const [client] = useState(() =>
+    createMockORPCClient({ updateStatus: props.status, updateChannel: "nightly" })
+  );
+  return (
+    <APIProvider client={client}>
+      <AboutDialogProvider>
+        <OpenAbout />
+      </AboutDialogProvider>
+    </APIProvider>
+  );
+}
+
+const meta = {
+  ...lightweightMeta,
+  title: "Features/About/Server updates",
+  component: ServerUpdateStory,
+  play: async ({ canvasElement }) => {
+    await userEvent.click(within(canvasElement).getByRole("button", { name: "Open About" }));
+  },
+} satisfies Meta<typeof ServerUpdateStory>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Unsupported: Story = {
+  args: {
+    status: {
+      type: "unsupported",
+      reason: "Server updates require a supervisor configured to restart after exit",
+    },
+  },
+  play: async (context) => {
+    await meta.play(context);
+    const dialog = await within(document.body).findByRole("dialog");
+    await expect(
+      within(dialog).queryByRole("button", { name: "Install & restart" })
+    ).not.toBeInTheDocument();
+    await expect(
+      within(dialog).queryByRole("button", { name: "Check for Updates" })
+    ).not.toBeInTheDocument();
+  },
+};
+
+export const Downloading: Story = {
+  args: { status: { type: "downloading", percent: null } },
+  play: async (context) => {
+    await meta.play(context);
+    const dialog = await within(document.body).findByRole("dialog");
+    await expect(within(dialog).getByRole("button", { name: "Check for Updates" })).toBeDisabled();
+  },
+};
+
+export const BlockedPhone: Story = {
+  args: {
+    status: {
+      type: "install-blocked",
+      info: { version: "0.28.4-next.123.g123456789" },
+      blockers: [
+        { kind: "pending-turns", count: 2 },
+        { kind: "terminals", count: 1 },
+      ],
+    },
+  },
+  parameters: { pixel: { matrix: { viewports: ["phone"] } } },
+  globals: { viewport: { value: "mobile1", isRotated: false } },
+  play: async (context) => {
+    await meta.play(context);
+    const dialog = await within(document.body).findByRole("dialog");
+    const retry = within(dialog).getByRole("button", { name: "Install & restart" });
+    await expect(retry).toBeEnabled();
+    await expect(within(dialog).getByRole("status")).toBeVisible();
+    if (window.innerWidth <= 440) {
+      await expect(dialog.getBoundingClientRect().right).toBeLessThanOrEqual(window.innerWidth);
+      await expect(retry.getBoundingClientRect().right).toBeLessThanOrEqual(
+        dialog.getBoundingClientRect().right
+      );
+    }
+  },
+};