Merge branch 'main' into chore/update-claude-fallback-models

Users deploying behind a reverse proxy need a config they can adapt.

The template documents each proxy block and centralizes upstream/subpath values.

It also notes that Nginx location matchers still require literal subpath edits.

docs/nginx-subpath-template.conf

@@ -0,0 +1,218 @@
+# CloudCLI UI Nginx subpath deployment template.
+#
+# Purpose:
+#   Serve CloudCLI UI from a path prefix such as:
+#     http://localhost/ai/
+#     https://example.com/ai/
+#
+# CloudCLI itself still runs at the root of its own HTTP server, for example:
+#     http://127.0.0.1:3001/
+#
+# Nginx receives public requests under /ai, strips that prefix, and forwards the
+# remaining path to CloudCLI. For example:
+#     /ai/                  ->  /
+#     /ai/session/abc       ->  /session/abc
+#     /ai/assets/index.js   ->  /assets/index.js
+#
+# Important Nginx limitation:
+#   Nginx does not allow variables in `location` matchers or `rewrite` regexes.
+#   The configurable variables below are still useful for proxy/filter values,
+#   but if you change /ai to a different subpath, also update every line marked:
+#     [SUBPATH LITERAL]
+#
+# To use a different subpath, replace these literal matchers:
+#     location = /ai
+#     location ^~ /ai/
+#     rewrite ^/ai(?<cloudcli_path>/.*)$ ...
+#
+# Recommended deployment shape:
+#   CloudCLI is the only app using /ai, while root paths /api, /ws, and /shell
+#   are also proxied because the current frontend still calls those endpoints
+#   with root-relative URLs.
+
+worker_processes 1;
+
+events {
+    # Maximum simultaneous connections handled by each worker process.
+    # The default is enough for local testing and small self-hosted deployments.
+    worker_connections 1024;
+}
+
+http {
+    # WebSocket requests include an Upgrade header. Normal HTTP requests do not.
+    # This map gives us the right Connection header for both cases:
+    #   Upgrade present -> "upgrade"
+    #   Upgrade absent  -> "close"
+    map $http_upgrade $connection_upgrade {
+        default upgrade;
+        '' close;
+    }
+
+    server {
+        # For HTTPS deployments, replace this with `listen 443 ssl http2;` and
+        # add ssl_certificate / ssl_certificate_key lines.
+        listen 80 default_server;
+
+        # Use your real hostname in production, for example:
+        #   server_name cloudcli.example.com;
+        server_name localhost 127.0.0.1;
+
+        # ---- User settings -------------------------------------------------
+        #
+        # Public path prefix where users access CloudCLI.
+        # Do not add a trailing slash.
+        #
+        # This variable can be used in redirects and response rewrites. It
+        # cannot be used in `location` matchers, so update the [SUBPATH LITERAL]
+        # lines too if you change it.
+        set $cloudcli_subpath /ai;
+
+        # Private upstream URL where the CloudCLI server is listening.
+        # For a default local server this is usually http://127.0.0.1:3001.
+        set $cloudcli_upstream http://127.0.0.1:3001;
+
+        # Allow larger file uploads through the code editor/project file APIs.
+        client_max_body_size 100m;
+
+        # Redirect /ai to /ai/ so relative browser URL resolution is stable.
+        # [SUBPATH LITERAL] Change `/ai` if you change $cloudcli_subpath.
+        location = /ai {
+            return 301 $cloudcli_subpath/;
+        }
+
+        # Main prefixed CloudCLI UI route.
+        #
+        # [SUBPATH LITERAL] Change `/ai/` and the `^/ai` rewrite if you change
+        # $cloudcli_subpath.
+        location ^~ /ai/ {
+            # Strip the public subpath before proxying. CloudCLI expects to see
+            # root paths such as /, /session/:id, /assets/..., /manifest.json.
+            rewrite ^/ai(?<cloudcli_path>/.*)$ $cloudcli_path break;
+
+            # Forward the rewritten request to the private CloudCLI server.
+            proxy_pass $cloudcli_upstream;
+
+            # Use HTTP/1.1 so WebSocket upgrade requests can pass through if a
+            # browser reaches a socket endpoint under the subpath.
+            proxy_http_version 1.1;
+
+            # Preserve useful request metadata for logs and future app support.
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Prefix $cloudcli_subpath;
+
+            # WebSocket upgrade headers. Harmless for normal HTTP requests.
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection $connection_upgrade;
+
+            # Long-running agent and terminal sessions can stay open for a long
+            # time, so avoid closing idle proxied connections too aggressively.
+            proxy_read_timeout 3600s;
+            proxy_send_timeout 3600s;
+
+            # Disable gzip from the upstream response so sub_filter can inspect
+            # and rewrite HTML/JSON/JS response bodies.
+            proxy_set_header Accept-Encoding "";
+
+            # Rewrite browser-visible root-relative URLs so the runtime can
+            # discover that the app is mounted under the subpath.
+            #
+            # Examples:
+            #   href="/manifest.json" -> href="/ai/manifest.json"
+            #   src="/assets/app.js"  -> src="/ai/assets/app.js"
+            #
+            # These rewrites are important for React Router basename detection.
+            sub_filter_once off;
+            sub_filter_types
+                application/json
+                application/manifest+json
+                application/javascript
+                text/javascript;
+
+            sub_filter 'href="/' 'href="$cloudcli_subpath/';
+            sub_filter 'src="/' 'src="$cloudcli_subpath/';
+
+            # The production HTML and JS register the service worker at /sw.js.
+            # Rewrite that registration so the worker is served from /ai/sw.js.
+            sub_filter "register('/sw.js')" "register('$cloudcli_subpath/sw.js')";
+            sub_filter 'register("/sw.js")' 'register("$cloudcli_subpath/sw.js")';
+
+            # The manifest and service worker contain root-relative paths too.
+            # Rewriting them keeps PWA metadata and cached manifest requests
+            # under the same public subpath.
+            sub_filter '"start_url": "/"' '"start_url": "$cloudcli_subpath/"';
+            sub_filter '"scope": "/"' '"scope": "$cloudcli_subpath/"';
+            sub_filter '"src": "/' '"src": "$cloudcli_subpath/';
+            sub_filter "'/manifest.json'" "'$cloudcli_subpath/manifest.json'";
+            sub_filter '"/manifest.json"' '"$cloudcli_subpath/manifest.json"';
+        }
+
+        # Root API proxy.
+        #
+        # The current CloudCLI frontend calls APIs with root-relative URLs such
+        # as /api/auth/login. Keep this location unless the frontend becomes
+        # fully prefix-aware for API requests.
+        location ^~ /api/ {
+            proxy_pass $cloudcli_upstream;
+
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Prefix $cloudcli_subpath;
+
+            proxy_read_timeout 3600s;
+            proxy_send_timeout 3600s;
+        }
+
+        # Main app WebSocket proxy.
+        #
+        # The frontend opens /ws for realtime chat/session/task updates.
+        location /ws {
+            proxy_pass $cloudcli_upstream;
+
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection $connection_upgrade;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Prefix $cloudcli_subpath;
+
+            proxy_read_timeout 3600s;
+            proxy_send_timeout 3600s;
+        }
+
+        # Shell WebSocket proxy.
+        #
+        # The browser terminal uses /shell. It requires the same WebSocket
+        # upgrade handling as /ws.
+        location /shell {
+            proxy_pass $cloudcli_upstream;
+
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection $connection_upgrade;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Prefix $cloudcli_subpath;
+
+            proxy_read_timeout 3600s;
+            proxy_send_timeout 3600s;
+        }
+
+        # Optional health endpoint proxy used by the frontend version checker.
+        location = /health {
+            proxy_pass $cloudcli_upstream;
+
+            proxy_set_header Host $host;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-Prefix $cloudcli_subpath;
+        }
+    }
+}

public/modelConstants.js

@@ -11,7 +11,8 @@ export const CLAUDE_MODELS = {
     {
       value: "default",
       label: "Default (recommended)",
-      description: "Use the default model (currently Opus 4.8 (1M context)) · $5/$25 per Mtok",
+      description:
+        "Use the default model (currently Opus 4.8 (1M context)) · $5/$25 per Mtok",
     },
     {
       value: "sonnet",
@@ -23,6 +24,12 @@ export const CLAUDE_MODELS = {
       label: "Sonnet (1M context)",
       description: "Sonnet 4.6 for long sessions · $3/$15 per Mtok",
     },
+    {
+      value: "opus[1m]",
+      label: "Opus 4.8 (1M context)",
+      description:
+        "Opus 4.8 with 1M context · Most capable for complex work · $5/$25 per Mtok",
+    },
     {
       value: "haiku",
       label: "Haiku",

server/index.js

@@ -1483,74 +1483,133 @@ function permToRwx(perm) {
     return r + w + x;
 }
 
+// Directories that are almost never interesting for a project tree but can
+// contain tens of thousands of files. Skipping them before recursion keeps
+// traversal time bounded on large monorepos and high-latency filesystems
+// (NFS / SMB).
+const IGNORED_DIRS = new Set([
+    // JS / TS toolchains
+    'node_modules', 'dist', 'build', '.next', '.nuxt', '.cache', '.parcel-cache',
+    // VCS
+    '.git', '.svn', '.hg',
+    // Python
+    '__pycache__', '.pytest_cache', '.mypy_cache', '.tox', 'venv', '.venv',
+    // Rust / Go / Java / Ruby
+    'target', 'vendor',
+    // Build output / IDE
+    '.gradle', '.idea', 'coverage', '.nyc_output'
+]);
+
+const DEFAULT_FS_CONCURRENCY = 64;
+const parsedFsConcurrency = Number.parseInt(process.env.FS_CONCURRENCY || '', 10);
+const FS_CONCURRENCY = Number.isFinite(parsedFsConcurrency) && parsedFsConcurrency > 0
+    ? parsedFsConcurrency
+    : DEFAULT_FS_CONCURRENCY;
+let activeFsOperations = 0;
+const pendingFsOperations = [];
+
+async function acquire() {
+    if (activeFsOperations < FS_CONCURRENCY) {
+        activeFsOperations += 1;
+        return;
+    }
+
+    await new Promise((resolve) => {
+        pendingFsOperations.push(resolve);
+    });
+}
+
+function release() {
+    const next = pendingFsOperations.shift();
+    if (next) {
+        next();
+        return;
+    }
+
+    activeFsOperations = Math.max(0, activeFsOperations - 1);
+}
+
 async function getFileTree(dirPath, maxDepth = 3, currentDepth = 0, showHidden = true) {
     // Using fsPromises from import
-    const items = [];
-
+    let entries;
     try {
-        const entries = await fsPromises.readdir(dirPath, { withFileTypes: true });
-
-        for (const entry of entries) {
-            // Debug: log all entries including hidden files
-
-
-            // Skip heavy build directories and VCS directories
-            if (entry.name === 'node_modules' ||
-                entry.name === 'dist' ||
-                entry.name === 'build' ||
-                entry.name === '.git' ||
-                entry.name === '.svn' ||
-                entry.name === '.hg') continue;
-
-            const itemPath = path.join(dirPath, entry.name);
-            const item = {
-                name: entry.name,
-                path: itemPath,
-                type: entry.isDirectory() ? 'directory' : 'file'
-            };
-
-            // Get file stats for additional metadata
-            try {
-                const stats = await fsPromises.stat(itemPath);
-                item.size = stats.size;
-                item.modified = stats.mtime.toISOString();
-
-                // Convert permissions to rwx format
-                const mode = stats.mode;
-                const ownerPerm = (mode >> 6) & 7;
-                const groupPerm = (mode >> 3) & 7;
-                const otherPerm = mode & 7;
-                item.permissions = ((mode >> 6) & 7).toString() + ((mode >> 3) & 7).toString() + (mode & 7).toString();
-                item.permissionsRwx = permToRwx(ownerPerm) + permToRwx(groupPerm) + permToRwx(otherPerm);
-            } catch (statError) {
-                // If stat fails, provide default values
-                item.size = 0;
-                item.modified = null;
-                item.permissions = '000';
-                item.permissionsRwx = '---------';
-            }
-
-            if (entry.isDirectory() && currentDepth < maxDepth) {
-                // Recursively get subdirectories but limit depth
-                try {
-                    // Check if we can access the directory before trying to read it
-                    await fsPromises.access(item.path, fs.constants.R_OK);
-                    item.children = await getFileTree(item.path, maxDepth, currentDepth + 1, showHidden);
-                } catch (e) {
-                    // Silently skip directories we can't access (permission denied, etc.)
-                    item.children = [];
-                }
-            }
-
-            items.push(item);
+        await acquire();
+        try {
+            entries = await fsPromises.readdir(dirPath, { withFileTypes: true });
+        } finally {
+            release();
         }
     } catch (error) {
         // Only log non-permission errors to avoid spam
         if (error.code !== 'EACCES' && error.code !== 'EPERM') {
             console.error('Error reading directory:', error);
         }
+        return [];
     }
 
+    const filteredEntries = entries.filter((entry) => !(entry.isDirectory() && IGNORED_DIRS.has(entry.name)));
+
+    // Process every entry in parallel. On high-latency filesystems (NFS/SMB)
+    // serial stat() was the real bottleneck — issuing them concurrently lets
+    // the kernel pipeline the round-trips and the recursive calls overlap too.
+    const items = await Promise.all(filteredEntries.map(async (entry) => {
+        const itemPath = path.join(dirPath, entry.name);
+        const item = {
+            name: entry.name,
+            path: itemPath,
+            type: entry.isDirectory() ? 'directory' : 'file'
+        };
+
+        // Get file stats for additional metadata
+        try {
+            await acquire();
+            try {
+              const stats = await fsPromises.lstat(itemPath);
+              item.size = stats.size;
+              item.modified = stats.mtime.toISOString();
+
+              // Mark symlinks so UI can distinguish them
+              if (stats.isSymbolicLink()) {
+                item.isSymlink = true;
+              }
+
+              // Convert permissions to rwx format
+              const mode = stats.mode;
+              const ownerPerm = (mode >> 6) & 7;
+              const groupPerm = (mode >> 3) & 7;
+              const otherPerm = mode & 7;
+              item.permissions =
+                ((mode >> 6) & 7).toString() +
+                ((mode >> 3) & 7).toString() +
+                (mode & 7).toString();
+              item.permissionsRwx =
+                permToRwx(ownerPerm) +
+                permToRwx(groupPerm) +
+                permToRwx(otherPerm);
+            } finally {
+                release();
+            }
+        } catch (statError) {
+            // If stat fails, provide default values
+            item.size = 0;
+            item.modified = null;
+            item.permissions = '000';
+            item.permissionsRwx = '---------';
+        }
+
+        if (entry.isDirectory() && currentDepth < maxDepth) {
+            // Recurse. Let readdir's own EACCES bubble up through the catch in
+            // the recursive call rather than doing a separate access() probe
+            // (which doubled the round-trip count on SMB without adding info).
+            // The recursive call starts with a bounded readdir; holding a permit
+            // for the whole subtree can deadlock when sibling directories are
+            // waiting on their own children.
+            item.children = await getFileTree(itemPath, maxDepth, currentDepth + 1, showHidden);
+        }
+
+        return item;
+    }));
+
     return items.sort((a, b) => {
         if (a.type !== b.type) {
             return a.type === 'directory' ? -1 : 1;

server/modules/providers/list/claude/claude-models.provider.ts

@@ -18,18 +18,23 @@ export const CLAUDE_FALLBACK_MODELS: ProviderModelsDefinition = {
     {
       value: 'default',
       label: 'Default (recommended)',
-      description: 'Use the default model (currently Opus 4.7 (1M context)) · $5/$25 per Mtok',
+      description: 'Use the default model (currently Opus 4.8 (1M context)) · $5/$25 per Mtok',
     },
     {
-      value: 'sonnet',
-      label: 'Sonnet',
-      description: 'Sonnet 4.6 · Best for everyday tasks · $3/$15 per Mtok',
+      value: "sonnet",
+      label: "Sonnet",
+      description: "Sonnet 4.6 · Best for everyday tasks · $3/$15 per Mtok",
     },
     {
       value: 'sonnet[1m]',
       label: 'Sonnet (1M context)',
       description: 'Sonnet 4.6 for long sessions · $3/$15 per Mtok',
     },
+    {
+      value: 'opus[1m]',
+      label: 'Opus 4.8 (1M context)',
+      description: 'Opus 4.8 with 1M context · Most capable for complex work · $5/$25 per Mtok',
+    },
     {
       value: 'haiku',
       label: 'Haiku',

server/modules/providers/services/provider-models.service.ts

@@ -17,6 +17,7 @@ import { readProviderSessionActiveModelChange } from '@/shared/utils.js';
 
 export const PROVIDER_MODELS_CACHE_TTL_MS = 3 * 24 * 60 * 60 * 1000;
 const PROVIDER_MODELS_CACHE_VERSION = 1;
+const UNCACHED_PROVIDERS = new Set<LLMProvider>(['claude']);
 
 type ProviderModelsServiceDependencies = {
   resolveProvider?: (provider: LLMProvider) => Pick<IProvider, 'models'>;
@@ -232,10 +233,42 @@ export const createProviderModelsService = (dependencies: ProviderModelsServiceD
     return request;
   };
 
+  const loadDirectModels = (
+    provider: LLMProvider,
+  ): Promise<ProviderModelsResult> => {
+    const request = resolveProvider(provider).models.getSupportedModels()
+      .then((models) => {
+        const currentTime = now();
+        return {
+          models,
+          cache: {
+            updatedAt: new Date(currentTime).toISOString(),
+            expiresAt: new Date(currentTime).toISOString(),
+            source: 'fresh' as const,
+          },
+        };
+      })
+      .finally(() => {
+        pendingRequests.delete(provider);
+      });
+
+    pendingRequests.set(provider, request);
+    return request;
+  };
+
   const getProviderModels = async (
     provider: LLMProvider,
     options: ProviderModelsOptions = {},
   ): Promise<ProviderModelsResult> => {
+    if (UNCACHED_PROVIDERS.has(provider)) {
+      const pendingRequest = pendingRequests.get(provider);
+      if (pendingRequest) {
+        return pendingRequest;
+      }
+
+      return loadDirectModels(provider);
+    }
+
     if (options.bypassCache) {
       const pendingRequest = pendingRequests.get(provider);
       if (pendingRequest) {

server/modules/providers/tests/provider-models.service.test.ts

@@ -130,6 +130,37 @@ test('provider models are cached for the three-day ttl', async () => {
   }
 });
 
+test('claude provider models are always loaded directly from the provider', async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'provider-model-cache-claude-direct-'));
+  let loadCount = 0;
+
+  try {
+    const service = createProviderModelsService({
+      cachePath: path.join(tempRoot, 'models-cache.json'),
+      resolveProvider: (provider) => ({
+        models: {
+          getSupportedModels: async () => {
+            loadCount += 1;
+            return createModels(`${provider}-${loadCount}`);
+          },
+          getCurrentActiveModel: async () => createCurrentActiveModel(`${provider}-active`),
+          changeActiveModel: async (input) => createSessionActiveModelChange(provider, input),
+        },
+      }),
+    });
+
+    const first = await service.getProviderModels('claude');
+    const second = await service.getProviderModels('claude');
+
+    assert.equal(loadCount, 2);
+    assert.equal(first.models.DEFAULT, 'claude-1');
+    assert.equal(second.models.DEFAULT, 'claude-2');
+    assert.equal(second.cache.source, 'fresh');
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+});
+
 test('provider model cache is persisted across service instances', async () => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'provider-model-cache-file-'));
   const cachePath = path.join(tempRoot, 'models-cache.json');

server/modules/websocket/services/shell-websocket.service.ts

@@ -18,6 +18,7 @@ type ShellIncomingMessage = {
   provider?: string;
   initialCommand?: string;
   isPlainShell?: boolean;
+  forceRestart?: boolean;
 };
 
 type PtySessionEntry = {
@@ -180,6 +181,7 @@ export function handleShellConnection(
         const hasSession = readBoolean(data.hasSession);
         const provider = readString(data.provider, 'claude');
         const initialCommand = readString(data.initialCommand);
+        const forceRestart = readBoolean(data.forceRestart);
         const isPlainShell =
           readBoolean(data.isPlainShell) ||
           (!!initialCommand && !hasSession) ||
@@ -200,7 +202,7 @@ export function handleShellConnection(
             : '';
         ptySessionKey = `${projectPath}_${sessionId ?? 'default'}${commandSuffix}`;
 
-        if (isLoginCommand) {
+        if (isLoginCommand || forceRestart) {
           const oldSession = ptySessionsMap.get(ptySessionKey);
           if (oldSession) {
             if (oldSession.timeoutId) {
@@ -211,7 +213,8 @@ export function handleShellConnection(
           }
         }
 
-        const existingSession = isLoginCommand ? null : ptySessionsMap.get(ptySessionKey);
+        const existingSession =
+          isLoginCommand || forceRestart ? null : ptySessionsMap.get(ptySessionKey);
         if (existingSession) {
           shellProcess = existingSession.pty;
           if (existingSession.timeoutId) {
@@ -368,6 +371,10 @@ export function handleShellConnection(
           }
 
           const session = ptySessionsMap.get(ptySessionKey);
+          if (session && session.pty !== shellProcess) {
+            return;
+          }
+
           if (session && session.ws && session.ws.readyState === WebSocket.OPEN) {
             session.ws.send(
               JSON.stringify({
@@ -451,6 +458,10 @@ export function handleShellConnection(
 
     session.ws = null;
     session.timeoutId = setTimeout(() => {
+      if (ptySessionsMap.get(ptySessionKey as string) !== session) {
+        return;
+      }
+
       session.pty.kill();
       ptySessionsMap.delete(ptySessionKey as string);
     }, PTY_SESSION_TIMEOUT);

server/modules/websocket/services/websocket-auth.service.ts

@@ -20,7 +20,13 @@ export function verifyWebSocketClient(
   dependencies: WebSocketAuthDependencies
 ): boolean {
   const request = info.req as AuthenticatedWebSocketRequest;
-  console.log('WebSocket connection attempt to:', request.url);
+  const upgradeUrl = new URL(request.url ?? '/', 'http://localhost');
+  const loggedUrl = new URL(upgradeUrl);
+  if (loggedUrl.searchParams.has('token')) {
+    loggedUrl.searchParams.set('token', 'REDACTED');
+  }
+
+  console.log('WebSocket connection attempt to:', `${loggedUrl.pathname}${loggedUrl.search}`);
 
   // Platform mode: use the first DB user and skip token checks.
   if (dependencies.isPlatform) {
@@ -36,7 +42,6 @@ export function verifyWebSocketClient(
   }
 
   // OSS mode: read JWT from query string first, then Authorization header.
-  const upgradeUrl = new URL(request.url ?? '/', 'http://localhost');
   const token =
     upgradeUrl.searchParams.get('token') ??
     request.headers.authorization?.split(' ')[1] ??

src/components/shell/hooks/useShellConnection.ts

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import type { MutableRefObject } from 'react';
 import type { FitAddon } from '@xterm/addon-fit';
 import type { Terminal } from '@xterm/xterm';
+
 import type { Project, ProjectSession } from '../../../types/app';
 import { TERMINAL_INIT_DELAY_MS } from '../constants/constants';
 import { getShellWebSocketUrl, parseShellMessage, sendSocketMessage } from '../utils/socket';
@@ -31,8 +32,8 @@ type UseShellConnectionResult = {
   isConnected: boolean;
   isConnecting: boolean;
   closeSocket: () => void;
-  connectToShell: () => void;
-  disconnectFromShell: () => void;
+  connectToShell: (options?: { forceRestart?: boolean }) => void;
+  disconnectFromShell: (options?: { suppressAutoConnect?: boolean }) => void;
 };
 
 export function useShellConnection({
@@ -54,6 +55,8 @@ export function useShellConnection({
   const [isConnected, setIsConnected] = useState(false);
   const [isConnecting, setIsConnecting] = useState(false);
   const connectingRef = useRef(false);
+  const forceRestartOnInitRef = useRef(false);
+  const suppressAutoConnectRef = useRef(false);
 
   const handleProcessCompletion = useCallback(
     (output: string) => {
@@ -141,6 +144,8 @@ export function useShellConnection({
             }
 
             currentFitAddon.fit();
+            const forceRestart = forceRestartOnInitRef.current;
+            forceRestartOnInitRef.current = false;
 
             sendSocketMessage(socket, {
               type: 'init',
@@ -152,6 +157,7 @@ export function useShellConnection({
               rows: currentTerminal.rows,
               initialCommand: initialCommandRef.current,
               isPlainShell: isPlainShellRef.current,
+              forceRestart,
             });
           }, TERMINAL_INIT_DELAY_MS);
         };
@@ -177,6 +183,7 @@ export function useShellConnection({
         setIsConnected(false);
         setIsConnecting(false);
         connectingRef.current = false;
+        forceRestartOnInitRef.current = false;
       }
     },
     [
@@ -195,27 +202,40 @@ export function useShellConnection({
     ],
   );
 
-  const connectToShell = useCallback(() => {
+  const connectToShell = useCallback((options?: { forceRestart?: boolean }) => {
     if (!isInitialized || isConnected || isConnecting || connectingRef.current) {
       return;
     }
 
+    forceRestartOnInitRef.current = Boolean(options?.forceRestart);
+    suppressAutoConnectRef.current = false;
     connectingRef.current = true;
     setIsConnecting(true);
     connectWebSocket(true);
   }, [connectWebSocket, isConnected, isConnecting, isInitialized]);
 
-  const disconnectFromShell = useCallback(() => {
+  const disconnectFromShell = useCallback((options?: { suppressAutoConnect?: boolean }) => {
+    if (options?.suppressAutoConnect) {
+      suppressAutoConnectRef.current = true;
+    }
+
     closeSocket();
     clearTerminalScreen();
     setIsConnected(false);
     setIsConnecting(false);
     connectingRef.current = false;
+    forceRestartOnInitRef.current = false;
     setAuthUrl('');
   }, [clearTerminalScreen, closeSocket, setAuthUrl]);
 
   useEffect(() => {
-    if (!autoConnect || !isInitialized || isConnecting || isConnected) {
+    if (
+      !autoConnect ||
+      suppressAutoConnectRef.current ||
+      !isInitialized ||
+      isConnecting ||
+      isConnected
+    ) {
       return;
     }
 

src/components/shell/types/types.ts

@@ -1,6 +1,7 @@
 import type { MutableRefObject, RefObject } from 'react';
 import type { FitAddon } from '@xterm/addon-fit';
 import type { Terminal } from '@xterm/xterm';
+
 import type { Project, ProjectSession } from '../../../types/app';
 
 export type AuthCopyStatus = 'idle' | 'copied' | 'failed';
@@ -15,6 +16,7 @@ export type ShellInitMessage = {
   rows: number;
   initialCommand: string | null | undefined;
   isPlainShell: boolean;
+  forceRestart?: boolean;
 };
 
 export type ShellResizeMessage = {
@@ -69,8 +71,8 @@ export type UseShellRuntimeResult = {
   isConnecting: boolean;
   authUrl: string;
   authUrlVersion: number;
-  connectToShell: () => void;
-  disconnectFromShell: () => void;
+  connectToShell: (options?: { forceRestart?: boolean }) => void;
+  disconnectFromShell: (options?: { suppressAutoConnect?: boolean }) => void;
   openAuthUrlInBrowser: (url?: string) => boolean;
   copyAuthUrlToClipboard: (url?: string) => Promise<boolean>;
 };

src/components/shell/view/Shell.tsx

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
+
 import '@xterm/xterm/css/xterm.css';
 import type { Project, ProjectSession } from '../../../types/app';
 import {
@@ -13,6 +14,7 @@ import {
 import { useShellRuntime } from '../hooks/useShellRuntime';
 import { sendSocketMessage } from '../utils/socket';
 import { getSessionDisplayName } from '../utils/auth';
+
 import ShellConnectionOverlay from './subcomponents/ShellConnectionOverlay';
 import ShellEmptyState from './subcomponents/ShellEmptyState';
 import ShellHeader from './subcomponents/ShellHeader';
@@ -46,6 +48,8 @@ export default function Shell({
   const [isRestarting, setIsRestarting] = useState(false);
   const [cliPromptOptions, setCliPromptOptions] = useState<CliPromptOption[] | null>(null);
   const promptCheckTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const restartTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const restartAfterInitRef = useRef(false);
   const onOutputRef = useRef<(() => void) | null>(null);
 
   const {
@@ -140,6 +144,7 @@ export default function Shell({
   useEffect(() => {
     return () => {
       if (promptCheckTimer.current) clearTimeout(promptCheckTimer.current);
+      if (restartTimerRef.current) clearTimeout(restartTimerRef.current);
     };
   }, []);
 
@@ -190,12 +195,42 @@ export default function Shell({
   );
 
   const handleRestartShell = useCallback(() => {
+    restartAfterInitRef.current = true;
     setIsRestarting(true);
-    window.setTimeout(() => {
+    if (restartTimerRef.current) {
+      clearTimeout(restartTimerRef.current);
+    }
+    restartTimerRef.current = setTimeout(() => {
       setIsRestarting(false);
+      restartTimerRef.current = null;
     }, SHELL_RESTART_DELAY_MS);
   }, []);
 
+  const handleDisconnectShell = useCallback(() => {
+    restartAfterInitRef.current = false;
+    if (restartTimerRef.current) {
+      clearTimeout(restartTimerRef.current);
+      restartTimerRef.current = null;
+    }
+    setIsRestarting(false);
+    disconnectFromShell({ suppressAutoConnect: true });
+  }, [disconnectFromShell]);
+
+  useEffect(() => {
+    if (
+      !restartAfterInitRef.current ||
+      isRestarting ||
+      !isInitialized ||
+      isConnected ||
+      isConnecting
+    ) {
+      return;
+    }
+
+    restartAfterInitRef.current = false;
+    connectToShell({ forceRestart: true });
+  }, [connectToShell, isConnected, isConnecting, isInitialized, isRestarting]);
+
   if (!selectedProject) {
     return (
       <ShellEmptyState
@@ -254,7 +289,7 @@ export default function Shell({
         isRestarting={isRestarting}
         hasSession={Boolean(selectedSession)}
         sessionDisplayNameShort={sessionDisplayNameShort}
-        onDisconnect={disconnectFromShell}
+        onDisconnect={handleDisconnectShell}
         onRestart={handleRestartShell}
         statusNewSessionText={t('shell.status.newSession')}
         statusInitializingText={t('shell.status.initializing')}
@@ -263,7 +298,7 @@ export default function Shell({
         disconnectTitle={t('shell.actions.disconnectTitle')}
         restartLabel={t('shell.actions.restart')}
         restartTitle={t('shell.actions.restartTitle')}
-        disableRestart={isRestarting || isConnected}
+        disableRestart={isRestarting || !isInitialized}
       />
 
       <div className="relative flex-1 overflow-hidden p-2">
@@ -281,7 +316,7 @@ export default function Shell({
             connectLabel={t('shell.actions.connect')}
             connectTitle={t('shell.actions.connectTitle')}
             connectingLabel={t('shell.connecting')}
-            onConnect={connectToShell}
+            onConnect={handleRestartShell}
           />
         )}
 

src/components/shell/view/subcomponents/ShellConnectionOverlay.tsx

@@ -1,3 +1,5 @@
+import { Loader2, RotateCcw } from 'lucide-react';
+
 type ShellConnectionOverlayProps = {
   mode: 'loading' | 'connect' | 'connecting';
   description: string;
@@ -19,40 +21,42 @@ export default function ShellConnectionOverlay({
 }: ShellConnectionOverlayProps) {
   if (mode === 'loading') {
     return (
-      <div className="absolute inset-0 flex items-center justify-center bg-gray-900 bg-opacity-90">
-        <div className="text-white">{loadingLabel}</div>
+      <div className="absolute inset-0 z-20 flex items-center justify-center bg-gray-950/90">
+        <div className="inline-flex items-center gap-2 text-sm font-medium text-gray-100">
+          <Loader2 className="h-4 w-4 animate-spin text-blue-300" aria-hidden="true" />
+          <span>{loadingLabel}</span>
+        </div>
       </div>
     );
   }
 
   if (mode === 'connect') {
     return (
-      <div className="absolute inset-0 flex items-center justify-center bg-gray-900 bg-opacity-90 p-4">
-        <div className="w-full max-w-sm text-center">
+      <div className="absolute inset-0 z-20 flex items-center justify-center bg-gray-950/90 p-6">
+        <div className="flex w-full max-w-md flex-col items-center gap-3 text-center">
           <button
+            type="button"
             onClick={onConnect}
-            className="flex w-full items-center justify-center space-x-2 rounded-lg bg-green-600 px-6 py-3 text-base font-medium text-white transition-colors hover:bg-green-700 sm:w-auto"
+            className="pointer-events-auto inline-flex min-h-12 w-full max-w-xs cursor-pointer items-center justify-center gap-2 rounded-md bg-emerald-600 px-5 py-3 text-base font-semibold text-white shadow-lg shadow-emerald-950/30 transition-colors hover:bg-emerald-500 focus:outline-none focus:ring-2 focus:ring-emerald-300 focus:ring-offset-2 focus:ring-offset-gray-950 active:bg-emerald-700"
             title={connectTitle}
           >
-            <svg className="h-5 w-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 10V3L4 14h7v7l9-11h-7z" />
-            </svg>
-            <span>{connectLabel}</span>
+            <RotateCcw className="h-4 w-4" aria-hidden="true" />
+            <span className="min-w-0 truncate">{connectLabel}</span>
           </button>
-          <p className="mt-3 px-2 text-sm text-gray-400">{description}</p>
+          <p className="max-w-md break-words px-2 text-sm leading-6 text-gray-300">{description}</p>
         </div>
       </div>
     );
   }
 
   return (
-    <div className="absolute inset-0 flex items-center justify-center bg-gray-900 bg-opacity-90 p-4">
-      <div className="w-full max-w-sm text-center">
-        <div className="flex items-center justify-center space-x-3 text-yellow-400">
-          <div className="h-6 w-6 animate-spin rounded-full border-2 border-yellow-400 border-t-transparent"></div>
+    <div className="absolute inset-0 z-20 flex items-center justify-center bg-gray-950/90 p-6">
+      <div className="flex w-full max-w-md flex-col items-center gap-3 text-center">
+        <div className="flex items-center justify-center gap-3 text-yellow-300">
+          <Loader2 className="h-5 w-5 animate-spin" aria-hidden="true" />
           <span className="text-base font-medium">{connectingLabel}</span>
         </div>
-        <p className="mt-3 px-2 text-sm text-gray-400">{description}</p>
+        <p className="max-w-md break-words px-2 text-sm leading-6 text-gray-300">{description}</p>
       </div>
     </div>
   );

src/components/shell/view/subcomponents/ShellHeader.tsx

@@ -1,3 +1,5 @@
+import { RotateCcw, X } from 'lucide-react';
+
 type ShellHeaderProps = {
   isConnected: boolean;
   isInitialized: boolean;
@@ -50,34 +52,27 @@ export default function ShellHeader({
           {isRestarting && <span className="text-xs text-blue-400">{statusRestartingText}</span>}
         </div>
 
-        <div className="flex items-center space-x-3">
+        <div className="flex items-center gap-2">
           {isConnected && (
             <button
+              type="button"
               onClick={onDisconnect}
-              className="flex items-center space-x-1 rounded bg-red-600 px-3 py-1 text-xs text-white hover:bg-red-700"
+              className="inline-flex h-8 items-center gap-1.5 rounded-md bg-red-600 px-3 text-xs font-medium text-white transition-colors hover:bg-red-700 focus:outline-none focus:ring-2 focus:ring-red-400/70 focus:ring-offset-2 focus:ring-offset-gray-800"
               title={disconnectTitle}
             >
-              <svg className="h-3 w-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M6 18L18 6M6 6l12 12" />
-              </svg>
+              <X className="h-3.5 w-3.5" aria-hidden="true" />
               <span>{disconnectLabel}</span>
             </button>
           )}
 
           <button
+            type="button"
             onClick={onRestart}
             disabled={disableRestart}
-            className="flex items-center space-x-1 text-xs text-gray-400 hover:text-white disabled:cursor-not-allowed disabled:opacity-50"
+            className="inline-flex h-8 items-center gap-1.5 rounded-md border border-gray-600/80 bg-gray-700/70 px-3 text-xs font-medium text-gray-100 transition-colors hover:border-blue-400/70 hover:bg-blue-600/80 hover:text-white focus:outline-none focus:ring-2 focus:ring-blue-400/70 focus:ring-offset-2 focus:ring-offset-gray-800 disabled:cursor-not-allowed disabled:border-transparent disabled:bg-transparent disabled:text-gray-500 disabled:opacity-60"
             title={restartTitle}
           >
-            <svg className="h-3 w-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-              <path
-                strokeLinecap="round"
-                strokeLinejoin="round"
-                strokeWidth={2}
-                d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15"
-              />
-            </svg>
+            <RotateCcw className={`h-3.5 w-3.5 ${isRestarting ? 'animate-spin' : ''}`} aria-hidden="true" />
             <span>{restartLabel}</span>
           </button>
         </div>

src/i18n/locales/en/chat.json

@@ -229,7 +229,7 @@
       "disconnect": "Disconnect",
       "disconnectTitle": "Disconnect from shell",
       "restart": "Restart",
-      "restartTitle": "Restart Shell (disconnect first)",
+      "restartTitle": "Restart Shell",
       "connect": "Continue in Shell",
       "connectTitle": "Connect to shell"
     },