claude-mpm 4.2.21__py3-none-any.whl → 4.2.23__py3-none-any.whl

claude_mpm/VERSION

@@ -1 +1 @@
-4.2.21
+4.2.23

claude_mpm/cli/commands/monitor.py

@@ -91,8 +91,11 @@ class MonitorCommand(BaseCommand):
             host=host, port=port, daemon_mode=daemon_mode
         )
 
+        # Get force restart flag
+        force_restart = getattr(args, "force", False)
+        
         # Check if already running
-        if self.daemon.lifecycle.is_running():
+        if self.daemon.lifecycle.is_running() and not force_restart:
             existing_pid = self.daemon.lifecycle.get_pid()
             return CommandResult.success_result(
                 f"Unified monitor daemon already running with PID {existing_pid}",
@@ -103,14 +106,46 @@ class MonitorCommand(BaseCommand):
                 },
             )
 
-        # Start the daemon
-        if self.daemon.start():
-            mode_info = " in background" if daemon_mode else " in foreground"
+        # Start the daemon (with force restart if specified)
+        if self.daemon.start(force_restart=force_restart):
+            # For daemon mode, verify it actually started
+            if daemon_mode:
+                # Give it a moment to fully initialize
+                import time
+                time.sleep(0.5)
+                
+                # Check if it's actually running
+                if not self.daemon.lifecycle.is_running():
+                    return CommandResult.error_result(
+                        "Monitor daemon failed to start. Check ~/.claude-mpm/monitor-daemon.log for details."
+                    )
+                
+                # Get the actual PID
+                actual_pid = self.daemon.lifecycle.get_pid()
+                mode_info = f" in background (PID: {actual_pid})"
+            else:
+                mode_info = " in foreground"
+            
             return CommandResult.success_result(
                 f"Unified monitor daemon started on {host}:{port}{mode_info}",
                 data={"url": f"http://{host}:{port}", "port": port, "mode": mode_str},
             )
-        return CommandResult.error_result("Failed to start unified monitor daemon")
+        
+        # Check if error was due to port already in use
+        import socket
+        try:
+            test_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            test_sock.connect((host, port))
+            test_sock.close()
+            return CommandResult.error_result(
+                f"Port {port} is already in use. Try 'claude-mpm monitor stop' first or use a different port."
+            )
+        except:
+            pass
+        
+        return CommandResult.error_result(
+            "Failed to start unified monitor daemon. Check ~/.claude-mpm/monitor-daemon.log for details."
+        )
 
     def _stop_monitor(self, args) -> CommandResult:
         """Stop the unified monitor daemon."""

claude_mpm/services/cli/unified_dashboard_manager.py

@@ -75,7 +75,8 @@ class UnifiedDashboardManager(IUnifiedDashboardManager):
         self._lock = threading.Lock()
 
     def start_dashboard(
-        self, port: int = 8765, background: bool = False, open_browser: bool = True
+        self, port: int = 8765, background: bool = False, open_browser: bool = True,
+        force_restart: bool = False
     ) -> Tuple[bool, bool]:
         """
         Start the dashboard using unified daemon.
@@ -84,30 +85,41 @@ class UnifiedDashboardManager(IUnifiedDashboardManager):
             port: Port to run dashboard on
             background: Whether to run in background mode
             open_browser: Whether to open browser automatically
+            force_restart: If True, restart existing service if it's ours
 
         Returns:
             Tuple of (success, browser_opened)
         """
         try:
-            # Check if already running
-            if self.is_dashboard_running(port):
-                self.logger.info(f"Dashboard already running on port {port}")
+            # Create daemon instance to check service status
+            daemon = UnifiedMonitorDaemon(
+                host="localhost", port=port, daemon_mode=background
+            )
+            
+            # Check if it's our service running
+            is_ours, pid = daemon.lifecycle.is_our_service("localhost")
+            
+            if is_ours and not force_restart:
+                # Our service is already running, just open browser if needed
+                self.logger.info(f"Our dashboard already running on port {port} (PID: {pid})")
                 browser_opened = False
                 if open_browser:
                     browser_opened = self.open_browser(self.get_dashboard_url(port))
                 return True, browser_opened
+            elif is_ours and force_restart:
+                self.logger.info(f"Force restarting our dashboard on port {port} (PID: {pid})")
+            elif self.is_dashboard_running(port) and not force_restart:
+                # Different service is using the port
+                self.logger.warning(f"Port {port} is in use by a different service")
+                return False, False
 
             self.logger.info(
-                f"Starting unified dashboard on port {port} (background: {background})"
+                f"Starting unified dashboard on port {port} (background: {background}, force_restart: {force_restart})"
             )
 
             if background:
-                # Start daemon in background mode
-                daemon = UnifiedMonitorDaemon(
-                    host="localhost", port=port, daemon_mode=True
-                )
-
-                success = daemon.start()
+                # Start daemon in background mode with force restart if needed
+                success = daemon.start(force_restart=force_restart)
                 if success:
                     with self._lock:
                         self._background_daemons[port] = daemon
@@ -293,7 +305,7 @@ class UnifiedDashboardManager(IUnifiedDashboardManager):
         return self.port_manager.find_available_port(preferred_port)
 
     def start_server(
-        self, port: Optional[int] = None, timeout: int = 30
+        self, port: Optional[int] = None, timeout: int = 30, force_restart: bool = True
     ) -> Tuple[bool, DashboardInfo]:
         """
         Start the server (compatibility method for SocketIOManager interface).
@@ -301,6 +313,7 @@ class UnifiedDashboardManager(IUnifiedDashboardManager):
         Args:
             port: Port to use (finds available if None)
             timeout: Timeout for startup
+            force_restart: If True, restart existing service if it's ours
 
         Returns:
             Tuple of (success, DashboardInfo)
@@ -308,8 +321,9 @@ class UnifiedDashboardManager(IUnifiedDashboardManager):
         if port is None:
             port = self.find_available_port()
 
+        # Use force_restart to ensure we're using the latest code
         success, browser_opened = self.start_dashboard(
-            port=port, background=True, open_browser=False
+            port=port, background=True, open_browser=False, force_restart=force_restart
         )
 
         if success:

claude_mpm/services/monitor/daemon.py

@@ -57,9 +57,11 @@ class UnifiedMonitorDaemon:
         self.daemon_mode = daemon_mode
         self.logger = get_logger(__name__)
 
-        # Daemon management
+        # Daemon management with port for verification
         self.lifecycle = DaemonLifecycle(
-            pid_file=pid_file or self._get_default_pid_file(), log_file=log_file
+            pid_file=pid_file or self._get_default_pid_file(), 
+            log_file=log_file,
+            port=port
         )
 
         # Core server
@@ -79,28 +81,82 @@ class UnifiedMonitorDaemon:
         claude_mpm_dir.mkdir(exist_ok=True)
         return str(claude_mpm_dir / "monitor-daemon.pid")
 
-    def start(self) -> bool:
+    def start(self, force_restart: bool = False) -> bool:
         """Start the unified monitor daemon.
 
+        Args:
+            force_restart: If True, restart existing service if it's ours
+
         Returns:
             True if started successfully, False otherwise
         """
         try:
             if self.daemon_mode:
-                return self._start_daemon()
-            return self._start_foreground()
+                return self._start_daemon(force_restart=force_restart)
+            return self._start_foreground(force_restart=force_restart)
         except Exception as e:
             self.logger.error(f"Failed to start unified monitor daemon: {e}")
             return False
 
-    def _start_daemon(self) -> bool:
-        """Start as background daemon process."""
+    def _start_daemon(self, force_restart: bool = False) -> bool:
+        """Start as background daemon process.
+        
+        Args:
+            force_restart: If True, restart existing service if it's ours
+        """
         self.logger.info("Starting unified monitor daemon in background mode")
 
         # Check if already running
         if self.lifecycle.is_running():
             existing_pid = self.lifecycle.get_pid()
-            self.logger.warning(f"Daemon already running with PID {existing_pid}")
+            
+            if force_restart:
+                # Check if it's our service
+                is_ours, pid = self.lifecycle.is_our_service(self.host)
+                if is_ours:
+                    self.logger.info(f"Force restarting our existing daemon (PID: {pid or existing_pid})")
+                    # Stop the existing daemon
+                    if self.lifecycle.stop_daemon():
+                        # Wait a moment for port to be released
+                        time.sleep(2)
+                    else:
+                        self.logger.error("Failed to stop existing daemon for restart")
+                        return False
+                else:
+                    self.logger.warning(f"Daemon already running with PID {existing_pid}, but it's not our service")
+                    return False
+            else:
+                self.logger.warning(f"Daemon already running with PID {existing_pid}")
+                return False
+        
+        # Check for orphaned processes (service running but no PID file)
+        elif force_restart:
+            is_ours, pid = self.lifecycle.is_our_service(self.host)
+            if is_ours and pid:
+                self.logger.info(f"Found orphaned claude-mpm service (PID: {pid}), force restarting")
+                # Try to kill the orphaned process
+                try:
+                    os.kill(pid, signal.SIGTERM)
+                    # Wait for it to exit
+                    for _ in range(10):
+                        try:
+                            os.kill(pid, 0)  # Check if still exists
+                            time.sleep(0.5)
+                        except ProcessLookupError:
+                            break
+                    else:
+                        # Force kill if still running
+                        os.kill(pid, signal.SIGKILL)
+                        time.sleep(1)
+                except Exception as e:
+                    self.logger.error(f"Failed to kill orphaned process: {e}")
+                    return False
+        
+        # Verify port is available before forking
+        port_available, error_msg = self.lifecycle.verify_port_available(self.host)
+        if not port_available:
+            self.logger.error(error_msg)
+            print(f"Error: {error_msg}", file=sys.stderr)
             return False
 
         # Wait for any pre-warming threads to complete before forking
@@ -112,19 +168,73 @@ class UnifiedMonitorDaemon:
             return False
 
         # Start the server in daemon mode
-        return self._run_server()
+        # This will run in the child process
+        try:
+            result = self._run_server()
+            if not result:
+                # Report failure before exiting
+                self.lifecycle._report_startup_error("Failed to start server")
+            return result
+        except Exception as e:
+            # Report any exceptions during startup
+            self.lifecycle._report_startup_error(f"Server startup exception: {e}")
+            raise
 
-    def _start_foreground(self) -> bool:
-        """Start in foreground mode."""
+    def _start_foreground(self, force_restart: bool = False) -> bool:
+        """Start in foreground mode.
+        
+        Args:
+            force_restart: If True, restart existing service if it's ours
+        """
         self.logger.info(f"Starting unified monitor daemon on {self.host}:{self.port}")
 
         # Check if already running (check PID file even in foreground mode)
         if self.lifecycle.is_running():
             existing_pid = self.lifecycle.get_pid()
-            self.logger.warning(
-                f"Monitor daemon already running with PID {existing_pid}"
-            )
-            return False
+            
+            if force_restart:
+                # Check if it's our service
+                is_ours, pid = self.lifecycle.is_our_service(self.host)
+                if is_ours:
+                    self.logger.info(f"Force restarting our existing daemon (PID: {pid or existing_pid})")
+                    # Stop the existing daemon
+                    if self.lifecycle.stop_daemon():
+                        # Wait a moment for port to be released
+                        time.sleep(2)
+                    else:
+                        self.logger.error("Failed to stop existing daemon for restart")
+                        return False
+                else:
+                    self.logger.warning(f"Monitor daemon already running with PID {existing_pid}, but it's not our service")
+                    return False
+            else:
+                self.logger.warning(
+                    f"Monitor daemon already running with PID {existing_pid}"
+                )
+                return False
+        
+        # Check for orphaned processes (service running but no PID file)
+        elif force_restart:
+            is_ours, pid = self.lifecycle.is_our_service(self.host)
+            if is_ours and pid:
+                self.logger.info(f"Found orphaned claude-mpm service (PID: {pid}), force restarting")
+                # Try to kill the orphaned process
+                try:
+                    os.kill(pid, signal.SIGTERM)
+                    # Wait for it to exit
+                    for _ in range(10):
+                        try:
+                            os.kill(pid, 0)  # Check if still exists
+                            time.sleep(0.5)
+                        except ProcessLookupError:
+                            break
+                    else:
+                        # Force kill if still running
+                        os.kill(pid, signal.SIGKILL)
+                        time.sleep(1)
+                except Exception as e:
+                    self.logger.error(f"Failed to kill orphaned process: {e}")
+                    return False
 
         # Setup signal handlers for graceful shutdown
         self._setup_signal_handlers()
@@ -140,11 +250,17 @@ class UnifiedMonitorDaemon:
         try:
             # Ensure components exist before starting
             if not self.health_monitor:
-                self.logger.error("Health monitor not initialized")
+                error_msg = "Health monitor not initialized"
+                self.logger.error(error_msg)
+                if self.daemon_mode:
+                    self.lifecycle._report_startup_error(error_msg)
                 return False
 
             if not self.server:
-                self.logger.error("Server not initialized")
+                error_msg = "Server not initialized"
+                self.logger.error(error_msg)
+                if self.daemon_mode:
+                    self.lifecycle._report_startup_error(error_msg)
                 return False
 
             # Start health monitoring
@@ -153,11 +269,18 @@ class UnifiedMonitorDaemon:
             # Start the unified server
             success = self.server.start()
             if not success:
-                self.logger.error("Failed to start unified monitor server")
+                error_msg = "Failed to start unified monitor server"
+                self.logger.error(error_msg)
+                if self.daemon_mode:
+                    self.lifecycle._report_startup_error(error_msg)
                 return False
 
             self.running = True
             self.logger.info("Unified monitor daemon started successfully")
+            
+            # Report successful startup to parent (for daemon mode)
+            if self.daemon_mode:
+                self.lifecycle._report_startup_success()
 
             # Keep running until shutdown
             if self.daemon_mode:

claude_mpm/services/monitor/management/lifecycle.py

@@ -15,10 +15,13 @@ DESIGN DECISIONS:
 
 import os
 import signal
+import socket
 import sys
+import tempfile
 import time
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Tuple
+import json
 
 from ....core.logging_config import get_logger
 
@@ -30,16 +33,20 @@ class DaemonLifecycle:
     handling, and graceful shutdown capabilities.
     """
 
-    def __init__(self, pid_file: str, log_file: Optional[str] = None):
+    def __init__(self, pid_file: str, log_file: Optional[str] = None, port: int = 8765):
         """Initialize daemon lifecycle manager.
 
         Args:
             pid_file: Path to PID file
             log_file: Path to log file for daemon mode
+            port: Port number for startup verification
         """
         self.pid_file = Path(pid_file)
         self.log_file = Path(log_file) if log_file else None
+        self.port = port
         self.logger = get_logger(__name__)
+        # Create a temporary file for startup status communication
+        self.startup_status_file = None
 
     def daemonize(self) -> bool:
         """Daemonize the current process.
@@ -50,14 +57,20 @@ class DaemonLifecycle:
         try:
             # Clean up any existing asyncio event loops before forking
             self._cleanup_event_loops()
+            
+            # Create a temporary file for startup status communication
+            with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix='.status') as f:
+                self.startup_status_file = f.name
+                f.write("starting")
 
             # First fork
             pid = os.fork()
             if pid > 0:
-                # Parent process exits
-                sys.exit(0)
+                # Parent process - wait for child to confirm startup
+                return self._parent_wait_for_startup(pid)
         except OSError as e:
             self.logger.error(f"First fork failed: {e}")
+            self._report_startup_error(f"First fork failed: {e}")
             return False
 
         # Decouple from parent environment
@@ -69,22 +82,33 @@ class DaemonLifecycle:
             # Second fork
             pid = os.fork()
             if pid > 0:
-                # Parent process exits
+                # First child process exits
                 sys.exit(0)
         except OSError as e:
             self.logger.error(f"Second fork failed: {e}")
+            self._report_startup_error(f"Second fork failed: {e}")
+            return False
+
+        # Set up error logging before redirecting streams
+        self._setup_early_error_logging()
+        
+        # Write PID file first (before stream redirection)
+        try:
+            self.write_pid_file()
+        except Exception as e:
+            self._report_startup_error(f"Failed to write PID file: {e}")
             return False
 
         # Redirect standard file descriptors
         self._redirect_streams()
 
-        # Write PID file
-        self.write_pid_file()
-
         # Setup signal handlers
         self._setup_signal_handlers()
 
         self.logger.info(f"Daemon process started with PID {os.getpid()}")
+        
+        # Report successful startup (after basic setup but before server start)
+        self._report_startup_success()
         return True
 
     def _redirect_streams(self):
@@ -105,13 +129,16 @@ class DaemonLifecycle:
                     os.dup2(log_out.fileno(), sys.stdout.fileno())
                     os.dup2(log_out.fileno(), sys.stderr.fileno())
             else:
-                # Redirect to /dev/null
-                with open("/dev/null", "w") as null_out:
-                    os.dup2(null_out.fileno(), sys.stdout.fileno())
-                    os.dup2(null_out.fileno(), sys.stderr.fileno())
+                # Default to a daemon log file instead of /dev/null for errors
+                default_log = Path.home() / ".claude-mpm" / "monitor-daemon.log"
+                default_log.parent.mkdir(parents=True, exist_ok=True)
+                with open(default_log, "a") as log_out:
+                    os.dup2(log_out.fileno(), sys.stdout.fileno())
+                    os.dup2(log_out.fileno(), sys.stderr.fileno())
 
         except Exception as e:
             self.logger.error(f"Error redirecting streams: {e}")
+            self._report_startup_error(f"Failed to redirect streams: {e}")
 
     def write_pid_file(self):
         """Write PID to PID file."""
@@ -336,3 +363,266 @@ class DaemonLifecycle:
                 self.logger.debug(f"Error getting process info: {e}")
 
         return status
+
+    def _parent_wait_for_startup(self, child_pid: int, timeout: float = 10.0) -> bool:
+        """Parent process waits for child daemon to report startup status.
+        
+        Args:
+            child_pid: PID of the child process
+            timeout: Maximum time to wait for startup
+            
+        Returns:
+            True if child started successfully, False otherwise
+        """
+        import time
+        start_time = time.time()
+        
+        # Wait for child to update status file
+        while time.time() - start_time < timeout:
+            try:
+                # Check if status file exists and read it
+                if self.startup_status_file and Path(self.startup_status_file).exists():
+                    with open(self.startup_status_file, 'r') as f:
+                        status = f.read().strip()
+                    
+                    if status == "success":
+                        # Child started successfully
+                        self._cleanup_status_file()
+                        return True
+                    elif status.startswith("error:"):
+                        # Child reported an error
+                        error_msg = status[6:]  # Remove "error:" prefix
+                        self.logger.error(f"Daemon startup failed: {error_msg}")
+                        print(f"Error: Failed to start monitor daemon: {error_msg}", file=sys.stderr)
+                        self._cleanup_status_file()
+                        return False
+                    elif status == "starting":
+                        # Still starting, continue waiting
+                        pass
+                    
+                # Also check if child process is still alive
+                try:
+                    os.kill(child_pid, 0)  # Check if process exists
+                except ProcessLookupError:
+                    # Child process died
+                    self.logger.error("Child daemon process died during startup")
+                    print("Error: Monitor daemon process died during startup", file=sys.stderr)
+                    self._cleanup_status_file()
+                    return False
+                    
+            except Exception as e:
+                self.logger.debug(f"Error checking startup status: {e}")
+            
+            time.sleep(0.1)  # Check every 100ms
+        
+        # Timeout reached
+        self.logger.error(f"Daemon startup timed out after {timeout} seconds")
+        print(f"Error: Monitor daemon startup timed out after {timeout} seconds", file=sys.stderr)
+        self._cleanup_status_file()
+        return False
+    
+    def _report_startup_success(self):
+        """Report successful startup to parent process."""
+        if self.startup_status_file:
+            try:
+                with open(self.startup_status_file, 'w') as f:
+                    f.write("success")
+            except Exception as e:
+                self.logger.error(f"Failed to report startup success: {e}")
+    
+    def _report_startup_error(self, error_msg: str):
+        """Report startup error to parent process.
+        
+        Args:
+            error_msg: Error message to report
+        """
+        if self.startup_status_file:
+            try:
+                with open(self.startup_status_file, 'w') as f:
+                    f.write(f"error:{error_msg}")
+            except Exception:
+                pass  # Can't report if file write fails
+    
+    def _cleanup_status_file(self):
+        """Clean up the temporary status file."""
+        if self.startup_status_file:
+            try:
+                Path(self.startup_status_file).unlink(missing_ok=True)
+            except Exception:
+                pass  # Ignore cleanup errors
+            finally:
+                self.startup_status_file = None
+    
+    def _setup_early_error_logging(self):
+        """Set up error logging before stream redirection.
+        
+        This ensures we can capture and report errors that occur during
+        daemon initialization, especially port binding errors.
+        """
+        try:
+            # If no log file specified, create a default one
+            if not self.log_file:
+                default_log = Path.home() / ".claude-mpm" / "monitor-daemon.log"
+                default_log.parent.mkdir(parents=True, exist_ok=True)
+                self.log_file = default_log
+                
+            # Configure logger to write to file immediately
+            import logging
+            file_handler = logging.FileHandler(self.log_file)
+            file_handler.setLevel(logging.DEBUG)
+            formatter = logging.Formatter(
+                '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+            )
+            file_handler.setFormatter(formatter)
+            self.logger.addHandler(file_handler)
+            
+        except Exception as e:
+            # If we can't set up logging, at least try to report the error
+            self._report_startup_error(f"Failed to setup error logging: {e}")
+    
+    def verify_port_available(self, host: str = "localhost") -> Tuple[bool, Optional[str]]:
+        """Verify that the port is available for binding.
+        
+        Args:
+            host: Host to check port on
+            
+        Returns:
+            Tuple of (is_available, error_message)
+        """
+        try:
+            test_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            test_sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            test_sock.bind((host, self.port))
+            test_sock.close()
+            return True, None
+        except OSError as e:
+            error_msg = f"Port {self.port} is already in use or cannot be bound: {e}"
+            return False, error_msg
+    
+    def is_our_service(self, host: str = "localhost") -> Tuple[bool, Optional[int]]:
+        """Check if the service on the port is our Socket.IO service.
+        
+        This uses multiple detection methods:
+        1. Check health endpoint for service signature
+        2. Check Socket.IO namespace availability
+        3. Check process ownership if PID file exists
+        
+        Args:
+            host: Host to check
+            
+        Returns:
+            Tuple of (is_ours, pid_if_found)
+        """
+        try:
+            # Method 1: Check health endpoint
+            import urllib.request
+            import urllib.error
+            
+            health_url = f"http://{host}:{self.port}/health"
+            try:
+                with urllib.request.urlopen(health_url, timeout=2) as response:
+                    if response.status == 200:
+                        data = json.loads(response.read().decode())
+                        # Check for our service signature
+                        if data.get("service") == "claude-mpm-monitor":
+                            # Try to get PID from response
+                            pid = data.get("pid")
+                            if pid:
+                                self.logger.debug(f"Found our service via health endpoint, PID: {pid}")
+                                return True, pid
+                            else:
+                                # Service is ours but no PID in response
+                                # Try to get from PID file
+                                file_pid = self.get_pid()
+                                self.logger.debug(f"Found our service via health endpoint, PID from file: {file_pid}")
+                                return True, file_pid
+            except (urllib.error.URLError, urllib.error.HTTPError, json.JSONDecodeError):
+                # Health endpoint not accessible or invalid response
+                pass
+            
+            # Method 2: Check if PID file exists and process matches
+            pid = self.get_pid()
+            if pid:
+                try:
+                    # Check if process exists
+                    os.kill(pid, 0)
+                    
+                    # Process exists, check if it's using our port
+                    # This requires psutil for accurate port checking
+                    try:
+                        import psutil
+                        process = psutil.Process(pid)
+                        connections = process.connections()
+                        for conn in connections:
+                            if conn.laddr.port == self.port:
+                                self.logger.debug(f"Found our service via PID file, PID: {pid}")
+                                return True, pid
+                    except ImportError:
+                        # psutil not available, assume it's ours if PID matches
+                        self.logger.debug(f"Found process with our PID file: {pid}, assuming it's ours")
+                        return True, pid
+                    except Exception:
+                        pass
+                        
+                except (OSError, ProcessLookupError):
+                    # Process doesn't exist
+                    pass
+            
+            # Method 3: Try Socket.IO connection to check namespace
+            try:
+                import socketio
+                sio_client = socketio.Client()
+                
+                # Try to connect with a short timeout
+                connected = False
+                def on_connect():
+                    nonlocal connected
+                    connected = True
+                
+                sio_client.on('connect', on_connect)
+                
+                try:
+                    sio_client.connect(f'http://{host}:{self.port}', wait_timeout=2)
+                    if connected:
+                        # Successfully connected to Socket.IO
+                        sio_client.disconnect()
+                        
+                        # Check for orphaned process (no PID file but service running)
+                        try:
+                            # Try to find process using the port
+                            import psutil
+                            for proc in psutil.process_iter(['pid', 'name']):
+                                try:
+                                    for conn in proc.connections():
+                                        if conn.laddr.port == self.port and conn.status == 'LISTEN':
+                                            # Found process listening on our port
+                                            if 'python' in proc.name().lower():
+                                                self.logger.debug(f"Found likely orphaned claude-mpm service on port {self.port}, PID: {proc.pid}")
+                                                return True, proc.pid
+                                except (psutil.NoSuchProcess, psutil.AccessDenied):
+                                    continue
+                        except ImportError:
+                            pass
+                        
+                        # Socket.IO service exists but can't determine if it's ours
+                        self.logger.debug(f"Found Socket.IO service on port {self.port}, but cannot confirm ownership")
+                        return False, None
+                        
+                except Exception:
+                    pass
+                finally:
+                    if sio_client.connected:
+                        sio_client.disconnect()
+                        
+            except ImportError:
+                # socketio not available
+                pass
+            except Exception as e:
+                self.logger.debug(f"Error checking Socket.IO connection: {e}")
+            
+            # No service detected or not ours
+            return False, None
+            
+        except Exception as e:
+            self.logger.error(f"Error checking if service is ours: {e}")
+            return False, None

claude_mpm/services/monitor/server.py

@@ -15,6 +15,7 @@ DESIGN DECISIONS:
 """
 
 import asyncio
+import os
 import threading
 import time
 from datetime import datetime
@@ -79,6 +80,7 @@ class UnifiedMonitorServer:
         self.running = False
         self.loop = None
         self.server_thread = None
+        self.startup_error = None  # Track startup errors
 
         # Heartbeat tracking
         self.heartbeat_task: Optional[asyncio.Task] = None
@@ -106,10 +108,15 @@ class UnifiedMonitorServer:
             for _ in range(50):  # Wait up to 5 seconds
                 if self.running:
                     break
+                if self.startup_error:
+                    # Server thread reported an error
+                    self.logger.error(f"Server startup failed: {self.startup_error}")
+                    return False
                 time.sleep(0.1)
 
             if not self.running:
-                self.logger.error("Server failed to start within timeout")
+                error_msg = self.startup_error or "Server failed to start within timeout"
+                self.logger.error(error_msg)
                 return False
 
             self.logger.info("Unified monitor server started successfully")
@@ -131,8 +138,17 @@ class UnifiedMonitorServer:
             # Run the async server
             loop.run_until_complete(self._start_async_server())
 
+        except OSError as e:
+            # Specific handling for port binding errors
+            if "Address already in use" in str(e) or "[Errno 48]" in str(e):
+                self.logger.error(f"Port {self.port} is already in use: {e}")
+                self.startup_error = f"Port {self.port} is already in use"
+            else:
+                self.logger.error(f"OS error in server thread: {e}")
+                self.startup_error = str(e)
         except Exception as e:
             self.logger.error(f"Error in server thread: {e}")
+            self.startup_error = str(e)
         finally:
             # Always ensure loop cleanup happens
             if loop is not None:
@@ -212,11 +228,23 @@ class UnifiedMonitorServer:
             self.runner = web.AppRunner(self.app)
             await self.runner.setup()
 
-            self.site = web.TCPSite(self.runner, self.host, self.port)
-            await self.site.start()
-
-            self.running = True
-            self.logger.info(f"Server running on http://{self.host}:{self.port}")
+            try:
+                self.site = web.TCPSite(self.runner, self.host, self.port)
+                await self.site.start()
+                
+                self.running = True
+                self.logger.info(f"Server running on http://{self.host}:{self.port}")
+            except OSError as e:
+                # Port binding error - make sure it's reported clearly
+                if "Address already in use" in str(e) or "[Errno 48]" in str(e):
+                    error_msg = f"Port {self.port} is already in use. Another process may be using this port."
+                    self.logger.error(error_msg)
+                    self.startup_error = error_msg
+                    raise OSError(error_msg) from e
+                else:
+                    self.logger.error(f"Failed to bind to {self.host}:{self.port}: {e}")
+                    self.startup_error = str(e)
+                    raise
 
             # Keep the server running
             while self.running:
@@ -281,12 +309,23 @@ class UnifiedMonitorServer:
 
             # Health check
             async def health_check(request):
+                # Get version from VERSION file
+                version = "1.0.0"
+                try:
+                    version_file = Path(__file__).parent.parent.parent.parent.parent / "VERSION"
+                    if version_file.exists():
+                        version = version_file.read_text().strip()
+                except Exception:
+                    pass
+                
                 return web.json_response(
                     {
                         "status": "healthy",
-                        "service": "unified-monitor",
-                        "version": "1.0.0",
+                        "service": "claude-mpm-monitor",  # Important: must match what is_our_service() checks
+                        "version": version,
                         "port": self.port,
+                        "pid": os.getpid(),
+                        "uptime": int(time.time() - self.server_start_time),
                     }
                 )
 

{claude_mpm-4.2.21.dist-info → claude_mpm-4.2.23.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.2.21
+Version: 4.2.23
 Summary: Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking
 Author-email: Bob Matsuoka <bob@matsuoka.com>
 Maintainer: Claude MPM Team
@@ -149,11 +149,18 @@ pip install claude-mpm
 
 Or with pipx (recommended for isolated installation):
 ```bash
+# Install with monitor support (recommended)
+pipx install "claude-mpm[monitor]"
+
+# Basic installation without monitor
 pipx install claude-mpm
+
 # Configure MCP for pipx users:
 claude-mpm mcp-pipx-config
 ```
 
+**💡 Pipx Tip**: Use `"claude-mpm[monitor]"` to get full monitoring dashboard functionality! The `[monitor]` optional dependency includes Socket.IO and async web server components needed for real-time agent monitoring.
+
 **🎉 Pipx Support Now Fully Functional!** Recent improvements ensure complete compatibility:
 - ✅ Socket.IO daemon script path resolution (fixed)
 - ✅ Commands directory access (fixed) 

{claude_mpm-4.2.21.dist-info → claude_mpm-4.2.23.dist-info}/RECORD

@@ -1,5 +1,5 @@
 claude_mpm/BUILD_NUMBER,sha256=toytnNjkIKPgQaGwDqQdC1rpNTAdSEc6Vja50d7Ovug,4
-claude_mpm/VERSION,sha256=wsCsu3SGhnVCrJ3G8gVo7Vf1VJhypvvtmS7mEhwhYs4,7
+claude_mpm/VERSION,sha256=bLmVrJAUXnac417S8JQgDFhX08Y4MIxjz0i-TIhW9zA,7
 claude_mpm/__init__.py,sha256=lyTZAYGH4DTaFGLRNWJKk5Q5oTjzN5I6AXmfVX-Jff0,1512
 claude_mpm/__main__.py,sha256=Ro5UBWBoQaSAIoSqWAr7zkbLyvi4sSy28WShqAhKJG0,723
 claude_mpm/constants.py,sha256=I946iCQzIIPRZVVJ8aO7lA4euiyDnNw2IX7EelAOkIE,5915
@@ -83,7 +83,7 @@ claude_mpm/cli/commands/mcp_pipx_config.py,sha256=sE62VD6Q1CcO2k1nlbIhHMfAJFQTZf
 claude_mpm/cli/commands/mcp_server_commands.py,sha256=-1G_2Y5ScTvzDd-kY8fTAao2H6FH7DnsLimleF1rVqQ,6197
 claude_mpm/cli/commands/mcp_tool_commands.py,sha256=q17GzlFT3JiLTrDqwPO2tz1-fKmPO5QU449syTnKTz4,1283
 claude_mpm/cli/commands/memory.py,sha256=Yzfs3_oiKciv3sfOoDm2lJL4M9idG7ARV3-sNw1ge_g,26186
-claude_mpm/cli/commands/monitor.py,sha256=Z7JPvx1PO4t8vUsWVZvWqdEkPtDG7E-01Bn1lUjY2sY,8213
+claude_mpm/cli/commands/monitor.py,sha256=K8TNtOsdsFgzr9VePELxFnNqZOGhL5a7XFbgOpNYq0g,9621
 claude_mpm/cli/commands/mpm_init.py,sha256=lO7N91ZHn_n18XbchUUcYoyme7L5NLcXVnhWm5F_Gq8,22367
 claude_mpm/cli/commands/mpm_init_handler.py,sha256=-pCB0XL3KipqGtnta8CC7Lg5TPMwstEhMFBcgF4aaa4,2919
 claude_mpm/cli/commands/run.py,sha256=qS3eolLiDrE8EXLQJioB6kL1ONr_l0c3OE3qMUJCqbA,43489
@@ -432,7 +432,7 @@ claude_mpm/services/cli/memory_crud_service.py,sha256=ciN9Pl_12iDAqF9zPBWOzu-iXi
 claude_mpm/services/cli/memory_output_formatter.py,sha256=nbf7VsjGvH4e9fLv9c7PzjuO9COZhbK5P2fNZ79055w,24783
 claude_mpm/services/cli/session_manager.py,sha256=rla_Stbcvt93wa9G9MCMu9UqB3FLGqlPt_eN5lQb3Gg,16599
 claude_mpm/services/cli/startup_checker.py,sha256=efhuvu8ns5G16jcQ0nQZKVddmD2AktUEdlvjNcXjAuk,12232
-claude_mpm/services/cli/unified_dashboard_manager.py,sha256=GHLDe57UI1SMW04G6E97oc-bZPnNDv4eMXrUfll2ShE,11570
+claude_mpm/services/cli/unified_dashboard_manager.py,sha256=3IRum9HH6IA4UQtTzD5l6rCngfxfqeqfTGzpKIpmZd8,12607
 claude_mpm/services/communication/__init__.py,sha256=b4qc7_Rqy4DE9q7BAUlfUZjoYG4uimAyUnE0irPcXyU,560
 claude_mpm/services/core/__init__.py,sha256=evEayLlBqJvxMZhrhuK6aagXmNrKGSj8Jm9OOxKzqvU,2195
 claude_mpm/services/core/base.py,sha256=iA-F7DgGp-FJIMvQTiHQ68RkG_k-AtUWlArJPMw6ZPk,7297
@@ -548,9 +548,9 @@ claude_mpm/services/memory/cache/__init__.py,sha256=6M6-P8ParyxX8vOgp_IxHgLMvacr
 claude_mpm/services/memory/cache/shared_prompt_cache.py,sha256=crnYPUT8zcS7TvoE1vW7pyaf4T77N5rJ1wUf_YQ2vvo,28704
 claude_mpm/services/memory/cache/simple_cache.py,sha256=qsTjbcsPxj-kNfaod9VN_uE5NioIwpfkUin_mMVUJCg,10218
 claude_mpm/services/monitor/__init__.py,sha256=X7gxSLUm9Fg_zEsX6LtCHP2ipF0qj6Emkun20h2So7g,745
-claude_mpm/services/monitor/daemon.py,sha256=f51ulONe_IyHpfFTFaEl93CQc5gnNT3nrQGMdb6hfo0,15351
+claude_mpm/services/monitor/daemon.py,sha256=g7g7g7kZTzCowM5iNJHhkE2UYDRms_7C34Net2CpdjQ,21015
 claude_mpm/services/monitor/event_emitter.py,sha256=JzRLNg8PUJ5s3ulNnq_D4yqCPItvidJzu8DmFxriieQ,12224
-claude_mpm/services/monitor/server.py,sha256=Z7K4pKEbrDtEVVJzrB6QVPVhW_3eEcTaQAnpP3boJco,26401
+claude_mpm/services/monitor/server.py,sha256=2-xLo14qFBZf5MDYwBxBhTrFCNnbu3tOS3eEu8vyddc,28476
 claude_mpm/services/monitor/handlers/__init__.py,sha256=jgPIf4IJVERm_tAeD9834tfx9IcxtlHj5r9rhEWpkfM,701
 claude_mpm/services/monitor/handlers/code_analysis.py,sha256=mHyI27Wp6WVmUBc0m0i991ogyFZBTvkrfR7Kf3EAk5U,11474
 claude_mpm/services/monitor/handlers/dashboard.py,sha256=uGBhb-6RG6u4WLipUXgdx7RCW-vb_qek5dIfHIwAC7o,9805
@@ -558,7 +558,7 @@ claude_mpm/services/monitor/handlers/file.py,sha256=p3C4wffl0GIcN00b-KkrmZ8F-Amd
 claude_mpm/services/monitor/handlers/hooks.py,sha256=dlrmyFu8WChlvn6-sND9DLjSbm5nrMfNZrAgoWN-2No,17582
 claude_mpm/services/monitor/management/__init__.py,sha256=mxaEFRgvvgV85gUpXu_DsnHtywihdP14EisvISAVZuQ,525
 claude_mpm/services/monitor/management/health.py,sha256=Wm92Cli_4cWD6B89KX_CdpAvvevuEaGB8Ah59ILhFww,3772
-claude_mpm/services/monitor/management/lifecycle.py,sha256=Cahpc1-R09ihDYVWiMI9wnv-Qw20cNhHHcJyxZ9JcBo,10575
+claude_mpm/services/monitor/management/lifecycle.py,sha256=DO3UYLWN2tW1P72--kTbWCpWZBNxK1Ok2GeI_PdOgHc,23713
 claude_mpm/services/project/__init__.py,sha256=IUclN1L7ChHCNya7PJiVxu4nttxsrj3WRIpwyA1A_hw,512
 claude_mpm/services/project/analyzer.py,sha256=VHlLrP8-S5gr12w4Yzs7-6d7LWdJKISHPCFSG7SDiQU,38434
 claude_mpm/services/project/analyzer_refactored.py,sha256=USYEdPAhSoGPqZCpaT89Dw6ElFW_L1yXSURheQjAhLA,18243
@@ -639,9 +639,9 @@ claude_mpm/utils/subprocess_utils.py,sha256=zgiwLqh_17WxHpySvUPH65pb4bzIeUGOAYUJ
 claude_mpm/validation/__init__.py,sha256=YZhwE3mhit-lslvRLuwfX82xJ_k4haZeKmh4IWaVwtk,156
 claude_mpm/validation/agent_validator.py,sha256=3Lo6LK-Mw9IdnL_bd3zl_R6FkgSVDYKUUM7EeVVD3jc,20865
 claude_mpm/validation/frontmatter_validator.py,sha256=u8g4Eyd_9O6ugj7Un47oSGh3kqv4wMkuks2i_CtWRvM,7028
-claude_mpm-4.2.21.dist-info/licenses/LICENSE,sha256=lpaivOlPuBZW1ds05uQLJJswy8Rp_HMNieJEbFlqvLk,1072
-claude_mpm-4.2.21.dist-info/METADATA,sha256=79KK9Dg30eyjYMaOvrTCuyKmVtkZNKPR8gdrjJ5bp90,14110
-claude_mpm-4.2.21.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-claude_mpm-4.2.21.dist-info/entry_points.txt,sha256=FDPZgz8JOvD-6iuXY2l9Zbo9zYVRuE4uz4Qr0vLeGOk,471
-claude_mpm-4.2.21.dist-info/top_level.txt,sha256=1nUg3FEaBySgm8t-s54jK5zoPnu3_eY6EP6IOlekyHA,11
-claude_mpm-4.2.21.dist-info/RECORD,,
+claude_mpm-4.2.23.dist-info/licenses/LICENSE,sha256=lpaivOlPuBZW1ds05uQLJJswy8Rp_HMNieJEbFlqvLk,1072
+claude_mpm-4.2.23.dist-info/METADATA,sha256=5lkYIMEIiPKrYRkOrljAj3wfsRqrBzIip_Vh9sb4eZE,14451
+claude_mpm-4.2.23.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+claude_mpm-4.2.23.dist-info/entry_points.txt,sha256=FDPZgz8JOvD-6iuXY2l9Zbo9zYVRuE4uz4Qr0vLeGOk,471
+claude_mpm-4.2.23.dist-info/top_level.txt,sha256=1nUg3FEaBySgm8t-s54jK5zoPnu3_eY6EP6IOlekyHA,11
+claude_mpm-4.2.23.dist-info/RECORD,,