feat(desktop): split daemon and release settings to main process

Move daemon management and release channel settings out of the renderer's
AsyncStorage and into a desktop-owned settings store persisted by the main
process. Adds a "Keep daemon running after quit" option, a daemon lifecycle
section in settings, and a one-time migration of legacy renderer-owned
desktop settings.

packages/desktop/src/daemon/daemon-manager.ts

@@ -33,6 +33,11 @@ import {
   runCliJsonCommand,
   runCliTextCommand,
 } from "./runtime-paths.js";
+import {
+  createDesktopSettingsCommandHandlers,
+  type DesktopCommandHandler,
+} from "../settings/desktop-settings-commands.js";
+import { getDesktopSettingsStore } from "../settings/desktop-settings-electron.js";
 
 const DAEMON_LOG_FILENAME = "daemon.log";
 const PID_POLL_INTERVAL_MS = 100;
@@ -44,7 +49,7 @@ const DETACHED_STARTUP_GRACE_MS = 1200;
 
 type DesktopDaemonState = "starting" | "running" | "stopped" | "errored";
 
-interface DesktopDaemonStatus {
+export interface DesktopDaemonStatus {
   serverId: string;
   status: DesktopDaemonState;
   listen: string | null;
@@ -67,10 +72,16 @@ interface DesktopPairingOffer {
   qr: string | null;
 }
 
-type DesktopCommandHandler = (args?: Record<string, unknown>) => Promise<unknown> | unknown;
-
-function parseReleaseChannel(args: Record<string, unknown> | undefined): AppReleaseChannel {
-  return args?.releaseChannel === "beta" ? "beta" : "stable";
+function parseReleaseChannel(
+  args: Record<string, unknown> | undefined,
+): AppReleaseChannel | undefined {
+  if (args?.releaseChannel === "beta") {
+    return "beta";
+  }
+  if (args?.releaseChannel === "stable") {
+    return "stable";
+  }
+  return undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -195,7 +206,7 @@ function resolveDesktopAppVersion(): string {
 // Daemon lifecycle
 // ---------------------------------------------------------------------------
 
-async function resolveStatus(): Promise<DesktopDaemonStatus> {
+export async function resolveDesktopDaemonStatus(): Promise<DesktopDaemonStatus> {
   const home = getPaseoHome();
 
   try {
@@ -265,8 +276,8 @@ function buildStartupFailureError(
 
 async function pollForRunningDaemon(): Promise<DesktopDaemonStatus> {
   async function poll(attempt: number): Promise<DesktopDaemonStatus> {
-    if (attempt >= STARTUP_POLL_MAX_ATTEMPTS) return resolveStatus();
-    const status = await resolveStatus();
+    if (attempt >= STARTUP_POLL_MAX_ATTEMPTS) return resolveDesktopDaemonStatus();
+    const status = await resolveDesktopDaemonStatus();
     if (attempt === 0 || attempt === STARTUP_POLL_MAX_ATTEMPTS - 1 || attempt % 10 === 9) {
       logDesktopDaemonLifecycle("polling daemon status after detached start", {
         attempt: attempt + 1,
@@ -284,7 +295,7 @@ async function pollForRunningDaemon(): Promise<DesktopDaemonStatus> {
 }
 
 async function startDaemon(): Promise<DesktopDaemonStatus> {
-  const current = await resolveStatus();
+  const current = await resolveDesktopDaemonStatus();
   logDesktopDaemonLifecycle("initial status check before start", {
     status: current.status,
     pid: current.pid,
@@ -299,7 +310,7 @@ async function startDaemon(): Promise<DesktopDaemonStatus> {
         appVersion: normalizeVersion(resolveDesktopAppVersion()),
         daemonVersion: normalizeVersion(current.version),
       });
-      await stopDaemon();
+      await stopDesktopDaemon();
     } else {
       return current;
     }
@@ -389,8 +400,8 @@ async function startDaemon(): Promise<DesktopDaemonStatus> {
   return pollForRunningDaemon();
 }
 
-async function stopDaemon(): Promise<DesktopDaemonStatus> {
-  const status = await resolveStatus();
+export async function stopDesktopDaemon(): Promise<DesktopDaemonStatus> {
+  const status = await resolveDesktopDaemonStatus();
   if (status.status !== "running" || !status.pid) return status;
 
   const pid = status.pid;
@@ -406,11 +417,11 @@ async function stopDaemon(): Promise<DesktopDaemonStatus> {
     throw new Error(`Timed out waiting for daemon PID ${pid} to stop`);
   }
 
-  return await resolveStatus();
+  return await resolveDesktopDaemonStatus();
 }
 
 async function restartDaemon(): Promise<DesktopDaemonStatus> {
-  await stopDaemon();
+  await stopDesktopDaemon();
   return startDaemon();
 }
 
@@ -427,7 +438,7 @@ async function getCliDaemonStatus(): Promise<string> {
 }
 
 async function getDaemonPairing(): Promise<DesktopPairingOffer> {
-  const status = await resolveStatus();
+  const status = await resolveDesktopDaemonStatus();
   if (status.status !== "running") {
     return {
       relayEnabled: false,
@@ -457,7 +468,7 @@ async function getDaemonPairing(): Promise<DesktopPairingOffer> {
 }
 
 async function getLocalDaemonVersion(): Promise<{ version: string | null; error: string | null }> {
-  const status = await resolveStatus();
+  const status = await resolveDesktopDaemonStatus();
   if (status.status !== "running") {
     return { version: null, error: "Daemon is not running." };
   }
@@ -467,12 +478,10 @@ async function getLocalDaemonVersion(): Promise<{ version: string | null; error:
   };
 }
 
-function resolveCurrentUpdateVersion(): string {
-  return resolveDesktopAppVersion();
-}
-
-function getSystemIdleTimeMs(): number {
-  return powerMonitor.getSystemIdleTime() * 1000;
+async function resolveRequestedReleaseChannel(
+  args: Record<string, unknown> | undefined,
+): Promise<AppReleaseChannel> {
+  return parseReleaseChannel(args) ?? (await getDesktopSettingsStore().get()).releaseChannel;
 }
 
 // ---------------------------------------------------------------------------
@@ -481,13 +490,14 @@ function getSystemIdleTimeMs(): number {
 
 export function createDaemonCommandHandlers(): Record<string, DesktopCommandHandler> {
   return {
-    desktop_daemon_status: () => resolveStatus(),
+    ...createDesktopSettingsCommandHandlers({ settingsStore: getDesktopSettingsStore() }),
+    desktop_daemon_status: () => resolveDesktopDaemonStatus(),
     start_desktop_daemon: () => startDaemon(),
-    stop_desktop_daemon: () => stopDaemon(),
+    stop_desktop_daemon: () => stopDesktopDaemon(),
     restart_desktop_daemon: () => restartDaemon(),
     desktop_daemon_logs: () => getDaemonLogs(),
     desktop_daemon_pairing: () => getDaemonPairing(),
-    desktop_get_system_idle_time: () => getSystemIdleTimeMs(),
+    desktop_get_system_idle_time: () => powerMonitor.getSystemIdleTime() * 1000,
     cli_daemon_status: () => getCliDaemonStatus(),
     write_attachment_base64: (args) => writeAttachmentBase64(args ?? {}),
     copy_attachment_file: (args) => copyAttachmentFileToManagedStorage(args ?? {}),
@@ -511,15 +521,18 @@ export function createDaemonCommandHandlers(): Record<string, DesktopCommandHand
       if (sessionId) closeLocalTransportSession(sessionId);
     },
     check_app_update: async (args) => {
-      const currentVersion = await resolveCurrentUpdateVersion();
-      return checkForAppUpdate({ currentVersion, releaseChannel: parseReleaseChannel(args) });
+      const currentVersion = resolveDesktopAppVersion();
+      return checkForAppUpdate({
+        currentVersion,
+        releaseChannel: await resolveRequestedReleaseChannel(args),
+      });
     },
     install_app_update: async (args) => {
-      const currentVersion = await resolveCurrentUpdateVersion();
+      const currentVersion = resolveDesktopAppVersion();
       return downloadAndInstallUpdate(
-        { currentVersion, releaseChannel: parseReleaseChannel(args) },
+        { currentVersion, releaseChannel: await resolveRequestedReleaseChannel(args) },
         async () => {
-          await stopDaemon();
+          await stopDesktopDaemon();
         },
       );
     },

packages/desktop/src/daemon/quit-lifecycle.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { DEFAULT_DESKTOP_SETTINGS } from "../settings/desktop-settings";
+import {
+  createBeforeQuitHandler,
+  shouldStopDesktopManagedDaemonOnQuit,
+  stopDesktopManagedDaemonOnQuitIfNeeded,
+} from "./quit-lifecycle";
+
+describe("quit-lifecycle", () => {
+  it("stops only when quit persistence disables keep-running and the daemon is desktop-managed", () => {
+    expect(
+      shouldStopDesktopManagedDaemonOnQuit({
+        settings: {
+          ...DEFAULT_DESKTOP_SETTINGS,
+          daemon: {
+            ...DEFAULT_DESKTOP_SETTINGS.daemon,
+            keepRunningAfterQuit: false,
+          },
+        },
+        daemonStatus: {
+          status: "running",
+          desktopManaged: true,
+        },
+      }),
+    ).toBe(true);
+  });
+
+  it("does not stop a manually started daemon on quit", async () => {
+    const stopDaemon = vi.fn(async () => undefined);
+
+    const stopped = await stopDesktopManagedDaemonOnQuitIfNeeded({
+      settingsStore: {
+        get: async () => ({
+          ...DEFAULT_DESKTOP_SETTINGS,
+          daemon: {
+            ...DEFAULT_DESKTOP_SETTINGS.daemon,
+            keepRunningAfterQuit: false,
+          },
+        }),
+        patch: async () => DEFAULT_DESKTOP_SETTINGS,
+        migrateLegacyRendererSettings: async () => DEFAULT_DESKTOP_SETTINGS,
+      },
+      resolveStatus: async () => ({
+        status: "running",
+        desktopManaged: false,
+      }),
+      stopDaemon,
+    });
+
+    expect(stopped).toBe(false);
+    expect(stopDaemon).not.toHaveBeenCalled();
+  });
+
+  it("gates quit until the stop decision completes, then lets the next quit pass through", async () => {
+    let resolveStopDecision: (() => void) | null = null;
+    const app = { quit: vi.fn() };
+    const closeTransportSessions = vi.fn();
+    const onStopError = vi.fn();
+    const preventDefault = vi.fn();
+    const secondPreventDefault = vi.fn();
+
+    const handleBeforeQuit = createBeforeQuitHandler({
+      app,
+      closeTransportSessions,
+      stopDesktopManagedDaemonIfNeeded: vi.fn(
+        () =>
+          new Promise<boolean>((resolve) => {
+            resolveStopDecision = () => resolve(false);
+          }),
+      ),
+      onStopError,
+    });
+
+    handleBeforeQuit({ preventDefault });
+
+    expect(preventDefault).toHaveBeenCalledTimes(1);
+    expect(closeTransportSessions).toHaveBeenCalledTimes(1);
+    expect(app.quit).not.toHaveBeenCalled();
+    expect(resolveStopDecision).not.toBeNull();
+
+    resolveStopDecision?.();
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(app.quit).toHaveBeenCalledTimes(1);
+    expect(onStopError).not.toHaveBeenCalled();
+
+    handleBeforeQuit({ preventDefault: secondPreventDefault });
+
+    expect(secondPreventDefault).not.toHaveBeenCalled();
+    expect(closeTransportSessions).toHaveBeenCalledTimes(2);
+    expect(app.quit).toHaveBeenCalledTimes(1);
+  });
+});

packages/desktop/src/daemon/quit-lifecycle.ts

@@ -0,0 +1,93 @@
+import type { DesktopSettingsStore } from "../settings/desktop-settings.js";
+
+interface QuitLifecycleSettings {
+  daemon: {
+    keepRunningAfterQuit: boolean;
+  };
+}
+
+interface QuitLifecycleStatus {
+  status: "starting" | "running" | "stopped" | "errored";
+  desktopManaged: boolean;
+}
+
+interface BeforeQuitEvent {
+  preventDefault(): void;
+}
+
+interface BeforeQuitApp {
+  quit(): void;
+}
+
+export function shouldStopDesktopManagedDaemonOnQuit({
+  settings,
+  daemonStatus,
+}: {
+  settings: QuitLifecycleSettings;
+  daemonStatus: QuitLifecycleStatus;
+}): boolean {
+  return (
+    settings.daemon.keepRunningAfterQuit === false &&
+    daemonStatus.status === "running" &&
+    daemonStatus.desktopManaged
+  );
+}
+
+export async function stopDesktopManagedDaemonOnQuitIfNeeded({
+  settingsStore,
+  resolveStatus,
+  stopDaemon,
+}: {
+  settingsStore: DesktopSettingsStore;
+  resolveStatus: () => Promise<QuitLifecycleStatus>;
+  stopDaemon: () => Promise<unknown>;
+}): Promise<boolean> {
+  const settings = await settingsStore.get();
+  const daemonStatus = await resolveStatus();
+
+  if (!shouldStopDesktopManagedDaemonOnQuit({ settings, daemonStatus })) {
+    return false;
+  }
+
+  await stopDaemon();
+  return true;
+}
+
+export function createBeforeQuitHandler({
+  app,
+  closeTransportSessions,
+  stopDesktopManagedDaemonIfNeeded,
+  onStopError,
+}: {
+  app: BeforeQuitApp;
+  closeTransportSessions: () => void;
+  stopDesktopManagedDaemonIfNeeded: () => Promise<boolean>;
+  onStopError: (error: unknown) => void;
+}): (event: BeforeQuitEvent) => void {
+  let allowingQuitToContinue = false;
+  let quittingInProgress = false;
+
+  return (event) => {
+    closeTransportSessions();
+
+    if (allowingQuitToContinue) {
+      return;
+    }
+
+    event.preventDefault();
+    if (quittingInProgress) {
+      return;
+    }
+
+    quittingInProgress = true;
+    void stopDesktopManagedDaemonIfNeeded()
+      .catch((error) => {
+        onStopError(error);
+      })
+      .finally(() => {
+        allowingQuitToContinue = true;
+        quittingInProgress = false;
+        app.quit();
+      });
+  };
+}

packages/desktop/src/main.ts

@@ -34,6 +34,12 @@ import {
 import { registerOpenerHandlers } from "./features/opener.js";
 import { setupApplicationMenu } from "./features/menu.js";
 import { parseOpenProjectPathFromArgv } from "./open-project-routing.js";
+import { getDesktopSettingsStore } from "./settings/desktop-settings-electron.js";
+import { resolveDesktopDaemonStatus, stopDesktopDaemon } from "./daemon/daemon-manager.js";
+import {
+  createBeforeQuitHandler,
+  stopDesktopManagedDaemonOnQuitIfNeeded,
+} from "./daemon/quit-lifecycle.js";
 
 const DEV_SERVER_URL = process.env.EXPO_DEV_URL ?? "http://localhost:8081";
 const APP_SCHEME = "paseo";
@@ -340,9 +346,22 @@ void bootstrap().catch((error) => {
   process.exit(1);
 });
 
-app.on("before-quit", () => {
-  closeAllTransportSessions();
-});
+app.on(
+  "before-quit",
+  createBeforeQuitHandler({
+    app,
+    closeTransportSessions: closeAllTransportSessions,
+    stopDesktopManagedDaemonIfNeeded: () =>
+      stopDesktopManagedDaemonOnQuitIfNeeded({
+        settingsStore: getDesktopSettingsStore(),
+        resolveStatus: resolveDesktopDaemonStatus,
+        stopDaemon: stopDesktopDaemon,
+      }),
+    onStopError: (error) => {
+      log.error("[desktop daemon] failed to stop managed daemon on quit", error);
+    },
+  }),
+);
 
 app.on("window-all-closed", () => {
   if (process.platform !== "darwin") {

packages/desktop/src/settings/desktop-settings-commands.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { DEFAULT_DESKTOP_SETTINGS, type DesktopSettingsStore } from "./desktop-settings";
+import { createDesktopSettingsCommandHandlers } from "./desktop-settings-commands";
+
+function createStoreMock(): DesktopSettingsStore {
+  return {
+    get: vi.fn(async () => DEFAULT_DESKTOP_SETTINGS),
+    patch: vi.fn(async () => ({
+      ...DEFAULT_DESKTOP_SETTINGS,
+      releaseChannel: "beta",
+    })),
+    migrateLegacyRendererSettings: vi.fn(async () => ({
+      ...DEFAULT_DESKTOP_SETTINGS,
+      releaseChannel: "beta",
+      daemon: {
+        manageBuiltInDaemon: false,
+        keepRunningAfterQuit: true,
+      },
+    })),
+  };
+}
+
+describe("desktop-settings-commands", () => {
+  it("exposes get and patch handlers through the desktop command bus shape", async () => {
+    const store = createStoreMock();
+    const handlers = createDesktopSettingsCommandHandlers({ settingsStore: store });
+
+    await expect(handlers.get_desktop_settings()).resolves.toEqual(DEFAULT_DESKTOP_SETTINGS);
+    await expect(
+      handlers.patch_desktop_settings({
+        daemon: { keepRunningAfterQuit: false },
+      }),
+    ).resolves.toEqual({
+      ...DEFAULT_DESKTOP_SETTINGS,
+      releaseChannel: "beta",
+    });
+
+    expect(store.get).toHaveBeenCalledTimes(1);
+    expect(store.patch).toHaveBeenCalledWith({
+      daemon: { keepRunningAfterQuit: false },
+    });
+  });
+
+  it("accepts legacy renderer settings migration payloads", async () => {
+    const store = createStoreMock();
+    const handlers = createDesktopSettingsCommandHandlers({ settingsStore: store });
+
+    const result = await handlers.migrate_legacy_desktop_settings({
+      releaseChannel: "beta",
+      manageBuiltInDaemon: false,
+    });
+
+    expect(result).toEqual({
+      ...DEFAULT_DESKTOP_SETTINGS,
+      releaseChannel: "beta",
+      daemon: {
+        manageBuiltInDaemon: false,
+        keepRunningAfterQuit: true,
+      },
+    });
+    expect(store.migrateLegacyRendererSettings).toHaveBeenCalledWith({
+      releaseChannel: "beta",
+      manageBuiltInDaemon: false,
+    });
+  });
+});

packages/desktop/src/settings/desktop-settings-commands.ts

@@ -0,0 +1,15 @@
+import type { DesktopSettingsStore } from "./desktop-settings.js";
+
+export type DesktopCommandHandler = (args?: Record<string, unknown>) => Promise<unknown> | unknown;
+
+export function createDesktopSettingsCommandHandlers({
+  settingsStore,
+}: {
+  settingsStore: DesktopSettingsStore;
+}): Record<string, DesktopCommandHandler> {
+  return {
+    get_desktop_settings: () => settingsStore.get(),
+    patch_desktop_settings: (args) => settingsStore.patch(args),
+    migrate_legacy_desktop_settings: (args) => settingsStore.migrateLegacyRendererSettings(args),
+  };
+}

packages/desktop/src/settings/desktop-settings-electron.ts

@@ -0,0 +1,12 @@
+import { app } from "electron";
+
+import { createDesktopSettingsStore, type DesktopSettingsStore } from "./desktop-settings.js";
+
+let desktopSettingsStore: DesktopSettingsStore | null = null;
+
+export function getDesktopSettingsStore(): DesktopSettingsStore {
+  desktopSettingsStore ??= createDesktopSettingsStore({
+    userDataPath: app.getPath("userData"),
+  });
+  return desktopSettingsStore;
+}

packages/desktop/src/settings/desktop-settings.test.ts

@@ -0,0 +1,127 @@
+import { mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import {
+  DEFAULT_DESKTOP_SETTINGS,
+  type DesktopSettings,
+  createDesktopSettingsStore,
+} from "./desktop-settings";
+
+async function createTempUserDataDir(): Promise<string> {
+  return await mkdtemp(path.join(os.tmpdir(), "paseo-desktop-settings-"));
+}
+
+function settingsFilePath(userDataPath: string): string {
+  return path.join(userDataPath, "desktop-settings.json");
+}
+
+describe("desktop-settings", () => {
+  const directories = new Set<string>();
+
+  afterEach(async () => {
+    await Promise.all(
+      [...directories].map(async (directory) => {
+        await rm(directory, { recursive: true, force: true });
+      }),
+    );
+    directories.clear();
+  });
+
+  it("persists default settings for new users", async () => {
+    const userDataPath = await createTempUserDataDir();
+    directories.add(userDataPath);
+    const store = createDesktopSettingsStore({ userDataPath });
+
+    const settings = await store.get();
+    const persisted = JSON.parse(await readFile(settingsFilePath(userDataPath), "utf8")) as {
+      settings: DesktopSettings;
+    };
+
+    expect(settings).toEqual(DEFAULT_DESKTOP_SETTINGS);
+    expect(persisted.settings).toEqual(DEFAULT_DESKTOP_SETTINGS);
+  });
+
+  it("coerces invalid persisted values back to safe defaults", async () => {
+    const userDataPath = await createTempUserDataDir();
+    directories.add(userDataPath);
+    await writeFile(
+      settingsFilePath(userDataPath),
+      JSON.stringify({
+        version: 1,
+        settings: {
+          releaseChannel: "nightly",
+          daemon: {
+            manageBuiltInDaemon: "sometimes",
+            keepRunningAfterQuit: false,
+          },
+        },
+      }),
+    );
+    const store = createDesktopSettingsStore({ userDataPath });
+
+    const settings = await store.get();
+
+    expect(settings).toEqual({
+      releaseChannel: "stable",
+      daemon: {
+        manageBuiltInDaemon: true,
+        keepRunningAfterQuit: false,
+      },
+    });
+  });
+
+  it("patches nested settings and leaves no temp files behind", async () => {
+    const userDataPath = await createTempUserDataDir();
+    directories.add(userDataPath);
+    const store = createDesktopSettingsStore({ userDataPath });
+
+    await store.get();
+    const next = await store.patch({
+      releaseChannel: "beta",
+      daemon: { keepRunningAfterQuit: false },
+    });
+    const files = await readdir(userDataPath);
+
+    expect(next).toEqual({
+      releaseChannel: "beta",
+      daemon: {
+        manageBuiltInDaemon: true,
+        keepRunningAfterQuit: false,
+      },
+    });
+    expect(files).toEqual(["desktop-settings.json"]);
+  });
+
+  it("migrates desktop-owned values from legacy renderer settings once", async () => {
+    const userDataPath = await createTempUserDataDir();
+    directories.add(userDataPath);
+    const store = createDesktopSettingsStore({ userDataPath });
+
+    await store.patch({
+      daemon: {
+        keepRunningAfterQuit: false,
+      },
+    });
+
+    const migrated = await store.migrateLegacyRendererSettings({
+      releaseChannel: "beta",
+      manageBuiltInDaemon: false,
+      theme: "dark",
+    });
+    const ignoredSecondMigration = await store.migrateLegacyRendererSettings({
+      releaseChannel: "stable",
+      manageBuiltInDaemon: true,
+    });
+
+    expect(migrated).toEqual({
+      releaseChannel: "beta",
+      daemon: {
+        manageBuiltInDaemon: false,
+        keepRunningAfterQuit: false,
+      },
+    });
+    expect(ignoredSecondMigration).toEqual(migrated);
+  });
+});

packages/desktop/src/settings/desktop-settings.ts

@@ -0,0 +1,261 @@
+import { access, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import type { AppReleaseChannel } from "../features/auto-updater.js";
+
+export interface DesktopSettings {
+  releaseChannel: AppReleaseChannel;
+  daemon: {
+    manageBuiltInDaemon: boolean;
+    keepRunningAfterQuit: boolean;
+  };
+}
+
+interface DesktopSettingsPatch {
+  releaseChannel?: AppReleaseChannel;
+  daemon?: Partial<DesktopSettings["daemon"]>;
+}
+
+interface PersistedDesktopSettingsDocument {
+  version: 1;
+  settings: DesktopSettings;
+  migrations: {
+    legacyRendererSettingsImported: boolean;
+  };
+}
+
+export interface DesktopSettingsStore {
+  get(): Promise<DesktopSettings>;
+  patch(patch: unknown): Promise<DesktopSettings>;
+  migrateLegacyRendererSettings(legacySettings: unknown): Promise<DesktopSettings>;
+}
+
+export const DEFAULT_DESKTOP_SETTINGS: DesktopSettings = {
+  releaseChannel: "stable",
+  daemon: {
+    manageBuiltInDaemon: true,
+    keepRunningAfterQuit: true,
+  },
+};
+
+const DESKTOP_SETTINGS_FILENAME = "desktop-settings.json";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function coerceReleaseChannel(value: unknown): AppReleaseChannel | null {
+  if (value === "beta") {
+    return "beta";
+  }
+  if (value === "stable") {
+    return "stable";
+  }
+  return null;
+}
+
+function coerceBoolean(value: unknown): boolean | null {
+  return typeof value === "boolean" ? value : null;
+}
+
+function buildDefaultDocument(): PersistedDesktopSettingsDocument {
+  return {
+    version: 1,
+    settings: DEFAULT_DESKTOP_SETTINGS,
+    migrations: {
+      legacyRendererSettingsImported: false,
+    },
+  };
+}
+
+function coerceDesktopSettings(input: unknown): DesktopSettings {
+  const result: DesktopSettings = {
+    releaseChannel: DEFAULT_DESKTOP_SETTINGS.releaseChannel,
+    daemon: { ...DEFAULT_DESKTOP_SETTINGS.daemon },
+  };
+
+  if (!isRecord(input)) {
+    return result;
+  }
+
+  const releaseChannel = coerceReleaseChannel(input.releaseChannel);
+  if (releaseChannel) {
+    result.releaseChannel = releaseChannel;
+  }
+
+  if (isRecord(input.daemon)) {
+    const manageBuiltInDaemon = coerceBoolean(input.daemon.manageBuiltInDaemon);
+    if (manageBuiltInDaemon !== null) {
+      result.daemon.manageBuiltInDaemon = manageBuiltInDaemon;
+    }
+
+    const keepRunningAfterQuit = coerceBoolean(input.daemon.keepRunningAfterQuit);
+    if (keepRunningAfterQuit !== null) {
+      result.daemon.keepRunningAfterQuit = keepRunningAfterQuit;
+    }
+  }
+
+  return result;
+}
+
+function coerceDesktopSettingsPatch(input: unknown): DesktopSettingsPatch {
+  if (!isRecord(input)) {
+    return {};
+  }
+
+  const patch: DesktopSettingsPatch = {};
+
+  const releaseChannel = coerceReleaseChannel(input.releaseChannel);
+  if (releaseChannel) {
+    patch.releaseChannel = releaseChannel;
+  }
+
+  if (isRecord(input.daemon)) {
+    const daemonPatch: Partial<DesktopSettings["daemon"]> = {};
+    const manageBuiltInDaemon = coerceBoolean(input.daemon.manageBuiltInDaemon);
+    if (manageBuiltInDaemon !== null) {
+      daemonPatch.manageBuiltInDaemon = manageBuiltInDaemon;
+    }
+    const keepRunningAfterQuit = coerceBoolean(input.daemon.keepRunningAfterQuit);
+    if (keepRunningAfterQuit !== null) {
+      daemonPatch.keepRunningAfterQuit = keepRunningAfterQuit;
+    }
+    if (Object.keys(daemonPatch).length > 0) {
+      patch.daemon = daemonPatch;
+    }
+  }
+
+  return patch;
+}
+
+function pickDesktopSettingsFromLegacyRendererSettings(
+  legacySettings: unknown,
+): DesktopSettingsPatch {
+  if (!isRecord(legacySettings)) {
+    return {};
+  }
+
+  const patch: DesktopSettingsPatch = {};
+  const releaseChannel = coerceReleaseChannel(legacySettings.releaseChannel);
+  if (releaseChannel) {
+    patch.releaseChannel = releaseChannel;
+  }
+
+  const manageBuiltInDaemon = coerceBoolean(legacySettings.manageBuiltInDaemon);
+  if (manageBuiltInDaemon !== null) {
+    patch.daemon = { manageBuiltInDaemon };
+  }
+
+  return patch;
+}
+
+function mergeDesktopSettings(
+  current: DesktopSettings,
+  patch: DesktopSettingsPatch,
+): DesktopSettings {
+  return {
+    releaseChannel: patch.releaseChannel ?? current.releaseChannel,
+    daemon: { ...current.daemon, ...patch.daemon },
+  };
+}
+
+function coerceDocument(input: unknown): PersistedDesktopSettingsDocument {
+  if (!isRecord(input)) {
+    return buildDefaultDocument();
+  }
+
+  const settings = coerceDesktopSettings(input.settings);
+  const migrations = isRecord(input.migrations)
+    ? {
+        legacyRendererSettingsImported: input.migrations.legacyRendererSettingsImported === true,
+      }
+    : {
+        legacyRendererSettingsImported: false,
+      };
+
+  return {
+    version: 1,
+    settings,
+    migrations,
+  };
+}
+
+export function createDesktopSettingsStore({
+  userDataPath,
+}: {
+  userDataPath: string;
+}): DesktopSettingsStore {
+  const filePath = path.join(userDataPath, DESKTOP_SETTINGS_FILENAME);
+  let cachedDocument: PersistedDesktopSettingsDocument | null = null;
+
+  async function persistDocument(document: PersistedDesktopSettingsDocument): Promise<void> {
+    await mkdir(userDataPath, { recursive: true });
+    const tempFilePath = `${filePath}.tmp`;
+    await writeFile(tempFilePath, `${JSON.stringify(document, null, 2)}\n`, "utf8");
+    await rename(tempFilePath, filePath);
+    cachedDocument = document;
+  }
+
+  async function loadDocument(): Promise<PersistedDesktopSettingsDocument> {
+    if (cachedDocument) {
+      return cachedDocument;
+    }
+
+    try {
+      await access(filePath);
+    } catch {
+      const document = buildDefaultDocument();
+      await persistDocument(document);
+      return document;
+    }
+
+    try {
+      const raw = await readFile(filePath, "utf8");
+      const document = coerceDocument(JSON.parse(raw));
+      await persistDocument(document);
+      return document;
+    } catch {
+      const document = buildDefaultDocument();
+      await persistDocument(document);
+      return document;
+    }
+  }
+
+  return {
+    async get(): Promise<DesktopSettings> {
+      const document = await loadDocument();
+      return document.settings;
+    },
+
+    async patch(patch: unknown): Promise<DesktopSettings> {
+      const current = await loadDocument();
+      const next = mergeDesktopSettings(current.settings, coerceDesktopSettingsPatch(patch));
+      await persistDocument({
+        ...current,
+        settings: next,
+      });
+      return next;
+    },
+
+    async migrateLegacyRendererSettings(legacySettings: unknown): Promise<DesktopSettings> {
+      const current = await loadDocument();
+      if (current.migrations.legacyRendererSettingsImported) {
+        return current.settings;
+      }
+
+      const next = mergeDesktopSettings(
+        current.settings,
+        pickDesktopSettingsFromLegacyRendererSettings(legacySettings),
+      );
+      await persistDocument({
+        ...current,
+        settings: next,
+        migrations: {
+          ...current.migrations,
+          legacyRendererSettingsImported: true,
+        },
+      });
+      return next;
+    },
+  };
+}