fix: prevent duplicate task generation button for late-joining users (#228)

* fix(ui): prevent duplicate task generation button for late-joining users

This addresses a UX issue where users who log into a project where
tasks have already been generated still see the "Generate Task Breakdown"
button, which fails with a 400 error when clicked.

Changes:
- Backend: Make generate-tasks endpoint idempotent by returning
  {success: true, tasks_already_exist: true} instead of 400 error
  when tasks already exist
- Frontend: Check for existing tasks on component mount during
  state initialization (in fetchProgress with initializePrdState)
- Frontend: Handle idempotent backend response gracefully in
  handleGenerateTaskBreakdown
- Types: Add optional tasks_already_exist field to API response type

This implements defensive programming on both sides:
1. Frontend checks task existence on mount (covers late-joining users)
2. Backend handles duplicate requests gracefully (covers edge cases)
3. Error handler transitions to "tasks ready" state on idempotent response

TDD: Tests written first, all 95 frontend + 9 backend tests passing.

* test(e2e): add late-joining user tests for task generation

Addresses a critical E2E test coverage gap: no tests verified UI state
for users who arrive AFTER WebSocket events have occurred.

Changes:
- Add test_late_joining_user.spec.ts with scenarios:
  - Tasks already exist → should see "Review Tasks" not "Generate Tasks"
  - PRD already complete → should see "View PRD" with correct state
  - Idempotent API call → backend returns success, not error
- Update seed-test-data.py to create "planning" phase project:
  - Set project phase to "planning" instead of "discovery"
  - Set discovery state to "completed"
  - Seed PRD content in memory table

Why this gap existed:
- All existing E2E tests followed real-time happy path flow
- Tests assumed user was present during WebSocket events
- Conditional skip patterns (test.skip when element not visible)
  masked the issue instead of catching it

This ensures future similar bugs are caught by E2E tests.

* fix(e2e): correct projects table schema in seed script

The seed script was using incorrect columns (slug, updated_at) that
don't exist in the projects table. Updated to use the correct schema:
id, name, description, user_id, workspace_path, phase, created_at

This enables proper seeding of Project 2 for late-joining user tests.

* fix(e2e): complete Project 2 seed data for late-joining user tests

The dashboard was crashing for Project 2 due to missing required fields:
- Added `status` field (was null, causing .toUpperCase() error)
- Added workspace directory creation
- Added project-agent assignments
- Fixed tasks table columns (assigned_to not assigned_agent)

Also updated debug-error.spec.ts to use E2E_TEST_PROJECT_PLANNING_ID
for testing Project 2 scenarios.

* fix: address code review feedback for late-joining user feature

- Fix agent ID mismatch: backend-001 → backend-worker-001, frontend-001 → frontend-specialist-001
- Add taskStateInitialized flag to prevent race condition during async task check
- Add user notification when tasks already exist (tasksAlreadyExistMessage)
- Simplify E2E test assertions with explicit expect() calls instead of conditionals
- API type already had tasks_already_exist field (verified, no change needed)

* test(e2e): add curated smoke test suite with @smoke tagging

- Update test:smoke script to filter by @smoke tag (Chromium only)
- Tag 4 critical-path tests as @smoke:
  - Auth: login with valid credentials
  - Project: create new project via UI
  - Dashboard: display all main sections
  - Late-joining: show Tasks Ready when tasks exist
- Remove WebSocket test from smoke suite (flaky, needs investigation)
- Smoke suite runs in ~45s for fast CI feedback

* fix(websocket): queue subscriptions when socket not yet open

Root cause: subscribe() silently did nothing when called before the
WebSocket was OPEN. AgentStateProvider calls connect() then immediately
subscribe(), but the socket is still CONNECTING, causing the subscribe
message to never be sent.

Fix: Add pendingSubscriptions queue that holds project IDs until the
socket opens, then sends all queued subscriptions in onopen handler.

This fixes the WebSocket E2E test regression and re-enables it as a
smoke test.

* fix(e2e): align tasks_p2 schema with 22-column tasks table format

Update Project 2 task seeding to use the full tasks table schema:
- Add all 22 columns (issue_id, task_number, depends_on, etc.)
- Include realistic values for tokens, quality gates, timestamps
- Match the format used for Project 1 tasks

This ensures consistency between projects and prevents potential
schema mismatches that could cause test failures.

* fix(ux): convert tasks-already-exist notification to fixed-position toast

Convert the inline notification for "tasks already exist" (idempotent
response) to a fixed-position toast notification in the bottom-right
corner. This ensures the feedback is always visible regardless of
scroll position.

- Moved notification outside main content flow
- Added fixed positioning (bottom-4 right-4)
- Added shadow and slide-in animation
- Maintains accessibility attributes (role="status", aria-live="polite")

* test: add missing API mocks for task-generation-section tests

The tests expecting task-generation-section to appear were missing
mocks for mockGetPRD and mockTasksList. These are required because
the component now waits for taskStateInitialized before showing the
"Generate Task Breakdown" button (prevents button flash on mount).

* fix(e2e): correct project 2 seeding schema alignment

Two fixes for seed-test-data.py:

1. Add missing is_active column to project 2 agent assignments
   - Schema requires 5 columns: project_id, agent_id, role, is_active, assigned_at
   - Was using 4 columns, causing NOT NULL constraint errors

2. Add table_exists guard for project 2 memory table inserts
   - Discovery state and PRD content inserts now check TABLE_MEMORY exists
   - Matches defensive pattern used for project 1

* fix(react): prevent state update on unmounted component

Replace inline setTimeout in handleGenerateTaskBreakdown with a useEffect
that properly manages the timeout lifecycle. This prevents the React warning
"Can't perform a React state update on an unmounted component" if the
component unmounts before the 3-second timeout completes.

The useEffect:
- Watches tasksAlreadyExistMessage state
- Sets timeout only when message is true
- Returns cleanup function that clears the timeout on unmount

Author: frankbria

codeframe/ui/routers/discovery.py

@@ -692,13 +692,19 @@ async def generate_tasks(
             "Please complete PRD generation first.",
         )
 
-    # Check if tasks already exist to prevent duplicate generation
+    # Check if tasks already exist - return idempotent success instead of error
+    # This improves UX for users who join late and miss WebSocket events
     existing_tasks = db.get_project_tasks(project_id)
     if existing_tasks:
-        raise HTTPException(
-            status_code=400,
-            detail="Tasks have already been generated for this project.",
+        logger.info(
+            f"Tasks already exist for project {project_id} "
+            f"(count: {len(existing_tasks)}). Returning idempotent success."
         )
+        return {
+            "success": True,
+            "message": "Tasks have already been generated for this project.",
+            "tasks_already_exist": True,
+        }
 
     # Verify API key is available
     api_key = os.environ.get("ANTHROPIC_API_KEY")

tests/api/test_generate_tasks_endpoint.py

@@ -191,8 +191,13 @@ def test_background_task_receives_correct_parameters(
         # Note: In TestClient, background tasks are executed synchronously
         # so we can verify the function was called correctly
 
-    def test_returns_400_when_tasks_already_exist(self, api_client):
-        """Test endpoint returns 400 when tasks have already been generated."""
+    def test_returns_200_with_flag_when_tasks_already_exist(self, api_client):
+        """Test endpoint is idempotent - returns 200 with tasks_already_exist flag.
+
+        Instead of returning 400 error when tasks exist, the endpoint should
+        be idempotent and return success with a flag indicating tasks already
+        exist. This improves UX for users who join late and miss WebSocket events.
+        """
         # ARRANGE
         db = get_db_from_client(api_client)
         project_id = db.create_project("test-project", "Test Project")
@@ -216,10 +221,12 @@ def test_returns_400_when_tasks_already_exist(self, api_client):
             f"/api/projects/{project_id}/discovery/generate-tasks"
         )
 
-        # ASSERT
-        assert response.status_code == 400
-        detail = response.json()["detail"].lower()
-        assert "already" in detail or "exist" in detail
+        # ASSERT - idempotent endpoint returns 200 with flag
+        assert response.status_code == 200
+        data = response.json()
+        assert data["success"] is True
+        assert data["tasks_already_exist"] is True
+        assert "already" in data["message"].lower()
 
 
 class TestGenerateTasksEndpointIntegration:

tests/e2e/debug-error.spec.ts

@@ -10,7 +10,8 @@ import { test } from '@playwright/test';
 import { loginUser } from './test-utils';
 
 const FRONTEND_URL = process.env.FRONTEND_URL || 'http://localhost:3001';
-const PROJECT_ID = process.env.E2E_TEST_PROJECT_ID || '1';
+// Use Project 2 for testing late-joining user scenarios (matches late-joining tests)
+const PROJECT_ID = process.env.E2E_TEST_PROJECT_PLANNING_ID || '2';
 
 test('capture browser console errors', async ({ page }) => {
   // Login first to access protected routes
@@ -33,8 +34,12 @@ test('capture browser console errors', async ({ page }) => {
   });
 
   // Navigate to dashboard
-  console.log('\n=== Navigating to dashboard ===');
-  await page.goto(`${FRONTEND_URL}/projects/${PROJECT_ID}`);
+  const targetUrl = `${FRONTEND_URL}/projects/${PROJECT_ID}`;
+  console.log(`\n=== Navigating to dashboard ===`);
+  console.log(`Target URL: ${targetUrl}`);
+  console.log(`PROJECT_ID: ${PROJECT_ID}`);
+  await page.goto(targetUrl);
+  console.log(`Current URL after navigation: ${page.url()}`);
 
   // Wait a bit to see what happens
   await page.waitForTimeout(5000);

tests/e2e/package.json

@@ -5,7 +5,7 @@
   "private": true,
   "scripts": {
     "test": "playwright test",
-    "test:smoke": "playwright test --project=chromium",
+    "test:smoke": "playwright test --grep @smoke --project=chromium",
     "test:headed": "playwright test --headed",
     "test:debug": "playwright test --debug",
     "test:chromium": "playwright test --project=chromium",

tests/e2e/seed-test-data.py

@@ -1179,10 +1179,11 @@ def seed_test_data(db_path: str, project_id: int):
             print(f"✅ Seeded {count}/3 discovery state entries for project {project_id}")
 
         # ========================================
-        # 8. Update Project Phase for Discovery Tests
+        # 8. Update Project Phase for Discovery Tests (Project 1)
         # ========================================
         # Set project to 'discovery' phase so discovery UI renders correctly
-        print("📋 Setting project phase to 'discovery'...")
+        # This project is used by test_start_agent_flow.spec.ts and other discovery tests
+        print("📋 Setting project phase to 'discovery' for discovery tests...")
         try:
             cursor.execute(
                 "UPDATE projects SET phase = 'discovery' WHERE id = ?",
@@ -1192,6 +1193,184 @@ def seed_test_data(db_path: str, project_id: int):
         except sqlite3.Error as e:
             print(f"⚠️  Failed to update project phase: {e}")
 
+        # ========================================
+        # 9. Create Second Project for Late-Joining User Tests (Project 2)
+        # ========================================
+        # Create a separate project in 'planning' phase with completed PRD and tasks
+        # This enables testing late-joining user scenarios where tasks already exist
+        print("\n📦 Creating second project for late-joining user tests...")
+        planning_project_id = 2
+
+        # Create workspace directory for Project 2 (required for dashboard to load)
+        workspace_path_p2 = os.path.join(E2E_TEST_ROOT, ".codeframe", "workspaces", str(planning_project_id))
+        os.makedirs(workspace_path_p2, exist_ok=True)
+        print(f"   📁 Created workspace: {workspace_path_p2}")
+
+        # Use INSERT OR REPLACE to ensure project exists with correct data
+        # This handles both fresh installs and re-runs
+        # NOTE: Both 'status' and 'phase' must be set - status is used in Dashboard header
+        cursor.execute(
+            """
+            INSERT OR REPLACE INTO projects (id, name, description, user_id, workspace_path, status, phase, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                planning_project_id,
+                "e2e-planning-project",
+                "Test project in planning phase with tasks (for late-joining user tests)",
+                1,  # test user
+                workspace_path_p2,
+                "planning",  # status - required for Dashboard to render (not null)
+                "planning",  # phase - project lifecycle phase
+                now_ts,
+            ),
+        )
+        print(f"✅ Created/updated project {planning_project_id} in 'planning' phase")
+
+        # Add completed discovery state for project 2 (guard against missing memory table)
+        if table_exists(cursor, TABLE_MEMORY):
+            discovery_entries_p2 = [
+                (planning_project_id, "discovery_state", "state", "completed", now_ts, now_ts),
+            ]
+            for entry in discovery_entries_p2:
+                cursor.execute(
+                    """
+                    INSERT OR REPLACE INTO memory (project_id, category, key, value, created_at, updated_at)
+                    VALUES (?, ?, ?, ?, ?, ?)
+                    """,
+                    entry,
+                )
+
+            # Add PRD content for project 2
+            prd_content = """# Project Requirements Document
+
+## Overview
+This is a test PRD for late-joining user E2E tests.
+
+## Features
+1. User authentication
+2. Project management
+3. Task tracking
+
+## Technical Requirements
+- FastAPI backend
+- Next.js frontend
+- SQLite database
+
+## Timeline
+Sprint 1: Core features
+Sprint 2: Testing and polish
+"""
+            cursor.execute(
+                """
+                INSERT OR REPLACE INTO memory (project_id, category, key, value, created_at, updated_at)
+                VALUES (?, 'prd', 'content', ?, ?, ?)
+                """,
+                (planning_project_id, prd_content, now_ts, now_ts),
+            )
+        else:
+            print(f"⚠️  Warning: {TABLE_MEMORY} table doesn't exist, skipping project 2 discovery state and PRD")
+
+        # Clear existing tasks for project 2 before re-seeding (ensures clean state)
+        cursor.execute("DELETE FROM tasks WHERE project_id = ?", (planning_project_id,))
+
+        # Add tasks for project 2 (so late-joining user tests can verify task state)
+        # Using full 22-column tasks schema to match Project 1 format
+        # Schema: id, project_id, issue_id, task_number, parent_issue_number, title, description,
+        #         status, assigned_to, depends_on, can_parallelize, priority, workflow_step,
+        #         requires_mcp, estimated_tokens, actual_tokens, created_at, completed_at,
+        #         commit_sha, quality_gate_status, quality_gate_failures, requires_human_approval
+        tasks_p2 = [
+            (
+                None,  # id (auto-increment)
+                planning_project_id,
+                None,  # issue_id
+                "T001",  # task_number
+                None,  # parent_issue_number
+                "Implement user authentication",  # title
+                "Set up JWT-based authentication",  # description
+                "completed",  # status
+                "backend-worker-001",  # assigned_to
+                None,  # depends_on
+                0,  # can_parallelize
+                3,  # priority (high)
+                1,  # workflow_step
+                0,  # requires_mcp
+                5000,  # estimated_tokens
+                4800,  # actual_tokens
+                now_ts,  # created_at
+                now_ts,  # completed_at
+                "abc123",  # commit_sha
+                "passed",  # quality_gate_status
+                None,  # quality_gate_failures
+                0,  # requires_human_approval
+            ),
+            (
+                None,  # id (auto-increment)
+                planning_project_id,
+                None,  # issue_id
+                "T002",  # task_number
+                None,  # parent_issue_number
+                "Create project dashboard",  # title
+                "Build the main dashboard UI",  # description
+                "in_progress",  # status
+                "frontend-specialist-001",  # assigned_to
+                "1",  # depends_on (depends on T001)
+                1,  # can_parallelize
+                2,  # priority (medium)
+                2,  # workflow_step
+                0,  # requires_mcp
+                8000,  # estimated_tokens
+                3500,  # actual_tokens
+                now_ts,  # created_at
+                None,  # completed_at
+                None,  # commit_sha
+                None,  # quality_gate_status
+                None,  # quality_gate_failures
+                0,  # requires_human_approval
+            ),
+        ]
+        for task in tasks_p2:
+            cursor.execute(
+                """
+                INSERT INTO tasks (
+                    id, project_id, issue_id, task_number, parent_issue_number, title, description,
+                    status, assigned_to, depends_on, can_parallelize, priority, workflow_step,
+                    requires_mcp, estimated_tokens, actual_tokens, created_at, completed_at,
+                    commit_sha, quality_gate_status, quality_gate_failures, requires_human_approval
+                )
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                task,
+            )
+
+        cursor.execute(
+            "SELECT COUNT(*) FROM tasks WHERE project_id = ?",
+            (planning_project_id,),
+        )
+        task_count = cursor.fetchone()[0]
+        print(f"✅ Seeded {task_count} tasks for project {planning_project_id}")
+
+        # Add project-agent assignments for project 2 (required for Dashboard to render)
+        # Clear existing assignments first
+        cursor.execute("DELETE FROM project_agents WHERE project_id = ?", (planning_project_id,))
+        # Use the same agents seeded for project 1
+        # Schema: project_id, agent_id, role, is_active, assigned_at (5 columns - must match project 1)
+        project_agent_assignments_p2 = [
+            (planning_project_id, "backend-worker-001", "developer", 1, now_ts),
+            (planning_project_id, "frontend-specialist-001", "developer", 1, now_ts),
+        ]
+        for assignment in project_agent_assignments_p2:
+            cursor.execute(
+                """
+                INSERT INTO project_agents (project_id, agent_id, role, is_active, assigned_at)
+                VALUES (?, ?, ?, ?, ?)
+                """,
+                assignment,
+            )
+        print(f"✅ Seeded {len(project_agent_assignments_p2)} project-agent assignments for project {planning_project_id}")
+        print(f"✅ Set E2E_TEST_PROJECT_PLANNING_ID={planning_project_id}")
+
         # Commit all changes
         conn.commit()
         print(f"\n✅ Test data seeding complete for project {project_id}!")

tests/e2e/test_auth_flow.spec.ts

@@ -137,7 +137,7 @@ test.describe('Authentication Flow', () => {
   });
 
   test.describe('Login Success', () => {
-    test('should login successfully with valid credentials', async ({ page }) => {
+    test('should login successfully with valid credentials @smoke', async ({ page }) => {
       await page.goto('/login');
 
       // Fill in credentials

tests/e2e/test_dashboard.spec.ts

@@ -148,7 +148,7 @@ test.describe('Dashboard - Sprint 10 Features', () => {
     ]);
   });
 
-  test('should display all main dashboard sections', async () => {
+  test('should display all main dashboard sections @smoke', async () => {
     // Verify main dashboard elements are visible with waits
     const header = page.locator('[data-testid="dashboard-header"]');
     await header.waitFor({ state: 'visible', timeout: 15000 });
@@ -287,7 +287,7 @@ test.describe('Dashboard - Sprint 10 Features', () => {
     await expect(page.locator('[data-testid="total-cost-display"]')).toBeAttached();
   });
 
-  test('should receive real-time updates via WebSocket', async () => {
+  test('should receive real-time updates via WebSocket @smoke', async () => {
     // Step 1: Verify WebSocket backend endpoint is ready
     await waitForWebSocketReady(BACKEND_URL);