claude-mpm 3.7.8__py3-none-any.whl → 3.9.0__py3-none-any.whl

claude_mpm/services/communication/socketio.py

@@ -0,0 +1,1933 @@
+"""Socket.IO server for real-time monitoring of Claude MPM sessions.
+
+WHY: This provides a Socket.IO-based alternative to the WebSocket server,
+offering improved connection reliability and automatic reconnection.
+Socket.IO handles connection drops gracefully and provides better
+cross-platform compatibility.
+"""
+
+import asyncio
+import json
+import logging
+import os
+import threading
+import time
+from datetime import datetime
+from typing import Set, Dict, Any, Optional, List
+from collections import deque
+from pathlib import Path
+
+try:
+    import socketio
+    import aiohttp
+    from aiohttp import web
+    SOCKETIO_AVAILABLE = True
+    # Don't print at module level - this causes output during imports
+    # Version will be logged when server is actually started
+except ImportError:
+    SOCKETIO_AVAILABLE = False
+    socketio = None
+    aiohttp = None
+    web = None
+    # Don't print warnings at module level
+
+from ..core.logging_config import get_logger, log_operation, log_performance_context
+from ..deployment_paths import get_project_root, get_scripts_dir
+from .socketio.handlers import EventHandlerRegistry, FileEventHandler, GitEventHandler
+from ..core.constants import (
+    SystemLimits,
+    NetworkConfig,
+    TimeoutConfig,
+    PerformanceConfig
+)
+from ..core.interfaces import SocketIOServiceInterface
+from ..exceptions import MPMConnectionError
+
+
+class SocketIOClientProxy:
+    """Proxy that connects to an existing Socket.IO server as a client.
+    
+    WHY: In exec mode, a persistent Socket.IO server runs in a separate process.
+    The hook handler in the Claude process needs a Socket.IO-like interface
+    but shouldn't start another server. This proxy provides that interface
+    while the actual events are handled by the persistent server.
+    """
+    
+    def __init__(self, host: str = "localhost", port: int = 8765):
+        self.host = host
+        self.port = port
+        self.logger = get_logger(__name__ + ".SocketIOClientProxy")
+        self.running = True  # Always "running" for compatibility
+        self._sio_client = None
+        self._client_thread = None
+        self._client_loop = None
+        
+    def start_sync(self):
+        """Start the Socket.IO client connection to the persistent server."""
+        self.logger.debug(f"SocketIOClientProxy: Connecting to server on {self.host}:{self.port}")
+        if SOCKETIO_AVAILABLE:
+            self._start_client()
+        
+    def stop_sync(self):
+        """Stop the Socket.IO client connection."""
+        self.logger.debug(f"SocketIOClientProxy: Disconnecting from server")
+        if self._sio_client:
+            self._sio_client.disconnect()
+        
+    def _start_client(self):
+        """Start Socket.IO client in a background thread."""
+        def run_client():
+            self._client_loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(self._client_loop)
+            try:
+                self._client_loop.run_until_complete(self._connect_and_run())
+            except Exception as e:
+                self.logger.error(f"SocketIOClientProxy client thread error: {e}")
+            finally:
+                self._client_loop.close()
+            
+        self._client_thread = threading.Thread(target=run_client, daemon=True)
+        self._client_thread.start()
+        # Give it a moment to connect
+        time.sleep(0.2)
+        
+    async def _connect_and_run(self):
+        """Connect to the persistent Socket.IO server and keep connection alive."""
+        try:
+            self._sio_client = socketio.AsyncClient()
+            
+            @self._sio_client.event
+            async def connect():
+                self.logger.info(f"SocketIOClientProxy: Connected to server at http://{self.host}:{self.port}")
+                
+            @self._sio_client.event
+            async def disconnect():
+                self.logger.info(f"SocketIOClientProxy: Disconnected from server")
+                
+            # Connect to the server
+            await self._sio_client.connect(f'http://127.0.0.1:{self.port}')
+            
+            # Keep the connection alive until stopped
+            while self.running:
+                await asyncio.sleep(1)
+                    
+        except Exception as e:
+            self.logger.error(f"SocketIOClientProxy: Connection error: {e}")
+            self._sio_client = None
+        
+    def broadcast_event(self, event_type: str, data: Dict[str, Any]):
+        """Send event to the persistent Socket.IO server."""
+        if not SOCKETIO_AVAILABLE:
+            return
+            
+        # Ensure client is started
+        if not self._client_thread or not self._client_thread.is_alive():
+            self.logger.debug(f"SocketIOClientProxy: Starting client for {event_type}")
+            self._start_client()
+            
+        if self._sio_client and self._sio_client.connected:
+            try:
+                event = {
+                    "type": event_type,
+                    "timestamp": datetime.now().isoformat(),
+                    "data": data
+                }
+                
+                # Send event safely using run_coroutine_threadsafe
+                if hasattr(self, '_client_loop') and self._client_loop and not self._client_loop.is_closed():
+                    try:
+                        future = asyncio.run_coroutine_threadsafe(
+                            self._sio_client.emit('claude_event', event),
+                            self._client_loop
+                        )
+                        # Don't wait for the result to avoid blocking
+                        self.logger.debug(f"SocketIOClientProxy: Scheduled emit for {event_type}")
+                    except Exception as e:
+                        self.logger.error(f"SocketIOClientProxy: Failed to schedule emit for {event_type}: {e}")
+                else:
+                    self.logger.warning(f"SocketIOClientProxy: Client event loop not available for {event_type}")
+                
+                self.logger.debug(f"SocketIOClientProxy: Sent event {event_type}")
+            except Exception as e:
+                self.logger.error(f"SocketIOClientProxy: Failed to send event {event_type}: {e}")
+        else:
+            self.logger.warning(f"SocketIOClientProxy: Client not ready for {event_type}")
+    
+    # Compatibility methods for WebSocketServer interface
+    def session_started(self, session_id: str, launch_method: str, working_dir: str):
+        self.logger.debug(f"SocketIOClientProxy: Session started {session_id}")
+        
+    def session_ended(self):
+        self.logger.debug(f"SocketIOClientProxy: Session ended")
+        
+    def claude_status_changed(self, status: str, pid: Optional[int] = None, message: str = ""):
+        self.logger.debug(f"SocketIOClientProxy: Claude status {status}")
+        
+    def agent_delegated(self, agent: str, task: str, status: str = "started"):
+        self.logger.debug(f"SocketIOClientProxy: Agent {agent} delegated")
+        
+    def todo_updated(self, todos: List[Dict[str, Any]]):
+        self.logger.debug(f"SocketIOClientProxy: Todo updated ({len(todos)} todos)")
+
+
+class SocketIOServer(SocketIOServiceInterface):
+    """Socket.IO server for broadcasting Claude MPM events.
+    
+    WHY: Socket.IO provides better connection reliability than raw WebSockets,
+    with automatic reconnection, fallback transports, and better error handling.
+    It maintains the same event interface as WebSocketServer for compatibility.
+    """
+    
+    def __init__(self, host: str = "localhost", port: int = 8765):
+        self.host = host
+        self.port = port
+        self.logger = get_logger(__name__)
+        self.clients: Set[str] = set()  # Store session IDs instead of connection objects
+        self.event_history: deque = deque(maxlen=SystemLimits.MAX_EVENT_HISTORY)
+        self.sio = None
+        self.app = None
+        self.runner = None
+        self.site = None
+        self.loop = None
+        self.thread = None
+        self.running = False
+        
+        # Session state
+        self.session_id = None
+        self.session_start = None
+        self.claude_status = "stopped"
+        self.claude_pid = None
+        
+        if not SOCKETIO_AVAILABLE:
+            self.logger.warning("Socket.IO support not available. Install 'python-socketio' and 'aiohttp' packages to enable.")
+        else:
+            # Log version info when server is actually created
+            try:
+                version = getattr(socketio, '__version__', 'unknown')
+                self.logger.info(f"Socket.IO server using python-socketio v{version}")
+            except:
+                self.logger.info("Socket.IO server using python-socketio (version unavailable)")
+        
+    def start_sync(self):
+        """Start the Socket.IO server in a background thread (synchronous version)."""
+        if not SOCKETIO_AVAILABLE:
+            self.logger.debug("Socket.IO server skipped - required packages not installed")
+            return
+            
+        if self.running:
+            self.logger.debug(f"Socket.IO server already running on port {self.port}")
+            return
+            
+        self.running = True
+        self.thread = threading.Thread(target=self._run_server, daemon=True)
+        self.thread.start()
+        self.logger.info(f"🚀 Socket.IO server STARTING on http://{self.host}:{self.port}")
+        self.logger.info(f"🔧 Thread created: {self.thread.name} (daemon={self.thread.daemon})")
+        
+        # Give server a moment to start
+        time.sleep(0.1)
+        
+        if self.thread.is_alive():
+            self.logger.info(f"✅ Socket.IO server thread is alive and running")
+        else:
+            self.logger.error(f"❌ Socket.IO server thread failed to start!")
+        
+    def stop_sync(self):
+        """Stop the Socket.IO server (synchronous version)."""
+        self.running = False
+        if self.loop:
+            asyncio.run_coroutine_threadsafe(self._shutdown(), self.loop)
+        if self.thread:
+            self.thread.join(timeout=TimeoutConfig.THREAD_JOIN_TIMEOUT)
+        self.logger.info("Socket.IO server stopped")
+        
+    def _run_server(self):
+        """Run the server event loop."""
+        self.logger.info(f"🔄 _run_server starting on thread: {threading.current_thread().name}")
+        self.loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self.loop)
+        self.logger.info(f"📡 Event loop created and set for Socket.IO server")
+        
+        try:
+            self.logger.info(f"🎯 About to start _serve() coroutine")
+            self.loop.run_until_complete(self._serve())
+        except Exception as e:
+            self.logger.error(f"❌ Socket.IO server error in _run_server: {e}")
+            import traceback
+            self.logger.error(f"Stack trace: {traceback.format_exc()}")
+        finally:
+            self.logger.info(f"🔚 Socket.IO server _run_server shutting down")
+            self.loop.close()
+            
+    async def _serve(self):
+        """Start the Socket.IO server."""
+        try:
+            self.logger.info(f"🔌 _serve() starting - attempting to bind to {self.host}:{self.port}")
+            
+            # Create Socket.IO server with improved configuration
+            self.sio = socketio.AsyncServer(
+                cors_allowed_origins="*",
+                ping_timeout=NetworkConfig.PING_TIMEOUT,
+                ping_interval=NetworkConfig.PING_INTERVAL,
+                max_http_buffer_size=1000000,
+                allow_upgrades=True,
+                transports=['websocket', 'polling'],
+                logger=False,  # Reduce noise in logs
+                engineio_logger=False
+            )
+            
+            # Create aiohttp web application
+            self.app = web.Application()
+            self.sio.attach(self.app)
+            
+            # Add CORS middleware
+            import aiohttp_cors
+            cors = aiohttp_cors.setup(self.app, defaults={
+                "*": aiohttp_cors.ResourceOptions(
+                    allow_credentials=True,
+                    expose_headers="*",
+                    allow_headers="*",
+                    allow_methods="*"
+                )
+            })
+            
+            # Add HTTP routes
+            self.app.router.add_get('/health', self._handle_health)
+            self.app.router.add_get('/status', self._handle_health)
+            self.app.router.add_get('/api/git-diff', self._handle_git_diff)
+            self.app.router.add_options('/api/git-diff', self._handle_cors_preflight)
+            self.app.router.add_get('/api/file-content', self._handle_file_content)
+            self.app.router.add_options('/api/file-content', self._handle_cors_preflight)
+            
+            # Add dashboard routes
+            self.app.router.add_get('/', self._handle_dashboard)
+            self.app.router.add_get('/dashboard', self._handle_dashboard)
+            
+            # Add static file serving for web assets
+            static_path = self._find_static_path()
+            if static_path and static_path.exists():
+                self.app.router.add_static('/static/', path=str(static_path), name='static')
+                self.logger.info(f"Static files served from: {static_path}")
+            else:
+                self.logger.warning("Static files directory not found - CSS/JS files will not be available")
+            
+            # Register event handlers
+            self._register_events()
+            
+            # Start the server
+            self.runner = web.AppRunner(self.app)
+            await self.runner.setup()
+            
+            self.site = web.TCPSite(self.runner, self.host, self.port)
+            try:
+                await self.site.start()
+            except OSError as e:
+                if "Address already in use" in str(e) or "address already in use" in str(e).lower():
+                    raise MPMConnectionError(
+                        f"Port {self.port} is already in use",
+                        context={"host": self.host, "port": self.port, "error": str(e)}
+                    ) from e
+                else:
+                    raise
+            
+            self.logger.info(f"🎉 Socket.IO server SUCCESSFULLY listening on http://{self.host}:{self.port}")
+            
+            # Keep server running
+            loop_count = 0
+            while self.running:
+                await asyncio.sleep(0.1)
+                loop_count += 1
+                if loop_count % PerformanceConfig.LOG_EVERY_N_ITERATIONS == 0:
+                    self.logger.debug(f"🔄 Socket.IO server heartbeat - {len(self.clients)} clients connected")
+                
+        except Exception as e:
+            self.logger.error(f"❌ Failed to start Socket.IO server: {e}")
+            import traceback
+            self.logger.error(f"Stack trace: {traceback.format_exc()}")
+            raise
+                
+    async def _shutdown(self):
+        """Shutdown the server."""
+        if self.site:
+            await self.site.stop()
+        if self.runner:
+            await self.runner.cleanup()
+            
+    async def _handle_health(self, request):
+        """Handle health check requests."""
+        return web.json_response({
+            "status": "healthy",
+            "server": "claude-mpm-python-socketio",
+            "timestamp": datetime.utcnow().isoformat() + "Z",
+            "port": self.port,
+            "host": self.host,
+            "clients_connected": len(self.clients)
+        }, headers={
+            'Access-Control-Allow-Origin': '*',
+            'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+            'Access-Control-Allow-Headers': 'Content-Type, Accept'
+        })
+
+    def _find_static_path(self):
+        """Find the static files directory using multiple approaches.
+        
+        WHY: Static files need to be found in both development and installed environments.
+        This uses the same multi-approach pattern as dashboard HTML resolution.
+        """
+        
+        # Approach 1: Use module-relative path (works in installed environment)
+        try:
+            import claude_mpm.dashboard
+            
+            # Try __file__ attribute first
+            if hasattr(claude_mpm.dashboard, '__file__') and claude_mpm.dashboard.__file__:
+                dashboard_module_path = Path(claude_mpm.dashboard.__file__).parent
+                candidate_path = dashboard_module_path / "static"
+                if candidate_path.exists():
+                    self.logger.info(f"Found static files using module __file__ path: {candidate_path}")
+                    return candidate_path
+            
+            # Try __path__ attribute for namespace packages
+            elif hasattr(claude_mpm.dashboard, '__path__') and claude_mpm.dashboard.__path__:
+                # __path__ is a list, take the first entry
+                dashboard_module_path = Path(claude_mpm.dashboard.__path__[0])
+                candidate_path = dashboard_module_path / "static"
+                if candidate_path.exists():
+                    self.logger.info(f"Found static files using module __path__: {candidate_path}")
+                    return candidate_path
+                    
+        except Exception as e:
+            self.logger.debug(f"Module-relative static path failed: {e}")
+        
+        # Approach 2: Use project root (works in development environment)
+        try:
+            candidate_path = get_project_root() / 'src' / 'claude_mpm' / 'dashboard' / 'static'
+            if candidate_path.exists():
+                self.logger.info(f"Found static files using project root: {candidate_path}")
+                return candidate_path
+        except Exception as e:
+            self.logger.debug(f"Project root static path failed: {e}")
+        
+        # Approach 3: Search for static files in package installation
+        try:
+            candidate_path = get_project_root() / 'claude_mpm' / 'dashboard' / 'static'
+            if candidate_path.exists():
+                self.logger.info(f"Found static files using package path: {candidate_path}")
+                return candidate_path
+        except Exception as e:
+            self.logger.debug(f"Package static path failed: {e}")
+        
+        return None
+
+    async def _handle_dashboard(self, request):
+        """Serve the dashboard HTML file."""
+        # Try to find dashboard path using multiple approaches
+        dashboard_path = None
+        
+        # Approach 1: Use module-relative path (works in installed environment)
+        try:
+            import claude_mpm.dashboard
+            
+            # Try __file__ attribute first
+            if hasattr(claude_mpm.dashboard, '__file__') and claude_mpm.dashboard.__file__:
+                dashboard_module_path = Path(claude_mpm.dashboard.__file__).parent
+                candidate_path = dashboard_module_path / "templates" / "index.html"
+                if candidate_path.exists():
+                    dashboard_path = candidate_path
+                    self.logger.info(f"Found dashboard using module __file__ path: {dashboard_path}")
+            
+            # Try __path__ attribute for namespace packages
+            elif hasattr(claude_mpm.dashboard, '__path__') and claude_mpm.dashboard.__path__:
+                # __path__ is a list, take the first entry
+                dashboard_module_path = Path(claude_mpm.dashboard.__path__[0])
+                candidate_path = dashboard_module_path / "templates" / "index.html"
+                if candidate_path.exists():
+                    dashboard_path = candidate_path
+                    self.logger.info(f"Found dashboard using module __path__: {dashboard_path}")
+                    
+        except Exception as e:
+            self.logger.debug(f"Module-relative path failed: {e}")
+        
+        # Approach 2: Use project root (works in development environment)
+        if dashboard_path is None:
+            try:
+                candidate_path = get_project_root() / 'src' / 'claude_mpm' / 'dashboard' / 'templates' / 'index.html'
+                if candidate_path.exists():
+                    dashboard_path = candidate_path
+                    self.logger.info(f"Found dashboard using project root: {dashboard_path}")
+            except Exception as e:
+                self.logger.debug(f"Project root path failed: {e}")
+        
+        # Approach 3: Search for dashboard in package installation
+        if dashboard_path is None:
+            try:
+                candidate_path = get_project_root() / 'claude_mpm' / 'dashboard' / 'templates' / 'index.html'
+                if candidate_path.exists():
+                    dashboard_path = candidate_path
+                    self.logger.info(f"Found dashboard using package path: {dashboard_path}")
+            except Exception as e:
+                self.logger.debug(f"Package path failed: {e}")
+        
+        if dashboard_path and dashboard_path.exists():
+            return web.FileResponse(str(dashboard_path))
+        else:
+            error_msg = f"Dashboard not found. Searched paths:\n"
+            error_msg += f"1. Module-relative: {dashboard_module_path / 'templates' / 'index.html' if 'dashboard_module_path' in locals() else 'N/A'}\n"
+            error_msg += f"2. Development: {get_project_root() / 'src' / 'claude_mpm' / 'dashboard' / 'templates' / 'index.html'}\n"
+            error_msg += f"3. Package: {get_project_root() / 'claude_mpm' / 'dashboard' / 'templates' / 'index.html'}"
+            self.logger.error(error_msg)
+            return web.Response(text=error_msg, status=404)
+    
+    async def _handle_cors_preflight(self, request):
+        """Handle CORS preflight requests."""
+        return web.Response(
+            status=NetworkConfig.HTTP_OK,
+            headers={
+                'Access-Control-Allow-Origin': '*',
+                'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+                'Access-Control-Allow-Headers': 'Content-Type, Accept, Authorization',
+                'Access-Control-Max-Age': '86400'
+            }
+        )
+        
+    async def _handle_git_diff(self, request):
+        """Handle git diff requests for file operations.
+        
+        Expected query parameters:
+        - file: The file path to generate diff for
+        - timestamp: ISO timestamp of the operation (optional)
+        - working_dir: Working directory for git operations (optional)
+        """
+        try:
+            # Extract query parameters
+            file_path = request.query.get('file')
+            timestamp = request.query.get('timestamp')
+            working_dir = request.query.get('working_dir', os.getcwd())
+            
+            self.logger.info(f"Git diff API request: file={file_path}, timestamp={timestamp}, working_dir={working_dir}")
+            self.logger.info(f"Git diff request details: query_params={dict(request.query)}, file_exists={os.path.exists(file_path) if file_path else False}")
+            
+            if not file_path:
+                self.logger.warning("Git diff request missing file parameter")
+                return web.json_response({
+                    "success": False,
+                    "error": "Missing required parameter: file"
+                }, status=400, headers={
+                    'Access-Control-Allow-Origin': '*',
+                    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+                    'Access-Control-Allow-Headers': 'Content-Type, Accept'
+                })
+            
+            self.logger.debug(f"Git diff requested for file: {file_path}, timestamp: {timestamp}")
+            
+            # Generate git diff using the git handler's method
+            if hasattr(self, 'git_handler') and self.git_handler:
+                diff_result = await self.git_handler.generate_git_diff(file_path, timestamp, working_dir)
+            else:
+                # Fallback to old method if handler not available
+                diff_result = await self._generate_git_diff(file_path, timestamp, working_dir)
+            
+            self.logger.info(f"Git diff result: success={diff_result.get('success', False)}, method={diff_result.get('method', 'unknown')}")
+            
+            return web.json_response(diff_result, headers={
+                'Access-Control-Allow-Origin': '*',
+                'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+                'Access-Control-Allow-Headers': 'Content-Type, Accept'
+            })
+            
+        except Exception as e:
+            self.logger.error(f"Error generating git diff: {e}")
+            import traceback
+            self.logger.error(f"Git diff error traceback: {traceback.format_exc()}")
+            return web.json_response({
+                "success": False,
+                "error": f"Failed to generate git diff: {str(e)}"
+            }, status=NetworkConfig.HTTP_INTERNAL_ERROR, headers={
+                'Access-Control-Allow-Origin': '*',
+                'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+                'Access-Control-Allow-Headers': 'Content-Type, Accept'
+            })
+    
+    async def _handle_file_content(self, request):
+        """Handle file content requests via HTTP API.
+        
+        Expected query parameters:
+        - file_path: The file path to read
+        - working_dir: Working directory for file operations (optional)
+        - max_size: Maximum file size in bytes (optional, default 1MB)
+        """
+        try:
+            # Extract query parameters
+            file_path = request.query.get('file_path')
+            working_dir = request.query.get('working_dir', os.getcwd())
+            max_size = int(request.query.get('max_size', SystemLimits.MAX_FILE_SIZE))
+            
+            self.logger.info(f"File content API request: file_path={file_path}, working_dir={working_dir}")
+            
+            if not file_path:
+                self.logger.warning("File content request missing file_path parameter")
+                return web.json_response({
+                    "success": False,
+                    "error": "Missing required parameter: file_path"
+                }, status=400, headers={
+                    'Access-Control-Allow-Origin': '*',
+                    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+                    'Access-Control-Allow-Headers': 'Content-Type, Accept'
+                })
+            
+            # Use the file handler's safe reading logic
+            if hasattr(self, 'file_handler') and self.file_handler:
+                result = await self.file_handler._read_file_safely(file_path, working_dir, max_size)
+            else:
+                # Fallback to old method if handler not available
+                result = await self._read_file_safely(file_path, working_dir, max_size)
+            
+            status_code = 200 if result.get('success') else 400
+            return web.json_response(result, status=status_code, headers={
+                'Access-Control-Allow-Origin': '*',
+                'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',  
+                'Access-Control-Allow-Headers': 'Content-Type, Accept'
+            })
+            
+        except Exception as e:
+            self.logger.error(f"Error reading file content: {e}")
+            import traceback
+            self.logger.error(f"File content error traceback: {traceback.format_exc()}")
+            return web.json_response({
+                "success": False,
+                "error": f"Failed to read file: {str(e)}"
+            }, status=NetworkConfig.HTTP_INTERNAL_ERROR, headers={
+                'Access-Control-Allow-Origin': '*',
+                'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+                'Access-Control-Allow-Headers': 'Content-Type, Accept'
+            })
+    
+    async def _read_file_safely(self, file_path: str, working_dir: str = None, max_size: int = SystemLimits.MAX_FILE_SIZE):
+        """Safely read file content with security checks.
+        
+        This method contains the core file reading logic that can be used by both
+        HTTP API endpoints and Socket.IO event handlers.
+        
+        Args:
+            file_path: Path to the file to read
+            working_dir: Working directory (defaults to current directory)
+            max_size: Maximum file size in bytes
+            
+        Returns:
+            dict: Response with success status, content, and metadata
+        """
+        try:
+            if working_dir is None:
+                working_dir = os.getcwd()
+                
+            # Resolve absolute path based on working directory
+            if not os.path.isabs(file_path):
+                full_path = os.path.join(working_dir, file_path)
+            else:
+                full_path = file_path
+            
+            # Security check: ensure file is within working directory or project
+            try:
+                real_path = os.path.realpath(full_path)
+                real_working_dir = os.path.realpath(working_dir)
+                
+                # Allow access to files within working directory or the project root
+                project_root = os.path.realpath(get_project_root())
+                allowed_paths = [real_working_dir, project_root]
+                
+                is_allowed = any(real_path.startswith(allowed_path) for allowed_path in allowed_paths)
+                
+                if not is_allowed:
+                    return {
+                        'success': False,
+                        'error': 'Access denied: file is outside allowed directories',
+                        'file_path': file_path
+                    }
+                    
+            except Exception as path_error:
+                self.logger.error(f"Path validation error: {path_error}")
+                return {
+                    'success': False,
+                    'error': 'Invalid file path',
+                    'file_path': file_path
+                }
+            
+            # Check if file exists
+            if not os.path.exists(real_path):
+                return {
+                    'success': False,
+                    'error': 'File does not exist',
+                    'file_path': file_path
+                }
+            
+            # Check if it's a file (not directory)
+            if not os.path.isfile(real_path):
+                return {
+                    'success': False,
+                    'error': 'Path is not a file',
+                    'file_path': file_path
+                }
+            
+            # Check file size
+            file_size = os.path.getsize(real_path)
+            if file_size > max_size:
+                return {
+                    'success': False,
+                    'error': f'File too large ({file_size} bytes). Maximum allowed: {max_size} bytes',
+                    'file_path': file_path,
+                    'file_size': file_size
+                }
+            
+            # Read file content
+            try:
+                with open(real_path, 'r', encoding='utf-8') as f:
+                    content = f.read()
+                
+                # Get file extension for syntax highlighting hint
+                _, ext = os.path.splitext(real_path)
+                
+                return {
+                    'success': True,
+                    'file_path': file_path,
+                    'content': content,
+                    'file_size': file_size,
+                    'extension': ext.lower(),
+                    'encoding': 'utf-8'
+                }
+                
+            except UnicodeDecodeError:
+                # Try reading as binary if UTF-8 fails
+                try:
+                    with open(real_path, 'rb') as f:
+                        binary_content = f.read()
+                    
+                    # Check if it's a text file by looking for common text patterns
+                    try:
+                        text_content = binary_content.decode('latin-1')
+                        if '\x00' in text_content:
+                            # Binary file
+                            return {
+                                'success': False,
+                                'error': 'File appears to be binary and cannot be displayed as text',
+                                'file_path': file_path,
+                                'file_size': file_size
+                            }
+                        else:
+                            # Text file with different encoding
+                            _, ext = os.path.splitext(real_path)
+                            return {
+                                'success': True,
+                                'file_path': file_path,
+                                'content': text_content,
+                                'file_size': file_size,
+                                'extension': ext.lower(),
+                                'encoding': 'latin-1'
+                            }
+                    except Exception:
+                        return {
+                            'success': False,
+                            'error': 'File encoding not supported',
+                            'file_path': file_path
+                        }
+                except Exception as read_error:
+                    return {
+                        'success': False,
+                        'error': f'Failed to read file: {str(read_error)}',
+                        'file_path': file_path
+                    }
+                    
+        except Exception as e:
+            self.logger.error(f"Error in _read_file_safely: {e}")
+            return {
+                'success': False,
+                'error': str(e),
+                'file_path': file_path
+            }
+    
+    async def _generate_git_diff(self, file_path: str, timestamp: Optional[str] = None, working_dir: str = None):
+        """Generate git diff for a specific file operation.
+        
+        WHY: This method generates a git diff showing the changes made to a file
+        during a specific write operation. It uses git log and show commands to
+        find the most relevant commit around the specified timestamp.
+        
+        Args:
+            file_path: Path to the file relative to the git repository
+            timestamp: ISO timestamp of the file operation (optional)
+            working_dir: Working directory containing the git repository
+            
+        Returns:
+            dict: Contains diff content, metadata, and status information
+        """
+        try:
+            # If file_path is absolute, determine its git repository
+            if os.path.isabs(file_path):
+                # Find the directory containing the file
+                file_dir = os.path.dirname(file_path)
+                if os.path.exists(file_dir):
+                    # Try to find the git root from the file's directory
+                    current_dir = file_dir
+                    while current_dir != "/" and current_dir:
+                        if os.path.exists(os.path.join(current_dir, ".git")):
+                            working_dir = current_dir
+                            self.logger.info(f"Found git repository at: {working_dir}")
+                            break
+                        current_dir = os.path.dirname(current_dir)
+                    else:
+                        # If no git repo found, use the file's directory
+                        working_dir = file_dir
+                        self.logger.info(f"No git repo found, using file's directory: {working_dir}")
+            
+            # Handle case where working_dir is None, empty string, or 'Unknown'
+            original_working_dir = working_dir
+            if not working_dir or working_dir == 'Unknown' or working_dir.strip() == '':
+                working_dir = os.getcwd()
+                self.logger.info(f"[GIT-DIFF-DEBUG] working_dir was invalid ({repr(original_working_dir)}), using cwd: {working_dir}")
+            else:
+                self.logger.info(f"[GIT-DIFF-DEBUG] Using provided working_dir: {working_dir}")
+                
+            # For read-only git operations, we can work from any directory
+            # by passing the -C flag to git commands instead of changing directories
+            original_cwd = os.getcwd()
+            try:
+                # We'll use git -C <working_dir> for all commands instead of chdir
+                
+                # Check if this is a git repository
+                git_check = await asyncio.create_subprocess_exec(
+                    'git', '-C', working_dir, 'rev-parse', '--git-dir',
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE
+                )
+                await git_check.communicate()
+                
+                if git_check.returncode != 0:
+                    return {
+                        "success": False,
+                        "error": "Not a git repository",
+                        "file_path": file_path,
+                        "working_dir": working_dir
+                    }
+                
+                # Get the absolute path of the file relative to git root
+                git_root_proc = await asyncio.create_subprocess_exec(
+                    'git', '-C', working_dir, 'rev-parse', '--show-toplevel',
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE
+                )
+                git_root_output, _ = await git_root_proc.communicate()
+                
+                if git_root_proc.returncode != 0:
+                    return {"success": False, "error": "Failed to determine git root directory"}
+                
+                git_root = git_root_output.decode().strip()
+                
+                # Make file_path relative to git root if it's absolute
+                if os.path.isabs(file_path):
+                    try:
+                        file_path = os.path.relpath(file_path, git_root)
+                    except ValueError:
+                        # File is not under git root
+                        pass
+                
+                # If timestamp is provided, try to find commits around that time
+                if timestamp:
+                    # Convert timestamp to git format
+                    try:
+                        from datetime import datetime
+                        dt = datetime.fromisoformat(timestamp.replace('Z', '+00:00'))
+                        git_since = dt.strftime('%Y-%m-%d %H:%M:%S')
+                        
+                        # Find commits that modified this file around the timestamp
+                        log_proc = await asyncio.create_subprocess_exec(
+                            'git', '-C', working_dir, 'log', '--oneline', '--since', git_since, 
+                            '--until', f'{git_since} +1 hour', '--', file_path,
+                            stdout=asyncio.subprocess.PIPE,
+                            stderr=asyncio.subprocess.PIPE
+                        )
+                        log_output, _ = await log_proc.communicate()
+                        
+                        if log_proc.returncode == 0 and log_output:
+                            # Get the most recent commit hash
+                            commits = log_output.decode().strip().split('\n')
+                            if commits and commits[0]:
+                                commit_hash = commits[0].split()[0]
+                                
+                                # Get the diff for this specific commit
+                                diff_proc = await asyncio.create_subprocess_exec(
+                                    'git', '-C', working_dir, 'show', '--format=fuller', commit_hash, '--', file_path,
+                                    stdout=asyncio.subprocess.PIPE,
+                                    stderr=asyncio.subprocess.PIPE
+                                )
+                                diff_output, diff_error = await diff_proc.communicate()
+                                
+                                if diff_proc.returncode == 0:
+                                    return {
+                                        "success": True,
+                                        "diff": diff_output.decode(),
+                                        "commit_hash": commit_hash,
+                                        "file_path": file_path,
+                                        "method": "timestamp_based",
+                                        "timestamp": timestamp
+                                    }
+                    except Exception as e:
+                        self.logger.warning(f"Failed to parse timestamp or find commits: {e}")
+                
+                # Fallback: Get the most recent change to the file
+                log_proc = await asyncio.create_subprocess_exec(
+                    'git', '-C', working_dir, 'log', '-1', '--oneline', '--', file_path,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE
+                )
+                log_output, _ = await log_proc.communicate()
+                
+                if log_proc.returncode == 0 and log_output:
+                    commit_hash = log_output.decode().strip().split()[0]
+                    
+                    # Get the diff for the most recent commit
+                    diff_proc = await asyncio.create_subprocess_exec(
+                        'git', '-C', working_dir, 'show', '--format=fuller', commit_hash, '--', file_path,
+                        stdout=asyncio.subprocess.PIPE,
+                        stderr=asyncio.subprocess.PIPE
+                    )
+                    diff_output, diff_error = await diff_proc.communicate()
+                    
+                    if diff_proc.returncode == 0:
+                        return {
+                            "success": True,
+                            "diff": diff_output.decode(),
+                            "commit_hash": commit_hash,
+                            "file_path": file_path,
+                            "method": "latest_commit",
+                            "timestamp": timestamp
+                        }
+                
+                # Try to show unstaged changes first
+                diff_proc = await asyncio.create_subprocess_exec(
+                    'git', '-C', working_dir, 'diff', '--', file_path,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE
+                )
+                diff_output, _ = await diff_proc.communicate()
+                
+                if diff_proc.returncode == 0 and diff_output.decode().strip():
+                    return {
+                        "success": True,
+                        "diff": diff_output.decode(),
+                        "commit_hash": "unstaged_changes",
+                        "file_path": file_path,
+                        "method": "unstaged_changes",
+                        "timestamp": timestamp
+                    }
+                
+                # Then try staged changes
+                diff_proc = await asyncio.create_subprocess_exec(
+                    'git', '-C', working_dir, 'diff', '--cached', '--', file_path,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE
+                )
+                diff_output, _ = await diff_proc.communicate()
+                
+                if diff_proc.returncode == 0 and diff_output.decode().strip():
+                    return {
+                        "success": True,
+                        "diff": diff_output.decode(),
+                        "commit_hash": "staged_changes",
+                        "file_path": file_path,
+                        "method": "staged_changes",
+                        "timestamp": timestamp
+                    }
+                
+                # Final fallback: Show changes against HEAD
+                diff_proc = await asyncio.create_subprocess_exec(
+                    'git', '-C', working_dir, 'diff', 'HEAD', '--', file_path,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE
+                )
+                diff_output, _ = await diff_proc.communicate()
+                
+                if diff_proc.returncode == 0:
+                    working_diff = diff_output.decode()
+                    if working_diff.strip():
+                        return {
+                            "success": True,
+                            "diff": working_diff,
+                            "commit_hash": "working_directory",
+                            "file_path": file_path,
+                            "method": "working_directory",
+                            "timestamp": timestamp
+                        }
+                
+                # Check if file is tracked by git
+                status_proc = await asyncio.create_subprocess_exec(
+                    'git', '-C', working_dir, 'ls-files', '--', file_path,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE
+                )
+                status_output, _ = await status_proc.communicate()
+                
+                is_tracked = status_proc.returncode == 0 and status_output.decode().strip()
+                
+                if not is_tracked:
+                    # File is not tracked by git
+                    return {
+                        "success": False,
+                        "error": "This file is not tracked by git",
+                        "file_path": file_path,
+                        "working_dir": working_dir,
+                        "suggestions": [
+                            "This file has not been added to git yet",
+                            "Use 'git add' to track this file before viewing its diff",
+                            "Git diff can only show changes for files that are tracked by git"
+                        ]
+                    }
+                
+                # File is tracked but has no changes to show
+                suggestions = [
+                    "The file may not have any committed changes yet",
+                    "The file may have been added but not committed",
+                    "The timestamp may be outside the git history range"
+                ]
+                
+                if os.path.isabs(file_path) and not file_path.startswith(os.getcwd()):
+                    current_repo = os.path.basename(os.getcwd())
+                    file_repo = "unknown"
+                    # Try to extract repository name from path
+                    path_parts = file_path.split("/")
+                    if "Projects" in path_parts:
+                        idx = path_parts.index("Projects")
+                        if idx + 1 < len(path_parts):
+                            file_repo = path_parts[idx + 1]
+                    
+                    suggestions.clear()
+                    suggestions.append(f"This file is from the '{file_repo}' repository")
+                    suggestions.append(f"The git diff viewer is running from the '{current_repo}' repository")
+                    suggestions.append("Git diff can only show changes for files in the current repository")
+                    suggestions.append("To view changes for this file, run the monitoring dashboard from its repository")
+                
+                return {
+                    "success": False,
+                    "error": "No git history found for this file",
+                    "file_path": file_path,
+                    "suggestions": suggestions
+                }
+                
+            finally:
+                os.chdir(original_cwd)
+                
+        except Exception as e:
+            self.logger.error(f"Error in _generate_git_diff: {e}")
+            return {
+                "success": False,
+                "error": f"Git diff generation failed: {str(e)}",
+                "file_path": file_path
+            }
+        
+            
+    def _register_events(self):
+        """Register Socket.IO event handlers.
+        
+        WHY: This method now uses the EventHandlerRegistry to manage all event
+        handlers in a modular way. Each handler focuses on a specific domain,
+        reducing complexity and improving maintainability.
+        """
+        # Initialize the event handler registry
+        self.event_registry = EventHandlerRegistry(self)
+        self.event_registry.initialize()
+        
+        # Register all events from all handlers
+        self.event_registry.register_all_events()
+        
+        # Keep handler instances for HTTP endpoint compatibility
+        self.file_handler = self.event_registry.get_handler(FileEventHandler)
+        self.git_handler = self.event_registry.get_handler(GitEventHandler)
+        
+        self.logger.info("All Socket.IO events registered via handler system")
+        
+        # Note: The actual event registration is now handled by individual
+        # handler classes in socketio/handlers/. This dramatically reduces
+        # the complexity of this method from 514 lines to under 20 lines.
+        
+        return  # Early return to skip old implementation
+        
+        @self.sio.event
+        async def connect(sid, environ, *args):
+            """Handle client connection."""
+            self.clients.add(sid)
+            client_addr = environ.get('REMOTE_ADDR', 'unknown') 
+            user_agent = environ.get('HTTP_USER_AGENT', 'unknown')
+            self.logger.info(f"🔗 NEW CLIENT CONNECTED: {sid} from {client_addr}")
+            self.logger.info(f"📱 User Agent: {user_agent[:100]}...")
+            self.logger.info(f"📈 Total clients now: {len(self.clients)}")
+            
+            # Send initial status immediately with enhanced data
+            status_data = {
+                "server": "claude-mpm-python-socketio",
+                "timestamp": datetime.utcnow().isoformat() + "Z",
+                "clients_connected": len(self.clients),
+                "session_id": self.session_id,
+                "claude_status": self.claude_status,
+                "claude_pid": self.claude_pid,
+                "server_version": "2.0.0",
+                "client_id": sid
+            }
+            
+            try:
+                await self.sio.emit('status', status_data, room=sid)
+                await self.sio.emit('welcome', {
+                    "message": "Connected to Claude MPM Socket.IO server",
+                    "client_id": sid,
+                    "server_time": datetime.utcnow().isoformat() + "Z"
+                }, room=sid)
+                
+                # Automatically send the last 50 events to new clients
+                await self._send_event_history(sid, limit=50)
+                
+                self.logger.debug(f"✅ Sent welcome messages and event history to client {sid}")
+            except Exception as e:
+                self.logger.error(f"❌ Failed to send welcome to client {sid}: {e}")
+                import traceback
+                self.logger.error(f"Full traceback: {traceback.format_exc()}")
+            
+        @self.sio.event
+        async def disconnect(sid):
+            """Handle client disconnection."""
+            if sid in self.clients:
+                self.clients.remove(sid)
+                self.logger.info(f"🔌 CLIENT DISCONNECTED: {sid}")
+                self.logger.info(f"📉 Total clients now: {len(self.clients)}")
+            else:
+                self.logger.warning(f"⚠️  Attempted to disconnect unknown client: {sid}")
+            
+        @self.sio.event
+        async def get_status(sid):
+            """Handle status request."""
+            # Send compatible status event (not claude_event)
+            status_data = {
+                "server": "claude-mpm-python-socketio",
+                "timestamp": datetime.utcnow().isoformat() + "Z",
+                "clients_connected": len(self.clients),
+                "session_id": self.session_id,
+                "claude_status": self.claude_status,
+                "claude_pid": self.claude_pid
+            }
+            await self.sio.emit('status', status_data, room=sid)
+            self.logger.debug(f"Sent status response to client {sid}")
+            
+        @self.sio.event
+        async def get_history(sid, data=None):
+            """Handle history request."""
+            params = data or {}
+            event_types = params.get("event_types", [])
+            limit = min(params.get("limit", 100), len(self.event_history))
+            
+            await self._send_event_history(sid, event_types=event_types, limit=limit)
+            
+        @self.sio.event
+        async def request_history(sid, data=None):
+            """Handle legacy history request (for client compatibility)."""
+            # This handles the 'request.history' event that the client currently emits
+            params = data or {}
+            event_types = params.get("event_types", [])
+            limit = min(params.get("limit", 50), len(self.event_history))
+            
+            await self._send_event_history(sid, event_types=event_types, limit=limit)
+            
+        @self.sio.event
+        async def subscribe(sid, data=None):
+            """Handle subscription request."""
+            channels = data.get("channels", ["*"]) if data else ["*"]
+            await self.sio.emit('subscribed', {
+                "channels": channels
+            }, room=sid)
+            
+        @self.sio.event
+        async def claude_event(sid, data):
+            """Handle events from client proxies."""
+            # Store in history
+            self.event_history.append(data)
+            self.logger.debug(f"📚 Event from client stored in history (total: {len(self.event_history)})")
+            
+            # Re-broadcast to all other clients
+            await self.sio.emit('claude_event', data, skip_sid=sid)
+        
+        @self.sio.event
+        async def get_git_branch(sid, working_dir=None):
+            """Get the current git branch for a directory"""
+            import subprocess
+            try:
+                self.logger.info(f"[GIT-BRANCH-DEBUG] get_git_branch called with working_dir: {repr(working_dir)} (type: {type(working_dir)})")
+                
+                # Handle case where working_dir is None, empty string, or common invalid states
+                original_working_dir = working_dir
+                invalid_states = [
+                    None, '', 'Unknown', 'Loading...', 'Loading', 'undefined', 'null', 
+                    'Not Connected', 'Invalid Directory', 'No Directory'
+                ]
+                
+                if working_dir in invalid_states or (isinstance(working_dir, str) and working_dir.strip() == ''):
+                    working_dir = os.getcwd()
+                    self.logger.info(f"[GIT-BRANCH-DEBUG] working_dir was invalid ({repr(original_working_dir)}), using cwd: {working_dir}")
+                else:
+                    self.logger.info(f"[GIT-BRANCH-DEBUG] Using provided working_dir: {working_dir}")
+                    
+                # Additional validation for obviously invalid paths
+                if isinstance(working_dir, str):
+                    working_dir = working_dir.strip()
+                    # Check for null bytes or other invalid characters
+                    if '\x00' in working_dir:
+                        self.logger.warning(f"[GIT-BRANCH-DEBUG] working_dir contains null bytes, using cwd instead")
+                        working_dir = os.getcwd()
+                
+                # Validate that the directory exists and is a valid path
+                if not os.path.exists(working_dir):
+                    self.logger.info(f"[GIT-BRANCH-DEBUG] Directory does not exist: {working_dir} - responding gracefully")
+                    await self.sio.emit('git_branch_response', {
+                        'success': False,
+                        'error': f'Directory not found',
+                        'working_dir': working_dir,
+                        'original_working_dir': original_working_dir,
+                        'detail': f'Path does not exist: {working_dir}'
+                    }, room=sid)
+                    return
+                    
+                if not os.path.isdir(working_dir):
+                    self.logger.info(f"[GIT-BRANCH-DEBUG] Path is not a directory: {working_dir} - responding gracefully")
+                    await self.sio.emit('git_branch_response', {
+                        'success': False,
+                        'error': f'Not a directory',
+                        'working_dir': working_dir,
+                        'original_working_dir': original_working_dir,
+                        'detail': f'Path is not a directory: {working_dir}'
+                    }, room=sid)
+                    return
+                
+                self.logger.info(f"[GIT-BRANCH-DEBUG] Running git command in directory: {working_dir}")
+                
+                # Run git command to get current branch
+                result = subprocess.run(
+                    ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+                    cwd=working_dir,
+                    capture_output=True,
+                    text=True
+                )
+                
+                self.logger.info(f"[GIT-BRANCH-DEBUG] Git command result: returncode={result.returncode}, stdout={repr(result.stdout)}, stderr={repr(result.stderr)}")
+                
+                if result.returncode == 0:
+                    branch = result.stdout.strip()
+                    self.logger.info(f"[GIT-BRANCH-DEBUG] Successfully got git branch: {branch}")
+                    await self.sio.emit('git_branch_response', {
+                        'success': True,
+                        'branch': branch,
+                        'working_dir': working_dir,
+                        'original_working_dir': original_working_dir
+                    }, room=sid)
+                else:
+                    self.logger.warning(f"[GIT-BRANCH-DEBUG] Git command failed: {result.stderr}")
+                    await self.sio.emit('git_branch_response', {
+                        'success': False,
+                        'error': 'Not a git repository',
+                        'working_dir': working_dir,
+                        'original_working_dir': original_working_dir,
+                        'git_error': result.stderr
+                    }, room=sid)
+                    
+            except Exception as e:
+                self.logger.error(f"[GIT-BRANCH-DEBUG] Exception in get_git_branch: {e}")
+                import traceback
+                self.logger.error(f"[GIT-BRANCH-DEBUG] Stack trace: {traceback.format_exc()}")
+                await self.sio.emit('git_branch_response', {
+                    'success': False,
+                    'error': str(e),
+                    'working_dir': working_dir,
+                    'original_working_dir': original_working_dir
+                }, room=sid)
+        
+        @self.sio.event
+        async def check_file_tracked(sid, data):
+            """Check if a file is tracked by git"""
+            import subprocess
+            try:
+                file_path = data.get('file_path')
+                working_dir = data.get('working_dir', os.getcwd())
+                
+                if not file_path:
+                    await self.sio.emit('file_tracked_response', {
+                        'success': False,
+                        'error': 'file_path is required',
+                        'file_path': file_path
+                    }, room=sid)
+                    return
+                
+                # Use git ls-files to check if file is tracked
+                result = subprocess.run(
+                    ["git", "-C", working_dir, "ls-files", "--", file_path],
+                    capture_output=True,
+                    text=True
+                )
+                
+                is_tracked = result.returncode == 0 and result.stdout.strip()
+                
+                await self.sio.emit('file_tracked_response', {
+                    'success': True,
+                    'file_path': file_path,
+                    'working_dir': working_dir,
+                    'is_tracked': bool(is_tracked)
+                }, room=sid)
+                    
+            except Exception as e:
+                self.logger.error(f"Error checking file tracked status: {e}")
+                await self.sio.emit('file_tracked_response', {
+                    'success': False,
+                    'error': str(e),
+                    'file_path': data.get('file_path', 'unknown')
+                }, room=sid)
+        
+        @self.sio.event
+        async def read_file(sid, data):
+            """Read file contents safely"""
+            try:
+                file_path = data.get('file_path')
+                working_dir = data.get('working_dir', os.getcwd())
+                max_size = data.get('max_size', SystemLimits.MAX_FILE_SIZE)
+                
+                if not file_path:
+                    await self.sio.emit('file_content_response', {
+                        'success': False,
+                        'error': 'file_path is required',
+                        'file_path': file_path
+                    }, room=sid)
+                    return
+                
+                # Use the shared file reading logic
+                result = await self._read_file_safely(file_path, working_dir, max_size)
+                
+                # Send the result back to the client
+                await self.sio.emit('file_content_response', result, room=sid)
+                        
+            except Exception as e:
+                self.logger.error(f"Error reading file: {e}")
+                await self.sio.emit('file_content_response', {
+                    'success': False,
+                    'error': str(e),
+                    'file_path': data.get('file_path', 'unknown')
+                }, room=sid)
+        
+        @self.sio.event
+        async def check_git_status(sid, data):
+            """Check git status for a file to determine if git diff icons should be shown"""
+            import subprocess
+            try:
+                file_path = data.get('file_path')
+                working_dir = data.get('working_dir', os.getcwd())
+                
+                self.logger.info(f"[GIT-STATUS-DEBUG] check_git_status called with file_path: {repr(file_path)}, working_dir: {repr(working_dir)}")
+                
+                if not file_path:
+                    await self.sio.emit('git_status_response', {
+                        'success': False,
+                        'error': 'file_path is required',
+                        'file_path': file_path
+                    }, room=sid)
+                    return
+                
+                # Validate and sanitize working_dir
+                original_working_dir = working_dir
+                if not working_dir or working_dir == 'Unknown' or working_dir.strip() == '' or working_dir == '.':
+                    working_dir = os.getcwd()
+                    self.logger.info(f"[GIT-STATUS-DEBUG] working_dir was invalid ({repr(original_working_dir)}), using cwd: {working_dir}")
+                else:
+                    self.logger.info(f"[GIT-STATUS-DEBUG] Using provided working_dir: {working_dir}")
+                
+                # Check if the working directory exists and is a directory
+                if not os.path.exists(working_dir):
+                    self.logger.warning(f"[GIT-STATUS-DEBUG] Directory does not exist: {working_dir}")
+                    await self.sio.emit('git_status_response', {
+                        'success': False,
+                        'error': f'Directory does not exist: {working_dir}',
+                        'file_path': file_path,
+                        'working_dir': working_dir,
+                        'original_working_dir': original_working_dir
+                    }, room=sid)
+                    return
+                    
+                if not os.path.isdir(working_dir):
+                    self.logger.warning(f"[GIT-STATUS-DEBUG] Path is not a directory: {working_dir}")
+                    await self.sio.emit('git_status_response', {
+                        'success': False,
+                        'error': f'Path is not a directory: {working_dir}',
+                        'file_path': file_path,
+                        'working_dir': working_dir,
+                        'original_working_dir': original_working_dir
+                    }, room=sid)
+                    return
+                
+                # Check if this is a git repository
+                self.logger.info(f"[GIT-STATUS-DEBUG] Checking if {working_dir} is a git repository")
+                git_check = subprocess.run(
+                    ["git", "-C", working_dir, "rev-parse", "--git-dir"],
+                    capture_output=True,
+                    text=True
+                )
+                
+                if git_check.returncode != 0:
+                    self.logger.info(f"[GIT-STATUS-DEBUG] Not a git repository: {working_dir}")
+                    await self.sio.emit('git_status_response', {
+                        'success': False,
+                        'error': 'Not a git repository',
+                        'file_path': file_path,
+                        'working_dir': working_dir,
+                        'original_working_dir': original_working_dir
+                    }, room=sid)
+                    return
+                
+                # Determine if the file path should be made relative to git root
+                file_path_for_git = file_path
+                if os.path.isabs(file_path):
+                    # Get git root to make path relative if needed
+                    git_root_result = subprocess.run(
+                        ["git", "-C", working_dir, "rev-parse", "--show-toplevel"],
+                        capture_output=True,
+                        text=True
+                    )
+                    
+                    if git_root_result.returncode == 0:
+                        git_root = git_root_result.stdout.strip()
+                        try:
+                            file_path_for_git = os.path.relpath(file_path, git_root)
+                            self.logger.info(f"[GIT-STATUS-DEBUG] Made file path relative to git root: {file_path_for_git}")
+                        except ValueError:
+                            # File is not under git root - keep original path
+                            self.logger.info(f"[GIT-STATUS-DEBUG] File not under git root, keeping original path: {file_path}")
+                            pass
+                
+                # Check if the file exists
+                full_path = file_path if os.path.isabs(file_path) else os.path.join(working_dir, file_path)
+                if not os.path.exists(full_path):
+                    self.logger.warning(f"[GIT-STATUS-DEBUG] File does not exist: {full_path}")
+                    await self.sio.emit('git_status_response', {
+                        'success': False,
+                        'error': f'File does not exist: {file_path}',
+                        'file_path': file_path,
+                        'working_dir': working_dir,
+                        'original_working_dir': original_working_dir
+                    }, room=sid)
+                    return
+                
+                # Check git status for the file - this succeeds if git knows about the file
+                # (either tracked, modified, staged, etc.)
+                self.logger.info(f"[GIT-STATUS-DEBUG] Checking git status for file: {file_path_for_git}")
+                git_status_result = subprocess.run(
+                    ["git", "-C", working_dir, "status", "--porcelain", file_path_for_git],
+                    capture_output=True,
+                    text=True
+                )
+                
+                self.logger.info(f"[GIT-STATUS-DEBUG] Git status result: returncode={git_status_result.returncode}, stdout={repr(git_status_result.stdout)}, stderr={repr(git_status_result.stderr)}")
+                
+                # Also check if file is tracked by git (alternative approach)
+                ls_files_result = subprocess.run(
+                    ["git", "-C", working_dir, "ls-files", file_path_for_git],
+                    capture_output=True,
+                    text=True
+                )
+                
+                is_tracked = ls_files_result.returncode == 0 and ls_files_result.stdout.strip()
+                has_status = git_status_result.returncode == 0
+                
+                self.logger.info(f"[GIT-STATUS-DEBUG] File tracking status: is_tracked={is_tracked}, has_status={has_status}")
+                
+                # Success if git knows about the file (either tracked or has status changes)
+                if is_tracked or has_status:
+                    self.logger.info(f"[GIT-STATUS-DEBUG] Git status check successful for {file_path}")
+                    await self.sio.emit('git_status_response', {
+                        'success': True,
+                        'file_path': file_path,
+                        'working_dir': working_dir,
+                        'original_working_dir': original_working_dir,
+                        'is_tracked': is_tracked,
+                        'has_changes': bool(git_status_result.stdout.strip()) if has_status else False
+                    }, room=sid)
+                else:
+                    self.logger.info(f"[GIT-STATUS-DEBUG] File {file_path} is not tracked by git")
+                    await self.sio.emit('git_status_response', {
+                        'success': False,
+                        'error': 'File is not tracked by git',
+                        'file_path': file_path,
+                        'working_dir': working_dir,
+                        'original_working_dir': original_working_dir,
+                        'is_tracked': False
+                    }, room=sid)
+                    
+            except Exception as e:
+                self.logger.error(f"[GIT-STATUS-DEBUG] Exception in check_git_status: {e}")
+                import traceback
+                self.logger.error(f"[GIT-STATUS-DEBUG] Stack trace: {traceback.format_exc()}")
+                await self.sio.emit('git_status_response', {
+                    'success': False,
+                    'error': str(e),
+                    'file_path': data.get('file_path', 'unknown'),
+                    'working_dir': data.get('working_dir', 'unknown')
+                }, room=sid)
+
+        @self.sio.event
+        async def git_add_file(sid, data):
+            """Add file to git tracking"""
+            import subprocess
+            try:
+                file_path = data.get('file_path')
+                working_dir = data.get('working_dir', os.getcwd())
+                
+                self.logger.info(f"[GIT-ADD-DEBUG] git_add_file called with file_path: {repr(file_path)}, working_dir: {repr(working_dir)} (type: {type(working_dir)})")
+                
+                if not file_path:
+                    await self.sio.emit('git_add_response', {
+                        'success': False,
+                        'error': 'file_path is required',
+                        'file_path': file_path
+                    }, room=sid)
+                    return
+                
+                # Validate and sanitize working_dir
+                original_working_dir = working_dir
+                if not working_dir or working_dir == 'Unknown' or working_dir.strip() == '' or working_dir == '.':
+                    working_dir = os.getcwd()
+                    self.logger.info(f"[GIT-ADD-DEBUG] working_dir was invalid ({repr(original_working_dir)}), using cwd: {working_dir}")
+                else:
+                    self.logger.info(f"[GIT-ADD-DEBUG] Using provided working_dir: {working_dir}")
+                
+                # Validate that the directory exists and is a valid path
+                if not os.path.exists(working_dir):
+                    self.logger.warning(f"[GIT-ADD-DEBUG] Directory does not exist: {working_dir}")
+                    await self.sio.emit('git_add_response', {
+                        'success': False,
+                        'error': f'Directory does not exist: {working_dir}',
+                        'file_path': file_path,
+                        'working_dir': working_dir,
+                        'original_working_dir': original_working_dir
+                    }, room=sid)
+                    return
+                    
+                if not os.path.isdir(working_dir):
+                    self.logger.warning(f"[GIT-ADD-DEBUG] Path is not a directory: {working_dir}")
+                    await self.sio.emit('git_add_response', {
+                        'success': False,
+                        'error': f'Path is not a directory: {working_dir}',
+                        'file_path': file_path,
+                        'working_dir': working_dir,
+                        'original_working_dir': original_working_dir
+                    }, room=sid)
+                    return
+                
+                self.logger.info(f"[GIT-ADD-DEBUG] Running git add command in directory: {working_dir}")
+                
+                # Use git add to track the file
+                result = subprocess.run(
+                    ["git", "-C", working_dir, "add", file_path],
+                    capture_output=True,
+                    text=True
+                )
+                
+                self.logger.info(f"[GIT-ADD-DEBUG] Git add result: returncode={result.returncode}, stdout={repr(result.stdout)}, stderr={repr(result.stderr)}")
+                
+                if result.returncode == 0:
+                    self.logger.info(f"[GIT-ADD-DEBUG] Successfully added {file_path} to git in {working_dir}")
+                    await self.sio.emit('git_add_response', {
+                        'success': True,
+                        'file_path': file_path,
+                        'working_dir': working_dir,
+                        'original_working_dir': original_working_dir,
+                        'message': 'File successfully added to git tracking'
+                    }, room=sid)
+                else:
+                    error_message = result.stderr.strip() or 'Unknown git error'
+                    self.logger.warning(f"[GIT-ADD-DEBUG] Git add failed: {error_message}")
+                    await self.sio.emit('git_add_response', {
+                        'success': False,
+                        'error': f'Git add failed: {error_message}',
+                        'file_path': file_path,
+                        'working_dir': working_dir,
+                        'original_working_dir': original_working_dir
+                    }, room=sid)
+                    
+            except Exception as e:
+                self.logger.error(f"[GIT-ADD-DEBUG] Exception in git_add_file: {e}")
+                import traceback
+                self.logger.error(f"[GIT-ADD-DEBUG] Stack trace: {traceback.format_exc()}")
+                await self.sio.emit('git_add_response', {
+                    'success': False,
+                    'error': str(e),
+                    'file_path': data.get('file_path', 'unknown'),
+                    'working_dir': data.get('working_dir', 'unknown')
+                }, room=sid)
+            
+    async def _send_current_status(self, sid: str):
+        """Send current system status to a client."""
+        try:
+            status = {
+                "type": "system.status",
+                "timestamp": datetime.utcnow().isoformat() + "Z",
+                "data": {
+                    "session_id": self.session_id,
+                    "session_start": self.session_start,
+                    "claude_status": self.claude_status,
+                    "claude_pid": self.claude_pid,
+                    "connected_clients": len(self.clients),
+                    "websocket_port": self.port,
+                    "instance_info": {
+                        "port": self.port,
+                        "host": self.host,
+                        "working_dir": os.getcwd() if self.session_id else None
+                    }
+                }
+            }
+            await self.sio.emit('claude_event', status, room=sid)
+            self.logger.debug("Sent status to client")
+        except Exception as e:
+            self.logger.error(f"Failed to send status to client: {e}")
+            raise
+            
+    async def _send_event_history(self, sid: str, event_types: list = None, limit: int = 50):
+        """Send event history to a specific client.
+        
+        WHY: When clients connect to the dashboard, they need context from recent events
+        to understand what's been happening. This sends the most recent events in
+        chronological order (oldest first) so the dashboard displays them properly.
+        
+        Args:
+            sid: Socket.IO session ID of the client
+            event_types: Optional list of event types to filter by
+            limit: Maximum number of events to send (default: 50)
+        """
+        try:
+            if not self.event_history:
+                self.logger.debug(f"No event history to send to client {sid}")
+                return
+                
+            # Limit to reasonable number to avoid overwhelming client
+            limit = min(limit, 100)
+            
+            # Get the most recent events, filtered by type if specified
+            history = []
+            for event in reversed(self.event_history):
+                if not event_types or event.get("type") in event_types:
+                    history.append(event)
+                    if len(history) >= limit:
+                        break
+            
+            # Reverse to get chronological order (oldest first)
+            history = list(reversed(history))
+            
+            if history:
+                # Send as 'history' event that the client expects
+                await self.sio.emit('history', {
+                    "events": history,
+                    "count": len(history),
+                    "total_available": len(self.event_history)
+                }, room=sid)
+                
+                self.logger.info(f"📚 Sent {len(history)} historical events to client {sid}")
+            else:
+                self.logger.debug(f"No matching events found for client {sid} with filters: {event_types}")
+                
+        except Exception as e:
+            self.logger.error(f"❌ Failed to send event history to client {sid}: {e}")
+            import traceback
+            self.logger.error(f"Stack trace: {traceback.format_exc()}")
+            
+    def broadcast_event(self, event_type: str, data: Dict[str, Any]):
+        """Broadcast an event to all connected clients."""
+        if not SOCKETIO_AVAILABLE:
+            self.logger.debug(f"⚠️  Socket.IO broadcast skipped - packages not available")
+            return
+            
+        event = {
+            "type": event_type,
+            "timestamp": datetime.utcnow().isoformat() + "Z",
+            "data": data
+        }
+        
+        self.logger.info(f"📤 BROADCASTING EVENT: {event_type}")
+        self.logger.debug(f"📄 Event data: {json.dumps(data, indent=2)[:200]}...")
+        
+        # Store in history
+        self.event_history.append(event)
+        self.logger.debug(f"📚 Event stored in history (total: {len(self.event_history)})")
+        
+        # Check if we have clients and event loop
+        if not self.clients:
+            self.logger.warning(f"⚠️  No Socket.IO clients connected - event will not be delivered")
+            return
+            
+        if not self.loop or not self.sio:
+            self.logger.error(f"❌ No event loop or Socket.IO instance available - cannot broadcast event")
+            return
+            
+        self.logger.info(f"🎯 Broadcasting to {len(self.clients)} clients via event loop")
+        
+        # Broadcast to clients with timeout and error handling
+        try:
+            # Check if the event loop is still running and not closed
+            if self.loop and not self.loop.is_closed() and self.loop.is_running():
+                future = asyncio.run_coroutine_threadsafe(
+                    self.sio.emit('claude_event', event),
+                    self.loop
+                )
+                # Wait for completion with timeout to detect issues
+                try:
+                    future.result(timeout=TimeoutConfig.QUICK_TIMEOUT)
+                    self.logger.debug(f"📨 Successfully broadcasted {event_type} to {len(self.clients)} clients")
+                except asyncio.TimeoutError:
+                    self.logger.warning(f"⏰ Broadcast timeout for event {event_type} - continuing anyway")
+                except Exception as emit_error:
+                    self.logger.error(f"❌ Broadcast emit error for {event_type}: {emit_error}")
+            else:
+                self.logger.warning(f"⚠️ Event loop not available for broadcast of {event_type} - event loop closed or not running")
+        except Exception as e:
+            self.logger.error(f"❌ Failed to submit broadcast to event loop: {e}")
+            import traceback
+            self.logger.error(f"Stack trace: {traceback.format_exc()}")
+            
+    # Convenience methods for common events (same interface as WebSocketServer)
+    
+    def session_started(self, session_id: str, launch_method: str, working_dir: str):
+        """Notify that a session has started."""
+        self.session_id = session_id
+        self.session_start = datetime.utcnow().isoformat() + "Z"
+        self.broadcast_event("session.start", {
+            "session_id": session_id,
+            "start_time": self.session_start,
+            "launch_method": launch_method,
+            "working_directory": working_dir,
+            "websocket_port": self.port,
+            "instance_info": {
+                "port": self.port,
+                "host": self.host,
+                "working_dir": working_dir
+            }
+        })
+        
+    def session_ended(self):
+        """Notify that a session has ended."""
+        if self.session_id:
+            duration = None
+            if self.session_start:
+                start = datetime.fromisoformat(self.session_start.replace("Z", "+00:00"))
+                duration = (datetime.utcnow() - start.replace(tzinfo=None)).total_seconds()
+                
+            self.broadcast_event("session.end", {
+                "session_id": self.session_id,
+                "end_time": datetime.utcnow().isoformat() + "Z",
+                "duration_seconds": duration
+            })
+            
+        self.session_id = None
+        self.session_start = None
+        
+    def claude_status_changed(self, status: str, pid: Optional[int] = None, message: str = ""):
+        """Notify Claude status change."""
+        self.claude_status = status
+        self.claude_pid = pid
+        self.broadcast_event("claude.status", {
+            "status": status,
+            "pid": pid,
+            "message": message
+        })
+        
+    def claude_output(self, content: str, stream: str = "stdout"):
+        """Broadcast Claude output."""
+        self.broadcast_event("claude.output", {
+            "content": content,
+            "stream": stream
+        })
+        
+    def agent_delegated(self, agent: str, task: str, status: str = "started"):
+        """Notify agent delegation."""
+        self.broadcast_event("agent.delegation", {
+            "agent": agent,
+            "task": task,
+            "status": status,
+            "timestamp": datetime.utcnow().isoformat() + "Z"
+        })
+        
+    def todo_updated(self, todos: List[Dict[str, Any]]):
+        """Notify todo list update."""
+        stats = {
+            "total": len(todos),
+            "completed": sum(1 for t in todos if t.get("status") == "completed"),
+            "in_progress": sum(1 for t in todos if t.get("status") == "in_progress"),
+            "pending": sum(1 for t in todos if t.get("status") == "pending")
+        }
+        
+        self.broadcast_event("todo.update", {
+            "todos": todos,
+            "stats": stats
+        })
+        
+    def ticket_created(self, ticket_id: str, title: str, priority: str = "medium"):
+        """Notify ticket creation."""
+        self.broadcast_event("ticket.created", {
+            "id": ticket_id,
+            "title": title,
+            "priority": priority,
+            "created_at": datetime.utcnow().isoformat() + "Z"
+        })
+        
+    def memory_loaded(self, agent_id: str, memory_size: int, sections_count: int):
+        """Notify when agent memory is loaded from file."""
+        self.broadcast_event("memory:loaded", {
+            "agent_id": agent_id,
+            "memory_size": memory_size,
+            "sections_count": sections_count,
+            "timestamp": datetime.utcnow().isoformat() + "Z"
+        })
+        
+    def memory_created(self, agent_id: str, template_type: str):
+        """Notify when new agent memory is created from template."""
+        self.broadcast_event("memory:created", {
+            "agent_id": agent_id,
+            "template_type": template_type,
+            "timestamp": datetime.utcnow().isoformat() + "Z"
+        })
+        
+    def memory_updated(self, agent_id: str, learning_type: str, content: str, section: str):
+        """Notify when learning is added to agent memory."""
+        self.broadcast_event("memory:updated", {
+            "agent_id": agent_id,
+            "learning_type": learning_type,
+            "content": content,
+            "section": section,
+            "timestamp": datetime.utcnow().isoformat() + "Z"
+        })
+        
+    def memory_injected(self, agent_id: str, context_size: int):
+        """Notify when agent memory is injected into context."""
+        self.broadcast_event("memory:injected", {
+            "agent_id": agent_id,
+            "context_size": context_size,
+            "timestamp": datetime.utcnow().isoformat() + "Z"
+        })
+    
+    # ================================================================================
+    # Interface Adapter Methods
+    # ================================================================================
+    # These methods adapt the existing implementation to comply with SocketIOServiceInterface
+    
+    async def start(self, host: str = "localhost", port: int = 8765) -> None:
+        """Start the WebSocket server (async adapter).
+        
+        WHY: The interface expects async methods, but our implementation uses
+        synchronous start with background threads. This adapter provides compatibility.
+        
+        Args:
+            host: Host to bind to
+            port: Port to listen on
+        """
+        self.host = host
+        self.port = port
+        # Call the synchronous start method
+        self.start_sync()
+    
+    async def stop(self) -> None:
+        """Stop the WebSocket server (async adapter).
+        
+        WHY: The interface expects async methods. This adapter wraps the
+        synchronous stop method for interface compliance.
+        """
+        # Call the synchronous stop method
+        self.stop_sync()
+    
+    async def emit(self, event: str, data: Any, room: Optional[str] = None) -> None:
+        """Emit an event to connected clients.
+        
+        WHY: Provides interface compliance by wrapping broadcast_event with
+        async signature and room support.
+        
+        Args:
+            event: Event name
+            data: Event data
+            room: Optional room to target (not supported in current implementation)
+        """
+        if room:
+            self.logger.warning(f"Room-based emit not supported, broadcasting to all: {event}")
+        
+        # Use existing broadcast_event method
+        self.broadcast_event(event, data)
+    
+    async def broadcast(self, event: str, data: Any) -> None:
+        """Broadcast event to all connected clients.
+        
+        WHY: Provides interface compliance with async signature.
+        
+        Args:
+            event: Event name
+            data: Event data
+        """
+        self.broadcast_event(event, data)
+    
+    def get_connection_count(self) -> int:
+        """Get number of connected clients.
+        
+        WHY: Provides interface compliance for monitoring connections.
+        
+        Returns:
+            Number of active connections
+        """
+        return len(self.clients)
+    
+    def is_running(self) -> bool:
+        """Check if server is running.
+        
+        WHY: Provides interface compliance for status checking.
+        
+        Returns:
+            True if server is active
+        """
+        return self.running
+
+
+# Global instance for easy access
+_socketio_server: Optional[SocketIOServer] = None
+
+
+def get_socketio_server() -> SocketIOServer:
+    """Get or create the global Socket.IO server instance.
+    
+    WHY: In exec mode, a persistent Socket.IO server may already be running
+    in a separate process. We need to detect this and create a client proxy
+    instead of trying to start another server.
+    """
+    global _socketio_server
+    if _socketio_server is None:
+        # Check if a Socket.IO server is already running on the default port
+        import socket
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.settimeout(0.5)
+                result = s.connect_ex(('127.0.0.1', 8765))
+                if result == 0:
+                    # Server is already running - create a client proxy
+                    _socketio_server = SocketIOClientProxy(port=8765)
+                else:
+                    # No server running - create a real server
+                    _socketio_server = SocketIOServer()
+        except Exception:
+            # On any error, create a real server
+            _socketio_server = SocketIOServer()
+        
+    return _socketio_server
+
+
+def start_socketio_server():
+    """Start the global Socket.IO server."""
+    server = get_socketio_server()
+    server.start_sync()
+    return server
+
+
+def stop_socketio_server():
+    """Stop the global Socket.IO server."""
+    global _socketio_server
+    if _socketio_server:
+        _socketio_server.stop_sync()
+        _socketio_server = None