@aiworker/web 1.22.2 → 1.23.0

package/server/lib/network-defaults.js

@@ -0,0 +1,23 @@
+import net from 'node:net';
+
+// Node caps each happy-eyeballs connect attempt at 250ms by default
+// (autoSelectFamilyAttemptTimeout). TCP handshakes to provider endpoints that are
+// geographically distant routinely take 300-1500ms, so fetch() from a Node process
+// aborts every attempt (ETIMEDOUT) and surfaces "fetch failed" even though the host
+// is reachable — e.g. the z.ai quota endpoint from an IPv4-only egress (#3399).
+//
+// Every Node process entrypoint that performs provider fetches raises the
+// per-attempt cap. Family autoselection itself stays enabled, so the IPv6→IPv4
+// fallback and ::1/localhost servers keep working; disabling it instead breaks
+// local MCP servers. Runtimes without the setter (Bun's fetch path, older Node)
+// are a no-op.
+export const CONNECT_ATTEMPT_TIMEOUT_MS = 5_000;
+
+export const applyConnectAttemptTimeout = (netModule = net) => {
+  try {
+    netModule.setDefaultAutoSelectFamilyAttemptTimeout(CONNECT_ATTEMPT_TIMEOUT_MS);
+    return true;
+  } catch {
+    return false;
+  }
+};

package/server/lib/network-defaults.test.js

@@ -0,0 +1,52 @@
+import { describe, expect, it, vi } from 'vitest';
+import net from 'node:net';
+import { spawnSync } from 'node:child_process';
+
+import { applyConnectAttemptTimeout, CONNECT_ATTEMPT_TIMEOUT_MS } from './network-defaults.js';
+
+describe('applyConnectAttemptTimeout', () => {
+  it('initializes the server entrypoint in a fresh Node process', () => {
+    const serverUrl = new URL('../index.js', import.meta.url).href;
+    const result = spawnSync('node', ['--input-type=module', '--eval', `
+      import net from 'node:net';
+      import assert from 'node:assert/strict';
+      const family = net.getDefaultAutoSelectFamily();
+      net.setDefaultAutoSelectFamilyAttemptTimeout(250);
+      await import(${JSON.stringify(serverUrl)});
+      assert.equal(net.getDefaultAutoSelectFamilyAttemptTimeout(), 5000);
+      assert.equal(net.getDefaultAutoSelectFamily(), family);
+      process.exit(0);
+    `], { encoding: 'utf8', timeout: 15_000, windowsHide: true });
+    expect(result.status, result.stderr).toBe(0);
+  });
+
+  it('raises the per-attempt connect timeout on runtimes that expose the setter', () => {
+    const previous = net.getDefaultAutoSelectFamilyAttemptTimeout();
+    try {
+      expect(applyConnectAttemptTimeout()).toBe(true);
+      expect(net.getDefaultAutoSelectFamilyAttemptTimeout()).toBe(CONNECT_ATTEMPT_TIMEOUT_MS);
+    } finally {
+      net.setDefaultAutoSelectFamilyAttemptTimeout(previous);
+    }
+  });
+
+  it('is a no-op on runtimes without the setter', () => {
+    expect(applyConnectAttemptTimeout({})).toBe(false);
+  });
+
+  it('survives a throwing setter', () => {
+    const setDefaultAutoSelectFamilyAttemptTimeout = vi.fn(() => {
+      throw new Error('not supported');
+    });
+    expect(applyConnectAttemptTimeout({ setDefaultAutoSelectFamilyAttemptTimeout })).toBe(false);
+  });
+
+  it('leaves family autoselection itself untouched', () => {
+    const setDefaultAutoSelectFamily = vi.fn();
+    const setDefaultAutoSelectFamilyAttemptTimeout = vi.fn();
+    applyConnectAttemptTimeout({ setDefaultAutoSelectFamily, setDefaultAutoSelectFamilyAttemptTimeout });
+    expect(setDefaultAutoSelectFamilyAttemptTimeout).toHaveBeenCalledTimes(1);
+    expect(setDefaultAutoSelectFamilyAttemptTimeout).toHaveBeenCalledWith(CONNECT_ATTEMPT_TIMEOUT_MS);
+    expect(setDefaultAutoSelectFamily).not.toHaveBeenCalled();
+  });
+});

package/server/lib/opencode/DOCUMENTATION.md

@@ -212,7 +212,12 @@ Managed health failures are classified as `timeout`, `connection_refused`, `conn
   - `persistSettings(changes)`
 - Persistent permission auto-accept policy is stored under `permissionAutoAccept`; execution ownership lives in `lib/permission-auto-accept/`.
 - Queued follow-up messages live in `<data-dir>/message-queue.json`, not in settings; execution ownership lives in `lib/message-queue/`.
-- Shared sidebar preferences are stored as validated top-level fields: `sidebarProjectDisplayMode`, `sidebarSessionGroupingMode`, `sidebarProjectSortOrder`, and `sidebarShowRecentSection`. Device-local picker selection and sticky-header state do not enter `settings.json`.
+- Shared sidebar preferences are stored as validated top-level fields: `sidebarProjectDisplayMode`, `sidebarSessionGroupingMode`, `sidebarProjectSortOrder`, and `sidebarShowRecentSection`. Device-local picker selection and sticky-header state do not enter either settings file.
+- Two files (`settings-files.js`): `settings.json` holds instance facts and any legacy or unknown keys; `preferences.json` beside it holds every key the generated registry snapshot (`settings-registry.json`) marks `profile`, as `{ version: 1, fields: { key: { value, updatedAt, surfaces? } } }`. Keys the snapshot marks `perSurface` are stored per surface kind: `GET`/`PUT /api/config/settings` read the client's kind from the `surface` query parameter (`settingsSurfaceOf`; the legacy `x-openchamber-surface` header is still honoured, but a header forces a CORS preflight that cross-origin shells and older instances refuse, so clients must not send one) (`web`, `desktop`, `vscode`, `mobile`; anything else means base), `persistSettings(changes, { surface })` writes a changed per-surface key under `surfaces[surface]` and never touches its base, and `readSettingsFromDisk({ surface })` resolves that kind's value first, the base otherwise. Callers without a surface (migrations, the seed, server-side feature writers) read and write the base. `readSettingsFromDisk()` returns the merged document and seeds `preferences.json` once from an existing `settings.json` (which it leaves intact). An existing `preferences.json` that fails to parse is a failure, not an empty profile: it is never seeded or overwritten, the merged read serves the instance part, and `persistSettings` drops profile keys with a warning until the file is fixed or removed. `writeSettingsToDisk(document)` splits by scope and writes `settings.json` as the instance part plus a copy of the profile's base values (`legacySettingsDocumentOf`): a build from before the split reads only that file, so a rollback keeps the user's preferences, while current builds ignore the copy because `preferences.json` wins in the merge; device keys are dropped from writes. Modules that read one profile key off the disk on a hot path use `readMergedSettingsSync`.
+
+## Public exports (settings-files.js)
+- `parsePreferencesDocument(raw)`, `serializePreferencesDocument(fields)`, `flattenPreferences(fields)`, `buildPreferencesFields(previousFields, document, now)`, `instancePartOf(document)`, `seedPreferencesFrom(document, now)`, `readMergedSettingsSync({ fs, path, settingsFilePath })`, `getSettingsScope(key)`, `isProfileSettingsKey(key)`, `isDeviceSettingsKey(key)`, `preferencesFilePathFor(settingsFilePath, path)`.
+- The VS Code extension host writes the same two files with the same shape (`packages/vscode/src/settings-files.ts`); format changes go to both.
 
 ## Public exports (settings-helpers.js)
 - `createSettingsHelpers(dependencies)`: creates settings helper runtime for settings request/response shaping.
@@ -363,9 +368,20 @@ before starting managed OpenCode. The managed custom tool therefore receives
 an authoritative loopback callback URL even when AiWorker binds port `0`.
 
 ## Public exports (openchamber-routes.js)
+Browser completion checks use `appType=web&updateStatus=true` to stay on the
+Desktop Host's native updater. A rejected native restart is retained in the
+server process and returned to these polls as `DESKTOP_UPDATE_RESTART_FAILED`;
+ordinary availability checks remain usable so a browser reload can offer a
+retry. Starting another installation clears the previous restart error.
+The shared UI's `lib/web-update.ts` parses install/check responses and waits
+for the installed native target version, rather than treating absence of a
+newer release as installation success. Poll requests have individual deadlines
+within a ten-minute overall deadline.
+
 - `registerAiWorkerRoutes(app, dependencies)`: registers AiWorker endpoints:
   - `GET /api/openchamber/update-check`
   - `POST /api/openchamber/update-install`
+    - Desktop-managed hosts delegate authenticated Web update requests to the Electron main process, which checks, downloads, and applies the update through `electron-updater` before restarting the host.
     - Foreground servers running under a systemd user unit queue installation in
       a separate transient unit and restart the configured service afterwards.
       `AIWORKER_SYSTEMD_UNIT` overrides the default `aiworker.service`.

package/server/lib/opencode/bootstrap-runtime.js

@@ -63,6 +63,7 @@ export const createBootstrapRuntime = (dependencies) => {
       getCachedZenModels,
       setAutoAcceptSession,
       agentToolRuntime,
+      desktopUpdater,
     } = options;
 
     const uiAuthController = createUiAuth({
@@ -153,6 +154,7 @@ export const createBootstrapRuntime = (dependencies) => {
       readSettingsFromDiskMigrated,
       fetchFreeZenModels,
       getCachedZenModels,
+      desktopUpdater,
     });
 
     return {

package/server/lib/opencode/feature-routes-runtime.js

@@ -10,6 +10,7 @@ import { registerDevServerRoutes } from '../dev-servers/routes.js';
 import { registerMagicPromptRoutes } from '../magic-prompts/routes.js';
 import { registerSessionFoldersRoutes } from '../session-folders/routes.js';
 import { registerProjectContextRoutes } from '../project-context/routes.js';
+import { registerProjectSetupRoutes } from '../projects/routes.js';
 import { registerAgentMemoryRoutes } from '../agent-memory/routes.js';
 import { registerSessionKnowledgeRoutes } from '../session-knowledge/routes.js';
 import { registerPermissionAutoAcceptRoutes } from '../permission-auto-accept/runtime.js';
@@ -314,6 +315,7 @@ export const createFeatureRoutesRuntime = (dependencies) => {
       aiworkerDataDir,
     });
     registerProjectContextRoutes(app, { projectContextRuntime });
+    registerProjectSetupRoutes(app, { projectConfigRuntime });
     registerAgentMemoryRoutes(app, { agentMemoryRuntime, isAgentMemoryEnabled });
     registerSessionKnowledgeRoutes(app, { sessionKnowledgeRuntime });
 

package/server/lib/opencode/openchamber-routes.js

@@ -29,11 +29,13 @@ export const registerAiWorkerRoutes = (app, dependencies) => {
     readSettingsFromDiskMigrated,
     fetchFreeZenModels,
     getCachedZenModels,
+    desktopUpdater,
   } = dependencies;
 
+  let desktopRestartError = null;
+
   app.get('/api/openchamber/update-check', async (req, res) => {
     try {
-      const { checkForUpdates } = await import('../package-manager.js');
       const parseString = (value) => (typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined);
       const parseReportUsage = (value) => {
         if (typeof value !== 'string') return true;
@@ -49,8 +51,7 @@ export const registerAiWorkerRoutes = (app, dependencies) => {
         return 'desktop';
       };
       const userAgent = typeof req.headers['user-agent'] === 'string' ? req.headers['user-agent'] : '';
-
-      const updateInfo = await checkForUpdates({
+      const updateRequest = {
         appType: parseString(req.query.appType),
         deviceClass: parseString(req.query.deviceClass) || inferDeviceClass(userAgent),
         platform: parseString(req.query.platform),
@@ -59,7 +60,31 @@ export const registerAiWorkerRoutes = (app, dependencies) => {
         currentVersion: parseString(req.query.currentVersion),
         installId: parseString(req.query.installId),
         reportUsage: parseReportUsage(parseString(req.query.reportUsage)),
-      });
+      };
+      let updateInfo;
+      if (process.env.AIWORKER_RUNTIME === 'desktop' && updateRequest.appType === 'web') {
+        if (desktopRestartError && req.query.updateStatus === 'true') {
+          return res.status(503).json({
+            code: 'DESKTOP_UPDATE_RESTART_FAILED',
+            error: desktopRestartError,
+          });
+        }
+        if (typeof desktopUpdater?.check !== 'function') {
+          return res.status(503).json({
+            available: false,
+            code: 'DESKTOP_UPDATER_UNAVAILABLE',
+            error: 'The desktop updater is not available.',
+          });
+        }
+        updateInfo = {
+          ...await desktopUpdater.check(),
+          packageManager: 'electron',
+          updateOwner: 'electron-updater',
+        };
+      } else {
+        const { checkForUpdates } = await import('../package-manager.js');
+        updateInfo = await checkForUpdates(updateRequest);
+      }
       res.json(updateInfo);
     } catch (error) {
       console.error('Failed to check for updates:', error);
@@ -72,6 +97,41 @@ export const registerAiWorkerRoutes = (app, dependencies) => {
 
   app.post('/api/openchamber/update-install', async (_req, res) => {
     try {
+      if (process.env.AIWORKER_RUNTIME === 'desktop') {
+        if (typeof desktopUpdater?.install !== 'function' || typeof desktopUpdater?.restart !== 'function') {
+          return res.status(503).json({
+            code: 'DESKTOP_UPDATER_UNAVAILABLE',
+            error: 'The desktop updater is not available.',
+          });
+        }
+
+        desktopRestartError = null;
+        const updateInfo = await desktopUpdater.install();
+        if (!updateInfo?.available) {
+          return res.status(400).json({ error: 'No update available' });
+        }
+
+        res.json({
+          success: true,
+          message: 'Desktop update downloaded, host will restart shortly',
+          version: updateInfo.version,
+          packageManager: 'electron',
+          updateOwner: 'electron-updater',
+          autoRestart: true,
+          restartManager: 'electron-updater',
+        });
+
+        setImmediate(() => {
+          Promise.resolve()
+            .then(() => desktopUpdater.restart())
+            .catch((error) => {
+              desktopRestartError = error instanceof Error ? error.message : 'Failed to restart after desktop update';
+              console.error('Failed to restart after desktop update:', error);
+            });
+        });
+        return;
+      }
+
       const { spawn: spawnChild, spawnSync } = await import('child_process');
       const {
         checkForUpdates,

package/server/lib/opencode/openchamber-routes.test.js

@@ -18,7 +18,7 @@ const childProcess = await import('child_process');
 const packageManager = await import('../package-manager.js');
 const { registerAiWorkerRoutes } = await import('./openchamber-routes.js');
 
-const createApp = ({ environment = {}, storedOptions = {} } = {}) => {
+const createApp = ({ environment = {}, storedOptions = {}, desktopUpdater } = {}) => {
   const app = express();
   const dependencies = {
     fs: {
@@ -47,6 +47,7 @@ const createApp = ({ environment = {}, storedOptions = {} } = {}) => {
     readSettingsFromDiskMigrated: vi.fn(),
     fetchFreeZenModels: vi.fn(),
     getCachedZenModels: vi.fn(),
+    desktopUpdater,
   };
 
   registerAiWorkerRoutes(app, dependencies);
@@ -69,6 +70,132 @@ afterEach(() => {
   vi.clearAllMocks();
 });
 
+describe('AiWorker desktop host update route', () => {
+  it('reports a restart rejection until the user retries installation', async () => {
+    const desktopUpdater = {
+      check: vi.fn(async () => ({ available: true, currentVersion: '1.17.0', version: '1.17.1' })),
+      install: vi.fn(async () => ({ available: true, version: '1.17.1' })),
+      restart: vi.fn().mockRejectedValueOnce(new Error('Signature rejected')).mockResolvedValue(undefined),
+    };
+    const { app } = createApp({ environment: { AIWORKER_RUNTIME: 'desktop' }, desktopUpdater });
+    const logError = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    await request(app).post('/api/openchamber/update-install').expect(200);
+    await new Promise(resolve => setImmediate(resolve));
+    await request(app).get('/api/openchamber/update-check?appType=web&reportUsage=false&updateStatus=true').expect(503, {
+      code: 'DESKTOP_UPDATE_RESTART_FAILED', error: 'Signature rejected',
+    });
+    expect(desktopUpdater.check).not.toHaveBeenCalled();
+    expect(logError).toHaveBeenCalledOnce();
+    // Availability remains reachable after a browser reload, so users can retry.
+    await request(app).get('/api/openchamber/update-check?appType=web&reportUsage=false').expect(200);
+
+    await request(app).post('/api/openchamber/update-install').expect(200);
+    await new Promise(resolve => setImmediate(resolve));
+    const response = await request(app).get('/api/openchamber/update-check?appType=web&reportUsage=false').expect(200);
+    expect(response.body.currentVersion).toBe('1.17.0');
+    expect(response.body.updateOwner).toBe('electron-updater');
+    expect(packageManager.checkForUpdates).not.toHaveBeenCalled();
+  });
+
+  it('rejects native checks without a bridge and preserves explicit non-web checks', async () => {
+    const { app } = createApp({ environment: { AIWORKER_RUNTIME: 'desktop' } });
+    await request(app).get('/api/openchamber/update-check?appType=web').expect(503, {
+      available: false, code: 'DESKTOP_UPDATER_UNAVAILABLE', error: 'The desktop updater is not available.',
+    });
+    expect(packageManager.checkForUpdates).not.toHaveBeenCalled();
+    await request(app).get('/api/openchamber/update-check?appType=desktop-electron').expect(200);
+    expect(packageManager.checkForUpdates).toHaveBeenCalledOnce();
+  });
+
+  it('uses electron-updater to check for Web client updates', async () => {
+    const desktopUpdater = {
+      check: vi.fn(async () => ({
+        available: true,
+        currentVersion: '1.17.0',
+        version: '1.17.1',
+      })),
+      install: vi.fn(),
+      restart: vi.fn(),
+    };
+    const { app } = createApp({
+      environment: {
+        AIWORKER_RUNTIME: 'desktop',
+      },
+      desktopUpdater,
+    });
+
+    await request(app)
+      .get('/api/openchamber/update-check?appType=web&reportUsage=false')
+      .expect(200, {
+        available: true,
+        currentVersion: '1.17.0',
+        version: '1.17.1',
+        packageManager: 'electron',
+        updateOwner: 'electron-updater',
+      });
+
+    expect(desktopUpdater.check).toHaveBeenCalledOnce();
+    expect(packageManager.checkForUpdates).not.toHaveBeenCalled();
+  });
+
+  it('installs through electron-updater and restarts after responding', async () => {
+    const desktopUpdater = {
+      check: vi.fn(),
+      install: vi.fn(async () => ({
+        available: true,
+        version: '1.17.1',
+      })),
+      restart: vi.fn(),
+    };
+    const { app } = createApp({
+      environment: {
+        AIWORKER_RUNTIME: 'desktop',
+      },
+      desktopUpdater,
+    });
+
+    await request(app)
+      .post('/api/openchamber/update-install')
+      .expect(200, {
+        success: true,
+        message: 'Desktop update downloaded, host will restart shortly',
+        version: '1.17.1',
+        packageManager: 'electron',
+        updateOwner: 'electron-updater',
+        autoRestart: true,
+        restartManager: 'electron-updater',
+      });
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(desktopUpdater.install).toHaveBeenCalledOnce();
+    expect(desktopUpdater.restart).toHaveBeenCalledOnce();
+    expect(packageManager.checkForUpdates).not.toHaveBeenCalled();
+    expect(packageManager.detectPackageManagerDetails).not.toHaveBeenCalled();
+    expect(packageManager.getUpdateCommand).not.toHaveBeenCalled();
+    expect(childProcess.spawn).not.toHaveBeenCalled();
+    expect(childProcess.spawnSync).not.toHaveBeenCalled();
+  });
+
+  it('fails safely when the Electron updater bridge is unavailable', async () => {
+    const { app } = createApp({
+      environment: {
+        AIWORKER_RUNTIME: 'desktop',
+      },
+    });
+
+    await request(app)
+      .post('/api/openchamber/update-install')
+      .expect(503, {
+        code: 'DESKTOP_UPDATER_UNAVAILABLE',
+        error: 'The desktop updater is not available.',
+      });
+
+    expect(packageManager.checkForUpdates).not.toHaveBeenCalled();
+    expect(childProcess.spawn).not.toHaveBeenCalled();
+  });
+});
+
 describe('AiWorker foreground update route', () => {
   it('rejects a foreground update when the server is not owned by systemd', async () => {
     const { app } = createApp();

package/server/lib/opencode/routes.js

@@ -7,6 +7,7 @@ import {
 } from './config-mutation-response.js';
 import { getClaudeCliAuthStatus } from './claude-cli-auth.js';
 import { OPENCODE_CONFIG_DIR } from './shared.js';
+import { settingsSurfaceOf } from './settings-files.js';
 
 export const registerOpenCodeRoutes = (app, dependencies) => {
   const {
@@ -208,9 +209,10 @@ ${desktopReturn ? `<a class="return" href="aiworker://focus/mcp-auth">Return to
     }
   };
 
-  app.get('/api/config/settings', async (_req, res) => {
+  app.get('/api/config/settings', async (req, res) => {
     try {
-      const settings = await readSettingsFromDiskMigrated();
+      // The surface kind resolves the per-surface profile keys; absent means base.
+      const settings = await readSettingsFromDiskMigrated({ surface: settingsSurfaceOf(req) });
       res.json(formatSettingsResponse(settings));
     } catch (error) {
       console.error('Failed to read settings:', error);
@@ -422,7 +424,7 @@ ${desktopReturn ? `<a class="return" href="aiworker://focus/mcp-auth">Return to
 
   app.put('/api/config/settings', async (req, res) => {
     try {
-      const updated = await persistSettings(req.body ?? {});
+      const updated = await persistSettings(req.body ?? {}, { surface: settingsSurfaceOf(req) });
       res.json(updated);
     } catch (error) {
       console.error('[API:PUT /api/config/settings] Failed to save settings:', error);

package/server/lib/opencode/settings-files.js

@@ -0,0 +1,214 @@
+// The two settings files and how a merged document is split between them.
+//
+// `settings.json` holds instance facts (and, untouched, whatever legacy keys
+// older builds left there). `preferences.json` holds the user's profile: the
+// keys the settings registry marks `profile`, each with the time the store
+// last accepted a new value for it. Device keys never reach either file.
+//
+// The VS Code extension host writes the same two files with the same shape
+// (`packages/vscode/src/settings-files.ts`); keep the format changes in sync.
+import { createRequire } from 'node:module';
+
+const registry = createRequire(import.meta.url)('./settings-registry.json');
+
+const PREFERENCES_FILE_NAME = 'preferences.json';
+const PREFERENCES_DOCUMENT_VERSION = 1;
+
+/** The registry scope for a key, or `null` when the registry does not know it. */
+const getSettingsScope = (key) => registry.fields[key]?.scope ?? null;
+
+export const isProfileSettingsKey = (key) => getSettingsScope(key) === 'profile';
+export const isDeviceSettingsKey = (key) => getSettingsScope(key) === 'device';
+
+/** Profile keys the owner chose to store per surface kind (a change on a phone stays on phones). */
+const isPerSurfaceSettingsKey = (key) => registry.fields[key]?.perSurface === true;
+
+const SETTINGS_SURFACES = Object.freeze(['web', 'desktop', 'vscode', 'mobile']);
+
+export const normalizeSettingsSurface = (value) => (
+  typeof value === 'string' && SETTINGS_SURFACES.includes(value.trim()) ? value.trim() : null
+);
+
+/**
+ * Which surface kind a settings request comes from; `null` means "base".
+ * Clients send `?surface=<kind>` (a query parameter keeps the request
+ * CORS-simple for cross-origin shells and older instances); the
+ * `x-openchamber-surface` header is still honoured for clients that sent it.
+ */
+export const settingsSurfaceOf = (req) => (
+  normalizeSettingsSurface(req.query?.surface) ?? normalizeSettingsSurface(req.get?.('x-openchamber-surface'))
+);
+
+export const preferencesFilePathFor = (settingsFilePath, path) => path.join(path.dirname(settingsFilePath), PREFERENCES_FILE_NAME);
+
+const isPlainObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const sameValue = (left, right) => {
+  if (left === right) return true;
+  if (left === undefined || right === undefined) return false;
+  return JSON.stringify(left) === JSON.stringify(right);
+};
+
+const parseStamp = (value) => (Number.isFinite(value) ? value : 0);
+
+/**
+ * Parse the text of a preferences file. A missing file is the caller's case
+ * (ENOENT); anything that is not a version-1 document with a `fields` object
+ * is a failure, never an empty profile.
+ *
+ * An entry is `{ value, updatedAt }` for the base value, optionally with
+ * `surfaces: { [surface]: { value, updatedAt } }` for per-surface keys; a
+ * per-surface key that was only ever set from one surface kind has no base.
+ */
+export const parsePreferencesDocument = (raw) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    return { ok: false, reason: `invalid JSON: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  if (!isPlainObject(parsed) || parsed.version !== PREFERENCES_DOCUMENT_VERSION || !isPlainObject(parsed.fields)) {
+    return { ok: false, reason: 'not a version-1 preferences document' };
+  }
+  const fields = {};
+  for (const [key, entry] of Object.entries(parsed.fields)) {
+    if (!isPlainObject(entry) || (!('value' in entry) && !isPlainObject(entry.surfaces))) {
+      return { ok: false, reason: `field "${key}" is not a { value, updatedAt } entry` };
+    }
+    const next = { updatedAt: parseStamp(entry.updatedAt) };
+    if ('value' in entry) next.value = entry.value;
+    if (isPlainObject(entry.surfaces)) {
+      next.surfaces = {};
+      for (const [surface, surfaceEntry] of Object.entries(entry.surfaces)) {
+        if (!SETTINGS_SURFACES.includes(surface) || !isPlainObject(surfaceEntry) || !('value' in surfaceEntry)) {
+          return { ok: false, reason: `field "${key}" has an invalid surface entry "${surface}"` };
+        }
+        next.surfaces[surface] = { value: surfaceEntry.value, updatedAt: parseStamp(surfaceEntry.updatedAt) };
+      }
+    }
+    fields[key] = next;
+  }
+  return { ok: true, fields };
+};
+
+export const serializePreferencesDocument = (fields) => JSON.stringify({ version: PREFERENCES_DOCUMENT_VERSION, fields }, null, 2);
+
+/**
+ * The plain key → value view of preference fields as one surface kind sees it:
+ * that surface's own value first, the base value otherwise; a key with neither
+ * is absent (the client keeps what it holds, or its default).
+ */
+export const flattenPreferences = (fields, surface = null) => {
+  const values = {};
+  for (const [key, entry] of Object.entries(fields)) {
+    const own = surface && entry.surfaces ? entry.surfaces[surface] : undefined;
+    if (own) {
+      values[key] = own.value;
+    } else if ('value' in entry) {
+      values[key] = entry.value;
+    }
+  }
+  return values;
+};
+
+/**
+ * The next preference fields for a merged document: every profile key it
+ * carries, stamped `now` when its value differs from what the file held and
+ * keeping the earlier stamp otherwise. Profile keys the document no longer
+ * carries are dropped (that is how a cleared key leaves the file).
+ *
+ * Per-surface keys: when the write comes from a surface kind (`surface`) and
+ * the key is among the keys that write changed (`changedKeys`), the value goes
+ * under `surfaces[surface]` and the base is left as it was; a per-surface key
+ * the write did not change keeps its whole entry (the document only carries
+ * that surface's resolved view of it). Without a surface (migrations, the
+ * one-time seed) the base is written.
+ */
+export const buildPreferencesFields = (previousFields, document, now, { surface = null, changedKeys = null } = {}) => {
+  const fields = {};
+  const changed = changedKeys ? new Set(changedKeys) : null;
+  for (const [key, value] of Object.entries(document)) {
+    if (value === undefined || !isProfileSettingsKey(key)) continue;
+    const previous = previousFields[key];
+    if (isPerSurfaceSettingsKey(key) && surface) {
+      if (changed && !changed.has(key)) {
+        if (previous) fields[key] = previous;
+        continue;
+      }
+      const previousOwn = previous?.surfaces?.[surface];
+      const own = previousOwn && sameValue(previousOwn.value, value) ? previousOwn : { value, updatedAt: now };
+      fields[key] = {
+        ...(previous ?? { updatedAt: 0 }),
+        surfaces: { ...(previous?.surfaces ?? {}), [surface]: own },
+      };
+      continue;
+    }
+    if (previous && 'value' in previous && sameValue(previous.value, value)) {
+      fields[key] = previous;
+    } else {
+      fields[key] = { ...(previous ?? {}), value, updatedAt: now };
+    }
+  }
+  return fields;
+};
+
+/**
+ * The part of a merged document that belongs in `settings.json`: everything
+ * that is not a profile key. Device keys older builds persisted stay in place
+ * as a read-once seed for clients; the write path never adds new ones.
+ */
+export const instancePartOf = (document) => {
+  const instance = {};
+  for (const [key, value] of Object.entries(document)) {
+    if (value === undefined || isProfileSettingsKey(key)) continue;
+    instance[key] = value;
+  }
+  return instance;
+};
+
+/** The profile keys of a document (the part `instancePartOf` leaves out). */
+export const profilePartOf = (document) => {
+  const profile = {};
+  for (const [key, value] of Object.entries(document)) {
+    if (value !== undefined && isProfileSettingsKey(key)) profile[key] = value;
+  }
+  return profile;
+};
+
+/**
+ * What `settings.json` holds after a write: the instance part plus a copy of
+ * the profile's base values. The copy is for builds that predate the split —
+ * they read only this file, so a rollback still finds the user's preferences.
+ * Current builds ignore it: `preferences.json` wins in the merged read.
+ */
+export const legacySettingsDocumentOf = (document, preferenceFields) => ({
+  ...instancePartOf(document),
+  ...flattenPreferences(preferenceFields),
+});
+
+/** The profile keys of a document, as they would seed a fresh preferences file. */
+export const seedPreferencesFrom = (document, now) => buildPreferencesFields({}, document, now);
+
+/**
+ * Synchronous merged read for server modules that consult one or two profile
+ * keys on a hot path (small-model resolution, goal/assist toggles). A missing
+ * or unreadable preferences file contributes nothing, and the caller's own
+ * default applies — the same "missing is not default" rule the clients use.
+ */
+export const readMergedSettingsSync = ({ fs, path, settingsFilePath }) => {
+  let settings = {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(settingsFilePath, 'utf8'));
+    if (isPlainObject(parsed)) settings = parsed;
+  } catch {
+    settings = {};
+  }
+  let preferences = {};
+  try {
+    const parsed = parsePreferencesDocument(fs.readFileSync(preferencesFilePathFor(settingsFilePath, path), 'utf8'));
+    if (parsed.ok) preferences = flattenPreferences(parsed.fields);
+  } catch {
+    preferences = {};
+  }
+  return { ...settings, ...preferences };
+};