[P0] Clicking 'Start Discovery' doesn't start discovery process

[frankbria]

When the user is on the project page: /projects/[id] and the project is not finished with discovery, there is a button 'Start Discovery' which should begin the discovery process. But, when the user clicks the button, the API (/projects/[id]/start) returns the following:

{message: "Project 1 is already running", status: "running"}
message
: 
"Project 1 is already running"
status
: 
"running"

Because of this message, the page does not kick off any discovery process.

Expected Behavior:

1. Even if the project is already running, the Start Discovery button should begin the discovery process from scratch. Future issues address what happens if the project is part-way through the discovery process.
2. The project page already queries the API (/projects/[id]/status) which in the case of a project that hasn't begun discovery returns the following:

{project_id: 1, name: "test-project", status: "running", phase: "discovery", workflow_step: 1,…}
name: "test-project"
phase: "discovery"
progress: {completed_tasks: 0, total_tasks: 0, percentage: 0}
completed_tasks: 0
percentage: 0
total_tasks: 0
project_id: 1
status: "running"
workflow_step: 1

This response should automatically indicate to the application that the discovery process has not begun and should now begin (or at least ask the user if they're ready to begin). So, the button and/or the status information should kick off the process. Currently, it does not.

In addition to solving the workflow issue, unit tests on the button and E2E tests on the workflow should have caught this but did not. They need to be updated in order to handle this workflow.

[traycerai]

Plan

Observations

The issue stems from a mismatch between project status and discovery state. When a project is created, it's set to status "running" but discovery hasn't started (state: "idle", completed_tasks: 0). The /start endpoint in file:codeframe/ui/routers/agents.py (lines 74-78) checks only project status and returns "already running" without verifying if discovery has actually begun. This blocks the "Start Discovery" button in file:web-ui/src/components/DiscoveryProgress.tsx from initiating the discovery process. The frontend correctly calls projectsApi.startProject() which hits this endpoint, but the backend logic incorrectly assumes "running" status means discovery is active.

Approach

The fix requires modifying the /start endpoint to check discovery state in addition to project status. Instead of immediately returning "already running" when status is "RUNNING", the endpoint should query the discovery status via LeadAgent and only proceed to start discovery if it's in "idle" state. This aligns with the expected behavior: even if a project is marked "running", if discovery hasn't started (completed_tasks: 0, state: "idle"), the button should initiate it. The implementation will leverage existing LeadAgent.get_discovery_status() and LeadAgent.start_discovery() methods. Tests need updates to cover the scenario where a "running" project with idle discovery can be started.

Implementation Steps

1. Backend: Modify /start Endpoint Logic

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

Changes to start_project_agent function (lines 37-89):

• Remove the immediate return when project status is "RUNNING" (lines 74-78)
• Add logic to check discovery state using LeadAgent.get_discovery_status()
• If discovery state is "idle", proceed to start discovery by calling the background task
• If discovery state is "discovering" or "completed", return appropriate response
• Handle the case where project is truly already running with an active agent

Detailed modifications:

a. After checking project exists and authorization (lines 64-71), add discovery state check:

• Initialize a temporary LeadAgent instance with dummy API key (for status check only)
• Call agent.get_discovery_status() to get current discovery state
• Check if state is "idle" - if yes, proceed to start discovery
• Check if state is "discovering" - if yes, return "discovery already in progress"
• Check if state is "completed" - if yes, return "discovery already completed"

b. Update the "already running" check (lines 74-78):

• Instead of checking only project["status"] == ProjectStatus.RUNNING.value
• Check both project status AND whether an agent is already in running_agents dict
• Only return "already running" if both conditions are true

c. Ensure the background task start_agent is called when discovery is idle, regardless of project status

Error handling:

• Wrap discovery status check in try-except to handle cases where LeadAgent initialization fails
• If status check fails, log warning and proceed with normal start flow

2. Backend: Update start_agent Function

File: file:codeframe/ui/shared.py

Changes to start_agent function (lines 257-361):

• After creating LeadAgent instance (line 287), check if discovery needs to be started
• Call agent.get_discovery_status() to determine current state
• If state is "idle", call agent.start_discovery() to initiate the discovery process
• Update project phase to "discovery" in database
• Broadcast discovery_started event via WebSocket

Detailed modifications:

a. After line 297 (storing agent in dictionaries), add discovery initialization:

• Get discovery status: status = agent.get_discovery_status()
• If status["state"] == "idle":
  • Call agent.start_discovery() to get first question
  • Update project phase: db.update_project(project_id, {"phase": "discovery"})
  • Broadcast discovery_started event with first question

b. Handle errors during discovery start:

• Wrap discovery start in try-except
• If it fails, log error but don't fail the entire agent start
• The agent will still be running, user can retry discovery start

3. Frontend: Enhance Error Handling

File: file:web-ui/src/components/DiscoveryProgress.tsx

Changes to handleStartDiscovery function (lines 114-132):

• Update error handling to distinguish between different error types
• If API returns "already running" but discovery is idle, show appropriate message
• Add retry logic for transient failures

Detailed modifications:

a. Enhance error handling in catch block (lines 126-128):

• Parse error response to check if it's "already running" vs other errors
• If "already running", check if discovery state is idle
• Show user-friendly message: "Discovery is starting, please wait..."
• Auto-retry after 2 seconds if discovery is idle

b. Update success handling (lines 123-125):

• After successful start, immediately refresh discovery progress
• Show loading indicator while waiting for first question

4. Unit Tests: Update Backend Tests

File: file:tests/agents/test_agent_lifecycle.py

Add new test cases:

a. test_start_endpoint_starts_discovery_when_project_running_but_discovery_idle:

• Create project with status "running"
• Set discovery state to "idle" (no discovery started)
• Call POST /api/projects/{id}/start
• Assert response is 202 Accepted
• Assert discovery is started (state changes to "discovering")

b. test_start_endpoint_returns_already_running_when_discovery_active:

• Create project with status "running"
• Start discovery (state: "discovering")
• Call POST /api/projects/{id}/start
• Assert response is 200 OK with "already running" message

c. test_start_endpoint_handles_discovery_completed:

• Create project with discovery completed
• Call POST /api/projects/{id}/start
• Assert response indicates discovery is complete

File: file:tests/core/test_project_start.py

Add new test case:

d. test_start_begins_discovery_when_project_running_but_discovery_idle:

• Create project with status "running"
• Mock LeadAgent with discovery state "idle"
• Call project.start()
• Assert start_discovery() is called
• Assert project status remains "running" or updates to "planning"

5. Unit Tests: Update Frontend Tests

File: file:web-ui/src/components/__tests__/DiscoveryProgress.test.tsx

Update existing tests:

a. Update test "should call API when Start Discovery button clicked" (around line 380):

• Mock API to return 202 Accepted
• Assert button shows "Starting..." during request
• Assert progress is refreshed after successful start

b. Add new test "should handle already running response gracefully":

• Mock API to return 200 with "already running" message
• Assert appropriate message is shown to user
• Assert no error state is triggered

c. Add new test "should retry when discovery is idle but project running":

• Mock API to return "already running" first time
• Mock discovery progress to show "idle" state
• Assert component retries after delay
• Assert discovery starts on retry

6. E2E Tests: Update Discovery Workflow Tests

File: file:tests/e2e/test_start_agent_flow.spec.ts

Add new test scenario:

a. "should start discovery when project is running but discovery not started":

• Create project via API
• Verify project status is "running"
• Navigate to project page
• Verify "Start Discovery" button is visible
• Click "Start Discovery" button
• Verify discovery question appears
• Verify discovery state changes to "discovering"

File: file:tests/e2e/test_complete_user_journey.spec.ts

Update existing test:

b. Update "complete user journey from project creation to task execution":

• After project creation, verify discovery can be started
• Handle case where project is already "running"
• Ensure discovery starts regardless of project status

7. API Documentation Updates

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

Update docstring for start_project_agent (lines 44-62):

• Update description to clarify behavior when project is "running" but discovery is idle
• Document the discovery state check logic
• Update return codes:
  • 202 Accepted: Discovery starting (even if project status is "running")
  • 200 OK: Discovery already in progress or completed
  • 404 Not Found: Project doesn't exist
  • 403 Forbidden: User lacks access
  • 500 Internal Server Error: API key not configured or other errors

Implementation Flow Diagram

sequenceDiagram
    participant User
    participant Frontend as DiscoveryProgress.tsx
    participant API as /api/projects/{id}/start
    participant Agent as start_agent()
    participant LeadAgent
    participant DB as Database

    User->>Frontend: Click "Start Discovery"
    Frontend->>API: POST /start
    
    API->>DB: Check project exists
    API->>DB: Check user authorization
    
    API->>LeadAgent: get_discovery_status()
    LeadAgent->>DB: Query discovery state
    LeadAgent-->>API: {state: "idle"}
    
    alt Discovery is idle
        API->>Agent: start_agent() [background]
        API-->>Frontend: 202 Accepted
        
        Agent->>LeadAgent: Create instance
        Agent->>LeadAgent: get_discovery_status()
        LeadAgent-->>Agent: {state: "idle"}
        
        Agent->>LeadAgent: start_discovery()
        LeadAgent->>DB: Initialize discovery
        LeadAgent->>DB: Get first question
        LeadAgent-->>Agent: First question
        
        Agent->>DB: Update project phase
        Agent->>Frontend: WebSocket: discovery_started
        
        Frontend->>Frontend: Refresh progress
        Frontend->>User: Show first question
    else Discovery already active
        API-->>Frontend: 200 OK (already running)
        Frontend->>User: Show "Discovery in progress"
    end

Loading

Files to Modify

File	Changes	Priority
file:codeframe/ui/routers/agents.py	Modify /start endpoint logic to check discovery state	P0
file:codeframe/ui/shared.py	Update start_agent() to initiate discovery when idle	P0
file:web-ui/src/components/DiscoveryProgress.tsx	Enhance error handling and retry logic	P1
file:tests/agents/test_agent_lifecycle.py	Add tests for discovery state checks	P0
file:tests/core/test_project_start.py	Add test for running project with idle discovery	P0
file:web-ui/src/components/__tests__/DiscoveryProgress.test.tsx	Update button click tests	P1
file:tests/e2e/test_start_agent_flow.spec.ts	Add E2E test for discovery start workflow	P2
file:tests/e2e/test_complete_user_journey.spec.ts	Update journey test to handle running status	P2

Testing Strategy

Unit Tests

1. Backend: Test /start endpoint with various discovery states (idle, discovering, completed)
2. Backend: Test start_agent() function initiates discovery when state is idle
3. Frontend: Test button behavior with different API responses
4. Frontend: Test error handling and retry logic

Integration Tests

1. Test full flow: project creation → start discovery → first question appears
2. Test idempotency: calling start multiple times doesn't create duplicate discovery sessions
3. Test state transitions: idle → discovering → completed

E2E Tests

1. Test user journey: create project → click Start Discovery → answer questions
2. Test edge case: refresh page during discovery start
3. Test error recovery: network failure during start, then retry

Manual Testing Checklist

• Create new project, verify "Start Discovery" button appears
• Click button, verify discovery starts and first question shows
• Refresh page, verify button doesn't reappear if discovery started
• Test with project already running, verify discovery still starts
• Test with discovery in progress, verify appropriate message shown
• Test with discovery completed, verify no start button shown

Import In IDE

🤖 Prompt for AI Agents

## Observations

The issue stems from a mismatch between project status and discovery state. When a project is created, it's set to status "running" but discovery hasn't started (state: "idle", completed_tasks: 0). The `/start` endpoint in `file:codeframe/ui/routers/agents.py` (lines 74-78) checks only project status and returns "already running" without verifying if discovery has actually begun. This blocks the "Start Discovery" button in `file:web-ui/src/components/DiscoveryProgress.tsx` from initiating the discovery process. The frontend correctly calls `projectsApi.startProject()` which hits this endpoint, but the backend logic incorrectly assumes "running" status means discovery is active.

## Approach

The fix requires modifying the `/start` endpoint to check discovery state in addition to project status. Instead of immediately returning "already running" when status is "RUNNING", the endpoint should query the discovery status via LeadAgent and only proceed to start discovery if it's in "idle" state. This aligns with the expected behavior: even if a project is marked "running", if discovery hasn't started (completed_tasks: 0, state: "idle"), the button should initiate it. The implementation will leverage existing `LeadAgent.get_discovery_status()` and `LeadAgent.start_discovery()` methods. Tests need updates to cover the scenario where a "running" project with idle discovery can be started.

## Implementation Steps

### 1. Backend: Modify `/start` Endpoint Logic

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

**Changes to `start_project_agent` function (lines 37-89):**

- Remove the immediate return when project status is "RUNNING" (lines 74-78)
- Add logic to check discovery state using `LeadAgent.get_discovery_status()`
- If discovery state is "idle", proceed to start discovery by calling the background task
- If discovery state is "discovering" or "completed", return appropriate response
- Handle the case where project is truly already running with an active agent

**Detailed modifications:**

a. After checking project exists and authorization (lines 64-71), add discovery state check:
   - Initialize a temporary LeadAgent instance with dummy API key (for status check only)
   - Call `agent.get_discovery_status()` to get current discovery state
   - Check if state is "idle" - if yes, proceed to start discovery
   - Check if state is "discovering" - if yes, return "discovery already in progress"
   - Check if state is "completed" - if yes, return "discovery already completed"

b. Update the "already running" check (lines 74-78):
   - Instead of checking only `project["status"] == ProjectStatus.RUNNING.value`
   - Check both project status AND whether an agent is already in `running_agents` dict
   - Only return "already running" if both conditions are true

c. Ensure the background task `start_agent` is called when discovery is idle, regardless of project status

**Error handling:**
- Wrap discovery status check in try-except to handle cases where LeadAgent initialization fails
- If status check fails, log warning and proceed with normal start flow

### 2. Backend: Update `start_agent` Function

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

**Changes to `start_agent` function (lines 257-361):**

- After creating LeadAgent instance (line 287), check if discovery needs to be started
- Call `agent.get_discovery_status()` to determine current state
- If state is "idle", call `agent.start_discovery()` to initiate the discovery process
- Update project phase to "discovery" in database
- Broadcast discovery_started event via WebSocket

**Detailed modifications:**

a. After line 297 (storing agent in dictionaries), add discovery initialization:
   - Get discovery status: `status = agent.get_discovery_status()`
   - If `status["state"] == "idle"`:
     - Call `agent.start_discovery()` to get first question
     - Update project phase: `db.update_project(project_id, {"phase": "discovery"})`
     - Broadcast discovery_started event with first question

b. Handle errors during discovery start:
   - Wrap discovery start in try-except
   - If it fails, log error but don't fail the entire agent start
   - The agent will still be running, user can retry discovery start

### 3. Frontend: Enhance Error Handling

**File:** `file:web-ui/src/components/DiscoveryProgress.tsx`

**Changes to `handleStartDiscovery` function (lines 114-132):**

- Update error handling to distinguish between different error types
- If API returns "already running" but discovery is idle, show appropriate message
- Add retry logic for transient failures

**Detailed modifications:**

a. Enhance error handling in catch block (lines 126-128):
   - Parse error response to check if it's "already running" vs other errors
   - If "already running", check if discovery state is idle
   - Show user-friendly message: "Discovery is starting, please wait..."
   - Auto-retry after 2 seconds if discovery is idle

b. Update success handling (lines 123-125):
   - After successful start, immediately refresh discovery progress
   - Show loading indicator while waiting for first question

### 4. Unit Tests: Update Backend Tests

**File:** `file:tests/agents/test_agent_lifecycle.py`

**Add new test cases:**

a. `test_start_endpoint_starts_discovery_when_project_running_but_discovery_idle`:
   - Create project with status "running"
   - Set discovery state to "idle" (no discovery started)
   - Call POST `/api/projects/{id}/start`
   - Assert response is 202 Accepted
   - Assert discovery is started (state changes to "discovering")

b. `test_start_endpoint_returns_already_running_when_discovery_active`:
   - Create project with status "running"
   - Start discovery (state: "discovering")
   - Call POST `/api/projects/{id}/start`
   - Assert response is 200 OK with "already running" message

c. `test_start_endpoint_handles_discovery_completed`:
   - Create project with discovery completed
   - Call POST `/api/projects/{id}/start`
   - Assert response indicates discovery is complete

**File:** `file:tests/core/test_project_start.py`

**Add new test case:**

d. `test_start_begins_discovery_when_project_running_but_discovery_idle`:
   - Create project with status "running"
   - Mock LeadAgent with discovery state "idle"
   - Call `project.start()`
   - Assert `start_discovery()` is called
   - Assert project status remains "running" or updates to "planning"

### 5. Unit Tests: Update Frontend Tests

**File:** `file:web-ui/src/components/__tests__/DiscoveryProgress.test.tsx`

**Update existing tests:**

a. Update test "should call API when Start Discovery button clicked" (around line 380):
   - Mock API to return 202 Accepted
   - Assert button shows "Starting..." during request
   - Assert progress is refreshed after successful start

b. Add new test "should handle already running response gracefully":
   - Mock API to return 200 with "already running" message
   - Assert appropriate message is shown to user
   - Assert no error state is triggered

c. Add new test "should retry when discovery is idle but project running":
   - Mock API to return "already running" first time
   - Mock discovery progress to show "idle" state
   - Assert component retries after delay
   - Assert discovery starts on retry

### 6. E2E Tests: Update Discovery Workflow Tests

**File:** `file:tests/e2e/test_start_agent_flow.spec.ts`

**Add new test scenario:**

a. "should start discovery when project is running but discovery not started":
   - Create project via API
   - Verify project status is "running"
   - Navigate to project page
   - Verify "Start Discovery" button is visible
   - Click "Start Discovery" button
   - Verify discovery question appears
   - Verify discovery state changes to "discovering"

**File:** `file:tests/e2e/test_complete_user_journey.spec.ts`

**Update existing test:**

b. Update "complete user journey from project creation to task execution":
   - After project creation, verify discovery can be started
   - Handle case where project is already "running"
   - Ensure discovery starts regardless of project status

### 7. API Documentation Updates

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

**Update docstring for `start_project_agent` (lines 44-62):**

- Update description to clarify behavior when project is "running" but discovery is idle
- Document the discovery state check logic
- Update return codes:
  - 202 Accepted: Discovery starting (even if project status is "running")
  - 200 OK: Discovery already in progress or completed
  - 404 Not Found: Project doesn't exist
  - 403 Forbidden: User lacks access
  - 500 Internal Server Error: API key not configured or other errors

## Implementation Flow Diagram

```mermaid
sequenceDiagram
    participant User
    participant Frontend as DiscoveryProgress.tsx
    participant API as /api/projects/{id}/start
    participant Agent as start_agent()
    participant LeadAgent
    participant DB as Database

    User->>Frontend: Click "Start Discovery"
    Frontend->>API: POST /start
    
    API->>DB: Check project exists
    API->>DB: Check user authorization
    
    API->>LeadAgent: get_discovery_status()
    LeadAgent->>DB: Query discovery state
    LeadAgent-->>API: {state: "idle"}
    
    alt Discovery is idle
        API->>Agent: start_agent() [background]
        API-->>Frontend: 202 Accepted
        
        Agent->>LeadAgent: Create instance
        Agent->>LeadAgent: get_discovery_status()
        LeadAgent-->>Agent: {state: "idle"}
        
        Agent->>LeadAgent: start_discovery()
        LeadAgent->>DB: Initialize discovery
        LeadAgent->>DB: Get first question
        LeadAgent-->>Agent: First question
        
        Agent->>DB: Update project phase
        Agent->>Frontend: WebSocket: discovery_started
        
        Frontend->>Frontend: Refresh progress
        Frontend->>User: Show first question
    else Discovery already active
        API-->>Frontend: 200 OK (already running)
        Frontend->>User: Show "Discovery in progress"
    end
```

## Files to Modify

| File | Changes | Priority |
|------|---------|----------|
| `file:codeframe/ui/routers/agents.py` | Modify `/start` endpoint logic to check discovery state | P0 |
| `file:codeframe/ui/shared.py` | Update `start_agent()` to initiate discovery when idle | P0 |
| `file:web-ui/src/components/DiscoveryProgress.tsx` | Enhance error handling and retry logic | P1 |
| `file:tests/agents/test_agent_lifecycle.py` | Add tests for discovery state checks | P0 |
| `file:tests/core/test_project_start.py` | Add test for running project with idle discovery | P0 |
| `file:web-ui/src/components/__tests__/DiscoveryProgress.test.tsx` | Update button click tests | P1 |
| `file:tests/e2e/test_start_agent_flow.spec.ts` | Add E2E test for discovery start workflow | P2 |
| `file:tests/e2e/test_complete_user_journey.spec.ts` | Update journey test to handle running status | P2 |

## Testing Strategy

### Unit Tests
1. Backend: Test `/start` endpoint with various discovery states (idle, discovering, completed)
2. Backend: Test `start_agent()` function initiates discovery when state is idle
3. Frontend: Test button behavior with different API responses
4. Frontend: Test error handling and retry logic

### Integration Tests
1. Test full flow: project creation → start discovery → first question appears
2. Test idempotency: calling start multiple times doesn't create duplicate discovery sessions
3. Test state transitions: idle → discovering → completed

### E2E Tests
1. Test user journey: create project → click Start Discovery → answer questions
2. Test edge case: refresh page during discovery start
3. Test error recovery: network failure during start, then retry

### Manual Testing Checklist
- [ ] Create new project, verify "Start Discovery" button appears
- [ ] Click button, verify discovery starts and first question shows
- [ ] Refresh page, verify button doesn't reappear if discovery started
- [ ] Test with project already running, verify discovery still starts
- [ ] Test with discovery in progress, verify appropriate message shown
- [ ] Test with discovery completed, verify no start button shown

---

Execution Information

Branch: main
Commit: d0b4437

---

💡 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

---

🔗 Similar Issues

Possible Duplicates

• The project discovery process doesn't kick off on new project creation #170

Related Issues

• [P2] Add confirmation/warning when restarting discovery on completed projects #171
• After creating a project on the main screen, the app returns to the create project screen #94
• [P1] Implement Project.start() with Lead Agent initialization #102

👤 Suggested Assignees

• frankbria

---

🧪 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!