@cloudcli-ai/cloudcli 1.37.1 → 1.37.3

package/server/modules/database/migrations.ts

@@ -7,7 +7,11 @@ import {
   PROJECTS_TABLE_SCHEMA_SQL,
   PROVIDER_MODELS_TABLE_SCHEMA_SQL,
   PUSH_SUBSCRIPTIONS_TABLE_SCHEMA_SQL,
+  SESSION_DRAFTS_TABLE_SCHEMA_SQL,
+  SUPERSEDED_PROVIDER_SESSIONS_TABLE_SCHEMA_SQL,
+  SCHEDULED_MESSAGES_TABLE_SCHEMA_SQL,
   SESSIONS_TABLE_SCHEMA_SQL,
+  USER_PREFERENCES_TABLE_SCHEMA_SQL,
   USER_NOTIFICATION_PREFERENCES_TABLE_SCHEMA_SQL,
   VAPID_KEYS_TABLE_SCHEMA_SQL,
 } from '@/modules/database/schema.js';
@@ -403,6 +407,29 @@ const addProviderSessionIdMapping = (db: Database): void => {
   `);
 };
 
+/**
+ * Adds the `forked_from_session_id` column recording where a branched session
+ * came from.
+ *
+ * Nothing is backfilled: a session that predates forking was not forked.
+ */
+/**
+ * Adds the transcript path to the superseded-session record.
+ *
+ * Only rows written before this column existed lack it, and there is nothing
+ * to backfill from — the session stopped pointing at that file when the row
+ * was created — so they keep a NULL and the delete path skips them.
+ */
+const addSupersededTranscriptPathColumn = (db: Database): void => {
+  const columnNames = getTableInfo(db, 'superseded_provider_sessions').map((column) => column.name);
+  addColumnToTableIfNotExists(db, 'superseded_provider_sessions', columnNames, 'jsonl_path', 'TEXT');
+};
+
+const addForkedFromSessionIdColumn = (db: Database): void => {
+  const columnNames = getTableInfo(db, 'sessions').map((column) => column.name);
+  addColumnToTableIfNotExists(db, 'sessions', columnNames, 'forked_from_session_id', 'TEXT');
+};
+
 /**
  * Adds the `model` column that records which model each session runs with.
  *
@@ -477,6 +504,10 @@ export const runMigrations = (db: Database) => {
       CREATE INDEX IF NOT EXISTS idx_provider_models_provider_order
       ON provider_models(provider, sort_order, id)
     `);
+    db.exec(USER_PREFERENCES_TABLE_SCHEMA_SQL);
+    db.exec(SESSION_DRAFTS_TABLE_SCHEMA_SQL);
+    db.exec(SUPERSEDED_PROVIDER_SESSIONS_TABLE_SCHEMA_SQL);
+    addSupersededTranscriptPathColumn(db);
 
     db.exec(PROJECTS_TABLE_SCHEMA_SQL);
     rebuildProjectsTableWithPrimaryKeySchema(db);
@@ -487,11 +518,17 @@ export const runMigrations = (db: Database) => {
     addProviderSessionIdMapping(db);
     addSessionModelColumn(db);
     addSessionEffortColumn(db);
+    addForkedFromSessionIdColumn(db);
     ensureProjectsForSessionPaths(db);
+    db.exec(SCHEDULED_MESSAGES_TABLE_SCHEMA_SQL);
 
     db.exec('CREATE INDEX IF NOT EXISTS idx_session_ids_lookup ON sessions(session_id)');
     db.exec('CREATE INDEX IF NOT EXISTS idx_sessions_provider_session_id ON sessions(provider_session_id)');
     db.exec('CREATE INDEX IF NOT EXISTS idx_sessions_project_path ON sessions(project_path)');
+    db.exec('CREATE INDEX IF NOT EXISTS idx_sessions_forked_from ON sessions(forked_from_session_id)');
+    // The due-message poll runs on a timer; without this it table-scans.
+    db.exec('CREATE INDEX IF NOT EXISTS idx_scheduled_messages_due ON scheduled_messages(status, scheduled_for)');
+    db.exec('CREATE INDEX IF NOT EXISTS idx_scheduled_messages_session ON scheduled_messages(session_id)');
     db.exec('CREATE INDEX IF NOT EXISTS idx_sessions_is_archived ON sessions(isArchived)');
     db.exec('CREATE INDEX IF NOT EXISTS idx_projects_is_starred ON projects(isStarred)');
     db.exec('CREATE INDEX IF NOT EXISTS idx_projects_is_archived ON projects(isArchived)');

package/server/modules/database/repositories/scheduled-messages.db.ts

@@ -0,0 +1,127 @@
+import { randomUUID } from 'node:crypto';
+
+import { getConnection } from '@/modules/database/connection.js';
+
+export type ScheduledMessageStatus = 'pending' | 'sent' | 'failed' | 'cancelled';
+
+export type ScheduledMessageRow = {
+  id: string;
+  user_id: number;
+  session_id: string;
+  content: string;
+  options: string;
+  scheduled_for: string;
+  status: ScheduledMessageStatus;
+  failure_reason: string | null;
+  created_at: string;
+  updated_at: string;
+};
+
+const COLUMNS =
+  'id, user_id, session_id, content, options, scheduled_for, status, failure_reason, created_at, updated_at';
+
+export const scheduledMessagesDb = {
+  create(input: {
+    userId: number;
+    sessionId: string;
+    content: string;
+    options: unknown;
+    scheduledFor: Date;
+  }): ScheduledMessageRow {
+    const db = getConnection();
+    const id = randomUUID();
+
+    db.prepare(
+      `INSERT INTO scheduled_messages (id, user_id, session_id, content, options, scheduled_for, status)
+       VALUES (?, ?, ?, ?, ?, ?, 'pending')`
+    ).run(
+      id,
+      input.userId,
+      input.sessionId,
+      input.content,
+      JSON.stringify(input.options ?? {}),
+      input.scheduledFor.toISOString(),
+    );
+
+    return db.prepare(`SELECT ${COLUMNS} FROM scheduled_messages WHERE id = ?`).get(id) as ScheduledMessageRow;
+  },
+
+  /** Everything still to come or recently resolved, newest schedule first. */
+  listForSession(userId: number, sessionId: string): ScheduledMessageRow[] {
+    return getConnection()
+      .prepare(
+        `SELECT ${COLUMNS} FROM scheduled_messages
+         WHERE user_id = ? AND session_id = ?
+         ORDER BY scheduled_for ASC`
+      )
+      .all(userId, sessionId) as ScheduledMessageRow[];
+  },
+
+  listPendingForUser(userId: number): ScheduledMessageRow[] {
+    return getConnection()
+      .prepare(
+        `SELECT ${COLUMNS} FROM scheduled_messages
+         WHERE user_id = ? AND status = 'pending'
+         ORDER BY scheduled_for ASC`
+      )
+      .all(userId) as ScheduledMessageRow[];
+  },
+
+  /**
+   * Claims every message whose time has passed, marking them in the same
+   * statement that selects them.
+   *
+   * Claiming is what makes a missed schedule work: the server can be down at
+   * the moment a message was due, and the next poll after it starts picks the
+   * message up instead of skipping it. Doing it in one transaction is what
+   * stops two overlapping polls from sending the same message twice.
+   */
+  claimDue(now: Date): ScheduledMessageRow[] {
+    const db = getConnection();
+    const nowIso = now.toISOString();
+
+    return db.transaction(() => {
+      const due = db
+        .prepare(
+          `SELECT ${COLUMNS} FROM scheduled_messages
+           WHERE status = 'pending' AND scheduled_for <= ?
+           ORDER BY scheduled_for ASC`
+        )
+        .all(nowIso) as ScheduledMessageRow[];
+
+      for (const row of due) {
+        db.prepare(
+          `UPDATE scheduled_messages SET status = 'sent', updated_at = CURRENT_TIMESTAMP WHERE id = ?`
+        ).run(row.id);
+      }
+
+      return due;
+    })();
+  },
+
+  markFailed(id: string, reason: string): void {
+    getConnection()
+      .prepare(
+        `UPDATE scheduled_messages
+         SET status = 'failed', failure_reason = ?, updated_at = CURRENT_TIMESTAMP
+         WHERE id = ?`
+      )
+      .run(reason.slice(0, 500), id);
+  },
+
+  /**
+   * Cancels a pending message, or dismisses a failed one so its banner goes
+   * away. Returns false when it had already fired successfully.
+   */
+  cancel(userId: number, id: string): boolean {
+    const result = getConnection()
+      .prepare(
+        `UPDATE scheduled_messages
+         SET status = 'cancelled', updated_at = CURRENT_TIMESTAMP
+         WHERE id = ? AND user_id = ? AND status IN ('pending', 'failed')`
+      )
+      .run(id, userId);
+
+    return result.changes > 0;
+  },
+};

package/server/modules/database/repositories/session-drafts.db.ts

@@ -0,0 +1,171 @@
+import { getConnection } from '@/modules/database/connection.js';
+
+/**
+ * One chat scope's unsent state: the text still in the composer, plus the
+ * message queued behind an in-flight turn. Both are optional — a scope can
+ * hold only a draft, only a queued message, or both.
+ */
+export type SessionDraftRecord = {
+  scope: string;
+  text: string;
+  queuedMessage: unknown | null;
+  updatedAt: string;
+};
+
+type DraftRow = {
+  draft_scope: string;
+  draft_text: string;
+  queued_message: string | null;
+  updated_at: string;
+};
+
+/** A server-owned queued turn together with the exact stored value used to claim it once. */
+export type QueuedSessionMessageRecord = {
+  userId: number;
+  sessionId: string;
+  queuedMessage: unknown;
+  claimToken: string;
+};
+
+type QueuedMessageRow = {
+  user_id: number;
+  draft_scope: string;
+  queued_message: string;
+};
+
+/** A queued message that no longer parses is treated as absent, not fatal. */
+function parseQueuedMessage(raw: string | null): unknown | null {
+  if (!raw) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+function toRecord(row: DraftRow): SessionDraftRecord {
+  return {
+    scope: row.draft_scope,
+    text: row.draft_text,
+    queuedMessage: parseQueuedMessage(row.queued_message),
+    updatedAt: row.updated_at,
+  };
+}
+
+export const sessionDraftsDb = {
+  /**
+   * Returns every draft the user has, newest first.
+   *
+   * The client pulls the whole set once per load: drafts are short strings, and
+   * having them all up front means switching sessions restores a draft written
+   * on another device without a round trip.
+   */
+  getDrafts(userId: number): SessionDraftRecord[] {
+    const db = getConnection();
+    const rows = db
+      .prepare(
+        `SELECT draft_scope, draft_text, queued_message, updated_at
+         FROM session_drafts
+         WHERE user_id = ?
+         ORDER BY datetime(updated_at) DESC`
+      )
+      .all(userId) as DraftRow[];
+
+    return rows.map(toRecord);
+  },
+
+  /** Lists persisted queued turns whose scopes are real chat sessions. */
+  listQueuedMessages(): QueuedSessionMessageRecord[] {
+    const rows = getConnection()
+      .prepare(
+        `SELECT drafts.user_id, drafts.draft_scope, drafts.queued_message
+         FROM session_drafts AS drafts
+         INNER JOIN sessions ON sessions.session_id = drafts.draft_scope
+         WHERE drafts.queued_message IS NOT NULL`
+      )
+      .all() as QueuedMessageRow[];
+
+    return rows.map((row) => ({
+      userId: row.user_id,
+      sessionId: row.draft_scope,
+      queuedMessage: parseQueuedMessage(row.queued_message),
+      claimToken: row.queued_message,
+    }));
+  },
+
+  /** Atomically removes a queued turn only if it has not been edited since listing. */
+  claimQueuedMessage(candidate: QueuedSessionMessageRecord): boolean {
+    const result = getConnection()
+      .prepare(
+        `UPDATE session_drafts
+         SET queued_message = NULL, updated_at = CURRENT_TIMESTAMP
+         WHERE user_id = ? AND draft_scope = ? AND queued_message = ?`
+      )
+      .run(candidate.userId, candidate.sessionId, candidate.claimToken);
+    return result.changes > 0;
+  },
+
+  /** Restores a claim lost to the narrow race where another run starts first. */
+  restoreQueuedMessage(candidate: QueuedSessionMessageRecord): void {
+    getConnection()
+      .prepare(
+        `UPDATE session_drafts
+         SET queued_message = ?, updated_at = CURRENT_TIMESTAMP
+         WHERE user_id = ? AND draft_scope = ? AND queued_message IS NULL`
+      )
+      .run(candidate.claimToken, candidate.userId, candidate.sessionId);
+  },
+
+  /** Removes the placeholder row left after its last queued turn is claimed. */
+  deleteEmptyDraft(userId: number, scope: string): void {
+    getConnection()
+      .prepare(
+        `DELETE FROM session_drafts
+         WHERE user_id = ? AND draft_scope = ? AND draft_text = '' AND queued_message IS NULL`
+      )
+      .run(userId, scope);
+  },
+
+  /**
+   * Writes one scope's draft, or deletes the row when nothing is left to keep.
+   *
+   * Deleting on empty is what stops the table growing a permanent row for every
+   * session the user ever opened and typed a character into.
+   */
+  saveDraft(
+    userId: number,
+    scope: string,
+    draft: { text: string; queuedMessage: unknown | null }
+  ): void {
+    const db = getConnection();
+
+    if (!draft.text && draft.queuedMessage === null) {
+      db.prepare('DELETE FROM session_drafts WHERE user_id = ? AND draft_scope = ?')
+        .run(userId, scope);
+      return;
+    }
+
+    db.prepare(
+      `INSERT INTO session_drafts (user_id, draft_scope, draft_text, queued_message, updated_at)
+       VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP)
+       ON CONFLICT(user_id, draft_scope) DO UPDATE SET
+         draft_text = excluded.draft_text,
+         queued_message = excluded.queued_message,
+         updated_at = CURRENT_TIMESTAMP`
+    ).run(
+      userId,
+      scope,
+      draft.text,
+      draft.queuedMessage === null ? null : JSON.stringify(draft.queuedMessage)
+    );
+  },
+
+  deleteDraft(userId: number, scope: string): void {
+    const db = getConnection();
+    db.prepare('DELETE FROM session_drafts WHERE user_id = ? AND draft_scope = ?')
+      .run(userId, scope);
+  },
+};

package/server/modules/database/repositories/sessions.db.ts

@@ -13,6 +13,8 @@ type SessionRow = {
   model: string | null;
   /** Reasoning effort this session runs with; NULL until the app records one. */
   effort: string | null;
+  /** The app session this one was branched from; NULL unless it is a fork. */
+  forked_from_session_id: string | null;
   isArchived: number;
   created_at: string;
   updated_at: string;
@@ -24,7 +26,7 @@ type RecentSessionsPage = {
 };
 
 const SESSION_ROW_COLUMNS =
-  'session_id, provider, provider_session_id, project_path, jsonl_path, custom_name, model, effort, isArchived, created_at, updated_at';
+  'session_id, provider, provider_session_id, project_path, jsonl_path, custom_name, model, effort, forked_from_session_id, isArchived, created_at, updated_at';
 
 const SQLITE_UTC_TIMESTAMP_REGEX = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
 
@@ -111,7 +113,7 @@ export const sessionsDb = {
            updated_at = COALESCE(?, CURRENT_TIMESTAMP),
            project_path = ?,
            jsonl_path = ?,
-           isArchived = 0,
+           isArchived = CASE WHEN ? IS NULL OR julianday(?) > julianday(updated_at) THEN 0 ELSE isArchived END,
            custom_name = CASE
              WHEN session_id <> provider_session_id AND custom_name IS NOT NULL THEN custom_name
              ELSE COALESCE(?, custom_name)
@@ -122,6 +124,8 @@ export const sessionsDb = {
         updatedAtValue,
         normalizedProjectPath,
         jsonlPath ?? null,
+        updatedAtValue,
+        updatedAtValue,
         customName ?? null,
         existing.session_id
       );
@@ -141,7 +145,7 @@ export const sessionsDb = {
          updated_at = excluded.updated_at,
          project_path = excluded.project_path,
          jsonl_path = excluded.jsonl_path,
-         isArchived = 0,
+         isArchived = CASE WHEN ? IS NULL OR julianday(excluded.updated_at) > julianday(sessions.updated_at) THEN 0 ELSE sessions.isArchived END,
          custom_name = CASE
            WHEN sessions.session_id <> sessions.provider_session_id AND sessions.custom_name IS NOT NULL
              THEN sessions.custom_name
@@ -155,6 +159,7 @@ export const sessionsDb = {
       normalizedProjectPath,
       jsonlPath ?? null,
       createdAtValue,
+      updatedAtValue,
       updatedAtValue
     );
 
@@ -189,6 +194,55 @@ export const sessionsDb = {
     return sessionId;
   },
 
+  /**
+   * Inserts a session that already has its provider artifact on disk.
+   *
+   * Unlike `createAppSession` this writes `provider_session_id` and
+   * `jsonl_path` immediately, because a fork's transcript file exists before
+   * the row does — and the filesystem watcher would otherwise index it as an
+   * unrelated session under its own id.
+   */
+  createForkedSession(input: {
+    sessionId: string;
+    provider: string;
+    projectPath: string;
+    customName: string | null;
+    providerSessionId: string;
+    jsonlPath: string;
+    forkedFromSessionId: string;
+    model: string | null;
+    effort: string | null;
+  }): string {
+    const db = getConnection();
+    const normalizedProjectPath = normalizeProjectPathForProvider(input.provider, input.projectPath);
+
+    projectsDb.createProjectPath(normalizedProjectPath);
+
+    // The watcher may already have created a row for the new transcript. Its
+    // id is the provider-native one, which is what this row claims, so replace
+    // it rather than leaving two sidebar entries for one conversation.
+    db.transaction(() => {
+      db.prepare('DELETE FROM sessions WHERE session_id = ? AND session_id <> ?')
+        .run(input.providerSessionId, input.sessionId);
+      db.prepare(
+        `INSERT INTO sessions (session_id, provider, provider_session_id, custom_name, project_path, jsonl_path, model, effort, forked_from_session_id, isArchived, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)`
+      ).run(
+        input.sessionId,
+        input.provider,
+        input.providerSessionId,
+        input.customName,
+        normalizedProjectPath,
+        input.jsonlPath,
+        input.model,
+        input.effort,
+        input.forkedFromSessionId,
+      );
+    })();
+
+    return input.sessionId;
+  },
+
   /**
    * Records the provider-native session id for one app-allocated session.
    *
@@ -235,6 +289,125 @@ export const sessionsDb = {
     merge();
   },
 
+  /**
+   * Moves one session onto a different provider session and transcript.
+   *
+   * Only editing a message on a provider that has to branch to rewind (Codex)
+   * does this — an ordinary run keeps the same provider session for its whole
+   * life. `assignProviderSessionId` cannot be used for it: that one keeps the
+   * existing `jsonl_path` on purpose, so a session repointed with it would
+   * claim the new thread while still reading the old transcript.
+   *
+   * The watcher may already have indexed the new transcript under its own id.
+   * That row is the same conversation this one is about to become, so it is
+   * replaced rather than left behind as a second sidebar entry.
+   */
+  repointSessionToProviderSession(
+    sessionId: string,
+    input: { providerSessionId: string; jsonlPath: string },
+  ): void {
+    const db = getConnection();
+
+    db.transaction(() => {
+      db.prepare('DELETE FROM sessions WHERE session_id = ? AND session_id <> ?')
+        .run(input.providerSessionId, sessionId);
+      db.prepare(
+        `UPDATE sessions SET
+           provider_session_id = ?,
+           jsonl_path = ?,
+           updated_at = CURRENT_TIMESTAMP
+         WHERE session_id = ?`
+      ).run(input.providerSessionId, input.jsonlPath, sessionId);
+    })();
+  },
+
+  /**
+   * Detaches a session from its provider session so the next run starts a new
+   * one.
+   *
+   * Used when an edit replaces the very first prompt: there is no conversation
+   * left to branch from, so the session starts over instead.
+   */
+  detachProviderSession(sessionId: string): void {
+    const db = getConnection();
+    db.prepare(
+      `UPDATE sessions SET
+         provider_session_id = NULL,
+         jsonl_path = NULL,
+         updated_at = CURRENT_TIMESTAMP
+       WHERE session_id = ?`
+    ).run(sessionId);
+  },
+
+  /**
+   * Records that a session has left a provider session behind for good.
+   *
+   * The transcript stays on disk, which is deliberate — the abandoned attempt
+   * is recoverable — but the indexer must not offer it back, and on a session
+   * discovered from disk (whose app id *is* the provider id) rediscovering it
+   * would repoint the row at the conversation the user edited away from.
+   */
+  markProviderSessionSuperseded(input: {
+    providerSessionId: string;
+    provider: string;
+    sessionId: string;
+    jsonlPath: string | null;
+  }): void {
+    const db = getConnection();
+    db.prepare(
+      `INSERT INTO superseded_provider_sessions (provider_session_id, provider, session_id, jsonl_path)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(provider_session_id, provider) DO UPDATE SET
+         session_id = excluded.session_id,
+         jsonl_path = excluded.jsonl_path,
+         created_at = CURRENT_TIMESTAMP`
+    ).run(input.providerSessionId, input.provider, input.sessionId, input.jsonlPath);
+  },
+
+  isProviderSessionSuperseded(providerSessionId: string, provider: string): boolean {
+    const db = getConnection();
+    const row = db
+      .prepare(
+        `SELECT 1 AS found FROM superseded_provider_sessions
+         WHERE provider_session_id = ? AND provider = ?
+         LIMIT 1`
+      )
+      .get(providerSessionId, provider) as { found: number } | undefined;
+
+    return Boolean(row);
+  },
+
+  /**
+   * Transcripts one session has left behind, for the caller that deletes a
+   * conversation from disk.
+   *
+   * A conversation edited more than once has lived in more than one file, and
+   * the session row only ever points at the newest.
+   */
+  getSupersededTranscriptPaths(sessionId: string): string[] {
+    const db = getConnection();
+    const rows = db
+      .prepare(
+        `SELECT jsonl_path FROM superseded_provider_sessions
+         WHERE session_id = ? AND jsonl_path IS NOT NULL`
+      )
+      .all(sessionId) as Array<{ jsonl_path: string }>;
+
+    return rows.map((row) => row.jsonl_path);
+  },
+
+  /**
+   * Forgets what a session left behind, once the session itself is gone.
+   *
+   * Without this the record outlives the row it was written for and keeps the
+   * indexer refusing a transcript that no longer belongs to anything — a
+   * conversation invisible to the app and impossible to delete through it.
+   */
+  clearSupersededProviderSessions(sessionId: string): void {
+    const db = getConnection();
+    db.prepare('DELETE FROM superseded_provider_sessions WHERE session_id = ?').run(sessionId);
+  },
+
   /**
    * Records the model one session runs with.
    *
@@ -521,4 +694,24 @@ export const sessionsDb = {
     const db = getConnection();
     return db.prepare('DELETE FROM sessions WHERE session_id = ?').run(sessionId).changes > 0;
   },
+
+  /**
+   * Lists every indexed session that claims a transcript file on disk.
+   *
+   * Only rows with a `jsonl_path` are returned, which deliberately excludes
+   * app-created sessions still waiting for their first provider write and
+   * OpenCode rows (whose transcripts all live inside one shared sqlite file).
+   * Used by the session synchronizer to find rows whose transcript has been
+   * deleted underneath the index.
+   */
+  getSessionsWithTranscriptPath(): Array<{ session_id: string; jsonl_path: string }> {
+    const db = getConnection();
+    return db
+      .prepare(
+        `SELECT session_id, jsonl_path
+         FROM sessions
+         WHERE jsonl_path IS NOT NULL AND jsonl_path <> ''`
+      )
+      .all() as Array<{ session_id: string; jsonl_path: string }>;
+  },
 };

package/server/modules/database/repositories/user-preferences.db.ts

@@ -0,0 +1,80 @@
+import { getConnection } from '@/modules/database/connection.js';
+
+type PreferenceRow = {
+  preference_key: string;
+  preference_value: string;
+};
+
+/**
+ * Decodes one stored preference, dropping any row whose JSON no longer parses
+ * rather than failing the whole read. A single corrupted value must not cost
+ * the user every other setting they have.
+ */
+function decodePreference(row: PreferenceRow): [string, unknown] | null {
+  try {
+    return [row.preference_key, JSON.parse(row.preference_value) as unknown];
+  } catch {
+    console.warn(`[UserPreferences] Dropping unreadable value for "${row.preference_key}"`);
+    return null;
+  }
+}
+
+export const userPreferencesDb = {
+  /**
+   * Returns every preference the user has ever set, as one object.
+   *
+   * The client fetches this once on start-up, so absent keys simply mean "the
+   * user never changed this" and the client applies its own default.
+   */
+  getPreferences(userId: number): Record<string, unknown> {
+    const db = getConnection();
+    const rows = db
+      .prepare(
+        `SELECT preference_key, preference_value
+         FROM user_preferences
+         WHERE user_id = ?`
+      )
+      .all(userId) as PreferenceRow[];
+
+    const preferences: Record<string, unknown> = {};
+    for (const row of rows) {
+      const decoded = decodePreference(row);
+      if (decoded) {
+        preferences[decoded[0]] = decoded[1];
+      }
+    }
+
+    return preferences;
+  },
+
+  /**
+   * Merge-patches preferences: keys present in `updates` are written, keys
+   * absent are left alone, and a key given as `undefined` is deleted.
+   *
+   * Runs in one transaction so a multi-key save from the settings dialog can
+   * never be observed half-applied.
+   */
+  savePreferences(userId: number, updates: Record<string, unknown>): void {
+    const db = getConnection();
+    const upsert = db.prepare(
+      `INSERT INTO user_preferences (user_id, preference_key, preference_value, updated_at)
+       VALUES (?, ?, ?, CURRENT_TIMESTAMP)
+       ON CONFLICT(user_id, preference_key) DO UPDATE SET
+         preference_value = excluded.preference_value,
+         updated_at = CURRENT_TIMESTAMP`
+    );
+    const remove = db.prepare(
+      'DELETE FROM user_preferences WHERE user_id = ? AND preference_key = ?'
+    );
+
+    db.transaction(() => {
+      for (const [key, value] of Object.entries(updates)) {
+        if (value === undefined) {
+          remove.run(userId, key);
+          continue;
+        }
+        upsert.run(userId, key, JSON.stringify(value));
+      }
+    })();
+  },
+};