chore(release): v1.29.3

* fix: remove project dependency from settings controller and onboarding

* fix(settings): remove onClose prop from useSettingsController args

* chore: tailwind classes order

* refactor: move provider auth status management to custom hook

* refactor: rename SessionProvider to LLMProvider

* feat(frontend): support for @ alias based imports)

* fix: replace init.sql with schema.js

* fix: refactor database initialization to use schema.js for SQL statements

* feat(server): add a real backend TypeScript build and enforce module boundaries

The backend had started to grow beyond what the frontend-only tooling setup could
support safely. We were still running server code directly from /server, linting
mainly the client, and relying on path assumptions such as "../.." that only
worked in the source layout. That created three problems:

- backend alias imports were hard to resolve consistently in the editor, ESLint,
  and the runtime
- server code had no enforced module boundary rules, so cross-module deep imports
  could bypass intended public entry points
- building the backend into a separate output directory would break repo-level
  lookups for package.json, .env, dist, and public assets because those paths
  were derived from source-only relative assumptions

This change makes the backend tooling explicit and runtime-safe.

A dedicated backend TypeScript config now lives in server/tsconfig.json, with
tsconfig.server.json reduced to a compatibility shim. This gives the language
service and backend tooling a canonical project rooted in /server while still
preserving top-level compatibility for any existing references. The backend alias
mapping now resolves relative to /server, which avoids colliding with the
frontend's "@/..." -> "src/*" mapping.

The package scripts were updated so development runs through tsx with the backend
tsconfig, build now produces a compiled backend in dist-server, and typecheck/lint
cover both client and server. A new build-server.mjs script runs TypeScript and
tsc-alias and cleans dist-server first, which prevents stale compiled files from
shadowing current source files after refactors.

To make the compiled backend behave the same as the source backend, runtime path
resolution was centralized in server/utils/runtime-paths.js. Instead of assuming
fixed relative paths from each module, server entry points now resolve the actual
app root and server root at runtime. That keeps package.json, .env, dist, public,
and default database paths stable whether code is executed from /server or from
/dist-server/server.

ESLint was expanded from a frontend-only setup into a backend-aware one. The
backend now uses import resolution tied to the backend tsconfig so aliased imports
resolve correctly in linting, import ordering matches the frontend style, and
unused/duplicate imports are surfaced consistently.

Most importantly, eslint-plugin-boundaries now enforces server module boundaries.
Files under server/modules can no longer import another module's internals
directly. Cross-module imports must go through that module's barrel file
(index.ts/index.js). boundaries/no-unknown was also enabled so alias-resolution
gaps cannot silently bypass the rule.

Together, these changes make the backend buildable, keep runtime path resolution
stable after compilation, align server tooling with the client where appropriate,
and enforce a stricter modular architecture for server code.

* fix: update package.json to include dist-server in files and remove tsconfig.server.json

* refactor: remove build-server.mjs and inline its logic into package.json scripts

* fix: update paths in package.json and bin.js to use dist-server directory

* feat(eslint): add backend shared types and enforce compile-time contract for imports

* fix(eslint): update shared types pattern

---------

Co-authored-by: Haileyesus <something@gmail.com>

.github/workflows/release.yml

@@ -20,14 +20,14 @@ jobs:
       contents: write
       id-token: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
           token: ${{ secrets.RELEASE_PAT }}
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
-          node-version: 20
+          node-version: 22
           registry-url: https://registry.npmjs.org
 
       - name: git config

.gitignore

@@ -8,6 +8,7 @@ lerna-debug.log*
 
 # Build outputs
 dist/
+dist-server/
 dist-ssr/
 build/
 out/

CHANGELOG.md

@@ -3,6 +3,42 @@
 All notable changes to CloudCLI UI will be documented in this file.
 
 
+## [1.29.3](https://github.com/siteboon/claudecodeui/compare/v1.29.2...v1.29.3) (2026-04-15)
+
+### Bug Fixes
+
+* **version-upgrade-modal:** implement reload countdown and update UI messages ([#655](https://github.com/siteboon/claudecodeui/issues/655)) ([6413042](https://github.com/siteboon/claudecodeui/commit/641304242d7705b54aab65faa4a7673438c92c60))
+
+### Maintenance
+
+* remove unused route (migrated to providers already) ([31f28a2](https://github.com/siteboon/claudecodeui/commit/31f28a2c183f6ead50941027632d7ab64b7bb2d4))
+
+## [1.29.2](https://github.com/siteboon/claudecodeui/compare/v1.29.1...v1.29.2) (2026-04-14)
+
+### Bug Fixes
+
+* **sandbox:** use backgrounded sbx run to keep sandbox  alive ([9b11c03](https://github.com/siteboon/claudecodeui/commit/9b11c034d9a19710a23b56c62dcf07c21a17bd97))
+
+## [1.29.1](https://github.com/siteboon/claudecodeui/compare/v1.29.0...v1.29.1) (2026-04-14)
+
+### Bug Fixes
+
+* add latest tag to docker npx command and change the detach mode to work without spawn ([4a56972](https://github.com/siteboon/claudecodeui/commit/4a569725dae320a505753359d8edfd8ca79f0fd7))
+
+## [1.29.0](https://github.com/siteboon/claudecodeui/compare/v1.28.1...v1.29.0) (2026-04-14)
+
+### New Features
+
+* adding docker sandbox environments ([13e97e2](https://github.com/siteboon/claudecodeui/commit/13e97e2c71254de7a60afb5495b21064c4bc4241))
+
+### Bug Fixes
+
+* **thinking-mode:** fix dropdown positioning ([#646](https://github.com/siteboon/claudecodeui/issues/646)) ([c7a5baf](https://github.com/siteboon/claudecodeui/commit/c7a5baf1479404bd40e23aa58bd9f677df9a04c6))
+
+### Maintenance
+
+* update release flow node version ([e2459cb](https://github.com/siteboon/claudecodeui/commit/e2459cb0f8b35f54827778a7b444e6c3ca326506))
+
 ## [1.28.1](https://github.com/siteboon/claudecodeui/compare/v1.28.0...v1.28.1) (2026-04-10)
 
 ### New Features

README.de.md

@@ -76,6 +76,8 @@ Der schnellste Einstieg – keine lokale Einrichtung erforderlich. Erhalte eine
 
 ### Self-Hosted (Open Source)
 
+#### npm
+
 CloudCLI UI sofort mit **npx** ausprobieren (erfordert **Node.js** v22+):
 
 ```bash
@@ -93,6 +95,15 @@ cloudcli
 
 Die **[Dokumentation →](https://cloudcli.ai/docs)** enthält weitere Konfigurationsoptionen, PM2, Remote-Server-Einrichtung und mehr.
 
+#### Docker Sandboxes (Experimentell)
+
+Agents in isolierten Sandboxes mit Hypervisor-Isolation ausführen. Standardmäßig wird Claude Code gestartet. Erfordert die [`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/).
+
+```
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project
+```
+
+Unterstützt Claude Code, Codex und Gemini CLI. Weitere Details in der [Sandbox-Dokumentation](docker/).
 
 ---
 

README.ja.md

@@ -72,6 +72,8 @@
 
 ### セルフホスト（オープンソース）
 
+#### npm
+
 **npx** で今すぐ CloudCLI UI を試せます（**Node.js** v22+ が必要）：
 
 ```bash
@@ -89,6 +91,15 @@ cloudcli
 
 より詳細な設定オプション、PM2、リモートサーバー設定などについては **[ドキュメントはこちら →](https://cloudcli.ai/docs)** を参照してください。
 
+#### Docker Sandboxes（実験的）
+
+ハイパーバイザーレベルの分離でエージェントをサンドボックスで実行します。デフォルトでは Claude Code が起動します。[`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/) が必要です。
+
+```
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project
+```
+
+Claude Code、Codex、Gemini CLI に対応。詳細は[サンドボックスのドキュメント](docker/)をご覧ください。
 
 ---
 

README.ko.md

@@ -72,6 +72,8 @@
 
 ### 셀프 호스트 (오픈 소스)
 
+#### npm
+
 **npx**로 즉시 CloudCLI UI를 실행하세요 (Node.js v22+ 필요):
 
 ```bash
@@ -87,7 +89,17 @@ cloudcli
 
 `http://localhost:3001`을 열면 기존 세션이 자동으로 발견됩니다.
 
-자세한 구성 옵션, PM2, 원격 서버 설정 등은 **[문서 →](https://cloudcli.ai/docs)**를 참고하세요
+자세한 구성 옵션, PM2, 원격 서버 설정 등은 **[문서 →](https://cloudcli.ai/docs)**를 참고하세요.
+
+#### Docker Sandboxes (실험적)
+
+하이퍼바이저 수준 격리로 에이전트를 샌드박스에서 실행합니다. 기본 에이전트는 Claude Code입니다. [`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/)가 필요합니다.
+
+```
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project
+```
+
+Claude Code, Codex, Gemini CLI를 지원합니다. 자세한 내용은 [샌드박스 문서](docker/)를 참고하세요.
 
 ---
 

README.md

@@ -76,6 +76,8 @@ The fastest way to get started — no local setup required. Get a fully managed,
 
 ### Self-Hosted (Open source)
 
+#### npm
+
 Try CloudCLI UI instantly with **npx** (requires **Node.js** v22+):
 
 ```
@@ -91,33 +93,41 @@ cloudcli
 
 Open `http://localhost:3001` — all your existing sessions are discovered automatically.
 
-Visit the **[documentation →](https://cloudcli.ai/docs)** for more full configuration options, PM2, remote server setup and more
+Visit the **[documentation →](https://cloudcli.ai/docs)** for full configuration options, PM2, remote server setup and more.
+
+#### Docker Sandboxes (Experimental)
+
+Run agents in isolated sandboxes with hypervisor-level isolation. Starts Claude Code by default. Requires the [`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/).
+
+```
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project
+```
+
+Supports Claude Code, Codex, and Gemini CLI. See the [sandbox docs](docker/) for setup and advanced options.
 
 
 ---
 
 ## Which option is right for you?
 
-CloudCLI UI is the open source UI layer that powers CloudCLI Cloud. You can self-host it on your own machine, or use CloudCLI Cloud which builds on top of it with a full managed cloud environment, team features, and deeper integrations.
+CloudCLI UI is the open source UI layer that powers CloudCLI Cloud. You can self-host it on your own machine, run it in a Docker sandbox for isolation, or use CloudCLI Cloud for a fully managed environment.
 
-| | CloudCLI UI (Self-hosted) | CloudCLI Cloud |
+| | Self-Hosted (npm) | Self-Hosted (Docker Sandbox) *(Experimental)* | CloudCLI Cloud |
-|---|---|---|
+|---|---|---|---|
-| **Best for** | Developers who want a full UI for local agent sessions on their own machine | Teams and developers who want agents running in the cloud, accessible from anywhere |
+| **Best for** | Local agent sessions on your own machine | Isolated agents with web/mobile IDE | Teams who want agents in the cloud |
-| **How you access it** | Browser via `[yourip]:port` | Browser, any IDE, REST API, n8n |
+| **How you access it** | Browser via `[yourip]:port` | Browser via `localhost:port` | Browser, any IDE, REST API, n8n |
-| **Setup** | `npx @cloudcli-ai/cloudcli` | No setup required |
+| **Setup** | `npx @cloudcli-ai/cloudcli` | `npx @cloudcli-ai/cloudcli@latest sandbox ~/project` | No setup required |
-| **Machine needs to stay on** | Yes | No |
+| **Isolation** | Runs on your host | Hypervisor-level sandbox (microVM) | Full cloud isolation |
-| **Mobile access** | Any browser on your network | Any device, native app coming |
+| **Machine needs to stay on** | Yes | Yes | No |
-| **Sessions available** | All sessions auto-discovered from `~/.claude` | All sessions within your cloud environment |
+| **Mobile access** | Any browser on your network | Any browser on your network | Any device, native app coming |
-| **Agents supported** | Claude Code, Cursor CLI, Codex, Gemini CLI | Claude Code, Cursor CLI, Codex, Gemini CLI |
+| **Agents supported** | Claude Code, Cursor CLI, Codex, Gemini CLI | Claude Code, Codex, Gemini CLI | Claude Code, Cursor CLI, Codex, Gemini CLI |
-| **File explorer and Git** | Yes, built into the UI | Yes, built into the UI |
+| **File explorer and Git** | Yes | Yes | Yes |
-| **MCP configuration** | Managed via UI, synced with your local `~/.claude` config | Managed via UI |
+| **MCP configuration** | Synced with `~/.claude` | Managed via UI | Managed via UI |
-| **IDE access** | Your local IDE | Any IDE connected to your cloud environment |
+| **REST API** | Yes | Yes | Yes |
-| **REST API** | Yes | Yes |
+| **Team sharing** | No | No | Yes |
-| **n8n node** | No | Yes |
+| **Platform cost** | Free, open source | Free, open source | Starts at $7/month |
-| **Team sharing** | No | Yes |
-| **Platform cost** | Free, open source | Starts at $7/month |
 
-> Both options use your own AI subscriptions (Claude, Cursor, etc.) — CloudCLI provides the environment, not the AI.
+> All options use your own AI subscriptions (Claude, Cursor, etc.) — CloudCLI provides the environment, not the AI.
 
 ---
 

README.ru.md

@@ -76,6 +76,8 @@
 
 ### Self-Hosted (Open source)
 
+#### npm
+
 Попробовать CloudCLI UI можно сразу через **npx** (требуется **Node.js** v22+):
 
 ```bash
@@ -91,8 +93,17 @@ cloudcli
 
 Откройте `http://localhost:3001` — все ваши существующие сессии будут обнаружены автоматически.
 
-Посетите **[документацию →](https://cloudcli.ai/docs)**, чтобы узнать про дополнительные варианты конфигурации, PM2, настройку удалённого сервера и многое другое
+Посетите **[документацию →](https://cloudcli.ai/docs)**, чтобы узнать про дополнительные варианты конфигурации, PM2, настройку удалённого сервера и многое другое.
 
+#### Docker Sandboxes (Экспериментально)
+
+Запускайте агентов в изолированных песочницах с гипервизорной изоляцией. По умолчанию запускается Claude Code. Требуется [`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/).
+
+```
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project
+```
+
+Поддерживаются Claude Code, Codex и Gemini CLI. Подробнее в [документации sandbox](docker/).
 
 ---
 

README.zh-CN.md

@@ -72,6 +72,8 @@
 
 ### 自托管（开源）
 
+#### npm
+
 启动 CloudCLI UI，只需一行 `npx`（需要 Node.js v22+）：
 
 ```bash
@@ -87,7 +89,17 @@ cloudcli
 
 打开 `http://localhost:3001`，系统会自动发现所有现有会话。
 
-更多配置选项、PM2、远程服务器设置等，请参阅 **[文档 →](https://cloudcli.ai/docs)**
+更多配置选项、PM2、远程服务器设置等，请参阅 **[文档 →](https://cloudcli.ai/docs)**。
+
+#### Docker Sandboxes（实验性）
+
+在隔离的沙箱中运行代理，具有虚拟机管理程序级别的隔离。默认启动 Claude Code。需要 [`sbx` CLI](https://docs.docker.com/ai/sandboxes/get-started/)。
+
+```
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project
+```
+
+支持 Claude Code、Codex 和 Gemini CLI。详情请参阅 [沙箱文档](docker/)。
 
 ---
 

docker/README.md

@@ -1,89 +1,160 @@
-# CloudCLI — Docker Sandbox Templates
+<!-- Docker Hub short description (100 chars max): -->
+<!-- Sandbox templates for running AI coding agents with a web & mobile IDE (Claude Code, Codex, Gemini) -->
 
-Run AI coding agents with a full web IDE inside [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/).
+# Sandboxed coding agents with a web & mobile IDE (CloudCLI)
 
-Instead of a terminal-only experience, get a browser-based interface with chat, file explorer, git panel, shell, and MCP configuration — all running safely inside an isolated sandbox.
+[Docker Sandbox](https://docs.docker.com/ai/sandboxes/) templates that add [CloudCLI](https://cloudcli.ai) on top of Claude Code, Codex, and Gemini CLI. You get a full web and mobile IDE accessible from any browser on any device.
 
-## Available Templates
+## Get started
 
-| Template | Base Image | Agent |
+### 1. Install the sbx CLI
-|----------|-----------|-------|
-| `cloudcli-ai/sandbox:claude-code` | `docker/sandbox-templates:claude-code` | Claude Code |
-| `cloudcli-ai/sandbox:codex` | `docker/sandbox-templates:codex` | OpenAI Codex |
-| `cloudcli-ai/sandbox:gemini` | `docker/sandbox-templates:gemini` | Gemini CLI |
 
-## Quick Start
+Docker Sandboxes run agents in isolated microVMs. Install the `sbx` CLI:
 
-### 1. Start a sandbox with the template
+- **macOS**: `brew install docker/tap/sbx`
+- **Windows**: `winget install -h Docker.sbx`
+- **Linux**: `sudo apt-get install docker-sbx`
+
+Full instructions: [docs.docker.com/ai/sandboxes/get-started](https://docs.docker.com/ai/sandboxes/get-started/)
+
+### 2. Store your API key
+
+`sbx` manages credentials securely — your API key never enters the sandbox. Store it once:
 
 ```bash
-sbx run --template docker.io/cloudcli-ai/sandbox:claude-code claude ~/my-project
+sbx login
+sbx secret set -g anthropic
 ```
 
-### 2. Forward the UI port
+### 3. Launch Claude Code
 
 ```bash
-sbx ports <sandbox-name> --publish 3001:3001
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project
 ```
 
-### 3. Open the browser
+Open **http://localhost:3001**. Set a password on first visit. Start building.
 
-```
+### Using a different agent
-http://localhost:3001
+
+Store the matching API key and pass `--agent`:
+
+```bash
+# OpenAI Codex
+sbx secret set -g openai
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project --agent codex
+
+# Gemini CLI
+sbx secret set -g google
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project --agent gemini
 ```
 
-On first visit you'll set a password — this protects the UI if the port is ever exposed beyond localhost.
+### Available templates
 
-## What You Get
+| Agent | Template |
+|-------|----------|
+| **Claude Code** (default) | `docker.io/cloudcliai/sandbox:claude-code` |
+| OpenAI Codex | `docker.io/cloudcliai/sandbox:codex` |
+| Gemini CLI | `docker.io/cloudcliai/sandbox:gemini` |
 
-- **Chat** — Rich conversation UI with markdown rendering, code blocks, and message history
+These are used with `--template` when running `sbx` directly (see [Advanced usage](#advanced-usage)).
-- **Files** — Visual file tree with syntax-highlighted editor
+
-- **Git** — Diff viewer, staging, branch switching, and commit — all visual
+## Managing sandboxes
+
+```bash
+sbx ls                               # List all sandboxes
+sbx stop my-project                  # Stop (preserves state)
+sbx start my-project                 # Restart a stopped sandbox
+sbx rm my-project                    # Remove everything
+sbx exec my-project bash             # Open a shell inside the sandbox
+```
+
+If you install CloudCLI globally (`npm install -g @cloudcli-ai/cloudcli`), you can also use:
+
+```bash
+cloudcli sandbox ls
+cloudcli sandbox start my-project    # Restart and re-launch web UI
+cloudcli sandbox logs my-project     # View server logs
+```
+
+## What you get
+
+- **Chat** — Markdown rendering, code blocks, message history
+- **Files** — File tree with syntax-highlighted editor
+- **Git** — Diff viewer, staging, branch switching, commits
 - **Shell** — Built-in terminal emulator
-- **MCP** — Configure Model Context Protocol servers through the UI
+- **MCP** — Configure Model Context Protocol servers visually
 - **Mobile** — Works on tablet and phone browsers
 
-## Building Locally
+Your project directory is mounted bidirectionally — edits propagate in real time, both ways.
-
-All Dockerfiles share scripts from `shared/`. Build with the `docker/` directory as context:
-
-```bash
-# Claude Code variant
-docker build -f docker/claude-code/Dockerfile -t cloudcli-sandbox:claude-code docker/
-
-# Codex variant
-docker build -f docker/codex/Dockerfile -t cloudcli-sandbox:codex docker/
-
-# Gemini variant
-docker build -f docker/gemini/Dockerfile -t cloudcli-sandbox:gemini docker/
-```
-
-## How It Works
-
-Each template extends Docker's official sandbox base image and adds:
-
-1. **Node.js 22** — Runtime for CloudCLI
-2. **CloudCLI** — Installed globally via `npm install -g @cloudcli-ai/cloudcli`
-3. **Auto-start** — The UI server starts in the background when the sandbox shell opens (port 3001)
-
-The agent (Claude Code, Codex, or Gemini) comes from the base image. CloudCLI connects to it and provides the web interface on top.
 
 ## Configuration
 
-| Environment Variable | Default | Description |
+Set variables at creation time with `--env`:
-|---------------------|---------|-------------|
-| `SERVER_PORT` | `3001` | Port for the web UI |
-| `HOST` | `0.0.0.0` | Bind address |
-| `DATABASE_PATH` | `~/.cloudcli/auth.db` | SQLite database location |
-
-## Network Policies
-
-If your sandbox uses restricted network policies, allow the UI port:
 
 ```bash
-sbx policy allow network "localhost:3001"
+npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project --env SERVER_PORT=8080
 ```
 
+Or inside a running sandbox:
+
+```bash
+sbx exec my-project bash -c 'echo "export SERVER_PORT=8080" >> /etc/sandbox-persistent.sh'
+```
+
+Restart CloudCLI for changes to take effect:
+
+```bash
+sbx exec my-project bash -c 'pkill -f "server/index.js"'
+sbx exec -d my-project cloudcli start --port 3001
+```
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SERVER_PORT` | `3001` | Web UI port |
+| `HOST` | `0.0.0.0` | Bind address (must be `0.0.0.0` for `sbx ports`) |
+| `DATABASE_PATH` | `~/.cloudcli/auth.db` | SQLite database location |
+
+## Advanced usage
+
+For branch mode, multiple workspaces, memory limits, or the terminal agent experience, use `sbx` with the template:
+
+```bash
+# Terminal agent + web UI
+sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/my-project --name my-project
+sbx ports my-project --publish 3001:3001
+
+# Branch mode (Git worktree isolation)
+sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/my-project --branch my-feature
+
+# Multiple workspaces
+sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/project ~/shared-libs:ro
+
+# Pass a prompt directly
+sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/my-project -- "Fix the auth bug"
+```
+
+CloudCLI auto-starts via `.bashrc` when using `sbx run`.
+
+Full options in the [Docker Sandboxes usage guide](https://docs.docker.com/ai/sandboxes/usage/).
+
+## Network policies
+
+Sandboxes restrict outbound access by default. To reach host services from inside the sandbox:
+
+```bash
+sbx policy allow network localhost:11434
+# Inside the sandbox: curl http://host.docker.internal:11434
+```
+
+The web UI itself doesn't need a policy — access it via `sbx ports`.
+
+## Links
+
+- [CloudCLI Cloud](https://cloudcli.ai) — fully managed, no setup required
+- [Documentation](https://cloudcli.ai/docs) — full configuration guide
+- [Discord](https://discord.gg/buxwujPNRE) — community support
+- [GitHub](https://github.com/siteboon/claudecodeui) — source code and issues
+
 ## License
 
-These templates are free and open-source under the same license as CloudCLI (AGPL-3.0-or-later).
+AGPL-3.0-or-later

docker/claude-code/Dockerfile

@@ -5,7 +5,7 @@ COPY shared/install-cloudcli.sh /tmp/install-cloudcli.sh
 RUN chmod +x /tmp/install-cloudcli.sh && /tmp/install-cloudcli.sh
 
 USER agent
-RUN npm install -g @cloudcli-ai/cloudcli
+RUN npm install -g @cloudcli-ai/cloudcli && cloudcli --version
 
-COPY shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
+COPY --chown=agent:agent shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
 RUN echo '. ~/.cloudcli-start.sh' >> /home/agent/.bashrc

docker/codex/Dockerfile

@@ -5,7 +5,7 @@ COPY shared/install-cloudcli.sh /tmp/install-cloudcli.sh
 RUN chmod +x /tmp/install-cloudcli.sh && /tmp/install-cloudcli.sh
 
 USER agent
-RUN npm install -g @cloudcli-ai/cloudcli
+RUN npm install -g @cloudcli-ai/cloudcli && cloudcli --version
 
-COPY shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
+COPY --chown=agent:agent shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
 RUN echo '. ~/.cloudcli-start.sh' >> /home/agent/.bashrc

docker/gemini/Dockerfile

@@ -5,7 +5,7 @@ COPY shared/install-cloudcli.sh /tmp/install-cloudcli.sh
 RUN chmod +x /tmp/install-cloudcli.sh && /tmp/install-cloudcli.sh
 
 USER agent
-RUN npm install -g @cloudcli-ai/cloudcli
+RUN npm install -g @cloudcli-ai/cloudcli && cloudcli --version
 
-COPY shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
+COPY --chown=agent:agent shared/start-cloudcli.sh /home/agent/.cloudcli-start.sh
 RUN echo '. ~/.cloudcli-start.sh' >> /home/agent/.bashrc

docker/shared/install-cloudcli.sh

@@ -1,13 +1,10 @@
 #!/bin/bash
 set -e
 
-# Install Node.js 22 LTS
+# Install build tools needed for native modules (node-pty, better-sqlite3, bcrypt)
-curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
+# Node.js is already provided by the sandbox base image
-
+apt-get update && apt-get install -y --no-install-recommends \
-# Install Node.js + build tools needed for native modules (node-pty, better-sqlite3, bcrypt)
+  build-essential python3 python3-setuptools \
-# Node.js + build tools for native modules + common dev tools
-apt-get install -y --no-install-recommends \
-  nodejs build-essential python3 python3-setuptools \
   jq ripgrep sqlite3 zip unzip tree vim-tiny
 
 # Clean up apt cache to reduce image size

docker/shared/start-cloudcli.sh

@@ -4,19 +4,14 @@
 # This script is sourced from ~/.bashrc on sandbox shell open.
 
 if ! pgrep -f "server/index.js" > /dev/null 2>&1; then
-  # Start the pre-installed version immediately
   nohup cloudcli start --port 3001 > /tmp/cloudcli-ui.log 2>&1 &
   disown
 
-  # Check for updates in the background (non-blocking)
-  nohup npm update -g @cloudcli-ai/cloudcli > /tmp/cloudcli-update.log 2>&1 &
-  disown
-
   echo ""
   echo "  CloudCLI is starting on port 3001..."
   echo ""
-  echo "  To access the web UI, forward the port:"
+  echo "  Forward the port from another terminal:"
-  echo "    sbx ports \$(hostname) --publish 3001:3001"
+  echo "    sbx ports <sandbox-name> --publish 3001:3001"
   echo ""
   echo "  Then open: http://localhost:3001"
   echo ""

eslint.config.js

@@ -3,7 +3,9 @@ import tseslint from "typescript-eslint";
 import react from "eslint-plugin-react";
 import reactHooks from "eslint-plugin-react-hooks";
 import reactRefresh from "eslint-plugin-react-refresh";
-import importX from "eslint-plugin-import-x";
+import { createNodeResolver, importX } from "eslint-plugin-import-x";
+import { createTypeScriptImportResolver } from "eslint-import-resolver-typescript";
+import boundaries from "eslint-plugin-boundaries";
 import tailwindcss from "eslint-plugin-tailwindcss";
 import unusedImports from "eslint-plugin-unused-imports";
 import globals from "globals";
@@ -82,7 +84,7 @@ export default tseslint.config(
             "sibling",
             "index",
           ],
-          "newlines-between": "never",
+          "newlines-between": "always",
         },
       ],
 
@@ -98,5 +100,131 @@ export default tseslint.config(
       "no-control-regex": "off",
       "no-useless-escape": "off",
     },
+  },
+  {
+    files: ["server/**/*.{js,ts}"], // apply this block only to backend source files
+    ignores: ["server/**/*.d.ts"], // skip generated declaration files in backend linting
+    plugins: {
+      boundaries, // enforce backend architecture boundaries (module-to-module contracts)
+      "import-x": importX, // keep import hygiene rules (duplicates, unresolved paths, etc.)
+      "unused-imports": unusedImports, // remove dead imports/variables from backend files
+    },
+    languageOptions: {
+      parser: tseslint.parser, // parse both JS and TS syntax in backend files
+      parserOptions: {
+        ecmaVersion: "latest", // support modern ECMAScript syntax in backend code
+        sourceType: "module", // treat backend files as ESM modules
+      },
+      globals: {
+        ...globals.node, // expose Node.js globals such as process, Buffer, and __dirname equivalents
+      },
+    },
+    settings: {
+      "boundaries/include": ["server/**/*.{js,ts}"], // only analyze dependency boundaries inside backend files
+      "import/resolver": {
+        // boundaries resolves imports through eslint-module-utils, which reads the classic
+        // import/resolver setting instead of import-x/resolver-next.
+        typescript: {
+          project: ["server/tsconfig.json"], // resolve backend aliases using the canonical backend tsconfig
+          alwaysTryTypes: true, // keep normal TS package/type resolution working alongside aliases
+        },
+        node: {
+          extensions: [".mjs", ".cjs", ".js", ".json", ".node", ".ts", ".tsx"], // preserve Node-style fallback resolution for plain files
+        },
+      },
+      "import-x/resolver-next": [
+        // ESLint's import plugin does not read tsconfig path aliases on its own.
+        // This resolver teaches import-x how to understand the backend-only "@/*"
+        // mapping defined in server/tsconfig.json, which fixes false no-unresolved errors in editors.
+        createTypeScriptImportResolver({
+          project: ["server/tsconfig.json"], // point the resolver at the canonical backend tsconfig instead of the frontend one
+          alwaysTryTypes: true, // keep standard TypeScript package resolution working while backend aliases are enabled
+        }),
+        // Keep Node-style resolution available for normal package imports and plain relative JS files.
+        // The TypeScript resolver handles aliases, while the Node resolver preserves the expected fallback behavior.
+        createNodeResolver({
+          extensions: [".mjs", ".cjs", ".js", ".json", ".node", ".ts", ".tsx"],
+        }),
+      ],
+      "boundaries/elements": [
+        {
+          type: "backend-shared-types", // shared backend type contract that modules may consume without creating runtime coupling
+          pattern: ["server/shared/types.{js,ts}"], // support the current shared types path
+          mode: "file", // treat the types file itself as the boundary element instead of the whole folder
+        },
+        {
+          type: "backend-module", // logical element name used by boundaries rules below
+          pattern: "server/modules/*", // each direct folder in server/modules is treated as one module boundary
+          mode: "folder", // classify dependencies at folder-module level (not per individual file)
+          capture: ["moduleName"], // capture the module folder name for messages/debugging/template use
+        },
+      ],
+    },
+    rules: {
+      // --- Unused imports/vars (backend) ---
+      "unused-imports/no-unused-imports": "warn", // warn when imports are not used so they can be cleaned up
+      "unused-imports/no-unused-vars": "off", // keep backend signal focused on dead imports instead of local unused variables
+
+      // --- Import hygiene (backend) ---
+      "import-x/no-duplicates": "warn", // prevent duplicate import lines from the same module
+      "import-x/order": [
+        "warn", // keep backend import grouping/order consistent with the frontend config
+        {
+          groups: [
+            "builtin", // Node built-ins such as fs, path, and url come first
+            "external", // third-party packages come after built-ins
+            "internal", // aliased internal imports such as @/... come next
+            "parent", // ../ imports come after aliased internal imports
+            "sibling", // ./foo imports come after parent imports
+            "index", // bare ./ imports stay last
+          ],
+          "newlines-between": "always", // require a blank line between import groups in backend files too
+        },
+      ],
+      "import-x/no-unresolved": "error", // fail when an import path cannot be resolved
+      "import-x/no-useless-path-segments": "warn", // prefer cleaner paths (remove redundant ./ and ../ segments)
+      "import-x/no-absolute-path": "error", // disallow absolute filesystem imports in backend files
+
+      // --- General safety/style (backend) ---
+      eqeqeq: ["warn", "always", { null: "ignore" }], // avoid accidental coercion while still allowing x == null checks
+
+      // --- Architecture boundaries (backend modules) ---
+      "boundaries/dependencies": [
+        "error", // treat architecture violations as lint errors
+        {
+          default: "allow", // allow normal imports unless a rule below explicitly disallows them
+          checkInternals: false, // do not apply these cross-module rules to imports inside the same module
+          rules: [
+            {
+              from: { type: "backend-module" }, // modules may depend on the shared types contract only as erased type-only imports
+              to: { type: "backend-shared-types" },
+              disallow: {
+                dependency: { kind: ["value", "typeof"] },
+              }, // block runtime imports so shared types stay a compile-time contract instead of a hidden shared module
+              message:
+                "Backend modules may only use `import type` when importing from server/shared/types.ts (or server/types.ts).",
+            },
+            {
+              to: { type: "backend-module" }, // when importing anything that belongs to another backend module
+              disallow: { to: { internalPath: "**" } }, // block all direct/deep imports into module internals by default
+              message:
+                "Cross-module imports must go through that module's barrel file (server/modules/<module>/index.ts or index.js).", // explicit error message for architecture violations
+            },
+            {
+              to: { type: "backend-module" }, // same target scope as the disallow rule above
+              allow: {
+                to: {
+                  internalPath: [
+                    "index", // allow extensionless barrel imports resolved as module root index
+                    "index.{js,mjs,cjs,ts,tsx}", // allow explicit index.* barrel file imports
+                  ],
+                },
+              }, // re-allow only public module entry points (barrel files)
+            },
+          ],
+        },
+      ],
+      "boundaries/no-unknown": "error", // fail fast if boundaries cannot classify a dependency, which prevents silent rule bypasses
+    },
   }
 );

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@cloudcli-ai/cloudcli",
-  "version": "1.28.1",
+  "version": "1.29.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@cloudcli-ai/cloudcli",
-      "version": "1.28.1",
+      "version": "1.29.3",
       "hasInstallScript": true,
       "license": "AGPL-3.0-or-later",
       "dependencies": {
@@ -69,7 +69,7 @@
         "ws": "^8.14.2"
       },
       "bin": {
-        "cloudcli": "server/cli.js"
+        "cloudcli": "dist-server/server/cli.js"
       },
       "devDependencies": {
         "@commitlint/cli": "^20.4.3",
@@ -84,6 +84,8 @@
         "autoprefixer": "^10.4.16",
         "concurrently": "^8.2.2",
         "eslint": "^9.39.3",
+        "eslint-import-resolver-typescript": "^4.4.4",
+        "eslint-plugin-boundaries": "^6.0.2",
         "eslint-plugin-import-x": "^4.16.1",
         "eslint-plugin-react": "^7.37.5",
         "eslint-plugin-react-hooks": "^7.0.1",
@@ -98,6 +100,8 @@
         "release-it": "^19.0.5",
         "sharp": "^0.34.2",
         "tailwindcss": "^3.4.0",
+        "tsc-alias": "^1.8.16",
+        "tsx": "^4.21.0",
         "typescript": "^5.9.3",
         "typescript-eslint": "^8.56.1",
         "vite": "^7.0.4"
@@ -443,6 +447,23 @@
         "node": ">=6.9.0"
       }
     },
+    "node_modules/@boundaries/elements": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/@boundaries/elements/-/elements-2.0.1.tgz",
+      "integrity": "sha512-sAWO3D8PFP6pBXdxxW93SQi/KQqqhE2AAHo3AgWfdtJXwO6bfK6/wUN81XnOZk0qRC6vHzUEKhjwVD9dtDWvxg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "eslint-import-resolver-node": "0.3.9",
+        "eslint-module-utils": "2.12.1",
+        "handlebars": "4.7.9",
+        "is-core-module": "2.16.1",
+        "micromatch": "4.0.8"
+      },
+      "engines": {
+        "node": ">=18.18"
+      }
+    },
     "node_modules/@codemirror/autocomplete": {
       "version": "6.18.6",
       "resolved": "https://registry.npmjs.org/@codemirror/autocomplete/-/autocomplete-6.18.6.tgz",
@@ -4815,6 +4836,16 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/array-union": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/array-union/-/array-union-2.1.0.tgz",
+      "integrity": "sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/array.prototype.findlast": {
       "version": "1.2.5",
       "resolved": "https://registry.npmjs.org/array.prototype.findlast/-/array.prototype.findlast-1.2.5.tgz",
@@ -6673,6 +6704,19 @@
       "integrity": "sha512-gxtyfqMg7GKyhQmb056K7M3xszy/myH8w+B4RT+QXBQsvAOdc3XymqDDPHx1BgPgsdAA5SIifona89YtRATDzw==",
       "license": "Apache-2.0"
     },
+    "node_modules/dir-glob": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/dir-glob/-/dir-glob-3.0.1.tgz",
+      "integrity": "sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "path-type": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/dlv": {
       "version": "1.1.3",
       "resolved": "https://registry.npmjs.org/dlv/-/dlv-1.1.3.tgz",
@@ -7217,6 +7261,112 @@
         }
       }
     },
+    "node_modules/eslint-import-resolver-node": {
+      "version": "0.3.9",
+      "resolved": "https://registry.npmjs.org/eslint-import-resolver-node/-/eslint-import-resolver-node-0.3.9.tgz",
+      "integrity": "sha512-WFj2isz22JahUv+B788TlO3N6zL3nNJGU8CcZbPZvVEkBPaJdCV4vy5wyghty5ROFbCRnm132v8BScu5/1BQ8g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "debug": "^3.2.7",
+        "is-core-module": "^2.13.0",
+        "resolve": "^1.22.4"
+      }
+    },
+    "node_modules/eslint-import-resolver-node/node_modules/debug": {
+      "version": "3.2.7",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-3.2.7.tgz",
+      "integrity": "sha512-CFjzYYAi4ThfiQvizrFQevTTXHtnCqWfe7x1AhgEscTz6ZbLbfoLRLPugTQyBth6f8ZERVUSyWHFD/7Wu4t1XQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ms": "^2.1.1"
+      }
+    },
+    "node_modules/eslint-import-resolver-typescript": {
+      "version": "4.4.4",
+      "resolved": "https://registry.npmjs.org/eslint-import-resolver-typescript/-/eslint-import-resolver-typescript-4.4.4.tgz",
+      "integrity": "sha512-1iM2zeBvrYmUNTj2vSC/90JTHDth+dfOfiNKkxApWRsTJYNrc8rOdxxIf5vazX+BiAXTeOT0UvWpGI/7qIWQOw==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "debug": "^4.4.1",
+        "eslint-import-context": "^0.1.8",
+        "get-tsconfig": "^4.10.1",
+        "is-bun-module": "^2.0.0",
+        "stable-hash-x": "^0.2.0",
+        "tinyglobby": "^0.2.14",
+        "unrs-resolver": "^1.7.11"
+      },
+      "engines": {
+        "node": "^16.17.0 || >=18.6.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/eslint-import-resolver-typescript"
+      },
+      "peerDependencies": {
+        "eslint": "*",
+        "eslint-plugin-import": "*",
+        "eslint-plugin-import-x": "*"
+      },
+      "peerDependenciesMeta": {
+        "eslint-plugin-import": {
+          "optional": true
+        },
+        "eslint-plugin-import-x": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/eslint-module-utils": {
+      "version": "2.12.1",
+      "resolved": "https://registry.npmjs.org/eslint-module-utils/-/eslint-module-utils-2.12.1.tgz",
+      "integrity": "sha512-L8jSWTze7K2mTg0vos/RuLRS5soomksDPoJLXIslC7c8Wmut3bx7CPpJijDcBZtxQ5lrbUdM+s0OlNbz0DCDNw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "debug": "^3.2.7"
+      },
+      "engines": {
+        "node": ">=4"
+      },
+      "peerDependenciesMeta": {
+        "eslint": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/eslint-module-utils/node_modules/debug": {
+      "version": "3.2.7",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-3.2.7.tgz",
+      "integrity": "sha512-CFjzYYAi4ThfiQvizrFQevTTXHtnCqWfe7x1AhgEscTz6ZbLbfoLRLPugTQyBth6f8ZERVUSyWHFD/7Wu4t1XQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ms": "^2.1.1"
+      }
+    },
+    "node_modules/eslint-plugin-boundaries": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/eslint-plugin-boundaries/-/eslint-plugin-boundaries-6.0.2.tgz",
+      "integrity": "sha512-wSHgiYeMEbziP91lH0UQ9oslgF2djG1x+LV9z/qO19ggMKZaCB8pKIGePHAY91eLF4EAgpsxQk8MRSFGRPfPzw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@boundaries/elements": "2.0.1",
+        "chalk": "4.1.2",
+        "eslint-import-resolver-node": "0.3.9",
+        "eslint-module-utils": "2.12.1",
+        "handlebars": "4.7.9",
+        "micromatch": "4.0.8"
+      },
+      "engines": {
+        "node": ">=18.18"
+      },
+      "peerDependencies": {
+        "eslint": ">=6.0.0"
+      }
+    },
     "node_modules/eslint-plugin-import-x": {
       "version": "4.16.1",
       "resolved": "https://registry.npmjs.org/eslint-plugin-import-x/-/eslint-plugin-import-x-4.16.1.tgz",
@@ -8519,6 +8669,27 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/globby": {
+      "version": "11.1.0",
+      "resolved": "https://registry.npmjs.org/globby/-/globby-11.1.0.tgz",
+      "integrity": "sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "array-union": "^2.1.0",
+        "dir-glob": "^3.0.1",
+        "fast-glob": "^3.2.9",
+        "ignore": "^5.2.0",
+        "merge2": "^1.4.1",
+        "slash": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/gopd": {
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
@@ -8554,9 +8725,9 @@
       }
     },
     "node_modules/handlebars": {
-      "version": "4.7.8",
+      "version": "4.7.9",
-      "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.8.tgz",
+      "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.9.tgz",
-      "integrity": "sha512-vafaFqs8MZkRrSX7sFVUdo3ap/eNiLnb4IakshzvP56X5Nr1iGKAIqdX6tMlm6HcNRIkr6AxO5jFEoJzzpT8aQ==",
+      "integrity": "sha512-4E71E0rpOaQuJR2A3xDZ+GM1HyWYv1clR58tC8emQNeQe3RH7MAzSbat+V0wG78LQBo6m6bzSG/L4pBuCsgnUQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -9446,6 +9617,29 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/is-bun-module": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/is-bun-module/-/is-bun-module-2.0.0.tgz",
+      "integrity": "sha512-gNCGbnnnnFAUGKeZ9PdbyeGYJqewpmc2aKHUEMO5nQPWU9lOmv7jcmQIv+qHD8fXW6W7qfuCwX4rY9LNRjXrkQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "semver": "^7.7.1"
+      }
+    },
+    "node_modules/is-bun-module/node_modules/semver": {
+      "version": "7.7.4",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
+      "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/is-callable": {
       "version": "1.2.7",
       "resolved": "https://registry.npmjs.org/is-callable/-/is-callable-1.2.7.tgz",
@@ -12026,6 +12220,20 @@
         "node": "^18.17.0 || >=20.5.0"
       }
     },
+    "node_modules/mylas": {
+      "version": "2.1.14",
+      "resolved": "https://registry.npmjs.org/mylas/-/mylas-2.1.14.tgz",
+      "integrity": "sha512-BzQguy9W9NJgoVn2mRWzbFrFWWztGCcng2QI9+41frfk+Athwgx3qhqhvStz7ExeUUu7Kzw427sNzHpEZNINog==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=16.0.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/raouldeheer"
+      }
+    },
     "node_modules/mz": {
       "version": "2.7.0",
       "resolved": "https://registry.npmjs.org/mz/-/mz-2.7.0.tgz",
@@ -12989,6 +13197,16 @@
       "integrity": "sha512-RA1GjUVMnvYFxuqovrEqZoxxW5NUZqbwKtYz/Tt7nXerk0LbLblQmrsgdeOxV5SFHf0UDggjS/bSeOZwt1pmEQ==",
       "license": "MIT"
     },
+    "node_modules/path-type": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz",
+      "integrity": "sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/pathe": {
       "version": "2.0.3",
       "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
@@ -13051,6 +13269,19 @@
         "pathe": "^2.0.3"
       }
     },
+    "node_modules/plimit-lit": {
+      "version": "1.6.1",
+      "resolved": "https://registry.npmjs.org/plimit-lit/-/plimit-lit-1.6.1.tgz",
+      "integrity": "sha512-B7+VDyb8Tl6oMJT9oSO2CW8XC/T4UcJGrwOVoNGwOQsQYhlpfajmrMj5xeejqaASq3V/EqThyOeATEOMuSEXiA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "queue-lit": "^1.5.1"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/possible-typed-array-names": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/possible-typed-array-names/-/possible-typed-array-names-1.1.0.tgz",
@@ -13412,6 +13643,16 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/queue-lit": {
+      "version": "1.5.2",
+      "resolved": "https://registry.npmjs.org/queue-lit/-/queue-lit-1.5.2.tgz",
+      "integrity": "sha512-tLc36IOPeMAubu8BkW8YDBV+WyIgKlYU7zUNs0J5Vk9skSZ4JfGlPOqplP0aHdfv7HL0B2Pg6nwiq60Qc6M2Hw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/queue-microtask": {
       "version": "1.2.3",
       "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz",
@@ -15173,6 +15414,16 @@
         "is-arrayish": "^0.3.1"
       }
     },
+    "node_modules/slash": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
+      "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/slice-ansi": {
       "version": "8.0.0",
       "resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-8.0.0.tgz",
@@ -16479,12 +16730,599 @@
       "integrity": "sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA==",
       "license": "Apache-2.0"
     },
+    "node_modules/tsc-alias": {
+      "version": "1.8.16",
+      "resolved": "https://registry.npmjs.org/tsc-alias/-/tsc-alias-1.8.16.tgz",
+      "integrity": "sha512-QjCyu55NFyRSBAl6+MTFwplpFcnm2Pq01rR/uxfqJoLMm6X3O14KEGtaSDZpJYaE1bJBGDjD0eSuiIWPe2T58g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "chokidar": "^3.5.3",
+        "commander": "^9.0.0",
+        "get-tsconfig": "^4.10.0",
+        "globby": "^11.0.4",
+        "mylas": "^2.1.9",
+        "normalize-path": "^3.0.0",
+        "plimit-lit": "^1.2.6"
+      },
+      "bin": {
+        "tsc-alias": "dist/bin/index.js"
+      },
+      "engines": {
+        "node": ">=16.20.2"
+      }
+    },
+    "node_modules/tsc-alias/node_modules/chokidar": {
+      "version": "3.6.0",
+      "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.6.0.tgz",
+      "integrity": "sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "anymatch": "~3.1.2",
+        "braces": "~3.0.2",
+        "glob-parent": "~5.1.2",
+        "is-binary-path": "~2.1.0",
+        "is-glob": "~4.0.1",
+        "normalize-path": "~3.0.0",
+        "readdirp": "~3.6.0"
+      },
+      "engines": {
+        "node": ">= 8.10.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.2"
+      }
+    },
+    "node_modules/tsc-alias/node_modules/commander": {
+      "version": "9.5.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-9.5.0.tgz",
+      "integrity": "sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^12.20.0 || >=14"
+      }
+    },
+    "node_modules/tsc-alias/node_modules/glob-parent": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz",
+      "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "is-glob": "^4.0.1"
+      },
+      "engines": {
+        "node": ">= 6"
+      }
+    },
+    "node_modules/tsc-alias/node_modules/readdirp": {
+      "version": "3.6.0",
+      "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-3.6.0.tgz",
+      "integrity": "sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "picomatch": "^2.2.1"
+      },
+      "engines": {
+        "node": ">=8.10.0"
+      }
+    },
     "node_modules/tslib": {
       "version": "2.8.1",
       "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
       "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
       "license": "0BSD"
     },
+    "node_modules/tsx": {
+      "version": "4.21.0",
+      "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.21.0.tgz",
+      "integrity": "sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "~0.27.0",
+        "get-tsconfig": "^4.7.5"
+      },
+      "bin": {
+        "tsx": "dist/cli.mjs"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/aix-ppc64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.7.tgz",
+      "integrity": "sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/android-arm": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.7.tgz",
+      "integrity": "sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/android-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.7.tgz",
+      "integrity": "sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/android-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.7.tgz",
+      "integrity": "sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/darwin-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.7.tgz",
+      "integrity": "sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/darwin-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.7.tgz",
+      "integrity": "sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.7.tgz",
+      "integrity": "sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/freebsd-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.7.tgz",
+      "integrity": "sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-arm": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.7.tgz",
+      "integrity": "sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.7.tgz",
+      "integrity": "sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-ia32": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.7.tgz",
+      "integrity": "sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-loong64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.7.tgz",
+      "integrity": "sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-mips64el": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.7.tgz",
+      "integrity": "sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-ppc64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.7.tgz",
+      "integrity": "sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-riscv64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.7.tgz",
+      "integrity": "sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-s390x": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.7.tgz",
+      "integrity": "sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/linux-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.7.tgz",
+      "integrity": "sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.7.tgz",
+      "integrity": "sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/netbsd-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.7.tgz",
+      "integrity": "sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.7.tgz",
+      "integrity": "sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/openbsd-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.7.tgz",
+      "integrity": "sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.7.tgz",
+      "integrity": "sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/sunos-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.7.tgz",
+      "integrity": "sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/win32-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.7.tgz",
+      "integrity": "sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/win32-ia32": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.7.tgz",
+      "integrity": "sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/@esbuild/win32-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.7.tgz",
+      "integrity": "sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tsx/node_modules/esbuild": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.7.tgz",
+      "integrity": "sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.27.7",
+        "@esbuild/android-arm": "0.27.7",
+        "@esbuild/android-arm64": "0.27.7",
+        "@esbuild/android-x64": "0.27.7",
+        "@esbuild/darwin-arm64": "0.27.7",
+        "@esbuild/darwin-x64": "0.27.7",
+        "@esbuild/freebsd-arm64": "0.27.7",
+        "@esbuild/freebsd-x64": "0.27.7",
+        "@esbuild/linux-arm": "0.27.7",
+        "@esbuild/linux-arm64": "0.27.7",
+        "@esbuild/linux-ia32": "0.27.7",
+        "@esbuild/linux-loong64": "0.27.7",
+        "@esbuild/linux-mips64el": "0.27.7",
+        "@esbuild/linux-ppc64": "0.27.7",
+        "@esbuild/linux-riscv64": "0.27.7",
+        "@esbuild/linux-s390x": "0.27.7",
+        "@esbuild/linux-x64": "0.27.7",
+        "@esbuild/netbsd-arm64": "0.27.7",
+        "@esbuild/netbsd-x64": "0.27.7",
+        "@esbuild/openbsd-arm64": "0.27.7",
+        "@esbuild/openbsd-x64": "0.27.7",
+        "@esbuild/openharmony-arm64": "0.27.7",
+        "@esbuild/sunos-x64": "0.27.7",
+        "@esbuild/win32-arm64": "0.27.7",
+        "@esbuild/win32-ia32": "0.27.7",
+        "@esbuild/win32-x64": "0.27.7"
+      }
+    },
     "node_modules/tunnel-agent": {
       "version": "0.6.0",
       "resolved": "https://registry.npmjs.org/tunnel-agent/-/tunnel-agent-0.6.0.tgz",

package.json

@@ -1,16 +1,17 @@
 {
   "name": "@cloudcli-ai/cloudcli",
-  "version": "1.28.1",
+  "version": "1.29.3",
   "description": "A web-based UI for Claude Code CLI",
   "type": "module",
-  "main": "server/index.js",
+  "main": "dist-server/server/index.js",
   "bin": {
-    "cloudcli": "server/cli.js"
+    "cloudcli": "dist-server/server/cli.js"
   },
   "files": [
     "server/",
     "shared/",
     "dist/",
+    "dist-server/",
     "scripts/",
     "README.md"
   ],
@@ -23,19 +24,25 @@
     "url": "https://github.com/siteboon/claudecodeui/issues"
   },
   "scripts": {
-    "dev": "concurrently --kill-others \"npm run server\" \"npm run client\"",
+    "dev": "concurrently --kill-others \"npm run server:dev\" \"npm run client\"",
-    "server": "node server/index.js",
+    "server": "node dist-server/server/index.js",
+    "server:dev": "tsx --tsconfig server/tsconfig.json server/index.js",
+    "server:dev-watch": "tsx watch --tsconfig server/tsconfig.json server/index.js",
     "client": "vite",
-    "build": "vite build",
+    "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 })\"",
+    "build:server": "tsc -p server/tsconfig.json && tsc-alias -p server/tsconfig.json",
     "preview": "vite preview",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p server/tsconfig.json",
-    "lint": "eslint src/",
+    "lint": "eslint src/ server/",
-    "lint:fix": "eslint src/ --fix",
+    "lint:fix": "eslint src/ server/ --fix",
     "start": "npm run build && npm run server",
     "release": "./release.sh",
     "prepublishOnly": "npm run build",
     "postinstall": "node scripts/fix-node-pty.js",
-    "prepare": "husky"
+    "prepare": "husky",
+    "update:platform": "./update-platform.sh"
   },
   "keywords": [
     "claude code",
@@ -129,6 +136,8 @@
     "autoprefixer": "^10.4.16",
     "concurrently": "^8.2.2",
     "eslint": "^9.39.3",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-boundaries": "^6.0.2",
     "eslint-plugin-import-x": "^4.16.1",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.0.1",
@@ -143,11 +152,14 @@
     "release-it": "^19.0.5",
     "sharp": "^0.34.2",
     "tailwindcss": "^3.4.0",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.56.1",
     "vite": "^7.0.4"
   },
   "lint-staged": {
-    "src/**/*.{ts,tsx,js,jsx}": "eslint"
+    "src/**/*.{ts,tsx,js,jsx}": "eslint",
+    "server/**/*.{js,ts}": "eslint"
   }
 }

redirect-package/bin.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import('@cloudcli-ai/cloudcli/server/cli.js');
+import('@cloudcli-ai/cloudcli/dist-server/server/cli.js');

server/cli.js

@@ -7,6 +7,7 @@
  * Commands:
  *   (no args)     - Start the server (default)
  *   start         - Start the server
+ *   sandbox       - Manage Docker sandbox environments
  *   status        - Show configuration and data locations
  *   help          - Show help information
  *   version       - Show version information
@@ -15,11 +16,12 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
-import { fileURLToPath } from 'url';
+import { findAppRoot, getModuleDir } from './utils/runtime-paths.js';
-import { dirname } from 'path';
 
-const __filename = fileURLToPath(import.meta.url);
+const __dirname = getModuleDir(import.meta.url);
-const __dirname = dirname(__filename);
+// The CLI is compiled into dist-server/server, but it still needs to read the top-level
+// package.json and .env file. Resolving the app root once keeps those lookups stable.
+const APP_ROOT = findAppRoot(__dirname);
 
 // ANSI color codes for terminal output
 const colors = {
@@ -49,13 +51,16 @@ const c = {
 };
 
 // Load package.json for version info
-const packageJsonPath = path.join(__dirname, '../package.json');
+const packageJsonPath = path.join(APP_ROOT, 'package.json');
 const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+// Match the runtime fallback in load-env.js so "cloudcli status" reports the same default
+// database location that the backend will actually use when no DATABASE_PATH is configured.
+const DEFAULT_DATABASE_PATH = path.join(os.homedir(), '.cloudcli', 'auth.db');
 
 // Load environment variables from .env file if it exists
 function loadEnvFile() {
     try {
-        const envPath = path.join(__dirname, '../.env');
+        const envPath = path.join(APP_ROOT, '.env');
         const envFile = fs.readFileSync(envPath, 'utf8');
         envFile.split('\n').forEach(line => {
             const trimmedLine = line.trim();
@@ -74,12 +79,12 @@ function loadEnvFile() {
 // Get the database path (same logic as db.js)
 function getDatabasePath() {
     loadEnvFile();
-    return process.env.DATABASE_PATH || path.join(__dirname, 'database', 'auth.db');
+    return process.env.DATABASE_PATH || DEFAULT_DATABASE_PATH;
 }
 
 // Get the installation directory
 function getInstallDir() {
-    return path.join(__dirname, '..');
+    return APP_ROOT;
 }
 
 // Show status command
@@ -123,7 +128,7 @@ function showStatus() {
     console.log(`       Status: ${projectsExists ? c.ok('[OK] Exists') : c.warn('[WARN] Not found')}`);
 
     // Config file location
-    const envFilePath = path.join(__dirname, '../.env');
+    const envFilePath = path.join(APP_ROOT, '.env');
     const envExists = fs.existsSync(envFilePath);
     console.log(`\n${c.info('[INFO]')} Configuration File:`);
     console.log(`       ${c.dim(envFilePath)}`);
@@ -150,6 +155,7 @@ Usage:
 
 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
@@ -164,8 +170,7 @@ Options:
 Examples:
   $ cloudcli                        # Start with defaults
   $ cloudcli --port 8080            # Start on port 8080
-  $ cloudcli -p 3000                # Short form for port
+  $ cloudcli sandbox ~/my-project   # Run in a Docker sandbox
-  $ cloudcli start --port 4000      # Explicit start command
   $ cloudcli status                 # Show configuration
 
 Environment Variables:
@@ -244,6 +249,353 @@ async function updatePackage() {
     }
 }
 
+// ── Sandbox command ─────────────────────────────────────────
+
+const SANDBOX_TEMPLATES = {
+    claude: 'docker.io/cloudcliai/sandbox:claude-code',
+    codex: 'docker.io/cloudcliai/sandbox:codex',
+    gemini: 'docker.io/cloudcliai/sandbox:gemini',
+};
+
+const SANDBOX_SECRETS = {
+    claude: 'anthropic',
+    codex: 'openai',
+    gemini: 'google',
+};
+
+function parseSandboxArgs(args) {
+    const result = {
+        subcommand: null,
+        workspace: null,
+        agent: 'claude',
+        name: null,
+        port: 3001,
+        template: null,
+        env: [],
+    };
+
+    const subcommands = ['ls', 'stop', 'start', 'rm', 'logs', 'help'];
+
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+
+        if (i === 0 && subcommands.includes(arg)) {
+            result.subcommand = arg;
+        } else if (arg === '--agent' || arg === '-a') {
+            result.agent = args[++i];
+        } else if (arg === '--name' || arg === '-n') {
+            result.name = args[++i];
+        } else if (arg === '--port') {
+            result.port = parseInt(args[++i], 10);
+        } else if (arg === '--template' || arg === '-t') {
+            result.template = args[++i];
+        } else if (arg === '--env' || arg === '-e') {
+            result.env.push(args[++i]);
+        } else if (!arg.startsWith('-')) {
+            if (!result.subcommand) {
+                result.workspace = arg;
+            } else {
+                result.name = arg; // for stop/start/rm/logs <name>
+            }
+        }
+    }
+
+    // Default subcommand based on what we got
+    if (!result.subcommand) {
+        result.subcommand = 'create';
+    }
+
+    // Derive name from workspace path if not set
+    if (!result.name && result.workspace) {
+        result.name = path.basename(path.resolve(result.workspace.replace(/^~/, os.homedir())));
+    }
+
+    // Default template from agent
+    if (!result.template) {
+        result.template = SANDBOX_TEMPLATES[result.agent] || SANDBOX_TEMPLATES.claude;
+    }
+
+    return result;
+}
+
+function showSandboxHelp() {
+    console.log(`
+${c.bright('CloudCLI Sandbox')} — Run CloudCLI inside Docker Sandboxes
+
+Usage:
+  cloudcli sandbox <workspace>            Create and start a sandbox
+  cloudcli sandbox <subcommand> [name]    Manage sandboxes
+
+Subcommands:
+  ${c.bright('(default)')}    Create a sandbox and start the web UI
+  ${c.bright('ls')}           List all sandboxes
+  ${c.bright('start')}        Restart a stopped sandbox and re-launch the web UI
+  ${c.bright('stop')}         Stop a sandbox (preserves state)
+  ${c.bright('rm')}           Remove a sandbox
+  ${c.bright('logs')}         Show CloudCLI server logs
+  ${c.bright('help')}         Show this help
+
+Options:
+  -a, --agent <agent>       Agent to use: claude, codex, gemini (default: claude)
+  -n, --name <name>         Sandbox name (default: derived from workspace folder)
+  -t, --template <image>    Custom template image
+  -e, --env <KEY=VALUE>     Set environment variable (repeatable)
+      --port <port>         Host port for the web UI (default: 3001)
+
+Examples:
+  $ cloudcli sandbox ~/my-project
+  $ cloudcli sandbox ~/my-project --agent codex --port 8080
+  $ cloudcli sandbox ~/my-project --env SERVER_PORT=8080 --env HOST=0.0.0.0
+  $ cloudcli sandbox ls
+  $ cloudcli sandbox stop my-project
+  $ cloudcli sandbox start my-project
+  $ cloudcli sandbox rm my-project
+
+Prerequisites:
+  1. Install sbx CLI: https://docs.docker.com/ai/sandboxes/get-started/
+  2. Authenticate and store your API key:
+       sbx login
+       sbx secret set -g anthropic   # for Claude
+       sbx secret set -g openai      # for Codex
+       sbx secret set -g google      # for Gemini
+
+Advanced usage:
+  For branch mode, multiple workspaces, memory limits, network policies,
+  or passing prompts to the agent, use sbx directly with the template:
+
+    sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/my-project --branch my-feature
+    sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/project ~/libs:ro --memory 8g
+
+  Full Docker Sandboxes docs: https://docs.docker.com/ai/sandboxes/usage/
+`);
+}
+
+async function sandboxCommand(args) {
+    const { execFileSync, spawn: spawnProcess } = await import('child_process');
+
+    // Safe execution — uses execFileSync (no shell) to prevent injection
+    const sbx = (subcmd, opts = {}) => {
+        const result = execFileSync('sbx', subcmd, {
+            encoding: 'utf8',
+            stdio: opts.inherit ? 'inherit' : 'pipe',
+        });
+        return result || '';
+    };
+
+    const opts = parseSandboxArgs(args);
+
+    if (opts.subcommand === 'help') {
+        showSandboxHelp();
+        return;
+    }
+
+    // Validate name (alphanumeric, hyphens, underscores only)
+    if (opts.name && !/^[\w-]+$/.test(opts.name)) {
+        console.error(`\n${c.error('❌')} Invalid sandbox name: ${opts.name}`);
+        console.log(`   Names may only contain letters, numbers, hyphens, and underscores.\n`);
+        process.exit(1);
+    }
+
+    // Check sbx is installed
+    try {
+        sbx(['version']);
+    } catch {
+        console.error(`\n${c.error('❌')} ${c.bright('sbx')} CLI not found.\n`);
+        console.log(`   Install it from: ${c.info('https://docs.docker.com/ai/sandboxes/get-started/')}`);
+        console.log(`   Then run: ${c.bright('sbx login')}`);
+        console.log(`   And store your API key: ${c.bright('sbx secret set -g anthropic')}\n`);
+        process.exit(1);
+    }
+
+    switch (opts.subcommand) {
+
+        case 'ls':
+            sbx(['ls'], { inherit: true });
+            break;
+
+        case 'stop':
+            if (!opts.name) {
+                console.error(`\n${c.error('❌')} Sandbox name required: cloudcli sandbox stop <name>\n`);
+                process.exit(1);
+            }
+            sbx(['stop', opts.name], { inherit: true });
+            break;
+
+        case 'rm':
+            if (!opts.name) {
+                console.error(`\n${c.error('❌')} Sandbox name required: cloudcli sandbox rm <name>\n`);
+                process.exit(1);
+            }
+            sbx(['rm', opts.name], { inherit: true });
+            break;
+
+        case 'logs':
+            if (!opts.name) {
+                console.error(`\n${c.error('❌')} Sandbox name required: cloudcli sandbox logs <name>\n`);
+                process.exit(1);
+            }
+            try {
+                sbx(['exec', opts.name, 'bash', '-c', 'cat /tmp/cloudcli-ui.log'], { inherit: true });
+            } catch (e) {
+                console.error(`\n${c.error('❌')} Could not read logs: ${e.message || 'Is the sandbox running?'}\n`);
+            }
+            break;
+
+        case 'start': {
+            if (!opts.name) {
+                console.error(`\n${c.error('❌')} Sandbox name required: cloudcli sandbox start <name>\n`);
+                process.exit(1);
+            }
+            console.log(`\n${c.info('▶')} Starting sandbox ${c.bright(opts.name)}...`);
+            const restartRun = spawnProcess('sbx', ['run', opts.name], {
+                detached: true,
+                stdio: ['ignore', 'ignore', 'ignore'],
+            });
+            restartRun.unref();
+            await new Promise(resolve => setTimeout(resolve, 5000));
+
+            console.log(`${c.info('▶')} Launching CloudCLI web server...`);
+            sbx(['exec', opts.name, 'bash', '-c', 'cloudcli start --port 3001 &']);
+
+            console.log(`${c.info('▶')} Forwarding port ${opts.port} → 3001...`);
+            try {
+                sbx(['ports', opts.name, '--publish', `${opts.port}:3001`]);
+            } catch (e) {
+                const msg = e.stdout || e.stderr || e.message || '';
+                if (msg.includes('address already in use')) {
+                    const altPort = opts.port + 1;
+                    console.log(`${c.warn('⚠')}  Port ${opts.port} in use, trying ${altPort}...`);
+                    try {
+                        sbx(['ports', opts.name, '--publish', `${altPort}:3001`]);
+                        opts.port = altPort;
+                    } catch {
+                        console.error(`${c.error('❌')} Ports ${opts.port} and ${altPort} both in use. Use --port to specify a free port.`);
+                        process.exit(1);
+                    }
+                } else {
+                    throw e;
+                }
+            }
+
+            console.log(`\n${c.ok('✔')} ${c.bright('CloudCLI is ready!')}`);
+            console.log(`  ${c.info('→')} ${c.bright(`http://localhost:${opts.port}`)}\n`);
+            break;
+        }
+
+        case 'create': {
+            if (!opts.workspace) {
+                console.error(`\n${c.error('❌')} Workspace path required: cloudcli sandbox <path>\n`);
+                console.log(`   Example: ${c.bright('cloudcli sandbox ~/my-project')}\n`);
+                process.exit(1);
+            }
+
+            const workspace = opts.workspace.startsWith('~')
+                ? opts.workspace.replace(/^~/, os.homedir())
+                : path.resolve(opts.workspace);
+
+            if (!fs.existsSync(workspace)) {
+                console.error(`\n${c.error('❌')} Workspace path not found: ${c.dim(workspace)}\n`);
+                process.exit(1);
+            }
+
+            const secret = SANDBOX_SECRETS[opts.agent] || 'anthropic';
+
+            // Check if the required secret is stored
+            try {
+                const secretList = sbx(['secret', 'ls']);
+                if (!secretList.includes(secret)) {
+                    console.error(`\n${c.error('❌')} No ${c.bright(secret)} API key found.\n`);
+                    console.log(`   Run: ${c.bright(`sbx secret set -g ${secret}`)}\n`);
+                    process.exit(1);
+                }
+            } catch { /* sbx secret ls not available, skip check */ }
+
+            console.log(`\n${c.bright('CloudCLI Sandbox')}`);
+            console.log(c.dim('─'.repeat(50)));
+            console.log(`  Agent:     ${c.info(opts.agent)} ${c.dim(`(${secret} credentials)`)}`);
+            console.log(`  Workspace: ${c.dim(workspace)}`);
+            console.log(`  Name:      ${c.dim(opts.name)}`);
+            console.log(`  Template:  ${c.dim(opts.template)}`);
+            console.log(`  Port:      ${c.dim(String(opts.port))}`);
+            if (opts.env.length > 0) {
+                console.log(`  Env:       ${c.dim(opts.env.join(', '))}`);
+            }
+            console.log(c.dim('─'.repeat(50)));
+
+            // Step 1: Launch sandbox with sbx run in background.
+            // sbx run creates the sandbox (or reconnects) AND holds an active session,
+            // which prevents the sandbox from auto-stopping.
+            console.log(`\n${c.info('▶')} Creating sandbox ${c.bright(opts.name)}...`);
+            const bgRun = spawnProcess('sbx', [
+                'run', '--template', opts.template, '--name', opts.name, opts.agent, workspace,
+            ], {
+                detached: true,
+                stdio: ['ignore', 'ignore', 'ignore'],
+            });
+            bgRun.unref();
+            // Wait for sandbox to be ready
+            await new Promise(resolve => setTimeout(resolve, 5000));
+
+            // Step 2: Inject environment variables
+            if (opts.env.length > 0) {
+                console.log(`${c.info('▶')} Setting environment variables...`);
+                const exports = opts.env
+                    .filter(e => /^\w+=.+$/.test(e))
+                    .map(e => `export ${e}`)
+                    .join('\n');
+                if (exports) {
+                    sbx(['exec', opts.name, 'bash', '-c', `echo '${exports}' >> /etc/sandbox-persistent.sh`]);
+                }
+                const invalid = opts.env.filter(e => !/^\w+=.+$/.test(e));
+                if (invalid.length > 0) {
+                    console.log(`${c.warn('⚠')}  Skipped invalid env vars: ${invalid.join(', ')} (expected KEY=VALUE)`);
+                }
+            }
+
+            // Step 3: Start CloudCLI inside the sandbox
+            console.log(`${c.info('▶')} Launching CloudCLI web server...`);
+            sbx(['exec', opts.name, 'bash', '-c', 'cloudcli start --port 3001 &']);
+
+            // Step 4: Forward port
+            console.log(`${c.info('▶')} Forwarding port ${opts.port} → 3001...`);
+            try {
+                sbx(['ports', opts.name, '--publish', `${opts.port}:3001`]);
+            } catch (e) {
+                const msg = e.stdout || e.stderr || e.message || '';
+                if (msg.includes('address already in use')) {
+                    const altPort = opts.port + 1;
+                    console.log(`${c.warn('⚠')}  Port ${opts.port} in use, trying ${altPort}...`);
+                    try {
+                        sbx(['ports', opts.name, '--publish', `${altPort}:3001`]);
+                        opts.port = altPort;
+                    } catch {
+                        console.error(`${c.error('❌')} Ports ${opts.port} and ${altPort} both in use. Use --port to specify a free port.`);
+                        process.exit(1);
+                    }
+                } else {
+                    throw e;
+                }
+            }
+
+            // Done
+            console.log(`\n${c.ok('✔')} ${c.bright('CloudCLI is ready!')}`);
+            console.log(`  ${c.info('→')} Open ${c.bright(`http://localhost:${opts.port}`)}`);
+            console.log(`\n${c.dim('  Manage with:')}`);
+            console.log(`  ${c.dim('$')} sbx ls`);
+            console.log(`  ${c.dim('$')} sbx stop ${opts.name}`);
+            console.log(`  ${c.dim('$')} sbx start ${opts.name}`);
+            console.log(`  ${c.dim('$')} sbx rm ${opts.name}`);
+            console.log(`\n${c.dim('  Or install globally:')} npm install -g @cloudcli-ai/cloudcli\n`);
+            break;
+        }
+
+        default:
+            showSandboxHelp();
+    }
+}
+
+// ── Server ──────────────────────────────────────────────────
+
 // Start the server
 async function startServer() {
     // Check for updates silently on startup
@@ -274,6 +626,10 @@ function parseArgs(args) {
             parsed.command = 'version';
         } else if (!arg.startsWith('-')) {
             parsed.command = arg;
+            if (arg === 'sandbox') {
+                parsed.remainingArgs = args.slice(i + 1);
+                break;
+            }
         }
     }
 
@@ -283,7 +639,7 @@ function parseArgs(args) {
 // Main CLI handler
 async function main() {
     const args = process.argv.slice(2);
-    const { command, options } = parseArgs(args);
+    const { command, options, remainingArgs } = parseArgs(args);
 
     // Apply CLI options to environment variables
     if (options.serverPort) {
@@ -299,6 +655,9 @@ async function main() {
         case 'start':
             await startServer();
             break;
+        case 'sandbox':
+            await sandboxCommand(remainingArgs || []);
+            break;
         case 'status':
         case 'info':
             showStatus();

server/database/db.js

@@ -2,11 +2,21 @@ import Database from 'better-sqlite3';
 import path from 'path';
 import fs from 'fs';
 import crypto from 'crypto';
-import { fileURLToPath } from 'url';
+import { findAppRoot, getModuleDir } from '../utils/runtime-paths.js';
-import { dirname } from 'path';
+import {
+  APP_CONFIG_TABLE_SQL,
+  USER_NOTIFICATION_PREFERENCES_TABLE_SQL,
+  VAPID_KEYS_TABLE_SQL,
+  PUSH_SUBSCRIPTIONS_TABLE_SQL,
+  SESSION_NAMES_TABLE_SQL,
+  SESSION_NAMES_LOOKUP_INDEX_SQL,
+  DATABASE_SCHEMA_SQL
+} from './schema.js';
 
-const __filename = fileURLToPath(import.meta.url);
+const __dirname = getModuleDir(import.meta.url);
-const __dirname = dirname(__filename);
+// The compiled backend lives under dist-server/server/database, but the install root we log
+// should still point at the project/app root. Resolving it here avoids build-layout drift.
+const APP_ROOT = findAppRoot(__dirname);
 
 // ANSI color codes for terminal output
 const colors = {
@@ -24,7 +34,6 @@ const c = {
 
 // Use DATABASE_PATH environment variable if set, otherwise use default location
 const DB_PATH = process.env.DATABASE_PATH || path.join(__dirname, 'auth.db');
-const INIT_SQL_PATH = path.join(__dirname, 'init.sql');
 
 // Ensure database directory exists if custom path is provided
 if (process.env.DATABASE_PATH) {
@@ -62,14 +71,10 @@ const db = new Database(DB_PATH);
 // app_config must exist before any other module imports (auth.js reads the JWT secret at load time).
 // runMigrations() also creates this table, but it runs too late for existing installations
 // where auth.js is imported before initializeDatabase() is called.
-db.exec(`CREATE TABLE IF NOT EXISTS app_config (
+db.exec(APP_CONFIG_TABLE_SQL);
-  key TEXT PRIMARY KEY,
-  value TEXT NOT NULL,
-  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-)`);
 
 // Show app installation path prominently
-const appInstallPath = path.join(__dirname, '../..');
+const appInstallPath = APP_ROOT;
 console.log('');
 console.log(c.dim('═'.repeat(60)));
 console.log(`${c.info('[INFO]')} App Installation: ${c.bright(appInstallPath)}`);
@@ -100,53 +105,12 @@ const runMigrations = () => {
       db.exec('ALTER TABLE users ADD COLUMN has_completed_onboarding BOOLEAN DEFAULT 0');
     }
 
-    db.exec(`
+    db.exec(USER_NOTIFICATION_PREFERENCES_TABLE_SQL);
-      CREATE TABLE IF NOT EXISTS user_notification_preferences (
+    db.exec(VAPID_KEYS_TABLE_SQL);
-        user_id INTEGER PRIMARY KEY,
+    db.exec(PUSH_SUBSCRIPTIONS_TABLE_SQL);
-        preferences_json TEXT NOT NULL,
+    db.exec(APP_CONFIG_TABLE_SQL);
-        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    db.exec(SESSION_NAMES_TABLE_SQL);
-        FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+    db.exec(SESSION_NAMES_LOOKUP_INDEX_SQL);
-      )
-    `);
-
-    db.exec(`
-      CREATE TABLE IF NOT EXISTS vapid_keys (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        public_key TEXT NOT NULL,
-        private_key TEXT NOT NULL,
-        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-      )
-    `);
-
-    db.exec(`
-      CREATE TABLE IF NOT EXISTS push_subscriptions (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        user_id INTEGER NOT NULL,
-        endpoint TEXT NOT NULL UNIQUE,
-        keys_p256dh TEXT NOT NULL,
-        keys_auth TEXT NOT NULL,
-        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-        FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-      )
-    `);
-    // Create app_config table if it doesn't exist (for existing installations)
-    db.exec(`CREATE TABLE IF NOT EXISTS app_config (
-      key TEXT PRIMARY KEY,
-      value TEXT NOT NULL,
-      created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-    )`);
-
-    // Create session_names table if it doesn't exist (for existing installations)
-    db.exec(`CREATE TABLE IF NOT EXISTS session_names (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      session_id TEXT NOT NULL,
-      provider TEXT NOT NULL DEFAULT 'claude',
-      custom_name TEXT NOT NULL,
-      created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-      updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-      UNIQUE(session_id, provider)
-    )`);
-    db.exec('CREATE INDEX IF NOT EXISTS idx_session_names_lookup ON session_names(session_id, provider)');
 
     console.log('Database migrations completed successfully');
   } catch (error) {
@@ -158,8 +122,7 @@ const runMigrations = () => {
 // Initialize database with schema
 const initializeDatabase = async () => {
   try {
-    const initSQL = fs.readFileSync(INIT_SQL_PATH, 'utf8');
+    db.exec(DATABASE_SCHEMA_SQL);
-    db.exec(initSQL);
     console.log('Database initialized successfully');
     runMigrations();
   } catch (error) {

server/database/init.sql

@@ -1,99 +0,0 @@
--- Initialize authentication database
-PRAGMA foreign_keys = ON;
-
--- Users table (single user system)
-CREATE TABLE IF NOT EXISTS users (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    username TEXT UNIQUE NOT NULL,
-    password_hash TEXT NOT NULL,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-    last_login DATETIME,
-    is_active BOOLEAN DEFAULT 1,
-    git_name TEXT,
-    git_email TEXT,
-    has_completed_onboarding BOOLEAN DEFAULT 0
-);
-
--- Indexes for performance
-CREATE INDEX IF NOT EXISTS idx_users_username ON users(username);
-CREATE INDEX IF NOT EXISTS idx_users_active ON users(is_active);
-
--- API Keys table for external API access
-CREATE TABLE IF NOT EXISTS api_keys (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    user_id INTEGER NOT NULL,
-    key_name TEXT NOT NULL,
-    api_key TEXT UNIQUE NOT NULL,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-    last_used DATETIME,
-    is_active BOOLEAN DEFAULT 1,
-    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-);
-
-CREATE INDEX IF NOT EXISTS idx_api_keys_key ON api_keys(api_key);
-CREATE INDEX IF NOT EXISTS idx_api_keys_user_id ON api_keys(user_id);
-CREATE INDEX IF NOT EXISTS idx_api_keys_active ON api_keys(is_active);
-
--- User credentials table for storing various tokens/credentials (GitHub, GitLab, etc.)
-CREATE TABLE IF NOT EXISTS user_credentials (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    user_id INTEGER NOT NULL,
-    credential_name TEXT NOT NULL,
-    credential_type TEXT NOT NULL, -- 'github_token', 'gitlab_token', 'bitbucket_token', etc.
-    credential_value TEXT NOT NULL,
-    description TEXT,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-    is_active BOOLEAN DEFAULT 1,
-    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-);
-
-CREATE INDEX IF NOT EXISTS idx_user_credentials_user_id ON user_credentials(user_id);
-CREATE INDEX IF NOT EXISTS idx_user_credentials_type ON user_credentials(credential_type);
-CREATE INDEX IF NOT EXISTS idx_user_credentials_active ON user_credentials(is_active);
-
--- User notification preferences (backend-owned, provider-agnostic)
-CREATE TABLE IF NOT EXISTS user_notification_preferences (
-    user_id INTEGER PRIMARY KEY,
-    preferences_json TEXT NOT NULL,
-    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-);
-
--- VAPID key pair for Web Push notifications
-CREATE TABLE IF NOT EXISTS vapid_keys (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    public_key TEXT NOT NULL,
-    private_key TEXT NOT NULL,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);
-
--- Browser push subscriptions
-CREATE TABLE IF NOT EXISTS push_subscriptions (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    user_id INTEGER NOT NULL,
-    endpoint TEXT NOT NULL UNIQUE,
-    keys_p256dh TEXT NOT NULL,
-    keys_auth TEXT NOT NULL,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-);
-
--- Session custom names (provider-agnostic display name overrides)
-CREATE TABLE IF NOT EXISTS session_names (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    session_id TEXT NOT NULL,
-    provider TEXT NOT NULL DEFAULT 'claude',
-    custom_name TEXT NOT NULL,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-    UNIQUE(session_id, provider)
-);
-
-CREATE INDEX IF NOT EXISTS idx_session_names_lookup ON session_names(session_id, provider);
-
--- App configuration table (auto-generated secrets, settings, etc.)
-CREATE TABLE IF NOT EXISTS app_config (
-    key TEXT PRIMARY KEY,
-    value TEXT NOT NULL,
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);

server/database/schema.js

@@ -0,0 +1,102 @@
+export const APP_CONFIG_TABLE_SQL = `CREATE TABLE IF NOT EXISTS app_config (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);`;
+
+export const USER_NOTIFICATION_PREFERENCES_TABLE_SQL = `CREATE TABLE IF NOT EXISTS user_notification_preferences (
+  user_id INTEGER PRIMARY KEY,
+  preferences_json TEXT NOT NULL,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);`;
+
+export const VAPID_KEYS_TABLE_SQL = `CREATE TABLE IF NOT EXISTS vapid_keys (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  public_key TEXT NOT NULL,
+  private_key TEXT NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);`;
+
+export const PUSH_SUBSCRIPTIONS_TABLE_SQL = `CREATE TABLE IF NOT EXISTS push_subscriptions (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL,
+  endpoint TEXT NOT NULL UNIQUE,
+  keys_p256dh TEXT NOT NULL,
+  keys_auth TEXT NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);`;
+
+export const SESSION_NAMES_TABLE_SQL = `CREATE TABLE IF NOT EXISTS session_names (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id TEXT NOT NULL,
+  provider TEXT NOT NULL DEFAULT 'claude',
+  custom_name TEXT NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(session_id, provider)
+);`;
+
+export const SESSION_NAMES_LOOKUP_INDEX_SQL = `CREATE INDEX IF NOT EXISTS idx_session_names_lookup ON session_names(session_id, provider);`;
+
+export const DATABASE_SCHEMA_SQL = `PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  username TEXT UNIQUE NOT NULL,
+  password_hash TEXT NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  last_login DATETIME,
+  is_active BOOLEAN DEFAULT 1,
+  git_name TEXT,
+  git_email TEXT,
+  has_completed_onboarding BOOLEAN DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_users_username ON users(username);
+CREATE INDEX IF NOT EXISTS idx_users_active ON users(is_active);
+
+CREATE TABLE IF NOT EXISTS api_keys (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL,
+  key_name TEXT NOT NULL,
+  api_key TEXT UNIQUE NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  last_used DATETIME,
+  is_active BOOLEAN DEFAULT 1,
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_api_keys_key ON api_keys(api_key);
+CREATE INDEX IF NOT EXISTS idx_api_keys_user_id ON api_keys(user_id);
+CREATE INDEX IF NOT EXISTS idx_api_keys_active ON api_keys(is_active);
+
+CREATE TABLE IF NOT EXISTS user_credentials (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL,
+  credential_name TEXT NOT NULL,
+  credential_type TEXT NOT NULL,
+  credential_value TEXT NOT NULL,
+  description TEXT,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  is_active BOOLEAN DEFAULT 1,
+  FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_user_credentials_user_id ON user_credentials(user_id);
+CREATE INDEX IF NOT EXISTS idx_user_credentials_type ON user_credentials(credential_type);
+CREATE INDEX IF NOT EXISTS idx_user_credentials_active ON user_credentials(is_active);
+
+${USER_NOTIFICATION_PREFERENCES_TABLE_SQL}
+
+${VAPID_KEYS_TABLE_SQL}
+
+${PUSH_SUBSCRIPTIONS_TABLE_SQL}
+
+${SESSION_NAMES_TABLE_SQL}
+
+${SESSION_NAMES_LOOKUP_INDEX_SQL}
+
+${APP_CONFIG_TABLE_SQL}
+`;

server/index.js

@@ -3,13 +3,13 @@
 import './load-env.js';
 import fs from 'fs';
 import path from 'path';
-import { fileURLToPath } from 'url';
+import { findAppRoot, getModuleDir } from './utils/runtime-paths.js';
-import { dirname } from 'path';
 
-const __filename = fileURLToPath(import.meta.url);
+const __dirname = getModuleDir(import.meta.url);
-const __dirname = dirname(__filename);
+// The server source runs from /server, while the compiled output runs from /dist-server/server.
-
+// Resolving the app root once keeps every repo-level lookup below aligned across both layouts.
-const installMode = fs.existsSync(path.join(__dirname, '..', '.git')) ? 'git' : 'npm';
+const APP_ROOT = findAppRoot(__dirname);
+const installMode = fs.existsSync(path.join(APP_ROOT, '.git')) ? 'git' : 'npm';
 
 // ANSI color codes for terminal output
 const colors = {
@@ -405,11 +405,11 @@ app.use('/api/sessions', authenticateToken, messagesRoutes);
 app.use('/api/agent', agentRoutes);
 
 // Serve public files (like api-docs.html)
-app.use(express.static(path.join(__dirname, '../public')));
+app.use(express.static(path.join(APP_ROOT, 'public')));
 
 // Static files served after API routes
 // Add cache control: HTML files should not be cached, but assets can be cached
-app.use(express.static(path.join(__dirname, '../dist'), {
+app.use(express.static(path.join(APP_ROOT, 'dist'), {
     setHeaders: (res, filePath) => {
         if (filePath.endsWith('.html')) {
             // Prevent HTML caching to avoid service worker issues after builds
@@ -431,17 +431,24 @@ app.use(express.static(path.join(__dirname, '../dist'), {
 app.post('/api/system/update', authenticateToken, async (req, res) => {
     try {
         // Get the project root directory (parent of server directory)
-        const projectRoot = path.join(__dirname, '..');
+        const projectRoot = APP_ROOT;
 
         console.log('Starting system update from directory:', projectRoot);
 
-        // Run the update command based on install mode
+        // Platform deployments use their own update workflow from the project root.
-        const updateCommand = installMode === 'git'
+        const updateCommand = IS_PLATFORM
-            ? 'git checkout main && git pull && npm install'
+        // In platform, husky and dev dependencies are not needed
-            : 'npm install -g @cloudcli-ai/cloudcli@latest';
+            ? 'npm run update:platform'
+            : installMode === 'git'
+                ? 'git checkout main && git pull && npm install'
+                : 'npm install -g @cloudcli-ai/cloudcli@latest';
+
+        const updateCwd = IS_PLATFORM || installMode === 'git'
+            ? projectRoot
+            : os.homedir();
 
         const child = spawn('sh', ['-c', updateCommand], {
-            cwd: installMode === 'git' ? projectRoot : os.homedir(),
+            cwd: updateCwd,
             env: process.env
         });
 
@@ -2266,7 +2273,7 @@ app.get('*', (req, res) => {
 
     // Only serve index.html for HTML routes, not for static assets
     // Static assets should already be handled by express.static middleware above
-    const indexPath = path.join(__dirname, '../dist/index.html');
+    const indexPath = path.join(APP_ROOT, 'dist', 'index.html');
 
     // Check if dist/index.html exists (production build available)
     if (fs.existsSync(indexPath)) {
@@ -2381,7 +2388,7 @@ async function startServer() {
         configureWebPush();
 
         // Check if running in production mode (dist folder exists)
-        const distIndexPath = path.join(__dirname, '../dist/index.html');
+        const distIndexPath = path.join(APP_ROOT, 'dist', 'index.html');
         const isProduction = fs.existsSync(distIndexPath);
 
         // Log Claude implementation mode
@@ -2395,7 +2402,7 @@ async function startServer() {
         console.log(`${c.info('[INFO]')} To run in development mode with hot-module replacement, go to http://${DISPLAY_HOST}:${VITE_PORT}`);
    
         server.listen(SERVER_PORT, HOST, async () => {
-            const appInstallPath = path.join(__dirname, '..');
+            const appInstallPath = APP_ROOT;
 
             console.log('');
             console.log(c.dim('═'.repeat(63)));

server/load-env.js

@@ -2,14 +2,15 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import { fileURLToPath } from 'url';
+import { findAppRoot, getModuleDir } from './utils/runtime-paths.js';
-import { dirname } from 'path';
 
-const __filename = fileURLToPath(import.meta.url);
+const __dirname = getModuleDir(import.meta.url);
-const __dirname = dirname(__filename);
+// Resolve the repo/app root via the nearest /server folder so this file keeps finding the
+// same top-level .env file from both /server/load-env.js and /dist-server/server/load-env.js.
+const APP_ROOT = findAppRoot(__dirname);
 
 try {
-  const envPath = path.join(__dirname, '../.env');
+  const envPath = path.join(APP_ROOT, '.env');
   const envFile = fs.readFileSync(envPath, 'utf8');
   envFile.split('\n').forEach(line => {
     const trimmedLine = line.trim();
@@ -24,6 +25,10 @@ try {
   console.log('No .env file found or error reading it:', e.message);
 }
 
+// Keep the default database in a stable user-level location so rebuilding dist-server
+// never changes where the backend stores auth.db when DATABASE_PATH is not set explicitly.
+const DEFAULT_DATABASE_PATH = path.join(os.homedir(), '.cloudcli', 'auth.db');
+
 if (!process.env.DATABASE_PATH) {
-  process.env.DATABASE_PATH = path.join(os.homedir(), '.cloudcli', 'auth.db');
+  process.env.DATABASE_PATH = DEFAULT_DATABASE_PATH;
 }

server/routes/commands.js

@@ -1,13 +1,15 @@
 import express from 'express';
 import { promises as fs } from 'fs';
 import path from 'path';
-import { fileURLToPath } from 'url';
 import os from 'os';
 import { CLAUDE_MODELS, CURSOR_MODELS, CODEX_MODELS } from '../../shared/modelConstants.js';
 import { parseFrontmatter } from '../utils/frontmatter.js';
+import { findAppRoot, getModuleDir } from '../utils/runtime-paths.js';
 
-const __filename = fileURLToPath(import.meta.url);
+const __dirname = getModuleDir(import.meta.url);
-const __dirname = path.dirname(__filename);
+// This route reads the top-level package.json for the status command, so it needs the real
+// app root even after compilation moves the route file under dist-server/server/routes.
+const APP_ROOT = findAppRoot(__dirname);
 
 const router = express.Router();
 
@@ -291,7 +293,7 @@ Custom commands can be created in:
 
   '/status': async (args, context) => {
     // Read version from package.json
-    const packageJsonPath = path.join(path.dirname(__dirname), '..', 'package.json');
+    const packageJsonPath = path.join(APP_ROOT, 'package.json');
     let version = 'unknown';
     let packageName = 'claude-code-ui';
 

server/routes/cursor.js

@@ -2,7 +2,6 @@ import express from 'express';
 import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
-import { spawn } from 'child_process';
 import sqlite3 from 'sqlite3';
 import { open } from 'sqlite';
 import crypto from 'crypto';
@@ -578,221 +577,4 @@ router.get('/sessions', async (req, res) => {
     });
   }
 });
-
-// GET /api/cursor/sessions/:sessionId - Get specific Cursor session from SQLite
-router.get('/sessions/:sessionId', async (req, res) => {
-  try {
-    const { sessionId } = req.params;
-    const { projectPath } = req.query;
-    
-    // Calculate cwdID hash for the project path
-    const cwdId = crypto.createHash('md5').update(projectPath || process.cwd()).digest('hex');
-    const storeDbPath = path.join(os.homedir(), '.cursor', 'chats', cwdId, sessionId, 'store.db');
-    
-    
-    // Open SQLite database
-    const db = await open({
-      filename: storeDbPath,
-      driver: sqlite3.Database,
-      mode: sqlite3.OPEN_READONLY
-    });
-    
-    // Get all blobs to build the DAG structure
-    const allBlobs = await db.all(`
-      SELECT rowid, id, data FROM blobs
-    `);
-    
-    // Build the DAG structure from parent-child relationships
-    const blobMap = new Map(); // id -> blob data
-    const parentRefs = new Map(); // blob id -> [parent blob ids]
-    const childRefs = new Map(); // blob id -> [child blob ids]
-    const jsonBlobs = []; // Clean JSON messages
-    
-    for (const blob of allBlobs) {
-      blobMap.set(blob.id, blob);
-      
-      // Check if this is a JSON blob (actual message) or protobuf (DAG structure)
-      if (blob.data && blob.data[0] === 0x7B) { // Starts with '{' - JSON blob
-        try {
-          const parsed = JSON.parse(blob.data.toString('utf8'));
-          jsonBlobs.push({ ...blob, parsed });
-        } catch (e) {
-          console.log('Failed to parse JSON blob:', blob.rowid);
-        }
-      } else if (blob.data) { // Protobuf blob - extract parent references
-        const parents = [];
-        let i = 0;
-        
-        // Scan for parent references (0x0A 0x20 followed by 32-byte hash)
-        while (i < blob.data.length - 33) {
-          if (blob.data[i] === 0x0A && blob.data[i+1] === 0x20) {
-            const parentHash = blob.data.slice(i+2, i+34).toString('hex');
-            if (blobMap.has(parentHash)) {
-              parents.push(parentHash);
-            }
-            i += 34;
-          } else {
-            i++;
-          }
-        }
-        
-        if (parents.length > 0) {
-          parentRefs.set(blob.id, parents);
-          // Update child references
-          for (const parentId of parents) {
-            if (!childRefs.has(parentId)) {
-              childRefs.set(parentId, []);
-            }
-            childRefs.get(parentId).push(blob.id);
-          }
-        }
-      }
-    }
-    
-    // Perform topological sort to get chronological order
-    const visited = new Set();
-    const sorted = [];
-    
-    // DFS-based topological sort
-    function visit(nodeId) {
-      if (visited.has(nodeId)) return;
-      visited.add(nodeId);
-      
-      // Visit all parents first (dependencies)
-      const parents = parentRefs.get(nodeId) || [];
-      for (const parentId of parents) {
-        visit(parentId);
-      }
-      
-      // Add this node after all its parents
-      const blob = blobMap.get(nodeId);
-      if (blob) {
-        sorted.push(blob);
-      }
-    }
-    
-    // Start with nodes that have no parents (roots)
-    for (const blob of allBlobs) {
-      if (!parentRefs.has(blob.id)) {
-        visit(blob.id);
-      }
-    }
-    
-    // Visit any remaining nodes (disconnected components)
-    for (const blob of allBlobs) {
-      visit(blob.id);
-    }
-    
-    // Now extract JSON messages in the order they appear in the sorted DAG
-    const messageOrder = new Map(); // JSON blob id -> order index
-    let orderIndex = 0;
-    
-    for (const blob of sorted) {
-      // Check if this blob references any JSON messages
-      if (blob.data && blob.data[0] !== 0x7B) { // Protobuf blob
-        // Look for JSON blob references
-        for (const jsonBlob of jsonBlobs) {
-          try {
-            const jsonIdBytes = Buffer.from(jsonBlob.id, 'hex');
-            if (blob.data.includes(jsonIdBytes)) {
-              if (!messageOrder.has(jsonBlob.id)) {
-                messageOrder.set(jsonBlob.id, orderIndex++);
-              }
-            }
-          } catch (e) {
-            // Skip if can't convert ID
-          }
-        }
-      }
-    }
-    
-    // Sort JSON blobs by their appearance order in the DAG
-    const sortedJsonBlobs = jsonBlobs.sort((a, b) => {
-      const orderA = messageOrder.get(a.id) ?? Number.MAX_SAFE_INTEGER;
-      const orderB = messageOrder.get(b.id) ?? Number.MAX_SAFE_INTEGER;
-      if (orderA !== orderB) return orderA - orderB;
-      // Fallback to rowid if not in order map
-      return a.rowid - b.rowid;
-    });
-    
-    // Use sorted JSON blobs
-    const blobs = sortedJsonBlobs.map((blob, idx) => ({
-      ...blob,
-      sequence_num: idx + 1,
-      original_rowid: blob.rowid
-    }));
-    
-    // Get metadata from meta table
-    const metaRows = await db.all(`
-      SELECT key, value FROM meta
-    `);
-    
-    // Parse metadata
-    let metadata = {};
-    for (const row of metaRows) {
-      if (row.value) {
-        try {
-          // Try to decode as hex-encoded JSON
-          const hexMatch = row.value.toString().match(/^[0-9a-fA-F]+$/);
-          if (hexMatch) {
-            const jsonStr = Buffer.from(row.value, 'hex').toString('utf8');
-            metadata[row.key] = JSON.parse(jsonStr);
-          } else {
-            metadata[row.key] = row.value.toString();
-          }
-        } catch (e) {
-          metadata[row.key] = row.value.toString();
-        }
-      }
-    }
-    
-    // Extract messages from sorted JSON blobs
-    const messages = [];
-    for (const blob of blobs) {
-      try {
-        // We already parsed JSON blobs earlier
-        const parsed = blob.parsed;
-        
-        if (parsed) {
-          // Filter out ONLY system messages at the server level
-          // Check both direct role and nested message.role
-          const role = parsed?.role || parsed?.message?.role;
-          if (role === 'system') {
-            continue; // Skip only system messages
-          }
-          messages.push({ 
-            id: blob.id, 
-            sequence: blob.sequence_num,
-            rowid: blob.original_rowid, 
-            content: parsed 
-          });
-        }
-      } catch (e) {
-        // Skip blobs that cause errors
-        console.log(`Skipping blob ${blob.id}: ${e.message}`);
-      }
-    }
-    
-    await db.close();
-    
-    res.json({ 
-      success: true, 
-      session: {
-        id: sessionId,
-        projectPath: projectPath,
-        messages: messages,
-        metadata: metadata,
-        cwdId: cwdId
-      }
-    });
-    
-  } catch (error) {
-    console.error('Error reading Cursor session:', error);
-    res.status(500).json({ 
-      error: 'Failed to read Cursor session', 
-      details: error.message 
-    });
-  }
-});
-
 export default router;

server/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "baseUrl": ".",
+    "paths": {
+      // In the backend config, "@" maps to the /server directory itself.
+      "@/*": ["*"]
+    },
+    // The backend is still mostly JavaScript today, so allowJs lets us add a real
+    // TypeScript build without forcing a large rename before the tooling is usable.
+    "allowJs": true,
+    // Keep the migration incremental: existing JS keeps building, while any new TS files
+    // still go through the normal TypeScript pipeline and strict checks.
+    "checkJs": false,
+    "strict": true,
+    "noEmitOnError": true,
+    // The backend build emits both /server and /shared into dist-server, so rootDir must
+    // stay one level above this file even though the config itself now lives in /server.
+    "rootDir": "..",
+    "outDir": "../dist-server",
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["./**/*.js", "./**/*.ts", "../shared/**/*.js", "../shared/**/*.ts"],
+  "exclude": ["../dist", "../dist-server", "../node_modules", "../src"]
+}

server/utils/runtime-paths.js

@@ -0,0 +1,37 @@
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+export function getModuleDir(importMetaUrl) {
+  return path.dirname(fileURLToPath(importMetaUrl));
+}
+
+export function findServerRoot(startDir) {
+  // Source files live under /server, while compiled files live under /dist-server/server.
+  // Walking up to the nearest "server" folder gives every backend module one stable anchor
+  // that works in both layouts instead of relying on fragile "../.." assumptions.
+  let currentDir = startDir;
+
+  while (path.basename(currentDir) !== 'server') {
+    const parentDir = path.dirname(currentDir);
+
+    if (parentDir === currentDir) {
+      throw new Error(`Could not resolve the backend server root from "${startDir}".`);
+    }
+
+    currentDir = parentDir;
+  }
+
+  return currentDir;
+}
+
+export function findAppRoot(startDir) {
+  const serverRoot = findServerRoot(startDir);
+  const parentOfServerRoot = path.dirname(serverRoot);
+
+  // Source files live at <app>/server, while compiled files live at <app>/dist-server/server.
+  // When the nearest server folder sits inside dist-server we need to hop one extra level up
+  // so repo-level files still resolve from the real app root instead of the build directory.
+  return path.basename(parentOfServerRoot) === 'dist-server'
+    ? path.dirname(parentOfServerRoot)
+    : parentOfServerRoot;
+}

shared/modelConstants.js

@@ -18,9 +18,10 @@ export const CLAUDE_MODELS = {
     { value: "haiku", label: "Haiku" },
     { value: "opusplan", label: "Opus Plan" },
     { value: "sonnet[1m]", label: "Sonnet [1M]" },
+    { value: "opus[1m]", label: "Opus [1M]" },
   ],
 
-  DEFAULT: "sonnet",
+  DEFAULT: "opus",
 };
 
 /**
@@ -58,6 +59,7 @@ export const CURSOR_MODELS = {
 export const CODEX_MODELS = {
   OPTIONS: [
     { value: "gpt-5.4", label: "GPT-5.4" },
+    { value: "gpt-5.4-mini", label: "GPT-5.4 mini" },
     { value: "gpt-5.3-codex", label: "GPT-5.3 Codex" },
     { value: "gpt-5.2-codex", label: "GPT-5.2 Codex" },
     { value: "gpt-5.2", label: "GPT-5.2" },
@@ -88,5 +90,5 @@ export const GEMINI_MODELS = {
     },
   ],
 
-  DEFAULT: "gemini-2.5-flash",
+  DEFAULT: "gemini-3.1-pro-preview",
 };

src/components/chat/hooks/useChatComposerState.ts

@@ -19,7 +19,7 @@ import type {
   PendingPermissionRequest,
   PermissionMode,
 } from '../types/types';
-import type { Project, ProjectSession, SessionProvider } from '../../../types/app';
+import type { Project, ProjectSession, LLMProvider } from '../../../types/app';
 import { escapeRegExp } from '../utils/chatFormatting';
 import { useFileMentions } from './useFileMentions';
 import { type SlashCommand, useSlashCommands } from './useSlashCommands';
@@ -33,7 +33,7 @@ interface UseChatComposerStateArgs {
   selectedProject: Project | null;
   selectedSession: ProjectSession | null;
   currentSessionId: string | null;
-  provider: SessionProvider;
+  provider: LLMProvider;
   permissionMode: PermissionMode | string;
   cyclePermissionMode: () => void;
   cursorModel: string;

src/components/chat/hooks/useChatProviderState.ts

@@ -2,7 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { authenticatedFetch } from '../../../utils/api';
 import { CLAUDE_MODELS, CODEX_MODELS, CURSOR_MODELS, GEMINI_MODELS } from '../../../../shared/modelConstants';
 import type { PendingPermissionRequest, PermissionMode } from '../types/types';
-import type { ProjectSession, SessionProvider } from '../../../types/app';
+import type { ProjectSession, LLMProvider } from '../../../types/app';
 
 interface UseChatProviderStateArgs {
   selectedSession: ProjectSession | null;
@@ -11,8 +11,8 @@ interface UseChatProviderStateArgs {
 export function useChatProviderState({ selectedSession }: UseChatProviderStateArgs) {
   const [permissionMode, setPermissionMode] = useState<PermissionMode>('default');
   const [pendingPermissionRequests, setPendingPermissionRequests] = useState<PendingPermissionRequest[]>([]);
-  const [provider, setProvider] = useState<SessionProvider>(() => {
+  const [provider, setProvider] = useState<LLMProvider>(() => {
-    return (localStorage.getItem('selected-provider') as SessionProvider) || 'claude';
+    return (localStorage.getItem('selected-provider') as LLMProvider) || 'claude';
   });
   const [cursorModel, setCursorModel] = useState<string>(() => {
     return localStorage.getItem('cursor-model') || CURSOR_MODELS.DEFAULT;

src/components/chat/hooks/useChatRealtimeHandlers.ts

@@ -1,7 +1,7 @@
 import { useEffect, useRef } from 'react';
 import type { Dispatch, MutableRefObject, SetStateAction } from 'react';
 import type { PendingPermissionRequest } from '../types/types';
-import type { Project, ProjectSession, SessionProvider } from '../../../types/app';
+import type { Project, ProjectSession, LLMProvider } from '../../../types/app';
 import type { SessionStore, NormalizedMessage } from '../../../stores/useSessionStore';
 
 type PendingViewSession = {
@@ -48,7 +48,7 @@ type LatestChatMessage = {
 
 interface UseChatRealtimeHandlersArgs {
   latestMessage: LatestChatMessage | null;
-  provider: SessionProvider;
+  provider: LLMProvider;
   selectedProject: Project | null;
   selectedSession: ProjectSession | null;
   currentSessionId: string | null;

src/components/chat/hooks/useChatSessionState.ts

@@ -2,7 +2,7 @@ import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } fr
 import type { MutableRefObject } from 'react';
 import { authenticatedFetch } from '../../../utils/api';
 import type { ChatMessage, Provider } from '../types/types';
-import type { Project, ProjectSession, SessionProvider } from '../../../types/app';
+import type { Project, ProjectSession, LLMProvider } from '../../../types/app';
 import { createCachedDiffCalculator, type DiffCalculator } from '../utils/messageTransforms';
 import { normalizedToChatMessages } from './useChatMessages';
 import type { SessionStore, NormalizedMessage } from '../../../stores/useSessionStore';
@@ -40,7 +40,7 @@ interface ScrollRestoreState {
 function chatMessageToNormalized(
   msg: ChatMessage,
   sessionId: string,
-  provider: SessionProvider,
+  provider: LLMProvider,
 ): NormalizedMessage | null {
   const id = `local_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
   const ts = msg.timestamp instanceof Date
@@ -151,7 +151,7 @@ export function useChatSessionState({
   // When a real session ID arrives and we have a pending user message, flush it to the store
   const prevActiveSessionRef = useRef<string | null>(null);
   if (activeSessionId && activeSessionId !== prevActiveSessionRef.current && pendingUserMessage) {
-    const prov = (localStorage.getItem('selected-provider') as SessionProvider) || 'claude';
+    const prov = (localStorage.getItem('selected-provider') as LLMProvider) || 'claude';
     const normalized = chatMessageToNormalized(pendingUserMessage, activeSessionId, prov);
     if (normalized) {
       sessionStore.appendRealtime(activeSessionId, normalized);
@@ -189,7 +189,7 @@ export function useChatSessionState({
       setPendingUserMessage(msg);
       return;
     }
-    const prov = (localStorage.getItem('selected-provider') as SessionProvider) || 'claude';
+    const prov = (localStorage.getItem('selected-provider') as LLMProvider) || 'claude';
     const normalized = chatMessageToNormalized(msg, activeSessionId, prov);
     if (normalized) {
       sessionStore.appendRealtime(activeSessionId, normalized);
@@ -240,7 +240,7 @@ export function useChatSessionState({
 
       try {
         const slot = await sessionStore.fetchMore(selectedSession.id, {
-          provider: sessionProvider as SessionProvider,
+          provider: sessionProvider as LLMProvider,
           projectName: selectedProject.name,
           projectPath: selectedProject.fullPath || selectedProject.path || '',
           limit: MESSAGES_PER_PAGE,
@@ -374,7 +374,7 @@ export function useChatSessionState({
     // Fetch from server → store updates → chatMessages re-derives automatically
     setIsLoadingSessionMessages(true);
     sessionStore.fetchFromServer(selectedSession.id, {
-      provider: (selectedSession.__provider || provider) as SessionProvider,
+      provider: (selectedSession.__provider || provider) as LLMProvider,
       projectName: selectedProject.name,
       projectPath: selectedProject.fullPath || selectedProject.path || '',
       limit: MESSAGES_PER_PAGE,
@@ -410,7 +410,7 @@ export function useChatSessionState({
         // Skip store refresh during active streaming
         if (!isLoading) {
           await sessionStore.refreshFromServer(selectedSession.id, {
-            provider: (selectedSession.__provider || provider) as SessionProvider,
+            provider: (selectedSession.__provider || provider) as LLMProvider,
             projectName: selectedProject.name,
             projectPath: selectedProject.fullPath || selectedProject.path || '',
           });
@@ -468,7 +468,7 @@ export function useChatSessionState({
           try {
             // Load all messages into the store for search navigation
             const slot = await sessionStore.fetchFromServer(selectedSession.id, {
-              provider: sessionProvider as SessionProvider,
+              provider: sessionProvider as LLMProvider,
               projectName: selectedProject.name,
               projectPath: selectedProject.fullPath || selectedProject.path || '',
               limit: null,
@@ -655,7 +655,7 @@ export function useChatSessionState({
 
     try {
       const slot = await sessionStore.fetchFromServer(requestSessionId, {
-        provider: sessionProvider as SessionProvider,
+        provider: sessionProvider as LLMProvider,
         projectName: selectedProject.name,
         projectPath: selectedProject.fullPath || selectedProject.path || '',
         limit: null,

src/components/chat/types/types.ts

@@ -1,6 +1,6 @@
-import type { Project, ProjectSession, SessionProvider } from '../../../types/app';
+import type { Project, ProjectSession, LLMProvider } from '../../../types/app';
 
-export type Provider = SessionProvider;
+export type Provider = LLMProvider;
 
 export type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan';
 

src/components/chat/view/ChatInterface.tsx

@@ -3,7 +3,7 @@ import { useTranslation } from 'react-i18next';
 import { useTasksSettings } from '../../../contexts/TasksSettingsContext';
 import { QuickSettingsPanel } from '../../quick-settings-panel';
 import type { ChatInterfaceProps, Provider  } from '../types/types';
-import type { SessionProvider } from '../../../types/app';
+import type { LLMProvider } from '../../../types/app';
 import { useChatProviderState } from '../hooks/useChatProviderState';
 import { useChatSessionState } from '../hooks/useChatSessionState';
 import { useChatRealtimeHandlers } from '../hooks/useChatRealtimeHandlers';
@@ -206,9 +206,9 @@ function ChatInterface({
   // so missed streaming events are shown. Also reset isLoading.
   const handleWebSocketReconnect = useCallback(async () => {
     if (!selectedProject || !selectedSession) return;
-    const providerVal = (localStorage.getItem('selected-provider') as SessionProvider) || 'claude';
+    const providerVal = (localStorage.getItem('selected-provider') as LLMProvider) || 'claude';
     await sessionStore.refreshFromServer(selectedSession.id, {
-      provider: (selectedSession.__provider || providerVal) as SessionProvider,
+      provider: (selectedSession.__provider || providerVal) as LLMProvider,
       projectName: selectedProject.name,
       projectPath: selectedProject.fullPath || selectedProject.path || '',
     });

src/components/chat/view/subcomponents/ChatMessagesPane.tsx

@@ -2,7 +2,7 @@ import { useTranslation } from 'react-i18next';
 import { useCallback, useRef } from 'react';
 import type { Dispatch, RefObject, SetStateAction } from 'react';
 import type { ChatMessage } from '../../types/types';
-import type { Project, ProjectSession, SessionProvider } from '../../../../types/app';
+import type { Project, ProjectSession, LLMProvider } from '../../../../types/app';
 import { getIntrinsicMessageKey } from '../../utils/messageKeys';
 import MessageComponent from './MessageComponent';
 import ProviderSelectionEmptyState from './ProviderSelectionEmptyState';
@@ -15,8 +15,8 @@ interface ChatMessagesPaneProps {
   chatMessages: ChatMessage[];
   selectedSession: ProjectSession | null;
   currentSessionId: string | null;
-  provider: SessionProvider;
+  provider: LLMProvider;
-  setProvider: (provider: SessionProvider) => void;
+  setProvider: (provider: LLMProvider) => void;
   textareaRef: RefObject<HTMLTextAreaElement>;
   claudeModel: string;
   setClaudeModel: (model: string) => void;

src/components/chat/view/subcomponents/ProviderSelectionEmptyState.tsx

@@ -8,14 +8,14 @@ import {
   CODEX_MODELS,
   GEMINI_MODELS,
 } from "../../../../../shared/modelConstants";
-import type { ProjectSession, SessionProvider } from "../../../../types/app";
+import type { ProjectSession, LLMProvider } from "../../../../types/app";
 import { NextTaskBanner } from "../../../task-master";
 
 type ProviderSelectionEmptyStateProps = {
   selectedSession: ProjectSession | null;
   currentSessionId: string | null;
-  provider: SessionProvider;
+  provider: LLMProvider;
-  setProvider: (next: SessionProvider) => void;
+  setProvider: (next: LLMProvider) => void;
   textareaRef: React.RefObject<HTMLTextAreaElement>;
   claudeModel: string;
   setClaudeModel: (model: string) => void;
@@ -32,7 +32,7 @@ type ProviderSelectionEmptyStateProps = {
 };
 
 type ProviderDef = {
-  id: SessionProvider;
+  id: LLMProvider;
   name: string;
   infoKey: string;
   accent: string;
@@ -75,7 +75,7 @@ const PROVIDERS: ProviderDef[] = [
   },
 ];
 
-function getModelConfig(p: SessionProvider) {
+function getModelConfig(p: LLMProvider) {
   if (p === "claude") return CLAUDE_MODELS;
   if (p === "codex") return CODEX_MODELS;
   if (p === "gemini") return GEMINI_MODELS;
@@ -83,7 +83,7 @@ function getModelConfig(p: SessionProvider) {
 }
 
 function getModelValue(
-  p: SessionProvider,
+  p: LLMProvider,
   c: string,
   cu: string,
   co: string,
@@ -119,7 +119,7 @@ export default function ProviderSelectionEmptyState({
     defaultValue: "Start the next task",
   });
 
-  const selectProvider = (next: SessionProvider) => {
+  const selectProvider = (next: LLMProvider) => {
     setProvider(next);
     localStorage.setItem("selected-provider", next);
     setTimeout(() => textareaRef.current?.focus(), 100);

src/components/chat/view/subcomponents/ThinkingModeSelector.tsx

@@ -1,4 +1,5 @@
-import { useState, useRef, useEffect } from 'react';
+import { useState, useRef, useEffect, useCallback, type CSSProperties } from 'react';
+import { createPortal } from 'react-dom';
 import { Brain, X } from 'lucide-react';
 import { useTranslation } from 'react-i18next';
 import { thinkingModes } from '../../constants/thinkingModes';
@@ -12,6 +13,11 @@ type ThinkingModeSelectorProps = {
 
 function ThinkingModeSelector({ selectedMode, onModeChange, onClose, className = '' }: ThinkingModeSelectorProps) {
   const { t } = useTranslation('chat');
+  const [isOpen, setIsOpen] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+  const [dropdownStyle, setDropdownStyle] = useState<CSSProperties | null>(null);
 
   // Mapping from mode ID to translation key
   const modeKeyMap: Record<string, string> = {
@@ -29,50 +35,143 @@ function ThinkingModeSelector({ selectedMode, onModeChange, onClose, className =
     };
   });
 
-  const [isOpen, setIsOpen] = useState(false);
+  const closeDropdown = useCallback(() => {
-  const dropdownRef = useRef<HTMLDivElement>(null);
+    setIsOpen(false);
+    onClose?.();
+  }, [onClose]);
+
+  const updateDropdownPosition = useCallback(() => {
+    const trigger = triggerRef.current;
+    const dropdown = dropdownRef.current;
+    if (!trigger || !dropdown || typeof window === 'undefined') {
+      return;
+    }
+
+    const triggerRect = trigger.getBoundingClientRect();
+    const viewportPadding = window.innerWidth < 640 ? 12 : 16;
+    const spacing = 8;
+    const width = Math.min(window.innerWidth - viewportPadding * 2, window.innerWidth < 640 ? 320 : 256);
+    let left = triggerRect.left + triggerRect.width / 2 - width / 2;
+    left = Math.max(viewportPadding, Math.min(left, window.innerWidth - width - viewportPadding));
+
+    const measuredHeight = dropdown.offsetHeight || 0;
+    const spaceBelow = window.innerHeight - triggerRect.bottom - spacing - viewportPadding;
+    const spaceAbove = triggerRect.top - spacing - viewportPadding;
+    const openBelow = spaceBelow >= Math.min(measuredHeight || 320, 320) || spaceBelow >= spaceAbove;
+    const availableHeight = Math.min(
+      window.innerHeight - viewportPadding * 2,
+      Math.max(180, openBelow ? spaceBelow : spaceAbove),
+    );
+    const panelHeight = Math.min(measuredHeight || availableHeight, availableHeight);
+    const top = openBelow
+      ? Math.min(triggerRect.bottom + spacing, window.innerHeight - viewportPadding - panelHeight)
+      : Math.max(viewportPadding, triggerRect.top - spacing - panelHeight);
+
+    setDropdownStyle({
+      position: 'fixed',
+      top,
+      left,
+      width,
+      maxHeight: availableHeight,
+      zIndex: 80,
+    });
+  }, []);
 
   useEffect(() => {
-    const handleClickOutside = (event: MouseEvent) => {
+    if (!isOpen) {
-      if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
+      setDropdownStyle(null);
-        setIsOpen(false);
+      return;
-        if (onClose) onClose();
+    }
+
+    const rafId = window.requestAnimationFrame(updateDropdownPosition);
+    const handleViewportChange = () => updateDropdownPosition();
+
+    window.addEventListener('resize', handleViewportChange);
+    window.addEventListener('scroll', handleViewportChange, true);
+
+    return () => {
+      window.cancelAnimationFrame(rafId);
+      window.removeEventListener('resize', handleViewportChange);
+      window.removeEventListener('scroll', handleViewportChange, true);
+    };
+  }, [isOpen, updateDropdownPosition]);
+
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+
+    const handlePointerDown = (event: PointerEvent) => {
+      const target = event.target;
+      if (!(target instanceof Node)) {
+        return;
+      }
+
+      if (containerRef.current?.contains(target) || dropdownRef.current?.contains(target)) {
+        return;
+      }
+
+      closeDropdown();
+    };
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        closeDropdown();
       }
     };
 
-    document.addEventListener('mousedown', handleClickOutside);
+    document.addEventListener('pointerdown', handlePointerDown, true);
-    return () => document.removeEventListener('mousedown', handleClickOutside);
+    document.addEventListener('keydown', handleKeyDown);
-  }, [onClose]);
+
+    return () => {
+      document.removeEventListener('pointerdown', handlePointerDown, true);
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [isOpen, closeDropdown]);
 
   const currentMode = translatedModes.find(mode => mode.id === selectedMode) || translatedModes[0];
   const IconComponent = currentMode.icon || Brain;
 
   return (
-    <div className={`relative ${className}`} ref={dropdownRef}>
+    <div className={`relative ${className}`} ref={containerRef}>
       <button
+        ref={triggerRef}
         type="button"
-        onClick={() => setIsOpen(!isOpen)}
+        onClick={() => {
+          if (isOpen) {
+            closeDropdown();
+            return;
+          }
+
+          setIsOpen(true);
+        }}
         className={`flex h-10 w-10 items-center justify-center rounded-full transition-all duration-200 sm:h-10 sm:w-10 ${selectedMode === 'none'
             ? 'bg-gray-100 hover:bg-gray-200 dark:bg-gray-700 dark:hover:bg-gray-600'
             : 'bg-blue-100 hover:bg-blue-200 dark:bg-blue-900 dark:hover:bg-blue-800'
           }`}
         title={t('thinkingMode.buttonTitle', { mode: currentMode.name })}
+        aria-haspopup="dialog"
+        aria-expanded={isOpen}
       >
         <IconComponent className={`h-5 w-5 ${currentMode.color}`} />
       </button>
 
-      {isOpen && (
+      {isOpen && typeof document !== 'undefined' && createPortal(
-        <div className="absolute bottom-full right-0 mb-2 w-64 overflow-hidden rounded-lg border border-gray-200 bg-white shadow-xl dark:border-gray-700 dark:bg-gray-800">
+        <div
+          ref={dropdownRef}
+          style={dropdownStyle || { position: 'fixed', top: 0, left: 0, visibility: 'hidden' }}
+          className="flex flex-col overflow-hidden rounded-xl border border-gray-200 bg-white shadow-xl dark:border-gray-700 dark:bg-gray-800"
+          role="dialog"
+          aria-modal="false"
+        >
           <div className="border-b border-gray-200 p-3 dark:border-gray-700">
             <div className="flex items-center justify-between">
               <h3 className="text-sm font-semibold text-gray-900 dark:text-white">
                 {t('thinkingMode.selector.title')}
               </h3>
               <button
-                onClick={() => {
+                type="button"
-                  setIsOpen(false);
+                onClick={closeDropdown}
-                  if (onClose) onClose();
-                }}
                 className="rounded p-1 hover:bg-gray-100 dark:hover:bg-gray-700"
               >
                 <X className="h-4 w-4 text-gray-500" />
@@ -83,7 +182,7 @@ function ThinkingModeSelector({ selectedMode, onModeChange, onClose, className =
             </p>
           </div>
 
-          <div className="py-1">
+          <div className="min-h-0 overflow-y-auto py-1">
             {translatedModes.map((mode) => {
               const ModeIcon = mode.icon;
               const isSelected = mode.id === selectedMode;
@@ -91,10 +190,10 @@ function ThinkingModeSelector({ selectedMode, onModeChange, onClose, className =
               return (
                 <button
                   key={mode.id}
+                  type="button"
                   onClick={() => {
                     onModeChange(mode.id);
-                    setIsOpen(false);
+                    closeDropdown();
-                    if (onClose) onClose();
                   }}
                   className={`w-full px-4 py-3 text-left transition-colors hover:bg-gray-50 dark:hover:bg-gray-700 ${isSelected ? 'bg-gray-50 dark:bg-gray-700' : ''
                     }`}
@@ -135,7 +234,8 @@ function ThinkingModeSelector({ selectedMode, onModeChange, onClose, className =
               <strong>Tip:</strong> {t('thinkingMode.selector.tip')}
             </p>
           </div>
-        </div>
+        </div>,
+        document.body
       )}
     </div>
   );

src/components/llm-logo-provider/SessionProviderLogo.tsx

@@ -1,11 +1,11 @@
-import type { SessionProvider } from '../../types/app';
+import type { LLMProvider } from '../../types/app';
 import ClaudeLogo from './ClaudeLogo';
 import CodexLogo from './CodexLogo';
 import CursorLogo from './CursorLogo';
 import GeminiLogo from './GeminiLogo';
 
 type SessionProviderLogoProps = {
-  provider?: SessionProvider | string | null;
+  provider?: LLMProvider | string | null;
   className?: string;
 };
 

src/components/onboarding/view/Onboarding.tsx

@@ -1,17 +1,15 @@
 import { Check, ChevronLeft, ChevronRight, Loader2 } from 'lucide-react';
 import { useCallback, useEffect, useRef, useState } from 'react';
+import type { LLMProvider } from '../../../types/app';
 import { authenticatedFetch } from '../../../utils/api';
+import { useProviderAuthStatus } from '../../provider-auth/hooks/useProviderAuthStatus';
 import ProviderLoginModal from '../../provider-auth/view/ProviderLoginModal';
 import AgentConnectionsStep from './subcomponents/AgentConnectionsStep';
 import GitConfigurationStep from './subcomponents/GitConfigurationStep';
 import OnboardingStepProgress from './subcomponents/OnboardingStepProgress';
-import type { CliProvider, ProviderStatusMap } from './types';
 import {
-  cliProviders,
-  createInitialProviderStatuses,
   gitEmailPattern,
   readErrorMessageFromResponse,
-  selectedProject,
 } from './utils';
 
 type OnboardingProps = {
@@ -24,59 +22,14 @@ export default function Onboarding({ onComplete }: OnboardingProps) {
   const [gitEmail, setGitEmail] = useState('');
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [errorMessage, setErrorMessage] = useState('');
-  const [activeLoginProvider, setActiveLoginProvider] = useState<CliProvider | null>(null);
+  const [activeLoginProvider, setActiveLoginProvider] = useState<LLMProvider | null>(null);
-  const [providerStatuses, setProviderStatuses] = useState<ProviderStatusMap>(createInitialProviderStatuses);
+  const {
+    providerAuthStatus,
+    checkProviderAuthStatus,
+    refreshProviderAuthStatuses,
+  } = useProviderAuthStatus();
 
-  const previousActiveLoginProviderRef = useRef<CliProvider | null | undefined>(undefined);
+  const previousActiveLoginProviderRef = useRef<LLMProvider | null | undefined>(undefined);
-
-  const checkProviderAuthStatus = useCallback(async (provider: CliProvider) => {
-    try {
-      const response = await authenticatedFetch(`/api/cli/${provider}/status`);
-      if (!response.ok) {
-        setProviderStatuses((previous) => ({
-          ...previous,
-          [provider]: {
-            authenticated: false,
-            email: null,
-            loading: false,
-            error: 'Failed to check authentication status',
-          },
-        }));
-        return;
-      }
-
-      const payload = (await response.json()) as {
-        authenticated?: boolean;
-        email?: string | null;
-        error?: string | null;
-      };
-
-      setProviderStatuses((previous) => ({
-        ...previous,
-        [provider]: {
-          authenticated: Boolean(payload.authenticated),
-          email: payload.email ?? null,
-          loading: false,
-          error: payload.error ?? null,
-        },
-      }));
-    } catch (caughtError) {
-      console.error(`Error checking ${provider} auth status:`, caughtError);
-      setProviderStatuses((previous) => ({
-        ...previous,
-        [provider]: {
-          authenticated: false,
-          email: null,
-          loading: false,
-          error: caughtError instanceof Error ? caughtError.message : 'Unknown error',
-        },
-      }));
-    }
-  }, []);
-
-  const refreshAllProviderStatuses = useCallback(async () => {
-    await Promise.all(cliProviders.map((provider) => checkProviderAuthStatus(provider)));
-  }, [checkProviderAuthStatus]);
 
   const loadGitConfig = useCallback(async () => {
     try {
@@ -99,23 +52,24 @@ export default function Onboarding({ onComplete }: OnboardingProps) {
 
   useEffect(() => {
     void loadGitConfig();
-    void refreshAllProviderStatuses();
+    void refreshProviderAuthStatuses();
-  }, [loadGitConfig, refreshAllProviderStatuses]);
+  }, [loadGitConfig, refreshProviderAuthStatuses]);
 
   useEffect(() => {
     const previousProvider = previousActiveLoginProviderRef.current;
     previousActiveLoginProviderRef.current = activeLoginProvider;
 
-    const isInitialMount = previousProvider === undefined;
+    const didCloseModal = previousProvider !== undefined
-    const didCloseModal = previousProvider !== null && activeLoginProvider === null;
+      && previousProvider !== null
+      && activeLoginProvider === null;
 
-    // Refresh statuses once on mount and again after the login modal is closed.
+    // Refresh statuses after the login modal is closed.
-    if (isInitialMount || didCloseModal) {
+    if (didCloseModal) {
-      void refreshAllProviderStatuses();
+      void refreshProviderAuthStatuses();
     }
-  }, [activeLoginProvider, refreshAllProviderStatuses]);
+  }, [activeLoginProvider, refreshProviderAuthStatuses]);
 
-  const handleProviderLoginOpen = (provider: CliProvider) => {
+  const handleProviderLoginOpen = (provider: LLMProvider) => {
     setActiveLoginProvider(provider);
   };
 
@@ -209,7 +163,7 @@ export default function Onboarding({ onComplete }: OnboardingProps) {
               />
             ) : (
               <AgentConnectionsStep
-                providerStatuses={providerStatuses}
+                providerStatuses={providerAuthStatus}
                 onOpenProviderLogin={handleProviderLoginOpen}
               />
             )}
@@ -279,7 +233,6 @@ export default function Onboarding({ onComplete }: OnboardingProps) {
           isOpen={Boolean(activeLoginProvider)}
           onClose={() => setActiveLoginProvider(null)}
           provider={activeLoginProvider}
-          project={selectedProject}
           onComplete={handleLoginComplete}
         />
       )}

src/components/onboarding/view/subcomponents/AgentConnectionCard.tsx

@@ -1,9 +1,10 @@
 import { Check } from 'lucide-react';
 import SessionProviderLogo from '../../../llm-logo-provider/SessionProviderLogo';
-import type { CliProvider, ProviderAuthStatus } from '../types';
+import type { LLMProvider } from '../../../../types/app';
+import type { ProviderAuthStatus } from '../../../provider-auth/types';
 
 type AgentConnectionCardProps = {
-  provider: CliProvider;
+  provider: LLMProvider;
   title: string;
   status: ProviderAuthStatus;
   connectedClassName: string;

src/components/onboarding/view/subcomponents/AgentConnectionsStep.tsx

@@ -1,9 +1,10 @@
-import type { CliProvider, ProviderStatusMap } from '../types';
+import type { LLMProvider } from '../../../../types/app';
+import type { ProviderAuthStatusMap } from '../../../provider-auth/types';
 import AgentConnectionCard from './AgentConnectionCard';
 
 type AgentConnectionsStepProps = {
-  providerStatuses: ProviderStatusMap;
+  providerStatuses: ProviderAuthStatusMap;
-  onOpenProviderLogin: (provider: CliProvider) => void;
+  onOpenProviderLogin: (provider: LLMProvider) => void;
 };
 
 const providerCards = [

src/components/onboarding/view/types.ts

@@ -1,12 +0,0 @@
-import type { CliProvider } from '../../provider-auth/types';
-
-export type { CliProvider };
-
-export type ProviderAuthStatus = {
-  authenticated: boolean;
-  email: string | null;
-  loading: boolean;
-  error: string | null;
-};
-
-export type ProviderStatusMap = Record<CliProvider, ProviderAuthStatus>;

src/components/onboarding/view/utils.ts

@@ -1,24 +1,5 @@
-import { IS_PLATFORM } from '../../../constants/config';
-import type { CliProvider, ProviderStatusMap } from './types';
-
-export const cliProviders: CliProvider[] = ['claude', 'cursor', 'codex', 'gemini'];
-
 export const gitEmailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 
-export const selectedProject = {
-  name: 'default',
-  displayName: 'default',
-  fullPath: IS_PLATFORM ? '/workspace' : '',
-  path: IS_PLATFORM ? '/workspace' : '',
-};
-
-export const createInitialProviderStatuses = (): ProviderStatusMap => ({
-  claude: { authenticated: false, email: null, loading: true, error: null },
-  cursor: { authenticated: false, email: null, loading: true, error: null },
-  codex: { authenticated: false, email: null, loading: true, error: null },
-  gemini: { authenticated: false, email: null, loading: true, error: null },
-});
-
 export const readErrorMessageFromResponse = async (response: Response, fallback: string) => {
   try {
     const payload = (await response.json()) as { error?: string };

src/components/provider-auth/hooks/useProviderAuthStatus.ts

@@ -0,0 +1,109 @@
+import { useCallback, useState } from 'react';
+import { authenticatedFetch } from '../../../utils/api';
+import type { LLMProvider } from '../../../types/app';
+import {
+  CLI_AUTH_STATUS_ENDPOINTS,
+  CLI_PROVIDERS,
+  createInitialProviderAuthStatusMap,
+} from '../types';
+import type {
+  ProviderAuthStatus,
+  ProviderAuthStatusMap,
+} from '../types';
+
+type ProviderAuthStatusPayload = {
+  authenticated?: boolean;
+  email?: string | null;
+  method?: string | null;
+  error?: string | null;
+};
+
+const FALLBACK_STATUS_ERROR = 'Failed to check authentication status';
+const FALLBACK_UNKNOWN_ERROR = 'Unknown error';
+
+const toErrorMessage = (error: unknown): string => (
+  error instanceof Error ? error.message : FALLBACK_UNKNOWN_ERROR
+);
+
+const toProviderAuthStatus = (
+  payload: ProviderAuthStatusPayload,
+  fallbackError: string | null = null,
+): ProviderAuthStatus => ({
+  authenticated: Boolean(payload.authenticated),
+  email: payload.email ?? null,
+  method: payload.method ?? null,
+  error: payload.error ?? fallbackError,
+  loading: false,
+});
+
+type UseProviderAuthStatusOptions = {
+  initialLoading?: boolean;
+};
+
+export function useProviderAuthStatus(
+  { initialLoading = true }: UseProviderAuthStatusOptions = {},
+) {
+  const [providerAuthStatus, setProviderAuthStatus] = useState<ProviderAuthStatusMap>(() => (
+    createInitialProviderAuthStatusMap(initialLoading)
+  ));
+
+  const setProviderLoading = useCallback((provider: LLMProvider) => {
+    setProviderAuthStatus((previous) => ({
+      ...previous,
+      [provider]: {
+        ...previous[provider],
+        loading: true,
+        error: null,
+      },
+    }));
+  }, []);
+
+  const setProviderStatus = useCallback((provider: LLMProvider, status: ProviderAuthStatus) => {
+    setProviderAuthStatus((previous) => ({
+      ...previous,
+      [provider]: status,
+    }));
+  }, []);
+
+  const checkProviderAuthStatus = useCallback(async (provider: LLMProvider) => {
+    setProviderLoading(provider);
+
+    try {
+      const response = await authenticatedFetch(CLI_AUTH_STATUS_ENDPOINTS[provider]);
+
+      if (!response.ok) {
+        setProviderStatus(provider, {
+          authenticated: false,
+          email: null,
+          method: null,
+          loading: false,
+          error: FALLBACK_STATUS_ERROR,
+        });
+        return;
+      }
+
+      const payload = (await response.json()) as ProviderAuthStatusPayload;
+      setProviderStatus(provider, toProviderAuthStatus(payload));
+    } catch (caughtError) {
+      console.error(`Error checking ${provider} auth status:`, caughtError);
+      setProviderStatus(provider, {
+        authenticated: false,
+        email: null,
+        method: null,
+        loading: false,
+        error: toErrorMessage(caughtError),
+      });
+    }
+  }, [setProviderLoading, setProviderStatus]);
+
+  const refreshProviderAuthStatuses = useCallback(async (providers: LLMProvider[] = CLI_PROVIDERS) => {
+    await Promise.all(providers.map((provider) => checkProviderAuthStatus(provider)));
+  }, [checkProviderAuthStatus]);
+
+  return {
+    providerAuthStatus,
+    setProviderAuthStatus,
+    checkProviderAuthStatus,
+    refreshProviderAuthStatuses,
+  };
+}

src/components/provider-auth/types.ts

@@ -1 +1,27 @@
-export type CliProvider = 'claude' | 'cursor' | 'codex' | 'gemini';
+import type { LLMProvider } from '../../types/app';
+
+export type ProviderAuthStatus = {
+  authenticated: boolean;
+  email: string | null;
+  method: string | null;
+  error: string | null;
+  loading: boolean;
+};
+
+export type ProviderAuthStatusMap = Record<LLMProvider, ProviderAuthStatus>;
+
+export const CLI_PROVIDERS: LLMProvider[] = ['claude', 'cursor', 'codex', 'gemini'];
+
+export const CLI_AUTH_STATUS_ENDPOINTS: Record<LLMProvider, string> = {
+  claude: '/api/cli/claude/status',
+  cursor: '/api/cli/cursor/status',
+  codex: '/api/cli/codex/status',
+  gemini: '/api/cli/gemini/status',
+};
+
+export const createInitialProviderAuthStatusMap = (loading = true): ProviderAuthStatusMap => ({
+  claude: { authenticated: false, email: null, method: null, error: null, loading },
+  cursor: { authenticated: false, email: null, method: null, error: null, loading },
+  codex: { authenticated: false, email: null, method: null, error: null, loading },
+  gemini: { authenticated: false, email: null, method: null, error: null, loading },
+});

src/components/provider-auth/view/ProviderLoginModal.tsx

@@ -1,21 +1,12 @@
 import { ExternalLink, KeyRound, X } from 'lucide-react';
 import StandaloneShell from '../../standalone-shell/view/StandaloneShell';
-import { IS_PLATFORM } from '../../../constants/config';
+import { DEFAULT_PROJECT_FOR_EMPTY_SHELL, IS_PLATFORM } from '../../../constants/config';
-import type { CliProvider } from '../types';
+import type { LLMProvider } from '../../../types/app';
-
-type LoginModalProject = {
-  name?: string;
-  displayName?: string;
-  fullPath?: string;
-  path?: string;
-  [key: string]: unknown;
-};
 
 type ProviderLoginModalProps = {
   isOpen: boolean;
   onClose: () => void;
-  provider?: CliProvider;
+  provider?: LLMProvider;
-  project?: LoginModalProject | null;
   onComplete?: (exitCode: number) => void;
   customCommand?: string;
   isAuthenticated?: boolean;
@@ -26,7 +17,7 @@ const getProviderCommand = ({
   customCommand,
   isAuthenticated: _isAuthenticated,
 }: {
-  provider: CliProvider;
+  provider: LLMProvider;
   customCommand?: string;
   isAuthenticated: boolean;
 }) => {
@@ -49,30 +40,17 @@ const getProviderCommand = ({
   return 'gemini status';
 };
 
-const getProviderTitle = (provider: CliProvider) => {
+const getProviderTitle = (provider: LLMProvider) => {
   if (provider === 'claude') return 'Claude CLI Login';
   if (provider === 'cursor') return 'Cursor CLI Login';
   if (provider === 'codex') return 'Codex CLI Login';
   return 'Gemini CLI Configuration';
 };
 
-const normalizeProject = (project?: LoginModalProject | null) => {
-  const normalizedName = project?.name || 'default';
-  const normalizedFullPath = project?.fullPath ?? project?.path ?? (IS_PLATFORM ? '/workspace' : '');
-
-  return {
-    name: normalizedName,
-    displayName: project?.displayName || normalizedName,
-    fullPath: normalizedFullPath,
-    path: project?.path ?? normalizedFullPath,
-  };
-};
-
 export default function ProviderLoginModal({
   isOpen,
   onClose,
   provider = 'claude',
-  project = null,
   onComplete,
   customCommand,
   isAuthenticated = false,
@@ -83,7 +61,6 @@ export default function ProviderLoginModal({
 
   const command = getProviderCommand({ provider, customCommand, isAuthenticated });
   const title = getProviderTitle(provider);
-  const shellProject = normalizeProject(project);
 
   const handleComplete = (exitCode: number) => {
     onComplete?.(exitCode);
@@ -158,7 +135,7 @@ export default function ProviderLoginModal({
               </button>
             </div>
           ) : (
-            <StandaloneShell project={shellProject} command={command} onComplete={handleComplete} minimal={true} />
+            <StandaloneShell project={DEFAULT_PROJECT_FOR_EMPTY_SHELL} command={command} onComplete={handleComplete} minimal={true} />
           )}
         </div>
       </div>

src/components/settings/constants/constants.ts

@@ -1,7 +1,6 @@
 import type {
   AgentCategory,
   AgentProvider,
-  AuthStatus,
   ClaudeMcpFormState,
   CodexMcpFormState,
   CodeEditorSettingsState,
@@ -34,13 +33,6 @@ export const DEFAULT_CODE_EDITOR_SETTINGS: CodeEditorSettingsState = {
   fontSize: '14',
 };
 
-export const DEFAULT_AUTH_STATUS: AuthStatus = {
-  authenticated: false,
-  email: null,
-  loading: true,
-  error: null,
-};
-
 export const DEFAULT_MCP_TEST_RESULT: McpTestResult = {
   success: false,
   message: '',
@@ -88,9 +80,3 @@ export const DEFAULT_CURSOR_PERMISSIONS: CursorPermissionsState = {
   skipPermissions: false,
 };
 
-export const AUTH_STATUS_ENDPOINTS: Record<AgentProvider, string> = {
-  claude: '/api/cli/claude/status',
-  cursor: '/api/cli/cursor/status',
-  codex: '/api/cli/codex/status',
-  gemini: '/api/cli/gemini/status',
-};

src/components/settings/hooks/useSettingsController.ts

@@ -1,15 +1,13 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { useTheme } from '../../../contexts/ThemeContext';
 import { authenticatedFetch } from '../../../utils/api';
+import { useProviderAuthStatus } from '../../provider-auth/hooks/useProviderAuthStatus';
 import {
-  AUTH_STATUS_ENDPOINTS,
-  DEFAULT_AUTH_STATUS,
   DEFAULT_CODE_EDITOR_SETTINGS,
   DEFAULT_CURSOR_PERMISSIONS,
 } from '../constants/constants';
 import type {
   AgentProvider,
-  AuthStatus,
   ClaudeMcpFormState,
   ClaudePermissionsState,
   CodeEditorSettingsState,
@@ -23,7 +21,6 @@ import type {
   NotificationPreferencesState,
   ProjectSortOrder,
   SettingsMainTab,
-  SettingsProject,
 } from '../types/types';
 
 type ThemeContextValue = {
@@ -34,15 +31,6 @@ type ThemeContextValue = {
 type UseSettingsControllerArgs = {
   isOpen: boolean;
   initialTab: string;
-  projects: SettingsProject[];
-  onClose: () => void;
-};
-
-type StatusApiResponse = {
-  authenticated?: boolean;
-  email?: string | null;
-  error?: string | null;
-  method?: string;
 };
 
 type JsonResult = {
@@ -166,20 +154,6 @@ const mapCliServersToMcpServers = (servers: McpCliServer[] = []): McpServer[] =>
   }))
 );
 
-const getDefaultProject = (projects: SettingsProject[]): SettingsProject => {
-  if (projects.length > 0) {
-    return projects[0];
-  }
-
-  const cwd = typeof process !== 'undefined' && process.cwd ? process.cwd() : '';
-  return {
-    name: 'default',
-    displayName: 'default',
-    fullPath: cwd,
-    path: cwd,
-  };
-};
-
 const toResponseJson = async <T>(response: Response): Promise<T> => response.json() as Promise<T>;
 
 const createEmptyClaudePermissions = (): ClaudePermissionsState => ({
@@ -204,7 +178,7 @@ const createDefaultNotificationPreferences = (): NotificationPreferencesState =>
   },
 });
 
-export function useSettingsController({ isOpen, initialTab, projects, onClose }: UseSettingsControllerArgs) {
+export function useSettingsController({ isOpen, initialTab }: UseSettingsControllerArgs) {
   const { isDarkMode, toggleDarkMode } = useTheme() as ThemeContextValue;
   const closeTimerRef = useRef<number | null>(null);
 
@@ -242,64 +216,11 @@ export function useSettingsController({ isOpen, initialTab, projects, onClose }:
 
   const [showLoginModal, setShowLoginModal] = useState(false);
   const [loginProvider, setLoginProvider] = useState<ActiveLoginProvider>('');
-  const [selectedProject, setSelectedProject] = useState<SettingsProject | null>(null);
+  const {
-
+    providerAuthStatus,
-  const [claudeAuthStatus, setClaudeAuthStatus] = useState<AuthStatus>(DEFAULT_AUTH_STATUS);
+    checkProviderAuthStatus,
-  const [cursorAuthStatus, setCursorAuthStatus] = useState<AuthStatus>(DEFAULT_AUTH_STATUS);
+    refreshProviderAuthStatuses,
-  const [codexAuthStatus, setCodexAuthStatus] = useState<AuthStatus>(DEFAULT_AUTH_STATUS);
+  } = useProviderAuthStatus();
-  const [geminiAuthStatus, setGeminiAuthStatus] = useState<AuthStatus>(DEFAULT_AUTH_STATUS);
-
-  const setAuthStatusByProvider = useCallback((provider: AgentProvider, status: AuthStatus) => {
-    if (provider === 'claude') {
-      setClaudeAuthStatus(status);
-      return;
-    }
-
-    if (provider === 'cursor') {
-      setCursorAuthStatus(status);
-      return;
-    }
-
-    if (provider === 'gemini') {
-      setGeminiAuthStatus(status);
-      return;
-    }
-
-    setCodexAuthStatus(status);
-  }, []);
-
-  const checkAuthStatus = useCallback(async (provider: AgentProvider) => {
-    try {
-      const response = await authenticatedFetch(AUTH_STATUS_ENDPOINTS[provider]);
-
-      if (!response.ok) {
-        setAuthStatusByProvider(provider, {
-          authenticated: false,
-          email: null,
-          loading: false,
-          error: 'Failed to check authentication status',
-        });
-        return;
-      }
-
-      const data = await toResponseJson<StatusApiResponse>(response);
-      setAuthStatusByProvider(provider, {
-        authenticated: Boolean(data.authenticated),
-        email: data.email || null,
-        loading: false,
-        error: data.error || null,
-        method: data.method,
-      });
-    } catch (error) {
-      console.error(`Error checking ${provider} auth status:`, error);
-      setAuthStatusByProvider(provider, {
-        authenticated: false,
-        email: null,
-        loading: false,
-        error: getErrorMessage(error),
-      });
-    }
-  }, [setAuthStatusByProvider]);
 
   const fetchCursorMcpServers = useCallback(async () => {
     try {
@@ -724,9 +645,8 @@ export function useSettingsController({ isOpen, initialTab, projects, onClose }:
 
   const openLoginForProvider = useCallback((provider: AgentProvider) => {
     setLoginProvider(provider);
-    setSelectedProject(getDefaultProject(projects));
     setShowLoginModal(true);
-  }, [projects]);
+  }, []);
 
   const handleLoginComplete = useCallback((exitCode: number) => {
     if (exitCode !== 0 || !loginProvider) {
@@ -734,8 +654,8 @@ export function useSettingsController({ isOpen, initialTab, projects, onClose }:
     }
 
     setSaveStatus('success');
-    void checkAuthStatus(loginProvider);
+    void checkProviderAuthStatus(loginProvider);
-  }, [checkAuthStatus, loginProvider]);
+  }, [checkProviderAuthStatus, loginProvider]);
 
   const saveSettings = useCallback(async () => {
     setSaveStatus(null);
@@ -827,11 +747,8 @@ export function useSettingsController({ isOpen, initialTab, projects, onClose }:
 
     setActiveTab(normalizeMainTab(initialTab));
     void loadSettings();
-    void checkAuthStatus('claude');
+    void refreshProviderAuthStatuses();
-    void checkAuthStatus('cursor');
+  }, [initialTab, isOpen, loadSettings, refreshProviderAuthStatuses]);
-    void checkAuthStatus('codex');
-    void checkAuthStatus('gemini');
-  }, [checkAuthStatus, initialTab, isOpen, loadSettings]);
 
   useEffect(() => {
     localStorage.setItem('codeEditorTheme', codeEditorSettings.theme);
@@ -935,17 +852,13 @@ export function useSettingsController({ isOpen, initialTab, projects, onClose }:
     closeCodexMcpForm,
     submitCodexMcpForm,
     handleCodexMcpDelete,
-    claudeAuthStatus,
+    providerAuthStatus,
-    cursorAuthStatus,
-    codexAuthStatus,
-    geminiAuthStatus,
     geminiPermissionMode,
     setGeminiPermissionMode,
     openLoginForProvider,
     showLoginModal,
     setShowLoginModal,
     loginProvider,
-    selectedProject,
     handleLoginComplete,
   };
 }

src/components/settings/types/types.ts

@@ -1,7 +1,9 @@
 import type { Dispatch, SetStateAction } from 'react';
+import type { LLMProvider } from '../../../types/app';
+import type { ProviderAuthStatus } from '../../provider-auth/types';
 
 export type SettingsMainTab = 'agents' | 'appearance' | 'git' | 'api' | 'tasks' | 'notifications' | 'plugins' | 'about';
-export type AgentProvider = 'claude' | 'cursor' | 'codex' | 'gemini';
+export type AgentProvider = LLMProvider;
 export type AgentCategory = 'account' | 'permissions' | 'mcp';
 export type ProjectSortOrder = 'name' | 'date';
 export type SaveStatus = 'success' | 'error' | null;
@@ -18,13 +20,7 @@ export type SettingsProject = {
   path?: string;
 };
 
-export type AuthStatus = {
+export type AuthStatus = ProviderAuthStatus;
-  authenticated: boolean;
-  email: string | null;
-  loading: boolean;
-  error: string | null;
-  method?: string;
-};
 
 export type KeyValueMap = Record<string, string>;
 

src/components/settings/view/Settings.tsx

@@ -56,23 +56,17 @@ function Settings({ isOpen, onClose, projects = [], initialTab = 'agents' }: Set
     closeCodexMcpForm,
     submitCodexMcpForm,
     handleCodexMcpDelete,
-    claudeAuthStatus,
+    providerAuthStatus,
-    cursorAuthStatus,
-    codexAuthStatus,
-    geminiAuthStatus,
     geminiPermissionMode,
     setGeminiPermissionMode,
     openLoginForProvider,
     showLoginModal,
     setShowLoginModal,
     loginProvider,
-    selectedProject,
     handleLoginComplete,
   } = useSettingsController({
     isOpen,
-    initialTab,
+    initialTab
-    projects,
-    onClose,
   });
 
   const {
@@ -105,13 +99,7 @@ function Settings({ isOpen, onClose, projects = [], initialTab = 'agents' }: Set
     return null;
   }
 
-  const isAuthenticated = loginProvider === 'claude'
+  const isAuthenticated = Boolean(loginProvider && providerAuthStatus[loginProvider].authenticated);
-    ? claudeAuthStatus.authenticated
-    : loginProvider === 'cursor'
-      ? cursorAuthStatus.authenticated
-      : loginProvider === 'codex'
-        ? codexAuthStatus.authenticated
-        : false;
 
   return (
     <div className="modal-backdrop fixed inset-0 z-[9999] flex items-center justify-center bg-background/80 backdrop-blur-sm md:p-4">
@@ -121,7 +109,7 @@ function Settings({ isOpen, onClose, projects = [], initialTab = 'agents' }: Set
           <h2 className="text-base font-semibold text-foreground">{t('title')}</h2>
           <div className="flex items-center gap-2">
             {saveStatus === 'success' && (
-              <span className="text-xs text-muted-foreground animate-in fade-in">{t('saveStatus.success')}</span>
+              <span className="animate-in fade-in text-xs text-muted-foreground">{t('saveStatus.success')}</span>
             )}
             <Button
               variant="ghost"
@@ -158,14 +146,8 @@ function Settings({ isOpen, onClose, projects = [], initialTab = 'agents' }: Set
 
               {activeTab === 'agents' && (
                 <AgentsSettingsTab
-                  claudeAuthStatus={claudeAuthStatus}
+                  providerAuthStatus={providerAuthStatus}
-                  cursorAuthStatus={cursorAuthStatus}
+                  onProviderLogin={openLoginForProvider}
-                  codexAuthStatus={codexAuthStatus}
-                  geminiAuthStatus={geminiAuthStatus}
-                  onClaudeLogin={() => openLoginForProvider('claude')}
-                  onCursorLogin={() => openLoginForProvider('cursor')}
-                  onCodexLogin={() => openLoginForProvider('codex')}
-                  onGeminiLogin={() => openLoginForProvider('gemini')}
                   claudePermissions={claudePermissions}
                   onClaudePermissionsChange={setClaudePermissions}
                   cursorPermissions={cursorPermissions}
@@ -219,7 +201,6 @@ function Settings({ isOpen, onClose, projects = [], initialTab = 'agents' }: Set
         isOpen={showLoginModal}
         onClose={() => setShowLoginModal(false)}
         provider={loginProvider || 'claude'}
-        project={selectedProject}
         onComplete={handleLoginComplete}
         isAuthenticated={isAuthenticated}
       />

src/components/settings/view/tabs/agents-settings/AgentsSettingsTab.tsx

@@ -6,14 +6,8 @@ import AgentSelectorSection from './sections/AgentSelectorSection';
 import type { AgentContext, AgentsSettingsTabProps } from './types';
 
 export default function AgentsSettingsTab({
-  claudeAuthStatus,
+  providerAuthStatus,
-  cursorAuthStatus,
+  onProviderLogin,
-  codexAuthStatus,
-  geminiAuthStatus,
-  onClaudeLogin,
-  onCursorLogin,
-  onCodexLogin,
-  onGeminiLogin,
   claudePermissions,
   onClaudePermissionsChange,
   cursorPermissions,
@@ -41,30 +35,27 @@ export default function AgentsSettingsTab({
 
   const agentContextById = useMemo<Record<AgentProvider, AgentContext>>(() => ({
     claude: {
-      authStatus: claudeAuthStatus,
+      authStatus: providerAuthStatus.claude,
-      onLogin: onClaudeLogin,
+      onLogin: () => onProviderLogin('claude'),
     },
     cursor: {
-      authStatus: cursorAuthStatus,
+      authStatus: providerAuthStatus.cursor,
-      onLogin: onCursorLogin,
+      onLogin: () => onProviderLogin('cursor'),
     },
     codex: {
-      authStatus: codexAuthStatus,
+      authStatus: providerAuthStatus.codex,
-      onLogin: onCodexLogin,
+      onLogin: () => onProviderLogin('codex'),
     },
     gemini: {
-      authStatus: geminiAuthStatus,
+      authStatus: providerAuthStatus.gemini,
-      onLogin: onGeminiLogin,
+      onLogin: () => onProviderLogin('gemini'),
     },
   }), [
-    claudeAuthStatus,
+    onProviderLogin,
-    codexAuthStatus,
+    providerAuthStatus.claude,
-    cursorAuthStatus,
+    providerAuthStatus.codex,
-    geminiAuthStatus,
+    providerAuthStatus.cursor,
-    onClaudeLogin,
+    providerAuthStatus.gemini,
-    onCodexLogin,
-    onCursorLogin,
-    onGeminiLogin,
   ]);
 
   return (

src/components/settings/view/tabs/agents-settings/types.ts

@@ -17,16 +17,11 @@ export type AgentContext = {
 };
 
 export type AgentContextByProvider = Record<AgentProvider, AgentContext>;
+export type ProviderAuthStatusByProvider = Record<AgentProvider, AuthStatus>;
 
 export type AgentsSettingsTabProps = {
-  claudeAuthStatus: AuthStatus;
+  providerAuthStatus: ProviderAuthStatusByProvider;
-  cursorAuthStatus: AuthStatus;
+  onProviderLogin: (provider: AgentProvider) => void;
-  codexAuthStatus: AuthStatus;
-  geminiAuthStatus: AuthStatus;
-  onClaudeLogin: () => void;
-  onCursorLogin: () => void;
-  onCodexLogin: () => void;
-  onGeminiLogin: () => void;
   claudePermissions: ClaudePermissionsState;
   onClaudePermissionsChange: (value: ClaudePermissionsState) => void;
   cursorPermissions: CursorPermissionsState;

src/components/sidebar/hooks/useSidebarController.ts

@@ -2,7 +2,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type React from 'react';
 import type { TFunction } from 'i18next';
 import { api } from '../../../utils/api';
-import type { Project, ProjectSession, SessionProvider } from '../../../types/app';
+import type { Project, ProjectSession, LLMProvider } from '../../../types/app';
 import type {
   AdditionalSessionsByProject,
   DeleteProjectConfirmation,
@@ -545,7 +545,7 @@ export function useSidebarController({
   }, [onRefresh]);
 
   const updateSessionSummary = useCallback(
-    async (_projectName: string, sessionId: string, summary: string, provider: SessionProvider) => {
+    async (_projectName: string, sessionId: string, summary: string, provider: LLMProvider) => {
       const trimmed = summary.trim();
       if (!trimmed) {
         setEditingSession(null);

src/components/sidebar/types/types.ts

@@ -1,9 +1,9 @@
-import type { LoadingProgress, Project, ProjectSession, SessionProvider } from '../../../types/app';
+import type { LoadingProgress, Project, ProjectSession, LLMProvider } from '../../../types/app';
 
 export type ProjectSortOrder = 'name' | 'date';
 
 export type SessionWithProvider = ProjectSession & {
-  __provider: SessionProvider;
+  __provider: LLMProvider;
 };
 
 export type AdditionalSessionsByProject = Record<string, ProjectSession[]>;
@@ -18,7 +18,7 @@ export type SessionDeleteConfirmation = {
   projectName: string;
   sessionId: string;
   sessionTitle: string;
-  provider: SessionProvider;
+  provider: LLMProvider;
 };
 
 export type SidebarProps = {

src/components/sidebar/view/Sidebar.tsx

@@ -6,7 +6,7 @@ import { useUiPreferences } from '../../../hooks/useUiPreferences';
 import { useSidebarController } from '../hooks/useSidebarController';
 import { useTaskMaster } from '../../../contexts/TaskMasterContext';
 import { useTasksSettings } from '../../../contexts/TasksSettingsContext';
-import type { Project, SessionProvider } from '../../../types/app';
+import type { Project, LLMProvider } from '../../../types/app';
 import type { MCPServerStatus, SidebarProps } from '../types/types';
 import SidebarCollapsed from './subcomponents/SidebarCollapsed';
 import SidebarContent from './subcomponents/SidebarContent';
@@ -177,7 +177,7 @@ function Sidebar({
       setEditingSession(null);
       setEditingSessionName('');
     },
-    onSaveEditingSession: (projectName: string, sessionId: string, summary: string, provider: SessionProvider) => {
+    onSaveEditingSession: (projectName: string, sessionId: string, summary: string, provider: LLMProvider) => {
       void updateSessionSummary(projectName, sessionId, summary, provider);
     },
     t,
@@ -235,7 +235,7 @@ function Sidebar({
             isSearching={isSearching}
             searchProgress={searchProgress}
             onConversationResultClick={(projectName: string, sessionId: string, provider: string, messageTimestamp?: string | null, messageSnippet?: string | null) => {
-              const resolvedProvider = (provider || 'claude') as SessionProvider;
+              const resolvedProvider = (provider || 'claude') as LLMProvider;
               const project = projects.find(p => p.name === projectName);
               const searchTarget = { __searchTargetTimestamp: messageTimestamp || null, __searchTargetSnippet: messageSnippet || null };
               const sessionObj = {

src/components/sidebar/view/subcomponents/SidebarProjectItem.tsx

@@ -2,7 +2,7 @@ import { Check, ChevronDown, ChevronRight, Edit3, Folder, FolderOpen, Star, Tras
 import type { TFunction } from 'i18next';
 import { Button } from '../../../../shared/view/ui';
 import { cn } from '../../../../lib/utils';
-import type { Project, ProjectSession, SessionProvider } from '../../../../types/app';
+import type { Project, ProjectSession, LLMProvider } from '../../../../types/app';
 import type { MCPServerStatus, SessionWithProvider } from '../../types/types';
 import { getTaskIndicatorStatus } from '../../utils/utils';
 import TaskIndicator from './TaskIndicator';
@@ -38,14 +38,14 @@ type SidebarProjectItemProps = {
     projectName: string,
     sessionId: string,
     sessionTitle: string,
-    provider: SessionProvider,
+    provider: LLMProvider,
   ) => void;
   onLoadMoreSessions: (project: Project) => void;
   onNewSession: (project: Project) => void;
   onEditingSessionNameChange: (value: string) => void;
   onStartEditingSession: (sessionId: string, initialName: string) => void;
   onCancelEditingSession: () => void;
-  onSaveEditingSession: (projectName: string, sessionId: string, summary: string, provider: SessionProvider) => void;
+  onSaveEditingSession: (projectName: string, sessionId: string, summary: string, provider: LLMProvider) => void;
   t: TFunction;
 };
 

src/components/sidebar/view/subcomponents/SidebarProjectList.tsx

@@ -1,6 +1,6 @@
 import { useEffect } from 'react';
 import type { TFunction } from 'i18next';
-import type { LoadingProgress, Project, ProjectSession, SessionProvider } from '../../../../types/app';
+import type { LoadingProgress, Project, ProjectSession, LLMProvider } from '../../../../types/app';
 import type {
   LoadingSessionsByProject,
   MCPServerStatus,
@@ -42,14 +42,14 @@ export type SidebarProjectListProps = {
     projectName: string,
     sessionId: string,
     sessionTitle: string,
-    provider: SessionProvider,
+    provider: LLMProvider,
   ) => void;
   onLoadMoreSessions: (project: Project) => void;
   onNewSession: (project: Project) => void;
   onEditingSessionNameChange: (value: string) => void;
   onStartEditingSession: (sessionId: string, initialName: string) => void;
   onCancelEditingSession: () => void;
-  onSaveEditingSession: (projectName: string, sessionId: string, summary: string, provider: SessionProvider) => void;
+  onSaveEditingSession: (projectName: string, sessionId: string, summary: string, provider: LLMProvider) => void;
   t: TFunction;
 };
 

src/components/sidebar/view/subcomponents/SidebarProjectSessions.tsx

@@ -1,7 +1,7 @@
 import { ChevronDown, Plus } from 'lucide-react';
 import type { TFunction } from 'i18next';
 import { Button } from '../../../../shared/view/ui';
-import type { Project, ProjectSession, SessionProvider } from '../../../../types/app';
+import type { Project, ProjectSession, LLMProvider } from '../../../../types/app';
 import type { SessionWithProvider } from '../../types/types';
 import SidebarSessionItem from './SidebarSessionItem';
 
@@ -18,14 +18,14 @@ type SidebarProjectSessionsProps = {
   onEditingSessionNameChange: (value: string) => void;
   onStartEditingSession: (sessionId: string, initialName: string) => void;
   onCancelEditingSession: () => void;
-  onSaveEditingSession: (projectName: string, sessionId: string, summary: string, provider: SessionProvider) => void;
+  onSaveEditingSession: (projectName: string, sessionId: string, summary: string, provider: LLMProvider) => void;
   onProjectSelect: (project: Project) => void;
   onSessionSelect: (session: SessionWithProvider, projectName: string) => void;
   onDeleteSession: (
     projectName: string,
     sessionId: string,
     sessionTitle: string,
-    provider: SessionProvider,
+    provider: LLMProvider,
   ) => void;
   onLoadMoreSessions: (project: Project) => void;
   onNewSession: (project: Project) => void;

src/components/sidebar/view/subcomponents/SidebarSessionItem.tsx

@@ -3,7 +3,7 @@ import type { TFunction } from 'i18next';
 import { Badge, Button } from '../../../../shared/view/ui';
 import { cn } from '../../../../lib/utils';
 import { formatTimeAgo } from '../../../../utils/dateUtils';
-import type { Project, ProjectSession, SessionProvider } from '../../../../types/app';
+import type { Project, ProjectSession, LLMProvider } from '../../../../types/app';
 import type { SessionWithProvider } from '../../types/types';
 import { createSessionViewModel } from '../../utils/utils';
 import SessionProviderLogo from '../../../llm-logo-provider/SessionProviderLogo';
@@ -18,14 +18,14 @@ type SidebarSessionItemProps = {
   onEditingSessionNameChange: (value: string) => void;
   onStartEditingSession: (sessionId: string, initialName: string) => void;
   onCancelEditingSession: () => void;
-  onSaveEditingSession: (projectName: string, sessionId: string, summary: string, provider: SessionProvider) => void;
+  onSaveEditingSession: (projectName: string, sessionId: string, summary: string, provider: LLMProvider) => void;
   onProjectSelect: (project: Project) => void;
   onSessionSelect: (session: SessionWithProvider, projectName: string) => void;
   onDeleteSession: (
     projectName: string,
     sessionId: string,
     sessionTitle: string,
-    provider: SessionProvider,
+    provider: LLMProvider,
   ) => void;
   t: TFunction;
 };

src/components/version-upgrade/view/VersionUpgradeModal.tsx

@@ -1,9 +1,10 @@
-import { useCallback, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { authenticatedFetch } from "../../../utils/api";
 import { ReleaseInfo } from "../../../types/sharedTypes";
 import { copyTextToClipboard } from "../../../utils/clipboard";
 import type { InstallMode } from "../../../hooks/useVersionCheck";
+import { IS_PLATFORM } from "../../../constants/config";
 
 interface VersionUpgradeModalProps {
     isOpen: boolean;
@@ -14,6 +15,8 @@ interface VersionUpgradeModalProps {
     installMode: InstallMode;
 }
 
+const RELOAD_COUNTDOWN_START = 30;
+
 export function VersionUpgradeModal({
     isOpen,
     onClose,
@@ -25,14 +28,36 @@ export function VersionUpgradeModal({
     const { t } = useTranslation('common');
     const upgradeCommand = installMode === 'npm'
         ? t('versionUpdate.npmUpgradeCommand')
-        : 'git checkout main && git pull && npm install';
+        : IS_PLATFORM
+            ? 'npm run update:platform'
+            : 'git checkout main && git pull && npm install';
     const [isUpdating, setIsUpdating] = useState(false);
     const [updateOutput, setUpdateOutput] = useState('');
     const [updateError, setUpdateError] = useState('');
+    const [reloadCountdown, setReloadCountdown] = useState<number | null>(null);
+
+    useEffect(() => {
+        if (!IS_PLATFORM || reloadCountdown === null || reloadCountdown <= 0) {
+            return;
+        }
+
+        const timeoutId = window.setTimeout(() => {
+            setReloadCountdown((previousCountdown) => {
+                if (previousCountdown === null) {
+                    return null;
+                }
+
+                return Math.max(previousCountdown - 1, 0);
+            });
+        }, 1000);
+
+        return () => window.clearTimeout(timeoutId);
+    }, [reloadCountdown]);
 
     const handleUpdateNow = useCallback(async () => {
         setIsUpdating(true);
         setUpdateOutput('Starting update...\n');
+        setReloadCountdown(IS_PLATFORM ? RELOAD_COUNTDOWN_START : null);
         setUpdateError('');
 
         try {
@@ -46,7 +71,7 @@ export function VersionUpgradeModal({
             if (response.ok) {
                 setUpdateOutput(prev => prev + data.output + '\n');
                 setUpdateOutput(prev => prev + '\n✅ Update completed successfully!\n');
-                setUpdateOutput(prev => prev + 'Please restart the server to apply changes.\n');
+                setUpdateOutput(prev => prev + 'Please restart the server to apply changes.' + '\n');
             } else {
                 setUpdateError(data.error || 'Update failed');
                 setUpdateOutput(prev => prev + '\n❌ Update failed: ' + (data.error || 'Unknown error') + '\n');
@@ -143,6 +168,13 @@ export function VersionUpgradeModal({
                         <div className="max-h-48 overflow-y-auto rounded-lg border border-gray-700 bg-gray-900 p-4 dark:bg-gray-950">
                             <pre className="whitespace-pre-wrap font-mono text-xs text-green-400">{updateOutput}</pre>
                         </div>
+                        {IS_PLATFORM && reloadCountdown !== null && (
+                            <div className="rounded-md border border-blue-200 bg-blue-50 px-3 py-2 text-xs text-blue-700 dark:border-blue-900/40 dark:bg-blue-900/20 dark:text-blue-200">
+                                {reloadCountdown === 0
+                                    ? 'Refresh the page now. If that doesn\'t work, RESTART the environment.'
+                                    : `Refresh the page in ${reloadCountdown} ${reloadCountdown === 1 ? 'second' : 'seconds'}. If that doesn\'t work, RESTART the environment.`}
+                            </div>
+                        )}
                         {updateError && (
                             <div className="rounded-md border border-red-200 bg-red-50 px-3 py-2 text-xs text-red-700 dark:border-red-900/40 dark:bg-red-900/20 dark:text-red-200">
                                 {updateError}

src/constants/config.ts

@@ -3,3 +3,15 @@
  * Indicates if the app is running in Platform mode (hosted) or OSS mode (self-hosted)
  */
 export const IS_PLATFORM = import.meta.env.VITE_IS_PLATFORM === 'true';
+
+/**
+ * For empty shell instances where no project is provided, 
+ * we use a default project object to ensure the shell can still function. 
+ * This prevents errors related to missing project data.
+ */
+export const DEFAULT_PROJECT_FOR_EMPTY_SHELL = {
+  name: 'default',
+  displayName: 'default',
+  fullPath: IS_PLATFORM ? '/workspace' : '',
+  path: IS_PLATFORM ? '/workspace' : '',
+};

src/stores/useSessionStore.ts

@@ -8,7 +8,7 @@
  */
 
 import { useCallback, useMemo, useRef, useState } from 'react';
-import type { SessionProvider } from '../types/app';
+import type { LLMProvider } from '../types/app';
 import { authenticatedFetch } from '../utils/api';
 
 // ─── NormalizedMessage (mirrors server/adapters/types.js) ────────────────────
@@ -33,7 +33,7 @@ export interface NormalizedMessage {
   id: string;
   sessionId: string;
   timestamp: string;
-  provider: SessionProvider;
+  provider: LLMProvider;
   kind: MessageKind;
 
   // kind-specific fields (flat for simplicity)
@@ -169,7 +169,7 @@ export function useSessionStore() {
   const fetchFromServer = useCallback(async (
     sessionId: string,
     opts: {
-      provider?: SessionProvider;
+      provider?: LLMProvider;
       projectName?: string;
       projectPath?: string;
       limit?: number | null;
@@ -228,7 +228,7 @@ export function useSessionStore() {
   const fetchMore = useCallback(async (
     sessionId: string,
     opts: {
-      provider?: SessionProvider;
+      provider?: LLMProvider;
       projectName?: string;
       projectPath?: string;
       limit?: number;
@@ -303,7 +303,7 @@ export function useSessionStore() {
   const refreshFromServer = useCallback(async (
     sessionId: string,
     opts: {
-      provider?: SessionProvider;
+      provider?: LLMProvider;
       projectName?: string;
       projectPath?: string;
     } = {},
@@ -357,7 +357,7 @@ export function useSessionStore() {
    * Update or create a streaming message (accumulated text so far).
    * Uses a well-known ID so subsequent calls replace the same message.
    */
-  const updateStreaming = useCallback((sessionId: string, accumulatedText: string, msgProvider: SessionProvider) => {
+  const updateStreaming = useCallback((sessionId: string, accumulatedText: string, msgProvider: LLMProvider) => {
     const slot = getSlot(sessionId);
     const streamId = `__streaming_${sessionId}`;
     const msg: NormalizedMessage = {

src/types/app.ts

@@ -1,4 +1,4 @@
-export type SessionProvider = 'claude' | 'cursor' | 'codex' | 'gemini';
+export type LLMProvider = 'claude' | 'cursor' | 'codex' | 'gemini';
 
 export type AppTab = 'chat' | 'files' | 'shell' | 'git' | 'tasks' | 'preview' | `plugin:${string}`;
 
@@ -12,7 +12,7 @@ export interface ProjectSession {
   updated_at?: string;
   lastActivity?: string;
   messageCount?: number;
-  __provider?: SessionProvider;
+  __provider?: LLMProvider;
   __projectName?: string;
   [key: string]: unknown;
 }

tsconfig.json

@@ -4,6 +4,13 @@
     "useDefineForClassFields": true,
     "lib": ["ES2020", "DOM", "DOM.Iterable"],
     "module": "ESNext",
+    "baseUrl": ".",
+    "paths": {
+      // The frontend keeps "@" mapped to /src.
+      // The backend gets its own "@" mapping in server/tsconfig.json so both sides can use
+      // the same alias name without sharing one compiler configuration.
+      "@/*": ["src/*"]
+    },
     "skipLibCheck": true,
     "moduleResolution": "Bundler",
     "resolveJsonModule": true,
@@ -14,7 +21,8 @@
     "forceConsistentCasingInFileNames": true,
     "allowJs": true,
     // "checkJs": true, 
-    "types": ["vite/client"]
+    "types": ["vite/client"],
+    "ignoreDeprecations": "5.0"
   },
   "include": ["src", "shared", "vite.config.js"]
 }

vite.config.js

@@ -1,3 +1,4 @@
+import { fileURLToPath, URL } from 'node:url'
 import { defineConfig, loadEnv } from 'vite'
 import react from '@vitejs/plugin-react'
 import { getConnectableHost, normalizeLoopbackHost } from './shared/networkHosts.js'
@@ -19,6 +20,11 @@ export default defineConfig(({ mode }) => {
 
   return {
     plugins: [react()],
+    resolve: {
+      alias: {
+        '@': fileURLToPath(new URL('./src', import.meta.url))
+      }
+    },
     server: {
       host,
       port: parseInt(env.VITE_PORT) || 5173,