Enforce single active GUI connection with proper race condition handling

- Add async locking mechanism to prevent race conditions during connection setup
- Wait for existing connection setup to complete before accepting new connection
- Remove event listeners from old connection before closing to prevent interference
- Add timeout failsafe (2 seconds) to prevent deadlocks
- Frontend detects "Replaced by new connection" and shows appropriate message
- No reconnection attempts when connection is explicitly replaced
- Update CLAUDE.md with single-connection behavior documentation
- Bump version to 1.1.5

Fixes issue where multiple tabs could remain connected simultaneously due to race conditions.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: anatoly314

CLAUDE.md

@@ -140,11 +140,17 @@ This is a **pnpm workspaces + Turborepo** monorepo (converted from standalone ap
 - WebSocket auto-detects URL from browser (supports both direct access and nginx proxy)
   - Auto-detection: `ws://localhost:5173/remote-control` (dev) or `ws://localhost:8080/remote-control` (Docker)
   - Protocol switches to `wss://` for HTTPS connections
+- **Single Active Connection**: Only one GUI can control the diagram at a time
+  - When a new GUI connects, the previous connection is gracefully closed
+  - Old GUI shows "AI Assistant disconnected - connection taken over by another tab/window"
+  - Prevents confusion from multiple tabs trying to control the same backend
 - Commands are handled by contexts (`DiagramContext`, `AreasContext`, `NotesContext`, etc.)
 - Automatic reconnection with exponential backoff (max 10 attempts, up to 30s delay with jitter)
-- Connection status displayed via Toast notifications ("AI Assistant connected/disconnected")
+  - Exception: Won't reconnect if connection was replaced by another session
+- Connection status displayed via Toast notifications and persistent status badge
 - All commands processed through `useRemoteControl.js:152` switch statement
 - Command timeout: 30 seconds (configured in `DrawDBClientService:15`)
+- Heartbeat: Frontend sends ping every 30 seconds to keep connection alive
 
 ### Backend (apps/backend)
 
@@ -402,6 +408,8 @@ function MyComponent() {
 
 - **WebSocket connection fails**: Check that `VITE_REMOTE_CONTROL_ENABLED=true` and backend is running
 - **MCP tools timeout**: Default timeout is 30s (configured in `DrawDBClientService:15`)
+- **Multiple tabs/windows**: Only one GUI can be connected at a time. Opening a new tab will disconnect the previous one with message "connection taken over by another tab/window"
+- **Connection replaced**: If you see "connection taken over", another tab/window is now active. Close it or refresh this tab to reconnect
 - **Docker nginx issues**: Nginx runs as non-root user `nodejs:nodejs`, requires proper permissions
 - **Build failures**: Run `pnpm clean` then `pnpm install` to reset
 - **Turborepo cache issues**: Delete `.turbo` directory to clear cache
@@ -431,7 +439,7 @@ function MyComponent() {
 
 ### Version Management
 
-- Backend version: `apps/backend/package.json` (currently 1.1.4)
+- Backend version: `apps/backend/package.json` (currently 1.1.5)
 - GUI version: `apps/gui/package.json` (currently 1.0.0)
 - Root package: `package.json` (workspace root, 1.0.0)
 

apps/backend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Model Context Protocol server for DrawDB - enables AI assistants to create and modify database diagrams via WebSocket",
   "author": "Anatoly Tarnavsky",
   "private": true,

apps/backend/src/drawdb/drawdb-client.service.ts

@@ -8,6 +8,7 @@ import { DrawDBCommand, DrawDBResponse } from './drawdb.types';
 export class DrawDBClientService {
   private readonly logger = new Logger(DrawDBClientService.name);
   private ws: any = null;
+  private isSettingConnection = false; // Lock to prevent race conditions
   private pendingRequests = new Map<
     string,
     { resolve: (value: any) => void; reject: (error: Error) => void; timeout: NodeJS.Timeout }
@@ -16,42 +17,93 @@ export class DrawDBClientService {
 
   /**
    * Set the WebSocket connection
+   * Closes any existing connection to ensure only one GUI is active at a time
+   * Uses a lock to prevent race conditions from simultaneous connections
    */
-  setConnection(ws: any) {
-    this.ws = ws;
-    this.logger.log('DrawDB client connected');
+  async setConnection(ws: any) {
+    // Wait if another connection is being set up (prevents race condition)
+    let waitCount = 0;
+    while (this.isSettingConnection && waitCount < 20) {
+      // Wait max 2 seconds (20 * 100ms)
+      this.logger.warn(
+        `Connection setup already in progress, waiting... (${waitCount + 1}/20)`,
+      );
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      waitCount++;
+    }
 
-    // Setup message handler
-    ws.on('message', (data: string) => {
-      try {
-        const message = JSON.parse(data);
+    if (this.isSettingConnection) {
+      this.logger.error('Connection setup timeout - forcing connection replacement');
+      this.isSettingConnection = false; // Force unlock
+    }
 
-        // Handle ping/pong heartbeat
-        if (message.type === 'ping') {
-          this.logger.debug('Received ping, sending pong');
-          ws.send(JSON.stringify({ type: 'pong' }));
-          return;
-        }
+    // Set lock
+    this.isSettingConnection = true;
 
-        // Handle normal command responses
-        const response: DrawDBResponse = message;
-        this.handleResponse(response);
-      } catch (error) {
-        this.logger.error('Failed to parse message from DrawDB client:', error);
+    try {
+      // Close existing connection if present
+      if (this.ws) {
+        const oldWs = this.ws;
+        const isOpen = oldWs.readyState === 1; // WebSocket.OPEN = 1
+
+        if (isOpen) {
+          this.logger.log(
+            'Closing previous DrawDB client connection - new client connecting',
+          );
+
+          // Remove event handlers from old connection to prevent interference
+          oldWs.removeAllListeners();
+
+          // Close the old connection
+          oldWs.close(1000, 'Replaced by new connection');
+
+          // Wait a tiny bit for close to propagate
+          await new Promise((resolve) => setTimeout(resolve, 50));
+        } else {
+          this.logger.debug(
+            `Previous connection already closed (state: ${oldWs.readyState})`,
+          );
+        }
       }
-    });
 
-    // Setup close handler
-    ws.on('close', () => {
-      this.logger.log('DrawDB client disconnected');
-      this.ws = null;
-      // Reject all pending requests
-      this.pendingRequests.forEach(({ reject, timeout }) => {
-        clearTimeout(timeout);
-        reject(new Error('DrawDB client disconnected'));
+      this.ws = ws;
+      this.logger.log('DrawDB client connected');
+
+      // Setup message handler
+      ws.on('message', (data: string) => {
+        try {
+          const message = JSON.parse(data);
+
+          // Handle ping/pong heartbeat
+          if (message.type === 'ping') {
+            this.logger.debug('Received ping, sending pong');
+            ws.send(JSON.stringify({ type: 'pong' }));
+            return;
+          }
+
+          // Handle normal command responses
+          const response: DrawDBResponse = message;
+          this.handleResponse(response);
+        } catch (error) {
+          this.logger.error('Failed to parse message from DrawDB client:', error);
+        }
       });
-      this.pendingRequests.clear();
-    });
+
+      // Setup close handler
+      ws.on('close', () => {
+        this.logger.log('DrawDB client disconnected');
+        this.ws = null;
+        // Reject all pending requests
+        this.pendingRequests.forEach(({ reject, timeout }) => {
+          clearTimeout(timeout);
+          reject(new Error('DrawDB client disconnected'));
+        });
+        this.pendingRequests.clear();
+      });
+    } finally {
+      // Release lock
+      this.isSettingConnection = false;
+    }
   }
 
   /**

apps/backend/src/drawdb/drawdb.gateway.ts

@@ -26,11 +26,12 @@ export class DrawDBGateway implements OnGatewayConnection, OnGatewayDisconnect {
 
   constructor(private readonly drawdbClient: DrawDBClientService) {}
 
-  handleConnection(client: any) {
+  async handleConnection(client: any) {
     this.logger.log('DrawDB client attempting to connect...');
 
     // Set the client connection in the service
-    this.drawdbClient.setConnection(client);
+    // This is async to properly handle connection replacement and prevent race conditions
+    await this.drawdbClient.setConnection(client);
   }
 
   handleDisconnect(client: any) {

apps/gui/src/hooks/useRemoteControl.js

@@ -124,6 +124,17 @@ export function useRemoteControl(enabled = false) {
           pingIntervalRef.current = null;
         }
 
+        // Check if connection was replaced by another session
+        const wasReplaced = event.code === 1000 && event.reason === "Replaced by new connection";
+
+        if (wasReplaced) {
+          // Connection taken over by another tab/window - don't reconnect
+          console.log("[RemoteControl] Connection taken over by another session");
+          Toast.warning("AI Assistant disconnected - connection taken over by another tab/window");
+          reconnectAttemptsRef.current = maxReconnectAttempts; // Prevent reconnection
+          return;
+        }
+
         // Only attempt to reconnect if enabled and haven't exceeded max attempts
         if (enabled && reconnectAttemptsRef.current < maxReconnectAttempts) {
           reconnectAttemptsRef.current++;