claude-mpm 5.0.2__py3-none-any.whl → 5.1.9__py3-none-any.whl

claude_mpm/services/monitor/daemon.py

@@ -88,11 +88,12 @@ class UnifiedMonitorDaemon:
         self.shutdown_event = threading.Event()
 
     def _get_default_pid_file(self) -> str:
-        """Get default PID file path."""
+        """Get default PID file path with port number to support multiple daemons."""
         project_root = Path.cwd()
         claude_mpm_dir = project_root / ".claude-mpm"
         claude_mpm_dir.mkdir(exist_ok=True)
-        return str(claude_mpm_dir / "monitor-daemon.pid")
+        # Include port in filename to support multiple daemon instances
+        return str(claude_mpm_dir / f"monitor-daemon-{self.port}.pid")
 
     def start(self, force_restart: bool = False) -> bool:
         """Start the unified monitor daemon.
@@ -145,16 +146,26 @@ class UnifiedMonitorDaemon:
         if self.daemon_manager.is_running():
             existing_pid = self.daemon_manager.get_pid()
             if not force_restart:
-                self.logger.warning(f"Daemon already running with PID {existing_pid}")
+                msg = f"Daemon already running on port {self.port} with PID {existing_pid}"
+                self.logger.warning(msg)
+                # If we're in subprocess mode, this is an error - we should have cleaned up
+                if os.environ.get("CLAUDE_MPM_SUBPROCESS_DAEMON") == "1":
+                    self.logger.error(
+                        f"SUBPROCESS ERROR: {msg} - This should not happen in subprocess mode!"
+                    )
                 return False
             # Force restart was already handled above
 
         # Check for our service on the port
         is_ours, pid = self.daemon_manager.is_our_service()
         if is_ours and pid and not force_restart:
-            self.logger.warning(
-                f"Our service already running on port {self.port} (PID: {pid})"
-            )
+            msg = f"Our service already running on port {self.port} (PID: {pid})"
+            self.logger.warning(msg)
+            # If we're in subprocess mode, this is an error - we should have cleaned up
+            if os.environ.get("CLAUDE_MPM_SUBPROCESS_DAEMON") == "1":
+                self.logger.error(
+                    f"SUBPROCESS ERROR: {msg} - This should not happen in subprocess mode!"
+                )
             return False
 
         # Use subprocess approach for clean daemon startup (v4.2.40)
@@ -169,20 +180,29 @@ class UnifiedMonitorDaemon:
         if os.environ.get("CLAUDE_MPM_SUBPROCESS_DAEMON") == "1":
             # We're in a subprocess started by start_daemon_subprocess
             # We need to write the PID file ourselves since parent didn't
-            self.logger.info("Running in subprocess daemon mode, writing PID file")
+            self.logger.info(f"Running in subprocess daemon mode on port {self.port}")
+            self.logger.info(f"Subprocess PID: {os.getpid()}")
+            self.logger.info(f"PID file path: {self.daemon_manager.pid_file}")
             self.daemon_manager.write_pid_file()
+            self.logger.info("PID file written successfully")
 
             # Setup signal handlers for graceful shutdown
             self._setup_signal_handlers()
+            self.logger.info("Signal handlers configured")
 
             # Start the server (this will run until shutdown)
+            self.logger.info("Starting server in subprocess mode...")
             try:
                 result = self._run_server()
                 if not result:
                     self.logger.error("Failed to start server in subprocess mode")
+                    return result
+                self.logger.info("Server started successfully in subprocess mode")
                 return result
             except Exception as e:
-                self.logger.error(f"Server startup exception in subprocess: {e}")
+                self.logger.error(
+                    f"Server startup exception in subprocess: {e}", exc_info=True
+                )
                 raise
         else:
             # Legacy fork approach (kept for compatibility but not used by default)

claude_mpm/services/monitor/daemon_manager.py

@@ -80,18 +80,20 @@ class DaemonManager:
         self.startup_status_file = None
 
     def _get_default_pid_file(self) -> Path:
-        """Get default PID file path."""
+        """Get default PID file path with port number to support multiple daemons."""
         project_root = Path.cwd()
         claude_mpm_dir = project_root / ".claude-mpm"
         claude_mpm_dir.mkdir(exist_ok=True)
-        return claude_mpm_dir / "monitor-daemon.pid"
+        # Include port in filename to support multiple daemon instances
+        return claude_mpm_dir / f"monitor-daemon-{self.port}.pid"
 
     def _get_default_log_file(self) -> Path:
-        """Get default log file path."""
+        """Get default log file path with port number to support multiple daemons."""
         project_root = Path.cwd()
         claude_mpm_dir = project_root / ".claude-mpm"
         claude_mpm_dir.mkdir(exist_ok=True)
-        return claude_mpm_dir / "monitor-daemon.log"
+        # Include port in filename to support multiple daemon instances
+        return claude_mpm_dir / f"monitor-daemon-{self.port}.log"
 
     def cleanup_port_conflicts(self, max_retries: int = 3) -> bool:
         """Clean up any processes using the daemon port.
@@ -471,6 +473,55 @@ class DaemonManager:
 
         return None
 
+    def _verify_daemon_health(self, max_attempts: int = 3) -> bool:
+        """Verify daemon is healthy by checking HTTP health endpoint.
+
+        Args:
+            max_attempts: Maximum number of connection attempts
+
+        Returns:
+            True if health check passes, False otherwise
+        """
+        try:
+            import requests
+
+            for attempt in range(max_attempts):
+                try:
+                    # Try to connect to health endpoint
+                    response = requests.get(
+                        f"http://{self.host}:{self.port}/health", timeout=2
+                    )
+
+                    if response.status_code == 200:
+                        self.logger.debug(
+                            f"Health check passed on attempt {attempt + 1}/{max_attempts}"
+                        )
+                        return True
+
+                    self.logger.debug(
+                        f"Health check returned status {response.status_code} on attempt {attempt + 1}/{max_attempts}"
+                    )
+
+                except requests.exceptions.RequestException as e:
+                    self.logger.debug(
+                        f"Health check attempt {attempt + 1}/{max_attempts} failed: {e}"
+                    )
+
+                # Wait before retry (except on last attempt)
+                if attempt < max_attempts - 1:
+                    time.sleep(1)
+
+            self.logger.debug(f"Health check failed after {max_attempts} attempts")
+            return False
+
+        except ImportError:
+            # requests not available, skip health check
+            self.logger.debug("requests library not available, skipping health check")
+            return True
+        except Exception as e:
+            self.logger.debug(f"Health check error: {e}")
+            return False
+
     def start_daemon(self, force_restart: bool = False) -> bool:
         """Start the daemon with automatic cleanup and retry.
 
@@ -588,36 +639,62 @@ class DaemonManager:
                 pid = process.pid
                 self.logger.info(f"Monitor subprocess started with PID {pid}")
 
-                # Wait for the subprocess to write its PID file
+                # Wait for the subprocess to write its PID file and bind to port
                 # The subprocess will write the PID file after it starts successfully
                 max_wait = 10  # seconds
                 start_time = time.time()
+                pid_file_found = False
+                port_bound = False
+
+                self.logger.debug(f"Waiting up to {max_wait}s for daemon to start...")
 
                 while time.time() - start_time < max_wait:
                     # Check if process is still running
-                    if process.poll() is not None:
-                        # Process exited
+                    returncode = process.poll()
+                    if returncode is not None:
+                        # Process exited - this is the bug we're fixing!
+                        self.logger.error(
+                            f"Monitor daemon subprocess exited prematurely with code {returncode}"
+                        )
                         self.logger.error(
-                            f"Monitor daemon exited with code {process.returncode}"
+                            f"Port {self.port} daemon failed to start. Check {self.log_file} for details."
                         )
                         return False
 
                     # Check if PID file was written
-                    if self.pid_file.exists():
+                    if not pid_file_found and self.pid_file.exists():
                         try:
                             with self.pid_file.open() as f:
                                 written_pid = int(f.read().strip())
                             if written_pid == pid:
-                                # PID file written correctly, check port
-                                if (
-                                    not self._is_port_available()
-                                ):  # Port NOT available means it's in use (good!)
-                                    self.logger.info(
-                                        f"Monitor daemon successfully started on port {self.port}"
-                                    )
-                                    return True
-                        except Exception:
-                            pass  # PID file not ready yet
+                                pid_file_found = True
+                                self.logger.debug(
+                                    f"PID file found with correct PID {pid}"
+                                )
+                        except Exception as e:
+                            self.logger.debug(f"Error reading PID file: {e}")
+
+                    # Check if port is bound (health check)
+                    if not port_bound and not self._is_port_available():
+                        # Port NOT available means it's in use (good!)
+                        port_bound = True
+                        self.logger.debug(f"Port {self.port} is now bound")
+
+                    # Success criteria: both PID file exists and port is bound
+                    if pid_file_found and port_bound:
+                        self.logger.info(
+                            f"Monitor daemon successfully started on port {self.port} (PID: {pid})"
+                        )
+                        # Additional health check: verify we can connect
+                        if self._verify_daemon_health(max_attempts=3):
+                            self.logger.info("Daemon health check passed")
+                            return True
+                        self.logger.warning(
+                            "Daemon started but health check failed - may still be initializing"
+                        )
+                        return (
+                            True  # Return success anyway if PID file and port are good
+                        )
 
                     time.sleep(0.5)
 

claude_mpm/services/project/project_organizer.py

@@ -58,6 +58,10 @@ class ProjectOrganizer:
         ".mcp-vector-search/",
         ".kuzu-memory/",
         "kuzu-memories/",  # kuzu-memory database directory
+        # User-specific config files (should NOT be committed)
+        ".mcp.json",
+        ".claude.json",
+        ".claude/",
         # Python artifacts
         "__pycache__/",
         "*.py[cod]",

claude_mpm/services/runner_configuration_service.py

@@ -10,10 +10,14 @@ This service handles:
 5. Hook service registration
 
 Extracted from ClaudeRunner to follow Single Responsibility Principle.
+
+DEPENDENCY INJECTION:
+This service uses protocol-based dependency injection to avoid circular imports
+when registering the SessionManagementService.
 """
 
 import os
-from typing import Any, Dict, List, Optional, Tuple
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
 
 from claude_mpm.core.base_service import BaseService
 from claude_mpm.core.config import Config
@@ -22,6 +26,13 @@ from claude_mpm.core.logger import get_project_logger
 from claude_mpm.core.shared.config_loader import ConfigLoader
 from claude_mpm.services.core.interfaces import RunnerConfigurationInterface
 
+# Protocol imports for type checking without circular dependencies
+if TYPE_CHECKING:
+    from claude_mpm.core.protocols import ClaudeRunnerProtocol
+else:
+    # At runtime, accept any object with matching interface
+    ClaudeRunnerProtocol = Any
+
 
 class RunnerConfigurationService(BaseService, RunnerConfigurationInterface):
     """Service for configuring and initializing ClaudeRunner components."""
@@ -495,12 +506,14 @@ class RunnerConfigurationService(BaseService, RunnerConfigurationInterface):
             )
             return None
 
-    def register_session_management_service(self, container, runner):
+    def register_session_management_service(
+        self, container, runner: "ClaudeRunnerProtocol"
+    ):
         """Register session management service in the DI container.
 
         Args:
             container: DI container instance
-            runner: ClaudeRunner instance dependency
+            runner: ClaudeRunner instance (or any object matching ClaudeRunnerProtocol)
 
         Returns:
             Initialized session management service or None if failed

claude_mpm/services/session_management_service.py

@@ -9,29 +9,41 @@ This service handles:
 4. Session logging and cleanup
 
 Extracted from ClaudeRunner to follow Single Responsibility Principle.
+
+DEPENDENCY INJECTION:
+This service uses protocol-based dependency injection to avoid circular imports.
+It accepts a ClaudeRunnerProtocol instead of importing ClaudeRunner directly.
 """
 
 import time
 import uuid
 from datetime import timezone
-from typing import Any, Dict, List, Optional
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
 
 from claude_mpm.core.base_service import BaseService
 from claude_mpm.core.enums import OperationResult, ServiceState
 from claude_mpm.services.core.interfaces import SessionManagementInterface
 
+# Protocol imports for type checking without circular dependencies
+if TYPE_CHECKING:
+    from claude_mpm.core.protocols import ClaudeRunnerProtocol
+else:
+    # At runtime, accept any object with matching interface
+    ClaudeRunnerProtocol = Any
+
 
 class SessionManagementService(BaseService, SessionManagementInterface):
     """Service for managing Claude session orchestration."""
 
-    def __init__(self, runner=None):
+    def __init__(self, runner: Optional["ClaudeRunnerProtocol"] = None):
         """Initialize the session management service.
 
         Args:
-            runner: ClaudeRunner instance for delegation
+            runner: ClaudeRunner instance (or any object matching ClaudeRunnerProtocol)
+                    for delegation
         """
         super().__init__(name="session_management_service")
-        self.runner = runner
+        self.runner: Optional[ClaudeRunnerProtocol] = runner
         self.active_sessions = {}  # Track active sessions
 
     async def _initialize(self) -> None:

claude_mpm/utils/agent_filters.py

@@ -0,0 +1,288 @@
+"""
+Agent filtering utilities for claude-mpm.
+
+WHY: This module provides centralized filtering logic to remove non-deployable
+agents (BASE_AGENT) and already-deployed agents from user-facing displays.
+
+DESIGN DECISIONS:
+- BASE_AGENT is a build tool, not a deployable agent - filter everywhere
+- Deployed agent detection supports both new (.claude-mpm/agents/) and
+  legacy (.claude/agents/)
+- Case-insensitive BASE_AGENT detection for robustness
+- Pure functions for easy testing and reuse
+
+IMPLEMENTATION NOTES:
+- Related to ticket 1M-502 Phase 1: UX improvements for agent filtering
+- Addresses user confusion from seeing BASE_AGENT and deployed agents in lists
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+
+
+def is_base_agent(agent_id: str) -> bool:
+    """Check if agent is BASE_AGENT (build tool, not deployable).
+
+    BASE_AGENT is an internal build tool used to construct other agents.
+    It should never appear in user-facing agent lists or deployment menus.
+
+    Args:
+        agent_id: Agent identifier to check (may include path like "qa/BASE-AGENT")
+
+    Returns:
+        True if agent is BASE_AGENT (case-insensitive), False otherwise
+
+    Examples:
+        >>> is_base_agent("BASE_AGENT")
+        True
+        >>> is_base_agent("base-agent")
+        True
+        >>> is_base_agent("qa/BASE-AGENT")
+        True
+        >>> is_base_agent("ENGINEER")
+        False
+    """
+    if not agent_id:
+        return False
+
+    # Extract filename from path (handle cases like "qa/BASE-AGENT")
+    # 1M-502: Remote agents may have path prefixes like "qa/", "pm/", etc.
+    agent_name = agent_id.split("/")[-1]
+
+    normalized_id = agent_name.lower().replace("-", "").replace("_", "")
+    return normalized_id == "baseagent"
+
+
+def filter_base_agents(agents: List[Dict]) -> List[Dict]:
+    """Remove BASE_AGENT from agent list.
+
+    Filters out any agent with agent_id matching BASE_AGENT (case-insensitive).
+    This prevents users from seeing or selecting the internal build tool.
+
+    Args:
+        agents: List of agent dictionaries, each containing at least 'agent_id' key
+
+    Returns:
+        Filtered list with BASE_AGENT removed
+
+    Examples:
+        >>> agents = [
+        ...     {"agent_id": "ENGINEER", "name": "Engineer"},
+        ...     {"agent_id": "BASE_AGENT", "name": "Base Agent"},
+        ...     {"agent_id": "PM", "name": "PM"}
+        ... ]
+        >>> filtered = filter_base_agents(agents)
+        >>> len(filtered)
+        2
+        >>> "BASE_AGENT" in [a["agent_id"] for a in filtered]
+        False
+    """
+    return [a for a in agents if not is_base_agent(a.get("agent_id", ""))]
+
+
+def get_deployed_agent_ids(project_dir: Optional[Path] = None) -> Set[str]:
+    """Get set of currently deployed agent IDs.
+
+    Checks virtual deployment state (.mpm_deployment_state) first, then falls back
+    to physical .md files for backward compatibility. This ensures agents are detected
+    whether deployed virtually or as physical files.
+
+    Args:
+        project_dir: Project directory to check, defaults to current working directory
+
+    Returns:
+        Set of deployed agent IDs (leaf names like "python-engineer", "qa")
+
+    Examples:
+        >>> deployed = get_deployed_agent_ids()
+        >>> "python-engineer" in deployed  # If agent exists in deployment state
+        True
+        >>> "ENGINEER" in deployed  # If ENGINEER.md exists
+        True
+
+    Design Rationale:
+        - Primary detection: Virtual deployment state (.mpm_deployment_state)
+        - Fallback detection: Physical .md files (.claude-mpm/agents/, .claude/agents/)
+        - Returns leaf names for consistent comparison with agent_id formats
+        - Combines both detection methods for complete coverage
+        - Graceful error handling for malformed or missing state files
+
+    Related:
+        - Fixes checkbox interface showing all agents as "○ [Available]" instead of "● [Installed]"
+        - Matches detection logic from _is_agent_deployed() in agent_state_manager.py
+        - Related to ticket 1M-502: Virtual deployment state detection
+    """
+    deployed = set()
+
+    # Track if project_dir was explicitly provided
+    explicit_project_dir = project_dir is not None
+
+    if project_dir is None:
+        project_dir = Path.cwd()
+
+    # NEW: Check virtual deployment state (primary method)
+    # This is the current deployment model used by Claude Code
+    deployment_state_paths = [
+        project_dir / ".claude" / "agents" / ".mpm_deployment_state",
+    ]
+
+    # Only check user-level state if using default project directory
+    # This prevents test isolation issues when explicit project_dir is provided
+    if not explicit_project_dir:
+        deployment_state_paths.append(
+            Path.home() / ".claude" / "agents" / ".mpm_deployment_state"
+        )
+
+    for state_path in deployment_state_paths:
+        if state_path.exists():
+            try:
+                import json
+
+                with state_path.open() as f:
+                    state = json.load(f)
+
+                # Extract agent IDs from deployment state
+                # Agent IDs are leaf names (e.g., "python-engineer", "qa")
+                agents = state.get("last_check_results", {}).get("agents", {})
+                deployed.update(agents.keys())
+
+            except (json.JSONDecodeError, KeyError) as e:
+                # Log error but continue - don't break if state file is malformed
+                import logging
+
+                logger = logging.getLogger(__name__)
+                logger.debug(f"Failed to read deployment state from {state_path}: {e}")
+                continue
+            except Exception as e:
+                # Catch unexpected errors - fail gracefully
+                import logging
+
+                logger = logging.getLogger(__name__)
+                logger.debug(f"Unexpected error reading deployment state: {e}")
+                continue
+
+    # EXISTING: Check physical .md files (fallback for backward compatibility)
+    # Check new architecture
+    new_agents_dir = project_dir / ".claude-mpm" / "agents"
+    if new_agents_dir.exists():
+        for file in new_agents_dir.glob("*.md"):
+            if file.stem not in {"BASE-AGENT", ".DS_Store"}:
+                deployed.add(file.stem)
+
+    # Check legacy architecture
+    legacy_agents_dir = project_dir / ".claude" / "agents"
+    if legacy_agents_dir.exists():
+        for file in legacy_agents_dir.glob("*.md"):
+            if file.stem not in {"BASE-AGENT", ".DS_Store"}:
+                deployed.add(file.stem)
+
+    # Check .claude/templates/ directory (where agents are actually deployed)
+    templates_dir = project_dir / ".claude" / "templates"
+    if templates_dir.exists():
+        for file in templates_dir.glob("*.md"):
+            if file.stem not in {
+                "BASE-AGENT",
+                ".DS_Store",
+                "README",
+                "circuit-breakers",
+            }:
+                # Skip template/example files
+                if not any(x in file.stem for x in ["example", "template", "pm-"]):
+                    deployed.add(file.stem)
+
+    # Check user-level directory only if using default project directory
+    # This prevents test isolation issues when explicit project_dir is provided
+    if not explicit_project_dir:
+        user_agents_dir = Path.home() / ".claude" / "agents"
+        if user_agents_dir.exists():
+            for file in user_agents_dir.glob("*.md"):
+                if file.stem not in {"BASE-AGENT", ".DS_Store"}:
+                    deployed.add(file.stem)
+
+    return deployed
+
+
+def filter_deployed_agents(
+    agents: List[Dict], project_dir: Optional[Path] = None
+) -> List[Dict]:
+    """Remove already-deployed agents from list.
+
+    Filters agent list to show only agents that are not currently deployed.
+    This prevents users from attempting to re-deploy existing agents and
+    reduces confusion in deployment menus.
+
+    Args:
+        agents: List of agent dictionaries, each containing at least 'agent_id' key
+        project_dir: Project directory to check, defaults to current working directory
+
+    Returns:
+        Filtered list containing only non-deployed agents
+
+    Examples:
+        >>> agents = [
+        ...     {"agent_id": "ENGINEER", "name": "Engineer"},
+        ...     {"agent_id": "PM", "name": "PM"},
+        ...     {"agent_id": "QA", "name": "QA"}
+        ... ]
+        >>> # Assuming ENGINEER is deployed
+        >>> filtered = filter_deployed_agents(agents)
+        >>> "ENGINEER" not in [a["agent_id"] for a in filtered]
+        True
+
+    Design Rationale:
+        - Checks filesystem for actual deployed files (source of truth)
+        - Supports both new and legacy agent directory structures
+        - Preserves agent order for consistent UX
+    """
+    deployed_ids = get_deployed_agent_ids(project_dir)
+    return [a for a in agents if a.get("agent_id") not in deployed_ids]
+
+
+def apply_all_filters(
+    agents: List[Dict],
+    project_dir: Optional[Path] = None,
+    filter_base: bool = True,
+    filter_deployed: bool = False,
+) -> List[Dict]:
+    """Apply multiple filters to agent list in correct order.
+
+    Convenience function to apply common filtering combinations. Filters are
+    applied in this order:
+    1. BASE_AGENT filtering (if enabled)
+    2. Deployed agent filtering (if enabled)
+
+    Args:
+        agents: List of agent dictionaries to filter
+        project_dir: Project directory for deployment checks
+        filter_base: Remove BASE_AGENT from list (default: True)
+        filter_deployed: Remove deployed agents from list (default: False)
+
+    Returns:
+        Filtered agent list
+
+    Examples:
+        >>> agents = get_all_agents()
+        >>> # For display/info purposes - remove only BASE_AGENT
+        >>> filtered = apply_all_filters(
+        ...     agents, filter_base=True, filter_deployed=False
+        ... )
+        >>> # For deployment menus - remove BASE_AGENT and deployed agents
+        >>> deployable = apply_all_filters(
+        ...     agents, filter_base=True, filter_deployed=True
+        ... )
+
+    Usage Guidelines:
+        - Use filter_base=True (default) for all user-facing displays
+        - Use filter_deployed=True when showing deployment options
+        - Use filter_deployed=False when showing all available agents
+          (info/list commands)
+    """
+    result = agents
+
+    if filter_base:
+        result = filter_base_agents(result)
+
+    if filter_deployed:
+        result = filter_deployed_agents(result, project_dir)
+
+    return result

claude_mpm/utils/gitignore.py

@@ -212,6 +212,9 @@ def ensure_claude_mpm_gitignore(project_dir: str = ".") -> dict:
         entries_to_add = [
             ".claude-mpm/",
             ".claude/agents/",
+            ".mcp.json",
+            ".claude.json",
+            ".claude/",
         ]
 
         added, existing = manager.ensure_entries(entries_to_add)