claude-mpm 5.6.23__py3-none-any.whl → 5.6.73__py3-none-any.whl

claude_mpm/commander/instance_manager.py

@@ -1,19 +1,32 @@
 """Manages running Claude Code/MPM instances."""
 
+import asyncio
 import logging
+import re
+from datetime import datetime, timezone
 from pathlib import Path
-from typing import Optional
+from typing import TYPE_CHECKING, Optional
 
 from claude_mpm.commander.adapters import (
     AdapterResponse,
     ClaudeCodeAdapter,
     ClaudeCodeCommunicationAdapter,
 )
-from claude_mpm.commander.frameworks.base import BaseFramework, InstanceInfo
+from claude_mpm.commander.frameworks.base import (
+    BaseFramework,
+    InstanceInfo,
+    RegisteredInstance,
+)
 from claude_mpm.commander.frameworks.claude_code import ClaudeCodeFramework
 from claude_mpm.commander.frameworks.mpm import MPMFramework
+from claude_mpm.commander.git.worktree_manager import WorktreeManager
+from claude_mpm.commander.models.events import EventType
 from claude_mpm.commander.tmux_orchestrator import TmuxOrchestrator
 
+if TYPE_CHECKING:
+    from claude_mpm.commander.events.manager import EventManager
+    from claude_mpm.commander.persistence.state_store import StateStore
+
 logger = logging.getLogger(__name__)
 
 
@@ -75,6 +88,32 @@ class InstanceManager:
         self._instances: dict[str, InstanceInfo] = {}
         self._frameworks = self._load_frameworks()
         self._adapters: dict[str, ClaudeCodeCommunicationAdapter] = {}
+        self._event_manager: Optional[EventManager] = None
+        self._state_store: Optional[StateStore] = None
+
+    def set_event_manager(self, event_manager: "EventManager") -> None:
+        """Set the event manager for emitting instance events.
+
+        Args:
+            event_manager: EventManager instance for event emission
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> manager.set_event_manager(event_manager)
+        """
+        self._event_manager = event_manager
+
+    def set_state_store(self, state_store: "StateStore") -> None:
+        """Set state store for persistence.
+
+        Args:
+            state_store: StateStore instance for persisting registered instances
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> manager.set_state_store(state_store)
+        """
+        self._state_store = state_store
 
     def _load_frameworks(self) -> dict[str, BaseFramework]:
         """Load available frameworks.
@@ -200,8 +239,187 @@ class InstanceManager:
             f"Started instance '{name}' with framework '{framework}' at {project_path}"
         )
 
+        # Emit starting event and start background ready detection
+        if self._event_manager:
+            event = self._event_manager.create(
+                project_id=name,
+                event_type=EventType.INSTANCE_STARTING,
+                title=f"Starting instance '{name}'",
+                content=f"Instance {name} is starting at {project_path}",
+                context={"instance_name": name, "working_dir": str(project_path)},
+            )
+            await self._event_manager.emit(event)
+
+        # Start background ready detection (always, not just with event_manager)
+        asyncio.create_task(self._detect_ready(name, instance))
+
         return instance
 
+    async def _detect_ready(
+        self, name: str, instance_info: InstanceInfo, timeout: int = 30
+    ) -> None:
+        """Background task to detect when instance is ready.
+
+        Monitors the pane output for patterns indicating the instance
+        is ready to accept commands.
+
+        Args:
+            name: Instance name
+            instance_info: InstanceInfo with pane details
+            timeout: Maximum seconds to wait for ready state
+
+        Example:
+            >>> # Called internally by start_instance
+            >>> asyncio.create_task(self._detect_ready(name, instance))
+        """
+        # TIER 1: Startup markers (most reliable, appear at T+0-2s)
+        startup_patterns = [
+            r"Claude Code v[\d.]+",  # Version marker
+            r"Claude Code",  # Product identification
+            r"Opus 4\.5",  # Model identifier
+            r"Claude Max|Claude Pro",  # Tier indicator
+        ]
+
+        # TIER 2: Ready state indicators (appear at T+5-10s)
+        ready_patterns = [
+            r">\s*$",  # CLI prompt (end of line)
+            r"^>\s*",  # CLI prompt (start of line)
+            r"What can I.*help",  # Specific greeting
+            r"How can I.*assist",  # Specific greeting
+            r"(Human|User):\s*$",  # Anthropic format
+        ]
+
+        # TIER 3: Secondary indicators (confirmation)
+        secondary_patterns = [
+            r"Ready for input",  # Explicit ready
+            r"Tips for getting",  # Claude CLI tips
+            r"Use /help",  # Help hint
+            r"claudeMd",  # CLAUDE.md loaded
+            r"Agent Memory",  # Agent initialized
+            r"PM_INSTRUCTIONS",  # MPM initialized
+        ]
+
+        # Combine all patterns (TIER 1 most reliable)
+        all_patterns = startup_patterns + ready_patterns + secondary_patterns
+
+        start_time = asyncio.get_event_loop().time()
+        check_count = 0
+
+        while asyncio.get_event_loop().time() - start_time < timeout:
+            elapsed = asyncio.get_event_loop().time() - start_time
+            check_count += 1
+
+            # Progress logging at key milestones
+            if elapsed > 10 and check_count == 11:
+                logger.info(
+                    f"Ready detection for '{name}' still waiting after 10s... "
+                    f"(Claude Code startup may be slow)"
+                )
+            elif elapsed > 20 and check_count == 21:
+                logger.info(
+                    f"Ready detection for '{name}' still waiting after 20s... "
+                    f"(system may be overloaded)"
+                )
+
+            await asyncio.sleep(1)
+            try:
+                # IMPROVED: Increased buffer from 50 to 100 lines
+                output = self.orchestrator.capture_output(
+                    instance_info.pane_target, lines=100
+                )
+
+                if output:
+                    # Check all patterns (added re.IGNORECASE flag)
+                    # IMPROVED: Use MULTILINE | IGNORECASE flags
+                    for pattern in all_patterns:
+                        if re.search(pattern, output, re.MULTILINE | re.IGNORECASE):
+                            # Instance is ready!
+                            if name in self._instances:
+                                self._instances[name].ready = True
+
+                            # Emit ready event
+                            if self._event_manager:
+                                event = self._event_manager.create(
+                                    project_id=name,
+                                    event_type=EventType.INSTANCE_READY,
+                                    title=f"Instance '{name}' ready",
+                                    content=(
+                                        f"Instance {name} is ready for commands "
+                                        f"(detected in {elapsed:.1f}s)"
+                                    ),
+                                    context={
+                                        "instance_name": name,
+                                        "detection_time": elapsed,
+                                        "pattern_matched": pattern,
+                                    },
+                                )
+                                await self._event_manager.emit(event)
+
+                            logger.info(
+                                f"Instance '{name}' is ready "
+                                f"(detected in {elapsed:.1f}s via pattern: {pattern})"
+                            )
+                            return
+
+            except Exception as e:
+                logger.debug(
+                    f"Error checking ready state for '{name}': {e}. "
+                    f"Elapsed: {elapsed:.1f}s"
+                )
+
+        # Timeout - mark as ready anyway since instance might still work
+        logger.warning(
+            f"Instance '{name}' ready detection timed out after {timeout}s. "
+            f"Instance may still be functional. Check logs for issues."
+        )
+
+        if name in self._instances:
+            self._instances[name].ready = True
+
+        if self._event_manager:
+            event = self._event_manager.create(
+                project_id=name,
+                event_type=EventType.INSTANCE_READY,
+                title=f"Instance '{name}' started",
+                content=(
+                    f"Instance {name} startup timeout. "
+                    f"May be ready, or startup may be slow/blocked. "
+                    f"Check instance manually if issues occur."
+                ),
+                context={
+                    "instance_name": name,
+                    "timeout": True,
+                    "timeout_seconds": timeout,
+                },
+            )
+            await self._event_manager.emit(event)
+
+    async def wait_for_ready(self, name: str, timeout: int = 30) -> bool:
+        """Wait for an instance to be ready.
+
+        Polls the instance's ready flag until it becomes True or timeout.
+
+        Args:
+            name: Instance name
+            timeout: Maximum seconds to wait
+
+        Returns:
+            True if instance is ready, False if timeout
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> await manager.start_instance("myapp", "/path/to/app", "mpm")
+            >>> if await manager.wait_for_ready("myapp", timeout=30):
+            ...     print("Ready!")
+        """
+        start_time = asyncio.get_event_loop().time()
+        while asyncio.get_event_loop().time() - start_time < timeout:
+            inst = self._instances.get(name)
+            if inst and inst.ready:
+                return True
+            await asyncio.sleep(0.5)
+        return False
+
     async def stop_instance(self, name: str) -> bool:
         """Stop an instance.
 
@@ -387,26 +605,50 @@ class InstanceManager:
 
         return True
 
-    async def close_instance(self, name: str) -> bool:
-        """Close and remove an instance.
-
-        Alias for stop_instance that provides clearer semantics for closing.
+    async def close_instance(self, name: str, merge: bool = True) -> tuple[bool, str]:
+        """Close instance: stop tmux, optionally merge worktree, cleanup.
 
         Args:
             name: Instance name to close
+            merge: Whether to merge worktree to main (default True)
 
         Returns:
-            True if closed successfully
-
-        Raises:
-            InstanceNotFoundError: If instance not found
+            Tuple of (success, message)
 
         Example:
             >>> manager = InstanceManager(orchestrator)
-            >>> await manager.close_instance("myapp")
-            True
+            >>> success, msg = await manager.close_instance("myapp")
+            >>> print(success, msg)
+            True Closed 'myapp'
         """
-        return await self.stop_instance(name)
+        registered = (
+            self._state_store.get_registered_instance(name)
+            if self._state_store
+            else None
+        )
+
+        # Stop the tmux session
+        try:
+            await self.stop_instance(name)
+        except InstanceNotFoundError:
+            # Instance not running, but may still have worktree to clean up
+            pass
+
+        # Merge and cleanup worktree if enabled
+        if registered and registered.use_worktree and registered.worktree_path:
+            wt_manager = WorktreeManager(Path(registered.path))
+            if merge:
+                success, msg = wt_manager.merge_to_main(name, delete_after=True)
+                if not success:
+                    return False, msg
+            else:
+                wt_manager.remove(name, force=True)
+
+        # Remove from registry
+        if self._state_store:
+            self._state_store.unregister_instance(name)
+
+        return True, f"Closed '{name}'"
 
     async def disconnect_instance(self, name: str) -> bool:
         """Disconnect from an instance without closing it.
@@ -448,3 +690,176 @@ class InstanceManager:
             logger.debug(f"No adapter to disconnect for instance '{name}'")
 
         return True
+
+    async def register_instance(
+        self,
+        path: str,
+        framework: str,
+        name: str,
+        use_worktree: bool = True,
+        branch: Optional[str] = None,
+    ) -> InstanceInfo:
+        """Register an instance and start it.
+
+        Registers the instance in persistent storage so it can be started
+        by name in future sessions, then starts the instance.
+
+        Args:
+            path: Project directory path
+            framework: Framework to use ("cc" or "mpm")
+            name: Instance name (also worktree name if enabled)
+            use_worktree: Create isolated git worktree (default True)
+            branch: Branch for worktree (default: session-{name})
+
+        Returns:
+            InstanceInfo with tmux session details
+
+        Raises:
+            FrameworkNotFoundError: If framework is not available
+            InstanceAlreadyExistsError: If instance already exists
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> manager.set_state_store(state_store)
+            >>> instance = await manager.register_instance(
+            ...     "/Users/user/myapp", "cc", "myapp"
+            ... )
+            >>> print(instance.name, instance.framework)
+            myapp cc
+        """
+        project_path = Path(path).expanduser().resolve()
+
+        worktree_path = None
+        worktree_branch = None
+        working_path = project_path
+
+        # Create worktree if enabled and it's a git repo
+        if use_worktree and (project_path / ".git").exists():
+            try:
+                wt_manager = WorktreeManager(project_path)
+                wt_info = wt_manager.create(name, branch)
+                worktree_path = str(wt_info.path)
+                worktree_branch = wt_info.branch
+                working_path = wt_info.path
+                logger.info(
+                    f"Created worktree for '{name}' at {worktree_path} "
+                    f"on branch {worktree_branch}"
+                )
+            except Exception as e:
+                logger.warning(f"Could not create worktree: {e}. Using original path.")
+
+        # Create registered instance with worktree info
+        registered = RegisteredInstance(
+            name=name,
+            path=str(project_path),
+            framework=framework,
+            registered_at=datetime.now(timezone.utc).isoformat(),
+            worktree_path=worktree_path,
+            worktree_branch=worktree_branch,
+            use_worktree=use_worktree and worktree_path is not None,
+        )
+
+        # Save to persistent storage
+        if self._state_store:
+            self._state_store.register_instance(registered)
+
+        # Start the instance in worktree path
+        return await self.start_instance(name, working_path, framework)
+
+    async def start_by_name(self, name: str) -> Optional[InstanceInfo]:
+        """Start a previously registered instance by name.
+
+        Looks up the instance registration and starts it with the
+        stored path and framework. Uses the worktree path if configured.
+
+        Args:
+            name: Instance name (must have been previously registered)
+
+        Returns:
+            InstanceInfo if instance was found and started, None if not registered
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> manager.set_state_store(state_store)
+            >>> # After previous registration
+            >>> instance = await manager.start_by_name("myapp")
+            >>> if instance:
+            ...     print(instance.name, instance.project_path)
+            myapp /Users/user/myapp
+        """
+        if not self._state_store:
+            return None
+
+        registered = self._state_store.get_registered_instance(name)
+        if not registered:
+            return None
+
+        # Use working_path which respects worktree setting
+        return await self.start_instance(
+            registered.name,
+            Path(registered.working_path),
+            registered.framework,
+        )
+
+    def list_registered(self) -> dict[str, RegisteredInstance]:
+        """List all registered instances.
+
+        Returns:
+            Dict mapping instance name to RegisteredInstance
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> manager.set_state_store(state_store)
+            >>> registered = manager.list_registered()
+            >>> for name, instance in registered.items():
+            ...     print(f"{name}: {instance.path} ({instance.framework})")
+            myapp: /Users/user/myapp (cc)
+        """
+        if not self._state_store:
+            return {}
+        return self._state_store.load_instances()
+
+    def unregister(self, name: str) -> bool:
+        """Unregister an instance.
+
+        Removes the instance from persistent storage. Does not stop
+        any running instance with this name.
+
+        Args:
+            name: Instance name to unregister
+
+        Returns:
+            True if instance was found and unregistered, False if not found
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> manager.set_state_store(state_store)
+            >>> success = manager.unregister("myapp")
+            >>> print(success)
+            True
+        """
+        if not self._state_store:
+            return False
+        return self._state_store.unregister_instance(name)
+
+    def list_worktrees(self, path: str) -> list:
+        """List worktrees for a project.
+
+        Args:
+            path: Project directory path
+
+        Returns:
+            List of WorktreeInfo for all worktrees associated with the project
+
+        Example:
+            >>> manager = InstanceManager(orchestrator)
+            >>> worktrees = manager.list_worktrees("/Users/user/myapp")
+            >>> for wt in worktrees:
+            ...     print(f"{wt.name}: {wt.path} ({wt.branch})")
+            myapp: /Users/user/.worktrees-myapp/myapp (session-myapp)
+        """
+        try:
+            wt_manager = WorktreeManager(Path(path))
+            return wt_manager.list()
+        except Exception:
+            return []

claude_mpm/commander/models/events.py

@@ -26,6 +26,9 @@ class EventType(Enum):
     MILESTONE = "milestone"  # Significant progress
     STATUS = "status"  # General update
     PROJECT_IDLE = "project_idle"  # Project has no work
+    INSTANCE_STARTING = "instance_starting"  # Instance is starting up
+    INSTANCE_READY = "instance_ready"  # Instance is ready for work
+    INSTANCE_ERROR = "instance_error"  # Instance encountered an error
 
 
 class EventPriority(Enum):
@@ -62,6 +65,9 @@ DEFAULT_PRIORITIES: Dict[EventType, EventPriority] = {
     EventType.MILESTONE: EventPriority.LOW,
     EventType.STATUS: EventPriority.INFO,
     EventType.PROJECT_IDLE: EventPriority.INFO,
+    EventType.INSTANCE_STARTING: EventPriority.INFO,
+    EventType.INSTANCE_READY: EventPriority.INFO,
+    EventType.INSTANCE_ERROR: EventPriority.HIGH,
 }
 
 

claude_mpm/commander/persistence/state_store.py

@@ -10,8 +10,9 @@ import logging
 import tempfile
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional
 
+from ..frameworks.base import RegisteredInstance
 from ..models import Project, ProjectState, ToolSession
 from ..registry import ProjectRegistry
 
@@ -48,6 +49,7 @@ class StateStore:
 
         self.projects_path = self.state_dir / "projects.json"
         self.sessions_path = self.state_dir / "sessions.json"
+        self.instances_path = self.state_dir / "instances.json"
 
         logger.info(f"Initialized StateStore at {self.state_dir}")
 
@@ -307,3 +309,95 @@ class StateStore:
                 else None
             ),
         )
+
+    # Instance persistence methods
+
+    def save_instances(self, instances: Dict[str, RegisteredInstance]) -> None:
+        """Save registered instances to disk.
+
+        Args:
+            instances: Dict mapping instance name to RegisteredInstance
+
+        Raises:
+            IOError: If write fails
+        """
+        data = {
+            "version": self.VERSION,
+            "saved_at": datetime.now(timezone.utc).isoformat(),
+            "instances": {name: inst.to_dict() for name, inst in instances.items()},
+        }
+        self._atomic_write(self.instances_path, data)
+        logger.info(f"Saved {len(instances)} instances to {self.instances_path}")
+
+    def load_instances(self) -> Dict[str, RegisteredInstance]:
+        """Load registered instances from disk.
+
+        Returns:
+            Dict mapping instance name to RegisteredInstance
+            (empty if file missing or corrupt)
+        """
+        if not self.instances_path.exists():
+            logger.info("No instances file found, returning empty dict")
+            return {}
+
+        try:
+            data = self._read_json(self.instances_path)
+
+            if data.get("version") != self.VERSION:
+                logger.warning(
+                    f"Version mismatch: expected {self.VERSION}, "
+                    f"got {data.get('version')}"
+                )
+
+            instances = {
+                name: RegisteredInstance.from_dict(inst_data)
+                for name, inst_data in data.get("instances", {}).items()
+            }
+
+            logger.info(f"Loaded {len(instances)} instances from {self.instances_path}")
+            return instances
+
+        except Exception as e:
+            logger.error(f"Failed to load instances: {e}", exc_info=True)
+            return {}
+
+    def register_instance(self, instance: RegisteredInstance) -> None:
+        """Register a single instance (add to existing).
+
+        Args:
+            instance: RegisteredInstance to add
+        """
+        instances = self.load_instances()
+        instances[instance.name] = instance
+        self.save_instances(instances)
+        logger.info(f"Registered instance '{instance.name}'")
+
+    def unregister_instance(self, name: str) -> bool:
+        """Remove an instance registration.
+
+        Args:
+            name: Instance name to remove
+
+        Returns:
+            True if instance was found and removed, False if not found
+        """
+        instances = self.load_instances()
+        if name in instances:
+            del instances[name]
+            self.save_instances(instances)
+            logger.info(f"Unregistered instance '{name}'")
+            return True
+        logger.warning(f"Instance '{name}' not found for unregistration")
+        return False
+
+    def get_registered_instance(self, name: str) -> Optional[RegisteredInstance]:
+        """Get a single registered instance by name.
+
+        Args:
+            name: Instance name to look up
+
+        Returns:
+            RegisteredInstance if found, None otherwise
+        """
+        instances = self.load_instances()
+        return instances.get(name)

claude_mpm/commander/tmux_orchestrator.py

@@ -158,10 +158,11 @@ class TmuxOrchestrator:
         """
         logger.info(f"Creating pane '{pane_id}' in {working_dir}")
 
-        # Split window to create new pane
+        # Create new window instead of splitting pane to avoid "no space for new pane" error
+        # when tmux window is too small to split
         self._run_tmux(
             [
-                "split-window",
+                "new-window",
                 "-t",
                 self.session_name,
                 "-c",

claude_mpm/constants.py

@@ -46,6 +46,7 @@ class CLICommands(str, Enum):
     DASHBOARD = "dashboard"
     UPGRADE = "upgrade"
     SKILLS = "skills"
+    OAUTH = "oauth"
 
     def with_prefix(self, prefix: CLIPrefix = CLIPrefix.MPM) -> str:
         """Get command with prefix."""
@@ -143,6 +144,10 @@ class MCPCommands(str, Enum):
     CONFIG = "config"
     SERVER = "server"
     EXTERNAL = "external"
+    # Service management commands
+    ENABLE = "enable"
+    DISABLE = "disable"
+    LIST = "list"
 
 
 class TicketCommands(str, Enum):

claude_mpm/core/hook_manager.py

@@ -186,8 +186,9 @@ class HookManager:
             env["CLAUDE_MPM_HOOK_DEBUG"] = "true"
 
             # Execute with timeout in background thread
+            # Run as module to ensure proper package context for relative imports
             result = subprocess.run(  # nosec B603 B607
-                ["python", str(self.hook_handler_path)],
+                ["python", "-m", "claude_mpm.hooks.claude_hooks.hook_handler"],
                 input=event_json,
                 text=True,
                 capture_output=True,

claude_mpm/core/logging_utils.py

@@ -121,8 +121,10 @@ class LoggerFactory:
             root_logger.setLevel(desired_level)
         # else: root logger is suppressed (CRITICAL+1), keep it suppressed
 
-        # Remove existing handlers
-        root_logger.handlers = []
+        # Preserve FileHandlers (e.g., hooks logging), only remove StreamHandlers
+        root_logger.handlers = [
+            h for h in root_logger.handlers if isinstance(h, logging.FileHandler)
+        ]
 
         # CRITICAL FIX: Don't add handlers if logging is suppressed
         # If root logger is at CRITICAL+1 (startup suppression), don't add any handlers