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

claude_mpm/agents/base_agent_loader.py

@@ -311,42 +311,17 @@ def _remove_test_mode_instructions(content: str) -> str:
     Returns:
         str: Content with test-mode instructions removed
     """
-    lines = content.split("\n")
-    filtered_lines = []
-    skip_section = False
-
-    i = 0
-    while i < len(lines):
-        line = lines[i]
-
-        # Check if we're entering the test response protocol section
-        if line.strip() == "## Standard Test Response Protocol":
-            skip_section = True
-            i += 1
-            continue
-
-        # Check if we're in the test section and need to continue skipping
-        if skip_section:
-            # Check if we've reached a new top-level section (## but not ###)
-            # Only stop skipping when we hit another ## section (same level as test section)
-            if line.startswith("##") and not line.startswith("###"):
-                skip_section = False
-                # Don't skip this line - it's the start of a new section
-                filtered_lines.append(line)
-                i += 1
-                continue
-            # Skip this line as we're still in test section (includes ### subsections)
-            i += 1
-            continue
-
-        # Not in test section, keep the line
-        filtered_lines.append(line)
-        i += 1
-
-    # Join back and clean up extra blank lines
-    result = "\n".join(filtered_lines)
+    import re
+
+    # Pattern matches from "## Standard Test Response Protocol"
+    # until the next "##" (but not "###") or end of string
+    # Uses negative lookahead to stop at ## but not ###
+    pattern = r"## Standard Test Response Protocol\n.*?(?=\n##(?!#)|\Z)"
+
+    # Remove the test section (DOTALL allows . to match newlines)
+    result = re.sub(pattern, "", content, flags=re.DOTALL)
 
-    # Replace multiple consecutive newlines with double newlines
+    # Clean up multiple consecutive newlines
     while "\n\n\n" in result:
         result = result.replace("\n\n\n", "\n\n")
 

claude_mpm/agents/frontmatter_validator.py

@@ -143,6 +143,10 @@ class FrontmatterValidator:
             "dependencies",
             "capabilities",
             "color",
+            # NEW: Collection-based identification fields
+            "collection_id",
+            "source_path",
+            "canonical_id",
         }
 
     def validate_and_correct(self, frontmatter: Dict[str, Any]) -> ValidationResult:
@@ -176,6 +180,8 @@ class FrontmatterValidator:
         self._validate_author_field(corrected, errors, warnings)
         self._validate_tags_field(corrected, errors, warnings)
         self._validate_numeric_fields(corrected, errors, warnings)
+        # NEW: Validate collection-based identification fields
+        self._validate_collection_fields(corrected, field_corrections, errors, warnings)
 
         # Determine if valid
         is_valid = len(errors) == 0
@@ -464,6 +470,68 @@ class FrontmatterValidator:
                     f"Field '{field_name}' value {value} outside recommended range [{min_val}, {max_val}]"
                 )
 
+    def _validate_collection_fields(
+        self,
+        corrected: Dict[str, Any],
+        field_corrections: Dict[str, Any],
+        errors: List[str],
+        warnings: List[str],
+    ) -> None:
+        """Validate collection-based identification fields.
+
+        NEW: Validates collection_id, source_path, and canonical_id fields.
+
+        These fields are auto-populated by RemoteAgentDiscoveryService for remote agents
+        and should follow specific formats:
+        - collection_id: "owner/repo-name" (e.g., "bobmatnyc/claude-mpm-agents")
+        - source_path: Relative path in repo (e.g., "agents/pm.md")
+        - canonical_id: "collection_id:agent_id" or "legacy:filename"
+        """
+        # Validate collection_id format (optional field)
+        if "collection_id" in corrected:
+            collection_id = corrected["collection_id"]
+            if not isinstance(collection_id, str):
+                errors.append(
+                    f"Field 'collection_id' must be a string, got {type(collection_id).__name__}"
+                )
+            elif "/" not in collection_id:
+                warnings.append(
+                    f"Field 'collection_id' should be in format 'owner/repo-name', got '{collection_id}'"
+                )
+
+        # Validate source_path format (optional field)
+        if "source_path" in corrected:
+            source_path = corrected["source_path"]
+            if not isinstance(source_path, str):
+                errors.append(
+                    f"Field 'source_path' must be a string, got {type(source_path).__name__}"
+                )
+
+        # Validate canonical_id format (optional field)
+        if "canonical_id" in corrected:
+            canonical_id = corrected["canonical_id"]
+            if not isinstance(canonical_id, str):
+                errors.append(
+                    f"Field 'canonical_id' must be a string, got {type(canonical_id).__name__}"
+                )
+            elif ":" not in canonical_id:
+                warnings.append(
+                    f"Field 'canonical_id' should be in format 'collection:agent_id' or 'legacy:filename', got '{canonical_id}'"
+                )
+
+        # Auto-generate canonical_id if collection_id is present but canonical_id is missing
+        if "collection_id" in corrected and "canonical_id" not in corrected:
+            collection_id = corrected["collection_id"]
+            agent_id = corrected.get("name", "unknown")
+
+            # Generate canonical_id
+            canonical_id = f"{collection_id}:{agent_id}"
+            corrected["canonical_id"] = canonical_id
+            field_corrections["canonical_id"] = canonical_id
+            warnings.append(
+                f"Auto-generated canonical_id: '{canonical_id}' from collection_id and name"
+            )
+
     def _normalize_model(self, model: str) -> str:
         """
         Normalize model name to standard tier using ModelTier enum.

claude_mpm/agents/templates/circuit-breakers.md

@@ -134,73 +134,265 @@ PM: Task(agent="engineer", task="Add express dependency to package.json")
 
 ## Circuit Breaker #2: Investigation Detection
 
-**Purpose**: Prevent PM from investigating code, analyzing patterns, or researching solutions.
+**Purpose**: Block PM from investigation work through pre-action enforcement
 
-### Trigger Conditions
+**Effectiveness Target**: 95% compliance (upgraded from 40% reactive detection)
+**Model**: Pre-action blocking pattern (Circuit Breaker #6 architecture)
+**Related Tests**: `tests/one-shot/pm-investigation-violations/test_001.md` through `test_005.md`
+**Research Analysis**: `docs/research/pm-investigation-violation-analysis.md`
 
-**IF PM attempts ANY of the following:**
+### Core Principle
 
-#### File Reading Investigation
-- Reading more than 1 file per session
-- Using `Read` tool for code exploration
-- Checking file contents for investigation
-- Reading documentation for understanding
+PM must detect investigation intent BEFORE using investigation tools. This circuit breaker enforces mandatory Research delegation for any task requiring code analysis, multi-file reading, or solution exploration.
 
-#### Search and Analysis
-- Using `Grep` tool for code search
-- Using `Glob` tool for file discovery
-- Using `WebSearch` or `WebFetch` for research
-- Analyzing code patterns or architecture
+### Pre-Action Blocking Protocol
 
-#### Investigation Activities
-- Searching for solutions or approaches
-- Examining dependencies or imports
-- Checking logs for debugging
-- Running git commands for history (`git log`, `git blame`)
+**MANDATORY: PM checks for investigation signals before tool execution**
 
-### Violation Response
+#### Step 1: User Request Analysis (BLOCKING)
 
-**→ STOP IMMEDIATELY**
+Before any tool use, PM analyzes user request for investigation triggers:
 
-**→ ERROR**: `"PM VIOLATION - Must delegate investigation to Research"`
+**Investigation Trigger Keywords**:
 
-**→ REQUIRED ACTION**: Delegate to:
-- **Research**: For code investigation, documentation reading, web research
-- **Code Analyzer**: For code analysis, pattern identification, architecture review
-- **Ops**: For log analysis and debugging
-- **Version Control**: For git history and code evolution
+| Category | Keywords | Action |
+|----------|----------|--------|
+| **Investigation Verbs** | "investigate", "check", "look at", "explore", "examine" | Block → Delegate to Research |
+| **Analysis Requests** | "analyze", "review", "inspect", "understand", "figure out" | Block → Delegate to Research |
+| **Problem Diagnosis** | "debug", "find out", "what's wrong", "why is", "how does" | Block → Delegate to Research |
+| **Code Exploration** | "see what", "show me", "where is", "find the code" | Block → Delegate to Research |
 
-**→ VIOLATIONS TRACKED AND REPORTED**
+**Detection Rule**: If user request contains ANY trigger keyword → PM MUST delegate to Research BEFORE using Read/Grep/Glob/WebSearch/WebFetch tools.
 
-### Allowed Exceptions
+**Example**:
+```
+User: "Investigate why authentication is failing"
+         ↓
+PM detects: "investigate" (trigger keyword)
+         ↓
+BLOCK: Read/Grep/Glob tools forbidden
+         ↓
+PM delegates: Task(agent="research", task="Investigate authentication failure")
+```
+
+#### Step 2: PM Self-Awareness Check (BLOCKING)
+
+PM monitors own statements for investigation language:
+
+**Self-Detection Triggers**:
+
+| PM Statement | Violation Type | Required Self-Correction |
+|--------------|----------------|--------------------------|
+| "I'll investigate..." | Investigation intent | "I'll have Research investigate..." |
+| "Let me check..." | Investigation intent | "I'll delegate to Research to check..." |
+| "I'll look at..." | Investigation intent | "I'll have Research analyze..." |
+| "I'll analyze..." | Investigation intent | "I'll delegate to Research to analyze..." |
+| "I'll explore..." | Investigation intent | "I'll have Research explore..." |
+
+**Detection Rule**: PM detects investigation language in own reasoning → Self-correct to delegation language BEFORE tool use.
+
+**Example**:
+```
+PM thinks: "I'll investigate this bug..."
+            ↓
+PM detects: "investigate" in own statement (trigger)
+            ↓
+PM corrects: "I'll have Research investigate this bug..."
+            ↓
+PM delegates: Task(agent="research", task="...")
+```
+
+#### Step 3: Read Tool Limit Enforcement (BLOCKING)
+
+**Absolute Rule**: PM can read EXACTLY ONE file per task for delegation context only.
+
+**Pre-Read Checkpoint** (MANDATORY before Read tool):
+
+```python
+def before_read_tool(file_path, task_context):
+    # Checkpoint 1: Investigation keywords present?
+    if user_request_has_investigation_keywords():
+        BLOCK("User request requires investigation. Delegate to Research. Zero reads allowed.")
+
+    # Checkpoint 2: Already used Read once?
+    if read_count_this_task >= 1:
+        BLOCK("PM already read one file. Second read forbidden. Delegate to Research.")
+
+    # Checkpoint 3: Source code file?
+    if is_source_code(file_path):  # .py, .js, .ts, .java, .go, etc.
+        BLOCK("PM cannot read source code. Delegate to Research for code investigation.")
+
+    # Checkpoint 4: Task requires codebase understanding?
+    if task_requires_understanding_architecture():
+        BLOCK("Task requires investigation. Delegate to Research. Zero reads allowed.")
+
+    # All checkpoints passed - allow ONE file read
+    read_count_this_task += 1
+    ALLOW(file_path)
+```
+
+**Blocking Conditions**:
+- Read count ≥ 1 → Block second read
+- Source code file → Block (any .py/.js/.ts/.java/.go file)
+- Investigation keywords in request → Block (zero reads allowed)
+- Task requires understanding → Block (delegate instead)
+
+**Allowed Exception** (strict criteria):
+- File is configuration (config.json, database.yaml, package.json)
+- Purpose is delegation context (not investigation)
+- Zero investigation keywords in user request
+- PM has NOT already used Read in this task
+
+#### Step 4: Investigation Tool Blocking (ABSOLUTE)
+
+**Grep/Glob Tools**: ALWAYS FORBIDDEN for PM (no exceptions)
+
+**Blocking Rule**:
+```python
+def before_grep_or_glob_tool(tool_name):
+    BLOCK(
+        f"Circuit Breaker #2 VIOLATION: "
+        f"PM cannot use {tool_name} for code exploration. "
+        f"MUST delegate to Research agent."
+    )
+```
+
+**WebSearch/WebFetch Tools**: ALWAYS FORBIDDEN for PM (no exceptions)
+
+**Blocking Rule**:
+```python
+def before_web_research_tool(tool_name):
+    BLOCK(
+        f"Circuit Breaker #2 VIOLATION: "
+        f"PM cannot use {tool_name} for research. "
+        f"MUST delegate to Research agent."
+    )
+```
+
+**Rationale**: These tools are investigation tools by design. PM using them indicates investigation work that must be delegated.
+
+### Trigger Conditions Summary
+
+**BLOCK immediately if PM attempts**:
+
+1. **Investigation Keywords Detected**
+   - User says: "investigate", "check", "analyze", "explore", "debug"
+   - PM must delegate BEFORE using Read/Grep/Glob/WebSearch
 
-**ONE file read** per session is allowed for quick context (e.g., checking a single config file).
+2. **PM Self-Investigation Statements**
+   - PM says: "I'll investigate", "let me check", "I'll look at"
+   - PM must self-correct to delegation language
 
-**Vector search** (`mcp__mcp-vector-search__*`) is allowed for quick context BEFORE delegation.
+3. **Multiple File Reading**
+   - PM already used Read once → Second read blocked
+   - Must delegate to Research for multi-file investigation
+
+4. **Source Code Reading**
+   - PM attempts Read on .py/.js/.ts/.java/.go files → Blocked
+   - Must delegate to Research for code investigation
+
+5. **Investigation Tools**
+   - Grep/Glob/WebSearch/WebFetch → Always blocked
+   - Must delegate to Research (no exceptions)
+
+### Violation Response
+
+**→ BLOCK BEFORE TOOL EXECUTION**
+
+**→ ERROR MESSAGE**:
+```
+"Circuit Breaker #2 VIOLATION: [specific violation]
+PM cannot investigate directly.
+MUST delegate to Research agent."
+```
+
+**→ REQUIRED ACTION**: Immediate delegation to Research agent
+
+**→ VIOLATIONS LOGGED**: Track for session compliance report
+
+### Delegation Targets
+
+**Delegate investigation work to**:
+- **Research**: Code investigation, multi-file analysis, web research, documentation reading
+- **Code Analyzer**: Architecture review, pattern analysis (after Research provides context)
+- **Ops**: Log analysis, debugging production issues
+- **Version Control**: Git history investigation, code evolution analysis
 
 ### Examples
 
-#### ❌ VIOLATION Examples
+#### Pre-Action Blocking (CORRECT)
 
 ```
-PM: Read("src/auth.js")
-    Read("src/middleware.js")               # VIOLATION - reading multiple files
-PM: Grep(pattern="authentication")          # VIOLATION - searching code
-PM: Glob(pattern="**/*.js")                 # VIOLATION - file discovery
-PM: WebSearch(query="how to fix CORS")      # VIOLATION - researching solutions
-PM: Bash("git log src/auth.js")             # VIOLATION - investigating history
+User: "Investigate authentication failure"
+       ↓
+PM detects: "investigate" keyword
+       ↓
+PM blocks: Read/Grep/Glob tools (BEFORE use)
+       ↓
+PM delegates: Task(agent="research", task="Investigate authentication failure")
+       ↓
+Tool usage count: 0 (zero tools used by PM)
 ```
 
-#### ✅ CORRECT Examples
+#### Self-Correction (CORRECT)
 
 ```
-PM: Task(agent="research", task="Analyze authentication system across all auth-related files")
-PM: Task(agent="research", task="Find all JavaScript files using Glob and summarize")
-PM: Task(agent="research", task="Research CORS fix solutions for Express.js")
-PM: Task(agent="version-control", task="Review git history for auth.js changes")
-PM: Read("config.json")                     # ALLOWED - single file for context
+User: "Check why login is broken"
+       ↓
+PM thinks: "I'll investigate the login code..."
+       ↓
+PM detects: "investigate" in own statement
+       ↓
+PM corrects: "I'll have Research investigate..."
+       ↓
+PM delegates: Task(agent="research", task="Investigate login bug")
 ```
 
+#### Read Limit Enforcement (CORRECT)
+
+```
+User: "Check auth and session code"
+       ↓
+PM detects: "check" + multiple components
+       ↓
+PM reasoning: "Would need to read auth.js AND session.js (>1 file)"
+       ↓
+PM blocks: Read tool (BEFORE first read)
+       ↓
+PM delegates: Task(agent="research", task="Analyze auth and session code")
+       ↓
+Read count: 0 (zero reads by PM)
+```
+
+#### Violation Examples (BLOCKED)
+
+```
+❌ PM: Read("src/auth.js") then Read("src/session.js")
+   VIOLATION: Multiple file reads (>1 file limit)
+
+❌ PM: "I'll investigate..." then uses Read tool
+   VIOLATION: Investigation language detected, proceeded anyway
+
+❌ PM: Grep(pattern="authentication")
+   VIOLATION: Investigation tool usage (Grep always forbidden)
+
+❌ PM: User says "investigate", PM uses Read
+   VIOLATION: Investigation keyword ignored, proceeded with tools
+```
+
+### Success Metrics
+
+**Target Effectiveness**: 95% compliance
+
+**Measurement Criteria**:
+1. **Trigger Word Detection**: 90%+ of investigation keywords detected
+2. **Self-Awareness**: 85%+ of PM investigation statements self-corrected
+3. **Pre-Action Blocking**: 95%+ of blocks occur BEFORE tool use
+4. **Read Limit Compliance**: 98%+ tasks follow one-file maximum rule
+5. **Overall Violation Rate**: <10% sessions with Circuit Breaker #2 violations
+
+**Test Validation**: All 5 test cases in `tests/one-shot/pm-investigation-violations/` must pass
+
 ---
 
 ## Circuit Breaker #3: Unverified Assertion Detection
@@ -558,11 +750,68 @@ PM: "All test files tracked in git"
 
 **CRITICAL**: PM MUST NEVER use ticketing tools directly - ALWAYS delegate to ticketing.
 
-#### Ticketing Tool Direct Usage
+#### Ticketing Tool Direct Usage (BLOCKING)
 - PM uses any mcp-ticketer tools (`mcp__mcp-ticketer__*`)
 - PM runs aitrackdown CLI commands (`aitrackdown create`, `aitrackdown show`, etc.)
 - PM accesses Linear/GitHub/JIRA APIs directly
 - PM reads/writes ticket data without delegating
+- PM uses WebFetch on ticket URLs (Linear, GitHub, JIRA)
+
+#### Pre-Action Enforcement Hook
+
+**BEFORE PM uses ANY tool, check:**
+
+```python
+# Forbidden tool patterns for PM
+FORBIDDEN_TICKETING_TOOLS = [
+    "mcp__mcp-ticketer__",  # All mcp-ticketer tools
+    "aitrackdown",           # CLI commands
+    "linear.app",            # Linear URLs in WebFetch
+    "github.com/*/issues/",  # GitHub issue URLs
+    "*/jira/",               # JIRA URLs
+]
+
+def before_pm_tool_use(tool_name, tool_params):
+    # Block mcp-ticketer tools
+    if tool_name.startswith("mcp__mcp-ticketer__"):
+        raise ViolationError(
+            "Circuit Breaker #6 VIOLATION: "
+            "PM cannot use mcp-ticketer tools directly. "
+            "MUST delegate to ticketing agent. "
+            f"Attempted: {tool_name}"
+        )
+
+    # Block ticket URL access
+    if tool_name == "WebFetch":
+        url = tool_params.get("url", "")
+        for forbidden in ["linear.app", "github.com", "jira"]:
+            if forbidden in url and ("issue" in url or "ticket" in url):
+                raise ViolationError(
+                    "Circuit Breaker #6 VIOLATION: "
+                    "PM cannot access ticket URLs directly. "
+                    "MUST delegate to ticketing agent. "
+                    f"URL: {url}"
+                )
+
+    # Block Bash commands for ticketing CLIs
+    if tool_name == "Bash":
+        command = tool_params.get("command", "")
+        if "aitrackdown" in command:
+            raise ViolationError(
+                "Circuit Breaker #6 VIOLATION: "
+                "PM cannot use aitrackdown CLI directly. "
+                "MUST delegate to ticketing agent. "
+                f"Command: {command}"
+            )
+```
+
+#### Tool Usage Detection Patterns
+
+**Ticket URL Detection** (triggers delegation):
+- `https://linear.app/*/issue/*` → Delegate to ticketing
+- `https://github.com/*/issues/*` → Delegate to ticketing
+- `https://*/jira/browse/*` → Delegate to ticketing
+- Any URL containing both "ticket" and platform name → Delegate to ticketing
 
 ### Why This Matters
 

claude_mpm/cli/__init__.py

@@ -91,7 +91,6 @@ def main(argv: Optional[list] = None):
         )
 
         try:
-            launch_progress.update(10)  # Start progress
             run_background_services()
             launch_progress.finish(message="Ready")
 

claude_mpm/cli/commands/__init__.py

@@ -19,6 +19,7 @@ from .info import show_info
 from .mcp import manage_mcp
 from .memory import manage_memory
 from .monitor import manage_monitor
+from .postmortem import run_postmortem
 from .run import run_session
 from .skills import manage_skills
 from .tickets import list_tickets, manage_tickets
@@ -41,6 +42,7 @@ __all__ = [
     # 'run_guarded_session',  # Excluded from default exports (experimental)
     "manage_tickets",
     "run_doctor",
+    "run_postmortem",
     "run_session",
     "show_info",
 ]

claude_mpm/cli/commands/agent_state_manager.py

@@ -169,18 +169,25 @@ class SimpleAgentManager:
                     # Normalize agent ID (remove -agent suffix if present, replace underscores)
                     normalized_id = agent_id.replace("-agent", "").replace("_", "-")
 
-                    agents.append(
-                        AgentConfig(
-                            name=normalized_id,
-                            description=(
-                                description[:80] + "..."
-                                if len(description) > 80
-                                else description
-                            ),
-                            dependencies=display_tools,
-                        )
+                    # Check if this agent is deployed
+                    is_deployed = self._is_agent_deployed(normalized_id)
+
+                    agent_config = AgentConfig(
+                        name=normalized_id,
+                        description=(
+                            description[:80] + "..."
+                            if len(description) > 80
+                            else description
+                        ),
+                        dependencies=display_tools,
                     )
 
+                    # Set deployment status
+                    agent_config.is_deployed = is_deployed
+                    agent_config.source_type = "local"
+
+                    agents.append(agent_config)
+
                 except (json.JSONDecodeError, KeyError) as e:
                     # Log malformed templates but continue
                     self.logger.debug(
@@ -256,7 +263,7 @@ class SimpleAgentManager:
             return []
 
     def _is_agent_deployed(self, agent_id: str) -> bool:
-        """Check if agent is deployed in current project or user directory.
+        """Check if agent is deployed (virtual deployment or physical files).
 
         Args:
             agent_id: Full agent ID (may include hierarchy like engineer/backend/python-engineer)
@@ -264,6 +271,46 @@ class SimpleAgentManager:
         Returns:
             True if agent is deployed, False otherwise
         """
+        # Check virtual deployment state (primary method)
+        deployment_state_paths = [
+            Path.cwd() / ".claude" / "agents" / ".mpm_deployment_state",
+            Path.home() / ".claude" / "agents" / ".mpm_deployment_state",
+        ]
+
+        for state_path in deployment_state_paths:
+            if state_path.exists():
+                try:
+                    with state_path.open() as f:
+                        state = json.load(f)
+
+                    # Check if agent is in deployment state
+                    agents = state.get("last_check_results", {}).get("agents", {})
+
+                    # Check full agent_id
+                    if agent_id in agents:
+                        self.logger.debug(
+                            f"Agent {agent_id} found in virtual deployment state"
+                        )
+                        return True
+
+                    # Check leaf name for hierarchical IDs
+                    if "/" in agent_id:
+                        leaf_name = agent_id.split("/")[-1]
+                        if leaf_name in agents:
+                            self.logger.debug(
+                                f"Agent {agent_id} (leaf: {leaf_name}) found in virtual deployment state"
+                            )
+                            return True
+                except (json.JSONDecodeError, KeyError) as e:
+                    self.logger.debug(
+                        f"Failed to read deployment state from {state_path}: {e}"
+                    )
+                    continue
+                except Exception as e:
+                    self.logger.debug(f"Unexpected error reading deployment state: {e}")
+                    continue
+
+        # Fallback to physical file checks (legacy support)
         # For hierarchical IDs, check both full ID and leaf name
         agent_file_names = [f"{agent_id}.md"]
 
@@ -278,6 +325,9 @@ class SimpleAgentManager:
             for agent_file_name in agent_file_names:
                 agent_file = project_agents_dir / agent_file_name
                 if agent_file.exists():
+                    self.logger.debug(
+                        f"Agent {agent_id} found as physical file: {agent_file}"
+                    )
                     return True
 
         # Check ~/.claude/agents/ directory (user level)
@@ -286,6 +336,9 @@ class SimpleAgentManager:
             for agent_file_name in agent_file_names:
                 agent_file = user_agents_dir / agent_file_name
                 if agent_file.exists():
+                    self.logger.debug(
+                        f"Agent {agent_id} found as physical file: {agent_file}"
+                    )
                     return True
 
         return False