diff --git a/CHANGELOG.md b/CHANGELOG.md
index 26dfba72..075cd618 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,39 @@
 All notable changes to CloudCLI UI will be documented in this file.
 
 
+## [1.32.0](https://github.com/siteboon/claudecodeui/compare/v1.31.5...v1.32.0) (2026-05-13)
+
+### Bug Fixes
+
+* add clarification on auto mode ([392c73b](https://github.com/siteboon/claudecodeui/commit/392c73b6933600ea8a589c5d4eff5f7b830f99c5))
+* enhance regex to correctly parse wrapper file paths for claude.exe ([#741](https://github.com/siteboon/claudecodeui/issues/741)) ([beb0a50](https://github.com/siteboon/claudecodeui/commit/beb0a50413beddfb16f6b49103e1b6b80567cb90))
+
+## [1.31.5](https://github.com/siteboon/claudecodeui/compare/v1.31.4...v1.31.5) (2026-04-30)
+
+### New Features
+
+* add auto mode to claude code ([3f71d49](https://github.com/siteboon/claudecodeui/commit/3f71d4932b05dfedcdf816e2a3d7d0cd69c4f566))
+
+## [1.31.4](https://github.com/siteboon/claudecodeui/compare/v1.31.3...v1.31.4) (2026-04-30)
+
+### Bug Fixes
+
+* bump codex sdk to latest version ([658421c](https://github.com/siteboon/claudecodeui/commit/658421c1c44ec4eb58b69ec7b1844a9fba11a3f3))
+
+## [1.31.3](https://github.com/siteboon/claudecodeui/compare/v1.31.2...v1.31.3) (2026-04-30)
+
+## [1.31.2](https://github.com/siteboon/claudecodeui/compare/v1.31.0...v1.31.2) (2026-04-30)
+
+### Bug Fixes
+
+* migrations for new sqlite schema ([0753c04](https://github.com/siteboon/claudecodeui/commit/0753c047837dab17b86ae4453027e30b465870f8))
+
+## [1.31.0](https://github.com/siteboon/claudecodeui/compare/v1.30.0...v1.31.0) (2026-04-30)
+
+### Bug Fixes
+
+* **/status:** use CLAUDE_MODELS.DEFAULT instead of stale 'claude-sonnet-4.5' fallback ([#723](https://github.com/siteboon/claudecodeui/issues/723)) ([b4a39c7](https://github.com/siteboon/claudecodeui/commit/b4a39c729710a6294c62eb742e99e05f3e3914e9))
+
 ## [1.30.0](https://github.com/siteboon/claudecodeui/compare/v1.29.5...v1.30.0) (2026-04-21)
 
 ### New Features
diff --git a/README.de.md b/README.de.md
index c98af089..9f8a429b 100644
--- a/README.de.md
+++ b/README.de.md
@@ -62,7 +62,7 @@
 - **Sitzungsverwaltung** – Gespräche fortsetzen, mehrere Sitzungen verwalten und Verlauf nachverfolgen
 - **Plugin-System** – CloudCLI mit eigenen Plugins erweitern – neue Tabs, Backend-Dienste und Integrationen hinzufügen. [Eigenes Plugin erstellen →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)
 - **TaskMaster AI Integration** *(Optional)* – Erweitertes Projektmanagement mit KI-gestützter Aufgabenplanung, PRD-Parsing und Workflow-Automatisierung
-- **Modell-Kompatibilität** – Funktioniert mit Claude, GPT und Gemini (vollständige Liste unterstützter Modelle in [`shared/modelConstants.js`](shared/modelConstants.js))
+- **Modell-Kompatibilität** – Funktioniert mit Claude, GPT und Gemini (vollständige Liste unterstützter Modelle in [`public/modelConstants.js`](public/modelConstants.js))
 
 
 ## Schnellstart
diff --git a/README.ko.md b/README.ko.md
index b5cf5a98..41e142bf 100644
--- a/README.ko.md
+++ b/README.ko.md
@@ -60,7 +60,7 @@
 - **세션 관리** - 대화를 재개하고, 여러 세션을 관리하며 기록을 추적
 - **플러그인 시스템** - 커스텀 탭, 백엔드 서비스, 통합을 추가하여 CloudCLI 확장. [직접 빌드 →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)
 - **TaskMaster AI 통합** *(선택사항)* - AI 중심의 작업 계획, PRD 파싱, 워크플로 자동화를 통한 고급 프로젝트 관리
-- **모델 호환성** - Claude, GPT, Gemini 모델 계열에서 작동 (`shared/modelConstants.js`에서 전체 지원 모델 확인)
+- **모델 호환성** - Claude, GPT, Gemini 모델 계열에서 작동 (`public/modelConstants.js`에서 전체 지원 모델 확인)
 
 ## 빠른 시작
 
diff --git a/README.md b/README.md
index a3db9410..bb60c9e0 100644
--- a/README.md
+++ b/README.md
@@ -62,7 +62,7 @@
 - **Session Management** - Resume conversations, manage multiple sessions, and track history
 - **Plugin System** - Extend CloudCLI with custom plugins — add new tabs, backend services, and integrations. [Build your own →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)
 - **TaskMaster AI Integration** *(Optional)* - Advanced project management with AI-powered task planning, PRD parsing, and workflow automation
-- **Model Compatibility** - Works with Claude, GPT, and Gemini model families (see [`shared/modelConstants.js`](shared/modelConstants.js) for the full list of supported models)
+- **Model Compatibility** - Works with Claude, GPT, and Gemini model families (see [`public/modelConstants.js`](public/modelConstants.js) for the full list of supported models)
 
 
 ## Quick Start
@@ -164,7 +164,7 @@ CloudCLI has a plugin system that lets you add custom tabs with their own fronte
 |---|---|
 | **[Project Stats](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** | Shows file counts, lines of code, file-type breakdown, largest files, and recently modified files for your current project |
 | **[Web Terminal](https://github.com/cloudcli-ai/cloudcli-plugin-terminal)** | Full xterm.js terminal with multi-tab support|
-
+| **[CloudCLI Scheduler](https://github.com/grostim/cloudcli-cron)** | Create workspace-scoped scheduled prompts and execute them through a local CLI such as Codex, Claude Code, or Gemini CLI|
 ### Build Your Own
 
 **[Plugin Starter Template →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** — fork this repo to create your own plugin. It includes a working example with frontend rendering, live context updates, and RPC communication to a backend server.
diff --git a/README.ru.md b/README.ru.md
index c197676a..97d8074f 100644
--- a/README.ru.md
+++ b/README.ru.md
@@ -62,7 +62,7 @@
 - **Управление сессиями** - возобновляйте диалоги, управляйте несколькими сессиями и отслеживайте историю
 - **Система плагинов** - расширяйте CloudCLI кастомными плагинами — добавляйте новые вкладки, бэкенд-сервисы и интеграции. [Создать свой →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)
 - **Интеграция с TaskMaster AI** *(опционально)* - продвинутое управление проектами с планированием задач на базе AI, разбором PRD и автоматизацией workflow
-- **Совместимость с моделями** - работает с семействами моделей Claude, GPT и Gemini (см. [`shared/modelConstants.js`](shared/modelConstants.js) для полного списка поддерживаемых моделей)
+- **Совместимость с моделями** - работает с семействами моделей Claude, GPT и Gemini (см. [`public/modelConstants.js`](public/modelConstants.js) для полного списка поддерживаемых моделей)
 
 
 ## Быстрый старт
diff --git a/README.tr.md b/README.tr.md
index a0bcdf58..c84770e5 100644
--- a/README.tr.md
+++ b/README.tr.md
@@ -62,7 +62,7 @@
 - **Oturum Yönetimi** — Konuşmalara devam et, birden fazla oturumu yönet ve geçmişi takip et
 - **Eklenti Sistemi** — CloudCLI'ı özel eklentilerle genişlet: yeni sekmeler, arka uç servisleri ve entegrasyonlar ekle. [Kendi eklentini yaz →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)
 - **TaskMaster AI Entegrasyonu** *(İsteğe Bağlı)* — AI destekli görev planlama, PRD ayrıştırma ve iş akışı otomasyonu ile gelişmiş proje yönetimi
-- **Model Uyumluluğu** — Claude, GPT ve Gemini model aileleriyle çalışır (desteklenen tüm modeller için [`shared/modelConstants.js`](shared/modelConstants.js) dosyasına bak)
+- **Model Uyumluluğu** — Claude, GPT ve Gemini model aileleriyle çalışır (desteklenen tüm modeller için [`public/modelConstants.js`](public/modelConstants.js) dosyasına bak)
 
 
 ## Hızlı Başlangıç
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 3e6ced3f..2ee656e8 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -60,7 +60,7 @@
 - **会话管理** - 恢复对话、管理多个会话并跟踪历史记录
 - **插件系统** - 通过自定义选项卡、后端服务与集成扩展 CloudCLI。 [开始构建 →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)
 - **TaskMaster AI 集成** *(可选)* - 结合 AI 任务规划、PRD 分析与工作流自动化，实现高级项目管理
-- **模型兼容性** - 支持 Claude、GPT、Gemini 模型家族（完整支持列表见 [`shared/modelConstants.js`](shared/modelConstants.js)）
+- **模型兼容性** - 支持 Claude、GPT、Gemini 模型家族（完整支持列表见 [`public/modelConstants.js`](public/modelConstants.js)）
 
 ## 快速开始
 
diff --git a/eslint.config.js b/eslint.config.js
index 742f0c2b..e002aece 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -157,7 +157,11 @@ export default tseslint.config(
         },
         {
           type: "backend-shared-utils", // shared backend runtime helpers that modules may import directly
-          pattern: ["server/shared/utils.{js,ts}"], // classify the shared utils file so modules can depend on it explicitly
+          pattern: [
+            "server/shared/utils.{js,ts}",
+            "server/shared/frontmatter.ts",
+            "server/shared/claude-cli-path.ts",
+          ], // classify shared utility files so modules can depend on them explicitly
           mode: "file",
         },
         {
@@ -165,9 +169,8 @@ export default tseslint.config(
           pattern: [
             "server/projects.js",
             "server/sessionManager.js",
-            "server/database/*.{js,ts}",
             "server/utils/runtime-paths.js",
-          ], // provider history loading still resolves session data through these legacy runtime/database files
+          ], // provider history loading still resolves session data through these legacy runtime files
           mode: "file",
         },
         {
diff --git a/package-lock.json b/package-lock.json
index 2bdf35ab..e1cf70c0 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@cloudcli-ai/cloudcli",
-  "version": "1.30.0",
+  "version": "1.32.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@cloudcli-ai/cloudcli",
-      "version": "1.30.0",
+      "version": "1.32.0",
       "hasInstallScript": true,
       "license": "AGPL-3.0-or-later",
       "dependencies": {
@@ -21,10 +21,11 @@
         "@codemirror/theme-one-dark": "^6.1.2",
         "@iarna/toml": "^2.2.5",
         "@octokit/rest": "^22.0.0",
-        "@openai/codex-sdk": "^0.101.0",
+        "@openai/codex-sdk": "^0.125.0",
         "@replit/codemirror-minimap": "^0.5.2",
         "@tailwindcss/typography": "^0.5.16",
         "@uiw/react-codemirror": "^4.23.13",
+        "@vscode/ripgrep": "^1.17.1",
         "@xterm/addon-clipboard": "^0.1.0",
         "@xterm/addon-fit": "^0.10.0",
         "@xterm/addon-web-links": "^0.11.0",
@@ -35,6 +36,7 @@
         "chokidar": "^4.0.3",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
+        "cmdk": "^1.1.1",
         "cors": "^2.8.5",
         "cross-spawn": "^7.0.3",
         "express": "^4.18.2",
@@ -80,6 +82,7 @@
         "@types/node": "^22.19.7",
         "@types/react": "^18.2.43",
         "@types/react-dom": "^18.2.17",
+        "@types/ws": "^8.18.1",
         "@vitejs/plugin-react": "^4.6.0",
         "auto-changelog": "^2.5.0",
         "autoprefixer": "^10.4.16",
@@ -3304,9 +3307,9 @@
       }
     },
     "node_modules/@openai/codex": {
-      "version": "0.101.0",
-      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.101.0.tgz",
-      "integrity": "sha512-H874q5K5I3chrT588BaddMr7GNvRYypc8C1MKWytNUF2PgxWMko2g/2DgKbt5OdajZKMsWdbsPywu34KQGf5Qw==",
+      "version": "0.125.0",
+      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.125.0.tgz",
+      "integrity": "sha512-GiE9wlgL95u/5BRirY5d3EaRLU1tu7Y1R09R8lCHHVmcQdSmhS809FdPDWH3gIYHS7ZriAPqXwJ3aLA0WKl40Q==",
       "license": "Apache-2.0",
       "bin": {
         "codex": "bin/codex.js"
@@ -3315,19 +3318,19 @@
         "node": ">=16"
       },
       "optionalDependencies": {
-        "@openai/codex-darwin-arm64": "npm:@openai/codex@0.101.0-darwin-arm64",
-        "@openai/codex-darwin-x64": "npm:@openai/codex@0.101.0-darwin-x64",
-        "@openai/codex-linux-arm64": "npm:@openai/codex@0.101.0-linux-arm64",
-        "@openai/codex-linux-x64": "npm:@openai/codex@0.101.0-linux-x64",
-        "@openai/codex-win32-arm64": "npm:@openai/codex@0.101.0-win32-arm64",
-        "@openai/codex-win32-x64": "npm:@openai/codex@0.101.0-win32-x64"
+        "@openai/codex-darwin-arm64": "npm:@openai/codex@0.125.0-darwin-arm64",
+        "@openai/codex-darwin-x64": "npm:@openai/codex@0.125.0-darwin-x64",
+        "@openai/codex-linux-arm64": "npm:@openai/codex@0.125.0-linux-arm64",
+        "@openai/codex-linux-x64": "npm:@openai/codex@0.125.0-linux-x64",
+        "@openai/codex-win32-arm64": "npm:@openai/codex@0.125.0-win32-arm64",
+        "@openai/codex-win32-x64": "npm:@openai/codex@0.125.0-win32-x64"
       }
     },
     "node_modules/@openai/codex-darwin-arm64": {
       "name": "@openai/codex",
-      "version": "0.101.0-darwin-arm64",
-      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.101.0-darwin-arm64.tgz",
-      "integrity": "sha512-unk4rTRQQ9o0w2Upu35IsJHpoZHJ+tU/myn6LNhUjcP9FrjLnEcAQJ6WIMtdTYVPja1PGhFSO0DNxV79GMvehw==",
+      "version": "0.125.0-darwin-arm64",
+      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.125.0-darwin-arm64.tgz",
+      "integrity": "sha512-Gn2fHiSO0XgyHp1OSd5DWUTm66Bv9UEuipW5pVEj1E+hWZCOrdqnYttllKFWtRGj5yiKefNX3JIxONgh/ZwlOQ==",
       "cpu": [
         "arm64"
       ],
@@ -3342,9 +3345,9 @@
     },
     "node_modules/@openai/codex-darwin-x64": {
       "name": "@openai/codex",
-      "version": "0.101.0-darwin-x64",
-      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.101.0-darwin-x64.tgz",
-      "integrity": "sha512-+KFi1IapCQGd3vLQp2lI4xI3hu2QffDZYt7Fhfw6NxEFOKhHnTamRtQ5yI8jYQcYF+pQfYF2fyiuXLM1lITLQw==",
+      "version": "0.125.0-darwin-x64",
+      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.125.0-darwin-x64.tgz",
+      "integrity": "sha512-TZ5Lek2X/UXTI9LXFxzarvQaJeuTrqVh4POc7soO/8RclVnCxADnCf15sivxLd5eiFW4t0myGoeVoM4lciRiRg==",
       "cpu": [
         "x64"
       ],
@@ -3359,9 +3362,9 @@
     },
     "node_modules/@openai/codex-linux-arm64": {
       "name": "@openai/codex",
-      "version": "0.101.0-linux-arm64",
-      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.101.0-linux-arm64.tgz",
-      "integrity": "sha512-RkDnQeq7M6ZBtD+8i+I5ewjjOf02BcJq6r1kN4RBewfAQBsz6B73Ns3OrI2bHVRsuPtAf8Cf1S4xg/eFZT2Omg==",
+      "version": "0.125.0-linux-arm64",
+      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.125.0-linux-arm64.tgz",
+      "integrity": "sha512-pPnJoJD6rZ2Iin0zNt/up36bO2/EOp2B+1/rPHu/lSq3PJbT3Fmnfut2kJy5LylXb7bGA2XQbtqOogZzIbnlkA==",
       "cpu": [
         "arm64"
       ],
@@ -3376,9 +3379,9 @@
     },
     "node_modules/@openai/codex-linux-x64": {
       "name": "@openai/codex",
-      "version": "0.101.0-linux-x64",
-      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.101.0-linux-x64.tgz",
-      "integrity": "sha512-SJeEdQ4ReEU3nvtceZ1uY3me6oWoB3djr3GnZmAUCEUuYEWD1kRGprAyJB1N0B+8zhSv0SU2e9sX5t3aCV4AwQ==",
+      "version": "0.125.0-linux-x64",
+      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.125.0-linux-x64.tgz",
+      "integrity": "sha512-K2NTTEeBpz/G+N2x17UGWfauRt3So+ir4f+U/60l5PPnYEJB/w3YZrlXo2G9og8Dm9BqtoBAjoPV74sRv9tWWQ==",
       "cpu": [
         "x64"
       ],
@@ -3392,12 +3395,12 @@
       }
     },
     "node_modules/@openai/codex-sdk": {
-      "version": "0.101.0",
-      "resolved": "https://registry.npmjs.org/@openai/codex-sdk/-/codex-sdk-0.101.0.tgz",
-      "integrity": "sha512-Lrar2pDvGUX64itSbMNKuNBzxh72UwKokY4TPuXJRURwGX0qyDi80n7DiVivC40BwFsQWNs6behSo/9Mr6PoLw==",
+      "version": "0.125.0",
+      "resolved": "https://registry.npmjs.org/@openai/codex-sdk/-/codex-sdk-0.125.0.tgz",
+      "integrity": "sha512-1xCIHdSbQVF880nJ2aVWdPIsWZbSpKODwuP9y/gvtChDYhYfYEW0DKp2H8ZlctkzIjlzS/WzYmP6ZZPHIvs2Dg==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@openai/codex": "0.101.0"
+        "@openai/codex": "0.125.0"
       },
       "engines": {
         "node": ">=18"
@@ -3405,9 +3408,9 @@
     },
     "node_modules/@openai/codex-win32-arm64": {
       "name": "@openai/codex",
-      "version": "0.101.0-win32-arm64",
-      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.101.0-win32-arm64.tgz",
-      "integrity": "sha512-WQ8QsychjHyvlr+vCSTMbd2/yrBIZre5tRuM79eZi973BJz0CSEiFsNSGg5fvpnJuiHHawZ/8HWeir7nlatamQ==",
+      "version": "0.125.0-win32-arm64",
+      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.125.0-win32-arm64.tgz",
+      "integrity": "sha512-zxoUakw9oIHIFrAyk400XkkLBJFA6nOym0NDq6sQ/jhdcYraKqNSRCII2nsBwZHk+/4zgUvuk52iuutgysY/rQ==",
       "cpu": [
         "arm64"
       ],
@@ -3422,9 +3425,9 @@
     },
     "node_modules/@openai/codex-win32-x64": {
       "name": "@openai/codex",
-      "version": "0.101.0-win32-x64",
-      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.101.0-win32-x64.tgz",
-      "integrity": "sha512-H+7h9x0fYrJRUZZHCA62Dzb/CS5Scl1sUw1aamfmHJzzorX+uTFOgGsibzqFpHTd6nRM4q8//fCdSxe5wUpOQQ==",
+      "version": "0.125.0-win32-x64",
+      "resolved": "https://registry.npmjs.org/@openai/codex/-/codex-0.125.0-win32-x64.tgz",
+      "integrity": "sha512-ofpOK+OWH5QFuUZ9pTM0d/PcXUXiIP5z5DpRcE9MlucJoyOl4Zy4Nu3NcuHF4YzCkZMQb6x3j0tjDEPHKqNQzw==",
       "cpu": [
         "x64"
       ],
@@ -3461,6 +3464,447 @@
         "node": ">=14"
       }
     },
+    "node_modules/@radix-ui/primitive": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.1.3.tgz",
+      "integrity": "sha512-JTF99U/6XIjCBo0wqkU5sK10glYe27MRRsfwoiq5zzOEZLHU3A3KCMa5X/azekYRCJ0HlwI0crAXS/5dEHTzDg==",
+      "license": "MIT"
+    },
+    "node_modules/@radix-ui/react-compose-refs": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.2.tgz",
+      "integrity": "sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==",
+      "license": "MIT",
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-context": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-context/-/react-context-1.1.2.tgz",
+      "integrity": "sha512-jCi/QKUM2r1Ju5a3J64TH2A5SpKAgh0LpknyqdQ4m6DCV0xJ2HG1xARRwNGPQfi1SLdLWZ1OJz6F4OMBBNiGJA==",
+      "license": "MIT",
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-dialog": {
+      "version": "1.1.15",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-dialog/-/react-dialog-1.1.15.tgz",
+      "integrity": "sha512-TCglVRtzlffRNxRMEyR36DGBLJpeusFcgMVD9PZEzAKnUs1lKCgX5u9BmC2Yg+LL9MgZDugFFs1Vl+Jp4t/PGw==",
+      "license": "MIT",
+      "dependencies": {
+        "@radix-ui/primitive": "1.1.3",
+        "@radix-ui/react-compose-refs": "1.1.2",
+        "@radix-ui/react-context": "1.1.2",
+        "@radix-ui/react-dismissable-layer": "1.1.11",
+        "@radix-ui/react-focus-guards": "1.1.3",
+        "@radix-ui/react-focus-scope": "1.1.7",
+        "@radix-ui/react-id": "1.1.1",
+        "@radix-ui/react-portal": "1.1.9",
+        "@radix-ui/react-presence": "1.1.5",
+        "@radix-ui/react-primitive": "2.1.3",
+        "@radix-ui/react-slot": "1.2.3",
+        "@radix-ui/react-use-controllable-state": "1.2.2",
+        "aria-hidden": "^1.2.4",
+        "react-remove-scroll": "^2.6.3"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "@types/react-dom": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "@types/react-dom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-dialog/node_modules/@radix-ui/react-primitive": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz",
+      "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@radix-ui/react-slot": "1.2.3"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "@types/react-dom": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "@types/react-dom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-dismissable-layer": {
+      "version": "1.1.11",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-dismissable-layer/-/react-dismissable-layer-1.1.11.tgz",
+      "integrity": "sha512-Nqcp+t5cTB8BinFkZgXiMJniQH0PsUt2k51FUhbdfeKvc4ACcG2uQniY/8+h1Yv6Kza4Q7lD7PQV0z0oicE0Mg==",
+      "license": "MIT",
+      "dependencies": {
+        "@radix-ui/primitive": "1.1.3",
+        "@radix-ui/react-compose-refs": "1.1.2",
+        "@radix-ui/react-primitive": "2.1.3",
+        "@radix-ui/react-use-callback-ref": "1.1.1",
+        "@radix-ui/react-use-escape-keydown": "1.1.1"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "@types/react-dom": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "@types/react-dom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-dismissable-layer/node_modules/@radix-ui/react-primitive": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz",
+      "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@radix-ui/react-slot": "1.2.3"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "@types/react-dom": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "@types/react-dom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-focus-guards": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-guards/-/react-focus-guards-1.1.3.tgz",
+      "integrity": "sha512-0rFg/Rj2Q62NCm62jZw0QX7a3sz6QCQU0LpZdNrJX8byRGaGVTqbrW9jAoIAHyMQqsNpeZ81YgSizOt5WXq0Pw==",
+      "license": "MIT",
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-focus-scope": {
+      "version": "1.1.7",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-focus-scope/-/react-focus-scope-1.1.7.tgz",
+      "integrity": "sha512-t2ODlkXBQyn7jkl6TNaw/MtVEVvIGelJDCG41Okq/KwUsJBwQ4XVZsHAVUkK4mBv3ewiAS3PGuUWuY2BoK4ZUw==",
+      "license": "MIT",
+      "dependencies": {
+        "@radix-ui/react-compose-refs": "1.1.2",
+        "@radix-ui/react-primitive": "2.1.3",
+        "@radix-ui/react-use-callback-ref": "1.1.1"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "@types/react-dom": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "@types/react-dom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-focus-scope/node_modules/@radix-ui/react-primitive": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz",
+      "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@radix-ui/react-slot": "1.2.3"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "@types/react-dom": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "@types/react-dom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-id": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-id/-/react-id-1.1.1.tgz",
+      "integrity": "sha512-kGkGegYIdQsOb4XjsfM97rXsiHaBwco+hFI66oO4s9LU+PLAC5oJ7khdOVFxkhsmlbpUqDAvXw11CluXP+jkHg==",
+      "license": "MIT",
+      "dependencies": {
+        "@radix-ui/react-use-layout-effect": "1.1.1"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-portal": {
+      "version": "1.1.9",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-portal/-/react-portal-1.1.9.tgz",
+      "integrity": "sha512-bpIxvq03if6UNwXZ+HTK71JLh4APvnXntDc6XOX8UVq4XQOVl7lwok0AvIl+b8zgCw3fSaVTZMpAPPagXbKmHQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@radix-ui/react-primitive": "2.1.3",
+        "@radix-ui/react-use-layout-effect": "1.1.1"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "@types/react-dom": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "@types/react-dom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-portal/node_modules/@radix-ui/react-primitive": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.3.tgz",
+      "integrity": "sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@radix-ui/react-slot": "1.2.3"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "@types/react-dom": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "@types/react-dom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-presence": {
+      "version": "1.1.5",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-presence/-/react-presence-1.1.5.tgz",
+      "integrity": "sha512-/jfEwNDdQVBCNvjkGit4h6pMOzq8bHkopq458dPt2lMjx+eBQUohZNG9A7DtO/O5ukSbxuaNGXMjHicgwy6rQQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@radix-ui/react-compose-refs": "1.1.2",
+        "@radix-ui/react-use-layout-effect": "1.1.1"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "@types/react-dom": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "@types/react-dom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-primitive": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-primitive/-/react-primitive-2.1.4.tgz",
+      "integrity": "sha512-9hQc4+GNVtJAIEPEqlYqW5RiYdrr8ea5XQ0ZOnD6fgru+83kqT15mq2OCcbe8KnjRZl5vF3ks69AKz3kh1jrhg==",
+      "license": "MIT",
+      "dependencies": {
+        "@radix-ui/react-slot": "1.2.4"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "@types/react-dom": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
+        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "@types/react-dom": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-primitive/node_modules/@radix-ui/react-slot": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.4.tgz",
+      "integrity": "sha512-Jl+bCv8HxKnlTLVrcDE8zTMJ09R9/ukw4qBs/oZClOfoQk/cOTbDn+NceXfV7j09YPVQUryJPHurafcSg6EVKA==",
+      "license": "MIT",
+      "dependencies": {
+        "@radix-ui/react-compose-refs": "1.1.2"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-slot": {
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz",
+      "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==",
+      "license": "MIT",
+      "dependencies": {
+        "@radix-ui/react-compose-refs": "1.1.2"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-use-callback-ref": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-callback-ref/-/react-use-callback-ref-1.1.1.tgz",
+      "integrity": "sha512-FkBMwD+qbGQeMu1cOHnuGB6x4yzPjho8ap5WtbEJ26umhgqVXbhekKUQO+hZEL1vU92a3wHwdp0HAcqAUF5iDg==",
+      "license": "MIT",
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-use-controllable-state": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-controllable-state/-/react-use-controllable-state-1.2.2.tgz",
+      "integrity": "sha512-BjasUjixPFdS+NKkypcyyN5Pmg83Olst0+c6vGov0diwTEo6mgdqVR6hxcEgFuh4QrAs7Rc+9KuGJ9TVCj0Zzg==",
+      "license": "MIT",
+      "dependencies": {
+        "@radix-ui/react-use-effect-event": "0.0.2",
+        "@radix-ui/react-use-layout-effect": "1.1.1"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-use-effect-event": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-effect-event/-/react-use-effect-event-0.0.2.tgz",
+      "integrity": "sha512-Qp8WbZOBe+blgpuUT+lw2xheLP8q0oatc9UpmiemEICxGvFLYmHm9QowVZGHtJlGbS6A6yJ3iViad/2cVjnOiA==",
+      "license": "MIT",
+      "dependencies": {
+        "@radix-ui/react-use-layout-effect": "1.1.1"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-use-escape-keydown": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-escape-keydown/-/react-use-escape-keydown-1.1.1.tgz",
+      "integrity": "sha512-Il0+boE7w/XebUHyBjroE+DbByORGR9KKmITzbR7MyQ4akpORYP/ZmbhAr0DG7RmmBqoOnZdy2QlvajJ2QA59g==",
+      "license": "MIT",
+      "dependencies": {
+        "@radix-ui/react-use-callback-ref": "1.1.1"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@radix-ui/react-use-layout-effect": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@radix-ui/react-use-layout-effect/-/react-use-layout-effect-1.1.1.tgz",
+      "integrity": "sha512-RbJRS4UWQFkzHTTwVymMTUv8EqYhOp8dOOviLj2ugtTiXRaRQS7GLGxZTLL1jWhMeoSCf5zmcZkqTl9IiYfXcQ==",
+      "license": "MIT",
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/@release-it/conventional-changelog": {
       "version": "10.0.5",
       "resolved": "https://registry.npmjs.org/@release-it/conventional-changelog/-/conventional-changelog-10.0.5.tgz",
@@ -4109,7 +4553,7 @@
       "version": "18.3.7",
       "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-18.3.7.tgz",
       "integrity": "sha512-MEe3UeoENYVFXzoXEWsvcpg6ZvlrFNlOQ7EOsvhI3CfAXwzPfO8Qwuxd40nepsYKqyyVQnTdEfv68q91yLcKrQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "peerDependencies": {
         "@types/react": "^18.0.0"
@@ -4142,6 +4586,16 @@
       "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==",
       "license": "MIT"
     },
+    "node_modules/@types/ws": {
+      "version": "8.18.1",
+      "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
+      "integrity": "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
     "node_modules/@typescript-eslint/eslint-plugin": {
       "version": "8.56.1",
       "resolved": "https://registry.npmjs.org/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.56.1.tgz",
@@ -4786,6 +5240,18 @@
         "vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
       }
     },
+    "node_modules/@vscode/ripgrep": {
+      "version": "1.17.1",
+      "resolved": "https://registry.npmjs.org/@vscode/ripgrep/-/ripgrep-1.17.1.tgz",
+      "integrity": "sha512-xTs7DGyAO3IsJYOCTBP8LnTvPiYVKEuyv8s0xyJDBXfs8rhBfqnZPvb6xDT+RnwWzcXqW27xLS/aGrkjX7lNWw==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "dependencies": {
+        "https-proxy-agent": "^7.0.2",
+        "proxy-from-env": "^1.1.0",
+        "yauzl": "^2.9.2"
+      }
+    },
     "node_modules/@xterm/addon-clipboard": {
       "version": "0.1.0",
       "resolved": "https://registry.npmjs.org/@xterm/addon-clipboard/-/addon-clipboard-0.1.0.tgz",
@@ -5060,6 +5526,18 @@
         "sprintf-js": "~1.0.2"
       }
     },
+    "node_modules/aria-hidden": {
+      "version": "1.2.6",
+      "resolved": "https://registry.npmjs.org/aria-hidden/-/aria-hidden-1.2.6.tgz",
+      "integrity": "sha512-ik3ZgC9dY/lYVVM++OISsaYDeg1tb0VtP5uL3ouh1koGOaUMDPpbFIei4JkFimWUFPn90sbMNMXQAIVOlnYKJA==",
+      "license": "MIT",
+      "dependencies": {
+        "tslib": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/array-buffer-byte-length": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/array-buffer-byte-length/-/array-buffer-byte-length-1.0.2.tgz",
@@ -5618,6 +6096,15 @@
         "ieee754": "^1.1.13"
       }
     },
+    "node_modules/buffer-crc32": {
+      "version": "0.2.13",
+      "resolved": "https://registry.npmjs.org/buffer-crc32/-/buffer-crc32-0.2.13.tgz",
+      "integrity": "sha512-VO9Ht/+p3SN7SKWqcrgEzjGbRSJYTx+Q1pTQC0wrWqHx0vpJraQ6GtHx8tvcg1rlK1byhU5gccxgOgj7B0TDkQ==",
+      "license": "MIT",
+      "engines": {
+        "node": "*"
+      }
+    },
     "node_modules/buffer-equal-constant-time": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/buffer-equal-constant-time/-/buffer-equal-constant-time-1.0.1.tgz",
@@ -6153,6 +6640,22 @@
         "node": ">=6"
       }
     },
+    "node_modules/cmdk": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/cmdk/-/cmdk-1.1.1.tgz",
+      "integrity": "sha512-Vsv7kFaXm+ptHDMZ7izaRsP70GgrW9NBNGswt9OZaVBLlE0SNpDq8eu/VGXyF9r7M0azK3Wy7OlYXsuyYLFzHg==",
+      "license": "MIT",
+      "dependencies": {
+        "@radix-ui/react-compose-refs": "^1.1.1",
+        "@radix-ui/react-dialog": "^1.1.6",
+        "@radix-ui/react-id": "^1.1.0",
+        "@radix-ui/react-primitive": "^2.0.2"
+      },
+      "peerDependencies": {
+        "react": "^18 || ^19 || ^19.0.0-rc",
+        "react-dom": "^18 || ^19 || ^19.0.0-rc"
+      }
+    },
     "node_modules/codemirror": {
       "version": "6.0.2",
       "resolved": "https://registry.npmjs.org/codemirror/-/codemirror-6.0.2.tgz",
@@ -6925,6 +7428,12 @@
         "node": ">=8"
       }
     },
+    "node_modules/detect-node-es": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/detect-node-es/-/detect-node-es-1.1.0.tgz",
+      "integrity": "sha512-ypdmJU/TbBby2Dxibuv7ZLW3Bs1QEmM7nHjEANfohJLvE0XVujisn1qPJcZxg+qDucsr+bP6fLD1rPS3AhJ7EQ==",
+      "license": "MIT"
+    },
     "node_modules/devlop": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/devlop/-/devlop-1.1.0.tgz",
@@ -8277,6 +8786,15 @@
         "walk-up-path": "^4.0.0"
       }
     },
+    "node_modules/fd-slicer": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/fd-slicer/-/fd-slicer-1.1.0.tgz",
+      "integrity": "sha512-cE1qsB/VwyQozZ+q1dGxR8LBYNZeofhEdUNGSMbQD3Gw2lAzX9Zb3uIU6Ebc/Fmyjo9AWWfnn0AUCHqtevs/8g==",
+      "license": "MIT",
+      "dependencies": {
+        "pend": "~1.2.0"
+      }
+    },
     "node_modules/file-entry-cache": {
       "version": "8.0.0",
       "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-8.0.0.tgz",
@@ -8632,6 +9150,15 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/get-nonce": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/get-nonce/-/get-nonce-1.0.1.tgz",
+      "integrity": "sha512-FJhYRoDaiatfEkUK8HKlicmu/3SGFD51q3itKDGoSTysQJBnfOcxU5GxnhE1E6soB76MbT0MBtnKJuXyAx+96Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/get-proto": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz",
@@ -13381,6 +13908,12 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/pend": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/pend/-/pend-1.2.0.tgz",
+      "integrity": "sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg==",
+      "license": "MIT"
+    },
     "node_modules/perfect-debounce": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/perfect-debounce/-/perfect-debounce-2.0.0.tgz",
@@ -13774,7 +14307,6 @@
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-1.1.0.tgz",
       "integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/pump": {
@@ -14016,6 +14548,53 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/react-remove-scroll": {
+      "version": "2.7.2",
+      "resolved": "https://registry.npmjs.org/react-remove-scroll/-/react-remove-scroll-2.7.2.tgz",
+      "integrity": "sha512-Iqb9NjCCTt6Hf+vOdNIZGdTiH1QSqr27H/Ek9sv/a97gfueI/5h1s3yRi1nngzMUaOOToin5dI1dXKdXiF+u0Q==",
+      "license": "MIT",
+      "dependencies": {
+        "react-remove-scroll-bar": "^2.3.7",
+        "react-style-singleton": "^2.2.3",
+        "tslib": "^2.1.0",
+        "use-callback-ref": "^1.3.3",
+        "use-sidecar": "^1.1.3"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/react-remove-scroll-bar": {
+      "version": "2.3.8",
+      "resolved": "https://registry.npmjs.org/react-remove-scroll-bar/-/react-remove-scroll-bar-2.3.8.tgz",
+      "integrity": "sha512-9r+yi9+mgU33AKcj6IbT9oRCO78WriSj6t/cF8DWBZJ9aOGPOTEDvdUDz1FwKim7QXWwmHqtdHnRJfhAxEG46Q==",
+      "license": "MIT",
+      "dependencies": {
+        "react-style-singleton": "^2.2.2",
+        "tslib": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/react-router": {
       "version": "6.30.1",
       "resolved": "https://registry.npmjs.org/react-router/-/react-router-6.30.1.tgz",
@@ -14048,6 +14627,28 @@
         "react-dom": ">=16.8"
       }
     },
+    "node_modules/react-style-singleton": {
+      "version": "2.2.3",
+      "resolved": "https://registry.npmjs.org/react-style-singleton/-/react-style-singleton-2.2.3.tgz",
+      "integrity": "sha512-b6jSvxvVnyptAiLjbkWLE/lOnR4lfTtDAl+eUC7RZy+QQWc6wRzIV2CE6xBuMmDxc2qIihtDCZD5NPOFl7fRBQ==",
+      "license": "MIT",
+      "dependencies": {
+        "get-nonce": "^1.0.0",
+        "tslib": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/react-syntax-highlighter": {
       "version": "15.6.6",
       "resolved": "https://registry.npmjs.org/react-syntax-highlighter/-/react-syntax-highlighter-15.6.6.tgz",
@@ -17545,6 +18146,49 @@
         "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
       }
     },
+    "node_modules/use-callback-ref": {
+      "version": "1.3.3",
+      "resolved": "https://registry.npmjs.org/use-callback-ref/-/use-callback-ref-1.3.3.tgz",
+      "integrity": "sha512-jQL3lRnocaFtu3V00JToYz/4QkNWswxijDaCVNZRiRTO3HQDLsdu1ZtmIUvV4yPp+rvWm5j0y0TG/S61cuijTg==",
+      "license": "MIT",
+      "dependencies": {
+        "tslib": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/use-sidecar": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/use-sidecar/-/use-sidecar-1.1.3.tgz",
+      "integrity": "sha512-Fedw0aZvkhynoPYlA5WXrMCAMm+nSWdZt6lzJQ7Ok8S6Q+VsHmHpRWndVRJ8Be0ZbkfPc5LRYH+5XrzXcEeLRQ==",
+      "license": "MIT",
+      "dependencies": {
+        "detect-node-es": "^1.1.0",
+        "tslib": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "peerDependencies": {
+        "@types/react": "*",
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/use-sync-external-store": {
       "version": "1.6.0",
       "resolved": "https://registry.npmmirror.com/use-sync-external-store/-/use-sync-external-store-1.6.0.tgz",
@@ -18225,6 +18869,16 @@
         "node": ">=8"
       }
     },
+    "node_modules/yauzl": {
+      "version": "2.10.0",
+      "resolved": "https://registry.npmjs.org/yauzl/-/yauzl-2.10.0.tgz",
+      "integrity": "sha512-p4a9I6X6nu6IhoGmBqAcbJy1mlC4j27vEPZX9F4L4/vZT3Lyq1VkFHw/V/PUcB9Buo+DG3iHkT0x3Qya58zc3g==",
+      "license": "MIT",
+      "dependencies": {
+        "buffer-crc32": "~0.2.3",
+        "fd-slicer": "~1.1.0"
+      }
+    },
     "node_modules/yocto-queue": {
       "version": "0.1.0",
       "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz",
diff --git a/package.json b/package.json
index 3388f7a4..626d0e3b 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@cloudcli-ai/cloudcli",
-  "version": "1.30.0",
+  "version": "1.32.0",
   "description": "A web-based UI for Claude Code CLI",
   "type": "module",
   "main": "dist-server/server/index.js",
@@ -10,6 +10,8 @@
   "files": [
     "server/",
     "shared/",
+    "public/api-docs.html",
+    "public/modelConstants.js",
     "dist/",
     "dist-server/",
     "scripts/",
@@ -76,10 +78,11 @@
     "@codemirror/theme-one-dark": "^6.1.2",
     "@iarna/toml": "^2.2.5",
     "@octokit/rest": "^22.0.0",
-    "@openai/codex-sdk": "^0.101.0",
+    "@openai/codex-sdk": "^0.125.0",
     "@replit/codemirror-minimap": "^0.5.2",
     "@tailwindcss/typography": "^0.5.16",
     "@uiw/react-codemirror": "^4.23.13",
+    "@vscode/ripgrep": "^1.17.1",
     "@xterm/addon-clipboard": "^0.1.0",
     "@xterm/addon-fit": "^0.10.0",
     "@xterm/addon-web-links": "^0.11.0",
@@ -90,6 +93,7 @@
     "chokidar": "^4.0.3",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
     "cors": "^2.8.5",
     "cross-spawn": "^7.0.3",
     "express": "^4.18.2",
@@ -132,6 +136,7 @@
     "@types/node": "^22.19.7",
     "@types/react": "^18.2.43",
     "@types/react-dom": "^18.2.17",
+    "@types/ws": "^8.18.1",
     "@vitejs/plugin-react": "^4.6.0",
     "auto-changelog": "^2.5.0",
     "autoprefixer": "^10.4.16",
diff --git a/public/api-docs.html b/public/api-docs.html
index 1d86cf4c..0103b5ca 100644
--- a/public/api-docs.html
+++ b/public/api-docs.html
@@ -822,7 +822,7 @@ data: {"type":"done"}</code></pre>
 
     <script type="module">
         // Import model constants
-        import { CLAUDE_MODELS, CURSOR_MODELS, CODEX_MODELS } from '/shared/modelConstants.js';
+        import { PROVIDERS } from './modelConstants.js';
 
         // Dynamic URL replacement
         const apiUrl = window.location.origin;
@@ -834,15 +834,14 @@ data: {"type":"done"}</code></pre>
         window.addEventListener('DOMContentLoaded', () => {
             const modelCell = document.getElementById('model-options-cell');
             if (modelCell) {
-                const claudeModels = CLAUDE_MODELS.OPTIONS.map(m => `<code>${m.value}</code>`).join(', ');
-                const cursorModels = CURSOR_MODELS.OPTIONS.slice(0, 8).map(m => `<code>${m.value}</code>`).join(', ');
-                const codexModels = CODEX_MODELS.OPTIONS.map(m => `<code>${m.value}</code>`).join(', ');
+                const providerModels = PROVIDERS.map(provider => {
+                    const models = provider.models.OPTIONS.map(m => `<code>${m.value}</code>`).join(', ');
+                    return `<strong>${provider.name}:</strong> ${models} (default: <code>${provider.models.DEFAULT}</code>)`;
+                }).join('<br><br>');
 
                 modelCell.innerHTML = `
                     Model identifier for the AI provider:<br><br>
-                    <strong>Claude:</strong> ${claudeModels} (default: <code>${CLAUDE_MODELS.DEFAULT}</code>)<br><br>
-                    <strong>Cursor:</strong> ${cursorModels}, and more (default: <code>${CURSOR_MODELS.DEFAULT}</code>)<br><br>
-                    <strong>Codex:</strong> ${codexModels} (default: <code>${CODEX_MODELS.DEFAULT}</code>)
+                    ${providerModels}
                 `;
             }
         });
diff --git a/public/modelConstants.js b/public/modelConstants.js
new file mode 100644
index 00000000..35e653aa
--- /dev/null
+++ b/public/modelConstants.js
@@ -0,0 +1,841 @@
+/**
+ * Documentation Model Definitions
+ * Used by README links and the public API docs.
+ */
+
+/**
+ * Claude (Anthropic) Models
+ */
+export const CLAUDE_MODELS = {
+  OPTIONS: [
+    {
+      value: "default",
+      label: "Default (recommended)",
+      description: "Use the default model (currently Opus 4.7 (1M context)) · $5/$25 per Mtok",
+    },
+    {
+      value: "sonnet",
+      label: "Sonnet",
+      description: "Sonnet 4.6 · Best for everyday tasks · $3/$15 per Mtok",
+    },
+    {
+      value: "sonnet[1m]",
+      label: "Sonnet (1M context)",
+      description: "Sonnet 4.6 for long sessions · $3/$15 per Mtok",
+    },
+    {
+      value: "haiku",
+      label: "Haiku",
+      description: "Haiku 4.5 · Fastest for quick answers · $1/$5 per Mtok",
+    },
+  ],
+
+  DEFAULT: "default",
+};
+
+/**
+ * Cursor Models
+ */
+export const CURSOR_MODELS = {
+  OPTIONS: [
+    { value: "auto", label: "auto", description: "Auto" },
+    {
+      value: "composer-2-fast",
+      label: "composer-2-fast",
+      description: "Composer 2 Fast",
+    },
+    {
+      value: "composer-2",
+      label: "composer-2",
+      description: "Composer 2",
+    },
+    {
+      value: "gpt-5.3-codex-low",
+      label: "gpt-5.3-codex-low",
+      description: "Codex 5.3 Low",
+    },
+    {
+      value: "gpt-5.3-codex-low-fast",
+      label: "gpt-5.3-codex-low-fast",
+      description: "Codex 5.3 Low Fast",
+    },
+    {
+      value: "gpt-5.3-codex",
+      label: "gpt-5.3-codex",
+      description: "Codex 5.3",
+    },
+    {
+      value: "gpt-5.3-codex-fast",
+      label: "gpt-5.3-codex-fast",
+      description: "Codex 5.3 Fast",
+    },
+    {
+      value: "gpt-5.3-codex-high",
+      label: "gpt-5.3-codex-high",
+      description: "Codex 5.3 High",
+    },
+    {
+      value: "gpt-5.3-codex-high-fast",
+      label: "gpt-5.3-codex-high-fast",
+      description: "Codex 5.3 High Fast",
+    },
+    {
+      value: "gpt-5.3-codex-xhigh",
+      label: "gpt-5.3-codex-xhigh",
+      description: "Codex 5.3 Extra High",
+    },
+    {
+      value: "gpt-5.3-codex-xhigh-fast",
+      label: "gpt-5.3-codex-xhigh-fast",
+      description: "Codex 5.3 Extra High Fast",
+    },
+    { value: "gpt-5.2", label: "gpt-5.2", description: "GPT-5.2" },
+    {
+      value: "gpt-5.2-codex-low",
+      label: "gpt-5.2-codex-low",
+      description: "Codex 5.2 Low",
+    },
+    {
+      value: "gpt-5.2-codex-low-fast",
+      label: "gpt-5.2-codex-low-fast",
+      description: "Codex 5.2 Low Fast",
+    },
+    {
+      value: "gpt-5.2-codex",
+      label: "gpt-5.2-codex",
+      description: "Codex 5.2",
+    },
+    {
+      value: "gpt-5.2-codex-fast",
+      label: "gpt-5.2-codex-fast",
+      description: "Codex 5.2 Fast",
+    },
+    {
+      value: "gpt-5.2-codex-high",
+      label: "gpt-5.2-codex-high",
+      description: "Codex 5.2 High",
+    },
+    {
+      value: "gpt-5.2-codex-high-fast",
+      label: "gpt-5.2-codex-high-fast",
+      description: "Codex 5.2 High Fast",
+    },
+    {
+      value: "gpt-5.2-codex-xhigh",
+      label: "gpt-5.2-codex-xhigh",
+      description: "Codex 5.2 Extra High",
+    },
+    {
+      value: "gpt-5.2-codex-xhigh-fast",
+      label: "gpt-5.2-codex-xhigh-fast",
+      description: "Codex 5.2 Extra High Fast",
+    },
+    {
+      value: "gpt-5.1-codex-max-low",
+      label: "gpt-5.1-codex-max-low",
+      description: "Codex 5.1 Max Low",
+    },
+    {
+      value: "gpt-5.1-codex-max-low-fast",
+      label: "gpt-5.1-codex-max-low-fast",
+      description: "Codex 5.1 Max Low Fast",
+    },
+    {
+      value: "gpt-5.1-codex-max-medium",
+      label: "gpt-5.1-codex-max-medium",
+      description: "Codex 5.1 Max",
+    },
+    {
+      value: "gpt-5.1-codex-max-medium-fast",
+      label: "gpt-5.1-codex-max-medium-fast",
+      description: "Codex 5.1 Max Medium Fast",
+    },
+    {
+      value: "gpt-5.1-codex-max-high",
+      label: "gpt-5.1-codex-max-high",
+      description: "Codex 5.1 Max High",
+    },
+    {
+      value: "gpt-5.1-codex-max-high-fast",
+      label: "gpt-5.1-codex-max-high-fast",
+      description: "Codex 5.1 Max High Fast",
+    },
+    {
+      value: "gpt-5.1-codex-max-xhigh",
+      label: "gpt-5.1-codex-max-xhigh",
+      description: "Codex 5.1 Max Extra High",
+    },
+    {
+      value: "gpt-5.1-codex-max-xhigh-fast",
+      label: "gpt-5.1-codex-max-xhigh-fast",
+      description: "Codex 5.1 Max Extra High Fast",
+    },
+    {
+      value: "composer-2.5",
+      label: "composer-2.5",
+      description: "Composer 2.5",
+    },
+    {
+      value: "gpt-5.5-high",
+      label: "gpt-5.5-high",
+      description: "GPT-5.5 1M High",
+    },
+    {
+      value: "gpt-5.5-high-fast",
+      label: "gpt-5.5-high-fast",
+      description: "GPT-5.5 High Fast",
+    },
+    {
+      value: "claude-opus-4-7-thinking-high",
+      label: "claude-opus-4-7-thinking-high",
+      description: "Opus 4.7 1M High Thinking",
+    },
+    {
+      value: "gpt-5.4-high",
+      label: "gpt-5.4-high",
+      description: "GPT-5.4 1M High",
+    },
+    {
+      value: "gpt-5.4-high-fast",
+      label: "gpt-5.4-high-fast",
+      description: "GPT-5.4 High Fast",
+    },
+    {
+      value: "claude-4.6-opus-high-thinking",
+      label: "claude-4.6-opus-high-thinking",
+      description: "Opus 4.6 1M Thinking",
+    },
+    {
+      value: "claude-4.6-opus-high-thinking-fast",
+      label: "claude-4.6-opus-high-thinking-fast",
+      description: "Opus 4.6 1M Thinking Fast",
+    },
+    {
+      value: "composer-2.5-fast",
+      label: "composer-2.5-fast",
+      description: "Composer 2.5 Fast",
+    },
+    {
+      value: "gpt-5.5-none",
+      label: "gpt-5.5-none",
+      description: "GPT-5.5 1M None",
+    },
+    {
+      value: "gpt-5.5-none-fast",
+      label: "gpt-5.5-none-fast",
+      description: "GPT-5.5 None Fast",
+    },
+    {
+      value: "gpt-5.5-low",
+      label: "gpt-5.5-low",
+      description: "GPT-5.5 1M Low",
+    },
+    {
+      value: "gpt-5.5-low-fast",
+      label: "gpt-5.5-low-fast",
+      description: "GPT-5.5 Low Fast",
+    },
+    {
+      value: "gpt-5.5-medium",
+      label: "gpt-5.5-medium",
+      description: "GPT-5.5 1M",
+    },
+    {
+      value: "gpt-5.5-medium-fast",
+      label: "gpt-5.5-medium-fast",
+      description: "GPT-5.5 Fast",
+    },
+    {
+      value: "gpt-5.5-extra-high",
+      label: "gpt-5.5-extra-high",
+      description: "GPT-5.5 1M Extra High",
+    },
+    {
+      value: "gpt-5.5-extra-high-fast",
+      label: "gpt-5.5-extra-high-fast",
+      description: "GPT-5.5 Extra High Fast",
+    },
+    {
+      value: "claude-4.6-sonnet-medium",
+      label: "claude-4.6-sonnet-medium",
+      description: "Sonnet 4.6 1M",
+    },
+    {
+      value: "claude-4.6-sonnet-medium-thinking",
+      label: "claude-4.6-sonnet-medium-thinking",
+      description: "Sonnet 4.6 1M Thinking",
+    },
+    {
+      value: "claude-opus-4-7-low",
+      label: "claude-opus-4-7-low",
+      description: "Opus 4.7 1M Low",
+    },
+    {
+      value: "claude-opus-4-7-low-fast",
+      label: "claude-opus-4-7-low-fast",
+      description: "Opus 4.7 1M Low Fast",
+    },
+    {
+      value: "claude-opus-4-7-medium",
+      label: "claude-opus-4-7-medium",
+      description: "Opus 4.7 1M Medium",
+    },
+    {
+      value: "claude-opus-4-7-medium-fast",
+      label: "claude-opus-4-7-medium-fast",
+      description: "Opus 4.7 1M Medium Fast",
+    },
+    {
+      value: "claude-opus-4-7-high",
+      label: "claude-opus-4-7-high",
+      description: "Opus 4.7 1M High",
+    },
+    {
+      value: "claude-opus-4-7-high-fast",
+      label: "claude-opus-4-7-high-fast",
+      description: "Opus 4.7 1M High Fast",
+    },
+    {
+      value: "claude-opus-4-7-xhigh",
+      label: "claude-opus-4-7-xhigh",
+      description: "Opus 4.7 1M",
+    },
+    {
+      value: "claude-opus-4-7-xhigh-fast",
+      label: "claude-opus-4-7-xhigh-fast",
+      description: "Opus 4.7 1M Fast",
+    },
+    {
+      value: "claude-opus-4-7-max",
+      label: "claude-opus-4-7-max",
+      description: "Opus 4.7 1M Max",
+    },
+    {
+      value: "claude-opus-4-7-max-fast",
+      label: "claude-opus-4-7-max-fast",
+      description: "Opus 4.7 1M Max Fast",
+    },
+    {
+      value: "claude-opus-4-7-thinking-low",
+      label: "claude-opus-4-7-thinking-low",
+      description: "Opus 4.7 1M Low Thinking",
+    },
+    {
+      value: "claude-opus-4-7-thinking-low-fast",
+      label: "claude-opus-4-7-thinking-low-fast",
+      description: "Opus 4.7 1M Low Thinking Fast",
+    },
+    {
+      value: "claude-opus-4-7-thinking-medium",
+      label: "claude-opus-4-7-thinking-medium",
+      description: "Opus 4.7 1M Medium Thinking",
+    },
+    {
+      value: "claude-opus-4-7-thinking-medium-fast",
+      label: "claude-opus-4-7-thinking-medium-fast",
+      description: "Opus 4.7 1M Medium Thinking Fast",
+    },
+    {
+      value: "claude-opus-4-7-thinking-high-fast",
+      label: "claude-opus-4-7-thinking-high-fast",
+      description: "Opus 4.7 1M High Thinking Fast",
+    },
+    {
+      value: "claude-opus-4-7-thinking-xhigh",
+      label: "claude-opus-4-7-thinking-xhigh",
+      description: "Opus 4.7 1M Thinking",
+    },
+    {
+      value: "claude-opus-4-7-thinking-xhigh-fast",
+      label: "claude-opus-4-7-thinking-xhigh-fast",
+      description: "Opus 4.7 1M Thinking Fast",
+    },
+    {
+      value: "claude-opus-4-7-thinking-max",
+      label: "claude-opus-4-7-thinking-max",
+      description: "Opus 4.7 1M Max Thinking",
+    },
+    {
+      value: "claude-opus-4-7-thinking-max-fast",
+      label: "claude-opus-4-7-thinking-max-fast",
+      description: "Opus 4.7 1M Max Thinking Fast",
+    },
+    {
+      value: "grok-build-0.1",
+      label: "grok-build-0.1",
+      description: "Grok Build 0.1 1M",
+    },
+    {
+      value: "gpt-5.4-low",
+      label: "gpt-5.4-low",
+      description: "GPT-5.4 1M Low",
+    },
+    {
+      value: "gpt-5.4-medium",
+      label: "gpt-5.4-medium",
+      description: "GPT-5.4 1M",
+    },
+    {
+      value: "gpt-5.4-medium-fast",
+      label: "gpt-5.4-medium-fast",
+      description: "GPT-5.4 Fast",
+    },
+    {
+      value: "gpt-5.4-xhigh",
+      label: "gpt-5.4-xhigh",
+      description: "GPT-5.4 1M Extra High",
+    },
+    {
+      value: "gpt-5.4-xhigh-fast",
+      label: "gpt-5.4-xhigh-fast",
+      description: "GPT-5.4 Extra High Fast",
+    },
+    {
+      value: "claude-4.6-opus-high",
+      label: "claude-4.6-opus-high",
+      description: "Opus 4.6 1M",
+    },
+    {
+      value: "claude-4.6-opus-max",
+      label: "claude-4.6-opus-max",
+      description: "Opus 4.6 1M Max",
+    },
+    {
+      value: "claude-4.6-opus-max-thinking",
+      label: "claude-4.6-opus-max-thinking",
+      description: "Opus 4.6 1M Max Thinking",
+    },
+    {
+      value: "claude-4.6-opus-max-thinking-fast",
+      label: "claude-4.6-opus-max-thinking-fast",
+      description: "Opus 4.6 1M Max Thinking Fast",
+    },
+    {
+      value: "claude-4.5-opus-high",
+      label: "claude-4.5-opus-high",
+      description: "Opus 4.5",
+    },
+    {
+      value: "claude-4.5-opus-high-thinking",
+      label: "claude-4.5-opus-high-thinking",
+      description: "Opus 4.5 Thinking",
+    },
+    {
+      value: "gpt-5.2-low",
+      label: "gpt-5.2-low",
+      description: "GPT-5.2 Low",
+    },
+    {
+      value: "gpt-5.2-low-fast",
+      label: "gpt-5.2-low-fast",
+      description: "GPT-5.2 Low Fast",
+    },
+    {
+      value: "gpt-5.2-fast",
+      label: "gpt-5.2-fast",
+      description: "GPT-5.2 Fast",
+    },
+    {
+      value: "gpt-5.2-high",
+      label: "gpt-5.2-high",
+      description: "GPT-5.2 High",
+    },
+    {
+      value: "gpt-5.2-high-fast",
+      label: "gpt-5.2-high-fast",
+      description: "GPT-5.2 High Fast",
+    },
+    {
+      value: "gpt-5.2-xhigh",
+      label: "gpt-5.2-xhigh",
+      description: "GPT-5.2 Extra High",
+    },
+    {
+      value: "gpt-5.2-xhigh-fast",
+      label: "gpt-5.2-xhigh-fast",
+      description: "GPT-5.2 Extra High Fast",
+    },
+    {
+      value: "gemini-3.1-pro",
+      label: "gemini-3.1-pro",
+      description: "Gemini 3.1 Pro",
+    },
+    {
+      value: "gpt-5.4-mini-none",
+      label: "gpt-5.4-mini-none",
+      description: "GPT-5.4 Mini None",
+    },
+    {
+      value: "gpt-5.4-mini-low",
+      label: "gpt-5.4-mini-low",
+      description: "GPT-5.4 Mini Low",
+    },
+    {
+      value: "gpt-5.4-mini-medium",
+      label: "gpt-5.4-mini-medium",
+      description: "GPT-5.4 Mini",
+    },
+    {
+      value: "gpt-5.4-mini-high",
+      label: "gpt-5.4-mini-high",
+      description: "GPT-5.4 Mini High",
+    },
+    {
+      value: "gpt-5.4-mini-xhigh",
+      label: "gpt-5.4-mini-xhigh",
+      description: "GPT-5.4 Mini Extra High",
+    },
+    {
+      value: "gpt-5.4-nano-none",
+      label: "gpt-5.4-nano-none",
+      description: "GPT-5.4 Nano None",
+    },
+    {
+      value: "gpt-5.4-nano-low",
+      label: "gpt-5.4-nano-low",
+      description: "GPT-5.4 Nano Low",
+    },
+    {
+      value: "gpt-5.4-nano-medium",
+      label: "gpt-5.4-nano-medium",
+      description: "GPT-5.4 Nano",
+    },
+    {
+      value: "gpt-5.4-nano-high",
+      label: "gpt-5.4-nano-high",
+      description: "GPT-5.4 Nano High",
+    },
+    {
+      value: "gpt-5.4-nano-xhigh",
+      label: "gpt-5.4-nano-xhigh",
+      description: "GPT-5.4 Nano Extra High",
+    },
+    {
+      value: "grok-4.3",
+      label: "grok-4.3",
+      description: "Grok 4.3 1M",
+    },
+    {
+      value: "claude-4.5-sonnet",
+      label: "claude-4.5-sonnet",
+      description: "Sonnet 4.5",
+    },
+    {
+      value: "claude-4.5-sonnet-thinking",
+      label: "claude-4.5-sonnet-thinking",
+      description: "Sonnet 4.5 Thinking",
+    },
+    {
+      value: "gpt-5.1-low",
+      label: "gpt-5.1-low",
+      description: "GPT-5.1 Low",
+    },
+    {
+      value: "gpt-5.1",
+      label: "gpt-5.1",
+      description: "GPT-5.1",
+    },
+    {
+      value: "gpt-5.1-high",
+      label: "gpt-5.1-high",
+      description: "GPT-5.1 High",
+    },
+    {
+      value: "gemini-3-flash",
+      label: "gemini-3-flash",
+      description: "Gemini 3 Flash",
+    },
+    {
+      value: "gemini-3.5-flash",
+      label: "gemini-3.5-flash",
+      description: "Gemini 3.5 Flash",
+    },
+    {
+      value: "gpt-5.1-codex-mini-low",
+      label: "gpt-5.1-codex-mini-low",
+      description: "Codex 5.1 Mini Low",
+    },
+    {
+      value: "gpt-5.1-codex-mini",
+      label: "gpt-5.1-codex-mini",
+      description: "Codex 5.1 Mini",
+    },
+    {
+      value: "gpt-5.1-codex-mini-high",
+      label: "gpt-5.1-codex-mini-high",
+      description: "Codex 5.1 Mini High",
+    },
+    {
+      value: "claude-4-sonnet",
+      label: "claude-4-sonnet",
+      description: "Sonnet 4",
+    },
+    {
+      value: "claude-4-sonnet-thinking",
+      label: "claude-4-sonnet-thinking",
+      description: "Sonnet 4 Thinking",
+    },
+    {
+      value: "gpt-5-mini",
+      label: "gpt-5-mini",
+      description: "GPT-5 Mini",
+    },
+    {
+      value: "kimi-k2.5",
+      label: "kimi-k2.5",
+      description: "Kimi K2.5",
+    },
+  ],
+
+  DEFAULT: "composer-2.5-fast",
+};
+
+/**
+ * Codex (OpenAI) Models
+ */
+export const CODEX_MODELS = {
+  OPTIONS: [
+    { value: "gpt-5.5", label: "gpt-5.5" },
+    { value: "gpt-5.4", label: "gpt-5.4" },
+    { value: "gpt-5.4-mini", label: "gpt-5.4-mini" },
+    { value: "gpt-5.3-codex", label: "gpt-5.3-codex" },
+    { value: "gpt-5.2", label: "gpt-5.2" },
+  ],
+
+  DEFAULT: "gpt-5.4",
+};
+
+/**
+ * Gemini Models
+ */
+export const GEMINI_MODELS = {
+  OPTIONS: [
+    { value: "gemini-3.1-pro-preview", label: "Gemini 3.1 Pro Preview" },
+    { value: "gemini-3-pro-preview", label: "Gemini 3 Pro Preview" },
+    { value: "gemini-3-flash-preview", label: "Gemini 3 Flash Preview" },
+    { value: "gemini-2.5-flash", label: "Gemini 2.5 Flash" },
+    { value: "gemini-2.5-pro", label: "Gemini 2.5 Pro" },
+    { value: "gemini-2.0-flash-lite", label: "Gemini 2.0 Flash Lite" },
+    { value: "gemini-2.0-flash", label: "Gemini 2.0 Flash" },
+    { value: "gemini-2.0-pro-exp", label: "Gemini 2.0 Pro Experimental" },
+    {
+      value: "gemini-2.0-flash-thinking-exp",
+      label: "Gemini 2.0 Flash Thinking",
+    },
+  ],
+
+  DEFAULT: "gemini-3.1-pro-preview",
+};
+
+/**
+ * OpenCode Models
+ *
+ * OpenCode model ids include the upstream provider prefix.
+ */
+export const OPENCODE_MODELS = {
+  OPTIONS: [
+    {
+      value: "opencode/big-pickle",
+      label: "Big Pickle",
+      description: "opencode - opencode/big-pickle",
+    },
+    {
+      value: "opencode/deepseek-v4-flash-free",
+      label: "Deepseek V4 Flash Free",
+      description: "opencode - opencode/deepseek-v4-flash-free",
+    },
+    {
+      value: "opencode/nemotron-3-super-free",
+      label: "Nemotron 3 Super Free",
+      description: "opencode - opencode/nemotron-3-super-free",
+    },
+    {
+      value: "anthropic/claude-3-5-haiku-20241022",
+      label: "Claude 3.5 Haiku (2024-10-22)",
+      description: "anthropic - anthropic/claude-3-5-haiku-20241022",
+    },
+    {
+      value: "anthropic/claude-3-5-haiku-latest",
+      label: "Claude 3.5 Haiku Latest",
+      description: "anthropic - anthropic/claude-3-5-haiku-latest",
+    },
+    {
+      value: "anthropic/claude-3-5-sonnet-20240620",
+      label: "Claude 3.5 Sonnet (2024-06-20)",
+      description: "anthropic - anthropic/claude-3-5-sonnet-20240620",
+    },
+    {
+      value: "anthropic/claude-3-5-sonnet-20241022",
+      label: "Claude 3.5 Sonnet (2024-10-22)",
+      description: "anthropic - anthropic/claude-3-5-sonnet-20241022",
+    },
+    {
+      value: "anthropic/claude-3-7-sonnet-20250219",
+      label: "Claude 3.7 Sonnet (2025-02-19)",
+      description: "anthropic - anthropic/claude-3-7-sonnet-20250219",
+    },
+    {
+      value: "anthropic/claude-3-haiku-20240307",
+      label: "Claude 3 Haiku (2024-03-07)",
+      description: "anthropic - anthropic/claude-3-haiku-20240307",
+    },
+    {
+      value: "anthropic/claude-3-opus-20240229",
+      label: "Claude 3 Opus (2024-02-29)",
+      description: "anthropic - anthropic/claude-3-opus-20240229",
+    },
+    {
+      value: "anthropic/claude-3-sonnet-20240229",
+      label: "Claude 3 Sonnet (2024-02-29)",
+      description: "anthropic - anthropic/claude-3-sonnet-20240229",
+    },
+    {
+      value: "anthropic/claude-haiku-4-5",
+      label: "Claude Haiku 4.5",
+      description: "anthropic - anthropic/claude-haiku-4-5",
+    },
+    {
+      value: "anthropic/claude-haiku-4-5-20251001",
+      label: "Claude Haiku 4.5 (2025-10-01)",
+      description: "anthropic - anthropic/claude-haiku-4-5-20251001",
+    },
+    {
+      value: "anthropic/claude-opus-4-0",
+      label: "Claude Opus 4.0",
+      description: "anthropic - anthropic/claude-opus-4-0",
+    },
+    {
+      value: "anthropic/claude-opus-4-1",
+      label: "Claude Opus 4.1",
+      description: "anthropic - anthropic/claude-opus-4-1",
+    },
+    {
+      value: "anthropic/claude-opus-4-1-20250805",
+      label: "Claude Opus 4.1 (2025-08-05)",
+      description: "anthropic - anthropic/claude-opus-4-1-20250805",
+    },
+    {
+      value: "anthropic/claude-opus-4-20250514",
+      label: "Claude Opus 4 (2025-05-14)",
+      description: "anthropic - anthropic/claude-opus-4-20250514",
+    },
+    {
+      value: "anthropic/claude-opus-4-5",
+      label: "Claude Opus 4.5",
+      description: "anthropic - anthropic/claude-opus-4-5",
+    },
+    {
+      value: "anthropic/claude-opus-4-5-20251101",
+      label: "Claude Opus 4.5 (2025-11-01)",
+      description: "anthropic - anthropic/claude-opus-4-5-20251101",
+    },
+    {
+      value: "anthropic/claude-opus-4-6",
+      label: "Claude Opus 4.6",
+      description: "anthropic - anthropic/claude-opus-4-6",
+    },
+    {
+      value: "anthropic/claude-opus-4-6-fast",
+      label: "Claude Opus 4.6 Fast",
+      description: "anthropic - anthropic/claude-opus-4-6-fast",
+    },
+    {
+      value: "anthropic/claude-opus-4-7",
+      label: "Claude Opus 4.7",
+      description: "anthropic - anthropic/claude-opus-4-7",
+    },
+    {
+      value: "anthropic/claude-opus-4-7-fast",
+      label: "Claude Opus 4.7 Fast",
+      description: "anthropic - anthropic/claude-opus-4-7-fast",
+    },
+    {
+      value: "anthropic/claude-sonnet-4-0",
+      label: "Claude Sonnet 4.0",
+      description: "anthropic - anthropic/claude-sonnet-4-0",
+    },
+    {
+      value: "anthropic/claude-sonnet-4-20250514",
+      label: "Claude Sonnet 4 (2025-05-14)",
+      description: "anthropic - anthropic/claude-sonnet-4-20250514",
+    },
+    {
+      value: "anthropic/claude-sonnet-4-5",
+      label: "Claude Sonnet 4.5",
+      description: "anthropic - anthropic/claude-sonnet-4-5",
+    },
+    {
+      value: "anthropic/claude-sonnet-4-5-20250929",
+      label: "Claude Sonnet 4.5 (2025-09-29)",
+      description: "anthropic - anthropic/claude-sonnet-4-5-20250929",
+    },
+    {
+      value: "anthropic/claude-sonnet-4-6",
+      label: "Claude Sonnet 4.6",
+      description: "anthropic - anthropic/claude-sonnet-4-6",
+    },
+    {
+      value: "openai/gpt-5.2",
+      label: "GPT-5.2",
+      description: "openai - openai/gpt-5.2",
+    },
+    {
+      value: "openai/gpt-5.3-codex",
+      label: "GPT-5.3 Codex",
+      description: "openai - openai/gpt-5.3-codex",
+    },
+    {
+      value: "openai/gpt-5.3-codex-spark",
+      label: "GPT-5.3 Codex Spark",
+      description: "openai - openai/gpt-5.3-codex-spark",
+    },
+    {
+      value: "openai/gpt-5.4",
+      label: "GPT-5.4",
+      description: "openai - openai/gpt-5.4",
+    },
+    {
+      value: "openai/gpt-5.4-fast",
+      label: "GPT-5.4 Fast",
+      description: "openai - openai/gpt-5.4-fast",
+    },
+    {
+      value: "openai/gpt-5.4-mini",
+      label: "GPT-5.4 Mini",
+      description: "openai - openai/gpt-5.4-mini",
+    },
+    {
+      value: "openai/gpt-5.4-mini-fast",
+      label: "GPT-5.4 Mini Fast",
+      description: "openai - openai/gpt-5.4-mini-fast",
+    },
+    {
+      value: "openai/gpt-5.5",
+      label: "GPT-5.5",
+      description: "openai - openai/gpt-5.5",
+    },
+    {
+      value: "openai/gpt-5.5-fast",
+      label: "GPT-5.5 Fast",
+      description: "openai - openai/gpt-5.5-fast",
+    },
+    {
+      value: "openai/gpt-5.5-pro",
+      label: "GPT-5.5 Pro",
+      description: "openai - openai/gpt-5.5-pro",
+    },
+  ],
+
+  DEFAULT: "anthropic/claude-sonnet-4-5",
+};
+
+/**
+ * Ordered provider registry. Display order in documentation.
+ */
+export const PROVIDERS = [
+  { id: "claude", name: "Anthropic", models: CLAUDE_MODELS },
+  { id: "codex", name: "OpenAI", models: CODEX_MODELS },
+  { id: "gemini", name: "Google", models: GEMINI_MODELS },
+  { id: "cursor", name: "Cursor", models: CURSOR_MODELS },
+  { id: "opencode", name: "OpenCode", models: OPENCODE_MODELS },
+];
diff --git a/redirect-package/README.md b/redirect-package/README.md
index 2cc6cdda..6dd6c618 100644
--- a/redirect-package/README.md
+++ b/redirect-package/README.md
@@ -75,7 +75,7 @@
 - **Session Management** - Resume conversations, manage multiple sessions, and track history
 - **Plugin System** - Extend CloudCLI with custom plugins — add new tabs, backend services, and integrations. [Build your own →](https://github.com/cloudcli-ai/cloudcli-plugin-starter)
 - **TaskMaster AI Integration** *(Optional)* - Advanced project management with AI-powered task planning, PRD parsing, and workflow automation
-- **Model Compatibility** - Works with Claude, GPT, and Gemini model families (see [`shared/modelConstants.js`](https://github.com/siteboon/claudecodeui/blob/main/shared/modelConstants.js) for the full list of supported models)
+- **Model Compatibility** - Works with Claude, GPT, and Gemini model families (see [`public/modelConstants.js`](https://github.com/siteboon/claudecodeui/blob/main/public/modelConstants.js) for the full list of supported models)
 
 
 ## Quick Start
diff --git a/server/claude-sdk.js b/server/claude-sdk.js
index 7239f81a..5d8a27d7 100644
--- a/server/claude-sdk.js
+++ b/server/claude-sdk.js
@@ -17,7 +17,9 @@ import crypto from 'crypto';
 import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
-import { CLAUDE_MODELS } from '../shared/modelConstants.js';
+import { CLAUDE_FALLBACK_MODELS } from './modules/providers/list/claude/claude-models.provider.js';
+import { providerModelsService } from './modules/providers/services/provider-models.service.js';
+import { resolveClaudeCodeExecutablePath } from './shared/claude-cli-path.js';
 import {
   createNotificationEvent,
   notifyRunFailed,
@@ -153,11 +155,9 @@ function mapCliOptionsToSDK(options = {}) {
   // Since SDK 0.2.113, options.env replaces process.env instead of overlaying it.
   sdkOptions.env = { ...process.env };
 
-  // Use CLAUDE_CLI_PATH if explicitly set, otherwise fall back to 'claude' on PATH.
-  // The SDK 0.2.113+ looks for a bundled native binary optional dep by default;
-  // this fallback ensures users who installed via the official installer still work
-  // even when npm prune --production has removed those optional deps.
-  sdkOptions.pathToClaudeCodeExecutable = process.env.CLAUDE_CLI_PATH || 'claude';
+  // Resolve the executable eagerly on Windows because the SDK uses raw child_process.spawn,
+  // which does not reliably follow npm's shell wrappers like cross-spawn does.
+  sdkOptions.pathToClaudeCodeExecutable = resolveClaudeCodeExecutablePath(process.env.CLAUDE_CLI_PATH);
 
   // Map working directory
   if (cwd) {
@@ -205,7 +205,7 @@ function mapCliOptionsToSDK(options = {}) {
 
   // Map model (default to sonnet)
   // Valid models: sonnet, opus, haiku, opusplan, sonnet[1m]
-  sdkOptions.model = options.model || CLAUDE_MODELS.DEFAULT;
+  sdkOptions.model = options.model || CLAUDE_FALLBACK_MODELS.DEFAULT;
   // Model logged at query start below
 
   // Map system prompt configuration
@@ -285,43 +285,68 @@ function transformMessage(sdkMessage) {
   return sdkMessage;
 }
 
+function readNumber(value) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
 /**
- * Extracts token usage from SDK result messages
- * @param {Object} resultMessage - SDK result message
+ * Extracts token usage from SDK messages.
+ * Prefers per-step `message.usage` (Claude message payload), then falls back
+ * to result-level usage/modelUsage for compatibility across SDK versions.
+ * @param {Object} sdkMessage - SDK stream message
  * @returns {Object|null} Token budget object or null
  */
-function extractTokenBudget(resultMessage) {
-  if (resultMessage.type !== 'result' || !resultMessage.modelUsage) {
+function extractTokenBudget(sdkMessage) {
+  if (!sdkMessage || typeof sdkMessage !== 'object') {
     return null;
   }
 
-  // Get the first model's usage data
-  const modelKey = Object.keys(resultMessage.modelUsage)[0];
-  const modelData = resultMessage.modelUsage[modelKey];
+  const messageUsage = sdkMessage.message?.usage || sdkMessage.usage;
+  if (messageUsage && typeof messageUsage === 'object') {
+    const inputTokens = readNumber(messageUsage.input_tokens ?? messageUsage.inputTokens);
+    const outputTokens = readNumber(messageUsage.output_tokens ?? messageUsage.outputTokens);
+    const totalUsed = inputTokens + outputTokens;
+    const contextWindow = parseInt(process.env.CONTEXT_WINDOW, 10) || 160000;
 
-  if (!modelData) {
+    return {
+      used: totalUsed,
+      total: contextWindow,
+      inputTokens,
+      outputTokens,
+      breakdown: {
+        input: inputTokens,
+        output: outputTokens,
+      },
+    };
+  }
+
+  if (!sdkMessage.modelUsage || typeof sdkMessage.modelUsage !== 'object') {
     return null;
   }
 
-  // Use cumulative tokens if available (tracks total for the session)
-  // Otherwise fall back to per-request tokens
-  const inputTokens = modelData.cumulativeInputTokens || modelData.inputTokens || 0;
-  const outputTokens = modelData.cumulativeOutputTokens || modelData.outputTokens || 0;
-  const cacheReadTokens = modelData.cumulativeCacheReadInputTokens || modelData.cacheReadInputTokens || 0;
-  const cacheCreationTokens = modelData.cumulativeCacheCreationInputTokens || modelData.cacheCreationInputTokens || 0;
+  // Fallback for older SDK messages with only modelUsage
+  const modelKey = Object.keys(sdkMessage.modelUsage)[0];
+  const modelData = sdkMessage.modelUsage[modelKey];
 
-  // Total used = input + output + cache tokens
-  const totalUsed = inputTokens + outputTokens + cacheReadTokens + cacheCreationTokens;
+  if (!modelData || typeof modelData !== 'object') {
+    return null;
+  }
 
-  // Use configured context window budget from environment (default 160000)
-  // This is the user's budget limit, not the model's context window
-  const contextWindow = parseInt(process.env.CONTEXT_WINDOW) || 160000;
-
-  // Token calc logged via token-budget WS event
+  const inputTokens = readNumber(modelData.cumulativeInputTokens ?? modelData.inputTokens);
+  const outputTokens = readNumber(modelData.cumulativeOutputTokens ?? modelData.outputTokens);
+  const totalUsed = inputTokens + outputTokens;
+  const contextWindow = parseInt(process.env.CONTEXT_WINDOW, 10) || 160000;
 
   return {
     used: totalUsed,
-    total: contextWindow
+    total: contextWindow,
+    inputTokens,
+    outputTokens,
+    breakdown: {
+      input: inputTokens,
+      output: outputTokens,
+    },
   };
 }
 
@@ -492,8 +517,17 @@ async function queryClaudeSDK(command, options = {}, ws) {
   };
 
   try {
+    const resolvedModel = await providerModelsService.resolveResumeModel(
+      'claude',
+      sessionId,
+      options.model,
+    );
+
     // Map CLI options to SDK format
-    const sdkOptions = mapCliOptionsToSDK(options);
+    const sdkOptions = mapCliOptionsToSDK({
+      ...options,
+      model: resolvedModel || options.model,
+    });
 
     // Load MCP configuration
     const mcpServers = await loadMcpConfig(options.cwd);
@@ -527,6 +561,12 @@ async function queryClaudeSDK(command, options = {}, ws) {
       }]
     };
 
+    // Caveat: in 'auto' and 'bypassPermissions' modes the SDK resolves approval
+    // at the permission-mode step and skips this callback, so interactive tools
+    // (AskUserQuestion, ExitPlanMode) won't reach the UI — the classifier/bypass
+    // auto-approves them and the model acts on a generated answer. Move these
+    // tools to a PreToolUse hook (runs before the mode check) if we need them
+    // to work in those modes.
     sdkOptions.canUseTool = async (toolName, input, context) => {
       const requiresInteraction = TOOLS_REQUIRING_INTERACTION.has(toolName);
 
@@ -669,16 +709,10 @@ async function queryClaudeSDK(command, options = {}, ws) {
         ws.send(msg);
       }
 
-      // Extract and send token budget updates from result messages
-      if (message.type === 'result') {
-        const models = Object.keys(message.modelUsage || {});
-        if (models.length > 0) {
-          // Model info available in result message
-        }
-        const tokenBudgetData = extractTokenBudget(message);
-        if (tokenBudgetData) {
-          ws.send(createNormalizedMessage({ kind: 'status', text: 'token_budget', tokenBudget: tokenBudgetData, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
-        }
+      // Extract and send token budget updates from assistant/result usage payloads
+      const tokenBudgetData = extractTokenBudget(message);
+      if (tokenBudgetData) {
+        ws.send(createNormalizedMessage({ kind: 'status', text: 'token_budget', tokenBudget: tokenBudgetData, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
       }
     }
 
diff --git a/server/cursor-cli.js b/server/cursor-cli.js
index 66af16ef..6cfd7bac 100644
--- a/server/cursor-cli.js
+++ b/server/cursor-cli.js
@@ -3,6 +3,7 @@ import crossSpawn from 'cross-spawn';
 import { notifyRunFailed, notifyRunStopped } from './services/notification-orchestrator.js';
 import { sessionsService } from './modules/providers/services/sessions.service.js';
 import { providerAuthService } from './modules/providers/services/provider-auth.service.js';
+import { providerModelsService } from './modules/providers/services/provider-models.service.js';
 import { createNormalizedMessage } from './shared/utils.js';
 
 // Use cross-spawn on Windows for better command execution
@@ -28,6 +29,7 @@ function isWorkspaceTrustPrompt(text = '') {
 async function spawnCursor(command, options = {}, ws) {
   return new Promise(async (resolve, reject) => {
     const { sessionId, projectPath, cwd, resume, toolsSettings, skipPermissions, model, sessionSummary } = options;
+    const resolvedModel = await providerModelsService.resolveResumeModel('cursor', sessionId, model);
     let capturedSessionId = sessionId; // Track session ID throughout the process
     let sessionCreatedSent = false; // Track if we've already sent session-created event
     let hasRetriedWithTrust = false;
@@ -52,9 +54,10 @@ async function spawnCursor(command, options = {}, ws) {
       // Provide a prompt (works for both new and resumed sessions)
       baseArgs.push('-p', command);
 
-      // Add model flag if specified (only meaningful for new sessions; harmless on resume)
-      if (!sessionId && model) {
-        baseArgs.push('--model', model);
+      // Model overrides are applied to both new and resumed sessions so a
+      // session-scoped change request can take effect on the next turn.
+      if (resolvedModel) {
+        baseArgs.push('--model', resolvedModel);
       }
 
       // Request streaming JSON when we are providing a prompt
@@ -150,7 +153,6 @@ async function spawnCursor(command, options = {}, ws) {
 
         try {
           const response = JSON.parse(line);
-          console.log('Parsed JSON response:', response);
 
           // Handle different message types
           switch (response.type) {
@@ -159,7 +161,6 @@ async function spawnCursor(command, options = {}, ws) {
                 // Capture session ID
                 if (response.session_id && !capturedSessionId) {
                   capturedSessionId = response.session_id;
-                  console.log('Captured session ID:', capturedSessionId);
 
                   // Update process key with captured session ID
                   if (processKey !== capturedSessionId) {
@@ -197,7 +198,6 @@ async function spawnCursor(command, options = {}, ws) {
 
             case 'result': {
               // Session complete — send stream end + lifecycle complete with result payload
-              console.log('Cursor session result:', response);
               const resultText = typeof response.result === 'string' ? response.result : '';
               ws.send(createNormalizedMessage({
                 kind: 'complete',
@@ -213,8 +213,6 @@ async function spawnCursor(command, options = {}, ws) {
               // Unknown message types — ignore.
           }
         } catch (parseError) {
-          console.log('Non-JSON response:', line);
-
           if (shouldSuppressForTrustRetry(line)) {
             return;
           }
@@ -228,7 +226,6 @@ async function spawnCursor(command, options = {}, ws) {
       // Handle stdout (streaming JSON responses)
       cursorProcess.stdout.on('data', (data) => {
         const rawOutput = data.toString();
-        console.log('Cursor CLI stdout:', rawOutput);
 
         // Stream chunks can split JSON objects across packets; keep trailing partial line.
         stdoutLineBuffer += rawOutput;
@@ -254,8 +251,6 @@ async function spawnCursor(command, options = {}, ws) {
 
       // Handle process completion
       cursorProcess.on('close', async (code) => {
-        console.log(`Cursor CLI process exited with code ${code}`);
-
         const finalSessionId = capturedSessionId || sessionId || processKey;
         activeCursorProcesses.delete(finalSessionId);
 
diff --git a/server/database/db.js b/server/database/db.js
deleted file mode 100644
index f43c894a..00000000
--- a/server/database/db.js
+++ /dev/null
@@ -1,593 +0,0 @@
-import Database from 'better-sqlite3';
-import path from 'path';
-import fs from 'fs';
-import crypto from 'crypto';
-import { findAppRoot, getModuleDir } from '../utils/runtime-paths.js';
-import {
-  APP_CONFIG_TABLE_SQL,
-  USER_NOTIFICATION_PREFERENCES_TABLE_SQL,
-  VAPID_KEYS_TABLE_SQL,
-  PUSH_SUBSCRIPTIONS_TABLE_SQL,
-  SESSION_NAMES_TABLE_SQL,
-  SESSION_NAMES_LOOKUP_INDEX_SQL,
-  DATABASE_SCHEMA_SQL
-} from './schema.js';
-
-const __dirname = getModuleDir(import.meta.url);
-// The compiled backend lives under dist-server/server/database, but the install root we log
-// should still point at the project/app root. Resolving it here avoids build-layout drift.
-const APP_ROOT = findAppRoot(__dirname);
-
-// ANSI color codes for terminal output
-const colors = {
-    reset: '\x1b[0m',
-    bright: '\x1b[1m',
-    cyan: '\x1b[36m',
-    dim: '\x1b[2m',
-};
-
-const c = {
-    info: (text) => `${colors.cyan}${text}${colors.reset}`,
-    bright: (text) => `${colors.bright}${text}${colors.reset}`,
-    dim: (text) => `${colors.dim}${text}${colors.reset}`,
-};
-
-// Use DATABASE_PATH environment variable if set, otherwise use default location
-const DB_PATH = process.env.DATABASE_PATH || path.join(__dirname, 'auth.db');
-
-// Ensure database directory exists if custom path is provided
-if (process.env.DATABASE_PATH) {
-  const dbDir = path.dirname(DB_PATH);
-  try {
-    if (!fs.existsSync(dbDir)) {
-      fs.mkdirSync(dbDir, { recursive: true });
-      console.log(`Created database directory: ${dbDir}`);
-    }
-  } catch (error) {
-    console.error(`Failed to create database directory ${dbDir}:`, error.message);
-    throw error;
-  }
-}
-
-// As part of 1.19.2 we are introducing a new location for auth.db. The below handles exisitng moving legacy database from install directory to new location
-const LEGACY_DB_PATH = path.join(__dirname, 'auth.db');
-if (DB_PATH !== LEGACY_DB_PATH && !fs.existsSync(DB_PATH) && fs.existsSync(LEGACY_DB_PATH)) {
-  try {
-    fs.copyFileSync(LEGACY_DB_PATH, DB_PATH);
-    console.log(`[MIGRATION] Copied database from ${LEGACY_DB_PATH} to ${DB_PATH}`);
-    for (const suffix of ['-wal', '-shm']) {
-      if (fs.existsSync(LEGACY_DB_PATH + suffix)) {
-        fs.copyFileSync(LEGACY_DB_PATH + suffix, DB_PATH + suffix);
-      }
-    }
-  } catch (err) {
-    console.warn(`[MIGRATION] Could not copy legacy database: ${err.message}`);
-  }
-}
-
-// Create database connection
-const db = new Database(DB_PATH);
-
-// app_config must exist before any other module imports (auth.js reads the JWT secret at load time).
-// runMigrations() also creates this table, but it runs too late for existing installations
-// where auth.js is imported before initializeDatabase() is called.
-db.exec(APP_CONFIG_TABLE_SQL);
-
-// Show app installation path prominently
-const appInstallPath = APP_ROOT;
-console.log('');
-console.log(c.dim('═'.repeat(60)));
-console.log(`${c.info('[INFO]')} App Installation: ${c.bright(appInstallPath)}`);
-console.log(`${c.info('[INFO]')} Database: ${c.dim(path.relative(appInstallPath, DB_PATH))}`);
-if (process.env.DATABASE_PATH) {
-  console.log(`       ${c.dim('(Using custom DATABASE_PATH from environment)')}`);
-}
-console.log(c.dim('═'.repeat(60)));
-console.log('');
-
-const runMigrations = () => {
-  try {
-    const tableInfo = db.prepare("PRAGMA table_info(users)").all();
-    const columnNames = tableInfo.map(col => col.name);
-
-    if (!columnNames.includes('git_name')) {
-      console.log('Running migration: Adding git_name column');
-      db.exec('ALTER TABLE users ADD COLUMN git_name TEXT');
-    }
-
-    if (!columnNames.includes('git_email')) {
-      console.log('Running migration: Adding git_email column');
-      db.exec('ALTER TABLE users ADD COLUMN git_email TEXT');
-    }
-
-    if (!columnNames.includes('has_completed_onboarding')) {
-      console.log('Running migration: Adding has_completed_onboarding column');
-      db.exec('ALTER TABLE users ADD COLUMN has_completed_onboarding BOOLEAN DEFAULT 0');
-    }
-
-    db.exec(USER_NOTIFICATION_PREFERENCES_TABLE_SQL);
-    db.exec(VAPID_KEYS_TABLE_SQL);
-    db.exec(PUSH_SUBSCRIPTIONS_TABLE_SQL);
-    db.exec(APP_CONFIG_TABLE_SQL);
-    db.exec(SESSION_NAMES_TABLE_SQL);
-    db.exec(SESSION_NAMES_LOOKUP_INDEX_SQL);
-
-    console.log('Database migrations completed successfully');
-  } catch (error) {
-    console.error('Error running migrations:', error.message);
-    throw error;
-  }
-};
-
-// Initialize database with schema
-const initializeDatabase = async () => {
-  try {
-    db.exec(DATABASE_SCHEMA_SQL);
-    console.log('Database initialized successfully');
-    runMigrations();
-  } catch (error) {
-    console.error('Error initializing database:', error.message);
-    throw error;
-  }
-};
-
-// User database operations
-const userDb = {
-  // Check if any users exist
-  hasUsers: () => {
-    try {
-      const row = db.prepare('SELECT COUNT(*) as count FROM users').get();
-      return row.count > 0;
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  // Create a new user
-  createUser: (username, passwordHash) => {
-    try {
-      const stmt = db.prepare('INSERT INTO users (username, password_hash) VALUES (?, ?)');
-      const result = stmt.run(username, passwordHash);
-      return { id: result.lastInsertRowid, username };
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  // Get user by username
-  getUserByUsername: (username) => {
-    try {
-      const row = db.prepare('SELECT * FROM users WHERE username = ? AND is_active = 1').get(username);
-      return row;
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  // Update last login time (non-fatal — logged but not thrown)
-  updateLastLogin: (userId) => {
-    try {
-      db.prepare('UPDATE users SET last_login = CURRENT_TIMESTAMP WHERE id = ?').run(userId);
-    } catch (err) {
-      console.warn('Failed to update last login:', err.message);
-    }
-  },
-
-  // Get user by ID
-  getUserById: (userId) => {
-    try {
-      const row = db.prepare('SELECT id, username, created_at, last_login FROM users WHERE id = ? AND is_active = 1').get(userId);
-      return row;
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  getFirstUser: () => {
-    try {
-      const row = db.prepare('SELECT id, username, created_at, last_login FROM users WHERE is_active = 1 LIMIT 1').get();
-      return row;
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  updateGitConfig: (userId, gitName, gitEmail) => {
-    try {
-      const stmt = db.prepare('UPDATE users SET git_name = ?, git_email = ? WHERE id = ?');
-      stmt.run(gitName, gitEmail, userId);
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  getGitConfig: (userId) => {
-    try {
-      const row = db.prepare('SELECT git_name, git_email FROM users WHERE id = ?').get(userId);
-      return row;
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  completeOnboarding: (userId) => {
-    try {
-      const stmt = db.prepare('UPDATE users SET has_completed_onboarding = 1 WHERE id = ?');
-      stmt.run(userId);
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  hasCompletedOnboarding: (userId) => {
-    try {
-      const row = db.prepare('SELECT has_completed_onboarding FROM users WHERE id = ?').get(userId);
-      return row?.has_completed_onboarding === 1;
-    } catch (err) {
-      throw err;
-    }
-  }
-};
-
-// API Keys database operations
-const apiKeysDb = {
-  // Generate a new API key
-  generateApiKey: () => {
-    return 'ck_' + crypto.randomBytes(32).toString('hex');
-  },
-
-  // Create a new API key
-  createApiKey: (userId, keyName) => {
-    try {
-      const apiKey = apiKeysDb.generateApiKey();
-      const stmt = db.prepare('INSERT INTO api_keys (user_id, key_name, api_key) VALUES (?, ?, ?)');
-      const result = stmt.run(userId, keyName, apiKey);
-      return { id: result.lastInsertRowid, keyName, apiKey };
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  // Get all API keys for a user
-  getApiKeys: (userId) => {
-    try {
-      const rows = db.prepare('SELECT id, key_name, api_key, created_at, last_used, is_active FROM api_keys WHERE user_id = ? ORDER BY created_at DESC').all(userId);
-      return rows;
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  // Validate API key and get user
-  validateApiKey: (apiKey) => {
-    try {
-      const row = db.prepare(`
-        SELECT u.id, u.username, ak.id as api_key_id
-        FROM api_keys ak
-        JOIN users u ON ak.user_id = u.id
-        WHERE ak.api_key = ? AND ak.is_active = 1 AND u.is_active = 1
-      `).get(apiKey);
-
-      if (row) {
-        // Update last_used timestamp
-        db.prepare('UPDATE api_keys SET last_used = CURRENT_TIMESTAMP WHERE id = ?').run(row.api_key_id);
-      }
-
-      return row;
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  // Delete an API key
-  deleteApiKey: (userId, apiKeyId) => {
-    try {
-      const stmt = db.prepare('DELETE FROM api_keys WHERE id = ? AND user_id = ?');
-      const result = stmt.run(apiKeyId, userId);
-      return result.changes > 0;
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  // Toggle API key active status
-  toggleApiKey: (userId, apiKeyId, isActive) => {
-    try {
-      const stmt = db.prepare('UPDATE api_keys SET is_active = ? WHERE id = ? AND user_id = ?');
-      const result = stmt.run(isActive ? 1 : 0, apiKeyId, userId);
-      return result.changes > 0;
-    } catch (err) {
-      throw err;
-    }
-  }
-};
-
-// User credentials database operations (for GitHub tokens, GitLab tokens, etc.)
-const credentialsDb = {
-  // Create a new credential
-  createCredential: (userId, credentialName, credentialType, credentialValue, description = null) => {
-    try {
-      const stmt = db.prepare('INSERT INTO user_credentials (user_id, credential_name, credential_type, credential_value, description) VALUES (?, ?, ?, ?, ?)');
-      const result = stmt.run(userId, credentialName, credentialType, credentialValue, description);
-      return { id: result.lastInsertRowid, credentialName, credentialType };
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  // Get all credentials for a user, optionally filtered by type
-  getCredentials: (userId, credentialType = null) => {
-    try {
-      let query = 'SELECT id, credential_name, credential_type, description, created_at, is_active FROM user_credentials WHERE user_id = ?';
-      const params = [userId];
-
-      if (credentialType) {
-        query += ' AND credential_type = ?';
-        params.push(credentialType);
-      }
-
-      query += ' ORDER BY created_at DESC';
-
-      const rows = db.prepare(query).all(...params);
-      return rows;
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  // Get active credential value for a user by type (returns most recent active)
-  getActiveCredential: (userId, credentialType) => {
-    try {
-      const row = db.prepare('SELECT credential_value FROM user_credentials WHERE user_id = ? AND credential_type = ? AND is_active = 1 ORDER BY created_at DESC LIMIT 1').get(userId, credentialType);
-      return row?.credential_value || null;
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  // Delete a credential
-  deleteCredential: (userId, credentialId) => {
-    try {
-      const stmt = db.prepare('DELETE FROM user_credentials WHERE id = ? AND user_id = ?');
-      const result = stmt.run(credentialId, userId);
-      return result.changes > 0;
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  // Toggle credential active status
-  toggleCredential: (userId, credentialId, isActive) => {
-    try {
-      const stmt = db.prepare('UPDATE user_credentials SET is_active = ? WHERE id = ? AND user_id = ?');
-      const result = stmt.run(isActive ? 1 : 0, credentialId, userId);
-      return result.changes > 0;
-    } catch (err) {
-      throw err;
-    }
-  }
-};
-
-const DEFAULT_NOTIFICATION_PREFERENCES = {
-  channels: {
-    inApp: false,
-    webPush: false
-  },
-  events: {
-    actionRequired: true,
-    stop: true,
-    error: true
-  }
-};
-
-const normalizeNotificationPreferences = (value) => {
-  const source = value && typeof value === 'object' ? value : {};
-
-  return {
-    channels: {
-      inApp: source.channels?.inApp === true,
-      webPush: source.channels?.webPush === true
-    },
-    events: {
-      actionRequired: source.events?.actionRequired !== false,
-      stop: source.events?.stop !== false,
-      error: source.events?.error !== false
-    }
-  };
-};
-
-const notificationPreferencesDb = {
-  getPreferences: (userId) => {
-    try {
-      const row = db.prepare('SELECT preferences_json FROM user_notification_preferences WHERE user_id = ?').get(userId);
-      if (!row) {
-        const defaults = normalizeNotificationPreferences(DEFAULT_NOTIFICATION_PREFERENCES);
-        db.prepare(
-          'INSERT INTO user_notification_preferences (user_id, preferences_json, updated_at) VALUES (?, ?, CURRENT_TIMESTAMP)'
-        ).run(userId, JSON.stringify(defaults));
-        return defaults;
-      }
-
-      let parsed;
-      try {
-        parsed = JSON.parse(row.preferences_json);
-      } catch {
-        parsed = DEFAULT_NOTIFICATION_PREFERENCES;
-      }
-      return normalizeNotificationPreferences(parsed);
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  updatePreferences: (userId, preferences) => {
-    try {
-      const normalized = normalizeNotificationPreferences(preferences);
-      db.prepare(
-        `INSERT INTO user_notification_preferences (user_id, preferences_json, updated_at)
-         VALUES (?, ?, CURRENT_TIMESTAMP)
-         ON CONFLICT(user_id) DO UPDATE SET
-           preferences_json = excluded.preferences_json,
-           updated_at = CURRENT_TIMESTAMP`
-      ).run(userId, JSON.stringify(normalized));
-      return normalized;
-    } catch (err) {
-      throw err;
-    }
-  }
-};
-
-const pushSubscriptionsDb = {
-  saveSubscription: (userId, endpoint, keysP256dh, keysAuth) => {
-    try {
-      db.prepare(
-        `INSERT INTO push_subscriptions (user_id, endpoint, keys_p256dh, keys_auth)
-         VALUES (?, ?, ?, ?)
-         ON CONFLICT(endpoint) DO UPDATE SET
-           user_id = excluded.user_id,
-           keys_p256dh = excluded.keys_p256dh,
-           keys_auth = excluded.keys_auth`
-      ).run(userId, endpoint, keysP256dh, keysAuth);
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  getSubscriptions: (userId) => {
-    try {
-      return db.prepare('SELECT endpoint, keys_p256dh, keys_auth FROM push_subscriptions WHERE user_id = ?').all(userId);
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  removeSubscription: (endpoint) => {
-    try {
-      db.prepare('DELETE FROM push_subscriptions WHERE endpoint = ?').run(endpoint);
-    } catch (err) {
-      throw err;
-    }
-  },
-
-  removeAllForUser: (userId) => {
-    try {
-      db.prepare('DELETE FROM push_subscriptions WHERE user_id = ?').run(userId);
-    } catch (err) {
-      throw err;
-    }
-  }
-};
-
-// Session custom names database operations
-const sessionNamesDb = {
-  // Set (insert or update) a custom session name
-  setName: (sessionId, provider, customName) => {
-    db.prepare(`
-      INSERT INTO session_names (session_id, provider, custom_name)
-      VALUES (?, ?, ?)
-      ON CONFLICT(session_id, provider)
-      DO UPDATE SET custom_name = excluded.custom_name, updated_at = CURRENT_TIMESTAMP
-    `).run(sessionId, provider, customName);
-  },
-
-  // Get a single custom session name
-  getName: (sessionId, provider) => {
-    const row = db.prepare(
-      'SELECT custom_name FROM session_names WHERE session_id = ? AND provider = ?'
-    ).get(sessionId, provider);
-    return row?.custom_name || null;
-  },
-
-  // Batch lookup — returns Map<sessionId, customName>
-  getNames: (sessionIds, provider) => {
-    if (!sessionIds.length) return new Map();
-    const placeholders = sessionIds.map(() => '?').join(',');
-    const rows = db.prepare(
-      `SELECT session_id, custom_name FROM session_names
-       WHERE session_id IN (${placeholders}) AND provider = ?`
-    ).all(...sessionIds, provider);
-    return new Map(rows.map(r => [r.session_id, r.custom_name]));
-  },
-
-  // Delete a custom session name
-  deleteName: (sessionId, provider) => {
-    return db.prepare(
-      'DELETE FROM session_names WHERE session_id = ? AND provider = ?'
-    ).run(sessionId, provider).changes > 0;
-  },
-};
-
-// Apply custom session names from the database (overrides CLI-generated summaries)
-function applyCustomSessionNames(sessions, provider) {
-  if (!sessions?.length) return;
-  try {
-    const ids = sessions.map(s => s.id);
-    const customNames = sessionNamesDb.getNames(ids, provider);
-    for (const session of sessions) {
-      const custom = customNames.get(session.id);
-      if (custom) session.summary = custom;
-    }
-  } catch (error) {
-    console.warn(`[DB] Failed to apply custom session names for ${provider}:`, error.message);
-  }
-}
-
-// App config database operations
-const appConfigDb = {
-  get: (key) => {
-    try {
-      const row = db.prepare('SELECT value FROM app_config WHERE key = ?').get(key);
-      return row?.value || null;
-    } catch (err) {
-      return null;
-    }
-  },
-
-  set: (key, value) => {
-    db.prepare(
-      'INSERT INTO app_config (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value'
-    ).run(key, value);
-  },
-
-  getOrCreateJwtSecret: () => {
-    let secret = appConfigDb.get('jwt_secret');
-    if (!secret) {
-      secret = crypto.randomBytes(64).toString('hex');
-      appConfigDb.set('jwt_secret', secret);
-    }
-    return secret;
-  }
-};
-
-// Backward compatibility - keep old names pointing to new system
-const githubTokensDb = {
-  createGithubToken: (userId, tokenName, githubToken, description = null) => {
-    return credentialsDb.createCredential(userId, tokenName, 'github_token', githubToken, description);
-  },
-  getGithubTokens: (userId) => {
-    return credentialsDb.getCredentials(userId, 'github_token');
-  },
-  getActiveGithubToken: (userId) => {
-    return credentialsDb.getActiveCredential(userId, 'github_token');
-  },
-  deleteGithubToken: (userId, tokenId) => {
-    return credentialsDb.deleteCredential(userId, tokenId);
-  },
-  toggleGithubToken: (userId, tokenId, isActive) => {
-    return credentialsDb.toggleCredential(userId, tokenId, isActive);
-  }
-};
-
-export {
-  db,
-  initializeDatabase,
-  userDb,
-  apiKeysDb,
-  credentialsDb,
-  notificationPreferencesDb,
-  pushSubscriptionsDb,
-  sessionNamesDb,
-  applyCustomSessionNames,
-  appConfigDb,
-  githubTokensDb // Backward compatibility
-};
diff --git a/server/database/schema.js b/server/database/schema.js
deleted file mode 100644
index 21c1b8eb..00000000
--- a/server/database/schema.js
+++ /dev/null
@@ -1,102 +0,0 @@
-export const APP_CONFIG_TABLE_SQL = `CREATE TABLE IF NOT EXISTS app_config (
-  key TEXT PRIMARY KEY,
-  value TEXT NOT NULL,
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);`;
-
-export const USER_NOTIFICATION_PREFERENCES_TABLE_SQL = `CREATE TABLE IF NOT EXISTS user_notification_preferences (
-  user_id INTEGER PRIMARY KEY,
-  preferences_json TEXT NOT NULL,
-  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-);`;
-
-export const VAPID_KEYS_TABLE_SQL = `CREATE TABLE IF NOT EXISTS vapid_keys (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  public_key TEXT NOT NULL,
-  private_key TEXT NOT NULL,
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);`;
-
-export const PUSH_SUBSCRIPTIONS_TABLE_SQL = `CREATE TABLE IF NOT EXISTS push_subscriptions (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  user_id INTEGER NOT NULL,
-  endpoint TEXT NOT NULL UNIQUE,
-  keys_p256dh TEXT NOT NULL,
-  keys_auth TEXT NOT NULL,
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-);`;
-
-export const SESSION_NAMES_TABLE_SQL = `CREATE TABLE IF NOT EXISTS session_names (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  session_id TEXT NOT NULL,
-  provider TEXT NOT NULL DEFAULT 'claude',
-  custom_name TEXT NOT NULL,
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-  UNIQUE(session_id, provider)
-);`;
-
-export const SESSION_NAMES_LOOKUP_INDEX_SQL = `CREATE INDEX IF NOT EXISTS idx_session_names_lookup ON session_names(session_id, provider);`;
-
-export const DATABASE_SCHEMA_SQL = `PRAGMA foreign_keys = ON;
-
-CREATE TABLE IF NOT EXISTS users (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  username TEXT UNIQUE NOT NULL,
-  password_hash TEXT NOT NULL,
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-  last_login DATETIME,
-  is_active BOOLEAN DEFAULT 1,
-  git_name TEXT,
-  git_email TEXT,
-  has_completed_onboarding BOOLEAN DEFAULT 0
-);
-
-CREATE INDEX IF NOT EXISTS idx_users_username ON users(username);
-CREATE INDEX IF NOT EXISTS idx_users_active ON users(is_active);
-
-CREATE TABLE IF NOT EXISTS api_keys (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  user_id INTEGER NOT NULL,
-  key_name TEXT NOT NULL,
-  api_key TEXT UNIQUE NOT NULL,
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-  last_used DATETIME,
-  is_active BOOLEAN DEFAULT 1,
-  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-);
-
-CREATE INDEX IF NOT EXISTS idx_api_keys_key ON api_keys(api_key);
-CREATE INDEX IF NOT EXISTS idx_api_keys_user_id ON api_keys(user_id);
-CREATE INDEX IF NOT EXISTS idx_api_keys_active ON api_keys(is_active);
-
-CREATE TABLE IF NOT EXISTS user_credentials (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  user_id INTEGER NOT NULL,
-  credential_name TEXT NOT NULL,
-  credential_type TEXT NOT NULL,
-  credential_value TEXT NOT NULL,
-  description TEXT,
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-  is_active BOOLEAN DEFAULT 1,
-  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-);
-
-CREATE INDEX IF NOT EXISTS idx_user_credentials_user_id ON user_credentials(user_id);
-CREATE INDEX IF NOT EXISTS idx_user_credentials_type ON user_credentials(credential_type);
-CREATE INDEX IF NOT EXISTS idx_user_credentials_active ON user_credentials(is_active);
-
-${USER_NOTIFICATION_PREFERENCES_TABLE_SQL}
-
-${VAPID_KEYS_TABLE_SQL}
-
-${PUSH_SUBSCRIPTIONS_TABLE_SQL}
-
-${SESSION_NAMES_TABLE_SQL}
-
-${SESSION_NAMES_LOOKUP_INDEX_SQL}
-
-${APP_CONFIG_TABLE_SQL}
-`;
diff --git a/server/gemini-cli.js b/server/gemini-cli.js
index 2e68a938..ee1fd845 100644
--- a/server/gemini-cli.js
+++ b/server/gemini-cli.js
@@ -1,21 +1,131 @@
 import { spawn } from 'child_process';
+import { promises as fs } from 'fs';
+import os from 'os';
+import path from 'path';
+
 import crossSpawn from 'cross-spawn';
 
-// Use cross-spawn on Windows for correct .cmd resolution (same pattern as cursor-cli.js)
-const spawnFunction = process.platform === 'win32' ? crossSpawn : spawn;
-import { promises as fs } from 'fs';
-import path from 'path';
-import os from 'os';
 import sessionManager from './sessionManager.js';
 import GeminiResponseHandler from './gemini-response-handler.js';
 import { notifyRunFailed, notifyRunStopped } from './services/notification-orchestrator.js';
 import { providerAuthService } from './modules/providers/services/provider-auth.service.js';
+import { providerModelsService } from './modules/providers/services/provider-models.service.js';
 import { createNormalizedMessage } from './shared/utils.js';
 
+// Use cross-spawn on Windows for correct .cmd resolution (same pattern as cursor-cli.js)
+const spawnFunction = process.platform === 'win32' ? crossSpawn : spawn;
+
 let activeGeminiProcesses = new Map(); // Track active processes by session ID
 
+function mapGeminiExitCodeToMessage(exitCode) {
+    switch (exitCode) {
+        case 42:
+            return 'Gemini rejected the request input (exit code 42).';
+        case 44:
+            return 'Gemini sandbox error (exit code 44). Check local sandbox/container settings.';
+        case 52:
+            return 'Gemini configuration error (exit code 52). Check your Gemini settings files for invalid JSON/config.';
+        case 53:
+            return 'Gemini conversation turn limit reached (exit code 53). Start a new Gemini session.';
+        default:
+            return null;
+    }
+}
+
+const GEMINI_AUTH_ENV_KEYS = [
+    'GEMINI_API_KEY',
+    'GOOGLE_API_KEY',
+    'GOOGLE_CLOUD_PROJECT',
+    'GOOGLE_CLOUD_PROJECT_ID',
+    'GOOGLE_CLOUD_LOCATION',
+    'GOOGLE_APPLICATION_CREDENTIALS'
+];
+
+function parseEnvFileContent(content) {
+    const parsed = {};
+
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#')) {
+            continue;
+        }
+
+        const exportPrefix = 'export ';
+        const normalizedLine = line.startsWith(exportPrefix) ? line.slice(exportPrefix.length).trim() : line;
+        const separatorIndex = normalizedLine.indexOf('=');
+
+        if (separatorIndex <= 0) {
+            continue;
+        }
+
+        const key = normalizedLine.slice(0, separatorIndex).trim();
+        if (!key) {
+            continue;
+        }
+
+        let value = normalizedLine.slice(separatorIndex + 1).trim();
+        const hasDoubleQuotes = value.startsWith('"') && value.endsWith('"');
+        const hasSingleQuotes = value.startsWith('\'') && value.endsWith('\'');
+
+        if (hasDoubleQuotes || hasSingleQuotes) {
+            value = value.slice(1, -1);
+        } else {
+            // Support inline comments in unquoted values: KEY=value # comment
+            value = value.replace(/\s+#.*$/, '').trim();
+        }
+
+        parsed[key] = value;
+    }
+
+    return parsed;
+}
+
+async function loadGeminiUserLevelEnv() {
+    const geminiCliHome = (process.env.GEMINI_CLI_HOME || '').trim() || os.homedir();
+    const envCandidates = [
+        path.join(geminiCliHome, '.gemini', '.env'),
+        path.join(geminiCliHome, '.env')
+    ];
+
+    for (const envPath of envCandidates) {
+        try {
+            await fs.access(envPath);
+            const content = await fs.readFile(envPath, 'utf8');
+            return parseEnvFileContent(content);
+        } catch {
+            // Keep scanning for the next candidate.
+        }
+    }
+
+    return {};
+}
+
+async function buildGeminiProcessEnv() {
+    const processEnv = { ...process.env };
+    if (processEnv.GEMINI_API_KEY || processEnv.GOOGLE_API_KEY || processEnv.GOOGLE_APPLICATION_CREDENTIALS) {
+        return processEnv;
+    }
+
+    // Gemini CLI docs recommend ~/.gemini/.env for persistent headless auth settings.
+    // When the server process was launched without shell profile variables, we still
+    // want the spawned CLI process to inherit those user-level credentials.
+    const userEnv = await loadGeminiUserLevelEnv();
+    for (const key of GEMINI_AUTH_ENV_KEYS) {
+        if (!processEnv[key] && userEnv[key]) {
+            processEnv[key] = userEnv[key];
+        }
+    }
+
+    return processEnv;
+}
+
 async function spawnGemini(command, options = {}, ws) {
     const { sessionId, projectPath, cwd, toolsSettings, permissionMode, images, sessionSummary } = options;
+    const resolvedModel = await providerModelsService.resolveResumeModel(
+        'gemini',
+        sessionId,
+        options.model
+    );
     let capturedSessionId = sessionId; // Track session ID throughout the process
     let sessionCreatedSent = false; // Track if we've already sent session-created event
     let assistantBlocks = []; // Accumulate the full response blocks including tools
@@ -100,6 +210,11 @@ async function spawnGemini(command, options = {}, ws) {
         args.push('--debug');
     }
 
+    // This integration runs Gemini in headless mode and cannot answer trust prompts.
+    // Skip folder-trust interactivity so authenticated runs don't fail with
+    // FatalUntrustedWorkspaceError in previously unseen directories.
+    args.push('--skip-trust');
+
     // Add MCP config flag only if MCP servers are configured
     try {
         const geminiConfigPath = path.join(os.homedir(), '.gemini.json');
@@ -135,7 +250,7 @@ async function spawnGemini(command, options = {}, ws) {
     }
 
     // Add model for all sessions (both new and resumed)
-    let modelToUse = options.model || 'gemini-2.5-flash';
+    let modelToUse = resolvedModel || 'gemini-2.5-flash';
     args.push('--model', modelToUse);
     args.push('--output-format', 'stream-json');
 
@@ -154,9 +269,6 @@ async function spawnGemini(command, options = {}, ws) {
 
     // Try to find gemini in PATH first, then fall back to environment variable
     const geminiPath = process.env.GEMINI_PATH || 'gemini';
-    console.log('Spawning Gemini CLI:', geminiPath, args.join(' '));
-    console.log('Working directory:', workingDir);
-
     let spawnCmd = geminiPath;
     let spawnArgs = args;
 
@@ -168,11 +280,13 @@ async function spawnGemini(command, options = {}, ws) {
         spawnArgs = ['-c', 'exec "$0" "$@"', geminiPath, ...args];
     }
 
+    const spawnEnv = await buildGeminiProcessEnv();
+
     return new Promise((resolve, reject) => {
         const geminiProcess = spawnFunction(spawnCmd, spawnArgs, {
             cwd: workingDir,
             stdio: ['pipe', 'pipe', 'pipe'],
-            env: { ...process.env } // Inherit all environment variables
+            env: spawnEnv
         });
         let terminalNotificationSent = false;
         let terminalFailureReason = null;
@@ -276,12 +390,43 @@ async function spawnGemini(command, options = {}, ws) {
                     }
                 },
                 onInit: (event) => {
-                    if (capturedSessionId) {
-                        const sess = sessionManager.getSession(capturedSessionId);
-                        if (sess && !sess.cliSessionId) {
-                            sess.cliSessionId = event.session_id;
-                            sessionManager.saveSession(capturedSessionId);
+                    const discoveredSessionId = event?.session_id;
+                    if (!discoveredSessionId) {
+                        return;
+                    }
+
+                    // New Gemini sessions announce their canonical ID asynchronously via the
+                    // initial `init` stream event. Avoid synthetic IDs and only register
+                    // the session once that real ID is known (same model used by Claude/Codex).
+                    if (!capturedSessionId) {
+                        capturedSessionId = discoveredSessionId;
+
+                        sessionManager.createSession(capturedSessionId, cwd || process.cwd());
+                        if (command) {
+                            sessionManager.addMessage(capturedSessionId, 'user', command);
                         }
+
+                        if (processKey !== capturedSessionId) {
+                            activeGeminiProcesses.delete(processKey);
+                            activeGeminiProcesses.set(capturedSessionId, geminiProcess);
+                        }
+
+                        geminiProcess.sessionId = capturedSessionId;
+
+                        if (ws.setSessionId && typeof ws.setSessionId === 'function') {
+                            ws.setSessionId(capturedSessionId);
+                        }
+
+                        if (!sessionId && !sessionCreatedSent) {
+                            sessionCreatedSent = true;
+                            ws.send(createNormalizedMessage({ kind: 'session_created', newSessionId: capturedSessionId, sessionId: capturedSessionId, provider: 'gemini' }));
+                        }
+                    }
+
+                    const sess = sessionManager.getSession(capturedSessionId);
+                    if (sess && !sess.cliSessionId) {
+                        sess.cliSessionId = discoveredSessionId;
+                        sessionManager.saveSession(capturedSessionId);
                     }
                 }
             });
@@ -292,30 +437,6 @@ async function spawnGemini(command, options = {}, ws) {
             const rawOutput = data.toString();
             startTimeout(); // Re-arm the timeout
 
-            // For new sessions, create a session ID FIRST
-            if (!sessionId && !sessionCreatedSent && !capturedSessionId) {
-                capturedSessionId = `gemini_${Date.now()}`;
-                sessionCreatedSent = true;
-
-                // Create session in session manager
-                sessionManager.createSession(capturedSessionId, cwd || process.cwd());
-
-                // Save the user message now that we have a session ID
-                if (command) {
-                    sessionManager.addMessage(capturedSessionId, 'user', command);
-                }
-
-                // Update process key with captured session ID
-                if (processKey !== capturedSessionId) {
-                    activeGeminiProcesses.delete(processKey);
-                    activeGeminiProcesses.set(capturedSessionId, geminiProcess);
-                }
-
-                ws.setSessionId && typeof ws.setSessionId === 'function' && ws.setSessionId(capturedSessionId);
-
-                ws.send(createNormalizedMessage({ kind: 'session_created', newSessionId: capturedSessionId, sessionId: capturedSessionId, provider: 'gemini' }));
-            }
-
             if (responseHandler) {
                 responseHandler.processData(rawOutput);
             } else if (rawOutput) {
@@ -381,12 +502,38 @@ async function spawnGemini(command, options = {}, ws) {
                 notifyTerminalState({ code });
                 resolve();
             } else {
-                // code 127 = shell "command not found" — check installation
+                const socketSessionId = typeof ws.getSessionId === 'function' ? ws.getSessionId() : finalSessionId;
+
+                // code 127 = shell "command not found" - check installation
                 if (code === 127) {
                     const installed = await providerAuthService.isProviderInstalled('gemini');
                     if (!installed) {
-                        const socketSessionId = typeof ws.getSessionId === 'function' ? ws.getSessionId() : finalSessionId;
-                        ws.send(createNormalizedMessage({ kind: 'error', content: 'Gemini CLI is not installed. Please install it first: https://github.com/google-gemini/gemini-cli', sessionId: socketSessionId, provider: 'gemini' }));
+                        terminalFailureReason = 'Gemini CLI is not installed. Please install it first: https://github.com/google-gemini/gemini-cli';
+                        ws.send(createNormalizedMessage({ kind: 'error', content: terminalFailureReason, sessionId: socketSessionId, provider: 'gemini' }));
+                    }
+                } else if (code === 41) {
+                    // Gemini CLI documents exit code 41 as FatalAuthenticationError.
+                    // Surface an actionable auth error instead of a generic exit-code message.
+                    let authErrorSuffix = '';
+                    try {
+                        const authStatus = await providerAuthService.getProviderAuthStatus('gemini');
+                        if (!authStatus?.authenticated && authStatus?.error) {
+                            authErrorSuffix = ` Details: ${authStatus.error}`;
+                        }
+                    } catch {
+                        // Keep base remediation text when auth status lookup fails.
+                    }
+
+                    terminalFailureReason =
+                        'Gemini authentication failed (exit code 41). '
+                        + 'Run `gemini` in a terminal to choose an auth method, or configure a valid `GEMINI_API_KEY`.'
+                        + authErrorSuffix;
+                    ws.send(createNormalizedMessage({ kind: 'error', content: terminalFailureReason, sessionId: socketSessionId, provider: 'gemini' }));
+                } else {
+                    const mappedError = mapGeminiExitCodeToMessage(code);
+                    if (mappedError) {
+                        terminalFailureReason = mappedError;
+                        ws.send(createNormalizedMessage({ kind: 'error', content: terminalFailureReason, sessionId: socketSessionId, provider: 'gemini' }));
                     }
                 }
 
@@ -394,7 +541,14 @@ async function spawnGemini(command, options = {}, ws) {
                     code,
                     error: code === null ? 'Gemini CLI process was terminated or timed out' : null
                 });
-                reject(new Error(code === null ? 'Gemini CLI process was terminated or timed out' : `Gemini CLI exited with code ${code}`));
+                reject(
+                    new Error(
+                        terminalFailureReason
+                        || (code === null
+                            ? 'Gemini CLI process was terminated or timed out'
+                            : `Gemini CLI exited with code ${code}`)
+                    )
+                );
             }
         });
 
diff --git a/server/gemini-response-handler.js b/server/gemini-response-handler.js
index b0a17485..6f314443 100644
--- a/server/gemini-response-handler.js
+++ b/server/gemini-response-handler.js
@@ -1,5 +1,32 @@
 // Gemini Response Handler - JSON Stream processing
 import { sessionsService } from './modules/providers/services/sessions.service.js';
+import { createNormalizedMessage } from './shared/utils.js';
+
+function buildGeminiTokenBudget(tokens) {
+  if (!tokens || typeof tokens !== 'object') {
+    return null;
+  }
+
+  const parsedInputTokens = Number(tokens.input);
+  const parsedOutputTokens = Number(tokens.output);
+  const inputTokens = Number.isFinite(parsedInputTokens) ? parsedInputTokens : 0;
+  const outputTokens = Number.isFinite(parsedOutputTokens) ? parsedOutputTokens : 0;
+  const parsedUsed = Number(tokens.total);
+  const used = Number.isFinite(parsedUsed) ? parsedUsed : inputTokens + outputTokens;
+  if (!Number.isFinite(used) || used <= 0) {
+    return null;
+  }
+
+  return {
+    used,
+    inputTokens,
+    outputTokens,
+    breakdown: {
+      input: inputTokens,
+      output: outputTokens,
+    },
+  };
+}
 
 class GeminiResponseHandler {
   constructor(ws, options = {}) {
@@ -60,6 +87,17 @@ class GeminiResponseHandler {
     for (const msg of normalized) {
       this.ws.send(msg);
     }
+
+    const tokenBudget = buildGeminiTokenBudget(event.tokens);
+    if (tokenBudget) {
+      this.ws.send(createNormalizedMessage({
+        kind: 'status',
+        text: 'token_budget',
+        tokenBudget,
+        sessionId: sid,
+        provider: 'gemini',
+      }));
+    }
   }
 
   forceFlush() {
diff --git a/server/index.js b/server/index.js
index 62d85130..a986148e 100755
--- a/server/index.js
+++ b/server/index.js
@@ -1,39 +1,64 @@
 #!/usr/bin/env node
 // Load environment variables before other imports execute
 import './load-env.js';
-import fs from 'fs';
+import fs, { promises as fsPromises } from 'fs';
 import path from 'path';
-import { findAppRoot, getModuleDir } from './utils/runtime-paths.js';
-
-import { AppError, createNormalizedMessage } from '@/shared/utils.js';
-
-
-const __dirname = getModuleDir(import.meta.url);
-// The server source runs from /server, while the compiled output runs from /dist-server/server.
-// Resolving the app root once keeps every repo-level lookup below aligned across both layouts.
-const APP_ROOT = findAppRoot(__dirname);
-const installMode = fs.existsSync(path.join(APP_ROOT, '.git')) ? 'git' : 'npm';
-
-import { c } from './utils/colors.js';
-
-console.log('SERVER_PORT from env:', process.env.SERVER_PORT);
-
-import express from 'express';
-import { WebSocketServer, WebSocket } from 'ws';
 import os from 'os';
 import http from 'http';
-import cors from 'cors';
-import { promises as fsPromises } from 'fs';
 import { spawn } from 'child_process';
-import pty from 'node-pty';
-import mime from 'mime-types';
 
-import { getProjects, getSessions, renameProject, deleteSession, deleteProject, extractProjectDirectory, clearProjectDirectoryCache, searchConversations } from './projects.js';
-import { queryClaudeSDK, abortClaudeSDKSession, isClaudeSDKSessionActive, getActiveClaudeSDKSessions, resolveToolApproval, getPendingApprovalsForSession, reconnectSessionWriter } from './claude-sdk.js';
-import { spawnCursor, abortCursorSession, isCursorSessionActive, getActiveCursorSessions } from './cursor-cli.js';
-import { queryCodex, abortCodexSession, isCodexSessionActive, getActiveCodexSessions } from './openai-codex.js';
-import { spawnGemini, abortGeminiSession, isGeminiSessionActive, getActiveGeminiSessions } from './gemini-cli.js';
+import express from 'express';
+import cors from 'cors';
+import mime from 'mime-types';
+import Database from 'better-sqlite3';
+
+import { AppError, WORKSPACES_ROOT, getOpenCodeDatabasePath, validateWorkspacePath } from '@/shared/utils.js';
+import { closeSessionsWatcher, initializeSessionsWatcher } from '@/modules/providers/index.js';
+import { createWebSocketServer } from '@/modules/websocket/index.js';
+
+import { getConnectableHost } from '../shared/networkHosts.js';
+
+import { findAppRoot, getModuleDir } from './utils/runtime-paths.js';
+import {
+    queryClaudeSDK,
+    abortClaudeSDKSession,
+    isClaudeSDKSessionActive,
+    getActiveClaudeSDKSessions,
+    resolveToolApproval,
+    getPendingApprovalsForSession,
+    reconnectSessionWriter,
+} from './claude-sdk.js';
+import {
+    spawnCursor,
+    abortCursorSession,
+    isCursorSessionActive,
+    getActiveCursorSessions,
+} from './cursor-cli.js';
+import {
+    queryCodex,
+    abortCodexSession,
+    isCodexSessionActive,
+    getActiveCodexSessions,
+} from './openai-codex.js';
+import {
+    spawnGemini,
+    abortGeminiSession,
+    isGeminiSessionActive,
+    getActiveGeminiSessions,
+} from './gemini-cli.js';
+import {
+    spawnOpenCode,
+    abortOpenCodeSession,
+    isOpenCodeSessionActive,
+    getActiveOpenCodeSessions,
+} from './opencode-cli.js';
 import sessionManager from './sessionManager.js';
+import {
+    stripAnsiSequences,
+    normalizeDetectedUrl,
+    extractUrlsFromText,
+    shouldAutoOpenUrlFromOutput,
+} from './utils/url-detection.js';
 import gitRoutes from './routes/git.js';
 import authRoutes from './routes/auth.js';
 import cursorRoutes from './routes/cursor.js';
@@ -42,210 +67,68 @@ import mcpUtilsRoutes from './routes/mcp-utils.js';
 import commandsRoutes from './routes/commands.js';
 import settingsRoutes from './routes/settings.js';
 import agentRoutes from './routes/agent.js';
-import projectsRoutes, { WORKSPACES_ROOT, validateWorkspacePath } from './routes/projects.js';
+import projectModuleRoutes from './modules/projects/projects.routes.js';
 import userRoutes from './routes/user.js';
-import codexRoutes from './routes/codex.js';
 import geminiRoutes from './routes/gemini.js';
 import pluginsRoutes from './routes/plugins.js';
-import messagesRoutes from './routes/messages.js';
 import providerRoutes from './modules/providers/provider.routes.js';
 import { startEnabledPluginServers, stopAllPlugins, getPluginPort } from './utils/plugin-process-manager.js';
-import { initializeDatabase, sessionNamesDb, applyCustomSessionNames } from './database/db.js';
+import { initializeDatabase, projectsDb, sessionsDb } from './modules/database/index.js';
 import { configureWebPush } from './services/vapid-keys.js';
 import { validateApiKey, authenticateToken, authenticateWebSocket } from './middleware/auth.js';
 import { IS_PLATFORM } from './constants/config.js';
-import { getConnectableHost } from '../shared/networkHosts.js';
+import { c } from './utils/colors.js';
 
-const VALID_PROVIDERS = ['claude', 'codex', 'cursor', 'gemini'];
-
-// File system watchers for provider project/session folders
-const PROVIDER_WATCH_PATHS = [
-    { provider: 'claude', rootPath: path.join(os.homedir(), '.claude', 'projects') },
-    { provider: 'cursor', rootPath: path.join(os.homedir(), '.cursor', 'chats') },
-    { provider: 'codex', rootPath: path.join(os.homedir(), '.codex', 'sessions') },
-    { provider: 'gemini', rootPath: path.join(os.homedir(), '.gemini', 'projects') },
-    { provider: 'gemini_sessions', rootPath: path.join(os.homedir(), '.gemini', 'sessions') }
-];
-const WATCHER_IGNORED_PATTERNS = [
-    '**/node_modules/**',
-    '**/.git/**',
-    '**/dist/**',
-    '**/build/**',
-    '**/*.tmp',
-    '**/*.swp',
-    '**/.DS_Store'
-];
-const WATCHER_DEBOUNCE_MS = 300;
-let projectsWatchers = [];
-let projectsWatcherDebounceTimer = null;
-const connectedClients = new Set();
-let isGetProjectsRunning = false; // Flag to prevent reentrant calls
-
-// Broadcast progress to all connected WebSocket clients
-function broadcastProgress(progress) {
-    const message = JSON.stringify({
-        type: 'loading_progress',
-        ...progress
-    });
-    connectedClients.forEach(client => {
-        if (client.readyState === WebSocket.OPEN) {
-            client.send(message);
-        }
-    });
-}
-
-// Setup file system watchers for Claude, Cursor, and Codex project/session folders
-async function setupProjectsWatcher() {
-    const chokidar = (await import('chokidar')).default;
-
-    if (projectsWatcherDebounceTimer) {
-        clearTimeout(projectsWatcherDebounceTimer);
-        projectsWatcherDebounceTimer = null;
-    }
-
-    await Promise.all(
-        projectsWatchers.map(async (watcher) => {
-            try {
-                await watcher.close();
-            } catch (error) {
-                console.error('[WARN] Failed to close watcher:', error);
-            }
-        })
-    );
-    projectsWatchers = [];
-
-    const debouncedUpdate = (eventType, filePath, provider, rootPath) => {
-        if (projectsWatcherDebounceTimer) {
-            clearTimeout(projectsWatcherDebounceTimer);
-        }
-
-        projectsWatcherDebounceTimer = setTimeout(async () => {
-            // Prevent reentrant calls
-            if (isGetProjectsRunning) {
-                return;
-            }
-
-            try {
-                isGetProjectsRunning = true;
-
-                // Clear project directory cache when files change
-                clearProjectDirectoryCache();
-
-                // Get updated projects list
-                const updatedProjects = await getProjects(broadcastProgress);
-
-                // Notify all connected clients about the project changes
-                const updateMessage = JSON.stringify({
-                    type: 'projects_updated',
-                    projects: updatedProjects,
-                    timestamp: new Date().toISOString(),
-                    changeType: eventType,
-                    changedFile: path.relative(rootPath, filePath),
-                    watchProvider: provider
-                });
-
-                connectedClients.forEach(client => {
-                    if (client.readyState === WebSocket.OPEN) {
-                        client.send(updateMessage);
-                    }
-                });
-
-            } catch (error) {
-                console.error('[ERROR] Error handling project changes:', error);
-            } finally {
-                isGetProjectsRunning = false;
-            }
-        }, WATCHER_DEBOUNCE_MS);
-    };
-
-    for (const { provider, rootPath } of PROVIDER_WATCH_PATHS) {
-        try {
-            // chokidar v4 emits ENOENT via the "error" event for missing roots and will not auto-recover.
-            // Ensure provider folders exist before creating the watcher so watching stays active.
-            await fsPromises.mkdir(rootPath, { recursive: true });
-
-            // Initialize chokidar watcher with optimized settings
-            const watcher = chokidar.watch(rootPath, {
-                ignored: WATCHER_IGNORED_PATTERNS,
-                persistent: true,
-                ignoreInitial: true, // Don't fire events for existing files on startup
-                followSymlinks: false,
-                depth: 10, // Reasonable depth limit
-                awaitWriteFinish: {
-                    stabilityThreshold: 100, // Wait 100ms for file to stabilize
-                    pollInterval: 50
-                }
-            });
-
-            // Set up event listeners
-            watcher
-                .on('add', (filePath) => debouncedUpdate('add', filePath, provider, rootPath))
-                .on('change', (filePath) => debouncedUpdate('change', filePath, provider, rootPath))
-                .on('unlink', (filePath) => debouncedUpdate('unlink', filePath, provider, rootPath))
-                .on('addDir', (dirPath) => debouncedUpdate('addDir', dirPath, provider, rootPath))
-                .on('unlinkDir', (dirPath) => debouncedUpdate('unlinkDir', dirPath, provider, rootPath))
-                .on('error', (error) => {
-                    console.error(`[ERROR] ${provider} watcher error:`, error);
-                })
-                .on('ready', () => {
-                });
-
-            projectsWatchers.push(watcher);
-        } catch (error) {
-            console.error(`[ERROR] Failed to setup ${provider} watcher for ${rootPath}:`, error);
-        }
-    }
-
-    if (projectsWatchers.length === 0) {
-        console.error('[ERROR] Failed to setup any provider watchers');
-    }
-}
+const __dirname = getModuleDir(import.meta.url);
+// The server source runs from /server, while the compiled output runs from /dist-server/server.
+// Resolving the app root once keeps every repo-level lookup below aligned across both layouts.
+const APP_ROOT = findAppRoot(__dirname);
+const installMode = fs.existsSync(path.join(APP_ROOT, '.git')) ? 'git' : 'npm';
 
+console.log('SERVER_PORT from env:', process.env.SERVER_PORT);
 
 const app = express();
 const server = http.createServer(app);
 
-const ptySessionsMap = new Map();
-const PTY_SESSION_TIMEOUT = 30 * 60 * 1000;
-const SHELL_URL_PARSE_BUFFER_LIMIT = 32768;
-import { stripAnsiSequences, normalizeDetectedUrl, extractUrlsFromText, shouldAutoOpenUrlFromOutput } from './utils/url-detection.js';
-
-// Single WebSocket server that handles both paths
-const wss = new WebSocketServer({
-    server,
-    verifyClient: (info) => {
-        console.log('WebSocket connection attempt to:', info.req.url);
-
-        // Platform mode: always allow connection
-        if (IS_PLATFORM) {
-            const user = authenticateWebSocket(null); // Will return first user
-            if (!user) {
-                console.log('[WARN] Platform mode: No user found in database');
-                return false;
-            }
-            info.req.user = user;
-            console.log('[OK] Platform mode WebSocket authenticated for user:', user.username);
-            return true;
-        }
-
-        // Normal mode: verify token
-        // Extract token from query parameters or headers
-        const url = new URL(info.req.url, 'http://localhost');
-        const token = url.searchParams.get('token') ||
-            info.req.headers.authorization?.split(' ')[1];
-
-        // Verify token
-        const user = authenticateWebSocket(token);
-        if (!user) {
-            console.log('[WARN] WebSocket authentication failed');
-            return false;
-        }
-
-        // Store user info in the request for later use
-        info.req.user = user;
-        console.log('[OK] WebSocket authenticated for user:', user.username);
-        return true;
-    }
+// Single WebSocket server that handles chat, shell, and plugin proxy paths.
+const wss = createWebSocketServer(server, {
+    verifyClient: {
+        isPlatform: IS_PLATFORM,
+        authenticateWebSocket,
+    },
+    chat: {
+        queryClaudeSDK,
+        spawnCursor,
+        queryCodex,
+        spawnGemini,
+        spawnOpenCode,
+        abortClaudeSDKSession,
+        abortCursorSession,
+        abortCodexSession,
+        abortGeminiSession,
+        abortOpenCodeSession,
+        resolveToolApproval,
+        isClaudeSDKSessionActive,
+        isCursorSessionActive,
+        isCodexSessionActive,
+        isGeminiSessionActive,
+        isOpenCodeSessionActive,
+        reconnectSessionWriter,
+        getPendingApprovalsForSession,
+        getActiveClaudeSDKSessions,
+        getActiveCursorSessions,
+        getActiveCodexSessions,
+        getActiveGeminiSessions,
+        getActiveOpenCodeSessions,
+    },
+    shell: {
+        getSessionById: (sessionId) => sessionManager.getSession(sessionId),
+        stripAnsiSequences,
+        normalizeDetectedUrl,
+        extractUrlsFromText,
+        shouldAutoOpenUrlFromOutput,
+    },
+    getPluginPort,
 });
 
 // Make WebSocket server available to routes
@@ -281,7 +164,7 @@ app.use('/api', validateApiKey);
 app.use('/api/auth', authRoutes);
 
 // Projects API Routes (protected)
-app.use('/api/projects', authenticateToken, projectsRoutes);
+app.use('/api/projects', authenticateToken, projectModuleRoutes);
 
 // Git API Routes (protected)
 app.use('/api/git', authenticateToken, gitRoutes);
@@ -304,18 +187,12 @@ app.use('/api/settings', authenticateToken, settingsRoutes);
 // User API Routes (protected)
 app.use('/api/user', authenticateToken, userRoutes);
 
-// Codex API Routes (protected)
-app.use('/api/codex', authenticateToken, codexRoutes);
-
 // Gemini API Routes (protected)
 app.use('/api/gemini', authenticateToken, geminiRoutes);
 
 // Plugins API Routes (protected)
 app.use('/api/plugins', authenticateToken, pluginsRoutes);
 
-// Unified session messages route (protected)
-app.use('/api/sessions', authenticateToken, messagesRoutes);
-
 // Unified provider MCP routes (protected)
 app.use('/api/providers', authenticateToken, providerRoutes);
 
@@ -419,138 +296,6 @@ app.post('/api/system/update', authenticateToken, async (req, res) => {
     }
 });
 
-app.get('/api/projects', authenticateToken, async (req, res) => {
-    try {
-        const projects = await getProjects(broadcastProgress);
-        res.json(projects);
-    } catch (error) {
-        res.status(500).json({ error: error.message });
-    }
-});
-
-app.get('/api/projects/:projectName/sessions', authenticateToken, async (req, res) => {
-    try {
-        const { limit = 5, offset = 0 } = req.query;
-        const result = await getSessions(req.params.projectName, parseInt(limit), parseInt(offset));
-        applyCustomSessionNames(result.sessions, 'claude');
-        res.json(result);
-    } catch (error) {
-        res.status(500).json({ error: error.message });
-    }
-});
-
-// Rename project endpoint
-app.put('/api/projects/:projectName/rename', authenticateToken, async (req, res) => {
-    try {
-        const { displayName } = req.body;
-        await renameProject(req.params.projectName, displayName);
-        res.json({ success: true });
-    } catch (error) {
-        res.status(500).json({ error: error.message });
-    }
-});
-
-// Delete session endpoint
-app.delete('/api/projects/:projectName/sessions/:sessionId', authenticateToken, async (req, res) => {
-    try {
-        const { projectName, sessionId } = req.params;
-        console.log(`[API] Deleting session: ${sessionId} from project: ${projectName}`);
-        await deleteSession(projectName, sessionId);
-        sessionNamesDb.deleteName(sessionId, 'claude');
-        console.log(`[API] Session ${sessionId} deleted successfully`);
-        res.json({ success: true });
-    } catch (error) {
-        console.error(`[API] Error deleting session ${req.params.sessionId}:`, error);
-        res.status(500).json({ error: error.message });
-    }
-});
-
-// Rename session endpoint
-app.put('/api/sessions/:sessionId/rename', authenticateToken, async (req, res) => {
-    try {
-        const { sessionId } = req.params;
-        const safeSessionId = String(sessionId).replace(/[^a-zA-Z0-9._-]/g, '');
-        if (!safeSessionId || safeSessionId !== String(sessionId)) {
-            return res.status(400).json({ error: 'Invalid sessionId' });
-        }
-        const { summary, provider } = req.body;
-        if (!summary || typeof summary !== 'string' || summary.trim() === '') {
-            return res.status(400).json({ error: 'Summary is required' });
-        }
-        if (summary.trim().length > 500) {
-            return res.status(400).json({ error: 'Summary must not exceed 500 characters' });
-        }
-        if (!provider || !VALID_PROVIDERS.includes(provider)) {
-            return res.status(400).json({ error: `Provider must be one of: ${VALID_PROVIDERS.join(', ')}` });
-        }
-        sessionNamesDb.setName(safeSessionId, provider, summary.trim());
-        res.json({ success: true });
-    } catch (error) {
-        console.error(`[API] Error renaming session ${req.params.sessionId}:`, error);
-        res.status(500).json({ error: error.message });
-    }
-});
-
-// Delete project endpoint
-// force=true to allow removal even when sessions exist
-// deleteData=true to also delete session/memory files on disk (destructive)
-app.delete('/api/projects/:projectName', authenticateToken, async (req, res) => {
-    try {
-        const { projectName } = req.params;
-        const force = req.query.force === 'true';
-        const deleteData = req.query.deleteData === 'true';
-        await deleteProject(projectName, force, deleteData);
-        res.json({ success: true });
-    } catch (error) {
-        res.status(500).json({ error: error.message });
-    }
-});
-
-// Search conversations content (SSE streaming)
-app.get('/api/search/conversations', authenticateToken, async (req, res) => {
-    const query = typeof req.query.q === 'string' ? req.query.q.trim() : '';
-    const parsedLimit = Number.parseInt(String(req.query.limit), 10);
-    const limit = Number.isNaN(parsedLimit) ? 50 : Math.max(1, Math.min(parsedLimit, 100));
-
-    if (query.length < 2) {
-        return res.status(400).json({ error: 'Query must be at least 2 characters' });
-    }
-
-    res.writeHead(200, {
-        'Content-Type': 'text/event-stream',
-        'Cache-Control': 'no-cache',
-        'Connection': 'keep-alive',
-        'X-Accel-Buffering': 'no',
-    });
-
-    let closed = false;
-    const abortController = new AbortController();
-    req.on('close', () => { closed = true; abortController.abort(); });
-
-    try {
-        await searchConversations(query, limit, ({ projectResult, totalMatches, scannedProjects, totalProjects }) => {
-            if (closed) return;
-            if (projectResult) {
-                res.write(`event: result\ndata: ${JSON.stringify({ projectResult, totalMatches, scannedProjects, totalProjects })}\n\n`);
-            } else {
-                res.write(`event: progress\ndata: ${JSON.stringify({ totalMatches, scannedProjects, totalProjects })}\n\n`);
-            }
-        }, abortController.signal);
-        if (!closed) {
-            res.write(`event: done\ndata: {}\n\n`);
-        }
-    } catch (error) {
-        console.error('Error searching conversations:', error);
-        if (!closed) {
-            res.write(`event: error\ndata: ${JSON.stringify({ error: 'Search failed' })}\n\n`);
-        }
-    } finally {
-        if (!closed) {
-            res.end();
-        }
-    }
-});
-
 const expandWorkspacePath = (inputPath) => {
     if (!inputPath) return inputPath;
     if (inputPath === '~') {
@@ -684,9 +429,9 @@ app.post('/api/create-folder', authenticateToken, async (req, res) => {
 });
 
 // Read file content endpoint
-app.get('/api/projects/:projectName/file', authenticateToken, async (req, res) => {
+app.get('/api/projects/:projectId/file', authenticateToken, async (req, res) => {
     try {
-        const { projectName } = req.params;
+        const { projectId } = req.params;
         const { filePath } = req.query;
 
 
@@ -695,7 +440,9 @@ app.get('/api/projects/:projectName/file', authenticateToken, async (req, res) =
             return res.status(400).json({ error: 'Invalid file path' });
         }
 
-        const projectRoot = await extractProjectDirectory(projectName).catch(() => null);
+        // Resolve the absolute project root via the DB-backed helper; the
+        // caller passes the DB-assigned `projectId`, not a folder name.
+        const projectRoot = await projectsDb.getProjectPathById(projectId);
         if (!projectRoot) {
             return res.status(404).json({ error: 'Project not found' });
         }
@@ -724,9 +471,9 @@ app.get('/api/projects/:projectName/file', authenticateToken, async (req, res) =
 });
 
 // Serve raw file bytes for previews and downloads.
-app.get('/api/projects/:projectName/files/content', authenticateToken, async (req, res) => {
+app.get('/api/projects/:projectId/files/content', authenticateToken, async (req, res) => {
     try {
-        const { projectName } = req.params;
+        const { projectId } = req.params;
         const { path: filePath } = req.query;
 
 
@@ -735,7 +482,8 @@ app.get('/api/projects/:projectName/files/content', authenticateToken, async (re
             return res.status(400).json({ error: 'Invalid file path' });
         }
 
-        const projectRoot = await extractProjectDirectory(projectName).catch(() => null);
+        // Projects are now addressed by DB `projectId`, resolved to their path here.
+        const projectRoot = await projectsDb.getProjectPathById(projectId);
         if (!projectRoot) {
             return res.status(404).json({ error: 'Project not found' });
         }
@@ -781,9 +529,9 @@ app.get('/api/projects/:projectName/files/content', authenticateToken, async (re
 });
 
 // Save file content endpoint
-app.put('/api/projects/:projectName/file', authenticateToken, async (req, res) => {
+app.put('/api/projects/:projectId/file', authenticateToken, async (req, res) => {
     try {
-        const { projectName } = req.params;
+        const { projectId } = req.params;
         const { filePath, content } = req.body;
 
 
@@ -796,7 +544,8 @@ app.put('/api/projects/:projectName/file', authenticateToken, async (req, res) =
             return res.status(400).json({ error: 'Content is required' });
         }
 
-        const projectRoot = await extractProjectDirectory(projectName).catch(() => null);
+        // Projects are now addressed by DB `projectId`, resolved to their path here.
+        const projectRoot = await projectsDb.getProjectPathById(projectId);
         if (!projectRoot) {
             return res.status(404).json({ error: 'Project not found' });
         }
@@ -830,19 +579,16 @@ app.put('/api/projects/:projectName/file', authenticateToken, async (req, res) =
     }
 });
 
-app.get('/api/projects/:projectName/files', authenticateToken, async (req, res) => {
+app.get('/api/projects/:projectId/files', authenticateToken, async (req, res) => {
     try {
 
         // Using fsPromises from import
 
-        // Use extractProjectDirectory to get the actual project path
-        let actualPath;
-        try {
-            actualPath = await extractProjectDirectory(req.params.projectName);
-        } catch (error) {
-            console.error('Error extracting project directory:', error);
-            // Fallback to simple dash replacement
-            actualPath = req.params.projectName.replace(/-/g, '/');
+        // Resolve the project's absolute path through the DB (projectId is the
+        // primary key of the `projects` table after the identifier migration).
+        const actualPath = await projectsDb.getProjectPathById(req.params.projectId);
+        if (!actualPath) {
+            return res.status(404).json({ error: 'Project not found' });
         }
 
         // Check if path exists
@@ -907,10 +653,10 @@ function validateFilename(name) {
     return { valid: true };
 }
 
-// POST /api/projects/:projectName/files/create - Create new file or directory
-app.post('/api/projects/:projectName/files/create', authenticateToken, async (req, res) => {
+// POST /api/projects/:projectId/files/create - Create new file or directory
+app.post('/api/projects/:projectId/files/create', authenticateToken, async (req, res) => {
     try {
-        const { projectName } = req.params;
+        const { projectId } = req.params;
         const { path: parentPath, type, name } = req.body;
 
         // Validate input
@@ -927,8 +673,8 @@ app.post('/api/projects/:projectName/files/create', authenticateToken, async (re
             return res.status(400).json({ error: nameValidation.error });
         }
 
-        // Get project root
-        const projectRoot = await extractProjectDirectory(projectName).catch(() => null);
+        // Resolve the project directory through the DB using the new projectId.
+        const projectRoot = await projectsDb.getProjectPathById(projectId);
         if (!projectRoot) {
             return res.status(404).json({ error: 'Project not found' });
         }
@@ -984,10 +730,10 @@ app.post('/api/projects/:projectName/files/create', authenticateToken, async (re
     }
 });
 
-// PUT /api/projects/:projectName/files/rename - Rename file or directory
-app.put('/api/projects/:projectName/files/rename', authenticateToken, async (req, res) => {
+// PUT /api/projects/:projectId/files/rename - Rename file or directory
+app.put('/api/projects/:projectId/files/rename', authenticateToken, async (req, res) => {
     try {
-        const { projectName } = req.params;
+        const { projectId } = req.params;
         const { oldPath, newName } = req.body;
 
         // Validate input
@@ -1000,8 +746,8 @@ app.put('/api/projects/:projectName/files/rename', authenticateToken, async (req
             return res.status(400).json({ error: nameValidation.error });
         }
 
-        // Get project root
-        const projectRoot = await extractProjectDirectory(projectName).catch(() => null);
+        // Resolve the project directory through the DB using the new projectId.
+        const projectRoot = await projectsDb.getProjectPathById(projectId);
         if (!projectRoot) {
             return res.status(404).json({ error: 'Project not found' });
         }
@@ -1061,10 +807,10 @@ app.put('/api/projects/:projectName/files/rename', authenticateToken, async (req
     }
 });
 
-// DELETE /api/projects/:projectName/files - Delete file or directory
-app.delete('/api/projects/:projectName/files', authenticateToken, async (req, res) => {
+// DELETE /api/projects/:projectId/files - Delete file or directory
+app.delete('/api/projects/:projectId/files', authenticateToken, async (req, res) => {
     try {
-        const { projectName } = req.params;
+        const { projectId } = req.params;
         const { path: targetPath, type } = req.body;
 
         // Validate input
@@ -1072,8 +818,8 @@ app.delete('/api/projects/:projectName/files', authenticateToken, async (req, re
             return res.status(400).json({ error: 'Path is required' });
         }
 
-        // Get project root
-        const projectRoot = await extractProjectDirectory(projectName).catch(() => null);
+        // Resolve the project directory through the DB using the new projectId.
+        const projectRoot = await projectsDb.getProjectPathById(projectId);
         if (!projectRoot) {
             return res.status(404).json({ error: 'Project not found' });
         }
@@ -1126,7 +872,7 @@ app.delete('/api/projects/:projectName/files', authenticateToken, async (req, re
     }
 });
 
-// POST /api/projects/:projectName/files/upload - Upload files
+// POST /api/projects/:projectId/files/upload - Upload files
 // Dynamic import of multer for file uploads
 const uploadFilesHandler = async (req, res) => {
     // Dynamic import of multer
@@ -1165,7 +911,7 @@ const uploadFilesHandler = async (req, res) => {
         }
 
         try {
-            const { projectName } = req.params;
+            const { projectId } = req.params;
             const { targetPath, relativePaths } = req.body;
 
             // Parse relative paths if provided (for folder uploads)
@@ -1179,7 +925,7 @@ const uploadFilesHandler = async (req, res) => {
             }
 
             console.log('[DEBUG] File upload request:', {
-                projectName,
+                projectId,
                 targetPath: JSON.stringify(targetPath),
                 targetPathType: typeof targetPath,
                 filesCount: req.files?.length,
@@ -1190,8 +936,8 @@ const uploadFilesHandler = async (req, res) => {
                 return res.status(400).json({ error: 'No files provided' });
             }
 
-            // Get project root
-            const projectRoot = await extractProjectDirectory(projectName).catch(() => null);
+            // Resolve the project directory through the DB using the new projectId.
+            const projectRoot = await projectsDb.getProjectPathById(projectId);
             if (!projectRoot) {
                 return res.status(404).json({ error: 'Project not found' });
             }
@@ -1288,615 +1034,12 @@ const uploadFilesHandler = async (req, res) => {
     });
 };
 
-app.post('/api/projects/:projectName/files/upload', authenticateToken, uploadFilesHandler);
+app.post('/api/projects/:projectId/files/upload', authenticateToken, uploadFilesHandler);
 
-/**
- * Proxy an authenticated client WebSocket to a plugin's internal WS server.
- * Auth is enforced by verifyClient before this function is reached.
- */
-function handlePluginWsProxy(clientWs, pathname) {
-    const pluginName = pathname.replace('/plugin-ws/', '');
-    if (!pluginName || /[^a-zA-Z0-9_-]/.test(pluginName)) {
-        clientWs.close(4400, 'Invalid plugin name');
-        return;
-    }
-
-    const port = getPluginPort(pluginName);
-    if (!port) {
-        clientWs.close(4404, 'Plugin not running');
-        return;
-    }
-
-    const upstream = new WebSocket(`ws://127.0.0.1:${port}/ws`);
-
-    upstream.on('open', () => {
-        console.log(`[Plugins] WS proxy connected to "${pluginName}" on port ${port}`);
-    });
-
-    // Relay messages bidirectionally
-    upstream.on('message', (data) => {
-        if (clientWs.readyState === WebSocket.OPEN) clientWs.send(data);
-    });
-    clientWs.on('message', (data) => {
-        if (upstream.readyState === WebSocket.OPEN) upstream.send(data);
-    });
-
-    // Propagate close in both directions
-    upstream.on('close', () => { if (clientWs.readyState === WebSocket.OPEN) clientWs.close(); });
-    clientWs.on('close', () => { if (upstream.readyState === WebSocket.OPEN) upstream.close(); });
-
-    upstream.on('error', (err) => {
-        console.error(`[Plugins] WS proxy error for "${pluginName}":`, err.message);
-        if (clientWs.readyState === WebSocket.OPEN) clientWs.close(4502, 'Upstream error');
-    });
-    clientWs.on('error', () => {
-        if (upstream.readyState === WebSocket.OPEN) upstream.close();
-    });
-}
-
-// WebSocket connection handler that routes based on URL path
-wss.on('connection', (ws, request) => {
-    const url = request.url;
-    console.log('[INFO] Client connected to:', url);
-
-    // Parse URL to get pathname without query parameters
-    const urlObj = new URL(url, 'http://localhost');
-    const pathname = urlObj.pathname;
-
-    if (pathname === '/shell') {
-        handleShellConnection(ws);
-    } else if (pathname === '/ws') {
-        handleChatConnection(ws, request);
-    } else if (pathname.startsWith('/plugin-ws/')) {
-        handlePluginWsProxy(ws, pathname);
-    } else {
-        console.log('[WARN] Unknown WebSocket path:', pathname);
-        ws.close();
-    }
-});
-
-/**
- * WebSocket Writer - Wrapper for WebSocket to match SSEStreamWriter interface
- *
- * Provider files use `createNormalizedMessage()` from `shared/utils.js` and
- * adapter `normalizeMessage()` to produce unified NormalizedMessage events.
- * The writer simply serialises and sends.
- */
-class WebSocketWriter {
-    constructor(ws, userId = null) {
-        this.ws = ws;
-        this.sessionId = null;
-        this.userId = userId;
-        this.isWebSocketWriter = true;  // Marker for transport detection
-    }
-
-    send(data) {
-        if (this.ws.readyState === 1) { // WebSocket.OPEN
-            this.ws.send(JSON.stringify(data));
-        }
-    }
-
-    updateWebSocket(newRawWs) {
-        this.ws = newRawWs;
-    }
-
-    setSessionId(sessionId) {
-        this.sessionId = sessionId;
-    }
-
-    getSessionId() {
-        return this.sessionId;
-    }
-}
-
-// Handle chat WebSocket connections
-function handleChatConnection(ws, request) {
-    console.log('[INFO] Chat WebSocket connected');
-
-    // Add to connected clients for project updates
-    connectedClients.add(ws);
-
-    // Wrap WebSocket with writer for consistent interface with SSEStreamWriter
-    const writer = new WebSocketWriter(ws, request?.user?.id ?? request?.user?.userId ?? null);
-
-    ws.on('message', async (message) => {
-        try {
-            const data = JSON.parse(message);
-
-            if (data.type === 'claude-command') {
-                console.log('[DEBUG] User message:', data.command || '[Continue/Resume]');
-                console.log('📁 Project:', data.options?.projectPath || 'Unknown');
-                console.log('🔄 Session:', data.options?.sessionId ? 'Resume' : 'New');
-
-                // Use Claude Agents SDK
-                await queryClaudeSDK(data.command, data.options, writer);
-            } else if (data.type === 'cursor-command') {
-                console.log('[DEBUG] Cursor message:', data.command || '[Continue/Resume]');
-                console.log('📁 Project:', data.options?.cwd || 'Unknown');
-                console.log('🔄 Session:', data.options?.sessionId ? 'Resume' : 'New');
-                console.log('🤖 Model:', data.options?.model || 'default');
-                await spawnCursor(data.command, data.options, writer);
-            } else if (data.type === 'codex-command') {
-                console.log('[DEBUG] Codex message:', data.command || '[Continue/Resume]');
-                console.log('📁 Project:', data.options?.projectPath || data.options?.cwd || 'Unknown');
-                console.log('🔄 Session:', data.options?.sessionId ? 'Resume' : 'New');
-                console.log('🤖 Model:', data.options?.model || 'default');
-                await queryCodex(data.command, data.options, writer);
-            } else if (data.type === 'gemini-command') {
-                console.log('[DEBUG] Gemini message:', data.command || '[Continue/Resume]');
-                console.log('📁 Project:', data.options?.projectPath || data.options?.cwd || 'Unknown');
-                console.log('🔄 Session:', data.options?.sessionId ? 'Resume' : 'New');
-                console.log('🤖 Model:', data.options?.model || 'default');
-                await spawnGemini(data.command, data.options, writer);
-            } else if (data.type === 'cursor-resume') {
-                // Backward compatibility: treat as cursor-command with resume and no prompt
-                console.log('[DEBUG] Cursor resume session (compat):', data.sessionId);
-                await spawnCursor('', {
-                    sessionId: data.sessionId,
-                    resume: true,
-                    cwd: data.options?.cwd
-                }, writer);
-            } else if (data.type === 'abort-session') {
-                console.log('[DEBUG] Abort session request:', data.sessionId);
-                const provider = data.provider || 'claude';
-                let success;
-
-                if (provider === 'cursor') {
-                    success = abortCursorSession(data.sessionId);
-                } else if (provider === 'codex') {
-                    success = abortCodexSession(data.sessionId);
-                } else if (provider === 'gemini') {
-                    success = abortGeminiSession(data.sessionId);
-                } else {
-                    // Use Claude Agents SDK
-                    success = await abortClaudeSDKSession(data.sessionId);
-                }
-
-                writer.send(createNormalizedMessage({ kind: 'complete', exitCode: success ? 0 : 1, aborted: true, success, sessionId: data.sessionId, provider }));
-            } else if (data.type === 'claude-permission-response') {
-                // Relay UI approval decisions back into the SDK control flow.
-                // This does not persist permissions; it only resolves the in-flight request,
-                // introduced so the SDK can resume once the user clicks Allow/Deny.
-                if (data.requestId) {
-                    resolveToolApproval(data.requestId, {
-                        allow: Boolean(data.allow),
-                        updatedInput: data.updatedInput,
-                        message: data.message,
-                        rememberEntry: data.rememberEntry
-                    });
-                }
-            } else if (data.type === 'cursor-abort') {
-                console.log('[DEBUG] Abort Cursor session:', data.sessionId);
-                const success = abortCursorSession(data.sessionId);
-                writer.send(createNormalizedMessage({ kind: 'complete', exitCode: success ? 0 : 1, aborted: true, success, sessionId: data.sessionId, provider: 'cursor' }));
-            } else if (data.type === 'check-session-status') {
-                // Check if a specific session is currently processing
-                const provider = data.provider || 'claude';
-                const sessionId = data.sessionId;
-                let isActive;
-
-                if (provider === 'cursor') {
-                    isActive = isCursorSessionActive(sessionId);
-                } else if (provider === 'codex') {
-                    isActive = isCodexSessionActive(sessionId);
-                } else if (provider === 'gemini') {
-                    isActive = isGeminiSessionActive(sessionId);
-                } else {
-                    // Use Claude Agents SDK
-                    isActive = isClaudeSDKSessionActive(sessionId);
-                    if (isActive) {
-                        // Reconnect the session's writer to the new WebSocket so
-                        // subsequent SDK output flows to the refreshed client.
-                        reconnectSessionWriter(sessionId, ws);
-                    }
-                }
-
-                writer.send({
-                    type: 'session-status',
-                    sessionId,
-                    provider,
-                    isProcessing: isActive
-                });
-            } else if (data.type === 'get-pending-permissions') {
-                // Return pending permission requests for a session
-                const sessionId = data.sessionId;
-                if (sessionId && isClaudeSDKSessionActive(sessionId)) {
-                    const pending = getPendingApprovalsForSession(sessionId);
-                    writer.send({
-                        type: 'pending-permissions-response',
-                        sessionId,
-                        data: pending
-                    });
-                }
-            } else if (data.type === 'get-active-sessions') {
-                // Get all currently active sessions
-                const activeSessions = {
-                    claude: getActiveClaudeSDKSessions(),
-                    cursor: getActiveCursorSessions(),
-                    codex: getActiveCodexSessions(),
-                    gemini: getActiveGeminiSessions()
-                };
-                writer.send({
-                    type: 'active-sessions',
-                    sessions: activeSessions
-                });
-            }
-        } catch (error) {
-            console.error('[ERROR] Chat WebSocket error:', error.message);
-            writer.send({
-                type: 'error',
-                error: error.message
-            });
-        }
-    });
-
-    ws.on('close', () => {
-        console.log('🔌 Chat client disconnected');
-        // Remove from connected clients
-        connectedClients.delete(ws);
-    });
-}
-
-// Handle shell WebSocket connections
-function handleShellConnection(ws) {
-    console.log('🐚 Shell client connected');
-    let shellProcess = null;
-    let ptySessionKey = null;
-    let urlDetectionBuffer = '';
-    const announcedAuthUrls = new Set();
-
-    ws.on('message', async (message) => {
-        try {
-            const data = JSON.parse(message);
-            console.log('📨 Shell message received:', data.type);
-
-            if (data.type === 'init') {
-                const projectPath = data.projectPath || process.cwd();
-                const sessionId = data.sessionId;
-                const hasSession = data.hasSession;
-                const provider = data.provider || 'claude';
-                const initialCommand = data.initialCommand;
-                const isPlainShell = data.isPlainShell || (!!initialCommand && !hasSession) || provider === 'plain-shell';
-                urlDetectionBuffer = '';
-                announcedAuthUrls.clear();
-
-                // Login commands (Claude/Cursor auth) should never reuse cached sessions
-                const isLoginCommand = initialCommand && (
-                    initialCommand.includes('setup-token') ||
-                    initialCommand.includes('cursor-agent login') ||
-                    initialCommand.includes('auth login')
-                );
-
-                // Include command hash in session key so different commands get separate sessions
-                const commandSuffix = isPlainShell && initialCommand
-                    ? `_cmd_${Buffer.from(initialCommand).toString('base64').slice(0, 16)}`
-                    : '';
-                ptySessionKey = `${projectPath}_${sessionId || 'default'}${commandSuffix}`;
-
-                // Kill any existing login session before starting fresh
-                if (isLoginCommand) {
-                    const oldSession = ptySessionsMap.get(ptySessionKey);
-                    if (oldSession) {
-                        console.log('🧹 Cleaning up existing login session:', ptySessionKey);
-                        if (oldSession.timeoutId) clearTimeout(oldSession.timeoutId);
-                        if (oldSession.pty && oldSession.pty.kill) oldSession.pty.kill();
-                        ptySessionsMap.delete(ptySessionKey);
-                    }
-                }
-
-                const existingSession = isLoginCommand ? null : ptySessionsMap.get(ptySessionKey);
-                if (existingSession) {
-                    console.log('♻️  Reconnecting to existing PTY session:', ptySessionKey);
-                    shellProcess = existingSession.pty;
-
-                    clearTimeout(existingSession.timeoutId);
-
-                    ws.send(JSON.stringify({
-                        type: 'output',
-                        data: `\x1b[36m[Reconnected to existing session]\x1b[0m\r\n`
-                    }));
-
-                    if (existingSession.buffer && existingSession.buffer.length > 0) {
-                        console.log(`📜 Sending ${existingSession.buffer.length} buffered messages`);
-                        existingSession.buffer.forEach(bufferedData => {
-                            ws.send(JSON.stringify({
-                                type: 'output',
-                                data: bufferedData
-                            }));
-                        });
-                    }
-
-                    existingSession.ws = ws;
-
-                    return;
-                }
-
-                console.log('[INFO] Starting shell in:', projectPath);
-                console.log('📋 Session info:', hasSession ? `Resume session ${sessionId}` : (isPlainShell ? 'Plain shell mode' : 'New session'));
-                console.log('🤖 Provider:', isPlainShell ? 'plain-shell' : provider);
-                if (initialCommand) {
-                    console.log('⚡ Initial command:', initialCommand);
-                }
-
-                // First send a welcome message
-                let welcomeMsg;
-                if (isPlainShell) {
-                    welcomeMsg = `\x1b[36mStarting terminal in: ${projectPath}\x1b[0m\r\n`;
-                } else {
-                    const providerName = provider === 'cursor' ? 'Cursor' : (provider === 'codex' ? 'Codex' : (provider === 'gemini' ? 'Gemini' : 'Claude'));
-                    welcomeMsg = hasSession ?
-                        `\x1b[36mResuming ${providerName} session ${sessionId} in: ${projectPath}\x1b[0m\r\n` :
-                        `\x1b[36mStarting new ${providerName} session in: ${projectPath}\x1b[0m\r\n`;
-                }
-
-                ws.send(JSON.stringify({
-                    type: 'output',
-                    data: welcomeMsg
-                }));
-
-                try {
-                    // Validate projectPath — resolve to absolute and verify it exists
-                    const resolvedProjectPath = path.resolve(projectPath);
-                    try {
-                        const stats = fs.statSync(resolvedProjectPath);
-                        if (!stats.isDirectory()) {
-                            throw new Error('Not a directory');
-                        }
-                    } catch (pathErr) {
-                        ws.send(JSON.stringify({ type: 'error', message: 'Invalid project path' }));
-                        return;
-                    }
-
-                    // Validate sessionId — only allow safe characters
-                    const safeSessionIdPattern = /^[a-zA-Z0-9_.\-:]+$/;
-                    if (sessionId && !safeSessionIdPattern.test(sessionId)) {
-                        ws.send(JSON.stringify({ type: 'error', message: 'Invalid session ID' }));
-                        return;
-                    }
-
-                    // Build shell command — use cwd for project path (never interpolate into shell string)
-                    let shellCommand;
-                    if (isPlainShell) {
-                        // Plain shell mode - run the initial command in the project directory
-                        shellCommand = initialCommand;
-                    } else if (provider === 'cursor') {
-                        if (hasSession && sessionId) {
-                            shellCommand = `cursor-agent --resume="${sessionId}"`;
-                        } else {
-                            shellCommand = 'cursor-agent';
-                        }
-                    } else if (provider === 'codex') {
-                        // Use codex command; attempt to resume and fall back to a new session when the resume fails.
-                        if (hasSession && sessionId) {
-                            if (os.platform() === 'win32') {
-                                // PowerShell syntax for fallback
-                                shellCommand = `codex resume "${sessionId}"; if ($LASTEXITCODE -ne 0) { codex }`;
-                            } else {
-                                shellCommand = `codex resume "${sessionId}" || codex`;
-                            }
-                        } else {
-                            shellCommand = 'codex';
-                        }
-                    } else if (provider === 'gemini') {
-                        const command = initialCommand || 'gemini';
-                        let resumeId = sessionId;
-                        if (hasSession && sessionId) {
-                            try {
-                                // Gemini CLI enforces its own native session IDs, unlike other agents that accept arbitrary string names.
-                                // The UI only knows about its internal generated `sessionId` (e.g. gemini_1234).
-                                // We must fetch the mapping from the backend session manager to pass the native `cliSessionId` to the shell.
-                                const sess = sessionManager.getSession(sessionId);
-                                if (sess && sess.cliSessionId) {
-                                    resumeId = sess.cliSessionId;
-                                    // Validate the looked-up CLI session ID too
-                                    if (!safeSessionIdPattern.test(resumeId)) {
-                                        resumeId = null;
-                                    }
-                                }
-                            } catch (err) {
-                                console.error('Failed to get Gemini CLI session ID:', err);
-                            }
-                        }
-
-                        if (hasSession && resumeId) {
-                            shellCommand = `${command} --resume "${resumeId}"`;
-                        } else {
-                            shellCommand = command;
-                        }
-                    } else {
-                        // Claude (default provider)
-                        const command = initialCommand || 'claude';
-                        if (hasSession && sessionId) {
-                            if (os.platform() === 'win32') {
-                                shellCommand = `claude --resume "${sessionId}"; if ($LASTEXITCODE -ne 0) { claude }`;
-                            } else {
-                                shellCommand = `claude --resume "${sessionId}" || claude`;
-                            }
-                        } else {
-                            shellCommand = command;
-                        }
-                    }
-
-                    console.log('🔧 Executing shell command:', shellCommand);
-
-                    // Use appropriate shell based on platform
-                    const shell = os.platform() === 'win32' ? 'powershell.exe' : 'bash';
-                    const shellArgs = os.platform() === 'win32' ? ['-Command', shellCommand] : ['-c', shellCommand];
-
-                    // Use terminal dimensions from client if provided, otherwise use defaults
-                    const termCols = data.cols || 80;
-                    const termRows = data.rows || 24;
-                    console.log('📐 Using terminal dimensions:', termCols, 'x', termRows);
-
-                    shellProcess = pty.spawn(shell, shellArgs, {
-                        name: 'xterm-256color',
-                        cols: termCols,
-                        rows: termRows,
-                        cwd: resolvedProjectPath,
-                        env: {
-                            ...process.env,
-                            TERM: 'xterm-256color',
-                            COLORTERM: 'truecolor',
-                            FORCE_COLOR: '3'
-                        }
-                    });
-
-                    console.log('🟢 Shell process started with PTY, PID:', shellProcess.pid);
-
-                    ptySessionsMap.set(ptySessionKey, {
-                        pty: shellProcess,
-                        ws: ws,
-                        buffer: [],
-                        timeoutId: null,
-                        projectPath,
-                        sessionId
-                    });
-
-                    // Handle data output
-                    shellProcess.onData((data) => {
-                        const session = ptySessionsMap.get(ptySessionKey);
-                        if (!session) return;
-
-                        if (session.buffer.length < 5000) {
-                            session.buffer.push(data);
-                        } else {
-                            session.buffer.shift();
-                            session.buffer.push(data);
-                        }
-
-                        if (session.ws && session.ws.readyState === WebSocket.OPEN) {
-                            let outputData = data;
-
-                            const cleanChunk = stripAnsiSequences(data);
-                            urlDetectionBuffer = `${urlDetectionBuffer}${cleanChunk}`.slice(-SHELL_URL_PARSE_BUFFER_LIMIT);
-
-                            outputData = outputData.replace(
-                                /OPEN_URL:\s*(https?:\/\/[^\s\x1b\x07]+)/g,
-                                '[INFO] Opening in browser: $1'
-                            );
-
-                            const emitAuthUrl = (detectedUrl, autoOpen = false) => {
-                                const normalizedUrl = normalizeDetectedUrl(detectedUrl);
-                                if (!normalizedUrl) return;
-
-                                const isNewUrl = !announcedAuthUrls.has(normalizedUrl);
-                                if (isNewUrl) {
-                                    announcedAuthUrls.add(normalizedUrl);
-                                    session.ws.send(JSON.stringify({
-                                        type: 'auth_url',
-                                        url: normalizedUrl,
-                                        autoOpen
-                                    }));
-                                }
-
-                            };
-
-                            const normalizedDetectedUrls = extractUrlsFromText(urlDetectionBuffer)
-                                .map((url) => normalizeDetectedUrl(url))
-                                .filter(Boolean);
-
-                            // Prefer the most complete URL if shorter prefix variants are also present.
-                            const dedupedDetectedUrls = Array.from(new Set(normalizedDetectedUrls)).filter((url, _, urls) =>
-                                !urls.some((otherUrl) => otherUrl !== url && otherUrl.startsWith(url))
-                            );
-
-                            dedupedDetectedUrls.forEach((url) => emitAuthUrl(url, false));
-
-                            if (shouldAutoOpenUrlFromOutput(cleanChunk) && dedupedDetectedUrls.length > 0) {
-                                const bestUrl = dedupedDetectedUrls.reduce((longest, current) =>
-                                    current.length > longest.length ? current : longest
-                                );
-                                emitAuthUrl(bestUrl, true);
-                            }
-
-                            // Send regular output
-                            session.ws.send(JSON.stringify({
-                                type: 'output',
-                                data: outputData
-                            }));
-                        }
-                    });
-
-                    // Handle process exit
-                    shellProcess.onExit((exitCode) => {
-                        console.log('🔚 Shell process exited with code:', exitCode.exitCode, 'signal:', exitCode.signal);
-                        const session = ptySessionsMap.get(ptySessionKey);
-                        if (session && session.ws && session.ws.readyState === WebSocket.OPEN) {
-                            session.ws.send(JSON.stringify({
-                                type: 'output',
-                                data: `\r\n\x1b[33mProcess exited with code ${exitCode.exitCode}${exitCode.signal ? ` (${exitCode.signal})` : ''}\x1b[0m\r\n`
-                            }));
-                        }
-                        if (session && session.timeoutId) {
-                            clearTimeout(session.timeoutId);
-                        }
-                        ptySessionsMap.delete(ptySessionKey);
-                        shellProcess = null;
-                    });
-
-                } catch (spawnError) {
-                    console.error('[ERROR] Error spawning process:', spawnError);
-                    ws.send(JSON.stringify({
-                        type: 'output',
-                        data: `\r\n\x1b[31mError: ${spawnError.message}\x1b[0m\r\n`
-                    }));
-                }
-
-            } else if (data.type === 'input') {
-                // Send input to shell process
-                if (shellProcess && shellProcess.write) {
-                    try {
-                        shellProcess.write(data.data);
-                    } catch (error) {
-                        console.error('Error writing to shell:', error);
-                    }
-                } else {
-                    console.warn('No active shell process to send input to');
-                }
-            } else if (data.type === 'resize') {
-                // Handle terminal resize
-                if (shellProcess && shellProcess.resize) {
-                    console.log('Terminal resize requested:', data.cols, 'x', data.rows);
-                    shellProcess.resize(data.cols, data.rows);
-                }
-            }
-        } catch (error) {
-            console.error('[ERROR] Shell WebSocket error:', error.message);
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(JSON.stringify({
-                    type: 'output',
-                    data: `\r\n\x1b[31mError: ${error.message}\x1b[0m\r\n`
-                }));
-            }
-        }
-    });
-
-    ws.on('close', () => {
-        console.log('🔌 Shell client disconnected');
-
-        if (ptySessionKey) {
-            const session = ptySessionsMap.get(ptySessionKey);
-            if (session) {
-                console.log('⏳ PTY session kept alive, will timeout in 30 minutes:', ptySessionKey);
-                session.ws = null;
-
-                session.timeoutId = setTimeout(() => {
-                    console.log('⏰ PTY session timeout, killing process:', ptySessionKey);
-                    if (session.pty && session.pty.kill) {
-                        session.pty.kill();
-                    }
-                    ptySessionsMap.delete(ptySessionKey);
-                }, PTY_SESSION_TIMEOUT);
-            }
-        }
-    });
-
-    ws.on('error', (error) => {
-        console.error('[ERROR] Shell WebSocket error:', error);
-    });
-}
-// Image upload endpoint
-app.post('/api/projects/:projectName/upload-images', authenticateToken, async (req, res) => {
+// Image upload endpoint. Accepts the DB-assigned `projectId` (not a folder name)
+// but the current implementation doesn't need to touch the project directory,
+// so we just leave the param rename for consistency with the rest of the API.
+app.post('/api/projects/:projectId/upload-images', authenticateToken, async (req, res) => {
     try {
         const multer = (await import('multer')).default;
         const path = (await import('path')).default;
@@ -1980,10 +1123,11 @@ app.post('/api/projects/:projectName/upload-images', authenticateToken, async (r
     }
 });
 
-// Get token usage for a specific session
-app.get('/api/projects/:projectName/sessions/:sessionId/token-usage', authenticateToken, async (req, res) => {
+// Get token usage for a specific session. `projectId` is the DB primary key;
+// the Claude branch below resolves it to an absolute path via the DB.
+app.get('/api/projects/:projectId/sessions/:sessionId/token-usage', authenticateToken, async (req, res) => {
     try {
-        const { projectName, sessionId } = req.params;
+        const { projectId, sessionId } = req.params;
         const { provider = 'claude' } = req.query;
         const homeDir = os.homedir();
 
@@ -1998,23 +1142,129 @@ app.get('/api/projects/:projectName/sessions/:sessionId/token-usage', authentica
             return res.json({
                 used: 0,
                 total: 0,
-                breakdown: { input: 0, cacheCreation: 0, cacheRead: 0 },
+                inputTokens: 0,
+                outputTokens: 0,
+                breakdown: { input: 0, output: 0 },
                 unsupported: true,
                 message: 'Token usage tracking not available for Cursor sessions'
             });
         }
 
-        // Handle Gemini sessions - they are raw logs in our current setup
         if (provider === 'gemini') {
+            const session = sessionsDb.getSessionById(safeSessionId);
+            const sessionFilePath = session?.jsonl_path;
+            if (!sessionFilePath) {
+                return res.json({
+                    used: 0,
+                    inputTokens: 0,
+                    outputTokens: 0,
+                    breakdown: { input: 0, output: 0 },
+                    unsupported: true,
+                    message: 'Token usage tracking not available for this Gemini session'
+                });
+            }
+
+            let fileContent;
+            try {
+                fileContent = await fsPromises.readFile(sessionFilePath, 'utf8');
+            } catch (error) {
+                if (error.code === 'ENOENT') {
+                    return res.status(404).json({ error: 'Session file not found', path: sessionFilePath });
+                }
+                throw error;
+            }
+
+            const lines = fileContent.trim().split('\n');
+            let inputTokens = 0;
+            let outputTokens = 0;
+            let totalTokens = 0;
+
+            for (let i = lines.length - 1; i >= 0; i--) {
+                try {
+                    const entry = JSON.parse(lines[i]);
+                    if (!entry.tokens || typeof entry.tokens !== 'object') {
+                        continue;
+                    }
+
+                    inputTokens = Number(entry.tokens.input || 0);
+                    outputTokens = Number(entry.tokens.output || 0);
+                    totalTokens = Number(entry.tokens.total || inputTokens + outputTokens || 0);
+                    break;
+                } catch {
+                    continue;
+                }
+            }
+
             return res.json({
-                used: 0,
-                total: 0,
-                breakdown: { input: 0, cacheCreation: 0, cacheRead: 0 },
-                unsupported: true,
-                message: 'Token usage tracking not available for Gemini sessions'
+                used: totalTokens,
+                inputTokens,
+                outputTokens,
+                breakdown: {
+                    input: inputTokens,
+                    output: outputTokens
+                }
             });
         }
 
+        if (provider === 'opencode') {
+            const dbPath = getOpenCodeDatabasePath();
+            if (!fs.existsSync(dbPath)) {
+                return res.status(404).json({ error: 'OpenCode database not found' });
+            }
+
+            const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+            try {
+                const columns = db.prepare('PRAGMA table_info(session)').all();
+                const columnNames = new Set(columns.map((column) => column.name));
+                const requiredColumns = ['tokens_input', 'tokens_output', 'tokens_reasoning', 'tokens_cache_read', 'tokens_cache_write'];
+                if (!requiredColumns.every((column) => columnNames.has(column))) {
+                    return res.json({
+                        used: 0,
+                        inputTokens: 0,
+                        outputTokens: 0,
+                        breakdown: { input: 0, output: 0 },
+                        unsupported: true,
+                        message: 'Token usage tracking is not available in this OpenCode database schema'
+                    });
+                }
+
+                const row = db.prepare(`
+                    SELECT
+                        tokens_input AS inputTokens,
+                        tokens_output AS outputTokens,
+                        tokens_reasoning AS reasoningTokens,
+                        tokens_cache_read AS cacheReadTokens,
+                        tokens_cache_write AS cacheWriteTokens
+                    FROM session
+                    WHERE id = ?
+                `).get(safeSessionId);
+
+                if (!row) {
+                    return res.status(404).json({ error: 'OpenCode session not found', sessionId: safeSessionId });
+                }
+
+                const inputTokens = Number(row.inputTokens || 0) + Number(row.cacheReadTokens || 0);
+                const outputTokens = Number(row.outputTokens || 0);
+                const totalUsed = Number(row.inputTokens || 0)
+                    + outputTokens
+                    + Number(row.reasoningTokens || 0)
+                    + Number(row.cacheReadTokens || 0)
+                    + Number(row.cacheWriteTokens || 0);
+
+                return res.json({
+                    used: totalUsed,
+                    inputTokens,
+                    outputTokens,
+                    breakdown: {
+                        input: inputTokens,
+                        output: outputTokens
+                    }
+                });
+            } finally {
+                db.close();
+            }
+        }
+
         // Handle Codex sessions
         if (provider === 'codex') {
             const codexSessionsDir = path.join(homeDir, '.codex', 'sessions');
@@ -2055,6 +1305,8 @@ app.get('/api/projects/:projectName/sessions/:sessionId/token-usage', authentica
                 throw error;
             }
             const lines = fileContent.trim().split('\n');
+            let inputTokens = 0;
+            let outputTokens = 0;
             let totalTokens = 0;
             let contextWindow = 200000; // Default for Codex/OpenAI
 
@@ -2067,7 +1319,9 @@ app.get('/api/projects/:projectName/sessions/:sessionId/token-usage', authentica
                     if (entry.type === 'event_msg' && entry.payload?.type === 'token_count' && entry.payload?.info) {
                         const tokenInfo = entry.payload.info;
                         if (tokenInfo.total_token_usage) {
-                            totalTokens = tokenInfo.total_token_usage.total_tokens || 0;
+                            inputTokens = tokenInfo.total_token_usage.input_tokens || 0;
+                            outputTokens = tokenInfo.total_token_usage.output_tokens || 0;
+                            totalTokens = tokenInfo.total_token_usage.total_tokens || inputTokens + outputTokens;
                         }
                         if (tokenInfo.model_context_window) {
                             contextWindow = tokenInfo.model_context_window;
@@ -2082,18 +1336,24 @@ app.get('/api/projects/:projectName/sessions/:sessionId/token-usage', authentica
 
             return res.json({
                 used: totalTokens,
-                total: contextWindow
+                total: contextWindow,
+                inputTokens,
+                outputTokens,
+                breakdown: {
+                    input: inputTokens,
+                    output: outputTokens
+                }
             });
         }
 
         // Handle Claude sessions (default)
-        // Extract actual project path
-        let projectPath;
-        try {
-            projectPath = await extractProjectDirectory(projectName);
-        } catch (error) {
-            console.error('Error extracting project directory:', error);
-            return res.status(500).json({ error: 'Failed to determine project path' });
+        // Resolve the project path through the DB using the caller-supplied
+        // `projectId`. Legacy code here called extractProjectDirectory with a
+        // folder-encoded project name; the migration centralizes that lookup
+        // in the projects table.
+        const projectPath = await projectsDb.getProjectPathById(projectId);
+        if (!projectPath) {
+            return res.status(404).json({ error: 'Project not found' });
         }
 
         // Construct the JSONL file path
@@ -2125,8 +1385,7 @@ app.get('/api/projects/:projectName/sessions/:sessionId/token-usage', authentica
         const parsedContextWindow = parseInt(process.env.CONTEXT_WINDOW, 10);
         const contextWindow = Number.isFinite(parsedContextWindow) ? parsedContextWindow : 160000;
         let inputTokens = 0;
-        let cacheCreationTokens = 0;
-        let cacheReadTokens = 0;
+        let outputTokens = 0;
 
         // Find the latest assistant message with usage data (scan from end)
         for (let i = lines.length - 1; i >= 0; i--) {
@@ -2139,8 +1398,7 @@ app.get('/api/projects/:projectName/sessions/:sessionId/token-usage', authentica
 
                     // Use token counts from latest assistant message only
                     inputTokens = usage.input_tokens || 0;
-                    cacheCreationTokens = usage.cache_creation_input_tokens || 0;
-                    cacheReadTokens = usage.cache_read_input_tokens || 0;
+                    outputTokens = usage.output_tokens || 0;
 
                     break; // Stop after finding the latest assistant message
                 }
@@ -2150,16 +1408,16 @@ app.get('/api/projects/:projectName/sessions/:sessionId/token-usage', authentica
             }
         }
 
-        // Calculate total context usage (excluding output_tokens, as per ccusage)
-        const totalUsed = inputTokens + cacheCreationTokens + cacheReadTokens;
+        const totalUsed = inputTokens + outputTokens;
 
         res.json({
             used: totalUsed,
             total: contextWindow,
+            inputTokens,
+            outputTokens,
             breakdown: {
                 input: inputTokens,
-                cacheCreation: cacheCreationTokens,
-                cacheRead: cacheReadTokens
+                output: outputTokens
             }
         });
     } catch (error) {
@@ -2343,7 +1601,7 @@ async function startServer() {
             console.log('');
 
             // Start watching the projects folder for changes
-            await setupProjectsWatcher();
+            await initializeSessionsWatcher();
 
             // Start server-side plugin processes for enabled plugins
             startEnabledPluginServers().catch(err => {
@@ -2351,6 +1609,7 @@ async function startServer() {
             });
         });
 
+        await closeSessionsWatcher();
         // Clean up plugin processes on shutdown
         const shutdownPlugins = async () => {
             await stopAllPlugins();
diff --git a/server/middleware/auth.js b/server/middleware/auth.js
index 73749792..c40237b2 100644
--- a/server/middleware/auth.js
+++ b/server/middleware/auth.js
@@ -1,5 +1,5 @@
 import jwt from 'jsonwebtoken';
-import { userDb, appConfigDb } from '../database/db.js';
+import { userDb, appConfigDb } from '../modules/database/index.js';
 import { IS_PLATFORM } from '../constants/config.js';
 
 // Use env var if set, otherwise auto-generate a unique secret per installation
diff --git a/server/modules/database/connection.ts b/server/modules/database/connection.ts
new file mode 100644
index 00000000..4453b0e3
--- /dev/null
+++ b/server/modules/database/connection.ts
@@ -0,0 +1,143 @@
+/**
+ * Database connection management.
+ *
+ * Owns the single SQLite connection used across all repositories.
+ * Handles path resolution, directory creation, legacy database migration,
+ * and eager app_config bootstrap so the auth middleware can read the
+ * JWT secret before the full schema is applied.
+ *
+ * Consumers should never create their own Database instance — they use
+ * `getConnection()` to obtain the shared singleton.
+ */
+
+import Database from 'better-sqlite3';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import { APP_CONFIG_TABLE_SCHEMA_SQL } from '@/modules/database/schema.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolves the database file path from environment or falls back
+ * to the legacy location inside the server/database/ folder.
+ *
+ * Priority:
+ *   1. DATABASE_PATH environment variable (set by cli.js or load-env-vars.js)
+ *   2. Legacy path: server/database/auth.db
+ */
+function resolveDatabasePath(): string {
+    // process.env.DATABASE_PATH is set by load-env-vars.js to either the .env value or a default(~/.cloudcli/auth.db) in the user's home directory. 
+    return process.env.DATABASE_PATH || resolveLegacyDatabasePath();
+}
+
+/**
+ * Resolves the legacy database path (always inside server/database/).
+ * Used for the one-time migration to the new external location.
+ */
+function resolveLegacyDatabasePath(): string {
+  const serverDir = path.resolve(__dirname, '..', '..', '..');
+  return path.join(serverDir, 'database', 'auth.db');
+}
+
+// ---------------------------------------------------------------------------
+// Directory & migration helpers
+// ---------------------------------------------------------------------------
+
+function ensureDatabaseDirectory(dbPath: string): void {
+  const dir = path.dirname(dbPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+    console.log('Created database directory:', dir);
+  }
+}
+
+/**
+ * If the database was moved to an external location (e.g. ~/.cloudcli/)
+ * but the user still has a legacy auth.db inside the install directory,
+ * copy it to the new location as a one-time migration.
+ */
+function migrateLegacyDatabase(targetPath: string): void {
+  const legacyPath = resolveLegacyDatabasePath();
+
+  if (targetPath === legacyPath) return;
+  if (fs.existsSync(targetPath)) return;
+  if (!fs.existsSync(legacyPath)) return;
+
+  try {
+    fs.copyFileSync(legacyPath, targetPath);
+    console.log('Migrated legacy database', { from: legacyPath, to: targetPath });
+
+
+    // copy the write-ahead log and shared memory files (auth.db-wal, auth.db-shm) if they exist, to preserve any uncommitted transactions
+    for (const suffix of ['-wal', '-shm']) {
+      const src = legacyPath + suffix;
+      if (fs.existsSync(src)) {
+        fs.copyFileSync(src, targetPath + suffix);
+      }
+    }
+  } catch (err: any) {
+    console.error('Could not migrate legacy database', { error: err.message });
+  }
+}
+
+
+// ---------------------------------------------------------------------------
+// Singleton connection
+// ---------------------------------------------------------------------------
+
+let instance: Database.Database | null = null;
+
+/**
+ * Returns the shared database connection, creating it on first call.
+ *
+ * The first invocation:
+ *   1. Resolves the target database path
+ *   2. Ensures the parent directory exists
+ *   3. Migrates from the legacy install-directory path if needed
+ *   4. Opens the SQLite connection
+ *   5. Eagerly creates the app_config table (auth reads JWT secret at import time)
+ *   6. Logs the database location
+ */
+export function getConnection(): Database.Database {
+  if (instance) return instance;
+
+  const dbPath = resolveDatabasePath();
+
+  ensureDatabaseDirectory(dbPath);
+  migrateLegacyDatabase(dbPath);
+
+  instance = new Database(dbPath);
+
+  // app_config must exist immediately — the auth middleware reads
+  // the JWT secret at module-load time, before initializeDatabase() runs.
+  instance.exec(APP_CONFIG_TABLE_SCHEMA_SQL);
+
+  return instance;
+}
+
+/**
+ * Returns the resolved database file path without opening a connection.
+ * Useful for diagnostics and CLI status commands.
+ */
+export function getDatabasePath(): string {
+  return resolveDatabasePath();
+}
+
+/**
+ * Closes the database connection and clears the singleton.
+ * Primarily used for graceful shutdown or testing.
+ */
+export function closeConnection(): void {
+  if (instance) {
+    instance.close();
+    instance = null;
+    console.log('Database connection closed');
+  }
+}
diff --git a/server/modules/database/index.ts b/server/modules/database/index.ts
new file mode 100644
index 00000000..da87740c
--- /dev/null
+++ b/server/modules/database/index.ts
@@ -0,0 +1,13 @@
+export { initializeDatabase } from '@/modules/database/init-db.js';
+export { closeConnection, getConnection, getDatabasePath } from '@/modules/database/connection.js';
+export { apiKeysDb } from '@/modules/database/repositories/api-keys.js';
+export { appConfigDb } from '@/modules/database/repositories/app-config.js';
+export { credentialsDb } from '@/modules/database/repositories/credentials.js';
+export { githubTokensDb } from '@/modules/database/repositories/github-tokens.js';
+export { notificationPreferencesDb } from '@/modules/database/repositories/notification-preferences.js';
+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';
+export { sessionsDb } from '@/modules/database/repositories/sessions.db.js';
+export { userDb } from '@/modules/database/repositories/users.js';
+export { vapidKeysDb } from '@/modules/database/repositories/vapid-keys.js';
diff --git a/server/modules/database/init-db.ts b/server/modules/database/init-db.ts
new file mode 100644
index 00000000..8dfcc4ee
--- /dev/null
+++ b/server/modules/database/init-db.ts
@@ -0,0 +1,17 @@
+import { getConnection } from "@/modules/database/connection.js";
+import { runMigrations } from "@/modules/database/migrations.js";
+import { INIT_SCHEMA_SQL } from "@/modules/database/schema.js";
+
+// Initialize database with schema
+export const initializeDatabase = async () => {
+    try {
+        const db = getConnection();
+        db.exec(INIT_SCHEMA_SQL);
+        console.log('Database schema applied');
+        runMigrations(db);
+    } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.log('Database initialization failed', { error: message });
+        throw err;
+    }
+};
diff --git a/server/modules/database/migrations.ts b/server/modules/database/migrations.ts
new file mode 100644
index 00000000..5b0490cb
--- /dev/null
+++ b/server/modules/database/migrations.ts
@@ -0,0 +1,455 @@
+import { Database } from 'better-sqlite3';
+
+import {
+  APP_CONFIG_TABLE_SCHEMA_SQL,
+  LAST_SCANNED_AT_SQL,
+  PROJECTS_TABLE_SCHEMA_SQL,
+  PUSH_SUBSCRIPTIONS_TABLE_SCHEMA_SQL,
+  SESSIONS_TABLE_SCHEMA_SQL,
+  USER_NOTIFICATION_PREFERENCES_TABLE_SCHEMA_SQL,
+  VAPID_KEYS_TABLE_SCHEMA_SQL,
+} from '@/modules/database/schema.js';
+
+const SQLITE_UUID_SQL = `
+lower(hex(randomblob(4))) || '-' ||
+lower(hex(randomblob(2))) || '-' ||
+lower(hex(randomblob(2))) || '-' ||
+lower(hex(randomblob(2))) || '-' ||
+lower(hex(randomblob(6)))
+`;
+
+type TableInfoRow = {
+  name: string;
+  pk: number;
+};
+
+const addColumnToTableIfNotExists = (
+  db: Database,
+  tableName: string,
+  columnNames: string[],
+  columnName: string,
+  columnType: string
+) => {
+  if (!columnNames.includes(columnName)) {
+    console.log(`Running migration: Adding ${columnName} column to ${tableName} table`);
+    db.exec(`ALTER TABLE ${tableName} ADD COLUMN ${columnName} ${columnType}`);
+  }
+};
+
+const tableExists = (db: Database, tableName: string): boolean =>
+  Boolean(
+    db
+      .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?")
+      .get(tableName)
+  );
+
+const getTableInfo = (db: Database, tableName: string): TableInfoRow[] =>
+  db.prepare(`PRAGMA table_info(${tableName})`).all() as TableInfoRow[];
+
+const migrateLegacySessionNames = (db: Database): void => {
+  const hasLegacySessionNamesTable = tableExists(db, 'session_names');
+  const hasSessionsTable = tableExists(db, 'sessions');
+
+  if (!hasLegacySessionNamesTable) {
+    return;
+  }
+
+  if (hasSessionsTable) {
+    console.log('Running migration: Merging session_names into sessions');
+    db.exec(`
+      INSERT INTO sessions (session_id, provider, custom_name, created_at, updated_at)
+      SELECT
+        session_id,
+        COALESCE(provider, 'claude'),
+        custom_name,
+        COALESCE(created_at, CURRENT_TIMESTAMP),
+        COALESCE(updated_at, CURRENT_TIMESTAMP)
+      FROM session_names
+      WHERE true
+      ON CONFLICT(session_id) DO UPDATE SET
+        provider = excluded.provider,
+        custom_name = COALESCE(excluded.custom_name, sessions.custom_name),
+        created_at = COALESCE(sessions.created_at, excluded.created_at),
+        updated_at = COALESCE(excluded.updated_at, sessions.updated_at)
+    `);
+    db.exec('DROP TABLE session_names');
+    return;
+  }
+
+  console.log('Running migration: Renaming session_names table to sessions');
+  db.exec('ALTER TABLE session_names RENAME TO sessions');
+};
+
+const migrateLegacyWorkspaceTableIntoProjects = (db: Database): void => {
+  db.exec(PROJECTS_TABLE_SCHEMA_SQL);
+
+  if (!tableExists(db, 'workspace_original_paths')) {
+    return;
+  }
+
+  console.log('Running migration: Migrating workspace_original_paths data into projects');
+  db.exec(`
+    INSERT INTO projects (project_id, project_path, custom_project_name, isStarred, isArchived)
+    SELECT
+      CASE
+        WHEN workspace_id IS NULL OR trim(workspace_id) = ''
+        THEN ${SQLITE_UUID_SQL}
+        ELSE workspace_id
+      END,
+      workspace_path,
+      custom_workspace_name,
+      COALESCE(isStarred, 0),
+      0
+    FROM workspace_original_paths
+    WHERE workspace_path IS NOT NULL AND trim(workspace_path) <> ''
+    ON CONFLICT(project_path) DO UPDATE SET
+      custom_project_name = COALESCE(projects.custom_project_name, excluded.custom_project_name),
+      isStarred = COALESCE(projects.isStarred, excluded.isStarred)
+  `);
+};
+
+const rebuildProjectsTableWithPrimaryKeySchema = (db: Database): void => {
+  const hasProjectsTable = tableExists(db, 'projects');
+  if (!hasProjectsTable) {
+    db.exec(PROJECTS_TABLE_SCHEMA_SQL);
+    return;
+  }
+
+  const projectsTableInfo = getTableInfo(db, 'projects');
+  const columnNames = projectsTableInfo.map((column) => column.name);
+  const hasProjectIdPrimaryKey = projectsTableInfo.some(
+    (column) => column.name === 'project_id' && column.pk === 1,
+  );
+
+  if (hasProjectIdPrimaryKey) {
+    addColumnToTableIfNotExists(db, 'projects', columnNames, 'custom_project_name', 'TEXT DEFAULT NULL');
+    addColumnToTableIfNotExists(db, 'projects', columnNames, 'isStarred', 'BOOLEAN DEFAULT 0');
+    addColumnToTableIfNotExists(db, 'projects', columnNames, 'isArchived', 'BOOLEAN DEFAULT 0');
+    db.exec(`
+      UPDATE projects
+      SET project_id = ${SQLITE_UUID_SQL}
+      WHERE project_id IS NULL OR trim(project_id) = ''
+    `);
+    return;
+  }
+
+  console.log('Running migration: Rebuilding projects table to enforce project_id primary key');
+
+  const projectPathExpression = columnNames.includes('project_path')
+    ? 'project_path'
+    : columnNames.includes('workspace_path')
+      ? 'workspace_path'
+      : 'NULL';
+
+  const customProjectNameExpression = columnNames.includes('custom_project_name')
+    ? 'custom_project_name'
+    : columnNames.includes('custom_workspace_name')
+      ? 'custom_workspace_name'
+      : 'NULL';
+
+  const isStarredExpression = columnNames.includes('isStarred') ? 'COALESCE(isStarred, 0)' : '0';
+
+  const isArchivedExpression = columnNames.includes('isArchived') ? 'COALESCE(isArchived, 0)' : '0';
+
+  const projectIdExpression = columnNames.includes('project_id')
+    ? `CASE
+         WHEN project_id IS NULL OR trim(project_id) = ''
+         THEN ${SQLITE_UUID_SQL}
+         ELSE project_id
+       END`
+    : SQLITE_UUID_SQL;
+
+  db.exec('PRAGMA foreign_keys = OFF');
+  try {
+    db.exec('BEGIN TRANSACTION');
+    db.exec('DROP TABLE IF EXISTS projects__new');
+    db.exec(`
+      CREATE TABLE projects__new (
+        project_id TEXT PRIMARY KEY NOT NULL,
+        project_path TEXT NOT NULL UNIQUE,
+        custom_project_name TEXT DEFAULT NULL,
+        isStarred BOOLEAN DEFAULT 0,
+        isArchived BOOLEAN DEFAULT 0
+      )
+    `);
+    db.exec(`
+      WITH source_rows AS (
+        SELECT
+          ${projectPathExpression} AS project_path,
+          ${customProjectNameExpression} AS custom_project_name,
+          ${isStarredExpression} AS isStarred,
+          ${isArchivedExpression} AS isArchived,
+          ${projectIdExpression} AS candidate_project_id,
+          rowid AS source_rowid
+        FROM projects
+        WHERE ${projectPathExpression} IS NOT NULL AND trim(${projectPathExpression}) <> ''
+      ),
+      deduped_paths AS (
+        SELECT
+          project_path,
+          custom_project_name,
+          isStarred,
+          isArchived,
+          candidate_project_id,
+          source_rowid,
+          ROW_NUMBER() OVER (PARTITION BY project_path ORDER BY source_rowid) AS project_path_rank
+        FROM source_rows
+      ),
+      prepared_rows AS (
+        SELECT
+          CASE
+            WHEN ROW_NUMBER() OVER (PARTITION BY candidate_project_id ORDER BY source_rowid) = 1
+            THEN candidate_project_id
+            ELSE ${SQLITE_UUID_SQL}
+          END AS project_id,
+          project_path,
+          custom_project_name,
+          isStarred,
+          isArchived
+        FROM deduped_paths
+        WHERE project_path_rank = 1
+      )
+      INSERT INTO projects__new (
+        project_id,
+        project_path,
+        custom_project_name,
+        isStarred,
+        isArchived
+      )
+      SELECT
+        project_id,
+        project_path,
+        custom_project_name,
+        isStarred,
+        isArchived
+      FROM prepared_rows
+    `);
+    db.exec('DROP TABLE projects');
+    db.exec('ALTER TABLE projects__new RENAME TO projects');
+    db.exec('COMMIT');
+  } catch (migrationError) {
+    db.exec('ROLLBACK');
+    throw migrationError;
+  } finally {
+    db.exec('PRAGMA foreign_keys = ON');
+  }
+};
+
+const rebuildSessionsTableWithProjectSchema = (db: Database): void => {
+  const hasSessions = tableExists(db, 'sessions');
+  if (!hasSessions) {
+    db.exec(SESSIONS_TABLE_SCHEMA_SQL);
+    return;
+  }
+
+  const sessionsTableInfo = getTableInfo(db, 'sessions');
+  const columnNames = sessionsTableInfo.map((column) => column.name);
+  const primaryKeyColumns = sessionsTableInfo
+    .filter((column) => column.pk > 0)
+    .sort((a, b) => a.pk - b.pk)
+    .map((column) => column.name);
+
+  const shouldRebuild =
+    !columnNames.includes('project_path') ||
+    primaryKeyColumns.length !== 1 ||
+    primaryKeyColumns[0] !== 'session_id' ||
+    !columnNames.includes('provider');
+
+  if (!shouldRebuild) {
+    addColumnToTableIfNotExists(db, 'sessions', columnNames, 'jsonl_path', 'TEXT');
+    addColumnToTableIfNotExists(db, 'sessions', columnNames, 'isArchived', 'BOOLEAN DEFAULT 0');
+    addColumnToTableIfNotExists(db, 'sessions', columnNames, 'created_at', 'DATETIME');
+    addColumnToTableIfNotExists(db, 'sessions', columnNames, 'updated_at', 'DATETIME');
+    db.exec('UPDATE sessions SET isArchived = COALESCE(isArchived, 0)');
+    db.exec('UPDATE sessions SET created_at = COALESCE(created_at, CURRENT_TIMESTAMP)');
+    db.exec('UPDATE sessions SET updated_at = COALESCE(updated_at, CURRENT_TIMESTAMP)');
+    return;
+  }
+
+  console.log('Running migration: Rebuilding sessions table to project-based schema');
+
+  const projectPathExpression = columnNames.includes('project_path')
+    ? 'project_path'
+    : columnNames.includes('workspace_path')
+      ? 'workspace_path'
+      : 'NULL';
+
+  const providerExpression = columnNames.includes('provider')
+    ? "COALESCE(provider, 'claude')"
+    : "'claude'";
+
+  const customNameExpression = columnNames.includes('custom_name')
+    ? 'custom_name'
+    : 'NULL';
+
+  const jsonlPathExpression = columnNames.includes('jsonl_path')
+    ? 'jsonl_path'
+    : 'NULL';
+
+  const isArchivedExpression = columnNames.includes('isArchived')
+    ? 'COALESCE(isArchived, 0)'
+    : '0';
+
+  const createdAtExpression = columnNames.includes('created_at')
+    ? 'COALESCE(created_at, CURRENT_TIMESTAMP)'
+    : 'CURRENT_TIMESTAMP';
+
+  const updatedAtExpression = columnNames.includes('updated_at')
+    ? 'COALESCE(updated_at, CURRENT_TIMESTAMP)'
+    : 'CURRENT_TIMESTAMP';
+
+  db.exec('PRAGMA foreign_keys = OFF');
+  try {
+    db.exec('BEGIN TRANSACTION');
+    db.exec('DROP TABLE IF EXISTS sessions__new');
+    db.exec(`
+      CREATE TABLE sessions__new (
+        session_id TEXT NOT NULL,
+        provider TEXT NOT NULL DEFAULT 'claude',
+        custom_name TEXT,
+        project_path TEXT,
+        jsonl_path TEXT,
+        isArchived BOOLEAN DEFAULT 0,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        PRIMARY KEY (session_id),
+        FOREIGN KEY (project_path) REFERENCES projects(project_path)
+        ON DELETE SET NULL
+        ON UPDATE CASCADE
+      )
+    `);
+    db.exec(`
+      WITH source_rows AS (
+        SELECT
+          session_id,
+          ${providerExpression} AS provider,
+          ${customNameExpression} AS custom_name,
+          ${projectPathExpression} AS project_path,
+          ${jsonlPathExpression} AS jsonl_path,
+          ${isArchivedExpression} AS isArchived,
+          ${createdAtExpression} AS created_at,
+          ${updatedAtExpression} AS updated_at,
+          rowid AS source_rowid
+        FROM sessions
+        WHERE session_id IS NOT NULL AND trim(session_id) <> ''
+      ),
+      ranked_rows AS (
+        SELECT
+          session_id,
+          provider,
+          custom_name,
+          project_path,
+          jsonl_path,
+          isArchived,
+          created_at,
+          updated_at,
+          ROW_NUMBER() OVER (
+            PARTITION BY session_id
+            ORDER BY datetime(COALESCE(updated_at, created_at)) DESC, source_rowid DESC
+          ) AS session_rank
+        FROM source_rows
+      )
+      INSERT INTO sessions__new (
+        session_id,
+        provider,
+        custom_name,
+        project_path,
+        jsonl_path,
+        isArchived,
+        created_at,
+        updated_at
+      )
+      SELECT
+        session_id,
+        provider,
+        custom_name,
+        project_path,
+        jsonl_path,
+        isArchived,
+        created_at,
+        updated_at
+      FROM ranked_rows
+      WHERE session_rank = 1
+    `);
+    db.exec('DROP TABLE sessions');
+    db.exec('ALTER TABLE sessions__new RENAME TO sessions');
+    db.exec('COMMIT');
+  } catch (migrationError) {
+    db.exec('ROLLBACK');
+    throw migrationError;
+  } finally {
+    db.exec('PRAGMA foreign_keys = ON');
+  }
+};
+
+const ensureProjectsForSessionPaths = (db: Database): void => {
+  if (!tableExists(db, 'sessions')) {
+    return;
+  }
+
+  db.exec(`
+    INSERT INTO projects (project_id, project_path, custom_project_name, isStarred, isArchived)
+    SELECT
+      ${SQLITE_UUID_SQL},
+      project_path,
+      NULL,
+      0,
+      0
+    FROM sessions
+    WHERE project_path IS NOT NULL AND trim(project_path) <> ''
+    ON CONFLICT(project_path) DO NOTHING
+  `);
+};
+
+export const runMigrations = (db: Database) => {
+  try {
+    const usersTableInfo = db.prepare('PRAGMA table_info(users)').all() as { name: string }[];
+    const userColumnNames = usersTableInfo.map((column) => column.name);
+
+    addColumnToTableIfNotExists(db, 'users', userColumnNames, 'git_name', 'TEXT');
+    addColumnToTableIfNotExists(db, 'users', userColumnNames, 'git_email', 'TEXT');
+    addColumnToTableIfNotExists(
+      db,
+      'users',
+      userColumnNames,
+      'has_completed_onboarding',
+      'BOOLEAN DEFAULT 0'
+    );
+
+    db.exec(APP_CONFIG_TABLE_SCHEMA_SQL);
+    db.exec(USER_NOTIFICATION_PREFERENCES_TABLE_SCHEMA_SQL);
+    db.exec(VAPID_KEYS_TABLE_SCHEMA_SQL);
+    db.exec(PUSH_SUBSCRIPTIONS_TABLE_SCHEMA_SQL);
+    db.exec('CREATE INDEX IF NOT EXISTS idx_push_subscriptions_user_id ON push_subscriptions(user_id)');
+
+    db.exec(PROJECTS_TABLE_SCHEMA_SQL);
+    rebuildProjectsTableWithPrimaryKeySchema(db);
+
+    migrateLegacyWorkspaceTableIntoProjects(db);
+    rebuildSessionsTableWithProjectSchema(db);
+    migrateLegacySessionNames(db);
+    ensureProjectsForSessionPaths(db);
+
+    db.exec('CREATE INDEX IF NOT EXISTS idx_session_ids_lookup ON sessions(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_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)');
+
+    db.exec('DROP INDEX IF EXISTS idx_session_names_lookup');
+    db.exec('DROP INDEX IF EXISTS idx_sessions_workspace_path');
+    db.exec('DROP INDEX IF EXISTS idx_workspace_original_paths_is_starred');
+    db.exec('DROP INDEX IF EXISTS idx_workspace_original_paths_workspace_id');
+
+    if (tableExists(db, 'workspace_original_paths')) {
+      console.log('Running migration: Dropping legacy workspace_original_paths table');
+      db.exec('DROP TABLE workspace_original_paths');
+    }
+
+    db.exec(LAST_SCANNED_AT_SQL);
+    console.log('Database migrations completed successfully');
+  } catch (error: any) {
+    console.error('Error running migrations:', error.message);
+    throw error;
+  }
+};
diff --git a/server/modules/database/repositories/api-keys.ts b/server/modules/database/repositories/api-keys.ts
new file mode 100644
index 00000000..f2c06f07
--- /dev/null
+++ b/server/modules/database/repositories/api-keys.ts
@@ -0,0 +1,119 @@
+/**
+ * API keys repository.
+ *
+ * Manages API keys used for external/programmatic access to the backend.
+ * Keys are prefixed with `ck_` and tied to a user via foreign key.
+ */
+
+import crypto from 'crypto';
+
+import { getConnection } from '@/modules/database/connection.js';
+
+type ApiKeyRow = {
+  id: number;
+  key_name: string;
+  api_key: string;
+  created_at: string;
+  last_used: string | null;
+  is_active: number;
+};
+
+type CreateApiKeyResult = {
+  id: number | bigint;
+  keyName: string;
+  apiKey: string;
+};
+
+type ValidatedApiKeyUser = {
+  id: number;
+  username: string;
+  api_key_id: number;
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Generates a cryptographically random API key with the `ck_` prefix. */
+function generateApiKey(): string {
+  return 'ck_' + crypto.randomBytes(32).toString('hex');
+}
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+export const apiKeysDb = {
+  generateApiKey,
+
+  /** Creates a new API key for the given user and returns it for one-time display. */
+  createApiKey(userId: number, keyName: string): CreateApiKeyResult {
+    const db = getConnection();
+    const apiKey = generateApiKey();
+    const result = db
+      .prepare(
+        'INSERT INTO api_keys (user_id, key_name, api_key) VALUES (?, ?, ?)'
+      )
+      .run(userId, keyName, apiKey);
+    return { id: result.lastInsertRowid, keyName, apiKey };
+  },
+
+  /** Lists all API keys for a user, most recent first. */
+  getApiKeys(userId: number): ApiKeyRow[] {
+    const db = getConnection();
+    return db
+      .prepare(
+        'SELECT id, key_name, api_key, created_at, last_used, is_active FROM api_keys WHERE user_id = ? ORDER BY created_at DESC'
+      )
+      .all(userId) as ApiKeyRow[];
+  },
+
+  /**
+   * Validates an API key and resolves the owning user.
+   * If the key is valid, its `last_used` timestamp is updated as a side effect.
+   * Returns undefined when the key is invalid or the user is inactive.
+   */
+  validateApiKey(apiKey: string): ValidatedApiKeyUser | undefined {
+    const db = getConnection();
+    const row = db
+      .prepare(
+        `SELECT u.id, u.username, ak.id as api_key_id
+         FROM api_keys ak
+         JOIN users u ON ak.user_id = u.id
+         WHERE ak.api_key = ? AND ak.is_active = 1 AND u.is_active = 1`
+      )
+      .get(apiKey) as ValidatedApiKeyUser | undefined;
+
+    if (row) {
+      db.prepare(
+        'UPDATE api_keys SET last_used = CURRENT_TIMESTAMP WHERE id = ?'
+      ).run(row.api_key_id);
+    }
+
+    return row;
+  },
+
+  /** Permanently removes an API key. Returns true if a row was deleted. */
+  deleteApiKey(userId: number, apiKeyId: number): boolean {
+    const db = getConnection();
+    const result = db
+      .prepare('DELETE FROM api_keys WHERE id = ? AND user_id = ?')
+      .run(apiKeyId, userId);
+    return result.changes > 0;
+  },
+
+  /** Enables or disables an API key without deleting it. */
+  toggleApiKey(
+    userId: number,
+    apiKeyId: number,
+    isActive: boolean
+  ): boolean {
+    const db = getConnection();
+    const result = db
+      .prepare(
+        'UPDATE api_keys SET is_active = ? WHERE id = ? AND user_id = ?'
+      )
+      .run(isActive ? 1 : 0, apiKeyId, userId);
+    return result.changes > 0;
+  },
+};
diff --git a/server/modules/database/repositories/app-config.ts b/server/modules/database/repositories/app-config.ts
new file mode 100644
index 00000000..691a1b4e
--- /dev/null
+++ b/server/modules/database/repositories/app-config.ts
@@ -0,0 +1,53 @@
+/**
+ * App config repository.
+ *
+ * Key-value store for application-level configuration that persists
+ * across restarts (JWT secret, feature flags, etc.). Values are always
+ * stored as strings; callers handle parsing.
+ */
+
+import crypto from 'crypto';
+
+import { getConnection } from '@/modules/database/connection.js';
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+export const appConfigDb = {
+  /** Returns the stored value for a config key, or null if missing. */
+  get(key: string): string | null {
+    try {
+      const db = getConnection();
+      const row = db
+        .prepare('SELECT value FROM app_config WHERE key = ?')
+        .get(key) as { value: string } | undefined;
+      return row?.value ?? null;
+    } catch {
+      // Swallow errors so early-startup reads (e.g. JWT secret) do not crash.
+      return null;
+    }
+  },
+
+  /** Inserts or updates a config key (upsert). */
+  set(key: string, value: string): void {
+    const db = getConnection();
+    db.prepare(
+      'INSERT INTO app_config (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value'
+    ).run(key, value);
+  },
+
+  /**
+   * Returns the JWT signing secret, generating and persisting one
+   * if it does not already exist. This ensures the secret survives
+   * server restarts while being created automatically on first boot.
+   */
+  getOrCreateJwtSecret(): string {
+    let secret = appConfigDb.get('jwt_secret');
+    if (!secret) {
+      secret = crypto.randomBytes(64).toString('hex');
+      appConfigDb.set('jwt_secret', secret);
+    }
+    return secret;
+  },
+};
diff --git a/server/modules/database/repositories/credentials.ts b/server/modules/database/repositories/credentials.ts
new file mode 100644
index 00000000..8bb11107
--- /dev/null
+++ b/server/modules/database/repositories/credentials.ts
@@ -0,0 +1,106 @@
+/**
+ * User credentials repository.
+ *
+ * Manages external service tokens (GitHub, GitLab, Bitbucket, etc.)
+ * stored per-user. Each credential has a type discriminator so multiple
+ * credential kinds can coexist in the same table.
+ */
+
+import { getConnection } from '@/modules/database/connection.js';
+import type {
+  CreateCredentialResult,
+  CredentialPublicRow,
+} from '@/shared/types.js';
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+export const credentialsDb = {
+  /** Stores a new credential and returns a safe (no raw value) result. */
+  createCredential(
+    userId: number,
+    credentialName: string,
+    credentialType: string,
+    credentialValue: string,
+    description: string | null = null
+  ): CreateCredentialResult {
+    const db = getConnection();
+    const result = db
+      .prepare(
+        'INSERT INTO user_credentials (user_id, credential_name, credential_type, credential_value, description) VALUES (?, ?, ?, ?, ?)'
+      )
+      .run(userId, credentialName, credentialType, credentialValue, description);
+    return {
+      id: result.lastInsertRowid,
+      credentialName,
+      credentialType,
+    };
+  },
+
+  /**
+   * Lists credentials for a user (excluding raw values).
+   * Optionally filters by credential type (e.g. 'github_token').
+   */
+  getCredentials(
+    userId: number,
+    credentialType: string | null = null
+  ): CredentialPublicRow[] {
+    const db = getConnection();
+
+    if (credentialType) {
+      return db
+        .prepare(
+          'SELECT id, credential_name, credential_type, description, created_at, is_active FROM user_credentials WHERE user_id = ? AND credential_type = ? ORDER BY created_at DESC'
+        )
+        .all(userId, credentialType) as CredentialPublicRow[];
+    }
+
+    return db
+      .prepare(
+        'SELECT id, credential_name, credential_type, description, created_at, is_active FROM user_credentials WHERE user_id = ? ORDER BY created_at DESC'
+      )
+      .all(userId) as CredentialPublicRow[];
+  },
+
+  /**
+   * Returns the raw credential value for the most recent active
+   * credential of the given type, or null if none exists.
+   */
+  getActiveCredential(
+    userId: number,
+    credentialType: string
+  ): string | null {
+    const db = getConnection();
+    const row = db
+      .prepare(
+        'SELECT credential_value FROM user_credentials WHERE user_id = ? AND credential_type = ? AND is_active = 1 ORDER BY created_at DESC LIMIT 1'
+      )
+      .get(userId, credentialType) as { credential_value: string } | undefined;
+    return row?.credential_value ?? null;
+  },
+
+  /** Permanently removes a credential. Returns true if a row was deleted. */
+  deleteCredential(userId: number, credentialId: number): boolean {
+    const db = getConnection();
+    const result = db
+      .prepare('DELETE FROM user_credentials WHERE id = ? AND user_id = ?')
+      .run(credentialId, userId);
+    return result.changes > 0;
+  },
+
+  /** Enables or disables a credential without deleting it. */
+  toggleCredential(
+    userId: number,
+    credentialId: number,
+    isActive: boolean
+  ): boolean {
+    const db = getConnection();
+    const result = db
+      .prepare(
+        'UPDATE user_credentials SET is_active = ? WHERE id = ? AND user_id = ?'
+      )
+      .run(isActive ? 1 : 0, credentialId, userId);
+    return result.changes > 0;
+  },
+};
diff --git a/server/modules/database/repositories/github-tokens.ts b/server/modules/database/repositories/github-tokens.ts
new file mode 100644
index 00000000..475f515b
--- /dev/null
+++ b/server/modules/database/repositories/github-tokens.ts
@@ -0,0 +1,100 @@
+/**
+ * GitHub tokens repository.
+ *
+ * Backward-compatible helper layer over generic credentials storage.
+ * Tokens are stored in `user_credentials` with `credential_type = 'github_token'`.
+ */
+
+import { getConnection } from '@/modules/database/connection.js';
+import { credentialsDb } from '@/modules/database/repositories/credentials.js';
+import type {
+  CredentialPublicRow,
+  CreateCredentialResult,
+} from '@/shared/types.js';
+
+const GITHUB_TOKEN_TYPE = 'github_token';
+
+type CredentialRow = {
+  id: number;
+  user_id: number;
+  credential_name: string;
+  credential_type: string;
+  credential_value: string;
+  description: string | null;
+  created_at: string;
+  is_active: number;
+};
+
+type GithubTokenLookup = CredentialRow & {
+  github_token: string;
+};
+
+export const githubTokensDb = {
+  /** Creates a GitHub token credential entry. */
+  createGithubToken(
+    userId: number,
+    tokenName: string,
+    githubToken: string,
+    description: string | null = null
+  ): CreateCredentialResult {
+    return credentialsDb.createCredential(
+      userId,
+      tokenName,
+      GITHUB_TOKEN_TYPE,
+      githubToken,
+      description
+    );
+  },
+
+  /** Returns all GitHub tokens (safe shape: no credential value). */
+  getGithubTokens(userId: number): CredentialPublicRow[] {
+    return credentialsDb.getCredentials(userId, GITHUB_TOKEN_TYPE);
+  },
+
+  /** Returns the most recent active GitHub token value for a user. */
+  getActiveGithubToken(userId: number): string | null {
+    return credentialsDb.getActiveCredential(userId, GITHUB_TOKEN_TYPE);
+  },
+
+  /**
+   * Returns a specific active GitHub token row by id/user, including
+   * a `github_token` compatibility field.
+   */
+  getGithubTokenById(userId: number, tokenId: number): GithubTokenLookup | null {
+    const db = getConnection();
+    const row = db
+      .prepare(
+        `SELECT *
+         FROM user_credentials
+         WHERE id = ? AND user_id = ? AND credential_type = ? AND is_active = 1`
+      )
+      .get(tokenId, userId, GITHUB_TOKEN_TYPE) as CredentialRow | undefined;
+
+    if (!row) return null;
+
+    return {
+      ...row,
+      github_token: row.credential_value,
+    };
+  },
+
+  /** Updates active state for a GitHub token. */
+  updateGithubToken(
+    userId: number,
+    tokenId: number,
+    isActive: boolean
+  ): boolean {
+    return credentialsDb.toggleCredential(userId, tokenId, isActive);
+  },
+
+  /** Deletes a GitHub token. */
+  deleteGithubToken(userId: number, tokenId: number): boolean {
+    return credentialsDb.deleteCredential(userId, tokenId);
+  },
+
+  // Legacy alias used by existing routes
+  toggleGithubToken(userId: number, tokenId: number, isActive: boolean): boolean {
+    return githubTokensDb.updateGithubToken(userId, tokenId, isActive);
+  },
+};
+
diff --git a/server/modules/database/repositories/notification-preferences.ts b/server/modules/database/repositories/notification-preferences.ts
new file mode 100644
index 00000000..6ba21976
--- /dev/null
+++ b/server/modules/database/repositories/notification-preferences.ts
@@ -0,0 +1,103 @@
+/**
+ * Notification preferences repository.
+ *
+ * Stores per-user notification channel/event preferences as JSON.
+ */
+
+import { getConnection } from '@/modules/database/connection.js';
+
+type NotificationPreferences = {
+  channels: {
+    inApp: boolean;
+    webPush: boolean;
+  };
+  events: {
+    actionRequired: boolean;
+    stop: boolean;
+    error: boolean;
+  };
+};
+
+const DEFAULT_NOTIFICATION_PREFERENCES: NotificationPreferences = {
+  channels: {
+    inApp: false,
+    webPush: false,
+  },
+  events: {
+    actionRequired: true,
+    stop: true,
+    error: true,
+  },
+};
+
+function normalizeNotificationPreferences(value: unknown): NotificationPreferences {
+  const source = value && typeof value === 'object' ? (value as Record<string, any>) : {};
+
+  return {
+    channels: {
+      inApp: source.channels?.inApp === true,
+      webPush: source.channels?.webPush === true,
+    },
+    events: {
+      actionRequired: source.events?.actionRequired !== false,
+      stop: source.events?.stop !== false,
+      error: source.events?.error !== false,
+    },
+  };
+}
+
+export const notificationPreferencesDb = {
+  /** Returns the normalized preferences for a user, creating defaults on first read. */
+  getNotificationPreferences(userId: number): NotificationPreferences {
+    const db = getConnection();
+    const row = db
+      .prepare(
+        'SELECT preferences_json FROM user_notification_preferences WHERE user_id = ?'
+      )
+      .get(userId) as { preferences_json: string } | undefined;
+
+    if (!row) {
+      const defaults = normalizeNotificationPreferences(DEFAULT_NOTIFICATION_PREFERENCES);
+      db.prepare(
+        'INSERT INTO user_notification_preferences (user_id, preferences_json, updated_at) VALUES (?, ?, CURRENT_TIMESTAMP)'
+      ).run(userId, JSON.stringify(defaults));
+      return defaults;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(row.preferences_json);
+    } catch {
+      parsed = DEFAULT_NOTIFICATION_PREFERENCES;
+    }
+    return normalizeNotificationPreferences(parsed);
+  },
+
+  /** Upserts normalized preferences for a user and returns the stored value. */
+  updateNotificationPreferences(
+    userId: number,
+    preferences: unknown
+  ): NotificationPreferences {
+    const normalized = normalizeNotificationPreferences(preferences);
+    const db = getConnection();
+
+    db.prepare(
+      `INSERT INTO user_notification_preferences (user_id, preferences_json, updated_at)
+       VALUES (?, ?, CURRENT_TIMESTAMP)
+       ON CONFLICT(user_id) DO UPDATE SET
+         preferences_json = excluded.preferences_json,
+         updated_at = CURRENT_TIMESTAMP`
+    ).run(userId, JSON.stringify(normalized));
+
+    return normalized;
+  },
+
+  // Legacy aliases used by existing services/routes
+  getPreferences(userId: number): NotificationPreferences {
+    return notificationPreferencesDb.getNotificationPreferences(userId);
+  },
+  updatePreferences(userId: number, preferences: unknown): NotificationPreferences {
+    return notificationPreferencesDb.updateNotificationPreferences(userId, preferences);
+  },
+};
+
diff --git a/server/modules/database/repositories/projects.db.integration.test.ts b/server/modules/database/repositories/projects.db.integration.test.ts
new file mode 100644
index 00000000..6ccf0c21
--- /dev/null
+++ b/server/modules/database/repositories/projects.db.integration.test.ts
@@ -0,0 +1,72 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+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';
+
+async function withIsolatedDatabase(runTest: () => void | Promise<void>): Promise<void> {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const tempDirectory = await mkdtemp(path.join(tmpdir(), 'projects-db-'));
+  const databasePath = path.join(tempDirectory, 'auth.db');
+
+  closeConnection();
+  process.env.DATABASE_PATH = databasePath;
+  await initializeDatabase();
+
+  try {
+    await runTest();
+  } finally {
+    closeConnection();
+    if (previousDatabasePath === undefined) {
+      delete process.env.DATABASE_PATH;
+    } else {
+      process.env.DATABASE_PATH = previousDatabasePath;
+    }
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+}
+
+test('projectsDb.createProjectPath returns created for fresh paths', async () => {
+  await withIsolatedDatabase(() => {
+    const created = projectsDb.createProjectPath('/workspace/new-project');
+
+    assert.equal(created.outcome, 'created');
+    assert.ok(created.project);
+    assert.equal(created.project?.project_path, '/workspace/new-project');
+    assert.equal(created.project?.isArchived, 0);
+  });
+});
+
+test('projectsDb.createProjectPath returns reactivated_archived for archived duplicates', async () => {
+  await withIsolatedDatabase(() => {
+    const initial = projectsDb.createProjectPath('/workspace/archived-project', 'Archived Project');
+    assert.equal(initial.outcome, 'created');
+    assert.ok(initial.project);
+
+    projectsDb.updateProjectIsArchived('/workspace/archived-project', true);
+
+    const reused = projectsDb.createProjectPath('/workspace/archived-project', 'Renamed Project');
+    assert.equal(reused.outcome, 'reactivated_archived');
+    assert.ok(reused.project);
+    assert.equal(reused.project?.project_id, initial.project?.project_id);
+    assert.equal(reused.project?.isArchived, 0);
+  });
+});
+
+test('projectsDb.createProjectPath returns active_conflict for active duplicates', async () => {
+  await withIsolatedDatabase(() => {
+    const initial = projectsDb.createProjectPath('/workspace/active-project');
+    assert.equal(initial.outcome, 'created');
+    assert.ok(initial.project);
+
+    const conflict = projectsDb.createProjectPath('/workspace/active-project');
+    assert.equal(conflict.outcome, 'active_conflict');
+    assert.ok(conflict.project);
+    assert.equal(conflict.project?.project_id, initial.project?.project_id);
+    assert.equal(conflict.project?.isArchived, 0);
+  });
+});
diff --git a/server/modules/database/repositories/projects.db.ts b/server/modules/database/repositories/projects.db.ts
new file mode 100644
index 00000000..ddbec8fa
--- /dev/null
+++ b/server/modules/database/repositories/projects.db.ts
@@ -0,0 +1,196 @@
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+
+import { getConnection } from '@/modules/database/connection.js';
+import type { CreateProjectPathResult, ProjectRepositoryRow } from '@/shared/types.js';
+import { normalizeProjectPath } from '@/shared/utils.js';
+
+function normalizeProjectDisplayName(projectPath: string, customProjectName: string | null): string {
+    const trimmedCustomName = typeof customProjectName === 'string' ? customProjectName.trim() : '';
+    if (trimmedCustomName.length > 0) {
+        return trimmedCustomName;
+    }
+
+    const directoryName = path.basename(projectPath);
+    return directoryName || projectPath;
+}
+
+export const projectsDb = {
+    createProjectPath(projectPath: string, customProjectName: string | null = null): CreateProjectPathResult {
+        const db = getConnection();
+        const normalizedProjectPath = normalizeProjectPath(projectPath);
+        const normalizedProjectName = normalizeProjectDisplayName(normalizedProjectPath, customProjectName);
+        const attemptedId = randomUUID();
+        const row = db.prepare(`
+        INSERT INTO projects (project_id, project_path, custom_project_name, isArchived)
+            VALUES (?, ?, ?, 0)
+            ON CONFLICT(project_path) DO UPDATE SET
+            isArchived = 0
+            WHERE projects.isArchived = 1
+            RETURNING project_id, project_path, custom_project_name, isStarred, isArchived
+        `).get(attemptedId, normalizedProjectPath, normalizedProjectName) as ProjectRepositoryRow | undefined;
+
+        if (row) {
+            return {
+                outcome: row.project_id === attemptedId ? 'created' : 'reactivated_archived',
+                project: row,
+            };
+        }
+
+        const existingProject = projectsDb.getProjectPath(normalizedProjectPath);
+        return {
+            outcome: 'active_conflict',
+            project: existingProject,
+        };
+    },
+
+    getProjectPath(projectPath: string): ProjectRepositoryRow | null {
+        const db = getConnection();
+        const normalizedProjectPath = normalizeProjectPath(projectPath);
+        const row = db.prepare(`
+            SELECT project_id, project_path, custom_project_name, isStarred, isArchived
+            FROM projects
+            WHERE project_path = ?
+        `).get(normalizedProjectPath) as ProjectRepositoryRow | undefined;
+
+        return row ?? null;
+    },
+
+    getProjectById(projectId: string): ProjectRepositoryRow | null {
+        const db = getConnection();
+        const row = db.prepare(`
+            SELECT project_id, project_path, custom_project_name, isStarred, isArchived
+            FROM projects
+            WHERE project_id = ?
+        `).get(projectId) as ProjectRepositoryRow | undefined;
+
+        return row ?? null;
+    },
+
+    /**
+     * Resolve the absolute project directory from a database project_id.
+     *
+     * This is the canonical lookup used after the projectName → projectId migration:
+     * API routes receive the DB-assigned `projectId` and must resolve the real folder
+     * path through this helper before touching the filesystem. Returns `null` when the
+     * project row does not exist so callers can respond with a 404.
+     */
+    getProjectPathById(projectId: string): string | null {
+        const db = getConnection();
+        const row = db.prepare(`
+            SELECT project_path
+            FROM projects
+            WHERE project_id = ?
+        `).get(projectId) as Pick<ProjectRepositoryRow, 'project_path'> | undefined;
+
+        return row?.project_path ?? null;
+    },
+
+    getProjectPaths(): ProjectRepositoryRow[] {
+        const db = getConnection();
+        return db.prepare(`
+            SELECT project_id, project_path, custom_project_name, isStarred, isArchived
+            FROM projects
+            WHERE isArchived = 0
+        `).all() as ProjectRepositoryRow[];
+    },
+
+    /**
+     * Archived rows are queried separately so archive-focused UIs can present
+     * hidden workspaces without reintroducing them into the active sidebar list.
+     */
+    getArchivedProjectPaths(): ProjectRepositoryRow[] {
+        const db = getConnection();
+        return db.prepare(`
+            SELECT project_id, project_path, custom_project_name, isStarred, isArchived
+            FROM projects
+            WHERE isArchived = 1
+        `).all() as ProjectRepositoryRow[];
+    },
+
+    getCustomProjectName(projectPath: string): string | null {
+        const db = getConnection();
+        const normalizedProjectPath = normalizeProjectPath(projectPath);
+        const row = db.prepare(`
+            SELECT custom_project_name
+            FROM projects
+            WHERE project_path = ?
+        `).get(normalizedProjectPath) as Pick<ProjectRepositoryRow, 'custom_project_name'> | undefined;
+
+        return row?.custom_project_name ?? null;
+    },
+
+    updateCustomProjectName(projectPath: string, customProjectName: string | null): void {
+        const db = getConnection();
+        const normalizedProjectPath = normalizeProjectPath(projectPath);
+        db.prepare(`
+            INSERT INTO projects (project_id, project_path, custom_project_name)
+            VALUES (?, ?, ?)
+            ON CONFLICT(project_path) DO UPDATE SET custom_project_name = excluded.custom_project_name
+        `).run(randomUUID(), normalizedProjectPath, customProjectName);
+    },
+
+    updateCustomProjectNameById(projectId: string, customProjectName: string | null): void {
+        const db = getConnection();
+        db.prepare(`
+            UPDATE projects
+            SET custom_project_name = ?
+            WHERE project_id = ?
+        `).run(customProjectName, projectId);
+    },
+
+    updateProjectIsStarred(projectPath: string, isStarred: boolean): void {
+        const db = getConnection();
+        const normalizedProjectPath = normalizeProjectPath(projectPath);
+        db.prepare(`
+            UPDATE projects
+            SET isStarred = ?
+            WHERE project_path = ?
+        `).run(isStarred ? 1 : 0, normalizedProjectPath);
+    },
+
+    updateProjectIsStarredById(projectId: string, isStarred: boolean): void {
+        const db = getConnection();
+        db.prepare(`
+            UPDATE projects
+            SET isStarred = ?
+            WHERE project_id = ?
+        `).run(isStarred ? 1 : 0, projectId);
+    },
+
+    updateProjectIsArchived(projectPath: string, isArchived: boolean): void {
+        const db = getConnection();
+        const normalizedProjectPath = normalizeProjectPath(projectPath);
+        db.prepare(`
+            UPDATE projects
+            SET isArchived = ?
+            WHERE project_path = ?
+        `).run(isArchived ? 1 : 0, normalizedProjectPath);
+    },
+
+    updateProjectIsArchivedById(projectId: string, isArchived: boolean): void {
+        const db = getConnection();
+        db.prepare(`
+            UPDATE projects
+            SET isArchived = ?
+            WHERE project_id = ?
+        `).run(isArchived ? 1 : 0, projectId);
+    },
+
+    deleteProjectPath(projectPath: string): void {
+        const db = getConnection();
+        const normalizedProjectPath = normalizeProjectPath(projectPath);
+        db.prepare(`
+            DELETE FROM projects
+            WHERE project_path = ?
+        `).run(normalizedProjectPath);
+    },
+
+    deleteProjectById(projectId: string): void {
+        const db = getConnection();
+        db.prepare(`
+            DELETE FROM projects
+            WHERE project_id = ?
+        `).run(projectId);
+    },
+};
diff --git a/server/modules/database/repositories/push-subscriptions.ts b/server/modules/database/repositories/push-subscriptions.ts
new file mode 100644
index 00000000..91ef044c
--- /dev/null
+++ b/server/modules/database/repositories/push-subscriptions.ts
@@ -0,0 +1,80 @@
+/**
+ * Push subscriptions repository.
+ *
+ * Persists browser push subscription endpoints and keys per user.
+ */
+
+import { getConnection } from '@/modules/database/connection.js';
+
+type PushSubscriptionLookupRow = {
+  endpoint: string;
+  keys_p256dh: string;
+  keys_auth: string;
+};
+
+export const pushSubscriptionsDb = {
+  /** Upserts a push subscription endpoint for a user. */
+  createPushSubscription(
+    userId: number,
+    endpoint: string,
+    keysP256dh: string,
+    keysAuth: string
+  ): void {
+    const db = getConnection();
+    db.prepare(
+      `INSERT INTO push_subscriptions (user_id, endpoint, keys_p256dh, keys_auth)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(endpoint) DO UPDATE SET
+         user_id = excluded.user_id,
+         keys_p256dh = excluded.keys_p256dh,
+         keys_auth = excluded.keys_auth`
+    ).run(userId, endpoint, keysP256dh, keysAuth);
+  },
+
+  /** Returns all subscriptions for a user. */
+  getPushSubscriptions(userId: number): PushSubscriptionLookupRow[] {
+    const db = getConnection();
+    return db
+      .prepare(
+        'SELECT endpoint, keys_p256dh, keys_auth FROM push_subscriptions WHERE user_id = ?'
+      )
+      .all(userId) as PushSubscriptionLookupRow[];
+  },
+
+  /** Deletes one subscription by endpoint. */
+  deletePushSubscription(endpoint: string): void {
+    const db = getConnection();
+    db.prepare('DELETE FROM push_subscriptions WHERE endpoint = ?').run(endpoint);
+  },
+
+  /** Deletes all subscriptions for a user. */
+  deletePushSubscriptionsForUser(userId: number): void {
+    const db = getConnection();
+    db.prepare('DELETE FROM push_subscriptions WHERE user_id = ?').run(userId);
+  },
+
+  // Legacy aliases used by existing services/routes
+  saveSubscription(
+    userId: number,
+    endpoint: string,
+    keysP256dh: string,
+    keysAuth: string
+  ): void {
+    pushSubscriptionsDb.createPushSubscription(
+      userId,
+      endpoint,
+      keysP256dh,
+      keysAuth
+    );
+  },
+  getSubscriptions(userId: number): PushSubscriptionLookupRow[] {
+    return pushSubscriptionsDb.getPushSubscriptions(userId);
+  },
+  removeSubscription(endpoint: string): void {
+    pushSubscriptionsDb.deletePushSubscription(endpoint);
+  },
+  removeAllForUser(userId: number): void {
+    pushSubscriptionsDb.deletePushSubscriptionsForUser(userId);
+  },
+};
+
diff --git a/server/modules/database/repositories/scan-state.db.ts b/server/modules/database/repositories/scan-state.db.ts
new file mode 100644
index 00000000..5e93940c
--- /dev/null
+++ b/server/modules/database/repositories/scan-state.db.ts
@@ -0,0 +1,42 @@
+import { getConnection } from '@/modules/database/connection.js';
+
+type ScanStateRow = {
+  last_scanned_at: string;
+};
+
+export const scanStateDb = {
+    getLastScannedAt() {
+        const db = getConnection();
+
+        const row = db
+            .prepare(`SELECT last_scanned_at FROM scan_state WHERE id = 1`)
+            .get() as ScanStateRow;
+
+        if (!row) {
+            return null; // Before any scan, the row is undefined.
+        }
+
+        let lastScannedDate: Date | null = null;
+        const lastScannedStr = row.last_scanned_at;
+
+        if (lastScannedStr) {
+            // SQLite CURRENT_TIMESTAMP returns UTC in "YYYY-MM-DD HH:MM:SS" format.
+            // Replace space with 'T' and append 'Z' to parse reliably in JS across all platforms.
+            lastScannedDate = new Date(lastScannedStr.replace(' ', 'T') + 'Z');
+        }
+
+        return lastScannedDate;
+    },
+
+    updateLastScannedAt(scannedAt: Date = new Date()) {
+        const db = getConnection();
+        const sqliteTimestamp = scannedAt.toISOString().slice(0, 19).replace('T', ' ');
+
+        db.prepare(`
+            INSERT INTO scan_state (id, last_scanned_at)
+            VALUES (1, ?)
+            ON CONFLICT (id)
+            DO UPDATE SET last_scanned_at = excluded.last_scanned_at
+        `).run(sqliteTimestamp);
+    }
+};
diff --git a/server/modules/database/repositories/sessions.db.integration.test.ts b/server/modules/database/repositories/sessions.db.integration.test.ts
new file mode 100644
index 00000000..d14ec5ae
--- /dev/null
+++ b/server/modules/database/repositories/sessions.db.integration.test.ts
@@ -0,0 +1,72 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { closeConnection } from '@/modules/database/connection.js';
+import { initializeDatabase } from '@/modules/database/init-db.js';
+import { sessionsDb } from '@/modules/database/repositories/sessions.db.js';
+
+async function withIsolatedDatabase(runTest: () => void | Promise<void>): Promise<void> {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const tempDirectory = await mkdtemp(path.join(tmpdir(), 'sessions-db-'));
+  const databasePath = path.join(tempDirectory, 'auth.db');
+
+  closeConnection();
+  process.env.DATABASE_PATH = databasePath;
+  await initializeDatabase();
+
+  try {
+    await runTest();
+  } finally {
+    closeConnection();
+    if (previousDatabasePath === undefined) {
+      delete process.env.DATABASE_PATH;
+    } else {
+      process.env.DATABASE_PATH = previousDatabasePath;
+    }
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+}
+
+test('session archive queries hide archived rows from active project views', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createSession('session-active', 'claude', '/workspace/demo-project', 'Active Session');
+    sessionsDb.createSession('session-archived', 'claude', '/workspace/demo-project', 'Archived Session');
+    sessionsDb.updateSessionIsArchived('session-archived', true);
+
+    const activeSessions = sessionsDb.getAllSessions();
+    const archivedSessions = sessionsDb.getArchivedSessions();
+    const activeProjectSessions = sessionsDb.getSessionsByProjectPath('/workspace/demo-project');
+    const allProjectSessions = sessionsDb.getSessionsByProjectPathIncludingArchived('/workspace/demo-project');
+
+    assert.deepEqual(activeSessions.map((session) => session.session_id), ['session-active']);
+    assert.deepEqual(archivedSessions.map((session) => session.session_id), ['session-archived']);
+    assert.deepEqual(activeProjectSessions.map((session) => session.session_id), ['session-active']);
+    assert.deepEqual(
+      allProjectSessions.map((session) => session.session_id).sort(),
+      ['session-active', 'session-archived'],
+    );
+    assert.equal(sessionsDb.countSessionsByProjectPath('/workspace/demo-project'), 1);
+  });
+});
+
+test('createSession reactivates archived rows when the session becomes active again', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createSession('session-reused', 'claude', '/workspace/demo-project', 'First Name');
+    sessionsDb.updateSessionIsArchived('session-reused', true);
+
+    sessionsDb.createSession('session-reused', 'claude', '/workspace/demo-project', 'Updated Name');
+
+    const activeSessions = sessionsDb.getAllSessions();
+    const archivedSessions = sessionsDb.getArchivedSessions();
+    const restoredSession = sessionsDb.getSessionById('session-reused');
+
+    assert.equal(activeSessions.length, 1);
+    assert.equal(activeSessions[0]?.session_id, 'session-reused');
+    assert.equal(activeSessions[0]?.custom_name, 'Updated Name');
+    assert.equal(archivedSessions.length, 0);
+    assert.equal(restoredSession?.isArchived, 0);
+  });
+});
diff --git a/server/modules/database/repositories/sessions.db.ts b/server/modules/database/repositories/sessions.db.ts
new file mode 100644
index 00000000..d79fdeb8
--- /dev/null
+++ b/server/modules/database/repositories/sessions.db.ts
@@ -0,0 +1,225 @@
+import { getConnection } from '@/modules/database/connection.js';
+import { projectsDb } from '@/modules/database/repositories/projects.db.js';
+import { normalizeProjectPath } from '@/shared/utils.js';
+
+type SessionRow = {
+  session_id: string;
+  provider: string;
+  project_path: string | null;
+  jsonl_path: string | null;
+  custom_name: string | null;
+  isArchived: number;
+  created_at: string;
+  updated_at: string;
+};
+
+type SessionMetadataLookupRow = Pick<
+  SessionRow,
+  'session_id' | 'provider' | 'project_path' | 'jsonl_path' | 'custom_name' | 'isArchived' | 'created_at' | 'updated_at'
+>;
+
+function normalizeTimestamp(value?: string): string | null {
+  if (!value) return null;
+
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    return null;
+  }
+
+  return parsed.toISOString();
+}
+
+function normalizeProjectPathForProvider(provider: string, projectPath: string): string {
+  void provider;
+  return normalizeProjectPath(projectPath);
+}
+
+export const sessionsDb = {
+  createSession(
+    sessionId: string,
+    provider: string,
+    projectPath: string,
+    customName?: string,
+    createdAt?: string,
+    updatedAt?: string,
+    jsonlPath?: string | null
+  ): string {
+    const db = getConnection();
+    const createdAtValue = normalizeTimestamp(createdAt);
+    const updatedAtValue = normalizeTimestamp(updatedAt);
+    const normalizedProjectPath = normalizeProjectPathForProvider(provider, projectPath);
+
+    // First, ensure the project path is recorded in the projects table,
+    // since it's a foreign key in the sessions table.
+    projectsDb.createProjectPath(normalizedProjectPath);
+
+    db.prepare(
+      `INSERT INTO sessions (session_id, provider, custom_name, project_path, jsonl_path, isArchived, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, 0, COALESCE(?, CURRENT_TIMESTAMP), COALESCE(?, CURRENT_TIMESTAMP))
+       ON CONFLICT(session_id) DO UPDATE SET
+         provider = excluded.provider,
+         updated_at = excluded.updated_at,
+         project_path = excluded.project_path,
+         jsonl_path = excluded.jsonl_path,
+         isArchived = 0,
+         custom_name = COALESCE(excluded.custom_name, sessions.custom_name)`
+    ).run(
+      sessionId,
+      provider,
+      customName ?? null,
+      normalizedProjectPath,
+      jsonlPath ?? null,
+      createdAtValue,
+      updatedAtValue
+    );
+
+    return sessionId;
+  },
+
+  updateSessionCustomName(sessionId: string, customName: string): void {
+    const db = getConnection();
+    db.prepare(
+      `UPDATE sessions
+       SET custom_name = ?
+       WHERE session_id = ?`
+    ).run(customName, sessionId);
+  },
+
+  getSessionById(sessionId: string): SessionMetadataLookupRow | null {
+    const db = getConnection();
+    const row = db
+      .prepare(
+        `SELECT session_id, provider, project_path, jsonl_path, custom_name, isArchived, created_at, updated_at
+         FROM sessions
+         WHERE session_id = ?
+         ORDER BY updated_at DESC
+         LIMIT 1`
+      )
+      .get(sessionId) as SessionMetadataLookupRow | undefined;
+
+    return row ?? null;
+  },
+
+  getAllSessions(): SessionRow[] {
+    const db = getConnection();
+    return db
+      .prepare(
+        `SELECT session_id, provider, project_path, jsonl_path, custom_name, isArchived, created_at, updated_at
+         FROM sessions
+         WHERE isArchived = 0`
+      )
+      .all() as SessionRow[];
+  },
+
+  /**
+   * Archived rows are intentionally queried separately so the caller can render
+   * them in a dedicated view without reintroducing them into active session lists.
+   */
+  getArchivedSessions(): SessionRow[] {
+    const db = getConnection();
+    return db
+      .prepare(
+        `SELECT session_id, provider, project_path, jsonl_path, custom_name, isArchived, created_at, updated_at
+         FROM sessions
+         WHERE isArchived = 1
+         ORDER BY datetime(COALESCE(updated_at, created_at)) DESC, session_id DESC`
+      )
+      .all() as SessionRow[];
+  },
+
+  getSessionsByProjectPath(projectPath: string): SessionRow[] {
+    const db = getConnection();
+    const normalizedProjectPath = normalizeProjectPath(projectPath);
+    return db
+      .prepare(
+        `SELECT session_id, provider, project_path, jsonl_path, custom_name, isArchived, created_at, updated_at
+         FROM sessions
+         WHERE project_path = ?
+           AND isArchived = 0`
+      )
+      .all(normalizedProjectPath) as SessionRow[];
+  },
+
+  /**
+   * Permanent project deletion must see every session row for the path,
+   * including archived ones, so their transcript files can be cleaned up.
+   */
+  getSessionsByProjectPathIncludingArchived(projectPath: string): SessionRow[] {
+    const db = getConnection();
+    const normalizedProjectPath = normalizeProjectPath(projectPath);
+    return db
+      .prepare(
+        `SELECT session_id, provider, project_path, jsonl_path, custom_name, isArchived, created_at, updated_at
+         FROM sessions
+         WHERE project_path = ?`
+      )
+      .all(normalizedProjectPath) as SessionRow[];
+  },
+
+  getSessionsByProjectPathPage(projectPath: string, limit: number, offset: number): SessionRow[] {
+    const db = getConnection();
+    const normalizedProjectPath = normalizeProjectPath(projectPath);
+    return db
+      .prepare(
+        `SELECT session_id, provider, project_path, jsonl_path, custom_name, isArchived, created_at, updated_at
+         FROM sessions
+         WHERE project_path = ?
+           AND isArchived = 0
+         ORDER BY datetime(COALESCE(updated_at, created_at)) DESC, session_id DESC
+         LIMIT ? OFFSET ?`
+      )
+      .all(normalizedProjectPath, limit, offset) as SessionRow[];
+  },
+
+  countSessionsByProjectPath(projectPath: string): number {
+    const db = getConnection();
+    const normalizedProjectPath = normalizeProjectPath(projectPath);
+    const row = db
+      .prepare(
+        `SELECT COUNT(*) AS count
+         FROM sessions
+         WHERE project_path = ?
+           AND isArchived = 0`
+      )
+      .get(normalizedProjectPath) as { count: number } | undefined;
+
+    return Number(row?.count ?? 0);
+  },
+
+  deleteSessionsByProjectPath(projectPath: string): void {
+    const db = getConnection();
+    const normalizedProjectPath = normalizeProjectPath(projectPath);
+    db.prepare(`DELETE FROM sessions WHERE project_path = ?`).run(normalizedProjectPath);
+  },
+
+  getSessionName(sessionId: string, provider: string): string | null {
+    const db = getConnection();
+    const row = db
+      .prepare(
+        `SELECT custom_name
+         FROM sessions
+         WHERE session_id = ? AND provider = ?`
+      )
+      .get(sessionId, provider) as { custom_name: string | null } | undefined;
+
+    return row?.custom_name ?? null;
+  },
+
+  /**
+   * Soft-delete and restore both use the same flag update so callers keep the
+   * row, metadata, and file path intact while toggling visibility.
+   */
+  updateSessionIsArchived(sessionId: string, isArchived: boolean): void {
+    const db = getConnection();
+    db.prepare(
+      `UPDATE sessions
+       SET isArchived = ?
+       WHERE session_id = ?`
+    ).run(isArchived ? 1 : 0, sessionId);
+  },
+
+  deleteSessionById(sessionId: string): boolean {
+    const db = getConnection();
+    return db.prepare('DELETE FROM sessions WHERE session_id = ?').run(sessionId).changes > 0;
+  },
+};
diff --git a/server/modules/database/repositories/users.ts b/server/modules/database/repositories/users.ts
new file mode 100644
index 00000000..25bb57bd
--- /dev/null
+++ b/server/modules/database/repositories/users.ts
@@ -0,0 +1,140 @@
+/**
+ * User repository.
+ *
+ * Provides typed CRUD operations for the `users` table.
+ * This is a single-user system, but the schema supports multiple
+ * users for forward compatibility.
+ */
+
+import { getConnection } from '@/modules/database/connection.js';
+
+type UserRow = {
+  id: number;
+  username: string;
+  password_hash: string;
+  created_at: string;
+  last_login: string | null;
+  is_active: number;
+  git_name: string | null;
+  git_email: string | null;
+  has_completed_onboarding: number;
+};
+
+type UserPublicRow = Pick<UserRow, 'id' | 'username' | 'created_at' | 'last_login'>;
+
+type UserGitConfig = {
+  git_name: string | null;
+  git_email: string | null;
+};
+
+type CreateUserResult = {
+  id: number | bigint;
+  username: string;
+};
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+export const userDb = {
+  /** Returns true if at least one user exists in the database. */
+  hasUsers(): boolean {
+    const db = getConnection();
+    const row = db.prepare('SELECT COUNT(*) as count FROM users').get() as {
+      count: number;
+    };
+    return row.count > 0;
+  },
+
+  /** Inserts a new user and returns the created ID + username. */
+  createUser(username: string, passwordHash: string): CreateUserResult {
+    const db = getConnection();
+    const result = db
+      .prepare('INSERT INTO users (username, password_hash) VALUES (?, ?)')
+      .run(username, passwordHash);
+    return { id: result.lastInsertRowid, username };
+  },
+
+  /**
+   * Looks up an active user by username.
+   * Returns the full row (including password hash) for auth verification.
+   */
+  getUserByUsername(username: string): UserRow | undefined {
+    const db = getConnection();
+    return db
+      .prepare('SELECT * FROM users WHERE username = ? AND is_active = 1')
+      .get(username) as UserRow | undefined;
+  },
+
+  /** Updates the last_login timestamp. Non-fatal — logs but does not throw. */
+  updateLastLogin(userId: number): void {
+    try {
+      const db = getConnection();
+      db.prepare(
+        'UPDATE users SET last_login = CURRENT_TIMESTAMP WHERE id = ?'
+      ).run(userId);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error('Failed to update last login', { error: message });
+    }
+  },
+
+  /** Returns public user fields by ID (no password hash). */
+  getUserById(userId: number): UserPublicRow | undefined {
+    const db = getConnection();
+    return db
+      .prepare(
+        'SELECT id, username, created_at, last_login FROM users WHERE id = ? AND is_active = 1'
+      )
+      .get(userId) as UserPublicRow | undefined;
+  },
+
+  /** Returns the first active user. Used for single-user mode lookups. */
+  getFirstUser(): UserPublicRow | undefined {
+    const db = getConnection();
+    return db
+      .prepare(
+        'SELECT id, username, created_at, last_login FROM users WHERE is_active = 1 LIMIT 1'
+      )
+      .get() as UserPublicRow | undefined;
+  },
+
+  /** Stores the user's preferred git name and email. */
+  updateGitConfig(
+    userId: number,
+    gitName: string,
+    gitEmail: string
+  ): void {
+    const db = getConnection();
+    db.prepare('UPDATE users SET git_name = ?, git_email = ? WHERE id = ?').run(
+      gitName,
+      gitEmail,
+      userId
+    );
+  },
+
+  /** Retrieves the user's git identity (name + email). */
+  getGitConfig(userId: number): UserGitConfig | undefined {
+    const db = getConnection();
+    return db
+      .prepare('SELECT git_name, git_email FROM users WHERE id = ?')
+      .get(userId) as UserGitConfig | undefined;
+  },
+
+  /** Marks onboarding as complete for the given user. */
+  completeOnboarding(userId: number): void {
+    const db = getConnection();
+    db.prepare(
+      'UPDATE users SET has_completed_onboarding = 1 WHERE id = ?'
+    ).run(userId);
+  },
+
+  /** Returns true if the user has finished the onboarding flow. */
+  hasCompletedOnboarding(userId: number): boolean {
+    const db = getConnection();
+    const row = db
+      .prepare('SELECT has_completed_onboarding FROM users WHERE id = ?')
+      .get(userId) as { has_completed_onboarding: number } | undefined;
+    return row?.has_completed_onboarding === 1;
+  },
+};
diff --git a/server/modules/database/repositories/vapid-keys.ts b/server/modules/database/repositories/vapid-keys.ts
new file mode 100644
index 00000000..13faeb34
--- /dev/null
+++ b/server/modules/database/repositories/vapid-keys.ts
@@ -0,0 +1,57 @@
+/**
+ * VAPID keys repository.
+ *
+ * Stores and retrieves the Web Push VAPID key pair.
+ */
+
+import { getConnection } from '@/modules/database/connection.js';
+
+type VapidKeyRow = {
+  public_key: string;
+  private_key: string;
+};
+
+type VapidKeyPair = {
+  publicKey: string;
+  privateKey: string;
+};
+
+export const vapidKeysDb = {
+  /** Returns the latest stored VAPID key pair, or null when unset. */
+  getVapidKeys(): VapidKeyPair | null {
+    const db = getConnection();
+    const row = db
+      .prepare(
+        'SELECT public_key, private_key FROM vapid_keys ORDER BY id DESC LIMIT 1'
+      )
+      .get() as Pick<VapidKeyRow, 'public_key' | 'private_key'> | undefined;
+
+    if (!row) return null;
+    return {
+      publicKey: row.public_key,
+      privateKey: row.private_key,
+    };
+  },
+
+  /** Persists a new VAPID key pair. */
+  createVapidKeys(publicKey: string, privateKey: string): void {
+    const db = getConnection();
+    db.prepare(
+      'INSERT INTO vapid_keys (public_key, private_key) VALUES (?, ?)'
+    ).run(publicKey, privateKey);
+  },
+
+  /** Replaces all existing keys with a fresh pair. */
+  updateVapidKeys(publicKey: string, privateKey: string): void {
+    const db = getConnection();
+    db.prepare('DELETE FROM vapid_keys').run();
+    vapidKeysDb.createVapidKeys(publicKey, privateKey);
+  },
+
+  /** Deletes all VAPID key rows. */
+  deleteVapidKeys(): void {
+    const db = getConnection();
+    db.prepare('DELETE FROM vapid_keys').run();
+  },
+};
+
diff --git a/server/modules/database/schema.ts b/server/modules/database/schema.ts
new file mode 100644
index 00000000..b3639af2
--- /dev/null
+++ b/server/modules/database/schema.ts
@@ -0,0 +1,153 @@
+const USER_TABLE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    username TEXT UNIQUE NOT NULL,
+    password_hash TEXT NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    last_login DATETIME,
+    is_active BOOLEAN DEFAULT 1,
+    git_name TEXT,
+    git_email TEXT,
+    has_completed_onboarding BOOLEAN DEFAULT 0
+);
+`;
+
+export const API_KEYS_TABLE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS api_keys (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id INTEGER NOT NULL,
+    key_name TEXT NOT NULL,
+    api_key TEXT UNIQUE NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    last_used DATETIME,
+    is_active BOOLEAN DEFAULT 1,
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+`;
+
+export const USER_CREDENTIALS_TABLE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS user_credentials (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id INTEGER NOT NULL,
+    credential_name TEXT NOT NULL,
+    credential_type TEXT NOT NULL, -- 'github_token', 'gitlab_token', 'bitbucket_token', etc.
+    credential_value TEXT NOT NULL,
+    description TEXT,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    is_active BOOLEAN DEFAULT 1,
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+`;
+
+export const USER_NOTIFICATION_PREFERENCES_TABLE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS user_notification_preferences (
+    user_id INTEGER PRIMARY KEY,
+    preferences_json TEXT NOT NULL,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+`;
+
+export const VAPID_KEYS_TABLE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS vapid_keys (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    public_key TEXT NOT NULL,
+    private_key TEXT NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+`;
+
+export const PUSH_SUBSCRIPTIONS_TABLE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS push_subscriptions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id INTEGER NOT NULL,
+    endpoint TEXT NOT NULL UNIQUE,
+    keys_p256dh TEXT NOT NULL,
+    keys_auth TEXT NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+`;
+
+export const PROJECTS_TABLE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS projects (
+    project_id TEXT PRIMARY KEY NOT NULL,
+    project_path TEXT NOT NULL UNIQUE,
+    custom_project_name TEXT DEFAULT NULL,
+    isStarred BOOLEAN DEFAULT 0,
+    isArchived BOOLEAN DEFAULT 0
+);
+`;
+
+export const SESSIONS_TABLE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS sessions (
+    session_id TEXT NOT NULL,
+    provider TEXT NOT NULL DEFAULT 'claude',
+    custom_name TEXT,
+    project_path TEXT,
+    jsonl_path TEXT,
+    isArchived BOOLEAN DEFAULT 0,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    PRIMARY KEY (session_id),
+    FOREIGN KEY (project_path) REFERENCES projects(project_path)
+    ON DELETE SET NULL
+    ON UPDATE CASCADE
+);
+`;
+
+export const LAST_SCANNED_AT_SQL = `
+CREATE TABLE IF NOT EXISTS scan_state (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  last_scanned_at TIMESTAMP NULL
+);
+`;
+
+export const APP_CONFIG_TABLE_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS app_config (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+`;
+
+export const INIT_SCHEMA_SQL = `
+-- Initialize authentication database
+PRAGMA foreign_keys = ON;
+
+${USER_TABLE_SCHEMA_SQL}
+-- Indexes for performance for user lookups
+CREATE INDEX IF NOT EXISTS idx_users_username ON users(username);
+CREATE INDEX IF NOT EXISTS idx_users_active ON users(is_active);
+
+${API_KEYS_TABLE_SCHEMA_SQL}
+CREATE INDEX IF NOT EXISTS idx_api_keys_key ON api_keys(api_key);
+CREATE INDEX IF NOT EXISTS idx_api_keys_user_id ON api_keys(user_id);
+CREATE INDEX IF NOT EXISTS idx_api_keys_active ON api_keys(is_active);
+
+${USER_CREDENTIALS_TABLE_SCHEMA_SQL}
+CREATE INDEX IF NOT EXISTS idx_user_credentials_user_id ON user_credentials(user_id);
+CREATE INDEX IF NOT EXISTS idx_user_credentials_type ON user_credentials(credential_type);
+CREATE INDEX IF NOT EXISTS idx_user_credentials_active ON user_credentials(is_active);
+
+${USER_NOTIFICATION_PREFERENCES_TABLE_SCHEMA_SQL}
+CREATE INDEX IF NOT EXISTS idx_user_notification_preferences_user_id ON user_notification_preferences(user_id);
+
+${VAPID_KEYS_TABLE_SCHEMA_SQL}
+
+${PUSH_SUBSCRIPTIONS_TABLE_SCHEMA_SQL}
+CREATE INDEX IF NOT EXISTS idx_push_subscriptions_user_id ON push_subscriptions(user_id);
+
+${PROJECTS_TABLE_SCHEMA_SQL}
+-- NOTE: These indexes are created in migrations after legacy table-shape repairs.
+-- Creating them here can fail on upgraded installs where projects lacks those columns.
+
+${SESSIONS_TABLE_SCHEMA_SQL}
+CREATE INDEX IF NOT EXISTS idx_session_ids_lookup ON sessions(session_id);
+-- NOTE: This index is created in migrations after sessions is rebuilt to include project_path.
+-- Creating it here can fail on upgraded installs where the legacy sessions table has no project_path.
+
+${LAST_SCANNED_AT_SQL}
+
+${APP_CONFIG_TABLE_SCHEMA_SQL}
+`;
diff --git a/server/modules/projects/index.ts b/server/modules/projects/index.ts
new file mode 100644
index 00000000..2adbf7a5
--- /dev/null
+++ b/server/modules/projects/index.ts
@@ -0,0 +1,6 @@
+export {
+  generateDisplayName,
+  getProjectsWithSessions,
+} from './services/projects-with-sessions-fetch.service.js';
+export { updateProjectDisplayName } from './services/project-management.service.js';
+export { deleteOrArchiveProject, deleteSessionJsonlFilesForProjectPath } from './services/project-delete.service.js';
diff --git a/server/modules/projects/projects.routes.ts b/server/modules/projects/projects.routes.ts
new file mode 100644
index 00000000..5b52425c
--- /dev/null
+++ b/server/modules/projects/projects.routes.ts
@@ -0,0 +1,264 @@
+import express from 'express';
+
+import { createProject, updateProjectDisplayName } from '@/modules/projects/services/project-management.service.js';
+import { startCloneProject } from '@/modules/projects/services/project-clone.service.js';
+import { getProjectTaskMaster } from '@/modules/projects/services/projects-has-taskmaster.service.js';
+import { AppError, asyncHandler, createApiSuccessResponse } from '@/shared/utils.js';
+import { getArchivedProjectsWithSessions, getProjectSessionsPage, getProjectsWithSessions } from '@/modules/projects/services/projects-with-sessions-fetch.service.js';
+import { deleteOrArchiveProject, restoreArchivedProject } from '@/modules/projects/services/project-delete.service.js';
+import { applyLegacyStarredProjectIds, toggleProjectStar } from '@/modules/projects/services/project-star.service.js';
+
+const router = express.Router();
+
+type AuthenticatedUser = {
+  id?: number | string;
+};
+
+function readQueryStringValue(value: unknown): string {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  if (Array.isArray(value) && typeof value[0] === 'string') {
+    return value[0];
+  }
+
+  return '';
+}
+
+function readOptionalNumericQueryValue(value: unknown): number | null {
+  const rawValue = readQueryStringValue(value).trim();
+  if (!rawValue) {
+    return null;
+  }
+
+  const parsedValue = Number.parseInt(rawValue, 10);
+  return Number.isNaN(parsedValue) ? null : parsedValue;
+}
+
+function parseNonNegativeIntQuery(value: unknown, name: string, fallback: number): number {
+  const rawValue = readQueryStringValue(value).trim();
+  if (!rawValue) {
+    return fallback;
+  }
+
+  const parsedValue = Number.parseInt(rawValue, 10);
+  if (Number.isNaN(parsedValue) || parsedValue < 0) {
+    throw new AppError(`${name} must be a non-negative integer`, {
+      code: 'INVALID_QUERY_PARAMETER',
+      statusCode: 400,
+    });
+  }
+
+  return parsedValue;
+}
+
+function resolveRouteErrorMessage(error: unknown): string {
+  if (error instanceof AppError) {
+    return error.message;
+  }
+
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+
+  return 'Failed to clone repository';
+}
+
+router.get(
+  '/',
+  asyncHandler(async (_req, res) => {
+    const projects = await getProjectsWithSessions();
+    res.json(projects);
+  }),
+);
+
+router.get(
+  '/archived',
+  asyncHandler(async (_req, res) => {
+    const projects = await getArchivedProjectsWithSessions();
+    res.json(createApiSuccessResponse({ projects }));
+  }),
+);
+
+router.get(
+  '/:projectId/sessions',
+  asyncHandler(async (req, res) => {
+    const projectId = typeof req.params.projectId === 'string' ? req.params.projectId : '';
+    const limit = parseNonNegativeIntQuery(req.query.limit, 'limit', 20);
+    const offset = parseNonNegativeIntQuery(req.query.offset, 'offset', 0);
+    const sessionsPage = await getProjectSessionsPage(projectId, { limit, offset });
+    res.json(sessionsPage);
+  }),
+);
+
+router.post(
+  '/create-project',
+  asyncHandler(async (req, res) => {
+    const requestBody = req.body as Record<string, unknown>;
+    const projectPath = typeof requestBody.path === 'string' ? requestBody.path : '';
+    const customName = typeof requestBody.customName === 'string' ? requestBody.customName : null;
+
+    if (requestBody.workspaceType !== undefined) {
+      throw new AppError('workspaceType is no longer supported. Use the single create-project flow.', {
+        code: 'LEGACY_WORKSPACE_TYPE_UNSUPPORTED',
+        statusCode: 400,
+      });
+    }
+
+    if (requestBody.githubUrl || requestBody.githubTokenId || requestBody.newGithubToken) {
+      throw new AppError('Repository cloning is not supported on create-project', {
+        code: 'CLONE_NOT_SUPPORTED_ON_CREATE_PROJECT',
+        statusCode: 400,
+        details: 'Use /api/projects/clone-progress for cloning workflows',
+      });
+    }
+
+    const projectCreationResult = await createProject({
+      projectPath,
+      customName,
+    });
+
+    res.json({
+      success: true,
+      project: projectCreationResult.project,
+      message:
+        projectCreationResult.outcome === 'reactivated_archived'
+          ? 'Archived project path reused successfully'
+          : 'Project created successfully',
+    });
+  }),
+);
+
+/**
+ * One-time (or idempotent) migration: apply legacy `localStorage` starred projectIds to the DB, then clear client storage.
+ */
+router.post(
+  '/migrate-legacy-stars',
+  asyncHandler(async (req, res) => {
+    const projectIds = Array.isArray((req.body as { projectIds?: unknown })?.projectIds)
+      ? ((req.body as { projectIds: unknown[] }).projectIds as unknown[]).map((x) => String(x))
+      : [];
+    const { updated } = applyLegacyStarredProjectIds(projectIds);
+    res.json({ success: true, updated });
+  }),
+);
+
+router.get('/clone-progress', async (req, res) => {
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.setHeader('Connection', 'keep-alive');
+  res.flushHeaders();
+
+  const sendEvent = (type: string, data: Record<string, unknown>) => {
+    if (res.writableEnded) {
+      return;
+    }
+
+    res.write(`data: ${JSON.stringify({ type, ...data })}\n\n`);
+  };
+
+  let cloneOperation: Awaited<ReturnType<typeof startCloneProject>> | null = null;
+  const closeListener = () => {
+    cloneOperation?.cancel();
+  };
+  req.on('close', closeListener);
+
+  try {
+    const queryParams = req.query as Record<string, unknown>;
+    const workspacePath = readQueryStringValue(queryParams.path);
+    const githubUrl = readQueryStringValue(queryParams.githubUrl);
+    const githubTokenId = readOptionalNumericQueryValue(queryParams.githubTokenId);
+    const newGithubToken = readQueryStringValue(queryParams.newGithubToken) || null;
+
+    const authenticatedUser = (req as typeof req & { user?: AuthenticatedUser }).user;
+    const userId = authenticatedUser?.id;
+    if (userId === undefined || userId === null) {
+      throw new AppError('Authenticated user is required', {
+        code: 'AUTHENTICATION_REQUIRED',
+        statusCode: 401,
+      });
+    }
+
+    cloneOperation = await startCloneProject(
+      {
+        workspacePath,
+        githubUrl,
+        githubTokenId,
+        newGithubToken,
+        userId,
+      },
+      {
+        onProgress: (message) => {
+          sendEvent('progress', { message });
+        },
+        onComplete: ({ project, message }) => {
+          sendEvent('complete', { project, message });
+        },
+      },
+    );
+
+    await cloneOperation.waitForCompletion;
+  } catch (error) {
+    sendEvent('error', { message: resolveRouteErrorMessage(error) });
+  } finally {
+    req.off('close', closeListener);
+    if (!res.writableEnded) {
+      res.end();
+    }
+  }
+});
+
+router.get(
+  '/:projectId/taskmaster',
+  asyncHandler(async (req, res) => {
+    const projectId = typeof req.params.projectId === 'string' ? req.params.projectId : '';
+    const taskMasterDetails = await getProjectTaskMaster(projectId);
+    res.json(taskMasterDetails);
+  }),
+);
+
+router.put('/:projectId/rename', (req, res) => {
+  try {
+    const projectId = typeof req.params.projectId === 'string' ? req.params.projectId : '';
+    const { displayName } = req.body as { displayName?: unknown };
+    updateProjectDisplayName(projectId, displayName);
+    res.json({ success: true });
+  } catch (error) {
+    res.status(500).json({ error: error instanceof Error ? error.message : 'Failed to rename project' });
+  }
+});
+
+router.post(
+  '/:projectId/toggle-star',
+  asyncHandler(async (req, res) => {
+    const projectId = typeof req.params.projectId === 'string' ? req.params.projectId : '';
+    const { isStarred } = toggleProjectStar(projectId);
+    res.json({ success: true, isStarred });
+  }),
+);
+
+router.post(
+  '/:projectId/restore',
+  asyncHandler(async (req, res) => {
+    const projectId = typeof req.params.projectId === 'string' ? req.params.projectId : '';
+    restoreArchivedProject(projectId);
+    res.json(createApiSuccessResponse({ projectId, isArchived: false }));
+  }),
+);
+
+/**
+ * - `force` not set / false: archive project in DB only (`isArchived` = 1; hidden from active list).
+ * - `force=true`: remove DB row, delete session rows for that path, remove all `*.jsonl` under the Claude project dir.
+ */
+router.delete(
+  '/:projectId',
+  asyncHandler(async (req, res) => {
+    const projectId = typeof req.params.projectId === 'string' ? req.params.projectId : '';
+    const force = req.query.force === 'true';
+    await deleteOrArchiveProject(projectId, force);
+    res.json({ success: true });
+  }),
+);
+
+export default router;
diff --git a/server/modules/projects/services/project-clone.service.ts b/server/modules/projects/services/project-clone.service.ts
new file mode 100644
index 00000000..1a91b879
--- /dev/null
+++ b/server/modules/projects/services/project-clone.service.ts
@@ -0,0 +1,321 @@
+import { spawn } from 'node:child_process';
+import { access, mkdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+import { githubTokensDb } from '@/modules/database/index.js';
+import { createProject } from '@/modules/projects/services/project-management.service.js';
+import type { WorkspacePathValidationResult } from '@/shared/types.js';
+import { AppError, validateWorkspacePath } from '@/shared/utils.js';
+
+type CloneProjectInput = {
+  workspacePath: string;
+  githubUrl: string;
+  githubTokenId?: number | null;
+  newGithubToken?: string | null;
+  userId: number | string;
+};
+
+type CloneCompletePayload = {
+  project: Record<string, unknown>;
+  message: string;
+};
+
+type CloneProjectEventHandlers = {
+  onProgress: (message: string) => void;
+  onComplete: (payload: CloneCompletePayload) => void;
+};
+
+type GitCloneProcess = {
+  stdout: NodeJS.ReadableStream | null;
+  stderr: NodeJS.ReadableStream | null;
+  on(event: 'close', listener: (code: number | null) => void): void;
+  on(event: 'error', listener: (error: NodeJS.ErrnoException) => void): void;
+  kill(): void;
+};
+
+type CloneProjectDependencies = {
+  validatePath: (requestedPath: string) => Promise<WorkspacePathValidationResult>;
+  ensureDirectory: (directoryPath: string) => Promise<void>;
+  pathExists: (targetPath: string) => Promise<boolean>;
+  removePath: (targetPath: string) => Promise<void>;
+  getGithubTokenById: (
+    tokenId: number,
+    userId: number,
+  ) => Promise<{ github_token: string } | null>;
+  spawnGitClone: (cloneUrl: string, clonePath: string) => GitCloneProcess;
+  registerProject: (projectPath: string, customName: string) => Promise<{ project: Record<string, unknown> }>;
+  logError: (message: string, error: unknown) => void;
+};
+
+export type CloneProjectOperation = {
+  waitForCompletion: Promise<void>;
+  cancel: () => void;
+};
+
+async function defaultPathExists(targetPath: string): Promise<boolean> {
+  try {
+    await access(targetPath);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return false;
+    }
+
+    throw error;
+  }
+}
+
+function sanitizeGitError(message: string, token: string | null): string {
+  if (!message || !token) {
+    return message;
+  }
+
+  const escapedToken = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return message.replace(new RegExp(escapedToken, 'g'), '***');
+}
+
+function resolveCloneFailureMessage(lastError: string, sanitizedError: string): string {
+  if (lastError.includes('Authentication failed') || lastError.includes('could not read Username')) {
+    return 'Authentication failed. Please check your credentials.';
+  }
+
+  if (lastError.includes('Repository not found')) {
+    return 'Repository not found. Please check the URL and ensure you have access.';
+  }
+
+  if (lastError.includes('already exists')) {
+    return 'Directory already exists';
+  }
+
+  if (sanitizedError) {
+    return sanitizedError;
+  }
+
+  return 'Git clone failed';
+}
+
+function resolveErrorMessage(error: unknown): string {
+  if (error instanceof AppError) {
+    return error.message;
+  }
+
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+
+  return 'Unexpected error';
+}
+
+const defaultDependencies: CloneProjectDependencies = {
+  validatePath: validateWorkspacePath,
+  ensureDirectory: async (directoryPath: string): Promise<void> => {
+    await mkdir(directoryPath, { recursive: true });
+  },
+  pathExists: defaultPathExists,
+  removePath: async (targetPath: string): Promise<void> => {
+    await rm(targetPath, { recursive: true, force: true });
+  },
+  getGithubTokenById: async (
+    tokenId: number,
+    userId: number,
+  ): Promise<{ github_token: string } | null> => {
+    const tokenRow = githubTokensDb.getGithubTokenById(userId, tokenId) as
+      | { github_token: string }
+      | null;
+    return tokenRow;
+  },
+  spawnGitClone: (cloneUrl: string, clonePath: string): GitCloneProcess =>
+    spawn('git', ['clone', '--progress', '--', cloneUrl, clonePath], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        GIT_TERMINAL_PROMPT: '0',
+      },
+    }) as unknown as GitCloneProcess,
+  registerProject: async (
+    projectPath: string,
+    customName: string,
+  ): Promise<{ project: Record<string, unknown> }> =>
+    createProject({
+      projectPath,
+      customName,
+    }) as Promise<{ project: Record<string, unknown> }>,
+  logError: (message: string, error: unknown): void => {
+    console.error(message, error);
+  },
+};
+
+export async function startCloneProject(
+  input: CloneProjectInput,
+  handlers: CloneProjectEventHandlers,
+  dependencies: CloneProjectDependencies = defaultDependencies,
+): Promise<CloneProjectOperation> {
+  const normalizedWorkspacePath = input.workspacePath.trim();
+  const normalizedGithubUrl = input.githubUrl.trim();
+
+  if (!normalizedWorkspacePath) {
+    throw new AppError('workspacePath and githubUrl are required', {
+      code: 'WORKSPACE_PATH_REQUIRED',
+      statusCode: 400,
+    });
+  }
+
+  if (!normalizedGithubUrl) {
+    throw new AppError('workspacePath and githubUrl are required', {
+      code: 'GITHUB_URL_REQUIRED',
+      statusCode: 400,
+    });
+  }
+
+  if (normalizedGithubUrl.startsWith('-')) {
+    throw new AppError('Invalid githubUrl', {
+      code: 'INVALID_GITHUB_URL',
+      statusCode: 400,
+    });
+  }
+
+  const pathValidation = await dependencies.validatePath(normalizedWorkspacePath);
+  if (!pathValidation.valid || !pathValidation.resolvedPath) {
+    throw new AppError(pathValidation.error || 'Invalid workspace path', {
+      code: 'INVALID_PROJECT_PATH',
+      statusCode: 400,
+    });
+  }
+
+  const absolutePath = pathValidation.resolvedPath;
+  await dependencies.ensureDirectory(absolutePath);
+
+  let githubToken: string | null = null;
+  if (typeof input.githubTokenId === 'number') {
+    const numericUserId =
+      typeof input.userId === 'number' ? input.userId : Number.parseInt(String(input.userId), 10);
+    if (Number.isNaN(numericUserId)) {
+      throw new AppError('Authenticated user is required', {
+        code: 'AUTHENTICATION_REQUIRED',
+        statusCode: 401,
+      });
+    }
+
+    const token = await dependencies.getGithubTokenById(input.githubTokenId, numericUserId);
+    if (!token) {
+      throw new AppError('GitHub token not found', {
+        code: 'GITHUB_TOKEN_NOT_FOUND',
+        statusCode: 404,
+      });
+    }
+
+    githubToken = token.github_token;
+  } else if (input.newGithubToken && input.newGithubToken.trim().length > 0) {
+    githubToken = input.newGithubToken.trim();
+  }
+
+  const sanitizedGithubUrl = normalizedGithubUrl.replace(/\/+$/, '').replace(/\.git$/, '');
+  const repoName = sanitizedGithubUrl.split('/').pop() || 'repository';
+  const clonePath = path.join(absolutePath, repoName);
+
+  if (await dependencies.pathExists(clonePath)) {
+    throw new AppError(
+      `Directory "${repoName}" already exists. Please choose a different location or remove the existing directory.`,
+      {
+        code: 'CLONE_TARGET_ALREADY_EXISTS',
+        statusCode: 409,
+      },
+    );
+  }
+
+  let cloneUrl = normalizedGithubUrl;
+  if (githubToken) {
+    try {
+      const url = new URL(normalizedGithubUrl);
+      url.username = githubToken;
+      url.password = '';
+      cloneUrl = url.toString();
+    } catch {
+      // SSH URLs cannot be represented by URL constructor and are used as-is.
+    }
+  }
+
+  handlers.onProgress(`Cloning into '${repoName}'...`);
+  const gitProcess = dependencies.spawnGitClone(cloneUrl, clonePath);
+  let lastError = '';
+
+  gitProcess.stdout?.on('data', (data: Buffer | string) => {
+    const message = data.toString().trim();
+    if (message) {
+      handlers.onProgress(message);
+    }
+  });
+
+  gitProcess.stderr?.on('data', (data: Buffer | string) => {
+    const message = data.toString().trim();
+    lastError = message;
+    if (message) {
+      handlers.onProgress(message);
+    }
+  });
+
+  const waitForCompletion = new Promise<void>((resolve, reject) => {
+    gitProcess.on('close', async (code) => {
+      if (code === 0) {
+        try {
+          const createdProject = await dependencies.registerProject(clonePath, repoName);
+          handlers.onComplete({
+            project: createdProject.project,
+            message: 'Repository cloned successfully',
+          });
+          resolve();
+        } catch (error) {
+          reject(
+            new AppError(`Clone succeeded but failed to add project: ${resolveErrorMessage(error)}`, {
+              code: 'CLONE_PROJECT_REGISTRATION_FAILED',
+              statusCode: 500,
+            }),
+          );
+        }
+        return;
+      }
+
+      const sanitizedError = sanitizeGitError(lastError, githubToken);
+      const errorMessage = resolveCloneFailureMessage(lastError, sanitizedError);
+
+      try {
+        await dependencies.removePath(clonePath);
+      } catch (cleanupError) {
+        dependencies.logError('Failed to clean up after clone failure:', cleanupError);
+      }
+
+      reject(
+        new AppError(errorMessage, {
+          code: 'GIT_CLONE_FAILED',
+          statusCode: 500,
+        }),
+      );
+    });
+
+    gitProcess.on('error', (error) => {
+      if (error.code === 'ENOENT') {
+        reject(
+          new AppError('Git is not installed or not in PATH', {
+            code: 'GIT_NOT_FOUND',
+            statusCode: 500,
+          }),
+        );
+        return;
+      }
+
+      reject(
+        new AppError(error.message, {
+          code: 'GIT_EXECUTION_FAILED',
+          statusCode: 500,
+        }),
+      );
+    });
+  });
+
+  return {
+    waitForCompletion,
+    cancel: () => {
+      gitProcess.kill();
+    },
+  };
+}
diff --git a/server/modules/projects/services/project-delete.service.ts b/server/modules/projects/services/project-delete.service.ts
new file mode 100644
index 00000000..cbb1c7ed
--- /dev/null
+++ b/server/modules/projects/services/project-delete.service.ts
@@ -0,0 +1,90 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+import { projectsDb, sessionsDb } from '@/modules/database/index.js';
+import { AppError } from '@/shared/utils.js';
+
+function uniqueJsonlPathsFromSessions(
+  sessions: Array<{ jsonl_path: string | null }>,
+): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+
+  for (const row of sessions) {
+    const raw = row.jsonl_path?.trim();
+    if (!raw) {
+      continue;
+    }
+    const absolute = path.isAbsolute(raw) ? path.normalize(raw) : path.resolve(raw);
+    if (seen.has(absolute)) {
+      continue;
+    }
+    seen.add(absolute);
+    result.push(absolute);
+  }
+
+  return result;
+}
+
+async function unlinkJsonlIfExists(filePath: string): Promise<void> {
+  try {
+    await fs.unlink(filePath);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') {
+      return;
+    }
+    console.warn(`[project-delete] Failed to remove ${filePath}:`, (error as Error).message);
+  }
+}
+
+/**
+ * Loads all session rows for the project path and removes each distinct `jsonl_path` file on disk.
+ */
+export async function deleteSessionJsonlFilesForProjectPath(projectPath: string): Promise<void> {
+  const sessions = sessionsDb.getSessionsByProjectPathIncludingArchived(projectPath);
+  const paths = uniqueJsonlPathsFromSessions(sessions);
+
+  for (const filePath of paths) {
+    await unlinkJsonlIfExists(filePath);
+  }
+}
+
+/**
+ * - **Soft delete** (`force` false): set `isArchived` on the `projects` row (hide from the active list; DB only).
+ * - **Force** (`force` true): for each session row for that `project_path`, delete the file at `jsonl_path`
+ *   (when set), then remove session rows and the `projects` row.
+ */
+export async function deleteOrArchiveProject(projectId: string, force: boolean): Promise<void> {
+  const row = projectsDb.getProjectById(projectId);
+  if (!row) {
+    throw new AppError(`Unknown projectId: ${projectId}`, {
+      code: 'PROJECT_NOT_FOUND',
+      statusCode: 404,
+    });
+  }
+
+  if (!force) {
+    projectsDb.updateProjectIsArchivedById(projectId, true);
+    return;
+  }
+
+  await deleteSessionJsonlFilesForProjectPath(row.project_path);
+  sessionsDb.deleteSessionsByProjectPath(row.project_path);
+  projectsDb.deleteProjectById(projectId);
+}
+
+/**
+ * Restores one archived project row back into the active project list.
+ */
+export function restoreArchivedProject(projectId: string): void {
+  const row = projectsDb.getProjectById(projectId);
+  if (!row) {
+    throw new AppError(`Unknown projectId: ${projectId}`, {
+      code: 'PROJECT_NOT_FOUND',
+      statusCode: 404,
+    });
+  }
+
+  projectsDb.updateProjectIsArchivedById(projectId, false);
+}
diff --git a/server/modules/projects/services/project-management.service.ts b/server/modules/projects/services/project-management.service.ts
new file mode 100644
index 00000000..674418cc
--- /dev/null
+++ b/server/modules/projects/services/project-management.service.ts
@@ -0,0 +1,152 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { projectsDb } from '@/modules/database/index.js';
+import type {
+  CreateProjectPathResult,
+  ProjectRepositoryRow,
+  WorkspacePathValidationResult,
+} from '@/shared/types.js';
+import { AppError, normalizeProjectPath, validateWorkspacePath } from '@/shared/utils.js';
+
+type CreateProjectInput = {
+  projectPath: string;
+  customName?: string | null;
+};
+
+type CreateProjectDependencies = {
+  validatePath: (projectPath: string) => Promise<WorkspacePathValidationResult>;
+  ensureWorkspaceDirectory: (projectPath: string) => Promise<void>;
+  persistProjectPath: (projectPath: string, customName: string | null) => CreateProjectPathResult;
+  getProjectByPath: (projectPath: string) => ProjectRepositoryRow | null;
+};
+
+type ProjectApiView = {
+  projectId: string;
+  path: string;
+  fullPath: string;
+  displayName: string;
+  customName: string | null;
+  isArchived: boolean;
+  isStarred: boolean;
+  sessions: [];
+  cursorSessions: [];
+  codexSessions: [];
+  geminiSessions: [];
+  opencodeSessions: [];
+  sessionMeta: {
+    hasMore: false;
+    total: 0;
+  };
+};
+
+type CreateProjectServiceResult = {
+  outcome: 'created' | 'reactivated_archived';
+  project: ProjectApiView;
+};
+
+const defaultDependencies: CreateProjectDependencies = {
+  validatePath: validateWorkspacePath,
+  ensureWorkspaceDirectory: async (projectPath: string): Promise<void> => {
+    await fs.mkdir(projectPath, { recursive: true });
+    const directoryStats = await fs.stat(projectPath);
+    if (!directoryStats.isDirectory()) {
+      throw new AppError('Path exists but is not a directory', {
+        code: 'PROJECT_PATH_NOT_DIRECTORY',
+        statusCode: 400,
+      });
+    }
+  },
+  persistProjectPath: (projectPath: string, customName: string | null): CreateProjectPathResult =>
+    projectsDb.createProjectPath(projectPath, customName),
+  getProjectByPath: (projectPath: string): ProjectRepositoryRow | null =>
+    projectsDb.getProjectPath(projectPath),
+};
+
+function resolveDisplayName(customName: string | null | undefined, projectPath: string): string {
+  const trimmedCustomName = typeof customName === 'string' ? customName.trim() : '';
+  if (trimmedCustomName.length > 0) {
+    return trimmedCustomName;
+  }
+
+  return path.basename(projectPath) || projectPath;
+}
+
+function mapProjectRowToApiView(projectRow: ProjectRepositoryRow): ProjectApiView {
+  return {
+    projectId: projectRow.project_id,
+    path: projectRow.project_path,
+    fullPath: projectRow.project_path,
+    displayName: resolveDisplayName(projectRow.custom_project_name, projectRow.project_path),
+    customName: projectRow.custom_project_name,
+    isArchived: Boolean(projectRow.isArchived),
+    isStarred: Boolean(projectRow.isStarred),
+    sessions: [],
+    cursorSessions: [],
+    codexSessions: [],
+    geminiSessions: [],
+    opencodeSessions: [],
+    sessionMeta: {
+      hasMore: false,
+      total: 0,
+    },
+  };
+}
+
+export async function createProject(
+  input: CreateProjectInput,
+  dependencies: CreateProjectDependencies = defaultDependencies,
+): Promise<CreateProjectServiceResult> {
+  const normalizedPath = normalizeProjectPath(input.projectPath || '');
+  if (!normalizedPath) {
+    throw new AppError('path is required', {
+      code: 'PROJECT_PATH_REQUIRED',
+      statusCode: 400,
+    });
+  }
+
+  const pathValidation = await dependencies.validatePath(normalizedPath);
+  if (!pathValidation.valid || !pathValidation.resolvedPath) {
+    throw new AppError('Invalid project path', {
+      code: 'INVALID_PROJECT_PATH',
+      statusCode: 400,
+      details: pathValidation.error ?? 'Path validation failed',
+    });
+  }
+
+  const resolvedProjectPath = normalizeProjectPath(pathValidation.resolvedPath);
+  await dependencies.ensureWorkspaceDirectory(resolvedProjectPath);
+
+  const normalizedCustomName = resolveDisplayName(input.customName ?? null, resolvedProjectPath);
+  const persistedProject = dependencies.persistProjectPath(resolvedProjectPath, normalizedCustomName);
+
+  if (persistedProject.outcome === 'active_conflict') {
+    throw new AppError('Project path already exists and is active', {
+      code: 'PROJECT_ALREADY_EXISTS',
+      statusCode: 409,
+      details: `Project path already exists: ${resolvedProjectPath}`,
+    });
+  }
+
+  const projectRow = persistedProject.project ?? dependencies.getProjectByPath(resolvedProjectPath);
+  if (!projectRow) {
+    throw new AppError('Failed to resolve project after creation', {
+      code: 'PROJECT_CREATE_FAILED',
+      statusCode: 500,
+    });
+  }
+
+  // Archived rows intentionally remain archived when reused, as requested.
+  return {
+    outcome: persistedProject.outcome,
+    project: mapProjectRowToApiView(projectRow),
+  };
+}
+
+/**
+ * Sets `projects.custom_project_name` for the given `projectId` (or clears it when empty).
+ */
+export function updateProjectDisplayName(projectId: string, newDisplayName: unknown): void {
+  const trimmed = typeof newDisplayName === 'string' ? newDisplayName.trim() : '';
+  projectsDb.updateCustomProjectNameById(projectId, trimmed.length > 0 ? trimmed : null);
+}
diff --git a/server/modules/projects/services/project-star.service.ts b/server/modules/projects/services/project-star.service.ts
new file mode 100644
index 00000000..2c7f11ac
--- /dev/null
+++ b/server/modules/projects/services/project-star.service.ts
@@ -0,0 +1,78 @@
+import { projectsDb } from '@/modules/database/index.js';
+import { AppError } from '@/shared/utils.js';
+
+type ToggleProjectStarResult = {
+  isStarred: boolean;
+};
+
+type ApplyLegacyStarredProjectIdsResult = {
+  updated: number;
+};
+
+function normalizeProjectId(projectId: string): string {
+  return projectId.trim();
+}
+
+function uniqueProjectIds(projectIds: string[]): string[] {
+  const uniqueIds = new Set<string>();
+  for (const projectId of projectIds) {
+    const normalizedProjectId = normalizeProjectId(projectId);
+    if (!normalizedProjectId) {
+      continue;
+    }
+    uniqueIds.add(normalizedProjectId);
+  }
+  return [...uniqueIds];
+}
+
+/**
+ * Applies legacy `localStorage` stars keyed by DB `projectId` onto `projects.isStarred`.
+ *
+ * The operation is idempotent: already-starred projects are ignored, unknown ids are skipped.
+ */
+export function applyLegacyStarredProjectIds(projectIds: string[]): ApplyLegacyStarredProjectIdsResult {
+  const normalizedProjectIds = uniqueProjectIds(projectIds);
+  let updated = 0;
+
+  for (const projectId of normalizedProjectIds) {
+    const project = projectsDb.getProjectById(projectId);
+    if (!project) {
+      continue;
+    }
+
+    if (Boolean(project.isStarred)) {
+      continue;
+    }
+
+    projectsDb.updateProjectIsStarredById(projectId, true);
+    updated += 1;
+  }
+
+  return { updated };
+}
+
+/**
+ * Flips `projects.isStarred` for one project and returns the new state.
+ */
+export function toggleProjectStar(projectId: string): ToggleProjectStarResult {
+  const normalizedProjectId = normalizeProjectId(projectId);
+  if (!normalizedProjectId) {
+    throw new AppError('projectId is required', {
+      code: 'PROJECT_ID_REQUIRED',
+      statusCode: 400,
+    });
+  }
+
+  const project = projectsDb.getProjectById(normalizedProjectId);
+  if (!project) {
+    throw new AppError('Project not found', {
+      code: 'PROJECT_NOT_FOUND',
+      statusCode: 404,
+    });
+  }
+
+  const nextStarredState = !Boolean(project.isStarred);
+  projectsDb.updateProjectIsStarredById(normalizedProjectId, nextStarredState);
+
+  return { isStarred: nextStarredState };
+}
diff --git a/server/modules/projects/services/projects-has-taskmaster.service.ts b/server/modules/projects/services/projects-has-taskmaster.service.ts
new file mode 100644
index 00000000..ee1d6c6c
--- /dev/null
+++ b/server/modules/projects/services/projects-has-taskmaster.service.ts
@@ -0,0 +1,248 @@
+import { access, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+import { projectsDb } from '@/modules/database/index.js';
+import { AppError } from '@/shared/utils.js';
+
+type TaskMasterTask = {
+  status?: string;
+  subtasks?: Array<{
+    status?: string;
+  }>;
+};
+
+type TaskMasterMetadata =
+  | {
+      taskCount: number;
+      subtaskCount: number;
+      completed: number;
+      pending: number;
+      inProgress: number;
+      review: number;
+      completionPercentage: number;
+      lastModified: string;
+    }
+  | {
+      error: string;
+    }
+  | null;
+
+type TaskMasterDetectionResult = {
+  hasTaskmaster: boolean;
+  hasEssentialFiles?: boolean;
+  files?: Record<string, boolean>;
+  metadata?: TaskMasterMetadata;
+  path?: string;
+  reason?: string;
+};
+
+type NormalizedTaskMasterInfo = {
+  hasTaskmaster: boolean;
+  hasEssentialFiles: boolean;
+  metadata: TaskMasterMetadata;
+  status: 'configured' | 'not-configured';
+};
+
+type GetProjectTaskMasterByIdResult = {
+  projectId: string;
+  projectPath: string;
+  taskmaster: NormalizedTaskMasterInfo;
+};
+
+type GetProjectTaskMasterDependencies = {
+  resolveProjectPathById: (projectId: string) => string | null;
+  detectTaskMasterFolder: (projectPath: string) => Promise<TaskMasterDetectionResult>;
+};
+
+type GetProjectTaskMasterResolver = (projectId: string) => Promise<GetProjectTaskMasterByIdResult | null>;
+
+function extractTasksFromJson(tasksData: unknown): TaskMasterTask[] {
+  if (!tasksData || typeof tasksData !== 'object') {
+    return [];
+  }
+
+  const legacyTasks = (tasksData as { tasks?: unknown }).tasks;
+  if (Array.isArray(legacyTasks)) {
+    return legacyTasks as TaskMasterTask[];
+  }
+
+  const taggedTaskCollections: TaskMasterTask[] = [];
+  for (const tagValue of Object.values(tasksData)) {
+    if (!tagValue || typeof tagValue !== 'object') {
+      continue;
+    }
+
+    const tagTasks = (tagValue as { tasks?: unknown }).tasks;
+    if (Array.isArray(tagTasks)) {
+      taggedTaskCollections.push(...(tagTasks as TaskMasterTask[]));
+    }
+  }
+
+  return taggedTaskCollections;
+}
+
+async function detectTaskMasterFolder(projectPath: string): Promise<TaskMasterDetectionResult> {
+  try {
+    const taskMasterPath = path.join(projectPath, '.taskmaster');
+
+    try {
+      const taskMasterStats = await stat(taskMasterPath);
+      if (!taskMasterStats.isDirectory()) {
+        return {
+          hasTaskmaster: false,
+          reason: '.taskmaster exists but is not a directory',
+        };
+      }
+    } catch (error) {
+      const fileError = error as NodeJS.ErrnoException;
+      if (fileError.code === 'ENOENT') {
+        return {
+          hasTaskmaster: false,
+          reason: '.taskmaster directory not found',
+        };
+      }
+
+      throw fileError;
+    }
+
+    const keyFiles = ['tasks/tasks.json', 'config.json'];
+    const fileStatus: Record<string, boolean> = {};
+    let hasEssentialFiles = true;
+
+    for (const fileName of keyFiles) {
+      const absoluteFilePath = path.join(taskMasterPath, fileName);
+      try {
+        await access(absoluteFilePath);
+        fileStatus[fileName] = true;
+      } catch {
+        fileStatus[fileName] = false;
+        if (fileName === 'tasks/tasks.json') {
+          hasEssentialFiles = false;
+        }
+      }
+    }
+
+    let taskMetadata: TaskMasterMetadata = null;
+    if (fileStatus['tasks/tasks.json']) {
+      const tasksPath = path.join(taskMasterPath, 'tasks/tasks.json');
+      try {
+        const tasksContent = await readFile(tasksPath, 'utf8');
+        const parsedTasksJson = JSON.parse(tasksContent) as unknown;
+        const tasks = extractTasksFromJson(parsedTasksJson);
+
+        const stats = tasks.reduce(
+          (accumulator, currentTask) => {
+            accumulator.total += 1;
+            const normalizedTaskStatus = currentTask.status || 'pending';
+            accumulator.byStatus[normalizedTaskStatus] = (accumulator.byStatus[normalizedTaskStatus] || 0) + 1;
+
+            if (Array.isArray(currentTask.subtasks)) {
+              for (const subtask of currentTask.subtasks) {
+                accumulator.subtotalTasks += 1;
+                const normalizedSubtaskStatus = subtask.status || 'pending';
+                accumulator.subtaskByStatus[normalizedSubtaskStatus] =
+                  (accumulator.subtaskByStatus[normalizedSubtaskStatus] || 0) + 1;
+              }
+            }
+
+            return accumulator;
+          },
+          {
+            total: 0,
+            subtotalTasks: 0,
+            byStatus: {} as Record<string, number>,
+            subtaskByStatus: {} as Record<string, number>,
+          },
+        );
+
+        const tasksStat = await stat(tasksPath);
+        taskMetadata = {
+          taskCount: stats.total,
+          subtaskCount: stats.subtotalTasks,
+          completed: stats.byStatus.done || 0,
+          pending: stats.byStatus.pending || 0,
+          inProgress: stats.byStatus['in-progress'] || 0,
+          review: stats.byStatus.review || 0,
+          completionPercentage: stats.total > 0 ? Math.round(((stats.byStatus.done || 0) / stats.total) * 100) : 0,
+          lastModified: tasksStat.mtime.toISOString(),
+        };
+      } catch (parseError) {
+        console.warn('Failed to parse tasks.json:', (parseError as Error).message);
+        taskMetadata = {
+          error: 'Failed to parse tasks.json',
+        };
+      }
+    }
+
+    return {
+      hasTaskmaster: true,
+      hasEssentialFiles,
+      files: fileStatus,
+      metadata: taskMetadata,
+      path: taskMasterPath,
+    };
+  } catch (error) {
+    console.error('Error detecting TaskMaster folder:', error);
+    return {
+      hasTaskmaster: false,
+      reason: `Error checking directory: ${(error as Error).message}`,
+    };
+  }
+}
+
+function normalizeTaskMasterInfo(taskMasterResult: TaskMasterDetectionResult | null = null): NormalizedTaskMasterInfo {
+  const hasTaskmaster = Boolean(taskMasterResult?.hasTaskmaster);
+  const hasEssentialFiles = Boolean(taskMasterResult?.hasEssentialFiles);
+
+  return {
+    hasTaskmaster,
+    hasEssentialFiles,
+    metadata: taskMasterResult?.metadata ?? null,
+    status: hasTaskmaster && hasEssentialFiles ? 'configured' : 'not-configured',
+  };
+}
+
+const defaultDependencies: GetProjectTaskMasterDependencies = {
+  resolveProjectPathById: (projectId: string): string | null => projectsDb.getProjectPathById(projectId),
+  detectTaskMasterFolder,
+};
+
+export async function getProjectTaskMasterById(
+  projectId: string,
+  dependencies: GetProjectTaskMasterDependencies = defaultDependencies,
+): Promise<GetProjectTaskMasterByIdResult | null> {
+  const projectPath = dependencies.resolveProjectPathById(projectId);
+  if (!projectPath) {
+    return null;
+  }
+
+  const taskMasterResult = await dependencies.detectTaskMasterFolder(projectPath);
+  return {
+    projectId,
+    projectPath,
+    taskmaster: normalizeTaskMasterInfo(taskMasterResult),
+  };
+}
+
+export async function getProjectTaskMaster(
+  projectId: string,
+  resolveById: GetProjectTaskMasterResolver = getProjectTaskMasterById,
+): Promise<GetProjectTaskMasterByIdResult> {
+  const normalizedProjectId = projectId.trim();
+  if (!normalizedProjectId) {
+    throw new AppError('projectId is required', {
+      code: 'PROJECT_ID_REQUIRED',
+      statusCode: 400,
+    });
+  }
+
+  const taskMasterDetails = await resolveById(normalizedProjectId);
+  if (!taskMasterDetails) {
+    throw new AppError('Project not found', {
+      code: 'PROJECT_NOT_FOUND',
+      statusCode: 404,
+    });
+  }
+
+  return taskMasterDetails;
+}
diff --git a/server/modules/projects/services/projects-with-sessions-fetch.service.ts b/server/modules/projects/services/projects-with-sessions-fetch.service.ts
new file mode 100644
index 00000000..bb252f69
--- /dev/null
+++ b/server/modules/projects/services/projects-with-sessions-fetch.service.ts
@@ -0,0 +1,355 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { projectsDb, sessionsDb } from '@/modules/database/index.js';
+import { sessionSynchronizerService } from '@/modules/providers/index.js';
+import { WS_OPEN_STATE, connectedClients } from '@/modules/websocket/index.js';
+import type { RealtimeClientConnection } from '@/shared/types.js';
+import { AppError } from '@/shared/utils.js';
+
+type SessionSummary = {
+  id: string;
+  summary: string;
+  messageCount: number;
+  lastActivity: string;
+};
+
+type SessionsByProvider = Record<'claude' | 'cursor' | 'codex' | 'gemini' | 'opencode', SessionSummary[]>;
+
+type SessionRepositoryRow = {
+  provider: string;
+  session_id: string;
+  custom_name?: string | null;
+  updated_at?: string | null;
+  created_at?: string | null;
+};
+
+export type ProjectListItem = {
+  projectId: string;
+  path: string;
+  displayName: string;
+  fullPath: string;
+  isStarred: boolean;
+  sessions: SessionSummary[];
+  cursorSessions: SessionSummary[];
+  codexSessions: SessionSummary[];
+  geminiSessions: SessionSummary[];
+  opencodeSessions: SessionSummary[];
+  sessionMeta: {
+    hasMore: boolean;
+    total: number;
+  };
+};
+
+export type ArchivedProjectListItem = ProjectListItem & {
+  isArchived: true;
+};
+
+type ProgressUpdate = {
+  phase: 'loading' | 'complete';
+  current: number;
+  total: number;
+  currentProject?: string;
+};
+
+type GetProjectsWithSessionsOptions = {
+  skipSynchronization?: boolean;
+  sessionsLimit?: number;
+  sessionsOffset?: number;
+};
+
+type SessionPaginationOptions = {
+  limit?: number;
+  offset?: number;
+};
+
+type ProjectSessionsPageResult = {
+  sessionsByProvider: SessionsByProvider;
+  total: number;
+  hasMore: boolean;
+};
+
+export type ProjectSessionsPageApiView = {
+  projectId: string;
+  sessions: SessionSummary[];
+  cursorSessions: SessionSummary[];
+  codexSessions: SessionSummary[];
+  geminiSessions: SessionSummary[];
+  opencodeSessions: SessionSummary[];
+  sessionMeta: {
+    hasMore: boolean;
+    total: number;
+  };
+};
+
+const DEFAULT_PROJECT_SESSIONS_PAGE_SIZE = 20;
+const MAX_PROJECT_SESSIONS_PAGE_SIZE = 200;
+
+/**
+ * Generate better display name from path.
+ */
+export async function generateDisplayName(projectName: string, actualProjectDir: string | null = null): Promise<string> {
+  // Use actual project directory if provided, otherwise decode from project name.
+  const projectPath = actualProjectDir || projectName.replace(/-/g, '/');
+
+  // Try to read package.json from the project path.
+  try {
+    const packageJsonPath = path.join(projectPath, 'package.json');
+    const packageData = await fs.readFile(packageJsonPath, 'utf8');
+    const packageJson = JSON.parse(packageData) as { name?: string };
+
+    // Return the name from package.json if it exists.
+    if (packageJson.name) {
+      return packageJson.name;
+    }
+  } catch {
+    // Fall back to path-based naming if package.json doesn't exist or can't be read.
+  }
+
+  // If it starts with /, it's an absolute path.
+  if (projectPath.startsWith('/')) {
+    const parts = projectPath.split('/').filter(Boolean);
+    // Return only the last folder name.
+    return parts[parts.length - 1] || projectPath;
+  }
+
+  return projectPath;
+}
+
+function normalizeSessionPagination(options: SessionPaginationOptions = {}): { limit: number; offset: number } {
+  const rawLimit = Number.isFinite(options.limit) ? Math.floor(Number(options.limit)) : DEFAULT_PROJECT_SESSIONS_PAGE_SIZE;
+  const rawOffset = Number.isFinite(options.offset) ? Math.floor(Number(options.offset)) : 0;
+
+  return {
+    limit: Math.min(Math.max(1, rawLimit), MAX_PROJECT_SESSIONS_PAGE_SIZE),
+    offset: Math.max(0, rawOffset),
+  };
+}
+
+function mapSessionRowToSummary(row: SessionRepositoryRow): SessionSummary {
+  return {
+    id: row.session_id,
+    summary: row.custom_name || '',
+    messageCount: 0,
+    lastActivity: row.updated_at ?? row.created_at ?? new Date().toISOString(),
+  };
+}
+
+function bucketSessionRowsByProvider(rows: SessionRepositoryRow[]): SessionsByProvider {
+  const byProvider: SessionsByProvider = {
+    claude: [],
+    cursor: [],
+    codex: [],
+    gemini: [],
+    opencode: [],
+  };
+
+  for (const row of rows) {
+    const provider = row.provider as keyof SessionsByProvider;
+    const bucket = byProvider[provider];
+    if (!bucket) {
+      continue;
+    }
+
+    bucket.push(mapSessionRowToSummary(row));
+  }
+
+  return byProvider;
+}
+
+function readProjectSessionsIncludingArchived(projectPath: string): ProjectSessionsPageResult {
+  const rows = sessionsDb.getSessionsByProjectPathIncludingArchived(projectPath) as SessionRepositoryRow[];
+
+  return {
+    sessionsByProvider: bucketSessionRowsByProvider(rows),
+    total: rows.length,
+    hasMore: false,
+  };
+}
+
+/**
+ * Reads one paginated project session slice from the DB and groups rows by provider.
+ */
+function readProjectSessionsPageByPath(
+  projectPath: string,
+  options: SessionPaginationOptions = {},
+): ProjectSessionsPageResult {
+  const pagination = normalizeSessionPagination(options);
+  const rows = sessionsDb.getSessionsByProjectPathPage(
+    projectPath,
+    pagination.limit,
+    pagination.offset,
+  ) as SessionRepositoryRow[];
+  const total = sessionsDb.countSessionsByProjectPath(projectPath);
+
+  return {
+    sessionsByProvider: bucketSessionRowsByProvider(rows),
+    total,
+    hasMore: pagination.offset + rows.length < total,
+  };
+}
+
+// Broadcast progress to all connected WebSocket clients
+function broadcastProgress(progress: ProgressUpdate) {
+  const message = JSON.stringify({
+    type: 'loading_progress',
+    ...progress,
+  });
+
+  connectedClients.forEach((client: RealtimeClientConnection) => {
+    if (client.readyState === WS_OPEN_STATE) {
+      client.send(message);
+    }
+  });
+}
+
+/**
+ * Reads all projects from DB and returns provider-bucketed session summaries.
+ */
+export async function getProjectsWithSessions(
+  options: GetProjectsWithSessionsOptions = {}
+): Promise<ProjectListItem[]> {
+  if (!options.skipSynchronization) {
+    await sessionSynchronizerService.synchronizeSessions();
+  }
+
+  const projectRows = projectsDb.getProjectPaths() as Array<{
+    project_id: string;
+    project_path: string;
+    custom_project_name?: string | null;
+    isStarred?: number;
+  }>;
+  const totalProjects = projectRows.length;
+  const projects: ProjectListItem[] = [];
+  let processedProjects = 0;
+
+  for (const row of projectRows) {
+    processedProjects += 1;
+
+    const projectId = row.project_id;
+    const projectPath = row.project_path;
+
+    broadcastProgress({
+      phase: 'loading',
+      current: processedProjects,
+      total: totalProjects,
+      currentProject: projectPath,
+    });
+
+    const displayName =
+      row.custom_project_name && row.custom_project_name.trim().length > 0
+        ? row.custom_project_name
+        : await generateDisplayName(path.basename(projectPath) || projectPath, projectPath);
+
+    const sessionsPage = readProjectSessionsPageByPath(projectPath, {
+      limit: options.sessionsLimit,
+      offset: options.sessionsOffset,
+    });
+
+    projects.push({
+      projectId,
+      path: projectPath,
+      displayName,
+      fullPath: projectPath,
+      isStarred: Boolean(row.isStarred),
+      sessions: sessionsPage.sessionsByProvider.claude,
+      cursorSessions: sessionsPage.sessionsByProvider.cursor,
+      codexSessions: sessionsPage.sessionsByProvider.codex,
+      geminiSessions: sessionsPage.sessionsByProvider.gemini,
+      opencodeSessions: sessionsPage.sessionsByProvider.opencode,
+      sessionMeta: {
+        hasMore: sessionsPage.hasMore,
+        total: sessionsPage.total,
+      },
+    });
+  }
+
+  broadcastProgress({
+    phase: 'complete',
+    current: totalProjects,
+    total: totalProjects,
+  });
+
+  return projects;
+}
+
+/**
+ * Reads archived projects from DB and includes every session row for each
+ * project path, because an archived workspace should surface all preserved
+ * conversation history in the archive view regardless of each session's flag.
+ */
+export async function getArchivedProjectsWithSessions(
+  options: Pick<GetProjectsWithSessionsOptions, 'skipSynchronization'> = {},
+): Promise<ArchivedProjectListItem[]> {
+  if (!options.skipSynchronization) {
+    await sessionSynchronizerService.synchronizeSessions();
+  }
+
+  const projectRows = projectsDb.getArchivedProjectPaths() as Array<{
+    project_id: string;
+    project_path: string;
+    custom_project_name?: string | null;
+    isStarred?: number;
+  }>;
+
+  const archivedProjects: ArchivedProjectListItem[] = [];
+
+  for (const row of projectRows) {
+    const displayName =
+      row.custom_project_name && row.custom_project_name.trim().length > 0
+        ? row.custom_project_name
+        : await generateDisplayName(path.basename(row.project_path) || row.project_path, row.project_path);
+
+    const sessionsPage = readProjectSessionsIncludingArchived(row.project_path);
+
+    archivedProjects.push({
+      projectId: row.project_id,
+      path: row.project_path,
+      displayName,
+      fullPath: row.project_path,
+      isStarred: Boolean(row.isStarred),
+      isArchived: true,
+      sessions: sessionsPage.sessionsByProvider.claude,
+      cursorSessions: sessionsPage.sessionsByProvider.cursor,
+      codexSessions: sessionsPage.sessionsByProvider.codex,
+      geminiSessions: sessionsPage.sessionsByProvider.gemini,
+      opencodeSessions: sessionsPage.sessionsByProvider.opencode,
+      sessionMeta: {
+        hasMore: sessionsPage.hasMore,
+        total: sessionsPage.total,
+      },
+    });
+  }
+
+  return archivedProjects;
+}
+
+/**
+ * Loads one paginated session slice for a specific project id.
+ */
+export async function getProjectSessionsPage(
+  projectId: string,
+  options: SessionPaginationOptions = {},
+): Promise<ProjectSessionsPageApiView> {
+  const projectRow = projectsDb.getProjectById(projectId);
+  if (!projectRow) {
+    throw new AppError(`Project "${projectId}" was not found.`, {
+      code: 'PROJECT_NOT_FOUND',
+      statusCode: 404,
+    });
+  }
+
+  const sessionsPage = readProjectSessionsPageByPath(projectRow.project_path, options);
+  return {
+    projectId: projectRow.project_id,
+    sessions: sessionsPage.sessionsByProvider.claude,
+    cursorSessions: sessionsPage.sessionsByProvider.cursor,
+    codexSessions: sessionsPage.sessionsByProvider.codex,
+    geminiSessions: sessionsPage.sessionsByProvider.gemini,
+    opencodeSessions: sessionsPage.sessionsByProvider.opencode,
+    sessionMeta: {
+      hasMore: sessionsPage.hasMore,
+      total: sessionsPage.total,
+    },
+  };
+}
diff --git a/server/modules/projects/tests/project-clone.service.test.ts b/server/modules/projects/tests/project-clone.service.test.ts
new file mode 100644
index 00000000..85c807d8
--- /dev/null
+++ b/server/modules/projects/tests/project-clone.service.test.ts
@@ -0,0 +1,183 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import path from 'node:path';
+import { PassThrough } from 'node:stream';
+import test from 'node:test';
+
+import { startCloneProject } from '@/modules/projects/services/project-clone.service.js';
+import { AppError } from '@/shared/utils.js';
+
+type TestDependencies = Parameters<typeof startCloneProject>[2];
+
+function buildDependencies(overrides: Partial<NonNullable<TestDependencies>> = {}): NonNullable<TestDependencies> {
+  return {
+    validatePath: async () => ({ valid: true, resolvedPath: '/workspace/root' }),
+    ensureDirectory: async () => undefined,
+    pathExists: async () => false,
+    removePath: async () => undefined,
+    getGithubTokenById: async () => ({ github_token: 'token-value' }),
+    spawnGitClone: () => {
+      throw new Error('spawnGitClone should be overridden in this test');
+    },
+    registerProject: async () => ({ project: { projectId: 'project-1' } }),
+    logError: () => undefined,
+    ...overrides,
+  };
+}
+
+function createMockGitProcess() {
+  const emitter = new EventEmitter() as EventEmitter & {
+    stdout: PassThrough;
+    stderr: PassThrough;
+    kill: () => void;
+  };
+
+  emitter.stdout = new PassThrough();
+  emitter.stderr = new PassThrough();
+  emitter.kill = () => {
+    emitter.emit('close', null);
+  };
+
+  return emitter;
+}
+
+test('startCloneProject rejects when workspace path is missing', async () => {
+  await assert.rejects(
+    async () =>
+      startCloneProject(
+        {
+          workspacePath: '',
+          githubUrl: 'https://github.com/example/repo',
+          userId: 1,
+        },
+        {
+          onProgress: () => undefined,
+          onComplete: () => undefined,
+        },
+        buildDependencies(),
+      ),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.code, 'WORKSPACE_PATH_REQUIRED');
+      return true;
+    },
+  );
+});
+
+test('startCloneProject rejects when github URL is missing', async () => {
+  await assert.rejects(
+    async () =>
+      startCloneProject(
+        {
+          workspacePath: '/workspace/root',
+          githubUrl: '',
+          userId: 1,
+        },
+        {
+          onProgress: () => undefined,
+          onComplete: () => undefined,
+        },
+        buildDependencies(),
+      ),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.code, 'GITHUB_URL_REQUIRED');
+      return true;
+    },
+  );
+});
+
+test('startCloneProject rejects github URL values that begin with option prefixes', async () => {
+  await assert.rejects(
+    async () =>
+      startCloneProject(
+        {
+          workspacePath: '/workspace/root',
+          githubUrl: '--upload-pack=malicious',
+          userId: 1,
+        },
+        {
+          onProgress: () => undefined,
+          onComplete: () => undefined,
+        },
+        buildDependencies(),
+      ),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.code, 'INVALID_GITHUB_URL');
+      return true;
+    },
+  );
+});
+
+test('startCloneProject rejects when selected github token does not exist', async () => {
+  await assert.rejects(
+    async () =>
+      startCloneProject(
+        {
+          workspacePath: '/workspace/root',
+          githubUrl: 'https://github.com/example/repo',
+          githubTokenId: 12,
+          userId: 1,
+        },
+        {
+          onProgress: () => undefined,
+          onComplete: () => undefined,
+        },
+        buildDependencies({
+          getGithubTokenById: async () => null,
+        }),
+      ),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.code, 'GITHUB_TOKEN_NOT_FOUND');
+      return true;
+    },
+  );
+});
+
+test('startCloneProject completes and emits complete payload when git exits successfully', async () => {
+  const gitProcess = createMockGitProcess();
+  const progressMessages: string[] = [];
+  let completePayload: { project: Record<string, unknown>; message: string } | null = null;
+  let capturedProjectPath = '';
+  let capturedCustomName = '';
+
+  const operation = await startCloneProject(
+    {
+      workspacePath: '/workspace/root',
+      githubUrl: 'https://github.com/example/repo.git',
+      userId: 1,
+    },
+    {
+      onProgress: (message) => {
+        progressMessages.push(message);
+      },
+      onComplete: (payload: { project: Record<string, unknown>; message: string }) => {
+        completePayload = payload;
+      },
+    },
+    buildDependencies({
+      spawnGitClone: () => gitProcess as any,
+      registerProject: async (projectPath, customName) => {
+        capturedProjectPath = projectPath;
+        capturedCustomName = customName;
+        return { project: { projectId: 'project-1', path: projectPath } };
+      },
+    }),
+  );
+
+  gitProcess.emit('close', 0);
+  await operation.waitForCompletion;
+
+  assert.ok(progressMessages.some((message) => message.includes("Cloning into 'repo'")));
+  assert.equal(capturedCustomName, 'repo');
+  assert.equal(path.basename(capturedProjectPath), 'repo');
+  assert.notEqual(completePayload, null);
+  const resolvedCompletePayload = completePayload as unknown as {
+    project: Record<string, unknown>;
+    message: string;
+  };
+  assert.equal(resolvedCompletePayload.message, 'Repository cloned successfully');
+  assert.equal((resolvedCompletePayload.project.projectId as string) || '', 'project-1');
+});
diff --git a/server/modules/projects/tests/project-management.service.test.ts b/server/modules/projects/tests/project-management.service.test.ts
new file mode 100644
index 00000000..3b0e47bb
--- /dev/null
+++ b/server/modules/projects/tests/project-management.service.test.ts
@@ -0,0 +1,117 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createProject } from '@/modules/projects/services/project-management.service.js';
+import { AppError } from '@/shared/utils.js';
+
+const projectRow = {
+  project_id: 'project-1',
+  project_path: '/workspace/my-project',
+  custom_project_name: 'my-project',
+  isStarred: 0,
+  isArchived: 0,
+};
+
+test('createProject throws when project path is missing', async () => {
+  await assert.rejects(
+    async () => createProject({ projectPath: '' }),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.code, 'PROJECT_PATH_REQUIRED');
+      assert.equal(error.statusCode, 400);
+      return true;
+    },
+  );
+});
+
+test('createProject throws when path validation fails', async () => {
+  await assert.rejects(
+    async () =>
+      createProject(
+        { projectPath: '/invalid/path' },
+        {
+          validatePath: async () => ({ valid: false, error: 'blocked path' }),
+          ensureWorkspaceDirectory: async () => undefined,
+          persistProjectPath: () => ({ outcome: 'created', project: projectRow }),
+          getProjectByPath: () => projectRow,
+        },
+      ),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.code, 'INVALID_PROJECT_PATH');
+      assert.equal(error.statusCode, 400);
+      assert.equal(error.details, 'blocked path');
+      return true;
+    },
+  );
+});
+
+test('createProject throws conflict when active project path already exists', async () => {
+  await assert.rejects(
+    async () =>
+      createProject(
+        { projectPath: '/workspace/my-project' },
+        {
+          validatePath: async () => ({ valid: true, resolvedPath: '/workspace/my-project' }),
+          ensureWorkspaceDirectory: async () => undefined,
+          persistProjectPath: () => ({ outcome: 'active_conflict', project: projectRow }),
+          getProjectByPath: () => projectRow,
+        },
+      ),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.code, 'PROJECT_ALREADY_EXISTS');
+      assert.equal(error.statusCode, 409);
+      assert.equal(error.details, 'Project path already exists: /workspace/my-project');
+      return true;
+    },
+  );
+});
+
+test('createProject falls back to directory name when custom name is not provided', async () => {
+  let capturedCustomName: string | null = null;
+
+  const result = await createProject(
+    { projectPath: '/workspace/my-project', customName: '' },
+    {
+      validatePath: async () => ({ valid: true, resolvedPath: '/workspace/my-project' }),
+      ensureWorkspaceDirectory: async () => undefined,
+      persistProjectPath: (_projectPath, customName) => {
+        capturedCustomName = customName;
+        return {
+          outcome: 'created',
+          project: {
+            ...projectRow,
+            custom_project_name: customName,
+          },
+        };
+      },
+      getProjectByPath: () => projectRow,
+    },
+  );
+
+  assert.equal(capturedCustomName, 'my-project');
+  assert.equal(result.outcome, 'created');
+  assert.equal(result.project.displayName, 'my-project');
+});
+
+test('createProject returns archived reuse outcome when archived row is reused', async () => {
+  const result = await createProject(
+    { projectPath: '/workspace/my-project' },
+    {
+      validatePath: async () => ({ valid: true, resolvedPath: '/workspace/my-project' }),
+      ensureWorkspaceDirectory: async () => undefined,
+      persistProjectPath: () => ({
+        outcome: 'reactivated_archived',
+        project: {
+          ...projectRow,
+          isArchived: 1,
+        },
+      }),
+      getProjectByPath: () => projectRow,
+    },
+  );
+
+  assert.equal(result.outcome, 'reactivated_archived');
+  assert.equal(result.project.isArchived, true);
+});
diff --git a/server/modules/projects/tests/project-star.service.test.ts b/server/modules/projects/tests/project-star.service.test.ts
new file mode 100644
index 00000000..ea594c86
--- /dev/null
+++ b/server/modules/projects/tests/project-star.service.test.ts
@@ -0,0 +1,123 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { projectsDb } from '@/modules/database/index.js';
+import { applyLegacyStarredProjectIds, toggleProjectStar } from '@/modules/projects/services/project-star.service.js';
+import { AppError } from '@/shared/utils.js';
+
+type ProjectRow = {
+  project_id: string;
+  project_path: string;
+  custom_project_name: string | null;
+  isStarred: number;
+  isArchived: number;
+};
+
+test('toggleProjectStar throws when projectId is missing', () => {
+  assert.throws(
+    () => toggleProjectStar('   '),
+    (error: unknown) =>
+      error instanceof AppError
+      && error.code === 'PROJECT_ID_REQUIRED'
+      && error.statusCode === 400,
+  );
+});
+
+test('toggleProjectStar throws when project does not exist', () => {
+  const originalGetProjectById = projectsDb.getProjectById;
+  try {
+    projectsDb.getProjectById = () => null;
+    assert.throws(
+      () => toggleProjectStar('project-1'),
+      (error: unknown) =>
+        error instanceof AppError
+        && error.code === 'PROJECT_NOT_FOUND'
+        && error.statusCode === 404,
+    );
+  } finally {
+    projectsDb.getProjectById = originalGetProjectById;
+  }
+});
+
+test('toggleProjectStar flips star state and persists it', () => {
+  const originalGetProjectById = projectsDb.getProjectById;
+  const originalUpdateProjectIsStarredById = projectsDb.updateProjectIsStarredById;
+
+  let capturedProjectId = '';
+  let capturedState = false;
+
+  try {
+    projectsDb.getProjectById = () =>
+      ({
+        project_id: 'project-1',
+        project_path: '/workspace/project-1',
+        custom_project_name: 'project-1',
+        isStarred: 0,
+        isArchived: 0,
+      }) as ProjectRow;
+    projectsDb.updateProjectIsStarredById = (projectId: string, isStarred: boolean) => {
+      capturedProjectId = projectId;
+      capturedState = isStarred;
+    };
+
+    const result = toggleProjectStar('project-1');
+
+    assert.equal(result.isStarred, true);
+    assert.equal(capturedProjectId, 'project-1');
+    assert.equal(capturedState, true);
+  } finally {
+    projectsDb.getProjectById = originalGetProjectById;
+    projectsDb.updateProjectIsStarredById = originalUpdateProjectIsStarredById;
+  }
+});
+
+test('applyLegacyStarredProjectIds stars only valid, unstarred projects', () => {
+  const originalGetProjectById = projectsDb.getProjectById;
+  const originalUpdateProjectIsStarredById = projectsDb.updateProjectIsStarredById;
+
+  const updatedProjectIds: string[] = [];
+
+  try {
+    projectsDb.getProjectById = (projectId: string) => {
+      if (projectId === 'project-a') {
+        return {
+          project_id: 'project-a',
+          project_path: '/workspace/project-a',
+          custom_project_name: 'A',
+          isStarred: 0,
+          isArchived: 0,
+        } as ProjectRow;
+      }
+
+      if (projectId === 'project-b') {
+        return {
+          project_id: 'project-b',
+          project_path: '/workspace/project-b',
+          custom_project_name: 'B',
+          isStarred: 1,
+          isArchived: 0,
+        } as ProjectRow;
+      }
+
+      return null;
+    };
+    projectsDb.updateProjectIsStarredById = (projectId: string) => {
+      updatedProjectIds.push(projectId);
+    };
+
+    const result = applyLegacyStarredProjectIds([
+      'project-a',
+      'project-b',
+      'missing-project',
+      'project-a',
+      '',
+      '   ',
+    ]);
+
+    assert.equal(result.updated, 1);
+    assert.deepEqual(updatedProjectIds, ['project-a']);
+  } finally {
+    projectsDb.getProjectById = originalGetProjectById;
+    projectsDb.updateProjectIsStarredById = originalUpdateProjectIsStarredById;
+  }
+});
diff --git a/server/modules/projects/tests/projects-has-taskmaster.service.test.ts b/server/modules/projects/tests/projects-has-taskmaster.service.test.ts
new file mode 100644
index 00000000..f7e8863d
--- /dev/null
+++ b/server/modules/projects/tests/projects-has-taskmaster.service.test.ts
@@ -0,0 +1,105 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  getProjectTaskMaster,
+  getProjectTaskMasterById,
+} from '@/modules/projects/services/projects-has-taskmaster.service.js';
+import { AppError } from '@/shared/utils.js';
+
+test('getProjectTaskMasterById returns null when project path is missing', async () => {
+  const result = await getProjectTaskMasterById('project-1', {
+    resolveProjectPathById: () => null,
+    detectTaskMasterFolder: async () => {
+      throw new Error('detectTaskMasterFolder should not be called when path is missing');
+    },
+  });
+
+  assert.equal(result, null);
+});
+
+test('getProjectTaskMasterById returns configured status when taskmaster exists with essential files', async () => {
+  const result = await getProjectTaskMasterById('project-1', {
+    resolveProjectPathById: () => '/workspace/project-1',
+    detectTaskMasterFolder: async () => ({
+      hasTaskmaster: true,
+      hasEssentialFiles: true,
+      metadata: {
+        taskCount: 3,
+        subtaskCount: 0,
+        completed: 1,
+        pending: 2,
+        inProgress: 0,
+        review: 0,
+        completionPercentage: 33,
+        lastModified: '2026-01-01T00:00:00.000Z',
+      },
+    }),
+  });
+
+  assert.ok(result);
+  assert.equal(result.projectId, 'project-1');
+  assert.equal(result.projectPath, '/workspace/project-1');
+  assert.equal(result.taskmaster.hasTaskmaster, true);
+  assert.equal(result.taskmaster.hasEssentialFiles, true);
+  assert.equal(result.taskmaster.status, 'configured');
+  assert.deepEqual(result.taskmaster.metadata, {
+    taskCount: 3,
+    subtaskCount: 0,
+    completed: 1,
+    pending: 2,
+    inProgress: 0,
+    review: 0,
+    completionPercentage: 33,
+    lastModified: '2026-01-01T00:00:00.000Z',
+  });
+});
+
+test('getProjectTaskMasterById returns not-configured status when taskmaster is missing', async () => {
+  const result = await getProjectTaskMasterById('project-1', {
+    resolveProjectPathById: () => '/workspace/project-1',
+    detectTaskMasterFolder: async () => ({
+      hasTaskmaster: false,
+    }),
+  });
+
+  assert.ok(result);
+  assert.equal(result.taskmaster.hasTaskmaster, false);
+  assert.equal(result.taskmaster.hasEssentialFiles, false);
+  assert.equal(result.taskmaster.status, 'not-configured');
+  assert.equal(result.taskmaster.metadata, null);
+});
+
+test('getProjectTaskMaster throws when project id is missing', async () => {
+  await assert.rejects(
+    async () =>
+      getProjectTaskMaster('', async () => ({
+        projectId: 'project-1',
+        projectPath: '/workspace/project-1',
+        taskmaster: {
+          hasTaskmaster: true,
+          hasEssentialFiles: true,
+          metadata: null,
+          status: 'configured',
+        },
+      })),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.code, 'PROJECT_ID_REQUIRED');
+      assert.equal(error.statusCode, 400);
+      return true;
+    },
+  );
+});
+
+test('getProjectTaskMaster throws when project does not exist', async () => {
+  await assert.rejects(
+    async () => getProjectTaskMaster('project-that-does-not-exist', async () => null),
+    (error: unknown) => {
+      assert.ok(error instanceof AppError);
+      assert.equal(error.code, 'PROJECT_NOT_FOUND');
+      assert.equal(error.statusCode, 404);
+      return true;
+    },
+  );
+});
diff --git a/server/modules/providers/README.md b/server/modules/providers/README.md
new file mode 100644
index 00000000..6812fb3e
--- /dev/null
+++ b/server/modules/providers/README.md
@@ -0,0 +1,354 @@
+# Providers Module Guide
+
+This file documents the current provider contract in `server/modules/providers`.
+Keep it current whenever provider wiring, skill discovery, or session sync
+behavior changes. The goal is that a human or AI agent can add a new provider
+without guessing which files need to move.
+
+## Current Provider Shape
+
+Every provider wrapper exposes five facets:
+
+- `auth`
+- `mcp`
+- `skills`
+- `sessions`
+- `sessionSynchronizer`
+
+These correspond to the shared interfaces in `server/shared/interfaces.ts`:
+
+- `IProviderAuth`
+- `IProviderMcp`
+- `IProviderSkills`
+- `IProviderSessions`
+- `IProviderSessionSynchronizer`
+
+The services that consume them are:
+
+- `providerAuthService`
+- `providerMcpService`
+- `providerSkillsService`
+- `sessionsService`
+- `sessionSynchronizerService`
+
+Current provider ids in this repo are:
+
+- `claude`
+- `codex`
+- `cursor`
+- `gemini`
+- `opencode`
+
+Those ids are mirrored in backend unions and frontend provider constants. If
+adding a new provider, update every place that hardcodes this list.
+
+## Current File Layout
+
+Each provider lives under its own folder in `server/modules/providers/list/`:
+
+```text
+server/modules/providers/list/<provider>/
+  <provider>.provider.ts
+  <provider>-auth.provider.ts
+  <provider>-mcp.provider.ts
+  <provider>-skills.provider.ts
+  <provider>-sessions.provider.ts
+  <provider>-session-synchronizer.provider.ts
+```
+
+The existing provider folders are `claude`, `codex`, `cursor`, `gemini`, and
+`opencode`.
+
+## What Each Facet Does
+
+| Facet | Responsibility | Base / Service |
+| --- | --- | --- |
+| `auth` | Report install/auth state for the provider runtime | `IProviderAuth` -> `providerAuthService` |
+| `mcp` | Read, list, write, and remove provider-native MCP config | `McpProvider` -> `providerMcpService` |
+| `skills` | Discover provider-native skill markdown files | `SkillsProvider` -> `providerSkillsService` |
+| `sessions` | Normalize live events and fetch session history | `IProviderSessions` -> `sessionsService` |
+| `sessionSynchronizer` | Scan transcript artifacts and upsert session metadata | `IProviderSessionSynchronizer` -> `sessionSynchronizerService` |
+
+`sessions` and `sessionSynchronizer` are separate concerns:
+
+- `sessions` handles runtime event normalization and history fetches.
+- `sessionSynchronizer` handles file-backed session indexing into `sessionsDb`.
+
+## How To Add A Provider
+
+1. Add the provider id everywhere it is part of the contract.
+
+- Update `server/shared/types.ts` `LLMProvider`.
+- Update `src/types/app.ts` `LLMProvider` if the frontend should know about it.
+- Update `server/modules/providers/provider.routes.ts`.
+- Update `server/routes/agent.js` if the provider is launchable from the agent runtime.
+- Update `server/index.js` if the provider needs runtime boot or shutdown wiring.
+- Update `public/modelConstants.js` if the provider appears in README or public API docs.
+- Update `src/components/chat/hooks/useChatProviderState.ts` and
+  `src/components/chat/view/subcomponents/ProviderSelectionEmptyState.tsx` if
+  the provider should be selectable in chat.
+- Update `src/components/provider-auth/view/ProviderLoginModal.tsx` if the
+  provider has a login/setup flow.
+
+2. Create the wrapper class.
+
+- Add `server/modules/providers/list/<provider>/<provider>.provider.ts`.
+- Extend `AbstractProvider`.
+- Expose readonly `auth`, `mcp`, `skills`, `sessions`, and `sessionSynchronizer`.
+- Call `super('<provider>')`.
+
+3. Implement auth.
+
+- Return a full `ProviderAuthStatus`.
+- Treat normal `not installed` / `not authenticated` states as data, not exceptions.
+- Keep provider-specific credential discovery inside the auth provider.
+- If the provider has no auth step, return a stable unauthenticated or not-installed status instead of omitting the facet.
+
+4. Implement MCP.
+
+- Extend `McpProvider`.
+- Pass the supported scopes and transports to `super(...)`.
+- Implement the four required methods:
+  - `readScopedServers(...)`
+  - `writeScopedServers(...)`
+  - `buildServerConfig(...)`
+  - `normalizeServerConfig(...)`
+- Use the shared validation and normalization behavior from `McpProvider`.
+- Keep the provider-specific config format local to the provider implementation.
+
+Current MCP formats in this repo are:
+
+| Provider | User / Project Storage | Supported Scopes | Supported Transports |
+| --- | --- | --- | --- |
+| Claude | `.mcp.json` in user / local / project locations | `user`, `local`, `project` | `stdio`, `http`, `sse` |
+| Codex | `.codex/config.toml` | `user`, `project` | `stdio`, `http` |
+| Cursor | `.cursor/mcp.json` | `user`, `project` | `stdio`, `http` |
+| Gemini | `.gemini/settings.json` | `user`, `project` | `stdio`, `http` |
+| OpenCode | `~/.config/opencode/opencode.json` or `<workspace>/opencode.json` (`.jsonc` is read when present) | `user`, `project` | `stdio`, `http` |
+
+5. Implement skills.
+
+- Extend `SkillsProvider`.
+- Implement `getSkillSources(workspacePath)`.
+- Return the actual discovery roots for the provider.
+- Skills are discovered from `SKILL.md` files.
+- `readProviderSkillMarkdownDefinition(...)` reads front matter `name` and `description`.
+- If `name` is missing, the parent directory name is used as a fallback.
+- Use `recursive: true` only when the provider stores skills in nested trees.
+- Keep the emitted `command` string aligned with the provider's real skill syntax.
+
+Current skill discovery roots are:
+
+| Provider | User Roots | Project / Repo Roots | Prefix | Notes |
+| --- | --- | --- | --- | --- |
+| Claude | `~/.claude/skills` | `<workspace>/.claude/skills` | `/` | Also discovers Claude plugin skills from enabled plugin installs. Command skills live under `commands/`; markdown skills live under `skills/` and are scanned recursively. |
+| Codex | `~/.agents/skills`, `~/.codex/skills/.system`, `/etc/codex/skills` | `<workspace>/.agents/skills`, `path.dirname(workspacePath)/.agents/skills`, topmost git root `.agents/skills` | `$` | Overlapping roots are deduplicated before scanning. |
+| Cursor | `~/.cursor/skills` | `<workspace>/.cursor/skills`, `<workspace>/.agents/skills` | `/` | Uses slash-style commands. |
+| Gemini | `~/.gemini/skills`, `~/.agents/skills` | `<workspace>/.gemini/skills`, `<workspace>/.agents/skills` | `/` | Uses slash-style commands. |
+| OpenCode | `~/.config/opencode/skills`, `~/.claude/skills`, `~/.agents/skills` | Cwd-to-topmost-git-root `.opencode/skills`, `.claude/skills`, and `.agents/skills` | `/` | Reuses OpenCode, Claude, and Agents skill locations. Overlapping roots are deduplicated before scanning. |
+
+Command forms currently used by the providers are:
+
+- Claude user/project skills: `/skill-name`
+- Claude plugin skills: `/plugin-name:skill-name`
+- Codex skills: `$skill-name`
+- Cursor skills: `/skill-name`
+- Gemini skills: `/skill-name`
+- OpenCode skills: `/skill-name`
+
+6. Implement sessions.
+
+- Implement `normalizeMessage(raw, sessionId)` and `fetchHistory(sessionId, options)`.
+- Use `createNormalizedMessage(...)` and `generateMessageId(...)` for emitted messages.
+- Keep normalized message ids unique. If one raw event produces multiple text
+  parts, append a discriminator so ids do not collide.
+- Keep pagination consistent:
+  - `limit: null` means unbounded/full history.
+  - `limit: 0` means an empty page.
+  - always return `total`, `hasMore`, `offset`, and `limit` when paginating.
+- Sanitize any filesystem-derived ids before using them in file or database paths.
+- Do not assume a provider's history format matches another provider's format.
+
+7. Implement session synchronization.
+
+- Implement `synchronize(since?: Date)` to scan provider artifacts and upsert
+  sessions into `sessionsDb`.
+- Implement `synchronizeFile(filePath)` for single-file watcher updates.
+- Use the existing helpers when they fit:
+  - `buildLookupMap(...)`
+  - `extractFirstValidJsonlData(...)`
+  - `findFilesRecursivelyCreatedAfter(...)`
+  - `normalizeSessionName(...)`
+  - `readFileTimestamps(...)`
+- Make the sync resilient to partial, malformed, or missing provider files.
+- The orchestration service runs all provider synchronizers and only advances
+  `scan_state.last_scanned_at` when every provider succeeds.
+
+Current session sync roots are:
+
+| Provider | Scan Roots | Metadata Helpers / Notes |
+| --- | --- | --- |
+| Claude | `~/.claude/projects/**/*.jsonl` | Uses `~/.claude/history.jsonl` for name lookup and the trailing `ai-title`, `last-prompt`, or `custom-title` entries for title recovery. |
+| Codex | `~/.codex/sessions/**/*.jsonl` | Uses `~/.codex/session_index.jsonl` for title lookup and the last `task_complete` message for a fallback title. |
+| Cursor | `~/.cursor/projects/**/*.jsonl` | Uses sibling `worker.log` to recover `workspacePath`, then derives the session title from the first user prompt. |
+| Gemini | `~/.gemini/tmp/**/*.jsonl` | Current full scans only index temp JSONL chat artifacts. Single-file sync also accepts legacy `.json` files. |
+| OpenCode | `~/.local/share/opencode/opencode.db` | Reads active sessions/messages/parts from OpenCode's shared SQLite database and stores `jsonl_path` as `null` so deleting one app session cannot remove the shared DB. |
+
+8. Register the provider.
+
+- Add the new provider class to `server/modules/providers/provider.registry.ts`.
+- Update `server/modules/providers/provider.routes.ts` provider parsing.
+- If the provider introduces a new service or lifecycle hook, export it from the module entrypoint that consumes providers.
+
+9. Wire runtime and UI surfaces outside the providers module when needed.
+
+If the provider can run live chat sessions, update the runtime entrypoints too:
+
+- `server/routes/agent.js`
+- `server/index.js`
+
+If the provider is visible in the UI, update:
+
+- provider model fallback files under `server/modules/providers/list/<provider>/`
+- `src/components/chat/hooks/useChatProviderState.ts`
+- `src/components/chat/view/subcomponents/ProviderSelectionEmptyState.tsx`
+- `src/components/provider-auth/view/ProviderLoginModal.tsx`
+- `src/components/mcp/constants.ts`
+
+## Minimal Wrapper Template
+
+```ts
+import { AbstractProvider } from '@/modules/providers/shared/base/abstract.provider.js';
+import { <Provider>ProviderAuth } from './<provider>-auth.provider.js';
+import { <Provider>McpProvider } from './<provider>-mcp.provider.js';
+import { <Provider>SkillsProvider } from './<provider>-skills.provider.js';
+import { <Provider>SessionsProvider } from './<provider>-sessions.provider.js';
+import { <Provider>SessionSynchronizer } from './<provider>-session-synchronizer.provider.js';
+import type {
+  IProviderAuth,
+  IProviderMcp,
+  IProviderSessionSynchronizer,
+  IProviderSessions,
+  IProviderSkills,
+} from '@/shared/interfaces.js';
+
+export class <Provider>Provider extends AbstractProvider {
+  readonly auth: IProviderAuth = new <Provider>ProviderAuth();
+  readonly mcp: IProviderMcp = new <Provider>McpProvider();
+  readonly skills: IProviderSkills = new <Provider>SkillsProvider();
+  readonly sessions: IProviderSessions = new <Provider>SessionsProvider();
+  readonly sessionSynchronizer: IProviderSessionSynchronizer =
+    new <Provider>SessionSynchronizer();
+
+  constructor() {
+    super('<provider>');
+  }
+}
+```
+
+## Minimal Skills Template
+
+```ts
+import path from 'node:path';
+
+import { SkillsProvider } from '@/modules/providers/shared/skills/skills.provider.js';
+import type { ProviderSkillSource } from '@/shared/types.js';
+
+export class <Provider>SkillsProvider extends SkillsProvider {
+  constructor() {
+    super('<provider>');
+  }
+
+  protected async getSkillSources(workspacePath: string): Promise<ProviderSkillSource[]> {
+    return [
+      {
+        scope: 'project',
+        rootDir: path.join(workspacePath, '.<provider>', 'skills'),
+        commandPrefix: '/',
+      },
+    ];
+  }
+}
+```
+
+## Minimal Session Sync Template
+
+```ts
+import type { IProviderSessionSynchronizer } from '@/shared/interfaces.js';
+
+export class <Provider>SessionSynchronizer implements IProviderSessionSynchronizer {
+  async synchronize(since?: Date): Promise<number> {
+    return 0;
+  }
+
+  async synchronizeFile(filePath: string): Promise<string | null> {
+    return null;
+  }
+}
+```
+
+## AI Prompt Template
+
+Use this prompt when asking an AI agent to add a provider:
+
+```text
+Add a new provider "<provider>" using the current provider module architecture.
+
+Requirements:
+1) Create:
+   - server/modules/providers/list/<provider>/<provider>.provider.ts
+   - server/modules/providers/list/<provider>/<provider>-auth.provider.ts
+   - server/modules/providers/list/<provider>/<provider>-mcp.provider.ts
+   - server/modules/providers/list/<provider>/<provider>-skills.provider.ts
+   - server/modules/providers/list/<provider>/<provider>-sessions.provider.ts
+   - server/modules/providers/list/<provider>/<provider>-session-synchronizer.provider.ts
+2) Register in:
+   - server/modules/providers/provider.registry.ts
+   - server/modules/providers/provider.routes.ts
+   - server/shared/types.ts LLMProvider
+   - src/types/app.ts LLMProvider
+3) Mirror the nearest existing provider implementation for file naming, style,
+   and error handling.
+4) Implement skills support with SkillsProvider and the current skill roots.
+5) Implement session synchronization if the provider stores transcript files.
+6) Ensure sessions use unique ids, safe path handling, and correct pagination.
+7) Keep `sessions` and `sessionSynchronizer` separate.
+8) Run:
+   - npx eslint <touched files>
+   - npx tsc --noEmit -p server/tsconfig.json
+```
+
+## Validation
+
+After adding or changing a provider, run the relevant checks:
+
+```bash
+npx eslint server/modules/providers/**/*.ts server/shared/types.ts server/shared/interfaces.ts
+npx tsc --noEmit -p server/tsconfig.json
+```
+
+Useful tests in this repo:
+
+- `server/modules/providers/tests/mcp.test.ts`
+- `server/modules/providers/tests/skills.test.ts`
+- `server/modules/providers/tests/opencode-sessions.test.ts`
+
+If you touch sessions or session synchronization, add or update focused tests
+alongside the implementation.
+
+## Common Mistakes
+
+- Adding provider files but forgetting `provider.registry.ts` or
+  `provider.routes.ts`.
+- Updating backend provider ids but not `src/types/app.ts` or the frontend
+  provider constants.
+- Omitting `skills` or `sessionSynchronizer` from the wrapper.
+- Returning duplicate normalized message ids for split content.
+- Treating `limit === 0` as unbounded history.
+- Building file paths from raw session ids without validation.
+- Hardcoding a skill root without checking the provider's actual discovery rules.
+- Forgetting that Claude plugin skills are discovered differently from normal
+  user/project skill folders.
+- Assuming one provider's MCP config file format works for the others.
+
+
diff --git a/server/modules/providers/index.ts b/server/modules/providers/index.ts
new file mode 100644
index 00000000..0d8d8edd
--- /dev/null
+++ b/server/modules/providers/index.ts
@@ -0,0 +1,5 @@
+export { sessionSynchronizerService } from './services/session-synchronizer.service.js';
+export { providerSkillsService } from './services/skills.service.js';
+
+export { initializeSessionsWatcher } from './services/sessions-watcher.service.js';
+export { closeSessionsWatcher } from './services/sessions-watcher.service.js';
diff --git a/server/modules/providers/list/claude/claude-auth.provider.ts b/server/modules/providers/list/claude/claude-auth.provider.ts
index 1194ae1d..68874b9d 100644
--- a/server/modules/providers/list/claude/claude-auth.provider.ts
+++ b/server/modules/providers/list/claude/claude-auth.provider.ts
@@ -4,6 +4,7 @@ import path from 'node:path';
 
 import spawn from 'cross-spawn';
 
+import { resolveClaudeCodeExecutablePath } from '@/shared/claude-cli-path.js';
 import type { IProviderAuth } from '@/shared/interfaces.js';
 import type { ProviderAuthStatus } from '@/shared/types.js';
 import { readObjectRecord, readOptionalString } from '@/shared/utils.js';
@@ -15,18 +16,22 @@ type ClaudeCredentialsStatus = {
   error?: string;
 };
 
+const hasErrorCode = (error: unknown, code: string): boolean => (
+  error instanceof Error && 'code' in error && error.code === code
+);
+
 export class ClaudeProviderAuth implements IProviderAuth {
   /**
    * Checks whether the Claude Code CLI is available on this host.
    */
   private checkInstalled(): boolean {
-      const cliPath = process.env.CLAUDE_CLI_PATH || 'claude';
-      try {
-        spawn.sync(cliPath, ['--version'], { stdio: 'ignore', timeout: 5000 });
-        return true;
-      } catch {
-        return false;
-      }
+    const cliPath = resolveClaudeCodeExecutablePath(process.env.CLAUDE_CLI_PATH);
+    try {
+      spawn.sync(cliPath, ['--version'], { stdio: 'ignore', timeout: 5000 });
+      return true;
+    } catch {
+      return false;
+    }
   }
 
   /**
@@ -76,6 +81,8 @@ export class ClaudeProviderAuth implements IProviderAuth {
    * Checks Claude credentials in the same priority order used by Claude Code.
    */
   private async checkCredentials(): Promise<ClaudeCredentialsStatus> {
+    const missingCredentialsError = 'Claude CLI is not authenticated. Run claude /login or configure ANTHROPIC_API_KEY.';
+
     if (process.env.ANTHROPIC_API_KEY?.trim()) {
       return { authenticated: true, email: 'API Key Auth', method: 'api_key' };
     }
@@ -109,15 +116,33 @@ export class ClaudeProviderAuth implements IProviderAuth {
 
         return {
           authenticated: false,
-          email,
-          method: 'credentials_file',
-          error: 'OAuth token has expired. Please re-authenticate with claude login',
+          email: null,
+          method: null,
+          error: 'Claude login has expired. Run claude /login again.',
         };
       }
 
-      return { authenticated: false, email: null, method: null };
-    } catch {
-      return { authenticated: false, email: null, method: null };
+      return {
+        authenticated: false,
+        email: null,
+        method: null,
+        error: missingCredentialsError,
+      };
+    } catch (error) {
+      let errorMessage = 'Unable to read Claude credentials. Run claude /login again.';
+
+      if (hasErrorCode(error, 'ENOENT')) {
+        errorMessage = missingCredentialsError;
+      } else if (error instanceof SyntaxError) {
+        errorMessage = 'Claude credentials are unreadable. Run claude /login again.';
+      }
+
+      return {
+        authenticated: false,
+        email: null,
+        method: null,
+        error: errorMessage,
+      };
     }
   }
 }
diff --git a/server/modules/providers/list/claude/claude-models.provider.ts b/server/modules/providers/list/claude/claude-models.provider.ts
new file mode 100644
index 00000000..81e89027
--- /dev/null
+++ b/server/modules/providers/list/claude/claude-models.provider.ts
@@ -0,0 +1,191 @@
+import { readFile } from 'node:fs/promises';
+
+import { sessionsDb } from '@/modules/database/index.js';
+import type { IProviderModels } from '@/shared/interfaces.js';
+import type {
+  ProviderChangeActiveModelInput,
+  ProviderCurrentActiveModel,
+  ProviderModelsDefinition,
+  ProviderSessionActiveModelChange,
+} from '@/shared/types.js';
+import {
+  buildDefaultProviderCurrentActiveModel,
+  writeProviderSessionActiveModelChange,
+} from '@/shared/utils.js';
+
+export const CLAUDE_FALLBACK_MODELS: ProviderModelsDefinition = {
+  OPTIONS: [
+    {
+      value: 'default',
+      label: 'Default (recommended)',
+      description: 'Use the default model (currently Opus 4.7 (1M context)) · $5/$25 per Mtok',
+    },
+    {
+      value: 'sonnet',
+      label: 'Sonnet',
+      description: 'Sonnet 4.6 · Best for everyday tasks · $3/$15 per Mtok',
+    },
+    {
+      value: 'sonnet[1m]',
+      label: 'Sonnet (1M context)',
+      description: 'Sonnet 4.6 for long sessions · $3/$15 per Mtok',
+    },
+    {
+      value: 'haiku',
+      label: 'Haiku',
+      description: 'Haiku 4.5 · Fastest for quick answers · $1/$5 per Mtok',
+    },
+  ],
+  DEFAULT: 'default',
+};
+type ClaudeInitEvent = {
+  sessionId?: string;
+  session_id?: string;
+  type?: string;
+  subtype?: string;
+  model?: string;
+  message?: {
+    content?: unknown;
+    model?: string;
+  };
+};
+
+const ANSI_PATTERN = new RegExp(
+  '[\\u001B\\u009B][[\\]()#;?]*(?:'
+  + '(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]'
+  + '|(?:[\\dA-PR-TZcf-ntqry=><~]))',
+  'g',
+);
+
+const extractClaudeEventModel = (event: ClaudeInitEvent, sessionId: string): string | null => {
+  const eventSessionId = event.sessionId ?? event.session_id;
+  if (eventSessionId && eventSessionId !== sessionId) {
+    return null;
+  }
+
+  const contentModel = extractClaudeModelFromMessageContent(event.message?.content);
+  if (contentModel) {
+    return contentModel;
+  }
+
+  const directModel = event.model?.trim();
+  if (directModel) {
+    return directModel;
+  }
+
+  const messageModel = event.message?.model?.trim();
+  return messageModel || null;
+};
+
+const stripAnsi = (value: string): string => value.replace(ANSI_PATTERN, '');
+
+const extractTaggedContent = (content: string, tagName: string): string | null => {
+  const escapedTagName = tagName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = new RegExp(`<${escapedTagName}>([\\s\\S]*?)<\\/${escapedTagName}>`).exec(content);
+  return match ? match[1] : null;
+};
+
+const extractClaudeModelFromTextContent = (content: string): string | null => {
+  const localCommandStdout = extractTaggedContent(content, 'local-command-stdout');
+  if (localCommandStdout !== null) {
+    const cleanedStdout = stripAnsi(localCommandStdout).replace(/\s+/g, ' ').trim();
+    const changedModel = /(?:set|changed|switched)\s+model\s+to\s+(.+?)\.?$/i.exec(cleanedStdout);
+    if (changedModel?.[1]?.trim()) {
+      return changedModel[1].trim();
+    }
+  }
+
+  const modelTag = extractTaggedContent(content, 'model')?.trim();
+  return modelTag || null;
+};
+
+const extractClaudeModelFromMessageContent = (content: unknown): string | null => {
+  if (typeof content === 'string') {
+    return extractClaudeModelFromTextContent(content);
+  }
+
+  if (!Array.isArray(content)) {
+    return null;
+  }
+
+  for (const part of content) {
+    if (!part || typeof part !== 'object' || !('text' in part) || typeof part.text !== 'string') {
+      continue;
+    }
+
+    const model = extractClaudeModelFromTextContent(part.text);
+    if (model) {
+      return model;
+    }
+  }
+
+  return null;
+};
+
+const readClaudeSessionModelFromJsonl = async (
+  sessionId: string,
+  jsonlPath: string,
+): Promise<ProviderCurrentActiveModel | null> => {
+  const content = await readFile(jsonlPath, 'utf8');
+  const lines = content
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    try {
+      const event = JSON.parse(lines[index]) as ClaudeInitEvent;
+      const model = extractClaudeEventModel(event, sessionId);
+      if (model) {
+        return { model };
+      }
+    } catch {
+      // Skip malformed JSONL lines that can happen during concurrent writes.
+    }
+  }
+
+  return null;
+};
+
+export class ClaudeProviderModels implements IProviderModels {
+  async getSupportedModels(): Promise<ProviderModelsDefinition> {
+    // claude creates a new jsonl file as a separate session for this request.
+    // As a result, it lists the workspace where this is invoked when it shouldn't.
+    //
+    // Disabled for now:
+    // const queryInstance = query({
+    //   prompt: 'Get supported models',
+    //   options: buildClaudeQueryOptions(),
+    // });
+    // const supportedModels = await queryInstance.supportedModels();
+    // queryInstance.close();
+    // return buildClaudeModelsDefinition(supportedModels);
+    return CLAUDE_FALLBACK_MODELS;
+  }
+
+  async getCurrentActiveModel(sessionId?: string): Promise<ProviderCurrentActiveModel> {
+    if (!sessionId?.trim()) {
+      return buildDefaultProviderCurrentActiveModel(await this.getSupportedModels());
+    }
+
+    try {
+      const jsonlPath = sessionsDb.getSessionById(sessionId)?.jsonl_path;
+      const activeModel = jsonlPath
+        ? await readClaudeSessionModelFromJsonl(sessionId, jsonlPath)
+        : null;
+      if (activeModel?.model) {
+        return activeModel;
+      }
+    } catch {
+      // Fall through to the provider default when the session-backed lookup fails.
+    }
+
+    return buildDefaultProviderCurrentActiveModel(await this.getSupportedModels());
+  }
+
+  async changeActiveModel(
+    input: ProviderChangeActiveModelInput,
+  ): Promise<ProviderSessionActiveModelChange> {
+    return writeProviderSessionActiveModelChange('claude', input);
+  }
+}
diff --git a/server/modules/providers/list/claude/claude-session-synchronizer.provider.ts b/server/modules/providers/list/claude/claude-session-synchronizer.provider.ts
new file mode 100644
index 00000000..1bf3bffc
--- /dev/null
+++ b/server/modules/providers/list/claude/claude-session-synchronizer.provider.ts
@@ -0,0 +1,176 @@
+import os from 'node:os';
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+import { sessionsDb } from '@/modules/database/index.js';
+import {
+  buildLookupMap,
+  extractFirstValidJsonlData,
+  findFilesRecursivelyCreatedAfter,
+  normalizeSessionName,
+  readFileTimestamps,
+} from '@/shared/utils.js';
+import type { IProviderSessionSynchronizer } from '@/shared/interfaces.js';
+
+type ParsedSession = {
+  sessionId: string;
+  projectPath: string;
+  sessionName?: string;
+};
+
+/**
+ * Session indexer for Claude transcript artifacts.
+ */
+export class ClaudeSessionSynchronizer implements IProviderSessionSynchronizer {
+  private readonly provider = 'claude' as const;
+  private readonly claudeHome = path.join(os.homedir(), '.claude');
+
+  /**
+   * Scans ~/.claude/projects and upserts discovered sessions into DB.
+   */
+  async synchronize(since?: Date): Promise<number> {
+    const nameMap = await buildLookupMap(path.join(this.claudeHome, 'history.jsonl'), 'sessionId', 'display');
+    const files = await findFilesRecursivelyCreatedAfter(
+      path.join(this.claudeHome, 'projects'),
+      '.jsonl',
+      since ?? null
+    );
+
+    let processed = 0;
+    for (const filePath of files) {
+      const parsed = await this.processSessionFile(filePath, nameMap);
+      if (!parsed) {
+        continue;
+      }
+
+      const timestamps = await readFileTimestamps(filePath);
+      sessionsDb.createSession(
+        parsed.sessionId,
+        this.provider,
+        parsed.projectPath,
+        parsed.sessionName,
+        timestamps.createdAt,
+        timestamps.updatedAt,
+        filePath
+      );
+      processed += 1;
+    }
+
+    return processed;
+  }
+
+  /**
+   * Parses and upserts one Claude session JSONL file.
+   */
+  async synchronizeFile(filePath: string): Promise<string | null> {
+    if (!filePath.endsWith('.jsonl')) {
+      return null;
+    }
+
+    const nameMap = await buildLookupMap(path.join(this.claudeHome, 'history.jsonl'), 'sessionId', 'display');
+    const parsed = await this.processSessionFile(filePath, nameMap);
+    if (!parsed) {
+      return null;
+    }
+
+    const timestamps = await readFileTimestamps(filePath);
+    return sessionsDb.createSession(
+      parsed.sessionId,
+      this.provider,
+      parsed.projectPath,
+      parsed.sessionName,
+      timestamps.createdAt,
+      timestamps.updatedAt,
+      filePath
+    );
+  }
+
+  /**
+   * Extracts session metadata from one Claude JSONL session file.
+   */
+  private async processSessionFile(
+    filePath: string,
+    nameMap: Map<string, string>
+  ): Promise<ParsedSession | null> {
+    const parsed = await extractFirstValidJsonlData(filePath, (rawData) => {
+      const data = rawData as Record<string, unknown>;
+      const sessionId = typeof data.sessionId === 'string' ? data.sessionId : undefined;
+      const projectPath = typeof data.cwd === 'string' ? data.cwd : undefined;
+
+      if (!sessionId || !projectPath) {
+        return null;
+      }
+
+      return {
+        sessionId,
+        projectPath,
+      };
+    });
+
+    if (!parsed) {
+      return null;
+    }
+
+    const existingSession = sessionsDb.getSessionById(parsed.sessionId);
+    const existingSessionName = existingSession?.custom_name;
+    if (existingSessionName && existingSessionName !== 'Untitled Claude Session') {
+      return {
+        ...parsed,
+        sessionName: normalizeSessionName(existingSessionName, 'Untitled Claude Session'),
+      };
+    }
+
+    let sessionName = nameMap.get(parsed.sessionId);
+    if (!sessionName) {
+      sessionName = await this.extractSessionAiTitleFromEnd(filePath, parsed.sessionId);
+    }
+
+    return {
+      ...parsed,
+      sessionName: normalizeSessionName(sessionName, 'Untitled Claude Session'),
+    };
+  }
+
+  private async extractSessionAiTitleFromEnd(
+    filePath: string,
+    sessionId: string
+  ): Promise<string | undefined> {
+    try {
+      const content = await readFile(filePath, 'utf8');
+      const lines = content.split(/\r?\n/);
+
+      for (let index = lines.length - 1; index >= 0; index -= 1) {
+        const line = lines[index]?.trim();
+        if (!line) {
+          continue;
+        }
+
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(line);
+        } catch {
+          continue;
+        }
+
+        const data = parsed as Record<string, unknown>;
+        const eventType = typeof data.type === 'string' ? data.type : undefined;
+        const eventSessionId = typeof data.sessionId === 'string' ? data.sessionId : undefined;
+        const aiTitle = typeof data.aiTitle === 'string' ? data.aiTitle : undefined;
+        const lastPrompt = typeof data.lastPrompt === 'string' ? data.lastPrompt : undefined;
+        const claudeRenamedTitle = typeof data.customTitle === 'string' ? data.customTitle : undefined;
+
+        if (
+          (eventType === 'ai-title' && eventSessionId === sessionId && aiTitle?.trim()) ||
+          (eventType === 'last-prompt' && eventSessionId === sessionId && lastPrompt?.trim()) ||
+          (eventType === "custom-title" && eventSessionId === sessionId && claudeRenamedTitle?.trim())
+        ) {
+          return aiTitle || lastPrompt || claudeRenamedTitle;
+        }
+      }
+    } catch {
+      // Ignore missing/unreadable files so sync can continue.
+    }
+
+    return undefined;
+  }
+}
diff --git a/server/modules/providers/list/claude/claude-sessions.provider.ts b/server/modules/providers/list/claude/claude-sessions.provider.ts
index 72bbe07e..f803d92c 100644
--- a/server/modules/providers/list/claude/claude-sessions.provider.ts
+++ b/server/modules/providers/list/claude/claude-sessions.provider.ts
@@ -1,7 +1,12 @@
-import { getSessionMessages } from '@/projects.js';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import readline from 'node:readline';
+
 import type { IProviderSessions } from '@/shared/interfaces.js';
 import type { AnyRecord, FetchHistoryOptions, FetchHistoryResult, NormalizedMessage } from '@/shared/types.js';
 import { createNormalizedMessage, generateMessageId, readObjectRecord } from '@/shared/utils.js';
+import { sessionsDb } from '@/modules/database/index.js';
 
 const PROVIDER = 'claude';
 
@@ -15,30 +20,198 @@ type ClaudeToolResult = {
 type ClaudeHistoryResult =
   | AnyRecord[]
   | {
-      messages?: AnyRecord[];
-      total?: number;
-      hasMore?: boolean;
-    };
+    messages?: AnyRecord[];
+    total?: number;
+    hasMore?: boolean;
+  };
 
-const loadClaudeSessionMessages = getSessionMessages as unknown as (
-  projectName: string,
+type ClaudeHistoryMessagesResult =
+  | AnyRecord[]
+  | {
+    messages: AnyRecord[];
+    total: number;
+    hasMore: boolean;
+    offset?: number;
+    limit?: number | null;
+  };
+
+async function parseAgentTools(filePath: string): Promise<AnyRecord[]> {
+  const tools: AnyRecord[] = [];
+
+  try {
+    const fileStream = fs.createReadStream(filePath);
+    const rl = readline.createInterface({
+      input: fileStream,
+      crlfDelay: Infinity,
+    });
+
+    for await (const line of rl) {
+      if (!line.trim()) {
+        continue;
+      }
+
+      try {
+        const entry = JSON.parse(line) as AnyRecord;
+
+        if (entry.message?.role === 'assistant' && Array.isArray(entry.message?.content)) {
+          for (const part of entry.message.content as AnyRecord[]) {
+            if (part.type === 'tool_use') {
+              tools.push({
+                toolId: part.id,
+                toolName: part.name,
+                toolInput: part.input,
+                timestamp: entry.timestamp,
+              });
+            }
+          }
+        }
+
+        if (entry.message?.role === 'user' && Array.isArray(entry.message?.content)) {
+          for (const part of entry.message.content as AnyRecord[]) {
+            if (part.type !== 'tool_result') {
+              continue;
+            }
+
+            const tool = tools.find((candidate) => candidate.toolId === part.tool_use_id);
+            if (!tool) {
+              continue;
+            }
+
+            tool.toolResult = {
+              content: typeof part.content === 'string'
+                ? part.content
+                : Array.isArray(part.content)
+                  ? part.content
+                    .map((contentPart: AnyRecord) => contentPart?.text || '')
+                    .join('\n')
+                  : JSON.stringify(part.content),
+              isError: Boolean(part.is_error),
+            };
+          }
+        }
+      } catch {
+        // Skip malformed lines that can happen during concurrent writes.
+      }
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`Error parsing agent file ${filePath}:`, message);
+  }
+
+  return tools;
+}
+
+async function getSessionMessages(
   sessionId: string,
   limit: number | null,
   offset: number,
-) => Promise<ClaudeHistoryResult>;
+): Promise<ClaudeHistoryMessagesResult> {
+  try {
+    const jsonLPath = sessionsDb.getSessionById(sessionId)?.jsonl_path;
+
+    if (!jsonLPath) {
+      return { messages: [], total: 0, hasMore: false };
+    }
+
+    const projectDir = path.dirname(jsonLPath);
+    const files = await fsp.readdir(projectDir);
+    const agentFiles = files.filter((file) => file.endsWith('.jsonl') && file.startsWith('agent-'));
+
+    const messages: AnyRecord[] = [];
+    const agentToolsCache = new Map<string, AnyRecord[]>();
+
+    const fileStream = fs.createReadStream(jsonLPath);
+    const rl = readline.createInterface({
+      input: fileStream,
+      crlfDelay: Infinity,
+    });
+
+    for await (const line of rl) {
+      if (!line.trim()) {
+        continue;
+      }
+
+      try {
+        const entry = JSON.parse(line) as AnyRecord;
+        if (entry.sessionId === sessionId) {
+          messages.push(entry);
+        }
+      } catch {
+        // Skip malformed JSONL lines that can happen during concurrent writes.
+      }
+    }
+
+    const agentIds = new Set<string>();
+    for (const message of messages) {
+      const agentId = message.toolUseResult?.agentId;
+      if (agentId) {
+        agentIds.add(String(agentId));
+      }
+    }
+
+    for (const agentId of agentIds) {
+      const agentFileName = `agent-${agentId}.jsonl`;
+      if (!agentFiles.includes(agentFileName)) {
+        continue;
+      }
+
+      const agentFilePath = path.join(projectDir, agentFileName);
+      const tools = await parseAgentTools(agentFilePath);
+      agentToolsCache.set(agentId, tools);
+    }
+
+    for (const message of messages) {
+      const agentId = message.toolUseResult?.agentId;
+      if (!agentId) {
+        continue;
+      }
+
+      const agentTools = agentToolsCache.get(String(agentId));
+      if (agentTools && agentTools.length > 0) {
+        message.subagentTools = agentTools;
+      }
+    }
+
+    const sortedMessages = messages.sort(
+      (a, b) => new Date(a.timestamp || 0).getTime() - new Date(b.timestamp || 0).getTime(),
+    );
+    const total = sortedMessages.length;
+
+    if (limit === null) {
+      return sortedMessages;
+    }
+
+    const startIndex = Math.max(0, total - offset - limit);
+    const endIndex = total - offset;
+    const paginatedMessages = sortedMessages.slice(startIndex, endIndex);
+    const hasMore = startIndex > 0;
+
+    return {
+      messages: paginatedMessages,
+      total,
+      hasMore,
+      offset,
+      limit,
+    };
+  } catch (error) {
+    console.error(`Error reading messages for session ${sessionId}:`, error);
+    return limit === null ? [] : { messages: [], total: 0, hasMore: false };
+  }
+}
 
 /**
- * Claude writes internal command and system reminder entries into history.
- * Those are useful for the CLI but should not appear in the user-facing chat.
+ * Claude writes a mix of truly internal transcript rows and "UI-hidden" local
+ * command artifacts into the same JSONL stream.
+ *
+ * Important distinction:
+ * - system reminders / caveats / interruption banners should stay hidden
+ * - local command payloads (`<command-name>...`) and stdout wrappers
+ *   (`<local-command-stdout>...`) should be remapped into normal chat messages
+ *   instead of being discarded as internal content
  */
 const INTERNAL_CONTENT_PREFIXES = [
-  '<command-name>',
-  '<command-message>',
-  '<command-args>',
-  '<local-command-stdout>',
   '<system-reminder>',
   'Caveat:',
-  'This session is being continued from a previous',
   '[Request interrupted',
 ] as const;
 
@@ -46,6 +219,73 @@ function isInternalContent(content: string): boolean {
   return INTERNAL_CONTENT_PREFIXES.some((prefix) => content.startsWith(prefix));
 }
 
+/**
+ * Claude wraps local slash-command metadata in lightweight XML-like tags inside
+ * a plain string payload. We intentionally parse only the small tag surface we
+ * care about instead of introducing a generic XML parser for untrusted history.
+ */
+function extractTaggedContent(content: string, tagName: string): string | null {
+  const escapedTagName = tagName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = new RegExp(`<${escapedTagName}>([\\s\\S]*?)<\\/${escapedTagName}>`).exec(content);
+  return match ? match[1] : null;
+}
+
+type ClaudeLocalCommandPayload = {
+  commandName: string;
+  commandMessage: string;
+  commandArgs: string;
+};
+
+/**
+ * Converts Claude's hidden local command wrapper into structured metadata.
+ *
+ * The three tags often coexist in one string payload. Returning `null` lets the
+ * normal text path continue untouched for unrelated messages.
+ */
+function parseLocalCommandPayload(content: string): ClaudeLocalCommandPayload | null {
+  const commandName = extractTaggedContent(content, 'command-name');
+  const commandMessage = extractTaggedContent(content, 'command-message');
+  const commandArgs = extractTaggedContent(content, 'command-args');
+
+  if (commandName === null && commandMessage === null && commandArgs === null) {
+    return null;
+  }
+
+  return {
+    commandName: commandName ?? '',
+    commandMessage: commandMessage ?? '',
+    commandArgs: commandArgs ?? '',
+  };
+}
+
+/**
+ * Produces the short user-visible command string that should appear in chat.
+ *
+ * We prefer the slash-prefixed command name because that most closely matches
+ * what the user actually typed, and only fall back to the message body when the
+ * command name is unavailable in older transcript variants.
+ */
+function buildLocalCommandDisplayText(payload: ClaudeLocalCommandPayload): string {
+  const commandName = payload.commandName.trim();
+  const commandMessage = payload.commandMessage.trim();
+  const commandArgs = payload.commandArgs.trim();
+  const baseCommand = commandName || commandMessage;
+
+  if (!baseCommand) {
+    return '';
+  }
+
+  return commandArgs ? `${baseCommand} ${commandArgs}` : baseCommand;
+}
+
+/**
+ * Claude local-command stdout may contain ANSI styling codes because it was
+ * captured from the terminal. The web chat should receive readable plain text.
+ */
+function stripAnsiFormatting(text: string): string {
+  return text.replace(/\u001B\[[0-9;?]*[ -/]*[@-~]/g, '');
+}
+
 export class ClaudeSessionsProvider implements IProviderSessions {
   /**
    * Normalizes one Claude JSONL entry or live SDK stream event into the shared
@@ -68,7 +308,7 @@ export class ClaudeSessionsProvider implements IProviderSessions {
     const ts = raw.timestamp || new Date().toISOString();
     const baseId = raw.uuid || generateMessageId('claude');
 
-    if (raw.message?.role === 'user' && raw.message?.content) {
+    if (raw.message?.role === 'user' && raw.message?.content && raw.isMeta !== true) {
       if (Array.isArray(raw.message.content)) {
         for (let partIndex = 0; partIndex < raw.message.content.length; partIndex++) {
           const part = raw.message.content[partIndex];
@@ -121,6 +361,80 @@ export class ClaudeSessionsProvider implements IProviderSessions {
         }
       } else if (typeof raw.message.content === 'string') {
         const text = raw.message.content;
+
+        /**
+         * Claude stores compact summaries as synthetic "user" rows so the CLI
+         * can resume the next session turn with the summary in-context.
+         *
+         * For the web UI this is much more useful as assistant-authored summary
+         * text; otherwise it is both filtered by the generic internal-prefix
+         * check and visually mislabeled as a user message.
+         */
+        if (raw.isCompactSummary === true && text.trim()) {
+          messages.push(createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'text',
+            role: 'assistant',
+            content: text,
+            isCompactSummary: true,
+          }));
+          return messages;
+        }
+
+        /**
+         * Local slash commands are serialized as tagged text even though they
+         * are semantically a user action. Expose the parsed fields to the
+         * frontend and emit a plain user-visible command string so the command
+         * no longer disappears from history.
+         */
+        const localCommandPayload = parseLocalCommandPayload(text);
+        if (localCommandPayload) {
+          const displayText = buildLocalCommandDisplayText(localCommandPayload);
+          if (displayText) {
+            messages.push(createNormalizedMessage({
+              id: baseId,
+              sessionId,
+              timestamp: ts,
+              provider: PROVIDER,
+              kind: 'text',
+              role: 'user',
+              content: displayText,
+              commandName: localCommandPayload.commandName,
+              commandMessage: localCommandPayload.commandMessage,
+              commandArgs: localCommandPayload.commandArgs,
+              isLocalCommand: true,
+            }));
+          }
+          return messages;
+        }
+
+        /**
+         * Local command stdout is also written as a "user" row in Claude's
+         * transcript, but it is terminal output produced in response to the
+         * command. Re-label it as assistant text so the chat transcript matches
+         * the actual conversational flow seen by the user.
+         */
+        const localCommandStdout = extractTaggedContent(text, 'local-command-stdout');
+        if (localCommandStdout !== null) {
+          const stdoutText = stripAnsiFormatting(localCommandStdout).trim();
+          if (stdoutText) {
+            messages.push(createNormalizedMessage({
+              id: baseId,
+              sessionId,
+              timestamp: ts,
+              provider: PROVIDER,
+              kind: 'text',
+              role: 'assistant',
+              content: stdoutText,
+              isLocalCommandStdout: true,
+            }));
+          }
+          return messages;
+        }
+
         if (text && !isInternalContent(text)) {
           messages.push(createNormalizedMessage({
             id: baseId,
@@ -238,14 +552,13 @@ export class ClaudeSessionsProvider implements IProviderSessions {
     sessionId: string,
     options: FetchHistoryOptions = {},
   ): Promise<FetchHistoryResult> {
-    const { projectName, limit = null, offset = 0 } = options;
-    if (!projectName) {
-      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
-    }
+    const { limit = null, offset = 0 } = options;
 
     let result: ClaudeHistoryResult;
     try {
-      result = await loadClaudeSessionMessages(projectName, sessionId, limit, offset);
+      // Load full history first so `total` reflects frontend-normalized messages,
+      // not raw JSONL records.
+      result = await getSessionMessages(sessionId, null, 0);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       console.warn(`[ClaudeProvider] Failed to load session ${sessionId}:`, message);
@@ -253,8 +566,6 @@ export class ClaudeSessionsProvider implements IProviderSessions {
     }
 
     const rawMessages = Array.isArray(result) ? result : (result.messages || []);
-    const total = Array.isArray(result) ? rawMessages.length : (result.total || 0);
-    const hasMore = Array.isArray(result) ? false : Boolean(result.hasMore);
 
     const toolResultMap = new Map<string, ClaudeToolResult>();
     for (const raw of rawMessages) {
@@ -295,12 +606,31 @@ export class ClaudeSessionsProvider implements IProviderSessions {
       }
     }
 
+    const totalNormalized = normalized.length;
+    let total = 0;
+    for (const msg of normalized) {
+      if (msg.kind !== 'tool_result') {
+        total += 1;
+      }
+    }
+    const normalizedOffset = Math.max(0, offset);
+    const normalizedLimit = limit === null ? null : Math.max(0, limit);
+    const messages = normalizedLimit === null
+      ? normalized
+      : normalized.slice(
+          Math.max(0, totalNormalized - normalizedOffset - normalizedLimit),
+          Math.max(0, totalNormalized - normalizedOffset),
+        );
+    const hasMore = normalizedLimit === null
+      ? false
+      : Math.max(0, totalNormalized - normalizedOffset - normalizedLimit) > 0;
+
     return {
-      messages: normalized,
+      messages,
       total,
       hasMore,
-      offset,
-      limit,
+      offset: normalizedOffset,
+      limit: normalizedLimit,
     };
   }
 }
diff --git a/server/modules/providers/list/claude/claude-skills.provider.ts b/server/modules/providers/list/claude/claude-skills.provider.ts
new file mode 100644
index 00000000..cbb1073a
--- /dev/null
+++ b/server/modules/providers/list/claude/claude-skills.provider.ts
@@ -0,0 +1,257 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { SkillsProvider } from '@/modules/providers/shared/skills/skills.provider.js';
+import { parseFrontMatter } from '@/shared/frontmatter.js';
+import type {
+  ProviderSkill,
+  ProviderSkillListOptions,
+  ProviderSkillSource,
+} from '@/shared/types.js';
+import {
+  findProviderSkillMarkdownFiles,
+  readJsonConfig,
+  readObjectRecord,
+  readOptionalString,
+  readProviderSkillMarkdownDefinition,
+} from '@/shared/utils.js';
+
+const getClaudeHomePath = (): string => path.join(os.homedir(), '.claude');
+
+const getClaudePluginName = (pluginId: string): string | null => {
+  const normalizedPluginId = pluginId.trim();
+  if (!normalizedPluginId || normalizedPluginId === '@') {
+    return null;
+  }
+
+  const [pluginName] = normalizedPluginId.split('@');
+  return readOptionalString(pluginName) ?? null;
+};
+
+const stripMarkdownExtension = (filename: string): string =>
+  filename.replace(/\.md$/i, '');
+
+const pathExistsAsDirectory = async (directoryPath: string): Promise<boolean> => {
+  try {
+    const directoryStats = await stat(directoryPath);
+    return directoryStats.isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+const listChildDirectories = async (directoryPath: string): Promise<string[]> => {
+  try {
+    const entries = await readdir(directoryPath, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => path.join(directoryPath, entry.name))
+      .sort((left, right) => left.localeCompare(right));
+  } catch {
+    return [];
+  }
+};
+
+const readClaudePluginName = async (
+  installPath: string,
+  pluginId: string,
+): Promise<string | null> => {
+  try {
+    const pluginConfig = await readJsonConfig(
+      path.join(installPath, '.claude-plugin', 'plugin.json'),
+    );
+
+    // Older or partial plugin installs may not have plugin.json yet. Falling
+    // back keeps discovery useful without inventing a separate namespace.
+    return readOptionalString(pluginConfig.name) ?? getClaudePluginName(pluginId);
+  } catch {
+    return getClaudePluginName(pluginId);
+  }
+};
+
+export class ClaudeSkillsProvider extends SkillsProvider {
+  constructor() {
+    super('claude');
+  }
+
+  async listSkills(options?: ProviderSkillListOptions): Promise<ProviderSkill[]> {
+    return [
+      ...(await super.listSkills(options)),
+      ...(await this.listPluginSkills(getClaudeHomePath())),
+    ];
+  }
+
+  protected async getSkillSources(workspacePath: string): Promise<ProviderSkillSource[]> {
+    const claudeHomePath = getClaudeHomePath();
+
+    return [
+      {
+        scope: 'user',
+        rootDir: path.join(claudeHomePath, 'skills'),
+        commandPrefix: '/',
+      },
+      {
+        scope: 'project',
+        rootDir: path.join(workspacePath, '.claude', 'skills'),
+        commandPrefix: '/',
+      },
+    ];
+  }
+
+  private async listPluginSkills(claudeHomePath: string): Promise<ProviderSkill[]> {
+    const settings = await readJsonConfig(path.join(claudeHomePath, 'settings.json'));
+    const enabledPlugins = readObjectRecord(settings.enabledPlugins);
+    if (!enabledPlugins) {
+      return [];
+    }
+
+    const installedConfig = await readJsonConfig(
+      path.join(claudeHomePath, 'plugins', 'installed_plugins.json'),
+    );
+    const installedPlugins = readObjectRecord(installedConfig.plugins);
+    if (!installedPlugins) {
+      return [];
+    }
+
+    const skills: ProviderSkill[] = [];
+    const visitedPluginFolders = new Set<string>();
+    const pluginEntries = Object.entries(enabledPlugins)
+      .sort(([left], [right]) => left.localeCompare(right));
+    for (const [pluginId, enabled] of pluginEntries) {
+      if (enabled !== true) {
+        continue;
+      }
+
+      const installs = installedPlugins[pluginId];
+      if (!Array.isArray(installs)) {
+        continue;
+      }
+
+      for (const install of installs) {
+        const installRecord = readObjectRecord(install);
+        const installPath = readOptionalString(installRecord?.installPath);
+        if (!installPath) {
+          continue;
+        }
+
+        // Claude's installed path points at one version folder; the usable
+        // plugin payloads live in the direct child folders beside it.
+        const pluginFolders = await listChildDirectories(path.dirname(installPath));
+        for (const pluginFolder of pluginFolders) {
+          const pluginFolderKey = `${pluginId}:${path.resolve(pluginFolder)}`;
+          if (visitedPluginFolders.has(pluginFolderKey)) {
+            continue;
+          }
+          visitedPluginFolders.add(pluginFolderKey);
+
+          const pluginName = await readClaudePluginName(pluginFolder, pluginId);
+          if (!pluginName) {
+            continue;
+          }
+
+          const commandsPath = path.join(pluginFolder, 'commands');
+          if (await pathExistsAsDirectory(commandsPath)) {
+            skills.push(
+              ...(await this.listPluginCommandSkills(commandsPath, pluginId, pluginName)),
+            );
+            continue;
+          }
+
+          const skillsPath = path.join(pluginFolder, 'skills');
+          if (!(await pathExistsAsDirectory(skillsPath))) {
+            continue;
+          }
+
+          skills.push(
+            ...(await this.listPluginSkillMarkdowns(pluginFolder, pluginId, pluginName)),
+          );
+        }
+      }
+    }
+
+    return skills;
+  }
+
+  private async listPluginCommandSkills(
+    commandsPath: string,
+    pluginId: string,
+    pluginName: string,
+  ): Promise<ProviderSkill[]> {
+    const skills: ProviderSkill[] = [];
+
+    try {
+      const entries = await readdir(commandsPath, { withFileTypes: true });
+      const commandFiles = entries
+        .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith('.md'))
+        .sort((left, right) => left.name.localeCompare(right.name));
+
+      for (const commandFile of commandFiles) {
+        const sourcePath = path.join(commandsPath, commandFile.name);
+        try {
+          const definition = await this.readPluginCommandDefinition(sourcePath);
+          skills.push({
+            provider: this.provider,
+            name: definition.name,
+            description: definition.description,
+            command: `/${pluginName}:${definition.name}`,
+            scope: 'plugin',
+            sourcePath,
+            pluginName,
+            pluginId,
+          });
+        } catch {
+          // Malformed command markdown should not block sibling plugin commands.
+        }
+      }
+    } catch {
+      // Missing or unreadable command folders are treated as empty plugin command sets.
+    }
+
+    return skills;
+  }
+
+  private async readPluginCommandDefinition(
+    commandPath: string,
+  ): Promise<{ name: string; description: string }> {
+    const content = await readFile(commandPath, 'utf8');
+    const parsed = parseFrontMatter(content);
+    const data = readObjectRecord(parsed.data) ?? {};
+
+    return {
+      name: stripMarkdownExtension(path.basename(commandPath)),
+      description: readOptionalString(data.description) ?? '',
+    };
+  }
+
+  private async listPluginSkillMarkdowns(
+    installPath: string,
+    pluginId: string,
+    pluginName: string,
+  ): Promise<ProviderSkill[]> {
+    const skillFiles = await findProviderSkillMarkdownFiles(path.join(installPath, 'skills'), {
+      recursive: true,
+    });
+    const skills: ProviderSkill[] = [];
+
+    for (const skillPath of skillFiles) {
+      try {
+        const definition = await readProviderSkillMarkdownDefinition(skillPath);
+        skills.push({
+          provider: this.provider,
+          name: definition.name,
+          description: definition.description,
+          command: `/${pluginName}:${definition.name}`,
+          scope: 'plugin',
+          sourcePath: skillPath,
+          pluginName,
+          pluginId,
+        });
+      } catch {
+        // A bad plugin skill file should not block other installed plugin skills.
+      }
+    }
+
+    return skills;
+  }
+}
diff --git a/server/modules/providers/list/claude/claude.provider.ts b/server/modules/providers/list/claude/claude.provider.ts
index 675d82dd..33a75210 100644
--- a/server/modules/providers/list/claude/claude.provider.ts
+++ b/server/modules/providers/list/claude/claude.provider.ts
@@ -1,13 +1,25 @@
 import { AbstractProvider } from '@/modules/providers/shared/base/abstract.provider.js';
 import { ClaudeProviderAuth } from '@/modules/providers/list/claude/claude-auth.provider.js';
+import { ClaudeProviderModels } from '@/modules/providers/list/claude/claude-models.provider.js';
 import { ClaudeMcpProvider } from '@/modules/providers/list/claude/claude-mcp.provider.js';
+import { ClaudeSessionSynchronizer } from '@/modules/providers/list/claude/claude-session-synchronizer.provider.js';
 import { ClaudeSessionsProvider } from '@/modules/providers/list/claude/claude-sessions.provider.js';
-import type { IProviderAuth, IProviderSessions } from '@/shared/interfaces.js';
+import { ClaudeSkillsProvider } from '@/modules/providers/list/claude/claude-skills.provider.js';
+import type {
+  IProviderAuth,
+  IProviderModels,
+  IProviderSessionSynchronizer,
+  IProviderSkills,
+  IProviderSessions,
+} from '@/shared/interfaces.js';
 
 export class ClaudeProvider extends AbstractProvider {
+  readonly models: IProviderModels = new ClaudeProviderModels();
   readonly mcp = new ClaudeMcpProvider();
   readonly auth: IProviderAuth = new ClaudeProviderAuth();
+  readonly skills: IProviderSkills = new ClaudeSkillsProvider();
   readonly sessions: IProviderSessions = new ClaudeSessionsProvider();
+  readonly sessionSynchronizer: IProviderSessionSynchronizer = new ClaudeSessionSynchronizer();
 
   constructor() {
     super('claude');
diff --git a/server/modules/providers/list/codex/codex-models.provider.ts b/server/modules/providers/list/codex/codex-models.provider.ts
new file mode 100644
index 00000000..de4de0ea
--- /dev/null
+++ b/server/modules/providers/list/codex/codex-models.provider.ts
@@ -0,0 +1,125 @@
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import TOML from '@iarna/toml';
+
+import type { IProviderModels } from '@/shared/interfaces.js';
+import type {
+  ProviderChangeActiveModelInput,
+  ProviderCurrentActiveModel,
+  ProviderModelOption,
+  ProviderModelsDefinition,
+  ProviderSessionActiveModelChange,
+} from '@/shared/types.js';
+import {
+  buildDefaultProviderCurrentActiveModel,
+  readObjectRecord,
+  readOptionalString,
+  writeProviderSessionActiveModelChange,
+} from '@/shared/utils.js';
+
+export const CODEX_FALLBACK_MODELS: ProviderModelsDefinition = {
+  OPTIONS: [
+    { value: 'gpt-5.5', label: 'gpt-5.5' },
+    { value: 'gpt-5.4', label: 'gpt-5.4' },
+    { value: 'gpt-5.4-mini', label: 'gpt-5.4-mini' },
+    { value: 'gpt-5.3-codex', label: 'gpt-5.3-codex' },
+    { value: 'gpt-5.2', label: 'gpt-5.2' },
+  ],
+  DEFAULT: 'gpt-5.4',
+};
+
+type CodexCachedModel = {
+  slug?: string;
+  display_name?: string;
+  description?: string;
+  priority?: number;
+  visibility?: string;
+  supported_in_api?: boolean;
+};
+
+const CODEX_MODELS_CACHE_PATH = path.join(os.homedir(), '.codex', 'models_cache.json');
+const CODEX_CONFIG_PATH = path.join(os.homedir(), '.codex', 'config.toml');
+
+const isCodexCachedModel = (value: unknown): value is CodexCachedModel => {
+  const record = readObjectRecord(value);
+  return Boolean(record && readOptionalString(record.slug));
+};
+
+const readCodexPriority = (value: unknown): number => (
+  typeof value === 'number' && Number.isFinite(value) ? value : Number.MAX_SAFE_INTEGER
+);
+
+const mapCodexModel = (model: CodexCachedModel): ProviderModelOption => ({
+  value: model.slug as string,
+  label: readOptionalString(model.display_name) ?? (model.slug as string),
+  description: readOptionalString(model.description),
+});
+
+const buildCodexModelsDefinition = (models: CodexCachedModel[]): ProviderModelsDefinition => {
+  const sortedModels = [...models]
+    .filter((model) => model.visibility !== 'hidden' && model.supported_in_api !== false)
+    .sort((left, right) => readCodexPriority(left.priority) - readCodexPriority(right.priority));
+
+  const options: ProviderModelOption[] = [];
+  const seenValues = new Set<string>();
+
+  for (const model of sortedModels) {
+    const mappedModel = mapCodexModel(model);
+    if (seenValues.has(mappedModel.value)) {
+      continue;
+    }
+
+    seenValues.add(mappedModel.value);
+    options.push(mappedModel);
+  }
+
+  if (options.length === 0) {
+    return CODEX_FALLBACK_MODELS;
+  }
+
+  return {
+    OPTIONS: options,
+    DEFAULT: options[0]?.value ?? CODEX_FALLBACK_MODELS.DEFAULT,
+  };
+};
+
+export class CodexProviderModels implements IProviderModels {
+  async getSupportedModels(): Promise<ProviderModelsDefinition> {
+    try {
+      const raw = await readFile(CODEX_MODELS_CACHE_PATH, 'utf8');
+      const parsed = readObjectRecord(JSON.parse(raw));
+      const models = Array.isArray(parsed?.models)
+        ? parsed.models.filter(isCodexCachedModel)
+        : [];
+
+      return buildCodexModelsDefinition(models);
+    } catch {
+      return CODEX_FALLBACK_MODELS;
+    }
+  }
+
+  async getCurrentActiveModel(): Promise<ProviderCurrentActiveModel> {
+    try {
+      const raw = await readFile(CODEX_CONFIG_PATH, 'utf8');
+      const parsed = readObjectRecord(TOML.parse(raw));
+      const model = readOptionalString(parsed?.model);
+      if (!model) {
+        return buildDefaultProviderCurrentActiveModel(await this.getSupportedModels());
+      }
+
+      return {
+        model,
+      };
+    } catch {
+      return buildDefaultProviderCurrentActiveModel(await this.getSupportedModels());
+    }
+  }
+
+  async changeActiveModel(
+    input: ProviderChangeActiveModelInput,
+  ): Promise<ProviderSessionActiveModelChange> {
+    return writeProviderSessionActiveModelChange('codex', input);
+  }
+}
diff --git a/server/modules/providers/list/codex/codex-session-synchronizer.provider.ts b/server/modules/providers/list/codex/codex-session-synchronizer.provider.ts
new file mode 100644
index 00000000..0e8025ef
--- /dev/null
+++ b/server/modules/providers/list/codex/codex-session-synchronizer.provider.ts
@@ -0,0 +1,179 @@
+import os from 'node:os';
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+import { sessionsDb } from '@/modules/database/index.js';
+import {
+  buildLookupMap,
+  extractFirstValidJsonlData,
+  findFilesRecursivelyCreatedAfter,
+  normalizeSessionName,
+  readFileTimestamps,
+} from '@/shared/utils.js';
+import type { IProviderSessionSynchronizer } from '@/shared/interfaces.js';
+
+type ParsedSession = {
+  sessionId: string;
+  projectPath: string;
+  sessionName?: string;
+};
+
+/**
+ * Session indexer for Codex transcript artifacts.
+ */
+export class CodexSessionSynchronizer implements IProviderSessionSynchronizer {
+  private readonly provider = 'codex' as const;
+  private readonly codexHome = path.join(os.homedir(), '.codex');
+
+  /**
+   * Scans ~/.codex/sessions and upserts discovered sessions into DB.
+   */
+  async synchronize(since?: Date): Promise<number> {
+    const nameMap = await buildLookupMap(path.join(this.codexHome, 'session_index.jsonl'), 'id', 'thread_name');
+    const files = await findFilesRecursivelyCreatedAfter(
+      path.join(this.codexHome, 'sessions'),
+      '.jsonl',
+      since ?? null
+    );
+
+    let processed = 0;
+    for (const filePath of files) {
+      const parsed = await this.processSessionFile(filePath, nameMap);
+      if (!parsed) {
+        continue;
+      }
+
+      const existingSession = sessionsDb.getSessionById(parsed.sessionId);
+      if (existingSession) {
+        // If session name is untitled and we now have a name, update it
+        if (existingSession.custom_name === 'Untitled Codex Session' && parsed.sessionName && parsed.sessionName !== 'Untitled Codex Session') {
+          sessionsDb.updateSessionCustomName(parsed.sessionId, parsed.sessionName);
+        }
+      }
+
+      const timestamps = await readFileTimestamps(filePath);
+      sessionsDb.createSession(
+        parsed.sessionId,
+        this.provider,
+        parsed.projectPath,
+        parsed.sessionName,
+        timestamps.createdAt,
+        timestamps.updatedAt,
+        filePath
+      );
+      processed += 1;
+    }
+
+    return processed;
+  }
+
+  /**
+   * Parses and upserts one Codex session JSONL file.
+   */
+  async synchronizeFile(filePath: string): Promise<string | null> {
+    if (!filePath.endsWith('.jsonl')) {
+      return null;
+    }
+
+    const nameMap = await buildLookupMap(path.join(this.codexHome, 'session_index.jsonl'), 'id', 'thread_name');
+    const parsed = await this.processSessionFile(filePath, nameMap);
+    if (!parsed) {
+      return null;
+    }
+
+    const timestamps = await readFileTimestamps(filePath);
+    return sessionsDb.createSession(
+      parsed.sessionId,
+      this.provider,
+      parsed.projectPath,
+      parsed.sessionName,
+      timestamps.createdAt,
+      timestamps.updatedAt,
+      filePath
+    );
+  }
+
+  /**
+   * Extracts session metadata from one Codex JSONL session file.
+   */
+  private async processSessionFile(
+    filePath: string,
+    nameMap: Map<string, string>
+  ): Promise<ParsedSession | null> {
+    const parsed = await extractFirstValidJsonlData(filePath, (rawData) => {
+      const data = rawData as Record<string, unknown>;
+      const payload = data.payload as Record<string, unknown> | undefined;
+      const sessionId = typeof payload?.id === 'string' ? payload.id : undefined;
+      const projectPath = typeof payload?.cwd === 'string' ? payload.cwd : undefined;
+
+      if (!sessionId || !projectPath) {
+        return null;
+      }
+
+      return {
+        sessionId,
+        projectPath,
+      };
+    });
+
+    if (!parsed) {
+      return null;
+    }
+
+    const existingSession = sessionsDb.getSessionById(parsed.sessionId);
+    const existingSessionName = existingSession?.custom_name;
+    if (existingSessionName && existingSessionName !== 'Untitled Codex Session') {
+      return {
+        ...parsed,
+        sessionName: normalizeSessionName(existingSessionName, 'Untitled Codex Session'),
+      };
+    }
+
+    let sessionName = nameMap.get(parsed.sessionId);
+    if (!sessionName) {
+      sessionName = await this.extractLastAgentMessageFromEnd(filePath);
+    }
+
+    return {
+      ...parsed,
+      sessionName: normalizeSessionName(sessionName, 'Untitled Codex Session'),
+    };
+  }
+
+  private async extractLastAgentMessageFromEnd(filePath: string): Promise<string | undefined> {
+    try {
+      const content = await readFile(filePath, 'utf8');
+      const lines = content.split(/\r?\n/);
+
+      for (let index = lines.length - 1; index >= 0; index -= 1) {
+        const line = lines[index]?.trim();
+        if (!line) {
+          continue;
+        }
+
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(line);
+        } catch {
+          continue;
+        }
+
+        const data = parsed as Record<string, unknown>;
+        const eventType = typeof data.type === 'string' ? data.type : undefined;
+        const payload = data.payload as Record<string, unknown> | undefined;
+        const payloadType = typeof payload?.type === 'string' ? payload.type : undefined;
+        const lastAgentMessage = typeof payload?.last_agent_message === 'string'
+          ? payload.last_agent_message
+          : undefined;
+
+        if (eventType === 'event_msg' && payloadType === 'task_complete' && lastAgentMessage?.trim()) {
+          return lastAgentMessage;
+        }
+      }
+    } catch {
+      // Ignore missing/unreadable files so sync can continue.
+    }
+
+    return undefined;
+  }
+}
diff --git a/server/modules/providers/list/codex/codex-sessions.provider.ts b/server/modules/providers/list/codex/codex-sessions.provider.ts
index 1ea986f7..5cad1334 100644
--- a/server/modules/providers/list/codex/codex-sessions.provider.ts
+++ b/server/modules/providers/list/codex/codex-sessions.provider.ts
@@ -1,4 +1,7 @@
-import { getCodexSessionMessages } from '@/projects.js';
+import fsSync from 'node:fs';
+import readline from 'node:readline';
+
+import { sessionsDb } from '@/modules/database/index.js';
 import type { IProviderSessions } from '@/shared/interfaces.js';
 import type { AnyRecord, FetchHistoryOptions, FetchHistoryResult, NormalizedMessage } from '@/shared/types.js';
 import { createNormalizedMessage, generateMessageId, readObjectRecord } from '@/shared/utils.js';
@@ -11,14 +14,250 @@ type CodexHistoryResult =
       messages?: AnyRecord[];
       total?: number;
       hasMore?: boolean;
+      offset?: number;
+      limit?: number | null;
       tokenUsage?: unknown;
     };
 
-const loadCodexSessionMessages = getCodexSessionMessages as unknown as (
+function isVisibleCodexUserMessage(payload: AnyRecord | null | undefined): boolean {
+  if (!payload || payload.type !== 'user_message') {
+    return false;
+  }
+
+  if (payload.kind && payload.kind !== 'plain') {
+    return false;
+  }
+
+  return typeof payload.message === 'string' && payload.message.trim().length > 0;
+}
+
+function extractCodexTextContent(content: unknown): string {
+  if (!Array.isArray(content)) {
+    return typeof content === 'string' ? content : '';
+  }
+
+  return content
+    .map((item) => {
+      if (!item || typeof item !== 'object') {
+        return '';
+      }
+
+      const record = item as AnyRecord;
+      if (
+        (record.type === 'input_text' || record.type === 'output_text' || record.type === 'text')
+        && typeof record.text === 'string'
+      ) {
+        return record.text;
+      }
+
+      return '';
+    })
+    .filter(Boolean)
+    .join('\n');
+}
+
+async function getCodexSessionMessages(
   sessionId: string,
-  limit: number | null,
-  offset: number,
-) => Promise<CodexHistoryResult>;
+  limit: number | null = null,
+  offset = 0,
+): Promise<CodexHistoryResult> {
+  try {
+    const sessionFilePath = sessionsDb.getSessionById(sessionId)?.jsonl_path;
+
+    if (!sessionFilePath) {
+      console.warn(`Codex session file not found for session ${sessionId}`);
+      return { messages: [], total: 0, hasMore: false };
+    }
+
+    const messages: AnyRecord[] = [];
+    let tokenUsage: AnyRecord | null = null;
+    const fileStream = fsSync.createReadStream(sessionFilePath);
+    const rl = readline.createInterface({
+      input: fileStream,
+      crlfDelay: Infinity,
+    });
+
+    for await (const line of rl) {
+      if (!line.trim()) {
+        continue;
+      }
+
+      try {
+        const entry = JSON.parse(line) as AnyRecord;
+
+        if (entry.type === 'event_msg' && entry.payload?.type === 'token_count' && entry.payload?.info) {
+          const info = entry.payload.info as AnyRecord;
+          if (info.total_token_usage) {
+            const usage = info.total_token_usage as AnyRecord;
+            tokenUsage = {
+              used: usage.total_tokens || 0,
+              total: info.model_context_window || 200000,
+            };
+          }
+        }
+
+        if (entry.type === 'event_msg' && isVisibleCodexUserMessage(entry.payload as AnyRecord)) {
+          messages.push({
+            type: 'user',
+            timestamp: entry.timestamp,
+            message: {
+              role: 'user',
+              content: entry.payload.message,
+            },
+          });
+        }
+
+        if (
+          entry.type === 'response_item' &&
+          entry.payload?.type === 'message' &&
+          entry.payload.role === 'assistant'
+        ) {
+          const textContent = extractCodexTextContent(entry.payload.content);
+          if (textContent.trim()) {
+            messages.push({
+              type: 'assistant',
+              timestamp: entry.timestamp,
+              message: {
+                role: 'assistant',
+                content: textContent,
+              },
+            });
+          }
+        }
+
+        if (entry.type === 'response_item' && entry.payload?.type === 'reasoning') {
+          const summaryText = Array.isArray(entry.payload.summary)
+            ? entry.payload.summary
+                .map((item: AnyRecord) => item?.text)
+                .filter(Boolean)
+                .join('\n')
+            : '';
+
+          if (summaryText.trim()) {
+            messages.push({
+              type: 'thinking',
+              timestamp: entry.timestamp,
+              message: {
+                role: 'assistant',
+                content: summaryText,
+              },
+            });
+          }
+        }
+
+        if (entry.type === 'response_item' && entry.payload?.type === 'function_call') {
+          let toolName = entry.payload.name;
+          let toolInput = entry.payload.arguments;
+
+          if (toolName === 'shell_command') {
+            toolName = 'Bash';
+            try {
+              const args = JSON.parse(entry.payload.arguments) as AnyRecord;
+              toolInput = JSON.stringify({ command: args.command });
+            } catch {
+              // Keep original arguments when parsing fails.
+            }
+          }
+
+          messages.push({
+            type: 'tool_use',
+            timestamp: entry.timestamp,
+            toolName,
+            toolInput,
+            toolCallId: entry.payload.call_id,
+          });
+        }
+
+        if (entry.type === 'response_item' && entry.payload?.type === 'function_call_output') {
+          messages.push({
+            type: 'tool_result',
+            timestamp: entry.timestamp,
+            toolCallId: entry.payload.call_id,
+            output: entry.payload.output,
+          });
+        }
+
+        if (entry.type === 'response_item' && entry.payload?.type === 'custom_tool_call') {
+          const toolName = entry.payload.name || 'custom_tool';
+          const input = entry.payload.input || '';
+
+          if (toolName === 'apply_patch') {
+            const fileMatch = String(input).match(/\*\*\* Update File: (.+)/);
+            const filePath = fileMatch ? fileMatch[1].trim() : 'unknown';
+            const lines = String(input).split('\n');
+            const oldLines: string[] = [];
+            const newLines: string[] = [];
+
+            for (const lineContent of lines) {
+              if (lineContent.startsWith('-') && !lineContent.startsWith('---')) {
+                oldLines.push(lineContent.slice(1));
+              } else if (lineContent.startsWith('+') && !lineContent.startsWith('+++')) {
+                newLines.push(lineContent.slice(1));
+              }
+            }
+
+            messages.push({
+              type: 'tool_use',
+              timestamp: entry.timestamp,
+              toolName: 'Edit',
+              toolInput: JSON.stringify({
+                file_path: filePath,
+                old_string: oldLines.join('\n'),
+                new_string: newLines.join('\n'),
+              }),
+              toolCallId: entry.payload.call_id,
+            });
+          } else {
+            messages.push({
+              type: 'tool_use',
+              timestamp: entry.timestamp,
+              toolName,
+              toolInput: input,
+              toolCallId: entry.payload.call_id,
+            });
+          }
+        }
+
+        if (entry.type === 'response_item' && entry.payload?.type === 'custom_tool_call_output') {
+          messages.push({
+            type: 'tool_result',
+            timestamp: entry.timestamp,
+            toolCallId: entry.payload.call_id,
+            output: entry.payload.output || '',
+          });
+        }
+      } catch {
+        // Skip malformed lines.
+      }
+    }
+
+    messages.sort(
+      (a, b) => new Date(a.timestamp || 0).getTime() - new Date(b.timestamp || 0).getTime(),
+    );
+    const total = messages.length;
+
+    if (limit !== null) {
+      const startIndex = Math.max(0, total - offset - limit);
+      const endIndex = total - offset;
+      const paginatedMessages = messages.slice(startIndex, endIndex);
+      const hasMore = startIndex > 0;
+
+      return {
+        messages: paginatedMessages,
+        total,
+        hasMore,
+        offset,
+        limit,
+        tokenUsage,
+      };
+    }
+
+    return { messages, tokenUsage };
+  } catch (error) {
+    console.error(`Error reading Codex session messages for ${sessionId}:`, error);
+    return { messages: [], total: 0, hasMore: false };
+  }
+}
 
 export class CodexSessionsProvider implements IProviderSessions {
   /**
@@ -31,6 +270,23 @@ export class CodexSessionsProvider implements IProviderSessions {
     const ts = raw.timestamp || new Date().toISOString();
     const baseId = raw.uuid || generateMessageId('codex');
 
+    if (raw.type === 'thinking' || raw.isReasoning) {
+      const thinkingContent = typeof raw.message?.content === 'string'
+        ? raw.message.content
+        : '';
+      if (!thinkingContent.trim()) {
+        return [];
+      }
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId,
+        timestamp: ts,
+        provider: PROVIDER,
+        kind: 'thinking',
+        content: thinkingContent,
+      })];
+    }
+
     if (raw.message?.role === 'user') {
       const content = typeof raw.message.content === 'string'
         ? raw.message.content
@@ -77,17 +333,6 @@ export class CodexSessionsProvider implements IProviderSessions {
       })];
     }
 
-    if (raw.type === 'thinking' || raw.isReasoning) {
-      return [createNormalizedMessage({
-        id: baseId,
-        sessionId,
-        timestamp: ts,
-        provider: PROVIDER,
-        kind: 'thinking',
-        content: raw.message?.content || '',
-      })];
-    }
-
     if (raw.type === 'tool_use' || raw.toolName) {
       return [createNormalizedMessage({
         id: baseId,
@@ -275,7 +520,9 @@ export class CodexSessionsProvider implements IProviderSessions {
 
     let result: CodexHistoryResult;
     try {
-      result = await loadCodexSessionMessages(sessionId, limit, offset);
+      // Load full history first so `total` reflects frontend-normalized messages,
+      // not raw JSONL records.
+      result = await getCodexSessionMessages(sessionId, null, 0);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       console.warn(`[CodexProvider] Failed to load session ${sessionId}:`, message);
@@ -283,8 +530,6 @@ export class CodexSessionsProvider implements IProviderSessions {
     }
 
     const rawMessages = Array.isArray(result) ? result : (result.messages || []);
-    const total = Array.isArray(result) ? rawMessages.length : (result.total || 0);
-    const hasMore = Array.isArray(result) ? false : Boolean(result.hasMore);
     const tokenUsage = Array.isArray(result) ? undefined : result.tokenUsage;
 
     const normalized: NormalizedMessage[] = [];
@@ -307,12 +552,31 @@ export class CodexSessionsProvider implements IProviderSessions {
       }
     }
 
+    const totalNormalized = normalized.length;
+    let total = 0;
+    for (const msg of normalized) {
+      if (msg.kind !== 'tool_result') {
+        total += 1;
+      }
+    }
+    const normalizedOffset = Math.max(0, offset);
+    const normalizedLimit = limit === null ? null : Math.max(0, limit);
+    const messages = normalizedLimit === null
+      ? normalized
+      : normalized.slice(
+          Math.max(0, totalNormalized - normalizedOffset - normalizedLimit),
+          Math.max(0, totalNormalized - normalizedOffset),
+        );
+    const hasMore = normalizedLimit === null
+      ? false
+      : Math.max(0, totalNormalized - normalizedOffset - normalizedLimit) > 0;
+
     return {
-      messages: normalized,
+      messages,
       total,
       hasMore,
-      offset,
-      limit,
+      offset: normalizedOffset,
+      limit: normalizedLimit,
       tokenUsage,
     };
   }
diff --git a/server/modules/providers/list/codex/codex-skills.provider.ts b/server/modules/providers/list/codex/codex-skills.provider.ts
new file mode 100644
index 00000000..fe61af51
--- /dev/null
+++ b/server/modules/providers/list/codex/codex-skills.provider.ts
@@ -0,0 +1,60 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import { SkillsProvider } from '@/modules/providers/shared/skills/skills.provider.js';
+import type { ProviderSkillSource } from '@/shared/types.js';
+import {
+  addUniqueProviderSkillSource,
+  findTopmostGitRoot,
+} from '@/shared/utils.js';
+
+export class CodexSkillsProvider extends SkillsProvider {
+  constructor() {
+    super('codex');
+  }
+
+  protected async getSkillSources(workspacePath: string): Promise<ProviderSkillSource[]> {
+    const sources: ProviderSkillSource[] = [];
+    const seenRootDirs = new Set<string>();
+    const repoRoot = await findTopmostGitRoot(workspacePath);
+
+    addUniqueProviderSkillSource(sources, seenRootDirs, {
+      scope: 'repo',
+      rootDir: path.join(workspacePath, '.agents', 'skills'),
+      commandPrefix: '$',
+    });
+
+    if (repoRoot) {
+      // Codex checks repository skills at the launch folder, one folder above it,
+      // and the topmost git root; these can collapse to the same directory.
+      addUniqueProviderSkillSource(sources, seenRootDirs, {
+        scope: 'repo',
+        rootDir: path.join(path.dirname(workspacePath), '.agents', 'skills'),
+        commandPrefix: '$',
+      });
+      addUniqueProviderSkillSource(sources, seenRootDirs, {
+        scope: 'repo',
+        rootDir: path.join(repoRoot, '.agents', 'skills'),
+        commandPrefix: '$',
+      });
+    }
+
+    addUniqueProviderSkillSource(sources, seenRootDirs, {
+      scope: 'user',
+      rootDir: path.join(os.homedir(), '.agents', 'skills'),
+      commandPrefix: '$',
+    });
+    addUniqueProviderSkillSource(sources, seenRootDirs, {
+      scope: 'admin',
+      rootDir: path.join('/etc', 'codex', 'skills'),
+      commandPrefix: '$',
+    });
+    addUniqueProviderSkillSource(sources, seenRootDirs, {
+      scope: 'system',
+      rootDir: path.join(os.homedir(), '.codex', 'skills', '.system'),
+      commandPrefix: '$',
+    });
+
+    return sources;
+  }
+}
diff --git a/server/modules/providers/list/codex/codex.provider.ts b/server/modules/providers/list/codex/codex.provider.ts
index fe1b9eb5..25fc6bad 100644
--- a/server/modules/providers/list/codex/codex.provider.ts
+++ b/server/modules/providers/list/codex/codex.provider.ts
@@ -1,13 +1,25 @@
 import { AbstractProvider } from '@/modules/providers/shared/base/abstract.provider.js';
 import { CodexProviderAuth } from '@/modules/providers/list/codex/codex-auth.provider.js';
+import { CodexProviderModels } from '@/modules/providers/list/codex/codex-models.provider.js';
 import { CodexMcpProvider } from '@/modules/providers/list/codex/codex-mcp.provider.js';
+import { CodexSessionSynchronizer } from '@/modules/providers/list/codex/codex-session-synchronizer.provider.js';
 import { CodexSessionsProvider } from '@/modules/providers/list/codex/codex-sessions.provider.js';
-import type { IProviderAuth, IProviderSessions } from '@/shared/interfaces.js';
+import { CodexSkillsProvider } from '@/modules/providers/list/codex/codex-skills.provider.js';
+import type {
+  IProviderAuth,
+  IProviderModels,
+  IProviderSessionSynchronizer,
+  IProviderSkills,
+  IProviderSessions,
+} from '@/shared/interfaces.js';
 
 export class CodexProvider extends AbstractProvider {
+  readonly models: IProviderModels = new CodexProviderModels();
   readonly mcp = new CodexMcpProvider();
   readonly auth: IProviderAuth = new CodexProviderAuth();
+  readonly skills: IProviderSkills = new CodexSkillsProvider();
   readonly sessions: IProviderSessions = new CodexSessionsProvider();
+  readonly sessionSynchronizer: IProviderSessionSynchronizer = new CodexSessionSynchronizer();
 
   constructor() {
     super('codex');
diff --git a/server/modules/providers/list/cursor/cursor-models.provider.ts b/server/modules/providers/list/cursor/cursor-models.provider.ts
new file mode 100644
index 00000000..da8daaed
--- /dev/null
+++ b/server/modules/providers/list/cursor/cursor-models.provider.ts
@@ -0,0 +1,820 @@
+import { access, readdir } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+import crossSpawn from 'cross-spawn';
+
+import type { IProviderModels } from '@/shared/interfaces.js';
+import type {
+  ProviderChangeActiveModelInput,
+  ProviderCurrentActiveModel,
+  ProviderModelOption,
+  ProviderModelsDefinition,
+  ProviderSessionActiveModelChange,
+} from '@/shared/types.js';
+import {
+  buildDefaultProviderCurrentActiveModel,
+  sanitizeLeafDirectoryName,
+  writeProviderSessionActiveModelChange,
+} from '@/shared/utils.js';
+
+export const CURSOR_FALLBACK_MODELS: ProviderModelsDefinition = {
+  OPTIONS: [
+    {
+      value: "auto",
+      label: "auto",
+      description: "Auto",
+    },
+    {
+      value: "composer-2-fast",
+      label: "composer-2-fast",
+      description: "Composer 2 Fast",
+    },
+    {
+      value: "composer-2",
+      label: "composer-2",
+      description: "Composer 2",
+    },
+    {
+      value: "gpt-5.3-codex-low",
+      label: "gpt-5.3-codex-low",
+      description: "Codex 5.3 Low",
+    },
+    {
+      value: "gpt-5.3-codex-low-fast",
+      label: "gpt-5.3-codex-low-fast",
+      description: "Codex 5.3 Low Fast",
+    },
+    {
+      value: "gpt-5.3-codex",
+      label: "gpt-5.3-codex",
+      description: "Codex 5.3",
+    },
+    {
+      value: "gpt-5.3-codex-fast",
+      label: "gpt-5.3-codex-fast",
+      description: "Codex 5.3 Fast",
+    },
+    {
+      value: "gpt-5.3-codex-high",
+      label: "gpt-5.3-codex-high",
+      description: "Codex 5.3 High",
+    },
+    {
+      value: "gpt-5.3-codex-high-fast",
+      label: "gpt-5.3-codex-high-fast",
+      description: "Codex 5.3 High Fast",
+    },
+    {
+      value: "gpt-5.3-codex-xhigh",
+      label: "gpt-5.3-codex-xhigh",
+      description: "Codex 5.3 Extra High",
+    },
+    {
+      value: "gpt-5.3-codex-xhigh-fast",
+      label: "gpt-5.3-codex-xhigh-fast",
+      description: "Codex 5.3 Extra High Fast",
+    },
+    {
+      value: "gpt-5.2",
+      label: "gpt-5.2",
+      description: "GPT-5.2",
+    },
+    {
+      value: "gpt-5.2-codex-low",
+      label: "gpt-5.2-codex-low",
+      description: "Codex 5.2 Low",
+    },
+    {
+      value: "gpt-5.2-codex-low-fast",
+      label: "gpt-5.2-codex-low-fast",
+      description: "Codex 5.2 Low Fast",
+    },
+    {
+      value: "gpt-5.2-codex",
+      label: "gpt-5.2-codex",
+      description: "Codex 5.2",
+    },
+    {
+      value: "gpt-5.2-codex-fast",
+      label: "gpt-5.2-codex-fast",
+      description: "Codex 5.2 Fast",
+    },
+    {
+      value: "gpt-5.2-codex-high",
+      label: "gpt-5.2-codex-high",
+      description: "Codex 5.2 High",
+    },
+    {
+      value: "gpt-5.2-codex-high-fast",
+      label: "gpt-5.2-codex-high-fast",
+      description: "Codex 5.2 High Fast",
+    },
+    {
+      value: "gpt-5.2-codex-xhigh",
+      label: "gpt-5.2-codex-xhigh",
+      description: "Codex 5.2 Extra High",
+    },
+    {
+      value: "gpt-5.2-codex-xhigh-fast",
+      label: "gpt-5.2-codex-xhigh-fast",
+      description: "Codex 5.2 Extra High Fast",
+    },
+    {
+      value: "gpt-5.1-codex-max-low",
+      label: "gpt-5.1-codex-max-low",
+      description: "Codex 5.1 Max Low",
+    },
+    {
+      value: "gpt-5.1-codex-max-low-fast",
+      label: "gpt-5.1-codex-max-low-fast",
+      description: "Codex 5.1 Max Low Fast",
+    },
+    {
+      value: "gpt-5.1-codex-max-medium",
+      label: "gpt-5.1-codex-max-medium",
+      description: "Codex 5.1 Max",
+    },
+    {
+      value: "gpt-5.1-codex-max-medium-fast",
+      label: "gpt-5.1-codex-max-medium-fast",
+      description: "Codex 5.1 Max Medium Fast",
+    },
+    {
+      value: "gpt-5.1-codex-max-high",
+      label: "gpt-5.1-codex-max-high",
+      description: "Codex 5.1 Max High",
+    },
+    {
+      value: "gpt-5.1-codex-max-high-fast",
+      label: "gpt-5.1-codex-max-high-fast",
+      description: "Codex 5.1 Max High Fast",
+    },
+    {
+      value: "gpt-5.1-codex-max-xhigh",
+      label: "gpt-5.1-codex-max-xhigh",
+      description: "Codex 5.1 Max Extra High",
+    },
+    {
+      value: "gpt-5.1-codex-max-xhigh-fast",
+      label: "gpt-5.1-codex-max-xhigh-fast",
+      description: "Codex 5.1 Max Extra High Fast",
+    },
+    {
+      value: "composer-2.5",
+      label: "composer-2.5",
+      description: "Composer 2.5",
+    },
+    {
+      value: "gpt-5.5-high",
+      label: "gpt-5.5-high",
+      description: "GPT-5.5 1M High",
+    },
+    {
+      value: "gpt-5.5-high-fast",
+      label: "gpt-5.5-high-fast",
+      description: "GPT-5.5 High Fast",
+    },
+    {
+      value: "claude-opus-4-7-thinking-high",
+      label: "claude-opus-4-7-thinking-high",
+      description: "Opus 4.7 1M High Thinking",
+    },
+    {
+      value: "gpt-5.4-high",
+      label: "gpt-5.4-high",
+      description: "GPT-5.4 1M High",
+    },
+    {
+      value: "gpt-5.4-high-fast",
+      label: "gpt-5.4-high-fast",
+      description: "GPT-5.4 High Fast",
+    },
+    {
+      value: "claude-4.6-opus-high-thinking",
+      label: "claude-4.6-opus-high-thinking",
+      description: "Opus 4.6 1M Thinking",
+    },
+    {
+      value: "claude-4.6-opus-high-thinking-fast",
+      label: "claude-4.6-opus-high-thinking-fast",
+      description: "Opus 4.6 1M Thinking Fast",
+    },
+    {
+      value: "composer-2.5-fast",
+      label: "composer-2.5-fast",
+      description: "Composer 2.5 Fast",
+    },
+    {
+      value: "gpt-5.5-none",
+      label: "gpt-5.5-none",
+      description: "GPT-5.5 1M None",
+    },
+    {
+      value: "gpt-5.5-none-fast",
+      label: "gpt-5.5-none-fast",
+      description: "GPT-5.5 None Fast",
+    },
+    {
+      value: "gpt-5.5-low",
+      label: "gpt-5.5-low",
+      description: "GPT-5.5 1M Low",
+    },
+    {
+      value: "gpt-5.5-low-fast",
+      label: "gpt-5.5-low-fast",
+      description: "GPT-5.5 Low Fast",
+    },
+    {
+      value: "gpt-5.5-medium",
+      label: "gpt-5.5-medium",
+      description: "GPT-5.5 1M",
+    },
+    {
+      value: "gpt-5.5-medium-fast",
+      label: "gpt-5.5-medium-fast",
+      description: "GPT-5.5 Fast",
+    },
+    {
+      value: "gpt-5.5-extra-high",
+      label: "gpt-5.5-extra-high",
+      description: "GPT-5.5 1M Extra High",
+    },
+    {
+      value: "gpt-5.5-extra-high-fast",
+      label: "gpt-5.5-extra-high-fast",
+      description: "GPT-5.5 Extra High Fast",
+    },
+    {
+      value: "claude-4.6-sonnet-medium",
+      label: "claude-4.6-sonnet-medium",
+      description: "Sonnet 4.6 1M",
+    },
+    {
+      value: "claude-4.6-sonnet-medium-thinking",
+      label: "claude-4.6-sonnet-medium-thinking",
+      description: "Sonnet 4.6 1M Thinking",
+    },
+    {
+      value: "claude-opus-4-7-low",
+      label: "claude-opus-4-7-low",
+      description: "Opus 4.7 1M Low",
+    },
+    {
+      value: "claude-opus-4-7-low-fast",
+      label: "claude-opus-4-7-low-fast",
+      description: "Opus 4.7 1M Low Fast",
+    },
+    {
+      value: "claude-opus-4-7-medium",
+      label: "claude-opus-4-7-medium",
+      description: "Opus 4.7 1M Medium",
+    },
+    {
+      value: "claude-opus-4-7-medium-fast",
+      label: "claude-opus-4-7-medium-fast",
+      description: "Opus 4.7 1M Medium Fast",
+    },
+    {
+      value: "claude-opus-4-7-high",
+      label: "claude-opus-4-7-high",
+      description: "Opus 4.7 1M High",
+    },
+    {
+      value: "claude-opus-4-7-high-fast",
+      label: "claude-opus-4-7-high-fast",
+      description: "Opus 4.7 1M High Fast",
+    },
+    {
+      value: "claude-opus-4-7-xhigh",
+      label: "claude-opus-4-7-xhigh",
+      description: "Opus 4.7 1M",
+    },
+    {
+      value: "claude-opus-4-7-xhigh-fast",
+      label: "claude-opus-4-7-xhigh-fast",
+      description: "Opus 4.7 1M Fast",
+    },
+    {
+      value: "claude-opus-4-7-max",
+      label: "claude-opus-4-7-max",
+      description: "Opus 4.7 1M Max",
+    },
+    {
+      value: "claude-opus-4-7-max-fast",
+      label: "claude-opus-4-7-max-fast",
+      description: "Opus 4.7 1M Max Fast",
+    },
+    {
+      value: "claude-opus-4-7-thinking-low",
+      label: "claude-opus-4-7-thinking-low",
+      description: "Opus 4.7 1M Low Thinking",
+    },
+    {
+      value: "claude-opus-4-7-thinking-low-fast",
+      label: "claude-opus-4-7-thinking-low-fast",
+      description: "Opus 4.7 1M Low Thinking Fast",
+    },
+    {
+      value: "claude-opus-4-7-thinking-medium",
+      label: "claude-opus-4-7-thinking-medium",
+      description: "Opus 4.7 1M Medium Thinking",
+    },
+    {
+      value: "claude-opus-4-7-thinking-medium-fast",
+      label: "claude-opus-4-7-thinking-medium-fast",
+      description: "Opus 4.7 1M Medium Thinking Fast",
+    },
+    {
+      value: "claude-opus-4-7-thinking-high-fast",
+      label: "claude-opus-4-7-thinking-high-fast",
+      description: "Opus 4.7 1M High Thinking Fast",
+    },
+    {
+      value: "claude-opus-4-7-thinking-xhigh",
+      label: "claude-opus-4-7-thinking-xhigh",
+      description: "Opus 4.7 1M Thinking",
+    },
+    {
+      value: "claude-opus-4-7-thinking-xhigh-fast",
+      label: "claude-opus-4-7-thinking-xhigh-fast",
+      description: "Opus 4.7 1M Thinking Fast",
+    },
+    {
+      value: "claude-opus-4-7-thinking-max",
+      label: "claude-opus-4-7-thinking-max",
+      description: "Opus 4.7 1M Max Thinking",
+    },
+    {
+      value: "claude-opus-4-7-thinking-max-fast",
+      label: "claude-opus-4-7-thinking-max-fast",
+      description: "Opus 4.7 1M Max Thinking Fast",
+    },
+    {
+      value: "grok-build-0.1",
+      label: "grok-build-0.1",
+      description: "Grok Build 0.1 1M",
+    },
+    {
+      value: "gpt-5.4-low",
+      label: "gpt-5.4-low",
+      description: "GPT-5.4 1M Low",
+    },
+    {
+      value: "gpt-5.4-medium",
+      label: "gpt-5.4-medium",
+      description: "GPT-5.4 1M",
+    },
+    {
+      value: "gpt-5.4-medium-fast",
+      label: "gpt-5.4-medium-fast",
+      description: "GPT-5.4 Fast",
+    },
+    {
+      value: "gpt-5.4-xhigh",
+      label: "gpt-5.4-xhigh",
+      description: "GPT-5.4 1M Extra High",
+    },
+    {
+      value: "gpt-5.4-xhigh-fast",
+      label: "gpt-5.4-xhigh-fast",
+      description: "GPT-5.4 Extra High Fast",
+    },
+    {
+      value: "claude-4.6-opus-high",
+      label: "claude-4.6-opus-high",
+      description: "Opus 4.6 1M",
+    },
+    {
+      value: "claude-4.6-opus-max",
+      label: "claude-4.6-opus-max",
+      description: "Opus 4.6 1M Max",
+    },
+    {
+      value: "claude-4.6-opus-max-thinking",
+      label: "claude-4.6-opus-max-thinking",
+      description: "Opus 4.6 1M Max Thinking",
+    },
+    {
+      value: "claude-4.6-opus-max-thinking-fast",
+      label: "claude-4.6-opus-max-thinking-fast",
+      description: "Opus 4.6 1M Max Thinking Fast",
+    },
+    {
+      value: "claude-4.5-opus-high",
+      label: "claude-4.5-opus-high",
+      description: "Opus 4.5",
+    },
+    {
+      value: "claude-4.5-opus-high-thinking",
+      label: "claude-4.5-opus-high-thinking",
+      description: "Opus 4.5 Thinking",
+    },
+    {
+      value: "gpt-5.2-low",
+      label: "gpt-5.2-low",
+      description: "GPT-5.2 Low",
+    },
+    {
+      value: "gpt-5.2-low-fast",
+      label: "gpt-5.2-low-fast",
+      description: "GPT-5.2 Low Fast",
+    },
+    {
+      value: "gpt-5.2-fast",
+      label: "gpt-5.2-fast",
+      description: "GPT-5.2 Fast",
+    },
+    {
+      value: "gpt-5.2-high",
+      label: "gpt-5.2-high",
+      description: "GPT-5.2 High",
+    },
+    {
+      value: "gpt-5.2-high-fast",
+      label: "gpt-5.2-high-fast",
+      description: "GPT-5.2 High Fast",
+    },
+    {
+      value: "gpt-5.2-xhigh",
+      label: "gpt-5.2-xhigh",
+      description: "GPT-5.2 Extra High",
+    },
+    {
+      value: "gpt-5.2-xhigh-fast",
+      label: "gpt-5.2-xhigh-fast",
+      description: "GPT-5.2 Extra High Fast",
+    },
+    {
+      value: "gemini-3.1-pro",
+      label: "gemini-3.1-pro",
+      description: "Gemini 3.1 Pro",
+    },
+    {
+      value: "gpt-5.4-mini-none",
+      label: "gpt-5.4-mini-none",
+      description: "GPT-5.4 Mini None",
+    },
+    {
+      value: "gpt-5.4-mini-low",
+      label: "gpt-5.4-mini-low",
+      description: "GPT-5.4 Mini Low",
+    },
+    {
+      value: "gpt-5.4-mini-medium",
+      label: "gpt-5.4-mini-medium",
+      description: "GPT-5.4 Mini",
+    },
+    {
+      value: "gpt-5.4-mini-high",
+      label: "gpt-5.4-mini-high",
+      description: "GPT-5.4 Mini High",
+    },
+    {
+      value: "gpt-5.4-mini-xhigh",
+      label: "gpt-5.4-mini-xhigh",
+      description: "GPT-5.4 Mini Extra High",
+    },
+    {
+      value: "gpt-5.4-nano-none",
+      label: "gpt-5.4-nano-none",
+      description: "GPT-5.4 Nano None",
+    },
+    {
+      value: "gpt-5.4-nano-low",
+      label: "gpt-5.4-nano-low",
+      description: "GPT-5.4 Nano Low",
+    },
+    {
+      value: "gpt-5.4-nano-medium",
+      label: "gpt-5.4-nano-medium",
+      description: "GPT-5.4 Nano",
+    },
+    {
+      value: "gpt-5.4-nano-high",
+      label: "gpt-5.4-nano-high",
+      description: "GPT-5.4 Nano High",
+    },
+    {
+      value: "gpt-5.4-nano-xhigh",
+      label: "gpt-5.4-nano-xhigh",
+      description: "GPT-5.4 Nano Extra High",
+    },
+    {
+      value: "grok-4.3",
+      label: "grok-4.3",
+      description: "Grok 4.3 1M",
+    },
+    {
+      value: "claude-4.5-sonnet",
+      label: "claude-4.5-sonnet",
+      description: "Sonnet 4.5",
+    },
+    {
+      value: "claude-4.5-sonnet-thinking",
+      label: "claude-4.5-sonnet-thinking",
+      description: "Sonnet 4.5 Thinking",
+    },
+    {
+      value: "gpt-5.1-low",
+      label: "gpt-5.1-low",
+      description: "GPT-5.1 Low",
+    },
+    {
+      value: "gpt-5.1",
+      label: "gpt-5.1",
+      description: "GPT-5.1",
+    },
+    {
+      value: "gpt-5.1-high",
+      label: "gpt-5.1-high",
+      description: "GPT-5.1 High",
+    },
+    {
+      value: "gemini-3-flash",
+      label: "gemini-3-flash",
+      description: "Gemini 3 Flash",
+    },
+    {
+      value: "gemini-3.5-flash",
+      label: "gemini-3.5-flash",
+      description: "Gemini 3.5 Flash",
+    },
+    {
+      value: "gpt-5.1-codex-mini-low",
+      label: "gpt-5.1-codex-mini-low",
+      description: "Codex 5.1 Mini Low",
+    },
+    {
+      value: "gpt-5.1-codex-mini",
+      label: "gpt-5.1-codex-mini",
+      description: "Codex 5.1 Mini",
+    },
+    {
+      value: "gpt-5.1-codex-mini-high",
+      label: "gpt-5.1-codex-mini-high",
+      description: "Codex 5.1 Mini High",
+    },
+    {
+      value: "claude-4-sonnet",
+      label: "claude-4-sonnet",
+      description: "Sonnet 4",
+    },
+    {
+      value: "claude-4-sonnet-thinking",
+      label: "claude-4-sonnet-thinking",
+      description: "Sonnet 4 Thinking",
+    },
+    {
+      value: "gpt-5-mini",
+      label: "gpt-5-mini",
+      description: "GPT-5 Mini",
+    },
+    {
+      value: "kimi-k2.5",
+      label: "kimi-k2.5",
+      description: "Kimi K2.5",
+    },
+  ],
+  DEFAULT: "composer-2.5-fast",
+};
+
+type CursorModelRow = {
+  name: string;
+  description: string;
+  current: boolean;
+  default: boolean;
+};
+
+const CURSOR_MODELS_TIMEOUT_MS = 10_000;
+const CURSOR_CHATS_ROOT = path.join(os.homedir(), '.cursor', 'chats');
+const spawnFunction = process.platform === 'win32' ? crossSpawn : spawn;
+const ANSI_PATTERN = new RegExp(
+  // eslint-disable-next-line no-control-regex
+  '[\\u001B\\u009B][[\\]()#;?]*(?:'
+  + '(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]'
+  + '|(?:[\\dA-PR-TZcf-ntqry=><~]))',
+  'g',
+);
+
+const stripAnsi = (value: string): string => value.replace(ANSI_PATTERN, '');
+
+const parseModelLine = (line: string): CursorModelRow | null => {
+  const trimmed = line.trim();
+
+  if (
+    !trimmed
+    || trimmed === 'Available models'
+    || trimmed.startsWith('Loading models')
+    || trimmed.startsWith('Tip:')
+  ) {
+    return null;
+  }
+
+  const match = trimmed.match(/^(.+?)\s+-\s+(.+)$/);
+  if (!match) {
+    return null;
+  }
+
+  const name = match[1].trim();
+  let description = match[2].trim();
+  const current = /\(current\)/i.test(description);
+  const defaultModel = /\(default\)/i.test(description);
+
+  description = description.replace(/\s*\((current|default)\)/gi, '').replace(/\s{2,}/g, ' ').trim();
+
+  return {
+    name,
+    description,
+    current,
+    default: defaultModel,
+  };
+};
+
+const parseModelsOutput = (text: string): CursorModelRow[] => {
+  const models: CursorModelRow[] = [];
+
+  for (const line of stripAnsi(text).split(/\r?\n/)) {
+    const parsed = parseModelLine(line);
+    if (parsed) {
+      models.push(parsed);
+    }
+  }
+
+  return models;
+};
+
+const runCursorListModels = (): Promise<string> => new Promise((resolve, reject) => {
+  const cursorProcess = spawnFunction('cursor-agent', ['--list-models'], {
+    env: { ...process.env },
+  });
+
+  let stdout = '';
+  let stderr = '';
+  let settled = false;
+
+  const timer = setTimeout(() => {
+    cursorProcess.kill('SIGTERM');
+    if (!settled) {
+      settled = true;
+      reject(new Error('cursor-agent --list-models timed out'));
+    }
+  }, CURSOR_MODELS_TIMEOUT_MS);
+
+  const finish = (error: Error | null, output: string) => {
+    if (settled) {
+      return;
+    }
+
+    settled = true;
+    clearTimeout(timer);
+
+    if (error) {
+      reject(error);
+      return;
+    }
+
+    resolve(output);
+  };
+
+  cursorProcess.stdout?.on('data', (chunk: Buffer) => {
+    stdout += chunk.toString();
+  });
+
+  cursorProcess.stderr?.on('data', (chunk: Buffer) => {
+    stderr += chunk.toString();
+  });
+
+  cursorProcess.on('error', (error) => {
+    finish(error instanceof Error ? error : new Error(String(error)), '');
+  });
+
+  cursorProcess.on('close', (code) => {
+    if (code !== 0) {
+      finish(new Error(stderr.trim() || `cursor-agent --list-models exited with code ${code}`), '');
+      return;
+    }
+
+    finish(null, stdout);
+  });
+});
+
+const buildCursorModelsDefinition = (models: CursorModelRow[]): ProviderModelsDefinition => {
+  const options: ProviderModelOption[] = [];
+  const seenValues = new Set<string>();
+
+  for (const model of models) {
+    if (seenValues.has(model.name)) {
+      continue;
+    }
+
+    seenValues.add(model.name);
+    options.push({
+      value: model.name,
+      label: model.name,
+      description: model.description || undefined,
+    });
+  }
+
+  if (options.length === 0) {
+    return CURSOR_FALLBACK_MODELS;
+  }
+
+  const defaultValue = models.find((model) => model.default)?.name
+    ?? models.find((model) => model.current)?.name
+    ?? options[0]?.value
+    ?? CURSOR_FALLBACK_MODELS.DEFAULT;
+
+  return {
+    OPTIONS: options,
+    DEFAULT: defaultValue,
+  };
+};
+
+const resolveCursorSessionStorePath = async (sessionId: string): Promise<string | null> => {
+  const safeSessionId = sanitizeLeafDirectoryName(sessionId, 'cursor session id');
+
+  try {
+    const workspaceEntries = await readdir(CURSOR_CHATS_ROOT, { withFileTypes: true });
+    for (const workspaceEntry of workspaceEntries) {
+      if (!workspaceEntry.isDirectory()) {
+        continue;
+      }
+
+      const storeDbPath = path.join(CURSOR_CHATS_ROOT, workspaceEntry.name, safeSessionId, 'store.db');
+      try {
+        await access(storeDbPath);
+        return storeDbPath;
+      } catch {
+        // Keep scanning sibling workspaces until the matching session directory is found.
+      }
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+};
+
+export class CursorProviderModels implements IProviderModels {
+  async getSupportedModels(): Promise<ProviderModelsDefinition> {
+    try {
+      const stdout = await runCursorListModels();
+      const models = parseModelsOutput(stdout);
+      return buildCursorModelsDefinition(models);
+    } catch {
+      return CURSOR_FALLBACK_MODELS;
+    }
+  }
+
+  async getCurrentActiveModel(sessionId?: string): Promise<ProviderCurrentActiveModel> {
+    if (!sessionId?.trim()) {
+      return buildDefaultProviderCurrentActiveModel(await this.getSupportedModels());
+    }
+
+    try {
+      const storeDbPath = await resolveCursorSessionStorePath(sessionId);
+      if (!storeDbPath) {
+        return buildDefaultProviderCurrentActiveModel(await this.getSupportedModels());
+      }
+
+      const { default: Database } = await import('better-sqlite3');
+      const db = new Database(storeDbPath, { readonly: true, fileMustExist: true });
+
+      try {
+        const row = db.prepare(`SELECT value FROM meta WHERE key='0' LIMIT 1;`).get() as {
+          value?: Buffer | string;
+        } | undefined;
+        const metadataText = Buffer.isBuffer(row?.value)
+          ? row.value.toString('utf8')
+          : typeof row?.value === 'string' && row.value.trim()
+            ? Buffer.from(row.value.trim(), 'hex').toString('utf8')
+            : '';
+        if (!metadataText) {
+          return buildDefaultProviderCurrentActiveModel(await this.getSupportedModels());
+        }
+
+        const metadata = JSON.parse(metadataText) as { lastUsedModel?: string };
+        if (typeof metadata.lastUsedModel === 'string' && metadata.lastUsedModel.trim()) {
+          return {
+            model: metadata.lastUsedModel.trim(),
+          };
+        }
+      } finally {
+        db.close();
+      }
+    } catch {
+      // Fall through to the provider default when Cursor metadata cannot be read.
+    }
+
+    return buildDefaultProviderCurrentActiveModel(await this.getSupportedModels());
+  }
+
+  async changeActiveModel(
+    input: ProviderChangeActiveModelInput,
+  ): Promise<ProviderSessionActiveModelChange> {
+    return writeProviderSessionActiveModelChange('cursor', input);
+  }
+}
+
diff --git a/server/modules/providers/list/cursor/cursor-session-synchronizer.provider.ts b/server/modules/providers/list/cursor/cursor-session-synchronizer.provider.ts
new file mode 100644
index 00000000..d5ea9b3c
--- /dev/null
+++ b/server/modules/providers/list/cursor/cursor-session-synchronizer.provider.ts
@@ -0,0 +1,153 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+
+import { sessionsDb } from '@/modules/database/index.js';
+import {
+  extractFirstValidJsonlData,
+  findFilesRecursivelyCreatedAfter,
+  normalizeSessionName,
+  readFileTimestamps,
+} from '@/shared/utils.js';
+import type { IProviderSessionSynchronizer } from '@/shared/interfaces.js';
+
+type ParsedSession = {
+  sessionId: string;
+  projectPath: string;
+  sessionName?: string;
+};
+
+/**
+ * Returns directory entries or an empty list when the folder is missing.
+ */
+async function listDirectoryEntriesSafe(
+  directoryPath: string
+): Promise<import('node:fs').Dirent[]> {
+  try {
+    return await fsp.readdir(directoryPath, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Session indexer for Cursor transcript artifacts.
+ */
+export class CursorSessionSynchronizer implements IProviderSessionSynchronizer {
+  private readonly provider = 'cursor' as const;
+  private readonly cursorHome = path.join(os.homedir(), '.cursor');
+
+  /**
+   * Scans Cursor chats and upserts discovered sessions into DB.
+   */
+  async synchronize(since?: Date): Promise<number> {
+    const projectsDir = path.join(this.cursorHome, 'projects');
+
+    let processed = 0;
+
+    const files = await findFilesRecursivelyCreatedAfter(projectsDir, '.jsonl', since ?? null);
+
+    for (const filePath of files) {
+      const parsed = await this.processSessionFile(filePath);
+      if (!parsed) {
+        continue;
+      }
+
+      const timestamps = await readFileTimestamps(filePath);
+      sessionsDb.createSession(
+        parsed.sessionId,
+        this.provider,
+        parsed.projectPath,
+        parsed.sessionName,
+        timestamps.createdAt,
+        timestamps.updatedAt,
+        filePath
+      );
+      processed += 1;
+    }
+
+    return processed;
+  }
+
+  /**
+   * Parses and upserts one Cursor session JSONL file.
+   */
+  async synchronizeFile(filePath: string): Promise<string | null> {
+    if (!filePath.endsWith('.jsonl')) {
+      return null;
+    }
+
+    const parsed = await this.processSessionFile(filePath);
+    if (!parsed) {
+      return null;
+    }
+
+    const timestamps = await readFileTimestamps(filePath);
+    return sessionsDb.createSession(
+      parsed.sessionId,
+      this.provider,
+      parsed.projectPath,
+      parsed.sessionName,
+      timestamps.createdAt,
+      timestamps.updatedAt,
+      filePath
+    );
+  }
+
+  /**
+   * Extracts project path from Cursor worker.log.
+   */
+  private async extractProjectPathFromWorkerLog(filePath: string): Promise<string | null> {
+    try {
+      const fileStream = fs.createReadStream(filePath, { encoding: 'utf8' });
+      const lineReader = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+
+      for await (const line of lineReader) {
+        const match = line.match(/workspacePath=(.*)$/);
+        const projectPath = match?.[1]?.trim();
+        if (projectPath) {
+          lineReader.close();
+          fileStream.close();
+          return projectPath;
+        }
+      }
+    } catch {
+      // Missing worker logs are valid for partial or incomplete session data.
+    }
+
+    return null;
+  }
+
+  /**
+   * Extracts session metadata from one Cursor JSONL session file.
+   */
+  private async processSessionFile(filePath: string): Promise<ParsedSession | null> {
+    const sessionId = path.basename(filePath, '.jsonl');
+    const grandparentDir = path.dirname(path.dirname(path.dirname(filePath)));
+    const workerLogPath = path.join(grandparentDir, 'worker.log');
+    const projectPath = await this.extractProjectPathFromWorkerLog(workerLogPath);
+
+    if (!projectPath) {
+      return null;
+    }
+
+    return extractFirstValidJsonlData(filePath, (rawData) => {
+      const data = rawData as Record<string, any>;
+      if (data.role !== 'user') {
+        return null;
+      }
+
+      const text = typeof data.message?.content?.[0]?.text === 'string' ? data.message.content[0].text : '';
+      const firstLine = text.replace(/<\/?user_query>/g, '').trim().split('\n')[0];
+
+      return {
+        sessionId,
+        projectPath,
+        sessionName: normalizeSessionName(firstLine, 'Untitled Cursor Session'),
+      };
+    });
+  }
+}
diff --git a/server/modules/providers/list/cursor/cursor-sessions.provider.ts b/server/modules/providers/list/cursor/cursor-sessions.provider.ts
index e276ba8c..33f93ea5 100644
--- a/server/modules/providers/list/cursor/cursor-sessions.provider.ts
+++ b/server/modules/providers/list/cursor/cursor-sessions.provider.ts
@@ -4,7 +4,12 @@ import path from 'node:path';
 
 import type { IProviderSessions } from '@/shared/interfaces.js';
 import type { AnyRecord, FetchHistoryOptions, FetchHistoryResult, NormalizedMessage } from '@/shared/types.js';
-import { createNormalizedMessage, generateMessageId, readObjectRecord } from '@/shared/utils.js';
+import {
+  createNormalizedMessage,
+  generateMessageId,
+  readObjectRecord,
+  sanitizeLeafDirectoryName,
+} from '@/shared/utils.js';
 
 const PROVIDER = 'cursor';
 
@@ -25,19 +30,162 @@ type CursorMessageBlob = {
   content: AnyRecord;
 };
 
-function sanitizeCursorSessionId(sessionId: string): string {
-  const normalized = sessionId.trim();
-  if (!normalized) {
-    throw new Error('Cursor session id is required.');
+function isInternalCursorText(value: unknown): boolean {
+  if (typeof value !== 'string') {
+    return false;
   }
 
-  if (
-    normalized.includes('..')
-    || normalized.includes(path.posix.sep)
-    || normalized.includes(path.win32.sep)
-    || normalized !== path.basename(normalized)
-  ) {
-    throw new Error(`Invalid cursor session id "${sessionId}".`);
+  const normalized = value.trim();
+  return normalized.startsWith('<user_info>') || normalized.startsWith('<system_reminder>');
+}
+
+function isInternalCursorPart(part: unknown): boolean {
+  if (!part || typeof part !== 'object') {
+    return false;
+  }
+
+  const record = part as AnyRecord;
+  const type = typeof record.type === 'string' ? record.type : '';
+  if (type === 'user_info' || type === 'system_reminder') {
+    return true;
+  }
+
+  return isInternalCursorText(record.text);
+}
+
+function unwrapUserQueryText(value: string, role: 'user' | 'assistant'): string {
+  if (role !== 'user') {
+    return value;
+  }
+
+  const normalized = value.trimStart();
+  const openTag = '<user_query>';
+  const closeTag = '</user_query>';
+  if (!normalized.startsWith(openTag)) {
+    return value;
+  }
+
+  const afterOpen = normalized.slice(openTag.length);
+  const closeIndex = afterOpen.lastIndexOf(closeTag);
+  const inner = closeIndex >= 0 ? afterOpen.slice(0, closeIndex) : afterOpen;
+  return inner.trim();
+}
+
+function normalizeToolId(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const normalized = value.trim();
+  return normalized ? normalized : null;
+}
+
+function extractCursorToolResultContent(item: AnyRecord): string {
+  if (typeof item.result === 'string' && item.result.trim()) {
+    return item.result;
+  }
+
+  if (typeof item.output === 'string' && item.output.trim()) {
+    return item.output;
+  }
+
+  if (Array.isArray(item.experimental_content)) {
+    const experimentalText = item.experimental_content
+      .map((part: unknown) => {
+        if (typeof part === 'string') {
+          return part;
+        }
+        if (part && typeof part === 'object') {
+          const record = part as AnyRecord;
+          if (typeof record.text === 'string') {
+            return record.text;
+          }
+        }
+        return '';
+      })
+      .filter(Boolean)
+      .join('\n');
+
+    if (experimentalText.trim()) {
+      return experimentalText;
+    }
+  }
+
+  return typeof item.result === 'string' ? item.result : '';
+}
+
+function parseCursorToolInput(rawInput: unknown): unknown {
+  if (typeof rawInput !== 'string') {
+    return rawInput;
+  }
+
+  const trimmed = rawInput.trim();
+  if (!trimmed) {
+    return rawInput;
+  }
+
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return rawInput;
+  }
+}
+
+function normalizeCursorToolInput(toolName: string, rawInput: unknown): unknown {
+  const parsed = parseCursorToolInput(rawInput);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return parsed;
+  }
+
+  const input = parsed as AnyRecord;
+  const normalized: AnyRecord = { ...input };
+
+  const filePath = input.file_path
+    ?? input.filePath
+    ?? input.path
+    ?? input.file
+    ?? input.filename;
+  if (typeof filePath === 'string' && filePath.trim()) {
+    normalized.file_path = filePath;
+  }
+
+  if (toolName === 'Write') {
+    const content = input.content
+      ?? input.text
+      ?? input.value
+      ?? input.contents
+      ?? input.fileContent
+      ?? input.new_string
+      ?? input.newString;
+    if (typeof content === 'string') {
+      normalized.content = content;
+    }
+  }
+
+  if (toolName === 'Edit') {
+    const oldString = input.old_string
+      ?? input.oldString
+      ?? input.old
+      ?? '';
+    const newString = input.new_string
+      ?? input.newString
+      ?? input.new
+      ?? input.content
+      ?? '';
+
+    if (typeof oldString === 'string') {
+      normalized.old_string = oldString;
+    }
+    if (typeof newString === 'string') {
+      normalized.new_string = newString;
+    }
+  }
+
+  if (toolName === 'ApplyPatch') {
+    const patch = input.patch ?? input.diff ?? input.content;
+    if (typeof patch === 'string' && !normalized.patch) {
+      normalized.patch = patch;
+    }
   }
 
   return normalized;
@@ -53,7 +201,7 @@ export class CursorSessionsProvider implements IProviderSessions {
     const { default: Database } = await import('better-sqlite3');
 
     const cwdId = crypto.createHash('md5').update(projectPath || process.cwd()).digest('hex');
-    const safeSessionId = sanitizeCursorSessionId(sessionId);
+    const safeSessionId = sanitizeLeafDirectoryName(sessionId, 'cursor session id');
     const baseChatsPath = path.join(os.homedir(), '.cursor', 'chats', cwdId);
     const storeDbPath = path.join(baseChatsPath, safeSessionId, 'store.db');
     const resolvedBaseChatsPath = path.resolve(baseChatsPath);
@@ -225,13 +373,14 @@ export class CursorSessionsProvider implements IProviderSessions {
     try {
       const blobs = await this.loadCursorBlobs(sessionId, projectPath);
       const allNormalized = this.normalizeCursorBlobs(blobs, sessionId);
-      const total = allNormalized.length;
+      const renderableMessages = allNormalized.filter((msg) => msg.kind !== 'tool_result');
+      const total = renderableMessages.length;
 
       if (limit !== null) {
         const start = offset;
         const page = limit === 0
           ? []
-          : allNormalized.slice(start, start + limit);
+          : renderableMessages.slice(start, start + limit);
         const hasMore = limit === 0
           ? start < total
           : start + limit < total;
@@ -245,7 +394,7 @@ export class CursorSessionsProvider implements IProviderSessions {
       }
 
       return {
-        messages: allNormalized,
+        messages: renderableMessages,
         total,
         hasMore: false,
         offset: 0,
@@ -283,11 +432,24 @@ export class CursorSessionsProvider implements IProviderSessions {
             let text = '';
             if (Array.isArray(content.message.content)) {
               text = content.message.content
-                .map((part: string | AnyRecord) => typeof part === 'string' ? part : part?.text || '')
+                .map((part: string | AnyRecord) => {
+                  if (typeof part === 'string') {
+                    if (isInternalCursorText(part)) {
+                      return '';
+                    }
+                    return unwrapUserQueryText(part, role);
+                  }
+                  if (isInternalCursorPart(part)) {
+                    return '';
+                  }
+                  return unwrapUserQueryText(part?.text || '', role);
+                })
                 .filter(Boolean)
                 .join('\n');
             } else if (typeof content.message.content === 'string') {
-              text = content.message.content;
+              if (!isInternalCursorText(content.message.content)) {
+                text = unwrapUserQueryText(content.message.content, role);
+              }
             }
             if (text?.trim()) {
               messages.push(createNormalizedMessage({
@@ -316,7 +478,14 @@ export class CursorSessionsProvider implements IProviderSessions {
             if (item?.type !== 'tool-result') {
               continue;
             }
-            const toolCallId = item.toolCallId || content.id;
+            const cursorOptions = content.providerOptions?.cursor as AnyRecord | undefined;
+            const highLevelToolCallResult = cursorOptions?.highLevelToolCallResult;
+            const toolCallId = normalizeToolId(item.toolCallId)
+              || normalizeToolId(item.tool_call_id)
+              || normalizeToolId(highLevelToolCallResult?.toolCallId)
+              || normalizeToolId(highLevelToolCallResult?.tool_call_id)
+              || normalizeToolId(content.id)
+              || '';
             messages.push(createNormalizedMessage({
               id: `${baseId}_tr`,
               sessionId,
@@ -324,8 +493,9 @@ export class CursorSessionsProvider implements IProviderSessions {
               provider: PROVIDER,
               kind: 'tool_result',
               toolId: toolCallId,
-              content: item.result || '',
-              isError: false,
+              content: extractCursorToolResultContent(item),
+              isError: Boolean(item.isError || item.is_error),
+              toolUseResult: highLevelToolCallResult,
             }));
           }
           continue;
@@ -336,8 +506,15 @@ export class CursorSessionsProvider implements IProviderSessions {
         if (Array.isArray(content.content)) {
           for (let partIdx = 0; partIdx < content.content.length; partIdx++) {
             const part = content.content[partIdx];
+            if (isInternalCursorPart(part)) {
+              continue;
+            }
 
             if (part?.type === 'text' && part?.text) {
+              const normalizedPartText = unwrapUserQueryText(part.text, role);
+              if (!normalizedPartText) {
+                continue;
+              }
               messages.push(createNormalizedMessage({
                 id: `${baseId}_${partIdx}`,
                 sessionId,
@@ -345,7 +522,7 @@ export class CursorSessionsProvider implements IProviderSessions {
                 provider: PROVIDER,
                 kind: 'text',
                 role,
-                content: part.text,
+                content: normalizedPartText,
                 sequence: blob.sequence,
                 rowid: blob.rowid,
               }));
@@ -361,7 +538,11 @@ export class CursorSessionsProvider implements IProviderSessions {
             } else if (part?.type === 'tool-call' || part?.type === 'tool_use') {
               const rawToolName = part.toolName || part.name || 'Unknown Tool';
               const toolName = rawToolName === 'ApplyPatch' ? 'Edit' : rawToolName;
-              const toolId = part.toolCallId || part.id || `tool_${i}_${partIdx}`;
+              const toolId = normalizeToolId(part.toolCallId)
+                || normalizeToolId(part.tool_call_id)
+                || normalizeToolId(part.id)
+                || `tool_${i}_${partIdx}`;
+              const normalizedToolInput = normalizeCursorToolInput(rawToolName, part.args ?? part.input);
               const message = createNormalizedMessage({
                 id: `${baseId}_${partIdx}`,
                 sessionId,
@@ -369,14 +550,22 @@ export class CursorSessionsProvider implements IProviderSessions {
                 provider: PROVIDER,
                 kind: 'tool_use',
                 toolName,
-                toolInput: part.args || part.input,
+                toolInput: normalizedToolInput,
                 toolId,
               });
               messages.push(message);
               toolUseMap.set(toolId, message);
             }
           }
-        } else if (typeof content.content === 'string' && content.content.trim()) {
+        } else if (
+          typeof content.content === 'string'
+          && content.content.trim()
+          && !isInternalCursorText(content.content)
+        ) {
+          const normalizedText = unwrapUserQueryText(content.content, role);
+          if (!normalizedText) {
+            continue;
+          }
           messages.push(createNormalizedMessage({
             id: baseId,
             sessionId,
@@ -384,7 +573,7 @@ export class CursorSessionsProvider implements IProviderSessions {
             provider: PROVIDER,
             kind: 'text',
             role,
-            content: content.content,
+            content: normalizedText,
             sequence: blob.sequence,
             rowid: blob.rowid,
           }));
@@ -401,6 +590,7 @@ export class CursorSessionsProvider implements IProviderSessions {
           toolUse.toolResult = {
             content: msg.content,
             isError: msg.isError,
+            toolUseResult: msg.toolUseResult,
           };
         }
       }
diff --git a/server/modules/providers/list/cursor/cursor-skills.provider.ts b/server/modules/providers/list/cursor/cursor-skills.provider.ts
new file mode 100644
index 00000000..3da72b9f
--- /dev/null
+++ b/server/modules/providers/list/cursor/cursor-skills.provider.ts
@@ -0,0 +1,31 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import { SkillsProvider } from '@/modules/providers/shared/skills/skills.provider.js';
+import type { ProviderSkillSource } from '@/shared/types.js';
+
+export class CursorSkillsProvider extends SkillsProvider {
+  constructor() {
+    super('cursor');
+  }
+
+  protected async getSkillSources(workspacePath: string): Promise<ProviderSkillSource[]> {
+    return [
+      {
+        scope: 'project',
+        rootDir: path.join(workspacePath, '.agents', 'skills'),
+        commandPrefix: '/',
+      },
+      {
+        scope: 'project',
+        rootDir: path.join(workspacePath, '.cursor', 'skills'),
+        commandPrefix: '/',
+      },
+      {
+        scope: 'user',
+        rootDir: path.join(os.homedir(), '.cursor', 'skills'),
+        commandPrefix: '/',
+      },
+    ];
+  }
+}
diff --git a/server/modules/providers/list/cursor/cursor.provider.ts b/server/modules/providers/list/cursor/cursor.provider.ts
index 7e834a10..ad125815 100644
--- a/server/modules/providers/list/cursor/cursor.provider.ts
+++ b/server/modules/providers/list/cursor/cursor.provider.ts
@@ -1,13 +1,25 @@
 import { AbstractProvider } from '@/modules/providers/shared/base/abstract.provider.js';
 import { CursorProviderAuth } from '@/modules/providers/list/cursor/cursor-auth.provider.js';
+import { CursorProviderModels } from '@/modules/providers/list/cursor/cursor-models.provider.js';
 import { CursorMcpProvider } from '@/modules/providers/list/cursor/cursor-mcp.provider.js';
+import { CursorSessionSynchronizer } from '@/modules/providers/list/cursor/cursor-session-synchronizer.provider.js';
 import { CursorSessionsProvider } from '@/modules/providers/list/cursor/cursor-sessions.provider.js';
-import type { IProviderAuth, IProviderSessions } from '@/shared/interfaces.js';
+import { CursorSkillsProvider } from '@/modules/providers/list/cursor/cursor-skills.provider.js';
+import type {
+  IProviderAuth,
+  IProviderModels,
+  IProviderSessionSynchronizer,
+  IProviderSkills,
+  IProviderSessions,
+} from '@/shared/interfaces.js';
 
 export class CursorProvider extends AbstractProvider {
+  readonly models: IProviderModels = new CursorProviderModels();
   readonly mcp = new CursorMcpProvider();
   readonly auth: IProviderAuth = new CursorProviderAuth();
+  readonly skills: IProviderSkills = new CursorSkillsProvider();
   readonly sessions: IProviderSessions = new CursorSessionsProvider();
+  readonly sessionSynchronizer: IProviderSessionSynchronizer = new CursorSessionSynchronizer();
 
   constructor() {
     super('cursor');
diff --git a/server/modules/providers/list/gemini/gemini-auth.provider.ts b/server/modules/providers/list/gemini/gemini-auth.provider.ts
index 60b0749e..c6897e74 100644
--- a/server/modules/providers/list/gemini/gemini-auth.provider.ts
+++ b/server/modules/providers/list/gemini/gemini-auth.provider.ts
@@ -15,7 +15,24 @@ type GeminiCredentialsStatus = {
   error?: string;
 };
 
+type GeminiAuthType =
+  | 'oauth-personal'
+  | 'gemini-api-key'
+  | 'vertex-ai'
+  | 'compute-default-credentials'
+  | 'gateway'
+  | 'cloud-shell'
+  | null;
+
 export class GeminiProviderAuth implements IProviderAuth {
+  /**
+   * Gemini CLI can override its home root via GEMINI_CLI_HOME.
+   * Use the same resolution so status checks match runtime behavior.
+   */
+  private getGeminiCliHome(): string {
+    return process.env.GEMINI_CLI_HOME?.trim() || os.homedir();
+  }
+
   /**
    * Checks whether the Gemini CLI is available on this host.
    */
@@ -58,6 +75,88 @@ export class GeminiProviderAuth implements IProviderAuth {
     };
   }
 
+  /**
+   * Parses dotenv-style key/value pairs.
+   */
+  private parseEnvFile(content: string): Record<string, string> {
+    const parsed: Record<string, string> = {};
+
+    for (const rawLine of content.split(/\r?\n/)) {
+      const line = rawLine.trim();
+      if (!line || line.startsWith('#')) {
+        continue;
+      }
+
+      const normalizedLine = line.startsWith('export ')
+        ? line.slice('export '.length).trim()
+        : line;
+      const separatorIndex = normalizedLine.indexOf('=');
+      if (separatorIndex <= 0) {
+        continue;
+      }
+
+      const key = normalizedLine.slice(0, separatorIndex).trim();
+      if (!key) {
+        continue;
+      }
+
+      let value = normalizedLine.slice(separatorIndex + 1).trim();
+      const quoted = (value.startsWith('"') && value.endsWith('"')) || (value.startsWith('\'') && value.endsWith('\''));
+      if (quoted) {
+        value = value.slice(1, -1);
+      } else {
+        value = value.replace(/\s+#.*$/, '').trim();
+      }
+
+      parsed[key] = value;
+    }
+
+    return parsed;
+  }
+
+  /**
+   * Loads user-level auth env in Gemini's "first file found" order.
+   */
+  private async loadUserLevelAuthEnv(): Promise<Record<string, string>> {
+    const geminiCliHome = this.getGeminiCliHome();
+    const envCandidates = [
+      path.join(geminiCliHome, '.gemini', '.env'),
+      path.join(geminiCliHome, '.env'),
+    ];
+
+    for (const envPath of envCandidates) {
+      try {
+        const content = await readFile(envPath, 'utf8');
+        return this.parseEnvFile(content);
+      } catch {
+        // Continue to the next fallback.
+      }
+    }
+
+    return {};
+  }
+
+  /**
+   * Reads Gemini's selected auth type from settings.json when available.
+   */
+  private async readSelectedAuthType(): Promise<GeminiAuthType> {
+    try {
+      const settingsPath = path.join(this.getGeminiCliHome(), '.gemini', 'settings.json');
+      const content = await readFile(settingsPath, 'utf8');
+      const settings = readObjectRecord(JSON.parse(content));
+      const security = readObjectRecord(settings?.security);
+      const auth = readObjectRecord(security?.auth);
+      const selectedType = readOptionalString(auth?.selectedType);
+      if (!selectedType) {
+        return null;
+      }
+
+      return selectedType as GeminiAuthType;
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * Checks Gemini credentials from API key env vars or local OAuth credential files.
    */
@@ -66,8 +165,46 @@ export class GeminiProviderAuth implements IProviderAuth {
       return { authenticated: true, email: 'API Key Auth', method: 'api_key' };
     }
 
+    const userEnv = await this.loadUserLevelAuthEnv();
+    if (readOptionalString(userEnv.GEMINI_API_KEY)) {
+      return { authenticated: true, email: 'API Key Auth', method: 'api_key' };
+    }
+
+    const selectedType = await this.readSelectedAuthType();
+    if (selectedType === 'vertex-ai') {
+      const hasGoogleApiKey = Boolean(
+        process.env.GOOGLE_API_KEY?.trim()
+        || readOptionalString(userEnv.GOOGLE_API_KEY)
+      );
+      const hasProject = Boolean(
+        process.env.GOOGLE_CLOUD_PROJECT?.trim()
+        || process.env.GOOGLE_CLOUD_PROJECT_ID?.trim()
+        || readOptionalString(userEnv.GOOGLE_CLOUD_PROJECT)
+        || readOptionalString(userEnv.GOOGLE_CLOUD_PROJECT_ID)
+      );
+      const hasLocation = Boolean(
+        process.env.GOOGLE_CLOUD_LOCATION?.trim()
+        || readOptionalString(userEnv.GOOGLE_CLOUD_LOCATION)
+      );
+      const hasServiceAccount = Boolean(
+        process.env.GOOGLE_APPLICATION_CREDENTIALS?.trim()
+        || readOptionalString(userEnv.GOOGLE_APPLICATION_CREDENTIALS)
+      );
+
+      if (hasGoogleApiKey || hasServiceAccount || (hasProject && hasLocation)) {
+        return { authenticated: true, email: 'Vertex AI Auth', method: 'vertex_ai' };
+      }
+
+      return {
+        authenticated: false,
+        email: null,
+        method: 'vertex_ai',
+        error: 'Gemini is set to Vertex AI, but required env vars are missing',
+      };
+    }
+
     try {
-      const credsPath = path.join(os.homedir(), '.gemini', 'oauth_creds.json');
+      const credsPath = path.join(this.getGeminiCliHome(), '.gemini', 'oauth_creds.json');
       const content = await readFile(credsPath, 'utf8');
       const creds = readObjectRecord(JSON.parse(content)) ?? {};
       const accessToken = readOptionalString(creds.access_token);
@@ -106,6 +243,25 @@ export class GeminiProviderAuth implements IProviderAuth {
         method: 'credentials_file',
       };
     } catch {
+      if (selectedType === 'gemini-api-key') {
+        return {
+          authenticated: false,
+          email: null,
+          method: 'api_key',
+          error: 'Gemini is set to "Use Gemini API key", but GEMINI_API_KEY is unavailable',
+        };
+      }
+
+      if (selectedType === 'oauth-personal') {
+        return {
+          authenticated: false,
+          email: null,
+          method: 'credentials_file',
+          error: 'Gemini is set to Google sign-in, but no cached OAuth credentials were found',
+        };
+      }
+
+      // If no explicit auth type was selected, surface the generic "not configured" error.
       return {
         authenticated: false,
         email: null,
@@ -140,7 +296,7 @@ export class GeminiProviderAuth implements IProviderAuth {
    */
   private async getActiveAccountEmail(): Promise<string | null> {
     try {
-      const accPath = path.join(os.homedir(), '.gemini', 'google_accounts.json');
+      const accPath = path.join(this.getGeminiCliHome(), '.gemini', 'google_accounts.json');
       const accContent = await readFile(accPath, 'utf8');
       const accounts = readObjectRecord(JSON.parse(accContent));
       return readOptionalString(accounts?.active) ?? null;
diff --git a/server/modules/providers/list/gemini/gemini-models.provider.ts b/server/modules/providers/list/gemini/gemini-models.provider.ts
new file mode 100644
index 00000000..fc830394
--- /dev/null
+++ b/server/modules/providers/list/gemini/gemini-models.provider.ts
@@ -0,0 +1,42 @@
+import type { IProviderModels } from '@/shared/interfaces.js';
+import type {
+  ProviderChangeActiveModelInput,
+  ProviderCurrentActiveModel,
+  ProviderModelsDefinition,
+  ProviderSessionActiveModelChange,
+} from '@/shared/types.js';
+import {
+  buildDefaultProviderCurrentActiveModel,
+  writeProviderSessionActiveModelChange,
+} from '@/shared/utils.js';
+
+export const GEMINI_FALLBACK_MODELS: ProviderModelsDefinition = {
+  OPTIONS: [
+    { value: 'gemini-3.1-pro-preview', label: 'Gemini 3.1 Pro Preview' },
+    { value: 'gemini-3-pro-preview', label: 'Gemini 3 Pro Preview' },
+    { value: 'gemini-3-flash-preview', label: 'Gemini 3 Flash Preview' },
+    { value: 'gemini-2.5-flash', label: 'Gemini 2.5 Flash' },
+    { value: 'gemini-2.5-pro', label: 'Gemini 2.5 Pro' },
+    { value: 'gemini-2.0-flash-lite', label: 'Gemini 2.0 Flash Lite' },
+    { value: 'gemini-2.0-flash', label: 'Gemini 2.0 Flash' },
+    { value: 'gemini-2.0-pro-exp', label: 'Gemini 2.0 Pro Experimental' },
+    { value: 'gemini-2.0-flash-thinking-exp', label: 'Gemini 2.0 Flash Thinking' },
+  ],
+  DEFAULT: 'gemini-3.1-pro-preview',
+};
+
+export class GeminiProviderModels implements IProviderModels {
+  async getSupportedModels(): Promise<ProviderModelsDefinition> {
+    return GEMINI_FALLBACK_MODELS;
+  }
+
+  async getCurrentActiveModel(): Promise<ProviderCurrentActiveModel> {
+    return buildDefaultProviderCurrentActiveModel(GEMINI_FALLBACK_MODELS);
+  }
+
+  async changeActiveModel(
+    input: ProviderChangeActiveModelInput,
+  ): Promise<ProviderSessionActiveModelChange> {
+    return writeProviderSessionActiveModelChange('gemini', input);
+  }
+}
diff --git a/server/modules/providers/list/gemini/gemini-session-synchronizer.provider.ts b/server/modules/providers/list/gemini/gemini-session-synchronizer.provider.ts
new file mode 100644
index 00000000..7ec3eff9
--- /dev/null
+++ b/server/modules/providers/list/gemini/gemini-session-synchronizer.provider.ts
@@ -0,0 +1,405 @@
+import crypto from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+import { projectsDb, sessionsDb } from '@/modules/database/index.js';
+import {
+  findFilesRecursivelyCreatedAfter,
+  normalizeProjectPath,
+  normalizeSessionName,
+  readFileTimestamps,
+} from '@/shared/utils.js';
+import type { IProviderSessionSynchronizer } from '@/shared/interfaces.js';
+import type { AnyRecord } from '@/shared/types.js';
+
+type ParsedSession = {
+  sessionId: string;
+  projectPath: string;
+  sessionName?: string;
+};
+
+type GeminiJsonlMetadata = {
+  sessionId: string;
+  projectPath?: string;
+  projectHash?: string;
+  firstUserMessage?: string;
+};
+
+/**
+ * Session indexer for Gemini transcript artifacts.
+ */
+export class GeminiSessionSynchronizer implements IProviderSessionSynchronizer {
+  private readonly provider = 'gemini' as const;
+  private readonly geminiHome = path.join(os.homedir(), '.gemini');
+
+  /**
+   * Scans Gemini legacy JSON and new JSONL artifacts and upserts sessions into DB.
+   */
+  async synchronize(since?: Date): Promise<number> {
+    const projectHashLookup = this.buildProjectHashLookup();
+
+    // const legacySessionFiles = await findFilesRecursivelyCreatedAfter(
+    //   path.join(this.geminiHome, 'sessions'),
+    //   '.json',
+    //   since ?? null
+    // );
+    // Gemini creates overlapping artifacts across `sessions/` and `tmp/`.
+    // We currently index only `tmp/*/chats/*.jsonl` because those files are the
+    // live transcript source and avoid duplicate session rows from mirrored files.
+    // const legacyTempFiles = await findFilesRecursivelyCreatedAfter(
+    //   path.join(this.geminiHome, 'tmp'),
+    //   '.json',
+    //   since ?? null
+    // );
+    // const jsonlSessionFiles = await findFilesRecursivelyCreatedAfter(
+    //   path.join(this.geminiHome, 'sessions'),
+    //   '.jsonl',
+    //   since ?? null
+    // );
+    const jsonlTempFiles = await findFilesRecursivelyCreatedAfter(
+      path.join(this.geminiHome, 'tmp'),
+      '.jsonl',
+      since ?? null
+    );
+
+    // Current strategy: index only temp chat JSONL artifacts.
+    const files = [
+      // ...legacySessionFiles,
+      // Intentionally disabled to avoid duplicate indexing from mirrored
+      // `sessions/*.json` and `sessions/*.jsonl` artifacts.
+      // ...legacyTempFiles,
+      // ...jsonlSessionFiles,
+      ...jsonlTempFiles,
+    ];
+
+    let processed = 0;
+    for (const filePath of files) {
+      if (this.shouldSkipTempArtifact(filePath)) {
+        continue;
+      }
+
+      const parsed = filePath.endsWith('.jsonl')
+        ? await this.processJsonlSessionFile(filePath, projectHashLookup)
+        : await this.processLegacySessionFile(filePath);
+      if (!parsed) {
+        continue;
+      }
+
+      const timestamps = await readFileTimestamps(filePath);
+      sessionsDb.createSession(
+        parsed.sessionId,
+        this.provider,
+        parsed.projectPath,
+        parsed.sessionName,
+        timestamps.createdAt,
+        timestamps.updatedAt,
+        filePath
+      );
+      processed += 1;
+    }
+
+    return processed;
+  }
+
+  /**
+   * Parses and upserts one Gemini legacy JSON or JSONL artifact.
+   */
+  async synchronizeFile(filePath: string): Promise<string | null> {
+    if (!filePath.endsWith('.json') && !filePath.endsWith('.jsonl')) {
+      return null;
+    }
+
+    if (this.shouldSkipTempArtifact(filePath)) {
+      return null;
+    }
+
+    const parsed = filePath.endsWith('.jsonl')
+      ? await this.processJsonlSessionFile(filePath, this.buildProjectHashLookup())
+      : await this.processLegacySessionFile(filePath);
+    if (!parsed) {
+      return null;
+    }
+
+    const timestamps = await readFileTimestamps(filePath);
+    return sessionsDb.createSession(
+      parsed.sessionId,
+      this.provider,
+      parsed.projectPath,
+      parsed.sessionName,
+      timestamps.createdAt,
+      timestamps.updatedAt,
+      filePath
+    );
+  }
+
+  /**
+   * Extracts session metadata from one Gemini legacy JSON artifact.
+   */
+  private async processLegacySessionFile(filePath: string): Promise<ParsedSession | null> {
+    try {
+      const content = await readFile(filePath, 'utf8');
+      const data = JSON.parse(content) as AnyRecord;
+
+      const sessionId =
+        typeof data.sessionId === 'string'
+          ? data.sessionId
+          : typeof data.id === 'string'
+            ? data.id
+            : undefined;
+      if (!sessionId) {
+        return null;
+      }
+
+      const workspaceProjectPath = await this.resolveProjectPathFromChatWorkspace(filePath);
+      const projectPath = typeof data.projectPath === 'string' && data.projectPath.trim().length > 0
+        ? data.projectPath
+        : workspaceProjectPath;
+      if (!projectPath) {
+        return null;
+      }
+
+      const messages = Array.isArray(data.messages) ? data.messages : [];
+      const firstMessage = messages[0] as AnyRecord | undefined;
+      let rawName: string | undefined;
+
+      if (Array.isArray(firstMessage?.content) && typeof firstMessage.content[0]?.text === 'string') {
+        rawName = firstMessage.content[0].text;
+      } else if (typeof firstMessage?.content === 'string') {
+        rawName = firstMessage.content;
+      }
+
+      return {
+        sessionId,
+        projectPath,
+        sessionName: normalizeSessionName(rawName, 'New Gemini Chat'),
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Extracts session metadata from one Gemini JSONL artifact.
+   */
+  private async processJsonlSessionFile(
+    filePath: string,
+    projectHashLookup: Map<string, string>
+  ): Promise<ParsedSession | null> {
+    const metadata = await this.extractJsonlMetadata(filePath);
+    if (!metadata) {
+      return null;
+    }
+
+    let projectPath = typeof metadata.projectPath === 'string' ? metadata.projectPath.trim() : '';
+    if (!projectPath) {
+      const workspaceProjectPath = await this.resolveProjectPathFromChatWorkspace(filePath);
+      if (workspaceProjectPath) {
+        projectPath = workspaceProjectPath;
+      }
+    }
+    if (!projectPath && typeof metadata.projectHash === 'string') {
+      projectPath = projectHashLookup.get(metadata.projectHash.trim().toLowerCase()) ?? '';
+    }
+    if (!projectPath) {
+      return null;
+    }
+
+    // Once we resolve a project hash/path pair, keep it in-memory for this sync run.
+    if (typeof metadata.projectHash === 'string' && metadata.projectHash.trim()) {
+      projectHashLookup.set(metadata.projectHash.trim().toLowerCase(), projectPath);
+    }
+
+    return {
+      sessionId: metadata.sessionId,
+      projectPath,
+      sessionName: normalizeSessionName(metadata.firstUserMessage, 'New Gemini Chat'),
+    };
+  }
+
+  /**
+   * Reads first useful metadata from Gemini JSONL files.
+   */
+  private async extractJsonlMetadata(filePath: string): Promise<GeminiJsonlMetadata | null> {
+    try {
+      const content = await readFile(filePath, 'utf8');
+      const lines = content.split('\n');
+
+      let sessionId: string | undefined;
+      let projectPath: string | undefined;
+      let projectHash: string | undefined;
+      let firstUserMessage: string | undefined;
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+          continue;
+        }
+
+        let parsed: AnyRecord;
+        try {
+          parsed = JSON.parse(trimmed) as AnyRecord;
+        } catch {
+          continue;
+        }
+
+        if (!sessionId && typeof parsed.sessionId === 'string') {
+          sessionId = parsed.sessionId;
+        }
+        if (!projectPath && typeof parsed.projectPath === 'string') {
+          projectPath = parsed.projectPath;
+        }
+        if (!projectHash && typeof parsed.projectHash === 'string') {
+          projectHash = parsed.projectHash;
+        }
+
+        if (!firstUserMessage && parsed.type === 'user') {
+          firstUserMessage = this.extractGeminiTextContent(parsed.content);
+        }
+
+        if (sessionId && (projectPath || projectHash) && firstUserMessage) {
+          break;
+        }
+      }
+
+      if (!sessionId) {
+        return null;
+      }
+
+      return {
+        sessionId,
+        projectPath,
+        projectHash,
+        firstUserMessage,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Tries to resolve project root from Gemini tmp chat workspaces.
+   */
+  private async resolveProjectPathFromChatWorkspace(filePath: string): Promise<string> {
+    if (!filePath.includes(`${path.sep}chats${path.sep}`)) {
+      return '';
+    }
+
+    const chatsDir = path.dirname(filePath);
+    const workspaceDir = path.dirname(chatsDir);
+    const projectRootPath = path.join(workspaceDir, '.project_root');
+
+    try {
+      const rootContent = await readFile(projectRootPath, 'utf8');
+      return rootContent.trim();
+    } catch {
+      return '';
+    }
+  }
+
+  /**
+   * Builds a hash->path lookup for Gemini JSONL metadata that stores projectHash.
+   */
+  private buildProjectHashLookup(): Map<string, string> {
+    const lookup = new Map<string, string>();
+    const knownPaths = new Set<string>();
+
+    for (const project of projectsDb.getProjectPaths()) {
+      if (typeof project.project_path === 'string' && project.project_path.trim()) {
+        knownPaths.add(project.project_path.trim());
+      }
+    }
+
+    for (const session of sessionsDb.getAllSessions()) {
+      if (session.provider === this.provider && typeof session.project_path === 'string' && session.project_path.trim()) {
+        knownPaths.add(session.project_path.trim());
+      }
+    }
+
+    for (const knownPath of knownPaths) {
+      this.addProjectHashCandidates(lookup, knownPath);
+    }
+
+    return lookup;
+  }
+
+  /**
+   * Adds likely Gemini hash variants for one project path.
+   */
+  private addProjectHashCandidates(lookup: Map<string, string>, projectPath: string): void {
+    const trimmed = projectPath.trim();
+    if (!trimmed) {
+      return;
+    }
+
+    const normalized = normalizeProjectPath(trimmed);
+    const resolved = path.resolve(trimmed);
+    const resolvedNormalized = normalizeProjectPath(resolved);
+
+    const candidates = new Set<string>([
+      trimmed,
+      normalized,
+      resolved,
+      resolvedNormalized,
+    ]);
+
+    if (process.platform === 'win32') {
+      for (const candidate of [...candidates]) {
+        candidates.add(candidate.toLowerCase());
+      }
+    }
+
+    for (const candidate of candidates) {
+      if (!candidate) {
+        continue;
+      }
+
+      const hash = this.sha256(candidate);
+      if (!lookup.has(hash)) {
+        lookup.set(hash, trimmed);
+      }
+    }
+  }
+
+  /**
+   * Returns first user text from Gemini content payload shapes.
+   */
+  private extractGeminiTextContent(content: unknown): string | undefined {
+    if (typeof content === 'string' && content.trim().length > 0) {
+      return content;
+    }
+
+    if (!Array.isArray(content)) {
+      return undefined;
+    }
+
+    for (const part of content) {
+      if (typeof part === 'string' && part.trim().length > 0) {
+        return part;
+      }
+
+      if (part && typeof part === 'object' && typeof (part as AnyRecord).text === 'string') {
+        const text = (part as AnyRecord).text;
+        if (text.trim().length > 0) {
+          return text;
+        }
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Keeps tmp scanning scoped to chat artifacts only.
+   */
+  private shouldSkipTempArtifact(filePath: string): boolean {
+    return (
+      filePath.startsWith(path.join(this.geminiHome, 'tmp'))
+      && !filePath.includes(`${path.sep}chats${path.sep}`)
+    );
+  }
+
+  private sha256(value: string): string {
+    return crypto.createHash('sha256').update(value).digest('hex');
+  }
+}
diff --git a/server/modules/providers/list/gemini/gemini-sessions.provider.ts b/server/modules/providers/list/gemini/gemini-sessions.provider.ts
index 7d5b5f1a..32781c9d 100644
--- a/server/modules/providers/list/gemini/gemini-sessions.provider.ts
+++ b/server/modules/providers/list/gemini/gemini-sessions.provider.ts
@@ -1,11 +1,242 @@
-import sessionManager from '@/sessionManager.js';
-import { getGeminiCliSessionMessages } from '@/projects.js';
+import fsSync from 'node:fs';
+import fs from 'node:fs/promises';
+import readline from 'node:readline';
+
+import { sessionsDb } from '@/modules/database/index.js';
 import type { IProviderSessions } from '@/shared/interfaces.js';
 import type { AnyRecord, FetchHistoryOptions, FetchHistoryResult, NormalizedMessage } from '@/shared/types.js';
 import { createNormalizedMessage, generateMessageId, readObjectRecord } from '@/shared/utils.js';
 
 const PROVIDER = 'gemini';
 
+type GeminiHistoryResult = {
+  messages: AnyRecord[];
+  tokenUsage?: unknown;
+};
+
+function mapGeminiRole(value: unknown): 'user' | 'assistant' | null {
+  if (value === 'user') {
+    return 'user';
+  }
+
+  if (value === 'gemini' || value === 'assistant') {
+    return 'assistant';
+  }
+
+  return null;
+}
+
+function extractGeminiTextContent(content: unknown): string {
+  if (typeof content === 'string') {
+    return content;
+  }
+
+  if (!Array.isArray(content)) {
+    return '';
+  }
+
+  return content
+    .map((part) => {
+      if (typeof part === 'string') {
+        return part;
+      }
+      if (!part || typeof part !== 'object') {
+        return '';
+      }
+
+      const record = part as AnyRecord;
+      if (typeof record.text === 'string') {
+        return record.text;
+      }
+
+      return '';
+    })
+    .filter(Boolean)
+    .join('\n');
+}
+
+function extractGeminiThoughts(thoughts: unknown): string {
+  if (!Array.isArray(thoughts)) {
+    return '';
+  }
+
+  return thoughts
+    .map((item) => {
+      if (!item || typeof item !== 'object') {
+        return '';
+      }
+
+      const record = item as AnyRecord;
+      const subject = typeof record.subject === 'string' ? record.subject.trim() : '';
+      const description = typeof record.description === 'string' ? record.description.trim() : '';
+
+      if (subject && description) {
+        return `${subject}: ${description}`;
+      }
+
+      return description || subject;
+    })
+    .filter(Boolean)
+    .join('\n');
+}
+
+function buildGeminiTokenUsage(tokens: unknown): AnyRecord | undefined {
+  if (!tokens || typeof tokens !== 'object') {
+    return undefined;
+  }
+
+  const record = tokens as AnyRecord;
+  const input = Number(record.input || 0);
+  const output = Number(record.output || 0);
+  const total = Number(record.total || input + output || 0);
+
+  return {
+    used: total,
+    inputTokens: input,
+    outputTokens: output,
+    breakdown: {
+      input,
+      output,
+    },
+  };
+}
+
+async function getGeminiLegacySessionMessages(sessionFilePath: string): Promise<GeminiHistoryResult> {
+  try {
+    const data = await fs.readFile(sessionFilePath, 'utf8');
+    const session = JSON.parse(data) as AnyRecord;
+    const sourceMessages = Array.isArray(session.messages) ? session.messages : [];
+
+    const messages: AnyRecord[] = [];
+    for (const msg of sourceMessages) {
+      const role = mapGeminiRole(msg.type ?? msg.role);
+      if (!role) {
+        continue;
+      }
+
+      messages.push({
+        type: 'message',
+        uuid: typeof msg.id === 'string' ? msg.id : undefined,
+        message: { role, content: msg.content },
+        timestamp: msg.timestamp || null,
+      });
+    }
+
+    return { messages };
+  } catch {
+    return { messages: [] };
+  }
+}
+
+async function getGeminiJsonlSessionMessages(sessionFilePath: string): Promise<GeminiHistoryResult> {
+  const messages: AnyRecord[] = [];
+  let tokenUsage: AnyRecord | undefined;
+
+  try {
+    const fileStream = fsSync.createReadStream(sessionFilePath);
+    const lineReader = readline.createInterface({
+      input: fileStream,
+      crlfDelay: Infinity,
+    });
+
+    for await (const line of lineReader) {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        continue;
+      }
+
+      let entry: AnyRecord;
+      try {
+        entry = JSON.parse(trimmed) as AnyRecord;
+      } catch {
+        continue;
+      }
+
+      // Metadata/update lines (e.g. {$set:{lastUpdated:...}}) do not represent chat messages.
+      if (entry.$set) {
+        continue;
+      }
+
+      const role = mapGeminiRole(entry.type);
+      if (role) {
+        const textContent = extractGeminiTextContent(entry.content);
+        if (textContent.trim()) {
+          messages.push({
+            type: 'message',
+            uuid: typeof entry.id === 'string' ? entry.id : undefined,
+            message: { role, content: textContent },
+            timestamp: entry.timestamp || null,
+          });
+        }
+
+        const thinkingContent = extractGeminiThoughts(entry.thoughts);
+        if (thinkingContent.trim()) {
+          messages.push({
+            type: 'thinking',
+            uuid: typeof entry.id === 'string' ? `${entry.id}_thinking` : undefined,
+            message: { role: 'assistant', content: thinkingContent },
+            timestamp: entry.timestamp || null,
+            isReasoning: true,
+          });
+        }
+
+        if (role === 'assistant') {
+          const usage = buildGeminiTokenUsage(entry.tokens);
+          if (usage) {
+            tokenUsage = usage;
+          }
+        }
+
+        continue;
+      }
+
+      if (entry.type === 'tool_use') {
+        messages.push({
+          type: 'tool_use',
+          uuid: typeof entry.id === 'string' ? entry.id : undefined,
+          timestamp: entry.timestamp || null,
+          toolName: entry.tool_name || entry.name || 'Tool',
+          toolInput: entry.parameters ?? entry.input ?? entry.arguments ?? '',
+          toolCallId: entry.tool_id || entry.toolCallId || entry.id,
+        });
+        continue;
+      }
+
+      if (entry.type === 'tool_result') {
+        messages.push({
+          type: 'tool_result',
+          uuid: typeof entry.id === 'string' ? entry.id : undefined,
+          timestamp: entry.timestamp || null,
+          toolCallId: entry.tool_id || entry.toolCallId || entry.id || '',
+          output: entry.output ?? entry.result ?? '',
+          isError: Boolean(entry.error) || entry.status === 'error',
+        });
+      }
+    }
+  } catch {
+    return { messages: [] };
+  }
+
+  messages.sort(
+    (a, b) => new Date(a.timestamp || 0).getTime() - new Date(b.timestamp || 0).getTime(),
+  );
+
+  return { messages, tokenUsage };
+}
+
+async function getGeminiCliSessionMessages(sessionId: string): Promise<GeminiHistoryResult> {
+  const sessionFilePath = sessionsDb.getSessionById(sessionId)?.jsonl_path;
+  if (!sessionFilePath) {
+    return { messages: [] };
+  }
+
+  if (sessionFilePath.endsWith('.jsonl')) {
+    return getGeminiJsonlSessionMessages(sessionFilePath);
+  }
+
+  return getGeminiLegacySessionMessages(sessionFilePath);
+}
+
 export class GeminiSessionsProvider implements IProviderSessions {
   /**
    * Normalizes live Gemini stream-json events into the shared message shape.
@@ -108,8 +339,7 @@ export class GeminiSessionsProvider implements IProviderSessions {
   }
 
   /**
-   * Loads Gemini history from the in-memory session manager first, then falls
-   * back to Gemini CLI session files on disk.
+   * Loads Gemini history from Gemini CLI session files on disk.
    */
   async fetchHistory(
     sessionId: string,
@@ -117,28 +347,73 @@ export class GeminiSessionsProvider implements IProviderSessions {
   ): Promise<FetchHistoryResult> {
     const { limit = null, offset = 0 } = options;
 
-    let rawMessages: AnyRecord[];
+    let result: GeminiHistoryResult;
     try {
-      rawMessages = sessionManager.getSessionMessages(sessionId) as AnyRecord[];
-
-      if (rawMessages.length === 0) {
-        rawMessages = await getGeminiCliSessionMessages(sessionId) as AnyRecord[];
-      }
+      result = await getGeminiCliSessionMessages(sessionId);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       console.warn(`[GeminiProvider] Failed to load session ${sessionId}:`, message);
       return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
     }
 
+    const rawMessages = result.messages;
     const normalized: NormalizedMessage[] = [];
+
     for (let i = 0; i < rawMessages.length; i++) {
       const raw = rawMessages[i];
       const ts = raw.timestamp || new Date().toISOString();
       const baseId = raw.uuid || generateMessageId('gemini');
 
+      if (raw.type === 'thinking' || raw.isReasoning) {
+        const thinkingContent = typeof raw.message?.content === 'string'
+          ? raw.message.content
+          : typeof raw.content === 'string'
+            ? raw.content
+            : '';
+
+        if (thinkingContent.trim()) {
+          normalized.push(createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'thinking',
+            content: thinkingContent,
+          }));
+        }
+        continue;
+      }
+
+      if (raw.type === 'tool_use' || raw.toolName) {
+        normalized.push(createNormalizedMessage({
+          id: baseId,
+          sessionId,
+          timestamp: ts,
+          provider: PROVIDER,
+          kind: 'tool_use',
+          toolName: raw.toolName || 'Tool',
+          toolInput: raw.toolInput,
+          toolId: raw.toolCallId || baseId,
+        }));
+        continue;
+      }
+
+      if (raw.type === 'tool_result') {
+        normalized.push(createNormalizedMessage({
+          id: baseId,
+          sessionId,
+          timestamp: ts,
+          provider: PROVIDER,
+          kind: 'tool_result',
+          toolId: raw.toolCallId || '',
+          content: raw.output === undefined ? '' : String(raw.output),
+          isError: Boolean(raw.isError),
+        }));
+        continue;
+      }
+
       const role = raw.message?.role || raw.role;
       const content = raw.message?.content || raw.content;
-
       if (!role || !content) {
         continue;
       }
@@ -147,8 +422,26 @@ export class GeminiSessionsProvider implements IProviderSessions {
 
       if (Array.isArray(content)) {
         for (let partIdx = 0; partIdx < content.length; partIdx++) {
-          const part = content[partIdx];
-          if (part.type === 'text' && part.text) {
+          const part = content[partIdx] as AnyRecord | string;
+
+          if (typeof part === 'string' && part.trim()) {
+            normalized.push(createNormalizedMessage({
+              id: `${baseId}_${partIdx}`,
+              sessionId,
+              timestamp: ts,
+              provider: PROVIDER,
+              kind: 'text',
+              role: normalizedRole,
+              content: part,
+            }));
+            continue;
+          }
+
+          if (!part || typeof part !== 'object') {
+            continue;
+          }
+
+          if ((part.type === 'text' || !part.type) && typeof part.text === 'string' && part.text.trim()) {
             normalized.push(createNormalizedMessage({
               id: `${baseId}_${partIdx}`,
               sessionId,
@@ -192,6 +485,19 @@ export class GeminiSessionsProvider implements IProviderSessions {
           role: normalizedRole,
           content,
         }));
+      } else {
+        const textContent = extractGeminiTextContent(content);
+        if (textContent.trim()) {
+          normalized.push(createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp: ts,
+            provider: PROVIDER,
+            kind: 'text',
+            role: normalizedRole,
+            content: textContent,
+          }));
+        }
       }
     }
 
@@ -215,13 +521,20 @@ export class GeminiSessionsProvider implements IProviderSessions {
     const messages = pageLimit === null
       ? normalized.slice(start)
       : normalized.slice(start, start + pageLimit);
+    let total = 0;
+    for (const msg of normalized) {
+      if (msg.kind !== 'tool_result') {
+        total += 1;
+      }
+    }
 
     return {
       messages,
-      total: normalized.length,
+      total,
       hasMore: pageLimit === null ? false : start + pageLimit < normalized.length,
       offset: start,
       limit: pageLimit,
+      tokenUsage: result.tokenUsage,
     };
   }
 }
diff --git a/server/modules/providers/list/gemini/gemini-skills.provider.ts b/server/modules/providers/list/gemini/gemini-skills.provider.ts
new file mode 100644
index 00000000..e49746a5
--- /dev/null
+++ b/server/modules/providers/list/gemini/gemini-skills.provider.ts
@@ -0,0 +1,36 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import { SkillsProvider } from '@/modules/providers/shared/skills/skills.provider.js';
+import type { ProviderSkillSource } from '@/shared/types.js';
+
+export class GeminiSkillsProvider extends SkillsProvider {
+  constructor() {
+    super('gemini');
+  }
+
+  protected async getSkillSources(workspacePath: string): Promise<ProviderSkillSource[]> {
+    return [
+      {
+        scope: 'user',
+        rootDir: path.join(os.homedir(), '.gemini', 'skills'),
+        commandPrefix: '/',
+      },
+      {
+        scope: 'user',
+        rootDir: path.join(os.homedir(), '.agents', 'skills'),
+        commandPrefix: '/',
+      },
+      {
+        scope: 'project',
+        rootDir: path.join(workspacePath, '.gemini', 'skills'),
+        commandPrefix: '/',
+      },
+      {
+        scope: 'project',
+        rootDir: path.join(workspacePath, '.agents', 'skills'),
+        commandPrefix: '/',
+      },
+    ];
+  }
+}
diff --git a/server/modules/providers/list/gemini/gemini.provider.ts b/server/modules/providers/list/gemini/gemini.provider.ts
index d968b7c0..38d25245 100644
--- a/server/modules/providers/list/gemini/gemini.provider.ts
+++ b/server/modules/providers/list/gemini/gemini.provider.ts
@@ -1,13 +1,25 @@
 import { AbstractProvider } from '@/modules/providers/shared/base/abstract.provider.js';
 import { GeminiProviderAuth } from '@/modules/providers/list/gemini/gemini-auth.provider.js';
+import { GeminiProviderModels } from '@/modules/providers/list/gemini/gemini-models.provider.js';
 import { GeminiMcpProvider } from '@/modules/providers/list/gemini/gemini-mcp.provider.js';
+import { GeminiSessionSynchronizer } from '@/modules/providers/list/gemini/gemini-session-synchronizer.provider.js';
 import { GeminiSessionsProvider } from '@/modules/providers/list/gemini/gemini-sessions.provider.js';
-import type { IProviderAuth, IProviderSessions } from '@/shared/interfaces.js';
+import { GeminiSkillsProvider } from '@/modules/providers/list/gemini/gemini-skills.provider.js';
+import type {
+  IProviderAuth,
+  IProviderModels,
+  IProviderSessionSynchronizer,
+  IProviderSkills,
+  IProviderSessions,
+} from '@/shared/interfaces.js';
 
 export class GeminiProvider extends AbstractProvider {
+  readonly models: IProviderModels = new GeminiProviderModels();
   readonly mcp = new GeminiMcpProvider();
   readonly auth: IProviderAuth = new GeminiProviderAuth();
+  readonly skills: IProviderSkills = new GeminiSkillsProvider();
   readonly sessions: IProviderSessions = new GeminiSessionsProvider();
+  readonly sessionSynchronizer: IProviderSessionSynchronizer = new GeminiSessionSynchronizer();
 
   constructor() {
     super('gemini');
diff --git a/server/modules/providers/list/opencode/opencode-auth.provider.ts b/server/modules/providers/list/opencode/opencode-auth.provider.ts
new file mode 100644
index 00000000..9f55d18b
--- /dev/null
+++ b/server/modules/providers/list/opencode/opencode-auth.provider.ts
@@ -0,0 +1,111 @@
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import spawn from 'cross-spawn';
+
+import type { IProviderAuth } from '@/shared/interfaces.js';
+import type { ProviderAuthStatus } from '@/shared/types.js';
+import { readObjectRecord, readOptionalString } from '@/shared/utils.js';
+
+type OpenCodeCredentialsStatus = {
+  authenticated: boolean;
+  email: string | null;
+  method: string | null;
+  error?: string;
+};
+
+const OPENCODE_ENV_CREDENTIAL_KEYS = [
+  'ANTHROPIC_API_KEY',
+  'OPENAI_API_KEY',
+  'GOOGLE_GENERATIVE_AI_API_KEY',
+  'GEMINI_API_KEY',
+  'GROQ_API_KEY',
+  'OPENROUTER_API_KEY',
+];
+
+export class OpenCodeProviderAuth implements IProviderAuth {
+  /**
+   * Checks whether the OpenCode CLI is available to the server process.
+   */
+  private checkInstalled(): boolean {
+    try {
+      const result = spawn.sync('opencode', ['--version'], { stdio: 'ignore', timeout: 5000 });
+      return !result.error && result.status === 0;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Returns OpenCode CLI installation and credential status.
+   */
+  async getStatus(): Promise<ProviderAuthStatus> {
+    const installed = this.checkInstalled();
+    const credentials = await this.checkCredentials();
+
+    return {
+      installed,
+      provider: 'opencode',
+      authenticated: credentials.authenticated,
+      email: credentials.email,
+      method: credentials.method,
+      error: credentials.authenticated ? undefined : credentials.error || 'Not authenticated',
+    };
+  }
+
+  /**
+   * Reads OpenCode's auth store or falls back to provider API key environment variables.
+   */
+  private async checkCredentials(): Promise<OpenCodeCredentialsStatus> {
+    try {
+      const authPath = path.join(os.homedir(), '.local', 'share', 'opencode', 'auth.json');
+      const content = await readFile(authPath, 'utf8');
+      const auth = readObjectRecord(JSON.parse(content)) ?? {};
+
+      for (const [providerId, providerAuth] of Object.entries(auth)) {
+        const providerRecord = readObjectRecord(providerAuth);
+        if (!providerRecord) {
+          continue;
+        }
+
+        const hasCredential = Object.values(providerRecord).some(
+          (value) => readOptionalString(value) !== undefined || Boolean(readObjectRecord(value)),
+        );
+        if (hasCredential) {
+          return {
+            authenticated: true,
+            email: `${providerId} credentials`,
+            method: 'credentials_file',
+          };
+        }
+      }
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== 'ENOENT') {
+        return {
+          authenticated: false,
+          email: null,
+          method: null,
+          error: error instanceof Error ? error.message : 'Failed to read OpenCode auth',
+        };
+      }
+    }
+
+    const envCredential = OPENCODE_ENV_CREDENTIAL_KEYS.find((key) => process.env[key]?.trim());
+    if (envCredential) {
+      return {
+        authenticated: true,
+        email: envCredential,
+        method: 'environment',
+      };
+    }
+
+    return {
+      authenticated: false,
+      email: null,
+      method: null,
+      error: 'OpenCode not configured',
+    };
+  }
+}
diff --git a/server/modules/providers/list/opencode/opencode-mcp.provider.ts b/server/modules/providers/list/opencode/opencode-mcp.provider.ts
new file mode 100644
index 00000000..f2020382
--- /dev/null
+++ b/server/modules/providers/list/opencode/opencode-mcp.provider.ts
@@ -0,0 +1,228 @@
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { McpProvider } from '@/modules/providers/shared/mcp/mcp.provider.js';
+import type { McpScope, ProviderMcpServer, UpsertProviderMcpServerInput } from '@/shared/types.js';
+import {
+  AppError,
+  readObjectRecord,
+  readOptionalString,
+  readStringArray,
+  readStringRecord,
+} from '@/shared/utils.js';
+
+type OpenCodeConfigPath = {
+  filePath: string;
+  exists: boolean;
+};
+
+const fileExists = async (filePath: string): Promise<boolean> => {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Removes JSONC comments without touching comment-like text inside strings.
+ */
+const stripJsonComments = (content: string): string => {
+  let output = '';
+  let inString = false;
+  let quote = '';
+  let escaped = false;
+
+  for (let index = 0; index < content.length; index += 1) {
+    const char = content[index];
+    const next = content[index + 1];
+
+    if (inString) {
+      output += char;
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === quote) {
+        inString = false;
+        quote = '';
+      }
+      continue;
+    }
+
+    if (char === '"' || char === '\'') {
+      inString = true;
+      quote = char;
+      output += char;
+      continue;
+    }
+
+    if (char === '/' && next === '/') {
+      while (index < content.length && content[index] !== '\n') {
+        index += 1;
+      }
+      output += '\n';
+      continue;
+    }
+
+    if (char === '/' && next === '*') {
+      index += 2;
+      while (index < content.length && !(content[index] === '*' && content[index + 1] === '/')) {
+        index += 1;
+      }
+      index += 1;
+      continue;
+    }
+
+    output += char;
+  }
+
+  return output;
+};
+
+const stripTrailingCommas = (content: string): string =>
+  content.replace(/,\s*([}\]])/g, '$1');
+
+const readOpenCodeConfig = async (filePath: string): Promise<Record<string, unknown>> => {
+  try {
+    const content = await readFile(filePath, 'utf8');
+    const parsed = JSON.parse(stripTrailingCommas(stripJsonComments(content))) as unknown;
+    return readObjectRecord(parsed) ?? {};
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') {
+      return {};
+    }
+
+    throw error;
+  }
+};
+
+const writeOpenCodeConfig = async (filePath: string, data: Record<string, unknown>): Promise<void> => {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+};
+
+const resolveOpenCodeConfigPath = async (scope: McpScope, workspacePath: string): Promise<OpenCodeConfigPath> => {
+  const root = scope === 'user'
+    ? path.join(os.homedir(), '.config', 'opencode')
+    : workspacePath;
+  const jsonPath = path.join(root, 'opencode.json');
+  const jsoncPath = path.join(root, 'opencode.jsonc');
+
+  if (await fileExists(jsonPath)) {
+    return { filePath: jsonPath, exists: true };
+  }
+
+  if (await fileExists(jsoncPath)) {
+    return { filePath: jsoncPath, exists: true };
+  }
+
+  return { filePath: jsonPath, exists: false };
+};
+
+export class OpenCodeMcpProvider extends McpProvider {
+  constructor() {
+    super('opencode', ['user', 'project'], ['stdio', 'http']);
+  }
+
+  protected async readScopedServers(scope: McpScope, workspacePath: string): Promise<Record<string, unknown>> {
+    const { filePath } = await resolveOpenCodeConfigPath(scope, workspacePath);
+    const config = await readOpenCodeConfig(filePath);
+    return readObjectRecord(config.mcp) ?? {};
+  }
+
+  protected async writeScopedServers(
+    scope: McpScope,
+    workspacePath: string,
+    servers: Record<string, unknown>,
+  ): Promise<void> {
+    const { filePath } = await resolveOpenCodeConfigPath(scope, workspacePath);
+    const config = await readOpenCodeConfig(filePath);
+    config.mcp = servers;
+    await writeOpenCodeConfig(filePath, config);
+  }
+
+  protected buildServerConfig(input: UpsertProviderMcpServerInput): Record<string, unknown> {
+    if (input.transport === 'stdio') {
+      if (!input.command?.trim()) {
+        throw new AppError('command is required for stdio MCP servers.', {
+          code: 'MCP_COMMAND_REQUIRED',
+          statusCode: 400,
+        });
+      }
+
+      return {
+        type: 'local',
+        command: [input.command, ...(input.args ?? [])],
+        enabled: true,
+        environment: input.env ?? {},
+      };
+    }
+
+    if (!input.url?.trim()) {
+      throw new AppError('url is required for http MCP servers.', {
+        code: 'MCP_URL_REQUIRED',
+        statusCode: 400,
+      });
+    }
+
+    return {
+      type: 'remote',
+      url: input.url,
+      enabled: true,
+      headers: input.headers ?? {},
+    };
+  }
+
+  protected normalizeServerConfig(
+    scope: McpScope,
+    name: string,
+    rawConfig: unknown,
+  ): ProviderMcpServer | null {
+    const config = readObjectRecord(rawConfig);
+    if (!config) {
+      return null;
+    }
+
+    if (config.type === 'local' || config.command !== undefined) {
+      const commandParts = typeof config.command === 'string'
+        ? [config.command, ...(readStringArray(config.args) ?? [])]
+        : readStringArray(config.command);
+      const command = commandParts?.[0];
+      if (!command) {
+        return null;
+      }
+
+      return {
+        provider: 'opencode',
+        name,
+        scope,
+        transport: 'stdio',
+        command,
+        args: commandParts.slice(1),
+        env: readStringRecord(config.environment) ?? readStringRecord(config.env),
+      };
+    }
+
+    if (config.type === 'remote' || typeof config.url === 'string') {
+      const url = readOptionalString(config.url);
+      if (!url) {
+        return null;
+      }
+
+      return {
+        provider: 'opencode',
+        name,
+        scope,
+        transport: 'http',
+        url,
+        headers: readStringRecord(config.headers),
+      };
+    }
+
+    return null;
+  }
+}
diff --git a/server/modules/providers/list/opencode/opencode-models.provider.ts b/server/modules/providers/list/opencode/opencode-models.provider.ts
new file mode 100644
index 00000000..0e5f7477
--- /dev/null
+++ b/server/modules/providers/list/opencode/opencode-models.provider.ts
@@ -0,0 +1,339 @@
+import { spawn } from 'node:child_process';
+
+import Database from 'better-sqlite3';
+import crossSpawn from 'cross-spawn';
+
+import type { IProviderModels } from '@/shared/interfaces.js';
+import type {
+  ProviderChangeActiveModelInput,
+  ProviderCurrentActiveModel,
+  ProviderModelOption,
+  ProviderModelsDefinition,
+  ProviderSessionActiveModelChange,
+} from '@/shared/types.js';
+import {
+  buildDefaultProviderCurrentActiveModel,
+  getOpenCodeDatabasePath,
+  readObjectRecord,
+  readOptionalString,
+  writeProviderSessionActiveModelChange,
+} from '@/shared/utils.js';
+
+export const OPENCODE_FALLBACK_MODELS: ProviderModelsDefinition = {
+  OPTIONS: [
+    {
+      value: 'anthropic/claude-sonnet-4-5',
+      label: 'Claude Sonnet 4.5',
+      description: 'anthropic - anthropic/claude-sonnet-4-5',
+    },
+    {
+      value: 'anthropic/claude-opus-4-1',
+      label: 'Claude Opus 4.1',
+      description: 'anthropic - anthropic/claude-opus-4-1',
+    },
+    {
+      value: 'anthropic/claude-haiku-4-5',
+      label: 'Claude Haiku 4.5',
+      description: 'anthropic - anthropic/claude-haiku-4-5',
+    },
+    {
+      value: 'openai/gpt-5.1',
+      label: 'GPT-5.1',
+      description: 'openai - openai/gpt-5.1',
+    },
+    {
+      value: 'openai/gpt-5.1-codex',
+      label: 'GPT-5.1 Codex',
+      description: 'openai - openai/gpt-5.1-codex',
+    },
+    {
+      value: 'openai/gpt-5.4-mini',
+      label: 'GPT-5.4 Mini',
+      description: 'openai - openai/gpt-5.4-mini',
+    },
+    {
+      value: 'google/gemini-2.5-pro',
+      label: 'Gemini 2.5 Pro',
+      description: 'google - google/gemini-2.5-pro',
+    },
+    {
+      value: 'google/gemini-2.5-flash',
+      label: 'Gemini 2.5 Flash',
+      description: 'google - google/gemini-2.5-flash',
+    },
+  ],
+  DEFAULT: 'anthropic/claude-sonnet-4-5',
+};
+
+const OPEN_CODE_MODELS_TIMEOUT_MS = 20_000;
+const MODEL_ID_LINE = /^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/i;
+const spawnFunction = process.platform === 'win32' ? crossSpawn : spawn;
+const DATE_TOKEN = /^\d{8}$/;
+const SIMPLE_NUMBER_TOKEN = /^\d$/;
+const VERSION_TOKEN = /^[a-z]\d+$/i;
+const NUMERIC_TOKEN = /^\d+(?:\.\d+)*$/;
+const SHORT_ACRONYM_TOKEN = /^[a-z]{2,3}$/;
+
+export const parseOpenCodeModelsStdout = (stdout: string): string[] => {
+  const ids: string[] = [];
+
+  for (const rawLine of stdout.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('{') || line.startsWith('[')) {
+      continue;
+    }
+
+    if (MODEL_ID_LINE.test(line)) {
+      ids.push(line);
+    }
+  }
+
+  return [...new Set(ids)];
+};
+
+const formatDateToken = (token: string): string => (
+  `${token.slice(0, 4)}-${token.slice(4, 6)}-${token.slice(6, 8)}`
+);
+
+const formatModelToken = (token: string, nextToken?: string): string => {
+  const lower = token.toLowerCase();
+
+  if (VERSION_TOKEN.test(token)) {
+    return token.toUpperCase();
+  }
+
+  if (SHORT_ACRONYM_TOKEN.test(lower) && nextToken && NUMERIC_TOKEN.test(nextToken)) {
+    return token.toUpperCase();
+  }
+
+  return lower.charAt(0).toUpperCase() + lower.slice(1);
+};
+
+const formatOpenCodeModelSlug = (slug: string): string => {
+  const labelParts: string[] = [];
+  const dateParts: string[] = [];
+  const tokens = slug.split('-').filter(Boolean);
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    const nextToken = tokens[index + 1];
+
+    if (DATE_TOKEN.test(token)) {
+      dateParts.push(formatDateToken(token));
+      continue;
+    }
+
+    if (SIMPLE_NUMBER_TOKEN.test(token) && nextToken && SIMPLE_NUMBER_TOKEN.test(nextToken)) {
+      labelParts.push(`${token}.${nextToken}`);
+      index += 1;
+      continue;
+    }
+
+    labelParts.push(formatModelToken(token, nextToken));
+  }
+
+  const label = (labelParts.join(' ').trim() || slug).replace(/^GPT\s+/, 'GPT-');
+  if (dateParts.length === 0) {
+    return label;
+  }
+
+  return `${label} (${dateParts.join(', ')})`;
+};
+
+const readOpenCodeModelParts = (id: string): { upstreamProvider: string; slug: string } => {
+  const separatorIndex = id.indexOf('/');
+  if (separatorIndex < 0) {
+    return {
+      upstreamProvider: '',
+      slug: id,
+    };
+  }
+
+  return {
+    upstreamProvider: id.slice(0, separatorIndex),
+    slug: id.slice(separatorIndex + 1),
+  };
+};
+
+const labelForOpenCodeModelId = (id: string): string => {
+  const fallbackLabel = OPENCODE_FALLBACK_MODELS.OPTIONS.find((option) => option.value === id)?.label;
+  if (fallbackLabel) {
+    return fallbackLabel;
+  }
+
+  const { slug } = readOpenCodeModelParts(id);
+  return formatOpenCodeModelSlug(slug);
+};
+
+const descriptionForOpenCodeModelId = (id: string): string => {
+  const { upstreamProvider } = readOpenCodeModelParts(id);
+  return upstreamProvider ? `${upstreamProvider} - ${id}` : id;
+};
+
+export const buildOpenCodeDefinitionFromIds = (ids: string[]): ProviderModelsDefinition => {
+  const options: ProviderModelOption[] = ids.map((value) => ({
+    value,
+    label: labelForOpenCodeModelId(value),
+    description: descriptionForOpenCodeModelId(value),
+  }));
+
+  const defaultValue = options.find((option) => option.value === OPENCODE_FALLBACK_MODELS.DEFAULT)?.value
+    ?? options[0]?.value
+    ?? OPENCODE_FALLBACK_MODELS.DEFAULT;
+
+  return {
+    OPTIONS: options,
+    DEFAULT: defaultValue,
+  };
+};
+
+const parseOpenCodeSessionModelValue = (rawModel: unknown): string | null => {
+  if (typeof rawModel === 'string') {
+    const trimmed = rawModel.trim();
+    if (!trimmed) {
+      return null;
+    }
+
+    try {
+      return parseOpenCodeSessionModelValue(JSON.parse(trimmed));
+    } catch {
+      return trimmed;
+    }
+  }
+
+  const record = readObjectRecord(rawModel);
+  if (!record) {
+    return null;
+  }
+
+  return readOptionalString(record.id)
+    ?? readOptionalString(record.model)
+    ?? readOptionalString(record.name)
+    ?? readOptionalString(record.value)
+    ?? null;
+};
+
+const runOpenCodeModelsCommand = (): Promise<string> => new Promise((resolve, reject) => {
+  const openCodeProcess = spawnFunction('opencode', ['models'], {
+    cwd: process.cwd(),
+    env: { ...process.env },
+  });
+
+  let stdout = '';
+  let stderr = '';
+  let settled = false;
+
+  const timer = setTimeout(() => {
+    openCodeProcess.kill('SIGTERM');
+    if (!settled) {
+      settled = true;
+      reject(new Error('opencode models timed out'));
+    }
+  }, OPEN_CODE_MODELS_TIMEOUT_MS);
+
+  const finish = (error: Error | null, output: string) => {
+    if (settled) {
+      return;
+    }
+
+    settled = true;
+    clearTimeout(timer);
+
+    if (error) {
+      reject(error);
+      return;
+    }
+
+    resolve(output);
+  };
+
+  openCodeProcess.stdout?.on('data', (chunk: Buffer) => {
+    stdout += chunk.toString();
+  });
+
+  openCodeProcess.stderr?.on('data', (chunk: Buffer) => {
+    stderr += chunk.toString();
+  });
+
+  openCodeProcess.on('error', (error) => {
+    finish(error instanceof Error ? error : new Error(String(error)), '');
+  });
+
+  openCodeProcess.on('close', (code) => {
+    if (code !== 0) {
+      finish(new Error(stderr.trim() || `opencode models exited with code ${code}`), '');
+      return;
+    }
+
+    finish(null, stdout);
+  });
+});
+
+export class OpenCodeProviderModels implements IProviderModels {
+  async getSupportedModels(): Promise<ProviderModelsDefinition> {
+    try {
+      const stdout = await runOpenCodeModelsCommand();
+      const ids = parseOpenCodeModelsStdout(stdout);
+      if (ids.length === 0) {
+        return OPENCODE_FALLBACK_MODELS;
+      }
+
+      return buildOpenCodeDefinitionFromIds(ids);
+    } catch {
+      return OPENCODE_FALLBACK_MODELS;
+    }
+  }
+
+  async getCurrentActiveModel(sessionId?: string): Promise<ProviderCurrentActiveModel> {
+    if (!sessionId?.trim()) {
+      return buildDefaultProviderCurrentActiveModel(await this.getSupportedModels());
+    }
+
+    try {
+      const dbPath = getOpenCodeDatabasePath();
+      const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+
+      try {
+        const row = db.prepare(`
+          SELECT
+            s.id AS sessionId,
+            s.model AS model,
+            s.agent AS agent,
+            s.directory AS directory,
+            s.time_updated AS timeUpdated,
+            s.time_created AS timeCreated
+          FROM session s
+          WHERE s.id = ?
+          ORDER BY COALESCE(s.time_updated, s.time_created, 0) DESC
+          LIMIT 1
+        `).get(sessionId) as {
+          sessionId?: string;
+          model?: unknown;
+          agent?: string | null;
+          directory?: string | null;
+          timeUpdated?: number | null;
+          timeCreated?: number | null;
+        } | undefined;
+
+        const model = parseOpenCodeSessionModelValue(row?.model);
+        if (model) {
+          return {
+            model,
+          };
+        }
+      } finally {
+        db.close();
+      }
+    } catch {
+      // Fall through to the provider default when OpenCode session lookup fails.
+    }
+
+    return buildDefaultProviderCurrentActiveModel(await this.getSupportedModels());
+  }
+
+  async changeActiveModel(
+    input: ProviderChangeActiveModelInput,
+  ): Promise<ProviderSessionActiveModelChange> {
+    return writeProviderSessionActiveModelChange('opencode', input);
+  }
+}
diff --git a/server/modules/providers/list/opencode/opencode-session-synchronizer.provider.ts b/server/modules/providers/list/opencode/opencode-session-synchronizer.provider.ts
new file mode 100644
index 00000000..bd9ad9fe
--- /dev/null
+++ b/server/modules/providers/list/opencode/opencode-session-synchronizer.provider.ts
@@ -0,0 +1,157 @@
+import fsSync from 'node:fs';
+import path from 'node:path';
+
+import Database from 'better-sqlite3';
+
+import { sessionsDb } from '@/modules/database/index.js';
+import type { IProviderSessionSynchronizer } from '@/shared/interfaces.js';
+import {
+  getOpenCodeDatabasePath,
+  normalizeProviderTimestamp,
+  normalizeSessionName,
+  readJsonRecord,
+  readOptionalString,
+} from '@/shared/utils.js';
+
+type OpenCodeSessionRow = {
+  id: string;
+  directory: string | null;
+  title: string | null;
+  time_created: number | null;
+  time_updated: number | null;
+  worktree: string | null;
+};
+
+type SynchronizeRowsResult = {
+  processed: number;
+  firstSessionId: string | null;
+};
+
+/**
+ * Session indexer for OpenCode's SQLite-backed session store.
+ */
+export class OpenCodeSessionSynchronizer implements IProviderSessionSynchronizer {
+  private readonly provider = 'opencode' as const;
+
+  /**
+   * Scans OpenCode's shared opencode.db and upserts active sessions into DB.
+   */
+  async synchronize(since?: Date): Promise<number> {
+    const result = this.synchronizeRows(since);
+    return result.processed;
+  }
+
+  /**
+   * Handles watcher changes for opencode.db.
+   */
+  async synchronizeFile(filePath: string): Promise<string | null> {
+    if (path.basename(filePath) !== 'opencode.db') {
+      return null;
+    }
+
+    const result = this.synchronizeRows(undefined, 1);
+    return result.firstSessionId;
+  }
+
+  private synchronizeRows(since?: Date, limit?: number): SynchronizeRowsResult {
+    const dbPath = getOpenCodeDatabasePath();
+    if (!fsSync.existsSync(dbPath)) {
+      return { processed: 0, firstSessionId: null };
+    }
+
+    const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    try {
+      const sinceMillis = since?.getTime() ?? null;
+      const limitClause = limit ? 'LIMIT ?' : '';
+      const params = limit ? [sinceMillis, sinceMillis, limit] : [sinceMillis, sinceMillis];
+      const rows = db.prepare(`
+        SELECT
+          s.id AS id,
+          s.directory AS directory,
+          s.title AS title,
+          s.time_created AS time_created,
+          s.time_updated AS time_updated,
+          p.worktree AS worktree
+        FROM session s
+        LEFT JOIN project p ON p.id = s.project_id
+        WHERE s.time_archived IS NULL
+          AND (? IS NULL OR COALESCE(s.time_updated, s.time_created, 0) >= ?)
+        ORDER BY COALESCE(s.time_updated, s.time_created, 0) DESC, s.id DESC
+        ${limitClause}
+      `).all(...params) as OpenCodeSessionRow[];
+
+      let processed = 0;
+      let firstSessionId: string | null = null;
+      for (const row of rows) {
+        const indexedSessionId = this.upsertSession(db, row);
+        if (!indexedSessionId) {
+          continue;
+        }
+
+        if (!firstSessionId) {
+          firstSessionId = indexedSessionId;
+        }
+        processed += 1;
+      }
+
+      return { processed, firstSessionId };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn('[OpenCodeProvider] Failed to synchronize sessions:', message);
+      return { processed: 0, firstSessionId: null };
+    } finally {
+      db.close();
+    }
+  }
+
+  private upsertSession(db: Database.Database, row: OpenCodeSessionRow): string | null {
+    const sessionId = readOptionalString(row.id);
+    const projectPath = readOptionalString(row.directory) ?? readOptionalString(row.worktree);
+    if (!sessionId || !projectPath) {
+      return null;
+    }
+
+    const fallbackTitle = 'Untitled OpenCode Session';
+    const existingSession = sessionsDb.getSessionById(sessionId);
+    const existingName = existingSession?.custom_name;
+    const nextName = existingName && existingName !== fallbackTitle
+      ? existingName
+      : readOptionalString(row.title) ?? this.readFirstUserText(db, sessionId);
+
+    // OpenCode stores every session in one shared sqlite database, so jsonl_path
+    // must stay null to avoid deleting opencode.db when one app session is removed.
+    sessionsDb.createSession(
+      sessionId,
+      this.provider,
+      projectPath,
+      normalizeSessionName(nextName, fallbackTitle),
+      normalizeProviderTimestamp(row.time_created),
+      normalizeProviderTimestamp(row.time_updated ?? row.time_created),
+      null,
+    );
+
+    return sessionId;
+  }
+
+  private readFirstUserText(db: Database.Database, sessionId: string): string | undefined {
+    try {
+      const row = db.prepare(`
+        SELECT p.data AS data
+        FROM message m
+        INNER JOIN part p
+          ON p.session_id = m.session_id
+         AND p.message_id = m.id
+        WHERE m.session_id = ?
+          AND json_extract(m.data, '$.role') = 'user'
+          AND json_extract(p.data, '$.type') = 'text'
+        ORDER BY COALESCE(m.time_created, 0), COALESCE(p.time_created, 0)
+        LIMIT 1
+      `).get(sessionId) as { data: string | null } | undefined;
+
+      const data = readJsonRecord(row?.data);
+      return readOptionalString(data?.text);
+    } catch {
+      return undefined;
+    }
+  }
+}
diff --git a/server/modules/providers/list/opencode/opencode-sessions.provider.ts b/server/modules/providers/list/opencode/opencode-sessions.provider.ts
new file mode 100644
index 00000000..5b7bcce7
--- /dev/null
+++ b/server/modules/providers/list/opencode/opencode-sessions.provider.ts
@@ -0,0 +1,506 @@
+import fsSync from 'node:fs';
+
+import Database from 'better-sqlite3';
+
+import type { IProviderSessions } from '@/shared/interfaces.js';
+import type { AnyRecord, FetchHistoryOptions, FetchHistoryResult, NormalizedMessage } from '@/shared/types.js';
+import {
+  createNormalizedMessage,
+  generateMessageId,
+  getOpenCodeDatabasePath,
+  normalizeProviderTimestamp,
+  readObjectRecord,
+  readJsonRecord,
+  readOptionalString,
+} from '@/shared/utils.js';
+
+const PROVIDER = 'opencode';
+
+type OpenCodeHistoryRow = {
+  message_id: string;
+  message_time_created: number | null;
+  message_data: string | null;
+  part_id: string | null;
+  part_time_created: number | null;
+  part_data: string | null;
+};
+
+type OpenCodeTokenTotals = {
+  inputTokens: number;
+  outputTokens: number;
+  reasoningTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+};
+
+const openOpenCodeDatabase = (): Database.Database | null => {
+  const dbPath = getOpenCodeDatabasePath();
+  if (!fsSync.existsSync(dbPath)) {
+    return null;
+  }
+
+  return new Database(dbPath, { readonly: true, fileMustExist: true });
+};
+
+const formatToolContent = (value: unknown): string => {
+  if (value === undefined || value === null) {
+    return '';
+  }
+
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+};
+
+/**
+ * OpenCode can persist the first prompt as a JSON string literal inside a text
+ * part, for example `"hello"` instead of `hello`. Decode only complete JSON
+ * string literals so normal assistant/user prose remains untouched.
+ */
+const unwrapJsonStringLiteral = (value: string): string => {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith('"') || !trimmed.endsWith('"')) {
+    return value;
+  }
+
+  try {
+    const parsed = JSON.parse(trimmed);
+    return typeof parsed === 'string' ? parsed : value;
+  } catch {
+    return value;
+  }
+};
+
+const extractText = (value: unknown): string => {
+  if (typeof value === 'string') {
+    return unwrapJsonStringLiteral(value);
+  }
+
+  const record = readObjectRecord(value);
+  const text = readOptionalString(record?.text)
+    ?? readOptionalString(record?.content)
+    ?? '';
+  return unwrapJsonStringLiteral(text);
+};
+
+const hasUserRole = (value: unknown): boolean => {
+  const record = readObjectRecord(value);
+  return readOptionalString(record?.role) === 'user';
+};
+
+const isUserTextEcho = (raw: AnyRecord): boolean => {
+  return readOptionalString(raw.role) === 'user'
+    || hasUserRole(raw.message)
+    || hasUserRole(raw.part);
+};
+
+const buildTokenUsage = (totals: OpenCodeTokenTotals | undefined): AnyRecord | undefined => {
+  if (!totals) {
+    return undefined;
+  }
+
+  const inputTokens = totals.inputTokens;
+  const displayInputTokens = inputTokens + totals.cacheReadTokens;
+  const outputTokens = totals.outputTokens;
+  const used = inputTokens
+    + outputTokens
+    + totals.reasoningTokens
+    + totals.cacheReadTokens
+    + totals.cacheWriteTokens;
+
+  if (used <= 0) {
+    return undefined;
+  }
+
+  return {
+    used,
+    inputTokens: displayInputTokens,
+    outputTokens,
+    breakdown: {
+      input: displayInputTokens,
+      output: outputTokens,
+    },
+  };
+};
+
+const readOpenCodeSessionColumnTokenUsage = (
+  db: Database.Database,
+  sessionId: string,
+): AnyRecord | undefined => {
+  const columns = db.prepare('PRAGMA table_info(session)').all() as { name: string }[];
+  const columnNames = new Set(columns.map((column) => column.name));
+  const requiredColumns = ['tokens_input', 'tokens_output', 'tokens_reasoning', 'tokens_cache_read', 'tokens_cache_write'];
+  if (!requiredColumns.every((column) => columnNames.has(column))) {
+    return undefined;
+  }
+
+  const row = db.prepare(`
+    SELECT
+      tokens_input AS inputTokens,
+      tokens_output AS outputTokens,
+      tokens_reasoning AS reasoningTokens,
+      tokens_cache_read AS cacheReadTokens,
+      tokens_cache_write AS cacheWriteTokens
+    FROM session
+    WHERE id = ?
+  `).get(sessionId) as OpenCodeTokenTotals | undefined;
+
+  if (!row) {
+    return undefined;
+  }
+
+  return buildTokenUsage({
+    inputTokens: Number(row.inputTokens ?? 0),
+    outputTokens: Number(row.outputTokens ?? 0),
+    reasoningTokens: Number(row.reasoningTokens ?? 0),
+    cacheReadTokens: Number(row.cacheReadTokens ?? 0),
+    cacheWriteTokens: Number(row.cacheWriteTokens ?? 0),
+  });
+};
+
+/**
+ * OpenCode stores per-message token counts on assistant `message.data` objects
+ * (see MessageV2.Assistant). Older DBs also had session-level counters; this
+ * matches current `opencode.db` layouts that only persist message JSON.
+ */
+const aggregateOpenCodeSessionTokenUsage = (
+  db: Database.Database,
+  sessionId: string,
+): AnyRecord | undefined => {
+  const sessionColumnUsage = readOpenCodeSessionColumnTokenUsage(db, sessionId);
+  if (sessionColumnUsage) {
+    return sessionColumnUsage;
+  }
+
+  const rows = db.prepare('SELECT data FROM message WHERE session_id = ?').all(sessionId) as { data: string }[];
+
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let reasoningTokens = 0;
+  let cacheReadTokens = 0;
+  let cacheWriteTokens = 0;
+
+  for (const row of rows) {
+    const info = readJsonRecord(row.data);
+    if (readOptionalString(info?.role) !== 'assistant') {
+      continue;
+    }
+
+    const tokens = readObjectRecord(info?.tokens);
+    if (!tokens) {
+      continue;
+    }
+
+    inputTokens += Number(tokens.input ?? 0);
+    outputTokens += Number(tokens.output ?? 0);
+    reasoningTokens += Number(tokens.reasoning ?? 0);
+    const cache = readObjectRecord(tokens.cache);
+    cacheReadTokens += Number(cache?.read ?? 0);
+    cacheWriteTokens += Number(cache?.write ?? 0);
+  }
+
+  return buildTokenUsage({
+    inputTokens,
+    outputTokens,
+    reasoningTokens,
+    cacheReadTokens,
+    cacheWriteTokens,
+  });
+};
+
+export class OpenCodeSessionsProvider implements IProviderSessions {
+  /**
+   * Normalizes live `opencode run --format json` events into frontend messages.
+   */
+  normalizeMessage(rawMessage: unknown, sessionId: string | null): NormalizedMessage[] {
+    const raw = readObjectRecord(rawMessage);
+    if (!raw) {
+      return [];
+    }
+
+    const type = readOptionalString(raw.type) ?? readOptionalString(raw.event);
+    const eventSessionId = readOptionalString(raw.sessionID) ?? readOptionalString(raw.sessionId) ?? sessionId;
+    const timestamp = normalizeProviderTimestamp(raw.time ?? raw.timestamp);
+    const baseId = readOptionalString(raw.id)
+      ?? readOptionalString(raw.messageID)
+      ?? generateMessageId('opencode');
+
+    if (type === 'text') {
+      // The client already renders an optimistic user bubble, so provider user
+      // echoes must not be streamed back as assistant text.
+      if (isUserTextEcho(raw)) {
+        return [];
+      }
+
+      const content = extractText(raw.text ?? raw.delta ?? raw.message);
+      if (!content.trim()) {
+        return [];
+      }
+
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId: eventSessionId,
+        timestamp,
+        provider: PROVIDER,
+        kind: 'stream_delta',
+        content,
+      })];
+    }
+
+    if (type === 'reasoning') {
+      const content = extractText(raw.text ?? raw.delta ?? raw.message);
+      if (!content.trim()) {
+        return [];
+      }
+
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId: eventSessionId,
+        timestamp,
+        provider: PROVIDER,
+        kind: 'thinking',
+        content,
+      })];
+    }
+
+    if (type === 'tool_use') {
+      const toolName = readOptionalString(raw.tool) ?? readOptionalString(raw.name) ?? 'Tool';
+      const toolId = readOptionalString(raw.callID) ?? readOptionalString(raw.toolCallId) ?? baseId;
+      const toolMessage = createNormalizedMessage({
+        id: baseId,
+        sessionId: eventSessionId,
+        timestamp,
+        provider: PROVIDER,
+        kind: 'tool_use',
+        toolName,
+        toolInput: raw.input ?? raw.arguments ?? {},
+        toolId,
+      });
+
+      if (raw.output !== undefined || raw.error !== undefined) {
+        toolMessage.toolResult = {
+          content: formatToolContent(raw.output ?? raw.error),
+          isError: raw.error !== undefined,
+        };
+      }
+
+      return [toolMessage];
+    }
+
+    if (type === 'error') {
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId: eventSessionId,
+        timestamp,
+        provider: PROVIDER,
+        kind: 'error',
+        content: readOptionalString(raw.error) ?? readOptionalString(raw.message) ?? 'Unknown OpenCode error',
+      })];
+    }
+
+    if (type === 'step_finish') {
+      return [createNormalizedMessage({
+        id: baseId,
+        sessionId: eventSessionId,
+        timestamp,
+        provider: PROVIDER,
+        kind: 'stream_end',
+      })];
+    }
+
+    return [];
+  }
+
+  /**
+   * Loads OpenCode history from the shared SQLite session database.
+   */
+  async fetchHistory(
+    sessionId: string,
+    options: FetchHistoryOptions = {},
+  ): Promise<FetchHistoryResult> {
+    const { limit = null, offset = 0 } = options;
+    const db = openOpenCodeDatabase();
+    if (!db) {
+      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
+    }
+
+    try {
+      const rows = db.prepare(`
+        SELECT
+          m.id AS message_id,
+          m.time_created AS message_time_created,
+          m.data AS message_data,
+          p.id AS part_id,
+          p.time_created AS part_time_created,
+          p.data AS part_data
+        FROM message m
+        LEFT JOIN part p
+          ON p.session_id = m.session_id
+         AND p.message_id = m.id
+        WHERE m.session_id = ?
+        ORDER BY
+          COALESCE(m.time_created, 0),
+          m.id,
+          COALESCE(p.time_created, 0),
+          p.id
+      `).all(sessionId) as OpenCodeHistoryRow[];
+
+      const normalized = this.normalizeHistoryRows(rows, sessionId);
+      const tokenUsage = aggregateOpenCodeSessionTokenUsage(db, sessionId);
+
+      const normalizedOffset = Math.max(0, offset);
+      const normalizedLimit = limit === null ? null : Math.max(0, limit);
+      const total = normalized.length;
+      const messages = normalizedLimit === null
+        ? normalized
+        : normalized.slice(
+            Math.max(0, total - normalizedOffset - normalizedLimit),
+            Math.max(0, total - normalizedOffset),
+          );
+
+      return {
+        messages,
+        total,
+        hasMore: normalizedLimit === null
+          ? false
+          : Math.max(0, total - normalizedOffset - normalizedLimit) > 0,
+        offset: normalizedOffset,
+        limit: normalizedLimit,
+        tokenUsage,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(`[OpenCodeProvider] Failed to load session ${sessionId}:`, message);
+      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
+    } finally {
+      db.close();
+    }
+  }
+
+  private normalizeHistoryRows(rows: OpenCodeHistoryRow[], sessionId: string): NormalizedMessage[] {
+    const normalized: NormalizedMessage[] = [];
+    const emittedMessageErrors = new Set<string>();
+
+    for (const row of rows) {
+      const timestamp = normalizeProviderTimestamp(row.part_time_created ?? row.message_time_created);
+      const baseId = `${row.message_id}_${row.part_id ?? normalized.length}`;
+      const messageInfo = readJsonRecord(row.message_data);
+      const messageRole = readOptionalString(messageInfo?.role);
+
+      if (
+        messageInfo
+        && messageRole === 'assistant'
+        && messageInfo.error != null
+        && !emittedMessageErrors.has(row.message_id)
+      ) {
+        emittedMessageErrors.add(row.message_id);
+        normalized.push(createNormalizedMessage({
+          id: `${baseId}_error`,
+          sessionId,
+          timestamp,
+          provider: PROVIDER,
+          kind: 'error',
+          content: formatToolContent(messageInfo.error),
+        }));
+      }
+
+      if (!row.part_id) {
+        continue;
+      }
+
+      const partData = readJsonRecord(row.part_data) ?? {};
+      const partType = readOptionalString(partData.type);
+      if (!partType) {
+        continue;
+      }
+
+      if (partType === 'text') {
+        const content = extractText(partData);
+        if (content.trim()) {
+          normalized.push(createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp,
+            provider: PROVIDER,
+            kind: 'text',
+            role: messageRole === 'user' ? 'user' : 'assistant',
+            content,
+          }));
+        }
+        continue;
+      }
+
+      if (partType === 'reasoning') {
+        const content = extractText(partData);
+        if (content.trim()) {
+          normalized.push(createNormalizedMessage({
+            id: baseId,
+            sessionId,
+            timestamp,
+            provider: PROVIDER,
+            kind: 'thinking',
+            content,
+          }));
+        }
+        continue;
+      }
+
+      if (partType === 'tool') {
+        const state = readObjectRecord(partData.state) ?? {};
+        const status = readOptionalString(state.status);
+        const toolMessage = createNormalizedMessage({
+          id: baseId,
+          sessionId,
+          timestamp,
+          provider: PROVIDER,
+          kind: 'tool_use',
+          toolName: readOptionalString(partData.tool) ?? 'Tool',
+          toolInput: state.input ?? partData.input ?? {},
+          toolId: readOptionalString(partData.callID) ?? row.part_id,
+        });
+
+        if (status === 'completed' || status === 'error') {
+          toolMessage.toolResult = {
+            content: formatToolContent(state.output ?? state.error),
+            isError: status === 'error',
+          };
+        }
+
+        normalized.push(toolMessage);
+        continue;
+      }
+
+      if (partType === 'step-finish') {
+        normalized.push(createNormalizedMessage({
+          id: baseId,
+          sessionId,
+          timestamp,
+          provider: PROVIDER,
+          kind: 'stream_end',
+        }));
+        continue;
+      }
+
+      if (partType === 'patch' || partType === 'agent') {
+        normalized.push(createNormalizedMessage({
+          id: baseId,
+          sessionId,
+          timestamp,
+          provider: PROVIDER,
+          kind: 'tool_use',
+          toolName: partType === 'patch' ? 'Patch' : 'Agent',
+          toolInput: partData,
+          toolId: row.part_id,
+        }));
+      }
+    }
+
+    return normalized;
+  }
+}
diff --git a/server/modules/providers/list/opencode/opencode-skills.provider.ts b/server/modules/providers/list/opencode/opencode-skills.provider.ts
new file mode 100644
index 00000000..599402ec
--- /dev/null
+++ b/server/modules/providers/list/opencode/opencode-skills.provider.ts
@@ -0,0 +1,78 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import { SkillsProvider } from '@/modules/providers/shared/skills/skills.provider.js';
+import type { ProviderSkillSource } from '@/shared/types.js';
+import {
+  addUniqueProviderSkillSource,
+  findTopmostGitRoot,
+} from '@/shared/utils.js';
+
+const OPENCODE_PROJECT_SKILL_DIRS = [
+  ['.opencode', 'skills'],
+  ['.claude', 'skills'],
+  ['.agents', 'skills'],
+];
+
+const OPENCODE_USER_SKILL_DIRS = [
+  ['.config', 'opencode', 'skills'],
+  ['.claude', 'skills'],
+  ['.agents', 'skills'],
+];
+
+export class OpenCodeSkillsProvider extends SkillsProvider {
+  constructor() {
+    super('opencode');
+  }
+
+  protected async getSkillSources(workspacePath: string): Promise<ProviderSkillSource[]> {
+    const sources: ProviderSkillSource[] = [];
+    const seenRootDirs = new Set<string>();
+    const repoRoot = await findTopmostGitRoot(workspacePath);
+
+    for (const projectRoot of this.getProjectSearchRoots(workspacePath, repoRoot)) {
+      for (const skillDir of OPENCODE_PROJECT_SKILL_DIRS) {
+        // OpenCode intentionally reads Claude and Agents skill folders so users
+        // can reuse the same skill libraries across compatible coding agents.
+        addUniqueProviderSkillSource(sources, seenRootDirs, {
+          scope: 'project',
+          rootDir: path.join(projectRoot, ...skillDir),
+          commandPrefix: '/',
+        });
+      }
+    }
+
+    for (const skillDir of OPENCODE_USER_SKILL_DIRS) {
+      addUniqueProviderSkillSource(sources, seenRootDirs, {
+        scope: 'user',
+        rootDir: path.join(os.homedir(), ...skillDir),
+        commandPrefix: '/',
+      });
+    }
+
+    return sources;
+  }
+
+  private getProjectSearchRoots(workspacePath: string, repoRoot: string | null): string[] {
+    const roots: string[] = [];
+    const normalizedWorkspacePath = path.resolve(workspacePath);
+    const normalizedRepoRoot = repoRoot ? path.resolve(repoRoot) : null;
+    let currentPath = normalizedWorkspacePath;
+
+    while (true) {
+      roots.push(currentPath);
+      if (!normalizedRepoRoot || currentPath === normalizedRepoRoot) {
+        break;
+      }
+
+      const parentPath = path.dirname(currentPath);
+      if (parentPath === currentPath) {
+        break;
+      }
+
+      currentPath = parentPath;
+    }
+
+    return roots;
+  }
+}
diff --git a/server/modules/providers/list/opencode/opencode.provider.ts b/server/modules/providers/list/opencode/opencode.provider.ts
new file mode 100644
index 00000000..38f0efd1
--- /dev/null
+++ b/server/modules/providers/list/opencode/opencode.provider.ts
@@ -0,0 +1,27 @@
+import { OpenCodeProviderAuth } from '@/modules/providers/list/opencode/opencode-auth.provider.js';
+import { OpenCodeProviderModels } from '@/modules/providers/list/opencode/opencode-models.provider.js';
+import { OpenCodeMcpProvider } from '@/modules/providers/list/opencode/opencode-mcp.provider.js';
+import { OpenCodeSessionSynchronizer } from '@/modules/providers/list/opencode/opencode-session-synchronizer.provider.js';
+import { OpenCodeSessionsProvider } from '@/modules/providers/list/opencode/opencode-sessions.provider.js';
+import { OpenCodeSkillsProvider } from '@/modules/providers/list/opencode/opencode-skills.provider.js';
+import { AbstractProvider } from '@/modules/providers/shared/base/abstract.provider.js';
+import type {
+  IProviderAuth,
+  IProviderModels,
+  IProviderSessionSynchronizer,
+  IProviderSkills,
+  IProviderSessions,
+} from '@/shared/interfaces.js';
+
+export class OpenCodeProvider extends AbstractProvider {
+  readonly models: IProviderModels = new OpenCodeProviderModels();
+  readonly mcp = new OpenCodeMcpProvider();
+  readonly auth: IProviderAuth = new OpenCodeProviderAuth();
+  readonly skills: IProviderSkills = new OpenCodeSkillsProvider();
+  readonly sessions: IProviderSessions = new OpenCodeSessionsProvider();
+  readonly sessionSynchronizer: IProviderSessionSynchronizer = new OpenCodeSessionSynchronizer();
+
+  constructor() {
+    super('opencode');
+  }
+}
diff --git a/server/modules/providers/provider.registry.ts b/server/modules/providers/provider.registry.ts
index 2f959b22..a9f0d26b 100644
--- a/server/modules/providers/provider.registry.ts
+++ b/server/modules/providers/provider.registry.ts
@@ -2,6 +2,7 @@ import { ClaudeProvider } from '@/modules/providers/list/claude/claude.provider.
 import { CodexProvider } from '@/modules/providers/list/codex/codex.provider.js';
 import { CursorProvider } from '@/modules/providers/list/cursor/cursor.provider.js';
 import { GeminiProvider } from '@/modules/providers/list/gemini/gemini.provider.js';
+import { OpenCodeProvider } from '@/modules/providers/list/opencode/opencode.provider.js';
 import type { IProvider } from '@/shared/interfaces.js';
 import type { LLMProvider } from '@/shared/types.js';
 import { AppError } from '@/shared/utils.js';
@@ -11,6 +12,7 @@ const providers: Record<LLMProvider, IProvider> = {
   codex: new CodexProvider(),
   cursor: new CursorProvider(),
   gemini: new GeminiProvider(),
+  opencode: new OpenCodeProvider(),
 };
 
 /**
diff --git a/server/modules/providers/provider.routes.ts b/server/modules/providers/provider.routes.ts
index 895aba84..2604fcc8 100644
--- a/server/modules/providers/provider.routes.ts
+++ b/server/modules/providers/provider.routes.ts
@@ -2,7 +2,17 @@ import express, { type Request, type Response } from 'express';
 
 import { providerAuthService } from '@/modules/providers/services/provider-auth.service.js';
 import { providerMcpService } from '@/modules/providers/services/mcp.service.js';
-import type { LLMProvider, McpScope, McpTransport, UpsertProviderMcpServerInput } from '@/shared/types.js';
+import { providerModelsService } from '@/modules/providers/services/provider-models.service.js';
+import { providerSkillsService } from '@/modules/providers/services/skills.service.js';
+import { sessionConversationsSearchService } from '@/modules/providers/services/session-conversations-search.service.js';
+import { sessionsService } from '@/modules/providers/services/sessions.service.js';
+import type {
+  LLMProvider,
+  McpScope,
+  McpTransport,
+  ProviderChangeActiveModelInput,
+  UpsertProviderMcpServerInput,
+} from '@/shared/types.js';
 import { AppError, asyncHandler, createApiSuccessResponse } from '@/shared/utils.js';
 
 const router = express.Router();
@@ -25,6 +35,20 @@ const readPathParam = (value: unknown, name: string): string => {
 const normalizeProviderParam = (value: unknown): string =>
   readPathParam(value, 'provider').trim().toLowerCase();
 
+const SESSION_ID_PATTERN = /^[a-zA-Z0-9._-]{1,120}$/;
+
+const parseSessionId = (value: unknown): string => {
+  const sessionId = readPathParam(value, 'sessionId').trim();
+  if (!SESSION_ID_PATTERN.test(sessionId)) {
+    throw new AppError('Invalid sessionId.', {
+      code: 'INVALID_SESSION_ID',
+      statusCode: 400,
+    });
+  }
+
+  return sessionId;
+};
+
 const readOptionalQueryString = (value: unknown): string | undefined => {
   if (typeof value !== 'string') {
     return undefined;
@@ -34,6 +58,29 @@ const readOptionalQueryString = (value: unknown): string | undefined => {
   return normalized.length > 0 ? normalized : undefined;
 };
 
+const parseOptionalBooleanQuery = (value: unknown, name: string): boolean | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const normalized = readOptionalQueryString(value);
+  if (!normalized) {
+    return undefined;
+  }
+
+  if (normalized === 'true') {
+    return true;
+  }
+  if (normalized === 'false') {
+    return false;
+  }
+
+  throw new AppError(`${name} must be "true" or "false".`, {
+    code: 'INVALID_QUERY_PARAMETER',
+    statusCode: 400,
+  });
+};
+
 const parseMcpScope = (value: unknown): McpScope | undefined => {
   if (value === undefined) {
     return undefined;
@@ -103,19 +150,19 @@ const parseMcpUpsertPayload = (payload: unknown): UpsertProviderMcpServerInput =
     args: Array.isArray(body.args) ? body.args.filter((entry): entry is string => typeof entry === 'string') : undefined,
     env: typeof body.env === 'object' && body.env !== null
       ? Object.fromEntries(
-          Object.entries(body.env as Record<string, unknown>).filter(
-            (entry): entry is [string, string] => typeof entry[1] === 'string',
-          ),
-        )
+        Object.entries(body.env as Record<string, unknown>).filter(
+          (entry): entry is [string, string] => typeof entry[1] === 'string',
+        ),
+      )
       : undefined,
     cwd: readOptionalQueryString(body.cwd),
     url: readOptionalQueryString(body.url),
     headers: typeof body.headers === 'object' && body.headers !== null
       ? Object.fromEntries(
-          Object.entries(body.headers as Record<string, unknown>).filter(
-            (entry): entry is [string, string] => typeof entry[1] === 'string',
-          ),
-        )
+        Object.entries(body.headers as Record<string, unknown>).filter(
+          (entry): entry is [string, string] => typeof entry[1] === 'string',
+        ),
+      )
       : undefined,
     envVars: Array.isArray(body.envVars)
       ? body.envVars.filter((entry): entry is string => typeof entry === 'string')
@@ -123,17 +170,23 @@ const parseMcpUpsertPayload = (payload: unknown): UpsertProviderMcpServerInput =
     bearerTokenEnvVar: readOptionalQueryString(body.bearerTokenEnvVar),
     envHttpHeaders: typeof body.envHttpHeaders === 'object' && body.envHttpHeaders !== null
       ? Object.fromEntries(
-          Object.entries(body.envHttpHeaders as Record<string, unknown>).filter(
-            (entry): entry is [string, string] => typeof entry[1] === 'string',
-          ),
-        )
+        Object.entries(body.envHttpHeaders as Record<string, unknown>).filter(
+          (entry): entry is [string, string] => typeof entry[1] === 'string',
+        ),
+      )
       : undefined,
   };
 };
 
 const parseProvider = (value: unknown): LLMProvider => {
   const normalized = normalizeProviderParam(value);
-  if (normalized === 'claude' || normalized === 'codex' || normalized === 'cursor' || normalized === 'gemini') {
+  if (
+    normalized === 'claude'
+    || normalized === 'codex'
+    || normalized === 'cursor'
+    || normalized === 'gemini'
+    || normalized === 'opencode'
+  ) {
     return normalized;
   }
 
@@ -143,6 +196,85 @@ const parseProvider = (value: unknown): LLMProvider => {
   });
 };
 
+const parseSessionRenameSummary = (payload: unknown): string => {
+  if (!payload || typeof payload !== 'object') {
+    throw new AppError('Request body must be an object.', {
+      code: 'INVALID_REQUEST_BODY',
+      statusCode: 400,
+    });
+  }
+
+  const body = payload as Record<string, unknown>;
+  const summary = typeof body.summary === 'string' ? body.summary.trim() : '';
+  if (!summary) {
+    throw new AppError('Summary is required.', {
+      code: 'INVALID_SESSION_SUMMARY',
+      statusCode: 400,
+    });
+  }
+
+  if (summary.length > 500) {
+    throw new AppError('Summary must not exceed 500 characters.', {
+      code: 'INVALID_SESSION_SUMMARY',
+      statusCode: 400,
+    });
+  }
+
+  return summary;
+};
+
+const parseSessionSearchQuery = (value: unknown): string => {
+  const query = readOptionalQueryString(value) ?? '';
+  if (query.length < 2) {
+    throw new AppError('Query must be at least 2 characters', {
+      code: 'INVALID_SEARCH_QUERY',
+      statusCode: 400,
+    });
+  }
+
+  return query;
+};
+
+const parseSessionSearchLimit = (value: unknown): number => {
+  const raw = readOptionalQueryString(value);
+  if (!raw) {
+    return 50;
+  }
+
+  const parsed = Number.parseInt(raw, 10);
+  if (Number.isNaN(parsed)) {
+    throw new AppError('limit must be a valid integer.', {
+      code: 'INVALID_QUERY_PARAMETER',
+      statusCode: 400,
+    });
+  }
+
+  return Math.max(1, Math.min(parsed, 100));
+};
+
+const parseChangeActiveModelPayload = (payload: unknown): ProviderChangeActiveModelInput => {
+  if (!payload || typeof payload !== 'object') {
+    throw new AppError('Request body must be an object.', {
+      code: 'INVALID_REQUEST_BODY',
+      statusCode: 400,
+    });
+  }
+
+  const body = payload as Record<string, unknown>;
+  const model = readOptionalQueryString(body.model);
+  if (!model) {
+    throw new AppError('model is required.', {
+      code: 'MODEL_REQUIRED',
+      statusCode: 400,
+    });
+  }
+
+  return {
+    sessionId: '',
+    model,
+  };
+};
+
 router.get(
   '/:provider/auth/status',
   asyncHandler(async (req: Request, res: Response) => {
@@ -152,6 +284,42 @@ router.get(
   }),
 );
 
+router.get(
+  '/:provider/models',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const bypassCache = parseOptionalBooleanQuery(req.query.bypassCache, 'bypassCache') ?? false;
+    const result = await providerModelsService.getProviderModels(provider, { bypassCache });
+    res.json(createApiSuccessResponse({ provider, models: result.models, cache: result.cache }));
+  }),
+);
+
+router.post(
+  '/:provider/sessions/:sessionId/active-model',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const sessionId = parseSessionId(req.params.sessionId);
+    const payload = parseChangeActiveModelPayload(req.body);
+    const result = await providerModelsService.changeActiveModel(provider, {
+      ...payload,
+      sessionId,
+    });
+    res.json(createApiSuccessResponse(result));
+  }),
+);
+
+// ----------------- Skills routes -----------------
+router.get(
+  '/:provider/skills',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const workspacePath = readOptionalQueryString(req.query.workspacePath);
+    const skills = await providerSkillsService.listProviderSkills(provider, { workspacePath });
+    res.json(createApiSuccessResponse({ provider, skills }));
+  }),
+);
+
+// ----------------- MCP routes -----------------
 router.get(
   '/:provider/mcp/servers',
   asyncHandler(async (req: Request, res: Response) => {
@@ -214,4 +382,137 @@ router.post(
   }),
 );
 
+// ----------------- Session routes -----------------
+router.get(
+  '/sessions/archived',
+  asyncHandler(async (_req: Request, res: Response) => {
+    const sessions = sessionsService.listArchivedSessions();
+    res.json(createApiSuccessResponse({ sessions }));
+  }),
+);
+
+router.delete(
+  '/sessions/:sessionId',
+  asyncHandler(async (req: Request, res: Response) => {
+    const sessionId = parseSessionId(req.params.sessionId);
+    const force = parseOptionalBooleanQuery(req.query.force, 'force') ?? false;
+    const deletedFromDisk = parseOptionalBooleanQuery(req.query.deletedFromDisk, 'deletedFromDisk') ?? force;
+    const result = await sessionsService.deleteOrArchiveSessionById(sessionId, {
+      force,
+      deletedFromDisk,
+    });
+    res.json(createApiSuccessResponse(result));
+  }),
+);
+
+router.post(
+  '/sessions/:sessionId/restore',
+  asyncHandler(async (req: Request, res: Response) => {
+    const sessionId = parseSessionId(req.params.sessionId);
+    const result = sessionsService.restoreSessionById(sessionId);
+    res.json(createApiSuccessResponse(result));
+  }),
+);
+
+router.put(
+  '/sessions/:sessionId',
+  asyncHandler(async (req: Request, res: Response) => {
+    const sessionId = parseSessionId(req.params.sessionId);
+    const summary = parseSessionRenameSummary(req.body);
+    const result = sessionsService.renameSessionById(sessionId, summary);
+    res.json(createApiSuccessResponse(result));
+  }),
+);
+
+router.get(
+  '/sessions/:sessionId/messages',
+  asyncHandler(async (req: Request, res: Response) => {
+    const sessionId = parseSessionId(req.params.sessionId);
+    const limitRaw = readOptionalQueryString(req.query.limit);
+    const offsetRaw = readOptionalQueryString(req.query.offset);
+
+    let limit: number | null = null;
+    if (limitRaw !== undefined) {
+      const parsedLimit = Number.parseInt(limitRaw, 10);
+      if (Number.isNaN(parsedLimit) || parsedLimit < 0) {
+        throw new AppError('limit must be a non-negative integer.', {
+          code: 'INVALID_QUERY_PARAMETER',
+          statusCode: 400,
+        });
+      }
+      limit = parsedLimit;
+    }
+
+    let offset = 0;
+    if (offsetRaw !== undefined) {
+      const parsedOffset = Number.parseInt(offsetRaw, 10);
+      if (Number.isNaN(parsedOffset) || parsedOffset < 0) {
+        throw new AppError('offset must be a non-negative integer.', {
+          code: 'INVALID_QUERY_PARAMETER',
+          statusCode: 400,
+        });
+      }
+      offset = parsedOffset;
+    }
+
+    const result = await sessionsService.fetchHistory(sessionId, {
+      limit,
+      offset,
+    });
+    res.json(result);
+  }),
+);
+
+router.get('/search/sessions', asyncHandler(async (req: Request, res: Response) => {
+  const query = parseSessionSearchQuery(req.query.q);
+  const limit = parseSessionSearchLimit(req.query.limit);
+
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+    'X-Accel-Buffering': 'no',
+  });
+
+  let closed = false;
+  const abortController = new AbortController();
+  req.on('close', () => {
+    closed = true;
+    abortController.abort();
+  });
+
+  try {
+    await sessionConversationsSearchService.search({
+      query,
+      limit,
+      signal: abortController.signal,
+      onProgress: ({ projectResult, totalMatches, scannedProjects, totalProjects }) => {
+        if (closed) {
+          return;
+        }
+
+        if (projectResult) {
+          res.write(`event: result\ndata: ${JSON.stringify({ projectResult, totalMatches, scannedProjects, totalProjects })}\n\n`);
+          return;
+        }
+
+        res.write(`event: progress\ndata: ${JSON.stringify({ totalMatches, scannedProjects, totalProjects })}\n\n`);
+      },
+    });
+
+    if (!closed) {
+      res.write('event: done\ndata: {}\n\n');
+    }
+  } catch (error) {
+    console.error('Error searching conversations:', error);
+    if (!closed) {
+      res.write(`event: error\ndata: ${JSON.stringify({ error: 'Search failed' })}\n\n`);
+    }
+  } finally {
+    if (!closed) {
+      res.end();
+    }
+  }
+}));
+
 export default router;
diff --git a/server/modules/providers/services/mcp.service.ts b/server/modules/providers/services/mcp.service.ts
index bffb52de..da7a5665 100644
--- a/server/modules/providers/services/mcp.service.ts
+++ b/server/modules/providers/services/mcp.service.ts
@@ -1,18 +1,7 @@
-import os from 'node:os';
-
 import { providerRegistry } from '@/modules/providers/provider.registry.js';
 import type { LLMProvider, McpScope, ProviderMcpServer, UpsertProviderMcpServerInput } from '@/shared/types.js';
 import { AppError } from '@/shared/utils.js';
 
-/** Cursor MCP is not supported on Windows hosts (no Cursor CLI integration). */
-function includeProviderInGlobalMcp(providerId: LLMProvider): boolean {
-  if (providerId === 'cursor' && os.platform() === 'win32') {
-    return false;
-  }
-
-  return true;
-}
-
 
 export const providerMcpService = {
   /**
@@ -75,7 +64,7 @@ export const providerMcpService = {
 
     const scope = input.scope ?? 'project';
     const results: Array<{ provider: LLMProvider; created: boolean; error?: string }> = [];
-    const providers = providerRegistry.listProviders().filter((p) => includeProviderInGlobalMcp(p.id));
+    const providers = providerRegistry.listProviders();
     for (const provider of providers) {
       try {
         await provider.mcp.upsertServer({ ...input, scope });
diff --git a/server/modules/providers/services/provider-models.service.ts b/server/modules/providers/services/provider-models.service.ts
new file mode 100644
index 00000000..5cb62433
--- /dev/null
+++ b/server/modules/providers/services/provider-models.service.ts
@@ -0,0 +1,325 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { providerRegistry } from '@/modules/providers/provider.registry.js';
+import type { IProvider } from '@/shared/interfaces.js';
+import type {
+  LLMProvider,
+  ProviderChangeActiveModelInput,
+  ProviderCurrentActiveModel,
+  ProviderModelsCacheInfo,
+  ProviderModelsDefinition,
+  ProviderModelsResult,
+  ProviderSessionActiveModelChange,
+} from '@/shared/types.js';
+import { readProviderSessionActiveModelChange } from '@/shared/utils.js';
+
+export const PROVIDER_MODELS_CACHE_TTL_MS = 3 * 24 * 60 * 60 * 1000;
+const PROVIDER_MODELS_CACHE_VERSION = 1;
+
+type ProviderModelsServiceDependencies = {
+  resolveProvider?: (provider: LLMProvider) => Pick<IProvider, 'models'>;
+  cachePath?: string;
+  activeModelChangesPath?: string;
+  now?: () => number;
+};
+
+type ProviderModelsOptions = {
+  bypassCache?: boolean;
+};
+
+type ProviderModelsCacheEntry = {
+  updatedAt: number;
+  expiresAt: number;
+  models: ProviderModelsDefinition;
+};
+
+type ProviderModelsCacheFile = {
+  version: number;
+  entries: Record<string, ProviderModelsCacheEntry>;
+};
+
+const getProviderModelsCachePath = (): string => path.join(
+  os.homedir(),
+  '.cloudcli',
+  'provider-models-cache.json',
+);
+
+const toProviderModelsCacheInfo = (
+  entry: ProviderModelsCacheEntry,
+  source: ProviderModelsCacheInfo['source'],
+): ProviderModelsCacheInfo => ({
+  updatedAt: new Date(entry.updatedAt).toISOString(),
+  expiresAt: new Date(entry.expiresAt).toISOString(),
+  source,
+});
+
+const isProviderModelOption = (
+  value: unknown,
+): value is ProviderModelsDefinition['OPTIONS'][number] => (
+  Boolean(value)
+  && typeof value === 'object'
+  && typeof (value as ProviderModelsDefinition['OPTIONS'][number]).value === 'string'
+  && typeof (value as ProviderModelsDefinition['OPTIONS'][number]).label === 'string'
+  && (
+    typeof (value as ProviderModelsDefinition['OPTIONS'][number]).description === 'undefined'
+    || typeof (value as ProviderModelsDefinition['OPTIONS'][number]).description === 'string'
+  )
+);
+
+const isProviderModelsDefinition = (value: unknown): value is ProviderModelsDefinition => (
+  Boolean(value)
+  && typeof value === 'object'
+  && Array.isArray((value as ProviderModelsDefinition).OPTIONS)
+  && (value as ProviderModelsDefinition).OPTIONS.every(isProviderModelOption)
+  && typeof (value as ProviderModelsDefinition).DEFAULT === 'string'
+);
+
+const isProviderModelsCacheEntry = (value: unknown): value is ProviderModelsCacheEntry => (
+  Boolean(value)
+  && typeof value === 'object'
+  && typeof (value as ProviderModelsCacheEntry).updatedAt === 'number'
+  && typeof (value as ProviderModelsCacheEntry).expiresAt === 'number'
+  && isProviderModelsDefinition((value as ProviderModelsCacheEntry).models)
+);
+
+const readProviderModelsCacheFile = async (
+  cachePath: string,
+): Promise<ProviderModelsCacheFile | null> => {
+  try {
+    const raw = await readFile(cachePath, 'utf8');
+    const parsed = JSON.parse(raw) as Partial<ProviderModelsCacheFile>;
+    if (parsed.version !== PROVIDER_MODELS_CACHE_VERSION || !parsed.entries || typeof parsed.entries !== 'object') {
+      return null;
+    }
+
+    const entries = Object.fromEntries(
+      Object.entries(parsed.entries).filter((entry): entry is [string, ProviderModelsCacheEntry] =>
+        isProviderModelsCacheEntry(entry[1]),
+      ),
+    );
+
+    return {
+      version: PROVIDER_MODELS_CACHE_VERSION,
+      entries,
+    };
+  } catch {
+    return null;
+  }
+};
+
+const writeProviderModelsCacheFile = async (
+  cachePath: string,
+  entries: Map<LLMProvider, ProviderModelsCacheEntry>,
+  now: number,
+): Promise<void> => {
+  const serializableEntries = Object.fromEntries(
+    [...entries.entries()].filter(([, entry]) => entry.expiresAt > now),
+  );
+  const payload: ProviderModelsCacheFile = {
+    version: PROVIDER_MODELS_CACHE_VERSION,
+    entries: serializableEntries,
+  };
+
+  await mkdir(path.dirname(cachePath), { recursive: true });
+  await writeFile(cachePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+};
+
+/**
+ * Provider model lookup service.
+ *
+ * Routes and other service callers use this layer instead of resolving provider
+ * classes directly so the provider-registry dependency stays centralized in one
+ * place.
+ */
+export const createProviderModelsService = (dependencies: ProviderModelsServiceDependencies = {}) => {
+  const resolveProvider = dependencies.resolveProvider ?? providerRegistry.resolveProvider;
+  const cachePath = dependencies.cachePath ?? getProviderModelsCachePath();
+  const activeModelChangesPath = dependencies.activeModelChangesPath;
+  const now = dependencies.now ?? (() => Date.now());
+  const memoryCache = new Map<LLMProvider, ProviderModelsCacheEntry>();
+  const pendingRequests = new Map<LLMProvider, Promise<ProviderModelsResult>>();
+  let persistedCacheLoaded = false;
+  let persistedCacheLoadPromise: Promise<void> | null = null;
+
+  const pruneExpiredMemoryEntry = (
+    provider: LLMProvider,
+    currentTime: number,
+    source: ProviderModelsCacheInfo['source'],
+  ): ProviderModelsResult | null => {
+    const cachedEntry = memoryCache.get(provider);
+    if (!cachedEntry) {
+      return null;
+    }
+
+    if (cachedEntry.expiresAt > currentTime) {
+      return {
+        models: cachedEntry.models,
+        cache: toProviderModelsCacheInfo(cachedEntry, source),
+      };
+    }
+
+    memoryCache.delete(provider);
+    return null;
+  };
+
+  const loadPersistedCache = async (): Promise<void> => {
+    if (persistedCacheLoaded) {
+      return;
+    }
+
+    if (!persistedCacheLoadPromise) {
+      persistedCacheLoadPromise = (async () => {
+        const cacheFile = await readProviderModelsCacheFile(cachePath);
+        const currentTime = now();
+
+        for (const [provider, entry] of Object.entries(cacheFile?.entries ?? {})) {
+          if (entry.expiresAt > currentTime) {
+            memoryCache.set(provider as LLMProvider, entry);
+          }
+        }
+
+        persistedCacheLoaded = true;
+      })().finally(() => {
+        persistedCacheLoadPromise = null;
+      });
+    }
+
+    await persistedCacheLoadPromise;
+  };
+
+  const persistCache = async (): Promise<void> => {
+    try {
+      await writeProviderModelsCacheFile(cachePath, memoryCache, now());
+    } catch (error) {
+      console.warn('Unable to persist provider models cache:', error);
+    }
+  };
+
+  const setCacheEntry = async (
+    provider: LLMProvider,
+    models: ProviderModelsDefinition,
+  ): Promise<ProviderModelsCacheEntry> => {
+    const currentTime = now();
+    const entry: ProviderModelsCacheEntry = {
+      updatedAt: currentTime,
+      expiresAt: currentTime + PROVIDER_MODELS_CACHE_TTL_MS,
+      models,
+    };
+
+    memoryCache.set(provider, entry);
+    await persistCache();
+    return entry;
+  };
+
+  const loadAndCacheModels = (
+    provider: LLMProvider,
+  ): Promise<ProviderModelsResult> => {
+    const request = resolveProvider(provider).models.getSupportedModels()
+      .then(async (models) => {
+        const entry = await setCacheEntry(provider, models);
+        return {
+          models,
+          cache: toProviderModelsCacheInfo(entry, 'fresh'),
+        };
+      })
+      .finally(() => {
+        pendingRequests.delete(provider);
+      });
+
+    pendingRequests.set(provider, request);
+    return request;
+  };
+
+  const getProviderModels = async (
+    provider: LLMProvider,
+    options: ProviderModelsOptions = {},
+  ): Promise<ProviderModelsResult> => {
+    if (options.bypassCache) {
+      const pendingRequest = pendingRequests.get(provider);
+      if (pendingRequest) {
+        return pendingRequest;
+      }
+
+      return loadAndCacheModels(provider);
+    }
+
+    const cachedModels = pruneExpiredMemoryEntry(provider, now(), 'memory');
+    if (cachedModels) {
+      return cachedModels;
+    }
+
+    const pendingRequest = pendingRequests.get(provider);
+    if (pendingRequest) {
+      return pendingRequest;
+    }
+
+    await loadPersistedCache();
+
+    const persistedModels = pruneExpiredMemoryEntry(provider, now(), 'disk');
+    if (persistedModels) {
+      return persistedModels;
+    }
+
+    const postLoadPendingRequest = pendingRequests.get(provider);
+    if (postLoadPendingRequest) {
+      return postLoadPendingRequest;
+    }
+
+    return loadAndCacheModels(provider);
+  };
+
+  const getCurrentActiveModel = async (
+    provider: LLMProvider,
+    sessionId?: string,
+  ): Promise<ProviderCurrentActiveModel> => resolveProvider(provider).models.getCurrentActiveModel(sessionId);
+
+  const changeActiveModel = async (
+    provider: LLMProvider,
+    input: ProviderChangeActiveModelInput,
+  ): Promise<ProviderSessionActiveModelChange> => resolveProvider(provider).models.changeActiveModel(input);
+
+  const getChangedActiveModel = async (
+    provider: LLMProvider,
+    sessionId: string,
+  ): Promise<ProviderSessionActiveModelChange> => readProviderSessionActiveModelChange(provider, sessionId, {
+    filePath: activeModelChangesPath,
+  });
+
+  const resolveResumeModel = async (
+    provider: LLMProvider,
+    sessionId: string | undefined,
+    requestedModel?: string | null,
+  ): Promise<string | undefined> => {
+    const normalizedRequestedModel = typeof requestedModel === 'string' ? requestedModel.trim() : '';
+    if (!sessionId?.trim()) {
+      return normalizedRequestedModel || undefined;
+    }
+
+    const changedModel = await getChangedActiveModel(provider, sessionId);
+    if (changedModel.supported && changedModel.changed && changedModel.model?.trim()) {
+      return changedModel.model.trim();
+    }
+
+    return normalizedRequestedModel || undefined;
+  };
+
+  const clearCache = (): void => {
+    memoryCache.clear();
+    pendingRequests.clear();
+    persistedCacheLoaded = false;
+    persistedCacheLoadPromise = null;
+  };
+
+  return {
+    getProviderModels,
+    getCurrentActiveModel,
+    getChangedActiveModel,
+    changeActiveModel,
+    resolveResumeModel,
+    clearCache,
+  };
+};
+
+export const providerModelsService = createProviderModelsService();
diff --git a/server/modules/providers/services/session-conversations-search.service.ts b/server/modules/providers/services/session-conversations-search.service.ts
new file mode 100644
index 00000000..101a0955
--- /dev/null
+++ b/server/modules/providers/services/session-conversations-search.service.ts
@@ -0,0 +1,1316 @@
+import fsSync, { promises as fs } from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+
+import { spawn } from 'cross-spawn';
+import { rgPath } from '@vscode/ripgrep';
+
+import { projectsDb, sessionsDb } from '@/modules/database/index.js';
+
+type AnyRecord = Record<string, any>;
+type SearchableProvider = 'claude' | 'codex' | 'gemini';
+
+type SearchSnippetHighlight = {
+  start: number;
+  end: number;
+};
+
+type SessionConversationMatch = {
+  role: string;
+  snippet: string;
+  highlights: SearchSnippetHighlight[];
+  timestamp: string | null;
+  provider: SearchableProvider;
+  messageUuid?: string | null;
+};
+
+type SessionConversationResult = {
+  sessionId: string;
+  provider: SearchableProvider;
+  sessionSummary: string;
+  matches: SessionConversationMatch[];
+};
+
+type ProjectConversationResult = {
+  projectId: string | null;
+  projectName: string;
+  projectDisplayName: string;
+  sessions: SessionConversationResult[];
+};
+
+export type SessionConversationSearchProgressUpdate = {
+  projectResult: ProjectConversationResult | null;
+  totalMatches: number;
+  scannedProjects: number;
+  totalProjects: number;
+};
+
+type SearchSessionConversationsInput = {
+  query: string;
+  limit: number;
+  signal?: AbortSignal;
+  onProgress?: (update: SessionConversationSearchProgressUpdate) => void;
+};
+
+type SessionRepositoryRow = ReturnType<typeof sessionsDb.getAllSessions>[number];
+type SearchableSessionRow = SessionRepositoryRow & {
+  provider: SearchableProvider;
+  jsonl_path: string;
+};
+
+type SearchRuntime = {
+  matchesQuery: (text: string) => boolean;
+  buildSnippet: (text: string) => { snippet: string; highlights: SearchSnippetHighlight[] };
+  limit: number;
+  totalMatches: number;
+  isAborted: () => boolean;
+  matchedSessionKeys: Set<string>;
+  claudeSessionsByFileKey: Map<string, SearchableSessionRow[]>;
+  claudeFileResultsCache: Map<string, Map<string, SessionConversationResult>>;
+};
+
+type SearchablePathEntry = {
+  normalizedPath: string;
+  absolutePath: string;
+};
+
+type ProjectBucket = {
+  key: string;
+  projectId: string | null;
+  projectName: string;
+  projectDisplayName: string;
+  sessions: SearchableSessionRow[];
+};
+
+const SUPPORTED_PROVIDERS = new Set<SearchableProvider>(['claude', 'codex', 'gemini']);
+const MAX_MATCHES_PER_SESSION = 2;
+const RIPGREP_FILE_CHUNK_SIZE = 40;
+const RIPGREP_CHUNK_CONCURRENCY = 6;
+const UNKNOWN_PROJECT_KEY = '__unknown_project__';
+
+const INTERNAL_CONTENT_PREFIXES = [
+  '<system-reminder>',
+  'Caveat:',
+  'Invalid API key',
+  '[Request interrupted',
+] as const;
+
+/**
+ * Codex includes extra internal metadata tags that should not surface as
+ * user-facing searchable conversation content.
+ */
+const CODEX_INTERNAL_CONTENT_PREFIXES = [
+  '<environment_context>',
+  '<cwd>',
+] as const;
+
+function normalizeComparablePath(inputPath: string): string {
+  if (!inputPath || typeof inputPath !== 'string') {
+    return '';
+  }
+
+  const withoutLongPathPrefix = inputPath.startsWith('\\\\?\\')
+    ? inputPath.slice(4)
+    : inputPath;
+  const normalized = path.normalize(withoutLongPathPrefix.trim());
+  if (!normalized) {
+    return '';
+  }
+
+  const resolved = path.resolve(normalized);
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+function chunkArray<TItem>(items: TItem[], size: number): TItem[][] {
+  if (size <= 0) {
+    return [items];
+  }
+
+  const chunks: TItem[][] = [];
+  for (let idx = 0; idx < items.length; idx += size) {
+    chunks.push(items.slice(idx, idx + size));
+  }
+  return chunks;
+}
+
+function getSessionKey(session: Pick<SessionRepositoryRow, 'provider' | 'session_id'>): string {
+  return `${session.provider}:${session.session_id}`;
+}
+
+function makeProjectKey(projectPath: string | null): string {
+  const normalized = typeof projectPath === 'string' ? projectPath.trim() : '';
+  return normalized.length > 0 ? normalized : UNKNOWN_PROJECT_KEY;
+}
+
+function toSummaryText(customName: string | null, fallback: string | null | undefined, emptyLabel: string): string {
+  const trimmedCustomName = typeof customName === 'string' ? customName.trim() : '';
+  if (trimmedCustomName) {
+    return trimmedCustomName;
+  }
+
+  const trimmedFallback = typeof fallback === 'string' ? fallback.trim() : '';
+  if (!trimmedFallback) {
+    return emptyLabel;
+  }
+
+  return trimmedFallback.length > 50 ? `${trimmedFallback.slice(0, 50)}...` : trimmedFallback;
+}
+
+function isInternalContent(content: string): boolean {
+  return INTERNAL_CONTENT_PREFIXES.some((prefix) => content.startsWith(prefix));
+}
+
+function isInternalCodexContent(content: string): boolean {
+  const normalized = content.trimStart();
+  return CODEX_INTERNAL_CONTENT_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function createWordMatcher(
+  rawQuery: string,
+  words: string[],
+): Pick<SearchRuntime, 'matchesQuery' | 'buildSnippet'> {
+  const normalizedQuery = rawQuery.trim().replace(/\s+/g, ' ');
+  const requireExactPhrase = words.length > 1 && normalizedQuery.length > 0;
+  const wordPatterns = words.map((word) => new RegExp(`(?<!\\p{L})${escapeRegex(word)}(?!\\p{L})`, 'u'));
+  const phrasePattern = words.map((word) => escapeRegex(word)).join('\\s+');
+  const phraseRegex = new RegExp(phrasePattern, 'iu');
+
+  const allWordsMatch = (textLower: string): boolean =>
+    wordPatterns.every((pattern) => pattern.test(textLower));
+
+  const matchesQuery = (text: string): boolean => {
+    if (typeof text !== 'string' || text.length === 0) {
+      return false;
+    }
+
+    if (requireExactPhrase) {
+      return phraseRegex.test(text);
+    }
+
+    if (phraseRegex.test(text)) {
+      return true;
+    }
+
+    if (words.length === 1) {
+      return allWordsMatch(text.toLowerCase());
+    }
+
+    return allWordsMatch(text.toLowerCase());
+  };
+
+  const buildSnippet = (
+    text: string,
+    snippetLen = 150,
+  ): { snippet: string; highlights: SearchSnippetHighlight[] } => {
+    const textLower = text.toLowerCase();
+    let firstIndex = -1;
+    let firstWordLen = 0;
+    let phraseStart = -1;
+    let phraseLength = 0;
+
+    const phraseMatch = phraseRegex.exec(text);
+    if (phraseMatch) {
+      phraseStart = phraseMatch.index;
+      phraseLength = phraseMatch[0].length;
+      firstIndex = phraseStart;
+      firstWordLen = phraseLength;
+    }
+
+    if (firstIndex === -1) {
+      for (const word of words) {
+        const regex = new RegExp(`(?<!\\p{L})${escapeRegex(word)}(?!\\p{L})`, 'u');
+        const match = regex.exec(textLower);
+        if (match && (firstIndex === -1 || match.index < firstIndex)) {
+          firstIndex = match.index;
+          firstWordLen = word.length;
+        }
+      }
+    }
+
+    if (firstIndex === -1) {
+      firstIndex = 0;
+    }
+
+    const halfLen = Math.floor(snippetLen / 2);
+    const start = Math.max(0, firstIndex - halfLen);
+    const end = Math.min(text.length, firstIndex + halfLen + firstWordLen);
+    const prefix = start > 0 ? '...' : '';
+    const suffix = end < text.length ? '...' : '';
+    const snippetBody = text.slice(start, end).replace(/\n/g, ' ');
+    const snippet = `${prefix}${snippetBody}${suffix}`;
+
+    const snippetLower = snippet.toLowerCase();
+    const highlights: SearchSnippetHighlight[] = [];
+
+    if (phraseStart >= start && phraseStart + phraseLength <= end) {
+      const phraseOffset = prefix.length + (phraseStart - start);
+      highlights.push({
+        start: phraseOffset,
+        end: phraseOffset + phraseLength,
+      });
+    }
+
+    if (!requireExactPhrase) {
+      for (const word of words) {
+        const regex = new RegExp(`(?<!\\p{L})${escapeRegex(word)}(?!\\p{L})`, 'gu');
+        let match = regex.exec(snippetLower);
+        while (match) {
+          highlights.push({ start: match.index, end: match.index + word.length });
+          match = regex.exec(snippetLower);
+        }
+      }
+    }
+
+    highlights.sort((left, right) => left.start - right.start);
+    const merged: SearchSnippetHighlight[] = [];
+    for (const highlight of highlights) {
+      const previous = merged[merged.length - 1];
+      if (previous && highlight.start <= previous.end) {
+        previous.end = Math.max(previous.end, highlight.end);
+      } else {
+        merged.push({ ...highlight });
+      }
+    }
+
+    return { snippet, highlights: merged };
+  };
+
+  return { matchesQuery, buildSnippet };
+}
+
+function extractClaudeText(content: unknown): string {
+  if (typeof content === 'string') {
+    return content;
+  }
+
+  if (!Array.isArray(content)) {
+    return '';
+  }
+
+  return content
+    .filter((part: AnyRecord) => part?.type === 'text' && typeof part?.text === 'string')
+    .map((part: AnyRecord) => String(part.text))
+    .join(' ');
+}
+
+function extractTaggedContent(content: string, tagName: string): string | null {
+  const escapedTagName = tagName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = new RegExp(`<${escapedTagName}>([\\s\\S]*?)<\\/${escapedTagName}>`).exec(content);
+  return match ? match[1] : null;
+}
+
+type ClaudeLocalCommandPayload = {
+  commandName: string;
+  commandMessage: string;
+  commandArgs: string;
+};
+
+function parseClaudeLocalCommandPayload(content: string): ClaudeLocalCommandPayload | null {
+  const commandName = extractTaggedContent(content, 'command-name');
+  const commandMessage = extractTaggedContent(content, 'command-message');
+  const commandArgs = extractTaggedContent(content, 'command-args');
+
+  if (commandName === null && commandMessage === null && commandArgs === null) {
+    return null;
+  }
+
+  return {
+    commandName: commandName ?? '',
+    commandMessage: commandMessage ?? '',
+    commandArgs: commandArgs ?? '',
+  };
+}
+
+function buildClaudeLocalCommandDisplayText(payload: ClaudeLocalCommandPayload): string {
+  const commandName = payload.commandName.trim();
+  const commandMessage = payload.commandMessage.trim();
+  const commandArgs = payload.commandArgs.trim();
+  const baseCommand = commandName || commandMessage;
+
+  if (!baseCommand) {
+    return '';
+  }
+
+  return commandArgs ? `${baseCommand} ${commandArgs}` : baseCommand;
+}
+
+function stripAnsiFormatting(text: string): string {
+  return text.replace(/\u001B\[[0-9;?]*[ -/]*[@-~]/g, '');
+}
+
+type ClaudeSearchableMessage = {
+  text: string;
+  role: 'user' | 'assistant';
+};
+
+/**
+ * Claude mixes visible chat, compact summaries, and local command wrappers into
+ * the same transcript stream. Search should operate on the user-visible meaning
+ * of those rows rather than the raw wrapper syntax.
+ */
+function extractClaudeSearchableMessage(entry: AnyRecord): ClaudeSearchableMessage | null {
+  if (!entry.message?.content || entry.isApiErrorMessage) {
+    return null;
+  }
+
+  const rawRole = entry.message.role;
+  if (rawRole !== 'user' && rawRole !== 'assistant') {
+    return null;
+  }
+
+  if (typeof entry.message.content === 'string') {
+    const content = String(entry.message.content);
+
+    if (entry.isCompactSummary === true && content.trim()) {
+      return {
+        text: content,
+        role: 'assistant',
+      };
+    }
+
+    const localCommand = parseClaudeLocalCommandPayload(content);
+    if (localCommand) {
+      const displayText = buildClaudeLocalCommandDisplayText(localCommand);
+      return displayText
+        ? {
+            text: displayText,
+            role: 'user',
+          }
+        : null;
+    }
+
+    const localCommandStdout = extractTaggedContent(content, 'local-command-stdout');
+    if (localCommandStdout !== null) {
+      const stdoutText = stripAnsiFormatting(localCommandStdout).trim();
+      return stdoutText
+        ? {
+            text: stdoutText,
+            role: 'assistant',
+          }
+        : null;
+    }
+
+    if (!content || isInternalContent(content)) {
+      return null;
+    }
+
+    return {
+      text: content,
+      role: rawRole,
+    };
+  }
+
+  const text = extractClaudeText(entry.message.content);
+  if (!text) {
+    return null;
+  }
+
+  if (entry.isCompactSummary === true) {
+    return {
+      text,
+      role: 'assistant',
+    };
+  }
+
+  if (isInternalContent(text)) {
+    return null;
+  }
+
+  return {
+    text,
+    role: rawRole,
+  };
+}
+
+function extractCodexText(content: unknown): string {
+  if (typeof content === 'string') {
+    return content;
+  }
+
+  if (!Array.isArray(content)) {
+    return '';
+  }
+
+  return content
+    .map((item) => {
+      if (!item || typeof item !== 'object') {
+        return '';
+      }
+
+      const record = item as AnyRecord;
+      if (
+        (record.type === 'input_text' || record.type === 'output_text' || record.type === 'text')
+        && typeof record.text === 'string'
+      ) {
+        return record.text;
+      }
+
+      return '';
+    })
+    .filter(Boolean)
+    .join(' ');
+}
+
+function extractGeminiText(content: unknown): string {
+  if (typeof content === 'string') {
+    return content;
+  }
+
+  if (!Array.isArray(content)) {
+    return '';
+  }
+
+  return content
+    .filter((part: AnyRecord) => typeof part?.text === 'string')
+    .map((part: AnyRecord) => String(part.text))
+    .join(' ');
+}
+
+function normalizeSearchableSessions(rows: SessionRepositoryRow[]): SearchableSessionRow[] {
+  const normalizedRows: SearchableSessionRow[] = [];
+  const projectArchiveStateByPath = new Map<string, boolean>();
+
+  for (const row of rows) {
+    const provider = row.provider as SearchableProvider;
+    if (!SUPPORTED_PROVIDERS.has(provider)) {
+      continue;
+    }
+
+    const rawJsonlPath = typeof row.jsonl_path === 'string' ? row.jsonl_path.trim() : '';
+    if (!rawJsonlPath) {
+      continue;
+    }
+
+    const absoluteJsonlPath = path.resolve(rawJsonlPath);
+    if (!fsSync.existsSync(absoluteJsonlPath)) {
+      continue;
+    }
+
+    /**
+     * Active session rows can still belong to an archived project because
+     * project archiving intentionally preserves the underlying session data.
+     * Global conversation search should follow the visible workspace model,
+     * which means excluding any session whose owning project is archived.
+     *
+     * Cache the archive lookup per normalized project path so one search pass
+     * does not re-query the same project row for every session in that folder.
+     */
+    const normalizedProjectPath = typeof row.project_path === 'string' ? row.project_path.trim() : '';
+    if (normalizedProjectPath) {
+      if (!projectArchiveStateByPath.has(normalizedProjectPath)) {
+        const projectRow = projectsDb.getProjectPath(normalizedProjectPath);
+        projectArchiveStateByPath.set(normalizedProjectPath, Boolean(projectRow?.isArchived));
+      }
+
+      if (projectArchiveStateByPath.get(normalizedProjectPath) === true) {
+        continue;
+      }
+    }
+
+    normalizedRows.push({
+      ...row,
+      provider,
+      jsonl_path: absoluteJsonlPath,
+    });
+  }
+
+  return normalizedRows;
+}
+
+function buildProjectBuckets(searchableSessions: SearchableSessionRow[]): ProjectBucket[] {
+  const projectBuckets = new Map<string, ProjectBucket>();
+  const projectMetadataCache = new Map<string, { projectId: string | null; projectDisplayName: string }>();
+
+  for (const session of searchableSessions) {
+    const key = makeProjectKey(session.project_path);
+    if (!projectBuckets.has(key)) {
+      if (!projectMetadataCache.has(key)) {
+        if (key === UNKNOWN_PROJECT_KEY) {
+          projectMetadataCache.set(key, {
+            projectId: null,
+            projectDisplayName: 'Unknown Project',
+          });
+        } else {
+          const projectRow = projectsDb.getProjectPath(key);
+          const customProjectName = typeof projectRow?.custom_project_name === 'string'
+            ? projectRow.custom_project_name.trim()
+            : '';
+          const displayName = customProjectName || path.basename(key) || key;
+
+          projectMetadataCache.set(key, {
+            projectId: projectRow?.project_id ?? null,
+            projectDisplayName: displayName,
+          });
+        }
+      }
+
+      const metadata = projectMetadataCache.get(key) as { projectId: string | null; projectDisplayName: string };
+      projectBuckets.set(key, {
+        key,
+        projectId: metadata.projectId,
+        projectName: key,
+        projectDisplayName: metadata.projectDisplayName,
+        sessions: [],
+      });
+    }
+
+    const bucket = projectBuckets.get(key) as ProjectBucket;
+    bucket.sessions.push(session);
+  }
+
+  const buckets = Array.from(projectBuckets.values());
+  for (const bucket of buckets) {
+    bucket.sessions.sort((left, right) => {
+      const leftTs = new Date(left.updated_at || left.created_at || 0).getTime();
+      const rightTs = new Date(right.updated_at || right.created_at || 0).getTime();
+      return rightTs - leftTs;
+    });
+  }
+
+  return buckets;
+}
+
+/**
+ * Executes ripgrep with the file list explicitly provided from sessionsDb jsonl paths.
+ *
+ * This avoids recursive directory walks and uses a fixed known candidate list.
+ */
+async function runRipgrepFilesWithMatches(
+  pattern: string,
+  filePaths: string[],
+  signal?: AbortSignal,
+): Promise<Set<string>> {
+  if (!pattern || filePaths.length === 0 || signal?.aborted) {
+    return new Set();
+  }
+
+  return new Promise((resolve, reject) => {
+    const args = [
+      '--files-with-matches',
+      '--no-messages',
+      '--ignore-case',
+      '--fixed-strings',
+      '--',
+      pattern,
+      ...filePaths,
+    ];
+    const rg = spawn(rgPath, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+
+    const stdoutChunks: Buffer[] = [];
+    const stderrChunks: Buffer[] = [];
+    let aborted = false;
+
+    const abortListener = () => {
+      aborted = true;
+      rg.kill();
+    };
+
+    if (signal) {
+      signal.addEventListener('abort', abortListener, { once: true });
+    }
+
+    rg.stdout.on('data', (chunk: Buffer) => {
+      stdoutChunks.push(chunk);
+    });
+
+    rg.stderr.on('data', (chunk: Buffer) => {
+      stderrChunks.push(chunk);
+    });
+
+    rg.on('error', (error) => {
+      if (signal) {
+        signal.removeEventListener('abort', abortListener);
+      }
+
+      if (aborted || signal?.aborted) {
+        resolve(new Set());
+        return;
+      }
+
+      reject(error);
+    });
+
+    rg.on('close', (code) => {
+      if (signal) {
+        signal.removeEventListener('abort', abortListener);
+      }
+
+      if (aborted || signal?.aborted) {
+        resolve(new Set());
+        return;
+      }
+
+      if (code !== 0 && code !== 1) {
+        const stderr = Buffer.concat(stderrChunks).toString('utf8').trim();
+        reject(new Error(`ripgrep failed with code ${String(code)}: ${stderr}`));
+        return;
+      }
+
+      const stdout = Buffer.concat(stdoutChunks).toString('utf8');
+      const matchedPaths = new Set<string>();
+
+      for (const line of stdout.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+          continue;
+        }
+
+        matchedPaths.add(normalizeComparablePath(trimmed));
+      }
+
+      resolve(matchedPaths);
+    });
+  });
+}
+
+async function findMatchedFileKeys(
+  searchablePathEntries: SearchablePathEntry[],
+  rawQuery: string,
+  words: string[],
+  signal?: AbortSignal,
+): Promise<Set<string>> {
+  if (searchablePathEntries.length === 0 || words.length === 0 || signal?.aborted) {
+    return new Set();
+  }
+
+  const normalizedQuery = rawQuery.trim().replace(/\s+/g, ' ');
+  const requireExactPhrase = words.length > 1 && normalizedQuery.length > 0;
+
+  if (requireExactPhrase) {
+    let matchedForPhrase = searchablePathEntries.slice();
+
+    // Keep ripgrep as an over-approximation for exact phrase mode by requiring
+    // each word to appear somewhere in the file, then defer strict phrase
+    // validation to the in-memory matcher.
+    for (const word of words) {
+      if (signal?.aborted) {
+        return new Set();
+      }
+
+      const matchedForWord = new Set<string>();
+      const fileChunks = chunkArray(
+        matchedForPhrase.map((entry) => entry.absolutePath),
+        RIPGREP_FILE_CHUNK_SIZE,
+      );
+
+      let nextChunkIndex = 0;
+      const workerCount = Math.min(RIPGREP_CHUNK_CONCURRENCY, fileChunks.length);
+      const workers = Array.from({ length: workerCount }, async () => {
+        while (nextChunkIndex < fileChunks.length && !signal?.aborted) {
+          const currentIndex = nextChunkIndex;
+          nextChunkIndex += 1;
+          const chunkMatches = await runRipgrepFilesWithMatches(word, fileChunks[currentIndex], signal);
+          for (const matchedPath of chunkMatches) {
+            matchedForWord.add(matchedPath);
+          }
+        }
+      });
+
+      await Promise.all(workers);
+      if (signal?.aborted) {
+        return new Set();
+      }
+
+      matchedForPhrase = matchedForPhrase.filter((entry) => matchedForWord.has(entry.normalizedPath));
+      if (matchedForPhrase.length === 0) {
+        break;
+      }
+    }
+
+    return new Set(matchedForPhrase.map((entry) => entry.normalizedPath));
+  }
+
+  let remainingEntries = searchablePathEntries.slice();
+
+  // Run one ripgrep pass per term and intersect by keeping only files that
+  // matched every query word.
+  for (const word of words) {
+    if (signal?.aborted) {
+      return new Set();
+    }
+
+    const matchedForWord = new Set<string>();
+    const fileChunks = chunkArray(
+      remainingEntries.map((entry) => entry.absolutePath),
+      RIPGREP_FILE_CHUNK_SIZE,
+    );
+
+    let nextChunkIndex = 0;
+    const workerCount = Math.min(RIPGREP_CHUNK_CONCURRENCY, fileChunks.length);
+
+    const workers = Array.from({ length: workerCount }, async () => {
+      while (nextChunkIndex < fileChunks.length && !signal?.aborted) {
+        const currentIndex = nextChunkIndex;
+        nextChunkIndex += 1;
+        const chunkMatches = await runRipgrepFilesWithMatches(word, fileChunks[currentIndex], signal);
+        for (const matchedPath of chunkMatches) {
+          matchedForWord.add(matchedPath);
+        }
+      }
+    });
+
+    await Promise.all(workers);
+    if (signal?.aborted) {
+      return new Set();
+    }
+
+    remainingEntries = remainingEntries.filter((entry) => matchedForWord.has(entry.normalizedPath));
+    if (remainingEntries.length === 0) {
+      break;
+    }
+  }
+
+  return new Set(remainingEntries.map((entry) => entry.normalizedPath));
+}
+
+function addSessionMatch(
+  runtime: SearchRuntime,
+  matches: SessionConversationMatch[],
+  match: SessionConversationMatch,
+): void {
+  if (runtime.totalMatches >= runtime.limit || matches.length >= MAX_MATCHES_PER_SESSION) {
+    return;
+  }
+
+  matches.push(match);
+  runtime.totalMatches += 1;
+}
+
+async function parseClaudeSessionMatches(
+  session: SearchableSessionRow,
+  runtime: SearchRuntime,
+): Promise<SessionConversationResult | null> {
+  const fileKey = normalizeComparablePath(session.jsonl_path);
+  if (!fileKey) {
+    return null;
+  }
+
+  if (!runtime.claudeFileResultsCache.has(fileKey)) {
+    const sessionsForFile = runtime.claudeSessionsByFileKey.get(fileKey) || [];
+    const matchedSessionsForFile = sessionsForFile.filter((candidate) =>
+      runtime.matchedSessionKeys.has(getSessionKey(candidate)),
+    );
+
+    const targetSessions = matchedSessionsForFile.length > 0
+      ? matchedSessionsForFile
+      : [session];
+
+    const targetSessionIds = new Set(targetSessions.map((candidate) => candidate.session_id));
+    const customNameBySessionId = new Map<string, string | null>();
+    for (const candidate of targetSessions) {
+      customNameBySessionId.set(candidate.session_id, candidate.custom_name ?? null);
+    }
+
+    type ClaudeSessionSearchState = {
+      matches: SessionConversationMatch[];
+      pendingSummaries: Map<string, string>;
+      fallbackUserText: string | null;
+      fallbackAssistantText: string | null;
+      resolvedSummary: string | null;
+    };
+
+    const sessionStateById = new Map<string, ClaudeSessionSearchState>();
+    const getSessionState = (sessionId: string): ClaudeSessionSearchState => {
+      if (!sessionStateById.has(sessionId)) {
+        sessionStateById.set(sessionId, {
+          matches: [],
+          pendingSummaries: new Map<string, string>(),
+          fallbackUserText: null,
+          fallbackAssistantText: null,
+          resolvedSummary: null,
+        });
+      }
+      return sessionStateById.get(sessionId) as ClaudeSessionSearchState;
+    };
+
+    let currentSessionId: string | null = null;
+
+    try {
+      const fileStream = fsSync.createReadStream(session.jsonl_path);
+      const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+
+      for await (const line of rl) {
+        if (runtime.totalMatches >= runtime.limit || runtime.isAborted()) {
+          break;
+        }
+        if (!line.trim()) {
+          continue;
+        }
+
+        let entry: AnyRecord;
+        try {
+          entry = JSON.parse(line) as AnyRecord;
+        } catch {
+          continue;
+        }
+
+        if (entry.sessionId) {
+          currentSessionId = String(entry.sessionId);
+        }
+        const entrySessionId = entry.sessionId
+          ? String(entry.sessionId)
+          : currentSessionId;
+        if (!entrySessionId || !targetSessionIds.has(entrySessionId)) {
+          continue;
+        }
+
+        const state = getSessionState(entrySessionId);
+
+        if (entry.type === 'summary' && entry.summary) {
+          const summaryValue = String(entry.summary);
+          if (entry.sessionId) {
+            state.resolvedSummary = summaryValue;
+          } else if (entry.leafUuid) {
+            state.pendingSummaries.set(String(entry.leafUuid), summaryValue);
+          }
+        }
+
+        if (!state.resolvedSummary && entry.parentUuid) {
+          const pendingSummary = state.pendingSummaries.get(String(entry.parentUuid));
+          if (pendingSummary) {
+            state.resolvedSummary = pendingSummary;
+          }
+        }
+
+        const searchableMessage = extractClaudeSearchableMessage(entry);
+        if (!searchableMessage) {
+          continue;
+        }
+
+        const { text, role } = searchableMessage;
+
+        /**
+         * Claude compact summaries are the most faithful session-summary source
+         * after a `/compact` because they describe the post-compaction state that
+         * the resumed session actually continues from. Prefer them over generic
+         * fallback user text when present.
+         */
+        if (entry.isCompactSummary === true) {
+          state.resolvedSummary = text;
+        }
+
+        if (role === 'user') {
+          state.fallbackUserText = text;
+        } else {
+          state.fallbackAssistantText = text;
+        }
+
+        if (!runtime.matchesQuery(text)) {
+          continue;
+        }
+
+        const { snippet, highlights } = runtime.buildSnippet(text);
+        addSessionMatch(runtime, state.matches, {
+          role,
+          snippet,
+          highlights,
+          timestamp: entry.timestamp ? String(entry.timestamp) : null,
+          provider: 'claude',
+          messageUuid: entry.uuid ? String(entry.uuid) : null,
+        });
+      }
+    } catch {
+      runtime.claudeFileResultsCache.set(fileKey, new Map());
+      return null;
+    }
+
+    const fileResults = new Map<string, SessionConversationResult>();
+    for (const [sessionId, state] of sessionStateById.entries()) {
+      if (state.matches.length === 0) {
+        continue;
+      }
+
+      fileResults.set(sessionId, {
+        sessionId,
+        provider: 'claude',
+        sessionSummary: toSummaryText(
+          customNameBySessionId.get(sessionId) ?? null,
+          state.resolvedSummary || state.fallbackUserText || state.fallbackAssistantText,
+          'New Session',
+        ),
+        matches: state.matches,
+      });
+    }
+
+    runtime.claudeFileResultsCache.set(fileKey, fileResults);
+  }
+
+  return runtime.claudeFileResultsCache.get(fileKey)?.get(session.session_id) ?? null;
+}
+
+function isVisibleCodexUserMessage(payload: AnyRecord | null | undefined): boolean {
+  if (!payload || payload.type !== 'user_message') {
+    return false;
+  }
+
+  if (payload.kind && payload.kind !== 'plain') {
+    return false;
+  }
+
+  return typeof payload.message === 'string' && payload.message.trim().length > 0;
+}
+
+async function parseCodexSessionMatches(
+  session: SearchableSessionRow,
+  runtime: SearchRuntime,
+): Promise<SessionConversationResult | null> {
+  const matches: SessionConversationMatch[] = [];
+  let latestUserMessageText: string | null = null;
+  const seenMessageFingerprints = new Set<string>();
+
+  try {
+    const fileStream = fsSync.createReadStream(session.jsonl_path);
+    const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+
+    for await (const line of rl) {
+      if (runtime.totalMatches >= runtime.limit || runtime.isAborted()) {
+        break;
+      }
+      if (!line.trim()) {
+        continue;
+      }
+
+      let entry: AnyRecord;
+      try {
+        entry = JSON.parse(line) as AnyRecord;
+      } catch {
+        continue;
+      }
+
+      let text: string | null = null;
+      let role: 'user' | 'assistant' | null = null;
+
+      if (entry.type === 'event_msg' && isVisibleCodexUserMessage(entry.payload as AnyRecord)) {
+        text = String(entry.payload.message);
+        role = 'user';
+      } else if (
+        entry.type === 'event_msg'
+        && entry.payload?.type === 'agent_reasoning'
+        && typeof entry.payload?.text === 'string'
+      ) {
+        text = String(entry.payload.text);
+        role = 'assistant';
+      } else if (entry.type === 'response_item' && entry.payload?.type === 'message') {
+        const payload = entry.payload as AnyRecord;
+        if (payload.role === 'user') {
+          text = extractCodexText(payload.content);
+          role = 'user';
+        } else if (payload.role === 'assistant') {
+          text = extractCodexText(payload.content);
+          role = 'assistant';
+        }
+      } else if (entry.type === 'response_item' && entry.payload?.type === 'reasoning') {
+        const summaryText = Array.isArray(entry.payload.summary)
+          ? entry.payload.summary
+            .map((item: AnyRecord) => (typeof item?.text === 'string' ? item.text : ''))
+            .filter(Boolean)
+            .join('\n')
+          : '';
+
+        if (summaryText.trim()) {
+          text = summaryText;
+          role = 'assistant';
+        }
+      }
+
+      if (!text || !role) {
+        continue;
+      }
+      if (isInternalCodexContent(text)) {
+        continue;
+      }
+      if (role === 'user') {
+        latestUserMessageText = text;
+      }
+
+      const fingerprint = `${role}:${text.trim().toLowerCase()}`;
+      if (seenMessageFingerprints.has(fingerprint)) {
+        continue;
+      }
+      seenMessageFingerprints.add(fingerprint);
+
+      if (!runtime.matchesQuery(text)) {
+        continue;
+      }
+
+      const { snippet, highlights } = runtime.buildSnippet(text);
+      addSessionMatch(runtime, matches, {
+        role,
+        snippet,
+        highlights,
+        timestamp: entry.timestamp ? String(entry.timestamp) : null,
+        provider: 'codex',
+      });
+    }
+  } catch {
+    return null;
+  }
+
+  if (matches.length === 0) {
+    return null;
+  }
+
+  return {
+    sessionId: session.session_id,
+    provider: 'codex',
+    sessionSummary: toSummaryText(session.custom_name, latestUserMessageText, 'Codex Session'),
+    matches,
+  };
+}
+
+async function parseGeminiSessionMatches(
+  session: SearchableSessionRow,
+  runtime: SearchRuntime,
+): Promise<SessionConversationResult | null> {
+  let data: string;
+  try {
+    data = await fs.readFile(session.jsonl_path, 'utf8');
+  } catch {
+    return null;
+  }
+
+  let parsed: AnyRecord;
+  try {
+    parsed = JSON.parse(data) as AnyRecord;
+  } catch {
+    return null;
+  }
+
+  const sourceMessages = Array.isArray(parsed.messages) ? parsed.messages as AnyRecord[] : [];
+  if (sourceMessages.length === 0) {
+    return null;
+  }
+
+  const matches: SessionConversationMatch[] = [];
+  let firstUserText: string | null = null;
+
+  for (const msg of sourceMessages) {
+    if (runtime.totalMatches >= runtime.limit || runtime.isAborted()) {
+      break;
+    }
+
+    const role = msg.type === 'user'
+      ? 'user'
+      : (msg.type === 'gemini' || msg.type === 'assistant')
+        ? 'assistant'
+        : null;
+    if (!role) {
+      continue;
+    }
+
+    const text = extractGeminiText(msg.content);
+    if (!text) {
+      continue;
+    }
+
+    if (role === 'user' && !firstUserText) {
+      firstUserText = text;
+    }
+
+    if (!runtime.matchesQuery(text)) {
+      continue;
+    }
+
+    const { snippet, highlights } = runtime.buildSnippet(text);
+    addSessionMatch(runtime, matches, {
+      role,
+      snippet,
+      highlights,
+      timestamp: msg.timestamp ? String(msg.timestamp) : null,
+      provider: 'gemini',
+    });
+  }
+
+  if (matches.length === 0) {
+    return null;
+  }
+
+  return {
+    sessionId: session.session_id,
+    provider: 'gemini',
+    sessionSummary: toSummaryText(session.custom_name, firstUserText, 'Gemini Session'),
+    matches,
+  };
+}
+
+async function parseSessionMatches(
+  session: SearchableSessionRow,
+  runtime: SearchRuntime,
+): Promise<SessionConversationResult | null> {
+  if (session.provider === 'claude') {
+    return parseClaudeSessionMatches(session, runtime);
+  }
+  if (session.provider === 'codex') {
+    return parseCodexSessionMatches(session, runtime);
+  }
+  return parseGeminiSessionMatches(session, runtime);
+}
+
+export async function searchConversations(
+  query: string,
+  limit = 50,
+  onProjectResult: ((update: SessionConversationSearchProgressUpdate) => void) | null = null,
+  signal: AbortSignal | null = null,
+): Promise<{ results: ProjectConversationResult[]; totalMatches: number; query: string }> {
+  const safeQuery = typeof query === 'string' ? query.trim() : '';
+  const safeLimit = Math.max(1, Math.min(Number.isFinite(limit) ? limit : 50, 200));
+  const words = safeQuery.toLowerCase().split(/\s+/).filter((word) => word.length > 0);
+
+  if (words.length === 0) {
+    return { results: [], totalMatches: 0, query: safeQuery };
+  }
+
+  const isAborted = () => signal?.aborted === true;
+  if (isAborted()) {
+    return { results: [], totalMatches: 0, query: safeQuery };
+  }
+
+  const searchableSessions = normalizeSearchableSessions(sessionsDb.getAllSessions());
+  if (searchableSessions.length === 0) {
+    return { results: [], totalMatches: 0, query: safeQuery };
+  }
+
+  const sessionsByPathKey = new Map<string, SearchableSessionRow[]>();
+  const searchablePathEntries: SearchablePathEntry[] = [];
+
+  for (const session of searchableSessions) {
+    const normalizedPath = normalizeComparablePath(session.jsonl_path);
+    if (!normalizedPath) {
+      continue;
+    }
+
+    if (!sessionsByPathKey.has(normalizedPath)) {
+      sessionsByPathKey.set(normalizedPath, []);
+      searchablePathEntries.push({
+        normalizedPath,
+        absolutePath: session.jsonl_path,
+      });
+    }
+
+    const pathSessions = sessionsByPathKey.get(normalizedPath) as SearchableSessionRow[];
+    pathSessions.push(session);
+  }
+
+  const matchedFileKeys = await findMatchedFileKeys(
+    searchablePathEntries,
+    safeQuery,
+    words,
+    signal ?? undefined,
+  );
+  if (isAborted() || matchedFileKeys.size === 0) {
+    return { results: [], totalMatches: 0, query: safeQuery };
+  }
+
+  const matchedSessionKeys = new Set<string>();
+  for (const fileKey of matchedFileKeys) {
+    const sessions = sessionsByPathKey.get(fileKey);
+    if (!sessions) {
+      continue;
+    }
+
+    for (const session of sessions) {
+      matchedSessionKeys.add(getSessionKey(session));
+    }
+  }
+
+  const projectBuckets = buildProjectBuckets(searchableSessions);
+  const totalProjects = projectBuckets.length;
+  const results: ProjectConversationResult[] = [];
+  let scannedProjects = 0;
+
+  const runtime: SearchRuntime = {
+    ...createWordMatcher(safeQuery, words),
+    limit: safeLimit,
+    totalMatches: 0,
+    isAborted,
+    matchedSessionKeys,
+    claudeSessionsByFileKey: new Map<string, SearchableSessionRow[]>(),
+    claudeFileResultsCache: new Map<string, Map<string, SessionConversationResult>>(),
+  };
+
+  for (const [fileKey, sessions] of sessionsByPathKey.entries()) {
+    const claudeSessions = sessions.filter((session) => session.provider === 'claude');
+    if (claudeSessions.length > 0) {
+      runtime.claudeSessionsByFileKey.set(fileKey, claudeSessions);
+    }
+  }
+
+  for (const bucket of projectBuckets) {
+    if (runtime.totalMatches >= runtime.limit || runtime.isAborted()) {
+      break;
+    }
+
+    const projectResult: ProjectConversationResult = {
+      projectId: bucket.projectId,
+      projectName: bucket.projectName,
+      projectDisplayName: bucket.projectDisplayName,
+      sessions: [],
+    };
+
+    for (const session of bucket.sessions) {
+      if (runtime.totalMatches >= runtime.limit || runtime.isAborted()) {
+        break;
+      }
+      if (!matchedSessionKeys.has(getSessionKey(session))) {
+        continue;
+      }
+
+      const sessionResult = await parseSessionMatches(session, runtime);
+      if (sessionResult) {
+        projectResult.sessions.push(sessionResult);
+      }
+    }
+
+    scannedProjects += 1;
+    if (projectResult.sessions.length > 0) {
+      results.push(projectResult);
+      onProjectResult?.({
+        projectResult,
+        totalMatches: runtime.totalMatches,
+        scannedProjects,
+        totalProjects,
+      });
+    } else if (onProjectResult && scannedProjects % 10 === 0) {
+      onProjectResult({
+        projectResult: null,
+        totalMatches: runtime.totalMatches,
+        scannedProjects,
+        totalProjects,
+      });
+    }
+  }
+
+  return {
+    results,
+    totalMatches: runtime.totalMatches,
+    query: safeQuery,
+  };
+}
+
+/**
+ * Application service for session-conversation search.
+ *
+ * Provider routes call this service so route handlers stay focused on
+ * request parsing/response formatting, while search execution remains
+ * centralized in one place.
+ */
+export const sessionConversationsSearchService = {
+  /**
+   * Streams progress updates while the search scans provider session logs.
+   */
+  async search(input: SearchSessionConversationsInput): Promise<void> {
+    await searchConversations(
+      input.query,
+      input.limit,
+      input.onProgress ?? null,
+      input.signal ?? null,
+    );
+  },
+};
diff --git a/server/modules/providers/services/session-synchronizer.service.ts b/server/modules/providers/services/session-synchronizer.service.ts
new file mode 100644
index 00000000..55b41f9e
--- /dev/null
+++ b/server/modules/providers/services/session-synchronizer.service.ts
@@ -0,0 +1,75 @@
+import { scanStateDb } from '@/modules/database/index.js';
+import { providerRegistry } from '@/modules/providers/provider.registry.js';
+import type { LLMProvider } from '@/shared/types.js';
+
+type SessionSynchronizeResult = {
+  processedByProvider: Record<LLMProvider, number>;
+  failures: string[];
+};
+
+/**
+ * Orchestrates provider-specific session indexers and indexed-session lifecycle operations.
+ */
+export const sessionSynchronizerService = {
+  /**
+   * Runs all provider synchronizers and updates scan_state.last_scanned_at.
+   */
+  async synchronizeSessions(): Promise<SessionSynchronizeResult> {
+    const lastScanAt = scanStateDb.getLastScannedAt();
+    const scanBoundary = new Date();
+    const processedByProvider: Record<LLMProvider, number> = {
+      claude: 0,
+      codex: 0,
+      cursor: 0,
+      gemini: 0,
+      opencode: 0,
+    };
+    const failures: string[] = [];
+
+    const results = await Promise.allSettled(
+      providerRegistry.listProviders().map(async (provider) => ({
+        provider: provider.id,
+        processed: await provider.sessionSynchronizer.synchronize(lastScanAt ?? undefined),
+      }))
+    );
+
+    for (const result of results) {
+      if (result.status === 'fulfilled') {
+        processedByProvider[result.value.provider] = result.value.processed;
+        continue;
+      }
+
+      const reason = result.reason instanceof Error ? result.reason.message : String(result.reason);
+      failures.push(reason);
+    }
+
+    if (failures.length === 0) {
+      scanStateDb.updateLastScannedAt(scanBoundary);
+    } else {
+      console.warn(
+        `[Sessions] Skipping scan_state cursor advance because ${failures.length} provider sync(s) failed.`,
+      );
+    }
+
+    return {
+      processedByProvider,
+      failures,
+    };
+  },
+
+  /**
+   * Indexes one provider artifact file without running a full provider rescan.
+   */
+  async synchronizeProviderFile(
+    provider: LLMProvider,
+    filePath: string
+  ): Promise<{ provider: LLMProvider; indexed: boolean; sessionId: string | null }> {
+    const resolvedProvider = providerRegistry.resolveProvider(provider);
+    const sessionId = await resolvedProvider.sessionSynchronizer.synchronizeFile(filePath);
+    return {
+      provider,
+      indexed: Boolean(sessionId),
+      sessionId,
+    };
+  },
+};
diff --git a/server/modules/providers/services/sessions-watcher.service.ts b/server/modules/providers/services/sessions-watcher.service.ts
new file mode 100644
index 00000000..7e0ab36a
--- /dev/null
+++ b/server/modules/providers/services/sessions-watcher.service.ts
@@ -0,0 +1,293 @@
+import os from 'node:os';
+import path from 'node:path';
+import { promises as fsPromises } from 'node:fs';
+
+import chokidar, { type FSWatcher } from 'chokidar';
+
+import { sessionSynchronizerService } from '@/modules/providers/services/session-synchronizer.service.js';
+import { WS_OPEN_STATE, connectedClients } from '@/modules/websocket/index.js';
+import type { LLMProvider } from '@/shared/types.js';
+import { getProjectsWithSessions } from '@/modules/projects/index.js';
+
+type WatcherEventType = 'add' | 'change';
+
+const PROVIDER_WATCH_PATHS: Array<{ provider: LLMProvider; rootPath: string }> = [
+  {
+    provider: 'claude',
+    rootPath: path.join(os.homedir(), '.claude', 'projects'),
+  },
+  {
+    provider: 'cursor',
+    rootPath: path.join(os.homedir(), '.cursor', 'projects'),
+  },
+  {
+    provider: 'codex',
+    rootPath: path.join(os.homedir(), '.codex', 'sessions'),
+  },
+  // {
+  //   provider: 'gemini',
+  //   rootPath: path.join(os.homedir(), '.gemini', 'sessions'),
+  // },
+  // Keep `sessions/` watcher disabled: Gemini also mirrors artifacts there,
+  // which causes duplicate synchronization events.
+  {
+    provider: 'gemini',
+    rootPath: path.join(os.homedir(), '.gemini', 'tmp'),
+  },
+  {
+    provider: 'opencode',
+    rootPath: path.join(os.homedir(), '.local', 'share', 'opencode'),
+  },
+];
+
+const WATCHER_IGNORED_PATTERNS = [
+  '**/node_modules/**',
+  '**/.git/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/*.tmp',
+  '**/*.swp',
+  '**/.DS_Store',
+];
+
+const PROJECTS_UPDATE_DEBOUNCE_MS = 500;
+const PROJECTS_UPDATE_MAX_WAIT_MS = 2_000;
+
+const watchers: FSWatcher[] = [];
+
+type PendingWatcherUpdate = {
+  providers: Set<LLMProvider>;
+  changeTypes: Set<WatcherEventType>;
+  updatedSessionIds: Set<string>;
+};
+
+let pendingWatcherUpdate: PendingWatcherUpdate | null = null;
+let pendingWatcherUpdateStartedAt: number | null = null;
+let pendingWatcherFlushTimer: ReturnType<typeof setTimeout> | null = null;
+let watcherRefreshInFlight = false;
+let watcherRescheduleAfterRefresh = false;
+
+/**
+ * Filters watcher events to provider-specific session artifact file types.
+ */
+function isWatcherTargetFile(provider: LLMProvider, filePath: string): boolean {
+  if (provider === 'opencode') {
+    return path.basename(filePath) === 'opencode.db';
+  }
+
+  if (provider === 'gemini') {
+    return filePath.endsWith('.json') || filePath.endsWith('.jsonl');
+  }
+
+  return filePath.endsWith('.jsonl');
+}
+
+function clearPendingWatcherFlushTimer(): void {
+  if (pendingWatcherFlushTimer) {
+    clearTimeout(pendingWatcherFlushTimer);
+    pendingWatcherFlushTimer = null;
+  }
+}
+
+function schedulePendingWatcherFlush(): void {
+  if (!pendingWatcherUpdate) {
+    return;
+  }
+
+  const now = Date.now();
+  if (pendingWatcherUpdateStartedAt === null) {
+    pendingWatcherUpdateStartedAt = now;
+  }
+
+  const elapsed = now - pendingWatcherUpdateStartedAt;
+  const remainingMaxWait = Math.max(0, PROJECTS_UPDATE_MAX_WAIT_MS - elapsed);
+  const delay = Math.min(PROJECTS_UPDATE_DEBOUNCE_MS, remainingMaxWait);
+
+  clearPendingWatcherFlushTimer();
+  pendingWatcherFlushTimer = setTimeout(() => {
+    void flushPendingWatcherUpdate();
+  }, delay);
+}
+
+function queuePendingWatcherUpdate(
+  eventType: WatcherEventType,
+  provider: LLMProvider,
+  updatedSessionId: string | null
+): void {
+  if (!pendingWatcherUpdate) {
+    pendingWatcherUpdate = {
+      providers: new Set<LLMProvider>(),
+      changeTypes: new Set<WatcherEventType>(),
+      updatedSessionIds: new Set<string>(),
+    };
+  }
+
+  pendingWatcherUpdate.providers.add(provider);
+  pendingWatcherUpdate.changeTypes.add(eventType);
+  if (updatedSessionId) {
+    pendingWatcherUpdate.updatedSessionIds.add(updatedSessionId);
+  }
+
+  schedulePendingWatcherFlush();
+}
+
+async function flushPendingWatcherUpdate(): Promise<void> {
+  clearPendingWatcherFlushTimer();
+
+  if (!pendingWatcherUpdate) {
+    return;
+  }
+
+  if (watcherRefreshInFlight) {
+    watcherRescheduleAfterRefresh = true;
+    return;
+  }
+
+  const queuedUpdate = pendingWatcherUpdate;
+  pendingWatcherUpdate = null;
+  pendingWatcherUpdateStartedAt = null;
+  watcherRefreshInFlight = true;
+
+  try {
+    const updatedProjects = await getProjectsWithSessions({ skipSynchronization: true });
+    const changeTypes = Array.from(queuedUpdate.changeTypes);
+    const watchProviders = Array.from(queuedUpdate.providers);
+    const updatedSessionIds = Array.from(queuedUpdate.updatedSessionIds);
+
+    // Backward-compatible fields stay populated with the first queued values.
+    const updateMessage = JSON.stringify({
+      type: 'projects_updated',
+      projects: updatedProjects,
+      timestamp: new Date().toISOString(),
+      changeType: changeTypes[0] ?? 'change',
+      updatedSessionId: updatedSessionIds[0] ?? undefined,
+      watchProvider: watchProviders[0] ?? undefined,
+      changeTypes,
+      updatedSessionIds,
+      watchProviders,
+      batched: true,
+    });
+
+    connectedClients.forEach(client => {
+      if (client.readyState === WS_OPEN_STATE) {
+        client.send(updateMessage);
+      }
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error('Session watcher refresh failed while broadcasting projects_updated', { error: message });
+  } finally {
+    watcherRefreshInFlight = false;
+
+    if (pendingWatcherUpdate || watcherRescheduleAfterRefresh) {
+      watcherRescheduleAfterRefresh = false;
+      schedulePendingWatcherFlush();
+    }
+  }
+}
+
+/**
+ * Handles file watcher updates and triggers provider file-level synchronization.
+ */
+async function onUpdate(
+  eventType: WatcherEventType,
+  filePath: string,
+  provider: LLMProvider
+): Promise<void> {
+  if (!isWatcherTargetFile(provider, filePath)) {
+    return;
+  }
+
+  try {
+    const result = await sessionSynchronizerService.synchronizeProviderFile(provider, filePath);
+    if (!result.indexed) {
+      return;
+    }
+
+    console.log(`Session synchronization triggered by ${eventType} event for provider "${provider}"`, {
+      filePath,
+      sessionId: result.sessionId,
+    });
+    queuePendingWatcherUpdate(eventType, provider, result.sessionId);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Session watcher sync failed for provider "${provider}"`, {
+      eventType,
+      filePath,
+      error: message,
+    });
+  }
+}
+
+/**
+ * Starts provider filesystem watchers and performs initial DB synchronization.
+ */
+export async function initializeSessionsWatcher(): Promise<void> {
+  console.log('Setting up session watchers');
+
+  const initialSync = await sessionSynchronizerService.synchronizeSessions();
+  console.log('Initial session synchronization complete', {
+    processedByProvider: initialSync.processedByProvider,
+    failures: initialSync.failures,
+  });
+
+  for (const { provider, rootPath } of PROVIDER_WATCH_PATHS) {
+    try {
+      await fsPromises.mkdir(rootPath, { recursive: true });
+
+      const watcher = chokidar.watch(rootPath, {
+        ignored: WATCHER_IGNORED_PATTERNS,
+        persistent: true,
+        ignoreInitial: true,
+        followSymlinks: false,
+        depth: 6,
+        usePolling: true,
+        interval: 6_000,
+        binaryInterval: 6_000,
+      });
+
+      watcher
+        .on('add', (filePath: string) => {
+          void onUpdate('add', filePath, provider);
+        })
+        .on('change', (filePath: string) => {
+          void onUpdate('change', filePath, provider);
+        })
+        .on('error', (error: unknown) => {
+          const message = error instanceof Error ? error.message : String(error);
+          console.error(`Session watcher error for provider "${provider}"`, { error: message });
+        });
+
+      watchers.push(watcher);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`Failed to initialize session watcher for provider "${provider}"`, {
+        rootPath,
+        error: message,
+      });
+    }
+  }
+}
+
+/**
+ * Stops all active provider session watchers.
+ */
+export async function closeSessionsWatcher(): Promise<void> {
+  clearPendingWatcherFlushTimer();
+
+  await Promise.all(
+    watchers.map(async (watcher) => {
+      try {
+        await watcher.close();
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error('Failed to close session watcher', { error: message });
+      }
+    })
+  );
+  watchers.length = 0;
+  pendingWatcherUpdate = null;
+  pendingWatcherUpdateStartedAt = null;
+  watcherRefreshInFlight = false;
+  watcherRescheduleAfterRefresh = false;
+}
diff --git a/server/modules/providers/services/sessions.service.ts b/server/modules/providers/services/sessions.service.ts
index adff6e8f..49b5dcb7 100644
--- a/server/modules/providers/services/sessions.service.ts
+++ b/server/modules/providers/services/sessions.service.ts
@@ -1,3 +1,7 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import { projectsDb, sessionsDb } from '@/modules/database/index.js';
 import { providerRegistry } from '@/modules/providers/provider.registry.js';
 import type {
   FetchHistoryOptions,
@@ -5,6 +9,58 @@ import type {
   LLMProvider,
   NormalizedMessage,
 } from '@/shared/types.js';
+import { AppError } from '@/shared/utils.js';
+
+type ArchivedSessionListItem = {
+  sessionId: string;
+  provider: LLMProvider;
+  projectId: string | null;
+  projectPath: string | null;
+  projectDisplayName: string;
+  sessionTitle: string;
+  createdAt: string | null;
+  updatedAt: string | null;
+  lastActivity: string | null;
+  isProjectArchived: boolean;
+};
+
+/**
+ * Removes one file if it exists.
+ */
+async function removeFileIfExists(filePath: string): Promise<boolean> {
+  try {
+    await fsp.unlink(filePath);
+    return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Archive rows need a stable project label even when the owning project is not
+ * part of the active sidebar payload. This lightweight resolver keeps the
+ * archive API self-contained while still matching the project's stored display
+ * name when one exists.
+ */
+function resolveProjectDisplayName(
+  projectPath: string | null,
+  customProjectName: string | null | undefined,
+): string {
+  const trimmedCustomName = typeof customProjectName === 'string' ? customProjectName.trim() : '';
+  if (trimmedCustomName.length > 0) {
+    return trimmedCustomName;
+  }
+
+  if (!projectPath) {
+    return 'Unknown Project';
+  }
+
+  return path.basename(projectPath) || projectPath;
+}
 
 /**
  * Application service for provider-backed session message operations.
@@ -33,13 +89,145 @@ export const sessionsService = {
   },
 
   /**
-   * Fetches normalized persisted session history for one provider/session pair.
+   * Fetches persisted history by session id.
+   *
+   * Provider and provider-specific lookup hints are resolved from the indexed
+   * session metadata in the database.
    */
   fetchHistory(
-    providerName: string,
     sessionId: string,
-    options?: FetchHistoryOptions,
+    options: Pick<FetchHistoryOptions, 'limit' | 'offset'> = {},
   ): Promise<FetchHistoryResult> {
-    return providerRegistry.resolveProvider(providerName).sessions.fetchHistory(sessionId, options);
+    const session = sessionsDb.getSessionById(sessionId);
+    if (!session) {
+      throw new AppError(`Session "${sessionId}" was not found.`, {
+        code: 'SESSION_NOT_FOUND',
+        statusCode: 404,
+      });
+    }
+
+    const provider = session.provider as LLMProvider;
+    return providerRegistry.resolveProvider(provider).sessions.fetchHistory(sessionId, {
+      limit: options.limit ?? null,
+      offset: options.offset ?? 0,
+      projectPath: session.project_path ?? '',
+    });
+  },
+
+  /**
+   * Returns archived sessions with enough project metadata for the sidebar to
+   * group, filter, open, and restore them without a per-row follow-up query.
+   */
+  listArchivedSessions(): ArchivedSessionListItem[] {
+    const archivedSessions = sessionsDb.getArchivedSessions();
+    const projectCache = new Map<string, ReturnType<typeof projectsDb.getProjectPath>>();
+
+    return archivedSessions.map((session) => {
+      const projectPath = session.project_path?.trim() ? session.project_path : null;
+      let project = null;
+
+      if (projectPath) {
+        if (!projectCache.has(projectPath)) {
+          projectCache.set(projectPath, projectsDb.getProjectPath(projectPath));
+        }
+        project = projectCache.get(projectPath) ?? null;
+      }
+
+      return {
+        sessionId: session.session_id,
+        provider: session.provider as LLMProvider,
+        projectId: project?.project_id ?? null,
+        projectPath,
+        projectDisplayName: resolveProjectDisplayName(projectPath, project?.custom_project_name),
+        sessionTitle: session.custom_name?.trim() || session.session_id,
+        createdAt: session.created_at ?? null,
+        updatedAt: session.updated_at ?? null,
+        lastActivity: session.updated_at ?? session.created_at ?? null,
+        isProjectArchived: Boolean(project?.isArchived),
+      };
+    });
+  },
+
+  /**
+   * Archives or permanently deletes one persisted session row by id.
+   *
+   * Soft-delete mirrors the project behavior by toggling `isArchived` so the
+   * row disappears from active lists but remains restorable. Force-delete
+   * optionally removes the transcript file before deleting the database row.
+   */
+  async deleteOrArchiveSessionById(
+    sessionId: string,
+    options: {
+      force?: boolean;
+      deletedFromDisk?: boolean;
+    } = {},
+  ): Promise<{ sessionId: string; action: 'archived' | 'deleted'; deletedFromDisk: boolean }> {
+    const session = sessionsDb.getSessionById(sessionId);
+    if (!session) {
+      throw new AppError(`Session "${sessionId}" was not found.`, {
+        code: 'SESSION_NOT_FOUND',
+        statusCode: 404,
+      });
+    }
+
+    if (!options.force) {
+      sessionsDb.updateSessionIsArchived(sessionId, true);
+      return {
+        sessionId,
+        action: 'archived',
+        deletedFromDisk: false,
+      };
+    }
+
+    let removedFromDisk = false;
+    if (options.deletedFromDisk && session.jsonl_path) {
+      removedFromDisk = await removeFileIfExists(session.jsonl_path);
+    }
+
+    const deleted = sessionsDb.deleteSessionById(sessionId);
+    if (!deleted) {
+      throw new AppError(`Session "${sessionId}" was not found.`, {
+        code: 'SESSION_NOT_FOUND',
+        statusCode: 404,
+      });
+    }
+
+    return {
+      sessionId,
+      action: 'deleted',
+      deletedFromDisk: removedFromDisk,
+    };
+  },
+
+  /**
+   * Restores one archived session back into the active sidebar lists.
+   */
+  restoreSessionById(sessionId: string): { sessionId: string; isArchived: false } {
+    const session = sessionsDb.getSessionById(sessionId);
+    if (!session) {
+      throw new AppError(`Session "${sessionId}" was not found.`, {
+        code: 'SESSION_NOT_FOUND',
+        statusCode: 404,
+      });
+    }
+
+    sessionsDb.updateSessionIsArchived(sessionId, false);
+    return { sessionId, isArchived: false };
+  },
+
+  /**
+   * Renames one session by id without requiring the caller to pass provider.
+   */
+  renameSessionById(sessionId: string, summary: string): { sessionId: string; summary: string } {
+    const session = sessionsDb.getSessionById(sessionId);
+    if (!session) {
+      throw new AppError(`Session "${sessionId}" was not found.`, {
+        code: 'SESSION_NOT_FOUND',
+        statusCode: 404,
+      });
+    }
+
+    sessionsDb.updateSessionCustomName(sessionId, summary);
+    return { sessionId, summary };
   },
 };
diff --git a/server/modules/providers/services/skills.service.ts b/server/modules/providers/services/skills.service.ts
new file mode 100644
index 00000000..2a02ad22
--- /dev/null
+++ b/server/modules/providers/services/skills.service.ts
@@ -0,0 +1,15 @@
+import { providerRegistry } from '@/modules/providers/provider.registry.js';
+import type { ProviderSkill, ProviderSkillListOptions } from '@/shared/types.js';
+
+export const providerSkillsService = {
+  /**
+   * Lists normalized skills visible to one provider.
+   */
+  async listProviderSkills(
+    providerName: string,
+    options?: ProviderSkillListOptions,
+  ): Promise<ProviderSkill[]> {
+    const provider = providerRegistry.resolveProvider(providerName);
+    return provider.skills.listSkills(options);
+  },
+};
diff --git a/server/modules/providers/shared/base/abstract.provider.ts b/server/modules/providers/shared/base/abstract.provider.ts
index 4a591baf..56054e14 100644
--- a/server/modules/providers/shared/base/abstract.provider.ts
+++ b/server/modules/providers/shared/base/abstract.provider.ts
@@ -1,4 +1,12 @@
-import type { IProvider, IProviderAuth, IProviderMcp, IProviderSessions } from '@/shared/interfaces.js';
+import type {
+  IProvider,
+  IProviderAuth,
+  IProviderMcp,
+  IProviderModels,
+  IProviderSessionSynchronizer,
+  IProviderSkills,
+  IProviderSessions,
+} from '@/shared/interfaces.js';
 import type { LLMProvider } from '@/shared/types.js';
 
 /**
@@ -10,9 +18,12 @@ import type { LLMProvider } from '@/shared/types.js';
  */
 export abstract class AbstractProvider implements IProvider {
   readonly id: LLMProvider;
+  abstract readonly models: IProviderModels;
   abstract readonly mcp: IProviderMcp;
   abstract readonly auth: IProviderAuth;
+  abstract readonly skills: IProviderSkills;
   abstract readonly sessions: IProviderSessions;
+  abstract readonly sessionSynchronizer: IProviderSessionSynchronizer;
 
   protected constructor(id: LLMProvider) {
     this.id = id;
diff --git a/server/modules/providers/shared/skills/skills.provider.ts b/server/modules/providers/shared/skills/skills.provider.ts
new file mode 100644
index 00000000..07e83a5b
--- /dev/null
+++ b/server/modules/providers/shared/skills/skills.provider.ts
@@ -0,0 +1,64 @@
+import path from 'node:path';
+
+import type { IProviderSkills } from '@/shared/interfaces.js';
+import type {
+  LLMProvider,
+  ProviderSkill,
+  ProviderSkillListOptions,
+  ProviderSkillSource,
+} from '@/shared/types.js';
+import {
+  findProviderSkillMarkdownFiles,
+  readProviderSkillMarkdownDefinition,
+} from '@/shared/utils.js';
+
+const resolveWorkspacePath = (workspacePath?: string): string =>
+  path.resolve(workspacePath ?? process.cwd());
+
+/**
+ * Shared skills provider for provider-specific skill source discovery.
+ */
+export abstract class SkillsProvider implements IProviderSkills {
+  protected readonly provider: LLMProvider;
+
+  protected constructor(provider: LLMProvider) {
+    this.provider = provider;
+  }
+
+  async listSkills(options?: ProviderSkillListOptions): Promise<ProviderSkill[]> {
+    const workspacePath = resolveWorkspacePath(options?.workspacePath);
+    const sources = await this.getSkillSources(workspacePath);
+    const skills: ProviderSkill[] = [];
+
+    for (const source of sources) {
+      const skillFiles = await findProviderSkillMarkdownFiles(source.rootDir, {
+        recursive: source.recursive,
+      });
+      for (const skillPath of skillFiles) {
+        try {
+          const definition = await readProviderSkillMarkdownDefinition(skillPath);
+          const command = source.commandForSkill
+            ? source.commandForSkill(definition.name)
+            : `${source.commandPrefix ?? '/'}${definition.name}`;
+
+          skills.push({
+            provider: this.provider,
+            name: definition.name,
+            description: definition.description,
+            command,
+            scope: source.scope,
+            sourcePath: skillPath,
+            pluginName: source.pluginName,
+            pluginId: source.pluginId,
+          });
+        } catch {
+          // A malformed or unreadable skill markdown file should not hide other valid skills.
+        }
+      }
+    }
+
+    return skills;
+  }
+
+  protected abstract getSkillSources(workspacePath: string): Promise<ProviderSkillSource[]>;
+}
diff --git a/server/modules/providers/tests/mcp.test.ts b/server/modules/providers/tests/mcp.test.ts
index a64914d6..f10b1354 100644
--- a/server/modules/providers/tests/mcp.test.ts
+++ b/server/modules/providers/tests/mcp.test.ts
@@ -169,6 +169,93 @@ test('providerMcpService handles codex MCP TOML config and capability validation
   }
 });
 
+/**
+ * This test covers OpenCode MCP support for user/project config files, JSONC-compatible
+ * reads, and validation for unsupported scope/transport combinations.
+ */
+test('providerMcpService handles opencode MCP config and capability validation', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-mcp-opencode-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  await fs.mkdir(workspacePath, { recursive: true });
+  await fs.mkdir(path.join(tempRoot, '.config', 'opencode'), { recursive: true });
+  await fs.writeFile(
+    path.join(tempRoot, '.config', 'opencode', 'opencode.jsonc'),
+    `{
+      // Existing comments should not block OpenCode MCP reads.
+      "mcp": {}
+    }\n`,
+    'utf8',
+  );
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  try {
+    await providerMcpService.upsertProviderMcpServer('opencode', {
+      name: 'opencode-user-stdio',
+      scope: 'user',
+      transport: 'stdio',
+      command: 'node',
+      args: ['server.js'],
+      env: { API_KEY: 'x' },
+    });
+
+    await providerMcpService.upsertProviderMcpServer('opencode', {
+      name: 'opencode-project-http',
+      scope: 'project',
+      transport: 'http',
+      url: 'https://opencode.example.com/mcp',
+      headers: { Authorization: 'Bearer token' },
+      workspacePath,
+    });
+
+    const userConfig = await readJson(path.join(tempRoot, '.config', 'opencode', 'opencode.jsonc'));
+    const userServers = userConfig.mcp as Record<string, unknown>;
+    const userStdio = userServers['opencode-user-stdio'] as Record<string, unknown>;
+    assert.equal(userStdio.type, 'local');
+    assert.deepEqual(userStdio.command, ['node', 'server.js']);
+    assert.deepEqual(userStdio.environment, { API_KEY: 'x' });
+
+    const projectConfig = await readJson(path.join(workspacePath, 'opencode.json'));
+    const projectServers = projectConfig.mcp as Record<string, unknown>;
+    const projectHttp = projectServers['opencode-project-http'] as Record<string, unknown>;
+    assert.equal(projectHttp.type, 'remote');
+    assert.equal(projectHttp.url, 'https://opencode.example.com/mcp');
+
+    const grouped = await providerMcpService.listProviderMcpServers('opencode', { workspacePath });
+    assert.ok(grouped.user.some((server) => server.name === 'opencode-user-stdio' && server.transport === 'stdio'));
+    assert.ok(grouped.project.some((server) => server.name === 'opencode-project-http' && server.transport === 'http'));
+
+    await assert.rejects(
+      providerMcpService.upsertProviderMcpServer('opencode', {
+        name: 'opencode-local',
+        scope: 'local',
+        transport: 'stdio',
+        command: 'node',
+      }),
+      (error: unknown) =>
+        error instanceof AppError &&
+        error.code === 'MCP_SCOPE_NOT_SUPPORTED' &&
+        error.statusCode === 400,
+    );
+
+    await assert.rejects(
+      providerMcpService.upsertProviderMcpServer('opencode', {
+        name: 'opencode-sse',
+        scope: 'project',
+        transport: 'sse',
+        url: 'https://example.com/sse',
+        workspacePath,
+      }),
+      (error: unknown) =>
+        error instanceof AppError &&
+        error.code === 'MCP_TRANSPORT_NOT_SUPPORTED' &&
+        error.statusCode === 400,
+    );
+  } finally {
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
 /**
  * This test covers Gemini/Cursor MCP JSON formats and user/project scope persistence.
  */
@@ -254,8 +341,7 @@ test('providerMcpService global adder writes to all providers and rejects unsupp
       workspacePath,
     });
 
-    const expectCursorGlobal = process.platform !== 'win32';
-    assert.equal(globalResult.length, expectCursorGlobal ? 4 : 3);
+    assert.equal(globalResult.length, 5);
     assert.ok(globalResult.every((entry) => entry.created === true));
 
     const claudeProject = await readJson(path.join(workspacePath, '.mcp.json'));
@@ -267,10 +353,11 @@ test('providerMcpService global adder writes to all providers and rejects unsupp
     const geminiProject = await readJson(path.join(workspacePath, '.gemini', 'settings.json'));
     assert.ok((geminiProject.mcpServers as Record<string, unknown>)['global-http']);
 
-    if (expectCursorGlobal) {
-      const cursorProject = await readJson(path.join(workspacePath, '.cursor', 'mcp.json'));
-      assert.ok((cursorProject.mcpServers as Record<string, unknown>)['global-http']);
-    }
+    const opencodeProject = await readJson(path.join(workspacePath, 'opencode.json'));
+    assert.ok((opencodeProject.mcp as Record<string, unknown>)['global-http']);
+
+    const cursorProject = await readJson(path.join(workspacePath, '.cursor', 'mcp.json'));
+    assert.ok((cursorProject.mcpServers as Record<string, unknown>)['global-http']);
 
     await assert.rejects(
       providerMcpService.addMcpServerToAllProviders({
diff --git a/server/modules/providers/tests/opencode-models.test.ts b/server/modules/providers/tests/opencode-models.test.ts
new file mode 100644
index 00000000..c28ac0ef
--- /dev/null
+++ b/server/modules/providers/tests/opencode-models.test.ts
@@ -0,0 +1,73 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  buildOpenCodeDefinitionFromIds,
+  parseOpenCodeModelsStdout,
+} from '@/modules/providers/list/opencode/opencode-models.provider.js';
+
+test('OpenCode models provider parses plain CLI output and removes duplicates', () => {
+  const ids = parseOpenCodeModelsStdout(`
+opencode/big-pickle
+not a model
+anthropic/claude-opus-4-7-fast
+anthropic/claude-opus-4-7-fast
+openai/gpt-5.5-pro
+`);
+
+  assert.deepEqual(ids, [
+    'opencode/big-pickle',
+    'anthropic/claude-opus-4-7-fast',
+    'openai/gpt-5.5-pro',
+  ]);
+});
+
+test('OpenCode models provider formats frontend labels from provider-prefixed ids', () => {
+  const definition = buildOpenCodeDefinitionFromIds([
+    'opencode/deepseek-v4-flash-free',
+    'opencode/nemotron-3-super-free',
+    'anthropic/claude-3-5-sonnet-20241022',
+    'anthropic/claude-opus-4-7-fast',
+    'openai/gpt-5.4-mini-fast',
+    'openai/gpt-5.5-pro',
+    'newprovider/alpha-v12-special-20261231',
+  ]);
+
+  assert.deepEqual(definition.OPTIONS, [
+    {
+      value: 'opencode/deepseek-v4-flash-free',
+      label: 'Deepseek V4 Flash Free',
+      description: 'opencode - opencode/deepseek-v4-flash-free',
+    },
+    {
+      value: 'opencode/nemotron-3-super-free',
+      label: 'Nemotron 3 Super Free',
+      description: 'opencode - opencode/nemotron-3-super-free',
+    },
+    {
+      value: 'anthropic/claude-3-5-sonnet-20241022',
+      label: 'Claude 3.5 Sonnet (2024-10-22)',
+      description: 'anthropic - anthropic/claude-3-5-sonnet-20241022',
+    },
+    {
+      value: 'anthropic/claude-opus-4-7-fast',
+      label: 'Claude Opus 4.7 Fast',
+      description: 'anthropic - anthropic/claude-opus-4-7-fast',
+    },
+    {
+      value: 'openai/gpt-5.4-mini-fast',
+      label: 'GPT-5.4 Mini Fast',
+      description: 'openai - openai/gpt-5.4-mini-fast',
+    },
+    {
+      value: 'openai/gpt-5.5-pro',
+      label: 'GPT-5.5 Pro',
+      description: 'openai - openai/gpt-5.5-pro',
+    },
+    {
+      value: 'newprovider/alpha-v12-special-20261231',
+      label: 'Alpha V12 Special (2026-12-31)',
+      description: 'newprovider - newprovider/alpha-v12-special-20261231',
+    },
+  ]);
+});
diff --git a/server/modules/providers/tests/opencode-sessions.test.ts b/server/modules/providers/tests/opencode-sessions.test.ts
new file mode 100644
index 00000000..d5b65e4e
--- /dev/null
+++ b/server/modules/providers/tests/opencode-sessions.test.ts
@@ -0,0 +1,334 @@
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import Database from 'better-sqlite3';
+
+import { closeConnection, initializeDatabase, sessionsDb } from '@/modules/database/index.js';
+import { OpenCodeSessionSynchronizer } from '@/modules/providers/list/opencode/opencode-session-synchronizer.provider.js';
+import { OpenCodeSessionsProvider } from '@/modules/providers/list/opencode/opencode-sessions.provider.js';
+
+const patchHomeDir = (nextHomeDir: string) => {
+  const original = os.homedir;
+  (os as any).homedir = () => nextHomeDir;
+  return () => {
+    (os as any).homedir = original;
+  };
+};
+
+async function withIsolatedDatabase(runTest: () => void | Promise<void>): Promise<void> {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const tempDirectory = await mkdtemp(path.join(os.tmpdir(), 'opencode-provider-db-'));
+  const databasePath = path.join(tempDirectory, 'auth.db');
+
+  closeConnection();
+  process.env.DATABASE_PATH = databasePath;
+  await initializeDatabase();
+
+  try {
+    await runTest();
+  } finally {
+    closeConnection();
+    if (previousDatabasePath === undefined) {
+      delete process.env.DATABASE_PATH;
+    } else {
+      process.env.DATABASE_PATH = previousDatabasePath;
+    }
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+}
+
+const createOpenCodeDatabase = async (homeDir: string, workspacePath: string): Promise<void> => {
+  const dataDir = path.join(homeDir, '.local', 'share', 'opencode');
+  await mkdir(dataDir, { recursive: true });
+
+  const db = new Database(path.join(dataDir, 'opencode.db'));
+  try {
+    db.exec(`
+      CREATE TABLE project (
+        id TEXT PRIMARY KEY,
+        worktree TEXT NOT NULL,
+        vcs TEXT,
+        name TEXT,
+        icon_url TEXT,
+        icon_color TEXT,
+        time_created INTEGER NOT NULL,
+        time_updated INTEGER NOT NULL,
+        time_initialized INTEGER,
+        sandboxes TEXT NOT NULL,
+        commands TEXT,
+        icon_url_override TEXT
+      );
+
+      CREATE TABLE session (
+        id TEXT PRIMARY KEY,
+        project_id TEXT NOT NULL,
+        parent_id TEXT,
+        slug TEXT NOT NULL,
+        directory TEXT NOT NULL,
+        title TEXT NOT NULL,
+        version TEXT NOT NULL,
+        share_url TEXT,
+        summary_additions INTEGER,
+        summary_deletions INTEGER,
+        summary_files INTEGER,
+        summary_diffs TEXT,
+        revert TEXT,
+        permission TEXT,
+        time_created INTEGER NOT NULL,
+        time_updated INTEGER NOT NULL,
+        time_compacting INTEGER,
+        time_archived INTEGER,
+        workspace_id TEXT,
+        path TEXT,
+        agent TEXT,
+        model TEXT,
+        cost REAL NOT NULL DEFAULT 0,
+        tokens_input INTEGER NOT NULL DEFAULT 0,
+        tokens_output INTEGER NOT NULL DEFAULT 0,
+        tokens_reasoning INTEGER NOT NULL DEFAULT 0,
+        tokens_cache_read INTEGER NOT NULL DEFAULT 0,
+        tokens_cache_write INTEGER NOT NULL DEFAULT 0,
+        FOREIGN KEY (project_id) REFERENCES project(id) ON DELETE CASCADE
+      );
+
+      CREATE TABLE message (
+        id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        time_created INTEGER NOT NULL,
+        time_updated INTEGER NOT NULL,
+        data TEXT NOT NULL,
+        FOREIGN KEY (session_id) REFERENCES session(id) ON DELETE CASCADE
+      );
+
+      CREATE TABLE part (
+        id TEXT PRIMARY KEY,
+        message_id TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        time_created INTEGER NOT NULL,
+        time_updated INTEGER NOT NULL,
+        data TEXT NOT NULL,
+        FOREIGN KEY (message_id) REFERENCES message(id) ON DELETE CASCADE
+      );
+
+      CREATE INDEX part_session_idx ON part (session_id);
+      CREATE INDEX session_project_idx ON session (project_id);
+      CREATE INDEX message_session_time_created_id_idx ON message (session_id, time_created, id);
+      CREATE INDEX part_message_id_id_idx ON part (message_id, id);
+    `);
+
+    db.prepare(
+      'INSERT INTO project (id, worktree, time_created, time_updated, sandboxes) VALUES (?, ?, ?, ?, ?)',
+    ).run(
+      'project-1',
+      workspacePath,
+      1_700_000_000_000,
+      1_700_000_001_000,
+      '[]',
+    );
+    db.prepare(`
+      INSERT INTO session (
+        id, project_id, slug, directory, title, version, time_created, time_updated, time_archived,
+        tokens_input, tokens_output, tokens_reasoning, tokens_cache_read, tokens_cache_write
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      'open-session-1',
+      'project-1',
+      'open-session-1',
+      workspacePath,
+      'OpenCode indexed title',
+      '0.0.0',
+      1_700_000_000_000,
+      1_700_000_004_000,
+      null,
+      10,
+      20,
+      7,
+      3,
+      2,
+    );
+
+    const userMessageData = JSON.stringify({
+      role: 'user',
+      time: { created: 1_700_000_001_000 },
+      agent: 'test',
+      model: { providerID: 'anthropic', modelID: 'claude' },
+    });
+    const assistantMessageData = JSON.stringify({
+      role: 'assistant',
+      time: { created: 1_700_000_002_000, completed: 1_700_000_003_000 },
+      parentID: 'message-user',
+      modelID: 'anthropic/claude-sonnet-4-5',
+      providerID: 'anthropic',
+      mode: 'default',
+      agent: 'test',
+      path: { cwd: '.', root: '.' },
+      cost: 0.01,
+      tokens: {
+        input: 10,
+        output: 20,
+        reasoning: 0,
+        cache: { read: 3, write: 2 },
+      },
+    });
+
+    db.prepare(
+      'INSERT INTO message (id, session_id, time_created, time_updated, data) VALUES (?, ?, ?, ?, ?)',
+    ).run('message-user', 'open-session-1', 1_700_000_001_000, 1_700_000_001_500, userMessageData);
+    db.prepare(
+      'INSERT INTO message (id, session_id, time_created, time_updated, data) VALUES (?, ?, ?, ?, ?)',
+    ).run('message-assistant', 'open-session-1', 1_700_000_002_000, 1_700_000_003_000, assistantMessageData);
+
+    const insertPart = db.prepare(`
+      INSERT INTO part (id, message_id, session_id, time_created, time_updated, data)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `);
+    insertPart.run(
+      'part-user-text',
+      'message-user',
+      'open-session-1',
+      1_700_000_001_000,
+      1_700_000_001_000,
+      JSON.stringify({
+        type: 'text',
+        text: JSON.stringify('Build the OpenCode integration.'),
+      }),
+    );
+    insertPart.run(
+      'part-reasoning',
+      'message-assistant',
+      'open-session-1',
+      1_700_000_002_000,
+      1_700_000_002_000,
+      JSON.stringify({
+        type: 'reasoning',
+        text: 'I will inspect the provider shape first.',
+        time: { start: 0, end: 1 },
+      }),
+    );
+    insertPart.run(
+      'part-assistant-text',
+      'message-assistant',
+      'open-session-1',
+      1_700_000_002_500,
+      1_700_000_002_500,
+      JSON.stringify({
+        type: 'text',
+        text: 'The provider is wired.',
+      }),
+    );
+    insertPart.run(
+      'part-tool',
+      'message-assistant',
+      'open-session-1',
+      1_700_000_003_000,
+      1_700_000_003_000,
+      JSON.stringify({
+        type: 'tool',
+        tool: 'bash',
+        callID: 'tool-call-1',
+        state: {
+          status: 'completed',
+          input: { command: 'npm test' },
+          output: 'ok',
+          title: 'bash',
+          metadata: {},
+          time: { start: 0, end: 1 },
+        },
+      }),
+    );
+  } finally {
+    db.close();
+  }
+};
+
+test('OpenCode session synchronizer indexes sqlite sessions without deletable transcript paths', { concurrency: false }, async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'opencode-session-sync-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  await mkdir(workspacePath, { recursive: true });
+  const restoreHomeDir = patchHomeDir(tempRoot);
+
+  try {
+    await createOpenCodeDatabase(tempRoot, workspacePath);
+    await withIsolatedDatabase(() => {
+      const synchronizer = new OpenCodeSessionSynchronizer();
+      const processed = synchronizer.synchronize();
+
+      return Promise.resolve(processed).then((count) => {
+        assert.equal(count, 1);
+        const indexed = sessionsDb.getSessionById('open-session-1');
+        assert.equal(indexed?.provider, 'opencode');
+        assert.equal(indexed?.project_path, workspacePath);
+        assert.equal(indexed?.custom_name, 'OpenCode indexed title');
+        assert.equal(indexed?.jsonl_path, null);
+      });
+    });
+  } finally {
+    restoreHomeDir();
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+test('OpenCode sessions provider normalizes quoted live text and skips user echoes', () => {
+  const provider = new OpenCodeSessionsProvider();
+  const normalized = provider.normalizeMessage({
+    type: 'text',
+    sessionID: 'open-session-live',
+    text: JSON.stringify('hello bro'),
+  }, null);
+
+  assert.equal(normalized.length, 1);
+  assert.equal(normalized[0]?.kind, 'stream_delta');
+  assert.equal(normalized[0]?.content, 'hello bro');
+
+  const userEcho = provider.normalizeMessage({
+    type: 'text',
+    sessionID: 'open-session-live',
+    role: 'user',
+    text: 'hello bro',
+  }, null);
+
+  assert.deepEqual(userEcho, []);
+});
+
+test('OpenCode sessions provider reads sqlite history and token usage', { concurrency: false }, async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'opencode-session-history-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  await mkdir(workspacePath, { recursive: true });
+  const restoreHomeDir = patchHomeDir(tempRoot);
+
+  try {
+    await createOpenCodeDatabase(tempRoot, workspacePath);
+    const provider = new OpenCodeSessionsProvider();
+    const history = await provider.fetchHistory('open-session-1');
+
+    assert.equal(history.total, 4);
+    assert.equal(history.messages[0]?.kind, 'text');
+    assert.equal(history.messages[0]?.role, 'user');
+    assert.equal(history.messages[0]?.content, 'Build the OpenCode integration.');
+    assert.equal(history.messages[1]?.kind, 'thinking');
+    assert.equal(history.messages[2]?.content, 'The provider is wired.');
+    assert.equal(history.messages[3]?.kind, 'tool_use');
+    assert.deepEqual(history.messages[3]?.toolResult, { content: 'ok', isError: false });
+    assert.deepEqual(history.tokenUsage, {
+      used: 42,
+      inputTokens: 13,
+      outputTokens: 20,
+      breakdown: {
+        input: 13,
+        output: 20,
+      },
+    });
+
+    const paged = await provider.fetchHistory('open-session-1', { limit: 2, offset: 0 });
+    assert.equal(paged.messages.length, 2);
+    assert.equal(paged.hasMore, true);
+    assert.equal(paged.messages[0]?.content, 'The provider is wired.');
+  } finally {
+    restoreHomeDir();
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+});
diff --git a/server/modules/providers/tests/provider-models.service.test.ts b/server/modules/providers/tests/provider-models.service.test.ts
new file mode 100644
index 00000000..fb9ebf7d
--- /dev/null
+++ b/server/modules/providers/tests/provider-models.service.test.ts
@@ -0,0 +1,318 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import {
+  createProviderModelsService,
+  PROVIDER_MODELS_CACHE_TTL_MS,
+} from '@/modules/providers/services/provider-models.service.js';
+import type {
+  ProviderChangeActiveModelInput,
+  LLMProvider,
+  ProviderCurrentActiveModel,
+  ProviderModelsDefinition,
+  ProviderSessionActiveModelChange,
+} from '@/shared/types.js';
+import { writeProviderSessionActiveModelChange } from '@/shared/utils.js';
+
+const createModels = (value: string): ProviderModelsDefinition => ({
+  OPTIONS: [{ value, label: value }],
+  DEFAULT: value,
+});
+
+const createCurrentActiveModel = (model: string): ProviderCurrentActiveModel => ({
+  model,
+});
+
+const createSessionActiveModelChange = (
+  provider: LLMProvider,
+  input: ProviderChangeActiveModelInput,
+): ProviderSessionActiveModelChange => ({
+  provider,
+  sessionId: input.sessionId,
+  supported: true,
+  changed: true,
+  model: input.model,
+});
+
+const createEphemeralCachePath = (): string => path.join(
+  os.tmpdir(),
+  `provider-model-cache-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.json`,
+);
+
+test('provider models service delegates to the resolved provider model adapter', async () => {
+  const calls: LLMProvider[] = [];
+  const service = createProviderModelsService({
+    cachePath: createEphemeralCachePath(),
+    resolveProvider: (provider) => {
+      calls.push(provider);
+      return {
+        models: {
+          getSupportedModels: async () => createModels(`${provider}-models`),
+          getCurrentActiveModel: async () => createCurrentActiveModel(`${provider}-active`),
+          changeActiveModel: async (input) => createSessionActiveModelChange(provider, input),
+        },
+      };
+    },
+  });
+
+  const models = await service.getProviderModels('codex', { bypassCache: true });
+
+  assert.deepEqual(calls, ['codex']);
+  assert.equal(models.models.DEFAULT, 'codex-models');
+  assert.equal(models.cache.source, 'fresh');
+});
+
+test('provider models service returns each provider adapter result without rewriting it', async () => {
+  const expectedModels: ProviderModelsDefinition = {
+    OPTIONS: [
+      { value: 'cursor-a', label: 'Cursor A' },
+      { value: 'cursor-b', label: 'Cursor B' },
+    ],
+    DEFAULT: 'cursor-b',
+  };
+
+  const service = createProviderModelsService({
+    cachePath: createEphemeralCachePath(),
+    resolveProvider: () => ({
+      models: {
+        getSupportedModels: async () => expectedModels,
+        getCurrentActiveModel: async () => createCurrentActiveModel('cursor-active'),
+        changeActiveModel: async (input) => createSessionActiveModelChange('cursor', input),
+      },
+    }),
+  });
+
+  const models = await service.getProviderModels('cursor', { bypassCache: true });
+
+  assert.deepEqual(models.models, expectedModels);
+});
+
+test('provider models are cached for the three-day ttl', async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'provider-model-cache-ttl-'));
+  let currentTime = 1_000;
+  let loadCount = 0;
+
+  try {
+    const service = createProviderModelsService({
+      cachePath: path.join(tempRoot, 'models-cache.json'),
+      now: () => currentTime,
+      resolveProvider: (provider) => ({
+        models: {
+          getSupportedModels: async () => {
+            loadCount += 1;
+            return createModels(`${provider}-${loadCount}`);
+          },
+          getCurrentActiveModel: async () => createCurrentActiveModel(`${provider}-active`),
+          changeActiveModel: async (input) => createSessionActiveModelChange(provider, input),
+        },
+      }),
+    });
+
+    const first = await service.getProviderModels('codex');
+    const cached = await service.getProviderModels('codex');
+    assert.equal(loadCount, 1);
+    assert.equal(cached.models.DEFAULT, first.models.DEFAULT);
+    assert.equal(cached.cache.source, 'memory');
+
+    currentTime += PROVIDER_MODELS_CACHE_TTL_MS - 1;
+    await service.getProviderModels('codex');
+    assert.equal(loadCount, 1);
+
+    currentTime += 2;
+    const refreshed = await service.getProviderModels('codex');
+    assert.equal(loadCount, 2);
+    assert.equal(refreshed.models.DEFAULT, 'codex-2');
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+test('provider model cache is persisted across service instances', async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'provider-model-cache-file-'));
+  const cachePath = path.join(tempRoot, 'models-cache.json');
+
+  try {
+    const writer = createProviderModelsService({
+      cachePath,
+      resolveProvider: () => ({
+        models: {
+          getSupportedModels: async () => createModels('gemini-cached'),
+          getCurrentActiveModel: async () => createCurrentActiveModel('gemini-active'),
+          changeActiveModel: async (input) => createSessionActiveModelChange('gemini', input),
+        },
+      }),
+    });
+    await writer.getProviderModels('gemini');
+
+    const reader = createProviderModelsService({
+      cachePath,
+      resolveProvider: () => ({
+        models: {
+          getSupportedModels: async () => {
+            throw new Error('loader should not be called for persisted cache hits');
+          },
+          getCurrentActiveModel: async () => createCurrentActiveModel('gemini-active'),
+          changeActiveModel: async (input) => createSessionActiveModelChange('gemini', input),
+        },
+      }),
+    });
+    const models = await reader.getProviderModels('gemini');
+    assert.equal(models.models.DEFAULT, 'gemini-cached');
+    assert.equal(models.cache.source, 'disk');
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+test('concurrent provider model requests share one load operation', async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'provider-model-cache-pending-'));
+  let loadCount = 0;
+
+  try {
+    const service = createProviderModelsService({
+      cachePath: path.join(tempRoot, 'models-cache.json'),
+      resolveProvider: () => ({
+        models: {
+          getSupportedModels: async () => {
+            loadCount += 1;
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            return createModels('claude-cached');
+          },
+          getCurrentActiveModel: async () => createCurrentActiveModel('claude-active'),
+          changeActiveModel: async (input) => createSessionActiveModelChange('claude', input),
+        },
+      }),
+    });
+
+    const [first, second] = await Promise.all([
+      service.getProviderModels('claude'),
+      service.getProviderModels('claude'),
+    ]);
+
+    assert.equal(loadCount, 1);
+    assert.equal(first.models.DEFAULT, 'claude-cached');
+    assert.equal(second.models.DEFAULT, 'claude-cached');
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+test('bypassCache forces a fresh provider fetch and updates cache metadata', async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'provider-model-cache-refresh-'));
+  let currentTime = 1_000;
+  let loadCount = 0;
+
+  try {
+    const service = createProviderModelsService({
+      cachePath: path.join(tempRoot, 'models-cache.json'),
+      now: () => currentTime,
+      resolveProvider: (provider) => ({
+        models: {
+          getSupportedModels: async () => {
+            loadCount += 1;
+            return createModels(`${provider}-${loadCount}`);
+          },
+          getCurrentActiveModel: async () => createCurrentActiveModel(`${provider}-active-${loadCount}`),
+          changeActiveModel: async (input) => createSessionActiveModelChange(provider, input),
+        },
+      }),
+    });
+
+    const first = await service.getProviderModels('claude');
+    currentTime += 50;
+    const refreshed = await service.getProviderModels('claude', { bypassCache: true });
+
+    assert.equal(first.models.DEFAULT, 'claude-1');
+    assert.equal(refreshed.models.DEFAULT, 'claude-2');
+    assert.equal(refreshed.cache.source, 'fresh');
+    assert.notEqual(refreshed.cache.updatedAt, first.cache.updatedAt);
+    assert.equal(loadCount, 2);
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+test('provider models service delegates current active model lookups to the provider adapter', async () => {
+  const calls: Array<{ provider: LLMProvider; sessionId?: string }> = [];
+  const service = createProviderModelsService({
+    resolveProvider: (provider) => ({
+      models: {
+        getSupportedModels: async () => createModels(`${provider}-models`),
+        getCurrentActiveModel: async (sessionId) => {
+          calls.push({ provider, sessionId });
+          return createCurrentActiveModel(`${provider}-${sessionId}`);
+        },
+        changeActiveModel: async (input) => createSessionActiveModelChange(provider, input),
+      },
+    }),
+  });
+
+  const activeModel = await service.getCurrentActiveModel('opencode', 'session-123');
+
+  assert.deepEqual(calls, [{ provider: 'opencode', sessionId: 'session-123' }]);
+  assert.equal(activeModel.model, 'opencode-session-123');
+});
+
+test('provider models service delegates active model change requests to the provider adapter', async () => {
+  const calls: Array<{ provider: LLMProvider; input: ProviderChangeActiveModelInput }> = [];
+  const service = createProviderModelsService({
+    resolveProvider: (provider) => ({
+      models: {
+        getSupportedModels: async () => createModels(`${provider}-models`),
+        getCurrentActiveModel: async () => createCurrentActiveModel(`${provider}-active`),
+        changeActiveModel: async (input) => {
+          calls.push({ provider, input });
+          return createSessionActiveModelChange(provider, input);
+        },
+      },
+    }),
+  });
+
+  const changedModel = await service.changeActiveModel('claude', {
+    sessionId: 'session-123',
+    model: 'opus',
+  });
+
+  assert.deepEqual(calls, [{
+    provider: 'claude',
+    input: {
+      sessionId: 'session-123',
+      model: 'opus',
+    },
+  }]);
+  assert.equal(changedModel.changed, true);
+  assert.equal(changedModel.model, 'opus');
+});
+
+test('resolveResumeModel prefers a stored changed model over the requested one', async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'provider-model-change-'));
+  const activeModelChangesPath = path.join(tempRoot, 'session-model-changes.json');
+
+  try {
+    const service = createProviderModelsService({
+      activeModelChangesPath,
+      resolveProvider: (provider) => ({
+        models: {
+          getSupportedModels: async () => createModels(`${provider}-models`),
+          getCurrentActiveModel: async () => createCurrentActiveModel(`${provider}-active`),
+          changeActiveModel: async (input) => createSessionActiveModelChange(provider, input),
+        },
+      }),
+    });
+
+    await writeProviderSessionActiveModelChange('cursor', {
+      sessionId: 'session-456',
+      model: 'composer-2',
+    }, {
+      filePath: activeModelChangesPath,
+    });
+
+    const model = await service.resolveResumeModel('cursor', 'session-456', 'composer-2-fast');
+    assert.equal(model, 'composer-2');
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+});
diff --git a/server/modules/providers/tests/skills.test.ts b/server/modules/providers/tests/skills.test.ts
new file mode 100644
index 00000000..2c32c67b
--- /dev/null
+++ b/server/modules/providers/tests/skills.test.ts
@@ -0,0 +1,512 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { providerSkillsService } from '@/modules/providers/services/skills.service.js';
+
+const patchHomeDir = (nextHomeDir: string) => {
+  const original = os.homedir;
+  (os as any).homedir = () => nextHomeDir;
+  return () => {
+    (os as any).homedir = original;
+  };
+};
+
+const writeSkill = async (
+  skillsRoot: string,
+  directoryName: string,
+  name: string,
+  description: string,
+): Promise<string> => {
+  const skillDir = path.join(skillsRoot, directoryName);
+  await fs.mkdir(skillDir, { recursive: true });
+  const skillPath = path.join(skillDir, 'SKILL.md');
+  await fs.writeFile(
+    skillPath,
+    `---\nname: ${name}\ndescription: ${description}\n---\n\n`,
+    'utf8',
+  );
+  return skillPath;
+};
+
+const writeClaudePluginManifest = async (
+  installPath: string,
+  name: string,
+): Promise<void> => {
+  const pluginConfigDir = path.join(installPath, '.claude-plugin');
+  await fs.mkdir(pluginConfigDir, { recursive: true });
+  await fs.writeFile(
+    path.join(pluginConfigDir, 'plugin.json'),
+    JSON.stringify(
+      {
+        name,
+        version: '0.1.0',
+        description: `${name} test plugin`,
+      },
+      null,
+      2,
+    ),
+    'utf8',
+  );
+};
+
+const writeClaudePluginCommand = async (
+  commandsRoot: string,
+  commandName: string,
+  description: string,
+): Promise<string> => {
+  await fs.mkdir(commandsRoot, { recursive: true });
+  const commandPath = path.join(commandsRoot, `${commandName}.md`);
+  await fs.writeFile(
+    commandPath,
+    `---\ndescription: ${description}\nargument-hint: 'test args'\n---\n\nCommand body.\n`,
+    'utf8',
+  );
+  return commandPath;
+};
+
+/**
+ * This test covers Claude user/project skill folders plus plugin discovery from
+ * installed plugin command files and fallback plugin skill files.
+ */
+test('providerSkillsService lists claude user, project, and enabled plugin skills', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-skills-claude-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  const commandPluginInstallPath = path.join(
+    tempRoot,
+    '.claude',
+    'plugins',
+    'cache',
+    'notion-plugin',
+    'notion',
+    'abc123',
+  );
+  const skillPluginInstallPath = path.join(
+    tempRoot,
+    '.claude',
+    'plugins',
+    'cache',
+    'anthropic-agent-skills',
+    'example-skills',
+    'def456',
+  );
+  const disabledPluginInstallPath = path.join(
+    tempRoot,
+    '.claude',
+    'plugins',
+    'cache',
+    'disabled-marketplace',
+    'disabled-skills',
+    'ghi789',
+  );
+  const emptyIdPluginInstallPath = path.join(
+    tempRoot,
+    '.claude',
+    'plugins',
+    'cache',
+    'invalid-empty-plugin',
+    'empty',
+    '000',
+  );
+  const atIdPluginInstallPath = path.join(
+    tempRoot,
+    '.claude',
+    'plugins',
+    'cache',
+    'invalid-at-plugin',
+    'at',
+    '000',
+  );
+  const siblingSkillPluginPath = path.join(path.dirname(skillPluginInstallPath), 'legacy777');
+  await fs.mkdir(workspacePath, { recursive: true });
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  try {
+    await writeSkill(
+      path.join(tempRoot, '.claude', 'skills'),
+      'claude-user-dir',
+      'claude-user',
+      'Claude user skill',
+    );
+    await writeSkill(
+      path.join(workspacePath, '.claude', 'skills'),
+      'claude-project-dir',
+      'claude-project',
+      'Claude project skill',
+    );
+    await writeClaudePluginManifest(commandPluginInstallPath, 'Notion');
+    await writeClaudePluginCommand(
+      path.join(commandPluginInstallPath, 'commands'),
+      'insert-row',
+      'Insert a Notion database row',
+    );
+    await writeSkill(
+      path.join(commandPluginInstallPath, 'skills'),
+      'ignored-command-plugin-skill-dir',
+      'ignored-command-plugin-skill',
+      'Command plugin fallback skill should be ignored',
+    );
+    await writeClaudePluginManifest(skillPluginInstallPath, 'ExampleSkills');
+    await writeSkill(
+      path.join(skillPluginInstallPath, 'skills'),
+      'claude-plugin-dir',
+      'claude-plugin',
+      'Claude plugin skill',
+    );
+    await writeSkill(
+      path.join(skillPluginInstallPath, 'skills'),
+      'claude-plugin-second-dir',
+      'claude-plugin-second',
+      'Second Claude plugin skill',
+    );
+    await writeSkill(
+      path.join(skillPluginInstallPath, 'skills', 'nested', 'collection'),
+      'claude-plugin-nested-dir',
+      'claude-plugin-nested',
+      'Nested Claude plugin skill',
+    );
+    await writeSkill(
+      path.join(siblingSkillPluginPath, 'skills'),
+      'claude-plugin-sibling-dir',
+      'claude-plugin-sibling',
+      'Sibling Claude plugin skill',
+    );
+    await writeClaudePluginManifest(disabledPluginInstallPath, 'DisabledSkills');
+    await writeClaudePluginCommand(
+      path.join(disabledPluginInstallPath, 'commands'),
+      'disabled-command',
+      'Disabled plugin command',
+    );
+    await writeClaudePluginCommand(
+      path.join(emptyIdPluginInstallPath, 'commands'),
+      'invalid-empty-command',
+      'Invalid empty id command',
+    );
+    await writeClaudePluginCommand(
+      path.join(atIdPluginInstallPath, 'commands'),
+      'invalid-at-command',
+      'Invalid at id command',
+    );
+    await writeSkill(
+      path.join(
+        disabledPluginInstallPath,
+        'skills',
+      ),
+      'disabled-plugin-dir',
+      'disabled-plugin',
+      'Disabled plugin skill',
+    );
+
+    await fs.writeFile(
+      path.join(tempRoot, '.claude', 'settings.json'),
+      JSON.stringify(
+        {
+          enabledPlugins: {
+            '': true,
+            '@': true,
+            'notion@notion-marketplace': true,
+            'example-skills@anthropic-agent-skills': true,
+            'disabled-skills@disabled-marketplace': false,
+          },
+        },
+        null,
+        2,
+      ),
+      'utf8',
+    );
+    await fs.writeFile(
+      path.join(tempRoot, '.claude', 'plugins', 'installed_plugins.json'),
+      JSON.stringify(
+        {
+          version: 2,
+          plugins: {
+            '': [
+              {
+                scope: 'user',
+                installPath: emptyIdPluginInstallPath,
+                version: '000',
+              },
+            ],
+            '@': [
+              {
+                scope: 'user',
+                installPath: atIdPluginInstallPath,
+                version: '000',
+              },
+            ],
+            'notion@notion-marketplace': [
+              {
+                scope: 'user',
+                installPath: commandPluginInstallPath,
+                version: 'abc123',
+              },
+            ],
+            'example-skills@anthropic-agent-skills': [
+              {
+                scope: 'user',
+                installPath: skillPluginInstallPath,
+                version: 'def456',
+              },
+            ],
+            'disabled-skills@disabled-marketplace': [
+              {
+                scope: 'user',
+                installPath: disabledPluginInstallPath,
+                version: 'ghi789',
+              },
+            ],
+          },
+        },
+        null,
+        2,
+      ),
+      'utf8',
+    );
+
+    const skills = await providerSkillsService.listProviderSkills('claude', { workspacePath });
+    const byName = new Map(skills.map((skill) => [skill.name, skill]));
+
+    assert.equal(byName.get('claude-user')?.scope, 'user');
+    assert.equal(byName.get('claude-user')?.command, '/claude-user');
+    assert.equal(byName.get('claude-project')?.scope, 'project');
+    assert.equal(byName.get('claude-project')?.command, '/claude-project');
+
+    const pluginCommand = byName.get('insert-row');
+    assert.equal(pluginCommand?.scope, 'plugin');
+    assert.equal(pluginCommand?.pluginName, 'Notion');
+    assert.equal(pluginCommand?.pluginId, 'notion@notion-marketplace');
+    assert.equal(pluginCommand?.command, '/Notion:insert-row');
+    assert.equal(pluginCommand?.description, 'Insert a Notion database row');
+    assert.match(pluginCommand?.sourcePath ?? '', /commands[\\/]insert-row\.md$/);
+    assert.equal(byName.has('ignored-command-plugin-skill'), false);
+
+    const pluginSkill = byName.get('claude-plugin');
+    assert.equal(pluginSkill?.scope, 'plugin');
+    assert.equal(pluginSkill?.pluginName, 'ExampleSkills');
+    assert.equal(pluginSkill?.pluginId, 'example-skills@anthropic-agent-skills');
+    assert.equal(pluginSkill?.command, '/ExampleSkills:claude-plugin');
+    assert.equal(pluginSkill?.description, 'Claude plugin skill');
+    assert.match(
+      pluginSkill?.sourcePath ?? '',
+      /cache[\\/]anthropic-agent-skills[\\/]example-skills[\\/]def456[\\/]skills[\\/]/,
+    );
+
+    const secondPluginSkill = byName.get('claude-plugin-second');
+    assert.equal(secondPluginSkill?.scope, 'plugin');
+    assert.equal(secondPluginSkill?.command, '/ExampleSkills:claude-plugin-second');
+
+    const nestedPluginSkill = byName.get('claude-plugin-nested');
+    assert.equal(nestedPluginSkill?.scope, 'plugin');
+    assert.equal(nestedPluginSkill?.command, '/ExampleSkills:claude-plugin-nested');
+    assert.equal(nestedPluginSkill?.description, 'Nested Claude plugin skill');
+
+    const siblingPluginSkill = byName.get('claude-plugin-sibling');
+    assert.equal(siblingPluginSkill?.scope, 'plugin');
+    assert.equal(siblingPluginSkill?.pluginName, 'example-skills');
+    assert.equal(siblingPluginSkill?.command, '/example-skills:claude-plugin-sibling');
+    assert.equal(siblingPluginSkill?.description, 'Sibling Claude plugin skill');
+    assert.equal(byName.has('disabled-command'), false);
+    assert.equal(byName.has('disabled-plugin'), false);
+    assert.equal(byName.has('invalid-empty-command'), false);
+    assert.equal(byName.has('invalid-at-command'), false);
+    assert.equal(skills.some((skill) => skill.command.startsWith('/:')), false);
+  } finally {
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+/**
+ * This test covers Codex repository/user/system skill folders and verifies that
+ * repository lookup includes cwd, parent, and git root skill locations.
+ */
+test('providerSkillsService lists codex repository, user, and system skills', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-skills-codex-'));
+  const repoRoot = path.join(tempRoot, 'repo');
+  const workspacePath = path.join(repoRoot, 'packages', 'app');
+  await fs.mkdir(path.join(repoRoot, '.git'), { recursive: true });
+  await fs.mkdir(workspacePath, { recursive: true });
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  try {
+    await writeSkill(
+      path.join(workspacePath, '.agents', 'skills'),
+      'codex-cwd-dir',
+      'codex-cwd',
+      'Codex cwd skill',
+    );
+    await writeSkill(
+      path.join(repoRoot, 'packages', '.agents', 'skills'),
+      'codex-parent-dir',
+      'codex-parent',
+      'Codex parent skill',
+    );
+    await writeSkill(
+      path.join(repoRoot, '.agents', 'skills'),
+      'codex-root-dir',
+      'codex-root',
+      'Codex root skill',
+    );
+    await writeSkill(
+      path.join(tempRoot, '.agents', 'skills'),
+      'codex-user-dir',
+      'codex-user',
+      'Codex user skill',
+    );
+    await writeSkill(
+      path.join(tempRoot, '.codex', 'skills', '.system'),
+      'codex-system-dir',
+      'codex-system',
+      'Codex system skill',
+    );
+
+    const skills = await providerSkillsService.listProviderSkills('codex', { workspacePath });
+    const byName = new Map(skills.map((skill) => [skill.name, skill]));
+
+    assert.equal(byName.get('codex-cwd')?.scope, 'repo');
+    assert.equal(byName.get('codex-parent')?.scope, 'repo');
+    assert.equal(byName.get('codex-root')?.scope, 'repo');
+    assert.equal(byName.get('codex-user')?.scope, 'user');
+    assert.equal(byName.get('codex-system')?.scope, 'system');
+    assert.equal(byName.get('codex-root')?.command, '$codex-root');
+  } finally {
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+/**
+ * This test covers OpenCode skill lookup across cwd-to-git-root project folders
+ * plus the global OpenCode/Claude/Agents compatibility locations.
+ */
+test('providerSkillsService lists opencode project and user compatibility skills', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-skills-opencode-'));
+  const repoRoot = path.join(tempRoot, 'repo');
+  const workspacePath = path.join(repoRoot, 'packages', 'app');
+  await fs.mkdir(path.join(repoRoot, '.git'), { recursive: true });
+  await fs.mkdir(workspacePath, { recursive: true });
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  try {
+    await writeSkill(
+      path.join(workspacePath, '.opencode', 'skills'),
+      'opencode-cwd-dir',
+      'opencode-cwd',
+      'OpenCode cwd skill',
+    );
+    await writeSkill(
+      path.join(repoRoot, 'packages', '.claude', 'skills'),
+      'opencode-claude-parent-dir',
+      'opencode-claude-parent',
+      'OpenCode Claude parent skill',
+    );
+    await writeSkill(
+      path.join(repoRoot, '.agents', 'skills'),
+      'opencode-agents-root-dir',
+      'opencode-agents-root',
+      'OpenCode Agents root skill',
+    );
+    await writeSkill(
+      path.join(tempRoot, '.config', 'opencode', 'skills'),
+      'opencode-user-dir',
+      'opencode-user',
+      'OpenCode user skill',
+    );
+    await writeSkill(
+      path.join(tempRoot, '.claude', 'skills'),
+      'opencode-claude-user-dir',
+      'opencode-claude-user',
+      'OpenCode Claude user skill',
+    );
+    await writeSkill(
+      path.join(tempRoot, '.agents', 'skills'),
+      'opencode-agents-user-dir',
+      'opencode-agents-user',
+      'OpenCode Agents user skill',
+    );
+
+    const skills = await providerSkillsService.listProviderSkills('opencode', { workspacePath });
+    const byName = new Map(skills.map((skill) => [skill.name, skill]));
+
+    assert.equal(byName.get('opencode-cwd')?.scope, 'project');
+    assert.equal(byName.get('opencode-claude-parent')?.scope, 'project');
+    assert.equal(byName.get('opencode-agents-root')?.scope, 'project');
+    assert.equal(byName.get('opencode-user')?.scope, 'user');
+    assert.equal(byName.get('opencode-claude-user')?.scope, 'user');
+    assert.equal(byName.get('opencode-agents-user')?.scope, 'user');
+    assert.equal(byName.get('opencode-cwd')?.command, '/opencode-cwd');
+  } finally {
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+/**
+ * This test covers Gemini and Cursor skill directory rules, including shared
+ * `.agents/skills` project support.
+ */
+test('providerSkillsService lists gemini and cursor skills from their configured directories', { concurrency: false }, async () => {
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'llm-skills-gc-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  await fs.mkdir(workspacePath, { recursive: true });
+
+  const restoreHomeDir = patchHomeDir(tempRoot);
+  try {
+    await writeSkill(
+      path.join(tempRoot, '.gemini', 'skills'),
+      'gemini-user-dir',
+      'gemini-user',
+      'Gemini user skill',
+    );
+    await writeSkill(
+      path.join(tempRoot, '.agents', 'skills'),
+      'agents-user-dir',
+      'agents-user',
+      'Agents user skill',
+    );
+    await writeSkill(
+      path.join(workspacePath, '.gemini', 'skills'),
+      'gemini-project-dir',
+      'gemini-project',
+      'Gemini project skill',
+    );
+    await writeSkill(
+      path.join(workspacePath, '.agents', 'skills'),
+      'agents-project-dir',
+      'agents-project',
+      'Agents project skill',
+    );
+    await writeSkill(
+      path.join(workspacePath, '.cursor', 'skills'),
+      'cursor-project-dir',
+      'cursor-project',
+      'Cursor project skill',
+    );
+    await writeSkill(
+      path.join(tempRoot, '.cursor', 'skills'),
+      'cursor-user-dir',
+      'cursor-user',
+      'Cursor user skill',
+    );
+
+    const geminiSkills = await providerSkillsService.listProviderSkills('gemini', { workspacePath });
+    const geminiByName = new Map(geminiSkills.map((skill) => [skill.name, skill]));
+    assert.equal(geminiByName.get('gemini-user')?.scope, 'user');
+    assert.equal(geminiByName.get('agents-user')?.scope, 'user');
+    assert.equal(geminiByName.get('gemini-project')?.scope, 'project');
+    assert.equal(geminiByName.get('agents-project')?.scope, 'project');
+    assert.equal(geminiByName.get('gemini-project')?.command, '/gemini-project');
+
+    const cursorSkills = await providerSkillsService.listProviderSkills('cursor', { workspacePath });
+    const cursorByName = new Map(cursorSkills.map((skill) => [skill.name, skill]));
+    assert.equal(cursorByName.get('agents-project')?.scope, 'project');
+    assert.equal(cursorByName.get('cursor-project')?.scope, 'project');
+    assert.equal(cursorByName.get('cursor-user')?.scope, 'user');
+    assert.equal(cursorByName.get('cursor-user')?.command, '/cursor-user');
+  } finally {
+    restoreHomeDir();
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+});
diff --git a/server/modules/websocket/README.md b/server/modules/websocket/README.md
new file mode 100644
index 00000000..12db6349
--- /dev/null
+++ b/server/modules/websocket/README.md
@@ -0,0 +1,267 @@
+# WebSocket Module
+
+This module owns the server-side WebSocket gateway used by:
+
+1. Chat streaming (`/ws`)
+2. Interactive terminal sessions (`/shell`)
+3. Plugin WebSocket passthrough (`/plugin-ws/:pluginName`)
+
+It is intentionally structured as **small services** plus a **barrel export** in `index.ts`.
+
+## Public API
+
+`server/modules/websocket/index.ts` exports:
+
+1. `createWebSocketServer(server, dependencies)`  
+Creates and wires the shared `ws` server.
+2. `connectedClients` and `WS_OPEN_STATE`  
+Shared chat client registry and open-state constant used by other modules.
+
+## Why Dependency Injection Is Used
+
+The module receives runtime-specific functions from `server/index.js` instead of importing legacy runtime files directly.
+
+Benefits:
+
+1. Keeps module boundaries clean (`server/modules/*` architecture rule).
+2. Makes each service easier to test in isolation.
+3. Keeps WebSocket transport concerns separate from provider runtime concerns.
+
+## Service Map
+
+| File | Responsibility |
+|---|---|
+| `services/websocket-server.service.ts` | Creates `WebSocketServer`, binds `verifyClient`, routes connection by pathname |
+| `services/websocket-auth.service.ts` | Authenticates upgrade requests and attaches `request.user` |
+| `services/chat-websocket.service.ts` | Handles `/ws` chat protocol and provider command/session control messages |
+| `services/shell-websocket.service.ts` | Handles `/shell` PTY lifecycle, reconnect buffering, auth URL detection |
+| `services/plugin-websocket-proxy.service.ts` | Bridges client socket to plugin socket |
+| `services/websocket-writer.service.ts` | Adapts raw WebSocket to writer interface (`send`, `setSessionId`, `getSessionId`) |
+| `services/websocket-state.service.ts` | Holds shared chat client set and open-state constant |
+
+## High-Level Architecture
+
+```mermaid
+flowchart LR
+  A[HTTP Server] --> B[createWebSocketServer]
+  B --> C[verifyWebSocketClient]
+  B --> D{Pathname}
+  D -->|/ws| E[handleChatConnection]
+  D -->|/shell| F[handleShellConnection]
+  D -->|/plugin-ws/:name| G[handlePluginWsProxy]
+  D -->|other| H[close()]
+
+  E --> I[connectedClients Set]
+  E --> J[WebSocketWriter]
+  F --> K[ptySessionsMap]
+  G --> L[Upstream Plugin ws://127.0.0.1:port/ws]
+
+  I --> M[projects.service broadcastProgress]
+  I --> N[sessions-watcher.service projects_updated]
+```
+
+## Connection Handshake + Routing
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant WSS as WebSocketServer
+  participant Auth as verifyWebSocketClient
+  participant Router as connection router
+  participant Chat as /ws handler
+  participant Shell as /shell handler
+  participant Proxy as /plugin-ws handler
+
+  Client->>WSS: Upgrade Request
+  WSS->>Auth: verifyClient(info)
+  alt Platform mode
+    Auth->>Auth: authenticateWebSocket(null)
+    Auth->>Auth: attach request.user
+  else OSS mode
+    Auth->>Auth: read token from ?token or Authorization
+    Auth->>Auth: authenticateWebSocket(token)
+    Auth->>Auth: attach request.user
+  end
+
+  alt Auth failed
+    Auth-->>WSS: false (reject handshake)
+  else Auth ok
+    Auth-->>WSS: true
+    WSS->>Router: on("connection", ws, request)
+    alt pathname == /ws
+      Router->>Chat: handleChatConnection(ws, request, deps.chat)
+    else pathname == /shell
+      Router->>Shell: handleShellConnection(ws, deps.shell)
+    else pathname startsWith /plugin-ws/
+      Router->>Proxy: handlePluginWsProxy(ws, pathname, getPluginPort)
+    else unknown
+      Router->>Router: ws.close()
+    end
+  end
+```
+
+## `/ws` Chat Flow
+
+When a chat socket connects:
+
+1. Add socket to `connectedClients`.
+2. Build `WebSocketWriter` (captures `userId` from authenticated request).
+3. Parse each incoming message with `parseIncomingJsonObject`.
+4. Dispatch by `data.type`.
+5. On close, remove socket from `connectedClients`.
+
+### Chat Message Dispatch
+
+```mermaid
+flowchart TD
+  A[Incoming WS message] --> B[parseIncomingJsonObject]
+  B -->|invalid| C[send {type:error}]
+  B -->|ok| D{data.type}
+
+  D -->|claude-command| E[queryClaudeSDK]
+  D -->|cursor-command| F[spawnCursor]
+  D -->|codex-command| G[queryCodex]
+  D -->|gemini-command| H[spawnGemini]
+  D -->|cursor-resume| I[spawnCursor resume]
+  D -->|abort-session| J[abort by provider]
+  D -->|claude-permission-response| K[resolveToolApproval]
+  D -->|cursor-abort| L[abortCursorSession]
+  D -->|check-session-status| M[is*SessionActive + optional reconnectSessionWriter]
+  D -->|get-pending-permissions| N[getPendingApprovalsForSession]
+  D -->|get-active-sessions| O[getActive*Sessions]
+```
+
+### Chat Notes
+
+1. `abort-session` returns a normalized `complete` message with `aborted: true`.
+2. `check-session-status` returns `{ type: "session-status", isProcessing }`.
+3. Claude status checks can reconnect output stream to the new socket via `reconnectSessionWriter`.
+
+## `/shell` Terminal Flow
+
+The shell handler manages persistent PTY sessions keyed by:
+
+`<projectPath>_<sessionIdOrDefault>[_cmd_<hash>]`
+
+This enables reconnect behavior and isolates command-specific plain-shell sessions.
+
+### Shell Lifecycle
+
+```mermaid
+stateDiagram-v2
+  [*] --> WaitingInit
+  WaitingInit --> ValidateInit: message.type == init
+  ValidateInit --> ReconnectExisting: session key exists and not login reset
+  ValidateInit --> SpawnNewPTY: valid path + valid sessionId
+  ValidateInit --> EmitError: invalid payload/path/sessionId
+
+  ReconnectExisting --> Running: attach ws, replay buffer
+  SpawnNewPTY --> Running: pty.spawn + wire onData/onExit
+
+  Running --> Running: input -> pty.write
+  Running --> Running: resize -> pty.resize
+  Running --> Running: onData -> buffer + output + auth_url detection
+  Running --> Exited: onExit
+  Running --> Detached: ws close
+
+  Detached --> Running: reconnect before timeout
+  Detached --> Killed: timeout reached -> pty.kill
+  Exited --> [*]
+  Killed --> [*]
+  EmitError --> WaitingInit
+```
+
+### Shell Behaviors in Detail
+
+1. `init`:
+Reads `projectPath`, `sessionId`, `provider`, `hasSession`, `initialCommand`, `isPlainShell`.
+2. Login reset:
+For login-like commands, existing keyed PTY session is killed and recreated.
+3. Validation:
+Path must exist and be a directory; `sessionId` must match safe pattern.
+4. Command build:
+Provider-specific command construction with resume semantics.
+5. PTY output buffering:
+Stores up to 5000 chunks for replay on reconnect.
+6. URL detection:
+Strips ANSI, accumulates text buffer, extracts URLs, emits `auth_url` once per normalized URL, supports `autoOpen`.
+7. Close behavior:
+Socket disconnect does not instantly kill PTY; session is kept alive and terminated on timeout.
+
+## `/plugin-ws/:pluginName` Proxy Flow
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant Proxy as handlePluginWsProxy
+  participant PM as getPluginPort
+  participant Upstream as Plugin WS
+
+  Client->>Proxy: Connect /plugin-ws/:name
+  Proxy->>Proxy: Validate pluginName regex
+  alt Invalid name
+    Proxy-->>Client: close(4400, "Invalid plugin name")
+  else Valid
+    Proxy->>PM: getPluginPort(name)
+    alt Plugin not running
+      Proxy-->>Client: close(4404, "Plugin not running")
+    else Port found
+      Proxy->>Upstream: new WebSocket(ws://127.0.0.1:port/ws)
+      Client-->>Upstream: relay messages bidirectionally
+      Upstream-->>Client: relay messages bidirectionally
+      Upstream-->>Client: close propagation
+      Client-->>Upstream: close propagation
+      Upstream-->>Client: close(4502, "Upstream error") on upstream error
+    end
+  end
+```
+
+## Shared Client Registry and Broadcasts
+
+Only chat sockets (`/ws`) are tracked in `connectedClients`.
+
+That shared set is consumed by:
+
+1. `modules/projects/services/projects-with-sessions-fetch.service.ts`
+Broadcasts `loading_progress` while project snapshots are being built.
+2. `modules/providers/services/sessions-watcher.service.ts`
+Broadcasts `projects_updated` when provider session artifacts change.
+
+This design centralizes cross-module realtime fanout without requiring route-local references to WebSocket internals.
+
+## Writer Adapter (`WebSocketWriter`)
+
+`WebSocketWriter` normalizes chat transport behavior to match existing writer-style interfaces used elsewhere.
+
+Methods:
+
+1. `send(data)`  
+JSON-serializes and sends only if socket is open.
+2. `setSessionId(sessionId)` / `getSessionId()`  
+Supports provider session bookkeeping and resume flows.
+3. `updateWebSocket(newRawWs)`  
+Allows active session stream redirection on reconnect.
+
+## Error Handling and Close Codes
+
+Current explicit close codes in this module:
+
+1. `4400`: Invalid plugin name
+2. `4404`: Plugin not running
+3. `4502`: Upstream plugin WebSocket error
+
+Other errors:
+
+1. Chat handler catches and emits `{ type: "error", error }`.
+2. Shell handler catches and writes terminal-visible error output.
+3. Unknown websocket paths are closed immediately.
+
+## Extending This Module
+
+To add a new websocket route:
+
+1. Add a new handler service under `services/`.
+2. Extend `WebSocketServerDependencies` in `websocket-server.service.ts` if needed.
+3. Add a new pathname branch in the router.
+4. Wire dependency injection from `server/index.js`.
+5. Keep `index.ts` as barrel-only export surface.
diff --git a/server/modules/websocket/index.ts b/server/modules/websocket/index.ts
new file mode 100644
index 00000000..da65ee82
--- /dev/null
+++ b/server/modules/websocket/index.ts
@@ -0,0 +1,2 @@
+export { WS_OPEN_STATE, connectedClients } from './services/websocket-state.service.js';
+export { createWebSocketServer } from './services/websocket-server.service.js';
diff --git a/server/modules/websocket/services/chat-websocket.service.ts b/server/modules/websocket/services/chat-websocket.service.ts
new file mode 100644
index 00000000..829cb0b0
--- /dev/null
+++ b/server/modules/websocket/services/chat-websocket.service.ts
@@ -0,0 +1,285 @@
+import type { WebSocket } from 'ws';
+
+import { connectedClients } from '@/modules/websocket/services/websocket-state.service.js';
+import { WebSocketWriter } from '@/modules/websocket/services/websocket-writer.service.js';
+import type {
+  AnyRecord,
+  AuthenticatedWebSocketRequest,
+  LLMProvider,
+} from '@/shared/types.js';
+import { createNormalizedMessage, parseIncomingJsonObject } from '@/shared/utils.js';
+
+type ChatIncomingMessage = AnyRecord & {
+  type?: string;
+  command?: string;
+  options?: AnyRecord;
+  provider?: string;
+  sessionId?: string;
+  requestId?: string;
+  allow?: unknown;
+  updatedInput?: unknown;
+  message?: unknown;
+  rememberEntry?: unknown;
+};
+
+const DEFAULT_PROVIDER: LLMProvider = 'claude';
+
+type ChatWebSocketDependencies = {
+  queryClaudeSDK: (command: string, options: unknown, writer: WebSocketWriter) => Promise<unknown>;
+  spawnCursor: (command: string, options: unknown, writer: WebSocketWriter) => Promise<unknown>;
+  queryCodex: (command: string, options: unknown, writer: WebSocketWriter) => Promise<unknown>;
+  spawnGemini: (command: string, options: unknown, writer: WebSocketWriter) => Promise<unknown>;
+  spawnOpenCode: (command: string, options: unknown, writer: WebSocketWriter) => Promise<unknown>;
+  abortClaudeSDKSession: (sessionId: string) => Promise<boolean>;
+  abortCursorSession: (sessionId: string) => boolean;
+  abortCodexSession: (sessionId: string) => boolean;
+  abortGeminiSession: (sessionId: string) => boolean;
+  abortOpenCodeSession: (sessionId: string) => boolean;
+  resolveToolApproval: (
+    requestId: string,
+    payload: {
+      allow: boolean;
+      updatedInput?: unknown;
+      message?: string;
+      rememberEntry?: unknown;
+    }
+  ) => void;
+  isClaudeSDKSessionActive: (sessionId: string) => boolean;
+  isCursorSessionActive: (sessionId: string) => boolean;
+  isCodexSessionActive: (sessionId: string) => boolean;
+  isGeminiSessionActive: (sessionId: string) => boolean;
+  isOpenCodeSessionActive: (sessionId: string) => boolean;
+  reconnectSessionWriter: (sessionId: string, ws: WebSocket) => boolean;
+  getPendingApprovalsForSession: (sessionId: string) => unknown[];
+  getActiveClaudeSDKSessions: () => unknown;
+  getActiveCursorSessions: () => unknown;
+  getActiveCodexSessions: () => unknown;
+  getActiveGeminiSessions: () => unknown;
+  getActiveOpenCodeSessions: () => unknown;
+};
+
+/**
+ * Normalizes potentially invalid provider names coming from websocket payloads.
+ */
+function readProvider(value: unknown): LLMProvider {
+  if (value === 'claude' || value === 'cursor' || value === 'codex' || value === 'gemini' || value === 'opencode') {
+    return value;
+  }
+
+  return DEFAULT_PROVIDER;
+}
+
+/**
+ * Extracts the authenticated request user id in the formats currently produced
+ * by platform and OSS auth code paths.
+ */
+function readRequestUserId(
+  request: AuthenticatedWebSocketRequest | undefined
+): string | number | null {
+  const user = request?.user;
+  if (!user) {
+    return null;
+  }
+
+  if (typeof user.id === 'string' || typeof user.id === 'number') {
+    return user.id;
+  }
+
+  if (typeof user.userId === 'string' || typeof user.userId === 'number') {
+    return user.userId;
+  }
+
+  return null;
+}
+
+/**
+ * Handles authenticated chat websocket messages used by the main chat panel.
+ */
+export function handleChatConnection(
+  ws: WebSocket,
+  request: AuthenticatedWebSocketRequest,
+  dependencies: ChatWebSocketDependencies
+): void {
+  console.log('[INFO] Chat WebSocket connected');
+  connectedClients.add(ws);
+
+  const writer = new WebSocketWriter(ws, readRequestUserId(request));
+
+  ws.on('message', async (rawMessage) => {
+    try {
+      const parsed = parseIncomingJsonObject(rawMessage);
+      if (!parsed) {
+        throw new Error('Invalid websocket payload');
+      }
+
+      const data = parsed as ChatIncomingMessage;
+      const messageType = data.type;
+      if (!messageType) {
+        throw new Error('Message type is required');
+      }
+
+      if (messageType === 'claude-command') {
+        await dependencies.queryClaudeSDK(data.command ?? '', data.options, writer);
+        return;
+      }
+
+      if (messageType === 'cursor-command') {
+        await dependencies.spawnCursor(data.command ?? '', data.options, writer);
+        return;
+      }
+
+      if (messageType === 'codex-command') {
+        await dependencies.queryCodex(data.command ?? '', data.options, writer);
+        return;
+      }
+
+      if (messageType === 'gemini-command') {
+        await dependencies.spawnGemini(data.command ?? '', data.options, writer);
+        return;
+      }
+
+      if (messageType === 'opencode-command') {
+        await dependencies.spawnOpenCode(data.command ?? '', data.options, writer);
+        return;
+      }
+
+      if (messageType === 'cursor-resume') {
+        await dependencies.spawnCursor(
+          '',
+          {
+            sessionId: data.sessionId,
+            resume: true,
+            cwd: data.options?.cwd,
+          },
+          writer
+        );
+        return;
+      }
+
+      if (messageType === 'abort-session') {
+        const provider = readProvider(data.provider);
+        const sessionId = typeof data.sessionId === 'string' ? data.sessionId : '';
+        let success = false;
+
+        if (provider === 'cursor') {
+          success = dependencies.abortCursorSession(sessionId);
+        } else if (provider === 'codex') {
+          success = dependencies.abortCodexSession(sessionId);
+        } else if (provider === 'gemini') {
+          success = dependencies.abortGeminiSession(sessionId);
+        } else if (provider === 'opencode') {
+          success = dependencies.abortOpenCodeSession(sessionId);
+        } else {
+          success = await dependencies.abortClaudeSDKSession(sessionId);
+        }
+
+        writer.send(
+          createNormalizedMessage({
+            kind: 'complete',
+            exitCode: success ? 0 : 1,
+            aborted: true,
+            success,
+            sessionId,
+            provider,
+          })
+        );
+        return;
+      }
+
+      if (messageType === 'claude-permission-response') {
+        if (typeof data.requestId === 'string' && data.requestId.length > 0) {
+          dependencies.resolveToolApproval(data.requestId, {
+            allow: Boolean(data.allow),
+            updatedInput: data.updatedInput,
+            message: typeof data.message === 'string' ? data.message : undefined,
+            rememberEntry: data.rememberEntry,
+          });
+        }
+        return;
+      }
+
+      if (messageType === 'cursor-abort') {
+        const sessionId = typeof data.sessionId === 'string' ? data.sessionId : '';
+        const success = dependencies.abortCursorSession(sessionId);
+        writer.send(
+          createNormalizedMessage({
+            kind: 'complete',
+            exitCode: success ? 0 : 1,
+            aborted: true,
+            success,
+            sessionId,
+            provider: 'cursor',
+          })
+        );
+        return;
+      }
+
+      if (messageType === 'check-session-status') {
+        const provider = readProvider(data.provider);
+        const sessionId = typeof data.sessionId === 'string' ? data.sessionId : '';
+        let isActive = false;
+
+        if (provider === 'cursor') {
+          isActive = dependencies.isCursorSessionActive(sessionId);
+        } else if (provider === 'codex') {
+          isActive = dependencies.isCodexSessionActive(sessionId);
+        } else if (provider === 'gemini') {
+          isActive = dependencies.isGeminiSessionActive(sessionId);
+        } else if (provider === 'opencode') {
+          isActive = dependencies.isOpenCodeSessionActive(sessionId);
+        } else {
+          isActive = dependencies.isClaudeSDKSessionActive(sessionId);
+          if (isActive) {
+            dependencies.reconnectSessionWriter(sessionId, ws);
+          }
+        }
+
+        writer.send({
+          type: 'session-status',
+          sessionId,
+          provider,
+          isProcessing: isActive,
+        });
+        return;
+      }
+
+      if (messageType === 'get-pending-permissions') {
+        const sessionId = typeof data.sessionId === 'string' ? data.sessionId : '';
+        if (sessionId && dependencies.isClaudeSDKSessionActive(sessionId)) {
+          const pending = dependencies.getPendingApprovalsForSession(sessionId);
+          writer.send({
+            type: 'pending-permissions-response',
+            sessionId,
+            data: pending,
+          });
+        }
+        return;
+      }
+
+      if (messageType === 'get-active-sessions') {
+        writer.send({
+          type: 'active-sessions',
+          sessions: {
+            claude: dependencies.getActiveClaudeSDKSessions(),
+            cursor: dependencies.getActiveCursorSessions(),
+            codex: dependencies.getActiveCodexSessions(),
+            gemini: dependencies.getActiveGeminiSessions(),
+            opencode: dependencies.getActiveOpenCodeSessions(),
+          },
+        });
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error('[ERROR] Chat WebSocket error:', message);
+      writer.send({
+        type: 'error',
+        error: message,
+      });
+    }
+  });
+
+  ws.on('close', () => {
+    console.log('[INFO] Chat client disconnected');
+    connectedClients.delete(ws);
+  });
+}
diff --git a/server/modules/websocket/services/plugin-websocket-proxy.service.ts b/server/modules/websocket/services/plugin-websocket-proxy.service.ts
new file mode 100644
index 00000000..34e86ac6
--- /dev/null
+++ b/server/modules/websocket/services/plugin-websocket-proxy.service.ts
@@ -0,0 +1,65 @@
+import { WebSocket } from 'ws';
+
+/**
+ * Proxies an authenticated client websocket to a plugin websocket endpoint.
+ */
+export function handlePluginWsProxy(
+  clientWs: WebSocket,
+  pathname: string,
+  getPluginPort: (pluginName: string) => number | null
+): void {
+  const pluginName = pathname.replace('/plugin-ws/', '');
+  if (!pluginName || /[^a-zA-Z0-9_-]/.test(pluginName)) {
+    clientWs.close(4400, 'Invalid plugin name');
+    return;
+  }
+
+  const port = getPluginPort(pluginName);
+  if (!port) {
+    clientWs.close(4404, 'Plugin not running');
+    return;
+  }
+
+  const upstream = new WebSocket(`ws://127.0.0.1:${port}/ws`);
+
+  upstream.on('open', () => {
+    console.log(`[Plugins] WS proxy connected to "${pluginName}" on port ${port}`);
+  });
+
+  upstream.on('message', (data, isBinary) => {
+    if (clientWs.readyState === WebSocket.OPEN) {
+      clientWs.send(data, { binary: isBinary });
+    }
+  });
+
+  clientWs.on('message', (data, isBinary) => {
+    if (upstream.readyState === WebSocket.OPEN) {
+      upstream.send(data, { binary: isBinary });
+    }
+  });
+
+  upstream.on('close', () => {
+    if (clientWs.readyState === WebSocket.OPEN) {
+      clientWs.close();
+    }
+  });
+
+  clientWs.on('close', () => {
+    if (upstream.readyState === WebSocket.OPEN) {
+      upstream.close();
+    }
+  });
+
+  upstream.on('error', (error) => {
+    console.error(`[Plugins] WS proxy error for "${pluginName}":`, error.message);
+    if (clientWs.readyState === WebSocket.OPEN) {
+      clientWs.close(4502, 'Upstream error');
+    }
+  });
+
+  clientWs.on('error', () => {
+    if (upstream.readyState === WebSocket.OPEN) {
+      upstream.close();
+    }
+  });
+}
diff --git a/server/modules/websocket/services/shell-websocket.service.ts b/server/modules/websocket/services/shell-websocket.service.ts
new file mode 100644
index 00000000..b8f34ae8
--- /dev/null
+++ b/server/modules/websocket/services/shell-websocket.service.ts
@@ -0,0 +1,462 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import pty, { type IPty } from 'node-pty';
+import { WebSocket, type RawData } from 'ws';
+
+import { parseIncomingJsonObject } from '@/shared/utils.js';
+
+type ShellIncomingMessage = {
+  type?: string;
+  data?: string;
+  cols?: number;
+  rows?: number;
+  projectPath?: string;
+  sessionId?: string;
+  hasSession?: boolean;
+  provider?: string;
+  initialCommand?: string;
+  isPlainShell?: boolean;
+};
+
+type PtySessionEntry = {
+  pty: IPty;
+  ws: WebSocket | null;
+  buffer: string[];
+  timeoutId: NodeJS.Timeout | null;
+  projectPath: string;
+  sessionId: string | null;
+};
+
+const ptySessionsMap = new Map<string, PtySessionEntry>();
+const PTY_SESSION_TIMEOUT = 30 * 60 * 1000;
+const SHELL_URL_PARSE_BUFFER_LIMIT = 32768;
+
+type ShellWebSocketDependencies = {
+  getSessionById: (sessionId: string) => { cliSessionId?: string } | null | undefined;
+  stripAnsiSequences: (content: string) => string;
+  normalizeDetectedUrl: (url: string) => string | null;
+  extractUrlsFromText: (content: string) => string[];
+  shouldAutoOpenUrlFromOutput: (content: string) => boolean;
+};
+
+/**
+ * Reads a string field from untyped payloads and falls back when absent.
+ */
+function readString(value: unknown, fallback = ''): string {
+  return typeof value === 'string' ? value : fallback;
+}
+
+/**
+ * Reads a boolean field from untyped payloads and falls back when absent.
+ */
+function readBoolean(value: unknown, fallback = false): boolean {
+  return typeof value === 'boolean' ? value : fallback;
+}
+
+/**
+ * Reads a finite number field from untyped payloads and falls back when absent.
+ */
+function readNumber(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+/**
+ * Parses incoming websocket shell messages and keeps processing safe when
+ * malformed payloads are received.
+ */
+function parseShellMessage(rawMessage: RawData): ShellIncomingMessage | null {
+  const payload = parseIncomingJsonObject(rawMessage);
+  if (!payload) {
+    return null;
+  }
+
+  return payload as ShellIncomingMessage;
+}
+
+/**
+ * Resolves provider command line for plain shell and agent-backed shell modes.
+ */
+function buildShellCommand(
+  message: ShellIncomingMessage,
+  dependencies: ShellWebSocketDependencies
+): string {
+  const hasSession = readBoolean(message.hasSession);
+  const sessionId = readString(message.sessionId);
+  const initialCommand = readString(message.initialCommand);
+  const provider = readString(message.provider, 'claude');
+  const safeSessionIdPattern = /^[a-zA-Z0-9_.\-:]+$/;
+  const isPlainShell =
+    readBoolean(message.isPlainShell) ||
+    (!!initialCommand && !hasSession) ||
+    provider === 'plain-shell';
+
+  if (isPlainShell) {
+    return initialCommand;
+  }
+
+  if (provider === 'cursor') {
+    if (hasSession && sessionId) {
+      return `cursor-agent --resume="${sessionId}"`;
+    }
+    return 'cursor-agent';
+  }
+
+  if (provider === 'codex') {
+    if (hasSession && sessionId) {
+      if (os.platform() === 'win32') {
+        return `codex resume "${sessionId}"; if ($LASTEXITCODE -ne 0) { codex }`;
+      }
+      return `codex resume "${sessionId}" || codex`;
+    }
+    return 'codex';
+  }
+
+  if (provider === 'gemini') {
+    const command = initialCommand || 'gemini';
+    let resumeId = sessionId;
+    if (hasSession && sessionId) {
+      try {
+        const existingSession = dependencies.getSessionById(sessionId);
+        if (existingSession && existingSession.cliSessionId) {
+          resumeId = existingSession.cliSessionId;
+          if (!safeSessionIdPattern.test(resumeId)) {
+            resumeId = '';
+          }
+        }
+      } catch (error) {
+        console.error('Failed to get Gemini CLI session ID:', error);
+      }
+    }
+
+    if (hasSession && resumeId) {
+      return `${command} --resume "${resumeId}"`;
+    }
+    return command;
+  }
+
+  if (provider === 'opencode') {
+    if (hasSession && sessionId) {
+      return `opencode --session "${sessionId}"`;
+    }
+    return initialCommand || 'opencode';
+  }
+
+  const command = initialCommand || 'claude';
+  if (hasSession && sessionId) {
+    if (os.platform() === 'win32') {
+      return `claude --resume "${sessionId}"; if ($LASTEXITCODE -ne 0) { claude }`;
+    }
+    return `claude --resume "${sessionId}" || claude`;
+  }
+  return command;
+}
+
+/**
+ * Handles websocket connections used by the standalone shell terminal UI.
+ */
+export function handleShellConnection(
+  ws: WebSocket,
+  dependencies: ShellWebSocketDependencies
+): void {
+  console.log('[INFO] Shell websocket connected');
+
+  let shellProcess: IPty | null = null;
+  let ptySessionKey: string | null = null;
+  let urlDetectionBuffer = '';
+  const announcedAuthUrls = new Set<string>();
+
+  ws.on('message', async (rawMessage) => {
+    try {
+      const data = parseShellMessage(rawMessage);
+      if (!data?.type) {
+        throw new Error('Invalid websocket payload');
+      }
+
+      if (data.type === 'init') {
+        const projectPath = readString(data.projectPath, process.cwd());
+        const sessionId = readString(data.sessionId) || null;
+        const hasSession = readBoolean(data.hasSession);
+        const provider = readString(data.provider, 'claude');
+        const initialCommand = readString(data.initialCommand);
+        const isPlainShell =
+          readBoolean(data.isPlainShell) ||
+          (!!initialCommand && !hasSession) ||
+          provider === 'plain-shell';
+
+        urlDetectionBuffer = '';
+        announcedAuthUrls.clear();
+
+        const isLoginCommand =
+          !!initialCommand &&
+          (initialCommand.includes('setup-token') ||
+            initialCommand.includes('cursor-agent login') ||
+            initialCommand.includes('auth login'));
+
+        const commandSuffix =
+          isPlainShell && initialCommand
+            ? `_cmd_${Buffer.from(initialCommand).toString('base64').slice(0, 16)}`
+            : '';
+        ptySessionKey = `${projectPath}_${sessionId ?? 'default'}${commandSuffix}`;
+
+        if (isLoginCommand) {
+          const oldSession = ptySessionsMap.get(ptySessionKey);
+          if (oldSession) {
+            if (oldSession.timeoutId) {
+              clearTimeout(oldSession.timeoutId);
+            }
+            oldSession.pty.kill();
+            ptySessionsMap.delete(ptySessionKey);
+          }
+        }
+
+        const existingSession = isLoginCommand ? null : ptySessionsMap.get(ptySessionKey);
+        if (existingSession) {
+          shellProcess = existingSession.pty;
+          if (existingSession.timeoutId) {
+            clearTimeout(existingSession.timeoutId);
+          }
+
+          ws.send(
+            JSON.stringify({
+              type: 'output',
+              data: '\x1b[36m[Reconnected to existing session]\x1b[0m\r\n',
+            })
+          );
+
+          if (existingSession.buffer.length > 0) {
+            existingSession.buffer.forEach((bufferedData) => {
+              ws.send(
+                JSON.stringify({
+                  type: 'output',
+                  data: bufferedData,
+                })
+              );
+            });
+          }
+
+          existingSession.ws = ws;
+          return;
+        }
+
+        const resolvedProjectPath = path.resolve(projectPath);
+        try {
+          const stats = fs.statSync(resolvedProjectPath);
+          if (!stats.isDirectory()) {
+            throw new Error('Not a directory');
+          }
+        } catch {
+          ws.send(JSON.stringify({ type: 'error', message: 'Invalid project path' }));
+          return;
+        }
+
+        const safeSessionIdPattern = /^[a-zA-Z0-9_.\-:]+$/;
+        if (sessionId && !safeSessionIdPattern.test(sessionId)) {
+          ws.send(JSON.stringify({ type: 'error', message: 'Invalid session ID' }));
+          return;
+        }
+
+        const shellCommand = buildShellCommand(data, dependencies);
+        const shell = os.platform() === 'win32' ? 'powershell.exe' : 'bash';
+        const shellArgs =
+          os.platform() === 'win32' ? ['-Command', shellCommand] : ['-c', shellCommand];
+        const termCols = readNumber(data.cols, 80);
+        const termRows = readNumber(data.rows, 24);
+
+        shellProcess = pty.spawn(shell, shellArgs, {
+          name: 'xterm-256color',
+          cols: termCols,
+          rows: termRows,
+          cwd: resolvedProjectPath,
+          env: {
+            ...process.env,
+            TERM: 'xterm-256color',
+            COLORTERM: 'truecolor',
+            FORCE_COLOR: '3',
+          },
+        });
+
+        ptySessionsMap.set(ptySessionKey, {
+          pty: shellProcess,
+          ws,
+          buffer: [],
+          timeoutId: null,
+          projectPath,
+          sessionId,
+        });
+
+        shellProcess.onData((chunk) => {
+          if (!ptySessionKey) {
+            return;
+          }
+
+          const session = ptySessionsMap.get(ptySessionKey);
+          if (!session) {
+            return;
+          }
+
+          if (session.buffer.length < 5000) {
+            session.buffer.push(chunk);
+          } else {
+            session.buffer.shift();
+            session.buffer.push(chunk);
+          }
+
+          if (session.ws && session.ws.readyState === WebSocket.OPEN) {
+            let outputData = chunk;
+            const cleanChunk = dependencies.stripAnsiSequences(chunk);
+            urlDetectionBuffer = `${urlDetectionBuffer}${cleanChunk}`.slice(-SHELL_URL_PARSE_BUFFER_LIMIT);
+
+            outputData = outputData.replace(
+              /OPEN_URL:\s*(https?:\/\/[^\s\x1b\x07]+)/g,
+              '[INFO] Opening in browser: $1'
+            );
+
+            const emitAuthUrl = (detectedUrl: string, autoOpen = false) => {
+              const normalizedUrl = dependencies.normalizeDetectedUrl(detectedUrl);
+              if (!normalizedUrl) {
+                return;
+              }
+
+              const isNewUrl = !announcedAuthUrls.has(normalizedUrl);
+              if (isNewUrl) {
+                announcedAuthUrls.add(normalizedUrl);
+                session.ws?.send(
+                  JSON.stringify({
+                    type: 'auth_url',
+                    url: normalizedUrl,
+                    autoOpen,
+                  })
+                );
+              }
+            };
+
+            const normalizedDetectedUrls = dependencies.extractUrlsFromText(urlDetectionBuffer)
+              .map((url) => dependencies.normalizeDetectedUrl(url))
+              .filter((url): url is string => Boolean(url));
+
+            const dedupedDetectedUrls = Array.from(new Set(normalizedDetectedUrls)).filter(
+              (url, _, urls) =>
+                !urls.some((otherUrl) => otherUrl !== url && otherUrl.startsWith(url))
+            );
+
+            dedupedDetectedUrls.forEach((url) => emitAuthUrl(url, false));
+
+            if (
+              dependencies.shouldAutoOpenUrlFromOutput(cleanChunk) &&
+              dedupedDetectedUrls.length > 0
+            ) {
+              const bestUrl = dedupedDetectedUrls.reduce((longest, current) =>
+                current.length > longest.length ? current : longest
+              );
+              emitAuthUrl(bestUrl, true);
+            }
+
+            session.ws.send(
+              JSON.stringify({
+                type: 'output',
+                data: outputData,
+              })
+            );
+          }
+        });
+
+        shellProcess.onExit((exitCode) => {
+          if (!ptySessionKey) {
+            return;
+          }
+
+          const session = ptySessionsMap.get(ptySessionKey);
+          if (session && session.ws && session.ws.readyState === WebSocket.OPEN) {
+            session.ws.send(
+              JSON.stringify({
+                type: 'output',
+                data: `\r\n\x1b[33mProcess exited with code ${exitCode.exitCode}${
+                  exitCode.signal != null ? ` (${exitCode.signal})` : ''
+                }\x1b[0m\r\n`,
+              })
+            );
+          }
+
+          if (session?.timeoutId) {
+            clearTimeout(session.timeoutId);
+          }
+
+          ptySessionsMap.delete(ptySessionKey);
+          shellProcess = null;
+        });
+
+        let welcomeMsg = `\x1b[36mStarting terminal in: ${projectPath}\x1b[0m\r\n`;
+        if (!isPlainShell) {
+          const providerName =
+            provider === 'cursor'
+              ? 'Cursor'
+              : provider === 'codex'
+                ? 'Codex'
+                : provider === 'gemini'
+                  ? 'Gemini'
+                  : provider === 'opencode'
+                    ? 'OpenCode'
+                  : 'Claude';
+          welcomeMsg = hasSession
+            ? `\x1b[36mResuming ${providerName} session ${sessionId} in: ${projectPath}\x1b[0m\r\n`
+            : `\x1b[36mStarting new ${providerName} session in: ${projectPath}\x1b[0m\r\n`;
+        }
+
+        ws.send(
+          JSON.stringify({
+            type: 'output',
+            data: welcomeMsg,
+          })
+        );
+        return;
+      }
+
+      if (data.type === 'input') {
+        if (shellProcess) {
+          shellProcess.write(readString(data.data));
+        }
+        return;
+      }
+
+      if (data.type === 'resize') {
+        if (shellProcess) {
+          shellProcess.resize(readNumber(data.cols, 80), readNumber(data.rows, 24));
+        }
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error('[ERROR] Shell WebSocket error:', message);
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(
+          JSON.stringify({
+            type: 'output',
+            data: `\r\n\x1b[31mError: ${message}\x1b[0m\r\n`,
+          })
+        );
+      }
+    }
+  });
+
+  ws.on('close', () => {
+    if (!ptySessionKey) {
+      return;
+    }
+
+    const session = ptySessionsMap.get(ptySessionKey);
+    if (!session) {
+      return;
+    }
+
+    session.ws = null;
+    session.timeoutId = setTimeout(() => {
+      session.pty.kill();
+      ptySessionsMap.delete(ptySessionKey as string);
+    }, PTY_SESSION_TIMEOUT);
+  });
+
+  ws.on('error', (error) => {
+    console.error('[ERROR] Shell WebSocket error:', error);
+  });
+}
diff --git a/server/modules/websocket/services/websocket-auth.service.ts b/server/modules/websocket/services/websocket-auth.service.ts
new file mode 100644
index 00000000..bd689d5d
--- /dev/null
+++ b/server/modules/websocket/services/websocket-auth.service.ts
@@ -0,0 +1,54 @@
+import type { VerifyClientCallbackSync } from 'ws';
+
+import type { AuthenticatedWebSocketRequest } from '@/shared/types.js';
+
+type WebSocketAuthDependencies = {
+  isPlatform: boolean;
+  authenticateWebSocket: (token: string | null) => {
+    id?: string | number;
+    userId?: string | number;
+    username?: string;
+    [key: string]: unknown;
+  } | null;
+};
+
+/**
+ * Authenticates websocket upgrade requests before the `connection` handler runs.
+ */
+export function verifyWebSocketClient(
+  info: Parameters<VerifyClientCallbackSync<AuthenticatedWebSocketRequest>>[0],
+  dependencies: WebSocketAuthDependencies
+): boolean {
+  const request = info.req as AuthenticatedWebSocketRequest;
+  console.log('WebSocket connection attempt to:', request.url);
+
+  // Platform mode: use the first DB user and skip token checks.
+  if (dependencies.isPlatform) {
+    const user = dependencies.authenticateWebSocket(null);
+    if (!user) {
+      console.log('[WARN] Platform mode: No user found in database');
+      return false;
+    }
+
+    request.user = user;
+    console.log('[OK] Platform mode WebSocket authenticated for user:', user.username);
+    return true;
+  }
+
+  // OSS mode: read JWT from query string first, then Authorization header.
+  const upgradeUrl = new URL(request.url ?? '/', 'http://localhost');
+  const token =
+    upgradeUrl.searchParams.get('token') ??
+    request.headers.authorization?.split(' ')[1] ??
+    null;
+
+  const user = dependencies.authenticateWebSocket(token);
+  if (!user) {
+    console.log('[WARN] WebSocket authentication failed');
+    return false;
+  }
+
+  request.user = user;
+  console.log('[OK] WebSocket authenticated for user:', user.username);
+  return true;
+}
diff --git a/server/modules/websocket/services/websocket-server.service.ts b/server/modules/websocket/services/websocket-server.service.ts
new file mode 100644
index 00000000..7e5c12e4
--- /dev/null
+++ b/server/modules/websocket/services/websocket-server.service.ts
@@ -0,0 +1,58 @@
+import type { Server as HttpServer } from 'node:http';
+
+import { WebSocketServer, type VerifyClientCallbackSync } from 'ws';
+
+import { handleChatConnection } from '@/modules/websocket/services/chat-websocket.service.js';
+import { verifyWebSocketClient } from '@/modules/websocket/services/websocket-auth.service.js';
+import { handlePluginWsProxy } from '@/modules/websocket/services/plugin-websocket-proxy.service.js';
+import { handleShellConnection } from '@/modules/websocket/services/shell-websocket.service.js';
+import type { AuthenticatedWebSocketRequest } from '@/shared/types.js';
+
+type WebSocketServerDependencies = {
+  verifyClient: Parameters<typeof verifyWebSocketClient>[1];
+  chat: Parameters<typeof handleChatConnection>[2];
+  shell: Parameters<typeof handleShellConnection>[1];
+  getPluginPort: Parameters<typeof handlePluginWsProxy>[2];
+};
+
+/**
+ * Creates and wires the server-wide websocket gateway used for chat, shell, and
+ * plugin proxy routes.
+ */
+export function createWebSocketServer(
+  server: HttpServer,
+  dependencies: WebSocketServerDependencies
+): WebSocketServer {
+  const wss = new WebSocketServer({
+    server,
+    verifyClient: ((
+      info: Parameters<VerifyClientCallbackSync<AuthenticatedWebSocketRequest>>[0]
+    ) => verifyWebSocketClient(info, dependencies.verifyClient)),
+  });
+
+  wss.on('connection', (ws, request) => {
+    const incomingRequest = request as AuthenticatedWebSocketRequest;
+    const url = incomingRequest.url ?? '/';
+    const pathname = new URL(url, 'http://localhost').pathname;
+
+    if (pathname === '/shell') {
+      handleShellConnection(ws, dependencies.shell);
+      return;
+    }
+
+    if (pathname === '/ws') {
+      handleChatConnection(ws, incomingRequest, dependencies.chat);
+      return;
+    }
+
+    if (pathname.startsWith('/plugin-ws/')) {
+      handlePluginWsProxy(ws, pathname, dependencies.getPluginPort);
+      return;
+    }
+
+    console.log('[WARN] Unknown WebSocket path:', pathname);
+    ws.close();
+  });
+
+  return wss;
+}
diff --git a/server/modules/websocket/services/websocket-state.service.ts b/server/modules/websocket/services/websocket-state.service.ts
new file mode 100644
index 00000000..3cffce24
--- /dev/null
+++ b/server/modules/websocket/services/websocket-state.service.ts
@@ -0,0 +1,16 @@
+import type { RealtimeClientConnection } from '@/shared/types.js';
+
+/**
+ * Numeric readyState for an open WebSocket connection.
+ *
+ * We keep this in module state so services that broadcast updates do not need
+ * to import `ws` directly just to compare open/closed state.
+ */
+export const WS_OPEN_STATE = 1;
+
+/**
+ * Shared registry of active chat WebSocket connections.
+ *
+ * Project/session services publish realtime updates by iterating this set.
+ */
+export const connectedClients = new Set<RealtimeClientConnection>();
diff --git a/server/modules/websocket/services/websocket-writer.service.ts b/server/modules/websocket/services/websocket-writer.service.ts
new file mode 100644
index 00000000..af307ad6
--- /dev/null
+++ b/server/modules/websocket/services/websocket-writer.service.ts
@@ -0,0 +1,38 @@
+import { WS_OPEN_STATE } from '@/modules/websocket/services/websocket-state.service.js';
+import type { RealtimeClientConnection } from '@/shared/types.js';
+
+/**
+ * Thin transport adapter that gives WebSocket connections the same interface as
+ * SSE writers used by API routes (`send`, `setSessionId`, `getSessionId`).
+ */
+export class WebSocketWriter {
+  ws: RealtimeClientConnection;
+  sessionId: string | null;
+  userId: string | number | null;
+  isWebSocketWriter: boolean;
+
+  constructor(ws: RealtimeClientConnection, userId: string | number | null = null) {
+    this.ws = ws;
+    this.sessionId = null;
+    this.userId = userId;
+    this.isWebSocketWriter = true;
+  }
+
+  send(data: unknown): void {
+    if (this.ws.readyState === WS_OPEN_STATE) {
+      this.ws.send(JSON.stringify(data));
+    }
+  }
+
+  updateWebSocket(newRawWs: RealtimeClientConnection): void {
+    this.ws = newRawWs;
+  }
+
+  setSessionId(sessionId: string): void {
+    this.sessionId = sessionId;
+  }
+
+  getSessionId(): string | null {
+    return this.sessionId;
+  }
+}
diff --git a/server/openai-codex.js b/server/openai-codex.js
index 5a7a9007..8e14fcdf 100644
--- a/server/openai-codex.js
+++ b/server/openai-codex.js
@@ -17,11 +17,40 @@ import { Codex } from '@openai/codex-sdk';
 import { notifyRunFailed, notifyRunStopped } from './services/notification-orchestrator.js';
 import { sessionsService } from './modules/providers/services/sessions.service.js';
 import { providerAuthService } from './modules/providers/services/provider-auth.service.js';
+import { providerModelsService } from './modules/providers/services/provider-models.service.js';
 import { createNormalizedMessage } from './shared/utils.js';
 
 // Track active sessions
 const activeCodexSessions = new Map();
 
+function readUsageNumber(value) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function extractCodexTokenBudget(event) {
+  const info = event?.info || event?.payload?.info || event?.usage?.info;
+  const usage = info?.total_token_usage || event?.usage?.total_token_usage || event?.usage;
+  if (!usage || typeof usage !== 'object') {
+    return null;
+  }
+
+  const inputTokens = readUsageNumber(usage.input_tokens);
+  const outputTokens = readUsageNumber(usage.output_tokens);
+  const used = readUsageNumber(usage.total_tokens) || inputTokens + outputTokens;
+
+  return {
+    used,
+    total: readUsageNumber(info?.model_context_window || event?.usage?.model_context_window) || 200000,
+    inputTokens,
+    outputTokens,
+    breakdown: {
+      input: inputTokens,
+      output: outputTokens,
+    },
+  };
+}
+
 /**
  * Transform Codex SDK event to WebSocket message format
  * @param {object} event - SDK event
@@ -143,7 +172,7 @@ function transformCodexEvent(event) {
     case 'thread.started':
       return {
         type: 'thread_started',
-        threadId: event.id
+        threadId: event.thread_id || event.id
       };
 
     case 'error':
@@ -202,12 +231,19 @@ export async function queryCodex(command, options = {}, ws) {
     permissionMode = 'default'
   } = options;
 
+  const resolvedModel = await providerModelsService.resolveResumeModel(
+    'codex',
+    sessionId,
+    model,
+  );
+
   const workingDirectory = cwd || projectPath || process.cwd();
   const { sandboxMode, approvalPolicy } = mapPermissionModeToCodexOptions(permissionMode);
 
   let codex;
   let thread;
-  let currentSessionId = sessionId;
+  let capturedSessionId = sessionId;
+  let sessionCreatedSent = false;
   let terminalFailure = null;
   const abortController = new AbortController();
 
@@ -221,7 +257,7 @@ export async function queryCodex(command, options = {}, ws) {
       skipGitRepoCheck: true,
       sandboxMode,
       approvalPolicy,
-      model
+      model: resolvedModel
     };
 
     // Start or resume thread
@@ -231,20 +267,23 @@ export async function queryCodex(command, options = {}, ws) {
       thread = codex.startThread(threadOptions);
     }
 
-    // Get the thread ID
-    currentSessionId = thread.id || sessionId || `codex-${Date.now()}`;
+    const registerSession = (id) => {
+      if (!id) {
+        return;
+      }
+      activeCodexSessions.set(id, {
+        thread,
+        codex,
+        status: 'running',
+        abortController,
+        startedAt: new Date().toISOString()
+      });
+    };
 
-    // Track the session
-    activeCodexSessions.set(currentSessionId, {
-      thread,
-      codex,
-      status: 'running',
-      abortController,
-      startedAt: new Date().toISOString()
-    });
-
-    // Send session created event
-    sendMessage(ws, createNormalizedMessage({ kind: 'session_created', newSessionId: currentSessionId, sessionId: currentSessionId, provider: 'codex' }));
+    // Existing sessions can be tracked immediately; new sessions are tracked after thread.started.
+    if (capturedSessionId) {
+      registerSession(capturedSessionId);
+    }
 
     // Execute with streaming
     const streamedTurn = await thread.runStreamed(command, {
@@ -252,11 +291,34 @@ export async function queryCodex(command, options = {}, ws) {
     });
 
     for await (const event of streamedTurn.events) {
+      // Capture thread/session id lazily from the stream (Codex emits this asynchronously).
+      if (event.type === 'thread.started') {
+        const discoveredSessionId = event.thread_id || event.id || null;
+        if (discoveredSessionId && !capturedSessionId) {
+          capturedSessionId = discoveredSessionId;
+          registerSession(capturedSessionId);
+
+          if (ws.setSessionId && typeof ws.setSessionId === 'function') {
+            ws.setSessionId(capturedSessionId);
+          }
+
+          if (!sessionId && !sessionCreatedSent) {
+            sessionCreatedSent = true;
+            sendMessage(ws, createNormalizedMessage({ kind: 'session_created', newSessionId: capturedSessionId, sessionId: capturedSessionId, provider: 'codex' }));
+          }
+        }
+      }
+
       // Check if session was aborted
-      const session = activeCodexSessions.get(currentSessionId);
-      if (!session || session.status === 'aborted') {
+      if (abortController.signal.aborted) {
         break;
       }
+      if (capturedSessionId) {
+        const session = activeCodexSessions.get(capturedSessionId);
+        if (session?.status === 'aborted') {
+          break;
+        }
+      }
 
       if (event.type === 'item.started' || event.type === 'item.updated') {
         continue;
@@ -265,7 +327,7 @@ export async function queryCodex(command, options = {}, ws) {
       const transformed = transformCodexEvent(event);
 
       // Normalize the transformed event into NormalizedMessage(s) via adapter
-      const normalizedMsgs = sessionsService.normalizeMessage('codex', transformed, currentSessionId);
+      const normalizedMsgs = sessionsService.normalizeMessage('codex', transformed, capturedSessionId || sessionId || null);
       for (const msg of normalizedMsgs) {
         sendMessage(ws, msg);
       }
@@ -275,33 +337,40 @@ export async function queryCodex(command, options = {}, ws) {
         notifyRunFailed({
           userId: ws?.userId || null,
           provider: 'codex',
-          sessionId: currentSessionId,
+          sessionId: capturedSessionId || sessionId || null,
           sessionName: sessionSummary,
           error: terminalFailure
         });
       }
 
       // Extract and send token usage if available (normalized to match Claude format)
-      if (event.type === 'turn.completed' && event.usage) {
-        const totalTokens = (event.usage.input_tokens || 0) + (event.usage.output_tokens || 0);
-        sendMessage(ws, createNormalizedMessage({ kind: 'status', text: 'token_budget', tokenBudget: { used: totalTokens, total: 200000 }, sessionId: currentSessionId, provider: 'codex' }));
+      if (event.type === 'turn.completed') {
+        const tokenBudget = extractCodexTokenBudget(event);
+        if (tokenBudget) {
+          sendMessage(ws, createNormalizedMessage({ kind: 'status', text: 'token_budget', tokenBudget, sessionId: capturedSessionId || sessionId || null, provider: 'codex' }));
+        }
       }
     }
 
     // Send completion event
     if (!terminalFailure) {
-      sendMessage(ws, createNormalizedMessage({ kind: 'complete', actualSessionId: thread.id, sessionId: currentSessionId, provider: 'codex' }));
+      sendMessage(ws, createNormalizedMessage({
+        kind: 'complete',
+        actualSessionId: capturedSessionId || thread.id || sessionId || null,
+        sessionId: capturedSessionId || sessionId || null,
+        provider: 'codex'
+      }));
       notifyRunStopped({
         userId: ws?.userId || null,
         provider: 'codex',
-        sessionId: currentSessionId,
+        sessionId: capturedSessionId || sessionId || null,
         sessionName: sessionSummary,
         stopReason: 'completed'
       });
     }
 
   } catch (error) {
-    const session = currentSessionId ? activeCodexSessions.get(currentSessionId) : null;
+    const session = capturedSessionId ? activeCodexSessions.get(capturedSessionId) : null;
     const wasAborted =
       session?.status === 'aborted' ||
       error?.name === 'AbortError' ||
@@ -316,12 +385,12 @@ export async function queryCodex(command, options = {}, ws) {
         ? 'Codex CLI is not configured. Please set up authentication first.'
         : error.message;
 
-      sendMessage(ws, createNormalizedMessage({ kind: 'error', content: errorContent, sessionId: currentSessionId, provider: 'codex' }));
+      sendMessage(ws, createNormalizedMessage({ kind: 'error', content: errorContent, sessionId: capturedSessionId || sessionId || null, provider: 'codex' }));
       if (!terminalFailure) {
         notifyRunFailed({
           userId: ws?.userId || null,
           provider: 'codex',
-          sessionId: currentSessionId,
+          sessionId: capturedSessionId || sessionId || null,
           sessionName: sessionSummary,
           error
         });
@@ -330,8 +399,8 @@ export async function queryCodex(command, options = {}, ws) {
 
   } finally {
     // Update session status
-    if (currentSessionId) {
-      const session = activeCodexSessions.get(currentSessionId);
+    if (capturedSessionId) {
+      const session = activeCodexSessions.get(capturedSessionId);
       if (session) {
         session.status = session.status === 'aborted' ? 'aborted' : 'completed';
       }
diff --git a/server/opencode-cli.js b/server/opencode-cli.js
new file mode 100644
index 00000000..6f3e0f65
--- /dev/null
+++ b/server/opencode-cli.js
@@ -0,0 +1,336 @@
+import { spawn } from 'child_process';
+import fsSync from 'node:fs';
+
+import crossSpawn from 'cross-spawn';
+import Database from 'better-sqlite3';
+
+import { sessionsService } from './modules/providers/services/sessions.service.js';
+import { providerAuthService } from './modules/providers/services/provider-auth.service.js';
+import { providerModelsService } from './modules/providers/services/provider-models.service.js';
+import { notifyRunFailed, notifyRunStopped } from './services/notification-orchestrator.js';
+import { createNormalizedMessage, getOpenCodeDatabasePath } from './shared/utils.js';
+
+const spawnFunction = process.platform === 'win32' ? crossSpawn : spawn;
+
+const activeOpenCodeProcesses = new Map();
+
+function readOpenCodeSessionId(event) {
+  if (!event || typeof event !== 'object') {
+    return null;
+  }
+
+  return event.sessionID || event.sessionId || null;
+}
+
+function readOpenCodeTokenUsage(sessionId) {
+  const dbPath = getOpenCodeDatabasePath();
+  if (!sessionId || !fsSync.existsSync(dbPath)) {
+    return null;
+  }
+
+  let db = null;
+  try {
+    db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    const columns = db.prepare('PRAGMA table_info(session)').all();
+    const columnNames = new Set(columns.map((column) => column.name));
+    const requiredColumns = ['tokens_input', 'tokens_output', 'tokens_reasoning', 'tokens_cache_read', 'tokens_cache_write'];
+    if (!requiredColumns.every((column) => columnNames.has(column))) {
+      return null;
+    }
+
+    const row = db.prepare(`
+      SELECT
+        tokens_input AS inputTokens,
+        tokens_output AS outputTokens,
+        tokens_reasoning AS reasoningTokens,
+        tokens_cache_read AS cacheReadTokens,
+        tokens_cache_write AS cacheWriteTokens
+      FROM session
+      WHERE id = ?
+    `).get(sessionId);
+
+    if (!row) {
+      return null;
+    }
+
+    const inputTokens = Number(row.inputTokens || 0) + Number(row.cacheReadTokens || 0);
+    const outputTokens = Number(row.outputTokens || 0);
+    const used = Number(row.inputTokens || 0)
+      + outputTokens
+      + Number(row.reasoningTokens || 0)
+      + Number(row.cacheReadTokens || 0)
+      + Number(row.cacheWriteTokens || 0);
+    if (used <= 0) {
+      return null;
+    }
+
+    return {
+      used,
+      inputTokens,
+      outputTokens,
+      breakdown: {
+        input: inputTokens,
+        output: outputTokens,
+      },
+    };
+  } catch {
+    return null;
+  } finally {
+    if (db) {
+      db.close();
+    }
+  }
+}
+
+async function spawnOpenCode(command, options = {}, ws) {
+  return new Promise((resolve, reject) => {
+    const { sessionId, projectPath, cwd, model, sessionSummary } = options;
+    const workingDir = cwd || projectPath || process.cwd();
+    const processKey = sessionId || Date.now().toString();
+    let capturedSessionId = sessionId || null;
+    let sessionCreatedSent = false;
+    let stdoutLineBuffer = '';
+    let terminalNotificationSent = false;
+    let opencodeProcess = null;
+
+    const notifyTerminalState = ({ code = null, error = null } = {}) => {
+      if (terminalNotificationSent) {
+        return;
+      }
+
+      terminalNotificationSent = true;
+      const finalSessionId = capturedSessionId || sessionId || processKey;
+      if (code === 0 && !error) {
+        notifyRunStopped({
+          userId: ws?.userId || null,
+          provider: 'opencode',
+          sessionId: finalSessionId,
+          sessionName: sessionSummary,
+          stopReason: 'completed',
+        });
+        return;
+      }
+
+      notifyRunFailed({
+        userId: ws?.userId || null,
+        provider: 'opencode',
+        sessionId: finalSessionId,
+        sessionName: sessionSummary,
+        error: error || `OpenCode CLI exited with code ${code}`,
+      });
+    };
+
+    const registerSession = (nextSessionId) => {
+      if (!nextSessionId || capturedSessionId === nextSessionId) {
+        return;
+      }
+
+      capturedSessionId = nextSessionId;
+      if (processKey !== capturedSessionId && opencodeProcess) {
+        activeOpenCodeProcesses.delete(processKey);
+        activeOpenCodeProcesses.set(capturedSessionId, opencodeProcess);
+      }
+      if (opencodeProcess) {
+        opencodeProcess.sessionId = capturedSessionId;
+      }
+
+      if (ws.setSessionId && typeof ws.setSessionId === 'function') {
+        ws.setSessionId(capturedSessionId);
+      }
+
+      if (!sessionId && !sessionCreatedSent) {
+        sessionCreatedSent = true;
+        ws.send(createNormalizedMessage({
+          kind: 'session_created',
+          newSessionId: capturedSessionId,
+          sessionId: capturedSessionId,
+          provider: 'opencode',
+        }));
+      }
+    };
+
+    const processOpenCodeOutputLine = (line) => {
+      if (!line || !line.trim()) {
+        return;
+      }
+
+      let response;
+      try {
+        response = JSON.parse(line);
+      } catch {
+        ws.send(createNormalizedMessage({
+          kind: 'stream_delta',
+          content: line,
+          sessionId: capturedSessionId || sessionId || null,
+          provider: 'opencode',
+        }));
+        return;
+      }
+
+      try {
+        registerSession(readOpenCodeSessionId(response));
+        const normalized = sessionsService.normalizeMessage(
+          'opencode',
+          response,
+          capturedSessionId || sessionId || null,
+        );
+        for (const msg of normalized) {
+          ws.send(msg);
+        }
+      } catch (error) {
+        const errorContent = error instanceof Error ? error.message : String(error);
+        console.error('[OpenCode] Failed to process JSON output:', errorContent);
+        ws.send(createNormalizedMessage({
+          kind: 'error',
+          content: errorContent,
+          sessionId: capturedSessionId || sessionId || null,
+          provider: 'opencode',
+        }));
+      }
+    };
+
+    void providerModelsService.resolveResumeModel('opencode', sessionId, model).then((resolvedModel) => {
+      const args = ['run', '--format', 'json'];
+      if (sessionId) {
+        args.push('--session', sessionId);
+      }
+      if (resolvedModel) {
+        args.push('--model', resolvedModel);
+      }
+      if (command && command.trim()) {
+        args.push(command.trim());
+      }
+
+      opencodeProcess = spawnFunction('opencode', args, {
+        cwd: workingDir,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env },
+      });
+
+      activeOpenCodeProcesses.set(processKey, opencodeProcess);
+      opencodeProcess.sessionId = processKey;
+      opencodeProcess.stdin.end();
+
+      opencodeProcess.stdout.on('data', (data) => {
+        stdoutLineBuffer += data.toString();
+        const completeLines = stdoutLineBuffer.split(/\r?\n/);
+        stdoutLineBuffer = completeLines.pop() || '';
+
+        completeLines.forEach((line) => {
+          processOpenCodeOutputLine(line.trim());
+        });
+      });
+
+      opencodeProcess.stderr.on('data', (data) => {
+        const stderrText = data.toString();
+        if (!stderrText.trim()) {
+          return;
+        }
+
+        ws.send(createNormalizedMessage({
+          kind: 'error',
+          content: stderrText,
+          sessionId: capturedSessionId || sessionId || null,
+          provider: 'opencode',
+        }));
+      });
+
+      opencodeProcess.on('close', async (code) => {
+        const finalSessionId = capturedSessionId || sessionId || processKey;
+        activeOpenCodeProcesses.delete(finalSessionId);
+        activeOpenCodeProcesses.delete(processKey);
+
+        if (stdoutLineBuffer.trim()) {
+          processOpenCodeOutputLine(stdoutLineBuffer.trim());
+          stdoutLineBuffer = '';
+        }
+
+        const tokenBudget = readOpenCodeTokenUsage(finalSessionId);
+        if (tokenBudget) {
+          ws.send(createNormalizedMessage({
+            kind: 'status',
+            text: 'token_budget',
+            tokenBudget,
+            sessionId: finalSessionId,
+            provider: 'opencode',
+          }));
+        }
+
+        ws.send(createNormalizedMessage({
+          kind: 'complete',
+          exitCode: code,
+          isNewSession: !sessionId && !!command,
+          sessionId: finalSessionId,
+          provider: 'opencode',
+        }));
+
+        if (code === 0) {
+          notifyTerminalState({ code });
+          resolve();
+          return;
+        }
+
+        if (code === 127 || code === null) {
+          const installed = await providerAuthService.isProviderInstalled('opencode');
+          if (!installed) {
+            ws.send(createNormalizedMessage({
+              kind: 'error',
+              content: 'OpenCode CLI is not installed. Install it from https://opencode.ai/docs/',
+              sessionId: finalSessionId,
+              provider: 'opencode',
+            }));
+          }
+        }
+
+        notifyTerminalState({ code });
+        reject(new Error(code === null ? 'OpenCode CLI process was terminated' : `OpenCode CLI exited with code ${code}`));
+      });
+
+      opencodeProcess.on('error', async (error) => {
+        const finalSessionId = capturedSessionId || sessionId || processKey;
+        activeOpenCodeProcesses.delete(finalSessionId);
+        activeOpenCodeProcesses.delete(processKey);
+
+        const installed = await providerAuthService.isProviderInstalled('opencode');
+        const errorContent = !installed
+          ? 'OpenCode CLI is not installed. Install it from https://opencode.ai/docs/'
+          : error.message;
+
+        ws.send(createNormalizedMessage({
+          kind: 'error',
+          content: errorContent,
+          sessionId: finalSessionId,
+          provider: 'opencode',
+        }));
+        notifyTerminalState({ error });
+        reject(error);
+      });
+    }).catch(reject);
+  });
+}
+
+function abortOpenCodeSession(sessionId) {
+  const process = activeOpenCodeProcesses.get(sessionId);
+  if (!process) {
+    return false;
+  }
+
+  process.kill('SIGTERM');
+  activeOpenCodeProcesses.delete(sessionId);
+  return true;
+}
+
+function isOpenCodeSessionActive(sessionId) {
+  return activeOpenCodeProcesses.has(sessionId);
+}
+
+function getActiveOpenCodeSessions() {
+  return Array.from(activeOpenCodeProcesses.keys());
+}
+
+export {
+  spawnOpenCode,
+  abortOpenCodeSession,
+  isOpenCodeSessionActive,
+  getActiveOpenCodeSessions,
+};
diff --git a/server/opencode-cli.test.js b/server/opencode-cli.test.js
new file mode 100644
index 00000000..082451c3
--- /dev/null
+++ b/server/opencode-cli.test.js
@@ -0,0 +1,95 @@
+import assert from 'node:assert/strict';
+import { chmod, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+
+import { spawnOpenCode } from './opencode-cli.js';
+
+const findEnvKey = (name) =>
+  Object.keys(process.env).find((key) => key.toLowerCase() === name.toLowerCase()) || name;
+
+async function createFakeOpenCodeExecutable(binDir) {
+  const scriptPath = path.join(binDir, 'opencode.js');
+  await writeFile(scriptPath, `
+const events = [
+  { type: 'text', sessionID: 'open-live-1', text: 'assistant response' },
+  { type: 'step_finish', sessionID: 'open-live-1' },
+];
+
+for (const event of events) {
+  console.log(JSON.stringify(event));
+}
+`, 'utf8');
+
+  if (process.platform === 'win32') {
+    const commandPath = path.join(binDir, 'opencode.cmd');
+    await writeFile(commandPath, '@echo off\r\nnode "%~dp0opencode.js" %*\r\n', 'utf8');
+    return;
+  }
+
+  const commandPath = path.join(binDir, 'opencode');
+  await writeFile(commandPath, '#!/bin/sh\nnode "$(dirname "$0")/opencode.js" "$@"\n', 'utf8');
+  await chmod(commandPath, 0o755);
+}
+
+test('spawnOpenCode emits session_created before normalized live messages for new sessions', async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'opencode-cli-live-'));
+  const pathKey = findEnvKey('PATH');
+  const pathExtKey = findEnvKey('PATHEXT');
+  const previousPath = process.env[pathKey];
+  const previousPathExt = process.env[pathExtKey];
+  const messages = [];
+  const writer = {
+    userId: null,
+    sessionId: null,
+    send(message) {
+      messages.push(message);
+    },
+    setSessionId(sessionId) {
+      this.sessionId = sessionId;
+    },
+  };
+
+  try {
+    await createFakeOpenCodeExecutable(tempRoot);
+    process.env[pathKey] = `${tempRoot}${path.delimiter}${previousPath || ''}`;
+    if (process.platform === 'win32') {
+      process.env[pathExtKey] = previousPathExt?.toUpperCase().includes('.CMD')
+        ? previousPathExt
+        : `.COM;.EXE;.BAT;.CMD${previousPathExt ? `;${previousPathExt}` : ''}`;
+    }
+
+    await spawnOpenCode('Hi', { cwd: tempRoot }, writer);
+
+    const sessionCreatedIndex = messages.findIndex((message) => message.kind === 'session_created');
+    const assistantDeltaIndex = messages.findIndex((message) =>
+      message.kind === 'stream_delta' && message.content === 'assistant response',
+    );
+    const streamEnd = messages.find((message) => message.kind === 'stream_end');
+    const complete = messages.find((message) => message.kind === 'complete');
+
+    assert.notEqual(sessionCreatedIndex, -1);
+    assert.notEqual(assistantDeltaIndex, -1);
+    assert.ok(sessionCreatedIndex < assistantDeltaIndex);
+    assert.equal(messages[sessionCreatedIndex].newSessionId, 'open-live-1');
+    assert.equal(writer.sessionId, 'open-live-1');
+    assert.equal(streamEnd?.sessionId, 'open-live-1');
+    assert.equal(complete?.sessionId, 'open-live-1');
+    assert.equal(messages.some((message) => message.kind === 'error'), false);
+  } finally {
+    if (previousPath === undefined) {
+      delete process.env[pathKey];
+    } else {
+      process.env[pathKey] = previousPath;
+    }
+
+    if (previousPathExt === undefined) {
+      delete process.env[pathExtKey];
+    } else {
+      process.env[pathExtKey] = previousPathExt;
+    }
+
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+});
diff --git a/server/projects.js b/server/projects.js
deleted file mode 100755
index 67184af0..00000000
--- a/server/projects.js
+++ /dev/null
@@ -1,2555 +0,0 @@
-/**
- * PROJECT DISCOVERY AND MANAGEMENT SYSTEM
- * ========================================
- * 
- * This module manages project discovery for both Claude CLI and Cursor CLI sessions.
- * 
- * ## Architecture Overview
- * 
- * 1. **Claude Projects** (stored in ~/.claude/projects/)
- *    - Each project is a directory named with the project path encoded (/ replaced with -)
- *    - Contains .jsonl files with conversation history including 'cwd' field
- *    - Project metadata stored in ~/.claude/project-config.json
- * 
- * 2. **Cursor Projects** (stored in ~/.cursor/chats/)
- *    - Each project directory is named with MD5 hash of the absolute project path
- *    - Example: /Users/john/myproject -> MD5 -> a1b2c3d4e5f6...
- *    - Contains session directories with SQLite databases (store.db)
- *    - Project path is NOT stored in the database - only in the MD5 hash
- * 
- * ## Project Discovery Strategy
- * 
- * 1. **Claude Projects Discovery**:
- *    - Scan ~/.claude/projects/ directory for Claude project folders
- *    - Extract actual project path from .jsonl files (cwd field)
- *    - Fall back to decoded directory name if no sessions exist
- * 
- * 2. **Cursor Sessions Discovery**:
- *    - For each KNOWN project (from Claude or manually added)
- *    - Compute MD5 hash of the project's absolute path
- *    - Check if ~/.cursor/chats/{md5_hash}/ directory exists
- *    - Read session metadata from SQLite store.db files
- * 
- * 3. **Manual Project Addition**:
- *    - Users can manually add project paths via UI
- *    - Stored in ~/.claude/project-config.json with 'manuallyAdded' flag
- *    - Allows discovering Cursor sessions for projects without Claude sessions
- * 
- * ## Critical Limitations
- * 
- * - **CANNOT discover Cursor-only projects**: From a quick check, there was no mention of
- *   the cwd of each project. if someone has the time, you can try to reverse engineer it.
- * 
- * - **Project relocation breaks history**: If a project directory is moved or renamed,
- *   the MD5 hash changes, making old Cursor sessions inaccessible unless the old
- *   path is known and manually added.
- * 
- * ## Error Handling
- * 
- * - Missing ~/.claude directory is handled gracefully with automatic creation
- * - ENOENT errors are caught and handled without crashing
- * - Empty arrays returned when no projects/sessions exist
- * 
- * ## Caching Strategy
- * 
- * - Project directory extraction is cached to minimize file I/O
- * - Cache is cleared when project configuration changes
- * - Session data is fetched on-demand, not cached
- */
-
-import { promises as fs } from 'fs';
-import fsSync from 'fs';
-import path from 'path';
-import readline from 'readline';
-import crypto from 'crypto';
-import Database from 'better-sqlite3';
-import os from 'os';
-import sessionManager from './sessionManager.js';
-import { applyCustomSessionNames } from './database/db.js';
-
-// Import TaskMaster detection functions
-async function detectTaskMasterFolder(projectPath) {
-  try {
-    const taskMasterPath = path.join(projectPath, '.taskmaster');
-
-    // Check if .taskmaster directory exists
-    try {
-      const stats = await fs.stat(taskMasterPath);
-      if (!stats.isDirectory()) {
-        return {
-          hasTaskmaster: false,
-          reason: '.taskmaster exists but is not a directory'
-        };
-      }
-    } catch (error) {
-      if (error.code === 'ENOENT') {
-        return {
-          hasTaskmaster: false,
-          reason: '.taskmaster directory not found'
-        };
-      }
-      throw error;
-    }
-
-    // Check for key TaskMaster files
-    const keyFiles = [
-      'tasks/tasks.json',
-      'config.json'
-    ];
-
-    const fileStatus = {};
-    let hasEssentialFiles = true;
-
-    for (const file of keyFiles) {
-      const filePath = path.join(taskMasterPath, file);
-      try {
-        await fs.access(filePath);
-        fileStatus[file] = true;
-      } catch (error) {
-        fileStatus[file] = false;
-        if (file === 'tasks/tasks.json') {
-          hasEssentialFiles = false;
-        }
-      }
-    }
-
-    // Parse tasks.json if it exists for metadata
-    let taskMetadata = null;
-    if (fileStatus['tasks/tasks.json']) {
-      try {
-        const tasksPath = path.join(taskMasterPath, 'tasks/tasks.json');
-        const tasksContent = await fs.readFile(tasksPath, 'utf8');
-        const tasksData = JSON.parse(tasksContent);
-
-        // Handle both tagged and legacy formats
-        let tasks = [];
-        if (tasksData.tasks) {
-          // Legacy format
-          tasks = tasksData.tasks;
-        } else {
-          // Tagged format - get tasks from all tags
-          Object.values(tasksData).forEach(tagData => {
-            if (tagData.tasks) {
-              tasks = tasks.concat(tagData.tasks);
-            }
-          });
-        }
-
-        // Calculate task statistics
-        const stats = tasks.reduce((acc, task) => {
-          acc.total++;
-          acc[task.status] = (acc[task.status] || 0) + 1;
-
-          // Count subtasks
-          if (task.subtasks) {
-            task.subtasks.forEach(subtask => {
-              acc.subtotalTasks++;
-              acc.subtasks = acc.subtasks || {};
-              acc.subtasks[subtask.status] = (acc.subtasks[subtask.status] || 0) + 1;
-            });
-          }
-
-          return acc;
-        }, {
-          total: 0,
-          subtotalTasks: 0,
-          pending: 0,
-          'in-progress': 0,
-          done: 0,
-          review: 0,
-          deferred: 0,
-          cancelled: 0,
-          subtasks: {}
-        });
-
-        taskMetadata = {
-          taskCount: stats.total,
-          subtaskCount: stats.subtotalTasks,
-          completed: stats.done || 0,
-          pending: stats.pending || 0,
-          inProgress: stats['in-progress'] || 0,
-          review: stats.review || 0,
-          completionPercentage: stats.total > 0 ? Math.round((stats.done / stats.total) * 100) : 0,
-          lastModified: (await fs.stat(tasksPath)).mtime.toISOString()
-        };
-      } catch (parseError) {
-        console.warn('Failed to parse tasks.json:', parseError.message);
-        taskMetadata = { error: 'Failed to parse tasks.json' };
-      }
-    }
-
-    return {
-      hasTaskmaster: true,
-      hasEssentialFiles,
-      files: fileStatus,
-      metadata: taskMetadata,
-      path: taskMasterPath
-    };
-
-  } catch (error) {
-    console.error('Error detecting TaskMaster folder:', error);
-    return {
-      hasTaskmaster: false,
-      reason: `Error checking directory: ${error.message}`
-    };
-  }
-}
-
-// Cache for extracted project directories
-const projectDirectoryCache = new Map();
-
-// Clear cache when needed (called when project files change)
-function clearProjectDirectoryCache() {
-  projectDirectoryCache.clear();
-}
-
-// Load project configuration file
-async function loadProjectConfig() {
-  const configPath = path.join(os.homedir(), '.claude', 'project-config.json');
-  try {
-    const configData = await fs.readFile(configPath, 'utf8');
-    return JSON.parse(configData);
-  } catch (error) {
-    // Return empty config if file doesn't exist
-    return {};
-  }
-}
-
-// Save project configuration file
-async function saveProjectConfig(config) {
-  const claudeDir = path.join(os.homedir(), '.claude');
-  const configPath = path.join(claudeDir, 'project-config.json');
-
-  // Ensure the .claude directory exists
-  try {
-    await fs.mkdir(claudeDir, { recursive: true });
-  } catch (error) {
-    if (error.code !== 'EEXIST') {
-      throw error;
-    }
-  }
-
-  await fs.writeFile(configPath, JSON.stringify(config, null, 2), 'utf8');
-}
-
-// Generate better display name from path
-async function generateDisplayName(projectName, actualProjectDir = null) {
-  // Use actual project directory if provided, otherwise decode from project name
-  let projectPath = actualProjectDir || projectName.replace(/-/g, '/');
-
-  // Try to read package.json from the project path
-  try {
-    const packageJsonPath = path.join(projectPath, 'package.json');
-    const packageData = await fs.readFile(packageJsonPath, 'utf8');
-    const packageJson = JSON.parse(packageData);
-
-    // Return the name from package.json if it exists
-    if (packageJson.name) {
-      return packageJson.name;
-    }
-  } catch (error) {
-    // Fall back to path-based naming if package.json doesn't exist or can't be read
-  }
-
-  // If it starts with /, it's an absolute path
-  if (projectPath.startsWith('/')) {
-    const parts = projectPath.split('/').filter(Boolean);
-    // Return only the last folder name
-    return parts[parts.length - 1] || projectPath;
-  }
-
-  return projectPath;
-}
-
-// Extract the actual project directory from JSONL sessions (with caching)
-async function extractProjectDirectory(projectName) {
-  // Check cache first
-  if (projectDirectoryCache.has(projectName)) {
-    return projectDirectoryCache.get(projectName);
-  }
-
-  // Check project config for originalPath (manually added projects via UI or platform)
-  // This handles projects with dashes in their directory names correctly
-  const config = await loadProjectConfig();
-  if (config[projectName]?.originalPath) {
-    const originalPath = config[projectName].originalPath;
-    projectDirectoryCache.set(projectName, originalPath);
-    return originalPath;
-  }
-
-  const projectDir = path.join(os.homedir(), '.claude', 'projects', projectName);
-  const cwdCounts = new Map();
-  let latestTimestamp = 0;
-  let latestCwd = null;
-  let extractedPath;
-
-  try {
-    // Check if the project directory exists
-    await fs.access(projectDir);
-
-    const files = await fs.readdir(projectDir);
-    const jsonlFiles = files.filter(file => file.endsWith('.jsonl'));
-
-    if (jsonlFiles.length === 0) {
-      // Fall back to decoded project name if no sessions
-      extractedPath = projectName.replace(/-/g, '/');
-    } else {
-      // Process all JSONL files to collect cwd values
-      for (const file of jsonlFiles) {
-        const jsonlFile = path.join(projectDir, file);
-        const fileStream = fsSync.createReadStream(jsonlFile);
-        const rl = readline.createInterface({
-          input: fileStream,
-          crlfDelay: Infinity
-        });
-
-        for await (const line of rl) {
-          if (line.trim()) {
-            try {
-              const entry = JSON.parse(line);
-
-              if (entry.cwd) {
-                // Count occurrences of each cwd
-                cwdCounts.set(entry.cwd, (cwdCounts.get(entry.cwd) || 0) + 1);
-
-                // Track the most recent cwd
-                const timestamp = new Date(entry.timestamp || 0).getTime();
-                if (timestamp > latestTimestamp) {
-                  latestTimestamp = timestamp;
-                  latestCwd = entry.cwd;
-                }
-              }
-            } catch (parseError) {
-              // Skip malformed lines
-            }
-          }
-        }
-      }
-
-      // Determine the best cwd to use
-      if (cwdCounts.size === 0) {
-        // No cwd found, fall back to decoded project name
-        extractedPath = projectName.replace(/-/g, '/');
-      } else if (cwdCounts.size === 1) {
-        // Only one cwd, use it
-        extractedPath = Array.from(cwdCounts.keys())[0];
-      } else {
-        // Multiple cwd values - prefer the most recent one if it has reasonable usage
-        const mostRecentCount = cwdCounts.get(latestCwd) || 0;
-        const maxCount = Math.max(...cwdCounts.values());
-
-        // Use most recent if it has at least 25% of the max count
-        if (mostRecentCount >= maxCount * 0.25) {
-          extractedPath = latestCwd;
-        } else {
-          // Otherwise use the most frequently used cwd
-          for (const [cwd, count] of cwdCounts.entries()) {
-            if (count === maxCount) {
-              extractedPath = cwd;
-              break;
-            }
-          }
-        }
-
-        // Fallback (shouldn't reach here)
-        if (!extractedPath) {
-          extractedPath = latestCwd || projectName.replace(/-/g, '/');
-        }
-      }
-    }
-
-    // Cache the result
-    projectDirectoryCache.set(projectName, extractedPath);
-
-    return extractedPath;
-
-  } catch (error) {
-    // If the directory doesn't exist, just use the decoded project name
-    if (error.code === 'ENOENT') {
-      extractedPath = projectName.replace(/-/g, '/');
-    } else {
-      console.error(`Error extracting project directory for ${projectName}:`, error);
-      // Fall back to decoded project name for other errors
-      extractedPath = projectName.replace(/-/g, '/');
-    }
-
-    // Cache the fallback result too
-    projectDirectoryCache.set(projectName, extractedPath);
-
-    return extractedPath;
-  }
-}
-
-async function getProjects(progressCallback = null) {
-  const claudeDir = path.join(os.homedir(), '.claude', 'projects');
-  const config = await loadProjectConfig();
-  const projects = [];
-  const existingProjects = new Set();
-  const codexSessionsIndexRef = { sessionsByProject: null };
-  let totalProjects = 0;
-  let processedProjects = 0;
-  let directories = [];
-
-  try {
-    // Check if the .claude/projects directory exists
-    await fs.access(claudeDir);
-
-    // First, get existing Claude projects from the file system
-    const entries = await fs.readdir(claudeDir, { withFileTypes: true });
-    directories = entries.filter(e => e.isDirectory());
-
-    // Build set of existing project names for later
-    directories.forEach(e => existingProjects.add(e.name));
-
-    // Count manual projects not already in directories
-    const manualProjectsCount = Object.entries(config)
-      .filter(([name, cfg]) => cfg.manuallyAdded && !existingProjects.has(name))
-      .length;
-
-    totalProjects = directories.length + manualProjectsCount;
-
-    for (const entry of directories) {
-      processedProjects++;
-
-      // Emit progress
-      if (progressCallback) {
-        progressCallback({
-          phase: 'loading',
-          current: processedProjects,
-          total: totalProjects,
-          currentProject: entry.name
-        });
-      }
-
-      // Extract actual project directory from JSONL sessions
-      const actualProjectDir = await extractProjectDirectory(entry.name);
-
-      // Get display name from config or generate one
-      const customName = config[entry.name]?.displayName;
-      const autoDisplayName = await generateDisplayName(entry.name, actualProjectDir);
-      const fullPath = actualProjectDir;
-
-      const project = {
-        name: entry.name,
-        path: actualProjectDir,
-        displayName: customName || autoDisplayName,
-        fullPath: fullPath,
-        isCustomName: !!customName,
-        sessions: [],
-        geminiSessions: [],
-        sessionMeta: {
-          hasMore: false,
-          total: 0
-        }
-      };
-
-      // Try to get sessions for this project (just first 5 for performance)
-      try {
-        const sessionResult = await getSessions(entry.name, 5, 0);
-        project.sessions = sessionResult.sessions || [];
-        project.sessionMeta = {
-          hasMore: sessionResult.hasMore,
-          total: sessionResult.total
-        };
-      } catch (e) {
-        console.warn(`Could not load sessions for project ${entry.name}:`, e.message);
-        project.sessionMeta = {
-          hasMore: false,
-          total: 0
-        };
-      }
-      applyCustomSessionNames(project.sessions, 'claude');
-
-      // Also fetch Cursor sessions for this project
-      try {
-        project.cursorSessions = await getCursorSessions(actualProjectDir);
-      } catch (e) {
-        console.warn(`Could not load Cursor sessions for project ${entry.name}:`, e.message);
-        project.cursorSessions = [];
-      }
-      applyCustomSessionNames(project.cursorSessions, 'cursor');
-
-      // Also fetch Codex sessions for this project
-      try {
-        project.codexSessions = await getCodexSessions(actualProjectDir, {
-          indexRef: codexSessionsIndexRef,
-        });
-      } catch (e) {
-        console.warn(`Could not load Codex sessions for project ${entry.name}:`, e.message);
-        project.codexSessions = [];
-      }
-      applyCustomSessionNames(project.codexSessions, 'codex');
-
-      // Also fetch Gemini sessions for this project (UI + CLI)
-      try {
-        const uiSessions = sessionManager.getProjectSessions(actualProjectDir) || [];
-        const cliSessions = await getGeminiCliSessions(actualProjectDir);
-        const uiIds = new Set(uiSessions.map(s => s.id));
-        const mergedGemini = [...uiSessions, ...cliSessions.filter(s => !uiIds.has(s.id))];
-        project.geminiSessions = mergedGemini;
-      } catch (e) {
-        console.warn(`Could not load Gemini sessions for project ${entry.name}:`, e.message);
-        project.geminiSessions = [];
-      }
-      applyCustomSessionNames(project.geminiSessions, 'gemini');
-
-      // Add TaskMaster detection
-      try {
-        const taskMasterResult = await detectTaskMasterFolder(actualProjectDir);
-        project.taskmaster = {
-          hasTaskmaster: taskMasterResult.hasTaskmaster,
-          hasEssentialFiles: taskMasterResult.hasEssentialFiles,
-          metadata: taskMasterResult.metadata,
-          status: taskMasterResult.hasTaskmaster && taskMasterResult.hasEssentialFiles ? 'configured' : 'not-configured'
-        };
-      } catch (e) {
-        console.warn(`Could not detect TaskMaster for project ${entry.name}:`, e.message);
-        project.taskmaster = {
-          hasTaskmaster: false,
-          hasEssentialFiles: false,
-          metadata: null,
-          status: 'error'
-        };
-      }
-
-      projects.push(project);
-    }
-  } catch (error) {
-    // If the directory doesn't exist (ENOENT), that's okay - just continue with empty projects
-    if (error.code !== 'ENOENT') {
-      console.error('Error reading projects directory:', error);
-    }
-    // Calculate total for manual projects only (no directories exist)
-    totalProjects = Object.entries(config)
-      .filter(([name, cfg]) => cfg.manuallyAdded)
-      .length;
-  }
-
-  // Add manually configured projects that don't exist as folders yet
-  for (const [projectName, projectConfig] of Object.entries(config)) {
-    if (!existingProjects.has(projectName) && projectConfig.manuallyAdded) {
-      processedProjects++;
-
-      // Emit progress for manual projects
-      if (progressCallback) {
-        progressCallback({
-          phase: 'loading',
-          current: processedProjects,
-          total: totalProjects,
-          currentProject: projectName
-        });
-      }
-
-      // Use the original path if available, otherwise extract from potential sessions
-      let actualProjectDir = projectConfig.originalPath;
-
-      if (!actualProjectDir) {
-        try {
-          actualProjectDir = await extractProjectDirectory(projectName);
-        } catch (error) {
-          // Fall back to decoded project name
-          actualProjectDir = projectName.replace(/-/g, '/');
-        }
-      }
-
-      const project = {
-        name: projectName,
-        path: actualProjectDir,
-        displayName: projectConfig.displayName || await generateDisplayName(projectName, actualProjectDir),
-        fullPath: actualProjectDir,
-        isCustomName: !!projectConfig.displayName,
-        isManuallyAdded: true,
-        sessions: [],
-        geminiSessions: [],
-        sessionMeta: {
-          hasMore: false,
-          total: 0
-        },
-        cursorSessions: [],
-        codexSessions: []
-      };
-
-      // Try to fetch Cursor sessions for manual projects too
-      try {
-        project.cursorSessions = await getCursorSessions(actualProjectDir);
-      } catch (e) {
-        console.warn(`Could not load Cursor sessions for manual project ${projectName}:`, e.message);
-      }
-      applyCustomSessionNames(project.cursorSessions, 'cursor');
-
-      // Try to fetch Codex sessions for manual projects too
-      try {
-        project.codexSessions = await getCodexSessions(actualProjectDir, {
-          indexRef: codexSessionsIndexRef,
-        });
-      } catch (e) {
-        console.warn(`Could not load Codex sessions for manual project ${projectName}:`, e.message);
-      }
-      applyCustomSessionNames(project.codexSessions, 'codex');
-
-      // Try to fetch Gemini sessions for manual projects too (UI + CLI)
-      try {
-        const uiSessions = sessionManager.getProjectSessions(actualProjectDir) || [];
-        const cliSessions = await getGeminiCliSessions(actualProjectDir);
-        const uiIds = new Set(uiSessions.map(s => s.id));
-        project.geminiSessions = [...uiSessions, ...cliSessions.filter(s => !uiIds.has(s.id))];
-      } catch (e) {
-        console.warn(`Could not load Gemini sessions for manual project ${projectName}:`, e.message);
-      }
-      applyCustomSessionNames(project.geminiSessions, 'gemini');
-
-      // Add TaskMaster detection for manual projects
-      try {
-        const taskMasterResult = await detectTaskMasterFolder(actualProjectDir);
-
-        // Determine TaskMaster status
-        let taskMasterStatus = 'not-configured';
-        if (taskMasterResult.hasTaskmaster && taskMasterResult.hasEssentialFiles) {
-          taskMasterStatus = 'taskmaster-only'; // We don't check MCP for manual projects in bulk
-        }
-
-        project.taskmaster = {
-          status: taskMasterStatus,
-          hasTaskmaster: taskMasterResult.hasTaskmaster,
-          hasEssentialFiles: taskMasterResult.hasEssentialFiles,
-          metadata: taskMasterResult.metadata
-        };
-      } catch (error) {
-        console.warn(`TaskMaster detection failed for manual project ${projectName}:`, error.message);
-        project.taskmaster = {
-          status: 'error',
-          hasTaskmaster: false,
-          hasEssentialFiles: false,
-          error: error.message
-        };
-      }
-
-      projects.push(project);
-    }
-  }
-
-  // Emit completion after all projects (including manual) are processed
-  if (progressCallback) {
-    progressCallback({
-      phase: 'complete',
-      current: totalProjects,
-      total: totalProjects
-    });
-  }
-
-  return projects;
-}
-
-async function getSessions(projectName, limit = 5, offset = 0) {
-  const projectDir = path.join(os.homedir(), '.claude', 'projects', projectName);
-
-  try {
-    const files = await fs.readdir(projectDir);
-    // agent-*.jsonl files contain session start data at this point. This needs to be revisited
-    // periodically to make sure only accurate data is there and no new functionality is added there
-    const jsonlFiles = files.filter(file => file.endsWith('.jsonl') && !file.startsWith('agent-'));
-
-    if (jsonlFiles.length === 0) {
-      return { sessions: [], hasMore: false, total: 0 };
-    }
-
-    // Sort files by modification time (newest first)
-    const filesWithStats = await Promise.all(
-      jsonlFiles.map(async (file) => {
-        const filePath = path.join(projectDir, file);
-        const stats = await fs.stat(filePath);
-        return { file, mtime: stats.mtime };
-      })
-    );
-    filesWithStats.sort((a, b) => b.mtime - a.mtime);
-
-    const allSessions = new Map();
-    const allEntries = [];
-    const uuidToSessionMap = new Map();
-
-    // Collect all sessions and entries from all files
-    for (const { file } of filesWithStats) {
-      const jsonlFile = path.join(projectDir, file);
-      const result = await parseJsonlSessions(jsonlFile);
-
-      result.sessions.forEach(session => {
-        if (!allSessions.has(session.id)) {
-          allSessions.set(session.id, session);
-        }
-      });
-
-      allEntries.push(...result.entries);
-
-      // Early exit optimization for large projects
-      if (allSessions.size >= (limit + offset) * 2 && allEntries.length >= Math.min(3, filesWithStats.length)) {
-        break;
-      }
-    }
-
-    // Build UUID-to-session mapping for timeline detection
-    allEntries.forEach(entry => {
-      if (entry.uuid && entry.sessionId) {
-        uuidToSessionMap.set(entry.uuid, entry.sessionId);
-      }
-    });
-
-    // Group sessions by first user message ID
-    const sessionGroups = new Map(); // firstUserMsgId -> { latestSession, allSessions[] }
-    const sessionToFirstUserMsgId = new Map(); // sessionId -> firstUserMsgId
-
-    // Find the first user message for each session
-    allEntries.forEach(entry => {
-      if (entry.sessionId && entry.type === 'user' && entry.parentUuid === null && entry.uuid) {
-        // This is a first user message in a session (parentUuid is null)
-        const firstUserMsgId = entry.uuid;
-
-        if (!sessionToFirstUserMsgId.has(entry.sessionId)) {
-          sessionToFirstUserMsgId.set(entry.sessionId, firstUserMsgId);
-
-          const session = allSessions.get(entry.sessionId);
-          if (session) {
-            if (!sessionGroups.has(firstUserMsgId)) {
-              sessionGroups.set(firstUserMsgId, {
-                latestSession: session,
-                allSessions: [session]
-              });
-            } else {
-              const group = sessionGroups.get(firstUserMsgId);
-              group.allSessions.push(session);
-
-              // Update latest session if this one is more recent
-              if (new Date(session.lastActivity) > new Date(group.latestSession.lastActivity)) {
-                group.latestSession = session;
-              }
-            }
-          }
-        }
-      }
-    });
-
-    // Collect all sessions that don't belong to any group (standalone sessions)
-    const groupedSessionIds = new Set();
-    sessionGroups.forEach(group => {
-      group.allSessions.forEach(session => groupedSessionIds.add(session.id));
-    });
-
-    const standaloneSessionsArray = Array.from(allSessions.values())
-      .filter(session => !groupedSessionIds.has(session.id));
-
-    // Combine grouped sessions (only show latest from each group) + standalone sessions
-    const latestFromGroups = Array.from(sessionGroups.values()).map(group => {
-      const session = { ...group.latestSession };
-      // Add metadata about grouping
-      if (group.allSessions.length > 1) {
-        session.isGrouped = true;
-        session.groupSize = group.allSessions.length;
-        session.groupSessions = group.allSessions.map(s => s.id);
-      }
-      return session;
-    });
-    const visibleSessions = [...latestFromGroups, ...standaloneSessionsArray]
-      .filter(session => !session.summary.startsWith('{ "'))
-      .sort((a, b) => new Date(b.lastActivity) - new Date(a.lastActivity));
-
-    const total = visibleSessions.length;
-    const paginatedSessions = visibleSessions.slice(offset, offset + limit);
-    const hasMore = offset + limit < total;
-
-    return {
-      sessions: paginatedSessions,
-      hasMore,
-      total,
-      offset,
-      limit
-    };
-  } catch (error) {
-    console.error(`Error reading sessions for project ${projectName}:`, error);
-    return { sessions: [], hasMore: false, total: 0 };
-  }
-}
-
-async function parseJsonlSessions(filePath) {
-  const sessions = new Map();
-  const entries = [];
-  const pendingSummaries = new Map(); // leafUuid -> summary for entries without sessionId
-
-  try {
-    const fileStream = fsSync.createReadStream(filePath);
-    const rl = readline.createInterface({
-      input: fileStream,
-      crlfDelay: Infinity
-    });
-
-    for await (const line of rl) {
-      if (line.trim()) {
-        try {
-          const entry = JSON.parse(line);
-          entries.push(entry);
-
-          // Handle summary entries that don't have sessionId yet
-          if (entry.type === 'summary' && entry.summary && !entry.sessionId && entry.leafUuid) {
-            pendingSummaries.set(entry.leafUuid, entry.summary);
-          }
-
-          if (entry.sessionId) {
-            if (!sessions.has(entry.sessionId)) {
-              sessions.set(entry.sessionId, {
-                id: entry.sessionId,
-                summary: 'New Session',
-                messageCount: 0,
-                lastActivity: new Date(),
-                cwd: entry.cwd || '',
-                lastUserMessage: null,
-                lastAssistantMessage: null
-              });
-            }
-
-            const session = sessions.get(entry.sessionId);
-
-            // Apply pending summary if this entry has a parentUuid that matches a pending summary
-            if (session.summary === 'New Session' && entry.parentUuid && pendingSummaries.has(entry.parentUuid)) {
-              session.summary = pendingSummaries.get(entry.parentUuid);
-            }
-
-            // Update summary from summary entries with sessionId
-            if (entry.type === 'summary' && entry.summary) {
-              session.summary = entry.summary;
-            }
-
-            // Track last user and assistant messages (skip system messages)
-            if (entry.message?.role === 'user' && entry.message?.content) {
-              const content = entry.message.content;
-
-              // Extract text from array format if needed
-              let textContent = content;
-              if (Array.isArray(content) && content.length > 0 && content[0].type === 'text') {
-                textContent = content[0].text;
-              }
-
-              const isSystemMessage = typeof textContent === 'string' && (
-                textContent.startsWith('<command-name>') ||
-                textContent.startsWith('<command-message>') ||
-                textContent.startsWith('<command-args>') ||
-                textContent.startsWith('<local-command-stdout>') ||
-                textContent.startsWith('<system-reminder>') ||
-                textContent.startsWith('Caveat:') ||
-                textContent.startsWith('This session is being continued from a previous') ||
-                textContent.startsWith('Invalid API key') ||
-                textContent.includes('{"subtasks":') || // Filter Task Master prompts
-                textContent.includes('CRITICAL: You MUST respond with ONLY a JSON') || // Filter Task Master system prompts
-                textContent === 'Warmup' // Explicitly filter out "Warmup"
-              );
-
-              if (typeof textContent === 'string' && textContent.length > 0 && !isSystemMessage) {
-                session.lastUserMessage = textContent;
-              }
-            } else if (entry.message?.role === 'assistant' && entry.message?.content) {
-              // Skip API error messages using the isApiErrorMessage flag
-              if (entry.isApiErrorMessage === true) {
-                // Skip this message entirely
-              } else {
-                // Track last assistant text message
-                let assistantText = null;
-
-                if (Array.isArray(entry.message.content)) {
-                  for (const part of entry.message.content) {
-                    if (part.type === 'text' && part.text) {
-                      assistantText = part.text;
-                    }
-                  }
-                } else if (typeof entry.message.content === 'string') {
-                  assistantText = entry.message.content;
-                }
-
-                // Additional filter for assistant messages with system content
-                const isSystemAssistantMessage = typeof assistantText === 'string' && (
-                  assistantText.startsWith('Invalid API key') ||
-                  assistantText.includes('{"subtasks":') ||
-                  assistantText.includes('CRITICAL: You MUST respond with ONLY a JSON')
-                );
-
-                if (assistantText && !isSystemAssistantMessage) {
-                  session.lastAssistantMessage = assistantText;
-                }
-              }
-            }
-
-            session.messageCount++;
-
-            if (entry.timestamp) {
-              session.lastActivity = new Date(entry.timestamp);
-            }
-          }
-        } catch (parseError) {
-          // Skip malformed lines silently
-        }
-      }
-    }
-
-    // After processing all entries, set final summary based on last message if no summary exists
-    for (const session of sessions.values()) {
-      if (session.summary === 'New Session') {
-        // Prefer last user message, fall back to last assistant message
-        const lastMessage = session.lastUserMessage || session.lastAssistantMessage;
-        if (lastMessage) {
-          session.summary = lastMessage.length > 50 ? lastMessage.substring(0, 50) + '...' : lastMessage;
-        }
-      }
-    }
-
-    // Filter out sessions that contain JSON responses (Task Master errors)
-    const allSessions = Array.from(sessions.values());
-    const filteredSessions = allSessions.filter(session => {
-      const shouldFilter = session.summary.startsWith('{ "');
-      if (shouldFilter) {
-      }
-      // Log a sample of summaries to debug
-      if (Math.random() < 0.01) { // Log 1% of sessions
-      }
-      return !shouldFilter;
-    });
-
-
-    return {
-      sessions: filteredSessions,
-      entries: entries
-    };
-
-  } catch (error) {
-    console.error('Error reading JSONL file:', error);
-    return { sessions: [], entries: [] };
-  }
-}
-
-// Parse an agent JSONL file and extract tool uses
-async function parseAgentTools(filePath) {
-  const tools = [];
-
-  try {
-    const fileStream = fsSync.createReadStream(filePath);
-    const rl = readline.createInterface({
-      input: fileStream,
-      crlfDelay: Infinity
-    });
-
-    for await (const line of rl) {
-      if (line.trim()) {
-        try {
-          const entry = JSON.parse(line);
-          // Look for assistant messages with tool_use
-          if (entry.message?.role === 'assistant' && Array.isArray(entry.message?.content)) {
-            for (const part of entry.message.content) {
-              if (part.type === 'tool_use') {
-                tools.push({
-                  toolId: part.id,
-                  toolName: part.name,
-                  toolInput: part.input,
-                  timestamp: entry.timestamp
-                });
-              }
-            }
-          }
-          // Look for tool results
-          if (entry.message?.role === 'user' && Array.isArray(entry.message?.content)) {
-            for (const part of entry.message.content) {
-              if (part.type === 'tool_result') {
-                // Find the matching tool and add result
-                const tool = tools.find(t => t.toolId === part.tool_use_id);
-                if (tool) {
-                  tool.toolResult = {
-                    content: typeof part.content === 'string' ? part.content :
-                      Array.isArray(part.content) ? part.content.map(c => c.text || '').join('\n') :
-                        JSON.stringify(part.content),
-                    isError: Boolean(part.is_error)
-                  };
-                }
-              }
-            }
-          }
-        } catch (parseError) {
-          // Skip malformed lines
-        }
-      }
-    }
-  } catch (error) {
-    console.warn(`Error parsing agent file ${filePath}:`, error.message);
-  }
-
-  return tools;
-}
-
-// Get messages for a specific session with pagination support
-async function getSessionMessages(projectName, sessionId, limit = null, offset = 0) {
-  const projectDir = path.join(os.homedir(), '.claude', 'projects', projectName);
-
-  try {
-    const files = await fs.readdir(projectDir);
-    // agent-*.jsonl files contain subagent tool history - we'll process them separately
-    const jsonlFiles = files.filter(file => file.endsWith('.jsonl') && !file.startsWith('agent-'));
-    const agentFiles = files.filter(file => file.endsWith('.jsonl') && file.startsWith('agent-'));
-
-    if (jsonlFiles.length === 0) {
-      return { messages: [], total: 0, hasMore: false };
-    }
-
-    const messages = [];
-    // Map of agentId -> tools for subagent tool grouping
-    const agentToolsCache = new Map();
-
-    // Process all JSONL files to find messages for this session
-    for (const file of jsonlFiles) {
-      const jsonlFile = path.join(projectDir, file);
-      const fileStream = fsSync.createReadStream(jsonlFile);
-      const rl = readline.createInterface({
-        input: fileStream,
-        crlfDelay: Infinity
-      });
-
-      for await (const line of rl) {
-        if (line.trim()) {
-          try {
-            const entry = JSON.parse(line);
-            if (entry.sessionId === sessionId) {
-              messages.push(entry);
-            }
-          } catch (parseError) {
-            // Silently skip malformed JSONL lines (common with concurrent writes)
-          }
-        }
-      }
-    }
-
-    // Collect agentIds from Task tool results
-    const agentIds = new Set();
-    for (const message of messages) {
-      if (message.toolUseResult?.agentId) {
-        agentIds.add(message.toolUseResult.agentId);
-      }
-    }
-
-    // Load agent tools for each agentId found
-    for (const agentId of agentIds) {
-      const agentFileName = `agent-${agentId}.jsonl`;
-      if (agentFiles.includes(agentFileName)) {
-        const agentFilePath = path.join(projectDir, agentFileName);
-        const tools = await parseAgentTools(agentFilePath);
-        agentToolsCache.set(agentId, tools);
-      }
-    }
-
-    // Attach agent tools to their parent Task messages
-    for (const message of messages) {
-      if (message.toolUseResult?.agentId) {
-        const agentId = message.toolUseResult.agentId;
-        const agentTools = agentToolsCache.get(agentId);
-        if (agentTools && agentTools.length > 0) {
-          message.subagentTools = agentTools;
-        }
-      }
-    }
-    // Sort messages by timestamp
-    const sortedMessages = messages.sort((a, b) =>
-      new Date(a.timestamp || 0) - new Date(b.timestamp || 0)
-    );
-
-    const total = sortedMessages.length;
-
-    // If no limit is specified, return all messages (backward compatibility)
-    if (limit === null) {
-      return sortedMessages;
-    }
-
-    // Apply pagination - for recent messages, we need to slice from the end
-    // offset 0 should give us the most recent messages
-    const startIndex = Math.max(0, total - offset - limit);
-    const endIndex = total - offset;
-    const paginatedMessages = sortedMessages.slice(startIndex, endIndex);
-    const hasMore = startIndex > 0;
-
-    return {
-      messages: paginatedMessages,
-      total,
-      hasMore,
-      offset,
-      limit
-    };
-  } catch (error) {
-    console.error(`Error reading messages for session ${sessionId}:`, error);
-    return limit === null ? [] : { messages: [], total: 0, hasMore: false };
-  }
-}
-
-// Rename a project's display name
-async function renameProject(projectName, newDisplayName) {
-  const config = await loadProjectConfig();
-
-  if (!newDisplayName || newDisplayName.trim() === '') {
-    // Remove custom name if empty, will fall back to auto-generated
-    if (config[projectName]) {
-      delete config[projectName].displayName;
-    }
-  } else {
-    // Set custom display name, preserving other properties (manuallyAdded, originalPath)
-    config[projectName] = {
-      ...config[projectName],
-      displayName: newDisplayName.trim()
-    };
-  }
-
-  await saveProjectConfig(config);
-  return true;
-}
-
-// Delete a session from a project
-async function deleteSession(projectName, sessionId) {
-  const projectDir = path.join(os.homedir(), '.claude', 'projects', projectName);
-
-  try {
-    const files = await fs.readdir(projectDir);
-    const jsonlFiles = files.filter(file => file.endsWith('.jsonl'));
-
-    if (jsonlFiles.length === 0) {
-      throw new Error('No session files found for this project');
-    }
-
-    // Check all JSONL files to find which one contains the session
-    for (const file of jsonlFiles) {
-      const jsonlFile = path.join(projectDir, file);
-      const content = await fs.readFile(jsonlFile, 'utf8');
-      const lines = content.split('\n').filter(line => line.trim());
-
-      // Check if this file contains the session
-      const hasSession = lines.some(line => {
-        try {
-          const data = JSON.parse(line);
-          return data.sessionId === sessionId;
-        } catch {
-          return false;
-        }
-      });
-
-      if (hasSession) {
-        // Filter out all entries for this session
-        const filteredLines = lines.filter(line => {
-          try {
-            const data = JSON.parse(line);
-            return data.sessionId !== sessionId;
-          } catch {
-            return true; // Keep malformed lines
-          }
-        });
-
-        // Write back the filtered content
-        await fs.writeFile(jsonlFile, filteredLines.join('\n') + (filteredLines.length > 0 ? '\n' : ''));
-        return true;
-      }
-    }
-
-    throw new Error(`Session ${sessionId} not found in any files`);
-  } catch (error) {
-    console.error(`Error deleting session ${sessionId} from project ${projectName}:`, error);
-    throw error;
-  }
-}
-
-// Check if a project is empty (has no sessions)
-async function isProjectEmpty(projectName) {
-  try {
-    const sessionsResult = await getSessions(projectName, 1, 0);
-    return sessionsResult.total === 0;
-  } catch (error) {
-    console.error(`Error checking if project ${projectName} is empty:`, error);
-    return false;
-  }
-}
-
-// Remove a project from the UI.
-// When deleteData=true, also delete session/memory files on disk (destructive).
-async function deleteProject(projectName, force = false, deleteData = false) {
-  const projectDir = path.join(os.homedir(), '.claude', 'projects', projectName);
-
-  try {
-    const isEmpty = await isProjectEmpty(projectName);
-    if (!isEmpty && !force) {
-      throw new Error('Cannot delete project with existing sessions');
-    }
-
-    const config = await loadProjectConfig();
-
-    // Destructive path: delete underlying data when explicitly requested
-    if (deleteData) {
-      let projectPath = config[projectName]?.path || config[projectName]?.originalPath;
-      if (!projectPath) {
-        projectPath = await extractProjectDirectory(projectName);
-      }
-
-      // Remove the Claude project directory (session logs, memory, subagent data)
-      await fs.rm(projectDir, { recursive: true, force: true });
-
-      // Delete Codex sessions associated with this project
-      if (projectPath) {
-        try {
-          const codexSessions = await getCodexSessions(projectPath, { limit: 0 });
-          for (const session of codexSessions) {
-            try {
-              await deleteCodexSession(session.id);
-            } catch (err) {
-              console.warn(`Failed to delete Codex session ${session.id}:`, err.message);
-            }
-          }
-        } catch (err) {
-          console.warn('Failed to delete Codex sessions:', err.message);
-        }
-
-        // Delete Cursor sessions directory if it exists
-        try {
-          const hash = crypto.createHash('md5').update(projectPath).digest('hex');
-          const cursorProjectDir = path.join(os.homedir(), '.cursor', 'chats', hash);
-          await fs.rm(cursorProjectDir, { recursive: true, force: true });
-        } catch (err) {
-          // Cursor dir may not exist, ignore
-        }
-      }
-    }
-
-    // Always remove from project config
-    delete config[projectName];
-    await saveProjectConfig(config);
-
-    return true;
-  } catch (error) {
-    console.error(`Error removing project ${projectName}:`, error);
-    throw error;
-  }
-}
-
-// Add a project manually to the config (without creating folders)
-async function addProjectManually(projectPath, displayName = null) {
-  const absolutePath = path.resolve(projectPath);
-
-  try {
-    // Check if the path exists
-    await fs.access(absolutePath);
-  } catch (error) {
-    throw new Error(`Path does not exist: ${absolutePath}`);
-  }
-
-  // Generate project name (encode path for use as directory name)
-  const projectName = absolutePath.replace(/[\\/:\s~_]/g, '-');
-
-  // Check if project already exists in config
-  const config = await loadProjectConfig();
-  const projectDir = path.join(os.homedir(), '.claude', 'projects', projectName);
-
-  if (config[projectName]) {
-    throw new Error(`Project already configured for path: ${absolutePath}`);
-  }
-
-  // Allow adding projects even if the directory exists - this enables tracking
-  // existing Claude Code or Cursor projects in the UI
-
-  // Add to config as manually added project
-  config[projectName] = {
-    manuallyAdded: true,
-    originalPath: absolutePath
-  };
-
-  if (displayName) {
-    config[projectName].displayName = displayName;
-  }
-
-  await saveProjectConfig(config);
-
-
-  return {
-    name: projectName,
-    path: absolutePath,
-    fullPath: absolutePath,
-    displayName: displayName || await generateDisplayName(projectName, absolutePath),
-    isManuallyAdded: true,
-    sessions: [],
-    cursorSessions: []
-  };
-}
-
-// Fetch Cursor sessions for a given project path
-async function getCursorSessions(projectPath) {
-  try {
-    // Calculate cwdID hash for the project path (Cursor uses MD5 hash)
-    const cwdId = crypto.createHash('md5').update(projectPath).digest('hex');
-    const cursorChatsPath = path.join(os.homedir(), '.cursor', 'chats', cwdId);
-
-    // Check if the directory exists
-    try {
-      await fs.access(cursorChatsPath);
-    } catch (error) {
-      // No sessions for this project
-      return [];
-    }
-
-    // List all session directories
-    const sessionDirs = await fs.readdir(cursorChatsPath);
-    const sessions = [];
-
-    for (const sessionId of sessionDirs) {
-      const sessionPath = path.join(cursorChatsPath, sessionId);
-      const storeDbPath = path.join(sessionPath, 'store.db');
-
-      try {
-        // Check if store.db exists
-        await fs.access(storeDbPath);
-
-        // Capture store.db mtime as a reliable fallback timestamp
-        let dbStatMtimeMs = null;
-        try {
-          const stat = await fs.stat(storeDbPath);
-          dbStatMtimeMs = stat.mtimeMs;
-        } catch (_) { }
-
-        // Open SQLite database
-        const db = new Database(storeDbPath, { readonly: true, fileMustExist: true });
-
-        // Get metadata from meta table
-        const metaRows = db.prepare('SELECT key, value FROM meta').all();
-
-        // Parse metadata
-        let metadata = {};
-        for (const row of metaRows) {
-          if (row.value) {
-            try {
-              // Try to decode as hex-encoded JSON
-              const hexMatch = row.value.toString().match(/^[0-9a-fA-F]+$/);
-              if (hexMatch) {
-                const jsonStr = Buffer.from(row.value, 'hex').toString('utf8');
-                metadata[row.key] = JSON.parse(jsonStr);
-              } else {
-                metadata[row.key] = row.value.toString();
-              }
-            } catch (e) {
-              metadata[row.key] = row.value.toString();
-            }
-          }
-        }
-
-        // Get message count
-        const messageCountResult = db.prepare('SELECT COUNT(*) as count FROM blobs').get();
-
-        db.close();
-
-        // Extract session info
-        const sessionName = metadata.title || metadata.sessionTitle || 'Untitled Session';
-
-        // Determine timestamp - prefer createdAt from metadata, fall back to db file mtime
-        let createdAt = null;
-        if (metadata.createdAt) {
-          createdAt = new Date(metadata.createdAt).toISOString();
-        } else if (dbStatMtimeMs) {
-          createdAt = new Date(dbStatMtimeMs).toISOString();
-        } else {
-          createdAt = new Date().toISOString();
-        }
-
-        sessions.push({
-          id: sessionId,
-          name: sessionName,
-          createdAt: createdAt,
-          lastActivity: createdAt, // For compatibility with Claude sessions
-          messageCount: messageCountResult.count || 0,
-          projectPath: projectPath
-        });
-
-      } catch (error) {
-        console.warn(`Could not read Cursor session ${sessionId}:`, error.message);
-      }
-    }
-
-    // Sort sessions by creation time (newest first)
-    sessions.sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));
-
-    // Return only the first 5 sessions for performance
-    return sessions.slice(0, 5);
-
-  } catch (error) {
-    console.error('Error fetching Cursor sessions:', error);
-    return [];
-  }
-}
-
-
-function normalizeComparablePath(inputPath) {
-  if (!inputPath || typeof inputPath !== 'string') {
-    return '';
-  }
-
-  const withoutLongPathPrefix = inputPath.startsWith('\\\\?\\')
-    ? inputPath.slice(4)
-    : inputPath;
-  const normalized = path.normalize(withoutLongPathPrefix.trim());
-
-  if (!normalized) {
-    return '';
-  }
-
-  const resolved = path.resolve(normalized);
-  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
-}
-
-async function findCodexJsonlFiles(dir) {
-  const files = [];
-
-  try {
-    const entries = await fs.readdir(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      const fullPath = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        files.push(...await findCodexJsonlFiles(fullPath));
-      } else if (entry.name.endsWith('.jsonl')) {
-        files.push(fullPath);
-      }
-    }
-  } catch (error) {
-    // Skip directories we can't read
-  }
-
-  return files;
-}
-
-async function buildCodexSessionsIndex() {
-  const codexSessionsDir = path.join(os.homedir(), '.codex', 'sessions');
-  const sessionsByProject = new Map();
-
-  try {
-    await fs.access(codexSessionsDir);
-  } catch (error) {
-    return sessionsByProject;
-  }
-
-  const jsonlFiles = await findCodexJsonlFiles(codexSessionsDir);
-
-  for (const filePath of jsonlFiles) {
-    try {
-      const sessionData = await parseCodexSessionFile(filePath);
-      if (!sessionData || !sessionData.id) {
-        continue;
-      }
-
-      const normalizedProjectPath = normalizeComparablePath(sessionData.cwd);
-      if (!normalizedProjectPath) {
-        continue;
-      }
-
-      const session = {
-        id: sessionData.id,
-        summary: sessionData.summary || 'Codex Session',
-        messageCount: sessionData.messageCount || 0,
-        lastActivity: sessionData.timestamp ? new Date(sessionData.timestamp) : new Date(),
-        cwd: sessionData.cwd,
-        model: sessionData.model,
-        filePath,
-        provider: 'codex',
-      };
-
-      if (!sessionsByProject.has(normalizedProjectPath)) {
-        sessionsByProject.set(normalizedProjectPath, []);
-      }
-
-      sessionsByProject.get(normalizedProjectPath).push(session);
-    } catch (error) {
-      console.warn(`Could not parse Codex session file ${filePath}:`, error.message);
-    }
-  }
-
-  for (const sessions of sessionsByProject.values()) {
-    sessions.sort((a, b) => new Date(b.lastActivity) - new Date(a.lastActivity));
-  }
-
-  return sessionsByProject;
-}
-
-// Fetch Codex sessions for a given project path
-async function getCodexSessions(projectPath, options = {}) {
-  const { limit = 5, indexRef = null } = options;
-  try {
-    const normalizedProjectPath = normalizeComparablePath(projectPath);
-    if (!normalizedProjectPath) {
-      return [];
-    }
-
-    if (indexRef && !indexRef.sessionsByProject) {
-      indexRef.sessionsByProject = await buildCodexSessionsIndex();
-    }
-
-    const sessionsByProject = indexRef?.sessionsByProject || await buildCodexSessionsIndex();
-    const sessions = sessionsByProject.get(normalizedProjectPath) || [];
-
-    // Return limited sessions for performance (0 = unlimited for deletion)
-    return limit > 0 ? sessions.slice(0, limit) : [...sessions];
-
-  } catch (error) {
-    console.error('Error fetching Codex sessions:', error);
-    return [];
-  }
-}
-
-function isVisibleCodexUserMessage(payload) {
-  if (!payload || payload.type !== 'user_message') {
-    return false;
-  }
-
-  // Codex logs internal context (environment, instructions) as non-plain user_message kinds.
-  if (payload.kind && payload.kind !== 'plain') {
-    return false;
-  }
-
-  if (typeof payload.message !== 'string' || payload.message.trim().length === 0) {
-    return false;
-  }
-  
-  return true;
-}
-
-// Parse a Codex session JSONL file to extract metadata
-async function parseCodexSessionFile(filePath) {
-  try {
-    const fileStream = fsSync.createReadStream(filePath);
-    const rl = readline.createInterface({
-      input: fileStream,
-      crlfDelay: Infinity
-    });
-
-    let sessionMeta = null;
-    let lastTimestamp = null;
-    let lastUserMessage = null;
-    let messageCount = 0;
-
-    for await (const line of rl) {
-      if (line.trim()) {
-        try {
-          const entry = JSON.parse(line);
-
-          // Track timestamp
-          if (entry.timestamp) {
-            lastTimestamp = entry.timestamp;
-          }
-
-          // Extract session metadata
-          if (entry.type === 'session_meta' && entry.payload) {
-            sessionMeta = {
-              id: entry.payload.id,
-              cwd: entry.payload.cwd,
-              model: entry.payload.model || entry.payload.model_provider,
-              timestamp: entry.timestamp,
-              git: entry.payload.git
-            };
-          }
-
-          // Count visible user messages and extract summary from the latest plain user input.
-          if (entry.type === 'event_msg' && isVisibleCodexUserMessage(entry.payload)) {
-            messageCount++;
-            if (entry.payload.message) {
-              lastUserMessage = entry.payload.message;
-            }
-          }
-
-          if (entry.type === 'response_item' && entry.payload?.type === 'message' && entry.payload.role === 'assistant') {
-            messageCount++;
-          }
-
-        } catch (parseError) {
-          // Skip malformed lines
-        }
-      }
-    }
-
-    if (sessionMeta) {
-      return {
-        ...sessionMeta,
-        timestamp: lastTimestamp || sessionMeta.timestamp,
-        summary: lastUserMessage ?
-          (lastUserMessage.length > 50 ? lastUserMessage.substring(0, 50) + '...' : lastUserMessage) :
-          'Codex Session',
-        messageCount
-      };
-    }
-
-    return null;
-
-  } catch (error) {
-    console.error('Error parsing Codex session file:', error);
-    return null;
-  }
-}
-
-// Get messages for a specific Codex session
-async function getCodexSessionMessages(sessionId, limit = null, offset = 0) {
-  try {
-    const codexSessionsDir = path.join(os.homedir(), '.codex', 'sessions');
-
-    // Find the session file by searching for the session ID
-    const findSessionFile = async (dir) => {
-      try {
-        const entries = await fs.readdir(dir, { withFileTypes: true });
-        for (const entry of entries) {
-          const fullPath = path.join(dir, entry.name);
-          if (entry.isDirectory()) {
-            const found = await findSessionFile(fullPath);
-            if (found) return found;
-          } else if (entry.name.includes(sessionId) && entry.name.endsWith('.jsonl')) {
-            return fullPath;
-          }
-        }
-      } catch (error) {
-        // Skip directories we can't read
-      }
-      return null;
-    };
-
-    const sessionFilePath = await findSessionFile(codexSessionsDir);
-
-    if (!sessionFilePath) {
-      console.warn(`Codex session file not found for session ${sessionId}`);
-      return { messages: [], total: 0, hasMore: false };
-    }
-
-    const messages = [];
-    let tokenUsage = null;
-    const fileStream = fsSync.createReadStream(sessionFilePath);
-    const rl = readline.createInterface({
-      input: fileStream,
-      crlfDelay: Infinity
-    });
-
-    // Helper to extract text from Codex content array
-    const extractText = (content) => {
-      if (!Array.isArray(content)) return content;
-      return content
-        .map(item => {
-          if (item.type === 'input_text' || item.type === 'output_text') {
-            return item.text;
-          }
-          if (item.type === 'text') {
-            return item.text;
-          }
-          return '';
-        })
-        .filter(Boolean)
-        .join('\n');
-    };
-
-    for await (const line of rl) {
-      if (line.trim()) {
-        try {
-          const entry = JSON.parse(line);
-
-          // Extract token usage from token_count events (keep latest)
-          if (entry.type === 'event_msg' && entry.payload?.type === 'token_count' && entry.payload?.info) {
-            const info = entry.payload.info;
-            if (info.total_token_usage) {
-              tokenUsage = {
-                used: info.total_token_usage.total_tokens || 0,
-                total: info.model_context_window || 200000
-              };
-            }
-          }
-          
-          // Use event_msg.user_message for user-visible inputs.
-          if (entry.type === 'event_msg' && isVisibleCodexUserMessage(entry.payload)) {
-            messages.push({
-              type: 'user',
-              timestamp: entry.timestamp,
-              message: {
-                role: 'user',
-                content: entry.payload.message
-              }
-            });
-          }
-
-          // response_item.message may include internal prompts for non-assistant roles.
-          // Keep only assistant output from response_item.
-          if (
-            entry.type === 'response_item' &&
-            entry.payload?.type === 'message' &&
-            entry.payload.role === 'assistant'
-          ) {
-            const content = entry.payload.content;
-            const textContent = extractText(content);
-
-            // Only add if there's actual content
-            if (textContent?.trim()) {
-              messages.push({
-                type: 'assistant',
-                timestamp: entry.timestamp,
-                message: {
-                  role: 'assistant',
-                  content: textContent
-                }
-              });
-            }
-          }
-
-          if (entry.type === 'response_item' && entry.payload?.type === 'reasoning') {
-            const summaryText = entry.payload.summary
-              ?.map(s => s.text)
-              .filter(Boolean)
-              .join('\n');
-            if (summaryText?.trim()) {
-              messages.push({
-                type: 'thinking',
-                timestamp: entry.timestamp,
-                message: {
-                  role: 'assistant',
-                  content: summaryText
-                }
-              });
-            }
-          }
-
-          if (entry.type === 'response_item' && entry.payload?.type === 'function_call') {
-            let toolName = entry.payload.name;
-            let toolInput = entry.payload.arguments;
-
-            // Map Codex tool names to Claude equivalents
-            if (toolName === 'shell_command') {
-              toolName = 'Bash';
-              try {
-                const args = JSON.parse(entry.payload.arguments);
-                toolInput = JSON.stringify({ command: args.command });
-              } catch (e) {
-                // Keep original if parsing fails
-              }
-            }
-
-            messages.push({
-              type: 'tool_use',
-              timestamp: entry.timestamp,
-              toolName: toolName,
-              toolInput: toolInput,
-              toolCallId: entry.payload.call_id
-            });
-          }
-
-          if (entry.type === 'response_item' && entry.payload?.type === 'function_call_output') {
-            messages.push({
-              type: 'tool_result',
-              timestamp: entry.timestamp,
-              toolCallId: entry.payload.call_id,
-              output: entry.payload.output
-            });
-          }
-
-          if (entry.type === 'response_item' && entry.payload?.type === 'custom_tool_call') {
-            const toolName = entry.payload.name || 'custom_tool';
-            const input = entry.payload.input || '';
-
-            if (toolName === 'apply_patch') {
-              // Parse Codex patch format and convert to Claude Edit format
-              const fileMatch = input.match(/\*\*\* Update File: (.+)/);
-              const filePath = fileMatch ? fileMatch[1].trim() : 'unknown';
-
-              // Extract old and new content from patch
-              const lines = input.split('\n');
-              const oldLines = [];
-              const newLines = [];
-
-              for (const line of lines) {
-                if (line.startsWith('-') && !line.startsWith('---')) {
-                  oldLines.push(line.substring(1));
-                } else if (line.startsWith('+') && !line.startsWith('+++')) {
-                  newLines.push(line.substring(1));
-                }
-              }
-
-              messages.push({
-                type: 'tool_use',
-                timestamp: entry.timestamp,
-                toolName: 'Edit',
-                toolInput: JSON.stringify({
-                  file_path: filePath,
-                  old_string: oldLines.join('\n'),
-                  new_string: newLines.join('\n')
-                }),
-                toolCallId: entry.payload.call_id
-              });
-            } else {
-              messages.push({
-                type: 'tool_use',
-                timestamp: entry.timestamp,
-                toolName: toolName,
-                toolInput: input,
-                toolCallId: entry.payload.call_id
-              });
-            }
-          }
-
-          if (entry.type === 'response_item' && entry.payload?.type === 'custom_tool_call_output') {
-            messages.push({
-              type: 'tool_result',
-              timestamp: entry.timestamp,
-              toolCallId: entry.payload.call_id,
-              output: entry.payload.output || ''
-            });
-          }
-
-        } catch (parseError) {
-          // Skip malformed lines
-        }
-      }
-    }
-
-    // Sort by timestamp
-    messages.sort((a, b) => new Date(a.timestamp || 0) - new Date(b.timestamp || 0));
-
-    const total = messages.length;
-
-    // Apply pagination if limit is specified
-    if (limit !== null) {
-      const startIndex = Math.max(0, total - offset - limit);
-      const endIndex = total - offset;
-      const paginatedMessages = messages.slice(startIndex, endIndex);
-      const hasMore = startIndex > 0;
-
-      return {
-        messages: paginatedMessages,
-        total,
-        hasMore,
-        offset,
-        limit,
-        tokenUsage
-      };
-    }
-
-    return { messages, tokenUsage };
-
-  } catch (error) {
-    console.error(`Error reading Codex session messages for ${sessionId}:`, error);
-    return { messages: [], total: 0, hasMore: false };
-  }
-}
-
-async function deleteCodexSession(sessionId) {
-  try {
-    const codexSessionsDir = path.join(os.homedir(), '.codex', 'sessions');
-
-    const findJsonlFiles = async (dir) => {
-      const files = [];
-      try {
-        const entries = await fs.readdir(dir, { withFileTypes: true });
-        for (const entry of entries) {
-          const fullPath = path.join(dir, entry.name);
-          if (entry.isDirectory()) {
-            files.push(...await findJsonlFiles(fullPath));
-          } else if (entry.name.endsWith('.jsonl')) {
-            files.push(fullPath);
-          }
-        }
-      } catch (error) { }
-      return files;
-    };
-
-    const jsonlFiles = await findJsonlFiles(codexSessionsDir);
-
-    for (const filePath of jsonlFiles) {
-      const sessionData = await parseCodexSessionFile(filePath);
-      if (sessionData && sessionData.id === sessionId) {
-        await fs.unlink(filePath);
-        return true;
-      }
-    }
-
-    throw new Error(`Codex session file not found for session ${sessionId}`);
-  } catch (error) {
-    console.error(`Error deleting Codex session ${sessionId}:`, error);
-    throw error;
-  }
-}
-
-async function searchConversations(query, limit = 50, onProjectResult = null, signal = null) {
-  const safeQuery = typeof query === 'string' ? query.trim() : '';
-  const safeLimit = Math.max(1, Math.min(Number.isFinite(limit) ? limit : 50, 200));
-  const claudeDir = path.join(os.homedir(), '.claude', 'projects');
-  const config = await loadProjectConfig();
-  const results = [];
-  let totalMatches = 0;
-  const words = safeQuery.toLowerCase().split(/\s+/).filter(w => w.length > 0);
-  if (words.length === 0) return { results: [], totalMatches: 0, query: safeQuery };
-
-  const isAborted = () => signal?.aborted === true;
-
-  const isSystemMessage = (textContent) => {
-    return typeof textContent === 'string' && (
-      textContent.startsWith('<command-name>') ||
-      textContent.startsWith('<command-message>') ||
-      textContent.startsWith('<command-args>') ||
-      textContent.startsWith('<local-command-stdout>') ||
-      textContent.startsWith('<system-reminder>') ||
-      textContent.startsWith('Caveat:') ||
-      textContent.startsWith('This session is being continued from a previous') ||
-      textContent.startsWith('Invalid API key') ||
-      textContent.includes('{"subtasks":') ||
-      textContent.includes('CRITICAL: You MUST respond with ONLY a JSON') ||
-      textContent === 'Warmup'
-    );
-  };
-
-  const extractText = (content) => {
-    if (typeof content === 'string') return content;
-    if (Array.isArray(content)) {
-      return content
-        .filter(part => part.type === 'text' && part.text)
-        .map(part => part.text)
-        .join(' ');
-    }
-    return '';
-  };
-
-  const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const wordPatterns = words.map(w => new RegExp(`(?<!\\p{L})${escapeRegex(w)}(?!\\p{L})`, 'u'));
-  const allWordsMatch = (textLower) => {
-    return wordPatterns.every(p => p.test(textLower));
-  };
-
-  const buildSnippet = (text, textLower, snippetLen = 150) => {
-    let firstIndex = -1;
-    let firstWordLen = 0;
-    for (const w of words) {
-      const re = new RegExp(`(?<!\\p{L})${escapeRegex(w)}(?!\\p{L})`, 'u');
-      const m = re.exec(textLower);
-      if (m && (firstIndex === -1 || m.index < firstIndex)) {
-        firstIndex = m.index;
-        firstWordLen = w.length;
-      }
-    }
-    if (firstIndex === -1) firstIndex = 0;
-    const halfLen = Math.floor(snippetLen / 2);
-    let start = Math.max(0, firstIndex - halfLen);
-    let end = Math.min(text.length, firstIndex + halfLen + firstWordLen);
-    let snippet = text.slice(start, end).replace(/\n/g, ' ');
-    const prefix = start > 0 ? '...' : '';
-    const suffix = end < text.length ? '...' : '';
-    snippet = prefix + snippet + suffix;
-    const snippetLower = snippet.toLowerCase();
-    const highlights = [];
-    for (const word of words) {
-      const re = new RegExp(`(?<!\\p{L})${escapeRegex(word)}(?!\\p{L})`, 'gu');
-      let match;
-      while ((match = re.exec(snippetLower)) !== null) {
-        highlights.push({ start: match.index, end: match.index + word.length });
-      }
-    }
-    highlights.sort((a, b) => a.start - b.start);
-    const merged = [];
-    for (const h of highlights) {
-      const last = merged[merged.length - 1];
-      if (last && h.start <= last.end) {
-        last.end = Math.max(last.end, h.end);
-      } else {
-        merged.push({ ...h });
-      }
-    }
-    return { snippet, highlights: merged };
-  };
-
-  try {
-    await fs.access(claudeDir);
-    const entries = await fs.readdir(claudeDir, { withFileTypes: true });
-    const projectDirs = entries.filter(e => e.isDirectory());
-    let scannedProjects = 0;
-    const totalProjects = projectDirs.length;
-
-    for (const projectEntry of projectDirs) {
-      if (totalMatches >= safeLimit || isAborted()) break;
-
-      const projectName = projectEntry.name;
-      const projectDir = path.join(claudeDir, projectName);
-      const displayName = config[projectName]?.displayName
-        || await generateDisplayName(projectName);
-
-      let files;
-      try {
-        files = await fs.readdir(projectDir);
-      } catch {
-        continue;
-      }
-
-      const jsonlFiles = files.filter(
-        file => file.endsWith('.jsonl') && !file.startsWith('agent-')
-      );
-
-      const projectResult = {
-        projectName,
-        projectDisplayName: displayName,
-        sessions: []
-      };
-
-      for (const file of jsonlFiles) {
-        if (totalMatches >= safeLimit || isAborted()) break;
-
-        const filePath = path.join(projectDir, file);
-        const sessionMatches = new Map();
-        const sessionSummaries = new Map();
-        const pendingSummaries = new Map();
-        const sessionLastMessages = new Map();
-        let currentSessionId = null;
-
-        try {
-          const fileStream = fsSync.createReadStream(filePath);
-          const rl = readline.createInterface({
-            input: fileStream,
-            crlfDelay: Infinity
-          });
-
-          for await (const line of rl) {
-            if (totalMatches >= safeLimit || isAborted()) break;
-            if (!line.trim()) continue;
-
-            let entry;
-            try {
-              entry = JSON.parse(line);
-            } catch {
-              continue;
-            }
-
-            if (entry.sessionId) {
-              currentSessionId = entry.sessionId;
-            }
-            if (entry.type === 'summary' && entry.summary) {
-              const sid = entry.sessionId || currentSessionId;
-              if (sid) {
-                sessionSummaries.set(sid, entry.summary);
-              } else if (entry.leafUuid) {
-                pendingSummaries.set(entry.leafUuid, entry.summary);
-              }
-            }
-
-            // Apply pending summary via parentUuid
-            if (entry.parentUuid && currentSessionId && !sessionSummaries.has(currentSessionId)) {
-              const pending = pendingSummaries.get(entry.parentUuid);
-              if (pending) sessionSummaries.set(currentSessionId, pending);
-            }
-
-            // Track last user/assistant message for fallback title
-            if (entry.message?.content && currentSessionId && !entry.isApiErrorMessage) {
-              const role = entry.message.role;
-              if (role === 'user' || role === 'assistant') {
-                const text = extractText(entry.message.content);
-                if (text && !isSystemMessage(text)) {
-                  if (!sessionLastMessages.has(currentSessionId)) {
-                    sessionLastMessages.set(currentSessionId, {});
-                  }
-                  const msgs = sessionLastMessages.get(currentSessionId);
-                  if (role === 'user') msgs.user = text;
-                  else msgs.assistant = text;
-                }
-              }
-            }
-
-            if (!entry.message?.content) continue;
-            if (entry.message.role !== 'user' && entry.message.role !== 'assistant') continue;
-            if (entry.isApiErrorMessage) continue;
-
-            const text = extractText(entry.message.content);
-            if (!text || isSystemMessage(text)) continue;
-
-            const textLower = text.toLowerCase();
-            if (!allWordsMatch(textLower)) continue;
-
-            const sessionId = entry.sessionId || currentSessionId || file.replace('.jsonl', '');
-            if (!sessionMatches.has(sessionId)) {
-              sessionMatches.set(sessionId, []);
-            }
-
-            const matches = sessionMatches.get(sessionId);
-            if (matches.length < 2) {
-              const { snippet, highlights } = buildSnippet(text, textLower);
-              matches.push({
-                role: entry.message.role,
-                snippet,
-                highlights,
-                timestamp: entry.timestamp || null,
-                provider: 'claude',
-                messageUuid: entry.uuid || null
-              });
-              totalMatches++;
-            }
-          }
-        } catch {
-          continue;
-        }
-
-        for (const [sessionId, matches] of sessionMatches) {
-          projectResult.sessions.push({
-            sessionId,
-            provider: 'claude',
-            sessionSummary: sessionSummaries.get(sessionId) || (() => {
-              const msgs = sessionLastMessages.get(sessionId);
-              const lastMsg = msgs?.user || msgs?.assistant;
-              return lastMsg ? (lastMsg.length > 50 ? lastMsg.substring(0, 50) + '...' : lastMsg) : 'New Session';
-            })(),
-            matches
-          });
-        }
-      }
-
-      // Search Codex sessions for this project
-      try {
-        const actualProjectDir = await extractProjectDirectory(projectName);
-        if (actualProjectDir && !isAborted() && totalMatches < safeLimit) {
-          await searchCodexSessionsForProject(
-            actualProjectDir, projectResult, words, allWordsMatch, extractText, isSystemMessage,
-            buildSnippet, safeLimit, () => totalMatches, (n) => { totalMatches += n; }, isAborted
-          );
-        }
-      } catch {
-        // Skip codex search errors
-      }
-
-      // Search Gemini sessions for this project
-      try {
-        const actualProjectDir = await extractProjectDirectory(projectName);
-        if (actualProjectDir && !isAborted() && totalMatches < safeLimit) {
-          await searchGeminiSessionsForProject(
-            actualProjectDir, projectResult, words, allWordsMatch,
-            buildSnippet, safeLimit, () => totalMatches, (n) => { totalMatches += n; }
-          );
-        }
-      } catch {
-        // Skip gemini search errors
-      }
-
-      scannedProjects++;
-      if (projectResult.sessions.length > 0) {
-        results.push(projectResult);
-        if (onProjectResult) {
-          onProjectResult({ projectResult, totalMatches, scannedProjects, totalProjects });
-        }
-      } else if (onProjectResult && scannedProjects % 10 === 0) {
-        onProjectResult({ projectResult: null, totalMatches, scannedProjects, totalProjects });
-      }
-    }
-  } catch {
-    // claudeDir doesn't exist
-  }
-
-  return { results, totalMatches, query: safeQuery };
-}
-
-async function searchCodexSessionsForProject(
-  projectPath, projectResult, words, allWordsMatch, extractText, isSystemMessage,
-  buildSnippet, limit, getTotalMatches, addMatches, isAborted
-) {
-  const normalizedProjectPath = normalizeComparablePath(projectPath);
-  if (!normalizedProjectPath) return;
-  const codexSessionsDir = path.join(os.homedir(), '.codex', 'sessions');
-  try {
-    await fs.access(codexSessionsDir);
-  } catch {
-    return;
-  }
-
-  const jsonlFiles = await findCodexJsonlFiles(codexSessionsDir);
-
-  for (const filePath of jsonlFiles) {
-    if (getTotalMatches() >= limit || isAborted()) break;
-
-    try {
-      const fileStream = fsSync.createReadStream(filePath);
-      const rl = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
-
-      // First pass: read session_meta to check project path match
-      let sessionMeta = null;
-      for await (const line of rl) {
-        if (!line.trim()) continue;
-        try {
-          const entry = JSON.parse(line);
-          if (entry.type === 'session_meta' && entry.payload) {
-            sessionMeta = entry.payload;
-            break;
-          }
-        } catch { continue; }
-      }
-
-      // Skip sessions that don't belong to this project
-      if (!sessionMeta) continue;
-      const sessionProjectPath = normalizeComparablePath(sessionMeta.cwd);
-      if (sessionProjectPath !== normalizedProjectPath) continue;
-
-      // Second pass: re-read file to find matching messages
-      const fileStream2 = fsSync.createReadStream(filePath);
-      const rl2 = readline.createInterface({ input: fileStream2, crlfDelay: Infinity });
-      let lastUserMessage = null;
-      const matches = [];
-
-      for await (const line of rl2) {
-        if (getTotalMatches() >= limit || isAborted()) break;
-        if (!line.trim()) continue;
-
-        let entry;
-        try { entry = JSON.parse(line); } catch { continue; }
-
-        let text = null;
-        let role = null;
-
-        if (entry.type === 'event_msg' && entry.payload?.type === 'user_message' && entry.payload.message) {
-          text = entry.payload.message;
-          role = 'user';
-          lastUserMessage = text;
-        } else if (entry.type === 'response_item' && entry.payload?.type === 'message') {
-          const contentParts = entry.payload.content || [];
-          if (entry.payload.role === 'user') {
-            text = contentParts
-              .filter(p => p.type === 'input_text' && p.text)
-              .map(p => p.text)
-              .join(' ');
-            role = 'user';
-            if (text) lastUserMessage = text;
-          } else if (entry.payload.role === 'assistant') {
-            text = contentParts
-              .filter(p => p.type === 'output_text' && p.text)
-              .map(p => p.text)
-              .join(' ');
-            role = 'assistant';
-          }
-        }
-
-        if (!text || !role) continue;
-        const textLower = text.toLowerCase();
-        if (!allWordsMatch(textLower)) continue;
-
-        if (matches.length < 2) {
-          const { snippet, highlights } = buildSnippet(text, textLower);
-          matches.push({ role, snippet, highlights, timestamp: entry.timestamp || null, provider: 'codex' });
-          addMatches(1);
-        }
-      }
-
-      if (matches.length > 0) {
-        projectResult.sessions.push({
-          sessionId: sessionMeta.id,
-          provider: 'codex',
-          sessionSummary: lastUserMessage
-            ? (lastUserMessage.length > 50 ? lastUserMessage.substring(0, 50) + '...' : lastUserMessage)
-            : 'Codex Session',
-          matches
-        });
-      }
-    } catch {
-      continue;
-    }
-  }
-}
-
-async function searchGeminiSessionsForProject(
-  projectPath, projectResult, words, allWordsMatch,
-  buildSnippet, limit, getTotalMatches, addMatches
-) {
-  // 1) Search in-memory sessions (created via UI)
-  for (const [sessionId, session] of sessionManager.sessions) {
-    if (getTotalMatches() >= limit) break;
-    if (session.projectPath !== projectPath) continue;
-
-    const matches = [];
-    for (const msg of session.messages) {
-      if (getTotalMatches() >= limit) break;
-      if (msg.role !== 'user' && msg.role !== 'assistant') continue;
-
-      const text = typeof msg.content === 'string' ? msg.content
-        : Array.isArray(msg.content) ? msg.content.filter(p => p.type === 'text').map(p => p.text).join(' ')
-        : '';
-      if (!text) continue;
-
-      const textLower = text.toLowerCase();
-      if (!allWordsMatch(textLower)) continue;
-
-      if (matches.length < 2) {
-        const { snippet, highlights } = buildSnippet(text, textLower);
-        matches.push({
-          role: msg.role, snippet, highlights,
-          timestamp: msg.timestamp ? msg.timestamp.toISOString() : null,
-          provider: 'gemini'
-        });
-        addMatches(1);
-      }
-    }
-
-    if (matches.length > 0) {
-      const firstUserMsg = session.messages.find(m => m.role === 'user');
-      const summary = firstUserMsg?.content
-        ? (typeof firstUserMsg.content === 'string'
-          ? (firstUserMsg.content.length > 50 ? firstUserMsg.content.substring(0, 50) + '...' : firstUserMsg.content)
-          : 'Gemini Session')
-        : 'Gemini Session';
-
-      projectResult.sessions.push({
-        sessionId,
-        provider: 'gemini',
-        sessionSummary: summary,
-        matches
-      });
-    }
-  }
-
-  // 2) Search Gemini CLI sessions on disk (~/.gemini/tmp/<project>/chats/*.json)
-  const normalizedProjectPath = normalizeComparablePath(projectPath);
-  if (!normalizedProjectPath) return;
-
-  const geminiTmpDir = path.join(os.homedir(), '.gemini', 'tmp');
-  try {
-    await fs.access(geminiTmpDir);
-  } catch {
-    return;
-  }
-
-  const trackedSessionIds = new Set();
-  for (const [sid] of sessionManager.sessions) {
-    trackedSessionIds.add(sid);
-  }
-
-  let projectDirs;
-  try {
-    projectDirs = await fs.readdir(geminiTmpDir);
-  } catch {
-    return;
-  }
-
-  for (const projectDir of projectDirs) {
-    if (getTotalMatches() >= limit) break;
-
-    const projectRootFile = path.join(geminiTmpDir, projectDir, '.project_root');
-    let projectRoot;
-    try {
-      projectRoot = (await fs.readFile(projectRootFile, 'utf8')).trim();
-    } catch {
-      continue;
-    }
-
-    if (normalizeComparablePath(projectRoot) !== normalizedProjectPath) continue;
-
-    const chatsDir = path.join(geminiTmpDir, projectDir, 'chats');
-    let chatFiles;
-    try {
-      chatFiles = await fs.readdir(chatsDir);
-    } catch {
-      continue;
-    }
-
-    for (const chatFile of chatFiles) {
-      if (getTotalMatches() >= limit) break;
-      if (!chatFile.endsWith('.json')) continue;
-
-      try {
-        const filePath = path.join(chatsDir, chatFile);
-        const data = await fs.readFile(filePath, 'utf8');
-        const session = JSON.parse(data);
-        if (!session.messages || !Array.isArray(session.messages)) continue;
-
-        const cliSessionId = session.sessionId || chatFile.replace('.json', '');
-        if (trackedSessionIds.has(cliSessionId)) continue;
-
-        const matches = [];
-        let firstUserText = null;
-
-        for (const msg of session.messages) {
-          if (getTotalMatches() >= limit) break;
-
-          const role = msg.type === 'user' ? 'user'
-            : (msg.type === 'gemini' || msg.type === 'assistant') ? 'assistant'
-            : null;
-          if (!role) continue;
-
-          let text = '';
-          if (typeof msg.content === 'string') {
-            text = msg.content;
-          } else if (Array.isArray(msg.content)) {
-            text = msg.content
-              .filter(p => p.text)
-              .map(p => p.text)
-              .join(' ');
-          }
-          if (!text) continue;
-
-          if (role === 'user' && !firstUserText) firstUserText = text;
-
-          const textLower = text.toLowerCase();
-          if (!allWordsMatch(textLower)) continue;
-
-          if (matches.length < 2) {
-            const { snippet, highlights } = buildSnippet(text, textLower);
-            matches.push({
-              role, snippet, highlights,
-              timestamp: msg.timestamp || null,
-              provider: 'gemini'
-            });
-            addMatches(1);
-          }
-        }
-
-        if (matches.length > 0) {
-          const summary = firstUserText
-            ? (firstUserText.length > 50 ? firstUserText.substring(0, 50) + '...' : firstUserText)
-            : 'Gemini CLI Session';
-
-          projectResult.sessions.push({
-            sessionId: cliSessionId,
-            provider: 'gemini',
-            sessionSummary: summary,
-            matches
-          });
-        }
-      } catch {
-        continue;
-      }
-    }
-  }
-}
-
-async function getGeminiCliSessions(projectPath) {
-  const normalizedProjectPath = normalizeComparablePath(projectPath);
-  if (!normalizedProjectPath) return [];
-
-  const geminiTmpDir = path.join(os.homedir(), '.gemini', 'tmp');
-  try {
-    await fs.access(geminiTmpDir);
-  } catch {
-    return [];
-  }
-
-  const sessions = [];
-  let projectDirs;
-  try {
-    projectDirs = await fs.readdir(geminiTmpDir);
-  } catch {
-    return [];
-  }
-
-  for (const projectDir of projectDirs) {
-    const projectRootFile = path.join(geminiTmpDir, projectDir, '.project_root');
-    let projectRoot;
-    try {
-      projectRoot = (await fs.readFile(projectRootFile, 'utf8')).trim();
-    } catch {
-      continue;
-    }
-
-    if (normalizeComparablePath(projectRoot) !== normalizedProjectPath) continue;
-
-    const chatsDir = path.join(geminiTmpDir, projectDir, 'chats');
-    let chatFiles;
-    try {
-      chatFiles = await fs.readdir(chatsDir);
-    } catch {
-      continue;
-    }
-
-    for (const chatFile of chatFiles) {
-      if (!chatFile.endsWith('.json')) continue;
-      try {
-        const filePath = path.join(chatsDir, chatFile);
-        const data = await fs.readFile(filePath, 'utf8');
-        const session = JSON.parse(data);
-        if (!session.messages || !Array.isArray(session.messages)) continue;
-
-        const sessionId = session.sessionId || chatFile.replace('.json', '');
-        const firstUserMsg = session.messages.find(m => m.type === 'user');
-        let summary = 'Gemini CLI Session';
-        if (firstUserMsg) {
-          const text = Array.isArray(firstUserMsg.content)
-            ? firstUserMsg.content.filter(p => p.text).map(p => p.text).join(' ')
-            : (typeof firstUserMsg.content === 'string' ? firstUserMsg.content : '');
-          if (text) {
-            summary = text.length > 50 ? text.substring(0, 50) + '...' : text;
-          }
-        }
-
-        sessions.push({
-          id: sessionId,
-          summary,
-          messageCount: session.messages.length,
-          lastActivity: session.lastUpdated || session.startTime || null,
-          provider: 'gemini'
-        });
-      } catch {
-        continue;
-      }
-    }
-  }
-
-  return sessions.sort((a, b) =>
-    new Date(b.lastActivity || 0) - new Date(a.lastActivity || 0)
-  );
-}
-
-async function getGeminiCliSessionMessages(sessionId) {
-  const geminiTmpDir = path.join(os.homedir(), '.gemini', 'tmp');
-  let projectDirs;
-  try {
-    projectDirs = await fs.readdir(geminiTmpDir);
-  } catch {
-    return [];
-  }
-
-  for (const projectDir of projectDirs) {
-    const chatsDir = path.join(geminiTmpDir, projectDir, 'chats');
-    let chatFiles;
-    try {
-      chatFiles = await fs.readdir(chatsDir);
-    } catch {
-      continue;
-    }
-
-    for (const chatFile of chatFiles) {
-      if (!chatFile.endsWith('.json')) continue;
-      try {
-        const filePath = path.join(chatsDir, chatFile);
-        const data = await fs.readFile(filePath, 'utf8');
-        const session = JSON.parse(data);
-        const fileSessionId = session.sessionId || chatFile.replace('.json', '');
-        if (fileSessionId !== sessionId) continue;
-
-        return (session.messages || []).map(msg => {
-          const role = msg.type === 'user' ? 'user'
-            : (msg.type === 'gemini' || msg.type === 'assistant') ? 'assistant'
-            : msg.type;
-
-          let content = '';
-          if (typeof msg.content === 'string') {
-            content = msg.content;
-          } else if (Array.isArray(msg.content)) {
-            content = msg.content.filter(p => p.text).map(p => p.text).join('\n');
-          }
-
-          return {
-            type: 'message',
-            message: { role, content },
-            timestamp: msg.timestamp || null
-          };
-        });
-      } catch {
-        continue;
-      }
-    }
-  }
-
-  return [];
-}
-
-export {
-  getProjects,
-  getSessions,
-  getSessionMessages,
-  parseJsonlSessions,
-  renameProject,
-  deleteSession,
-  isProjectEmpty,
-  deleteProject,
-  addProjectManually,
-  loadProjectConfig,
-  saveProjectConfig,
-  extractProjectDirectory,
-  clearProjectDirectoryCache,
-  getCodexSessions,
-  getCodexSessionMessages,
-  deleteCodexSession,
-  getGeminiCliSessions,
-  getGeminiCliSessionMessages,
-  searchConversations
-};
diff --git a/server/routes/agent.js b/server/routes/agent.js
index cdcd3a65..a5607588 100644
--- a/server/routes/agent.js
+++ b/server/routes/agent.js
@@ -4,15 +4,16 @@ import path from 'path';
 import os from 'os';
 import { promises as fs } from 'fs';
 import crypto from 'crypto';
-import { userDb, apiKeysDb, githubTokensDb } from '../database/db.js';
-import { addProjectManually } from '../projects.js';
+import { userDb, apiKeysDb, githubTokensDb, projectsDb } from '../modules/database/index.js';
 import { queryClaudeSDK } from '../claude-sdk.js';
 import { spawnCursor } from '../cursor-cli.js';
 import { queryCodex } from '../openai-codex.js';
 import { spawnGemini } from '../gemini-cli.js';
+import { spawnOpenCode } from '../opencode-cli.js';
 import { Octokit } from '@octokit/rest';
-import { CLAUDE_MODELS, CURSOR_MODELS, CODEX_MODELS } from '../../shared/modelConstants.js';
+import { providerModelsService } from '../modules/providers/services/provider-models.service.js';
 import { IS_PLATFORM } from '../constants/config.js';
+import { normalizeProjectPath } from '../shared/utils.js';
 
 const router = express.Router();
 
@@ -608,7 +609,7 @@ class ResponseCollector {
 /**
  * POST /api/agent
  *
- * Trigger an AI agent (Claude or Cursor) to work on a project.
+ * Trigger an AI agent to work on a project.
  * Supports automatic GitHub branch and pull request creation after successful completion.
  *
  * ================================================================================================
@@ -633,7 +634,7 @@ class ResponseCollector {
  *                          - Source for auto-generated branch names (if createBranch=true and no branchName)
  *                          - Fallback for PR title if no commits are made
  *
- * @param {string} provider - (Optional) AI provider to use. Options: 'claude' | 'cursor' | 'codex' | 'gemini'
+ * @param {string} provider - (Optional) AI provider to use. Options: 'claude' | 'cursor' | 'codex' | 'gemini' | 'opencode'
  *                           Default: 'claude'
  *
  * @param {boolean} stream - (Optional) Enable Server-Sent Events (SSE) streaming for real-time updates.
@@ -751,7 +752,7 @@ class ResponseCollector {
  * Input Validations (400 Bad Request):
  *   - Either githubUrl OR projectPath must be provided (not neither)
  *   - message must be non-empty string
- *   - provider must be 'claude', 'cursor', 'codex', or 'gemini'
+ *   - provider must be 'claude', 'cursor', 'codex', 'gemini', or 'opencode'
  *   - createBranch/createPR requires githubUrl OR projectPath (not neither)
  *   - branchName must pass Git naming rules (if provided)
  *
@@ -859,8 +860,8 @@ router.post('/', validateExternalApiKey, async (req, res) => {
     return res.status(400).json({ error: 'message is required' });
   }
 
-  if (!['claude', 'cursor', 'codex', 'gemini'].includes(provider)) {
-    return res.status(400).json({ error: 'provider must be "claude", "cursor", "codex", or "gemini"' });
+  if (!['claude', 'cursor', 'codex', 'gemini', 'opencode'].includes(provider)) {
+    return res.status(400).json({ error: 'provider must be "claude", "cursor", "codex", "gemini", or "opencode"' });
   }
 
   // Validate GitHub branch/PR creation requirements
@@ -890,7 +891,7 @@ router.post('/', validateExternalApiKey, async (req, res) => {
       finalProjectPath = await cloneGitHubRepo(githubUrl.trim(), tokenToUse, targetPath);
     } else {
       // Use existing project path
-      finalProjectPath = path.resolve(projectPath);
+      finalProjectPath = normalizeProjectPath(path.resolve(projectPath));
 
       // Verify the path exists
       try {
@@ -900,19 +901,14 @@ router.post('/', validateExternalApiKey, async (req, res) => {
       }
     }
 
-    // Register the project (or use existing registration)
-    let project;
-    try {
-      project = await addProjectManually(finalProjectPath);
-      console.log('📦 Project registered:', project);
-    } catch (error) {
-      // If project already exists, that's fine - continue with the existing registration
-      if (error.message && error.message.includes('Project already configured')) {
-        console.log('📦 Using existing project registration for:', finalProjectPath);
-        project = { path: finalProjectPath };
-      } else {
-        throw error;
-      }
+    finalProjectPath = normalizeProjectPath(finalProjectPath);
+
+    // Register project path in DB (or reuse existing active registration)
+    const registrationResult = projectsDb.createProjectPath(finalProjectPath, null);
+    if (registrationResult.outcome === 'active_conflict') {
+      console.log('Project registration already exists for:', finalProjectPath);
+    } else {
+      console.log('Project registered:', registrationResult.project);
     }
 
     // Set up writer based on streaming mode
@@ -943,6 +939,10 @@ router.post('/', validateExternalApiKey, async (req, res) => {
       });
     }
 
+    const codexModels = (await providerModelsService.getProviderModels('codex')).models;
+    const geminiModels = (await providerModelsService.getProviderModels('gemini')).models;
+    const opencodeModels = (await providerModelsService.getProviderModels('opencode')).models;
+
     // Start the appropriate session
     if (provider === 'claude') {
       console.log('🤖 Starting Claude SDK session');
@@ -972,7 +972,7 @@ router.post('/', validateExternalApiKey, async (req, res) => {
         projectPath: finalProjectPath,
         cwd: finalProjectPath,
         sessionId: sessionId || null,
-        model: model || CODEX_MODELS.DEFAULT,
+        model: model || codexModels.DEFAULT,
         permissionMode: 'bypassPermissions'
       }, writer);
     } else if (provider === 'gemini') {
@@ -982,9 +982,18 @@ router.post('/', validateExternalApiKey, async (req, res) => {
         projectPath: finalProjectPath,
         cwd: finalProjectPath,
         sessionId: sessionId || null,
-        model: model,
+        model: model || geminiModels.DEFAULT,
         skipPermissions: true // CLI mode bypasses permissions
       }, writer);
+    } else if (provider === 'opencode') {
+      console.log('Starting OpenCode CLI session');
+
+      await spawnOpenCode(message.trim(), {
+        projectPath: finalProjectPath,
+        cwd: finalProjectPath,
+        sessionId: sessionId || null,
+        model: model || opencodeModels.DEFAULT
+      }, writer);
     }
 
     // Handle GitHub branch and PR creation after successful agent completion
diff --git a/server/routes/auth.js b/server/routes/auth.js
index be4c38c1..dcb2e3ff 100644
--- a/server/routes/auth.js
+++ b/server/routes/auth.js
@@ -1,9 +1,11 @@
 import express from 'express';
 import bcrypt from 'bcrypt';
-import { userDb, db } from '../database/db.js';
+import { userDb } from '../modules/database/index.js';
+import { getConnection } from '../modules/database/connection.js';
 import { generateToken, authenticateToken } from '../middleware/auth.js';
 
 const router = express.Router();
+const db = getConnection();
 
 // Check auth status and setup requirements
 router.get('/status', async (req, res) => {
@@ -132,4 +134,4 @@ router.post('/logout', authenticateToken, (req, res) => {
   res.json({ success: true, message: 'Logged out successfully' });
 });
 
-export default router;
\ No newline at end of file
+export default router;
diff --git a/server/routes/codex.js b/server/routes/codex.js
deleted file mode 100644
index 06630414..00000000
--- a/server/routes/codex.js
+++ /dev/null
@@ -1,19 +0,0 @@
-import express from 'express';
-import { deleteCodexSession } from '../projects.js';
-import { sessionNamesDb } from '../database/db.js';
-
-const router = express.Router();
-
-router.delete('/sessions/:sessionId', async (req, res) => {
-  try {
-    const { sessionId } = req.params;
-    await deleteCodexSession(sessionId);
-    sessionNamesDb.deleteName(sessionId, 'codex');
-    res.json({ success: true });
-  } catch (error) {
-    console.error(`Error deleting Codex session ${req.params.sessionId}:`, error);
-    res.status(500).json({ success: false, error: error.message });
-  }
-});
-
-export default router;
diff --git a/server/routes/commands.js b/server/routes/commands.js
index 4b791564..09022e0c 100644
--- a/server/routes/commands.js
+++ b/server/routes/commands.js
@@ -1,10 +1,12 @@
-import express from 'express';
-import { promises as fs } from 'fs';
-import path from 'path';
-import os from 'os';
-import { CLAUDE_MODELS, CURSOR_MODELS, CODEX_MODELS } from '../../shared/modelConstants.js';
-import { parseFrontmatter } from '../utils/frontmatter.js';
-import { findAppRoot, getModuleDir } from '../utils/runtime-paths.js';
+import { promises as fs } from "fs";
+import os from "os";
+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
@@ -13,6 +15,77 @@ const APP_ROOT = findAppRoot(__dirname);
 
 const router = express.Router();
 
+const MODEL_PROVIDERS = ["claude", "cursor", "codex", "gemini", "opencode"];
+
+const MODEL_PROVIDER_LABELS = {
+  claude: "Claude",
+  cursor: "Cursor",
+  codex: "Codex",
+  gemini: "Gemini",
+  opencode: "OpenCode",
+};
+
+const readModelProvider = (value) => {
+  if (typeof value !== "string") {
+    return "claude";
+  }
+
+  const normalized = value.trim().toLowerCase();
+  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;
+};
+
+export const executeModelsCommand = async (args, context) => {
+  const currentProvider = readModelProvider(context?.provider);
+  const result = await providerModelsService.getProviderModels(currentProvider);
+  const catalog = result.models;
+  const currentModel = await resolveCommandModel(
+    currentProvider,
+    catalog,
+    context?.sessionId,
+  );
+  const availableModels = catalog.OPTIONS.map((option) => option.value);
+  const availableOptions = catalog.OPTIONS.map((option) => ({
+    value: option.value,
+    label: option.label,
+    description: option.description,
+  }));
+
+  return {
+    type: "builtin",
+    action: "models",
+    data: {
+      current: {
+        provider: currentProvider,
+        providerLabel: MODEL_PROVIDER_LABELS[currentProvider],
+        model: currentModel,
+      },
+      available: {
+        [currentProvider]: availableModels,
+      },
+      availableModels,
+      availableOptions,
+      defaultModel: catalog.DEFAULT,
+      cache: result.cache,
+      message: `Current model: ${currentModel}`,
+    },
+  };
+};
+
 /**
  * Recursively scan directory for command files (.md)
  * @param {string} dir - Directory to scan
@@ -34,24 +107,30 @@ async function scanCommandsDirectory(dir, baseDir, namespace) {
 
       if (entry.isDirectory()) {
         // Recursively scan subdirectories
-        const subCommands = await scanCommandsDirectory(fullPath, baseDir, namespace);
+        const subCommands = await scanCommandsDirectory(
+          fullPath,
+          baseDir,
+          namespace,
+        );
         commands.push(...subCommands);
-      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      } else if (entry.isFile() && entry.name.endsWith(".md")) {
         // Parse markdown file for metadata
         try {
-          const content = await fs.readFile(fullPath, 'utf8');
-          const { data: frontmatter, content: commandContent } = parseFrontmatter(content);
+          const content = await fs.readFile(fullPath, "utf8");
+          const { data: frontmatter, content: commandContent } =
+            parseFrontMatter(content);
 
           // Calculate relative path from baseDir for command name
           const relativePath = path.relative(baseDir, fullPath);
           // Remove .md extension and convert to command name
-          const commandName = '/' + relativePath.replace(/\.md$/, '').replace(/\\/g, '/');
+          const commandName =
+            "/" + relativePath.replace(/\.md$/, "").replace(/\\/g, "/");
 
           // Extract description from frontmatter or first line of content
-          let description = frontmatter.description || '';
+          let description = frontmatter.description || "";
           if (!description) {
-            const firstLine = commandContent.trim().split('\n')[0];
-            description = firstLine.replace(/^#+\s*/, '').trim();
+            const firstLine = commandContent.trim().split("\n")[0];
+            description = firstLine.replace(/^#+\s*/, "").trim();
           }
 
           commands.push({
@@ -60,7 +139,7 @@ async function scanCommandsDirectory(dir, baseDir, namespace) {
             relativePath,
             description,
             namespace,
-            metadata: frontmatter
+            metadata: frontmatter,
           });
         } catch (err) {
           console.error(`Error parsing command file ${fullPath}:`, err.message);
@@ -69,7 +148,7 @@ async function scanCommandsDirectory(dir, baseDir, namespace) {
     }
   } catch (err) {
     // Directory doesn't exist or can't be accessed - this is okay
-    if (err.code !== 'ENOENT' && err.code !== 'EACCES') {
+    if (err.code !== "ENOENT" && err.code !== "EACCES") {
       console.error(`Error scanning directory ${dir}:`, err.message);
     }
   }
@@ -82,53 +161,41 @@ async function scanCommandsDirectory(dir, baseDir, namespace) {
  */
 const builtInCommands = [
   {
-    name: '/help',
-    description: 'Show help documentation for Claude Code',
-    namespace: 'builtin',
-    metadata: { type: 'builtin' }
+    name: "/help",
+    description: "Show help documentation for Claude Code",
+    namespace: "builtin",
+    metadata: { type: "builtin" },
   },
   {
-    name: '/clear',
-    description: 'Clear the conversation history',
-    namespace: 'builtin',
-    metadata: { type: 'builtin' }
+    name: "/models",
+    description: "View available models for the current provider",
+    namespace: "builtin",
+    metadata: { type: "builtin" },
   },
   {
-    name: '/model',
-    description: 'Switch or view the current AI model',
-    namespace: 'builtin',
-    metadata: { type: 'builtin' }
+    name: "/cost",
+    description: "Display token usage information",
+    namespace: "builtin",
+    metadata: { type: "builtin" },
   },
   {
-    name: '/cost',
-    description: 'Display token usage and cost information',
-    namespace: 'builtin',
-    metadata: { type: 'builtin' }
+    name: "/memory",
+    description: "Open CLAUDE.md memory file for editing",
+    namespace: "builtin",
+    metadata: { type: "builtin" },
   },
   {
-    name: '/memory',
-    description: 'Open CLAUDE.md memory file for editing',
-    namespace: 'builtin',
-    metadata: { type: 'builtin' }
+    name: "/config",
+    description: "Open settings and configuration",
+    namespace: "builtin",
+    metadata: { type: "builtin" },
   },
   {
-    name: '/config',
-    description: 'Open settings and configuration',
-    namespace: 'builtin',
-    metadata: { type: 'builtin' }
+    name: "/status",
+    description: "Show system status and version information",
+    namespace: "builtin",
+    metadata: { type: "builtin" },
   },
-  {
-    name: '/status',
-    description: 'Show system status and version information',
-    namespace: 'builtin',
-    metadata: { type: 'builtin' }
-  },
-  {
-    name: '/rewind',
-    description: 'Rewind the conversation to a previous state',
-    namespace: 'builtin',
-    metadata: { type: 'builtin' }
-  }
 ];
 
 /**
@@ -136,14 +203,18 @@ const builtInCommands = [
  * Each handler returns { type: 'builtin', action: string, data: any }
  */
 const builtInHandlers = {
-  '/help': async (args, context) => {
+  "/help": async (args, context) => {
     const helpText = `# Claude Code Commands
 
 ## Built-in Commands
 
-${builtInCommands.map(cmd => `### ${cmd.name}
+${builtInCommands
+  .map(
+    (cmd) => `### ${cmd.name}
 ${cmd.description}
-`).join('\n')}
+`,
+  )
+  .join("\n")}
 
 ## Custom Commands
 
@@ -165,77 +236,45 @@ Custom commands can be created in:
 `;
 
     return {
-      type: 'builtin',
-      action: 'help',
+      type: "builtin",
+      action: "help",
       data: {
         content: helpText,
-        format: 'markdown'
-      }
+        format: "markdown",
+        commands: builtInCommands.map((command) => ({
+          name: command.name,
+          description: command.description,
+          namespace: command.namespace,
+        })),
+      },
     };
   },
 
-  '/clear': async (args, context) => {
-    return {
-      type: 'builtin',
-      action: 'clear',
-      data: {
-        message: 'Conversation history cleared'
-      }
-    };
-  },
+  "/models": executeModelsCommand,
 
-  '/model': async (args, context) => {
-    // Read available models from centralized constants
-    const availableModels = {
-      claude: CLAUDE_MODELS.OPTIONS.map(o => o.value),
-      cursor: CURSOR_MODELS.OPTIONS.map(o => o.value),
-      codex: CODEX_MODELS.OPTIONS.map(o => o.value)
-    };
-
-    const currentProvider = context?.provider || 'claude';
-    const currentModel = context?.model || CLAUDE_MODELS.DEFAULT;
-
-    return {
-      type: 'builtin',
-      action: 'model',
-      data: {
-        current: {
-          provider: currentProvider,
-          model: currentModel
-        },
-        available: availableModels,
-        message: args.length > 0
-          ? `Switching to model: ${args[0]}`
-          : `Current model: ${currentModel}`
-      }
-    };
-  },
-
-  '/cost': async (args, context) => {
+  "/cost": async (args, context) => {
     const tokenUsage = context?.tokenUsage || {};
-    const provider = context?.provider || 'claude';
-    const model =
-      context?.model ||
-      (provider === 'cursor'
-        ? CURSOR_MODELS.DEFAULT
-        : provider === 'codex'
-          ? CODEX_MODELS.DEFAULT
-          : CLAUDE_MODELS.DEFAULT);
+    const provider = readModelProvider(context?.provider);
+    const catalog = (await providerModelsService.getProviderModels(provider)).models;
+    const model = await resolveCommandModel(provider, catalog, context?.sessionId);
 
-    const used = Number(tokenUsage.used ?? tokenUsage.totalUsed ?? tokenUsage.total_tokens ?? 0) || 0;
+    const reportedUsed =
+      Number(
+        tokenUsage.used ?? tokenUsage.totalUsed ?? tokenUsage.total_tokens ?? 0,
+      ) || 0;
     const total =
       Number(
         tokenUsage.total ??
           tokenUsage.contextWindow ??
-          parseInt(process.env.CONTEXT_WINDOW || '160000', 10),
-      ) || 160000;
-    const percentage = total > 0 ? Number(((used / total) * 100).toFixed(1)) : 0;
-
+          0,
+      ) || 0;
     const inputTokensRaw =
       Number(
         tokenUsage.inputTokens ??
           tokenUsage.input ??
+          tokenUsage.input_tokens ??
           tokenUsage.cumulativeInputTokens ??
+          tokenUsage.breakdown?.input ??
           tokenUsage.promptTokens ??
           0,
       ) || 0;
@@ -243,106 +282,103 @@ Custom commands can be created in:
       Number(
         tokenUsage.outputTokens ??
           tokenUsage.output ??
+          tokenUsage.output_tokens ??
           tokenUsage.cumulativeOutputTokens ??
+          tokenUsage.breakdown?.output ??
           tokenUsage.completionTokens ??
           0,
       ) || 0;
-    const cacheTokens =
-      Number(
-        tokenUsage.cacheReadTokens ??
-          tokenUsage.cacheCreationTokens ??
-          tokenUsage.cacheTokens ??
-          tokenUsage.cachedTokens ??
-          0,
-      ) || 0;
-
-    // If we only have total used tokens, treat them as input for display/estimation.
-    const inputTokens =
-      inputTokensRaw > 0 || outputTokens > 0 || cacheTokens > 0 ? inputTokensRaw + cacheTokens : used;
-
-    // Rough default rates by provider (USD / 1M tokens).
-    const pricingByProvider = {
-      claude: { input: 3, output: 15 },
-      cursor: { input: 3, output: 15 },
-      codex: { input: 1.5, output: 6 },
-    };
-    const rates = pricingByProvider[provider] || pricingByProvider.claude;
-
-    const inputCost = (inputTokens / 1_000_000) * rates.input;
-    const outputCost = (outputTokens / 1_000_000) * rates.output;
-    const totalCost = inputCost + outputCost;
+    const hasTokenBreakdown = inputTokensRaw > 0 || outputTokens > 0;
+    const used = reportedUsed || inputTokensRaw + outputTokens;
 
     return {
-      type: 'builtin',
-      action: 'cost',
+      type: "builtin",
+      action: "cost",
       data: {
         tokenUsage: {
           used,
           total,
-          percentage,
-        },
-        cost: {
-          input: inputCost.toFixed(4),
-          output: outputCost.toFixed(4),
-          total: totalCost.toFixed(4),
         },
+        ...(hasTokenBreakdown
+          ? {
+              tokenBreakdown: {
+                input: inputTokensRaw,
+                output: outputTokens,
+              },
+            }
+          : {}),
+        provider,
         model,
       },
     };
   },
 
-  '/status': async (args, context) => {
+  "/status": async (args, context) => {
     // Read version from package.json
-    const packageJsonPath = path.join(APP_ROOT, 'package.json');
-    let version = 'unknown';
-    let packageName = 'claude-code-ui';
+    const packageJsonPath = path.join(APP_ROOT, "package.json");
+    let version = "unknown";
+    let packageName = "claude-code-ui";
 
     try {
-      const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+      const packageJson = JSON.parse(
+        await fs.readFile(packageJsonPath, "utf8"),
+      );
       version = packageJson.version;
       packageName = packageJson.name;
     } catch (err) {
-      console.error('Error reading package.json:', err);
+      console.error("Error reading package.json:", err);
     }
 
     const uptime = process.uptime();
     const uptimeMinutes = Math.floor(uptime / 60);
     const uptimeHours = Math.floor(uptimeMinutes / 60);
-    const uptimeFormatted = uptimeHours > 0
-      ? `${uptimeHours}h ${uptimeMinutes % 60}m`
-      : `${uptimeMinutes}m`;
+    const uptimeFormatted =
+      uptimeHours > 0
+        ? `${uptimeHours}h ${uptimeMinutes % 60}m`
+        : `${uptimeMinutes}m`;
+
+    const statusProvider = readModelProvider(context?.provider);
+    const statusCatalog = (await providerModelsService.getProviderModels(statusProvider)).models;
+    const model = await resolveCommandModel(statusProvider, statusCatalog, context?.sessionId);
+    const memoryUsage = process.memoryUsage();
 
     return {
-      type: 'builtin',
-      action: 'status',
+      type: "builtin",
+      action: "status",
       data: {
         version,
         packageName,
         uptime: uptimeFormatted,
         uptimeSeconds: Math.floor(uptime),
-        model: context?.model || 'claude-sonnet-4.5',
-        provider: context?.provider || 'claude',
+        model,
+        provider: statusProvider,
         nodeVersion: process.version,
-        platform: process.platform
-      }
+        platform: process.platform,
+        pid: process.pid,
+        memoryUsage: {
+          rssMb: Math.round(memoryUsage.rss / 1024 / 1024),
+          heapUsedMb: Math.round(memoryUsage.heapUsed / 1024 / 1024),
+          heapTotalMb: Math.round(memoryUsage.heapTotal / 1024 / 1024),
+        },
+      },
     };
   },
 
-  '/memory': async (args, context) => {
+  "/memory": async (args, context) => {
     const projectPath = context?.projectPath;
 
     if (!projectPath) {
       return {
-        type: 'builtin',
-        action: 'memory',
+        type: "builtin",
+        action: "memory",
         data: {
-          error: 'No project selected',
-          message: 'Please select a project to access its CLAUDE.md file'
-        }
+          error: "No project selected",
+          message: "Please select a project to access its CLAUDE.md file",
+        },
       };
     }
 
-    const claudeMdPath = path.join(projectPath, 'CLAUDE.md');
+    const claudeMdPath = path.join(projectPath, "CLAUDE.md");
 
     // Check if CLAUDE.md exists
     let exists = false;
@@ -354,85 +390,63 @@ Custom commands can be created in:
     }
 
     return {
-      type: 'builtin',
-      action: 'memory',
+      type: "builtin",
+      action: "memory",
       data: {
         path: claudeMdPath,
         exists,
         message: exists
           ? `Opening CLAUDE.md at ${claudeMdPath}`
-          : `CLAUDE.md not found at ${claudeMdPath}. Create it to store project-specific instructions.`
-      }
+          : `CLAUDE.md not found at ${claudeMdPath}. Create it to store project-specific instructions.`,
+      },
     };
   },
 
-  '/config': async (args, context) => {
+  "/config": async (args, context) => {
     return {
-      type: 'builtin',
-      action: 'config',
+      type: "builtin",
+      action: "config",
       data: {
-        message: 'Opening settings...'
-      }
+        message: "Opening settings...",
+      },
     };
   },
-
-  '/rewind': async (args, context) => {
-    const steps = args[0] ? parseInt(args[0]) : 1;
-
-    if (isNaN(steps) || steps < 1) {
-      return {
-        type: 'builtin',
-        action: 'rewind',
-        data: {
-          error: 'Invalid steps parameter',
-          message: 'Usage: /rewind [number] - Rewind conversation by N steps (default: 1)'
-        }
-      };
-    }
-
-    return {
-      type: 'builtin',
-      action: 'rewind',
-      data: {
-        steps,
-        message: `Rewinding conversation by ${steps} step${steps > 1 ? 's' : ''}...`
-      }
-    };
-  }
 };
 
 /**
  * POST /api/commands/list
  * List all available commands from project and user directories
  */
-router.post('/list', async (req, res) => {
+router.post("/list", async (req, res) => {
   try {
     const { projectPath } = req.body;
     const allCommands = [...builtInCommands];
 
     // Scan project-level commands (.claude/commands/)
     if (projectPath) {
-      const projectCommandsDir = path.join(projectPath, '.claude', 'commands');
+      const projectCommandsDir = path.join(projectPath, ".claude", "commands");
       const projectCommands = await scanCommandsDirectory(
         projectCommandsDir,
         projectCommandsDir,
-        'project'
+        "project",
       );
       allCommands.push(...projectCommands);
     }
 
     // Scan user-level commands (~/.claude/commands/)
     const homeDir = os.homedir();
-    const userCommandsDir = path.join(homeDir, '.claude', 'commands');
+    const userCommandsDir = path.join(homeDir, ".claude", "commands");
     const userCommands = await scanCommandsDirectory(
       userCommandsDir,
       userCommandsDir,
-      'user'
+      "user",
     );
     allCommands.push(...userCommands);
 
     // Separate built-in and custom commands
-    const customCommands = allCommands.filter(cmd => cmd.namespace !== 'builtin');
+    const customCommands = allCommands.filter(
+      (cmd) => cmd.namespace !== "builtin",
+    );
 
     // Sort commands alphabetically by name
     customCommands.sort((a, b) => a.name.localeCompare(b.name));
@@ -440,13 +454,13 @@ router.post('/list', async (req, res) => {
     res.json({
       builtIn: builtInCommands,
       custom: customCommands,
-      count: allCommands.length
+      count: allCommands.length,
     });
   } catch (error) {
-    console.error('Error listing commands:', error);
+    console.error("Error listing commands:", error);
     res.status(500).json({
-      error: 'Failed to list commands',
-      message: error.message
+      error: "Failed to list commands",
+      message: error.message,
     });
   }
 });
@@ -457,13 +471,13 @@ router.post('/list', async (req, res) => {
  * This endpoint prepares the command content but doesn't execute bash commands yet
  * (that will be handled in the command parser utility)
  */
-router.post('/execute', async (req, res) => {
+router.post("/execute", async (req, res) => {
   try {
     const { commandName, commandPath, args = [], context = {} } = req.body;
 
     if (!commandName) {
       return res.status(400).json({
-        error: 'Command name is required'
+        error: "Command name is required",
       });
     }
 
@@ -474,14 +488,17 @@ router.post('/execute', async (req, res) => {
         const result = await handler(args, context);
         return res.json({
           ...result,
-          command: commandName
+          command: commandName,
         });
       } catch (error) {
-        console.error(`Error executing built-in command ${commandName}:`, error);
+        console.error(
+          `Error executing built-in command ${commandName}:`,
+          error,
+        );
         return res.status(500).json({
-          error: 'Command execution failed',
+          error: "Command execution failed",
           message: error.message,
-          command: commandName
+          command: commandName,
         });
       }
     }
@@ -489,7 +506,7 @@ router.post('/execute', async (req, res) => {
     // Handle custom commands
     if (!commandPath) {
       return res.status(400).json({
-        error: 'Command path is required for custom commands'
+        error: "Command path is required for custom commands",
       });
     }
 
@@ -497,56 +514,62 @@ router.post('/execute', async (req, res) => {
     // Security: validate commandPath is within allowed directories
     {
       const resolvedPath = path.resolve(commandPath);
-      const userBase = path.resolve(path.join(os.homedir(), '.claude', 'commands'));
+      const userBase = path.resolve(
+        path.join(os.homedir(), ".claude", "commands"),
+      );
       const projectBase = context?.projectPath
-        ? path.resolve(path.join(context.projectPath, '.claude', 'commands'))
+        ? path.resolve(path.join(context.projectPath, ".claude", "commands"))
         : null;
       const isUnder = (base) => {
         const rel = path.relative(base, resolvedPath);
-        return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+        return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
       };
       if (!(isUnder(userBase) || (projectBase && isUnder(projectBase)))) {
         return res.status(403).json({
-          error: 'Access denied',
-          message: 'Command must be in .claude/commands directory'
+          error: "Access denied",
+          message: "Command must be in .claude/commands directory",
         });
       }
     }
-    const content = await fs.readFile(commandPath, 'utf8');
-    const { data: metadata, content: commandContent } = parseFrontmatter(content);
+    const content = await fs.readFile(commandPath, "utf8");
+    const { data: metadata, content: commandContent } =
+      parseFrontMatter(content);
     // Basic argument replacement (will be enhanced in command parser utility)
     let processedContent = commandContent;
 
     // Replace $ARGUMENTS with all arguments joined
-    const argsString = args.join(' ');
+    const argsString = args.join(" ");
     processedContent = processedContent.replace(/\$ARGUMENTS/g, argsString);
 
     // Replace $1, $2, etc. with positional arguments
     args.forEach((arg, index) => {
       const placeholder = `$${index + 1}`;
-      processedContent = processedContent.replace(new RegExp(`\\${placeholder}\\b`, 'g'), arg);
+      processedContent = processedContent.replace(
+        new RegExp(`\\${placeholder}\\b`, "g"),
+        arg,
+      );
     });
 
     res.json({
-      type: 'custom',
+      type: "custom",
       command: commandName,
       content: processedContent,
       metadata,
-      hasFileIncludes: processedContent.includes('@'),
-      hasBashCommands: processedContent.includes('!')
+      hasFileIncludes: processedContent.includes("@"),
+      hasBashCommands: processedContent.includes("!"),
     });
   } catch (error) {
-    if (error.code === 'ENOENT') {
+    if (error.code === "ENOENT") {
       return res.status(404).json({
-        error: 'Command not found',
-        message: `Command file not found: ${req.body.commandPath}`
+        error: "Command not found",
+        message: `Command file not found: ${req.body.commandPath}`,
       });
     }
 
-    console.error('Error executing command:', error);
+    console.error("Error executing command:", error);
     res.status(500).json({
-      error: 'Failed to execute command',
-      message: error.message
+      error: "Failed to execute command",
+      message: error.message,
     });
   }
 });
diff --git a/server/routes/cursor.js b/server/routes/cursor.js
index 5fbe98ce..bcb2d61b 100644
--- a/server/routes/cursor.js
+++ b/server/routes/cursor.js
@@ -2,7 +2,7 @@ import express from 'express';
 import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
-import { CURSOR_MODELS } from '../../shared/modelConstants.js';
+import { CURSOR_FALLBACK_MODELS } from '../modules/providers/list/cursor/cursor-models.provider.js';
 
 const router = express.Router();
 
@@ -29,7 +29,7 @@ router.get('/config', async (req, res) => {
         config: {
           version: 1,
           model: {
-            modelId: CURSOR_MODELS.DEFAULT,
+            modelId: CURSOR_FALLBACK_MODELS.DEFAULT,
             displayName: 'GPT-5',
           },
           permissions: {
diff --git a/server/routes/gemini.js b/server/routes/gemini.js
index ff7f3663..341365b4 100644
--- a/server/routes/gemini.js
+++ b/server/routes/gemini.js
@@ -1,6 +1,7 @@
 import express from 'express';
+
 import sessionManager from '../sessionManager.js';
-import { sessionNamesDb } from '../database/db.js';
+import { sessionsDb } from '../modules/database/index.js';
 
 const router = express.Router();
 
@@ -13,7 +14,7 @@ router.delete('/sessions/:sessionId', async (req, res) => {
         }
 
         await sessionManager.deleteSession(sessionId);
-        sessionNamesDb.deleteName(sessionId, 'gemini');
+        sessionsDb.deleteSessionById(sessionId);
         res.json({ success: true });
     } catch (error) {
         console.error(`Error deleting Gemini session ${req.params.sessionId}:`, error);
diff --git a/server/routes/git.js b/server/routes/git.js
index a4395638..2aebdad4 100755
--- a/server/routes/git.js
+++ b/server/routes/git.js
@@ -2,7 +2,7 @@ import express from 'express';
 import { spawn } from 'child_process';
 import path from 'path';
 import { promises as fs } from 'fs';
-import { extractProjectDirectory } from '../projects.js';
+import { projectsDb } from '../modules/database/index.js';
 import { queryClaudeSDK } from '../claude-sdk.js';
 import { spawnCursor } from '../cursor-cli.js';
 
@@ -101,14 +101,19 @@ function validateProjectPath(projectPath) {
   return resolved;
 }
 
-// Helper function to get the actual project path from the encoded project name
-async function getActualProjectPath(projectName) {
-  let projectPath;
-  try {
-    projectPath = await extractProjectDirectory(projectName);
-  } catch (error) {
-    console.error(`Error extracting project directory for ${projectName}:`, error);
-    throw new Error(`Unable to resolve project path for "${projectName}"`);
+/**
+ * Resolve the absolute project directory for a given DB `projectId`.
+ *
+ * After the projectName → projectId migration, every git endpoint receives
+ * the DB primary key (`project` query/body param). The legacy filesystem
+ * resolver that walked Claude's JSONL history is no longer used here; the
+ * path comes straight from the `projects` table and is then sanity-checked
+ * by `validateProjectPath` before any `git` command runs against it.
+ */
+async function getActualProjectPath(projectId) {
+  const projectPath = await projectsDb.getProjectPathById(projectId);
+  if (!projectPath) {
+    throw new Error(`Unable to resolve project path for "${projectId}"`);
   }
   return validateProjectPath(projectPath);
 }
@@ -292,7 +297,7 @@ router.get('/status', async (req, res) => {
   const { project } = req.query;
 
   if (!project) {
-    return res.status(400).json({ error: 'Project name is required' });
+    return res.status(400).json({ error: 'Project id is required' });
   }
 
   try {
@@ -355,7 +360,7 @@ router.get('/diff', async (req, res) => {
   const { project, file } = req.query;
   
   if (!project || !file) {
-    return res.status(400).json({ error: 'Project name and file path are required' });
+    return res.status(400).json({ error: 'Project id and file path are required' });
   }
 
   try {
@@ -438,7 +443,7 @@ router.get('/file-with-diff', async (req, res) => {
   const { project, file } = req.query;
 
   if (!project || !file) {
-    return res.status(400).json({ error: 'Project name and file path are required' });
+    return res.status(400).json({ error: 'Project id and file path are required' });
   }
 
   try {
@@ -518,7 +523,7 @@ router.post('/initial-commit', async (req, res) => {
   const { project } = req.body;
 
   if (!project) {
-    return res.status(400).json({ error: 'Project name is required' });
+    return res.status(400).json({ error: 'Project id is required' });
   }
 
   try {
@@ -593,7 +598,7 @@ router.post('/revert-local-commit', async (req, res) => {
   const { project } = req.body;
 
   if (!project) {
-    return res.status(400).json({ error: 'Project name is required' });
+    return res.status(400).json({ error: 'Project id is required' });
   }
 
   try {
@@ -640,7 +645,7 @@ router.get('/branches', async (req, res) => {
   const { project } = req.query;
   
   if (!project) {
-    return res.status(400).json({ error: 'Project name is required' });
+    return res.status(400).json({ error: 'Project id is required' });
   }
 
   try {
@@ -684,7 +689,7 @@ router.post('/checkout', async (req, res) => {
   const { project, branch } = req.body;
   
   if (!project || !branch) {
-    return res.status(400).json({ error: 'Project name and branch are required' });
+    return res.status(400).json({ error: 'Project id and branch are required' });
   }
 
   try {
@@ -706,7 +711,7 @@ router.post('/create-branch', async (req, res) => {
   const { project, branch } = req.body;
   
   if (!project || !branch) {
-    return res.status(400).json({ error: 'Project name and branch name are required' });
+    return res.status(400).json({ error: 'Project id and branch name are required' });
   }
 
   try {
@@ -728,7 +733,7 @@ router.post('/delete-branch', async (req, res) => {
   const { project, branch } = req.body;
 
   if (!project || !branch) {
-    return res.status(400).json({ error: 'Project name and branch name are required' });
+    return res.status(400).json({ error: 'Project id and branch name are required' });
   }
 
   try {
@@ -754,7 +759,7 @@ router.get('/commits', async (req, res) => {
   const { project, limit = 10 } = req.query;
   
   if (!project) {
-    return res.status(400).json({ error: 'Project name is required' });
+    return res.status(400).json({ error: 'Project id is required' });
   }
 
   try {
@@ -811,7 +816,7 @@ router.get('/commit-diff', async (req, res) => {
   const { project, commit } = req.query;
   
   if (!project || !commit) {
-    return res.status(400).json({ error: 'Project name and commit hash are required' });
+    return res.status(400).json({ error: 'Project id and commit hash are required' });
   }
 
   try {
@@ -843,7 +848,7 @@ router.post('/generate-commit-message', async (req, res) => {
   const { project, files, provider = 'claude' } = req.body;
 
   if (!project || !files || files.length === 0) {
-    return res.status(400).json({ error: 'Project name and files are required' });
+    return res.status(400).json({ error: 'Project id and files are required' });
   }
 
   // Validate provider
@@ -1048,7 +1053,7 @@ router.get('/remote-status', async (req, res) => {
   const { project } = req.query;
   
   if (!project) {
-    return res.status(400).json({ error: 'Project name is required' });
+    return res.status(400).json({ error: 'Project id is required' });
   }
 
   try {
@@ -1126,7 +1131,7 @@ router.post('/fetch', async (req, res) => {
   const { project } = req.body;
   
   if (!project) {
-    return res.status(400).json({ error: 'Project name is required' });
+    return res.status(400).json({ error: 'Project id is required' });
   }
 
   try {
@@ -1167,7 +1172,7 @@ router.post('/pull', async (req, res) => {
   const { project } = req.body;
   
   if (!project) {
-    return res.status(400).json({ error: 'Project name is required' });
+    return res.status(400).json({ error: 'Project id is required' });
   }
 
   try {
@@ -1235,7 +1240,7 @@ router.post('/push', async (req, res) => {
   const { project } = req.body;
   
   if (!project) {
-    return res.status(400).json({ error: 'Project name is required' });
+    return res.status(400).json({ error: 'Project id is required' });
   }
 
   try {
@@ -1306,7 +1311,7 @@ router.post('/publish', async (req, res) => {
   const { project, branch } = req.body;
   
   if (!project || !branch) {
-    return res.status(400).json({ error: 'Project name and branch are required' });
+    return res.status(400).json({ error: 'Project id and branch are required' });
   }
 
   try {
@@ -1385,7 +1390,7 @@ router.post('/discard', async (req, res) => {
   const { project, file } = req.body;
   
   if (!project || !file) {
-    return res.status(400).json({ error: 'Project name and file path are required' });
+    return res.status(400).json({ error: 'Project id and file path are required' });
   }
 
   try {
@@ -1439,7 +1444,7 @@ router.post('/delete-untracked', async (req, res) => {
   const { project, file } = req.body;
   
   if (!project || !file) {
-    return res.status(400).json({ error: 'Project name and file path are required' });
+    return res.status(400).json({ error: 'Project id and file path are required' });
   }
 
   try {
diff --git a/server/routes/messages.js b/server/routes/messages.js
deleted file mode 100644
index 81444d56..00000000
--- a/server/routes/messages.js
+++ /dev/null
@@ -1,61 +0,0 @@
-/**
- * Unified messages endpoint.
- *
- * GET /api/sessions/:sessionId/messages?provider=claude&projectName=foo&limit=50&offset=0
- *
- * Replaces the four provider-specific session message endpoints with a single route
- * that delegates to the appropriate adapter via the provider registry.
- *
- * @module routes/messages
- */
-
-import express from 'express';
-import { sessionsService } from '../modules/providers/services/sessions.service.js';
-
-const router = express.Router();
-
-/**
- * GET /api/sessions/:sessionId/messages
- *
- * Auth: authenticateToken applied at mount level in index.js
- *
- * Query params:
- *   provider    - 'claude' | 'cursor' | 'codex' | 'gemini' (default: 'claude')
- *   projectName - required for claude provider
- *   projectPath - required for cursor provider (absolute path used for cwdId hash)
- *   limit       - page size (omit or null for all)
- *   offset      - pagination offset (default: 0)
- */
-router.get('/:sessionId/messages', async (req, res) => {
-  try {
-    const { sessionId } = req.params;
-    const provider = String(req.query.provider || 'claude').trim().toLowerCase();
-    const projectName = req.query.projectName || '';
-    const projectPath = req.query.projectPath || '';
-    const limitParam = req.query.limit;
-    const limit = limitParam !== undefined && limitParam !== null && limitParam !== ''
-      ? parseInt(limitParam, 10)
-      : null;
-    const offset = parseInt(req.query.offset || '0', 10);
-
-    const availableProviders = sessionsService.listProviderIds();
-    if (!availableProviders.includes(provider)) {
-      const available = availableProviders.join(', ');
-      return res.status(400).json({ error: `Unknown provider: ${provider}. Available: ${available}` });
-    }
-
-    const result = await sessionsService.fetchHistory(provider, sessionId, {
-      projectName,
-      projectPath,
-      limit,
-      offset,
-    });
-
-    return res.json(result);
-  } catch (error) {
-    console.error('Error fetching unified messages:', error);
-    return res.status(500).json({ error: 'Failed to fetch messages' });
-  }
-});
-
-export default router;
diff --git a/server/routes/projects.js b/server/routes/projects.js
deleted file mode 100644
index cf3a62e4..00000000
--- a/server/routes/projects.js
+++ /dev/null
@@ -1,548 +0,0 @@
-import express from 'express';
-import { promises as fs } from 'fs';
-import path from 'path';
-import { spawn } from 'child_process';
-import os from 'os';
-import { addProjectManually } from '../projects.js';
-
-const router = express.Router();
-
-function sanitizeGitError(message, token) {
-  if (!message || !token) return message;
-  return message.replace(new RegExp(token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'), '***');
-}
-
-// Configure allowed workspace root (defaults to user's home directory)
-export const WORKSPACES_ROOT = process.env.WORKSPACES_ROOT || os.homedir();
-
-// System-critical paths that should never be used as workspace directories
-export const FORBIDDEN_PATHS = [
-  // Unix
-  '/',
-  '/etc',
-  '/bin',
-  '/sbin',
-  '/usr',
-  '/dev',
-  '/proc',
-  '/sys',
-  '/var',
-  '/boot',
-  '/root',
-  '/lib',
-  '/lib64',
-  '/opt',
-  '/tmp',
-  '/run',
-  // Windows
-  'C:\\Windows',
-  'C:\\Program Files',
-  'C:\\Program Files (x86)',
-  'C:\\ProgramData',
-  'C:\\System Volume Information',
-  'C:\\$Recycle.Bin'
-];
-
-/**
- * Validates that a path is safe for workspace operations
- * @param {string} requestedPath - The path to validate
- * @returns {Promise<{valid: boolean, resolvedPath?: string, error?: string}>}
- */
-export async function validateWorkspacePath(requestedPath) {
-  try {
-    // Resolve to absolute path
-    let absolutePath = path.resolve(requestedPath);
-
-    // Check if path is a forbidden system directory
-    const normalizedPath = path.normalize(absolutePath);
-    if (FORBIDDEN_PATHS.includes(normalizedPath) || normalizedPath === '/') {
-      return {
-        valid: false,
-        error: 'Cannot use system-critical directories as workspace locations'
-      };
-    }
-
-    // Additional check for paths starting with forbidden directories
-    for (const forbidden of FORBIDDEN_PATHS) {
-      if (normalizedPath === forbidden ||
-          normalizedPath.startsWith(forbidden + path.sep)) {
-        // Exception: /var/tmp and similar user-accessible paths might be allowed
-        // but /var itself and most /var subdirectories should be blocked
-        if (forbidden === '/var' &&
-            (normalizedPath.startsWith('/var/tmp') ||
-             normalizedPath.startsWith('/var/folders'))) {
-          continue; // Allow these specific cases
-        }
-
-        return {
-          valid: false,
-          error: `Cannot create workspace in system directory: ${forbidden}`
-        };
-      }
-    }
-
-    // Try to resolve the real path (following symlinks)
-    let realPath;
-    try {
-      // Check if path exists to resolve real path
-      await fs.access(absolutePath);
-      realPath = await fs.realpath(absolutePath);
-    } catch (error) {
-      if (error.code === 'ENOENT') {
-        // Path doesn't exist yet - check parent directory
-        let parentPath = path.dirname(absolutePath);
-        try {
-          const parentRealPath = await fs.realpath(parentPath);
-
-          // Reconstruct the full path with real parent
-          realPath = path.join(parentRealPath, path.basename(absolutePath));
-        } catch (parentError) {
-          if (parentError.code === 'ENOENT') {
-            // Parent doesn't exist either - use the absolute path as-is
-            // We'll validate it's within allowed root
-            realPath = absolutePath;
-          } else {
-            throw parentError;
-          }
-        }
-      } else {
-        throw error;
-      }
-    }
-
-    // Resolve the workspace root to its real path
-    const resolvedWorkspaceRoot = await fs.realpath(WORKSPACES_ROOT);
-
-    // Ensure the resolved path is contained within the allowed workspace root
-    if (!realPath.startsWith(resolvedWorkspaceRoot + path.sep) &&
-        realPath !== resolvedWorkspaceRoot) {
-      return {
-        valid: false,
-        error: `Workspace path must be within the allowed workspace root: ${WORKSPACES_ROOT}`
-      };
-    }
-
-    // Additional symlink check for existing paths
-    try {
-      await fs.access(absolutePath);
-      const stats = await fs.lstat(absolutePath);
-
-      if (stats.isSymbolicLink()) {
-        // Verify symlink target is also within allowed root
-        const linkTarget = await fs.readlink(absolutePath);
-        const resolvedTarget = path.resolve(path.dirname(absolutePath), linkTarget);
-        const realTarget = await fs.realpath(resolvedTarget);
-
-        if (!realTarget.startsWith(resolvedWorkspaceRoot + path.sep) &&
-            realTarget !== resolvedWorkspaceRoot) {
-          return {
-            valid: false,
-            error: 'Symlink target is outside the allowed workspace root'
-          };
-        }
-      }
-    } catch (error) {
-      if (error.code !== 'ENOENT') {
-        throw error;
-      }
-      // Path doesn't exist - that's fine for new workspace creation
-    }
-
-    return {
-      valid: true,
-      resolvedPath: realPath
-    };
-
-  } catch (error) {
-    return {
-      valid: false,
-      error: `Path validation failed: ${error.message}`
-    };
-  }
-}
-
-/**
- * Create a new workspace
- * POST /api/projects/create-workspace
- *
- * Body:
- * - workspaceType: 'existing' | 'new'
- * - path: string (workspace path)
- * - githubUrl?: string (optional, for new workspaces)
- * - githubTokenId?: number (optional, ID of stored token)
- * - newGithubToken?: string (optional, one-time token)
- */
-router.post('/create-workspace', async (req, res) => {
-  try {
-    const { workspaceType, path: workspacePath, githubUrl, githubTokenId, newGithubToken } = req.body;
-
-    // Validate required fields
-    if (!workspaceType || !workspacePath) {
-      return res.status(400).json({ error: 'workspaceType and path are required' });
-    }
-
-    if (!['existing', 'new'].includes(workspaceType)) {
-      return res.status(400).json({ error: 'workspaceType must be "existing" or "new"' });
-    }
-
-    // Validate path safety before any operations
-    const validation = await validateWorkspacePath(workspacePath);
-    if (!validation.valid) {
-      return res.status(400).json({
-        error: 'Invalid workspace path',
-        details: validation.error
-      });
-    }
-
-    const absolutePath = validation.resolvedPath;
-
-    // Handle existing workspace
-    if (workspaceType === 'existing') {
-      // Check if the path exists
-      try {
-        await fs.access(absolutePath);
-        const stats = await fs.stat(absolutePath);
-
-        if (!stats.isDirectory()) {
-          return res.status(400).json({ error: 'Path exists but is not a directory' });
-        }
-      } catch (error) {
-        if (error.code === 'ENOENT') {
-          return res.status(404).json({ error: 'Workspace path does not exist' });
-        }
-        throw error;
-      }
-
-      // Add the existing workspace to the project list
-      const project = await addProjectManually(absolutePath);
-
-      return res.json({
-        success: true,
-        project,
-        message: 'Existing workspace added successfully'
-      });
-    }
-
-    // Handle new workspace creation
-    if (workspaceType === 'new') {
-      // Create the directory if it doesn't exist
-      await fs.mkdir(absolutePath, { recursive: true });
-
-      // If GitHub URL is provided, clone the repository
-      if (githubUrl) {
-        let githubToken = null;
-
-        // Get GitHub token if needed
-        if (githubTokenId) {
-          // Fetch token from database
-          const token = await getGithubTokenById(githubTokenId, req.user.id);
-          if (!token) {
-            // Clean up created directory
-            await fs.rm(absolutePath, { recursive: true, force: true });
-            return res.status(404).json({ error: 'GitHub token not found' });
-          }
-          githubToken = token.github_token;
-        } else if (newGithubToken) {
-          githubToken = newGithubToken;
-        }
-
-        // Extract repo name from URL for the clone destination
-        const normalizedUrl = githubUrl.replace(/\/+$/, '').replace(/\.git$/, '');
-        const repoName = normalizedUrl.split('/').pop() || 'repository';
-        const clonePath = path.join(absolutePath, repoName);
-
-        // Check if clone destination already exists to prevent data loss
-        try {
-          await fs.access(clonePath);
-          return res.status(409).json({
-            error: 'Directory already exists',
-            details: `The destination path "${clonePath}" already exists. Please choose a different location or remove the existing directory.`
-          });
-        } catch (err) {
-          // Directory doesn't exist, which is what we want
-        }
-
-        // Clone the repository into a subfolder
-        try {
-          await cloneGitHubRepository(githubUrl, clonePath, githubToken);
-        } catch (error) {
-          // Only clean up if clone created partial data (check if dir exists and is empty or partial)
-          try {
-            const stats = await fs.stat(clonePath);
-            if (stats.isDirectory()) {
-              await fs.rm(clonePath, { recursive: true, force: true });
-            }
-          } catch (cleanupError) {
-            // Directory doesn't exist or cleanup failed - ignore
-          }
-          throw new Error(`Failed to clone repository: ${error.message}`);
-        }
-
-        // Add the cloned repo path to the project list
-        const project = await addProjectManually(clonePath);
-
-        return res.json({
-          success: true,
-          project,
-          message: 'New workspace created and repository cloned successfully'
-        });
-      }
-
-      // Add the new workspace to the project list (no clone)
-      const project = await addProjectManually(absolutePath);
-
-      return res.json({
-        success: true,
-        project,
-        message: 'New workspace created successfully'
-      });
-    }
-
-  } catch (error) {
-    console.error('Error creating workspace:', error);
-    res.status(500).json({
-      error: error.message || 'Failed to create workspace',
-      details: process.env.NODE_ENV === 'development' ? error.stack : undefined
-    });
-  }
-});
-
-/**
- * Helper function to get GitHub token from database
- */
-async function getGithubTokenById(tokenId, userId) {
-  const { db } = await import('../database/db.js');
-
-  const credential = db.prepare(
-    'SELECT * FROM user_credentials WHERE id = ? AND user_id = ? AND credential_type = ? AND is_active = 1'
-  ).get(tokenId, userId, 'github_token');
-
-  // Return in the expected format (github_token field for compatibility)
-  if (credential) {
-    return {
-      ...credential,
-      github_token: credential.credential_value
-    };
-  }
-
-  return null;
-}
-
-/**
- * Clone repository with progress streaming (SSE)
- * GET /api/projects/clone-progress
- */
-router.get('/clone-progress', async (req, res) => {
-  const { path: workspacePath, githubUrl, githubTokenId, newGithubToken } = req.query;
-
-  res.setHeader('Content-Type', 'text/event-stream');
-  res.setHeader('Cache-Control', 'no-cache');
-  res.setHeader('Connection', 'keep-alive');
-  res.flushHeaders();
-
-  const sendEvent = (type, data) => {
-    res.write(`data: ${JSON.stringify({ type, ...data })}\n\n`);
-  };
-
-  try {
-    if (!workspacePath || !githubUrl) {
-      sendEvent('error', { message: 'workspacePath and githubUrl are required' });
-      res.end();
-      return;
-    }
-
-    const validation = await validateWorkspacePath(workspacePath);
-    if (!validation.valid) {
-      sendEvent('error', { message: validation.error });
-      res.end();
-      return;
-    }
-
-    const absolutePath = validation.resolvedPath;
-
-    await fs.mkdir(absolutePath, { recursive: true });
-
-    let githubToken = null;
-    if (githubTokenId) {
-      const token = await getGithubTokenById(parseInt(githubTokenId), req.user.id);
-      if (!token) {
-        await fs.rm(absolutePath, { recursive: true, force: true });
-        sendEvent('error', { message: 'GitHub token not found' });
-        res.end();
-        return;
-      }
-      githubToken = token.github_token;
-    } else if (newGithubToken) {
-      githubToken = newGithubToken;
-    }
-
-    const normalizedUrl = githubUrl.replace(/\/+$/, '').replace(/\.git$/, '');
-    const repoName = normalizedUrl.split('/').pop() || 'repository';
-    const clonePath = path.join(absolutePath, repoName);
-
-    // Check if clone destination already exists to prevent data loss
-    try {
-      await fs.access(clonePath);
-      sendEvent('error', { message: `Directory "${repoName}" already exists. Please choose a different location or remove the existing directory.` });
-      res.end();
-      return;
-    } catch (err) {
-      // Directory doesn't exist, which is what we want
-    }
-
-    let cloneUrl = githubUrl;
-    if (githubToken) {
-      try {
-        const url = new URL(githubUrl);
-        url.username = githubToken;
-        url.password = '';
-        cloneUrl = url.toString();
-      } catch (error) {
-        // SSH URL or invalid - use as-is
-      }
-    }
-
-    sendEvent('progress', { message: `Cloning into '${repoName}'...` });
-
-    const gitProcess = spawn('git', ['clone', '--progress', cloneUrl, clonePath], {
-      stdio: ['ignore', 'pipe', 'pipe'],
-      env: {
-        ...process.env,
-        GIT_TERMINAL_PROMPT: '0'
-      }
-    });
-
-    let lastError = '';
-
-    gitProcess.stdout.on('data', (data) => {
-      const message = data.toString().trim();
-      if (message) {
-        sendEvent('progress', { message });
-      }
-    });
-
-    gitProcess.stderr.on('data', (data) => {
-      const message = data.toString().trim();
-      lastError = message;
-      if (message) {
-        sendEvent('progress', { message });
-      }
-    });
-
-    gitProcess.on('close', async (code) => {
-      if (code === 0) {
-        try {
-          const project = await addProjectManually(clonePath);
-          sendEvent('complete', { project, message: 'Repository cloned successfully' });
-        } catch (error) {
-          sendEvent('error', { message: `Clone succeeded but failed to add project: ${error.message}` });
-        }
-      } else {
-        const sanitizedError = sanitizeGitError(lastError, githubToken);
-        let errorMessage = 'Git clone failed';
-        if (lastError.includes('Authentication failed') || lastError.includes('could not read Username')) {
-          errorMessage = 'Authentication failed. Please check your credentials.';
-        } else if (lastError.includes('Repository not found')) {
-          errorMessage = 'Repository not found. Please check the URL and ensure you have access.';
-        } else if (lastError.includes('already exists')) {
-          errorMessage = 'Directory already exists';
-        } else if (sanitizedError) {
-          errorMessage = sanitizedError;
-        }
-        try {
-          await fs.rm(clonePath, { recursive: true, force: true });
-        } catch (cleanupError) {
-          console.error('Failed to clean up after clone failure:', sanitizeGitError(cleanupError.message, githubToken));
-        }
-        sendEvent('error', { message: errorMessage });
-      }
-      res.end();
-    });
-
-    gitProcess.on('error', (error) => {
-      if (error.code === 'ENOENT') {
-        sendEvent('error', { message: 'Git is not installed or not in PATH' });
-      } else {
-        sendEvent('error', { message: error.message });
-      }
-      res.end();
-    });
-
-    req.on('close', () => {
-      gitProcess.kill();
-    });
-
-  } catch (error) {
-    sendEvent('error', { message: error.message });
-    res.end();
-  }
-});
-
-/**
- * Helper function to clone a GitHub repository
- */
-function cloneGitHubRepository(githubUrl, destinationPath, githubToken = null) {
-  return new Promise((resolve, reject) => {
-    let cloneUrl = githubUrl;
-
-    if (githubToken) {
-      try {
-        const url = new URL(githubUrl);
-        url.username = githubToken;
-        url.password = '';
-        cloneUrl = url.toString();
-      } catch (error) {
-        // SSH URL - use as-is
-      }
-    }
-
-    const gitProcess = spawn('git', ['clone', '--progress', cloneUrl, destinationPath], {
-      stdio: ['ignore', 'pipe', 'pipe'],
-      env: {
-        ...process.env,
-        GIT_TERMINAL_PROMPT: '0'
-      }
-    });
-
-    let stdout = '';
-    let stderr = '';
-
-    gitProcess.stdout.on('data', (data) => {
-      stdout += data.toString();
-    });
-
-    gitProcess.stderr.on('data', (data) => {
-      stderr += data.toString();
-    });
-
-    gitProcess.on('close', (code) => {
-      if (code === 0) {
-        resolve({ stdout, stderr });
-      } else {
-        let errorMessage = 'Git clone failed';
-
-        if (stderr.includes('Authentication failed') || stderr.includes('could not read Username')) {
-          errorMessage = 'Authentication failed. Please check your GitHub token.';
-        } else if (stderr.includes('Repository not found')) {
-          errorMessage = 'Repository not found. Please check the URL and ensure you have access.';
-        } else if (stderr.includes('already exists')) {
-          errorMessage = 'Directory already exists';
-        } else if (stderr) {
-          errorMessage = stderr;
-        }
-
-        reject(new Error(errorMessage));
-      }
-    });
-
-    gitProcess.on('error', (error) => {
-      if (error.code === 'ENOENT') {
-        reject(new Error('Git is not installed or not in PATH'));
-      } else {
-        reject(error);
-      }
-    });
-  });
-}
-
-export default router;
diff --git a/server/routes/settings.js b/server/routes/settings.js
index e2ce0885..75406c54 100644
--- a/server/routes/settings.js
+++ b/server/routes/settings.js
@@ -1,5 +1,6 @@
 import express from 'express';
-import { apiKeysDb, credentialsDb, notificationPreferencesDb, pushSubscriptionsDb } from '../database/db.js';
+
+import { apiKeysDb, credentialsDb, notificationPreferencesDb, pushSubscriptionsDb } from '../modules/database/index.js';
 import { getPublicKey } from '../services/vapid-keys.js';
 import { createNotificationEvent, notifyUserIfEnabled } from '../services/notification-orchestrator.js';
 
@@ -273,14 +274,4 @@ router.post('/push/unsubscribe', async (req, res) => {
   }
 });
 
-// Host OS for UI (e.g. hide Cursor agent when the backend runs on Windows).
-router.get('/server-env', async (req, res) => {
-  try {
-    res.json({ platform: process.platform });
-  } catch (error) {
-    console.error('Error reading server environment:', error);
-    res.status(500).json({ error: 'Failed to read server environment' });
-  }
-});
-
 export default router;
diff --git a/server/routes/taskmaster.js b/server/routes/taskmaster.js
index 54f7153a..01a8d801 100644
--- a/server/routes/taskmaster.js
+++ b/server/routes/taskmaster.js
@@ -13,10 +13,25 @@ import fs from 'fs';
 import path from 'path';
 import { promises as fsPromises } from 'fs';
 import { spawn } from 'child_process';
-import { extractProjectDirectory } from '../projects.js';
+import { projectsDb } from '../modules/database/index.js';
 import { detectTaskMasterMCPServer } from '../utils/mcp-detector.js';
 import { broadcastTaskMasterProjectUpdate, broadcastTaskMasterTasksUpdate } from '../utils/taskmaster-websocket.js';
 
+/**
+ * Resolve the absolute project directory from a DB-assigned `projectId`.
+ *
+ * TaskMaster routes used to accept a Claude-encoded folder name (`projectName`)
+ * and derive the path from JSONL history. After the projectId migration the
+ * only identifier we accept is the primary key of the `projects` table, so
+ * every handler calls this helper and 404s when the id is unknown.
+ */
+async function resolveProjectPathFromId(projectId) {
+  if (!projectId) {
+    return null;
+  }
+  return projectsDb.getProjectPathById(projectId);
+}
+
 const router = express.Router();
 
 /**
@@ -132,21 +147,22 @@ router.get('/installation-status', async (req, res) => {
 });
 
 /**
- * GET /api/taskmaster/tasks/:projectName
+ * GET /api/taskmaster/tasks/:projectId
  * Load actual tasks from .taskmaster/tasks/tasks.json
+ *
+ * `projectId` is the DB primary key of the project; the folder is resolved via
+ * the projects table rather than extracted from Claude JSONL history.
  */
-router.get('/tasks/:projectName', async (req, res) => {
+router.get('/tasks/:projectId', async (req, res) => {
     try {
-        const { projectName } = req.params;
-        
-        // Get project path
-        let projectPath;
-        try {
-            projectPath = await extractProjectDirectory(projectName);
-        } catch (error) {
+        const { projectId } = req.params;
+
+        // Get project path via the DB; the legacy JSONL-based resolver is gone.
+        const projectPath = await resolveProjectPathFromId(projectId);
+        if (!projectPath) {
             return res.status(404).json({
                 error: 'Project not found',
-                message: `Project "${projectName}" does not exist`
+                message: `Project "${projectId}" does not exist`
             });
         }
 
@@ -158,7 +174,7 @@ router.get('/tasks/:projectName', async (req, res) => {
             await fsPromises.access(tasksFilePath);
         } catch (error) {
             return res.json({
-                projectName,
+                projectId,
                 tasks: [],
                 message: 'No tasks.json file found'
             });
@@ -213,7 +229,7 @@ router.get('/tasks/:projectName', async (req, res) => {
             }));
 
             res.json({
-                projectName,
+                projectId,
                 projectPath,
                 tasks: transformedTasks,
                 currentTag,
@@ -247,21 +263,19 @@ router.get('/tasks/:projectName', async (req, res) => {
 });
 
 /**
- * GET /api/taskmaster/prd/:projectName
+ * GET /api/taskmaster/prd/:projectId
  * List all PRD files in the project's .taskmaster/docs directory
  */
-router.get('/prd/:projectName', async (req, res) => {
+router.get('/prd/:projectId', async (req, res) => {
     try {
-        const { projectName } = req.params;
-        
-        // Get project path
-        let projectPath;
-        try {
-            projectPath = await extractProjectDirectory(projectName);
-        } catch (error) {
+        const { projectId } = req.params;
+
+        // projectId → projectPath lookup through the DB (post-migration).
+        const projectPath = await resolveProjectPathFromId(projectId);
+        if (!projectPath) {
             return res.status(404).json({
                 error: 'Project not found',
-                message: `Project "${projectName}" does not exist`
+                message: `Project "${projectId}" does not exist`
             });
         }
 
@@ -272,7 +286,7 @@ router.get('/prd/:projectName', async (req, res) => {
             await fsPromises.access(docsPath, fs.constants.R_OK);
         } catch (error) {
             return res.json({
-                projectName,
+                projectId,
                 prdFiles: [],
                 message: 'No .taskmaster/docs directory found'
             });
@@ -299,7 +313,7 @@ router.get('/prd/:projectName', async (req, res) => {
             }
 
             res.json({
-                projectName,
+                projectId,
                 projectPath,
                 prdFiles: prdFiles.sort((a, b) => new Date(b.modified) - new Date(a.modified)),
                 timestamp: new Date().toISOString()
@@ -323,12 +337,12 @@ router.get('/prd/:projectName', async (req, res) => {
 });
 
 /**
- * POST /api/taskmaster/prd/:projectName
+ * POST /api/taskmaster/prd/:projectId
  * Create or update a PRD file in the project's .taskmaster/docs directory
  */
-router.post('/prd/:projectName', async (req, res) => {
+router.post('/prd/:projectId', async (req, res) => {
     try {
-        const { projectName } = req.params;
+        const { projectId } = req.params;
         const { fileName, content } = req.body;
 
         if (!fileName || !content) {
@@ -346,14 +360,12 @@ router.post('/prd/:projectName', async (req, res) => {
             });
         }
 
-        // Get project path
-        let projectPath;
-        try {
-            projectPath = await extractProjectDirectory(projectName);
-        } catch (error) {
+        // Resolve the project folder through the DB using the projectId param.
+        const projectPath = await resolveProjectPathFromId(projectId);
+        if (!projectPath) {
             return res.status(404).json({
                 error: 'Project not found',
-                message: `Project "${projectName}" does not exist`
+                message: `Project "${projectId}" does not exist`
             });
         }
 
@@ -379,7 +391,7 @@ router.post('/prd/:projectName', async (req, res) => {
             const stats = await fsPromises.stat(filePath);
 
             res.json({
-                projectName,
+                projectId,
                 projectPath,
                 fileName,
                 filePath: path.relative(projectPath, filePath),
@@ -408,21 +420,18 @@ router.post('/prd/:projectName', async (req, res) => {
 });
 
 /**
- * GET /api/taskmaster/prd/:projectName/:fileName
+ * GET /api/taskmaster/prd/:projectId/:fileName
  * Get content of a specific PRD file
  */
-router.get('/prd/:projectName/:fileName', async (req, res) => {
+router.get('/prd/:projectId/:fileName', async (req, res) => {
     try {
-        const { projectName, fileName } = req.params;
-        
-        // Get project path
-        let projectPath;
-        try {
-            projectPath = await extractProjectDirectory(projectName);
-        } catch (error) {
+        const { projectId, fileName } = req.params;
+
+        const projectPath = await resolveProjectPathFromId(projectId);
+        if (!projectPath) {
             return res.status(404).json({
                 error: 'Project not found',
-                message: `Project "${projectName}" does not exist`
+                message: `Project "${projectId}" does not exist`
             });
         }
 
@@ -444,7 +453,7 @@ router.get('/prd/:projectName/:fileName', async (req, res) => {
             const stats = await fsPromises.stat(filePath);
 
             res.json({
-                projectName,
+                projectId,
                 projectPath,
                 fileName,
                 filePath: path.relative(projectPath, filePath),
@@ -473,21 +482,18 @@ router.get('/prd/:projectName/:fileName', async (req, res) => {
 });
 
 /**
- * POST /api/taskmaster/init/:projectName
+ * POST /api/taskmaster/init/:projectId
  * Initialize TaskMaster in a project
  */
-router.post('/init/:projectName', async (req, res) => {
+router.post('/init/:projectId', async (req, res) => {
     try {
-        const { projectName } = req.params;
-        
-        // Get project path
-        let projectPath;
-        try {
-            projectPath = await extractProjectDirectory(projectName);
-        } catch (error) {
+        const { projectId } = req.params;
+
+        const projectPath = await resolveProjectPathFromId(projectId);
+        if (!projectPath) {
             return res.status(404).json({
                 error: 'Project not found',
-                message: `Project "${projectName}" does not exist`
+                message: `Project "${projectId}" does not exist`
             });
         }
 
@@ -522,17 +528,19 @@ router.post('/init/:projectName', async (req, res) => {
 
         initProcess.on('close', (code) => {
             if (code === 0) {
-                // Broadcast TaskMaster project update via WebSocket
+                // Broadcast TaskMaster project update via WebSocket. The
+                // WebSocket payload keeps using `projectId` so the frontend
+                // can match notifications against the current selection.
                 if (req.app.locals.wss) {
                     broadcastTaskMasterProjectUpdate(
-                        req.app.locals.wss, 
-                        projectName, 
+                        req.app.locals.wss,
+                        projectId,
                         { hasTaskmaster: true, status: 'initialized' }
                     );
                 }
 
                 res.json({
-                    projectName,
+                    projectId,
                     projectPath,
                     message: 'TaskMaster initialized successfully',
                     output: stdout,
@@ -562,12 +570,12 @@ router.post('/init/:projectName', async (req, res) => {
 });
 
 /**
- * POST /api/taskmaster/add-task/:projectName
+ * POST /api/taskmaster/add-task/:projectId
  * Add a new task to the project
  */
-router.post('/add-task/:projectName', async (req, res) => {
+router.post('/add-task/:projectId', async (req, res) => {
     try {
-        const { projectName } = req.params;
+        const { projectId } = req.params;
         const { prompt, title, description, priority = 'medium', dependencies } = req.body;
 
         if (!prompt && (!title || !description)) {
@@ -576,15 +584,12 @@ router.post('/add-task/:projectName', async (req, res) => {
                 message: 'Either "prompt" or both "title" and "description" are required'
             });
         }
-        
-        // Get project path
-        let projectPath;
-        try {
-            projectPath = await extractProjectDirectory(projectName);
-        } catch (error) {
+
+        const projectPath = await resolveProjectPathFromId(projectId);
+        if (!projectPath) {
             return res.status(404).json({
                 error: 'Project not found',
-                message: `Project "${projectName}" does not exist`
+                message: `Project "${projectId}" does not exist`
             });
         }
 
@@ -629,16 +634,17 @@ router.post('/add-task/:projectName', async (req, res) => {
             console.log('Stderr:', stderr);
             
             if (code === 0) {
-                // Broadcast task update via WebSocket
+                // Broadcast task update via WebSocket using the projectId so
+                // clients subscribed to this project get notified immediately.
                 if (req.app.locals.wss) {
                     broadcastTaskMasterTasksUpdate(
-                        req.app.locals.wss, 
-                        projectName
+                        req.app.locals.wss,
+                        projectId
                     );
                 }
 
                 res.json({
-                    projectName,
+                    projectId,
                     projectPath,
                     message: 'Task added successfully',
                     output: stdout,
@@ -666,22 +672,19 @@ router.post('/add-task/:projectName', async (req, res) => {
 });
 
 /**
- * PUT /api/taskmaster/update-task/:projectName/:taskId
+ * PUT /api/taskmaster/update-task/:projectId/:taskId
  * Update a specific task using TaskMaster CLI
  */
-router.put('/update-task/:projectName/:taskId', async (req, res) => {
+router.put('/update-task/:projectId/:taskId', async (req, res) => {
     try {
-        const { projectName, taskId } = req.params;
+        const { projectId, taskId } = req.params;
         const { title, description, status, priority, details } = req.body;
-        
-        // Get project path
-        let projectPath;
-        try {
-            projectPath = await extractProjectDirectory(projectName);
-        } catch (error) {
+
+        const projectPath = await resolveProjectPathFromId(projectId);
+        if (!projectPath) {
             return res.status(404).json({
                 error: 'Project not found',
-                message: `Project "${projectName}" does not exist`
+                message: `Project "${projectId}" does not exist`
             });
         }
 
@@ -707,11 +710,11 @@ router.put('/update-task/:projectName/:taskId', async (req, res) => {
                 if (code === 0) {
                     // Broadcast task update via WebSocket
                     if (req.app.locals.wss) {
-                        broadcastTaskMasterTasksUpdate(req.app.locals.wss, projectName);
+                        broadcastTaskMasterTasksUpdate(req.app.locals.wss, projectId);
                     }
 
                     res.json({
-                        projectName,
+                        projectId,
                         projectPath,
                         taskId,
                         message: 'Task status updated successfully',
@@ -759,11 +762,11 @@ router.put('/update-task/:projectName/:taskId', async (req, res) => {
                 if (code === 0) {
                     // Broadcast task update via WebSocket
                     if (req.app.locals.wss) {
-                        broadcastTaskMasterTasksUpdate(req.app.locals.wss, projectName);
+                        broadcastTaskMasterTasksUpdate(req.app.locals.wss, projectId);
                     }
 
                     res.json({
-                        projectName,
+                        projectId,
                         projectPath,
                         taskId,
                         message: 'Task updated successfully',
@@ -793,22 +796,19 @@ router.put('/update-task/:projectName/:taskId', async (req, res) => {
 });
 
 /**
- * POST /api/taskmaster/parse-prd/:projectName
+ * POST /api/taskmaster/parse-prd/:projectId
  * Parse a PRD file to generate tasks
  */
-router.post('/parse-prd/:projectName', async (req, res) => {
+router.post('/parse-prd/:projectId', async (req, res) => {
     try {
-        const { projectName } = req.params;
+        const { projectId } = req.params;
         const { fileName = 'prd.txt', numTasks, append = false } = req.body;
-        
-        // Get project path
-        let projectPath;
-        try {
-            projectPath = await extractProjectDirectory(projectName);
-        } catch (error) {
+
+        const projectPath = await resolveProjectPathFromId(projectId);
+        if (!projectPath) {
             return res.status(404).json({
                 error: 'Project not found',
-                message: `Project "${projectName}" does not exist`
+                message: `Project "${projectId}" does not exist`
             });
         }
 
@@ -859,13 +859,13 @@ router.post('/parse-prd/:projectName', async (req, res) => {
                 // Broadcast task update via WebSocket
                 if (req.app.locals.wss) {
                     broadcastTaskMasterTasksUpdate(
-                        req.app.locals.wss, 
-                        projectName
+                        req.app.locals.wss,
+                        projectId
                     );
                 }
 
                 res.json({
-                    projectName,
+                    projectId,
                     projectPath,
                     prdFile: fileName,
                     message: 'PRD parsed and tasks generated successfully',
@@ -1340,12 +1340,12 @@ Description of the business problem, data sources, and expected insights.
 });
 
 /**
- * POST /api/taskmaster/apply-template/:projectName
+ * POST /api/taskmaster/apply-template/:projectId
  * Apply a PRD template to create a new PRD file
  */
-router.post('/apply-template/:projectName', async (req, res) => {
+router.post('/apply-template/:projectId', async (req, res) => {
     try {
-        const { projectName } = req.params;
+        const { projectId } = req.params;
         const { templateId, fileName = 'prd.txt', customizations = {} } = req.body;
 
         if (!templateId) {
@@ -1355,14 +1355,11 @@ router.post('/apply-template/:projectName', async (req, res) => {
             });
         }
 
-        // Get project path
-        let projectPath;
-        try {
-            projectPath = await extractProjectDirectory(projectName);
-        } catch (error) {
+        const projectPath = await resolveProjectPathFromId(projectId);
+        if (!projectPath) {
             return res.status(404).json({
                 error: 'Project not found',
-                message: `Project "${projectName}" does not exist`
+                message: `Project "${projectId}" does not exist`
             });
         }
 
@@ -1401,7 +1398,7 @@ router.post('/apply-template/:projectName', async (req, res) => {
             await fsPromises.writeFile(filePath, content, 'utf8');
 
             res.json({
-                projectName,
+                projectId,
                 projectPath,
                 templateId,
                 templateName: template.name,
diff --git a/server/routes/tests/commands.test.js b/server/routes/tests/commands.test.js
new file mode 100644
index 00000000..ada58dac
--- /dev/null
+++ b/server/routes/tests/commands.test.js
@@ -0,0 +1,82 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { executeModelsCommand } from '../commands.js';
+import { providerModelsService } from '../../modules/providers/services/provider-models.service.js';
+
+test('models command returns available models only for the active provider', async () => {
+  const originalGetProviderModels = providerModelsService.getProviderModels;
+  const originalGetCurrentActiveModel = providerModelsService.getCurrentActiveModel;
+  let getCurrentActiveModelCalls = 0;
+
+  providerModelsService.getProviderModels = async () => ({
+    models: {
+      OPTIONS: [{ value: 'gpt-5.4', label: 'gpt-5.4' }],
+      DEFAULT: 'gpt-5.4',
+    },
+    cache: {
+      updatedAt: '2026-01-01T00:00:00.000Z',
+      expiresAt: '2026-01-04T00:00:00.000Z',
+      source: 'fresh',
+    },
+  });
+  providerModelsService.getCurrentActiveModel = async () => {
+    getCurrentActiveModelCalls += 1;
+    return {
+      model: 'gpt-5.3-codex',
+    };
+  };
+
+  try {
+    const result = await executeModelsCommand([], {
+      provider: 'codex',
+      model: 'gpt-5.4',
+    });
+
+    assert.equal(result.type, 'builtin');
+    assert.equal(result.action, 'models');
+    assert.equal(result.data.current.provider, 'codex');
+    assert.equal(result.data.current.model, 'gpt-5.4');
+    assert.deepEqual(Object.keys(result.data.available), ['codex']);
+    assert.deepEqual(result.data.available.codex, result.data.availableModels);
+    assert.ok(result.data.availableModels.includes('gpt-5.4'));
+    assert.equal(result.data.available.claude, undefined);
+    assert.equal(result.data.available.cursor, undefined);
+    assert.equal(getCurrentActiveModelCalls, 0);
+  } finally {
+    providerModelsService.getProviderModels = originalGetProviderModels;
+    providerModelsService.getCurrentActiveModel = originalGetCurrentActiveModel;
+  }
+});
+
+test('models command falls back to claude for unsupported providers', async () => {
+  const originalGetProviderModels = providerModelsService.getProviderModels;
+  const originalGetCurrentActiveModel = providerModelsService.getCurrentActiveModel;
+
+  providerModelsService.getProviderModels = async () => ({
+    models: {
+      OPTIONS: [{ value: 'default', label: 'Default (recommended)' }],
+      DEFAULT: 'default',
+    },
+    cache: {
+      updatedAt: '2026-01-01T00:00:00.000Z',
+      expiresAt: '2026-01-04T00:00:00.000Z',
+      source: 'fresh',
+    },
+  });
+  providerModelsService.getCurrentActiveModel = async () => ({
+    model: 'default',
+  });
+
+  try {
+    const result = await executeModelsCommand([], {
+      provider: 'unknown-provider',
+    });
+
+    assert.equal(result.data.current.provider, 'claude');
+    assert.deepEqual(Object.keys(result.data.available), ['claude']);
+  } finally {
+    providerModelsService.getProviderModels = originalGetProviderModels;
+    providerModelsService.getCurrentActiveModel = originalGetCurrentActiveModel;
+  }
+});
diff --git a/server/routes/user.js b/server/routes/user.js
index 877cd45b..dcb8ecd7 100644
--- a/server/routes/user.js
+++ b/server/routes/user.js
@@ -1,5 +1,5 @@
 import express from 'express';
-import { userDb } from '../database/db.js';
+import { userDb } from '../modules/database/index.js';
 import { authenticateToken } from '../middleware/auth.js';
 import { getSystemGitConfig } from '../utils/gitConfig.js';
 import { spawn } from 'child_process';
diff --git a/server/services/notification-orchestrator.js b/server/services/notification-orchestrator.js
index d3d47dd6..43a7d058 100644
--- a/server/services/notification-orchestrator.js
+++ b/server/services/notification-orchestrator.js
@@ -1,5 +1,6 @@
 import webPush from 'web-push';
-import { notificationPreferencesDb, pushSubscriptionsDb, sessionNamesDb } from '../database/db.js';
+
+import { notificationPreferencesDb, pushSubscriptionsDb, sessionsDb } from '../modules/database/index.js';
 
 const KIND_TO_PREF_KEY = {
   action_required: 'actionRequired',
@@ -107,7 +108,7 @@ function resolveSessionName(event) {
     return null;
   }
 
-  return normalizeSessionName(sessionNamesDb.getName(event.sessionId, event.provider));
+  return normalizeSessionName(sessionsDb.getSessionName(event.sessionId, event.provider));
 }
 
 function buildPushBody(event) {
diff --git a/server/services/vapid-keys.js b/server/services/vapid-keys.js
index 1abaeba1..8fce37e0 100644
--- a/server/services/vapid-keys.js
+++ b/server/services/vapid-keys.js
@@ -1,7 +1,8 @@
 import webPush from 'web-push';
-import { db } from '../database/db.js';
+import { getConnection } from '../modules/database/connection.js';
 
 let cachedKeys = null;
+const db = getConnection();
 
 function ensureVapidKeys() {
   if (cachedKeys) return cachedKeys;
diff --git a/server/shared/claude-cli-path.test.ts b/server/shared/claude-cli-path.test.ts
new file mode 100644
index 00000000..5d0507d7
--- /dev/null
+++ b/server/shared/claude-cli-path.test.ts
@@ -0,0 +1,61 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  resolveClaudeCodeExecutablePath,
+  type ResolveClaudeCodeExecutablePathDependencies,
+} from '@/shared/claude-cli-path.js';
+
+test('resolveClaudeCodeExecutablePath resolves the npm Claude wrapper to its native exe on Windows', () => {
+  const wrapperDir = 'C:\\nvm4w\\nodejs';
+  const nativePath = `${wrapperDir}\\node_modules\\@anthropic-ai\\claude-code\\bin\\claude.exe`;
+  const execFileSync =
+    (() => `${wrapperDir}\\claude\r\n${wrapperDir}\\claude.cmd\r\n`) as unknown as ResolveClaudeCodeExecutablePathDependencies['execFileSync'];
+  const readFileSync = (() => '') as unknown as ResolveClaudeCodeExecutablePathDependencies['readFileSync'];
+
+  const resolved = resolveClaudeCodeExecutablePath('claude', {
+    platform: 'win32',
+    execFileSync,
+    existsSync: (candidate) => candidate === nativePath,
+    readFileSync,
+  });
+
+  assert.equal(resolved, nativePath);
+});
+
+test('resolveClaudeCodeExecutablePath keeps an explicit JavaScript launcher path unchanged', () => {
+  const scriptPath = 'C:\\tools\\claude.js';
+
+  const resolved = resolveClaudeCodeExecutablePath(scriptPath, {
+    platform: 'win32',
+  });
+
+  assert.equal(resolved, scriptPath);
+});
+
+test('resolveClaudeCodeExecutablePath can parse a wrapper file path containing letters r and n before claude.exe', () => {
+  const wrapperPath = 'C:\\tools\\claude';
+  const nativePath = 'C:\\tools\\custom\\bin\\node_modules\\@anthropic-ai\\claude-code\\bin\\claude.exe';
+  const readFileSync = (() => `exec "$basedir/custom/bin/node_modules/@anthropic-ai/claude-code/bin/claude.exe" "$@"`) as unknown as ResolveClaudeCodeExecutablePathDependencies['readFileSync'];
+
+  const resolved = resolveClaudeCodeExecutablePath(wrapperPath, {
+    platform: 'win32',
+    existsSync: (candidate) => candidate === nativePath,
+    readFileSync,
+  });
+
+  assert.equal(resolved, nativePath);
+});
+
+test('resolveClaudeCodeExecutablePath falls back to the configured command when PATH lookup fails', () => {
+  const execFileSync = (() => {
+    throw new Error('not found');
+  }) as unknown as ResolveClaudeCodeExecutablePathDependencies['execFileSync'];
+
+  const resolved = resolveClaudeCodeExecutablePath('claude', {
+    platform: 'win32',
+    execFileSync,
+  });
+
+  assert.equal(resolved, 'claude');
+});
diff --git a/server/shared/claude-cli-path.ts b/server/shared/claude-cli-path.ts
new file mode 100644
index 00000000..d917144e
--- /dev/null
+++ b/server/shared/claude-cli-path.ts
@@ -0,0 +1,139 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DEFAULT_CLAUDE_COMMAND = 'claude';
+const CLAUDE_SCRIPT_EXTENSIONS = new Set(['.cjs', '.js', '.jsx', '.mjs', '.ts', '.tsx']);
+const CLAUDE_WRAPPER_SEGMENTS = ['node_modules', '@anthropic-ai', 'claude-code', 'bin', 'claude.exe'] as const;
+
+export type ResolveClaudeCodeExecutablePathDependencies = {
+  execFileSync?: typeof execFileSync;
+  existsSync?: typeof fs.existsSync;
+  platform?: NodeJS.Platform;
+  readFileSync?: typeof fs.readFileSync;
+};
+
+function getPathApi(platform: NodeJS.Platform) {
+  return platform === 'win32' ? path.win32 : path;
+}
+
+function stripWrappingQuotes(value: string): string {
+  const trimmed = value.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+function isPathLike(value: string): boolean {
+  return value.includes('/') || value.includes('\\');
+}
+
+function resolveClaudeWrapperBinary(
+  wrapperPath: string,
+  deps: Required<ResolveClaudeCodeExecutablePathDependencies>,
+): string | null {
+  const pathApi = getPathApi(deps.platform);
+  const directCandidate = pathApi.resolve(pathApi.dirname(wrapperPath), ...CLAUDE_WRAPPER_SEGMENTS);
+
+  if (deps.existsSync(directCandidate)) {
+    return directCandidate;
+  }
+
+  let content: string;
+  try {
+    content = deps.readFileSync(wrapperPath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  const matches = content.matchAll(/["']([^"'\\\r\n]*claude\.exe)["']/gi);
+  for (const match of matches) {
+    const rawTarget = match[1]
+      .replace(/^\$basedir[\\/]/i, '')
+      .replace(/^%dp0%[\\/]/i, '')
+      .replace(/^%~dp0[\\/]/i, '');
+    const normalizedTarget = rawTarget.replace(/[\\/]/g, pathApi.sep);
+    const candidate = pathApi.isAbsolute(normalizedTarget)
+      ? normalizedTarget
+      : pathApi.resolve(pathApi.dirname(wrapperPath), normalizedTarget);
+
+    if (deps.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function resolveWindowsClaudeExecutablePath(
+  configuredPath: string,
+  deps: Required<ResolveClaudeCodeExecutablePathDependencies>,
+): string {
+  const pathApi = getPathApi(deps.platform);
+  const extension = pathApi.extname(configuredPath).toLowerCase();
+  const explicitPath = isPathLike(configuredPath) || pathApi.isAbsolute(configuredPath);
+
+  if (CLAUDE_SCRIPT_EXTENSIONS.has(extension)) {
+    return configuredPath;
+  }
+
+  if (explicitPath && extension === '.exe') {
+    return configuredPath;
+  }
+
+  if (explicitPath) {
+    return resolveClaudeWrapperBinary(configuredPath, deps) ?? configuredPath;
+  }
+
+  try {
+    const stdout = deps.execFileSync('where.exe', [configuredPath], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+    });
+    const candidates = stdout
+      .split(/\r?\n/)
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+
+    for (const candidate of candidates) {
+      if (pathApi.extname(candidate).toLowerCase() === '.exe') {
+        return candidate;
+      }
+    }
+
+    for (const candidate of candidates) {
+      const resolved = resolveClaudeWrapperBinary(candidate, deps);
+      if (resolved) {
+        return resolved;
+      }
+    }
+  } catch {
+    return configuredPath;
+  }
+
+  return configuredPath;
+}
+
+export function resolveClaudeCodeExecutablePath(
+  configuredPath: string | undefined = process.env.CLAUDE_CLI_PATH,
+  dependencies: ResolveClaudeCodeExecutablePathDependencies = {},
+): string {
+  const deps: Required<ResolveClaudeCodeExecutablePathDependencies> = {
+    execFileSync: dependencies.execFileSync ?? execFileSync,
+    existsSync: dependencies.existsSync ?? fs.existsSync,
+    platform: dependencies.platform ?? process.platform,
+    readFileSync: dependencies.readFileSync ?? fs.readFileSync,
+  };
+
+  const normalizedPath = stripWrappingQuotes(configuredPath || DEFAULT_CLAUDE_COMMAND);
+  if (deps.platform !== 'win32') {
+    return normalizedPath;
+  }
+
+  return resolveWindowsClaudeExecutablePath(normalizedPath, deps);
+}
diff --git a/server/utils/frontmatter.js b/server/shared/frontmatter.ts
similarity index 81%
rename from server/utils/frontmatter.js
rename to server/shared/frontmatter.ts
index 0a4b1eb8..9eb7ddd8 100644
--- a/server/utils/frontmatter.js
+++ b/server/shared/frontmatter.ts
@@ -9,10 +9,10 @@ const frontmatterOptions = {
   engines: {
     js: disabledFrontmatterEngine,
     javascript: disabledFrontmatterEngine,
-    json: disabledFrontmatterEngine
-  }
+    json: disabledFrontmatterEngine,
+  },
 };
 
-export function parseFrontmatter(content) {
+export function parseFrontMatter(content: string) {
   return matter(content, frontmatterOptions);
 }
diff --git a/server/shared/interfaces.ts b/server/shared/interfaces.ts
index 954b38a3..1864fd02 100644
--- a/server/shared/interfaces.ts
+++ b/server/shared/interfaces.ts
@@ -4,11 +4,18 @@ import type {
   LLMProvider,
   McpScope,
   NormalizedMessage,
+  ProviderSkill,
+  ProviderSkillListOptions,
   ProviderAuthStatus,
+  ProviderChangeActiveModelInput,
+  ProviderCurrentActiveModel,
+  ProviderModelsDefinition,
   ProviderMcpServer,
+  ProviderSessionActiveModelChange,
   UpsertProviderMcpServerInput,
 } from '@/shared/types.js';
 
+//----------------- PROVIDER CONTRACT INTERFACES ------------
 /**
  * Main provider contract for CLI and SDK integrations.
  *
@@ -17,14 +24,61 @@ import type {
  */
 export interface IProvider {
   readonly id: LLMProvider;
+  readonly models: IProviderModels;
   readonly mcp: IProviderMcp;
   readonly auth: IProviderAuth;
+  readonly skills: IProviderSkills;
   readonly sessions: IProviderSessions;
+  readonly sessionSynchronizer: IProviderSessionSynchronizer;
 }
 
+// ---------------------------
+//----------------- PROVIDER MODEL INTERFACE ------------
+/**
+ * Model catalog contract for one provider.
+ *
+ * Implementations are responsible for resolving the provider's currently
+ * supported models and converting them into the shared
+ * `ProviderModelsDefinition` shape used by backend routes and frontend model
+ * pickers. The `DEFAULT` field should be the most appropriate default selection
+ * for that provider at the time the catalog is read.
+ */
+export interface IProviderModels {
+  /**
+   * Returns the provider's currently supported model catalog.
+   */
+  getSupportedModels(): Promise<ProviderModelsDefinition>;
 
+  /**
+   * Returns the currently active model for one session or provider runtime.
+   *
+   * Implementations must use the provider-specific lookup mechanism approved
+   * for that provider and fall back only to the provider catalog default when
+   * no active model can be resolved.
+   */
+  getCurrentActiveModel(sessionId?: string): Promise<ProviderCurrentActiveModel>;
+
+  /**
+   * Persists a session-scoped model override that the next resumed turn should
+   * honor for this provider.
+   *
+   * This does not require the provider to mutate an already running remote
+   * session in-place. Instead, adapters store the user's explicit model choice
+   * so the backend resume path can add the correct provider-native model option
+   * on the next CLI/SDK invocation for the same session.
+   */
+  changeActiveModel(
+    input: ProviderChangeActiveModelInput,
+  ): Promise<ProviderSessionActiveModelChange>;
+}
+
+// ---------------------------
+//----------------- PROVIDER AUTH INTERFACE ------------
 /**
  * Auth contract for one provider.
+ *
+ * Implementations should return a complete installation/authentication status
+ * without throwing for normal "not installed" or "not authenticated" states.
  */
 export interface IProviderAuth {
   /**
@@ -33,8 +87,29 @@ export interface IProviderAuth {
   getStatus(): Promise<ProviderAuthStatus>;
 }
 
+// ---------------------------
+//----------------- PROVIDER SKILLS INTERFACE ------------
+/**
+ * Skills contract for one provider.
+ *
+ * Implementations discover provider-native skill markdown locations and return
+ * normalized skill records with the exact command syntax expected by that
+ * provider. Each skill is read from a `SKILL.md` file under its skill directory.
+ */
+export interface IProviderSkills {
+  /**
+   * Lists all skills visible to this provider for the optional workspace.
+   */
+  listSkills(options?: ProviderSkillListOptions): Promise<ProviderSkill[]>;
+}
+
+// ---------------------------
+//----------------- PROVIDER MCP INTERFACE ------------
 /**
  * MCP contract for one provider.
+ *
+ * Implementations must map provider-native MCP config formats to shared
+ * `ProviderMcpServer` records used by routes and frontend state.
  */
 export interface IProviderMcp {
   listServers(options?: { workspacePath?: string }): Promise<Record<McpScope, ProviderMcpServer[]>>;
@@ -45,10 +120,37 @@ export interface IProviderMcp {
   ): Promise<{ removed: boolean; provider: LLMProvider; name: string; scope: McpScope }>;
 }
 
+// ---------------------------
+//----------------- PROVIDER SESSION INTERFACE ------------
 /**
  * Session/history contract for one provider.
+ *
+ * Implementations normalize provider-specific events and message history into
+ * shared transport shapes consumed by API routes and realtime streams.
  */
 export interface IProviderSessions {
   normalizeMessage(raw: unknown, sessionId: string | null): NormalizedMessage[];
   fetchHistory(sessionId: string, options?: FetchHistoryOptions): Promise<FetchHistoryResult>;
 }
+
+// ---------------------------
+//----------------- PROVIDER SESSION SYNCHRONIZER INTERFACE ------------
+/**
+ * Session indexing contract for one provider.
+ *
+ * Implementations scan provider-specific session artifacts on disk and upsert
+ * normalized session metadata into the database. The service layer uses this
+ * interface for both full rescans and single-file incremental sync triggered
+ * by filesystem watcher events.
+ */
+export interface IProviderSessionSynchronizer {
+  /**
+   * Scans provider session artifacts and upserts discovered sessions into DB.
+   */
+  synchronize(since?: Date): Promise<number>;
+
+  /**
+   * Parses and upserts one provider artifact file without running a full scan.
+   */
+  synchronizeFile(filePath: string): Promise<string | null>;
+}
diff --git a/server/shared/types.ts b/server/shared/types.ts
index 7fe545c5..dbcef5d4 100644
--- a/server/shared/types.ts
+++ b/server/shared/types.ts
@@ -1,18 +1,164 @@
-// -------------- HTTP API response shapes for the server, shared across modules --------------
+import type { IncomingMessage } from 'node:http';
 
+//----------------- HTTP RESPONSE SHAPES ------------
+/**
+ * Canonical success envelope used by backend APIs that return a structured payload.
+ *
+ * Use this for route handlers that need a stable `success/data` shape so frontend
+ * consumers can parse responses consistently across endpoints.
+ */
 export type ApiSuccessShape<TData = unknown> = {
   success: true;
   data: TData;
 };
 
+/**
+ * Generic plain-object record used when parsing loosely typed JSON payloads.
+ *
+ * Use this only after runtime shape checks, not as a replacement for validated
+ * domain models.
+ */
 export type AnyRecord = Record<string, any>;
 
-// ---------------------------------------------------------------------------------------------
+// ---------------------------
+//----------------- WEBSOCKET TRANSPORT TYPES ------------
+/**
+ * Minimal websocket client contract used by backend broadcaster services.
+ *
+ * Any transport object added to `connectedClients` must implement these two
+ * members so shared services can safely send JSON strings and check whether the
+ * socket is still open before broadcasting.
+ */
+export type RealtimeClientConnection = {
+  readyState: number;
+  send(data: string): void;
+};
 
-export type LLMProvider = 'claude' | 'codex' | 'gemini' | 'cursor';
+/**
+ * Authenticated user payload attached to websocket upgrade requests.
+ *
+ * Platform and OSS auth flows currently use either `id` or `userId`; both are
+ * represented here so websocket handlers can resolve a stable writer user id.
+ */
+export type AuthenticatedWebSocketUser = {
+  id?: string | number;
+  userId?: string | number;
+  username?: string;
+  [key: string]: unknown;
+};
 
-// ---------------------------------------------------------------------------------------------
+/**
+ * HTTP upgrade request shape after websocket authentication succeeds.
+ *
+ * `verifyClient` populates `request.user` with the authenticated payload, and
+ * downstream websocket handlers rely on this extended request type.
+ */
+export type AuthenticatedWebSocketRequest = IncomingMessage & {
+  user?: AuthenticatedWebSocketUser;
+};
 
+// ---------------------------
+//----------------- PROVIDER MESSAGE MODEL ------------
+/**
+ * Providers supported by the unified server runtime.
+ *
+ * Use this as the source of truth whenever a function or payload needs to identify
+ * a specific LLM integration.
+ */
+export type LLMProvider = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode';
+
+/**
+ * One selectable model row (matches the documentation `public/modelConstants.js` option shape).
+ */
+export type ProviderModelOption = {
+  value: string;
+  label: string;
+  description?: string;
+};
+
+/**
+ * Provider model catalog returned by `GET /api/providers/:provider/models`.
+ */
+export type ProviderModelsDefinition = {
+  OPTIONS: ProviderModelOption[];
+  DEFAULT: string;
+};
+
+/**
+ * Cache metadata returned alongside one provider model catalog.
+ *
+ * `updatedAt` is when the current cached snapshot was last refreshed from the
+ * provider itself. `expiresAt` is the backend cache expiry timestamp, and
+ * `source` tells callers whether the current response came from in-memory cache,
+ * persisted disk cache, or a fresh provider fetch.
+ */
+export type ProviderModelsCacheInfo = {
+  updatedAt: string;
+  expiresAt: string;
+  source: 'memory' | 'disk' | 'fresh';
+};
+
+/**
+ * Full provider model lookup result returned by the backend service layer.
+ *
+ * Use this shape when a caller needs both the selectable model catalog and the
+ * cache metadata that explains how current the catalog is.
+ */
+export type ProviderModelsResult = {
+  models: ProviderModelsDefinition;
+  cache: ProviderModelsCacheInfo;
+};
+
+// ---------------------------
+//----------------- PROVIDER ACTIVE MODEL TYPES ------------
+/**
+ * Provider-neutral result for the model that is actively driving a session or
+ * provider runtime at the time of lookup.
+ *
+ * `model` must always be populated. Provider adapters should use the
+ * provider-specific lookup method requested by the caller, and only fall back
+ * to the provider catalog `DEFAULT` value when the active model cannot be read.
+ */
+export type ProviderCurrentActiveModel = {
+  model: string;
+};
+
+/**
+ * Input payload used when one session needs to use a different model on its
+ * next resumed turn.
+ *
+ * This is a backend-owned session override, not a claim that the provider has
+ * already switched the currently running session in-place. Provider adapters
+ * persist this request so the next CLI/SDK resume can inject the chosen model
+ * using the provider-specific mechanism supported by that runtime.
+ */
+export type ProviderChangeActiveModelInput = {
+  sessionId: string;
+  model: string;
+};
+
+/**
+ * Provider-neutral session model-change state.
+ *
+ * `supported` indicates whether the provider adapter supports the app's
+ * session-scoped resume override flow. `changed` is the persisted boolean the
+ * resume layer checks before forcing a model on the next resumed turn. When
+ * `changed` is `false`, `model` is `null` and the runtime should use the
+ * normal request/default model selection path.
+ */
+export type ProviderSessionActiveModelChange = {
+  provider: LLMProvider;
+  sessionId: string;
+  supported: boolean;
+  changed: boolean;
+  model: string | null;
+};
+
+/**
+ * Message/event variants emitted by provider adapters and normalized transports.
+ *
+ * Keep this union in sync with event kinds produced by provider session adapters.
+ */
 export type MessageKind =
   | 'text'
   | 'tool_use'
@@ -30,11 +176,10 @@ export type MessageKind =
   | 'task_notification';
 
 /**
- * Provider-neutral message event emitted over REST and realtime transports.
+ * Provider-neutral message envelope used in REST responses and realtime channels.
  *
- * Providers all produce their own native SDK/CLI event shapes, so this type keeps
- * the common envelope strict while allowing provider-specific details to ride
- * along as optional properties.
+ * Every provider-specific message must be converted into this shape before being
+ * emitted outside provider-specific modules.
  */
 export type NormalizedMessage = {
   id: string;
@@ -44,6 +189,21 @@ export type NormalizedMessage = {
   kind: MessageKind;
   role?: 'user' | 'assistant';
   content?: string;
+  /**
+   * Optional display-oriented metadata used by providers that need to expose
+   * richer transcript artifacts without introducing a brand-new message kind.
+   *
+   * Current Claude usage:
+   * - local slash commands expose parsed command fields
+   * - compact summaries are flagged so the UI can treat them differently later
+   */
+  displayText?: string;
+  commandName?: string;
+  commandMessage?: string;
+  commandArgs?: string;
+  isLocalCommand?: boolean;
+  isLocalCommandStdout?: boolean;
+  isCompactSummary?: boolean;
   images?: unknown;
   toolName?: string;
   toolInput?: unknown;
@@ -73,21 +233,21 @@ export type NormalizedMessage = {
 };
 
 /**
- * Pagination and provider lookup options for reading persisted session history.
+ * Shared options used to fetch historical provider messages.
+ *
+ * Consumers should pass provider-specific lookup hints (`projectPath`) only
+ * when the selected provider requires them.
  */
 export type FetchHistoryOptions = {
-  /** Claude project folder name. Required by Claude history lookup. */
-  projectName?: string;
-  /** Absolute workspace path. Required by Cursor to compute its chat hash. */
   projectPath?: string;
-  /** Page size. `null` means all messages. */
   limit?: number | null;
-  /** Pagination offset from the newest messages. */
   offset?: number;
 };
 
 /**
- * Provider-neutral history result returned by the unified messages endpoint.
+ * Standardized response payload returned from provider history readers.
+ *
+ * Use this as the contract for APIs that return paginated conversation history.
  */
 export type FetchHistoryResult = {
   messages: NormalizedMessage[];
@@ -98,21 +258,103 @@ export type FetchHistoryResult = {
   tokenUsage?: unknown;
 };
 
-// ---------------------------------------------------------------------------------------------
+// ---------------------------
+//----------------- PROVIDER SKILL TYPES ------------
+/**
+ * Scope where a provider skill definition was discovered.
+ *
+ * Provider skill adapters should use this to describe the origin of each
+ * skill markdown file without leaking provider-specific folder names into route
+ * contracts. `repo` is used for Codex repository lookup locations, while
+ * `project` is used for providers that treat workspace-local skills as project
+ * scoped.
+ */
+export type ProviderSkillScope = 'user' | 'project' | 'plugin' | 'repo' | 'admin' | 'system';
 
+/**
+ * Shared input accepted by provider skill listing operations.
+ *
+ * Routes pass `workspacePath` when a caller wants project/repository skills for
+ * a specific folder. Providers should fall back to the backend process cwd when
+ * this option is omitted.
+ */
+export type ProviderSkillListOptions = {
+  workspacePath?: string;
+};
+
+/**
+ * Normalized skill record returned by provider skill adapters.
+ *
+ * The `command` value is the exact invocation text the selected provider expects
+ * for this skill. Claude plugin skills use a namespaced command such as
+ * `/plugin-name:skill-name`, while Codex skills use the `$skill-name` form.
+ * `sourcePath` points to the skill markdown file that produced the record so
+ * callers can distinguish duplicate skill names across scopes.
+ */
+export type ProviderSkill = {
+  provider: LLMProvider;
+  name: string;
+  description: string;
+  command: string;
+  scope: ProviderSkillScope;
+  sourcePath: string;
+  pluginName?: string;
+  pluginId?: string;
+};
+
+/**
+ * Internal source descriptor consumed by shared provider skill discovery logic.
+ *
+ * Concrete provider adapters build these records from their native lookup rules.
+ * The shared skills provider then scans `rootDir` for child skill markdown files
+ * and uses `commandForSkill` or `commandPrefix` to produce the provider-specific
+ * invocation command. Set `recursive` only when a provider stores skills under
+ * arbitrary nested folders below the source root.
+ */
+export type ProviderSkillSource = {
+  scope: ProviderSkillScope;
+  rootDir: string;
+  recursive?: boolean;
+  commandPrefix?: '/' | '$';
+  commandForSkill?: (skillName: string) => string;
+  pluginName?: string;
+  pluginId?: string;
+};
+
+// ---------------------------
+//----------------- SHARED ERROR TYPES ------------
+/**
+ * Optional metadata used when constructing application-level errors.
+ *
+ * `statusCode` should reflect the HTTP response status, while `code` identifies
+ * the stable machine-readable error category.
+ */
 export type AppErrorOptions = {
   code?: string;
   statusCode?: number;
   details?: unknown;
 };
 
-// -------------------- MCP related shared types --------------------
+// ---------------------------
+//----------------- MCP TYPES ------------
+/**
+ * Scope where an MCP server definition is stored and resolved.
+ *
+ * `user` is global for a user account, `local` is provider-local, and `project`
+ * is tied to a specific project path.
+ */
 export type McpScope = 'user' | 'local' | 'project';
 
+/**
+ * Transport protocol used by an MCP server definition.
+ */
 export type McpTransport = 'stdio' | 'http' | 'sse';
 
 /**
- * Provider MCP server descriptor normalized for frontend consumption.
+ * Normalized MCP server model exposed to frontend and route handlers.
+ *
+ * Provider adapters should map provider-native config to this structure before
+ * returning results.
  */
 export type ProviderMcpServer = {
   provider: LLMProvider;
@@ -131,7 +373,10 @@ export type ProviderMcpServer = {
 };
 
 /**
- * Shared payload shape for MCP server create/update operations.
+ * Payload for create/update MCP server operations.
+ *
+ * Routes and services should accept this type, validate it, and then persist it
+ * through provider-specific MCP repositories.
  */
 export type UpsertProviderMcpServerInput = {
   name: string;
@@ -149,18 +394,13 @@ export type UpsertProviderMcpServerInput = {
   envHttpHeaders?: Record<string, string>;
 };
 
-// ---------------------------------------------------------------------------------------------
-
-// -------------------- Provider auth status types --------------------
+// ---------------------------
+//----------------- PROVIDER AUTH TYPES ------------
 /**
- * Result of a provider status check (installation + authentication).
+ * Authentication status result returned by provider health checks.
  *
- * installed - Whether the provider's CLI/SDK is available
- * provider - Provider id the status belongs to
- * authenticated - Whether valid credentials exist
- * email - User email or auth method identifier
- * method - Auth method (e.g. 'api_key', 'credentials_file')
- * [error] - Error message if not installed or not authenticated
+ * This shape is consumed by settings/status endpoints to report installation and
+ * credential state for each provider.
  */
 export type ProviderAuthStatus = {
   installed: boolean;
@@ -170,3 +410,83 @@ export type ProviderAuthStatus = {
   method: string | null;
   error?: string;
 };
+
+// ---------------------------
+//----------------- SHARED DATABASE CREDENTIAL TYPES ------------
+/**
+ * Safe credential view returned by credential listing APIs.
+ *
+ * This intentionally excludes the raw credential secret while still exposing
+ * metadata needed for UI rendering and management operations.
+ */
+export type CredentialPublicRow = {
+  id: number;
+  credential_name: string;
+  credential_type: string;
+  description: string | null;
+  created_at: string;
+  is_active: number;
+};
+
+/**
+ * Result returned after creating a credential record.
+ *
+ * Use this return shape when callers need the created id and display metadata,
+ * but must never receive the stored secret value.
+ */
+export type CreateCredentialResult = {
+  id: number | bigint;
+  credentialName: string;
+  credentialType: string;
+};
+
+// ---------------------------
+//----------------- PROJECT PERSISTENCE TYPES ------------
+/**
+ * Canonical project row shape returned by the projects repository.
+ *
+ * Use this type whenever backend services need to pass around one database
+ * project record without leaking raw SQL row typing across modules.
+ */
+export type ProjectRepositoryRow = {
+  project_id: string;
+  project_path: string;
+  custom_project_name: string | null;
+  isStarred: number;
+  isArchived: number;
+};
+
+/**
+ * Result category returned by `projectsDb.createProjectPath`.
+ *
+ * `created` means a fresh row was inserted, `reactivated_archived` means an
+ * existing archived path was accepted and updated, and `active_conflict` means
+ * an already-active path blocked project creation.
+ */
+export type CreateProjectPathOutcome =
+  | 'created'
+  | 'reactivated_archived'
+  | 'active_conflict';
+
+/**
+ * Structured result returned by project-path upsert operations.
+ *
+ * Services should use this result to decide whether a request succeeded,
+ * should return a conflict, or needs follow-up retrieval of row metadata.
+ */
+export type CreateProjectPathResult = {
+  outcome: CreateProjectPathOutcome;
+  project: ProjectRepositoryRow | null;
+};
+
+/**
+ * Validation result for user-supplied workspace/project paths.
+ *
+ * `resolvedPath` is present only when validation succeeds. `error` is present
+ * only when validation fails and is suitable for user-facing diagnostics.
+ */
+export type WorkspacePathValidationResult = {
+  valid: boolean;
+  resolvedPath?: string;
+  error?: string;
+};
diff --git a/server/shared/utils.ts b/server/shared/utils.ts
index de6aed56..821489c5 100644
--- a/server/shared/utils.ts
+++ b/server/shared/utils.ts
@@ -1,17 +1,45 @@
-
 import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import fs from 'node:fs';
+import {
+  access,
+  lstat,
+  mkdir,
+  readFile,
+  readdir,
+  readlink,
+  realpath,
+  stat,
+  writeFile,
+} from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
+import readline from 'node:readline';
 
 import type { NextFunction, Request, RequestHandler, Response } from 'express';
 
+import { parseFrontMatter } from '@/shared/frontmatter.js';
 import type {
   AnyRecord,
   ApiSuccessShape,
   AppErrorOptions,
+  LLMProvider,
   NormalizedMessage,
+  ProviderChangeActiveModelInput,
+  ProviderCurrentActiveModel,
+  ProviderModelsDefinition,
+  ProviderSessionActiveModelChange,
+  ProviderSkillSource,
+  WorkspacePathValidationResult,
 } from '@/shared/types.js';
 
+//----------------- NORMALIZED MESSAGE HELPER INPUT TYPES ------------
+/**
+ * Input payload accepted by `createNormalizedMessage`.
+ *
+ * Callers provide provider-specific fields plus the required `kind/provider`
+ * pair; this helper fills missing envelope fields (`id`, `sessionId`,
+ * `timestamp`) in a consistent way.
+ */
 type NormalizedMessageInput =
   {
     kind: NormalizedMessage['kind'];
@@ -21,6 +49,14 @@ type NormalizedMessageInput =
     timestamp?: string | null;
   } & Record<string, unknown>;
 
+// ---------------------------
+//----------------- HTTP HANDLER UTILITIES ------------
+/**
+ * Wraps arbitrary data in the standard API success envelope.
+ *
+ * Use this helper in route handlers to keep successful JSON responses consistent
+ * across endpoints.
+ */
 export function createApiSuccessResponse<TData>(
   data: TData,
 ): ApiSuccessShape<TData> {
@@ -30,6 +66,12 @@ export function createApiSuccessResponse<TData>(
   };
 }
 
+/**
+ * Converts an async Express handler into a standard `RequestHandler` and routes
+ * rejected promises to Express error middleware.
+ *
+ * Use this to avoid repeating `try/catch(next)` in every async route.
+ */
 export function asyncHandler(
   handler: (req: Request, res: Response, next: NextFunction) => Promise<unknown>
 ): RequestHandler {
@@ -38,7 +80,14 @@ export function asyncHandler(
   };
 }
 
-// --------- Global app error class for consistent error handling across the server ---------
+// ---------------------------
+//----------------- SHARED ERROR UTILITIES ------------
+/**
+ * Shared application error with HTTP status and machine-readable code metadata.
+ *
+ * Throw this from service/route layers when the caller should receive a
+ * controlled error response rather than a generic 500.
+ */
 export class AppError extends Error {
   readonly code: string;
   readonly statusCode: number;
@@ -53,9 +102,226 @@ export class AppError extends Error {
   }
 }
 
-// -------------------------------------------------------------------------------------------
+// ---------------------------
+//----------------- WORKSPACE PATH VALIDATION UTILITIES ------------
+/**
+ * Root directory that all workspace/project paths must stay under.
+ *
+ * This is resolved from `WORKSPACES_ROOT` when configured; otherwise it falls
+ * back to the current user's home directory.
+ */
+export const WORKSPACES_ROOT = process.env.WORKSPACES_ROOT || os.homedir();
 
-// ------------------------ Normalized provider message helpers ------------------------
+/**
+ * System-critical paths that must never be used as workspace roots.
+ *
+ * The validation helper blocks these values directly and also blocks paths
+ * nested under them (with explicit allow-list exceptions where necessary).
+ */
+export const FORBIDDEN_WORKSPACE_PATHS = [
+  // Unix
+  '/',
+  '/etc',
+  '/bin',
+  '/sbin',
+  '/usr',
+  '/dev',
+  '/proc',
+  '/sys',
+  '/var',
+  '/boot',
+  '/root',
+  '/lib',
+  '/lib64',
+  '/opt',
+  '/tmp',
+  '/run',
+  // Windows
+  'C:\\Windows',
+  'C:\\Program Files',
+  'C:\\Program Files (x86)',
+  'C:\\ProgramData',
+  'C:\\System Volume Information',
+  'C:\\$Recycle.Bin',
+];
+
+function stripWindowsLongPathPrefix(inputPath: string): string {
+  if (inputPath.startsWith('\\\\?\\UNC\\')) {
+    return `\\\\${inputPath.slice('\\\\?\\UNC\\'.length)}`;
+  }
+
+  if (inputPath.startsWith('\\\\?\\')) {
+    return inputPath.slice('\\\\?\\'.length);
+  }
+
+  return inputPath;
+}
+
+function shouldUseWindowsPathNormalization(inputPath: string): boolean {
+  if (process.platform === 'win32') {
+    return true;
+  }
+
+  return inputPath.startsWith('\\\\') || /^[a-zA-Z]:([\\/]|$)/.test(inputPath);
+}
+
+/**
+ * Canonicalizes project/workspace paths for stable DB keys and comparisons.
+ *
+ * Normalization rules:
+ * - trim whitespace
+ * - strip Windows long-path prefixes (`\\?\` and `\\?\UNC\`)
+ * - normalize path separators and dot segments
+ * - trim trailing separators except for filesystem roots
+ */
+export function normalizeProjectPath(inputPath: string): string {
+  if (typeof inputPath !== 'string') {
+    return '';
+  }
+
+  const trimmed = inputPath.trim();
+  if (!trimmed) {
+    return '';
+  }
+
+  const withoutLongPrefix = stripWindowsLongPathPrefix(trimmed);
+  const useWindowsPathRules = shouldUseWindowsPathNormalization(withoutLongPrefix);
+  const normalized = useWindowsPathRules
+    ? path.win32.normalize(withoutLongPrefix)
+    : path.posix.normalize(withoutLongPrefix);
+
+  if (!normalized) {
+    return '';
+  }
+
+  const parser = useWindowsPathRules ? path.win32 : path.posix;
+  const root = parser.parse(normalized).root;
+  if (normalized === root) {
+    return normalized;
+  }
+
+  return normalized.replace(/[\\/]+$/, '');
+}
+
+/**
+ * Validates that a user-supplied workspace path is safe to use.
+ *
+ * Call this before any filesystem mutation that creates or registers projects.
+ * The function resolves symlinks, enforces `WORKSPACES_ROOT` containment, and
+ * blocks known system directories.
+ */
+export async function validateWorkspacePath(requestedPath: string): Promise<WorkspacePathValidationResult> {
+  try {
+    const normalizedRequestedPath = normalizeProjectPath(requestedPath);
+    if (!normalizedRequestedPath) {
+      return {
+        valid: false,
+        error: 'Workspace path is required',
+      };
+    }
+
+    const absolutePath = path.resolve(normalizedRequestedPath);
+    const normalizedPath = normalizeProjectPath(absolutePath);
+
+    if (FORBIDDEN_WORKSPACE_PATHS.includes(normalizedPath) || normalizedPath === '/') {
+      return {
+        valid: false,
+        error: 'Cannot use system-critical directories as workspace locations',
+      };
+    }
+
+    for (const forbiddenPath of FORBIDDEN_WORKSPACE_PATHS) {
+      const normalizedForbiddenPath = normalizeProjectPath(forbiddenPath);
+      if (
+        normalizedPath === normalizedForbiddenPath
+        || normalizedPath.startsWith(`${normalizedForbiddenPath}${path.sep}`)
+      ) {
+        // Allow specific user-writable folders under /var.
+        if (
+          normalizedForbiddenPath === '/var'
+          && (normalizedPath.startsWith('/var/tmp') || normalizedPath.startsWith('/var/folders'))
+        ) {
+          continue;
+        }
+
+        return {
+          valid: false,
+          error: `Cannot create workspace in system directory: ${forbiddenPath}`,
+        };
+      }
+    }
+
+    let resolvedPath = normalizeProjectPath(absolutePath);
+    try {
+      await access(absolutePath);
+      resolvedPath = normalizeProjectPath(await realpath(absolutePath));
+    } catch (error) {
+      const fileError = error as NodeJS.ErrnoException;
+      if (fileError.code !== 'ENOENT') {
+        throw fileError;
+      }
+
+      const parentPath = path.dirname(absolutePath);
+      try {
+        const parentRealPath = await realpath(parentPath);
+        resolvedPath = normalizeProjectPath(path.join(parentRealPath, path.basename(absolutePath)));
+      } catch (parentError) {
+        const parentFileError = parentError as NodeJS.ErrnoException;
+        if (parentFileError.code !== 'ENOENT') {
+          throw parentFileError;
+        }
+      }
+    }
+
+    const resolvedWorkspaceRoot = normalizeProjectPath(await realpath(WORKSPACES_ROOT));
+    if (
+      !resolvedPath.startsWith(`${resolvedWorkspaceRoot}${path.sep}`)
+      && resolvedPath !== resolvedWorkspaceRoot
+    ) {
+      return {
+        valid: false,
+        error: `Workspace path must be within the allowed workspace root: ${WORKSPACES_ROOT}`,
+      };
+    }
+
+    try {
+      await access(absolutePath);
+      const pathStats = await lstat(absolutePath);
+      if (pathStats.isSymbolicLink()) {
+        const symlinkTarget = await readlink(absolutePath);
+        const resolvedSymlinkPath = path.resolve(path.dirname(absolutePath), symlinkTarget);
+        const realSymlinkPath = await realpath(resolvedSymlinkPath);
+        if (
+          !realSymlinkPath.startsWith(`${resolvedWorkspaceRoot}${path.sep}`)
+          && realSymlinkPath !== resolvedWorkspaceRoot
+        ) {
+          return {
+            valid: false,
+            error: 'Symlink target is outside the allowed workspace root',
+          };
+        }
+      }
+    } catch (error) {
+      const fileError = error as NodeJS.ErrnoException;
+      if (fileError.code !== 'ENOENT') {
+        throw fileError;
+      }
+    }
+
+    return {
+      valid: true,
+      resolvedPath,
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      error: `Path validation failed: ${(error as Error).message}`,
+    };
+  }
+}
+
+// ---------------------------
+//----------------- NORMALIZED PROVIDER MESSAGE UTILITIES ------------
 /**
  * Generates a stable unique id for normalized provider messages.
  */
@@ -80,9 +346,8 @@ export function createNormalizedMessage(fields: NormalizedMessageInput): Normali
   };
 }
 
-// -------------------------------------------------------------------------------------------
-
-// ------------------------ The following are mainly for provider MCP runtimes ------------------------
+// ---------------------------
+//----------------- MCP CONFIG PARSING UTILITIES ------------
 /**
  * Safely narrows an unknown value to a plain object record.
  *
@@ -154,6 +419,287 @@ export const readStringRecord = (value: unknown): Record<string, string> | undef
   return Object.keys(normalized).length > 0 ? normalized : undefined;
 };
 
+// ---------------------------
+//----------------- PROVIDER MODEL LOOKUP UTILITIES ------------
+/**
+ * Builds the standard "default current model" result used when a provider
+ * cannot resolve a session-backed active model.
+ *
+ * Provider model adapters should call this after loading their supported model
+ * catalog so the fallback stays aligned with the provider's current `DEFAULT`
+ * selection instead of drifting to a hard-coded duplicate.
+ */
+export function buildDefaultProviderCurrentActiveModel(
+  models: ProviderModelsDefinition,
+): ProviderCurrentActiveModel {
+  return {
+    model: models.DEFAULT,
+  };
+}
+
+// ---------------------------
+//----------------- PROVIDER SESSION MODEL CHANGE UTILITIES ------------
+type ProviderSessionActiveModelChangeCacheEntry = ProviderSessionActiveModelChange & {
+  updatedAt: string;
+};
+
+type ProviderSessionActiveModelChangeCacheFile = {
+  version: number;
+  entries: Record<string, ProviderSessionActiveModelChangeCacheEntry>;
+};
+
+const PROVIDER_SESSION_ACTIVE_MODEL_CHANGE_CACHE_VERSION = 1;
+
+/**
+ * Resolves the backend-owned cache file used for session-scoped resume model
+ * overrides.
+ *
+ * The file lives under `~/.cloudcli` because these overrides are an application
+ * concern rather than a provider-native config file. Providers, routes, and
+ * runtime command launchers should all use this helper instead of re-creating
+ * the path so the storage location stays consistent.
+ */
+export function getProviderSessionActiveModelChangesPath(): string {
+  return path.join(os.homedir(), '.cloudcli', 'provider-session-active-model-changes.json');
+}
+
+const buildProviderSessionActiveModelChangeKey = (
+  provider: LLMProvider,
+  sessionId: string,
+): string => `${provider}:${sessionId}`;
+
+const isProviderSessionActiveModelChangeCacheEntry = (
+  value: unknown,
+): value is ProviderSessionActiveModelChangeCacheEntry => {
+  const record = readObjectRecord(value);
+  return Boolean(
+    record
+    && typeof record.provider === 'string'
+    && typeof record.sessionId === 'string'
+    && typeof record.supported === 'boolean'
+    && typeof record.changed === 'boolean'
+    && (typeof record.model === 'string' || record.model === null)
+    && typeof record.updatedAt === 'string',
+  );
+};
+
+const readProviderSessionActiveModelChangeCacheFile = async (
+  filePath: string,
+): Promise<ProviderSessionActiveModelChangeCacheFile> => {
+  try {
+    const raw = await readFile(filePath, 'utf8');
+    const parsed = readObjectRecord(JSON.parse(raw));
+    if (
+      !parsed
+      || parsed.version !== PROVIDER_SESSION_ACTIVE_MODEL_CHANGE_CACHE_VERSION
+      || !readObjectRecord(parsed.entries)
+    ) {
+      return {
+        version: PROVIDER_SESSION_ACTIVE_MODEL_CHANGE_CACHE_VERSION,
+        entries: {},
+      };
+    }
+
+    const entries = Object.fromEntries(
+      Object.entries(parsed.entries).filter((entry): entry is [string, ProviderSessionActiveModelChangeCacheEntry] =>
+        isProviderSessionActiveModelChangeCacheEntry(entry[1]),
+      ),
+    );
+
+    return {
+      version: PROVIDER_SESSION_ACTIVE_MODEL_CHANGE_CACHE_VERSION,
+      entries,
+    };
+  } catch {
+    return {
+      version: PROVIDER_SESSION_ACTIVE_MODEL_CHANGE_CACHE_VERSION,
+      entries: {},
+    };
+  }
+};
+
+const writeProviderSessionActiveModelChangeCacheFile = async (
+  filePath: string,
+  payload: ProviderSessionActiveModelChangeCacheFile,
+): Promise<void> => {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+};
+
+const buildUnsupportedProviderSessionActiveModelChange = (
+  provider: LLMProvider,
+  sessionId: string,
+): ProviderSessionActiveModelChange => ({
+  provider,
+  sessionId,
+  supported: false,
+  changed: false,
+  model: null,
+});
+
+/**
+ * Reads the persisted session model-change state for one provider session.
+ *
+ * Runtime resume paths use this to decide whether they should inject a
+ * provider-specific model argument/thread option for the next resumed turn.
+ * Missing cache entries are normalized to `{ changed: false }` so callers can
+ * treat absence as "use the ordinary model selection flow".
+ */
+export async function readProviderSessionActiveModelChange(
+  provider: LLMProvider,
+  sessionId: string,
+  options: {
+    filePath?: string;
+    supported?: boolean;
+  } = {},
+): Promise<ProviderSessionActiveModelChange> {
+  const normalizedSessionId = sessionId.trim();
+  if (!normalizedSessionId) {
+    return buildUnsupportedProviderSessionActiveModelChange(provider, normalizedSessionId);
+  }
+
+  const supported = options.supported ?? true;
+  if (!supported) {
+    return buildUnsupportedProviderSessionActiveModelChange(provider, normalizedSessionId);
+  }
+
+  const filePath = options.filePath ?? getProviderSessionActiveModelChangesPath();
+  const cacheFile = await readProviderSessionActiveModelChangeCacheFile(filePath);
+  const cacheEntry = cacheFile.entries[
+    buildProviderSessionActiveModelChangeKey(provider, normalizedSessionId)
+  ];
+
+  if (!cacheEntry || !cacheEntry.changed || !cacheEntry.model?.trim()) {
+    return {
+      provider,
+      sessionId: normalizedSessionId,
+      supported: true,
+      changed: false,
+      model: null,
+    };
+  }
+
+  return {
+    provider,
+    sessionId: normalizedSessionId,
+    supported: true,
+    changed: true,
+    model: cacheEntry.model.trim(),
+  };
+}
+
+/**
+ * Persists a session model-change request for one provider.
+ *
+ * Provider adapters call this when the frontend explicitly selects a different
+ * model for an existing session. The stored `changed: true` flag is the single
+ * source of truth used later by resume paths to decide whether they should add
+ * a provider-native model override on the next invocation.
+ */
+export async function writeProviderSessionActiveModelChange(
+  provider: LLMProvider,
+  input: ProviderChangeActiveModelInput,
+  options: {
+    filePath?: string;
+    supported?: boolean;
+  } = {},
+): Promise<ProviderSessionActiveModelChange> {
+  const normalizedSessionId = input.sessionId.trim();
+  const normalizedModel = input.model.trim();
+  const supported = options.supported ?? true;
+
+  if (!supported) {
+    return buildUnsupportedProviderSessionActiveModelChange(provider, normalizedSessionId);
+  }
+
+  if (!normalizedSessionId || !normalizedModel) {
+    return {
+      provider,
+      sessionId: normalizedSessionId,
+      supported: true,
+      changed: false,
+      model: null,
+    };
+  }
+
+  const filePath = options.filePath ?? getProviderSessionActiveModelChangesPath();
+  const cacheFile = await readProviderSessionActiveModelChangeCacheFile(filePath);
+  cacheFile.entries[buildProviderSessionActiveModelChangeKey(provider, normalizedSessionId)] = {
+    provider,
+    sessionId: normalizedSessionId,
+    supported: true,
+    changed: true,
+    model: normalizedModel,
+    updatedAt: new Date().toISOString(),
+  };
+
+  await writeProviderSessionActiveModelChangeCacheFile(filePath, cacheFile);
+
+  return {
+    provider,
+    sessionId: normalizedSessionId,
+    supported: true,
+    changed: true,
+    model: normalizedModel,
+  };
+}
+
+// ---------------------------
+//----------------- WEBSOCKET PAYLOAD PARSING UTILITIES ------------
+/**
+ * Parses one websocket message payload into a plain JSON object record.
+ *
+ * Use this in realtime handlers that receive raw websocket payloads as `string`,
+ * `Buffer`, `ArrayBuffer`, or chunk arrays. The helper converts supported
+ * payload formats to UTF-8 text, parses JSON, and returns only object payloads.
+ * Primitive/array/invalid payloads return `null` so callers can handle bad input
+ * without throwing from deeply nested message handlers.
+ */
+export const parseIncomingJsonObject = (payload: unknown): AnyRecord | null => {
+  let text: string | null = null;
+
+  if (typeof payload === 'string') {
+    text = payload;
+  } else if (Buffer.isBuffer(payload)) {
+    text = payload.toString('utf8');
+  } else if (payload instanceof ArrayBuffer) {
+    text = Buffer.from(payload).toString('utf8');
+  } else if (Array.isArray(payload)) {
+    const buffers = payload
+      .map((entry) => {
+        if (Buffer.isBuffer(entry)) {
+          return entry;
+        }
+
+        if (entry instanceof ArrayBuffer) {
+          return Buffer.from(entry);
+        }
+
+        if (ArrayBuffer.isView(entry)) {
+          return Buffer.from(entry.buffer, entry.byteOffset, entry.byteLength);
+        }
+
+        return null;
+      })
+      .filter((entry): entry is Buffer => entry !== null);
+
+    if (buffers.length > 0) {
+      text = Buffer.concat(buffers).toString('utf8');
+    }
+  }
+
+  if (typeof text !== 'string' || text.trim().length === 0) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    return readObjectRecord(parsed);
+  } catch {
+    return null;
+  }
+};
+
 /**
  * Reads a JSON config file and guarantees a plain object result.
  *
@@ -189,5 +735,413 @@ export const writeJsonConfig = async (filePath: string, data: Record<string, unk
   await writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
 };
 
-// -------------------------------------------------------------------------------------------
+// ---------------------------
+//----------------- PROVIDER SKILL FILE UTILITIES ------------
+async function hasGitMarker(dirPath: string): Promise<boolean> {
+  try {
+    const gitMarkerStats = await stat(path.join(dirPath, '.git'));
+    return gitMarkerStats.isDirectory() || gitMarkerStats.isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Finds the highest git worktree root visible from a starting directory.
+ *
+ * Provider skill systems such as Codex and OpenCode walk upward through parent
+ * folders when resolving repository/project skills. Use this helper when a
+ * provider needs the topmost `.git` marker instead of only the nearest one, so
+ * monorepos and nested package folders discover shared root-level skills once.
+ */
+export async function findTopmostGitRoot(startPath: string): Promise<string | null> {
+  let currentPath = path.resolve(startPath);
+  let topmostGitRoot: string | null = null;
+
+  while (true) {
+    if (await hasGitMarker(currentPath)) {
+      topmostGitRoot = currentPath;
+    }
+
+    const parentPath = path.dirname(currentPath);
+    if (parentPath === currentPath) {
+      break;
+    }
+
+    currentPath = parentPath;
+  }
+
+  return topmostGitRoot;
+}
+
+/**
+ * Adds one provider skill source after normalizing and de-duplicating its root.
+ *
+ * Provider skill lookup rules often point at overlapping folders (for example a
+ * workspace folder can also be the git root). Use this helper while building a
+ * provider's `ProviderSkillSource[]` so the shared skills scanner reads each
+ * physical root once and still preserves provider-specific scope/command data.
+ */
+export function addUniqueProviderSkillSource(
+  sources: ProviderSkillSource[],
+  seenRootDirs: Set<string>,
+  source: ProviderSkillSource,
+): void {
+  const normalizedRootDir = path.resolve(source.rootDir);
+  if (seenRootDirs.has(normalizedRootDir)) {
+    return;
+  }
+
+  seenRootDirs.add(normalizedRootDir);
+  sources.push({ ...source, rootDir: normalizedRootDir });
+}
+
+// ---------------------------
+//----------------- PROVIDER SKILL MARKDOWN UTILITIES ------------
+/**
+ * Finds direct child skill markdown files under a provider skill root.
+ *
+ * Skill systems usually store one skill per child directory, so direct mode
+ * scans only `<root>/<skill-name>/SKILL.md`. Recursive mode is reserved for
+ * provider sources that can nest skills arbitrarily, and it returns every
+ * descendant `SKILL.md`. Missing or unreadable roots return an empty list
+ * because users may not have every provider installed or configured.
+ */
+export async function findProviderSkillMarkdownFiles(
+  rootDir: string,
+  options: { recursive?: boolean } = {},
+): Promise<string[]> {
+  const skillFiles: string[] = [];
+
+  const collectRecursive = async (dirPath: string): Promise<void> => {
+    let entries;
+    try {
+      entries = await readdir(dirPath, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    try {
+      const skillPath = path.join(dirPath, 'SKILL.md');
+      const skillStats = await stat(skillPath);
+      if (skillStats.isFile()) {
+        skillFiles.push(skillPath);
+      }
+    } catch {
+      // Directories without SKILL.md are expected while walking plugin trees.
+    }
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        await collectRecursive(path.join(dirPath, entry.name));
+      }
+    }
+  };
+
+  if (options.recursive) {
+    await collectRecursive(rootDir);
+    return skillFiles.sort((left, right) => left.localeCompare(right));
+  }
+
+  try {
+    const entries = await readdir(rootDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      const skillPath = path.join(rootDir, entry.name, 'SKILL.md');
+      try {
+        const skillStats = await stat(skillPath);
+        if (skillStats.isFile()) {
+          skillFiles.push(skillPath);
+        }
+      } catch {
+        // A partial skill directory should not block discovery of sibling skills.
+      }
+    }
+
+    return skillFiles.sort((left, right) => left.localeCompare(right));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Reads the `name` and `description` fields from a provider skill markdown file.
+ *
+ * The metadata is expected in markdown front matter. If a skill omits `name`, the
+ * parent directory name is used as a stable fallback so providers can still
+ * expose the skill. Missing descriptions are normalized to an empty string.
+ */
+export async function readProviderSkillMarkdownDefinition(
+  skillPath: string,
+): Promise<{ name: string; description: string }> {
+  const content = await readFile(skillPath, 'utf8');
+  const parsed = parseFrontMatter(content);
+  const data = readObjectRecord(parsed.data) ?? {};
+  const fallbackName = path.basename(path.dirname(skillPath));
+
+  return {
+    name: readOptionalString(data.name) ?? fallbackName,
+    description: readOptionalString(data.description) ?? '',
+  };
+}
+
+// ---------------------------
+//----------------- SESSION SYNCHRONIZER TITLE HELPERS ------------
+/**
+ * Produces a compact session title suitable for UI rendering and DB storage.
+ *
+ * Use this when converting provider-native names into a consistent title value.
+ * The helper collapses repeated whitespace, trims the result, and truncates it
+ * to 120 characters so every provider writes stable and bounded metadata.
+ * If the normalized input is empty, it returns the supplied fallback title.
+ */
+export function normalizeSessionName(rawValue: string | undefined, fallback: string): string {
+  const normalized = (rawValue ?? '').replace(/\s+/g, ' ').trim();
+  if (!normalized) {
+    return fallback;
+  }
+
+  return normalized.slice(0, 120);
+}
+
+// ---------------------------
+//----------------- PROVIDER SESSION VALUE NORMALIZATION UTILITIES ------------
+/**
+ * Converts provider-native timestamps into ISO strings.
+ *
+ * Provider CLIs commonly persist epoch timestamps as milliseconds, seconds, or
+ * already-formatted date strings. Use this helper when normalizing session
+ * metadata or transcript events so every provider writes the same ISO timestamp
+ * shape to API responses and database rows.
+ */
+export function normalizeProviderTimestamp(value: unknown): string {
+  if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+    const millis = value < 1_000_000_000_000 ? value * 1000 : value;
+    return new Date(millis).toISOString();
+  }
+
+  if (typeof value === 'string' && value.trim()) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) {
+      return normalizeProviderTimestamp(parsed);
+    }
+
+    const date = new Date(value);
+    if (!Number.isNaN(date.getTime())) {
+      return date.toISOString();
+    }
+  }
+
+  return new Date().toISOString();
+}
+
+/**
+ * Parses a JSON string or narrows an existing object into a plain record.
+ *
+ * Use this when provider databases store structured JSON inside text columns.
+ * Invalid JSON, arrays, and primitive values return `null` so callers can skip
+ * malformed optional metadata without hiding the rest of a session transcript.
+ */
+export function readJsonRecord(value: unknown): AnyRecord | null {
+  if (typeof value !== 'string') {
+    return readObjectRecord(value);
+  }
+
+  try {
+    return readObjectRecord(JSON.parse(value));
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------
+//----------------- OPENCODE SESSION STORAGE UTILITIES ------------
+/**
+ * Resolves the OpenCode SQLite session database path.
+ *
+ * OpenCode stores session, message, part, and project metadata in one shared
+ * `opencode.db` file under its XDG data directory. Provider readers and
+ * synchronizers should use this path for read-only access and should never store
+ * it as a deletable transcript path for an individual app session row.
+ */
+export function getOpenCodeDatabasePath(): string {
+  return path.join(os.homedir(), '.local', 'share', 'opencode', 'opencode.db');
+}
+
+// ---------------------------
+//----------------- SAFE DIRECTORY NAME UTILITIES ------------
+/**
+ * Validates that a user or provider supplied identifier can safely be treated
+ * as one leaf directory name under an existing root folder.
+ *
+ * Use this before composing paths like `<root>/<session-id>/file.db>` to block
+ * path traversal and accidental nested paths. The returned string is trimmed but
+ * otherwise unchanged so callers can still match the provider's on-disk naming.
+ */
+export function sanitizeLeafDirectoryName(inputName: string, label = 'directory name'): string {
+  const normalized = inputName.trim();
+  if (!normalized) {
+    throw new Error(`${label} is required.`);
+  }
+
+  if (
+    normalized.includes('..')
+    || normalized.includes(path.posix.sep)
+    || normalized.includes(path.win32.sep)
+    || normalized !== path.basename(normalized)
+  ) {
+    throw new Error(`Invalid ${label} "${inputName}".`);
+  }
+
+  return normalized;
+}
+
+// ---------------------------
+//----------------- SESSION SYNCHRONIZER FILESYSTEM HELPERS ------------
+/**
+ * Recursively discovers files that match one extension, with optional incremental filtering.
+ *
+ * Provider synchronizers call this to find transcript artifacts under provider
+ * home directories. Pass `lastScanAt` to include only files created after the
+ * previous scan, or pass `null` to perform a full rescan. Missing directories
+ * are treated as empty because not every provider exists on every machine.
+ */
+export async function findFilesRecursivelyCreatedAfter(
+  rootDir: string,
+  extension: string,
+  lastScanAt: Date | null,
+  fileList: string[] = []
+): Promise<string[]> {
+  try {
+    const entries = await readdir(rootDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(rootDir, entry.name);
+
+      if (entry.isDirectory()) {
+        await findFilesRecursivelyCreatedAfter(fullPath, extension, lastScanAt, fileList);
+        continue;
+      }
+
+      if (!entry.isFile() || !entry.name.endsWith(extension)) {
+        continue;
+      }
+
+      if (!lastScanAt) {
+        fileList.push(fullPath);
+        continue;
+      }
+
+      const fileStat = await stat(fullPath);
+      if (fileStat.birthtime > lastScanAt) {
+        fileList.push(fullPath);
+      }
+    }
+  } catch {
+    // Missing provider folders are expected in first-run or partial setups.
+  }
+
+  return fileList;
+}
+
+/**
+ * Reads file creation/update timestamps and maps them to DB-friendly ISO strings.
+ *
+ * Session indexers use this to persist `created_at` and `updated_at` metadata
+ * when upserting sessions. If the file cannot be read, an empty object is
+ * returned so indexing can continue for other files.
+ */
+export async function readFileTimestamps(
+  filePath: string
+): Promise<{ createdAt?: string; updatedAt?: string }> {
+  try {
+    const fileStat = await stat(filePath);
+    return {
+      createdAt: fileStat.birthtime.toISOString(),
+      updatedAt: fileStat.mtime.toISOString(),
+    };
+  } catch {
+    return {};
+  }
+}
+
+// ---------------------------
+//----------------- SESSION SYNCHRONIZER JSONL PARSING HELPERS ------------
+/**
+ * Builds a first-seen key/value lookup map from a JSONL file.
+ *
+ * Use this for provider index files where session id -> display name metadata
+ * is stored line-by-line. The first value for each key wins, preserving the
+ * earliest known label while avoiding repeated map overwrites.
+ */
+export async function buildLookupMap(
+  filePath: string,
+  keyField: string,
+  valueField: string
+): Promise<Map<string, string>> {
+  const lookup = new Map<string, string>();
+
+  try {
+    const fileStream = fs.createReadStream(filePath);
+    const lineReader = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+
+    for await (const line of lineReader) {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        continue;
+      }
+
+      const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+      const key = parsed[keyField];
+      const value = parsed[valueField];
+
+      if (typeof key === 'string' && typeof value === 'string' && !lookup.has(key)) {
+        lookup.set(key, value);
+      }
+    }
+  } catch {
+    // Missing or unreadable lookup files should not block session sync.
+  }
+
+  return lookup;
+}
+
+/**
+ * Reads a JSONL file and returns the first extracted payload that matches caller criteria.
+ *
+ * The caller supplies an `extractor` that validates provider-specific row
+ * shapes. This helper centralizes line-by-line parsing and lets indexers stop
+ * scanning as soon as one valid row is found.
+ */
+export async function extractFirstValidJsonlData<T>(
+  filePath: string,
+  extractor: (parsedJson: unknown) => T | null | undefined
+): Promise<T | null> {
+  try {
+    const fileStream = fs.createReadStream(filePath);
+    const lineReader = readline.createInterface({ input: fileStream, crlfDelay: Infinity });
+
+    for await (const line of lineReader) {
+      const trimmed = line.trim();
+      if (!trimmed) {
+        continue;
+      }
+
+      const parsed = JSON.parse(trimmed);
+      const extracted = extractor(parsed);
+      if (extracted) {
+        lineReader.close();
+        fileStream.close();
+        return extracted;
+      }
+    }
+  } catch {
+    // Ignore malformed or missing artifacts so full scans keep progressing.
+  }
+
+  return null;
+}
 
diff --git a/server/utils/commandParser.js b/server/utils/commandParser.js
index 56e3f702..0451320d 100644
--- a/server/utils/commandParser.js
+++ b/server/utils/commandParser.js
@@ -1,9 +1,11 @@
+import { execFile } from 'child_process';
 import { promises as fs } from 'fs';
 import path from 'path';
-import { execFile } from 'child_process';
 import { promisify } from 'util';
+
 import { parse as parseShellCommand } from 'shell-quote';
-import { parseFrontmatter } from './frontmatter.js';
+
+import { parseFrontMatter } from '../shared/frontmatter.js';
 
 const execFileAsync = promisify(execFile);
 
@@ -32,7 +34,7 @@ const BASH_COMMAND_ALLOWLIST = [
  */
 export function parseCommand(content) {
   try {
-    const parsed = parseFrontmatter(content);
+    const parsed = parseFrontMatter(content);
     return {
       data: parsed.data || {},
       content: parsed.content || '',
diff --git a/server/utils/taskmaster-websocket.js b/server/utils/taskmaster-websocket.js
index 87c05498..001b3ecc 100644
--- a/server/utils/taskmaster-websocket.js
+++ b/server/utils/taskmaster-websocket.js
@@ -7,20 +7,25 @@
  */
 
 /**
- * Broadcast TaskMaster project update to all connected clients
+ * Broadcast TaskMaster project update to all connected clients.
+ *
+ * The payload key is `projectId` post-migration so frontend listeners can
+ * match notifications against the DB-assigned project identifier they
+ * already use everywhere else.
+ *
  * @param {WebSocket.Server} wss - WebSocket server instance
- * @param {string} projectName - Name of the updated project
+ * @param {string} projectId - DB id of the updated project
  * @param {Object} taskMasterData - Updated TaskMaster data
  */
-export function broadcastTaskMasterProjectUpdate(wss, projectName, taskMasterData) {
-    if (!wss || !projectName) {
-        console.warn('TaskMaster WebSocket broadcast: Missing wss or projectName');
+export function broadcastTaskMasterProjectUpdate(wss, projectId, taskMasterData) {
+    if (!wss || !projectId) {
+        console.warn('TaskMaster WebSocket broadcast: Missing wss or projectId');
         return;
     }
 
     const message = {
         type: 'taskmaster-project-updated',
-        projectName,
+        projectId,
         taskMasterData,
         timestamp: new Date().toISOString()
     };
@@ -38,20 +43,21 @@ export function broadcastTaskMasterProjectUpdate(wss, projectName, taskMasterDat
 }
 
 /**
- * Broadcast TaskMaster tasks update for a specific project
- * @param {WebSocket.Server} wss - WebSocket server instance  
- * @param {string} projectName - Name of the project with updated tasks
+ * Broadcast TaskMaster tasks update for a specific project.
+ *
+ * @param {WebSocket.Server} wss - WebSocket server instance
+ * @param {string} projectId - DB id of the project with updated tasks
  * @param {Object} tasksData - Updated tasks data
  */
-export function broadcastTaskMasterTasksUpdate(wss, projectName, tasksData) {
-    if (!wss || !projectName) {
-        console.warn('TaskMaster WebSocket broadcast: Missing wss or projectName');
+export function broadcastTaskMasterTasksUpdate(wss, projectId, tasksData) {
+    if (!wss || !projectId) {
+        console.warn('TaskMaster WebSocket broadcast: Missing wss or projectId');
         return;
     }
 
     const message = {
         type: 'taskmaster-tasks-updated',
-        projectName,
+        projectId,
         tasksData,
         timestamp: new Date().toISOString()
     };
diff --git a/shared/modelConstants.js b/shared/modelConstants.js
deleted file mode 100644
index d7aaac4c..00000000
--- a/shared/modelConstants.js
+++ /dev/null
@@ -1,95 +0,0 @@
-/**
- * Centralized Model Definitions
- * Single source of truth for all supported AI models
- */
-
-/**
- * Claude (Anthropic) Models
- *
- * Note: Claude uses two different formats:
- * - SDK format ('sonnet', 'opus') - used by the UI and claude-sdk.js
- * - API format ('claude-sonnet-4.5') - used by slash commands for display
- */
-export const CLAUDE_MODELS = {
-  // Models in SDK format (what the actual SDK accepts)
-  OPTIONS: [
-    { value: "sonnet", label: "Sonnet" },
-    { value: "opus", label: "Opus" },
-    { value: "haiku", label: "Haiku" },
-    { value: "claude-opus-4-6", label: "Opus 4.6" },
-    { value: "opusplan", label: "Opus Plan" },
-    { value: "sonnet[1m]", label: "Sonnet [1M]" },
-    { value: "opus[1m]", label: "Opus [1M]" },
-  ],
-
-  DEFAULT: "opus",
-};
-
-/**
- * Cursor Models
- */
-export const CURSOR_MODELS = {
-  OPTIONS: [
-    { value: "opus-4.6-thinking", label: "Claude 4.6 Opus (Thinking)" },
-    { value: "gpt-5.3-codex", label: "GPT-5.3" },
-    { value: "gpt-5.2-high", label: "GPT-5.2 High" },
-    { value: "gemini-3-pro", label: "Gemini 3 Pro" },
-    { value: "opus-4.5-thinking", label: "Claude 4.5 Opus (Thinking)" },
-    { value: "gpt-5.2", label: "GPT-5.2" },
-    { value: "gpt-5.1", label: "GPT-5.1" },
-    { value: "gpt-5.1-high", label: "GPT-5.1 High" },
-    { value: "composer-1", label: "Composer 1" },
-    { value: "auto", label: "Auto" },
-    { value: "sonnet-4.5", label: "Claude 4.5 Sonnet" },
-    { value: "sonnet-4.5-thinking", label: "Claude 4.5 Sonnet (Thinking)" },
-    { value: "opus-4.5", label: "Claude 4.5 Opus" },
-    { value: "gpt-5.1-codex", label: "GPT-5.1 Codex" },
-    { value: "gpt-5.1-codex-high", label: "GPT-5.1 Codex High" },
-    { value: "gpt-5.1-codex-max", label: "GPT-5.1 Codex Max" },
-    { value: "gpt-5.1-codex-max-high", label: "GPT-5.1 Codex Max High" },
-    { value: "opus-4.1", label: "Claude 4.1 Opus" },
-    { value: "grok", label: "Grok" },
-  ],
-
-  DEFAULT: "gpt-5-3-codex",
-};
-
-/**
- * Codex (OpenAI) Models
- */
-export const CODEX_MODELS = {
-  OPTIONS: [
-    { value: "gpt-5.4", label: "GPT-5.4" },
-    { value: "gpt-5.4-mini", label: "GPT-5.4 mini" },
-    { value: "gpt-5.3-codex", label: "GPT-5.3 Codex" },
-    { value: "gpt-5.2-codex", label: "GPT-5.2 Codex" },
-    { value: "gpt-5.2", label: "GPT-5.2" },
-    { value: "gpt-5.1-codex-max", label: "GPT-5.1 Codex Max" },
-    { value: "o3", label: "O3" },
-    { value: "o4-mini", label: "O4-mini" },
-  ],
-
-  DEFAULT: "gpt-5.4",
-};
-
-/**
- * Gemini Models
- */
-export const GEMINI_MODELS = {
-  OPTIONS: [
-    { value: "gemini-3.1-pro-preview", label: "Gemini 3.1 Pro Preview" },
-    { value: "gemini-3-pro-preview", label: "Gemini 3 Pro Preview" },
-    { value: "gemini-3-flash-preview", label: "Gemini 3 Flash Preview" },
-    { value: "gemini-2.5-flash", label: "Gemini 2.5 Flash" },
-    { value: "gemini-2.5-pro", label: "Gemini 2.5 Pro" },
-    { value: "gemini-2.0-flash-lite", label: "Gemini 2.0 Flash Lite" },
-    { value: "gemini-2.0-flash", label: "Gemini 2.0 Flash" },
-    { value: "gemini-2.0-pro-exp", label: "Gemini 2.0 Pro Experimental" },
-    {
-      value: "gemini-2.0-flash-thinking-exp",
-      label: "Gemini 2.0 Flash Thinking",
-    },
-  ],
-
-  DEFAULT: "gemini-3.1-pro-preview",
-};
diff --git a/src/components/app/AppContent.tsx b/src/components/app/AppContent.tsx
index 63c11df0..1ba41b95 100644
--- a/src/components/app/AppContent.tsx
+++ b/src/components/app/AppContent.tsx
@@ -1,14 +1,25 @@
 import { useEffect, useRef } from 'react';
 import { useNavigate, useParams } from 'react-router-dom';
 import { useTranslation } from 'react-i18next';
+
 import Sidebar from '../sidebar/view/Sidebar';
 import MainContent from '../main-content/view/MainContent';
+import CommandPalette from '../command-palette/CommandPalette';
 import { useWebSocket } from '../../contexts/WebSocketContext';
+import { PaletteOpsProvider, usePaletteOpsRegister } from '../../contexts/PaletteOpsContext';
 import { useDeviceSettings } from '../../hooks/useDeviceSettings';
 import { useSessionProtection } from '../../hooks/useSessionProtection';
 import { useProjectsState } from '../../hooks/useProjectsState';
 
 export default function AppContent() {
+  return (
+    <PaletteOpsProvider>
+      <AppContentInner />
+    </PaletteOpsProvider>
+  );
+}
+
+function AppContentInner() {
   const navigate = useNavigate();
   const { sessionId } = useParams<{ sessionId?: string }>();
   const { t } = useTranslation('common');
@@ -23,7 +34,6 @@ export default function AppContent() {
     markSessionAsInactive,
     markSessionAsProcessing,
     markSessionAsNotProcessing,
-    replaceTemporarySession,
   } = useSessionProtection();
 
   const {
@@ -33,6 +43,7 @@ export default function AppContent() {
     sidebarOpen,
     isLoadingProjects,
     externalMessageUpdate,
+    newSessionTrigger,
     setActiveTab,
     setSidebarOpen,
     setIsInputFocused,
@@ -40,6 +51,7 @@ export default function AppContent() {
     openSettings,
     refreshProjectsSilently,
     sidebarSharedProps,
+    handleNewSession,
   } = useProjectsState({
     sessionId,
     navigate,
@@ -48,27 +60,10 @@ export default function AppContent() {
     activeSessions,
   });
 
-  useEffect(() => {
-    // Expose a non-blocking refresh for chat/session flows.
-    // Full loading refreshes are still available through direct fetchProjects calls.
-    window.refreshProjects = refreshProjectsSilently;
-
-    return () => {
-      if (window.refreshProjects === refreshProjectsSilently) {
-        delete window.refreshProjects;
-      }
-    };
-  }, [refreshProjectsSilently]);
-
-  useEffect(() => {
-    window.openSettings = openSettings;
-
-    return () => {
-      if (window.openSettings === openSettings) {
-        delete window.openSettings;
-      }
-    };
-  }, [openSettings]);
+  usePaletteOpsRegister({
+    openSettings,
+    refreshProjects: refreshProjectsSilently,
+  });
 
   useEffect(() => {
     if (typeof navigator === 'undefined' || !('serviceWorker' in navigator)) {
@@ -195,13 +190,21 @@ export default function AppContent() {
           onSessionProcessing={markSessionAsProcessing}
           onSessionNotProcessing={markSessionAsNotProcessing}
           processingSessions={processingSessions}
-          onReplaceTemporarySession={replaceTemporarySession}
-          onNavigateToSession={(targetSessionId: string) => navigate(`/session/${targetSessionId}`)}
+          onNavigateToSession={(targetSessionId: string, options) =>
+            navigate(`/session/${targetSessionId}`, { replace: Boolean(options?.replace) })
+          }
           onShowSettings={() => setShowSettings(true)}
           externalMessageUpdate={externalMessageUpdate}
+          newSessionTrigger={newSessionTrigger}
         />
       </div>
 
+      <CommandPalette
+        selectedProject={selectedProject}
+        onStartNewChat={handleNewSession}
+        onOpenSettings={() => openSettings()}
+        onShowTab={setActiveTab}
+      />
     </div>
   );
 }
diff --git a/src/components/chat/hooks/useChatComposerState.ts b/src/components/chat/hooks/useChatComposerState.ts
index 3b167215..6d3b93df 100644
--- a/src/components/chat/hooks/useChatComposerState.ts
+++ b/src/components/chat/hooks/useChatComposerState.ts
@@ -10,6 +10,7 @@ import type {
   TouchEvent,
 } from 'react';
 import { useDropzone } from 'react-dropzone';
+
 import { authenticatedFetch } from '../../../utils/api';
 import { thinkingModes } from '../constants/thinkingModes';
 import { grantClaudeToolPermission } from '../utils/chatPermissions';
@@ -19,13 +20,13 @@ import type {
   PendingPermissionRequest,
   PermissionMode,
 } from '../types/types';
-import type { Project, ProjectSession, LLMProvider } from '../../../types/app';
+import type { Project, ProjectSession, LLMProvider, ProviderModelsCacheInfo } from '../../../types/app';
 import { escapeRegExp } from '../utils/chatFormatting';
+
 import { useFileMentions } from './useFileMentions';
 import { type SlashCommand, useSlashCommands } from './useSlashCommands';
 
 type PendingViewSession = {
-  sessionId: string | null;
   startedAt: number;
 };
 
@@ -40,6 +41,7 @@ interface UseChatComposerStateArgs {
   claudeModel: string;
   codexModel: string;
   geminiModel: string;
+  opencodeModel: string;
   isLoading: boolean;
   canAbortSession: boolean;
   tokenBudget: Record<string, unknown> | null;
@@ -53,8 +55,6 @@ interface UseChatComposerStateArgs {
   pendingViewSessionRef: { current: PendingViewSession | null };
   scrollToBottom: () => void;
   addMessage: (msg: ChatMessage) => void;
-  clearMessages: () => void;
-  rewindMessages: (count: number) => void;
   setIsLoading: (loading: boolean) => void;
   setCanAbortSession: (canAbort: boolean) => void;
   setClaudeStatus: (status: { text: string; tokens: number; can_interrupt: boolean } | null) => void;
@@ -76,13 +76,73 @@ interface CommandExecutionResult {
   hasFileIncludes?: boolean;
 }
 
+export type ModelCommandData = {
+  current?: {
+    provider?: string;
+    providerLabel?: string;
+    model?: string;
+  };
+  available?: Partial<Record<LLMProvider, string[]>>;
+  availableModels?: string[];
+  availableOptions?: Array<{
+    value: string;
+    label?: string;
+    description?: string;
+  }>;
+  defaultModel?: string;
+  cache?: ProviderModelsCacheInfo;
+};
+
+export type CostCommandData = {
+  tokenUsage?: {
+    used?: number;
+    total?: number;
+  };
+  tokenBreakdown?: {
+    input?: number;
+    output?: number;
+  };
+  provider?: string;
+  model?: string;
+};
+
+export type StatusCommandData = {
+  version?: string;
+  packageName?: string;
+  uptime?: string;
+  model?: string;
+  provider?: string;
+  nodeVersion?: string;
+  platform?: string;
+  pid?: number;
+  memoryUsage?: {
+    rssMb?: number;
+    heapUsedMb?: number;
+    heapTotalMb?: number;
+  };
+};
+
+export type HelpCommandData = {
+  content?: string;
+  format?: string;
+  commands?: Array<{
+    name: string;
+    description?: string;
+    namespace?: string;
+  }>;
+};
+
+export type CommandModalKind = 'help' | 'models' | 'cost' | 'status';
+
+export type CommandModalPayload = {
+  kind: CommandModalKind;
+  data: HelpCommandData | ModelCommandData | CostCommandData | StatusCommandData;
+};
+
 const createFakeSubmitEvent = () => {
   return { preventDefault: () => undefined } as unknown as FormEvent<HTMLFormElement>;
 };
 
-const isTemporarySessionId = (sessionId: string | null | undefined) =>
-  Boolean(sessionId && sessionId.startsWith('new-session-'));
-
 const getNotificationSessionSummary = (
   selectedSession: ProjectSession | null,
   fallbackInput: string,
@@ -112,6 +172,7 @@ export function useChatComposerState({
   claudeModel,
   codexModel,
   geminiModel,
+  opencodeModel,
   isLoading,
   canAbortSession,
   tokenBudget,
@@ -125,8 +186,6 @@ export function useChatComposerState({
   pendingViewSessionRef,
   scrollToBottom,
   addMessage,
-  clearMessages,
-  rewindMessages,
   setIsLoading,
   setCanAbortSession,
   setClaudeStatus,
@@ -135,7 +194,9 @@ export function useChatComposerState({
 }: UseChatComposerStateArgs) {
   const [input, setInput] = useState(() => {
     if (typeof window !== 'undefined' && selectedProject) {
-      return safeLocalStorage.getItem(`draft_input_${selectedProject.name}`) || '';
+      // Draft inputs are keyed by the DB projectId so per-project drafts
+      // survive display-name changes.
+      return safeLocalStorage.getItem(`draft_input_${selectedProject.projectId}`) || '';
     }
     return '';
   });
@@ -144,6 +205,7 @@ export function useChatComposerState({
   const [imageErrors, setImageErrors] = useState<Map<string, string>>(new Map());
   const [isTextareaExpanded, setIsTextareaExpanded] = useState(false);
   const [thinkingMode, setThinkingMode] = useState('none');
+  const [commandModalPayload, setCommandModalPayload] = useState<CommandModalPayload | null>(null);
 
   const textareaRef = useRef<HTMLTextAreaElement>(null);
   const inputHighlightRef = useRef<HTMLDivElement>(null);
@@ -151,40 +213,39 @@ export function useChatComposerState({
     ((event: FormEvent<HTMLFormElement> | MouseEvent | TouchEvent | KeyboardEvent<HTMLTextAreaElement>) => Promise<void>) | null
   >(null);
   const inputValueRef = useRef(input);
+  const selectedProjectId = selectedProject?.projectId;
 
   const handleBuiltInCommand = useCallback(
     (result: CommandExecutionResult) => {
       const { action, data } = result;
       switch (action) {
-        case 'clear':
-          clearMessages();
-          break;
-
         case 'help':
-          addMessage({
-            type: 'assistant',
-            content: data.content,
-            timestamp: Date.now(),
+          setCommandModalPayload({
+            kind: 'help',
+            data: (data || {}) as HelpCommandData,
           });
           break;
 
-        case 'model':
-          addMessage({
-            type: 'assistant',
-            content: `**Current Model**: ${data.current.model}\n\n**Available Models**:\n\nClaude: ${data.available.claude.join(', ')}\n\nCursor: ${data.available.cursor.join(', ')}`,
-            timestamp: Date.now(),
+        case 'models':
+          setCommandModalPayload({
+            kind: 'models',
+            data: (data || {}) as ModelCommandData,
           });
           break;
 
         case 'cost': {
-          const costMessage = `**Token Usage**: ${data.tokenUsage.used.toLocaleString()} / ${data.tokenUsage.total.toLocaleString()} (${data.tokenUsage.percentage}%)\n\n**Estimated Cost**:\n- Input: $${data.cost.input}\n- Output: $${data.cost.output}\n- **Total**: $${data.cost.total}\n\n**Model**: ${data.model}`;
-          addMessage({ type: 'assistant', content: costMessage, timestamp: Date.now() });
+          setCommandModalPayload({
+            kind: 'cost',
+            data: (data || {}) as CostCommandData,
+          });
           break;
         }
 
         case 'status': {
-          const statusMessage = `**System Status**\n\n- Version: ${data.version}\n- Uptime: ${data.uptime}\n- Model: ${data.model}\n- Provider: ${data.provider}\n- Node.js: ${data.nodeVersion}\n- Platform: ${data.platform}`;
-          addMessage({ type: 'assistant', content: statusMessage, timestamp: Date.now() });
+          setCommandModalPayload({
+            kind: 'status',
+            data: (data || {}) as StatusCommandData,
+          });
           break;
         }
 
@@ -211,30 +272,17 @@ export function useChatComposerState({
           onShowSettings?.();
           break;
 
-        case 'rewind':
-          if (data.error) {
-            addMessage({
-              type: 'assistant',
-              content: `Warning: ${data.message}`,
-              timestamp: Date.now(),
-            });
-          } else {
-            rewindMessages(data.steps * 2);
-            addMessage({
-              type: 'assistant',
-              content: `Rewound ${data.steps} step(s). ${data.message}`,
-              timestamp: Date.now(),
-            });
-          }
-          break;
-
         default:
           console.warn('Unknown built-in command action:', action);
       }
     },
-    [onFileOpen, onShowSettings, addMessage, clearMessages, rewindMessages],
+    [onFileOpen, onShowSettings, addMessage],
   );
 
+  const closeCommandModal = useCallback(() => {
+    setCommandModalPayload(null);
+  }, []);
+
   const handleCustomCommand = useCallback(async (result: CommandExecutionResult) => {
     const { content, hasBashCommands } = result;
 
@@ -276,12 +324,22 @@ export function useChatComposerState({
         const args =
           commandMatch && commandMatch[1] ? commandMatch[1].trim().split(/\s+/) : [];
 
+        // The `/api/commands/execute` context sends `projectId` now instead of
+        // a folder-derived project name; the path is still included verbatim.
         const context = {
           projectPath: selectedProject.fullPath || selectedProject.path,
-          projectName: selectedProject.name,
+          projectId: selectedProject.projectId,
           sessionId: currentSessionId,
           provider,
-          model: provider === 'cursor' ? cursorModel : provider === 'codex' ? codexModel : provider === 'gemini' ? geminiModel : claudeModel,
+          model: provider === 'cursor'
+            ? cursorModel
+            : provider === 'codex'
+              ? codexModel
+              : provider === 'gemini'
+                ? geminiModel
+                : provider === 'opencode'
+                  ? opencodeModel
+                  : claudeModel,
           tokenUsage: tokenBudget,
         };
 
@@ -333,6 +391,7 @@ export function useChatComposerState({
       currentSessionId,
       cursorModel,
       geminiModel,
+      opencodeModel,
       handleBuiltInCommand,
       handleCustomCommand,
       input,
@@ -358,6 +417,7 @@ export function useChatComposerState({
     handleCommandMenuKeyDown,
   } = useSlashCommands({
     selectedProject,
+    provider,
     input,
     setInput,
     textareaRef,
@@ -467,14 +527,27 @@ export function useChatComposerState({
         return;
       }
 
-      // Intercept slash commands: if input starts with /commandName, execute as command with args
-      const trimmedInput = currentInput.trim();
-      if (trimmedInput.startsWith('/')) {
-        const firstSpace = trimmedInput.indexOf(' ');
-        const commandName = firstSpace > 0 ? trimmedInput.slice(0, firstSpace) : trimmedInput;
-        const matchedCommand = slashCommands.find((cmd: SlashCommand) => cmd.name === commandName);
-        if (matchedCommand) {
-          executeCommand(matchedCommand, trimmedInput);
+      // Intercept slash commands only when "/" is the first input character.
+      // Also accept exact "help" as a convenience alias for users who expect CLI-style help.
+      const commandInput = currentInput.trimEnd();
+      const isHelpAlias = commandInput.trim().toLowerCase() === 'help';
+      if (commandInput.startsWith('/') || isHelpAlias) {
+        const firstSpace = commandInput.indexOf(' ');
+        const commandName = isHelpAlias
+          ? '/help'
+          : firstSpace > 0 ? commandInput.slice(0, firstSpace) : commandInput;
+        const matchedCommand =
+          slashCommands.find((cmd: SlashCommand) => cmd.name === commandName) ||
+          (commandName === '/help'
+            ? ({
+                name: '/help',
+                description: 'Show help documentation for Claude Code',
+                namespace: 'builtin',
+                metadata: { type: 'builtin' },
+              } as SlashCommand)
+            : undefined);
+        if (matchedCommand && matchedCommand.type !== 'skill') {
+          executeCommand(matchedCommand, isHelpAlias ? '/help' : commandInput);
           setInput('');
           inputValueRef.current = '';
           setAttachedImages([]);
@@ -503,7 +576,7 @@ export function useChatComposerState({
         });
 
         try {
-          const response = await authenticatedFetch(`/api/projects/${selectedProject.name}/upload-images`, {
+          const response = await authenticatedFetch(`/api/projects/${selectedProject.projectId}/upload-images`, {
             method: 'POST',
             headers: {},
             body: formData,
@@ -529,7 +602,6 @@ export function useChatComposerState({
 
       const effectiveSessionId =
         currentSessionId || selectedSession?.id || sessionStorage.getItem('cursorSessionId');
-      const sessionToActivate = effectiveSessionId || `new-session-${Date.now()}`;
 
       const userMessage: ChatMessage = {
         type: 'user',
@@ -551,14 +623,12 @@ export function useChatComposerState({
       setTimeout(() => scrollToBottom(), 100);
 
       if (!effectiveSessionId && !selectedSession?.id) {
-        if (typeof window !== 'undefined') {
-          // Reset stale pending IDs from previous interrupted runs before creating a new one.
-          sessionStorage.removeItem('pendingSessionId');
-        }
-        pendingViewSessionRef.current = { sessionId: null, startedAt: Date.now() };
+        // This tracks only that a request is in flight before the provider has
+        // emitted its real session id; routing still waits for session_created.
+        pendingViewSessionRef.current = { startedAt: Date.now() };
       }
-      onSessionActive?.(sessionToActivate);
-      if (effectiveSessionId && !isTemporarySessionId(effectiveSessionId)) {
+      if (effectiveSessionId) {
+        onSessionActive?.(effectiveSessionId);
         onSessionProcessing?.(effectiveSessionId);
       }
 
@@ -571,6 +641,8 @@ export function useChatComposerState({
                 ? 'codex-settings'
                 : provider === 'gemini'
                   ? 'gemini-settings'
+                  : provider === 'opencode'
+                    ? 'opencode-settings'
                   : 'claude-settings';
           const savedSettings = safeLocalStorage.getItem(settingsKey);
           if (savedSettings) {
@@ -638,6 +710,20 @@ export function useChatComposerState({
             toolsSettings,
           },
         });
+      } else if (provider === 'opencode') {
+        sendMessage({
+          type: 'opencode-command',
+          command: messageContent,
+          sessionId: effectiveSessionId,
+          options: {
+            cwd: resolvedProjectPath,
+            projectPath: resolvedProjectPath,
+            sessionId: effectiveSessionId,
+            resume: Boolean(effectiveSessionId),
+            model: opencodeModel,
+            sessionSummary,
+          },
+        });
       } else {
         sendMessage({
           type: 'claude-command',
@@ -669,7 +755,7 @@ export function useChatComposerState({
         textareaRef.current.style.height = 'auto';
       }
 
-      safeLocalStorage.removeItem(`draft_input_${selectedProject.name}`);
+      safeLocalStorage.removeItem(`draft_input_${selectedProject.projectId}`);
     },
     [
       selectedSession,
@@ -680,6 +766,7 @@ export function useChatComposerState({
       cursorModel,
       executeCommand,
       geminiModel,
+      opencodeModel,
       isLoading,
       onSessionActive,
       onSessionProcessing,
@@ -709,27 +796,27 @@ export function useChatComposerState({
   }, [input]);
 
   useEffect(() => {
-    if (!selectedProject) {
+    if (!selectedProjectId) {
       return;
     }
-    const savedInput = safeLocalStorage.getItem(`draft_input_${selectedProject.name}`) || '';
+    const savedInput = safeLocalStorage.getItem(`draft_input_${selectedProjectId}`) || '';
     setInput((previous) => {
       const next = previous === savedInput ? previous : savedInput;
       inputValueRef.current = next;
       return next;
     });
-  }, [selectedProject?.name]);
+  }, [selectedProjectId]);
 
   useEffect(() => {
-    if (!selectedProject) {
+    if (!selectedProjectId) {
       return;
     }
     if (input !== '') {
-      safeLocalStorage.setItem(`draft_input_${selectedProject.name}`, input);
+      safeLocalStorage.setItem(`draft_input_${selectedProjectId}`, input);
     } else {
-      safeLocalStorage.removeItem(`draft_input_${selectedProject.name}`);
+      safeLocalStorage.removeItem(`draft_input_${selectedProjectId}`);
     }
-  }, [input, selectedProject]);
+  }, [input, selectedProjectId]);
 
   useEffect(() => {
     if (!textareaRef.current) {
@@ -850,21 +937,17 @@ export function useChatComposerState({
       return;
     }
 
-    const pendingSessionId =
-      typeof window !== 'undefined' ? sessionStorage.getItem('pendingSessionId') : null;
     const cursorSessionId =
       typeof window !== 'undefined' ? sessionStorage.getItem('cursorSessionId') : null;
 
     const candidateSessionIds = [
       currentSessionId,
-      pendingViewSessionRef.current?.sessionId || null,
-      pendingSessionId,
       provider === 'cursor' ? cursorSessionId : null,
       selectedSession?.id || null,
     ];
 
     const targetSessionId =
-      candidateSessionIds.find((sessionId) => Boolean(sessionId) && !isTemporarySessionId(sessionId)) || null;
+      candidateSessionIds.find((sessionId) => Boolean(sessionId)) || null;
 
     if (!targetSessionId) {
       console.warn('Abort requested but no concrete session ID is available yet.');
@@ -876,7 +959,7 @@ export function useChatComposerState({
       sessionId: targetSessionId,
       provider,
     });
-  }, [canAbortSession, currentSessionId, pendingViewSessionRef, provider, selectedSession?.id, sendMessage]);
+  }, [canAbortSession, currentSessionId, provider, selectedSession?.id, sendMessage]);
 
   const handleGrantToolPermission = useCallback(
     (suggestion: { entry: string; toolName: string }) => {
@@ -974,5 +1057,7 @@ export function useChatComposerState({
     handleGrantToolPermission,
     handleInputFocusChange,
     isInputFocused,
+    commandModalPayload,
+    closeCommandModal,
   };
 }
diff --git a/src/components/chat/hooks/useChatMessages.ts b/src/components/chat/hooks/useChatMessages.ts
index 8f417de5..1590c4af 100644
--- a/src/components/chat/hooks/useChatMessages.ts
+++ b/src/components/chat/hooks/useChatMessages.ts
@@ -11,8 +11,9 @@ import { decodeHtmlEntities, unescapeWithMathProtection, formatUsageLimitText }
  * Convert NormalizedMessage[] from the session store into ChatMessage[]
  * that the existing UI components expect.
  *
- * Internal/system content (e.g. <system-reminder>, <command-name>) is already
- * filtered server-side by the Claude provider module.
+ * Truly internal/system content is already filtered server-side. Some Claude
+ * transcript artifacts such as local slash commands and compact summaries are
+ * intentionally preserved and annotated so they can render like normal chat.
  */
 export function normalizedToChatMessages(messages: NormalizedMessage[]): ChatMessage[] {
   const converted: ChatMessage[] = [];
@@ -26,6 +27,16 @@ export function normalizedToChatMessages(messages: NormalizedMessage[]): ChatMes
   }
 
   for (const msg of messages) {
+    const sharedMetadata = {
+      displayText: msg.displayText,
+      commandName: msg.commandName,
+      commandMessage: msg.commandMessage,
+      commandArgs: msg.commandArgs,
+      isLocalCommand: msg.isLocalCommand,
+      isLocalCommandStdout: msg.isLocalCommandStdout,
+      isCompactSummary: msg.isCompactSummary,
+    };
+
     switch (msg.kind) {
       case 'text': {
         const content = msg.content || '';
@@ -42,12 +53,14 @@ export function normalizedToChatMessages(messages: NormalizedMessage[]): ChatMes
               timestamp: msg.timestamp,
               isTaskNotification: true,
               taskStatus: taskNotifMatch[1]?.trim() || 'completed',
+              ...sharedMetadata,
             });
           } else {
             converted.push({
               type: 'user',
               content: unescapeWithMathProtection(decodeHtmlEntities(content)),
               timestamp: msg.timestamp,
+              ...sharedMetadata,
             });
           }
         } else {
@@ -58,6 +71,7 @@ export function normalizedToChatMessages(messages: NormalizedMessage[]): ChatMes
             type: 'assistant',
             content: text,
             timestamp: msg.timestamp,
+            ...sharedMetadata,
           });
         }
         break;
@@ -106,6 +120,7 @@ export function normalizedToChatMessages(messages: NormalizedMessage[]): ChatMes
                 isComplete: Boolean(toolResult),
               }
             : undefined,
+          ...sharedMetadata,
         });
         break;
       }
@@ -117,6 +132,7 @@ export function normalizedToChatMessages(messages: NormalizedMessage[]): ChatMes
             content: unescapeWithMathProtection(msg.content),
             timestamp: msg.timestamp,
             isThinking: true,
+            ...sharedMetadata,
           });
         }
         break;
@@ -126,6 +142,7 @@ export function normalizedToChatMessages(messages: NormalizedMessage[]): ChatMes
           type: 'error',
           content: msg.content || 'Unknown error',
           timestamp: msg.timestamp,
+          ...sharedMetadata,
         });
         break;
 
@@ -135,6 +152,7 @@ export function normalizedToChatMessages(messages: NormalizedMessage[]): ChatMes
           content: msg.content || '',
           timestamp: msg.timestamp,
           isInteractivePrompt: true,
+          ...sharedMetadata,
         });
         break;
 
@@ -145,6 +163,7 @@ export function normalizedToChatMessages(messages: NormalizedMessage[]): ChatMes
           timestamp: msg.timestamp,
           isTaskNotification: true,
           taskStatus: msg.status || 'completed',
+          ...sharedMetadata,
         });
         break;
 
@@ -155,6 +174,7 @@ export function normalizedToChatMessages(messages: NormalizedMessage[]): ChatMes
             content: msg.content,
             timestamp: msg.timestamp,
             isStreaming: true,
+            ...sharedMetadata,
           });
         }
         break;
diff --git a/src/components/chat/hooks/useChatProviderState.ts b/src/components/chat/hooks/useChatProviderState.ts
index 6d39d22a..33c54d4b 100644
--- a/src/components/chat/hooks/useChatProviderState.ts
+++ b/src/components/chat/hooks/useChatProviderState.ts
@@ -1,42 +1,275 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { authenticatedFetch } from '../../../utils/api';
-import { CLAUDE_MODELS, CODEX_MODELS, CURSOR_MODELS, GEMINI_MODELS } from '../../../../shared/modelConstants';
 import type { PendingPermissionRequest, PermissionMode } from '../types/types';
-import type { ProjectSession, LLMProvider } from '../../../types/app';
+import type {
+  ProjectSession,
+  LLMProvider,
+  Project,
+  ProviderModelsCacheInfo,
+  ProviderModelsDefinition,
+} from '../../../types/app';
+
+const FALLBACK_DEFAULT_MODEL: Record<LLMProvider, string> = {
+  claude: 'opus',
+  cursor: 'gpt-5.3-codex',
+  codex: 'gpt-5.4',
+  gemini: 'gemini-3.1-pro-preview',
+  opencode: 'anthropic/claude-sonnet-4-5',
+};
+
+const getPermissionModesForProvider = (provider: LLMProvider): PermissionMode[] => {
+  if (provider === 'codex') {
+    return ['default', 'acceptEdits', 'bypassPermissions'];
+  }
+  if (provider === 'claude') {
+    return ['default', 'auto', 'acceptEdits', 'bypassPermissions', 'plan'];
+  }
+  if (provider === 'opencode') {
+    return ['default'];
+  }
+  return ['default', 'acceptEdits', 'bypassPermissions', 'plan'];
+};
 
 interface UseChatProviderStateArgs {
   selectedSession: ProjectSession | null;
+  selectedProject: Project | null;
 }
 
-export function useChatProviderState({ selectedSession }: UseChatProviderStateArgs) {
+type ProviderModelsApiResponse = {
+  success?: boolean;
+  data?: {
+    models?: ProviderModelsDefinition;
+    cache?: ProviderModelsCacheInfo;
+  };
+};
+
+type ChangeActiveModelApiResponse = {
+  success?: boolean;
+  data?: {
+    provider?: LLMProvider;
+    sessionId?: string;
+    supported?: boolean;
+    changed?: boolean;
+    model?: string | null;
+  };
+};
+
+export function useChatProviderState({ selectedSession, selectedProject }: UseChatProviderStateArgs) {
   const [permissionMode, setPermissionMode] = useState<PermissionMode>('default');
   const [pendingPermissionRequests, setPendingPermissionRequests] = useState<PendingPermissionRequest[]>([]);
   const [provider, setProvider] = useState<LLMProvider>(() => {
     return (localStorage.getItem('selected-provider') as LLMProvider) || 'claude';
   });
   const [cursorModel, setCursorModel] = useState<string>(() => {
-    return localStorage.getItem('cursor-model') || CURSOR_MODELS.DEFAULT;
+    return localStorage.getItem('cursor-model') || FALLBACK_DEFAULT_MODEL.cursor;
   });
   const [claudeModel, setClaudeModel] = useState<string>(() => {
-    return localStorage.getItem('claude-model') || CLAUDE_MODELS.DEFAULT;
+    return localStorage.getItem('claude-model') || FALLBACK_DEFAULT_MODEL.claude;
   });
   const [codexModel, setCodexModel] = useState<string>(() => {
-    return localStorage.getItem('codex-model') || CODEX_MODELS.DEFAULT;
+    return localStorage.getItem('codex-model') || FALLBACK_DEFAULT_MODEL.codex;
   });
   const [geminiModel, setGeminiModel] = useState<string>(() => {
-    return localStorage.getItem('gemini-model') || GEMINI_MODELS.DEFAULT;
+    return localStorage.getItem('gemini-model') || FALLBACK_DEFAULT_MODEL.gemini;
+  });
+  const [opencodeModel, setOpenCodeModel] = useState<string>(() => {
+    return localStorage.getItem('opencode-model') || FALLBACK_DEFAULT_MODEL.opencode;
   });
 
+  const [providerModelCatalog, setProviderModelCatalog] = useState<
+    Partial<Record<LLMProvider, ProviderModelsDefinition>>
+  >({});
+  const [providerModelCacheCatalog, setProviderModelCacheCatalog] = useState<
+    Partial<Record<LLMProvider, ProviderModelsCacheInfo>>
+  >({});
+  const [providerModelsLoading, setProviderModelsLoading] = useState(true);
+  const [providerModelsRefreshing, setProviderModelsRefreshing] = useState(false);
+
   const lastProviderRef = useRef(provider);
+  const providerModelsRequestIdRef = useRef(0);
+
+  const setStoredProviderModel = useCallback((targetProvider: LLMProvider, model: string) => {
+    if (targetProvider === 'claude') {
+      setClaudeModel(model);
+      localStorage.setItem('claude-model', model);
+      return;
+    }
+
+    if (targetProvider === 'cursor') {
+      setCursorModel(model);
+      localStorage.setItem('cursor-model', model);
+      return;
+    }
+
+    if (targetProvider === 'codex') {
+      setCodexModel(model);
+      localStorage.setItem('codex-model', model);
+      return;
+    }
+
+    if (targetProvider === 'gemini') {
+      setGeminiModel(model);
+      localStorage.setItem('gemini-model', model);
+      return;
+    }
+
+    setOpenCodeModel(model);
+    localStorage.setItem('opencode-model', model);
+  }, []);
+
+  const loadProviderModels = useCallback(async (options: { bypassCache?: boolean } = {}) => {
+    const providers: LLMProvider[] = ['claude', 'cursor', 'codex', 'gemini', 'opencode'];
+    const requestId = providerModelsRequestIdRef.current + 1;
+    providerModelsRequestIdRef.current = requestId;
+    const isHardRefresh = options.bypassCache === true;
+
+    if (isHardRefresh) {
+      setProviderModelsRefreshing(true);
+    } else {
+      setProviderModelsLoading(true);
+    }
+
+    try {
+      const results = await Promise.all(
+        providers.map(async (p) => {
+          const params = new URLSearchParams();
+          if (options.bypassCache) {
+            params.set('bypassCache', 'true');
+          }
+
+          const queryString = params.toString();
+          const response = await authenticatedFetch(`/api/providers/${p}/models${queryString ? `?${queryString}` : ''}`);
+          const body = (await response.json()) as ProviderModelsApiResponse;
+          if (!body.success || !body.data?.models || !body.data?.cache) {
+            return null;
+          }
+
+          return body.data;
+        }),
+      );
+
+      if (providerModelsRequestIdRef.current !== requestId) {
+        return;
+      }
+
+      const nextCatalog: Partial<Record<LLMProvider, ProviderModelsDefinition>> = {};
+      const nextCacheCatalog: Partial<Record<LLMProvider, ProviderModelsCacheInfo>> = {};
+
+      providers.forEach((p, i) => {
+        const entry = results[i];
+        if (!entry) {
+          return;
+        }
+
+        nextCatalog[p] = entry.models;
+        nextCacheCatalog[p] = entry.cache;
+      });
+
+      setProviderModelCatalog(nextCatalog);
+      setProviderModelCacheCatalog(nextCacheCatalog);
+    } catch (error) {
+      console.error('Error loading provider models:', error);
+    } finally {
+      if (providerModelsRequestIdRef.current === requestId) {
+        setProviderModelsLoading(false);
+        setProviderModelsRefreshing(false);
+      }
+    }
+  }, []);
+
+  useEffect(() => {
+    void loadProviderModels();
+  }, [loadProviderModels]);
+
+  const pickStoredOrCurrent = (
+    storageKey: string,
+    current: string,
+    def: ProviderModelsDefinition,
+  ): string => {
+    const stored = localStorage.getItem(storageKey);
+    if (stored && def.OPTIONS.some((o) => o.value === stored)) {
+      return stored;
+    }
+    if (current && def.OPTIONS.some((o) => o.value === current)) {
+      return current;
+    }
+    return def.DEFAULT;
+  };
+
+  useEffect(() => {
+    const claude = providerModelCatalog.claude;
+    if (claude) {
+      const next = pickStoredOrCurrent('claude-model', claudeModel, claude);
+      if (next !== claudeModel) {
+        setClaudeModel(next);
+      }
+      if (localStorage.getItem('claude-model') !== next) {
+        localStorage.setItem('claude-model', next);
+      }
+    }
+  }, [providerModelCatalog.claude, claudeModel]);
+
+  useEffect(() => {
+    const cursor = providerModelCatalog.cursor;
+    if (cursor) {
+      const next = pickStoredOrCurrent('cursor-model', cursorModel, cursor);
+      if (next !== cursorModel) {
+        setCursorModel(next);
+      }
+      if (localStorage.getItem('cursor-model') !== next) {
+        localStorage.setItem('cursor-model', next);
+      }
+    }
+  }, [providerModelCatalog.cursor, cursorModel]);
+
+  useEffect(() => {
+    const codex = providerModelCatalog.codex;
+    if (codex) {
+      const next = pickStoredOrCurrent('codex-model', codexModel, codex);
+      if (next !== codexModel) {
+        setCodexModel(next);
+      }
+      if (localStorage.getItem('codex-model') !== next) {
+        localStorage.setItem('codex-model', next);
+      }
+    }
+  }, [providerModelCatalog.codex, codexModel]);
+
+  useEffect(() => {
+    const gemini = providerModelCatalog.gemini;
+    if (gemini) {
+      const next = pickStoredOrCurrent('gemini-model', geminiModel, gemini);
+      if (next !== geminiModel) {
+        setGeminiModel(next);
+      }
+      if (localStorage.getItem('gemini-model') !== next) {
+        localStorage.setItem('gemini-model', next);
+      }
+    }
+  }, [providerModelCatalog.gemini, geminiModel]);
+
+  useEffect(() => {
+    const opencode = providerModelCatalog.opencode;
+    if (opencode) {
+      const next = pickStoredOrCurrent('opencode-model', opencodeModel, opencode);
+      if (next !== opencodeModel) {
+        setOpenCodeModel(next);
+      }
+      if (localStorage.getItem('opencode-model') !== next) {
+        localStorage.setItem('opencode-model', next);
+      }
+    }
+  }, [providerModelCatalog.opencode, opencodeModel]);
 
   useEffect(() => {
     if (!selectedSession?.id) {
       return;
     }
 
-    const savedMode = localStorage.getItem(`permissionMode-${selectedSession.id}`);
-    setPermissionMode((savedMode as PermissionMode) || 'default');
-  }, [selectedSession?.id]);
+    const savedMode = localStorage.getItem(`permissionMode-${selectedSession.id}`) as PermissionMode | null;
+    const validModes = getPermissionModesForProvider(provider);
+    setPermissionMode(savedMode && validModes.includes(savedMode) ? savedMode : 'default');
+  }, [selectedSession?.id, provider]);
 
   useEffect(() => {
     if (!selectedSession?.__provider || selectedSession.__provider === provider) {
@@ -84,10 +317,7 @@ export function useChatProviderState({ selectedSession }: UseChatProviderStateAr
   }, [provider]);
 
   const cyclePermissionMode = useCallback(() => {
-    const modes: PermissionMode[] =
-      provider === 'codex'
-        ? ['default', 'acceptEdits', 'bypassPermissions']
-        : ['default', 'acceptEdits', 'bypassPermissions', 'plan'];
+    const modes = getPermissionModesForProvider(provider);
 
     const currentIndex = modes.indexOf(permissionMode);
     const nextIndex = (currentIndex + 1) % modes.length;
@@ -99,6 +329,41 @@ export function useChatProviderState({ selectedSession }: UseChatProviderStateAr
     }
   }, [permissionMode, provider, selectedSession?.id]);
 
+  const selectProviderModel = useCallback(async (
+    targetProvider: LLMProvider,
+    model: string,
+    sessionId?: string | null,
+  ) => {
+    const normalizedSessionId = typeof sessionId === 'string' ? sessionId.trim() : '';
+    if (!normalizedSessionId) {
+      setStoredProviderModel(targetProvider, model);
+      return {
+        scope: 'default' as const,
+        changed: false,
+        model,
+      };
+    }
+
+    const response = await authenticatedFetch(
+      `/api/providers/${targetProvider}/sessions/${encodeURIComponent(normalizedSessionId)}/active-model`,
+      {
+        method: 'POST',
+        body: JSON.stringify({ model }),
+      },
+    );
+
+    const body = (await response.json()) as ChangeActiveModelApiResponse;
+    if (!response.ok || !body.success || !body.data?.supported) {
+      throw new Error('Unable to change the active model for this session.');
+    }
+
+    return {
+      scope: 'session' as const,
+      changed: body.data.changed === true,
+      model: body.data.model || model,
+    };
+  }, [setStoredProviderModel]);
+
   return {
     provider,
     setProvider,
@@ -110,10 +375,18 @@ export function useChatProviderState({ selectedSession }: UseChatProviderStateAr
     setCodexModel,
     geminiModel,
     setGeminiModel,
+    opencodeModel,
+    setOpenCodeModel,
     permissionMode,
     setPermissionMode,
     pendingPermissionRequests,
     setPendingPermissionRequests,
     cyclePermissionMode,
+    providerModelCatalog,
+    providerModelCacheCatalog,
+    providerModelsLoading,
+    providerModelsRefreshing,
+    hardRefreshProviderModels: () => loadProviderModels({ bypassCache: true }),
+    selectProviderModel,
   };
 }
diff --git a/src/components/chat/hooks/useChatRealtimeHandlers.ts b/src/components/chat/hooks/useChatRealtimeHandlers.ts
index 73d1a5e7..6a5a1b81 100644
--- a/src/components/chat/hooks/useChatRealtimeHandlers.ts
+++ b/src/components/chat/hooks/useChatRealtimeHandlers.ts
@@ -1,11 +1,12 @@
 import { useEffect, useRef } from 'react';
 import type { Dispatch, MutableRefObject, SetStateAction } from 'react';
-import type { PendingPermissionRequest } from '../types/types';
-import type { Project, ProjectSession, LLMProvider } from '../../../types/app';
+
+import { usePaletteOps } from '../../../contexts/PaletteOpsContext';
+import type { PendingPermissionRequest, SessionNavigationOptions } from '../types/types';
+import type { ProjectSession, LLMProvider } from '../../../types/app';
 import type { SessionStore, NormalizedMessage } from '../../../stores/useSessionStore';
 
 type PendingViewSession = {
-  sessionId: string | null;
   startedAt: number;
 };
 
@@ -49,7 +50,6 @@ type LatestChatMessage = {
 interface UseChatRealtimeHandlersArgs {
   latestMessage: LatestChatMessage | null;
   provider: LLMProvider;
-  selectedProject: Project | null;
   selectedSession: ProjectSession | null;
   currentSessionId: string | null;
   setCurrentSessionId: (sessionId: string | null) => void;
@@ -59,14 +59,13 @@ interface UseChatRealtimeHandlersArgs {
   setTokenBudget: (budget: Record<string, unknown> | null) => void;
   setPendingPermissionRequests: Dispatch<SetStateAction<PendingPermissionRequest[]>>;
   pendingViewSessionRef: MutableRefObject<PendingViewSession | null>;
-  streamBufferRef: MutableRefObject<string>;
   streamTimerRef: MutableRefObject<number | null>;
   accumulatedStreamRef: MutableRefObject<string>;
   onSessionInactive?: (sessionId?: string | null) => void;
+  onSessionActive?: (sessionId?: string | null) => void;
   onSessionProcessing?: (sessionId?: string | null) => void;
   onSessionNotProcessing?: (sessionId?: string | null) => void;
-  onReplaceTemporarySession?: (sessionId?: string | null) => void;
-  onNavigateToSession?: (sessionId: string) => void;
+  onNavigateToSession?: (sessionId: string, options?: SessionNavigationOptions) => void;
   onWebSocketReconnect?: () => void;
   sessionStore: SessionStore;
 }
@@ -78,7 +77,6 @@ interface UseChatRealtimeHandlersArgs {
 export function useChatRealtimeHandlers({
   latestMessage,
   provider,
-  selectedProject,
   selectedSession,
   currentSessionId,
   setCurrentSessionId,
@@ -88,17 +86,17 @@ export function useChatRealtimeHandlers({
   setTokenBudget,
   setPendingPermissionRequests,
   pendingViewSessionRef,
-  streamBufferRef,
   streamTimerRef,
   accumulatedStreamRef,
   onSessionInactive,
+  onSessionActive,
   onSessionProcessing,
   onSessionNotProcessing,
-  onReplaceTemporarySession,
   onNavigateToSession,
   onWebSocketReconnect,
   sessionStore,
 }: UseChatRealtimeHandlersArgs) {
+  const paletteOps = usePaletteOps();
   const lastProcessedMessageRef = useRef<LatestChatMessage | null>(null);
 
   useEffect(() => {
@@ -107,7 +105,7 @@ export function useChatRealtimeHandlers({
     lastProcessedMessageRef.current = latestMessage;
 
     const activeViewSessionId =
-      selectedSession?.id || currentSessionId || pendingViewSessionRef.current?.sessionId || null;
+      selectedSession?.id || currentSessionId || null;
 
     /* ---------------------------------------------------------------- */
     /*  Legacy messages (no `kind` field) — handle and return           */
@@ -154,10 +152,12 @@ export function useChatRealtimeHandlers({
             statusSessionId === currentSessionId || (selectedSession && statusSessionId === selectedSession.id);
 
           if (msg.isProcessing) {
+            onSessionActive?.(statusSessionId);
             onSessionProcessing?.(statusSessionId);
             if (isCurrentSession) { setIsLoading(true); setCanAbortSession(true); }
             return;
           }
+
           onSessionInactive?.(statusSessionId);
           onSessionNotProcessing?.(statusSessionId);
           if (isCurrentSession) {
@@ -184,7 +184,6 @@ export function useChatRealtimeHandlers({
     if (msg.kind === 'stream_delta') {
       const text = msg.content || '';
       if (!text) return;
-      streamBufferRef.current += text;
       accumulatedStreamRef.current += text;
       if (!streamTimerRef.current) {
         streamTimerRef.current = window.setTimeout(() => {
@@ -213,12 +212,18 @@ export function useChatRealtimeHandlers({
         sessionStore.finalizeStreaming(sid);
       }
       accumulatedStreamRef.current = '';
-      streamBufferRef.current = '';
       return;
     }
 
     // --- All other messages: route to store ---
-    if (sid) {
+    const shouldPersist =
+      msg.kind !== 'session_created'
+      && msg.kind !== 'complete'
+      && msg.kind !== 'status'
+      && msg.kind !== 'permission_request'
+      && msg.kind !== 'permission_cancelled';
+
+    if (sid && shouldPersist) {
       sessionStore.appendRealtime(sid, msg as NormalizedMessage);
     }
 
@@ -228,17 +233,26 @@ export function useChatRealtimeHandlers({
         const newSessionId = msg.newSessionId;
         if (!newSessionId) break;
 
-        if (!currentSessionId || currentSessionId.startsWith('new-session-')) {
-          sessionStorage.setItem('pendingSessionId', newSessionId);
-          if (pendingViewSessionRef.current && !pendingViewSessionRef.current.sessionId) {
-            pendingViewSessionRef.current.sessionId = newSessionId;
-          }
+        // We no longer synthesize client-side placeholder IDs. Until the provider
+        // announces `session_created`, the active id is expected to be null.
+        if (!currentSessionId) {
+          console.log('Session created with ID:', newSessionId);
+          console.log('Existing session ID:', currentSessionId);
           setCurrentSessionId(newSessionId);
-          onReplaceTemporarySession?.(newSessionId);
           setPendingPermissionRequests((prev) =>
             prev.map((r) => (r.sessionId ? r : { ...r, sessionId: newSessionId })),
           );
         }
+        pendingViewSessionRef.current = null;
+        onSessionActive?.(newSessionId);
+        onSessionProcessing?.(newSessionId);
+        setIsLoading(true);
+        setCanAbortSession(true);
+        setClaudeStatus({
+          text: 'Processing',
+          tokens: 0,
+          can_interrupt: true,
+        });
         onNavigateToSession?.(newSessionId);
         break;
       }
@@ -254,7 +268,6 @@ export function useChatRealtimeHandlers({
           sessionStore.finalizeStreaming(sid);
         }
         accumulatedStreamRef.current = '';
-        streamBufferRef.current = '';
 
         setIsLoading(false);
         setCanAbortSession(false);
@@ -262,6 +275,7 @@ export function useChatRealtimeHandlers({
         setPendingPermissionRequests([]);
         onSessionInactive?.(sid);
         onSessionNotProcessing?.(sid);
+        pendingViewSessionRef.current = null;
 
         // Handle aborted case
         if (msg.aborted) {
@@ -271,19 +285,30 @@ export function useChatRealtimeHandlers({
           break;
         }
 
-        // Clear pending session
-        const pendingSessionId = sessionStorage.getItem('pendingSessionId');
-        if (pendingSessionId && !currentSessionId && msg.exitCode === 0) {
-          const actualId = msg.actualSessionId || pendingSessionId;
-          setCurrentSessionId(actualId);
-          if (msg.actualSessionId) {
-            onNavigateToSession?.(actualId);
+        const actualSessionId =
+          typeof msg.actualSessionId === 'string' && msg.actualSessionId.trim().length > 0
+            ? msg.actualSessionId
+            : null;
+        const isVisibleSession =
+          Boolean(
+            sid
+            && sid === activeViewSessionId,
+          );
+
+        if (actualSessionId && sid && actualSessionId !== sid) {
+          sessionStore.replaceSessionId(sid, actualSessionId);
+
+          if (isVisibleSession) {
+            setCurrentSessionId(actualSessionId);
           }
-          sessionStorage.removeItem('pendingSessionId');
-          if (window.refreshProjects) {
-            setTimeout(() => window.refreshProjects?.(), 500);
+
+          if (isVisibleSession) {
+            onNavigateToSession?.(actualSessionId, { replace: true });
+            setTimeout(() => { void paletteOps.refreshProjects(); }, 500);
           }
+          break;
         }
+
         break;
       }
 
@@ -293,6 +318,7 @@ export function useChatRealtimeHandlers({
         setClaudeStatus(null);
         onSessionInactive?.(sid);
         onSessionNotProcessing?.(sid);
+        pendingViewSessionRef.current = null;
         break;
       }
 
@@ -345,7 +371,6 @@ export function useChatRealtimeHandlers({
   }, [
     latestMessage,
     provider,
-    selectedProject,
     selectedSession,
     currentSessionId,
     setCurrentSessionId,
@@ -355,15 +380,15 @@ export function useChatRealtimeHandlers({
     setTokenBudget,
     setPendingPermissionRequests,
     pendingViewSessionRef,
-    streamBufferRef,
     streamTimerRef,
     accumulatedStreamRef,
     onSessionInactive,
+    onSessionActive,
     onSessionProcessing,
     onSessionNotProcessing,
-    onReplaceTemporarySession,
     onNavigateToSession,
     onWebSocketReconnect,
     sessionStore,
+    paletteOps,
   ]);
 }
diff --git a/src/components/chat/hooks/useChatSessionState.ts b/src/components/chat/hooks/useChatSessionState.ts
index b551060a..20f42551 100644
--- a/src/components/chat/hooks/useChatSessionState.ts
+++ b/src/components/chat/hooks/useChatSessionState.ts
@@ -1,17 +1,18 @@
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import type { MutableRefObject } from 'react';
+
 import { authenticatedFetch } from '../../../utils/api';
-import type { ChatMessage, Provider } from '../types/types';
 import type { Project, ProjectSession, LLMProvider } from '../../../types/app';
-import { createCachedDiffCalculator, type DiffCalculator } from '../utils/messageTransforms';
-import { normalizedToChatMessages } from './useChatMessages';
 import type { SessionStore, NormalizedMessage } from '../../../stores/useSessionStore';
+import type { ChatMessage, Provider } from '../types/types';
+import { createCachedDiffCalculator, type DiffCalculator } from '../utils/messageTransforms';
+
+import { normalizedToChatMessages } from './useChatMessages';
 
 const MESSAGES_PER_PAGE = 20;
 const INITIAL_VISIBLE_MESSAGES = 100;
 
 type PendingViewSession = {
-  sessionId: string | null;
   startedAt: number;
 };
 
@@ -22,6 +23,7 @@ interface UseChatSessionStateArgs {
   sendMessage: (message: unknown) => void;
   autoScrollToBottom?: boolean;
   externalMessageUpdate?: number;
+  newSessionTrigger?: number;
   processingSessions?: Set<string>;
   resetStreamingState: () => void;
   pendingViewSessionRef: MutableRefObject<PendingViewSession | null>;
@@ -95,6 +97,7 @@ export function useChatSessionState({
   sendMessage,
   autoScrollToBottom,
   externalMessageUpdate,
+  newSessionTrigger,
   processingSessions,
   resetStreamingState,
   pendingViewSessionRef,
@@ -131,15 +134,85 @@ export function useChatSessionState({
   const loadAllFinishedTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const loadAllOverlayTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const lastLoadedSessionKeyRef = useRef<string | null>(null);
+  /**
+   * Tracks the last processed value from `useProjectsState.newSessionTrigger`.
+   *
+   * The trigger itself is intentionally increment-only and routed via:
+   * useProjectsState -> AppContent -> MainContent -> ChatInterface -> this hook.
+   * We compare values to ensure each explicit New Session click runs exactly one
+   * reset pass in this local chat state domain.
+   */
+  const previousNewSessionTriggerRef = useRef(newSessionTrigger ?? 0);
 
   const createDiff = useMemo<DiffCalculator>(() => createCachedDiffCalculator(), []);
 
+  useEffect(() => {
+    const trigger = newSessionTrigger ?? 0;
+    if (trigger === previousNewSessionTriggerRef.current) {
+      return;
+    }
+    previousNewSessionTriggerRef.current = trigger;
+
+    /**
+     * Consumer-side reset for explicit New Session intent.
+     *
+     * Why this is essential:
+     * - Chat keeps local state that is not fully derived from `selectedSession`:
+     *   `currentSessionId`, `pendingUserMessage`, streaming/status flags, message
+     *   pagination/scroll bookkeeping, and provider-specific sessionStorage keys.
+     * - If the user clicks New Session while already on the same route with no
+     *   selected session, parent state updates can be idempotent and this local
+     *   state would otherwise persist, making the click appear to "do nothing".
+     *
+     * What this reset guarantees:
+     * - A deterministic clean draft state on every New Session click.
+     * - No dependence on route/tab/session-object identity changes.
+     * - No coupling to unrelated external update signals.
+     */
+    resetStreamingState();
+    pendingViewSessionRef.current = null;
+    setClaudeStatus(null);
+    setCanAbortSession(false);
+    setIsLoading(false);
+    setCurrentSessionId(null);
+    setPendingUserMessage(null);
+    sessionStorage.removeItem('cursorSessionId');
+    messagesOffsetRef.current = 0;
+    setHasMoreMessages(false);
+    setTotalMessages(0);
+    
+    setTokenBudget(null);
+    setVisibleMessageCount(INITIAL_VISIBLE_MESSAGES);
+    setAllMessagesLoaded(false);
+    allMessagesLoadedRef.current = false;
+    setIsLoadingAllMessages(false);
+    setLoadAllJustFinished(false);
+    setShowLoadAllOverlay(false);
+    setViewHiddenCount(0);
+    setSearchTarget(null);
+    searchScrollActiveRef.current = false;
+    topLoadLockRef.current = false;
+    pendingScrollRestoreRef.current = null;
+    pendingInitialScrollRef.current = true;
+    lastLoadedSessionKeyRef.current = null;
+
+    if (loadAllOverlayTimerRef.current) {
+      clearTimeout(loadAllOverlayTimerRef.current);
+      loadAllOverlayTimerRef.current = null;
+    }
+    if (loadAllFinishedTimerRef.current) {
+      clearTimeout(loadAllFinishedTimerRef.current);
+      loadAllFinishedTimerRef.current = null;
+    }
+  }, [newSessionTrigger, pendingViewSessionRef, resetStreamingState]);
+
   /* ---------------------------------------------------------------- */
   /*  Derive chatMessages from the store                              */
   /* ---------------------------------------------------------------- */
 
   const activeSessionId = selectedSession?.id || currentSessionId || null;
   const [pendingUserMessage, setPendingUserMessage] = useState<ChatMessage | null>(null);
+  const flushedPendingUserMessageRef = useRef<ChatMessage | null>(null);
 
   // Tell the store which session we're viewing so it only re-renders for this one
   const prevActiveForStoreRef = useRef<string | null>(null);
@@ -148,17 +221,29 @@ export function useChatSessionState({
     sessionStore.setActiveSession(activeSessionId);
   }
 
-  // When a real session ID arrives and we have a pending user message, flush it to the store
-  const prevActiveSessionRef = useRef<string | null>(null);
-  if (activeSessionId && activeSessionId !== prevActiveSessionRef.current && pendingUserMessage) {
+  useEffect(() => {
+    if (!pendingUserMessage) {
+      flushedPendingUserMessageRef.current = null;
+      return;
+    }
+
+    if (!activeSessionId) {
+      return;
+    }
+
+    if (flushedPendingUserMessageRef.current === pendingUserMessage) {
+      return;
+    }
+
     const prov = (localStorage.getItem('selected-provider') as LLMProvider) || 'claude';
     const normalized = chatMessageToNormalized(pendingUserMessage, activeSessionId, prov);
     if (normalized) {
       sessionStore.appendRealtime(activeSessionId, normalized);
     }
+
+    flushedPendingUserMessageRef.current = pendingUserMessage;
     setPendingUserMessage(null);
-  }
-  prevActiveSessionRef.current = activeSessionId;
+  }, [activeSessionId, pendingUserMessage, sessionStore]);
 
   const storeMessages = activeSessionId ? sessionStore.getMessages(activeSessionId) : [];
 
@@ -232,7 +317,6 @@ export function useChatSessionState({
       if (!hasMoreMessages || !selectedSession || !selectedProject) return false;
 
       const sessionProvider = selectedSession.__provider || 'claude';
-      if (sessionProvider === 'cursor') return false;
 
       isLoadingMoreRef.current = true;
       const previousScrollHeight = container.scrollHeight;
@@ -241,7 +325,8 @@ export function useChatSessionState({
       try {
         const slot = await sessionStore.fetchMore(selectedSession.id, {
           provider: sessionProvider as LLMProvider,
-          projectName: selectedProject.name,
+          // DB-assigned projectId replaces the legacy folder-derived name.
+          projectId: selectedProject.projectId,
           projectPath: selectedProject.fullPath || selectedProject.path || '',
           limit: MESSAGES_PER_PAGE,
         });
@@ -296,7 +381,7 @@ export function useChatSessionState({
     topLoadLockRef.current = false;
     pendingScrollRestoreRef.current = null;
     setIsUserScrolledUp(false);
-  }, [selectedProject?.name, selectedSession?.id]);
+  }, [selectedProject?.projectId, selectedSession?.id]);
 
   // Initial scroll to bottom
   useEffect(() => {
@@ -309,6 +394,12 @@ export function useChatSessionState({
   // Main session loading effect — store-based
   useEffect(() => {
     if (!selectedSession || !selectedProject) {
+      // A new provider run can be in flight before the router has a canonical
+      // selectedSession. Keep the processing banner alive until complete/error.
+      if (pendingViewSessionRef.current) {
+        return;
+      }
+
       resetStreamingState();
       pendingViewSessionRef.current = null;
       setClaudeStatus(null);
@@ -325,7 +416,7 @@ export function useChatSessionState({
     }
 
     const provider = (selectedSession.__provider || localStorage.getItem('selected-provider') as Provider) || 'claude';
-    const sessionKey = `${selectedSession.id}:${selectedProject.name}:${provider}`;
+    const sessionKey = `${selectedSession.id}:${selectedProject.projectId}:${provider}`;
 
     // Skip if already loaded and fresh
     if (lastLoadedSessionKeyRef.current === sessionKey && sessionStore.has(selectedSession.id) && !sessionStore.isStale(selectedSession.id)) {
@@ -375,7 +466,7 @@ export function useChatSessionState({
     setIsLoadingSessionMessages(true);
     sessionStore.fetchFromServer(selectedSession.id, {
       provider: (selectedSession.__provider || provider) as LLMProvider,
-      projectName: selectedProject.name,
+      projectId: selectedProject.projectId,
       projectPath: selectedProject.fullPath || selectedProject.path || '',
       limit: MESSAGES_PER_PAGE,
       offset: 0,
@@ -411,7 +502,7 @@ export function useChatSessionState({
         if (!isLoading) {
           await sessionStore.refreshFromServer(selectedSession.id, {
             provider: (selectedSession.__provider || provider) as LLMProvider,
-            projectName: selectedProject.name,
+            projectId: selectedProject.projectId,
             projectPath: selectedProject.fullPath || selectedProject.path || '',
           });
 
@@ -450,10 +541,6 @@ export function useChatSessionState({
     }
   }, [selectedSession]);
 
-  useEffect(() => {
-    if (selectedSession?.id) pendingViewSessionRef.current = null;
-  }, [pendingViewSessionRef, selectedSession?.id]);
-
   // Scroll to search target
   useEffect(() => {
     if (!searchTarget || chatMessages.length === 0 || isLoadingSessionMessages) return;
@@ -464,12 +551,11 @@ export function useChatSessionState({
     const scrollToTarget = async () => {
       if (!allMessagesLoadedRef.current && selectedSession && selectedProject) {
         const sessionProvider = selectedSession.__provider || 'claude';
-        if (sessionProvider !== 'cursor') {
           try {
             // Load all messages into the store for search navigation
             const slot = await sessionStore.fetchFromServer(selectedSession.id, {
               provider: sessionProvider as LLMProvider,
-              projectName: selectedProject.name,
+              projectId: selectedProject.projectId,
               projectPath: selectedProject.fullPath || selectedProject.path || '',
               limit: null,
               offset: 0,
@@ -486,7 +572,6 @@ export function useChatSessionState({
           } catch {
             // Fall through and scroll in current messages
           }
-        }
       }
       setVisibleMessageCount(Infinity);
 
@@ -539,18 +624,23 @@ export function useChatSessionState({
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [chatMessages.length, isLoadingSessionMessages, searchTarget]);
 
-  // Token usage fetch for Claude
+  // Initial token usage fetch for providers with file-backed usage data.
   useEffect(() => {
-    if (!selectedProject || !selectedSession?.id || selectedSession.id.startsWith('new-session-')) {
+    if (!selectedProject || !selectedSession?.id) {
       setTokenBudget(null);
       return;
     }
     const sessionProvider = selectedSession.__provider || 'claude';
-    if (sessionProvider !== 'claude') return;
+    if (sessionProvider !== 'claude' && sessionProvider !== 'codex' && sessionProvider !== 'gemini' && sessionProvider !== 'opencode') {
+      setTokenBudget(null);
+      return;
+    }
 
     const fetchInitialTokenUsage = async () => {
       try {
-        const url = `/api/projects/${selectedProject.name}/sessions/${selectedSession.id}/token-usage`;
+        // Token usage endpoint is now keyed by the DB projectId.
+        const params = new URLSearchParams({ provider: sessionProvider });
+        const url = `/api/projects/${selectedProject.projectId}/sessions/${selectedSession.id}/token-usage?${params.toString()}`;
         const response = await authenticatedFetch(url);
         if (response.ok) {
           setTokenBudget(await response.json());
@@ -633,15 +723,6 @@ export function useChatSessionState({
     if (!selectedSession || !selectedProject) return;
     if (isLoadingAllMessages) return;
     const sessionProvider = selectedSession.__provider || 'claude';
-    if (sessionProvider === 'cursor') {
-      setVisibleMessageCount(Infinity);
-      setAllMessagesLoaded(true);
-      allMessagesLoadedRef.current = true;
-      setLoadAllJustFinished(true);
-      if (loadAllFinishedTimerRef.current) clearTimeout(loadAllFinishedTimerRef.current);
-      loadAllFinishedTimerRef.current = setTimeout(() => { setLoadAllJustFinished(false); setShowLoadAllOverlay(false); }, 1000);
-      return;
-    }
 
     const requestSessionId = selectedSession.id;
     allMessagesLoadedRef.current = true;
@@ -656,7 +737,7 @@ export function useChatSessionState({
     try {
       const slot = await sessionStore.fetchFromServer(requestSessionId, {
         provider: sessionProvider as LLMProvider,
-        projectName: selectedProject.name,
+        projectId: selectedProject.projectId,
         projectPath: selectedProject.fullPath || selectedProject.path || '',
         limit: null,
         offset: 0,
diff --git a/src/components/chat/hooks/useFileMentions.tsx b/src/components/chat/hooks/useFileMentions.tsx
index c53f4c7b..4061605d 100644
--- a/src/components/chat/hooks/useFileMentions.tsx
+++ b/src/components/chat/hooks/useFileMentions.tsx
@@ -59,16 +59,18 @@ export function useFileMentions({ selectedProject, input, setInput, textareaRef
     const abortController = new AbortController();
 
     const fetchProjectFiles = async () => {
-      const projectName = selectedProject?.name;
+      // File list is keyed by DB projectId now; the backend resolves it to
+      // the project's path before reading.
+      const projectId = selectedProject?.projectId;
       setFileList([]);
       setFilteredFiles([]);
-      if (!projectName) {
+      if (!projectId) {
         return;
       }
 
 
       try {
-        const response = await api.getFiles(projectName, { signal: abortController.signal });
+        const response = await api.getFiles(projectId, { signal: abortController.signal });
         if (!response.ok) {
           return;
         }
@@ -88,7 +90,7 @@ export function useFileMentions({ selectedProject, input, setInput, textareaRef
     return () => {
       abortController.abort();
     };
-  }, [selectedProject?.name]);
+  }, [selectedProject?.projectId]);
 
   useEffect(() => {
     const textBeforeCursor = input.slice(0, cursorPosition);
diff --git a/src/components/chat/hooks/useSlashCommands.ts b/src/components/chat/hooks/useSlashCommands.ts
index 067cd24d..db6eefaa 100644
--- a/src/components/chat/hooks/useSlashCommands.ts
+++ b/src/components/chat/hooks/useSlashCommands.ts
@@ -1,9 +1,9 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type { Dispatch, KeyboardEvent, RefObject, SetStateAction } from 'react';
-import Fuse from 'fuse.js';
+
 import { authenticatedFetch } from '../../../utils/api';
 import { safeLocalStorage } from '../utils/chatStorage';
-import type { Project } from '../../../types/app';
+import type { LLMProvider, Project } from '../../../types/app';
 
 const COMMAND_QUERY_DEBOUNCE_MS = 150;
 
@@ -12,19 +12,37 @@ export interface SlashCommand {
   description?: string;
   namespace?: string;
   path?: string;
-  type?: string;
+  type?: 'built-in' | 'custom' | 'skill' | string;
   metadata?: Record<string, unknown>;
   [key: string]: unknown;
 }
 
 interface UseSlashCommandsOptions {
   selectedProject: Project | null;
+  provider: LLMProvider;
   input: string;
   setInput: Dispatch<SetStateAction<string>>;
   textareaRef: RefObject<HTMLTextAreaElement>;
   onExecuteCommand: (command: SlashCommand, rawInput?: string) => void | Promise<void>;
 }
 
+type ProviderSkill = {
+  name: string;
+  description?: string;
+  command: string;
+  scope: string;
+  sourcePath?: string;
+  pluginName?: string;
+  pluginId?: string;
+};
+
+type ProviderSkillsResponse = {
+  success?: boolean;
+  data?: {
+    skills?: ProviderSkill[];
+  };
+};
+
 const getCommandHistoryKey = (projectName: string) => `command_history_${projectName}`;
 
 const readCommandHistory = (projectName: string): Record<string, number> => {
@@ -48,8 +66,78 @@ const saveCommandHistory = (projectName: string, history: Record<string, number>
 const isPromiseLike = (value: unknown): value is Promise<unknown> =>
   Boolean(value) && typeof (value as Promise<unknown>).then === 'function';
 
+const isSkillCommand = (command: SlashCommand) =>
+  command.type === 'skill' || command.metadata?.type === 'skill';
+
+const dedupeProviderSkills = (skills: ProviderSkill[]): ProviderSkill[] => {
+  const seenCommands = new Set<string>();
+
+  return skills.filter((skill) => {
+    // Multiple physical Claude plugin folders can expose the same invocation.
+    // The slash menu should show each executable command only once.
+    const key = skill.command;
+    if (seenCommands.has(key)) {
+      return false;
+    }
+
+    seenCommands.add(key);
+    return true;
+  });
+};
+
+const mapSkillToSlashCommand = (skill: ProviderSkill): SlashCommand => ({
+  name: skill.command,
+  description: skill.description,
+  namespace: 'skill',
+  path: skill.sourcePath,
+  type: 'skill',
+  metadata: {
+    type: skill.scope,
+    scope: skill.scope,
+    sourcePath: skill.sourcePath,
+    pluginName: skill.pluginName,
+    pluginId: skill.pluginId,
+    skillName: skill.name,
+  },
+});
+
+const filterSlashCommands = (
+  commands: SlashCommand[],
+  query: string,
+): SlashCommand[] => {
+  const normalizedQuery = query.trim().toLowerCase();
+  if (!normalizedQuery) {
+    return commands;
+  }
+
+  const commandPrefix = normalizedQuery.startsWith('/')
+    ? normalizedQuery
+    : `/${normalizedQuery}`;
+  const namePrefixMatches = commands.filter((command) =>
+    command.name.toLowerCase().startsWith(commandPrefix),
+  );
+
+  // Namespaced commands should behave like path completion. Once a provider
+  // namespace is typed, only exact command-prefix matches should stay visible.
+  if (normalizedQuery.includes(':') || namePrefixMatches.length > 0) {
+    return namePrefixMatches;
+  }
+
+  const nameSubstringMatches = commands.filter((command) =>
+    command.name.toLowerCase().includes(normalizedQuery),
+  );
+  if (nameSubstringMatches.length > 0) {
+    return nameSubstringMatches;
+  }
+
+  return commands.filter((command) =>
+    command.description?.toLowerCase().includes(normalizedQuery),
+  );
+};
+
 export function useSlashCommands({
   selectedProject,
+  provider,
   input,
   setInput,
   textareaRef,
@@ -80,6 +168,8 @@ export function useSlashCommands({
   }, [clearCommandQueryTimer]);
 
   useEffect(() => {
+    let cancelled = false;
+
     const fetchCommands = async () => {
       if (!selectedProject) {
         setSlashCommands([]);
@@ -88,13 +178,14 @@ export function useSlashCommands({
       }
 
       try {
+        const workspacePath = selectedProject.fullPath || selectedProject.path || '';
         const response = await authenticatedFetch('/api/commands/list', {
           method: 'POST',
           headers: {
             'Content-Type': 'application/json',
           },
           body: JSON.stringify({
-            projectPath: selectedProject.path,
+            projectPath: workspacePath || selectedProject.path,
           }),
         });
 
@@ -103,33 +194,54 @@ export function useSlashCommands({
         }
 
         const data = await response.json();
+        const skillsParams = new URLSearchParams();
+        if (workspacePath) {
+          skillsParams.set('workspacePath', workspacePath);
+        }
+
+        const skillsResponse = await authenticatedFetch(
+          `/api/providers/${encodeURIComponent(provider)}/skills${skillsParams.toString() ? `?${skillsParams.toString()}` : ''}`,
+        );
+        const skillsData = skillsResponse.ok
+          ? ((await skillsResponse.json()) as ProviderSkillsResponse)
+          : null;
+        const skillCommands = dedupeProviderSkills(skillsData?.data?.skills || [])
+          .map(mapSkillToSlashCommand);
         const allCommands: SlashCommand[] = [
           ...((data.builtIn || []) as SlashCommand[]).map((command) => ({
             ...command,
             type: 'built-in',
           })),
+          ...skillCommands,
           ...((data.custom || []) as SlashCommand[]).map((command) => ({
             ...command,
             type: 'custom',
           })),
         ];
 
-        const parsedHistory = readCommandHistory(selectedProject.name);
+        const parsedHistory = readCommandHistory(selectedProject.projectId);
         const sortedCommands = [...allCommands].sort((commandA, commandB) => {
           const commandAUsage = parsedHistory[commandA.name] || 0;
           const commandBUsage = parsedHistory[commandB.name] || 0;
           return commandBUsage - commandAUsage;
         });
 
-        setSlashCommands(sortedCommands);
+        if (!cancelled) {
+          setSlashCommands(sortedCommands);
+        }
       } catch (error) {
         console.error('Error fetching slash commands:', error);
-        setSlashCommands([]);
+        if (!cancelled) {
+          setSlashCommands([]);
+        }
       }
     };
 
     fetchCommands();
-  }, [selectedProject]);
+    return () => {
+      cancelled = true;
+    };
+  }, [selectedProject, provider]);
 
   useEffect(() => {
     if (!showCommandMenu) {
@@ -137,43 +249,16 @@ export function useSlashCommands({
     }
   }, [showCommandMenu]);
 
-  const fuse = useMemo(() => {
-    if (!slashCommands.length) {
-      return null;
-    }
-
-    return new Fuse(slashCommands, {
-      keys: [
-        { name: 'name', weight: 2 },
-        { name: 'description', weight: 1 },
-      ],
-      threshold: 0.4,
-      includeScore: true,
-      minMatchCharLength: 1,
-    });
-  }, [slashCommands]);
-
   useEffect(() => {
-    if (!commandQuery) {
-      setFilteredCommands(slashCommands);
-      return;
-    }
-
-    if (!fuse) {
-      setFilteredCommands([]);
-      return;
-    }
-
-    const results = fuse.search(commandQuery);
-    setFilteredCommands(results.map((result) => result.item));
-  }, [commandQuery, slashCommands, fuse]);
+    setFilteredCommands(filterSlashCommands(slashCommands, commandQuery));
+  }, [commandQuery, slashCommands]);
 
   const frequentCommands = useMemo(() => {
     if (!selectedProject || slashCommands.length === 0) {
       return [];
     }
 
-    const parsedHistory = readCommandHistory(selectedProject.name);
+    const parsedHistory = readCommandHistory(selectedProject.projectId);
 
     return slashCommands
       .map((command) => ({
@@ -191,32 +276,70 @@ export function useSlashCommands({
         return;
       }
 
-      const parsedHistory = readCommandHistory(selectedProject.name);
+      const parsedHistory = readCommandHistory(selectedProject.projectId);
       parsedHistory[command.name] = (parsedHistory[command.name] || 0) + 1;
-      saveCommandHistory(selectedProject.name, parsedHistory);
+      saveCommandHistory(selectedProject.projectId, parsedHistory);
     },
     [selectedProject],
   );
 
-  const selectCommandFromKeyboard = useCallback(
+  const insertCommandIntoInput = useCallback(
     (command: SlashCommand) => {
-      const textBeforeSlash = input.slice(0, slashPosition);
-      const textAfterSlash = input.slice(slashPosition);
-      const spaceIndex = textAfterSlash.indexOf(' ');
-      const textAfterQuery = spaceIndex !== -1 ? textAfterSlash.slice(spaceIndex) : '';
-      const newInput = `${textBeforeSlash}${command.name} ${textAfterQuery}`;
+      const currentTextarea = textareaRef.current;
+      const insertionStart = slashPosition >= 0
+        ? slashPosition
+        : currentTextarea?.selectionStart ?? input.length;
+      const textBeforeCommand = input.slice(0, insertionStart);
+      const textAfterCommandStart = input.slice(insertionStart);
+      const spaceIndex = textAfterCommandStart.indexOf(' ');
+      const textAfterCommand = slashPosition >= 0 && spaceIndex !== -1
+        ? textAfterCommandStart.slice(spaceIndex).trimStart()
+        : input.slice(currentTextarea?.selectionEnd ?? insertionStart);
+      const separator = textBeforeCommand && !/\s$/.test(textBeforeCommand) ? ' ' : '';
+      const newInput = `${textBeforeCommand}${separator}${command.name}${textAfterCommand ? ` ${textAfterCommand}` : ' '}`;
 
       setInput(newInput);
       resetCommandMenuState();
 
+      window.requestAnimationFrame(() => {
+        currentTextarea?.focus();
+        const nextCursorPosition = `${textBeforeCommand}${separator}${command.name} `.length;
+        currentTextarea?.setSelectionRange(nextCursorPosition, nextCursorPosition);
+      });
+    },
+    [input, resetCommandMenuState, setInput, slashPosition, textareaRef],
+  );
+
+  const executeNonSkillCommand = useCallback(
+    (command: SlashCommand) => {
       const executionResult = onExecuteCommand(command);
       if (isPromiseLike(executionResult)) {
-        executionResult.catch(() => {
-          // Keep behavior silent; execution errors are handled by caller.
-        });
+        executionResult.then(
+          () => {
+            resetCommandMenuState();
+          },
+          () => {
+            resetCommandMenuState();
+            // Keep behavior silent; execution errors are handled by caller.
+          },
+        );
+      } else {
+        resetCommandMenuState();
       }
     },
-    [input, slashPosition, setInput, resetCommandMenuState, onExecuteCommand],
+    [onExecuteCommand, resetCommandMenuState],
+  );
+
+  const selectCommandFromKeyboard = useCallback(
+    (command: SlashCommand) => {
+      if (isSkillCommand(command)) {
+        insertCommandIntoInput(command);
+        return;
+      }
+
+      executeNonSkillCommand(command);
+    },
+    [executeNonSkillCommand, insertCommandIntoInput],
   );
 
   const handleCommandSelect = useCallback(
@@ -231,20 +354,14 @@ export function useSlashCommands({
       }
 
       trackCommandUsage(command);
-      const executionResult = onExecuteCommand(command);
-
-      if (isPromiseLike(executionResult)) {
-        executionResult.then(() => {
-          resetCommandMenuState();
-        });
-        executionResult.catch(() => {
-          // Keep behavior silent; execution errors are handled by caller.
-        });
-      } else {
-        resetCommandMenuState();
+      if (isSkillCommand(command)) {
+        insertCommandIntoInput(command);
+        return;
       }
+
+      executeNonSkillCommand(command);
     },
-    [selectedProject, trackCommandUsage, onExecuteCommand, resetCommandMenuState],
+    [selectedProject, trackCommandUsage, insertCommandIntoInput, executeNonSkillCommand],
   );
 
   const handleToggleCommandMenu = useCallback(() => {
@@ -276,7 +393,7 @@ export function useSlashCommands({
         return;
       }
 
-      const slashPattern = /(^|\s)\/(\S*)$/;
+      const slashPattern = /^\/(\S*)$/;
       const match = textBeforeCursor.match(slashPattern);
 
       if (!match) {
@@ -284,8 +401,8 @@ export function useSlashCommands({
         return;
       }
 
-      const slashPos = (match.index || 0) + match[1].length;
-      const query = match[2];
+      const slashPos = 0;
+      const query = match[1];
 
       setSlashPosition(slashPos);
       setShowCommandMenu(true);
diff --git a/src/components/chat/types/types.ts b/src/components/chat/types/types.ts
index 900028c0..474f23e1 100644
--- a/src/components/chat/types/types.ts
+++ b/src/components/chat/types/types.ts
@@ -2,7 +2,7 @@ import type { Project, ProjectSession, LLMProvider } from '../../../types/app';
 
 export type Provider = LLMProvider;
 
-export type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan';
+export type PermissionMode = 'default' | 'acceptEdits' | 'auto' | 'bypassPermissions' | 'plan';
 
 export interface ChatImage {
   data: string;
@@ -28,6 +28,7 @@ export interface SubagentChildTool {
 export interface ChatMessage {
   type: string;
   content?: string;
+  displayText?: string;
   timestamp: string | number | Date;
   images?: ChatImage[];
   reasoning?: string;
@@ -40,6 +41,12 @@ export interface ChatMessage {
   toolResult?: ToolResult | null;
   toolId?: string;
   toolCallId?: string;
+  commandName?: string;
+  commandMessage?: string;
+  commandArgs?: string;
+  isLocalCommand?: boolean;
+  isLocalCommandStdout?: boolean;
+  isCompactSummary?: boolean;
   isSubagentContainer?: boolean;
   subagentState?: {
     childTools: SubagentChildTool[];
@@ -91,6 +98,10 @@ export interface Question {
   multiSelect?: boolean;
 }
 
+export type SessionNavigationOptions = {
+  replace?: boolean;
+};
+
 export interface ChatInterfaceProps {
   selectedProject: Project | null;
   selectedSession: ProjectSession | null;
@@ -104,8 +115,7 @@ export interface ChatInterfaceProps {
   onSessionProcessing?: (sessionId?: string | null) => void;
   onSessionNotProcessing?: (sessionId?: string | null) => void;
   processingSessions?: Set<string>;
-  onReplaceTemporarySession?: (sessionId?: string | null) => void;
-  onNavigateToSession?: (targetSessionId: string) => void;
+  onNavigateToSession?: (targetSessionId: string, options?: SessionNavigationOptions) => void;
   onShowSettings?: () => void;
   autoExpandTools?: boolean;
   showRawParameters?: boolean;
@@ -113,6 +123,7 @@ export interface ChatInterfaceProps {
   autoScrollToBottom?: boolean;
   sendByCtrlEnter?: boolean;
   externalMessageUpdate?: number;
+  newSessionTrigger?: number;
   onTaskClick?: (...args: unknown[]) => void;
   onShowAllTasks?: (() => void) | null;
 }
diff --git a/src/components/chat/view/ChatInterface.tsx b/src/components/chat/view/ChatInterface.tsx
index 1b3ae95c..2f677bbb 100644
--- a/src/components/chat/view/ChatInterface.tsx
+++ b/src/components/chat/view/ChatInterface.tsx
@@ -14,10 +14,10 @@ import { useSessionStore } from '../../../stores/useSessionStore';
 
 import ChatMessagesPane from './subcomponents/ChatMessagesPane';
 import ChatComposer from './subcomponents/ChatComposer';
+import CommandResultModal from './subcomponents/CommandResultModal';
 
 
 type PendingViewSession = {
-  sessionId: string | null;
   startedAt: number;
 };
 
@@ -34,7 +34,6 @@ function ChatInterface({
   onSessionProcessing,
   onSessionNotProcessing,
   processingSessions,
-  onReplaceTemporarySession,
   onNavigateToSession,
   onShowSettings,
   autoExpandTools,
@@ -43,13 +42,13 @@ function ChatInterface({
   autoScrollToBottom,
   sendByCtrlEnter,
   externalMessageUpdate,
+  newSessionTrigger,
   onShowAllTasks,
 }: ChatInterfaceProps) {
   const { tasksEnabled, isTaskMasterInstalled } = useTasksSettings();
   const { t } = useTranslation('chat');
 
   const sessionStore = useSessionStore();
-  const streamBufferRef = useRef('');
   const streamTimerRef = useRef<number | null>(null);
   const accumulatedStreamRef = useRef('');
   const pendingViewSessionRef = useRef<PendingViewSession | null>(null);
@@ -59,7 +58,6 @@ function ChatInterface({
       clearTimeout(streamTimerRef.current);
       streamTimerRef.current = null;
     }
-    streamBufferRef.current = '';
     accumulatedStreamRef.current = '';
   }, []);
 
@@ -74,19 +72,26 @@ function ChatInterface({
     setCodexModel,
     geminiModel,
     setGeminiModel,
+    opencodeModel,
+    setOpenCodeModel,
     permissionMode,
     pendingPermissionRequests,
     setPendingPermissionRequests,
     cyclePermissionMode,
+    providerModelCatalog,
+    providerModelCacheCatalog,
+    providerModelsLoading,
+    providerModelsRefreshing,
+    hardRefreshProviderModels,
+    selectProviderModel,
   } = useChatProviderState({
     selectedSession,
+    selectedProject,
   });
 
   const {
     chatMessages,
     addMessage,
-    clearMessages,
-    rewindMessages,
     isLoading,
     setIsLoading,
     currentSessionId,
@@ -123,6 +128,7 @@ function ChatInterface({
     sendMessage,
     autoScrollToBottom,
     externalMessageUpdate,
+    newSessionTrigger,
     processingSessions,
     resetStreamingState,
     pendingViewSessionRef,
@@ -171,7 +177,9 @@ function ChatInterface({
     handlePermissionDecision,
     handleGrantToolPermission,
     handleInputFocusChange,
-    isInputFocused,
+    isInputFocused: _isInputFocused,
+    commandModalPayload,
+    closeCommandModal,
   } = useChatComposerState({
     selectedProject,
     selectedSession,
@@ -183,6 +191,7 @@ function ChatInterface({
     claudeModel,
     codexModel,
     geminiModel,
+    opencodeModel,
     isLoading,
     canAbortSession,
     tokenBudget,
@@ -196,8 +205,6 @@ function ChatInterface({
     pendingViewSessionRef,
     scrollToBottom,
     addMessage,
-    clearMessages,
-    rewindMessages,
     setIsLoading,
     setCanAbortSession,
     setClaudeStatus,
@@ -212,7 +219,8 @@ function ChatInterface({
     const providerVal = (localStorage.getItem('selected-provider') as LLMProvider) || 'claude';
     await sessionStore.refreshFromServer(selectedSession.id, {
       provider: (selectedSession.__provider || providerVal) as LLMProvider,
-      projectName: selectedProject.name,
+      // Use DB projectId; legacy folder-derived projectName is no longer accepted here.
+      projectId: selectedProject.projectId,
       projectPath: selectedProject.fullPath || selectedProject.path || '',
     });
     setIsLoading(false);
@@ -222,7 +230,6 @@ function ChatInterface({
   useChatRealtimeHandlers({
     latestMessage,
     provider,
-    selectedProject,
     selectedSession,
     currentSessionId,
     setCurrentSessionId,
@@ -232,13 +239,12 @@ function ChatInterface({
     setTokenBudget,
     setPendingPermissionRequests,
     pendingViewSessionRef,
-    streamBufferRef,
     streamTimerRef,
     accumulatedStreamRef,
     onSessionInactive,
+    onSessionActive,
     onSessionProcessing,
     onSessionNotProcessing,
-    onReplaceTemporarySession,
     onNavigateToSession,
     onWebSocketReconnect: handleWebSocketReconnect,
     sessionStore,
@@ -283,6 +289,8 @@ function ChatInterface({
           ? t('messageTypes.codex')
           : provider === 'gemini'
             ? t('messageTypes.gemini')
+            : provider === 'opencode'
+              ? t('messageTypes.opencode', { defaultValue: 'OpenCode' })
             : t('messageTypes.claude');
 
     return (
@@ -321,6 +329,10 @@ function ChatInterface({
           setCodexModel={setCodexModel}
           geminiModel={geminiModel}
           setGeminiModel={setGeminiModel}
+          opencodeModel={opencodeModel}
+          setOpenCodeModel={setOpenCodeModel}
+          providerModelCatalog={providerModelCatalog}
+          providerModelsLoading={providerModelsLoading}
           tasksEnabled={tasksEnabled}
           isTaskMasterInstalled={isTaskMasterInstalled}
           onShowAllTasks={onShowAllTasks}
@@ -409,6 +421,8 @@ function ChatInterface({
                   ? t('messageTypes.codex')
                   : provider === 'gemini'
                     ? t('messageTypes.gemini')
+                    : provider === 'opencode'
+                      ? t('messageTypes.opencode', { defaultValue: 'OpenCode' })
                     : t('messageTypes.claude'),
           })}
           isTextareaExpanded={isTextareaExpanded}
@@ -417,6 +431,17 @@ function ChatInterface({
       </div>
 
       <QuickSettingsPanel />
+
+      <CommandResultModal
+        payload={commandModalPayload}
+        onClose={closeCommandModal}
+        providerModelCatalog={providerModelCatalog}
+        providerModelCacheCatalog={providerModelCacheCatalog}
+        providerModelsRefreshing={providerModelsRefreshing}
+        onHardRefreshProviderModels={hardRefreshProviderModels}
+        currentSessionId={currentSessionId || selectedSession?.id || null}
+        onSelectProviderModel={selectProviderModel}
+      />
     </PermissionContext.Provider>
   );
 }
diff --git a/src/components/chat/view/subcomponents/ChatComposer.tsx b/src/components/chat/view/subcomponents/ChatComposer.tsx
index e67ee64b..c447bc19 100644
--- a/src/components/chat/view/subcomponents/ChatComposer.tsx
+++ b/src/components/chat/view/subcomponents/ChatComposer.tsx
@@ -18,7 +18,7 @@ import ClaudeStatus from './ClaudeStatus';
 import ImageAttachment from './ImageAttachment';
 import PermissionRequestsBanner from './PermissionRequestsBanner';
 import ThinkingModeSelector from './ThinkingModeSelector';
-import TokenUsagePie from './TokenUsagePie';
+import TokenUsageSummary from './TokenUsageSummary';
 import {
   PromptInput,
   PromptInputHeader,
@@ -60,7 +60,7 @@ interface ChatComposerProps {
   onModeSwitch: () => void;
   thinkingMode: string;
   setThinkingMode: Dispatch<SetStateAction<string>>;
-  tokenBudget: { used?: number; total?: number } | null;
+  tokenBudget: Record<string, unknown> | null;
   slashCommandsCount: number;
   onToggleCommandMenu: () => void;
   hasInput: boolean;
@@ -325,9 +325,11 @@ export default function ChatComposer({
                   ? 'border-border/60 bg-muted/50 text-muted-foreground hover:bg-muted'
                   : permissionMode === 'acceptEdits'
                     ? 'border-green-300/60 bg-green-50 text-green-700 hover:bg-green-100 dark:border-green-600/40 dark:bg-green-900/15 dark:text-green-300 dark:hover:bg-green-900/25'
-                    : permissionMode === 'bypassPermissions'
-                      ? 'border-orange-300/60 bg-orange-50 text-orange-700 hover:bg-orange-100 dark:border-orange-600/40 dark:bg-orange-900/15 dark:text-orange-300 dark:hover:bg-orange-900/25'
-                      : 'border-primary/20 bg-primary/5 text-primary hover:bg-primary/10'
+                    : permissionMode === 'auto'
+                      ? 'border-blue-300/60 bg-blue-50 text-blue-700 hover:bg-blue-100 dark:border-blue-600/40 dark:bg-blue-900/15 dark:text-blue-300 dark:hover:bg-blue-900/25'
+                      : permissionMode === 'bypassPermissions'
+                        ? 'border-orange-300/60 bg-orange-50 text-orange-700 hover:bg-orange-100 dark:border-orange-600/40 dark:bg-orange-900/15 dark:text-orange-300 dark:hover:bg-orange-900/25'
+                        : 'border-primary/20 bg-primary/5 text-primary hover:bg-primary/10'
               }`}
               title={t('input.clickToChangeMode')}
             >
@@ -338,14 +340,17 @@ export default function ChatComposer({
                       ? 'bg-muted-foreground'
                       : permissionMode === 'acceptEdits'
                         ? 'bg-green-500'
-                        : permissionMode === 'bypassPermissions'
-                          ? 'bg-orange-500'
-                          : 'bg-primary'
+                        : permissionMode === 'auto'
+                          ? 'bg-blue-500'
+                          : permissionMode === 'bypassPermissions'
+                            ? 'bg-orange-500'
+                            : 'bg-primary'
                   }`}
                 />
                 <span className="hidden whitespace-nowrap sm:inline">
                   {permissionMode === 'default' && t('codex.modes.default')}
                   {permissionMode === 'acceptEdits' && t('codex.modes.acceptEdits')}
+                  {permissionMode === 'auto' && t('codex.modes.auto')}
                   {permissionMode === 'bypassPermissions' && t('codex.modes.bypassPermissions')}
                   {permissionMode === 'plan' && t('codex.modes.plan')}
                 </span>
@@ -356,7 +361,7 @@ export default function ChatComposer({
               <ThinkingModeSelector selectedMode={thinkingMode} onModeChange={setThinkingMode} onClose={() => {}} className="" />
             )}
 
-            <TokenUsagePie used={tokenBudget?.used || 0} total={tokenBudget?.total || parseInt(import.meta.env.VITE_CONTEXT_WINDOW) || 160000} />
+            <TokenUsageSummary usage={tokenBudget} />
 
             <PromptInputButton
               tooltip={{ content: t('input.showAllCommands') }}
@@ -396,14 +401,6 @@ export default function ChatComposer({
             <PromptInputSubmit
               disabled={!input.trim() || isLoading}
               className="h-10 w-10 sm:h-10 sm:w-10"
-              onMouseDown={(event) => {
-                event.preventDefault();
-                onSubmit(event as unknown as MouseEvent<HTMLButtonElement>);
-              }}
-              onTouchStart={(event) => {
-                event.preventDefault();
-                onSubmit(event as unknown as TouchEvent<HTMLButtonElement>);
-              }}
             />
           </div>
         </PromptInputFooter>
diff --git a/src/components/chat/view/subcomponents/ChatMessagesPane.tsx b/src/components/chat/view/subcomponents/ChatMessagesPane.tsx
index 9d47a7c2..f4ba1161 100644
--- a/src/components/chat/view/subcomponents/ChatMessagesPane.tsx
+++ b/src/components/chat/view/subcomponents/ChatMessagesPane.tsx
@@ -1,9 +1,16 @@
 import { useTranslation } from 'react-i18next';
 import { useCallback, useRef } from 'react';
 import type { Dispatch, RefObject, SetStateAction } from 'react';
+
 import type { ChatMessage } from '../../types/types';
-import type { Project, ProjectSession, LLMProvider } from '../../../../types/app';
+import type {
+  Project,
+  ProjectSession,
+  LLMProvider,
+  ProviderModelsDefinition,
+} from '../../../../types/app';
 import { getIntrinsicMessageKey } from '../../utils/messageKeys';
+
 import MessageComponent from './MessageComponent';
 import ProviderSelectionEmptyState from './ProviderSelectionEmptyState';
 
@@ -26,6 +33,10 @@ interface ChatMessagesPaneProps {
   setCodexModel: (model: string) => void;
   geminiModel: string;
   setGeminiModel: (model: string) => void;
+  opencodeModel: string;
+  setOpenCodeModel: (model: string) => void;
+  providerModelCatalog: Partial<Record<LLMProvider, ProviderModelsDefinition>>;
+  providerModelsLoading: boolean;
   tasksEnabled: boolean;
   isTaskMasterInstalled: boolean | null;
   onShowAllTasks?: (() => void) | null;
@@ -71,6 +82,10 @@ export default function ChatMessagesPane({
   setCodexModel,
   geminiModel,
   setGeminiModel,
+  opencodeModel,
+  setOpenCodeModel,
+  providerModelCatalog,
+  providerModelsLoading,
   tasksEnabled,
   isTaskMasterInstalled,
   onShowAllTasks,
@@ -154,6 +169,10 @@ export default function ChatMessagesPane({
           setCodexModel={setCodexModel}
           geminiModel={geminiModel}
           setGeminiModel={setGeminiModel}
+          opencodeModel={opencodeModel}
+          setOpenCodeModel={setOpenCodeModel}
+          providerModelCatalog={providerModelCatalog}
+          providerModelsLoading={providerModelsLoading}
           tasksEnabled={tasksEnabled}
           isTaskMasterInstalled={isTaskMasterInstalled}
           onShowAllTasks={onShowAllTasks}
@@ -213,13 +232,6 @@ export default function ChatMessagesPane({
             </div>
           )}
 
-          {/* Performance warning when all messages are loaded */}
-          {allMessagesLoaded && (
-            <div className="border-b border-amber-200 bg-amber-50 py-1.5 text-center text-xs text-amber-600 dark:border-amber-800 dark:bg-amber-900/20 dark:text-amber-400">
-              {t('session.messages.perfWarning')}
-            </div>
-          )}
-
           {/* Legacy message count indicator (for non-paginated view) */}
           {!hasMoreMessages && chatMessages.length > visibleMessageCount && (
             <div className="border-b border-gray-200 py-2 text-center text-sm text-gray-500 dark:border-gray-700 dark:text-gray-400">
diff --git a/src/components/chat/view/subcomponents/ClaudeStatus.tsx b/src/components/chat/view/subcomponents/ClaudeStatus.tsx
index f42e29cf..4640ffbc 100644
--- a/src/components/chat/view/subcomponents/ClaudeStatus.tsx
+++ b/src/components/chat/view/subcomponents/ClaudeStatus.tsx
@@ -29,6 +29,7 @@ const PROVIDER_LABEL_KEYS: Record<string, string> = {
   codex: 'messageTypes.codex',
   cursor: 'messageTypes.cursor',
   gemini: 'messageTypes.gemini',
+  opencode: 'messageTypes.opencode',
 };
 
 function formatElapsedTime(totalSeconds: number) {
@@ -126,4 +127,4 @@ export default function ClaudeStatus({
       </div>
     </div>
   );
-}
\ No newline at end of file
+}
diff --git a/src/components/chat/view/subcomponents/CommandMenu.tsx b/src/components/chat/view/subcomponents/CommandMenu.tsx
index 92a598ea..3e6116a0 100644
--- a/src/components/chat/view/subcomponents/CommandMenu.tsx
+++ b/src/components/chat/view/subcomponents/CommandMenu.tsx
@@ -1,5 +1,15 @@
 import { useEffect, useRef } from 'react';
 import type { CSSProperties } from 'react';
+import {
+  CornerDownLeft,
+  Folder,
+  MessageSquare,
+  Sparkles,
+  Star,
+  Terminal,
+  User,
+  type LucideIcon,
+} from 'lucide-react';
 
 type CommandMenuCommand = {
   name: string;
@@ -21,59 +31,92 @@ type CommandMenuProps = {
   frequentCommands?: CommandMenuCommand[];
 };
 
+type CommandMenuRow = {
+  command: CommandMenuCommand;
+  commandIndex: number;
+  renderKey: string;
+};
+
 const menuBaseStyle: CSSProperties = {
-  maxHeight: '300px',
+  maxHeight: '360px',
   overflowY: 'auto',
   borderRadius: '8px',
-  boxShadow: '0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05)',
+  boxShadow: '0 24px 60px rgba(2, 6, 23, 0.38), 0 0 0 1px rgba(148, 163, 184, 0.12)',
   zIndex: 1000,
-  padding: '8px',
+  padding: '6px',
   transition: 'opacity 150ms ease-in-out, transform 150ms ease-in-out',
+  backdropFilter: 'blur(12px)',
 };
 
 const namespaceLabels: Record<string, string> = {
   frequent: 'Frequently Used',
   builtin: 'Built-in Commands',
+  skill: 'Skills',
   project: 'Project Commands',
   user: 'User Commands',
   other: 'Other Commands',
 };
 
-const namespaceIcons: Record<string, string> = {
-  frequent: '[*]',
-  builtin: '[B]',
-  project: '[P]',
-  user: '[U]',
-  other: '[O]',
+const namespaceIcons: Record<string, LucideIcon> = {
+  frequent: Star,
+  builtin: Terminal,
+  skill: Sparkles,
+  project: Folder,
+  user: User,
+  other: MessageSquare,
 };
 
+const namespaceAccentClasses: Record<string, string> = {
+  frequent: 'border-amber-200 bg-amber-50 text-amber-700 dark:border-amber-400/20 dark:bg-amber-400/10 dark:text-amber-200',
+  builtin: 'border-sky-200 bg-sky-50 text-sky-700 dark:border-sky-400/20 dark:bg-sky-400/10 dark:text-sky-200',
+  skill: 'border-emerald-200 bg-emerald-50 text-emerald-700 dark:border-emerald-400/20 dark:bg-emerald-400/10 dark:text-emerald-200',
+  project: 'border-indigo-200 bg-indigo-50 text-indigo-700 dark:border-indigo-400/20 dark:bg-indigo-400/10 dark:text-indigo-200',
+  user: 'border-rose-200 bg-rose-50 text-rose-700 dark:border-rose-400/20 dark:bg-rose-400/10 dark:text-rose-200',
+  other: 'border-gray-200 bg-gray-50 text-gray-600 dark:border-gray-500/20 dark:bg-gray-500/10 dark:text-gray-200',
+};
+
+const MENU_EDGE_GAP = 16;
+const MENU_MAX_HEIGHT = 360;
+
 const getCommandKey = (command: CommandMenuCommand) =>
   `${command.name}::${command.namespace || command.type || 'other'}::${command.path || ''}`;
 
 const getNamespace = (command: CommandMenuCommand) => command.namespace || command.type || 'other';
 
+const getNamespaceIcon = (namespace: string) => namespaceIcons[namespace] || namespaceIcons.other;
+
+const getNamespaceAccentClass = (namespace: string) =>
+  namespaceAccentClasses[namespace] || namespaceAccentClasses.other;
+
 const getMenuPosition = (position: { top: number; left: number; bottom?: number }): CSSProperties => {
   if (typeof window === 'undefined') {
     return { position: 'fixed', top: '16px', left: '16px' };
   }
   if (window.innerWidth < 640) {
+    const anchorBottom = Math.max(MENU_EDGE_GAP, position.bottom ?? 90);
     return {
       position: 'fixed',
-      bottom: `${position.bottom ?? 90}px`,
+      bottom: `${anchorBottom}px`,
       left: '16px',
       right: '16px',
       width: 'auto',
       maxWidth: 'calc(100vw - 32px)',
-      maxHeight: 'min(50vh, 300px)',
+      maxHeight: `min(54vh, calc(100vh - ${anchorBottom}px - ${MENU_EDGE_GAP}px))`,
     };
   }
+  const anchorBottom = Math.max(MENU_EDGE_GAP, position.bottom ?? 90);
+  const clampedLeft = Math.max(
+    MENU_EDGE_GAP,
+    Math.min(position.left, window.innerWidth - 440 - MENU_EDGE_GAP),
+  );
+
   return {
     position: 'fixed',
-    top: `${Math.max(16, Math.min(position.top, window.innerHeight - 316))}px`,
-    left: `${position.left}px`,
-    width: 'min(400px, calc(100vw - 32px))',
+    bottom: `${anchorBottom}px`,
+    left: `${clampedLeft}px`,
+    width: 'min(440px, calc(100vw - 32px))',
     maxWidth: 'calc(100vw - 32px)',
-    maxHeight: '300px',
+    maxHeight: `min(${MENU_MAX_HEIGHT}px, calc(100vh - ${anchorBottom}px - ${MENU_EDGE_GAP}px))`,
   };
 };
 
@@ -123,7 +166,24 @@ export default function CommandMenu({
 
   const hasFrequentCommands = frequentCommands.length > 0;
   const frequentCommandKeys = new Set(frequentCommands.map(getCommandKey));
-  const groupedCommands = commands.reduce<Record<string, CommandMenuCommand[]>>((groups, command) => {
+  const commandIndexesByKey = new Map<string, number[]>();
+  commands.forEach((command, index) => {
+    const key = getCommandKey(command);
+    const commandIndexes = commandIndexesByKey.get(key) ?? [];
+    commandIndexes.push(index);
+    commandIndexesByKey.set(key, commandIndexes);
+  });
+  const frequentCommandOccurrences = new Map<string, number>();
+  const getFrequentCommandIndex = (command: CommandMenuCommand): number => {
+    const key = getCommandKey(command);
+    const occurrence = frequentCommandOccurrences.get(key) ?? 0;
+    frequentCommandOccurrences.set(key, occurrence + 1);
+
+    const commandIndexes = commandIndexesByKey.get(key) ?? [];
+    return commandIndexes[occurrence] ?? commandIndexes[0] ?? -1;
+  };
+
+  const groupedCommands = commands.reduce<Record<string, CommandMenuRow[]>>((groups, command, index) => {
     if (hasFrequentCommands && frequentCommandKeys.has(getCommandKey(command))) {
       return groups;
     }
@@ -131,33 +191,46 @@ export default function CommandMenu({
     if (!groups[namespace]) {
       groups[namespace] = [];
     }
-    groups[namespace].push(command);
+    groups[namespace].push({
+      command,
+      commandIndex: index,
+      renderKey: `${namespace}-${index}-${getCommandKey(command)}`,
+    });
     return groups;
   }, {});
   if (hasFrequentCommands) {
-    groupedCommands.frequent = frequentCommands;
+    groupedCommands.frequent = frequentCommands
+      .map((command, index) => {
+        const commandIndex = getFrequentCommandIndex(command);
+        return {
+          command,
+          commandIndex,
+          renderKey: `frequent-${index}-${commandIndex}-${getCommandKey(command)}`,
+        };
+      })
+      .filter((row) => row.commandIndex >= 0);
   }
 
   const preferredOrder = hasFrequentCommands
-    ? ['frequent', 'builtin', 'project', 'user', 'other']
-    : ['builtin', 'project', 'user', 'other'];
+    ? ['frequent', 'builtin', 'skill', 'project', 'user', 'other']
+    : ['builtin', 'skill', 'project', 'user', 'other'];
   const extraNamespaces = Object.keys(groupedCommands).filter((namespace) => !preferredOrder.includes(namespace));
   const orderedNamespaces = [...preferredOrder, ...extraNamespaces].filter((namespace) => groupedCommands[namespace]);
 
-  const commandIndexByKey = new Map<string, number>();
-  commands.forEach((command, index) => {
-    const key = getCommandKey(command);
-    if (!commandIndexByKey.has(key)) {
-      commandIndexByKey.set(key, index);
-    }
-  });
-
   if (commands.length === 0) {
     return (
       <div
         ref={menuRef}
-        className="command-menu command-menu-empty border border-gray-200 bg-white text-gray-500 dark:border-gray-700 dark:bg-gray-800 dark:text-gray-400"
-        style={{ ...menuPosition, ...menuBaseStyle, overflowY: 'hidden', padding: '20px', opacity: 1, transform: 'translateY(0)', textAlign: 'center' }}
+        className="command-menu command-menu-empty border border-gray-200 bg-white/95 text-sm text-gray-500 dark:border-gray-700/80 dark:bg-gray-900/95 dark:text-gray-400"
+        style={{
+          ...menuBaseStyle,
+          ...menuPosition,
+          overflowY: 'hidden',
+          padding: '20px',
+          opacity: 1,
+          transform: 'translateY(0)',
+          textAlign: 'center',
+        }}
       >
         No commands available
       </div>
@@ -169,51 +242,73 @@ export default function CommandMenu({
       ref={menuRef}
       role="listbox"
       aria-label="Available commands"
-      className="command-menu border border-gray-200 bg-white dark:border-gray-700 dark:bg-gray-800"
-      style={{ ...menuPosition, ...menuBaseStyle, opacity: 1, transform: 'translateY(0)' }}
+      className="command-menu border border-gray-200/90 bg-white/95 text-gray-900 dark:border-slate-700/80 dark:bg-slate-950/95 dark:text-slate-100"
+      style={{ ...menuBaseStyle, ...menuPosition, opacity: 1, transform: 'translateY(0)' }}
     >
       {orderedNamespaces.map((namespace) => (
         <div key={namespace} className="command-group">
           {orderedNamespaces.length > 1 && (
-            <div className="px-3 pb-1 pt-2 text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400">
-              {namespaceLabels[namespace] || namespace}
+            <div className="flex items-center justify-between px-2 pb-1.5 pt-2 text-[10px] font-semibold uppercase tracking-wide text-gray-500 dark:text-slate-400">
+              <span>{namespaceLabels[namespace] || namespace}</span>
+              <span className="rounded border border-gray-200 bg-gray-50 px-1.5 py-0.5 text-[10px] text-gray-500 dark:border-slate-700 dark:bg-slate-900 dark:text-slate-400">
+                {(groupedCommands[namespace] || []).length}
+              </span>
             </div>
           )}
 
-          {(groupedCommands[namespace] || []).map((command) => {
-            const commandKey = getCommandKey(command);
-            const commandIndex = commandIndexByKey.get(commandKey) ?? -1;
+          {(groupedCommands[namespace] || []).map(({ command, commandIndex, renderKey }) => {
             const isSelected = commandIndex === selectedIndex;
+            const NamespaceIcon = getNamespaceIcon(namespace);
+            const accentClass = getNamespaceAccentClass(namespace);
             return (
               <div
-                key={`${namespace}-${command.name}-${command.path || ''}`}
+                key={renderKey}
                 ref={isSelected ? selectedItemRef : null}
                 role="option"
                 aria-selected={isSelected}
-                className={`command-item mb-0.5 flex cursor-pointer items-start rounded-md px-3 py-2.5 transition-colors ${
-                  isSelected ? 'bg-blue-50 dark:bg-blue-900' : 'bg-transparent'
+                className={`command-item group relative mb-1 flex cursor-pointer items-start gap-2 rounded-md border px-2.5 py-2 transition-all ${
+                  isSelected
+                    ? 'border-sky-200 bg-sky-50 shadow-sm dark:border-cyan-400/30 dark:bg-cyan-400/10'
+                    : 'border-transparent bg-transparent hover:border-gray-200 hover:bg-gray-50/90 dark:hover:border-slate-700 dark:hover:bg-slate-900/80'
                 }`}
                 onMouseEnter={() => onSelect && commandIndex >= 0 && onSelect(command, commandIndex, true)}
                 onClick={() => onSelect && commandIndex >= 0 && onSelect(command, commandIndex, false)}
                 onMouseDown={(event) => event.preventDefault()}
               >
-                <div className="min-w-0 flex-1">
-                  <div className={`flex items-center gap-2 ${command.description ? 'mb-1' : 'mb-0'}`}>
-                    <span className="shrink-0 text-xs text-gray-500 dark:text-gray-300">{namespaceIcons[namespace] || namespaceIcons.other}</span>
-                    <span className="font-mono text-sm font-semibold text-gray-900 dark:text-gray-100">{command.name}</span>
+                {isSelected && (
+                  <span className="absolute bottom-1.5 left-1.5 top-1.5 w-0.5 rounded-full bg-sky-500 dark:bg-cyan-300" />
+                )}
+                <span className={`mt-0.5 flex h-7 w-7 shrink-0 items-center justify-center rounded-md border ${accentClass}`}>
+                  <NamespaceIcon aria-hidden="true" size={14} strokeWidth={2.2} />
+                </span>
+                <div className="min-w-0 flex-1 pr-1">
+                  <div className={`flex min-w-0 items-center gap-2 ${command.description ? 'mb-1' : 'mb-0'}`}>
+                    <span
+                      className="min-w-0 truncate font-mono text-[13px] font-semibold text-gray-950 dark:text-slate-50"
+                      title={command.name}
+                    >
+                      {command.name}
+                    </span>
                     {command.metadata?.type && (
-                      <span className="command-metadata-badge rounded bg-gray-100 px-1.5 py-0.5 text-[10px] font-medium text-gray-500 dark:bg-gray-700 dark:text-gray-300">
+                      <span className="command-metadata-badge shrink-0 rounded border border-gray-200 bg-white px-1.5 py-0.5 text-[10px] font-medium text-gray-500 shadow-sm dark:border-slate-700 dark:bg-slate-900 dark:text-slate-300">
                         {command.metadata.type}
                       </span>
                     )}
                   </div>
                   {command.description && (
-                    <div className="ml-6 truncate whitespace-nowrap text-[13px] text-gray-500 dark:text-gray-300">
+                    <div
+                      className="truncate whitespace-nowrap text-[12px] leading-4 text-gray-500 dark:text-slate-400"
+                      title={command.description}
+                    >
                       {command.description}
                     </div>
                   )}
                 </div>
-                {isSelected && <span className="ml-2 text-xs font-semibold text-blue-500 dark:text-blue-300">{'<-'}</span>}
+                {isSelected && (
+                  <span className="mt-1 flex h-6 w-6 shrink-0 items-center justify-center rounded border border-sky-200 bg-white text-sky-600 shadow-sm dark:border-cyan-400/30 dark:bg-slate-950 dark:text-cyan-200">
+                    <CornerDownLeft aria-hidden="true" size={13} strokeWidth={2.2} />
+                  </span>
+                )}
               </div>
             );
           })}
diff --git a/src/components/chat/view/subcomponents/CommandResultModal.tsx b/src/components/chat/view/subcomponents/CommandResultModal.tsx
new file mode 100644
index 00000000..2e391ebe
--- /dev/null
+++ b/src/components/chat/view/subcomponents/CommandResultModal.tsx
@@ -0,0 +1,726 @@
+import { useMemo, useState } from 'react';
+import {
+  Activity,
+  BadgeCheck,
+  Check,
+  CircleHelp,
+  Clipboard,
+  Coins,
+  Cpu,
+  Gauge,
+  Package,
+  Search,
+  Server,
+  Sparkles,
+  TerminalSquare,
+  Timer,
+  RefreshCw,
+  X,
+} from 'lucide-react';
+
+import { Badge, Button, Dialog, DialogContent, DialogTitle, Input } from '../../../../shared/view/ui';
+import type { LLMProvider, ProviderModelsCacheInfo, ProviderModelsDefinition } from '../../../../types/app';
+import type {
+  CommandModalPayload,
+  CostCommandData,
+  HelpCommandData,
+  ModelCommandData,
+  StatusCommandData,
+} from '../../hooks/useChatComposerState';
+
+type CommandResultModalProps = {
+  payload: CommandModalPayload | null;
+  onClose: () => void;
+  providerModelCatalog: Partial<Record<LLMProvider, ProviderModelsDefinition>>;
+  providerModelCacheCatalog: Partial<Record<LLMProvider, ProviderModelsCacheInfo>>;
+  providerModelsRefreshing: boolean;
+  onHardRefreshProviderModels: () => void;
+  currentSessionId: string | null;
+  onSelectProviderModel: (
+    provider: LLMProvider,
+    model: string,
+    sessionId?: string | null,
+  ) => Promise<{
+    scope: 'default' | 'session';
+    changed: boolean;
+    model: string;
+  }>;
+};
+
+type CommandEntry = {
+  name: string;
+  description?: string;
+  namespace?: string;
+};
+
+type ModelOption = {
+  value: string;
+  label?: string;
+  description?: string;
+};
+
+const formatUpdatedAt = (value?: string) => {
+  if (!value) {
+    return 'Not cached yet';
+  }
+
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    return 'Not cached yet';
+  }
+
+  return parsed.toLocaleString();
+};
+
+const PROVIDER_LABELS: Record<string, string> = {
+  claude: 'Claude',
+  cursor: 'Cursor',
+  codex: 'Codex',
+  gemini: 'Gemini',
+  opencode: 'OpenCode',
+};
+
+const FALLBACK_COMMANDS: CommandEntry[] = [
+  { name: '/models', description: 'Browse available models for the active provider.' },
+  { name: '/cost', description: 'Review token usage for the active session.' },
+  { name: '/status', description: 'Inspect runtime, version, provider, and environment status.' },
+  { name: '/memory', description: 'Open the project CLAUDE.md memory file.' },
+  { name: '/config', description: 'Open settings and configuration.' },
+  { name: '/help', description: 'Show command documentation and syntax.' },
+];
+
+const getProviderLabel = (provider: string | undefined, fallback = 'Unknown') => {
+  if (!provider) {
+    return fallback;
+  }
+
+  return PROVIDER_LABELS[provider] || provider;
+};
+
+const formatNumber = (value: number) => {
+  if (!Number.isFinite(value)) {
+    return '0';
+  }
+  return value.toLocaleString();
+};
+
+function MetricCard({
+  label,
+  value,
+  icon: Icon,
+  tone = 'neutral',
+  compact = false,
+}: {
+  label: string;
+  value: string;
+  icon: typeof Activity;
+  tone?: 'neutral' | 'primary' | 'success';
+  compact?: boolean;
+}) {
+  const toneClass =
+    tone === 'primary'
+      ? 'border-primary/35 bg-primary/10 text-primary'
+      : tone === 'success'
+        ? 'border-emerald-500/30 bg-emerald-500/10 text-emerald-600 dark:text-emerald-300'
+        : 'border-border/70 bg-background/75 text-muted-foreground';
+
+  return (
+    <div
+      className={`group rounded-2xl border border-border/70 bg-background/75 shadow-sm transition-all duration-200 hover:-translate-y-0.5 hover:border-primary/25 hover:shadow-md ${
+        compact ? 'p-3' : 'p-4'
+      }`}
+    >
+      <div className={`inline-flex rounded-xl border ${compact ? 'mb-2 p-1.5' : 'mb-3 p-2'} ${toneClass}`}>
+        <Icon className={compact ? 'h-3.5 w-3.5' : 'h-4 w-4'} />
+      </div>
+      <p className="text-[11px] font-semibold uppercase tracking-[0.18em] text-muted-foreground">{label}</p>
+      <p className={`${compact ? 'mt-0.5 text-[13px]' : 'mt-1 text-sm'} break-all font-semibold text-foreground`}>{value}</p>
+    </div>
+  );
+}
+
+function SearchField({
+  value,
+  onChange,
+  placeholder,
+}: {
+  value: string;
+  onChange: (value: string) => void;
+  placeholder: string;
+}) {
+  return (
+    <div className="relative">
+      <Search className="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
+      <Input
+        value={value}
+        onChange={(event) => onChange(event.target.value)}
+        placeholder={placeholder}
+        className="h-10 rounded-xl border-border/70 bg-background/75 pl-9 pr-3 shadow-none focus-visible:ring-primary/40"
+      />
+    </div>
+  );
+}
+
+function HelpContent({ data }: { data: HelpCommandData }) {
+  const [query, setQuery] = useState('');
+  const commands = (Array.isArray(data.commands) && data.commands.length > 0
+    ? data.commands
+    : FALLBACK_COMMANDS) as CommandEntry[];
+
+  const filteredCommands = useMemo(() => {
+    const normalized = query.trim().toLowerCase();
+    if (!normalized) {
+      return commands;
+    }
+
+    return commands.filter((command) => {
+      const haystack = `${command.name} ${command.description || ''} ${command.namespace || ''}`.toLowerCase();
+      return haystack.includes(normalized);
+    });
+  }, [commands, query]);
+
+  return (
+    <div className="grid h-full min-h-0 gap-4 lg:grid-cols-[minmax(0,1fr)_18rem]">
+      <div className="flex min-h-0 flex-col gap-3">
+        <SearchField value={query} onChange={setQuery} placeholder="Filter commands..." />
+
+        <div className="scrollbar-thin min-h-0 flex-1 overflow-y-auto pr-1">
+          <div className="grid gap-2 sm:grid-cols-2">
+            {filteredCommands.map((command, index) => (
+              <div
+                key={`${command.namespace || 'builtin'}-${command.name}`}
+                className="settings-content-enter rounded-2xl border border-border/70 bg-background/75 p-3 shadow-sm transition-all duration-200 hover:-translate-y-0.5 hover:border-primary/30 hover:bg-muted/25"
+                style={{ animationDelay: `${Math.min(index * 18, 160)}ms` }}
+              >
+                <div className="flex items-start justify-between gap-3">
+                  <code className="rounded-lg border border-primary/20 bg-primary/10 px-2 py-1 text-xs font-semibold text-primary">
+                    {command.name}
+                  </code>
+                  <Badge variant="secondary" className="shrink-0 text-[10px] capitalize">
+                    {command.namespace || 'builtin'}
+                  </Badge>
+                </div>
+                <p className="mt-3 text-sm leading-5 text-muted-foreground">
+                  {command.description || 'No description available.'}
+                </p>
+              </div>
+            ))}
+          </div>
+
+          {filteredCommands.length === 0 && (
+            <div className="rounded-2xl border border-dashed border-border bg-muted/20 px-4 py-10 text-center text-sm text-muted-foreground">
+              No commands match that filter.
+            </div>
+          )}
+        </div>
+      </div>
+
+      <aside className="space-y-3">
+        <div className="rounded-2xl border border-border/70 bg-muted/20 p-4">
+          <div className="mb-3 flex items-center gap-2 text-sm font-semibold text-foreground">
+            <TerminalSquare className="h-4 w-4 text-primary" />
+            Syntax
+          </div>
+          <div className="space-y-2 text-sm text-muted-foreground">
+            <p><code className="text-foreground">/command arg1 arg2</code></p>
+            <p><code className="text-foreground">$ARGUMENTS</code> passes all args.</p>
+            <p><code className="text-foreground">$1</code>, <code className="text-foreground">$2</code> pass positional args.</p>
+            <p><code className="text-foreground">@file</code> includes file contents.</p>
+          </div>
+        </div>
+
+        <div className="rounded-2xl border border-primary/25 bg-primary/10 p-4">
+          <div className="mb-2 flex items-center gap-2 text-sm font-semibold text-foreground">
+            <Sparkles className="h-4 w-4 text-primary" />
+            Quick tip
+          </div>
+          <p className="text-sm leading-5 text-muted-foreground">
+            Type <code className="text-foreground">/</code> in the composer to open the command palette, then use arrows and Enter to run a command.
+          </p>
+        </div>
+      </aside>
+    </div>
+  );
+}
+
+function ModelsContent({
+  data,
+  providerModelCatalog,
+  providerModelCacheCatalog,
+  providerModelsRefreshing,
+  onHardRefreshProviderModels,
+  currentSessionId,
+  onSelectProviderModel,
+}: {
+  data: ModelCommandData;
+  providerModelCatalog: Partial<Record<LLMProvider, ProviderModelsDefinition>>;
+  providerModelCacheCatalog: Partial<Record<LLMProvider, ProviderModelsCacheInfo>>;
+  providerModelsRefreshing: boolean;
+  onHardRefreshProviderModels: () => void;
+  currentSessionId: string | null;
+  onSelectProviderModel: CommandResultModalProps['onSelectProviderModel'];
+}) {
+  const [query, setQuery] = useState('');
+  const [copiedModel, setCopiedModel] = useState<string | null>(null);
+  const [changingModel, setChangingModel] = useState<string | null>(null);
+  const [pendingSessionModel, setPendingSessionModel] = useState<string | null>(null);
+  const [selectionNotice, setSelectionNotice] = useState<string | null>(null);
+  const currentProvider = (data?.current?.provider || 'claude') as LLMProvider;
+  const currentModel = data?.current?.model || 'Unknown';
+  const providerLabel = data?.current?.providerLabel || getProviderLabel(currentProvider);
+  const liveDefinition = providerModelCatalog[currentProvider];
+  const currentCache = providerModelCacheCatalog[currentProvider] ?? data?.cache;
+  const availableOptions = useMemo<ModelOption[]>(() => {
+    if (liveDefinition?.OPTIONS && liveDefinition.OPTIONS.length > 0) {
+      return liveDefinition.OPTIONS;
+    }
+
+    if (Array.isArray(data?.availableOptions) && data.availableOptions.length > 0) {
+      return data.availableOptions;
+    }
+
+    const availableModels = Array.isArray(data?.availableModels) ? data.availableModels : [];
+    return availableModels.map((model) => ({ value: model, label: model }));
+  }, [data, liveDefinition]);
+  const defaultModel = liveDefinition?.DEFAULT || data?.defaultModel || currentModel;
+
+  const filteredOptions = useMemo(() => {
+    const normalized = query.trim().toLowerCase();
+    if (!normalized) {
+      return availableOptions;
+    }
+
+    return availableOptions.filter((option) => {
+      const haystack = `${option.value} ${option.label || ''} ${option.description || ''}`.toLowerCase();
+      return haystack.includes(normalized);
+    });
+  }, [availableOptions, query]);
+
+  const activeOption = availableOptions.find((option) => option.value === currentModel);
+  const hasConcreteSessionId = typeof currentSessionId === 'string' && currentSessionId.trim().length > 0;
+
+  const copyModel = (model: string) => {
+    if (typeof navigator !== 'undefined' && navigator.clipboard) {
+      void navigator.clipboard.writeText(model).catch(() => undefined);
+    }
+    setCopiedModel(model);
+    window.setTimeout(() => {
+      setCopiedModel((current) => (current === model ? null : current));
+    }, 1300);
+  };
+
+  const handleSelectModel = async (model: string) => {
+    setChangingModel(model);
+    try {
+      const result = await onSelectProviderModel(currentProvider, model, currentSessionId);
+      if (result.scope === 'session') {
+        setPendingSessionModel(result.model);
+        setSelectionNotice(`Next response will resume with ${result.model}.`);
+        return;
+      }
+
+      setPendingSessionModel(null);
+      setSelectionNotice(`Default ${providerLabel} model set to ${result.model}.`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unable to change the model right now.';
+      setSelectionNotice(message);
+    } finally {
+      setChangingModel(null);
+    }
+  };
+
+  return (
+    <div className="flex h-full min-h-0 flex-col gap-2.5">
+      <div className="rounded-2xl border border-border/70 bg-muted/20 p-2.5">
+        <div className="grid gap-2.5 lg:grid-cols-[minmax(0,1.55fr)_minmax(12rem,0.7fr)_minmax(15rem,0.9fr)] lg:items-start">
+          <div className="min-w-0">
+            <div className="flex flex-wrap items-center gap-2">
+              <Badge variant="secondary" className="rounded-lg border border-primary/20 bg-primary/10 px-2.5 py-1 text-[10px] font-semibold uppercase tracking-[0.18em] text-primary">
+                {providerLabel}
+              </Badge>
+              <Badge variant="secondary" className="rounded-lg px-2.5 py-1 text-[10px] font-semibold uppercase tracking-[0.18em] text-foreground">
+                {availableOptions.length} models
+              </Badge>
+            </div>
+
+            <div className="mt-2 rounded-xl border border-primary/15 bg-primary/[0.06] px-3 py-2">
+              <p className="text-[11px] font-bold uppercase tracking-[0.2em] text-primary">Active Model</p>
+              <p className="mt-1 break-all font-mono text-[0.98rem] font-semibold leading-5 text-foreground sm:text-[1.05rem]">
+                {currentModel}
+              </p>
+              {activeOption?.label && activeOption.label !== currentModel && (
+                <p className="mt-1 text-[11px] font-medium text-foreground/85">{activeOption.label}</p>
+              )}
+              {activeOption?.description && (
+                <p className="mt-0.5 line-clamp-1 text-[11px] text-muted-foreground">{activeOption.description}</p>
+              )}
+              {pendingSessionModel && pendingSessionModel !== currentModel && (
+                <p className="mt-1 text-[10px] font-semibold uppercase tracking-[0.16em] text-primary">
+                  Next response: {pendingSessionModel}
+                </p>
+              )}
+            </div>
+          </div>
+
+          <div className="grid gap-2 sm:grid-cols-2 lg:grid-cols-1">
+            <div className="rounded-xl border border-border/60 bg-background/55 px-2.5 py-1.5">
+              <p className="text-[10px] font-bold uppercase tracking-[0.18em] text-foreground/80">Default</p>
+              <p className="mt-1 break-all font-mono text-[11px] font-medium text-foreground">{defaultModel}</p>
+            </div>
+            <div className="rounded-xl border border-border/60 bg-background/55 px-2.5 py-1.5">
+              <p className="text-[10px] font-bold uppercase tracking-[0.18em] text-foreground/80">Updated</p>
+              <p className="mt-1 text-[11px] font-medium text-foreground">{formatUpdatedAt(currentCache?.updatedAt)}</p>
+            </div>
+          </div>
+
+          <div className="rounded-xl border border-border/60 bg-background/55 p-2.5">
+            <div className="flex flex-wrap items-center gap-1.5">
+              <p className="text-[10px] font-bold uppercase tracking-[0.18em] text-foreground/80">
+                Catalog Refresh
+              </p>
+              <Badge variant="secondary" className="rounded-md px-1.5 py-0 text-[9px] uppercase tracking-[0.14em]">
+                All providers
+              </Badge>
+            </div>
+            <p className="mt-1.5 text-[11px] leading-4 text-muted-foreground">
+              Model lists are cached for 3 days. Refresh after CLI, auth, or config changes,
+              or when a new model is missing.
+            </p>
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={onHardRefreshProviderModels}
+              disabled={providerModelsRefreshing}
+              className="mt-2 h-8 w-full rounded-xl px-3"
+            >
+              <RefreshCw className={providerModelsRefreshing ? 'animate-spin' : ''} />
+              {providerModelsRefreshing ? 'Refreshing catalogs...' : 'Refresh from providers'}
+            </Button>
+          </div>
+        </div>
+
+        <div className="mt-2 border-t border-border/50 pt-1.5 text-[11px] text-muted-foreground">
+          {hasConcreteSessionId
+            ? 'Selecting a model stores a session override and applies it on the next response for this session.'
+            : 'Selecting a model updates the default model used for new turns in this provider.'}
+          {selectionNotice && <span className="ml-2 text-foreground">{selectionNotice}</span>}
+        </div>
+      </div>
+
+      <div className="flex min-h-0 flex-1 flex-col rounded-3xl border border-border/70 bg-muted/15 p-3 sm:p-4">
+        <div className="mb-2.5 grid gap-2 sm:grid-cols-[1fr_auto] sm:items-center">
+          <div className="min-w-0">
+            <SearchField value={query} onChange={setQuery} placeholder={`Search ${providerLabel} models...`} />
+          </div>
+          <Badge variant="secondary" className="h-9 justify-center rounded-xl px-3 font-mono text-xs">
+            {filteredOptions.length} shown
+          </Badge>
+        </div>
+
+        {filteredOptions.length > 0 ? (
+          <div className="scrollbar-thin min-h-0 flex-1 overflow-y-auto pr-1">
+            <div className="grid gap-2 md:grid-cols-2">
+              {filteredOptions.map((option, index) => {
+                const isCurrent = option.value === currentModel;
+                const wasCopied = copiedModel === option.value;
+                const isPendingSelection = option.value === pendingSessionModel;
+                const isChanging = option.value === changingModel;
+                return (
+                  <div
+                    key={option.value}
+                    className={`settings-content-enter group flex min-h-[4.5rem] items-start gap-3 rounded-2xl border p-3 shadow-sm transition-all duration-200 hover:-translate-y-0.5 hover:shadow-md ${
+                      isCurrent
+                        ? 'border-primary/45 bg-primary/10'
+                        : isPendingSelection
+                          ? 'border-emerald-500/35 bg-emerald-500/10'
+                          : 'border-border/70 bg-background/80 hover:border-primary/30 hover:bg-background'
+                    }`}
+                    style={{ animationDelay: `${Math.min(index * 14, 180)}ms` }}
+                  >
+                    <button
+                      type="button"
+                      onClick={() => handleSelectModel(option.value)}
+                      disabled={Boolean(changingModel)}
+                      className="min-w-0 flex-1 text-left focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                      aria-label={`Use model ${option.value}`}
+                    >
+                      <span className="flex items-center gap-2">
+                        <span className="break-all font-mono text-sm font-semibold text-foreground">{option.value}</span>
+                        {isCurrent && <BadgeCheck className="h-4 w-4 shrink-0 text-primary" />}
+                      </span>
+                      {option.label && option.label !== option.value && (
+                        <span className="mt-1 block text-xs text-muted-foreground">{option.label}</span>
+                      )}
+                      {option.description && (
+                        <span className="mt-1 block text-xs leading-5 text-muted-foreground">{option.description}</span>
+                      )}
+                      {isCurrent && <span className="mt-2 block text-[11px] font-semibold uppercase tracking-[0.16em] text-primary">Current selection</span>}
+                      {isPendingSelection && !isCurrent && (
+                        <span className="mt-2 block text-[11px] font-semibold uppercase tracking-[0.16em] text-emerald-400">
+                          Next response selection
+                        </span>
+                      )}
+                      {isChanging && (
+                        <span className="mt-2 block text-[11px] font-semibold uppercase tracking-[0.16em] text-primary">
+                          Applying...
+                        </span>
+                      )}
+                    </button>
+                    <button
+                      type="button"
+                      onClick={() => copyModel(option.value)}
+                      className="rounded-lg border border-border/70 bg-muted/30 p-2 text-muted-foreground transition-colors group-hover:text-primary"
+                      aria-label={`Copy model id ${option.value}`}
+                    >
+                      {wasCopied ? <Check className="h-4 w-4" /> : <Clipboard className="h-4 w-4" />}
+                    </button>
+                  </div>
+                );
+              })}
+            </div>
+          </div>
+        ) : (
+          <div className="rounded-2xl border border-dashed border-border bg-background/60 px-4 py-10 text-center text-sm text-muted-foreground">
+            No models match that search.
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function CostContent({ data }: { data: CostCommandData }) {
+  const used = Number(data.tokenUsage?.used ?? 0);
+  const total = Number(data.tokenUsage?.total ?? 0);
+  const model = data.model || 'Unknown';
+  const provider = getProviderLabel(data.provider, data.provider || 'Unknown');
+  const hasBreakdown =
+    typeof data.tokenBreakdown?.input === 'number' ||
+    typeof data.tokenBreakdown?.output === 'number';
+  const usageRows = [
+    { label: 'Total tokens used', value: formatNumber(used), icon: Activity },
+    ...(hasBreakdown
+      ? [
+          {
+            label: 'Input tokens',
+            value: formatNumber(Number(data.tokenBreakdown?.input ?? 0)),
+            icon: TerminalSquare,
+          },
+          {
+            label: 'Output tokens',
+            value: formatNumber(Number(data.tokenBreakdown?.output ?? 0)),
+            icon: Coins,
+          },
+        ]
+      : [
+          {
+            label: 'Breakdown',
+            value: 'Unavailable',
+            icon: TerminalSquare,
+          },
+        ]),
+    ...(total > 0
+      ? [{ label: 'Context window', value: formatNumber(total), icon: Gauge }]
+      : []),
+  ];
+
+  return (
+    <div className="space-y-4">
+      <div className="overflow-hidden rounded-2xl border border-border/70 bg-background/75">
+        {usageRows.map((row) => {
+          const Icon = row.icon;
+
+          return (
+            <div
+              key={row.label}
+              className="flex items-center justify-between gap-4 border-b border-border/60 px-4 py-3 last:border-b-0"
+            >
+              <div className="flex min-w-0 items-center gap-3">
+                <span className="grid h-9 w-9 shrink-0 place-items-center rounded-xl border border-primary/20 bg-primary/10 text-primary">
+                  <Icon className="h-4 w-4" />
+                </span>
+                <span className="truncate text-sm font-medium text-foreground">{row.label}</span>
+              </div>
+              <span className="shrink-0 font-mono text-sm font-semibold text-foreground">{row.value}</span>
+            </div>
+          );
+        })}
+      </div>
+
+      <div className="rounded-2xl border border-border/70 bg-muted/20 p-4">
+        <div className="grid gap-3 sm:grid-cols-2">
+          <div>
+            <p className="text-[11px] font-semibold uppercase tracking-[0.18em] text-muted-foreground">Provider</p>
+            <p className="mt-1 text-sm font-semibold text-foreground">{provider}</p>
+          </div>
+          <div>
+            <p className="text-[11px] font-semibold uppercase tracking-[0.18em] text-muted-foreground">Model</p>
+            <p className="mt-1 break-all font-mono text-sm text-foreground">{model}</p>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function StatusContent({ data }: { data: StatusCommandData }) {
+  const memoryRssMb = data.memoryUsage?.rssMb;
+  const rows = [
+    { label: 'Package', value: data.packageName || 'claude-code-ui', icon: Package },
+    { label: 'Version', value: data.version || 'Unknown', icon: BadgeCheck, tone: 'success' as const },
+    { label: 'Uptime', value: data.uptime || 'Unknown', icon: Timer },
+    { label: 'Provider', value: getProviderLabel(data.provider, data.provider || 'Unknown'), icon: Server, tone: 'primary' as const },
+    { label: 'Model', value: data.model || 'Unknown', icon: Cpu },
+    { label: 'Node.js', value: data.nodeVersion || 'Unknown', icon: TerminalSquare },
+    { label: 'Platform', value: data.platform || 'Unknown', icon: Activity },
+    { label: 'Memory', value: typeof memoryRssMb === 'number' ? `${memoryRssMb} MB RSS` : 'Unknown', icon: Gauge },
+  ];
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center justify-between rounded-3xl border border-emerald-500/25 bg-emerald-500/10 p-4">
+        <div className="flex items-center gap-3">
+          <span className="relative flex h-3 w-3">
+            <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-emerald-400 opacity-75" />
+            <span className="relative inline-flex h-3 w-3 rounded-full bg-emerald-500" />
+          </span>
+          <div>
+            <p className="text-sm font-semibold text-foreground">Runtime online</p>
+            <p className="text-xs text-muted-foreground">Process {data.pid ? `#${data.pid}` : 'status'} is responding.</p>
+          </div>
+        </div>
+        <Badge className="rounded-full bg-emerald-500 text-white hover:bg-emerald-500">Healthy</Badge>
+      </div>
+
+      <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-4">
+        {rows.map((row) => (
+          <MetricCard key={row.label} label={row.label} value={String(row.value)} icon={row.icon} tone={row.tone} />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export default function CommandResultModal({
+  payload,
+  onClose,
+  providerModelCatalog,
+  providerModelCacheCatalog,
+  providerModelsRefreshing,
+  onHardRefreshProviderModels,
+  currentSessionId,
+  onSelectProviderModel,
+}: CommandResultModalProps) {
+  const isOpen = Boolean(payload);
+  const kind = payload?.kind;
+  const isModelsModal = kind === 'models';
+
+  const modalMeta = {
+    help: {
+      eyebrow: 'Command center',
+      title: 'Help & Shortcuts',
+      subtitle: 'Search built-ins, syntax patterns, and command usage without leaving the chat.',
+      icon: CircleHelp,
+    },
+    models: {
+      eyebrow: 'Model inventory',
+      title: 'Available Models',
+      subtitle: 'Browse, search, and copy model IDs for the active provider.',
+      icon: Cpu,
+    },
+    cost: {
+      eyebrow: 'Session telemetry',
+      title: 'Token Usage',
+      subtitle: 'Input, output, and total token counts for this session.',
+      icon: Coins,
+    },
+    status: {
+      eyebrow: 'Runtime health',
+      title: 'System Status',
+      subtitle: 'Version, provider, runtime, and environment details in one place.',
+      icon: Activity,
+    },
+  } as const;
+
+  const activeMeta = kind ? modalMeta[kind] : null;
+  const HeaderIcon = activeMeta?.icon || Sparkles;
+
+  return (
+    <Dialog open={isOpen} onOpenChange={(open) => !open && onClose()}>
+      <DialogContent className="flex h-[min(92dvh,48rem)] w-[calc(100vw-1rem)] max-w-5xl flex-col overflow-hidden rounded-3xl border-border/80 bg-popover/95 p-0 shadow-2xl backdrop-blur-xl sm:w-[min(94vw,64rem)]">
+        <DialogTitle>{activeMeta?.title || 'Command Result'}</DialogTitle>
+
+        <div
+          className={`relative shrink-0 overflow-hidden border-b border-border/70 bg-gradient-to-br from-primary/15 via-background to-muted/40 ${
+            isModelsModal ? 'px-4 pb-3 pt-3 sm:px-5 sm:pb-4 sm:pt-4' : 'px-4 pb-4 pt-4 sm:px-6 sm:pb-5 sm:pt-5'
+          }`}
+        >
+          <div className="pointer-events-none absolute -left-20 -top-24 h-56 w-56 rounded-full bg-primary/20 blur-3xl" />
+          <div className="pointer-events-none absolute right-0 top-0 h-full w-1/2 bg-[radial-gradient(circle_at_top_right,hsl(var(--primary)/0.16),transparent_58%)]" />
+
+          <div className="relative flex items-start justify-between gap-3">
+            <div className="flex min-w-0 items-start gap-3 sm:items-center">
+              <div
+                className={`rounded-2xl border border-primary/30 bg-primary/10 text-primary shadow-sm ${
+                  isModelsModal ? 'p-2.5' : 'p-3'
+                }`}
+              >
+                <HeaderIcon className={isModelsModal ? 'h-4 w-4' : 'h-5 w-5'} />
+              </div>
+              <div className="min-w-0">
+                <p className="text-[12px] font-bold uppercase tracking-[0.22em] text-primary">
+                  {activeMeta?.eyebrow}
+                </p>
+                <p className={`mt-1 font-semibold tracking-tight text-foreground ${isModelsModal ? 'text-xl sm:text-2xl' : 'text-xl sm:text-2xl'}`}>
+                  {activeMeta?.title}
+                </p>
+                <p className={`mt-1 max-w-2xl ${isModelsModal ? 'text-sm leading-5 text-foreground/75' : 'text-sm leading-5 text-muted-foreground'}`}>
+                  {activeMeta?.subtitle}
+                </p>
+              </div>
+            </div>
+
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon"
+              onClick={onClose}
+              className="h-9 w-9 shrink-0 rounded-xl text-muted-foreground hover:bg-background/70 hover:text-foreground"
+              aria-label="Close command result modal"
+            >
+              <X className="h-4 w-4" />
+            </Button>
+          </div>
+        </div>
+
+        <div className="settings-content-enter min-h-0 flex-1 overflow-hidden px-4 py-4 sm:px-6 sm:py-5">
+          {payload?.kind === 'help' && <HelpContent data={payload.data as HelpCommandData} />}
+          {payload?.kind === 'models' && (
+            <ModelsContent
+              data={payload.data as ModelCommandData}
+              providerModelCatalog={providerModelCatalog}
+              providerModelCacheCatalog={providerModelCacheCatalog}
+              providerModelsRefreshing={providerModelsRefreshing}
+              onHardRefreshProviderModels={onHardRefreshProviderModels}
+              currentSessionId={currentSessionId}
+              onSelectProviderModel={onSelectProviderModel}
+            />
+          )}
+          {payload?.kind === 'cost' && <CostContent data={payload.data as CostCommandData} />}
+          {payload?.kind === 'status' && <StatusContent data={payload.data as StatusCommandData} />}
+        </div>
+
+        <div className="flex shrink-0 flex-col gap-3 border-t border-border/70 bg-muted/20 px-4 py-3 text-xs text-muted-foreground sm:flex-row sm:items-center sm:justify-between sm:px-6">
+          <div className="flex items-center gap-2">
+            <Gauge className="h-3.5 w-3.5" />
+            <span>Esc closes the modal.</span>
+          </div>
+          <Button type="button" variant="outline" size="sm" onClick={onClose} className="rounded-xl">
+            Close
+          </Button>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
diff --git a/src/components/chat/view/subcomponents/MessageComponent.tsx b/src/components/chat/view/subcomponents/MessageComponent.tsx
index 1b678a57..fa013783 100644
--- a/src/components/chat/view/subcomponents/MessageComponent.tsx
+++ b/src/components/chat/view/subcomponents/MessageComponent.tsx
@@ -176,7 +176,19 @@ const MessageComponent = memo(({ message, prevMessage, createDiff, onFileOpen, o
                 </div>
               )}
               <div className="text-sm font-medium text-gray-900 dark:text-white">
-                {message.type === 'error' ? t('messageTypes.error') : message.type === 'tool' ? t('messageTypes.tool') : (provider === 'cursor' ? t('messageTypes.cursor') : provider === 'codex' ? t('messageTypes.codex') : provider === 'gemini' ? t('messageTypes.gemini') : t('messageTypes.claude'))}
+                {message.type === 'error'
+                  ? t('messageTypes.error')
+                  : message.type === 'tool'
+                    ? t('messageTypes.tool')
+                    : (provider === 'cursor'
+                        ? t('messageTypes.cursor')
+                        : provider === 'codex'
+                          ? t('messageTypes.codex')
+                          : provider === 'gemini'
+                            ? t('messageTypes.gemini')
+                            : provider === 'opencode'
+                              ? t('messageTypes.opencode', { defaultValue: 'OpenCode' })
+                              : t('messageTypes.claude'))}
               </div>
             </div>
           )}
diff --git a/src/components/chat/view/subcomponents/ProviderSelectionEmptyState.tsx b/src/components/chat/view/subcomponents/ProviderSelectionEmptyState.tsx
index 04569e60..a336b953 100644
--- a/src/components/chat/view/subcomponents/ProviderSelectionEmptyState.tsx
+++ b/src/components/chat/view/subcomponents/ProviderSelectionEmptyState.tsx
@@ -1,16 +1,13 @@
-import React, { useCallback, useEffect, useMemo, useState } from "react";
+import React, { useCallback, useMemo, useState } from "react";
 import { Check, ChevronDown } from "lucide-react";
-import { useTranslation } from "react-i18next";
+import { Trans, useTranslation } from "react-i18next";
 
-import { useServerPlatform } from "../../../../hooks/useServerPlatform";
+import type {
+  ProjectSession,
+  LLMProvider,
+  ProviderModelsDefinition,
+} from "../../../../types/app";
 import SessionProviderLogo from "../../../llm-logo-provider/SessionProviderLogo";
-import {
-  CLAUDE_MODELS,
-  CURSOR_MODELS,
-  CODEX_MODELS,
-  GEMINI_MODELS,
-} from "../../../../../shared/modelConstants";
-import type { ProjectSession, LLMProvider } from "../../../../types/app";
 import { NextTaskBanner } from "../../../task-master";
 import {
   Dialog,
@@ -26,6 +23,17 @@ import {
   Card,
 } from "../../../../shared/view/ui";
 
+const PROVIDER_META: { id: LLMProvider; name: string }[] = [
+  { id: "claude", name: "Anthropic" },
+  { id: "codex", name: "OpenAI" },
+  { id: "gemini", name: "Google" },
+  { id: "cursor", name: "Cursor" },
+  { id: "opencode", name: "OpenCode" },
+];
+
+const MOD_KEY =
+  typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform) ? "⌘" : "Ctrl";
+
 type ProviderSelectionEmptyStateProps = {
   selectedSession: ProjectSession | null;
   currentSessionId: string | null;
@@ -40,6 +48,10 @@ type ProviderSelectionEmptyStateProps = {
   setCodexModel: (model: string) => void;
   geminiModel: string;
   setGeminiModel: (model: string) => void;
+  opencodeModel: string;
+  setOpenCodeModel: (model: string) => void;
+  providerModelCatalog: Partial<Record<LLMProvider, ProviderModelsDefinition>>;
+  providerModelsLoading: boolean;
   tasksEnabled: boolean;
   isTaskMasterInstalled: boolean | null;
   onShowAllTasks?: (() => void) | null;
@@ -49,21 +61,15 @@ type ProviderSelectionEmptyStateProps = {
 type ProviderGroup = {
   id: LLMProvider;
   name: string;
-  models: { value: string; label: string }[];
+  models: { value: string; label: string; description?: string }[];
 };
 
-const PROVIDER_GROUPS: ProviderGroup[] = [
-  { id: "claude", name: "Anthropic", models: CLAUDE_MODELS.OPTIONS },
-  { id: "cursor", name: "Cursor", models: CURSOR_MODELS.OPTIONS },
-  { id: "codex", name: "OpenAI", models: CODEX_MODELS.OPTIONS },
-  { id: "gemini", name: "Google", models: GEMINI_MODELS.OPTIONS },
-];
-
-function getModelConfig(p: LLMProvider) {
-  if (p === "claude") return CLAUDE_MODELS;
-  if (p === "codex") return CODEX_MODELS;
-  if (p === "gemini") return GEMINI_MODELS;
-  return CURSOR_MODELS;
+function getModelConfig(
+  p: LLMProvider,
+  catalog: Partial<Record<LLMProvider, ProviderModelsDefinition>>,
+): ProviderModelsDefinition {
+  const entry = catalog[p];
+  return entry ?? { OPTIONS: [], DEFAULT: "" };
 }
 
 function getCurrentModel(
@@ -72,10 +78,12 @@ function getCurrentModel(
   cu: string,
   co: string,
   g: string,
+  o: string,
 ) {
   if (p === "claude") return c;
   if (p === "codex") return co;
   if (p === "gemini") return g;
+  if (p === "opencode") return o;
   return cu;
 }
 
@@ -83,6 +91,7 @@ function getProviderDisplayName(p: LLMProvider) {
   if (p === "claude") return "Claude";
   if (p === "cursor") return "Cursor";
   if (p === "codex") return "Codex";
+  if (p === "opencode") return "OpenCode";
   return "Gemini";
 }
 
@@ -100,26 +109,25 @@ export default function ProviderSelectionEmptyState({
   setCodexModel,
   geminiModel,
   setGeminiModel,
+  opencodeModel,
+  setOpenCodeModel,
+  providerModelCatalog,
+  providerModelsLoading,
   tasksEnabled,
   isTaskMasterInstalled,
   onShowAllTasks,
   setInput,
 }: ProviderSelectionEmptyStateProps) {
   const { t } = useTranslation("chat");
-  const { isWindowsServer } = useServerPlatform();
   const [dialogOpen, setDialogOpen] = useState(false);
 
-  const visibleProviderGroups = useMemo(
-    () => (isWindowsServer ? PROVIDER_GROUPS.filter((p) => p.id !== "cursor") : PROVIDER_GROUPS),
-    [isWindowsServer],
-  );
-
-  useEffect(() => {
-    if (isWindowsServer && provider === "cursor") {
-      setProvider("claude");
-      localStorage.setItem("selected-provider", "claude");
-    }
-  }, [isWindowsServer, provider, setProvider]);
+  const visibleProviderGroups = useMemo<ProviderGroup[]>(() => {
+    return PROVIDER_META.map((p) => ({
+      id: p.id,
+      name: p.name,
+      models: providerModelCatalog[p.id]?.OPTIONS ?? [],
+    }));
+  }, [providerModelCatalog]);
 
   const nextTaskPrompt = t("tasks.nextTaskPrompt", {
     defaultValue: "Start the next task",
@@ -131,15 +139,16 @@ export default function ProviderSelectionEmptyState({
     cursorModel,
     codexModel,
     geminiModel,
+    opencodeModel,
   );
 
   const currentModelLabel = useMemo(() => {
-    const config = getModelConfig(provider);
+    const config = getModelConfig(provider, providerModelCatalog);
     const found = config.OPTIONS.find(
       (o: { value: string; label: string }) => o.value === currentModel,
     );
     return found?.label || currentModel;
-  }, [provider, currentModel]);
+  }, [provider, currentModel, providerModelCatalog]);
 
   const setModelForProvider = useCallback(
     (providerId: LLMProvider, modelValue: string) => {
@@ -152,12 +161,15 @@ export default function ProviderSelectionEmptyState({
       } else if (providerId === "gemini") {
         setGeminiModel(modelValue);
         localStorage.setItem("gemini-model", modelValue);
+      } else if (providerId === "opencode") {
+        setOpenCodeModel(modelValue);
+        localStorage.setItem("opencode-model", modelValue);
       } else {
         setCursorModel(modelValue);
         localStorage.setItem("cursor-model", modelValue);
       }
     },
-    [setClaudeModel, setCursorModel, setCodexModel, setGeminiModel],
+    [setClaudeModel, setCursorModel, setCodexModel, setGeminiModel, setOpenCodeModel],
   );
 
   const handleModelSelect = useCallback(
@@ -219,6 +231,9 @@ export default function ProviderSelectionEmptyState({
 
             <DialogContent className="max-w-md overflow-hidden p-0">
               <DialogTitle>Model Selector</DialogTitle>
+              <div className="border-b border-border/60 bg-muted/20 px-4 py-3">
+                <p className="text-sm font-semibold text-foreground">Choose a model</p>
+              </div>
               <Command>
                 <CommandInput
                   placeholder={t("providerSelection.searchModels", {
@@ -231,9 +246,14 @@ export default function ProviderSelectionEmptyState({
                       defaultValue: "No models found.",
                     })}
                   </CommandEmpty>
-                  {visibleProviderGroups.map((group) => (
+                  {visibleProviderGroups.map((group, idx) => (
                     <CommandGroup
                       key={group.id}
+                      className={
+                        idx > 0
+                          ? "border-t border-border/40 [&_[cmdk-group-heading]]:mt-1 [&_[cmdk-group-heading]]:uppercase [&_[cmdk-group-heading]]:tracking-wider"
+                          : "[&_[cmdk-group-heading]]:uppercase [&_[cmdk-group-heading]]:tracking-wider"
+                      }
                       heading={
                         <span className="flex items-center gap-1.5">
                           <SessionProviderLogo provider={group.id} className="h-3.5 w-3.5 shrink-0" />
@@ -241,15 +261,28 @@ export default function ProviderSelectionEmptyState({
                         </span>
                       }
                     >
+                      {group.models.length === 0 && providerModelsLoading ? (
+                        <CommandItem disabled className="ml-4 border-l border-border/40 pl-4 text-muted-foreground">
+                          {t("providerSelection.loadingModels", { defaultValue: "Loading models…" })}
+                        </CommandItem>
+                      ) : null}
                       {group.models.map((model) => {
                         const isSelected = provider === group.id && currentModel === model.value;
                         return (
                           <CommandItem
                             key={`${group.id}-${model.value}`}
-                            value={`${group.name} ${model.label}`}
+                            value={`${group.name} ${model.label} ${model.description || ''}`}
                             onSelect={() => handleModelSelect(group.id, model.value)}
+                            className="ml-4 border-l border-border/40 pl-4"
                           >
-                            <span className="flex-1 truncate">{model.label}</span>
+                            <div className="min-w-0 flex-1">
+                              <div className="truncate">{model.label}</div>
+                              {model.description && (
+                                <div className="truncate text-xs text-muted-foreground">
+                                  {model.description}
+                                </div>
+                              )}
+                            </div>
                             {isSelected && (
                               <Check className="ml-auto h-4 w-4 shrink-0 text-primary" />
                             )}
@@ -278,10 +311,26 @@ export default function ProviderSelectionEmptyState({
                 gemini: t("providerSelection.readyPrompt.gemini", {
                   model: geminiModel,
                 }),
+                opencode: t("providerSelection.readyPrompt.opencode", {
+                  model: opencodeModel,
+                  defaultValue: "Ready with OpenCode {{model}}",
+                }),
               }[provider]
             }
           </p>
 
+          <p className="mt-3 flex items-center justify-center gap-1.5 text-center text-xs text-muted-foreground/60">
+            <Trans
+              i18nKey="providerSelection.pressToSearch"
+              values={{ shortcut: MOD_KEY === "⌘" ? "⌘K" : "Ctrl+K" }}
+              components={{
+                kbd: (
+                  <kbd className="inline-flex items-center gap-0.5 rounded border border-border/60 bg-muted/40 px-1.5 py-0.5 font-mono text-[10px]" />
+                ),
+              }}
+            />
+          </p>
+
           {provider && tasksEnabled && isTaskMasterInstalled && (
             <div className="mt-5">
               <NextTaskBanner
diff --git a/src/components/chat/view/subcomponents/TokenUsagePie.tsx b/src/components/chat/view/subcomponents/TokenUsagePie.tsx
deleted file mode 100644
index 1e7adb17..00000000
--- a/src/components/chat/view/subcomponents/TokenUsagePie.tsx
+++ /dev/null
@@ -1,54 +0,0 @@
-type TokenUsagePieProps = {
-  used: number;
-  total: number;
-};
-
-export default function TokenUsagePie({ used, total }: TokenUsagePieProps) {
-  // Token usage visualization component
-  // Only bail out on missing values or non‐positive totals; allow used===0 to render 0%
-  if (used == null || total == null || total <= 0) return null;
-
-  const percentage = Math.min(100, (used / total) * 100);
-  const radius = 10;
-  const circumference = 2 * Math.PI * radius;
-  const offset = circumference - (percentage / 100) * circumference;
-
-  // Color based on usage level
-  const getColor = () => {
-    if (percentage < 50) return '#3b82f6'; // blue
-    if (percentage < 75) return '#f59e0b'; // orange
-    return '#ef4444'; // red
-  };
-
-  return (
-    <div className="flex items-center gap-2 text-xs text-gray-600 dark:text-gray-400">
-      <svg width="24" height="24" viewBox="0 0 24 24" className="-rotate-90 transform">
-        {/* Background circle */}
-        <circle
-          cx="12"
-          cy="12"
-          r={radius}
-          fill="none"
-          stroke="currentColor"
-          strokeWidth="2"
-          className="text-gray-300 dark:text-gray-600"
-        />
-        {/* Progress circle */}
-        <circle
-          cx="12"
-          cy="12"
-          r={radius}
-          fill="none"
-          stroke={getColor()}
-          strokeWidth="2"
-          strokeDasharray={circumference}
-          strokeDashoffset={offset}
-          strokeLinecap="round"
-        />
-      </svg>
-      <span title={`${used.toLocaleString()} / ${total.toLocaleString()} tokens`}>
-        {percentage.toFixed(1)}%
-      </span>
-    </div>
-  );
-}
\ No newline at end of file
diff --git a/src/components/chat/view/subcomponents/TokenUsageSummary.tsx b/src/components/chat/view/subcomponents/TokenUsageSummary.tsx
new file mode 100644
index 00000000..5d9f575b
--- /dev/null
+++ b/src/components/chat/view/subcomponents/TokenUsageSummary.tsx
@@ -0,0 +1,53 @@
+import { ActivityIcon } from 'lucide-react';
+
+type TokenUsageSummaryProps = {
+  usage: Record<string, unknown> | null;
+};
+
+const formatTokenCount = (value: number) => {
+  if (!Number.isFinite(value) || value <= 0) {
+    return '0';
+  }
+
+  if (value >= 1_000_000) {
+    return `${(value / 1_000_000).toFixed(value >= 10_000_000 ? 0 : 1)}M`;
+  }
+
+  if (value >= 10_000) {
+    return `${Math.round(value / 1_000)}K`;
+  }
+
+  if (value >= 1_000) {
+    return `${(value / 1_000).toFixed(1)}K`;
+  }
+
+  return value.toLocaleString();
+};
+
+const readUsageNumber = (value: unknown) => {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : 0;
+};
+
+export default function TokenUsageSummary({ usage }: TokenUsageSummaryProps) {
+  const breakdown =
+    usage?.breakdown && typeof usage.breakdown === 'object'
+      ? usage.breakdown as Record<string, unknown>
+      : null;
+  const inputTokens = readUsageNumber(usage?.inputTokens ?? breakdown?.input);
+  const outputTokens = readUsageNumber(usage?.outputTokens ?? breakdown?.output);
+  const usedTokens = readUsageNumber(usage?.used) || inputTokens + outputTokens;
+
+  return (
+    <div
+      className="inline-flex h-9 items-center gap-1.5 rounded-lg border border-border/70 bg-background/70 px-2 text-xs text-muted-foreground shadow-sm transition-colors hover:border-primary/25 hover:text-foreground sm:gap-2 sm:px-2.5"
+      title={`${usedTokens.toLocaleString()} tokens used`}
+    >
+      <span className="grid h-5 w-5 place-items-center rounded-md bg-primary/10 text-primary">
+        <ActivityIcon className="h-3.5 w-3.5" />
+      </span>
+      <span className="font-medium text-foreground">{formatTokenCount(usedTokens)}</span>
+      <span className="hidden text-muted-foreground/70 sm:inline">tokens</span>
+    </div>
+  );
+}
diff --git a/src/components/code-editor/hooks/useCodeEditorDocument.ts b/src/components/code-editor/hooks/useCodeEditorDocument.ts
index 5e3adc3e..b2b7acd2 100644
--- a/src/components/code-editor/hooks/useCodeEditorDocument.ts
+++ b/src/components/code-editor/hooks/useCodeEditorDocument.ts
@@ -23,7 +23,10 @@ export const useCodeEditorDocument = ({ file, projectPath }: UseCodeEditorDocume
   const [saveSuccess, setSaveSuccess] = useState(false);
   const [saveError, setSaveError] = useState<string | null>(null);
   const [isBinary, setIsBinary] = useState(false);
-  const fileProjectName = file.projectName ?? projectPath;
+  // `fileProjectId` is the DB primary key passed down from the editor sidebar;
+  // the fallback to `projectPath` preserves older callers that didn't yet
+  // propagate the identifier.
+  const fileProjectId = file.projectId ?? projectPath;
   const filePath = file.path;
   const fileName = file.name;
   const fileDiffNewString = file.diffInfo?.new_string;
@@ -49,11 +52,11 @@ export const useCodeEditorDocument = ({ file, projectPath }: UseCodeEditorDocume
           return;
         }
 
-        if (!fileProjectName) {
+        if (!fileProjectId) {
           throw new Error('Missing project identifier');
         }
 
-        const response = await api.readFile(fileProjectName, filePath);
+        const response = await api.readFile(fileProjectId, filePath);
         if (!response.ok) {
           throw new Error(`Failed to load file: ${response.status} ${response.statusText}`);
         }
@@ -70,18 +73,18 @@ export const useCodeEditorDocument = ({ file, projectPath }: UseCodeEditorDocume
     };
 
     loadFileContent();
-  }, [file.diffInfo, file.name, fileDiffNewString, fileDiffOldString, fileName, filePath, fileProjectName]);
+  }, [file.diffInfo, file.name, fileDiffNewString, fileDiffOldString, fileName, filePath, fileProjectId]);
 
   const handleSave = useCallback(async () => {
     setSaving(true);
     setSaveError(null);
 
     try {
-      if (!fileProjectName) {
+      if (!fileProjectId) {
         throw new Error('Missing project identifier');
       }
 
-      const response = await api.saveFile(fileProjectName, filePath, content);
+      const response = await api.saveFile(fileProjectId, filePath, content);
 
       if (!response.ok) {
         const contentType = response.headers.get('content-type');
@@ -106,7 +109,7 @@ export const useCodeEditorDocument = ({ file, projectPath }: UseCodeEditorDocume
     } finally {
       setSaving(false);
     }
-  }, [content, filePath, fileProjectName]);
+  }, [content, filePath, fileProjectId]);
 
   const handleDownload = useCallback(() => {
     const blob = new Blob([content], { type: 'text/plain' });
diff --git a/src/components/code-editor/hooks/useEditorSidebar.ts b/src/components/code-editor/hooks/useEditorSidebar.ts
index d5a650b4..87e4303d 100644
--- a/src/components/code-editor/hooks/useEditorSidebar.ts
+++ b/src/components/code-editor/hooks/useEditorSidebar.ts
@@ -29,11 +29,13 @@ export const useEditorSidebar = ({
       setEditingFile({
         name: fileName,
         path: filePath,
-        projectName: selectedProject?.name,
+        // DB projectId is forwarded to the editor so it can read/save files
+        // via `/api/projects/:projectId/file` endpoints.
+        projectId: selectedProject?.projectId,
         diffInfo,
       });
     },
-    [selectedProject?.name],
+    [selectedProject?.projectId],
   );
 
   const handleCloseEditor = useCallback(() => {
diff --git a/src/components/code-editor/types/types.ts b/src/components/code-editor/types/types.ts
index 8427a5e0..799868c5 100644
--- a/src/components/code-editor/types/types.ts
+++ b/src/components/code-editor/types/types.ts
@@ -7,7 +7,9 @@ export type CodeEditorDiffInfo = {
 export type CodeEditorFile = {
   name: string;
   path: string;
-  projectName?: string;
+  // DB projectId; used by the editor to build `/api/projects/:projectId/file`
+  // URLs for reading and saving content.
+  projectId?: string;
   diffInfo?: CodeEditorDiffInfo | null;
   [key: string]: unknown;
 };
diff --git a/src/components/code-editor/view/CodeEditor.tsx b/src/components/code-editor/view/CodeEditor.tsx
index e68a73d3..5861ce71 100644
--- a/src/components/code-editor/view/CodeEditor.tsx
+++ b/src/components/code-editor/view/CodeEditor.tsx
@@ -3,6 +3,7 @@ import { unifiedMergeView } from '@codemirror/merge';
 import type { Extension } from '@codemirror/state';
 import { useMemo, useState } from 'react';
 import { useTranslation } from 'react-i18next';
+import { usePaletteOps } from '../../../contexts/PaletteOpsContext';
 import { useCodeEditorDocument } from '../hooks/useCodeEditorDocument';
 import { useCodeEditorSettings } from '../hooks/useCodeEditorSettings';
 import { useEditorKeyboardShortcuts } from '../hooks/useEditorKeyboardShortcuts';
@@ -36,6 +37,7 @@ export default function CodeEditor({
   onPopOut = null,
 }: CodeEditorProps) {
   const { t } = useTranslation('codeEditor');
+  const paletteOps = usePaletteOps();
   const [isFullscreen, setIsFullscreen] = useState(false);
   const [showDiff, setShowDiff] = useState(Boolean(file.diffInfo));
   const [markdownPreview, setMarkdownPreview] = useState(false);
@@ -199,7 +201,7 @@ export default function CodeEditor({
             saving={saving}
             saveSuccess={saveSuccess}
             onToggleMarkdownPreview={() => setMarkdownPreview((previous) => !previous)}
-            onOpenSettings={() => window.openSettings?.('appearance')}
+            onOpenSettings={() => paletteOps.openSettings('appearance')}
             onDownload={handleDownload}
             onSave={handleSave}
             onToggleFullscreen={() => setIsFullscreen((previous) => !previous)}
diff --git a/src/components/command-palette/CommandPalette.tsx b/src/components/command-palette/CommandPalette.tsx
new file mode 100644
index 00000000..db3bd87b
--- /dev/null
+++ b/src/components/command-palette/CommandPalette.tsx
@@ -0,0 +1,373 @@
+import * as React from 'react';
+import { useNavigate } from 'react-router-dom';
+import {
+  ArrowDownToLine,
+  ArrowUpFromLine,
+  ChevronRight,
+  FileText,
+  GitCommit,
+  GitMerge,
+  MessageSquare,
+  MessageSquarePlus,
+  RefreshCw,
+  Settings,
+  SunMoon,
+  X,
+} from 'lucide-react';
+
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  Dialog,
+  DialogContent,
+  DialogTitle,
+} from '../../shared/view/ui';
+import { useTheme } from '../../contexts/ThemeContext';
+import { usePaletteOps } from '../../contexts/PaletteOpsContext';
+import { SETTINGS_MAIN_TABS } from '../settings/constants/constants';
+import type { AppTab, Project } from '../../types/app';
+
+import { useSessionsSource } from './sources/useSessionsSource';
+import { useFilesSource } from './sources/useFilesSource';
+import { useCommitsSource } from './sources/useCommitsSource';
+import { useSessionMessageSearch } from './sources/useSessionMessageSearch';
+import { useBranchesSource } from './sources/useBranchesSource';
+import { useGitActions } from './sources/useGitActions';
+
+type Page = 'actions' | 'files' | 'sessions' | 'commits' | 'branches';
+
+const PAGE_LABELS: Record<Page, string> = {
+  actions: 'Actions',
+  files: 'Files',
+  sessions: 'Sessions',
+  commits: 'Commits',
+  branches: 'Branches',
+};
+
+type CommandPaletteProps = {
+  selectedProject: Project | null;
+  onStartNewChat: (project: Project) => void;
+  onOpenSettings: (tab?: string) => void;
+  onShowTab?: (tab: AppTab) => void;
+};
+
+const NAV_TABS: Array<{ id: AppTab; label: string; keywords: string }> = [
+  { id: 'chat', label: 'Go to Chat', keywords: 'chat messages conversation' },
+  { id: 'files', label: 'Go to Files', keywords: 'files file tree explorer' },
+  { id: 'shell', label: 'Go to Shell', keywords: 'shell terminal console' },
+  { id: 'git', label: 'Go to Git', keywords: 'git diff branches' },
+  { id: 'tasks', label: 'Go to Tasks', keywords: 'tasks taskmaster' },
+];
+
+export default function CommandPalette({
+  selectedProject,
+  onStartNewChat,
+  onOpenSettings,
+  onShowTab,
+}: CommandPaletteProps) {
+  const [open, setOpen] = React.useState(false);
+  const [search, setSearch] = React.useState('');
+  const [pages, setPages] = React.useState<Page[]>([]);
+  const { toggleDarkMode } = useTheme();
+  const navigate = useNavigate();
+  const ops = usePaletteOps();
+
+  const page = pages.at(-1);
+
+  React.useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      const isCmdK = (e.metaKey || e.ctrlKey) && !e.shiftKey && !e.altKey && e.key.toLowerCase() === 'k';
+      if (!isCmdK) return;
+      e.preventDefault();
+      setOpen((prev) => !prev);
+    };
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, []);
+
+  React.useEffect(() => {
+    if (!open) {
+      setSearch('');
+      setPages([]);
+    }
+  }, [open]);
+
+  const projectId = selectedProject?.projectId;
+
+  const showActions = !page || page === 'actions';
+  const showSessions = !page || page === 'sessions';
+  const showFiles = !page || page === 'files';
+  const showCommits = !page || page === 'commits';
+  const showBranches = !page || page === 'branches' || page === 'actions';
+
+  const sessions = useSessionsSource(projectId, open && showSessions);
+  const messageMatches = useSessionMessageSearch(projectId, search, open && showSessions);
+  const files = useFilesSource(projectId, open && showFiles);
+  const commits = useCommitsSource(projectId, open && showCommits);
+  const branches = useBranchesSource(projectId, open && showBranches);
+  const git = useGitActions(projectId);
+
+  const sessionRows = React.useMemo(() => {
+    if (!showSessions) return [];
+    type Row = { id: string; label: string; provider?: string; snippet?: string };
+    const byId = new Map<string, Row>();
+    for (const s of sessions) {
+      byId.set(s.id, { id: s.id, label: s.label, provider: s.provider });
+    }
+    for (const m of messageMatches) {
+      const existing = byId.get(m.sessionId);
+      if (existing) {
+        existing.snippet = m.snippet;
+      } else {
+        byId.set(m.sessionId, {
+          id: m.sessionId,
+          label: m.label,
+          provider: m.provider,
+          snippet: m.snippet,
+        });
+      }
+    }
+    return Array.from(byId.values());
+  }, [sessions, messageMatches, showSessions]);
+
+  const run = React.useCallback((fn: () => void) => {
+    setOpen(false);
+    fn();
+  }, []);
+
+  const pushPage = React.useCallback((next: Page) => {
+    setSearch('');
+    setPages((prev) => [...prev, next]);
+  }, []);
+
+  const popPage = React.useCallback(() => {
+    setSearch('');
+    setPages((prev) => prev.slice(0, -1));
+  }, []);
+
+  const handleKeyDown = React.useCallback((e: React.KeyboardEvent) => {
+    if (e.key === 'Backspace' && !search && pages.length > 0) {
+      e.preventDefault();
+      popPage();
+    }
+  }, [search, pages.length, popPage]);
+
+  const startNewChatDisabled = !selectedProject;
+  const browseLimit = 5;
+  const filesShown = page === 'files' ? files : files.slice(0, browseLimit);
+  const commitsShown = page === 'commits' ? commits : commits.slice(0, browseLimit);
+  const sessionsShown = page === 'sessions' ? sessionRows : sessionRows.slice(0, browseLimit);
+  const branchesShown = page === 'branches' ? branches : branches.slice(0, browseLimit);
+
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      <DialogContent className="max-w-xl overflow-hidden p-0">
+        <DialogTitle>Command palette</DialogTitle>
+        <Command label="Command palette" onKeyDown={handleKeyDown}>
+          {page && (
+            <div className="flex items-center gap-2 border-b px-3 py-2">
+              <span className="inline-flex items-center gap-1 rounded-md bg-accent px-2 py-0.5 text-xs font-medium text-accent-foreground">
+                {PAGE_LABELS[page]}
+                <button
+                  type="button"
+                  onClick={popPage}
+                  aria-label="Back to all"
+                  className="ml-0.5 rounded-sm opacity-70 hover:opacity-100"
+                >
+                  <X className="h-3 w-3" />
+                </button>
+              </span>
+              <span className="text-xs text-muted-foreground">Backspace to go back</span>
+            </div>
+          )}
+          <CommandInput
+            placeholder={page ? `Search ${PAGE_LABELS[page].toLowerCase()}…` : 'Type to search anything…'}
+            value={search}
+            onValueChange={setSearch}
+          />
+          <CommandList>
+            <CommandEmpty>No results.</CommandEmpty>
+
+            {showActions && (
+              <CommandGroup heading="Actions">
+                <CommandItem
+                  value="Start new chat"
+                  disabled={startNewChatDisabled}
+                  onSelect={() => {
+                    if (!selectedProject) return;
+                    run(() => onStartNewChat(selectedProject));
+                  }}
+                >
+                  <MessageSquarePlus className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
+                  <span className="flex-1">Start new chat</span>
+                  {startNewChatDisabled && (
+                    <span className="text-xs text-muted-foreground">Select a project first</span>
+                  )}
+                </CommandItem>
+                <CommandItem value="Open settings" onSelect={() => run(() => onOpenSettings())}>
+                  <Settings className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
+                  <span className="flex-1">Open settings</span>
+                </CommandItem>
+                <CommandItem value="Toggle theme dark light mode" onSelect={() => run(toggleDarkMode)}>
+                  <SunMoon className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
+                  <span className="flex-1">Toggle theme</span>
+                </CommandItem>
+              </CommandGroup>
+            )}
+
+            {showActions && (
+              <CommandGroup heading="Navigate">
+                {NAV_TABS.map((tab) => (
+                  <CommandItem
+                    key={tab.id as string}
+                    value={`${tab.label} ${tab.keywords}`}
+                    onSelect={() => run(() => onShowTab?.(tab.id))}
+                  >
+                    <span className="flex-1">{tab.label}</span>
+                  </CommandItem>
+                ))}
+              </CommandGroup>
+            )}
+
+            {showActions && projectId && (
+              <CommandGroup heading="Git">
+                <CommandItem
+                  value="Git Fetch remote"
+                  onSelect={() => run(() => { void git.fetch(); onShowTab?.('git'); })}
+                >
+                  <RefreshCw className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
+                  <span className="flex-1">Git: Fetch</span>
+                </CommandItem>
+                <CommandItem
+                  value="Git Pull merge upstream"
+                  onSelect={() => run(() => { void git.pull(); onShowTab?.('git'); })}
+                >
+                  <ArrowDownToLine className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
+                  <span className="flex-1">Git: Pull</span>
+                </CommandItem>
+                <CommandItem
+                  value="Git Push origin remote"
+                  onSelect={() => run(() => { void git.push(); onShowTab?.('git'); })}
+                >
+                  <ArrowUpFromLine className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
+                  <span className="flex-1">Git: Push</span>
+                </CommandItem>
+              </CommandGroup>
+            )}
+
+            {showActions && (
+              <CommandGroup heading="Settings">
+                {SETTINGS_MAIN_TABS.map(({ id, label, keywords, icon: Icon }) => (
+                  <CommandItem
+                    key={id}
+                    value={`Settings ${label} ${keywords}`}
+                    onSelect={() => run(() => onOpenSettings(id))}
+                  >
+                    <Icon className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
+                    <span className="flex-1">Settings: {label}</span>
+                  </CommandItem>
+                ))}
+              </CommandGroup>
+            )}
+
+            {showSessions && projectId && sessionsShown.length > 0 && (
+              <CommandGroup heading="Sessions">
+                {sessionsShown.map((s) => (
+                  <CommandItem
+                    key={s.id}
+                    value={`${s.label} ${s.snippet ?? ''} ${s.id}`.trim()}
+                    onSelect={() => run(() => navigate(`/session/${s.id}`))}
+                  >
+                    <MessageSquare className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
+                    <div className="flex min-w-0 flex-1 flex-col">
+                      <span className="truncate">{s.label}</span>
+                      {s.snippet && (
+                        <span className="truncate text-xs text-muted-foreground">{s.snippet}</span>
+                      )}
+                    </div>
+                    {s.provider && (
+                      <span className="text-xs text-muted-foreground">{s.provider}</span>
+                    )}
+                  </CommandItem>
+                ))}
+                {!page && sessionRows.length > browseLimit && (
+                  <BrowseAllItem label={`Browse all sessions (${sessionRows.length})`} onSelect={() => pushPage('sessions')} />
+                )}
+              </CommandGroup>
+            )}
+
+            {showFiles && projectId && filesShown.length > 0 && (
+              <CommandGroup heading="Files">
+                {filesShown.map((f) => (
+                  <CommandItem
+                    key={f.path}
+                    value={f.path}
+                    onSelect={() => run(() => ops.openFile(f.path))}
+                  >
+                    <FileText className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
+                    <span className="flex-1 truncate">{f.name}</span>
+                    <span className="truncate text-xs text-muted-foreground">{f.path}</span>
+                  </CommandItem>
+                ))}
+                {!page && files.length > browseLimit && (
+                  <BrowseAllItem label={`Browse all files (${files.length})`} onSelect={() => pushPage('files')} />
+                )}
+              </CommandGroup>
+            )}
+
+            {showCommits && projectId && commitsShown.length > 0 && (
+              <CommandGroup heading="Commits">
+                {commitsShown.map((c) => (
+                  <CommandItem
+                    key={c.hash}
+                    value={`${c.message} ${c.author} ${c.shortHash}`}
+                    onSelect={() => run(() => onShowTab?.('git'))}
+                  >
+                    <GitCommit className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
+                    <span className="font-mono text-xs text-muted-foreground">{c.shortHash}</span>
+                    <span className="flex-1 truncate">{c.message}</span>
+                    <span className="truncate text-xs text-muted-foreground">{c.author}</span>
+                  </CommandItem>
+                ))}
+                {!page && commits.length > browseLimit && (
+                  <BrowseAllItem label={`Browse all commits (${commits.length})`} onSelect={() => pushPage('commits')} />
+                )}
+              </CommandGroup>
+            )}
+
+            {showBranches && projectId && branchesShown.length > 0 && (
+              <CommandGroup heading="Branches">
+                {branchesShown.map((b) => (
+                  <CommandItem
+                    key={`branch-${b.name}`}
+                    value={b.name}
+                    onSelect={() => run(() => { void git.checkout(b.name); onShowTab?.('git'); })}
+                  >
+                    <GitMerge className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
+                    <span className="flex-1 truncate">Switch to: {b.name}</span>
+                  </CommandItem>
+                ))}
+                {!page && branches.length > browseLimit && (
+                  <BrowseAllItem label={`Browse all branches (${branches.length})`} onSelect={() => pushPage('branches')} />
+                )}
+              </CommandGroup>
+            )}
+          </CommandList>
+        </Command>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function BrowseAllItem({ label, onSelect }: { label: string; onSelect: () => void }) {
+  return (
+    <CommandItem value={label} onSelect={onSelect}>
+      <ChevronRight className="h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
+      <span className="flex-1 text-muted-foreground">{label}</span>
+    </CommandItem>
+  );
+}
diff --git a/src/components/command-palette/sources/useApiSource.ts b/src/components/command-palette/sources/useApiSource.ts
new file mode 100644
index 00000000..979a8914
--- /dev/null
+++ b/src/components/command-palette/sources/useApiSource.ts
@@ -0,0 +1,37 @@
+import { useEffect, useState, type DependencyList } from 'react';
+
+export function useApiSource<T, R = unknown>(opts: {
+  enabled: boolean;
+  deps: DependencyList;
+  fetcher: (signal: AbortSignal) => Promise<Response>;
+  parse: (raw: R) => T[];
+}): T[] {
+  const [items, setItems] = useState<T[]>([]);
+  const { enabled, deps, fetcher, parse } = opts;
+
+  useEffect(() => {
+    if (!enabled) {
+      setItems([]);
+      return;
+    }
+
+    const controller = new AbortController();
+
+    fetcher(controller.signal)
+      .then((r) => r.json() as Promise<R>)
+      .then((data) => {
+        if (controller.signal.aborted) return;
+        setItems(parse(data));
+      })
+      .catch((err: unknown) => {
+        if (controller.signal.aborted) return;
+        if (err instanceof DOMException && err.name === 'AbortError') return;
+        setItems([]);
+      });
+
+    return () => controller.abort();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, ...deps]);
+
+  return items;
+}
diff --git a/src/components/command-palette/sources/useBranchesSource.ts b/src/components/command-palette/sources/useBranchesSource.ts
new file mode 100644
index 00000000..33a30870
--- /dev/null
+++ b/src/components/command-palette/sources/useBranchesSource.ts
@@ -0,0 +1,21 @@
+import { authenticatedFetch } from '../../../utils/api';
+
+import { useApiSource } from './useApiSource';
+
+export type BranchResult = { name: string };
+
+interface BranchesResponse {
+  localBranches?: string[];
+}
+
+export function useBranchesSource(projectId: string | undefined, enabled: boolean) {
+  return useApiSource<BranchResult, BranchesResponse>({
+    enabled: enabled && !!projectId,
+    deps: [projectId],
+    fetcher: (signal) => {
+      const params = new URLSearchParams({ project: projectId! });
+      return authenticatedFetch(`/api/git/branches?${params.toString()}`, { signal });
+    },
+    parse: (data) => (data.localBranches ?? []).map((name) => ({ name })),
+  });
+}
diff --git a/src/components/command-palette/sources/useCommitsSource.ts b/src/components/command-palette/sources/useCommitsSource.ts
new file mode 100644
index 00000000..e173fa7f
--- /dev/null
+++ b/src/components/command-palette/sources/useCommitsSource.ts
@@ -0,0 +1,35 @@
+import { authenticatedFetch } from '../../../utils/api';
+
+import { useApiSource } from './useApiSource';
+
+export type CommitResult = {
+  hash: string;
+  shortHash: string;
+  message: string;
+  author: string;
+};
+
+interface CommitsResponse {
+  commits?: Array<{ hash: string; message: string; author: string }>;
+  error?: string;
+}
+
+export function useCommitsSource(projectId: string | undefined, enabled: boolean) {
+  return useApiSource<CommitResult, CommitsResponse>({
+    enabled: enabled && !!projectId,
+    deps: [projectId],
+    fetcher: (signal) => {
+      const params = new URLSearchParams({ project: projectId!, limit: '50' });
+      return authenticatedFetch(`/api/git/commits?${params.toString()}`, { signal });
+    },
+    parse: (data) => {
+      if (!data.commits) return [];
+      return data.commits.map<CommitResult>((c) => ({
+        hash: c.hash,
+        shortHash: c.hash.slice(0, 7),
+        message: c.message,
+        author: c.author,
+      }));
+    },
+  });
+}
diff --git a/src/components/command-palette/sources/useFilesSource.ts b/src/components/command-palette/sources/useFilesSource.ts
new file mode 100644
index 00000000..e96b511a
--- /dev/null
+++ b/src/components/command-palette/sources/useFilesSource.ts
@@ -0,0 +1,42 @@
+import { api } from '../../../utils/api';
+
+import { useApiSource } from './useApiSource';
+
+export type FileResult = {
+  path: string;
+  name: string;
+};
+
+interface FileNode {
+  type: 'file' | 'directory';
+  name: string;
+  path: string;
+  children?: FileNode[];
+}
+
+const MAX_FILES = 500;
+
+function flatten(nodes: FileNode[], out: FileResult[]): void {
+  for (const node of nodes) {
+    if (out.length >= MAX_FILES) return;
+    if (node.type === 'file') {
+      out.push({ path: node.path, name: node.name });
+    } else if (node.children && node.children.length > 0) {
+      flatten(node.children, out);
+    }
+  }
+}
+
+export function useFilesSource(projectId: string | undefined, enabled: boolean) {
+  return useApiSource<FileResult, unknown>({
+    enabled: enabled && !!projectId,
+    deps: [projectId],
+    fetcher: (signal) => api.getFiles(projectId!, { signal }),
+    parse: (data) => {
+      const tree: FileNode[] = Array.isArray(data) ? (data as FileNode[]) : [];
+      const flat: FileResult[] = [];
+      flatten(tree, flat);
+      return flat;
+    },
+  });
+}
diff --git a/src/components/command-palette/sources/useGitActions.ts b/src/components/command-palette/sources/useGitActions.ts
new file mode 100644
index 00000000..cf765f34
--- /dev/null
+++ b/src/components/command-palette/sources/useGitActions.ts
@@ -0,0 +1,38 @@
+import { useCallback } from 'react';
+
+import { authenticatedFetch } from '../../../utils/api';
+
+async function postGit(path: string, body: Record<string, unknown>) {
+  const res = await authenticatedFetch(path, {
+    method: 'POST',
+    body: JSON.stringify(body),
+  });
+  return res.json();
+}
+
+export function useGitActions(projectId: string | undefined) {
+  const fetch = useCallback(() => {
+    if (!projectId) return Promise.resolve();
+    return postGit('/api/git/fetch', { project: projectId });
+  }, [projectId]);
+
+  const pull = useCallback(() => {
+    if (!projectId) return Promise.resolve();
+    return postGit('/api/git/pull', { project: projectId });
+  }, [projectId]);
+
+  const push = useCallback(() => {
+    if (!projectId) return Promise.resolve();
+    return postGit('/api/git/push', { project: projectId });
+  }, [projectId]);
+
+  const checkout = useCallback(
+    (branch: string) => {
+      if (!projectId) return Promise.resolve();
+      return postGit('/api/git/checkout', { project: projectId, branch });
+    },
+    [projectId],
+  );
+
+  return { fetch, pull, push, checkout };
+}
diff --git a/src/components/command-palette/sources/useSessionMessageSearch.ts b/src/components/command-palette/sources/useSessionMessageSearch.ts
new file mode 100644
index 00000000..f8a399eb
--- /dev/null
+++ b/src/components/command-palette/sources/useSessionMessageSearch.ts
@@ -0,0 +1,101 @@
+import { useEffect, useRef, useState } from 'react';
+
+import { api } from '../../../utils/api';
+import type { LLMProvider } from '../../../types/app';
+
+export type SessionMessageMatch = {
+  sessionId: string;
+  label: string;
+  snippet: string;
+  provider: LLMProvider;
+};
+
+type ProjectResult = {
+  projectId: string | null;
+  projectName: string;
+  sessions: Array<{
+    sessionId: string;
+    provider: LLMProvider;
+    sessionSummary: string;
+    matches: Array<{ snippet: string }>;
+  }>;
+};
+
+const MIN_QUERY = 2;
+const DEBOUNCE_MS = 250;
+
+export function useSessionMessageSearch(
+  projectId: string | undefined,
+  query: string,
+  enabled: boolean,
+) {
+  const [items, setItems] = useState<SessionMessageMatch[]>([]);
+  const seqRef = useRef(0);
+  const esRef = useRef<EventSource | null>(null);
+
+  useEffect(() => {
+    const trimmed = query.trim();
+    if (!enabled || !projectId || trimmed.length < MIN_QUERY) {
+      setItems([]);
+      esRef.current?.close();
+      esRef.current = null;
+      return;
+    }
+
+    esRef.current?.close();
+    esRef.current = null;
+    seqRef.current++;
+
+    const handle = setTimeout(() => {
+      const seq = ++seqRef.current;
+      const url = api.searchConversationsUrl(trimmed);
+      const es = new EventSource(url);
+      esRef.current = es;
+      const accumulated: SessionMessageMatch[] = [];
+
+      es.addEventListener('result', (evt) => {
+        if (seq !== seqRef.current) {
+          es.close();
+          return;
+        }
+        try {
+          const data = JSON.parse((evt as MessageEvent).data) as { projectResult: ProjectResult };
+          const pr = data.projectResult;
+          if (pr.projectId !== projectId) return;
+          for (const s of pr.sessions) {
+            accumulated.push({
+              sessionId: s.sessionId,
+              label: s.sessionSummary || s.sessionId,
+              snippet: s.matches[0]?.snippet ?? '',
+              provider: s.provider,
+            });
+          }
+          setItems([...accumulated]);
+        } catch {
+          // ignore malformed
+        }
+      });
+
+      const finish = () => {
+        if (seq !== seqRef.current) return;
+        es.close();
+        esRef.current = null;
+      };
+      es.addEventListener('done', finish);
+      es.addEventListener('error', finish);
+    }, DEBOUNCE_MS);
+
+    return () => {
+      clearTimeout(handle);
+    };
+  }, [projectId, query, enabled]);
+
+  useEffect(() => {
+    return () => {
+      esRef.current?.close();
+      esRef.current = null;
+    };
+  }, []);
+
+  return items;
+}
diff --git a/src/components/command-palette/sources/useSessionsSource.ts b/src/components/command-palette/sources/useSessionsSource.ts
new file mode 100644
index 00000000..3623c798
--- /dev/null
+++ b/src/components/command-palette/sources/useSessionsSource.ts
@@ -0,0 +1,46 @@
+import { authenticatedFetch } from '../../../utils/api';
+import type { LLMProvider, ProjectSession } from '../../../types/app';
+
+import { useApiSource } from './useApiSource';
+
+export type SessionResult = {
+  id: string;
+  label: string;
+  provider?: LLMProvider;
+};
+
+interface SessionsResponse {
+  sessions?: ProjectSession[];
+  cursorSessions?: ProjectSession[];
+  codexSessions?: ProjectSession[];
+  geminiSessions?: ProjectSession[];
+  opencodeSessions?: ProjectSession[];
+}
+
+export function useSessionsSource(projectId: string | undefined, enabled: boolean) {
+  return useApiSource<SessionResult, SessionsResponse>({
+    enabled: enabled && !!projectId,
+    deps: [projectId],
+    fetcher: (signal) => {
+      const params = new URLSearchParams({ limit: '50', offset: '0' });
+      return authenticatedFetch(
+        `/api/projects/${encodeURIComponent(projectId!)}/sessions?${params.toString()}`,
+        { signal },
+      );
+    },
+    parse: (data) => {
+      const all: ProjectSession[] = [
+        ...(data.sessions ?? []),
+        ...(data.cursorSessions ?? []),
+        ...(data.codexSessions ?? []),
+        ...(data.geminiSessions ?? []),
+        ...(data.opencodeSessions ?? []),
+      ];
+      return all.map<SessionResult>((s) => ({
+        id: s.id,
+        label: (s.title || s.summary || s.name || s.id) as string,
+        provider: s.__provider,
+      }));
+    },
+  });
+}
diff --git a/src/components/file-tree/hooks/useFileTreeData.ts b/src/components/file-tree/hooks/useFileTreeData.ts
index 2ac88162..0a7a9b86 100644
--- a/src/components/file-tree/hooks/useFileTreeData.ts
+++ b/src/components/file-tree/hooks/useFileTreeData.ts
@@ -20,9 +20,11 @@ export function useFileTreeData(selectedProject: Project | null): UseFileTreeDat
   }, []);
 
   useEffect(() => {
-    const projectName = selectedProject?.name;
+    // File-tree requests use the DB projectId; the backend resolves it to the
+    // project's absolute path through the projects table.
+    const projectId = selectedProject?.projectId;
 
-    if (!projectName) {
+    if (!projectId) {
       setFiles([]);
       setLoading(false);
       return;
@@ -42,7 +44,7 @@ export function useFileTreeData(selectedProject: Project | null): UseFileTreeDat
         setLoading(true);
       }
       try {
-        const response = await api.getFiles(projectName, { signal: abortControllerRef.current!.signal });
+        const response = await api.getFiles(projectId, { signal: abortControllerRef.current!.signal });
 
         if (!response.ok) {
           const errorText = await response.text();
@@ -79,7 +81,7 @@ export function useFileTreeData(selectedProject: Project | null): UseFileTreeDat
       isActive = false;
       abortControllerRef.current?.abort();
     };
-  }, [selectedProject?.name, refreshKey]);
+  }, [selectedProject?.projectId, refreshKey]);
 
   return {
     files,
diff --git a/src/components/file-tree/hooks/useFileTreeOperations.ts b/src/components/file-tree/hooks/useFileTreeOperations.ts
index 398fcbe5..559654c6 100644
--- a/src/components/file-tree/hooks/useFileTreeOperations.ts
+++ b/src/components/file-tree/hooks/useFileTreeOperations.ts
@@ -126,7 +126,7 @@ export function useFileTreeOperations({
 
     setOperationLoading(true);
     try {
-      const response = await api.renameFile(selectedProject.name, {
+      const response = await api.renameFile(selectedProject.projectId, {
         oldPath: renamingItem.path,
         newName: renameValue,
       });
@@ -161,7 +161,7 @@ export function useFileTreeOperations({
 
     setOperationLoading(true);
     try {
-      const response = await api.deleteFile(selectedProject.name, {
+      const response = await api.deleteFile(selectedProject.projectId, {
         path: item.path,
         type: item.type,
       });
@@ -212,7 +212,7 @@ export function useFileTreeOperations({
 
     setOperationLoading(true);
     try {
-      const response = await api.createFile(selectedProject.name, {
+      const response = await api.createFile(selectedProject.projectId, {
         path: newItemParent,
         type: newItemType,
         name: newItemName,
@@ -287,7 +287,7 @@ export function useFileTreeOperations({
     if (!selectedProject) return;
 
     // Use the binary streaming endpoint so downloads preserve raw bytes.
-    const response = await api.readFileBlob(selectedProject.name, item.path);
+    const response = await api.readFileBlob(selectedProject.projectId, item.path);
 
     if (!response.ok) {
       throw new Error('Failed to download file');
@@ -308,7 +308,7 @@ export function useFileTreeOperations({
       const fullPath = currentPath ? `${currentPath}/${node.name}` : node.name;
 
       if (node.type === 'file') {
-        const response = await api.readFileBlob(selectedProject.name, node.path);
+        const response = await api.readFileBlob(selectedProject.projectId, node.path);
         if (!response.ok) {
           throw new Error(`Failed to download "${node.name}" for ZIP export`);
         }
diff --git a/src/components/file-tree/hooks/useFileTreeUpload.ts b/src/components/file-tree/hooks/useFileTreeUpload.ts
index c512091a..6879e3ae 100644
--- a/src/components/file-tree/hooks/useFileTreeUpload.ts
+++ b/src/components/file-tree/hooks/useFileTreeUpload.ts
@@ -154,7 +154,8 @@ export const useFileTreeUpload = ({
       formData.append('relativePaths', JSON.stringify(relativePaths));
 
       const response = await api.post(
-        `/projects/${encodeURIComponent(selectedProject!.name)}/files/upload`,
+        // File upload endpoint is keyed by DB projectId post-migration.
+        `/projects/${encodeURIComponent(selectedProject!.projectId)}/files/upload`,
         formData
       );
 
diff --git a/src/components/file-tree/types/types.ts b/src/components/file-tree/types/types.ts
index fb2ac842..1cdb8194 100644
--- a/src/components/file-tree/types/types.ts
+++ b/src/components/file-tree/types/types.ts
@@ -19,7 +19,8 @@ export interface FileTreeImageSelection {
   name: string;
   path: string;
   projectPath?: string;
-  projectName: string;
+  // DB projectId; used by ImageViewer to build the raw content URL.
+  projectId: string;
 }
 
 export interface FileIconData {
diff --git a/src/components/file-tree/view/FileTree.tsx b/src/components/file-tree/view/FileTree.tsx
index e847613c..b42e1014 100644
--- a/src/components/file-tree/view/FileTree.tsx
+++ b/src/components/file-tree/view/FileTree.tsx
@@ -101,7 +101,9 @@ export default function FileTree({ selectedProject, onFileOpen }: FileTreeProps)
           name: item.name,
           path: item.path,
           projectPath: selectedProject.path,
-          projectName: selectedProject.name,
+          // Image URL uses the DB projectId so ImageViewer can hit the
+          // /api/projects/:projectId/files/content endpoint directly.
+          projectId: selectedProject.projectId,
         });
         return;
       }
diff --git a/src/components/file-tree/view/ImageViewer.tsx b/src/components/file-tree/view/ImageViewer.tsx
index 0d151090..771b1f01 100644
--- a/src/components/file-tree/view/ImageViewer.tsx
+++ b/src/components/file-tree/view/ImageViewer.tsx
@@ -10,7 +10,7 @@ type ImageViewerProps = {
 };
 
 export default function ImageViewer({ file, onClose }: ImageViewerProps) {
-  const imagePath = `/api/projects/${file.projectName}/files/content?path=${encodeURIComponent(file.path)}`;
+  const imagePath = `/api/projects/${file.projectId}/files/content?path=${encodeURIComponent(file.path)}`;
   const [imageUrl, setImageUrl] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [loading, setLoading] = useState(true);
diff --git a/src/components/git-panel/hooks/useGitPanelController.ts b/src/components/git-panel/hooks/useGitPanelController.ts
index cb34cf13..4ef54002 100644
--- a/src/components/git-panel/hooks/useGitPanelController.ts
+++ b/src/components/git-panel/hooks/useGitPanelController.ts
@@ -64,10 +64,12 @@ export function useGitPanelController({
   const [operationError, setOperationError] = useState<string | null>(null);
 
   const clearOperationError = useCallback(() => setOperationError(null), []);
-  const selectedProjectNameRef = useRef<string | null>(selectedProject?.name ?? null);
+  // Tracks the DB projectId so async requests can detect stale responses when
+  // the user switches projects mid-flight.
+  const selectedProjectIdRef = useRef<string | null>(selectedProject?.projectId ?? null);
 
   useEffect(() => {
-    selectedProjectNameRef.current = selectedProject?.name ?? null;
+    selectedProjectIdRef.current = selectedProject?.projectId ?? null;
   }, [selectedProject]);
 
   const provider = useSelectedProvider();
@@ -78,18 +80,19 @@ export function useGitPanelController({
         return;
       }
 
-      const projectName = selectedProject.name;
+      // Git endpoints receive the DB projectId via the `project` query param.
+      const projectId = selectedProject.projectId;
 
       try {
         const response = await fetchWithAuth(
-          `/api/git/diff?project=${encodeURIComponent(projectName)}&file=${encodeURIComponent(filePath)}`,
+          `/api/git/diff?project=${encodeURIComponent(projectId)}&file=${encodeURIComponent(filePath)}`,
           { signal },
         );
         const data = await readJson<GitDiffResponse>(response, signal);
 
         if (
           signal?.aborted ||
-          selectedProjectNameRef.current !== projectName
+          selectedProjectIdRef.current !== projectId
         ) {
           return;
         }
@@ -116,16 +119,17 @@ export function useGitPanelController({
       return;
     }
 
-    const projectName = selectedProject.name;
+    // `project` query param carries the DB projectId everywhere now.
+    const projectId = selectedProject.projectId;
 
     setIsLoading(true);
     try {
-      const response = await fetchWithAuth(`/api/git/status?project=${encodeURIComponent(projectName)}`, { signal });
+      const response = await fetchWithAuth(`/api/git/status?project=${encodeURIComponent(projectId)}`, { signal });
       const data = await readJson<GitStatusResponse>(response, signal);
 
       if (
         signal?.aborted ||
-        selectedProjectNameRef.current !== projectName
+        selectedProjectIdRef.current !== projectId
       ) {
         return;
       }
@@ -150,7 +154,7 @@ export function useGitPanelController({
       }
 
       if (
-        selectedProjectNameRef.current !== projectName
+        selectedProjectIdRef.current !== projectId
       ) {
         return;
       }
@@ -169,7 +173,7 @@ export function useGitPanelController({
     }
 
     try {
-      const response = await fetchWithAuth(`/api/git/branches?project=${encodeURIComponent(selectedProject.name)}`);
+      const response = await fetchWithAuth(`/api/git/branches?project=${encodeURIComponent(selectedProject.projectId)}`);
       const data = await readJson<GitBranchesResponse>(response);
 
       if (!data.error && data.branches) {
@@ -196,7 +200,7 @@ export function useGitPanelController({
     }
 
     try {
-      const response = await fetchWithAuth(`/api/git/remote-status?project=${encodeURIComponent(selectedProject.name)}`);
+      const response = await fetchWithAuth(`/api/git/remote-status?project=${encodeURIComponent(selectedProject.projectId)}`);
       const data = await readJson<GitRemoteStatus | GitApiErrorResponse>(response);
 
       if (!data.error) {
@@ -222,7 +226,7 @@ export function useGitPanelController({
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify({
-            project: selectedProject.name,
+            project: selectedProject.projectId,
             branch: branchName,
           }),
         });
@@ -257,7 +261,7 @@ export function useGitPanelController({
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify({
-            project: selectedProject.name,
+            project: selectedProject.projectId,
             branch: trimmedBranchName,
           }),
         });
@@ -290,7 +294,7 @@ export function useGitPanelController({
         const response = await fetchWithAuth('/api/git/delete-branch', {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ project: selectedProject.name, branch: branchName }),
+          body: JSON.stringify({ project: selectedProject.projectId, branch: branchName }),
         });
 
         const data = await readJson<GitOperationResponse>(response);
@@ -320,7 +324,7 @@ export function useGitPanelController({
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
-          project: selectedProject.name,
+          project: selectedProject.projectId,
         }),
       });
 
@@ -351,7 +355,7 @@ export function useGitPanelController({
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
-          project: selectedProject.name,
+          project: selectedProject.projectId,
         }),
       });
 
@@ -381,7 +385,7 @@ export function useGitPanelController({
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
-          project: selectedProject.name,
+          project: selectedProject.projectId,
         }),
       });
 
@@ -411,7 +415,7 @@ export function useGitPanelController({
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
-          project: selectedProject.name,
+          project: selectedProject.projectId,
           branch: currentBranch,
         }),
       });
@@ -442,7 +446,7 @@ export function useGitPanelController({
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify({
-            project: selectedProject.name,
+            project: selectedProject.projectId,
             file: filePath,
           }),
         });
@@ -472,7 +476,7 @@ export function useGitPanelController({
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify({
-            project: selectedProject.name,
+            project: selectedProject.projectId,
             file: filePath,
           }),
         });
@@ -498,7 +502,7 @@ export function useGitPanelController({
 
     try {
       const response = await fetchWithAuth(
-        `/api/git/commits?project=${encodeURIComponent(selectedProject.name)}&limit=${RECENT_COMMITS_LIMIT}`,
+        `/api/git/commits?project=${encodeURIComponent(selectedProject.projectId)}&limit=${RECENT_COMMITS_LIMIT}`,
       );
       const data = await readJson<GitCommitsResponse>(response);
 
@@ -518,7 +522,7 @@ export function useGitPanelController({
 
       try {
         const response = await fetchWithAuth(
-          `/api/git/commit-diff?project=${encodeURIComponent(selectedProject.name)}&commit=${commitHash}`,
+          `/api/git/commit-diff?project=${encodeURIComponent(selectedProject.projectId)}&commit=${commitHash}`,
         );
         const data = await readJson<GitDiffResponse>(response);
 
@@ -546,7 +550,7 @@ export function useGitPanelController({
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify({
-            project: selectedProject.name,
+            project: selectedProject.projectId,
             files,
             provider,
           }),
@@ -578,7 +582,7 @@ export function useGitPanelController({
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify({
-            project: selectedProject.name,
+            project: selectedProject.projectId,
             message,
             files,
           }),
@@ -612,7 +616,7 @@ export function useGitPanelController({
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
-          project: selectedProject.name,
+          project: selectedProject.projectId,
         }),
       });
 
@@ -645,7 +649,7 @@ export function useGitPanelController({
 
       try {
         const response = await fetchWithAuth(
-          `/api/git/file-with-diff?project=${encodeURIComponent(selectedProject.name)}&file=${encodeURIComponent(filePath)}`,
+          `/api/git/file-with-diff?project=${encodeURIComponent(selectedProject.projectId)}&file=${encodeURIComponent(filePath)}`,
         );
         const data = await readJson<GitFileWithDiffResponse>(response);
 
diff --git a/src/components/git-panel/hooks/useRevertLocalCommit.ts b/src/components/git-panel/hooks/useRevertLocalCommit.ts
index 3c3ea918..86929528 100644
--- a/src/components/git-panel/hooks/useRevertLocalCommit.ts
+++ b/src/components/git-panel/hooks/useRevertLocalCommit.ts
@@ -3,7 +3,9 @@ import { authenticatedFetch } from '../../../utils/api';
 import type { GitOperationResponse } from '../types/types';
 
 type UseRevertLocalCommitOptions = {
-  projectName: string | null;
+  // DB primary key for the project; forwarded to the git API via the
+  // `project` body param.
+  projectId: string | null;
   onSuccess?: () => void;
 };
 
@@ -11,11 +13,11 @@ async function readJson<T>(response: Response): Promise<T> {
   return (await response.json()) as T;
 }
 
-export function useRevertLocalCommit({ projectName, onSuccess }: UseRevertLocalCommitOptions) {
+export function useRevertLocalCommit({ projectId, onSuccess }: UseRevertLocalCommitOptions) {
   const [isRevertingLocalCommit, setIsRevertingLocalCommit] = useState(false);
 
   const revertLatestLocalCommit = useCallback(async () => {
-    if (!projectName) {
+    if (!projectId) {
       return;
     }
 
@@ -24,7 +26,7 @@ export function useRevertLocalCommit({ projectName, onSuccess }: UseRevertLocalC
       const response = await authenticatedFetch('/api/git/revert-local-commit', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ project: projectName }),
+        body: JSON.stringify({ project: projectId }),
       });
       const data = await readJson<GitOperationResponse>(response);
 
@@ -39,7 +41,7 @@ export function useRevertLocalCommit({ projectName, onSuccess }: UseRevertLocalC
     } finally {
       setIsRevertingLocalCommit(false);
     }
-  }, [onSuccess, projectName]);
+  }, [onSuccess, projectId]);
 
   return {
     isRevertingLocalCommit,
diff --git a/src/components/git-panel/view/GitPanel.tsx b/src/components/git-panel/view/GitPanel.tsx
index fc6438bd..de9891dd 100644
--- a/src/components/git-panel/view/GitPanel.tsx
+++ b/src/components/git-panel/view/GitPanel.tsx
@@ -58,7 +58,9 @@ export default function GitPanel({ selectedProject, isMobile = false, onFileOpen
   });
 
   const { isRevertingLocalCommit, revertLatestLocalCommit } = useRevertLocalCommit({
-    projectName: selectedProject?.name ?? null,
+    // `projectId` (DB primary key) is forwarded to the revert API which uses it
+    // as the `project` body param.
+    projectId: selectedProject?.projectId ?? null,
     onSuccess: refreshAll,
   });
 
diff --git a/src/components/llm-logo-provider/OpenCodeLogo.tsx b/src/components/llm-logo-provider/OpenCodeLogo.tsx
new file mode 100644
index 00000000..8e44a289
--- /dev/null
+++ b/src/components/llm-logo-provider/OpenCodeLogo.tsx
@@ -0,0 +1,25 @@
+type OpenCodeLogoProps = {
+  className?: string;
+};
+
+const OpenCodeLogo = ({ className = 'w-5 h-5' }: OpenCodeLogoProps) => (
+  <svg
+    viewBox="0 0 24 24"
+    role="img"
+    aria-label="OpenCode"
+    className={className}
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <rect x="2.5" y="2.5" width="19" height="19" rx="4" className="fill-foreground" />
+    <path
+      d="M8.1 8.1 4.9 12l3.2 3.9M15.9 8.1l3.2 3.9-3.2 3.9M13.2 6.9l-2.4 10.2"
+      className="stroke-background"
+      strokeWidth="1.9"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+);
+
+export default OpenCodeLogo;
diff --git a/src/components/llm-logo-provider/SessionProviderLogo.tsx b/src/components/llm-logo-provider/SessionProviderLogo.tsx
index 53c02291..e29ecd6d 100644
--- a/src/components/llm-logo-provider/SessionProviderLogo.tsx
+++ b/src/components/llm-logo-provider/SessionProviderLogo.tsx
@@ -3,6 +3,7 @@ import ClaudeLogo from './ClaudeLogo';
 import CodexLogo from './CodexLogo';
 import CursorLogo from './CursorLogo';
 import GeminiLogo from './GeminiLogo';
+import OpenCodeLogo from './OpenCodeLogo';
 
 type SessionProviderLogoProps = {
   provider?: LLMProvider | string | null;
@@ -25,5 +26,9 @@ export default function SessionProviderLogo({
     return <GeminiLogo className={className} />;
   }
 
+  if (provider === 'opencode') {
+    return <OpenCodeLogo className={className} />;
+  }
+
   return <ClaudeLogo className={className} />;
 }
diff --git a/src/components/main-content/types/types.ts b/src/components/main-content/types/types.ts
index d4e708df..68b03b29 100644
--- a/src/components/main-content/types/types.ts
+++ b/src/components/main-content/types/types.ts
@@ -1,5 +1,7 @@
 import type { Dispatch, SetStateAction } from 'react';
+
 import type { AppTab, Project, ProjectSession } from '../../../types/app';
+import type { SessionNavigationOptions } from '../../chat/types/types';
 
 export type SessionLifecycleHandler = (sessionId?: string | null) => void;
 
@@ -49,10 +51,10 @@ export type MainContentProps = {
   onSessionProcessing: SessionLifecycleHandler;
   onSessionNotProcessing: SessionLifecycleHandler;
   processingSessions: Set<string>;
-  onReplaceTemporarySession: SessionLifecycleHandler;
-  onNavigateToSession: (targetSessionId: string) => void;
+  onNavigateToSession: (targetSessionId: string, options?: SessionNavigationOptions) => void;
   onShowSettings: () => void;
   externalMessageUpdate: number;
+  newSessionTrigger: number;
 };
 
 export type MainContentHeaderProps = {
diff --git a/src/components/main-content/view/MainContent.tsx b/src/components/main-content/view/MainContent.tsx
index 89197150..f0a29a70 100644
--- a/src/components/main-content/view/MainContent.tsx
+++ b/src/components/main-content/view/MainContent.tsx
@@ -1,4 +1,5 @@
 import React, { useEffect } from 'react';
+
 import ChatInterface from '../../chat/view/ChatInterface';
 import FileTree from '../../file-tree/view/FileTree';
 import StandaloneShell from '../../standalone-shell/view/StandaloneShell';
@@ -6,12 +7,14 @@ import GitPanel from '../../git-panel/view/GitPanel';
 import PluginTabContent from '../../plugins/view/PluginTabContent';
 import type { MainContentProps } from '../types/types';
 import { useTaskMaster } from '../../../contexts/TaskMasterContext';
+import { usePaletteOpsRegister } from '../../../contexts/PaletteOpsContext';
 import { useTasksSettings } from '../../../contexts/TasksSettingsContext';
 import { useUiPreferences } from '../../../hooks/useUiPreferences';
 import { useEditorSidebar } from '../../code-editor/hooks/useEditorSidebar';
 import EditorSidebar from '../../code-editor/view/EditorSidebar';
 import type { Project } from '../../../types/app';
 import { TaskMasterPanel } from '../../task-master';
+
 import MainContentHeader from './subcomponents/MainContentHeader';
 import MainContentStateView from './subcomponents/MainContentStateView';
 import ErrorBoundary from './ErrorBoundary';
@@ -44,10 +47,10 @@ function MainContent({
   onSessionProcessing,
   onSessionNotProcessing,
   processingSessions,
-  onReplaceTemporarySession,
   onNavigateToSession,
   onShowSettings,
   externalMessageUpdate,
+  newSessionTrigger,
 }: MainContentProps) {
   const { preferences } = useUiPreferences();
   const { autoExpandTools, showRawParameters, showThinking, autoScrollToBottom, sendByCtrlEnter } = preferences;
@@ -73,13 +76,15 @@ function MainContent({
   });
 
   useEffect(() => {
-    const selectedProjectName = selectedProject?.name;
-    const currentProjectName = currentProject?.name;
+    // Identify projects by DB `projectId`; the TaskMaster context uses the
+    // same identifier to key its internal maps.
+    const selectedProjectId = selectedProject?.projectId;
+    const currentProjectId = currentProject?.projectId;
 
-    if (selectedProject && selectedProjectName !== currentProjectName) {
+    if (selectedProject && selectedProjectId !== currentProjectId) {
       setCurrentProject?.(selectedProject);
     }
-  }, [selectedProject, currentProject?.name, setCurrentProject]);
+  }, [selectedProject, currentProject?.projectId, setCurrentProject]);
 
   useEffect(() => {
     if (!shouldShowTasksTab && activeTab === 'tasks') {
@@ -87,6 +92,13 @@ function MainContent({
     }
   }, [shouldShowTasksTab, activeTab, setActiveTab]);
 
+  usePaletteOpsRegister({
+    openFile: (filePath: string) => {
+      setActiveTab('files');
+      handleFileOpen(filePath);
+    },
+  });
+
   if (isLoading) {
     return <MainContentStateView mode="loading" isMobile={isMobile} onMenuClick={onMenuClick} />;
   }
@@ -124,7 +136,6 @@ function MainContent({
                 onSessionProcessing={onSessionProcessing}
                 onSessionNotProcessing={onSessionNotProcessing}
                 processingSessions={processingSessions}
-                onReplaceTemporarySession={onReplaceTemporarySession}
                 onNavigateToSession={onNavigateToSession}
                 onShowSettings={onShowSettings}
                 autoExpandTools={autoExpandTools}
@@ -133,6 +144,7 @@ function MainContent({
                 autoScrollToBottom={autoScrollToBottom}
                 sendByCtrlEnter={sendByCtrlEnter}
                 externalMessageUpdate={externalMessageUpdate}
+                newSessionTrigger={newSessionTrigger}
                 onShowAllTasks={tasksEnabled ? () => setActiveTab('tasks') : null}
               />
             </ErrorBoundary>
diff --git a/src/components/mcp/constants.ts b/src/components/mcp/constants.ts
index 4b1a949c..ab6396ff 100644
--- a/src/components/mcp/constants.ts
+++ b/src/components/mcp/constants.ts
@@ -5,6 +5,7 @@ export const MCP_PROVIDER_NAMES: Record<McpProvider, string> = {
   cursor: 'Cursor',
   codex: 'Codex',
   gemini: 'Gemini',
+  opencode: 'OpenCode',
 };
 
 export const MCP_SUPPORTED_SCOPES: Record<McpProvider, McpScope[]> = {
@@ -12,6 +13,7 @@ export const MCP_SUPPORTED_SCOPES: Record<McpProvider, McpScope[]> = {
   cursor: ['user', 'project'],
   codex: ['user', 'project'],
   gemini: ['user', 'project'],
+  opencode: ['user', 'project'],
 };
 
 export const MCP_SUPPORTED_TRANSPORTS: Record<McpProvider, McpTransport[]> = {
@@ -19,6 +21,7 @@ export const MCP_SUPPORTED_TRANSPORTS: Record<McpProvider, McpTransport[]> = {
   cursor: ['stdio', 'http'],
   codex: ['stdio', 'http'],
   gemini: ['stdio', 'http', 'sse'],
+  opencode: ['stdio', 'http'],
 };
 
 export const MCP_GLOBAL_SUPPORTED_SCOPES: McpScope[] = ['user', 'project'];
@@ -30,6 +33,7 @@ export const MCP_PROVIDER_BUTTON_CLASSES: Record<McpProvider, string> = {
   cursor: 'bg-purple-600 text-white hover:bg-purple-700',
   codex: 'bg-gray-800 text-white hover:bg-gray-900 dark:bg-gray-700 dark:hover:bg-gray-600',
   gemini: 'bg-blue-600 text-white hover:bg-blue-700',
+  opencode: 'bg-zinc-900 text-white hover:bg-zinc-800 dark:bg-zinc-700 dark:hover:bg-zinc-600',
 };
 
 export const MCP_SUPPORTS_WORKING_DIRECTORY: Record<McpProvider, boolean> = {
@@ -37,6 +41,7 @@ export const MCP_SUPPORTS_WORKING_DIRECTORY: Record<McpProvider, boolean> = {
   cursor: false,
   codex: true,
   gemini: true,
+  opencode: false,
 };
 
 export const DEFAULT_MCP_FORM: McpFormState = {
diff --git a/src/components/mcp/hooks/useMcpServerForm.ts b/src/components/mcp/hooks/useMcpServerForm.ts
index 52809cbe..f38ef83e 100644
--- a/src/components/mcp/hooks/useMcpServerForm.ts
+++ b/src/components/mcp/hooks/useMcpServerForm.ts
@@ -128,7 +128,8 @@ export function useMcpServerForm({
     currentProjects
       .map((project) => ({
         value: getProjectPath(project),
-        label: project.displayName || project.name,
+        // Fall back to projectId (DB primary key) when no display name is set.
+        label: project.displayName || project.projectId,
       }))
       .filter((project) => project.value)
   ), [currentProjects]);
diff --git a/src/components/mcp/hooks/useMcpServers.ts b/src/components/mcp/hooks/useMcpServers.ts
index 57ed81cc..e9cb2d3c 100644
--- a/src/components/mcp/hooks/useMcpServers.ts
+++ b/src/components/mcp/hooks/useMcpServers.ts
@@ -31,6 +31,8 @@ type GlobalMcpServerResponse = {
   results: GlobalMcpServerResult[];
 };
 
+// Internal MCP-side shape; `name` is now filled from the DB projectId since
+// the legacy Project.name field was removed during the projectId migration.
 type ProjectTarget = {
   name: string;
   displayName: string;
@@ -111,6 +113,9 @@ const normalizeServer = (
     bearerTokenEnvVar: server.bearerTokenEnvVar,
     envHttpHeaders: server.envHttpHeaders ?? {},
     workspacePath: project?.path || server.workspacePath,
+    // Keep the `projectName` key in the MCP wire payload for backwards
+    // compatibility. ProjectTarget.name is populated from the DB `projectId`
+    // (see createProjectTargets) so this still carries the new identifier.
     projectName: project?.name || server.projectName,
     projectDisplayName: project?.displayName || server.projectDisplayName,
   };
@@ -126,8 +131,9 @@ const createProjectTargets = (projects: McpProject[]): ProjectTarget[] => {
 
     seen.add(projectPath);
     acc.push({
-      name: project.name,
-      displayName: project.displayName || project.name,
+      // Use projectId as the stable internal identifier.
+      name: project.projectId,
+      displayName: project.displayName || project.projectId,
       path: projectPath,
     });
     return acc;
diff --git a/src/components/mcp/types.ts b/src/components/mcp/types.ts
index 810258e9..2e3b618d 100644
--- a/src/components/mcp/types.ts
+++ b/src/components/mcp/types.ts
@@ -7,8 +7,10 @@ export type McpImportMode = 'form' | 'json';
 export type McpFormMode = 'provider' | 'global';
 export type KeyValueMap = Record<string, string>;
 
+// Internal MCP shape; `projectId` replaces the legacy `name` field from the
+// projectName → projectId migration.
 export type McpProject = {
-  name: string;
+  projectId: string;
   displayName?: string;
   fullPath?: string;
   path?: string;
diff --git a/src/components/onboarding/view/subcomponents/AgentConnectionsStep.tsx b/src/components/onboarding/view/subcomponents/AgentConnectionsStep.tsx
index 3dfb25a9..5c66997a 100644
--- a/src/components/onboarding/view/subcomponents/AgentConnectionsStep.tsx
+++ b/src/components/onboarding/view/subcomponents/AgentConnectionsStep.tsx
@@ -1,5 +1,6 @@
 import type { LLMProvider } from '../../../../types/app';
 import type { ProviderAuthStatusMap } from '../../../provider-auth/types';
+
 import AgentConnectionCard from './AgentConnectionCard';
 
 type AgentConnectionsStepProps = {
@@ -36,6 +37,13 @@ const providerCards = [
     iconContainerClassName: 'bg-teal-100 dark:bg-teal-900/30',
     loginButtonClassName: 'bg-teal-600 hover:bg-teal-700',
   },
+  {
+    provider: 'opencode' as const,
+    title: 'OpenCode',
+    connectedClassName: 'bg-zinc-100 dark:bg-zinc-800/50 border-zinc-300 dark:border-zinc-600',
+    iconContainerClassName: 'bg-zinc-100 dark:bg-zinc-800',
+    loginButtonClassName: 'bg-zinc-800 hover:bg-zinc-900 dark:bg-zinc-700 dark:hover:bg-zinc-600',
+  },
 ];
 
 export default function AgentConnectionsStep({
diff --git a/src/components/plugins/view/PluginSettingsTab.tsx b/src/components/plugins/view/PluginSettingsTab.tsx
index a411b94c..72de671b 100644
--- a/src/components/plugins/view/PluginSettingsTab.tsx
+++ b/src/components/plugins/view/PluginSettingsTab.tsx
@@ -1,12 +1,93 @@
-import { useState } from 'react';
+import { useState, type ReactNode } from 'react';
 import { useTranslation } from 'react-i18next';
-import { Trash2, RefreshCw, GitBranch, Loader2, ServerCrash, ShieldAlert, ExternalLink, BookOpen, Download, BarChart3 } from 'lucide-react';
+import {
+  Activity,
+  BarChart3,
+  BookOpen,
+  Clock,
+  Download,
+  ExternalLink,
+  GitBranch,
+  Loader2,
+  RefreshCw,
+  ServerCrash,
+  ShieldAlert,
+  Terminal,
+  Trash2,
+  type LucideIcon,
+} from 'lucide-react';
+
 import { usePlugins } from '../../../contexts/PluginsContext';
 import type { Plugin } from '../../../contexts/PluginsContext';
+
 import PluginIcon from './PluginIcon';
 
 const STARTER_PLUGIN_URL = 'https://github.com/cloudcli-ai/cloudcli-plugin-starter';
 const TERMINAL_PLUGIN_URL = 'https://github.com/cloudcli-ai/cloudcli-plugin-terminal';
+const SCHEDULED_PROMPT_PLUGIN_URL = 'https://github.com/grostim/cloudcli-cron';
+const CLAUDE_WATCH_PLUGIN_URL = 'https://github.com/satsuki19980613/cloudcli-claude-watch';
+
+type PluginRecommendation = {
+  id: string;
+  translationKey: string;
+  repoUrl: string;
+  installedNames: string[];
+  icon: LucideIcon;
+  source: 'official' | 'unofficial';
+};
+
+const OFFICIAL_PLUGIN_RECOMMENDATIONS: PluginRecommendation[] = [
+  {
+    id: 'project-stats',
+    translationKey: 'starterPlugin',
+    repoUrl: STARTER_PLUGIN_URL,
+    installedNames: ['project-stats'],
+    icon: BarChart3,
+    source: 'official',
+  },
+  {
+    id: 'web-terminal',
+    translationKey: 'terminalPlugin',
+    repoUrl: TERMINAL_PLUGIN_URL,
+    installedNames: ['web-terminal'],
+    icon: Terminal,
+    source: 'official',
+  },
+];
+
+const UNOFFICIAL_PLUGIN_RECOMMENDATIONS: PluginRecommendation[] = [
+  {
+    id: 'cloudcli-claude-watch',
+    translationKey: 'claudeWatchPlugin',
+    repoUrl: CLAUDE_WATCH_PLUGIN_URL,
+    installedNames: ['cloudcli-claude-watch'],
+    icon: Activity,
+    source: 'unofficial',
+  },
+  {
+    id: 'workspace-scheduled-prompts',
+    translationKey: 'scheduledPromptPlugin',
+    repoUrl: SCHEDULED_PROMPT_PLUGIN_URL,
+    installedNames: ['workspace-scheduled-prompts'],
+    icon: Clock,
+    source: 'unofficial',
+  },
+];
+
+function repoSlug(repoUrl: string) {
+  return repoUrl.replace(/^https?:\/\/(www\.)?github\.com\//, '');
+}
+
+function normalizeRepoUrl(repoUrl: string | null) {
+  return repoUrl?.replace(/\.git$/, '').replace(/\/$/, '').toLowerCase() ?? null;
+}
+
+function pluginMatchesRecommendation(plugin: Plugin, recommendation: PluginRecommendation) {
+  return (
+    recommendation.installedNames.includes(plugin.name)
+    || normalizeRepoUrl(plugin.repoUrl) === normalizeRepoUrl(recommendation.repoUrl)
+  );
+}
 
 /* ─── Toggle Switch ─────────────────────────────────────────────────────── */
 function ToggleSwitch({ checked, onChange, ariaLabel }: { checked: boolean; onChange: (v: boolean) => void; ariaLabel: string }) {
@@ -208,117 +289,95 @@ function PluginCard({
   );
 }
 
-/* ─── Starter Plugin Card ───────────────────────────────────────────────── */
-function StarterPluginCard({ onInstall, installing }: { onInstall: () => void; installing: boolean }) {
-  const { t } = useTranslation('settings');
-
+/* ─── Recommendation Section ────────────────────────────────────────────── */
+function RecommendationSection({
+  title,
+  description,
+  children,
+}: {
+  title: string;
+  description: string;
+  children: ReactNode;
+}) {
   return (
-    <div className="relative flex overflow-hidden rounded-lg border border-dashed border-border bg-card transition-all duration-200 hover:border-blue-400 dark:hover:border-blue-500">
-      <div className="w-[3px] flex-shrink-0 bg-blue-500/30" />
-      <div className="min-w-0 flex-1 p-4">
-        <div className="flex items-start justify-between gap-3">
-          <div className="flex min-w-0 items-center gap-2.5">
-            <div className="h-5 w-5 flex-shrink-0 text-blue-500">
-              <BarChart3 className="h-5 w-5" />
-            </div>
-            <div className="min-w-0">
-              <div className="flex flex-wrap items-center gap-2">
-                <span className="text-sm font-semibold leading-none text-foreground">
-                  {t('pluginSettings.starterPlugin.name')}
-                </span>
-                <span className="rounded bg-blue-50 px-1.5 py-0.5 text-[10px] font-medium text-blue-600 dark:bg-blue-950/50 dark:text-blue-400">
-                  {t('pluginSettings.starterPlugin.badge')}
-                </span>
-                <span className="rounded bg-muted px-1.5 py-0.5 text-[10px] text-muted-foreground">
-                  {t('pluginSettings.tab')}
-                </span>
-              </div>
-              <p className="mt-1 text-sm leading-snug text-muted-foreground">
-                {t('pluginSettings.starterPlugin.description')}
-              </p>
-              <a
-                href={STARTER_PLUGIN_URL}
-                target="_blank"
-                rel="noopener noreferrer"
-                className="mt-1 inline-flex items-center gap-1 text-xs text-muted-foreground/60 transition-colors hover:text-foreground"
-              >
-                <GitBranch className="h-3 w-3" />
-                cloudcli-ai/cloudcli-plugin-starter
-              </a>
-            </div>
-          </div>
-          <button
-            onClick={onInstall}
-            disabled={installing}
-            className="flex flex-shrink-0 items-center gap-1.5 rounded-md bg-blue-600 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-blue-700 disabled:opacity-50"
-          >
-            {installing ? (
-              <Loader2 className="h-3.5 w-3.5 animate-spin" />
-            ) : (
-              <Download className="h-3.5 w-3.5" />
-            )}
-            {installing ? t('pluginSettings.installing') : t('pluginSettings.starterPlugin.install')}
-          </button>
-        </div>
+    <section className="space-y-2">
+      <div>
+        <h4 className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+          {title}
+        </h4>
+        <p className="mt-0.5 text-xs text-muted-foreground/70">
+          {description}
+        </p>
       </div>
-    </div>
+      <div className="space-y-2">
+        {children}
+      </div>
+    </section>
   );
 }
 
-/* ─── Terminal Plugin Card ──────────────────────────────────────────────── */
-function TerminalPluginCard({ onInstall, installing }: { onInstall: () => void; installing: boolean }) {
+/* ─── Plugin Recommendation Card ────────────────────────────────────────── */
+function PluginRecommendationCard({
+  recommendation,
+  onInstall,
+  disabled,
+  installing,
+}: {
+  recommendation: PluginRecommendation;
+  onInstall: () => void;
+  disabled: boolean;
+  installing: boolean;
+}) {
   const { t } = useTranslation('settings');
+  const Icon = recommendation.icon;
+  const isOfficial = recommendation.source === 'official';
+  const accentClass = isOfficial ? 'bg-blue-500/30' : 'bg-amber-500/40';
+  const hoverClass = isOfficial ? 'hover:border-blue-400 dark:hover:border-blue-500' : 'hover:border-amber-400 dark:hover:border-amber-500';
+  const iconClass = isOfficial ? 'text-blue-500' : 'text-amber-500';
 
   return (
-    <div className="relative flex overflow-hidden rounded-lg border border-dashed border-border bg-card transition-all duration-200 hover:border-blue-400 dark:hover:border-blue-500">
-      <div className="w-[3px] flex-shrink-0 bg-blue-500/30" />
+    <div className={`relative flex overflow-hidden rounded-lg border border-dashed border-border bg-card transition-all duration-200 ${hoverClass}`}>
+      <div className={`w-[3px] flex-shrink-0 ${accentClass}`} />
       <div className="min-w-0 flex-1 p-4">
         <div className="flex items-start justify-between gap-3">
           <div className="flex min-w-0 items-center gap-2.5">
-            <div className="h-5 w-5 flex-shrink-0 text-blue-500">
-              <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className="h-5 w-5">
-                <rect x="3" y="3" width="18" height="18" rx="2"/>
-                <path d="M7 8l4 4-4 4"/>
-                <line x1="13" y1="16" x2="17" y2="16"/>
-              </svg>
+            <div className={`h-5 w-5 flex-shrink-0 ${iconClass}`}>
+              <Icon className="h-5 w-5" />
             </div>
             <div className="min-w-0">
               <div className="flex flex-wrap items-center gap-2">
                 <span className="text-sm font-semibold leading-none text-foreground">
-                  {t('pluginSettings.terminalPlugin.name')}
-                </span>
-                <span className="rounded bg-blue-50 px-1.5 py-0.5 text-[10px] font-medium text-blue-600 dark:bg-blue-950/50 dark:text-blue-400">
-                  {t('pluginSettings.terminalPlugin.badge')}
+                  {t(`pluginSettings.${recommendation.translationKey}.name`)}
                 </span>
                 <span className="rounded bg-muted px-1.5 py-0.5 text-[10px] text-muted-foreground">
                   {t('pluginSettings.tab')}
                 </span>
               </div>
               <p className="mt-1 text-sm leading-snug text-muted-foreground">
-                {t('pluginSettings.terminalPlugin.description')}
+                {t(`pluginSettings.${recommendation.translationKey}.description`)}
               </p>
               <a
-                href={TERMINAL_PLUGIN_URL}
+                href={recommendation.repoUrl}
                 target="_blank"
                 rel="noopener noreferrer"
                 className="mt-1 inline-flex items-center gap-1 text-xs text-muted-foreground/60 transition-colors hover:text-foreground"
               >
                 <GitBranch className="h-3 w-3" />
-                cloudcli-ai/cloudcli-plugin-terminal
+                {repoSlug(recommendation.repoUrl)}
               </a>
             </div>
           </div>
           <button
             onClick={onInstall}
-            disabled={installing}
-            className="flex flex-shrink-0 items-center gap-1.5 rounded-md bg-blue-600 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-blue-700 disabled:opacity-50"
+            disabled={disabled}
+            className="flex flex-shrink-0 items-center gap-1.5 rounded-md bg-foreground px-4 py-2 text-sm font-medium text-background transition-opacity hover:opacity-90 disabled:opacity-50"
           >
             {installing ? (
               <Loader2 className="h-3.5 w-3.5 animate-spin" />
             ) : (
               <Download className="h-3.5 w-3.5" />
             )}
-            {installing ? t('pluginSettings.installing') : t('pluginSettings.terminalPlugin.install')}
+            {installing ? t('pluginSettings.installing') : t(`pluginSettings.${recommendation.translationKey}.install`)}
           </button>
         </div>
       </div>
@@ -334,8 +393,7 @@ export default function PluginSettingsTab() {
 
   const [gitUrl, setGitUrl] = useState('');
   const [installing, setInstalling] = useState(false);
-  const [installingStarter, setInstallingStarter] = useState(false);
-  const [installingTerminal, setInstallingTerminal] = useState(false);
+  const [installingRecommendation, setInstallingRecommendation] = useState<string | null>(null);
   const [installError, setInstallError] = useState<string | null>(null);
   const [confirmUninstall, setConfirmUninstall] = useState<string | null>(null);
   const [updatingPlugins, setUpdatingPlugins] = useState<Set<string>>(new Set());
@@ -364,24 +422,18 @@ export default function PluginSettingsTab() {
     setInstalling(false);
   };
 
-  const handleInstallStarter = async () => {
-    setInstallingStarter(true);
+  const handleInstallRecommendation = async (recommendation: PluginRecommendation) => {
+    if (installingRecommendation) return;
+    setInstallingRecommendation(recommendation.id);
     setInstallError(null);
-    const result = await installPlugin(STARTER_PLUGIN_URL);
-    if (!result.success) {
-      setInstallError(result.error || t('pluginSettings.installFailed'));
+    try {
+      const result = await installPlugin(recommendation.repoUrl);
+      if (!result.success) {
+        setInstallError(result.error || t('pluginSettings.installFailed'));
+      }
+    } finally {
+      setInstallingRecommendation(null);
     }
-    setInstallingStarter(false);
-  };
-
-  const handleInstallTerminal = async () => {
-    setInstallingTerminal(true);
-    setInstallError(null);
-    const result = await installPlugin(TERMINAL_PLUGIN_URL);
-    if (!result.success) {
-      setInstallError(result.error || t('pluginSettings.installFailed'));
-    }
-    setInstallingTerminal(false);
   };
 
   const handleUninstall = async (name: string) => {
@@ -398,8 +450,50 @@ export default function PluginSettingsTab() {
     }
   };
 
-  const hasStarterInstalled = plugins.some((p) => p.name === 'project-stats');
-  const hasTerminalInstalled = plugins.some((p) => p.name === 'web-terminal');
+  const isRecommendationInstalled = (recommendation: PluginRecommendation) => {
+    return plugins.some((plugin) => pluginMatchesRecommendation(plugin, recommendation));
+  };
+
+  const isOfficialPlugin = (plugin: Plugin) => {
+    return OFFICIAL_PLUGIN_RECOMMENDATIONS.some((recommendation) => (
+      pluginMatchesRecommendation(plugin, recommendation)
+    ));
+  };
+
+  const officialPlugins = plugins.filter(isOfficialPlugin);
+  const otherPlugins = plugins.filter((plugin) => !isOfficialPlugin(plugin));
+  const officialRecommendations = OFFICIAL_PLUGIN_RECOMMENDATIONS.filter(
+    (recommendation) => !isRecommendationInstalled(recommendation),
+  );
+  const unofficialRecommendations = UNOFFICIAL_PLUGIN_RECOMMENDATIONS.filter(
+    (recommendation) => !isRecommendationInstalled(recommendation),
+  );
+  const hasOfficialSection = officialPlugins.length > 0 || officialRecommendations.length > 0;
+  const hasOtherSection = otherPlugins.length > 0 || unofficialRecommendations.length > 0;
+
+  const renderPluginCard = (plugin: Plugin, index: number) => {
+    const handleToggle = async (enabled: boolean) => {
+      const r = await togglePlugin(plugin.name, enabled);
+      if (!r.success) {
+        setInstallError(r.error || t('pluginSettings.toggleFailed'));
+      }
+    };
+
+    return (
+      <PluginCard
+        key={plugin.name}
+        plugin={plugin}
+        index={index}
+        onToggle={(enabled) => void handleToggle(enabled)}
+        onUpdate={() => void handleUpdate(plugin.name)}
+        onUninstall={() => void handleUninstall(plugin.name)}
+        updating={updatingPlugins.has(plugin.name)}
+        confirmingUninstall={confirmUninstall === plugin.name}
+        onCancelUninstall={() => setConfirmUninstall(null)}
+        updateError={updateErrors[plugin.name] ?? null}
+      />
+    );
+  };
 
   return (
     <div className="space-y-6">
@@ -456,51 +550,49 @@ export default function PluginSettingsTab() {
         </span>
       </p>
 
-      {/* Official plugin suggestions — above the list */}
-      {!loading && (!hasStarterInstalled || !hasTerminalInstalled) && (
-        <div className="space-y-2">
-          {!hasStarterInstalled && (
-            <StarterPluginCard onInstall={handleInstallStarter} installing={installingStarter} />
-          )}
-          {!hasTerminalInstalled && (
-            <TerminalPluginCard onInstall={handleInstallTerminal} installing={installingTerminal} />
-          )}
-        </div>
-      )}
-
-      {/* Plugin List */}
+      {/* Plugin sections */}
       {loading ? (
         <div className="flex items-center justify-center gap-2 py-10 text-sm text-muted-foreground">
           <Loader2 className="h-4 w-4 animate-spin" />
           {t('pluginSettings.scanningPlugins')}
         </div>
-      ) : plugins.length === 0 ? (
-        <p className="py-8 text-center text-sm text-muted-foreground">{t('pluginSettings.noPluginsInstalled')}</p>
       ) : (
-        <div className="space-y-2">
-          {plugins.map((plugin, index) => {
-            const handleToggle = async (enabled: boolean) => {
-              const r = await togglePlugin(plugin.name, enabled);
-              if (!r.success) {
-                setInstallError(r.error || t('pluginSettings.toggleFailed'));
-              }
-            };
+        <div className="space-y-4">
+          {hasOfficialSection && (
+            <RecommendationSection
+              title={t('pluginSettings.sections.officialTitle')}
+              description={t('pluginSettings.sections.officialDescription')}
+            >
+              {officialPlugins.map((plugin, index) => renderPluginCard(plugin, index))}
+              {officialRecommendations.map((recommendation) => (
+                <PluginRecommendationCard
+                  key={recommendation.id}
+                  recommendation={recommendation}
+                  onInstall={() => void handleInstallRecommendation(recommendation)}
+                  disabled={!!installingRecommendation}
+                  installing={installingRecommendation === recommendation.id}
+                />
+              ))}
+            </RecommendationSection>
+          )}
 
-            return (
-              <PluginCard
-                key={plugin.name}
-                plugin={plugin}
-                index={index}
-                onToggle={(enabled) => void handleToggle(enabled)}
-                onUpdate={() => void handleUpdate(plugin.name)}
-                onUninstall={() => void handleUninstall(plugin.name)}
-                updating={updatingPlugins.has(plugin.name)}
-                confirmingUninstall={confirmUninstall === plugin.name}
-                onCancelUninstall={() => setConfirmUninstall(null)}
-                updateError={updateErrors[plugin.name] ?? null}
-              />
-            );
-          })}
+          {hasOtherSection && (
+            <RecommendationSection
+              title={t('pluginSettings.sections.unofficialTitle')}
+              description={t('pluginSettings.sections.unofficialDescription')}
+            >
+              {otherPlugins.map((plugin, index) => renderPluginCard(plugin, officialPlugins.length + index))}
+              {unofficialRecommendations.map((recommendation) => (
+                <PluginRecommendationCard
+                  key={recommendation.id}
+                  recommendation={recommendation}
+                  onInstall={() => void handleInstallRecommendation(recommendation)}
+                  disabled={!!installingRecommendation}
+                  installing={installingRecommendation === recommendation.id}
+                />
+              ))}
+            </RecommendationSection>
+          )}
         </div>
       )}
 
diff --git a/src/components/plugins/view/PluginTabContent.tsx b/src/components/plugins/view/PluginTabContent.tsx
index f3340738..7e7f8db5 100644
--- a/src/components/plugins/view/PluginTabContent.tsx
+++ b/src/components/plugins/view/PluginTabContent.tsx
@@ -12,6 +12,9 @@ type PluginTabContentProps = {
 
 type PluginContext = {
   theme: 'dark' | 'light';
+  // Plugin contract historically used `name` for the project identifier; we
+  // keep that key and populate it from the DB `projectId` so external plugins
+  // continue to receive a stable opaque id.
   project: { name: string; path: string } | null;
   session: { id: string; title: string } | null;
 };
@@ -25,7 +28,7 @@ function buildContext(
     theme: isDarkMode ? 'dark' : 'light',
     project: selectedProject
       ? {
-        name: selectedProject.name,
+        name: selectedProject.projectId,
         path: selectedProject.fullPath || selectedProject.path || '',
       }
       : null,
diff --git a/src/components/prd-editor/PRDEditor.tsx b/src/components/prd-editor/PRDEditor.tsx
index 3ad89d63..5cf23e77 100644
--- a/src/components/prd-editor/PRDEditor.tsx
+++ b/src/components/prd-editor/PRDEditor.tsx
@@ -39,14 +39,16 @@ export default function PRDEditor({
     projectPath,
   });
 
+  // PRD hooks are now addressed by DB `projectId`; the backend resolves the
+  // `.taskmaster/docs` folder from the `projects` table.
   const { existingPrds, refreshExistingPrds } = usePrdRegistry({
-    projectName: project?.name,
+    projectId: project?.projectId,
   });
 
   const isExistingFile = useMemo(() => !isNewFile || Boolean(file?.isExisting), [file?.isExisting, isNewFile]);
 
   const { savePrd, saving, saveSuccess } = usePrdSave({
-    projectName: project?.name,
+    projectId: project?.projectId,
     existingPrds,
     isExistingFile,
     onAfterSave: async () => {
diff --git a/src/components/prd-editor/hooks/usePrdDocument.ts b/src/components/prd-editor/hooks/usePrdDocument.ts
index 3728caf4..9d817d16 100644
--- a/src/components/prd-editor/hooks/usePrdDocument.ts
+++ b/src/components/prd-editor/hooks/usePrdDocument.ts
@@ -73,7 +73,7 @@ export function usePrdDocument({
         return;
       }
 
-      if (!file?.projectName || !file?.path) {
+      if (!file?.projectId || !file?.path) {
         if (!isMounted) {
           return;
         }
@@ -87,7 +87,8 @@ export function usePrdDocument({
       try {
         setLoading(true);
 
-        const response = await api.readFile(file.projectName, file.path);
+        // readFile uses the DB projectId to resolve the project's path server-side.
+        const response = await api.readFile(file.projectId, file.path);
         if (!response.ok) {
           throw new Error(`Failed to load file: ${response.status} ${response.statusText}`);
         }
diff --git a/src/components/prd-editor/hooks/usePrdRegistry.ts b/src/components/prd-editor/hooks/usePrdRegistry.ts
index f7a40856..f28b1665 100644
--- a/src/components/prd-editor/hooks/usePrdRegistry.ts
+++ b/src/components/prd-editor/hooks/usePrdRegistry.ts
@@ -3,7 +3,8 @@ import { api } from '../../../utils/api';
 import type { ExistingPrdFile, PrdListResponse } from '../types';
 
 type UsePrdRegistryArgs = {
-  projectName?: string;
+  // DB primary key of the project (post migration).
+  projectId?: string;
 };
 
 type UsePrdRegistryResult = {
@@ -15,17 +16,17 @@ function getPrdFiles(data: PrdListResponse): ExistingPrdFile[] {
   return data.prdFiles || data.prds || [];
 }
 
-export function usePrdRegistry({ projectName }: UsePrdRegistryArgs): UsePrdRegistryResult {
+export function usePrdRegistry({ projectId }: UsePrdRegistryArgs): UsePrdRegistryResult {
   const [existingPrds, setExistingPrds] = useState<ExistingPrdFile[]>([]);
 
   const refreshExistingPrds = useCallback(async () => {
-    if (!projectName) {
+    if (!projectId) {
       setExistingPrds([]);
       return;
     }
 
     try {
-      const response = await api.get(`/taskmaster/prd/${encodeURIComponent(projectName)}`);
+      const response = await api.get(`/taskmaster/prd/${encodeURIComponent(projectId)}`);
       if (!response.ok) {
         setExistingPrds([]);
         return;
@@ -37,7 +38,7 @@ export function usePrdRegistry({ projectName }: UsePrdRegistryArgs): UsePrdRegis
       console.error('Failed to fetch existing PRDs:', error);
       setExistingPrds([]);
     }
-  }, [projectName]);
+  }, [projectId]);
 
   useEffect(() => {
     void refreshExistingPrds();
diff --git a/src/components/prd-editor/hooks/usePrdSave.ts b/src/components/prd-editor/hooks/usePrdSave.ts
index 1d802ad5..b216f6cb 100644
--- a/src/components/prd-editor/hooks/usePrdSave.ts
+++ b/src/components/prd-editor/hooks/usePrdSave.ts
@@ -4,7 +4,8 @@ import type { ExistingPrdFile, SavePrdInput, SavePrdResult } from '../types';
 import { ensurePrdExtension } from '../utils/fileName';
 
 type UsePrdSaveArgs = {
-  projectName?: string;
+  // DB primary key of the project (post migration).
+  projectId?: string;
   existingPrds: ExistingPrdFile[];
   isExistingFile: boolean;
   onAfterSave?: () => Promise<void>;
@@ -17,7 +18,7 @@ type UsePrdSaveResult = {
 };
 
 export function usePrdSave({
-  projectName,
+  projectId,
   existingPrds,
   isExistingFile,
   onAfterSave,
@@ -44,7 +45,7 @@ export function usePrdSave({
         return { status: 'failed', message: 'Please provide a filename for the PRD.' };
       }
 
-      if (!projectName) {
+      if (!projectId) {
         return { status: 'failed', message: 'No project selected. Please reopen the editor.' };
       }
 
@@ -59,7 +60,7 @@ export function usePrdSave({
       setSaving(true);
 
       try {
-        const response = await authenticatedFetch(`/api/taskmaster/prd/${encodeURIComponent(projectName)}`, {
+        const response = await authenticatedFetch(`/api/taskmaster/prd/${encodeURIComponent(projectId)}`, {
           method: 'POST',
           body: JSON.stringify({
             fileName: finalFileName,
@@ -100,7 +101,7 @@ export function usePrdSave({
         setSaving(false);
       }
     },
-    [existingPrds, isExistingFile, onAfterSave, projectName],
+    [existingPrds, isExistingFile, onAfterSave, projectId],
   );
 
   return {
diff --git a/src/components/prd-editor/types.ts b/src/components/prd-editor/types.ts
index c9ddfd85..8cac8c15 100644
--- a/src/components/prd-editor/types.ts
+++ b/src/components/prd-editor/types.ts
@@ -1,7 +1,8 @@
 export type PrdFile = {
   name?: string;
   path?: string;
-  projectName?: string;
+  // DB projectId used to resolve the project path when fetching file content.
+  projectId?: string;
   content?: string;
   isExisting?: boolean;
 };
diff --git a/src/components/project-creation-wizard/ProjectCreationWizard.tsx b/src/components/project-creation-wizard/ProjectCreationWizard.tsx
index fca05c53..022b5ba3 100644
--- a/src/components/project-creation-wizard/ProjectCreationWizard.tsx
+++ b/src/components/project-creation-wizard/ProjectCreationWizard.tsx
@@ -4,13 +4,12 @@ import { useTranslation } from 'react-i18next';
 import ErrorBanner from './components/ErrorBanner';
 import StepConfiguration from './components/StepConfiguration';
 import StepReview from './components/StepReview';
-import StepTypeSelection from './components/StepTypeSelection';
 import WizardFooter from './components/WizardFooter';
 import WizardProgress from './components/WizardProgress';
 import { useGithubTokens } from './hooks/useGithubTokens';
-import { cloneWorkspaceWithProgress, createWorkspaceRequest } from './data/workspaceApi';
+import { cloneWorkspaceWithProgress, createProjectRequest } from './data/workspaceApi';
 import { isCloneWorkflow, shouldShowGithubAuthentication } from './utils/pathUtils';
-import type { TokenMode, WizardFormState, WizardStep, WorkspaceType } from './types';
+import type { TokenMode, WizardFormState, WizardStep } from './types';
 
 type ProjectCreationWizardProps = {
   onClose: () => void;
@@ -18,7 +17,6 @@ type ProjectCreationWizardProps = {
 };
 
 const initialFormState: WizardFormState = {
-  workspaceType: 'existing',
   workspacePath: '',
   githubUrl: '',
   tokenMode: 'stored',
@@ -38,7 +36,7 @@ export default function ProjectCreationWizard({
   const [cloneProgress, setCloneProgress] = useState('');
 
   const shouldLoadTokens =
-    step === 2 && shouldShowGithubAuthentication(formState.workspaceType, formState.githubUrl);
+    step === 1 && shouldShowGithubAuthentication(formState.githubUrl);
 
   const autoSelectToken = useCallback((tokenId: string) => {
     setFormState((previous) => ({ ...previous, selectedGithubToken: tokenId }));
@@ -60,11 +58,6 @@ export default function ProjectCreationWizard({
     setFormState((previous) => ({ ...previous, [key]: value }));
   }, []);
 
-  const updateWorkspaceType = useCallback(
-    (workspaceType: WorkspaceType) => updateField('workspaceType', workspaceType),
-    [updateField],
-  );
-
   const updateTokenMode = useCallback(
     (tokenMode: TokenMode) => updateField('tokenMode', tokenMode),
     [updateField],
@@ -74,22 +67,13 @@ export default function ProjectCreationWizard({
     setError(null);
 
     if (step === 1) {
-      if (!formState.workspaceType) {
-        setError(t('projectWizard.errors.selectType'));
-        return;
-      }
-      setStep(2);
-      return;
-    }
-
-    if (step === 2) {
       if (!formState.workspacePath.trim()) {
         setError(t('projectWizard.errors.providePath'));
         return;
       }
-      setStep(3);
+      setStep(2);
     }
-  }, [formState.workspacePath, formState.workspaceType, step, t]);
+  }, [formState.workspacePath, step, t]);
 
   const handleBack = useCallback(() => {
     setError(null);
@@ -102,7 +86,7 @@ export default function ProjectCreationWizard({
     setCloneProgress('');
 
     try {
-      const shouldCloneRepository = isCloneWorkflow(formState.workspaceType, formState.githubUrl);
+      const shouldCloneRepository = isCloneWorkflow(formState.githubUrl);
 
       if (shouldCloneRepository) {
         const project = await cloneWorkspaceWithProgress(
@@ -123,8 +107,7 @@ export default function ProjectCreationWizard({
         return;
       }
 
-      const project = await createWorkspaceRequest({
-        workspaceType: formState.workspaceType,
+      const project = await createProjectRequest({
         path: formState.workspacePath.trim(),
       });
 
@@ -142,8 +125,8 @@ export default function ProjectCreationWizard({
   }, [formState, onClose, onProjectCreated, t]);
 
   const shouldCloneRepository = useMemo(
-    () => isCloneWorkflow(formState.workspaceType, formState.githubUrl),
-    [formState.githubUrl, formState.workspaceType],
+    () => isCloneWorkflow(formState.githubUrl),
+    [formState.githubUrl],
   );
 
   return (
@@ -173,15 +156,7 @@ export default function ProjectCreationWizard({
           {error && <ErrorBanner message={error} />}
 
           {step === 1 && (
-            <StepTypeSelection
-              workspaceType={formState.workspaceType}
-              onWorkspaceTypeChange={updateWorkspaceType}
-            />
-          )}
-
-          {step === 2 && (
             <StepConfiguration
-              workspaceType={formState.workspaceType}
               workspacePath={formState.workspacePath}
               githubUrl={formState.githubUrl}
               tokenMode={formState.tokenMode}
@@ -200,11 +175,11 @@ export default function ProjectCreationWizard({
               onNewGithubTokenChange={(newGithubToken) =>
                 updateField('newGithubToken', newGithubToken)
               }
-              onAdvanceToConfirm={() => setStep(3)}
+              onAdvanceToConfirm={() => setStep(2)}
             />
           )}
 
-          {step === 3 && (
+          {step === 2 && (
             <StepReview
               formState={formState}
               selectedTokenName={selectedTokenName}
diff --git a/src/components/project-creation-wizard/components/StepConfiguration.tsx b/src/components/project-creation-wizard/components/StepConfiguration.tsx
index 8dde3a20..62f5751a 100644
--- a/src/components/project-creation-wizard/components/StepConfiguration.tsx
+++ b/src/components/project-creation-wizard/components/StepConfiguration.tsx
@@ -1,12 +1,11 @@
 import { useTranslation } from 'react-i18next';
 import { Input } from '../../../shared/view/ui';
 import { shouldShowGithubAuthentication } from '../utils/pathUtils';
-import type { GithubTokenCredential, TokenMode, WorkspaceType } from '../types';
+import type { GithubTokenCredential, TokenMode } from '../types';
 import GithubAuthenticationCard from './GithubAuthenticationCard';
 import WorkspacePathField from './WorkspacePathField';
 
 type StepConfigurationProps = {
-  workspaceType: WorkspaceType;
   workspacePath: string;
   githubUrl: string;
   tokenMode: TokenMode;
@@ -25,7 +24,6 @@ type StepConfigurationProps = {
 };
 
 export default function StepConfiguration({
-  workspaceType,
   workspacePath,
   githubUrl,
   tokenMode,
@@ -43,19 +41,16 @@ export default function StepConfiguration({
   onAdvanceToConfirm,
 }: StepConfigurationProps) {
   const { t } = useTranslation();
-  const showGithubAuth = shouldShowGithubAuthentication(workspaceType, githubUrl);
+  const showGithubAuth = shouldShowGithubAuthentication(githubUrl);
 
   return (
     <div className="space-y-4">
       <div>
         <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
-          {workspaceType === 'existing'
-            ? t('projectWizard.step2.existingPath')
-            : t('projectWizard.step2.newPath')}
+          {t('projectWizard.step2.newPath')}
         </label>
 
         <WorkspacePathField
-          workspaceType={workspaceType}
           value={workspacePath}
           disabled={isCreating}
           onChange={onWorkspacePathChange}
@@ -63,45 +58,39 @@ export default function StepConfiguration({
         />
 
         <p className="mt-1 text-xs text-gray-500 dark:text-gray-400">
-          {workspaceType === 'existing'
-            ? t('projectWizard.step2.existingHelp')
-            : t('projectWizard.step2.newHelp')}
+          {t('projectWizard.step2.newHelp')}
         </p>
       </div>
 
-      {workspaceType === 'new' && (
-        <>
-          <div>
-            <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
-              {t('projectWizard.step2.githubUrl')}
-            </label>
-            <Input
-              type="text"
-              value={githubUrl}
-              onChange={(event) => onGithubUrlChange(event.target.value)}
-              placeholder="https://github.com/username/repository"
-              className="w-full"
-              disabled={isCreating}
-            />
-            <p className="mt-1 text-xs text-gray-500 dark:text-gray-400">
-              {t('projectWizard.step2.githubHelp')}
-            </p>
-          </div>
+      <div>
+        <label className="mb-2 block text-sm font-medium text-gray-700 dark:text-gray-300">
+          {t('projectWizard.step2.githubUrl')}
+        </label>
+        <Input
+          type="text"
+          value={githubUrl}
+          onChange={(event) => onGithubUrlChange(event.target.value)}
+          placeholder="https://github.com/username/repository"
+          className="w-full"
+          disabled={isCreating}
+        />
+        <p className="mt-1 text-xs text-gray-500 dark:text-gray-400">
+          {t('projectWizard.step2.githubHelp')}
+        </p>
+      </div>
 
-          {showGithubAuth && (
-            <GithubAuthenticationCard
-              tokenMode={tokenMode}
-              selectedGithubToken={selectedGithubToken}
-              newGithubToken={newGithubToken}
-              availableTokens={availableTokens}
-              loadingTokens={loadingTokens}
-              tokenLoadError={tokenLoadError}
-              onTokenModeChange={onTokenModeChange}
-              onSelectedGithubTokenChange={onSelectedGithubTokenChange}
-              onNewGithubTokenChange={onNewGithubTokenChange}
-            />
-          )}
-        </>
+      {showGithubAuth && (
+        <GithubAuthenticationCard
+          tokenMode={tokenMode}
+          selectedGithubToken={selectedGithubToken}
+          newGithubToken={newGithubToken}
+          availableTokens={availableTokens}
+          loadingTokens={loadingTokens}
+          tokenLoadError={tokenLoadError}
+          onTokenModeChange={onTokenModeChange}
+          onSelectedGithubTokenChange={onSelectedGithubTokenChange}
+          onNewGithubTokenChange={onNewGithubTokenChange}
+        />
       )}
     </div>
   );
diff --git a/src/components/project-creation-wizard/components/StepReview.tsx b/src/components/project-creation-wizard/components/StepReview.tsx
index 843726a4..526dabf1 100644
--- a/src/components/project-creation-wizard/components/StepReview.tsx
+++ b/src/components/project-creation-wizard/components/StepReview.tsx
@@ -42,17 +42,6 @@ export default function StepReview({
         </h4>
 
         <div className="space-y-2">
-          <div className="flex justify-between text-sm">
-            <span className="text-gray-600 dark:text-gray-400">
-              {t('projectWizard.step3.workspaceType')}
-            </span>
-            <span className="font-medium text-gray-900 dark:text-white">
-              {formState.workspaceType === 'existing'
-                ? t('projectWizard.step3.existingWorkspace')
-                : t('projectWizard.step3.newWorkspace')}
-            </span>
-          </div>
-
           <div className="flex justify-between text-sm">
             <span className="text-gray-600 dark:text-gray-400">{t('projectWizard.step3.path')}</span>
             <span className="break-all font-mono text-xs text-gray-900 dark:text-white">
@@ -60,7 +49,7 @@ export default function StepReview({
             </span>
           </div>
 
-          {formState.workspaceType === 'new' && formState.githubUrl && (
+          {formState.githubUrl && (
             <>
               <div className="flex justify-between text-sm">
                 <span className="text-gray-600 dark:text-gray-400">
@@ -94,11 +83,9 @@ export default function StepReview({
           </div>
         ) : (
           <p className="text-sm text-blue-800 dark:text-blue-200">
-            {formState.workspaceType === 'existing'
-              ? t('projectWizard.step3.existingInfo')
-              : formState.githubUrl
-                ? t('projectWizard.step3.newWithClone')
-                : t('projectWizard.step3.newEmpty')}
+            {formState.githubUrl
+              ? t('projectWizard.step3.newWithClone')
+              : t('projectWizard.step3.newEmpty')}
           </p>
         )}
       </div>
diff --git a/src/components/project-creation-wizard/components/StepTypeSelection.tsx b/src/components/project-creation-wizard/components/StepTypeSelection.tsx
deleted file mode 100644
index efa4345e..00000000
--- a/src/components/project-creation-wizard/components/StepTypeSelection.tsx
+++ /dev/null
@@ -1,71 +0,0 @@
-import { FolderPlus, GitBranch } from 'lucide-react';
-import { useTranslation } from 'react-i18next';
-import type { WorkspaceType } from '../types';
-
-type StepTypeSelectionProps = {
-  workspaceType: WorkspaceType;
-  onWorkspaceTypeChange: (workspaceType: WorkspaceType) => void;
-};
-
-export default function StepTypeSelection({
-  workspaceType,
-  onWorkspaceTypeChange,
-}: StepTypeSelectionProps) {
-  const { t } = useTranslation();
-
-  return (
-    <div className="space-y-4">
-      <h4 className="mb-3 text-sm font-medium text-gray-700 dark:text-gray-300">
-        {t('projectWizard.step1.question')}
-      </h4>
-
-      <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
-        <button
-          onClick={() => onWorkspaceTypeChange('existing')}
-          className={`rounded-lg border-2 p-4 text-left transition-all ${
-            workspaceType === 'existing'
-              ? 'border-blue-500 bg-blue-50 dark:bg-blue-900/20'
-              : 'border-gray-200 hover:border-gray-300 dark:border-gray-700 dark:hover:border-gray-600'
-          }`}
-        >
-          <div className="flex items-start gap-3">
-            <div className="flex h-10 w-10 flex-shrink-0 items-center justify-center rounded-lg bg-green-100 dark:bg-green-900/50">
-              <FolderPlus className="h-5 w-5 text-green-600 dark:text-green-400" />
-            </div>
-            <div className="flex-1">
-              <h5 className="mb-1 font-semibold text-gray-900 dark:text-white">
-                {t('projectWizard.step1.existing.title')}
-              </h5>
-              <p className="text-sm text-gray-600 dark:text-gray-400">
-                {t('projectWizard.step1.existing.description')}
-              </p>
-            </div>
-          </div>
-        </button>
-
-        <button
-          onClick={() => onWorkspaceTypeChange('new')}
-          className={`rounded-lg border-2 p-4 text-left transition-all ${
-            workspaceType === 'new'
-              ? 'border-blue-500 bg-blue-50 dark:bg-blue-900/20'
-              : 'border-gray-200 hover:border-gray-300 dark:border-gray-700 dark:hover:border-gray-600'
-          }`}
-        >
-          <div className="flex items-start gap-3">
-            <div className="flex h-10 w-10 flex-shrink-0 items-center justify-center rounded-lg bg-purple-100 dark:bg-purple-900/50">
-              <GitBranch className="h-5 w-5 text-purple-600 dark:text-purple-400" />
-            </div>
-            <div className="flex-1">
-              <h5 className="mb-1 font-semibold text-gray-900 dark:text-white">
-                {t('projectWizard.step1.new.title')}
-              </h5>
-              <p className="text-sm text-gray-600 dark:text-gray-400">
-                {t('projectWizard.step1.new.description')}
-              </p>
-            </div>
-          </div>
-        </button>
-      </div>
-    </div>
-  );
-}
diff --git a/src/components/project-creation-wizard/components/WizardFooter.tsx b/src/components/project-creation-wizard/components/WizardFooter.tsx
index 5fbf64ab..78cf2fec 100644
--- a/src/components/project-creation-wizard/components/WizardFooter.tsx
+++ b/src/components/project-creation-wizard/components/WizardFooter.tsx
@@ -37,7 +37,7 @@ export default function WizardFooter({
         )}
       </Button>
 
-      <Button onClick={step === 3 ? onCreate : onNext} disabled={isCreating}>
+      <Button onClick={step === 2 ? onCreate : onNext} disabled={isCreating}>
         {isCreating ? (
           <>
             <Loader2 className="mr-2 h-4 w-4 animate-spin" />
@@ -45,7 +45,7 @@ export default function WizardFooter({
               ? t('projectWizard.buttons.cloning', { defaultValue: 'Cloning...' })
               : t('projectWizard.buttons.creating')}
           </>
-        ) : step === 3 ? (
+        ) : step === 2 ? (
           <>
             <Check className="mr-1 h-4 w-4" />
             {t('projectWizard.buttons.createProject')}
diff --git a/src/components/project-creation-wizard/components/WizardProgress.tsx b/src/components/project-creation-wizard/components/WizardProgress.tsx
index 719eefaa..87695b79 100644
--- a/src/components/project-creation-wizard/components/WizardProgress.tsx
+++ b/src/components/project-creation-wizard/components/WizardProgress.tsx
@@ -9,7 +9,7 @@ type WizardProgressProps = {
 
 export default function WizardProgress({ step }: WizardProgressProps) {
   const { t } = useTranslation();
-  const steps: WizardStep[] = [1, 2, 3];
+  const steps: WizardStep[] = [1, 2];
 
   return (
     <div className="px-6 pb-2 pt-4">
@@ -30,14 +30,12 @@ export default function WizardProgress({ step }: WizardProgressProps) {
               </div>
               <span className="hidden text-sm font-medium text-gray-700 dark:text-gray-300 sm:inline">
                 {currentStep === 1
-                  ? t('projectWizard.steps.type')
-                  : currentStep === 2
-                    ? t('projectWizard.steps.configure')
-                    : t('projectWizard.steps.confirm')}
+                  ? t('projectWizard.steps.configure')
+                  : t('projectWizard.steps.confirm')}
               </span>
             </div>
 
-            {currentStep < 3 && (
+            {currentStep < 2 && (
               <div
                 className={`mx-2 h-1 flex-1 rounded ${
                   currentStep < step ? 'bg-green-500' : 'bg-gray-200 dark:bg-gray-700'
diff --git a/src/components/project-creation-wizard/components/WorkspacePathField.tsx b/src/components/project-creation-wizard/components/WorkspacePathField.tsx
index 54f60f06..1d7c2865 100644
--- a/src/components/project-creation-wizard/components/WorkspacePathField.tsx
+++ b/src/components/project-creation-wizard/components/WorkspacePathField.tsx
@@ -3,11 +3,10 @@ import { FolderOpen } from 'lucide-react';
 import { Button, Input } from '../../../shared/view/ui';
 import { browseFilesystemFolders } from '../data/workspaceApi';
 import { getSuggestionRootPath } from '../utils/pathUtils';
-import type { FolderSuggestion, WorkspaceType } from '../types';
+import type { FolderSuggestion } from '../types';
 import FolderBrowserModal from './FolderBrowserModal';
 
 type WorkspacePathFieldProps = {
-  workspaceType: WorkspaceType;
   value: string;
   disabled?: boolean;
   onChange: (path: string) => void;
@@ -15,7 +14,6 @@ type WorkspacePathFieldProps = {
 };
 
 export default function WorkspacePathField({
-  workspaceType,
   value,
   disabled = false,
   onChange,
@@ -88,11 +86,7 @@ export default function WorkspacePathField({
             type="text"
             value={value}
             onChange={(event) => onChange(event.target.value)}
-            placeholder={
-              workspaceType === 'existing'
-                ? '/path/to/existing/workspace'
-                : '/path/to/new/workspace'
-            }
+            placeholder="/path/to/project/workspace"
             className="w-full"
             disabled={disabled}
           />
@@ -127,7 +121,7 @@ export default function WorkspacePathField({
 
       <FolderBrowserModal
         isOpen={showFolderBrowser}
-        autoAdvanceOnSelect={workspaceType === 'existing'}
+        autoAdvanceOnSelect={false}
         onClose={() => setShowFolderBrowser(false)}
         onFolderSelected={handleFolderSelected}
       />
diff --git a/src/components/project-creation-wizard/data/workspaceApi.ts b/src/components/project-creation-wizard/data/workspaceApi.ts
index f4ca3baf..9d6d428f 100644
--- a/src/components/project-creation-wizard/data/workspaceApi.ts
+++ b/src/components/project-creation-wizard/data/workspaceApi.ts
@@ -3,8 +3,8 @@ import type {
   BrowseFilesystemResponse,
   CloneProgressEvent,
   CreateFolderResponse,
-  CreateWorkspacePayload,
-  CreateWorkspaceResponse,
+  CreateProjectPayload,
+  CreateProjectResponse,
   CredentialsResponse,
   FolderSuggestion,
   TokenMode,
@@ -27,6 +27,42 @@ const parseJson = async <T>(response: Response): Promise<T> => {
   return data;
 };
 
+const resolveCreateProjectErrorMessage = (responseData: CreateProjectResponse): string | null => {
+  if (typeof responseData.details === 'string' && responseData.details.trim().length > 0) {
+    return responseData.details;
+  }
+
+  if (typeof responseData.error === 'string' && responseData.error.trim().length > 0) {
+    return responseData.error;
+  }
+
+  if (responseData.error && typeof responseData.error === 'object') {
+    const errorObject = responseData.error as { message?: unknown; details?: unknown };
+
+    if (typeof errorObject.details === 'string' && errorObject.details.trim().length > 0) {
+      return errorObject.details;
+    }
+
+    if (typeof errorObject.message === 'string' && errorObject.message.trim().length > 0) {
+      return errorObject.message;
+    }
+
+    if (
+      errorObject.details
+      && typeof errorObject.details === 'object'
+      && typeof (errorObject.details as { projectPath?: unknown }).projectPath === 'string'
+    ) {
+      return `Project path already exists: ${(errorObject.details as { projectPath: string }).projectPath}`;
+    }
+  }
+
+  if (typeof responseData.message === 'string' && responseData.message.trim().length > 0) {
+    return responseData.message;
+  }
+
+  return null;
+};
+
 export const fetchGithubTokenCredentials = async () => {
   const response = await api.get('/settings/credentials?type=github_token');
   const data = await parseJson<CredentialsResponse>(response);
@@ -64,12 +100,12 @@ export const createFolderInFilesystem = async (folderPath: string) => {
   return data.path || folderPath;
 };
 
-export const createWorkspaceRequest = async (payload: CreateWorkspacePayload) => {
-  const response = await api.createWorkspace(payload);
-  const data = await parseJson<CreateWorkspaceResponse>(response);
+export const createProjectRequest = async (payload: CreateProjectPayload) => {
+  const response = await api.createProject(payload);
+  const data = await parseJson<CreateProjectResponse>(response);
 
   if (!response.ok) {
-    throw new Error(data.details || data.error || 'Failed to create workspace');
+    throw new Error(resolveCreateProjectErrorMessage(data) || 'Failed to create project');
   }
 
   return data.project;
diff --git a/src/components/project-creation-wizard/types.ts b/src/components/project-creation-wizard/types.ts
index 4b156303..eb25c342 100644
--- a/src/components/project-creation-wizard/types.ts
+++ b/src/components/project-creation-wizard/types.ts
@@ -1,6 +1,4 @@
-export type WizardStep = 1 | 2 | 3;
-
-export type WorkspaceType = 'existing' | 'new';
+export type WizardStep = 1 | 2;
 
 export type TokenMode = 'stored' | 'new' | 'none';
 
@@ -34,16 +32,23 @@ export type CreateFolderResponse = {
   details?: string;
 };
 
-export type CreateWorkspacePayload = {
-  workspaceType: WorkspaceType;
+export type CreateProjectPayload = {
   path: string;
+  customName?: string;
 };
 
-export type CreateWorkspaceResponse = {
+export type CreateProjectApiError = {
+  code?: string;
+  message?: string;
+  details?: unknown;
+};
+
+export type CreateProjectResponse = {
   success?: boolean;
   project?: Record<string, unknown>;
-  error?: string;
+  error?: string | CreateProjectApiError;
   details?: string;
+  message?: string;
 };
 
 export type CloneProgressEvent = {
@@ -53,7 +58,6 @@ export type CloneProgressEvent = {
 };
 
 export type WizardFormState = {
-  workspaceType: WorkspaceType;
   workspacePath: string;
   githubUrl: string;
   tokenMode: TokenMode;
diff --git a/src/components/project-creation-wizard/utils/pathUtils.ts b/src/components/project-creation-wizard/utils/pathUtils.ts
index 6799c3c1..0efe6c83 100644
--- a/src/components/project-creation-wizard/utils/pathUtils.ts
+++ b/src/components/project-creation-wizard/utils/pathUtils.ts
@@ -1,5 +1,3 @@
-import type { WorkspaceType } from '../types';
-
 const SSH_PREFIXES = ['git@', 'ssh://'];
 const WINDOWS_DRIVE_PATTERN = /^[A-Za-z]:\\?$/;
 
@@ -8,13 +6,11 @@ export const isSshGitUrl = (url: string): boolean => {
   return SSH_PREFIXES.some((prefix) => trimmedUrl.startsWith(prefix));
 };
 
-export const shouldShowGithubAuthentication = (
-  workspaceType: WorkspaceType,
-  githubUrl: string,
-): boolean => workspaceType === 'new' && githubUrl.trim().length > 0 && !isSshGitUrl(githubUrl);
+export const shouldShowGithubAuthentication = (githubUrl: string): boolean =>
+  githubUrl.trim().length > 0 && !isSshGitUrl(githubUrl);
 
-export const isCloneWorkflow = (workspaceType: WorkspaceType, githubUrl: string): boolean =>
-  workspaceType === 'new' && githubUrl.trim().length > 0;
+export const isCloneWorkflow = (githubUrl: string): boolean =>
+  githubUrl.trim().length > 0;
 
 export const getSuggestionRootPath = (inputPath: string): string => {
   const trimmedPath = inputPath.trim();
diff --git a/src/components/provider-auth/hooks/useProviderAuthStatus.ts b/src/components/provider-auth/hooks/useProviderAuthStatus.ts
index 387d6327..9231e770 100644
--- a/src/components/provider-auth/hooks/useProviderAuthStatus.ts
+++ b/src/components/provider-auth/hooks/useProviderAuthStatus.ts
@@ -70,34 +70,39 @@ export function useProviderAuthStatus(
     }));
   }, []);
 
-  const checkProviderAuthStatus = useCallback(async (provider: LLMProvider) => {
+  const checkProviderAuthStatus = useCallback(async (provider: LLMProvider): Promise<ProviderAuthStatus> => {
     setProviderLoading(provider);
 
     try {
       const response = await authenticatedFetch(PROVIDER_AUTH_STATUS_ENDPOINTS[provider]);
 
       if (!response.ok) {
-        setProviderStatus(provider, {
+        const status: ProviderAuthStatus = {
           authenticated: false,
           email: null,
           method: null,
           loading: false,
           error: FALLBACK_STATUS_ERROR,
-        });
-        return;
+        };
+        setProviderStatus(provider, status);
+        return status;
       }
 
       const payload = (await response.json()) as ProviderAuthStatusApiResponse;
-      setProviderStatus(provider, toProviderAuthStatus(payload.data));
+      const status = toProviderAuthStatus(payload.data);
+      setProviderStatus(provider, status);
+      return status;
     } catch (caughtError) {
       console.error(`Error checking ${provider} auth status:`, caughtError);
-      setProviderStatus(provider, {
+      const status: ProviderAuthStatus = {
         authenticated: false,
         email: null,
         method: null,
         loading: false,
         error: toErrorMessage(caughtError),
-      });
+      };
+      setProviderStatus(provider, status);
+      return status;
     }
   }, [setProviderLoading, setProviderStatus]);
 
diff --git a/src/components/provider-auth/types.ts b/src/components/provider-auth/types.ts
index d79ab1c8..afa08094 100644
--- a/src/components/provider-auth/types.ts
+++ b/src/components/provider-auth/types.ts
@@ -10,13 +10,14 @@ export type ProviderAuthStatus = {
 
 export type ProviderAuthStatusMap = Record<LLMProvider, ProviderAuthStatus>;
 
-export const CLI_PROVIDERS: LLMProvider[] = ['claude', 'cursor', 'codex', 'gemini'];
+export const CLI_PROVIDERS: LLMProvider[] = ['claude', 'cursor', 'codex', 'gemini', 'opencode'];
 
 export const PROVIDER_AUTH_STATUS_ENDPOINTS: Record<LLMProvider, string> = {
   claude: '/api/providers/claude/auth/status',
   cursor: '/api/providers/cursor/auth/status',
   codex: '/api/providers/codex/auth/status',
   gemini: '/api/providers/gemini/auth/status',
+  opencode: '/api/providers/opencode/auth/status',
 };
 
 export const createInitialProviderAuthStatusMap = (loading = true): ProviderAuthStatusMap => ({
@@ -24,4 +25,5 @@ export const createInitialProviderAuthStatusMap = (loading = true): ProviderAuth
   cursor: { authenticated: false, email: null, method: null, error: null, loading },
   codex: { authenticated: false, email: null, method: null, error: null, loading },
   gemini: { authenticated: false, email: null, method: null, error: null, loading },
+  opencode: { authenticated: false, email: null, method: null, error: null, loading },
 });
diff --git a/src/components/provider-auth/view/ProviderLoginModal.tsx b/src/components/provider-auth/view/ProviderLoginModal.tsx
index fa1d4407..9de1d227 100644
--- a/src/components/provider-auth/view/ProviderLoginModal.tsx
+++ b/src/components/provider-auth/view/ProviderLoginModal.tsx
@@ -37,6 +37,10 @@ const getProviderCommand = ({
     return IS_PLATFORM ? 'codex login --device-auth' : 'codex login';
   }
 
+  if (provider === 'opencode') {
+    return 'opencode auth login';
+  }
+
   return 'gemini status';
 };
 
@@ -44,6 +48,7 @@ const getProviderTitle = (provider: LLMProvider) => {
   if (provider === 'claude') return 'Claude CLI Login';
   if (provider === 'cursor') return 'Cursor CLI Login';
   if (provider === 'codex') return 'Codex CLI Login';
+  if (provider === 'opencode') return 'OpenCode CLI Login';
   return 'Gemini CLI Configuration';
 };
 
diff --git a/src/components/settings/constants/constants.ts b/src/components/settings/constants/constants.ts
index 429aabbe..7d4c353d 100644
--- a/src/components/settings/constants/constants.ts
+++ b/src/components/settings/constants/constants.ts
@@ -1,3 +1,15 @@
+import type { ComponentType } from 'react';
+import {
+  Bell,
+  Bot,
+  GitBranch,
+  Info,
+  KeyRound,
+  ListChecks,
+  Palette,
+  Plug,
+} from 'lucide-react';
+
 import type {
   AgentCategory,
   AgentProvider,
@@ -7,16 +19,25 @@ import type {
   SettingsMainTab,
 } from '../types/types';
 
-export const SETTINGS_MAIN_TABS: SettingsMainTab[] = [
-  'agents',
-  'appearance',
-  'git',
-  'api',
-  'tasks',
-  'notifications',
+export type SettingsMainTabMeta = {
+  id: SettingsMainTab;
+  label: string;
+  keywords: string;
+  icon: ComponentType<{ className?: string }>;
+};
+
+export const SETTINGS_MAIN_TABS: SettingsMainTabMeta[] = [
+  { id: 'agents', label: 'Agents', keywords: 'agents subagents claude code', icon: Bot },
+  { id: 'appearance', label: 'Appearance', keywords: 'appearance theme dark light language', icon: Palette },
+  { id: 'git', label: 'Git', keywords: 'git github commits', icon: GitBranch },
+  { id: 'api', label: 'API Tokens', keywords: 'api tokens auth keys', icon: KeyRound },
+  { id: 'tasks', label: 'Tasks', keywords: 'tasks taskmaster', icon: ListChecks },
+  { id: 'notifications', label: 'Notifications', keywords: 'notifications alerts push', icon: Bell },
+  { id: 'plugins', label: 'Plugins', keywords: 'plugins extensions integrations', icon: Plug },
+  { id: 'about', label: 'About', keywords: 'about version info', icon: Info },
 ];
 
-export const AGENT_PROVIDERS: AgentProvider[] = ['claude', 'cursor', 'codex', 'gemini'];
+export const AGENT_PROVIDERS: AgentProvider[] = ['claude', 'cursor', 'codex', 'gemini', 'opencode'];
 export const AGENT_CATEGORIES: AgentCategory[] = ['account', 'permissions', 'mcp'];
 
 export const DEFAULT_PROJECT_SORT_ORDER: ProjectSortOrder = 'name';
@@ -34,4 +55,3 @@ export const DEFAULT_CURSOR_PERMISSIONS: CursorPermissionsState = {
   disallowedCommands: [],
   skipPermissions: false,
 };
-
diff --git a/src/components/settings/hooks/useSettingsController.ts b/src/components/settings/hooks/useSettingsController.ts
index 5463a5bb..c81a7c04 100644
--- a/src/components/settings/hooks/useSettingsController.ts
+++ b/src/components/settings/hooks/useSettingsController.ts
@@ -213,12 +213,19 @@ export function useSettingsController({ isOpen, initialTab }: UseSettingsControl
   }, []);
 
   const handleLoginComplete = useCallback((exitCode: number) => {
-    if (exitCode !== 0 || !loginProvider) {
+    if (!loginProvider) {
       return;
     }
 
-    setSaveStatus('success');
-    void checkProviderAuthStatus(loginProvider);
+    void (async () => {
+      const authStatus = await checkProviderAuthStatus(loginProvider);
+
+      if (exitCode !== 0) {
+        console.warn(`Login process exited with code ${exitCode}; refreshing auth status before setting save status.`);
+      }
+
+      setSaveStatus(authStatus.authenticated ? 'success' : 'error');
+    })();
   }, [checkProviderAuthStatus, loginProvider]);
 
   const saveSettings = useCallback(async () => {
diff --git a/src/components/settings/view/tabs/agents-settings/AgentListItem.tsx b/src/components/settings/view/tabs/agents-settings/AgentListItem.tsx
index 47135939..b23784ee 100644
--- a/src/components/settings/view/tabs/agents-settings/AgentListItem.tsx
+++ b/src/components/settings/view/tabs/agents-settings/AgentListItem.tsx
@@ -12,7 +12,7 @@ type AgentListItemProps = {
 
 type AgentConfig = {
   name: string;
-  color: 'blue' | 'purple' | 'gray' | 'indigo';
+  color: 'blue' | 'purple' | 'gray' | 'indigo' | 'zinc';
 };
 
 const agentConfig: Record<AgentProvider, AgentConfig> = {
@@ -31,7 +31,11 @@ const agentConfig: Record<AgentProvider, AgentConfig> = {
   gemini: {
     name: 'Gemini',
     color: 'indigo',
-  }
+  },
+  opencode: {
+    name: 'OpenCode',
+    color: 'zinc',
+  },
 };
 
 const colorClasses = {
@@ -47,6 +51,9 @@ const colorClasses = {
   indigo: {
     dot: 'bg-indigo-500',
   },
+  zinc: {
+    dot: 'bg-zinc-500',
+  },
 } as const;
 
 export default function AgentListItem({
diff --git a/src/components/settings/view/tabs/agents-settings/AgentsSettingsTab.tsx b/src/components/settings/view/tabs/agents-settings/AgentsSettingsTab.tsx
index 47087676..ee24239c 100644
--- a/src/components/settings/view/tabs/agents-settings/AgentsSettingsTab.tsx
+++ b/src/components/settings/view/tabs/agents-settings/AgentsSettingsTab.tsx
@@ -1,6 +1,5 @@
-import { useEffect, useMemo, useState } from 'react';
+import { useMemo, useState } from 'react';
 
-import { useServerPlatform } from '../../../../../hooks/useServerPlatform';
 import type { AgentCategory, AgentProvider } from '../../../types/types';
 
 import type { AgentContext, AgentsSettingsTabProps } from './types';
@@ -23,22 +22,10 @@ export default function AgentsSettingsTab({
 }: AgentsSettingsTabProps) {
   const [selectedAgent, setSelectedAgent] = useState<AgentProvider>('claude');
   const [selectedCategory, setSelectedCategory] = useState<AgentCategory>('account');
-  const { isWindowsServer } = useServerPlatform();
 
   const visibleAgents = useMemo<AgentProvider[]>(() => {
-    const all: AgentProvider[] = ['claude', 'cursor', 'codex', 'gemini'];
-    if (isWindowsServer) {
-      return all.filter((id) => id !== 'cursor');
-    }
-
-    return all;
-  }, [isWindowsServer]);
-
-  useEffect(() => {
-    if (isWindowsServer && selectedAgent === 'cursor') {
-      setSelectedAgent('claude');
-    }
-  }, [isWindowsServer, selectedAgent]);
+    return ['claude', 'cursor', 'codex', 'gemini', 'opencode'];
+  }, []);
 
   const agentContextById = useMemo<Record<AgentProvider, AgentContext>>(() => ({
     claude: {
@@ -57,12 +44,17 @@ export default function AgentsSettingsTab({
       authStatus: providerAuthStatus.gemini,
       onLogin: () => onProviderLogin('gemini'),
     },
+    opencode: {
+      authStatus: providerAuthStatus.opencode,
+      onLogin: () => onProviderLogin('opencode'),
+    },
   }), [
     onProviderLogin,
     providerAuthStatus.claude,
     providerAuthStatus.codex,
     providerAuthStatus.cursor,
     providerAuthStatus.gemini,
+    providerAuthStatus.opencode,
   ]);
 
   return (
diff --git a/src/components/settings/view/tabs/agents-settings/sections/AgentCategoryContentSection.tsx b/src/components/settings/view/tabs/agents-settings/sections/AgentCategoryContentSection.tsx
index caeca7c1..6f9fee5a 100644
--- a/src/components/settings/view/tabs/agents-settings/sections/AgentCategoryContentSection.tsx
+++ b/src/components/settings/view/tabs/agents-settings/sections/AgentCategoryContentSection.tsx
@@ -1,4 +1,5 @@
 import type { AgentCategoryContentSectionProps } from '../types';
+import type { McpProject } from '../../../../../mcp/types';
 import { McpServers } from '../../../../../mcp';
 
 import AccountContent from './content/AccountContent';
@@ -71,9 +72,16 @@ export default function AgentCategoryContentSection({
       )}
 
       {selectedCategory === 'mcp' && (
+        // SettingsProject.name is populated from the DB projectId by
+        // normalizeProjectForSettings, so we can map it straight through.
         <McpServers
           selectedProvider={selectedAgent}
-          currentProjects={projects}
+          currentProjects={projects.map<McpProject>((project) => ({
+            projectId: project.name,
+            displayName: project.displayName,
+            fullPath: project.fullPath,
+            path: project.path,
+          }))}
         />
       )}
     </div>
diff --git a/src/components/settings/view/tabs/agents-settings/sections/AgentSelectorSection.tsx b/src/components/settings/view/tabs/agents-settings/sections/AgentSelectorSection.tsx
index 92304c01..a6d017fa 100644
--- a/src/components/settings/view/tabs/agents-settings/sections/AgentSelectorSection.tsx
+++ b/src/components/settings/view/tabs/agents-settings/sections/AgentSelectorSection.tsx
@@ -8,6 +8,7 @@ const AGENT_NAMES: Record<AgentProvider, string> = {
   cursor: 'Cursor',
   codex: 'Codex',
   gemini: 'Gemini',
+  opencode: 'OpenCode',
 };
 
 export default function AgentSelectorSection({
@@ -23,7 +24,8 @@ export default function AgentSelectorSection({
           const dotColor =
             agent === 'claude' ? 'bg-blue-500' :
             agent === 'cursor' ? 'bg-purple-500' :
-            agent === 'gemini' ? 'bg-indigo-500' : 'bg-foreground/60';
+            agent === 'gemini' ? 'bg-indigo-500' :
+            agent === 'opencode' ? 'bg-zinc-500' : 'bg-foreground/60';
 
           return (
             <Pill
diff --git a/src/components/settings/view/tabs/agents-settings/sections/content/AccountContent.tsx b/src/components/settings/view/tabs/agents-settings/sections/content/AccountContent.tsx
index dcf4baf1..c0ed69d5 100644
--- a/src/components/settings/view/tabs/agents-settings/sections/content/AccountContent.tsx
+++ b/src/components/settings/view/tabs/agents-settings/sections/content/AccountContent.tsx
@@ -54,6 +54,15 @@ const agentConfig: Record<AgentProvider, AgentVisualConfig> = {
     subtextClass: 'text-indigo-700 dark:text-indigo-300',
     buttonClass: 'bg-indigo-600 hover:bg-indigo-700 active:bg-indigo-800',
   },
+  opencode: {
+    name: 'OpenCode',
+    description: 'OpenCode CLI assistant',
+    bgClass: 'bg-zinc-50 dark:bg-zinc-900/20',
+    borderClass: 'border-zinc-200 dark:border-zinc-700',
+    textClass: 'text-zinc-900 dark:text-zinc-100',
+    subtextClass: 'text-zinc-700 dark:text-zinc-300',
+    buttonClass: 'bg-zinc-900 hover:bg-zinc-800 active:bg-zinc-950 dark:bg-zinc-700 dark:hover:bg-zinc-600',
+  },
 };
 
 export default function AccountContent({ agent, authStatus, onLogin }: AccountContentProps) {
@@ -66,7 +75,11 @@ export default function AccountContent({ agent, authStatus, onLogin }: AccountCo
         <SessionProviderLogo provider={agent} className="h-6 w-6" />
         <div>
           <h3 className="text-lg font-medium text-foreground">{config.name}</h3>
-          <p className="text-sm text-muted-foreground">{t(`agents.account.${agent}.description`)}</p>
+          <p className="text-sm text-muted-foreground">
+            {t(`agents.account.${agent}.description`, {
+              defaultValue: config.description || `${config.name} CLI assistant`,
+            })}
+          </p>
         </div>
       </div>
 
diff --git a/src/components/sidebar/hooks/useSidebarController.ts b/src/components/sidebar/hooks/useSidebarController.ts
index b21f13ad..ba559442 100644
--- a/src/components/sidebar/hooks/useSidebarController.ts
+++ b/src/components/sidebar/hooks/useSidebarController.ts
@@ -1,21 +1,23 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import type React from 'react';
 import type { TFunction } from 'i18next';
+
 import { api } from '../../../utils/api';
+import { usePaletteOps } from '../../../contexts/PaletteOpsContext';
 import type { Project, ProjectSession, LLMProvider } from '../../../types/app';
 import type {
-  AdditionalSessionsByProject,
+  ArchivedProjectListItem,
+  ArchivedSessionListItem,
   DeleteProjectConfirmation,
-  LoadingSessionsByProject,
   ProjectSortOrder,
+  SidebarSearchMode,
   SessionDeleteConfirmation,
   SessionWithProvider,
 } from '../types/types';
 import {
+  clearLegacyStarredProjectIds,
   filterProjects,
   getAllSessions,
-  loadStarredProjects,
-  persistStarredProjects,
+  readLegacyStarredProjectIds,
   readProjectSortOrder,
   sortProjects,
 } from '../utils/utils';
@@ -42,6 +44,9 @@ type ConversationSession = {
 };
 
 type ConversationProjectResult = {
+  // Emitted by the provider search service so the sidebar can map a
+  // match back to the Project in its current state by projectId.
+  projectId: string | null;
   projectName: string;
   projectDisplayName: string;
   sessions: ConversationSession[];
@@ -58,6 +63,20 @@ export type SearchProgress = {
   totalProjects: number;
 };
 
+type ArchivedSessionsApiPayload = {
+  success?: boolean;
+  data?: {
+    sessions?: ArchivedSessionListItem[];
+  };
+};
+
+type ArchivedProjectsApiPayload = {
+  success?: boolean;
+  data?: {
+    projects?: ArchivedProjectListItem[];
+  };
+};
+
 type UseSidebarControllerArgs = {
   projects: Project[];
   selectedProject: Project | null;
@@ -69,7 +88,9 @@ type UseSidebarControllerArgs = {
   onProjectSelect: (project: Project) => void;
   onSessionSelect: (session: ProjectSession) => void;
   onSessionDelete?: (sessionId: string) => void;
-  onProjectDelete?: (projectName: string) => void;
+  onLoadMoreSessions?: (projectId: string) => Promise<void> | void;
+  // `projectId` is the DB-assigned identifier; callbacks use that post-migration.
+  onProjectDelete?: (projectId: string) => void;
   setCurrentProject: (project: Project) => void;
   setSidebarVisible: (visible: boolean) => void;
   sidebarVisible: boolean;
@@ -78,7 +99,7 @@ type UseSidebarControllerArgs = {
 export function useSidebarController({
   projects,
   selectedProject,
-  selectedSession,
+  selectedSession: _selectedSession,
   isLoading,
   isMobile,
   t,
@@ -86,22 +107,21 @@ export function useSidebarController({
   onProjectSelect,
   onSessionSelect,
   onSessionDelete,
+  onLoadMoreSessions,
   onProjectDelete,
   setCurrentProject,
   setSidebarVisible,
   sidebarVisible,
 }: UseSidebarControllerArgs) {
+  const paletteOps = usePaletteOps();
   const [expandedProjects, setExpandedProjects] = useState<Set<string>>(new Set());
   const [editingProject, setEditingProject] = useState<string | null>(null);
   const [showNewProject, setShowNewProject] = useState(false);
   const [editingName, setEditingName] = useState('');
-  const [loadingSessions, setLoadingSessions] = useState<LoadingSessionsByProject>({});
-  const [additionalSessions, setAdditionalSessions] = useState<AdditionalSessionsByProject>({});
   const [initialSessionsLoaded, setInitialSessionsLoaded] = useState<Set<string>>(new Set());
   const [currentTime, setCurrentTime] = useState(new Date());
   const [projectSortOrder, setProjectSortOrder] = useState<ProjectSortOrder>('name');
   const [isRefreshing, setIsRefreshing] = useState(false);
-  const [projectHasMoreOverrides, setProjectHasMoreOverrides] = useState<Record<string, boolean>>({});
   const [editingSession, setEditingSession] = useState<string | null>(null);
   const [editingSessionName, setEditingSessionName] = useState('');
   const [searchFilter, setSearchFilter] = useState('');
@@ -109,14 +129,21 @@ export function useSidebarController({
   const [deleteConfirmation, setDeleteConfirmation] = useState<DeleteProjectConfirmation | null>(null);
   const [sessionDeleteConfirmation, setSessionDeleteConfirmation] = useState<SessionDeleteConfirmation | null>(null);
   const [showVersionModal, setShowVersionModal] = useState(false);
-  const [starredProjects, setStarredProjects] = useState<Set<string>>(() => loadStarredProjects());
-  const [searchMode, setSearchMode] = useState<'projects' | 'conversations'>('projects');
+  const [searchMode, setSearchMode] = useState<SidebarSearchMode>('projects');
   const [conversationResults, setConversationResults] = useState<ConversationSearchResults | null>(null);
   const [isSearching, setIsSearching] = useState(false);
   const [searchProgress, setSearchProgress] = useState<SearchProgress | null>(null);
-  const searchTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [archivedProjects, setArchivedProjects] = useState<ArchivedProjectListItem[]>([]);
+  const [archivedSessions, setArchivedSessions] = useState<ArchivedSessionListItem[]>([]);
+  const [isArchivedSessionsLoading, setIsArchivedSessionsLoading] = useState(false);
+  const [debouncedSearchQuery, setDebouncedSearchQuery] = useState('');
+  const [optimisticStarByProjectId, setOptimisticStarByProjectId] = useState<Map<string, boolean>>(new Map());
+  const [loadingMoreProjects, setLoadingMoreProjects] = useState<Set<string>>(new Set());
   const searchSeqRef = useRef(0);
   const eventSourceRef = useRef<EventSource | null>(null);
+  const starToggleSequenceByProjectRef = useRef<Map<string, number>>(new Map());
+  const migrationStartedRef = useRef(false);
+  const onRefreshRef = useRef(onRefresh);
 
   const isSidebarCollapsed = !isMobile && !sidebarVisible;
 
@@ -129,30 +156,34 @@ export function useSidebarController({
   }, []);
 
   useEffect(() => {
-    setAdditionalSessions({});
     setInitialSessionsLoaded(new Set());
-    setProjectHasMoreOverrides({});
   }, [projects]);
 
   useEffect(() => {
-    if (selectedProject) {
-      setExpandedProjects((prev) => {
-        if (prev.has(selectedProject.name)) {
-          return prev;
-        }
-        const next = new Set(prev);
-        next.add(selectedProject.name);
-        return next;
-      });
+    // Auto-expand only when the selected project identity changes.
+    // Depending on the full `selectedProject` object (or `selectedSession`) causes
+    // websocket-driven list refreshes to re-open projects users manually collapsed.
+    const selectedProjectId = selectedProject?.projectId;
+    if (!selectedProjectId) {
+      return;
     }
-  }, [selectedSession, selectedProject]);
+
+    setExpandedProjects((prev) => {
+      if (prev.has(selectedProjectId)) {
+        return prev;
+      }
+      const next = new Set(prev);
+      next.add(selectedProjectId);
+      return next;
+    });
+  }, [selectedProject?.projectId]);
 
   useEffect(() => {
     if (projects.length > 0 && !isLoading) {
       const loadedProjects = new Set<string>();
       projects.forEach((project) => {
         if (project.sessions && project.sessions.length >= 0) {
-          loadedProjects.add(project.name);
+          loadedProjects.add(project.projectId);
         }
       });
       setInitialSessionsLoaded(loadedProjects);
@@ -186,17 +217,131 @@ export function useSidebarController({
     };
   }, []);
 
+  useEffect(() => {
+    onRefreshRef.current = onRefresh;
+  }, [onRefresh]);
+
+  const fetchArchivedSessions = useCallback(async () => {
+    setIsArchivedSessionsLoading(true);
+
+    try {
+      const [archivedProjectsResponse, archivedSessionsResponse] = await Promise.all([
+        api.archivedProjects(),
+        api.getArchivedSessions(),
+      ]);
+
+      if (!archivedProjectsResponse.ok) {
+        throw new Error(`Failed to load archived projects: ${archivedProjectsResponse.status}`);
+      }
+
+      if (!archivedSessionsResponse.ok) {
+        throw new Error(`Failed to load archived sessions: ${archivedSessionsResponse.status}`);
+      }
+
+      const archivedProjectsPayload = (await archivedProjectsResponse.json()) as ArchivedProjectsApiPayload;
+      const archivedSessionsPayload = (await archivedSessionsResponse.json()) as ArchivedSessionsApiPayload;
+      const nextProjects = Array.isArray(archivedProjectsPayload.data?.projects) ? archivedProjectsPayload.data.projects : [];
+      const archivedProjectIds = new Set(nextProjects.map((project) => project.projectId));
+      const nextStandaloneSessions = Array.isArray(archivedSessionsPayload.data?.sessions)
+        ? archivedSessionsPayload.data.sessions.filter((session) => !session.projectId || !archivedProjectIds.has(session.projectId))
+        : [];
+
+      setArchivedProjects(nextProjects);
+      setArchivedSessions(nextStandaloneSessions);
+    } catch (error) {
+      console.error('[Sidebar] Failed to load archived sessions:', error);
+    } finally {
+      setIsArchivedSessionsLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (migrationStartedRef.current) {
+      return;
+    }
+
+    const legacyStarredProjectIds = readLegacyStarredProjectIds();
+    if (legacyStarredProjectIds.length === 0) {
+      return;
+    }
+
+    migrationStartedRef.current = true;
+
+    const migrateLegacyStars = async () => {
+      try {
+        await api.migrateLegacyProjectStars(legacyStarredProjectIds);
+        await onRefreshRef.current();
+      } catch (error) {
+        console.error('[Sidebar] Failed to migrate legacy starred projects:', error);
+      } finally {
+        clearLegacyStarredProjectIds();
+      }
+    };
+
+    void migrateLegacyStars();
+  }, [onRefresh]);
+
+  useEffect(() => {
+    void fetchArchivedSessions();
+  }, [fetchArchivedSessions]);
+
+  useEffect(() => {
+    if (searchMode !== 'archived') {
+      return;
+    }
+
+    // Refresh archive contents when the archived tab opens so restore actions
+    // and background synchronizer updates are reflected without a full reload.
+    void fetchArchivedSessions();
+  }, [fetchArchivedSessions, searchMode]);
+
+  useEffect(() => {
+    setOptimisticStarByProjectId((previous) => {
+      if (previous.size === 0) {
+        return previous;
+      }
+
+      const next = new Map(previous);
+      let changed = false;
+
+      for (const [projectId, optimisticValue] of previous.entries()) {
+        const project = projects.find((candidate) => candidate.projectId === projectId);
+        if (!project) {
+          next.delete(projectId);
+          changed = true;
+          continue;
+        }
+
+        if (Boolean(project.isStarred) === optimisticValue) {
+          next.delete(projectId);
+          changed = true;
+        }
+      }
+
+      return changed ? next : previous;
+    });
+  }, [projects]);
+
+  // Debounce search text updates so both project filtering and conversation
+  // SSE requests avoid running on every keypress.
+  useEffect(() => {
+    const timeout = setTimeout(() => {
+      setDebouncedSearchQuery(searchFilter.trim());
+    }, 300);
+
+    return () => {
+      clearTimeout(timeout);
+    };
+  }, [searchFilter]);
+
   // Debounced conversation search with SSE streaming
   useEffect(() => {
-    if (searchTimeoutRef.current) {
-      clearTimeout(searchTimeoutRef.current);
-    }
     if (eventSourceRef.current) {
       eventSourceRef.current.close();
       eventSourceRef.current = null;
     }
 
-    const query = searchFilter.trim();
+    const query = debouncedSearchQuery;
     if (searchMode !== 'conversations' || query.length < 2) {
       searchSeqRef.current += 1;
       setConversationResults(null);
@@ -208,163 +353,294 @@ export function useSidebarController({
     setIsSearching(true);
     const seq = ++searchSeqRef.current;
 
-    searchTimeoutRef.current = setTimeout(() => {
-      if (seq !== searchSeqRef.current) return;
+    if (seq !== searchSeqRef.current) {
+      return;
+    }
 
-      const url = api.searchConversationsUrl(query);
-      const es = new EventSource(url);
-      eventSourceRef.current = es;
+    const url = api.searchConversationsUrl(query);
+    const es = new EventSource(url);
+    eventSourceRef.current = es;
 
-      const accumulated: ConversationProjectResult[] = [];
-      let totalMatches = 0;
+    const accumulated: ConversationProjectResult[] = [];
+    let totalMatches = 0;
 
-      es.addEventListener('result', (evt) => {
-        if (seq !== searchSeqRef.current) { es.close(); return; }
-        try {
-          const data = JSON.parse(evt.data) as {
-            projectResult: ConversationProjectResult;
-            totalMatches: number;
-            scannedProjects: number;
-            totalProjects: number;
-          };
-          accumulated.push(data.projectResult);
-          totalMatches = data.totalMatches;
-          setConversationResults({ results: [...accumulated], totalMatches, query });
-          setSearchProgress({ scannedProjects: data.scannedProjects, totalProjects: data.totalProjects });
-        } catch {
-          // Ignore malformed SSE data
-        }
-      });
+    es.addEventListener('result', (evt) => {
+      if (seq !== searchSeqRef.current) { es.close(); return; }
+      try {
+        const data = JSON.parse(evt.data) as {
+          projectResult: ConversationProjectResult;
+          totalMatches: number;
+          scannedProjects: number;
+          totalProjects: number;
+        };
+        accumulated.push(data.projectResult);
+        totalMatches = data.totalMatches;
+        setConversationResults({ results: [...accumulated], totalMatches, query });
+        setSearchProgress({ scannedProjects: data.scannedProjects, totalProjects: data.totalProjects });
+      } catch {
+        // Ignore malformed SSE data
+      }
+    });
 
-      es.addEventListener('progress', (evt) => {
-        if (seq !== searchSeqRef.current) { es.close(); return; }
-        try {
-          const data = JSON.parse(evt.data) as { totalMatches: number; scannedProjects: number; totalProjects: number };
-          totalMatches = data.totalMatches;
-          setSearchProgress({ scannedProjects: data.scannedProjects, totalProjects: data.totalProjects });
-        } catch {
-          // Ignore malformed SSE data
-        }
-      });
+    es.addEventListener('progress', (evt) => {
+      if (seq !== searchSeqRef.current) { es.close(); return; }
+      try {
+        const data = JSON.parse(evt.data) as { totalMatches: number; scannedProjects: number; totalProjects: number };
+        totalMatches = data.totalMatches;
+        setSearchProgress({ scannedProjects: data.scannedProjects, totalProjects: data.totalProjects });
+      } catch {
+        // Ignore malformed SSE data
+      }
+    });
 
-      es.addEventListener('done', () => {
-        if (seq !== searchSeqRef.current) { es.close(); return; }
-        es.close();
-        eventSourceRef.current = null;
-        setIsSearching(false);
-        setSearchProgress(null);
-        if (accumulated.length === 0) {
-          setConversationResults({ results: [], totalMatches: 0, query });
-        }
-      });
+    es.addEventListener('done', () => {
+      if (seq !== searchSeqRef.current) { es.close(); return; }
+      es.close();
+      eventSourceRef.current = null;
+      setIsSearching(false);
+      setSearchProgress(null);
+      if (accumulated.length === 0) {
+        setConversationResults({ results: [], totalMatches: 0, query });
+      }
+    });
 
-      es.addEventListener('error', () => {
-        if (seq !== searchSeqRef.current) { es.close(); return; }
-        es.close();
-        eventSourceRef.current = null;
-        setIsSearching(false);
-        setSearchProgress(null);
-        if (accumulated.length === 0) {
-          setConversationResults({ results: [], totalMatches: 0, query });
-        }
-      });
-    }, 400);
+    es.addEventListener('error', () => {
+      if (seq !== searchSeqRef.current) { es.close(); return; }
+      es.close();
+      eventSourceRef.current = null;
+      setIsSearching(false);
+      setSearchProgress(null);
+      if (accumulated.length === 0) {
+        setConversationResults({ results: [], totalMatches: 0, query });
+      }
+    });
 
     return () => {
-      if (searchTimeoutRef.current) {
-        clearTimeout(searchTimeoutRef.current);
-      }
       if (eventSourceRef.current) {
         eventSourceRef.current.close();
         eventSourceRef.current = null;
       }
     };
-  }, [searchFilter, searchMode]);
+  }, [debouncedSearchQuery, searchMode]);
 
-  const handleTouchClick = useCallback(
-    (callback: () => void) =>
-      (event: React.TouchEvent<HTMLElement>) => {
-        const target = event.target as HTMLElement;
-        if (target.closest('.overflow-y-auto') || target.closest('[data-scroll-container]')) {
-          return;
-        }
-
-        event.preventDefault();
-        event.stopPropagation();
-        callback();
-      },
-    [],
-  );
-
-  const toggleProject = useCallback((projectName: string) => {
+  // All sidebar state keys (expanded, starred, loading, etc.) use the DB
+  // `projectId` as their identifier after the migration.
+  const toggleProject = useCallback((projectId: string) => {
     setExpandedProjects((prev) => {
       const next = new Set<string>();
-      if (!prev.has(projectName)) {
-        next.add(projectName);
+      if (!prev.has(projectId)) {
+        next.add(projectId);
       }
       return next;
     });
   }, []);
 
   const handleSessionClick = useCallback(
-    (session: SessionWithProvider, projectName: string) => {
-      onSessionSelect({ ...session, __projectName: projectName });
+    (session: SessionWithProvider, projectId: string) => {
+      // Tag the session with its owning projectId so downstream handlers
+      // can correlate it with the selectedProject in the app state.
+      onSessionSelect({ ...session, __projectId: projectId });
     },
     [onSessionSelect],
   );
 
-  const toggleStarProject = useCallback((projectName: string) => {
-    setStarredProjects((prev) => {
-      const next = new Set(prev);
-      if (next.has(projectName)) {
-        next.delete(projectName);
-      } else {
-        next.add(projectName);
+  const resolveProjectStarState = useCallback(
+    (projectId: string): boolean => {
+      if (optimisticStarByProjectId.has(projectId)) {
+        return Boolean(optimisticStarByProjectId.get(projectId));
       }
 
-      persistStarredProjects(next);
+      return projects.some((project) => project.projectId === projectId && Boolean(project.isStarred));
+    },
+    [optimisticStarByProjectId, projects],
+  );
+
+  const toggleStarProject = useCallback((projectId: string) => {
+    const previousStarState = resolveProjectStarState(projectId);
+    const optimisticStarState = !previousStarState;
+    const latestSequence = (starToggleSequenceByProjectRef.current.get(projectId) ?? 0) + 1;
+    starToggleSequenceByProjectRef.current.set(projectId, latestSequence);
+
+    setOptimisticStarByProjectId((previous) => {
+      const next = new Map(previous);
+      next.set(projectId, optimisticStarState);
       return next;
     });
-  }, []);
 
-  const isProjectStarred = useCallback(
-    (projectName: string) => starredProjects.has(projectName),
-    [starredProjects],
-  );
-
-  const getProjectSessions = useCallback(
-    (project: Project) => getAllSessions(project, additionalSessions),
-    [additionalSessions],
-  );
-
-  const projectsWithSessionMeta = useMemo(
-    () =>
-      projects.map((project) => {
-        const hasMoreOverride = projectHasMoreOverrides[project.name];
-        if (hasMoreOverride === undefined) {
-          return project;
+    const updateStar = async () => {
+      try {
+        const response = await api.toggleProjectStar(projectId);
+        if (!response.ok) {
+          const payload = (await response.json()) as { error?: string | { message?: string } };
+          const errorPayload = payload.error;
+          const message =
+            typeof errorPayload === 'string'
+              ? errorPayload
+              : errorPayload && typeof errorPayload === 'object' && errorPayload.message
+                ? errorPayload.message
+                : t('messages.updateProjectError');
+          throw new Error(message);
         }
 
-        return {
-          ...project,
-          sessionMeta: { ...project.sessionMeta, hasMore: hasMoreOverride },
-        };
-      }),
-    [projectHasMoreOverrides, projects],
+        const payload = (await response.json()) as { isStarred?: boolean };
+        const isLatestSequence = starToggleSequenceByProjectRef.current.get(projectId) === latestSequence;
+        if (!isLatestSequence) {
+          return;
+        }
+
+        setOptimisticStarByProjectId((previous) => {
+          const next = new Map(previous);
+          next.set(projectId, Boolean(payload.isStarred));
+          return next;
+        });
+      } catch (error) {
+        const isLatestSequence = starToggleSequenceByProjectRef.current.get(projectId) === latestSequence;
+        if (!isLatestSequence) {
+          return;
+        }
+
+        setOptimisticStarByProjectId((previous) => {
+          const next = new Map(previous);
+          next.set(projectId, previousStarState);
+          return next;
+        });
+        console.error('[Sidebar] Failed to toggle project star:', error);
+        alert(t('messages.updateProjectError'));
+      }
+    };
+
+    void updateStar();
+  }, [resolveProjectStarState, t]);
+
+  const isProjectStarred = useCallback(
+    (projectId: string) => resolveProjectStarState(projectId),
+    [resolveProjectStarState],
   );
 
+  const getProjectSessions = useCallback((project: Project) => getAllSessions(project), []);
+
+  const loadMoreSessionsForProject = useCallback(async (projectId: string) => {
+    if (!onLoadMoreSessions) {
+      return;
+    }
+
+    let shouldLoad = false;
+    setLoadingMoreProjects((previous) => {
+      if (previous.has(projectId)) {
+        return previous;
+      }
+
+      shouldLoad = true;
+      const next = new Set(previous);
+      next.add(projectId);
+      return next;
+    });
+
+    if (!shouldLoad) {
+      return;
+    }
+
+    try {
+      await onLoadMoreSessions(projectId);
+    } catch (error) {
+      console.error('[Sidebar] Failed to load more sessions:', error);
+      alert(t('messages.refreshError'));
+    } finally {
+      setLoadingMoreProjects((previous) => {
+        const next = new Set(previous);
+        next.delete(projectId);
+        return next;
+      });
+    }
+  }, [onLoadMoreSessions, t]);
+
+  const projectsWithResolvedStarState = useMemo(() => {
+    if (optimisticStarByProjectId.size === 0) {
+      return projects;
+    }
+
+    return projects.map((project) => {
+      const optimisticStarState = optimisticStarByProjectId.get(project.projectId);
+      if (optimisticStarState === undefined) {
+        return project;
+      }
+
+      const currentStarState = Boolean(project.isStarred);
+      if (currentStarState === optimisticStarState) {
+        return project;
+      }
+
+      return {
+        ...project,
+        isStarred: optimisticStarState,
+      };
+    });
+  }, [optimisticStarByProjectId, projects]);
+
   const sortedProjects = useMemo(
-    () => sortProjects(projectsWithSessionMeta, projectSortOrder, starredProjects, additionalSessions),
-    [additionalSessions, projectSortOrder, projectsWithSessionMeta, starredProjects],
+    () => sortProjects(projectsWithResolvedStarState, projectSortOrder),
+    [projectSortOrder, projectsWithResolvedStarState],
   );
 
   const filteredProjects = useMemo(
-    () => filterProjects(sortedProjects, searchFilter),
-    [searchFilter, sortedProjects],
+    () => filterProjects(sortedProjects, debouncedSearchQuery),
+    [debouncedSearchQuery, sortedProjects],
   );
 
+  const filteredArchivedSessions = useMemo(() => {
+    const normalizedSearch = debouncedSearchQuery.trim().toLowerCase();
+    if (!normalizedSearch) {
+      return archivedSessions;
+    }
+
+    return archivedSessions.filter((session) => {
+      const searchableFields = [
+        session.sessionTitle,
+        session.projectDisplayName,
+        session.projectPath ?? '',
+        session.provider,
+      ];
+
+      return searchableFields.some((value) => value.toLowerCase().includes(normalizedSearch));
+    });
+  }, [archivedSessions, debouncedSearchQuery]);
+
+  const filteredArchivedProjects = useMemo(() => {
+    const normalizedSearch = debouncedSearchQuery.trim().toLowerCase();
+    if (!normalizedSearch) {
+      return archivedProjects;
+    }
+
+    return archivedProjects.filter((project) => {
+      const projectMatches = [
+        project.displayName,
+        project.fullPath || '',
+      ].some((value) => value.toLowerCase().includes(normalizedSearch));
+
+      if (projectMatches) {
+        return true;
+      }
+
+      return getAllSessions(project).some((session) => {
+        const sessionSummary =
+          typeof session.summary === 'string' && session.summary.trim().length > 0
+            ? session.summary
+            : typeof session.name === 'string'
+              ? session.name
+              : '';
+
+        return [
+          sessionSummary,
+          session.__provider,
+        ].some((value) => value.toLowerCase().includes(normalizedSearch));
+      });
+    });
+  }, [archivedProjects, debouncedSearchQuery]);
+
   const startEditing = useCallback((project: Project) => {
-    setEditingProject(project.name);
+    // `editingProject` is keyed by projectId so it stays stable across
+    // display-name mutations that happen while the input is open.
+    setEditingProject(project.projectId);
     setEditingName(project.displayName);
   }, []);
 
@@ -374,15 +650,13 @@ export function useSidebarController({
   }, []);
 
   const saveProjectName = useCallback(
-    async (projectName: string) => {
+    // `projectId` is the DB primary key; the rename API resolves the path
+    // through the `projects` table before writing the new display name.
+    async (projectId: string) => {
       try {
-        const response = await api.renameProject(projectName, editingName);
+        const response = await api.renameProject(projectId, editingName);
         if (response.ok) {
-          if (window.refreshProjects) {
-            await window.refreshProjects();
-          } else {
-            window.location.reload();
-          }
+          await paletteOps.refreshProjects();
         } else {
           console.error('Failed to rename project');
         }
@@ -393,41 +667,46 @@ export function useSidebarController({
         setEditingName('');
       }
     },
-    [editingName],
+    [editingName, paletteOps],
   );
 
   const showDeleteSessionConfirmation = useCallback(
+    // Kept with project/provider arguments for component wiring compatibility;
+    // deletion now uses only `sessionId` via /api/providers/sessions/:sessionId.
     (
-      projectName: string,
+      projectId: string | null,
       sessionId: string,
       sessionTitle: string,
       provider: SessionDeleteConfirmation['provider'] = 'claude',
+      options: {
+        isArchived?: boolean;
+      } = {},
     ) => {
-      setSessionDeleteConfirmation({ projectName, sessionId, sessionTitle, provider });
+      setSessionDeleteConfirmation({
+        projectId,
+        sessionId,
+        sessionTitle,
+        provider,
+        isArchived: Boolean(options.isArchived),
+      });
     },
     [],
   );
 
-  const confirmDeleteSession = useCallback(async () => {
+  const confirmDeleteSession = useCallback(async (hardDelete = false) => {
     if (!sessionDeleteConfirmation) {
       return;
     }
 
-    const { projectName, sessionId, provider } = sessionDeleteConfirmation;
+    const { sessionId } = sessionDeleteConfirmation;
     setSessionDeleteConfirmation(null);
 
     try {
-      let response;
-      if (provider === 'codex') {
-        response = await api.deleteCodexSession(sessionId);
-      } else if (provider === 'gemini') {
-        response = await api.deleteGeminiSession(sessionId);
-      } else {
-        response = await api.deleteSession(projectName, sessionId);
-      }
+      const response = await api.deleteSession(sessionId, hardDelete);
 
       if (response.ok) {
         onSessionDelete?.(sessionId);
+        await fetchArchivedSessions();
       } else {
         const errorText = await response.text();
         console.error('[Sidebar] Failed to delete session:', {
@@ -440,7 +719,7 @@ export function useSidebarController({
       console.error('[Sidebar] Error deleting session:', error);
       alert(t('messages.deleteSessionError'));
     }
-  }, [onSessionDelete, sessionDeleteConfirmation, t]);
+  }, [fetchArchivedSessions, onSessionDelete, sessionDeleteConfirmation, t]);
 
   const requestProjectDelete = useCallback(
     (project: Project) => {
@@ -457,20 +736,24 @@ export function useSidebarController({
       return;
     }
 
-    const { project, sessionCount } = deleteConfirmation;
-    const isEmpty = sessionCount === 0;
+    const { project } = deleteConfirmation;
 
     setDeleteConfirmation(null);
-    setDeletingProjects((prev) => new Set([...prev, project.name]));
+    // Track in-flight deletes by projectId so the UI can disable actions
+    // even if the project object is rebuilt while the request is flying.
+    setDeletingProjects((prev) => new Set([...prev, project.projectId]));
 
     try {
-      const response = await api.deleteProject(project.name, !isEmpty, deleteData);
+      const response = await api.deleteProject(project.projectId, deleteData);
 
       if (response.ok) {
-        onProjectDelete?.(project.name);
+        onProjectDelete?.(project.projectId);
       } else {
-        const error = (await response.json()) as { error?: string };
-        alert(error.error || t('messages.deleteProjectFailed'));
+        const data = (await response.json()) as { error?: string | { message?: string } };
+        const err = data.error;
+        const message =
+          typeof err === 'string' ? err : err && typeof err === 'object' && err.message ? err.message : t('messages.deleteProjectFailed');
+        alert(message);
       }
     } catch (error) {
       console.error('Error deleting project:', error);
@@ -478,55 +761,12 @@ export function useSidebarController({
     } finally {
       setDeletingProjects((prev) => {
         const next = new Set(prev);
-        next.delete(project.name);
+        next.delete(project.projectId);
         return next;
       });
     }
   }, [deleteConfirmation, onProjectDelete, t]);
 
-  const loadMoreSessions = useCallback(
-    async (project: Project) => {
-      const hasMoreOverride = projectHasMoreOverrides[project.name];
-      const canLoadMore =
-        hasMoreOverride !== undefined ? hasMoreOverride : project.sessionMeta?.hasMore === true;
-      if (!canLoadMore || loadingSessions[project.name]) {
-        return;
-      }
-
-      setLoadingSessions((prev) => ({ ...prev, [project.name]: true }));
-
-      try {
-        const currentSessionCount =
-          (project.sessions?.length || 0) + (additionalSessions[project.name]?.length || 0);
-        const response = await api.sessions(project.name, 5, currentSessionCount);
-
-        if (!response.ok) {
-          return;
-        }
-
-        const result = (await response.json()) as {
-          sessions?: ProjectSession[];
-          hasMore?: boolean;
-        };
-
-        setAdditionalSessions((prev) => ({
-          ...prev,
-          [project.name]: [...(prev[project.name] || []), ...(result.sessions || [])],
-        }));
-
-        if (result.hasMore === false) {
-          // Keep hasMore state in local hook state instead of mutating the project prop object.
-          setProjectHasMoreOverrides((prev) => ({ ...prev, [project.name]: false }));
-        }
-      } catch (error) {
-        console.error('Error loading more sessions:', error);
-      } finally {
-        setLoadingSessions((prev) => ({ ...prev, [project.name]: false }));
-      }
-    },
-    [additionalSessions, loadingSessions, projectHasMoreOverrides],
-  );
-
   const handleProjectSelect = useCallback(
     (project: Project) => {
       onProjectSelect(project);
@@ -535,17 +775,93 @@ export function useSidebarController({
     [onProjectSelect, setCurrentProject],
   );
 
+  const openArchivedSession = useCallback((session: ArchivedSessionListItem) => {
+    const activeProject = session.projectId
+      ? projects.find((candidate) => candidate.projectId === session.projectId)
+      : null;
+    const archivedProject = session.projectId
+      ? archivedProjects.find((candidate) => candidate.projectId === session.projectId)
+      : null;
+    const matchingProject = activeProject ?? archivedProject ?? null;
+    const sessionPayload: ProjectSession = {
+      id: session.sessionId,
+      summary: session.sessionTitle,
+      __provider: session.provider,
+      __projectId: matchingProject?.projectId ?? session.projectId ?? undefined,
+    };
+
+    // Archived sessions still need a selected project context. Active projects
+    // come from the normal sidebar list, while archived-project sessions resolve
+    // through the archive payload loaded by this controller.
+    if (matchingProject) {
+      handleProjectSelect(matchingProject);
+    }
+
+    onSessionSelect(sessionPayload);
+  }, [archivedProjects, handleProjectSelect, onSessionSelect, projects]);
+
+  const restoreArchivedProject = useCallback(async (projectId: string) => {
+    try {
+      const response = await api.restoreProject(projectId);
+      if (!response.ok) {
+        const errorText = await response.text();
+        console.error('[Sidebar] Failed to restore project:', {
+          status: response.status,
+          error: errorText,
+        });
+        alert(t('messages.restoreProjectFailed', 'Failed to restore project. Please try again.'));
+        return;
+      }
+
+      await Promise.all([
+        Promise.resolve(onRefresh()),
+        fetchArchivedSessions(),
+      ]);
+    } catch (error) {
+      console.error('[Sidebar] Error restoring project:', error);
+      alert(t('messages.restoreProjectError', 'Error restoring project. Please try again.'));
+    }
+  }, [fetchArchivedSessions, onRefresh, t]);
+
+  const restoreArchivedSession = useCallback(async (sessionId: string) => {
+    try {
+      const response = await api.restoreSession(sessionId);
+      if (!response.ok) {
+        const errorText = await response.text();
+        console.error('[Sidebar] Failed to restore session:', {
+          status: response.status,
+          error: errorText,
+        });
+        alert(t('messages.restoreSessionFailed', 'Failed to restore session. Please try again.'));
+        return;
+      }
+
+      await Promise.all([
+        Promise.resolve(onRefresh()),
+        fetchArchivedSessions(),
+      ]);
+    } catch (error) {
+      console.error('[Sidebar] Error restoring session:', error);
+      alert(t('messages.restoreSessionError', 'Error restoring session. Please try again.'));
+    }
+  }, [fetchArchivedSessions, onRefresh, t]);
+
   const refreshProjects = useCallback(async () => {
     setIsRefreshing(true);
     try {
-      await onRefresh();
+      await Promise.all([
+        Promise.resolve(onRefresh()),
+        fetchArchivedSessions(),
+      ]);
     } finally {
       setIsRefreshing(false);
     }
-  }, [onRefresh]);
+  }, [fetchArchivedSessions, onRefresh]);
 
   const updateSessionSummary = useCallback(
-    async (_projectName: string, sessionId: string, summary: string, provider: LLMProvider) => {
+    // `_projectId` and `_provider` are preserved for compatibility with
+    // existing sidebar callback signatures; backend rename only needs sessionId.
+    async (_projectId: string, sessionId: string, summary: string, _provider: LLMProvider) => {
       const trimmed = summary.trim();
       if (!trimmed) {
         setEditingSession(null);
@@ -553,7 +869,7 @@ export function useSidebarController({
         return;
       }
       try {
-        const response = await api.renameSession(sessionId, trimmed, provider);
+        const response = await api.renameSession(sessionId, trimmed);
         if (response.ok) {
           await onRefresh();
         } else {
@@ -585,8 +901,6 @@ export function useSidebarController({
     editingProject,
     showNewProject,
     editingName,
-    loadingSessions,
-    additionalSessions,
     initialSessionsLoaded,
     currentTime,
     projectSortOrder,
@@ -595,16 +909,21 @@ export function useSidebarController({
     editingSessionName,
     searchFilter,
     deletingProjects,
+    loadingMoreProjects,
     deleteConfirmation,
     sessionDeleteConfirmation,
     showVersionModal,
-    starredProjects,
     filteredProjects,
+    archivedProjects: filteredArchivedProjects,
+    archivedSessions: filteredArchivedSessions,
+    archivedSessionsCount: archivedProjects.length + archivedSessions.length,
+    isArchivedSessionsLoading,
     toggleProject,
     handleSessionClick,
     toggleStarProject,
     isProjectStarred,
     getProjectSessions,
+    loadMoreSessionsForProject,
     startEditing,
     cancelEditing,
     saveProjectName,
@@ -612,8 +931,10 @@ export function useSidebarController({
     confirmDeleteSession,
     requestProjectDelete,
     confirmDeleteProject,
-    loadMoreSessions,
     handleProjectSelect,
+    openArchivedSession,
+    restoreArchivedProject,
+    restoreArchivedSession,
     refreshProjects,
     updateSessionSummary,
     collapseSidebar,
diff --git a/src/components/sidebar/types/types.ts b/src/components/sidebar/types/types.ts
index 9154717e..f8c31be2 100644
--- a/src/components/sidebar/types/types.ts
+++ b/src/components/sidebar/types/types.ts
@@ -1,24 +1,39 @@
 import type { LoadingProgress, Project, ProjectSession, LLMProvider } from '../../../types/app';
 
 export type ProjectSortOrder = 'name' | 'date';
+export type SidebarSearchMode = 'projects' | 'conversations' | 'archived';
+export type ArchivedProjectListItem = Project & { isArchived: true };
 
 export type SessionWithProvider = ProjectSession & {
   __provider: LLMProvider;
 };
 
-export type AdditionalSessionsByProject = Record<string, ProjectSession[]>;
-export type LoadingSessionsByProject = Record<string, boolean>;
+export type ArchivedSessionListItem = {
+  sessionId: string;
+  provider: LLMProvider;
+  projectId: string | null;
+  projectPath: string | null;
+  projectDisplayName: string;
+  sessionTitle: string;
+  createdAt: string | null;
+  updatedAt: string | null;
+  lastActivity: string | null;
+  isProjectArchived: boolean;
+};
 
 export type DeleteProjectConfirmation = {
   project: Project;
   sessionCount: number;
 };
 
+// Delete confirmation payload used by sidebar UX. `projectId`/`provider` are
+// kept for wiring compatibility, while API deletion now keys only by sessionId.
 export type SessionDeleteConfirmation = {
-  projectName: string;
+  projectId: string | null;
   sessionId: string;
   sessionTitle: string;
   provider: LLMProvider;
+  isArchived: boolean;
 };
 
 export type SidebarProps = {
@@ -29,7 +44,10 @@ export type SidebarProps = {
   onSessionSelect: (session: ProjectSession) => void;
   onNewSession: (project: Project) => void;
   onSessionDelete?: (sessionId: string) => void;
-  onProjectDelete?: (projectName: string) => void;
+  onLoadMoreSessions?: (projectId: string) => Promise<void> | void;
+  // `projectId` is the DB identifier; the sidebar hands it back to the parent
+  // when the delete flow completes.
+  onProjectDelete?: (projectId: string) => void;
   isLoading: boolean;
   loadingProgress: LoadingProgress | null;
   onRefresh: () => Promise<void> | void;
@@ -44,6 +62,7 @@ export type SessionViewModel = {
   isCursorSession: boolean;
   isCodexSession: boolean;
   isGeminiSession: boolean;
+  isOpenCodeSession: boolean;
   isActive: boolean;
   sessionName: string;
   sessionTime: string;
@@ -55,4 +74,11 @@ export type MCPServerStatus = {
   isConfigured?: boolean;
 } | null;
 
-export type SettingsProject = Pick<Project, 'name' | 'displayName' | 'fullPath' | 'path'>;
+// Retained as `name` for backwards compatibility with existing settings
+// consumers; the value is populated from `projectId` by normalizeProjectForSettings.
+export type SettingsProject = {
+  name: string;
+  displayName: string;
+  fullPath: string;
+  path?: string;
+};
diff --git a/src/components/sidebar/utils/utils.ts b/src/components/sidebar/utils/utils.ts
index a3ec377c..57e28b1d 100644
--- a/src/components/sidebar/utils/utils.ts
+++ b/src/components/sidebar/utils/utils.ts
@@ -1,12 +1,7 @@
 import type { TFunction } from 'i18next';
+
 import type { Project } from '../../../types/app';
-import type {
-  AdditionalSessionsByProject,
-  ProjectSortOrder,
-  SettingsProject,
-  SessionViewModel,
-  SessionWithProvider,
-} from '../types/types';
+import type { ProjectSortOrder, SettingsProject, SessionViewModel, SessionWithProvider } from '../types/types';
 
 export const readProjectSortOrder = (): ProjectSortOrder => {
   try {
@@ -22,61 +17,60 @@ export const readProjectSortOrder = (): ProjectSortOrder => {
   }
 };
 
-export const loadStarredProjects = (): Set<string> => {
+const LEGACY_STARRED_PROJECTS_STORAGE_KEY = 'starredProjects';
+
+/**
+ * Reads legacy project stars from localStorage (used only for one-time migration to backend).
+ */
+export const readLegacyStarredProjectIds = (): string[] => {
   try {
-    const saved = localStorage.getItem('starredProjects');
-    return saved ? new Set<string>(JSON.parse(saved)) : new Set<string>();
+    const saved = localStorage.getItem(LEGACY_STARRED_PROJECTS_STORAGE_KEY);
+    if (!saved) {
+      return [];
+    }
+
+    const parsed = JSON.parse(saved) as unknown;
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+
+    return parsed
+      .map((value) => String(value).trim())
+      .filter((value) => value.length > 0);
   } catch {
-    return new Set<string>();
+    return [];
   }
 };
 
-export const persistStarredProjects = (starredProjects: Set<string>) => {
+/**
+ * Clears the legacy localStorage stars key after migration to backend completes.
+ */
+export const clearLegacyStarredProjectIds = () => {
   try {
-    localStorage.setItem('starredProjects', JSON.stringify([...starredProjects]));
+    localStorage.removeItem(LEGACY_STARRED_PROJECTS_STORAGE_KEY);
   } catch {
-    // Keep UI responsive even if storage fails.
+    // Keep UI responsive even if storage is unavailable.
   }
 };
 
+const getCreatedTimestamp = (session: SessionWithProvider): string => {
+  return String(session.createdAt || session.created_at || '');
+};
+
+const getUpdatedTimestamp = (session: SessionWithProvider): string => {
+  return String(session.lastActivity || '');
+};
+
 export const getSessionDate = (session: SessionWithProvider): Date => {
-  if (session.__provider === 'cursor') {
-    return new Date(session.createdAt || 0);
-  }
-
-  if (session.__provider === 'codex') {
-    return new Date(session.createdAt || session.lastActivity || 0);
-  }
-
-  return new Date(session.lastActivity || session.createdAt || 0);
+  return new Date(getUpdatedTimestamp(session) || getCreatedTimestamp(session) || 0);
 };
 
 export const getSessionName = (session: SessionWithProvider, t: TFunction): string => {
-  if (session.__provider === 'cursor') {
-    return session.summary || session.name || t('projects.untitledSession');
-  }
-
-  if (session.__provider === 'codex') {
-    return session.summary || session.name || t('projects.codexSession');
-  }
-
-  if (session.__provider === 'gemini') {
-    return session.summary || session.name || t('projects.newSession');
-  }
-
-  return session.summary || t('projects.newSession');
+  return session.summary || session.name || t('projects.newSession');
 };
 
 export const getSessionTime = (session: SessionWithProvider): string => {
-  if (session.__provider === 'cursor') {
-    return String(session.createdAt || '');
-  }
-
-  if (session.__provider === 'codex') {
-    return String(session.createdAt || session.lastActivity || '');
-  }
-
-  return String(session.lastActivity || session.createdAt || '');
+  return getUpdatedTimestamp(session) || getCreatedTimestamp(session);
 };
 
 export const createSessionViewModel = (
@@ -91,6 +85,7 @@ export const createSessionViewModel = (
     isCursorSession: session.__provider === 'cursor',
     isCodexSession: session.__provider === 'codex',
     isGeminiSession: session.__provider === 'gemini',
+    isOpenCodeSession: session.__provider === 'opencode',
     isActive: diffInMinutes < 10,
     sessionName: getSessionName(session, t),
     sessionTime: getSessionTime(session),
@@ -98,14 +93,11 @@ export const createSessionViewModel = (
   };
 };
 
-export const getAllSessions = (
-  project: Project,
-  additionalSessions: AdditionalSessionsByProject,
-): SessionWithProvider[] => {
-  const claudeSessions = [
-    ...(project.sessions || []),
-    ...(additionalSessions[project.name] || []),
-  ].map((session) => ({ ...session, __provider: 'claude' as const }));
+export const getAllSessions = (project: Project): SessionWithProvider[] => {
+  const claudeSessions = [...(project.sessions || [])].map((session) => ({
+    ...session,
+    __provider: 'claude' as const,
+  }));
 
   const cursorSessions = (project.cursorSessions || []).map((session) => ({
     ...session,
@@ -122,16 +114,18 @@ export const getAllSessions = (
     __provider: 'gemini' as const,
   }));
 
-  return [...claudeSessions, ...cursorSessions, ...codexSessions, ...geminiSessions].sort(
+  const opencodeSessions = (project.opencodeSessions || []).map((session) => ({
+    ...session,
+    __provider: 'opencode' as const,
+  }));
+
+  return [...claudeSessions, ...cursorSessions, ...codexSessions, ...geminiSessions, ...opencodeSessions].sort(
     (a, b) => getSessionDate(b).getTime() - getSessionDate(a).getTime(),
   );
 };
 
-export const getProjectLastActivity = (
-  project: Project,
-  additionalSessions: AdditionalSessionsByProject,
-): Date => {
-  const sessions = getAllSessions(project, additionalSessions);
+export const getProjectLastActivity = (project: Project): Date => {
+  const sessions = getAllSessions(project);
   if (sessions.length === 0) {
     return new Date(0);
   }
@@ -145,14 +139,13 @@ export const getProjectLastActivity = (
 export const sortProjects = (
   projects: Project[],
   projectSortOrder: ProjectSortOrder,
-  starredProjects: Set<string>,
-  additionalSessions: AdditionalSessionsByProject,
 ): Project[] => {
   const byName = [...projects];
 
   byName.sort((projectA, projectB) => {
-    const aStarred = starredProjects.has(projectA.name);
-    const bStarred = starredProjects.has(projectB.name);
+    // Star order now comes from backend `projects.isStarred`.
+    const aStarred = Boolean(projectA.isStarred);
+    const bStarred = Boolean(projectB.isStarred);
 
     if (aStarred && !bStarred) {
       return -1;
@@ -163,13 +156,10 @@ export const sortProjects = (
     }
 
     if (projectSortOrder === 'date') {
-      return (
-        getProjectLastActivity(projectB, additionalSessions).getTime() -
-        getProjectLastActivity(projectA, additionalSessions).getTime()
-      );
+      return getProjectLastActivity(projectB).getTime() - getProjectLastActivity(projectA).getTime();
     }
 
-    return (projectA.displayName || projectA.name).localeCompare(projectB.displayName || projectB.name);
+    return (projectA.displayName || projectA.projectId).localeCompare(projectB.displayName || projectB.projectId);
   });
 
   return byName;
@@ -182,9 +172,11 @@ export const filterProjects = (projects: Project[], searchFilter: string): Proje
   }
 
   return projects.filter((project) => {
-    const displayName = (project.displayName || project.name).toLowerCase();
-    const projectName = project.name.toLowerCase();
-    return displayName.includes(normalizedSearch) || projectName.includes(normalizedSearch);
+    const displayName = (project.displayName || project.projectId).toLowerCase();
+    // `project.path`/`fullPath` is the most useful search target now that the
+    // folder-derived name is gone; fall back to displayName above.
+    const searchPath = (project.path || project.fullPath || '').toLowerCase();
+    return displayName.includes(normalizedSearch) || searchPath.includes(normalizedSearch);
   });
 };
 
@@ -218,12 +210,14 @@ export const normalizeProjectForSettings = (project: Project): SettingsProject =
         ? project.path
         : '';
 
+  // Legacy SettingsProject still expects a `name` field; use the projectId so
+  // downstream consumers that rely on a stable identifier continue to work.
   return {
-    name: project.name,
+    name: project.projectId,
     displayName:
       typeof project.displayName === 'string' && project.displayName.trim().length > 0
         ? project.displayName
-        : project.name,
+        : project.projectId,
     fullPath: fallbackPath,
     path:
       typeof project.path === 'string' && project.path.length > 0
diff --git a/src/components/sidebar/view/Sidebar.tsx b/src/components/sidebar/view/Sidebar.tsx
index 0d6c9061..ebc046c5 100644
--- a/src/components/sidebar/view/Sidebar.tsx
+++ b/src/components/sidebar/view/Sidebar.tsx
@@ -1,13 +1,16 @@
 import { useEffect } from 'react';
 import { useTranslation } from 'react-i18next';
+
 import { useDeviceSettings } from '../../../hooks/useDeviceSettings';
 import { useVersionCheck } from '../../../hooks/useVersionCheck';
 import { useUiPreferences } from '../../../hooks/useUiPreferences';
 import { useSidebarController } from '../hooks/useSidebarController';
 import { useTaskMaster } from '../../../contexts/TaskMasterContext';
+import { usePaletteOps } from '../../../contexts/PaletteOpsContext';
 import { useTasksSettings } from '../../../contexts/TasksSettingsContext';
 import type { Project, LLMProvider } from '../../../types/app';
 import type { MCPServerStatus, SidebarProps } from '../types/types';
+
 import SidebarCollapsed from './subcomponents/SidebarCollapsed';
 import SidebarContent from './subcomponents/SidebarContent';
 import SidebarModals from './subcomponents/SidebarModals';
@@ -26,6 +29,7 @@ function Sidebar({
   onSessionSelect,
   onNewSession,
   onSessionDelete,
+  onLoadMoreSessions,
   onProjectDelete,
   isLoading,
   loadingProgress,
@@ -46,6 +50,7 @@ function Sidebar({
   const { sidebarVisible } = preferences;
   const { setCurrentProject, mcpServerStatus } = useTaskMaster() as TaskMasterSidebarContext;
   const { tasksEnabled } = useTasksSettings();
+  const paletteOps = usePaletteOps();
 
   const {
     isSidebarCollapsed,
@@ -53,7 +58,6 @@ function Sidebar({
     editingProject,
     showNewProject,
     editingName,
-    loadingSessions,
     initialSessionsLoaded,
     currentTime,
     isRefreshing,
@@ -71,11 +75,17 @@ function Sidebar({
     sessionDeleteConfirmation,
     showVersionModal,
     filteredProjects,
+    archivedProjects,
+    archivedSessions,
+    archivedSessionsCount,
+    isArchivedSessionsLoading,
     toggleProject,
     handleSessionClick,
     toggleStarProject,
     isProjectStarred,
     getProjectSessions,
+    loadingMoreProjects,
+    loadMoreSessionsForProject,
     startEditing,
     cancelEditing,
     saveProjectName,
@@ -83,8 +93,10 @@ function Sidebar({
     confirmDeleteSession,
     requestProjectDelete,
     confirmDeleteProject,
-    loadMoreSessions,
     handleProjectSelect,
+    openArchivedSession,
+    restoreArchivedProject,
+    restoreArchivedSession,
     refreshProjects,
     updateSessionSummary,
     collapseSidebar: handleCollapseSidebar,
@@ -108,6 +120,7 @@ function Sidebar({
     onProjectSelect,
     onSessionSelect,
     onSessionDelete,
+    onLoadMoreSessions,
     onProjectDelete,
     setCurrentProject,
     setSidebarVisible: (visible) => setPreference('sidebarVisible', visible),
@@ -124,12 +137,7 @@ function Sidebar({
   }, [isPWA]);
 
   const handleProjectCreated = () => {
-    if (window.refreshProjects) {
-      void window.refreshProjects();
-      return;
-    }
-
-    window.location.reload();
+    void paletteOps.refreshProjects();
   };
 
   const projectListProps: SidebarProjectListProps = {
@@ -142,7 +150,6 @@ function Sidebar({
     expandedProjects,
     editingProject,
     editingName,
-    loadingSessions,
     initialSessionsLoaded,
     currentTime,
     editingSession,
@@ -151,6 +158,7 @@ function Sidebar({
     tasksEnabled,
     mcpServerStatus,
     getProjectSessions,
+    loadingMoreProjects,
     isProjectStarred,
     onEditingNameChange: setEditingName,
     onToggleProject: toggleProject,
@@ -164,9 +172,7 @@ function Sidebar({
     onDeleteProject: requestProjectDelete,
     onSessionSelect: handleSessionClick,
     onDeleteSession: showDeleteSessionConfirmation,
-    onLoadMoreSessions: (project) => {
-      void loadMoreSessions(project);
-    },
+    onLoadMoreSessions: loadMoreSessionsForProject,
     onNewSession,
     onEditingSessionNameChange: setEditingSessionName,
     onStartEditingSession: (sessionId, initialName) => {
@@ -185,8 +191,8 @@ function Sidebar({
 
   return (
     <>
-      <SidebarModals
-        projects={projects}
+        <SidebarModals
+          projects={projects}
         showSettings={showSettings}
         settingsInitialTab={settingsInitialTab}
         onCloseSettings={onCloseSettings}
@@ -218,30 +224,50 @@ function Sidebar({
         />
       ) : (
         <>
-          <SidebarContent
+        <SidebarContent
             isPWA={isPWA}
             isMobile={isMobile}
             isLoading={isLoading}
             projects={projects}
+            archivedProjects={archivedProjects}
+            archivedSessions={archivedSessions}
+            archivedSessionsCount={archivedSessionsCount}
+            isArchivedSessionsLoading={isArchivedSessionsLoading}
             searchFilter={searchFilter}
             onSearchFilterChange={setSearchFilter}
             onClearSearchFilter={() => setSearchFilter('')}
             searchMode={searchMode}
-            onSearchModeChange={(mode: 'projects' | 'conversations') => {
+            onSearchModeChange={(mode) => {
               setSearchMode(mode);
               if (mode === 'projects') clearConversationResults();
             }}
             conversationResults={conversationResults}
             isSearching={isSearching}
             searchProgress={searchProgress}
-            onConversationResultClick={(projectName: string, sessionId: string, provider: string, messageTimestamp?: string | null, messageSnippet?: string | null) => {
+            onRestoreArchivedProject={restoreArchivedProject}
+            onArchivedSessionClick={openArchivedSession}
+            onRestoreArchivedSession={restoreArchivedSession}
+            onDeleteArchivedSession={(session) => {
+              showDeleteSessionConfirmation(
+                session.projectId,
+                session.sessionId,
+                session.sessionTitle,
+                session.provider,
+                { isArchived: true },
+              );
+            }}
+            onConversationResultClick={(projectId: string | null, sessionId: string, provider: string, messageTimestamp?: string | null, messageSnippet?: string | null) => {
+              // `projectId` (DB key) is the canonical identifier post-migration.
+              // The server emits null when it can't resolve a project row for
+              // the search hit; treat that as "no project" and still navigate
+              // to the session so the user can open it from the URL.
               const resolvedProvider = (provider || 'claude') as LLMProvider;
-              const project = projects.find(p => p.name === projectName);
+              const project = projectId ? projects.find(p => p.projectId === projectId) : null;
               const searchTarget = { __searchTargetTimestamp: messageTimestamp || null, __searchTargetSnippet: messageSnippet || null };
               const sessionObj = {
                 id: sessionId,
                 __provider: resolvedProvider,
-                __projectName: projectName,
+                __projectId: projectId ?? undefined,
                 ...searchTarget,
               };
               if (project) {
@@ -249,12 +275,12 @@ function Sidebar({
                 const sessions = getProjectSessions(project);
                 const existing = sessions.find(s => s.id === sessionId);
                 if (existing) {
-                  handleSessionClick({ ...existing, ...searchTarget }, projectName);
+                  handleSessionClick({ ...existing, ...searchTarget }, project.projectId);
                 } else {
-                  handleSessionClick(sessionObj, projectName);
+                  handleSessionClick(sessionObj, project.projectId);
                 }
               } else {
-                handleSessionClick(sessionObj, projectName);
+                handleSessionClick(sessionObj, projectId ?? '');
               }
             }}
             onRefresh={() => {
diff --git a/src/components/sidebar/view/subcomponents/SidebarContent.tsx b/src/components/sidebar/view/subcomponents/SidebarContent.tsx
index 250a04d8..5ce63b8b 100644
--- a/src/components/sidebar/view/subcomponents/SidebarContent.tsx
+++ b/src/components/sidebar/view/subcomponents/SidebarContent.tsx
@@ -1,15 +1,16 @@
 import { type ReactNode } from 'react';
-import { Folder, MessageSquare, Search } from 'lucide-react';
+import { Archive, Folder, MessageSquare, RotateCcw, Search, Trash2 } from 'lucide-react';
 import type { TFunction } from 'i18next';
 import { ScrollArea } from '../../../../shared/view/ui';
 import type { Project } from '../../../../types/app';
 import type { ReleaseInfo } from '../../../../types/sharedTypes';
 import type { ConversationSearchResults, SearchProgress } from '../../hooks/useSidebarController';
+import type { ArchivedProjectListItem, ArchivedSessionListItem, SidebarSearchMode } from '../../types/types';
+import SessionProviderLogo from '../../../llm-logo-provider/SessionProviderLogo';
 import SidebarFooter from './SidebarFooter';
 import SidebarHeader from './SidebarHeader';
 import SidebarProjectList, { type SidebarProjectListProps } from './SidebarProjectList';
-
-type SearchMode = 'projects' | 'conversations';
+import { getAllSessions } from '../../utils/utils';
 
 function HighlightedSnippet({ snippet, highlights }: { snippet: string; highlights: { start: number; end: number }[] }) {
   const parts: ReactNode[] = [];
@@ -35,20 +36,103 @@ function HighlightedSnippet({ snippet, highlights }: { snippet: string; highligh
   );
 }
 
+type ArchivedSessionGroup = {
+  key: string;
+  projectId: string | null;
+  projectDisplayName: string;
+  projectPath: string | null;
+  isProjectArchived: boolean;
+  sessions: ArchivedSessionListItem[];
+  latestActivity: string | null;
+};
+
+/**
+ * Groups archived sessions by project metadata so the archive view preserves
+ * the same mental model as the active sidebar: projects first, then sessions.
+ */
+function groupArchivedSessionsByProject(sessions: ArchivedSessionListItem[]): ArchivedSessionGroup[] {
+  const groups = new Map<string, ArchivedSessionGroup>();
+
+  for (const session of sessions) {
+    const key = session.projectId ?? session.projectPath ?? `session:${session.sessionId}`;
+    const existingGroup = groups.get(key);
+
+    if (existingGroup) {
+      existingGroup.sessions.push(session);
+      if (!existingGroup.latestActivity || (session.lastActivity && session.lastActivity > existingGroup.latestActivity)) {
+        existingGroup.latestActivity = session.lastActivity;
+      }
+      continue;
+    }
+
+    groups.set(key, {
+      key,
+      projectId: session.projectId,
+      projectDisplayName: session.projectDisplayName,
+      projectPath: session.projectPath,
+      isProjectArchived: session.isProjectArchived,
+      sessions: [session],
+      latestActivity: session.lastActivity,
+    });
+  }
+
+  return [...groups.values()].sort((groupA, groupB) => {
+    const a = groupA.latestActivity ?? '';
+    const b = groupB.latestActivity ?? '';
+    return b.localeCompare(a);
+  });
+}
+
+function formatCompactArchivedAge(dateString: string | null): string {
+  if (!dateString) {
+    return '';
+  }
+
+  const date = new Date(dateString);
+  if (Number.isNaN(date.getTime())) {
+    return '';
+  }
+
+  const diffInMinutes = Math.floor(Math.max(0, Date.now() - date.getTime()) / (1000 * 60));
+  if (diffInMinutes < 1) {
+    return '<1m';
+  }
+  if (diffInMinutes < 60) {
+    return `${diffInMinutes}m`;
+  }
+
+  const diffInHours = Math.floor(diffInMinutes / 60);
+  if (diffInHours < 24) {
+    return `${diffInHours}hr`;
+  }
+
+  return `${Math.floor(diffInHours / 24)}d`;
+}
+
 type SidebarContentProps = {
   isPWA: boolean;
   isMobile: boolean;
   isLoading: boolean;
   projects: Project[];
+  archivedProjects: ArchivedProjectListItem[];
+  archivedSessions: ArchivedSessionListItem[];
+  archivedSessionsCount: number;
+  isArchivedSessionsLoading: boolean;
   searchFilter: string;
   onSearchFilterChange: (value: string) => void;
   onClearSearchFilter: () => void;
-  searchMode: SearchMode;
-  onSearchModeChange: (mode: SearchMode) => void;
+  searchMode: SidebarSearchMode;
+  onSearchModeChange: (mode: SidebarSearchMode) => void;
   conversationResults: ConversationSearchResults | null;
   isSearching: boolean;
   searchProgress: SearchProgress | null;
-  onConversationResultClick: (projectName: string, sessionId: string, provider: string, messageTimestamp?: string | null, messageSnippet?: string | null) => void;
+  onRestoreArchivedProject: (projectId: string) => void;
+  onArchivedSessionClick: (session: ArchivedSessionListItem) => void;
+  onRestoreArchivedSession: (sessionId: string) => void;
+  onDeleteArchivedSession: (session: ArchivedSessionListItem) => void;
+  // Conversation result clicks pass back the DB projectId (or null when the
+  // server couldn't resolve it). Consumers must handle the null case.
+  onConversationResultClick: (projectId: string | null, sessionId: string, provider: string, messageTimestamp?: string | null, messageSnippet?: string | null) => void;
   onRefresh: () => void;
   isRefreshing: boolean;
   onCreateProject: () => void;
@@ -68,6 +152,10 @@ export default function SidebarContent({
   isMobile,
   isLoading,
   projects,
+  archivedProjects,
+  archivedSessions,
+  archivedSessionsCount,
+  isArchivedSessionsLoading,
   searchFilter,
   onSearchFilterChange,
   onClearSearchFilter,
@@ -76,6 +164,10 @@ export default function SidebarContent({
   conversationResults,
   isSearching,
   searchProgress,
+  onRestoreArchivedProject,
+  onArchivedSessionClick,
+  onRestoreArchivedSession,
+  onDeleteArchivedSession,
   onConversationResultClick,
   onRefresh,
   isRefreshing,
@@ -92,6 +184,7 @@ export default function SidebarContent({
 }: SidebarContentProps) {
   const showConversationSearch = searchMode === 'conversations' && searchFilter.trim().length >= 2;
   const hasPartialResults = conversationResults && conversationResults.results.length > 0;
+  const groupedArchivedSessions = groupArchivedSessionsByProject(archivedSessions);
 
   return (
     <div
@@ -103,6 +196,8 @@ export default function SidebarContent({
         isMobile={isMobile}
         isLoading={isLoading}
         projectsCount={projects.length}
+        archivedSessionsCount={archivedSessionsCount}
+        isArchivedSessionsLoading={isArchivedSessionsLoading}
         searchFilter={searchFilter}
         onSearchFilterChange={onSearchFilterChange}
         onClearSearchFilter={onClearSearchFilter}
@@ -170,10 +265,12 @@ export default function SidebarContent({
                   </div>
                   {projectResult.sessions.map((session) => (
                     <button
-                      key={`${projectResult.projectName}-${session.sessionId}`}
+                      key={`${projectResult.projectId ?? projectResult.projectName}-${session.sessionId}`}
                       className="w-full rounded-md px-2 py-2 text-left transition-colors hover:bg-accent/50"
                       onClick={() => onConversationResultClick(
-                        projectResult.projectName,
+                        // Pass the DB projectId (preferred) so the parent can
+                        // cross-reference with the loaded projects list.
+                        projectResult.projectId,
                         session.sessionId,
                         session.provider || session.matches[0]?.provider || 'claude',
                         session.matches[0]?.timestamp,
@@ -210,6 +307,207 @@ export default function SidebarContent({
               ))}
             </div>
           ) : null
+        ) : searchMode === 'archived' ? (
+          isArchivedSessionsLoading ? (
+            <div className="px-4 py-12 text-center md:py-8">
+              <div className="mx-auto mb-4 flex h-12 w-12 items-center justify-center rounded-lg bg-muted md:mb-3">
+                <div className="h-6 w-6 animate-spin rounded-full border-2 border-muted-foreground border-t-transparent" />
+              </div>
+              <h3 className="mb-2 text-base font-medium text-foreground md:mb-1">
+                {t('archived.loadingTitle', 'Loading archive...')}
+              </h3>
+              <p className="text-sm text-muted-foreground">
+                {t('archived.loadingDescription', 'Fetching hidden workspaces and sessions you can restore later.')}
+              </p>
+            </div>
+          ) : archivedProjects.length === 0 && groupedArchivedSessions.length === 0 ? (
+            <div className="px-4 py-12 text-center md:py-8">
+              <div className="mx-auto mb-4 flex h-12 w-12 items-center justify-center rounded-lg bg-muted md:mb-3">
+                <Archive className="h-6 w-6 text-muted-foreground" />
+              </div>
+              <h3 className="mb-2 text-base font-medium text-foreground md:mb-1">
+                {archivedSessionsCount > 0
+                  ? t('archived.noMatchingSessions', 'No matching archived items')
+                  : t('archived.emptyTitle', 'No archived items')}
+              </h3>
+              <p className="text-sm text-muted-foreground">
+                {archivedSessionsCount > 0
+                  ? t('archived.tryDifferentSearch', 'Try a different search term.')
+                  : t('archived.emptyDescription', 'Archived workspaces and sessions will appear here when you hide them from the active list.')}
+              </p>
+            </div>
+          ) : (
+            <div className="space-y-3 px-2">
+              <div className="flex items-center justify-between px-1">
+                <p className="text-xs text-muted-foreground">
+                  {`${archivedSessionsCount} ${t(
+                    archivedSessionsCount === 1 ? 'archived.sessionCountOne' : 'archived.sessionCountOther',
+                    archivedSessionsCount === 1 ? 'archived item' : 'archived items',
+                  )}`}
+                </p>
+              </div>
+              {archivedProjects.map((project) => {
+                const projectSessions = getAllSessions(project);
+
+                return (
+                  <div key={project.projectId} className="overflow-hidden rounded-xl border border-border/70 bg-card/60 shadow-sm">
+                    <div className="flex items-start justify-between gap-3 border-b border-border/60 px-3 py-2.5">
+                      <div className="min-w-0">
+                        <div className="flex items-center gap-2">
+                          <Folder className="h-3.5 w-3.5 flex-shrink-0 text-muted-foreground" />
+                          <span className="truncate text-sm font-medium text-foreground">
+                            {project.displayName}
+                          </span>
+                          <span className="inline-flex items-center justify-center rounded-full bg-muted px-1 py-px text-[7px] font-medium uppercase leading-none tracking-[0.02em] text-center text-muted-foreground">
+                            {t('archived.projectArchived', 'Project archived')}
+                          </span>
+                        </div>
+                        <p className="mt-1 truncate text-xs text-muted-foreground/70" title={project.fullPath}>
+                          {project.fullPath}
+                        </p>
+                      </div>
+                      <button
+                        className="flex h-7 w-7 flex-shrink-0 items-center justify-center rounded-lg bg-emerald-50 text-emerald-700 transition-colors hover:bg-emerald-100 dark:bg-emerald-900/20 dark:text-emerald-300 dark:hover:bg-emerald-900/30"
+                        onClick={() => onRestoreArchivedProject(project.projectId)}
+                        title={t('archived.restoreProject', 'Restore workspace')}
+                      >
+                        <RotateCcw className="h-3.5 w-3.5" />
+                      </button>
+                    </div>
+                    {projectSessions.length > 0 && (
+                      <div className="divide-y divide-border/50">
+                        {projectSessions.map((session) => (
+                          <button
+                            key={String(session.id)}
+                            className="flex w-full items-center gap-2 px-3 py-2.5 text-left transition-colors hover:bg-accent/40"
+                            onClick={() => onArchivedSessionClick({
+                              sessionId: String(session.id),
+                              provider: session.__provider,
+                              projectId: project.projectId,
+                              projectPath: project.fullPath,
+                              projectDisplayName: project.displayName,
+                              sessionTitle:
+                                (typeof session.summary === 'string' && session.summary.trim().length > 0
+                                  ? session.summary
+                                  : typeof session.name === 'string' && session.name.trim().length > 0
+                                    ? session.name
+                                    : String(session.id)),
+                              createdAt: typeof session.created_at === 'string' ? session.created_at : null,
+                              updatedAt: typeof session.updated_at === 'string' ? session.updated_at : null,
+                              lastActivity:
+                                typeof session.lastActivity === 'string'
+                                  ? session.lastActivity
+                                  : typeof session.updated_at === 'string'
+                                    ? session.updated_at
+                                    : typeof session.created_at === 'string'
+                                      ? session.created_at
+                                      : null,
+                              isProjectArchived: true,
+                            })}
+                          >
+                            <SessionProviderLogo provider={session.__provider} className="h-3.5 w-3.5 flex-shrink-0" />
+                            <div className="min-w-0 flex-1">
+                              <div className="flex items-center gap-2">
+                                <span className="truncate text-xs font-medium text-foreground">
+                                  {(typeof session.summary === 'string' && session.summary.trim().length > 0
+                                    ? session.summary
+                                    : typeof session.name === 'string' && session.name.trim().length > 0
+                                      ? session.name
+                                      : String(session.id))}
+                                </span>
+                                <span className="ml-auto flex-shrink-0 text-[11px] text-muted-foreground">
+                                  {formatCompactArchivedAge(
+                                    typeof session.lastActivity === 'string'
+                                      ? session.lastActivity
+                                      : typeof session.updated_at === 'string'
+                                        ? session.updated_at
+                                        : typeof session.created_at === 'string'
+                                          ? session.created_at
+                                          : null,
+                                  )}
+                                </span>
+                              </div>
+                              <p className="mt-0.5 text-[11px] uppercase tracking-wide text-muted-foreground/70">
+                                {session.__provider}
+                              </p>
+                            </div>
+                          </button>
+                        ))}
+                      </div>
+                    )}
+                  </div>
+                );
+              })}
+              {groupedArchivedSessions.map((group) => (
+                <div key={group.key} className="overflow-hidden rounded-xl border border-border/70 bg-card/60 shadow-sm">
+                  <div className="flex items-start justify-between gap-3 border-b border-border/60 px-3 py-2.5">
+                    <div className="min-w-0">
+                      <div className="flex items-center gap-2">
+                        <Folder className="h-3.5 w-3.5 flex-shrink-0 text-muted-foreground" />
+                        <span className="truncate text-sm font-medium text-foreground">
+                          {group.projectDisplayName}
+                        </span>
+                        {group.isProjectArchived && (
+                          <span className="inline-flex items-center justify-center rounded-full bg-muted px-1 py-px text-[7px] font-medium uppercase leading-none tracking-[0.02em] text-center text-muted-foreground">
+                            {t('archived.projectArchived', 'Project archived')}
+                          </span>
+                        )}
+                      </div>
+                      {group.projectPath && (
+                        <p className="mt-1 truncate text-xs text-muted-foreground/70" title={group.projectPath}>
+                          {group.projectPath}
+                        </p>
+                      )}
+                    </div>
+                    <span className="flex-shrink-0 text-[11px] text-muted-foreground">
+                      {group.sessions.length}
+                    </span>
+                  </div>
+                  <div className="divide-y divide-border/50">
+                    {group.sessions.map((session) => (
+                      <div key={session.sessionId} className="flex items-center gap-2 px-3 py-2.5">
+                        <button
+                          className="flex min-w-0 flex-1 items-center gap-2 text-left transition-colors hover:text-foreground"
+                          onClick={() => onArchivedSessionClick(session)}
+                        >
+                          <SessionProviderLogo provider={session.provider} className="h-3.5 w-3.5 flex-shrink-0" />
+                          <div className="min-w-0 flex-1">
+                            <div className="flex items-center gap-2">
+                              <span className="truncate text-xs font-medium text-foreground">
+                                {session.sessionTitle}
+                              </span>
+                              {session.lastActivity && (
+                                <span className="ml-auto flex-shrink-0 text-[11px] text-muted-foreground">
+                                  {formatCompactArchivedAge(session.lastActivity)}
+                                </span>
+                              )}
+                            </div>
+                            <p className="mt-0.5 text-[11px] uppercase tracking-wide text-muted-foreground/70">
+                              {session.provider}
+                            </p>
+                          </div>
+                        </button>
+                        <button
+                          className="flex h-7 w-7 flex-shrink-0 items-center justify-center rounded-lg bg-emerald-50 text-emerald-700 transition-colors hover:bg-emerald-100 dark:bg-emerald-900/20 dark:text-emerald-300 dark:hover:bg-emerald-900/30"
+                          onClick={() => onRestoreArchivedSession(session.sessionId)}
+                          title={t('archived.restore', 'Restore session')}
+                        >
+                          <RotateCcw className="h-3.5 w-3.5" />
+                        </button>
+                        <button
+                          className="flex h-7 w-7 flex-shrink-0 items-center justify-center rounded-lg bg-red-50 text-red-700 transition-colors hover:bg-red-100 dark:bg-red-900/20 dark:text-red-300 dark:hover:bg-red-900/30"
+                          onClick={() => onDeleteArchivedSession(session)}
+                          title={t('archived.deletePermanently', 'Delete permanently')}
+                        >
+                          <Trash2 className="h-3.5 w-3.5" />
+                        </button>
+                      </div>
+                    ))}
+                  </div>
+                </div>
+              ))}
+            </div>
+          )
         ) : (
           <SidebarProjectList {...projectListProps} />
         )}
diff --git a/src/components/sidebar/view/subcomponents/SidebarHeader.tsx b/src/components/sidebar/view/subcomponents/SidebarHeader.tsx
index 551c0095..5117b8db 100644
--- a/src/components/sidebar/view/subcomponents/SidebarHeader.tsx
+++ b/src/components/sidebar/view/subcomponents/SidebarHeader.tsx
@@ -1,22 +1,26 @@
-import { Folder, FolderPlus, MessageSquare, Plus, RefreshCw, Search, X, PanelLeftClose } from 'lucide-react';
+import { Archive, Folder, FolderPlus, MessageSquare, Plus, RefreshCw, Search, X, PanelLeftClose } from 'lucide-react';
 import type { TFunction } from 'i18next';
-import { Button, Input } from '../../../../shared/view/ui';
+import { Button, Input, Tooltip } from '../../../../shared/view/ui';
 import { IS_PLATFORM } from '../../../../constants/config';
 import { cn } from '../../../../lib/utils';
+import type { SidebarSearchMode } from '../../types/types';
 import GitHubStarBadge from './GitHubStarBadge';
 
-type SearchMode = 'projects' | 'conversations';
+const MOD_KEY =
+  typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.platform) ? '⌘' : 'Ctrl';
 
 type SidebarHeaderProps = {
   isPWA: boolean;
   isMobile: boolean;
   isLoading: boolean;
   projectsCount: number;
+  archivedSessionsCount: number;
+  isArchivedSessionsLoading: boolean;
   searchFilter: string;
   onSearchFilterChange: (value: string) => void;
   onClearSearchFilter: () => void;
-  searchMode: SearchMode;
-  onSearchModeChange: (mode: SearchMode) => void;
+  searchMode: SidebarSearchMode;
+  onSearchModeChange: (mode: SidebarSearchMode) => void;
   onRefresh: () => void;
   isRefreshing: boolean;
   onCreateProject: () => void;
@@ -29,6 +33,8 @@ export default function SidebarHeader({
   isMobile,
   isLoading,
   projectsCount,
+  archivedSessionsCount,
+  isArchivedSessionsLoading,
   searchFilter,
   onSearchFilterChange,
   onClearSearchFilter,
@@ -40,6 +46,13 @@ export default function SidebarHeader({
   onCollapseSidebar,
   t,
 }: SidebarHeaderProps) {
+  const showSearchTools = (projectsCount > 0 || archivedSessionsCount > 0 || isArchivedSessionsLoading) && !isLoading;
+  const searchPlaceholder = searchMode === 'conversations'
+    ? t('search.conversationsPlaceholder')
+    : searchMode === 'archived'
+      ? t('search.archivedPlaceholder', 'Search archived sessions...')
+      : t('projects.searchPlaceholder');
+
   const LogoBlock = () => (
     <div className="flex min-w-0 items-center gap-2.5">
       <div className="flex h-7 w-7 flex-shrink-0 items-center justify-center rounded-lg bg-primary/90 shadow-sm">
@@ -110,7 +123,7 @@ export default function SidebarHeader({
         <GitHubStarBadge />
 
         {/* Search bar */}
-        {projectsCount > 0 && !isLoading && (
+        {showSearchTools && (
           <div className="mt-2.5 space-y-2">
             {/* Search mode toggle */}
             <div className="flex rounded-lg bg-muted/50 p-0.5">
@@ -140,17 +153,33 @@ export default function SidebarHeader({
                 <MessageSquare className="h-3 w-3" />
                 {t('search.modeConversations')}
               </button>
+              <Tooltip content={t('search.archiveOnlyTooltip', 'Archive only')} position="top">
+                <button
+                  onClick={() => onSearchModeChange('archived')}
+                  aria-pressed={searchMode === 'archived'}
+                  aria-label={t('search.archiveOnlyTooltip', 'Archive only')}
+                  title={t('search.archiveOnlyTooltip', 'Archive only')}
+                  className={cn(
+                    "flex items-center justify-center rounded-md px-2.5 py-1.5 text-xs font-medium transition-all",
+                    searchMode === 'archived'
+                      ? "bg-background shadow-sm text-foreground"
+                      : "text-muted-foreground hover:text-foreground"
+                  )}
+                >
+                  <Archive className="h-3 w-3" />
+                </button>
+              </Tooltip>
             </div>
             <div className="relative">
               <Search className="pointer-events-none absolute left-3 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-muted-foreground/50" />
               <Input
                 type="text"
-                placeholder={searchMode === 'conversations' ? t('search.conversationsPlaceholder') : t('projects.searchPlaceholder')}
+                placeholder={searchPlaceholder}
                 value={searchFilter}
                 onChange={(event) => onSearchFilterChange(event.target.value)}
-                className="nav-search-input h-9 rounded-xl border-0 pl-9 pr-8 text-sm transition-all duration-200 placeholder:text-muted-foreground/40 focus-visible:ring-0 focus-visible:ring-offset-0"
+                className="nav-search-input h-9 rounded-xl border-0 pl-9 pr-14 text-sm transition-all duration-200 placeholder:text-muted-foreground/40 focus-visible:ring-0 focus-visible:ring-offset-0"
               />
-              {searchFilter && (
+              {searchFilter ? (
                 <button
                   onClick={onClearSearchFilter}
                   aria-label={t('tooltips.clearSearch')}
@@ -158,6 +187,15 @@ export default function SidebarHeader({
                 >
                   <X className="h-3 w-3 text-muted-foreground" />
                 </button>
+              ) : (
+                <kbd
+                  aria-hidden
+                  title={t('tooltips.openCommandPalette')}
+                  className="pointer-events-none absolute right-2.5 top-1/2 hidden -translate-y-1/2 items-center gap-0.5 rounded border border-border/60 bg-muted/40 px-1.5 py-0.5 font-mono text-[10px] text-muted-foreground md:inline-flex"
+                >
+                  {MOD_KEY}
+                  <span>K</span>
+                </kbd>
               )}
             </div>
           </div>
@@ -203,7 +241,7 @@ export default function SidebarHeader({
         </div>
 
         {/* Mobile search */}
-        {projectsCount > 0 && !isLoading && (
+        {showSearchTools && (
           <div className="mt-2.5 space-y-2">
             <div className="flex rounded-lg bg-muted/50 p-0.5">
               <button
@@ -232,12 +270,28 @@ export default function SidebarHeader({
                 <MessageSquare className="h-3 w-3" />
                 {t('search.modeConversations')}
               </button>
+              <Tooltip content={t('search.archiveOnlyTooltip', 'Archive only')} position="top">
+                <button
+                  onClick={() => onSearchModeChange('archived')}
+                  aria-pressed={searchMode === 'archived'}
+                  aria-label={t('search.archiveOnlyTooltip', 'Archive only')}
+                  title={t('search.archiveOnlyTooltip', 'Archive only')}
+                  className={cn(
+                    "flex items-center justify-center rounded-md px-2.5 py-1.5 text-xs font-medium transition-all",
+                    searchMode === 'archived'
+                      ? "bg-background shadow-sm text-foreground"
+                      : "text-muted-foreground hover:text-foreground"
+                  )}
+                >
+                  <Archive className="h-3 w-3" />
+                </button>
+              </Tooltip>
             </div>
             <div className="relative">
               <Search className="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground/50" />
               <Input
                 type="text"
-                placeholder={searchMode === 'conversations' ? t('search.conversationsPlaceholder') : t('projects.searchPlaceholder')}
+                placeholder={searchPlaceholder}
                 value={searchFilter}
                 onChange={(event) => onSearchFilterChange(event.target.value)}
                 className="nav-search-input h-10 rounded-xl border-0 pl-10 pr-9 text-sm transition-all duration-200 placeholder:text-muted-foreground/40 focus-visible:ring-0 focus-visible:ring-offset-0"
diff --git a/src/components/sidebar/view/subcomponents/SidebarModals.tsx b/src/components/sidebar/view/subcomponents/SidebarModals.tsx
index 6d6d69d3..28404940 100644
--- a/src/components/sidebar/view/subcomponents/SidebarModals.tsx
+++ b/src/components/sidebar/view/subcomponents/SidebarModals.tsx
@@ -25,7 +25,7 @@ type SidebarModalsProps = {
   onConfirmDeleteProject: (deleteData?: boolean) => void;
   sessionDeleteConfirmation: SessionDeleteConfirmation | null;
   onCancelDeleteSession: () => void;
-  onConfirmDeleteSession: () => void;
+  onConfirmDeleteSession: (hardDelete?: boolean) => void;
   showVersionModal: boolean;
   onCloseVersionModal: () => void;
   releaseInfo: ReleaseInfo | null;
@@ -114,7 +114,7 @@ export default function SidebarModals({
                     <p className="mb-1 text-sm text-muted-foreground">
                       {t('deleteConfirmation.confirmDelete')}{' '}
                       <span className="font-medium text-foreground">
-                        {deleteConfirmation.project.displayName || deleteConfirmation.project.name}
+                        {deleteConfirmation.project.displayName || deleteConfirmation.project.projectId}
                       </span>
                       ?
                     </p>
@@ -133,7 +133,7 @@ export default function SidebarModals({
                   onClick={() => onConfirmDeleteProject(false)}
                 >
                   <EyeOff className="mr-2 h-4 w-4" />
-                  {t('deleteConfirmation.removeFromSidebar')}
+                  {t('deleteConfirmation.archiveProject', 'Archive project')}
                 </Button>
                 <Button
                   variant="destructive"
@@ -173,22 +173,34 @@ export default function SidebarModals({
                       ?
                     </p>
                     <p className="mt-3 text-xs text-muted-foreground">
-                      {t('deleteConfirmation.cannotUndo')}
+                      {sessionDeleteConfirmation.isArchived
+                        ? t('deleteConfirmation.archivedSessionNotice', 'This session is already archived. You can keep it hidden or delete it permanently.')
+                        : t('deleteConfirmation.archiveSessionNotice', 'Archive keeps the session out of the active list while preserving its history.')}
                     </p>
                   </div>
                 </div>
               </div>
-              <div className="flex gap-3 border-t border-border bg-muted/30 p-4">
-                <Button variant="outline" className="flex-1" onClick={onCancelDeleteSession}>
-                  {t('actions.cancel')}
-                </Button>
+              <div className="flex flex-col gap-2 border-t border-border bg-muted/30 p-4">
+                {!sessionDeleteConfirmation.isArchived && (
+                  <Button
+                    variant="outline"
+                    className="w-full justify-start"
+                    onClick={() => onConfirmDeleteSession(false)}
+                  >
+                    <EyeOff className="mr-2 h-4 w-4" />
+                    {t('deleteConfirmation.archiveSession', 'Archive session')}
+                  </Button>
+                )}
                 <Button
                   variant="destructive"
-                  className="flex-1 bg-red-600 text-white hover:bg-red-700"
-                  onClick={onConfirmDeleteSession}
+                  className="w-full justify-start bg-red-600 text-white hover:bg-red-700"
+                  onClick={() => onConfirmDeleteSession(true)}
                 >
                   <Trash2 className="mr-2 h-4 w-4" />
-                  {t('actions.delete')}
+                  {t('deleteConfirmation.deleteSessionPermanently', 'Delete permanently')}
+                </Button>
+                <Button variant="ghost" className="w-full" onClick={onCancelDeleteSession}>
+                  {t('actions.cancel')}
                 </Button>
               </div>
             </div>
diff --git a/src/components/sidebar/view/subcomponents/SidebarProjectItem.tsx b/src/components/sidebar/view/subcomponents/SidebarProjectItem.tsx
index 5ac02019..7caf0642 100644
--- a/src/components/sidebar/view/subcomponents/SidebarProjectItem.tsx
+++ b/src/components/sidebar/view/subcomponents/SidebarProjectItem.tsx
@@ -1,10 +1,12 @@
-import { Check, ChevronDown, ChevronRight, Edit3, Folder, FolderOpen, Star, Trash2, X } from 'lucide-react';
+import { Check, ChevronDown, ChevronRight, Edit3, Star, Trash2, X } from 'lucide-react';
 import type { TFunction } from 'i18next';
+
 import { Button } from '../../../../shared/view/ui';
 import { cn } from '../../../../lib/utils';
 import type { Project, ProjectSession, LLMProvider } from '../../../../types/app';
 import type { MCPServerStatus, SessionWithProvider } from '../../types/types';
 import { getTaskIndicatorStatus } from '../../utils/utils';
+
 import TaskIndicator from './TaskIndicator';
 import SidebarProjectSessions from './SidebarProjectSessions';
 
@@ -19,7 +21,7 @@ type SidebarProjectItemProps = {
   editingName: string;
   sessions: SessionWithProvider[];
   initialSessionsLoaded: boolean;
-  isLoadingSessions: boolean;
+  isLoadingMoreSessions: boolean;
   currentTime: Date;
   editingSession: string | null;
   editingSessionName: string;
@@ -40,7 +42,7 @@ type SidebarProjectItemProps = {
     sessionTitle: string,
     provider: LLMProvider,
   ) => void;
-  onLoadMoreSessions: (project: Project) => void;
+  onLoadMoreSessions: (projectId: string) => void;
   onNewSession: (project: Project) => void;
   onEditingSessionNameChange: (value: string) => void;
   onStartEditingSession: (sessionId: string, initialName: string) => void;
@@ -49,13 +51,9 @@ type SidebarProjectItemProps = {
   t: TFunction;
 };
 
-const getSessionCountDisplay = (sessions: SessionWithProvider[], hasMoreSessions: boolean): string => {
-  const sessionCount = sessions.length;
-  if (hasMoreSessions && sessionCount >= 5) {
-    return `${sessionCount}+`;
-  }
-
-  return `${sessionCount}`;
+const getSessionCountDisplay = (project: Project, sessions: SessionWithProvider[]): string => {
+  const total = Number(project.sessionMeta?.total ?? sessions.length);
+  return String(total);
 };
 
 export default function SidebarProjectItem({
@@ -69,7 +67,7 @@ export default function SidebarProjectItem({
   editingName,
   sessions,
   initialSessionsLoaded,
-  isLoadingSessions,
+  isLoadingMoreSessions,
   currentTime,
   editingSession,
   editingSessionName,
@@ -93,22 +91,24 @@ export default function SidebarProjectItem({
   onSaveEditingSession,
   t,
 }: SidebarProjectItemProps) {
-  const isSelected = selectedProject?.name === project.name;
-  const isEditing = editingProject === project.name;
-  const hasMoreSessions = project.sessionMeta?.hasMore === true;
-  const sessionCountDisplay = getSessionCountDisplay(sessions, hasMoreSessions);
-  const sessionCountLabel = `${sessionCountDisplay} session${sessions.length === 1 ? '' : 's'}`;
+  // Project identity is tracked by the DB-assigned `projectId` everywhere
+  // after the projectName → projectId migration.
+  const isSelected = selectedProject?.projectId === project.projectId;
+  const isEditing = editingProject === project.projectId;
+  const totalSessionCount = Number(project.sessionMeta?.total ?? sessions.length);
+  const sessionCountDisplay = getSessionCountDisplay(project, sessions);
+  const sessionCountLabel = `${sessionCountDisplay} session${totalSessionCount === 1 ? '' : 's'}`;
   const taskStatus = getTaskIndicatorStatus(project, mcpServerStatus);
 
-  const toggleProject = () => onToggleProject(project.name);
-  const toggleStarProject = () => onToggleStarProject(project.name);
+  const toggleProject = () => onToggleProject(project.projectId);
+  const toggleStarProject = () => onToggleStarProject(project.projectId);
 
   const saveProjectName = () => {
-    onSaveProjectName(project.name);
+    onSaveProjectName(project.projectId);
   };
 
   const selectAndToggleProject = () => {
-    if (selectedProject?.name !== project.name) {
+    if (selectedProject?.projectId !== project.projectId) {
       onProjectSelect(project);
     }
 
@@ -131,18 +131,28 @@ export default function SidebarProjectItem({
           >
             <div className="flex items-center justify-between">
               <div className="flex min-w-0 flex-1 items-center gap-3">
-                <div
+                <button
                   className={cn(
-                    'w-8 h-8 rounded-lg flex items-center justify-center transition-colors',
-                    isExpanded ? 'bg-primary/10' : 'bg-muted',
+                    'w-8 h-8 rounded-lg flex items-center justify-center active:scale-90 transition-all duration-150 border',
+                    isStarred
+                      ? 'bg-yellow-500/10 dark:bg-yellow-900/30 border-yellow-200 dark:border-yellow-800'
+                      : 'bg-gray-500/10 dark:bg-gray-900/30 border-gray-200 dark:border-gray-800',
                   )}
+                  onClick={(event) => {
+                    event.stopPropagation();
+                    toggleStarProject();
+                  }}
+                  title={isStarred ? t('tooltips.removeFromFavorites') : t('tooltips.addToFavorites')}
                 >
-                  {isExpanded ? (
-                    <FolderOpen className="h-4 w-4 text-primary" />
-                  ) : (
-                    <Folder className="h-4 w-4 text-muted-foreground" />
-                  )}
-                </div>
+                  <Star
+                    className={cn(
+                      'w-4 h-4 transition-colors',
+                      isStarred
+                        ? 'text-yellow-600 dark:text-yellow-400 fill-current'
+                        : 'text-gray-600 dark:text-gray-400',
+                    )}
+                  />
+                </button>
 
                 <div className="min-w-0 flex-1">
                   {isEditing ? (
@@ -212,29 +222,6 @@ export default function SidebarProjectItem({
                   </>
                 ) : (
                   <>
-                    <button
-                      className={cn(
-                        'w-8 h-8 rounded-lg flex items-center justify-center active:scale-90 transition-all duration-150 border',
-                        isStarred
-                          ? 'bg-yellow-500/10 dark:bg-yellow-900/30 border-yellow-200 dark:border-yellow-800'
-                          : 'bg-gray-500/10 dark:bg-gray-900/30 border-gray-200 dark:border-gray-800',
-                      )}
-                      onClick={(event) => {
-                        event.stopPropagation();
-                        toggleStarProject();
-                      }}
-                      title={isStarred ? t('tooltips.removeFromFavorites') : t('tooltips.addToFavorites')}
-                    >
-                      <Star
-                        className={cn(
-                          'w-4 h-4 transition-colors',
-                          isStarred
-                            ? 'text-yellow-600 dark:text-yellow-400 fill-current'
-                            : 'text-gray-600 dark:text-gray-400',
-                        )}
-                      />
-                    </button>
-
                     <button
                       className="flex h-8 w-8 items-center justify-center rounded-lg border border-red-200 bg-red-500/10 active:scale-90 dark:border-red-800 dark:bg-red-900/30"
                       onClick={(event) => {
@@ -281,11 +268,28 @@ export default function SidebarProjectItem({
           onClick={selectAndToggleProject}
         >
           <div className="flex min-w-0 flex-1 items-center gap-3">
-            {isExpanded ? (
-              <FolderOpen className="h-4 w-4 flex-shrink-0 text-primary" />
-            ) : (
-              <Folder className="h-4 w-4 flex-shrink-0 text-muted-foreground" />
-            )}
+            <div
+              className={cn(
+                'w-6 h-6 flex items-center justify-center rounded cursor-pointer transition-all duration-200',
+                isStarred
+                  ? 'hover:bg-yellow-50 dark:hover:bg-yellow-900/20'
+                  : 'opacity-40 hover:opacity-100 hover:bg-accent',
+              )}
+              onClick={(event) => {
+                event.stopPropagation();
+                toggleStarProject();
+              }}
+              title={isStarred ? t('tooltips.removeFromFavorites') : t('tooltips.addToFavorites')}
+            >
+              <Star
+                className={cn(
+                  'w-3 h-3 transition-colors',
+                  isStarred
+                    ? 'text-yellow-600 dark:text-yellow-400 fill-current'
+                    : 'text-muted-foreground',
+                )}
+              />
+            </div>
             <div className="min-w-0 flex-1 text-left">
               {isEditing ? (
                 <div className="space-y-1">
@@ -352,26 +356,6 @@ export default function SidebarProjectItem({
               </>
             ) : (
               <>
-                <div
-                  className={cn(
-                    'w-6 h-6 opacity-0 group-hover:opacity-100 transition-all duration-200 flex items-center justify-center rounded cursor-pointer touch:opacity-100',
-                    isStarred ? 'hover:bg-yellow-50 dark:hover:bg-yellow-900/20 opacity-100' : 'hover:bg-accent',
-                  )}
-                  onClick={(event) => {
-                    event.stopPropagation();
-                    toggleStarProject();
-                  }}
-                  title={isStarred ? t('tooltips.removeFromFavorites') : t('tooltips.addToFavorites')}
-                >
-                  <Star
-                    className={cn(
-                      'w-3 h-3 transition-colors',
-                      isStarred
-                        ? 'text-yellow-600 dark:text-yellow-400 fill-current'
-                        : 'text-muted-foreground',
-                    )}
-                  />
-                </div>
                 <div
                   className="touch:opacity-100 flex h-6 w-6 cursor-pointer items-center justify-center rounded opacity-0 transition-all duration-200 hover:bg-accent group-hover:opacity-100"
                   onClick={(event) => {
@@ -409,7 +393,8 @@ export default function SidebarProjectItem({
         sessions={sessions}
         selectedSession={selectedSession}
         initialSessionsLoaded={initialSessionsLoaded}
-        isLoadingSessions={isLoadingSessions}
+        hasMoreSessions={Boolean(project.sessionMeta?.hasMore)}
+        isLoadingMoreSessions={isLoadingMoreSessions}
         currentTime={currentTime}
         editingSession={editingSession}
         editingSessionName={editingSessionName}
diff --git a/src/components/sidebar/view/subcomponents/SidebarProjectList.tsx b/src/components/sidebar/view/subcomponents/SidebarProjectList.tsx
index a755b1da..fc9fac6f 100644
--- a/src/components/sidebar/view/subcomponents/SidebarProjectList.tsx
+++ b/src/components/sidebar/view/subcomponents/SidebarProjectList.tsx
@@ -1,11 +1,9 @@
 import { useEffect } from 'react';
 import type { TFunction } from 'i18next';
+
 import type { LoadingProgress, Project, ProjectSession, LLMProvider } from '../../../../types/app';
-import type {
-  LoadingSessionsByProject,
-  MCPServerStatus,
-  SessionWithProvider,
-} from '../../types/types';
+import type { MCPServerStatus, SessionWithProvider } from '../../types/types';
+
 import SidebarProjectItem from './SidebarProjectItem';
 import SidebarProjectsState from './SidebarProjectsState';
 
@@ -19,7 +17,6 @@ export type SidebarProjectListProps = {
   expandedProjects: Set<string>;
   editingProject: string | null;
   editingName: string;
-  loadingSessions: LoadingSessionsByProject;
   initialSessionsLoaded: Set<string>;
   currentTime: Date;
   editingSession: string | null;
@@ -28,6 +25,8 @@ export type SidebarProjectListProps = {
   tasksEnabled: boolean;
   mcpServerStatus: MCPServerStatus;
   getProjectSessions: (project: Project) => SessionWithProvider[];
+  onLoadMoreSessions: (projectId: string) => void;
+  loadingMoreProjects: Set<string>;
   isProjectStarred: (projectName: string) => boolean;
   onEditingNameChange: (value: string) => void;
   onToggleProject: (projectName: string) => void;
@@ -44,7 +43,6 @@ export type SidebarProjectListProps = {
     sessionTitle: string,
     provider: LLMProvider,
   ) => void;
-  onLoadMoreSessions: (project: Project) => void;
   onNewSession: (project: Project) => void;
   onEditingSessionNameChange: (value: string) => void;
   onStartEditingSession: (sessionId: string, initialName: string) => void;
@@ -63,7 +61,6 @@ export default function SidebarProjectList({
   expandedProjects,
   editingProject,
   editingName,
-  loadingSessions,
   initialSessionsLoaded,
   currentTime,
   editingSession,
@@ -72,6 +69,8 @@ export default function SidebarProjectList({
   tasksEnabled,
   mcpServerStatus,
   getProjectSessions,
+  onLoadMoreSessions,
+  loadingMoreProjects,
   isProjectStarred,
   onEditingNameChange,
   onToggleProject,
@@ -83,7 +82,6 @@ export default function SidebarProjectList({
   onDeleteProject,
   onSessionSelect,
   onDeleteSession,
-  onLoadMoreSessions,
   onNewSession,
   onEditingSessionNameChange,
   onStartEditingSession,
@@ -117,19 +115,21 @@ export default function SidebarProjectList({
       {!showProjects
         ? state
         : filteredProjects.map((project) => (
+            // React key + per-project state lookups all use the DB `projectId`
+            // so they remain stable across renames and session changes.
             <SidebarProjectItem
-              key={project.name}
+              key={project.projectId}
               project={project}
               selectedProject={selectedProject}
               selectedSession={selectedSession}
-              isExpanded={expandedProjects.has(project.name)}
-              isDeleting={deletingProjects.has(project.name)}
-              isStarred={isProjectStarred(project.name)}
+              isExpanded={expandedProjects.has(project.projectId)}
+              isDeleting={deletingProjects.has(project.projectId)}
+              isStarred={isProjectStarred(project.projectId)}
               editingProject={editingProject}
               editingName={editingName}
               sessions={getProjectSessions(project)}
-              initialSessionsLoaded={initialSessionsLoaded.has(project.name)}
-              isLoadingSessions={Boolean(loadingSessions[project.name])}
+              initialSessionsLoaded={initialSessionsLoaded.has(project.projectId)}
+              isLoadingMoreSessions={loadingMoreProjects.has(project.projectId)}
               currentTime={currentTime}
               editingSession={editingSession}
               editingSessionName={editingSessionName}
diff --git a/src/components/sidebar/view/subcomponents/SidebarProjectSessions.tsx b/src/components/sidebar/view/subcomponents/SidebarProjectSessions.tsx
index 2f4068e9..f68daad6 100644
--- a/src/components/sidebar/view/subcomponents/SidebarProjectSessions.tsx
+++ b/src/components/sidebar/view/subcomponents/SidebarProjectSessions.tsx
@@ -1,8 +1,10 @@
-import { ChevronDown, Plus } from 'lucide-react';
+import { Plus } from 'lucide-react';
 import type { TFunction } from 'i18next';
+
 import { Button } from '../../../../shared/view/ui';
 import type { Project, ProjectSession, LLMProvider } from '../../../../types/app';
 import type { SessionWithProvider } from '../../types/types';
+
 import SidebarSessionItem from './SidebarSessionItem';
 
 type SidebarProjectSessionsProps = {
@@ -11,7 +13,8 @@ type SidebarProjectSessionsProps = {
   sessions: SessionWithProvider[];
   selectedSession: ProjectSession | null;
   initialSessionsLoaded: boolean;
-  isLoadingSessions: boolean;
+  hasMoreSessions: boolean;
+  isLoadingMoreSessions: boolean;
   currentTime: Date;
   editingSession: string | null;
   editingSessionName: string;
@@ -27,7 +30,7 @@ type SidebarProjectSessionsProps = {
     sessionTitle: string,
     provider: LLMProvider,
   ) => void;
-  onLoadMoreSessions: (project: Project) => void;
+  onLoadMoreSessions: (projectId: string) => void;
   onNewSession: (project: Project) => void;
   t: TFunction;
 };
@@ -56,7 +59,8 @@ export default function SidebarProjectSessions({
   sessions,
   selectedSession,
   initialSessionsLoaded,
-  isLoadingSessions,
+  hasMoreSessions,
+  isLoadingMoreSessions,
   currentTime,
   editingSession,
   editingSessionName,
@@ -76,7 +80,6 @@ export default function SidebarProjectSessions({
   }
 
   const hasSessions = sessions.length > 0;
-  const hasMoreSessions = project.sessionMeta?.hasMore === true;
 
   return (
     <div className="ml-3 space-y-1 border-l border-border pl-3">
@@ -105,52 +108,44 @@ export default function SidebarProjectSessions({
 
       {!initialSessionsLoaded ? (
         <SessionListSkeleton />
-      ) : !hasSessions && !isLoadingSessions ? (
+      ) : !hasSessions ? (
         <div className="px-3 py-2 text-left">
           <p className="text-xs text-muted-foreground">{t('sessions.noSessions')}</p>
         </div>
       ) : (
-        sessions.map((session) => (
-          <SidebarSessionItem
-            key={session.id}
-            project={project}
-            session={session}
-            selectedSession={selectedSession}
-            currentTime={currentTime}
-            editingSession={editingSession}
-            editingSessionName={editingSessionName}
-            onEditingSessionNameChange={onEditingSessionNameChange}
-            onStartEditingSession={onStartEditingSession}
-            onCancelEditingSession={onCancelEditingSession}
-            onSaveEditingSession={onSaveEditingSession}
-            onProjectSelect={onProjectSelect}
-            onSessionSelect={onSessionSelect}
-            onDeleteSession={onDeleteSession}
-            t={t}
-          />
-        ))
-      )}
+        <>
+          {sessions.map((session) => (
+            <SidebarSessionItem
+              key={session.id}
+              project={project}
+              session={session}
+              selectedSession={selectedSession}
+              currentTime={currentTime}
+              editingSession={editingSession}
+              editingSessionName={editingSessionName}
+              onEditingSessionNameChange={onEditingSessionNameChange}
+              onStartEditingSession={onStartEditingSession}
+              onCancelEditingSession={onCancelEditingSession}
+              onSaveEditingSession={onSaveEditingSession}
+              onProjectSelect={onProjectSelect}
+              onSessionSelect={onSessionSelect}
+              onDeleteSession={onDeleteSession}
+              t={t}
+            />
+          ))}
 
-      {hasSessions && hasMoreSessions && (
-        <Button
-          variant="ghost"
-          size="sm"
-          className="mt-2 w-full justify-center gap-2 text-muted-foreground"
-          onClick={() => onLoadMoreSessions(project)}
-          disabled={isLoadingSessions}
-        >
-          {isLoadingSessions ? (
-            <>
-              <div className="h-3 w-3 animate-spin rounded-full border border-muted-foreground border-t-transparent" />
-              {t('sessions.loading')}
-            </>
-          ) : (
-            <>
-              <ChevronDown className="h-3 w-3" />
-              {t('sessions.showMore')}
-            </>
+          {hasMoreSessions && (
+            <Button
+              variant="ghost"
+              size="sm"
+              className="h-8 w-full justify-center text-xs text-muted-foreground hover:text-foreground"
+              onClick={() => onLoadMoreSessions(project.projectId)}
+              disabled={isLoadingMoreSessions}
+            >
+              {isLoadingMoreSessions ? t('sessions.loadingSessions') : 'Load more sessions'}
+            </Button>
           )}
-        </Button>
+        </>
       )}
     </div>
   );
diff --git a/src/components/sidebar/view/subcomponents/SidebarSessionItem.tsx b/src/components/sidebar/view/subcomponents/SidebarSessionItem.tsx
index 507478a8..209a9832 100644
--- a/src/components/sidebar/view/subcomponents/SidebarSessionItem.tsx
+++ b/src/components/sidebar/view/subcomponents/SidebarSessionItem.tsx
@@ -1,8 +1,9 @@
-import { Check, Clock, Edit2, Trash2, X } from 'lucide-react';
+import { useEffect, useRef } from 'react';
+import { Check, Edit2, Trash2, X } from 'lucide-react';
 import type { TFunction } from 'i18next';
-import { Badge, Button } from '../../../../shared/view/ui';
+
+import { Badge, Button, Tooltip } from '../../../../shared/view/ui';
 import { cn } from '../../../../lib/utils';
-import { formatTimeAgo } from '../../../../utils/dateUtils';
 import type { Project, ProjectSession, LLMProvider } from '../../../../types/app';
 import type { SessionWithProvider } from '../../types/types';
 import { createSessionViewModel } from '../../utils/utils';
@@ -30,6 +31,34 @@ type SidebarSessionItemProps = {
   t: TFunction;
 };
 
+/**
+ * Compact relative time for sidebar rows:
+ * <1m, Xm, Xhr, Xd.
+ */
+const formatCompactSessionAge = (dateString: string, currentTime: Date): string => {
+  const date = new Date(dateString);
+  if (Number.isNaN(date.getTime())) {
+    return '';
+  }
+
+  const diffInMinutes = Math.floor(Math.max(0, currentTime.getTime() - date.getTime()) / (1000 * 60));
+  if (diffInMinutes < 1) {
+    return '<1m';
+  }
+
+  if (diffInMinutes < 60) {
+    return `${diffInMinutes}m`;
+  }
+
+  const diffInHours = Math.floor(diffInMinutes / 60);
+  if (diffInHours < 24) {
+    return `${diffInHours}hr`;
+  }
+
+  const diffInDays = Math.floor(diffInHours / 24);
+  return `${diffInDays}d`;
+};
+
 export default function SidebarSessionItem({
   project,
   session,
@@ -48,25 +77,55 @@ export default function SidebarSessionItem({
 }: SidebarSessionItemProps) {
   const sessionView = createSessionViewModel(session, currentTime, t);
   const isSelected = selectedSession?.id === session.id;
+  const isEditing = editingSession === session.id;
+  const compactSessionAge = formatCompactSessionAge(sessionView.sessionTime, currentTime);
+  const editingContainerRef = useRef<HTMLDivElement>(null);
 
+  // The rename panel sits inside a group-hover opacity wrapper, so leaving the row
+  // would visually hide it. While editing, dismiss only when the user clicks outside
+  // the panel (matches Escape / cancel-button behaviour).
+  useEffect(() => {
+    if (!isEditing) {
+      return;
+    }
+
+    const handlePointerDown = (event: MouseEvent) => {
+      const container = editingContainerRef.current;
+      if (container && !container.contains(event.target as Node)) {
+        onCancelEditingSession();
+      }
+    };
+
+    document.addEventListener('mousedown', handlePointerDown);
+    return () => document.removeEventListener('mousedown', handlePointerDown);
+  }, [isEditing, onCancelEditingSession]);
+
+  // Sessions are owned by a project identified by `projectId` (DB primary key)
+  // after the projectName → projectId migration.
   const selectMobileSession = () => {
     onProjectSelect(project);
-    onSessionSelect(session, project.name);
+    onSessionSelect(session, project.projectId);
   };
 
   const saveEditedSession = () => {
-    onSaveEditingSession(project.name, session.id, editingSessionName, session.__provider);
+    onSaveEditingSession(project.projectId, session.id, editingSessionName, session.__provider);
   };
 
   const requestDeleteSession = () => {
-    onDeleteSession(project.name, session.id, sessionView.sessionName, session.__provider);
+    onDeleteSession(project.projectId, session.id, sessionView.sessionName, session.__provider);
   };
 
   return (
     <div className="group relative">
       {sessionView.isActive && (
         <div className="absolute left-0 top-1/2 -translate-x-1 -translate-y-1/2 transform">
-          <div className="h-2 w-2 animate-pulse rounded-full bg-green-500" />
+          <Tooltip content={t('tooltips.activeSessionIndicator')} position="right">
+            <div
+              role="status"
+              aria-label={t('tooltips.activeSessionIndicator')}
+              className="h-2 w-2 animate-pulse rounded-full bg-green-500"
+            />
+          </Tooltip>
         </div>
       )}
 
@@ -92,20 +151,18 @@ export default function SidebarSessionItem({
             </div>
 
             <div className="min-w-0 flex-1">
-              <div className="truncate text-xs font-medium text-foreground">{sessionView.sessionName}</div>
-              <div className="mt-0.5 flex items-center gap-1">
-                <Clock className="h-2.5 w-2.5 text-muted-foreground" />
-                <span className="text-xs text-muted-foreground">
-                  {formatTimeAgo(sessionView.sessionTime, currentTime, t)}
-                </span>
+              <div className="flex items-center gap-2">
+                <div className="truncate text-xs font-medium text-foreground">{sessionView.sessionName}</div>
+                {compactSessionAge && (
+                  <span className="ml-auto flex-shrink-0 text-[11px] text-muted-foreground">{compactSessionAge}</span>
+                )}
+              </div>
+              <div className="mt-0.5 flex items-center">
                 {sessionView.messageCount > 0 && (
-                  <Badge variant="secondary" className="ml-auto px-1 py-0 text-xs">
+                  <Badge variant="secondary" className="px-1 py-0 text-xs">
                     {sessionView.messageCount}
                   </Badge>
                 )}
-                <span className="ml-1 opacity-70">
-                  <SessionProviderLogo provider={session.__provider} className="h-3 w-3" />
-                </span>
               </div>
             </div>
 
@@ -131,35 +188,39 @@ export default function SidebarSessionItem({
             'w-full justify-start p-2 h-auto font-normal text-left hover:bg-accent/50 transition-colors duration-200',
             isSelected && 'bg-accent text-accent-foreground',
           )}
-          onClick={() => onSessionSelect(session, project.name)}
+          onClick={() => onSessionSelect(session, project.projectId)}
         >
           <div className="flex w-full min-w-0 items-start gap-2">
             <SessionProviderLogo provider={session.__provider} className="mt-0.5 h-3 w-3 flex-shrink-0" />
             <div className="min-w-0 flex-1">
-              <div className="truncate text-xs font-medium text-foreground">{sessionView.sessionName}</div>
-              <div className="mt-0.5 flex items-center gap-1">
-                <Clock className="h-2.5 w-2.5 text-muted-foreground" />
-                <span className="text-xs text-muted-foreground">
-                  {formatTimeAgo(sessionView.sessionTime, currentTime, t)}
-                </span>
-                {sessionView.messageCount > 0 && (
-                  <Badge
-                    variant="secondary"
-                    className="ml-auto px-1 py-0 text-xs transition-opacity group-hover:opacity-0"
+              <div className="flex items-center gap-2">
+                <div className="truncate text-xs font-medium text-foreground">{sessionView.sessionName}</div>
+                {compactSessionAge && (
+                  <span
+                    className={cn(
+                      'ml-auto flex-shrink-0 text-[11px] text-muted-foreground transition-opacity duration-200',
+                      isEditing ? 'opacity-0' : 'group-hover:opacity-0',
+                    )}
                   >
-                    {sessionView.messageCount}
-                  </Badge>
+                    {compactSessionAge}
+                  </span>
                 )}
-                <span className="ml-1 opacity-70 transition-opacity group-hover:opacity-0">
-                  <SessionProviderLogo provider={session.__provider} className="h-3 w-3" />
-                </span>
+              </div>
+              <div className="mt-0.5 flex items-center">
+                {sessionView.messageCount > 0 && <Badge variant="secondary" className="px-1 py-0 text-xs">{sessionView.messageCount}</Badge>}
               </div>
             </div>
           </div>
         </Button>
 
-        <div className="absolute right-2 top-1/2 flex -translate-y-1/2 transform items-center gap-1 opacity-0 transition-all duration-200 group-hover:opacity-100">
-            {editingSession === session.id ? (
+        <div
+          ref={editingContainerRef}
+          className={cn(
+            'absolute right-2 top-1/2 flex -translate-y-1/2 transform items-center gap-1 transition-all duration-200',
+            isEditing ? 'opacity-100' : 'opacity-0 group-hover:opacity-100',
+          )}
+        >
+            {isEditing ? (
               <>
                 <input
                   type="text"
@@ -217,7 +278,7 @@ export default function SidebarSessionItem({
                       event.stopPropagation();
                       requestDeleteSession();
                     }}
-                    title={t('tooltips.deleteSession')}
+                    title={t('tooltips.deleteSessionOptions', 'Archive or permanently delete this session')}
                   >
                     <Trash2 className="h-3 w-3 text-red-600 dark:text-red-400" />
                   </button>
diff --git a/src/components/task-master/context/TaskMasterContext.tsx b/src/components/task-master/context/TaskMasterContext.tsx
index 37953ad8..05afaddf 100644
--- a/src/components/task-master/context/TaskMasterContext.tsx
+++ b/src/components/task-master/context/TaskMasterContext.tsx
@@ -1,4 +1,5 @@
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+
 import { api } from '../../../utils/api';
 import { useAuth } from '../../auth/context/AuthContext';
 import { useWebSocket } from '../../../contexts/WebSocketContext';
@@ -73,11 +74,19 @@ export function TaskMasterProvider({ children }: { children: React.ReactNode })
   const [isLoadingMCP, setIsLoadingMCP] = useState(false);
   const [error, setError] = useState<TaskMasterContextError | null>(null);
 
-  const currentProjectNameRef = useRef<string | null>(null);
+  // Track the active project via DB `projectId`; everything downstream uses
+  // the same identifier post-migration.
+  const currentProjectIdRef = useRef<string | null>(null);
+  const projectTaskMasterRef = useRef<TaskMasterProjectInfo | null>(null);
+  const taskMasterRequestSeqRef = useRef(0);
 
   useEffect(() => {
-    currentProjectNameRef.current = currentProject?.name ?? null;
-  }, [currentProject?.name]);
+    currentProjectIdRef.current = currentProject?.projectId ?? null;
+  }, [currentProject?.projectId]);
+
+  useEffect(() => {
+    projectTaskMasterRef.current = projectTaskMaster;
+  }, [projectTaskMaster]);
 
   const clearError = useCallback(() => {
     setError(null);
@@ -88,16 +97,96 @@ export function TaskMasterProvider({ children }: { children: React.ReactNode })
     setError(createTaskMasterError(context, caughtError));
   }, []);
 
-  const setCurrentProject = useCallback((project: TaskMasterProjectInput) => {
-    const normalizedProject = project ? enrichProject(project as TaskMasterProject) : null;
-    setCurrentProjectState(normalizedProject);
-    setProjectTaskMaster(normalizedProject?.taskmaster ?? null);
+  // Looks up projects by DB `projectId`; the legacy folder-derived `name`
+  // field has been removed from Project post-migration.
+  const applyTaskMasterInfo = useCallback((projectId: string, taskMasterInfo: TaskMasterProjectInfo | null) => {
+    setProjectTaskMaster(taskMasterInfo);
 
-    // Project-scoped task data is reset immediately to avoid stale task rendering.
-    setTasks([]);
-    setNextTask(null);
+    setProjects((previousProjects) =>
+      previousProjects.map((project) => {
+        if (project.projectId !== projectId) {
+          return project;
+        }
+
+        return enrichProject({
+          ...project,
+          taskmaster: taskMasterInfo ?? undefined,
+        });
+      }),
+    );
+
+    setCurrentProjectState((previousProject) => {
+      if (!previousProject || previousProject.projectId !== projectId) {
+        return previousProject;
+      }
+
+      return enrichProject({
+        ...previousProject,
+        taskmaster: taskMasterInfo ?? undefined,
+      });
+    });
   }, []);
 
+  const refreshCurrentProjectTaskMaster = useCallback(
+    async (projectId: string) => {
+      if (!projectId || !user || !token) {
+        return;
+      }
+
+      const requestSequence = ++taskMasterRequestSeqRef.current;
+
+      try {
+        const response = await api.projectTaskmaster(projectId);
+        if (!response.ok) {
+          throw new Error(`Failed to fetch TaskMaster details: ${response.status}`);
+        }
+
+        const data = (await response.json()) as { taskmaster?: TaskMasterProjectInfo };
+        const resolvedTaskMasterInfo = data.taskmaster ?? null;
+
+        if (
+          requestSequence !== taskMasterRequestSeqRef.current
+          || currentProjectIdRef.current !== projectId
+        ) {
+          return;
+        }
+
+        applyTaskMasterInfo(projectId, resolvedTaskMasterInfo);
+      } catch (caughtError) {
+        if (
+          requestSequence !== taskMasterRequestSeqRef.current
+          || currentProjectIdRef.current !== projectId
+        ) {
+          return;
+        }
+
+        handleError('load selected project TaskMaster info', caughtError);
+      }
+    },
+    [applyTaskMasterInfo, handleError, token, user],
+  );
+
+  const setCurrentProject = useCallback(
+    (project: TaskMasterProjectInput) => {
+      const normalizedProject = project ? enrichProject(project as TaskMasterProject) : null;
+      setCurrentProjectState(normalizedProject);
+      setProjectTaskMaster(normalizedProject?.taskmaster ?? null);
+
+      // Project-scoped task data is reset immediately to avoid stale task rendering.
+      setTasks([]);
+      setNextTask(null);
+
+      // `projectId` is the DB primary key used for every TaskMaster API call.
+      if (!normalizedProject?.projectId) {
+        taskMasterRequestSeqRef.current += 1;
+        return;
+      }
+
+      void refreshCurrentProjectTaskMaster(normalizedProject.projectId);
+    },
+    [refreshCurrentProjectTaskMaster],
+  );
+
   const refreshProjects = useCallback(async () => {
     if (!user || !token) {
       setProjects([]);
@@ -121,27 +210,67 @@ export function TaskMasterProvider({ children }: { children: React.ReactNode })
       const loadedProjects = Array.isArray(data) ? (data as TaskMasterProject[]) : [];
       const enrichedProjects = loadedProjects.map((project) => enrichProject(project));
 
-      setProjects(enrichedProjects);
+      setProjects((previousProjects) => {
+        // Cache is keyed by `projectId` (DB primary key) post-migration.
+        const taskMasterByProjectId = new Map(
+          previousProjects
+            .filter((project) => Boolean(project.taskmaster))
+            .map((project) => [project.projectId, project.taskmaster]),
+        );
 
-      const currentProjectName = currentProjectNameRef.current;
-      if (!currentProjectName) {
+        return enrichedProjects.map((project) => {
+          const cachedTaskMasterInfo = taskMasterByProjectId.get(project.projectId);
+          if (!cachedTaskMasterInfo) {
+            return project;
+          }
+
+          return enrichProject({
+            ...project,
+            taskmaster: cachedTaskMasterInfo,
+          });
+        });
+      });
+
+      const currentProjectId = currentProjectIdRef.current;
+      if (!currentProjectId) {
         return;
       }
 
-      const matchingProject = enrichedProjects.find((project) => project.name === currentProjectName) ?? null;
-      setCurrentProjectState(matchingProject);
-      setProjectTaskMaster(matchingProject?.taskmaster ?? null);
+      const matchingProject = enrichedProjects.find((project) => project.projectId === currentProjectId) ?? null;
+
+      if (!matchingProject) {
+        taskMasterRequestSeqRef.current += 1;
+        setCurrentProjectState(null);
+        setProjectTaskMaster(null);
+        setTasks([]);
+        setNextTask(null);
+        return;
+      }
+
+      const cachedTaskMasterInfo = matchingProject.taskmaster ?? projectTaskMasterRef.current ?? null;
+      setCurrentProjectState(
+        cachedTaskMasterInfo
+          ? enrichProject({
+              ...matchingProject,
+              taskmaster: cachedTaskMasterInfo,
+            })
+          : matchingProject,
+      );
+      setProjectTaskMaster(cachedTaskMasterInfo);
+
+      void refreshCurrentProjectTaskMaster(currentProjectId);
     } catch (caughtError) {
       handleError('load projects', caughtError);
     } finally {
       setIsLoading(false);
     }
-  }, [clearError, handleError, token, user]);
+  }, [clearError, handleError, refreshCurrentProjectTaskMaster, token, user]);
 
   const refreshTasks = useCallback(async () => {
-    const projectName = currentProject?.name;
+    // TaskMaster tasks endpoint now lives under /api/taskmaster/tasks/:projectId.
+    const projectId = currentProject?.projectId;
 
-    if (!projectName || !user || !token) {
+    if (!projectId || !user || !token) {
       setTasks([]);
       setNextTask(null);
       return;
@@ -151,7 +280,7 @@ export function TaskMasterProvider({ children }: { children: React.ReactNode })
       setIsLoadingTasks(true);
       clearError();
 
-      const response = await api.get(`/taskmaster/tasks/${encodeURIComponent(projectName)}`);
+      const response = await api.get(`/taskmaster/tasks/${encodeURIComponent(projectId)}`);
       if (!response.ok) {
         const errorPayload = (await response.json()) as { message?: string };
         throw new Error(errorPayload.message ?? 'Failed to load tasks');
@@ -169,7 +298,7 @@ export function TaskMasterProvider({ children }: { children: React.ReactNode })
     } finally {
       setIsLoadingTasks(false);
     }
-  }, [clearError, currentProject?.name, handleError, token, user]);
+  }, [clearError, currentProject?.projectId, handleError, token, user]);
 
   const refreshMCPStatus = useCallback(async () => {
     if (!user || !token) {
@@ -204,10 +333,10 @@ export function TaskMasterProvider({ children }: { children: React.ReactNode })
   }, [isAuthLoading, refreshMCPStatus, refreshProjects, token, user]);
 
   useEffect(() => {
-    if (currentProject?.name && user && token) {
+    if (currentProject?.projectId && user && token) {
       void refreshTasks();
     }
-  }, [currentProject?.name, refreshTasks, token, user]);
+  }, [currentProject?.projectId, refreshTasks, token, user]);
 
   useEffect(() => {
     const message = latestMessage as TaskMasterWebSocketMessage | null;
@@ -215,12 +344,16 @@ export function TaskMasterProvider({ children }: { children: React.ReactNode })
       return;
     }
 
-    if (message.type === 'taskmaster-project-updated' && message.projectName) {
+    // Broadcasts now identify projects by `projectId` (see taskmaster-websocket.js).
+    if (message.type === 'taskmaster-project-updated' && message.projectId) {
+      if (message.projectId === currentProjectIdRef.current) {
+        void refreshCurrentProjectTaskMaster(message.projectId);
+      }
       void refreshProjects();
       return;
     }
 
-    if (message.type === 'taskmaster-tasks-updated' && message.projectName === currentProject?.name) {
+    if (message.type === 'taskmaster-tasks-updated' && message.projectId === currentProject?.projectId) {
       void refreshTasks();
       return;
     }
@@ -228,7 +361,7 @@ export function TaskMasterProvider({ children }: { children: React.ReactNode })
     if (message.type === 'taskmaster-mcp-status-changed') {
       void refreshMCPStatus();
     }
-  }, [currentProject?.name, latestMessage, refreshMCPStatus, refreshProjects, refreshTasks]);
+  }, [currentProject?.projectId, latestMessage, refreshCurrentProjectTaskMaster, refreshMCPStatus, refreshProjects, refreshTasks]);
 
   const contextValue = useMemo<TaskMasterContextValue>(
     () => ({
diff --git a/src/components/task-master/hooks/useProjectPrdFiles.ts b/src/components/task-master/hooks/useProjectPrdFiles.ts
index 36ffa92a..e34b859b 100644
--- a/src/components/task-master/hooks/useProjectPrdFiles.ts
+++ b/src/components/task-master/hooks/useProjectPrdFiles.ts
@@ -3,7 +3,8 @@ import { api } from '../../../utils/api';
 import type { PrdFile } from '../types';
 
 type UseProjectPrdFilesOptions = {
-  projectName?: string;
+  // DB primary key of the project (post migration).
+  projectId?: string;
 };
 
 type PrdResponse = {
@@ -23,19 +24,19 @@ function normalizePrdResponse(responseData: PrdResponse): PrdFile[] {
   return [];
 }
 
-export function useProjectPrdFiles({ projectName }: UseProjectPrdFilesOptions) {
+export function useProjectPrdFiles({ projectId }: UseProjectPrdFilesOptions) {
   const [prdFiles, setPrdFiles] = useState<PrdFile[]>([]);
   const [isLoadingPrdFiles, setIsLoadingPrdFiles] = useState(false);
 
   const refreshPrdFiles = useCallback(async () => {
-    if (!projectName) {
+    if (!projectId) {
       setPrdFiles([]);
       return;
     }
 
     try {
       setIsLoadingPrdFiles(true);
-      const response = await api.get(`/taskmaster/prd/${encodeURIComponent(projectName)}`);
+      const response = await api.get(`/taskmaster/prd/${encodeURIComponent(projectId)}`);
 
       if (!response.ok) {
         setPrdFiles([]);
@@ -50,7 +51,7 @@ export function useProjectPrdFiles({ projectName }: UseProjectPrdFilesOptions) {
     } finally {
       setIsLoadingPrdFiles(false);
     }
-  }, [projectName]);
+  }, [projectId]);
 
   useEffect(() => {
     void refreshPrdFiles();
diff --git a/src/components/task-master/types.ts b/src/components/task-master/types.ts
index bfbebbe2..fda63716 100644
--- a/src/components/task-master/types.ts
+++ b/src/components/task-master/types.ts
@@ -90,7 +90,8 @@ export type TaskMasterMcpStatus = {
 
 export type TaskMasterWebSocketMessage = {
   type?: string;
-  projectName?: string;
+  // Post-migration TaskMaster broadcasts identify projects by `projectId`.
+  projectId?: string;
   [key: string]: unknown;
 };
 
diff --git a/src/components/task-master/view/TaskBoard.tsx b/src/components/task-master/view/TaskBoard.tsx
index 392cf15d..22a85a3f 100644
--- a/src/components/task-master/view/TaskBoard.tsx
+++ b/src/components/task-master/view/TaskBoard.tsx
@@ -72,13 +72,14 @@ export default function TaskBoard({
   );
 
   const loadPrdAndOpenEditor = async (prd: PrdFile) => {
-    if (!currentProject?.name) {
+    // Projects are addressed by DB projectId; see the projectName → projectId migration.
+    if (!currentProject?.projectId) {
       return;
     }
 
     try {
       const response = await api.get(
-        `/taskmaster/prd/${encodeURIComponent(currentProject.name)}/${encodeURIComponent(prd.name)}`,
+        `/taskmaster/prd/${encodeURIComponent(currentProject.projectId)}/${encodeURIComponent(prd.name)}`,
       );
 
       if (!response.ok) {
diff --git a/src/components/task-master/view/TaskMasterPanel.tsx b/src/components/task-master/view/TaskMasterPanel.tsx
index 78e9763c..8381cfdd 100644
--- a/src/components/task-master/view/TaskMasterPanel.tsx
+++ b/src/components/task-master/view/TaskMasterPanel.tsx
@@ -24,7 +24,7 @@ export default function TaskMasterPanel({ isVisible }: TaskMasterPanelProps) {
   const [prdNotification, setPrdNotification] = useState<string | null>(null);
   const notificationTimeoutRef = useRef<number | null>(null);
 
-  const { prdFiles, refreshPrdFiles } = useProjectPrdFiles({ projectName: currentProject?.name });
+  const { prdFiles, refreshPrdFiles } = useProjectPrdFiles({ projectId: currentProject?.projectId });
 
   const showPrdNotification = useCallback((message: string) => {
     if (notificationTimeoutRef.current) {
diff --git a/src/constants/config.ts b/src/constants/config.ts
index 853cfb43..6aa7885b 100644
--- a/src/constants/config.ts
+++ b/src/constants/config.ts
@@ -5,12 +5,16 @@
 export const IS_PLATFORM = import.meta.env.VITE_IS_PLATFORM === 'true';
 
 /**
- * For empty shell instances where no project is provided, 
- * we use a default project object to ensure the shell can still function. 
+ * For empty shell instances where no project is provided,
+ * we use a default project object to ensure the shell can still function.
  * This prevents errors related to missing project data.
+ *
+ * `projectId` is set to a well-known sentinel ('default') because the empty
+ * shell doesn't correspond to any real project row in the database; any API
+ * call that routes through this placeholder must tolerate a missing match.
  */
 export const DEFAULT_PROJECT_FOR_EMPTY_SHELL = {
-  name: 'default',
+  projectId: 'default',
   displayName: 'default',
   fullPath: IS_PLATFORM ? '/workspace' : '',
   path: IS_PLATFORM ? '/workspace' : '',
diff --git a/src/contexts/PaletteOpsContext.tsx b/src/contexts/PaletteOpsContext.tsx
new file mode 100644
index 00000000..c0281780
--- /dev/null
+++ b/src/contexts/PaletteOpsContext.tsx
@@ -0,0 +1,53 @@
+import { createContext, useContext, useEffect, useMemo, useRef } from 'react';
+import type { MutableRefObject, ReactNode } from 'react';
+
+export type PaletteOps = {
+  openFile: (path: string) => void;
+  openSettings: (tab?: string) => void;
+  refreshProjects: () => Promise<void> | void;
+};
+
+type Registry = MutableRefObject<Partial<PaletteOps>>;
+
+const PaletteOpsContext = createContext<Registry | null>(null);
+
+const defaultOps: PaletteOps = {
+  openFile: () => undefined,
+  openSettings: () => undefined,
+  refreshProjects: () => undefined,
+};
+
+export function PaletteOpsProvider({ children }: { children: ReactNode }) {
+  const ref = useRef<Partial<PaletteOps>>({});
+  return <PaletteOpsContext.Provider value={ref}>{children}</PaletteOpsContext.Provider>;
+}
+
+export function usePaletteOps(): PaletteOps {
+  const ref = useContext(PaletteOpsContext);
+  return useMemo<PaletteOps>(
+    () => ({
+      openFile: (path) => (ref?.current.openFile ?? defaultOps.openFile)(path),
+      openSettings: (tab) => (ref?.current.openSettings ?? defaultOps.openSettings)(tab),
+      refreshProjects: () => (ref?.current.refreshProjects ?? defaultOps.refreshProjects)(),
+    }),
+    [ref],
+  );
+}
+
+export function usePaletteOpsRegister(partial: Partial<PaletteOps>) {
+  const ref = useContext(PaletteOpsContext);
+  const { openFile, openSettings, refreshProjects } = partial;
+
+  useEffect(() => {
+    if (!ref) return undefined;
+    const prev = { ...ref.current };
+    if (openFile) ref.current.openFile = openFile;
+    if (openSettings) ref.current.openSettings = openSettings;
+    if (refreshProjects) ref.current.refreshProjects = refreshProjects;
+    return () => {
+      if (openFile && ref.current.openFile === openFile) ref.current.openFile = prev.openFile;
+      if (openSettings && ref.current.openSettings === openSettings) ref.current.openSettings = prev.openSettings;
+      if (refreshProjects && ref.current.refreshProjects === refreshProjects) ref.current.refreshProjects = prev.refreshProjects;
+    };
+  }, [ref, openFile, openSettings, refreshProjects]);
+}
diff --git a/src/hooks/useProjectsState.ts b/src/hooks/useProjectsState.ts
index 28cf682e..e6005693 100644
--- a/src/hooks/useProjectsState.ts
+++ b/src/hooks/useProjectsState.ts
@@ -1,9 +1,11 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type { NavigateFunction } from 'react-router-dom';
+
 import { api } from '../utils/api';
 import type {
   AppSocketMessage,
   AppTab,
+  LLMProvider,
   LoadingProgress,
   Project,
   ProjectSession,
@@ -40,9 +42,10 @@ const projectsHaveChanges = (
     }
 
     const baseChanged =
-      nextProject.name !== prevProject.name ||
+      nextProject.projectId !== prevProject.projectId ||
       nextProject.displayName !== prevProject.displayName ||
       nextProject.fullPath !== prevProject.fullPath ||
+      Boolean(nextProject.isStarred) !== Boolean(prevProject.isStarred) ||
       serialize(nextProject.sessionMeta) !== serialize(prevProject.sessionMeta) ||
       serialize(nextProject.sessions) !== serialize(prevProject.sessions) ||
       serialize(nextProject.taskmaster) !== serialize(prevProject.taskmaster);
@@ -58,20 +61,130 @@ const projectsHaveChanges = (
     return (
       serialize(nextProject.cursorSessions) !== serialize(prevProject.cursorSessions) ||
       serialize(nextProject.codexSessions) !== serialize(prevProject.codexSessions) ||
-      serialize(nextProject.geminiSessions) !== serialize(prevProject.geminiSessions)
+      serialize(nextProject.geminiSessions) !== serialize(prevProject.geminiSessions) ||
+      serialize(nextProject.opencodeSessions) !== serialize(prevProject.opencodeSessions)
     );
   });
 };
 
+const mergeTaskMasterCache = (nextProjects: Project[], previousProjects: Project[]): Project[] => {
+  if (previousProjects.length === 0) {
+    return nextProjects;
+  }
+
+  // Keyed by `projectId` (the DB primary key) so caches stay correct across
+  // renames and other mutations that might have changed the display name.
+  const previousTaskMasterByProject = new Map(
+    previousProjects
+      .filter((project) => Boolean(project.taskmaster))
+      .map((project) => [project.projectId, project.taskmaster]),
+  );
+
+  return nextProjects.map((project) => {
+    const cachedTaskMasterInfo = previousTaskMasterByProject.get(project.projectId);
+    if (!cachedTaskMasterInfo) {
+      return project;
+    }
+
+    return {
+      ...project,
+      taskmaster: cachedTaskMasterInfo,
+    };
+  });
+};
+
 const getProjectSessions = (project: Project): ProjectSession[] => {
   return [
     ...(project.sessions ?? []),
     ...(project.codexSessions ?? []),
     ...(project.cursorSessions ?? []),
     ...(project.geminiSessions ?? []),
+    ...(project.opencodeSessions ?? []),
   ];
 };
 
+const countLoadedProjectSessions = (project: Project): number => getProjectSessions(project).length;
+
+const mergeSessionProviderLists = (baseSessions: ProjectSession[], additionalSessions: ProjectSession[]): ProjectSession[] => {
+  const merged = [...baseSessions];
+  const seenSessionIds = new Set(baseSessions.map((session) => String(session.id)));
+
+  for (const session of additionalSessions) {
+    const sessionId = String(session.id);
+    if (seenSessionIds.has(sessionId)) {
+      continue;
+    }
+
+    merged.push(session);
+    seenSessionIds.add(sessionId);
+  }
+
+  return merged;
+};
+
+const mergeExpandedSessionPages = (previousProjects: Project[], incomingProjects: Project[]): Project[] => {
+  if (previousProjects.length === 0) {
+    return incomingProjects;
+  }
+
+  const previousByProjectId = new Map(previousProjects.map((project) => [project.projectId, project]));
+
+  return incomingProjects.map((incomingProject) => {
+    const previousProject = previousByProjectId.get(incomingProject.projectId);
+    if (!previousProject) {
+      return incomingProject;
+    }
+
+    const previousLoadedCount = countLoadedProjectSessions(previousProject);
+    const incomingLoadedCount = countLoadedProjectSessions(incomingProject);
+    if (previousLoadedCount <= incomingLoadedCount) {
+      return incomingProject;
+    }
+
+    const mergedProject: Project = {
+      ...incomingProject,
+      sessions: mergeSessionProviderLists(incomingProject.sessions ?? [], previousProject.sessions ?? []),
+      cursorSessions: mergeSessionProviderLists(incomingProject.cursorSessions ?? [], previousProject.cursorSessions ?? []),
+      codexSessions: mergeSessionProviderLists(incomingProject.codexSessions ?? [], previousProject.codexSessions ?? []),
+      geminiSessions: mergeSessionProviderLists(incomingProject.geminiSessions ?? [], previousProject.geminiSessions ?? []),
+      opencodeSessions: mergeSessionProviderLists(incomingProject.opencodeSessions ?? [], previousProject.opencodeSessions ?? []),
+    };
+
+    const totalSessions = Number(incomingProject.sessionMeta?.total ?? previousLoadedCount);
+    mergedProject.sessionMeta = {
+      ...incomingProject.sessionMeta,
+      total: totalSessions,
+      hasMore: countLoadedProjectSessions(mergedProject) < totalSessions,
+    };
+
+    return mergedProject;
+  });
+};
+
+const mergeProjectSessionPage = (
+  existingProject: Project,
+  sessionsPage: Pick<Project, 'sessions' | 'cursorSessions' | 'codexSessions' | 'geminiSessions' | 'opencodeSessions' | 'sessionMeta'>,
+): Project => {
+  const mergedProject: Project = {
+    ...existingProject,
+    sessions: mergeSessionProviderLists(existingProject.sessions ?? [], sessionsPage.sessions ?? []),
+    cursorSessions: mergeSessionProviderLists(existingProject.cursorSessions ?? [], sessionsPage.cursorSessions ?? []),
+    codexSessions: mergeSessionProviderLists(existingProject.codexSessions ?? [], sessionsPage.codexSessions ?? []),
+    geminiSessions: mergeSessionProviderLists(existingProject.geminiSessions ?? [], sessionsPage.geminiSessions ?? []),
+    opencodeSessions: mergeSessionProviderLists(existingProject.opencodeSessions ?? [], sessionsPage.opencodeSessions ?? []),
+  };
+
+  const totalSessions = Number(sessionsPage.sessionMeta?.total ?? existingProject.sessionMeta?.total ?? 0);
+  mergedProject.sessionMeta = {
+    ...existingProject.sessionMeta,
+    ...sessionsPage.sessionMeta,
+    total: totalSessions,
+    hasMore: countLoadedProjectSessions(mergedProject) < totalSessions,
+  };
+
+  return mergedProject;
+};
+
 const isUpdateAdditive = (
   currentProjects: Project[],
   updatedProjects: Project[],
@@ -82,8 +195,8 @@ const isUpdateAdditive = (
     return true;
   }
 
-  const currentSelectedProject = currentProjects.find((project) => project.name === selectedProject.name);
-  const updatedSelectedProject = updatedProjects.find((project) => project.name === selectedProject.name);
+  const currentSelectedProject = currentProjects.find((project) => project.projectId === selectedProject.projectId);
+  const updatedSelectedProject = updatedProjects.find((project) => project.projectId === selectedProject.projectId);
 
   if (!currentSelectedProject || !updatedSelectedProject) {
     return false;
@@ -153,8 +266,30 @@ export function useProjectsState({
   const [showSettings, setShowSettings] = useState(false);
   const [settingsInitialTab, setSettingsInitialTab] = useState('agents');
   const [externalMessageUpdate, setExternalMessageUpdate] = useState(0);
+  /**
+   * `newSessionTrigger` is an explicit, monotonic intent signal for user-driven
+   * New Session actions.
+   *
+   * It exists because `handleNewSession` can be invoked while the app is already in
+   * the same visible state (`selectedSession === null`, `activeTab === 'chat'`,
+   * route already `/`). In that case, React/router updates are idempotent and no
+   * downstream reset logic runs.
+   *
+   * Usage across the codebase:
+   * 1) Produced here in `handleNewSession` via increment (always changes).
+   * 2) Returned from this hook and threaded through:
+   *    useProjectsState -> AppContent -> MainContent -> ChatInterface.
+   * 3) Consumed in `useChatSessionState` as an effect dependency to forcibly clear
+   *    chat-local state (`currentSessionId`, pending draft message, streaming flags,
+   *    pending session storage keys, pagination/scroll artifacts).
+   *
+   * Keeping this signal dedicated avoids coupling resets to unrelated counters/events
+   * (for example websocket/project refresh updates) that could cause accidental resets.
+   */
+  const [newSessionTrigger, setNewSessionTrigger] = useState(0);
 
   const loadingProgressTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const lastHandledMessageRef = useRef<AppSocketMessage | null>(null);
 
   const fetchProjects = useCallback(async ({ showLoadingState = true }: FetchProjectsOptions = {}) => {
     try {
@@ -165,12 +300,15 @@ export function useProjectsState({
       const projectData = (await response.json()) as Project[];
 
       setProjects((prevProjects) => {
+        const projectsWithTaskMaster = mergeTaskMasterCache(projectData, prevProjects);
+        const mergedProjects = mergeExpandedSessionPages(prevProjects, projectsWithTaskMaster);
+
         if (prevProjects.length === 0) {
-          return projectData;
+          return mergedProjects;
         }
 
-        return projectsHaveChanges(prevProjects, projectData, true)
-          ? projectData
+        return projectsHaveChanges(prevProjects, mergedProjects, true)
+          ? mergedProjects
           : prevProjects;
       });
     } catch (error) {
@@ -187,6 +325,48 @@ export function useProjectsState({
     await fetchProjects({ showLoadingState: false });
   }, [fetchProjects]);
 
+  // Hydrates TaskMaster details for the given `projectId`. The project
+  // identifier comes directly from the DB-driven /api/projects response.
+  const hydrateProjectTaskMaster = useCallback(async (projectId: string) => {
+    if (!projectId) {
+      return;
+    }
+
+    try {
+      const response = await api.projectTaskmaster(projectId);
+      if (!response.ok) {
+        return;
+      }
+
+      const data = (await response.json()) as { taskmaster?: Project['taskmaster'] };
+      const taskMasterInfo = data.taskmaster;
+      if (!taskMasterInfo) {
+        return;
+      }
+
+      setProjects((previousProjects) =>
+        previousProjects.map((project) =>
+          project.projectId === projectId
+            ? { ...project, taskmaster: taskMasterInfo }
+            : project,
+        ),
+      );
+
+      setSelectedProject((previousProject) => {
+        if (!previousProject || previousProject.projectId !== projectId) {
+          return previousProject;
+        }
+
+        return {
+          ...previousProject,
+          taskmaster: taskMasterInfo,
+        };
+      });
+    } catch (error) {
+      console.error(`Error fetching TaskMaster info for project ${projectId}:`, error);
+    }
+  }, []);
+
   const openSettings = useCallback((tab = 'tools') => {
     setSettingsInitialTab(tab);
     setShowSettings(true);
@@ -196,6 +376,14 @@ export function useProjectsState({
     void fetchProjects();
   }, [fetchProjects]);
 
+  useEffect(() => {
+    if (!selectedProject?.projectId) {
+      return;
+    }
+
+    void hydrateProjectTaskMaster(selectedProject.projectId);
+  }, [hydrateProjectTaskMaster, selectedProject?.projectId]);
+
   // Auto-select the project when there is only one, so the user lands on the new session page
   useEffect(() => {
     if (!isLoadingProjects && projects.length === 1 && !selectedProject && !sessionId) {
@@ -208,6 +396,15 @@ export function useProjectsState({
       return;
     }
 
+    // `latestMessage` is event-like data. This effect also depends on local state
+    // (`projects`, `selectedProject`, `selectedSession`) to compute derived updates.
+    // Without this guard, handling one websocket message can update that local
+    // state, retrigger the effect, and re-handle the same websocket message.
+    if (lastHandledMessageRef.current === latestMessage) {
+      return;
+    }
+    lastHandledMessageRef.current = latestMessage;
+
     if (latestMessage.type === 'loading_progress') {
       if (loadingProgressTimeoutRef.current) {
         clearTimeout(loadingProgressTimeoutRef.current);
@@ -232,29 +429,20 @@ export function useProjectsState({
 
     const projectsMessage = latestMessage as ProjectsUpdatedMessage;
 
-    if (projectsMessage.changedFile && selectedSession && selectedProject) {
-      const normalized = projectsMessage.changedFile.replace(/\\/g, '/');
-      const changedFileParts = normalized.split('/');
+    if (projectsMessage.updatedSessionId && selectedSession && selectedProject) {
+      if (projectsMessage.updatedSessionId === selectedSession.id) {
+        const isSessionActive = activeSessions.has(selectedSession.id);
 
-      if (changedFileParts.length >= 2) {
-        const filename = changedFileParts[changedFileParts.length - 1];
-        const changedSessionId = filename.replace('.jsonl', '');
-
-        if (changedSessionId === selectedSession.id) {
-          const isSessionActive = activeSessions.has(selectedSession.id);
-
-          if (!isSessionActive) {
-            setExternalMessageUpdate((prev) => prev + 1);
-          }
+        if (!isSessionActive) {
+          setExternalMessageUpdate((prev) => prev + 1);
         }
       }
     }
 
-    const hasActiveSession =
-      (selectedSession && activeSessions.has(selectedSession.id)) ||
-      (activeSessions.size > 0 && Array.from(activeSessions).some((id) => id.startsWith('new-session-')));
+    const hasActiveSession = Boolean(selectedSession && activeSessions.has(selectedSession.id));
 
-    const updatedProjects = projectsMessage.projects;
+    const updatedProjectsWithTaskMaster = mergeTaskMasterCache(projectsMessage.projects, projects);
+    const updatedProjects = mergeExpandedSessionPages(projects, updatedProjectsWithTaskMaster);
 
     if (
       hasActiveSession &&
@@ -263,14 +451,16 @@ export function useProjectsState({
       return;
     }
 
-    setProjects(updatedProjects);
+    setProjects((previousProjects) =>
+      projectsHaveChanges(previousProjects, updatedProjects, true) ? updatedProjects : previousProjects,
+    );
 
     if (!selectedProject) {
       return;
     }
 
     const updatedSelectedProject = updatedProjects.find(
-      (project) => project.name === selectedProject.name,
+      (project) => project.projectId === selectedProject.projectId,
     );
 
     if (!updatedSelectedProject) {
@@ -308,10 +498,11 @@ export function useProjectsState({
       return;
     }
 
+    // Project membership is resolved through `projectId` after the migration.
     for (const project of projects) {
       const claudeSession = project.sessions?.find((session) => session.id === sessionId);
       if (claudeSession) {
-        const shouldUpdateProject = selectedProject?.name !== project.name;
+        const shouldUpdateProject = selectedProject?.projectId !== project.projectId;
         const shouldUpdateSession =
           selectedSession?.id !== sessionId || selectedSession.__provider !== 'claude';
 
@@ -326,7 +517,7 @@ export function useProjectsState({
 
       const cursorSession = project.cursorSessions?.find((session) => session.id === sessionId);
       if (cursorSession) {
-        const shouldUpdateProject = selectedProject?.name !== project.name;
+        const shouldUpdateProject = selectedProject?.projectId !== project.projectId;
         const shouldUpdateSession =
           selectedSession?.id !== sessionId || selectedSession.__provider !== 'cursor';
 
@@ -341,7 +532,7 @@ export function useProjectsState({
 
       const codexSession = project.codexSessions?.find((session) => session.id === sessionId);
       if (codexSession) {
-        const shouldUpdateProject = selectedProject?.name !== project.name;
+        const shouldUpdateProject = selectedProject?.projectId !== project.projectId;
         const shouldUpdateSession =
           selectedSession?.id !== sessionId || selectedSession.__provider !== 'codex';
 
@@ -356,7 +547,7 @@ export function useProjectsState({
 
       const geminiSession = project.geminiSessions?.find((session) => session.id === sessionId);
       if (geminiSession) {
-        const shouldUpdateProject = selectedProject?.name !== project.name;
+        const shouldUpdateProject = selectedProject?.projectId !== project.projectId;
         const shouldUpdateSession =
           selectedSession?.id !== sessionId || selectedSession.__provider !== 'gemini';
 
@@ -368,8 +559,60 @@ export function useProjectsState({
         }
         return;
       }
+
+      const opencodeSession = project.opencodeSessions?.find((session) => session.id === sessionId);
+      if (opencodeSession) {
+        const shouldUpdateProject = selectedProject?.projectId !== project.projectId;
+        const shouldUpdateSession =
+          selectedSession?.id !== sessionId || selectedSession.__provider !== 'opencode';
+
+        if (shouldUpdateProject) {
+          setSelectedProject(project);
+        }
+        if (shouldUpdateSession) {
+          setSelectedSession({ ...opencodeSession, __provider: 'opencode' });
+        }
+        return;
+      }
     }
-  }, [sessionId, projects, selectedProject?.name, selectedSession?.id, selectedSession?.__provider]);
+
+    // Session id is in the URL but not yet present on any project payload (common
+    // right after `session_created` + navigate, before the next projects refresh).
+    // Without a `selectedSession`, chat state clears `currentSessionId` and the
+    // UI stops reading the session store even though messages stream under this id.
+    if (selectedSession?.id === sessionId) {
+      return;
+    }
+
+    if (!selectedProject) {
+      return;
+    }
+
+    let providerFromStorage: string | null = null;
+    try {
+      providerFromStorage = localStorage.getItem('selected-provider');
+    } catch {
+      providerFromStorage = null;
+    }
+
+    const normalizedProvider: LLMProvider =
+      providerFromStorage === 'cursor'
+        ? 'cursor'
+        : providerFromStorage === 'codex'
+          ? 'codex'
+          : providerFromStorage === 'gemini'
+            ? 'gemini'
+            : providerFromStorage === 'opencode'
+              ? 'opencode'
+            : 'claude';
+
+    setSelectedSession({
+      id: sessionId,
+      __provider: normalizedProvider,
+      __projectId: selectedProject.projectId,
+      summary: '',
+    });
+  }, [sessionId, projects, selectedProject, selectedSession?.id, selectedSession?.__provider]);
 
   const handleProjectSelect = useCallback(
     (project: Project) => {
@@ -398,17 +641,21 @@ export function useProjectsState({
       }
 
       if (isMobile) {
-        const sessionProjectName = session.__projectName;
-        const currentProjectName = selectedProject?.name;
+        // Sessions are tagged with the owning project's DB `projectId` when
+        // picked from the sidebar (see useSidebarController); compare against
+        // the current selection's `projectId` so we know whether to collapse
+        // the sidebar after navigation.
+        const sessionProjectId = session.__projectId;
+        const currentProjectId = selectedProject?.projectId;
 
-        if (sessionProjectName !== currentProjectName) {
+        if (sessionProjectId !== currentProjectId) {
           setSidebarOpen(false);
         }
       }
 
       navigate(`/session/${session.id}`);
     },
-    [activeTab, isMobile, navigate, selectedProject?.name],
+    [activeTab, isMobile, navigate, selectedProject?.projectId],
   );
 
   const handleNewSession = useCallback(
@@ -416,6 +663,7 @@ export function useProjectsState({
       setSelectedProject(project);
       setSelectedSession(null);
       setActiveTab('chat');
+      setNewSessionTrigger((previous) => previous + 1);
       navigate('/');
 
       if (isMobile) {
@@ -433,14 +681,43 @@ export function useProjectsState({
       }
 
       setProjects((prevProjects) =>
-        prevProjects.map((project) => ({
-          ...project,
-          sessions: project.sessions?.filter((session) => session.id !== sessionIdToDelete) ?? [],
-          sessionMeta: {
+        prevProjects.map((project) => {
+          const sessions = project.sessions?.filter((session) => session.id !== sessionIdToDelete) ?? [];
+          const cursorSessions = project.cursorSessions?.filter((session) => session.id !== sessionIdToDelete) ?? [];
+          const codexSessions = project.codexSessions?.filter((session) => session.id !== sessionIdToDelete) ?? [];
+          const geminiSessions = project.geminiSessions?.filter((session) => session.id !== sessionIdToDelete) ?? [];
+          const opencodeSessions = project.opencodeSessions?.filter((session) => session.id !== sessionIdToDelete) ?? [];
+
+          const removedFromProject = (
+            sessions.length !== (project.sessions?.length ?? 0)
+            || cursorSessions.length !== (project.cursorSessions?.length ?? 0)
+            || codexSessions.length !== (project.codexSessions?.length ?? 0)
+            || geminiSessions.length !== (project.geminiSessions?.length ?? 0)
+            || opencodeSessions.length !== (project.opencodeSessions?.length ?? 0)
+          );
+
+          if (!removedFromProject) {
+            return project;
+          }
+
+          const updatedProject: Project = {
+            ...project,
+            sessions,
+            cursorSessions,
+            codexSessions,
+            geminiSessions,
+            opencodeSessions,
+          };
+
+          const totalSessions = Math.max(0, Number(project.sessionMeta?.total ?? 0) - 1);
+          updatedProject.sessionMeta = {
             ...project.sessionMeta,
-            total: Math.max(0, (project.sessionMeta?.total as number | undefined ?? 0) - 1),
-          },
-        })),
+            total: totalSessions,
+            hasMore: countLoadedProjectSessions(updatedProject) < totalSessions,
+          };
+
+          return updatedProject;
+        }),
       );
     },
     [navigate, selectedSession?.id],
@@ -450,16 +727,18 @@ export function useProjectsState({
     try {
       const response = await api.projects();
       const freshProjects = (await response.json()) as Project[];
+      const projectsWithTaskMaster = mergeTaskMasterCache(freshProjects, projects);
+      const mergedProjects = mergeExpandedSessionPages(projects, projectsWithTaskMaster);
 
       setProjects((prevProjects) =>
-        projectsHaveChanges(prevProjects, freshProjects, true) ? freshProjects : prevProjects,
+        projectsHaveChanges(prevProjects, mergedProjects, true) ? mergedProjects : prevProjects,
       );
 
       if (!selectedProject) {
         return;
       }
 
-      const refreshedProject = freshProjects.find((project) => project.name === selectedProject.name);
+      const refreshedProject = mergedProjects.find((project) => project.projectId === selectedProject.projectId);
       if (!refreshedProject) {
         return;
       }
@@ -490,19 +769,70 @@ export function useProjectsState({
     } catch (error) {
       console.error('Error refreshing sidebar:', error);
     }
-  }, [selectedProject, selectedSession]);
+  }, [projects, selectedProject, selectedSession]);
 
+  const loadMoreProjectSessions = useCallback(async (projectId: string) => {
+    const project = projects.find((candidate) => candidate.projectId === projectId);
+    if (!project) {
+      return;
+    }
+
+    const loadedCount = countLoadedProjectSessions(project);
+    const totalCount = Number(project.sessionMeta?.total ?? 0);
+    if (totalCount > 0 && loadedCount >= totalCount) {
+      return;
+    }
+
+    const response = await api.projectSessions(projectId, {
+      limit: 20,
+      offset: loadedCount,
+    });
+
+    if (!response.ok) {
+      const payload = (await response.json().catch(() => ({}))) as { error?: string | { message?: string } };
+      const errorPayload = payload.error;
+      const message =
+        typeof errorPayload === 'string'
+          ? errorPayload
+          : errorPayload && typeof errorPayload === 'object' && errorPayload.message
+            ? errorPayload.message
+            : `Failed to load more sessions for project ${projectId}`;
+      throw new Error(message);
+    }
+
+    const sessionsPage = (await response.json()) as Pick<Project, 'sessions' | 'cursorSessions' | 'codexSessions' | 'geminiSessions' | 'opencodeSessions' | 'sessionMeta'>;
+
+    let mergedProjectForSelection: Project | null = null;
+    setProjects((previousProjects) =>
+      previousProjects.map((candidate) => {
+        if (candidate.projectId !== projectId) {
+          return candidate;
+        }
+
+        const mergedProject = mergeProjectSessionPage(candidate, sessionsPage);
+        mergedProjectForSelection = mergedProject;
+        return mergedProject;
+      }),
+    );
+
+    if (selectedProject?.projectId === projectId && mergedProjectForSelection) {
+      setSelectedProject(mergedProjectForSelection);
+    }
+  }, [projects, selectedProject?.projectId]);
+
+  // `projectId` is the DB identifier passed from the sidebar's delete flow
+  // after the migration away from folder-derived project names.
   const handleProjectDelete = useCallback(
-    (projectName: string) => {
-      if (selectedProject?.name === projectName) {
+    (projectId: string) => {
+      if (selectedProject?.projectId === projectId) {
         setSelectedProject(null);
         setSelectedSession(null);
         navigate('/');
       }
 
-      setProjects((prevProjects) => prevProjects.filter((project) => project.name !== projectName));
+      setProjects((prevProjects) => prevProjects.filter((project) => project.projectId !== projectId));
     },
-    [navigate, selectedProject?.name],
+    [navigate, selectedProject?.projectId],
   );
 
   const sidebarSharedProps = useMemo(
@@ -514,6 +844,7 @@ export function useProjectsState({
       onSessionSelect: handleSessionSelect,
       onNewSession: handleNewSession,
       onSessionDelete: handleSessionDelete,
+      onLoadMoreSessions: loadMoreProjectSessions,
       onProjectDelete: handleProjectDelete,
       isLoading: isLoadingProjects,
       loadingProgress,
@@ -529,6 +860,7 @@ export function useProjectsState({
       handleProjectDelete,
       handleProjectSelect,
       handleSessionDelete,
+      loadMoreProjectSessions,
       handleSessionSelect,
       handleSidebarRefresh,
       isLoadingProjects,
@@ -554,6 +886,7 @@ export function useProjectsState({
     showSettings,
     settingsInitialTab,
     externalMessageUpdate,
+    newSessionTrigger,
     setActiveTab,
     setSidebarOpen,
     setIsInputFocused,
@@ -566,6 +899,7 @@ export function useProjectsState({
     handleSessionSelect,
     handleNewSession,
     handleSessionDelete,
+    loadMoreProjectSessions,
     handleProjectDelete,
     handleSidebarRefresh,
   };
diff --git a/src/hooks/useServerPlatform.ts b/src/hooks/useServerPlatform.ts
deleted file mode 100644
index c8d84f79..00000000
--- a/src/hooks/useServerPlatform.ts
+++ /dev/null
@@ -1,40 +0,0 @@
-import { useEffect, useState } from 'react';
-
-import { authenticatedFetch } from '../utils/api';
-
-/**
- * Node `process.platform` from the API host (e.g. win32, darwin, linux).
- * Null until loaded or if the request fails.
- */
-export function useServerPlatform(): {
-  serverPlatform: string | null;
-  isWindowsServer: boolean;
-} {
-  const [serverPlatform, setServerPlatform] = useState<string | null>(null);
-
-  useEffect(() => {
-    let cancelled = false;
-    (async () => {
-      try {
-        const response = await authenticatedFetch('/api/settings/server-env');
-        if (!response.ok) {
-          return;
-        }
-        const body = (await response.json()) as { platform?: string };
-        if (!cancelled && typeof body.platform === 'string') {
-          setServerPlatform(body.platform);
-        }
-      } catch {
-        // Keep null: treat as unknown host.
-      }
-    })();
-    return () => {
-      cancelled = true;
-    };
-  }, []);
-
-  return {
-    serverPlatform,
-    isWindowsServer: serverPlatform === 'win32',
-  };
-}
diff --git a/src/hooks/useSessionProtection.ts b/src/hooks/useSessionProtection.ts
index 0c3d1bab..cbdcdda1 100644
--- a/src/hooks/useSessionProtection.ts
+++ b/src/hooks/useSessionProtection.ts
@@ -44,23 +44,6 @@ export function useSessionProtection() {
     });
   }, []);
 
-  const replaceTemporarySession = useCallback((realSessionId?: string | null) => {
-    if (!realSessionId) {
-      return;
-    }
-
-    setActiveSessions((prev) => {
-      const next = new Set<string>();
-      for (const sessionId of prev) {
-        if (!sessionId.startsWith('new-session-')) {
-          next.add(sessionId);
-        }
-      }
-      next.add(realSessionId);
-      return next;
-    });
-  }, []);
-
   return {
     activeSessions,
     processingSessions,
@@ -68,6 +51,5 @@ export function useSessionProtection() {
     markSessionAsInactive,
     markSessionAsProcessing,
     markSessionAsNotProcessing,
-    replaceTemporarySession,
   };
 }
diff --git a/src/i18n/config.js b/src/i18n/config.js
index 16a9330e..7fcda777 100644
--- a/src/i18n/config.js
+++ b/src/i18n/config.js
@@ -187,7 +187,7 @@ i18n
     fallbackLng: 'en',
 
     // Enable debug mode in development (logs missing keys to console)
-    debug: import.meta.env.DEV,
+    debug: false,
 
     // Namespaces - load only what's needed
     ns: ['common', 'settings', 'auth', 'sidebar', 'chat', 'codeEditor', 'tasks'],
diff --git a/src/i18n/locales/de/chat.json b/src/i18n/locales/de/chat.json
index 4d978bcf..1737114a 100644
--- a/src/i18n/locales/de/chat.json
+++ b/src/i18n/locales/de/chat.json
@@ -89,12 +89,14 @@
     "permissionMode": "Berechtigungsmodus",
     "modes": {
       "default": "Standardmodus",
+      "auto": "Auto Mode",
       "acceptEdits": "Bearbeitungen akzeptieren",
       "bypassPermissions": "Berechtigungen umgehen",
       "plan": "Planungsmodus"
     },
     "descriptions": {
       "default": "Nur vertrauenswürdige Befehle (ls, cat, grep, git status usw.) werden automatisch ausgeführt. Andere Befehle werden übersprungen. Kann in den Arbeitsbereich schreiben.",
+      "auto": "A model classifier decides per tool call whether to approve or deny. Hands-off, but safer than Bypass — denials still happen.",
       "acceptEdits": "Alle Befehle werden automatisch innerhalb des Arbeitsbereichs ausgeführt. Vollautomatischer Modus mit isolierter Ausführung.",
       "bypassPermissions": "Vollständiger Systemzugriff ohne Einschränkungen. Alle Befehle werden automatisch mit vollem Festplatten- und Netzwerkzugriff ausgeführt. Mit Vorsicht verwenden.",
       "plan": "Planungsmodus – keine Befehle werden ausgeführt"
@@ -188,7 +190,8 @@
       "codex": "Bereit, Codex mit {{model}} zu verwenden. Gib unten deine Nachricht ein.",
       "gemini": "Bereit, Gemini mit {{model}} zu verwenden. Gib unten deine Nachricht ein.",
       "default": "Wähl oben einen Anbieter, um zu beginnen"
-    }
+    },
+    "pressToSearch": "Drücke <kbd>{{shortcut}}</kbd>, um Sitzungen, Dateien und Commits zu durchsuchen"
   },
   "session": {
     "continue": {
diff --git a/src/i18n/locales/de/common.json b/src/i18n/locales/de/common.json
index bc4c7473..94260cff 100644
--- a/src/i18n/locales/de/common.json
+++ b/src/i18n/locales/de/common.json
@@ -176,7 +176,6 @@
     },
     "step3": {
       "reviewConfig": "Konfiguration überprüfen",
-      "workspaceType": "Arbeitsbereichstyp:",
       "existingWorkspace": "Vorhandener Arbeitsbereich",
       "newWorkspace": "Neuer Arbeitsbereich",
       "path": "Pfad:",
diff --git a/src/i18n/locales/de/sidebar.json b/src/i18n/locales/de/sidebar.json
index b2df5190..48070815 100644
--- a/src/i18n/locales/de/sidebar.json
+++ b/src/i18n/locales/de/sidebar.json
@@ -45,9 +45,11 @@
     "removeFromFavorites": "Aus Favoriten entfernen",
     "editSessionName": "Sitzungsname manuell bearbeiten",
     "deleteSession": "Diese Sitzung dauerhaft löschen",
+    "activeSessionIndicator": "Kürzlich aktive Sitzung (letzte 10 Minuten)",
     "save": "Speichern",
     "cancel": "Abbrechen",
-    "clearSearch": "Suche leeren"
+    "clearSearch": "Suche leeren",
+    "openCommandPalette": "Befehlspalette öffnen"
   },
   "navigation": {
     "chat": "Chat",
diff --git a/src/i18n/locales/en/chat.json b/src/i18n/locales/en/chat.json
index dadaea89..2f5af581 100644
--- a/src/i18n/locales/en/chat.json
+++ b/src/i18n/locales/en/chat.json
@@ -18,7 +18,8 @@
     "claude": "Claude",
     "cursor": "Cursor",
     "codex": "Codex",
-    "gemini": "Gemini"
+    "gemini": "Gemini",
+    "opencode": "OpenCode"
   },
   "tools": {
     "settings": "Tool Settings",
@@ -89,12 +90,14 @@
     "permissionMode": "Permission Mode",
     "modes": {
       "default": "Default Mode",
+      "auto": "Auto Mode",
       "acceptEdits": "Accept Edits",
       "bypassPermissions": "Bypass Permissions",
       "plan": "Plan Mode"
     },
     "descriptions": {
       "default": "Only trusted commands (ls, cat, grep, git status, etc.) run automatically. Other commands are skipped. Can write to workspace.",
+      "auto": "A model classifier decides per tool call whether to approve or deny. Hands-off, but safer than Bypass — denials still happen.",
       "acceptEdits": "All commands run automatically within the workspace. Full auto mode with sandboxed execution.",
       "bypassPermissions": "Full system access with no restrictions. All commands run automatically with full disk and network access. Use with caution.",
       "plan": "Planning mode - no commands are executed"
@@ -187,8 +190,10 @@
       "cursor": "Ready to use Cursor with {{model}}. Start typing your message below.",
       "codex": "Ready to use Codex with {{model}}. Start typing your message below.",
       "gemini": "Ready to use Gemini with {{model}}. Start typing your message below.",
+      "opencode": "Ready to use OpenCode with {{model}}. Start typing your message below.",
       "default": "Select a provider above to begin"
-    }
+    },
+    "pressToSearch": "Press <kbd>{{shortcut}}</kbd> to search sessions, files, and commits"
   },
   "session": {
     "continue": {
diff --git a/src/i18n/locales/en/common.json b/src/i18n/locales/en/common.json
index 0d25fedf..f35eb3c5 100644
--- a/src/i18n/locales/en/common.json
+++ b/src/i18n/locales/en/common.json
@@ -176,7 +176,6 @@
     },
     "step3": {
       "reviewConfig": "Review Your Configuration",
-      "workspaceType": "Workspace Type:",
       "existingWorkspace": "Existing Workspace",
       "newWorkspace": "New Workspace",
       "path": "Path:",
diff --git a/src/i18n/locales/en/settings.json b/src/i18n/locales/en/settings.json
index 1285ac3f..b80d17d2 100644
--- a/src/i18n/locales/en/settings.json
+++ b/src/i18n/locales/en/settings.json
@@ -322,6 +322,9 @@
       },
       "gemini": {
         "description": "Google Gemini AI assistant"
+      },
+      "opencode": {
+        "description": "OpenCode CLI assistant"
       }
     },
     "connectionStatus": "Connection Status",
@@ -416,7 +419,8 @@
     "description": {
       "claude": "Model Context Protocol servers provide additional tools and data sources to Claude",
       "cursor": "Model Context Protocol servers provide additional tools and data sources to Cursor",
-      "codex": "Model Context Protocol servers provide additional tools and data sources to Codex"
+      "codex": "Model Context Protocol servers provide additional tools and data sources to Codex",
+      "opencode": "Model Context Protocol servers provide additional tools and data sources to OpenCode"
     },
     "addButton": "Add MCP Server",
     "empty": "No MCP servers configured",
@@ -468,6 +472,12 @@
     "starterPluginLabel": "Starter Plugin",
     "starter": "Starter",
     "docs": "Docs",
+    "sections": {
+      "officialTitle": "Official Plugins",
+      "officialDescription": "Maintained by the CloudCLI team and ready for direct install.",
+      "unofficialTitle": "Other Plugins",
+      "unofficialDescription": "Unofficial plugins and integrations from other users. Review the source before installing."
+    },
     "starterPlugin": {
       "name": "Project Stats",
       "badge": "starter",
@@ -480,6 +490,18 @@
       "description": "Integrated terminal with full shell access directly within the interface.",
       "install": "Install"
     },
+    "scheduledPromptPlugin": {
+      "name": "Scheduled Prompts",
+      "badge": "unofficial",
+      "description": "Schedule workspace prompts, review run history, and manage recurring local tasks.",
+      "install": "Install"
+    },
+    "claudeWatchPlugin": {
+      "name": "Claude Watch",
+      "badge": "unofficial",
+      "description": "Watch long-running Claude Code sessions for hangs and expose process controls.",
+      "install": "Install"
+    },
     "morePlugins": "More",
     "enable": "Enable",
     "disable": "Disable",
diff --git a/src/i18n/locales/en/sidebar.json b/src/i18n/locales/en/sidebar.json
index 7b3452cb..755729a7 100644
--- a/src/i18n/locales/en/sidebar.json
+++ b/src/i18n/locales/en/sidebar.json
@@ -45,9 +45,11 @@
     "removeFromFavorites": "Remove from favorites",
     "editSessionName": "Manually edit session name",
     "deleteSession": "Delete this session permanently",
+    "activeSessionIndicator": "Recently active session (last 10 minutes)",
     "save": "Save",
     "cancel": "Cancel",
-    "clearSearch": "Clear search"
+    "clearSearch": "Clear search",
+    "openCommandPalette": "Open command palette"
   },
   "navigation": {
     "chat": "Chat",
diff --git a/src/i18n/locales/it/chat.json b/src/i18n/locales/it/chat.json
index 78a7555a..848e5bfb 100644
--- a/src/i18n/locales/it/chat.json
+++ b/src/i18n/locales/it/chat.json
@@ -89,12 +89,14 @@
     "permissionMode": "Modalità permessi",
     "modes": {
       "default": "Modalità predefinita",
+      "auto": "Auto Mode",
       "acceptEdits": "Accetta modifiche",
       "bypassPermissions": "Ignora permessi",
       "plan": "Modalità piano"
     },
     "descriptions": {
       "default": "Solo i comandi attendibili (ls, cat, grep, git status, ecc.) vengono eseguiti automaticamente. Gli altri comandi vengono saltati. Può scrivere nell'area di lavoro.",
+      "auto": "A model classifier decides per tool call whether to approve or deny. Hands-off, but safer than Bypass — denials still happen.",
       "acceptEdits": "Tutti i comandi vengono eseguiti automaticamente nell'area di lavoro. Modalità completamente automatica con esecuzione sandboxed.",
       "bypassPermissions": "Accesso completo al sistema senza restrizioni. Tutti i comandi vengono eseguiti automaticamente con accesso completo a disco e rete. Usa con cautela.",
       "plan": "Modalità pianificazione - nessun comando viene eseguito"
@@ -188,7 +190,8 @@
       "codex": "Pronto a usare Codex con {{model}}. Inizia a digitare il tuo messaggio qui sotto.",
       "gemini": "Pronto a usare Gemini con {{model}}. Inizia a digitare il tuo messaggio qui sotto.",
       "default": "Seleziona un provider sopra per iniziare"
-    }
+    },
+    "pressToSearch": "Premi <kbd>{{shortcut}}</kbd> per cercare sessioni, file e commit"
   },
   "session": {
     "continue": {
diff --git a/src/i18n/locales/it/common.json b/src/i18n/locales/it/common.json
index ff890937..7993c69d 100644
--- a/src/i18n/locales/it/common.json
+++ b/src/i18n/locales/it/common.json
@@ -176,7 +176,6 @@
     },
     "step3": {
       "reviewConfig": "Rivedi la tua configurazione",
-      "workspaceType": "Tipo area di lavoro:",
       "existingWorkspace": "Area di lavoro esistente",
       "newWorkspace": "Nuova area di lavoro",
       "path": "Percorso:",
diff --git a/src/i18n/locales/it/sidebar.json b/src/i18n/locales/it/sidebar.json
index 79a71bad..dfad2684 100644
--- a/src/i18n/locales/it/sidebar.json
+++ b/src/i18n/locales/it/sidebar.json
@@ -45,9 +45,11 @@
     "removeFromFavorites": "Rimuovi dai preferiti",
     "editSessionName": "Modifica manualmente il nome della sessione",
     "deleteSession": "Elimina questa sessione permanentemente",
+    "activeSessionIndicator": "Sessione attiva di recente (ultimi 10 minuti)",
     "save": "Salva",
     "cancel": "Annulla",
-    "clearSearch": "Cancella ricerca"
+    "clearSearch": "Cancella ricerca",
+    "openCommandPalette": "Apri tavolozza comandi"
   },
   "navigation": {
     "chat": "Chat",
diff --git a/src/i18n/locales/ja/chat.json b/src/i18n/locales/ja/chat.json
index 10e03192..780bf76c 100644
--- a/src/i18n/locales/ja/chat.json
+++ b/src/i18n/locales/ja/chat.json
@@ -88,12 +88,14 @@
     "permissionMode": "権限モード",
     "modes": {
       "default": "デフォルトモード",
+      "auto": "Auto Mode",
       "acceptEdits": "編集を許可",
       "bypassPermissions": "権限をバイパス",
       "plan": "プランモード"
     },
     "descriptions": {
       "default": "信頼されたコマンド（ls、cat、grep、git statusなど）のみ自動実行。その他のコマンドはスキップ。ワークスペースへの書き込みは可能。",
+      "auto": "A model classifier decides per tool call whether to approve or deny. Hands-off, but safer than Bypass — denials still happen.",
       "acceptEdits": "ワークスペース内ですべてのコマンドを自動実行。サンドボックス環境での完全自動モード。",
       "bypassPermissions": "制限なしの完全なシステムアクセス。すべてのコマンドがディスクとネットワークへの完全なアクセスで自動実行されます。注意して使用してください。",
       "plan": "プランニングモード - コマンドは実行されません"
@@ -165,7 +167,8 @@
       "cursor": "{{model}}でCursorを使用する準備ができました。下にメッセージを入力してください。",
       "codex": "{{model}}でCodexを使用する準備ができました。下にメッセージを入力してください。",
       "default": "上からプロバイダーを選択して開始してください"
-    }
+    },
+    "pressToSearch": "<kbd>{{shortcut}}</kbd> を押してセッション、ファイル、コミットを検索"
   },
   "session": {
     "continue": {
diff --git a/src/i18n/locales/ja/common.json b/src/i18n/locales/ja/common.json
index 097eb057..0651e25c 100644
--- a/src/i18n/locales/ja/common.json
+++ b/src/i18n/locales/ja/common.json
@@ -176,7 +176,6 @@
     },
     "step3": {
       "reviewConfig": "設定の確認",
-      "workspaceType": "ワークスペースの種類:",
       "existingWorkspace": "既存のワークスペース",
       "newWorkspace": "新しいワークスペース",
       "path": "パス:",
diff --git a/src/i18n/locales/ja/sidebar.json b/src/i18n/locales/ja/sidebar.json
index 33c17399..4116178a 100644
--- a/src/i18n/locales/ja/sidebar.json
+++ b/src/i18n/locales/ja/sidebar.json
@@ -45,8 +45,10 @@
     "removeFromFavorites": "お気に入りから削除",
     "editSessionName": "セッション名を手動で編集",
     "deleteSession": "このセッションを完全に削除",
+    "activeSessionIndicator": "最近アクティブなセッション（過去10分以内）",
     "save": "保存",
-    "cancel": "キャンセル"
+    "cancel": "キャンセル",
+    "openCommandPalette": "コマンドパレットを開く"
   },
   "navigation": {
     "chat": "チャット",
diff --git a/src/i18n/locales/ko/chat.json b/src/i18n/locales/ko/chat.json
index aaf5b45c..545f35ce 100644
--- a/src/i18n/locales/ko/chat.json
+++ b/src/i18n/locales/ko/chat.json
@@ -89,12 +89,14 @@
     "permissionMode": "권한 모드",
     "modes": {
       "default": "기본 모드",
+      "auto": "Auto Mode",
       "acceptEdits": "편집 허용",
       "bypassPermissions": "권한 우회",
       "plan": "Plan 모드"
     },
     "descriptions": {
       "default": "신뢰할 수 있는 명령어(ls, cat, grep, git status 등)만 자동 실행됩니다. 다른 명령어는 건너뜁니다. 워크스페이스에 쓰기 가능.",
+      "auto": "A model classifier decides per tool call whether to approve or deny. Hands-off, but safer than Bypass — denials still happen.",
       "acceptEdits": "워크스페이스 내에서 모든 명령어가 자동 실행됩니다. 샌드박스 내 완전 자동 모드.",
       "bypassPermissions": "제한 없는 전체 시스템 접근. 모든 명령어가 전체 디스크 및 네트워크 접근 권한으로 자동 실행됩니다. 주의해서 사용하세요.",
       "plan": "계획 모드 - 명령어가 실행되지 않습니다"
@@ -170,7 +172,8 @@
       "codex": "{{model}} 모델로 Codex를 사용할 준비가 되었습니다. 아래에 메시지를 입력하세요.",
       "gemini": "{{model}} 모델로 Gemini를 사용할 준비가 되었습니다. 아래에 메시지를 입력하세요.",
       "default": "시작하려면 위에서 제공자를 선택하세요"
-    }
+    },
+    "pressToSearch": "<kbd>{{shortcut}}</kbd>를 눌러 세션, 파일 및 커밋을 검색하세요"
   },
   "session": {
     "continue": {
diff --git a/src/i18n/locales/ko/common.json b/src/i18n/locales/ko/common.json
index b3554401..fcf1de52 100644
--- a/src/i18n/locales/ko/common.json
+++ b/src/i18n/locales/ko/common.json
@@ -176,7 +176,6 @@
     },
     "step3": {
       "reviewConfig": "설정 검토",
-      "workspaceType": "워크스페이스 유형:",
       "existingWorkspace": "기존 워크스페이스",
       "newWorkspace": "새 워크스페이스",
       "path": "경로:",
diff --git a/src/i18n/locales/ko/sidebar.json b/src/i18n/locales/ko/sidebar.json
index d7fcafaa..360da6f8 100644
--- a/src/i18n/locales/ko/sidebar.json
+++ b/src/i18n/locales/ko/sidebar.json
@@ -45,8 +45,10 @@
     "removeFromFavorites": "즐겨찾기에서 제거",
     "editSessionName": "세션 이름 직접 편집",
     "deleteSession": "이 세션 영구 삭제",
+    "activeSessionIndicator": "최근 활성 세션 (지난 10분)",
     "save": "저장",
-    "cancel": "취소"
+    "cancel": "취소",
+    "openCommandPalette": "명령 팔레트 열기"
   },
   "navigation": {
     "chat": "채팅",
diff --git a/src/i18n/locales/ru/chat.json b/src/i18n/locales/ru/chat.json
index a1c5e277..4be43572 100644
--- a/src/i18n/locales/ru/chat.json
+++ b/src/i18n/locales/ru/chat.json
@@ -89,12 +89,14 @@
     "permissionMode": "Режим разрешений",
     "modes": {
       "default": "Режим по умолчанию",
+      "auto": "Auto Mode",
       "acceptEdits": "Принимать правки",
       "bypassPermissions": "Обход разрешений",
       "plan": "Режим планирования"
     },
     "descriptions": {
       "default": "Только доверенные команды (ls, cat, grep, git status и т.д.) выполняются автоматически. Другие команды пропускаются. Может записывать в рабочее пространство.",
+      "auto": "A model classifier decides per tool call whether to approve or deny. Hands-off, but safer than Bypass — denials still happen.",
       "acceptEdits": "Все команды выполняются автоматически в рабочем пространстве. Полный автоматический режим с изолированным выполнением.",
       "bypassPermissions": "Полный системный доступ без ограничений. Все команды выполняются автоматически с полным доступом к диску и сети. Используйте с осторожностью.",
       "plan": "Режим планирования - команды не выполняются"
@@ -188,7 +190,8 @@
       "codex": "Готов использовать Codex с {{model}}. Начните вводить сообщение ниже.",
       "gemini": "Готов использовать Gemini с {{model}}. Начните вводить сообщение ниже.",
       "default": "Выберите провайдера выше для начала"
-    }
+    },
+    "pressToSearch": "Нажмите <kbd>{{shortcut}}</kbd>, чтобы искать сессии, файлы и коммиты"
   },
   "session": {
     "continue": {
diff --git a/src/i18n/locales/ru/common.json b/src/i18n/locales/ru/common.json
index 906b78eb..24331f4a 100644
--- a/src/i18n/locales/ru/common.json
+++ b/src/i18n/locales/ru/common.json
@@ -176,7 +176,6 @@
     },
     "step3": {
       "reviewConfig": "Проверьте вашу конфигурацию",
-      "workspaceType": "Тип рабочего пространства:",
       "existingWorkspace": "Существующее рабочее пространство",
       "newWorkspace": "Новое рабочее пространство",
       "path": "Путь:",
diff --git a/src/i18n/locales/ru/sidebar.json b/src/i18n/locales/ru/sidebar.json
index 9af33d54..f34cd3df 100644
--- a/src/i18n/locales/ru/sidebar.json
+++ b/src/i18n/locales/ru/sidebar.json
@@ -45,9 +45,11 @@
     "removeFromFavorites": "Удалить из избранного",
     "editSessionName": "Вручную редактировать имя сеанса",
     "deleteSession": "Удалить этот сеанс навсегда",
+    "activeSessionIndicator": "Недавно активный сеанс (последние 10 минут)",
     "save": "Сохранить",
     "cancel": "Отмена",
-    "clearSearch": "Очистить поиск"
+    "clearSearch": "Очистить поиск",
+    "openCommandPalette": "Открыть палитру команд"
   },
   "navigation": {
     "chat": "Чат",
diff --git a/src/i18n/locales/tr/chat.json b/src/i18n/locales/tr/chat.json
index a866fcce..fb2cde17 100644
--- a/src/i18n/locales/tr/chat.json
+++ b/src/i18n/locales/tr/chat.json
@@ -89,12 +89,14 @@
     "permissionMode": "İzin Modu",
     "modes": {
       "default": "Varsayılan Mod",
+      "auto": "Auto Mode",
       "acceptEdits": "Düzenlemeleri Kabul Et",
       "bypassPermissions": "İzinleri Atla",
       "plan": "Plan Modu"
     },
     "descriptions": {
       "default": "Sadece güvenilir komutlar (ls, cat, grep, git status, vb.) otomatik çalışır. Diğer komutlar atlanır. Çalışma alanına yazabilir.",
+      "auto": "A model classifier decides per tool call whether to approve or deny. Hands-off, but safer than Bypass — denials still happen.",
       "acceptEdits": "Tüm komutlar çalışma alanı içinde otomatik çalışır. Sandbox'lu çalıştırma ile tam otomatik mod.",
       "bypassPermissions": "Kısıtlama olmadan tam sistem erişimi. Tüm komutlar tam disk ve ağ erişimiyle otomatik çalışır. Dikkatli kullan.",
       "plan": "Planlama modu — hiçbir komut çalıştırılmaz"
@@ -188,7 +190,8 @@
       "codex": "Codex'i {{model}} ile kullanmaya hazır. Mesajını aşağıya yazmaya başla.",
       "gemini": "Gemini'yi {{model}} ile kullanmaya hazır. Mesajını aşağıya yazmaya başla.",
       "default": "Başlamak için yukarıdan bir sağlayıcı seç"
-    }
+    },
+    "pressToSearch": "Oturumlarda, dosyalarda ve commit'lerde arama yapmak için <kbd>{{shortcut}}</kbd> tuşlarına bas"
   },
   "session": {
     "continue": {
diff --git a/src/i18n/locales/tr/common.json b/src/i18n/locales/tr/common.json
index 2a254034..3b9a6d27 100644
--- a/src/i18n/locales/tr/common.json
+++ b/src/i18n/locales/tr/common.json
@@ -176,7 +176,6 @@
     },
     "step3": {
       "reviewConfig": "Yapılandırmanı Gözden Geçir",
-      "workspaceType": "Çalışma Alanı Türü:",
       "existingWorkspace": "Mevcut Çalışma Alanı",
       "newWorkspace": "Yeni Çalışma Alanı",
       "path": "Yol:",
diff --git a/src/i18n/locales/tr/sidebar.json b/src/i18n/locales/tr/sidebar.json
index b0ba4ad7..bc872311 100644
--- a/src/i18n/locales/tr/sidebar.json
+++ b/src/i18n/locales/tr/sidebar.json
@@ -45,9 +45,11 @@
     "removeFromFavorites": "Favorilerden çıkar",
     "editSessionName": "Oturum adını elle düzenle",
     "deleteSession": "Bu oturumu kalıcı olarak sil",
+    "activeSessionIndicator": "Yakın zamanda etkin oturum (son 10 dakika)",
     "save": "Kaydet",
     "cancel": "İptal",
-    "clearSearch": "Aramayı temizle"
+    "clearSearch": "Aramayı temizle",
+    "openCommandPalette": "Komut paletini aç"
   },
   "navigation": {
     "chat": "Sohbet",
diff --git a/src/i18n/locales/zh-CN/chat.json b/src/i18n/locales/zh-CN/chat.json
index 1d224cc7..7f882281 100644
--- a/src/i18n/locales/zh-CN/chat.json
+++ b/src/i18n/locales/zh-CN/chat.json
@@ -89,12 +89,14 @@
     "permissionMode": "权限模式",
     "modes": {
       "default": "默认模式",
+      "auto": "Auto Mode",
       "acceptEdits": "编辑模式",
       "bypassPermissions": "无限制模式",
       "plan": "计划模式"
     },
     "descriptions": {
       "default": "只有受信任的命令（ls、cat、grep、git status 等）自动运行。其他命令将被跳过。可以写入工作区。",
+      "auto": "A model classifier decides per tool call whether to approve or deny. Hands-off, but safer than Bypass — denials still happen.",
       "acceptEdits": "工作区内的所有命令自动运行。完全自动模式，具有沙盒执行功能。",
       "bypassPermissions": "完全的系统访问，无限制。所有命令自动运行，具有完整的磁盘和网络访问权限。请谨慎使用。",
       "plan": "计划模式 - 不执行任何命令"
@@ -170,7 +172,8 @@
       "codex": "准备好使用带有 {{model}} 的 Codex。请在下方开始输入您的消息。",
       "gemini": "准备好使用带有 {{model}} 的 Gemini。请在下方开始输入您的消息。",
       "default": "请在上方选择一个提供者以开始"
-    }
+    },
+    "pressToSearch": "按 <kbd>{{shortcut}}</kbd> 搜索会话、文件和提交"
   },
   "session": {
     "continue": {
diff --git a/src/i18n/locales/zh-CN/common.json b/src/i18n/locales/zh-CN/common.json
index 936fe5b2..05e0369d 100644
--- a/src/i18n/locales/zh-CN/common.json
+++ b/src/i18n/locales/zh-CN/common.json
@@ -176,7 +176,6 @@
     },
     "step3": {
       "reviewConfig": "查看您的配置",
-      "workspaceType": "工作区类型：",
       "existingWorkspace": "现有工作区",
       "newWorkspace": "新建工作区",
       "path": "路径：",
diff --git a/src/i18n/locales/zh-CN/sidebar.json b/src/i18n/locales/zh-CN/sidebar.json
index 85053d92..be5da16b 100644
--- a/src/i18n/locales/zh-CN/sidebar.json
+++ b/src/i18n/locales/zh-CN/sidebar.json
@@ -45,9 +45,11 @@
     "removeFromFavorites": "从收藏移除",
     "editSessionName": "手动编辑会话名称",
     "deleteSession": "永久删除此会话",
+    "activeSessionIndicator": "最近活跃的会话（最近 10 分钟）",
     "save": "保存",
     "cancel": "取消",
-    "clearSearch": "清除搜索"
+    "clearSearch": "清除搜索",
+    "openCommandPalette": "打开命令面板"
   },
   "navigation": {
     "chat": "聊天",
diff --git a/src/shared/view/ui/Command.tsx b/src/shared/view/ui/Command.tsx
index 5bdccdbb..a66fc17c 100644
--- a/src/shared/view/ui/Command.tsx
+++ b/src/shared/view/ui/Command.tsx
@@ -1,320 +1,107 @@
 import * as React from 'react';
+import { Command as CommandPrimitive } from 'cmdk';
 import { Search } from 'lucide-react';
 
 import { cn } from '../../../lib/utils';
 
-/*
- * Lightweight command palette — inspired by cmdk but no external deps.
- *
- * Architecture:
- * - Command owns the search string and a flat list of registered item values.
- * - Items register via context on mount and deregister on unmount.
- * - Filtering, active index, and keyboard nav happen centrally in Command.
- * - Items read their "is visible" / "is active" state from context.
- */
+const Command = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive>
+>(({ className, ...props }, ref) => (
+  <CommandPrimitive
+    ref={ref}
+    className={cn('flex flex-col', className)}
+    {...props}
+  />
+));
+Command.displayName = CommandPrimitive.displayName;
 
-interface ItemEntry {
-  id: string;
-  value: string;       // searchable text (lowercase)
-  onSelect: () => void;
-  element: HTMLElement | null;
-}
-
-interface CommandContextValue {
-  search: string;
-  setSearch: (value: string) => void;
-  /** Set of visible item IDs after filtering (derived state, not a ref). */
-  visibleIds: Set<string>;
-  activeId: string | null;
-  setActiveId: (id: string | null) => void;
-  register: (entry: ItemEntry) => void;
-  unregister: (id: string) => void;
-  updateEntry: (id: string, patch: Partial<Pick<ItemEntry, 'value' | 'onSelect' | 'element'>>) => void;
-}
-
-const CommandContext = React.createContext<CommandContextValue | null>(null);
-
-function useCommand() {
-  const ctx = React.useContext(CommandContext);
-  if (!ctx) throw new Error('Command components must be used within <Command>');
-  return ctx;
-}
-
-/* ─── Command (root) ─────────────────────────────────────────────── */
-
-type CommandProps = React.HTMLAttributes<HTMLDivElement>;
-
-const Command = React.forwardRef<HTMLDivElement, CommandProps>(
-  ({ className, children, ...props }, ref) => {
-    const [search, setSearch] = React.useState('');
-    const entriesRef = React.useRef<Map<string, ItemEntry>>(new Map());
-    // Bump this counter whenever the entry set changes so derived state recalculates
-    const [revision, setRevision] = React.useState(0);
-
-    const register = React.useCallback((entry: ItemEntry) => {
-      entriesRef.current.set(entry.id, entry);
-      setRevision(r => r + 1);
-    }, []);
-
-    const unregister = React.useCallback((id: string) => {
-      entriesRef.current.delete(id);
-      setRevision(r => r + 1);
-    }, []);
-
-    const updateEntry = React.useCallback((id: string, patch: Partial<Pick<ItemEntry, 'value' | 'onSelect' | 'element'>>) => {
-      const existing = entriesRef.current.get(id);
-      if (existing) {
-        Object.assign(existing, patch);
-      }
-    }, []);
-
-    // Derive visible IDs from search + entries
-    const visibleIds = React.useMemo(() => {
-      const lowerSearch = search.toLowerCase();
-      const ids = new Set<string>();
-      for (const [id, entry] of entriesRef.current) {
-        if (!lowerSearch || entry.value.includes(lowerSearch)) {
-          ids.add(id);
-        }
-      }
-      return ids;
-      // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [search, revision]);
-
-    // Ordered list of visible entries (preserves DOM order via insertion order)
-    const visibleEntries = React.useMemo(() => {
-      const result: ItemEntry[] = [];
-      for (const [, entry] of entriesRef.current) {
-        if (visibleIds.has(entry.id)) result.push(entry);
-      }
-      return result;
-    }, [visibleIds]);
-
-    // Active item tracking
-    const [activeId, setActiveId] = React.useState<string | null>(null);
-
-    // Reset active to first visible item when search or visible set changes
-    React.useEffect(() => {
-      setActiveId(visibleEntries.length > 0 ? visibleEntries[0].id : null);
-    }, [visibleEntries]);
-
-    const handleKeyDown = React.useCallback((e: React.KeyboardEvent) => {
-      if (e.key === 'ArrowDown' || e.key === 'ArrowUp' || e.key === 'Enter') {
-        e.preventDefault();
-      } else {
-        return;
-      }
-
-      const entries = visibleEntries;
-      if (entries.length === 0) return;
-
-      if (e.key === 'Enter') {
-        const active = entries.find(entry => entry.id === activeId);
-        active?.onSelect();
-        return;
-      }
-
-      const currentIndex = entries.findIndex(entry => entry.id === activeId);
-      let nextIndex: number;
-      if (e.key === 'ArrowDown') {
-        nextIndex = currentIndex < entries.length - 1 ? currentIndex + 1 : 0;
-      } else {
-        nextIndex = currentIndex > 0 ? currentIndex - 1 : entries.length - 1;
-      }
-      const nextId = entries[nextIndex].id;
-      setActiveId(nextId);
-
-      // Scroll the active item into view
-      const nextEntry = entries[nextIndex];
-      nextEntry.element?.scrollIntoView({ block: 'nearest' });
-    }, [visibleEntries, activeId]);
-
-    const value = React.useMemo<CommandContextValue>(
-      () => ({ search, setSearch, visibleIds, activeId, setActiveId, register, unregister, updateEntry }),
-      [search, visibleIds, activeId, register, unregister, updateEntry]
-    );
-
-    return (
-      <CommandContext.Provider value={value}>
-        <div
-          ref={ref}
-          role="combobox"
-          aria-expanded="true"
-          aria-haspopup="listbox"
-          className={cn('flex flex-col', className)}
-          onKeyDown={handleKeyDown}
-          {...props}
-        >
-          {children}
-        </div>
-      </CommandContext.Provider>
-    );
-  }
-);
-Command.displayName = 'Command';
-
-/* ─── CommandInput ───────────────────────────────────────────────── */
-
-type CommandInputProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, 'onChange' | 'value' | 'type'>;
-
-const CommandInput = React.forwardRef<HTMLInputElement, CommandInputProps>(
-  ({ className, placeholder = 'Search...', ...props }, ref) => {
-    const { search, setSearch } = useCommand();
-
-    return (
-      <div className="flex items-center border-b px-3" role="presentation">
-        <Search className="mr-2 h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
-        <input
-          ref={ref}
-          type="text"
-          role="searchbox"
-          aria-autocomplete="list"
-          autoComplete="off"
-          autoCorrect="off"
-          spellCheck={false}
-          value={search}
-          onChange={(e) => setSearch(e.target.value)}
-          placeholder={placeholder}
-          className={cn(
-            'flex h-11 w-full rounded-md bg-transparent py-3 text-sm outline-none',
-            'placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50',
-            className
-          )}
-          {...props}
-        />
-      </div>
-    );
-  }
-);
-CommandInput.displayName = 'CommandInput';
-
-/* ─── CommandList ────────────────────────────────────────────────── */
-
-const CommandList = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
-  ({ className, ...props }, ref) => (
-    <div
+const CommandInput = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Input>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Input>
+>(({ className, ...props }, ref) => (
+  <div className="flex items-center border-b px-3">
+    <Search className="mr-2 h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
+    <CommandPrimitive.Input
       ref={ref}
-      role="listbox"
-      className={cn('max-h-[300px] overflow-y-auto overflow-x-hidden', className)}
+      className={cn(
+        'flex h-11 w-full rounded-md bg-transparent py-3 text-sm outline-none',
+        'placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50',
+        className,
+      )}
       {...props}
     />
-  )
-);
-CommandList.displayName = 'CommandList';
+  </div>
+));
+CommandInput.displayName = CommandPrimitive.Input.displayName;
 
-/* ─── CommandEmpty ───────────────────────────────────────────────── */
+const CommandList = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.List>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.List>
+>(({ className, ...props }, ref) => (
+  <CommandPrimitive.List
+    ref={ref}
+    className={cn('max-h-[300px] overflow-y-auto overflow-x-hidden', className)}
+    {...props}
+  />
+));
+CommandList.displayName = CommandPrimitive.List.displayName;
 
-const CommandEmpty = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
-  ({ className, ...props }, ref) => {
-    const { search, visibleIds } = useCommand();
+const CommandEmpty = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Empty>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Empty>
+>((props, ref) => (
+  <CommandPrimitive.Empty
+    ref={ref}
+    className="py-6 text-center text-sm text-muted-foreground"
+    {...props}
+  />
+));
+CommandEmpty.displayName = CommandPrimitive.Empty.displayName;
 
-    // Only show when there's a search term and zero matches
-    if (!search || visibleIds.size > 0) return null;
+const CommandGroup = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Group>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Group>
+>(({ className, ...props }, ref) => (
+  <CommandPrimitive.Group
+    ref={ref}
+    className={cn(
+      'overflow-hidden p-1 text-foreground',
+      '[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:py-1.5 [&_[cmdk-group-heading]]:text-xs [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground',
+      className,
+    )}
+    {...props}
+  />
+));
+CommandGroup.displayName = CommandPrimitive.Group.displayName;
 
-    return (
-      <div ref={ref} className={cn('py-6 text-center text-sm text-muted-foreground', className)} {...props} />
-    );
-  }
-);
-CommandEmpty.displayName = 'CommandEmpty';
+const CommandItem = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Item>
+>(({ className, ...props }, ref) => (
+  <CommandPrimitive.Item
+    ref={ref}
+    className={cn(
+      'relative flex cursor-pointer select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none',
+      'data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground',
+      'data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50',
+      className,
+    )}
+    {...props}
+  />
+));
+CommandItem.displayName = CommandPrimitive.Item.displayName;
 
-/* ─── CommandGroup ───────────────────────────────────────────────── */
-
-interface CommandGroupProps extends React.HTMLAttributes<HTMLDivElement> {
-  heading?: React.ReactNode;
-}
-
-const CommandGroup = React.forwardRef<HTMLDivElement, CommandGroupProps>(
-  ({ className, heading, children, ...props }, ref) => (
-    <div ref={ref} className={cn('overflow-hidden p-1', className)} role="group" aria-label={typeof heading === 'string' ? heading : undefined} {...props}>
-      {heading && (
-        <div className="px-2 py-1.5 text-xs font-medium text-muted-foreground" role="presentation">
-          {heading}
-        </div>
-      )}
-      {children}
-    </div>
-  )
-);
-CommandGroup.displayName = 'CommandGroup';
-
-/* ─── CommandItem ────────────────────────────────────────────────── */
-
-interface CommandItemProps extends React.HTMLAttributes<HTMLDivElement> {
-  value?: string;
-  onSelect?: () => void;
-  disabled?: boolean;
-}
-
-const CommandItem = React.forwardRef<HTMLDivElement, CommandItemProps>(
-  ({ className, value, onSelect, disabled, children, ...props }, ref) => {
-    const { visibleIds, activeId, setActiveId, register, unregister, updateEntry } = useCommand();
-    const stableId = React.useId();
-    const elementRef = React.useRef<HTMLElement | null>(null);
-    const searchableText = value || (typeof children === 'string' ? children : '');
-
-    // Register on mount, unregister on unmount
-    React.useEffect(() => {
-      register({
-        id: stableId,
-        value: searchableText.toLowerCase(),
-        onSelect: onSelect || (() => {}),
-        element: elementRef.current,
-      });
-      return () => unregister(stableId);
-      // Only re-register when the identity changes, not onSelect
-      // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [stableId, searchableText, register, unregister]);
-
-    // Keep onSelect up-to-date without re-registering
-    React.useEffect(() => {
-      updateEntry(stableId, { onSelect: onSelect || (() => {}) });
-    }, [stableId, onSelect, updateEntry]);
-
-    // Keep element ref up-to-date
-    const setRef = React.useCallback((node: HTMLDivElement | null) => {
-      elementRef.current = node;
-      updateEntry(stableId, { element: node });
-      if (typeof ref === 'function') ref(node);
-      else if (ref) ref.current = node;
-    }, [stableId, updateEntry, ref]);
-
-    // Hidden by filter
-    if (!visibleIds.has(stableId)) return null;
-
-    const isActive = activeId === stableId;
-
-    return (
-      <div
-        ref={setRef}
-        role="option"
-        aria-selected={isActive}
-        aria-disabled={disabled || undefined}
-        data-active={isActive || undefined}
-        className={cn(
-          'relative flex cursor-pointer select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none',
-          isActive && 'bg-accent text-accent-foreground',
-          disabled && 'pointer-events-none opacity-50',
-          className
-        )}
-        onPointerMove={() => { if (!disabled && activeId !== stableId) setActiveId(stableId); }}
-        onClick={() => !disabled && onSelect?.()}
-        {...props}
-      >
-        {children}
-      </div>
-    );
-  }
-);
-CommandItem.displayName = 'CommandItem';
-
-/* ─── CommandSeparator ───────────────────────────────────────────── */
-
-const CommandSeparator = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
-  ({ className, ...props }, ref) => (
-    <div ref={ref} className={cn('-mx-1 h-px bg-border', className)} {...props} />
-  )
-);
-CommandSeparator.displayName = 'CommandSeparator';
+const CommandSeparator = React.forwardRef<
+  React.ElementRef<typeof CommandPrimitive.Separator>,
+  React.ComponentPropsWithoutRef<typeof CommandPrimitive.Separator>
+>(({ className, ...props }, ref) => (
+  <CommandPrimitive.Separator
+    ref={ref}
+    className={cn('-mx-1 h-px bg-border', className)}
+    {...props}
+  />
+));
+CommandSeparator.displayName = CommandPrimitive.Separator.displayName;
 
 export { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator };
diff --git a/src/stores/useSessionStore.ts b/src/stores/useSessionStore.ts
index 5f6446be..1a720d3d 100644
--- a/src/stores/useSessionStore.ts
+++ b/src/stores/useSessionStore.ts
@@ -8,8 +8,9 @@
  */
 
 import { useCallback, useMemo, useRef, useState } from 'react';
-import type { LLMProvider } from '../types/app';
+
 import { authenticatedFetch } from '../utils/api';
+import type { LLMProvider } from '../types/app';
 
 // ─── NormalizedMessage (mirrors server/adapters/types.js) ────────────────────
 
@@ -39,6 +40,20 @@ export interface NormalizedMessage {
   // kind-specific fields (flat for simplicity)
   role?: 'user' | 'assistant';
   content?: string;
+  /**
+   * Mirrors optional transcript metadata from the server.
+   *
+   * These fields are currently used by Claude history normalization so local
+   * slash commands, local stdout, and compact summaries do not disappear when
+   * the session store hydrates from REST history.
+   */
+  displayText?: string;
+  commandName?: string;
+  commandMessage?: string;
+  commandArgs?: string;
+  isLocalCommand?: boolean;
+  isLocalCommandStdout?: boolean;
+  isCompactSummary?: boolean;
   images?: string[];
   toolName?: string;
   toolInput?: unknown;
@@ -103,17 +118,126 @@ function createEmptySlot(): SessionSlot {
 }
 
 /**
- * Compute merged messages: server + realtime, deduped by id.
- * Server messages take priority (they're the persisted source of truth).
- * Realtime messages that aren't yet in server stay (in-flight streaming).
+ * Compute merged messages: server + realtime, deduped by id and adjacent
+ * assistant echo (same trimmed text), so finalized stream rows do not stack
+ * on top of the persisted copy before realtime is cleared.
  */
+function userTextFingerprint(m: NormalizedMessage): string | null {
+  if (m.kind !== 'text' || m.role !== 'user') return null;
+  const t = (m.content || '').trim();
+  return t.length > 0 ? t : null;
+}
+
+/**
+ * After `finalizeStreaming`, the client holds a synthetic assistant `text` row
+ * while the sessions API soon returns the same reply with a different id.
+ * Those sit back-to-back in merged order and look like duplicate bubbles until
+ * `refreshFromServer` clears realtime. Collapse same-text assistant rows and
+ * stream_placeholder → text when content matches.
+ */
+function dedupeAdjacentAssistantEchoes(merged: NormalizedMessage[]): NormalizedMessage[] {
+  const out: NormalizedMessage[] = [];
+  for (const m of merged) {
+    const prev = out[out.length - 1];
+    if (prev) {
+      if (prev.kind === 'stream_delta' && m.kind === 'text' && m.role === 'assistant') {
+        const ps = (prev.content || '').trim();
+        const ms = (m.content || '').trim();
+        if (ps.length > 0 && ps === ms) {
+          out[out.length - 1] = m;
+          continue;
+        }
+      }
+      if (
+        prev.kind === 'text'
+        && m.kind === 'text'
+        && prev.role === 'assistant'
+        && m.role === 'assistant'
+      ) {
+        const ms = (m.content || '').trim();
+        if (ms.length > 0 && ms === (prev.content || '').trim()) {
+          continue;
+        }
+      }
+    }
+    out.push(m);
+  }
+  return out;
+}
+
 function computeMerged(server: NormalizedMessage[], realtime: NormalizedMessage[]): NormalizedMessage[] {
   if (realtime.length === 0) return server;
-  if (server.length === 0) return realtime;
+  if (server.length === 0) return dedupeAdjacentAssistantEchoes(realtime);
   const serverIds = new Set(server.map(m => m.id));
-  const extra = realtime.filter(m => !serverIds.has(m.id));
+  const serverUserTexts = new Set(
+    server.map(userTextFingerprint).filter((t): t is string => t !== null),
+  );
+  const extra = realtime.filter((m) => {
+    if (serverIds.has(m.id)) return false;
+    // Optimistic user rows use `local_*` ids; once the same text exists on the
+    // server-backed copy, drop the realtime echo to avoid duplicate bubbles.
+    if (m.id.startsWith('local_')) {
+      const fp = userTextFingerprint(m);
+      if (fp && serverUserTexts.has(fp)) return false;
+    }
+    return true;
+  });
   if (extra.length === 0) return server;
-  return [...server, ...extra];
+  return dedupeAdjacentAssistantEchoes([...server, ...extra]);
+}
+
+function compareMessagesByTimestamp(left: NormalizedMessage, right: NormalizedMessage): number {
+  const leftTime = Date.parse(left.timestamp);
+  const rightTime = Date.parse(right.timestamp);
+
+  if (Number.isNaN(leftTime) || Number.isNaN(rightTime) || leftTime === rightTime) {
+    return 0;
+  }
+
+  return leftTime - rightTime;
+}
+
+function rewriteMessageSessionId(
+  msg: NormalizedMessage,
+  fromSessionId: string,
+  toSessionId: string,
+): NormalizedMessage {
+  const streamingSourceId = `__streaming_${fromSessionId}`;
+  const nextId = msg.id === streamingSourceId ? `__streaming_${toSessionId}` : msg.id;
+
+  if (msg.sessionId === toSessionId && nextId === msg.id) {
+    return msg;
+  }
+
+  return {
+    ...msg,
+    id: nextId,
+    sessionId: toSessionId,
+  };
+}
+
+function mergeMessagesById(
+  existing: NormalizedMessage[],
+  incoming: NormalizedMessage[],
+): NormalizedMessage[] {
+  if (existing.length === 0) return incoming;
+  if (incoming.length === 0) return existing;
+
+  const merged = [...existing, ...incoming];
+  const deduped: NormalizedMessage[] = [];
+  const seen = new Set<string>();
+
+  for (const msg of merged) {
+    if (seen.has(msg.id)) {
+      continue;
+    }
+
+    seen.add(msg.id);
+    deduped.push(msg);
+  }
+
+  deduped.sort(compareMessagesByTimestamp);
+  return deduped;
 }
 
 /**
@@ -140,58 +264,89 @@ const MAX_REALTIME_MESSAGES = 500;
 
 export function useSessionStore() {
   const storeRef = useRef(new Map<string, SessionSlot>());
+  const sessionAliasesRef = useRef(new Map<string, string>());
   const activeSessionIdRef = useRef<string | null>(null);
   // Bump to force re-render — only when the active session's data changes
   const [, setTick] = useState(0);
   const notify = useCallback((sessionId: string) => {
-    if (sessionId === activeSessionIdRef.current) {
+    const aliases = sessionAliasesRef.current;
+    let resolvedSessionId = sessionId;
+    const visited = new Set<string>();
+
+    while (aliases.has(resolvedSessionId) && !visited.has(resolvedSessionId)) {
+      visited.add(resolvedSessionId);
+      resolvedSessionId = aliases.get(resolvedSessionId)!;
+    }
+
+    if (resolvedSessionId === activeSessionIdRef.current) {
       setTick(n => n + 1);
     }
   }, []);
 
-  const setActiveSession = useCallback((sessionId: string | null) => {
-    activeSessionIdRef.current = sessionId;
+  const resolveSessionId = useCallback((sessionId: string | null | undefined): string | null => {
+    if (!sessionId) {
+      return null;
+    }
+
+    const aliases = sessionAliasesRef.current;
+    let resolvedSessionId = sessionId;
+    const visited = new Set<string>();
+
+    while (aliases.has(resolvedSessionId) && !visited.has(resolvedSessionId)) {
+      visited.add(resolvedSessionId);
+      resolvedSessionId = aliases.get(resolvedSessionId)!;
+    }
+
+    return resolvedSessionId;
   }, []);
 
+  const setActiveSession = useCallback((sessionId: string | null) => {
+    activeSessionIdRef.current = resolveSessionId(sessionId);
+  }, [resolveSessionId]);
+
   const getSlot = useCallback((sessionId: string): SessionSlot => {
+    const resolvedSessionId = resolveSessionId(sessionId) ?? sessionId;
     const store = storeRef.current;
-    if (!store.has(sessionId)) {
-      store.set(sessionId, createEmptySlot());
+    if (!store.has(resolvedSessionId)) {
+      store.set(resolvedSessionId, createEmptySlot());
     }
-    return store.get(sessionId)!;
-  }, []);
+    return store.get(resolvedSessionId)!;
+  }, [resolveSessionId]);
 
-  const has = useCallback((sessionId: string) => storeRef.current.has(sessionId), []);
+  const has = useCallback((sessionId: string) => {
+    const resolvedSessionId = resolveSessionId(sessionId) ?? sessionId;
+    return storeRef.current.has(resolvedSessionId);
+  }, [resolveSessionId]);
 
   /**
-   * Fetch messages from the unified endpoint and populate serverMessages.
+   * Fetch messages from the provider sessions endpoint and populate serverMessages.
+   *
+   * Provider and project metadata are resolved server-side from `sessionId`.
    */
   const fetchFromServer = useCallback(async (
     sessionId: string,
     opts: {
       provider?: LLMProvider;
-      projectName?: string;
+      projectId?: string;
       projectPath?: string;
       limit?: number | null;
       offset?: number;
     } = {},
   ) => {
-    const slot = getSlot(sessionId);
+    const resolvedSessionId = resolveSessionId(sessionId) ?? sessionId;
+    const slot = getSlot(resolvedSessionId);
     slot.status = 'loading';
-    notify(sessionId);
+    notify(resolvedSessionId);
 
     try {
       const params = new URLSearchParams();
-      if (opts.provider) params.append('provider', opts.provider);
-      if (opts.projectName) params.append('projectName', opts.projectName);
-      if (opts.projectPath) params.append('projectPath', opts.projectPath);
       if (opts.limit !== null && opts.limit !== undefined) {
         params.append('limit', String(opts.limit));
         params.append('offset', String(opts.offset ?? 0));
       }
 
       const qs = params.toString();
-      const url = `/api/sessions/${encodeURIComponent(sessionId)}/messages${qs ? `?${qs}` : ''}`;
+      const url = `/api/providers/sessions/${encodeURIComponent(resolvedSessionId)}/messages${qs ? `?${qs}` : ''}`;
       const response = await authenticatedFetch(url);
 
       if (!response.ok) {
@@ -212,15 +367,15 @@ export function useSessionStore() {
         slot.tokenUsage = data.tokenUsage;
       }
 
-      notify(sessionId);
+      notify(resolvedSessionId);
       return slot;
     } catch (error) {
-      console.error(`[SessionStore] fetch failed for ${sessionId}:`, error);
+      console.error(`[SessionStore] fetch failed for ${resolvedSessionId}:`, error);
       slot.status = 'error';
-      notify(sessionId);
+      notify(resolvedSessionId);
       return slot;
     }
-  }, [getSlot, notify]);
+  }, [getSlot, notify, resolveSessionId]);
 
   /**
    * Load older (paginated) messages and prepend to serverMessages.
@@ -229,24 +384,22 @@ export function useSessionStore() {
     sessionId: string,
     opts: {
       provider?: LLMProvider;
-      projectName?: string;
+      projectId?: string;
       projectPath?: string;
       limit?: number;
     } = {},
   ) => {
-    const slot = getSlot(sessionId);
+    const resolvedSessionId = resolveSessionId(sessionId) ?? sessionId;
+    const slot = getSlot(resolvedSessionId);
     if (!slot.hasMore) return slot;
 
     const params = new URLSearchParams();
-    if (opts.provider) params.append('provider', opts.provider);
-    if (opts.projectName) params.append('projectName', opts.projectName);
-    if (opts.projectPath) params.append('projectPath', opts.projectPath);
     const limit = opts.limit ?? 20;
     params.append('limit', String(limit));
     params.append('offset', String(slot.offset));
 
     const qs = params.toString();
-    const url = `/api/sessions/${encodeURIComponent(sessionId)}/messages${qs ? `?${qs}` : ''}`;
+    const url = `/api/providers/sessions/${encodeURIComponent(resolvedSessionId)}/messages${qs ? `?${qs}` : ''}`;
 
     try {
       const response = await authenticatedFetch(url);
@@ -259,64 +412,73 @@ export function useSessionStore() {
       slot.hasMore = Boolean(data.hasMore);
       slot.offset = slot.offset + olderMessages.length;
       recomputeMergedIfNeeded(slot);
-      notify(sessionId);
+      notify(resolvedSessionId);
       return slot;
     } catch (error) {
-      console.error(`[SessionStore] fetchMore failed for ${sessionId}:`, error);
+      console.error(`[SessionStore] fetchMore failed for ${resolvedSessionId}:`, error);
       return slot;
     }
-  }, [getSlot, notify]);
+  }, [getSlot, notify, resolveSessionId]);
 
   /**
    * Append a realtime (WebSocket) message to the correct session slot.
    * This works regardless of which session is actively viewed.
    */
   const appendRealtime = useCallback((sessionId: string, msg: NormalizedMessage) => {
-    const slot = getSlot(sessionId);
-    let updated = [...slot.realtimeMessages, msg];
+    const resolvedSessionId = resolveSessionId(sessionId) ?? sessionId;
+    const slot = getSlot(resolvedSessionId);
+    const normalizedMessage =
+      msg.sessionId === resolvedSessionId
+        ? msg
+        : { ...msg, sessionId: resolvedSessionId };
+    let updated = [...slot.realtimeMessages, normalizedMessage];
     if (updated.length > MAX_REALTIME_MESSAGES) {
       updated = updated.slice(-MAX_REALTIME_MESSAGES);
     }
     slot.realtimeMessages = updated;
     recomputeMergedIfNeeded(slot);
-    notify(sessionId);
-  }, [getSlot, notify]);
+    notify(resolvedSessionId);
+  }, [getSlot, notify, resolveSessionId]);
 
   /**
    * Append multiple realtime messages at once (batch).
    */
   const appendRealtimeBatch = useCallback((sessionId: string, msgs: NormalizedMessage[]) => {
     if (msgs.length === 0) return;
-    const slot = getSlot(sessionId);
-    let updated = [...slot.realtimeMessages, ...msgs];
+    const resolvedSessionId = resolveSessionId(sessionId) ?? sessionId;
+    const slot = getSlot(resolvedSessionId);
+    const normalizedMessages = msgs.map((msg) =>
+      msg.sessionId === resolvedSessionId
+        ? msg
+        : { ...msg, sessionId: resolvedSessionId },
+    );
+    let updated = [...slot.realtimeMessages, ...normalizedMessages];
     if (updated.length > MAX_REALTIME_MESSAGES) {
       updated = updated.slice(-MAX_REALTIME_MESSAGES);
     }
     slot.realtimeMessages = updated;
     recomputeMergedIfNeeded(slot);
-    notify(sessionId);
-  }, [getSlot, notify]);
+    notify(resolvedSessionId);
+  }, [getSlot, notify, resolveSessionId]);
 
   /**
-   * Re-fetch serverMessages from the unified endpoint (e.g., on projects_updated).
+   * Re-fetch serverMessages from the provider sessions endpoint.
    */
   const refreshFromServer = useCallback(async (
     sessionId: string,
-    opts: {
+    _opts: {
       provider?: LLMProvider;
-      projectName?: string;
+      projectId?: string;
       projectPath?: string;
     } = {},
   ) => {
-    const slot = getSlot(sessionId);
+    const resolvedSessionId = resolveSessionId(sessionId) ?? sessionId;
+    const slot = getSlot(resolvedSessionId);
     try {
       const params = new URLSearchParams();
-      if (opts.provider) params.append('provider', opts.provider);
-      if (opts.projectName) params.append('projectName', opts.projectName);
-      if (opts.projectPath) params.append('projectPath', opts.projectPath);
 
       const qs = params.toString();
-      const url = `/api/sessions/${encodeURIComponent(sessionId)}/messages${qs ? `?${qs}` : ''}`;
+      const url = `/api/providers/sessions/${encodeURIComponent(resolvedSessionId)}/messages${qs ? `?${qs}` : ''}`;
       const response = await authenticatedFetch(url);
 
       if (!response.ok) throw new Error(`HTTP ${response.status}`);
@@ -329,40 +491,43 @@ export function useSessionStore() {
       // drop realtime messages that the server has caught up with to prevent unbounded growth.
       slot.realtimeMessages = [];
       recomputeMergedIfNeeded(slot);
-      notify(sessionId);
+      notify(resolvedSessionId);
     } catch (error) {
-      console.error(`[SessionStore] refresh failed for ${sessionId}:`, error);
+      console.error(`[SessionStore] refresh failed for ${resolvedSessionId}:`, error);
     }
-  }, [getSlot, notify]);
+  }, [getSlot, notify, resolveSessionId]);
 
   /**
    * Update session status.
    */
   const setStatus = useCallback((sessionId: string, status: SessionStatus) => {
-    const slot = getSlot(sessionId);
+    const resolvedSessionId = resolveSessionId(sessionId) ?? sessionId;
+    const slot = getSlot(resolvedSessionId);
     slot.status = status;
-    notify(sessionId);
-  }, [getSlot, notify]);
+    notify(resolvedSessionId);
+  }, [getSlot, notify, resolveSessionId]);
 
   /**
    * Check if a session's data is stale (>30s old).
    */
   const isStale = useCallback((sessionId: string) => {
-    const slot = storeRef.current.get(sessionId);
+    const resolvedSessionId = resolveSessionId(sessionId) ?? sessionId;
+    const slot = storeRef.current.get(resolvedSessionId);
     if (!slot) return true;
     return Date.now() - slot.fetchedAt > STALE_THRESHOLD_MS;
-  }, []);
+  }, [resolveSessionId]);
 
   /**
    * Update or create a streaming message (accumulated text so far).
    * Uses a well-known ID so subsequent calls replace the same message.
    */
   const updateStreaming = useCallback((sessionId: string, accumulatedText: string, msgProvider: LLMProvider) => {
-    const slot = getSlot(sessionId);
-    const streamId = `__streaming_${sessionId}`;
+    const resolvedSessionId = resolveSessionId(sessionId) ?? sessionId;
+    const slot = getSlot(resolvedSessionId);
+    const streamId = `__streaming_${resolvedSessionId}`;
     const msg: NormalizedMessage = {
       id: streamId,
-      sessionId,
+      sessionId: resolvedSessionId,
       timestamp: new Date().toISOString(),
       provider: msgProvider,
       kind: 'stream_delta',
@@ -376,17 +541,18 @@ export function useSessionStore() {
       slot.realtimeMessages = [...slot.realtimeMessages, msg];
     }
     recomputeMergedIfNeeded(slot);
-    notify(sessionId);
-  }, [getSlot, notify]);
+    notify(resolvedSessionId);
+  }, [getSlot, notify, resolveSessionId]);
 
   /**
    * Finalize streaming: convert the streaming message to a regular text message.
    * The well-known streaming ID is replaced with a unique text message ID.
    */
   const finalizeStreaming = useCallback((sessionId: string) => {
-    const slot = storeRef.current.get(sessionId);
+    const resolvedSessionId = resolveSessionId(sessionId) ?? sessionId;
+    const slot = storeRef.current.get(resolvedSessionId);
     if (!slot) return;
-    const streamId = `__streaming_${sessionId}`;
+    const streamId = `__streaming_${resolvedSessionId}`;
     const idx = slot.realtimeMessages.findIndex(m => m.id === streamId);
     if (idx >= 0) {
       const stream = slot.realtimeMessages[idx];
@@ -398,35 +564,104 @@ export function useSessionStore() {
         role: 'assistant',
       };
       recomputeMergedIfNeeded(slot);
-      notify(sessionId);
+      notify(resolvedSessionId);
     }
-  }, [notify]);
+  }, [notify, resolveSessionId]);
 
   /**
    * Clear realtime messages for a session (e.g., after stream completes and server fetch catches up).
    */
   const clearRealtime = useCallback((sessionId: string) => {
-    const slot = storeRef.current.get(sessionId);
+    const resolvedSessionId = resolveSessionId(sessionId) ?? sessionId;
+    const slot = storeRef.current.get(resolvedSessionId);
     if (slot) {
       slot.realtimeMessages = [];
       recomputeMergedIfNeeded(slot);
-      notify(sessionId);
+      notify(resolvedSessionId);
     }
-  }, [notify]);
+  }, [notify, resolveSessionId]);
 
   /**
    * Get merged messages for a session (for rendering).
    */
   const getMessages = useCallback((sessionId: string): NormalizedMessage[] => {
-    return storeRef.current.get(sessionId)?.merged ?? [];
-  }, []);
+    const resolvedSessionId = resolveSessionId(sessionId) ?? sessionId;
+    return storeRef.current.get(resolvedSessionId)?.merged ?? [];
+  }, [resolveSessionId]);
 
   /**
    * Get session slot (for status, pagination info, etc.).
    */
   const getSessionSlot = useCallback((sessionId: string): SessionSlot | undefined => {
-    return storeRef.current.get(sessionId);
-  }, []);
+    const resolvedSessionId = resolveSessionId(sessionId) ?? sessionId;
+    return storeRef.current.get(resolvedSessionId);
+  }, [resolveSessionId]);
+
+  const replaceSessionId = useCallback((fromSessionId: string, toSessionId: string) => {
+    const resolvedFromSessionId = resolveSessionId(fromSessionId) ?? fromSessionId;
+    const resolvedToSessionId = resolveSessionId(toSessionId) ?? toSessionId;
+
+    if (resolvedFromSessionId === resolvedToSessionId) {
+      sessionAliasesRef.current.set(fromSessionId, resolvedToSessionId);
+      return;
+    }
+
+    const store = storeRef.current;
+    const sourceSlot = store.get(resolvedFromSessionId);
+    const targetSlot = store.get(resolvedToSessionId) ?? createEmptySlot();
+
+    if (sourceSlot) {
+      const migratedServerMessages = sourceSlot.serverMessages.map((msg) =>
+        rewriteMessageSessionId(msg, resolvedFromSessionId, resolvedToSessionId),
+      );
+      const migratedRealtimeMessages = sourceSlot.realtimeMessages.map((msg) =>
+        rewriteMessageSessionId(msg, resolvedFromSessionId, resolvedToSessionId),
+      );
+
+      targetSlot.serverMessages = mergeMessagesById(targetSlot.serverMessages, migratedServerMessages);
+      targetSlot.realtimeMessages = mergeMessagesById(targetSlot.realtimeMessages, migratedRealtimeMessages);
+      if (targetSlot.realtimeMessages.length > MAX_REALTIME_MESSAGES) {
+        targetSlot.realtimeMessages = targetSlot.realtimeMessages.slice(-MAX_REALTIME_MESSAGES);
+      }
+      targetSlot.status =
+        sourceSlot.status === 'error'
+          ? 'error'
+          : sourceSlot.status === 'streaming' || targetSlot.status === 'streaming'
+            ? 'streaming'
+            : sourceSlot.status === 'loading' || targetSlot.status === 'loading'
+              ? 'loading'
+              : targetSlot.status;
+      targetSlot.fetchedAt = Math.max(targetSlot.fetchedAt, sourceSlot.fetchedAt, Date.now());
+      targetSlot.total = Math.max(
+        targetSlot.total,
+        sourceSlot.total,
+        targetSlot.serverMessages.length,
+        targetSlot.realtimeMessages.length,
+      );
+      targetSlot.hasMore = targetSlot.hasMore || sourceSlot.hasMore;
+      targetSlot.offset = Math.max(targetSlot.offset, sourceSlot.offset);
+      targetSlot.tokenUsage = targetSlot.tokenUsage ?? sourceSlot.tokenUsage;
+      recomputeMergedIfNeeded(targetSlot);
+
+      store.set(resolvedToSessionId, targetSlot);
+      store.delete(resolvedFromSessionId);
+    }
+
+    sessionAliasesRef.current.set(resolvedFromSessionId, resolvedToSessionId);
+    sessionAliasesRef.current.set(fromSessionId, resolvedToSessionId);
+
+    for (const [aliasSessionId, targetSessionId] of sessionAliasesRef.current.entries()) {
+      if (targetSessionId === resolvedFromSessionId) {
+        sessionAliasesRef.current.set(aliasSessionId, resolvedToSessionId);
+      }
+    }
+
+    if (activeSessionIdRef.current === resolvedFromSessionId) {
+      activeSessionIdRef.current = resolvedToSessionId;
+    }
+
+    notify(resolvedToSessionId);
+  }, [notify, resolveSessionId]);
 
   return useMemo(() => ({
     getSlot,
@@ -444,11 +679,12 @@ export function useSessionStore() {
     clearRealtime,
     getMessages,
     getSessionSlot,
+    replaceSessionId,
   }), [
     getSlot, has, fetchFromServer, fetchMore,
     appendRealtime, appendRealtimeBatch, refreshFromServer,
     setActiveSession, setStatus, isStale, updateStreaming, finalizeStreaming,
-    clearRealtime, getMessages, getSessionSlot,
+    clearRealtime, getMessages, getSessionSlot, replaceSessionId,
   ]);
 }
 
diff --git a/src/types/app.ts b/src/types/app.ts
index 4c2f230d..aed51fd4 100644
--- a/src/types/app.ts
+++ b/src/types/app.ts
@@ -1,4 +1,21 @@
-export type LLMProvider = 'claude' | 'cursor' | 'codex' | 'gemini';
+export type LLMProvider = 'claude' | 'cursor' | 'codex' | 'gemini' | 'opencode';
+
+export type ProviderModelOption = {
+  value: string;
+  label: string;
+  description?: string;
+};
+
+export type ProviderModelsDefinition = {
+  OPTIONS: ProviderModelOption[];
+  DEFAULT: string;
+};
+
+export type ProviderModelsCacheInfo = {
+  updatedAt: string;
+  expiresAt: string;
+  source: 'memory' | 'disk' | 'fresh';
+};
 
 export type AppTab = 'chat' | 'files' | 'shell' | 'git' | 'tasks' | 'preview' | `plugin:${string}`;
 
@@ -13,7 +30,9 @@ export interface ProjectSession {
   lastActivity?: string;
   messageCount?: number;
   __provider?: LLMProvider;
-  __projectName?: string;
+  // Tags the session with the owning project's DB `projectId` so UI handlers
+  // (session switching, sidebar focus, etc.) can match against selectedProject.
+  __projectId?: string;
   [key: string]: unknown;
 }
 
@@ -30,15 +49,21 @@ export interface ProjectTaskmasterInfo {
   [key: string]: unknown;
 }
 
+// After the projectName → projectId migration the backend no longer returns a
+// folder-derived `name` string. Projects are now addressed everywhere by the
+// DB-assigned `projectId` (primary key in the `projects` table), and the UI
+// uses the same identifier for routing, state keys and API calls.
 export interface Project {
-  name: string;
+  projectId: string;
   displayName: string;
   fullPath: string;
   path?: string;
+  isStarred?: boolean;
   sessions?: ProjectSession[];
   cursorSessions?: ProjectSession[];
   codexSessions?: ProjectSession[];
   geminiSessions?: ProjectSession[];
+  opencodeSessions?: ProjectSession[];
   sessionMeta?: ProjectSessionMeta;
   taskmaster?: ProjectTaskmasterInfo;
   [key: string]: unknown;
@@ -56,7 +81,13 @@ export interface LoadingProgress {
 export interface ProjectsUpdatedMessage {
   type: 'projects_updated';
   projects: Project[];
-  changedFile?: string;
+  updatedSessionId?: string;
+  updatedSessionIds?: string[];
+  watchProvider?: LLMProvider;
+  watchProviders?: LLMProvider[];
+  changeType?: 'add' | 'change';
+  changeTypes?: Array<'add' | 'change'>;
+  batched?: boolean;
   [key: string]: unknown;
 }
 
diff --git a/src/types/global.d.ts b/src/types/global.d.ts
index ba368e4b..7ed066a4 100644
--- a/src/types/global.d.ts
+++ b/src/types/global.d.ts
@@ -3,8 +3,6 @@ export {};
 declare global {
   interface Window {
     __ROUTER_BASENAME__?: string;
-    refreshProjects?: () => void | Promise<void>;
-    openSettings?: (tab?: string) => void;
   }
 
   interface EventSourceEventMap {
diff --git a/src/utils/api.js b/src/utils/api.js
index 3968daf9..999ee316 100644
--- a/src/utils/api.js
+++ b/src/utils/api.js
@@ -51,50 +51,68 @@ export const api = {
 
   // Protected endpoints
   // config endpoint removed - no longer needed (frontend uses window.location)
+  // After the projectName → projectId migration the path/query identifier is
+  // the DB-assigned `projectId`; parameter names reflect that for clarity.
   projects: () => authenticatedFetch('/api/projects'),
-  sessions: (projectName, limit = 5, offset = 0) =>
-    authenticatedFetch(`/api/projects/${projectName}/sessions?limit=${limit}&offset=${offset}`),
-  // Unified endpoint — all providers through one URL
-  unifiedSessionMessages: (sessionId, provider = 'claude', { projectName = '', projectPath = '', limit = null, offset = 0 } = {}) => {
+  archivedProjects: () => authenticatedFetch('/api/projects/archived'),
+  projectSessions: (projectId, { limit = 20, offset = 0 } = {}) => {
+    const params = new URLSearchParams();
+    params.set('limit', String(limit));
+    params.set('offset', String(offset));
+    return authenticatedFetch(`/api/projects/${encodeURIComponent(projectId)}/sessions?${params.toString()}`);
+  },
+  projectTaskmaster: (projectId) =>
+    authenticatedFetch(`/api/projects/${encodeURIComponent(projectId)}/taskmaster`),
+  // Unified endpoint for persisted session messages.
+  // Provider/project metadata are resolved by the backend from sessionId.
+  unifiedSessionMessages: (sessionId, _provider = 'claude', { limit = null, offset = 0 } = {}) => {
     const params = new URLSearchParams();
-    params.append('provider', provider);
-    if (projectName) params.append('projectName', projectName);
-    if (projectPath) params.append('projectPath', projectPath);
     if (limit !== null) {
       params.append('limit', String(limit));
       params.append('offset', String(offset));
     }
     const queryString = params.toString();
-    return authenticatedFetch(`/api/sessions/${encodeURIComponent(sessionId)}/messages${queryString ? `?${queryString}` : ''}`);
+    return authenticatedFetch(`/api/providers/sessions/${encodeURIComponent(sessionId)}/messages${queryString ? `?${queryString}` : ''}`);
   },
-  renameProject: (projectName, displayName) =>
-    authenticatedFetch(`/api/projects/${projectName}/rename`, {
+  renameProject: (projectId, displayName) =>
+    authenticatedFetch(`/api/projects/${projectId}/rename`, {
       method: 'PUT',
       body: JSON.stringify({ displayName }),
     }),
-  deleteSession: (projectName, sessionId) =>
-    authenticatedFetch(`/api/projects/${projectName}/sessions/${sessionId}`, {
-      method: 'DELETE',
+  restoreProject: (projectId) =>
+    authenticatedFetch(`/api/projects/${encodeURIComponent(projectId)}/restore`, {
+      method: 'POST',
     }),
-  renameSession: (sessionId, summary, provider) =>
-    authenticatedFetch(`/api/sessions/${sessionId}/rename`, {
-      method: 'PUT',
-      body: JSON.stringify({ summary, provider }),
-    }),
-  deleteCodexSession: (sessionId) =>
-    authenticatedFetch(`/api/codex/sessions/${sessionId}`, {
-      method: 'DELETE',
-    }),
-  deleteGeminiSession: (sessionId) =>
-    authenticatedFetch(`/api/gemini/sessions/${sessionId}`, {
-      method: 'DELETE',
-    }),
-  deleteProject: (projectName, force = false, deleteData = false) => {
+  // Session deletion now mirrors project deletion:
+  // - default: archive only (`isArchived = 1`)
+  // - hardDelete: remove the row and, by default, its persisted transcript file
+  deleteSession: (sessionId, hardDelete = false) => {
     const params = new URLSearchParams();
-    if (force) params.set('force', 'true');
-    if (deleteData) params.set('deleteData', 'true');
+    if (hardDelete) {
+      params.set('force', 'true');
+    }
     const qs = params.toString();
-    return authenticatedFetch(`/api/projects/${projectName}${qs ? `?${qs}` : ''}`, {
+    return authenticatedFetch(`/api/providers/sessions/${sessionId}${qs ? `?${qs}` : ''}`, {
+      method: 'DELETE',
+    });
+  },
+  getArchivedSessions: () =>
+    authenticatedFetch('/api/providers/sessions/archived'),
+  restoreSession: (sessionId) =>
+    authenticatedFetch(`/api/providers/sessions/${sessionId}/restore`, {
+      method: 'POST',
+    }),
+  renameSession: (sessionId, summary) =>
+    authenticatedFetch(`/api/providers/sessions/${sessionId}`, {
+      method: 'PUT',
+      body: JSON.stringify({ summary }),
+    }),
+  // `hardDelete` => server `?force=true` (remove DB row + Claude *.jsonl + sessions rows for path).
+  deleteProject: (projectId, hardDelete = false) => {
+    const params = new URLSearchParams();
+    if (hardDelete) params.set('force', 'true');
+    const qs = params.toString();
+    return authenticatedFetch(`/api/projects/${projectId}${qs ? `?${qs}` : ''}`, {
       method: 'DELETE',
     });
   },
@@ -102,69 +120,78 @@ export const api = {
     const token = localStorage.getItem('auth-token');
     const params = new URLSearchParams({ q: query, limit: String(limit) });
     if (token) params.set('token', token);
-    return `/api/search/conversations?${params.toString()}`;
+    return `/api/providers/search/sessions?${params.toString()}`;
   },
-  createWorkspace: (workspaceData) =>
-    authenticatedFetch('/api/projects/create-workspace', {
+  createProject: (projectData) =>
+    authenticatedFetch('/api/projects/create-project', {
       method: 'POST',
-      body: JSON.stringify(workspaceData),
+      body: JSON.stringify(projectData),
     }),
-  readFile: (projectName, filePath) =>
-    authenticatedFetch(`/api/projects/${projectName}/file?filePath=${encodeURIComponent(filePath)}`),
-  readFileBlob: (projectName, filePath) =>
-    authenticatedFetch(`/api/projects/${projectName}/files/content?path=${encodeURIComponent(filePath)}`),
-  saveFile: (projectName, filePath, content) =>
-    authenticatedFetch(`/api/projects/${projectName}/file`, {
+  migrateLegacyProjectStars: (projectIds) =>
+    authenticatedFetch('/api/projects/migrate-legacy-stars', {
+      method: 'POST',
+      body: JSON.stringify({ projectIds }),
+    }),
+  toggleProjectStar: (projectId) =>
+    authenticatedFetch(`/api/projects/${encodeURIComponent(projectId)}/toggle-star`, {
+      method: 'POST',
+    }),
+  readFile: (projectId, filePath) =>
+    authenticatedFetch(`/api/projects/${projectId}/file?filePath=${encodeURIComponent(filePath)}`),
+  readFileBlob: (projectId, filePath) =>
+    authenticatedFetch(`/api/projects/${projectId}/files/content?path=${encodeURIComponent(filePath)}`),
+  saveFile: (projectId, filePath, content) =>
+    authenticatedFetch(`/api/projects/${projectId}/file`, {
       method: 'PUT',
       body: JSON.stringify({ filePath, content }),
     }),
-  getFiles: (projectName, options = {}) =>
-    authenticatedFetch(`/api/projects/${projectName}/files`, options),
+  getFiles: (projectId, options = {}) =>
+    authenticatedFetch(`/api/projects/${projectId}/files`, options),
 
   // File operations
-  createFile: (projectName, { path, type, name }) =>
-    authenticatedFetch(`/api/projects/${projectName}/files/create`, {
+  createFile: (projectId, { path, type, name }) =>
+    authenticatedFetch(`/api/projects/${projectId}/files/create`, {
       method: 'POST',
       body: JSON.stringify({ path, type, name }),
     }),
 
-  renameFile: (projectName, { oldPath, newName }) =>
-    authenticatedFetch(`/api/projects/${projectName}/files/rename`, {
+  renameFile: (projectId, { oldPath, newName }) =>
+    authenticatedFetch(`/api/projects/${projectId}/files/rename`, {
       method: 'PUT',
       body: JSON.stringify({ oldPath, newName }),
     }),
 
-  deleteFile: (projectName, { path, type }) =>
-    authenticatedFetch(`/api/projects/${projectName}/files`, {
+  deleteFile: (projectId, { path, type }) =>
+    authenticatedFetch(`/api/projects/${projectId}/files`, {
       method: 'DELETE',
       body: JSON.stringify({ path, type }),
     }),
 
-  uploadFiles: (projectName, formData) =>
-    authenticatedFetch(`/api/projects/${projectName}/files/upload`, {
+  uploadFiles: (projectId, formData) =>
+    authenticatedFetch(`/api/projects/${projectId}/files/upload`, {
       method: 'POST',
       body: formData,
       headers: {}, // Let browser set Content-Type for FormData
     }),
 
-  // TaskMaster endpoints
+  // TaskMaster endpoints — all addressed by DB projectId post-migration.
   taskmaster: {
     // Initialize TaskMaster in a project
-    init: (projectName) =>
-      authenticatedFetch(`/api/taskmaster/init/${projectName}`, {
+    init: (projectId) =>
+      authenticatedFetch(`/api/taskmaster/init/${projectId}`, {
         method: 'POST',
       }),
 
     // Add a new task
-    addTask: (projectName, { prompt, title, description, priority, dependencies }) =>
-      authenticatedFetch(`/api/taskmaster/add-task/${projectName}`, {
+    addTask: (projectId, { prompt, title, description, priority, dependencies }) =>
+      authenticatedFetch(`/api/taskmaster/add-task/${projectId}`, {
         method: 'POST',
         body: JSON.stringify({ prompt, title, description, priority, dependencies }),
       }),
 
     // Parse PRD to generate tasks
-    parsePRD: (projectName, { fileName, numTasks, append }) =>
-      authenticatedFetch(`/api/taskmaster/parse-prd/${projectName}`, {
+    parsePRD: (projectId, { fileName, numTasks, append }) =>
+      authenticatedFetch(`/api/taskmaster/parse-prd/${projectId}`, {
         method: 'POST',
         body: JSON.stringify({ fileName, numTasks, append }),
       }),
@@ -174,15 +201,15 @@ export const api = {
       authenticatedFetch('/api/taskmaster/prd-templates'),
 
     // Apply a PRD template
-    applyTemplate: (projectName, { templateId, fileName, customizations }) =>
-      authenticatedFetch(`/api/taskmaster/apply-template/${projectName}`, {
+    applyTemplate: (projectId, { templateId, fileName, customizations }) =>
+      authenticatedFetch(`/api/taskmaster/apply-template/${projectId}`, {
         method: 'POST',
         body: JSON.stringify({ templateId, fileName, customizations }),
       }),
 
     // Update a task
-    updateTask: (projectName, taskId, updates) =>
-      authenticatedFetch(`/api/taskmaster/update-task/${projectName}/${taskId}`, {
+    updateTask: (projectId, taskId, updates) =>
+      authenticatedFetch(`/api/taskmaster/update-task/${projectId}/${taskId}`, {
         method: 'PUT',
         body: JSON.stringify(updates),
       }),