Fix desktop settings modal behavior

Authenticate ripgrep install in desktop workflows
Run desktop branch builds on electron app pushes
2026-06-18 22:57:31 +08:00 · 2026-06-18 06:15:17 +00:00 · 2026-06-17 22:29:55 +00:00 · 2026-06-17 22:26:47 +00:00 · 2026-06-17 22:15:36 +00:00 · 2026-06-17 20:18:09 +00:00
170 changed files with 20611 additions and 3115 deletions
--- a/.github/workflows/desktop-macos-branch-build.yml
+++ b/.github/workflows/desktop-macos-branch-build.yml
@@ -0,0 +1,82 @@
+name: Desktop macOS Branch Build
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - electron-app
+
+jobs:
+  build-macos:
+    name: Build macOS desktop artifact
+    runs-on: macos-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Resolve artifact metadata
+        id: artifact
+        run: |
+          SAFE_REF="$(printf '%s' "${GITHUB_REF_NAME}" | tr -c 'A-Za-z0-9._-' '-')"
+          echo "name=CloudCLI-macOS-${SAFE_REF}-${GITHUB_RUN_NUMBER}" >> "$GITHUB_OUTPUT"
+
+      - name: Verify signing secrets are configured
+        run: |
+          test -n "$CSC_LINK"
+          test -n "$CSC_KEY_PASSWORD"
+          test -n "$APPLE_ID"
+          test -n "$APPLE_APP_SPECIFIC_PASSWORD"
+          test -n "$APPLE_TEAM_ID"
+        env:
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Build signed and notarized macOS artifacts
+        run: npm run desktop:dist:mac -- --publish never
+        env:
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Verify macOS artifacts
+        run: |
+          test -n "$(find release -maxdepth 1 -name '*.dmg' -print -quit)"
+          test -n "$(find release -maxdepth 1 -name '*.zip' -print -quit)"
+          shasum -a 256 release/*.{dmg,zip} > release/SHASUMS256.txt
+          cat release/SHASUMS256.txt
+
+      - name: Upload branch build artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: ${{ steps.artifact.outputs.name }}
+          path: |
+            release/*.dmg
+            release/*.zip
+            release/*.yml
+            release/*.blockmap
+            release/SHASUMS256.txt
+          if-no-files-found: error
+          retention-days: 14
--- a/.github/workflows/desktop-macos-release.yml
+++ b/.github/workflows/desktop-macos-release.yml
@@ -0,0 +1,104 @@
+name: Desktop macOS Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag to create or update (defaults to v<package version>)'
+        required: false
+        type: string
+      release_name:
+        description: 'Release name (defaults to "CloudCLI Desktop macOS <tag>")'
+        required: false
+        type: string
+      prerelease:
+        description: 'Mark the GitHub release as a prerelease'
+        required: true
+        default: false
+        type: boolean
+
+jobs:
+  build-macos:
+    name: Build signed macOS desktop app
+    runs-on: macos-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Resolve release metadata
+        id: release
+        run: |
+          VERSION="$(node -p "require('./package.json').version")"
+          TAG="${{ inputs.tag }}"
+          if [ -z "$TAG" ]; then
+            TAG="v${VERSION}"
+          fi
+
+          RELEASE_NAME="${{ inputs.release_name }}"
+          if [ -z "$RELEASE_NAME" ]; then
+            RELEASE_NAME="CloudCLI Desktop macOS ${TAG}"
+          fi
+
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "release_name=$RELEASE_NAME" >> "$GITHUB_OUTPUT"
+
+      - name: Verify signing secrets are configured
+        run: |
+          test -n "$CSC_LINK"
+          test -n "$CSC_KEY_PASSWORD"
+          test -n "$APPLE_ID"
+          test -n "$APPLE_APP_SPECIFIC_PASSWORD"
+          test -n "$APPLE_TEAM_ID"
+        env:
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Build signed and notarized macOS artifacts
+        run: npm run desktop:dist:mac -- --publish never
+        env:
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Verify macOS artifacts
+        run: |
+          test -n "$(find release -maxdepth 1 -name '*.dmg' -print -quit)"
+          test -n "$(find release -maxdepth 1 -name '*.zip' -print -quit)"
+          shasum -a 256 release/*.{dmg,zip} > release/SHASUMS256.txt
+          cat release/SHASUMS256.txt
+
+      - name: Publish GitHub release assets
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.release.outputs.tag }}
+          target_commitish: ${{ github.sha }}
+          name: ${{ steps.release.outputs.release_name }}
+          prerelease: ${{ inputs.prerelease }}
+          fail_on_unmatched_files: false
+          files: |
+            release/*.dmg
+            release/*.zip
+            release/*.yml
+            release/*.blockmap
+            release/SHASUMS256.txt
--- a/.github/workflows/desktop-windows-branch-build.yml
+++ b/.github/workflows/desktop-windows-branch-build.yml
@@ -0,0 +1,66 @@
+name: Desktop Windows Branch Build
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - electron-app
+
+jobs:
+  build-windows:
+    name: Build unsigned Windows desktop artifact
+    runs-on: windows-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Resolve artifact metadata
+        id: artifact
+        shell: bash
+        run: |
+          SAFE_REF="$(printf '%s' "${GITHUB_REF_NAME}" | tr -c 'A-Za-z0-9._-' '-')"
+          echo "name=CloudCLI-windows-${SAFE_REF}-${GITHUB_RUN_NUMBER}" >> "$GITHUB_OUTPUT"
+
+      - name: Build unsigned Windows artifacts
+        run: npm run desktop:dist:win -- --publish never
+        env:
+          CSC_IDENTITY_AUTO_DISCOVERY: "false"
+
+      - name: Verify Windows artifacts
+        shell: bash
+        run: |
+          test -n "$(find release -maxdepth 1 -name '*.exe' -print -quit)"
+          test -n "$(find release -maxdepth 1 -name '*.zip' -print -quit)"
+          sha256sum release/*.{exe,zip} > release/SHASUMS256.txt
+          cat release/SHASUMS256.txt
+
+      - name: Upload branch build artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: ${{ steps.artifact.outputs.name }}
+          path: |
+            release/*.exe
+            release/*.zip
+            release/*.yml
+            release/*.blockmap
+            release/SHASUMS256.txt
+          if-no-files-found: error
+          retention-days: 14
--- a/.gitignore
+++ b/.gitignore
@@ -134,6 +134,7 @@ tasks/

 # Translations
 !src/i18n/locales/en/tasks.json
+!src/i18n/locales/fr/tasks.json
 !src/i18n/locales/ja/tasks.json
 !src/i18n/locales/ru/tasks.json
 !src/i18n/locales/de/tasks.json
@@ -142,3 +143,8 @@ tasks/

 # Git worktrees
 .worktrees/
+
+# Local desktop packaging artifacts
+cloudcli-sidebar-app-source.tar.gz
+cloudcli-sidebar.html
+electron/*.tar.gz
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,33 @@
 All notable changes to CloudCLI UI will be documented in this file.


+## [](https://github.com/siteboon/claudecodeui/compare/v1.33.3...vnull) (2026-06-09)
+
+### New Features
+
+* adding Fable 5 in claude code ([ce327b6](https://github.com/siteboon/claudecodeui/commit/ce327b6fa9329aa3e9a3a1da7225ca01d3b06ac5))
+
+## [1.33.3](https://github.com/siteboon/claudecodeui/compare/v1.33.2...v1.33.3) (2026-06-09)
+
+### New Features
+
+* add file tree upload progress ([c235b05](https://github.com/siteboon/claudecodeui/commit/c235b05e1d3b626667dba4043b685512e3cd3d5d))
+* signal when chat runs complete ([d70dc07](https://github.com/siteboon/claudecodeui/commit/d70dc077bfbbfcf2ff4fa5514fabf7b4485861fa))
+
+### Bug Fixes
+
+* address notification review feedback ([602e6ad](https://github.com/siteboon/claudecodeui/commit/602e6ad4acba612a7ea66fb3bc7485054f5675ee))
+* align prism plugin name and id with manifest.json ([ca8fd0e](https://github.com/siteboon/claudecodeui/commit/ca8fd0ee235b6a3210157bd0d9af83024d4a2248))
+* **chat:** re-anchor initial scroll across lazy content reflow ([33a4e72](https://github.com/siteboon/claudecodeui/commit/33a4e72ca4f84df60aadfc4ff3f3467d6f5ae948))
+* keep editor toolbar in view on long unwrapped lines ([beae8c6](https://github.com/siteboon/claudecodeui/commit/beae8c6513daa7518b9de40d8bfde3bf08e7bc87))
+* **sandbox:** prevent server SIGHUP on sbx exec exit ([#792](https://github.com/siteboon/claudecodeui/issues/792)) ([f4a1614](https://github.com/siteboon/claudecodeui/commit/f4a1614a0a4ab4b65e8368d5e4221f015cb7555d)), closes [#791](https://github.com/siteboon/claudecodeui/issues/791)
+* slash command suggestions trigger at any / in input, not only at start ([#843](https://github.com/siteboon/claudecodeui/issues/843)) ([f7c0024](https://github.com/siteboon/claudecodeui/commit/f7c0024fe15057ad049c71e15e88adb482a4497f))
+* update naming convention ([3cd8995](https://github.com/siteboon/claudecodeui/commit/3cd89956ba06f0fc3e17d349b0c50baab4012658))
+
+### Maintenance
+
+* add prism plugin ([01dbe2a](https://github.com/siteboon/claudecodeui/commit/01dbe2a8bfcb3b265995f01f905b218d5f576f7b))
+
 ## [1.33.2](https://github.com/siteboon/claudecodeui/compare/v1.33.1...v1.33.2) (2026-06-08)

 ### New Features
--- 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 [`public/modelConstants.js`](public/modelConstants.js))
+- **Modell-Kompatibilität** – Funktioniert mit Claude, GPT und Gemini (vollständige Liste unterstützter Modelle zur Laufzeit über `GET /api/providers/:provider/models`)


 ## Schnellstart
@@ -164,6 +164,14 @@ CloudCLI verfügt über ein Plugin-System, mit dem benutzerdefinierte Tabs mit e
 | Plugin | Beschreibung |
 |---|---|
 | **[Project Stats](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** | Zeigt Dateianzahl, Codezeilen, Dateityp-Aufschlüsselung, größte Dateien und zuletzt geänderte Dateien des aktuellen Projekts |
+| **[Web Terminal](https://github.com/cloudcli-ai/cloudcli-plugin-terminal)** | Vollwertiges xterm.js-Terminal mit Multi-Tab-Unterstützung |
+| **[Claude Watch](https://github.com/satsuki19980613/cloudcli-claude-watch)** | Überwacht lange laufende Claude-Code-Sitzungen auf Hänger und stellt Prozesssteuerungen bereit |
+| **[CloudCLI Scheduler](https://github.com/grostim/cloudcli-cron)** | Erstellt arbeitsbereichsbezogene geplante Prompts und führt sie über eine lokale CLI wie Codex, Claude Code oder Gemini CLI aus |
+| **[PRISM CloudCLI](https://github.com/jakeefr/cloudcli-plugin-prism)** | Sitzungsintelligenz für Claude Code in CloudCLI, inklusive Sichtbarkeit des Token-Verbrauchs |
+| **[Sessions](https://github.com/strykereye2/cloudcli-plugin-session-manager)** | Aktive Claude-Code-Sitzungen anzeigen, verwalten und beenden |
+| **[Token Cost Calculator](https://github.com/NightmareAway/cloudcli-plugin-token-cost-calculator)** | API-Kosten anhand von Modellpreisen und Token-Nutzung berechnen, mit Unterstützung für Preisvorlagen |
+| **[Task Queue](https://github.com/TadMSTR/cloudcli-plugin-task-queue)** | Task-Queue-Dashboard zum Anzeigen, Filtern und Starten von Agent-Aufgaben |
+| **[GitHub Issues Board](https://github.com/szmidtpiotr/claude-github-issue)** | Kanban-Board für GitHub Issues mit bidirektionaler TaskMaster-Synchronisierung und automatischer Installation des /github-task CLI-Skills |

 ### Eigenes Plugin erstellen

--- a/README.ja.md
+++ b/README.ja.md
@@ -158,6 +158,14 @@ CloudCLI にはプラグインシステムがあり、独自のフロントエ
 | プラグイン | 説明 |
 |---|---|
 | **[Project Stats](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** | 現在のプロジェクトについて、ファイル数、コード行数、ファイル種別の内訳、最大ファイル、最近変更されたファイルを表示 |
+| **[Web Terminal](https://github.com/cloudcli-ai/cloudcli-plugin-terminal)** | 複数タブに対応した本格的な xterm.js ターミナル |
+| **[Claude Watch](https://github.com/satsuki19980613/cloudcli-claude-watch)** | 長時間実行中の Claude Code セッションのハングを監視し、プロセス操作を提供 |
+| **[CloudCLI Scheduler](https://github.com/grostim/cloudcli-cron)** | ワークスペース単位のスケジュール済みプロンプトを作成し、Codex、Claude Code、Gemini CLI などのローカル CLI で実行 |
+| **[PRISM CloudCLI](https://github.com/jakeefr/cloudcli-plugin-prism)** | CloudCLI 内で Claude Code のセッション分析を行い、トークン消費の可視化も提供 |
+| **[Sessions](https://github.com/strykereye2/cloudcli-plugin-session-manager)** | アクティブな Claude Code セッションを表示、管理、終了 |
+| **[Token Cost Calculator](https://github.com/NightmareAway/cloudcli-plugin-token-cost-calculator)** | モデル価格とトークン使用量から API コストを計算し、モデル価格プリセットにも対応 |
+| **[Task Queue](https://github.com/TadMSTR/cloudcli-plugin-task-queue)** | エージェントタスクを表示、フィルタリング、起動するためのタスクキューダッシュボード |
+| **[GitHub Issues Board](https://github.com/szmidtpiotr/claude-github-issue)** | GitHub Issues 用の Kanban ボード。TaskMaster との双方向同期と /github-task CLI スキルの自動インストールに対応 |

 ### 自作する

--- 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 모델 계열에서 작동 (`public/modelConstants.js`에서 전체 지원 모델 확인)
+- **모델 호환성** - Claude, GPT, Gemini 모델 계열에서 작동 (`GET /api/providers/:provider/models` API에서 전체 지원 모델 확인)

 ## 빠른 시작

@@ -158,6 +158,14 @@ CloudCLI는 커스텀 탭과 선택적 Node.js 백엔드가 포함된 플러그
 | 플러그인 | 설명 |
 |---|---|
 | **[Project Stats](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** | 현재 프로젝트의 파일 수, 코드 줄 수, 파일 유형 분포, 가장 큰 파일, 최근 수정 파일을 표시 |
+| **[Web Terminal](https://github.com/cloudcli-ai/cloudcli-plugin-terminal)** | 다중 탭을 지원하는 전체 xterm.js 터미널 |
+| **[Claude Watch](https://github.com/satsuki19980613/cloudcli-claude-watch)** | 장시간 실행 중인 Claude Code 세션의 중단 상태를 감시하고 프로세스 제어를 제공 |
+| **[CloudCLI Scheduler](https://github.com/grostim/cloudcli-cron)** | 워크스페이스 범위 예약 프롬프트를 만들고 Codex, Claude Code, Gemini CLI 같은 로컬 CLI로 실행 |
+| **[PRISM CloudCLI](https://github.com/jakeefr/cloudcli-plugin-prism)** | CloudCLI 안에서 Claude Code 세션 인텔리전스와 토큰 소모 가시성을 제공 |
+| **[Sessions](https://github.com/strykereye2/cloudcli-plugin-session-manager)** | 활성 Claude Code 세션을 보고, 관리하고, 종료 |
+| **[Token Cost Calculator](https://github.com/NightmareAway/cloudcli-plugin-token-cost-calculator)** | 모델 가격과 토큰 사용량으로 API 비용을 계산하고 모델 가격 프리셋을 지원 |
+| **[Task Queue](https://github.com/TadMSTR/cloudcli-plugin-task-queue)** | 에이전트 작업을 보고, 필터링하고, 실행하는 작업 큐 대시보드 |
+| **[GitHub Issues Board](https://github.com/szmidtpiotr/claude-github-issue)** | GitHub Issues용 Kanban 보드. TaskMaster 양방향 동기화와 /github-task CLI 스킬 자동 설치 지원 |

 ### 직접 만들기

--- 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 [`public/modelConstants.js`](public/modelConstants.js) for the full list of supported models)
+- **Model Compatibility** - Works with Claude, GPT, and Gemini model families (the full list of supported models is available at runtime via `GET /api/providers/:provider/models`)


 ## Quick Start
@@ -163,8 +163,15 @@ CloudCLI has a plugin system that lets you add custom tabs with their own fronte
 | Plugin | Description |
 |---|---|
 | **[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|
+| **[Web Terminal](https://github.com/cloudcli-ai/cloudcli-plugin-terminal)** | Full xterm.js terminal with multi-tab support |
+| **[Claude Watch](https://github.com/satsuki19980613/cloudcli-claude-watch)** | Watches long-running Claude Code sessions for hangs and exposes process controls |
+| **[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 |
+| **[PRISM CloudCLI](https://github.com/jakeefr/cloudcli-plugin-prism)** | Session intelligence for Claude Code inside CloudCLI, including token burn visibility |
+| **[Sessions](https://github.com/strykereye2/cloudcli-plugin-session-manager)** | View, manage, and kill active Claude Code sessions |
+| **[Token Cost Calculator](https://github.com/NightmareAway/cloudcli-plugin-token-cost-calculator)** | Calculate API costs from model prices and token usage, with preset model pricing support |
+| **[Task Queue](https://github.com/TadMSTR/cloudcli-plugin-task-queue)** | Task queue dashboard to view, filter, and launch agent tasks |
+| **[GitHub Issues Board](https://github.com/szmidtpiotr/claude-github-issue)** | Kanban board for GitHub Issues with bidirectional TaskMaster sync and /github-task CLI skill auto-install |
+
 ### 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.
--- 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 (см. [`public/modelConstants.js`](public/modelConstants.js) для полного списка поддерживаемых моделей)
+- **Совместимость с моделями** - работает с семействами моделей Claude, GPT и Gemini (полный список поддерживаемых моделей доступен через `GET /api/providers/:provider/models`)


 ## Быстрый старт
@@ -164,6 +164,14 @@ CloudCLI UI — это open source UI-слой, на котором постро
 | Плагин | Описание |
 |---|---|
 | **[Project Stats](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** | Показывает количество файлов, строки кода, разбивку по типам файлов, самые большие файлы и недавно изменённые файлы для текущего проекта |
+| **[Web Terminal](https://github.com/cloudcli-ai/cloudcli-plugin-terminal)** | Полноценный терминал xterm.js с поддержкой нескольких вкладок |
+| **[Claude Watch](https://github.com/satsuki19980613/cloudcli-claude-watch)** | Отслеживает зависания долгих сессий Claude Code и предоставляет управление процессами |
+| **[CloudCLI Scheduler](https://github.com/grostim/cloudcli-cron)** | Создаёт запланированные промпты для рабочей области и запускает их через локальную CLI, например Codex, Claude Code или Gemini CLI |
+| **[PRISM CloudCLI](https://github.com/jakeefr/cloudcli-plugin-prism)** | Аналитика сессий Claude Code внутри CloudCLI, включая видимость расхода токенов |
+| **[Sessions](https://github.com/strykereye2/cloudcli-plugin-session-manager)** | Просмотр, управление и завершение активных сессий Claude Code |
+| **[Token Cost Calculator](https://github.com/NightmareAway/cloudcli-plugin-token-cost-calculator)** | Расчёт стоимости API по ценам моделей и использованию токенов, с поддержкой пресетов цен |
+| **[Task Queue](https://github.com/TadMSTR/cloudcli-plugin-task-queue)** | Дашборд очереди задач для просмотра, фильтрации и запуска агентских задач |
+| **[GitHub Issues Board](https://github.com/szmidtpiotr/claude-github-issue)** | Kanban-доска для GitHub Issues с двусторонней синхронизацией TaskMaster и автоустановкой CLI-навыка /github-task |

 ### Создать свой

--- 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 [`public/modelConstants.js`](public/modelConstants.js) dosyasına bak)
+- **Model Uyumluluğu** — Claude, GPT ve Gemini model aileleriyle çalışır (desteklenen tüm modeller için `GET /api/providers/:provider/models` API'sine bak)


 ## Hızlı Başlangıç
@@ -164,6 +164,13 @@ CloudCLI, kendi frontend UI'sı ve isteğe bağlı Node.js arka ucu olan özel s
 |---|---|
 | **[Project Stats](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** | Mevcut projen için dosya sayıları, kod satırları, dosya türü dağılımı, en büyük dosyalar ve son değiştirilen dosyaları gösterir |
 | **[Web Terminal](https://github.com/cloudcli-ai/cloudcli-plugin-terminal)** | Çoklu sekme destekli tam xterm.js terminali |
+| **[Claude Watch](https://github.com/satsuki19980613/cloudcli-claude-watch)** | Uzun süren Claude Code oturumlarını takılmalara karşı izler ve süreç kontrolleri sunar |
+| **[CloudCLI Scheduler](https://github.com/grostim/cloudcli-cron)** | Çalışma alanı kapsamlı zamanlanmış prompt'lar oluşturur ve bunları Codex, Claude Code veya Gemini CLI gibi yerel CLI'larla çalıştırır |
+| **[PRISM CloudCLI](https://github.com/jakeefr/cloudcli-plugin-prism)** | CloudCLI içinde Claude Code oturum zekası ve token tüketimi görünürlüğü sağlar |
+| **[Sessions](https://github.com/strykereye2/cloudcli-plugin-session-manager)** | Aktif Claude Code oturumlarını görüntülemeni, yönetmeni ve sonlandırmanı sağlar |
+| **[Token Cost Calculator](https://github.com/NightmareAway/cloudcli-plugin-token-cost-calculator)** | Model fiyatları ve token kullanımından API maliyetlerini hesaplar; model fiyatı hazır ayarlarını destekler |
+| **[Task Queue](https://github.com/TadMSTR/cloudcli-plugin-task-queue)** | Ajan görevlerini görüntülemek, filtrelemek ve başlatmak için görev kuyruğu paneli |
+| **[GitHub Issues Board](https://github.com/szmidtpiotr/claude-github-issue)** | GitHub Issues için Kanban panosu; çift yönlü TaskMaster senkronizasyonu ve /github-task CLI becerisi otomatik kurulumu içerir |

 ### Kendi Eklentini Yaz

--- 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 模型家族（完整支持列表见 [`public/modelConstants.js`](public/modelConstants.js)）
+- **模型兼容性** - 支持 Claude、GPT、Gemini 模型家族（完整支持列表可通过 `GET /api/providers/:provider/models` 接口获取）

 ## 快速开始

@@ -158,6 +158,14 @@ CloudCLI 配备插件系统，允许你添加带自定义前端 UI 和可选 Nod
 | 插件 | 描述 |
 |---|---|
 | **[Project Stats](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** | 展示当前项目的文件数、代码行数、文件类型分布、最大文件以及最近修改的文件 |
+| **[Web Terminal](https://github.com/cloudcli-ai/cloudcli-plugin-terminal)** | 支持多标签页的完整 xterm.js 终端 |
+| **[Claude Watch](https://github.com/satsuki19980613/cloudcli-claude-watch)** | 监控长时间运行的 Claude Code 会话是否卡住，并提供进程控制 |
+| **[CloudCLI Scheduler](https://github.com/grostim/cloudcli-cron)** | 创建工作区范围的定时提示词，并通过 Codex、Claude Code 或 Gemini CLI 等本地 CLI 执行 |
+| **[PRISM CloudCLI](https://github.com/jakeefr/cloudcli-plugin-prism)** | 在 CloudCLI 中提供 Claude Code 会话智能分析，包括 token 消耗可视化 |
+| **[Sessions](https://github.com/strykereye2/cloudcli-plugin-session-manager)** | 查看、管理并终止活动的 Claude Code 会话 |
+| **[Token Cost Calculator](https://github.com/NightmareAway/cloudcli-plugin-token-cost-calculator)** | 根据模型价格和 token 用量计算 API 成本，并支持模型价格预设 |
+| **[Task Queue](https://github.com/TadMSTR/cloudcli-plugin-task-queue)** | 用于查看、筛选和启动代理任务的任务队列仪表板 |
+| **[GitHub Issues Board](https://github.com/szmidtpiotr/claude-github-issue)** | 用于 GitHub Issues 的看板，支持 TaskMaster 双向同步和 /github-task CLI 技能自动安装 |

 ### 自行构建

--- a/README.zh-TW.md
+++ b/README.zh-TW.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 模型家族（完整支援列表可透過 `GET /api/providers/:provider/models` 介面取得）

 ## 快速開始

@@ -158,6 +158,14 @@ CloudCLI 配備外掛系統，允許你新增帶有自訂前端 UI 和選用 Nod
 | 外掛 | 描述 |
 |---|---|
 | **[Project Stats](https://github.com/cloudcli-ai/cloudcli-plugin-starter)** | 展示目前專案的檔案數、程式碼行數、檔案類型分佈、最大檔案以及最近修改的檔案 |
+| **[Web Terminal](https://github.com/cloudcli-ai/cloudcli-plugin-terminal)** | 支援多分頁的完整 xterm.js 終端機 |
+| **[Claude Watch](https://github.com/satsuki19980613/cloudcli-claude-watch)** | 監控長時間執行的 Claude Code 工作階段是否卡住，並提供程序控制 |
+| **[CloudCLI Scheduler](https://github.com/grostim/cloudcli-cron)** | 建立工作區範圍的排程提示詞，並透過 Codex、Claude Code 或 Gemini CLI 等本機 CLI 執行 |
+| **[PRISM CloudCLI](https://github.com/jakeefr/cloudcli-plugin-prism)** | 在 CloudCLI 中提供 Claude Code 工作階段智慧分析，包括 token 消耗可視化 |
+| **[Sessions](https://github.com/strykereye2/cloudcli-plugin-session-manager)** | 檢視、管理並終止作用中的 Claude Code 工作階段 |
+| **[Token Cost Calculator](https://github.com/NightmareAway/cloudcli-plugin-token-cost-calculator)** | 根據模型價格與 token 用量計算 API 成本，並支援模型價格預設 |
+| **[Task Queue](https://github.com/TadMSTR/cloudcli-plugin-task-queue)** | 用於檢視、篩選和啟動代理任務的任務佇列儀表板 |
+| **[GitHub Issues Board](https://github.com/szmidtpiotr/claude-github-issue)** | 用於 GitHub Issues 的看板，支援 TaskMaster 雙向同步和 /github-task CLI 技能自動安裝 |

 ### 自行建構

--- a/electron/assets/logo-macos.icns
+++ b/electron/assets/logo-macos.icns
--- a/electron/assets/logo-macos.png
+++ b/electron/assets/logo-macos.png
--- a/electron/cloud.js
+++ b/electron/cloud.js
@@ -0,0 +1,240 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { safeStorage } from 'electron';
+
+function encryptSecret(secret) {
+  if (!safeStorage.isEncryptionAvailable()) {
+    return { encrypted: false, value: secret };
+  }
+
+  return {
+    encrypted: true,
+    value: safeStorage.encryptString(secret).toString('base64'),
+  };
+}
+
+function decryptSecret(record) {
+  if (!record?.value) return null;
+  if (!record.encrypted) return record.value;
+  return safeStorage.decryptString(Buffer.from(record.value, 'base64'));
+}
+
+export class CloudController {
+  constructor({ storePath, controlPlaneUrl, callbackUrl, onChange }) {
+    this.storePath = storePath;
+    this.controlPlaneUrl = controlPlaneUrl;
+    this.callbackUrl = callbackUrl;
+    this.onChange = onChange;
+    this.cloudAccount = null;
+    this.cloudEnvironments = [];
+    this.authState = 'logged_out';
+  }
+
+  getAccount() {
+    return this.cloudAccount;
+  }
+
+  getAuthState() {
+    return this.authState;
+  }
+
+  getEnvironments() {
+    return this.cloudEnvironments;
+  }
+
+  getEnvironmentUrl(environment) {
+    return environment.access_url || `https://${environment.subdomain}.cloudcli.ai`;
+  }
+
+  async getEnvironmentLaunchUrl(environment) {
+    if (!environment?.id) {
+      return this.getEnvironmentUrl(environment);
+    }
+
+    const data = await this.cloudApi(`/api/v1/environments/${encodeURIComponent(environment.id)}/launch`, {
+      method: 'POST',
+    });
+
+    return data.launch_url || data.environment_url || this.getEnvironmentUrl(environment);
+  }
+
+  findEnvironment(environmentId) {
+    return this.cloudEnvironments.find((item) => item.id === environmentId) || null;
+  }
+
+  async loadCloudAccount() {
+    try {
+      const raw = await fs.readFile(this.storePath, 'utf8');
+      const stored = JSON.parse(raw);
+      const apiKey = decryptSecret(stored.apiKey);
+      this.cloudAccount = {
+        deviceId: stored.deviceId || crypto.randomUUID(),
+        email: stored.email || null,
+        apiKey: apiKey || null,
+      };
+      this.authState = apiKey ? 'connected' : (stored.email ? 'expired' : 'logged_out');
+      return this.cloudAccount;
+    } catch {
+      this.cloudAccount = {
+        deviceId: crypto.randomUUID(),
+        email: null,
+        apiKey: null,
+      };
+      this.authState = 'logged_out';
+      return this.cloudAccount;
+    }
+  }
+
+  async saveCloudAccount(account) {
+    const payload = {
+      deviceId: account.deviceId || crypto.randomUUID(),
+      email: account.email || null,
+      apiKey: account.apiKey ? encryptSecret(account.apiKey) : null,
+    };
+
+    await fs.mkdir(path.dirname(this.storePath), { recursive: true });
+    await fs.writeFile(this.storePath, JSON.stringify(payload, null, 2), 'utf8');
+    this.cloudAccount = {
+      deviceId: payload.deviceId,
+      email: payload.email,
+      apiKey: account.apiKey || null,
+    };
+    this.authState = account.apiKey ? 'connected' : 'logged_out';
+    this.onChange?.();
+    return this.cloudAccount;
+  }
+
+  async clearCloudAccount() {
+    this.cloudAccount = {
+      deviceId: crypto.randomUUID(),
+      email: null,
+      apiKey: null,
+    };
+    this.cloudEnvironments = [];
+    this.authState = 'logged_out';
+    await fs.rm(this.storePath, { force: true });
+    this.onChange?.();
+  }
+
+  async invalidateCloudAccount() {
+    this.cloudEnvironments = [];
+    if (!this.cloudAccount) {
+      this.cloudAccount = {
+        deviceId: crypto.randomUUID(),
+        email: null,
+        apiKey: null,
+      };
+    } else {
+      this.cloudAccount = {
+        ...this.cloudAccount,
+        apiKey: null,
+      };
+    }
+    this.authState = this.cloudAccount.email ? 'expired' : 'logged_out';
+    const payload = {
+      deviceId: this.cloudAccount.deviceId,
+      email: this.cloudAccount.email || null,
+      apiKey: null,
+    };
+    await fs.mkdir(path.dirname(this.storePath), { recursive: true });
+    await fs.writeFile(this.storePath, JSON.stringify(payload, null, 2), 'utf8');
+    this.onChange?.();
+  }
+
+  async cloudApi(pathname, options = {}) {
+    if (!this.cloudAccount?.apiKey) {
+      throw new Error('Connect your CloudCLI account first.');
+    }
+
+    const response = await fetch(`${this.controlPlaneUrl}${pathname}`, {
+      ...options,
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-Key': this.cloudAccount.apiKey,
+        ...(options.headers || {}),
+      },
+    });
+
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      if (response.status === 401 || response.status === 403) {
+        await this.invalidateCloudAccount();
+      }
+      throw new Error(body.error || `CloudCLI API request failed: ${response.status}`);
+    }
+
+    return body;
+  }
+
+  async refreshCloudEnvironments() {
+    if (!this.cloudAccount?.apiKey) {
+      this.cloudEnvironments = [];
+      this.onChange?.();
+      return [];
+    }
+
+    const data = await this.cloudApi('/api/v1/environments');
+    this.cloudEnvironments = data.environments || [];
+    this.onChange?.();
+    return this.cloudEnvironments;
+  }
+
+  async startEnvironment(environment) {
+    await this.cloudApi(`/api/v1/environments/${encodeURIComponent(environment.id)}/start`, {
+      method: 'POST',
+    });
+  }
+
+  async stopEnvironment(environment) {
+    await this.cloudApi(`/api/v1/environments/${encodeURIComponent(environment.id)}/stop`, {
+      method: 'POST',
+    });
+  }
+
+  async getEnvironmentCredentials(environment) {
+    return this.cloudApi(`/api/v1/environments/${encodeURIComponent(environment.id)}/credentials`);
+  }
+
+  async startEnvironmentAndWait(environment, timeoutMs) {
+    await this.startEnvironment(environment);
+
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+      const environments = await this.refreshCloudEnvironments();
+      const current = environments.find((env) => env.id === environment.id);
+      if (current?.status === 'running') {
+        return current;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+    }
+
+    throw new Error(`${environment.name} did not become ready in time.`);
+  }
+
+  buildConnectUrl() {
+    if (!this.cloudAccount?.deviceId) {
+      this.cloudAccount = {
+        deviceId: crypto.randomUUID(),
+        email: null,
+        apiKey: null,
+      };
+    }
+
+    const connectUrl = new URL('/auth/app-connect', this.controlPlaneUrl);
+    connectUrl.searchParams.set('device_id', this.cloudAccount.deviceId);
+    connectUrl.searchParams.set('callback_url', this.callbackUrl);
+    connectUrl.searchParams.set('app_surface', 'cloudcli_desktop');
+    connectUrl.searchParams.set('client_platform', 'desktop');
+    return connectUrl.toString();
+  }
+
+  async saveFromCallback({ apiKey, email }) {
+    await this.saveCloudAccount({
+      deviceId: this.cloudAccount?.deviceId || crypto.randomUUID(),
+      email,
+      apiKey,
+    });
+    return this.cloudAccount;
+  }
+}
--- a/electron/computerAgent.js
+++ b/electron/computerAgent.js
@@ -0,0 +1,225 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const IPC_PREFIX = '@@CUAGENT@@';
+
+function getDesktopPath() {
+  const currentPath = process.env.PATH || '';
+  const commonPaths = process.platform === 'win32'
+    ? []
+    : ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'];
+  return [...commonPaths, currentPath].filter(Boolean).join(path.delimiter);
+}
+
+function getNodeRuntime(isPackaged) {
+  if (isPackaged && process.versions.electron) {
+    return { command: process.execPath, env: { ELECTRON_RUN_AS_NODE: '1' } };
+  }
+  if (process.env.npm_node_execpath) {
+    return { command: process.env.npm_node_execpath, env: {} };
+  }
+  return { command: 'node', env: {} };
+}
+
+/** Converts an environment access URL (https://x) to its desktop-agent ws URL. */
+function toAgentWsUrl(httpUrl) {
+  try {
+    const parsed = new URL(httpUrl);
+    parsed.protocol = parsed.protocol === 'http:' ? 'ws:' : 'wss:';
+    parsed.pathname = '/desktop-agent';
+    parsed.search = '';
+    parsed.hash = '';
+    return parsed.toString();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Manages the standalone Computer Use desktop agent process. While the user has
+ * Computer Use enabled, this keeps an agent connected to every running cloud
+ * environment so hosted sessions can drive this machine. The local CloudCLI
+ * server is not involved.
+ */
+export class ComputerAgentController {
+  constructor({ appRoot, settingsPath, isPackaged = false, getRunningEnvironmentUrls, promptConsent, onChange }) {
+    this.appRoot = appRoot;
+    this.settingsPath = settingsPath;
+    this.isPackaged = isPackaged;
+    this.getRunningEnvironmentUrls = getRunningEnvironmentUrls;
+    this.promptConsent = promptConsent;
+    this.onChange = onChange;
+    this.settings = { enabled: false, consentMode: 'ask' };
+    this.child = null;
+    this.connectedUrls = new Set();
+    this.currentTargets = [];
+    this.stdoutBuffer = '';
+  }
+
+  getSettings() {
+    return { ...this.settings };
+  }
+
+  getState() {
+    return {
+      enabled: this.settings.enabled,
+      consentMode: this.settings.consentMode,
+      running: Boolean(this.child),
+      connectedCount: this.connectedUrls.size,
+      targetCount: this.currentTargets.length,
+    };
+  }
+
+  async loadSettings() {
+    try {
+      const raw = await fs.readFile(this.settingsPath, 'utf8');
+      const stored = JSON.parse(raw);
+      this.settings = {
+        enabled: Boolean(stored.enabled),
+        consentMode: stored.consentMode === 'auto' ? 'auto' : 'ask',
+      };
+    } catch {
+      this.settings = { enabled: false, consentMode: 'ask' };
+    }
+    return this.settings;
+  }
+
+  async saveSettings(next) {
+    this.settings = {
+      enabled: Boolean(next.enabled),
+      consentMode: next.consentMode === 'auto' ? 'auto' : 'ask',
+    };
+    await fs.mkdir(path.dirname(this.settingsPath), { recursive: true });
+    await fs.writeFile(this.settingsPath, JSON.stringify(this.settings, null, 2), 'utf8');
+    await this.sync();
+    this.onChange?.();
+    return this.settings;
+  }
+
+  /** Reconciles the agent process with the current settings + environments. */
+  async sync() {
+    const targets = this.settings.enabled ? (this.getRunningEnvironmentUrls?.() || []) : [];
+    const wsTargets = targets.map(toAgentWsUrl).filter(Boolean);
+
+    const sameTargets =
+      wsTargets.length === this.currentTargets.length &&
+      wsTargets.every((url) => this.currentTargets.includes(url));
+
+    if (!this.settings.enabled || wsTargets.length === 0) {
+      this.stop();
+      this.currentTargets = [];
+      return;
+    }
+
+    if (this.child && sameTargets) {
+      return; // already running with the right targets
+    }
+
+    this.currentTargets = wsTargets;
+    this.restart(wsTargets);
+  }
+
+  restart(wsTargets) {
+    this.stop();
+
+    const agentEntry = process.env.CLOUDCLI_COMPUTER_AGENT_ENTRY
+      || path.join(this.appRoot, 'dist-server', 'server', 'computer-use-agent.js');
+    const runtime = getNodeRuntime(this.isPackaged);
+
+    this.child = spawn(runtime.command, [agentEntry], {
+      cwd: this.appRoot,
+      env: {
+        ...process.env,
+        ...runtime.env,
+        PATH: getDesktopPath(),
+        CLOUDCLI_DESKTOP_AGENT_URLS: wsTargets.join(','),
+        CLOUDCLI_COMPUTER_USE_CONSENT_MODE: this.settings.consentMode,
+      },
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+
+    this.connectedUrls = new Set();
+
+    this.child.once('error', (error) => {
+      console.error('[ComputerAgent] failed to start:', error.message);
+      this.child = null;
+      this.onChange?.();
+    });
+
+    this.child.stdout?.on('data', (chunk) => this.handleStdout(String(chunk)));
+    this.child.stderr?.on('data', (chunk) => {
+      for (const line of String(chunk).split(/\r?\n/)) {
+        if (line.trim()) console.error('[ComputerAgent]', line);
+      }
+    });
+
+    this.child.once('exit', (code) => {
+      console.log(`[ComputerAgent] exited (code ${code ?? 'null'})`);
+      this.child = null;
+      this.connectedUrls = new Set();
+      this.onChange?.();
+    });
+
+    this.onChange?.();
+  }
+
+  handleStdout(chunk) {
+    this.stdoutBuffer += chunk;
+    const lines = this.stdoutBuffer.split('\n');
+    this.stdoutBuffer = lines.pop() || '';
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith(IPC_PREFIX)) {
+        if (trimmed) console.log('[ComputerAgent]', trimmed);
+        continue;
+      }
+      let payload;
+      try {
+        payload = JSON.parse(trimmed.slice(IPC_PREFIX.length).trim());
+      } catch {
+        continue;
+      }
+      void this.handleAgentEvent(payload);
+    }
+  }
+
+  async handleAgentEvent(payload) {
+    switch (payload.type) {
+      case 'connected':
+        this.connectedUrls.add(payload.url);
+        this.onChange?.();
+        break;
+      case 'disconnected':
+        this.connectedUrls.delete(payload.url);
+        this.onChange?.();
+        break;
+      case 'consent-request': {
+        const allow = await this.promptConsent?.(payload.sessionId);
+        this.sendToChild({ type: 'consent-response', sessionId: payload.sessionId, allow: Boolean(allow) });
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  sendToChild(message) {
+    if (this.child?.stdin?.writable) {
+      this.child.stdin.write(`${IPC_PREFIX} ${JSON.stringify(message)}\n`);
+    }
+  }
+
+  revokeSession(sessionId) {
+    this.sendToChild({ type: 'revoke-session', sessionId });
+  }
+
+  stop() {
+    if (!this.child) return;
+    const child = this.child;
+    this.child = null;
+    this.connectedUrls = new Set();
+    try { child.kill('SIGTERM'); } catch { /* noop */ }
+  }
+}
--- a/electron/desktopWindow.js
+++ b/electron/desktopWindow.js
@@ -0,0 +1,756 @@
+import { BrowserView, BrowserWindow, Menu, Tray, nativeImage, nativeTheme, session } from 'electron';
+
+const TITLEBAR_HEIGHT = 44;
+
+function escapeHtml(value) {
+  return String(value == null ? '' : value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function buildPlaceholderHtml(title, message, logs = []) {
+  const logHtml = logs.length
+    ? `<pre>${logs.map(escapeHtml).join('\n')}</pre>`
+    : '<pre>Waiting for process output...</pre>';
+  return [
+    '<!doctype html><meta charset="utf-8">',
+    '<style>',
+    'html,body{margin:0;height:100%;background:#0a0a0a;color:#fafafa;font:14px -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}',
+    'body{padding:28px;overflow:hidden}',
+    '.shell{height:100%;display:flex;flex-direction:column;gap:16px}',
+    '.box{display:flex;align-items:center;gap:10px;color:#d4d4d4;flex:0 0 auto}',
+    '.dot{width:8px;height:8px;border-radius:50%;background:#0b60ea;box-shadow:0 0 0 6px rgba(11,96,234,.15)}',
+    'pre{margin:0;flex:1;overflow:auto;border:1px solid #262626;border-radius:10px;background:#050505;color:#d4d4d4;padding:14px;font:12px/1.55 ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;white-space:pre-wrap;user-select:text}',
+    '</style>',
+    '<div class="shell">',
+    `<div class="box"><span class="dot"></span><span>${escapeHtml(message || `Opening ${title}...`)}</span></div>`,
+    logHtml,
+    '</div>',
+  ].join('');
+}
+
+export class DesktopWindowManager {
+  constructor({
+    appName,
+    getWindowIconPath,
+    getLauncherPath,
+    getPreloadPath,
+    openExternalUrl,
+    getDesktopState,
+    getDisplayTargetName,
+    getRemoteEnvironmentMenuItems,
+    getCloudState,
+    getLocalState,
+    actions,
+    tabs,
+  }) {
+    this.appName = appName;
+    this.getWindowIconPath = getWindowIconPath;
+    this.getLauncherPath = getLauncherPath;
+    this.getPreloadPath = getPreloadPath;
+    this.openExternalUrl = openExternalUrl;
+    this.getDesktopState = getDesktopState;
+    this.getDisplayTargetName = getDisplayTargetName;
+    this.getRemoteEnvironmentMenuItems = getRemoteEnvironmentMenuItems;
+    this.getCloudState = getCloudState;
+    this.getLocalState = getLocalState;
+    this.actions = actions;
+    this.tabs = tabs;
+
+    this.mainWindow = null;
+    this.settingsWindow = null;
+    this.tray = null;
+    this.launcherLoaded = false;
+    this.activeContentView = null;
+    this.tabViews = new Map();
+  }
+
+  getMainWindow() {
+    return this.mainWindow;
+  }
+
+  getTrayImage() {
+    const image = nativeImage.createFromPath(this.getWindowIconPath());
+    return image.resize({ width: 18, height: 18 });
+  }
+
+  getContentViewBounds() {
+    if (!this.mainWindow) return { x: 0, y: TITLEBAR_HEIGHT, width: 0, height: 0 };
+    const [width, height] = this.mainWindow.getContentSize();
+    return {
+      x: 0,
+      y: TITLEBAR_HEIGHT,
+      width,
+      height: Math.max(0, height - TITLEBAR_HEIGHT),
+    };
+  }
+
+  configureChildWebContents(webContents) {
+    webContents.setWindowOpenHandler(({ url }) => {
+      void this.openExternalUrl(url).catch((error) => this.actions.showError('Could not open external link', error));
+      return { action: 'deny' };
+    });
+  }
+
+  detachActiveContentView() {
+    if (!this.mainWindow || this.mainWindow.isDestroyed() || !this.activeContentView) return;
+    try {
+      if (this.mainWindow.getBrowserViews().includes(this.activeContentView)) {
+        this.mainWindow.removeBrowserView(this.activeContentView);
+      }
+    } catch {
+      // BrowserViews may already be gone during BrowserWindow teardown.
+    }
+    this.activeContentView = null;
+  }
+
+  getOrCreateTabView(tabId) {
+    let view = this.tabViews.get(tabId);
+    if (view) return view;
+
+    view = new BrowserView({
+      webPreferences: {
+        contextIsolation: true,
+        nodeIntegration: false,
+        sandbox: true,
+        preload: this.getPreloadPath(),
+      },
+    });
+    this.configureChildWebContents(view.webContents);
+    this.tabViews.set(tabId, view);
+    return view;
+  }
+
+  attachContentView(view) {
+    if (!this.mainWindow || this.mainWindow.isDestroyed()) return;
+    if (this.activeContentView && this.activeContentView !== view) {
+      this.detachActiveContentView();
+    }
+    this.activeContentView = view;
+    try {
+      if (!this.mainWindow.getBrowserViews().includes(view)) {
+        this.mainWindow.addBrowserView(view);
+      }
+    } catch {
+      return;
+    }
+    view.setBounds(this.getContentViewBounds());
+    view.setAutoResize({ width: true, height: true });
+  }
+
+  async showTabPlaceholder(target, message) {
+    const tabId = this.tabs.getTabIdForTarget(target);
+    const view = this.getOrCreateTabView(tabId);
+    this.attachContentView(view);
+    const html = buildPlaceholderHtml(target.name || this.appName, message);
+    await view.webContents.loadURL(`data:text/html;charset=utf-8,${encodeURIComponent(html)}`);
+    view.__cloudcliStartupHtml = html;
+    view.__cloudcliLoadedUrl = null;
+  }
+
+  async showLocalStartupTarget(target, logs) {
+    const tabId = this.tabs.getTabIdForTarget(target);
+    const view = this.getOrCreateTabView(tabId);
+    if (view.__cloudcliLoadingUrl) return;
+    this.attachContentView(view);
+    const html = buildPlaceholderHtml(target.name || this.appName, 'Starting Local CloudCLI...', logs);
+    if (view.__cloudcliStartupHtml === html) return;
+    await view.webContents.loadURL(`data:text/html;charset=utf-8,${encodeURIComponent(html)}`);
+    view.__cloudcliStartupHtml = html;
+    view.__cloudcliLoadedUrl = null;
+  }
+
+  async showContentTarget(target) {
+    const tabId = this.tabs.getTabIdForTarget(target);
+    const view = this.getOrCreateTabView(tabId);
+    this.attachContentView(view);
+    if (view.__cloudcliLoadedUrl !== target.url) {
+      view.__cloudcliLoadingUrl = target.url;
+      try {
+        await view.webContents.loadURL(target.url);
+        view.__cloudcliLoadedUrl = target.url;
+        view.__cloudcliStartupHtml = null;
+      } finally {
+        if (view.__cloudcliLoadingUrl === target.url) {
+          view.__cloudcliLoadingUrl = null;
+        }
+      }
+    }
+  }
+
+  destroyTabView(tabId) {
+    const view = this.tabViews.get(tabId);
+    if (!view) return;
+    if (this.mainWindow && !this.mainWindow.isDestroyed()) {
+      try {
+        if (this.mainWindow.getBrowserViews().includes(view)) {
+          this.mainWindow.removeBrowserView(view);
+        }
+      } catch {
+        // Ignore teardown races; Electron owns final destruction during quit.
+      }
+    }
+    if (this.activeContentView === view) {
+      this.activeContentView = null;
+    }
+    try {
+      if (!view.webContents.isDestroyed()) {
+        view.webContents.destroy();
+      }
+    } catch {
+      // The view may already be destroyed by its parent BrowserWindow.
+    }
+    this.tabViews.delete(tabId);
+  }
+
+  emitDesktopState() {
+    const state = this.getDesktopState();
+    if (this.mainWindow && !this.mainWindow.webContents.isDestroyed()) {
+      this.mainWindow.webContents.send('cloudcli-desktop:state-updated', state);
+    }
+    if (this.settingsWindow && !this.settingsWindow.webContents.isDestroyed()) {
+      this.settingsWindow.webContents.send('cloudcli-desktop:state-updated', state);
+    }
+  }
+
+  emitLauncherCommand(command) {
+    if (!this.mainWindow || this.mainWindow.webContents.isDestroyed()) return;
+    this.mainWindow.webContents.send('cloudcli-desktop:launcher-command', command);
+  }
+
+  emitSettingsCommand(command) {
+    if (!this.settingsWindow || this.settingsWindow.webContents.isDestroyed()) return;
+    this.settingsWindow.webContents.send('cloudcli-desktop:launcher-command', command);
+  }
+
+  syncSettingsWindowBounds() {
+    if (!this.mainWindow || !this.settingsWindow || this.settingsWindow.isDestroyed()) return;
+    this.settingsWindow.setBounds(this.mainWindow.getBounds());
+  }
+
+  async ensureSettingsWindow(sheet = 'desktop-settings') {
+    if (!this.mainWindow) return null;
+
+    if (this.settingsWindow && !this.settingsWindow.isDestroyed()) {
+      this.syncSettingsWindowBounds();
+      this.emitSettingsCommand({ type: 'open-sheet', sheet });
+      this.settingsWindow.focus();
+      return this.settingsWindow;
+    }
+
+    this.settingsWindow = new BrowserWindow({
+      parent: this.mainWindow,
+      modal: true,
+      show: false,
+      frame: false,
+      transparent: true,
+      hasShadow: false,
+      resizable: false,
+      minimizable: false,
+      maximizable: false,
+      fullscreenable: false,
+      movable: false,
+      skipTaskbar: true,
+      backgroundColor: '#00000000',
+      webPreferences: {
+        contextIsolation: true,
+        nodeIntegration: false,
+        sandbox: true,
+        preload: this.getPreloadPath(),
+      },
+    });
+    this.syncSettingsWindowBounds();
+    this.configureChildWebContents(this.settingsWindow.webContents);
+    this.settingsWindow.once('ready-to-show', () => this.settingsWindow?.show());
+    this.settingsWindow.on('closed', () => {
+      this.settingsWindow = null;
+    });
+    await this.settingsWindow.loadFile(this.getLauncherPath(), {
+      query: { modal: '1', sheet },
+    });
+    return this.settingsWindow;
+  }
+
+  closeSettingsWindow() {
+    if (!this.settingsWindow || this.settingsWindow.isDestroyed()) return;
+    this.settingsWindow.close();
+  }
+
+  async showTarget(target, { trackTab = true } = {}) {
+    if (!this.mainWindow) return;
+    if (trackTab) {
+      this.tabs.upsertTarget(target);
+    }
+    this.actions.setActiveTarget(target);
+    this.buildAppMenu();
+    this.mainWindow.setTitle(`${this.appName} - ${target.name}`);
+    await this.showContentTarget(target);
+    this.emitDesktopState();
+  }
+
+  async showLauncher() {
+    if (!this.mainWindow) return;
+    const target = { kind: 'launcher', name: this.appName, url: null };
+    this.tabs.upsertTarget(target);
+    this.actions.setActiveTarget(target);
+    this.detachActiveContentView();
+    this.buildAppMenu();
+    this.mainWindow.setTitle(this.appName);
+    if (!this.launcherLoaded) {
+      await this.mainWindow.loadFile(this.getLauncherPath());
+      this.launcherLoaded = true;
+    } else {
+      this.emitDesktopState();
+    }
+  }
+
+  async switchDesktopTab(tabId) {
+    const tab = this.tabs.activate(tabId);
+    if (!tab || !this.mainWindow) return this.getDesktopState();
+
+    if (tab.id === 'home' || tab.kind === 'launcher') {
+      await this.showLauncher();
+      return this.getDesktopState();
+    }
+
+    if (!tab.target?.url) {
+      throw new Error('This tab does not have a target URL.');
+    }
+
+    await this.showTarget(tab.target, { trackTab: false });
+    return this.getDesktopState();
+  }
+
+  async closeDesktopTab(tabId) {
+    const tab = this.tabs.remove(tabId);
+    if (!tab) return this.getDesktopState();
+    this.destroyTabView(tabId);
+    if (this.tabs.activeTabId === 'home') {
+      await this.showLauncher();
+    } else {
+      this.emitDesktopState();
+    }
+    return this.getDesktopState();
+  }
+
+  buildEnvironmentActionsSubmenu(environment) {
+    const items = [];
+    const statusSuffix = environment.status === 'running' ? '' : ` (${environment.status})`;
+    items.push({
+      label: 'Open Environment',
+      click: () => void this.actions.openEnvironmentInDesktop(environment)
+        .catch((error) => this.actions.showError(`Could not open ${environment.name || environment.subdomain}${statusSuffix}`, error)),
+    });
+    items.push({
+      label: 'Open in Browser',
+      click: () => void this.actions.openEnvironmentInBrowser(environment)
+        .catch((error) => this.actions.showError('Could not open environment in browser', error)),
+    });
+    items.push({
+      label: 'Open in VS Code',
+      click: () => void this.actions.openEnvironmentInIde(environment, 'vscode')
+        .catch((error) => this.actions.showError('Could not open environment in VS Code', error)),
+    });
+    items.push({
+      label: 'Open in Cursor',
+      click: () => void this.actions.openEnvironmentInIde(environment, 'cursor')
+        .catch((error) => this.actions.showError('Could not open environment in Cursor', error)),
+    });
+    items.push({
+      label: 'Open SSH Terminal',
+      click: () => void this.actions.openEnvironmentInSsh(environment)
+        .catch((error) => this.actions.showError('Could not open SSH terminal', error)),
+    });
+    items.push({
+      label: 'Copy Mobile/Web URL',
+      click: () => this.actions.copyText(this.actions.getEnvironmentUrl(environment)),
+    });
+    if (environment.status !== 'running') {
+      items.unshift({
+        label: environment.status === 'paused' ? 'Resume' : 'Start',
+        click: () => void this.actions.startEnvironment(environment)
+          .catch((error) => this.actions.showError('Could not start environment', error)),
+      });
+    }
+    if (environment.status === 'running') {
+      items.push({
+        label: 'Stop',
+        click: () => void this.actions.stopEnvironment(environment)
+          .catch((error) => this.actions.showError('Could not stop environment', error)),
+      });
+    }
+    return items;
+  }
+
+  buildTrayEnvironmentSection() {
+    const cloudState = this.getCloudState();
+    if (!cloudState.account?.apiKey) {
+      return [
+        {
+          label: cloudState.account?.email ? `Reconnect ${cloudState.account.email}` : 'Login',
+          click: () => void this.actions.connectCloudAccount()
+            .catch((error) => this.actions.showError('Could not connect CloudCLI account', error)),
+        },
+      ];
+    }
+
+    if (!cloudState.environments.length) {
+      return [{ label: 'No environments found', enabled: false }];
+    }
+
+    return cloudState.environments.map((environment) => ({
+      label: `${environment.name || environment.subdomain} - ${environment.status}`,
+      submenu: this.buildEnvironmentActionsSubmenu(environment),
+    }));
+  }
+
+  buildAppMenu() {
+    if (!this.mainWindow) return;
+    const cloudState = this.getCloudState();
+    const localState = this.getLocalState();
+    const remoteItems = this.getRemoteEnvironmentMenuItems();
+    const cloudAccountLabel = cloudState.account?.apiKey
+      ? (cloudState.account?.email ? `Connected: ${cloudState.account.email}` : 'CloudCLI Connected')
+      : (cloudState.account?.email ? `Reconnect: ${cloudState.account.email}` : 'Connect CloudCLI Account...');
+
+    const template = [
+      {
+        label: this.appName,
+        submenu: [
+          { label: `About ${this.appName}`, role: 'about' },
+          { type: 'separator' },
+          {
+            label: 'Show Launcher',
+            accelerator: 'CmdOrCtrl+Shift+L',
+            click: () => void this.showLauncher().catch((error) => this.actions.showError('Could not show launcher', error)),
+          },
+          {
+            label: 'Switch Environment',
+            accelerator: 'CmdOrCtrl+Shift+E',
+            click: () => void this.actions.showEnvironmentPicker().catch((error) => this.actions.showError('Could not switch environment', error)),
+          },
+          { type: 'separator' },
+          {
+            label: 'Services',
+            submenu: [
+              {
+                label: 'Computer Use',
+                click: () => void this.showDesktopSettings(),
+              },
+            ],
+          },
+          {
+            label: 'Diagnostics',
+            submenu: [
+              {
+                label: 'Copy Diagnostics',
+                click: () => void this.actions.copyDiagnostics(),
+              },
+            ],
+          },
+          { type: 'separator' },
+          {
+            label: process.platform === 'darwin' ? `Hide ${this.appName}` : 'Hide',
+            role: 'hide',
+            visible: process.platform === 'darwin',
+          },
+          { label: 'Hide Others', role: 'hideOthers', visible: process.platform === 'darwin' },
+          { label: 'Show All', role: 'unhide', visible: process.platform === 'darwin' },
+          { type: 'separator', visible: process.platform === 'darwin' },
+          { label: `Quit ${this.appName}`, accelerator: 'CmdOrCtrl+Q', role: 'quit' },
+        ],
+      },
+      {
+        label: 'Environment',
+        submenu: [
+          {
+            label: 'Show Launcher',
+            accelerator: 'CmdOrCtrl+Shift+L',
+            click: () => void this.showLauncher().catch((error) => this.actions.showError('Could not show launcher', error)),
+          },
+          {
+            label: 'Switch Environment',
+            accelerator: 'CmdOrCtrl+Shift+E',
+            click: () => void this.actions.showEnvironmentPicker().catch((error) => this.actions.showError('Could not switch environment', error)),
+          },
+          { type: 'separator' },
+          {
+            label: 'Open Local CloudCLI',
+            accelerator: 'CmdOrCtrl+L',
+            click: () => void this.actions.openLocalInDesktop().catch((error) => this.actions.showError('Could not open local CloudCLI', error)),
+          },
+          {
+            label: 'Open Local Web UI in Browser',
+            accelerator: 'CmdOrCtrl+Shift+W',
+            click: () => void this.actions.openLocalWebUi().catch((error) => this.actions.showError('Could not open local web UI', error)),
+          },
+          {
+            label: 'Copy Local Web URL',
+            accelerator: 'CmdOrCtrl+Shift+U',
+            click: () => void this.actions.copyLocalWebUrl().catch((error) => this.actions.showError('Could not copy local web URL', error)),
+          },
+          { type: 'separator' },
+          {
+            label: 'Keep Local Server Running After Quit',
+            type: 'checkbox',
+            checked: localState.desktopSettings.keepLocalServerRunning,
+            click: (menuItem) => void this.actions.updateDesktopSetting('keepLocalServerRunning', menuItem.checked)
+              .catch((error) => this.actions.showError('Could not update desktop setting', error)),
+          },
+          {
+            label: 'Allow LAN Access to Local Server',
+            type: 'checkbox',
+            checked: localState.desktopSettings.exposeLocalServerOnNetwork,
+            click: (menuItem) => void this.actions.updateDesktopSetting('exposeLocalServerOnNetwork', menuItem.checked)
+              .catch((error) => this.actions.showError('Could not update desktop setting', error)),
+          },
+        ],
+      },
+      {
+        label: 'Cloud',
+        submenu: [
+          {
+            label: cloudAccountLabel,
+            accelerator: 'CmdOrCtrl+Shift+C',
+            click: () => void this.actions.connectCloudAccount().catch((error) => this.actions.showError('Could not connect CloudCLI account', error)),
+          },
+          {
+            label: 'Refresh Cloud Environments',
+            click: () => void this.actions.refreshCloudEnvironments().catch((error) => this.actions.showError('Could not load CloudCLI environments', error)),
+            enabled: Boolean(cloudState.account?.apiKey),
+          },
+          {
+            label: 'Disconnect Cloud Account',
+            click: () => void this.actions.clearCloudAccount().catch((error) => this.actions.showError('Could not disconnect cloud account', error)),
+            enabled: Boolean(cloudState.account?.apiKey),
+          },
+          { type: 'separator' },
+          {
+            label: 'Remote Environments',
+            submenu: remoteItems,
+          },
+        ],
+      },
+      {
+        label: 'Edit',
+        submenu: [
+          { role: 'undo' },
+          { role: 'redo' },
+          { type: 'separator' },
+          { role: 'cut' },
+          { role: 'copy' },
+          { role: 'paste' },
+          { role: 'selectAll' },
+        ],
+      },
+      {
+        label: 'View',
+        submenu: [
+          { role: 'reload' },
+          { role: 'forceReload' },
+          { role: 'toggleDevTools' },
+          { type: 'separator' },
+          { role: 'resetZoom' },
+          { role: 'zoomIn' },
+          { role: 'zoomOut' },
+          { type: 'separator' },
+          { role: 'togglefullscreen' },
+        ],
+      },
+      {
+        label: 'Window',
+        submenu: [
+          { role: 'minimize' },
+          { role: 'zoom' },
+          ...(process.platform === 'darwin' ? [{ type: 'separator' }, { role: 'front' }] : []),
+        ],
+      },
+      {
+        label: 'Help',
+        submenu: [
+        {
+          label: 'Open cloudcli.ai',
+          click: () => void this.actions.openCloudDashboard(),
+        },
+          {
+            label: 'Copy Diagnostics',
+            click: () => void this.actions.copyDiagnostics(),
+          },
+        ],
+      },
+    ];
+
+    Menu.setApplicationMenu(Menu.buildFromTemplate(template));
+    this.buildTrayMenu();
+  }
+
+  buildTrayMenu() {
+    if (!this.tray) return;
+    const cloudState = this.getCloudState();
+    const localState = this.getLocalState();
+
+    const template = [
+      {
+        label: 'Local',
+        submenu: [
+          {
+            label: localState.localServerRunning ? 'Open Local in CloudCLI' : 'Start Local in CloudCLI',
+            click: () => void this.actions.openLocalInDesktop().catch((error) => this.actions.showError('Could not open local CloudCLI', error)),
+          },
+          {
+            label: 'Open Local in Browser',
+            click: () => void this.actions.openLocalWebUi().catch((error) => this.actions.showError('Could not open local web UI', error)),
+          },
+          {
+            label: 'Copy Local URL',
+            click: () => void this.actions.copyLocalWebUrl().catch((error) => this.actions.showError('Could not copy local web URL', error)),
+          },
+        ],
+      },
+      {
+        label: 'Cloud Environments',
+        submenu: this.buildTrayEnvironmentSection(),
+      },
+      { type: 'separator' },
+      {
+        label: cloudState.account?.email ? `Connected: ${cloudState.account.email}` : 'Login',
+        click: () => void this.actions.connectCloudAccount().catch((error) => this.actions.showError('Could not connect CloudCLI account', error)),
+      },
+      {
+        label: 'Disconnect Cloud Account',
+        click: () => void this.actions.clearCloudAccount().catch((error) => this.actions.showError('Could not disconnect cloud account', error)),
+        enabled: Boolean(cloudState.account?.apiKey),
+      },
+      { type: 'separator' },
+      {
+        label: `Quit ${this.appName}`,
+        role: 'quit',
+      },
+    ];
+
+    this.tray.setToolTip(`${this.appName}${this.actions.getActiveTarget()?.name ? ` - ${this.actions.getActiveTarget().name}` : ''}`);
+    this.tray.setContextMenu(Menu.buildFromTemplate(template));
+  }
+
+  async showDesktopSettings() {
+    if (!this.mainWindow) return this.getDesktopState();
+    await this.ensureSettingsWindow('desktop-settings');
+    return this.getDesktopState();
+  }
+
+  async showLocalSettings() {
+    if (!this.mainWindow) return this.getDesktopState();
+    await this.ensureSettingsWindow('local-settings');
+    return this.getDesktopState();
+  }
+
+  async showActiveEnvironmentActionsMenu() {
+    if (!this.mainWindow) return this.getDesktopState();
+    const activeTarget = this.actions.getActiveTarget();
+    if (activeTarget?.kind !== 'remote') return this.getDesktopState();
+
+    const environment = this.getCloudState().environments.find((item) => item.id === activeTarget.id);
+    if (!environment) return this.getDesktopState();
+
+    const menu = Menu.buildFromTemplate(this.buildEnvironmentActionsSubmenu(environment));
+    menu.popup({ window: this.mainWindow });
+    return this.getDesktopState();
+  }
+
+  async showEnvironmentActionsMenu(environmentId) {
+    if (!this.mainWindow) return this.getDesktopState();
+    const environment = this.getCloudState().environments.find((item) => item.id === environmentId);
+    if (!environment) return this.getDesktopState();
+
+    const menu = Menu.buildFromTemplate(this.buildEnvironmentActionsSubmenu(environment));
+    menu.popup({ window: this.mainWindow });
+    return this.getDesktopState();
+  }
+
+  configurePermissions() {
+    session.defaultSession.setPermissionRequestHandler((webContents, permission, callback) => {
+      const sourceUrl = webContents.getURL();
+      const isCloudCliOrigin = sourceUrl.startsWith('http://127.0.0.1:')
+        || sourceUrl.startsWith(this.getCloudState().controlPlaneUrl)
+        || /^https:\/\/[a-z0-9-]+\.cloudcli\.ai/i.test(sourceUrl);
+      const allowedPermissions = new Set(['clipboard-read', 'media']);
+      callback(isCloudCliOrigin && allowedPermissions.has(permission));
+    });
+  }
+
+  createTray() {
+    if (this.tray) return;
+    this.tray = new Tray(this.getTrayImage());
+    this.tray.on('click', () => {
+      if (!this.mainWindow) return;
+      if (this.mainWindow.isVisible()) {
+        this.mainWindow.focus();
+      } else {
+        this.mainWindow.show();
+      }
+    });
+    this.buildTrayMenu();
+  }
+
+  async createWindow() {
+    this.mainWindow = new BrowserWindow({
+      width: 1440,
+      height: 960,
+      minWidth: 1024,
+      minHeight: 720,
+      show: false,
+      backgroundColor: '#0f172a',
+      title: this.appName,
+      icon: this.getWindowIconPath(),
+      titleBarStyle: 'hidden',
+      ...(process.platform === 'darwin'
+        ? { trafficLightPosition: { x: 18, y: 14 } }
+        : {
+            titleBarOverlay: {
+              color: nativeTheme.shouldUseDarkColors ? '#111111' : '#f7f8fa',
+              symbolColor: nativeTheme.shouldUseDarkColors ? '#a1a1a1' : '#5b6470',
+              height: 44,
+            },
+          }),
+      webPreferences: {
+        contextIsolation: true,
+        nodeIntegration: false,
+        sandbox: true,
+        preload: this.getPreloadPath(),
+      },
+    });
+
+    this.mainWindow.once('ready-to-show', () => {
+      this.mainWindow?.show();
+    });
+
+    this.mainWindow.webContents.setWindowOpenHandler(({ url }) => {
+      void this.openExternalUrl(url).catch((error) => this.actions.showError('Could not open external link', error));
+      return { action: 'deny' };
+    });
+
+    this.mainWindow.on('resize', () => {
+      if (this.activeContentView) {
+        this.activeContentView.setBounds(this.getContentViewBounds());
+      }
+      this.syncSettingsWindowBounds();
+    });
+
+    this.mainWindow.on('move', () => {
+      this.syncSettingsWindowBounds();
+    });
+
+    this.mainWindow.on('closed', () => {
+      this.tabViews.clear();
+      this.activeContentView = null;
+      this.settingsWindow = null;
+      this.mainWindow = null;
+      this.launcherLoaded = false;
+    });
+
+    this.buildAppMenu();
+    await this.showLauncher();
+  }
+}
--- a/electron/launcher/index.html
+++ b/electron/launcher/index.html
@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<meta http-equiv="Content-Security-Policy" content="default-src 'self' 'unsafe-inline' data:; connect-src *; img-src 'self' data:" />
+<title>CloudCLI Desktop</title>
+<link rel="stylesheet" href="./launcher.css" />
+</head>
+<body>
+<div id="app"></div>
+<script src="./launcher.js"></script>
+</body>
+</html>
--- a/electron/launcher/launcher.css
+++ b/electron/launcher/launcher.css
@@ -0,0 +1,758 @@
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  height: 100%;
+}
+
+html.cc-modal-window,
+body.cc-modal-window {
+  background: transparent;
+}
+
+:root {
+  --bg: #111315;
+  --s1: #171a1d;
+  --s2: #1e2328;
+  --s3: #262d34;
+  --b-subtle: #28303a;
+  --b: #313b46;
+  --b-strong: #42505f;
+  --tx: #f5f7fa;
+  --tx2: #adb8c5;
+  --tx3: #7f8b98;
+  --brand: #0a66d9;
+  --brand-2: #5fa5ff;
+  --brand-faint: rgba(10, 102, 217, 0.14);
+  --ok: #2aa775;
+  --warn: #d48b20;
+  --err: #d65252;
+  --tab-hover-bg: rgba(255, 255, 255, 0.08);
+  --tab-active-bg: rgba(255, 255, 255, 0.14);
+  --mono: "SF Mono", "Geist Mono", "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, monospace;
+  --sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Inter, sans-serif;
+  color-scheme: dark;
+}
+
+:root[data-theme="light"] {
+  --bg: #f3f5f8;
+  --s1: #ffffff;
+  --s2: #f7f9fb;
+  --s3: #edf1f5;
+  --b-subtle: #e5eaf0;
+  --b: #d8dee6;
+  --b-strong: #c3ccd6;
+  --tx: #11151a;
+  --tx2: #566171;
+  --tx3: #7f8b98;
+  --brand: #0a66d9;
+  --brand-2: #0f5fc6;
+  --brand-faint: rgba(10, 102, 217, 0.09);
+  --ok: #1f8e61;
+  --warn: #b67515;
+  --err: #c24747;
+  --tab-hover-bg: rgba(15, 23, 42, 0.05);
+  --tab-active-bg: rgba(15, 23, 42, 0.08);
+  color-scheme: light;
+}
+
+body {
+  background: var(--bg);
+  color: var(--tx);
+  font-family: var(--sans);
+  font-size: 14px;
+  -webkit-font-smoothing: antialiased;
+  overflow: hidden;
+  user-select: none;
+}
+
+input {
+  font: inherit;
+  user-select: text;
+}
+
+button {
+  font: inherit;
+  color: inherit;
+  cursor: pointer;
+  border: 0;
+  background: none;
+}
+
+#app {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
+::-webkit-scrollbar {
+  width: 10px;
+  height: 10px;
+}
+
+::-webkit-scrollbar-thumb {
+  background: var(--b);
+  border-radius: 6px;
+  border: 2px solid transparent;
+  background-clip: content-box;
+}
+
+svg {
+  display: block;
+}
+
+.mono {
+  font-family: var(--mono);
+}
+
+.lbl {
+  font-family: var(--mono);
+  font-size: 11px;
+  letter-spacing: 1.1px;
+  text-transform: uppercase;
+  color: var(--tx3);
+}
+
+.dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--tx3);
+  flex: 0 0 auto;
+  display: inline-block;
+}
+
+.titlebar {
+  -webkit-app-region: drag;
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  height: 44px;
+  padding: 0 12px;
+  border-bottom: 1px solid var(--b-subtle);
+  background: color-mix(in srgb, var(--s1) 90%, transparent);
+  flex: 0 0 auto;
+}
+
+.titlebar button,
+.titlebar input,
+.titlebar .no-drag {
+  -webkit-app-region: no-drag;
+}
+
+.brand {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-weight: 600;
+}
+
+.brand .mk {
+  width: 22px;
+  height: 22px;
+  display: block;
+  flex: 0 0 auto;
+  object-fit: contain;
+}
+
+.btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 7px;
+  min-width: 0;
+  height: 32px;
+  padding: 0 13px;
+  border-radius: 9px;
+  border: 1px solid var(--b);
+  background: var(--s1);
+  color: var(--tx);
+  font-weight: 500;
+  transition: border-color 0.12s, background 0.12s, filter 0.12s;
+}
+
+.btn:hover {
+  border-color: var(--b-strong);
+  background: var(--s2);
+}
+
+.btn.pri {
+  background: var(--brand);
+  border-color: var(--brand);
+  color: #fff;
+}
+
+.btn.pri:hover {
+  filter: brightness(1.05);
+}
+
+.btn.sm {
+  height: 28px;
+  padding: 0 10px;
+  font-size: 12px;
+}
+
+.btn:disabled {
+  opacity: 0.55;
+  cursor: default;
+}
+
+.icon-btn {
+  width: 32px;
+  height: 32px;
+  display: grid;
+  place-items: center;
+  border-radius: 9px;
+  border: 1px solid transparent;
+  color: var(--tx2);
+}
+
+.icon-btn:hover {
+  background: var(--s2);
+  border-color: var(--b);
+  color: var(--tx);
+}
+
+.badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  min-height: 22px;
+  padding: 0 9px;
+  border-radius: 999px;
+  font-size: 11px;
+  background: var(--s2);
+  color: var(--tx2);
+  border: 1px solid var(--b-subtle);
+  white-space: nowrap;
+}
+
+.badge.ok {
+  color: var(--ok);
+}
+
+.badge.warn {
+  color: var(--warn);
+}
+
+.badge.idle {
+  color: var(--tx3);
+}
+
+.cc-body {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+  position: relative;
+}
+
+.statusbar {
+  flex: 0 0 auto;
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  height: 27px;
+  padding: 0 12px;
+  border-top: 1px solid var(--b-subtle);
+  background: var(--s1);
+  font-size: 11px;
+  color: var(--tx2);
+  font-family: var(--mono);
+}
+
+.statusbar .sep {
+  opacity: 0.4;
+}
+
+.status-msg.progress {
+  color: var(--brand-2);
+}
+
+.status-msg.error {
+  color: var(--err);
+}
+
+.cc-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(6, 8, 11, 0.46);
+  backdrop-filter: blur(16px);
+  display: none;
+  z-index: 50;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+}
+
+.cc-overlay.open {
+  display: flex;
+}
+
+.cc-sheet {
+  width: 620px;
+  max-width: min(92vw, 620px);
+  max-height: 86vh;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  border-radius: 18px;
+  border: 1px solid var(--b);
+  background: color-mix(in srgb, var(--s1) 94%, transparent);
+  box-shadow: 0 32px 80px rgba(0, 0, 0, 0.32);
+}
+
+.cc-sheet-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 20px 20px 18px;
+  border-bottom: 1px solid var(--b-subtle);
+}
+
+.cc-sheet-copy {
+  min-width: 0;
+}
+
+.cc-sheet-title {
+  font-size: 20px;
+  font-weight: 600;
+  line-height: 1.2;
+}
+
+.cc-sheet-subtitle {
+  margin-top: 6px;
+  color: var(--tx2);
+  line-height: 1.45;
+}
+
+.cc-sheet-close {
+  flex: 0 0 auto;
+}
+
+.cc-sheet-body {
+  overflow: auto;
+  padding: 16px 20px 20px;
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.cc-sheet-footer {
+  padding: 14px 20px 18px;
+  border-top: 1px solid var(--b-subtle);
+}
+
+.cc-section {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.cc-section-head {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.cc-section-title {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--tx);
+}
+
+.cc-section-body {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.cc-surface {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  padding: 14px;
+  border: 1px solid var(--b-subtle);
+  border-radius: 14px;
+  background: linear-gradient(180deg, color-mix(in srgb, var(--s2) 86%, transparent), var(--s1));
+}
+
+.cc-row2 {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 8px;
+}
+
+.cc-meta {
+  color: var(--tx2);
+  font-size: 12px;
+  line-height: 1.45;
+}
+
+.cc-toggle,
+.cc-choice {
+  display: grid;
+  grid-template-columns: 18px minmax(0, 1fr);
+  gap: 12px;
+  align-items: start;
+  color: var(--tx2);
+  font-size: 13px;
+  line-height: 1.45;
+}
+
+.cc-toggle input,
+.cc-choice input {
+  width: 16px;
+  height: 16px;
+  margin-top: 2px;
+  accent-color: var(--brand);
+}
+
+.cc-toggle b,
+.cc-choice b {
+  color: var(--tx);
+  font-weight: 600;
+}
+
+.cc-choice-group {
+  gap: 12px;
+}
+
+.cc-kv {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 2px 0;
+  color: var(--tx2);
+}
+
+.cc-kv span:last-child {
+  color: var(--tx);
+  font-weight: 500;
+}
+
+.cc-actions-inline {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  padding-top: 4px;
+}
+
+.cc-status-badge {
+  display: inline-flex;
+  align-items: center;
+  align-self: flex-start;
+  min-height: 28px;
+  padding: 0 10px;
+  border-radius: 999px;
+  border: 1px solid var(--b-subtle);
+  background: var(--s2);
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.cc-status-badge.ok {
+  color: var(--ok);
+}
+
+.cc-status-badge.warn {
+  color: var(--warn);
+}
+
+.cc-status-badge.idle {
+  color: var(--tx3);
+}
+
+.v-sidebar {
+  display: grid;
+  grid-template-columns: 248px 1fr;
+  overflow: hidden;
+}
+
+.sb {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 14px 12px;
+  border-right: 1px solid var(--b-subtle);
+  background: var(--s1);
+  overflow: auto;
+}
+
+.sb-grp {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+}
+
+.sb-grp .lbl {
+  padding: 6px 8px;
+}
+
+.sb-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 8px 10px;
+  border-radius: 10px;
+  color: var(--tx2);
+  text-align: left;
+}
+
+.sb-item > span:nth-child(2) {
+  flex: 1;
+}
+
+.sb-item .sb-meta {
+  font-size: 11px;
+  color: var(--tx3);
+  font-family: var(--mono);
+}
+
+.sb-item:hover {
+  background: var(--s2);
+}
+
+.sb-item.active {
+  background: var(--brand-faint);
+  color: var(--tx);
+}
+
+.sb-item.active svg {
+  color: var(--brand-2);
+}
+
+.sb-main {
+  overflow: auto;
+  padding: 24px;
+  min-width: 0;
+}
+
+.pane-h {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 16px;
+  margin-bottom: 18px;
+}
+
+.pane-title {
+  margin: 0;
+  font-size: 18px;
+  font-weight: 600;
+}
+
+.pane-sub {
+  margin: 4px 0 0;
+  color: var(--tx2);
+  font-size: 13px;
+}
+
+.card {
+  border: 1px solid var(--b);
+  border-radius: 14px;
+  background: color-mix(in srgb, var(--s1) 94%, transparent);
+  padding: 18px;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  max-width: 620px;
+  margin-bottom: 12px;
+  box-shadow: 0 14px 40px rgba(0, 0, 0, 0.08);
+}
+
+.card-head {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.card-tools {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.card-t {
+  font-size: 15px;
+  font-weight: 600;
+}
+
+.card-sub {
+  margin-top: 4px;
+  color: var(--tx2);
+  font-size: 13px;
+  line-height: 1.45;
+}
+
+.card-actions {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.env {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  cursor: pointer;
+  padding: 12px 14px;
+  border: 1px solid var(--b);
+  border-radius: 12px;
+  background: var(--s1);
+  margin-bottom: 8px;
+}
+
+.env:hover {
+  border-color: var(--b-strong);
+}
+
+.env-i {
+  flex: 1;
+  min-width: 0;
+}
+
+.env-n {
+  font-weight: 500;
+}
+
+.env-u {
+  font-size: 12px;
+  color: var(--tx3);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.env-tags {
+  display: flex;
+  gap: 6px;
+}
+
+.tag {
+  font-family: var(--mono);
+  font-size: 11px;
+  color: var(--tx2);
+  background: var(--s2);
+  border: 1px solid var(--b-subtle);
+  border-radius: 999px;
+  padding: 2px 7px;
+  white-space: nowrap;
+}
+
+.empty {
+  border: 1px dashed var(--b);
+  border-radius: 12px;
+  padding: 28px;
+  text-align: center;
+  color: var(--tx2);
+  max-width: 560px;
+}
+
+body.mac .titlebar {
+  padding-left: 92px;
+  padding-right: 12px;
+}
+
+body.win .titlebar {
+  padding-right: 150px;
+}
+
+.titlebar .brand {
+  margin-right: 6px;
+}
+
+.tb-tabs {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  min-width: 0;
+  overflow: hidden;
+}
+
+.tb-tab {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  min-width: 112px;
+  max-width: 232px;
+  flex: 0 0 auto;
+  height: 30px;
+  padding: 0 7px 0 12px;
+  border: 1px solid transparent;
+  border-radius: 8px;
+  color: var(--tx2);
+  font-size: 12px;
+  background: transparent;
+  transition: background 0.12s, color 0.12s;
+}
+
+.tb-tab:hover {
+  background: var(--tab-hover-bg);
+}
+
+.tb-tab.active {
+  background: var(--tab-active-bg);
+  color: var(--tx);
+}
+
+.tb-tab span:first-child {
+  flex: 1;
+  min-width: 0;
+  max-width: 20ch;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.tb-close {
+  display: grid;
+  width: 20px;
+  height: 20px;
+  margin-left: 8px;
+  place-items: center;
+  border-radius: 6px;
+  color: var(--tx3);
+  font-size: 14px;
+  line-height: 1;
+  flex: 0 0 auto;
+}
+
+.tb-close:hover {
+  background: var(--tab-hover-bg);
+  color: var(--tx);
+}
+
+.tb-action {
+  flex: 0 0 auto;
+}
+
+@media (max-width: 760px) {
+  .v-sidebar {
+    grid-template-columns: 1fr;
+  }
+
+  .sb {
+    flex-direction: row;
+    align-items: center;
+    overflow: auto;
+  }
+
+  .env-tags {
+    display: none;
+  }
+
+  .cc-sheet {
+    max-width: 100%;
+  }
+
+  .cc-row2 {
+    grid-template-columns: 1fr;
+  }
+}
--- a/electron/launcher/launcher.js
+++ b/electron/launcher/launcher.js
@@ -0,0 +1,732 @@
+window.__APP_VERSION__ = '1.34.0';
+window.__MOCK_STATE__ = {
+  account: { connected: true, email: 'you@cloudcli.ai' },
+  activeTarget: { kind: 'launcher', name: 'Launcher', url: null },
+  cloudLoading: false,
+  desktopSettings: { keepLocalServerRunning: false, exposeLocalServerOnNetwork: false, themeMode: 'system' },
+  localWebUrl: 'http://localhost:3001',
+  shareableWebUrl: 'http://localhost:3001',
+  localServerRunning: false,
+  localStartupLogs: [],
+  computerUse: { enabled: false, consentMode: 'ask', running: false, connectedCount: 0, targetCount: 0 },
+  environments: [
+    { id: 'env-api', name: 'api-gateway', subdomain: 'api-gateway', access_url: 'https://api-gateway.cloudcli.ai', status: 'running', region: 'fra1', agent: 'Claude Code' },
+    { id: 'env-web', name: 'web-frontend', subdomain: 'web-frontend', access_url: 'https://web-frontend.cloudcli.ai', status: 'stopped', region: 'sfo1', agent: 'Codex' },
+    { id: 'env-data', name: 'data-pipeline', subdomain: 'data-pipeline', access_url: 'https://data-pipeline.cloudcli.ai', status: 'stopped', region: 'fra1', agent: 'Cursor' },
+    { id: 'env-ml', name: 'ml-trainer', subdomain: 'ml-trainer', access_url: 'https://ml-trainer.cloudcli.ai', status: 'paused', region: 'iad1', agent: 'Gemini' },
+  ],
+};
+
+(function cloudCliLauncher() {
+  var MOCK = window.__MOCK_STATE__ || {};
+  var VERSION = window.__APP_VERSION__ || '';
+  var LOGO_URL = new URL('../../public/logo-32.png', window.location.href).toString();
+  var SEARCH = new URLSearchParams(window.location.search || '');
+
+  function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+  }
+
+  var mockState = clone(MOCK);
+  var mockBridge = {
+    getState: function () { return Promise.resolve(clone(mockState)); },
+    openLocal: function () {
+      mockState.localServerRunning = true;
+      mockState.activeTarget = { kind: 'local', name: 'Local CloudCLI', url: mockState.localWebUrl };
+      return Promise.resolve(clone(mockState));
+    },
+    openLocalWebUi: function () {
+      mockState.localServerRunning = true;
+      return Promise.resolve(clone(mockState));
+    },
+    copyLocalWebUrl: function () { return Promise.resolve(clone(mockState)); },
+    connectCloud: function () {
+      mockState.account = { connected: true, email: 'you@cloudcli.ai' };
+      return Promise.resolve(clone(mockState));
+    },
+    refreshEnvironments: function () { return Promise.resolve(clone(mockState)); },
+    copyDiagnostics: function () { return Promise.resolve(clone(mockState)); },
+    showComputerAccess: function () { return Promise.resolve(clone(mockState)); },
+    showEnvironmentPicker: function () { return Promise.resolve(clone(mockState)); },
+    showLauncher: function () { return Promise.resolve(clone(mockState)); },
+    showLocalSettings: function () { return Promise.resolve(clone(mockState)); },
+    showDesktopSettings: function () { return Promise.resolve(clone(mockState)); },
+    closeSettingsWindow: function () { return Promise.resolve(clone(mockState)); },
+    showActiveEnvironmentActionsMenu: function () { return Promise.resolve(clone(mockState)); },
+    openCloudDashboard: function () { return Promise.resolve(clone(mockState)); },
+    runActiveEnvironmentAction: function () { return Promise.resolve(clone(mockState)); },
+    switchTab: function (id) { mockState.activeTabId = id; return Promise.resolve(clone(mockState)); },
+    closeTab: function (id) {
+      mockState.tabs = (mockState.tabs || []).filter(function (tab) { return tab.id === 'home' || tab.id !== id; });
+      if (mockState.activeTabId === id) mockState.activeTabId = 'home';
+      return Promise.resolve(clone(mockState));
+    },
+    updateSetting: function (key, value) {
+      mockState.desktopSettings = mockState.desktopSettings || {};
+      mockState.desktopSettings[key] = key === 'themeMode' ? value : !!value;
+      return Promise.resolve(clone(mockState));
+    },
+    updateComputerUse: function (settings) {
+      mockState.computerUse = mockState.computerUse || { enabled: false, consentMode: 'ask', running: false, connectedCount: 0, targetCount: 0 };
+      if (typeof settings.enabled === 'boolean') mockState.computerUse.enabled = settings.enabled;
+      if (settings.consentMode === 'auto' || settings.consentMode === 'ask') mockState.computerUse.consentMode = settings.consentMode;
+      mockState.computerUse.running = mockState.computerUse.enabled;
+      return Promise.resolve(clone(mockState));
+    },
+    openEnvironment: function (id) {
+      var env = (mockState.environments || []).filter(function (item) { return item.id === id; })[0];
+      if (env) {
+        env.status = 'starting';
+        setTimeout(function () {
+          env.status = 'running';
+          mockState.activeTarget = { kind: 'remote', id: id, name: env.name, url: env.access_url };
+        }, 1700);
+      }
+      return Promise.resolve(clone(mockState));
+    },
+  };
+
+  var bridge = window.cloudcliDesktop || mockBridge;
+
+  var ICONS = {
+    terminal: '<polyline points="4 17 10 11 4 5"/><line x1="12" y1="19" x2="20" y2="19"/>',
+    cloud: '<path d="M17.5 19a4.5 4.5 0 0 0 .5-8.97A6 6 0 0 0 6.34 9 4 4 0 0 0 7 19z"/>',
+    refresh: '<polyline points="23 4 23 10 17 10"/><polyline points="1 20 1 14 7 14"/><path d="M3.51 9a9 9 0 0 1 14.85-3.36L23 10M1 14l4.64 4.36A9 9 0 0 0 20.49 15"/>',
+    settings: '<line x1="4" y1="21" x2="4" y2="14"/><line x1="4" y1="10" x2="4" y2="3"/><line x1="12" y1="21" x2="12" y2="12"/><line x1="12" y1="8" x2="12" y2="3"/><line x1="20" y1="21" x2="20" y2="16"/><line x1="20" y1="12" x2="20" y2="3"/><line x1="1" y1="14" x2="7" y2="14"/><line x1="9" y1="8" x2="15" y2="8"/><line x1="17" y1="16" x2="23" y2="16"/>',
+    gear: '<circle cx="12" cy="12" r="3"/><path d="M19.4 15a1.7 1.7 0 0 0 .34 1.88l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06A1.7 1.7 0 0 0 15 19.4a1.7 1.7 0 0 0-1 .6l-.03.08a2 2 0 1 1-3.94 0L10 20a1.7 1.7 0 0 0-1-.6 1.7 1.7 0 0 0-1.88.34l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06A1.7 1.7 0 0 0 4.6 15a1.7 1.7 0 0 0-.6-1l-.08-.03a2 2 0 1 1 0-3.94L4 10a1.7 1.7 0 0 0 .6-1 1.7 1.7 0 0 0-.34-1.88l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06A1.7 1.7 0 0 0 9 4.6a1.7 1.7 0 0 0 1-.6l.03-.08a2 2 0 1 1 3.94 0L14 4a1.7 1.7 0 0 0 1 .6 1.7 1.7 0 0 0 1.88-.34l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06A1.7 1.7 0 0 0 19.4 9c.2.36.4.7.6 1l.08.03a2 2 0 1 1 0 3.94L20 14a1.7 1.7 0 0 0-.6 1z"/>',
+    play: '<polygon points="6 4 20 12 6 20 6 4"/>',
+    arrow: '<line x1="7" y1="17" x2="17" y2="7"/><polyline points="8 7 17 7 17 16"/>',
+    copy: '<rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/>',
+    cloudPlus: '<path d="M17.5 19a4.5 4.5 0 0 0 .5-8.97A6 6 0 0 0 6.34 9 4 4 0 0 0 7 19z"/><line x1="12" y1="9" x2="12" y2="15"/><line x1="9" y1="12" x2="15" y2="12"/>',
+    monitor: '<rect x="2" y="3" width="20" height="14" rx="2"/><line x1="8" y1="21" x2="16" y2="21"/><line x1="12" y1="17" x2="12" y2="21"/>',
+    phone: '<rect x="7" y="2" width="10" height="20" rx="2"/><line x1="11" y1="18" x2="13" y2="18"/>',
+    x: '<line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/>',
+  };
+  var FILLED = { play: true };
+
+  function icon(name, size) {
+    size = size || 16;
+    return '<svg width="' + size + '" height="' + size + '" viewBox="0 0 24 24" fill="' + (FILLED[name] ? 'currentColor' : 'none') + '" stroke="' + (FILLED[name] ? 'none' : 'currentColor') + '" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">' + (ICONS[name] || '') + '</svg>';
+  }
+
+  function esc(value) {
+    return String(value == null ? '' : value)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;');
+  }
+
+  function statusMeta(status) {
+    var map = {
+      running: { label: 'Running', cls: 'ok', dot: '#10b981', verb: 'Opening', open: 'Open' },
+      starting: { label: 'Starting', cls: 'warn', dot: '#f59e0b', verb: 'Starting', open: 'Open', busy: true },
+      stopped: { label: 'Stopped', cls: 'idle', dot: '#6b7280', verb: 'Starting', open: 'Start & open' },
+      paused: { label: 'Paused', cls: 'warn', dot: '#f59e0b', verb: 'Resuming', open: 'Resume' },
+    };
+    return map[status] || { label: status || 'Unknown', cls: 'idle', dot: '#6b7280', verb: 'Starting', open: 'Start & open' };
+  }
+
+  function connected(state) {
+    return !!(state && state.account && state.account.connected);
+  }
+
+  function authState(state) {
+    return state && state.account ? (state.account.authState || (state.account.connected ? 'connected' : 'logged_out')) : 'logged_out';
+  }
+
+  function accountLabel(state) {
+    if (authState(state) === 'expired') return 'Reconnect';
+    if (state && state.account && state.account.email) return state.account.email;
+    if (connected(state)) return 'Connected';
+    return 'Log in';
+  }
+
+  function localUrl(state) {
+    return (state && (state.shareableWebUrl || state.localWebUrl)) || '';
+  }
+
+  function envCount(state) {
+    var count = state && state.environments ? state.environments.length : 0;
+    return count + ' environment' + (count === 1 ? '' : 's');
+  }
+
+  function errMsg(error) {
+    return error && error.message ? error.message : String(error);
+  }
+
+  function themeLabel(mode) {
+    if (mode === 'light') return 'Light';
+    if (mode === 'dark') return 'Dark';
+    return 'System';
+  }
+
+  function resolveTheme(state) {
+    var settings = state && state.desktopSettings ? state.desktopSettings : {};
+    var mode = settings.themeMode || 'system';
+    if (mode === 'light' || mode === 'dark') return mode;
+    return window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  }
+
+  function computerUseStatus(state) {
+    var computerUse = state && state.computerUse ? state.computerUse : {};
+    if (!computerUse.enabled) {
+      return { label: 'Disabled', tone: 'idle', detail: 'CloudCLI cannot use this computer.' };
+    }
+    if (computerUse.consentMode === 'auto') {
+      return { label: 'Unattended access', tone: 'warn', detail: 'Trusted agents can use this computer without a local approval prompt.' };
+    }
+    return { label: 'Ask before each session', tone: 'ok', detail: 'Agents need approval before control starts.' };
+  }
+
+  var CC = {
+    icon: icon,
+    esc: esc,
+    statusMeta: statusMeta,
+    connected: connected,
+    authState: authState,
+    accountLabel: accountLabel,
+    localUrl: localUrl,
+    envCount: envCount,
+    version: VERSION,
+    logoUrl: LOGO_URL,
+    platform: 'win',
+    state: clone(MOCK),
+    ui: {},
+    _busyEnv: null,
+    _status: { msg: '', tone: '' },
+    _reg: {},
+    _wired: false,
+    _poll: null,
+    modalMode: SEARCH.get('modal') === '1',
+  };
+
+  window.CC = CC;
+
+  var app;
+  var overlay;
+
+  CC.setState = function (state) {
+    var currentSheet = CC.ui.openSheet || (CC.modalMode ? (CC.ui.initialSheet || 'desktop-settings') : null);
+    var sheetBody = overlay ? overlay.querySelector('.cc-sheet-body') : null;
+    var scrollTop = sheetBody ? sheetBody.scrollTop : 0;
+    if (state && typeof state === 'object') CC.state = state;
+    CC.applyTheme(CC.state);
+    CC.render(CC.state);
+    if (currentSheet) {
+      CC.openSheet(currentSheet, { scrollTop: scrollTop });
+    }
+  };
+
+  CC.applyTheme = function (state) {
+    var settings = state && state.desktopSettings ? state.desktopSettings : {};
+    var themeMode = settings.themeMode || 'system';
+    var resolvedTheme = resolveTheme(state);
+    document.documentElement.setAttribute('data-theme', resolvedTheme);
+    document.documentElement.setAttribute('data-theme-mode', themeMode);
+  };
+
+  CC.refresh = function () {
+    return Promise.resolve(bridge.getState()).then(function (state) {
+      CC.setState(state);
+      return state;
+    });
+  };
+
+  CC.run = function (label, fn) {
+    CC._status = { msg: label, tone: 'progress' };
+    CC.render(CC.state);
+    return Promise.resolve()
+      .then(fn)
+      .then(function (state) {
+        if (state && state.environments) CC.state = state;
+        return CC.refresh();
+      })
+      .then(function () {
+        CC._status = { msg: '', tone: '' };
+        CC.render(CC.state);
+      })
+      .catch(function (error) {
+        CC._status = { msg: errMsg(error), tone: 'error' };
+        CC.render(CC.state);
+      });
+  };
+
+  CC.startPolling = function () {
+    if (CC._poll) return;
+    var ticks = 0;
+    CC._poll = setInterval(function () {
+      ticks += 1;
+      Promise.resolve(bridge.getState()).then(function (state) {
+        CC.setState(state);
+        var anyStarting = (state.environments || []).some(function (environment) { return environment.status === 'starting'; });
+        if (!anyStarting || ticks > 16) {
+          clearInterval(CC._poll);
+          CC._poll = null;
+          if (!anyStarting) {
+            CC._status = { msg: '', tone: '' };
+            CC.render(CC.state);
+          }
+        }
+      });
+    }, 1500);
+  };
+
+  CC.openEnv = function (id) {
+    var env = (CC.state.environments || []).filter(function (environment) { return environment.id === id; })[0];
+    var meta = statusMeta(env ? env.status : '');
+    CC._busyEnv = id;
+    CC._status = { msg: (meta.verb || 'Opening') + ' ' + ((env && (env.name || env.subdomain)) || 'environment') + '...', tone: 'progress' };
+    if (env) {
+      var tabId = 'remote:' + env.id;
+      var tabs = CC.state.tabs && CC.state.tabs.length ? CC.state.tabs : [{ id: 'home', title: 'Home', kind: 'launcher', closable: false }];
+      tabs = tabs.map(function (tab) {
+        tab.active = false;
+        return tab;
+      });
+      var existing = tabs.filter(function (tab) { return tab.id === tabId; })[0];
+      if (existing) {
+        existing.active = true;
+        existing.title = env.name || env.subdomain;
+      } else {
+        tabs.push({ id: tabId, title: env.name || env.subdomain, kind: 'remote', closable: true, active: true });
+      }
+      CC.state.tabs = tabs;
+      CC.state.activeTabId = tabId;
+    }
+    if (env && env.status !== 'running') env.status = 'starting';
+    CC.render(CC.state);
+    return Promise.resolve(bridge.openEnvironment(id)).then(function (state) {
+      if (state && state.environments) CC.setState(state);
+      CC.startPolling();
+    }).catch(function (error) {
+      CC._busyEnv = null;
+      if (env) env.status = 'stopped';
+      CC._status = { msg: errMsg(error), tone: 'error' };
+      CC.render(CC.state);
+    });
+  };
+
+  CC.act = function (name, node) {
+    switch (name) {
+      case 'local':
+        return CC.run('Starting Local CloudCLI...', function () { return bridge.openLocal(); });
+      case 'connect':
+        return CC.run('Opening cloudcli.ai to connect your account...', function () { return bridge.connectCloud(); });
+      case 'open-web':
+        return CC.run('Opening local web UI in your browser...', function () { return bridge.openLocalWebUi(); });
+      case 'copy-web':
+        return CC.run('Copied local URL to clipboard', function () { return bridge.copyLocalWebUrl(); });
+      case 'diagnostics':
+        return CC.run('Copied diagnostics to clipboard', function () { return bridge.copyDiagnostics(); });
+      case 'set-setting':
+        return CC.run('Saved', function () { return bridge.updateSetting(node.key, node.value); });
+      case 'set-theme-mode':
+        return CC.run('Saved', function () { return bridge.updateSetting('themeMode', node.value); });
+      case 'set-computer-mode':
+        return CC.run('Saved', function () {
+          return bridge.updateComputerUse({
+            enabled: true,
+            consentMode: node.value,
+          });
+        });
+      case 'set-computer-enabled':
+        return CC.run('Saved', function () {
+          var current = (CC.state && CC.state.computerUse) || { consentMode: 'ask' };
+          return bridge.updateComputerUse({
+            enabled: !!node.value,
+            consentMode: current.consentMode === 'auto' ? 'auto' : 'ask',
+          });
+        });
+      case 'settings-toggle':
+        return CC.run('Opening desktop settings...', function () { return bridge.showDesktopSettings(); });
+      case 'desktop-settings-toggle':
+        return CC.run('Opening desktop settings...', function () { return bridge.showDesktopSettings(); });
+      case 'local-settings-toggle':
+        return CC.run('Opening local settings...', function () { return bridge.showLocalSettings(); });
+      case 'computer-settings-toggle':
+        return CC.run('Opening desktop settings...', function () { return bridge.showDesktopSettings(); });
+      case 'settings-close':
+        return CC.closeSheet();
+      case 'dashboard':
+        return CC.run('Opening CloudCLI dashboard...', function () { return bridge.openCloudDashboard(); });
+      case 'env-action':
+        return CC.run('Opening environment...', function () { return bridge.runActiveEnvironmentAction(node.getAttribute('data-cc-env-action')); });
+      case 'env-menu':
+        return CC.run('Opening environment actions...', function () { return bridge.showActiveEnvironmentActionsMenu(); });
+      case 'env-row-menu':
+        return CC.run('Opening environment actions...', function () { return bridge.showEnvironmentActionsMenu(node.getAttribute('data-cc-environment-id')); });
+      default:
+        return;
+    }
+  };
+
+  function renderTabs(state) {
+    var tabs = state.tabs && state.tabs.length ? state.tabs : [{ id: 'home', title: 'Home', closable: false, active: true }];
+    return tabs.map(function (tab) {
+      var title = tab.title || '';
+      var visibleChars = Math.min(title.length, 20);
+      var tabWidth = Math.max(112, Math.min(232, (visibleChars * 8) + (tab.closable ? 56 : 38)));
+      return '<button class="tb-tab no-drag' + (tab.active ? ' active' : '') + '" data-cc-tab="' + esc(tab.id) + '" title="' + esc(title) + '" style="width:' + tabWidth + 'px;flex-basis:' + tabWidth + 'px">' +
+        '<span>' + esc(title) + '</span>' +
+        (tab.closable ? '<span class="tb-close" data-cc-close-tab="' + esc(tab.id) + '" title="Close tab">&times;</span>' : '') +
+        '</button>';
+    }).join('');
+  }
+
+  CC.titlebar = function (state) {
+    var conn = connected(state);
+    var activeRemote = state.activeTarget && state.activeTarget.kind === 'remote';
+    var envActions = activeRemote ? '<button class="btn sm tb-action no-drag" data-cc-action="env-menu" title="Open environment actions">Open environment in...</button>' : '';
+    return '<div class="titlebar">' +
+      '<div class="brand"><img class="mk" src="' + esc(LOGO_URL) + '" alt=""><span>CloudCLI</span></div>' +
+      '<div class="tb-tabs no-drag">' + renderTabs(state) + '</div>' +
+      '<span style="flex:1"></span>' +
+      envActions +
+      '<button class="btn sm tb-action no-drag" data-cc-action="connect" title="' + esc(authState(state) === 'expired' ? 'Reconnect your CloudCLI account' : accountLabel(state)) + '"><span class="dot" style="background:' + (conn ? 'var(--ok)' : (authState(state) === 'expired' ? 'var(--warn)' : 'var(--tx3)')) + '"></span>' + esc(accountLabel(state)) + '</button>' +
+      '<button class="icon-btn tb-action no-drag" data-cc-action="settings-toggle" title="Settings">' + icon('settings', 16) + '</button>' +
+      '</div>';
+  };
+
+  CC.statusbar = function (state) {
+    var status = CC._status || {};
+    var running = !!state.localServerRunning;
+    return '<div class="statusbar">' +
+      '<span><span class="dot" style="width:7px;height:7px;background:' + (running ? 'var(--ok)' : 'var(--tx3)') + '"></span> local ' + (running ? 'running · ' + esc(localUrl(state)) : 'idle') + '</span>' +
+      '<span class="sep">·</span><span>' + esc(envCount(state)) + '</span>' +
+      '<span class="sep">·</span><span>' + (authState(state) === 'expired' ? 'session expired' : (connected(state) ? esc(accountLabel(state)) : 'not connected')) + '</span>' +
+      '<span style="flex:1"></span>' +
+      (status.msg ? '<span class="status-msg ' + esc(status.tone) + '">' + esc(status.msg) + '</span><span class="sep">·</span>' : '') +
+      '<span>v' + esc(VERSION) + '</span>' +
+      '</div>';
+  };
+
+  CC.renderSheet = function (title, subtitle, sections, footer) {
+    overlay.innerHTML =
+      '<div class="cc-sheet cc-modal">' +
+      '<div class="cc-sheet-header">' +
+      '<div class="cc-sheet-copy"><div class="cc-sheet-title">' + esc(title) + '</div><div class="cc-sheet-subtitle">' + esc(subtitle || '') + '</div></div>' +
+      '<button class="icon-btn cc-sheet-close" data-cc-action="settings-close" title="Close">' + icon('x', 16) + '</button>' +
+      '</div>' +
+      '<div class="cc-sheet-body">' + sections.join('') + '</div>' +
+      (footer ? '<div class="cc-sheet-footer">' + footer + '</div>' : '') +
+      '</div>';
+  };
+
+  CC.renderSection = function (eyebrow, title, body) {
+    return '<section class="cc-section">' +
+      '<div class="cc-section-head">' +
+      '<div class="lbl">' + esc(eyebrow) + '</div>' +
+      '<div class="cc-section-title">' + esc(title) + '</div>' +
+      '</div>' +
+      '<div class="cc-section-body">' + body + '</div>' +
+      '</section>';
+  };
+
+  CC.renderRadioOption = function (name, value, checked, title, description) {
+    return '<label class="cc-choice">' +
+      '<input type="radio" name="' + esc(name) + '" value="' + esc(value) + '"' + (checked ? ' checked' : '') + '>' +
+      '<span><b>' + esc(title) + '</b><br>' + esc(description) + '</span>' +
+      '</label>';
+  };
+
+  CC.openSheet = function (sheet, options) {
+    options = options || {};
+    if (sheet === 'desktop-settings') {
+      CC.renderDesktopSettings();
+    } else {
+      CC.renderLocalSettings();
+    }
+    CC.ui.openSheet = sheet;
+    overlay.classList.add('open');
+    if (typeof options.scrollTop === 'number') {
+      var body = overlay.querySelector('.cc-sheet-body');
+      if (body) body.scrollTop = options.scrollTop;
+    }
+  };
+
+  CC.closeSheet = function () {
+    if (CC.modalMode && bridge.closeSettingsWindow) {
+      CC.ui.openSheet = null;
+      return bridge.closeSettingsWindow();
+    }
+    CC.ui.openSheet = null;
+    overlay.classList.remove('open');
+  };
+
+  CC.buildLocalServerSection = function (state, options) {
+    options = options || {};
+    var settings = state.desktopSettings || {};
+    var url = localUrl(state) || 'starts on demand';
+    var body = '<div class="cc-surface">' +
+      '<div class="cc-meta mono">' + esc(url) + '</div>' +
+      '<div class="cc-row2"><button class="btn sm" data-cc-action="open-web">' + icon('arrow', 14) + 'Open in browser</button><button class="btn sm" data-cc-action="copy-web">' + icon('copy', 14) + 'Copy URL</button></div>';
+    if (options.includePreferences) {
+      body +=
+        '<label class="cc-toggle"><input type="checkbox" data-cc-setting="keepLocalServerRunning"' + (settings.keepLocalServerRunning ? ' checked' : '') + '><span><b>Keep server running</b><br>Leave Local CloudCLI available after you quit the app.</span></label>' +
+        '<label class="cc-toggle"><input type="checkbox" data-cc-setting="exposeLocalServerOnNetwork"' + (settings.exposeLocalServerOnNetwork ? ' checked' : '') + '><span><b>Allow LAN access</b><br>Use the copied URL from another device on this network.</span></label>';
+    }
+    body += '</div>';
+    return CC.renderSection(
+      options.eyebrow || 'LOCAL SERVER',
+      options.title || 'Run Local CloudCLI on this machine',
+      body
+    );
+  };
+
+  CC.buildThemeSection = function (state) {
+    var settings = state.desktopSettings || {};
+    return CC.renderSection('APPEARANCE', 'Desktop theme', '' +
+      '<div class="cc-surface cc-choice-group">' +
+      CC.renderRadioOption('desktop-theme', 'system', settings.themeMode === 'system', 'System', 'Follow the operating system appearance.') +
+      CC.renderRadioOption('desktop-theme', 'light', settings.themeMode === 'light', 'Light', 'Use the light interface appearance.') +
+      CC.renderRadioOption('desktop-theme', 'dark', settings.themeMode === 'dark', 'Dark', 'Use the dark interface appearance.') +
+      '</div>'
+    );
+  };
+
+  CC.buildComputerUseSection = function (state) {
+    var computerUse = state.computerUse || {};
+    var body =
+      '<div class="cc-surface">' +
+      '<label class="cc-toggle"><input type="checkbox" data-cc-computer-enabled="true"' + (computerUse.enabled ? ' checked' : '') + '><span><b>Enable Computer Use</b><br>Let CloudCLI use the computer. Agents cannot act until you approve a session.</span></label>';
+    if (computerUse.enabled) {
+      body += '<div class="cc-choice-group">' +
+        CC.renderRadioOption('computer-access-mode', 'ask', computerUse.consentMode !== 'auto', 'Ask before each session', 'Agents can request control, but you approve every session.') +
+        CC.renderRadioOption('computer-access-mode', 'auto', computerUse.consentMode === 'auto', 'Unattended access', 'Trusted agents can use this computer without a local approval prompt.') +
+        '</div>';
+    }
+    body += '</div>';
+    return CC.renderSection('COMPUTER USE', 'Control how agents can use this computer', body);
+  };
+
+  CC.renderLocalSettings = function () {
+    var state = CC.state || {};
+    var sections = [
+      CC.buildLocalServerSection(state, { includePreferences: false }),
+      CC.renderSection('PREFERENCES', 'How the local service behaves', '' +
+        '<div class="cc-surface">' +
+        '<label class="cc-toggle"><input type="checkbox" data-cc-setting="keepLocalServerRunning"' + ((state.desktopSettings || {}).keepLocalServerRunning ? ' checked' : '') + '><span><b>Keep server running</b><br>Leave Local CloudCLI available after you quit the app.</span></label>' +
+        '<label class="cc-toggle"><input type="checkbox" data-cc-setting="exposeLocalServerOnNetwork"' + ((state.desktopSettings || {}).exposeLocalServerOnNetwork ? ' checked' : '') + '><span><b>Allow LAN access</b><br>Use the copied URL from another device on this network.</span></label>' +
+        '</div>'
+      ),
+    ];
+    CC.renderSheet('Local Settings', 'Manage how Local CloudCLI runs on this computer.', sections);
+  };
+
+  CC.renderDesktopSettings = function () {
+    var state = CC.state || {};
+    var sections = [
+      CC.buildThemeSection(state),
+      CC.buildComputerUseSection(state),
+    ];
+    CC.renderSheet('Desktop Settings', 'Manage the desktop app appearance and Computer Use behavior.', sections);
+  };
+
+  CC.render = function (state) {
+    state = state || CC.state;
+    var titlebar = (CC._reg.titlebar || CC.titlebar)(state);
+    var statusbar = (CC._reg.statusbar || CC.statusbar)(state);
+    var body = CC._reg.renderBody ? CC._reg.renderBody(state) : '';
+    if (CC.modalMode) {
+      app.innerHTML = '';
+    } else {
+      app.innerHTML = titlebar + '<div class="cc-body ' + (CC._reg.bodyClass || '') + '">' + body + '</div>' + statusbar;
+    }
+    if (CC._reg.afterRender) CC._reg.afterRender(state);
+  };
+
+  function wireEvents() {
+    if (CC._wired) return;
+    CC._wired = true;
+
+    document.addEventListener('click', function (event) {
+      if (CC._reg.onClick && CC._reg.onClick(event)) return;
+      var closeTab = event.target.closest('[data-cc-close-tab]');
+      if (closeTab) {
+        event.stopPropagation();
+        CC.run('Closing tab...', function () { return bridge.closeTab(closeTab.getAttribute('data-cc-close-tab')); });
+        return;
+      }
+      var tab = event.target.closest('[data-cc-tab]');
+      if (tab) {
+        CC.run('Switching tab...', function () { return bridge.switchTab(tab.getAttribute('data-cc-tab')); });
+        return;
+      }
+      var action = event.target.closest('[data-cc-action]');
+      if (action) {
+        CC.act(action.getAttribute('data-cc-action'), action);
+        return;
+      }
+      var env = event.target.closest('[data-cc-env]');
+      if (env) {
+        CC.openEnv(env.getAttribute('data-cc-env'));
+        return;
+      }
+      if (overlay.classList.contains('open') && !event.target.closest('.cc-sheet')) {
+        CC.closeSheet();
+      }
+    });
+
+    document.addEventListener('change', function (event) {
+      var setting = event.target.closest('[data-cc-setting]');
+      if (setting) {
+        CC.act('set-setting', {
+          key: setting.getAttribute('data-cc-setting'),
+          value: setting.checked,
+        });
+        return;
+      }
+      var theme = event.target.closest('[name="desktop-theme"]');
+      if (theme) {
+        CC.act('set-theme-mode', { value: theme.value });
+        return;
+      }
+      var computerMode = event.target.closest('[name="computer-access-mode"]');
+      if (computerMode) {
+        CC.act('set-computer-mode', { value: computerMode.value });
+        return;
+      }
+      var computerEnabled = event.target.closest('[data-cc-computer-enabled]');
+      if (computerEnabled) {
+        CC.act('set-computer-enabled', { value: computerEnabled.checked });
+      }
+    });
+
+    document.addEventListener('keydown', function (event) {
+      if (event.key === 'Escape' && overlay.classList.contains('open')) {
+        CC.closeSheet();
+        return;
+      }
+      if ((event.metaKey || event.ctrlKey) && event.key === ',') {
+        event.preventDefault();
+        CC.act('settings-toggle');
+        return;
+      }
+      if (overlay.classList.contains('open')) return;
+      if (CC._reg.onKey) CC._reg.onKey(event, CC.state);
+    });
+  }
+
+  function boot() {
+    app = document.getElementById('app');
+    overlay = document.createElement('div');
+    overlay.id = 'cc-overlay';
+    overlay.className = 'cc-overlay';
+    document.body.appendChild(overlay);
+
+    var isMac = /Mac/i.test(navigator.platform) || /Mac OS X/i.test(navigator.userAgent);
+    var isWin = /Win/i.test(navigator.platform);
+    CC.platform = isMac ? 'mac' : (isWin ? 'win' : 'linux');
+    document.body.classList.add(CC.platform);
+    CC.ui.initialSheet = SEARCH.get('sheet') || 'desktop-settings';
+    if (CC.modalMode) {
+      document.documentElement.classList.add('cc-modal-window');
+      document.body.classList.add('cc-modal-window');
+    }
+
+    wireEvents();
+    if (window.matchMedia) {
+      window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function () {
+        CC.applyTheme(CC.state);
+      });
+    }
+    if (bridge.onStateUpdated) {
+      bridge.onStateUpdated(function (state) { CC.setState(state); });
+    }
+    if (bridge.onLauncherCommand) {
+      bridge.onLauncherCommand(function (command) {
+        if (command && command.type === 'open-sheet') {
+          CC.ui.initialSheet = command.sheet || CC.ui.initialSheet || 'desktop-settings';
+          CC.openSheet(command.sheet);
+        }
+      });
+    }
+    CC.refresh().catch(function (error) {
+      CC._status = { msg: errMsg(error), tone: 'error' };
+      CC.render(CC.state);
+    });
+  }
+
+  CC.register = function (registry) {
+    CC._reg = registry || {};
+  };
+
+  CC.start = function () {
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', boot);
+    } else {
+      boot();
+    }
+  };
+})();
+
+(function sidebarApp() {
+  var CC = window.CC;
+
+  function navItem(id, iconName, label, meta, selected) {
+    return '<button class="sb-item' + (selected === id ? ' active' : '') + '" data-cc-nav="' + id + '">' +
+      CC.icon(iconName, 16) + '<span>' + label + '</span><span class="sb-meta">' + CC.esc(meta) + '</span></button>';
+  }
+
+  function localPane(state) {
+    return '<div class="pane-h"><div><h2 class="pane-title">Local CloudCLI</h2><p class="pane-sub">Run the open-source app on this machine. No account required.</p></div></div>' +
+      '<div class="card"><div class="card-head"><div><div class="card-t">Local server</div><div class="card-sub mono">' + CC.esc(CC.localUrl(state) || 'Starts on demand') + '</div></div><div class="card-tools"><span class="dot" style="background:' + (state.localServerRunning ? 'var(--ok)' : 'var(--tx3)') + '"></span><button class="icon-btn" data-cc-action="local-settings-toggle" title="Local settings">' + CC.icon('gear', 16) + '</button></div></div>' +
+      '<div class="card-actions"><button class="btn pri" data-cc-action="local">' + CC.icon('play', 15) + 'Open Local CloudCLI</button><button class="btn" data-cc-action="open-web">' + CC.icon('arrow', 14) + 'Open in browser</button><button class="btn" data-cc-action="copy-web">' + CC.icon('copy', 14) + 'Copy URL</button></div></div>' +
+      '<div class="card"><div class="card-head"><div><div class="card-t">Computer Use</div><div class="card-sub">' + CC.esc(computerUseStatus(state).detail) + '</div></div><div class="card-tools"><span class="badge ' + CC.esc(computerUseStatus(state).tone) + '">' + CC.esc(computerUseStatus(state).label) + '</span><button class="icon-btn" data-cc-action="computer-settings-toggle" title="Computer Use settings">' + CC.icon('monitor', 16) + '</button></div></div>' +
+      '<div class="card-actions"><button class="btn" data-cc-action="computer-settings-toggle">' + CC.icon('settings', 14) + 'Open settings</button></div></div>';
+  }
+
+  function envRow(environment) {
+    var meta = CC.statusMeta(environment.status);
+    var tags = (environment.agent ? '<span class="tag">' + CC.esc(environment.agent) + '</span>' : '') + (environment.region ? '<span class="tag">' + CC.esc(environment.region) + '</span>' : '');
+    return '<div class="env" data-cc-env="' + environment.id + '"><span class="dot" style="background:' + meta.dot + '"></span>' +
+      '<div class="env-i"><div class="env-n">' + CC.esc(environment.name || environment.subdomain) + '</div><div class="env-u mono">' + CC.esc(environment.access_url || '') + '</div></div>' +
+      '<div class="env-tags">' + tags + '</div>' +
+      '<span class="badge ' + meta.cls + '">' + meta.label + '</span>' +
+      '<button class="btn sm" data-cc-action="env-row-menu" data-cc-environment-id="' + environment.id + '">Open environment in...</button>' +
+      '<button class="btn sm ' + (environment.status === 'running' ? 'pri' : '') + '">' + CC.icon(meta.busy ? 'refresh' : (environment.status === 'running' ? 'arrow' : 'play'), 14) + meta.open + '</button></div>';
+  }
+
+  function cloudPane(state) {
+    var header = '<div class="pane-h"><div><h2 class="pane-title">Environments</h2><p class="pane-sub">' + CC.esc(CC.envCount(state)) + '</p></div><button class="btn sm" data-cc-action="dashboard">' + CC.icon('arrow', 14) + 'Dashboard</button></div>';
+    if (CC.authState(state) === 'expired') {
+      return header + '<div class="empty">Your CloudCLI session expired.<div style="margin-top:14px"><button class="btn pri" data-cc-action="connect">' + CC.icon('cloudPlus', 15) + 'Reconnect account</button></div></div>';
+    }
+    if (!CC.connected(state)) {
+      return header + '<div class="empty">Connect your CloudCLI account to list hosted environments.<div style="margin-top:14px"><button class="btn pri" data-cc-action="connect">' + CC.icon('cloudPlus', 15) + 'Connect account</button></div></div>';
+    }
+    if (state.cloudLoading && !(state.environments || []).length) {
+      return header + '<div class="empty">Loading your CloudCLI environments...</div>';
+    }
+
+    var list = (state.environments || []).map(envRow).join('');
+    if (!list) list = '<div class="empty">No hosted environments yet.</div>';
+    return header + list;
+  }
+
+  function renderBody(state) {
+    var section = CC.ui.section || ((CC.connected(state) || CC.authState(state) === 'expired') ? 'cloud' : 'local');
+    CC.ui.section = section;
+    var nav = '<div class="sb"><div class="sb-grp"><div class="lbl">Workspace</div>' +
+      navItem('local', 'terminal', 'Local', state.localServerRunning ? 'on' : 'idle', section) +
+      navItem('cloud', 'cloud', 'Cloud', (state.environments || []).length, section) +
+      '</div></div>';
+    return nav + '<div class="sb-main">' + (section === 'local' ? localPane(state) : cloudPane(state)) + '</div>';
+  }
+
+  function onClick(event) {
+    var nav = event.target.closest('[data-cc-nav]');
+    if (!nav) return false;
+    CC.ui.section = nav.getAttribute('data-cc-nav');
+    CC.render(CC.state);
+    return true;
+  }
+
+  CC.register({
+    bodyClass: 'v-sidebar',
+    renderBody: renderBody,
+    onClick: onClick,
+  });
+  CC.start();
+})();
--- a/electron/localServer.js
+++ b/electron/localServer.js
@@ -0,0 +1,488 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import http from 'node:http';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+
+const DEFAULT_PORT = 3001;
+const HOST = '127.0.0.1';
+const DISPLAY_HOST = 'localhost';
+const HEALTH_TIMEOUT_MS = 1000;
+const SERVER_START_TIMEOUT_MS = 30000;
+const MAX_STARTUP_LOG_LINES = 300;
+const SERVER_MARKER_PATH = path.join(os.homedir(), '.cloudcli', 'local-server.json');
+const LOCAL_SERVER_URL_ENV_KEYS = [
+  'CLOUDCLI_DESKTOP_LOCAL_SERVER_URL',
+  'CLOUDCLI_LOCAL_SERVER_URL',
+  'ELECTRON_LOCAL_SERVER_URL',
+];
+const LOCAL_SERVER_PORT_ENV_KEYS = [
+  'CLOUDCLI_DESKTOP_LOCAL_SERVER_PORT',
+  'CLOUDCLI_SERVER_PORT',
+  'SERVER_PORT',
+  'PORT',
+];
+
+function requestJson(url, timeoutMs = HEALTH_TIMEOUT_MS) {
+  return new Promise((resolve) => {
+    const req = http.get(url, { timeout: timeoutMs }, (res) => {
+      let body = '';
+
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => {
+        body += chunk;
+      });
+      res.on('end', () => {
+        try {
+          resolve({
+            ok: res.statusCode >= 200 && res.statusCode < 300,
+            json: JSON.parse(body),
+          });
+        } catch {
+          resolve({ ok: false, json: null });
+        }
+      });
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      resolve({ ok: false, json: null });
+    });
+    req.on('error', () => resolve({ ok: false, json: null }));
+  });
+}
+
+async function isCloudCliServer(baseUrl) {
+  const response = await requestJson(`${baseUrl}/health`);
+  return response.ok
+    && response.json?.status === 'ok'
+    && typeof response.json?.installMode === 'string';
+}
+
+function isPortAvailable(port, host = HOST) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+
+    server.once('error', () => resolve(false));
+    server.once('listening', () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port, host);
+  });
+}
+
+function getFreePort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+
+    server.once('error', reject);
+    server.once('listening', () => {
+      const address = server.address();
+      const port = typeof address === 'object' && address ? address.port : DEFAULT_PORT;
+      server.close(() => resolve(port));
+    });
+    server.listen(0, HOST);
+  });
+}
+
+async function chooseServerPort(host) {
+  if (await isPortAvailable(DEFAULT_PORT, host)) {
+    return DEFAULT_PORT;
+  }
+
+  return getFreePort();
+}
+
+function getDesktopPath() {
+  const currentPath = process.env.PATH || '';
+  const commonPaths = process.platform === 'win32'
+    ? []
+    : ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'];
+
+  return [...commonPaths, currentPath].filter(Boolean).join(path.delimiter);
+}
+
+function getNodeRuntime(usePackagedElectronRuntime) {
+  if (process.env.ELECTRON_NODE_PATH) {
+    return { command: process.env.ELECTRON_NODE_PATH, env: {}, label: 'ELECTRON_NODE_PATH' };
+  }
+
+  if (usePackagedElectronRuntime && process.versions.electron) {
+    return {
+      command: process.execPath,
+      env: { ELECTRON_RUN_AS_NODE: '1' },
+      label: `Electron ${process.versions.electron} Node ${process.versions.node}`,
+    };
+  }
+
+  if (process.env.npm_node_execpath) {
+    return { command: process.env.npm_node_execpath, env: {}, label: 'npm_node_execpath' };
+  }
+
+  return { command: 'node', env: {}, label: 'PATH node' };
+}
+
+function stripTrailingSlash(value) {
+  return value.endsWith('/') ? value.slice(0, -1) : value;
+}
+
+function addCandidateUrl(urls, rawUrl) {
+  if (!rawUrl) return;
+  try {
+    const parsed = new URL(String(rawUrl));
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return;
+    parsed.hash = '';
+    parsed.search = '';
+    const normalized = stripTrailingSlash(parsed.toString());
+    if (!urls.includes(normalized)) urls.push(normalized);
+  } catch {
+    // Ignore invalid user-provided discovery values.
+  }
+}
+
+function addCandidatePort(urls, rawPort) {
+  const port = Number.parseInt(String(rawPort || ''), 10);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) return;
+  addCandidateUrl(urls, `http://${HOST}:${port}`);
+}
+
+function getPortFromUrl(baseUrl) {
+  try {
+    const parsed = new URL(baseUrl);
+    if (parsed.port) return Number.parseInt(parsed.port, 10);
+    return parsed.protocol === 'https:' ? 443 : 80;
+  } catch {
+    return null;
+  }
+}
+
+function getDisplayUrl(baseUrl) {
+  try {
+    const parsed = new URL(baseUrl);
+    if (parsed.hostname === HOST) {
+      parsed.hostname = DISPLAY_HOST;
+    }
+    return stripTrailingSlash(parsed.toString());
+  } catch {
+    return baseUrl;
+  }
+}
+
+async function readServerMarkerUrl() {
+  try {
+    const raw = await fs.readFile(SERVER_MARKER_PATH, 'utf8');
+    const marker = JSON.parse(raw);
+    return marker.url || (marker.port ? `http://${marker.host || HOST}:${marker.port}` : null);
+  } catch {
+    return null;
+  }
+}
+
+async function getExistingServerCandidateUrls(defaultUrl) {
+  const urls = [];
+
+  for (const key of LOCAL_SERVER_URL_ENV_KEYS) {
+    addCandidateUrl(urls, process.env[key]);
+  }
+
+  addCandidateUrl(urls, await readServerMarkerUrl());
+
+  for (const key of LOCAL_SERVER_PORT_ENV_KEYS) {
+    addCandidatePort(urls, process.env[key]);
+  }
+
+  addCandidateUrl(urls, defaultUrl);
+  return urls;
+}
+
+async function waitForCloudCliServer(baseUrl, timeoutMs) {
+  const startedAt = Date.now();
+
+  while (Date.now() - startedAt < timeoutMs) {
+    if (await isCloudCliServer(baseUrl)) {
+      return true;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 300));
+  }
+
+  return false;
+}
+
+export class LocalServerController {
+  constructor({ appRoot, settingsPath, isPackaged = false, onChange }) {
+    this.appRoot = appRoot;
+    this.settingsPath = settingsPath;
+    this.isPackaged = isPackaged;
+    this.onChange = onChange;
+    this.localServerUrl = null;
+    this.localServerPort = null;
+    this.ownedServerProcess = null;
+    this.startupLogs = [];
+    this.desktopSettings = {
+      keepLocalServerRunning: false,
+      exposeLocalServerOnNetwork: false,
+      themeMode: 'system',
+    };
+  }
+
+  getSettings() {
+    return this.desktopSettings;
+  }
+
+  getLocalServerUrl() {
+    return this.localServerUrl;
+  }
+
+  getHealthCheckUrl() {
+    if (!this.localServerPort) return this.localServerUrl;
+    return `http://${HOST}:${this.localServerPort}`;
+  }
+
+  appendStartupLog(line) {
+    const text = String(line || '').trimEnd();
+    if (!text) return;
+    const timestamp = new Date().toLocaleTimeString();
+    this.startupLogs.push(`[${timestamp}] ${text}`);
+    if (this.startupLogs.length > MAX_STARTUP_LOG_LINES) {
+      this.startupLogs.splice(0, this.startupLogs.length - MAX_STARTUP_LOG_LINES);
+    }
+    this.onChange?.();
+  }
+
+  getStartupLogs() {
+    return [...this.startupLogs];
+  }
+
+  getPendingTarget() {
+    return {
+      kind: 'local',
+      name: 'Local CloudCLI',
+      url: this.localServerUrl || `http://${DISPLAY_HOST}:${this.localServerPort || DEFAULT_PORT}`,
+    };
+  }
+
+  getLanAddress() {
+    const interfaces = os.networkInterfaces();
+    for (const entries of Object.values(interfaces)) {
+      for (const entry of entries || []) {
+        if (entry.family === 'IPv4' && !entry.internal) {
+          return entry.address;
+        }
+      }
+    }
+    return null;
+  }
+
+  getShareableWebUrl() {
+    if (!this.localServerUrl || !this.localServerPort) return null;
+    if (this.desktopSettings.exposeLocalServerOnNetwork) {
+      const lanAddress = this.getLanAddress();
+      if (lanAddress) {
+        return `http://${lanAddress}:${this.localServerPort}`;
+      }
+    }
+    return this.getLocalServerUrl();
+  }
+
+  getServerBindHost() {
+    return this.desktopSettings.exposeLocalServerOnNetwork ? '0.0.0.0' : HOST;
+  }
+
+  async loadDesktopSettings() {
+    try {
+      const raw = await fs.readFile(this.settingsPath, 'utf8');
+      const stored = JSON.parse(raw);
+      this.desktopSettings = {
+        keepLocalServerRunning: Boolean(stored.keepLocalServerRunning),
+        exposeLocalServerOnNetwork: Boolean(stored.exposeLocalServerOnNetwork),
+        themeMode: stored.themeMode === 'light' || stored.themeMode === 'dark' ? stored.themeMode : 'system',
+      };
+    } catch {
+      this.desktopSettings = {
+        keepLocalServerRunning: false,
+        exposeLocalServerOnNetwork: false,
+        themeMode: 'system',
+      };
+    }
+  }
+
+  async saveDesktopSettings(nextSettings = this.desktopSettings) {
+    this.desktopSettings = {
+      keepLocalServerRunning: Boolean(nextSettings.keepLocalServerRunning),
+      exposeLocalServerOnNetwork: Boolean(nextSettings.exposeLocalServerOnNetwork),
+      themeMode: nextSettings.themeMode === 'light' || nextSettings.themeMode === 'dark' ? nextSettings.themeMode : 'system',
+    };
+    await fs.mkdir(path.dirname(this.settingsPath), { recursive: true });
+    await fs.writeFile(this.settingsPath, JSON.stringify(this.desktopSettings, null, 2), 'utf8');
+    this.onChange?.();
+  }
+
+  async updateDesktopSetting(key, value) {
+    if (!Object.prototype.hasOwnProperty.call(this.desktopSettings, key)) {
+      throw new Error(`Unknown desktop setting: ${key}`);
+    }
+
+    const wasExposeSetting = key === 'exposeLocalServerOnNetwork';
+    const wasLocalRunning = Boolean(this.localServerUrl);
+    const nextValue = key === 'themeMode' ? value : Boolean(value);
+    await this.saveDesktopSettings({ ...this.desktopSettings, [key]: nextValue });
+
+    return {
+      desktopSettings: this.desktopSettings,
+      requiresRestartNotice: wasExposeSetting && wasLocalRunning,
+    };
+  }
+
+  startBundledServer(port) {
+    const serverEntry = process.env.ELECTRON_SERVER_ENTRY
+      || path.join(this.appRoot, 'dist-server', 'server', 'index.js');
+    const bindHost = this.getServerBindHost();
+    const runtime = getNodeRuntime(this.isPackaged);
+
+    const command = `${runtime.command} ${serverEntry}`;
+    this.appendStartupLog(`$ ${command}`);
+    this.appendStartupLog(`runtime: ${runtime.label}`);
+    this.appendStartupLog(`cwd: ${this.appRoot}`);
+    this.appendStartupLog(`HOST=${bindHost} SERVER_PORT=${port} NODE_ENV=production`);
+
+    this.ownedServerProcess = spawn(runtime.command, [serverEntry], {
+      cwd: this.appRoot,
+      detached: true,
+      env: {
+        ...process.env,
+        ...runtime.env,
+        HOST: bindHost,
+        SERVER_PORT: String(port),
+        NODE_ENV: 'production',
+        PATH: getDesktopPath(),
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+
+    this.ownedServerProcess.once('error', (error) => {
+      this.appendStartupLog(`failed to start process: ${error.message}`);
+      this.ownedServerProcess = null;
+    });
+
+    this.ownedServerProcess.stdout?.on('data', (chunk) => {
+      for (const line of String(chunk).split(/\r?\n/)) {
+        this.appendStartupLog(line);
+      }
+    });
+
+    this.ownedServerProcess.stderr?.on('data', (chunk) => {
+      for (const line of String(chunk).split(/\r?\n/)) {
+        this.appendStartupLog(`stderr: ${line}`);
+      }
+    });
+
+    this.ownedServerProcess.once('exit', (code, signal) => {
+      this.appendStartupLog(`process exited with code ${code ?? 'null'} and signal ${signal ?? 'null'}`);
+      if (this.ownedServerProcess) {
+        console.error(`CloudCLI desktop server exited with code ${code ?? 'null'} and signal ${signal ?? 'null'}`);
+      }
+      this.ownedServerProcess = null;
+    });
+  }
+
+  async resolveLocalServerUrl() {
+    const defaultUrl = `http://${HOST}:${DEFAULT_PORT}`;
+    const defaultDisplayUrl = `http://${DISPLAY_HOST}:${DEFAULT_PORT}`;
+    const devUrl = process.env.ELECTRON_DEV_URL;
+    const forceOwnServer = process.env.ELECTRON_FORCE_OWN_SERVER === '1';
+
+    if (devUrl) {
+      const ready = await waitForCloudCliServer(defaultUrl, SERVER_START_TIMEOUT_MS);
+      if (!ready) {
+        throw new Error(`Development backend did not become ready at ${defaultDisplayUrl}`);
+      }
+      this.localServerPort = DEFAULT_PORT;
+      return devUrl;
+    }
+
+    if (!forceOwnServer) {
+      const candidateUrls = await getExistingServerCandidateUrls(defaultUrl);
+      for (const candidateUrl of candidateUrls) {
+        if (await isCloudCliServer(candidateUrl)) {
+          const displayUrl = getDisplayUrl(candidateUrl);
+          this.localServerPort = getPortFromUrl(candidateUrl);
+          this.appendStartupLog(`Using existing Local CloudCLI at ${displayUrl}`);
+          return displayUrl;
+        }
+      }
+    }
+
+    const port = await chooseServerPort(this.getServerBindHost());
+    const serverUrl = `http://${HOST}:${port}`;
+    const displayUrl = `http://${DISPLAY_HOST}:${port}`;
+    this.localServerPort = port;
+    this.startBundledServer(port);
+
+    const ready = await waitForCloudCliServer(serverUrl, SERVER_START_TIMEOUT_MS);
+    if (!ready) {
+      const recentLogs = this.getStartupLogs().slice(-20).join('\n');
+      this.localServerPort = null;
+      throw new Error([
+        `Bundled backend did not become ready at ${displayUrl}.`,
+        recentLogs ? `Recent startup output:\n${recentLogs}` : 'No startup output was captured.',
+      ].join('\n\n'));
+    }
+
+    this.appendStartupLog(`Local CloudCLI ready at ${displayUrl}`);
+    this.localServerUrl = displayUrl;
+    return displayUrl;
+  }
+
+  async ensureLocalServer() {
+    if (!this.localServerUrl) {
+      this.localServerUrl = await this.resolveLocalServerUrl();
+    }
+    return this.localServerUrl;
+  }
+
+  async getResolvedTarget() {
+    await this.ensureLocalServer();
+    return {
+      kind: 'local',
+      name: 'Local CloudCLI',
+      url: this.localServerUrl,
+    };
+  }
+
+  async loadLocalTarget() {
+    return {
+      pendingTarget: this.getPendingTarget(),
+      target: await this.getResolvedTarget(),
+    };
+  }
+
+  hasOwnedServer() {
+    return Boolean(this.ownedServerProcess);
+  }
+
+  detachOwnedServer() {
+    if (!this.ownedServerProcess) return;
+    this.ownedServerProcess.unref();
+    this.ownedServerProcess = null;
+  }
+
+  async shutdownOwnedServer() {
+    if (!this.ownedServerProcess) return;
+
+    const child = this.ownedServerProcess;
+    this.ownedServerProcess = null;
+    child.kill('SIGTERM');
+
+    await new Promise((resolve) => {
+      const timeout = setTimeout(resolve, 3000);
+      child.once('exit', () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+    });
+  }
+}
+
+export { DEFAULT_PORT, HOST };
--- a/electron/main.js
+++ b/electron/main.js
@@ -0,0 +1,843 @@
+import { app, BrowserWindow, clipboard, dialog, ipcMain, shell } from 'electron';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { CloudController } from './cloud.js';
+import { ComputerAgentController } from './computerAgent.js';
+import { DesktopWindowManager } from './desktopWindow.js';
+import { LocalServerController } from './localServer.js';
+import { TabsController } from './tabs.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const APP_NAME = 'CloudCLI';
+const CALLBACK_PROTOCOL = 'cloudcli';
+const CALLBACK_URL = `${CALLBACK_PROTOCOL}://auth/callback`;
+const CLOUDCLI_CONTROL_PLANE_URL = process.env.CLOUDCLI_CONTROL_PLANE_URL || 'https://cloudcli.ai';
+const REMOTE_START_TIMEOUT_MS = 30000;
+
+const tabs = new TabsController();
+
+let activeTarget = { kind: 'launcher', name: APP_NAME, url: null };
+let desktopWindow = null;
+let localServer = null;
+let cloud = null;
+let computerAgent = null;
+let isQuitting = false;
+let isRefreshingCloud = false;
+
+function getAppRoot() {
+  return app.isPackaged ? app.getAppPath() : path.resolve(__dirname, '..');
+}
+
+function getLauncherPath() {
+  return path.join(__dirname, 'launcher', 'index.html');
+}
+
+function getPreloadPath() {
+  return path.join(__dirname, 'preload.cjs');
+}
+
+function getWindowIconPath() {
+  if (process.platform === 'darwin') {
+    return path.join(getAppRoot(), 'electron', 'assets', 'logo-macos.png');
+  }
+  return path.join(getAppRoot(), 'public', 'logo-512.png');
+}
+
+function getStorePath() {
+  return path.join(app.getPath('userData'), 'cloud-account.json');
+}
+
+function getSettingsPath() {
+  return path.join(app.getPath('userData'), 'desktop-settings.json');
+}
+
+function getComputerUseSettingsPath() {
+  return path.join(app.getPath('userData'), 'computer-use-settings.json');
+}
+
+function getRunningEnvironmentUrls() {
+  return cloud.getEnvironments()
+    .filter((environment) => environment.status === 'running')
+    .map((environment) => cloud.getEnvironmentUrl(environment))
+    .filter(Boolean);
+}
+
+async function promptComputerUseConsent(sessionId) {
+  const { response } = await dialog.showMessageBox(desktopWindow?.getMainWindow() || undefined, {
+    type: 'warning',
+    buttons: ['Allow this session', 'Deny'],
+    defaultId: 0,
+    cancelId: 1,
+    title: 'Computer Use request',
+    message: 'An agent wants to control this computer',
+    detail: [
+      'A cloud agent is requesting control of your mouse, keyboard, and screen for this session.',
+      'Approval lasts for this session only. You can stop it any time from the Computer panel.',
+      sessionId ? `\nSession: ${sessionId}` : '',
+    ].join('\n'),
+  });
+  return response === 0;
+}
+
+function getDisplayTargetName() {
+  return activeTarget?.name || APP_NAME;
+}
+
+function getCloudState() {
+  return {
+    account: cloud.getAccount(),
+    environments: cloud.getEnvironments(),
+    controlPlaneUrl: CLOUDCLI_CONTROL_PLANE_URL,
+  };
+}
+
+function getLocalState() {
+  return {
+    desktopSettings: localServer.getSettings(),
+    localServerRunning: Boolean(localServer.getLocalServerUrl()),
+    localWebUrl: localServer.getLocalServerUrl(),
+    shareableWebUrl: localServer.getShareableWebUrl(),
+  };
+}
+
+function serializeEnvironment(environment) {
+  return {
+    id: environment.id,
+    name: environment.name,
+    subdomain: environment.subdomain,
+    access_url: cloud.getEnvironmentUrl(environment),
+    status: environment.status,
+    created_at: environment.created_at,
+    github_url: environment.github_url || null,
+    region: environment.region || null,
+    agent: environment.agent || null,
+  };
+}
+
+function getDesktopState() {
+  const cloudAccount = cloud.getAccount();
+  const localState = getLocalState();
+  const authState = cloud.getAuthState();
+  return {
+    account: {
+      connected: authState === 'connected',
+      email: cloudAccount?.email || null,
+      authState,
+      requiresReconnect: authState === 'expired',
+    },
+    activeTarget,
+    desktopSettings: localState.desktopSettings,
+    localWebUrl: localState.localWebUrl,
+    shareableWebUrl: localState.shareableWebUrl,
+    localServerRunning: localState.localServerRunning,
+    localStartupLogs: localServer.getStartupLogs(),
+    cloudLoading: isRefreshingCloud,
+    tabs: tabs.getSerializableTabs(),
+    activeTabId: tabs.activeTabId,
+    environments: cloud.getEnvironments().map(serializeEnvironment),
+    computerUse: computerAgent?.getState() || { enabled: false, consentMode: 'ask', running: false, connectedCount: 0, targetCount: 0 },
+  };
+}
+
+function isSafeExternalUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return ['https:', 'http:', 'mailto:'].includes(parsed.protocol)
+      || (parsed.protocol === `${CALLBACK_PROTOCOL}:` && parsed.hostname === 'auth');
+  } catch {
+    return false;
+  }
+}
+
+async function openExternalUrl(url) {
+  if (!isSafeExternalUrl(url)) {
+    throw new Error(`Refusing to open unsupported external URL: ${url}`);
+  }
+
+  if (url.startsWith(`${CALLBACK_PROTOCOL}://`)) {
+    await handleDeepLink(url);
+    return;
+  }
+
+  await shell.openExternal(url);
+}
+
+async function showError(title, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`${title}: ${message}`);
+  await dialog.showMessageBox(desktopWindow?.getMainWindow() || undefined, {
+    type: 'error',
+    title,
+    message: title,
+    detail: message,
+  });
+}
+
+function isExpectedNavigationAbort(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return error?.code === 'ERR_ABORTED' || message.includes('ERR_ABORTED') || message.includes('(-3)');
+}
+
+function syncDesktopState() {
+  if (!desktopWindow) return;
+  desktopWindow.buildAppMenu();
+  desktopWindow.emitDesktopState();
+  if (activeTarget?.kind === 'local' && !localServer?.getLocalServerUrl()) {
+    void desktopWindow.showLocalStartupTarget(localServer.getPendingTarget(), localServer.getStartupLogs())
+      .catch((error) => {
+        if (isExpectedNavigationAbort(error)) return;
+        void showError('Could not update local startup log', error);
+      });
+  }
+}
+
+function setActiveTarget(target) {
+  activeTarget = target;
+}
+
+function getEnvironmentTarget(environment) {
+  return {
+    kind: 'remote',
+    id: environment.id,
+    name: environment.name || environment.subdomain,
+    url: cloud.getEnvironmentUrl(environment),
+  };
+}
+
+async function getEnvironmentLaunchTarget(environment) {
+  return {
+    ...getEnvironmentTarget(environment),
+    url: await cloud.getEnvironmentLaunchUrl(environment),
+  };
+}
+
+function getDiagnosticsText() {
+  const cloudAccount = cloud.getAccount();
+  const localState = getLocalState();
+  return JSON.stringify({
+    app: APP_NAME,
+    version: app.getVersion(),
+    electron: process.versions.electron,
+    node: process.versions.node,
+    platform: process.platform,
+    arch: process.arch,
+    appPath: getAppRoot(),
+    userDataPath: app.getPath('userData'),
+    activeTarget,
+    localServerUrl: localState.localWebUrl,
+    localServerPort: localServer.localServerPort,
+    localWebUrl: localState.localWebUrl,
+    shareableWebUrl: localState.shareableWebUrl,
+    desktopSettings: localState.desktopSettings,
+    cloudConnected: Boolean(cloudAccount?.apiKey),
+    cloudEmail: cloudAccount?.email || null,
+    cloudEnvironmentCount: cloud.getEnvironments().length,
+    controlPlaneUrl: CLOUDCLI_CONTROL_PLANE_URL,
+  }, null, 2);
+}
+
+async function copyDiagnostics() {
+  clipboard.writeText(getDiagnosticsText());
+  await dialog.showMessageBox(desktopWindow?.getMainWindow() || undefined, {
+    type: 'info',
+    title: 'Diagnostics copied',
+    message: 'CloudCLI desktop diagnostics were copied to the clipboard.',
+  });
+}
+
+async function showComputerAccess() {
+  await desktopWindow?.showDesktopSettings();
+  return getDesktopState();
+}
+
+async function updateComputerUse(settings) {
+  const current = computerAgent?.getSettings() || { enabled: false, consentMode: 'ask' };
+  const next = {
+    enabled: typeof settings?.enabled === 'boolean' ? settings.enabled : current.enabled,
+    consentMode: settings?.consentMode === 'auto' ? 'auto' : 'ask',
+  };
+  await computerAgent?.saveSettings(next);
+  syncDesktopState();
+  return getDesktopState();
+}
+
+async function refreshCloudEnvironments({ showErrors = false } = {}) {
+  isRefreshingCloud = true;
+  syncDesktopState();
+  try {
+    return await cloud.refreshCloudEnvironments();
+  } catch (error) {
+    const authState = cloud.getAuthState();
+    if (authState === 'expired') {
+      const expiredError = new Error('Your CloudCLI session expired. Reconnect your account.');
+      if (showErrors) {
+        await showError('CloudCLI login required', expiredError);
+        return [];
+      }
+      throw expiredError;
+    }
+    if (showErrors) {
+      await showError('Could not load CloudCLI environments', error);
+      return [];
+    }
+    throw error;
+  } finally {
+    isRefreshingCloud = false;
+    // Reconcile the Computer Use desktop agent with the latest running environments.
+    void computerAgent?.sync().catch((error) => console.error('[ComputerAgent] sync failed:', error?.message || error));
+    syncDesktopState();
+  }
+}
+
+async function connectCloudAccount() {
+  const connectUrl = cloud.buildConnectUrl();
+  clipboard.writeText(connectUrl);
+  await openExternalUrl(connectUrl);
+  return connectUrl;
+}
+
+async function handleDeepLink(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return;
+  }
+
+  if (parsed.protocol !== `${CALLBACK_PROTOCOL}:` || parsed.hostname !== 'auth') {
+    return;
+  }
+
+  const apiKey = parsed.searchParams.get('api_key');
+  if (!apiKey) {
+    await showError('CloudCLI account connection failed', new Error('The callback did not include an API key.'));
+    return;
+  }
+
+  await cloud.saveFromCallback({
+    apiKey,
+    email: parsed.searchParams.get('email'),
+  });
+  await refreshCloudEnvironments({ showErrors: true });
+
+  dialog.showMessageBox(desktopWindow?.getMainWindow() || undefined, {
+    type: 'info',
+    title: 'CloudCLI account connected',
+    message: cloud.getAccount()?.email ? `Connected as ${cloud.getAccount().email}.` : 'CloudCLI account connected.',
+  }).catch(() => {});
+}
+
+async function copyLocalWebUrl() {
+  await localServer.ensureLocalServer();
+  const shareableUrl = localServer.getShareableWebUrl();
+  const localUrl = localServer.getLocalServerUrl();
+
+  if (!shareableUrl) {
+    throw new Error('Local CloudCLI URL is not available yet.');
+  }
+
+  clipboard.writeText(shareableUrl);
+  const isLanUrl = shareableUrl !== localUrl;
+  await dialog.showMessageBox(desktopWindow?.getMainWindow() || undefined, {
+    type: 'info',
+    title: 'Web URL copied',
+    message: isLanUrl ? 'LAN web URL copied.' : 'Local web URL copied.',
+    detail: isLanUrl
+      ? `${shareableUrl}\n\nUse this URL from another device on the same network.`
+      : `${shareableUrl}\n\nThis URL works on this computer. Enable LAN access before starting Local CloudCLI to copy a phone-accessible URL.`,
+  });
+
+  return getDesktopState();
+}
+
+async function openLocalWebUi() {
+  await localServer.ensureLocalServer();
+  const url = localServer.getShareableWebUrl() || localServer.getLocalServerUrl();
+  if (!url) {
+    throw new Error('Local CloudCLI URL is not available yet.');
+  }
+
+  await shell.openExternal(url);
+  return getDesktopState();
+}
+
+async function updateDesktopSetting(key, value) {
+  const result = await localServer.updateDesktopSetting(key, value);
+  syncDesktopState();
+
+  if (result.requiresRestartNotice) {
+    await dialog.showMessageBox(desktopWindow?.getMainWindow() || undefined, {
+      type: 'info',
+      title: 'Restart local server to apply',
+      message: 'LAN access changes apply the next time the local server starts.',
+      detail: 'Quit CloudCLI and stop the local server, then open Local CloudCLI again.',
+    });
+  }
+
+  return getDesktopState();
+}
+
+async function showEnvironmentPicker() {
+  const environments = await refreshCloudEnvironments({ showErrors: true });
+  const choices = ['Local CloudCLI', ...environments.map((environment) => {
+    const status = environment.status === 'running' ? '' : ` (${environment.status})`;
+    return `${environment.name || environment.subdomain}${status}`;
+  })];
+
+  const response = await dialog.showMessageBox(desktopWindow?.getMainWindow(), {
+    type: 'question',
+    buttons: [...choices, 'Cancel'],
+    defaultId: 0,
+    cancelId: choices.length,
+    title: 'Switch CloudCLI Environment',
+    message: 'Choose where this desktop window should connect.',
+  });
+
+  if (response.response === choices.length) return getDesktopState();
+  if (response.response === 0) return openLocalInDesktop();
+  return openEnvironmentInDesktop(environments[response.response - 1]);
+}
+
+async function startEnvironment(environment) {
+  await cloud.startEnvironmentAndWait(environment, REMOTE_START_TIMEOUT_MS);
+  await refreshCloudEnvironments({ showErrors: true });
+  return getDesktopState();
+}
+
+async function stopEnvironment(environment) {
+  await cloud.stopEnvironment(environment);
+  await refreshCloudEnvironments({ showErrors: true });
+  return getDesktopState();
+}
+
+async function openEnvironmentInBrowser(environment) {
+  await shell.openExternal(await cloud.getEnvironmentLaunchUrl(environment));
+  return getDesktopState();
+}
+
+function getProjectFolder(environment) {
+  return String(environment.name || environment.subdomain || 'workspace').replace(/[^a-zA-Z0-9-]/g, '');
+}
+
+function getSshTarget(credentials) {
+  if (credentials.ssh_command) {
+    const parts = String(credentials.ssh_command).split(/\s+/);
+    if (parts.length >= 2) return parts[1];
+  }
+  return `${credentials.username}@ssh.cloudcli.ai`;
+}
+
+function getSshHost(credentials) {
+  const target = getSshTarget(credentials);
+  const atIndex = target.indexOf('@');
+  return atIndex >= 0 ? target.slice(atIndex + 1) : 'ssh.cloudcli.ai';
+}
+
+async function getEnvironmentCredentials(environment) {
+  const credentials = await cloud.getEnvironmentCredentials(environment);
+  if (credentials.password) {
+    clipboard.writeText(credentials.password);
+  }
+  return credentials;
+}
+
+async function openEnvironmentInIde(environment, ide) {
+  const credentials = await getEnvironmentCredentials(environment);
+  const scheme = ide === 'cursor' ? 'cursor' : 'vscode';
+  const remoteUri = `${scheme}://vscode-remote/ssh-remote+${credentials.username}@${getSshHost(credentials)}/workspace/${getProjectFolder(environment)}?windowId=_blank`;
+  await shell.openExternal(remoteUri);
+  return getDesktopState();
+}
+
+async function openEnvironmentInSsh(environment) {
+  const credentials = await getEnvironmentCredentials(environment);
+  const sshCommand = `ssh -t ${getSshTarget(credentials)} "cd /workspace/${getProjectFolder(environment)} && exec $SHELL -l"`;
+
+  if (process.platform === 'darwin') {
+    const escaped = sshCommand.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    spawn('osascript', ['-e', `tell application "Terminal" to do script "${escaped}"`], {
+      detached: true,
+      stdio: 'ignore',
+    }).unref();
+  } else {
+    clipboard.writeText(sshCommand);
+    await dialog.showMessageBox(desktopWindow?.getMainWindow() || undefined, {
+      type: 'info',
+      title: 'SSH command copied',
+      message: 'The SSH command was copied to the clipboard.',
+      detail: sshCommand,
+    });
+  }
+
+  return getDesktopState();
+}
+
+async function copyEnvironmentMobileUrl(environment) {
+  const url = cloud.getEnvironmentUrl(environment);
+  clipboard.writeText(url);
+  await dialog.showMessageBox(desktopWindow?.getMainWindow() || undefined, {
+    type: 'info',
+    title: 'Environment URL copied',
+    message: 'Use this URL from your mobile browser.',
+    detail: url,
+  });
+  return getDesktopState();
+}
+
+async function openCloudDashboard() {
+  await shell.openExternal(CLOUDCLI_CONTROL_PLANE_URL);
+  return getDesktopState();
+}
+
+function getActiveRemoteEnvironment() {
+  if (activeTarget?.kind !== 'remote') return null;
+  return cloud.findEnvironment(activeTarget.id);
+}
+
+async function runActiveEnvironmentAction(action) {
+  const environment = getActiveRemoteEnvironment();
+  if (!environment) {
+    throw new Error('Open a cloud environment first.');
+  }
+
+  switch (action) {
+    case 'web':
+      return openEnvironmentInBrowser(environment);
+    case 'vscode':
+      return openEnvironmentInIde(environment, 'vscode');
+    case 'cursor':
+      return openEnvironmentInIde(environment, 'cursor');
+    case 'ssh':
+      return openEnvironmentInSsh(environment);
+    case 'mobile':
+      return copyEnvironmentMobileUrl(environment);
+    default:
+      throw new Error(`Unknown environment action: ${action}`);
+  }
+}
+
+async function openLocalInDesktop() {
+  const existingTab = tabs.getTab('local');
+  if (existingTab && localServer.getLocalServerUrl()) {
+    await desktopWindow.showTarget(await localServer.getResolvedTarget());
+    return getDesktopState();
+  }
+
+  const pendingTarget = localServer.getPendingTarget();
+  tabs.upsertTarget(pendingTarget);
+  setActiveTarget(pendingTarget);
+  await desktopWindow.showLocalStartupTarget(pendingTarget, localServer.getStartupLogs());
+  desktopWindow.emitDesktopState();
+
+  const target = await localServer.getResolvedTarget();
+  await desktopWindow.showTarget(target);
+  return getDesktopState();
+}
+
+async function openEnvironmentInDesktop(environment) {
+  const pendingTarget = getEnvironmentTarget(environment);
+  const tabId = tabs.getTabIdForTarget(pendingTarget);
+  const hadTab = Boolean(tabs.getTab(tabId));
+  const previousTabId = tabs.activeTabId;
+
+  if (!hadTab) {
+    await desktopWindow.showTabPlaceholder(
+      pendingTarget,
+      `${environment.status === 'running' ? 'Opening' : 'Starting'} ${pendingTarget.name}...`,
+    );
+    tabs.upsertTarget(pendingTarget);
+    desktopWindow.emitDesktopState();
+  }
+
+  let nextEnvironment = environment;
+
+  if (environment.status !== 'running') {
+    const response = await dialog.showMessageBox(desktopWindow?.getMainWindow(), {
+      type: 'question',
+      buttons: ['Start Environment', 'Cancel'],
+      defaultId: 0,
+      cancelId: 1,
+      title: 'Start environment?',
+      message: `${pendingTarget.name} is ${environment.status}.`,
+      detail: 'CloudCLI can start it before opening the remote app.',
+    });
+
+    if (response.response !== 0) {
+      if (!hadTab) {
+        tabs.remove(tabId);
+        desktopWindow.destroyTabView(tabId);
+        if (previousTabId && previousTabId !== tabId) {
+          await desktopWindow.switchDesktopTab(previousTabId);
+        } else {
+          await desktopWindow.showLauncher();
+        }
+      }
+      return getDesktopState();
+    }
+
+    if (hadTab) {
+      await desktopWindow.showTabPlaceholder(pendingTarget, `Starting ${pendingTarget.name}...`);
+      tabs.upsertTarget(pendingTarget);
+      desktopWindow.emitDesktopState();
+    }
+
+    nextEnvironment = await cloud.startEnvironmentAndWait(environment, REMOTE_START_TIMEOUT_MS);
+  }
+
+  const target = await getEnvironmentLaunchTarget(nextEnvironment);
+  await desktopWindow.showTarget(target);
+  return getDesktopState();
+}
+
+async function clearCloudAccount() {
+  await cloud.clearCloudAccount();
+  return getDesktopState();
+}
+
+function getRemoteEnvironmentMenuItems() {
+  const cloudAccount = cloud.getAccount();
+  const environments = cloud.getEnvironments();
+
+  if (!cloudAccount?.apiKey) {
+    return [{ label: 'Connect CloudCLI Account...', click: () => void connectCloudAccount() }];
+  }
+
+  if (!environments.length) {
+    return [{ label: 'No environments found', enabled: false }];
+  }
+
+  return environments.map((environment) => ({
+    label: `${environment.name || environment.subdomain}${environment.status === 'running' ? '' : ` (${environment.status})`}`,
+    click: () => void openEnvironmentInDesktop(environment)
+      .catch((error) => showError('Could not open environment', error)),
+  }));
+}
+
+function registerProtocolHandler() {
+  const appEntry = path.join(getAppRoot(), 'electron', 'main.js');
+  if (process.defaultApp && process.argv.length >= 2) {
+    app.setAsDefaultProtocolClient(CALLBACK_PROTOCOL, process.execPath, [appEntry]);
+  } else {
+    app.setAsDefaultProtocolClient(CALLBACK_PROTOCOL);
+  }
+}
+
+function registerIpcHandlers() {
+  ipcMain.handle('cloudcli-desktop:connect-cloud', async () => ({
+    ...getDesktopState(),
+    connectUrl: await connectCloudAccount(),
+  }));
+
+  ipcMain.handle('cloudcli-desktop:copy-diagnostics', async () => {
+    await copyDiagnostics();
+    return getDesktopState();
+  });
+
+  ipcMain.handle('cloudcli-desktop:copy-local-web-url', async () => copyLocalWebUrl());
+  ipcMain.handle('cloudcli-desktop:get-state', () => getDesktopState());
+  ipcMain.handle('cloudcli-desktop:open-cloud-dashboard', async () => openCloudDashboard());
+  ipcMain.handle('cloudcli-desktop:run-active-environment-action', async (_event, action) => runActiveEnvironmentAction(action));
+  ipcMain.handle('cloudcli-desktop:open-environment', async (_event, environmentId) => {
+    const environment = cloud.findEnvironment(environmentId);
+    if (!environment) {
+      throw new Error('Environment not found. Refresh and try again.');
+    }
+    return openEnvironmentInDesktop(environment);
+  });
+  ipcMain.handle('cloudcli-desktop:open-local', async () => openLocalInDesktop());
+  ipcMain.handle('cloudcli-desktop:open-local-web-ui', async () => openLocalWebUi());
+  ipcMain.handle('cloudcli-desktop:refresh-environments', async () => {
+    await refreshCloudEnvironments({ showErrors: true });
+    return getDesktopState();
+  });
+  ipcMain.handle('cloudcli-desktop:show-environment-picker', async () => showEnvironmentPicker());
+  ipcMain.handle('cloudcli-desktop:show-launcher', async () => {
+    await desktopWindow.showLauncher();
+    return getDesktopState();
+  });
+  ipcMain.handle('cloudcli-desktop:show-computer-access', async () => {
+    await showComputerAccess();
+    return getDesktopState();
+  });
+  ipcMain.handle('cloudcli-desktop:update-computer-use', async (_event, settings) => updateComputerUse(settings));
+  ipcMain.handle('cloudcli-desktop:show-desktop-settings', async () => desktopWindow.showDesktopSettings());
+  ipcMain.handle('cloudcli-desktop:show-local-settings', async () => desktopWindow.showLocalSettings());
+  ipcMain.handle('cloudcli-desktop:close-settings-window', async () => {
+    desktopWindow.closeSettingsWindow();
+    return getDesktopState();
+  });
+  ipcMain.handle('cloudcli-desktop:show-active-environment-actions-menu', async () => desktopWindow.showActiveEnvironmentActionsMenu());
+  ipcMain.handle('cloudcli-desktop:show-environment-actions-menu', async (_event, environmentId) => desktopWindow.showEnvironmentActionsMenu(environmentId));
+  ipcMain.handle('cloudcli-desktop:switch-tab', async (_event, tabId) => desktopWindow.switchDesktopTab(tabId));
+  ipcMain.handle('cloudcli-desktop:close-tab', async (_event, tabId) => desktopWindow.closeDesktopTab(tabId));
+  ipcMain.handle('cloudcli-desktop:update-setting', async (_event, key, value) => updateDesktopSetting(key, value));
+}
+
+function registerAppEvents() {
+  app.on('open-url', (event, url) => {
+    event.preventDefault();
+    void handleDeepLink(url);
+  });
+
+  app.on('activate', () => {
+    if (BrowserWindow.getAllWindows().length === 0) {
+      if (desktopWindow) {
+        void desktopWindow.createWindow();
+      } else {
+        void createDesktopWindow();
+      }
+      return;
+    }
+
+    const window = desktopWindow?.getMainWindow();
+    if (window) {
+      window.show();
+      window.focus();
+    }
+  });
+
+  app.on('before-quit', () => {
+    computerAgent?.stop();
+  });
+
+  app.on('before-quit', (event) => {
+    if (isQuitting || !localServer?.hasOwnedServer()) return;
+    if (localServer.getSettings().keepLocalServerRunning) {
+      localServer.detachOwnedServer();
+      return;
+    }
+
+    event.preventDefault();
+    isQuitting = true;
+    void localServer.shutdownOwnedServer().finally(() => app.quit());
+  });
+
+  app.on('window-all-closed', () => {
+    if (process.platform !== 'darwin') {
+      app.quit();
+    }
+  });
+}
+
+async function createDesktopWindow() {
+  desktopWindow = new DesktopWindowManager({
+    appName: APP_NAME,
+    getWindowIconPath,
+    getLauncherPath,
+    getPreloadPath,
+    openExternalUrl,
+    getDesktopState,
+    getDisplayTargetName,
+    getRemoteEnvironmentMenuItems,
+    getCloudState,
+    getLocalState,
+    tabs,
+    actions: {
+      copyDiagnostics,
+      copyText: (text) => clipboard.writeText(text),
+      clearCloudAccount,
+      connectCloudAccount,
+      getActiveTarget: () => activeTarget,
+      getEnvironmentUrl: (environment) => cloud.getEnvironmentUrl(environment),
+      openEnvironmentInBrowser,
+      openEnvironmentInDesktop,
+      openEnvironmentInIde,
+      openEnvironmentInSsh,
+      openLocalInDesktop,
+      openLocalWebUi,
+      openCloudDashboard,
+      refreshCloudEnvironments: () => refreshCloudEnvironments({ showErrors: true }),
+      setActiveTarget,
+      showComputerAccess,
+      showEnvironmentPicker,
+      showError,
+      startEnvironment,
+      stopEnvironment,
+      updateDesktopSetting,
+      copyLocalWebUrl,
+    },
+  });
+
+  desktopWindow.createTray();
+  desktopWindow.configurePermissions();
+  await desktopWindow.createWindow();
+}
+
+function registerSingleInstance() {
+  const gotSingleInstanceLock = app.requestSingleInstanceLock();
+  if (!gotSingleInstanceLock) {
+    app.quit();
+    return false;
+  }
+
+  app.on('second-instance', (_event, argv) => {
+    const deepLink = argv.find((arg) => arg.startsWith(`${CALLBACK_PROTOCOL}://`));
+    if (deepLink) {
+      void handleDeepLink(deepLink);
+    }
+
+    const window = desktopWindow?.getMainWindow();
+    if (window) {
+      if (window.isMinimized()) window.restore();
+      window.show();
+      window.focus();
+    }
+  });
+
+  return true;
+}
+
+async function bootstrap() {
+  app.name = APP_NAME;
+  app.setName(APP_NAME);
+  process.title = APP_NAME;
+
+  await app.whenReady();
+  app.setName(APP_NAME);
+  app.setAboutPanelOptions({
+    applicationName: APP_NAME,
+    applicationVersion: app.getVersion(),
+    copyright: 'CloudCLI',
+  });
+
+  localServer = new LocalServerController({
+    appRoot: getAppRoot(),
+    settingsPath: getSettingsPath(),
+    isPackaged: app.isPackaged,
+    onChange: syncDesktopState,
+  });
+  cloud = new CloudController({
+    storePath: getStorePath(),
+    controlPlaneUrl: CLOUDCLI_CONTROL_PLANE_URL,
+    callbackUrl: CALLBACK_URL,
+    onChange: syncDesktopState,
+  });
+  computerAgent = new ComputerAgentController({
+    appRoot: getAppRoot(),
+    settingsPath: getComputerUseSettingsPath(),
+    isPackaged: app.isPackaged,
+    getRunningEnvironmentUrls,
+    promptConsent: promptComputerUseConsent,
+    onChange: syncDesktopState,
+  });
+
+  await localServer.loadDesktopSettings();
+  await cloud.loadCloudAccount();
+  await computerAgent.loadSettings();
+
+  registerProtocolHandler();
+  registerIpcHandlers();
+  registerAppEvents();
+  await createDesktopWindow();
+  void refreshCloudEnvironments({ showErrors: false });
+}
+
+if (registerSingleInstance()) {
+  bootstrap().catch(async (error) => {
+    await showError('CloudCLI failed to start', error);
+    app.quit();
+  });
+}
--- a/electron/preload.cjs
+++ b/electron/preload.cjs
@@ -0,0 +1,34 @@
+const { contextBridge, ipcRenderer } = require('electron');
+
+if (window.location.protocol === 'file:') {
+  contextBridge.exposeInMainWorld('cloudcliDesktop', {
+    connectCloud: () => ipcRenderer.invoke('cloudcli-desktop:connect-cloud'),
+    copyDiagnostics: () => ipcRenderer.invoke('cloudcli-desktop:copy-diagnostics'),
+    copyLocalWebUrl: () => ipcRenderer.invoke('cloudcli-desktop:copy-local-web-url'),
+    getState: () => ipcRenderer.invoke('cloudcli-desktop:get-state'),
+    openCloudDashboard: () => ipcRenderer.invoke('cloudcli-desktop:open-cloud-dashboard'),
+    openEnvironment: (environmentId) => ipcRenderer.invoke('cloudcli-desktop:open-environment', environmentId),
+    runActiveEnvironmentAction: (action) => ipcRenderer.invoke('cloudcli-desktop:run-active-environment-action', action),
+    openLocal: () => ipcRenderer.invoke('cloudcli-desktop:open-local'),
+    openLocalWebUi: () => ipcRenderer.invoke('cloudcli-desktop:open-local-web-ui'),
+    refreshEnvironments: () => ipcRenderer.invoke('cloudcli-desktop:refresh-environments'),
+    showEnvironmentPicker: () => ipcRenderer.invoke('cloudcli-desktop:show-environment-picker'),
+    showLauncher: () => ipcRenderer.invoke('cloudcli-desktop:show-launcher'),
+    showComputerAccess: () => ipcRenderer.invoke('cloudcli-desktop:show-computer-access'),
+    showLocalSettings: () => ipcRenderer.invoke('cloudcli-desktop:show-local-settings'),
+    updateComputerUse: (settings) => ipcRenderer.invoke('cloudcli-desktop:update-computer-use', settings),
+    showDesktopSettings: () => ipcRenderer.invoke('cloudcli-desktop:show-desktop-settings'),
+    closeSettingsWindow: () => ipcRenderer.invoke('cloudcli-desktop:close-settings-window'),
+    showActiveEnvironmentActionsMenu: () => ipcRenderer.invoke('cloudcli-desktop:show-active-environment-actions-menu'),
+    showEnvironmentActionsMenu: (environmentId) => ipcRenderer.invoke('cloudcli-desktop:show-environment-actions-menu', environmentId),
+    switchTab: (tabId) => ipcRenderer.invoke('cloudcli-desktop:switch-tab', tabId),
+    closeTab: (tabId) => ipcRenderer.invoke('cloudcli-desktop:close-tab', tabId),
+    updateSetting: (key, value) => ipcRenderer.invoke('cloudcli-desktop:update-setting', key, value),
+    onStateUpdated: (callback) => {
+      ipcRenderer.on('cloudcli-desktop:state-updated', (_event, state) => callback(state));
+    },
+    onLauncherCommand: (callback) => {
+      ipcRenderer.on('cloudcli-desktop:launcher-command', (_event, command) => callback(command));
+    },
+  });
+}
--- a/electron/scripts/generate-macos-icon.js
+++ b/electron/scripts/generate-macos-icon.js
@@ -0,0 +1,62 @@
+import fs from 'node:fs/promises';
+import sharp from 'sharp';
+
+const size = 1024;
+const assetsDir = 'electron/assets';
+const iconPath = 'electron/assets/logo-macos.png';
+const icnsPath = 'electron/assets/logo-macos.icns';
+
+function renderSvg(entrySize) {
+  const scale = entrySize / 32;
+  return `
+<svg xmlns="http://www.w3.org/2000/svg" width="${entrySize}" height="${entrySize}" viewBox="0 0 ${entrySize} ${entrySize}">
+  <rect width="${entrySize}" height="${entrySize}" fill="#2563eb"/>
+  <path
+    d="M${8 * scale} ${9 * scale}C${8 * scale} ${8.44772 * scale} ${8.44772 * scale} ${8 * scale} ${9 * scale} ${8 * scale}H${23 * scale}C${23.5523 * scale} ${8 * scale} ${24 * scale} ${8.44772 * scale} ${24 * scale} ${9 * scale}V${18 * scale}C${24 * scale} ${18.5523 * scale} ${23.5523 * scale} ${19 * scale} ${23 * scale} ${19 * scale}H${12 * scale}L${8 * scale} ${23 * scale}V${9 * scale}Z"
+    stroke="white"
+    stroke-width="${2 * scale}"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    fill="none"
+  />
+</svg>`;
+}
+
+async function renderPng(entrySize) {
+  return sharp(Buffer.from(renderSvg(entrySize)))
+    .png()
+    .toBuffer();
+}
+
+await fs.mkdir(assetsDir, { recursive: true });
+await fs.writeFile(iconPath, await renderPng(size));
+
+const icnsEntries = [
+  ['icp4', 16],
+  ['icp5', 32],
+  ['icp6', 64],
+  ['ic07', 128],
+  ['ic08', 256],
+  ['ic09', 512],
+  ['ic10', 1024],
+  ['ic11', 32],
+  ['ic12', 64],
+  ['ic13', 256],
+  ['ic14', 512],
+];
+
+const blocks = await Promise.all(icnsEntries.map(async ([type, entrySize]) => {
+  const png = await renderPng(entrySize);
+  const block = Buffer.alloc(8 + png.length);
+  block.write(type, 0, 4, 'ascii');
+  block.writeUInt32BE(block.length, 4);
+  png.copy(block, 8);
+  return block;
+}));
+
+const totalLength = 8 + blocks.reduce((sum, block) => sum + block.length, 0);
+const header = Buffer.alloc(8);
+header.write('icns', 0, 4, 'ascii');
+header.writeUInt32BE(totalLength, 4);
+
+await fs.writeFile(icnsPath, Buffer.concat([header, ...blocks], totalLength));
--- a/electron/tabs.js
+++ b/electron/tabs.js
@@ -0,0 +1,71 @@
+export class TabsController {
+  constructor() {
+    this.activeTabId = 'home';
+    this.tabs = [
+      {
+        id: 'home',
+        title: 'Home',
+        kind: 'launcher',
+        closable: false,
+      },
+    ];
+  }
+
+  getTabIdForTarget(target) {
+    if (target.kind === 'launcher') return 'home';
+    if (target.kind === 'remote' && target.id) return `remote:${target.id}`;
+    return target.kind;
+  }
+
+  upsertTarget(target) {
+    const tabId = this.getTabIdForTarget(target);
+    const existingTab = this.tabs.find((tab) => tab.id === tabId);
+    const nextTab = {
+      id: tabId,
+      title: target.kind === 'launcher' ? 'Home' : target.name,
+      kind: target.kind,
+      target,
+      closable: tabId !== 'home',
+    };
+
+    if (existingTab) {
+      Object.assign(existingTab, nextTab);
+    } else {
+      this.tabs.push(nextTab);
+    }
+
+    this.activeTabId = tabId;
+    return nextTab;
+  }
+
+  activate(tabId) {
+    const tab = this.tabs.find((item) => item.id === tabId);
+    if (!tab) return null;
+    this.activeTabId = tab.id;
+    return tab;
+  }
+
+  remove(tabId) {
+    const tab = this.tabs.find((item) => item.id === tabId);
+    if (!tab || !tab.closable) return null;
+    this.tabs = this.tabs.filter((item) => item.id !== tabId);
+    if (this.activeTabId === tabId) {
+      this.activeTabId = 'home';
+    }
+    return tab;
+  }
+
+  getTab(tabId) {
+    return this.tabs.find((item) => item.id === tabId) || null;
+  }
+
+  getSerializableTabs() {
+    return this.tabs.map((tab) => ({
+      id: tab.id,
+      title: tab.title,
+      kind: tab.kind,
+      closable: tab.closable,
+      active: tab.id === this.activeTabId,
+    }));
+  }
+}
--- a/package-lock.json
+++ b/package-lock.json
--- a/package.json
+++ b/package.json
@@ -1,6 +1,7 @@
 {
  "name": "@cloudcli-ai/cloudcli",
-  "version": "1.33.2",
+  "version": "1.34.0",
+  "productName": "CloudCLI",
  "description": "A web-based UI for Claude Code CLI",
  "type": "module",
  "main": "dist-server/server/index.js",
@@ -8,10 +9,10 @@
    "cloudcli": "dist-server/server/cli.js"
  },
  "files": [
+    "electron/",
    "server/",
    "shared/",
    "public/api-docs.html",
-    "public/modelConstants.js",
    "dist/",
    "dist-server/",
    "scripts/",
@@ -31,6 +32,12 @@
    "server:dev": "tsx --tsconfig server/tsconfig.json server/index.js",
    "server:dev-watch": "tsx watch --tsconfig server/tsconfig.json server/index.js",
    "client": "vite",
+    "desktop": "electron electron/main.js",
+    "desktop:dev": "cross-env ELECTRON_DEV_URL=http://127.0.0.1:5173 electron electron/main.js",
+    "desktop:pack": "npm run build && electron-builder --dir",
+    "desktop:dist:mac": "npm run build && electron-builder --mac dmg zip",
+    "desktop:dist:win": "npm run build && electron-builder --win nsis zip",
+    "desktop:icon:mac": "node electron/scripts/generate-macos-icon.js",
    "build": "npm run build:client && npm run build:server",
    "build:client": "vite build",
    "prebuild:server": "node -e \"require('node:fs').rmSync('dist-server', { recursive: true, force: true })\"",
@@ -46,6 +53,62 @@
    "prepare": "husky",
    "update:platform": "./update-platform.sh"
  },
+  "build": {
+    "appId": "ai.cloudcli.desktop",
+    "productName": "CloudCLI",
+    "asar": false,
+    "artifactName": "CloudCLI-${version}-${arch}.${ext}",
+    "directories": {
+      "output": "release"
+    },
+    "extraMetadata": {
+      "main": "electron/main.js"
+    },
+    "files": [
+      "electron/",
+      "public/",
+      "dist/",
+      "dist-server/",
+      "shared/",
+      "server/",
+      "package.json"
+    ],
+    "protocols": [
+      {
+        "name": "CloudCLI",
+        "schemes": [
+          "cloudcli"
+        ]
+      }
+    ],
+    "mac": {
+      "category": "public.app-category.developer-tools",
+      "icon": "electron/assets/logo-macos.icns",
+      "notarize": true,
+      "target": [
+        "dmg",
+        "zip"
+      ],
+      "extendInfo": {
+        "CFBundleName": "CloudCLI",
+        "CFBundleDisplayName": "CloudCLI",
+        "CFBundleURLTypes": [
+          {
+            "CFBundleURLName": "CloudCLI",
+            "CFBundleURLSchemes": [
+              "cloudcli"
+            ]
+          }
+        ]
+      }
+    },
+    "win": {
+      "target": [
+        "nsis",
+        "zip"
+      ]
+    }
+  },
  "keywords": [
    "claude code",
    "claude-code",
@@ -142,6 +205,9 @@
    "auto-changelog": "^2.5.0",
    "autoprefixer": "^10.4.16",
    "concurrently": "^8.2.2",
+    "cross-env": "^10.1.0",
+    "electron": "^38.0.0",
+    "electron-builder": "^26.15.3",
    "eslint": "^9.39.3",
    "eslint-import-resolver-typescript": "^4.4.4",
    "eslint-plugin-boundaries": "^6.0.2",
@@ -168,5 +234,9 @@
  "lint-staged": {
    "src/**/*.{ts,tsx,js,jsx}": "eslint",
    "server/**/*.{js,ts}": "eslint"
+  },
+  "optionalDependencies": {
+    "@nut-tree-fork/nut-js": "^4.2.6",
+    "screenshot-desktop": "^1.15.4"
  }
 }
--- a/public/api-docs.html
+++ b/public/api-docs.html
@@ -820,31 +820,49 @@ data: {"type":"done"}</code></pre>
        </div>
    </div>

-    <script type="module">
-        // Import model constants
-        import { PROVIDERS } from './modelConstants.js';
-
+    <script>
        // Dynamic URL replacement
        const apiUrl = window.location.origin;
        document.querySelectorAll('.api-url').forEach(el => {
            el.textContent = apiUrl;
        });

-        // Dynamically populate model documentation
-        window.addEventListener('DOMContentLoaded', () => {
-            const modelCell = document.getElementById('model-options-cell');
-            if (modelCell) {
-                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>');
+        // Populate model documentation from the live provider API
+        const PROVIDER_ORDER = [
+            { id: 'claude',   name: 'Anthropic' },
+            { id: 'codex',    name: 'OpenAI' },
+            { id: 'gemini',   name: 'Google' },
+            { id: 'cursor',   name: 'Cursor' },
+            { id: 'opencode', name: 'OpenCode' },
+        ];

-                modelCell.innerHTML = `
-                    Model identifier for the AI provider:<br><br>
-                    ${providerModels}
-                `;
-            }
-        });
+        async function populateModels() {
+            const modelCell = document.getElementById('model-options-cell');
+            if (!modelCell) return;
+
+            const token = localStorage.getItem('auth-token');
+            const headers = token ? { Authorization: `Bearer ${token}` } : {};
+
+            const results = await Promise.allSettled(
+                PROVIDER_ORDER.map(({ id }) =>
+                    fetch(`/api/providers/${id}/models`, { headers }).then(r => r.json())
+                )
+            );
+
+            const providerModels = results.map((result, i) => {
+                const { name } = PROVIDER_ORDER[i];
+                if (result.status === 'rejected' || !result.value?.data?.models) {
+                    return `<strong>${name}:</strong> <em>unavailable</em>`;
+                }
+                const { OPTIONS, DEFAULT } = result.value.data.models;
+                const models = OPTIONS.map(m => `<code>${m.value}</code>`).join(', ');
+                return `<strong>${name}:</strong> ${models} (default: <code>${DEFAULT}</code>)`;
+            }).join('<br><br>');
+
+            modelCell.innerHTML = `Model identifier for the AI provider:<br><br>${providerModels}`;
+        }
+
+        document.addEventListener('DOMContentLoaded', populateModels);

        // Tab switching
        window.showTab = function(tabName) {
--- a/public/modelConstants.js
+++ b/public/modelConstants.js
@@ -1,848 +0,0 @@
-/**
- * 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.8 (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: "opus[1m]",
-      label: "Opus 4.8 (1M context)",
-      description:
-        "Opus 4.8 with 1M context · Most capable for complex work · $5/$25 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 },
-];
--- 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 [`public/modelConstants.js`](https://github.com/siteboon/claudecodeui/blob/main/public/modelConstants.js) for the full list of supported models)
+- **Model Compatibility** - Works with Claude, GPT, and Gemini model families (the full list of supported models is available at runtime via `GET /api/providers/:provider/models`)


 ## Quick Start
--- a/server/browser-use-mcp.ts
+++ b/server/browser-use-mcp.ts
@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+import './load-env.js';
+
+type JsonRpcRequest = {
+  jsonrpc: '2.0';
+  id?: string | number | null;
+  method: string;
+  params?: Record<string, unknown>;
+};
+
+type ToolDefinition = {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+};
+
+const textResponse = (text: string) => ({
+  content: [{ type: 'text', text }],
+});
+
+const jsonResponse = (value: unknown) => textResponse(JSON.stringify(value, null, 2));
+
+const readString = (value: unknown, name: string): string => {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`${name} is required.`);
+  }
+  return value.trim();
+};
+
+const readOptionalString = (value: unknown): string | undefined =>
+  typeof value === 'string' && value.trim() ? value.trim() : undefined;
+
+const readNumber = (value: unknown): number | undefined =>
+  typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+
+const apiUrl = (process.env.CLOUDCLI_BROWSER_USE_API_URL || 'http://127.0.0.1:3001/api/browser-use-mcp').replace(/\/$/, '');
+const apiToken = process.env.CLOUDCLI_BROWSER_USE_MCP_TOKEN || '';
+const API_TIMEOUT_MS = Number.parseInt(process.env.CLOUDCLI_BROWSER_USE_API_TIMEOUT_MS || '60000', 10);
+
+async function callBrowserUseApi(toolName: string, input: Record<string, unknown>) {
+  if (!apiToken) {
+    throw new Error('CLOUDCLI_BROWSER_USE_MCP_TOKEN is not configured.');
+  }
+
+  const response = await fetch(`${apiUrl}/tools/${encodeURIComponent(toolName)}`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${apiToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(input),
+    signal: AbortSignal.timeout(API_TIMEOUT_MS),
+  });
+  const data = await response.json() as { success?: boolean; data?: unknown; error?: string };
+  if (!response.ok || data.success === false) {
+    throw new Error(data.error || `Browser API request failed (${response.status})`);
+  }
+  return data.data;
+}
+
+const sessionIdSchema = {
+  type: 'object',
+  properties: {
+    sessionId: { type: 'string', description: 'Browser session id.' },
+  },
+  required: ['sessionId'],
+};
+
+const tools: ToolDefinition[] = [
+  {
+    name: 'browser_create_session',
+    description: 'Create a temporary Browser session that the agent can control. Optionally provide a background profileName to reuse cookies and storage.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        profileName: { type: 'string', description: 'Optional background profile name for persistent browser storage.' },
+      },
+    },
+  },
+  {
+    name: 'browser_list_sessions',
+    description: 'List Browser sessions currently available to agents.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'browser_snapshot',
+    description: 'Capture current page metadata, screenshot data URL, and visible body text for a Browser session.',
+    inputSchema: sessionIdSchema,
+  },
+  {
+    name: 'browser_take_screenshot',
+    description: 'Capture the latest screenshot for a Browser session.',
+    inputSchema: sessionIdSchema,
+  },
+  {
+    name: 'browser_navigate',
+    description: 'Navigate a Browser session to an HTTP or HTTPS URL.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string' },
+        url: { type: 'string' },
+      },
+      required: ['sessionId', 'url'],
+    },
+  },
+  {
+    name: 'browser_click',
+    description: 'Click an element by CSS selector, visible text, or x/y coordinates.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string' },
+        selector: { type: 'string' },
+        text: { type: 'string' },
+        x: { type: 'number' },
+        y: { type: 'number' },
+      },
+      required: ['sessionId'],
+    },
+  },
+  {
+    name: 'browser_type',
+    description: 'Type text into the focused page or fill a CSS selector. Set submit to press Enter after typing.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string' },
+        selector: { type: 'string' },
+        text: { type: 'string' },
+        submit: { type: 'boolean' },
+      },
+      required: ['sessionId', 'text'],
+    },
+  },
+  {
+    name: 'browser_fill_form',
+    description: 'Fill multiple form fields using CSS selectors.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string' },
+        fields: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              selector: { type: 'string' },
+              value: { type: 'string' },
+            },
+            required: ['selector', 'value'],
+          },
+        },
+      },
+      required: ['sessionId', 'fields'],
+    },
+  },
+  {
+    name: 'browser_press_key',
+    description: 'Press a keyboard key, for example Enter, Escape, Tab, or Control+A.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string' },
+        key: { type: 'string' },
+      },
+      required: ['sessionId', 'key'],
+    },
+  },
+  {
+    name: 'browser_select_option',
+    description: 'Select option values in a select element found by CSS selector.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string' },
+        selector: { type: 'string' },
+        values: { type: 'array', items: { type: 'string' } },
+      },
+      required: ['sessionId', 'selector', 'values'],
+    },
+  },
+  {
+    name: 'browser_wait_for',
+    description: 'Wait for visible text, a URL pattern, or a short timeout.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string' },
+        text: { type: 'string' },
+        url: { type: 'string' },
+        timeoutMs: { type: 'number' },
+      },
+      required: ['sessionId'],
+    },
+  },
+  {
+    name: 'browser_tabs',
+    description: 'List, open, select, or close tabs in a Browser session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string' },
+        action: { type: 'string', enum: ['list', 'new', 'select', 'close'] },
+        index: { type: 'number' },
+        url: { type: 'string' },
+      },
+      required: ['sessionId'],
+    },
+  },
+  {
+    name: 'browser_close_session',
+    description: 'Stop a Browser session controlled by agents.',
+    inputSchema: sessionIdSchema,
+  },
+];
+
+async function callTool(name: string, args: Record<string, unknown>) {
+  switch (name) {
+    case 'browser_create_session':
+      return jsonResponse(await callBrowserUseApi(name, {
+        profileName: readOptionalString(args.profileName),
+      }));
+    case 'browser_list_sessions':
+      return jsonResponse(await callBrowserUseApi(name, {}));
+    case 'browser_snapshot':
+      return jsonResponse(await callBrowserUseApi(name, { sessionId: readString(args.sessionId, 'sessionId') }));
+    case 'browser_take_screenshot': {
+      return jsonResponse(await callBrowserUseApi(name, { sessionId: readString(args.sessionId, 'sessionId') }));
+    }
+    case 'browser_navigate':
+      return jsonResponse(await callBrowserUseApi(name, {
+        sessionId: readString(args.sessionId, 'sessionId'),
+        url: readString(args.url, 'url'),
+      }));
+    case 'browser_click':
+      return jsonResponse(await callBrowserUseApi(name, {
+        sessionId: readString(args.sessionId, 'sessionId'),
+        selector: readOptionalString(args.selector),
+        text: readOptionalString(args.text),
+        x: readNumber(args.x),
+        y: readNumber(args.y),
+      }));
+    case 'browser_type':
+      return jsonResponse(await callBrowserUseApi(name, {
+        sessionId: readString(args.sessionId, 'sessionId'),
+        selector: readOptionalString(args.selector),
+        text: readString(args.text, 'text'),
+        submit: args.submit === true,
+      }));
+    case 'browser_fill_form': {
+      const fields = Array.isArray(args.fields)
+        ? args.fields.map((field) => {
+          const record = field as Record<string, unknown>;
+          return {
+            selector: readString(record.selector, 'field.selector'),
+            value: readString(record.value, 'field.value'),
+          };
+        })
+        : [];
+      return jsonResponse(await callBrowserUseApi(name, {
+        sessionId: readString(args.sessionId, 'sessionId'),
+        fields,
+      }));
+    }
+    case 'browser_press_key':
+      return jsonResponse(await callBrowserUseApi(name, {
+        sessionId: readString(args.sessionId, 'sessionId'),
+        key: readString(args.key, 'key'),
+      }));
+    case 'browser_select_option':
+      return jsonResponse(await callBrowserUseApi(name, {
+        sessionId: readString(args.sessionId, 'sessionId'),
+        selector: readString(args.selector, 'selector'),
+        values: Array.isArray(args.values) ? args.values.filter((value): value is string => typeof value === 'string') : [],
+      }));
+    case 'browser_wait_for':
+      return jsonResponse(await callBrowserUseApi(name, {
+        sessionId: readString(args.sessionId, 'sessionId'),
+        text: readOptionalString(args.text),
+        url: readOptionalString(args.url),
+        timeoutMs: readNumber(args.timeoutMs),
+      }));
+    case 'browser_tabs':
+      return jsonResponse(await callBrowserUseApi(name, {
+        sessionId: readString(args.sessionId, 'sessionId'),
+        action: args.action === 'new' || args.action === 'select' || args.action === 'close' || args.action === 'list'
+          ? args.action
+          : undefined,
+        index: readNumber(args.index),
+        url: readOptionalString(args.url),
+      }));
+    case 'browser_close_session':
+      return jsonResponse(await callBrowserUseApi(name, { sessionId: readString(args.sessionId, 'sessionId') }));
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+async function handleMessage(message: JsonRpcRequest) {
+  if (message.method === 'initialize') {
+    return {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: {} },
+      serverInfo: { name: 'cloudcli-browser', version: '1.0.0' },
+    };
+  }
+
+  if (message.method === 'tools/list') {
+    return { tools };
+  }
+
+  if (message.method === 'tools/call') {
+    const params = message.params || {};
+    const name = readString(params.name, 'name');
+    const args = (params.arguments && typeof params.arguments === 'object'
+      ? params.arguments
+      : {}) as Record<string, unknown>;
+    return callTool(name, args);
+  }
+
+  if (message.method.startsWith('notifications/')) {
+    return undefined;
+  }
+
+  throw new Error(`Unsupported method: ${message.method}`);
+}
+
+function writeMessage(message: Record<string, unknown>) {
+  // MCP stdio transport uses newline-delimited JSON (one JSON-RPC message per line,
+  // no embedded newlines). This is NOT the LSP Content-Length framing.
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function sendResult(id: string | number | null | undefined, result: unknown) {
+  if (id === undefined) {
+    return;
+  }
+  writeMessage({ jsonrpc: '2.0', id, result });
+}
+
+function sendError(id: string | number | null | undefined, error: unknown) {
+  if (id === undefined) {
+    return;
+  }
+  writeMessage({
+    jsonrpc: '2.0',
+    id,
+    error: {
+      code: -32000,
+      message: error instanceof Error ? error.message : String(error),
+    },
+  });
+}
+
+let buffer = '';
+
+process.stdin.on('data', (chunk) => {
+  buffer += chunk.toString('utf8');
+  let newlineIndex: number;
+  while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+    const rawMessage = buffer.slice(0, newlineIndex).trim();
+    buffer = buffer.slice(newlineIndex + 1);
+    if (!rawMessage) {
+      continue;
+    }
+
+    void (async () => {
+      let request: JsonRpcRequest;
+      try {
+        request = JSON.parse(rawMessage) as JsonRpcRequest;
+      } catch (error) {
+        sendError(null, error);
+        return;
+      }
+      try {
+        const result = await handleMessage(request);
+        sendResult(request.id, result);
+      } catch (error) {
+        sendError(request.id, error);
+      }
+    })();
+  }
+});
--- a/server/claude-sdk.js
+++ b/server/claude-sdk.js
@@ -28,10 +28,14 @@ import {
 } 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 { createNormalizedMessage } from './shared/utils.js';
+import { createCompleteMessage, createNormalizedMessage } from './shared/utils.js';

 const activeSessions = new Map();
 const pendingToolApprovals = new Map();
+// Sessions cancelled via abort-session. The abort handler already sent the
+// terminal `complete` (aborted: true) to the client, so the run loop must not
+// emit a second one when its generator winds down.
+const abortedSessionIds = new Set();

 const TOOL_APPROVAL_TIMEOUT_MS = parseInt(process.env.CLAUDE_TOOL_APPROVAL_TIMEOUT_MS, 10) || 55000;

@@ -204,7 +208,7 @@ function mapCliOptionsToSDK(options = {}) {
  sdkOptions.disallowedTools = settings.disallowedTools || [];

  // Map model (default to sonnet)
-  // Valid models: sonnet, opus, haiku, opusplan, sonnet[1m]
+  // Valid models: sonnet, opus, haiku, opusplan, sonnet[1m], fable
  sdkOptions.model = options.model || CLAUDE_FALLBACK_MODELS.DEFAULT;
  // Model logged at query start below

@@ -731,14 +735,18 @@ async function queryClaudeSDK(command, options = {}, ws) {
    // Clean up temporary image files
    await cleanupTempFiles(tempImagePaths, tempDir);

-    // Send completion event
-    ws.send(createNormalizedMessage({ kind: 'complete', exitCode: 0, isNewSession: !sessionId && !!command, sessionId: capturedSessionId, provider: 'claude' }));
+    // Send the terminal completion event — skipped for aborted runs, whose
+    // terminal `complete` (aborted: true) was already sent by abort-session.
+    const wasAborted = capturedSessionId ? abortedSessionIds.delete(capturedSessionId) : false;
+    if (!wasAborted) {
+      ws.send(createCompleteMessage({ provider: 'claude', sessionId: capturedSessionId || sessionId || null, exitCode: 0 }));
+    }
    notifyRunStopped({
      userId: ws?.userId || null,
      provider: 'claude',
      sessionId: capturedSessionId || sessionId || null,
      sessionName: sessionSummary,
-      stopReason: 'completed'
+      stopReason: wasAborted ? 'aborted' : 'completed'
    });
    // Complete

@@ -753,14 +761,22 @@ async function queryClaudeSDK(command, options = {}, ws) {
    // Clean up temporary image files on error
    await cleanupTempFiles(tempImagePaths, tempDir);

+    const wasAborted = capturedSessionId ? abortedSessionIds.delete(capturedSessionId) : false;
+    if (wasAborted) {
+      // The abort already produced the terminal complete; a generator throw
+      // caused by interrupt() is expected noise, not a user-facing error.
+      return;
+    }
+
    // Check if Claude CLI is installed for a clearer error message
    const installed = await providerAuthService.isProviderInstalled('claude');
    const errorContent = !installed
      ? 'Claude Code is not installed. Please install it first: https://docs.anthropic.com/en/docs/claude-code'
      : error.message;

-    // Send error to WebSocket
+    // Send error to WebSocket, then the terminal complete
    ws.send(createNormalizedMessage({ kind: 'error', content: errorContent, sessionId: capturedSessionId || sessionId || null, provider: 'claude' }));
+    ws.send(createCompleteMessage({ provider: 'claude', sessionId: capturedSessionId || sessionId || null, exitCode: 1 }));
    notifyRunFailed({
      userId: ws?.userId || null,
      provider: 'claude',
@@ -787,6 +803,10 @@ async function abortClaudeSDKSession(sessionId) {
  try {
    console.log(`Aborting SDK session: ${sessionId}`);

+    // Mark before interrupting so the run loop knows not to emit its own
+    // terminal complete (the abort handler sends the aborted one).
+    abortedSessionIds.add(sessionId);
+
    // Call interrupt() on the query instance
    await session.instance.interrupt();

@@ -802,6 +822,8 @@ async function abortClaudeSDKSession(sessionId) {
    return true;
  } catch (error) {
    console.error(`Error aborting session ${sessionId}:`, error);
+    // The run keeps going; let it emit its own terminal complete.
+    abortedSessionIds.delete(sessionId);
    return false;
  }
 }
--- a/server/cli.js
+++ b/server/cli.js
@@ -8,6 +8,7 @@
 *   (no args)     - Start the server (default)
 *   start         - Start the server
 *   sandbox       - Manage Docker sandbox environments
+ *   browser-use-mcp - Run Browser MCP stdio server
 *   status        - Show configuration and data locations
 *   help          - Show help information
 *   version       - Show version information
@@ -154,12 +155,13 @@ Usage:
  cloudcli [command] [options]

 Commands:
-  start          Start the CloudCLI server (default)
-  sandbox        Manage Docker sandbox environments
-  status         Show configuration and data locations
-  update         Update to the latest version
-  help           Show this help information
-  version        Show version information
+  start            Start the CloudCLI server (default)
+  sandbox          Manage Docker sandbox environments
+  browser-use-mcp  Run the Browser MCP stdio server
+  status           Show configuration and data locations
+  update           Update to the latest version
+  help             Show this help information
+  version          Show version information

 Options:
  -p, --port <port>           Set server port (default: 3001)
@@ -605,6 +607,10 @@ async function startServer() {
    await import('./index.js');
 }

+async function startBrowserUseMcp() {
+    await import('./browser-use-mcp.js');
+}
+
 // Parse CLI arguments
 function parseArgs(args) {
    const parsed = { command: 'start', options: {} };
@@ -658,6 +664,9 @@ async function main() {
        case 'sandbox':
            await sandboxCommand(remainingArgs || []);
            break;
+        case 'browser-use-mcp':
+            await startBrowserUseMcp();
+            break;
        case 'status':
        case 'info':
            showStatus();
--- a/server/computer-use-agent.ts
+++ b/server/computer-use-agent.ts
@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+/**
+ * CloudCLI Computer Use — Desktop Agent.
+ *
+ * Standalone executor for the cloud relay. The Electron desktop app spawns this
+ * process (via ELECTRON_RUN_AS_NODE) whenever Computer Use is enabled and the
+ * user has running cloud environments. It opens an outbound websocket to each
+ * environment's `/desktop-agent` endpoint and executes the `computer_*` actions
+ * the hosted server relays, returning a fresh screenshot each time.
+ *
+ * It is fully self-contained: it reuses the shared nut-js executor module and
+ * does NOT depend on the local CloudCLI server. Consent is enforced here (the
+ * controlled machine is the authority): in `ask` mode the agent asks the parent
+ * Electron process for a per-session decision before the first action runs.
+ */
+import readline from 'node:readline';
+
+import { WebSocket } from 'ws';
+
+import {
+  executor,
+  captureScreenshot,
+  getRuntimeReadiness,
+  type ExecutorTarget,
+  type Point,
+  type ClickButton,
+  type ScrollDirection,
+} from './modules/computer-use/computer-executor.js';
+
+type ConsentMode = 'ask' | 'auto';
+
+type RelayMessage = {
+  kind?: string;
+  type?: string;
+  id?: string;
+  params?: Record<string, unknown>;
+};
+
+const IPC_PREFIX = '@@CUAGENT@@';
+const RECONNECT_BASE_MS = 2000;
+const RECONNECT_MAX_MS = 30_000;
+
+const consentMode: ConsentMode = process.env.CLOUDCLI_COMPUTER_USE_CONSENT_MODE === 'auto' ? 'auto' : 'ask';
+const agentLabel = process.env.CLOUDCLI_DESKTOP_AGENT_LABEL || 'cloudcli-desktop';
+
+function parseTargets(): string[] {
+  const raw =
+    process.env.CLOUDCLI_DESKTOP_AGENT_URLS ||
+    process.env.CLOUDCLI_DESKTOP_AGENT_URL ||
+    '';
+  return raw
+    .split(',')
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+// --- Parent (Electron) IPC over stdout/stdin -------------------------------
+
+function emitToParent(message: Record<string, unknown>): void {
+  process.stdout.write(`${IPC_PREFIX} ${JSON.stringify(message)}\n`);
+}
+
+/** Per-session consent decisions, and resolvers awaiting a parent reply. */
+const sessionConsent = new Map<string, 'granted' | 'denied'>();
+const pendingConsent = new Map<string, Array<(allow: boolean) => void>>();
+
+const stdinReader = readline.createInterface({ input: process.stdin });
+stdinReader.on('line', (line) => {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith(IPC_PREFIX)) {
+    return;
+  }
+  try {
+    const payload = JSON.parse(trimmed.slice(IPC_PREFIX.length).trim()) as Record<string, unknown>;
+    if (payload.type === 'consent-response' && typeof payload.sessionId === 'string') {
+      const allow = payload.allow === true;
+      sessionConsent.set(payload.sessionId, allow ? 'granted' : 'denied');
+      const waiters = pendingConsent.get(payload.sessionId) || [];
+      pendingConsent.delete(payload.sessionId);
+      for (const resolve of waiters) {
+        resolve(allow);
+      }
+    } else if (payload.type === 'revoke-session' && typeof payload.sessionId === 'string') {
+      sessionConsent.delete(payload.sessionId);
+    }
+  } catch {
+    // ignore malformed control lines
+  }
+});
+
+async function ensureConsent(sessionId: string): Promise<boolean> {
+  if (consentMode === 'auto') {
+    return true;
+  }
+  const existing = sessionConsent.get(sessionId);
+  if (existing === 'granted') return true;
+  if (existing === 'denied') return false;
+
+  // Ask the parent (Electron) to prompt the user, and wait for the decision.
+  return new Promise<boolean>((resolve) => {
+    const waiters = pendingConsent.get(sessionId) || [];
+    waiters.push(resolve);
+    pendingConsent.set(sessionId, waiters);
+    emitToParent({ type: 'consent-request', sessionId });
+  });
+}
+
+// --- Action execution ------------------------------------------------------
+
+function asPoint(value: unknown): Point | undefined {
+  if (value && typeof value === 'object') {
+    const point = value as Record<string, unknown>;
+    if (typeof point.x === 'number' && typeof point.y === 'number') {
+      return { x: point.x, y: point.y };
+    }
+  }
+  return undefined;
+}
+
+async function snapshot(target: ExecutorTarget) {
+  const { dataUrl, size } = await captureScreenshot();
+  return { screenshotDataUrl: dataUrl, displaySize: size || target.displaySize };
+}
+
+async function runAction(type: string, params: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const readiness = getRuntimeReadiness();
+  if (!readiness.nutInstalled || !readiness.screenshotInstalled) {
+    throw new Error('Computer Use runtime is not installed on the desktop agent.');
+  }
+
+  const target: ExecutorTarget = {
+    displaySize: (params.displaySize as ExecutorTarget['displaySize']) ?? null,
+  };
+  const point = asPoint(params.point);
+
+  switch (type) {
+    case 'screenshot':
+      return snapshot(target);
+    case 'cursor_position': {
+      const position = await executor.cursorPosition(target);
+      return { ...(await snapshot(target)), position, cursor: position };
+    }
+    case 'mouse_move':
+      await executor.moveTo(target, point as Point);
+      return { ...(await snapshot(target)), cursor: point };
+    case 'click':
+      await executor.click(target, (params.button as ClickButton) || 'left', point, params.double === true);
+      return { ...(await snapshot(target)), cursor: point ?? null };
+    case 'drag':
+      await executor.drag(target, asPoint(params.from) as Point, asPoint(params.to) as Point, (params.button as ClickButton) || 'left');
+      return { ...(await snapshot(target)), cursor: asPoint(params.to) ?? null };
+    case 'type':
+      await executor.type(String(params.text ?? ''));
+      return snapshot(target);
+    case 'key':
+      await executor.pressChord(String(params.key ?? ''));
+      return snapshot(target);
+    case 'scroll':
+      await executor.scroll(
+        target,
+        (params.direction as ScrollDirection) || 'down',
+        typeof params.amount === 'number' ? params.amount : 3,
+        point,
+      );
+      return { ...(await snapshot(target)), cursor: point ?? null };
+    case 'wait':
+      await new Promise((resolve) => setTimeout(resolve, Math.max(0, Math.min(Number(params.ms) || 1000, 10_000))));
+      return snapshot(target);
+    default:
+      throw new Error(`Unsupported computer action: ${type}`);
+  }
+}
+
+// --- Relay connection ------------------------------------------------------
+
+function connect(url: string): void {
+  let reconnectMs = RECONNECT_BASE_MS;
+  let socket: WebSocket | null = null;
+
+  const open = () => {
+    socket = new WebSocket(url, {
+      headers: process.env.CLOUDCLI_DESKTOP_AGENT_TOKEN
+        ? { 'x-cloudcli-agent-token': process.env.CLOUDCLI_DESKTOP_AGENT_TOKEN }
+        : undefined,
+    });
+
+    socket.on('open', () => {
+      reconnectMs = RECONNECT_BASE_MS;
+      emitToParent({ type: 'connected', url });
+      socket?.send(JSON.stringify({ kind: 'register', label: agentLabel, consentMode }));
+    });
+
+    socket.on('message', async (raw) => {
+      let message: RelayMessage;
+      try {
+        message = JSON.parse(String(raw)) as RelayMessage;
+      } catch {
+        return;
+      }
+      const kind = message.kind || message.type;
+      if (kind !== 'computer_relay' || typeof message.id !== 'string') {
+        return;
+      }
+
+      const id = message.id;
+      const type = String(message.type || (message.params?.type as string) || '');
+      const params = message.params || {};
+      const sessionId = typeof params.sessionId === 'string' ? params.sessionId : 'default';
+
+      if (type === 'stop_session') {
+        sessionConsent.delete(sessionId);
+        socket?.send(JSON.stringify({ kind: 'computer_relay_result', id, result: { ok: true } }));
+        return;
+      }
+
+      try {
+        const allowed = await ensureConsent(sessionId);
+        if (!allowed) {
+          socket?.send(JSON.stringify({ kind: 'computer_relay_result', id, error: 'The user denied desktop control for this session.' }));
+          return;
+        }
+        const result = await runAction(type, params);
+        socket?.send(JSON.stringify({ kind: 'computer_relay_result', id, result }));
+      } catch (error) {
+        socket?.send(JSON.stringify({
+          kind: 'computer_relay_result',
+          id,
+          error: error instanceof Error ? error.message : 'Desktop agent action failed.',
+        }));
+      }
+    });
+
+    const scheduleReconnect = () => {
+      emitToParent({ type: 'disconnected', url });
+      setTimeout(open, reconnectMs);
+      reconnectMs = Math.min(reconnectMs * 2, RECONNECT_MAX_MS);
+    };
+
+    socket.on('close', scheduleReconnect);
+    socket.on('error', () => {
+      try { socket?.close(); } catch { /* noop */ }
+    });
+  };
+
+  open();
+}
+
+function main(): void {
+  const targets = parseTargets();
+  if (targets.length === 0) {
+    emitToParent({ type: 'error', message: 'No desktop-agent target URLs provided.' });
+    return;
+  }
+  emitToParent({ type: 'starting', targets, consentMode });
+  for (const url of targets) {
+    connect(url);
+  }
+}
+
+main();
--- a/server/computer-use-mcp.ts
+++ b/server/computer-use-mcp.ts
@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+import './load-env.js';
+
+type JsonRpcRequest = {
+  jsonrpc: '2.0';
+  id?: string | number | null;
+  method: string;
+  params?: Record<string, unknown>;
+};
+
+type ToolDefinition = {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+};
+
+const readString = (value: unknown, name: string): string => {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`${name} is required.`);
+  }
+  return value.trim();
+};
+
+const readNumber = (value: unknown): number | undefined =>
+  typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+
+const apiUrl = (process.env.CLOUDCLI_COMPUTER_USE_API_URL || 'http://127.0.0.1:3001/api/computer-use-mcp').replace(/\/$/, '');
+const apiToken = process.env.CLOUDCLI_COMPUTER_USE_MCP_TOKEN || '';
+
+async function callComputerUseApi(toolName: string, input: Record<string, unknown>) {
+  if (!apiToken) {
+    throw new Error('CLOUDCLI_COMPUTER_USE_MCP_TOKEN is not configured.');
+  }
+
+  const response = await fetch(`${apiUrl}/tools/${encodeURIComponent(toolName)}`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${apiToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(input),
+  });
+  const data = await response.json() as { success?: boolean; data?: unknown; error?: string };
+  if (!response.ok || data.success === false) {
+    throw new Error(data.error || `Computer Use API request failed (${response.status})`);
+  }
+  return data.data;
+}
+
+/** Pulls the most recent screenshot data URL out of an API result, if present. */
+function findScreenshot(value: unknown): string | null {
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+  const record = value as Record<string, unknown>;
+  if (typeof record.screenshotDataUrl === 'string') {
+    return record.screenshotDataUrl;
+  }
+  if (record.session && typeof record.session === 'object') {
+    const session = record.session as Record<string, unknown>;
+    if (typeof session.screenshotDataUrl === 'string') {
+      return session.screenshotDataUrl;
+    }
+  }
+  return null;
+}
+
+/** Removes the large data URL from JSON so the text block stays small. */
+function stripScreenshot(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(stripScreenshot);
+  }
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+      if (key === 'screenshotDataUrl' && typeof val === 'string') {
+        out.screenshot = '[returned as image]';
+        continue;
+      }
+      out[key] = stripScreenshot(val);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Builds an MCP tool result. Screenshots are returned as an `image` content block so
+ * vision-capable models actually see the desktop — a JSON data-URL string would not work.
+ */
+function toolResult(value: unknown) {
+  const content: Array<Record<string, unknown>> = [
+    { type: 'text', text: JSON.stringify(stripScreenshot(value), null, 2) },
+  ];
+
+  const screenshot = findScreenshot(value);
+  const match = screenshot ? /^data:(image\/[a-z]+);base64,(.+)$/i.exec(screenshot) : null;
+  if (match) {
+    content.push({ type: 'image', data: match[2], mimeType: match[1] });
+  }
+
+  return { content };
+}
+
+const sessionIdSchema = {
+  type: 'object',
+  properties: {
+    sessionId: { type: 'string', description: 'Computer Use session id.' },
+  },
+  required: ['sessionId'],
+};
+
+const pointSchema = {
+  type: 'object',
+  properties: {
+    sessionId: { type: 'string' },
+    x: { type: 'number', description: 'X coordinate in screenshot pixel space.' },
+    y: { type: 'number', description: 'Y coordinate in screenshot pixel space.' },
+  },
+  required: ['sessionId'],
+};
+
+const tools: ToolDefinition[] = [
+  {
+    name: 'computer_create_session',
+    description: 'Create a Computer Use session that controls the user desktop. The session starts WITHOUT control: the user must grant control in the Computer panel before any action will work. Returns a screenshot once available.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'computer_list_sessions',
+    description: 'List Computer Use sessions and whether the user has granted control.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'computer_screenshot',
+    description: 'Capture the current desktop screenshot. Returns the image plus the display size to use for coordinates.',
+    inputSchema: sessionIdSchema,
+  },
+  {
+    name: 'computer_cursor_position',
+    description: 'Get the current mouse cursor position in screenshot pixel space.',
+    inputSchema: sessionIdSchema,
+  },
+  {
+    name: 'computer_mouse_move',
+    description: 'Move the mouse cursor to x/y (screenshot pixel space).',
+    inputSchema: {
+      type: 'object',
+      properties: { sessionId: { type: 'string' }, x: { type: 'number' }, y: { type: 'number' } },
+      required: ['sessionId', 'x', 'y'],
+    },
+  },
+  {
+    name: 'computer_left_click',
+    description: 'Left-click. Optionally provide x/y to move there first.',
+    inputSchema: pointSchema,
+  },
+  {
+    name: 'computer_right_click',
+    description: 'Right-click. Optionally provide x/y to move there first.',
+    inputSchema: pointSchema,
+  },
+  {
+    name: 'computer_middle_click',
+    description: 'Middle-click. Optionally provide x/y to move there first.',
+    inputSchema: pointSchema,
+  },
+  {
+    name: 'computer_double_click',
+    description: 'Double-click. Optionally provide x/y to move there first.',
+    inputSchema: pointSchema,
+  },
+  {
+    name: 'computer_left_click_drag',
+    description: 'Press the left button at start coordinates and release at end coordinates (drag).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string' },
+        startX: { type: 'number' }, startY: { type: 'number' },
+        endX: { type: 'number' }, endY: { type: 'number' },
+      },
+      required: ['sessionId', 'startX', 'startY', 'endX', 'endY'],
+    },
+  },
+  {
+    name: 'computer_type',
+    description: 'Type a string of text at the current focus.',
+    inputSchema: {
+      type: 'object',
+      properties: { sessionId: { type: 'string' }, text: { type: 'string' } },
+      required: ['sessionId', 'text'],
+    },
+  },
+  {
+    name: 'computer_key',
+    description: 'Press a key or key chord using xdotool-style names, e.g. "Return", "Escape", "ctrl+a", "Page_Down".',
+    inputSchema: {
+      type: 'object',
+      properties: { sessionId: { type: 'string' }, key: { type: 'string' } },
+      required: ['sessionId', 'key'],
+    },
+  },
+  {
+    name: 'computer_scroll',
+    description: 'Scroll the mouse wheel. direction is up/down/left/right; amount is the number of steps. Optionally provide x/y to move there first.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string' },
+        direction: { type: 'string', enum: ['up', 'down', 'left', 'right'] },
+        amount: { type: 'number' },
+        x: { type: 'number' },
+        y: { type: 'number' },
+      },
+      required: ['sessionId', 'direction'],
+    },
+  },
+  {
+    name: 'computer_wait',
+    description: 'Wait for a short period (milliseconds, max 10000) then return a fresh screenshot.',
+    inputSchema: {
+      type: 'object',
+      properties: { sessionId: { type: 'string' }, timeoutMs: { type: 'number' } },
+      required: ['sessionId'],
+    },
+  },
+  {
+    name: 'computer_close_session',
+    description: 'Stop a Computer Use session and revoke control.',
+    inputSchema: sessionIdSchema,
+  },
+];
+
+async function callTool(name: string, args: Record<string, unknown>) {
+  switch (name) {
+    case 'computer_create_session':
+      return toolResult(await callComputerUseApi(name, {}));
+    case 'computer_list_sessions':
+      return toolResult(await callComputerUseApi(name, {}));
+    case 'computer_screenshot':
+    case 'computer_cursor_position':
+    case 'computer_close_session':
+      return toolResult(await callComputerUseApi(name, { sessionId: readString(args.sessionId, 'sessionId') }));
+    case 'computer_mouse_move':
+      return toolResult(await callComputerUseApi(name, {
+        sessionId: readString(args.sessionId, 'sessionId'),
+        x: readNumber(args.x),
+        y: readNumber(args.y),
+      }));
+    case 'computer_left_click':
+    case 'computer_right_click':
+    case 'computer_middle_click':
+    case 'computer_double_click':
+      return toolResult(await callComputerUseApi(name, {
+        sessionId: readString(args.sessionId, 'sessionId'),
+        x: readNumber(args.x),
+        y: readNumber(args.y),
+      }));
+    case 'computer_left_click_drag':
+      return toolResult(await callComputerUseApi(name, {
+        sessionId: readString(args.sessionId, 'sessionId'),
+        startX: readNumber(args.startX),
+        startY: readNumber(args.startY),
+        endX: readNumber(args.endX),
+        endY: readNumber(args.endY),
+      }));
+    case 'computer_type':
+      return toolResult(await callComputerUseApi(name, {
+        sessionId: readString(args.sessionId, 'sessionId'),
+        text: readString(args.text, 'text'),
+      }));
+    case 'computer_key':
+      return toolResult(await callComputerUseApi(name, {
+        sessionId: readString(args.sessionId, 'sessionId'),
+        key: readString(args.key, 'key'),
+      }));
+    case 'computer_scroll':
+      return toolResult(await callComputerUseApi(name, {
+        sessionId: readString(args.sessionId, 'sessionId'),
+        direction: typeof args.direction === 'string' ? args.direction : 'up',
+        amount: readNumber(args.amount),
+        x: readNumber(args.x),
+        y: readNumber(args.y),
+      }));
+    case 'computer_wait':
+      return toolResult(await callComputerUseApi(name, {
+        sessionId: readString(args.sessionId, 'sessionId'),
+        timeoutMs: readNumber(args.timeoutMs),
+      }));
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+async function handleMessage(message: JsonRpcRequest) {
+  if (message.method === 'initialize') {
+    return {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: {} },
+      serverInfo: { name: 'cloudcli-computer-use', version: '1.0.0' },
+    };
+  }
+
+  if (message.method === 'tools/list') {
+    return { tools };
+  }
+
+  if (message.method === 'tools/call') {
+    const params = message.params || {};
+    const name = readString(params.name, 'name');
+    const args = (params.arguments && typeof params.arguments === 'object'
+      ? params.arguments
+      : {}) as Record<string, unknown>;
+    return callTool(name, args);
+  }
+
+  if (message.method.startsWith('notifications/')) {
+    return undefined;
+  }
+
+  throw new Error(`Unsupported method: ${message.method}`);
+}
+
+function writeMessage(message: Record<string, unknown>) {
+  const payload = JSON.stringify(message);
+  process.stdout.write(`Content-Length: ${Buffer.byteLength(payload, 'utf8')}\r\n\r\n${payload}`);
+}
+
+function sendResult(id: string | number | null | undefined, result: unknown) {
+  if (id === undefined) {
+    return;
+  }
+  writeMessage({ jsonrpc: '2.0', id, result });
+}
+
+function sendError(id: string | number | null | undefined, error: unknown) {
+  if (id === undefined) {
+    return;
+  }
+  writeMessage({
+    jsonrpc: '2.0',
+    id,
+    error: {
+      code: -32000,
+      message: error instanceof Error ? error.message : String(error),
+    },
+  });
+}
+
+let buffer = Buffer.alloc(0);
+
+process.stdin.on('data', (chunk) => {
+  buffer = Buffer.concat([buffer, chunk]);
+  while (true) {
+    const headerEnd = buffer.indexOf('\r\n\r\n');
+    if (headerEnd === -1) {
+      return;
+    }
+
+    const header = buffer.slice(0, headerEnd).toString('utf8');
+    const lengthMatch = /Content-Length:\s*(\d+)/i.exec(header);
+    if (!lengthMatch) {
+      buffer = buffer.slice(headerEnd + 4);
+      continue;
+    }
+
+    const length = Number.parseInt(lengthMatch[1], 10);
+    const messageStart = headerEnd + 4;
+    const messageEnd = messageStart + length;
+    if (buffer.length < messageEnd) {
+      return;
+    }
+
+    const rawMessage = buffer.slice(messageStart, messageEnd).toString('utf8');
+    buffer = buffer.slice(messageEnd);
+
+    void (async () => {
+      const request = JSON.parse(rawMessage) as JsonRpcRequest;
+      try {
+        const result = await handleMessage(request);
+        sendResult(request.id, result);
+      } catch (error) {
+        sendError(request.id, error);
+      }
+    })();
+  }
+});
--- a/server/cursor-cli.js
+++ b/server/cursor-cli.js
@@ -4,7 +4,7 @@ import { notifyRunFailed, notifyRunStopped } from './services/notification-orche
 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';
+import { createCompleteMessage, createNormalizedMessage } from './shared/utils.js';

 // Use cross-spawn on Windows for better command execution
 const spawnFunction = process.platform === 'win32' ? crossSpawn : spawn;
@@ -34,6 +34,10 @@ async function spawnCursor(command, options = {}, ws) {
    let sessionCreatedSent = false; // Track if we've already sent session-created event
    let hasRetriedWithTrust = false;
    let settled = false;
+    // The unified lifecycle contract requires exactly one terminal `complete`
+    // per run. Cursor surfaces completion twice (the `result` JSON line and
+    // the process close), so the first emission wins.
+    let completeSent = false;

    // Use tools settings passed from frontend, or defaults
    const settings = toolsSettings || {
@@ -197,15 +201,15 @@ async function spawnCursor(command, options = {}, ws) {
              break;

            case 'result': {
-              // Session complete — send stream end + lifecycle complete with result payload
-              const resultText = typeof response.result === 'string' ? response.result : '';
-              ws.send(createNormalizedMessage({
-                kind: 'complete',
-                exitCode: response.subtype === 'success' ? 0 : 1,
-                resultText,
-                isError: response.subtype !== 'success',
-                sessionId: capturedSessionId || sessionId, provider: 'cursor',
-              }));
+              // Session complete — terminal lifecycle event for this run
+              if (!completeSent) {
+                completeSent = true;
+                ws.send(createCompleteMessage({
+                  provider: 'cursor',
+                  sessionId: capturedSessionId || sessionId || null,
+                  exitCode: response.subtype === 'success' ? 0 : 1,
+                }));
+              }
              break;
            }

@@ -271,7 +275,12 @@ async function spawnCursor(command, options = {}, ws) {
          return;
        }

-        ws.send(createNormalizedMessage({ kind: 'complete', exitCode: code, isNewSession: !sessionId && !!command, sessionId: finalSessionId, provider: 'cursor' }));
+        // Terminal complete — unless the `result` line already sent it, or the
+        // run was aborted (abort-session sent the aborted complete).
+        if (!completeSent && !cursorProcess.aborted) {
+          completeSent = true;
+          ws.send(createCompleteMessage({ provider: 'cursor', sessionId: finalSessionId, exitCode: code }));
+        }

        if (code === 0) {
          notifyTerminalState({ code });
@@ -297,6 +306,10 @@ async function spawnCursor(command, options = {}, ws) {
          : error.message;

        ws.send(createNormalizedMessage({ kind: 'error', content: errorContent, sessionId: capturedSessionId || sessionId || null, provider: 'cursor' }));
+        if (!completeSent && !cursorProcess.aborted) {
+          completeSent = true;
+          ws.send(createCompleteMessage({ provider: 'cursor', sessionId: capturedSessionId || sessionId || null, exitCode: 1 }));
+        }
        notifyTerminalState({ error });

        settleOnce(() => reject(error));
@@ -314,6 +327,9 @@ function abortCursorSession(sessionId) {
  const process = activeCursorProcesses.get(sessionId);
  if (process) {
    console.log(`Aborting Cursor session: ${sessionId}`);
+    // The abort handler sends the terminal complete (aborted: true); flag the
+    // process so its close handler does not emit a second one.
+    process.aborted = true;
    process.kill('SIGTERM');
    activeCursorProcesses.delete(sessionId);
    return true;
--- a/server/gemini-cli.js
+++ b/server/gemini-cli.js
@@ -10,7 +10,7 @@ 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';
+import { createCompleteMessage, 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;
@@ -129,6 +129,9 @@ async function spawnGemini(command, options = {}, ws) {
    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
+    // Unified lifecycle contract: exactly one terminal `complete` per run
+    // (close and error handlers can both fire for spawn failures).
+    let completeSent = false;

    // Use tools settings passed from frontend, or defaults
    const settings = toolsSettings || {
@@ -486,7 +489,12 @@ async function spawnGemini(command, options = {}, ws) {
                sessionManager.addMessage(finalSessionId, 'assistant', assistantBlocks);
            }

-            ws.send(createNormalizedMessage({ kind: 'complete', exitCode: code, isNewSession: !sessionId && !!command, sessionId: finalSessionId, provider: 'gemini' }));
+            // Terminal complete — skipped for aborted runs (abort-session
+            // already sent the aborted complete on this run's behalf).
+            if (!completeSent && !geminiProcess.aborted) {
+                completeSent = true;
+                ws.send(createCompleteMessage({ provider: 'gemini', sessionId: finalSessionId, exitCode: code }));
+            }

            // Clean up temporary image files if any
            if (geminiProcess.tempImagePaths && geminiProcess.tempImagePaths.length > 0) {
@@ -566,6 +574,10 @@ async function spawnGemini(command, options = {}, ws) {

            const errorSessionId = typeof ws.getSessionId === 'function' ? ws.getSessionId() : finalSessionId;
            ws.send(createNormalizedMessage({ kind: 'error', content: errorContent, sessionId: errorSessionId, provider: 'gemini' }));
+            if (!completeSent && !geminiProcess.aborted) {
+                completeSent = true;
+                ws.send(createCompleteMessage({ provider: 'gemini', sessionId: errorSessionId, exitCode: 1 }));
+            }
            notifyTerminalState({ error });

            reject(error);
@@ -590,6 +602,9 @@ function abortGeminiSession(sessionId) {

    if (geminiProc) {
        try {
+            // The abort handler sends the terminal complete (aborted: true);
+            // flag the process so its close handler does not emit a second one.
+            geminiProc.aborted = true;
            geminiProc.kill('SIGTERM');
            setTimeout(() => {
                if (activeGeminiProcesses.has(processKey)) {
--- a/server/index.js
+++ b/server/index.js
@@ -22,35 +22,24 @@ 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 {
@@ -72,6 +61,12 @@ import userRoutes from './routes/user.js';
 import geminiRoutes from './routes/gemini.js';
 import pluginsRoutes from './routes/plugins.js';
 import providerRoutes from './modules/providers/provider.routes.js';
+import browserUseRoutes from './modules/browser-use/browser-use.routes.js';
+import browserUseMcpRoutes from './modules/browser-use/browser-use-mcp.routes.js';
+import { browserUseService } from './modules/browser-use/browser-use.service.js';
+import computerUseRoutes from './modules/computer-use/computer-use.routes.js';
+import computerUseMcpRoutes from './modules/computer-use/computer-use-mcp.routes.js';
+import { computerUseService } from './modules/computer-use/computer-use.service.js';
 import { startEnabledPluginServers, stopAllPlugins, getPluginPort } from './utils/plugin-process-manager.js';
 import { initializeDatabase, projectsDb, sessionsDb } from './modules/database/index.js';
 import { configureWebPush } from './services/vapid-keys.js';
@@ -105,32 +100,35 @@ const wss = createWebSocketServer(server, {
        authenticateWebSocket,
    },
    chat: {
-        queryClaudeSDK,
-        spawnCursor,
-        queryCodex,
-        spawnGemini,
-        spawnOpenCode,
-        abortClaudeSDKSession,
-        abortCursorSession,
-        abortCodexSession,
-        abortGeminiSession,
-        abortOpenCodeSession,
+        spawnFns: {
+            claude: queryClaudeSDK,
+            cursor: spawnCursor,
+            codex: queryCodex,
+            gemini: spawnGemini,
+            opencode: spawnOpenCode,
+        },
+        abortFns: {
+            claude: abortClaudeSDKSession,
+            cursor: abortCursorSession,
+            codex: abortCodexSession,
+            gemini: abortGeminiSession,
+            opencode: abortOpenCodeSession,
+        },
        resolveToolApproval,
-        isClaudeSDKSessionActive,
-        isCursorSessionActive,
-        isCodexSessionActive,
-        isGeminiSessionActive,
-        isOpenCodeSessionActive,
-        reconnectSessionWriter,
        getPendingApprovalsForSession,
-        getActiveClaudeSDKSessions,
-        getActiveCursorSessions,
-        getActiveCodexSessions,
-        getActiveGeminiSessions,
-        getActiveOpenCodeSessions,
    },
    shell: {
-        getSessionById: (sessionId) => sessionManager.getSession(sessionId),
+        resolveProviderSessionId: (sessionId, provider) => {
+            const dbSession = sessionsDb.getSessionById(sessionId);
+            const legacyGeminiSession =
+                provider === 'gemini' ? sessionManager.getSession(sessionId) : null;
+
+            if (dbSession) {
+                return dbSession.provider_session_id ?? legacyGeminiSession?.cliSessionId ?? null;
+            }
+
+            return legacyGeminiSession?.cliSessionId;
+        },
        stripAnsiSequences,
        normalizeDetectedUrl,
        extractUrlsFromText,
@@ -201,6 +199,18 @@ app.use('/api/gemini', authenticateToken, geminiRoutes);
 // Plugins API Routes (protected)
 app.use('/api/plugins', authenticateToken, pluginsRoutes);

+// Browser MCP bridge API (local token protected)
+app.use('/api/browser-use-mcp', browserUseMcpRoutes);
+
+// Browser API Routes (protected)
+app.use('/api/browser-use', authenticateToken, browserUseRoutes);
+
+// Computer Use MCP bridge API (local token protected)
+app.use('/api/computer-use-mcp', computerUseMcpRoutes);
+
+// Computer Use API Routes (protected)
+app.use('/api/computer-use', authenticateToken, computerUseRoutes);
+
 // Unified provider MCP routes (protected)
 app.use('/api/providers', authenticateToken, providerRoutes);

@@ -1143,7 +1153,6 @@ app.post('/api/projects/:projectId/upload-images', authenticateToken, async (req
 app.get('/api/projects/:projectId/sessions/:sessionId/token-usage', authenticateToken, async (req, res) => {
    try {
        const { projectId, sessionId } = req.params;
-        const { provider = 'claude' } = req.query;
        const homeDir = os.homedir();

        // Allow only safe characters in sessionId
@@ -1152,6 +1161,18 @@ app.get('/api/projects/:projectId/sessions/:sessionId/token-usage', authenticate
            return res.status(400).json({ error: 'Invalid sessionId' });
        }

+        // Provider artifacts on disk (JSONL file names, OpenCode sqlite rows)
+        // are keyed by the provider-native session id, while the caller sends
+        // the app-facing id. Resolve provider and id mapping from the indexed
+        // session row so the frontend does not choose provider-specific paths.
+        const sessionRow = sessionsDb.getSessionById(safeSessionId);
+        if (!sessionRow) {
+            return res.status(404).json({ error: 'Session not found', sessionId: safeSessionId });
+        }
+
+        const provider = sessionRow.provider || 'claude';
+        const providerNativeSessionId = sessionRow?.provider_session_id || safeSessionId;
+
        // Handle Cursor sessions - they use SQLite and don't have token usage info
        if (provider === 'cursor') {
            return res.json({
@@ -1252,7 +1273,7 @@ app.get('/api/projects/:projectId/sessions/:sessionId/token-usage', authenticate
                        tokens_cache_write AS cacheWriteTokens
                    FROM session
                    WHERE id = ?
-                `).get(safeSessionId);
+                `).get(providerNativeSessionId);

                if (!row) {
                    return res.status(404).json({ error: 'OpenCode session not found', sessionId: safeSessionId });
@@ -1293,7 +1314,7 @@ app.get('/api/projects/:projectId/sessions/:sessionId/token-usage', authenticate
                        if (entry.isDirectory()) {
                            const found = await findSessionFile(fullPath);
                            if (found) return found;
-                        } else if (entry.name.includes(safeSessionId) && entry.name.endsWith('.jsonl')) {
+                        } else if (entry.name.includes(providerNativeSessionId) && entry.name.endsWith('.jsonl')) {
                            return fullPath;
                        }
                    }
@@ -1377,12 +1398,19 @@ app.get('/api/projects/:projectId/sessions/:sessionId/token-usage', authenticate
        const encodedPath = projectPath.replace(/[^a-zA-Z0-9-]/g, '-');
        const projectDir = path.join(homeDir, '.claude', 'projects', encodedPath);

-        const jsonlPath = path.join(projectDir, `${safeSessionId}.jsonl`);
+        // Prefer the indexed transcript path (already produced by the trusted
+        // session synchronizer); fall back to the conventional location
+        // derived from the provider-native session id.
+        let jsonlPath = sessionRow?.jsonl_path;
+        if (!jsonlPath) {
+            jsonlPath = path.join(projectDir, `${providerNativeSessionId}.jsonl`);

-        // Constrain to projectDir
-        const rel = path.relative(path.resolve(projectDir), path.resolve(jsonlPath));
-        if (rel.startsWith('..') || path.isAbsolute(rel)) {
-            return res.status(400).json({ error: 'Invalid path' });
+            // Constrain the constructed path to projectDir (the id is
+            // caller-influenced in this fallback branch).
+            const rel = path.relative(path.resolve(projectDir), path.resolve(jsonlPath));
+            if (rel.startsWith('..') || path.isAbsolute(rel)) {
+                return res.status(400).json({ error: 'Invalid path' });
+            }
        }

        // Read and parse the JSONL file
@@ -1646,6 +1674,40 @@ const SERVER_PORT = process.env.SERVER_PORT || 3001;
 const HOST = process.env.HOST || '0.0.0.0';
 const DISPLAY_HOST = getConnectableHost(HOST);
 const VITE_PORT = process.env.VITE_PORT || 5173;
+const LOCAL_SERVER_MARKER_PATH = path.join(os.homedir(), '.cloudcli', 'local-server.json');
+
+async function writeLocalServerMarker() {
+    const marker = {
+        pid: process.pid,
+        host: HOST,
+        port: Number.parseInt(String(SERVER_PORT), 10),
+        url: `http://${DISPLAY_HOST}:${SERVER_PORT}`,
+        installMode,
+        appRoot: APP_ROOT,
+        updatedAt: new Date().toISOString(),
+    };
+
+    await fsPromises.mkdir(path.dirname(LOCAL_SERVER_MARKER_PATH), { recursive: true });
+    await fsPromises.writeFile(LOCAL_SERVER_MARKER_PATH, JSON.stringify(marker, null, 2), 'utf8');
+}
+
+async function removeLocalServerMarker() {
+    try {
+        const raw = await fsPromises.readFile(LOCAL_SERVER_MARKER_PATH, 'utf8');
+        const marker = JSON.parse(raw);
+        if (marker.pid && marker.pid !== process.pid) return;
+    } catch (error) {
+        if (error.code === 'ENOENT') return;
+    }
+
+    try {
+        await fsPromises.unlink(LOCAL_SERVER_MARKER_PATH);
+    } catch (error) {
+        if (error.code !== 'ENOENT') {
+            console.warn('[WARN] Could not remove local server marker:', error.message);
+        }
+    }
+}

 // Initialize database and start server
 async function startServer() {
@@ -1672,6 +1734,9 @@ async function startServer() {
   
        server.listen(SERVER_PORT, HOST, async () => {
            const appInstallPath = APP_ROOT;
+            await writeLocalServerMarker().catch((error) => {
+                console.warn('[WARN] Could not write local server marker:', error.message);
+            });

            console.log('');
            console.log(c.dim('═'.repeat(63)));
@@ -1694,12 +1759,31 @@ async function startServer() {

        await closeSessionsWatcher();
        // Clean up plugin processes on shutdown
-        const shutdownPlugins = async () => {
-            await stopAllPlugins();
+        const shutdownRuntimeServices = async () => {
+            try {
+                await browserUseService.stopAllSessions();
+            } catch (err) {
+                console.error('[Browser] Error stopping sessions during shutdown:', err?.message || err);
+            }
+            try {
+                await computerUseService.stopAllSessions();
+            } catch (err) {
+                console.error('[Computer Use] Error stopping sessions during shutdown:', err?.message || err);
+            }
+            try {
+                await stopAllPlugins();
+            } catch (err) {
+                console.error('[Plugins] Error stopping plugins during shutdown:', err?.message || err);
+            }
+            try {
+                await removeLocalServerMarker();
+            } catch (err) {
+                console.error('[Local Server] Error removing server marker during shutdown:', err?.message || err);
+            }
            process.exit(0);
        };
-        process.on('SIGTERM', () => void shutdownPlugins());
-        process.on('SIGINT', () => void shutdownPlugins());
+        process.on('SIGTERM', () => void shutdownRuntimeServices());
+        process.on('SIGINT', () => void shutdownRuntimeServices());
    } catch (error) {
        console.error('[ERROR] Failed to start server:', error);
        process.exit(1);
--- a/server/modules/browser-use/browser-use-mcp.routes.ts
+++ b/server/modules/browser-use/browser-use-mcp.routes.ts
@@ -0,0 +1,120 @@
+import express from 'express';
+
+import { browserUseService } from '@/modules/browser-use/browser-use.service.js';
+
+const router = express.Router();
+
+function readBearerToken(header: unknown): string | null {
+  if (typeof header !== 'string') {
+    return null;
+  }
+  const match = /^Bearer\s+(\S.*)$/i.exec(header.trim());
+  return match?.[1]?.trim() || null;
+}
+
+router.use((req, res, next) => {
+  const expected = browserUseService.getMcpToken();
+  const token = readBearerToken(req.headers.authorization) || String(req.headers['x-browser-use-mcp-token'] || '');
+  if (!token || token !== expected) {
+    res.status(401).json({ success: false, error: 'Invalid Browser MCP token.' });
+    return;
+  }
+  next();
+});
+
+router.post('/tools/:toolName', async (req, res) => {
+  try {
+    const input = (req.body && typeof req.body === 'object' ? req.body : {}) as Record<string, unknown>;
+    const sessionId = typeof input.sessionId === 'string' ? input.sessionId : '';
+    const toolName = req.params.toolName;
+    let result: unknown;
+
+    switch (toolName) {
+      case 'browser_create_session':
+        result = await browserUseService.createAgentSession({
+          profileName: typeof input.profileName === 'string' ? input.profileName : null,
+        });
+        break;
+      case 'browser_list_sessions':
+        result = await browserUseService.listAgentSessions();
+        break;
+      case 'browser_snapshot':
+      case 'browser_take_screenshot':
+        result = await browserUseService.agentSnapshot(sessionId);
+        break;
+      case 'browser_navigate':
+        result = await browserUseService.agentNavigate(sessionId, String(input.url || ''));
+        break;
+      case 'browser_click':
+        result = await browserUseService.agentClick(sessionId, {
+          selector: typeof input.selector === 'string' ? input.selector : undefined,
+          text: typeof input.text === 'string' ? input.text : undefined,
+          x: typeof input.x === 'number' ? input.x : undefined,
+          y: typeof input.y === 'number' ? input.y : undefined,
+        });
+        break;
+      case 'browser_type':
+        result = await browserUseService.agentType(sessionId, {
+          selector: typeof input.selector === 'string' ? input.selector : undefined,
+          text: String(input.text || ''),
+          submit: input.submit === true,
+        });
+        break;
+      case 'browser_fill_form':
+        result = await browserUseService.agentFillForm(
+          sessionId,
+          Array.isArray(input.fields)
+            ? input.fields.map((field) => {
+              const record = field as Record<string, unknown>;
+              return {
+                selector: String(record.selector || ''),
+                value: String(record.value || ''),
+              };
+            })
+            : [],
+        );
+        break;
+      case 'browser_press_key':
+        result = await browserUseService.agentPressKey(sessionId, String(input.key || ''));
+        break;
+      case 'browser_select_option':
+        result = await browserUseService.agentSelectOption(
+          sessionId,
+          String(input.selector || ''),
+          Array.isArray(input.values) ? input.values.filter((value): value is string => typeof value === 'string') : [],
+        );
+        break;
+      case 'browser_wait_for':
+        result = await browserUseService.agentWaitFor(sessionId, {
+          text: typeof input.text === 'string' ? input.text : undefined,
+          url: typeof input.url === 'string' ? input.url : undefined,
+          timeoutMs: typeof input.timeoutMs === 'number' ? input.timeoutMs : undefined,
+        });
+        break;
+      case 'browser_tabs':
+        result = await browserUseService.agentTabs(sessionId, {
+          action: input.action === 'new' || input.action === 'select' || input.action === 'close' || input.action === 'list'
+            ? input.action
+            : undefined,
+          index: typeof input.index === 'number' ? input.index : undefined,
+          url: typeof input.url === 'string' ? input.url : undefined,
+        });
+        break;
+      case 'browser_close_session':
+        result = await browserUseService.agentStopSession(sessionId);
+        break;
+      default:
+        res.status(404).json({ success: false, error: `Unknown Browser MCP tool "${toolName}".` });
+        return;
+    }
+
+    res.json({ success: true, data: result });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Browser MCP tool failed.',
+    });
+  }
+});
+
+export default router;
--- a/server/modules/browser-use/browser-use.routes.ts
+++ b/server/modules/browser-use/browser-use.routes.ts
@@ -0,0 +1,96 @@
+import express from 'express';
+
+import { browserUseService } from '@/modules/browser-use/browser-use.service.js';
+
+const router = express.Router();
+
+function readParam(value: string | string[] | undefined): string {
+  return Array.isArray(value) ? value[0] || '' : value || '';
+}
+
+router.get('/status', async (_req, res) => {
+  try {
+    res.json({ success: true, data: await browserUseService.getStatus() });
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to load Browser status.',
+    });
+  }
+});
+
+router.get('/settings', async (_req, res) => {
+  try {
+    res.json({ success: true, data: { settings: await browserUseService.getSettings() } });
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to load Browser settings.',
+    });
+  }
+});
+
+router.put('/settings', async (req, res) => {
+  try {
+    const settings = await browserUseService.updateSettings(req.body || {});
+    res.json({ success: true, data: { settings } });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to save Browser settings.',
+    });
+  }
+});
+
+router.post('/runtime/install', async (_req, res) => {
+  try {
+    const result = await browserUseService.installRuntime();
+    res.status(result.success ? 200 : 500).json({
+      success: result.success,
+      data: result,
+      error: result.success ? undefined : result.message,
+    });
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to install Browser runtime.',
+    });
+  }
+});
+
+router.get('/sessions', async (_req, res) => {
+  try {
+    res.json({ success: true, data: { sessions: await browserUseService.listSessions() } });
+  } catch (error) {
+    res.status(401).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to list browser sessions.',
+    });
+  }
+});
+
+router.post('/sessions/:sessionId/stop', async (req, res) => {
+  try {
+    const result = await browserUseService.stopSession(readParam(req.params.sessionId));
+    res.json({ success: true, data: result });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to stop browser session.',
+    });
+  }
+});
+
+router.delete('/sessions/:sessionId', async (req, res) => {
+  try {
+    const result = await browserUseService.deleteSession(readParam(req.params.sessionId));
+    res.json({ success: true, data: result });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to delete browser session.',
+    });
+  }
+});
+
+export default router;
--- a/server/modules/browser-use/browser-use.service.ts
+++ b/server/modules/browser-use/browser-use.service.ts
@@ -0,0 +1,836 @@
+import { createRequire } from 'node:module';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { appConfigDb } from '@/modules/database/index.js';
+import { providerMcpService } from '@/modules/providers/index.js';
+import { getModuleDir } from '@/utils/runtime-paths.js';
+
+const require = createRequire(import.meta.url);
+const __dirname = getModuleDir(import.meta.url);
+const IS_PLATFORM = process.env.VITE_IS_PLATFORM === 'true';
+const MAX_SESSIONS_PER_OWNER = Number.parseInt(process.env.CLOUDCLI_BROWSER_USE_MAX_SESSIONS_PER_OWNER || '3', 10);
+const SESSION_TTL_MS = Number.parseInt(process.env.CLOUDCLI_BROWSER_USE_SESSION_TTL_MS || String(30 * 60 * 1000), 10);
+const BROWSER_USE_SETTINGS_KEY = 'browser_use_settings';
+const BROWSER_USE_MCP_TOKEN_KEY = 'browser_use_mcp_token';
+
+type BrowserUseRuntime = 'cloud' | 'local';
+type BrowserUseSessionStatus = 'ready' | 'stopped' | 'unavailable';
+
+type BrowserUseSession = {
+  id: string;
+  ownerId: string;
+  createdBy: 'agent';
+  runtime: BrowserUseRuntime;
+  status: BrowserUseSessionStatus;
+  url: string | null;
+  title: string | null;
+  screenshotDataUrl: string | null;
+  createdAt: string;
+  updatedAt: string;
+  lastAction: string | null;
+  message: string | null;
+  profileName: string | null;
+  viewport: {
+    width: number;
+    height: number;
+  } | null;
+  cursor: {
+    x: number;
+    y: number;
+    actor: 'agent';
+  } | null;
+};
+
+type PublicBrowserUseSession = Omit<BrowserUseSession, 'ownerId'>;
+
+type RuntimeHandle = {
+  browser?: any;
+  context?: any;
+  page?: any;
+};
+
+type BrowserUseSettings = {
+  enabled: boolean;
+};
+
+type RuntimeReadiness = {
+  playwright: any | null;
+  playwrightInstalled: boolean;
+  chromiumInstalled: boolean;
+  chromiumExecutablePath: string | null;
+  installInProgress: boolean;
+  installMessage: string | null;
+};
+
+type RuntimeProbe = Omit<RuntimeReadiness, 'installInProgress' | 'installMessage'>;
+
+const sessions = new Map<string, BrowserUseSession>();
+const handles = new Map<string, RuntimeHandle>();
+let installPromise: Promise<{ success: boolean; message: string }> | null = null;
+let lastInstallMessage: string | null = null;
+let runtimeProbeCache: { value: RuntimeProbe; updatedAt: number } | null = null;
+
+const DEFAULT_SETTINGS: BrowserUseSettings = {
+  enabled: false,
+};
+const AGENT_OWNER_ID = 'agent';
+const PROFILE_ROOT = path.join(os.homedir(), '.cloudcli', 'browser-use', 'profiles');
+const MCP_SERVER_NAME = 'cloudcli-browser';
+const LEGACY_MCP_SERVER_NAMES = ['cloudcli-browser-use'];
+const RUNTIME_READINESS_CACHE_TTL_MS = 30_000;
+
+function getRuntime(): BrowserUseRuntime {
+  return IS_PLATFORM ? 'cloud' : 'local';
+}
+
+function readSettings(): BrowserUseSettings {
+  try {
+    const raw = appConfigDb.get(BROWSER_USE_SETTINGS_KEY);
+    if (!raw) {
+      return DEFAULT_SETTINGS;
+    }
+
+    const parsed = JSON.parse(raw) as Partial<BrowserUseSettings>;
+    return {
+      enabled: parsed.enabled === true,
+    };
+  } catch (error: any) {
+    console.warn('[Browser] Failed to read settings:', error?.message || error);
+    return DEFAULT_SETTINGS;
+  }
+}
+
+function writeSettings(settings: BrowserUseSettings): BrowserUseSettings {
+  const normalized = {
+    enabled: settings.enabled === true,
+  };
+
+  appConfigDb.set(BROWSER_USE_SETTINGS_KEY, JSON.stringify(normalized));
+  return normalized;
+}
+
+function getOrCreateMcpToken(): string {
+  const existing = appConfigDb.get(BROWSER_USE_MCP_TOKEN_KEY);
+  if (existing) {
+    return existing;
+  }
+  const token = randomBytes(32).toString('hex');
+  appConfigDb.set(BROWSER_USE_MCP_TOKEN_KEY, token);
+  return token;
+}
+
+function getSetupMessage(settings: BrowserUseSettings, readiness: RuntimeReadiness): string {
+  if (!settings.enabled) {
+    return 'Browser is disabled in settings.';
+  }
+
+  if (!readiness.playwrightInstalled) {
+    return 'Install Playwright and Chromium to use browser sessions.';
+  }
+
+  if (!readiness.chromiumInstalled) {
+    return 'Playwright is installed, but Chromium is missing. Install the Chromium runtime to continue.';
+  }
+
+  return readiness.installMessage || 'Browser runtime is not ready.';
+}
+
+function getPlaywright(): any | null {
+  try {
+    return require('playwright');
+  } catch {
+    return null;
+  }
+}
+
+function getMcpCommand(): { command: string; args: string[] } {
+  const serverDir = path.resolve(__dirname, '..', '..');
+  const mcpScriptPath = path.join(serverDir, 'browser-use-mcp.js');
+  if (fs.existsSync(mcpScriptPath)) {
+    return {
+      command: process.execPath,
+      args: [mcpScriptPath],
+    };
+  }
+
+  return {
+    command: 'cloudcli',
+    args: ['browser-use-mcp'],
+  };
+}
+
+function getMcpApiUrl(): string {
+  const port = process.env.SERVER_PORT || process.env.PORT || '3001';
+  return `http://127.0.0.1:${port}/api/browser-use-mcp`;
+}
+
+async function removeMcpServerFromAllProviders(name: string) {
+  const results = await providerMcpService.removeMcpServerFromAllProviders({
+    name,
+    scope: 'user',
+  });
+  return results.map((result) => ({ ...result, name }));
+}
+
+function normalizeProfileName(profileName?: string | null): string | null {
+  const normalized = String(profileName || '').trim();
+  if (!normalized) {
+    return null;
+  }
+
+  return normalized.slice(0, 80);
+}
+
+function getProfilePath(profileName: string): string {
+  const safeName = profileName
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80) || 'default';
+  return path.join(PROFILE_ROOT, safeName);
+}
+
+function probeRuntime(): RuntimeProbe {
+  const playwright = getPlaywright();
+  const readiness: RuntimeProbe = {
+    playwright,
+    playwrightInstalled: Boolean(playwright),
+    chromiumInstalled: false,
+    chromiumExecutablePath: null,
+  };
+
+  if (!playwright) {
+    return readiness;
+  }
+
+  try {
+    const executablePath = playwright.chromium.executablePath();
+    readiness.chromiumExecutablePath = executablePath;
+    readiness.chromiumInstalled = Boolean(executablePath && fs.existsSync(executablePath));
+  } catch {
+    readiness.chromiumInstalled = false;
+  }
+
+  return readiness;
+}
+
+function getRuntimeReadiness(options: { force?: boolean } = {}): RuntimeReadiness {
+  const now = Date.now();
+  const cachedProbe = runtimeProbeCache;
+  const canUseCache = !options.force
+    && !installPromise
+    && cachedProbe
+    && now - cachedProbe.updatedAt < RUNTIME_READINESS_CACHE_TTL_MS;
+  const probe = canUseCache ? cachedProbe.value : probeRuntime();
+
+  if (!canUseCache && !installPromise) {
+    runtimeProbeCache = { value: probe, updatedAt: now };
+  }
+
+  return {
+    ...probe,
+    installInProgress: Boolean(installPromise),
+    installMessage: lastInstallMessage,
+  };
+}
+
+const INSTALL_COMMAND_TIMEOUT_MS = Number.parseInt(
+  process.env.CLOUDCLI_BROWSER_USE_INSTALL_TIMEOUT_MS || String(10 * 60 * 1000),
+  10,
+);
+
+function runCommand(command: string, args: string[]): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: process.cwd(),
+      env: process.env,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const output: string[] = [];
+    let settled = false;
+    const finish = (fn: () => void) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      fn();
+    };
+
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL');
+      finish(() => reject(new Error(
+        `${command} ${args.join(' ')} timed out after ${INSTALL_COMMAND_TIMEOUT_MS}ms.`,
+      )));
+    }, INSTALL_COMMAND_TIMEOUT_MS);
+    timer.unref?.();
+
+    child.stdout.on('data', (chunk) => output.push(String(chunk)));
+    child.stderr.on('data', (chunk) => output.push(String(chunk)));
+    child.on('error', (error) => finish(() => reject(error)));
+    child.on('close', (code) => finish(() => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+
+      reject(new Error(output.join('').trim() || `${command} ${args.join(' ')} exited with code ${code}`));
+    }));
+  });
+}
+
+function formatInstallError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.includes('sudo') && message.includes('password')) {
+    return 'Installing Chromium system dependencies requires administrator privileges. Run `npx playwright install-deps chromium` on the machine where CloudCLI runs, then try again.';
+  }
+  return message || 'Failed to install Browser runtime.';
+}
+
+async function installRuntime(): Promise<{ success: boolean; message: string }> {
+  if (installPromise) {
+    return installPromise;
+  }
+
+  const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  runtimeProbeCache = null;
+  installPromise = (async () => {
+    try {
+      lastInstallMessage = 'Installing Playwright package...';
+      await runCommand(npmCommand, ['install', '--no-save', '--no-package-lock', 'playwright']);
+
+      if (process.platform === 'linux') {
+        lastInstallMessage = 'Installing Chromium system dependencies...';
+        await runCommand(npmCommand, ['exec', '--', 'playwright', 'install-deps', 'chromium']);
+      }
+
+      lastInstallMessage = 'Installing Chromium runtime...';
+      await runCommand(npmCommand, ['exec', '--', 'playwright', 'install', 'chromium']);
+
+      lastInstallMessage = 'Browser runtime installed.';
+      return { success: true, message: lastInstallMessage };
+    } catch (error) {
+      lastInstallMessage = formatInstallError(error);
+      return { success: false, message: lastInstallMessage };
+    }
+  })();
+
+  try {
+    return await installPromise;
+  } finally {
+    installPromise = null;
+    runtimeProbeCache = null;
+  }
+}
+
+function normalizeUrl(rawUrl: string): string {
+  const trimmed = rawUrl.trim();
+  if (!trimmed) {
+    throw new Error('URL is required.');
+  }
+
+  const withProtocol = /^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(trimmed)
+    ? trimmed
+    : `https://${trimmed}`;
+  const parsed = new URL(withProtocol);
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error('Only http and https URLs are supported.');
+  }
+
+  return parsed.toString();
+}
+
+function publicSession(session: BrowserUseSession): PublicBrowserUseSession {
+  const { ownerId: _ownerId, ...publicFields } = session;
+  return publicFields;
+}
+
+function ownerSessions(ownerId: string): BrowserUseSession[] {
+  return [...sessions.values()].filter((session) => session.ownerId === ownerId);
+}
+
+async function closeHandle(sessionId: string): Promise<void> {
+  const handle = handles.get(sessionId);
+  handles.delete(sessionId);
+  await handle?.context?.close?.().catch(() => undefined);
+  await handle?.browser?.close().catch(() => undefined);
+}
+
+async function expireStaleSessions(now = Date.now()): Promise<void> {
+  await Promise.all([...sessions.values()].map(async (session) => {
+    if (session.status !== 'ready') {
+      return;
+    }
+
+    const updatedAt = Date.parse(session.updatedAt);
+    if (!Number.isFinite(updatedAt) || now - updatedAt <= SESSION_TTL_MS) {
+      return;
+    }
+
+    await closeHandle(session.id);
+    session.status = 'stopped';
+    session.updatedAt = new Date(now).toISOString();
+    session.lastAction = 'expire';
+    session.message = 'Browser session expired after inactivity.';
+  }));
+}
+
+async function captureSession(session: BrowserUseSession, page: any): Promise<void> {
+  const screenshot = await page.screenshot({ type: 'jpeg', quality: 72, fullPage: false });
+  session.screenshotDataUrl = `data:image/jpeg;base64,${Buffer.from(screenshot).toString('base64')}`;
+  session.title = await page.title().catch(() => null);
+  session.url = page.url() || session.url;
+  session.viewport = page.viewportSize?.() || session.viewport;
+  session.updatedAt = new Date().toISOString();
+}
+
+async function getActionPoint(page: any, input: { selector?: string; text?: string; x?: number; y?: number }) {
+  if (typeof input.x === 'number' && typeof input.y === 'number') {
+    return { x: input.x, y: input.y };
+  }
+
+  const locator = input.selector
+    ? page.locator(input.selector).first()
+    : input.text
+      ? page.getByText(input.text, { exact: false }).first()
+      : null;
+
+  if (!locator) {
+    return null;
+  }
+
+  const box = await locator.boundingBox().catch(() => null);
+  if (!box) {
+    return null;
+  }
+
+  return {
+    x: Math.round(box.x + box.width / 2),
+    y: Math.round(box.y + box.height / 2),
+  };
+}
+
+export const browserUseService = {
+  async getSettings() {
+    return readSettings();
+  },
+
+  async updateSettings(settings: Partial<BrowserUseSettings>) {
+    const current = readSettings();
+    const nextSettings = {
+      enabled: typeof settings.enabled === 'boolean' ? settings.enabled : current.enabled,
+    };
+
+    const next = writeSettings(nextSettings);
+    if (next.enabled) {
+      await this.registerAgentMcp();
+    } else if (current.enabled) {
+      await this.unregisterAgentMcp();
+      await this.stopAllSessions();
+    }
+    return next;
+  },
+
+  async getStatus() {
+    const settings = readSettings();
+    const readiness = getRuntimeReadiness();
+    const available = settings.enabled && readiness.playwrightInstalled && readiness.chromiumInstalled;
+
+    return {
+      enabled: settings.enabled,
+      runtime: getRuntime(),
+      available,
+      playwrightInstalled: readiness.playwrightInstalled,
+      chromiumInstalled: readiness.chromiumInstalled,
+      installInProgress: readiness.installInProgress,
+      sessionCount: sessions.size,
+      message: available
+        ? 'Browser runtime is available.'
+        : getSetupMessage(settings, readiness),
+    };
+  },
+
+  async registerAgentMcp() {
+    const { command, args } = getMcpCommand();
+    await Promise.all(LEGACY_MCP_SERVER_NAMES.map((name) => removeMcpServerFromAllProviders(name)));
+    const results = await providerMcpService.addMcpServerToAllProviders({
+      name: MCP_SERVER_NAME,
+      scope: 'user',
+      transport: 'stdio',
+      command,
+      args,
+      env: {
+        CLOUDCLI_BROWSER_USE_MCP_TOKEN: getOrCreateMcpToken(),
+        CLOUDCLI_BROWSER_USE_API_URL: getMcpApiUrl(),
+      },
+    });
+    return { name: MCP_SERVER_NAME, command, args, results };
+  },
+
+  getMcpToken() {
+    return getOrCreateMcpToken();
+  },
+
+  async unregisterAgentMcp() {
+    const results = (await Promise.all(
+      [MCP_SERVER_NAME, ...LEGACY_MCP_SERVER_NAMES].map((name) => removeMcpServerFromAllProviders(name)),
+    )).flat();
+    return { name: MCP_SERVER_NAME, results };
+  },
+
+  async installRuntime() {
+    const result = await installRuntime();
+    return {
+      ...result,
+      status: await this.getStatus(),
+    };
+  },
+
+  async listSessions() {
+    await expireStaleSessions();
+    return [...sessions.values()]
+      .filter((session) => session.ownerId === AGENT_OWNER_ID)
+      .map(publicSession);
+  },
+
+  async createAgentSession(options?: { profileName?: string | null }) {
+    const settings = readSettings();
+    if (!settings.enabled) {
+      throw new Error('Browser agent tools are disabled.');
+    }
+
+    await expireStaleSessions();
+    const profileName = normalizeProfileName(options?.profileName);
+
+    const now = new Date().toISOString();
+    const session: BrowserUseSession = {
+      id: randomUUID(),
+      ownerId: AGENT_OWNER_ID,
+      createdBy: 'agent',
+      runtime: getRuntime(),
+      status: 'unavailable',
+      url: null,
+      title: null,
+      screenshotDataUrl: null,
+      createdAt: now,
+      updatedAt: now,
+      lastAction: 'create',
+      message: null,
+      profileName,
+      viewport: { width: 1440, height: 900 },
+      cursor: null,
+    };
+
+    const activeOwnerSessions = ownerSessions(AGENT_OWNER_ID).filter((item) => item.status === 'ready');
+    if (activeOwnerSessions.length >= MAX_SESSIONS_PER_OWNER) {
+      throw new Error(`Browser is limited to ${MAX_SESSIONS_PER_OWNER} active agent sessions.`);
+    }
+
+    const readiness = getRuntimeReadiness();
+    if (!settings.enabled || !readiness.playwrightInstalled || !readiness.chromiumInstalled || !readiness.playwright) {
+      session.message = getSetupMessage(settings, readiness);
+      sessions.set(session.id, session);
+      return publicSession(session);
+    }
+
+    let browser: any | undefined;
+    let context: any | undefined;
+    let page: any;
+    const launchOptions = {
+      headless: true,
+      args: ['--disable-dev-shm-usage'],
+    };
+    const contextOptions = {
+      viewport: { width: 1440, height: 900 },
+      serviceWorkers: 'block',
+    };
+
+    if (profileName) {
+      fs.mkdirSync(PROFILE_ROOT, { recursive: true });
+      context = await readiness.playwright.chromium.launchPersistentContext(getProfilePath(profileName), {
+        ...launchOptions,
+        ...contextOptions,
+      });
+      page = context.pages()[0] || await context.newPage();
+    } else {
+      browser = await readiness.playwright.chromium.launch(launchOptions);
+      context = await browser.newContext(contextOptions);
+      page = await context.newPage();
+    }
+    session.status = 'ready';
+    session.message = 'Browser session is ready.';
+    sessions.set(session.id, session);
+    handles.set(session.id, { browser, context, page });
+    await captureSession(session, page);
+    return publicSession(session);
+  },
+
+  async listAgentSessions() {
+    const settings = readSettings();
+    if (!settings.enabled) {
+      return [];
+    }
+    await expireStaleSessions();
+    return [...sessions.values()]
+      .filter((session) => session.ownerId === AGENT_OWNER_ID)
+      .map(publicSession);
+  },
+
+  async getAgentSession(sessionId: string) {
+    const settings = readSettings();
+    if (!settings.enabled) {
+      throw new Error('Browser agent tools are disabled.');
+    }
+    const session = sessions.get(sessionId);
+    if (!session || session.ownerId !== AGENT_OWNER_ID) {
+      throw new Error('Browser session not found.');
+    }
+    return session;
+  },
+
+  async agentNavigate(sessionId: string, rawUrl: string) {
+    await this.getAgentSession(sessionId);
+    await expireStaleSessions();
+
+    const session = sessions.get(sessionId);
+    if (!session || session.ownerId !== AGENT_OWNER_ID) {
+      throw new Error('Browser session not found.');
+    }
+
+    if (session.status !== 'ready') {
+      throw new Error(session.message || 'Browser session is not available.');
+    }
+
+    const handle = handles.get(sessionId);
+    if (!handle?.page) {
+      throw new Error('Browser runtime handle is not available.');
+    }
+
+    const url = normalizeUrl(rawUrl);
+    await handle.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
+    session.lastAction = `navigate:${url}`;
+    session.cursor = null;
+    await captureSession(session, handle.page);
+    return publicSession(session);
+  },
+
+  async agentSnapshot(sessionId: string) {
+    const session = await this.getAgentSession(sessionId);
+    const handle = handles.get(sessionId);
+    if (!handle?.page) {
+      throw new Error('Browser runtime handle is not available.');
+    }
+    await captureSession(session, handle.page);
+    const text = await handle.page.locator('body').innerText({ timeout: 5_000 }).catch(() => '');
+    return {
+      session: publicSession(session),
+      text: text.slice(0, 30_000),
+    };
+  },
+
+  async agentClick(sessionId: string, input: { selector?: string; text?: string; x?: number; y?: number }) {
+    const session = await this.getAgentSession(sessionId);
+    const handle = handles.get(sessionId);
+    if (!handle?.page) {
+      throw new Error('Browser runtime handle is not available.');
+    }
+    const point = await getActionPoint(handle.page, input);
+
+    if (input.selector) {
+      await handle.page.locator(input.selector).first().click({ timeout: 10_000 });
+    } else if (input.text) {
+      await handle.page.getByText(input.text, { exact: false }).first().click({ timeout: 10_000 });
+    } else if (typeof input.x === 'number' && typeof input.y === 'number') {
+      await handle.page.mouse.click(input.x, input.y);
+    } else {
+      throw new Error('Provide selector, text, or x/y coordinates.');
+    }
+
+    session.lastAction = 'click';
+    session.cursor = point ? { ...point, actor: 'agent' } : null;
+    await captureSession(session, handle.page);
+    return publicSession(session);
+  },
+
+  async agentType(sessionId: string, input: { selector?: string; text: string; submit?: boolean }) {
+    const session = await this.getAgentSession(sessionId);
+    const handle = handles.get(sessionId);
+    if (!handle?.page) {
+      throw new Error('Browser runtime handle is not available.');
+    }
+
+    if (input.selector) {
+      await handle.page.locator(input.selector).first().fill(input.text, { timeout: 10_000 });
+      session.cursor = await getActionPoint(handle.page, input).then((point) => (
+        point ? { ...point, actor: 'agent' as const } : null
+      ));
+    } else {
+      await handle.page.keyboard.type(input.text);
+    }
+    if (input.submit) {
+      await handle.page.keyboard.press('Enter');
+    }
+
+    session.lastAction = 'type';
+    await captureSession(session, handle.page);
+    return publicSession(session);
+  },
+
+  async agentFillForm(sessionId: string, fields: Array<{ selector: string; value: string }>) {
+    const session = await this.getAgentSession(sessionId);
+    const handle = handles.get(sessionId);
+    if (!handle?.page) {
+      throw new Error('Browser runtime handle is not available.');
+    }
+    for (const field of fields) {
+      await handle.page.locator(field.selector).first().fill(field.value, { timeout: 10_000 });
+    }
+    session.lastAction = 'fill_form';
+    if (fields[0]) {
+      session.cursor = await getActionPoint(handle.page, { selector: fields[0].selector }).then((point) => (
+        point ? { ...point, actor: 'agent' as const } : null
+      ));
+    }
+    await captureSession(session, handle.page);
+    return publicSession(session);
+  },
+
+  async agentPressKey(sessionId: string, key: string) {
+    const session = await this.getAgentSession(sessionId);
+    const handle = handles.get(sessionId);
+    if (!handle?.page) {
+      throw new Error('Browser runtime handle is not available.');
+    }
+    await handle.page.keyboard.press(key);
+    session.lastAction = `press_key:${key}`;
+    await captureSession(session, handle.page);
+    return publicSession(session);
+  },
+
+  async agentSelectOption(sessionId: string, selector: string, values: string[]) {
+    const session = await this.getAgentSession(sessionId);
+    const handle = handles.get(sessionId);
+    if (!handle?.page) {
+      throw new Error('Browser runtime handle is not available.');
+    }
+    await handle.page.locator(selector).first().selectOption(values, { timeout: 10_000 });
+    session.lastAction = 'select_option';
+    session.cursor = await getActionPoint(handle.page, { selector }).then((point) => (
+      point ? { ...point, actor: 'agent' as const } : null
+    ));
+    await captureSession(session, handle.page);
+    return publicSession(session);
+  },
+
+  async agentWaitFor(sessionId: string, input: { text?: string; url?: string; timeoutMs?: number }) {
+    const session = await this.getAgentSession(sessionId);
+    const handle = handles.get(sessionId);
+    if (!handle?.page) {
+      throw new Error('Browser runtime handle is not available.');
+    }
+    const timeout = Math.max(250, Math.min(input.timeoutMs || 5_000, 30_000));
+    if (input.text) {
+      await handle.page.getByText(input.text, { exact: false }).first().waitFor({ timeout });
+    } else if (input.url) {
+      await handle.page.waitForURL(input.url, { timeout });
+    } else {
+      await handle.page.waitForTimeout(timeout);
+    }
+    session.lastAction = 'wait_for';
+    await captureSession(session, handle.page);
+    return publicSession(session);
+  },
+
+  async agentTabs(sessionId: string, input: { action?: 'list' | 'new' | 'select' | 'close'; index?: number; url?: string }) {
+    const session = await this.getAgentSession(sessionId);
+    const handle = handles.get(sessionId);
+    if (!handle?.context || !handle?.page) {
+      throw new Error('Browser runtime handle is not available.');
+    }
+    const action = input.action || 'list';
+    if (action === 'new') {
+      const page = await handle.context.newPage();
+      handles.set(sessionId, { ...handle, page });
+      if (input.url) {
+        await this.agentNavigate(sessionId, input.url);
+      }
+    } else if (action === 'select') {
+      const page = handle.context.pages()[input.index || 0];
+      if (!page) {
+        throw new Error('Tab not found.');
+      }
+      handles.set(sessionId, { ...handle, page });
+    } else if (action === 'close') {
+      const pages = handle.context.pages();
+      const page = pages[input.index ?? pages.indexOf(handle.page)];
+      if (!page) {
+        throw new Error('Tab not found.');
+      }
+      await page.close();
+      handles.set(sessionId, { ...handle, page: handle.context.pages()[0] || await handle.context.newPage() });
+    }
+    const updatedHandle = handles.get(sessionId);
+    await captureSession(session, updatedHandle?.page || handle.page);
+    return {
+      session: publicSession(session),
+      tabs: handle.context.pages().map((page: any, index: number) => ({
+        index,
+        url: page.url(),
+        active: page === (updatedHandle?.page || handle.page),
+      })),
+    };
+  },
+
+  async stopSession(sessionId: string) {
+    const session = sessions.get(sessionId);
+    if (!session || session.ownerId !== AGENT_OWNER_ID) {
+      return { stopped: false };
+    }
+
+    await closeHandle(sessionId);
+
+    session.status = 'stopped';
+    session.updatedAt = new Date().toISOString();
+    session.lastAction = 'stop';
+    session.message = 'Browser session stopped. Create a new session to continue browsing.';
+    return { stopped: true, session: publicSession(session) };
+  },
+
+  async deleteSession(sessionId: string) {
+    const session = sessions.get(sessionId);
+    if (!session || session.ownerId !== AGENT_OWNER_ID) {
+      return { deleted: false };
+    }
+
+    await closeHandle(sessionId);
+    sessions.delete(sessionId);
+    return { deleted: true, sessionId };
+  },
+
+  async agentStopSession(sessionId: string) {
+    await this.getAgentSession(sessionId);
+    return this.stopSession(sessionId);
+  },
+
+  async stopAllSessions() {
+    await Promise.all([...sessions.keys()].map(async (sessionId) => {
+      await closeHandle(sessionId);
+      const session = sessions.get(sessionId);
+      if (session) {
+        session.status = 'stopped';
+        session.updatedAt = new Date().toISOString();
+        session.lastAction = 'shutdown';
+        session.message = 'Browser session stopped during server shutdown.';
+      }
+    }));
+  },
+};
+
+process.once('beforeExit', () => {
+  void browserUseService.stopAllSessions();
+});
--- a/server/modules/browser-use/tests/browser-use.service.test.ts
+++ b/server/modules/browser-use/tests/browser-use.service.test.ts
@@ -0,0 +1,10 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { browserUseService } from '@/modules/browser-use/browser-use.service.js';
+
+test('browser monitor list starts empty without agent sessions', async () => {
+  const sessions = await browserUseService.listSessions();
+
+  assert.deepEqual(sessions, []);
+});
--- a/server/modules/computer-use/computer-executor.ts
+++ b/server/modules/computer-use/computer-executor.ts
@@ -0,0 +1,242 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export type Point = { x: number; y: number };
+export type ClickButton = 'left' | 'right' | 'middle';
+export type ScrollDirection = 'up' | 'down' | 'left' | 'right';
+export type DisplaySize = { width: number; height: number };
+
+export type RuntimeReadiness = {
+  nut: any | null;
+  screenshot: any | null;
+  nutInstalled: boolean;
+  screenshotInstalled: boolean;
+};
+
+/**
+ * Coordinate space the executor reports/accepts. The screenshot pixel space is
+ * the canonical space agents and users address; it is mapped to the nut-js
+ * logical mouse space before any action runs.
+ */
+export type ExecutorTarget = {
+  displaySize: DisplaySize | null;
+};
+
+export function getNut(): any | null {
+  try {
+    return require('@nut-tree-fork/nut-js');
+  } catch {
+    return null;
+  }
+}
+
+export function getScreenshot(): any | null {
+  try {
+    const mod = require('screenshot-desktop');
+    return mod?.default || mod;
+  } catch {
+    return null;
+  }
+}
+
+export function getRuntimeReadiness(): RuntimeReadiness {
+  const nut = getNut();
+  const screenshot = getScreenshot();
+  return {
+    nut,
+    screenshot,
+    nutInstalled: Boolean(nut),
+    screenshotInstalled: typeof screenshot === 'function',
+  };
+}
+
+/** Reads the pixel dimensions from a PNG/JPEG buffer header without decoding it. */
+export function readImageSize(buffer: Buffer): DisplaySize | null {
+  // PNG: 8-byte signature, then IHDR chunk with width/height as big-endian uint32.
+  if (buffer.length >= 24 && buffer[0] === 0x89 && buffer[1] === 0x50) {
+    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+  }
+  // JPEG: scan for a Start-Of-Frame marker (0xFFC0..0xFFCF, excluding C4/C8/CC).
+  if (buffer.length >= 4 && buffer[0] === 0xff && buffer[1] === 0xd8) {
+    let offset = 2;
+    while (offset + 9 < buffer.length) {
+      if (buffer[offset] !== 0xff) {
+        offset += 1;
+        continue;
+      }
+      const marker = buffer[offset + 1];
+      if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+        return { height: buffer.readUInt16BE(offset + 5), width: buffer.readUInt16BE(offset + 7) };
+      }
+      offset += 2 + buffer.readUInt16BE(offset + 2);
+    }
+  }
+  return null;
+}
+
+export async function captureScreenshot(): Promise<{ dataUrl: string; size: DisplaySize | null }> {
+  const screenshot = getScreenshot();
+  if (typeof screenshot !== 'function') {
+    throw new Error('Computer Use runtime is not available.');
+  }
+  const buffer: Buffer = await screenshot({ format: 'png' });
+  return {
+    dataUrl: `data:image/png;base64,${buffer.toString('base64')}`,
+    size: readImageSize(buffer),
+  };
+}
+
+/** Returns the mouse coordinate space size (logical screen pixels). */
+export async function getMouseSpaceSize(): Promise<DisplaySize> {
+  const nut = getNut();
+  if (!nut) {
+    throw new Error('Computer Use runtime is not available.');
+  }
+  const width = await nut.screen.width();
+  const height = await nut.screen.height();
+  return { width, height };
+}
+
+/** Maps a point from screenshot/image space to the mouse coordinate space. */
+export async function toMouseSpace(target: ExecutorTarget, point: Point): Promise<Point> {
+  const mouseSize = await getMouseSpaceSize();
+  const image = target.displaySize || mouseSize;
+  const scaleX = image.width ? mouseSize.width / image.width : 1;
+  const scaleY = image.height ? mouseSize.height / image.height : 1;
+  return {
+    x: Math.round(point.x * scaleX),
+    y: Math.round(point.y * scaleY),
+  };
+}
+
+/** Maps a point from the mouse coordinate space back to screenshot/image space. */
+export function toImageSpace(target: ExecutorTarget, point: Point, mouseSize: DisplaySize): Point {
+  const image = target.displaySize || mouseSize;
+  const scaleX = mouseSize.width ? image.width / mouseSize.width : 1;
+  const scaleY = mouseSize.height ? image.height / mouseSize.height : 1;
+  return {
+    x: Math.round(point.x * scaleX),
+    y: Math.round(point.y * scaleY),
+  };
+}
+
+function nutButton(nut: any, button: ClickButton) {
+  if (button === 'right') return nut.Button.RIGHT;
+  if (button === 'middle') return nut.Button.MIDDLE;
+  return nut.Button.LEFT;
+}
+
+/** Maps a key name (xdotool-style, as Anthropic's computer tool emits) to a nut-js Key. */
+function nutKey(nut: any, token: string): any {
+  const map: Record<string, string> = {
+    return: 'Enter', enter: 'Enter', esc: 'Escape', escape: 'Escape', tab: 'Tab',
+    space: 'Space', backspace: 'Backspace', delete: 'Delete', del: 'Delete', insert: 'Insert',
+    up: 'Up', down: 'Down', left: 'Left', right: 'Right',
+    home: 'Home', end: 'End', pageup: 'PageUp', page_up: 'PageUp', pagedown: 'PageDown', page_down: 'PageDown',
+    ctrl: 'LeftControl', control: 'LeftControl', alt: 'LeftAlt', shift: 'LeftShift',
+    meta: 'LeftSuper', super: 'LeftSuper', cmd: 'LeftSuper', win: 'LeftSuper',
+    capslock: 'CapsLock',
+  };
+  const lower = token.toLowerCase();
+  if (map[lower]) {
+    return nut.Key[map[lower]];
+  }
+  if (/^f([1-9]|1[0-9]|2[0-4])$/.test(lower)) {
+    return nut.Key[`F${lower.slice(1)}`];
+  }
+  if (token.length === 1) {
+    const upper = token.toUpperCase();
+    if (nut.Key[upper] !== undefined) {
+      return nut.Key[upper];
+    }
+    if (nut.Key[`Num${token}`] !== undefined && /[0-9]/.test(token)) {
+      return nut.Key[`Num${token}`];
+    }
+  }
+  throw new Error(`Unsupported key: ${token}`);
+}
+
+/**
+ * The cross-platform OS executor. It is intentionally free of any server,
+ * database, or session dependencies so it can run both inside the local server
+ * process (OSS mode) and inside the standalone desktop agent (cloud relay).
+ */
+export const executor = {
+  async configure() {
+    const nut = getNut();
+    if (nut) {
+      // Make actions responsive; the agent loop already paces itself with screenshots.
+      nut.mouse.config.autoDelayMs = 2;
+      nut.keyboard.config.autoDelayMs = 2;
+    }
+    return nut;
+  },
+
+  async cursorPosition(target: ExecutorTarget): Promise<Point> {
+    const nut = await this.configure();
+    const mouseSize = await getMouseSpaceSize();
+    const pos = await nut.mouse.getPosition();
+    return toImageSpace(target, { x: pos.x, y: pos.y }, mouseSize);
+  },
+
+  async moveTo(target: ExecutorTarget, point: Point): Promise<void> {
+    const nut = await this.configure();
+    const dest = await toMouseSpace(target, point);
+    await nut.mouse.setPosition(new nut.Point(dest.x, dest.y));
+  },
+
+  async click(target: ExecutorTarget, button: ClickButton, point?: Point, doubleClick = false): Promise<void> {
+    const nut = await this.configure();
+    if (point) {
+      await this.moveTo(target, point);
+    }
+    if (doubleClick) {
+      await nut.mouse.doubleClick(nutButton(nut, button));
+    } else {
+      await nut.mouse.click(nutButton(nut, button));
+    }
+  },
+
+  async drag(target: ExecutorTarget, from: Point, to: Point, button: ClickButton = 'left'): Promise<void> {
+    const nut = await this.configure();
+    const start = await toMouseSpace(target, from);
+    const end = await toMouseSpace(target, to);
+    await nut.mouse.setPosition(new nut.Point(start.x, start.y));
+    await nut.mouse.pressButton(nutButton(nut, button));
+    await nut.mouse.setPosition(new nut.Point(end.x, end.y));
+    await nut.mouse.releaseButton(nutButton(nut, button));
+  },
+
+  async type(text: string): Promise<void> {
+    const nut = await this.configure();
+    await nut.keyboard.type(text);
+  },
+
+  async pressChord(chord: string): Promise<void> {
+    const nut = await this.configure();
+    const tokens = chord.split('+').map((token) => token.trim()).filter(Boolean);
+    if (tokens.length === 0) {
+      return;
+    }
+    const keys = tokens.map((token) => nutKey(nut, token));
+    for (const key of keys) {
+      await nut.keyboard.pressKey(key);
+    }
+    for (const key of [...keys].reverse()) {
+      await nut.keyboard.releaseKey(key);
+    }
+  },
+
+  async scroll(target: ExecutorTarget, direction: ScrollDirection, amount: number, point?: Point): Promise<void> {
+    const nut = await this.configure();
+    if (point) {
+      await this.moveTo(target, point);
+    }
+    const steps = Math.max(1, Math.round(amount));
+    if (direction === 'up') await nut.mouse.scrollUp(steps);
+    else if (direction === 'down') await nut.mouse.scrollDown(steps);
+    else if (direction === 'left') await nut.mouse.scrollLeft(steps);
+    else await nut.mouse.scrollRight(steps);
+  },
+};
--- a/server/modules/computer-use/computer-use-mcp.routes.ts
+++ b/server/modules/computer-use/computer-use-mcp.routes.ts
@@ -0,0 +1,118 @@
+import express from 'express';
+
+import { computerUseService } from '@/modules/computer-use/computer-use.service.js';
+
+const router = express.Router();
+
+function readBearerToken(header: unknown): string | null {
+  if (typeof header !== 'string') {
+    return null;
+  }
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+  return match?.[1] || null;
+}
+
+function toButton(value: unknown): 'left' | 'right' | 'middle' {
+  return value === 'right' || value === 'middle' ? value : 'left';
+}
+
+function toScrollDirection(value: unknown): 'up' | 'down' | 'left' | 'right' {
+  return value === 'down' || value === 'left' || value === 'right' ? value : 'up';
+}
+
+function point(input: Record<string, unknown>): { x: number; y: number } | undefined {
+  return typeof input.x === 'number' && typeof input.y === 'number'
+    ? { x: input.x, y: input.y }
+    : undefined;
+}
+
+router.use((req, res, next) => {
+  const expected = computerUseService.getMcpToken();
+  const token = readBearerToken(req.headers.authorization) || String(req.headers['x-computer-use-mcp-token'] || '');
+  if (!token || token !== expected) {
+    res.status(401).json({ success: false, error: 'Invalid Computer Use MCP token.' });
+    return;
+  }
+  next();
+});
+
+router.post('/tools/:toolName', async (req, res) => {
+  try {
+    const input = (req.body && typeof req.body === 'object' ? req.body : {}) as Record<string, unknown>;
+    const sessionId = typeof input.sessionId === 'string' ? input.sessionId : '';
+    const toolName = req.params.toolName;
+    let result: unknown;
+
+    switch (toolName) {
+      case 'computer_create_session':
+        result = await computerUseService.createAgentSession();
+        break;
+      case 'computer_list_sessions':
+        result = await computerUseService.listAgentSessions();
+        break;
+      case 'computer_screenshot':
+        result = await computerUseService.agentScreenshot(sessionId);
+        break;
+      case 'computer_cursor_position':
+        result = await computerUseService.agentCursorPosition(sessionId);
+        break;
+      case 'computer_mouse_move':
+        result = await computerUseService.agentMouseMove(sessionId, point(input) || { x: 0, y: 0 });
+        break;
+      case 'computer_left_click':
+        result = await computerUseService.agentClick(sessionId, 'left', point(input));
+        break;
+      case 'computer_right_click':
+        result = await computerUseService.agentClick(sessionId, 'right', point(input));
+        break;
+      case 'computer_middle_click':
+        result = await computerUseService.agentClick(sessionId, 'middle', point(input));
+        break;
+      case 'computer_double_click':
+        result = await computerUseService.agentClick(sessionId, toButton(input.button), point(input), true);
+        break;
+      case 'computer_left_click_drag': {
+        const from = typeof input.startX === 'number' && typeof input.startY === 'number'
+          ? { x: input.startX, y: input.startY }
+          : { x: 0, y: 0 };
+        const to = typeof input.endX === 'number' && typeof input.endY === 'number'
+          ? { x: input.endX, y: input.endY }
+          : { x: 0, y: 0 };
+        result = await computerUseService.agentDrag(sessionId, from, to, 'left');
+        break;
+      }
+      case 'computer_type':
+        result = await computerUseService.agentType(sessionId, String(input.text || ''));
+        break;
+      case 'computer_key':
+        result = await computerUseService.agentKey(sessionId, String(input.key || ''));
+        break;
+      case 'computer_scroll':
+        result = await computerUseService.agentScroll(sessionId, {
+          direction: toScrollDirection(input.direction),
+          amount: typeof input.amount === 'number' ? input.amount : undefined,
+          x: typeof input.x === 'number' ? input.x : undefined,
+          y: typeof input.y === 'number' ? input.y : undefined,
+        });
+        break;
+      case 'computer_wait':
+        result = await computerUseService.agentWait(sessionId, typeof input.timeoutMs === 'number' ? input.timeoutMs : undefined);
+        break;
+      case 'computer_close_session':
+        result = await computerUseService.agentStopSession(sessionId);
+        break;
+      default:
+        res.status(404).json({ success: false, error: `Unknown Computer Use MCP tool "${toolName}".` });
+        return;
+    }
+
+    res.json({ success: true, data: result });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Computer Use MCP tool failed.',
+    });
+  }
+});
+
+export default router;
--- a/server/modules/computer-use/computer-use.routes.ts
+++ b/server/modules/computer-use/computer-use.routes.ts
@@ -0,0 +1,215 @@
+import express from 'express';
+
+import { computerUseService } from '@/modules/computer-use/computer-use.service.js';
+
+const router = express.Router();
+
+type AuthenticatedRequest = express.Request & {
+  user?: {
+    id?: string | number;
+  };
+};
+
+function requireUser(req: AuthenticatedRequest): { id: string | number } {
+  const userId = req.user?.id;
+  if (userId === undefined || userId === null) {
+    throw new Error('Authenticated user is required.');
+  }
+  return { id: userId };
+}
+
+function readParam(value: string | string[] | undefined): string {
+  return Array.isArray(value) ? value[0] || '' : value || '';
+}
+
+function toButton(value: unknown): 'left' | 'right' | 'middle' {
+  return value === 'right' || value === 'middle' ? value : 'left';
+}
+
+router.get('/status', async (_req, res) => {
+  try {
+    res.json({ success: true, data: await computerUseService.getStatus() });
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to load Computer Use status.',
+    });
+  }
+});
+
+router.get('/settings', async (_req, res) => {
+  try {
+    res.json({ success: true, data: { settings: await computerUseService.getSettings() } });
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to load Computer Use settings.',
+    });
+  }
+});
+
+router.put('/settings', async (req, res) => {
+  try {
+    const settings = await computerUseService.updateSettings(req.body || {});
+    res.json({ success: true, data: { settings } });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to save Computer Use settings.',
+    });
+  }
+});
+
+router.post('/agent-tools/register', async (_req, res) => {
+  try {
+    const result = await computerUseService.registerAgentMcp();
+    res.status(201).json({ success: true, data: result });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to register Computer Use MCP.',
+    });
+  }
+});
+
+router.post('/runtime/install', async (_req, res) => {
+  try {
+    const result = await computerUseService.installRuntime();
+    res.status(result.success ? 200 : 500).json({
+      success: result.success,
+      data: result,
+      error: result.success ? undefined : result.message,
+    });
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to install Computer Use runtime.',
+    });
+  }
+});
+
+router.get('/sessions', async (req: AuthenticatedRequest, res) => {
+  try {
+    res.json({ success: true, data: { sessions: await computerUseService.listSessions(requireUser(req)) } });
+  } catch (error) {
+    res.status(401).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to list Computer Use sessions.',
+    });
+  }
+});
+
+router.post('/sessions', async (req: AuthenticatedRequest, res) => {
+  try {
+    const session = await computerUseService.createSession(requireUser(req));
+    res.status(session.status === 'unavailable' ? 202 : 201).json({ success: true, data: { session } });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to create Computer Use session.',
+    });
+  }
+});
+
+router.post('/sessions/:sessionId/screenshot', async (req: AuthenticatedRequest, res) => {
+  try {
+    const session = await computerUseService.userScreenshot(requireUser(req), readParam(req.params.sessionId));
+    res.json({ success: true, data: { session } });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to capture the screen.',
+    });
+  }
+});
+
+router.post('/sessions/:sessionId/click', async (req: AuthenticatedRequest, res) => {
+  try {
+    const session = await computerUseService.userClick(requireUser(req), readParam(req.params.sessionId), {
+      x: Number(req.body?.x),
+      y: Number(req.body?.y),
+      button: toButton(req.body?.button),
+      double: req.body?.double === true,
+    });
+    res.json({ success: true, data: { session } });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to click.',
+    });
+  }
+});
+
+router.post('/sessions/:sessionId/type', async (req: AuthenticatedRequest, res) => {
+  try {
+    const session = await computerUseService.userType(requireUser(req), readParam(req.params.sessionId), String(req.body?.text || ''));
+    res.json({ success: true, data: { session } });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to type text.',
+    });
+  }
+});
+
+router.post('/sessions/:sessionId/press-key', async (req: AuthenticatedRequest, res) => {
+  try {
+    const session = await computerUseService.userPressKey(requireUser(req), readParam(req.params.sessionId), String(req.body?.key || ''));
+    res.json({ success: true, data: { session } });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to send key input.',
+    });
+  }
+});
+
+router.post('/sessions/:sessionId/consent/grant', async (req: AuthenticatedRequest, res) => {
+  try {
+    const session = await computerUseService.grantAgentAccess(requireUser(req), readParam(req.params.sessionId));
+    res.json({ success: true, data: { session } });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to grant control.',
+    });
+  }
+});
+
+router.post('/sessions/:sessionId/consent/revoke', async (req: AuthenticatedRequest, res) => {
+  try {
+    const session = await computerUseService.revokeAgentAccess(requireUser(req), readParam(req.params.sessionId));
+    res.json({ success: true, data: { session } });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to revoke control.',
+    });
+  }
+});
+
+router.post('/sessions/:sessionId/stop', async (req: AuthenticatedRequest, res) => {
+  try {
+    const result = await computerUseService.stopSession(requireUser(req), readParam(req.params.sessionId));
+    res.json({ success: true, data: result });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to stop Computer Use session.',
+    });
+  }
+});
+
+router.delete('/sessions/:sessionId', async (req: AuthenticatedRequest, res) => {
+  try {
+    const result = await computerUseService.deleteSession(requireUser(req), readParam(req.params.sessionId));
+    res.json({ success: true, data: result });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to delete Computer Use session.',
+    });
+  }
+});
+
+export default router;
--- a/server/modules/computer-use/computer-use.service.ts
+++ b/server/modules/computer-use/computer-use.service.ts
@@ -0,0 +1,883 @@
+import { createRequire } from 'node:module';
+import { randomBytes, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { appConfigDb } from '@/modules/database/repositories/app-config.js';
+import { providerMcpService } from '@/modules/providers/services/mcp.service.js';
+import { getModuleDir } from '@/utils/runtime-paths.js';
+import {
+  executor,
+  captureScreenshot as captureScreenshotRuntime,
+  getRuntimeReadiness as getExecutorReadiness,
+  type Point,
+  type ClickButton,
+  type ScrollDirection,
+} from '@/modules/computer-use/computer-executor.js';
+import { desktopAgentRelay } from '@/modules/computer-use/desktop-agent-relay.service.js';
+
+const __dirname = getModuleDir(import.meta.url);
+const IS_PLATFORM = process.env.VITE_IS_PLATFORM === 'true';
+const MAX_SESSIONS_PER_OWNER = Number.parseInt(process.env.CLOUDCLI_COMPUTER_USE_MAX_SESSIONS_PER_OWNER || '1', 10);
+const SESSION_TTL_MS = Number.parseInt(process.env.CLOUDCLI_COMPUTER_USE_SESSION_TTL_MS || String(30 * 60 * 1000), 10);
+const COMPUTER_USE_SETTINGS_KEY = 'computer_use_settings';
+const COMPUTER_USE_MCP_TOKEN_KEY = 'computer_use_mcp_token';
+
+type ComputerUseRuntime = 'cloud' | 'local';
+type ComputerUseSessionStatus = 'ready' | 'stopped' | 'unavailable';
+
+type ComputerUseSession = {
+  id: string;
+  ownerId: string;
+  createdBy: 'user' | 'agent';
+  runtime: ComputerUseRuntime;
+  status: ComputerUseSessionStatus;
+  screenshotDataUrl: string | null;
+  createdAt: string;
+  updatedAt: string;
+  lastAction: string | null;
+  message: string | null;
+  /** Per-session consent: agents may act only while this is true. */
+  agentAccessEnabled: boolean;
+  /** Size of the captured screenshot in pixels — the coordinate space agents/users use. */
+  displaySize: {
+    width: number;
+    height: number;
+  } | null;
+  cursor: {
+    x: number;
+    y: number;
+    actor: 'agent' | 'user';
+  } | null;
+};
+
+type PublicComputerUseSession = Omit<ComputerUseSession, 'ownerId'>;
+
+type ComputerUseOwner = {
+  id: string | number;
+};
+
+type ComputerUseSettings = {
+  enabled: boolean;
+  agentToolsEnabled: boolean;
+};
+
+type RuntimeReadiness = {
+  nut: any | null;
+  screenshot: any | null;
+  nutInstalled: boolean;
+  screenshotInstalled: boolean;
+  installInProgress: boolean;
+  installMessage: string | null;
+};
+
+const sessions = new Map<string, ComputerUseSession>();
+let installPromise: Promise<{ success: boolean; message: string }> | null = null;
+let lastInstallMessage: string | null = null;
+
+const DEFAULT_SETTINGS: ComputerUseSettings = {
+  enabled: false,
+  agentToolsEnabled: false,
+};
+const AGENT_OWNER_ID = 'agent';
+const MCP_SERVER_NAME = 'cloudcli-computer-use';
+const MCP_PROVIDERS = ['claude', 'codex', 'cursor', 'gemini', 'opencode'];
+
+function getRuntime(): ComputerUseRuntime {
+  return IS_PLATFORM ? 'cloud' : 'local';
+}
+
+function readSettings(): ComputerUseSettings {
+  try {
+    const raw = appConfigDb.get(COMPUTER_USE_SETTINGS_KEY);
+    if (!raw) {
+      return DEFAULT_SETTINGS;
+    }
+
+    const parsed = JSON.parse(raw) as Partial<ComputerUseSettings>;
+    return {
+      enabled: parsed.enabled === true,
+      agentToolsEnabled: parsed.agentToolsEnabled === true,
+    };
+  } catch (error: any) {
+    console.warn('[Computer Use] Failed to read settings:', error?.message || error);
+    return DEFAULT_SETTINGS;
+  }
+}
+
+function writeSettings(settings: ComputerUseSettings): ComputerUseSettings {
+  const normalized = {
+    enabled: settings.enabled === true,
+    agentToolsEnabled: settings.agentToolsEnabled === true,
+  };
+
+  appConfigDb.set(COMPUTER_USE_SETTINGS_KEY, JSON.stringify(normalized));
+  return normalized;
+}
+
+function getOrCreateMcpToken(): string {
+  const existing = appConfigDb.get(COMPUTER_USE_MCP_TOKEN_KEY);
+  if (existing) {
+    return existing;
+  }
+  const token = randomBytes(32).toString('hex');
+  appConfigDb.set(COMPUTER_USE_MCP_TOKEN_KEY, token);
+  return token;
+}
+
+function getSetupMessage(settings: ComputerUseSettings, readiness: RuntimeReadiness): string {
+  if (getRuntime() === 'cloud') {
+    return 'Cloud Computer Use requires a linked CloudCLI Desktop Agent on the user machine.';
+  }
+  if (!settings.enabled) {
+    return 'Computer Use is disabled in settings.';
+  }
+  if (!readiness.nutInstalled || !readiness.screenshotInstalled) {
+    return 'Install the desktop control runtime to capture the screen and drive the mouse and keyboard.';
+  }
+  return readiness.installMessage || 'Computer Use runtime is not ready.';
+}
+
+function getMcpCommand(): { command: string; args: string[] } {
+  const serverDir = path.resolve(__dirname, '..', '..');
+  const mcpScriptPath = path.join(serverDir, 'computer-use-mcp.js');
+  if (fs.existsSync(mcpScriptPath)) {
+    return {
+      command: process.execPath,
+      args: [mcpScriptPath],
+    };
+  }
+
+  return {
+    command: 'cloudcli',
+    args: ['computer-use-mcp'],
+  };
+}
+
+function getMcpApiUrl(): string {
+  const port = process.env.SERVER_PORT || process.env.PORT || '3001';
+  return `http://127.0.0.1:${port}/api/computer-use-mcp`;
+}
+
+function getRuntimeReadiness(): RuntimeReadiness {
+  const base = getExecutorReadiness();
+  return {
+    ...base,
+    installInProgress: Boolean(installPromise),
+    installMessage: lastInstallMessage,
+  };
+}
+
+function runCommand(command: string, args: string[]): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: process.cwd(),
+      env: process.env,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const output: string[] = [];
+
+    child.stdout.on('data', (chunk) => output.push(String(chunk)));
+    child.stderr.on('data', (chunk) => output.push(String(chunk)));
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+
+      reject(new Error(output.join('').trim() || `${command} ${args.join(' ')} exited with code ${code}`));
+    });
+  });
+}
+
+function formatInstallError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  if (process.platform === 'linux' && /libxtst|x11|xtst|libpng|imagemagick|scrot/i.test(message)) {
+    return [
+      'Installing the desktop control runtime needs system packages.',
+      'On Debian/Ubuntu run: sudo apt-get install -y libxtst-dev libpng-dev imagemagick',
+      'then try again.',
+    ].join(' ');
+  }
+  return message || 'Failed to install the Computer Use runtime.';
+}
+
+function isPackagedElectronNodeRuntime(): boolean {
+  return process.env.ELECTRON_RUN_AS_NODE === '1' && Boolean(process.versions.electron);
+}
+
+async function installRuntime(): Promise<{ success: boolean; message: string }> {
+  if (installPromise) {
+    return installPromise;
+  }
+
+  const readiness = getExecutorReadiness();
+  if (readiness.nutInstalled && readiness.screenshotInstalled) {
+    lastInstallMessage = 'Computer Use runtime is available.';
+    return { success: true, message: lastInstallMessage };
+  }
+
+  if (isPackagedElectronNodeRuntime()) {
+    lastInstallMessage = 'Computer Use runtime was not bundled with this desktop build.';
+    return { success: false, message: lastInstallMessage };
+  }
+
+  const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  installPromise = (async () => {
+    try {
+      lastInstallMessage = 'Installing desktop control runtime…';
+      await runCommand(npmCommand, [
+        'install',
+        '--no-save',
+        '--no-package-lock',
+        '@nut-tree-fork/nut-js',
+        'screenshot-desktop',
+      ]);
+
+      lastInstallMessage = 'Computer Use runtime installed.';
+      return { success: true, message: lastInstallMessage };
+    } catch (error) {
+      lastInstallMessage = formatInstallError(error);
+      return { success: false, message: lastInstallMessage };
+    }
+  })();
+
+  try {
+    return await installPromise;
+  } finally {
+    installPromise = null;
+  }
+}
+
+function getOwnerId(owner: ComputerUseOwner): string {
+  if (owner.id === undefined || owner.id === null || String(owner.id).trim() === '') {
+    throw new Error('Authenticated user is required.');
+  }
+
+  return String(owner.id);
+}
+
+function publicSession(session: ComputerUseSession): PublicComputerUseSession {
+  const { ownerId: _ownerId, ...publicFields } = session;
+  return publicFields;
+}
+
+function ownerSessions(ownerId: string): ComputerUseSession[] {
+  return [...sessions.values()].filter((session) => session.ownerId === ownerId);
+}
+
+function canAccessSession(ownerId: string, session: ComputerUseSession): boolean {
+  return session.ownerId === ownerId || session.ownerId === AGENT_OWNER_ID;
+}
+
+async function expireStaleSessions(now = Date.now()): Promise<void> {
+  for (const session of sessions.values()) {
+    if (session.status !== 'ready') {
+      continue;
+    }
+
+    const updatedAt = Date.parse(session.updatedAt);
+    if (!Number.isFinite(updatedAt) || now - updatedAt <= SESSION_TTL_MS) {
+      continue;
+    }
+
+    session.status = 'stopped';
+    session.agentAccessEnabled = false;
+    session.updatedAt = new Date(now).toISOString();
+    session.lastAction = 'expire';
+    session.message = 'Computer Use session expired after inactivity.';
+  }
+}
+
+// --- Action layer: local executor (OSS) or cloud relay to the desktop agent --
+//
+// Every desktop interaction goes through `performAction` / `getCursorPosition`.
+// In local mode it drives the in-process nut-js executor (computer-executor.ts);
+// in cloud mode it forwards the action to the linked desktop agent over
+// `desktopAgentRelay` and applies the returned screenshot. The local server
+// itself never touches the OS in cloud mode.
+
+/** One desktop interaction expressed in screenshot-pixel coordinate space. */
+export type ComputerAction =
+  | { type: 'screenshot' }
+  | { type: 'mouse_move'; point: Point }
+  | { type: 'click'; button: ClickButton; point?: Point; double?: boolean }
+  | { type: 'drag'; from: Point; to: Point; button?: ClickButton }
+  | { type: 'type'; text: string }
+  | { type: 'key'; key: string }
+  | { type: 'scroll'; direction: ScrollDirection; amount?: number; point?: Point }
+  | { type: 'wait'; ms?: number };
+
+/** Shape the desktop agent returns for any relayed action. */
+type RelayResult = {
+  screenshotDataUrl?: string | null;
+  displaySize?: { width: number; height: number } | null;
+  cursor?: { x: number; y: number } | null;
+  position?: Point | null;
+};
+
+function applyRelayResult(session: ComputerUseSession, result: RelayResult): void {
+  if (typeof result.screenshotDataUrl === 'string') {
+    session.screenshotDataUrl = result.screenshotDataUrl;
+  }
+  if (result.displaySize) {
+    session.displaySize = result.displaySize;
+  }
+  if (result.cursor) {
+    session.cursor = { x: result.cursor.x, y: result.cursor.y, actor: session.cursor?.actor ?? 'agent' };
+  }
+  session.updatedAt = new Date().toISOString();
+}
+
+async function refreshScreenshot(session: ComputerUseSession): Promise<void> {
+  if (getRuntime() === 'cloud') {
+    const result = (await desktopAgentRelay.relay('screenshot', { sessionId: session.id })) as RelayResult;
+    applyRelayResult(session, result);
+    return;
+  }
+  const { dataUrl, size } = await captureScreenshotRuntime();
+  session.screenshotDataUrl = dataUrl;
+  if (size) {
+    session.displaySize = size;
+  }
+  session.updatedAt = new Date().toISOString();
+}
+
+/** Runs one action and refreshes the session screenshot afterwards. */
+async function performAction(session: ComputerUseSession, action: ComputerAction): Promise<void> {
+  if (getRuntime() === 'cloud') {
+    const result = (await desktopAgentRelay.relay(action.type, {
+      ...action,
+      sessionId: session.id,
+      displaySize: session.displaySize,
+    })) as RelayResult;
+    applyRelayResult(session, result);
+    return;
+  }
+
+  switch (action.type) {
+    case 'screenshot':
+      break;
+    case 'mouse_move':
+      await executor.moveTo(session, action.point);
+      break;
+    case 'click':
+      await executor.click(session, action.button, action.point, action.double === true);
+      break;
+    case 'drag':
+      await executor.drag(session, action.from, action.to, action.button ?? 'left');
+      break;
+    case 'type':
+      await executor.type(action.text);
+      break;
+    case 'key':
+      await executor.pressChord(action.key);
+      break;
+    case 'scroll':
+      await executor.scroll(session, action.direction, action.amount ?? 3, action.point);
+      break;
+    case 'wait':
+      await new Promise((resolve) => setTimeout(resolve, Math.max(0, Math.min(action.ms ?? 1000, 10_000))));
+      break;
+  }
+  await refreshScreenshot(session);
+}
+
+/** Reads the current cursor position in screenshot-pixel space. */
+async function getCursorPosition(session: ComputerUseSession): Promise<Point> {
+  if (getRuntime() === 'cloud') {
+    const result = (await desktopAgentRelay.relay('cursor_position', {
+      sessionId: session.id,
+      displaySize: session.displaySize,
+    })) as RelayResult;
+    applyRelayResult(session, result);
+    if (result.position) {
+      return result.position;
+    }
+    return session.cursor ? { x: session.cursor.x, y: session.cursor.y } : { x: 0, y: 0 };
+  }
+  return executor.cursorPosition(session);
+}
+
+function assertReady(session: ComputerUseSession): void {
+  if (session.status !== 'ready') {
+    throw new Error(session.message || 'Computer Use session is not available.');
+  }
+}
+
+/**
+ * Whether agent tools may operate right now. Cloud mode depends purely on a
+ * connected desktop agent; local mode depends on the two opt-in settings.
+ */
+function agentToolsAvailable(): boolean {
+  if (getRuntime() === 'cloud') {
+    return desktopAgentRelay.isConnected();
+  }
+  const settings = readSettings();
+  return settings.enabled && settings.agentToolsEnabled;
+}
+
+function assertAgentToolsAvailable(): void {
+  if (agentToolsAvailable()) {
+    return;
+  }
+  throw new Error(
+    getRuntime() === 'cloud'
+      ? 'No desktop agent is connected. Open the CloudCLI desktop app with Computer Use enabled.'
+      : 'Computer Use agent tools are disabled.'
+  );
+}
+
+export const computerUseService = {
+  async getSettings() {
+    return readSettings();
+  },
+
+  async updateSettings(settings: Partial<ComputerUseSettings>) {
+    const current = readSettings();
+    const nextSettings = {
+      ...current,
+      enabled: typeof settings.enabled === 'boolean' ? settings.enabled : current.enabled,
+      agentToolsEnabled: typeof settings.agentToolsEnabled === 'boolean'
+        ? settings.agentToolsEnabled
+        : current.agentToolsEnabled,
+    };
+    if (!nextSettings.enabled) {
+      nextSettings.agentToolsEnabled = false;
+    }
+
+    const next = writeSettings(nextSettings);
+    if (next.agentToolsEnabled) {
+      await this.registerAgentMcp();
+    } else if (current.agentToolsEnabled) {
+      await this.unregisterAgentMcp();
+    }
+    return next;
+  },
+
+  async getStatus() {
+    const settings = readSettings();
+    const readiness = getRuntimeReadiness();
+    const isCloud = getRuntime() === 'cloud';
+    const runtimeReady = readiness.nutInstalled && readiness.screenshotInstalled;
+    // Cloud availability is purely a function of a connected desktop agent; the
+    // hosted server has no screen of its own. Local availability needs the
+    // in-process nut-js runtime installed and the feature enabled.
+    const desktopAgentConnected = desktopAgentRelay.isConnected();
+    const available = isCloud
+      ? desktopAgentConnected
+      : settings.enabled && runtimeReady;
+
+    return {
+      enabled: isCloud ? true : settings.enabled,
+      runtime: getRuntime(),
+      available,
+      requiresDesktopBridge: isCloud,
+      desktopAgentConnected,
+      nutInstalled: readiness.nutInstalled,
+      screenshotInstalled: readiness.screenshotInstalled,
+      installInProgress: readiness.installInProgress,
+      sessionCount: sessions.size,
+      agentToolsEnabled: isCloud ? desktopAgentConnected : settings.agentToolsEnabled,
+      mcpRecommended: !settings.agentToolsEnabled,
+      message: available ? 'Computer Use runtime is available.' : getSetupMessage(settings, readiness),
+    };
+  },
+
+  async registerAgentMcp() {
+    const { command, args } = getMcpCommand();
+    const results = await providerMcpService.addMcpServerToAllProviders({
+      name: MCP_SERVER_NAME,
+      scope: 'user',
+      transport: 'stdio',
+      command,
+      args,
+      env: {
+        CLOUDCLI_COMPUTER_USE_MCP_TOKEN: getOrCreateMcpToken(),
+        CLOUDCLI_COMPUTER_USE_API_URL: getMcpApiUrl(),
+      },
+    });
+    return { name: MCP_SERVER_NAME, command, args, results };
+  },
+
+  getMcpToken() {
+    return getOrCreateMcpToken();
+  },
+
+  async unregisterAgentMcp() {
+    const results = await Promise.all(MCP_PROVIDERS.map(async (provider) => {
+      try {
+        const result = await providerMcpService.removeProviderMcpServer(provider, {
+          name: MCP_SERVER_NAME,
+          scope: 'user',
+        });
+        return { provider, removed: result.removed };
+      } catch (error) {
+        return {
+          provider,
+          removed: false,
+          error: error instanceof Error ? error.message : 'Unknown error',
+        };
+      }
+    }));
+    return { name: MCP_SERVER_NAME, results };
+  },
+
+  async installRuntime() {
+    const result = await installRuntime();
+    return {
+      ...result,
+      status: await this.getStatus(),
+    };
+  },
+
+  async listSessions(owner: ComputerUseOwner) {
+    const ownerId = getOwnerId(owner);
+    await expireStaleSessions();
+    return [...sessions.values()]
+      .filter((session) => canAccessSession(ownerId, session))
+      .map(publicSession);
+  },
+
+  async createSession(owner: ComputerUseOwner, options?: { createdBy?: 'user' | 'agent' }) {
+    const ownerId = getOwnerId(owner);
+    await expireStaleSessions();
+    const createdBy = options?.createdBy ?? 'user';
+
+    const now = new Date().toISOString();
+    const session: ComputerUseSession = {
+      id: randomUUID(),
+      ownerId,
+      createdBy,
+      runtime: getRuntime(),
+      status: 'unavailable',
+      screenshotDataUrl: null,
+      createdAt: now,
+      updatedAt: now,
+      lastAction: 'create',
+      // Consent is always OFF at creation — the user must explicitly grant control,
+      // even for agent-initiated sessions controlling the full desktop.
+      agentAccessEnabled: false,
+      displaySize: null,
+      message: null,
+      cursor: null,
+    };
+
+    const activeOwnerSessions = ownerSessions(ownerId).filter((item) => item.status === 'ready');
+    if (activeOwnerSessions.length >= MAX_SESSIONS_PER_OWNER) {
+      throw new Error(`Computer Use is limited to ${MAX_SESSIONS_PER_OWNER} active session(s).`);
+    }
+
+    const settings = readSettings();
+    const readiness = getRuntimeReadiness();
+    const isCloud = getRuntime() === 'cloud';
+    const runtimeReady = readiness.nutInstalled && readiness.screenshotInstalled;
+    const ready = isCloud
+      ? desktopAgentRelay.isConnected()
+      : settings.enabled && runtimeReady;
+
+    if (!ready) {
+      session.message = getSetupMessage(settings, readiness);
+      sessions.set(session.id, session);
+      return publicSession(session);
+    }
+
+    // In cloud mode the linked desktop agent is the consent authority and prompts
+    // the user per its own consent mode, so the relay is allowed to act. In local
+    // mode the user must still grant control from the panel.
+    if (isCloud) {
+      session.agentAccessEnabled = true;
+    }
+
+    session.status = 'ready';
+    session.message = isCloud
+      ? 'Computer Use session is ready on the linked desktop.'
+      : 'Computer Use session is ready. Grant control to let agents act.';
+    sessions.set(session.id, session);
+    try {
+      await refreshScreenshot(session);
+    } catch (error) {
+      session.status = 'unavailable';
+      session.message = error instanceof Error ? error.message : 'Failed to capture the screen.';
+    }
+    return publicSession(session);
+  },
+
+  async grantAgentAccess(owner: ComputerUseOwner, sessionId: string) {
+    const ownerId = getOwnerId(owner);
+    const session = sessions.get(sessionId);
+    if (!session || !canAccessSession(ownerId, session)) {
+      throw new Error('Computer Use session not found.');
+    }
+    session.agentAccessEnabled = true;
+    session.updatedAt = new Date().toISOString();
+    session.lastAction = 'consent:grant';
+    return publicSession(session);
+  },
+
+  async revokeAgentAccess(owner: ComputerUseOwner, sessionId: string) {
+    const ownerId = getOwnerId(owner);
+    const session = sessions.get(sessionId);
+    if (!session || !canAccessSession(ownerId, session)) {
+      throw new Error('Computer Use session not found.');
+    }
+    session.agentAccessEnabled = false;
+    session.updatedAt = new Date().toISOString();
+    session.lastAction = 'consent:revoke';
+    return publicSession(session);
+  },
+
+  async stopSession(owner: ComputerUseOwner, sessionId: string) {
+    const ownerId = getOwnerId(owner);
+    const session = sessions.get(sessionId);
+    if (!session || !canAccessSession(ownerId, session)) {
+      return { stopped: false };
+    }
+
+    session.status = 'stopped';
+    session.agentAccessEnabled = false;
+    session.updatedAt = new Date().toISOString();
+    session.lastAction = 'stop';
+    session.message = 'Computer Use session stopped. Agent control is revoked.';
+    if (getRuntime() === 'cloud' && desktopAgentRelay.isConnected()) {
+      // Best-effort: tell the desktop agent to forget this session's consent.
+      void desktopAgentRelay.relay('stop_session', { sessionId }).catch(() => undefined);
+    }
+    return { stopped: true, session: publicSession(session) };
+  },
+
+  async deleteSession(owner: ComputerUseOwner, sessionId: string) {
+    const ownerId = getOwnerId(owner);
+    const session = sessions.get(sessionId);
+    if (!session || !canAccessSession(ownerId, session)) {
+      return { deleted: false };
+    }
+
+    sessions.delete(sessionId);
+    return { deleted: true, sessionId };
+  },
+
+  // --- User-initiated actions (from the panel) -------------------------------
+
+  async userScreenshot(owner: ComputerUseOwner, sessionId: string) {
+    const ownerId = getOwnerId(owner);
+    const session = sessions.get(sessionId);
+    if (!session || !canAccessSession(ownerId, session)) {
+      throw new Error('Computer Use session not found.');
+    }
+    assertReady(session);
+    await refreshScreenshot(session);
+    session.lastAction = 'screenshot';
+    return publicSession(session);
+  },
+
+  async userClick(owner: ComputerUseOwner, sessionId: string, input: { x: number; y: number; button?: ClickButton; double?: boolean }) {
+    const ownerId = getOwnerId(owner);
+    const session = sessions.get(sessionId);
+    if (!session || !canAccessSession(ownerId, session)) {
+      throw new Error('Computer Use session not found.');
+    }
+    assertReady(session);
+    await performAction(session, {
+      type: 'click',
+      button: input.button || 'left',
+      point: { x: input.x, y: input.y },
+      double: input.double === true,
+    });
+    session.cursor = { x: input.x, y: input.y, actor: 'user' };
+    session.lastAction = input.double ? 'double_click' : 'click';
+    return publicSession(session);
+  },
+
+  async userType(owner: ComputerUseOwner, sessionId: string, text: string) {
+    const ownerId = getOwnerId(owner);
+    const session = sessions.get(sessionId);
+    if (!session || !canAccessSession(ownerId, session)) {
+      throw new Error('Computer Use session not found.');
+    }
+    assertReady(session);
+    await performAction(session, { type: 'type', text });
+    session.lastAction = 'type';
+    return publicSession(session);
+  },
+
+  async userPressKey(owner: ComputerUseOwner, sessionId: string, key: string) {
+    const ownerId = getOwnerId(owner);
+    const session = sessions.get(sessionId);
+    if (!session || !canAccessSession(ownerId, session)) {
+      throw new Error('Computer Use session not found.');
+    }
+    assertReady(session);
+    await performAction(session, { type: 'key', key });
+    session.lastAction = `key:${key}`;
+    return publicSession(session);
+  },
+
+  // --- Agent-initiated actions (via MCP) ------------------------------------
+
+  async createAgentSession() {
+    assertAgentToolsAvailable();
+    return this.createSession({ id: AGENT_OWNER_ID }, { createdBy: 'agent' });
+  },
+
+  async listAgentSessions() {
+    if (!agentToolsAvailable()) {
+      return [];
+    }
+    await expireStaleSessions();
+    return [...sessions.values()].map(publicSession);
+  },
+
+  /**
+   * Resolves a session the agent is allowed to act on. In local mode this
+   * enforces the in-process per-session consent flag. In cloud mode the linked
+   * desktop agent is the consent authority (it prompts the user per its own
+   * consent mode), so this only requires the relay to be connected.
+   */
+  async getConsentedSession(sessionId: string): Promise<ComputerUseSession> {
+    assertAgentToolsAvailable();
+    const session = sessions.get(sessionId);
+    if (!session) {
+      throw new Error('Computer Use session not found.');
+    }
+    if (getRuntime() !== 'cloud' && !session.agentAccessEnabled) {
+      throw new Error('Computer Use session is awaiting user consent. Ask the user to grant control in the Computer panel.');
+    }
+    assertReady(session);
+    return session;
+  },
+
+  async agentScreenshot(sessionId: string) {
+    const session = await this.getConsentedSession(sessionId);
+    await refreshScreenshot(session);
+    session.lastAction = 'screenshot';
+    return publicSession(session);
+  },
+
+  async agentCursorPosition(sessionId: string) {
+    const session = await this.getConsentedSession(sessionId);
+    const point = await getCursorPosition(session);
+    session.cursor = { ...point, actor: 'agent' };
+    session.lastAction = 'cursor_position';
+    return { session: publicSession(session), position: point };
+  },
+
+  async agentMouseMove(sessionId: string, point: Point) {
+    const session = await this.getConsentedSession(sessionId);
+    await performAction(session, { type: 'mouse_move', point });
+    session.cursor = { ...point, actor: 'agent' };
+    session.lastAction = 'mouse_move';
+    return publicSession(session);
+  },
+
+  async agentClick(sessionId: string, button: ClickButton, point?: Point, doubleClick = false) {
+    const session = await this.getConsentedSession(sessionId);
+    await performAction(session, { type: 'click', button, point, double: doubleClick });
+    if (point) {
+      session.cursor = { ...point, actor: 'agent' };
+    }
+    session.lastAction = doubleClick ? 'double_click' : `${button}_click`;
+    return publicSession(session);
+  },
+
+  async agentDrag(sessionId: string, from: Point, to: Point, button: ClickButton = 'left') {
+    const session = await this.getConsentedSession(sessionId);
+    await performAction(session, { type: 'drag', from, to, button });
+    session.cursor = { ...to, actor: 'agent' };
+    session.lastAction = 'left_click_drag';
+    return publicSession(session);
+  },
+
+  async agentType(sessionId: string, text: string) {
+    const session = await this.getConsentedSession(sessionId);
+    await performAction(session, { type: 'type', text });
+    session.lastAction = 'type';
+    return publicSession(session);
+  },
+
+  async agentKey(sessionId: string, key: string) {
+    const session = await this.getConsentedSession(sessionId);
+    await performAction(session, { type: 'key', key });
+    session.lastAction = `key:${key}`;
+    return publicSession(session);
+  },
+
+  async agentScroll(sessionId: string, input: { direction: ScrollDirection; amount?: number; x?: number; y?: number }) {
+    const session = await this.getConsentedSession(sessionId);
+    const point = typeof input.x === 'number' && typeof input.y === 'number' ? { x: input.x, y: input.y } : undefined;
+    await performAction(session, { type: 'scroll', direction: input.direction, amount: input.amount, point });
+    if (point) {
+      session.cursor = { ...point, actor: 'agent' };
+    }
+    session.lastAction = `scroll:${input.direction}`;
+    return publicSession(session);
+  },
+
+  async agentWait(sessionId: string, timeoutMs?: number) {
+    const session = await this.getConsentedSession(sessionId);
+    await performAction(session, { type: 'wait', ms: timeoutMs });
+    session.lastAction = 'wait';
+    return publicSession(session);
+  },
+
+  async agentStopSession(sessionId: string) {
+    assertAgentToolsAvailable();
+    return this.stopSession({ id: AGENT_OWNER_ID }, sessionId);
+  },
+
+  /**
+   * Cloud only: when a desktop agent links to this hosted environment, expose
+   * the computer_* MCP tools to every provider so the running agent can use
+   * them. Mirrors `registerAgentMcp` but is driven by relay connectivity rather
+   * than a settings toggle.
+   */
+  async onDesktopAgentConnected() {
+    if (getRuntime() !== 'cloud') {
+      return;
+    }
+    try {
+      await this.registerAgentMcp();
+    } catch (error) {
+      console.warn('[Computer Use] Failed to register MCP for linked desktop agent:', error instanceof Error ? error.message : error);
+    }
+  },
+
+  /** Cloud only: tear down sessions when the last desktop agent disconnects. */
+  async onDesktopAgentDisconnected() {
+    if (getRuntime() !== 'cloud' || desktopAgentRelay.isConnected()) {
+      return;
+    }
+    for (const session of sessions.values()) {
+      if (session.status === 'ready') {
+        session.status = 'stopped';
+        session.agentAccessEnabled = false;
+        session.updatedAt = new Date().toISOString();
+        session.lastAction = 'agent-disconnected';
+        session.message = 'The linked desktop agent disconnected.';
+      }
+    }
+  },
+
+  async stopAllSessions() {
+    for (const session of sessions.values()) {
+      session.status = 'stopped';
+      session.agentAccessEnabled = false;
+      session.updatedAt = new Date().toISOString();
+      session.lastAction = 'shutdown';
+      session.message = 'Computer Use session stopped during server shutdown.';
+    }
+  },
+};
+
+// Drive cloud MCP exposure + session teardown off desktop-agent connectivity.
+desktopAgentRelay.setHooks({
+  onFirstConnect: () => computerUseService.onDesktopAgentConnected(),
+  onLastDisconnect: () => computerUseService.onDesktopAgentDisconnected(),
+});
+
+process.once('beforeExit', () => {
+  void computerUseService.stopAllSessions();
+});
--- a/server/modules/computer-use/desktop-agent-relay.service.ts
+++ b/server/modules/computer-use/desktop-agent-relay.service.ts
@@ -0,0 +1,129 @@
+import { randomUUID } from 'node:crypto';
+
+import type { WebSocket } from 'ws';
+
+const RELAY_TIMEOUT_MS = Number.parseInt(process.env.CLOUDCLI_COMPUTER_USE_RELAY_TIMEOUT_MS || '60000', 10);
+const WS_OPEN = 1;
+
+type PendingRelay = {
+  resolve: (value: unknown) => void;
+  reject: (reason: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+};
+
+type ConnectedAgent = {
+  ws: WebSocket;
+  label: string;
+  registeredAt: string;
+};
+
+type RelayLifecycleHooks = {
+  onFirstConnect?: () => void | Promise<void>;
+  onLastDisconnect?: () => void | Promise<void>;
+};
+
+const agents = new Map<WebSocket, ConnectedAgent>();
+const pending = new Map<string, PendingRelay>();
+let hooks: RelayLifecycleHooks = {};
+
+function rejectAllPending(reason: string): void {
+  for (const [callId, call] of pending.entries()) {
+    clearTimeout(call.timer);
+    call.reject(new Error(reason));
+    pending.delete(callId);
+  }
+}
+
+function pickAgent(): ConnectedAgent | undefined {
+  for (const agent of agents.values()) {
+    if (agent.ws.readyState === WS_OPEN) {
+      return agent;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Cloud-side registry of linked desktop agents and the request/response relay
+ * used to drive the user's real desktop. The hosted server never touches the OS
+ * itself — it only forwards `computer_*` actions to a connected desktop agent
+ * and awaits the screenshot it returns.
+ */
+export const desktopAgentRelay = {
+  setHooks(next: RelayLifecycleHooks): void {
+    hooks = next;
+  },
+
+  register(ws: WebSocket, label = 'desktop-agent'): void {
+    const wasEmpty = pickAgent() === undefined;
+    agents.set(ws, { ws, label, registeredAt: new Date().toISOString() });
+    console.log(`[DesktopAgent] Registered (${label}); ${agents.size} connected.`);
+
+    ws.on('close', () => {
+      agents.delete(ws);
+      console.log(`[DesktopAgent] Disconnected (${label}); ${agents.size} remain.`);
+      if (pickAgent() === undefined) {
+        rejectAllPending('Desktop agent disconnected.');
+        void hooks.onLastDisconnect?.();
+      }
+    });
+
+    if (wasEmpty) {
+      void hooks.onFirstConnect?.();
+    }
+  },
+
+  /** Resolves a pending relay call with the desktop agent's reply. */
+  handleResult(id: string, result: unknown, error?: string): void {
+    const call = pending.get(id);
+    if (!call) {
+      return;
+    }
+    clearTimeout(call.timer);
+    pending.delete(id);
+    if (error) {
+      call.reject(new Error(error));
+    } else {
+      call.resolve(result);
+    }
+  },
+
+  isConnected(): boolean {
+    return pickAgent() !== undefined;
+  },
+
+  connectedCount(): number {
+    let count = 0;
+    for (const agent of agents.values()) {
+      if (agent.ws.readyState === WS_OPEN) {
+        count++;
+      }
+    }
+    return count;
+  },
+
+  async relay(type: string, params: Record<string, unknown>): Promise<unknown> {
+    const agent = pickAgent();
+    if (!agent) {
+      throw new Error(
+        'No desktop agent connected. Open the CloudCLI desktop app with Computer Use enabled to control this machine.'
+      );
+    }
+
+    const id = randomUUID();
+    return new Promise<unknown>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error('Desktop agent did not respond in time.'));
+      }, RELAY_TIMEOUT_MS);
+      pending.set(id, { resolve, reject, timer });
+      try {
+        agent.ws.send(JSON.stringify({ kind: 'computer_relay', id, type, params }));
+      } catch (error) {
+        clearTimeout(timer);
+        pending.delete(id);
+        reject(error instanceof Error ? error : new Error('Failed to send to desktop agent.'));
+      }
+    });
+  },
+};
--- a/server/modules/computer-use/index.ts
+++ b/server/modules/computer-use/index.ts
@@ -0,0 +1,2 @@
+export { computerUseService } from '@/modules/computer-use/computer-use.service.js';
+export { desktopAgentRelay } from '@/modules/computer-use/desktop-agent-relay.service.js';
--- a/server/modules/database/migrations.ts
+++ b/server/modules/database/migrations.ts
@@ -382,6 +382,25 @@ const rebuildSessionsTableWithProjectSchema = (db: Database): void => {
  }
 };

+/**
+ * Adds the `provider_session_id` mapping column used by the session gateway.
+ *
+ * Rows that existed before this migration were always keyed directly by the
+ * provider-native session id, so backfilling `provider_session_id` with
+ * `session_id` keeps every legacy row resolvable through the new mapping.
+ */
+const addProviderSessionIdMapping = (db: Database): void => {
+  const sessionsTableInfo = getTableInfo(db, 'sessions');
+  const columnNames = sessionsTableInfo.map((column) => column.name);
+
+  addColumnToTableIfNotExists(db, 'sessions', columnNames, 'provider_session_id', 'TEXT');
+  db.exec(`
+    UPDATE sessions
+    SET provider_session_id = session_id
+    WHERE provider_session_id IS NULL
+  `);
+};
+
 const ensureProjectsForSessionPaths = (db: Database): void => {
  if (!tableExists(db, 'sessions')) {
    return;
@@ -428,9 +447,11 @@ export const runMigrations = (db: Database) => {
    migrateLegacyWorkspaceTableIntoProjects(db);
    rebuildSessionsTableWithProjectSchema(db);
    migrateLegacySessionNames(db);
+    addProviderSessionIdMapping(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_provider_session_id ON sessions(provider_session_id)');
    db.exec('CREATE INDEX IF NOT EXISTS idx_sessions_project_path ON sessions(project_path)');
    db.exec('CREATE INDEX IF NOT EXISTS idx_sessions_is_archived ON sessions(isArchived)');
    db.exec('CREATE INDEX IF NOT EXISTS idx_projects_is_starred ON projects(isStarred)');
--- a/server/modules/database/repositories/sessions.db.ts
+++ b/server/modules/database/repositories/sessions.db.ts
@@ -5,6 +5,7 @@ import { normalizeProjectPath } from '@/shared/utils.js';
 type SessionRow = {
  session_id: string;
  provider: string;
+  provider_session_id: string | null;
  project_path: string | null;
  jsonl_path: string | null;
  custom_name: string | null;
@@ -13,15 +14,22 @@ type SessionRow = {
  updated_at: string;
 };

-type SessionMetadataLookupRow = Pick<
-  SessionRow,
-  'session_id' | 'provider' | 'project_path' | 'jsonl_path' | 'custom_name' | 'isArchived' | 'created_at' | 'updated_at'
->;
+const SESSION_ROW_COLUMNS =
+  'session_id, provider, provider_session_id, project_path, jsonl_path, custom_name, isArchived, created_at, updated_at';
+
+const SQLITE_UTC_TIMESTAMP_REGEX = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;

 function normalizeTimestamp(value?: string): string | null {
  if (!value) return null;

-  const parsed = new Date(value);
+  // SQLite CURRENT_TIMESTAMP is stored as UTC without a timezone suffix.
+  // Normalize it here so every session reader returns canonical ISO strings
+  // and the sidebar never interprets fresh rows as local-time "hours old".
+  const normalizedValue = SQLITE_UTC_TIMESTAMP_REGEX.test(value)
+    ? `${value.replace(' ', 'T')}Z`
+    : value;
+
+  const parsed = new Date(normalizedValue);
  if (Number.isNaN(parsed.getTime())) {
    return null;
  }
@@ -29,14 +37,38 @@ function normalizeTimestamp(value?: string): string | null {
  return parsed.toISOString();
 }

+function normalizeSessionRow<T extends SessionRow | null | undefined>(row: T): T {
+  if (!row) {
+    return row;
+  }
+
+  return {
+    ...row,
+    created_at: normalizeTimestamp(row.created_at) ?? row.created_at,
+    updated_at: normalizeTimestamp(row.updated_at) ?? row.updated_at,
+  };
+}
+
+function normalizeSessionRows(rows: SessionRow[]): SessionRow[] {
+  return rows.map((row) => normalizeSessionRow(row) as SessionRow);
+}
+
 function normalizeProjectPathForProvider(provider: string, projectPath: string): string {
  void provider;
  return normalizeProjectPath(projectPath);
 }

 export const sessionsDb = {
+  /**
+   * Upserts one session row discovered on disk by a provider synchronizer.
+   *
+   * The given id is the provider-native session id. Rows are keyed by
+   * `provider_session_id` so a session that was first created by the app
+   * (with an app-allocated `session_id`) is updated in place once its
+   * transcript shows up on disk, instead of producing a duplicate row.
+   */
  createSession(
-    sessionId: string,
+    providerSessionId: string,
    provider: string,
    projectPath: string,
    customName?: string,
@@ -53,19 +85,54 @@ export const sessionsDb = {
    // since it's a foreign key in the sessions table.
    projectsDb.createProjectPath(normalizedProjectPath);

+    const existing = db
+      .prepare(
+        `SELECT session_id FROM sessions
+         WHERE provider_session_id = ? AND provider = ?
+         LIMIT 1`
+      )
+      .get(providerSessionId, provider) as { session_id: string } | undefined;
+
+    if (existing) {
+      db.prepare(
+        `UPDATE sessions SET
+           provider = ?,
+           updated_at = COALESCE(?, CURRENT_TIMESTAMP),
+           project_path = ?,
+           jsonl_path = ?,
+           isArchived = 0,
+           custom_name = COALESCE(?, custom_name)
+         WHERE session_id = ?`
+      ).run(
+        provider,
+        updatedAtValue,
+        normalizedProjectPath,
+        jsonlPath ?? null,
+        customName ?? null,
+        existing.session_id
+      );
+
+      return existing.session_id;
+    }
+
+    // Sessions created outside the app (directly via the provider CLI) are
+    // keyed by the provider-native id for both columns. The ON CONFLICT path
+    // covers legacy rows that predate the provider_session_id mapping.
    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))
+      `INSERT INTO sessions (session_id, provider, provider_session_id, 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,
+         provider_session_id = excluded.provider_session_id,
         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,
+      providerSessionId,
      provider,
+      providerSessionId,
      customName ?? null,
      normalizedProjectPath,
      jsonlPath ?? null,
@@ -73,9 +140,77 @@ export const sessionsDb = {
      updatedAtValue
    );

+    return providerSessionId;
+  },
+
+  /**
+   * Inserts one app-allocated session row before any provider run happens.
+   *
+   * The session gateway uses this when the frontend starts a brand-new chat:
+   * `session_id` is the stable app-facing id, while `provider_session_id`
+   * stays NULL until the provider runtime announces its own id and
+   * `assignProviderSessionId` records the mapping.
+   */
+  createAppSession(sessionId: string, provider: string, projectPath: string): string {
+    const db = getConnection();
+    const normalizedProjectPath = normalizeProjectPathForProvider(provider, projectPath);
+
+    projectsDb.createProjectPath(normalizedProjectPath);
+
+    db.prepare(
+      `INSERT INTO sessions (session_id, provider, provider_session_id, custom_name, project_path, jsonl_path, isArchived, created_at, updated_at)
+       VALUES (?, ?, NULL, NULL, ?, NULL, 0, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)`
+    ).run(sessionId, provider, normalizedProjectPath);
+
    return sessionId;
  },

+  /**
+   * Records the provider-native session id for one app-allocated session.
+   *
+   * If the filesystem watcher indexed the provider transcript before this
+   * mapping was recorded (a duplicate row keyed by the provider id exists),
+   * the duplicate is merged into the app row: its transcript path and name
+   * are adopted and the duplicate row is removed. Runs in a transaction so
+   * the sidebar can never observe both rows at once.
+   */
+  assignProviderSessionId(sessionId: string, providerSessionId: string): void {
+    const db = getConnection();
+
+    const merge = db.transaction(() => {
+      const duplicate = db
+        .prepare(
+          `SELECT ${SESSION_ROW_COLUMNS} FROM sessions
+           WHERE (session_id = ? OR provider_session_id = ?)
+             AND session_id <> ?
+           LIMIT 1`
+        )
+        .get(providerSessionId, providerSessionId, sessionId) as SessionRow | undefined;
+
+      if (duplicate) {
+        db.prepare('DELETE FROM sessions WHERE session_id = ?').run(duplicate.session_id);
+        db.prepare(
+          `UPDATE sessions SET
+             provider_session_id = ?,
+             jsonl_path = COALESCE(jsonl_path, ?),
+             custom_name = COALESCE(custom_name, ?),
+             updated_at = CURRENT_TIMESTAMP
+           WHERE session_id = ?`
+        ).run(providerSessionId, duplicate.jsonl_path, duplicate.custom_name, sessionId);
+        return;
+      }
+
+      db.prepare(
+        `UPDATE sessions SET
+           provider_session_id = ?,
+           updated_at = CURRENT_TIMESTAMP
+         WHERE session_id = ?`
+      ).run(providerSessionId, sessionId);
+    });
+
+    merge();
+  },
+
  updateSessionCustomName(sessionId: string, customName: string): void {
    const db = getConnection();
    db.prepare(
@@ -85,30 +220,91 @@ export const sessionsDb = {
    ).run(customName, sessionId);
  },

-  getSessionById(sessionId: string): SessionMetadataLookupRow | null {
+  getSessionById(sessionId: string): SessionRow | null {
    const db = getConnection();
    const row = db
      .prepare(
-        `SELECT session_id, provider, project_path, jsonl_path, custom_name, isArchived, created_at, updated_at
+        `SELECT ${SESSION_ROW_COLUMNS}
         FROM sessions
         WHERE session_id = ?
         ORDER BY updated_at DESC
         LIMIT 1`
      )
-      .get(sessionId) as SessionMetadataLookupRow | undefined;
+      .get(sessionId) as SessionRow | undefined;

-    return row ?? null;
+    return normalizeSessionRow(row) ?? null;
+  },
+
+  /**
+   * Resolves one session row through the provider-native id.
+   *
+   * The filesystem watcher only knows provider ids (they come from transcript
+   * file names), so it uses this lookup to translate disk artifacts back to
+   * the app-facing session row before broadcasting sidebar updates.
+   */
+  getSessionByProviderSessionId(providerSessionId: string): SessionRow | null {
+    const db = getConnection();
+    const row = db
+      .prepare(
+        `SELECT ${SESSION_ROW_COLUMNS}
+         FROM sessions
+         WHERE provider_session_id = ?
+         ORDER BY updated_at DESC
+         LIMIT 1`
+      )
+      .get(providerSessionId) as SessionRow | undefined;
+
+    return normalizeSessionRow(row) ?? null;
+  },
+
+  /**
+   * Finds the newest app-created session for a project that is still waiting
+   * for its provider-native id to be recorded.
+   *
+   * Primary intention: OpenCode can expose a new session in its shared
+   * `opencode.db` before the websocket runtime reports that same provider id
+   * back to our app. At that moment the sidebar already has an optimistic
+   * app-owned session row, but the watcher only knows the provider-native id.
+   *
+   * Without this lookup, the synchronizer would insert a second row keyed by
+   * the provider id, then `assignProviderSessionId()` would merge it a moment
+   * later. That eventually self-heals, but on slow networks the user can still
+   * briefly see two sidebar sessions for the same conversation.
+   *
+   * This helper lets the synchronizer claim the pending app row first, so the
+   * provider id is attached before any watcher-created row exists. The result
+   * is simpler than frontend dedupe and keeps the race resolved at the source.
+   */
+  findLatestPendingAppSession(provider: string, projectPath: string): SessionRow | null {
+    const db = getConnection();
+    const normalizedProjectPath = normalizeProjectPathForProvider(provider, projectPath);
+    const row = db
+      .prepare(
+        `SELECT ${SESSION_ROW_COLUMNS}
+         FROM sessions
+         WHERE provider = ?
+           AND project_path = ?
+           AND provider_session_id IS NULL
+           AND isArchived = 0
+         ORDER BY datetime(COALESCE(updated_at, created_at)) DESC, session_id DESC
+         LIMIT 1`
+      )
+      .get(provider, normalizedProjectPath) as SessionRow | undefined;
+
+    return normalizeSessionRow(row) ?? null;
  },

  getAllSessions(): SessionRow[] {
    const db = getConnection();
-    return db
+    const rows = db
      .prepare(
-        `SELECT session_id, provider, project_path, jsonl_path, custom_name, isArchived, created_at, updated_at
+        `SELECT ${SESSION_ROW_COLUMNS}
         FROM sessions
         WHERE isArchived = 0`
      )
      .all() as SessionRow[];
+
+    return normalizeSessionRows(rows);
  },

  /**
@@ -117,27 +313,31 @@ export const sessionsDb = {
   */
  getArchivedSessions(): SessionRow[] {
    const db = getConnection();
-    return db
+    const rows = db
      .prepare(
-        `SELECT session_id, provider, project_path, jsonl_path, custom_name, isArchived, created_at, updated_at
+        `SELECT ${SESSION_ROW_COLUMNS}
         FROM sessions
         WHERE isArchived = 1
         ORDER BY datetime(COALESCE(updated_at, created_at)) DESC, session_id DESC`
      )
      .all() as SessionRow[];
+
+    return normalizeSessionRows(rows);
  },

  getSessionsByProjectPath(projectPath: string): SessionRow[] {
    const db = getConnection();
    const normalizedProjectPath = normalizeProjectPath(projectPath);
-    return db
+    const rows = db
      .prepare(
-        `SELECT session_id, provider, project_path, jsonl_path, custom_name, isArchived, created_at, updated_at
+        `SELECT ${SESSION_ROW_COLUMNS}
         FROM sessions
         WHERE project_path = ?
           AND isArchived = 0`
      )
      .all(normalizedProjectPath) as SessionRow[];
+
+    return normalizeSessionRows(rows);
  },

  /**
@@ -147,21 +347,23 @@ export const sessionsDb = {
  getSessionsByProjectPathIncludingArchived(projectPath: string): SessionRow[] {
    const db = getConnection();
    const normalizedProjectPath = normalizeProjectPath(projectPath);
-    return db
+    const rows = db
      .prepare(
-        `SELECT session_id, provider, project_path, jsonl_path, custom_name, isArchived, created_at, updated_at
+        `SELECT ${SESSION_ROW_COLUMNS}
         FROM sessions
         WHERE project_path = ?`
      )
      .all(normalizedProjectPath) as SessionRow[];
+
+    return normalizeSessionRows(rows);
  },

  getSessionsByProjectPathPage(projectPath: string, limit: number, offset: number): SessionRow[] {
    const db = getConnection();
    const normalizedProjectPath = normalizeProjectPath(projectPath);
-    return db
+    const rows = db
      .prepare(
-        `SELECT session_id, provider, project_path, jsonl_path, custom_name, isArchived, created_at, updated_at
+        `SELECT ${SESSION_ROW_COLUMNS}
         FROM sessions
         WHERE project_path = ?
           AND isArchived = 0
@@ -169,6 +371,8 @@ export const sessionsDb = {
         LIMIT ? OFFSET ?`
      )
      .all(normalizedProjectPath, limit, offset) as SessionRow[];
+
+    return normalizeSessionRows(rows);
  },

  countSessionsByProjectPath(projectPath: string): number {
--- a/server/modules/database/schema.ts
+++ b/server/modules/database/schema.ts
@@ -83,6 +83,12 @@ export const SESSIONS_TABLE_SCHEMA_SQL = `
 CREATE TABLE IF NOT EXISTS sessions (
    session_id TEXT NOT NULL,
    provider TEXT NOT NULL DEFAULT 'claude',
+    -- The session id used by the provider CLI/SDK on disk (JSONL file name,
+    -- store.db folder, sqlite row id, ...). \`session_id\` is the stable
+    -- app-facing id that the frontend uses for the whole session lifetime;
+    -- \`provider_session_id\` is filled in once the provider announces its own
+    -- id mid-run, or equals \`session_id\` for sessions discovered on disk.
+    provider_session_id TEXT,
    custom_name TEXT,
    project_path TEXT,
    jsonl_path TEXT,
--- a/server/modules/database/repositories/projects.db.integration.test.ts
+++ b/server/modules/database/repositories/projects.db.integration.test.ts
--- a/server/modules/database/tests/sessions-provider-mapping.test.ts
+++ b/server/modules/database/tests/sessions-provider-mapping.test.ts
@@ -0,0 +1,108 @@
+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-mapping-'));
+  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('disk-discovered sessions are keyed by the provider id for both columns', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createSession('provider-abc', 'claude', '/workspace/demo', 'From Disk');
+
+    const row = sessionsDb.getSessionById('provider-abc');
+    assert.equal(row?.session_id, 'provider-abc');
+    assert.equal(row?.provider_session_id, 'provider-abc');
+
+    const byProviderId = sessionsDb.getSessionByProviderSessionId('provider-abc');
+    assert.equal(byProviderId?.session_id, 'provider-abc');
+  });
+});
+
+test('app sessions get the provider id assigned without creating a duplicate row', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createAppSession('app-id-1', 'claude', '/workspace/demo');
+    sessionsDb.assignProviderSessionId('app-id-1', 'provider-xyz');
+
+    // A later synchronizer pass that discovers the transcript on disk must
+    // update the app row in place instead of inserting a provider-keyed row.
+    const returnedId = sessionsDb.createSession(
+      'provider-xyz',
+      'claude',
+      '/workspace/demo',
+      'Synced Name',
+      undefined,
+      undefined,
+      '/fake/path/provider-xyz.jsonl',
+    );
+
+    assert.equal(returnedId, 'app-id-1');
+    assert.equal(sessionsDb.getAllSessions().length, 1);
+
+    const row = sessionsDb.getSessionById('app-id-1');
+    assert.equal(row?.provider_session_id, 'provider-xyz');
+    assert.equal(row?.jsonl_path, '/fake/path/provider-xyz.jsonl');
+  });
+});
+
+test('assignProviderSessionId merges a watcher-created duplicate into the app row', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createAppSession('app-id-2', 'codex', '/workspace/demo');
+
+    // Simulate the race: the filesystem watcher indexed the provider
+    // transcript before the runtime announced its session id to the gateway.
+    sessionsDb.createSession(
+      'provider-race',
+      'codex',
+      '/workspace/demo',
+      'Watcher Name',
+      undefined,
+      undefined,
+      '/fake/provider-race.jsonl',
+    );
+    assert.equal(sessionsDb.getAllSessions().length, 2);
+
+    sessionsDb.assignProviderSessionId('app-id-2', 'provider-race');
+
+    const rows = sessionsDb.getAllSessions();
+    assert.equal(rows.length, 1);
+    assert.equal(rows[0]?.session_id, 'app-id-2');
+    assert.equal(rows[0]?.provider_session_id, 'provider-race');
+    // Transcript path and name from the duplicate are adopted.
+    assert.equal(rows[0]?.jsonl_path, '/fake/provider-race.jsonl');
+    assert.equal(rows[0]?.custom_name, 'Watcher Name');
+  });
+});
+
+test('legacy provider-keyed rows stay resolvable through both lookups', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createSession('legacy-1', 'gemini', '/workspace/demo');
+
+    assert.equal(sessionsDb.getSessionById('legacy-1')?.provider, 'gemini');
+    assert.equal(sessionsDb.getSessionByProviderSessionId('legacy-1')?.session_id, 'legacy-1');
+  });
+});
--- a/server/modules/database/repositories/sessions.db.integration.test.ts
+++ b/server/modules/database/repositories/sessions.db.integration.test.ts
@@ -70,3 +70,15 @@ test('createSession reactivates archived rows when the session becomes active ag
    assert.equal(restoredSession?.isArchived, 0);
  });
 });
+
+test('repository reads normalize SQLite UTC timestamps to ISO strings', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createAppSession('session-timezone', 'claude', '/workspace/demo-project');
+
+    const row = sessionsDb.getSessionById('session-timezone');
+    assert.ok(row?.created_at.endsWith('Z'));
+    assert.ok(row?.updated_at.endsWith('Z'));
+    assert.match(row?.created_at ?? '', /^\d{4}-\d{2}-\d{2}T/);
+    assert.match(row?.updated_at ?? '', /^\d{4}-\d{2}-\d{2}T/);
+  });
+});
--- a/server/modules/projects/services/project-management.service.ts
+++ b/server/modules/projects/services/project-management.service.ts
@@ -30,10 +30,6 @@ type ProjectApiView = {
  isArchived: boolean;
  isStarred: boolean;
  sessions: [];
-  cursorSessions: [];
-  codexSessions: [];
-  geminiSessions: [];
-  opencodeSessions: [];
  sessionMeta: {
    hasMore: false;
    total: 0;
@@ -82,10 +78,6 @@ function mapProjectRowToApiView(projectRow: ProjectRepositoryRow): ProjectApiVie
    isArchived: Boolean(projectRow.isArchived),
    isStarred: Boolean(projectRow.isStarred),
    sessions: [],
-    cursorSessions: [],
-    codexSessions: [],
-    geminiSessions: [],
-    opencodeSessions: [],
    sessionMeta: {
      hasMore: false,
      total: 0,
--- a/server/modules/projects/services/projects-with-sessions-fetch.service.ts
+++ b/server/modules/projects/services/projects-with-sessions-fetch.service.ts
@@ -9,13 +9,12 @@ import { AppError } from '@/shared/utils.js';

 type SessionSummary = {
  id: string;
+  provider: string;
  summary: string;
  messageCount: number;
  lastActivity: string;
 };

-type SessionsByProvider = Record<'claude' | 'cursor' | 'codex' | 'gemini' | 'opencode', SessionSummary[]>;
-
 type SessionRepositoryRow = {
  provider: string;
  session_id: string;
@@ -31,10 +30,6 @@ export type ProjectListItem = {
  fullPath: string;
  isStarred: boolean;
  sessions: SessionSummary[];
-  cursorSessions: SessionSummary[];
-  codexSessions: SessionSummary[];
-  geminiSessions: SessionSummary[];
-  opencodeSessions: SessionSummary[];
  sessionMeta: {
    hasMore: boolean;
    total: number;
@@ -64,7 +59,7 @@ type SessionPaginationOptions = {
 };

 type ProjectSessionsPageResult = {
-  sessionsByProvider: SessionsByProvider;
+  sessions: SessionSummary[];
  total: number;
  hasMore: boolean;
 };
@@ -72,10 +67,6 @@ type ProjectSessionsPageResult = {
 export type ProjectSessionsPageApiView = {
  projectId: string;
  sessions: SessionSummary[];
-  cursorSessions: SessionSummary[];
-  codexSessions: SessionSummary[];
-  geminiSessions: SessionSummary[];
-  opencodeSessions: SessionSummary[];
  sessionMeta: {
    hasMore: boolean;
    total: number;
@@ -129,39 +120,18 @@ function normalizeSessionPagination(options: SessionPaginationOptions = {}): { l
 function mapSessionRowToSummary(row: SessionRepositoryRow): SessionSummary {
  return {
    id: row.session_id,
+    provider: row.provider,
    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),
+    sessions: rows.map(mapSessionRowToSummary),
    total: rows.length,
    hasMore: false,
  };
@@ -183,16 +153,17 @@ function readProjectSessionsPageByPath(
  const total = sessionsDb.countSessionsByProjectPath(projectPath);

  return {
-    sessionsByProvider: bucketSessionRowsByProvider(rows),
+    sessions: rows.map(mapSessionRowToSummary),
    total,
    hasMore: pagination.offset + rows.length < total,
  };
 }

-// Broadcast progress to all connected WebSocket clients
+// Broadcast progress to all connected WebSocket clients.
+// Uses the unified `kind` envelope like every other websocket frame.
 function broadcastProgress(progress: ProgressUpdate) {
  const message = JSON.stringify({
-    type: 'loading_progress',
+    kind: 'loading_progress',
    ...progress,
  });

@@ -204,7 +175,7 @@ function broadcastProgress(progress: ProgressUpdate) {
 }

 /**
- * Reads all projects from DB and returns provider-bucketed session summaries.
+ * Reads all projects from DB and returns normalized session summaries.
 */
 export async function getProjectsWithSessions(
  options: GetProjectsWithSessionsOptions = {}
@@ -252,11 +223,7 @@ export async function getProjectsWithSessions(
      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,
+      sessions: sessionsPage.sessions,
      sessionMeta: {
        hasMore: sessionsPage.hasMore,
        total: sessionsPage.total,
@@ -309,11 +276,7 @@ export async function getArchivedProjectsWithSessions(
      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,
+      sessions: sessionsPage.sessions,
      sessionMeta: {
        hasMore: sessionsPage.hasMore,
        total: sessionsPage.total,
@@ -342,11 +305,7 @@ export async function getProjectSessionsPage(
  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,
+    sessions: sessionsPage.sessions,
    sessionMeta: {
      hasMore: sessionsPage.hasMore,
      total: sessionsPage.total,
--- a/server/modules/providers/README.md
+++ b/server/modules/providers/README.md
@@ -83,7 +83,7 @@ The existing provider folders are `claude`, `codex`, `cursor`, `gemini`, and
 - 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 the `PROVIDER_ORDER` list in `public/api-docs.html` if the provider should appear in the 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.
--- a/server/modules/providers/index.ts
+++ b/server/modules/providers/index.ts
@@ -1,5 +1,6 @@
 export { sessionSynchronizerService } from './services/session-synchronizer.service.js';
 export { providerSkillsService } from './services/skills.service.js';
+export { providerMcpService } from './services/mcp.service.js';

 export { initializeSessionsWatcher } from './services/sessions-watcher.service.js';
 export { closeSessionsWatcher } from './services/sessions-watcher.service.js';
--- a/server/modules/providers/list/claude/claude-models.provider.ts
+++ b/server/modules/providers/list/claude/claude-models.provider.ts
@@ -20,6 +20,11 @@ export const CLAUDE_FALLBACK_MODELS: ProviderModelsDefinition = {
      label: 'Default (recommended)',
      description: 'Use the default model (currently Opus 4.8 (1M context)) · $5/$25 per Mtok',
    },
+    {
+      value: 'fable',
+      label: 'Fable',
+      description: 'Fable 5 · Most capable for your hardest and longest-running tasks · Uses your limits ~2× faster than Opus',
+    },
    {
      value: "sonnet",
      label: "Sonnet",
--- a/server/modules/providers/list/claude/claude-session-synchronizer.provider.ts
+++ b/server/modules/providers/list/claude/claude-session-synchronizer.provider.ts
@@ -111,7 +111,10 @@ export class ClaudeSessionSynchronizer implements IProviderSessionSynchronizer {
      return null;
    }

-    const existingSession = sessionsDb.getSessionById(parsed.sessionId);
+    // App-created sessions are keyed by an app id, so disk-discovered provider
+    // ids must be resolved through the provider-id mapping first.
+    const existingSession = sessionsDb.getSessionByProviderSessionId(parsed.sessionId)
+      ?? sessionsDb.getSessionById(parsed.sessionId);
    const existingSessionName = existingSession?.custom_name;
    if (existingSessionName && existingSessionName !== 'Untitled Claude Session') {
      return {
--- a/server/modules/providers/list/claude/claude-sessions.provider.ts
+++ b/server/modules/providers/list/claude/claude-sessions.provider.ts
@@ -5,7 +5,7 @@ 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 { createNormalizedMessage, generateMessageId, readObjectRecord, sliceTailPage } from '@/shared/utils.js';
 import { sessionsDb } from '@/modules/database/index.js';

 const PROVIDER = 'claude';
@@ -103,10 +103,13 @@ async function parseAgentTools(filePath: string): Promise<AnyRecord[]> {

 async function getSessionMessages(
  sessionId: string,
+  providerSessionId: string,
  limit: number | null,
  offset: number,
 ): Promise<ClaudeHistoryMessagesResult> {
  try {
+    // The DB row is keyed by the app-facing session id, while the JSONL rows
+    // on disk carry the provider-native id — both ids are needed here.
    const jsonLPath = sessionsDb.getSessionById(sessionId)?.jsonl_path;

    if (!jsonLPath) {
@@ -133,7 +136,7 @@ async function getSessionMessages(

      try {
        const entry = JSON.parse(line) as AnyRecord;
-        if (entry.sessionId === sessionId) {
+        if (entry.sessionId === providerSessionId) {
          messages.push(entry);
        }
      } catch {
@@ -553,12 +556,13 @@ export class ClaudeSessionsProvider implements IProviderSessions {
    options: FetchHistoryOptions = {},
  ): Promise<FetchHistoryResult> {
    const { limit = null, offset = 0 } = options;
+    const providerSessionId = options.providerSessionId ?? sessionId;

    let result: ClaudeHistoryResult;
    try {
      // Load full history first so `total` reflects frontend-normalized messages,
      // not raw JSONL records.
-      result = await getSessionMessages(sessionId, null, 0);
+      result = await getSessionMessages(sessionId, providerSessionId, null, 0);
    } catch (error) {
      const message = error instanceof Error ? error.message : String(error);
      console.warn(`[ClaudeProvider] Failed to load session ${sessionId}:`, message);
@@ -606,7 +610,6 @@ export class ClaudeSessionsProvider implements IProviderSessions {
      }
    }

-    const totalNormalized = normalized.length;
    let total = 0;
    for (const msg of normalized) {
      if (msg.kind !== 'tool_result') {
@@ -615,18 +618,10 @@ export class ClaudeSessionsProvider implements IProviderSessions {
    }
    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;
+    const { page, hasMore } = sliceTailPage(normalized, normalizedLimit, normalizedOffset);

    return {
-      messages,
+      messages: page,
      total,
      hasMore,
      offset: normalizedOffset,
--- a/server/modules/providers/list/codex/codex-session-synchronizer.provider.ts
+++ b/server/modules/providers/list/codex/codex-session-synchronizer.provider.ts
@@ -43,11 +43,12 @@ export class CodexSessionSynchronizer implements IProviderSessionSynchronizer {
        continue;
      }

-      const existingSession = sessionsDb.getSessionById(parsed.sessionId);
+      const existingSession = sessionsDb.getSessionByProviderSessionId(parsed.sessionId)
+        ?? 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);
+          sessionsDb.updateSessionCustomName(existingSession.session_id, parsed.sessionName);
        }
      }

@@ -120,7 +121,10 @@ export class CodexSessionSynchronizer implements IProviderSessionSynchronizer {
      return null;
    }

-    const existingSession = sessionsDb.getSessionById(parsed.sessionId);
+    // App-created sessions are keyed by an app id, so disk-discovered provider
+    // ids must be resolved through the provider-id mapping first.
+    const existingSession = sessionsDb.getSessionByProviderSessionId(parsed.sessionId)
+      ?? sessionsDb.getSessionById(parsed.sessionId);
    const existingSessionName = existingSession?.custom_name;
    if (existingSessionName && existingSessionName !== 'Untitled Codex Session') {
      return {
--- a/server/modules/providers/list/codex/codex-sessions.provider.ts
+++ b/server/modules/providers/list/codex/codex-sessions.provider.ts
@@ -4,7 +4,7 @@ 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';
+import { createNormalizedMessage, generateMessageId, readObjectRecord, sliceTailPage } from '@/shared/utils.js';

 const PROVIDER = 'codex';

@@ -552,7 +552,6 @@ export class CodexSessionsProvider implements IProviderSessions {
      }
    }

-    const totalNormalized = normalized.length;
    let total = 0;
    for (const msg of normalized) {
      if (msg.kind !== 'tool_result') {
@@ -561,18 +560,10 @@ export class CodexSessionsProvider implements IProviderSessions {
    }
    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;
+    const { page, hasMore } = sliceTailPage(normalized, normalizedLimit, normalizedOffset);

    return {
-      messages,
+      messages: page,
      total,
      hasMore,
      offset: normalizedOffset,
--- a/server/modules/providers/list/cursor/cursor-sessions.provider.ts
+++ b/server/modules/providers/list/cursor/cursor-sessions.provider.ts
@@ -9,6 +9,7 @@ import {
  generateMessageId,
  readObjectRecord,
  sanitizeLeafDirectoryName,
+  sliceTailPage,
 } from '@/shared/utils.js';

 const PROVIDER = 'cursor';
@@ -363,42 +364,32 @@ export class CursorSessionsProvider implements IProviderSessions {

  /**
   * Fetches and paginates Cursor session history from its project-scoped store.db.
+   *
+   * Pagination follows the shared tail contract (`sliceTailPage`): offset 0 is
+   * the most recent page, matching every other provider.
   */
  async fetchHistory(
    sessionId: string,
    options: FetchHistoryOptions = {},
  ): Promise<FetchHistoryResult> {
    const { projectPath = '', limit = null, offset = 0 } = options;
+    // The store.db folder on disk is named after the provider-native id, not
+    // the app-facing session id this method is addressed with.
+    const providerSessionId = options.providerSessionId ?? sessionId;

    try {
-      const blobs = await this.loadCursorBlobs(sessionId, projectPath);
+      const blobs = await this.loadCursorBlobs(providerSessionId, projectPath);
      const allNormalized = this.normalizeCursorBlobs(blobs, sessionId);
      const renderableMessages = allNormalized.filter((msg) => msg.kind !== 'tool_result');
      const total = renderableMessages.length;
-
-      if (limit !== null) {
-        const start = offset;
-        const page = limit === 0
-          ? []
-          : renderableMessages.slice(start, start + limit);
-        const hasMore = limit === 0
-          ? start < total
-          : start + limit < total;
-        return {
-          messages: page,
-          total,
-          hasMore,
-          offset,
-          limit,
-        };
-      }
+      const { page, hasMore } = sliceTailPage(renderableMessages, limit, offset);

      return {
-        messages: renderableMessages,
+        messages: page,
        total,
-        hasMore: false,
-        offset: 0,
-        limit: null,
+        hasMore,
+        offset,
+        limit,
      };
    } catch (error) {
      const message = error instanceof Error ? error.message : String(error);
--- a/server/modules/providers/list/gemini/gemini-models.provider.ts
+++ b/server/modules/providers/list/gemini/gemini-models.provider.ts
@@ -12,17 +12,14 @@ import {

 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-3.1-flash-lite-preview', label: 'Gemini 3.1 Flash Lite 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' },
+    { value: 'gemini-2.5-flash-lite', label: 'Gemini 2.5 Flash Lite' },
+    { value: 'gemma-4-31b-it', label: 'Gemma 4 31B IT' },
+    { value: 'gemma-4-26b-a4b-it', label: 'Gemma 4 26B A4B IT' },
  ],
-  DEFAULT: 'gemini-3.1-pro-preview',
+  DEFAULT: 'gemini-3-flash-preview',
 };

 export class GeminiProviderModels implements IProviderModels {
--- a/server/modules/providers/list/gemini/gemini-sessions.provider.ts
+++ b/server/modules/providers/list/gemini/gemini-sessions.provider.ts
@@ -5,7 +5,7 @@ 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';
+import { createNormalizedMessage, generateMessageId, readObjectRecord, sliceTailPage } from '@/shared/utils.js';

 const PROVIDER = 'gemini';

@@ -518,9 +518,9 @@ export class GeminiSessionsProvider implements IProviderSessions {

    const start = Math.max(0, offset);
    const pageLimit = limit === null ? null : Math.max(0, limit);
-    const messages = pageLimit === null
-      ? normalized.slice(start)
-      : normalized.slice(start, start + pageLimit);
+    // Tail pagination via the shared contract: offset 0 returns the most
+    // recent page, matching every other provider.
+    const { page, hasMore } = sliceTailPage(normalized, pageLimit, start);
    let total = 0;
    for (const msg of normalized) {
      if (msg.kind !== 'tool_result') {
@@ -529,9 +529,9 @@ export class GeminiSessionsProvider implements IProviderSessions {
    }

    return {
-      messages,
+      messages: page,
      total,
-      hasMore: pageLimit === null ? false : start + pageLimit < normalized.length,
+      hasMore,
      offset: start,
      limit: pageLimit,
      tokenUsage: result.tokenUsage,
--- a/server/modules/providers/list/opencode/opencode-session-synchronizer.provider.ts
+++ b/server/modules/providers/list/opencode/opencode-session-synchronizer.provider.ts
@@ -112,7 +112,21 @@ export class OpenCodeSessionSynchronizer implements IProviderSessionSynchronizer
    }

    const fallbackTitle = 'Untitled OpenCode Session';
-    const existingSession = sessionsDb.getSessionById(sessionId);
+    const pendingAppSession = sessionsDb.getSessionByProviderSessionId(sessionId)
+      ?? sessionsDb.getSessionById(sessionId)
+      ?? sessionsDb.findLatestPendingAppSession(this.provider, projectPath);
+    if (pendingAppSession && !pendingAppSession.provider_session_id) {
+      // Slow networks can let the sqlite watcher index opencode.db before the
+      // runtime reports its provider id back through the websocket mapping.
+      // Bind that id to the fresh app row first so the watcher does not create
+      // a temporary provider-id sidebar entry for the same session.
+      sessionsDb.assignProviderSessionId(pendingAppSession.session_id, sessionId);
+    }
+
+    // App-created sessions are keyed by an app id, so disk-discovered provider
+    // ids must be resolved through the provider-id mapping first.
+    const existingSession = sessionsDb.getSessionByProviderSessionId(sessionId)
+      ?? sessionsDb.getSessionById(sessionId);
    const existingName = existingSession?.custom_name;
    const nextName = existingName && existingName !== fallbackTitle
      ? existingName
@@ -120,7 +134,9 @@ export class OpenCodeSessionSynchronizer implements IProviderSessionSynchronizer

    // 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(
+    // Return the canonical stored row id so watcher-triggered sidebar updates
+    // stay on the app session once provider_session_id has already been mapped.
+    return sessionsDb.createSession(
      sessionId,
      this.provider,
      projectPath,
@@ -129,8 +145,6 @@ export class OpenCodeSessionSynchronizer implements IProviderSessionSynchronizer
      normalizeProviderTimestamp(row.time_updated ?? row.time_created),
      null,
    );
-
-    return sessionId;
  }

  private readFirstUserText(db: Database.Database, sessionId: string): string | undefined {
--- a/server/modules/providers/list/opencode/opencode-sessions.provider.ts
+++ b/server/modules/providers/list/opencode/opencode-sessions.provider.ts
@@ -12,6 +12,7 @@ import {
  readObjectRecord,
  readJsonRecord,
  readOptionalString,
+  sliceTailPage,
 } from '@/shared/utils.js';

 const PROVIDER = 'opencode';
@@ -325,6 +326,9 @@ export class OpenCodeSessionsProvider implements IProviderSessions {
    options: FetchHistoryOptions = {},
  ): Promise<FetchHistoryResult> {
    const { limit = null, offset = 0 } = options;
+    // OpenCode's shared sqlite database keys messages by the provider-native
+    // session id, not the app-facing id this method is addressed with.
+    const providerSessionId = options.providerSessionId ?? sessionId;
    const db = openOpenCodeDatabase();
    if (!db) {
      return { messages: [], total: 0, hasMore: false, offset: 0, limit: null };
@@ -349,27 +353,20 @@ export class OpenCodeSessionsProvider implements IProviderSessions {
          m.id,
          COALESCE(p.time_created, 0),
          p.id
-      `).all(sessionId) as OpenCodeHistoryRow[];
+      `).all(providerSessionId) as OpenCodeHistoryRow[];

      const normalized = this.normalizeHistoryRows(rows, sessionId);
-      const tokenUsage = aggregateOpenCodeSessionTokenUsage(db, sessionId);
+      const tokenUsage = aggregateOpenCodeSessionTokenUsage(db, providerSessionId);

      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),
-          );
+      const { page, hasMore } = sliceTailPage(normalized, normalizedLimit, normalizedOffset);

      return {
-        messages,
+        messages: page,
        total,
-        hasMore: normalizedLimit === null
-          ? false
-          : Math.max(0, total - normalizedOffset - normalizedLimit) > 0,
+        hasMore,
        offset: normalizedOffset,
        limit: normalizedLimit,
        tokenUsage,
--- a/server/modules/providers/provider.routes.ts
+++ b/server/modules/providers/provider.routes.ts
@@ -1,6 +1,7 @@
 import express, { type Request, type Response } from 'express';

 import { providerAuthService } from '@/modules/providers/services/provider-auth.service.js';
+import { providerCapabilitiesService } from '@/modules/providers/services/provider-capabilities.service.js';
 import { providerMcpService } from '@/modules/providers/services/mcp.service.js';
 import { providerModelsService } from '@/modules/providers/services/provider-models.service.js';
 import { providerSkillsService } from '@/modules/providers/services/skills.service.js';
@@ -382,7 +383,51 @@ router.post(
  }),
 );

+router.get(
+  '/capabilities',
+  asyncHandler(async (_req: Request, res: Response) => {
+    res.json(createApiSuccessResponse({
+      providers: providerCapabilitiesService.listAllProviderCapabilities(),
+    }));
+  }),
+);
+
+router.get(
+  '/:provider/capabilities',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    res.json(createApiSuccessResponse(
+      providerCapabilitiesService.getProviderCapabilities(provider),
+    ));
+  }),
+);
+
 // ----------------- Session routes -----------------
+/**
+ * Session gateway entry point: allocates the stable app-facing session id for
+ * a brand-new chat. The frontend must call this before the first `chat.send`
+ * so the session id in the URL, the store, and the websocket all agree from
+ * the very first message — there is no client-visible session-id handoff.
+ */
+router.post(
+  '/sessions',
+  asyncHandler(async (req: Request, res: Response) => {
+    const body = (req.body ?? {}) as Record<string, unknown>;
+    const provider = parseProvider(body.provider);
+    const projectPath = typeof body.projectPath === 'string' ? body.projectPath : '';
+    const result = sessionsService.createAppSession(provider, projectPath);
+    res.status(201).json(createApiSuccessResponse(result));
+  }),
+);
+
+router.get(
+  '/sessions/running',
+  asyncHandler(async (_req: Request, res: Response) => {
+    const sessions = sessionsService.listRunningSessions();
+    res.json(createApiSuccessResponse({ sessions }));
+  }),
+);
+
 router.get(
  '/sessions/archived',
  asyncHandler(async (_req: Request, res: Response) => {
@@ -459,7 +504,7 @@ router.get(
      limit,
      offset,
    });
-    res.json(result);
+    res.json(createApiSuccessResponse(result));
  }),
 );

--- a/server/modules/providers/services/mcp.service.ts
+++ b/server/modules/providers/services/mcp.service.ts
@@ -80,4 +80,30 @@ export const providerMcpService = {

    return results;
  },
+
+  /**
+   * Removes one MCP server from every provider. Mirrors `addMcpServerToAllProviders`
+   * by iterating the live provider registry, so callers stay in sync with which
+   * providers exist instead of maintaining their own provider list.
+   */
+  async removeMcpServerFromAllProviders(
+    input: { name: string; scope?: McpScope; workspacePath?: string },
+  ): Promise<Array<{ provider: LLMProvider; removed: boolean; error?: string }>> {
+    const results: Array<{ provider: LLMProvider; removed: boolean; error?: string }> = [];
+    const providers = providerRegistry.listProviders();
+    for (const provider of providers) {
+      try {
+        const result = await provider.mcp.removeServer(input);
+        results.push({ provider: provider.id, removed: result.removed });
+      } catch (error) {
+        results.push({
+          provider: provider.id,
+          removed: false,
+          error: error instanceof Error ? error.message : 'Unknown error',
+        });
+      }
+    }
+
+    return results;
+  },
 };
--- a/server/modules/providers/services/provider-capabilities.service.ts
+++ b/server/modules/providers/services/provider-capabilities.service.ts
@@ -0,0 +1,91 @@
+import type { LLMProvider } from '@/shared/types.js';
+
+/**
+ * Static, backend-owned description of what one provider integration supports.
+ *
+ * The frontend renders its composer UI (permission mode picker, image upload,
+ * abort button, ...) purely from this shape, which is what keeps the frontend
+ * free of per-provider conditionals. New provider features should be exposed
+ * here instead of branching on the provider id in React components.
+ */
+type ProviderCapabilities = {
+  provider: LLMProvider;
+  /** Permission modes the provider runtime understands, in cycle order. */
+  permissionModes: string[];
+  defaultPermissionMode: string;
+  /** Whether image attachments can be included in a chat.send. */
+  supportsImages: boolean;
+  /** Whether an in-flight run can be cancelled via chat.abort. */
+  supportsAbort: boolean;
+  /** Whether interactive tool permission prompts can reach the UI. */
+  supportsPermissionRequests: boolean;
+  /** Whether the token-usage endpoint has data for this provider. */
+  supportsTokenUsage: boolean;
+};
+
+/**
+ * The capability matrix mirrors what each runtime actually implements today:
+ * - permission modes match the option sets accepted by each CLI/SDK.
+ * - only the Claude SDK integration surfaces interactive permission requests.
+ * - Cursor has no token usage endpoint support (its store.db has no usage rows).
+ */
+const PROVIDER_CAPABILITIES: Record<LLMProvider, ProviderCapabilities> = {
+  claude: {
+    provider: 'claude',
+    permissionModes: ['default', 'auto', 'acceptEdits', 'bypassPermissions', 'plan'],
+    defaultPermissionMode: 'default',
+    supportsImages: true,
+    supportsAbort: true,
+    supportsPermissionRequests: true,
+    supportsTokenUsage: true,
+  },
+  cursor: {
+    provider: 'cursor',
+    permissionModes: ['default', 'acceptEdits', 'bypassPermissions', 'plan'],
+    defaultPermissionMode: 'default',
+    supportsImages: false,
+    supportsAbort: true,
+    supportsPermissionRequests: false,
+    supportsTokenUsage: false,
+  },
+  codex: {
+    provider: 'codex',
+    permissionModes: ['default', 'acceptEdits', 'bypassPermissions'],
+    defaultPermissionMode: 'default',
+    supportsImages: false,
+    supportsAbort: true,
+    supportsPermissionRequests: false,
+    supportsTokenUsage: true,
+  },
+  gemini: {
+    provider: 'gemini',
+    permissionModes: ['default', 'acceptEdits', 'bypassPermissions', 'plan'],
+    defaultPermissionMode: 'default',
+    supportsImages: false,
+    supportsAbort: true,
+    supportsPermissionRequests: false,
+    supportsTokenUsage: true,
+  },
+  opencode: {
+    provider: 'opencode',
+    permissionModes: ['default'],
+    defaultPermissionMode: 'default',
+    supportsImages: false,
+    supportsAbort: true,
+    supportsPermissionRequests: false,
+    supportsTokenUsage: true,
+  },
+};
+
+/**
+ * Application service exposing the provider capability matrix.
+ */
+export const providerCapabilitiesService = {
+  getProviderCapabilities(provider: LLMProvider): ProviderCapabilities {
+    return PROVIDER_CAPABILITIES[provider];
+  },
+
+  listAllProviderCapabilities(): ProviderCapabilities[] {
+    return Object.values(PROVIDER_CAPABILITIES);
+  },
+};
--- a/server/modules/providers/services/provider-models.service.ts
+++ b/server/modules/providers/services/provider-models.service.ts
@@ -17,7 +17,7 @@ import { readProviderSessionActiveModelChange } from '@/shared/utils.js';

 export const PROVIDER_MODELS_CACHE_TTL_MS = 3 * 24 * 60 * 60 * 1000;
 const PROVIDER_MODELS_CACHE_VERSION = 1;
-const UNCACHED_PROVIDERS = new Set<LLMProvider>(['claude']);
+const UNCACHED_PROVIDERS = new Set<LLMProvider>(['claude', 'gemini']);

 type ProviderModelsServiceDependencies = {
  resolveProvider?: (provider: LLMProvider) => Pick<IProvider, 'models'>;
--- a/server/modules/providers/services/sessions-watcher.service.ts
+++ b/server/modules/providers/services/sessions-watcher.service.ts
@@ -4,10 +4,11 @@ import { promises as fsPromises } from 'node:fs';

 import chokidar, { type FSWatcher } from 'chokidar';

+import { projectsDb, sessionsDb } from '@/modules/database/index.js';
 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';
+import { generateDisplayName } from '@/modules/projects/index.js';

 type WatcherEventType = 'add' | 'change';

@@ -58,6 +59,11 @@ const watchers: FSWatcher[] = [];
 type PendingWatcherUpdate = {
  providers: Set<LLMProvider>;
  changeTypes: Set<WatcherEventType>;
+  /**
+   * Provider-native session ids reported by the synchronizers. They are
+   * translated back to app-facing session rows at flush time, because the
+   * transcript file names on disk only ever contain provider ids.
+   */
  updatedSessionIds: Set<string>;
 };

@@ -131,6 +137,50 @@ function queuePendingWatcherUpdate(
  schedulePendingWatcherFlush();
 }

+/**
+ * Builds one `session_upserted` delta event for a provider-native session id.
+ *
+ * The event carries everything a sidebar needs to upsert the session in place
+ * (session summary plus owning-project metadata), so clients never need a full
+ * project-list refetch when a transcript file changes on disk. Returns `null`
+ * when the id cannot be resolved to an indexed session row.
+ */
+async function buildSessionUpsertedEvent(updatedProviderSessionId: string): Promise<string | null> {
+  const row = sessionsDb.getSessionByProviderSessionId(updatedProviderSessionId)
+    ?? sessionsDb.getSessionById(updatedProviderSessionId);
+  if (!row || row.isArchived) {
+    return null;
+  }
+
+  const projectPath = row.project_path;
+  const project = projectPath ? projectsDb.getProjectPath(projectPath) : null;
+  const displayName = project?.custom_project_name?.trim()
+    ? project.custom_project_name
+    : await generateDisplayName(path.basename(projectPath ?? '') || (projectPath ?? ''), projectPath);
+
+  return JSON.stringify({
+    kind: 'session_upserted',
+    sessionId: row.session_id,
+    provider: row.provider,
+    session: {
+      id: row.session_id,
+      summary: row.custom_name || '',
+      messageCount: 0,
+      lastActivity: row.updated_at ?? row.created_at ?? new Date().toISOString(),
+    },
+    project: project
+      ? {
+        projectId: project.project_id,
+        path: project.project_path,
+        fullPath: project.project_path,
+        displayName,
+        isStarred: Boolean(project.isStarred),
+      }
+      : null,
+    timestamp: new Date().toISOString(),
+  });
+}
+
 async function flushPendingWatcherUpdate(): Promise<void> {
  clearPendingWatcherFlushTimer();

@@ -149,33 +199,29 @@ async function flushPendingWatcherUpdate(): Promise<void> {
  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);
+    // Per-session deltas instead of full project snapshots: an upsert of one
+    // session can never clobber unrelated client state, so the frontend needs
+    // no "suppress updates while a run is active" protection logic.
+    const events: string[] = [];
+    for (const updatedSessionId of queuedUpdate.updatedSessionIds) {
+      const event = await buildSessionUpsertedEvent(updatedSessionId);
+      if (event) {
+        events.push(event);
      }
-    });
+    }
+
+    if (events.length > 0) {
+      connectedClients.forEach(client => {
+        if (client.readyState === WS_OPEN_STATE) {
+          for (const event of events) {
+            client.send(event);
+          }
+        }
+      });
+    }
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error);
-    console.error('Session watcher refresh failed while broadcasting projects_updated', { error: message });
+    console.error('Session watcher refresh failed while broadcasting session_upserted', { error: message });
  } finally {
    watcherRefreshInFlight = false;

--- a/server/modules/providers/services/sessions.service.ts
+++ b/server/modules/providers/services/sessions.service.ts
@@ -1,7 +1,9 @@
+import { randomUUID } from 'node:crypto';
 import fsp from 'node:fs/promises';
 import path from 'node:path';

 import { projectsDb, sessionsDb } from '@/modules/database/index.js';
+import { chatRunRegistry } from '@/modules/websocket/index.js';
 import { providerRegistry } from '@/modules/providers/provider.registry.js';
 import type {
  FetchHistoryOptions,
@@ -11,6 +13,12 @@ import type {
 } from '@/shared/types.js';
 import { AppError } from '@/shared/utils.js';

+type CreateAppSessionResult = {
+  sessionId: string;
+  provider: LLMProvider;
+  projectPath: string;
+};
+
 type ArchivedSessionListItem = {
  sessionId: string;
  provider: LLMProvider;
@@ -77,6 +85,21 @@ export const sessionsService = {
    return providerRegistry.listProviders().map((provider) => provider.id);
  },

+  /**
+   * Returns app-facing ids for provider runs that are currently processing.
+   *
+   * This is intentionally status-only: callers that only need sidebar activity
+   * indicators should not attach to chat streams or request replayed messages.
+   */
+  listRunningSessions(): Array<{
+    sessionId: string;
+    provider: LLMProvider;
+    startedAt: number;
+    lastSeq: number;
+  }> {
+    return chatRunRegistry.listRunningRuns();
+  },
+
  /**
   * Normalizes one provider-native event into frontend session message events.
   */
@@ -89,12 +112,43 @@ export const sessionsService = {
  },

  /**
-   * Fetches persisted history by session id.
+   * Allocates a stable app-facing session id before any provider run happens.
+   *
+   * This is the entry point of the session gateway: the frontend calls this
+   * (via `POST /api/providers/sessions`) when the user starts a brand-new
+   * chat, navigates to the returned id immediately, and the id never changes
+   * for the lifetime of the conversation. The provider-native id is mapped to
+   * this row later, when the provider runtime announces it mid-run.
+   */
+  createAppSession(provider: LLMProvider, projectPath: string): CreateAppSessionResult {
+    const normalizedProjectPath = projectPath.trim();
+    if (!normalizedProjectPath) {
+      throw new AppError('projectPath is required.', {
+        code: 'PROJECT_PATH_REQUIRED',
+        statusCode: 400,
+      });
+    }
+
+    const sessionId = randomUUID();
+    sessionsDb.createAppSession(sessionId, provider, normalizedProjectPath);
+
+    return {
+      sessionId,
+      provider,
+      projectPath: normalizedProjectPath,
+    };
+  },
+
+  /**
+   * Fetches persisted history by app session id.
   *
   * Provider and provider-specific lookup hints are resolved from the indexed
-   * session metadata in the database.
+   * session metadata in the database. The provider adapter receives the
+   * provider-native session id (the one written into transcripts on disk),
+   * and every returned message is remapped back to the app session id so
+   * provider ids never reach the frontend.
   */
-  fetchHistory(
+  async fetchHistory(
    sessionId: string,
    options: Pick<FetchHistoryOptions, 'limit' | 'offset'> = {},
  ): Promise<FetchHistoryResult> {
@@ -106,12 +160,33 @@ export const sessionsService = {
      });
    }

+    // App-created sessions that never produced a provider transcript yet
+    // (e.g. first message still streaming) simply have no history.
+    if (!session.provider_session_id) {
+      return {
+        messages: [],
+        total: 0,
+        hasMore: false,
+        offset: options.offset ?? 0,
+        limit: options.limit ?? null,
+      };
+    }
+
    const provider = session.provider as LLMProvider;
-    return providerRegistry.resolveProvider(provider).sessions.fetchHistory(sessionId, {
+    const result = await providerRegistry.resolveProvider(provider).sessions.fetchHistory(sessionId, {
      limit: options.limit ?? null,
      offset: options.offset ?? 0,
      projectPath: session.project_path ?? '',
+      providerSessionId: session.provider_session_id,
    });
+
+    return {
+      ...result,
+      messages: result.messages.map((message) => ({
+        ...message,
+        sessionId,
+      })),
+    };
  },

  /**
--- a/server/modules/providers/tests/opencode-sessions.test.ts
+++ b/server/modules/providers/tests/opencode-sessions.test.ts
@@ -272,6 +272,55 @@ test('OpenCode session synchronizer indexes sqlite sessions without deletable tr
  }
 });

+test('OpenCode session synchronizer returns the app session id once provider mapping exists', { concurrency: false }, async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'opencode-session-sync-mapped-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  await mkdir(workspacePath, { recursive: true });
+  const restoreHomeDir = patchHomeDir(tempRoot);
+
+  try {
+    await createOpenCodeDatabase(tempRoot, workspacePath);
+    await withIsolatedDatabase(() => {
+      sessionsDb.createAppSession('app-session-1', 'opencode', workspacePath);
+      sessionsDb.assignProviderSessionId('app-session-1', 'open-session-1');
+
+      const synchronizer = new OpenCodeSessionSynchronizer();
+      return synchronizer.synchronizeFile(path.join(tempRoot, '.local', 'share', 'opencode', 'opencode.db')).then((sessionId) => {
+        assert.equal(sessionId, 'app-session-1');
+        assert.equal(sessionsDb.getAllSessions().length, 1);
+        assert.equal(sessionsDb.getSessionById('app-session-1')?.provider_session_id, 'open-session-1');
+      });
+    });
+  } finally {
+    restoreHomeDir();
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
+test('OpenCode session synchronizer adopts the pending app session before watcher sync creates a duplicate', { concurrency: false }, async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'opencode-session-sync-race-'));
+  const workspacePath = path.join(tempRoot, 'workspace');
+  await mkdir(workspacePath, { recursive: true });
+  const restoreHomeDir = patchHomeDir(tempRoot);
+
+  try {
+    await createOpenCodeDatabase(tempRoot, workspacePath);
+    await withIsolatedDatabase(() => {
+      sessionsDb.createAppSession('app-session-race', 'opencode', workspacePath);
+
+      const synchronizer = new OpenCodeSessionSynchronizer();
+      return synchronizer.synchronizeFile(path.join(tempRoot, '.local', 'share', 'opencode', 'opencode.db')).then((sessionId) => {
+        assert.equal(sessionId, 'app-session-race');
+        assert.equal(sessionsDb.getAllSessions().length, 1);
+        assert.equal(sessionsDb.getSessionById('app-session-race')?.provider_session_id, 'open-session-1');
+      });
+    });
+  } 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({
--- a/server/modules/websocket/README.md
+++ b/server/modules/websocket/README.md
@@ -33,10 +33,12 @@ Benefits:
 |---|---|
 | `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/chat-websocket.service.ts` | Handles the `/ws` chat protocol (`chat.send` / `chat.abort` / `chat.subscribe` / `chat.permission-response`) |
+| `services/chat-run-registry.service.ts` | Tracks live provider runs per app session id: seq numbering, event replay buffer, provider-id mapping, completion state |
+| `services/chat-session-writer.service.ts` | Gateway writer handed to provider runtimes: remaps provider session ids to app ids, swallows `session_created`, assigns `seq` |
 | `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-writer.service.ts` | Adapts raw WebSocket to writer interface (`send`, `setSessionId`, `getSessionId`) for non-chat writer consumers |
 | `services/websocket-state.service.ts` | Holds shared chat client set and open-state constant |

 ## High-Level Architecture
@@ -52,12 +54,12 @@ flowchart LR
  D -->|other| H[close()]

  E --> I[connectedClients Set]
-  E --> J[WebSocketWriter]
+  E --> J[chatRunRegistry + ChatSessionWriter]
  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]
+  I --> M[projects.service loading_progress]
+  I --> N[sessions-watcher.service session_upserted]
 ```

 ## Connection Handshake + Routing
@@ -105,37 +107,41 @@ sequenceDiagram
 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`.
+2. Parse each incoming message with `parseIncomingJsonObject`.
+3. Dispatch by `data.type` (four message types, none provider-specific).
+4. On close, remove socket from `connectedClients`.
+
+### Session identity model
+
+The frontend only ever knows the **app session id** (allocated by
+`POST /api/providers/sessions` or discovered via the session index). The
+provider-native id (JSONL file name, CLI resume id) stays inside the backend:
+
+1. `chat.send` resolves the app id to `{ provider, provider_session_id, project_path }` from the sessions DB.
+2. The provider runtime receives the provider-native id for resume.
+3. The `ChatSessionWriter` remaps every outbound event back to the app id, and turns `session_created` announcements into a DB mapping update instead of forwarding them.

 ### Chat Message Dispatch

 ```mermaid
 flowchart TD
  A[Incoming WS message] --> B[parseIncomingJsonObject]
-  B -->|invalid| C[send {type:error}]
+  B -->|invalid| C[send kind:protocol_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]
+  D -->|chat.send| E[resolve session row -> startRun -> spawnFns provider]
+  D -->|chat.abort| F[abortFns provider + synthetic complete]
+  D -->|chat.subscribe| G[chat_subscribed ack + attach socket + replay events seq > lastSeq]
+  D -->|chat.permission-response| H[resolveToolApproval]
+  D -->|other| I[send kind:protocol_error]
 ```

 ### 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`.
+1. **Unified envelope**: every server-to-client frame carries a `kind` — either a provider `NormalizedMessage` kind or a gateway kind (`chat_subscribed`, `session_upserted`, `loading_progress`, `protocol_error`). There is no second `type`-based protocol.
+2. **Unified terminal lifecycle**: every provider run ends with exactly one `complete` message built by `createCompleteMessage()` (`server/shared/utils.ts`): `{ kind: "complete", sessionId, actualSessionId, exitCode, success, aborted }`. The chat handler emits a synthetic `complete` for runs that crash or get aborted, and the run registry drops duplicate completes.
+3. **Per-run event log**: every live event gets a monotonically increasing `seq`. `chat.subscribe { sessions: [{ sessionId, lastSeq }] }` re-attaches the live stream to the requesting socket (any provider, not just Claude) and replays events with `seq > lastSeq`. If the buffer no longer covers `lastSeq`, the client refreshes over REST.
+4. `chat_subscribed` includes `isProcessing` (replaces `check-session-status`) and `pendingPermissions` (replaces `get-pending-permissions`).

 ## `/shell` Terminal Flow

@@ -223,9 +229,9 @@ 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.
+Broadcasts `kind: loading_progress` while project snapshots are being built.
 2. `modules/providers/services/sessions-watcher.service.ts`
-Broadcasts `projects_updated` when provider session artifacts change.
+Broadcasts per-session `kind: session_upserted` deltas when provider session artifacts change (no full project snapshots).

 This design centralizes cross-module realtime fanout without requiring route-local references to WebSocket internals.

@@ -252,7 +258,7 @@ Current explicit close codes in this module:

 Other errors:

-1. Chat handler catches and emits `{ type: "error", error }`.
+1. Chat handler catches and emits `{ kind: "protocol_error", code, error }`.
 2. Shell handler catches and writes terminal-visible error output.
 3. Unknown websocket paths are closed immediately.

--- a/server/modules/websocket/index.ts
+++ b/server/modules/websocket/index.ts
@@ -1,2 +1,3 @@
 export { WS_OPEN_STATE, connectedClients } from './services/websocket-state.service.js';
 export { createWebSocketServer } from './services/websocket-server.service.js';
+export { chatRunRegistry } from './services/chat-run-registry.service.js';
--- a/server/modules/websocket/services/chat-run-registry.service.ts
+++ b/server/modules/websocket/services/chat-run-registry.service.ts
@@ -0,0 +1,327 @@
+import path from 'node:path';
+
+import { projectsDb, sessionsDb } from '@/modules/database/index.js';
+import { generateDisplayName } from '@/modules/projects/index.js';
+import { ChatSessionWriter } from '@/modules/websocket/services/chat-session-writer.service.js';
+import { connectedClients, WS_OPEN_STATE } from '@/modules/websocket/services/websocket-state.service.js';
+import type {
+  LLMProvider,
+  NormalizedMessage,
+  RealtimeClientConnection,
+} from '@/shared/types.js';
+
+type ChatRunStatus = 'running' | 'completed';
+
+/**
+ * One live (or recently finished) provider run for a single app session.
+ *
+ * State notes — why each mutable field is essential:
+ * - `providerSessionId`: the provider-native id captured mid-run. The abort
+ *   handler needs it to address the provider runtime, and the DB mapping is
+ *   written from it so history/resume work after the run.
+ * - `status`: drives `chat_subscribed.isProcessing`, prevents double sends
+ *   into the same session, and guards the synthetic-complete fallback in the
+ *   chat handler (only emitted when a runtime died without completing).
+ * - `lastSeq` / `events`: the per-run event log. Every live event gets a
+ *   monotonically increasing `seq` and is buffered so a reconnecting client
+ *   can replay exactly the events it missed via `chat.subscribe`.
+ */
+type ChatRun = {
+  appSessionId: string;
+  provider: LLMProvider;
+  providerSessionId: string | null;
+  status: ChatRunStatus;
+  lastSeq: number;
+  events: NormalizedMessage[];
+  writer: ChatSessionWriter;
+  startedAt: number;
+  completedAt: number | null;
+};
+
+/**
+ * How long a completed run stays available for replay. Covers the window
+ * between a run finishing and the client refreshing history over REST (for
+ * example when the browser tab was asleep while the run completed).
+ */
+const COMPLETED_RUN_RETENTION_MS = 5 * 60 * 1000;
+
+/**
+ * Upper bound on buffered events per run so a very long tool-heavy run cannot
+ * grow memory unbounded. When exceeded, the oldest events are dropped —
+ * a reconnecting client whose `lastSeq` predates the buffer falls back to a
+ * REST history refresh, which is always the authoritative source.
+ */
+const MAX_BUFFERED_EVENTS_PER_RUN = 5000;
+
+/**
+ * Active and recently-completed runs keyed by app session id.
+ *
+ * This map is the single in-memory source of truth for "is something running
+ * for this session" — the chat websocket handler, abort path, and subscribe
+ * path all consult it instead of asking each provider runtime individually.
+ */
+const runs = new Map<string, ChatRun>();
+
+async function broadcastCanonicalSessionUpsert(appSessionId: string): Promise<void> {
+  const row = sessionsDb.getSessionById(appSessionId);
+  if (!row || row.isArchived) {
+    return;
+  }
+
+  const projectPath = row.project_path;
+  const project = projectPath ? projectsDb.getProjectPath(projectPath) : null;
+  const displayName = project?.custom_project_name?.trim()
+    ? project.custom_project_name
+    : await generateDisplayName(path.basename(projectPath ?? '') || (projectPath ?? ''), projectPath);
+
+  const payload = JSON.stringify({
+    kind: 'session_upserted',
+    sessionId: row.session_id,
+    providerSessionId: row.provider_session_id,
+    provider: row.provider,
+    session: {
+      id: row.session_id,
+      summary: row.custom_name || '',
+      messageCount: 0,
+      lastActivity: row.updated_at ?? row.created_at ?? new Date().toISOString(),
+    },
+    project: project
+      ? {
+        projectId: project.project_id,
+        path: project.project_path,
+        fullPath: project.project_path,
+        displayName,
+        isStarred: Boolean(project.isStarred),
+      }
+      : null,
+    timestamp: new Date().toISOString(),
+  });
+
+  connectedClients.forEach((client) => {
+    if (client.readyState === WS_OPEN_STATE) {
+      client.send(payload);
+    }
+  });
+}
+
+function evictRunLater(appSessionId: string): void {
+  const timer = setTimeout(() => {
+    const run = runs.get(appSessionId);
+    if (run && run.status === 'completed') {
+      runs.delete(appSessionId);
+    }
+  }, COMPLETED_RUN_RETENTION_MS);
+
+  // Never keep the process alive just to evict a buffered run.
+  timer.unref?.();
+}
+
+/**
+ * Decorates one outbound live event for a run and records it in the event log.
+ *
+ * Responsibilities:
+ * 1. Remap `sessionId` (and `actualSessionId` on `complete`) to the stable
+ *    app session id — provider-native ids never leave the backend.
+ * 2. Assign the next `seq` so clients can detect/replay gaps.
+ * 3. Buffer the event for `chat.subscribe` replay.
+ * 4. Flip the run to `completed` when the terminal `complete` event passes by.
+ */
+function decorateAndRecordEvent(run: ChatRun, message: NormalizedMessage): NormalizedMessage | null {
+  // Exactly-one-complete contract: when a run is aborted the chat handler
+  // emits the terminal `complete` immediately, but the killed runtime may
+  // still emit its own `complete` from its exit handler moments later.
+  // Whichever arrives first wins; the duplicate is dropped here.
+  if (message.kind === 'complete' && run.status === 'completed') {
+    return null;
+  }
+
+  run.lastSeq += 1;
+
+  const outbound: NormalizedMessage = {
+    ...message,
+    sessionId: run.appSessionId,
+    seq: run.lastSeq,
+  };
+
+  if (message.kind === 'complete') {
+    // The provider may report its own id here; the frontend only ever knows
+    // the app id, so the "actual" id is by definition the app id as well.
+    outbound.actualSessionId = run.appSessionId;
+    run.status = 'completed';
+    run.completedAt = Date.now();
+    evictRunLater(run.appSessionId);
+  }
+
+  run.events.push(outbound);
+  if (run.events.length > MAX_BUFFERED_EVENTS_PER_RUN) {
+    run.events.splice(0, run.events.length - MAX_BUFFERED_EVENTS_PER_RUN);
+  }
+
+  return outbound;
+}
+
+/**
+ * Records the provider-native session id for a run and persists the
+ * app-id-to-provider-id mapping so history fetches and future resumes can
+ * address the provider transcript.
+ *
+ * Called from the gateway writer when the runtime either calls
+ * `setSessionId(...)` or emits its `session_created` event — whichever
+ * happens first wins; later calls with the same id are no-ops.
+ */
+function recordProviderSessionId(run: ChatRun, providerSessionId: string): void {
+  if (!providerSessionId || run.providerSessionId === providerSessionId) {
+    return;
+  }
+
+  run.providerSessionId = providerSessionId;
+
+  try {
+    sessionsDb.assignProviderSessionId(run.appSessionId, providerSessionId);
+    void broadcastCanonicalSessionUpsert(run.appSessionId).catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error('[ChatRunRegistry] Failed to broadcast canonical session mapping', {
+        appSessionId: run.appSessionId,
+        providerSessionId,
+        error: message,
+      });
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error('[ChatRunRegistry] Failed to persist provider session id mapping', {
+      appSessionId: run.appSessionId,
+      providerSessionId,
+      error: message,
+    });
+  }
+}
+
+/**
+ * Registry of live provider runs keyed by the stable app session id.
+ *
+ * The registry is what makes the websocket protocol provider-independent:
+ * every run gets a `ChatSessionWriter` that remaps provider-native session
+ * ids to the app id, assigns `seq` numbers, and buffers events for replay —
+ * regardless of which provider runtime produced them.
+ */
+export const chatRunRegistry = {
+  /**
+   * Starts tracking a run and returns it, or `null` when a run is already in
+   * progress for the session (callers must reject the duplicate send).
+   */
+  startRun(input: {
+    appSessionId: string;
+    provider: LLMProvider;
+    providerSessionId: string | null;
+    connection: RealtimeClientConnection;
+    userId: string | number | null;
+  }): ChatRun | null {
+    const existing = runs.get(input.appSessionId);
+    if (existing && existing.status === 'running') {
+      return null;
+    }
+
+    const run: ChatRun = {
+      appSessionId: input.appSessionId,
+      provider: input.provider,
+      providerSessionId: input.providerSessionId,
+      status: 'running',
+      lastSeq: 0,
+      events: [],
+      writer: null as unknown as ChatSessionWriter,
+      startedAt: Date.now(),
+      completedAt: null,
+    };
+
+    run.writer = new ChatSessionWriter({
+      connection: input.connection,
+      userId: input.userId,
+      provider: input.provider,
+      providerSessionId: input.providerSessionId,
+      onProviderSessionId: (providerSessionId) => {
+        recordProviderSessionId(run, providerSessionId);
+      },
+      decorateOutboundEvent: (message) => decorateAndRecordEvent(run, message),
+    });
+
+    runs.set(input.appSessionId, run);
+    return run;
+  },
+
+  getRun(appSessionId: string): ChatRun | undefined {
+    return runs.get(appSessionId);
+  },
+
+  isProcessing(appSessionId: string): boolean {
+    return runs.get(appSessionId)?.status === 'running';
+  },
+
+  listRunningRuns(): Array<{
+    sessionId: string;
+    provider: LLMProvider;
+    startedAt: number;
+    lastSeq: number;
+  }> {
+    return Array.from(runs.values())
+      .filter((run) => run.status === 'running')
+      .map((run) => ({
+        sessionId: run.appSessionId,
+        provider: run.provider,
+        startedAt: run.startedAt,
+        lastSeq: run.lastSeq,
+      }));
+  },
+
+  /**
+   * Re-attaches a run's outbound stream to a (new) websocket connection.
+   *
+   * This is the generic replacement for the Claude-only writer reconnect:
+   * after a page refresh the new socket subscribes and immediately starts
+   * receiving the still-running stream, for every provider.
+   */
+  attachConnection(appSessionId: string, connection: RealtimeClientConnection): boolean {
+    const run = runs.get(appSessionId);
+    if (!run) {
+      return false;
+    }
+
+    run.writer.updateWebSocket(connection);
+    return true;
+  },
+
+  /**
+   * Returns buffered events with `seq` greater than `afterSeq` for replay.
+   *
+   * An empty array with `run.lastSeq > afterSeq` not covered by the buffer
+   * means the buffer was truncated; the client should refresh over REST.
+   */
+  replayEvents(appSessionId: string, afterSeq: number): NormalizedMessage[] {
+    const run = runs.get(appSessionId);
+    if (!run) {
+      return [];
+    }
+
+    return run.events.filter((event) => typeof event.seq === 'number' && event.seq > afterSeq);
+  },
+
+  /**
+   * Emits a synthetic terminal `complete` if (and only if) the run is still
+   * marked running. Used when a provider runtime throws or resolves without
+   * having produced its own terminal event, and by the abort path.
+   */
+  completeRun(appSessionId: string, opts: { exitCode: number; aborted?: boolean }): void {
+    const run = runs.get(appSessionId);
+    if (!run || run.status !== 'running') {
+      return;
+    }
+
+    run.writer.sendComplete(opts);
+  },
+
+  /**
+   * Test-only escape hatch: clears every tracked run.
+   */
+  clearAll(): void {
+    runs.clear();
+  },
+};
--- a/server/modules/websocket/services/chat-session-writer.service.ts
+++ b/server/modules/websocket/services/chat-session-writer.service.ts
@@ -0,0 +1,145 @@
+import { WS_OPEN_STATE } from '@/modules/websocket/services/websocket-state.service.js';
+import type {
+  LLMProvider,
+  NormalizedMessage,
+  RealtimeClientConnection,
+} from '@/shared/types.js';
+import { createCompleteMessage, readObjectRecord } from '@/shared/utils.js';
+
+type ChatSessionWriterOptions = {
+  connection: RealtimeClientConnection;
+  userId: string | number | null;
+  provider: LLMProvider;
+  /** Provider-native id when resuming an existing session, otherwise null. */
+  providerSessionId: string | null;
+  /**
+   * Invoked the moment the provider runtime reveals its native session id
+   * (either via `setSessionId` or a `session_created` event). The registry
+   * persists the app-id-to-provider-id mapping from this callback.
+   */
+  onProviderSessionId: (providerSessionId: string) => void;
+  /**
+   * Remaps/sequences/buffers one outbound live event. Implemented by the chat
+   * run registry; the writer never forwards a provider event untouched.
+   * Returns `null` when the event must be dropped (duplicate terminal
+   * `complete` after an abort already completed the run).
+   */
+  decorateOutboundEvent: (message: NormalizedMessage) => NormalizedMessage | null;
+};
+
+/**
+ * Gateway writer handed to provider runtimes instead of a raw websocket writer.
+ *
+ * It exposes the exact same surface as `WebSocketWriter` (`send`,
+ * `setSessionId`, `getSessionId`, `updateWebSocket`, `userId`,
+ * `isWebSocketWriter`) so the provider runtimes (`claude-sdk.js`,
+ * `cursor-cli.js`, ...) need zero changes — but everything that flows through
+ * it is translated from the provider's world into the app's protocol:
+ *
+ * - `session_created` events are swallowed and turned into a provider-id
+ *   mapping; the frontend never learns provider-native ids.
+ * - every other event gets `sessionId` remapped to the app session id and a
+ *   per-run `seq` assigned before being forwarded.
+ * - `setSessionId(...)` calls (used by runtimes to label captured ids) are
+ *   intercepted and recorded as the provider-id mapping as well.
+ */
+export class ChatSessionWriter {
+  ws: RealtimeClientConnection;
+  userId: string | number | null;
+  /**
+   * Some runtimes feature-detect their writer with this flag; keep it so the
+   * gateway writer is a drop-in replacement for `WebSocketWriter`.
+   */
+  isWebSocketWriter = true;
+
+  private readonly options: ChatSessionWriterOptions;
+  /**
+   * The provider-native session id as the runtime knows it. Kept locally
+   * (besides the registry) because runtimes read it back via `getSessionId()`
+   * to label their own outgoing events — those labels are remapped on send
+   * anyway, but the runtime-visible value must stay provider-native.
+   */
+  private providerSessionId: string | null;
+
+  constructor(options: ChatSessionWriterOptions) {
+    this.options = options;
+    this.ws = options.connection;
+    this.userId = options.userId;
+    this.providerSessionId = options.providerSessionId;
+  }
+
+  send(data: unknown): void {
+    const record = readObjectRecord(data);
+    if (!record || typeof record.kind !== 'string') {
+      // Provider runtimes only emit kind-based normalized messages. Anything
+      // else indicates a programming error; drop it rather than leaking an
+      // un-remapped payload to the client.
+      console.error('[ChatSessionWriter] Dropping non-normalized outbound payload', data);
+      return;
+    }
+
+    const message = record as NormalizedMessage;
+
+    if (message.kind === 'session_created') {
+      const announcedId =
+        typeof message.newSessionId === 'string' && message.newSessionId
+          ? message.newSessionId
+          : message.sessionId;
+      if (announcedId) {
+        this.captureProviderSessionId(announcedId);
+      }
+      // Swallowed on purpose: the frontend already has the stable app session
+      // id, so there is no client-side handoff to perform anymore.
+      return;
+    }
+
+    const outbound = this.options.decorateOutboundEvent(message);
+    if (outbound) {
+      this.forward(outbound);
+    }
+  }
+
+  /**
+   * Emits the synthetic terminal `complete` for runs that ended without one
+   * (runtime crash before completing, or user abort).
+   */
+  sendComplete(opts: { exitCode: number; aborted?: boolean }): void {
+    const message = createCompleteMessage({
+      provider: this.options.provider,
+      sessionId: this.providerSessionId,
+      exitCode: opts.exitCode,
+      aborted: opts.aborted,
+    });
+    const outbound = this.options.decorateOutboundEvent(message);
+    if (outbound) {
+      this.forward(outbound);
+    }
+  }
+
+  updateWebSocket(newConnection: RealtimeClientConnection): void {
+    this.ws = newConnection;
+  }
+
+  setSessionId(sessionId: string): void {
+    this.captureProviderSessionId(sessionId);
+  }
+
+  getSessionId(): string | null {
+    return this.providerSessionId;
+  }
+
+  private captureProviderSessionId(providerSessionId: string): void {
+    if (!providerSessionId || this.providerSessionId === providerSessionId) {
+      return;
+    }
+
+    this.providerSessionId = providerSessionId;
+    this.options.onProviderSessionId(providerSessionId);
+  }
+
+  private forward(message: NormalizedMessage): void {
+    if (this.ws.readyState === WS_OPEN_STATE) {
+      this.ws.send(JSON.stringify(message));
+    }
+  }
+}
--- a/server/modules/websocket/services/chat-websocket.service.ts
+++ b/server/modules/websocket/services/chat-websocket.service.ts
@@ -1,40 +1,35 @@
 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 { sessionsDb } from '@/modules/database/index.js';
+import { chatRunRegistry } from '@/modules/websocket/services/chat-run-registry.service.js';
+import { connectedClients, WS_OPEN_STATE } from '@/modules/websocket/services/websocket-state.service.js';
 import type {
  AnyRecord,
  AuthenticatedWebSocketRequest,
  LLMProvider,
 } from '@/shared/types.js';
-import { createNormalizedMessage, parseIncomingJsonObject } from '@/shared/utils.js';
+import { 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';
+/**
+ * One provider runtime entry point. All five runtimes share this signature,
+ * which lets the chat handler dispatch through a provider-keyed map instead
+ * of provider-specific branches.
+ */
+type ProviderSpawnFn = (
+  command: string,
+  options: AnyRecord,
+  writer: unknown
+) => Promise<unknown>;

 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;
+  /** Provider runtimes keyed by provider id. */
+  spawnFns: Record<LLMProvider, ProviderSpawnFn>;
+  /**
+   * Abort functions keyed by provider id. They are addressed with the
+   * provider-native session id (that is how runtimes key their process maps).
+   * The Claude abort is async; the rest are sync — both shapes are accepted.
+   */
+  abortFns: Record<LLMProvider, (providerSessionId: string) => boolean | Promise<boolean>>;
  resolveToolApproval: (
    requestId: string,
    payload: {
@@ -44,31 +39,10 @@ type ChatWebSocketDependencies = {
      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;
+  /** Claude-only today: pending tool approvals included in `chat_subscribed`. */
+  getPendingApprovalsForSession: (providerSessionId: string) => 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.
@@ -92,8 +66,258 @@ function readRequestUserId(
  return null;
 }

+function sendJson(ws: WebSocket, payload: unknown): void {
+  if (ws.readyState === WS_OPEN_STATE) {
+    ws.send(JSON.stringify(payload));
+  }
+}
+
+/**
+ * Reports a protocol-level failure to the requesting client.
+ *
+ * Protocol errors deliberately use their own `kind` (instead of the provider
+ * `error` message kind) so the frontend can distinguish "your request was
+ * invalid" from "the model run produced an error" without inspecting text.
+ */
+function sendProtocolError(
+  ws: WebSocket,
+  code: string,
+  error: string,
+  sessionId?: string
+): void {
+  sendJson(ws, {
+    kind: 'protocol_error',
+    code,
+    error,
+    sessionId: sessionId ?? null,
+    timestamp: new Date().toISOString(),
+  });
+}
+
+function readRequiredSessionId(data: AnyRecord): string | null {
+  const sessionId = typeof data.sessionId === 'string' ? data.sessionId.trim() : '';
+  return sessionId.length > 0 ? sessionId : null;
+}
+
+/**
+ * Handles `chat.send`: resolves the session row (provider, project path, and
+ * provider-native id all come from the database — never from the client),
+ * registers the run, and dispatches to the provider runtime.
+ */
+async function handleChatSend(
+  ws: WebSocket,
+  userId: string | number | null,
+  data: AnyRecord,
+  dependencies: ChatWebSocketDependencies
+): Promise<void> {
+  const sessionId = readRequiredSessionId(data);
+  if (!sessionId) {
+    sendProtocolError(ws, 'SESSION_ID_REQUIRED', 'chat.send requires a sessionId.');
+    return;
+  }
+
+  const session = sessionsDb.getSessionById(sessionId);
+  if (!session) {
+    sendProtocolError(
+      ws,
+      'SESSION_NOT_FOUND',
+      `Session "${sessionId}" was not found. Create it via POST /api/providers/sessions first.`,
+      sessionId
+    );
+    return;
+  }
+
+  const provider = session.provider as LLMProvider;
+  const spawnFn = dependencies.spawnFns[provider];
+  if (!spawnFn) {
+    sendProtocolError(ws, 'UNSUPPORTED_PROVIDER', `Provider "${provider}" is not available.`, sessionId);
+    return;
+  }
+
+  const run = chatRunRegistry.startRun({
+    appSessionId: sessionId,
+    provider,
+    providerSessionId: session.provider_session_id,
+    connection: ws,
+    userId,
+  });
+
+  if (!run) {
+    sendProtocolError(
+      ws,
+      'RUN_IN_PROGRESS',
+      `Session "${sessionId}" already has a run in progress.`,
+      sessionId
+    );
+    return;
+  }
+
+  const clientOptions = (data.options ?? {}) as AnyRecord;
+  const command = typeof data.content === 'string' ? data.content : '';
+
+  // The provider runtimes receive the provider-native session id (that is the
+  // id their CLI/SDK understands for resume). Brand-new sessions have no
+  // provider id yet, so the runtime starts fresh and announces one, which the
+  // gateway writer captures and maps back to the app session id.
+  const runtimeOptions: AnyRecord = {
+    ...clientOptions,
+    sessionId: session.provider_session_id ?? undefined,
+    resume: Boolean(session.provider_session_id),
+    cwd: clientOptions.cwd ?? session.project_path ?? undefined,
+    projectPath: session.project_path ?? clientOptions.projectPath,
+  };
+
+  try {
+    await spawnFn(command, runtimeOptions, run.writer);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[Chat] Provider runtime "${provider}" failed`, { sessionId, error: message });
+  } finally {
+    // Safety net: a runtime that crashed (or resolved) without emitting its
+    // terminal `complete` would otherwise leave the session stuck in
+    // "processing" forever on every connected client.
+    chatRunRegistry.completeRun(sessionId, { exitCode: 1 });
+  }
+}
+
+/**
+ * Handles `chat.abort`: cancels the run for one app session and emits the
+ * terminal `complete` on its behalf (runtimes skip their own complete for
+ * aborted runs, and the registry drops any duplicate).
+ */
+async function handleChatAbort(
+  ws: WebSocket,
+  data: AnyRecord,
+  dependencies: ChatWebSocketDependencies
+): Promise<void> {
+  const sessionId = readRequiredSessionId(data);
+  if (!sessionId) {
+    sendProtocolError(ws, 'SESSION_ID_REQUIRED', 'chat.abort requires a sessionId.');
+    return;
+  }
+
+  const run = chatRunRegistry.getRun(sessionId);
+  if (!run || run.status !== 'running') {
+    sendProtocolError(ws, 'NO_ACTIVE_RUN', `Session "${sessionId}" has no active run.`, sessionId);
+    return;
+  }
+
+  const abortFn = dependencies.abortFns[run.provider];
+  let success = false;
+  if (abortFn && run.providerSessionId) {
+    success = Boolean(await abortFn(run.providerSessionId));
+  }
+
+  chatRunRegistry.completeRun(sessionId, {
+    exitCode: success ? 0 : 1,
+    aborted: true,
+  });
+}
+
+/**
+ * Handles `chat.subscribe`: for each requested session, reports whether a run
+ * is processing, re-attaches the live stream to this socket, replays missed
+ * events (seq > lastSeq), and includes pending permission requests.
+ *
+ * This single message replaces the old `check-session-status`,
+ * `get-pending-permissions`, and Claude-only writer reconnect flows.
+ */
+function handleChatSubscribe(
+  ws: WebSocket,
+  data: AnyRecord,
+  dependencies: ChatWebSocketDependencies
+): void {
+  const targets = Array.isArray(data.sessions) ? data.sessions : [];
+
+  for (const target of targets) {
+    if (!target || typeof target !== 'object') {
+      continue;
+    }
+
+    const sessionId = typeof (target as AnyRecord).sessionId === 'string'
+      ? ((target as AnyRecord).sessionId as string).trim()
+      : '';
+    if (!sessionId) {
+      continue;
+    }
+
+    const lastSeqRaw = (target as AnyRecord).lastSeq;
+    const lastSeq = typeof lastSeqRaw === 'number' && Number.isFinite(lastSeqRaw)
+      ? Math.max(0, Math.floor(lastSeqRaw))
+      : 0;
+
+    const run = chatRunRegistry.getRun(sessionId);
+    const isProcessing = chatRunRegistry.isProcessing(sessionId);
+
+    // Future live events for this run should land on the socket that asked —
+    // this is what makes mid-stream page refreshes work for all providers.
+    if (isProcessing) {
+      chatRunRegistry.attachConnection(sessionId, ws);
+    }
+
+    // Pending approvals are tracked under the provider-native id inside the
+    // Claude runtime; remap their sessionId so the client only sees app ids.
+    const pendingPermissions = (run?.providerSessionId
+      ? dependencies.getPendingApprovalsForSession(run.providerSessionId)
+      : []
+    ).map((approval) =>
+      approval && typeof approval === 'object'
+        ? { ...(approval as AnyRecord), sessionId }
+        : approval,
+    );
+
+    sendJson(ws, {
+      kind: 'chat_subscribed',
+      sessionId,
+      isProcessing,
+      lastSeq: run?.lastSeq ?? 0,
+      pendingPermissions,
+      timestamp: new Date().toISOString(),
+    });
+
+    // Replay only for RUNNING runs, strictly after the ack. Completed runs
+    // are fully persisted to the provider transcript and served over REST —
+    // replaying them (e.g. after a page reload where the client's lastSeq is
+    // 0) would duplicate messages the history fetch already returned.
+    if (isProcessing) {
+      for (const event of chatRunRegistry.replayEvents(sessionId, lastSeq)) {
+        sendJson(ws, event);
+      }
+    }
+  }
+}
+
+/**
+ * Handles `chat.permission-response`: forwards a tool-approval decision to the
+ * pending approval resolver (Claude is the only provider with interactive
+ * approvals today, but the message is intentionally provider-neutral).
+ */
+function handlePermissionResponse(data: AnyRecord, dependencies: ChatWebSocketDependencies): void {
+  if (typeof data.requestId !== 'string' || data.requestId.length === 0) {
+    return;
+  }
+
+  dependencies.resolveToolApproval(data.requestId, {
+    allow: Boolean(data.allow),
+    updatedInput: data.updatedInput,
+    message: typeof data.message === 'string' ? data.message : undefined,
+    rememberEntry: data.rememberEntry,
+  });
+}
+
 /**
 * Handles authenticated chat websocket messages used by the main chat panel.
+ *
+ * Inbound protocol (client to server):
+ * - `chat.send`                { sessionId, content, options? }
+ * - `chat.abort`               { sessionId }
+ * - `chat.subscribe`           { sessions: [{ sessionId, lastSeq? }] }
+ * - `chat.permission-response` { requestId, allow, updatedInput?, message?, rememberEntry? }
+ *
+ * Outbound protocol (server to client): every frame is `kind`-based — either
+ * a provider `NormalizedMessage` (with `seq`) or a gateway event
+ * (`chat_subscribed`, `session_upserted`, `loading_progress`,
+ * `protocol_error`).
 */
 export function handleChatConnection(
  ws: WebSocket,
@@ -103,7 +327,7 @@ export function handleChatConnection(
  console.log('[INFO] Chat WebSocket connected');
  connectedClients.add(ws);

-  const writer = new WebSocketWriter(ws, readRequestUserId(request));
+  const userId = readRequestUserId(request);

  ws.on('message', async (rawMessage) => {
    try {
@@ -112,169 +336,30 @@ export function handleChatConnection(
        throw new Error('Invalid websocket payload');
      }

-      const data = parsed as ChatIncomingMessage;
-      const messageType = data.type;
-      if (!messageType) {
-        throw new Error('Message type is required');
-      }
+      const data = parsed as AnyRecord;
+      const messageType = typeof data.type === 'string' ? data.type : '';

-      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(),
-          },
-        });
+      switch (messageType) {
+        case 'chat.send':
+          await handleChatSend(ws, userId, data, dependencies);
+          return;
+        case 'chat.abort':
+          await handleChatAbort(ws, data, dependencies);
+          return;
+        case 'chat.subscribe':
+          handleChatSubscribe(ws, data, dependencies);
+          return;
+        case 'chat.permission-response':
+          handlePermissionResponse(data, dependencies);
+          return;
+        default:
+          sendProtocolError(ws, 'UNKNOWN_MESSAGE_TYPE', `Unknown message type "${messageType}".`);
+          return;
      }
    } catch (error) {
      const message = error instanceof Error ? error.message : String(error);
      console.error('[ERROR] Chat WebSocket error:', message);
-      writer.send({
-        type: 'error',
-        error: message,
-      });
+      sendProtocolError(ws, 'INTERNAL_ERROR', message);
    }
  });

--- a/server/modules/websocket/services/desktop-agent-websocket.service.ts
+++ b/server/modules/websocket/services/desktop-agent-websocket.service.ts
@@ -0,0 +1,42 @@
+import type { WebSocket } from 'ws';
+
+import { desktopAgentRelay } from '@/modules/computer-use/index.js';
+import type { AuthenticatedWebSocketRequest } from '@/shared/types.js';
+import { parseIncomingJsonObject } from '@/shared/utils.js';
+
+/**
+ * Handles the `/desktop-agent` websocket — the inbound side of the cloud
+ * Computer Use relay. A linked CloudCLI desktop app connects here and registers
+ * itself as the executor for this hosted environment. The server then forwards
+ * `computer_*` actions via `desktopAgentRelay`, and the agent returns results as
+ * `computer_relay_result` frames correlated by `id`.
+ */
+export function handleDesktopAgentConnection(
+  ws: WebSocket,
+  request: AuthenticatedWebSocketRequest
+): void {
+  const label = request.user?.username ? `desktop:${request.user.username}` : 'desktop-agent';
+  console.log('[INFO] Desktop agent websocket connected:', label);
+  desktopAgentRelay.register(ws, label);
+
+  ws.on('message', (rawMessage) => {
+    const data = parseIncomingJsonObject(rawMessage);
+    if (!data) {
+      return;
+    }
+    const kind = typeof data.kind === 'string' ? data.kind : typeof data.type === 'string' ? data.type : '';
+    if (kind === 'computer_relay_result' && typeof data.id === 'string') {
+      desktopAgentRelay.handleResult(
+        data.id,
+        (data as Record<string, unknown>).result,
+        typeof (data as Record<string, unknown>).error === 'string'
+          ? ((data as Record<string, unknown>).error as string)
+          : undefined
+      );
+    }
+  });
+
+  ws.on('close', () => {
+    console.log('[INFO] Desktop agent websocket disconnected:', label);
+  });
+}
--- a/server/modules/websocket/services/shell-websocket.service.ts
+++ b/server/modules/websocket/services/shell-websocket.service.ts
@@ -35,7 +35,10 @@ const PTY_SESSION_TIMEOUT = 30 * 60 * 1000;
 const SHELL_URL_PARSE_BUFFER_LIMIT = 32768;

 type ShellWebSocketDependencies = {
-  getSessionById: (sessionId: string) => { cliSessionId?: string } | null | undefined;
+  resolveProviderSessionId: (
+    sessionId: string,
+    provider: string,
+  ) => string | null | undefined;
  stripAnsiSequences: (content: string) => string;
  normalizeDetectedUrl: (url: string) => string | null;
  extractUrlsFromText: (content: string) => string[];
@@ -76,6 +79,36 @@ function parseShellMessage(rawMessage: RawData): ShellIncomingMessage | null {
  return payload as ShellIncomingMessage;
 }

+const SAFE_SESSION_ID_PATTERN = /^[a-zA-Z0-9_.\-:]+$/;
+
+function resolveResumeSessionId(
+  message: ShellIncomingMessage,
+  dependencies: ShellWebSocketDependencies
+): string {
+  const hasSession = readBoolean(message.hasSession);
+  const sessionId = readString(message.sessionId);
+  const provider = readString(message.provider, 'claude');
+
+  if (!hasSession || !sessionId) {
+    return '';
+  }
+
+  let resumeSessionId: string | null | undefined;
+  try {
+    resumeSessionId = dependencies.resolveProviderSessionId(sessionId, provider);
+  } catch (error) {
+    console.error('Failed to resolve provider session ID:', error);
+    resumeSessionId = undefined;
+  }
+
+  const resolvedSessionId = resumeSessionId === undefined ? sessionId : resumeSessionId;
+  if (!resolvedSessionId || !SAFE_SESSION_ID_PATTERN.test(resolvedSessionId)) {
+    return '';
+  }
+
+  return resolvedSessionId;
+}
+
 /**
 * Resolves provider command line for plain shell and agent-backed shell modes.
 */
@@ -84,10 +117,9 @@ function buildShellCommand(
  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 resumeSessionId = resolveResumeSessionId(message, dependencies);
  const isPlainShell =
    readBoolean(message.isPlainShell) ||
    (!!initialCommand && !hasSession) ||
@@ -98,58 +130,43 @@ function buildShellCommand(
  }

  if (provider === 'cursor') {
-    if (hasSession && sessionId) {
-      return `cursor-agent --resume="${sessionId}"`;
+    if (resumeSessionId) {
+      return `cursor-agent --resume="${resumeSessionId}"`;
    }
    return 'cursor-agent';
  }

  if (provider === 'codex') {
-    if (hasSession && sessionId) {
+    if (resumeSessionId) {
      if (os.platform() === 'win32') {
-        return `codex resume "${sessionId}"; if ($LASTEXITCODE -ne 0) { codex }`;
+        return `codex resume "${resumeSessionId}"; if ($LASTEXITCODE -ne 0) { codex }`;
      }
-      return `codex resume "${sessionId}" || codex`;
+      return `codex resume "${resumeSessionId}" || 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}"`;
+    if (resumeSessionId) {
+      return `${command} --resume "${resumeSessionId}"`;
    }
    return command;
  }

  if (provider === 'opencode') {
-    if (hasSession && sessionId) {
-      return `opencode --session "${sessionId}"`;
+    if (resumeSessionId) {
+      return `opencode --session "${resumeSessionId}"`;
    }
    return initialCommand || 'opencode';
  }

  const command = initialCommand || 'claude';
-  if (hasSession && sessionId) {
+  if (resumeSessionId) {
    if (os.platform() === 'win32') {
-      return `claude --resume "${sessionId}"; if ($LASTEXITCODE -ne 0) { claude }`;
+      return `claude --resume "${resumeSessionId}"; if ($LASTEXITCODE -ne 0) { claude }`;
    }
-    return `claude --resume "${sessionId}" || claude`;
+    return `claude --resume "${resumeSessionId}" || claude`;
  }
  return command;
 }
@@ -261,6 +278,7 @@ export function handleShellConnection(
        }

        const shellCommand = buildShellCommand(data, dependencies);
+        const resumeSessionId = resolveResumeSessionId(data, dependencies);
        const shell = os.platform() === 'win32' ? 'powershell.exe' : 'bash';
        const shellArgs =
          os.platform() === 'win32' ? ['-Command', shellCommand] : ['-c', shellCommand];
@@ -406,8 +424,8 @@ export function handleShellConnection(
                  : provider === 'opencode'
                    ? 'OpenCode'
                  : 'Claude';
-          welcomeMsg = hasSession
-            ? `\x1b[36mResuming ${providerName} session ${sessionId} in: ${projectPath}\x1b[0m\r\n`
+          welcomeMsg = hasSession && resumeSessionId
+            ? `\x1b[36mResuming ${providerName} session ${resumeSessionId} in: ${projectPath}\x1b[0m\r\n`
            : `\x1b[36mStarting new ${providerName} session in: ${projectPath}\x1b[0m\r\n`;
        }

--- a/server/modules/websocket/services/websocket-server.service.ts
+++ b/server/modules/websocket/services/websocket-server.service.ts
@@ -6,6 +6,7 @@ import { handleChatConnection } from '@/modules/websocket/services/chat-websocke
 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 { handleDesktopAgentConnection } from '@/modules/websocket/services/desktop-agent-websocket.service.js';
 import type { AuthenticatedWebSocketRequest } from '@/shared/types.js';

 type WebSocketServerDependencies = {
@@ -63,6 +64,11 @@ export function createWebSocketServer(
      return;
    }

+    if (pathname === '/desktop-agent') {
+      handleDesktopAgentConnection(ws, incomingRequest);
+      return;
+    }
+
    if (pathname.startsWith('/plugin-ws/')) {
      handlePluginWsProxy(ws, pathname, dependencies.getPluginPort);
      return;
--- a/server/modules/websocket/tests/chat-run-registry.test.ts
+++ b/server/modules/websocket/tests/chat-run-registry.test.ts
@@ -0,0 +1,244 @@
+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, initializeDatabase, sessionsDb } from '@/modules/database/index.js';
+import { chatRunRegistry } from '@/modules/websocket/services/chat-run-registry.service.js';
+import { connectedClients } from '@/modules/websocket/services/websocket-state.service.js';
+
+/**
+ * Minimal stand-in for a websocket connection: collects every JSON frame the
+ * gateway writer forwards so assertions can inspect the outbound protocol.
+ */
+class FakeConnection {
+  readyState = 1; // WS_OPEN_STATE
+  frames: Array<Record<string, unknown>> = [];
+
+  send(data: string): void {
+    this.frames.push(JSON.parse(data) as Record<string, unknown>);
+  }
+}
+
+async function withIsolatedDatabase(runTest: () => void | Promise<void>): Promise<void> {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const tempDirectory = await mkdtemp(path.join(tmpdir(), 'chat-run-registry-'));
+  const databasePath = path.join(tempDirectory, 'auth.db');
+
+  closeConnection();
+  process.env.DATABASE_PATH = databasePath;
+  await initializeDatabase();
+
+  try {
+    await runTest();
+  } finally {
+    connectedClients.clear();
+    chatRunRegistry.clearAll();
+    closeConnection();
+    if (previousDatabasePath === undefined) {
+      delete process.env.DATABASE_PATH;
+    } else {
+      process.env.DATABASE_PATH = previousDatabasePath;
+    }
+    await rm(tempDirectory, { recursive: true, force: true });
+  }
+}
+
+test('live events are remapped to the app session id and sequenced', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createAppSession('app-run-1', 'claude', '/workspace/demo');
+    const connection = new FakeConnection();
+    const run = chatRunRegistry.startRun({
+      appSessionId: 'app-run-1',
+      provider: 'claude',
+      providerSessionId: null,
+      connection,
+      userId: 'user-1',
+    });
+    assert.ok(run);
+
+    run.writer.send({ kind: 'stream_delta', provider: 'claude', sessionId: 'provider-id-9', content: 'hello' });
+    run.writer.send({ kind: 'text', provider: 'claude', sessionId: 'provider-id-9', content: 'hello world' });
+
+    assert.equal(connection.frames.length, 2);
+    assert.equal(connection.frames[0]?.sessionId, 'app-run-1');
+    assert.equal(connection.frames[0]?.seq, 1);
+    assert.equal(connection.frames[1]?.sessionId, 'app-run-1');
+    assert.equal(connection.frames[1]?.seq, 2);
+  });
+});
+
+test('session_created is swallowed and persisted as the provider-id mapping', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createAppSession('app-run-2', 'cursor', '/workspace/demo');
+    const connection = new FakeConnection();
+    connectedClients.add(connection as never);
+    const run = chatRunRegistry.startRun({
+      appSessionId: 'app-run-2',
+      provider: 'cursor',
+      providerSessionId: null,
+      connection,
+      userId: null,
+    });
+    assert.ok(run);
+
+    run.writer.send({
+      kind: 'session_created',
+      provider: 'cursor',
+      sessionId: 'cursor-native-7',
+      newSessionId: 'cursor-native-7',
+    });
+
+    // The provider-native event itself is never forwarded...
+    const sessionUpserts = connection.frames.filter((frame) => frame.kind === 'session_upserted');
+    assert.equal(sessionUpserts.length, 1);
+    assert.equal(sessionUpserts[0]?.sessionId, 'app-run-2');
+    assert.equal(sessionUpserts[0]?.providerSessionId, 'cursor-native-7');
+    // ...but the canonical mapping is recorded and persisted in the database.
+    assert.equal(run.providerSessionId, 'cursor-native-7');
+    assert.equal(sessionsDb.getSessionById('app-run-2')?.provider_session_id, 'cursor-native-7');
+  });
+});
+
+test('complete marks the run finished and duplicate completes are dropped', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createAppSession('app-run-3', 'codex', '/workspace/demo');
+    const connection = new FakeConnection();
+    const run = chatRunRegistry.startRun({
+      appSessionId: 'app-run-3',
+      provider: 'codex',
+      providerSessionId: null,
+      connection,
+      userId: null,
+    });
+    assert.ok(run);
+
+    run.writer.send({ kind: 'complete', provider: 'codex', sessionId: 'native-3', exitCode: 0 });
+    // Late duplicate from a killed runtime's exit handler.
+    run.writer.send({ kind: 'complete', provider: 'codex', sessionId: 'native-3', exitCode: 1 });
+
+    const completes = connection.frames.filter((frame) => frame.kind === 'complete');
+    assert.equal(completes.length, 1);
+    assert.equal(completes[0]?.actualSessionId, 'app-run-3');
+    assert.equal(chatRunRegistry.isProcessing('app-run-3'), false);
+
+    // completeRun is also a no-op once the run already completed.
+    chatRunRegistry.completeRun('app-run-3', { exitCode: 1 });
+    assert.equal(connection.frames.filter((frame) => frame.kind === 'complete').length, 1);
+  });
+});
+
+test('listRunningRuns returns only currently running app sessions', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createAppSession('app-run-7', 'claude', '/workspace/demo');
+    sessionsDb.createAppSession('app-run-8', 'codex', '/workspace/demo');
+    const connection = new FakeConnection();
+
+    const completedRun = chatRunRegistry.startRun({
+      appSessionId: 'app-run-7',
+      provider: 'claude',
+      providerSessionId: null,
+      connection,
+      userId: null,
+    });
+    assert.ok(completedRun);
+
+    const runningRun = chatRunRegistry.startRun({
+      appSessionId: 'app-run-8',
+      provider: 'codex',
+      providerSessionId: null,
+      connection,
+      userId: null,
+    });
+    assert.ok(runningRun);
+
+    chatRunRegistry.completeRun('app-run-7', { exitCode: 0 });
+
+    const runningSessions = chatRunRegistry.listRunningRuns();
+    assert.deepEqual(runningSessions.map((session) => session.sessionId), ['app-run-8']);
+    assert.equal(runningSessions[0]?.provider, 'codex');
+  });
+});
+
+test('replayEvents returns only events after the requested seq', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createAppSession('app-run-4', 'claude', '/workspace/demo');
+    const connection = new FakeConnection();
+    const run = chatRunRegistry.startRun({
+      appSessionId: 'app-run-4',
+      provider: 'claude',
+      providerSessionId: null,
+      connection,
+      userId: null,
+    });
+    assert.ok(run);
+
+    run.writer.send({ kind: 'stream_delta', provider: 'claude', sessionId: 'x', content: 'a' });
+    run.writer.send({ kind: 'stream_delta', provider: 'claude', sessionId: 'x', content: 'b' });
+    run.writer.send({ kind: 'stream_delta', provider: 'claude', sessionId: 'x', content: 'c' });
+
+    const replayed = chatRunRegistry.replayEvents('app-run-4', 1);
+    assert.deepEqual(replayed.map((event) => event.content), ['b', 'c']);
+    assert.deepEqual(replayed.map((event) => event.seq), [2, 3]);
+  });
+});
+
+test('attachConnection reroutes the live stream to a new socket', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createAppSession('app-run-5', 'gemini', '/workspace/demo');
+    const firstConnection = new FakeConnection();
+    const run = chatRunRegistry.startRun({
+      appSessionId: 'app-run-5',
+      provider: 'gemini',
+      providerSessionId: null,
+      connection: firstConnection,
+      userId: null,
+    });
+    assert.ok(run);
+
+    run.writer.send({ kind: 'stream_delta', provider: 'gemini', sessionId: 'g', content: 'before' });
+
+    const secondConnection = new FakeConnection();
+    assert.equal(chatRunRegistry.attachConnection('app-run-5', secondConnection), true);
+    run.writer.send({ kind: 'stream_delta', provider: 'gemini', sessionId: 'g', content: 'after' });
+
+    assert.deepEqual(firstConnection.frames.map((frame) => frame.content), ['before']);
+    assert.deepEqual(secondConnection.frames.map((frame) => frame.content), ['after']);
+  });
+});
+
+test('startRun rejects a second concurrent run for the same session', async () => {
+  await withIsolatedDatabase(() => {
+    sessionsDb.createAppSession('app-run-6', 'opencode', '/workspace/demo');
+    const connection = new FakeConnection();
+    const first = chatRunRegistry.startRun({
+      appSessionId: 'app-run-6',
+      provider: 'opencode',
+      providerSessionId: null,
+      connection,
+      userId: null,
+    });
+    assert.ok(first);
+
+    const second = chatRunRegistry.startRun({
+      appSessionId: 'app-run-6',
+      provider: 'opencode',
+      providerSessionId: null,
+      connection,
+      userId: null,
+    });
+    assert.equal(second, null);
+
+    // After the run finishes a new one is allowed again.
+    chatRunRegistry.completeRun('app-run-6', { exitCode: 0 });
+    const third = chatRunRegistry.startRun({
+      appSessionId: 'app-run-6',
+      provider: 'opencode',
+      providerSessionId: null,
+      connection,
+      userId: null,
+    });
+    assert.ok(third);
+  });
+});
--- a/server/openai-codex.js
+++ b/server/openai-codex.js
@@ -18,7 +18,7 @@ import { notifyRunFailed, notifyRunStopped } from './services/notification-orche
 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';
+import { createCompleteMessage, createNormalizedMessage } from './shared/utils.js';

 // Track active sessions
 const activeCodexSessions = new Map();
@@ -352,21 +352,26 @@ export async function queryCodex(command, options = {}, ws) {
      }
    }

-    // Send completion event
-    if (!terminalFailure) {
-      sendMessage(ws, createNormalizedMessage({
-        kind: 'complete',
-        actualSessionId: capturedSessionId || thread.id || sessionId || null,
-        sessionId: capturedSessionId || sessionId || null,
-        provider: 'codex'
-      }));
-      notifyRunStopped({
-        userId: ws?.userId || null,
+    // Send the terminal completion event — skipped for aborted runs, whose
+    // terminal `complete` (aborted: true) was already sent by abort-session.
+    const runSession = capturedSessionId ? activeCodexSessions.get(capturedSessionId) : null;
+    const runAborted = runSession?.status === 'aborted' || abortController.signal.aborted;
+    if (!runAborted) {
+      sendMessage(ws, createCompleteMessage({
        provider: 'codex',
        sessionId: capturedSessionId || sessionId || null,
-        sessionName: sessionSummary,
-        stopReason: 'completed'
-      });
+        actualSessionId: capturedSessionId || thread.id || sessionId || null,
+        exitCode: terminalFailure ? 1 : 0,
+      }));
+      if (!terminalFailure) {
+        notifyRunStopped({
+          userId: ws?.userId || null,
+          provider: 'codex',
+          sessionId: capturedSessionId || sessionId || null,
+          sessionName: sessionSummary,
+          stopReason: 'completed'
+        });
+      }
    }

  } catch (error) {
@@ -386,6 +391,11 @@ export async function queryCodex(command, options = {}, ws) {
        : error.message;

      sendMessage(ws, createNormalizedMessage({ kind: 'error', content: errorContent, sessionId: capturedSessionId || sessionId || null, provider: 'codex' }));
+      sendMessage(ws, createCompleteMessage({
+        provider: 'codex',
+        sessionId: capturedSessionId || sessionId || null,
+        exitCode: 1,
+      }));
      if (!terminalFailure) {
        notifyRunFailed({
          userId: ws?.userId || null,
--- a/server/opencode-cli.js
+++ b/server/opencode-cli.js
@@ -8,7 +8,7 @@ import { sessionsService } from './modules/providers/services/sessions.service.j
 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';
+import { createCompleteMessage, createNormalizedMessage, getOpenCodeDatabasePath } from './shared/utils.js';

 const spawnFunction = process.platform === 'win32' ? crossSpawn : spawn;

@@ -92,6 +92,9 @@ async function spawnOpenCode(command, options = {}, ws) {
    let stdoutLineBuffer = '';
    let terminalNotificationSent = false;
    let opencodeProcess = null;
+    // Unified lifecycle contract: exactly one terminal `complete` per run
+    // (close and error handlers can both fire for spawn failures).
+    let completeSent = false;

    const notifyTerminalState = ({ code = null, error = null } = {}) => {
      if (terminalNotificationSent) {
@@ -191,6 +194,10 @@ async function spawnOpenCode(command, options = {}, ws) {

    void providerModelsService.resolveResumeModel('opencode', sessionId, model).then((resolvedModel) => {
      const args = ['run', '--format', 'json'];
+      // OpenCode's `run` command owns workspace selection through `--dir`.
+      // Relying on the child-process cwd alone is not enough on Linux, where
+      // the CLI can still resolve the session under the server install dir.
+      args.push('--dir', workingDir);
      if (sessionId) {
        args.push('--session', sessionId);
      }
@@ -256,13 +263,12 @@ async function spawnOpenCode(command, options = {}, ws) {
          }));
        }

-        ws.send(createNormalizedMessage({
-          kind: 'complete',
-          exitCode: code,
-          isNewSession: !sessionId && !!command,
-          sessionId: finalSessionId,
-          provider: 'opencode',
-        }));
+        // Terminal complete — skipped for aborted runs (abort-session
+        // already sent the aborted complete on this run's behalf).
+        if (!completeSent && !opencodeProcess.aborted) {
+          completeSent = true;
+          ws.send(createCompleteMessage({ provider: 'opencode', sessionId: finalSessionId, exitCode: code }));
+        }

        if (code === 0) {
          notifyTerminalState({ code });
@@ -302,6 +308,10 @@ async function spawnOpenCode(command, options = {}, ws) {
          sessionId: finalSessionId,
          provider: 'opencode',
        }));
+        if (!completeSent && !opencodeProcess.aborted) {
+          completeSent = true;
+          ws.send(createCompleteMessage({ provider: 'opencode', sessionId: finalSessionId, exitCode: 1 }));
+        }
        notifyTerminalState({ error });
        reject(error);
      });
@@ -315,6 +325,9 @@ function abortOpenCodeSession(sessionId) {
    return false;
  }

+  // The abort handler sends the terminal complete (aborted: true); flag the
+  // process so its close handler does not emit a second one.
+  process.aborted = true;
  process.kill('SIGTERM');
  activeOpenCodeProcesses.delete(sessionId);
  return true;
--- a/server/opencode-cli.test.js
+++ b/server/opencode-cli.test.js
@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict';
-import { chmod, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { chmod, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
@@ -12,6 +12,11 @@ const findEnvKey = (name) =>
 async function createFakeOpenCodeExecutable(binDir) {
  const scriptPath = path.join(binDir, 'opencode.js');
  await writeFile(scriptPath, `
+const capturePath = process.env.OPENCODE_ARGS_CAPTURE;
+if (capturePath) {
+  require('node:fs').writeFileSync(capturePath, JSON.stringify(process.argv.slice(2)));
+}
+
 const events = [
  { type: 'text', sessionID: 'open-live-1', text: 'assistant response' },
  { type: 'step_finish', sessionID: 'open-live-1' },
@@ -35,10 +40,12 @@ for (const event of events) {

 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 argsCapturePath = path.join(tempRoot, 'opencode-args.json');
  const pathKey = findEnvKey('PATH');
  const pathExtKey = findEnvKey('PATHEXT');
  const previousPath = process.env[pathKey];
  const previousPathExt = process.env[pathExtKey];
+  const previousArgsCapture = process.env.OPENCODE_ARGS_CAPTURE;
  const messages = [];
  const writer = {
    userId: null,
@@ -54,6 +61,7 @@ test('spawnOpenCode emits session_created before normalized live messages for ne
  try {
    await createFakeOpenCodeExecutable(tempRoot);
    process.env[pathKey] = `${tempRoot}${path.delimiter}${previousPath || ''}`;
+    process.env.OPENCODE_ARGS_CAPTURE = argsCapturePath;
    if (process.platform === 'win32') {
      process.env[pathExtKey] = previousPathExt?.toUpperCase().includes('.CMD')
        ? previousPathExt
@@ -77,6 +85,11 @@ test('spawnOpenCode emits session_created before normalized live messages for ne
    assert.equal(streamEnd?.sessionId, 'open-live-1');
    assert.equal(complete?.sessionId, 'open-live-1');
    assert.equal(messages.some((message) => message.kind === 'error'), false);
+
+    const launchedArgs = JSON.parse(await readFile(argsCapturePath, 'utf8'));
+    assert.ok(Array.isArray(launchedArgs));
+    assert.deepEqual(launchedArgs.slice(0, 4), ['run', '--format', 'json', '--dir']);
+    assert.equal(launchedArgs[4], tempRoot);
  } finally {
    if (previousPath === undefined) {
      delete process.env[pathKey];
@@ -90,6 +103,12 @@ test('spawnOpenCode emits session_created before normalized live messages for ne
      process.env[pathExtKey] = previousPathExt;
    }

+    if (previousArgsCapture === undefined) {
+      delete process.env.OPENCODE_ARGS_CAPTURE;
+    } else {
+      process.env.OPENCODE_ARGS_CAPTURE = previousArgsCapture;
+    }
+
    await rm(tempRoot, { recursive: true, force: true });
  }
 });
--- a/server/routes/agent.js
+++ b/server/routes/agent.js
@@ -646,7 +646,7 @@ class ResponseCollector {
 *
 * @param {string} model - (Optional) Model identifier for providers.
 *
- *                        Claude models: 'sonnet' (default), 'opus', 'haiku', 'opusplan', 'sonnet[1m]'
+ *                        Claude models: 'sonnet' (default), 'opus', 'haiku', 'opusplan', 'sonnet[1m]', 'fable'
 *                        Cursor models: 'gpt-5' (default), 'gpt-5.2', 'gpt-5.2-high', 'sonnet-4.5', 'opus-4.5',
 *                                       'gemini-3-pro', 'composer-1', 'auto', 'gpt-5.1', 'gpt-5.1-high',
 *                                       'gpt-5.1-codex', 'gpt-5.1-codex-high', 'gpt-5.1-codex-max',
--- a/server/services/notification-orchestrator.js
+++ b/server/services/notification-orchestrator.js
@@ -98,6 +98,44 @@ function normalizeSessionName(sessionName) {
  return normalized.length > 80 ? `${normalized.slice(0, 77)}...` : normalized;
 }

+function rowMatchesProvider(row, provider) {
+  return row && (!provider || row.provider === provider);
+}
+
+function resolveSessionRow(sessionId, provider) {
+  if (!sessionId) {
+    return null;
+  }
+
+  const appSessionRow = sessionsDb.getSessionById(sessionId);
+  if (rowMatchesProvider(appSessionRow, provider)) {
+    return appSessionRow;
+  }
+
+  const providerSessionRow = sessionsDb.getSessionByProviderSessionId(sessionId);
+  if (rowMatchesProvider(providerSessionRow, provider)) {
+    return providerSessionRow;
+  }
+
+  return null;
+}
+
+function normalizeNotificationSession(event) {
+  if (!event?.sessionId || !event.provider || event.provider === 'system') {
+    return event;
+  }
+
+  const row = resolveSessionRow(event.sessionId, event.provider);
+  if (!row || row.session_id === event.sessionId) {
+    return event;
+  }
+
+  return {
+    ...event,
+    sessionId: row.session_id
+  };
+}
+
 function resolveSessionName(event) {
  const explicitSessionName = normalizeSessionName(event.meta?.sessionName);
  if (explicitSessionName) {
@@ -112,28 +150,29 @@ function resolveSessionName(event) {
 }

 function buildPushBody(event) {
+  const normalizedEvent = normalizeNotificationSession(event);
  const CODE_MAP = {
-    'permission.required': event.meta?.toolName
-      ? `Action Required: Tool "${event.meta.toolName}" needs approval`
+    'permission.required': normalizedEvent.meta?.toolName
+      ? `Action Required: Tool "${normalizedEvent.meta.toolName}" needs approval`
      : 'Action Required: A tool needs your approval',
-    'run.stopped': event.meta?.stopReason || 'Run Stopped: The run has stopped',
-    'run.failed': event.meta?.error ? `Run Failed: ${event.meta.error}` : 'Run Failed: The run encountered an error',
-    'agent.notification': event.meta?.message ? String(event.meta.message) : 'You have a new notification',
+    'run.stopped': normalizedEvent.meta?.stopReason || 'Run Stopped: The run has stopped',
+    'run.failed': normalizedEvent.meta?.error ? `Run Failed: ${normalizedEvent.meta.error}` : 'Run Failed: The run encountered an error',
+    'agent.notification': normalizedEvent.meta?.message ? String(normalizedEvent.meta.message) : 'You have a new notification',
    'push.enabled': 'Push notifications are now enabled!'
  };
-  const providerLabel = PROVIDER_LABELS[event.provider] || 'Assistant';
-  const sessionName = resolveSessionName(event);
-  const message = CODE_MAP[event.code] || 'You have a new notification';
+  const providerLabel = PROVIDER_LABELS[normalizedEvent.provider] || 'Assistant';
+  const sessionName = resolveSessionName(normalizedEvent);
+  const message = CODE_MAP[normalizedEvent.code] || 'You have a new notification';

  return {
    title: sessionName || 'CloudCLI',
    body: `${providerLabel}: ${message}`,
    data: {
-      sessionId: event.sessionId || null,
-      code: event.code,
-      provider: event.provider || null,
+      sessionId: normalizedEvent.sessionId || null,
+      code: normalizedEvent.code,
+      provider: normalizedEvent.provider || null,
      sessionName,
-      tag: `${event.provider || 'assistant'}:${event.sessionId || 'none'}:${event.code}`
+      tag: `${normalizedEvent.provider || 'assistant'}:${normalizedEvent.sessionId || 'none'}:${normalizedEvent.code}`
    }
  };
 }
@@ -175,15 +214,16 @@ function notifyUserIfEnabled({ userId, event }) {
    return;
  }

+  const normalizedEvent = normalizeNotificationSession(event);
  const preferences = notificationPreferencesDb.getPreferences(userId);
-  if (!shouldSendPush(preferences, event)) {
+  if (!shouldSendPush(preferences, normalizedEvent)) {
    return;
  }
-  if (isDuplicate(event)) {
+  if (isDuplicate(normalizedEvent)) {
    return;
  }

-  sendWebPush(userId, event).catch((err) => {
+  sendWebPush(userId, normalizedEvent).catch((err) => {
    console.error('Web push send error:', err);
  });
 }
--- a/server/services/tests/notification-orchestrator.test.js
+++ b/server/services/tests/notification-orchestrator.test.js
@@ -0,0 +1,80 @@
+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 webPush from 'web-push';
+
+import {
+  closeConnection,
+  initializeDatabase,
+  notificationPreferencesDb,
+  pushSubscriptionsDb,
+  sessionsDb,
+  userDb,
+} from '../modules/database/index.js';
+
+import { notifyRunStopped } from './notification-orchestrator.js';
+
+async function withIsolatedDatabase(runTest) {
+  const previousDatabasePath = process.env.DATABASE_PATH;
+  const tempDirectory = await mkdtemp(path.join(tmpdir(), 'notification-orchestrator-'));
+  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('push payload uses the app session id when notified with a provider session id', async () => {
+  const originalSendNotification = webPush.sendNotification;
+  const sentPayloads = [];
+
+  webPush.sendNotification = async (_subscription, payload) => {
+    sentPayloads.push(JSON.parse(payload));
+    return {};
+  };
+
+  try {
+    await withIsolatedDatabase(async () => {
+      const user = userDb.createUser('notify-user', 'hash');
+      const userId = Number(user.id);
+
+      notificationPreferencesDb.updatePreferences(userId, {
+        channels: { webPush: true },
+        events: { actionRequired: true, stop: true, error: true },
+      });
+      pushSubscriptionsDb.saveSubscription(userId, 'https://example.test/push', 'p256dh', 'auth');
+      sessionsDb.createAppSession('app-session-1', 'claude', '/workspace/demo');
+      sessionsDb.assignProviderSessionId('app-session-1', 'claude-native-1');
+
+      notifyRunStopped({
+        userId,
+        provider: 'claude',
+        sessionId: 'claude-native-1',
+        stopReason: 'completed',
+      });
+
+      await new Promise((resolve) => setImmediate(resolve));
+
+      assert.equal(sentPayloads.length, 1);
+      assert.equal(sentPayloads[0]?.data?.sessionId, 'app-session-1');
+      assert.match(sentPayloads[0]?.data?.tag, /app-session-1/);
+    });
+  } finally {
+    webPush.sendNotification = originalSendNotification;
+  }
+});
--- a/server/shared/tests/claude-cli-path.test.ts
+++ b/server/shared/tests/claude-cli-path.test.ts
--- a/server/shared/tests/slice-tail-page.test.ts
+++ b/server/shared/tests/slice-tail-page.test.ts
@@ -0,0 +1,42 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { sliceTailPage } from '@/shared/utils.js';
+
+const ITEMS = ['a', 'b', 'c', 'd', 'e'];
+
+test('offset 0 returns the most recent page', () => {
+  const { page, hasMore } = sliceTailPage(ITEMS, 2, 0);
+  assert.deepEqual(page, ['d', 'e']);
+  assert.equal(hasMore, true);
+});
+
+test('increasing offsets walk backwards in time', () => {
+  const { page, hasMore } = sliceTailPage(ITEMS, 2, 2);
+  assert.deepEqual(page, ['b', 'c']);
+  assert.equal(hasMore, true);
+});
+
+test('the oldest page reports hasMore false', () => {
+  const { page, hasMore } = sliceTailPage(ITEMS, 2, 4);
+  assert.deepEqual(page, ['a']);
+  assert.equal(hasMore, false);
+});
+
+test('null limit returns everything', () => {
+  const { page, hasMore } = sliceTailPage(ITEMS, null, 0);
+  assert.deepEqual(page, ITEMS);
+  assert.equal(hasMore, false);
+});
+
+test('offsets past the start return an empty page', () => {
+  const { page, hasMore } = sliceTailPage(ITEMS, 3, 10);
+  assert.deepEqual(page, []);
+  assert.equal(hasMore, false);
+});
+
+test('zero limit returns an empty page but keeps hasMore accurate', () => {
+  const { page, hasMore } = sliceTailPage(ITEMS, 0, 0);
+  assert.deepEqual(page, []);
+  assert.equal(hasMore, true);
+});
--- a/server/shared/types.ts
+++ b/server/shared/types.ts
@@ -68,7 +68,7 @@ export type AuthenticatedWebSocketRequest = IncomingMessage & {
 export type LLMProvider = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode';

 /**
- * One selectable model row (matches the documentation `public/modelConstants.js` option shape).
+ * One selectable model row in a provider model catalog.
 */
 export type ProviderModelOption = {
  value: string;
@@ -175,6 +175,30 @@ export type MessageKind =
  | 'interactive_prompt'
  | 'task_notification';

+/**
+ * Event kinds added by the chat gateway layer on top of provider message kinds.
+ *
+ * These are app-level realtime events (subscription acks, sidebar deltas,
+ * project loading progress, protocol failures) that are not produced by any
+ * provider adapter. Together with `MessageKind` they form the complete set of
+ * `kind` values a websocket client can receive, so the frontend only ever
+ * needs one kind-based switch.
+ */
+export type GatewayEventKind =
+  | 'chat_subscribed'
+  | 'session_upserted'
+  | 'loading_progress'
+  | 'protocol_error';
+
+/**
+ * Complete set of `kind` values emitted to websocket clients.
+ *
+ * Every server-to-client websocket frame carries a `kind` from this union.
+ * Provider runtimes emit `MessageKind` values; gateway services emit
+ * `GatewayEventKind` values.
+ */
+export type ServerEventKind = MessageKind | GatewayEventKind;
+
 /**
 * Provider-neutral message envelope used in REST responses and realtime channels.
 *
@@ -187,6 +211,13 @@ export type NormalizedMessage = {
  timestamp: string;
  provider: LLMProvider;
  kind: MessageKind;
+  /**
+   * Monotonic per-run sequence number assigned by the chat run registry when a
+   * live event is forwarded to the websocket. History messages loaded over
+   * REST do not carry it. Clients use it with `chat.subscribe` to replay only
+   * the live events they missed across websocket reconnects.
+   */
+  seq?: number;
  role?: 'user' | 'assistant';
  content?: string;
  /**
@@ -237,11 +268,18 @@ export type NormalizedMessage = {
 *
 * Consumers should pass provider-specific lookup hints (`projectPath`) only
 * when the selected provider requires them.
+ *
+ * `providerSessionId` is the provider-native session id from the sessions
+ * index (transcript file name / provider database key). Provider adapters
+ * must use it — never the app-facing session id they were called with — when
+ * matching transcript rows on disk, because app-created sessions use an
+ * app-allocated id that the provider has never seen.
 */
 export type FetchHistoryOptions = {
  projectPath?: string;
  limit?: number | null;
  offset?: number;
+  providerSessionId?: string;
 };

 /**
--- a/server/shared/utils.ts
+++ b/server/shared/utils.ts
@@ -346,6 +346,84 @@ export function createNormalizedMessage(fields: NormalizedMessageInput): Normali
  };
 }

+/**
+ * Build the unified terminal `complete` lifecycle message.
+ *
+ * Contract: every provider run ends with exactly one `complete` (the
+ * abort-session handler emits it on behalf of cancelled runs, so aborted runs
+ * must NOT emit their own). The frontend treats `complete` as the only
+ * terminal signal and never needs provider-specific handling:
+ *
+ * - `sessionId`     — the id the client knows this run by ('' if never discovered)
+ * - `actualSessionId` — canonical id after the run; equals `sessionId` unless
+ *                       the provider rewrote it mid-run
+ * - `exitCode`      — 0 on success; a missing/null code (e.g. killed process)
+ *                     is reported as failure
+ * - `success`       — exitCode === 0 and not aborted
+ * - `aborted`       — run was cancelled by the user
+ */
+export function createCompleteMessage(opts: {
+  provider: NormalizedMessage['provider'];
+  sessionId?: string | null;
+  actualSessionId?: string | null;
+  exitCode?: number | null;
+  aborted?: boolean;
+}): NormalizedMessage {
+  const exitCode = typeof opts.exitCode === 'number' ? opts.exitCode : 1;
+  const aborted = Boolean(opts.aborted);
+
+  return createNormalizedMessage({
+    kind: 'complete',
+    provider: opts.provider,
+    sessionId: opts.sessionId || null,
+    actualSessionId: opts.actualSessionId || opts.sessionId || null,
+    exitCode,
+    success: exitCode === 0 && !aborted,
+    aborted,
+  });
+}
+
+// ---------------------------
+//----------------- CONVERSATION HISTORY PAGINATION UTILITIES ------------
+/**
+ * Slices one page from the END of a chronologically ordered message list.
+ *
+ * This is the single pagination contract for conversation history across all
+ * providers: `offset = 0` returns the most recent `limit` items, increasing
+ * offsets walk backwards in time (for "scroll up to load older" UIs), and a
+ * `null` limit returns everything. Items must already be sorted oldest-first;
+ * the returned page preserves that order.
+ *
+ * Every provider history reader must use this helper instead of slicing
+ * manually so `offset`/`limit` query params behave identically regardless of
+ * which provider produced the session.
+ */
+export function sliceTailPage<T>(
+  items: T[],
+  limit: number | null,
+  offset: number,
+): { page: T[]; hasMore: boolean } {
+  const total = items.length;
+  const normalizedOffset = Math.max(0, offset);
+
+  if (limit === null) {
+    // A null limit returns the full list; offset still trims newest entries
+    // so "everything before the page I already have" stays expressible.
+    const end = Math.max(0, total - normalizedOffset);
+    return {
+      page: items.slice(0, end),
+      hasMore: false,
+    };
+  }
+
+  const end = Math.max(0, total - normalizedOffset);
+  const start = Math.max(0, end - Math.max(0, limit));
+  return {
+    page: items.slice(start, end),
+    hasMore: start > 0,
+  };
+}
+
 // ---------------------------
 //----------------- MCP CONFIG PARSING UTILITIES ------------
 /**
--- a/src/components/app/AppContent.tsx
+++ b/src/components/app/AppContent.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useRef } from 'react';
+import { useCallback, useEffect } from 'react';
 import { useNavigate, useParams } from 'react-router-dom';
 import { useTranslation } from 'react-i18next';

@@ -10,6 +10,33 @@ import { PaletteOpsProvider, usePaletteOpsRegister } from '../../contexts/Palett
 import { useDeviceSettings } from '../../hooks/useDeviceSettings';
 import { useSessionProtection } from '../../hooks/useSessionProtection';
 import { useProjectsState } from '../../hooks/useProjectsState';
+import { api } from '../../utils/api';
+
+type RunningSessionApiItem = {
+  sessionId?: unknown;
+  startedAt?: unknown;
+  statusText?: unknown;
+  canInterrupt?: unknown;
+};
+
+type RunningSessionsApiPayload = {
+  data?: {
+    sessions?: RunningSessionApiItem[];
+  };
+};
+
+const parseStartedAt = (value: unknown): number | undefined => {
+  if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+    return value;
+  }
+
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+};

 export default function AppContent() {
  return (
@@ -24,16 +51,13 @@ function AppContentInner() {
  const { sessionId } = useParams<{ sessionId?: string }>();
  const { t } = useTranslation('common');
  const { isMobile } = useDeviceSettings({ trackPWA: false });
-  const { ws, sendMessage, latestMessage, isConnected } = useWebSocket();
-  const wasConnectedRef = useRef(false);
+  const { ws, sendMessage, subscribe } = useWebSocket();

  const {
-    activeSessions,
    processingSessions,
-    markSessionAsActive,
-    markSessionAsInactive,
-    markSessionAsProcessing,
-    markSessionAsNotProcessing,
+    markSessionProcessing,
+    markSessionIdle,
+    syncProcessingSessions,
  } = useSessionProtection();

  const {
@@ -47,19 +71,62 @@ function AppContentInner() {
    setActiveTab,
    setSidebarOpen,
    setIsInputFocused,
-    setShowSettings,
    openSettings,
    refreshProjectsSilently,
+    registerOptimisticSession,
    sidebarSharedProps,
    handleNewSession,
  } = useProjectsState({
    sessionId,
    navigate,
-    latestMessage,
+    subscribe,
    isMobile,
-    activeSessions,
+    activeSessions: processingSessions,
  });

+  const refreshRunningSessions = useCallback(async () => {
+    try {
+      const response = await api.runningSessions();
+      if (!response.ok) {
+        return;
+      }
+
+      const payload = (await response.json()) as RunningSessionsApiPayload;
+      const sessions = Array.isArray(payload.data?.sessions) ? payload.data.sessions : [];
+
+      syncProcessingSessions(
+        sessions
+          .map((session) => {
+            if (typeof session.sessionId !== 'string' || !session.sessionId) {
+              return null;
+            }
+
+            return {
+              sessionId: session.sessionId,
+              startedAt: parseStartedAt(session.startedAt),
+              statusText: typeof session.statusText === 'string' ? session.statusText : undefined,
+              canInterrupt: typeof session.canInterrupt === 'boolean' ? session.canInterrupt : undefined,
+            };
+          })
+          .filter((session): session is NonNullable<typeof session> => Boolean(session)),
+      );
+    } catch (error) {
+      console.error('[AppContent] Failed to sync running sessions:', error);
+    }
+  }, [syncProcessingSessions]);
+
+  useEffect(() => {
+    void refreshRunningSessions();
+  }, [refreshRunningSessions]);
+
+  useEffect(() => {
+    const interval = window.setInterval(() => {
+      void refreshRunningSessions();
+    }, 5000);
+
+    return () => window.clearInterval(interval);
+  }, [refreshRunningSessions]);
+
  usePaletteOpsRegister({
    openSettings,
    refreshProjects: refreshProjectsSilently,
@@ -99,23 +166,9 @@ function AppContentInner() {
    };
  }, [navigate, refreshProjectsSilently, setActiveTab, setSidebarOpen]);

-  // Permission recovery: query pending permissions on WebSocket reconnect or session change
-  useEffect(() => {
-    const isReconnect = isConnected && !wasConnectedRef.current;
-
-    if (isReconnect) {
-      wasConnectedRef.current = true;
-    } else if (!isConnected) {
-      wasConnectedRef.current = false;
-    }
-
-    if (isConnected && selectedSession?.id) {
-      sendMessage({
-        type: 'get-pending-permissions',
-        sessionId: selectedSession.id
-      });
-    }
-  }, [isConnected, selectedSession?.id, sendMessage]);
+  // Pending tool permissions are recovered through the `chat.subscribe` flow:
+  // the `chat_subscribed` ack carries them on session open and on reconnect,
+  // so no separate permission-recovery message is needed here.

  // Adjust the app container to stay above the virtual keyboard on iOS Safari.
  // On Chrome for Android the layout viewport already shrinks when the keyboard opens,
@@ -180,20 +233,20 @@ function AppContentInner() {
          setActiveTab={setActiveTab}
          ws={ws}
          sendMessage={sendMessage}
-          latestMessage={latestMessage}
          isMobile={isMobile}
          onMenuClick={() => setSidebarOpen(true)}
          isLoading={isLoadingProjects}
          onInputFocusChange={setIsInputFocused}
-          onSessionActive={markSessionAsActive}
-          onSessionInactive={markSessionAsInactive}
-          onSessionProcessing={markSessionAsProcessing}
-          onSessionNotProcessing={markSessionAsNotProcessing}
+          onSessionProcessing={markSessionProcessing}
+          onSessionIdle={markSessionIdle}
          processingSessions={processingSessions}
          onNavigateToSession={(targetSessionId: string, options) =>
            navigate(`/session/${targetSessionId}`, { replace: Boolean(options?.replace) })
          }
-          onShowSettings={() => setShowSettings(true)}
+          onSessionEstablished={(targetSessionId, context) =>
+            registerOptimisticSession({ sessionId: targetSessionId, ...context })
+          }
+          onShowSettings={openSettings}
          externalMessageUpdate={externalMessageUpdate}
          newSessionTrigger={newSessionTrigger}
        />
--- a/src/components/browser-use/index.ts
+++ b/src/components/browser-use/index.ts
@@ -0,0 +1 @@
+export { default as BrowserUsePanel } from './view/BrowserUsePanel';
--- a/src/components/browser-use/view/BrowserUsePanel.tsx
+++ b/src/components/browser-use/view/BrowserUsePanel.tsx
@@ -0,0 +1,536 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import {
+  Bot,
+  Clock3,
+  Download,
+  Expand,
+  ExternalLink,
+  Loader2,
+  MonitorPlay,
+  RefreshCw,
+  Settings,
+  Square,
+  Trash2,
+  X,
+} from 'lucide-react';
+
+import { cn } from '../../../lib/utils';
+import { Badge, Button } from '../../../shared/view/ui';
+import { authenticatedFetch } from '../../../utils/api';
+import type { SettingsMainTab } from '../../settings/types/types';
+
+type BrowserUseStatus = {
+  enabled: boolean;
+  available: boolean;
+  playwrightInstalled: boolean;
+  chromiumInstalled: boolean;
+  installInProgress: boolean;
+  sessionCount: number;
+  message: string;
+};
+
+type BrowserUseSession = {
+  id: string;
+  status: 'ready' | 'stopped' | 'unavailable';
+  url: string | null;
+  title: string | null;
+  screenshotDataUrl: string | null;
+  createdAt: string;
+  updatedAt: string;
+  lastAction: string | null;
+  message: string | null;
+  createdBy: 'agent';
+  profileName: string | null;
+  viewport: {
+    width: number;
+    height: number;
+  } | null;
+  cursor: {
+    x: number;
+    y: number;
+    actor: 'agent';
+  } | null;
+};
+
+type BrowserUsePanelProps = {
+  isVisible: boolean;
+  onShowSettings?: (tab?: SettingsMainTab) => void;
+};
+
+async function readJson<T>(response: Response): Promise<T> {
+  const data = await response.json();
+  if (!response.ok || data.success === false) {
+    throw new Error(data.error || data.details || `Request failed (${response.status})`);
+  }
+  return data as T;
+}
+
+function formatRelativeTime(value: string | null): string {
+  if (!value) return 'Never';
+
+  const timestamp = Date.parse(value);
+  if (!Number.isFinite(timestamp)) return 'Unknown';
+
+  const elapsedSeconds = Math.max(0, Math.round((Date.now() - timestamp) / 1000));
+  if (elapsedSeconds < 10) return 'Just now';
+  if (elapsedSeconds < 60) return `${elapsedSeconds}s ago`;
+  const elapsedMinutes = Math.round(elapsedSeconds / 60);
+  if (elapsedMinutes < 60) return `${elapsedMinutes}m ago`;
+  const elapsedHours = Math.round(elapsedMinutes / 60);
+  if (elapsedHours < 24) return `${elapsedHours}h ago`;
+  return `${Math.round(elapsedHours / 24)}d ago`;
+}
+
+function getDomain(url: string | null): string {
+  if (!url) return 'No page loaded';
+
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return url;
+  }
+}
+
+function formatAction(action: string | null): string {
+  if (!action) return 'Waiting';
+  return action.replace(/_/g, ' ').replace(/:/g, ': ');
+}
+
+function getStatusTone(status: BrowserUseSession['status']): string {
+  if (status === 'ready') {
+    return 'border-primary/30 bg-primary/5 text-foreground';
+  }
+  if (status === 'stopped') {
+    return 'border-border bg-muted text-muted-foreground';
+  }
+  return 'border-border bg-background text-muted-foreground';
+}
+
+function getRuntimeTone(status: BrowserUseStatus | null, installing: boolean): string {
+  if (!status?.enabled) return 'border-border bg-muted text-muted-foreground';
+  if (status.available) return 'border-primary/30 bg-primary/5 text-foreground';
+  if (status.installInProgress || installing) return 'border-primary/30 bg-primary/5 text-foreground';
+  return 'border-border bg-background text-muted-foreground';
+}
+
+function getStatusDot(status: BrowserUseSession['status']): string {
+  if (status === 'ready') return 'bg-primary';
+  if (status === 'stopped') return 'bg-muted-foreground/50';
+  return 'bg-border';
+}
+
+const PROMPTS = [
+  'Use Browser to inspect the checkout flow and report any broken UI states.',
+  'Open <url> with Browser, interact with the page, and summarize what changed after each step.',
+];
+
+export default function BrowserUsePanel({ isVisible, onShowSettings }: BrowserUsePanelProps) {
+  const [status, setStatus] = useState<BrowserUseStatus | null>(null);
+  const [sessions, setSessions] = useState<BrowserUseSession[]>([]);
+  const [selectedSessionId, setSelectedSessionId] = useState<string | null>(null);
+  const [isRefreshing, setIsRefreshing] = useState(false);
+  const [isBusy, setIsBusy] = useState(false);
+  const [isInstalling, setIsInstalling] = useState(false);
+  const [isFullscreen, setIsFullscreen] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const selectedSession = useMemo(
+    () => sessions.find((session) => session.id === selectedSessionId) || sessions[0] || null,
+    [selectedSessionId, sessions],
+  );
+
+  const activeSessions = sessions.filter((session) => session.status === 'ready');
+  const needsBrowserBinaries = Boolean(status?.enabled && (!status.playwrightInstalled || !status.chromiumInstalled));
+  const runtimeLabel = !status?.enabled
+    ? 'Disabled'
+    : status.available
+      ? 'Ready'
+      : status.installInProgress || isInstalling
+        ? 'Installing'
+        : 'Setup required';
+
+  const cursorStyle = selectedSession?.cursor && selectedSession.viewport
+    ? {
+      left: `${(selectedSession.cursor.x / selectedSession.viewport.width) * 100}%`,
+      top: `${(selectedSession.cursor.y / selectedSession.viewport.height) * 100}%`,
+    }
+    : null;
+
+  const refresh = useCallback(async () => {
+    setIsRefreshing(true);
+    try {
+      const [statusResponse, sessionsResponse] = await Promise.all([
+        authenticatedFetch('/api/browser-use/status'),
+        authenticatedFetch('/api/browser-use/sessions'),
+      ]);
+      const statusData = await readJson<{ data: BrowserUseStatus }>(statusResponse);
+      const sessionsData = await readJson<{ data: { sessions: BrowserUseSession[] } }>(sessionsResponse);
+      const nextSessions = sessionsData.data.sessions;
+      setStatus(statusData.data);
+      setSessions(nextSessions);
+      setSelectedSessionId((current) => (
+        current && nextSessions.some((session) => session.id === current)
+          ? current
+          : nextSessions[0]?.id || null
+      ));
+      setError(null);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to load Browser');
+    } finally {
+      setIsRefreshing(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (!isVisible) return;
+    void refresh();
+  }, [isVisible, refresh]);
+
+  const runAction = useCallback(async (action: () => Promise<void>) => {
+    setIsBusy(true);
+    setError(null);
+    try {
+      await action();
+      await refresh();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Browser action failed');
+    } finally {
+      setIsBusy(false);
+    }
+  }, [refresh]);
+
+  const stopSession = () => runAction(async () => {
+    if (!selectedSession) return;
+    const response = await authenticatedFetch(`/api/browser-use/sessions/${selectedSession.id}/stop`, { method: 'POST' });
+    await readJson(response);
+  });
+
+  const deleteSession = () => runAction(async () => {
+    if (!selectedSession) return;
+    const response = await authenticatedFetch(`/api/browser-use/sessions/${selectedSession.id}`, { method: 'DELETE' });
+    await readJson(response);
+    setIsFullscreen(false);
+  });
+
+  const installBrowserBinaries = () => runAction(async () => {
+    setIsInstalling(true);
+    try {
+      const response = await authenticatedFetch('/api/browser-use/runtime/install', { method: 'POST' });
+      await readJson(response);
+    } finally {
+      setIsInstalling(false);
+    }
+  });
+
+  const renderSessionItem = (session: BrowserUseSession) => {
+    const isSelected = selectedSession?.id === session.id;
+    return (
+      <button
+        key={session.id}
+        type="button"
+        onClick={() => setSelectedSessionId(session.id)}
+        className={cn(
+          'group w-full rounded-md border px-3 py-2.5 text-left transition-colors',
+          isSelected
+            ? 'border-primary/50 bg-primary/10 text-foreground'
+            : 'border-border/60 bg-card/30 text-muted-foreground hover:bg-muted/50',
+        )}
+      >
+        <div className="flex items-start justify-between gap-2">
+          <div className="min-w-0">
+            <div className="flex min-w-0 items-center gap-2">
+              <span className={cn('h-1.5 w-1.5 shrink-0 rounded-full', getStatusDot(session.status))} />
+              <div className="truncate text-sm font-medium">{session.title || getDomain(session.url)}</div>
+            </div>
+            <div className="mt-1 truncate pl-3.5 text-xs text-muted-foreground">{getDomain(session.url)}</div>
+          </div>
+          <Badge variant="outline" className="shrink-0 border-border bg-background text-[10px] text-muted-foreground">
+            {session.status}
+          </Badge>
+        </div>
+        <div className="mt-2 flex items-center gap-1.5 text-[11px] text-muted-foreground">
+          <Clock3 className="h-3 w-3" />
+          <span>{formatRelativeTime(session.updatedAt)}</span>
+          <span className="truncate">- {formatAction(session.lastAction)}</span>
+        </div>
+      </button>
+    );
+  };
+
+  const renderEmptyState = () => (
+    <div className="flex min-h-0 flex-1 items-center justify-center p-6">
+      <div className="w-full max-w-2xl rounded-md border border-border bg-card/40 p-5 shadow-sm">
+        <div className="flex items-start gap-3">
+          <div className="flex h-10 w-10 shrink-0 items-center justify-center rounded-md border border-border bg-background">
+            <MonitorPlay className="h-5 w-5 text-primary" />
+          </div>
+          <div className="min-w-0">
+            <div className="text-sm font-semibold text-foreground">
+              {status?.enabled ? 'No browser sessions yet' : 'Browser is disabled'}
+            </div>
+            <p className="mt-1 max-w-xl text-sm leading-6 text-muted-foreground">
+              {status?.enabled
+                ? 'Agent browser sessions appear here while an AI task is using Browser.'
+                : 'Enable Browser in settings to let agents open monitored browser sessions.'}
+            </p>
+          </div>
+        </div>
+
+        {needsBrowserBinaries && (
+          <div className="mt-4 rounded-md border border-border bg-muted/30 p-3">
+            <div className="text-sm font-medium text-foreground">Runtime setup required</div>
+            <p className="mt-1 text-sm text-muted-foreground">{status?.message}</p>
+            <Button
+              type="button"
+              size="sm"
+              className="mt-3"
+              onClick={installBrowserBinaries}
+              disabled={isBusy || isInstalling || status?.installInProgress}
+            >
+              {isInstalling || status?.installInProgress ? (
+                <Loader2 className="h-4 w-4 animate-spin" />
+              ) : (
+                <Download className="h-4 w-4" />
+              )}
+              {isInstalling || status?.installInProgress ? 'Installing...' : 'Install Runtime'}
+            </Button>
+          </div>
+        )}
+
+        <div className="mt-5 grid gap-2 sm:grid-cols-2">
+          {PROMPTS.map((prompt) => (
+            <div key={prompt} className="rounded-md border border-border/70 bg-background/70 p-3">
+              <div className="mb-2 flex items-center gap-2 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                <Bot className="h-3.5 w-3.5" />
+                Prompt
+              </div>
+              <p className="text-sm leading-6 text-foreground">{prompt}</p>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+
+  const renderBrowserSurface = (fullscreen = false) => (
+    <div className={cn('flex flex-1 items-center justify-center bg-neutral-950', fullscreen ? 'min-h-[80vh]' : 'min-h-[420px]')}>
+      {selectedSession?.screenshotDataUrl ? (
+        <div className="relative inline-block max-h-full">
+          <img
+            src={selectedSession.screenshotDataUrl}
+            alt="Browser session screenshot"
+            className={fullscreen ? 'block max-h-[80vh] w-auto max-w-full object-contain' : 'block max-h-[72vh] w-auto max-w-full object-contain'}
+          />
+          {cursorStyle && (
+            <div
+              className="pointer-events-none absolute h-5 w-5 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-white/90 bg-primary/80 shadow-[0_0_0_6px_hsl(var(--primary)/0.18)]"
+              style={cursorStyle}
+            >
+              <div className="absolute left-1/2 top-1/2 h-2 w-2 -translate-x-1/2 -translate-y-1/2 rounded-full bg-white" />
+            </div>
+          )}
+        </div>
+      ) : (
+        <div className="px-6 text-center">
+          <MonitorPlay className="mx-auto h-9 w-9 text-neutral-500" />
+          <div className="mt-3 text-sm font-medium text-neutral-100">{selectedSession?.message || 'Waiting for screenshot'}</div>
+          <p className="mt-1 text-xs text-neutral-400">The next agent browser snapshot will render here.</p>
+        </div>
+      )}
+    </div>
+  );
+
+  return (
+    <div className="flex h-full min-h-0 flex-col bg-background">
+      <div className="flex items-center justify-between gap-3 border-b border-border/60 px-4 py-3">
+        <div className="min-w-0">
+          <div className="flex items-center gap-2">
+            <MonitorPlay className="h-4 w-4 text-primary" />
+            <h3 className="text-sm font-semibold text-foreground">Browser</h3>
+            <Badge variant="outline" className={cn('text-[10px]', getRuntimeTone(status, isInstalling))}>
+              {runtimeLabel}
+            </Badge>
+          </div>
+          <p className="mt-0.5 text-xs text-muted-foreground">Monitor browser sessions opened by AI agents.</p>
+        </div>
+        <div className="flex items-center gap-1.5">
+          {onShowSettings && (
+            <Button
+              variant="ghost"
+              size="sm"
+              className="h-7 w-7 p-0"
+              onClick={() => onShowSettings('browser')}
+              title="Open Browser settings"
+              aria-label="Open Browser settings"
+            >
+              <Settings className="h-3.5 w-3.5" />
+            </Button>
+          )}
+          <Button
+            variant="ghost"
+            size="sm"
+            className="h-7 w-7 p-0"
+            onClick={() => void refresh()}
+            disabled={isRefreshing || isBusy}
+            title="Refresh browser sessions"
+            aria-label="Refresh browser sessions"
+          >
+            <RefreshCw className={cn('h-3.5 w-3.5', isRefreshing && 'animate-spin')} />
+          </Button>
+        </div>
+      </div>
+
+      {error && (
+        <div className="border-b border-destructive/20 bg-destructive/10 px-4 py-2 text-sm text-destructive">
+          {error}
+        </div>
+      )}
+
+      {sessions.length > 0 && (
+        <div className="border-b border-border/60 bg-muted/20 px-3 py-2 lg:hidden">
+          <div className="flex gap-2 overflow-x-auto">
+            {sessions.map((session) => (
+              <button
+                key={session.id}
+                type="button"
+                onClick={() => setSelectedSessionId(session.id)}
+                className={cn(
+                  'flex min-w-[180px] items-center gap-2 rounded-md border px-2.5 py-2 text-left',
+                  selectedSession?.id === session.id
+                    ? 'border-primary/40 bg-primary/5'
+                    : 'border-border bg-background',
+                )}
+              >
+                <span className={cn('h-1.5 w-1.5 shrink-0 rounded-full', getStatusDot(session.status))} />
+                <span className="min-w-0 flex-1 truncate text-xs font-medium text-foreground">
+                  {session.title || getDomain(session.url)}
+                </span>
+              </button>
+            ))}
+          </div>
+        </div>
+      )}
+
+      <div className="grid min-h-0 flex-1 grid-cols-1 lg:grid-cols-[minmax(0,1fr)_320px]">
+        <main className="flex min-h-0 flex-col overflow-hidden">
+          <div className="flex items-center justify-between gap-3 border-b border-border/60 bg-muted/20 px-4 py-2.5 text-xs text-muted-foreground">
+            <div className="min-w-0 truncate">
+              {activeSessions.length} active
+              <span className="px-1.5">/</span>
+              {sessions.length} total
+            </div>
+            <div className="min-w-0 truncate">
+              Updated {formatRelativeTime(selectedSession?.updatedAt || null)}
+            </div>
+          </div>
+
+          {sessions.length === 0 ? (
+            renderEmptyState()
+          ) : (
+            <div className="min-h-0 flex-1 overflow-auto bg-muted/20 p-4">
+              <div className="mx-auto flex min-h-[500px] max-w-7xl flex-col overflow-hidden rounded-md border border-border bg-background shadow-sm">
+                <div className="flex flex-wrap items-center gap-2 border-b border-border/60 px-3 py-2">
+                  <Badge variant="outline" className={selectedSession ? cn('text-[10px]', getStatusTone(selectedSession.status)) : 'text-[10px]'}>
+                    {selectedSession?.status || 'empty'}
+                  </Badge>
+                  <div className="min-w-0 flex-1">
+                    <div className="truncate text-sm font-medium text-foreground">
+                      {selectedSession?.title || getDomain(selectedSession?.url || null)}
+                    </div>
+                    <div className="mt-0.5 flex min-w-0 items-center gap-1.5 text-xs text-muted-foreground">
+                      <ExternalLink className="h-3.5 w-3.5 shrink-0" />
+                      <span className="truncate">{selectedSession?.url || 'No page loaded'}</span>
+                    </div>
+                  </div>
+                  <div className="hidden text-xs text-muted-foreground md:block">
+                    {formatAction(selectedSession?.lastAction || null)}
+                  </div>
+                  <Button variant="ghost" size="sm" className="h-8 w-8 p-0" onClick={() => setIsFullscreen(true)} disabled={!selectedSession?.screenshotDataUrl} title="Full screen" aria-label="Full screen">
+                    <Expand className="h-4 w-4" />
+                  </Button>
+                  <Button variant="ghost" size="sm" className="h-8 w-8 p-0 lg:hidden" onClick={stopSession} disabled={isBusy || !selectedSession || selectedSession.status !== 'ready'} title="Stop session" aria-label="Stop session">
+                    <Square className="h-4 w-4" />
+                  </Button>
+                  <Button variant="ghost" size="sm" className="h-8 w-8 p-0 lg:hidden" onClick={deleteSession} disabled={isBusy || !selectedSession} title="Delete session" aria-label="Delete session">
+                    <Trash2 className="h-4 w-4" />
+                  </Button>
+                </div>
+                {renderBrowserSurface()}
+              </div>
+            </div>
+          )}
+        </main>
+
+        <aside className="hidden min-h-0 flex-col border-l border-border/60 bg-background lg:flex">
+          <div className="border-b border-border/60 px-4 py-3">
+            <div className="flex items-center justify-between gap-2">
+              <div>
+                <div className="text-sm font-semibold text-foreground">Sessions</div>
+                <div className="mt-0.5 text-xs text-muted-foreground">{sessions.length} total</div>
+              </div>
+              <Badge variant="outline" className="text-[10px]">{activeSessions.length} active</Badge>
+            </div>
+          </div>
+
+          <div className="min-h-0 flex-1 overflow-y-auto p-3">
+            {sessions.length > 0 ? (
+              <div className="space-y-2">{sessions.map(renderSessionItem)}</div>
+            ) : (
+              <div className="rounded-md border border-dashed border-border/70 px-3 py-8 text-center text-xs text-muted-foreground">
+                No agent browser sessions.
+              </div>
+            )}
+          </div>
+
+          <div className="border-t border-border/60 p-3">
+            <div className="rounded-md border border-border/70 bg-muted/30 p-3">
+              <div className="flex items-center gap-2 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                <Bot className="h-3.5 w-3.5" />
+                Selected
+              </div>
+              <div className="mt-3 space-y-2 text-xs text-muted-foreground">
+                <div className="flex items-center justify-between gap-3">
+                  <span>Status</span>
+                  <span className="font-medium text-foreground">{selectedSession?.status || 'None'}</span>
+                </div>
+                <div className="flex items-center justify-between gap-3">
+                  <span>Last action</span>
+                  <span className="truncate font-medium text-foreground">{formatAction(selectedSession?.lastAction || null)}</span>
+                </div>
+                <div className="flex items-center justify-between gap-3">
+                  <span>Profile</span>
+                  <span className="truncate font-medium text-foreground">{selectedSession?.profileName || 'Temporary'}</span>
+                </div>
+              </div>
+              <div className="mt-3 grid grid-cols-2 gap-2">
+                <Button variant="outline" size="sm" onClick={stopSession} disabled={isBusy || !selectedSession || selectedSession.status !== 'ready'}>
+                  <Square className="h-4 w-4" />
+                  Stop
+                </Button>
+                <Button variant="outline" size="sm" onClick={deleteSession} disabled={isBusy || !selectedSession}>
+                  <Trash2 className="h-4 w-4" />
+                  Delete
+                </Button>
+              </div>
+            </div>
+          </div>
+        </aside>
+      </div>
+
+      {isFullscreen && selectedSession && (
+        <div className="fixed inset-0 z-50 bg-black/90 p-6">
+          <div className="flex h-full flex-col rounded-md border border-white/10 bg-black">
+            <div className="flex items-center justify-between border-b border-white/10 px-4 py-3 text-sm text-white/80">
+              <div className="min-w-0 truncate">{selectedSession.title || selectedSession.url || 'Browser session'}</div>
+              <Button variant="outline" size="sm" onClick={() => setIsFullscreen(false)}>
+                <X className="h-4 w-4" />
+                Close
+              </Button>
+            </div>
+            {renderBrowserSurface(true)}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
--- a/src/components/chat/hooks/useChatComposerState.ts
+++ b/src/components/chat/hooks/useChatComposerState.ts
@@ -12,12 +12,14 @@ import type {
 import { useDropzone } from 'react-dropzone';

 import { authenticatedFetch } from '../../../utils/api';
+import type { MarkSessionProcessing } from '../../../hooks/useSessionProtection';
 import { grantClaudeToolPermission } from '../utils/chatPermissions';
 import { safeLocalStorage } from '../utils/chatStorage';
 import type {
  ChatMessage,
  PendingPermissionRequest,
  PermissionMode,
+  SessionEstablishedContext,
 } from '../types/types';
 import type { Project, ProjectSession, LLMProvider, ProviderModelsCacheInfo } from '../../../types/app';
 import { escapeRegExp } from '../utils/chatFormatting';
@@ -25,10 +27,6 @@ import { escapeRegExp } from '../utils/chatFormatting';
 import { useFileMentions } from './useFileMentions';
 import { type SlashCommand, useSlashCommands } from './useSlashCommands';

-type PendingViewSession = {
-  startedAt: number;
-};
-
 interface UseChatComposerStateArgs {
  selectedProject: Project | null;
  selectedSession: ProjectSession | null;
@@ -46,17 +44,20 @@ interface UseChatComposerStateArgs {
  tokenBudget: Record<string, unknown> | null;
  sendMessage: (message: unknown) => void;
  sendByCtrlEnter?: boolean;
-  onSessionActive?: (sessionId?: string | null) => void;
-  onSessionProcessing?: (sessionId?: string | null) => void;
+  onSessionProcessing?: MarkSessionProcessing;
+  /**
+   * Invoked with the freshly allocated session id when the user sends the
+   * first message of a brand-new conversation. The backend allocates the id
+   * via POST /api/providers/sessions BEFORE the websocket send, so the id is
+   * stable for the conversation's whole lifetime — the consumer navigates to
+   * /session/:id and records it as the current session.
+   */
+  onSessionEstablished?: (sessionId: string, context: SessionEstablishedContext) => void;
  onInputFocusChange?: (focused: boolean) => void;
  onFileOpen?: (filePath: string, diffInfo?: unknown) => void;
  onShowSettings?: () => void;
-  pendingViewSessionRef: { current: PendingViewSession | null };
  scrollToBottom: () => void;
  addMessage: (msg: ChatMessage) => void;
-  setIsLoading: (loading: boolean) => void;
-  setCanAbortSession: (canAbort: boolean) => void;
-  setClaudeStatus: (status: { text: string; tokens: number; can_interrupt: boolean } | null) => void;
  setIsUserScrolledUp: (isScrolledUp: boolean) => void;
  setPendingPermissionRequests: Dispatch<SetStateAction<PendingPermissionRequest[]>>;
 }
@@ -177,17 +178,13 @@ export function useChatComposerState({
  tokenBudget,
  sendMessage,
  sendByCtrlEnter,
-  onSessionActive,
  onSessionProcessing,
+  onSessionEstablished,
  onInputFocusChange,
  onFileOpen,
  onShowSettings,
-  pendingViewSessionRef,
  scrollToBottom,
  addMessage,
-  setIsLoading,
-  setCanAbortSession,
-  setClaudeStatus,
  setIsUserScrolledUp,
  setPendingPermissionRequests,
 }: UseChatComposerStateArgs) {
@@ -609,8 +606,54 @@ export function useChatComposerState({
        }
      }

-      const effectiveSessionId =
-        currentSessionId || selectedSession?.id || sessionStorage.getItem('cursorSessionId');
+      const resolvedProjectPath = selectedProject.fullPath || selectedProject.path || '';
+      const sessionSummary = getNotificationSessionSummary(selectedSession, currentInput);
+
+      // The conversation always has a stable backend-allocated session id
+      // BEFORE the first websocket send: brand-new chats allocate one here
+      // via the session gateway. There is no client-visible session-id
+      // handoff later — this id stays valid for the conversation's lifetime.
+      let targetSessionId = selectedSession?.id || currentSessionId || null;
+      if (!targetSessionId) {
+        try {
+          const response = await authenticatedFetch('/api/providers/sessions', {
+            method: 'POST',
+            body: JSON.stringify({
+              provider,
+              projectPath: resolvedProjectPath,
+            }),
+          });
+          if (!response.ok) {
+            throw new Error(`Failed to create session (${response.status})`);
+          }
+          const body = await response.json();
+          targetSessionId = body?.data?.sessionId || null;
+        } catch (error) {
+          const message = error instanceof Error ? error.message : 'Unknown error';
+          console.error('Session creation failed:', error);
+          addMessage({
+            type: 'error',
+            content: `Failed to start a new session: ${message}`,
+            timestamp: new Date(),
+          });
+          return;
+        }
+
+        if (!targetSessionId) {
+          addMessage({
+            type: 'error',
+            content: 'Failed to start a new session: no session id returned.',
+            timestamp: new Date(),
+          });
+          return;
+        }
+
+        onSessionEstablished?.(targetSessionId, {
+          provider,
+          project: selectedProject,
+          summary: sessionSummary,
+        });
+      }

      const userMessage: ChatMessage = {
        type: 'user',
@@ -620,27 +663,17 @@ export function useChatComposerState({
      };

      addMessage(userMessage);
-      setIsLoading(true); // Processing banner starts
-      setCanAbortSession(true);
-      setClaudeStatus({
-        text: 'Processing',
-        tokens: 0,
-        can_interrupt: true,
+      // Mark this request as processing in the per-session activity map (the
+      // single source of truth the indicator derives from). The id is always
+      // concrete at this point — no pending placeholder exists anymore.
+      onSessionProcessing?.(targetSessionId, {
+        statusText: null,
+        canInterrupt: true,
      });

      setIsUserScrolledUp(false);
      setTimeout(() => scrollToBottom(), 100);

-      if (!effectiveSessionId && !selectedSession?.id) {
-        // 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() };
-      }
-      if (effectiveSessionId) {
-        onSessionActive?.(effectiveSessionId);
-        onSessionProcessing?.(effectiveSessionId);
-      }
-
      const getToolsSettings = () => {
        try {
          const settingsKey =
@@ -669,87 +702,35 @@ export function useChatComposerState({
      };

      const toolsSettings = getToolsSettings();
-      const resolvedProjectPath = selectedProject.fullPath || selectedProject.path || '';
-      const sessionSummary = getNotificationSessionSummary(selectedSession, currentInput);
+      const model =
+        provider === 'cursor'
+          ? cursorModel
+          : provider === 'codex'
+            ? codexModel
+            : provider === 'gemini'
+              ? geminiModel
+              : provider === 'opencode'
+                ? opencodeModel
+                : claudeModel;

-      if (provider === 'cursor') {
-        sendMessage({
-          type: 'cursor-command',
-          command: messageContent,
-          sessionId: effectiveSessionId,
-          options: {
-            cwd: resolvedProjectPath,
-            projectPath: resolvedProjectPath,
-            sessionId: effectiveSessionId,
-            resume: Boolean(effectiveSessionId),
-            model: cursorModel,
-            skipPermissions: toolsSettings?.skipPermissions || false,
-            sessionSummary,
-            toolsSettings,
-          },
-        });
-      } else if (provider === 'codex') {
-        sendMessage({
-          type: 'codex-command',
-          command: messageContent,
-          sessionId: effectiveSessionId,
-          options: {
-            cwd: resolvedProjectPath,
-            projectPath: resolvedProjectPath,
-            sessionId: effectiveSessionId,
-            resume: Boolean(effectiveSessionId),
-            model: codexModel,
-            sessionSummary,
-            permissionMode: permissionMode === 'plan' ? 'default' : permissionMode,
-          },
-        });
-      } else if (provider === 'gemini') {
-        sendMessage({
-          type: 'gemini-command',
-          command: messageContent,
-          sessionId: effectiveSessionId,
-          options: {
-            cwd: resolvedProjectPath,
-            projectPath: resolvedProjectPath,
-            sessionId: effectiveSessionId,
-            resume: Boolean(effectiveSessionId),
-            model: geminiModel,
-            sessionSummary,
-            permissionMode,
-            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',
-          command: messageContent,
-          options: {
-            projectPath: resolvedProjectPath,
-            cwd: resolvedProjectPath,
-            sessionId: effectiveSessionId,
-            resume: Boolean(effectiveSessionId),
-            toolsSettings,
-            permissionMode,
-            model: claudeModel,
-            sessionSummary,
-            images: uploadedImages,
-          },
-        });
-      }
+      // One message shape for every provider. The backend resolves the
+      // provider, project path, and provider-native resume id from the
+      // session row; `options` only carries composer-level preferences.
+      sendMessage({
+        type: 'chat.send',
+        sessionId: targetSessionId,
+        content: messageContent,
+        options: {
+          model,
+          // Codex has no plan mode; downgrade rather than sending an
+          // unsupported value to its runtime.
+          permissionMode: provider === 'codex' && permissionMode === 'plan' ? 'default' : permissionMode,
+          toolsSettings,
+          skipPermissions: toolsSettings?.skipPermissions || false,
+          sessionSummary,
+          images: uploadedImages,
+        },
+      });

      setInput('');
      inputValueRef.current = '';
@@ -776,19 +757,15 @@ export function useChatComposerState({
      geminiModel,
      opencodeModel,
      isLoading,
-      onSessionActive,
      onSessionProcessing,
-      pendingViewSessionRef,
+      onSessionEstablished,
      permissionMode,
      provider,
      resetCommandMenuState,
      scrollToBottom,
      selectedProject,
      sendMessage,
-      setCanAbortSession,
      addMessage,
-      setClaudeStatus,
-      setIsLoading,
      setIsUserScrolledUp,
      slashCommands,
    ],
@@ -944,29 +921,19 @@ export function useChatComposerState({
      return;
    }

-    const cursorSessionId =
-      typeof window !== 'undefined' ? sessionStorage.getItem('cursorSessionId') : null;
-
-    const candidateSessionIds = [
-      currentSessionId,
-      provider === 'cursor' ? cursorSessionId : null,
-      selectedSession?.id || null,
-    ];
-
-    const targetSessionId =
-      candidateSessionIds.find((sessionId) => Boolean(sessionId)) || null;
-
+    const targetSessionId = selectedSession?.id || currentSessionId || null;
    if (!targetSessionId) {
-      console.warn('Abort requested but no concrete session ID is available yet.');
+      console.warn('Abort requested but no session ID is available.');
      return;
    }

+    // The backend resolves the provider from the session row, so no provider
+    // field is needed here.
    sendMessage({
-      type: 'abort-session',
+      type: 'chat.abort',
      sessionId: targetSessionId,
-      provider,
    });
-  }, [canAbortSession, currentSessionId, provider, selectedSession?.id, sendMessage]);
+  }, [canAbortSession, currentSessionId, selectedSession?.id, sendMessage]);

  const handleGrantToolPermission = useCallback(
    (suggestion: { entry: string; toolName: string }) => {
@@ -991,7 +958,7 @@ export function useChatComposerState({

      validIds.forEach((requestId) => {
        sendMessage({
-          type: 'claude-permission-response',
+          type: 'chat.permission-response',
          requestId,
          allow: Boolean(decision?.allow),
          updatedInput: decision?.updatedInput,
@@ -1000,15 +967,11 @@ export function useChatComposerState({
        });
      });

-      setPendingPermissionRequests((previous) => {
-        const next = previous.filter((request) => !validIds.includes(request.requestId));
-        if (next.length === 0) {
-          setClaudeStatus(null);
-        }
-        return next;
-      });
+      setPendingPermissionRequests((previous) =>
+        previous.filter((request) => !validIds.includes(request.requestId)),
+      );
    },
-    [sendMessage, setClaudeStatus, setPendingPermissionRequests],
+    [sendMessage, setPendingPermissionRequests],
  );

  const [isInputFocused, setIsInputFocused] = useState(false);
--- a/src/components/chat/hooks/useChatProviderState.ts
+++ b/src/components/chat/hooks/useChatProviderState.ts
@@ -17,17 +17,35 @@ const FALLBACK_DEFAULT_MODEL: Record<LLMProvider, string> = {
  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'];
+/**
+ * Fallback permission-mode matrix used only until the backend capability
+ * matrix (`GET /api/providers/capabilities`) has loaded. The backend is the
+ * source of truth; this mirror exists so the composer renders sensibly on
+ * first paint and when the capabilities request fails.
+ */
+const FALLBACK_PERMISSION_MODES: Record<LLMProvider, PermissionMode[]> = {
+  claude: ['default', 'auto', 'acceptEdits', 'bypassPermissions', 'plan'],
+  cursor: ['default', 'acceptEdits', 'bypassPermissions', 'plan'],
+  codex: ['default', 'acceptEdits', 'bypassPermissions'],
+  gemini: ['default', 'acceptEdits', 'bypassPermissions', 'plan'],
+  opencode: ['default'],
+};
+
+type ProviderCapabilities = {
+  provider: LLMProvider;
+  permissionModes: string[];
+  defaultPermissionMode: string;
+  supportsImages: boolean;
+  supportsAbort: boolean;
+  supportsPermissionRequests: boolean;
+  supportsTokenUsage: boolean;
+};
+
+type ProviderCapabilitiesApiResponse = {
+  success?: boolean;
+  data?: {
+    providers?: ProviderCapabilities[];
+  };
 };

 interface UseChatProviderStateArgs {
@@ -76,6 +94,17 @@ export function useChatProviderState({ selectedSession, selectedProject }: UseCh
    return localStorage.getItem('opencode-model') || FALLBACK_DEFAULT_MODEL.opencode;
  });

+  /**
+   * Backend-owned capability matrix keyed by provider. Drives the permission
+   * mode picker (and is the extension point for future per-provider UI
+   * differences) so the frontend stays free of hardcoded provider branching.
+   * Null until `/api/providers/capabilities` resolves; the static fallback
+   * map covers that window.
+   */
+  const [providerCapabilities, setProviderCapabilities] = useState<
+    Partial<Record<LLMProvider, ProviderCapabilities>> | null
+  >(null);
+
  const [providerModelCatalog, setProviderModelCatalog] = useState<
    Partial<Record<LLMProvider, ProviderModelsDefinition>>
  >({});
@@ -181,6 +210,41 @@ export function useChatProviderState({ selectedSession, selectedProject }: UseCh
    void loadProviderModels();
  }, [loadProviderModels]);

+  useEffect(() => {
+    let cancelled = false;
+
+    const loadCapabilities = async () => {
+      try {
+        const response = await authenticatedFetch('/api/providers/capabilities');
+        const body = (await response.json()) as ProviderCapabilitiesApiResponse;
+        if (cancelled || !body.success || !Array.isArray(body.data?.providers)) {
+          return;
+        }
+
+        const byProvider: Partial<Record<LLMProvider, ProviderCapabilities>> = {};
+        for (const capabilities of body.data.providers) {
+          byProvider[capabilities.provider] = capabilities;
+        }
+        setProviderCapabilities(byProvider);
+      } catch (error) {
+        console.error('Error loading provider capabilities:', error);
+      }
+    };
+
+    void loadCapabilities();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const getPermissionModesForProvider = useCallback((targetProvider: LLMProvider): PermissionMode[] => {
+    const capabilityModes = providerCapabilities?.[targetProvider]?.permissionModes;
+    if (capabilityModes && capabilityModes.length > 0) {
+      return capabilityModes as PermissionMode[];
+    }
+    return FALLBACK_PERMISSION_MODES[targetProvider] ?? ['default'];
+  }, [providerCapabilities]);
+
  const pickStoredOrCurrent = (
    storageKey: string,
    current: string,
@@ -269,7 +333,7 @@ export function useChatProviderState({ selectedSession, selectedProject }: UseCh
    const savedMode = localStorage.getItem(`permissionMode-${selectedSession.id}`) as PermissionMode | null;
    const validModes = getPermissionModesForProvider(provider);
    setPermissionMode(savedMode && validModes.includes(savedMode) ? savedMode : 'default');
-  }, [selectedSession?.id, provider]);
+  }, [selectedSession?.id, provider, getPermissionModesForProvider]);

  useEffect(() => {
    if (!selectedSession?.__provider || selectedSession.__provider === provider) {
@@ -327,7 +391,7 @@ export function useChatProviderState({ selectedSession, selectedProject }: UseCh
    if (selectedSession?.id) {
      localStorage.setItem(`permissionMode-${selectedSession.id}`, nextMode);
    }
-  }, [permissionMode, provider, selectedSession?.id]);
+  }, [permissionMode, provider, selectedSession?.id, getPermissionModesForProvider]);

  const selectProviderModel = useCallback(async (
    targetProvider: LLMProvider,
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Simos Mikelatos	7786763dd1	Fix desktop settings modal behavior	2026-06-18 06:15:17 +00:00
Simos Mikelatos	1dbf545fd9	Authenticate ripgrep install in desktop workflows	2026-06-17 22:29:55 +00:00
Simos Mikelatos	ac37213269	Run desktop branch builds on electron app pushes	2026-06-17 22:26:47 +00:00
Simos Mikelatos	65fdc38f2e	Add desktop app packaging and settings updates	2026-06-17 22:15:36 +00:00
Simos Mikelatos	6c2652aee6	Merge remote-tracking branch 'origin/main' into electron-app # Conflicts: # package-lock.json # package.json # server/index.js # src/components/main-content/types/types.ts # src/components/main-content/view/MainContent.tsx # src/components/main-content/view/subcomponents/MainContentHeader.tsx # src/components/main-content/view/subcomponents/MainContentTabSwitcher.tsx # src/components/main-content/view/subcomponents/MainContentTitle.tsx # src/components/settings/hooks/useSettingsController.ts # src/components/settings/types/types.ts # src/components/settings/view/Settings.tsx # src/components/settings/view/SettingsSidebar.tsx # src/hooks/useProjectsState.ts # src/i18n/locales/de/common.json # src/i18n/locales/en/common.json # src/i18n/locales/en/settings.json # src/i18n/locales/it/common.json # src/i18n/locales/ja/common.json # src/i18n/locales/ko/common.json # src/i18n/locales/ru/common.json # src/i18n/locales/tr/common.json # src/i18n/locales/zh-CN/common.json # src/i18n/locales/zh-TW/common.json # src/types/app.ts	2026-06-17 20:18:09 +00:00
Simos Mikelatos	bf50d29c20	Merge remote-tracking branch 'origin/browser-use' into electron-app # Conflicts: # src/i18n/locales/en/settings.json	2026-06-17 20:17:38 +00:00
Simos Mikelatos	e88539170e	Add browser use as MCP to providers (#889 )	2026-06-17 22:06:17 +02:00
Simos Mikelatos	ffc0cd7501	Improve Browser settings load and managed MCP display	2026-06-17 20:04:44 +00:00
Simos Mikelatos	59194d1502	Refine Browser naming and managed MCP UX - Rename Browser Use surfaces to Browser - Register Browser MCP under the new server name - Mark CloudCLI-managed MCP servers read-only - Adjust MCP stdio framing and sidebar footer sizing	2026-06-17 19:18:23 +00:00
Simos Mikelatos	7e6028b113	feat: add desktop computer use runtime	2026-06-17 19:01:15 +00:00
Simos Mikelatos	9881e5e366	feat(browser-use): improve mobile monitoring ux	2026-06-17 18:19:12 +00:00
Simos Mikelatos	496a895e8a	feat(browser-use): refine monitoring panel ux	2026-06-17 17:39:55 +00:00
Simos Mikelatos	086df034b4	feat(browser-use): simplify agent session monitoring	2026-06-17 17:04:11 +00:00
Simos Mikelatos	fc71fc7d2b	Merge branch 'pr889-fixes' into electron-app # Conflicts: # server/index.js	2026-06-17 15:45:07 +00:00
Simos Mikelatos	a0d56429a7	fix browser use	2026-06-17 15:43:21 +00:00
Simos Mikelatos	6af4afe6f2	Merge branch 'main' into browser-use	2026-06-16 19:02:36 +02:00
Simos Mikelatos	c03ddb25fe	Merge pull request #887 from siteboon/feat/unify-websocket-2 Refactor chat activity indicator and unify session lifecycle handling	2026-06-16 19:01:25 +02:00
Haileyesus	d7a38a567a	chore: move tests to appropriate folder	2026-06-16 17:54:48 +03:00
Haileyesus	fec91d3deb	Merge branch 'feat/unify-websocket-2' of https://github.com/siteboon/claudecodeui into feat/unify-websocket-2	2026-06-16 17:48:08 +03:00
Haileyesus	c6c153e7f2	chore: move tests to appropriate folder	2026-06-16 17:47:52 +03:00
Haile	4758ccf36e	Merge branch 'main' into feat/unify-websocket-2	2026-06-16 17:39:10 +03:00
Haileyesus	e23e6af06a	docs: update session activity guard comment	2026-06-16 17:27:54 +03:00
Haileyesus	56b2e14059	fix: recover pending permission requests	2026-06-16 17:20:40 +03:00
Haileyesus	39b0473e38	fix: keep running-session polling active Keep the running-session poller active even when the local processing set is empty so runs started from another tab or client can still be discovered.	2026-06-16 16:52:12 +03:00
Simos Mikelatos	7aeca52669	Merge branch 'browser-use' into electron-app # Conflicts: # src/components/main-content/view/subcomponents/MainContentTabSwitcher.tsx	2026-06-16 06:51:35 +00:00
Simos Mikelatos	56532af33a	feat: add browser use guide links	2026-06-15 21:22:49 +00:00
Simos Mikelatos	9438a365f2	feat: improve browser use session controls	2026-06-15 21:14:10 +00:00
Simos Mikelatos	e5c6e5e596	fix: hide browser use runtime mode	2026-06-15 20:20:44 +00:00
Simos Mikelatos	0426522406	feat: expose browser use to agents via MCP	2026-06-15 19:47:58 +00:00
Simos Mikelatos	6e7e2ff4c1	feat: make browser use opt-in	2026-06-15 18:12:27 +00:00
Simos Mikelatos	e6263dbd1f	refactor: store browser use settings in database	2026-06-15 17:57:00 +00:00
Simos Mikelatos	260070bae0	feat: add browser use runtime setup settings	2026-06-15 17:52:27 +00:00
Simos Mikelatos	daac6e3fd3	ci: add macos desktop release workflow	2026-06-15 17:26:53 +00:00
Simos Mikelatos	861cfecbaa	feat: add electron app support	2026-06-15 16:21:05 +00:00
Simos Mikelatos	a182765e10	Merge branch 'browser-use' into electron-app	2026-06-15 16:15:03 +00:00
Simos Mikelatos	828d1a2302	Merge remote-tracking branch 'origin/feat/unify-websocket-2' into browser-use-independent	2026-06-15 16:12:10 +00:00
Aurélien	f319d2cf8d	feat(i18n): add French (fr) locale (#878 ) Complete French translation for all 7 locale files: auth, chat, codeEditor, common, settings, sidebar, tasks. Also fixes a bug in languages.js where the Turkish and Italian entries shared the same object (missing closing brace), causing Italian to be silently dropped from the supported languages list. Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-06-15 15:02:50 +03:00
Haileyesus	9fb2d91b26	fix: resolve session provider on backend reads Session history and token usage reads already have a stable app session id. Passing provider and project hints from the frontend kept those reads coupled with provider-specific state that the backend can resolve from the session row. Resolve token usage provider server-side and narrow the session store read API to session id plus pagination. This keeps provider-specific storage decisions behind the backend boundary and makes reconnect, pagination, and load-all use the same session-owned contract.	2026-06-15 14:04:50 +03:00
Haileyesus	9cb2afd67e	fix: upgrade gemini logo	2026-06-15 13:47:28 +03:00
Haileyesus	d0adddbbda	fix: normalize project session payloads The sidebar had to understand cursorSessions, codexSessions, and other provider buckets because /api/projects exposed provider-shaped arrays. That leaked backend adapter storage into project state and made frontend behavior drift each time a provider needed another bucket or exception. Return one sessions list with provider metadata instead. Project state, search, and running-session filtering now share one contract, while provider-specific storage remains behind the backend boundary.	2026-06-15 13:43:18 +03:00
Haileyesus	2abb45636b	fix: remove provider specific token usage calculator	2026-06-15 13:36:57 +03:00
Haileyesus	677d330981	fix: create one unified function for frontend session processing	2026-06-15 13:36:35 +03:00
Simos Mikelatos	d427004bd7	Merge browser use branch	2026-06-14 20:34:36 +00:00
Simos Mikelatos	243e6cecd5	Add browser use workspace panel	2026-06-14 20:34:16 +00:00
Haileyesus	1b336e9aa9	fix(sidebar): align session status controls across layouts	2026-06-13 00:09:59 +03:00
Haileyesus	7bed675ad5	fix: changes provider logos to svg for fast load	2026-06-13 00:04:56 +03:00
Haileyesus	5b9adbbdee	fix(opencode): bind watcher sessions to app rows early	2026-06-12 23:22:11 +03:00
Haileyesus	416a737d76	fix(opencode): pass workspace dir explicitly The remote environment could start OpenCode runs under /opt/claudecodeui. That happened even when the selected project path was correct. The integration relied on child-process cwd alone. OpenCode run resolves its workspace through the explicit --dir contract. Pass --dir with the resolved working directory. Assert in the CLI test that launch args include the workspace dir.	2026-06-12 22:45:22 +03:00
Haileyesus	3bbb42c233	fix(sessions): canonicalize sidebar ids and timestamps The sidebar could keep a provider-native id after backend remapping. That left a duplicate non-working session visible until refresh. Fresh sessions could also appear hours old. SQLite CURRENT_TIMESTAMP is UTC without a timezone suffix. Browser parsing then treated those values like local time. Broadcast a canonical session_upserted event when the provider id is mapped. Collapse provider-id aliases onto the stable app session id in the client. Normalize session-row timestamps to ISO UTC when reading from the repository.	2026-06-12 20:52:18 +03:00
Haileyesus	123ae31020	fix(chat): sort messages appropriately	2026-06-11 21:48:46 +03:00
Haileyesus	89f05247ed	fix(shell): use correct session id	2026-06-11 21:04:31 +03:00
Haileyesus	00e526b6e9	chore: remove a log	2026-06-11 20:22:07 +03:00
Haileyesus	591b18e9e3	feat(sidebar): improve running session state tracking Add a running-session view to the sidebar, including header controls, running counts, empty states, and row-level processing indicators so active provider work is visible outside the current chat. Hydrate running state after refresh through a status-only /api/providers/sessions/running endpoint backed by chatRunRegistry.listRunningRuns, then sync and poll the frontend processingSessions map from AppContent without attaching to chat streams or replaying messages. Preserve fresh local processing entries during sync so newly sent messages are not cleared before the backend registry catches up, and clear completed sessions once the status endpoint no longer reports them. Thread active session state through sidebar project/session components, show rotating loaders for processing sessions, and keep the running search mode expanded and filterable. Fix optimistic local user-message dedupe so repeated prompts are only collapsed when a matching server echo appears from the same send window, preventing sent messages from disappearing until assistant completion. Add registry test coverage for listing currently running app sessions. Tests: npx eslint on changed files; npx tsc --noEmit -p tsconfig.json; npx tsc --noEmit -p server/tsconfig.json; npx tsx --tsconfig server/tsconfig.json --test server/modules/websocket/tests/chat-run-registry.test.ts.	2026-06-11 20:04:38 +03:00
Haileyesus	881e72d4a0	fix: correct notification session id	2026-06-11 19:31:13 +03:00
Haileyesus	f5eac2ec12	feat(chat): unify session gateway with stable IDs and a single WS protocol The frontend previously juggled placeholder IDs, provider-native IDs, and session_created handoffs, which caused race conditions and provider-specific branching. This introduces app-allocated session IDs, a chat run registry with event replay, delta sidebar updates, and one kind-based websocket contract so the UI can treat every provider the same while JSONL remains the source of truth.	2026-06-11 18:47:19 +03:00
Haileyesus	3d948217ef	chore: upgrade gemini models	2026-06-11 18:38:02 +03:00
Simos Mikelatos	86f64797b0	Merge pull request #867 from siteboon/chore/add-github-issues-board-plugin	2026-06-11 13:29:44 +02:00
Haileyesus	21b0f14e7a	chore: add github issues board plugin	2026-06-11 14:00:41 +03:00
Simos Mikelatos	f12af8a61b	Merge pull request #864 from siteboon/chore/add-plugins chore: add plugins	2026-06-11 09:51:07 +02:00
Haileyesus	afc717e69e	feat(chat): derive activity indicator from per-session state and unify provider lifecycle events Replace the chat processing banner with a minimal activity indicator and rebuild the state model underneath it. The old banner was driven by five overlapping pieces of state (isLoading, canAbortSession, claudeStatus in the chat, plus two app-level Sets updated in lockstep through four callbacks) that had to be kept in sync imperatively. Because completion and status events mutated the viewed session's flags regardless of which session they belonged to, a background session finishing could hide the indicator for a still-running session, returning to a finished session could briefly show a stale banner, and a late status reply could override a newer request. The fix is structural rather than patch-by-patch: a single Map<sessionId, {statusText, canInterrupt, startedAt}> in useSessionProtection is now the only source of truth for "this session is working". The indicator, stop button, composer streaming state, and session protection are all derived from the viewed session's entry on render, so there is no stale local copy to restore or reset when switching sessions. A PENDING_SESSION_ID sentinel covers the window before a new conversation receives its real session id. Terminal events delete the entry atomically, which is why the indicator disappears the instant the final chunk arrives. Stale check-session-status replies are discarded via an ifStartedBefore guard (an idle reply older than the entry's startedAt describes a previous request, not the current one). The second half unifies the provider lifecycle contract, because the frontend could not be made race-free while each provider terminated differently: - cursor emitted complete twice per run (result line + process close), which double-played the completion sound and let a late close-complete clear a newer request's indicator - aborts produced two completes (the abort-session reply plus the provider's own non-aborted one), so cancelling a run played the celebration sound - codex omitted exitCode; others attached ad-hoc fields (resultText, isError, isNewSession) the client had to know about - claude/codex failures ended with only an error event while gemini/cursor also emit kind:'error' for mid-run stderr noise, so 'error' was ambiguous between "the run died" and "a process wrote to stderr" Every run now ends with exactly one complete built by createCompleteMessage() ({sessionId, actualSessionId, exitCode, success, aborted}); abort-session sends it on behalf of cancelled runs and providers detect the abort and skip their own. error is demoted to an informational row, so stderr noise no longer kills the indicator mid-run, and the client celebrates only success: true completes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-06-10 19:39:04 +03:00
Haileyesus	f549bd99e7	docs: update available plugin readmes	2026-06-10 16:57:40 +03:00
Haileyesus	bc34085af9	chore: add more plugins list	2026-06-10 16:49:38 +03:00
Simos Mikelatos	6a53c31e90	feat: render changelog as markdown in version upgrade modal	2026-06-09 20:53:15 +00:00
Simos Mikelatos	92de0ed613	chore: remove unused modelConstants from the project	2026-06-09 20:51:19 +00:00
viper151	b6a45b3183	chore(release): v1.34.0	2026-06-09 20:34:48 +00:00
Simos Mikelatos	ce327b6fa9	feat: adding Fable 5 in claude code	2026-06-09 20:33:00 +00:00
viper151	276639099b	chore(release): v1.33.3	2026-06-09 16:18:59 +00:00
Simos Mikelatos	f4f88318c2	Merge pull request #853 from siteboon/feature/chat-completion-notifications feat: signal when chat runs complete	2026-06-09 18:14:53 +02:00
				`@@ -0,0 +1 @@`
				`export { default as BrowserUsePanel } from './view/BrowserUsePanel';`