@cloudcli-ai/cloudcli 1.36.3 → 1.37.1

package/server/{routes/commands.js → modules/commands/commands.routes.ts}

@@ -1,18 +1,31 @@
-import { promises as fs } from "fs";
-import os from "os";
+// @ts-nocheck -- temporary while command handlers are extracted into the injected service.
 import path from "path";
 
 import express from "express";
 
-import { providerModelsService } from "../modules/providers/services/provider-models.service.js";
-import { parseFrontMatter } from "../shared/frontmatter.js";
-import { findAppRoot, getModuleDir } from "../utils/runtime-paths.js";
-
-const __dirname = getModuleDir(import.meta.url);
-// This route reads the top-level package.json for the status command, so it needs the real
-// app root even after compilation moves the route file under dist-server/server/routes.
-const APP_ROOT = findAppRoot(__dirname);
+import { parseFrontMatter } from "../../shared/frontmatter.js";
+
+type CommandsRouterDependencies = {
+  fileSystem: typeof import('node:fs/promises');
+  homeDirectory(): string;
+  appRoot: string;
+  models: typeof import('../providers/index.js').providerModelsService;
+  runtime: {
+    uptime(): number;
+    memoryUsage(): NodeJS.MemoryUsage;
+    version: string;
+    platform: NodeJS.Platform;
+    pid: number;
+  };
+};
 
+/** Creates Commands routes around explicit filesystem, model-catalog, and runtime adapters. */
+export function createCommandsRouter(dependencies: CommandsRouterDependencies): express.Router {
+const fs = dependencies.fileSystem;
+const os = { homedir: dependencies.homeDirectory };
+const APP_ROOT = dependencies.appRoot;
+const providerModelsService = dependencies.models;
+const process = dependencies.runtime;
 const router = express.Router();
 
 const MODEL_PROVIDERS = ["claude", "cursor", "codex", "opencode"];
@@ -33,35 +46,32 @@ const readModelProvider = (value) => {
   return MODEL_PROVIDERS.includes(normalized) ? normalized : "claude";
 };
 
-const hasConcreteSessionId = (value) =>
-  typeof value === "string" && value.trim().length > 0;
-
-const resolveCommandModel = async (provider, catalog, sessionId) => {
-  if (!hasConcreteSessionId(sessionId)) {
-    return catalog.DEFAULT;
-  }
-
-  const currentActiveModel = await providerModelsService.getCurrentActiveModel(
-    provider,
-    sessionId,
-  );
-  return currentActiveModel?.model || catalog.DEFAULT;
+/**
+ * Resolves the model a command should report.
+ *
+ * `context.model` is what the composer would send right now, so it stands in
+ * for a chat that has no session row yet; the service prefers the session's own
+ * recorded model whenever there is one.
+ */
+const resolveCommandModel = async (modelsService, provider, context) => {
+  const resolved = await modelsService.resolveSessionModel(provider, {
+    sessionId: context?.sessionId,
+    requestedModel: context?.model,
+  });
+  return resolved.model;
 };
 
-export const executeModelsCommand = async (args, context) => {
+const executeModelsCommand = async (args, context, modelsService) => {
   const currentProvider = readModelProvider(context?.provider);
-  const result = await providerModelsService.getProviderModels(currentProvider);
-  const catalog = result.models;
-  const currentModel = await resolveCommandModel(
-    currentProvider,
-    catalog,
-    context?.sessionId,
-  );
+  const catalog = await modelsService.getProviderModels(currentProvider);
+  const currentModel = await resolveCommandModel(modelsService, currentProvider, context);
   const availableModels = catalog.OPTIONS.map((option) => option.value);
   const availableOptions = catalog.OPTIONS.map((option) => ({
     value: option.value,
     label: option.label,
     description: option.description,
+    recordId: option.recordId,
+    isCustom: option.isCustom,
   }));
 
   return {
@@ -79,7 +89,6 @@ export const executeModelsCommand = async (args, context) => {
       availableModels,
       availableOptions,
       defaultModel: catalog.DEFAULT,
-      cache: result.cache,
       message: `Current model: ${currentModel}`,
     },
   };
@@ -249,13 +258,12 @@ Custom commands can be created in:
     };
   },
 
-  "/models": executeModelsCommand,
+  "/models": (args, context) => executeModelsCommand(args, context, providerModelsService),
 
   "/cost": async (args, context) => {
     const tokenUsage = context?.tokenUsage || {};
     const provider = readModelProvider(context?.provider);
-    const catalog = (await providerModelsService.getProviderModels(provider)).models;
-    const model = await resolveCommandModel(provider, catalog, context?.sessionId);
+    const model = await resolveCommandModel(providerModelsService, provider, context);
 
     const reportedUsed =
       Number(
@@ -357,8 +365,7 @@ Custom commands can be created in:
         : `${uptimeMinutes}m`;
 
     const statusProvider = readModelProvider(context?.provider);
-    const statusCatalog = (await providerModelsService.getProviderModels(statusProvider)).models;
-    const model = await resolveCommandModel(statusProvider, statusCatalog, context?.sessionId);
+    const model = await resolveCommandModel(providerModelsService, statusProvider, context);
     const memoryUsage = process.memoryUsage();
 
     return {
@@ -593,4 +600,5 @@ router.post("/execute", async (req, res) => {
   }
 });
 
-export default router;
+return router;
+}

package/server/modules/commands/index.ts

@@ -0,0 +1,2 @@
+// commandsRoutes: used by the server entrypoint to mount protected slash-command endpoints.
+export { commandsRoutes } from './commands.module.js';

package/server/modules/commands/tests/commands.test.ts

@@ -0,0 +1,114 @@
+import assert from 'node:assert/strict';
+import { once } from 'node:events';
+import type { AddressInfo } from 'node:net';
+import test from 'node:test';
+
+import express from 'express';
+
+import { createCommandsRouter } from '../commands.routes.js';
+
+/**
+ * Stands in for `providerModelsService`. `resolveSessionModel` mirrors the real
+ * precedence closely enough for the command handlers: a model recorded for the
+ * session wins, otherwise the client's requested model, otherwise the catalog
+ * default.
+ */
+function createModelsService(sessionModels: Record<string, string> = {}) {
+  return {
+    getProviderModels: async () => ({
+      OPTIONS: [{ value: 'default', label: 'Default' }],
+      DEFAULT: 'default',
+    }),
+    getCurrentActiveModel: async () => ({ model: 'default' }),
+    setSessionModel: () => null,
+    resolveSessionModel: async (
+      provider: string,
+      options: { sessionId?: string | null; requestedModel?: string | null } = {},
+    ) => {
+      const recorded = options.sessionId ? sessionModels[options.sessionId] : undefined;
+      const model = recorded || options.requestedModel || 'default';
+      return {
+        provider,
+        sessionId: options.sessionId ?? null,
+        model,
+        source: model === 'default' ? 'default' : 'session',
+      };
+    },
+    resolveResumeModel: async () => undefined,
+  };
+}
+
+async function executeCommand(
+  commandName: string,
+  context: Record<string, unknown>,
+  sessionModels: Record<string, string> = {},
+): Promise<Record<string, unknown>> {
+  const router = createCommandsRouter({
+    fileSystem: {
+      readFile: async () => JSON.stringify({ name: 'claude-code-ui', version: '0.0.0-test' }),
+    } as unknown as typeof import('node:fs/promises'),
+    homeDirectory: () => '/home/test',
+    appRoot: '/app',
+    models: createModelsService(sessionModels) as never,
+    runtime: {
+      uptime: () => 0,
+      memoryUsage: () => ({ rss: 0, heapTotal: 0, heapUsed: 0, external: 0, arrayBuffers: 0 }),
+      version: 'v22', platform: 'linux', pid: 1,
+    },
+  });
+  const app = express().use(express.json()).use('/api/commands', router);
+  const server = app.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  try {
+    const address = server.address() as AddressInfo;
+    const response = await fetch(`http://127.0.0.1:${address.port}/api/commands/execute`, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ commandName, context }),
+    });
+    assert.equal(response.status, 200);
+    return await response.json() as Record<string, unknown>;
+  } finally {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+}
+
+test('models command returns models only for the active provider using injected catalog', async () => {
+  const result = await executeCommand('/models', { provider: 'codex' });
+  const data = result.data as Record<string, unknown>;
+  assert.deepEqual(Object.keys(data.available as object), ['codex']);
+});
+
+test('models command falls back to claude for unsupported providers', async () => {
+  const result = await executeCommand('/models', { provider: 'unknown-provider' });
+  const data = result.data as { current: { provider: string } };
+  assert.equal(data.current.provider, 'claude');
+});
+
+test('models command reports the model recorded for the session', async () => {
+  const result = await executeCommand(
+    '/models',
+    { provider: 'claude', sessionId: 'session-1', model: 'sonnet' },
+    { 'session-1': 'haiku' },
+  );
+
+  const data = result.data as { current: { model: string } };
+  assert.equal(data.current.model, 'haiku');
+});
+
+test('models command reports the composer model for a chat with no session yet', async () => {
+  const result = await executeCommand('/models', { provider: 'claude', model: 'haiku' });
+
+  const data = result.data as { current: { model: string } };
+  assert.equal(data.current.model, 'haiku');
+});
+
+test('cost and status commands report the same resolved model as /models', async () => {
+  const context = { provider: 'claude', sessionId: 'session-1', model: 'sonnet' };
+  const sessionModels = { 'session-1': 'haiku' };
+
+  const cost = await executeCommand('/cost', context, sessionModels);
+  const status = await executeCommand('/status', context, sessionModels);
+
+  assert.equal((cost.data as { model: string }).model, 'haiku');
+  assert.equal((status.data as { model: string }).model, 'haiku');
+});

package/server/modules/database/index.ts

@@ -6,6 +6,9 @@ export { credentialsDb } from '@/modules/database/repositories/credentials.js';
 export { githubTokensDb } from '@/modules/database/repositories/github-tokens.js';
 export { notificationChannelEndpointsDb } from '@/modules/database/repositories/notification-channel-endpoints.js';
 export { notificationPreferencesDb } from '@/modules/database/repositories/notification-preferences.js';
+// providerModelsDb: used by Providers to persist user-managed custom model rows.
+export { providerModelsDb } from '@/modules/database/repositories/provider-models.js';
+// projectsDb: used by Projects, Worktrees, Git, WebSocket, and notification modules to persist and resolve project records.
 export { projectsDb } from '@/modules/database/repositories/projects.db.js';
 export { pushSubscriptionsDb } from '@/modules/database/repositories/push-subscriptions.js';
 export { scanStateDb } from '@/modules/database/repositories/scan-state.db.js';

package/server/modules/database/migrations.ts

@@ -5,6 +5,7 @@ import {
   LAST_SCANNED_AT_SQL,
   NOTIFICATION_CHANNEL_ENDPOINTS_TABLE_SCHEMA_SQL,
   PROJECTS_TABLE_SCHEMA_SQL,
+  PROVIDER_MODELS_TABLE_SCHEMA_SQL,
   PUSH_SUBSCRIPTIONS_TABLE_SCHEMA_SQL,
   SESSIONS_TABLE_SCHEMA_SQL,
   USER_NOTIFICATION_PREFERENCES_TABLE_SCHEMA_SQL,
@@ -402,6 +403,33 @@ const addProviderSessionIdMapping = (db: Database): void => {
   `);
 };
 
+/**
+ * Adds the `model` column that records which model each session runs with.
+ *
+ * Left NULL for pre-existing rows on purpose: the model resolver falls back to
+ * the provider-native lookup for sessions the app has never sent on, so a
+ * backfilled guess would only mask the real value.
+ */
+const addSessionModelColumn = (db: Database): void => {
+  const sessionsTableInfo = getTableInfo(db, 'sessions');
+  const columnNames = sessionsTableInfo.map((column) => column.name);
+
+  addColumnToTableIfNotExists(db, 'sessions', columnNames, 'model', 'TEXT');
+};
+
+/**
+ * Adds the `effort` column that records a session's reasoning-effort choice.
+ *
+ * Existing rows stay NULL so clients can continue falling back to their
+ * per-provider preference until the user selects an effort or sends a turn.
+ */
+const addSessionEffortColumn = (db: Database): void => {
+  const sessionsTableInfo = getTableInfo(db, 'sessions');
+  const columnNames = sessionsTableInfo.map((column) => column.name);
+
+  addColumnToTableIfNotExists(db, 'sessions', columnNames, 'effort', 'TEXT');
+};
+
 const ensureProjectsForSessionPaths = (db: Database): void => {
   if (!tableExists(db, 'sessions')) {
     return;
@@ -444,6 +472,11 @@ export const runMigrations = (db: Database) => {
     db.exec(NOTIFICATION_CHANNEL_ENDPOINTS_TABLE_SCHEMA_SQL);
     db.exec('CREATE INDEX IF NOT EXISTS idx_notification_channel_endpoints_user_channel ON notification_channel_endpoints(user_id, channel)');
     db.exec('CREATE INDEX IF NOT EXISTS idx_notification_channel_endpoints_enabled ON notification_channel_endpoints(enabled)');
+    db.exec(PROVIDER_MODELS_TABLE_SCHEMA_SQL);
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_provider_models_provider_order
+      ON provider_models(provider, sort_order, id)
+    `);
 
     db.exec(PROJECTS_TABLE_SCHEMA_SQL);
     rebuildProjectsTableWithPrimaryKeySchema(db);
@@ -452,6 +485,8 @@ export const runMigrations = (db: Database) => {
     rebuildSessionsTableWithProjectSchema(db);
     migrateLegacySessionNames(db);
     addProviderSessionIdMapping(db);
+    addSessionModelColumn(db);
+    addSessionEffortColumn(db);
     ensureProjectsForSessionPaths(db);
 
     db.exec('CREATE INDEX IF NOT EXISTS idx_session_ids_lookup ON sessions(session_id)');

package/server/modules/database/repositories/provider-models.ts

@@ -0,0 +1,168 @@
+import { getConnection } from '@/modules/database/connection.js';
+import type {
+  CustomProviderModelInput,
+  CustomProviderModelRecord,
+  LLMProvider,
+} from '@/shared/types.js';
+
+type CustomProviderModelRow = {
+  id: number;
+  provider: LLMProvider;
+  model_id: string;
+  model_name: string;
+  sort_order: number;
+};
+
+const toCustomProviderModelRecord = (
+  row: CustomProviderModelRow,
+): CustomProviderModelRecord => ({
+  recordId: row.id,
+  provider: row.provider,
+  modelId: row.model_id,
+  model: row.model_name,
+  sortOrder: row.sort_order,
+});
+
+const readCustomProviderModelRow = (
+  provider: LLMProvider,
+  recordId: number,
+): CustomProviderModelRow | null => {
+  const row = getConnection().prepare(`
+    SELECT id, provider, model_id, model_name, sort_order
+    FROM provider_models
+    WHERE provider = ? AND id = ?
+  `).get(provider, recordId) as CustomProviderModelRow | undefined;
+
+  return row ?? null;
+};
+
+/**
+ * Custom provider-model persistence API consumed by the Providers module.
+ *
+ * Every row in this repository is user-created. Predefined models are owned by
+ * provider adapters and never enter this table. Model-id changes are propagated
+ * to stored sessions, while deletion replaces affected session selections with
+ * the predefined default supplied by the Providers service.
+ */
+export const providerModelsDb = {
+  listCustomProviderModels(provider: LLMProvider): CustomProviderModelRecord[] {
+    const rows = getConnection().prepare(`
+      SELECT id, provider, model_id, model_name, sort_order
+      FROM provider_models
+      WHERE provider = ?
+      ORDER BY sort_order ASC, lower(model_name) ASC, id ASC
+    `).all(provider) as CustomProviderModelRow[];
+
+    return rows.map(toCustomProviderModelRecord);
+  },
+
+  getCustomProviderModel(
+    provider: LLMProvider,
+    recordId: number,
+  ): CustomProviderModelRecord | null {
+    const row = readCustomProviderModelRow(provider, recordId);
+    return row ? toCustomProviderModelRecord(row) : null;
+  },
+
+  findCustomProviderModelByModelId(
+    provider: LLMProvider,
+    modelId: string,
+  ): CustomProviderModelRecord | null {
+    const row = getConnection().prepare(`
+      SELECT id, provider, model_id, model_name, sort_order
+      FROM provider_models
+      WHERE provider = ? AND model_id = ?
+    `).get(provider, modelId) as CustomProviderModelRow | undefined;
+
+    return row ? toCustomProviderModelRecord(row) : null;
+  },
+
+  createCustomProviderModel(
+    provider: LLMProvider,
+    input: CustomProviderModelInput,
+  ): CustomProviderModelRecord {
+    const db = getConnection();
+    const nextOrder = db.prepare(`
+      SELECT COALESCE(MAX(sort_order), -1) + 1 AS next_order
+      FROM provider_models
+      WHERE provider = ?
+    `).get(provider) as { next_order: number };
+
+    const result = db.prepare(`
+      INSERT INTO provider_models (provider, model_id, model_name, sort_order)
+      VALUES (?, ?, ?, ?)
+    `).run(provider, input.id, input.model, nextOrder.next_order);
+
+    const row = readCustomProviderModelRow(provider, Number(result.lastInsertRowid));
+    if (!row) {
+      throw new Error('Created provider model could not be read back.');
+    }
+
+    return toCustomProviderModelRecord(row);
+  },
+
+  updateCustomProviderModel(
+    provider: LLMProvider,
+    recordId: number,
+    input: CustomProviderModelInput,
+  ): CustomProviderModelRecord | null {
+    const db = getConnection();
+    const update = db.transaction(() => {
+      const previous = readCustomProviderModelRow(provider, recordId);
+      if (!previous) {
+        return null;
+      }
+
+      db.prepare(`
+        UPDATE provider_models
+        SET model_id = ?, model_name = ?, updated_at = CURRENT_TIMESTAMP
+        WHERE provider = ? AND id = ?
+      `).run(input.id, input.model, provider, recordId);
+
+      if (previous.model_id !== input.id) {
+        db.prepare(`
+          UPDATE sessions
+          SET model = ?, updated_at = CURRENT_TIMESTAMP
+          WHERE provider = ? AND model = ?
+        `).run(input.id, provider, previous.model_id);
+      }
+
+      return readCustomProviderModelRow(provider, recordId);
+    });
+
+    const row = update();
+    return row ? toCustomProviderModelRecord(row) : null;
+  },
+
+  deleteCustomProviderModel(
+    provider: LLMProvider,
+    recordId: number,
+    fallbackModelId: string,
+  ): CustomProviderModelRecord | null {
+    const db = getConnection();
+    const remove = db.transaction(() => {
+      const row = readCustomProviderModelRow(provider, recordId);
+      if (!row) {
+        return null;
+      }
+
+      // The effort is cleared alongside the model because it was chosen for the
+      // deleted model; replaced sessions resume on the fallback model's default.
+      db.prepare(`
+        UPDATE sessions
+        SET model = ?, effort = NULL, updated_at = CURRENT_TIMESTAMP
+        WHERE provider = ? AND model = ?
+      `).run(fallbackModelId, provider, row.model_id);
+
+      db.prepare(`
+        DELETE FROM provider_models
+        WHERE provider = ? AND id = ?
+      `).run(provider, recordId);
+
+      return row;
+    });
+
+    const row = remove();
+    return row ? toCustomProviderModelRecord(row) : null;
+  },
+};

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

@@ -9,13 +9,22 @@ type SessionRow = {
   project_path: string | null;
   jsonl_path: string | null;
   custom_name: string | null;
+  /** Model this session runs with; NULL until the app records one for it. */
+  model: string | null;
+  /** Reasoning effort this session runs with; NULL until the app records one. */
+  effort: string | null;
   isArchived: number;
   created_at: string;
   updated_at: string;
 };
 
+type RecentSessionsPage = {
+  sessions: SessionRow[];
+  total: number;
+};
+
 const SESSION_ROW_COLUMNS =
-  'session_id, provider, provider_session_id, project_path, jsonl_path, custom_name, isArchived, created_at, updated_at';
+  'session_id, provider, provider_session_id, project_path, jsonl_path, custom_name, model, effort, isArchived, created_at, updated_at';
 
 const SQLITE_UTC_TIMESTAMP_REGEX = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
 
@@ -65,7 +74,9 @@ export const sessionsDb = {
    * The given id is the provider-native session id. Rows are keyed by
    * `provider_session_id` so a session that was first created by the app
    * (with an app-allocated `session_id`) is updated in place once its
-   * transcript shows up on disk, instead of producing a duplicate row.
+   * transcript shows up on disk, instead of producing a duplicate row. An
+   * app-created row keeps its existing name; synchronizer names only update
+   * rows that were themselves created by indexing provider storage.
    */
   createSession(
     providerSessionId: string,
@@ -101,7 +112,10 @@ export const sessionsDb = {
            project_path = ?,
            jsonl_path = ?,
            isArchived = 0,
-           custom_name = COALESCE(?, custom_name)
+           custom_name = CASE
+             WHEN session_id <> provider_session_id AND custom_name IS NOT NULL THEN custom_name
+             ELSE COALESCE(?, custom_name)
+           END
          WHERE session_id = ?`
       ).run(
         provider,
@@ -128,7 +142,11 @@ export const sessionsDb = {
          project_path = excluded.project_path,
          jsonl_path = excluded.jsonl_path,
          isArchived = 0,
-         custom_name = COALESCE(excluded.custom_name, sessions.custom_name)`
+         custom_name = CASE
+           WHEN sessions.session_id <> sessions.provider_session_id AND sessions.custom_name IS NOT NULL
+             THEN sessions.custom_name
+           ELSE COALESCE(excluded.custom_name, sessions.custom_name)
+         END`
     ).run(
       providerSessionId,
       provider,
@@ -149,9 +167,15 @@ export const sessionsDb = {
    * The session gateway uses this when the frontend starts a brand-new chat:
    * `session_id` is the stable app-facing id, while `provider_session_id`
    * stays NULL until the provider runtime announces its own id and
-   * `assignProviderSessionId` records the mapping.
+   * `assignProviderSessionId` records the mapping. `customName` is derived
+   * from the first visible CloudCLI message by the sessions service.
    */
-  createAppSession(sessionId: string, provider: string, projectPath: string): string {
+  createAppSession(
+    sessionId: string,
+    provider: string,
+    projectPath: string,
+    customName?: string,
+  ): string {
     const db = getConnection();
     const normalizedProjectPath = normalizeProjectPathForProvider(provider, projectPath);
 
@@ -159,8 +183,8 @@ export const sessionsDb = {
 
     db.prepare(
       `INSERT INTO sessions (session_id, provider, provider_session_id, custom_name, project_path, jsonl_path, isArchived, created_at, updated_at)
-       VALUES (?, ?, NULL, NULL, ?, NULL, 0, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)`
-    ).run(sessionId, provider, normalizedProjectPath);
+       VALUES (?, ?, NULL, ?, ?, NULL, 0, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)`
+    ).run(sessionId, provider, customName ?? null, normalizedProjectPath);
 
     return sessionId;
   },
@@ -211,6 +235,37 @@ export const sessionsDb = {
     merge();
   },
 
+  /**
+   * Records the model one session runs with.
+   *
+   * Called both when the user picks a model for the session and on every send,
+   * so the row always reflects what the session last ran with and reopening it
+   * restores that model instead of a catalog default.
+   */
+  setSessionModel(sessionId: string, model: string): void {
+    const db = getConnection();
+    db.prepare(
+      `UPDATE sessions
+       SET model = ?
+       WHERE session_id = ?`
+    ).run(model, sessionId);
+  },
+
+  /**
+   * Records the reasoning effort one session runs with.
+   *
+   * `default` is stored as an explicit choice rather than NULL so reopening
+   * the session does not inherit a later per-provider effort preference.
+   */
+  setSessionEffort(sessionId: string, effort: string): void {
+    const db = getConnection();
+    db.prepare(
+      `UPDATE sessions
+       SET effort = ?
+       WHERE session_id = ?`
+    ).run(effort, sessionId);
+  },
+
   updateSessionCustomName(sessionId: string, customName: string): void {
     const db = getConnection();
     db.prepare(
@@ -307,6 +362,46 @@ export const sessionsDb = {
     return normalizeSessionRows(rows);
   },
 
+  /**
+   * Returns one globally ordered page of visible conversations.
+   *
+   * Pagination happens after archived sessions and sessions belonging to an
+   * archived project have been excluded. This keeps the sidebar feed complete
+   * and correctly ordered across projects instead of flattening only the
+   * per-project slices already loaded by the client.
+   */
+  getRecentSessionsPage(limit: number, offset: number): RecentSessionsPage {
+    const db = getConnection();
+    const visibilityClause = `
+      sessions.isArchived = 0
+      AND (projects.isArchived IS NULL OR projects.isArchived = 0)
+    `;
+    const rows = db
+      .prepare(
+        `SELECT sessions.*
+         FROM sessions
+         LEFT JOIN projects ON projects.project_path = sessions.project_path
+         WHERE ${visibilityClause}
+         ORDER BY julianday(COALESCE(sessions.updated_at, sessions.created_at)) DESC,
+                  sessions.session_id DESC
+         LIMIT ? OFFSET ?`
+      )
+      .all(limit, offset) as SessionRow[];
+    const countRow = db
+      .prepare(
+        `SELECT COUNT(*) AS count
+         FROM sessions
+         LEFT JOIN projects ON projects.project_path = sessions.project_path
+         WHERE ${visibilityClause}`
+      )
+      .get() as { count: number } | undefined;
+
+    return {
+      sessions: normalizeSessionRows(rows),
+      total: Number(countRow?.count ?? 0),
+    };
+  },
+
   /**
    * Archived rows are intentionally queried separately so the caller can render
    * them in a dedicated view without reintroducing them into active session lists.