[P0] Tasks not displayed and agents not assigned after approval (Development Phase)

[frankbria]

Bug Report

Summary

After successfully approving tasks and transitioning to Development Phase, tasks are not displayed in the Tasks tab and no agents are assigned.

Steps to Reproduce

1. Complete Discovery phase (5 questions answered)
2. Wait for PRD generation
3. Go to Tasks Review tab (shows 16 tasks)
4. Click "Approve and Start Development"
5. Phase transitions to "Development Phase" ✅
6. Check Tasks tab and Multi-Agent Team section

Expected Behavior

• Tasks tab should show 16 tasks (same tasks that were approved)
• Agents should be automatically created and assigned to tasks
• Development work should begin

Actual Behavior

• Tasks tab shows 0/0 instead of 16 tasks
• Progress section shows 0 / 16 tasks (tasks exist but not displayed)
• Multi-Agent Team shows "No Agents Assigned"
• Message: "Agents will be created automatically when tasks are assigned"
• No recent activity logged

Screenshots

• Development Phase reached (Step 1 of 15, 7%)
• Status: RUNNING, Connected
• Blockers: None

Environment

• URL: https://dev.codeframeapp.com
• Project: test-weather-app
• Date: January 10, 2026

Notes

• Bug 016-2: Backend Automation - Planning Trigger + Task Approval #199 (approval 422/400 error) appears to be FIXED ✅
• This may be a follow-on bug in the approval → agent assignment flow
• Tasks were visible (16 total: 8 Core Features + 8 Non-Functional) before approval

Related Issues

• 016-2: Backend Automation - Planning Trigger + Task Approval #199 (Task approval failure) - NOW FIXED

[traycerai]

Plan

Observations

The bug occurs because the task approval flow (file:codeframe/ui/routers/tasks.py approve_tasks endpoint) successfully transitions the project phase to "active" and broadcasts a development_started event, but never initiates the multi-agent execution loop. The LeadAgent.start_multi_agent_execution() method exists and is responsible for creating agents, assigning tasks, and executing them, but it's never called after task approval. The frontend displays "0/0 tasks" and "No Agents Assigned" because the WebSocket-based agent state (used by TaskList and AgentList components) remains empty without active agent execution.

Approach

The fix requires adding a background task to the task approval endpoint that starts the multi-agent execution after successful phase transition. This follows the existing pattern used in file:codeframe/ui/routers/agents.py where start_agent is called as a background task. The solution involves: (1) creating a new async function to start multi-agent execution, (2) adding it as a background task in the approval endpoint, (3) ensuring proper error handling and WebSocket broadcasts for execution status, and (4) handling the LeadAgent lifecycle properly by storing it in running_agents dictionary.

Implementation Steps

1. Create Multi-Agent Execution Starter Function

File: file:codeframe/ui/shared.py

Add a new async function start_multi_agent_execution after the existing start_agent function (around line 413):

async def start_multi_agent_execution(
    project_id: int, 
    db: Database, 
    agents_dict: Dict[int, LeadAgent], 
    api_key: str
) -> None:
    """Start multi-agent execution for approved tasks.
    
    This function:
    - Gets or creates LeadAgent instance
    - Calls start_multi_agent_execution() to begin task execution
    - Broadcasts execution status via WebSocket
    - Handles errors gracefully with appropriate broadcasts
    
    Args:
        project_id: Project ID to start execution for
        db: Database connection
        agents_dict: Dictionary to store running agents
        api_key: Anthropic API key for agents
    """

Implementation details:

• Check if LeadAgent already exists in running_agents (reuse if available)
• If not, create new LeadAgent instance with project_id, db, and api_key
• Store agent in both shared_state._running_agents and agents_dict (thread-safe with lock)
• Call agent.start_multi_agent_execution() with appropriate parameters (max_retries=3, max_concurrent=5)
• Wrap execution in try-except to handle errors
• Broadcast agent_execution_started message before execution
• Broadcast agent_execution_completed or agent_execution_failed after execution
• Use asyncio.to_thread() for blocking operations to avoid blocking the event loop

2. Update Task Approval Endpoint

File: file:codeframe/ui/routers/tasks.py

Modify the approve_tasks function signature to include BackgroundTasks:

@project_router.post("/{project_id}/tasks/approve")
async def approve_tasks(
    project_id: int,
    request: TaskApprovalRequest,
    background_tasks: BackgroundTasks,  # ADD THIS
    db: Database = Depends(get_db),
    current_user: User = Depends(get_current_user),
) -> TaskApprovalResponse:

After the broadcast_development_started call (around line 231), add:

# Start multi-agent execution in background
api_key = os.environ.get("ANTHROPIC_API_KEY")
if api_key:
    background_tasks.add_task(
        start_multi_agent_execution,
        project_id,
        db,
        running_agents,
        api_key
    )
    logger.info(f"Scheduled multi-agent execution for project {project_id}")
else:
    logger.warning(f"ANTHROPIC_API_KEY not set - cannot start multi-agent execution for project {project_id}")

Import additions needed:

• Add BackgroundTasks to FastAPI imports
• Add start_multi_agent_execution to imports from codeframe.ui.shared
• Add running_agents to imports from codeframe.ui.shared
• Add os import for environment variable access

3. Add WebSocket Broadcast Functions

File: file:codeframe/ui/websocket_broadcasts.py

Add new broadcast functions after broadcast_development_started (around line 979):

async def broadcast_agent_execution_started(
    manager, project_id: int, total_tasks: int
) -> None:
    """Broadcast when multi-agent execution begins."""
    
async def broadcast_agent_execution_completed(
    manager, project_id: int, summary: Dict[str, Any]
) -> None:
    """Broadcast when multi-agent execution completes."""
    
async def broadcast_agent_execution_failed(
    manager, project_id: int, error: str
) -> None:
    """Broadcast when multi-agent execution fails."""

Message format:

• agent_execution_started: Include project_id, total_tasks, timestamp
• agent_execution_completed: Include project_id, completed, failed, retries, execution_time, timestamp
• agent_execution_failed: Include project_id, error, timestamp

4. Update Frontend WebSocket Handler

File: file:web-ui/src/lib/websocketMessageMapper.ts

Add handlers for new message types in the message mapper:

case 'agent_execution_started':
  // Handle execution start - could show loading indicator
  
case 'agent_execution_completed':
  // Handle execution completion - refresh task/agent state
  
case 'agent_execution_failed':
  // Handle execution failure - show error message

5. Handle Edge Cases

Considerations:

a) Idempotency: Check if execution is already running before starting

• In start_multi_agent_execution, check if agent exists and is already executing
• Return early if execution is in progress

b) Error Recovery: If execution fails, ensure proper cleanup

• Remove agent from running_agents on critical failure
• Update project status appropriately
• Broadcast error to frontend

c) Concurrent Approvals: Prevent race conditions

• Use shared_state._agents_lock when checking/creating agents
• Ensure atomic operations for agent lifecycle

d) API Key Validation: Handle missing API key gracefully

• Check for ANTHROPIC_API_KEY before scheduling background task
• Log warning and return appropriate response if missing

6. Update Tests

File: file:tests/ui/test_task_approval.py

Add new test case:

@pytest.mark.asyncio
async def test_approve_tasks_starts_multi_agent_execution(
    self, mock_db, mock_user
):
    """Test that multi-agent execution is started after approval."""

Test assertions:

• Verify background_tasks.add_task is called with start_multi_agent_execution
• Verify correct parameters are passed (project_id, db, running_agents, api_key)
• Mock start_multi_agent_execution and verify it's called
• Verify appropriate WebSocket broadcasts are sent

7. Documentation Updates

File: file:CHANGELOG.md

Add entry under bug fixes:

### Fixed
- [P0] Tasks and agents now display correctly after approval - multi-agent execution starts automatically when transitioning to Development Phase (#242)

Sequence Diagram

sequenceDiagram
    participant User
    participant Frontend
    participant TasksAPI as Tasks API
    participant BackgroundTask
    participant LeadAgent
    participant Database
    participant WebSocket

    User->>Frontend: Click "Approve and Start Development"
    Frontend->>TasksAPI: POST /api/projects/{id}/tasks/approve
    TasksAPI->>Database: Transition phase to "active"
    TasksAPI->>Database: Update tasks to "pending"
    TasksAPI->>WebSocket: broadcast_development_started
    TasksAPI->>BackgroundTask: Schedule start_multi_agent_execution
    TasksAPI-->>Frontend: 200 OK (approval success)
    
    BackgroundTask->>LeadAgent: Create/Get LeadAgent instance
    BackgroundTask->>Database: Store agent in running_agents
    BackgroundTask->>WebSocket: broadcast_agent_execution_started
    BackgroundTask->>LeadAgent: start_multi_agent_execution()
    
    loop For each task
        LeadAgent->>LeadAgent: Assign task to agent
        LeadAgent->>WebSocket: broadcast_agent_created
        LeadAgent->>WebSocket: broadcast_task_assigned
        LeadAgent->>Database: Update task status
        LeadAgent->>WebSocket: broadcast_task_status_changed
    end
    
    LeadAgent-->>BackgroundTask: Execution summary
    BackgroundTask->>WebSocket: broadcast_agent_execution_completed
    Frontend->>Frontend: Update UI (tasks & agents visible)

Loading

Files to Modify

1. file:codeframe/ui/shared.py - Add start_multi_agent_execution function
2. file:codeframe/ui/routers/tasks.py - Add BackgroundTasks parameter and schedule execution
3. file:codeframe/ui/websocket_broadcasts.py - Add execution status broadcast functions
4. file:web-ui/src/lib/websocketMessageMapper.ts - Add handlers for new message types
5. file:tests/ui/test_task_approval.py - Add test for execution startup
6. file:CHANGELOG.md - Document the fix

Risk Mitigation

• Backward Compatibility: The change is additive - existing functionality remains unchanged
• Performance: Background task execution prevents blocking the approval response
• Error Handling: Comprehensive try-except blocks with appropriate logging and broadcasts
• Testing: New test coverage ensures the fix works correctly
• Monitoring: WebSocket broadcasts provide visibility into execution status

Import In IDE

🤖 Prompt for AI Agents

## Observations

The bug occurs because the task approval flow (`file:codeframe/ui/routers/tasks.py` `approve_tasks` endpoint) successfully transitions the project phase to "active" and broadcasts a `development_started` event, but **never initiates the multi-agent execution loop**. The `LeadAgent.start_multi_agent_execution()` method exists and is responsible for creating agents, assigning tasks, and executing them, but it's never called after task approval. The frontend displays "0/0 tasks" and "No Agents Assigned" because the WebSocket-based agent state (used by `TaskList` and `AgentList` components) remains empty without active agent execution.

## Approach

The fix requires adding a background task to the task approval endpoint that starts the multi-agent execution after successful phase transition. This follows the existing pattern used in `file:codeframe/ui/routers/agents.py` where `start_agent` is called as a background task. The solution involves: (1) creating a new async function to start multi-agent execution, (2) adding it as a background task in the approval endpoint, (3) ensuring proper error handling and WebSocket broadcasts for execution status, and (4) handling the LeadAgent lifecycle properly by storing it in `running_agents` dictionary.

## Implementation Steps

### 1. Create Multi-Agent Execution Starter Function

**File:** `file:codeframe/ui/shared.py`

Add a new async function `start_multi_agent_execution` after the existing `start_agent` function (around line 413):

```python
async def start_multi_agent_execution(
    project_id: int, 
    db: Database, 
    agents_dict: Dict[int, LeadAgent], 
    api_key: str
) -> None:
    """Start multi-agent execution for approved tasks.
    
    This function:
    - Gets or creates LeadAgent instance
    - Calls start_multi_agent_execution() to begin task execution
    - Broadcasts execution status via WebSocket
    - Handles errors gracefully with appropriate broadcasts
    
    Args:
        project_id: Project ID to start execution for
        db: Database connection
        agents_dict: Dictionary to store running agents
        api_key: Anthropic API key for agents
    """
```

**Implementation details:**
- Check if LeadAgent already exists in `running_agents` (reuse if available)
- If not, create new LeadAgent instance with project_id, db, and api_key
- Store agent in both `shared_state._running_agents` and `agents_dict` (thread-safe with lock)
- Call `agent.start_multi_agent_execution()` with appropriate parameters (max_retries=3, max_concurrent=5)
- Wrap execution in try-except to handle errors
- Broadcast `agent_execution_started` message before execution
- Broadcast `agent_execution_completed` or `agent_execution_failed` after execution
- Use `asyncio.to_thread()` for blocking operations to avoid blocking the event loop

### 2. Update Task Approval Endpoint

**File:** `file:codeframe/ui/routers/tasks.py`

Modify the `approve_tasks` function signature to include `BackgroundTasks`:

```python
@project_router.post("/{project_id}/tasks/approve")
async def approve_tasks(
    project_id: int,
    request: TaskApprovalRequest,
    background_tasks: BackgroundTasks,  # ADD THIS
    db: Database = Depends(get_db),
    current_user: User = Depends(get_current_user),
) -> TaskApprovalResponse:
```

After the `broadcast_development_started` call (around line 231), add:

```python
# Start multi-agent execution in background
api_key = os.environ.get("ANTHROPIC_API_KEY")
if api_key:
    background_tasks.add_task(
        start_multi_agent_execution,
        project_id,
        db,
        running_agents,
        api_key
    )
    logger.info(f"Scheduled multi-agent execution for project {project_id}")
else:
    logger.warning(f"ANTHROPIC_API_KEY not set - cannot start multi-agent execution for project {project_id}")
```

**Import additions needed:**
- Add `BackgroundTasks` to FastAPI imports
- Add `start_multi_agent_execution` to imports from `codeframe.ui.shared`
- Add `running_agents` to imports from `codeframe.ui.shared`
- Add `os` import for environment variable access

### 3. Add WebSocket Broadcast Functions

**File:** `file:codeframe/ui/websocket_broadcasts.py`

Add new broadcast functions after `broadcast_development_started` (around line 979):

```python
async def broadcast_agent_execution_started(
    manager, project_id: int, total_tasks: int
) -> None:
    """Broadcast when multi-agent execution begins."""
    
async def broadcast_agent_execution_completed(
    manager, project_id: int, summary: Dict[str, Any]
) -> None:
    """Broadcast when multi-agent execution completes."""
    
async def broadcast_agent_execution_failed(
    manager, project_id: int, error: str
) -> None:
    """Broadcast when multi-agent execution fails."""
```

**Message format:**
- `agent_execution_started`: Include project_id, total_tasks, timestamp
- `agent_execution_completed`: Include project_id, completed, failed, retries, execution_time, timestamp
- `agent_execution_failed`: Include project_id, error, timestamp

### 4. Update Frontend WebSocket Handler

**File:** `file:web-ui/src/lib/websocketMessageMapper.ts`

Add handlers for new message types in the message mapper:

```typescript
case 'agent_execution_started':
  // Handle execution start - could show loading indicator
  
case 'agent_execution_completed':
  // Handle execution completion - refresh task/agent state
  
case 'agent_execution_failed':
  // Handle execution failure - show error message
```

### 5. Handle Edge Cases

**Considerations:**

a) **Idempotency:** Check if execution is already running before starting
   - In `start_multi_agent_execution`, check if agent exists and is already executing
   - Return early if execution is in progress

b) **Error Recovery:** If execution fails, ensure proper cleanup
   - Remove agent from `running_agents` on critical failure
   - Update project status appropriately
   - Broadcast error to frontend

c) **Concurrent Approvals:** Prevent race conditions
   - Use `shared_state._agents_lock` when checking/creating agents
   - Ensure atomic operations for agent lifecycle

d) **API Key Validation:** Handle missing API key gracefully
   - Check for ANTHROPIC_API_KEY before scheduling background task
   - Log warning and return appropriate response if missing

### 6. Update Tests

**File:** `file:tests/ui/test_task_approval.py`

Add new test case:

```python
@pytest.mark.asyncio
async def test_approve_tasks_starts_multi_agent_execution(
    self, mock_db, mock_user
):
    """Test that multi-agent execution is started after approval."""
```

**Test assertions:**
- Verify `background_tasks.add_task` is called with `start_multi_agent_execution`
- Verify correct parameters are passed (project_id, db, running_agents, api_key)
- Mock `start_multi_agent_execution` and verify it's called
- Verify appropriate WebSocket broadcasts are sent

### 7. Documentation Updates

**File:** `file:CHANGELOG.md`

Add entry under bug fixes:
```markdown
### Fixed
- [P0] Tasks and agents now display correctly after approval - multi-agent execution starts automatically when transitioning to Development Phase (#242)
```

## Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant TasksAPI as Tasks API
    participant BackgroundTask
    participant LeadAgent
    participant Database
    participant WebSocket

    User->>Frontend: Click "Approve and Start Development"
    Frontend->>TasksAPI: POST /api/projects/{id}/tasks/approve
    TasksAPI->>Database: Transition phase to "active"
    TasksAPI->>Database: Update tasks to "pending"
    TasksAPI->>WebSocket: broadcast_development_started
    TasksAPI->>BackgroundTask: Schedule start_multi_agent_execution
    TasksAPI-->>Frontend: 200 OK (approval success)
    
    BackgroundTask->>LeadAgent: Create/Get LeadAgent instance
    BackgroundTask->>Database: Store agent in running_agents
    BackgroundTask->>WebSocket: broadcast_agent_execution_started
    BackgroundTask->>LeadAgent: start_multi_agent_execution()
    
    loop For each task
        LeadAgent->>LeadAgent: Assign task to agent
        LeadAgent->>WebSocket: broadcast_agent_created
        LeadAgent->>WebSocket: broadcast_task_assigned
        LeadAgent->>Database: Update task status
        LeadAgent->>WebSocket: broadcast_task_status_changed
    end
    
    LeadAgent-->>BackgroundTask: Execution summary
    BackgroundTask->>WebSocket: broadcast_agent_execution_completed
    Frontend->>Frontend: Update UI (tasks & agents visible)
```

## Files to Modify

1. `file:codeframe/ui/shared.py` - Add `start_multi_agent_execution` function
2. `file:codeframe/ui/routers/tasks.py` - Add BackgroundTasks parameter and schedule execution
3. `file:codeframe/ui/websocket_broadcasts.py` - Add execution status broadcast functions
4. `file:web-ui/src/lib/websocketMessageMapper.ts` - Add handlers for new message types
5. `file:tests/ui/test_task_approval.py` - Add test for execution startup
6. `file:CHANGELOG.md` - Document the fix

## Risk Mitigation

- **Backward Compatibility:** The change is additive - existing functionality remains unchanged
- **Performance:** Background task execution prevents blocking the approval response
- **Error Handling:** Comprehensive try-except blocks with appropriate logging and broadcasts
- **Testing:** New test coverage ensures the fix works correctly
- **Monitoring:** WebSocket broadcasts provide visibility into execution status

---

Execution Information

Branch: main
Commit: 7b8257d

---

💡 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.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

⚠️ Possible Duplicate Issue

• [P0] Tasks do not display on the Task tab on project page #233

🔗 Related PRs

#205 - feat(planning): Add planning phase automation and task approval [merged]
#213 - feat(planning): Add Generate Task Breakdown button to DiscoveryProgress [merged]
#214 - feat(planning): Add TaskReview component for task approval workflow [merged]
#215 - feat(dashboard): Add phase-aware task view integration (#16-6) [merged]
#234 - fix(ui): make TaskStats phase-aware to fix late-joining user bug [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[frankbria]

Related to #231 - This bug should have been caught by E2E tests, but wasn't due to the test assertion issues described there.

Once #231 is fixed (proper positive assertions), tests should catch this type of state reconciliation bug automatically.

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

New Plan

Observations

The bug occurs because the task approval flow (file:codeframe/ui/routers/tasks.py approve_tasks endpoint) successfully transitions the project phase to "active" and broadcasts a development_started event, but never initiates the multi-agent execution loop. The LeadAgent.start_multi_agent_execution() method exists and is responsible for creating agents, assigning tasks, and executing them, but it's never called after task approval. The frontend displays "0/0 tasks" and "No Agents Assigned" because the WebSocket-based agent state (used by TaskList and AgentList components) remains empty without active agent execution.

Approach

The fix requires adding a background task to the task approval endpoint that starts the multi-agent execution after successful phase transition. This follows the existing pattern used in file:codeframe/ui/routers/agents.py where start_agent is called as a background task. The solution involves: (1) creating a new async function to start multi-agent execution, (2) adding it as a background task in the approval endpoint, (3) ensuring proper error handling and WebSocket broadcasts for execution status, and (4) handling the LeadAgent lifecycle properly by storing it in running_agents dictionary.

Implementation Steps

1. Create Multi-Agent Execution Starter Function

File: file:codeframe/ui/shared.py

Add a new async function start_multi_agent_execution after the existing start_agent function (around line 413):

async def start_multi_agent_execution(
    project_id: int, 
    db: Database, 
    agents_dict: Dict[int, LeadAgent], 
    api_key: str
) -> None:
    """Start multi-agent execution for approved tasks.
    
    This function:
    - Gets or creates LeadAgent instance
    - Calls start_multi_agent_execution() to begin task execution
    - Broadcasts execution status via WebSocket
    - Handles errors gracefully with appropriate broadcasts
    
    Args:
        project_id: Project ID to start execution for
        db: Database connection
        agents_dict: Dictionary to store running agents
        api_key: Anthropic API key for agents
    """

Implementation details:

• Check if LeadAgent already exists in running_agents (reuse if available)
• If not, create new LeadAgent instance with project_id, db, and api_key
• Store agent in both shared_state._running_agents and agents_dict (thread-safe with lock)
• Call agent.start_multi_agent_execution() with appropriate parameters (max_retries=3, max_concurrent=5)
• Wrap execution in try-except to handle errors
• Broadcast agent_execution_started message before execution
• Broadcast agent_execution_completed or agent_execution_failed after execution
• Use asyncio.to_thread() for blocking operations to avoid blocking the event loop

2. Update Task Approval Endpoint

File: file:codeframe/ui/routers/tasks.py

Modify the approve_tasks function signature to include BackgroundTasks:

@project_router.post("/{project_id}/tasks/approve")
async def approve_tasks(
    project_id: int,
    request: TaskApprovalRequest,
    background_tasks: BackgroundTasks,  # ADD THIS
    db: Database = Depends(get_db),
    current_user: User = Depends(get_current_user),
) -> TaskApprovalResponse:

After the broadcast_development_started call (around line 231), add:

# Start multi-agent execution in background
api_key = os.environ.get("ANTHROPIC_API_KEY")
if api_key:
    background_tasks.add_task(
        start_multi_agent_execution,
        project_id,
        db,
        running_agents,
        api_key
    )
    logger.info(f"Scheduled multi-agent execution for project {project_id}")
else:
    logger.warning(f"ANTHROPIC_API_KEY not set - cannot start multi-agent execution for project {project_id}")

Import additions needed:

• Add BackgroundTasks to FastAPI imports
• Add start_multi_agent_execution to imports from codeframe.ui.shared
• Add running_agents to imports from codeframe.ui.shared
• Add os import for environment variable access

3. Add WebSocket Broadcast Functions

File: file:codeframe/ui/websocket_broadcasts.py

Add new broadcast functions after broadcast_development_started (around line 979):

async def broadcast_agent_execution_started(
    manager, project_id: int, total_tasks: int
) -> None:
    """Broadcast when multi-agent execution begins."""
    
async def broadcast_agent_execution_completed(
    manager, project_id: int, summary: Dict[str, Any]
) -> None:
    """Broadcast when multi-agent execution completes."""
    
async def broadcast_agent_execution_failed(
    manager, project_id: int, error: str
) -> None:
    """Broadcast when multi-agent execution fails."""

Message format:

• agent_execution_started: Include project_id, total_tasks, timestamp
• agent_execution_completed: Include project_id, completed, failed, retries, execution_time, timestamp
• agent_execution_failed: Include project_id, error, timestamp

4. Update Frontend WebSocket Handler

File: file:web-ui/src/lib/websocketMessageMapper.ts

Add handlers for new message types in the message mapper:

case 'agent_execution_started':
  // Handle execution start - could show loading indicator
  
case 'agent_execution_completed':
  // Handle execution completion - refresh task/agent state
  
case 'agent_execution_failed':
  // Handle execution failure - show error message

5. Handle Edge Cases

Considerations:

a) Idempotency: Check if execution is already running before starting

• In start_multi_agent_execution, check if agent exists and is already executing
• Return early if execution is in progress

b) Error Recovery: If execution fails, ensure proper cleanup

• Remove agent from running_agents on critical failure
• Update project status appropriately
• Broadcast error to frontend

c) Concurrent Approvals: Prevent race conditions

• Use shared_state._agents_lock when checking/creating agents
• Ensure atomic operations for agent lifecycle

d) API Key Validation: Handle missing API key gracefully

• Check for ANTHROPIC_API_KEY before scheduling background task
• Log warning and return appropriate response if missing

6. Update Tests

File: file:tests/ui/test_task_approval.py

Add new test case:

@pytest.mark.asyncio
async def test_approve_tasks_starts_multi_agent_execution(
    self, mock_db, mock_user
):
    """Test that multi-agent execution is started after approval."""

Test assertions:

• Verify background_tasks.add_task is called with start_multi_agent_execution
• Verify correct parameters are passed (project_id, db, running_agents, api_key)
• Mock start_multi_agent_execution and verify it's called
• Verify appropriate WebSocket broadcasts are sent

7. Documentation Updates

File: file:CHANGELOG.md

Add entry under bug fixes:

### Fixed
- [P0] Tasks and agents now display correctly after approval - multi-agent execution starts automatically when transitioning to Development Phase (#242)

Sequence Diagram

sequenceDiagram
    participant User
    participant Frontend
    participant TasksAPI as Tasks API
    participant BackgroundTask
    participant LeadAgent
    participant Database
    participant WebSocket

    User->>Frontend: Click "Approve and Start Development"
    Frontend->>TasksAPI: POST /api/projects/{id}/tasks/approve
    TasksAPI->>Database: Transition phase to "active"
    TasksAPI->>Database: Update tasks to "pending"
    TasksAPI->>WebSocket: broadcast_development_started
    TasksAPI->>BackgroundTask: Schedule start_multi_agent_execution
    TasksAPI-->>Frontend: 200 OK (approval success)
    
    BackgroundTask->>LeadAgent: Create/Get LeadAgent instance
    BackgroundTask->>Database: Store agent in running_agents
    BackgroundTask->>WebSocket: broadcast_agent_execution_started
    BackgroundTask->>LeadAgent: start_multi_agent_execution()
    
    loop For each task
        LeadAgent->>LeadAgent: Assign task to agent
        LeadAgent->>WebSocket: broadcast_agent_created
        LeadAgent->>WebSocket: broadcast_task_assigned
        LeadAgent->>Database: Update task status
        LeadAgent->>WebSocket: broadcast_task_status_changed
    end
    
    LeadAgent-->>BackgroundTask: Execution summary
    BackgroundTask->>WebSocket: broadcast_agent_execution_completed
    Frontend->>Frontend: Update UI (tasks & agents visible)

Loading

Files to Modify

1. file:codeframe/ui/shared.py - Add start_multi_agent_execution function
2. file:codeframe/ui/routers/tasks.py - Add BackgroundTasks parameter and schedule execution
3. file:codeframe/ui/websocket_broadcasts.py - Add execution status broadcast functions
4. file:web-ui/src/lib/websocketMessageMapper.ts - Add handlers for new message types
5. file:tests/ui/test_task_approval.py - Add test for execution startup
6. file:CHANGELOG.md - Document the fix

Risk Mitigation

• Backward Compatibility: The change is additive - existing functionality remains unchanged
• Performance: Background task execution prevents blocking the approval response
• Error Handling: Comprehensive try-except blocks with appropriate logging and broadcasts
• Testing: New test coverage ensures the fix works correctly
• Monitoring: WebSocket broadcasts provide visibility into execution status

Import In IDE

🤖 Prompt for AI Agents

## Observations

The bug occurs because the task approval flow (`file:codeframe/ui/routers/tasks.py` `approve_tasks` endpoint) successfully transitions the project phase to "active" and broadcasts a `development_started` event, but **never initiates the multi-agent execution loop**. The `LeadAgent.start_multi_agent_execution()` method exists and is responsible for creating agents, assigning tasks, and executing them, but it's never called after task approval. The frontend displays "0/0 tasks" and "No Agents Assigned" because the WebSocket-based agent state (used by `TaskList` and `AgentList` components) remains empty without active agent execution.

## Approach

The fix requires adding a background task to the task approval endpoint that starts the multi-agent execution after successful phase transition. This follows the existing pattern used in `file:codeframe/ui/routers/agents.py` where `start_agent` is called as a background task. The solution involves: (1) creating a new async function to start multi-agent execution, (2) adding it as a background task in the approval endpoint, (3) ensuring proper error handling and WebSocket broadcasts for execution status, and (4) handling the LeadAgent lifecycle properly by storing it in `running_agents` dictionary.

## Implementation Steps

### 1. Create Multi-Agent Execution Starter Function

**File:** `file:codeframe/ui/shared.py`

Add a new async function `start_multi_agent_execution` after the existing `start_agent` function (around line 413):

```python
async def start_multi_agent_execution(
    project_id: int, 
    db: Database, 
    agents_dict: Dict[int, LeadAgent], 
    api_key: str
) -> None:
    """Start multi-agent execution for approved tasks.
    
    This function:
    - Gets or creates LeadAgent instance
    - Calls start_multi_agent_execution() to begin task execution
    - Broadcasts execution status via WebSocket
    - Handles errors gracefully with appropriate broadcasts
    
    Args:
        project_id: Project ID to start execution for
        db: Database connection
        agents_dict: Dictionary to store running agents
        api_key: Anthropic API key for agents
    """
```

**Implementation details:**
- Check if LeadAgent already exists in `running_agents` (reuse if available)
- If not, create new LeadAgent instance with project_id, db, and api_key
- Store agent in both `shared_state._running_agents` and `agents_dict` (thread-safe with lock)
- Call `agent.start_multi_agent_execution()` with appropriate parameters (max_retries=3, max_concurrent=5)
- Wrap execution in try-except to handle errors
- Broadcast `agent_execution_started` message before execution
- Broadcast `agent_execution_completed` or `agent_execution_failed` after execution
- Use `asyncio.to_thread()` for blocking operations to avoid blocking the event loop

### 2. Update Task Approval Endpoint

**File:** `file:codeframe/ui/routers/tasks.py`

Modify the `approve_tasks` function signature to include `BackgroundTasks`:

```python
@project_router.post("/{project_id}/tasks/approve")
async def approve_tasks(
    project_id: int,
    request: TaskApprovalRequest,
    background_tasks: BackgroundTasks,  # ADD THIS
    db: Database = Depends(get_db),
    current_user: User = Depends(get_current_user),
) -> TaskApprovalResponse:
```

After the `broadcast_development_started` call (around line 231), add:

```python
# Start multi-agent execution in background
api_key = os.environ.get("ANTHROPIC_API_KEY")
if api_key:
    background_tasks.add_task(
        start_multi_agent_execution,
        project_id,
        db,
        running_agents,
        api_key
    )
    logger.info(f"Scheduled multi-agent execution for project {project_id}")
else:
    logger.warning(f"ANTHROPIC_API_KEY not set - cannot start multi-agent execution for project {project_id}")
```

**Import additions needed:**
- Add `BackgroundTasks` to FastAPI imports
- Add `start_multi_agent_execution` to imports from `codeframe.ui.shared`
- Add `running_agents` to imports from `codeframe.ui.shared`
- Add `os` import for environment variable access

### 3. Add WebSocket Broadcast Functions

**File:** `file:codeframe/ui/websocket_broadcasts.py`

Add new broadcast functions after `broadcast_development_started` (around line 979):

```python
async def broadcast_agent_execution_started(
    manager, project_id: int, total_tasks: int
) -> None:
    """Broadcast when multi-agent execution begins."""
    
async def broadcast_agent_execution_completed(
    manager, project_id: int, summary: Dict[str, Any]
) -> None:
    """Broadcast when multi-agent execution completes."""
    
async def broadcast_agent_execution_failed(
    manager, project_id: int, error: str
) -> None:
    """Broadcast when multi-agent execution fails."""
```

**Message format:**
- `agent_execution_started`: Include project_id, total_tasks, timestamp
- `agent_execution_completed`: Include project_id, completed, failed, retries, execution_time, timestamp
- `agent_execution_failed`: Include project_id, error, timestamp

### 4. Update Frontend WebSocket Handler

**File:** `file:web-ui/src/lib/websocketMessageMapper.ts`

Add handlers for new message types in the message mapper:

```typescript
case 'agent_execution_started':
  // Handle execution start - could show loading indicator
  
case 'agent_execution_completed':
  // Handle execution completion - refresh task/agent state
  
case 'agent_execution_failed':
  // Handle execution failure - show error message
```

### 5. Handle Edge Cases

**Considerations:**

a) **Idempotency:** Check if execution is already running before starting
   - In `start_multi_agent_execution`, check if agent exists and is already executing
   - Return early if execution is in progress

b) **Error Recovery:** If execution fails, ensure proper cleanup
   - Remove agent from `running_agents` on critical failure
   - Update project status appropriately
   - Broadcast error to frontend

c) **Concurrent Approvals:** Prevent race conditions
   - Use `shared_state._agents_lock` when checking/creating agents
   - Ensure atomic operations for agent lifecycle

d) **API Key Validation:** Handle missing API key gracefully
   - Check for ANTHROPIC_API_KEY before scheduling background task
   - Log warning and return appropriate response if missing

### 6. Update Tests

**File:** `file:tests/ui/test_task_approval.py`

Add new test case:

```python
@pytest.mark.asyncio
async def test_approve_tasks_starts_multi_agent_execution(
    self, mock_db, mock_user
):
    """Test that multi-agent execution is started after approval."""
```

**Test assertions:**
- Verify `background_tasks.add_task` is called with `start_multi_agent_execution`
- Verify correct parameters are passed (project_id, db, running_agents, api_key)
- Mock `start_multi_agent_execution` and verify it's called
- Verify appropriate WebSocket broadcasts are sent

### 7. Documentation Updates

**File:** `file:CHANGELOG.md`

Add entry under bug fixes:
```markdown
### Fixed
- [P0] Tasks and agents now display correctly after approval - multi-agent execution starts automatically when transitioning to Development Phase (#242)
```

## Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant TasksAPI as Tasks API
    participant BackgroundTask
    participant LeadAgent
    participant Database
    participant WebSocket

    User->>Frontend: Click "Approve and Start Development"
    Frontend->>TasksAPI: POST /api/projects/{id}/tasks/approve
    TasksAPI->>Database: Transition phase to "active"
    TasksAPI->>Database: Update tasks to "pending"
    TasksAPI->>WebSocket: broadcast_development_started
    TasksAPI->>BackgroundTask: Schedule start_multi_agent_execution
    TasksAPI-->>Frontend: 200 OK (approval success)
    
    BackgroundTask->>LeadAgent: Create/Get LeadAgent instance
    BackgroundTask->>Database: Store agent in running_agents
    BackgroundTask->>WebSocket: broadcast_agent_execution_started
    BackgroundTask->>LeadAgent: start_multi_agent_execution()
    
    loop For each task
        LeadAgent->>LeadAgent: Assign task to agent
        LeadAgent->>WebSocket: broadcast_agent_created
        LeadAgent->>WebSocket: broadcast_task_assigned
        LeadAgent->>Database: Update task status
        LeadAgent->>WebSocket: broadcast_task_status_changed
    end
    
    LeadAgent-->>BackgroundTask: Execution summary
    BackgroundTask->>WebSocket: broadcast_agent_execution_completed
    Frontend->>Frontend: Update UI (tasks & agents visible)
```

## Files to Modify

1. `file:codeframe/ui/shared.py` - Add `start_multi_agent_execution` function
2. `file:codeframe/ui/routers/tasks.py` - Add BackgroundTasks parameter and schedule execution
3. `file:codeframe/ui/websocket_broadcasts.py` - Add execution status broadcast functions
4. `file:web-ui/src/lib/websocketMessageMapper.ts` - Add handlers for new message types
5. `file:tests/ui/test_task_approval.py` - Add test for execution startup
6. `file:CHANGELOG.md` - Document the fix

## Risk Mitigation

- **Backward Compatibility:** The change is additive - existing functionality remains unchanged
- **Performance:** Background task execution prevents blocking the approval response
- **Error Handling:** Comprehensive try-except blocks with appropriate logging and broadcasts
- **Testing:** New test coverage ensures the fix works correctly
- **Monitoring:** WebSocket broadcasts provide visibility into execution status

---

Execution Information

Branch: main
Commit: 7b8257d

[frankbria]

Update: Partially Fixed ✅

Progress Since Original Report (Jan 10)

Fixed:

• ✅ Tasks now display in Tasks tab (were completely empty)
• ✅ Task Statistics show correct total (16 tasks)
• ✅ Task names/content are correct

Still Issues:

• ❌ Tab count shows 0/16 (should show 16/16 or 16 pending)
• ❌ All tasks: "Assigned to: Unassigned"
• ❌ No agents created
• ❌ Progress: 0% (should reflect pending tasks)

Current State

• Phase: Development (✅ working)
• Status: RUNNING, Connected
• Blockers: 0 ("agents are running smoothly!")
• Console: No errors (WebSocket connected)

Root Cause

Tasks are stored and displayed, but:

1. Counter logic is broken (shows 0/16 instead of 16/16)
2. Agent assignment flow not triggering (no agents created)
3. Progress calculation wrong (0% when 16 tasks pending)

Related

Original bug #199 (approval 422/400) — ✅ FIXED

This is now a UI/agent assignment issue, not a data loss issue.

[frankbria]

Related issue filed:

#244 - [P1] Agents not auto-assigned after task approval (edge case)

This focuses on the root cause: agents not being created/assigned after approval. #242 tracks the UI/display fallout (counter wrong, no assignment shown), while #244 tracks the actual agent assignment flow issue.

[frankbria]

Closed with PR #246 (hopefully)