ompchamber 0.3.0

package/src/shared/lib/workspace/schema-migrations.ts

@@ -0,0 +1,19 @@
+import type { DbClient } from '@/server/lib/db/client';
+
+async function addColumn(db: DbClient, statement: string): Promise<void> {
+  try {
+    await db.exec(statement);
+  } catch (error) {
+    return;
+  }
+}
+
+export async function migrateWorkspaceFolderColumns(db: DbClient): Promise<void> {
+  await addColumn(db, 'ALTER TABLE workspace_folders ADD COLUMN is_expanded BOOLEAN DEFAULT 0;');
+  await addColumn(db, 'ALTER TABLE workspace_folders ADD COLUMN project_path TEXT;');
+  await addColumn(db, 'ALTER TABLE workspace_folders ADD COLUMN is_pinned BOOLEAN DEFAULT 0;');
+  await addColumn(db, "ALTER TABLE workspace_folders ADD COLUMN model TEXT DEFAULT 'Not selected';");
+  await addColumn(db, "ALTER TABLE workspace_folders ADD COLUMN accent_color TEXT DEFAULT '';");
+  await addColumn(db, "ALTER TABLE workspace_folders ADD COLUMN icon TEXT DEFAULT 'default';");
+  await addColumn(db, 'ALTER TABLE workspace_folders ADD COLUMN custom_icon_url TEXT;');
+}

package/src/shared/lib/workspace/session-state/store.ts

@@ -0,0 +1,267 @@
+/**
+ * Per-session UI state store (module singleton).
+ *
+ * UI state that should survive session switches (and full page reloads) is
+ * kept here in an in-memory cache keyed by the session id and persisted as
+ * one JSON blob per session into the `session_ui_state` SQLite table via
+ * `GET/POST /api/sessions/:sessionId/state`. Session ids are the URL
+ * `sessionId` param values: numeric in mock mode, omp UUID strings in real
+ * mode, plus transient `new-…` ids for pending chats (migrated to the real
+ * id on spawn adoption).
+ *
+ * Key namespace contract (dot-prefixed by owning panel):
+ * - layout.activeRightPanel   RightPanelType
+ * - layout.showRightPanel     boolean
+ * - layout.openedFiles        editor file entries array
+ * - layout.activeFileId       number | null
+ * - editor.previewMode        Record<fileId, boolean>
+ * - editor.wordWrap           boolean
+ * - editor.zoomLevel          number
+ * - files.expandedPaths       string[]
+ * - files.searchQuery         string
+ * - files.activeRepo          string
+ * - browser.viewportMode      string
+ * - browser.zoomLevel         number
+ * - userBrowser.history       string[]
+ * - userBrowser.historyIndex  number
+ * - userBrowser.inputUrl      string
+ * - userBrowser.viewportMode  string
+ * - userBrowser.zoomLevel     number
+ * - terminal.activeRepo       string
+ * - terminal.cwd              string
+ * - terminal.commandHistory   string[]
+ * - terminal.input            string
+ * - terminal.output           string (trimmed tail)
+ * - git.viewMode              'flat' | 'tree'
+ * - git.commitDraft           string
+ * - git.stagedExpanded        boolean
+ * - git.unstagedExpanded      boolean
+ * - git.expandedFolders       string[]
+ * - git.repoQuery             string
+ * - search.query              string
+ * - search.replaceQuery       string
+ * - search.matchCase          boolean
+ * - search.wholeWord          boolean
+ * - search.useRegex           boolean
+ * - search.includeFiles       string
+ * - search.showIncludeField   boolean
+ * - search.activeRepo         string
+ * - context.rawExpandedIds    Record<string, boolean>
+ * - context.rawFilterRole     'all' | 'assistant' | 'user'
+ * - usage.selectedProviderId  'kenari' | 'deepseek'
+ * - chat.draft                string
+ * - chat.draftAttachments     attachment metadata array
+ */
+
+type SessionState = Record<string, unknown>;
+
+const cache = new Map<string, SessionState>();
+/** Epoch ms of the last user-driven access per session (get/set/hydrate). */
+const lastTouched = new Map<string, number>();
+const readySessions = new Set<string>();
+const dirtySessions = new Map<string, boolean>();
+const persistTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+const PERSIST_DEBOUNCE_MS = 600;
+
+// Bounded LRU cache: cap the number of sessions kept in memory so the tab
+// doesn't grow unboundedly as the user visits more sessions.
+const MAX_CACHED_SESSIONS = 10;
+/** A session whose last user access is older than this is evicted regardless
+ *  of the size cap, so stale per-session UI state (drafts, panel layouts)
+ *  stops occupying memory 10 minutes after the user last opened it. */
+const SESSION_IDLE_TTL_MS = 10 * 60 * 1000;
+
+/**
+ * Reorder a cache entry to the end of the Map's iteration order (the
+ * most-recently-used position) via delete-then-set. Map.set on an existing
+ * key updates the value but keeps its original position, so the explicit
+ * delete is required for true LRU semantics.
+ */
+function touchCacheEntry(sessionId: string): void {
+  const value = cache.get(sessionId);
+  if (value !== undefined) {
+    cache.delete(sessionId);
+    cache.set(sessionId, value);
+  }
+  lastTouched.set(sessionId, Date.now());
+}
+
+/**
+ * Evict the oldest clean sessions until the cache is within bounds.
+ *
+ * Dirty-safety rule: a session with unsaved writes (`dirtySessions.get(id) ===
+ * true`) must never be evicted, or the user's drafts and editor state would be
+ * silently lost. If every candidate is dirty (or is the protected id currently
+ * being written), stop evicting rather than lose data.
+ *
+ * Entries idle past SESSION_IDLE_TTL_MS are evicted first — even when the
+ * cache is under the size cap — so long-unused sessions drop out on schedule.
+ */
+function evictIfNeeded(protectedId: string | null): void {
+  const now = Date.now();
+  const evict = (id: string): void => {
+    cache.delete(id);
+    readySessions.delete(id);
+    dirtySessions.delete(id);
+    lastTouched.delete(id);
+    const timer = persistTimers.get(id);
+    if (timer) {
+      clearTimeout(timer);
+      persistTimers.delete(id);
+    }
+  };
+  // TTL pass: safe to skip only while the timer still holds the unsaved state
+  // or the session is the one currently being written.
+  for (const [id, touched] of lastTouched) {
+    if (now - touched <= SESSION_IDLE_TTL_MS) continue;
+    if (id === protectedId) continue;
+    if (dirtySessions.get(id)) continue;
+    evict(id);
+  }
+  while (cache.size > MAX_CACHED_SESSIONS) {
+    let evicted = false;
+    for (const id of cache.keys()) {
+      if (id === protectedId) continue;
+      if (dirtySessions.get(id)) continue;
+      evict(id);
+      evicted = true;
+      break;
+    }
+    if (!evicted) break;
+  }
+}
+
+export function getSessionValue<T>(sessionId: string | null, key: string): T | undefined {
+  if (!sessionId) return undefined;
+  touchCacheEntry(sessionId);
+  return cache.get(sessionId)?.[key] as T | undefined;
+}
+
+export function setSessionKey(sessionId: string | null, key: string, value: unknown): void {
+  if (!sessionId) return;
+  const state = cache.get(sessionId) ?? {};
+  state[key] = value;
+  cache.set(sessionId, state);
+  touchCacheEntry(sessionId);
+  dirtySessions.set(sessionId, true);
+  schedulePersist(sessionId);
+  evictIfNeeded(sessionId);
+}
+
+function schedulePersist(sessionId: string): void {
+  const existing = persistTimers.get(sessionId);
+  if (existing) clearTimeout(existing);
+  persistTimers.set(
+    sessionId,
+    setTimeout(() => {
+      persistTimers.delete(sessionId);
+      void persistSession(sessionId);
+    }, PERSIST_DEBOUNCE_MS),
+  );
+}
+
+async function persistSession(sessionId: string): Promise<void> {
+  if (typeof window === 'undefined' || !sessionId) return;
+  if (!dirtySessions.get(sessionId)) return;
+  dirtySessions.set(sessionId, false);
+  const state = cache.get(sessionId) ?? {};
+  try {
+    await fetch(`/api/sessions/${encodeURIComponent(sessionId)}/state`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ state }),
+    });
+  } catch (err) {
+    console.warn('session-state persist failed:', err);
+    dirtySessions.set(sessionId, true);
+  }
+}
+
+/** Immediately persist any pending writes for a session (used on switch). */
+export function flushSession(sessionId: string | null): Promise<void> {
+  if (!sessionId || typeof window === 'undefined') return Promise.resolve();
+  const timer = persistTimers.get(sessionId);
+  if (timer) {
+    clearTimeout(timer);
+    persistTimers.delete(sessionId);
+  }
+  return persistSession(sessionId);
+}
+
+/** Fetch a session's stored blob and merge it under any local writes. */
+export async function loadSession(sessionId: string): Promise<void> {
+  if (!sessionId) return;
+  if (typeof window === 'undefined') {
+    readySessions.add(sessionId);
+    return;
+  }
+  try {
+    const res = await fetch(`/api/sessions/${encodeURIComponent(sessionId)}/state`);
+    if (res.ok) {
+      const data = (await res.json()) as { state?: SessionState };
+      const incoming = data.state && typeof data.state === 'object' ? data.state : {};
+      const existing = cache.get(sessionId) ?? {};
+      // Only keys written locally while the fetch was in flight win over the
+      // stored blob. Merging the WHOLE local cache over the blob (the old
+      // behavior) resurrected stale values on every tab: a second browser
+      // opening the session had cached the pre-write blob, and its stale
+      // copy clobbered another tab's fresh writes — queue items written in
+      // one tab never appeared in the other.
+      const dirty = dirtySessions.get(sessionId) === true;
+      const merged = dirty ? { ...incoming, ...existing } : incoming;
+      cache.set(sessionId, merged);
+      touchCacheEntry(sessionId);
+    }
+  } catch (err) {
+    console.warn('session-state load failed:', err);
+  }
+  readySessions.add(sessionId);
+  evictIfNeeded(sessionId);
+}
+
+/** Seed the cache synchronously (e.g. from SSR-provided data). */
+export function hydrateSession(sessionId: string | null, state: SessionState): void {
+  if (!sessionId) return;
+  cache.set(sessionId, { ...(cache.get(sessionId) ?? {}), ...state });
+  touchCacheEntry(sessionId);
+  readySessions.add(sessionId);
+  evictIfNeeded(sessionId);
+}
+
+/** Mark a session as loaded without fetching (fresh / ephemeral sessions). */
+export function markSessionReady(sessionId: string | null): void {
+  if (sessionId) readySessions.add(sessionId);
+}
+
+/**
+ * Record that the user opened this session now. Drives the mobile header's
+ * recent-session picker and the cache TTL: a session is "recent" only while
+ * its last open is within SESSION_IDLE_TTL_MS.
+ */
+export function recordSessionOpen(sessionId: string | null): void {
+  if (sessionId) lastTouched.set(sessionId, Date.now());
+}
+
+/** Epoch ms of the user's last open of this session in this tab, if any. */
+export function getLastOpenedAt(sessionId: string): number | undefined {
+  return lastTouched.get(sessionId);
+}
+
+/**
+ * Move a pending `new-…` session's state onto the real session id adopted
+ * by a spawn, then discard the transient slot.
+ */
+export function migrateSessionState(fromId: string, toId: string): void {
+  const from = cache.get(fromId);
+  if (from) cache.set(toId, { ...from, ...(cache.get(toId) ?? {}) });
+  touchCacheEntry(toId);
+  readySessions.add(toId);
+  dirtySessions.set(toId, true);
+  schedulePersist(toId);
+  cache.delete(fromId);
+  readySessions.delete(fromId);
+  dirtySessions.delete(fromId);
+  lastTouched.delete(fromId);
+  evictIfNeeded(toId);
+}

package/src/shared/lib/workspace/sidebar-expanded.ts

@@ -0,0 +1,23 @@
+/**
+ * Persistence for the sidebar's expanded-session rows.
+ *
+ * This is cross-session UI state (which session rows show their live subagent
+ * roster), stored in `app_settings` under its own key. The save path caps the
+ * array so it cannot grow without bound.
+ */
+
+import { readChamberSetting, writeSetting } from '@/shared/lib/settings/client';
+
+const SETTINGS_KEY = 'omp_sidebar_expanded_sessions';
+/** Beyond this many ids the oldest are dropped on save. */
+const MAX_IDS = 50;
+
+export function loadExpandedSessionIds(): Set<string> {
+  const parsed = readChamberSetting<unknown>(SETTINGS_KEY);
+  if (!Array.isArray(parsed)) return new Set();
+  return new Set(parsed.filter((id): id is string => typeof id === 'string'));
+}
+
+export function saveExpandedSessionIds(ids: Set<string>): void {
+  writeSetting(SETTINGS_KEY, [...ids].slice(-MAX_IDS));
+}

package/src/shared/lib/workspace/sidebar-sort.test.ts

@@ -0,0 +1,200 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { compareFolders, isValidSessionSortOption, sortFolders } from '@/shared/lib/workspace/sidebar-sort';
+import type { SessionItemData, SessionSortOption, WorkspaceFolderData } from '@/shared/types';
+
+/** Minimal session factory — only the fields the comparator reads. */
+function makeSession(
+  id: number | string,
+  createdAt?: string,
+  updatedAt?: string,
+): SessionItemData {
+  return {
+    id,
+    folder_id: 0,
+    title: `session-${id}`,
+    ...(createdAt !== undefined ? { created_at: createdAt } : {}),
+    ...(updatedAt !== undefined ? { updated_at: updatedAt } : {}),
+  };
+}
+
+/** Minimal folder factory — fills the fields the comparator ignores. */
+function makeFolder(
+  id: number,
+  name: string,
+  sessions: SessionItemData[] = [],
+  isPinned = false,
+): WorkspaceFolderData {
+  return {
+    id,
+    name,
+    isPinned,
+    isExpanded: false,
+    sessions,
+    hasMore: false,
+    totalSessions: sessions.length,
+  };
+}
+
+const ALL_OPTIONS: readonly SessionSortOption[] = [
+  'A-Z',
+  'Z-A',
+  'LATEST_SESSION',
+  'LATEST_ADDED',
+];
+
+describe('sidebar-sort', () => {
+  test('A-Z sorts folder names ascending', () => {
+    const folders = [makeFolder(1, 'zeta'), makeFolder(2, 'alpha'), makeFolder(3, 'mid')];
+    const sorted = sortFolders(folders, 'A-Z');
+    expect(sorted.map((f) => f.name)).toEqual(['alpha', 'mid', 'zeta']);
+  });
+
+  test('Z-A sorts folder names descending', () => {
+    const folders = [makeFolder(1, 'alpha'), makeFolder(2, 'zeta'), makeFolder(3, 'mid')];
+    const sorted = sortFolders(folders, 'Z-A');
+    expect(sorted.map((f) => f.name)).toEqual(['zeta', 'mid', 'alpha']);
+  });
+
+  test('A-Z puts pinned folders first even when their name sorts last', () => {
+    const folders = [
+      makeFolder(1, 'alpha'),
+      makeFolder(2, 'zeta', [], true),
+      makeFolder(3, 'mid'),
+    ];
+    const sorted = sortFolders(folders, 'A-Z');
+    expect(sorted.map((f) => f.name)).toEqual(['zeta', 'alpha', 'mid']);
+  });
+
+  test('LATEST_SESSION orders by newest updated_at desc with omp UUID string ids', () => {
+    const alpha = makeFolder(1, 'alpha', [
+      makeSession('ses_alpha', undefined, '2024-01-01T00:00:00.000Z'),
+    ]);
+    const beta = makeFolder(2, 'beta', [
+      makeSession('ses_beta', undefined, '2024-06-01T00:00:00.000Z'),
+    ]);
+    // Regression: comparing UUID strings numerically produced NaN -> no-op sort.
+    expect(Number.isNaN(compareFolders(alpha, beta, 'LATEST_SESSION'))).toBe(false);
+    const sorted = sortFolders([alpha, beta], 'LATEST_SESSION');
+    expect(sorted.map((f) => f.name)).toEqual(['beta', 'alpha']);
+  });
+
+  test('LATEST_SESSION falls back to created_at when updated_at is absent', () => {
+    const older = makeFolder(1, 'older', [
+      makeSession('ses_old', '2024-02-01T00:00:00.000Z'),
+    ]);
+    const newer = makeFolder(2, 'newer', [
+      makeSession('ses_new', '2024-09-01T00:00:00.000Z'),
+    ]);
+    const sorted = sortFolders([older, newer], 'LATEST_SESSION');
+    expect(sorted.map((f) => f.name)).toEqual(['newer', 'older']);
+  });
+
+  test('LATEST_SESSION breaks identical timestamps by highest numeric session id desc', () => {
+    const shared = '2024-03-03T00:00:00.000Z';
+    const low = makeFolder(1, 'low', [
+      makeSession(5, shared, shared),
+      makeSession(9, shared, shared),
+    ]);
+    const high = makeFolder(2, 'high', [makeSession(42, shared, shared)]);
+    const sorted = sortFolders([low, high], 'LATEST_SESSION');
+    expect(sorted.map((f) => f.name)).toEqual(['high', 'low']);
+  });
+
+  test('LATEST_SESSION puts a folder with no sessions after folders with activity', () => {
+    const empty = makeFolder(1, 'empty', []);
+    const active = makeFolder(2, 'active', [
+      makeSession('ses_x', undefined, '2024-05-05T00:00:00.000Z'),
+    ]);
+    const sorted = sortFolders([empty, active], 'LATEST_SESSION');
+    expect(sorted.map((f) => f.name)).toEqual(['active', 'empty']);
+  });
+
+  test('LATEST_SESSION puts a folder carrying a fresh pending session first', () => {
+    const pending = makeFolder(1, 'pending', [
+      makeSession('new-1737000000000', undefined, '2025-01-16T04:00:00.000Z'),
+    ]);
+    const settled = makeFolder(2, 'settled', [
+      makeSession('ses_settled', undefined, '2024-01-01T00:00:00.000Z'),
+    ]);
+    const sorted = sortFolders([settled, pending], 'LATEST_SESSION');
+    expect(sorted.map((f) => f.name)).toEqual(['pending', 'settled']);
+  });
+
+  test('LATEST_ADDED puts the highest numeric folder id first', () => {
+    const folders = [makeFolder(7, 'seven'), makeFolder(3, 'three'), makeFolder(20, 'twenty')];
+    const sorted = sortFolders(folders, 'LATEST_ADDED');
+    expect(sorted.map((f) => f.name)).toEqual(['twenty', 'seven', 'three']);
+  });
+
+  test('compareFolders returns a finite number for every option with UUID ids and no timestamps', () => {
+    const a = makeFolder(1, 'a', [makeSession('ses_alpha')]);
+    const b = makeFolder(2, 'b', [makeSession('ses_beta')]);
+    for (const option of ALL_OPTIONS) {
+      expect(Number.isNaN(compareFolders(a, b, option))).toBe(false);
+      expect(Number.isNaN(compareFolders(b, a, option))).toBe(false);
+    }
+  });
+
+  test('sortFolders does not mutate its input array', () => {
+    const folders = [makeFolder(1, 'zeta'), makeFolder(2, 'alpha'), makeFolder(3, 'mid')];
+    const before = folders.map((f) => f.name);
+    sortFolders(folders, 'A-Z');
+    expect(folders.map((f) => f.name)).toEqual(before);
+  });
+
+  test('sessions inside a folder are left untouched after sorting', () => {
+    const sessions = [
+      makeSession('ses_one', undefined, '2024-01-01T00:00:00.000Z'),
+      makeSession('ses_two', undefined, '2024-02-01T00:00:00.000Z'),
+    ];
+    const folder = makeFolder(1, 'keep', sessions);
+    const other = makeFolder(2, 'other', []);
+    const sorted = sortFolders([other, folder], 'LATEST_SESSION');
+    const kept = sorted.find((f) => f.name === 'keep');
+    expect(kept?.sessions).toBe(sessions);
+    expect(kept?.sessions.map((s) => s.id)).toEqual(['ses_one', 'ses_two']);
+  });
+});
+
+describe('isValidSessionSortOption', () => {
+  test('returns true for all four supported options', () => {
+    for (const option of ALL_OPTIONS) {
+      expect(isValidSessionSortOption(option)).toBe(true);
+    }
+  });
+
+  test('returns false for non-options and mistyped values', () => {
+    const invalid: unknown[] = [
+      undefined,
+      null,
+      '',
+      'latest_session',
+      'LATEST',
+      42,
+      {},
+      [],
+      true,
+      'A-Z ',
+    ];
+    for (const value of invalid) {
+      expect(isValidSessionSortOption(value)).toBe(false);
+    }
+  });
+
+  test('narrows the value so sortFolders accepts it without a cast', () => {
+    const folders = [makeFolder(1, 'zeta'), makeFolder(2, 'alpha')];
+    const candidate: unknown = 'A-Z';
+    if (isValidSessionSortOption(candidate)) {
+      const sorted = sortFolders(folders, candidate);
+      expect(sorted.map((f) => f.name)).toEqual(['alpha', 'zeta']);
+    } else {
+      throw new Error('expected the guard to narrow "A-Z"');
+    }
+  });
+});

package/src/shared/lib/workspace/sidebar-sort.ts

@@ -0,0 +1,131 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Sidebar workspace ordering, shared by the desktop and mobile session
+ * sidebars. One implementation is deliberate: the two sidebars used to carry
+ * their own comparators, and the mobile copy silently dropped both time-based
+ * options while the desktop copy compared omp session UUIDs numerically
+ * (Math.max over strings -> NaN -> a no-op sort).
+ */
+
+import type { SessionSortOption, WorkspaceFolderData } from '@/shared/types';
+
+/** Epoch ms of an ISO timestamp; NaN when missing or unparseable. */
+function parseTime(value?: string | null): number {
+  if (!value) return Number.NaN;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : Number.NaN;
+}
+
+/** Epoch ms of a folder's newest session; -Infinity when it has none. */
+function latestSessionTime(folder: WorkspaceFolderData): number {
+  let latest = Number.NEGATIVE_INFINITY;
+  for (const session of folder.sessions ?? []) {
+    const time = parseTime(session.updated_at ?? session.created_at);
+    if (time > latest) latest = time;
+  }
+  return latest;
+}
+
+/**
+ * Highest numeric session id in a folder (demo/mock ids are SQLite
+ * AUTOINCREMENT; real omp ids are UUIDs and yield -Infinity). Only a
+ * tiebreaker for equal timestamps — the norm in demo mode, where every seeded
+ * row shares one CURRENT_TIMESTAMP.
+ */
+function latestSessionSeq(folder: WorkspaceFolderData): number {
+  let latest = Number.NEGATIVE_INFINITY;
+  for (const session of folder.sessions ?? []) {
+    const id = Number(session.id);
+    if (Number.isFinite(id) && id > latest) latest = id;
+  }
+  return latest;
+}
+
+/** Numeric folder id, or -Infinity for a non-numeric id. */
+function folderId(folder: WorkspaceFolderData): number {
+  const id = Number(folder.id);
+  return Number.isFinite(id) ? id : Number.NEGATIVE_INFINITY;
+}
+
+/** Descending compare that is safe for -Infinity/-Infinity (never NaN). */
+function compareDesc(a: number, b: number): number {
+  if (a === b) return 0;
+  return a > b ? -1 : 1;
+}
+
+/** Ascending compare that is safe for -Infinity/-Infinity (never NaN). */
+function compareAsc(a: number, b: number): number {
+  if (a === b) return 0;
+  return a > b ? 1 : -1;
+}
+
+/**
+ * Order two sidebar workspaces. Pinned workspaces always lead; every option
+ * then falls back to a deterministic tiebreaker so equal keys never leave the
+ * order to chance.
+ *
+ * - `A-Z` / `Z-A`          — folder name, then folder id asc.
+ * - `LATEST_SESSION`       — newest session activity in the folder
+ *                            (updated_at, else created_at), then highest
+ *                            numeric session id (demo mode), then folder id
+ *                            desc. Folders without sessions sort last.
+ * - `LATEST_ADDED`         — newest folder first (folder id desc), then name.
+ */
+export function compareFolders(
+  a: WorkspaceFolderData,
+  b: WorkspaceFolderData,
+  sortOption: SessionSortOption,
+): number {
+  const pinnedA = Boolean(a.isPinned);
+  const pinnedB = Boolean(b.isPinned);
+  if (pinnedA !== pinnedB) return pinnedA ? -1 : 1;
+
+  switch (sortOption) {
+    case 'Z-A': {
+      const byName = b.name.localeCompare(a.name);
+      return byName !== 0 ? byName : compareAsc(folderId(a), folderId(b));
+    }
+    case 'LATEST_SESSION': {
+      const byTime = compareDesc(latestSessionTime(a), latestSessionTime(b));
+      if (byTime !== 0) return byTime;
+      const bySeq = compareDesc(latestSessionSeq(a), latestSessionSeq(b));
+      if (bySeq !== 0) return bySeq;
+      const byId = compareDesc(folderId(a), folderId(b));
+      return byId !== 0 ? byId : a.name.localeCompare(b.name);
+    }
+    case 'LATEST_ADDED': {
+      const byId = compareDesc(folderId(a), folderId(b));
+      return byId !== 0 ? byId : a.name.localeCompare(b.name);
+    }
+    case 'A-Z':
+    default: {
+      const byName = a.name.localeCompare(b.name);
+      return byName !== 0 ? byName : compareAsc(folderId(a), folderId(b));
+    }
+  }
+}
+
+/** Non-mutating workspace sort — returns a new array, never reorders in place. */
+export function sortFolders(
+  folders: WorkspaceFolderData[],
+  sortOption: SessionSortOption,
+): WorkspaceFolderData[] {
+  return [...folders].sort((a, b) => compareFolders(a, b, sortOption));
+}
+
+/** All supported workspace sort options, in menu order. */
+const SESSION_SORT_OPTIONS: readonly SessionSortOption[] = ['A-Z', 'Z-A', 'LATEST_SESSION', 'LATEST_ADDED'];
+
+/**
+ * Narrow an untrusted value (a DB-stored preference, a URL param) to a sort
+ * option. The loader and both sidebars must agree on what counts as a valid
+ * preference, so the guard lives next to the comparator instead of being
+ * re-implemented per call site.
+ */
+export function isValidSessionSortOption(value: unknown): value is SessionSortOption {
+  return typeof value === 'string' && (SESSION_SORT_OPTIONS as readonly string[]).includes(value);
+}