@cloudcli-ai/cloudcli 1.37.0 → 1.37.2

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

@@ -11,13 +11,20 @@ type SessionRow = {
   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, model, 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}$/;
 
@@ -67,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,
@@ -103,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,
@@ -130,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,
@@ -151,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);
 
@@ -161,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;
   },
@@ -229,6 +251,21 @@ export const sessionsDb = {
     ).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(
@@ -325,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.

package/server/modules/database/schema.ts

@@ -109,10 +109,11 @@ CREATE TABLE IF NOT EXISTS sessions (
     custom_name TEXT,
     project_path TEXT,
     jsonl_path TEXT,
-    -- Model this session runs with. Written when the user picks a model for the
-    -- session and on every send, so reopening a session restores the model it
-    -- was last used with instead of falling back to the catalog default.
+    -- Model and reasoning effort this session runs with. Written when the user
+    -- changes either selection and on every send, so reopening a session
+    -- restores its exact runtime configuration instead of provider defaults.
     model TEXT,
+    effort TEXT,
     isArchived BOOLEAN DEFAULT 0,
     created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
     updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
@@ -138,6 +139,27 @@ CREATE TABLE IF NOT EXISTS app_config (
 );
 `;
 
+/**
+ * Persistent custom-model library used by the Providers module.
+ *
+ * Only user-created models are stored here. Predefined models remain source-
+ * controlled in each provider's `-models.provider.ts` adapter so they can be
+ * updated without migrating application data. `model_id` is unique only within
+ * a provider because different CLIs can accept the same identifier.
+ */
+export const PROVIDER_MODELS_TABLE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS provider_models (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    provider TEXT NOT NULL CHECK (provider IN ('claude', 'cursor', 'codex', 'opencode')),
+    model_id TEXT NOT NULL,
+    model_name TEXT NOT NULL,
+    sort_order INTEGER NOT NULL DEFAULT 0,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(provider, model_id)
+);
+`;
+
 export const INIT_SCHEMA_SQL = `
 -- Initialize authentication database
 PRAGMA foreign_keys = ON;
@@ -181,4 +203,8 @@ CREATE INDEX IF NOT EXISTS idx_session_ids_lookup ON sessions(session_id);
 ${LAST_SCANNED_AT_SQL}
 
 ${APP_CONFIG_TABLE_SCHEMA_SQL}
+
+${PROVIDER_MODELS_TABLE_SCHEMA_SQL}
+CREATE INDEX IF NOT EXISTS idx_provider_models_provider_order
+ON provider_models(provider, sort_order, id);
 `;

package/server/modules/database/tests/provider-models.db.integration.test.ts

@@ -0,0 +1,125 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import {
+  closeConnection,
+  getConnection,
+  initializeDatabase,
+  providerModelsDb,
+  sessionsDb,
+} from '@/modules/database/index.js';
+import { runMigrations } from '@/modules/database/migrations.js';
+
+test('provider model repository stores custom rows only and maintains session references', async () => {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const tempDirectory = await mkdtemp(path.join(os.tmpdir(), 'provider-model-db-'));
+  const databasePath = path.join(tempDirectory, 'auth.db');
+
+  closeConnection();
+  process.env.DATABASE_PATH = databasePath;
+  await writeFile(databasePath, '');
+  await initializeDatabase();
+
+  try {
+    const columns = getConnection().prepare('PRAGMA table_info(provider_models)').all() as Array<{
+      name: string;
+    }>;
+    assert.deepEqual(columns.map((column) => column.name), [
+      'id',
+      'provider',
+      'model_id',
+      'model_name',
+      'sort_order',
+      'created_at',
+      'updated_at',
+    ]);
+    assert.deepEqual(providerModelsDb.listCustomProviderModels('codex'), []);
+
+    const custom = providerModelsDb.createCustomProviderModel('codex', {
+      model: 'Private Gateway Model',
+      id: 'gateway/model-v1',
+    });
+    assert.equal(custom.modelId, 'gateway/model-v1');
+    assert.equal(
+      providerModelsDb.findCustomProviderModelByModelId('codex', 'gateway/model-v1')?.recordId,
+      custom.recordId,
+    );
+
+    const db = getConnection();
+    db.prepare(`
+      INSERT INTO projects (project_id, project_path)
+      VALUES ('project-1', '/tmp/project-1')
+    `).run();
+    db.prepare(`
+      INSERT INTO sessions (session_id, provider, project_path, model, effort)
+      VALUES ('session-1', 'codex', '/tmp/project-1', 'gateway/model-v1', 'high')
+    `).run();
+
+    const updated = providerModelsDb.updateCustomProviderModel('codex', custom.recordId, {
+      model: 'Private Gateway Model 2',
+      id: 'gateway/model-v2',
+    });
+    assert.equal(updated?.modelId, 'gateway/model-v2');
+    assert.equal(sessionsDb.getSessionById('session-1')?.model, 'gateway/model-v2');
+    // A rename keeps the same underlying model, so its effort stays applicable.
+    assert.equal(sessionsDb.getSessionById('session-1')?.effort, 'high');
+
+    const removed = providerModelsDb.deleteCustomProviderModel(
+      'codex',
+      custom.recordId,
+      'gpt-default',
+    );
+    assert.equal(removed?.modelId, 'gateway/model-v2');
+    assert.equal(sessionsDb.getSessionById('session-1')?.model, 'gpt-default');
+    // The effort belonged to the deleted model and must not survive onto the
+    // fallback, which has its own default.
+    assert.equal(sessionsDb.getSessionById('session-1')?.effort, null);
+    assert.equal(providerModelsDb.getCustomProviderModel('codex', custom.recordId), null);
+  } finally {
+    closeConnection();
+    if (previousDatabasePath === undefined) {
+      delete process.env.DATABASE_PATH;
+    } else {
+      process.env.DATABASE_PATH = previousDatabasePath;
+    }
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+});
+
+test('migrations create the provider model index on an install that lacks it', async () => {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const tempDirectory = await mkdtemp(path.join(os.tmpdir(), 'provider-model-index-'));
+  const databasePath = path.join(tempDirectory, 'auth.db');
+
+  closeConnection();
+  process.env.DATABASE_PATH = databasePath;
+  await writeFile(databasePath, '');
+  await initializeDatabase();
+
+  try {
+    const db = getConnection();
+    // Upgraded installs reach runMigrations with provider_models present but no
+    // index, so the CREATE INDEX statement is compiled against the real table
+    // instead of short-circuiting on the existing index name.
+    db.exec('DROP INDEX IF EXISTS idx_provider_models_provider_order');
+
+    runMigrations(db);
+
+    const indexedColumns = (db
+      .prepare('PRAGMA index_info(idx_provider_models_provider_order)')
+      .all() as Array<{ name: string }>)
+      .map((column) => column.name);
+    assert.deepEqual(indexedColumns, ['provider', 'sort_order', 'id']);
+  } finally {
+    closeConnection();
+    if (previousDatabasePath === undefined) {
+      delete process.env.DATABASE_PATH;
+    } else {
+      process.env.DATABASE_PATH = previousDatabasePath;
+    }
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+});

package/server/modules/database/tests/sessions-provider-mapping.test.ts

@@ -45,7 +45,7 @@ test('disk-discovered sessions are keyed by the provider id for both columns', a
 
 test('app sessions get the provider id assigned without creating a duplicate row', async () => {
   await withIsolatedDatabase(() => {
-    sessionsDb.createAppSession('app-id-1', 'claude', '/workspace/demo');
+    sessionsDb.createAppSession('app-id-1', 'claude', '/workspace/demo', 'Initial CloudCLI message');
     sessionsDb.assignProviderSessionId('app-id-1', 'provider-xyz');
 
     // A later synchronizer pass that discovers the transcript on disk must
@@ -66,6 +66,7 @@ test('app sessions get the provider id assigned without creating a duplicate row
     const row = sessionsDb.getSessionById('app-id-1');
     assert.equal(row?.provider_session_id, 'provider-xyz');
     assert.equal(row?.jsonl_path, '/fake/path/provider-xyz.jsonl');
+    assert.equal(row?.custom_name, 'Initial CloudCLI message');
   });
 });
 

package/server/modules/database/tests/sessions.db.integration.test.ts

@@ -6,6 +6,7 @@ import test from 'node:test';
 
 import { closeConnection } from '@/modules/database/connection.js';
 import { initializeDatabase } from '@/modules/database/init-db.js';
+import { projectsDb } from '@/modules/database/repositories/projects.db.js';
 import { sessionsDb } from '@/modules/database/repositories/sessions.db.js';
 
 async function withIsolatedDatabase(runTest: () => void | Promise<void>): Promise<void> {
@@ -82,3 +83,34 @@ test('repository reads normalize SQLite UTC timestamps to ISO strings', async ()
     assert.match(row?.updated_at ?? '', /^\d{4}-\d{2}-\d{2}T/);
   });
 });
+
+test('recent sessions are globally ordered, paginated, and limited to visible conversations', async () => {
+  await withIsolatedDatabase(() => {
+    const fixtures: Array<Parameters<typeof sessionsDb.createSession>> = [
+      ['session-oldest', 'claude', '/workspace/project-a', 'Oldest', '2026-07-18T09:00:00.000Z', '2026-07-18T10:00:00.000Z'],
+      ['session-newest', 'codex', '/workspace/project-b', 'Newest', '2026-07-18T11:00:00.000Z', '2026-07-18T12:00:00.900Z'],
+      ['session-same-second', 'claude', '/workspace/project-a', 'Same second, slightly older', '2026-07-18T12:00:00.000Z', '2026-07-18T12:00:00.100Z'],
+      ['session-middle', 'claude', '/workspace/project-a', 'Middle', '2026-07-18T10:00:00.000Z', '2026-07-18T11:00:00.000Z'],
+      ['session-archived', 'claude', '/workspace/project-a', 'Archived session', '2026-07-18T13:00:00.000Z', '2026-07-18T13:00:00.000Z'],
+      ['session-hidden-project', 'claude', '/workspace/project-hidden', 'Archived project session', '2026-07-18T14:00:00.000Z', '2026-07-18T14:00:00.000Z'],
+    ];
+    fixtures.forEach((fixture) => sessionsDb.createSession(...fixture));
+
+    sessionsDb.updateSessionIsArchived('session-archived', true);
+    projectsDb.updateProjectIsArchived('/workspace/project-hidden', true);
+
+    const firstPage = sessionsDb.getRecentSessionsPage(2, 0);
+    const secondPage = sessionsDb.getRecentSessionsPage(2, 2);
+
+    assert.equal(firstPage.total, 4);
+    assert.deepEqual(
+      firstPage.sessions.map((session) => session.session_id),
+      ['session-newest', 'session-same-second'],
+    );
+    assert.equal(secondPage.total, 4);
+    assert.deepEqual(
+      secondPage.sessions.map((session) => session.session_id),
+      ['session-middle', 'session-oldest'],
+    );
+  });
+});

package/server/modules/file-tree/file-tree.module.ts

@@ -36,7 +36,11 @@ const fileTreeFileSystem: FileTreeFileSystem = {
   access: (candidatePath) => fsPromises.access(candidatePath),
   stat: (candidatePath) => fsPromises.stat(candidatePath),
   lstat: (candidatePath) => fsPromises.lstat(candidatePath),
-  readdir: (directoryPath) => fsPromises.readdir(directoryPath, { withFileTypes: true }),
+  // `opendir` streams entries in batches and the handle is closed by the
+  // iterator protocol, including when the caller stops early at the entry cap.
+  openDirectory: async function* (directoryPath) {
+    yield* await fsPromises.opendir(directoryPath);
+  },
   realpath: (candidatePath) => fsPromises.realpath(candidatePath),
   readTextFile: (filePath) => fsPromises.readFile(filePath, 'utf8'),
   writeTextFile: (filePath, content) => fsPromises.writeFile(filePath, content, 'utf8'),

package/server/modules/file-tree/file-tree.service.ts

@@ -3,16 +3,21 @@ import path from 'node:path';
 import ignore from 'ignore';
 
 import type {
+  FileTreeDirectoryEntry,
   FileTreeNode,
   FileTreeServiceDependencies,
   FileTreeServices,
   FileTreeUploadedFile,
 } from '@/shared/types.js';
-import { AppError } from '@/shared/utils.js';
+import { AppError, FORBIDDEN_WORKSPACE_PATHS, normalizeProjectPath } from '@/shared/utils.js';
+
+const HARD_EXCLUDED_DIRECTORY_NAMES = new Set([
+  'node_modules', '.git', '.svn', '.hg',
+]);
 
 const IGNORED_DIRECTORY_NAMES = new Set([
-  'node_modules', 'dist', 'build', '.next', '.nuxt', '.cache', '.parcel-cache',
-  '.git', '.svn', '.hg',
+  ...HARD_EXCLUDED_DIRECTORY_NAMES,
+  'dist', 'build', '.next', '.nuxt', '.cache', '.parcel-cache',
   '__pycache__', '.pytest_cache', '.mypy_cache', '.tox', 'venv', '.venv',
   'target', 'vendor',
   '.gradle', '.idea', 'coverage', '.nyc_output',
@@ -28,8 +33,22 @@ const COMMON_WORKSPACE_DIRECTORY_NAMES = [
   'workspace',
 ];
 
+// File Tree consumes this guard when recursively listing a project so a very
+// broad workspace (for example, a user's home directory) cannot exhaust the
+// server heap before the browser has a chance to switch to a narrower project.
+const MAXIMUM_FILE_TREE_ENTRIES = 10_000;
+
 type FileTreeEntryFilter = (entryPath: string, isDirectory: boolean) => boolean;
 
+function includeEntryByHardExclusions(entryPath: string, isDirectory: boolean): boolean {
+  return !isDirectory || !HARD_EXCLUDED_DIRECTORY_NAMES.has(path.basename(entryPath));
+}
+
+function includeEntryByFallbackDirectoryNames(entryPath: string, isDirectory: boolean): boolean {
+  return includeEntryByHardExclusions(entryPath, isDirectory)
+    && (!isDirectory || !IGNORED_DIRECTORY_NAMES.has(path.basename(entryPath)));
+}
+
 function createFileTreeError(message: string, statusCode: number, code: string): AppError {
   return new AppError(message, { statusCode, code });
 }
@@ -140,6 +159,8 @@ function createGitignoreEntryFilter(
   const gitignore = ignore().add(gitignoreContent);
 
   return (entryPath, isDirectory) => {
+    if (!includeEntryByHardExclusions(entryPath, isDirectory)) return false;
+
     const relativePath = path.relative(projectRoot, entryPath).split(path.sep).join('/');
     const matchPath = isDirectory ? `${relativePath}/` : relativePath;
     return !gitignore.ignores(matchPath);
@@ -167,35 +188,66 @@ export function createFileTreeService(dependencies: FileTreeServiceDependencies)
     return projectRoot;
   }
 
-  async function buildFileTree(
+  /**
+   * Streams one directory and keeps only the entries the tree will show.
+   *
+   * Entries are filtered and charged against the shared budget one at a time,
+   * so a pathologically large directory stops the walk at the cap instead of
+   * being read into memory in full first.
+   */
+  async function collectVisibleEntries(
     directoryPath: string,
-    maximumDepth: number,
-    currentDepth = 0,
-    includeEntry: FileTreeEntryFilter = () => true,
-  ): Promise<FileTreeNode[]> {
-    let entries;
+    includeEntry: FileTreeEntryFilter,
+    remainingEntries: { value: number },
+  ): Promise<FileTreeDirectoryEntry[]> {
+    const visibleEntries: FileTreeDirectoryEntry[] = [];
+
+    await acquire();
     try {
-      await acquire();
-      try {
-        entries = await fileSystem.readdir(directoryPath);
-      } finally {
-        release();
+      for await (const entry of fileSystem.openDirectory(directoryPath)) {
+        const isDirectory = entry.isDirectory();
+        if (!includeEntry(path.join(directoryPath, entry.name), isDirectory)) {
+          continue;
+        }
+
+        // Charged after visibility filtering so ignored entries never consume
+        // the budget. Every recursive branch shares one counter, so the cap
+        // applies to the whole tree rather than per directory.
+        if (remainingEntries.value <= 0) {
+          throw createFileTreeError(
+            `Project file tree exceeds the ${MAXIMUM_FILE_TREE_ENTRIES.toLocaleString()} entry limit. Choose a narrower project directory or add ignore rules.`,
+            413,
+            'FILE_TREE_TOO_LARGE',
+          );
+        }
+        remainingEntries.value -= 1;
+        visibleEntries.push(entry);
       }
     } catch (error) {
+      // The entry cap is a caller-visible outcome, not an unreadable directory.
+      if (error instanceof AppError) {
+        throw error;
+      }
       const errorCode = readErrorCode(error);
       if (errorCode !== 'EACCES' && errorCode !== 'EPERM') {
         dependencies.logger.error(`Error reading directory "${directoryPath}"`, error);
       }
       return [];
+    } finally {
+      release();
     }
 
-    const visibleEntries = entries.filter((entry) => {
-      const isDirectory = entry.isDirectory();
-      if (isDirectory && IGNORED_DIRECTORY_NAMES.has(entry.name)) {
-        return false;
-      }
-      return includeEntry(path.join(directoryPath, entry.name), isDirectory);
-    });
+    return visibleEntries;
+  }
+
+  async function buildFileTree(
+    directoryPath: string,
+    maximumDepth: number,
+    currentDepth = 0,
+    includeEntry: FileTreeEntryFilter = includeEntryByFallbackDirectoryNames,
+    remainingEntries = { value: MAXIMUM_FILE_TREE_ENTRIES },
+  ): Promise<FileTreeNode[]> {
+    const visibleEntries = await collectVisibleEntries(directoryPath, includeEntry, remainingEntries);
 
     const items = await Promise.all(visibleEntries.map(async (entry): Promise<FileTreeNode> => {
       const itemPath = path.join(directoryPath, entry.name);
@@ -233,12 +285,19 @@ export function createFileTreeService(dependencies: FileTreeServiceDependencies)
         // Metadata failures should not hide an otherwise readable tree entry.
       }
 
-      if (entry.isDirectory() && currentDepth < maximumDepth) {
+      // Skip recursing into pseudo-filesystems and other system-critical
+      // directories (e.g. /proc, /sys) — they're never valid project roots,
+      // and /proc in particular can contain thousands of virtual entries
+      // that make traversal from a broad root (e.g. "/") pathologically slow.
+      const isForbiddenSystemDir = FORBIDDEN_WORKSPACE_PATHS.includes(normalizeProjectPath(itemPath));
+
+      if (entry.isDirectory() && currentDepth < maximumDepth && !isForbiddenSystemDir) {
         item.children = await buildFileTree(
           itemPath,
           maximumDepth,
           currentDepth + 1,
           includeEntry,
+          remainingEntries,
         );
       }