claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

claude_mpm/services/exceptions.py

@@ -1,3 +1,5 @@
+from pathlib import Path
+
 """Enhanced error classes for daemon conflict and process management in claude-mpm Socket.IO server.
 
 These error classes provide detailed context and actionable guidance for users to resolve
@@ -11,25 +13,27 @@ Design Principles:
 5. Structured error data for programmatic handling
 """
 
-import os
-import sys
-import time
 import platform
-from datetime import datetime
-from typing import Dict, Any, Optional, List
-from pathlib import Path
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
 
 
 class SocketIOServerError(Exception):
     """Base exception for Socket.IO server errors.
-    
+
     Provides common functionality for all server-related errors including
     structured error data and detailed context information.
     """
-    
-    def __init__(self, message: str, error_code: str = None, context: Dict[str, Any] = None):
+
+    def __init__(
+        self,
+        message: str,
+        error_code: Optional[str] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ):
         """Initialize base server error.
-        
+
         Args:
             message: Human-readable error message
             error_code: Machine-readable error code for programmatic handling
@@ -39,8 +43,8 @@ class SocketIOServerError(Exception):
         self.message = message
         self.error_code = error_code or self.__class__.__name__.lower()
         self.context = context or {}
-        self.timestamp = datetime.utcnow().isoformat() + "Z"
-        
+        self.timestamp = datetime.now(timezone.utc).isoformat() + "Z"
+
     def to_dict(self) -> Dict[str, Any]:
         """Convert error to dictionary format for structured logging/handling."""
         return {
@@ -48,25 +52,27 @@ class SocketIOServerError(Exception):
             "error_code": self.error_code,
             "message": self.message,
             "context": self.context,
-            "timestamp": self.timestamp
+            "timestamp": self.timestamp,
         }
 
 
 class DaemonConflictError(SocketIOServerError):
     """Error raised when attempting to start server while another instance is already running.
-    
+
     This error provides detailed information about the conflicting process and
     actionable steps to resolve the conflict.
     """
-    
-    def __init__(self, 
-                 port: int,
-                 existing_pid: int,
-                 existing_server_id: str = None,
-                 process_info: Dict[str, Any] = None,
-                 pidfile_path: Path = None):
+
+    def __init__(
+        self,
+        port: int,
+        existing_pid: int,
+        existing_server_id: Optional[str] = None,
+        process_info: Optional[Dict[str, Any]] = None,
+        pidfile_path: Optional[Path] = None,
+    ):
         """Initialize daemon conflict error with detailed context.
-        
+
         Args:
             port: Port number where conflict occurred
             existing_pid: PID of the existing server process
@@ -79,70 +85,78 @@ class DaemonConflictError(SocketIOServerError):
         self.existing_server_id = existing_server_id or "unknown"
         self.process_info = process_info or {}
         self.pidfile_path = pidfile_path
-        
+
         # Build detailed error message with resolution steps
         message = self._build_error_message()
-        
+
         context = {
             "port": port,
             "existing_pid": existing_pid,
             "existing_server_id": self.existing_server_id,
             "process_info": process_info,
             "pidfile_path": str(pidfile_path) if pidfile_path else None,
-            "resolution_steps": self._get_resolution_steps()
+            "resolution_steps": self._get_resolution_steps(),
         }
-        
+
         super().__init__(message, "daemon_conflict", context)
-    
+
     def _build_error_message(self) -> str:
         """Build comprehensive error message with process details."""
         lines = [
             f"🚫 Socket.IO server conflict detected on port {self.port}",
-            f"",
-            f"CONFLICT DETAILS:",
+            "",
+            "CONFLICT DETAILS:",
             f"  • Existing PID: {self.existing_pid}",
             f"  • Server ID: {self.existing_server_id}",
         ]
-        
+
         # Add process information if available
         if self.process_info:
-            status = self.process_info.get('status', 'unknown')
-            name = self.process_info.get('name', 'unknown')
-            create_time = self.process_info.get('create_time')
-            memory_info = self.process_info.get('memory_info', {})
-            
-            lines.extend([
-                f"  • Process Status: {status}",
-                f"  • Process Name: {name}",
-            ])
-            
+            status = self.process_info.get("status", "unknown")
+            name = self.process_info.get("name", "unknown")
+            create_time = self.process_info.get("create_time")
+            memory_info = self.process_info.get("memory_info", {})
+
+            lines.extend(
+                [
+                    f"  • Process Status: {status}",
+                    f"  • Process Name: {name}",
+                ]
+            )
+
             if create_time:
-                start_time = datetime.fromtimestamp(create_time).strftime('%Y-%m-%d %H:%M:%S')
+                start_time = datetime.fromtimestamp(
+                    create_time, tz=timezone.utc
+                ).strftime("%Y-%m-%d %H:%M:%S")
                 uptime = time.time() - create_time
                 lines.append(f"  • Started: {start_time} (uptime: {uptime:.0f}s)")
-            
-            if memory_info.get('rss'):
-                memory_mb = memory_info['rss'] / (1024 * 1024)
+
+            if memory_info.get("rss"):
+                memory_mb = memory_info["rss"] / (1024 * 1024)
                 lines.append(f"  • Memory Usage: {memory_mb:.1f} MB")
-        
+
         # Add PID file information
         if self.pidfile_path:
-            lines.extend([
-                f"  • PID File: {self.pidfile_path}",
-                f"  • File Exists: {self.pidfile_path.exists() if isinstance(self.pidfile_path, Path) else 'unknown'}"
-            ])
-        
-        lines.extend([
-            f"",
-            f"RESOLUTION STEPS:",
-        ])
-        
+            lines.extend(
+                [
+                    f"  • PID File: {self.pidfile_path}",
+                    f"  • File Exists: {self.pidfile_path.exists() if isinstance(self.pidfile_path, Path) else 'unknown'}",
+                ]
+            )
+
+        lines.extend(
+            [
+                "",
+                "RESOLUTION STEPS:",
+            ]
+        )
+
         # Add resolution steps
         for i, step in enumerate(self._get_resolution_steps(), 1):
             lines.append(f"  {i}. {step}")
-        
+
         return "\n".join(lines)
-    
+
     def _get_resolution_steps(self) -> List[str]:
         """Get ordered list of resolution steps."""
         steps = [
@@ -150,137 +164,150 @@ class DaemonConflictError(SocketIOServerError):
             f"Stop the existing server gracefully: kill -TERM {self.existing_pid}",
             f"If graceful shutdown fails: kill -KILL {self.existing_pid}",
         ]
-        
+
         if self.pidfile_path:
             steps.append(f"Remove stale PID file if needed: rm {self.pidfile_path}")
-        
-        steps.extend([
-            f"Wait a few seconds for port cleanup",
-            f"Try starting the server again on port {self.port}",
-            f"Alternative: Use a different port with --port <new_port>"
-        ])
-        
+
+        steps.extend(
+            [
+                "Wait a few seconds for port cleanup",
+                f"Try starting the server again on port {self.port}",
+                "Alternative: Use a different port with --port <new_port>",
+            ]
+        )
+
         return steps
 
 
 class PortConflictError(SocketIOServerError):
     """Error raised when network port is already in use by another process.
-    
+
     This error helps identify what process is using the port and provides
     steps to resolve the conflict.
     """
-    
-    def __init__(self, 
-                 port: int, 
-                 host: str = "localhost",
-                 conflicting_process: Dict[str, Any] = None):
+
+    def __init__(
+        self,
+        port: int,
+        host: str = "localhost",
+        conflicting_process: Optional[Dict[str, Any]] = None,
+    ):
         """Initialize port conflict error.
-        
+
         Args:
             port: Port number that's in use
-            host: Host address where the conflict occurred  
+            host: Host address where the conflict occurred
             conflicting_process: Information about the process using the port
         """
         self.port = port
         self.host = host
         self.conflicting_process = conflicting_process or {}
-        
+
         message = self._build_error_message()
-        
+
         context = {
             "port": port,
             "host": host,
             "conflicting_process": conflicting_process,
-            "resolution_steps": self._get_resolution_steps()
+            "resolution_steps": self._get_resolution_steps(),
         }
-        
+
         super().__init__(message, "port_conflict", context)
-    
+
     def _build_error_message(self) -> str:
         """Build error message with port conflict details."""
         lines = [
-            f"🔌 Network port conflict detected",
-            f"",
-            f"PORT CONFLICT DETAILS:",
+            "🔌 Network port conflict detected",
+            "",
+            "PORT CONFLICT DETAILS:",
             f"  • Port: {self.port}",
             f"  • Host: {self.host}",
             f"  • Address: {self.host}:{self.port}",
         ]
-        
+
         # Add information about conflicting process if available
         if self.conflicting_process:
-            pid = self.conflicting_process.get('pid')
-            name = self.conflicting_process.get('name', 'unknown')
-            cmdline = self.conflicting_process.get('cmdline', [])
-            
-            lines.extend([
-                f"",
-                f"CONFLICTING PROCESS:",
-                f"  • PID: {pid or 'unknown'}",
-                f"  • Name: {name}",
-            ])
-            
+            pid = self.conflicting_process.get("pid")
+            name = self.conflicting_process.get("name", "unknown")
+            cmdline = self.conflicting_process.get("cmdline", [])
+
+            lines.extend(
+                [
+                    "",
+                    "CONFLICTING PROCESS:",
+                    f"  • PID: {pid or 'unknown'}",
+                    f"  • Name: {name}",
+                ]
+            )
+
             if cmdline:
                 lines.append(f"  • Command: {' '.join(cmdline)}")
-        
-        lines.extend([
-            f"",
-            f"RESOLUTION STEPS:",
-        ])
-        
+
+        lines.extend(
+            [
+                "",
+                "RESOLUTION STEPS:",
+            ]
+        )
+
         for i, step in enumerate(self._get_resolution_steps(), 1):
             lines.append(f"  {i}. {step}")
-        
+
         return "\n".join(lines)
-    
+
     def _get_resolution_steps(self) -> List[str]:
         """Get resolution steps for port conflicts."""
-        steps = [
-            f"Check what process is using port {self.port}:"
-        ]
-        
+        steps = [f"Check what process is using port {self.port}:"]
+
         # Add platform-specific commands
         if platform.system() == "Darwin":  # macOS
-            steps.extend([
-                f"   • lsof -i :{self.port}",
-                f"   • netstat -an | grep {self.port}"
-            ])
+            steps.extend(
+                [f"   • lsof -i :{self.port}", f"   • netstat -an | grep {self.port}"]
+            )
         elif platform.system() == "Linux":
-            steps.extend([
-                f"   • lsof -i :{self.port}",
-                f"   • netstat -tulpn | grep {self.port}",
-                f"   • ss -tulpn | grep {self.port}"
-            ])
+            steps.extend(
+                [
+                    f"   • lsof -i :{self.port}",
+                    f"   • netstat -tulpn | grep {self.port}",
+                    f"   • ss -tulpn | grep {self.port}",
+                ]
+            )
         elif platform.system() == "Windows":
-            steps.extend([
-                f"   • netstat -ano | findstr {self.port}",
-                f"   • tasklist /fi \"PID eq <PID_FROM_NETSTAT>\""
-            ])
-        
-        steps.extend([
-            f"Stop the conflicting process if it's safe to do so",
-            f"Wait for port cleanup (may take 30-60 seconds)",
-            f"Try again with the same port",
-            f"Alternative: Use a different port: --port {self.port + 1}"
-        ])
-        
+            steps.extend(
+                [
+                    f"   • netstat -ano | findstr {self.port}",
+                    '   • tasklist /fi "PID eq <PID_FROM_NETSTAT>"',
+                ]
+            )
+
+        steps.extend(
+            [
+                "Stop the conflicting process if it's safe to do so",
+                "Wait for port cleanup (may take 30-60 seconds)",
+                "Try again with the same port",
+                f"Alternative: Use a different port: --port {self.port + 1}",
+            ]
+        )
+
         return steps
 
 
 class StaleProcessError(SocketIOServerError):
     """Error raised when dealing with stale processes or PID files.
-    
+
     This error occurs when a PID file exists but the associated process
     is no longer running, is a zombie, or has been replaced.
     """
-    
-    def __init__(self, 
-                 pid: int,
-                 pidfile_path: Path = None,
-                 process_status: str = "not_found",
-                 validation_errors: List[str] = None):
+
+    def __init__(
+        self,
+        pid: int,
+        pidfile_path: Optional[Path] = None,
+        process_status: str = "not_found",
+        validation_errors: Optional[List[str]] = None,
+    ):
         """Initialize stale process error.
-        
+
         Args:
             pid: Process ID that's stale
             pidfile_path: Path to the stale PID file
@@ -291,19 +318,19 @@ class StaleProcessError(SocketIOServerError):
         self.pidfile_path = pidfile_path
         self.process_status = process_status
         self.validation_errors = validation_errors or []
-        
+
         message = self._build_error_message()
-        
+
         context = {
             "pid": pid,
             "pidfile_path": str(pidfile_path) if pidfile_path else None,
             "process_status": process_status,
             "validation_errors": validation_errors,
-            "resolution_steps": self._get_resolution_steps()
+            "resolution_steps": self._get_resolution_steps(),
         }
-        
+
         super().__init__(message, "stale_process", context)
-    
+
     def _build_error_message(self) -> str:
         """Build error message for stale process."""
         status_descriptions = {
@@ -311,91 +338,105 @@ class StaleProcessError(SocketIOServerError):
             "zombie": "Process is a zombie (terminated but not reaped)",
             "invalid": "Process exists but is not the expected server",
             "access_denied": "Cannot access process information",
-            "stale_pidfile": "PID file is stale or corrupted"
+            "stale_pidfile": "PID file is stale or corrupted",
         }
-        
-        status_desc = status_descriptions.get(self.process_status, f"Process status: {self.process_status}")
-        
+
+        status_desc = status_descriptions.get(
+            self.process_status, f"Process status: {self.process_status}"
+        )
+
         lines = [
-            f"🧟 Stale process detected",
-            f"",
-            f"PROCESS DETAILS:",
+            "🧟 Stale process detected",
+            "",
+            "PROCESS DETAILS:",
             f"  • PID: {self.pid}",
             f"  • Status: {status_desc}",
         ]
-        
+
         if self.pidfile_path:
-            lines.extend([
-                f"  • PID File: {self.pidfile_path}",
-                f"  • File Exists: {self.pidfile_path.exists() if isinstance(self.pidfile_path, Path) else 'unknown'}"
-            ])
-        
+            lines.extend(
+                [
+                    f"  • PID File: {self.pidfile_path}",
+                    f"  • File Exists: {self.pidfile_path.exists() if isinstance(self.pidfile_path, Path) else 'unknown'}",
+                ]
+            )
+
         if self.validation_errors:
-            lines.extend([
-                f"",
-                f"VALIDATION ERRORS:",
-            ])
+            lines.extend(
+                [
+                    "",
+                    "VALIDATION ERRORS:",
+                ]
+            )
             for error in self.validation_errors:
                 lines.append(f"  • {error}")
-        
-        lines.extend([
-            f"",
-            f"RESOLUTION STEPS:",
-        ])
-        
+
+        lines.extend(
+            [
+                "",
+                "RESOLUTION STEPS:",
+            ]
+        )
+
         for i, step in enumerate(self._get_resolution_steps(), 1):
             lines.append(f"  {i}. {step}")
-        
+
         return "\n".join(lines)
-    
+
     def _get_resolution_steps(self) -> List[str]:
         """Get resolution steps for stale processes."""
         steps = []
-        
+
         if self.process_status == "zombie":
-            steps.extend([
-                "Wait for parent process to reap zombie (usually automatic)",
-                f"If zombie persists, check parent process: ps -o ppid= -p {self.pid}",
-                "Restart parent process if necessary"
-            ])
+            steps.extend(
+                [
+                    "Wait for parent process to reap zombie (usually automatic)",
+                    f"If zombie persists, check parent process: ps -o ppid= -p {self.pid}",
+                    "Restart parent process if necessary",
+                ]
+            )
         elif self.process_status == "not_found":
-            steps.extend([
-                f"Process {self.pid} no longer exists - safe to clean up"
-            ])
+            steps.extend([f"Process {self.pid} no longer exists - safe to clean up"])
         elif self.process_status == "invalid":
-            steps.extend([
-                f"Verify process {self.pid} is not a legitimate server:",
-                f"   • ps -p {self.pid} -o pid,ppid,cmd",
-                "If it's not your server, it's safe to clean up the PID file"
-            ])
-        
+            steps.extend(
+                [
+                    f"Verify process {self.pid} is not a legitimate server:",
+                    f"   • ps -p {self.pid} -o pid,ppid,cmd",
+                    "If it's not your server, it's safe to clean up the PID file",
+                ]
+            )
+
         # Common cleanup steps
         if self.pidfile_path:
             steps.append(f"Remove stale PID file: rm {self.pidfile_path}")
-        
-        steps.extend([
-            "Try starting the server again",
-            "If issues persist, check for permission problems or disk space"
-        ])
-        
+
+        steps.extend(
+            [
+                "Try starting the server again",
+                "If issues persist, check for permission problems or disk space",
+            ]
+        )
+
         return steps
 
 
 class RecoveryFailedError(SocketIOServerError):
     """Error raised when automatic recovery mechanisms fail.
-    
+
     This error occurs when the health monitoring and recovery system
     cannot automatically resolve server issues.
     """
-    
-    def __init__(self,
-                 recovery_action: str,
-                 failure_reason: str,
-                 attempt_count: int = 1,
-                 health_status: Dict[str, Any] = None,
-                 last_successful_recovery: str = None):
+
+    def __init__(
+        self,
+        recovery_action: str,
+        failure_reason: str,
+        attempt_count: int = 1,
+        health_status: Optional[Dict[str, Any]] = None,
+        last_successful_recovery: Optional[str] = None,
+    ):
         """Initialize recovery failure error.
-        
+
         Args:
             recovery_action: The recovery action that failed (e.g., 'restart', 'cleanup')
             failure_reason: Why the recovery failed
@@ -408,56 +449,68 @@ class RecoveryFailedError(SocketIOServerError):
         self.attempt_count = attempt_count
         self.health_status = health_status or {}
         self.last_successful_recovery = last_successful_recovery
-        
+
         message = self._build_error_message()
-        
+
         context = {
             "recovery_action": recovery_action,
             "failure_reason": failure_reason,
             "attempt_count": attempt_count,
             "health_status": health_status,
             "last_successful_recovery": last_successful_recovery,
-            "resolution_steps": self._get_resolution_steps()
+            "resolution_steps": self._get_resolution_steps(),
         }
-        
+
         super().__init__(message, "recovery_failed", context)
-    
+
     def _build_error_message(self) -> str:
         """Build error message for recovery failure."""
         lines = [
-            f"🚨 Automatic recovery failed",
-            f"",
-            f"RECOVERY DETAILS:",
+            "🚨 Automatic recovery failed",
+            "",
+            "RECOVERY DETAILS:",
             f"  • Failed Action: {self.recovery_action}",
             f"  • Failure Reason: {self.failure_reason}",
             f"  • Attempt Count: {self.attempt_count}",
         ]
-        
+
         if self.last_successful_recovery:
-            lines.append(f"  • Last Successful Recovery: {self.last_successful_recovery}")
-        
+            lines.append(
+                f"  • Last Successful Recovery: {self.last_successful_recovery}"
+            )
+
         # Add health status information
         if self.health_status:
-            lines.extend([
-                f"",
-                f"CURRENT HEALTH STATUS:",
-            ])
-            
+            lines.extend(
+                [
+                    "",
+                    "CURRENT HEALTH STATUS:",
+                ]
+            )
+
             # Common health metrics
             for key, value in self.health_status.items():
-                if key in ['status', 'uptime', 'clients_connected', 'events_processed', 'errors']:
+                if key in [
+                    "status",
+                    "uptime",
+                    "clients_connected",
+                    "events_processed",
+                    "errors",
+                ]:
                     lines.append(f"  • {key.replace('_', ' ').title()}: {value}")
-        
-        lines.extend([
-            f"",
-            f"MANUAL RESOLUTION REQUIRED:",
-        ])
-        
+
+        lines.extend(
+            [
+                "",
+                "MANUAL RESOLUTION REQUIRED:",
+            ]
+        )
+
         for i, step in enumerate(self._get_resolution_steps(), 1):
             lines.append(f"  {i}. {step}")
-        
+
         return "\n".join(lines)
-    
+
     def _get_resolution_steps(self) -> List[str]:
         """Get manual resolution steps for recovery failures."""
         steps = [
@@ -465,51 +518,61 @@ class RecoveryFailedError(SocketIOServerError):
             "Verify system resources (CPU, memory, disk space)",
             "Check network connectivity and port availability",
         ]
-        
+
         if self.recovery_action == "restart":
-            steps.extend([
-                "Manually stop the server process",
-                "Wait for complete shutdown (check process list)",
-                "Remove any stale PID files",
-                "Restart the server manually"
-            ])
+            steps.extend(
+                [
+                    "Manually stop the server process",
+                    "Wait for complete shutdown (check process list)",
+                    "Remove any stale PID files",
+                    "Restart the server manually",
+                ]
+            )
         elif self.recovery_action == "cleanup":
-            steps.extend([
-                "Manually identify and clean up stale resources",
-                "Check for zombie processes",
-                "Clear temporary files and logs if needed"
-            ])
+            steps.extend(
+                [
+                    "Manually identify and clean up stale resources",
+                    "Check for zombie processes",
+                    "Clear temporary files and logs if needed",
+                ]
+            )
         elif self.recovery_action == "port_reset":
-            steps.extend([
-                "Check what's using the required port",
-                "Stop conflicting processes",
-                "Wait for port cleanup",
-                "Consider using a different port temporarily"
-            ])
-        
-        steps.extend([
-            "Review health monitoring configuration",
-            "Consider adjusting recovery thresholds if appropriate",
-            "Monitor server stability after manual intervention"
-        ])
-        
+            steps.extend(
+                [
+                    "Check what's using the required port",
+                    "Stop conflicting processes",
+                    "Wait for port cleanup",
+                    "Consider using a different port temporarily",
+                ]
+            )
+
+        steps.extend(
+            [
+                "Review health monitoring configuration",
+                "Consider adjusting recovery thresholds if appropriate",
+                "Monitor server stability after manual intervention",
+            ]
+        )
+
         return steps
 
 
 class HealthCheckError(SocketIOServerError):
     """Error raised when health monitoring detects critical issues.
-    
+
     This error provides detailed health status information and guidance
     for addressing system health problems.
     """
-    
-    def __init__(self,
-                 check_name: str,
-                 check_status: str,
-                 check_details: Dict[str, Any] = None,
-                 threshold_exceeded: Dict[str, Any] = None):
+
+    def __init__(
+        self,
+        check_name: str,
+        check_status: str,
+        check_details: Optional[Dict[str, Any]] = None,
+        threshold_exceeded: Optional[Dict[str, Any]] = None,
+    ):
         """Initialize health check error.
-        
+
         Args:
             check_name: Name of the failed health check
             check_status: Status of the health check (critical, warning, failed)
@@ -520,158 +583,175 @@ class HealthCheckError(SocketIOServerError):
         self.check_status = check_status
         self.check_details = check_details or {}
         self.threshold_exceeded = threshold_exceeded or {}
-        
+
         message = self._build_error_message()
-        
+
         context = {
             "check_name": check_name,
             "check_status": check_status,
             "check_details": check_details,
             "threshold_exceeded": threshold_exceeded,
-            "resolution_steps": self._get_resolution_steps()
+            "resolution_steps": self._get_resolution_steps(),
         }
-        
+
         super().__init__(message, "health_check_failed", context)
-    
+
     def _build_error_message(self) -> str:
         """Build error message for health check failure."""
-        status_emoji = {
-            "critical": "🚨",
-            "warning": "⚠️",
-            "failed": "❌"
-        }
-        
+        status_emoji = {"critical": "🚨", "warning": "⚠️", "failed": "❌"}
+
         emoji = status_emoji.get(self.check_status, "🔍")
-        
+
         lines = [
             f"{emoji} Health check failed: {self.check_name}",
-            f"",
-            f"CHECK DETAILS:",
+            "",
+            "CHECK DETAILS:",
             f"  • Check: {self.check_name}",
             f"  • Status: {self.check_status.upper()}",
         ]
-        
+
         # Add check details
         if self.check_details:
             for key, value in self.check_details.items():
-                if key not in ['raw_data', 'internal_state']:  # Skip internal data
+                if key not in ["raw_data", "internal_state"]:  # Skip internal data
                     lines.append(f"  • {key.replace('_', ' ').title()}: {value}")
-        
+
         # Add threshold information
         if self.threshold_exceeded:
-            lines.extend([
-                f"",
-                f"THRESHOLDS EXCEEDED:",
-            ])
+            lines.extend(
+                [
+                    "",
+                    "THRESHOLDS EXCEEDED:",
+                ]
+            )
             for metric, info in self.threshold_exceeded.items():
-                current = info.get('current', 'unknown')
-                threshold = info.get('threshold', 'unknown')
-                lines.append(f"  • {metric.title()}: {current} (threshold: {threshold})")
-        
-        lines.extend([
-            f"",
-            f"RECOMMENDED ACTIONS:",
-        ])
-        
+                current = info.get("current", "unknown")
+                threshold = info.get("threshold", "unknown")
+                lines.append(
+                    f"  • {metric.title()}: {current} (threshold: {threshold})"
+                )
+
+        lines.extend(
+            [
+                "",
+                "RECOMMENDED ACTIONS:",
+            ]
+        )
+
         for i, step in enumerate(self._get_resolution_steps(), 1):
             lines.append(f"  {i}. {step}")
-        
+
         return "\n".join(lines)
-    
+
     def _get_resolution_steps(self) -> List[str]:
         """Get resolution steps based on health check type."""
         steps = []
-        
+
         if "cpu" in self.check_name.lower():
-            steps.extend([
-                "Check for runaway processes consuming CPU",
-                "Consider adding rate limiting or request throttling",
-                "Monitor CPU usage patterns over time"
-            ])
+            steps.extend(
+                [
+                    "Check for runaway processes consuming CPU",
+                    "Consider adding rate limiting or request throttling",
+                    "Monitor CPU usage patterns over time",
+                ]
+            )
         elif "memory" in self.check_name.lower():
-            steps.extend([
-                "Check for memory leaks in the application",
-                "Monitor memory usage trends",
-                "Consider restarting if memory usage is excessive",
-                "Review event history size limits"
-            ])
-        elif "network" in self.check_name.lower() or "connectivity" in self.check_name.lower():
-            steps.extend([
-                "Check network connectivity to required services",
-                "Verify firewall settings and port accessibility",
-                "Test network latency and bandwidth"
-            ])
+            steps.extend(
+                [
+                    "Check for memory leaks in the application",
+                    "Monitor memory usage trends",
+                    "Consider restarting if memory usage is excessive",
+                    "Review event history size limits",
+                ]
+            )
+        elif (
+            "network" in self.check_name.lower()
+            or "connectivity" in self.check_name.lower()
+        ):
+            steps.extend(
+                [
+                    "Check network connectivity to required services",
+                    "Verify firewall settings and port accessibility",
+                    "Test network latency and bandwidth",
+                ]
+            )
         elif "disk" in self.check_name.lower() or "file" in self.check_name.lower():
-            steps.extend([
-                "Check available disk space",
-                "Clean up old log files and temporary data",
-                "Verify file permissions and access"
-            ])
-        
+            steps.extend(
+                [
+                    "Check available disk space",
+                    "Clean up old log files and temporary data",
+                    "Verify file permissions and access",
+                ]
+            )
+
         # General steps for all health check failures
-        steps.extend([
-            "Review recent system changes or deployments",
-            "Check system logs for related errors",
-            "Consider adjusting health check thresholds if appropriate",
-            "Monitor the issue to identify patterns or trends"
-        ])
-        
+        steps.extend(
+            [
+                "Review recent system changes or deployments",
+                "Check system logs for related errors",
+                "Consider adjusting health check thresholds if appropriate",
+                "Monitor the issue to identify patterns or trends",
+            ]
+        )
+
         return steps
 
 
 def format_troubleshooting_guide(error: SocketIOServerError) -> str:
     """Format a comprehensive troubleshooting guide for any Socket.IO server error.
-    
+
     Args:
         error: The error instance to create troubleshooting guide for
-        
+
     Returns:
         Formatted troubleshooting guide as a string
     """
     lines = [
-        f"═══════════════════════════════════════════════════════════════",
-        f"🔧 CLAUDE MPM SOCKET.IO SERVER TROUBLESHOOTING GUIDE",
-        f"═══════════════════════════════════════════════════════════════",
-        f"",
+        "═══════════════════════════════════════════════════════════════",
+        "🔧 CLAUDE MPM SOCKET.IO SERVER TROUBLESHOOTING GUIDE",
+        "═══════════════════════════════════════════════════════════════",
+        "",
         f"ERROR TYPE: {error.__class__.__name__}",
         f"ERROR CODE: {error.error_code}",
         f"TIMESTAMP: {error.timestamp}",
-        f"",
+        "",
         str(error),
-        f"",
-        f"ADDITIONAL TROUBLESHOOTING:",
-        f"",
-        f"🔍 DIAGNOSTIC COMMANDS:",
-        f"  • Check running processes: ps aux | grep socketio",
+        "",
+        "ADDITIONAL TROUBLESHOOTING:",
+        "",
+        "🔍 DIAGNOSTIC COMMANDS:",
+        "  • Check running processes: ps aux | grep socketio",
         f"  • Check port usage: lsof -i :{error.context.get('port', 'PORT')}",
-        f"  • Check system resources: top or htop",
-        f"  • Check disk space: df -h",
-        f"  • Check logs: tail -f /path/to/claude-mpm.log",
-        f"",
-        f"🛠️ COMMON SOLUTIONS:",
-        f"  1. Restart the Socket.IO server completely",
-        f"  2. Clear any stale PID files",
-        f"  3. Check for zombie processes and clean them up",
-        f"  4. Verify network port availability",
-        f"  5. Check system resource availability (CPU, memory, disk)",
-        f"  6. Review server configuration and permissions",
-        f"",
-        f"📞 GETTING HELP:",
-        f"  • Check the claude-mpm documentation",
-        f"  • Review server logs for additional context",
-        f"  • Report persistent issues with this error information",
-        f"",
-        f"🔗 ERROR CONTEXT DATA:",
+        "  • Check system resources: top or htop",
+        "  • Check disk space: df -h",
+        "  • Check logs: tail -f /path/to/claude-mpm.log",
+        "",
+        "🛠️ COMMON SOLUTIONS:",
+        "  1. Restart the Socket.IO server completely",
+        "  2. Clear any stale PID files",
+        "  3. Check for zombie processes and clean them up",
+        "  4. Verify network port availability",
+        "  5. Check system resource availability (CPU, memory, disk)",
+        "  6. Review server configuration and permissions",
+        "",
+        "📞 GETTING HELP:",
+        "  • Check the claude-mpm documentation",
+        "  • Review server logs for additional context",
+        "  • Report persistent issues with this error information",
+        "",
+        "🔗 ERROR CONTEXT DATA:",
     ]
-    
+
     # Add structured context data
     for key, value in error.context.items():
         if key != "resolution_steps":  # Skip resolution steps as they're already shown
             lines.append(f"  • {key}: {value}")
-    
-    lines.extend([
-        f"",
-        f"═══════════════════════════════════════════════════════════════",
-    ])
-    
-    return "\n".join(lines)
+
+    lines.extend(
+        [
+            "",
+            "═══════════════════════════════════════════════════════════════",
+        ]
+    )
+
+    return "\n".join(lines)