claude-mpm 4.1.6__py3-none-any.whl → 4.1.7__py3-none-any.whl

claude_mpm/VERSION

@@ -1 +1 @@
-4.1.6
+4.1.7

claude_mpm/agents/templates/agent-manager.json

@@ -6,7 +6,7 @@
   "tool_choice": "auto",
   "metadata": {
     "description": "Manages agent creation, customization, deployment, and PM instruction configuration",
-    "version": "1.0.0",
+    "version": "1.1.0",
     "capabilities": [
       "agent-creation",
       "variant-management",

claude_mpm/agents/templates/agent-manager.md

@@ -8,30 +8,72 @@ You are the Agent Manager, responsible for creating, customizing, deploying, and
 
 ## Agent Hierarchy Understanding
 
-You operate within a three-tier agent hierarchy with clear precedence:
+You operate within a three-source agent hierarchy with VERSION-BASED precedence:
 
-1. **Project Level** (`.claude/agents/`) - Highest priority
-   - Project-specific agents that override all others
-   - Deployed per-project for custom workflows
+1. **Project Level** (`.claude/agents/`) - Project-specific deployment
+   - Project-specific agents for custom workflows
+   - Deployed per-project for team collaboration
    - Persists with project repository
 
-2. **User Level** (`~/.claude/agents/`) - Middle priority
+2. **User Level** (`~/.claude/agents/`) - User's personal deployment
    - User's personal agent collection
    - Shared across all projects for that user
-   - Overrides system agents but not project agents
+   - Personal customizations and preferences
 
-3. **System Level** (Framework installation) - Lowest priority
+3. **System Level** (`/src/claude_mpm/agents/templates/`) - Framework built-in
    - Default agents shipped with claude-mpm
    - Available to all users and projects
-   - Can be overridden at user or project level
+   - Base templates and standard agents
 
-## PM Instructions Hierarchy
+**IMPORTANT: VERSION-BASED PRECEDENCE**
+- The agent with the HIGHEST semantic version wins, regardless of source
+- Example: Project agent v1.0.0 < User agent v2.0.0 < System agent v3.0.0
+- Development agents use version 999.x.x to always override production versions
+- MultiSourceAgentDeploymentService handles version resolution
 
-You also manage PM (Project Manager) instruction files:
+## PM Instructions Customization System
 
-1. **User CLAUDE.md** (`~/.claude/CLAUDE.md`) - User's global PM instructions
-2. **Project CLAUDE.md** (`<project>/CLAUDE.md`) - Project-specific PM instructions
-3. **Framework Instructions** (`BASE_PM.md`, `INSTRUCTIONS.md`) - Default PM behavior
+You manage a comprehensive PM (Project Manager) customization system:
+
+### Instruction Loading Order (Highest to Lowest Priority)
+
+1. **Project Instructions** (`./.claude-mpm/`) - Project-specific PM behavior
+   - `INSTRUCTIONS.md` - Main PM instructions
+   - `WORKFLOW.md` - Custom workflow patterns
+   - `MEMORY.md` - Memory system configuration
+   - `OUTPUT_STYLE.md` - Response formatting preferences
+   - Highest priority, overrides all others
+
+2. **User Instructions** (`~/.claude-mpm/`) - User's personal PM settings
+   - Same files as project level
+   - Applied across all user's projects
+   - Overrides system defaults
+
+3. **System Instructions** (Framework built-in) - Default PM behavior
+   - `BASE_PM.md` - Core PM framework
+   - `INSTRUCTIONS.md` - Default instructions
+   - Base behavior for all deployments
+
+### Configuration System
+
+Additionally manage configuration files:
+
+1. **Project Config** (`./.claude-mpm/configuration.yaml`)
+2. **User Config** (`~/.claude-mpm/configuration.yaml`)
+3. **System Config** (`/etc/claude-mpm/configuration.yaml`)
+
+Features configured:
+- Response logging settings
+- Agent exclusion lists
+- Memory system parameters
+- SocketIO server configuration
+- Performance tuning
+
+**IMPORTANT NOTES**:
+- CLAUDE.md files are NOT loaded by MPM (handled by Claude Code directly)
+- SystemInstructionsDeployer auto-deploys PM instructions on first run
+- FrameworkLoader orchestrates all customization loading
+- Template variable {{CAPABILITIES}} is dynamically replaced with agent list
 
 ## Core Responsibilities
 
@@ -61,10 +103,13 @@ You also manage PM (Project Manager) instruction files:
 - Clean deployment of obsolete agents
 
 ### 5. PM Instruction Management
-- Create and edit CLAUDE.md files
-- Customize delegation patterns
-- Modify workflow sequences
-- Configure PM behavior at user/project level
+- Create and edit INSTRUCTIONS.md files at project/user levels
+- Customize WORKFLOW.md for delegation patterns
+- Configure MEMORY.md for memory system behavior
+- Manage OUTPUT_STYLE.md for response formatting
+- Edit configuration.yaml for system settings
+- Deploy instruction templates with SystemInstructionsDeployer
+- Note: CLAUDE.md is for Claude Code, not MPM
 
 ### 6. Discovery & Listing
 - List all available agents across tiers
@@ -111,11 +156,17 @@ You also manage PM (Project Manager) instruction files:
 
 ### `customize-pm` - Edit PM Instructions
 ```python
-# Edit CLAUDE.md at user or project level
-# Provide template if creating new
-# Validate markdown structure
+# Edit instruction files at user or project level:
+#   - INSTRUCTIONS.md (main PM behavior)
+#   - WORKFLOW.md (delegation patterns)
+#   - MEMORY.md (memory configuration)
+#   - OUTPUT_STYLE.md (response formatting)
+# Edit configuration.yaml for system settings
+# Provide templates if creating new
+# Validate file structure
 # Show diff of changes
 # Backup before modification
+# Note: CLAUDE.md is separate (for Claude Code)
 ```
 
 ### `show` - Display Agent Details
@@ -149,7 +200,7 @@ When creating agents, use this structure:
   "tool_choice": "auto|required|any",
   "metadata": {
     "description": "Agent purpose and capabilities",
-    "version": "1.0.0",
+    "version": "1.0.0",  // Semantic version - determines precedence!
     "capabilities": ["capability1", "capability2"],
     "tags": ["tag1", "tag2"],
     "author": "Creator Name",
@@ -158,6 +209,12 @@ When creating agents, use this structure:
 }
 ```
 
+### Version Guidelines
+- Production versions: Use standard semantic versioning (1.0.0, 1.1.0, 2.0.0)
+- Development versions: Use 999.x.x to override all other versions
+- Version determines precedence across ALL sources (project/user/system)
+- Higher version always wins regardless of deployment location
+
 ## Validation Rules
 
 ### Agent ID Validation
@@ -218,9 +275,12 @@ When creating agents, use this structure:
 
 ### PM Customization
 - Keep instructions focused and clear
-- Document custom workflows
-- Test delegation patterns
-- Version control CLAUDE.md files
+- Use INSTRUCTIONS.md for main behavior (not CLAUDE.md)
+- Document workflows in WORKFLOW.md
+- Configure memory in MEMORY.md
+- Set output style in OUTPUT_STYLE.md
+- Test delegation patterns thoroughly
+- Version control all .claude-mpm/ files
 
 ### Deployment Strategy
 - Start with user level for testing
@@ -237,16 +297,31 @@ When creating agents, use this structure:
 - Integrate with discovery service
 
 ### With MultiSourceAgentDeploymentService
-- Handle multi-tier deployments
-- Manage source precedence
-- Coordinate cross-tier operations
-- Track deployment sources
+- Handle multi-source deployments
+- Manage VERSION-BASED precedence (highest version wins)
+- Coordinate cross-source operations
+- Track deployment sources and versions
+- Resolve agent conflicts by semantic version
+- Support development versions (999.x.x)
 
 ### With Agent Discovery
-- Register new agents
-- Update agent registry
-- Refresh discovery cache
-- Notify of changes
+- Register new agents with version tracking
+- Update agent registry with version resolution
+- Refresh discovery cache after deployments
+- Notify of version conflicts or overrides
+- Display effective agent (highest version)
+
+### With SystemInstructionsDeployer
+- Auto-deploy PM instructions on first run
+- Create .claude-mpm directories as needed
+- Deploy instruction templates
+- Handle user/project customization
+
+### With FrameworkLoader
+- Load PM instructions in priority order
+- Process {{CAPABILITIES}} template variable
+- Merge instruction files appropriately
+- Handle configuration loading
 
 ## Memory Considerations
 
@@ -285,8 +360,10 @@ Brief description of action taken
 ### Agent Information (if relevant)
 - ID: agent-id
 - Location: [P/U/S] /path/to/agent
-- Version: 1.0.0
-- Overrides: [list if any]
+- Version: 1.0.0 (determines precedence)
+- Effective Source: [Project/User/System] based on version
+- Overridden Versions: [list lower versions if any]
+- Development Mode: Yes/No (if version 999.x.x)
 ```
 
 ## Security Considerations

claude_mpm/config/socketio_config.py

@@ -10,6 +10,8 @@ WHY configuration management:
 - Supports multiple deployment scenarios (local, PyPI, Docker, etc.)
 - Provides environment-specific defaults
 - Allows runtime configuration overrides
+
+CRITICAL: Ping/pong settings MUST match between client and server to prevent disconnections!
 """
 
 import os
@@ -19,6 +21,33 @@ from typing import Any, Dict, List, Optional
 # Import constants for default values
 from claude_mpm.core.constants import NetworkConfig, RetryConfig, SystemLimits
 
+# Connection stability settings - MUST be consistent between client and server
+CONNECTION_CONFIG = {
+    # Ping/pong intervals (milliseconds for client, seconds for server)
+    'ping_interval_ms': 45000,     # 45 seconds (for client JavaScript)
+    'ping_interval': 45,            # 45 seconds (for server Python)
+    'ping_timeout_ms': 20000,       # 20 seconds (for client JavaScript)  
+    'ping_timeout': 20,             # 20 seconds (for server Python)
+    
+    # Connection management
+    'stale_timeout': 180,           # 3 minutes before considering connection stale
+    'health_check_interval': 30,    # Health check every 30 seconds
+    'event_ttl': 300,              # Keep events for 5 minutes for replay
+    
+    # Client reconnection settings
+    'reconnection_attempts': 5,     # Number of reconnection attempts
+    'reconnection_delay': 1000,     # Initial delay in ms
+    'reconnection_delay_max': 5000, # Maximum delay in ms
+    
+    # Feature flags
+    'enable_extra_heartbeat': False,  # Disable redundant heartbeats
+    'enable_health_monitoring': True,  # Enable connection health monitoring
+    
+    # Buffer settings
+    'max_events_buffer': 1000,      # Maximum events to buffer per client
+    'max_http_buffer_size': 1e8,    # 100MB max buffer for large payloads
+}
+
 
 @dataclass
 class SocketIOConfig:
@@ -29,11 +58,11 @@ class SocketIOConfig:
     port: int = NetworkConfig.DEFAULT_DASHBOARD_PORT
     server_id: Optional[str] = None
 
-    # Connection settings
+    # Connection settings - Use centralized config for consistency
     cors_allowed_origins: str = "*"  # Configure properly for production
-    ping_timeout: int = NetworkConfig.PING_TIMEOUT_STANDARD
-    ping_interval: int = NetworkConfig.PING_INTERVAL_STANDARD
-    max_http_buffer_size: int = 1000000
+    ping_timeout: int = CONNECTION_CONFIG['ping_timeout']  # 20 seconds
+    ping_interval: int = CONNECTION_CONFIG['ping_interval']  # 45 seconds
+    max_http_buffer_size: int = int(CONNECTION_CONFIG['max_http_buffer_size'])
 
     # Compatibility settings
     min_client_version: str = "0.7.0"

claude_mpm/dashboard/static/js/socket-client.js

@@ -38,10 +38,10 @@ class SocketClient {
         this.eventQueue = [];
         this.maxQueueSize = 100;
         
-        // Retry configuration
+        // Retry configuration - Match server settings
         this.retryAttempts = 0;
-        this.maxRetryAttempts = 3;
-        this.retryDelays = [1000, 2000, 4000]; // Exponential backoff
+        this.maxRetryAttempts = 5;  // Increased from 3 to 5 for better stability
+        this.retryDelays = [1000, 2000, 3000, 4000, 5000]; // Exponential backoff with 5 attempts
         this.pendingEmissions = new Map(); // Track pending emissions for retry
         
         // Health monitoring
@@ -98,12 +98,12 @@ class SocketClient {
             reconnection: true,
             reconnectionDelay: 1000,
             reconnectionDelayMax: 5000,
-            reconnectionAttempts: Infinity,  // Keep trying indefinitely
-            timeout: 20000,  // Increase connection timeout
+            reconnectionAttempts: 5,  // Try 5 times then stop (was Infinity which can cause issues)
+            timeout: 20000,  // Connection timeout
             forceNew: true,
             transports: ['websocket', 'polling'],
-            pingInterval: 25000,  // Match server setting
-            pingTimeout: 60000    // Match server setting
+            pingInterval: 45000,  // CRITICAL: Must match server's 45 seconds
+            pingTimeout: 20000    // CRITICAL: Must match server's 20 seconds
         });
 
         this.setupSocketHandlers();
@@ -143,17 +143,22 @@ class SocketClient {
         });
 
         this.socket.on('disconnect', (reason) => {
-            console.log('Disconnected from server:', reason);
+            // Enhanced logging for debugging disconnection issues
+            const disconnectInfo = {
+                reason: reason,
+                timestamp: new Date().toISOString(),
+                wasConnected: this.isConnected,
+                uptimeSeconds: this.lastConnectTime ? ((Date.now() - this.lastConnectTime) / 1000).toFixed(1) : 0,
+                lastPing: this.lastPingTime ? ((Date.now() - this.lastPingTime) / 1000).toFixed(1) + 's ago' : 'never',
+                lastPong: this.lastPongTime ? ((Date.now() - this.lastPongTime) / 1000).toFixed(1) + 's ago' : 'never'
+            };
+            
+            console.log('Disconnected from server:', disconnectInfo);
+            
             this.isConnected = false;
             this.isConnecting = false;
             this.disconnectTime = Date.now();
             
-            // Calculate uptime
-            if (this.lastConnectTime) {
-                const uptime = (Date.now() - this.lastConnectTime) / 1000;
-                console.log(`Connection uptime was ${uptime.toFixed(1)}s`);
-            }
-            
             this.notifyConnectionStatus(`Disconnected: ${reason}`, 'disconnected');
 
             // Emit disconnect callback
@@ -161,8 +166,21 @@ class SocketClient {
                 callback(reason)
             );
             
-            // Start auto-reconnect if it was an unexpected disconnect
-            if (reason === 'transport close' || reason === 'ping timeout') {
+            // Detailed reason analysis for auto-reconnect decision
+            const reconnectReasons = [
+                'transport close',      // Network issue
+                'ping timeout',         // Server not responding
+                'transport error',      // Connection error
+                'io server disconnect', // Server initiated disconnect (might be restart)
+            ];
+            
+            if (reconnectReasons.includes(reason)) {
+                console.log(`Auto-reconnect triggered for reason: ${reason}`);
+                this.scheduleReconnect();
+            } else if (reason === 'io client disconnect') {
+                console.log('Client-initiated disconnect, not auto-reconnecting');
+            } else {
+                console.log(`Unknown disconnect reason: ${reason}, attempting reconnect anyway`);
                 this.scheduleReconnect();
             }
         });
@@ -222,6 +240,12 @@ class SocketClient {
             });
         });
         
+        // Track pong responses from server
+        this.socket.on('pong', (data) => {
+            this.lastPongTime = Date.now();
+            // console.log('Received pong from server');
+        });
+        
         // Session and event handlers (legacy/fallback)
         this.socket.on('session.started', (data) => {
             this.addEvent({ type: 'session', subtype: 'started', timestamp: new Date().toISOString(), data });

claude_mpm/hooks/claude_hooks/services/connection_manager.py

@@ -170,11 +170,28 @@ class ConnectionManagerService:
                 # Publish to EventBus with topic format: hook.{event}
                 topic = f"hook.{event}"
                 self.event_bus.publish(topic, claude_event_data)
+
+                # Enhanced verification logging
                 if DEBUG:
                     print(f"✅ Published to EventBus: {topic}", file=sys.stderr)
+                    # Get EventBus stats to verify publication
+                    if hasattr(self.event_bus, "get_stats"):
+                        stats = self.event_bus.get_stats()
+                        print(
+                            f"📊 EventBus stats after publish: {stats}", file=sys.stderr
+                        )
+                    # Log the number of data keys being published
+                    if isinstance(claude_event_data, dict):
+                        print(
+                            f"📦 Published data keys: {list(claude_event_data.keys())}",
+                            file=sys.stderr,
+                        )
             except Exception as e:
                 if DEBUG:
                     print(f"⚠️ Failed to publish to EventBus: {e}", file=sys.stderr)
+                    import traceback
+
+                    traceback.print_exc(file=sys.stderr)
 
         # Warn if neither method is available
         if not self.connection_pool and not self.event_bus and DEBUG:

claude_mpm/services/event_bus/direct_relay.py

@@ -59,9 +59,30 @@ class DirectSocketIORelay:
 
         # Add debug logging for verification
         logger.info("[DirectRelay] Subscribed to hook.* events on EventBus")
+
+        # Check and log broadcaster availability
+        broadcaster_available = (
+            self.server
+            and hasattr(self.server, "broadcaster")
+            and self.server.broadcaster is not None
+        )
         logger.info(
-            f"[DirectRelay] Server broadcaster available: {self.server and self.server.broadcaster is not None}"
+            f"[DirectRelay] Server broadcaster available: {broadcaster_available}"
         )
+        if not broadcaster_available:
+            if not self.server:
+                logger.warning(
+                    "[DirectRelay] No server instance provided - events will not be relayed!"
+                )
+            elif not hasattr(self.server, "broadcaster"):
+                logger.warning(
+                    "[DirectRelay] Server has no broadcaster attribute - events will not be relayed!"
+                )
+            else:
+                logger.warning(
+                    "[DirectRelay] Server broadcaster is None - events will not be relayed!"
+                )
+
         logger.info(f"[DirectRelay] EventBus instance: {self.event_bus is not None}")
 
         # Mark as connected after successful subscription
@@ -76,9 +97,28 @@ class DirectSocketIORelay:
             data: The event data
         """
         try:
-            # Log the event reception
+            # Enhanced debug logging for troubleshooting
             if self.debug:
                 logger.debug(f"[DirectRelay] Received event: {event_type}")
+                logger.debug(f"[DirectRelay] Event data type: {type(data).__name__}")
+                logger.debug(
+                    f"[DirectRelay] Event data keys: {list(data.keys()) if isinstance(data, dict) else 'not-dict'}"
+                )
+                logger.debug(
+                    f"[DirectRelay] Relay state - enabled: {self.enabled}, connected: {self.connected}"
+                )
+                logger.debug(
+                    f"[DirectRelay] Server state - has_server: {self.server is not None}, has_broadcaster: {self.server and hasattr(self.server, 'broadcaster') and self.server.broadcaster is not None}"
+                )
+
+            # Always log reception of important events
+            if event_type in [
+                "hook.pre_tool",
+                "hook.post_tool",
+                "hook.user_prompt",
+                "hook.subagent_stop",
+            ]:
+                logger.info(f"[DirectRelay] Processing important event: {event_type}")
 
             # Only relay hook events
             if event_type.startswith("hook."):
@@ -143,9 +183,26 @@ class DirectSocketIORelay:
                             f"[DirectRelay] Broadcasted hook event: {event_type}"
                         )
                 else:
+                    # Enhanced logging when broadcaster is not available
                     logger.warning(
                         f"[DirectRelay] Server broadcaster not available for {event_type}"
                     )
+                    if self.server:
+                        logger.warning(
+                            f"[DirectRelay] Server exists but broadcaster is None"
+                        )
+                        logger.warning(
+                            f"[DirectRelay] Server type: {type(self.server).__name__}"
+                        )
+                        logger.warning(
+                            f"[DirectRelay] Server has broadcaster attr: {hasattr(self.server, 'broadcaster')}"
+                        )
+                        if hasattr(self.server, "broadcaster"):
+                            logger.warning(
+                                f"[DirectRelay] Broadcaster value: {self.server.broadcaster}"
+                            )
+                    else:
+                        logger.warning(f"[DirectRelay] Server is None")
                     self.stats["events_failed"] += 1
 
         except Exception as e:

claude_mpm/services/socketio/handlers/connection_handler.py

@@ -177,7 +177,7 @@ class EnhancedConnectionEventHandler(BaseEventHandler):
         async def ping(sid):
             """Handle ping from client for health monitoring."""
             try:
-                # Update activity in connection manager
+                # Update activity in connection manager - CRITICAL for preventing stale connections
                 if self.server.connection_manager:
                     await self.server.connection_manager.update_activity(sid, "ping")
 
@@ -293,23 +293,8 @@ class EnhancedConnectionEventHandler(BaseEventHandler):
             except Exception as e:
                 self.logger.error(f"Error getting connection stats for {sid}: {e}")
 
-        @sio.event
-        async def heartbeat(sid):
-            """Handle client heartbeat for connection monitoring."""
-            try:
-                # Update activity
-                if self.server.connection_manager:
-                    await self.server.connection_manager.update_activity(sid, "event")
-
-                # Send heartbeat response
-                await sio.emit(
-                    "heartbeat_response",
-                    {"timestamp": datetime.now().isoformat(), "status": "alive"},
-                    room=sid,
-                )
-
-            except Exception as e:
-                self.logger.error(f"Error handling heartbeat from {sid}: {e}")
+        # Heartbeat handler removed - Using Socket.IO's built-in ping/pong instead
+        # This prevents conflicting heartbeat systems that can cause disconnections
 
         self.logger.info("Enhanced connection event handlers registered")
 

claude_mpm/services/socketio/server/connection_manager.py

@@ -70,22 +70,30 @@ class ClientConnection:
     metrics: ConnectionMetrics = field(default_factory=ConnectionMetrics)
     metadata: Dict[str, Any] = field(default_factory=dict)
 
-    def is_healthy(self, timeout: float = 90.0) -> bool:
-        """Check if connection is healthy based on activity."""
+    def is_healthy(self, timeout: float = 180.0) -> bool:
+        """Check if connection is healthy based on activity.
+        
+        Args:
+            timeout: Seconds before considering connection unhealthy (default 180s)
+        """
         if self.state != ConnectionState.CONNECTED:
             return False
 
         now = time.time()
 
         # Check last activity (ping, pong, or event)
+        # Include metrics.last_activity for more comprehensive tracking
         last_activity = max(
             self.last_ping or 0,
             self.last_pong or 0,
             self.last_event or 0,
+            self.metrics.last_activity or 0,
             self.connected_at,
         )
 
-        return (now - last_activity) < timeout
+        # Add grace period for network hiccups (additional 10% of timeout)
+        grace_period = timeout * 1.1
+        return (now - last_activity) < grace_period
 
     def calculate_quality(self) -> float:
         """Calculate connection quality score (0-1)."""
@@ -140,22 +148,26 @@ class ConnectionManager:
     - Automatic event replay on reconnection
     """
 
-    def __init__(self, max_buffer_size: int = 1000, event_ttl: int = 300):
+    def __init__(self, max_buffer_size: int = None, event_ttl: int = None):
         """
-        Initialize connection manager.
+        Initialize connection manager with centralized configuration.
 
         Args:
-            max_buffer_size: Maximum events to buffer per client
-            event_ttl: Time-to-live for buffered events in seconds
+            max_buffer_size: Maximum events to buffer per client (uses config if None)
+            event_ttl: Time-to-live for buffered events in seconds (uses config if None)
         """
+        from ....config.socketio_config import CONNECTION_CONFIG
+        
         self.logger = get_logger(__name__)
         self.connections: Dict[str, ClientConnection] = {}
         self.client_mapping: Dict[str, str] = {}  # client_id -> current sid
-        self.max_buffer_size = max_buffer_size
-        self.event_ttl = event_ttl
+        
+        # Use centralized configuration with optional overrides
+        self.max_buffer_size = max_buffer_size or CONNECTION_CONFIG['max_events_buffer']
+        self.event_ttl = event_ttl or CONNECTION_CONFIG['event_ttl']
         self.global_sequence = 0
-        self.health_check_interval = 30  # seconds
-        self.stale_timeout = 90  # seconds
+        self.health_check_interval = CONNECTION_CONFIG['health_check_interval']  # 30 seconds
+        self.stale_timeout = CONNECTION_CONFIG['stale_timeout']  # 180 seconds (was 90)
         self.health_task = None
         self._lock = asyncio.Lock()
 
@@ -439,20 +451,39 @@ class ConnectionManager:
                     if conn.is_healthy(self.stale_timeout):
                         report["healthy"] += 1
                     else:
-                        # Mark as stale
-                        conn.state = ConnectionState.STALE
-                        report["stale"] += 1
-                        self.logger.warning(
-                            f"Connection {conn.client_id} marked as stale "
-                            f"(last activity: {now - conn.metrics.last_activity:.1f}s ago)"
+                        # Mark as stale only if really stale (no grace period activity)
+                        last_activity = max(
+                            conn.last_ping or 0,
+                            conn.last_pong or 0,
+                            conn.last_event or 0,
+                            conn.metrics.last_activity or 0,
+                            conn.connected_at,
                         )
+                        time_since_activity = now - last_activity
+                        
+                        # Only mark as stale if significantly over timeout (2x)
+                        if time_since_activity > (self.stale_timeout * 2):
+                            conn.state = ConnectionState.STALE
+                            report["stale"] += 1
+                            self.logger.warning(
+                                f"Connection {conn.client_id} marked as stale "
+                                f"(last activity: {time_since_activity:.1f}s ago)"
+                            )
+                        else:
+                            # Connection is borderline - keep it alive but log
+                            report["healthy"] += 1
+                            self.logger.debug(
+                                f"Connection {conn.client_id} borderline "
+                                f"(last activity: {time_since_activity:.1f}s ago)"
+                            )
+                            
                 elif conn.state == ConnectionState.DISCONNECTED:
                     report["disconnected"] += 1
 
-                    # Clean up old disconnected connections
+                    # Clean up old disconnected connections (be conservative)
                     if (
                         conn.disconnected_at
-                        and (now - conn.disconnected_at) > self.event_ttl
+                        and (now - conn.disconnected_at) > (self.event_ttl * 2)  # Double the TTL
                     ):
                         to_clean.append(sid)
 

claude_mpm/services/socketio/server/core.py

@@ -158,14 +158,18 @@ class SocketIOServerCore:
     async def _start_server(self):
         """Start the Socket.IO server with aiohttp."""
         try:
-            # Create Socket.IO server with proper ping/pong configuration
+            # Import centralized configuration for consistency
+            from ....config.socketio_config import CONNECTION_CONFIG
+            
+            # Create Socket.IO server with centralized configuration
+            # CRITICAL: These values MUST match client settings to prevent disconnections
             self.sio = socketio.AsyncServer(
                 cors_allowed_origins="*",
                 logger=False,  # Disable Socket.IO's own logging
                 engineio_logger=False,
-                ping_interval=25,  # Send ping every 25 seconds
-                ping_timeout=60,  # Wait 60 seconds for pong response
-                max_http_buffer_size=1e8,  # 100MB max buffer
+                ping_interval=CONNECTION_CONFIG['ping_interval'],  # 45 seconds from config
+                ping_timeout=CONNECTION_CONFIG['ping_timeout'],    # 20 seconds from config
+                max_http_buffer_size=CONNECTION_CONFIG['max_http_buffer_size'],  # 100MB from config
             )
 
             # Create aiohttp application
@@ -196,9 +200,13 @@ class SocketIOServerCore:
             if self.static_path:
                 self.logger.info(f"Serving static files from: {self.static_path}")
 
-            # Start heartbeat task
-            self.heartbeat_task = asyncio.create_task(self._heartbeat_loop())
-            self.logger.info("Started system heartbeat task")
+            # Conditionally start heartbeat task based on configuration
+            from ....config.socketio_config import CONNECTION_CONFIG
+            if CONNECTION_CONFIG.get('enable_extra_heartbeat', False):
+                self.heartbeat_task = asyncio.create_task(self._heartbeat_loop())
+                self.logger.info("Started system heartbeat task")
+            else:
+                self.logger.info("System heartbeat disabled (using Socket.IO ping/pong instead)")
 
             # Keep the server running
             while self.running:

claude_mpm/services/socketio/server/main.py

@@ -173,35 +173,64 @@ class SocketIOServer(SocketIOServiceInterface):
             f"[{datetime.now().isoformat()}] Setting up EventBus integration...",
             flush=True,
         )
-        try:
-            self.eventbus_integration = EventBusIntegration(self)
+
+        # CRITICAL: Ensure broadcaster is fully initialized before setting up EventBus
+        # The relay needs the broadcaster to be ready to relay events
+        if not self.broadcaster:
+            self.logger.error(
+                "Broadcaster not initialized - cannot setup EventBus integration"
+            )
             print(
-                f"[{datetime.now().isoformat()}] EventBusIntegration instance created",
+                f"[{datetime.now().isoformat()}] ERROR: Broadcaster not initialized",
+                flush=True,
+            )
+        else:
+            print(
+                f"[{datetime.now().isoformat()}] Broadcaster ready, proceeding with EventBus setup",
                 flush=True,
             )
 
-            if self.eventbus_integration.setup(self.port):
-                self.logger.info("EventBus integration setup successful")
+            try:
+                self.eventbus_integration = EventBusIntegration(self)
                 print(
-                    f"[{datetime.now().isoformat()}] EventBus integration setup successful",
+                    f"[{datetime.now().isoformat()}] EventBusIntegration instance created",
                     flush=True,
                 )
-            else:
-                self.logger.warning("EventBus integration setup failed or disabled")
+
+                if self.eventbus_integration.setup(self.port):
+                    self.logger.info("EventBus integration setup successful")
+                    print(
+                        f"[{datetime.now().isoformat()}] EventBus integration setup successful",
+                        flush=True,
+                    )
+
+                    # Verify relay is connected and has broadcaster
+                    if (
+                        hasattr(self.eventbus_integration, "relay")
+                        and self.eventbus_integration.relay
+                    ):
+                        relay_stats = self.eventbus_integration.relay.get_stats()
+                        self.logger.info(f"EventBus relay stats: {relay_stats}")
+                        print(
+                            f"[{datetime.now().isoformat()}] EventBus relay stats: {relay_stats}",
+                            flush=True,
+                        )
+                else:
+                    self.logger.warning("EventBus integration setup failed or disabled")
+                    print(
+                        f"[{datetime.now().isoformat()}] EventBus integration setup failed or disabled",
+                        flush=True,
+                    )
+            except Exception as e:
+                self.logger.error(f"Failed to setup EventBus integration: {e}")
                 print(
-                    f"[{datetime.now().isoformat()}] EventBus integration setup failed or disabled",
+                    f"[{datetime.now().isoformat()}] Failed to setup EventBus integration: {e}",
                     flush=True,
                 )
-        except Exception as e:
-            self.logger.error(f"Failed to setup EventBus integration: {e}")
-            print(
-                f"[{datetime.now().isoformat()}] Failed to setup EventBus integration: {e}",
-                flush=True,
-            )
-            import traceback
+                import traceback
 
-            traceback.print_exc()
-            self.eventbus_integration = None
+                traceback.print_exc()
+                self.eventbus_integration = None
 
         # Update running state
         self.running = self.core.running

{claude_mpm-4.1.6.dist-info → claude_mpm-4.1.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.1.6
+Version: 4.1.7
 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

{claude_mpm-4.1.6.dist-info → claude_mpm-4.1.7.dist-info}/RECORD

@@ -1,5 +1,5 @@
 claude_mpm/BUILD_NUMBER,sha256=toytnNjkIKPgQaGwDqQdC1rpNTAdSEc6Vja50d7Ovug,4
-claude_mpm/VERSION,sha256=w9Yv379QUvcGT8ToH1cuQa1SSo52GJWg_Ikc6-hN2jo,6
+claude_mpm/VERSION,sha256=IL2PXQTVrQbwaRBS2I7XrtbIpLEqZiqKK8JTfEKKnxo,6
 claude_mpm/__init__.py,sha256=lyTZAYGH4DTaFGLRNWJKk5Q5oTjzN5I6AXmfVX-Jff0,1512
 claude_mpm/__main__.py,sha256=Ro5UBWBoQaSAIoSqWAr7zkbLyvi4sSy28WShqAhKJG0,723
 claude_mpm/constants.py,sha256=5-k9ZbfDRe3WpGfHx3R0iTXokuOaZY-NcWcx1xkLTws,5678
@@ -22,8 +22,8 @@ claude_mpm/agents/frontmatter_validator.py,sha256=GiCxr13b-SFwvZNbNHDO0lFH9dFhsQ
 claude_mpm/agents/system_agent_config.py,sha256=HBDrtRld1ruPqrThA0j4vtMr4cBt0fT7qjDeCR79bps,24105
 claude_mpm/agents/schema/agent_schema.json,sha256=3p-_vcEAz5Py0ik7LPSJB9CQyE9L_zHhC82J0eCfn78,8784
 claude_mpm/agents/templates/__init__.py,sha256=kghxAWs3KvcAA9Esk3NI7caumYgW6fiW8vRO1-MEndU,2735
-claude_mpm/agents/templates/agent-manager.json,sha256=pRMILoAMxVZcc5g_XwStpJoz2K8LJo8sUyJB6bep6rI,628
-claude_mpm/agents/templates/agent-manager.md,sha256=vsy49vWxIlMVLX6H7_BtjPDaR4j_gkechvgWbN88aPI,8218
+claude_mpm/agents/templates/agent-manager.json,sha256=4iBwEgIZLk54BAC5qzqBXUNmB6zB1fm-sqQJkMDAx-0,628
+claude_mpm/agents/templates/agent-manager.md,sha256=evnX5dgSxxFmzOLV6K4aM4tgDFu7oPeNneMC_UqQQSs,11592
 claude_mpm/agents/templates/api_qa.json,sha256=hTdeNOgA2tzADCb2V9ExguFSvAv267yQYqa26AnOQHk,5786
 claude_mpm/agents/templates/code_analyzer.json,sha256=UOTXl6VTmzx1OoF5M4Bc9lQGriLf6Jq84rz30J77tEM,4718
 claude_mpm/agents/templates/data_engineer.json,sha256=rP3ffuaHwe0xGVpXShhVHTn1jEVMV2aAlnNGZL8j3jc,5629
@@ -95,7 +95,7 @@ claude_mpm/config/__init__.py,sha256=V2dyJQ8_gVCpNiCg8zYTQqE1RSeON5Zm8n5Ndkqhp1g
 claude_mpm/config/agent_config.py,sha256=d_cHE4HMkeZZrGjDGpBP655llV64p_E8DRDPPdsO1jg,14829
 claude_mpm/config/experimental_features.py,sha256=ma-Va7CVqOYrUEGZW6A4gdMRLHOpovHf8pHgP_3-xr0,7481
 claude_mpm/config/paths.py,sha256=Dl35_QF0kfC2I6Fy7ETcNjz7jlumNGt45qlRKqsPJrk,7611
-claude_mpm/config/socketio_config.py,sha256=qNLvjKZWUZEsNmSXUe0ueXu1q7-EOlxK3mdQquEZwTI,9714
+claude_mpm/config/socketio_config.py,sha256=5R1zouAmG1Nz9UayHqx_OPEXvCwgI3OzIMOaFr2sgSo,11204
 claude_mpm/core/__init__.py,sha256=QhEX_NpiCprUp87bV75FnMapblMeqC5soNVJXVvZObc,887
 claude_mpm/core/agent_name_normalizer.py,sha256=_h92sTPltmvqevCjdKQ7EsOz-CAm1-hd8GOubWjuRgw,8907
 claude_mpm/core/agent_registry.py,sha256=cPQsOSIyrspr3KpS-P9MQ6Dv_BLXa9BWhs9RM0iu4C4,18798
@@ -178,7 +178,7 @@ claude_mpm/dashboard/static/dist/components/working-directory.js,sha256=7V1pBeux
 claude_mpm/dashboard/static/js/connection-manager.js,sha256=IJrtihUCQqkECXhiqy53vAJIdxNp7pJVIsV2ocos3As,17981
 claude_mpm/dashboard/static/js/dashboard.js,sha256=bacYhLFaxQIVOeRaUZProQ0Px6CeZFZmgnwZoHjKWls,71535
 claude_mpm/dashboard/static/js/extension-error-handler.js,sha256=DZHrJ3gbfv4nsjmZpNMj-Sc3GKjVJ5ds8lgoaLRnq5I,6274
-claude_mpm/dashboard/static/js/socket-client.js,sha256=i19ZYpUqO38kXubk5NpuVXlSlz8UhorTEYYCJFxbcLM,35984
+claude_mpm/dashboard/static/js/socket-client.js,sha256=eXVTR3EQ6uK9PEjjmwT_8EpPDPPpCRbWiNBK5fS5CJk,37436
 claude_mpm/dashboard/static/js/components/agent-hierarchy.js,sha256=Xihxog_vJrk8VBEkDogV_wbye2GIFWmH71VQ1lETOHk,28243
 claude_mpm/dashboard/static/js/components/agent-inference.js,sha256=RUVZ_fLOyDkHYjrROen_Pzzay79Bh29eXp_GRIPbIRg,37493
 claude_mpm/dashboard/static/js/components/build-tracker.js,sha256=IBfKpoSKWD5QMPN4tOZl-E84Q3QADYVsZ76ickrKW8E,11485
@@ -216,7 +216,7 @@ claude_mpm/hooks/claude_hooks/memory_integration.py,sha256=TXLavDM9eEoakPX_n2Wtn
 claude_mpm/hooks/claude_hooks/response_tracking.py,sha256=4RcM54LyYeINf3A_toaSOPuD3oXS6jZtiRstHxgSOao,14990
 claude_mpm/hooks/claude_hooks/tool_analysis.py,sha256=3_o2PP9D7wEMwLriCtIBOw0cj2fSZfepN7lI4P1meSQ,7862
 claude_mpm/hooks/claude_hooks/services/__init__.py,sha256=OIYOKsUNw1BHYawOCp-KFK5kmQKuj92cCqCEPO0nwo0,585
-claude_mpm/hooks/claude_hooks/services/connection_manager.py,sha256=brkw3wE5m5RWa3fOo4noRO0xl0GpLWUPVacxcP6QYpM,7496
+claude_mpm/hooks/claude_hooks/services/connection_manager.py,sha256=brj_FrSRwusbzyQo8a8DRGruTRqucfNWZNSDiNkbLe8,8290
 claude_mpm/hooks/claude_hooks/services/connection_manager_http.py,sha256=-DZ2seh1tpdo_RQPo5qkkJBcbjEkSpIFWOMMij1V0So,7686
 claude_mpm/hooks/claude_hooks/services/duplicate_detector.py,sha256=Fh9LmEMsVmQM9t0U1v2l_fuBwvNpVkl_0EF8Wu5KLHQ,3882
 claude_mpm/hooks/claude_hooks/services/state_manager.py,sha256=c7OldfemaMU37YGJxgO2uEcTOuPc-C80SRhzEH07j7I,11072
@@ -391,7 +391,7 @@ claude_mpm/services/diagnostics/checks/monitor_check.py,sha256=NUx5G1yjHWlukZmwh
 claude_mpm/services/diagnostics/checks/startup_log_check.py,sha256=DrXdml2rHvmhFBdb_sntE3xmwaP_DZIKjdVbCn8Dy7E,12258
 claude_mpm/services/event_bus/__init__.py,sha256=ETCo4a6puIeyVWAv55uCDjjhzNyUwbVAHEcAVkVapx8,688
 claude_mpm/services/event_bus/config.py,sha256=MJdOBK3XgLpW66N81tetThslnKsFIWYtbqRamyTDxlU,4943
-claude_mpm/services/event_bus/direct_relay.py,sha256=F_N5oqE49u1pVM22Vx2V3rQrGKQmqxEyHt-UF7RJKAk,7253
+claude_mpm/services/event_bus/direct_relay.py,sha256=jijHA13xnKDFVIvefLFlpX2KsnSXwdU1X5QfUXsWwIc,9951
 claude_mpm/services/event_bus/event_bus.py,sha256=KQ8FpbHGsEVlygZj6CTYgugXL7Ht6KGlf1FAT4WJKEI,11920
 claude_mpm/services/event_bus/relay.py,sha256=yQ6Ow2rOj3dtNtYi2Vh4ToTouo-1eOiigtjnBM2w2Wo,9352
 claude_mpm/services/events/__init__.py,sha256=dna3DFYCxt9Y1jgK-0f2KPlX-jFo4n2dJyy9WKZkNlA,1092
@@ -495,7 +495,7 @@ claude_mpm/services/socketio/migration_utils.py,sha256=1pK_zGZ8Pd57pCg1O-3gKT8i7
 claude_mpm/services/socketio/handlers/__init__.py,sha256=zc1eo5hR5xDtnOZCeX38JNo8j9Vs10kV1cxZF20ZS4A,789
 claude_mpm/services/socketio/handlers/base.py,sha256=DjUODCOLTQSsC_-NP9yr-8g77arawmsRrM5KC06aDmw,4845
 claude_mpm/services/socketio/handlers/connection.py,sha256=sa6Rg5Y9tcf-e4PEb6f4fNhFQcpZ9WbwdiGXmkzlFTs,26781
-claude_mpm/services/socketio/handlers/connection_handler.py,sha256=7TMfi41nn_-5UUu_Zfh2u3sskefQ6adljgd_RDhqFLE,13749
+claude_mpm/services/socketio/handlers/connection_handler.py,sha256=DTY0pa--HQu4C6-WCgE1zskvHm3gVuEKWwaSFNBAoec,13287
 claude_mpm/services/socketio/handlers/file.py,sha256=itpPa5OAow5_OXrTOXk0vsyuEYm4iVmxwN9xowy7jiY,8341
 claude_mpm/services/socketio/handlers/git.py,sha256=xIjGGShyVNXzCtJfydbbnFTJhqzXwHLzGhLrqgy0JGQ,37934
 claude_mpm/services/socketio/handlers/hook.py,sha256=JVQufL_u85z3r-n3fnKExuziheJ2lzY6d0GDoUB9iXs,7786
@@ -504,10 +504,10 @@ claude_mpm/services/socketio/handlers/project.py,sha256=yYqWlPfPanA7zH7dgQnP3EpO
 claude_mpm/services/socketio/handlers/registry.py,sha256=f4eELY04c23F0S8A5cxm9PDfSiGFumnfNgg7Ua0TsGU,7946
 claude_mpm/services/socketio/server/__init__.py,sha256=S486w-i-hBo3rNW_AtzxbasEgP32By-uI9zz7hzKz-o,640
 claude_mpm/services/socketio/server/broadcaster.py,sha256=y_D-fDhSD2NZI0cP9wuoB2nlI7VkKjzW_EjVmP-xd5Y,21375
-claude_mpm/services/socketio/server/connection_manager.py,sha256=P22O3FxLdADUxMDCSr0Vzr0CxnExgLYYh_Y13att6T4,17747
-claude_mpm/services/socketio/server/core.py,sha256=nY-EpBB-qsPgiSH-w46C3rtbBCNmXbG72zyYFSX65gI,21301
+claude_mpm/services/socketio/server/connection_manager.py,sha256=sqOoORTFOXoUsW3_nrFfU4q-XYb4kEzP3TF6Dcrrh2o,19583
+claude_mpm/services/socketio/server/core.py,sha256=QZZV9iB-0lWfVZ6u-Zj48MAW2xu9yCv2dMuYp4c2P3I,21921
 claude_mpm/services/socketio/server/eventbus_integration.py,sha256=6LkK8W9wTiNd8d9KoAH2IY1b4osyGGgGaJ0DmwIwnVM,7790
-claude_mpm/services/socketio/server/main.py,sha256=uKsh03fY-5_8wK9JOKm8DJz679Gv0mFkfoFxqrF4mxI,16466
+claude_mpm/services/socketio/server/main.py,sha256=XyG5Bb3mtKpw5BNi8rRKaGB51Qmn_VtVU2km4ILFAVg,17820
 claude_mpm/services/ticket_services/__init__.py,sha256=I01W25n-tBWwZ0TD-dPA63nqzCU2KnpOvbqeysmaa2E,798
 claude_mpm/services/ticket_services/crud_service.py,sha256=4Ab1HONY219QSdRaLTgRInm6DNJXIUKiihyAree8y8A,11193
 claude_mpm/services/ticket_services/formatter_service.py,sha256=MQ981yaFuvXWUDLpHHiasc8BIFdeIeMS7Us0CgZHJ0A,9101
@@ -542,9 +542,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.1.6.dist-info/licenses/LICENSE,sha256=lpaivOlPuBZW1ds05uQLJJswy8Rp_HMNieJEbFlqvLk,1072
-claude_mpm-4.1.6.dist-info/METADATA,sha256=WzfyfF1uc4Ny1XukCgWXC1d884_DJAFtDzw0JHLTNu4,13386
-claude_mpm-4.1.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-claude_mpm-4.1.6.dist-info/entry_points.txt,sha256=FDPZgz8JOvD-6iuXY2l9Zbo9zYVRuE4uz4Qr0vLeGOk,471
-claude_mpm-4.1.6.dist-info/top_level.txt,sha256=1nUg3FEaBySgm8t-s54jK5zoPnu3_eY6EP6IOlekyHA,11
-claude_mpm-4.1.6.dist-info/RECORD,,
+claude_mpm-4.1.7.dist-info/licenses/LICENSE,sha256=lpaivOlPuBZW1ds05uQLJJswy8Rp_HMNieJEbFlqvLk,1072
+claude_mpm-4.1.7.dist-info/METADATA,sha256=NRjI5Nj-63NxX5dxg-9ahfdecMqorEGJgd8D6XODx2I,13386
+claude_mpm-4.1.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+claude_mpm-4.1.7.dist-info/entry_points.txt,sha256=FDPZgz8JOvD-6iuXY2l9Zbo9zYVRuE4uz4Qr0vLeGOk,471
+claude_mpm-4.1.7.dist-info/top_level.txt,sha256=1nUg3FEaBySgm8t-s54jK5zoPnu3_eY6EP6IOlekyHA,11
+claude_mpm-4.1.7.dist-info/RECORD,,