perf: overhaul session loading, caching, and runtime isolation (#2360)

Improve OpenChamber responsiveness under large session workloads while fixing cache, synchronization, and persistence correctness across runtimes, projects, directories, and worktrees. - prioritize selected and visible sessions during bootstrap and defer non-critical enrichment work - reduce redundant message loading, event processing, store publication, and hidden sidebar work - prevent stale session and message requests from overwriting newer authoritative state - preserve existing data when authoritative fetches fail instead of treating failures as successful empty responses - scope session materialization, messages, drafts, queues, todos, pins, permissions, folders, tabs, Git state, and pull request data by runtime and directory identity - harden runtime switching, reconnect, cleanup, mutation reconciliation, and persisted-state ordering - preserve live subagent Task linkage when metadata arrives after an older message request or while streaming parts are suspended - coalesce overlapping tail refreshes without losing newer refresh demand - improve cold-session loading by moving deferrable work out of the critical bootstrap path - isolate URL authentication, mobile credentials, native secrets, and other runtime-owned state across endpoint changes - bound long-lived caches and remove avoidable allocations from event and rendering hot paths - limit virtualization to archive collections where it improves rendering without disrupting active sidebar layout - stabilize session folders, pin ordering, expanded state, and persisted sidebar behavior - open skill files through the same secure editor and outside-workspace grant flow used by file navigation, including worktree sessions - expand regression coverage for stale completions, runtime collisions, reconnect behavior, persistence races, authoritative empty results, and subagent refresh ordering - document the updated synchronization, cache ownership, performance, and runtime-isolation invariants
2026-07-21 20:52:20 +03:00
parent 485efc7117
commit 85400459e9
197 changed files with 10835 additions and 3400 deletions
@@ -448,10 +448,7 @@ const sessionRuntime = createSessionRuntime({
  broadcastEvent: broadcastGlobalUiEvent,
 });

-const getActiveSessionCount = () => {
-  const snapshot = sessionRuntime.getSessionActivitySnapshot();
-  return Object.values(snapshot).filter((entry) => entry.type === 'busy').length;
-};
+const getActiveSessionCount = () => sessionRuntime.getActiveSessionCount();

 const getUpstreamStallTimeoutMs = () => (
  getActiveSessionCount() > 1
@@ -111,6 +111,7 @@
 - Closed or merged PR -> stop regular polling.
 - Hidden tab -> skip polling.
 - Non-forced refreshes use a `90s` TTL.
+- Failed non-forced attempts also observe the `90s` TTL so transient server or rate-limit failures cannot retry on every sidebar update. Forced user/action refreshes bypass this guard.

 ## Background tracking rules

@@ -87,6 +87,7 @@ This module provides OpenCode server integration utilities for the web server ru
 - Returned API:
  - `processOpenCodeSsePayload(payload)`
  - `getSessionActivitySnapshot()`
+  - `getActiveSessionCount()`
  - `getSessionStateSnapshot()`
  - `getSessionAttentionSnapshot()`
  - `getSessionState(sessionId)`
@@ -97,6 +98,8 @@ This module provides OpenCode server integration utilities for the web server ru
  - `resetAllSessionActivityToIdle()`
  - `dispose()`

+The runtime maintains active-session count incrementally from idempotent activity phase transitions. Upstream stall-timeout and lifecycle health checks read it in O(1); the hourly cleanup removes activity phases older than 24 hours without broadcasting synthetic state transitions. Snapshot generation remains reserved for the session-activity API.
+
 ## Public exports (lifecycle.js)
 - `createOpenCodeLifecycleRuntime(dependencies)`: creates lifecycle runtime for managed/external OpenCode process orchestration.
 - Returned API:
@@ -112,6 +115,7 @@ This module provides OpenCode server integration utilities for the web server ru

 ## Public exports (env-runtime.js)
 - `createOpenCodeEnvRuntime(dependencies)`: creates runtime that owns OpenCode CLI environment and binary discovery state.
+- OpenCode CLI resolution order is persisted settings, environment overrides, bundled Desktop CLI when available, PATH, known install locations, then platform shell discovery.
 - Returned API:
  - `applyLoginShellEnvSnapshot()`
  - `getLoginShellEnvSnapshot()`
@@ -347,9 +347,9 @@ export const createOpenCodeEnvRuntime = (deps) => {
      }
    }

-    // The bundled CLI is the LAST resort (see bundledOpenCodeCliFallback at the
-    // exit points below): a user's own OpenCode install — PATH, known install
-    // locations, or shell-resolved — must win over the pinned bundled copy.
+    const bundled = bundledOpenCodeCliFallback();
+    if (bundled) return bundled;
+
    const resolvedFromPath = searchPathFor('opencode');
    if (resolvedFromPath) {
      clearWslOpencodeResolution();
@@ -427,7 +427,7 @@ export const createOpenCodeEnvRuntime = (deps) => {
      // Do not auto-detect OpenCode from WSL. OpenCode sessions are keyed by
      // server-visible directories, and mixing Windows paths with WSL paths
      // creates duplicate/missing project state in the desktop app.
-      return bundledOpenCodeCliFallback();
+      return null;
    }

    const shells = [process.env.SHELL, '/bin/zsh', '/bin/bash', '/bin/sh'].filter(Boolean);
@@ -451,7 +451,7 @@ export const createOpenCodeEnvRuntime = (deps) => {
      }
    }

-    return bundledOpenCodeCliFallback();
+    return null;
  };

  const resolveNodeCliPath = () => {
@@ -163,7 +163,7 @@ describe('OpenCode env runtime', () => {
    expect(state.resolvedOpencodeBinarySource).toBe('settings');
  });

-  it('prefers a user-installed OpenCode from PATH over the bundled CLI', () => {
+  it('prefers the bundled CLI over a user-installed OpenCode from PATH', () => {
    const bundledDir = createTempDir('openchamber-bundled-opencode-');
    const bundledBinary = path.join(bundledDir, process.platform === 'win32' ? 'opencode.exe' : 'opencode');
    const pathDir = createTempDir('openchamber-path-opencode-');
@@ -179,8 +179,8 @@ describe('OpenCode env runtime', () => {
    delete process.env.OPENCODE_BINARY;
    const { runtime, state } = createRuntime({});

-    expect(runtime.resolveOpencodeCliPath()).toBe(pathBinary);
-    expect(state.resolvedOpencodeBinarySource).toBe('path');
+    expect(runtime.resolveOpencodeCliPath()).toBe(bundledBinary);
+    expect(state.resolvedOpencodeBinarySource).toBe('bundled');
  });

  it('keeps explicit OpenCode binary ahead of bundled CLI', () => {
@@ -202,7 +202,7 @@ describe('OpenCode env runtime', () => {
    expect(state.resolvedOpencodeBinarySource).toBe('env');
  });

-  it('falls back to the bundled OpenCode CLI from Electron resourcesPath when nothing else is installed', () => {
+  it('resolves the bundled OpenCode CLI from Electron resourcesPath', () => {
    const resourcesPath = createTempDir('openchamber-resources-');
    const bundledDir = path.join(resourcesPath, 'opencode-cli');
    const bundledBinary = path.join(bundledDir, process.platform === 'win32' ? 'opencode.exe' : 'opencode');
@@ -218,8 +218,6 @@ describe('OpenCode env runtime', () => {
    process.env.PATH = createTempDir('openchamber-empty-path-');
    delete process.env.OPENCHAMBER_BUNDLED_OPENCODE_CLI_DIR;
    delete process.env.OPENCODE_BINARY;
-    // The bundled CLI is the LAST resort now — hide the machine's own installs
-    // from the home-directory fallbacks and shell discovery.
    const emptyHome = createTempDir('openchamber-empty-home-');
    const { runtime, state } = createRuntime({}, {
      spawnSync: () => ({ status: 1, stdout: '', stderr: '' }),
@@ -1,6 +1,7 @@
 const SESSION_COOLDOWN_DURATION_MS = 2000;
 const SESSION_STATE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const SESSION_ATTENTION_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const SESSION_ACTIVITY_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const SESSION_STATE_CLEANUP_INTERVAL_MS = 60 * 60 * 1000;

 const extractSessionStatusUpdate = (payload) => {
@@ -37,26 +38,12 @@ const extractSessionStatusUpdate = (payload) => {
  };
 };

-const deriveSessionActivityTransitions = (payload) => {
-  const update = extractSessionStatusUpdate(payload);
-  if (!update) {
-    return [];
-  }
-
-  if (update.type === 'busy' || update.type === 'retry') {
-    return [{ sessionId: update.sessionId, phase: 'busy' }];
-  }
-  if (update.type === 'idle') {
-    return [{ sessionId: update.sessionId, phase: 'cooldown' }];
-  }
-  return [];
-};
-
 export const createSessionRuntime = ({ writeSseEvent, getNotificationClients, broadcastEvent }) => {
  const sessionActivityPhases = new Map();
  const sessionActivityCooldowns = new Map();
  const sessionStates = new Map();
  const sessionAttentionStates = new Map();
+  let activeSessionCount = 0;

  const getOrCreateAttentionState = (sessionId) => {
    if (!sessionId || typeof sessionId !== 'string') return null;
@@ -90,6 +77,11 @@ export const createSessionRuntime = ({ writeSseEvent, getNotificationClients, br
      sessionActivityCooldowns.delete(sessionId);
    }

+    const wasActive = current?.phase === 'busy';
+    const isActive = phase === 'busy';
+    if (wasActive !== isActive) {
+      activeSessionCount = Math.max(0, activeSessionCount + (isActive ? 1 : -1));
+    }
    sessionActivityPhases.set(sessionId, { phase, updatedAt: Date.now() });

    if (phase === 'cooldown') {
@@ -287,11 +279,14 @@ export const createSessionRuntime = ({ writeSseEvent, getNotificationClients, br
    return result;
  };

+  const getActiveSessionCount = () => activeSessionCount;
+
  const resetAllSessionActivityToIdle = () => {
    for (const timer of sessionActivityCooldowns.values()) {
      clearTimeout(timer);
    }
    sessionActivityCooldowns.clear();
+    activeSessionCount = 0;
    const now = Date.now();
    for (const [sessionId] of sessionActivityPhases) {
      sessionActivityPhases.set(sessionId, { phase: 'idle', updatedAt: now });
@@ -310,26 +305,33 @@ export const createSessionRuntime = ({ writeSseEvent, getNotificationClients, br
        sessionAttentionStates.delete(sessionId);
      }
    }
+    for (const [sessionId, data] of sessionActivityPhases) {
+      if (now - data.updatedAt <= SESSION_ACTIVITY_MAX_AGE_MS) continue;
+      const timer = sessionActivityCooldowns.get(sessionId);
+      if (timer) clearTimeout(timer);
+      sessionActivityCooldowns.delete(sessionId);
+      sessionActivityPhases.delete(sessionId);
+      if (data.phase === 'busy') activeSessionCount = Math.max(0, activeSessionCount - 1);
+    }
  };

  const cleanupInterval = setInterval(cleanupOldSessionStates, SESSION_STATE_CLEANUP_INTERVAL_MS);

  const processOpenCodeSsePayload = (payload) => {
-    const transitions = deriveSessionActivityTransitions(payload);
-    for (const activity of transitions) {
-      setSessionActivityPhase(activity.sessionId, activity.phase);
+    const update = extractSessionStatusUpdate(payload);
+    if (!update) return;
+
+    if (update.type === 'busy' || update.type === 'retry') {
+      setSessionActivityPhase(update.sessionId, 'busy');
+    } else if (update.type === 'idle') {
+      setSessionActivityPhase(update.sessionId, 'cooldown');
    }

-    if (payload && payload.type === 'session.status') {
-      const update = extractSessionStatusUpdate(payload);
-      if (update) {
-        updateSessionState(update.sessionId, update.type, update.eventId || `sse-${Date.now()}`, {
-          attempt: update.attempt,
-          message: update.message,
-          next: update.next,
-        });
-      }
-    }
+    updateSessionState(update.sessionId, update.type, update.eventId || `sse-${Date.now()}`, {
+      attempt: update.attempt,
+      message: update.message,
+      next: update.next,
+    });
  };

  const dispose = () => {
@@ -338,11 +340,16 @@ export const createSessionRuntime = ({ writeSseEvent, getNotificationClients, br
      clearTimeout(timer);
    }
    sessionActivityCooldowns.clear();
+    sessionActivityPhases.clear();
+    sessionStates.clear();
+    sessionAttentionStates.clear();
+    activeSessionCount = 0;
  };

  return {
    processOpenCodeSsePayload,
    getSessionActivitySnapshot,
+    getActiveSessionCount,
    getSessionStateSnapshot,
    getSessionAttentionSnapshot,
    getSessionState,
@@ -148,4 +148,84 @@ describe('session runtime', () => {
      vi.useRealTimers();
    }
  });
+
+  it('maintains an idempotent active session count', () => {
+    const runtime = createSessionRuntime({
+      writeSseEvent() {},
+      getNotificationClients: () => new Set(),
+      broadcastEvent() {},
+    });
+    runtimes.push(runtime);
+    const status = (sessionID, type) => runtime.processOpenCodeSsePayload({
+      type: 'session.status',
+      properties: { sessionID, status: { type } },
+    });
+
+    expect(runtime.getActiveSessionCount()).toBe(0);
+    status('session-1', 'busy');
+    status('session-1', 'busy');
+    status('session-1', 'retry');
+    expect(runtime.getActiveSessionCount()).toBe(1);
+
+    status('session-2', 'busy');
+    expect(runtime.getActiveSessionCount()).toBe(2);
+
+    status('session-1', 'idle');
+    expect(runtime.getActiveSessionCount()).toBe(1);
+    status('session-1', 'idle');
+    expect(runtime.getActiveSessionCount()).toBe(1);
+
+    runtime.resetAllSessionActivityToIdle();
+    expect(runtime.getActiveSessionCount()).toBe(0);
+  });
+
+  it('restores activity when busy interrupts cooldown without timer underflow', () => {
+    vi.useFakeTimers();
+    const runtime = createSessionRuntime({
+      writeSseEvent() {},
+      getNotificationClients: () => new Set(),
+      broadcastEvent() {},
+    });
+    const status = (type) => runtime.processOpenCodeSsePayload({
+      type: 'session.status',
+      properties: { sessionID: 'session-1', status: { type } },
+    });
+
+    try {
+      status('busy');
+      status('idle');
+      expect(runtime.getActiveSessionCount()).toBe(0);
+
+      status('retry');
+      expect(runtime.getActiveSessionCount()).toBe(1);
+      vi.advanceTimersByTime(2000);
+
+      expect(runtime.getActiveSessionCount()).toBe(1);
+      expect(runtime.getSessionActivitySnapshot()['session-1']).toEqual({ type: 'busy' });
+    } finally {
+      runtime.dispose();
+      vi.useRealTimers();
+    }
+  });
+
+  it('releases retained session state when disposed', () => {
+    const runtime = createSessionRuntime({
+      writeSseEvent() {},
+      getNotificationClients: () => new Set(),
+      broadcastEvent() {},
+    });
+    runtimes.push(runtime);
+
+    runtime.processOpenCodeSsePayload({
+      type: 'session.status',
+      properties: { sessionID: 'session-1', status: { type: 'busy' } },
+    });
+    runtime.markUserMessageSent('session-1');
+    runtime.dispose();
+
+    expect(runtime.getActiveSessionCount()).toBe(0);
+    expect(runtime.getSessionActivitySnapshot()).toEqual({});
+    expect(runtime.getSessionStateSnapshot()).toEqual({});
+    expect(runtime.getSessionAttentionSnapshot()).toEqual({});
+  });
 });
@@ -201,6 +201,10 @@ export const createSettingsHelpers = (dependencies) => {
      }
      result.permissionAutoAccept = {
        sessions,
+        revision: Number.isSafeInteger(candidate.permissionAutoAccept.revision)
+          && candidate.permissionAutoAccept.revision >= 0
+          ? candidate.permissionAutoAccept.revision
+          : 0,
      };
    }
    if (typeof candidate.desktopUiPassword === 'string') {
@@ -134,6 +134,7 @@ describe('settings helpers', () => {
    })).toEqual({
      permissionAutoAccept: {
        sessions: { root: true, child: false },
+        revision: 0,
      },
    });
  });
@@ -502,14 +502,18 @@ export const createSettingsRuntime = (deps) => {

  const writeSettingsToDisk = async (settings) => {
    try {
-      await fsPromises.mkdir(path.dirname(SETTINGS_FILE_PATH), { recursive: true });
+      const settingsDirectory = path.dirname(SETTINGS_FILE_PATH);
+      await fsPromises.mkdir(settingsDirectory, { recursive: true, mode: 0o700 });
+      if (process.platform !== 'win32') await fsPromises.chmod(settingsDirectory, 0o700);
      // Atomic write: Electron main and ssh-manager read this file via plain
      // readFile + JSON.parse and silently coerce parse errors to {}. A
      // partial read during a non-atomic writeFile would make their next
      // read-modify-write wipe the settings file.
      const tmp = `${SETTINGS_FILE_PATH}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-      await fsPromises.writeFile(tmp, JSON.stringify(settings, null, 2), 'utf8');
+      await fsPromises.writeFile(tmp, JSON.stringify(settings, null, 2), { encoding: 'utf8', mode: 0o600 });
+      if (process.platform !== 'win32') await fsPromises.chmod(tmp, 0o600);
      await replaceFile(tmp, SETTINGS_FILE_PATH);
+      if (process.platform !== 'win32') await fsPromises.chmod(SETTINGS_FILE_PATH, 0o600);
    } catch (error) {
      console.warn('Failed to write settings file:', error);
      throw error;
@@ -39,6 +39,18 @@ const createRuntime = async () => {
 };

 describe('settings runtime', () => {
+  it.skipIf(process.platform === 'win32')('writes settings with restrictive directory and file permissions', async () => {
+    const { runtime, settingsFilePath, tempRoot, cleanup } = await createRuntime();
+    try {
+      await runtime.writeSettingsToDisk({ desktopUiPassword: 'secret' });
+
+      expect((await fsPromises.stat(tempRoot)).mode & 0o777).toBe(0o700);
+      expect((await fsPromises.stat(settingsFilePath)).mode & 0o777).toBe(0o600);
+    } finally {
+      await cleanup();
+    }
+  });
+
  it('only remaps project plan paths within the migrated storage directory', async () => {
    const { runtime, settingsFilePath, tempRoot, cleanup } = await createRuntime();
    try {
@@ -12,7 +12,8 @@ const normalizePolicy = (value) => {
  for (const [sessionId, enabled] of entries) {
    if (sessionId && typeof enabled === 'boolean') sessions[sessionId] = enabled;
  }
-  return { sessions };
+  const revision = Number.isSafeInteger(source.revision) && source.revision >= 0 ? source.revision : 0;
+  return { sessions, revision };
 };

 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -38,6 +39,7 @@ export function createPermissionAutoAcceptRuntime({

  const snapshot = () => ({
    sessions: { ...policy.sessions },
+    revision: policy.revision,
  });

  const load = async () => {
@@ -76,6 +78,7 @@ export function createPermissionAutoAcceptRuntime({
    const result = await persistUpdate((current) => ({
      ...current,
      sessions: { ...current.sessions, [sessionId.trim()]: enabled },
+      revision: current.revision + 1,
    }));
    if (enabled) await reconcilePending({ directories: [directory] });
    return result;
@@ -38,9 +38,18 @@ describe('permission auto-accept runtime', () => {
    const second = createRuntime({ stored: first.getSettings() });
    await expect(second.runtime.load()).resolves.toEqual({
      sessions: { root: true },
+      revision: 1,
    });
  });

+  it('increments the authoritative policy revision', async () => {
+    const { runtime, getSettings } = createRuntime();
+
+    await expect(runtime.setSessionPolicy('root', true)).resolves.toMatchObject({ revision: 1 });
+    await expect(runtime.setSessionPolicy('child', false)).resolves.toMatchObject({ revision: 2 });
+    expect(getSettings().permissionAutoAccept.revision).toBe(2);
+  });
+
  it('uses nearest explicit ancestor policy for subagents', async () => {
    const { runtime, emit } = createRuntime({
      stored: { permissionAutoAccept: { sessions: { root: true, child: false } } },
@@ -132,6 +141,6 @@ describe('permission auto-accept runtime', () => {
      .map(([url]) => new URL(url).pathname);
    expect(replyPaths).toEqual(['/permission/root-pending/reply']);
    expect(fetchImpl.mock.calls.some(([url]) => new URL(url).searchParams.get('directory') === '/project')).toBe(true);
-    expect(await runtime.load()).toEqual({ sessions: { root: true } });
+    expect(await runtime.load()).toEqual({ sessions: { root: true }, revision: 1 });
  });
 });
@@ -1,5 +1,33 @@
 const MAX_BODY_BYTES = 4 * 1024 * 1024;

+const isObjectRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const hasValidFolderShape = (folder) => (
+  isObjectRecord(folder)
+  && typeof folder.id === 'string'
+  && typeof folder.name === 'string'
+  && Array.isArray(folder.sessionIds)
+  && folder.sessionIds.every((sessionId) => typeof sessionId === 'string')
+  && typeof folder.createdAt === 'number'
+  && Number.isFinite(folder.createdAt)
+  && (folder.parentId === undefined || folder.parentId === null || typeof folder.parentId === 'string')
+);
+
+const hasValidFoldersMapShape = (foldersMap) => (
+  isObjectRecord(foldersMap)
+  && Object.values(foldersMap).every((folders) => (
+    Array.isArray(folders) && folders.every(hasValidFolderShape)
+  ))
+);
+
+const hasValidFolderSnapshotShape = (snapshot) => (
+  isObjectRecord(snapshot)
+  && snapshot.version === 1
+  && hasValidFoldersMapShape(snapshot.foldersMap)
+  && Array.isArray(snapshot.collapsedFolderIds)
+  && snapshot.collapsedFolderIds.every((folderId) => typeof folderId === 'string')
+);
+
 export const registerSessionFoldersRoutes = (app, dependencies) => {
  const {
    fsPromises,
@@ -8,6 +36,7 @@ export const registerSessionFoldersRoutes = (app, dependencies) => {
  } = dependencies;

  const filePath = path.join(openchamberDataDir, 'sessions-directories.json');
+  let saveQueue = Promise.resolve();

  const ensureDir = async () => {
    await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
@@ -20,13 +49,21 @@ export const registerSessionFoldersRoutes = (app, dependencies) => {
        throw error;
      });
      if (!raw) {
-        return res.json({ version: 1, foldersMap: {}, collapsedFolderIds: [], updatedAt: 0 });
+        return res.json({ version: 1, exists: false });
      }
      try {
        const parsed = JSON.parse(raw);
-        return res.json(parsed);
+        if (
+          !hasValidFolderSnapshotShape(parsed)
+          || typeof parsed.updatedAt !== 'number'
+          || !Number.isFinite(parsed.updatedAt)
+          || parsed.updatedAt <= 0
+        ) {
+          return res.status(500).json({ error: 'Stored session folders have an invalid shape' });
+        }
+        return res.json({ ...parsed, exists: true });
      } catch {
-        return res.json({ version: 1, foldersMap: {}, collapsedFolderIds: [], updatedAt: 0 });
+        return res.status(500).json({ error: 'Stored session folders are malformed' });
      }
    } catch (error) {
      const message = error instanceof Error ? error.message : 'Failed to read session folders';
@@ -36,28 +73,59 @@ export const registerSessionFoldersRoutes = (app, dependencies) => {

  app.post('/api/session-folders', async (req, res) => {
    const body = req.body;
-    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    if (!isObjectRecord(body)) {
      return res.status(400).json({ error: 'Body must be an object' });
    }
+    if (!hasValidFolderSnapshotShape(body)) {
+      return res.status(400).json({ error: 'Invalid session folders payload' });
+    }
    const serialized = JSON.stringify(body, null, 2);
    if (Buffer.byteLength(serialized, 'utf8') > MAX_BODY_BYTES) {
      return res.status(413).json({ error: 'Payload too large' });
    }
-    let tmp;
-    let saved = false;
-    try {
-      await ensureDir();
-      tmp = `${filePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
-      await fsPromises.writeFile(tmp, serialized, 'utf8');
-      await fsPromises.rename(tmp, filePath);
-      saved = true;
-      return res.json({ success: true });
-    } catch (error) {
-      if (tmp && !saved) {
-        await fsPromises.unlink(tmp).catch(() => {});
-      }
-      const message = error instanceof Error ? error.message : 'Failed to write session folders';
-      return res.status(500).json({ error: message });
+    if (typeof body.updatedAt !== 'number' || !Number.isFinite(body.updatedAt) || body.updatedAt <= 0) {
+      return res.status(400).json({ error: 'updatedAt must be a positive finite number' });
    }
+
+    const save = async () => {
+      let tmp;
+      let saved = false;
+      try {
+        const currentRaw = await fsPromises.readFile(filePath, 'utf8').catch((error) => {
+          if (error && error.code === 'ENOENT') return null;
+          throw error;
+        });
+        if (currentRaw) {
+          try {
+            const current = JSON.parse(currentRaw);
+            const currentUpdatedAt = hasValidFolderSnapshotShape(current)
+              && typeof current.updatedAt === 'number'
+              && Number.isFinite(current.updatedAt)
+              ? current.updatedAt
+              : 0;
+            if (currentUpdatedAt >= body.updatedAt) {
+              return res.json({ success: true, ignored: true });
+            }
+          } catch { /* A valid new snapshot repairs malformed prior state. */ }
+        }
+
+        await ensureDir();
+        tmp = `${filePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+        await fsPromises.writeFile(tmp, serialized, 'utf8');
+        await fsPromises.rename(tmp, filePath);
+        saved = true;
+        return res.json({ success: true });
+      } catch (error) {
+        if (tmp && !saved) {
+          await fsPromises.unlink(tmp).catch(() => {});
+        }
+        const message = error instanceof Error ? error.message : 'Failed to write session folders';
+        return res.status(500).json({ error: message });
+      }
+    };
+
+    const pendingSave = saveQueue.then(save, save);
+    saveQueue = pendingSave.then(() => undefined, () => undefined);
+    return pendingSave;
  });
 };
@@ -43,11 +43,25 @@ const createMockResponse = () => {
  };
 };

+const missingFile = async () => {
+  const error = new Error('missing');
+  error.code = 'ENOENT';
+  throw error;
+};
+
+const folderPayload = (updatedAt) => ({
+  version: 1,
+  foldersMap: {},
+  collapsedFolderIds: [],
+  updatedAt,
+});
+
 describe('session folders routes', () => {
  it('uses unique temp files for concurrent saves', async () => {
    const { app, getRoute } = createRouteRegistry();
    const tempPaths = [];
    const fsPromises = {
+      readFile: vi.fn(missingFile),
      mkdir: vi.fn(async () => {}),
      writeFile: vi.fn(async (tempPath) => {
        tempPaths.push(tempPath);
@@ -65,8 +79,8 @@ describe('session folders routes', () => {
    const handler = getRoute('POST', '/api/session-folders');

    await Promise.all([
-      handler({ body: { version: 1, updatedAt: 1 } }, createMockResponse()),
-      handler({ body: { version: 1, updatedAt: 2 } }, createMockResponse()),
+      handler({ body: folderPayload(1) }, createMockResponse()),
+      handler({ body: folderPayload(2) }, createMockResponse()),
    ]);

    expect(tempPaths).toHaveLength(2);
@@ -77,6 +91,7 @@ describe('session folders routes', () => {
  it('removes the temp file when rename fails', async () => {
    const { app, getRoute } = createRouteRegistry();
    const fsPromises = {
+      readFile: vi.fn(missingFile),
      mkdir: vi.fn(async () => {}),
      writeFile: vi.fn(async () => {}),
      rename: vi.fn(async () => {
@@ -94,9 +109,131 @@ describe('session folders routes', () => {
    const handler = getRoute('POST', '/api/session-folders');
    const response = createMockResponse();

-    await handler({ body: { version: 1, updatedAt: 1 } }, response);
+    await handler({ body: folderPayload(1) }, response);

    expect(response.statusCode).toBe(500);
    expect(fsPromises.unlink).toHaveBeenCalledWith(expect.stringContaining('sessions-directories.json.tmp-'));
  });
+
+  it('does not present a missing disk file as an authoritative empty snapshot', async () => {
+    const { app, getRoute } = createRouteRegistry();
+    const fsPromises = { readFile: vi.fn(missingFile) };
+    registerSessionFoldersRoutes(app, {
+      fsPromises,
+      path,
+      openchamberDataDir: '/tmp/openchamber-test',
+    });
+
+    const response = createMockResponse();
+    await getRoute('GET', '/api/session-folders')({}, response);
+
+    expect(response.statusCode).toBe(200);
+    expect(response.body).toEqual({ version: 1, exists: false });
+  });
+
+  it('rejects malformed disk state instead of clearing valid browser state', async () => {
+    const { app, getRoute } = createRouteRegistry();
+    const fsPromises = { readFile: vi.fn(async () => '{broken') };
+    registerSessionFoldersRoutes(app, {
+      fsPromises,
+      path,
+      openchamberDataDir: '/tmp/openchamber-test',
+    });
+
+    const response = createMockResponse();
+    await getRoute('GET', '/api/session-folders')({}, response);
+
+    expect(response.statusCode).toBe(500);
+  });
+
+  it('rejects structurally invalid folder entries from disk', async () => {
+    const { app, getRoute } = createRouteRegistry();
+    const malformedPayload = {
+      ...folderPayload(10),
+      foldersMap: { project: [{ id: 'folder', name: 'Folder', sessionIds: 'session-1', createdAt: 1 }] },
+    };
+    const fsPromises = { readFile: vi.fn(async () => JSON.stringify(malformedPayload)) };
+    registerSessionFoldersRoutes(app, {
+      fsPromises,
+      path,
+      openchamberDataDir: '/tmp/openchamber-test',
+    });
+
+    const response = createMockResponse();
+    await getRoute('GET', '/api/session-folders')({}, response);
+
+    expect(response.statusCode).toBe(500);
+    expect(response.body).toEqual({ error: 'Stored session folders have an invalid shape' });
+  });
+
+  it('keeps the newest folder snapshot when an older write arrives later', async () => {
+    const { app, getRoute } = createRouteRegistry();
+    let persisted = JSON.stringify(folderPayload(20));
+    const fsPromises = {
+      readFile: vi.fn(async () => persisted),
+      mkdir: vi.fn(async () => {}),
+      writeFile: vi.fn(async (_tempPath, value) => {
+        persisted = value;
+      }),
+      rename: vi.fn(async () => {}),
+      unlink: vi.fn(async () => {}),
+    };
+    registerSessionFoldersRoutes(app, {
+      fsPromises,
+      path,
+      openchamberDataDir: '/tmp/openchamber-test',
+    });
+
+    const response = createMockResponse();
+    await getRoute('POST', '/api/session-folders')({ body: folderPayload(10) }, response);
+
+    expect(response.body).toEqual({ success: true, ignored: true });
+    expect(fsPromises.writeFile).not.toHaveBeenCalled();
+  });
+
+  it('keeps the existing folder snapshot when a duplicate revision has different data', async () => {
+    const { app, getRoute } = createRouteRegistry();
+    const persistedPayload = { ...folderPayload(20), foldersMap: { existing: [] } };
+    const fsPromises = {
+      readFile: vi.fn(async () => JSON.stringify(persistedPayload)),
+      mkdir: vi.fn(async () => {}),
+      writeFile: vi.fn(async () => {}),
+      rename: vi.fn(async () => {}),
+      unlink: vi.fn(async () => {}),
+    };
+    registerSessionFoldersRoutes(app, {
+      fsPromises,
+      path,
+      openchamberDataDir: '/tmp/openchamber-test',
+    });
+
+    const response = createMockResponse();
+    const duplicateRevision = { ...folderPayload(20), foldersMap: { replacement: [] } };
+    await getRoute('POST', '/api/session-folders')({ body: duplicateRevision }, response);
+
+    expect(response.body).toEqual({ success: true, ignored: true });
+    expect(fsPromises.writeFile).not.toHaveBeenCalled();
+  });
+
+  it('allows a valid snapshot to repair structurally invalid prior state', async () => {
+    const { app, getRoute } = createRouteRegistry();
+    const fsPromises = {
+      readFile: vi.fn(async () => JSON.stringify({ version: 1, updatedAt: 999, foldersMap: null })),
+      mkdir: vi.fn(async () => {}),
+      writeFile: vi.fn(async () => {}),
+      rename: vi.fn(async () => {}),
+      unlink: vi.fn(async () => {}),
+    };
+    registerSessionFoldersRoutes(app, {
+      fsPromises,
+      path,
+      openchamberDataDir: '/tmp/openchamber-test',
+    });
+
+    const response = createMockResponse();
+    await getRoute('POST', '/api/session-folders')({ body: folderPayload(10) }, response);
+
+    expect(response.body).toEqual({ success: true });
+    expect(fsPromises.writeFile).toHaveBeenCalledTimes(1);
+  });
 });