claude-mpm 4.5.5__tar.gz → 4.5.8__tar.gz

claude_mpm-4.5.8/BUILD_NUMBER

@@ -0,0 +1 @@
+415

{claude_mpm-4.5.5 → claude_mpm-4.5.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 4.5.5
+Version: 4.5.8
 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.5.8/VERSION

@@ -0,0 +1 @@
+4.5.8

{claude_mpm-4.5.5 → claude_mpm-4.5.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "claude-mpm"
-version = "4.5.5"
+version = "4.5.8"
 description = "Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -81,7 +81,7 @@ ignore-imports = false
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "4.5.5"
+version = "4.5.8"
 version_files = [ "VERSION", "src/claude_mpm/VERSION", "package.json:version",]
 tag_format = "v$version"
 update_changelog_on_bump = true

claude_mpm-4.5.8/src/claude_mpm/VERSION

@@ -0,0 +1 @@
+4.5.8

{claude_mpm-4.5.5 → claude_mpm-4.5.8}/src/claude_mpm/agents/BASE_OPS.md

@@ -4,6 +4,16 @@ All Ops agents inherit these common operational patterns and requirements.
 
 ## Core Ops Principles
 
+### Local Development Server Management
+**CRITICAL IMPERATIVES FOR LOCAL-OPS AGENTS:**
+- **MAINTAIN SINGLE STABLE INSTANCES**: Always strive to keep a single instance of each development server running stably. Avoid creating multiple instances of the same service.
+- **NEVER INTERRUPT OTHER PROJECTS**: Before stopping ANY service, verify it's not being used by another project or Claude Code session. Check process ownership and working directories.
+- **PROTECT CLAUDE CODE SERVICES**: Never terminate or interfere with Claude MPM services, monitor servers, or any processes that might be used by Claude Code.
+- **PORT MANAGEMENT**: Always check if a port is in use before attempting to use it. If occupied, find an alternative rather than killing the existing process.
+- **GRACEFUL OPERATIONS**: Use graceful shutdown procedures. Always attempt soft stops before forceful termination.
+- **SESSION AWARENESS**: Be aware that multiple Claude Code sessions might be active. Coordinate rather than conflict.
+- **HEALTH BEFORE ACTION**: Always verify service health before making changes. A running service should be left running unless explicitly requested to stop it.
+
 ### Infrastructure as Code
 - All infrastructure must be version controlled
 - Use declarative configuration over imperative scripts

{claude_mpm-4.5.5 → claude_mpm-4.5.8}/src/claude_mpm/agents/PM_INSTRUCTIONS.md

@@ -164,9 +164,31 @@ Read: /mpm-doctor   # WRONG - not a file to read
 **User mentions error → PM delegates to Ops for logs (NEVER debugs)**
 **User wants analysis → PM delegates to Code Analyzer (NEVER analyzes)**
 
+### 🔥 LOCAL-OPS-AGENT PRIORITY RULE 🔥
+
+**MANDATORY**: For ANY localhost/local development work, ALWAYS use **local-ops-agent** as the PRIMARY choice:
+- **Local servers**: localhost:3000, dev servers → **local-ops-agent** (NOT generic Ops)
+- **PM2 operations**: pm2 start/stop/status → **local-ops-agent** (EXPERT in PM2)
+- **Port management**: Port conflicts, EADDRINUSE → **local-ops-agent** (HANDLES gracefully)
+- **npm/yarn/pnpm**: npm start, yarn dev → **local-ops-agent** (PREFERRED)
+- **Process management**: ps, kill, restart → **local-ops-agent** (SAFE operations)
+- **Docker local**: docker-compose up → **local-ops-agent** (MANAGES containers)
+
+**WHY local-ops-agent?**
+- Maintains single stable instances (no duplicates)
+- Never interrupts other projects or Claude Code
+- Smart port allocation (finds alternatives, doesn't kill)
+- Graceful operations (soft stops, proper cleanup)
+- Session-aware (coordinates with multiple Claude sessions)
+
 ### Quick Delegation Matrix
 | User Says | PM's IMMEDIATE Response | You MUST Delegate To |
 |-----------|------------------------|---------------------|
+| "localhost", "local server", "dev server" | "I'll delegate to local-ops agent" | **local-ops-agent** (PRIMARY) |
+| "PM2", "process manager", "pm2 start" | "I'll have local-ops manage PM2" | **local-ops-agent** (ALWAYS) |
+| "port 3000", "port conflict", "EADDRINUSE" | "I'll have local-ops handle ports" | **local-ops-agent** (EXPERT) |
+| "npm start", "npm run dev", "yarn dev" | "I'll have local-ops run the dev server" | **local-ops-agent** (PREFERRED) |
+| "start my app", "run locally" | "I'll delegate to local-ops agent" | **local-ops-agent** (DEFAULT) |
 | "fix", "implement", "code", "create" | "I'll delegate this to Engineer" | Engineer |
 | "test", "verify", "check" | "I'll have QA verify this" | QA (or web-qa/api-qa) |
 | "deploy", "host", "launch" | "I'll delegate to Ops" | Ops (or platform-specific) |
@@ -245,7 +267,8 @@ START → [DELEGATE Research] → [DELEGATE Code Analyzer] → [DELEGATE Impleme
 
 | Deployment Type | Ops Agent | Required Verifications |
 |----------------|-----------|------------------------|
-| Local Dev (PM2, Docker) | Ops | Read logs, check process status, fetch endpoint, Playwright if UI |
+| Local Dev (PM2, Docker) | **local-ops-agent** (PRIMARY) | Read logs, check process status, fetch endpoint, Playwright if UI |
+| Local npm/yarn/pnpm | **local-ops-agent** (ALWAYS) | Process monitoring, port management, graceful operations |
 | Vercel | vercel-ops-agent | Read build logs, fetch deployment URL, check function logs, Playwright for pages |
 | Railway | railway-ops-agent | Read deployment logs, check health endpoint, verify database connections |
 | GCP/Cloud Run | gcp-ops-agent | Check Cloud Run logs, verify service status, test endpoints |
@@ -274,9 +297,10 @@ Requirements:
 ## LOCAL DEPLOYMENT MANDATORY VERIFICATION
 
 **CRITICAL**: PM MUST NEVER claim "running on localhost" without verification.
+**PRIMARY AGENT**: Always use **local-ops-agent** for ALL localhost work.
 
 ### Required for ALL Local Deployments (PM2, Docker, npm start, etc.):
-1. PM MUST delegate to local-ops-agent (or Ops) for deployment
+1. PM MUST delegate to **local-ops-agent** (NEVER generic Ops) for deployment
 2. Ops agent MUST verify with ALL of these:
    - Process status check (ps, pm2 status, docker ps)
    - Log examination for startup errors
@@ -309,7 +333,7 @@ These phrases without fetch evidence = IMMEDIATE VIOLATION:
 |------|-------------|----------|----------------|
 | API | HTTP calls | curl/fetch output | web-qa (MANDATORY) |
 | Web UI | Browser automation | Playwright results | web-qa with Playwright |
-| Local Deploy | PM2/Docker status + fetch/Playwright | Logs + endpoint tests | Ops (MUST verify) |
+| Local Deploy | PM2/Docker status + fetch/Playwright | Logs + endpoint tests | **local-ops-agent** (MUST verify) |
 | Vercel Deploy | Build success + fetch/Playwright | Deployment URL active | vercel-ops-agent (MUST verify) |
 | Railway Deploy | Service healthy + fetch tests | Logs + endpoint response | railway-ops-agent (MUST verify) |
 | GCP Deploy | Cloud Run active + endpoint tests | Service logs + HTTP 200 | gcp-ops-agent (MUST verify) |
@@ -597,7 +621,7 @@ Documentation → Report
 - Web UI: Research → Analyzer → web-ui/react-engineer → Ops (deploy) → Ops (VERIFY with Playwright) → web-qa → Docs
 - Vercel Site: Research → Analyzer → Engineer → vercel-ops (deploy) → vercel-ops (VERIFY) → web-qa → Docs
 - Railway App: Research → Analyzer → Engineer → railway-ops (deploy) → railway-ops (VERIFY) → api-qa → Docs
-- Local Dev: Research → Analyzer → Engineer → Ops (PM2/Docker) → Ops (VERIFY logs+fetch) → QA → Docs
+- Local Dev: Research → Analyzer → Engineer → **local-ops-agent** (PM2/Docker) → **local-ops-agent** (VERIFY logs+fetch) → QA → Docs
 - Bug Fix: Research → Analyzer → Engineer → Deploy → Ops (VERIFY) → web-qa (regression) → version-control
 
 ### Success Criteria

{claude_mpm-4.5.5 → claude_mpm-4.5.8}/src/claude_mpm/agents/templates/local_ops_agent.json

@@ -1,8 +1,8 @@
 {
   "name": "local-ops",
   "display_name": "Local Operations Agent",
-  "description": "Specialized agent for managing local development deployments with authority over PM2, Docker, and native processes",
-  "version": "1.0.0",
+  "description": "Specialized agent for managing local development deployments with focus on maintaining single stable instances, protecting existing services, and never interfering with other projects or Claude Code services",
+  "version": "1.0.1",
   "author": "Claude MPM",
   "authority": {
     "level": "deployment_manager",
@@ -65,7 +65,16 @@
     "state_file": ".claude-mpm/deployment-state.json",
     "health_check_interval": 30,
     "auto_restart_attempts": 3,
-    "cleanup_on_exit": false
+    "cleanup_on_exit": false,
+    "stability_policy": {
+      "single_instance_enforcement": true,
+      "reuse_existing_processes": true,
+      "protect_external_services": true,
+      "avoid_port_conflicts": true,
+      "graceful_shutdown_timeout": 10000,
+      "check_process_ownership": true,
+      "preserve_claude_mpm_services": true
+    }
   },
   "commands": {
     "deploy": {
@@ -78,9 +87,11 @@
       "workflow": [
         "detect_framework",
         "check_existing_deployments",
-        "allocate_port",
+        "verify_no_conflicts",
+        "check_process_ownership",
+        "reuse_or_allocate_port",
         "build_if_needed",
-        "start_process",
+        "start_or_attach_to_process",
         "monitor_health",
         "report_status"
       ]
@@ -213,7 +224,23 @@
   "error_recovery": {
     "port_conflict": {
       "detection": "EADDRINUSE",
-      "action": "allocate_next_available_port"
+      "action": "check_process_owner_then_allocate_alternative_port",
+      "never": "kill_existing_process_without_verification"
+    },
+    "existing_service": {
+      "detection": "service_already_running",
+      "action": "attach_to_existing_or_report_status",
+      "never": "create_duplicate_instance"
+    },
+    "external_ownership": {
+      "detection": "process_owned_by_other_project",
+      "action": "allocate_different_resources",
+      "never": "interfere_with_external_process"
+    },
+    "claude_mpm_service": {
+      "detection": "claude-mpm|mcp|monitor",
+      "action": "report_status_only",
+      "never": "stop_or_restart_system_services"
     },
     "build_failure": {
       "detection": "npm ERR!|ERROR|Failed",
@@ -235,11 +262,20 @@
     "secrets_handling": "environment_variables"
   },
   "integration": {
+    "operational_principles": {
+      "single_instance_policy": "Always maintain single stable instances of services",
+      "non_interference": "Never interrupt services owned by other projects or Claude Code",
+      "service_protection": "Protect all Claude MPM, MCP, and monitor services",
+      "graceful_operations": "Always prefer graceful operations over forceful actions",
+      "conflict_avoidance": "Find alternative resources rather than stopping existing services"
+    },
     "hooks": {
-      "pre_deploy": "validate_requirements",
+      "pre_deploy": "check_conflicts_and_validate_requirements",
       "post_deploy": "notify_status",
-      "pre_stop": "graceful_shutdown",
-      "on_crash": "auto_restart_with_backoff"
+      "pre_stop": "verify_ownership_then_graceful_shutdown",
+      "on_crash": "auto_restart_with_backoff",
+      "before_port_use": "check_existing_process_owner",
+      "on_conflict": "find_alternative_resources"
     },
     "monitoring": {
       "export_metrics": true,

{claude_mpm-4.5.5 → claude_mpm-4.5.8}/src/claude_mpm/services/async_session_logger.py

@@ -31,6 +31,9 @@ from typing import Any, Dict, Optional
 from claude_mpm.core.constants import PerformanceConfig, SystemLimits, TimeoutConfig
 from claude_mpm.core.logging_utils import get_logger
 
+# Import centralized session manager
+from claude_mpm.services.session_manager import get_session_manager
+
 # Import configuration manager
 from ..core.config import Config
 
@@ -68,8 +71,13 @@ class AsyncSessionLogger:
     - Configurable log formats (JSON, syslog, journald)
     - Fire-and-forget pattern for zero latency impact
     - Graceful degradation on errors
+    - Thread-safe singleton pattern with initialization flag
     """
 
+    _initialization_lock = Lock()
+    _initialized = False
+    _worker_started = False
+
     def __init__(
         self,
         base_dir: Optional[Path] = None,
@@ -90,104 +98,108 @@ class AsyncSessionLogger:
             enable_compression: Enable gzip compression for JSON logs (overrides config)
             config: Configuration instance to use (creates new if not provided)
         """
-        # Load configuration from YAML file or use provided config
-        if config is None:
-            config = Config()
-        self.config = config
-
-        # Get response logging configuration section
-        response_config = self.config.get("response_logging", {})
-
-        # Apply configuration with parameter overrides
-        self.base_dir = Path(
-            base_dir
-            or response_config.get("session_directory", ".claude-mpm/responses")
-        )
-
-        # Convert log format string to enum
-        format_str = response_config.get("format", "json").lower()
-        if log_format is not None:
-            self.log_format = log_format
-        elif format_str == "syslog":
-            self.log_format = LogFormat.SYSLOG
-        elif format_str == "journald":
-            self.log_format = LogFormat.JOURNALD
-        else:
-            self.log_format = LogFormat.JSON
+        # Use initialization flag to prevent duplicate setup
+        with self._initialization_lock:
+            if self._initialized and hasattr(self, "config"):
+                logger.debug("AsyncSessionLogger already initialized, skipping setup")
+                return
 
-        self.max_queue_size = (
-            max_queue_size
-            if max_queue_size is not None
-            else response_config.get("max_queue_size", SystemLimits.MAX_QUEUE_SIZE)
-        )
+            # Load configuration from YAML file or use provided config
+            if config is None:
+                config = Config()
+            self.config = config
 
-        # Handle async configuration with backward compatibility
-        if enable_async is not None:
-            self.enable_async = enable_async
-        else:
-            # Check configuration first, then environment variables for backward compatibility
-            self.enable_async = response_config.get("use_async", True)
-            # Override with environment variable if set (backward compatibility)
-            if os.environ.get("CLAUDE_USE_ASYNC_LOG"):
-                self.enable_async = (
-                    os.environ.get("CLAUDE_USE_ASYNC_LOG", "true").lower() == "true"
-                )
+            # Get response logging configuration section
+            response_config = self.config.get("response_logging", {})
 
-        # Check debug sync mode (forces synchronous for debugging)
-        if (
-            response_config.get("debug_sync", False)
-            or os.environ.get("CLAUDE_LOG_SYNC", "").lower() == "true"
-        ):
-            logger.info("Debug sync mode enabled - forcing synchronous logging")
-            self.enable_async = False
-
-        self.enable_compression = (
-            enable_compression
-            if enable_compression is not None
-            else response_config.get("enable_compression", False)
-        )
+            # Apply configuration with parameter overrides
+            self.base_dir = Path(
+                base_dir
+                or response_config.get("session_directory", ".claude-mpm/responses")
+            )
 
-        # Create base directory
-        self.base_dir.mkdir(parents=True, exist_ok=True)
+            # Convert log format string to enum
+            format_str = response_config.get("format", "json").lower()
+            if log_format is not None:
+                self.log_format = log_format
+            elif format_str == "syslog":
+                self.log_format = LogFormat.SYSLOG
+            elif format_str == "journald":
+                self.log_format = LogFormat.JOURNALD
+            else:
+                self.log_format = LogFormat.JSON
 
-        # Session management
-        self.session_id = self._get_claude_session_id()
+            self.max_queue_size = (
+                max_queue_size
+                if max_queue_size is not None
+                else response_config.get("max_queue_size", SystemLimits.MAX_QUEUE_SIZE)
+            )
 
-        # Async infrastructure
-        self._queue: Queue = Queue(maxsize=self.max_queue_size)
-        self._worker_thread: Optional[Thread] = None
-        self._shutdown = False
-        self._lock = Lock()
+            # Handle async configuration with backward compatibility
+            if enable_async is not None:
+                self.enable_async = enable_async
+            else:
+                # Check configuration first, then environment variables for backward compatibility
+                self.enable_async = response_config.get("use_async", True)
+                # Override with environment variable if set (backward compatibility)
+                if os.environ.get("CLAUDE_USE_ASYNC_LOG"):
+                    self.enable_async = (
+                        os.environ.get("CLAUDE_USE_ASYNC_LOG", "true").lower() == "true"
+                    )
 
-        # Statistics
-        self.stats = {
-            "logged": 0,
-            "queued": 0,
-            "dropped": 0,
-            "errors": 0,
-            "avg_write_time_ms": 0.0,
-        }
+            # Check debug sync mode (forces synchronous for debugging)
+            if (
+                response_config.get("debug_sync", False)
+                or os.environ.get("CLAUDE_LOG_SYNC", "").lower() == "true"
+            ):
+                logger.info("Debug sync mode enabled - forcing synchronous logging")
+                self.enable_async = False
+
+            self.enable_compression = (
+                enable_compression
+                if enable_compression is not None
+                else response_config.get("enable_compression", False)
+            )
 
-        # Initialize format-specific handlers
-        self._init_format_handler()
+            # Create base directory
+            self.base_dir.mkdir(parents=True, exist_ok=True)
+
+            # Use centralized SessionManager for session ID
+            session_manager = get_session_manager()
+            self.session_id = session_manager.get_session_id()
+
+            # Async infrastructure
+            self._queue: Queue = Queue(maxsize=self.max_queue_size)
+            self._worker_thread: Optional[Thread] = None
+            self._shutdown = False
+            self._lock = Lock()
+
+            # Statistics
+            self.stats = {
+                "logged": 0,
+                "queued": 0,
+                "dropped": 0,
+                "errors": 0,
+                "avg_write_time_ms": 0.0,
+            }
+
+            # Initialize format-specific handlers
+            self._init_format_handler()
+
+            # Mark as initialized
+            self._initialized = True
+
+            # Log initialization status
+            logger.info(
+                f"AsyncSessionLogger initialized with SessionManager: session_id={self.session_id}, async={self.enable_async}, format={self.log_format.value}"
+            )
 
-        # Start background worker if async enabled
-        if self.enable_async:
-            self._start_worker()
-
-    def _get_claude_session_id(self) -> str:
-        """Get or generate a Claude session ID."""
-        # Check environment variables in order of preference
-        for env_var in ["CLAUDE_SESSION_ID", "ANTHROPIC_SESSION_ID", "SESSION_ID"]:
-            session_id = os.environ.get(env_var)
-            if session_id:
-                logger.info(f"Using session ID from {env_var}: {session_id}")
-                return session_id
-
-        # Generate timestamp-based session ID
-        session_id = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
-        logger.info(f"Generated session ID: {session_id}")
-        return session_id
+        # Start background worker if async enabled (outside initialization lock)
+        if self.enable_async and not self._worker_started:
+            with self._initialization_lock:
+                if not self._worker_started:
+                    self._start_worker()
+                    self._worker_started = True
 
     def _init_format_handler(self):
         """Initialize format-specific logging handlers."""
@@ -471,8 +483,19 @@ class AsyncSessionLogger:
         Args:
             timeout: Maximum time to wait for shutdown
         """
+        # Only log shutdown if we're actually shutting down an active logger
+        if self._shutdown:
+            logger.debug("AsyncSessionLogger already shut down")
+            return
+
         if self.enable_async:
-            logger.info("Shutting down async logger")
+            # Only log at INFO level if we actually processed something
+            if self.stats.get("logged", 0) > 0 or self.stats.get("queued", 0) > 0:
+                logger.info(
+                    f"Shutting down async logger (logged: {self.stats.get('logged', 0)}, queued: {self.stats.get('queued', 0)})"
+                )
+            else:
+                logger.debug("Shutting down async logger (no activity)")
 
             # Signal shutdown
             self._shutdown = True
@@ -486,10 +509,16 @@ class AsyncSessionLogger:
 
             # Log final statistics only if we actually logged something
             if self.stats.get("logged", 0) > 0:
-                logger.info(f"Logger stats: {self.stats}")
+                logger.info(f"AsyncSessionLogger final stats: {self.stats}")
+            elif self.stats.get("queued", 0) > 0 or self.stats.get("dropped", 0) > 0:
+                logger.debug(
+                    f"AsyncSessionLogger stats (incomplete session): {self.stats}"
+                )
             else:
                 # Use debug level when nothing was logged
-                logger.debug(f"Logger stats (no sessions logged): {self.stats}")
+                logger.debug(
+                    f"AsyncSessionLogger stats (no sessions logged): {self.stats}"
+                )
 
     def get_stats(self) -> Dict[str, Any]:
         """Get logger statistics."""
@@ -497,8 +526,17 @@ class AsyncSessionLogger:
             return self.stats.copy()
 
     def set_session_id(self, session_id: str):
-        """Set a new session ID."""
+        """Set a new session ID.
+
+        Note: This updates both the local session ID and the SessionManager.
+
+        Args:
+            session_id: The new session ID to use
+        """
         self.session_id = session_id
+        # Also update SessionManager to keep consistency
+        session_manager = get_session_manager()
+        session_manager.set_session_id(session_id)
         logger.info(f"Session ID updated to: {session_id}")
 
     def is_enabled(self) -> bool: