[V2] Batch resume: Handle file conflicts from previous runs via orchestration escalation

[frankbria]

Problem

When retrying failed tasks or resuming a batch, individual coding agents fail with "File already exists" errors because previous runs created files that the agent's plan expects to create.

Current behavior: Agent fails immediately with executor error, no recovery attempted.

Expected behavior: Agent should escalate to orchestration layer which has context about:

• What files exist from previous runs
• Whether those files should be overwritten or edited instead of created
• The overall state of the workspace

Root Cause

The individual coding agents don't have awareness of the workspace state from previous runs. They generate plans assuming a clean slate. When they encounter existing files, they fail rather than adapting.

Proposed Solution

1. Orchestration-level handling: When an agent encounters "File already exists", it should escalate to the main orchestrator rather than failing outright.

2. Orchestrator context: The orchestrator should:

   • Track which files were created/modified by previous runs
   • Provide this context to agents on retry
   • Instruct agents to use "edit" operations instead of "create" for existing files

3. Tactical pattern: Add "File already exists" to the supervisor's tactical patterns so it can intervene and provide guidance.

Example Error

[DIAG] Agent FAILED - analyzing for supervisor intervention
[DIAG] Last step result: status=ExecutionStatus.FAILED, error=File already exists: src/task_tracker/exceptions.py
[DIAG] Matched tactical patterns: []  # <-- Should match a pattern here
[DIAG] No supervisor intervention - error_msg empty=False, no pattern match=True

Acceptance Criteria

• "File already exists" errors trigger supervisor intervention
• Supervisor provides agent with list of existing files from previous runs
• Agent adjusts plan to use edit operations for existing files
• Batch resume successfully continues where previous run left off

Labels

enhancement, agent-system, batch-execution

[traycerai]

Plan

Observations

The codebase currently has a blocker system for manual intervention but lacks a supervisor/tactical pattern system mentioned in the issue. The backend_worker_agent.py handles file operations in apply_file_changes() method, which doesn't check for existing files when action is "create". The frontend_worker_agent.py explicitly raises FileExistsError for existing components. The orchestration layer in lead_agent.py handles task retries but doesn't provide workspace state context to agents. The issue describes a feature that doesn't currently exist in the codebase.

Approach

Implement a three-layer solution: (1) Add tactical pattern detection system to identify "File already exists" errors at the orchestration level, (2) Enhance orchestration to track workspace state across runs and provide file existence context to agents on retry, (3) Modify agent execution to handle file conflicts by converting "create" operations to "edit" operations when files exist. This approach maintains separation of concerns while enabling intelligent recovery from file conflicts during batch resume scenarios.

Implementation Steps

1. Create Tactical Pattern Detection System

File: file:codeframe/agents/tactical_patterns.py (new file)

Create a new module to define and match tactical patterns for supervisor intervention:

• Define TacticalPattern dataclass with fields: pattern_id, error_pattern (regex), category, intervention_strategy
• Implement TacticalPatternMatcher class with method match_error(error_message: str) -> Optional[TacticalPattern]
• Add predefined patterns including:
  • "File already exists" pattern matching FileExistsError and similar messages
  • Pattern should suggest "convert_create_to_edit" intervention strategy
• Include pattern for "File not found" errors
• Make patterns extensible for future error types

2. Add Workspace State Tracking to Orchestration Layer

File: file:codeframe/agents/lead_agent.py

Enhance the LeadAgent class to track workspace state across task executions:

• Add _workspace_state dictionary attribute in __init__ to track files created/modified by task_id
• In _assign_and_execute_task() method (around line 2278), after successful task execution:
  • Query the database for files modified by the task (from git commits or task metadata)
  • Store in _workspace_state[task_id] = {"files_created": [...], "files_modified": [...]}
• Create new method get_workspace_context(task_id: int) -> Dict[str, Any] that returns:
  • List of all files created by previous runs
  • List of all files modified by previous runs
  • Aggregated from _workspace_state for all completed tasks

3. Implement Supervisor Intervention Logic

File: file:codeframe/agents/lead_agent.py

Add supervisor intervention when agents fail with tactical pattern matches:

• In _assign_and_execute_task() method, wrap the await agent_instance.execute_task(task_dict) call in try-except
• On exception, use TacticalPatternMatcher to check if error matches a known pattern
• If "File already exists" pattern matches:
  • Log diagnostic message: [DIAG] Agent FAILED - analyzing for supervisor intervention
  • Log matched pattern: [DIAG] Matched tactical patterns: ['file_already_exists']
  • Call new method _handle_file_conflict_intervention(task, error, pattern)
• If no pattern matches, log: [DIAG] No supervisor intervention - error_msg empty=False, no pattern match=True
• Re-raise exception to trigger normal retry logic

4. Create File Conflict Intervention Handler

File: file:codeframe/agents/lead_agent.py

Implement the intervention handler method:

• Create _handle_file_conflict_intervention(task: Task, error: Exception, pattern: TacticalPattern) -> None
• Extract conflicting file path from error message using regex
• Get workspace context via get_workspace_context(task.id)
• Check if conflicting file was created by a previous run of this task or a dependency
• Update task metadata in database with intervention context:
  • Add intervention_applied: true flag
  • Add existing_files: [list of files that exist]
  • Add instruction: "Use edit operations for existing files instead of create"
• Log intervention details for debugging

5. Modify Agent Task Execution to Handle Intervention Context

File: file:codeframe/agents/backend_worker_agent.py

Update execute_task() method to check for intervention context:

• At the start of execute_task() (around line 1004), check if task dict contains intervention_applied flag
• If intervention context exists:
  • Extract existing_files list from task metadata
  • Pass this context to build_context() method
  • Update system prompt to include: "The following files already exist from previous runs: [list]. Use 'modify' action instead of 'create' for these files."
• In apply_file_changes() method (around line 372):
  • Before processing each file, check if action is "create" and file exists
  • If file exists and intervention context indicates it's from previous run, automatically convert action to "modify"
  • Log the conversion: Converted create to modify for existing file: {path}

File: file:codeframe/agents/frontend_worker_agent.py

Update to handle file conflicts gracefully:

• In _create_component_files() method (around line 400), instead of raising FileExistsError:
  • Check if task has intervention context
  • If intervention applied, log warning and overwrite file (or skip creation)
  • If no intervention context, raise FileExistsError as before to trigger supervisor intervention

6. Enhance Task Retry Logic with Workspace Context

File: file:codeframe/agents/lead_agent.py

Modify the retry logic in _execute_coordination_loop():

• When resetting failed task to "pending" for retry (around line 2185), enrich task dict with workspace context:
  • Call get_workspace_context(task_id)
  • Add context to task updates in database
• Ensure workspace context is included when task is re-assigned to agent

7. Add Database Schema for Intervention Tracking

File: file:codeframe/persistence/database.py

Add support for storing intervention metadata:

• Add optional JSON column intervention_context to tasks table (via migration or ALTER TABLE)
• Create methods:
  • update_task_intervention_context(task_id: int, context: Dict[str, Any])
  • get_task_intervention_context(task_id: int) -> Optional[Dict[str, Any]]
• Store intervention details including: pattern matched, files affected, strategy applied

8. Add Diagnostic Logging

File: file:codeframe/agents/lead_agent.py

Add comprehensive diagnostic logging for debugging:

• Create logger with [DIAG] prefix for all supervisor intervention logs
• Log at key decision points:
  • When error is caught and analyzed
  • When pattern is matched or not matched
  • When intervention is applied
  • When task is retried with context
• Include relevant details: task_id, error message, matched pattern, intervention strategy

9. Update Task Model

File: file:codeframe/core/models.py

Extend the Task dataclass to support intervention context:

• Add optional field intervention_context: Optional[Dict[str, Any]] = None
• Update to_dict() method to include intervention_context
• Document the structure of intervention_context in docstring

10. Add Tests

File: file:tests/agents/test_tactical_patterns.py (new file)

Test the tactical pattern matching system:

• Test pattern matching for "File already exists" errors
• Test pattern matching for various error message formats
• Test no match for unrelated errors

File: file:tests/agents/test_lead_agent_intervention.py (new file)

Test supervisor intervention flow:

• Test that "File already exists" error triggers intervention
• Test workspace context is provided on retry
• Test task succeeds on retry with intervention context
• Test intervention is not applied for non-matching errors

File: file:tests/agents/test_backend_worker_intervention.py (new file)

Test agent handling of intervention context:

• Test agent converts "create" to "modify" when intervention context present
• Test agent uses existing files list from context
• Test agent succeeds when retrying with intervention

Architecture Diagram

sequenceDiagram
    participant O as Orchestrator (LeadAgent)
    participant TPM as TacticalPatternMatcher
    participant A as Agent (BackendWorker)
    participant FS as File System
    participant DB as Database

    Note over O,DB: Initial Task Execution
    O->>A: execute_task(task)
    A->>FS: create file X
    FS-->>A: FileExistsError
    A-->>O: Exception: File already exists

    Note over O,TPM: Supervisor Intervention
    O->>TPM: match_error(error_message)
    TPM-->>O: Pattern: file_already_exists
    O->>O: [DIAG] Matched tactical patterns
    O->>O: get_workspace_context(task_id)
    O->>DB: update_task_intervention_context()
    
    Note over O,A: Retry with Context
    O->>A: execute_task(task + intervention_context)
    A->>A: Check intervention_context
    A->>A: Convert "create" → "modify" for file X
    A->>FS: modify file X
    FS-->>A: Success
    A-->>O: Task completed
    O->>DB: mark task completed

Loading

Key Design Decisions

1. Separation of Concerns: Tactical pattern matching is isolated in its own module, making it easy to extend with new patterns without modifying orchestration logic

2. Workspace State Tracking: Orchestrator maintains workspace state rather than agents, as orchestrator has visibility across all tasks and runs

3. Graceful Degradation: If intervention fails or pattern doesn't match, system falls back to existing retry logic

4. Backward Compatibility: Intervention context is optional, so existing tasks without context continue to work

5. Diagnostic Logging: Explicit [DIAG] prefix makes it easy to filter and debug supervisor intervention behavior

6. Database-Driven: Intervention context stored in database ensures it persists across process restarts and is available to any agent instance

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has a blocker system for manual intervention but lacks a supervisor/tactical pattern system mentioned in the issue. The `backend_worker_agent.py` handles file operations in `apply_file_changes()` method, which doesn't check for existing files when action is "create". The `frontend_worker_agent.py` explicitly raises `FileExistsError` for existing components. The orchestration layer in `lead_agent.py` handles task retries but doesn't provide workspace state context to agents. The issue describes a feature that doesn't currently exist in the codebase.

## Approach

Implement a three-layer solution: (1) Add tactical pattern detection system to identify "File already exists" errors at the orchestration level, (2) Enhance orchestration to track workspace state across runs and provide file existence context to agents on retry, (3) Modify agent execution to handle file conflicts by converting "create" operations to "edit" operations when files exist. This approach maintains separation of concerns while enabling intelligent recovery from file conflicts during batch resume scenarios.

## Implementation Steps

### 1. Create Tactical Pattern Detection System

**File: `file:codeframe/agents/tactical_patterns.py` (new file)**

Create a new module to define and match tactical patterns for supervisor intervention:

- Define `TacticalPattern` dataclass with fields: `pattern_id`, `error_pattern` (regex), `category`, `intervention_strategy`
- Implement `TacticalPatternMatcher` class with method `match_error(error_message: str) -> Optional[TacticalPattern]`
- Add predefined patterns including:
  - "File already exists" pattern matching `FileExistsError` and similar messages
  - Pattern should suggest "convert_create_to_edit" intervention strategy
- Include pattern for "File not found" errors
- Make patterns extensible for future error types

### 2. Add Workspace State Tracking to Orchestration Layer

**File: `file:codeframe/agents/lead_agent.py`**

Enhance the `LeadAgent` class to track workspace state across task executions:

- Add `_workspace_state` dictionary attribute in `__init__` to track files created/modified by task_id
- In `_assign_and_execute_task()` method (around line 2278), after successful task execution:
  - Query the database for files modified by the task (from git commits or task metadata)
  - Store in `_workspace_state[task_id] = {"files_created": [...], "files_modified": [...]}`
- Create new method `get_workspace_context(task_id: int) -> Dict[str, Any]` that returns:
  - List of all files created by previous runs
  - List of all files modified by previous runs
  - Aggregated from `_workspace_state` for all completed tasks

### 3. Implement Supervisor Intervention Logic

**File: `file:codeframe/agents/lead_agent.py`**

Add supervisor intervention when agents fail with tactical pattern matches:

- In `_assign_and_execute_task()` method, wrap the `await agent_instance.execute_task(task_dict)` call in try-except
- On exception, use `TacticalPatternMatcher` to check if error matches a known pattern
- If "File already exists" pattern matches:
  - Log diagnostic message: `[DIAG] Agent FAILED - analyzing for supervisor intervention`
  - Log matched pattern: `[DIAG] Matched tactical patterns: ['file_already_exists']`
  - Call new method `_handle_file_conflict_intervention(task, error, pattern)`
- If no pattern matches, log: `[DIAG] No supervisor intervention - error_msg empty=False, no pattern match=True`
- Re-raise exception to trigger normal retry logic

### 4. Create File Conflict Intervention Handler

**File: `file:codeframe/agents/lead_agent.py`**

Implement the intervention handler method:

- Create `_handle_file_conflict_intervention(task: Task, error: Exception, pattern: TacticalPattern) -> None`
- Extract conflicting file path from error message using regex
- Get workspace context via `get_workspace_context(task.id)`
- Check if conflicting file was created by a previous run of this task or a dependency
- Update task metadata in database with intervention context:
  - Add `intervention_applied: true` flag
  - Add `existing_files: [list of files that exist]` 
  - Add `instruction: "Use edit operations for existing files instead of create"`
- Log intervention details for debugging

### 5. Modify Agent Task Execution to Handle Intervention Context

**File: `file:codeframe/agents/backend_worker_agent.py`**

Update `execute_task()` method to check for intervention context:

- At the start of `execute_task()` (around line 1004), check if task dict contains `intervention_applied` flag
- If intervention context exists:
  - Extract `existing_files` list from task metadata
  - Pass this context to `build_context()` method
  - Update system prompt to include: "The following files already exist from previous runs: [list]. Use 'modify' action instead of 'create' for these files."
- In `apply_file_changes()` method (around line 372):
  - Before processing each file, check if action is "create" and file exists
  - If file exists and intervention context indicates it's from previous run, automatically convert action to "modify"
  - Log the conversion: `Converted create to modify for existing file: {path}`

**File: `file:codeframe/agents/frontend_worker_agent.py`**

Update to handle file conflicts gracefully:

- In `_create_component_files()` method (around line 400), instead of raising `FileExistsError`:
  - Check if task has intervention context
  - If intervention applied, log warning and overwrite file (or skip creation)
  - If no intervention context, raise `FileExistsError` as before to trigger supervisor intervention

### 6. Enhance Task Retry Logic with Workspace Context

**File: `file:codeframe/agents/lead_agent.py`**

Modify the retry logic in `_execute_coordination_loop()`:

- When resetting failed task to "pending" for retry (around line 2185), enrich task dict with workspace context:
  - Call `get_workspace_context(task_id)` 
  - Add context to task updates in database
- Ensure workspace context is included when task is re-assigned to agent

### 7. Add Database Schema for Intervention Tracking

**File: `file:codeframe/persistence/database.py`**

Add support for storing intervention metadata:

- Add optional JSON column `intervention_context` to tasks table (via migration or ALTER TABLE)
- Create methods:
  - `update_task_intervention_context(task_id: int, context: Dict[str, Any])`
  - `get_task_intervention_context(task_id: int) -> Optional[Dict[str, Any]]`
- Store intervention details including: pattern matched, files affected, strategy applied

### 8. Add Diagnostic Logging

**File: `file:codeframe/agents/lead_agent.py`**

Add comprehensive diagnostic logging for debugging:

- Create logger with `[DIAG]` prefix for all supervisor intervention logs
- Log at key decision points:
  - When error is caught and analyzed
  - When pattern is matched or not matched
  - When intervention is applied
  - When task is retried with context
- Include relevant details: task_id, error message, matched pattern, intervention strategy

### 9. Update Task Model

**File: `file:codeframe/core/models.py`**

Extend the `Task` dataclass to support intervention context:

- Add optional field `intervention_context: Optional[Dict[str, Any]] = None`
- Update `to_dict()` method to include intervention_context
- Document the structure of intervention_context in docstring

### 10. Add Tests

**File: `file:tests/agents/test_tactical_patterns.py` (new file)**

Test the tactical pattern matching system:

- Test pattern matching for "File already exists" errors
- Test pattern matching for various error message formats
- Test no match for unrelated errors

**File: `file:tests/agents/test_lead_agent_intervention.py` (new file)**

Test supervisor intervention flow:

- Test that "File already exists" error triggers intervention
- Test workspace context is provided on retry
- Test task succeeds on retry with intervention context
- Test intervention is not applied for non-matching errors

**File: `file:tests/agents/test_backend_worker_intervention.py` (new file)**

Test agent handling of intervention context:

- Test agent converts "create" to "modify" when intervention context present
- Test agent uses existing files list from context
- Test agent succeeds when retrying with intervention

## Architecture Diagram

```mermaid
sequenceDiagram
    participant O as Orchestrator (LeadAgent)
    participant TPM as TacticalPatternMatcher
    participant A as Agent (BackendWorker)
    participant FS as File System
    participant DB as Database

    Note over O,DB: Initial Task Execution
    O->>A: execute_task(task)
    A->>FS: create file X
    FS-->>A: FileExistsError
    A-->>O: Exception: File already exists

    Note over O,TPM: Supervisor Intervention
    O->>TPM: match_error(error_message)
    TPM-->>O: Pattern: file_already_exists
    O->>O: [DIAG] Matched tactical patterns
    O->>O: get_workspace_context(task_id)
    O->>DB: update_task_intervention_context()
    
    Note over O,A: Retry with Context
    O->>A: execute_task(task + intervention_context)
    A->>A: Check intervention_context
    A->>A: Convert "create" → "modify" for file X
    A->>FS: modify file X
    FS-->>A: Success
    A-->>O: Task completed
    O->>DB: mark task completed
```

## Key Design Decisions

1. **Separation of Concerns**: Tactical pattern matching is isolated in its own module, making it easy to extend with new patterns without modifying orchestration logic

2. **Workspace State Tracking**: Orchestrator maintains workspace state rather than agents, as orchestrator has visibility across all tasks and runs

3. **Graceful Degradation**: If intervention fails or pattern doesn't match, system falls back to existing retry logic

4. **Backward Compatibility**: Intervention context is optional, so existing tasks without context continue to work

5. **Diagnostic Logging**: Explicit `[DIAG]` prefix makes it easy to filter and debug supervisor intervention behavior

6. **Database-Driven**: Intervention context stored in database ensures it persists across process restarts and is available to any agent instance

---

Execution Information

Branch: main
Commit: 589ae17

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.