claude-mpm 5.4.21__py3-none-any.whl → 5.4.59__py3-none-any.whl

claude_mpm/services/agents/deployment/remote_agent_discovery_service.py

@@ -42,7 +42,7 @@ class RemoteAgentMetadata:
 class RemoteAgentDiscoveryService:
     """Discovers and converts remote Markdown agents to JSON format.
 
-    Remote agents are discovered from the cache directory (~/.claude-mpm/cache/remote-agents/)
+    Remote agents are discovered from the cache directory (~/.claude-mpm/cache/agents/)
     where they are stored as Markdown files. This service:
     1. Discovers all *.md files in the remote agents cache
     2. Parses Markdown frontmatter and content to extract metadata
@@ -61,20 +61,20 @@ class RemoteAgentDiscoveryService:
     - Flexibility: Supports optional sections with defaults
     """
 
-    def __init__(self, remote_agents_dir: Path):
+    def __init__(self, agents_cache_dir: Path):
         """Initialize the remote agent discovery service.
 
         Args:
-            remote_agents_dir: Directory containing cached remote agent Markdown files
+            agents_cache_dir: Directory containing cached agent Markdown files
         """
-        self.remote_agents_dir = remote_agents_dir
+        self.agents_cache_dir = agents_cache_dir
         self.logger = get_logger(__name__)
 
     def _extract_collection_id_from_path(self, file_path: Path) -> Optional[str]:
         """Extract collection_id from repository path structure.
 
         Collection ID is derived from the repository path structure:
-        ~/.claude-mpm/cache/remote-agents/{owner}/{repo}/agents/...
+        ~/.claude-mpm/cache/agents/{owner}/{repo}/agents/...
 
         Args:
             file_path: Absolute path to agent Markdown file
@@ -83,28 +83,29 @@ class RemoteAgentDiscoveryService:
             Collection ID in format "owner/repo-name" or None if not found
 
         Example:
-            Input:  ~/.claude-mpm/cache/remote-agents/bobmatnyc/claude-mpm-agents/agents/pm.md
+            Input:  ~/.claude-mpm/cache/agents/bobmatnyc/claude-mpm-agents/agents/pm.md
             Output: "bobmatnyc/claude-mpm-agents"
         """
         try:
-            # Find "remote-agents" in the path
+            # Find "agents" cache directory in the path (looking for .claude-mpm/cache/agents)
             path_parts = file_path.parts
-            remote_agents_idx = -1
+            agents_cache_idx = -1
 
             for i, part in enumerate(path_parts):
-                if part == "remote-agents":
-                    remote_agents_idx = i
+                # Look for cache/agents pattern
+                if part == "agents" and i > 0 and path_parts[i - 1] == "cache":
+                    agents_cache_idx = i
                     break
 
-            if remote_agents_idx == -1 or remote_agents_idx + 2 >= len(path_parts):
+            if agents_cache_idx == -1 or agents_cache_idx + 2 >= len(path_parts):
                 self.logger.debug(
                     f"Could not extract collection_id from path: {file_path}"
                 )
                 return None
 
-            # Extract owner and repo (next two parts after "remote-agents")
-            owner = path_parts[remote_agents_idx + 1]
-            repo = path_parts[remote_agents_idx + 2]
+            # Extract owner and repo (next two parts after "cache/agents")
+            owner = path_parts[agents_cache_idx + 1]
+            repo = path_parts[agents_cache_idx + 2]
 
             collection_id = f"{owner}/{repo}"
             self.logger.debug(f"Extracted collection_id: {collection_id}")
@@ -128,25 +129,26 @@ class RemoteAgentDiscoveryService:
             Relative path from repo root, or None if not found
 
         Example:
-            Input:  ~/.claude-mpm/cache/remote-agents/bobmatnyc/claude-mpm-agents/agents/pm.md
+            Input:  ~/.claude-mpm/cache/agents/bobmatnyc/claude-mpm-agents/agents/pm.md
             Output: "agents/pm.md"
         """
         try:
-            # Find "remote-agents" in the path
+            # Find "agents" cache directory in the path
             path_parts = file_path.parts
-            remote_agents_idx = -1
+            agents_cache_idx = -1
 
             for i, part in enumerate(path_parts):
-                if part == "remote-agents":
-                    remote_agents_idx = i
+                # Look for cache/agents pattern
+                if part == "agents" and i > 0 and path_parts[i - 1] == "cache":
+                    agents_cache_idx = i
                     break
 
-            if remote_agents_idx == -1 or remote_agents_idx + 3 >= len(path_parts):
+            if agents_cache_idx == -1 or agents_cache_idx + 3 >= len(path_parts):
                 return None
 
             # Path after owner/repo is the source path
-            # remote-agents/{owner}/{repo}/{source_path}
-            repo_root_idx = remote_agents_idx + 3
+            # cache/agents/{owner}/{repo}/{source_path}
+            repo_root_idx = agents_cache_idx + 3
             source_parts = path_parts[repo_root_idx:]
 
             return "/".join(source_parts)
@@ -273,7 +275,7 @@ class RemoteAgentDiscoveryService:
 
         Supports both cache structures:
         1. Git repo: Calculate relative to /agents/ subdirectory
-        2. Flattened cache: Calculate relative to remote_agents_dir directly
+        2. Flattened cache: Calculate relative to agents_cache_dir directly
 
         Example (Git repo):
             Input:  /cache/bobmatnyc/claude-mpm-agents/agents/engineer/backend/python-engineer.md
@@ -281,8 +283,8 @@ class RemoteAgentDiscoveryService:
             Output: engineer/backend/python-engineer
 
         Example (Flattened cache):
-            Input:  /cache/remote-agents/engineer/python-engineer.md
-            Root:   /cache/remote-agents
+            Input:  /cache/agents/engineer/python-engineer.md
+            Root:   /cache/agents
             Output: engineer/python-engineer
 
         Args:
@@ -293,7 +295,7 @@ class RemoteAgentDiscoveryService:
         """
         try:
             # Try git repo structure first: /agents/ subdirectory
-            agents_dir = self.remote_agents_dir / "agents"
+            agents_dir = self.agents_cache_dir / "agents"
             if agents_dir.exists():
                 try:
                     relative_path = file_path.relative_to(agents_dir)
@@ -301,12 +303,12 @@ class RemoteAgentDiscoveryService:
                 except ValueError:
                     pass  # Not under agents_dir, try flattened structure
 
-            # Try flattened cache structure: calculate relative to remote_agents_dir
+            # Try flattened cache structure: calculate relative to agents_cache_dir
             try:
-                relative_path = file_path.relative_to(self.remote_agents_dir)
+                relative_path = file_path.relative_to(self.agents_cache_dir)
                 return str(relative_path.with_suffix("")).replace("\\", "/")
             except ValueError:
-                pass  # Not under remote_agents_dir either
+                pass  # Not under agents_cache_dir either
 
             # Fall back to filename
             self.logger.warning(
@@ -327,7 +329,7 @@ class RemoteAgentDiscoveryService:
 
         Supports both cache structures:
         1. Git repo: Calculate relative to /agents/ subdirectory
-        2. Flattened cache: Calculate relative to remote_agents_dir directly
+        2. Flattened cache: Calculate relative to agents_cache_dir directly
 
         Example (Git repo):
             Input:  /cache/bobmatnyc/claude-mpm-agents/agents/engineer/backend/python-engineer.md
@@ -335,8 +337,8 @@ class RemoteAgentDiscoveryService:
             Output: engineer/backend
 
         Example (Flattened cache):
-            Input:  /cache/remote-agents/engineer/python-engineer.md
-            Root:   /cache/remote-agents
+            Input:  /cache/agents/engineer/python-engineer.md
+            Root:   /cache/agents
             Output: engineer
 
         Args:
@@ -347,7 +349,7 @@ class RemoteAgentDiscoveryService:
         """
         try:
             # Try git repo structure first: /agents/ subdirectory
-            agents_dir = self.remote_agents_dir / "agents"
+            agents_dir = self.agents_cache_dir / "agents"
             if agents_dir.exists():
                 try:
                     relative_path = file_path.relative_to(agents_dir)
@@ -356,13 +358,13 @@ class RemoteAgentDiscoveryService:
                 except ValueError:
                     pass  # Not under agents_dir, try flattened structure
 
-            # Try flattened cache structure: calculate relative to remote_agents_dir
+            # Try flattened cache structure: calculate relative to agents_cache_dir
             try:
-                relative_path = file_path.relative_to(self.remote_agents_dir)
+                relative_path = file_path.relative_to(self.agents_cache_dir)
                 parts = relative_path.parts[:-1]  # Exclude filename
                 return "/".join(parts) if parts else "universal"
             except ValueError:
-                pass  # Not under remote_agents_dir either
+                pass  # Not under agents_cache_dir either
 
             return "universal"
         except Exception:
@@ -385,7 +387,7 @@ class RemoteAgentDiscoveryService:
             List of agent dictionaries in JSON template format
 
         Example:
-            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/remote-agents"))
+            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/agents"))
             >>> agents = service.discover_remote_agents()
             >>> len(agents)
             5
@@ -394,20 +396,21 @@ class RemoteAgentDiscoveryService:
         """
         agents = []
 
-        if not self.remote_agents_dir.exists():
+        if not self.agents_cache_dir.exists():
             self.logger.debug(
-                f"Remote agents directory does not exist: {self.remote_agents_dir}"
+                f"Agents cache directory does not exist: {self.agents_cache_dir}"
             )
             return agents
 
-        # Support three cache structures (PRIORITY ORDER):
+        # Support four cache structures (PRIORITY ORDER):
         # 1. Built output: {path}/dist/agents/ - PREFERRED (built with BASE-AGENT composition)
         # 2. Git repo path: {path}/agents/ - source files (fallback)
-        # 3. Flattened cache: {path}/ - directly contains category directories (legacy)
+        # 3. Owner/repo structure: {path}/{owner}/{repo}/agents/ - GitHub sync structure
+        # 4. Flattened cache: {path}/ - directly contains category directories (legacy)
 
         # Priority 1: Check for dist/agents/ (built output with BASE-AGENT composition)
-        dist_agents_dir = self.remote_agents_dir / "dist" / "agents"
-        agents_dir = self.remote_agents_dir / "agents"
+        dist_agents_dir = self.agents_cache_dir / "dist" / "agents"
+        agents_dir = self.agents_cache_dir / "agents"
 
         if dist_agents_dir.exists():
             # PREFERRED: Use built agents from dist/agents/
@@ -420,32 +423,52 @@ class RemoteAgentDiscoveryService:
             self.logger.debug(f"Using source agents (no dist/ found): {agents_dir}")
             scan_dir = agents_dir
         else:
-            # LEGACY: Flattened cache structure - scan root directly
-            # Check if this looks like the flattened cache (has category subdirectories)
-            category_dirs = [
-                "universal",
-                "engineer",
-                "ops",
-                "qa",
-                "security",
-                "documentation",
-            ]
-            has_categories = any(
-                (self.remote_agents_dir / cat).exists() for cat in category_dirs
-            )
-
-            if has_categories:
-                self.logger.debug(
-                    f"Using flattened cache structure: {self.remote_agents_dir}"
-                )
-                scan_dir = self.remote_agents_dir
+            # Priority 3: Check for {owner}/{repo}/agents/ structure (GitHub sync)
+            # e.g., ~/.claude-mpm/cache/agents/bobmatnyc/claude-mpm-agents/agents/
+            owner_repo_agents_dir = None
+            for owner_dir in self.agents_cache_dir.iterdir():
+                if owner_dir.is_dir() and not owner_dir.name.startswith("."):
+                    for repo_dir in owner_dir.iterdir():
+                        if repo_dir.is_dir():
+                            potential_agents = repo_dir / "agents"
+                            if potential_agents.exists():
+                                owner_repo_agents_dir = potential_agents
+                                self.logger.debug(
+                                    f"Using GitHub sync structure: {owner_repo_agents_dir}"
+                                )
+                                break
+                    if owner_repo_agents_dir:
+                        break
+
+            if owner_repo_agents_dir:
+                scan_dir = owner_repo_agents_dir
             else:
-                self.logger.warning(
-                    f"No agent directories found. Checked: {dist_agents_dir}, {agents_dir}, "
-                    f"and category directories in {self.remote_agents_dir}. "
-                    f"Expected agents in /dist/agents/, /agents/, or category directories."
+                # LEGACY: Flattened cache structure - scan root directly
+                # Check if this looks like the flattened cache (has category subdirectories)
+                category_dirs = [
+                    "universal",
+                    "engineer",
+                    "ops",
+                    "qa",
+                    "security",
+                    "documentation",
+                ]
+                has_categories = any(
+                    (self.agents_cache_dir / cat).exists() for cat in category_dirs
                 )
-                return agents
+
+                if has_categories:
+                    self.logger.debug(
+                        f"Using flattened cache structure: {self.agents_cache_dir}"
+                    )
+                    scan_dir = self.agents_cache_dir
+                else:
+                    self.logger.warning(
+                        f"No agent directories found. Checked: {dist_agents_dir}, {agents_dir}, "
+                        f"owner/repo/agents/ structure, and category directories in {self.agents_cache_dir}. "
+                        "Expected agents in /dist/agents/, /agents/, owner/repo/agents/, or category directories."
+                    )
+                    return agents
 
         # Find all Markdown files recursively
         md_files = list(scan_dir.rglob("*.md"))
@@ -482,16 +505,16 @@ class RemoteAgentDiscoveryService:
 
         # In flattened cache mode, also exclude files from git repository subdirectories
         # (files under directories that contain .git folder)
-        if scan_dir == self.remote_agents_dir:
+        if scan_dir == self.agents_cache_dir:
             filtered_files = []
             for f in md_files:
                 # Check if this file is inside a git repository (has .git in path)
-                # Git repos are at {remote_agents_dir}/{owner}/{repo}/.git
-                path_parts = f.relative_to(self.remote_agents_dir).parts
+                # Git repos are at {agents_cache_dir}/{owner}/{repo}/.git
+                path_parts = f.relative_to(self.agents_cache_dir).parts
                 if len(path_parts) >= 2:
                     # Check if this looks like a git repo path (owner/repo)
                     potential_repo = (
-                        self.remote_agents_dir / path_parts[0] / path_parts[1]
+                        self.agents_cache_dir / path_parts[0] / path_parts[1]
                     )
                     if (potential_repo / ".git").exists():
                         # This file is in a git repo, skip it (we'll handle git repos separately)
@@ -518,7 +541,7 @@ class RemoteAgentDiscoveryService:
                 self.logger.warning(f"Failed to parse remote agent {md_file.name}: {e}")
 
         self.logger.info(
-            f"Discovered {len(agents)} remote agents from {self.remote_agents_dir.name}"
+            f"Discovered {len(agents)} remote agents from {self.agents_cache_dir.name}"
         )
         return agents
 
@@ -735,7 +758,7 @@ class RemoteAgentDiscoveryService:
             RemoteAgentMetadata if found, None otherwise
         """
         # Bug #4 fix: Search in /agents/ subdirectory, not root directory
-        agents_dir = self.remote_agents_dir / "agents"
+        agents_dir = self.agents_cache_dir / "agents"
         if not agents_dir.exists():
             return None
 
@@ -767,7 +790,7 @@ class RemoteAgentDiscoveryService:
             List of agent dictionaries from the specified collection
 
         Example:
-            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/remote-agents"))
+            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/agents"))
             >>> agents = service.get_agents_by_collection("bobmatnyc/claude-mpm-agents")
             >>> len(agents)
             45
@@ -795,7 +818,7 @@ class RemoteAgentDiscoveryService:
             - agents: List of agent IDs in collection
 
         Example:
-            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/remote-agents"))
+            >>> service = RemoteAgentDiscoveryService(Path("~/.claude-mpm/cache/agents"))
             >>> collections = service.list_collections()
             >>> collections
             [

claude_mpm/services/agents/git_source_manager.py

@@ -50,10 +50,10 @@ class GitSourceManager:
 
         Args:
             cache_root: Root directory for repository caches.
-                       Defaults to ~/.claude-mpm/cache/remote-agents/
+                       Defaults to ~/.claude-mpm/cache/agents/
         """
         if cache_root is None:
-            cache_root = Path.home() / ".claude-mpm" / "cache" / "remote-agents"
+            cache_root = Path.home() / ".claude-mpm" / "cache" / "agents"
 
         self.cache_root = cache_root
         self.cache_root.mkdir(parents=True, exist_ok=True)
@@ -395,8 +395,27 @@ class GitSourceManager:
                     )
                     logger.debug(f"[DEBUG] Found {len(agents)} agents so far")
 
-        logger.debug(f"[DEBUG] list_cached_agents COMPLETE: {len(agents)} total agents")
-        return agents
+        logger.debug(
+            f"[DEBUG] list_cached_agents COMPLETE: {len(agents)} total agents (before deduplication)"
+        )
+
+        # Deduplicate agents by agent_id (Bug #2 fix)
+        # When same agent exists in multiple locations, keep only first occurrence
+        seen_ids = set()
+        deduplicated_agents = []
+
+        for agent in agents:
+            agent_id = agent.get("agent_id") or agent.get("metadata", {}).get("name")
+            if agent_id and agent_id not in seen_ids:
+                seen_ids.add(agent_id)
+                deduplicated_agents.append(agent)
+            elif agent_id:
+                logger.debug(f"[DEBUG] Skipping duplicate agent: {agent_id}")
+
+        logger.debug(
+            f"[DEBUG] After deduplication: {len(deduplicated_agents)} unique agents"
+        )
+        return deduplicated_agents
 
     def _discover_agents_in_directory(
         self,

claude_mpm/services/agents/recommender.py

@@ -226,9 +226,11 @@ class AgentRecommenderService(BaseService, IAgentRecommender):
         if max_agents is not None:
             recommendations = recommendations[:max_agents]
 
-        # Check if toolchain is unknown and we have no recommendations
-        if not recommendations and toolchain.primary_language.lower() == "unknown":
-            self.logger.info("Toolchain unknown - applying default configuration")
+        # Check if we have no recommendations (any reason: unknown language, low scores, etc.)
+        if not recommendations:
+            self.logger.info(
+                f"No agents scored above threshold for {toolchain.primary_language}; using defaults"
+            )
 
             # Get default configuration
             default_config = self._capabilities_config.get("default_configuration", {})

claude_mpm/services/agents/single_tier_deployment_service.py

@@ -78,14 +78,14 @@ class SingleTierDeploymentService:
             config: Agent source configuration with repositories
             deployment_dir: Target deployment directory (.claude/agents/)
             cache_root: Cache root for repositories
-                       (defaults to ~/.claude-mpm/cache/remote-agents/)
+                       (defaults to ~/.claude-mpm/cache/agents/)
         """
         self.config = config
         self.deployment_dir = deployment_dir
         self.deployment_dir.mkdir(parents=True, exist_ok=True)
 
         if cache_root is None:
-            cache_root = Path.home() / ".claude-mpm" / "cache" / "remote-agents"
+            cache_root = Path.home() / ".claude-mpm" / "cache" / "agents"
 
         self.cache_root = cache_root
         self.git_source_manager = GitSourceManager(cache_root)

claude_mpm/services/agents/sources/git_source_sync_service.py

@@ -13,11 +13,16 @@ import logging
 import time
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Dict, List, Optional, Set, Tuple
 
 import requests
 
 from claude_mpm.core.file_utils import get_file_hash
+
+# Import normalize function for exclusion filtering
+from claude_mpm.services.agents.deployment.multi_source_deployment_service import (
+    _normalize_agent_name,
+)
 from claude_mpm.services.agents.sources.agent_sync_state import AgentSyncState
 from claude_mpm.utils.progress import create_progress_bar
 
@@ -188,10 +193,10 @@ class GitSourceSyncService:
 
         Args:
             source_url: Base URL for raw files (without trailing slash)
-            cache_dir: Local cache directory (defaults to ~/.claude-mpm/cache/remote-agents/)
+            cache_dir: Local cache directory (defaults to ~/.claude-mpm/cache/agents/)
             source_id: Unique identifier for this source (for multi-source support)
 
-        Design Decision: Cache to ~/.claude-mpm/cache/remote-agents/ (canonical location)
+        Design Decision: Cache to ~/.claude-mpm/cache/agents/ (canonical location)
 
         Rationale: Separates cached repository structure from deployed agents.
         This allows preserving nested directory structure in cache while
@@ -207,13 +212,13 @@ class GitSourceSyncService:
         self.source_url = source_url.rstrip("/")
         self.source_id = source_id
 
-        # Setup cache directory (canonical: ~/.claude-mpm/cache/remote-agents/)
+        # Setup cache directory (canonical: ~/.claude-mpm/cache/agents/)
         if cache_dir:
             self.cache_dir = Path(cache_dir)
         else:
-            # Default to ~/.claude-mpm/cache/remote-agents/ (canonical cache location)
+            # Default to ~/.claude-mpm/cache/agents/ (canonical cache location)
             home = Path.home()
-            self.cache_dir = home / ".claude-mpm" / "cache" / "remote-agents"
+            self.cache_dir = home / ".claude-mpm" / "cache" / "agents"
 
         self.cache_dir.mkdir(parents=True, exist_ok=True)
 
@@ -923,6 +928,62 @@ class GitSourceSyncService:
         """
         return self.cache_dir
 
+    def _cleanup_excluded_agents(
+        self,
+        deployment_dir: Path,
+        excluded_set: Set[str],
+    ) -> Dict[str, List[str]]:
+        """Remove excluded agents from deployment directory.
+
+        Removes any agents in the deployment directory whose normalized
+        names match the exclusion list. This ensures that excluded agents
+        are cleaned up from previous deployments.
+
+        Args:
+            deployment_dir: Directory containing deployed agents
+            excluded_set: Set of normalized agent names to exclude
+
+        Returns:
+            Dictionary with cleanup results:
+            - removed: List of agent names that were removed
+        """
+        cleanup_results: Dict[str, List[str]] = {"removed": []}
+
+        if not deployment_dir.exists():
+            logger.debug("Deployment directory does not exist, no cleanup needed")
+            return cleanup_results
+
+        for item in deployment_dir.iterdir():
+            # Only process .md files
+            if not item.is_file() or item.suffix != ".md":
+                continue
+
+            # Skip hidden files
+            if item.name.startswith("."):
+                continue
+
+            # Normalize agent name for comparison
+            agent_name = _normalize_agent_name(item.stem)
+
+            # Check if this agent is excluded
+            if agent_name in excluded_set:
+                try:
+                    item.unlink()
+                    cleanup_results["removed"].append(item.stem)
+                    logger.info(f"Removed excluded agent: {item.stem}")
+                except PermissionError as e:
+                    logger.error(f"Permission denied removing {item.stem}: {e}")
+                except Exception as e:
+                    logger.error(f"Failed to remove {item.stem}: {e}")
+
+        # Log summary
+        if cleanup_results["removed"]:
+            logger.info(
+                f"Cleanup complete: removed {len(cleanup_results['removed'])} excluded agents"
+            )
+
+        return cleanup_results
+
     def deploy_agents_to_project(
         self,
         project_dir: Path,
@@ -977,6 +1038,8 @@ class GitSourceSyncService:
         """
         import shutil
 
+        from claude_mpm.core.config import Config
+
         # Deploy to .claude/agents/ where Claude Code expects them
         deployment_dir = project_dir / ".claude" / "agents"
         deployment_dir.mkdir(parents=True, exist_ok=True)
@@ -989,10 +1052,55 @@ class GitSourceSyncService:
             "deployment_dir": str(deployment_dir),
         }
 
+        # Load project config to get exclusion list
+        config_file = project_dir / ".claude-mpm" / "configuration.yaml"
+        if config_file.exists():
+            config = Config(config_file=config_file)
+            excluded_agents = config.get("excluded_agents", [])
+        else:
+            # No project config, no exclusions
+            excluded_agents = []
+
+        # Create normalized exclusion set
+        excluded_set: Set[str] = (
+            {_normalize_agent_name(name) for name in excluded_agents}
+            if excluded_agents
+            else set()
+        )
+
+        if excluded_set:
+            logger.info(
+                f"Applying exclusions: {', '.join(sorted(excluded_agents))} "
+                f"(normalized: {', '.join(sorted(excluded_set))})"
+            )
+
         # Get agents from cache or use provided list
         if agent_list is None:
             agent_list = self._discover_cached_agents()
 
+        # Filter out excluded agents
+        if excluded_set:
+            original_count = len(agent_list)
+            agent_list = [
+                agent_path
+                for agent_path in agent_list
+                if _normalize_agent_name(Path(agent_path).stem) not in excluded_set
+            ]
+            filtered_count = original_count - len(agent_list)
+            if filtered_count > 0:
+                logger.info(f"Filtered out {filtered_count} excluded agents")
+
+        # Clean up any previously deployed excluded agents
+        if excluded_set:
+            cleanup_results = self._cleanup_excluded_agents(
+                deployment_dir, excluded_set
+            )
+            if cleanup_results["removed"]:
+                logger.info(
+                    f"Cleaned up {len(cleanup_results['removed'])} excluded agents: "
+                    f"{', '.join(cleanup_results['removed'])}"
+                )
+
         logger.info(
             f"Deploying {len(agent_list)} agents from cache to {deployment_dir}"
         )
@@ -1010,14 +1118,17 @@ class GitSourceSyncService:
                 deploy_filename = Path(agent_path).name
                 deploy_file = deployment_dir / deploy_filename
 
-                # Check if update needed (compare modification times)
+                # Check if update needed (compare content, not just mtime)
+                # DESIGN: Use content hash comparison for reliable change detection
+                # Mtime comparison can fail when cache downloads have older timestamps
                 should_deploy = force
                 was_existing = deploy_file.exists()
 
                 if not force and was_existing:
-                    cache_mtime = cache_file.stat().st_mtime
-                    deploy_mtime = deploy_file.stat().st_mtime
-                    should_deploy = cache_mtime > deploy_mtime
+                    # Compare file contents using hash
+                    cache_content = cache_file.read_bytes()
+                    deploy_content = deploy_file.read_bytes()
+                    should_deploy = cache_content != deploy_content
 
                 if not should_deploy and was_existing:
                     results["skipped"].append(deploy_filename)