feat: add multi-feature batching for coding agents

Enable the orchestrator to assign 1-3 features per coding agent subprocess,
selected via dependency chain extension + same-category fill. This reduces
cold-start overhead and leverages shared context across related features.

Orchestrator (parallel_orchestrator.py):
- Add batch tracking: _batch_features and _feature_to_primary data structures
- Add build_feature_batches() with dependency chain + category fill algorithm
- Add start_feature_batch() and _spawn_coding_agent_batch() methods
- Update _on_agent_complete() for batch cleanup across all features
- Update stop_feature() with _feature_to_primary lookup
- Update get_ready_features() to exclude all batch feature IDs
- Update main loop to build batches then spawn per available slot

CLI and agent layer:
- Add --feature-ids (comma-separated) and --batch-size CLI args
- Add feature_ids parameter to run_autonomous_agent() with batch prompt selection
- Add get_batch_feature_prompt() with sequential workflow instructions

WebSocket layer (server/websocket.py):
- Add BATCH_CODING_AGENT_START_PATTERN and BATCH_FEATURES_COMPLETE_PATTERN
- Add _handle_batch_agent_start() and _handle_batch_agent_complete() methods
- Add featureIds field to all agent_update messages
- Track current_feature_id updates as agent moves through batch

Frontend (React UI):
- Add featureIds to ActiveAgent and WSAgentUpdateMessage types
- Update KanbanColumn and DependencyGraph agent-feature maps for batch
- Update AgentCard to show "Batch: #X, #Y, #Z" with active feature highlight
- Add "Features per Agent" segmented control (1-3) in SettingsModal

Settings integration (full stack):
- Add batch_size to schemas, settings router, agent router, process manager
- Default batch_size=3, user-configurable 1-3 via settings UI
- batch_size=1 is functionally identical to pre-batching behavior

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.claude/commands/create-spec.md

@@ -8,7 +8,7 @@ This command **requires** the project directory as an argument via `$ARGUMENTS`.
 
 **Example:** `/create-spec generations/my-app`
 
-**Output location:** `$ARGUMENTS/prompts/app_spec.txt` and `$ARGUMENTS/prompts/initializer_prompt.md`
+**Output location:** `$ARGUMENTS/.autocoder/prompts/app_spec.txt` and `$ARGUMENTS/.autocoder/prompts/initializer_prompt.md`
 
 If `$ARGUMENTS` is empty, inform the user they must provide a project path and exit.
 
@@ -95,6 +95,27 @@ Ask the user about their involvement preference:
 
 **For Detailed Mode users**, ask specific tech questions about frontend, backend, database, etc.
 
+### Phase 3b: Database Requirements (MANDATORY)
+
+**Always ask this question regardless of mode:**
+
+> "One foundational question about data storage:
+>
+> **Does this application need to store user data persistently?**
+>
+> 1. **Yes, needs a database** - Users create, save, and retrieve data (most apps)
+> 2. **No, stateless** - Pure frontend, no data storage needed (calculators, static sites)
+> 3. **Not sure** - Let me describe what I need and you decide"
+
+**Branching logic:**
+
+- **If "Yes" or "Not sure"**: Continue normally. The spec will include database in tech stack and the initializer will create 5 mandatory Infrastructure features (indices 0-4) to verify database connectivity and persistence.
+
+- **If "No, stateless"**: Note this in the spec. Skip database from tech stack. Infrastructure features will be simplified (no database persistence tests). Mark this clearly:
+  ```xml
+  <database>none - stateless application</database>
+  ```
+
 ## Phase 4: Features (THE MAIN PHASE)
 
 This is where you spend most of your time. Ask questions in plain language that anyone can answer.
@@ -207,12 +228,23 @@ After gathering all features, **you** (the agent) should tally up the testable f
 
 **Typical ranges for reference:**
 
-- **Simple apps** (todo list, calculator, notes): ~20-50 features
+- **Simple apps** (todo list, calculator, notes): ~25-55 features (includes 5 infrastructure)
-- **Medium apps** (blog, task manager with auth): ~100 features
+- **Medium apps** (blog, task manager with auth): ~105 features (includes 5 infrastructure)
-- **Advanced apps** (e-commerce, CRM, full SaaS): ~150-200 features
+- **Advanced apps** (e-commerce, CRM, full SaaS): ~155-205 features (includes 5 infrastructure)
 
 These are just reference points - your actual count should come from the requirements discussed.
 
+**MANDATORY: Infrastructure Features**
+
+If the app requires a database (Phase 3b answer was "Yes" or "Not sure"), you MUST include 5 Infrastructure features (indices 0-4):
+1. Database connection established
+2. Database schema applied correctly
+3. Data persists across server restart
+4. No mock data patterns in codebase
+5. Backend API queries real database
+
+These features ensure the coding agent implements a real database, not mock data or in-memory storage.
+
 **How to count features:**
 For each feature area discussed, estimate the number of discrete, testable behaviors:
 
@@ -225,17 +257,20 @@ For each feature area discussed, estimate the number of discrete, testable behav
 
 > "Based on what we discussed, here's my feature breakdown:
 >
+> - **Infrastructure (required)**: 5 features (database setup, persistence verification)
 > - [Category 1]: ~X features
 > - [Category 2]: ~Y features
 > - [Category 3]: ~Z features
 > - ...
 >
-> **Total: ~N features**
+> **Total: ~N features** (including 5 infrastructure)
 >
 > Does this seem right, or should I adjust?"
 
 Let the user confirm or adjust. This becomes your `feature_count` for the spec.
 
+**Important:** The first 5 features (indices 0-4) created by the initializer MUST be the Infrastructure category with no dependencies. All other features depend on these.
+
 ## Phase 5: Technical Details (DERIVED OR DISCUSSED)
 
 **For Quick Mode users:**
@@ -312,13 +347,13 @@ First ask in conversation if they want to make changes.
 
 ## Output Directory
 
-The output directory is: `$ARGUMENTS/prompts/`
+The output directory is: `$ARGUMENTS/.autocoder/prompts/`
 
 Once the user approves, generate these files:
 
 ## 1. Generate `app_spec.txt`
 
-**Output path:** `$ARGUMENTS/prompts/app_spec.txt`
+**Output path:** `$ARGUMENTS/.autocoder/prompts/app_spec.txt`
 
 Create a new file using this XML structure:
 
@@ -454,7 +489,7 @@ Create a new file using this XML structure:
 
 ## 2. Update `initializer_prompt.md`
 
-**Output path:** `$ARGUMENTS/prompts/initializer_prompt.md`
+**Output path:** `$ARGUMENTS/.autocoder/prompts/initializer_prompt.md`
 
 If the output directory has an existing `initializer_prompt.md`, read it and update the feature count.
 If not, copy from `.claude/templates/initializer_prompt.template.md` first, then update.
@@ -477,7 +512,7 @@ After:  **CRITICAL:** You must create exactly **25** features using the `feature
 
 ## 3. Write Status File (REQUIRED - Do This Last)
 
-**Output path:** `$ARGUMENTS/prompts/.spec_status.json`
+**Output path:** `$ARGUMENTS/.autocoder/prompts/.spec_status.json`
 
 **CRITICAL:** After you have completed ALL requested file changes, write this status file to signal completion to the UI. This is required for the "Continue to Project" button to appear.
 
@@ -489,8 +524,8 @@ Write this JSON file:
   "version": 1,
   "timestamp": "[current ISO 8601 timestamp, e.g., 2025-01-15T14:30:00.000Z]",
   "files_written": [
-    "prompts/app_spec.txt",
+    ".autocoder/prompts/app_spec.txt",
-    "prompts/initializer_prompt.md"
+    ".autocoder/prompts/initializer_prompt.md"
   ],
   "feature_count": [the feature count from Phase 4L]
 }
@@ -504,9 +539,9 @@ Write this JSON file:
   "version": 1,
   "timestamp": "2025-01-15T14:30:00.000Z",
   "files_written": [
-    "prompts/app_spec.txt",
+    ".autocoder/prompts/app_spec.txt",
-    "prompts/initializer_prompt.md",
+    ".autocoder/prompts/initializer_prompt.md",
-    "prompts/coding_prompt.md"
+    ".autocoder/prompts/coding_prompt.md"
   ],
   "feature_count": 35
 }
@@ -524,11 +559,11 @@ Write this JSON file:
 
 Once files are generated, tell the user what to do next:
 
-> "Your specification files have been created in `$ARGUMENTS/prompts/`!
+> "Your specification files have been created in `$ARGUMENTS/.autocoder/prompts/`!
 >
 > **Files created:**
-> - `$ARGUMENTS/prompts/app_spec.txt`
+> - `$ARGUMENTS/.autocoder/prompts/app_spec.txt`
-> - `$ARGUMENTS/prompts/initializer_prompt.md`
+> - `$ARGUMENTS/.autocoder/prompts/initializer_prompt.md`
 >
 > The **Continue to Project** button should now appear. Click it to start the autonomous coding agent!
 >

.claude/commands/expand-project.md

@@ -42,7 +42,7 @@ You are the **Project Expansion Assistant** - an expert at understanding existin
 # FIRST: Read and Understand Existing Project
 
 **Step 1:** Read the existing specification:
-- Read `$ARGUMENTS/prompts/app_spec.txt`
+- Read `$ARGUMENTS/.autocoder/prompts/app_spec.txt`
 
 **Step 2:** Present a summary to the user:
 
@@ -231,4 +231,4 @@ If they want to add more, go back to Phase 1.
 
 # BEGIN
 
-Start by reading the app specification file at `$ARGUMENTS/prompts/app_spec.txt`, then greet the user with a summary of their existing project and ask what they want to add.
+Start by reading the app specification file at `$ARGUMENTS/.autocoder/prompts/app_spec.txt`, then greet the user with a summary of their existing project and ask what they want to add.

.claude/commands/gsd-to-autocoder-spec.md

@@ -5,6 +5,6 @@ description: Convert GSD codebase mapping to Autocoder app_spec.txt
 
 # GSD to Autocoder Spec
 
-Convert `.planning/codebase/*.md` (from `/gsd:map-codebase`) to Autocoder's `prompts/app_spec.txt`.
+Convert `.planning/codebase/*.md` (from `/gsd:map-codebase`) to Autocoder's `.autocoder/prompts/app_spec.txt`.
 
 @.claude/skills/gsd-to-autocoder-spec/SKILL.md

.claude/commands/review-pr.md

@@ -8,8 +8,68 @@ Pull request(s): $ARGUMENTS
 - At least 1 PR is required.
 
 ## TASKS
-- Use the GH CLI tool to retrieve the details (descriptions, divs, comments, feedback, reviews, etc)
+
-- Use 3 deepdive subagents to analyze the impact of the codebase
+1. **Retrieve PR Details**
-- Provide a review on whether the PR is safe to merge as-is
+   - Use the GH CLI tool to retrieve the details (descriptions, diffs, comments, feedback, reviews, etc)
-- Provide any feedback in terms of risk level
+
-- Propose any improments in terms of importance and complexity 
+2. **Assess PR Complexity**
+
+   After retrieving PR details, assess complexity based on:
+   - Number of files changed
+   - Lines added/removed
+   - Number of contributors/commits
+   - Whether changes touch core/architectural files
+
+   ### Complexity Tiers
+
+   **Simple** (no deep dive agents needed):
+   - ≤5 files changed AND ≤100 lines changed AND single author
+   - Review directly without spawning agents
+
+   **Medium** (1-2 deep dive agents):
+   - 6-15 files changed, OR 100-500 lines, OR 2 contributors
+   - Spawn 1 agent for focused areas, 2 if changes span multiple domains
+
+   **Complex** (up to 3 deep dive agents):
+   - >15 files, OR >500 lines, OR >2 contributors, OR touches core architecture
+   - Spawn up to 3 agents to analyze different aspects (e.g., security, performance, architecture)
+
+3. **Analyze Codebase Impact**
+   - Based on the complexity tier determined above, spawn the appropriate number of deep dive subagents
+   - For Simple PRs: analyze directly without spawning agents
+   - For Medium PRs: spawn 1-2 agents focusing on the most impacted areas
+   - For Complex PRs: spawn up to 3 agents to cover security, performance, and architectural concerns
+
+4. **PR Scope & Title Alignment Check**
+   - Compare the PR title and description against the actual diff content
+   - Check whether the PR is focused on a single coherent change or contains multiple unrelated changes
+   - If the title/description describe one thing but the PR contains significantly more (e.g., title says "fix typo in README" but the diff touches 20 files across multiple domains), flag this as a **scope mismatch**
+   - A scope mismatch is a **merge blocker** — recommend the author split the PR into smaller, focused PRs
+   - Suggest specific ways to split the PR (e.g., "separate the refactor from the feature addition")
+   - Reviewing large, unfocused PRs is impractical and error-prone; the review cannot provide adequate assurance for such changes
+
+5. **Vision Alignment Check**
+   - Read the project's README.md and CLAUDE.md to understand the application's core purpose
+   - Assess whether this PR aligns with the application's intended functionality
+   - If the changes deviate significantly from the core vision or add functionality that doesn't serve the application's purpose, note this in the review
+   - This is not a blocker, but should be flagged for the reviewer's consideration
+
+6. **Safety Assessment**
+   - Provide a review on whether the PR is safe to merge as-is
+   - Provide any feedback in terms of risk level
+
+7. **Improvements**
+   - Propose any improvements in terms of importance and complexity
+
+8. **Merge Recommendation**
+   - Based on all findings, provide a clear merge/don't-merge recommendation
+   - If all concerns are minor (cosmetic issues, naming suggestions, small style nits, missing comments, etc.), recommend **merging the PR** and note that the reviewer can address these minor concerns themselves with a quick follow-up commit pushed directly to master
+   - If there are significant concerns (bugs, security issues, architectural problems, scope mismatch), recommend **not merging** and explain what needs to be resolved first
+
+9. **TLDR**
+   - End the review with a `## TLDR` section
+   - In 3-5 bullet points maximum, summarize:
+     - What this PR is actually about (one sentence)
+     - The key concerns, if any (or "no significant concerns")
+     - **Verdict: MERGE** / **MERGE (with minor follow-up)** / **DON'T MERGE** with a one-line reason
+   - This section should be scannable in under 10 seconds

.claude/skills/gsd-to-autocoder-spec/SKILL.md

@@ -9,7 +9,7 @@ description: |
 
 # GSD to Autocoder Spec Converter
 
-Converts `.planning/codebase/*.md` (GSD mapping output) to `prompts/app_spec.txt` (Autocoder format).
+Converts `.planning/codebase/*.md` (GSD mapping output) to `.autocoder/prompts/app_spec.txt` (Autocoder format).
 
 ## When to Use
 
@@ -84,7 +84,7 @@ Extract:
 
 Create `prompts/` directory:
 ```bash
-mkdir -p prompts
+mkdir -p .autocoder/prompts
 ```
 
 **Mapping GSD Documents to Autocoder Spec:**
@@ -114,7 +114,7 @@ mkdir -p prompts
 **Write the spec file** using the XML format from [references/app-spec-format.md](references/app-spec-format.md):
 
 ```bash
-cat > prompts/app_spec.txt << 'EOF'
+cat > .autocoder/prompts/app_spec.txt << 'EOF'
 <project_specification>
   <project_name>{from package.json or directory}</project_name>
 
@@ -173,9 +173,9 @@ EOF
 ### Step 5: Verify Generated Spec
 
 ```bash
-head -100 prompts/app_spec.txt
+head -100 .autocoder/prompts/app_spec.txt
 echo "---"
-grep -c "User can\|System\|API\|Feature" prompts/app_spec.txt || echo "0"
+grep -c "User can\|System\|API\|Feature" .autocoder/prompts/app_spec.txt || echo "0"
 ```
 
 **Validation checklist:**
@@ -194,7 +194,7 @@ Output:
 app_spec.txt generated from GSD codebase mapping.
 
 Source: .planning/codebase/*.md
-Output: prompts/app_spec.txt
+Output: .autocoder/prompts/app_spec.txt
 
 Next: Start Autocoder
 

.claude/templates/coding_prompt.template.md

@@ -49,51 +49,21 @@ Otherwise, start servers manually and document the process.
 
 #### TEST-DRIVEN DEVELOPMENT MINDSET (CRITICAL)
 
-Features are **test cases** that drive development. This is test-driven development:
+Features are **test cases** that drive development. If functionality doesn't exist, **BUILD IT** -- you are responsible for implementing ALL required functionality. Missing pages, endpoints, database tables, or components are NOT blockers; they are your job to create.
 
-- **If you can't test a feature because functionality doesn't exist → BUILD IT**
+**Note:** Your feature has been pre-assigned by the orchestrator. Use `feature_get_by_id` with your assigned feature ID to get the details. Then mark it as in-progress:
-- You are responsible for implementing ALL required functionality
-- Never assume another process will build it later
-- "Missing functionality" is NOT a blocker - it's your job to create it
-
-**Example:** Feature says "User can filter flashcards by difficulty level"
-- WRONG: "Flashcard page doesn't exist yet" → skip feature
-- RIGHT: "Flashcard page doesn't exist yet" → build flashcard page → implement filter → test feature
-
-**Note:** Your feature has been pre-assigned by the orchestrator. Use `feature_get_by_id` with your assigned feature ID to get the details.
-
-Once you've retrieved the feature, **mark it as in-progress** (if not already):
 
 ```
-# Mark feature as in-progress
 Use the feature_mark_in_progress tool with feature_id={your_assigned_id}
 ```
 
 If you get "already in-progress" error, that's OK - continue with implementation.
 
-Focus on completing one feature perfectly and completing its testing steps in this session before moving on to other features.
+Focus on completing one feature perfectly in this session. It's ok if you only complete one feature, as more sessions will follow.
-It's ok if you only complete one feature in this session, as there will be more sessions later that continue to make progress.
 
 #### When to Skip a Feature (EXTREMELY RARE)
 
-**Skipping should almost NEVER happen.** Only skip for truly external blockers you cannot control:
+Only skip for truly external blockers: missing third-party credentials (Stripe keys, OAuth secrets), unavailable external services, or unfulfillable environment requirements. **NEVER** skip because a page, endpoint, component, or data doesn't exist yet -- build it. If a feature requires other functionality first, build that functionality as part of this feature.
-
-- **External API not configured**: Third-party service credentials missing (e.g., Stripe keys, OAuth secrets)
-- **External service unavailable**: Dependency on service that's down or inaccessible
-- **Environment limitation**: Hardware or system requirement you cannot fulfill
-
-**NEVER skip because:**
-
-| Situation | Wrong Action | Correct Action |
-|-----------|--------------|----------------|
-| "Page doesn't exist" | Skip | Create the page |
-| "API endpoint missing" | Skip | Implement the endpoint |
-| "Database table not ready" | Skip | Create the migration |
-| "Component not built" | Skip | Build the component |
-| "No data to test with" | Skip | Create test data or build data entry flow |
-| "Feature X needs to be done first" | Skip | Build feature X as part of this feature |
-
-If a feature requires building other functionality first, **build that functionality**. You are the coding agent - your job is to make the feature work, not to defer it.
 
 If you must skip (truly external blocker only):
 
@@ -139,45 +109,22 @@ Use browser automation tools:
 
 ### STEP 5.5: MANDATORY VERIFICATION CHECKLIST (BEFORE MARKING ANY TEST PASSING)
 
-**You MUST complete ALL of these checks before marking any feature as "passes": true**
+**Complete ALL applicable checks before marking any feature as passing:**
 
-#### Security Verification (for protected features)
+- **Security:** Feature respects role permissions; unauthenticated access blocked; API checks auth (401/403); no cross-user data leaks via URL manipulation
-
+- **Real Data:** Create unique test data via UI, verify it appears, refresh to confirm persistence, delete and verify removal. No unexplained data (indicates mocks). Dashboard counts reflect real numbers
-- [ ] Feature respects user role permissions
+- **Mock Data Grep:** Run STEP 5.6 grep checks - no hits in src/ (excluding tests). No globalThis, devStore, or dev-store patterns
-- [ ] Unauthenticated access is blocked (redirects to login)
+- **Server Restart:** For data features, run STEP 5.7 - data persists across server restart
-- [ ] API endpoint checks authorization (returns 401/403 appropriately)
+- **Navigation:** All buttons link to existing routes, no 404s, back button works, edit/view/delete links have correct IDs
-- [ ] Cannot access other users' data by manipulating URLs
+- **Integration:** Zero JS console errors, no 500s in network tab, API data matches UI, loading/error states work
-
-#### Real Data Verification (CRITICAL - NO MOCK DATA)
-
-- [ ] Created unique test data via UI (e.g., "TEST_12345_VERIFY_ME")
-- [ ] Verified the EXACT data I created appears in UI
-- [ ] Refreshed page - data persists (proves database storage)
-- [ ] Deleted the test data - verified it's gone everywhere
-- [ ] NO unexplained data appeared (would indicate mock data)
-- [ ] Dashboard/counts reflect real numbers after my changes
-
-#### Navigation Verification
-
-- [ ] All buttons on this page link to existing routes
-- [ ] No 404 errors when clicking any interactive element
-- [ ] Back button returns to correct previous page
-- [ ] Related links (edit, view, delete) have correct IDs in URLs
-
-#### Integration Verification
-
-- [ ] Console shows ZERO JavaScript errors
-- [ ] Network tab shows successful API calls (no 500s)
-- [ ] Data returned from API matches what UI displays
-- [ ] Loading states appeared during API calls
-- [ ] Error states handle failures gracefully
 
 ### STEP 5.6: MOCK DATA DETECTION (Before marking passing)
 
-1. **Search code:** `grep -r "mockData\|fakeData\|TODO\|STUB" --include="*.ts" --include="*.tsx"`
+Before marking a feature passing, grep for mock/placeholder data patterns in src/ (excluding test files): `globalThis`, `devStore`, `dev-store`, `mockDb`, `mockData`, `fakeData`, `sampleData`, `dummyData`, `testData`, `TODO.*real`, `TODO.*database`, `STUB`, `MOCK`, `isDevelopment`, `isDev`. Any hits in production code must be investigated and fixed. Also create unique test data (e.g., "TEST_12345"), verify it appears in UI, then delete and confirm removal - unexplained data indicates mock implementations.
-2. **Runtime test:** Create unique data (e.g., "TEST_12345") → verify in UI → delete → verify gone
+
-3. **Check database:** All displayed data must come from real DB queries
+### STEP 5.7: SERVER RESTART PERSISTENCE TEST (MANDATORY for data features)
-4. If unexplained data appears, it's mock data - fix before marking passing.
+
+For any feature involving CRUD or data persistence: create unique test data (e.g., "RESTART_TEST_12345"), verify it exists, then fully stop and restart the dev server. After restart, verify the test data still exists. If data is gone, the implementation uses in-memory storage -- run STEP 5.6 greps, find the mock pattern, and replace with real database queries. Clean up test data after verification. This test catches in-memory stores like `globalThis.devStore` that pass all other tests but lose data on restart.
 
 ### STEP 6: UPDATE FEATURE STATUS (CAREFULLY!)
 
@@ -202,17 +149,23 @@ Use the feature_mark_passing tool with feature_id=42
 
 ### STEP 7: COMMIT YOUR PROGRESS
 
-Make a descriptive git commit:
+Make a descriptive git commit.
+
+**Git Commit Rules:**
+- ALWAYS use simple `-m` flag for commit messages
+- NEVER use heredocs (`cat <<EOF` or `<<'EOF'`) - they fail in sandbox mode with "can't create temp file for here document: operation not permitted"
+- For multi-line messages, use multiple `-m` flags:
 
 ```bash
 git add .
-git commit -m "Implement [feature name] - verified end-to-end
+git commit -m "Implement [feature name] - verified end-to-end" -m "- Added [specific changes]" -m "- Tested with browser automation" -m "- Marked feature #X as passing"
+```
 
-- Added [specific changes]
+Or use a single descriptive message:
-- Tested with browser automation
+
-- Marked feature #X as passing
+```bash
-- Screenshots in verification/ directory
+git add .
-"
+git commit -m "feat: implement [feature name] with browser verification"
 ```
 
 ### STEP 8: UPDATE PROGRESS NOTES

.claude/templates/initializer_prompt.template.md

@@ -36,9 +36,9 @@ Use the feature_create_bulk tool to add all features at once. You can create fea
 
 - Feature count must match the `feature_count` specified in app_spec.txt
 - Reference tiers for other projects:
-  - **Simple apps**: ~150 tests
+  - **Simple apps**: ~165 tests (includes 5 infrastructure)
-  - **Medium apps**: ~250 tests
+  - **Medium apps**: ~265 tests (includes 5 infrastructure)
-  - **Complex apps**: ~400+ tests
+  - **Advanced apps**: ~405+ tests (includes 5 infrastructure)
 - Both "functional" and "style" categories
 - Mix of narrow tests (2-5 steps) and comprehensive tests (10+ steps)
 - At least 25 tests MUST have 10+ steps each (more for complex apps)
@@ -60,8 +60,9 @@ Dependencies enable **parallel execution** of independent features. When specifi
 2. **Can only depend on EARLIER features** (index must be less than current position)
 3. **No circular dependencies** allowed
 4. **Maximum 20 dependencies** per feature
-5. **Foundation features (index 0-9)** should have NO dependencies
+5. **Infrastructure features (indices 0-4)** have NO dependencies - they run FIRST
-6. **60% of features after index 10** should have at least one dependency
+6. **ALL features after index 4** MUST depend on `[0, 1, 2, 3, 4]` (infrastructure)
+7. **60% of features after index 10** should have additional dependencies beyond infrastructure
 
 ### Dependency Types
 
@@ -82,30 +83,113 @@ Create WIDE dependency graphs, not linear chains:
 
 ```json
 [
-  // FOUNDATION TIER (indices 0-2, no dependencies) - run first
+  // INFRASTRUCTURE TIER (indices 0-4, no dependencies) - MUST run first
-  { "name": "App loads without errors", "category": "functional" },
+  { "name": "Database connection established", "category": "functional" },
-  { "name": "Navigation bar displays", "category": "style" },
+  { "name": "Database schema applied correctly", "category": "functional" },
-  { "name": "Homepage renders correctly", "category": "functional" },
+  { "name": "Data persists across server restart", "category": "functional" },
+  { "name": "No mock data patterns in codebase", "category": "functional" },
+  { "name": "Backend API queries real database", "category": "functional" },
 
-  // AUTH TIER (indices 3-5, depend on foundation) - run in parallel
+  // FOUNDATION TIER (indices 5-7, depend on infrastructure)
-  { "name": "User can register", "depends_on_indices": [0] },
+  { "name": "App loads without errors", "category": "functional", "depends_on_indices": [0, 1, 2, 3, 4] },
-  { "name": "User can login", "depends_on_indices": [0, 3] },
+  { "name": "Navigation bar displays", "category": "style", "depends_on_indices": [0, 1, 2, 3, 4] },
-  { "name": "User can logout", "depends_on_indices": [4] },
+  { "name": "Homepage renders correctly", "category": "functional", "depends_on_indices": [0, 1, 2, 3, 4] },
 
-  // CORE CRUD TIER (indices 6-9) - WIDE GRAPH: all 4 depend on login
+  // AUTH TIER (indices 8-10, depend on foundation + infrastructure)
-  // All 4 start as soon as login passes!
+  { "name": "User can register", "depends_on_indices": [0, 1, 2, 3, 4, 5] },
-  { "name": "User can create todo", "depends_on_indices": [4] },
+  { "name": "User can login", "depends_on_indices": [0, 1, 2, 3, 4, 5, 8] },
-  { "name": "User can view todos", "depends_on_indices": [4] },
+  { "name": "User can logout", "depends_on_indices": [0, 1, 2, 3, 4, 9] },
-  { "name": "User can edit todo", "depends_on_indices": [4, 6] },
-  { "name": "User can delete todo", "depends_on_indices": [4, 6] },
 
-  // ADVANCED TIER (indices 10-11) - both depend on view, not each other
+  // CORE CRUD TIER (indices 11-14) - WIDE GRAPH: all 4 depend on login
-  { "name": "User can filter todos", "depends_on_indices": [7] },
+  { "name": "User can create todo", "depends_on_indices": [0, 1, 2, 3, 4, 9] },
-  { "name": "User can search todos", "depends_on_indices": [7] }
+  { "name": "User can view todos", "depends_on_indices": [0, 1, 2, 3, 4, 9] },
+  { "name": "User can edit todo", "depends_on_indices": [0, 1, 2, 3, 4, 9, 11] },
+  { "name": "User can delete todo", "depends_on_indices": [0, 1, 2, 3, 4, 9, 11] },
+
+  // ADVANCED TIER (indices 15-16) - both depend on view, not each other
+  { "name": "User can filter todos", "depends_on_indices": [0, 1, 2, 3, 4, 12] },
+  { "name": "User can search todos", "depends_on_indices": [0, 1, 2, 3, 4, 12] }
 ]
 ```
 
-**Result:** With 3 parallel agents, this 12-feature project completes in ~5-6 cycles instead of 12 sequential cycles.
+**Result:** With 3 parallel agents, this project completes efficiently with proper database validation first.
+
+---
+
+## MANDATORY INFRASTRUCTURE FEATURES (Indices 0-4)
+
+**CRITICAL:** Create these FIRST, before any functional features. These features ensure the application uses a real database, not mock data or in-memory storage.
+
+| Index | Name | Test Steps |
+|-------|------|------------|
+| 0 | Database connection established | Start server → check logs for DB connection → health endpoint returns DB status |
+| 1 | Database schema applied correctly | Connect to DB directly → list tables → verify schema matches spec |
+| 2 | Data persists across server restart | Create via API → STOP server completely → START server → query API → data still exists |
+| 3 | No mock data patterns in codebase | Run grep for prohibited patterns → must return empty |
+| 4 | Backend API queries real database | Check server logs → SQL/DB queries appear for API calls |
+
+**ALL other features MUST depend on indices [0, 1, 2, 3, 4].**
+
+### Infrastructure Feature Descriptions
+
+**Feature 0 - Database connection established:**
+```text
+Steps:
+1. Start the development server
+2. Check server logs for database connection message
+3. Call health endpoint (e.g., GET /api/health)
+4. Verify response includes database status: connected
+```
+
+**Feature 1 - Database schema applied correctly:**
+```text
+Steps:
+1. Connect to database directly (sqlite3, psql, etc.)
+2. List all tables in the database
+3. Verify tables match what's defined in app_spec.txt
+4. Verify key columns exist on each table
+```
+
+**Feature 2 - Data persists across server restart (CRITICAL):**
+```text
+Steps:
+1. Create unique test data via API (e.g., POST /api/items with name "RESTART_TEST_12345")
+2. Verify data appears in API response (GET /api/items)
+3. STOP the server completely (kill by port to avoid killing unrelated Node processes):
+   - Unix/macOS: lsof -ti :$PORT | xargs kill -9 2>/dev/null || true && sleep 5
+   - Windows: FOR /F "tokens=5" %a IN ('netstat -aon ^| find ":$PORT"') DO taskkill /F /PID %a 2>nul
+   - Note: Replace $PORT with actual port (e.g., 3000)
+4. Verify server is stopped: lsof -ti :$PORT returns nothing (or netstat on Windows)
+5. RESTART the server: ./init.sh & sleep 15
+6. Query API again: GET /api/items
+7. Verify "RESTART_TEST_12345" still exists
+8. If data is GONE → CRITICAL FAILURE (in-memory storage detected)
+9. Clean up test data
+```
+
+**Feature 3 - No mock data patterns in codebase:**
+```text
+Steps:
+1. Run: grep -r "globalThis\." --include="*.ts" --include="*.tsx" --include="*.js" src/
+2. Run: grep -r "dev-store\|devStore\|DevStore\|mock-db\|mockDb" --include="*.ts" --include="*.tsx" --include="*.js" src/
+3. Run: grep -r "mockData\|testData\|fakeData\|sampleData\|dummyData" --include="*.ts" --include="*.tsx" --include="*.js" src/
+4. Run: grep -r "TODO.*real\|TODO.*database\|TODO.*API\|STUB\|MOCK" --include="*.ts" --include="*.tsx" --include="*.js" src/
+5. Run: grep -r "isDevelopment\|isDev\|process\.env\.NODE_ENV.*development" --include="*.ts" --include="*.tsx" --include="*.js" src/
+6. Run: grep -r "new Map\(\)\|new Set\(\)" --include="*.ts" --include="*.tsx" --include="*.js" src/ 2>/dev/null
+7. Run: grep -E "json-server|miragejs|msw" package.json
+8. ALL grep commands must return empty (exit code 1)
+9. If any returns results → investigate and fix before passing
+```
+
+**Feature 4 - Backend API queries real database:**
+```text
+Steps:
+1. Start server with verbose logging
+2. Make API call (e.g., GET /api/items)
+3. Check server logs
+4. Verify SQL query appears (SELECT, INSERT, etc.) or ORM query log
+5. If no DB queries in logs → implementation is using mock data
+```
 
 ---
 
@@ -115,8 +199,9 @@ The feature_list.json **MUST** include tests from ALL 20 categories. Minimum cou
 
 ### Category Distribution by Complexity Tier
 
-| Category                         | Simple  | Medium  | Complex  |
+| Category                         | Simple  | Medium  | Advanced |
 | -------------------------------- | ------- | ------- | -------- |
+| **0. Infrastructure (REQUIRED)** | 5       | 5       | 5        |
 | A. Security & Access Control     | 5       | 20      | 40       |
 | B. Navigation Integrity          | 15      | 25      | 40       |
 | C. Real Data Verification        | 20      | 30      | 50       |
@@ -137,12 +222,14 @@ The feature_list.json **MUST** include tests from ALL 20 categories. Minimum cou
 | R. Concurrency & Race Conditions | 5       | 8       | 15       |
 | S. Export/Import                 | 5       | 6       | 10       |
 | T. Performance                   | 5       | 5       | 10       |
-| **TOTAL**                        | **150** | **250** | **400+** |
+| **TOTAL**                        | **165** | **265** | **405+** |
 
 ---
 
 ### Category Descriptions
 
+**0. Infrastructure (REQUIRED - Priority 0)** - Database connectivity, schema existence, data persistence across server restart, absence of mock patterns. These features MUST pass before any functional features can begin. All tiers require exactly 5 infrastructure features (indices 0-4).
+
 **A. Security & Access Control** - Test unauthorized access blocking, permission enforcement, session management, role-based access, and data isolation between users.
 
 **B. Navigation Integrity** - Test all buttons, links, menus, breadcrumbs, deep links, back button behavior, 404 handling, and post-login/logout redirects.
@@ -205,6 +292,16 @@ The feature_list.json must include tests that **actively verify real data** and
 - `setTimeout` simulating API delays with static data
 - Static returns instead of database queries
 
+**Additional prohibited patterns (in-memory stores):**
+
+- `globalThis.` (in-memory storage pattern)
+- `dev-store`, `devStore`, `DevStore` (development stores)
+- `json-server`, `mirage`, `msw` (mock backends)
+- `Map()` or `Set()` used as primary data store
+- Environment checks like `if (process.env.NODE_ENV === 'development')` for data routing
+
+**Why this matters:** In-memory stores (like `globalThis.devStore`) will pass simple tests because data persists during a single server run. But data is LOST on server restart, which is unacceptable for production. The Infrastructure features (0-4) specifically test for this by requiring data to survive a full server restart.
+
 ---
 
 **CRITICAL INSTRUCTION:**

.claude/templates/testing_prompt.template.md

@@ -1,58 +1,29 @@
 ## YOUR ROLE - TESTING AGENT
 
-You are a **testing agent** responsible for **regression testing** previously-passing features.
+You are a **testing agent** responsible for **regression testing** previously-passing features. If you find a regression, you must fix it.
 
-Your job is to ensure that features marked as "passing" still work correctly. If you find a regression (a feature that no longer works), you must fix it.
+## ASSIGNED FEATURES FOR REGRESSION TESTING
 
-### STEP 1: GET YOUR BEARINGS (MANDATORY)
+You are assigned to test the following features: {{TESTING_FEATURE_IDS}}
 
-Start by orienting yourself:
+### Workflow for EACH feature:
+1. Call `feature_get_by_id` with the feature ID
+2. Read the feature's verification steps
+3. Test the feature in the browser
+4. Call `feature_mark_passing` or `feature_mark_failing`
+5. Move to the next feature
 
-```bash
+---
-# 1. See your working directory
-pwd
 
-# 2. List files to understand project structure
+### STEP 1: GET YOUR ASSIGNED FEATURE(S)
-ls -la
 
-# 3. Read progress notes from previous sessions (last 200 lines)
+Your features have been pre-assigned by the orchestrator. For each feature ID listed above, use `feature_get_by_id` to get the details:
-tail -200 claude-progress.txt
-
-# 4. Check recent git history
-git log --oneline -10
-```
-
-Then use MCP tools to check feature status:
 
 ```
-# 5. Get progress statistics
+Use the feature_get_by_id tool with feature_id=<ID>
-Use the feature_get_stats tool
 ```
 
-### STEP 2: START SERVERS (IF NOT RUNNING)
+### STEP 2: VERIFY THE FEATURE
-
-If `init.sh` exists, run it:
-
-```bash
-chmod +x init.sh
-./init.sh
-```
-
-Otherwise, start servers manually.
-
-### STEP 3: GET YOUR ASSIGNED FEATURE
-
-Your feature has been pre-assigned by the orchestrator. Use `feature_get_by_id` to get the details:
-
-```
-Use the feature_get_by_id tool with feature_id={your_assigned_id}
-```
-
-The orchestrator has already claimed this feature for testing (set `testing_in_progress=true`).
-
-**CRITICAL:** You MUST call `feature_release_testing` when done, regardless of pass/fail.
-
-### STEP 4: VERIFY THE FEATURE
 
 **CRITICAL:** You MUST verify the feature through the actual UI using browser automation.
 
@@ -81,21 +52,11 @@ Use browser automation tools:
 - browser_console_messages - Get browser console output (check for errors)
 - browser_network_requests - Monitor API calls
 
-### STEP 5: HANDLE RESULTS
+### STEP 3: HANDLE RESULTS
 
 #### If the feature PASSES:
 
-The feature still works correctly. Release the claim and end your session:
+The feature still works correctly. **DO NOT** call feature_mark_passing again -- it's already passing. End your session.
-
-```
-# Release the testing claim (tested_ok=true)
-Use the feature_release_testing tool with feature_id={id} and tested_ok=true
-
-# Log the successful verification
-echo "[Testing] Feature #{id} verified - still passing" >> claude-progress.txt
-```
-
-**DO NOT** call feature_mark_passing again - it's already passing.
 
 #### If the feature FAILS (regression found):
 
@@ -125,13 +86,7 @@ A regression has been introduced. You MUST fix it:
    Use the feature_mark_passing tool with feature_id={id}
    ```
 
-6. **Release the testing claim:**
+6. **Commit the fix:**
-   ```
-   Use the feature_release_testing tool with feature_id={id} and tested_ok=false
-   ```
-   Note: tested_ok=false because we found a regression (even though we fixed it).
-
-7. **Commit the fix:**
    ```bash
    git add .
    git commit -m "Fix regression in [feature name]
@@ -141,14 +96,6 @@ A regression has been introduced. You MUST fix it:
    - Verified with browser automation"
    ```
 
-### STEP 6: UPDATE PROGRESS AND END
-
-Update `claude-progress.txt`:
-
-```bash
-echo "[Testing] Session complete - verified/fixed feature #{id}" >> claude-progress.txt
-```
-
 ---
 
 ## AVAILABLE MCP TOOLS
@@ -156,12 +103,11 @@ echo "[Testing] Session complete - verified/fixed feature #{id}" >> claude-progr
 ### Feature Management
 - `feature_get_stats` - Get progress overview (passing/in_progress/total counts)
 - `feature_get_by_id` - Get your assigned feature details
-- `feature_release_testing` - **REQUIRED** - Release claim after testing (pass tested_ok=true/false)
 - `feature_mark_failing` - Mark a feature as failing (when you find a regression)
 - `feature_mark_passing` - Mark a feature as passing (after fixing a regression)
 
 ### Browser Automation (Playwright)
-All interaction tools have **built-in auto-wait** - no manual timeouts needed.
+All interaction tools have **built-in auto-wait** -- no manual timeouts needed.
 
 - `browser_navigate` - Navigate to URL
 - `browser_take_screenshot` - Capture screenshot
@@ -178,9 +124,7 @@ All interaction tools have **built-in auto-wait** - no manual timeouts needed.
 
 ## IMPORTANT REMINDERS
 
-**Your Goal:** Verify that passing features still work, and fix any regressions found.
+**Your Goal:** Test each assigned feature thoroughly. Verify it still works, and fix any regression found. Process ALL features in your list before ending your session.
-
-**This Session's Goal:** Test ONE feature thoroughly.
 
 **Quality Bar:**
 - Zero console errors
@@ -188,21 +132,15 @@ All interaction tools have **built-in auto-wait** - no manual timeouts needed.
 - Visual appearance correct
 - API calls succeed
 
-**CRITICAL - Always release your claim:**
-- Call `feature_release_testing` when done, whether pass or fail
-- Pass `tested_ok=true` if the feature passed
-- Pass `tested_ok=false` if you found a regression
-
 **If you find a regression:**
 1. Mark the feature as failing immediately
 2. Fix the issue
 3. Verify the fix with browser automation
 4. Mark as passing only after thorough verification
-5. Release the testing claim with `tested_ok=false`
+5. Commit the fix
-6. Commit the fix
 
-**You have one iteration.** Focus on testing ONE feature thoroughly.
+**You have one iteration.** Test all assigned features before ending.
 
 ---
 
-Begin by running Step 1 (Get Your Bearings).
+Begin by running Step 1 for the first feature in your assigned list.

.env.example

@@ -15,6 +15,25 @@
 # - false: Browser opens a visible window (useful for debugging)
 # PLAYWRIGHT_HEADLESS=true
 
+# Extra Read Paths (Optional)
+# Comma-separated list of absolute paths for read-only access to external directories.
+# The agent can read files from these paths but cannot write to them.
+# Useful for referencing documentation, shared libraries, or other projects.
+# Example: EXTRA_READ_PATHS=/Volumes/Data/dev,/Users/shared/libs
+# EXTRA_READ_PATHS=
+
+# Google Cloud Vertex AI Configuration (Optional)
+# To use Claude via Vertex AI on Google Cloud Platform, uncomment and set these variables.
+# Requires: gcloud CLI installed and authenticated (run: gcloud auth application-default login)
+# Note: Use @ instead of - in model names (e.g., claude-opus-4-5@20251101)
+#
+# CLAUDE_CODE_USE_VERTEX=1
+# CLOUD_ML_REGION=us-east5
+# ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
+# ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-5@20251101
+# ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5@20250929
+# ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-3-5-haiku@20241022
+
 # GLM/Alternative API Configuration (Optional)
 # To use Zhipu AI's GLM models instead of Claude, uncomment and set these variables.
 # This only affects AutoCoder - your global Claude Code settings remain unchanged.

.gitignore

@@ -76,6 +76,8 @@ ui/playwright-report/
 .dmypy.json
 dmypy.json
 
+.ruff_cache/
+
 # ===================
 # Claude Code
 # ===================

CLAUDE.md

@@ -2,6 +2,12 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Prerequisites
+
+- Python 3.11+
+- Node.js 20+ (for UI development)
+- Claude Code CLI
+
 ## Project Overview
 
 This is an autonomous coding agent system with a React-based UI. It uses the Claude Agent SDK to build complete applications over multiple sessions using a two-agent pattern:
@@ -86,12 +92,40 @@ npm run lint     # Run ESLint
 
 **Note:** The `start_ui.bat` script serves the pre-built UI from `ui/dist/`. After making UI changes, run `npm run build` in the `ui/` directory.
 
+## Testing
+
+### Python
+
+```bash
+ruff check .                      # Lint
+mypy .                            # Type check
+python test_security.py           # Security unit tests (163 tests)
+python test_security_integration.py  # Integration tests (9 tests)
+```
+
+### React UI
+
+```bash
+cd ui
+npm run lint          # ESLint
+npm run build         # Type check + build
+npm run test:e2e      # Playwright end-to-end tests
+npm run test:e2e:ui   # Playwright tests with UI
+```
+
+### Code Quality
+
+Configuration in `pyproject.toml`:
+- ruff: Line length 120, Python 3.11 target
+- mypy: Strict return type checking, ignores missing imports
+
 ## Architecture
 
 ### Core Python Modules
 
 - `start.py` - CLI launcher with project creation/selection menu
 - `autonomous_agent_demo.py` - Entry point for running the agent
+- `autocoder_paths.py` - Central path resolution with dual-path backward compatibility and migration
 - `agent.py` - Agent session loop using Claude Agent SDK
 - `client.py` - ClaudeSDKClient configuration with security hooks and MCP servers
 - `security.py` - Bash command allowlist validation (ALLOWED_COMMANDS whitelist)
@@ -141,7 +175,7 @@ MCP tools available to the agent:
 
 ### React UI (ui/)
 
-- Tech stack: React 18, TypeScript, TanStack Query, Tailwind CSS v4, Radix UI, dagre (graph layout)
+- Tech stack: React 19, TypeScript, TanStack Query, Tailwind CSS v4, Radix UI, dagre (graph layout)
 - `src/App.tsx` - Main app with project selection, kanban board, agent controls
 - `src/hooks/useWebSocket.ts` - Real-time updates via WebSocket (progress, agent status, logs, agent updates)
 - `src/hooks/useProjects.ts` - React Query hooks for API calls
@@ -164,12 +198,17 @@ Keyboard shortcuts (press `?` for help):
 ### Project Structure for Generated Apps
 
 Projects can be stored in any directory (registered in `~/.autocoder/registry.db`). Each project contains:
-- `prompts/app_spec.txt` - Application specification (XML format)
+- `.autocoder/prompts/app_spec.txt` - Application specification (XML format)
-- `prompts/initializer_prompt.md` - First session prompt
+- `.autocoder/prompts/initializer_prompt.md` - First session prompt
-- `prompts/coding_prompt.md` - Continuation session prompt
+- `.autocoder/prompts/coding_prompt.md` - Continuation session prompt
-- `features.db` - SQLite database with feature test cases
+- `.autocoder/features.db` - SQLite database with feature test cases
-- `.agent.lock` - Lock file to prevent multiple agent instances
+- `.autocoder/.agent.lock` - Lock file to prevent multiple agent instances
 - `.autocoder/allowed_commands.yaml` - Project-specific bash command allowlist (optional)
+- `.autocoder/.gitignore` - Ignores runtime files
+- `CLAUDE.md` - Stays at project root (SDK convention)
+- `app_spec.txt` - Root copy for agent template compatibility
+
+Legacy projects with files at root level (e.g., `features.db`, `prompts/`) are auto-migrated to `.autocoder/` on next agent start. Dual-path resolution ensures old and new layouts work transparently.
 
 ### Security Model
 
@@ -178,6 +217,46 @@ Defense-in-depth approach configured in `client.py`:
 2. Filesystem restricted to project directory only
 3. Bash commands validated using hierarchical allowlist system
 
+#### Extra Read Paths (Cross-Project File Access)
+
+The agent can optionally read files from directories outside the project folder via the `EXTRA_READ_PATHS` environment variable. This enables referencing documentation, shared libraries, or other projects.
+
+**Configuration:**
+
+```bash
+# Single path
+EXTRA_READ_PATHS=/Users/me/docs
+
+# Multiple paths (comma-separated)
+EXTRA_READ_PATHS=/Users/me/docs,/opt/shared-libs,/Volumes/Data/reference
+```
+
+**Security Controls:**
+
+All paths are validated before being granted read access:
+- Must be absolute paths (not relative)
+- Must exist and be directories
+- Paths are canonicalized via `Path.resolve()` to prevent `..` traversal attacks
+- Sensitive directories are blocked (see blocklist below)
+- Only Read, Glob, and Grep operations are allowed (no Write/Edit)
+
+**Blocked Sensitive Directories:**
+
+The following directories (relative to home) are always blocked:
+- `.ssh`, `.aws`, `.azure`, `.kube` - Cloud/SSH credentials
+- `.gnupg`, `.gpg`, `.password-store` - Encryption keys
+- `.docker`, `.config/gcloud` - Container/cloud configs
+- `.npmrc`, `.pypirc`, `.netrc` - Package manager credentials
+
+**Example Output:**
+
+```
+Created security settings at /path/to/project/.claude_settings.json
+   - Sandbox enabled (OS-level bash isolation)
+   - Filesystem restricted to: /path/to/project
+   - Extra read paths (validated): /Users/me/docs, /opt/shared-libs
+```
+
 #### Per-Project Allowed Commands
 
 The agent's bash command access is controlled through a hierarchical configuration system:
@@ -237,15 +316,6 @@ blocked_commands:
 - Blocklisted commands (sudo, dd, shutdown, etc.) can NEVER be allowed
 - Org-level blocked commands cannot be overridden by project configs
 
-**Testing:**
-```bash
-# Unit tests (136 tests - fast)
-python test_security.py
-
-# Integration tests (9 tests - uses real hooks)
-python test_security_integration.py
-```
-
 **Files:**
 - `security.py` - Command validation logic and hardcoded blocklist
 - `test_security.py` - Unit tests for security system (136 tests)
@@ -254,7 +324,6 @@ python test_security_integration.py
 - `examples/project_allowed_commands.yaml` - Project config example (all commented by default)
 - `examples/org_config.yaml` - Org config example (all commented by default)
 - `examples/README.md` - Comprehensive guide with use cases, testing, and troubleshooting
-- `PHASE3_SPEC.md` - Specification for mid-session approval feature (future enhancement)
 
 ### Ollama Local Models (Optional)
 
@@ -300,12 +369,12 @@ Run coding agents using local models via Ollama v0.14.0+:
 
 ### Prompt Loading Fallback Chain
 
-1. Project-specific: `{project_dir}/prompts/{name}.md`
+1. Project-specific: `{project_dir}/.autocoder/prompts/{name}.md` (or legacy `{project_dir}/prompts/{name}.md`)
 2. Base template: `.claude/templates/{name}.template.md`
 
 ### Agent Session Flow
 
-1. Check if `features.db` has features (determines initializer vs coding agent)
+1. Check if `.autocoder/features.db` has features (determines initializer vs coding agent)
 2. Create ClaudeSDKClient with security settings
 3. Send prompt and stream response
 4. Auto-continue with 3-second delay between sessions
@@ -334,55 +403,7 @@ The orchestrator enforces strict bounds on concurrent processes:
 - `MAX_PARALLEL_AGENTS = 5` - Maximum concurrent coding agents
 - `MAX_TOTAL_AGENTS = 10` - Hard limit on total agents (coding + testing)
 - Testing agents are capped at `max_concurrency` (same as coding agents)
-
+- Total process count never exceeds 11 Python processes (1 orchestrator + 5 coding + 5 testing)
-**Expected process count during normal operation:**
-- 1 orchestrator process
-- Up to 5 coding agents
-- Up to 5 testing agents
-- Total: never exceeds 11 Python processes
-
-**Stress Test Verification:**
-
-```bash
-# Windows - verify process bounds
-# 1. Note baseline count
-tasklist | findstr python | find /c /v ""
-
-# 2. Start parallel agent (max concurrency)
-python autonomous_agent_demo.py --project-dir test --parallel --max-concurrency 5
-
-# 3. During run - should NEVER exceed baseline + 11
-tasklist | findstr python | find /c /v ""
-
-# 4. After stop via UI - should return to baseline
-tasklist | findstr python | find /c /v ""
-```
-
-```bash
-# macOS/Linux - verify process bounds
-# 1. Note baseline count
-pgrep -c python
-
-# 2. Start parallel agent
-python autonomous_agent_demo.py --project-dir test --parallel --max-concurrency 5
-
-# 3. During run - should NEVER exceed baseline + 11
-pgrep -c python
-
-# 4. After stop - should return to baseline
-pgrep -c python
-```
-
-**Log Verification:**
-
-```bash
-# Check spawn vs completion balance
-grep "Started testing agent" orchestrator_debug.log | wc -l
-grep "Testing agent.*completed\|failed" orchestrator_debug.log | wc -l
-
-# Watch for cap enforcement messages
-grep "at max testing agents\|At max total agents" orchestrator_debug.log
-```
 
 ### Design System
 

CUSTOM_UPDATES.md

@@ -1,228 +0,0 @@
-# Custom Updates - AutoCoder
-
-This document tracks all customizations made to AutoCoder that deviate from the upstream repository. Reference this file before any updates to preserve these changes.
-
----
-
-## Table of Contents
-
-1. [UI Theme Customization](#1-ui-theme-customization)
-2. [Playwright Browser Configuration](#2-playwright-browser-configuration)
-3. [Update Checklist](#update-checklist)
-
----
-
-## 1. UI Theme Customization
-
-### Overview
-
-The UI has been customized from the default **neobrutalism** style to a clean **Twitter/Supabase-style** design.
-
-**Design Changes:**
-- No shadows
-- Thin borders (1px)
-- Rounded corners (1.3rem base)
-- Blue accent color (Twitter blue)
-- Clean typography (Open Sans)
-
-### Modified Files
-
-#### `ui/src/styles/custom-theme.css`
-
-**Purpose:** Main theme override file that replaces neo design with clean Twitter style.
-
-**Key Changes:**
-- All `--shadow-neo-*` variables set to `none`
-- All status colors (`pending`, `progress`, `done`) use Twitter blue
-- Rounded corners: `--radius-neo-lg: 1.3rem`
-- Font: Open Sans
-- Removed all transform effects on hover
-- Dark mode with proper contrast
-
-**CSS Variables (Light Mode):**
-```css
---color-neo-accent: oklch(0.6723 0.1606 244.9955);  /* Twitter blue */
---color-neo-pending: oklch(0.6723 0.1606 244.9955);
---color-neo-progress: oklch(0.6723 0.1606 244.9955);
---color-neo-done: oklch(0.6723 0.1606 244.9955);
-```
-
-**CSS Variables (Dark Mode):**
-```css
---color-neo-bg: oklch(0.08 0 0);
---color-neo-card: oklch(0.16 0.005 250);
---color-neo-border: oklch(0.30 0 0);
-```
-
-**How to preserve:** This file should NOT be overwritten. It loads after `globals.css` and overrides it.
-
----
-
-#### `ui/src/components/KanbanColumn.tsx`
-
-**Purpose:** Modified to support themeable kanban columns without inline styles.
-
-**Changes:**
-
-1. **colorMap changed from inline colors to CSS classes:**
-```tsx
-// BEFORE (original):
-const colorMap = {
-  pending: 'var(--color-neo-pending)',
-  progress: 'var(--color-neo-progress)',
-  done: 'var(--color-neo-done)',
-}
-
-// AFTER (customized):
-const colorMap = {
-  pending: 'kanban-header-pending',
-  progress: 'kanban-header-progress',
-  done: 'kanban-header-done',
-}
-```
-
-2. **Column div uses CSS class instead of inline style:**
-```tsx
-// BEFORE:
-<div className="neo-card overflow-hidden" style={{ borderColor: colorMap[color] }}>
-
-// AFTER:
-<div className={`neo-card overflow-hidden kanban-column ${colorMap[color]}`}>
-```
-
-3. **Header div simplified (removed duplicate color class):**
-```tsx
-// BEFORE:
-<div className={`... ${colorMap[color]}`} style={{ backgroundColor: colorMap[color] }}>
-
-// AFTER:
-<div className="kanban-header px-4 py-3 border-b border-[var(--color-neo-border)]">
-```
-
-4. **Title text color:**
-```tsx
-// BEFORE:
-text-[var(--color-neo-text-on-bright)]
-
-// AFTER:
-text-[var(--color-neo-text)]
-```
-
----
-
-## 2. Playwright Browser Configuration
-
-### Overview
-
-Changed default Playwright settings for better performance:
-- **Default browser:** Firefox (lower CPU usage)
-- **Default mode:** Headless (saves resources)
-
-### Modified Files
-
-#### `client.py`
-
-**Changes:**
-
-```python
-# BEFORE:
-DEFAULT_PLAYWRIGHT_HEADLESS = False
-
-# AFTER:
-DEFAULT_PLAYWRIGHT_HEADLESS = True
-DEFAULT_PLAYWRIGHT_BROWSER = "firefox"
-```
-
-**New function added:**
-```python
-def get_playwright_browser() -> str:
-    """
-    Get the browser to use for Playwright.
-    Options: chrome, firefox, webkit, msedge
-    Firefox is recommended for lower CPU usage.
-    """
-    return os.getenv("PLAYWRIGHT_BROWSER", DEFAULT_PLAYWRIGHT_BROWSER).lower()
-```
-
-**Playwright args updated:**
-```python
-playwright_args = [
-    "@playwright/mcp@latest",
-    "--viewport-size", "1280x720",
-    "--browser", browser,  # NEW: configurable browser
-]
-```
-
----
-
-#### `.env.example`
-
-**Updated documentation:**
-```bash
-# PLAYWRIGHT_BROWSER: Which browser to use for testing
-# - firefox: Lower CPU usage, recommended (default)
-# - chrome: Google Chrome
-# - webkit: Safari engine
-# - msedge: Microsoft Edge
-# PLAYWRIGHT_BROWSER=firefox
-
-# PLAYWRIGHT_HEADLESS: Run browser without visible window
-# - true: Browser runs in background, saves CPU (default)
-# - false: Browser opens a visible window (useful for debugging)
-# PLAYWRIGHT_HEADLESS=true
-```
-
----
-
-## 3. Update Checklist
-
-When updating AutoCoder from upstream, verify these items:
-
-### UI Changes
-- [ ] `ui/src/styles/custom-theme.css` is preserved
-- [ ] `ui/src/components/KanbanColumn.tsx` changes are preserved
-- [ ] Run `npm run build` in `ui/` directory
-- [ ] Test both light and dark modes
-
-### Backend Changes
-- [ ] `client.py` - Playwright browser/headless defaults preserved
-- [ ] `.env.example` - Documentation updates preserved
-
-### General
-- [ ] Verify Playwright uses Firefox by default
-- [ ] Check that browser runs headless by default
-
----
-
-## Reverting to Defaults
-
-### UI Only
-```bash
-rm ui/src/styles/custom-theme.css
-git checkout ui/src/components/KanbanColumn.tsx
-cd ui && npm run build
-```
-
-### Backend Only
-```bash
-git checkout client.py .env.example
-```
-
----
-
-## Files Summary
-
-| File | Type | Change Description |
-|------|------|-------------------|
-| `ui/src/styles/custom-theme.css` | UI | Twitter-style theme |
-| `ui/src/components/KanbanColumn.tsx` | UI | Themeable kanban columns |
-| `ui/src/main.tsx` | UI | Imports custom theme |
-| `client.py` | Backend | Firefox + headless defaults |
-| `.env.example` | Config | Updated documentation |
-
----
-
-## Last Updated
-
-**Date:** January 2026
-**PR:** #93 - Twitter-style UI theme with custom theme override system

SAMPLE_PROMPT.md

@@ -1,22 +0,0 @@
-Let's call it Simple Todo. This is a really simple web app that I can use to track my to-do items using a Kanban
-board. I should be able to add to-dos and then drag and drop them through the Kanban board. The different columns in
-the Kanban board are:
-
-- To Do
-- In Progress
-- Done
-
-The app should use a neobrutalism design.
-
-There is no need for user authentication either. All the to-dos will be stored in local storage, so each user has
-access to all of their to-dos when they open their browser. So do not worry about implementing a backend with user
-authentication or a database. Simply store everything in local storage. As for the design, please try to avoid AI
-slop, so use your front-end design skills to design something beautiful and practical. As for the content of the
-to-dos, we should store:
-
-- The name or the title at the very least
-- Optionally, we can also set tags, due dates, and priorities which should be represented as beautiful little badges
-  on the to-do card Users should have the ability to easily clear out all the completed To-Dos. They should also be
-  able to filter and search for To-Dos as well.
-
-You choose the rest. Keep it simple. Should be 25 features.

agent.py

@@ -23,14 +23,27 @@ if sys.platform == "win32":
     sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace", line_buffering=True)
 
 from client import create_client
-from progress import count_passing_tests, has_features, print_progress_summary, print_session_header
+from progress import (
+    count_passing_tests,
+    has_features,
+    print_progress_summary,
+    print_session_header,
+)
 from prompts import (
     copy_spec_to_project,
+    get_batch_feature_prompt,
     get_coding_prompt,
     get_initializer_prompt,
     get_single_feature_prompt,
     get_testing_prompt,
 )
+from rate_limit_utils import (
+    calculate_error_backoff,
+    calculate_rate_limit_backoff,
+    clamp_retry_delay,
+    is_rate_limit_error,
+    parse_retry_after,
+)
 
 # Configuration
 AUTO_CONTINUE_DELAY_SECONDS = 3
@@ -106,8 +119,19 @@ async def run_agent_session(
         return "continue", response_text
 
     except Exception as e:
-        print(f"Error during agent session: {e}")
+        error_str = str(e)
-        return "error", str(e)
+        print(f"Error during agent session: {error_str}")
+
+        # Detect rate limit errors from exception message
+        if is_rate_limit_error(error_str):
+            # Try to extract retry-after time from error
+            retry_seconds = parse_retry_after(error_str)
+            if retry_seconds is not None:
+                return "rate_limit", str(retry_seconds)
+            else:
+                return "rate_limit", "unknown"
+
+        return "error", error_str
 
 
 async def run_autonomous_agent(
@@ -116,8 +140,10 @@ async def run_autonomous_agent(
     max_iterations: Optional[int] = None,
     yolo_mode: bool = False,
     feature_id: Optional[int] = None,
+    feature_ids: Optional[list[int]] = None,
     agent_type: Optional[str] = None,
     testing_feature_id: Optional[int] = None,
+    testing_feature_ids: Optional[list[int]] = None,
 ) -> None:
     """
     Run the autonomous agent loop.
@@ -128,8 +154,10 @@ async def run_autonomous_agent(
         max_iterations: Maximum number of iterations (None for unlimited)
         yolo_mode: If True, skip browser testing in coding agent prompts
         feature_id: If set, work only on this specific feature (used by orchestrator for coding agents)
+        feature_ids: If set, work on these features in batch (used by orchestrator for batch mode)
         agent_type: Type of agent: "initializer", "coding", "testing", or None (auto-detect)
-        testing_feature_id: For testing agents, the pre-claimed feature ID to test
+        testing_feature_id: For testing agents, the pre-claimed feature ID to test (legacy single mode)
+        testing_feature_ids: For testing agents, list of feature IDs to batch test
     """
     print("\n" + "=" * 70)
     print("  AUTONOMOUS CODING AGENT")
@@ -140,7 +168,9 @@ async def run_autonomous_agent(
         print(f"Agent type: {agent_type}")
     if yolo_mode:
         print("Mode: YOLO (testing agents disabled)")
-    if feature_id:
+    if feature_ids and len(feature_ids) > 1:
+        print(f"Feature batch: {', '.join(f'#{fid}' for fid in feature_ids)}")
+    elif feature_id:
         print(f"Feature assignment: #{feature_id}")
     if max_iterations:
         print(f"Max iterations: {max_iterations}")
@@ -183,6 +213,8 @@ async def run_autonomous_agent(
 
     # Main loop
     iteration = 0
+    rate_limit_retries = 0  # Track consecutive rate limit errors for exponential backoff
+    error_retries = 0  # Track consecutive non-rate-limit errors
 
     while True:
         iteration += 1
@@ -212,23 +244,29 @@ async def run_autonomous_agent(
         import os
         if agent_type == "testing":
             agent_id = f"testing-{os.getpid()}"  # Unique ID for testing agents
+        elif feature_ids and len(feature_ids) > 1:
+            agent_id = f"batch-{feature_ids[0]}"
         elif feature_id:
             agent_id = f"feature-{feature_id}"
         else:
             agent_id = None
-        client = create_client(project_dir, model, yolo_mode=yolo_mode, agent_id=agent_id)
+        client = create_client(project_dir, model, yolo_mode=yolo_mode, agent_id=agent_id, agent_type=agent_type)
 
         # Choose prompt based on agent type
         if agent_type == "initializer":
             prompt = get_initializer_prompt(project_dir)
         elif agent_type == "testing":
-            prompt = get_testing_prompt(project_dir, testing_feature_id)
+            prompt = get_testing_prompt(project_dir, testing_feature_id, testing_feature_ids)
-        elif feature_id:
+        elif feature_ids and len(feature_ids) > 1:
+            # Batch mode (used by orchestrator for multi-feature coding agents)
+            prompt = get_batch_feature_prompt(feature_ids, project_dir, yolo_mode)
+        elif feature_id or (feature_ids is not None and len(feature_ids) == 1):
             # Single-feature mode (used by orchestrator for coding agents)
-            prompt = get_single_feature_prompt(feature_id, project_dir, yolo_mode)
+            fid = feature_id if feature_id is not None else feature_ids[0]  # type: ignore[index]
+            prompt = get_single_feature_prompt(fid, project_dir, yolo_mode)
         else:
             # General coding prompt (legacy path)
-            prompt = get_coding_prompt(project_dir)
+            prompt = get_coding_prompt(project_dir, yolo_mode=yolo_mode)
 
         # Run session with async context manager
         # Wrap in try/except to handle MCP server startup failures gracefully
@@ -250,13 +288,28 @@ async def run_autonomous_agent(
 
         # Handle status
         if status == "continue":
+            # Reset error retries on success; rate-limit retries reset only if no signal
+            error_retries = 0
+            reset_rate_limit_retries = True
+
             delay_seconds = AUTO_CONTINUE_DELAY_SECONDS
             target_time_str = None
 
-            if "limit reached" in response.lower():
+            # Check for rate limit indicators in response text
-                print("Claude Agent SDK indicated limit reached.")
+            if is_rate_limit_error(response):
+                print("Claude Agent SDK indicated rate limit reached.")
+                reset_rate_limit_retries = False
 
-                # Try to parse reset time from response
+                # Try to extract retry-after from response text first
+                retry_seconds = parse_retry_after(response)
+                if retry_seconds is not None:
+                    delay_seconds = clamp_retry_delay(retry_seconds)
+                else:
+                    # Use exponential backoff when retry-after unknown
+                    delay_seconds = calculate_rate_limit_backoff(rate_limit_retries)
+                    rate_limit_retries += 1
+
+                # Try to parse reset time from response (more specific format)
                 match = re.search(
                     r"(?i)\bresets(?:\s+at)?\s+(\d+)(?::(\d+))?\s*(am|pm)\s*\(([^)]+)\)",
                     response,
@@ -285,9 +338,7 @@ async def run_autonomous_agent(
                             target += timedelta(days=1)
 
                         delta = target - now
-                        delay_seconds = min(
+                        delay_seconds = min(max(int(delta.total_seconds()), 1), 24 * 60 * 60)
-                            delta.total_seconds(), 24 * 60 * 60
-                        )  # Clamp to 24 hours max
                         target_time_str = target.strftime("%B %d, %Y at %I:%M %p %Z")
 
                     except Exception as e:
@@ -316,20 +367,56 @@ async def run_autonomous_agent(
                 print("The autonomous agent has finished its work.")
                 break
 
-            # Single-feature mode OR testing agent: exit after one session
+            # Single-feature mode, batch mode, or testing agent: exit after one session
-            if feature_id is not None or agent_type == "testing":
+            if feature_ids and len(feature_ids) > 1:
+                print(f"\nBatch mode: Features {', '.join(f'#{fid}' for fid in feature_ids)} session complete.")
+                break
+            elif feature_id is not None or (feature_ids is not None and len(feature_ids) == 1):
+                fid = feature_id if feature_id is not None else feature_ids[0]  # type: ignore[index]
                 if agent_type == "testing":
                     print("\nTesting agent complete. Terminating session.")
                 else:
-                    print(f"\nSingle-feature mode: Feature #{feature_id} session complete.")
+                    print(f"\nSingle-feature mode: Feature #{fid} session complete.")
                 break
+            elif agent_type == "testing":
+                print("\nTesting agent complete. Terminating session.")
+                break
+
+            # Reset rate limit retries only if no rate limit signal was detected
+            if reset_rate_limit_retries:
+                rate_limit_retries = 0
+
+            await asyncio.sleep(delay_seconds)
+
+        elif status == "rate_limit":
+            # Smart rate limit handling with exponential backoff
+            # Reset error counter so mixed events don't inflate delays
+            error_retries = 0
+            if response != "unknown":
+                try:
+                    delay_seconds = clamp_retry_delay(int(response))
+                except (ValueError, TypeError):
+                    # Malformed value - fall through to exponential backoff
+                    response = "unknown"
+            if response == "unknown":
+                # Use exponential backoff when retry-after unknown or malformed
+                delay_seconds = calculate_rate_limit_backoff(rate_limit_retries)
+                rate_limit_retries += 1
+                print(f"\nRate limit hit. Backoff wait: {delay_seconds} seconds (attempt #{rate_limit_retries})...")
+            else:
+                print(f"\nRate limit hit. Waiting {delay_seconds} seconds before retry...")
 
             await asyncio.sleep(delay_seconds)
 
         elif status == "error":
+            # Non-rate-limit errors: linear backoff capped at 5 minutes
+            # Reset rate limit counter so mixed events don't inflate delays
+            rate_limit_retries = 0
+            error_retries += 1
+            delay_seconds = calculate_error_backoff(error_retries)
             print("\nSession encountered an error")
-            print("Will retry with a fresh session...")
+            print(f"Will retry in {delay_seconds}s (attempt #{error_retries})...")
-            await asyncio.sleep(AUTO_CONTINUE_DELAY_SECONDS)
+            await asyncio.sleep(delay_seconds)
 
         # Small delay between sessions
         if max_iterations is None or iteration < max_iterations:

api/database.py

@@ -8,7 +8,7 @@ SQLite database schema for feature storage using SQLAlchemy.
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Optional
+from typing import Generator, Optional
 
 
 def _utc_now() -> datetime:
@@ -26,13 +26,16 @@ from sqlalchemy import (
     String,
     Text,
     create_engine,
+    event,
     text,
 )
-from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import DeclarativeBase, Session, relationship, sessionmaker
-from sqlalchemy.orm import Session, relationship, sessionmaker
 from sqlalchemy.types import JSON
 
-Base = declarative_base()
+
+class Base(DeclarativeBase):
+    """SQLAlchemy 2.0 style declarative base."""
+    pass
 
 
 class Feature(Base):
@@ -180,7 +183,8 @@ class ScheduleOverride(Base):
 
 def get_database_path(project_dir: Path) -> Path:
     """Return the path to the SQLite database for a project."""
-    return project_dir / "features.db"
+    from autocoder_paths import get_features_db_path
+    return get_features_db_path(project_dir)
 
 
 def get_database_url(project_dir: Path) -> str:
@@ -307,11 +311,11 @@ def _migrate_add_schedules_tables(engine) -> None:
 
     # Create schedules table if missing
     if "schedules" not in existing_tables:
-        Schedule.__table__.create(bind=engine)
+        Schedule.__table__.create(bind=engine)  # type: ignore[attr-defined]
 
     # Create schedule_overrides table if missing
     if "schedule_overrides" not in existing_tables:
-        ScheduleOverride.__table__.create(bind=engine)
+        ScheduleOverride.__table__.create(bind=engine)  # type: ignore[attr-defined]
 
     # Add crash_count column if missing (for upgrades)
     if "schedules" in existing_tables:
@@ -332,32 +336,89 @@ def _migrate_add_schedules_tables(engine) -> None:
                 conn.commit()
 
 
+def _configure_sqlite_immediate_transactions(engine) -> None:
+    """Configure engine for IMMEDIATE transactions via event hooks.
+
+    Per SQLAlchemy docs: https://docs.sqlalchemy.org/en/20/dialects/sqlite.html
+
+    This replaces fragile pysqlite implicit transaction handling with explicit
+    BEGIN IMMEDIATE at transaction start. Benefits:
+    - Acquires write lock immediately, preventing stale reads
+    - Works correctly regardless of prior ORM operations
+    - Future-proof: won't break when pysqlite legacy mode is removed in Python 3.16
+    """
+    @event.listens_for(engine, "connect")
+    def do_connect(dbapi_connection, connection_record):
+        # Disable pysqlite's implicit transaction handling
+        dbapi_connection.isolation_level = None
+
+        # Set busy_timeout on raw connection before any transactions
+        cursor = dbapi_connection.cursor()
+        try:
+            cursor.execute("PRAGMA busy_timeout=30000")
+        finally:
+            cursor.close()
+
+    @event.listens_for(engine, "begin")
+    def do_begin(conn):
+        # Use IMMEDIATE for all transactions to prevent stale reads
+        conn.exec_driver_sql("BEGIN IMMEDIATE")
+
+
 def create_database(project_dir: Path) -> tuple:
     """
     Create database and return engine + session maker.
 
+    Uses a cache to avoid creating new engines for each request, which improves
+    performance by reusing database connections.
+
     Args:
         project_dir: Directory containing the project
 
     Returns:
         Tuple of (engine, SessionLocal)
     """
+    cache_key = project_dir.as_posix()
+
+    if cache_key in _engine_cache:
+        return _engine_cache[cache_key]
+
     db_url = get_database_url(project_dir)
-    engine = create_engine(db_url, connect_args={
+
-        "check_same_thread": False,
+    # Ensure parent directory exists (for .autocoder/ layout)
-        "timeout": 30  # Wait up to 30s for locks
+    db_path = get_database_path(project_dir)
-    })
+    db_path.parent.mkdir(parents=True, exist_ok=True)
-    Base.metadata.create_all(bind=engine)
 
     # Choose journal mode based on filesystem type
     # WAL mode doesn't work reliably on network filesystems and can cause corruption
     is_network = _is_network_path(project_dir)
     journal_mode = "DELETE" if is_network else "WAL"
 
+    engine = create_engine(db_url, connect_args={
+        "check_same_thread": False,
+        "timeout": 30  # Wait up to 30s for locks
+    })
+
+    # Set journal mode BEFORE configuring event hooks
+    # PRAGMA journal_mode must run outside of a transaction, and our event hooks
+    # start a transaction with BEGIN IMMEDIATE on every operation
     with engine.connect() as conn:
-        conn.execute(text(f"PRAGMA journal_mode={journal_mode}"))
+        # Get raw DBAPI connection to execute PRAGMA outside transaction
-        conn.execute(text("PRAGMA busy_timeout=30000"))
+        raw_conn = conn.connection.dbapi_connection
-        conn.commit()
+        if raw_conn is None:
+            raise RuntimeError("Failed to get raw DBAPI connection")
+        cursor = raw_conn.cursor()
+        try:
+            cursor.execute(f"PRAGMA journal_mode={journal_mode}")
+            cursor.execute("PRAGMA busy_timeout=30000")
+        finally:
+            cursor.close()
+
+    # Configure IMMEDIATE transactions via event hooks AFTER setting PRAGMAs
+    # This must happen before create_all() and migrations run
+    _configure_sqlite_immediate_transactions(engine)
+
+    Base.metadata.create_all(bind=engine)
 
     # Migrate existing databases
     _migrate_add_in_progress_column(engine)
@@ -369,12 +430,39 @@ def create_database(project_dir: Path) -> tuple:
     _migrate_add_schedules_tables(engine)
 
     SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+    # Cache the engine and session maker
+    _engine_cache[cache_key] = (engine, SessionLocal)
+
     return engine, SessionLocal
 
 
+def dispose_engine(project_dir: Path) -> bool:
+    """Dispose of and remove the cached engine for a project.
+
+    This closes all database connections, releasing file locks on Windows.
+    Should be called before deleting the database file.
+
+    Returns:
+        True if an engine was disposed, False if no engine was cached.
+    """
+    cache_key = project_dir.as_posix()
+
+    if cache_key in _engine_cache:
+        engine, _ = _engine_cache.pop(cache_key)
+        engine.dispose()
+        return True
+
+    return False
+
+
 # Global session maker - will be set when server starts
 _session_maker: Optional[sessionmaker] = None
 
+# Engine cache to avoid creating new engines for each request
+# Key: project directory path (as posix string), Value: (engine, SessionLocal)
+_engine_cache: dict[str, tuple] = {}
+
 
 def set_session_maker(session_maker: sessionmaker) -> None:
     """Set the global session maker."""
@@ -382,7 +470,7 @@ def set_session_maker(session_maker: sessionmaker) -> None:
     _session_maker = session_maker
 
 
-def get_db() -> Session:
+def get_db() -> Generator[Session, None, None]:
     """
     Dependency for FastAPI to get database session.
 
@@ -394,5 +482,55 @@ def get_db() -> Session:
     db = _session_maker()
     try:
         yield db
+    except Exception:
+        db.rollback()
+        raise
     finally:
         db.close()
+
+
+# =============================================================================
+# Atomic Transaction Helpers for Parallel Mode
+# =============================================================================
+# These helpers prevent database corruption when multiple processes access the
+# same SQLite database concurrently. They use IMMEDIATE transactions which
+# acquire write locks at the start (preventing stale reads) and atomic
+# UPDATE ... WHERE clauses (preventing check-then-modify races).
+
+
+from contextlib import contextmanager
+
+
+@contextmanager
+def atomic_transaction(session_maker):
+    """Context manager for atomic SQLite transactions.
+
+    Acquires a write lock immediately via BEGIN IMMEDIATE (configured by
+    engine event hooks), preventing stale reads in read-modify-write patterns.
+    This is essential for preventing race conditions in parallel mode.
+
+    Args:
+        session_maker: SQLAlchemy sessionmaker
+
+    Yields:
+        SQLAlchemy session with automatic commit/rollback
+
+    Example:
+        with atomic_transaction(session_maker) as session:
+            # All reads in this block are protected by write lock
+            feature = session.query(Feature).filter(...).first()
+            feature.priority = new_priority
+            # Commit happens automatically on exit
+    """
+    session = session_maker()
+    try:
+        yield session
+        session.commit()
+    except Exception:
+        try:
+            session.rollback()
+        except Exception:
+            pass  # Don't let rollback failure mask original error
+        raise
+    finally:
+        session.close()

api/dependency_resolver.py

@@ -7,6 +7,7 @@ Includes cycle detection, validation, and helper functions for dependency manage
 """
 
 import heapq
+from collections import deque
 from typing import TypedDict
 
 # Security: Prevent DoS via excessive dependencies
@@ -300,15 +301,21 @@ def compute_scheduling_scores(features: list[dict]) -> dict[int, float]:
                 parents[f["id"]].append(dep_id)
 
     # Calculate depths via BFS from roots
+    # Use visited set to prevent infinite loops from circular dependencies
+    # Use deque for O(1) popleft instead of list.pop(0) which is O(n)
     depths: dict[int, int] = {}
+    visited: set[int] = set()
     roots = [f["id"] for f in features if not parents[f["id"]]]
-    queue = [(root, 0) for root in roots]
+    bfs_queue: deque[tuple[int, int]] = deque((root, 0) for root in roots)
-    while queue:
+    while bfs_queue:
-        node_id, depth = queue.pop(0)
+        node_id, depth = bfs_queue.popleft()
-        if node_id not in depths or depth > depths[node_id]:
+        if node_id in visited:
-            depths[node_id] = depth
+            continue  # Skip already visited nodes (handles cycles)
+        visited.add(node_id)
+        depths[node_id] = depth
         for child_id in children[node_id]:
-            queue.append((child_id, depth + 1))
+            if child_id not in visited:
+                bfs_queue.append((child_id, depth + 1))
 
     # Handle orphaned nodes (shouldn't happen but be safe)
     for f in features:

autocoder_paths.py

@@ -0,0 +1,290 @@
+"""
+Autocoder Path Resolution
+=========================
+
+Central module for resolving paths to autocoder-generated files within a project.
+
+Implements a dual-path resolution strategy for backward compatibility:
+
+    1. Check ``project_dir / ".autocoder" / X`` (new layout)
+    2. Check ``project_dir / X`` (legacy root-level layout)
+    3. Default to the new location for fresh projects
+
+This allows existing projects with root-level ``features.db``, ``.agent.lock``,
+etc. to keep working while new projects store everything under ``.autocoder/``.
+
+The ``migrate_project_layout`` function can move an old-layout project to the
+new layout safely, with full integrity checks for SQLite databases.
+"""
+
+import logging
+import shutil
+import sqlite3
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# .gitignore content written into every .autocoder/ directory
+# ---------------------------------------------------------------------------
+_GITIGNORE_CONTENT = """\
+# Autocoder runtime files
+features.db
+features.db-wal
+features.db-shm
+assistant.db
+assistant.db-wal
+assistant.db-shm
+.agent.lock
+.devserver.lock
+.claude_settings.json
+.claude_assistant_settings.json
+.claude_settings.expand.*.json
+.progress_cache
+"""
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+def _resolve_path(project_dir: Path, filename: str) -> Path:
+    """Resolve a file path using dual-path strategy.
+
+    Checks the new ``.autocoder/`` location first, then falls back to the
+    legacy root-level location.  If neither exists, returns the new location
+    so that newly-created files land in ``.autocoder/``.
+    """
+    new = project_dir / ".autocoder" / filename
+    if new.exists():
+        return new
+    old = project_dir / filename
+    if old.exists():
+        return old
+    return new  # default for new projects
+
+
+def _resolve_dir(project_dir: Path, dirname: str) -> Path:
+    """Resolve a directory path using dual-path strategy.
+
+    Same logic as ``_resolve_path`` but intended for directories such as
+    ``prompts/``.
+    """
+    new = project_dir / ".autocoder" / dirname
+    if new.exists():
+        return new
+    old = project_dir / dirname
+    if old.exists():
+        return old
+    return new
+
+
+# ---------------------------------------------------------------------------
+# .autocoder directory management
+# ---------------------------------------------------------------------------
+
+def get_autocoder_dir(project_dir: Path) -> Path:
+    """Return the ``.autocoder`` directory path.  Does NOT create it."""
+    return project_dir / ".autocoder"
+
+
+def ensure_autocoder_dir(project_dir: Path) -> Path:
+    """Create the ``.autocoder/`` directory (if needed) and write its ``.gitignore``.
+
+    Returns:
+        The path to the ``.autocoder`` directory.
+    """
+    autocoder_dir = get_autocoder_dir(project_dir)
+    autocoder_dir.mkdir(parents=True, exist_ok=True)
+
+    gitignore_path = autocoder_dir / ".gitignore"
+    gitignore_path.write_text(_GITIGNORE_CONTENT, encoding="utf-8")
+
+    return autocoder_dir
+
+
+# ---------------------------------------------------------------------------
+# Dual-path file helpers
+# ---------------------------------------------------------------------------
+
+def get_features_db_path(project_dir: Path) -> Path:
+    """Resolve the path to ``features.db``."""
+    return _resolve_path(project_dir, "features.db")
+
+
+def get_assistant_db_path(project_dir: Path) -> Path:
+    """Resolve the path to ``assistant.db``."""
+    return _resolve_path(project_dir, "assistant.db")
+
+
+def get_agent_lock_path(project_dir: Path) -> Path:
+    """Resolve the path to ``.agent.lock``."""
+    return _resolve_path(project_dir, ".agent.lock")
+
+
+def get_devserver_lock_path(project_dir: Path) -> Path:
+    """Resolve the path to ``.devserver.lock``."""
+    return _resolve_path(project_dir, ".devserver.lock")
+
+
+def get_claude_settings_path(project_dir: Path) -> Path:
+    """Resolve the path to ``.claude_settings.json``."""
+    return _resolve_path(project_dir, ".claude_settings.json")
+
+
+def get_claude_assistant_settings_path(project_dir: Path) -> Path:
+    """Resolve the path to ``.claude_assistant_settings.json``."""
+    return _resolve_path(project_dir, ".claude_assistant_settings.json")
+
+
+def get_progress_cache_path(project_dir: Path) -> Path:
+    """Resolve the path to ``.progress_cache``."""
+    return _resolve_path(project_dir, ".progress_cache")
+
+
+def get_prompts_dir(project_dir: Path) -> Path:
+    """Resolve the path to the ``prompts/`` directory."""
+    return _resolve_dir(project_dir, "prompts")
+
+
+# ---------------------------------------------------------------------------
+# Non-dual-path helpers (always use new location)
+# ---------------------------------------------------------------------------
+
+def get_expand_settings_path(project_dir: Path, uuid_hex: str) -> Path:
+    """Return the path for an ephemeral expand-session settings file.
+
+    These files are short-lived and always stored in ``.autocoder/``.
+    """
+    return project_dir / ".autocoder" / f".claude_settings.expand.{uuid_hex}.json"
+
+
+# ---------------------------------------------------------------------------
+# Lock-file safety check
+# ---------------------------------------------------------------------------
+
+def has_agent_running(project_dir: Path) -> bool:
+    """Check whether any agent or dev-server lock file exists at either location.
+
+    Inspects both the legacy root-level paths and the new ``.autocoder/``
+    paths so that a running agent is detected regardless of project layout.
+
+    Returns:
+        ``True`` if any ``.agent.lock`` or ``.devserver.lock`` exists.
+    """
+    lock_names = (".agent.lock", ".devserver.lock")
+    for name in lock_names:
+        if (project_dir / name).exists():
+            return True
+        if (project_dir / ".autocoder" / name).exists():
+            return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Migration
+# ---------------------------------------------------------------------------
+
+def migrate_project_layout(project_dir: Path) -> list[str]:
+    """Migrate a project from the legacy root-level layout to ``.autocoder/``.
+
+    The migration is incremental and safe:
+
+    * If the agent is running (lock files present) the migration is skipped
+      entirely to avoid corrupting in-use databases.
+    * Each file/directory is migrated independently.  If any single step
+      fails the error is logged and migration continues with the remaining
+      items.  Partial migration is safe because the dual-path resolution
+      strategy will find files at whichever location they ended up in.
+
+    Returns:
+        A list of human-readable descriptions of what was migrated, e.g.
+        ``["prompts/ -> .autocoder/prompts/", "features.db -> .autocoder/features.db"]``.
+        An empty list means nothing was migrated (either everything is
+        already migrated, or the agent is running).
+    """
+    # Safety: refuse to migrate while an agent is running
+    if has_agent_running(project_dir):
+        logger.warning("Migration skipped: agent or dev-server is running for %s", project_dir)
+        return []
+
+    autocoder_dir = ensure_autocoder_dir(project_dir)
+    migrated: list[str] = []
+
+    # --- 1. Migrate prompts/ directory -----------------------------------
+    try:
+        old_prompts = project_dir / "prompts"
+        new_prompts = autocoder_dir / "prompts"
+        if old_prompts.exists() and old_prompts.is_dir() and not new_prompts.exists():
+            shutil.copytree(str(old_prompts), str(new_prompts))
+            shutil.rmtree(str(old_prompts))
+            migrated.append("prompts/ -> .autocoder/prompts/")
+            logger.info("Migrated prompts/ -> .autocoder/prompts/")
+    except Exception:
+        logger.warning("Failed to migrate prompts/ directory", exc_info=True)
+
+    # --- 2. Migrate SQLite databases (features.db, assistant.db) ---------
+    db_names = ("features.db", "assistant.db")
+    for db_name in db_names:
+        try:
+            old_db = project_dir / db_name
+            new_db = autocoder_dir / db_name
+            if old_db.exists() and not new_db.exists():
+                # Flush WAL to ensure all data is in the main database file
+                conn = sqlite3.connect(str(old_db))
+                try:
+                    cursor = conn.cursor()
+                    cursor.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+                finally:
+                    conn.close()
+
+                # Copy the main database file (WAL is now flushed)
+                shutil.copy2(str(old_db), str(new_db))
+
+                # Verify the copy is intact
+                verify_conn = sqlite3.connect(str(new_db))
+                try:
+                    verify_cursor = verify_conn.cursor()
+                    result = verify_cursor.execute("PRAGMA integrity_check").fetchone()
+                    if result is None or result[0] != "ok":
+                        logger.error(
+                            "Integrity check failed for migrated %s: %s",
+                            db_name, result,
+                        )
+                        # Remove the broken copy; old file stays in place
+                        new_db.unlink(missing_ok=True)
+                        continue
+                finally:
+                    verify_conn.close()
+
+                # Remove old database files (.db, .db-wal, .db-shm)
+                old_db.unlink(missing_ok=True)
+                for suffix in ("-wal", "-shm"):
+                    wal_file = project_dir / f"{db_name}{suffix}"
+                    wal_file.unlink(missing_ok=True)
+
+                migrated.append(f"{db_name} -> .autocoder/{db_name}")
+                logger.info("Migrated %s -> .autocoder/%s", db_name, db_name)
+        except Exception:
+            logger.warning("Failed to migrate %s", db_name, exc_info=True)
+
+    # --- 3. Migrate simple files -----------------------------------------
+    simple_files = (
+        ".agent.lock",
+        ".devserver.lock",
+        ".claude_settings.json",
+        ".claude_assistant_settings.json",
+        ".progress_cache",
+    )
+    for filename in simple_files:
+        try:
+            old_file = project_dir / filename
+            new_file = autocoder_dir / filename
+            if old_file.exists() and not new_file.exists():
+                shutil.move(str(old_file), str(new_file))
+                migrated.append(f"{filename} -> .autocoder/{filename}")
+                logger.info("Migrated %s -> .autocoder/%s", filename, filename)
+        except Exception:
+            logger.warning("Failed to migrate %s", filename, exc_info=True)
+
+    return migrated

autonomous_agent_demo.py

@@ -133,6 +133,13 @@ Authentication:
         help="Work on a specific feature ID only (used by orchestrator for coding agents)",
     )
 
+    parser.add_argument(
+        "--feature-ids",
+        type=str,
+        default=None,
+        help="Comma-separated feature IDs to implement in batch (e.g., '5,8,12')",
+    )
+
     # Agent type for subprocess mode
     parser.add_argument(
         "--agent-type",
@@ -145,7 +152,14 @@ Authentication:
         "--testing-feature-id",
         type=int,
         default=None,
-        help="Feature ID to regression test (used by orchestrator for testing agents)",
+        help="Feature ID to regression test (used by orchestrator for testing agents, legacy single mode)",
+    )
+
+    parser.add_argument(
+        "--testing-feature-ids",
+        type=str,
+        default=None,
+        help="Comma-separated feature IDs to regression test in batch (e.g., '5,12,18')",
     )
 
     # Testing agent configuration
@@ -156,6 +170,20 @@ Authentication:
         help="Testing agents per coding agent (0-3, default: 1). Set to 0 to disable testing agents.",
     )
 
+    parser.add_argument(
+        "--testing-batch-size",
+        type=int,
+        default=3,
+        help="Number of features per testing batch (1-5, default: 3)",
+    )
+
+    parser.add_argument(
+        "--batch-size",
+        type=int,
+        default=3,
+        help="Max features per coding agent batch (1-3, default: 3)",
+    )
+
     return parser.parse_args()
 
 
@@ -193,6 +221,30 @@ def main() -> None:
             print("Use an absolute path or register the project first.")
             return
 
+    # Migrate project layout to .autocoder/ if needed (idempotent, safe)
+    from autocoder_paths import migrate_project_layout
+    migrated = migrate_project_layout(project_dir)
+    if migrated:
+        print(f"Migrated project files to .autocoder/: {', '.join(migrated)}", flush=True)
+
+    # Parse batch testing feature IDs (comma-separated string -> list[int])
+    testing_feature_ids: list[int] | None = None
+    if args.testing_feature_ids:
+        try:
+            testing_feature_ids = [int(x.strip()) for x in args.testing_feature_ids.split(",") if x.strip()]
+        except ValueError:
+            print(f"Error: --testing-feature-ids must be comma-separated integers, got: {args.testing_feature_ids}")
+            return
+
+    # Parse batch coding feature IDs (comma-separated string -> list[int])
+    coding_feature_ids: list[int] | None = None
+    if args.feature_ids:
+        try:
+            coding_feature_ids = [int(x.strip()) for x in args.feature_ids.split(",") if x.strip()]
+        except ValueError:
+            print(f"Error: --feature-ids must be comma-separated integers, got: {args.feature_ids}")
+            return
+
     try:
         if args.agent_type:
             # Subprocess mode - spawned by orchestrator for a specific role
@@ -203,8 +255,10 @@ def main() -> None:
                     max_iterations=args.max_iterations or 1,
                     yolo_mode=args.yolo,
                     feature_id=args.feature_id,
+                    feature_ids=coding_feature_ids,
                     agent_type=args.agent_type,
                     testing_feature_id=args.testing_feature_id,
+                    testing_feature_ids=testing_feature_ids,
                 )
             )
         else:
@@ -223,6 +277,8 @@ def main() -> None:
                     model=args.model,
                     yolo_mode=args.yolo,
                     testing_agent_ratio=args.testing_ratio,
+                    testing_batch_size=args.testing_batch_size,
+                    batch_size=args.batch_size,
                 )
             )
     except KeyboardInterrupt:

client.py

@@ -7,6 +7,7 @@ Functions for creating and configuring the Claude Agent SDK client.
 
 import json
 import os
+import re
 import shutil
 import sys
 from pathlib import Path
@@ -15,7 +16,8 @@ from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient
 from claude_agent_sdk.types import HookContext, HookInput, HookMatcher, SyncHookJSONOutput
 from dotenv import load_dotenv
 
-from security import bash_security_hook
+from env_constants import API_ENV_VARS
+from security import SENSITIVE_DIRECTORIES, bash_security_hook
 
 # Load environment variables from .env file if present
 load_dotenv()
@@ -30,17 +32,44 @@ DEFAULT_PLAYWRIGHT_HEADLESS = True
 # Firefox is recommended for lower CPU usage
 DEFAULT_PLAYWRIGHT_BROWSER = "firefox"
 
-# Environment variables to pass through to Claude CLI for API configuration
+# Extra read paths for cross-project file access (read-only)
-# These allow using alternative API endpoints (e.g., GLM via z.ai) without
+# Set EXTRA_READ_PATHS environment variable with comma-separated absolute paths
-# affecting the user's global Claude Code settings
+# Example: EXTRA_READ_PATHS=/Volumes/Data/dev,/Users/shared/libs
-API_ENV_VARS = [
+EXTRA_READ_PATHS_VAR = "EXTRA_READ_PATHS"
-    "ANTHROPIC_BASE_URL",              # Custom API endpoint (e.g., https://api.z.ai/api/anthropic)
+
-    "ANTHROPIC_AUTH_TOKEN",            # API authentication token
+# Sensitive directories that should never be allowed via EXTRA_READ_PATHS.
-    "API_TIMEOUT_MS",                  # Request timeout in milliseconds
+# Delegates to the canonical SENSITIVE_DIRECTORIES set in security.py so that
-    "ANTHROPIC_DEFAULT_SONNET_MODEL",  # Model override for Sonnet
+# this blocklist and the filesystem browser API share a single source of truth.
-    "ANTHROPIC_DEFAULT_OPUS_MODEL",    # Model override for Opus
+EXTRA_READ_PATHS_BLOCKLIST = SENSITIVE_DIRECTORIES
-    "ANTHROPIC_DEFAULT_HAIKU_MODEL",   # Model override for Haiku
+
-]
+def convert_model_for_vertex(model: str) -> str:
+    """
+    Convert model name format for Vertex AI compatibility.
+
+    Vertex AI uses @ to separate model name from version (e.g., claude-opus-4-5@20251101)
+    while the Anthropic API uses - (e.g., claude-opus-4-5-20251101).
+
+    Args:
+        model: Model name in Anthropic format (with hyphens)
+
+    Returns:
+        Model name in Vertex AI format (with @ before date) if Vertex AI is enabled,
+        otherwise returns the model unchanged.
+    """
+    # Only convert if Vertex AI is enabled
+    if os.getenv("CLAUDE_CODE_USE_VERTEX") != "1":
+        return model
+
+    # Pattern: claude-{name}-{version}-{date} -> claude-{name}-{version}@{date}
+    # Example: claude-opus-4-5-20251101 -> claude-opus-4-5@20251101
+    # The date is always 8 digits at the end
+    match = re.match(r'^(claude-.+)-(\d{8})$', model)
+    if match:
+        base_name, date = match.groups()
+        return f"{base_name}@{date}"
+
+    # If already in @ format or doesn't match expected pattern, return as-is
+    return model
 
 
 def get_playwright_headless() -> bool:
@@ -80,32 +109,128 @@ def get_playwright_browser() -> str:
     return value
 
 
-# Feature MCP tools for feature/test management
+def get_extra_read_paths() -> list[Path]:
-FEATURE_MCP_TOOLS = [
+    """
-    # Core feature operations
+    Get extra read-only paths from EXTRA_READ_PATHS environment variable.
+
+    Parses comma-separated absolute paths and validates each one:
+    - Must be an absolute path
+    - Must exist and be a directory
+    - Cannot be or contain sensitive directories (e.g., .ssh, .aws)
+
+    Returns:
+        List of validated, canonicalized Path objects.
+    """
+    raw_value = os.getenv(EXTRA_READ_PATHS_VAR, "").strip()
+    if not raw_value:
+        return []
+
+    validated_paths: list[Path] = []
+    home_dir = Path.home()
+
+    for path_str in raw_value.split(","):
+        path_str = path_str.strip()
+        if not path_str:
+            continue
+
+        # Parse and canonicalize the path
+        try:
+            path = Path(path_str).resolve()
+        except (OSError, ValueError) as e:
+            print(f"   - Warning: Invalid EXTRA_READ_PATHS path '{path_str}': {e}")
+            continue
+
+        # Must be absolute (resolve() makes it absolute, but check original input)
+        if not Path(path_str).is_absolute():
+            print(f"   - Warning: EXTRA_READ_PATHS requires absolute paths, skipping: {path_str}")
+            continue
+
+        # Must exist
+        if not path.exists():
+            print(f"   - Warning: EXTRA_READ_PATHS path does not exist, skipping: {path_str}")
+            continue
+
+        # Must be a directory
+        if not path.is_dir():
+            print(f"   - Warning: EXTRA_READ_PATHS path is not a directory, skipping: {path_str}")
+            continue
+
+        # Check against sensitive directory blocklist
+        is_blocked = False
+        for sensitive in EXTRA_READ_PATHS_BLOCKLIST:
+            sensitive_path = (home_dir / sensitive).resolve()
+            try:
+                # Block if path IS the sensitive dir or is INSIDE it
+                if path == sensitive_path or path.is_relative_to(sensitive_path):
+                    print(f"   - Warning: EXTRA_READ_PATHS blocked sensitive path: {path_str}")
+                    is_blocked = True
+                    break
+                # Also block if sensitive dir is INSIDE the requested path
+                if sensitive_path.is_relative_to(path):
+                    print(f"   - Warning: EXTRA_READ_PATHS path contains sensitive directory ({sensitive}): {path_str}")
+                    is_blocked = True
+                    break
+            except (OSError, ValueError):
+                # is_relative_to can raise on some edge cases
+                continue
+
+        if is_blocked:
+            continue
+
+        validated_paths.append(path)
+
+    return validated_paths
+
+
+# Per-agent-type MCP tool lists.
+# Only expose the tools each agent type actually needs, reducing tool schema
+# overhead and preventing agents from calling tools meant for other roles.
+#
+# Tools intentionally omitted from ALL agent lists (UI/orchestrator only):
+#   feature_get_ready, feature_get_blocked, feature_get_graph,
+#   feature_remove_dependency
+#
+# The ghost tool "feature_release_testing" was removed entirely -- it was
+# listed here but never implemented in mcp_server/feature_mcp.py.
+
+CODING_AGENT_TOOLS = [
     "mcp__features__feature_get_stats",
-    "mcp__features__feature_get_by_id",  # Get assigned feature details
+    "mcp__features__feature_get_by_id",
-    "mcp__features__feature_get_summary",  # Lightweight: id, name, status, deps only
+    "mcp__features__feature_get_summary",
+    "mcp__features__feature_claim_and_get",
     "mcp__features__feature_mark_in_progress",
-    "mcp__features__feature_claim_and_get",  # Atomic claim + get details
     "mcp__features__feature_mark_passing",
-    "mcp__features__feature_mark_failing",  # Mark regression detected
+    "mcp__features__feature_mark_failing",
     "mcp__features__feature_skip",
-    "mcp__features__feature_create_bulk",
-    "mcp__features__feature_create",
     "mcp__features__feature_clear_in_progress",
-    "mcp__features__feature_release_testing",  # Release testing claim
-    # Dependency management
-    "mcp__features__feature_add_dependency",
-    "mcp__features__feature_remove_dependency",
-    "mcp__features__feature_set_dependencies",
-    # Query tools
-    "mcp__features__feature_get_ready",
-    "mcp__features__feature_get_blocked",
-    "mcp__features__feature_get_graph",
 ]
 
-# Playwright MCP tools for browser automation
+TESTING_AGENT_TOOLS = [
+    "mcp__features__feature_get_stats",
+    "mcp__features__feature_get_by_id",
+    "mcp__features__feature_get_summary",
+    "mcp__features__feature_mark_passing",
+    "mcp__features__feature_mark_failing",
+]
+
+INITIALIZER_AGENT_TOOLS = [
+    "mcp__features__feature_get_stats",
+    "mcp__features__feature_create_bulk",
+    "mcp__features__feature_create",
+    "mcp__features__feature_add_dependency",
+    "mcp__features__feature_set_dependencies",
+]
+
+# Union of all agent tool lists -- used for permissions (all tools remain
+# *permitted* so the MCP server can respond, but only the agent-type-specific
+# list is included in allowed_tools, which controls what the LLM sees).
+ALL_FEATURE_MCP_TOOLS = sorted(
+    set(CODING_AGENT_TOOLS) | set(TESTING_AGENT_TOOLS) | set(INITIALIZER_AGENT_TOOLS)
+)
+
+# Playwright MCP tools for browser automation.
+# Full set of tools for comprehensive UI testing including drag-and-drop,
+# hover menus, file uploads, tab management, etc.
 PLAYWRIGHT_TOOLS = [
     # Core navigation & screenshots
     "mcp__playwright__browser_navigate",
@@ -118,9 +243,10 @@ PLAYWRIGHT_TOOLS = [
     "mcp__playwright__browser_type",
     "mcp__playwright__browser_fill_form",
     "mcp__playwright__browser_select_option",
-    "mcp__playwright__browser_hover",
-    "mcp__playwright__browser_drag",
     "mcp__playwright__browser_press_key",
+    "mcp__playwright__browser_drag",
+    "mcp__playwright__browser_hover",
+    "mcp__playwright__browser_file_upload",
 
     # JavaScript & debugging
     "mcp__playwright__browser_evaluate",
@@ -129,16 +255,17 @@ PLAYWRIGHT_TOOLS = [
     "mcp__playwright__browser_network_requests",
 
     # Browser management
-    "mcp__playwright__browser_close",
     "mcp__playwright__browser_resize",
-    "mcp__playwright__browser_tabs",
     "mcp__playwright__browser_wait_for",
     "mcp__playwright__browser_handle_dialog",
-    "mcp__playwright__browser_file_upload",
     "mcp__playwright__browser_install",
+    "mcp__playwright__browser_close",
+    "mcp__playwright__browser_tabs",
 ]
 
-# Built-in tools
+# Built-in tools available to agents.
+# WebFetch and WebSearch are included so coding agents can look up current
+# documentation for frameworks and libraries they are implementing.
 BUILTIN_TOOLS = [
     "Read",
     "Write",
@@ -156,6 +283,7 @@ def create_client(
     model: str,
     yolo_mode: bool = False,
     agent_id: str | None = None,
+    agent_type: str = "coding",
 ):
     """
     Create a Claude Agent SDK client with multi-layered security.
@@ -166,6 +294,8 @@ def create_client(
         yolo_mode: If True, skip Playwright MCP server for rapid prototyping
         agent_id: Optional unique identifier for browser isolation in parallel mode.
                   When provided, each agent gets its own browser profile.
+        agent_type: One of "coding", "testing", or "initializer". Controls which
+                    MCP tools are exposed and the max_turns limit.
 
     Returns:
         Configured ClaudeSDKClient (from claude_agent_sdk)
@@ -179,13 +309,34 @@ def create_client(
     Note: Authentication is handled by start.bat/start.sh before this runs.
     The Claude SDK auto-detects credentials from the Claude CLI configuration
     """
-    # Build allowed tools list based on mode
+    # Select the feature MCP tools appropriate for this agent type
-    # In YOLO mode, exclude Playwright tools for faster prototyping
+    feature_tools_map = {
-    allowed_tools = [*BUILTIN_TOOLS, *FEATURE_MCP_TOOLS]
+        "coding": CODING_AGENT_TOOLS,
+        "testing": TESTING_AGENT_TOOLS,
+        "initializer": INITIALIZER_AGENT_TOOLS,
+    }
+    feature_tools = feature_tools_map.get(agent_type, CODING_AGENT_TOOLS)
+
+    # Select max_turns based on agent type:
+    #   - coding/initializer: 300 turns (complex multi-step implementation)
+    #   - testing: 100 turns (focused verification of a single feature)
+    max_turns_map = {
+        "coding": 300,
+        "testing": 100,
+        "initializer": 300,
+    }
+    max_turns = max_turns_map.get(agent_type, 300)
+
+    # Build allowed tools list based on mode and agent type.
+    # In YOLO mode, exclude Playwright tools for faster prototyping.
+    allowed_tools = [*BUILTIN_TOOLS, *feature_tools]
     if not yolo_mode:
         allowed_tools.extend(PLAYWRIGHT_TOOLS)
 
-    # Build permissions list
+    # Build permissions list.
+    # We permit ALL feature MCP tools at the security layer (so the MCP server
+    # can respond if called), but the LLM only *sees* the agent-type-specific
+    # subset via allowed_tools above.
     permissions_list = [
         # Allow all file operations within the project directory
         "Read(./**)",
@@ -196,12 +347,22 @@ def create_client(
         # Bash permission granted here, but actual commands are validated
         # by the bash_security_hook (see security.py for allowed commands)
         "Bash(*)",
-        # Allow web tools for documentation lookup
+        # Allow web tools for looking up framework/library documentation
-        "WebFetch",
+        "WebFetch(*)",
-        "WebSearch",
+        "WebSearch(*)",
         # Allow Feature MCP tools for feature management
-        *FEATURE_MCP_TOOLS,
+        *ALL_FEATURE_MCP_TOOLS,
     ]
+
+    # Add extra read paths from environment variable (read-only access)
+    # Paths are validated, canonicalized, and checked against sensitive blocklist
+    extra_read_paths = get_extra_read_paths()
+    for path in extra_read_paths:
+        # Add read-only permissions for each validated path
+        permissions_list.append(f"Read({path}/**)")
+        permissions_list.append(f"Glob({path}/**)")
+        permissions_list.append(f"Grep({path}/**)")
+
     if not yolo_mode:
         # Allow Playwright MCP tools for browser automation (standard mode only)
         permissions_list.extend(PLAYWRIGHT_TOOLS)
@@ -221,13 +382,17 @@ def create_client(
     project_dir.mkdir(parents=True, exist_ok=True)
 
     # Write settings to a file in the project directory
-    settings_file = project_dir / ".claude_settings.json"
+    from autocoder_paths import get_claude_settings_path
+    settings_file = get_claude_settings_path(project_dir)
+    settings_file.parent.mkdir(parents=True, exist_ok=True)
     with open(settings_file, "w") as f:
         json.dump(security_settings, f, indent=2)
 
     print(f"Created security settings at {settings_file}")
     print("   - Sandbox enabled (OS-level bash isolation)")
     print(f"   - Filesystem restricted to: {project_dir.resolve()}")
+    if extra_read_paths:
+        print(f"   - Extra read paths (validated): {', '.join(str(p) for p in extra_read_paths)}")
     print("   - Bash commands restricted to allowlist (see security.py)")
     if yolo_mode:
         print("   - MCP servers: features (database) - YOLO MODE (no Playwright)")
@@ -293,14 +458,19 @@ def create_client(
         if value:
             sdk_env[var] = value
 
-    # Detect alternative API mode (Ollama or GLM)
+    # Detect alternative API mode (Ollama, GLM, or Vertex AI)
     base_url = sdk_env.get("ANTHROPIC_BASE_URL", "")
-    is_alternative_api = bool(base_url)
+    is_vertex = sdk_env.get("CLAUDE_CODE_USE_VERTEX") == "1"
+    is_alternative_api = bool(base_url) or is_vertex
     is_ollama = "localhost:11434" in base_url or "127.0.0.1:11434" in base_url
-
+    model = convert_model_for_vertex(model)
     if sdk_env:
         print(f"   - API overrides: {', '.join(sdk_env.keys())}")
-        if is_ollama:
+        if is_vertex:
+            project_id = sdk_env.get("ANTHROPIC_VERTEX_PROJECT_ID", "unknown")
+            region = sdk_env.get("CLOUD_ML_REGION", "unknown")
+            print(f"   - Vertex AI Mode: Using GCP project '{project_id}' with model '{model}' in region '{region}'")
+        elif is_ollama:
             print("   - Ollama Mode: Using local models")
         elif "ANTHROPIC_BASE_URL" in sdk_env:
             print(f"   - GLM Mode: Using {sdk_env['ANTHROPIC_BASE_URL']}")
@@ -313,9 +483,10 @@ def create_client(
         context["project_dir"] = str(project_dir.resolve())
         return await bash_security_hook(input_data, tool_use_id, context)
 
-    # PreCompact hook for logging and customizing context compaction
+    # PreCompact hook for logging and customizing context compaction.
     # Compaction is handled automatically by Claude Code CLI when context approaches limits.
-    # This hook allows us to log when compaction occurs and optionally provide custom instructions.
+    # This hook provides custom instructions that guide the summarizer to preserve
+    # critical workflow state while discarding verbose/redundant content.
     async def pre_compact_hook(
         input_data: HookInput,
         tool_use_id: str | None,
@@ -328,8 +499,9 @@ def create_client(
         - "auto": Automatic compaction when context approaches token limits
         - "manual": User-initiated compaction via /compact command
 
-        The hook can customize compaction via hookSpecificOutput:
+        Returns custom instructions that guide the compaction summarizer to:
-        - customInstructions: String with focus areas for summarization
+        1. Preserve critical workflow state (feature ID, modified files, test results)
+        2. Discard verbose content (screenshots, long grep outputs, repeated reads)
         """
         trigger = input_data.get("trigger", "auto")
         custom_instructions = input_data.get("custom_instructions")
@@ -340,18 +512,53 @@ def create_client(
             print("[Context] Manual compaction requested")
 
         if custom_instructions:
-            print(f"[Context] Custom instructions: {custom_instructions}")
+            print(f"[Context] Custom instructions provided: {custom_instructions}")
 
-        # Return empty dict to allow compaction to proceed with default behavior
+        # Build compaction instructions that preserve workflow-critical context
-        # To customize, return:
+        # while discarding verbose content that inflates token usage.
-        # {
+        #
-        #     "hookSpecificOutput": {
+        # The summarizer receives these instructions and uses them to decide
-        #         "hookEventName": "PreCompact",
+        # what to keep vs. discard during context compaction.
-        #         "customInstructions": "Focus on preserving file paths and test results"
+        compaction_guidance = "\n".join([
-        #     }
+            "## PRESERVE (critical workflow state)",
-        # }
+            "- Current feature ID, feature name, and feature status (pending/in_progress/passing/failing)",
-        return SyncHookJSONOutput()
+            "- List of all files created or modified during this session, with their paths",
+            "- Last test/lint/type-check results: command run, pass/fail status, and key error messages",
+            "- Current step in the workflow (e.g., implementing, testing, fixing lint errors)",
+            "- Any dependency information (which features block this one)",
+            "- Git operations performed (commits, branches created)",
+            "- MCP tool call results (feature_claim_and_get, feature_mark_passing, etc.)",
+            "- Key architectural decisions made during this session",
+            "",
+            "## DISCARD (verbose content safe to drop)",
+            "- Full screenshot base64 data (just note that a screenshot was taken and what it showed)",
+            "- Long grep/find/glob output listings (summarize to: searched for X, found Y relevant files)",
+            "- Repeated file reads of the same file (keep only the latest read or a summary of changes)",
+            "- Full file contents from Read tool (summarize to: read file X, key sections were Y)",
+            "- Verbose npm/pip install output (just note: dependencies installed successfully/failed)",
+            "- Full lint/type-check output when passing (just note: lint passed with no errors)",
+            "- Browser console message dumps (summarize to: N errors found, key error was X)",
+            "- Redundant tool result confirmations ([Done] markers)",
+        ])
 
+        print("[Context] Applying custom compaction instructions (preserve workflow state, discard verbose content)")
+
+        # The SDK's HookSpecificOutput union type does not yet include a
+        # PreCompactHookSpecificOutput variant, but the CLI protocol accepts
+        # {"hookEventName": "PreCompact", "customInstructions": "..."}.
+        # The dict is serialized to JSON and sent to the CLI process directly,
+        # so the runtime behavior is correct despite the type mismatch.
+        return SyncHookJSONOutput(
+            hookSpecificOutput={  # type: ignore[typeddict-item]
+                "hookEventName": "PreCompact",
+                "customInstructions": compaction_guidance,
+            }
+        )
+
+    # PROMPT CACHING: The Claude Code CLI applies cache_control breakpoints internally.
+    # Our system_prompt benefits from automatic caching without explicit configuration.
+    # If explicit cache_control is needed, the SDK would need to accept content blocks
+    # with cache_control fields (not currently supported in v0.1.x).
     return ClaudeSDKClient(
         options=ClaudeAgentOptions(
             model=model,
@@ -360,7 +567,7 @@ def create_client(
             setting_sources=["project"],  # Enable skills, commands, and CLAUDE.md from project dir
             max_buffer_size=10 * 1024 * 1024,  # 10MB for large Playwright screenshots
             allowed_tools=allowed_tools,
-            mcp_servers=mcp_servers,
+            mcp_servers=mcp_servers,  # type: ignore[arg-type]  # SDK accepts dict config at runtime
             hooks={
                 "PreToolUse": [
                     HookMatcher(matcher="Bash", hooks=[bash_hook_with_context]),
@@ -372,14 +579,14 @@ def create_client(
                     HookMatcher(hooks=[pre_compact_hook]),
                 ],
             },
-            max_turns=1000,
+            max_turns=max_turns,
             cwd=str(project_dir.resolve()),
             settings=str(settings_file.resolve()),  # Use absolute path
             env=sdk_env,  # Pass API configuration overrides to CLI subprocess
             # Enable extended context beta for better handling of long sessions.
             # This provides up to 1M tokens of context with automatic compaction.
             # See: https://docs.anthropic.com/en/api/beta-headers
-            # Disabled for alternative APIs (Ollama, GLM) as they don't support Claude-specific betas.
+            # Disabled for alternative APIs (Ollama, GLM, Vertex AI) as they don't support this beta.
             betas=[] if is_alternative_api else ["context-1m-2025-08-07"],
             # Note on context management:
             # The Claude Agent SDK handles context management automatically through the
@@ -390,7 +597,7 @@ def create_client(
             # parameters. Instead, context is managed via:
             # 1. betas=["context-1m-2025-08-07"] - Extended context window
             # 2. PreCompact hook - Intercept and customize compaction behavior
-            # 3. max_turns - Limit conversation turns (set to 1000 for long sessions)
+            # 3. max_turns - Limit conversation turns (per agent type: coding=300, testing=100)
             #
             # Future SDK versions may add explicit compaction controls. When available,
             # consider adding:

env_constants.py

@@ -0,0 +1,27 @@
+"""
+Shared Environment Variable Constants
+======================================
+
+Single source of truth for environment variables forwarded to Claude CLI
+subprocesses.  Imported by both ``client.py`` (agent sessions) and
+``server/services/chat_constants.py`` (chat sessions) to avoid maintaining
+duplicate lists.
+
+These allow autocoder to use alternative API endpoints (Ollama, GLM,
+Vertex AI) without affecting the user's global Claude Code settings.
+"""
+
+API_ENV_VARS: list[str] = [
+    # Core API configuration
+    "ANTHROPIC_BASE_URL",              # Custom API endpoint (e.g., https://api.z.ai/api/anthropic)
+    "ANTHROPIC_AUTH_TOKEN",            # API authentication token
+    "API_TIMEOUT_MS",                  # Request timeout in milliseconds
+    # Model tier overrides
+    "ANTHROPIC_DEFAULT_SONNET_MODEL",  # Model override for Sonnet
+    "ANTHROPIC_DEFAULT_OPUS_MODEL",    # Model override for Opus
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL",   # Model override for Haiku
+    # Vertex AI configuration
+    "CLAUDE_CODE_USE_VERTEX",          # Enable Vertex AI mode (set to "1")
+    "CLOUD_ML_REGION",                 # GCP region (e.g., us-east5)
+    "ANTHROPIC_VERTEX_PROJECT_ID",     # GCP project ID
+]

mcp_server/feature_mcp.py

@@ -30,18 +30,18 @@ orchestrator, not by agents. Agents receive pre-assigned feature IDs.
 import json
 import os
 import sys
-import threading
 from contextlib import asynccontextmanager
 from pathlib import Path
 from typing import Annotated
 
 from mcp.server.fastmcp import FastMCP
 from pydantic import BaseModel, Field
+from sqlalchemy import text
 
 # Add parent directory to path so we can import from api module
 sys.path.insert(0, str(Path(__file__).parent.parent))
 
-from api.database import Feature, create_database
+from api.database import Feature, atomic_transaction, create_database
 from api.dependency_resolver import (
     MAX_DEPENDENCIES_PER_FEATURE,
     compute_scheduling_scores,
@@ -96,8 +96,9 @@ class BulkCreateInput(BaseModel):
 _session_maker = None
 _engine = None
 
-# Lock for priority assignment to prevent race conditions
+# NOTE: The old threading.Lock() was removed because it only worked per-process,
-_priority_lock = threading.Lock()
+# not cross-process. In parallel mode, multiple MCP servers run in separate
+# processes, so the lock was useless. We now use atomic SQL operations instead.
 
 
 @asynccontextmanager
@@ -243,15 +244,25 @@ def feature_mark_passing(
     """
     session = get_session()
     try:
-        feature = session.query(Feature).filter(Feature.id == feature_id).first()
+        # Atomic update with state guard - prevents double-pass in parallel mode
-
+        result = session.execute(text("""
-        if feature is None:
+            UPDATE features
-            return json.dumps({"error": f"Feature with ID {feature_id} not found"})
+            SET passes = 1, in_progress = 0
-
+            WHERE id = :id AND passes = 0
-        feature.passes = True
+        """), {"id": feature_id})
-        feature.in_progress = False
         session.commit()
 
+        if result.rowcount == 0:
+            # Check why the update didn't match
+            feature = session.query(Feature).filter(Feature.id == feature_id).first()
+            if feature is None:
+                return json.dumps({"error": f"Feature with ID {feature_id} not found"})
+            if feature.passes:
+                return json.dumps({"error": f"Feature with ID {feature_id} is already passing"})
+            return json.dumps({"error": "Failed to mark feature passing for unknown reason"})
+
+        # Get the feature name for the response
+        feature = session.query(Feature).filter(Feature.id == feature_id).first()
         return json.dumps({"success": True, "feature_id": feature_id, "name": feature.name})
     except Exception as e:
         session.rollback()
@@ -284,14 +295,20 @@ def feature_mark_failing(
     """
     session = get_session()
     try:
+        # Check if feature exists first
         feature = session.query(Feature).filter(Feature.id == feature_id).first()
-
         if feature is None:
             return json.dumps({"error": f"Feature with ID {feature_id} not found"})
 
-        feature.passes = False
+        # Atomic update for parallel safety
-        feature.in_progress = False
+        session.execute(text("""
+            UPDATE features
+            SET passes = 0, in_progress = 0
+            WHERE id = :id
+        """), {"id": feature_id})
         session.commit()
+
+        # Refresh to get updated state
         session.refresh(feature)
 
         return json.dumps({
@@ -337,25 +354,28 @@ def feature_skip(
             return json.dumps({"error": "Cannot skip a feature that is already passing"})
 
         old_priority = feature.priority
+        name = feature.name
 
-        # Use lock to prevent race condition in priority assignment
+        # Atomic update: set priority to max+1 in a single statement
-        with _priority_lock:
+        # This prevents race conditions where two features get the same priority
-            # Get max priority and set this feature to max + 1
+        session.execute(text("""
-            max_priority_result = session.query(Feature.priority).order_by(Feature.priority.desc()).first()
+            UPDATE features
-            new_priority = (max_priority_result[0] + 1) if max_priority_result else 1
+            SET priority = (SELECT COALESCE(MAX(priority), 0) + 1 FROM features),
-
+                in_progress = 0
-            feature.priority = new_priority
+            WHERE id = :id
-            feature.in_progress = False
+        """), {"id": feature_id})
-            session.commit()
+        session.commit()
 
+        # Refresh to get new priority
         session.refresh(feature)
+        new_priority = feature.priority
 
         return json.dumps({
-            "id": feature.id,
+            "id": feature_id,
-            "name": feature.name,
+            "name": name,
             "old_priority": old_priority,
             "new_priority": new_priority,
-            "message": f"Feature '{feature.name}' moved to end of queue"
+            "message": f"Feature '{name}' moved to end of queue"
         })
     except Exception as e:
         session.rollback()
@@ -381,21 +401,27 @@ def feature_mark_in_progress(
     """
     session = get_session()
     try:
-        feature = session.query(Feature).filter(Feature.id == feature_id).first()
+        # Atomic claim: only succeeds if feature is not already claimed or passing
-
+        result = session.execute(text("""
-        if feature is None:
+            UPDATE features
-            return json.dumps({"error": f"Feature with ID {feature_id} not found"})
+            SET in_progress = 1
-
+            WHERE id = :id AND passes = 0 AND in_progress = 0
-        if feature.passes:
+        """), {"id": feature_id})
-            return json.dumps({"error": f"Feature with ID {feature_id} is already passing"})
-
-        if feature.in_progress:
-            return json.dumps({"error": f"Feature with ID {feature_id} is already in-progress"})
-
-        feature.in_progress = True
         session.commit()
-        session.refresh(feature)
 
+        if result.rowcount == 0:
+            # Check why the claim failed
+            feature = session.query(Feature).filter(Feature.id == feature_id).first()
+            if feature is None:
+                return json.dumps({"error": f"Feature with ID {feature_id} not found"})
+            if feature.passes:
+                return json.dumps({"error": f"Feature with ID {feature_id} is already passing"})
+            if feature.in_progress:
+                return json.dumps({"error": f"Feature with ID {feature_id} is already in-progress"})
+            return json.dumps({"error": "Failed to mark feature in-progress for unknown reason"})
+
+        # Fetch the claimed feature
+        feature = session.query(Feature).filter(Feature.id == feature_id).first()
         return json.dumps(feature.to_dict())
     except Exception as e:
         session.rollback()
@@ -421,24 +447,35 @@ def feature_claim_and_get(
     """
     session = get_session()
     try:
+        # First check if feature exists
         feature = session.query(Feature).filter(Feature.id == feature_id).first()
-
         if feature is None:
             return json.dumps({"error": f"Feature with ID {feature_id} not found"})
 
         if feature.passes:
             return json.dumps({"error": f"Feature with ID {feature_id} is already passing"})
 
-        # Idempotent: if already in-progress, just return details
+        # Try atomic claim: only succeeds if not already claimed
-        already_claimed = feature.in_progress
+        result = session.execute(text("""
-        if not already_claimed:
+            UPDATE features
-            feature.in_progress = True
+            SET in_progress = 1
-            session.commit()
+            WHERE id = :id AND passes = 0 AND in_progress = 0
-            session.refresh(feature)
+        """), {"id": feature_id})
+        session.commit()
 
-        result = feature.to_dict()
+        # Determine if we claimed it or it was already claimed
-        result["already_claimed"] = already_claimed
+        already_claimed = result.rowcount == 0
-        return json.dumps(result)
+        if already_claimed:
+            # Verify it's in_progress (not some other failure condition)
+            session.refresh(feature)
+            if not feature.in_progress:
+                return json.dumps({"error": f"Failed to claim feature {feature_id} for unknown reason"})
+
+        # Refresh to get current state
+        session.refresh(feature)
+        result_dict = feature.to_dict()
+        result_dict["already_claimed"] = already_claimed
+        return json.dumps(result_dict)
     except Exception as e:
         session.rollback()
         return json.dumps({"error": f"Failed to claim feature: {str(e)}"})
@@ -463,15 +500,20 @@ def feature_clear_in_progress(
     """
     session = get_session()
     try:
+        # Check if feature exists
         feature = session.query(Feature).filter(Feature.id == feature_id).first()
-
         if feature is None:
             return json.dumps({"error": f"Feature with ID {feature_id} not found"})
 
-        feature.in_progress = False
+        # Atomic update - idempotent, safe in parallel mode
+        session.execute(text("""
+            UPDATE features
+            SET in_progress = 0
+            WHERE id = :id
+        """), {"id": feature_id})
         session.commit()
-        session.refresh(feature)
 
+        session.refresh(feature)
         return json.dumps(feature.to_dict())
     except Exception as e:
         session.rollback()
@@ -506,13 +548,14 @@ def feature_create_bulk(
     Returns:
         JSON with: created (int) - number of features created, with_dependencies (int)
     """
-    session = get_session()
     try:
-        # Use lock to prevent race condition in priority assignment
+        # Use atomic transaction for bulk inserts to prevent priority conflicts
-        with _priority_lock:
+        with atomic_transaction(_session_maker) as session:
-            # Get the starting priority
+            # Get the starting priority atomically within the transaction
-            max_priority_result = session.query(Feature.priority).order_by(Feature.priority.desc()).first()
+            result = session.execute(text("""
-            start_priority = (max_priority_result[0] + 1) if max_priority_result else 1
+                SELECT COALESCE(MAX(priority), 0) FROM features
+            """)).fetchone()
+            start_priority = (result[0] or 0) + 1
 
             # First pass: validate all features and their index-based dependencies
             for i, feature_data in enumerate(features):
@@ -546,7 +589,7 @@ def feature_create_bulk(
                                 "error": f"Feature at index {i} cannot depend on feature at index {idx} (forward reference not allowed)"
                             })
 
-            # Second pass: create all features
+            # Second pass: create all features with reserved priorities
             created_features: list[Feature] = []
             for i, feature_data in enumerate(features):
                 db_feature = Feature(
@@ -571,20 +614,16 @@ def feature_create_bulk(
                 if indices:
                     # Convert indices to actual feature IDs
                     dep_ids = [created_features[idx].id for idx in indices]
-                    created_features[i].dependencies = sorted(dep_ids)
+                    created_features[i].dependencies = sorted(dep_ids)  # type: ignore[assignment]  # SQLAlchemy JSON Column accepts list at runtime
                     deps_count += 1
 
-            session.commit()
+            # Commit happens automatically on context manager exit
-
+            return json.dumps({
-        return json.dumps({
+                "created": len(created_features),
-            "created": len(created_features),
+                "with_dependencies": deps_count
-            "with_dependencies": deps_count
+            })
-        })
     except Exception as e:
-        session.rollback()
         return json.dumps({"error": str(e)})
-    finally:
-        session.close()
 
 
 @mcp.tool()
@@ -608,13 +647,14 @@ def feature_create(
     Returns:
         JSON with the created feature details including its ID
     """
-    session = get_session()
     try:
-        # Use lock to prevent race condition in priority assignment
+        # Use atomic transaction to prevent priority collisions
-        with _priority_lock:
+        with atomic_transaction(_session_maker) as session:
-            # Get the next priority
+            # Get the next priority atomically within the transaction
-            max_priority_result = session.query(Feature.priority).order_by(Feature.priority.desc()).first()
+            result = session.execute(text("""
-            next_priority = (max_priority_result[0] + 1) if max_priority_result else 1
+                SELECT COALESCE(MAX(priority), 0) + 1 FROM features
+            """)).fetchone()
+            next_priority = result[0]
 
             db_feature = Feature(
                 priority=next_priority,
@@ -626,20 +666,18 @@ def feature_create(
                 in_progress=False,
             )
             session.add(db_feature)
-            session.commit()
+            session.flush()  # Get the ID
 
-        session.refresh(db_feature)
+            feature_dict = db_feature.to_dict()
+            # Commit happens automatically on context manager exit
 
         return json.dumps({
             "success": True,
             "message": f"Created feature: {name}",
-            "feature": db_feature.to_dict()
+            "feature": feature_dict
         })
     except Exception as e:
-        session.rollback()
         return json.dumps({"error": str(e)})
-    finally:
-        session.close()
 
 
 @mcp.tool()
@@ -659,52 +697,49 @@ def feature_add_dependency(
     Returns:
         JSON with success status and updated dependencies list, or error message
     """
-    session = get_session()
     try:
-        # Security: Self-reference check
+        # Security: Self-reference check (can do before transaction)
         if feature_id == dependency_id:
             return json.dumps({"error": "A feature cannot depend on itself"})
 
-        feature = session.query(Feature).filter(Feature.id == feature_id).first()
+        # Use atomic transaction for consistent cycle detection
-        dependency = session.query(Feature).filter(Feature.id == dependency_id).first()
+        with atomic_transaction(_session_maker) as session:
+            feature = session.query(Feature).filter(Feature.id == feature_id).first()
+            dependency = session.query(Feature).filter(Feature.id == dependency_id).first()
 
-        if not feature:
+            if not feature:
-            return json.dumps({"error": f"Feature {feature_id} not found"})
+                return json.dumps({"error": f"Feature {feature_id} not found"})
-        if not dependency:
+            if not dependency:
-            return json.dumps({"error": f"Dependency feature {dependency_id} not found"})
+                return json.dumps({"error": f"Dependency feature {dependency_id} not found"})
 
-        current_deps = feature.dependencies or []
+            current_deps = feature.dependencies or []
 
-        # Security: Max dependencies limit
+            # Security: Max dependencies limit
-        if len(current_deps) >= MAX_DEPENDENCIES_PER_FEATURE:
+            if len(current_deps) >= MAX_DEPENDENCIES_PER_FEATURE:
-            return json.dumps({"error": f"Maximum {MAX_DEPENDENCIES_PER_FEATURE} dependencies allowed per feature"})
+                return json.dumps({"error": f"Maximum {MAX_DEPENDENCIES_PER_FEATURE} dependencies allowed per feature"})
 
-        # Check if already exists
+            # Check if already exists
-        if dependency_id in current_deps:
+            if dependency_id in current_deps:
-            return json.dumps({"error": "Dependency already exists"})
+                return json.dumps({"error": "Dependency already exists"})
 
-        # Security: Circular dependency check
+            # Security: Circular dependency check
-        # would_create_circular_dependency(features, source_id, target_id)
+            # Within IMMEDIATE transaction, snapshot is protected by write lock
-        # source_id = feature gaining the dependency, target_id = feature being depended upon
+            all_features = [f.to_dict() for f in session.query(Feature).all()]
-        all_features = [f.to_dict() for f in session.query(Feature).all()]
+            if would_create_circular_dependency(all_features, feature_id, dependency_id):
-        if would_create_circular_dependency(all_features, feature_id, dependency_id):
+                return json.dumps({"error": "Cannot add: would create circular dependency"})
-            return json.dumps({"error": "Cannot add: would create circular dependency"})
 
-        # Add dependency
+            # Add dependency atomically
-        current_deps.append(dependency_id)
+            new_deps = sorted(current_deps + [dependency_id])
-        feature.dependencies = sorted(current_deps)
+            feature.dependencies = new_deps
-        session.commit()
+            # Commit happens automatically on context manager exit
 
-        return json.dumps({
+            return json.dumps({
-            "success": True,
+                "success": True,
-            "feature_id": feature_id,
+                "feature_id": feature_id,
-            "dependencies": feature.dependencies
+                "dependencies": new_deps
-        })
+            })
     except Exception as e:
-        session.rollback()
         return json.dumps({"error": f"Failed to add dependency: {str(e)}"})
-    finally:
-        session.close()
 
 
 @mcp.tool()
@@ -721,30 +756,29 @@ def feature_remove_dependency(
     Returns:
         JSON with success status and updated dependencies list, or error message
     """
-    session = get_session()
     try:
-        feature = session.query(Feature).filter(Feature.id == feature_id).first()
+        # Use atomic transaction for consistent read-modify-write
-        if not feature:
+        with atomic_transaction(_session_maker) as session:
-            return json.dumps({"error": f"Feature {feature_id} not found"})
+            feature = session.query(Feature).filter(Feature.id == feature_id).first()
+            if not feature:
+                return json.dumps({"error": f"Feature {feature_id} not found"})
 
-        current_deps = feature.dependencies or []
+            current_deps = feature.dependencies or []
-        if dependency_id not in current_deps:
+            if dependency_id not in current_deps:
-            return json.dumps({"error": "Dependency does not exist"})
+                return json.dumps({"error": "Dependency does not exist"})
 
-        current_deps.remove(dependency_id)
+            # Remove dependency atomically
-        feature.dependencies = current_deps if current_deps else None
+            new_deps = [d for d in current_deps if d != dependency_id]
-        session.commit()
+            feature.dependencies = new_deps if new_deps else None
+            # Commit happens automatically on context manager exit
 
-        return json.dumps({
+            return json.dumps({
-            "success": True,
+                "success": True,
-            "feature_id": feature_id,
+                "feature_id": feature_id,
-            "dependencies": feature.dependencies or []
+                "dependencies": new_deps
-        })
+            })
     except Exception as e:
-        session.rollback()
         return json.dumps({"error": f"Failed to remove dependency: {str(e)}"})
-    finally:
-        session.close()
 
 
 @mcp.tool()
@@ -897,9 +931,8 @@ def feature_set_dependencies(
     Returns:
         JSON with success status and updated dependencies list, or error message
     """
-    session = get_session()
     try:
-        # Security: Self-reference check
+        # Security: Self-reference check (can do before transaction)
         if feature_id in dependency_ids:
             return json.dumps({"error": "A feature cannot depend on itself"})
 
@@ -911,45 +944,44 @@ def feature_set_dependencies(
         if len(dependency_ids) != len(set(dependency_ids)):
             return json.dumps({"error": "Duplicate dependencies not allowed"})
 
-        feature = session.query(Feature).filter(Feature.id == feature_id).first()
+        # Use atomic transaction for consistent cycle detection
-        if not feature:
+        with atomic_transaction(_session_maker) as session:
-            return json.dumps({"error": f"Feature {feature_id} not found"})
+            feature = session.query(Feature).filter(Feature.id == feature_id).first()
+            if not feature:
+                return json.dumps({"error": f"Feature {feature_id} not found"})
 
-        # Validate all dependencies exist
+            # Validate all dependencies exist
-        all_feature_ids = {f.id for f in session.query(Feature).all()}
+            all_feature_ids = {f.id for f in session.query(Feature).all()}
-        missing = [d for d in dependency_ids if d not in all_feature_ids]
+            missing = [d for d in dependency_ids if d not in all_feature_ids]
-        if missing:
+            if missing:
-            return json.dumps({"error": f"Dependencies not found: {missing}"})
+                return json.dumps({"error": f"Dependencies not found: {missing}"})
 
-        # Check for circular dependencies
+            # Check for circular dependencies
-        all_features = [f.to_dict() for f in session.query(Feature).all()]
+            # Within IMMEDIATE transaction, snapshot is protected by write lock
-        # Temporarily update the feature's dependencies for cycle check
+            all_features = [f.to_dict() for f in session.query(Feature).all()]
-        test_features = []
+            test_features = []
-        for f in all_features:
+            for f in all_features:
-            if f["id"] == feature_id:
+                if f["id"] == feature_id:
-                test_features.append({**f, "dependencies": dependency_ids})
+                    test_features.append({**f, "dependencies": dependency_ids})
-            else:
+                else:
-                test_features.append(f)
+                    test_features.append(f)
 
-        for dep_id in dependency_ids:
+            for dep_id in dependency_ids:
-            # source_id = feature_id (gaining dep), target_id = dep_id (being depended upon)
+                if would_create_circular_dependency(test_features, feature_id, dep_id):
-            if would_create_circular_dependency(test_features, feature_id, dep_id):
+                    return json.dumps({"error": f"Cannot add dependency {dep_id}: would create circular dependency"})
-                return json.dumps({"error": f"Cannot add dependency {dep_id}: would create circular dependency"})
 
-        # Set dependencies
+            # Set dependencies atomically
-        feature.dependencies = sorted(dependency_ids) if dependency_ids else None
+            sorted_deps = sorted(dependency_ids) if dependency_ids else None
-        session.commit()
+            feature.dependencies = sorted_deps
+            # Commit happens automatically on context manager exit
 
-        return json.dumps({
+            return json.dumps({
-            "success": True,
+                "success": True,
-            "feature_id": feature_id,
+                "feature_id": feature_id,
-            "dependencies": feature.dependencies or []
+                "dependencies": sorted_deps or []
-        })
+            })
     except Exception as e:
-        session.rollback()
         return json.dumps({"error": f"Failed to set dependencies: {str(e)}"})
-    finally:
-        session.close()
 
 
 if __name__ == "__main__":

progress.py

@@ -10,12 +10,21 @@ import json
 import os
 import sqlite3
 import urllib.request
+from contextlib import closing
 from datetime import datetime, timezone
 from pathlib import Path
 
 WEBHOOK_URL = os.environ.get("PROGRESS_N8N_WEBHOOK_URL")
 PROGRESS_CACHE_FILE = ".progress_cache"
 
+# SQLite connection settings for parallel mode safety
+SQLITE_TIMEOUT = 30  # seconds to wait for locks
+
+
+def _get_connection(db_file: Path) -> sqlite3.Connection:
+    """Get a SQLite connection with proper timeout settings for parallel mode."""
+    return sqlite3.connect(db_file, timeout=SQLITE_TIMEOUT)
+
 
 def has_features(project_dir: Path) -> bool:
     """
@@ -31,25 +40,23 @@ def has_features(project_dir: Path) -> bool:
 
     Returns False if no features exist (initializer needs to run).
     """
-    import sqlite3
-
     # Check legacy JSON file first
     json_file = project_dir / "feature_list.json"
     if json_file.exists():
         return True
 
     # Check SQLite database
-    db_file = project_dir / "features.db"
+    from autocoder_paths import get_features_db_path
+    db_file = get_features_db_path(project_dir)
     if not db_file.exists():
         return False
 
     try:
-        conn = sqlite3.connect(db_file)
+        with closing(_get_connection(db_file)) as conn:
-        cursor = conn.cursor()
+            cursor = conn.cursor()
-        cursor.execute("SELECT COUNT(*) FROM features")
+            cursor.execute("SELECT COUNT(*) FROM features")
-        count = cursor.fetchone()[0]
+            count: int = cursor.fetchone()[0]
-        conn.close()
+            return bool(count > 0)
-        return count > 0
     except Exception:
         # Database exists but can't be read or has no features table
         return False
@@ -65,41 +72,41 @@ def count_passing_tests(project_dir: Path) -> tuple[int, int, int]:
     Returns:
         (passing_count, in_progress_count, total_count)
     """
-    db_file = project_dir / "features.db"
+    from autocoder_paths import get_features_db_path
+    db_file = get_features_db_path(project_dir)
     if not db_file.exists():
         return 0, 0, 0
 
     try:
-        conn = sqlite3.connect(db_file)
+        with closing(_get_connection(db_file)) as conn:
-        cursor = conn.cursor()
+            cursor = conn.cursor()
-        # Single aggregate query instead of 3 separate COUNT queries
+            # Single aggregate query instead of 3 separate COUNT queries
-        # Handle case where in_progress column doesn't exist yet (legacy DBs)
+            # Handle case where in_progress column doesn't exist yet (legacy DBs)
-        try:
+            try:
-            cursor.execute("""
+                cursor.execute("""
-                SELECT
+                    SELECT
-                    COUNT(*) as total,
+                        COUNT(*) as total,
-                    SUM(CASE WHEN passes = 1 THEN 1 ELSE 0 END) as passing,
+                        SUM(CASE WHEN passes = 1 THEN 1 ELSE 0 END) as passing,
-                    SUM(CASE WHEN in_progress = 1 THEN 1 ELSE 0 END) as in_progress
+                        SUM(CASE WHEN in_progress = 1 THEN 1 ELSE 0 END) as in_progress
-                FROM features
+                    FROM features
-            """)
+                """)
-            row = cursor.fetchone()
+                row = cursor.fetchone()
-            total = row[0] or 0
+                total = row[0] or 0
-            passing = row[1] or 0
+                passing = row[1] or 0
-            in_progress = row[2] or 0
+                in_progress = row[2] or 0
-        except sqlite3.OperationalError:
+            except sqlite3.OperationalError:
-            # Fallback for databases without in_progress column
+                # Fallback for databases without in_progress column
-            cursor.execute("""
+                cursor.execute("""
-                SELECT
+                    SELECT
-                    COUNT(*) as total,
+                        COUNT(*) as total,
-                    SUM(CASE WHEN passes = 1 THEN 1 ELSE 0 END) as passing
+                        SUM(CASE WHEN passes = 1 THEN 1 ELSE 0 END) as passing
-                FROM features
+                    FROM features
-            """)
+                """)
-            row = cursor.fetchone()
+                row = cursor.fetchone()
-            total = row[0] or 0
+                total = row[0] or 0
-            passing = row[1] or 0
+                passing = row[1] or 0
-            in_progress = 0
+                in_progress = 0
-        conn.close()
+            return passing, in_progress, total
-        return passing, in_progress, total
     except Exception as e:
         print(f"[Database error in count_passing_tests: {e}]")
         return 0, 0, 0
@@ -115,22 +122,22 @@ def get_all_passing_features(project_dir: Path) -> list[dict]:
     Returns:
         List of dicts with id, category, name for each passing feature
     """
-    db_file = project_dir / "features.db"
+    from autocoder_paths import get_features_db_path
+    db_file = get_features_db_path(project_dir)
     if not db_file.exists():
         return []
 
     try:
-        conn = sqlite3.connect(db_file)
+        with closing(_get_connection(db_file)) as conn:
-        cursor = conn.cursor()
+            cursor = conn.cursor()
-        cursor.execute(
+            cursor.execute(
-            "SELECT id, category, name FROM features WHERE passes = 1 ORDER BY priority ASC"
+                "SELECT id, category, name FROM features WHERE passes = 1 ORDER BY priority ASC"
-        )
+            )
-        features = [
+            features = [
-            {"id": row[0], "category": row[1], "name": row[2]}
+                {"id": row[0], "category": row[1], "name": row[2]}
-            for row in cursor.fetchall()
+                for row in cursor.fetchall()
-        ]
+            ]
-        conn.close()
+            return features
-        return features
     except Exception:
         return []
 
@@ -140,7 +147,8 @@ def send_progress_webhook(passing: int, total: int, project_dir: Path) -> None:
     if not WEBHOOK_URL:
         return  # Webhook not configured
 
-    cache_file = project_dir / PROGRESS_CACHE_FILE
+    from autocoder_paths import get_progress_cache_path
+    cache_file = get_progress_cache_path(project_dir)
     previous = 0
     previous_passing_ids = set()
 

prompts.py

@@ -9,6 +9,7 @@ Fallback chain:
 2. Base template: .claude/templates/{name}.template.md
 """
 
+import re
 import shutil
 from pathlib import Path
 
@@ -18,7 +19,8 @@ TEMPLATES_DIR = Path(__file__).parent / ".claude" / "templates"
 
 def get_project_prompts_dir(project_dir: Path) -> Path:
     """Get the prompts directory for a specific project."""
-    return project_dir / "prompts"
+    from autocoder_paths import get_prompts_dir
+    return get_prompts_dir(project_dir)
 
 
 def load_prompt(name: str, project_dir: Path | None = None) -> str:
@@ -69,42 +71,119 @@ def get_initializer_prompt(project_dir: Path | None = None) -> str:
     return load_prompt("initializer_prompt", project_dir)
 
 
-def get_coding_prompt(project_dir: Path | None = None) -> str:
+def _strip_browser_testing_sections(prompt: str) -> str:
-    """Load the coding agent prompt (project-specific if available)."""
+    """Strip browser automation and Playwright testing instructions from prompt.
-    return load_prompt("coding_prompt", project_dir)
+
+    Used in YOLO mode where browser testing is skipped entirely. Replaces
+    browser-related sections with a brief YOLO-mode note while preserving
+    all non-testing instructions (implementation, git, progress notes, etc.).
+
+    Args:
+        prompt: The full coding prompt text.
+
+    Returns:
+        The prompt with browser testing sections replaced by YOLO guidance.
+    """
+    original_prompt = prompt
+
+    # Replace STEP 5 (browser automation verification) with YOLO note
+    prompt = re.sub(
+        r"### STEP 5: VERIFY WITH BROWSER AUTOMATION.*?(?=### STEP 5\.5:)",
+        "### STEP 5: VERIFY FEATURE (YOLO MODE)\n\n"
+        "**YOLO mode is active.** Skip browser automation testing. "
+        "Instead, verify your feature works by ensuring:\n"
+        "- Code compiles without errors (lint and type-check pass)\n"
+        "- Server starts without errors after your changes\n"
+        "- No obvious runtime errors in server logs\n\n",
+        prompt,
+        flags=re.DOTALL,
+    )
+
+    # Replace the screenshots-only marking rule with YOLO-appropriate wording
+    prompt = prompt.replace(
+        "**ONLY MARK A FEATURE AS PASSING AFTER VERIFICATION WITH SCREENSHOTS.**",
+        "**YOLO mode: Mark a feature as passing after lint/type-check succeeds and server starts cleanly.**",
+    )
+
+    # Replace the BROWSER AUTOMATION reference section
+    prompt = re.sub(
+        r"## BROWSER AUTOMATION\n\n.*?(?=---)",
+        "## VERIFICATION (YOLO MODE)\n\n"
+        "Browser automation is disabled in YOLO mode. "
+        "Verify features by running lint, type-check, and confirming the dev server starts without errors.\n\n",
+        prompt,
+        flags=re.DOTALL,
+    )
+
+    # In STEP 4, replace browser automation reference with YOLO guidance
+    prompt = prompt.replace(
+        "2. Test manually using browser automation (see Step 5)",
+        "2. Verify code compiles (lint and type-check pass)",
+    )
+
+    if prompt == original_prompt:
+        print("[YOLO] Warning: No browser testing sections found to strip. "
+              "Project-specific prompt may need manual YOLO adaptation.")
+
+    return prompt
 
 
-def get_testing_prompt(project_dir: Path | None = None, testing_feature_id: int | None = None) -> str:
+def get_coding_prompt(project_dir: Path | None = None, yolo_mode: bool = False) -> str:
-    """Load the testing agent prompt (project-specific if available).
+    """Load the coding agent prompt (project-specific if available).
 
     Args:
         project_dir: Optional project directory for project-specific prompts
-        testing_feature_id: If provided, the pre-assigned feature ID to test.
+        yolo_mode: If True, strip browser automation / Playwright testing
-            The orchestrator claims the feature before spawning the agent.
+            instructions and replace with YOLO-mode guidance. This reduces
+            prompt tokens since YOLO mode skips all browser testing anyway.
 
     Returns:
-        The testing prompt, with pre-assigned feature instructions if applicable.
+        The coding prompt, optionally stripped of testing instructions.
+    """
+    prompt = load_prompt("coding_prompt", project_dir)
+
+    if yolo_mode:
+        prompt = _strip_browser_testing_sections(prompt)
+
+    return prompt
+
+
+def get_testing_prompt(
+    project_dir: Path | None = None,
+    testing_feature_id: int | None = None,
+    testing_feature_ids: list[int] | None = None,
+) -> str:
+    """Load the testing agent prompt (project-specific if available).
+
+    Supports both single-feature and multi-feature testing modes. When
+    testing_feature_ids is provided, the template's {{TESTING_FEATURE_IDS}}
+    placeholder is replaced with the comma-separated list. Falls back to
+    the legacy single-feature header when only testing_feature_id is given.
+
+    Args:
+        project_dir: Optional project directory for project-specific prompts
+        testing_feature_id: If provided, the pre-assigned feature ID to test (legacy single mode).
+        testing_feature_ids: If provided, a list of feature IDs to test (batch mode).
+            Takes precedence over testing_feature_id when both are set.
+
+    Returns:
+        The testing prompt, with feature assignment instructions populated.
     """
     base_prompt = load_prompt("testing_prompt", project_dir)
 
+    # Batch mode: replace the {{TESTING_FEATURE_IDS}} placeholder in the template
+    if testing_feature_ids is not None and len(testing_feature_ids) > 0:
+        ids_str = ", ".join(str(fid) for fid in testing_feature_ids)
+        return base_prompt.replace("{{TESTING_FEATURE_IDS}}", ids_str)
+
+    # Legacy single-feature mode: prepend header and replace placeholder
     if testing_feature_id is not None:
-        # Prepend pre-assigned feature instructions
+        # Replace the placeholder with the single ID for template consistency
-        pre_assigned_header = f"""## ASSIGNED FEATURE
+        base_prompt = base_prompt.replace("{{TESTING_FEATURE_IDS}}", str(testing_feature_id))
+        return base_prompt
 
-**You are assigned to regression test Feature #{testing_feature_id}.**
+    # No feature assignment -- return template with placeholder cleared
-
+    return base_prompt.replace("{{TESTING_FEATURE_IDS}}", "(none assigned)")
-### Your workflow:
-1. Call `feature_get_by_id` with ID {testing_feature_id} to get the feature details
-2. Verify the feature through the UI using browser automation
-3. If regression found, call `feature_mark_failing` with feature_id={testing_feature_id}
-4. Exit when done (no cleanup needed)
-
----
-
-"""
-        return pre_assigned_header + base_prompt
-
-    return base_prompt
 
 
 def get_single_feature_prompt(feature_id: int, project_dir: Path | None = None, yolo_mode: bool = False) -> str:
@@ -117,13 +196,13 @@ def get_single_feature_prompt(feature_id: int, project_dir: Path | None = None,
     Args:
         feature_id: The specific feature ID to work on
         project_dir: Optional project directory for project-specific prompts
-        yolo_mode: Ignored (kept for backward compatibility). Testing is now
+        yolo_mode: If True, strip browser testing instructions from the base
-                   handled by separate testing agents, not YOLO prompts.
+            coding prompt for reduced token usage in YOLO mode.
 
     Returns:
         The prompt with single-feature header prepended
     """
-    base_prompt = get_coding_prompt(project_dir)
+    base_prompt = get_coding_prompt(project_dir, yolo_mode=yolo_mode)
 
     # Minimal header - the base prompt already contains the full workflow
     single_feature_header = f"""## ASSIGNED FEATURE: #{feature_id}
@@ -138,6 +217,52 @@ If blocked, use `feature_skip` and document the blocker.
     return single_feature_header + base_prompt
 
 
+def get_batch_feature_prompt(
+    feature_ids: list[int],
+    project_dir: Path | None = None,
+    yolo_mode: bool = False,
+) -> str:
+    """Prepend batch-feature assignment header to base coding prompt.
+
+    Used in parallel mode to assign multiple features to an agent.
+    Features should be implemented sequentially in the given order.
+
+    Args:
+        feature_ids: List of feature IDs to implement in order
+        project_dir: Optional project directory for project-specific prompts
+        yolo_mode: If True, strip browser testing instructions from the base prompt
+
+    Returns:
+        The prompt with batch-feature header prepended
+    """
+    base_prompt = get_coding_prompt(project_dir, yolo_mode=yolo_mode)
+    ids_str = ", ".join(f"#{fid}" for fid in feature_ids)
+
+    batch_header = f"""## ASSIGNED FEATURES (BATCH): {ids_str}
+
+You have been assigned {len(feature_ids)} features to implement sequentially.
+Process them IN ORDER: {ids_str}
+
+### Workflow for each feature:
+1. Call `feature_claim_and_get` with the feature ID to get its details
+2. Implement the feature fully
+3. Verify it works (browser testing if applicable)
+4. Call `feature_mark_passing` to mark it complete
+5. Git commit the changes
+6. Move to the next feature
+
+### Important:
+- Complete each feature fully before starting the next
+- Mark each feature passing individually as you go
+- If blocked on a feature, use `feature_skip` and move to the next one
+- Other agents are handling other features - focus only on yours
+
+---
+
+"""
+    return batch_header + base_prompt
+
+
 def get_app_spec(project_dir: Path) -> str:
     """
     Load the app spec from the project.
@@ -190,9 +315,9 @@ def scaffold_project_prompts(project_dir: Path) -> Path:
     project_prompts = get_project_prompts_dir(project_dir)
     project_prompts.mkdir(parents=True, exist_ok=True)
 
-    # Create .autocoder directory for configuration files
+    # Create .autocoder directory with .gitignore for runtime files
-    autocoder_dir = project_dir / ".autocoder"
+    from autocoder_paths import ensure_autocoder_dir
-    autocoder_dir.mkdir(parents=True, exist_ok=True)
+    autocoder_dir = ensure_autocoder_dir(project_dir)
 
     # Define template mappings: (source_template, destination_name)
     templates = [

rate_limit_utils.py

@@ -0,0 +1,132 @@
+"""
+Rate Limit Utilities
+====================
+
+Shared utilities for detecting and handling API rate limits.
+Used by both agent.py (production) and test_rate_limit_utils.py (tests).
+"""
+
+import random
+import re
+from typing import Optional
+
+# Regex patterns for rate limit detection (used in both exception messages and response text)
+# These patterns use word boundaries to avoid false positives like "PR #429" or "please wait while I..."
+RATE_LIMIT_REGEX_PATTERNS = [
+    r"\brate[_\s]?limit",         # "rate limit", "rate_limit", "ratelimit"
+    r"\btoo\s+many\s+requests",   # "too many requests"
+    r"\bhttp\s*429\b",            # "http 429", "http429"
+    r"\bstatus\s*429\b",          # "status 429", "status429"
+    r"\berror\s*429\b",           # "error 429", "error429"
+    r"\b429\s+too\s+many",        # "429 too many"
+    r"\b(?:server|api|system)\s+(?:is\s+)?overloaded\b",  # "server is overloaded", "api overloaded"
+    r"\bquota\s*exceeded\b",      # "quota exceeded"
+]
+
+# Compiled regex for efficient matching
+_RATE_LIMIT_REGEX = re.compile(
+    "|".join(RATE_LIMIT_REGEX_PATTERNS),
+    re.IGNORECASE
+)
+
+
+def parse_retry_after(error_message: str) -> Optional[int]:
+    """
+    Extract retry-after seconds from various error message formats.
+
+    Handles common formats:
+    - "Retry-After: 60"
+    - "retry after 60 seconds"
+    - "try again in 5 seconds"
+    - "30 seconds remaining"
+
+    Args:
+        error_message: The error message to parse
+
+    Returns:
+        Seconds to wait, or None if not parseable.
+    """
+    # Patterns require explicit "seconds" or "s" unit, OR no unit at all (end of string/sentence)
+    # This prevents matching "30 minutes" or "1 hour" since those have non-seconds units
+    patterns = [
+        r"retry.?after[:\s]+(\d+)\s*(?:seconds?|s\b)",  # Requires seconds unit
+        r"retry.?after[:\s]+(\d+)(?:\s*$|\s*[,.])",     # Or end of string/sentence
+        r"try again in\s+(\d+)\s*(?:seconds?|s\b)",     # Requires seconds unit
+        r"try again in\s+(\d+)(?:\s*$|\s*[,.])",        # Or end of string/sentence
+        r"(\d+)\s*seconds?\s*(?:remaining|left|until)",
+    ]
+
+    for pattern in patterns:
+        match = re.search(pattern, error_message, re.IGNORECASE)
+        if match:
+            return int(match.group(1))
+
+    return None
+
+
+def is_rate_limit_error(error_message: str) -> bool:
+    """
+    Detect if an error message indicates a rate limit.
+
+    Uses regex patterns with word boundaries to avoid false positives
+    like "PR #429", "please wait while I...", or "Node v14.29.0".
+
+    Args:
+        error_message: The error message to check
+
+    Returns:
+        True if the message indicates a rate limit, False otherwise.
+    """
+    return bool(_RATE_LIMIT_REGEX.search(error_message))
+
+
+def calculate_rate_limit_backoff(retries: int) -> int:
+    """
+    Calculate exponential backoff with jitter for rate limits.
+
+    Base formula: min(15 * 2^retries, 3600)
+    Jitter: adds 0-30% random jitter to prevent thundering herd.
+    Base sequence: ~15-20s, ~30-40s, ~60-78s, ~120-156s, ...
+
+    The lower starting delay (15s vs 60s) allows faster recovery from
+    transient rate limits, while jitter prevents synchronized retries
+    when multiple agents hit limits simultaneously.
+
+    Args:
+        retries: Number of consecutive rate limit retries (0-indexed)
+
+    Returns:
+        Delay in seconds (clamped to 1-3600 range, with jitter)
+    """
+    base = int(min(max(15 * (2 ** retries), 1), 3600))
+    jitter = random.uniform(0, base * 0.3)
+    return int(base + jitter)
+
+
+def calculate_error_backoff(retries: int) -> int:
+    """
+    Calculate linear backoff for non-rate-limit errors.
+
+    Formula: min(30 * retries, 300) - caps at 5 minutes
+    Sequence: 30s, 60s, 90s, 120s, ... 300s
+
+    Args:
+        retries: Number of consecutive error retries (1-indexed)
+
+    Returns:
+        Delay in seconds (clamped to 1-300 range)
+    """
+    return min(max(30 * retries, 1), 300)
+
+
+def clamp_retry_delay(delay_seconds: int) -> int:
+    """
+    Clamp a retry delay to a safe range (1-3600 seconds).
+
+    Args:
+        delay_seconds: The raw delay value
+
+    Returns:
+        Delay clamped to 1-3600 seconds
+    """
+    return min(max(delay_seconds, 1), 3600)

registry.py

@@ -16,9 +16,8 @@ from datetime import datetime
 from pathlib import Path
 from typing import Any
 
-from sqlalchemy import Column, DateTime, String, create_engine
+from sqlalchemy import Column, DateTime, Integer, String, create_engine, text
-from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import DeclarativeBase, sessionmaker
-from sqlalchemy.orm import sessionmaker
 
 # Module logger
 logger = logging.getLogger(__name__)
@@ -39,7 +38,17 @@ AVAILABLE_MODELS = [
 VALID_MODELS = [m["id"] for m in AVAILABLE_MODELS]
 
 # Default model and settings
-DEFAULT_MODEL = "claude-opus-4-5-20251101"
+# Respect ANTHROPIC_DEFAULT_OPUS_MODEL env var for Foundry/custom deployments
+# Guard against empty/whitespace values by trimming and falling back when blank
+_env_default_model = os.getenv("ANTHROPIC_DEFAULT_OPUS_MODEL")
+if _env_default_model is not None:
+    _env_default_model = _env_default_model.strip()
+DEFAULT_MODEL = _env_default_model or "claude-opus-4-5-20251101"
+
+# Ensure env-provided DEFAULT_MODEL is in VALID_MODELS for validation consistency
+# (idempotent: only adds if missing, doesn't alter AVAILABLE_MODELS semantics)
+if DEFAULT_MODEL and DEFAULT_MODEL not in VALID_MODELS:
+    VALID_MODELS.append(DEFAULT_MODEL)
 DEFAULT_YOLO_MODE = False
 
 # SQLite connection settings
@@ -75,7 +84,9 @@ class RegistryPermissionDenied(RegistryError):
 # SQLAlchemy Model
 # =============================================================================
 
-Base = declarative_base()
+class Base(DeclarativeBase):
+    """SQLAlchemy 2.0 style declarative base."""
+    pass
 
 
 class Project(Base):
@@ -85,6 +96,7 @@ class Project(Base):
     name = Column(String(50), primary_key=True, index=True)
     path = Column(String, nullable=False)  # POSIX format for cross-platform
     created_at = Column(DateTime, nullable=False)
+    default_concurrency = Column(Integer, nullable=False, default=3)
 
 
 class Settings(Base):
@@ -146,12 +158,26 @@ def _get_engine():
                     }
                 )
                 Base.metadata.create_all(bind=_engine)
+                _migrate_add_default_concurrency(_engine)
                 _SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=_engine)
                 logger.debug("Initialized registry database at: %s", db_path)
 
     return _engine, _SessionLocal
 
 
+def _migrate_add_default_concurrency(engine) -> None:
+    """Add default_concurrency column if missing (for existing databases)."""
+    with engine.connect() as conn:
+        result = conn.execute(text("PRAGMA table_info(projects)"))
+        columns = [row[1] for row in result.fetchall()]
+        if "default_concurrency" not in columns:
+            conn.execute(text(
+                "ALTER TABLE projects ADD COLUMN default_concurrency INTEGER DEFAULT 3"
+            ))
+            conn.commit()
+            logger.info("Migrated projects table: added default_concurrency column")
+
+
 @contextmanager
 def _get_session():
     """
@@ -307,7 +333,8 @@ def list_registered_projects() -> dict[str, dict[str, Any]]:
         return {
             p.name: {
                 "path": p.path,
-                "created_at": p.created_at.isoformat() if p.created_at else None
+                "created_at": p.created_at.isoformat() if p.created_at else None,
+                "default_concurrency": getattr(p, 'default_concurrency', 3) or 3
             }
             for p in projects
         }
@@ -333,7 +360,8 @@ def get_project_info(name: str) -> dict[str, Any] | None:
             return None
         return {
             "path": project.path,
-            "created_at": project.created_at.isoformat() if project.created_at else None
+            "created_at": project.created_at.isoformat() if project.created_at else None,
+            "default_concurrency": getattr(project, 'default_concurrency', 3) or 3
         }
     finally:
         session.close()
@@ -362,6 +390,55 @@ def update_project_path(name: str, new_path: Path) -> bool:
     return True
 
 
+def get_project_concurrency(name: str) -> int:
+    """
+    Get project's default concurrency (1-5).
+
+    Args:
+        name: The project name.
+
+    Returns:
+        The default concurrency value (defaults to 3 if not set or project not found).
+    """
+    _, SessionLocal = _get_engine()
+    session = SessionLocal()
+    try:
+        project = session.query(Project).filter(Project.name == name).first()
+        if project is None:
+            return 3
+        return getattr(project, 'default_concurrency', 3) or 3
+    finally:
+        session.close()
+
+
+def set_project_concurrency(name: str, concurrency: int) -> bool:
+    """
+    Set project's default concurrency (1-5).
+
+    Args:
+        name: The project name.
+        concurrency: The concurrency value (1-5).
+
+    Returns:
+        True if updated, False if project wasn't found.
+
+    Raises:
+        ValueError: If concurrency is not between 1 and 5.
+    """
+    if concurrency < 1 or concurrency > 5:
+        raise ValueError("concurrency must be between 1 and 5")
+
+    with _get_session() as session:
+        project = session.query(Project).filter(Project.name == name).first()
+        if not project:
+            return False
+
+        project.default_concurrency = concurrency
+
+    logger.info("Set project '%s' default_concurrency to %d", name, concurrency)
+    return True
+
+
 # =============================================================================
 # Validation Functions
 # =============================================================================

requirements.txt

@@ -15,3 +15,4 @@ pyyaml>=6.0.0
 ruff>=0.8.0
 mypy>=1.13.0
 pytest>=8.0.0
+types-PyYAML>=6.0.0

security.py

@@ -6,6 +6,7 @@ Pre-tool-use hooks that validate bash commands for security.
 Uses an allowlist approach - only explicitly permitted commands can run.
 """
 
+import logging
 import os
 import re
 import shlex
@@ -14,6 +15,9 @@ from typing import Optional
 
 import yaml
 
+# Logger for security-related events (fallback parsing, validation failures, etc.)
+logger = logging.getLogger(__name__)
+
 # Regex pattern for valid pkill process names (no regex metacharacters allowed)
 # Matches alphanumeric names with dots, underscores, and hyphens
 VALID_PROCESS_NAME_PATTERN = re.compile(r"^[A-Za-z0-9._-]+$")
@@ -93,6 +97,31 @@ BLOCKED_COMMANDS = {
     "ufw",
 }
 
+# Sensitive directories (relative to home) that should never be exposed.
+# Used by both the EXTRA_READ_PATHS validator (client.py) and the filesystem
+# browser API (server/routers/filesystem.py) to block credential/key directories.
+# This is the single source of truth -- import from here in both places.
+#
+# SENSITIVE_DIRECTORIES is the union of the previous filesystem browser blocklist
+# (filesystem.py) and the previous EXTRA_READ_PATHS blocklist (client.py).
+# Some entries are new to each consumer -- this is intentional for defense-in-depth.
+SENSITIVE_DIRECTORIES = {
+    ".ssh",
+    ".aws",
+    ".azure",
+    ".kube",
+    ".gnupg",
+    ".gpg",
+    ".password-store",
+    ".docker",
+    ".config/gcloud",
+    ".config/gh",
+    ".npmrc",
+    ".pypirc",
+    ".netrc",
+    ".terraform",
+}
+
 # Commands that trigger emphatic warnings but CAN be approved (Phase 3)
 # For now, these are blocked like BLOCKED_COMMANDS until Phase 3 implements approval
 DANGEROUS_COMMANDS = {
@@ -140,6 +169,45 @@ def split_command_segments(command_string: str) -> list[str]:
     return result
 
 
+def _extract_primary_command(segment: str) -> str | None:
+    """
+    Fallback command extraction when shlex fails.
+
+    Extracts the first word that looks like a command, handling cases
+    like complex docker exec commands with nested quotes.
+
+    Args:
+        segment: The command segment to parse
+
+    Returns:
+        The primary command name, or None if extraction fails
+    """
+    # Remove leading whitespace
+    segment = segment.lstrip()
+
+    if not segment:
+        return None
+
+    # Skip env var assignments at start (VAR=value cmd)
+    words = segment.split()
+    while words and "=" in words[0] and not words[0].startswith("="):
+        words = words[1:]
+
+    if not words:
+        return None
+
+    # Extract first token (the command)
+    first_word = words[0]
+
+    # Match valid command characters (alphanumeric, dots, underscores, hyphens, slashes)
+    match = re.match(r"^([a-zA-Z0-9_./-]+)", first_word)
+    if match:
+        cmd = match.group(1)
+        return os.path.basename(cmd)
+
+    return None
+
+
 def extract_commands(command_string: str) -> list[str]:
     """
     Extract command names from a shell command string.
@@ -156,7 +224,6 @@ def extract_commands(command_string: str) -> list[str]:
     commands = []
 
     # shlex doesn't treat ; as a separator, so we need to pre-process
-    import re
 
     # Split on semicolons that aren't inside quotes (simple heuristic)
     # This handles common cases like "echo hello; ls"
@@ -171,8 +238,21 @@ def extract_commands(command_string: str) -> list[str]:
             tokens = shlex.split(segment)
         except ValueError:
             # Malformed command (unclosed quotes, etc.)
-            # Return empty to trigger block (fail-safe)
+            # Try fallback extraction instead of blocking entirely
-            return []
+            fallback_cmd = _extract_primary_command(segment)
+            if fallback_cmd:
+                logger.debug(
+                    "shlex fallback used: segment=%r -> command=%r",
+                    segment,
+                    fallback_cmd,
+                )
+                commands.append(fallback_cmd)
+            else:
+                logger.debug(
+                    "shlex fallback failed: segment=%r (no command extracted)",
+                    segment,
+                )
+            continue
 
         if not tokens:
             continue
@@ -358,24 +438,6 @@ def validate_init_script(command_string: str) -> tuple[bool, str]:
     return False, f"Only ./init.sh is allowed, got: {script}"
 
 
-def get_command_for_validation(cmd: str, segments: list[str]) -> str:
-    """
-    Find the specific command segment that contains the given command.
-
-    Args:
-        cmd: The command name to find
-        segments: List of command segments
-
-    Returns:
-        The segment containing the command, or empty string if not found
-    """
-    for segment in segments:
-        segment_commands = extract_commands(segment)
-        if cmd in segment_commands:
-            return segment
-    return ""
-
-
 def matches_pattern(command: str, pattern: str) -> bool:
     """
     Check if a command matches a pattern.
@@ -417,6 +479,75 @@ def matches_pattern(command: str, pattern: str) -> bool:
     return False
 
 
+def _validate_command_list(commands: list, config_path: Path, field_name: str) -> bool:
+    """
+    Validate a list of command entries from a YAML config.
+
+    Each entry must be a dict with a non-empty string 'name' field.
+    Used by both load_org_config() and load_project_commands() to avoid
+    duplicating the same validation logic.
+
+    Args:
+        commands: List of command entries to validate
+        config_path: Path to the config file (for log messages)
+        field_name: Name of the YAML field being validated (e.g., 'allowed_commands', 'commands')
+
+    Returns:
+        True if all entries are valid, False otherwise
+    """
+    if not isinstance(commands, list):
+        logger.warning(f"Config at {config_path}: '{field_name}' must be a list")
+        return False
+    for i, cmd in enumerate(commands):
+        if not isinstance(cmd, dict):
+            logger.warning(f"Config at {config_path}: {field_name}[{i}] must be a dict")
+            return False
+        if "name" not in cmd:
+            logger.warning(f"Config at {config_path}: {field_name}[{i}] missing 'name'")
+            return False
+        if not isinstance(cmd["name"], str) or cmd["name"].strip() == "":
+            logger.warning(f"Config at {config_path}: {field_name}[{i}] has invalid 'name'")
+            return False
+    return True
+
+
+def _validate_pkill_processes(config: dict, config_path: Path) -> Optional[list[str]]:
+    """
+    Validate and normalize pkill_processes from a YAML config.
+
+    Each entry must be a non-empty string matching VALID_PROCESS_NAME_PATTERN
+    (alphanumeric, dots, underscores, hyphens only -- no regex metacharacters).
+    Used by both load_org_config() and load_project_commands().
+
+    Args:
+        config: Parsed YAML config dict that may contain 'pkill_processes'
+        config_path: Path to the config file (for log messages)
+
+    Returns:
+        Normalized list of process names, or None if validation fails.
+        Returns an empty list if 'pkill_processes' is not present.
+    """
+    if "pkill_processes" not in config:
+        return []
+
+    processes = config["pkill_processes"]
+    if not isinstance(processes, list):
+        logger.warning(f"Config at {config_path}: 'pkill_processes' must be a list")
+        return None
+
+    normalized = []
+    for i, proc in enumerate(processes):
+        if not isinstance(proc, str):
+            logger.warning(f"Config at {config_path}: pkill_processes[{i}] must be a string")
+            return None
+        proc = proc.strip()
+        if not proc or not VALID_PROCESS_NAME_PATTERN.fullmatch(proc):
+            logger.warning(f"Config at {config_path}: pkill_processes[{i}] has invalid value '{proc}'")
+            return None
+        normalized.append(proc)
+    return normalized
+
+
 def get_org_config_path() -> Path:
     """
     Get the organization-level config file path.
@@ -444,58 +575,48 @@ def load_org_config() -> Optional[dict]:
             config = yaml.safe_load(f)
 
         if not config:
+            logger.warning(f"Org config at {config_path} is empty")
             return None
 
         # Validate structure
         if not isinstance(config, dict):
+            logger.warning(f"Org config at {config_path} must be a YAML dictionary")
             return None
 
         if "version" not in config:
+            logger.warning(f"Org config at {config_path} missing required 'version' field")
             return None
 
         # Validate allowed_commands if present
         if "allowed_commands" in config:
-            allowed = config["allowed_commands"]
+            if not _validate_command_list(config["allowed_commands"], config_path, "allowed_commands"):
-            if not isinstance(allowed, list):
                 return None
-            for cmd in allowed:
-                if not isinstance(cmd, dict):
-                    return None
-                if "name" not in cmd:
-                    return None
-                # Validate that name is a non-empty string
-                if not isinstance(cmd["name"], str) or cmd["name"].strip() == "":
-                    return None
 
         # Validate blocked_commands if present
         if "blocked_commands" in config:
             blocked = config["blocked_commands"]
             if not isinstance(blocked, list):
+                logger.warning(f"Org config at {config_path}: 'blocked_commands' must be a list")
                 return None
-            for cmd in blocked:
+            for i, cmd in enumerate(blocked):
                 if not isinstance(cmd, str):
+                    logger.warning(f"Org config at {config_path}: blocked_commands[{i}] must be a string")
                     return None
 
         # Validate pkill_processes if present
-        if "pkill_processes" in config:
+        normalized = _validate_pkill_processes(config, config_path)
-            processes = config["pkill_processes"]
+        if normalized is None:
-            if not isinstance(processes, list):
+            return None
-                return None
+        if normalized:
-            # Normalize and validate each process name against safe pattern
-            normalized = []
-            for proc in processes:
-                if not isinstance(proc, str):
-                    return None
-                proc = proc.strip()
-                # Block empty strings and regex metacharacters
-                if not proc or not VALID_PROCESS_NAME_PATTERN.fullmatch(proc):
-                    return None
-                normalized.append(proc)
             config["pkill_processes"] = normalized
 
         return config
 
-    except (yaml.YAMLError, IOError, OSError):
+    except yaml.YAMLError as e:
+        logger.warning(f"Failed to parse org config at {config_path}: {e}")
+        return None
+    except (IOError, OSError) as e:
+        logger.warning(f"Failed to read org config at {config_path}: {e}")
         return None
 
 
@@ -509,7 +630,7 @@ def load_project_commands(project_dir: Path) -> Optional[dict]:
     Returns:
         Dict with parsed YAML config, or None if file doesn't exist or is invalid
     """
-    config_path = project_dir / ".autocoder" / "allowed_commands.yaml"
+    config_path = project_dir.resolve() / ".autocoder" / "allowed_commands.yaml"
 
     if not config_path.exists():
         return None
@@ -519,53 +640,43 @@ def load_project_commands(project_dir: Path) -> Optional[dict]:
             config = yaml.safe_load(f)
 
         if not config:
+            logger.warning(f"Project config at {config_path} is empty")
             return None
 
         # Validate structure
         if not isinstance(config, dict):
+            logger.warning(f"Project config at {config_path} must be a YAML dictionary")
             return None
 
         if "version" not in config:
+            logger.warning(f"Project config at {config_path} missing required 'version' field")
             return None
 
         commands = config.get("commands", [])
-        if not isinstance(commands, list):
-            return None
 
         # Enforce 100 command limit
-        if len(commands) > 100:
+        if isinstance(commands, list) and len(commands) > 100:
+            logger.warning(f"Project config at {config_path} exceeds 100 command limit ({len(commands)} commands)")
             return None
 
-        # Validate each command entry
+        # Validate each command entry using shared helper
-        for cmd in commands:
+        if not _validate_command_list(commands, config_path, "commands"):
-            if not isinstance(cmd, dict):
+            return None
-                return None
-            if "name" not in cmd:
-                return None
-            # Validate name is a string
-            if not isinstance(cmd["name"], str):
-                return None
 
         # Validate pkill_processes if present
-        if "pkill_processes" in config:
+        normalized = _validate_pkill_processes(config, config_path)
-            processes = config["pkill_processes"]
+        if normalized is None:
-            if not isinstance(processes, list):
+            return None
-                return None
+        if normalized:
-            # Normalize and validate each process name against safe pattern
-            normalized = []
-            for proc in processes:
-                if not isinstance(proc, str):
-                    return None
-                proc = proc.strip()
-                # Block empty strings and regex metacharacters
-                if not proc or not VALID_PROCESS_NAME_PATTERN.fullmatch(proc):
-                    return None
-                normalized.append(proc)
             config["pkill_processes"] = normalized
 
         return config
 
-    except (yaml.YAMLError, IOError, OSError):
+    except yaml.YAMLError as e:
+        logger.warning(f"Failed to parse project config at {config_path}: {e}")
+        return None
+    except (IOError, OSError) as e:
+        logger.warning(f"Failed to read project config at {config_path}: {e}")
         return None
 
 
@@ -573,8 +684,12 @@ def validate_project_command(cmd_config: dict) -> tuple[bool, str]:
     """
     Validate a single command entry from project config.
 
+    Checks that the command has a valid name and is not in any blocklist.
+    Called during hierarchy resolution to gate each project command before
+    it is added to the effective allowed set.
+
     Args:
-        cmd_config: Dict with command configuration (name, description, args)
+        cmd_config: Dict with command configuration (name, description)
 
     Returns:
         Tuple of (is_valid, error_message)
@@ -604,15 +719,6 @@ def validate_project_command(cmd_config: dict) -> tuple[bool, str]:
     if "description" in cmd_config and not isinstance(cmd_config["description"], str):
         return False, "Description must be a string"
 
-    # Args validation (Phase 1 - just check structure)
-    if "args" in cmd_config:
-        args = cmd_config["args"]
-        if not isinstance(args, list):
-            return False, "Args must be a list"
-        for arg in args:
-            if not isinstance(arg, str):
-                return False, "Each arg must be a string"
-
     return True, ""
 
 
@@ -813,8 +919,13 @@ async def bash_security_hook(input_data, tool_use_id=None, context=None):
 
         # Additional validation for sensitive commands
         if cmd in COMMANDS_NEEDING_EXTRA_VALIDATION:
-            # Find the specific segment containing this command
+            # Find the specific segment containing this command by searching
-            cmd_segment = get_command_for_validation(cmd, segments)
+            # each segment's extracted commands for a match
+            cmd_segment = ""
+            for segment in segments:
+                if cmd in extract_commands(segment):
+                    cmd_segment = segment
+                    break
             if not cmd_segment:
                 cmd_segment = command  # Fallback to full command
 

server/main.py

@@ -7,6 +7,7 @@ Provides REST API, WebSocket, and static file serving.
 """
 
 import asyncio
+import logging
 import os
 import shutil
 import sys
@@ -42,6 +43,7 @@ from .routers import (
 )
 from .schemas import SetupStatus
 from .services.assistant_chat_session import cleanup_all_sessions as cleanup_assistant_sessions
+from .services.chat_constants import ROOT_DIR
 from .services.dev_server_manager import (
     cleanup_all_devservers,
     cleanup_orphaned_devserver_locks,
@@ -53,7 +55,6 @@ from .services.terminal_manager import cleanup_all_terminals
 from .websocket import project_websocket
 
 # Paths
-ROOT_DIR = Path(__file__).parent.parent
 UI_DIST_DIR = ROOT_DIR / "ui" / "dist"
 
 
@@ -88,10 +89,19 @@ app = FastAPI(
     lifespan=lifespan,
 )
 
+# Module logger
+logger = logging.getLogger(__name__)
+
 # Check if remote access is enabled via environment variable
 # Set by start_ui.py when --host is not 127.0.0.1
 ALLOW_REMOTE = os.environ.get("AUTOCODER_ALLOW_REMOTE", "").lower() in ("1", "true", "yes")
 
+if ALLOW_REMOTE:
+    logger.warning(
+        "ALLOW_REMOTE is enabled. Terminal WebSocket is exposed without sandboxing. "
+        "Only use this in trusted network environments."
+    )
+
 # CORS - allow all origins when remote access is enabled, otherwise localhost only
 if ALLOW_REMOTE:
     app.add_middleware(
@@ -222,7 +232,14 @@ if UI_DIST_DIR.exists():
             raise HTTPException(status_code=404)
 
         # Try to serve the file directly
-        file_path = UI_DIST_DIR / path
+        file_path = (UI_DIST_DIR / path).resolve()
+
+        # Ensure resolved path is within UI_DIST_DIR (prevent path traversal)
+        try:
+            file_path.relative_to(UI_DIST_DIR.resolve())
+        except ValueError:
+            raise HTTPException(status_code=404)
+
         if file_path.exists() and file_path.is_file():
             return FileResponse(file_path)
 

server/routers/agent.py

@@ -6,31 +6,22 @@ API endpoints for agent control (start/stop/pause/resume).
 Uses project registry for path lookups.
 """
 
-import re
 from pathlib import Path
 
 from fastapi import APIRouter, HTTPException
 
 from ..schemas import AgentActionResponse, AgentStartRequest, AgentStatus
+from ..services.chat_constants import ROOT_DIR
 from ..services.process_manager import get_manager
+from ..utils.project_helpers import get_project_path as _get_project_path
+from ..utils.validation import validate_project_name
 
 
-def _get_project_path(project_name: str) -> Path:
+def _get_settings_defaults() -> tuple[bool, str, int, bool, int]:
-    """Get project path from registry."""
-    import sys
-    root = Path(__file__).parent.parent.parent
-    if str(root) not in sys.path:
-        sys.path.insert(0, str(root))
-
-    from registry import get_project_path
-    return get_project_path(project_name)
-
-
-def _get_settings_defaults() -> tuple[bool, str, int]:
     """Get defaults from global settings.
 
     Returns:
-        Tuple of (yolo_mode, model, testing_agent_ratio)
+        Tuple of (yolo_mode, model, testing_agent_ratio, playwright_headless, batch_size)
     """
     import sys
     root = Path(__file__).parent.parent.parent
@@ -49,24 +40,18 @@ def _get_settings_defaults() -> tuple[bool, str, int]:
     except (ValueError, TypeError):
         testing_agent_ratio = 1
 
-    return yolo_mode, model, testing_agent_ratio
+    playwright_headless = (settings.get("playwright_headless") or "true").lower() == "true"
+
+    try:
+        batch_size = int(settings.get("batch_size", "3"))
+    except (ValueError, TypeError):
+        batch_size = 3
+
+    return yolo_mode, model, testing_agent_ratio, playwright_headless, batch_size
 
 
 router = APIRouter(prefix="/api/projects/{project_name}/agent", tags=["agent"])
 
-# Root directory for process manager
-ROOT_DIR = Path(__file__).parent.parent.parent
-
-
-def validate_project_name(name: str) -> str:
-    """Validate and sanitize project name to prevent path traversal."""
-    if not re.match(r'^[a-zA-Z0-9_-]{1,50}$', name):
-        raise HTTPException(
-            status_code=400,
-            detail="Invalid project name"
-        )
-    return name
-
 
 def get_project_manager(project_name: str):
     """Get the process manager for a project."""
@@ -111,18 +96,22 @@ async def start_agent(
     manager = get_project_manager(project_name)
 
     # Get defaults from global settings if not provided in request
-    default_yolo, default_model, default_testing_ratio = _get_settings_defaults()
+    default_yolo, default_model, default_testing_ratio, playwright_headless, default_batch_size = _get_settings_defaults()
 
     yolo_mode = request.yolo_mode if request.yolo_mode is not None else default_yolo
     model = request.model if request.model else default_model
     max_concurrency = request.max_concurrency or 1
     testing_agent_ratio = request.testing_agent_ratio if request.testing_agent_ratio is not None else default_testing_ratio
 
+    batch_size = default_batch_size
+
     success, message = await manager.start(
         yolo_mode=yolo_mode,
         model=model,
         max_concurrency=max_concurrency,
         testing_agent_ratio=testing_agent_ratio,
+        playwright_headless=playwright_headless,
+        batch_size=batch_size,
     )
 
     # Notify scheduler of manual start (to prevent auto-stop during scheduled window)

server/routers/assistant_chat.py

@@ -7,8 +7,6 @@ WebSocket and REST endpoints for the read-only project assistant.
 
 import json
 import logging
-import re
-from pathlib import Path
 from typing import Optional
 
 from fastapi import APIRouter, HTTPException, WebSocket, WebSocketDisconnect
@@ -27,30 +25,13 @@ from ..services.assistant_database import (
     get_conversation,
     get_conversations,
 )
+from ..utils.project_helpers import get_project_path as _get_project_path
+from ..utils.validation import is_valid_project_name as validate_project_name
 
 logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/api/assistant", tags=["assistant-chat"])
 
-# Root directory
-ROOT_DIR = Path(__file__).parent.parent.parent
-
-
-def _get_project_path(project_name: str) -> Optional[Path]:
-    """Get project path from registry."""
-    import sys
-    root = Path(__file__).parent.parent.parent
-    if str(root) not in sys.path:
-        sys.path.insert(0, str(root))
-
-    from registry import get_project_path
-    return get_project_path(project_name)
-
-
-def validate_project_name(name: str) -> bool:
-    """Validate project name to prevent path traversal."""
-    return bool(re.match(r'^[a-zA-Z0-9_-]{1,50}$', name))
-
 
 # ============================================================================
 # Pydantic Models
@@ -145,9 +126,9 @@ async def create_project_conversation(project_name: str):
 
     conversation = create_conversation(project_dir, project_name)
     return ConversationSummary(
-        id=conversation.id,
+        id=int(conversation.id),
-        project_name=conversation.project_name,
+        project_name=str(conversation.project_name),
-        title=conversation.title,
+        title=str(conversation.title) if conversation.title else None,
         created_at=conversation.created_at.isoformat() if conversation.created_at else None,
         updated_at=conversation.updated_at.isoformat() if conversation.updated_at else None,
         message_count=0,

server/routers/devserver.py

@@ -6,7 +6,7 @@ API endpoints for dev server control (start/stop) and configuration.
 Uses project registry for path lookups and project_config for command detection.
 """
 
-import re
+import logging
 import sys
 from pathlib import Path
 
@@ -26,38 +26,22 @@ from ..services.project_config import (
     get_project_config,
     set_dev_command,
 )
+from ..utils.project_helpers import get_project_path as _get_project_path
+from ..utils.validation import validate_project_name
 
-# Add root to path for registry import
+# Add root to path for security module import
 _root = Path(__file__).parent.parent.parent
 if str(_root) not in sys.path:
     sys.path.insert(0, str(_root))
 
-from registry import get_project_path as registry_get_project_path
+from security import extract_commands, get_effective_commands, is_command_allowed
 
-
+logger = logging.getLogger(__name__)
-def _get_project_path(project_name: str) -> Path | None:
-    """Get project path from registry."""
-    return registry_get_project_path(project_name)
 
 
 router = APIRouter(prefix="/api/projects/{project_name}/devserver", tags=["devserver"])
 
 
-# ============================================================================
-# Helper Functions
-# ============================================================================
-
-
-def validate_project_name(name: str) -> str:
-    """Validate and sanitize project name to prevent path traversal."""
-    if not re.match(r'^[a-zA-Z0-9_-]{1,50}$', name):
-        raise HTTPException(
-            status_code=400,
-            detail="Invalid project name"
-        )
-    return name
-
-
 def get_project_dir(project_name: str) -> Path:
     """
     Get the validated project directory for a project name.
@@ -106,6 +90,45 @@ def get_project_devserver_manager(project_name: str):
     return get_devserver_manager(project_name, project_dir)
 
 
+def validate_dev_command(command: str, project_dir: Path) -> None:
+    """
+    Validate a dev server command against the security allowlist.
+
+    Extracts all commands from the shell string and checks each against
+    the effective allowlist (global + org + project). Raises HTTPException
+    if any command is blocked or not allowed.
+
+    Args:
+        command: The shell command string to validate
+        project_dir: Project directory for loading project-level allowlists
+
+    Raises:
+        HTTPException 400: If the command fails validation
+    """
+    commands = extract_commands(command)
+    if not commands:
+        raise HTTPException(
+            status_code=400,
+            detail="Could not parse command for security validation"
+        )
+
+    allowed_commands, blocked_commands = get_effective_commands(project_dir)
+
+    for cmd in commands:
+        if cmd in blocked_commands:
+            logger.warning("Blocked dev server command '%s' (in blocklist) for project dir %s", cmd, project_dir)
+            raise HTTPException(
+                status_code=400,
+                detail=f"Command '{cmd}' is blocked and cannot be used as a dev server command"
+            )
+        if not is_command_allowed(cmd, allowed_commands):
+            logger.warning("Rejected dev server command '%s' (not in allowlist) for project dir %s", cmd, project_dir)
+            raise HTTPException(
+                status_code=400,
+                detail=f"Command '{cmd}' is not in the allowed commands list"
+            )
+
+
 # ============================================================================
 # Endpoints
 # ============================================================================
@@ -167,7 +190,10 @@ async def start_devserver(
             detail="No dev command available. Configure a custom command or ensure project type can be detected."
         )
 
-    # Now command is definitely str
+    # Validate command against security allowlist before execution
+    validate_dev_command(command, project_dir)
+
+    # Now command is definitely str and validated
     success, message = await manager.start(command)
 
     return DevServerActionResponse(
@@ -258,6 +284,9 @@ async def update_devserver_config(
         except ValueError as e:
             raise HTTPException(status_code=400, detail=str(e))
     else:
+        # Validate command against security allowlist before persisting
+        validate_dev_command(update.custom_command, project_dir)
+
         # Set the custom command
         try:
             set_dev_command(project_dir, update.custom_command)

server/routers/expand_project.py

@@ -8,7 +8,6 @@ Allows adding multiple features to existing projects via natural language.
 
 import json
 import logging
-from pathlib import Path
 from typing import Optional
 
 from fastapi import APIRouter, HTTPException, WebSocket, WebSocketDisconnect
@@ -22,27 +21,13 @@ from ..services.expand_chat_session import (
     list_expand_sessions,
     remove_expand_session,
 )
+from ..utils.project_helpers import get_project_path as _get_project_path
 from ..utils.validation import validate_project_name
 
 logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/api/expand", tags=["expand-project"])
 
-# Root directory
-ROOT_DIR = Path(__file__).parent.parent.parent
-
-
-def _get_project_path(project_name: str) -> Path:
-    """Get project path from registry."""
-    import sys
-    root = Path(__file__).parent.parent.parent
-    if str(root) not in sys.path:
-        sys.path.insert(0, str(root))
-
-    from registry import get_project_path
-    return get_project_path(project_name)
-
-
 
 
 # ============================================================================
@@ -136,7 +121,8 @@ async def expand_project_websocket(websocket: WebSocket, project_name: str):
         return
 
     # Verify project has app_spec.txt
-    spec_path = project_dir / "prompts" / "app_spec.txt"
+    from autocoder_paths import get_prompts_dir
+    spec_path = get_prompts_dir(project_dir) / "app_spec.txt"
     if not spec_path.exists():
         await websocket.close(code=4004, reason="Project has no spec. Create spec first.")
         return

server/routers/features.py

@@ -8,10 +8,12 @@ API endpoints for feature/test case management.
 import logging
 from contextlib import contextmanager
 from pathlib import Path
+from typing import Literal
 
 from fastapi import APIRouter, HTTPException
 
 from ..schemas import (
+    DependencyGraphEdge,
     DependencyGraphNode,
     DependencyGraphResponse,
     DependencyUpdate,
@@ -22,6 +24,7 @@ from ..schemas import (
     FeatureResponse,
     FeatureUpdate,
 )
+from ..utils.project_helpers import get_project_path as _get_project_path
 from ..utils.validation import validate_project_name
 
 # Lazy imports to avoid circular dependencies
@@ -31,17 +34,6 @@ _Feature = None
 logger = logging.getLogger(__name__)
 
 
-def _get_project_path(project_name: str) -> Path:
-    """Get project path from registry."""
-    import sys
-    root = Path(__file__).parent.parent.parent
-    if str(root) not in sys.path:
-        sys.path.insert(0, str(root))
-
-    from registry import get_project_path
-    return get_project_path(project_name)
-
-
 def _get_db_classes():
     """Lazy import of database classes."""
     global _create_database, _Feature
@@ -71,6 +63,9 @@ def get_db_session(project_dir: Path):
     session = SessionLocal()
     try:
         yield session
+    except Exception:
+        session.rollback()
+        raise
     finally:
         session.close()
 
@@ -131,7 +126,8 @@ async def list_features(project_name: str):
     if not project_dir.exists():
         raise HTTPException(status_code=404, detail="Project directory not found")
 
-    db_file = project_dir / "features.db"
+    from autocoder_paths import get_features_db_path
+    db_file = get_features_db_path(project_dir)
     if not db_file.exists():
         return FeatureListResponse(pending=[], in_progress=[], done=[])
 
@@ -326,7 +322,8 @@ async def get_dependency_graph(project_name: str):
     if not project_dir.exists():
         raise HTTPException(status_code=404, detail="Project directory not found")
 
-    db_file = project_dir / "features.db"
+    from autocoder_paths import get_features_db_path
+    db_file = get_features_db_path(project_dir)
     if not db_file.exists():
         return DependencyGraphResponse(nodes=[], edges=[])
 
@@ -344,6 +341,7 @@ async def get_dependency_graph(project_name: str):
                 deps = f.dependencies or []
                 blocking = [d for d in deps if d not in passing_ids]
 
+                status: Literal["pending", "in_progress", "done", "blocked"]
                 if f.passes:
                     status = "done"
                 elif blocking:
@@ -363,7 +361,7 @@ async def get_dependency_graph(project_name: str):
                 ))
 
                 for dep_id in deps:
-                    edges.append({"source": dep_id, "target": f.id})
+                    edges.append(DependencyGraphEdge(source=dep_id, target=f.id))
 
             return DependencyGraphResponse(nodes=nodes, edges=edges)
     except HTTPException:
@@ -390,7 +388,8 @@ async def get_feature(project_name: str, feature_id: int):
     if not project_dir.exists():
         raise HTTPException(status_code=404, detail="Project directory not found")
 
-    db_file = project_dir / "features.db"
+    from autocoder_paths import get_features_db_path
+    db_file = get_features_db_path(project_dir)
     if not db_file.exists():
         raise HTTPException(status_code=404, detail="No features database found")
 

server/routers/filesystem.py

@@ -6,6 +6,7 @@ API endpoints for browsing the filesystem for project folder selection.
 Provides cross-platform support for Windows, macOS, and Linux.
 """
 
+import functools
 import logging
 import os
 import re
@@ -14,6 +15,8 @@ from pathlib import Path
 
 from fastapi import APIRouter, HTTPException, Query
 
+from security import SENSITIVE_DIRECTORIES
+
 # Module logger
 logger = logging.getLogger(__name__)
 
@@ -77,17 +80,10 @@ LINUX_BLOCKED = {
     "/opt",
 }
 
-# Universal blocked paths (relative to home directory)
+# Universal blocked paths (relative to home directory).
-UNIVERSAL_BLOCKED_RELATIVE = {
+# Delegates to the canonical SENSITIVE_DIRECTORIES set in security.py so that
-    ".ssh",
+# the filesystem browser and the EXTRA_READ_PATHS validator share one source of truth.
-    ".aws",
+UNIVERSAL_BLOCKED_RELATIVE = SENSITIVE_DIRECTORIES
-    ".gnupg",
-    ".config/gh",
-    ".netrc",
-    ".docker",
-    ".kube",
-    ".terraform",
-}
 
 # Patterns for files that should not be shown
 HIDDEN_PATTERNS = [
@@ -99,8 +95,14 @@ HIDDEN_PATTERNS = [
 ]
 
 
-def get_blocked_paths() -> set[Path]:
+@functools.lru_cache(maxsize=1)
-    """Get the set of blocked paths for the current platform."""
+def get_blocked_paths() -> frozenset[Path]:
+    """
+    Get the set of blocked paths for the current platform.
+
+    Cached because the platform and home directory do not change at runtime,
+    and this function is called once per directory entry in list_directory().
+    """
     home = Path.home()
     blocked = set()
 
@@ -119,7 +121,7 @@ def get_blocked_paths() -> set[Path]:
     for rel in UNIVERSAL_BLOCKED_RELATIVE:
         blocked.add((home / rel).resolve())
 
-    return blocked
+    return frozenset(blocked)
 
 
 def is_path_blocked(path: Path) -> bool:

server/routers/projects.py

@@ -10,6 +10,7 @@ import re
 import shutil
 import sys
 from pathlib import Path
+from typing import Any, Callable
 
 from fastapi import APIRouter, HTTPException
 
@@ -18,16 +19,18 @@ from ..schemas import (
     ProjectDetail,
     ProjectPrompts,
     ProjectPromptsUpdate,
+    ProjectSettingsUpdate,
     ProjectStats,
     ProjectSummary,
 )
 
 # Lazy imports to avoid circular dependencies
+# These are initialized by _init_imports() before first use.
 _imports_initialized = False
-_check_spec_exists = None
+_check_spec_exists: Callable[..., Any] | None = None
-_scaffold_project_prompts = None
+_scaffold_project_prompts: Callable[..., Any] | None = None
-_get_project_prompts_dir = None
+_get_project_prompts_dir: Callable[..., Any] | None = None
-_count_passing_tests = None
+_count_passing_tests: Callable[..., Any] | None = None
 
 
 def _init_imports():
@@ -63,13 +66,23 @@ def _get_registry_functions():
         sys.path.insert(0, str(root))
 
     from registry import (
+        get_project_concurrency,
         get_project_path,
         list_registered_projects,
         register_project,
+        set_project_concurrency,
         unregister_project,
         validate_project_path,
     )
-    return register_project, unregister_project, get_project_path, list_registered_projects, validate_project_path
+    return (
+        register_project,
+        unregister_project,
+        get_project_path,
+        list_registered_projects,
+        validate_project_path,
+        get_project_concurrency,
+        set_project_concurrency,
+    )
 
 
 router = APIRouter(prefix="/api/projects", tags=["projects"])
@@ -88,6 +101,7 @@ def validate_project_name(name: str) -> str:
 def get_project_stats(project_dir: Path) -> ProjectStats:
     """Get statistics for a project."""
     _init_imports()
+    assert _count_passing_tests is not None  # guaranteed by _init_imports()
     passing, in_progress, total = _count_passing_tests(project_dir)
     percentage = (passing / total * 100) if total > 0 else 0.0
     return ProjectStats(
@@ -102,7 +116,9 @@ def get_project_stats(project_dir: Path) -> ProjectStats:
 async def list_projects():
     """List all registered projects."""
     _init_imports()
-    _, _, _, list_registered_projects, validate_project_path = _get_registry_functions()
+    assert _check_spec_exists is not None  # guaranteed by _init_imports()
+    (_, _, _, list_registered_projects, validate_project_path,
+     get_project_concurrency, _) = _get_registry_functions()
 
     projects = list_registered_projects()
     result = []
@@ -123,6 +139,7 @@ async def list_projects():
             path=info["path"],
             has_spec=has_spec,
             stats=stats,
+            default_concurrency=info.get("default_concurrency", 3),
         ))
 
     return result
@@ -132,7 +149,9 @@ async def list_projects():
 async def create_project(project: ProjectCreate):
     """Create a new project at the specified path."""
     _init_imports()
-    register_project, _, get_project_path, list_registered_projects, _ = _get_registry_functions()
+    assert _scaffold_project_prompts is not None  # guaranteed by _init_imports()
+    (register_project, _, get_project_path, list_registered_projects,
+     _, _, _) = _get_registry_functions()
 
     name = validate_project_name(project.name)
     project_path = Path(project.path).resolve()
@@ -203,6 +222,7 @@ async def create_project(project: ProjectCreate):
         path=project_path.as_posix(),
         has_spec=False,  # Just created, no spec yet
         stats=ProjectStats(passing=0, total=0, percentage=0.0),
+        default_concurrency=3,
     )
 
 
@@ -210,7 +230,9 @@ async def create_project(project: ProjectCreate):
 async def get_project(name: str):
     """Get detailed information about a project."""
     _init_imports()
-    _, _, get_project_path, _, _ = _get_registry_functions()
+    assert _check_spec_exists is not None  # guaranteed by _init_imports()
+    assert _get_project_prompts_dir is not None  # guaranteed by _init_imports()
+    (_, _, get_project_path, _, _, get_project_concurrency, _) = _get_registry_functions()
 
     name = validate_project_name(name)
     project_dir = get_project_path(name)
@@ -231,6 +253,7 @@ async def get_project(name: str):
         has_spec=has_spec,
         stats=stats,
         prompts_dir=str(prompts_dir),
+        default_concurrency=get_project_concurrency(name),
     )
 
 
@@ -244,7 +267,7 @@ async def delete_project(name: str, delete_files: bool = False):
         delete_files: If True, also delete the project directory and files
     """
     _init_imports()
-    _, unregister_project, get_project_path, _, _ = _get_registry_functions()
+    (_, unregister_project, get_project_path, _, _, _, _) = _get_registry_functions()
 
     name = validate_project_name(name)
     project_dir = get_project_path(name)
@@ -253,8 +276,8 @@ async def delete_project(name: str, delete_files: bool = False):
         raise HTTPException(status_code=404, detail=f"Project '{name}' not found")
 
     # Check if agent is running
-    lock_file = project_dir / ".agent.lock"
+    from autocoder_paths import has_agent_running
-    if lock_file.exists():
+    if has_agent_running(project_dir):
         raise HTTPException(
             status_code=409,
             detail="Cannot delete project while agent is running. Stop the agent first."
@@ -280,7 +303,8 @@ async def delete_project(name: str, delete_files: bool = False):
 async def get_project_prompts(name: str):
     """Get the content of project prompt files."""
     _init_imports()
-    _, _, get_project_path, _, _ = _get_registry_functions()
+    assert _get_project_prompts_dir is not None  # guaranteed by _init_imports()
+    (_, _, get_project_path, _, _, _, _) = _get_registry_functions()
 
     name = validate_project_name(name)
     project_dir = get_project_path(name)
@@ -291,7 +315,7 @@ async def get_project_prompts(name: str):
     if not project_dir.exists():
         raise HTTPException(status_code=404, detail="Project directory not found")
 
-    prompts_dir = _get_project_prompts_dir(project_dir)
+    prompts_dir: Path = _get_project_prompts_dir(project_dir)
 
     def read_file(filename: str) -> str:
         filepath = prompts_dir / filename
@@ -313,7 +337,8 @@ async def get_project_prompts(name: str):
 async def update_project_prompts(name: str, prompts: ProjectPromptsUpdate):
     """Update project prompt files."""
     _init_imports()
-    _, _, get_project_path, _, _ = _get_registry_functions()
+    assert _get_project_prompts_dir is not None  # guaranteed by _init_imports()
+    (_, _, get_project_path, _, _, _, _) = _get_registry_functions()
 
     name = validate_project_name(name)
     project_dir = get_project_path(name)
@@ -343,7 +368,7 @@ async def update_project_prompts(name: str, prompts: ProjectPromptsUpdate):
 async def get_project_stats_endpoint(name: str):
     """Get current progress statistics for a project."""
     _init_imports()
-    _, _, get_project_path, _, _ = _get_registry_functions()
+    (_, _, get_project_path, _, _, _, _) = _get_registry_functions()
 
     name = validate_project_name(name)
     project_dir = get_project_path(name)
@@ -355,3 +380,145 @@ async def get_project_stats_endpoint(name: str):
         raise HTTPException(status_code=404, detail="Project directory not found")
 
     return get_project_stats(project_dir)
+
+
+@router.post("/{name}/reset")
+async def reset_project(name: str, full_reset: bool = False):
+    """
+    Reset a project to its initial state.
+
+    Args:
+        name: Project name to reset
+        full_reset: If True, also delete prompts/ directory (triggers setup wizard)
+
+    Returns:
+        Dictionary with list of deleted files and reset type
+    """
+    _init_imports()
+    (_, _, get_project_path, _, _, _, _) = _get_registry_functions()
+
+    name = validate_project_name(name)
+    project_dir = get_project_path(name)
+
+    if not project_dir:
+        raise HTTPException(status_code=404, detail=f"Project '{name}' not found")
+
+    if not project_dir.exists():
+        raise HTTPException(status_code=404, detail="Project directory not found")
+
+    # Check if agent is running
+    from autocoder_paths import has_agent_running
+    if has_agent_running(project_dir):
+        raise HTTPException(
+            status_code=409,
+            detail="Cannot reset project while agent is running. Stop the agent first."
+        )
+
+    # Dispose of database engines to release file locks (required on Windows)
+    # Import here to avoid circular imports
+    from api.database import dispose_engine as dispose_features_engine
+    from server.services.assistant_database import dispose_engine as dispose_assistant_engine
+
+    dispose_features_engine(project_dir)
+    dispose_assistant_engine(project_dir)
+
+    deleted_files: list[str] = []
+
+    from autocoder_paths import (
+        get_assistant_db_path,
+        get_claude_assistant_settings_path,
+        get_claude_settings_path,
+        get_features_db_path,
+    )
+
+    # Build list of files to delete using path helpers (finds files at current location)
+    # Plus explicit old-location fallbacks for backward compatibility
+    db_path = get_features_db_path(project_dir)
+    asst_path = get_assistant_db_path(project_dir)
+    reset_files: list[Path] = [
+        db_path,
+        db_path.with_suffix(".db-wal"),
+        db_path.with_suffix(".db-shm"),
+        asst_path,
+        asst_path.with_suffix(".db-wal"),
+        asst_path.with_suffix(".db-shm"),
+        get_claude_settings_path(project_dir),
+        get_claude_assistant_settings_path(project_dir),
+        # Also clean old root-level locations if they exist
+        project_dir / "features.db",
+        project_dir / "features.db-wal",
+        project_dir / "features.db-shm",
+        project_dir / "assistant.db",
+        project_dir / "assistant.db-wal",
+        project_dir / "assistant.db-shm",
+        project_dir / ".claude_settings.json",
+        project_dir / ".claude_assistant_settings.json",
+    ]
+
+    for file_path in reset_files:
+        if file_path.exists():
+            try:
+                relative = file_path.relative_to(project_dir)
+                file_path.unlink()
+                deleted_files.append(str(relative))
+            except Exception as e:
+                raise HTTPException(status_code=500, detail=f"Failed to delete {file_path.name}: {e}")
+
+    # Full reset: also delete prompts directory
+    if full_reset:
+        from autocoder_paths import get_prompts_dir
+        # Delete prompts from both possible locations
+        for prompts_dir in [get_prompts_dir(project_dir), project_dir / "prompts"]:
+            if prompts_dir.exists():
+                try:
+                    relative = prompts_dir.relative_to(project_dir)
+                    shutil.rmtree(prompts_dir)
+                    deleted_files.append(f"{relative}/")
+                except Exception as e:
+                    raise HTTPException(status_code=500, detail=f"Failed to delete prompts: {e}")
+
+    return {
+        "success": True,
+        "reset_type": "full" if full_reset else "quick",
+        "deleted_files": deleted_files,
+        "message": f"Project '{name}' has been reset" + (" (full reset)" if full_reset else " (quick reset)")
+    }
+
+
+@router.patch("/{name}/settings", response_model=ProjectDetail)
+async def update_project_settings(name: str, settings: ProjectSettingsUpdate):
+    """Update project-level settings (concurrency, etc.)."""
+    _init_imports()
+    assert _check_spec_exists is not None  # guaranteed by _init_imports()
+    assert _get_project_prompts_dir is not None  # guaranteed by _init_imports()
+    (_, _, get_project_path, _, _, get_project_concurrency,
+     set_project_concurrency) = _get_registry_functions()
+
+    name = validate_project_name(name)
+    project_dir = get_project_path(name)
+
+    if not project_dir:
+        raise HTTPException(status_code=404, detail=f"Project '{name}' not found")
+
+    if not project_dir.exists():
+        raise HTTPException(status_code=404, detail="Project directory not found")
+
+    # Update concurrency if provided
+    if settings.default_concurrency is not None:
+        success = set_project_concurrency(name, settings.default_concurrency)
+        if not success:
+            raise HTTPException(status_code=500, detail="Failed to update concurrency")
+
+    # Return updated project details
+    has_spec = _check_spec_exists(project_dir)
+    stats = get_project_stats(project_dir)
+    prompts_dir = _get_project_prompts_dir(project_dir)
+
+    return ProjectDetail(
+        name=name,
+        path=project_dir.as_posix(),
+        has_spec=has_spec,
+        stats=stats,
+        prompts_dir=str(prompts_dir),
+        default_concurrency=get_project_concurrency(name),
+    )

server/routers/schedules.py

@@ -6,12 +6,10 @@ API endpoints for managing agent schedules.
 Provides CRUD operations for time-based schedule configuration.
 """
 
-import re
-import sys
 from contextlib import contextmanager
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
-from typing import Generator, Tuple
+from typing import TYPE_CHECKING, Generator, Tuple
 
 from fastapi import APIRouter, HTTPException
 from sqlalchemy.orm import Session
@@ -26,17 +24,21 @@ from ..schemas import (
     ScheduleResponse,
     ScheduleUpdate,
 )
+from ..utils.project_helpers import get_project_path as _get_project_path
+from ..utils.validation import validate_project_name
+
+if TYPE_CHECKING:
+    from api.database import Schedule as ScheduleModel
 
 
-def _get_project_path(project_name: str) -> Path:
+def _schedule_to_response(schedule: "ScheduleModel") -> ScheduleResponse:
-    """Get project path from registry."""
+    """Convert a Schedule ORM object to a ScheduleResponse Pydantic model.
-    root = Path(__file__).parent.parent.parent
-    if str(root) not in sys.path:
-        sys.path.insert(0, str(root))
-
-    from registry import get_project_path
-    return get_project_path(project_name)
 
+    SQLAlchemy Column descriptors resolve to Python types at instance access time,
+    but mypy sees the Column[T] descriptor type. Using model_validate with
+    from_attributes handles this conversion correctly.
+    """
+    return ScheduleResponse.model_validate(schedule, from_attributes=True)
 
 router = APIRouter(
     prefix="/api/projects/{project_name}/schedules",
@@ -44,16 +46,6 @@ router = APIRouter(
 )
 
 
-def validate_project_name(name: str) -> str:
-    """Validate and sanitize project name to prevent path traversal."""
-    if not re.match(r'^[a-zA-Z0-9_-]{1,50}$', name):
-        raise HTTPException(
-            status_code=400,
-            detail="Invalid project name"
-        )
-    return name
-
-
 @contextmanager
 def _get_db_session(project_name: str) -> Generator[Tuple[Session, Path], None, None]:
     """Get database session for a project as a context manager.
@@ -84,6 +76,9 @@ def _get_db_session(project_name: str) -> Generator[Tuple[Session, Path], None,
     db = SessionLocal()
     try:
         yield db, project_path
+    except Exception:
+        db.rollback()
+        raise
     finally:
         db.close()
 
@@ -99,21 +94,7 @@ async def list_schedules(project_name: str):
         ).order_by(Schedule.start_time).all()
 
         return ScheduleListResponse(
-            schedules=[
+            schedules=[_schedule_to_response(s) for s in schedules]
-                ScheduleResponse(
-                    id=s.id,
-                    project_name=s.project_name,
-                    start_time=s.start_time,
-                    duration_minutes=s.duration_minutes,
-                    days_of_week=s.days_of_week,
-                    enabled=s.enabled,
-                    yolo_mode=s.yolo_mode,
-                    model=s.model,
-                    crash_count=s.crash_count,
-                    created_at=s.created_at,
-                )
-                for s in schedules
-            ]
         )
 
 
@@ -187,18 +168,7 @@ async def create_schedule(project_name: str, data: ScheduleCreate):
                     except Exception as e:
                         logger.error(f"Failed to start agent for schedule {schedule.id}: {e}", exc_info=True)
 
-        return ScheduleResponse(
+        return _schedule_to_response(schedule)
-            id=schedule.id,
-            project_name=schedule.project_name,
-            start_time=schedule.start_time,
-            duration_minutes=schedule.duration_minutes,
-            days_of_week=schedule.days_of_week,
-            enabled=schedule.enabled,
-            yolo_mode=schedule.yolo_mode,
-            model=schedule.model,
-            crash_count=schedule.crash_count,
-            created_at=schedule.created_at,
-        )
 
 
 @router.get("/next", response_model=NextRunResponse)
@@ -256,8 +226,8 @@ async def get_next_scheduled_run(project_name: str):
 
         return NextRunResponse(
             has_schedules=True,
-            next_start=next_start.isoformat() if (active_count == 0 and next_start) else None,
+            next_start=next_start if active_count == 0 else None,
-            next_end=latest_end.isoformat() if latest_end else None,
+            next_end=latest_end,
             is_currently_running=active_count > 0,
             active_schedule_count=active_count,
         )
@@ -277,18 +247,7 @@ async def get_schedule(project_name: str, schedule_id: int):
         if not schedule:
             raise HTTPException(status_code=404, detail="Schedule not found")
 
-        return ScheduleResponse(
+        return _schedule_to_response(schedule)
-            id=schedule.id,
-            project_name=schedule.project_name,
-            start_time=schedule.start_time,
-            duration_minutes=schedule.duration_minutes,
-            days_of_week=schedule.days_of_week,
-            enabled=schedule.enabled,
-            yolo_mode=schedule.yolo_mode,
-            model=schedule.model,
-            crash_count=schedule.crash_count,
-            created_at=schedule.created_at,
-        )
 
 
 @router.patch("/{schedule_id}", response_model=ScheduleResponse)
@@ -331,18 +290,7 @@ async def update_schedule(
             # Was enabled, now disabled - remove jobs
             scheduler.remove_schedule(schedule_id)
 
-        return ScheduleResponse(
+        return _schedule_to_response(schedule)
-            id=schedule.id,
-            project_name=schedule.project_name,
-            start_time=schedule.start_time,
-            duration_minutes=schedule.duration_minutes,
-            days_of_week=schedule.days_of_week,
-            enabled=schedule.enabled,
-            yolo_mode=schedule.yolo_mode,
-            model=schedule.model,
-            crash_count=schedule.crash_count,
-            created_at=schedule.created_at,
-        )
 
 
 @router.delete("/{schedule_id}", status_code=204)

server/routers/settings.py

@@ -9,17 +9,16 @@ Settings are stored in the registry database and shared across all projects.
 import mimetypes
 import os
 import sys
-from pathlib import Path
 
 from fastapi import APIRouter
 
 from ..schemas import ModelInfo, ModelsResponse, SettingsResponse, SettingsUpdate
+from ..services.chat_constants import ROOT_DIR
 
 # Mimetype fix for Windows - must run before StaticFiles is mounted
 mimetypes.add_type("text/javascript", ".js", True)
 
-# Add root to path for registry import
+# Ensure root is on sys.path for registry import
-ROOT_DIR = Path(__file__).parent.parent.parent
 if str(ROOT_DIR) not in sys.path:
     sys.path.insert(0, str(ROOT_DIR))
 
@@ -92,6 +91,8 @@ async def get_settings():
         glm_mode=_is_glm_mode(),
         ollama_mode=_is_ollama_mode(),
         testing_agent_ratio=_parse_int(all_settings.get("testing_agent_ratio"), 1),
+        playwright_headless=_parse_bool(all_settings.get("playwright_headless"), default=True),
+        batch_size=_parse_int(all_settings.get("batch_size"), 3),
     )
 
 
@@ -107,6 +108,12 @@ async def update_settings(update: SettingsUpdate):
     if update.testing_agent_ratio is not None:
         set_setting("testing_agent_ratio", str(update.testing_agent_ratio))
 
+    if update.playwright_headless is not None:
+        set_setting("playwright_headless", "true" if update.playwright_headless else "false")
+
+    if update.batch_size is not None:
+        set_setting("batch_size", str(update.batch_size))
+
     # Return updated settings
     all_settings = get_all_settings()
     return SettingsResponse(
@@ -115,4 +122,6 @@ async def update_settings(update: SettingsUpdate):
         glm_mode=_is_glm_mode(),
         ollama_mode=_is_ollama_mode(),
         testing_agent_ratio=_parse_int(all_settings.get("testing_agent_ratio"), 1),
+        playwright_headless=_parse_bool(all_settings.get("playwright_headless"), default=True),
+        batch_size=_parse_int(all_settings.get("batch_size"), 3),
     )

server/routers/spec_creation.py

@@ -7,8 +7,6 @@ WebSocket and REST endpoints for interactive spec creation with Claude.
 
 import json
 import logging
-import re
-from pathlib import Path
 from typing import Optional
 
 from fastapi import APIRouter, HTTPException, WebSocket, WebSocketDisconnect
@@ -22,30 +20,13 @@ from ..services.spec_chat_session import (
     list_sessions,
     remove_session,
 )
+from ..utils.project_helpers import get_project_path as _get_project_path
+from ..utils.validation import is_valid_project_name as validate_project_name
 
 logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/api/spec", tags=["spec-creation"])
 
-# Root directory
-ROOT_DIR = Path(__file__).parent.parent.parent
-
-
-def _get_project_path(project_name: str) -> Path:
-    """Get project path from registry."""
-    import sys
-    root = Path(__file__).parent.parent.parent
-    if str(root) not in sys.path:
-        sys.path.insert(0, str(root))
-
-    from registry import get_project_path
-    return get_project_path(project_name)
-
-
-def validate_project_name(name: str) -> bool:
-    """Validate project name to prevent path traversal."""
-    return bool(re.match(r'^[a-zA-Z0-9_-]{1,50}$', name))
-
 
 # ============================================================================
 # REST Endpoints
@@ -124,7 +105,8 @@ async def get_spec_file_status(project_name: str):
     if not project_dir.exists():
         raise HTTPException(status_code=404, detail="Project directory not found")
 
-    status_file = project_dir / "prompts" / ".spec_status.json"
+    from autocoder_paths import get_prompts_dir
+    status_file = get_prompts_dir(project_dir) / ".spec_status.json"
 
     if not status_file.exists():
         return SpecFileStatus(

server/routers/terminal.py

@@ -12,8 +12,6 @@ import base64
 import json
 import logging
 import re
-import sys
-from pathlib import Path
 
 from fastapi import APIRouter, HTTPException, WebSocket, WebSocketDisconnect
 from pydantic import BaseModel
@@ -27,13 +25,8 @@ from ..services.terminal_manager import (
     rename_terminal,
     stop_terminal_session,
 )
-
+from ..utils.project_helpers import get_project_path as _get_project_path
-# Add project root to path for registry import
+from ..utils.validation import is_valid_project_name as validate_project_name
-_root = Path(__file__).parent.parent.parent
-if str(_root) not in sys.path:
-    sys.path.insert(0, str(_root))
-
-from registry import get_project_path as registry_get_project_path
 
 logger = logging.getLogger(__name__)
 
@@ -48,27 +41,6 @@ class TerminalCloseCode:
     FAILED_TO_START = 4500
 
 
-def _get_project_path(project_name: str) -> Path | None:
-    """Get project path from registry."""
-    return registry_get_project_path(project_name)
-
-
-def validate_project_name(name: str) -> bool:
-    """
-    Validate project name to prevent path traversal attacks.
-
-    Allows only alphanumeric characters, underscores, and hyphens.
-    Maximum length of 50 characters.
-
-    Args:
-        name: The project name to validate
-
-    Returns:
-        True if valid, False otherwise
-    """
-    return bool(re.match(r"^[a-zA-Z0-9_-]{1,50}$", name))
-
-
 def validate_terminal_id(terminal_id: str) -> bool:
     """
     Validate terminal ID format.

server/schemas.py

@@ -45,6 +45,7 @@ class ProjectSummary(BaseModel):
     path: str
     has_spec: bool
     stats: ProjectStats
+    default_concurrency: int = 3
 
 
 class ProjectDetail(BaseModel):
@@ -54,6 +55,7 @@ class ProjectDetail(BaseModel):
     has_spec: bool
     stats: ProjectStats
     prompts_dir: str
+    default_concurrency: int = 3
 
 
 class ProjectPrompts(BaseModel):
@@ -70,6 +72,18 @@ class ProjectPromptsUpdate(BaseModel):
     coding_prompt: str | None = None
 
 
+class ProjectSettingsUpdate(BaseModel):
+    """Request schema for updating project-level settings."""
+    default_concurrency: int | None = None
+
+    @field_validator('default_concurrency')
+    @classmethod
+    def validate_concurrency(cls, v: int | None) -> int | None:
+        if v is not None and (v < 1 or v > 5):
+            raise ValueError("default_concurrency must be between 1 and 5")
+        return v
+
+
 # ============================================================================
 # Feature Schemas
 # ============================================================================
@@ -384,6 +398,8 @@ class SettingsResponse(BaseModel):
     glm_mode: bool = False  # True if GLM API is configured via .env
     ollama_mode: bool = False  # True if Ollama API is configured via .env
     testing_agent_ratio: int = 1  # Regression testing agents (0-3)
+    playwright_headless: bool = True
+    batch_size: int = 3  # Features per coding agent batch (1-3)
 
 
 class ModelsResponse(BaseModel):
@@ -397,6 +413,8 @@ class SettingsUpdate(BaseModel):
     yolo_mode: bool | None = None
     model: str | None = None
     testing_agent_ratio: int | None = None  # 0-3
+    playwright_headless: bool | None = None
+    batch_size: int | None = None  # Features per agent batch (1-3)
 
     @field_validator('model')
     @classmethod
@@ -412,6 +430,13 @@ class SettingsUpdate(BaseModel):
             raise ValueError("testing_agent_ratio must be between 0 and 3")
         return v
 
+    @field_validator('batch_size')
+    @classmethod
+    def validate_batch_size(cls, v: int | None) -> int | None:
+        if v is not None and (v < 1 or v > 3):
+            raise ValueError("batch_size must be between 1 and 3")
+        return v
+
 
 # ============================================================================
 # Dev Server Schemas

server/services/assistant_chat_session.py

@@ -25,25 +25,13 @@ from .assistant_database import (
     create_conversation,
     get_messages,
 )
+from .chat_constants import API_ENV_VARS, ROOT_DIR
 
 # Load environment variables from .env file if present
 load_dotenv()
 
 logger = logging.getLogger(__name__)
 
-# Root directory of the project
-ROOT_DIR = Path(__file__).parent.parent.parent
-
-# Environment variables to pass through to Claude CLI for API configuration
-API_ENV_VARS = [
-    "ANTHROPIC_BASE_URL",
-    "ANTHROPIC_AUTH_TOKEN",
-    "API_TIMEOUT_MS",
-    "ANTHROPIC_DEFAULT_SONNET_MODEL",
-    "ANTHROPIC_DEFAULT_OPUS_MODEL",
-    "ANTHROPIC_DEFAULT_HAIKU_MODEL",
-]
-
 # Read-only feature MCP tools
 READONLY_FEATURE_MCP_TOOLS = [
     "mcp__features__feature_get_stats",
@@ -76,7 +64,8 @@ def get_system_prompt(project_name: str, project_dir: Path) -> str:
     """Generate the system prompt for the assistant with project context."""
     # Try to load app_spec.txt for context
     app_spec_content = ""
-    app_spec_path = project_dir / "prompts" / "app_spec.txt"
+    from autocoder_paths import get_prompts_dir
+    app_spec_path = get_prompts_dir(project_dir) / "app_spec.txt"
     if app_spec_path.exists():
         try:
             app_spec_content = app_spec_path.read_text(encoding="utf-8")
@@ -90,6 +79,8 @@ def get_system_prompt(project_name: str, project_dir: Path) -> str:
 
 Your role is to help users understand the codebase, answer questions about features, and manage the project backlog. You can READ files and CREATE/MANAGE features, but you cannot modify source code.
 
+You have MCP tools available for feature management. Use them directly by calling the tool -- do not suggest CLI commands, bash commands, or curl commands to the user. You can create features yourself using the feature_create and feature_create_bulk tools.
+
 ## What You CAN Do
 
 **Codebase Analysis (Read-Only):**
@@ -134,17 +125,21 @@ If the user asks you to modify code, explain that you're a project assistant and
 
 ## Creating Features
 
-When a user asks to add a feature, gather the following information:
+When a user asks to add a feature, use the `feature_create` or `feature_create_bulk` MCP tools directly:
-1. **Category**: A grouping like "Authentication", "API", "UI", "Database"
+
-2. **Name**: A concise, descriptive name
+For a **single feature**, call `feature_create` with:
-3. **Description**: What the feature should do
+- category: A grouping like "Authentication", "API", "UI", "Database"
-4. **Steps**: How to verify/implement the feature (as a list)
+- name: A concise, descriptive name
+- description: What the feature should do
+- steps: List of verification/implementation steps
+
+For **multiple features**, call `feature_create_bulk` with an array of feature objects.
 
 You can ask clarifying questions if the user's request is vague, or make reasonable assumptions for simple requests.
 
 **Example interaction:**
 User: "Add a feature for S3 sync"
-You: I'll create that feature. Let me add it to the backlog...
+You: I'll create that feature now.
 [calls feature_create with appropriate parameters]
 You: Done! I've added "S3 Sync Integration" to your backlog. It's now visible on the kanban board.
 
@@ -208,7 +203,7 @@ class AssistantChatSession:
         # Create a new conversation if we don't have one
         if is_new_conversation:
             conv = create_conversation(self.project_dir, self.project_name)
-            self.conversation_id = conv.id
+            self.conversation_id = int(conv.id)  # type coercion: Column[int] -> int
             yield {"type": "conversation_created", "conversation_id": self.conversation_id}
 
         # Build permissions list for assistant access (read + feature management)
@@ -229,7 +224,9 @@ class AssistantChatSession:
                 "allow": permissions_list,
             },
         }
-        settings_file = self.project_dir / ".claude_assistant_settings.json"
+        from autocoder_paths import get_claude_assistant_settings_path
+        settings_file = get_claude_assistant_settings_path(self.project_dir)
+        settings_file.parent.mkdir(parents=True, exist_ok=True)
         with open(settings_file, "w") as f:
             json.dump(security_settings, f, indent=2)
 
@@ -261,7 +258,11 @@ class AssistantChatSession:
         system_cli = shutil.which("claude")
 
         # Build environment overrides for API configuration
-        sdk_env = {var: os.getenv(var) for var in API_ENV_VARS if os.getenv(var)}
+        sdk_env: dict[str, str] = {}
+        for var in API_ENV_VARS:
+            value = os.getenv(var)
+            if value:
+                sdk_env[var] = value
 
         # Determine model from environment or use default
         # This allows using alternative APIs (e.g., GLM via z.ai) that may not support Claude model names
@@ -277,7 +278,7 @@ class AssistantChatSession:
                     # This avoids Windows command line length limit (~8191 chars)
                     setting_sources=["project"],
                     allowed_tools=[*READONLY_BUILTIN_TOOLS, *ASSISTANT_FEATURE_TOOLS],
-                    mcp_servers=mcp_servers,
+                    mcp_servers=mcp_servers,  # type: ignore[arg-type]  # SDK accepts dict config at runtime
                     permission_mode="bypassPermissions",
                     max_turns=100,
                     cwd=str(self.project_dir.resolve()),
@@ -303,6 +304,8 @@ class AssistantChatSession:
                 greeting = f"Hello! I'm your project assistant for **{self.project_name}**. I can help you understand the codebase, explain features, and answer questions about the project. What would you like to know?"
 
                 # Store the greeting in the database
+                # conversation_id is guaranteed non-None here (set on line 206 above)
+                assert self.conversation_id is not None
                 add_message(self.project_dir, self.conversation_id, "assistant", greeting)
 
                 yield {"type": "text", "content": greeting}

server/services/assistant_database.py

@@ -7,20 +7,28 @@ Each project has its own assistant.db file in the project directory.
 """
 
 import logging
+import threading
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
 from sqlalchemy import Column, DateTime, ForeignKey, Integer, String, Text, create_engine, func
-from sqlalchemy.orm import declarative_base, relationship, sessionmaker
+from sqlalchemy.engine import Engine
+from sqlalchemy.orm import DeclarativeBase, relationship, sessionmaker
 
 logger = logging.getLogger(__name__)
 
-Base = declarative_base()
+class Base(DeclarativeBase):
+    """SQLAlchemy 2.0 style declarative base."""
+    pass
 
 # Engine cache to avoid creating new engines for each request
 # Key: project directory path (as posix string), Value: SQLAlchemy engine
-_engine_cache: dict[str, object] = {}
+_engine_cache: dict[str, Engine] = {}
+
+# Lock for thread-safe access to the engine cache
+# Prevents race conditions when multiple threads create engines simultaneously
+_cache_lock = threading.Lock()
 
 
 def _utc_now() -> datetime:
@@ -56,7 +64,8 @@ class ConversationMessage(Base):
 
 def get_db_path(project_dir: Path) -> Path:
     """Get the path to the assistant database for a project."""
-    return project_dir / "assistant.db"
+    from autocoder_paths import get_assistant_db_path
+    return get_assistant_db_path(project_dir)
 
 
 def get_engine(project_dir: Path):
@@ -64,21 +73,57 @@ def get_engine(project_dir: Path):
 
     Uses a cache to avoid creating new engines for each request, which improves
     performance by reusing database connections.
+
+    Thread-safe: Uses a lock to prevent race conditions when multiple threads
+    try to create engines simultaneously for the same project.
     """
     cache_key = project_dir.as_posix()
 
-    if cache_key not in _engine_cache:
+    # Double-checked locking for thread safety and performance
-        db_path = get_db_path(project_dir)
+    if cache_key in _engine_cache:
-        # Use as_posix() for cross-platform compatibility with SQLite connection strings
+        return _engine_cache[cache_key]
-        db_url = f"sqlite:///{db_path.as_posix()}"
+
-        engine = create_engine(db_url, echo=False)
+    with _cache_lock:
-        Base.metadata.create_all(engine)
+        # Check again inside the lock in case another thread created it
-        _engine_cache[cache_key] = engine
+        if cache_key not in _engine_cache:
-        logger.debug(f"Created new database engine for {cache_key}")
+            db_path = get_db_path(project_dir)
+            # Use as_posix() for cross-platform compatibility with SQLite connection strings
+            db_url = f"sqlite:///{db_path.as_posix()}"
+            engine = create_engine(
+                db_url,
+                echo=False,
+                connect_args={
+                    "check_same_thread": False,
+                    "timeout": 30,  # Wait up to 30s for locks
+                }
+            )
+            Base.metadata.create_all(engine)
+            _engine_cache[cache_key] = engine
+            logger.debug(f"Created new database engine for {cache_key}")
 
     return _engine_cache[cache_key]
 
 
+def dispose_engine(project_dir: Path) -> bool:
+    """Dispose of and remove the cached engine for a project.
+
+    This closes all database connections, releasing file locks on Windows.
+    Should be called before deleting the database file.
+
+    Returns:
+        True if an engine was disposed, False if no engine was cached.
+    """
+    cache_key = project_dir.as_posix()
+
+    if cache_key in _engine_cache:
+        engine = _engine_cache.pop(cache_key)
+        engine.dispose()
+        logger.debug(f"Disposed database engine for {cache_key}")
+        return True
+
+    return False
+
+
 def get_session(project_dir: Path):
     """Get a new database session for a project."""
     engine = get_engine(project_dir)

server/services/chat_constants.py

@@ -0,0 +1,57 @@
+"""
+Chat Session Constants
+======================
+
+Shared constants for all chat session types (assistant, spec, expand).
+
+The canonical ``API_ENV_VARS`` list lives in ``env_constants.py`` at the
+project root and is re-exported here for convenience so that existing
+imports (``from .chat_constants import API_ENV_VARS``) continue to work.
+"""
+
+import sys
+from pathlib import Path
+from typing import AsyncGenerator
+
+# -------------------------------------------------------------------
+# Root directory of the autocoder project (repository root).
+# Used throughout the server package whenever the repo root is needed.
+# -------------------------------------------------------------------
+ROOT_DIR = Path(__file__).parent.parent.parent
+
+# Ensure the project root is on sys.path so we can import env_constants
+# from the root-level module without requiring a package install.
+_root_str = str(ROOT_DIR)
+if _root_str not in sys.path:
+    sys.path.insert(0, _root_str)
+
+# -------------------------------------------------------------------
+# Environment variables forwarded to Claude CLI subprocesses.
+# Single source of truth lives in env_constants.py at the project root.
+# Re-exported here so existing ``from .chat_constants import API_ENV_VARS``
+# imports continue to work unchanged.
+# -------------------------------------------------------------------
+from env_constants import API_ENV_VARS  # noqa: E402, F401
+
+
+async def make_multimodal_message(content_blocks: list[dict]) -> AsyncGenerator[dict, None]:
+    """Yield a single multimodal user message in Claude Agent SDK format.
+
+    The Claude Agent SDK's ``query()`` method accepts either a plain string
+    or an ``AsyncIterable[dict]`` for custom message formats.  This helper
+    wraps a list of content blocks (text and/or images) in the expected
+    envelope.
+
+    Args:
+        content_blocks: List of content-block dicts, e.g.
+            ``[{"type": "text", "text": "..."}, {"type": "image", ...}]``.
+
+    Yields:
+        A single dict representing the user message.
+    """
+    yield {
+        "type": "user",
+        "message": {"role": "user", "content": content_blocks},
+        "parent_tool_use_id": None,
+        "session_id": "default",
+    }

server/services/dev_server_manager.py

@@ -24,6 +24,7 @@ from typing import Awaitable, Callable, Literal, Set
 import psutil
 
 from registry import list_registered_projects
+from security import extract_commands, get_effective_commands, is_command_allowed
 from server.utils.process_utils import kill_process_tree
 
 logger = logging.getLogger(__name__)
@@ -114,7 +115,8 @@ class DevServerProcessManager:
         self._callbacks_lock = threading.Lock()
 
         # Lock file to prevent multiple instances (stored in project directory)
-        self.lock_file = self.project_dir / ".devserver.lock"
+        from autocoder_paths import get_devserver_lock_path
+        self.lock_file = get_devserver_lock_path(self.project_dir)
 
     @property
     def status(self) -> Literal["stopped", "running", "crashed"]:
@@ -304,6 +306,20 @@ class DevServerProcessManager:
         if not self.project_dir.exists():
             return False, f"Project directory does not exist: {self.project_dir}"
 
+        # Defense-in-depth: validate command against security allowlist
+        commands = extract_commands(command)
+        if not commands:
+            return False, "Could not parse command for security validation"
+
+        allowed_commands, blocked_commands = get_effective_commands(self.project_dir)
+        for cmd in commands:
+            if cmd in blocked_commands:
+                logger.warning("Blocked dev server command '%s' (in blocklist) for %s", cmd, self.project_name)
+                return False, f"Command '{cmd}' is blocked and cannot be used as a dev server command"
+            if not is_command_allowed(cmd, allowed_commands):
+                logger.warning("Rejected dev server command '%s' (not in allowlist) for %s", cmd, self.project_name)
+                return False, f"Command '{cmd}' is not in the allowed commands list"
+
         self._command = command
         self._detected_url = None  # Reset URL detection
 
@@ -487,8 +503,18 @@ def cleanup_orphaned_devserver_locks() -> int:
             if not project_path.exists():
                 continue
 
-            lock_file = project_path / ".devserver.lock"
+            # Check both legacy and new locations for lock files
-            if not lock_file.exists():
+            from autocoder_paths import get_autocoder_dir
+            lock_locations = [
+                project_path / ".devserver.lock",
+                get_autocoder_dir(project_path) / ".devserver.lock",
+            ]
+            lock_file = None
+            for candidate in lock_locations:
+                if candidate.exists():
+                    lock_file = candidate
+                    break
+            if lock_file is None:
                 continue
 
             try:

server/services/expand_chat_session.py

@@ -10,60 +10,41 @@ import asyncio
 import json
 import logging
 import os
-import re
 import shutil
+import sys
 import threading
 import uuid
 from datetime import datetime
 from pathlib import Path
-from typing import AsyncGenerator, Optional
+from typing import Any, AsyncGenerator, Optional
 
 from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient
 from dotenv import load_dotenv
 
 from ..schemas import ImageAttachment
+from .chat_constants import API_ENV_VARS, ROOT_DIR, make_multimodal_message
 
 # Load environment variables from .env file if present
 load_dotenv()
 
 logger = logging.getLogger(__name__)
 
-# Environment variables to pass through to Claude CLI for API configuration
+# Feature MCP tools needed for expand session
-API_ENV_VARS = [
+EXPAND_FEATURE_TOOLS = [
-    "ANTHROPIC_BASE_URL",
+    "mcp__features__feature_create",
-    "ANTHROPIC_AUTH_TOKEN",
+    "mcp__features__feature_create_bulk",
-    "API_TIMEOUT_MS",
+    "mcp__features__feature_get_stats",
-    "ANTHROPIC_DEFAULT_SONNET_MODEL",
-    "ANTHROPIC_DEFAULT_OPUS_MODEL",
-    "ANTHROPIC_DEFAULT_HAIKU_MODEL",
 ]
 
 
-async def _make_multimodal_message(content_blocks: list[dict]) -> AsyncGenerator[dict, None]:
-    """
-    Create an async generator that yields a properly formatted multimodal message.
-    """
-    yield {
-        "type": "user",
-        "message": {"role": "user", "content": content_blocks},
-        "parent_tool_use_id": None,
-        "session_id": "default",
-    }
-
-
-# Root directory of the project
-ROOT_DIR = Path(__file__).parent.parent.parent
-
-
 class ExpandChatSession:
     """
     Manages a project expansion conversation.
 
     Unlike SpecChatSession which writes spec files, this session:
     1. Reads existing app_spec.txt for context
-    2. Parses feature definitions from Claude's output
+    2. Chats with the user to define new features
-    3. Creates features via REST API
+    3. Claude creates features via the feature_create_bulk MCP tool
-    4. Tracks which features were created during the session
     """
 
     def __init__(self, project_name: str, project_dir: Path):
@@ -122,7 +103,8 @@ class ExpandChatSession:
             return
 
         # Verify project has existing spec
-        spec_path = self.project_dir / "prompts" / "app_spec.txt"
+        from autocoder_paths import get_prompts_dir
+        spec_path = get_prompts_dir(self.project_dir) / "app_spec.txt"
         if not spec_path.exists():
             yield {
                 "type": "error",
@@ -145,17 +127,24 @@ class ExpandChatSession:
             return
 
         # Create temporary security settings file (unique per session to avoid conflicts)
+        # Note: permission_mode="bypassPermissions" is safe here because:
+        # 1. Only Read/Glob file tools are allowed (no Write/Edit)
+        # 2. MCP tools are restricted to feature creation only
+        # 3. No Bash access - cannot execute arbitrary commands
         security_settings = {
             "sandbox": {"enabled": True},
             "permissions": {
-                "defaultMode": "acceptEdits",
+                "defaultMode": "bypassPermissions",
                 "allow": [
                     "Read(./**)",
                     "Glob(./**)",
+                    *EXPAND_FEATURE_TOOLS,
                 ],
             },
         }
-        settings_file = self.project_dir / f".claude_settings.expand.{uuid.uuid4().hex}.json"
+        from autocoder_paths import get_expand_settings_path
+        settings_file = get_expand_settings_path(self.project_dir, uuid.uuid4().hex)
+        settings_file.parent.mkdir(parents=True, exist_ok=True)
         self._settings_file = settings_file
         with open(settings_file, "w", encoding="utf-8") as f:
             json.dump(security_settings, f, indent=2)
@@ -165,12 +154,29 @@ class ExpandChatSession:
         system_prompt = skill_content.replace("$ARGUMENTS", project_path)
 
         # Build environment overrides for API configuration
-        sdk_env = {var: os.getenv(var) for var in API_ENV_VARS if os.getenv(var)}
+        # Filter to only include vars that are actually set (non-None)
+        sdk_env: dict[str, str] = {}
+        for var in API_ENV_VARS:
+            value = os.getenv(var)
+            if value:
+                sdk_env[var] = value
 
         # Determine model from environment or use default
         # This allows using alternative APIs (e.g., GLM via z.ai) that may not support Claude model names
         model = os.getenv("ANTHROPIC_DEFAULT_OPUS_MODEL", "claude-opus-4-5-20251101")
 
+        # Build MCP servers config for feature creation
+        mcp_servers = {
+            "features": {
+                "command": sys.executable,
+                "args": ["-m", "mcp_server.feature_mcp"],
+                "env": {
+                    "PROJECT_DIR": str(self.project_dir.resolve()),
+                    "PYTHONPATH": str(ROOT_DIR.resolve()),
+                },
+            },
+        }
+
         # Create Claude SDK client
         try:
             self.client = ClaudeSDKClient(
@@ -181,8 +187,13 @@ class ExpandChatSession:
                     allowed_tools=[
                         "Read",
                         "Glob",
+                        "Grep",
+                        "WebFetch",
+                        "WebSearch",
+                        *EXPAND_FEATURE_TOOLS,
                     ],
-                    permission_mode="acceptEdits",
+                    mcp_servers=mcp_servers,  # type: ignore[arg-type]  # SDK accepts dict config at runtime
+                    permission_mode="bypassPermissions",
                     max_turns=100,
                     cwd=str(self.project_dir.resolve()),
                     settings=str(settings_file.resolve()),
@@ -267,14 +278,15 @@ class ExpandChatSession:
         """
         Internal method to query Claude and stream responses.
 
-        Handles text responses and detects feature creation blocks.
+        Feature creation is handled by Claude calling the feature_create_bulk
+        MCP tool directly -- no text parsing needed.
         """
         if not self.client:
             return
 
         # Build the message content
         if attachments and len(attachments) > 0:
-            content_blocks = []
+            content_blocks: list[dict[str, Any]] = []
             if message:
                 content_blocks.append({"type": "text", "text": message})
             for att in attachments:
@@ -286,14 +298,11 @@ class ExpandChatSession:
                         "data": att.base64Data,
                     }
                 })
-            await self.client.query(_make_multimodal_message(content_blocks))
+            await self.client.query(make_multimodal_message(content_blocks))
             logger.info(f"Sent multimodal message with {len(attachments)} image(s)")
         else:
             await self.client.query(message)
 
-        # Accumulate full response to detect feature blocks
-        full_response = ""
-
         # Stream the response
         async for msg in self.client.receive_response():
             msg_type = type(msg).__name__
@@ -305,7 +314,6 @@ class ExpandChatSession:
                     if block_type == "TextBlock" and hasattr(block, "text"):
                         text = block.text
                         if text:
-                            full_response += text
                             yield {"type": "text", "content": text}
 
                             self.messages.append({
@@ -314,123 +322,6 @@ class ExpandChatSession:
                                 "timestamp": datetime.now().isoformat()
                             })
 
-        # Check for feature creation blocks in full response (handle multiple blocks)
-        features_matches = re.findall(
-            r'<features_to_create>\s*(\[[\s\S]*?\])\s*</features_to_create>',
-            full_response
-        )
-
-        if features_matches:
-            # Collect all features from all blocks, deduplicating by name
-            all_features: list[dict] = []
-            seen_names: set[str] = set()
-
-            for features_json in features_matches:
-                try:
-                    features_data = json.loads(features_json)
-
-                    if features_data and isinstance(features_data, list):
-                        for feature in features_data:
-                            name = feature.get("name", "")
-                            if name and name not in seen_names:
-                                seen_names.add(name)
-                                all_features.append(feature)
-                except json.JSONDecodeError as e:
-                    logger.error(f"Failed to parse features JSON block: {e}")
-                    # Continue processing other blocks
-
-            if all_features:
-                try:
-                    # Create all deduplicated features
-                    created = await self._create_features_bulk(all_features)
-
-                    if created:
-                        self.features_created += len(created)
-                        self.created_feature_ids.extend([f["id"] for f in created])
-
-                        yield {
-                            "type": "features_created",
-                            "count": len(created),
-                            "features": created
-                        }
-
-                        logger.info(f"Created {len(created)} features for {self.project_name}")
-                except Exception:
-                    logger.exception("Failed to create features")
-                    yield {
-                        "type": "error",
-                        "content": "Failed to create features"
-                    }
-
-    async def _create_features_bulk(self, features: list[dict]) -> list[dict]:
-        """
-        Create features directly in the database.
-
-        Args:
-            features: List of feature dictionaries with category, name, description, steps
-
-        Returns:
-            List of created feature dictionaries with IDs
-
-        Note:
-            Uses flush() to get IDs immediately without re-querying by priority range,
-            which could pick up rows from concurrent writers.
-        """
-        # Import database classes
-        import sys
-        root = Path(__file__).parent.parent.parent
-        if str(root) not in sys.path:
-            sys.path.insert(0, str(root))
-
-        from api.database import Feature, create_database
-
-        # Get database session
-        _, SessionLocal = create_database(self.project_dir)
-        session = SessionLocal()
-
-        try:
-            # Determine starting priority
-            max_priority_feature = session.query(Feature).order_by(Feature.priority.desc()).first()
-            current_priority = (max_priority_feature.priority + 1) if max_priority_feature else 1
-
-            created_rows: list = []
-
-            for f in features:
-                db_feature = Feature(
-                    priority=current_priority,
-                    category=f.get("category", "functional"),
-                    name=f.get("name", "Unnamed feature"),
-                    description=f.get("description", ""),
-                    steps=f.get("steps", []),
-                    passes=False,
-                    in_progress=False,
-                )
-                session.add(db_feature)
-                created_rows.append(db_feature)
-                current_priority += 1
-
-            # Flush to get IDs without relying on priority range query
-            session.flush()
-
-            # Build result from the flushed objects (IDs are now populated)
-            created_features = [
-                {
-                    "id": db_feature.id,
-                    "name": db_feature.name,
-                    "category": db_feature.category,
-                }
-                for db_feature in created_rows
-            ]
-
-            session.commit()
-            return created_features
-
-        except Exception:
-            session.rollback()
-            raise
-        finally:
-            session.close()
-
     def get_features_created(self) -> int:
         """Get the total number of features created in this session."""
         return self.features_created

server/services/process_manager.py

@@ -15,7 +15,7 @@ import sys
 import threading
 from datetime import datetime
 from pathlib import Path
-from typing import Awaitable, Callable, Literal, Set
+from typing import Any, Awaitable, Callable, Literal, Set
 
 import psutil
 
@@ -92,7 +92,8 @@ class AgentProcessManager:
         self._callbacks_lock = threading.Lock()
 
         # Lock file to prevent multiple instances (stored in project directory)
-        self.lock_file = self.project_dir / ".agent.lock"
+        from autocoder_paths import get_agent_lock_path
+        self.lock_file = get_agent_lock_path(self.project_dir)
 
     @property
     def status(self) -> Literal["stopped", "running", "paused", "crashed"]:
@@ -296,6 +297,8 @@ class AgentProcessManager:
         parallel_mode: bool = False,
         max_concurrency: int | None = None,
         testing_agent_ratio: int = 1,
+        playwright_headless: bool = True,
+        batch_size: int = 3,
     ) -> tuple[bool, str]:
         """
         Start the agent as a subprocess.
@@ -306,6 +309,7 @@ class AgentProcessManager:
             parallel_mode: DEPRECATED - ignored, always uses unified orchestrator
             max_concurrency: Max concurrent coding agents (1-5, default 1)
             testing_agent_ratio: Number of regression testing agents (0-3, default 1)
+            playwright_headless: If True, run browser in headless mode
 
         Returns:
             Tuple of (success, message)
@@ -346,17 +350,26 @@ class AgentProcessManager:
         # Add testing agent configuration
         cmd.extend(["--testing-ratio", str(testing_agent_ratio)])
 
+        # Add --batch-size flag for multi-feature batching
+        cmd.extend(["--batch-size", str(batch_size)])
+
         try:
             # Start subprocess with piped stdout/stderr
             # Use project_dir as cwd so Claude SDK sandbox allows access to project files
-            # IMPORTANT: Set PYTHONUNBUFFERED to ensure output isn't delayed
+            # stdin=DEVNULL prevents blocking if Claude CLI or child process tries to read stdin
-            self.process = subprocess.Popen(
+            # CREATE_NO_WINDOW on Windows prevents console window pop-ups
-                cmd,
+            # PYTHONUNBUFFERED ensures output isn't delayed
-                stdout=subprocess.PIPE,
+            popen_kwargs: dict[str, Any] = {
-                stderr=subprocess.STDOUT,
+                "stdin": subprocess.DEVNULL,
-                cwd=str(self.project_dir),
+                "stdout": subprocess.PIPE,
-                env={**os.environ, "PYTHONUNBUFFERED": "1"},
+                "stderr": subprocess.STDOUT,
-            )
+                "cwd": str(self.project_dir),
+                "env": {**os.environ, "PYTHONUNBUFFERED": "1", "PLAYWRIGHT_HEADLESS": "true" if playwright_headless else "false"},
+            }
+            if sys.platform == "win32":
+                popen_kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW
+
+            self.process = subprocess.Popen(cmd, **popen_kwargs)
 
             # Atomic lock creation - if it fails, another process beat us
             if not self._create_lock():
@@ -573,8 +586,18 @@ def cleanup_orphaned_locks() -> int:
             if not project_path.exists():
                 continue
 
-            lock_file = project_path / ".agent.lock"
+            # Check both legacy and new locations for lock files
-            if not lock_file.exists():
+            from autocoder_paths import get_autocoder_dir
+            lock_locations = [
+                project_path / ".agent.lock",
+                get_autocoder_dir(project_path) / ".agent.lock",
+            ]
+            lock_file = None
+            for candidate in lock_locations:
+                if candidate.exists():
+                    lock_file = candidate
+                    break
+            if lock_file is None:
                 continue
 
             try:

server/services/scheduler_service.py

@@ -92,8 +92,9 @@ class SchedulerService:
     async def _load_project_schedules(self, project_name: str, project_dir: Path) -> int:
         """Load schedules for a single project. Returns count of schedules loaded."""
         from api.database import Schedule, create_database
+        from autocoder_paths import get_features_db_path
 
-        db_path = project_dir / "features.db"
+        db_path = get_features_db_path(project_dir)
         if not db_path.exists():
             return 0
 
@@ -567,8 +568,9 @@ class SchedulerService:
     ):
         """Check if a project should be started on server startup."""
         from api.database import Schedule, ScheduleOverride, create_database
+        from autocoder_paths import get_features_db_path
 
-        db_path = project_dir / "features.db"
+        db_path = get_features_db_path(project_dir)
         if not db_path.exists():
             return
 

server/services/spec_chat_session.py

@@ -13,49 +13,19 @@ import shutil
 import threading
 from datetime import datetime
 from pathlib import Path
-from typing import AsyncGenerator, Optional
+from typing import Any, AsyncGenerator, Optional
 
 from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient
 from dotenv import load_dotenv
 
 from ..schemas import ImageAttachment
+from .chat_constants import API_ENV_VARS, ROOT_DIR, make_multimodal_message
 
 # Load environment variables from .env file if present
 load_dotenv()
 
 logger = logging.getLogger(__name__)
 
-# Environment variables to pass through to Claude CLI for API configuration
-API_ENV_VARS = [
-    "ANTHROPIC_BASE_URL",
-    "ANTHROPIC_AUTH_TOKEN",
-    "API_TIMEOUT_MS",
-    "ANTHROPIC_DEFAULT_SONNET_MODEL",
-    "ANTHROPIC_DEFAULT_OPUS_MODEL",
-    "ANTHROPIC_DEFAULT_HAIKU_MODEL",
-]
-
-
-async def _make_multimodal_message(content_blocks: list[dict]) -> AsyncGenerator[dict, None]:
-    """
-    Create an async generator that yields a properly formatted multimodal message.
-
-    The Claude Agent SDK's query() method accepts either:
-    - A string (simple text)
-    - An AsyncIterable[dict] (for custom message formats)
-
-    This function wraps content blocks in the expected message format.
-    """
-    yield {
-        "type": "user",
-        "message": {"role": "user", "content": content_blocks},
-        "parent_tool_use_id": None,
-        "session_id": "default",
-    }
-
-# Root directory of the project
-ROOT_DIR = Path(__file__).parent.parent.parent
-
 
 class SpecChatSession:
     """
@@ -125,7 +95,8 @@ class SpecChatSession:
         # Delete app_spec.txt so Claude can create it fresh
         # The SDK requires reading existing files before writing, but app_spec.txt is created new
         # Note: We keep initializer_prompt.md so Claude can read and update the template
-        prompts_dir = self.project_dir / "prompts"
+        from autocoder_paths import get_prompts_dir
+        prompts_dir = get_prompts_dir(self.project_dir)
         app_spec_path = prompts_dir / "app_spec.txt"
         if app_spec_path.exists():
             app_spec_path.unlink()
@@ -145,7 +116,9 @@ class SpecChatSession:
                 ],
             },
         }
-        settings_file = self.project_dir / ".claude_settings.json"
+        from autocoder_paths import get_claude_settings_path
+        settings_file = get_claude_settings_path(self.project_dir)
+        settings_file.parent.mkdir(parents=True, exist_ok=True)
         with open(settings_file, "w") as f:
             json.dump(security_settings, f, indent=2)
 
@@ -167,7 +140,12 @@ class SpecChatSession:
         system_cli = shutil.which("claude")
 
         # Build environment overrides for API configuration
-        sdk_env = {var: os.getenv(var) for var in API_ENV_VARS if os.getenv(var)}
+        # Filter to only include vars that are actually set (non-None)
+        sdk_env: dict[str, str] = {}
+        for var in API_ENV_VARS:
+            value = os.getenv(var)
+            if value:
+                sdk_env[var] = value
 
         # Determine model from environment or use default
         # This allows using alternative APIs (e.g., GLM via z.ai) that may not support Claude model names
@@ -289,7 +267,7 @@ class SpecChatSession:
         # Build the message content
         if attachments and len(attachments) > 0:
             # Multimodal message: build content blocks array
-            content_blocks = []
+            content_blocks: list[dict[str, Any]] = []
 
             # Add text block if there's text
             if message:
@@ -308,7 +286,7 @@ class SpecChatSession:
 
             # Send multimodal content to Claude using async generator format
             # The SDK's query() accepts AsyncIterable[dict] for custom message formats
-            await self.client.query(_make_multimodal_message(content_blocks))
+            await self.client.query(make_multimodal_message(content_blocks))
             logger.info(f"Sent multimodal message with {len(attachments)} image(s)")
         else:
             # Text-only message: use string format
@@ -317,7 +295,7 @@ class SpecChatSession:
         current_text = ""
 
         # Track pending writes for BOTH required files
-        pending_writes = {
+        pending_writes: dict[str, dict[str, Any] | None] = {
             "app_spec": None,      # {"tool_id": ..., "path": ...}
             "initializer": None,   # {"tool_id": ..., "path": ...}
         }
@@ -392,7 +370,8 @@ class SpecChatSession:
                             logger.warning(f"Tool error: {content}")
                             # Clear any pending writes that failed
                             for key in pending_writes:
-                                if pending_writes[key] and tool_use_id == pending_writes[key].get("tool_id"):
+                                pending_write = pending_writes[key]
+                                if pending_write is not None and tool_use_id == pending_write.get("tool_id"):
                                     logger.error(f"{key} write failed: {content}")
                                     pending_writes[key] = None
                         else:

server/services/terminal_manager.py

@@ -371,7 +371,7 @@ class TerminalSession:
             # Reap zombie if not already reaped
             if self._child_pid is not None:
                 try:
-                    os.waitpid(self._child_pid, os.WNOHANG)
+                    os.waitpid(self._child_pid, os.WNOHANG)  # type: ignore[attr-defined]  # Unix-only method, guarded by runtime platform selection
                 except ChildProcessError:
                     pass
                 except Exception:
@@ -736,7 +736,7 @@ async def cleanup_all_terminals() -> None:
     Called on server shutdown to ensure all PTY processes are terminated.
     """
     with _sessions_lock:
-        all_sessions = []
+        all_sessions: list[TerminalSession] = []
         for project_sessions in _sessions.values():
             all_sessions.extend(project_sessions.values())
 

server/utils/project_helpers.py

@@ -0,0 +1,32 @@
+"""
+Project Helper Utilities
+========================
+
+Shared project path lookup used across all server routers and websocket handlers.
+Consolidates the previously duplicated _get_project_path() function.
+"""
+
+import sys
+from pathlib import Path
+
+# Ensure the project root is on sys.path so `registry` can be imported.
+# This is necessary because `registry.py` lives at the repository root,
+# outside the `server` package.
+_root = Path(__file__).parent.parent.parent
+if str(_root) not in sys.path:
+    sys.path.insert(0, str(_root))
+
+from registry import get_project_path as _registry_get_project_path
+
+
+def get_project_path(project_name: str) -> Path | None:
+    """Look up a project's filesystem path from the global registry.
+
+    Args:
+        project_name: The registered name of the project.
+
+    Returns:
+        The resolved ``Path`` to the project directory, or ``None`` if the
+        project is not found in the registry.
+    """
+    return _registry_get_project_path(project_name)

server/utils/validation.py

@@ -1,26 +1,52 @@
 """
-Shared validation utilities for the server.
+Shared Validation Utilities
+============================
+
+Project name validation used across REST endpoints and WebSocket handlers.
+Two variants are provided:
+
+* ``is_valid_project_name`` -- returns ``bool``, suitable for WebSocket
+  handlers where raising an HTTPException is not appropriate.
+* ``validate_project_name`` -- raises ``HTTPException(400)`` on failure,
+  suitable for REST endpoint handlers.
 """
 
 import re
 
 from fastapi import HTTPException
 
+# Compiled once; reused by both variants.
+_PROJECT_NAME_RE = re.compile(r'^[a-zA-Z0-9_-]{1,50}$')
+
+
+def is_valid_project_name(name: str) -> bool:
+    """Check whether *name* is a valid project name.
+
+    Allows only ASCII letters, digits, hyphens, and underscores (1-50 chars).
+    Returns ``True`` if valid, ``False`` otherwise.
+
+    Use this in WebSocket handlers where you need to close the socket
+    yourself rather than raise an HTTP error.
+    """
+    return bool(_PROJECT_NAME_RE.match(name))
+
 
 def validate_project_name(name: str) -> str:
-    """
+    """Validate and return *name*, or raise ``HTTPException(400)``.
-    Validate and sanitize project name to prevent path traversal.
+
+    Suitable for REST endpoint handlers where FastAPI will convert the
+    exception into an HTTP 400 response automatically.
 
     Args:
-        name: Project name to validate
+        name: Project name to validate.
 
     Returns:
-        The validated project name
+        The validated project name (unchanged).
 
     Raises:
-        HTTPException: If name is invalid
+        HTTPException: If *name* is invalid.
     """
-    if not re.match(r'^[a-zA-Z0-9_-]{1,50}$', name):
+    if not _PROJECT_NAME_RE.match(name):
         raise HTTPException(
             status_code=400,
             detail="Invalid project name. Use only letters, numbers, hyphens, and underscores (1-50 chars)."

server/websocket.py

@@ -16,8 +16,11 @@ from typing import Set
 from fastapi import WebSocket, WebSocketDisconnect
 
 from .schemas import AGENT_MASCOTS
+from .services.chat_constants import ROOT_DIR
 from .services.dev_server_manager import get_devserver_manager
 from .services.process_manager import get_manager
+from .utils.project_helpers import get_project_path as _get_project_path
+from .utils.validation import is_valid_project_name as validate_project_name
 
 # Lazy imports
 _count_passing_tests = None
@@ -36,6 +39,14 @@ TESTING_AGENT_START_PATTERN = re.compile(r'Started testing agent for feature #(\
 # Matches: "Feature #123 testing completed" or "Feature #123 testing failed"
 TESTING_AGENT_COMPLETE_PATTERN = re.compile(r'Feature #(\d+) testing (completed|failed)')
 
+# Pattern to detect batch coding agent start message
+# Matches: "Started coding agent for features #5, #8, #12"
+BATCH_CODING_AGENT_START_PATTERN = re.compile(r'Started coding agent for features (#\d+(?:,\s*#\d+)*)')
+
+# Pattern to detect batch completion
+# Matches: "Features #5, #8, #12 completed" or "Features #5, #8, #12 failed"
+BATCH_FEATURES_COMPLETE_PATTERN = re.compile(r'Features (#\d+(?:,\s*#\d+)*)\s+(completed|failed)')
+
 # Patterns for detecting agent activity and thoughts
 THOUGHT_PATTERNS = [
     # Claude's tool usage patterns (actual format: [Tool: name])
@@ -61,9 +72,9 @@ ORCHESTRATOR_PATTERNS = {
     'capacity_check': re.compile(r'\[DEBUG\] Spawning loop: (\d+) ready, (\d+) slots'),
     'at_capacity': re.compile(r'At max capacity|at max testing agents|At max total agents'),
     'feature_start': re.compile(r'Starting feature \d+/\d+: #(\d+) - (.+)'),
-    'coding_spawn': re.compile(r'Started coding agent for feature #(\d+)'),
+    'coding_spawn': re.compile(r'Started coding agent for features? #(\d+)'),
     'testing_spawn': re.compile(r'Started testing agent for feature #(\d+)'),
-    'coding_complete': re.compile(r'Feature #(\d+) (completed|failed)'),
+    'coding_complete': re.compile(r'Features? #(\d+)(?:,\s*#\d+)* (completed|failed)'),
     'testing_complete': re.compile(r'Feature #(\d+) testing (completed|failed)'),
     'all_complete': re.compile(r'All features complete'),
     'blocked_features': re.compile(r'(\d+) blocked by dependencies'),
@@ -93,14 +104,26 @@ class AgentTracker:
         # Check for orchestrator status messages first
         # These don't have [Feature #X] prefix
 
-        # Coding agent start: "Started coding agent for feature #X"
+        # Batch coding agent start: "Started coding agent for features #5, #8, #12"
-        if line.startswith("Started coding agent for feature #"):
+        batch_start_match = BATCH_CODING_AGENT_START_PATTERN.match(line)
+        if batch_start_match:
             try:
-                feature_id = int(re.search(r'#(\d+)', line).group(1))
+                feature_ids = [int(x.strip().lstrip('#')) for x in batch_start_match.group(1).split(',')]
-                return await self._handle_agent_start(feature_id, line, agent_type="coding")
+                if feature_ids:
-            except (AttributeError, ValueError):
+                    return await self._handle_batch_agent_start(feature_ids, "coding")
+            except ValueError:
                 pass
 
+        # Single coding agent start: "Started coding agent for feature #X"
+        if line.startswith("Started coding agent for feature #"):
+            m = re.search(r'#(\d+)', line)
+            if m:
+                try:
+                    feature_id = int(m.group(1))
+                    return await self._handle_agent_start(feature_id, line, agent_type="coding")
+                except ValueError:
+                    pass
+
         # Testing agent start: "Started testing agent for feature #X (PID xxx)"
         testing_start_match = TESTING_AGENT_START_PATTERN.match(line)
         if testing_start_match:
@@ -114,14 +137,27 @@ class AgentTracker:
             is_success = testing_complete_match.group(2) == "completed"
             return await self._handle_agent_complete(feature_id, is_success, agent_type="testing")
 
+        # Batch features complete: "Features #5, #8, #12 completed/failed"
+        batch_complete_match = BATCH_FEATURES_COMPLETE_PATTERN.match(line)
+        if batch_complete_match:
+            try:
+                feature_ids = [int(x.strip().lstrip('#')) for x in batch_complete_match.group(1).split(',')]
+                is_success = batch_complete_match.group(2) == "completed"
+                if feature_ids:
+                    return await self._handle_batch_agent_complete(feature_ids, is_success, "coding")
+            except ValueError:
+                pass
+
         # Coding agent complete: "Feature #X completed/failed" (without "testing" keyword)
         if line.startswith("Feature #") and ("completed" in line or "failed" in line) and "testing" not in line:
-            try:
+            m = re.search(r'#(\d+)', line)
-                feature_id = int(re.search(r'#(\d+)', line).group(1))
+            if m:
-                is_success = "completed" in line
+                try:
-                return await self._handle_agent_complete(feature_id, is_success, agent_type="coding")
+                    feature_id = int(m.group(1))
-            except (AttributeError, ValueError):
+                    is_success = "completed" in line
-                pass
+                    return await self._handle_agent_complete(feature_id, is_success, agent_type="coding")
+                except ValueError:
+                    pass
 
         # Check for feature-specific output lines: [Feature #X] content
         # Both coding and testing agents use this format now
@@ -151,6 +187,7 @@ class AgentTracker:
                     'name': AGENT_MASCOTS[agent_index % len(AGENT_MASCOTS)],
                     'agent_index': agent_index,
                     'agent_type': 'coding',
+                    'feature_ids': [feature_id],
                     'state': 'thinking',
                     'feature_name': f'Feature #{feature_id}',
                     'last_thought': None,
@@ -158,6 +195,10 @@ class AgentTracker:
 
             agent = self.active_agents[key]
 
+            # Update current_feature_id for batch agents when output comes from a different feature
+            if 'current_feature_id' in agent and feature_id in agent.get('feature_ids', []):
+                agent['current_feature_id'] = feature_id
+
             # Detect state and thought from content
             state = 'working'
             thought = None
@@ -181,6 +222,7 @@ class AgentTracker:
                     'agentName': agent['name'],
                     'agentType': agent['agent_type'],
                     'featureId': feature_id,
+                    'featureIds': agent.get('feature_ids', [feature_id]),
                     'featureName': agent['feature_name'],
                     'state': state,
                     'thought': thought,
@@ -237,6 +279,7 @@ class AgentTracker:
                 'name': AGENT_MASCOTS[agent_index % len(AGENT_MASCOTS)],
                 'agent_index': agent_index,
                 'agent_type': agent_type,
+                'feature_ids': [feature_id],
                 'state': 'thinking',
                 'feature_name': feature_name,
                 'last_thought': 'Starting work...',
@@ -248,12 +291,55 @@ class AgentTracker:
                 'agentName': AGENT_MASCOTS[agent_index % len(AGENT_MASCOTS)],
                 'agentType': agent_type,
                 'featureId': feature_id,
+                'featureIds': [feature_id],
                 'featureName': feature_name,
                 'state': 'thinking',
                 'thought': 'Starting work...',
                 'timestamp': datetime.now().isoformat(),
             }
 
+    async def _handle_batch_agent_start(self, feature_ids: list[int], agent_type: str = "coding") -> dict | None:
+        """Handle batch agent start message from orchestrator."""
+        if not feature_ids:
+            return None
+        primary_id = feature_ids[0]
+        async with self._lock:
+            key = (primary_id, agent_type)
+            agent_index = self._next_agent_index
+            self._next_agent_index += 1
+
+            feature_name = f'Features {", ".join(f"#{fid}" for fid in feature_ids)}'
+
+            self.active_agents[key] = {
+                'name': AGENT_MASCOTS[agent_index % len(AGENT_MASCOTS)],
+                'agent_index': agent_index,
+                'agent_type': agent_type,
+                'feature_ids': list(feature_ids),
+                'current_feature_id': primary_id,
+                'state': 'thinking',
+                'feature_name': feature_name,
+                'last_thought': 'Starting batch work...',
+            }
+
+            # Register all feature IDs so output lines can find this agent
+            for fid in feature_ids:
+                secondary_key = (fid, agent_type)
+                if secondary_key != key:
+                    self.active_agents[secondary_key] = self.active_agents[key]
+
+            return {
+                'type': 'agent_update',
+                'agentIndex': agent_index,
+                'agentName': AGENT_MASCOTS[agent_index % len(AGENT_MASCOTS)],
+                'agentType': agent_type,
+                'featureId': primary_id,
+                'featureIds': list(feature_ids),
+                'featureName': feature_name,
+                'state': 'thinking',
+                'thought': 'Starting batch work...',
+                'timestamp': datetime.now().isoformat(),
+            }
+
     async def _handle_agent_complete(self, feature_id: int, is_success: bool, agent_type: str = "coding") -> dict | None:
         """Handle agent completion - ALWAYS emits a message, even if agent wasn't tracked.
 
@@ -275,6 +361,7 @@ class AgentTracker:
                     'agentName': agent['name'],
                     'agentType': agent.get('agent_type', agent_type),
                     'featureId': feature_id,
+                    'featureIds': agent.get('feature_ids', [feature_id]),
                     'featureName': agent['feature_name'],
                     'state': state,
                     'thought': 'Completed successfully!' if is_success else 'Failed to complete',
@@ -291,6 +378,7 @@ class AgentTracker:
                     'agentName': 'Unknown',
                     'agentType': agent_type,
                     'featureId': feature_id,
+                    'featureIds': [feature_id],
                     'featureName': f'Feature #{feature_id}',
                     'state': state,
                     'thought': 'Completed successfully!' if is_success else 'Failed to complete',
@@ -298,6 +386,49 @@ class AgentTracker:
                     'synthetic': True,
                 }
 
+    async def _handle_batch_agent_complete(self, feature_ids: list[int], is_success: bool, agent_type: str = "coding") -> dict | None:
+        """Handle batch agent completion."""
+        if not feature_ids:
+            return None
+        primary_id = feature_ids[0]
+        async with self._lock:
+            state = 'success' if is_success else 'error'
+            key = (primary_id, agent_type)
+
+            if key in self.active_agents:
+                agent = self.active_agents[key]
+                result = {
+                    'type': 'agent_update',
+                    'agentIndex': agent['agent_index'],
+                    'agentName': agent['name'],
+                    'agentType': agent.get('agent_type', agent_type),
+                    'featureId': primary_id,
+                    'featureIds': agent.get('feature_ids', list(feature_ids)),
+                    'featureName': agent['feature_name'],
+                    'state': state,
+                    'thought': 'Batch completed successfully!' if is_success else 'Batch failed to complete',
+                    'timestamp': datetime.now().isoformat(),
+                }
+                # Clean up all keys for this batch
+                for fid in feature_ids:
+                    self.active_agents.pop((fid, agent_type), None)
+                return result
+            else:
+                # Synthetic completion
+                return {
+                    'type': 'agent_update',
+                    'agentIndex': -1,
+                    'agentName': 'Unknown',
+                    'agentType': agent_type,
+                    'featureId': primary_id,
+                    'featureIds': list(feature_ids),
+                    'featureName': f'Features {", ".join(f"#{fid}" for fid in feature_ids)}',
+                    'state': state,
+                    'thought': 'Batch completed successfully!' if is_success else 'Batch failed to complete',
+                    'timestamp': datetime.now().isoformat(),
+                    'synthetic': True,
+                }
+
 
 class OrchestratorTracker:
     """Tracks orchestrator state for Mission Control observability.
@@ -444,7 +575,7 @@ class OrchestratorTracker:
         timestamp = datetime.now().isoformat()
 
         # Add to recent events (keep last 5)
-        event = {
+        event: dict[str, str | int] = {
             'eventType': event_type,
             'message': message,
             'timestamp': timestamp,
@@ -487,17 +618,6 @@ class OrchestratorTracker:
             self.recent_events.clear()
 
 
-def _get_project_path(project_name: str) -> Path:
-    """Get project path from registry."""
-    import sys
-    root = Path(__file__).parent.parent
-    if str(root) not in sys.path:
-        sys.path.insert(0, str(root))
-
-    from registry import get_project_path
-    return get_project_path(project_name)
-
-
 def _get_count_passing_tests():
     """Lazy import of count_passing_tests."""
     global _count_passing_tests
@@ -564,15 +684,6 @@ class ConnectionManager:
 # Global connection manager
 manager = ConnectionManager()
 
-# Root directory
-ROOT_DIR = Path(__file__).parent.parent
-
-
-def validate_project_name(name: str) -> bool:
-    """Validate project name to prevent path traversal."""
-    return bool(re.match(r'^[a-zA-Z0-9_-]{1,50}$', name))
-
-
 async def poll_progress(websocket: WebSocket, project_name: str, project_dir: Path):
     """Poll database for progress changes and send updates."""
     count_passing_tests = _get_count_passing_tests()
@@ -652,7 +763,7 @@ async def project_websocket(websocket: WebSocket, project_name: str):
                 agent_index, _ = await agent_tracker.get_agent_info(feature_id)
 
             # Send the raw log line with optional feature/agent attribution
-            log_msg = {
+            log_msg: dict[str, str | int] = {
                 "type": "log",
                 "line": line,
                 "timestamp": datetime.now().isoformat(),

start_ui.bat

@@ -39,5 +39,3 @@ pip install -r requirements.txt --quiet
 
 REM Run the Python launcher
 python "%~dp0start_ui.py" %*
-
-pause

start_ui.py

@@ -137,10 +137,25 @@ def check_node() -> bool:
 
 
 def install_npm_deps() -> bool:
-    """Install npm dependencies if node_modules doesn't exist."""
+    """Install npm dependencies if node_modules doesn't exist or is stale."""
     node_modules = UI_DIR / "node_modules"
+    package_json = UI_DIR / "package.json"
+    package_lock = UI_DIR / "package-lock.json"
 
-    if node_modules.exists():
+    # Check if npm install is needed
+    needs_install = False
+
+    if not node_modules.exists():
+        needs_install = True
+    elif package_json.exists():
+        # If package.json or package-lock.json is newer than node_modules, reinstall
+        node_modules_mtime = node_modules.stat().st_mtime
+        if package_json.stat().st_mtime > node_modules_mtime:
+            needs_install = True
+        elif package_lock.exists() and package_lock.stat().st_mtime > node_modules_mtime:
+            needs_install = True
+
+    if not needs_install:
         print("  npm dependencies already installed")
         return True
 
@@ -187,7 +202,7 @@ def build_frontend() -> bool:
         trigger_file = "dist/ directory missing"
     elif src_dir.exists():
         # Find the newest file in dist/ directory
-        newest_dist_mtime = 0
+        newest_dist_mtime: float = 0
         for dist_file in dist_dir.rglob("*"):
             try:
                 if dist_file.is_file():

test_client.py

@@ -0,0 +1,265 @@
+#!/usr/bin/env python3
+"""
+Client Utility Tests
+====================
+
+Tests for the client module utility functions.
+Run with: python test_client.py
+"""
+
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+from client import (
+    EXTRA_READ_PATHS_BLOCKLIST,
+    EXTRA_READ_PATHS_VAR,
+    convert_model_for_vertex,
+    get_extra_read_paths,
+)
+
+
+class TestConvertModelForVertex(unittest.TestCase):
+    """Tests for convert_model_for_vertex function."""
+
+    def setUp(self):
+        """Save original env state."""
+        self._orig_vertex = os.environ.get("CLAUDE_CODE_USE_VERTEX")
+
+    def tearDown(self):
+        """Restore original env state."""
+        if self._orig_vertex is None:
+            os.environ.pop("CLAUDE_CODE_USE_VERTEX", None)
+        else:
+            os.environ["CLAUDE_CODE_USE_VERTEX"] = self._orig_vertex
+
+    # --- Vertex AI disabled (default) ---
+
+    def test_returns_model_unchanged_when_vertex_disabled(self):
+        os.environ.pop("CLAUDE_CODE_USE_VERTEX", None)
+        self.assertEqual(
+            convert_model_for_vertex("claude-opus-4-5-20251101"),
+            "claude-opus-4-5-20251101",
+        )
+
+    def test_returns_model_unchanged_when_vertex_set_to_zero(self):
+        os.environ["CLAUDE_CODE_USE_VERTEX"] = "0"
+        self.assertEqual(
+            convert_model_for_vertex("claude-opus-4-5-20251101"),
+            "claude-opus-4-5-20251101",
+        )
+
+    def test_returns_model_unchanged_when_vertex_set_to_empty(self):
+        os.environ["CLAUDE_CODE_USE_VERTEX"] = ""
+        self.assertEqual(
+            convert_model_for_vertex("claude-sonnet-4-5-20250929"),
+            "claude-sonnet-4-5-20250929",
+        )
+
+    # --- Vertex AI enabled: standard conversions ---
+
+    def test_converts_opus_model(self):
+        os.environ["CLAUDE_CODE_USE_VERTEX"] = "1"
+        self.assertEqual(
+            convert_model_for_vertex("claude-opus-4-5-20251101"),
+            "claude-opus-4-5@20251101",
+        )
+
+    def test_converts_sonnet_model(self):
+        os.environ["CLAUDE_CODE_USE_VERTEX"] = "1"
+        self.assertEqual(
+            convert_model_for_vertex("claude-sonnet-4-5-20250929"),
+            "claude-sonnet-4-5@20250929",
+        )
+
+    def test_converts_haiku_model(self):
+        os.environ["CLAUDE_CODE_USE_VERTEX"] = "1"
+        self.assertEqual(
+            convert_model_for_vertex("claude-3-5-haiku-20241022"),
+            "claude-3-5-haiku@20241022",
+        )
+
+    # --- Vertex AI enabled: already converted or non-matching ---
+
+    def test_already_vertex_format_unchanged(self):
+        os.environ["CLAUDE_CODE_USE_VERTEX"] = "1"
+        self.assertEqual(
+            convert_model_for_vertex("claude-opus-4-5@20251101"),
+            "claude-opus-4-5@20251101",
+        )
+
+    def test_non_claude_model_unchanged(self):
+        os.environ["CLAUDE_CODE_USE_VERTEX"] = "1"
+        self.assertEqual(
+            convert_model_for_vertex("gpt-4o"),
+            "gpt-4o",
+        )
+
+    def test_model_without_date_suffix_unchanged(self):
+        os.environ["CLAUDE_CODE_USE_VERTEX"] = "1"
+        self.assertEqual(
+            convert_model_for_vertex("claude-opus-4-5"),
+            "claude-opus-4-5",
+        )
+
+    def test_empty_string_unchanged(self):
+        os.environ["CLAUDE_CODE_USE_VERTEX"] = "1"
+        self.assertEqual(convert_model_for_vertex(""), "")
+
+
+class TestExtraReadPathsBlocklist(unittest.TestCase):
+    """Tests for EXTRA_READ_PATHS sensitive directory blocking in get_extra_read_paths()."""
+
+    def setUp(self):
+        """Save original environment and home directory state."""
+        self._orig_extra_read = os.environ.get(EXTRA_READ_PATHS_VAR)
+        self._orig_home = os.environ.get("HOME")
+        self._orig_userprofile = os.environ.get("USERPROFILE")
+        self._orig_homedrive = os.environ.get("HOMEDRIVE")
+        self._orig_homepath = os.environ.get("HOMEPATH")
+
+    def tearDown(self):
+        """Restore original environment state."""
+        restore_map = {
+            EXTRA_READ_PATHS_VAR: self._orig_extra_read,
+            "HOME": self._orig_home,
+            "USERPROFILE": self._orig_userprofile,
+            "HOMEDRIVE": self._orig_homedrive,
+            "HOMEPATH": self._orig_homepath,
+        }
+        for key, value in restore_map.items():
+            if value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = value
+
+    def _set_home(self, home_path: str):
+        """Set the home directory for both Unix and Windows."""
+        os.environ["HOME"] = home_path
+        if sys.platform == "win32":
+            os.environ["USERPROFILE"] = home_path
+            drive, path = os.path.splitdrive(home_path)
+            if drive:
+                os.environ["HOMEDRIVE"] = drive
+                os.environ["HOMEPATH"] = path
+
+    def test_sensitive_directory_is_blocked(self):
+        """Path that IS a sensitive directory (e.g., ~/.ssh) should be blocked."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            self._set_home(tmpdir)
+            # Create the sensitive directory so it exists
+            ssh_dir = Path(tmpdir) / ".ssh"
+            ssh_dir.mkdir()
+
+            os.environ[EXTRA_READ_PATHS_VAR] = str(ssh_dir)
+            result = get_extra_read_paths()
+            self.assertEqual(result, [], "Path that IS ~/.ssh should be blocked")
+
+    def test_path_inside_sensitive_directory_is_blocked(self):
+        """Path INSIDE a sensitive directory (e.g., ~/.ssh/keys) should be blocked."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            self._set_home(tmpdir)
+            ssh_dir = Path(tmpdir) / ".ssh"
+            keys_dir = ssh_dir / "keys"
+            keys_dir.mkdir(parents=True)
+
+            os.environ[EXTRA_READ_PATHS_VAR] = str(keys_dir)
+            result = get_extra_read_paths()
+            self.assertEqual(result, [], "Path inside ~/.ssh should be blocked")
+
+    def test_path_containing_sensitive_directory_is_blocked(self):
+        """Path that contains a sensitive directory inside it should be blocked.
+
+        For example, if the extra read path is the user's home directory, and
+        ~/.ssh exists inside it, the path should be blocked because granting
+        read access to the parent would expose the sensitive subdirectory.
+        """
+        with tempfile.TemporaryDirectory() as tmpdir:
+            self._set_home(tmpdir)
+            # Create a sensitive dir inside the home so it triggers the
+            # "sensitive dir is inside the requested path" check
+            ssh_dir = Path(tmpdir) / ".ssh"
+            ssh_dir.mkdir()
+
+            os.environ[EXTRA_READ_PATHS_VAR] = tmpdir
+            result = get_extra_read_paths()
+            self.assertEqual(result, [], "Home dir containing .ssh should be blocked")
+
+    def test_valid_non_sensitive_path_is_allowed(self):
+        """A valid directory that is NOT sensitive should be allowed."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            self._set_home(tmpdir)
+            # Create a non-sensitive directory under home
+            docs_dir = Path(tmpdir) / "Documents" / "myproject"
+            docs_dir.mkdir(parents=True)
+
+            os.environ[EXTRA_READ_PATHS_VAR] = str(docs_dir)
+            result = get_extra_read_paths()
+            self.assertEqual(len(result), 1, "Non-sensitive path should be allowed")
+            self.assertEqual(result[0], docs_dir.resolve())
+
+    def test_all_blocklist_entries_are_checked(self):
+        """Every directory in EXTRA_READ_PATHS_BLOCKLIST should actually be blocked."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            self._set_home(tmpdir)
+
+            for sensitive_name in sorted(EXTRA_READ_PATHS_BLOCKLIST):
+                sensitive_dir = Path(tmpdir) / sensitive_name
+                sensitive_dir.mkdir(parents=True, exist_ok=True)
+
+                os.environ[EXTRA_READ_PATHS_VAR] = str(sensitive_dir)
+                result = get_extra_read_paths()
+                self.assertEqual(
+                    result, [],
+                    f"Blocklist entry '{sensitive_name}' should be blocked"
+                )
+
+    def test_multiple_paths_mixed_sensitive_and_valid(self):
+        """When given multiple paths, only non-sensitive ones should pass."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            self._set_home(tmpdir)
+
+            # Create one sensitive and one valid directory
+            ssh_dir = Path(tmpdir) / ".ssh"
+            ssh_dir.mkdir()
+            valid_dir = Path(tmpdir) / "projects"
+            valid_dir.mkdir()
+
+            os.environ[EXTRA_READ_PATHS_VAR] = f"{ssh_dir},{valid_dir}"
+            result = get_extra_read_paths()
+            self.assertEqual(len(result), 1, "Only the non-sensitive path should be returned")
+            self.assertEqual(result[0], valid_dir.resolve())
+
+    def test_empty_extra_read_paths_returns_empty(self):
+        """Empty EXTRA_READ_PATHS should return empty list."""
+        os.environ[EXTRA_READ_PATHS_VAR] = ""
+        result = get_extra_read_paths()
+        self.assertEqual(result, [])
+
+    def test_unset_extra_read_paths_returns_empty(self):
+        """Unset EXTRA_READ_PATHS should return empty list."""
+        os.environ.pop(EXTRA_READ_PATHS_VAR, None)
+        result = get_extra_read_paths()
+        self.assertEqual(result, [])
+
+    def test_nonexistent_path_is_skipped(self):
+        """A path that does not exist should be skipped."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            self._set_home(tmpdir)
+            nonexistent = Path(tmpdir) / "does_not_exist"
+
+            os.environ[EXTRA_READ_PATHS_VAR] = str(nonexistent)
+            result = get_extra_read_paths()
+            self.assertEqual(result, [])
+
+    def test_relative_path_is_skipped(self):
+        """A relative path should be skipped."""
+        os.environ[EXTRA_READ_PATHS_VAR] = "relative/path"
+        result = get_extra_read_paths()
+        self.assertEqual(result, [])
+
+
+if __name__ == "__main__":
+    unittest.main()

test_dependency_resolver.py

@@ -0,0 +1,426 @@
+#!/usr/bin/env python3
+"""
+Dependency Resolver Tests
+=========================
+
+Tests for the dependency resolver functions including cycle detection.
+Run with: python test_dependency_resolver.py
+"""
+
+import sys
+import time
+from concurrent.futures import ThreadPoolExecutor
+from concurrent.futures import TimeoutError as FuturesTimeoutError
+
+from api.dependency_resolver import (
+    are_dependencies_satisfied,
+    compute_scheduling_scores,
+    get_blocked_features,
+    get_blocking_dependencies,
+    get_ready_features,
+    resolve_dependencies,
+    would_create_circular_dependency,
+)
+
+
+def test_compute_scheduling_scores_simple_chain():
+    """Test scheduling scores for a simple linear dependency chain."""
+    print("\nTesting compute_scheduling_scores with simple chain:")
+
+    features = [
+        {"id": 1, "priority": 1, "dependencies": []},
+        {"id": 2, "priority": 2, "dependencies": [1]},
+        {"id": 3, "priority": 3, "dependencies": [2]},
+    ]
+
+    scores = compute_scheduling_scores(features)
+
+    # All features should have scores
+    passed = True
+    for f in features:
+        if f["id"] not in scores:
+            print(f"  FAIL: Feature {f['id']} missing from scores")
+            passed = False
+
+    if passed:
+        # Root feature (1) should have highest score (unblocks most)
+        if scores[1] > scores[2] > scores[3]:
+            print("  PASS: Root feature has highest score, leaf has lowest")
+        else:
+            print(f"  FAIL: Expected scores[1] > scores[2] > scores[3], got {scores}")
+            passed = False
+
+    return passed
+
+
+def test_compute_scheduling_scores_with_cycle():
+    """Test that compute_scheduling_scores handles circular dependencies without hanging."""
+    print("\nTesting compute_scheduling_scores with circular dependencies:")
+
+    # Create a cycle: 1 -> 2 -> 3 -> 1
+    features = [
+        {"id": 1, "priority": 1, "dependencies": [3]},
+        {"id": 2, "priority": 2, "dependencies": [1]},
+        {"id": 3, "priority": 3, "dependencies": [2]},
+    ]
+
+    # Use timeout to detect infinite loop
+    def compute_with_timeout():
+        return compute_scheduling_scores(features)
+
+    start = time.time()
+    try:
+        with ThreadPoolExecutor(max_workers=1) as executor:
+            future = executor.submit(compute_with_timeout)
+            scores = future.result(timeout=5.0)  # 5 second timeout
+
+        elapsed = time.time() - start
+
+        # Should complete quickly (< 1 second for 3 features)
+        if elapsed > 1.0:
+            print(f"  FAIL: Took {elapsed:.2f}s (expected < 1s)")
+            return False
+
+        # All features should have scores (even cyclic ones)
+        if len(scores) == 3:
+            print(f"  PASS: Completed in {elapsed:.3f}s with {len(scores)} scores")
+            return True
+        else:
+            print(f"  FAIL: Expected 3 scores, got {len(scores)}")
+            return False
+
+    except FuturesTimeoutError:
+        print("  FAIL: Infinite loop detected (timed out after 5s)")
+        return False
+
+
+def test_compute_scheduling_scores_self_reference():
+    """Test scheduling scores with self-referencing dependency."""
+    print("\nTesting compute_scheduling_scores with self-reference:")
+
+    features = [
+        {"id": 1, "priority": 1, "dependencies": [1]},  # Self-reference
+        {"id": 2, "priority": 2, "dependencies": []},
+    ]
+
+    start = time.time()
+    try:
+        with ThreadPoolExecutor(max_workers=1) as executor:
+            future = executor.submit(lambda: compute_scheduling_scores(features))
+            scores = future.result(timeout=5.0)
+
+        elapsed = time.time() - start
+
+        if elapsed > 1.0:
+            print(f"  FAIL: Took {elapsed:.2f}s (expected < 1s)")
+            return False
+
+        if len(scores) == 2:
+            print(f"  PASS: Completed in {elapsed:.3f}s with {len(scores)} scores")
+            return True
+        else:
+            print(f"  FAIL: Expected 2 scores, got {len(scores)}")
+            return False
+
+    except FuturesTimeoutError:
+        print("  FAIL: Infinite loop detected (timed out after 5s)")
+        return False
+
+
+def test_compute_scheduling_scores_complex_cycle():
+    """Test scheduling scores with complex circular dependencies."""
+    print("\nTesting compute_scheduling_scores with complex cycle:")
+
+    # Features 1-3 form a cycle, feature 4 depends on 1
+    features = [
+        {"id": 1, "priority": 1, "dependencies": [3]},
+        {"id": 2, "priority": 2, "dependencies": [1]},
+        {"id": 3, "priority": 3, "dependencies": [2]},
+        {"id": 4, "priority": 4, "dependencies": [1]},  # Outside cycle
+    ]
+
+    start = time.time()
+    try:
+        with ThreadPoolExecutor(max_workers=1) as executor:
+            future = executor.submit(lambda: compute_scheduling_scores(features))
+            scores = future.result(timeout=5.0)
+
+        elapsed = time.time() - start
+
+        if elapsed > 1.0:
+            print(f"  FAIL: Took {elapsed:.2f}s (expected < 1s)")
+            return False
+
+        if len(scores) == 4:
+            print(f"  PASS: Completed in {elapsed:.3f}s with {len(scores)} scores")
+            return True
+        else:
+            print(f"  FAIL: Expected 4 scores, got {len(scores)}")
+            return False
+
+    except FuturesTimeoutError:
+        print("  FAIL: Infinite loop detected (timed out after 5s)")
+        return False
+
+
+def test_compute_scheduling_scores_diamond():
+    """Test scheduling scores with diamond dependency pattern."""
+    print("\nTesting compute_scheduling_scores with diamond pattern:")
+
+    #     1
+    #    / \
+    #   2   3
+    #    \ /
+    #     4
+    features = [
+        {"id": 1, "priority": 1, "dependencies": []},
+        {"id": 2, "priority": 2, "dependencies": [1]},
+        {"id": 3, "priority": 3, "dependencies": [1]},
+        {"id": 4, "priority": 4, "dependencies": [2, 3]},
+    ]
+
+    scores = compute_scheduling_scores(features)
+
+    # Feature 1 should have highest score (unblocks 2, 3, and transitively 4)
+    if scores[1] > scores[2] and scores[1] > scores[3] and scores[1] > scores[4]:
+        # Feature 4 should have lowest score (leaf, unblocks nothing)
+        if scores[4] < scores[2] and scores[4] < scores[3]:
+            print("  PASS: Root has highest score, leaf has lowest")
+            return True
+        else:
+            print(f"  FAIL: Leaf should have lowest score. Scores: {scores}")
+            return False
+    else:
+        print(f"  FAIL: Root should have highest score. Scores: {scores}")
+        return False
+
+
+def test_compute_scheduling_scores_empty():
+    """Test scheduling scores with empty feature list."""
+    print("\nTesting compute_scheduling_scores with empty list:")
+
+    scores = compute_scheduling_scores([])
+
+    if scores == {}:
+        print("  PASS: Returns empty dict for empty input")
+        return True
+    else:
+        print(f"  FAIL: Expected empty dict, got {scores}")
+        return False
+
+
+def test_would_create_circular_dependency():
+    """Test cycle detection for new dependencies."""
+    print("\nTesting would_create_circular_dependency:")
+
+    # Current dependencies: 2 depends on 1, 3 depends on 2
+    # Dependency chain: 3 -> 2 -> 1 (arrows mean "depends on")
+    features = [
+        {"id": 1, "priority": 1, "dependencies": []},
+        {"id": 2, "priority": 2, "dependencies": [1]},
+        {"id": 3, "priority": 3, "dependencies": [2]},
+    ]
+
+    passed = True
+
+    # source_id gains dependency on target_id
+    # Adding "1 depends on 3" would create cycle: 1 -> 3 -> 2 -> 1
+    if would_create_circular_dependency(features, 1, 3):
+        print("  PASS: Detected cycle when adding 1 depends on 3")
+    else:
+        print("  FAIL: Should detect cycle when adding 1 depends on 3")
+        passed = False
+
+    # Adding "3 depends on 1" would NOT create cycle (redundant but not circular)
+    if not would_create_circular_dependency(features, 3, 1):
+        print("  PASS: No false positive for 3 depends on 1")
+    else:
+        print("  FAIL: False positive for 3 depends on 1")
+        passed = False
+
+    # Self-reference should be detected
+    if would_create_circular_dependency(features, 1, 1):
+        print("  PASS: Detected self-reference")
+    else:
+        print("  FAIL: Should detect self-reference")
+        passed = False
+
+    return passed
+
+
+def test_resolve_dependencies_with_cycle():
+    """Test resolve_dependencies detects and reports cycles."""
+    print("\nTesting resolve_dependencies with cycle:")
+
+    # Create a cycle: 1 -> 2 -> 3 -> 1
+    features = [
+        {"id": 1, "priority": 1, "dependencies": [3]},
+        {"id": 2, "priority": 2, "dependencies": [1]},
+        {"id": 3, "priority": 3, "dependencies": [2]},
+    ]
+
+    result = resolve_dependencies(features)
+
+    # Should report circular dependencies
+    if result["circular_dependencies"]:
+        print(f"  PASS: Detected cycle: {result['circular_dependencies']}")
+        return True
+    else:
+        print("  FAIL: Should report circular dependencies")
+        return False
+
+
+def test_are_dependencies_satisfied():
+    """Test dependency satisfaction checking."""
+    print("\nTesting are_dependencies_satisfied:")
+
+    features = [
+        {"id": 1, "priority": 1, "dependencies": [], "passes": True},
+        {"id": 2, "priority": 2, "dependencies": [1], "passes": False},
+        {"id": 3, "priority": 3, "dependencies": [2], "passes": False},
+    ]
+
+    passed = True
+
+    # Feature 1 has no deps, should be satisfied
+    if are_dependencies_satisfied(features[0], features):
+        print("  PASS: Feature 1 (no deps) is satisfied")
+    else:
+        print("  FAIL: Feature 1 should be satisfied")
+        passed = False
+
+    # Feature 2 depends on 1 which passes, should be satisfied
+    if are_dependencies_satisfied(features[1], features):
+        print("  PASS: Feature 2 (dep on passing) is satisfied")
+    else:
+        print("  FAIL: Feature 2 should be satisfied")
+        passed = False
+
+    # Feature 3 depends on 2 which doesn't pass, should NOT be satisfied
+    if not are_dependencies_satisfied(features[2], features):
+        print("  PASS: Feature 3 (dep on non-passing) is not satisfied")
+    else:
+        print("  FAIL: Feature 3 should not be satisfied")
+        passed = False
+
+    return passed
+
+
+def test_get_blocking_dependencies():
+    """Test getting blocking dependency IDs."""
+    print("\nTesting get_blocking_dependencies:")
+
+    features = [
+        {"id": 1, "priority": 1, "dependencies": [], "passes": True},
+        {"id": 2, "priority": 2, "dependencies": [], "passes": False},
+        {"id": 3, "priority": 3, "dependencies": [1, 2], "passes": False},
+    ]
+
+    blocking = get_blocking_dependencies(features[2], features)
+
+    # Only feature 2 should be blocking (1 passes)
+    if blocking == [2]:
+        print("  PASS: Correctly identified blocking dependency")
+        return True
+    else:
+        print(f"  FAIL: Expected [2], got {blocking}")
+        return False
+
+
+def test_get_ready_features():
+    """Test getting ready features."""
+    print("\nTesting get_ready_features:")
+
+    features = [
+        {"id": 1, "priority": 1, "dependencies": [], "passes": True},
+        {"id": 2, "priority": 2, "dependencies": [], "passes": False, "in_progress": False},
+        {"id": 3, "priority": 3, "dependencies": [1], "passes": False, "in_progress": False},
+        {"id": 4, "priority": 4, "dependencies": [2], "passes": False, "in_progress": False},
+    ]
+
+    ready = get_ready_features(features)
+
+    # Features 2 and 3 should be ready
+    # Feature 1 passes, feature 4 blocked by 2
+    ready_ids = [f["id"] for f in ready]
+
+    if 2 in ready_ids and 3 in ready_ids:
+        if 1 not in ready_ids and 4 not in ready_ids:
+            print(f"  PASS: Ready features: {ready_ids}")
+            return True
+        else:
+            print(f"  FAIL: Should not include passing/blocked. Got: {ready_ids}")
+            return False
+    else:
+        print(f"  FAIL: Should include 2 and 3. Got: {ready_ids}")
+        return False
+
+
+def test_get_blocked_features():
+    """Test getting blocked features."""
+    print("\nTesting get_blocked_features:")
+
+    features = [
+        {"id": 1, "priority": 1, "dependencies": [], "passes": False},
+        {"id": 2, "priority": 2, "dependencies": [1], "passes": False},
+    ]
+
+    blocked = get_blocked_features(features)
+
+    # Feature 2 should be blocked by 1
+    if len(blocked) == 1 and blocked[0]["id"] == 2:
+        if blocked[0]["blocked_by"] == [1]:
+            print("  PASS: Correctly identified blocked feature")
+            return True
+        else:
+            print(f"  FAIL: Wrong blocked_by: {blocked[0]['blocked_by']}")
+            return False
+    else:
+        print(f"  FAIL: Expected feature 2 blocked, got: {blocked}")
+        return False
+
+
+def run_all_tests():
+    """Run all tests and report results."""
+    print("=" * 60)
+    print("Dependency Resolver Tests")
+    print("=" * 60)
+
+    tests = [
+        test_compute_scheduling_scores_simple_chain,
+        test_compute_scheduling_scores_with_cycle,
+        test_compute_scheduling_scores_self_reference,
+        test_compute_scheduling_scores_complex_cycle,
+        test_compute_scheduling_scores_diamond,
+        test_compute_scheduling_scores_empty,
+        test_would_create_circular_dependency,
+        test_resolve_dependencies_with_cycle,
+        test_are_dependencies_satisfied,
+        test_get_blocking_dependencies,
+        test_get_ready_features,
+        test_get_blocked_features,
+    ]
+
+    passed = 0
+    failed = 0
+
+    for test in tests:
+        try:
+            if test():
+                passed += 1
+            else:
+                failed += 1
+        except Exception as e:
+            print(f"  ERROR: {e}")
+            failed += 1
+
+    print("\n" + "=" * 60)
+    print(f"Results: {passed} passed, {failed} failed")
+    print("=" * 60)
+
+    return failed == 0
+
+
+if __name__ == "__main__":
+    success = run_all_tests()
+    sys.exit(0 if success else 1)

test_rate_limit_utils.py

@@ -0,0 +1,205 @@
+"""
+Unit tests for rate limit handling functions.
+
+Tests the parse_retry_after(), is_rate_limit_error(), and backoff calculation
+functions from rate_limit_utils.py (shared module).
+"""
+
+import unittest
+
+from rate_limit_utils import (
+    calculate_error_backoff,
+    calculate_rate_limit_backoff,
+    clamp_retry_delay,
+    is_rate_limit_error,
+    parse_retry_after,
+)
+
+
+class TestParseRetryAfter(unittest.TestCase):
+    """Tests for parse_retry_after() function."""
+
+    def test_retry_after_colon_format(self):
+        """Test 'Retry-After: 60' format."""
+        assert parse_retry_after("Retry-After: 60") == 60
+        assert parse_retry_after("retry-after: 120") == 120
+        assert parse_retry_after("retry after: 30 seconds") == 30
+
+    def test_retry_after_space_format(self):
+        """Test 'retry after 60 seconds' format."""
+        assert parse_retry_after("retry after 60 seconds") == 60
+        assert parse_retry_after("Please retry after 120 seconds") == 120
+        assert parse_retry_after("Retry after 30") == 30
+
+    def test_try_again_in_format(self):
+        """Test 'try again in X seconds' format."""
+        assert parse_retry_after("try again in 120 seconds") == 120
+        assert parse_retry_after("Please try again in 60s") == 60
+        assert parse_retry_after("Try again in 30 seconds") == 30
+
+    def test_seconds_remaining_format(self):
+        """Test 'X seconds remaining' format."""
+        assert parse_retry_after("30 seconds remaining") == 30
+        assert parse_retry_after("60 seconds left") == 60
+        assert parse_retry_after("120 seconds until reset") == 120
+
+    def test_retry_after_zero(self):
+        """Test 'Retry-After: 0' returns 0 (not None)."""
+        assert parse_retry_after("Retry-After: 0") == 0
+        assert parse_retry_after("retry after 0 seconds") == 0
+
+    def test_no_match(self):
+        """Test messages that don't contain retry-after info."""
+        assert parse_retry_after("no match here") is None
+        assert parse_retry_after("Connection refused") is None
+        assert parse_retry_after("Internal server error") is None
+        assert parse_retry_after("") is None
+
+    def test_minutes_not_supported(self):
+        """Test that minutes are not parsed (by design)."""
+        # We only support seconds to avoid complexity
+        # These patterns should NOT match when followed by minute/hour units
+        assert parse_retry_after("wait 5 minutes") is None
+        assert parse_retry_after("try again in 2 minutes") is None
+        assert parse_retry_after("retry after 5 minutes") is None
+        assert parse_retry_after("retry after 1 hour") is None
+        assert parse_retry_after("try again in 30 min") is None
+
+
+class TestIsRateLimitError(unittest.TestCase):
+    """Tests for is_rate_limit_error() function."""
+
+    def test_rate_limit_patterns(self):
+        """Test various rate limit error messages."""
+        assert is_rate_limit_error("Rate limit exceeded") is True
+        assert is_rate_limit_error("rate_limit_exceeded") is True
+        assert is_rate_limit_error("Too many requests") is True
+        assert is_rate_limit_error("HTTP 429 Too Many Requests") is True
+        assert is_rate_limit_error("API quota exceeded") is True
+        assert is_rate_limit_error("Server is overloaded") is True
+
+    def test_specific_429_patterns(self):
+        """Test that 429 is detected with proper context."""
+        assert is_rate_limit_error("http 429") is True
+        assert is_rate_limit_error("HTTP429") is True
+        assert is_rate_limit_error("status 429") is True
+        assert is_rate_limit_error("error 429") is True
+        assert is_rate_limit_error("429 too many requests") is True
+
+    def test_case_insensitive(self):
+        """Test that detection is case-insensitive."""
+        assert is_rate_limit_error("RATE LIMIT") is True
+        assert is_rate_limit_error("Rate Limit") is True
+        assert is_rate_limit_error("rate limit") is True
+        assert is_rate_limit_error("RaTe LiMiT") is True
+
+    def test_non_rate_limit_errors(self):
+        """Test non-rate-limit error messages."""
+        assert is_rate_limit_error("Connection refused") is False
+        assert is_rate_limit_error("Authentication failed") is False
+        assert is_rate_limit_error("Invalid API key") is False
+        assert is_rate_limit_error("Internal server error") is False
+        assert is_rate_limit_error("Network timeout") is False
+        assert is_rate_limit_error("") is False
+
+
+class TestFalsePositives(unittest.TestCase):
+    """Verify non-rate-limit messages don't trigger detection."""
+
+    def test_version_numbers_with_429(self):
+        """Version numbers should not trigger."""
+        assert is_rate_limit_error("Node v14.29.0") is False
+        assert is_rate_limit_error("Python 3.12.429") is False
+        assert is_rate_limit_error("Version 2.429 released") is False
+
+    def test_issue_and_pr_numbers(self):
+        """Issue/PR numbers should not trigger."""
+        assert is_rate_limit_error("See PR #429") is False
+        assert is_rate_limit_error("Fixed in issue 429") is False
+        assert is_rate_limit_error("Closes #429") is False
+
+    def test_line_numbers(self):
+        """Line numbers in errors should not trigger."""
+        assert is_rate_limit_error("Error at line 429") is False
+        assert is_rate_limit_error("See file.py:429") is False
+
+    def test_port_numbers(self):
+        """Port numbers should not trigger."""
+        assert is_rate_limit_error("port 4293") is False
+        assert is_rate_limit_error("localhost:4290") is False
+
+    def test_legitimate_wait_messages(self):
+        """Legitimate wait instructions should not trigger."""
+        # These would fail if "please wait" pattern still exists
+        assert is_rate_limit_error("Please wait for the build to complete") is False
+        assert is_rate_limit_error("Please wait while I analyze this") is False
+
+    def test_retry_discussion_messages(self):
+        """Messages discussing retry logic should not trigger."""
+        # These would fail if "try again later" pattern still exists
+        assert is_rate_limit_error("Try again later after maintenance") is False
+        assert is_rate_limit_error("The user should try again later") is False
+
+    def test_limit_discussion_messages(self):
+        """Messages discussing limits should not trigger (removed pattern)."""
+        # These would fail if "limit reached" pattern still exists
+        assert is_rate_limit_error("File size limit reached") is False
+        assert is_rate_limit_error("Memory limit reached, consider optimization") is False
+
+    def test_overloaded_in_programming_context(self):
+        """Method/operator overloading discussions should not trigger."""
+        assert is_rate_limit_error("I will create an overloaded constructor") is False
+        assert is_rate_limit_error("The + operator is overloaded") is False
+        assert is_rate_limit_error("Here is the overloaded version of the function") is False
+        assert is_rate_limit_error("The method is overloaded to accept different types") is False
+        # But actual API overload messages should still match
+        assert is_rate_limit_error("Server is overloaded") is True
+        assert is_rate_limit_error("API overloaded") is True
+        assert is_rate_limit_error("system is overloaded") is True
+
+
+class TestBackoffFunctions(unittest.TestCase):
+    """Test backoff calculation functions from rate_limit_utils."""
+
+    def test_rate_limit_backoff_sequence(self):
+        """Test that rate limit backoff follows expected exponential sequence with jitter.
+
+        Base formula: 15 * 2^retries with 0-30% jitter.
+        Base values: 15, 30, 60, 120, 240, 480, 960, 1920, 3600, 3600
+        With jitter the result should be in [base, base * 1.3].
+        """
+        base_values = [15, 30, 60, 120, 240, 480, 960, 1920, 3600, 3600]
+        for retries, base in enumerate(base_values):
+            delay = calculate_rate_limit_backoff(retries)
+            # Delay must be at least the base value (jitter is non-negative)
+            assert delay >= base, f"Retry {retries}: {delay} < base {base}"
+            # Delay must not exceed base + 30% jitter (int truncation means <= base * 1.3)
+            max_with_jitter = int(base * 1.3)
+            assert delay <= max_with_jitter, f"Retry {retries}: {delay} > max {max_with_jitter}"
+
+    def test_error_backoff_sequence(self):
+        """Test that error backoff follows expected linear sequence."""
+        expected = [30, 60, 90, 120, 150, 180, 210, 240, 270, 300, 300]  # Caps at 300
+        for retries in range(1, len(expected) + 1):
+            delay = calculate_error_backoff(retries)
+            expected_delay = expected[retries - 1]
+            assert delay == expected_delay, f"Retry {retries}: expected {expected_delay}, got {delay}"
+
+    def test_clamp_retry_delay(self):
+        """Test that retry delay is clamped to valid range."""
+        # Values within range stay the same
+        assert clamp_retry_delay(60) == 60
+        assert clamp_retry_delay(1800) == 1800
+        assert clamp_retry_delay(3600) == 3600
+
+        # Values below minimum get clamped to 1
+        assert clamp_retry_delay(0) == 1
+        assert clamp_retry_delay(-10) == 1
+
+        # Values above maximum get clamped to 3600
+        assert clamp_retry_delay(7200) == 3600
+        assert clamp_retry_delay(86400) == 3600
+
+
+if __name__ == "__main__":
+    unittest.main()

test_security.py

@@ -107,6 +107,8 @@ def test_extract_commands():
         ("/usr/bin/node script.js", ["node"]),
         ("VAR=value ls", ["ls"]),
         ("git status || git init", ["git", "git"]),
+        # Fallback parser test: complex nested quotes that break shlex
+        ('docker exec container php -r "echo \\"test\\";"', ["docker"]),
     ]
 
     for cmd, expected in test_cases:
@@ -453,6 +455,21 @@ commands:
             print("  FAIL: Non-allowed command 'rustc' should be blocked")
             failed += 1
 
+        # Test 4: Empty command name is rejected
+        config_path.write_text("""version: 1
+commands:
+  - name: ""
+    description: Empty name should be rejected
+""")
+        result = load_project_commands(project_dir)
+        if result is None:
+            print("  PASS: Empty command name rejected in project config")
+            passed += 1
+        else:
+            print("  FAIL: Empty command name should be rejected in project config")
+            print(f"         Got: {result}")
+            failed += 1
+
     return passed, failed
 
 
@@ -975,31 +992,26 @@ def main():
     failed += pkill_failed
 
     # Commands that SHOULD be blocked
+    # Note: blocklisted commands (sudo, shutdown, dd, aws) are tested in
+    # test_blocklist_enforcement(). chmod validation is tested in
+    # test_validate_chmod(). init.sh validation is tested in
+    # test_validate_init_script(). pkill validation is tested in
+    # test_pkill_extensibility(). The entries below focus on scenarios
+    # NOT covered by those dedicated tests.
     print("\nCommands that should be BLOCKED:\n")
     dangerous = [
         # Not in allowlist - dangerous system commands
-        "shutdown now",
         "reboot",
-        "dd if=/dev/zero of=/dev/sda",
         # Not in allowlist - common commands excluded from minimal set
         "wget https://example.com",
         "python app.py",
         "killall node",
-        # pkill with non-dev processes
+        # pkill with non-dev processes (pkill python tested in test_pkill_extensibility)
         "pkill bash",
         "pkill chrome",
-        "pkill python",
         # Shell injection attempts
         "$(echo pkill) node",
         'eval "pkill node"',
-        # chmod with disallowed modes
-        "chmod 777 file.sh",
-        "chmod 755 file.sh",
-        "chmod +w file.sh",
-        "chmod -R +x dir/",
-        # Non-init.sh scripts
-        "./setup.sh",
-        "./malicious.sh",
     ]
 
     for cmd in dangerous:
@@ -1009,6 +1021,10 @@ def main():
             failed += 1
 
     # Commands that SHOULD be allowed
+    # Note: chmod +x variants are tested in test_validate_chmod().
+    # init.sh variants are tested in test_validate_init_script().
+    # The combined "chmod +x init.sh && ./init.sh" below serves as the
+    # integration test verifying the hook routes to both validators correctly.
     print("\nCommands that should be ALLOWED:\n")
     safe = [
         # File inspection
@@ -1059,16 +1075,7 @@ def main():
         "ls | grep test",
         # Full paths
         "/usr/local/bin/node app.js",
-        # chmod +x (allowed)
+        # Combined chmod and init.sh (integration test for both validators)
-        "chmod +x init.sh",
-        "chmod +x script.sh",
-        "chmod u+x init.sh",
-        "chmod a+x init.sh",
-        # init.sh execution (allowed)
-        "./init.sh",
-        "./init.sh --production",
-        "/path/to/init.sh",
-        # Combined chmod and init.sh
         "chmod +x init.sh && ./init.sh",
     ]
 

ui/package-lock.json

@@ -12,16 +12,9 @@
         "@radix-ui/react-dialog": "^1.1.15",
         "@radix-ui/react-dropdown-menu": "^2.1.16",
         "@radix-ui/react-label": "^2.1.8",
-        "@radix-ui/react-popover": "^1.1.15",
-        "@radix-ui/react-radio-group": "^1.3.8",
-        "@radix-ui/react-scroll-area": "^1.2.10",
-        "@radix-ui/react-select": "^2.2.6",
         "@radix-ui/react-separator": "^1.1.8",
         "@radix-ui/react-slot": "^1.2.4",
         "@radix-ui/react-switch": "^1.2.6",
-        "@radix-ui/react-tabs": "^1.1.13",
-        "@radix-ui/react-toggle": "^1.1.10",
-        "@radix-ui/react-tooltip": "^1.2.8",
         "@tanstack/react-query": "^5.72.0",
         "@xterm/addon-fit": "^0.11.0",
         "@xterm/addon-web-links": "^0.12.0",
@@ -1093,12 +1086,6 @@
         "node": ">=18"
       }
     },
-    "node_modules/@radix-ui/number": {
-      "version": "1.1.1",
-      "resolved": "https://registry.npmjs.org/@radix-ui/number/-/number-1.1.1.tgz",
-      "integrity": "sha512-MkKCwxlXTgz6CFoJx3pCwn07GKp36+aZyu/u2Ln2VrA5DcdyCZkASEDBTd8x5whTQQL5CiYf4prXKLcgQdv29g==",
-      "license": "MIT"
-    },
     "node_modules/@radix-ui/primitive": {
       "version": "1.1.3",
       "resolved": "https://registry.npmjs.org/@radix-ui/primitive/-/primitive-1.1.3.tgz",
@@ -1519,61 +1506,6 @@
         }
       }
     },
-    "node_modules/@radix-ui/react-popover": {
-      "version": "1.1.15",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-popover/-/react-popover-1.1.15.tgz",
-      "integrity": "sha512-kr0X2+6Yy/vJzLYJUPCZEc8SfQcf+1COFoAqauJm74umQhta9M7lNJHP7QQS3vkvcGLQUbWpMzwrXYwrYztHKA==",
-      "license": "MIT",
-      "dependencies": {
-        "@radix-ui/primitive": "1.1.3",
-        "@radix-ui/react-compose-refs": "1.1.2",
-        "@radix-ui/react-context": "1.1.2",
-        "@radix-ui/react-dismissable-layer": "1.1.11",
-        "@radix-ui/react-focus-guards": "1.1.3",
-        "@radix-ui/react-focus-scope": "1.1.7",
-        "@radix-ui/react-id": "1.1.1",
-        "@radix-ui/react-popper": "1.2.8",
-        "@radix-ui/react-portal": "1.1.9",
-        "@radix-ui/react-presence": "1.1.5",
-        "@radix-ui/react-primitive": "2.1.3",
-        "@radix-ui/react-slot": "1.2.3",
-        "@radix-ui/react-use-controllable-state": "1.2.2",
-        "aria-hidden": "^1.2.4",
-        "react-remove-scroll": "^2.6.3"
-      },
-      "peerDependencies": {
-        "@types/react": "*",
-        "@types/react-dom": "*",
-        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
-        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
-      },
-      "peerDependenciesMeta": {
-        "@types/react": {
-          "optional": true
-        },
-        "@types/react-dom": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/@radix-ui/react-popover/node_modules/@radix-ui/react-slot": {
-      "version": "1.2.3",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz",
-      "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==",
-      "license": "MIT",
-      "dependencies": {
-        "@radix-ui/react-compose-refs": "1.1.2"
-      },
-      "peerDependencies": {
-        "@types/react": "*",
-        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
-      },
-      "peerDependenciesMeta": {
-        "@types/react": {
-          "optional": true
-        }
-      }
-    },
     "node_modules/@radix-ui/react-popper": {
       "version": "1.2.8",
       "resolved": "https://registry.npmjs.org/@radix-ui/react-popper/-/react-popper-1.2.8.tgz",
@@ -1695,38 +1627,6 @@
         }
       }
     },
-    "node_modules/@radix-ui/react-radio-group": {
-      "version": "1.3.8",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-radio-group/-/react-radio-group-1.3.8.tgz",
-      "integrity": "sha512-VBKYIYImA5zsxACdisNQ3BjCBfmbGH3kQlnFVqlWU4tXwjy7cGX8ta80BcrO+WJXIn5iBylEH3K6ZTlee//lgQ==",
-      "license": "MIT",
-      "dependencies": {
-        "@radix-ui/primitive": "1.1.3",
-        "@radix-ui/react-compose-refs": "1.1.2",
-        "@radix-ui/react-context": "1.1.2",
-        "@radix-ui/react-direction": "1.1.1",
-        "@radix-ui/react-presence": "1.1.5",
-        "@radix-ui/react-primitive": "2.1.3",
-        "@radix-ui/react-roving-focus": "1.1.11",
-        "@radix-ui/react-use-controllable-state": "1.2.2",
-        "@radix-ui/react-use-previous": "1.1.1",
-        "@radix-ui/react-use-size": "1.1.1"
-      },
-      "peerDependencies": {
-        "@types/react": "*",
-        "@types/react-dom": "*",
-        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
-        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
-      },
-      "peerDependenciesMeta": {
-        "@types/react": {
-          "optional": true
-        },
-        "@types/react-dom": {
-          "optional": true
-        }
-      }
-    },
     "node_modules/@radix-ui/react-roving-focus": {
       "version": "1.1.11",
       "resolved": "https://registry.npmjs.org/@radix-ui/react-roving-focus/-/react-roving-focus-1.1.11.tgz",
@@ -1758,98 +1658,6 @@
         }
       }
     },
-    "node_modules/@radix-ui/react-scroll-area": {
-      "version": "1.2.10",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-scroll-area/-/react-scroll-area-1.2.10.tgz",
-      "integrity": "sha512-tAXIa1g3sM5CGpVT0uIbUx/U3Gs5N8T52IICuCtObaos1S8fzsrPXG5WObkQN3S6NVl6wKgPhAIiBGbWnvc97A==",
-      "license": "MIT",
-      "dependencies": {
-        "@radix-ui/number": "1.1.1",
-        "@radix-ui/primitive": "1.1.3",
-        "@radix-ui/react-compose-refs": "1.1.2",
-        "@radix-ui/react-context": "1.1.2",
-        "@radix-ui/react-direction": "1.1.1",
-        "@radix-ui/react-presence": "1.1.5",
-        "@radix-ui/react-primitive": "2.1.3",
-        "@radix-ui/react-use-callback-ref": "1.1.1",
-        "@radix-ui/react-use-layout-effect": "1.1.1"
-      },
-      "peerDependencies": {
-        "@types/react": "*",
-        "@types/react-dom": "*",
-        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
-        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
-      },
-      "peerDependenciesMeta": {
-        "@types/react": {
-          "optional": true
-        },
-        "@types/react-dom": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/@radix-ui/react-select": {
-      "version": "2.2.6",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-select/-/react-select-2.2.6.tgz",
-      "integrity": "sha512-I30RydO+bnn2PQztvo25tswPH+wFBjehVGtmagkU78yMdwTwVf12wnAOF+AeP8S2N8xD+5UPbGhkUfPyvT+mwQ==",
-      "license": "MIT",
-      "dependencies": {
-        "@radix-ui/number": "1.1.1",
-        "@radix-ui/primitive": "1.1.3",
-        "@radix-ui/react-collection": "1.1.7",
-        "@radix-ui/react-compose-refs": "1.1.2",
-        "@radix-ui/react-context": "1.1.2",
-        "@radix-ui/react-direction": "1.1.1",
-        "@radix-ui/react-dismissable-layer": "1.1.11",
-        "@radix-ui/react-focus-guards": "1.1.3",
-        "@radix-ui/react-focus-scope": "1.1.7",
-        "@radix-ui/react-id": "1.1.1",
-        "@radix-ui/react-popper": "1.2.8",
-        "@radix-ui/react-portal": "1.1.9",
-        "@radix-ui/react-primitive": "2.1.3",
-        "@radix-ui/react-slot": "1.2.3",
-        "@radix-ui/react-use-callback-ref": "1.1.1",
-        "@radix-ui/react-use-controllable-state": "1.2.2",
-        "@radix-ui/react-use-layout-effect": "1.1.1",
-        "@radix-ui/react-use-previous": "1.1.1",
-        "@radix-ui/react-visually-hidden": "1.2.3",
-        "aria-hidden": "^1.2.4",
-        "react-remove-scroll": "^2.6.3"
-      },
-      "peerDependencies": {
-        "@types/react": "*",
-        "@types/react-dom": "*",
-        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
-        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
-      },
-      "peerDependenciesMeta": {
-        "@types/react": {
-          "optional": true
-        },
-        "@types/react-dom": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/@radix-ui/react-select/node_modules/@radix-ui/react-slot": {
-      "version": "1.2.3",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz",
-      "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==",
-      "license": "MIT",
-      "dependencies": {
-        "@radix-ui/react-compose-refs": "1.1.2"
-      },
-      "peerDependencies": {
-        "@types/react": "*",
-        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
-      },
-      "peerDependenciesMeta": {
-        "@types/react": {
-          "optional": true
-        }
-      }
-    },
     "node_modules/@radix-ui/react-separator": {
       "version": "1.1.8",
       "resolved": "https://registry.npmjs.org/@radix-ui/react-separator/-/react-separator-1.1.8.tgz",
@@ -1943,113 +1751,6 @@
         }
       }
     },
-    "node_modules/@radix-ui/react-tabs": {
-      "version": "1.1.13",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-tabs/-/react-tabs-1.1.13.tgz",
-      "integrity": "sha512-7xdcatg7/U+7+Udyoj2zodtI9H/IIopqo+YOIcZOq1nJwXWBZ9p8xiu5llXlekDbZkca79a/fozEYQXIA4sW6A==",
-      "license": "MIT",
-      "dependencies": {
-        "@radix-ui/primitive": "1.1.3",
-        "@radix-ui/react-context": "1.1.2",
-        "@radix-ui/react-direction": "1.1.1",
-        "@radix-ui/react-id": "1.1.1",
-        "@radix-ui/react-presence": "1.1.5",
-        "@radix-ui/react-primitive": "2.1.3",
-        "@radix-ui/react-roving-focus": "1.1.11",
-        "@radix-ui/react-use-controllable-state": "1.2.2"
-      },
-      "peerDependencies": {
-        "@types/react": "*",
-        "@types/react-dom": "*",
-        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
-        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
-      },
-      "peerDependenciesMeta": {
-        "@types/react": {
-          "optional": true
-        },
-        "@types/react-dom": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/@radix-ui/react-toggle": {
-      "version": "1.1.10",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-toggle/-/react-toggle-1.1.10.tgz",
-      "integrity": "sha512-lS1odchhFTeZv3xwHH31YPObmJn8gOg7Lq12inrr0+BH/l3Tsq32VfjqH1oh80ARM3mlkfMic15n0kg4sD1poQ==",
-      "license": "MIT",
-      "dependencies": {
-        "@radix-ui/primitive": "1.1.3",
-        "@radix-ui/react-primitive": "2.1.3",
-        "@radix-ui/react-use-controllable-state": "1.2.2"
-      },
-      "peerDependencies": {
-        "@types/react": "*",
-        "@types/react-dom": "*",
-        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
-        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
-      },
-      "peerDependenciesMeta": {
-        "@types/react": {
-          "optional": true
-        },
-        "@types/react-dom": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/@radix-ui/react-tooltip": {
-      "version": "1.2.8",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-tooltip/-/react-tooltip-1.2.8.tgz",
-      "integrity": "sha512-tY7sVt1yL9ozIxvmbtN5qtmH2krXcBCfjEiCgKGLqunJHvgvZG2Pcl2oQ3kbcZARb1BGEHdkLzcYGO8ynVlieg==",
-      "license": "MIT",
-      "dependencies": {
-        "@radix-ui/primitive": "1.1.3",
-        "@radix-ui/react-compose-refs": "1.1.2",
-        "@radix-ui/react-context": "1.1.2",
-        "@radix-ui/react-dismissable-layer": "1.1.11",
-        "@radix-ui/react-id": "1.1.1",
-        "@radix-ui/react-popper": "1.2.8",
-        "@radix-ui/react-portal": "1.1.9",
-        "@radix-ui/react-presence": "1.1.5",
-        "@radix-ui/react-primitive": "2.1.3",
-        "@radix-ui/react-slot": "1.2.3",
-        "@radix-ui/react-use-controllable-state": "1.2.2",
-        "@radix-ui/react-visually-hidden": "1.2.3"
-      },
-      "peerDependencies": {
-        "@types/react": "*",
-        "@types/react-dom": "*",
-        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
-        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
-      },
-      "peerDependenciesMeta": {
-        "@types/react": {
-          "optional": true
-        },
-        "@types/react-dom": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/@radix-ui/react-tooltip/node_modules/@radix-ui/react-slot": {
-      "version": "1.2.3",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-slot/-/react-slot-1.2.3.tgz",
-      "integrity": "sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==",
-      "license": "MIT",
-      "dependencies": {
-        "@radix-ui/react-compose-refs": "1.1.2"
-      },
-      "peerDependencies": {
-        "@types/react": "*",
-        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
-      },
-      "peerDependenciesMeta": {
-        "@types/react": {
-          "optional": true
-        }
-      }
-    },
     "node_modules/@radix-ui/react-use-callback-ref": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/@radix-ui/react-use-callback-ref/-/react-use-callback-ref-1.1.1.tgz",
@@ -2186,29 +1887,6 @@
         }
       }
     },
-    "node_modules/@radix-ui/react-visually-hidden": {
-      "version": "1.2.3",
-      "resolved": "https://registry.npmjs.org/@radix-ui/react-visually-hidden/-/react-visually-hidden-1.2.3.tgz",
-      "integrity": "sha512-pzJq12tEaaIhqjbzpCuv/OypJY/BPavOofm+dbab+MHLajy277+1lLm6JFcGgF5eskJ6mquGirhXY2GD/8u8Ug==",
-      "license": "MIT",
-      "dependencies": {
-        "@radix-ui/react-primitive": "2.1.3"
-      },
-      "peerDependencies": {
-        "@types/react": "*",
-        "@types/react-dom": "*",
-        "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc",
-        "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc"
-      },
-      "peerDependenciesMeta": {
-        "@types/react": {
-          "optional": true
-        },
-        "@types/react-dom": {
-          "optional": true
-        }
-      }
-    },
     "node_modules/@radix-ui/rect": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/@radix-ui/rect/-/rect-1.1.1.tgz",
@@ -3024,7 +2702,7 @@
       "version": "19.2.9",
       "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.9.tgz",
       "integrity": "sha512-Lpo8kgb/igvMIPeNV2rsYKTgaORYdO1XGVZ4Qz3akwOj0ySGYMPlQWa8BaLn0G63D1aSaAQ5ldR06wCpChQCjA==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "dependencies": {
         "csstype": "^3.2.2"
@@ -3034,7 +2712,7 @@
       "version": "19.2.3",
       "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-19.2.3.tgz",
       "integrity": "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "peerDependencies": {
         "@types/react": "^19.2.0"
@@ -3658,7 +3336,7 @@
       "version": "3.2.3",
       "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
       "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT"
     },
     "node_modules/d3-color": {

ui/package.json

@@ -16,16 +16,9 @@
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",
-    "@radix-ui/react-popover": "^1.1.15",
-    "@radix-ui/react-radio-group": "^1.3.8",
-    "@radix-ui/react-scroll-area": "^1.2.10",
-    "@radix-ui/react-select": "^2.2.6",
     "@radix-ui/react-separator": "^1.1.8",
     "@radix-ui/react-slot": "^1.2.4",
     "@radix-ui/react-switch": "^1.2.6",
-    "@radix-ui/react-tabs": "^1.1.13",
-    "@radix-ui/react-toggle": "^1.1.10",
-    "@radix-ui/react-tooltip": "^1.2.8",
     "@tanstack/react-query": "^5.72.0",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/addon-web-links": "^0.12.0",

ui/src/App.tsx

@@ -13,7 +13,6 @@ import { SetupWizard } from './components/SetupWizard'
 import { AddFeatureForm } from './components/AddFeatureForm'
 import { FeatureModal } from './components/FeatureModal'
 import { DebugLogViewer, type TabType } from './components/DebugLogViewer'
-import { AgentThought } from './components/AgentThought'
 import { AgentMissionControl } from './components/AgentMissionControl'
 import { CelebrationOverlay } from './components/CelebrationOverlay'
 import { AssistantFAB } from './components/AssistantFAB'
@@ -26,8 +25,10 @@ import { ViewToggle, type ViewMode } from './components/ViewToggle'
 import { DependencyGraph } from './components/DependencyGraph'
 import { KeyboardShortcutsHelp } from './components/KeyboardShortcutsHelp'
 import { ThemeSelector } from './components/ThemeSelector'
-import { getDependencyGraph } from './lib/api'
+import { ResetProjectModal } from './components/ResetProjectModal'
-import { Loader2, Settings, Moon, Sun } from 'lucide-react'
+import { ProjectSetupRequired } from './components/ProjectSetupRequired'
+import { getDependencyGraph, startAgent } from './lib/api'
+import { Loader2, Settings, Moon, Sun, RotateCcw } from 'lucide-react'
 import type { Feature } from './lib/types'
 import { Button } from '@/components/ui/button'
 import { Card, CardContent } from '@/components/ui/card'
@@ -36,6 +37,11 @@ import { Badge } from '@/components/ui/badge'
 const STORAGE_KEY = 'autocoder-selected-project'
 const VIEW_MODE_KEY = 'autocoder-view-mode'
 
+// Bottom padding for main content when debug panel is collapsed (40px header + 8px margin)
+const COLLAPSED_DEBUG_PANEL_CLEARANCE = 48
+
+type InitializerStatus = 'idle' | 'starting' | 'error'
+
 function App() {
   // Initialize selected project from localStorage
   const [selectedProject, setSelectedProject] = useState<string | null>(() => {
@@ -56,7 +62,10 @@ function App() {
   const [showSettings, setShowSettings] = useState(false)
   const [showKeyboardHelp, setShowKeyboardHelp] = useState(false)
   const [isSpecCreating, setIsSpecCreating] = useState(false)
+  const [showResetModal, setShowResetModal] = useState(false)
   const [showSpecChat, setShowSpecChat] = useState(false)  // For "Create Spec" button in empty kanban
+  const [specInitializerStatus, setSpecInitializerStatus] = useState<InitializerStatus>('idle')
+  const [specInitializerError, setSpecInitializerError] = useState<string | null>(null)
   const [viewMode, setViewMode] = useState<ViewMode>(() => {
     try {
       const stored = localStorage.getItem(VIEW_MODE_KEY)
@@ -200,10 +209,18 @@ function App() {
         setShowKeyboardHelp(true)
       }
 
+      // R : Open reset modal (when project selected and agent not running)
+      if ((e.key === 'r' || e.key === 'R') && selectedProject && wsState.agentStatus !== 'running') {
+        e.preventDefault()
+        setShowResetModal(true)
+      }
+
       // Escape : Close modals
       if (e.key === 'Escape') {
         if (showKeyboardHelp) {
           setShowKeyboardHelp(false)
+        } else if (showResetModal) {
+          setShowResetModal(false)
         } else if (showExpandProject) {
           setShowExpandProject(false)
         } else if (showSettings) {
@@ -222,7 +239,7 @@ function App() {
 
     window.addEventListener('keydown', handleKeyDown)
     return () => window.removeEventListener('keydown', handleKeyDown)
-  }, [selectedProject, showAddFeature, showExpandProject, selectedFeature, debugOpen, debugActiveTab, assistantOpen, features, showSettings, showKeyboardHelp, isSpecCreating, viewMode])
+  }, [selectedProject, showAddFeature, showExpandProject, selectedFeature, debugOpen, debugActiveTab, assistantOpen, features, showSettings, showKeyboardHelp, isSpecCreating, viewMode, showResetModal, wsState.agentStatus])
 
   // Combine WebSocket progress with feature data
   const progress = wsState.progress.total > 0 ? wsState.progress : {
@@ -242,7 +259,7 @@ function App() {
   return (
     <div className="min-h-screen bg-background">
       {/* Header */}
-      <header className="bg-card text-foreground border-b-2 border-border">
+      <header className="sticky top-0 z-50 bg-card/80 backdrop-blur-md text-foreground border-b-2 border-border">
         <div className="max-w-7xl mx-auto px-4 py-4">
           <div className="flex items-center justify-between">
             {/* Logo and Title */}
@@ -265,6 +282,7 @@ function App() {
                   <AgentControl
                     projectName={selectedProject}
                     status={wsState.agentStatus}
+                    defaultConcurrency={selectedProjectData?.default_concurrency}
                   />
 
                   <DevServerControl
@@ -283,6 +301,17 @@ function App() {
                     <Settings size={18} />
                   </Button>
 
+                  <Button
+                    onClick={() => setShowResetModal(true)}
+                    variant="outline"
+                    size="sm"
+                    title="Reset Project (R)"
+                    aria-label="Reset Project"
+                    disabled={wsState.agentStatus === 'running'}
+                  >
+                    <RotateCcw size={18} />
+                  </Button>
+
                   {/* Ollama Mode Indicator */}
                   {settings?.ollama_mode && (
                     <div
@@ -331,7 +360,7 @@ function App() {
       {/* Main Content */}
       <main
         className="max-w-7xl mx-auto px-4 py-8"
-        style={{ paddingBottom: debugOpen ? debugPanelHeight + 32 : undefined }}
+        style={{ paddingBottom: debugOpen ? debugPanelHeight + 32 : COLLAPSED_DEBUG_PANEL_CLEARANCE }}
       >
         {!selectedProject ? (
           <div className="text-center mt-12">
@@ -342,6 +371,16 @@ function App() {
               Select a project from the dropdown above or create a new one to get started.
             </p>
           </div>
+        ) : !hasSpec ? (
+          <ProjectSetupRequired
+            projectName={selectedProject}
+            projectPath={selectedProjectData?.path}
+            onCreateWithClaude={() => setShowSpecChat(true)}
+            onEditManually={() => {
+              // Open debug panel for the user to see the project path
+              setDebugOpen(true)
+            }}
+          />
         ) : (
           <div className="space-y-8">
             {/* Progress Dashboard */}
@@ -350,6 +389,8 @@ function App() {
               total={progress.total}
               percentage={progress.percentage}
               isConnected={wsState.isConnected}
+              logs={wsState.activeAgents.length === 0 ? wsState.logs : undefined}
+              agentStatus={wsState.activeAgents.length === 0 ? wsState.agentStatus : undefined}
             />
 
             {/* Agent Mission Control - shows orchestrator status and active agents in parallel mode */}
@@ -360,13 +401,6 @@ function App() {
               getAgentLogs={wsState.getAgentLogs}
             />
 
-            {/* Agent Thought - shows latest agent narrative (single agent mode) */}
-            {wsState.activeAgents.length === 0 && (
-              <AgentThought
-                logs={wsState.logs}
-                agentStatus={wsState.agentStatus}
-              />
-            )}
 
             {/* Initializing Features State - show when agent is running but no features yet */}
             {features &&
@@ -459,14 +493,31 @@ function App() {
         <div className="fixed inset-0 z-50 bg-background">
           <SpecCreationChat
             projectName={selectedProject}
-            onComplete={() => {
+            onComplete={async (_specPath, yoloMode) => {
-              setShowSpecChat(false)
+              setSpecInitializerStatus('starting')
-              // Refresh projects to update has_spec
+              try {
-              queryClient.invalidateQueries({ queryKey: ['projects'] })
+                await startAgent(selectedProject, {
-              queryClient.invalidateQueries({ queryKey: ['features', selectedProject] })
+                  yoloMode: yoloMode ?? false,
+                  maxConcurrency: 3,
+                })
+                // Success — close chat and refresh
+                setShowSpecChat(false)
+                setSpecInitializerStatus('idle')
+                queryClient.invalidateQueries({ queryKey: ['projects'] })
+                queryClient.invalidateQueries({ queryKey: ['features', selectedProject] })
+              } catch (err) {
+                setSpecInitializerStatus('error')
+                setSpecInitializerError(err instanceof Error ? err.message : 'Failed to start agent')
+              }
+            }}
+            onCancel={() => { setShowSpecChat(false); setSpecInitializerStatus('idle') }}
+            onExitToProject={() => { setShowSpecChat(false); setSpecInitializerStatus('idle') }}
+            initializerStatus={specInitializerStatus}
+            initializerError={specInitializerError}
+            onRetryInitializer={() => {
+              setSpecInitializerError(null)
+              setSpecInitializerStatus('idle')
             }}
-            onCancel={() => setShowSpecChat(false)}
-            onExitToProject={() => setShowSpecChat(false)}
           />
         </div>
       )}
@@ -508,6 +559,21 @@ function App() {
       {/* Keyboard Shortcuts Help */}
       <KeyboardShortcutsHelp isOpen={showKeyboardHelp} onClose={() => setShowKeyboardHelp(false)} />
 
+      {/* Reset Project Modal */}
+      {showResetModal && selectedProject && (
+        <ResetProjectModal
+          isOpen={showResetModal}
+          projectName={selectedProject}
+          onClose={() => setShowResetModal(false)}
+          onResetComplete={(wasFullReset) => {
+            // If full reset, the spec was deleted - show spec creation chat
+            if (wasFullReset) {
+              setShowSpecChat(true)
+            }
+          }}
+        />
+      )}
+
       {/* Celebration Overlay - shows when a feature is completed by an agent */}
       {wsState.celebration && (
         <CelebrationOverlay

ui/src/components/AgentAvatar.tsx

@@ -1,4 +1,10 @@
 import { type AgentMascot, type AgentState } from '../lib/types'
+import {
+  AVATAR_COLORS,
+  UNKNOWN_COLORS,
+  MASCOT_SVGS,
+  UnknownMascotSVG,
+} from './mascotData'
 
 interface AgentAvatarProps {
   name: AgentMascot | 'Unknown'
@@ -7,515 +13,12 @@ interface AgentAvatarProps {
   showName?: boolean
 }
 
-// Fallback colors for unknown agents (neutral gray)
-const UNKNOWN_COLORS = { primary: '#6B7280', secondary: '#9CA3AF', accent: '#F3F4F6' }
-
-const AVATAR_COLORS: Record<AgentMascot, { primary: string; secondary: string; accent: string }> = {
-  // Original 5
-  Spark: { primary: '#3B82F6', secondary: '#60A5FA', accent: '#DBEAFE' },  // Blue robot
-  Fizz: { primary: '#F97316', secondary: '#FB923C', accent: '#FFEDD5' },   // Orange fox
-  Octo: { primary: '#8B5CF6', secondary: '#A78BFA', accent: '#EDE9FE' },   // Purple octopus
-  Hoot: { primary: '#22C55E', secondary: '#4ADE80', accent: '#DCFCE7' },   // Green owl
-  Buzz: { primary: '#EAB308', secondary: '#FACC15', accent: '#FEF9C3' },   // Yellow bee
-  // Tech-inspired
-  Pixel: { primary: '#EC4899', secondary: '#F472B6', accent: '#FCE7F3' },  // Pink
-  Byte: { primary: '#06B6D4', secondary: '#22D3EE', accent: '#CFFAFE' },   // Cyan
-  Nova: { primary: '#F43F5E', secondary: '#FB7185', accent: '#FFE4E6' },   // Rose
-  Chip: { primary: '#84CC16', secondary: '#A3E635', accent: '#ECFCCB' },   // Lime
-  Bolt: { primary: '#FBBF24', secondary: '#FCD34D', accent: '#FEF3C7' },   // Amber
-  // Energetic
-  Dash: { primary: '#14B8A6', secondary: '#2DD4BF', accent: '#CCFBF1' },   // Teal
-  Zap: { primary: '#A855F7', secondary: '#C084FC', accent: '#F3E8FF' },    // Violet
-  Gizmo: { primary: '#64748B', secondary: '#94A3B8', accent: '#F1F5F9' },  // Slate
-  Turbo: { primary: '#EF4444', secondary: '#F87171', accent: '#FEE2E2' },  // Red
-  Blip: { primary: '#10B981', secondary: '#34D399', accent: '#D1FAE5' },   // Emerald
-  // Playful
-  Neon: { primary: '#D946EF', secondary: '#E879F9', accent: '#FAE8FF' },   // Fuchsia
-  Widget: { primary: '#6366F1', secondary: '#818CF8', accent: '#E0E7FF' }, // Indigo
-  Zippy: { primary: '#F59E0B', secondary: '#FBBF24', accent: '#FEF3C7' },  // Orange-yellow
-  Quirk: { primary: '#0EA5E9', secondary: '#38BDF8', accent: '#E0F2FE' },  // Sky
-  Flux: { primary: '#7C3AED', secondary: '#8B5CF6', accent: '#EDE9FE' },   // Purple
-}
-
 const SIZES = {
   sm: { svg: 32, font: 'text-xs' },
   md: { svg: 48, font: 'text-sm' },
   lg: { svg: 64, font: 'text-base' },
 }
 
-// SVG mascot definitions - simple cute characters
-function SparkSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Spark; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Robot body */}
-      <rect x="16" y="20" width="32" height="28" rx="4" fill={colors.primary} />
-      {/* Robot head */}
-      <rect x="12" y="8" width="40" height="24" rx="4" fill={colors.secondary} />
-      {/* Antenna */}
-      <circle cx="32" cy="4" r="4" fill={colors.primary} className="animate-pulse" />
-      <rect x="30" y="4" width="4" height="8" fill={colors.primary} />
-      {/* Eyes */}
-      <circle cx="24" cy="18" r="4" fill="white" />
-      <circle cx="40" cy="18" r="4" fill="white" />
-      <circle cx="25" cy="18" r="2" fill={colors.primary} />
-      <circle cx="41" cy="18" r="2" fill={colors.primary} />
-      {/* Mouth */}
-      <rect x="26" y="24" width="12" height="2" rx="1" fill="white" />
-      {/* Arms */}
-      <rect x="6" y="24" width="8" height="4" rx="2" fill={colors.primary} />
-      <rect x="50" y="24" width="8" height="4" rx="2" fill={colors.primary} />
-    </svg>
-  )
-}
-
-function FizzSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Fizz; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Ears */}
-      <polygon points="12,12 20,28 4,28" fill={colors.primary} />
-      <polygon points="52,12 60,28 44,28" fill={colors.primary} />
-      <polygon points="14,14 18,26 8,26" fill={colors.accent} />
-      <polygon points="50,14 56,26 44,26" fill={colors.accent} />
-      {/* Head */}
-      <ellipse cx="32" cy="36" rx="24" ry="22" fill={colors.primary} />
-      {/* Face */}
-      <ellipse cx="32" cy="40" rx="18" ry="14" fill={colors.accent} />
-      {/* Eyes */}
-      <ellipse cx="24" cy="32" rx="4" ry="5" fill="white" />
-      <ellipse cx="40" cy="32" rx="4" ry="5" fill="white" />
-      <circle cx="25" cy="33" r="2" fill="#1a1a1a" />
-      <circle cx="41" cy="33" r="2" fill="#1a1a1a" />
-      {/* Nose */}
-      <ellipse cx="32" cy="42" rx="4" ry="3" fill={colors.primary} />
-      {/* Whiskers */}
-      <line x1="8" y1="38" x2="18" y2="40" stroke={colors.primary} strokeWidth="2" />
-      <line x1="8" y1="44" x2="18" y2="44" stroke={colors.primary} strokeWidth="2" />
-      <line x1="46" y1="40" x2="56" y2="38" stroke={colors.primary} strokeWidth="2" />
-      <line x1="46" y1="44" x2="56" y2="44" stroke={colors.primary} strokeWidth="2" />
-    </svg>
-  )
-}
-
-function OctoSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Octo; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Tentacles */}
-      <path d="M12,48 Q8,56 12,60 Q16,64 20,58" fill={colors.secondary} />
-      <path d="M22,50 Q20,58 24,62" fill={colors.secondary} />
-      <path d="M32,52 Q32,60 36,62" fill={colors.secondary} />
-      <path d="M42,50 Q44,58 40,62" fill={colors.secondary} />
-      <path d="M52,48 Q56,56 52,60 Q48,64 44,58" fill={colors.secondary} />
-      {/* Head */}
-      <ellipse cx="32" cy="32" rx="22" ry="24" fill={colors.primary} />
-      {/* Eyes */}
-      <ellipse cx="24" cy="28" rx="6" ry="8" fill="white" />
-      <ellipse cx="40" cy="28" rx="6" ry="8" fill="white" />
-      <ellipse cx="25" cy="30" rx="3" ry="4" fill={colors.primary} />
-      <ellipse cx="41" cy="30" rx="3" ry="4" fill={colors.primary} />
-      {/* Smile */}
-      <path d="M24,42 Q32,48 40,42" stroke={colors.accent} strokeWidth="2" fill="none" strokeLinecap="round" />
-    </svg>
-  )
-}
-
-function HootSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Hoot; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Ear tufts */}
-      <polygon points="14,8 22,24 6,20" fill={colors.primary} />
-      <polygon points="50,8 58,20 42,24" fill={colors.primary} />
-      {/* Body */}
-      <ellipse cx="32" cy="40" rx="20" ry="18" fill={colors.primary} />
-      {/* Head */}
-      <circle cx="32" cy="28" r="20" fill={colors.secondary} />
-      {/* Eye circles */}
-      <circle cx="24" cy="26" r="10" fill={colors.accent} />
-      <circle cx="40" cy="26" r="10" fill={colors.accent} />
-      {/* Eyes */}
-      <circle cx="24" cy="26" r="6" fill="white" />
-      <circle cx="40" cy="26" r="6" fill="white" />
-      <circle cx="25" cy="27" r="3" fill="#1a1a1a" />
-      <circle cx="41" cy="27" r="3" fill="#1a1a1a" />
-      {/* Beak */}
-      <polygon points="32,32 28,40 36,40" fill="#F97316" />
-      {/* Belly */}
-      <ellipse cx="32" cy="46" rx="10" ry="8" fill={colors.accent} />
-    </svg>
-  )
-}
-
-function BuzzSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Buzz; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Wings */}
-      <ellipse cx="14" cy="32" rx="10" ry="14" fill={colors.accent} opacity="0.8" className="animate-pulse" />
-      <ellipse cx="50" cy="32" rx="10" ry="14" fill={colors.accent} opacity="0.8" className="animate-pulse" />
-      {/* Body stripes */}
-      <ellipse cx="32" cy="36" rx="14" ry="20" fill={colors.primary} />
-      <ellipse cx="32" cy="30" rx="12" ry="6" fill="#1a1a1a" />
-      <ellipse cx="32" cy="44" rx="12" ry="6" fill="#1a1a1a" />
-      {/* Head */}
-      <circle cx="32" cy="16" r="12" fill={colors.primary} />
-      {/* Antennae */}
-      <line x1="26" y1="8" x2="22" y2="2" stroke="#1a1a1a" strokeWidth="2" />
-      <line x1="38" y1="8" x2="42" y2="2" stroke="#1a1a1a" strokeWidth="2" />
-      <circle cx="22" cy="2" r="2" fill="#1a1a1a" />
-      <circle cx="42" cy="2" r="2" fill="#1a1a1a" />
-      {/* Eyes */}
-      <circle cx="28" cy="14" r="4" fill="white" />
-      <circle cx="36" cy="14" r="4" fill="white" />
-      <circle cx="29" cy="15" r="2" fill="#1a1a1a" />
-      <circle cx="37" cy="15" r="2" fill="#1a1a1a" />
-      {/* Smile */}
-      <path d="M28,20 Q32,24 36,20" stroke="#1a1a1a" strokeWidth="1.5" fill="none" strokeLinecap="round" />
-    </svg>
-  )
-}
-
-// Pixel - cute pixel art style character
-function PixelSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Pixel; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Blocky body */}
-      <rect x="20" y="28" width="24" height="28" fill={colors.primary} />
-      <rect x="16" y="32" width="8" height="20" fill={colors.secondary} />
-      <rect x="40" y="32" width="8" height="20" fill={colors.secondary} />
-      {/* Head */}
-      <rect x="16" y="8" width="32" height="24" fill={colors.primary} />
-      {/* Eyes */}
-      <rect x="20" y="14" width="8" height="8" fill="white" />
-      <rect x="36" y="14" width="8" height="8" fill="white" />
-      <rect x="24" y="16" width="4" height="4" fill="#1a1a1a" />
-      <rect x="38" y="16" width="4" height="4" fill="#1a1a1a" />
-      {/* Mouth */}
-      <rect x="26" y="26" width="12" height="4" fill={colors.accent} />
-    </svg>
-  )
-}
-
-// Byte - data cube character
-function ByteSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Byte; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* 3D cube body */}
-      <polygon points="32,8 56,20 56,44 32,56 8,44 8,20" fill={colors.primary} />
-      <polygon points="32,8 56,20 32,32 8,20" fill={colors.secondary} />
-      <polygon points="32,32 56,20 56,44 32,56" fill={colors.accent} opacity="0.6" />
-      {/* Face */}
-      <circle cx="24" cy="28" r="4" fill="white" />
-      <circle cx="40" cy="28" r="4" fill="white" />
-      <circle cx="25" cy="29" r="2" fill="#1a1a1a" />
-      <circle cx="41" cy="29" r="2" fill="#1a1a1a" />
-      <path d="M26,38 Q32,42 38,38" stroke="white" strokeWidth="2" fill="none" strokeLinecap="round" />
-    </svg>
-  )
-}
-
-// Nova - star character
-function NovaSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Nova; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Star points */}
-      <polygon points="32,2 38,22 58,22 42,36 48,56 32,44 16,56 22,36 6,22 26,22" fill={colors.primary} />
-      <circle cx="32" cy="32" r="14" fill={colors.secondary} />
-      {/* Face */}
-      <circle cx="27" cy="30" r="3" fill="white" />
-      <circle cx="37" cy="30" r="3" fill="white" />
-      <circle cx="28" cy="31" r="1.5" fill="#1a1a1a" />
-      <circle cx="38" cy="31" r="1.5" fill="#1a1a1a" />
-      <path d="M28,37 Q32,40 36,37" stroke="#1a1a1a" strokeWidth="1.5" fill="none" strokeLinecap="round" />
-    </svg>
-  )
-}
-
-// Chip - circuit board character
-function ChipSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Chip; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Chip body */}
-      <rect x="16" y="16" width="32" height="32" rx="4" fill={colors.primary} />
-      {/* Pins */}
-      <rect x="20" y="10" width="4" height="8" fill={colors.secondary} />
-      <rect x="30" y="10" width="4" height="8" fill={colors.secondary} />
-      <rect x="40" y="10" width="4" height="8" fill={colors.secondary} />
-      <rect x="20" y="46" width="4" height="8" fill={colors.secondary} />
-      <rect x="30" y="46" width="4" height="8" fill={colors.secondary} />
-      <rect x="40" y="46" width="4" height="8" fill={colors.secondary} />
-      {/* Face */}
-      <circle cx="26" cy="28" r="4" fill={colors.accent} />
-      <circle cx="38" cy="28" r="4" fill={colors.accent} />
-      <circle cx="26" cy="28" r="2" fill="#1a1a1a" />
-      <circle cx="38" cy="28" r="2" fill="#1a1a1a" />
-      <rect x="26" y="38" width="12" height="3" rx="1" fill={colors.accent} />
-    </svg>
-  )
-}
-
-// Bolt - lightning character
-function BoltSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Bolt; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Lightning bolt body */}
-      <polygon points="36,4 20,28 30,28 24,60 48,32 36,32 44,4" fill={colors.primary} />
-      <polygon points="34,8 24,26 32,26 28,52 42,34 34,34 40,8" fill={colors.secondary} />
-      {/* Face */}
-      <circle cx="30" cy="30" r="3" fill="white" />
-      <circle cx="38" cy="26" r="3" fill="white" />
-      <circle cx="31" cy="31" r="1.5" fill="#1a1a1a" />
-      <circle cx="39" cy="27" r="1.5" fill="#1a1a1a" />
-    </svg>
-  )
-}
-
-// Dash - speedy character
-function DashSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Dash; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Speed lines */}
-      <rect x="4" y="28" width="12" height="3" rx="1" fill={colors.accent} opacity="0.6" />
-      <rect x="8" y="34" width="10" height="3" rx="1" fill={colors.accent} opacity="0.4" />
-      {/* Aerodynamic body */}
-      <ellipse cx="36" cy="32" rx="20" ry="16" fill={colors.primary} />
-      <ellipse cx="40" cy="32" rx="14" ry="12" fill={colors.secondary} />
-      {/* Face */}
-      <circle cx="38" cy="28" r="4" fill="white" />
-      <circle cx="48" cy="28" r="4" fill="white" />
-      <circle cx="39" cy="29" r="2" fill="#1a1a1a" />
-      <circle cx="49" cy="29" r="2" fill="#1a1a1a" />
-      <path d="M40,36 Q44,39 48,36" stroke="#1a1a1a" strokeWidth="1.5" fill="none" strokeLinecap="round" />
-    </svg>
-  )
-}
-
-// Zap - electric orb
-function ZapSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Zap; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Electric sparks */}
-      <path d="M12,32 L20,28 L16,32 L22,30" stroke={colors.secondary} strokeWidth="2" className="animate-pulse" />
-      <path d="M52,32 L44,28 L48,32 L42,30" stroke={colors.secondary} strokeWidth="2" className="animate-pulse" />
-      {/* Orb */}
-      <circle cx="32" cy="32" r="18" fill={colors.primary} />
-      <circle cx="32" cy="32" r="14" fill={colors.secondary} />
-      {/* Face */}
-      <circle cx="26" cy="30" r="4" fill="white" />
-      <circle cx="38" cy="30" r="4" fill="white" />
-      <circle cx="27" cy="31" r="2" fill={colors.primary} />
-      <circle cx="39" cy="31" r="2" fill={colors.primary} />
-      <path d="M28,40 Q32,44 36,40" stroke="white" strokeWidth="2" fill="none" strokeLinecap="round" />
-    </svg>
-  )
-}
-
-// Gizmo - gear character
-function GizmoSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Gizmo; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Gear teeth */}
-      <rect x="28" y="4" width="8" height="8" fill={colors.primary} />
-      <rect x="28" y="52" width="8" height="8" fill={colors.primary} />
-      <rect x="4" y="28" width="8" height="8" fill={colors.primary} />
-      <rect x="52" y="28" width="8" height="8" fill={colors.primary} />
-      {/* Gear body */}
-      <circle cx="32" cy="32" r="20" fill={colors.primary} />
-      <circle cx="32" cy="32" r="14" fill={colors.secondary} />
-      {/* Face */}
-      <circle cx="26" cy="30" r="4" fill="white" />
-      <circle cx="38" cy="30" r="4" fill="white" />
-      <circle cx="27" cy="31" r="2" fill="#1a1a1a" />
-      <circle cx="39" cy="31" r="2" fill="#1a1a1a" />
-      <path d="M28,40 Q32,43 36,40" stroke="#1a1a1a" strokeWidth="2" fill="none" strokeLinecap="round" />
-    </svg>
-  )
-}
-
-// Turbo - rocket character
-function TurboSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Turbo; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Flames */}
-      <ellipse cx="32" cy="58" rx="8" ry="6" fill="#FBBF24" className="animate-pulse" />
-      <ellipse cx="32" cy="56" rx="5" ry="4" fill="#FCD34D" />
-      {/* Rocket body */}
-      <ellipse cx="32" cy="32" rx="14" ry="24" fill={colors.primary} />
-      {/* Nose cone */}
-      <ellipse cx="32" cy="12" rx="8" ry="10" fill={colors.secondary} />
-      {/* Fins */}
-      <polygon points="18,44 10,56 18,52" fill={colors.secondary} />
-      <polygon points="46,44 54,56 46,52" fill={colors.secondary} />
-      {/* Window/Face */}
-      <circle cx="32" cy="28" r="8" fill={colors.accent} />
-      <circle cx="29" cy="27" r="2" fill="#1a1a1a" />
-      <circle cx="35" cy="27" r="2" fill="#1a1a1a" />
-      <path d="M29,32 Q32,34 35,32" stroke="#1a1a1a" strokeWidth="1" fill="none" />
-    </svg>
-  )
-}
-
-// Blip - radar dot character
-function BlipSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Blip; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Radar rings */}
-      <circle cx="32" cy="32" r="28" stroke={colors.accent} strokeWidth="2" fill="none" opacity="0.3" />
-      <circle cx="32" cy="32" r="22" stroke={colors.accent} strokeWidth="2" fill="none" opacity="0.5" />
-      {/* Main dot */}
-      <circle cx="32" cy="32" r="14" fill={colors.primary} />
-      <circle cx="32" cy="32" r="10" fill={colors.secondary} />
-      {/* Face */}
-      <circle cx="28" cy="30" r="3" fill="white" />
-      <circle cx="36" cy="30" r="3" fill="white" />
-      <circle cx="29" cy="31" r="1.5" fill="#1a1a1a" />
-      <circle cx="37" cy="31" r="1.5" fill="#1a1a1a" />
-      <path d="M29,37 Q32,40 35,37" stroke="white" strokeWidth="1.5" fill="none" strokeLinecap="round" />
-    </svg>
-  )
-}
-
-// Neon - glowing character
-function NeonSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Neon; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Glow effect */}
-      <circle cx="32" cy="32" r="26" fill={colors.accent} opacity="0.3" />
-      <circle cx="32" cy="32" r="22" fill={colors.accent} opacity="0.5" />
-      {/* Body */}
-      <circle cx="32" cy="32" r="18" fill={colors.primary} />
-      {/* Inner glow */}
-      <circle cx="32" cy="32" r="12" fill={colors.secondary} />
-      {/* Face */}
-      <circle cx="27" cy="30" r="4" fill="white" />
-      <circle cx="37" cy="30" r="4" fill="white" />
-      <circle cx="28" cy="31" r="2" fill={colors.primary} />
-      <circle cx="38" cy="31" r="2" fill={colors.primary} />
-      <path d="M28,38 Q32,42 36,38" stroke="white" strokeWidth="2" fill="none" strokeLinecap="round" />
-    </svg>
-  )
-}
-
-// Widget - UI component character
-function WidgetSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Widget; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Window frame */}
-      <rect x="8" y="12" width="48" height="40" rx="4" fill={colors.primary} />
-      {/* Title bar */}
-      <rect x="8" y="12" width="48" height="10" rx="4" fill={colors.secondary} />
-      <circle cx="16" cy="17" r="2" fill="#EF4444" />
-      <circle cx="24" cy="17" r="2" fill="#FBBF24" />
-      <circle cx="32" cy="17" r="2" fill="#22C55E" />
-      {/* Content area / Face */}
-      <rect x="12" y="26" width="40" height="22" rx="2" fill={colors.accent} />
-      <circle cx="24" cy="34" r="4" fill="white" />
-      <circle cx="40" cy="34" r="4" fill="white" />
-      <circle cx="25" cy="35" r="2" fill={colors.primary} />
-      <circle cx="41" cy="35" r="2" fill={colors.primary} />
-      <rect x="28" y="42" width="8" height="3" rx="1" fill={colors.primary} />
-    </svg>
-  )
-}
-
-// Zippy - fast bunny-like character
-function ZippySVG({ colors, size }: { colors: typeof AVATAR_COLORS.Zippy; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Ears */}
-      <ellipse cx="22" cy="14" rx="6" ry="14" fill={colors.primary} />
-      <ellipse cx="42" cy="14" rx="6" ry="14" fill={colors.primary} />
-      <ellipse cx="22" cy="14" rx="3" ry="10" fill={colors.accent} />
-      <ellipse cx="42" cy="14" rx="3" ry="10" fill={colors.accent} />
-      {/* Head */}
-      <circle cx="32" cy="38" r="20" fill={colors.primary} />
-      {/* Face */}
-      <circle cx="24" cy="34" r="5" fill="white" />
-      <circle cx="40" cy="34" r="5" fill="white" />
-      <circle cx="25" cy="35" r="2.5" fill="#1a1a1a" />
-      <circle cx="41" cy="35" r="2.5" fill="#1a1a1a" />
-      {/* Nose and mouth */}
-      <ellipse cx="32" cy="44" rx="3" ry="2" fill={colors.secondary} />
-      <path d="M32,46 L32,50 M28,52 Q32,56 36,52" stroke="#1a1a1a" strokeWidth="1.5" fill="none" />
-    </svg>
-  )
-}
-
-// Quirk - question mark character
-function QuirkSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Quirk; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Question mark body */}
-      <path d="M24,20 Q24,8 32,8 Q44,8 44,20 Q44,28 32,32 L32,40"
-            stroke={colors.primary} strokeWidth="8" fill="none" strokeLinecap="round" />
-      <circle cx="32" cy="52" r="6" fill={colors.primary} />
-      {/* Face on the dot */}
-      <circle cx="29" cy="51" r="1.5" fill="white" />
-      <circle cx="35" cy="51" r="1.5" fill="white" />
-      <circle cx="29" cy="51" r="0.75" fill="#1a1a1a" />
-      <circle cx="35" cy="51" r="0.75" fill="#1a1a1a" />
-      {/* Decorative swirl */}
-      <circle cx="32" cy="20" r="4" fill={colors.secondary} />
-    </svg>
-  )
-}
-
-// Flux - flowing wave character
-function FluxSVG({ colors, size }: { colors: typeof AVATAR_COLORS.Flux; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
-      {/* Wave body */}
-      <path d="M8,32 Q16,16 32,32 Q48,48 56,32" stroke={colors.primary} strokeWidth="16" fill="none" strokeLinecap="round" />
-      <path d="M8,32 Q16,16 32,32 Q48,48 56,32" stroke={colors.secondary} strokeWidth="10" fill="none" strokeLinecap="round" />
-      {/* Face */}
-      <circle cx="28" cy="28" r="4" fill="white" />
-      <circle cx="40" cy="36" r="4" fill="white" />
-      <circle cx="29" cy="29" r="2" fill="#1a1a1a" />
-      <circle cx="41" cy="37" r="2" fill="#1a1a1a" />
-      {/* Sparkles */}
-      <circle cx="16" cy="24" r="2" fill={colors.accent} className="animate-pulse" />
-      <circle cx="48" cy="40" r="2" fill={colors.accent} className="animate-pulse" />
-    </svg>
-  )
-}
-
-// Unknown agent fallback - simple question mark icon
-function UnknownSVG({ colors, size }: { colors: typeof UNKNOWN_COLORS; size: number }) {
-  return (
-    <svg width={size} height={size} viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg">
-      {/* Circle background */}
-      <circle cx="32" cy="32" r="28" fill={colors.primary} />
-      <circle cx="32" cy="32" r="24" fill={colors.secondary} />
-      {/* Question mark */}
-      <text x="32" y="44" textAnchor="middle" fontSize="32" fontWeight="bold" fill="white">?</text>
-    </svg>
-  )
-}
-
-const MASCOT_SVGS: Record<AgentMascot, typeof SparkSVG> = {
-  // Original 5
-  Spark: SparkSVG,
-  Fizz: FizzSVG,
-  Octo: OctoSVG,
-  Hoot: HootSVG,
-  Buzz: BuzzSVG,
-  // Tech-inspired
-  Pixel: PixelSVG,
-  Byte: ByteSVG,
-  Nova: NovaSVG,
-  Chip: ChipSVG,
-  Bolt: BoltSVG,
-  // Energetic
-  Dash: DashSVG,
-  Zap: ZapSVG,
-  Gizmo: GizmoSVG,
-  Turbo: TurboSVG,
-  Blip: BlipSVG,
-  // Playful
-  Neon: NeonSVG,
-  Widget: WidgetSVG,
-  Zippy: ZippySVG,
-  Quirk: QuirkSVG,
-  Flux: FluxSVG,
-}
-
 // Animation classes based on state
 function getStateAnimation(state: AgentState): string {
   switch (state) {
@@ -581,7 +84,7 @@ export function AgentAvatar({ name, state, size = 'md', showName = false }: Agen
   const isUnknown = name === 'Unknown'
   const colors = isUnknown ? UNKNOWN_COLORS : AVATAR_COLORS[name]
   const { svg: svgSize, font } = SIZES[size]
-  const SvgComponent = isUnknown ? UnknownSVG : MASCOT_SVGS[name]
+  const SvgComponent = isUnknown ? UnknownMascotSVG : MASCOT_SVGS[name]
   const stateDesc = getStateDescription(state)
   const ariaLabel = `Agent ${name} is ${stateDesc}`
 

ui/src/components/AgentCard.tsx

@@ -112,12 +112,25 @@ export function AgentCard({ agent, onShowLogs }: AgentCardProps) {
 
         {/* Feature info */}
         <div>
-          <div className="text-xs text-muted-foreground mb-0.5">
+          {agent.featureIds && agent.featureIds.length > 1 ? (
-            Feature #{agent.featureId}
+            <>
-          </div>
+              <div className="text-xs text-muted-foreground mb-0.5">
-          <div className="text-sm font-medium truncate" title={agent.featureName}>
+                Batch: {agent.featureIds.map(id => `#${id}`).join(', ')}
-            {agent.featureName}
+              </div>
-          </div>
+              <div className="text-sm font-bold truncate">
+                Active: Feature #{agent.featureId}
+              </div>
+            </>
+          ) : (
+            <>
+              <div className="text-xs text-muted-foreground mb-0.5">
+                Feature #{agent.featureId}
+              </div>
+              <div className="text-sm font-medium truncate" title={agent.featureName}>
+                {agent.featureName}
+              </div>
+            </>
+          )}
         </div>
 
         {/* Thought bubble */}
@@ -195,7 +208,10 @@ export function AgentLogModal({ agent, logs, onClose }: AgentLogModalProps) {
                 </Badge>
               </div>
               <p className="text-sm text-muted-foreground">
-                Feature #{agent.featureId}: {agent.featureName}
+                {agent.featureIds && agent.featureIds.length > 1
+                  ? `Batch: ${agent.featureIds.map(id => `#${id}`).join(', ')}`
+                  : `Feature #${agent.featureId}: ${agent.featureName}`
+                }
               </p>
             </div>
           </div>

ui/src/components/AgentControl.tsx

@@ -1,9 +1,10 @@
-import { useState } from 'react'
+import { useState, useEffect, useRef, useCallback } from 'react'
 import { Play, Square, Loader2, GitBranch, Clock } from 'lucide-react'
 import {
   useStartAgent,
   useStopAgent,
   useSettings,
+  useUpdateProjectSettings,
 } from '../hooks/useProjects'
 import { useNextScheduledRun } from '../hooks/useSchedules'
 import { formatNextRun, formatEndTime } from '../lib/timeUtils'
@@ -15,14 +16,47 @@ import { Badge } from '@/components/ui/badge'
 interface AgentControlProps {
   projectName: string
   status: AgentStatus
+  defaultConcurrency?: number
 }
 
-export function AgentControl({ projectName, status }: AgentControlProps) {
+export function AgentControl({ projectName, status, defaultConcurrency = 3 }: AgentControlProps) {
   const { data: settings } = useSettings()
   const yoloMode = settings?.yolo_mode ?? false
 
   // Concurrency: 1 = single agent, 2-5 = parallel
-  const [concurrency, setConcurrency] = useState(3)
+  const [concurrency, setConcurrency] = useState(defaultConcurrency)
+
+  // Sync concurrency when project changes or defaultConcurrency updates
+  useEffect(() => {
+    setConcurrency(defaultConcurrency)
+  }, [defaultConcurrency])
+
+  // Debounced save for concurrency changes
+  const updateProjectSettings = useUpdateProjectSettings(projectName)
+  const saveTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const handleConcurrencyChange = useCallback((newConcurrency: number) => {
+    setConcurrency(newConcurrency)
+
+    // Clear previous timeout
+    if (saveTimeoutRef.current) {
+      clearTimeout(saveTimeoutRef.current)
+    }
+
+    // Debounce save (500ms)
+    saveTimeoutRef.current = setTimeout(() => {
+      updateProjectSettings.mutate({ default_concurrency: newConcurrency })
+    }, 500)
+  }, [updateProjectSettings])
+
+  // Cleanup timeout on unmount
+  useEffect(() => {
+    return () => {
+      if (saveTimeoutRef.current) {
+        clearTimeout(saveTimeoutRef.current)
+      }
+    }
+  }, [])
 
   const startAgent = useStartAgent(projectName)
   const stopAgent = useStopAgent(projectName)
@@ -57,7 +91,7 @@ export function AgentControl({ projectName, status }: AgentControlProps) {
               min={1}
               max={5}
               value={concurrency}
-              onChange={(e) => setConcurrency(Number(e.target.value))}
+              onChange={(e) => handleConcurrencyChange(Number(e.target.value))}
               disabled={isLoading}
               className="w-16 h-2 accent-primary cursor-pointer"
               title={`${concurrency} concurrent agent${concurrency > 1 ? 's' : ''}`}

ui/src/components/AssistantChat.tsx

@@ -12,6 +12,7 @@ import { useAssistantChat } from '../hooks/useAssistantChat'
 import { ChatMessage as ChatMessageComponent } from './ChatMessage'
 import { ConversationHistory } from './ConversationHistory'
 import type { ChatMessage } from '../lib/types'
+import { isSubmitEnter } from '../lib/keyboard'
 import { Button } from '@/components/ui/button'
 import { Textarea } from '@/components/ui/textarea'
 
@@ -134,7 +135,7 @@ export function AssistantChat({
   }
 
   const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
-    if (e.key === 'Enter' && !e.shiftKey) {
+    if (isSubmitEnter(e)) {
       e.preventDefault()
       handleSend()
     }

ui/src/components/AssistantPanel.tsx

@@ -50,11 +50,23 @@ export function AssistantPanel({ projectName, isOpen, onClose }: AssistantPanelP
   )
 
   // Fetch conversation details when we have an ID
-  const { data: conversationDetail, isLoading: isLoadingConversation } = useConversation(
+  const { data: conversationDetail, isLoading: isLoadingConversation, error: conversationError } = useConversation(
     projectName,
     conversationId
   )
 
+  // Clear stored conversation ID if it no longer exists (404 error)
+  useEffect(() => {
+    if (conversationError && conversationId) {
+      const message = conversationError.message.toLowerCase()
+      // Only clear for 404 errors, not transient network issues
+      if (message.includes('not found') || message.includes('404')) {
+        console.warn(`Conversation ${conversationId} not found, clearing stored ID`)
+        setConversationId(null)
+      }
+    }
+  }, [conversationError, conversationId])
+
   // Convert API messages to ChatMessage format for the chat component
   const initialMessages: ChatMessage[] | undefined = conversationDetail?.messages.map((msg) => ({
     id: `db-${msg.id}`,

ui/src/components/ConversationHistory.tsx

@@ -168,7 +168,7 @@ export function ConversationHistory({
                     <Button
                       variant="ghost"
                       size="icon"
-                      onClick={(e) => handleDeleteClick(e, conversation)}
+                      onClick={(e: React.MouseEvent) => handleDeleteClick(e, conversation)}
                       className={`h-8 w-8 mr-2 ${
                         isCurrent
                           ? 'opacity-60 hover:opacity-100'

ui/src/components/DebugLogViewer.tsx

@@ -349,7 +349,7 @@ export function DebugLogViewer({
               <Button
                 variant={activeTab === 'agent' ? 'secondary' : 'ghost'}
                 size="sm"
-                onClick={(e) => {
+                onClick={(e: React.MouseEvent) => {
                   e.stopPropagation()
                   setActiveTab('agent')
                 }}
@@ -366,7 +366,7 @@ export function DebugLogViewer({
               <Button
                 variant={activeTab === 'devserver' ? 'secondary' : 'ghost'}
                 size="sm"
-                onClick={(e) => {
+                onClick={(e: React.MouseEvent) => {
                   e.stopPropagation()
                   setActiveTab('devserver')
                 }}
@@ -383,7 +383,7 @@ export function DebugLogViewer({
               <Button
                 variant={activeTab === 'terminal' ? 'secondary' : 'ghost'}
                 size="sm"
-                onClick={(e) => {
+                onClick={(e: React.MouseEvent) => {
                   e.stopPropagation()
                   setActiveTab('terminal')
                 }}
@@ -421,7 +421,7 @@ export function DebugLogViewer({
             <Button
               variant="ghost"
               size="icon"
-              onClick={(e) => {
+              onClick={(e: React.MouseEvent) => {
                 e.stopPropagation()
                 handleClear()
               }}

ui/src/components/DependencyGraph.tsx

@@ -227,10 +227,14 @@ function DependencyGraphInner({ graphData, onNodeClick, activeAgents = [] }: Dep
   }, [])
 
   // Create a map of featureId to agent info for quick lookup
+  // Maps ALL batch feature IDs to the same agent
   const agentByFeatureId = useMemo(() => {
     const map = new Map<number, NodeAgentInfo>()
     for (const agent of activeAgents) {
-      map.set(agent.featureId, { name: agent.agentName, state: agent.state })
+      const ids = agent.featureIds || [agent.featureId]
+      for (const fid of ids) {
+        map.set(fid, { name: agent.agentName, state: agent.state })
+      }
     }
     return map
   }, [activeAgents])

ui/src/components/ExpandProjectChat.tsx

@@ -11,6 +11,7 @@ import { useExpandChat } from '../hooks/useExpandChat'
 import { ChatMessage } from './ChatMessage'
 import { TypingIndicator } from './TypingIndicator'
 import type { ImageAttachment } from '../lib/types'
+import { isSubmitEnter } from '../lib/keyboard'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 import { Card, CardContent } from '@/components/ui/card'
@@ -88,7 +89,7 @@ export function ExpandProjectChat({
   }
 
   const handleKeyDown = (e: React.KeyboardEvent) => {
-    if (e.key === 'Enter' && !e.shiftKey) {
+    if (isSubmitEnter(e)) {
       e.preventDefault()
       handleSendMessage()
     }

ui/src/components/FolderBrowser.tsx

@@ -18,6 +18,7 @@ import {
   ArrowLeft,
 } from 'lucide-react'
 import * as api from '../lib/api'
+import { isSubmitEnter } from '../lib/keyboard'
 import type { DirectoryEntry, DriveInfo } from '../lib/types'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
@@ -269,7 +270,7 @@ export function FolderBrowser({ onSelect, onCancel, initialPath }: FolderBrowser
                     className="flex-1"
                     autoFocus
                     onKeyDown={(e) => {
-                      if (e.key === 'Enter') handleCreateFolder()
+                      if (isSubmitEnter(e, false)) handleCreateFolder()
                       if (e.key === 'Escape') {
                         setIsCreatingFolder(false)
                         setNewFolderName('')

ui/src/components/KanbanColumn.tsx

@@ -41,9 +41,14 @@ export function KanbanColumn({
   showCreateSpec,
 }: KanbanColumnProps) {
   // Create a map of feature ID to active agent for quick lookup
-  const agentByFeatureId = new Map(
+  // Maps ALL batch feature IDs to the same agent
-    activeAgents.map(agent => [agent.featureId, agent])
+  const agentByFeatureId = new Map<number, ActiveAgent>()
-  )
+  for (const agent of activeAgents) {
+    const ids = agent.featureIds || [agent.featureId]
+    for (const fid of ids) {
+      agentByFeatureId.set(fid, agent)
+    }
+  }
 
   return (
     <Card className={`overflow-hidden ${colorMap[color]} py-0`}>

ui/src/components/NewProjectModal.tsx

@@ -10,6 +10,7 @@
  */
 
 import { useState } from 'react'
+import { createPortal } from 'react-dom'
 import { Bot, FileEdit, ArrowRight, ArrowLeft, Loader2, CheckCircle2, Folder } from 'lucide-react'
 import { useCreateProject } from '../hooks/useProjects'
 import { SpecCreationChat } from './SpecCreationChat'
@@ -200,10 +201,10 @@ export function NewProjectModal({
     }
   }
 
-  // Full-screen chat view
+  // Full-screen chat view - use portal to render at body level
   if (step === 'chat') {
-    return (
+    return createPortal(
-      <div className="fixed inset-0 z-50 bg-background">
+      <div className="fixed inset-0 z-50 bg-background flex flex-col">
         <SpecCreationChat
           projectName={projectName.trim()}
           onComplete={handleSpecComplete}
@@ -213,7 +214,8 @@ export function NewProjectModal({
           initializerError={initializerError}
           onRetryInitializer={handleRetryInitializer}
         />
-      </div>
+      </div>,
+      document.body
     )
   }
 

ui/src/components/OrchestratorStatusCard.tsx

@@ -36,7 +36,7 @@ function getStateColor(state: OrchestratorState): string {
     case 'complete':
       return 'text-primary'
     case 'spawning':
-      return 'text-violet-600 dark:text-violet-400'
+      return 'text-primary'
     case 'scheduling':
     case 'monitoring':
       return 'text-primary'
@@ -65,7 +65,7 @@ export function OrchestratorStatusCard({ status }: OrchestratorStatusCardProps)
   const [showEvents, setShowEvents] = useState(false)
 
   return (
-    <Card className="mb-4 bg-gradient-to-r from-violet-50 to-purple-50 dark:from-violet-950/30 dark:to-purple-950/30 border-violet-200 dark:border-violet-800/50 py-4">
+    <Card className="mb-4 bg-primary/10 border-primary/30 py-4">
       <CardContent className="p-4">
         <div className="flex items-start gap-4">
           {/* Avatar */}
@@ -75,7 +75,7 @@ export function OrchestratorStatusCard({ status }: OrchestratorStatusCardProps)
           <div className="flex-1 min-w-0">
             {/* Header row */}
             <div className="flex items-center gap-2 mb-1">
-              <span className="font-semibold text-lg text-violet-700 dark:text-violet-300">
+              <span className="font-semibold text-lg text-primary">
                 Maestro
               </span>
               <span className={`text-sm font-medium ${getStateColor(status.state)}`}>
@@ -124,7 +124,7 @@ export function OrchestratorStatusCard({ status }: OrchestratorStatusCardProps)
               variant="ghost"
               size="sm"
               onClick={() => setShowEvents(!showEvents)}
-              className="text-violet-600 dark:text-violet-400 hover:bg-violet-100 dark:hover:bg-violet-900/30"
+              className="text-primary hover:bg-primary/10"
             >
               <Sparkles size={12} />
               Activity
@@ -135,14 +135,14 @@ export function OrchestratorStatusCard({ status }: OrchestratorStatusCardProps)
 
         {/* Collapsible recent events */}
         {showEvents && status.recentEvents.length > 0 && (
-          <div className="mt-3 pt-3 border-t border-violet-200 dark:border-violet-800/50">
+          <div className="mt-3 pt-3 border-t border-primary/20">
             <div className="space-y-1.5">
               {status.recentEvents.map((event, idx) => (
                 <div
                   key={`${event.timestamp}-${idx}`}
                   className="flex items-start gap-2 text-xs"
                 >
-                  <span className="text-violet-500 dark:text-violet-400 shrink-0 font-mono">
+                  <span className="text-primary shrink-0 font-mono">
                     {formatRelativeTime(event.timestamp)}
                   </span>
                   <span className="text-foreground">

ui/src/components/ProgressDashboard.tsx

@@ -1,12 +1,40 @@
-import { Wifi, WifiOff } from 'lucide-react'
+import { useMemo, useState, useEffect } from 'react'
+import { Wifi, WifiOff, Brain, Sparkles } from 'lucide-react'
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
 import { Badge } from '@/components/ui/badge'
+import type { AgentStatus } from '../lib/types'
 
 interface ProgressDashboardProps {
   passing: number
   total: number
   percentage: number
   isConnected: boolean
+  logs?: Array<{ line: string; timestamp: string }>
+  agentStatus?: AgentStatus
+}
+
+const IDLE_TIMEOUT = 30000
+
+function isAgentThought(line: string): boolean {
+  const trimmed = line.trim()
+  if (/^\[Tool:/.test(trimmed)) return false
+  if (/^\s*Input:\s*\{/.test(trimmed)) return false
+  if (/^\[(Done|Error)\]/.test(trimmed)) return false
+  if (/^Output:/.test(trimmed)) return false
+  if (/^[[{]/.test(trimmed)) return false
+  if (trimmed.length < 10) return false
+  if (/^[A-Za-z]:\\/.test(trimmed)) return false
+  if (/^\/[a-z]/.test(trimmed)) return false
+  return true
+}
+
+function getLatestThought(logs: Array<{ line: string; timestamp: string }>): string | null {
+  for (let i = logs.length - 1; i >= 0; i--) {
+    if (isAgentThought(logs[i].line)) {
+      return logs[i].line.trim()
+    }
+  }
+  return null
 }
 
 export function ProgressDashboard({
@@ -14,67 +42,109 @@ export function ProgressDashboard({
   total,
   percentage,
   isConnected,
+  logs = [],
+  agentStatus,
 }: ProgressDashboardProps) {
+  const thought = useMemo(() => getLatestThought(logs), [logs])
+  const [displayedThought, setDisplayedThought] = useState<string | null>(null)
+  const [textVisible, setTextVisible] = useState(true)
+
+  const lastLogTimestamp = logs.length > 0
+    ? new Date(logs[logs.length - 1].timestamp).getTime()
+    : 0
+
+  const showThought = useMemo(() => {
+    if (!thought) return false
+    if (agentStatus === 'running') return true
+    if (agentStatus === 'paused') {
+      return Date.now() - lastLogTimestamp < IDLE_TIMEOUT
+    }
+    return false
+  }, [thought, agentStatus, lastLogTimestamp])
+
+  useEffect(() => {
+    if (thought !== displayedThought && thought) {
+      setTextVisible(false)
+      const timeout = setTimeout(() => {
+        setDisplayedThought(thought)
+        setTextVisible(true)
+      }, 150)
+      return () => clearTimeout(timeout)
+    }
+  }, [thought, displayedThought])
+
+  const isRunning = agentStatus === 'running'
+
   return (
     <Card>
-      <CardHeader className="flex-row items-center justify-between space-y-0 pb-4">
+      <CardHeader className="flex-row items-center justify-between space-y-0 pb-0">
-        <CardTitle className="text-xl uppercase tracking-wide">
+        <div className="flex items-center gap-3">
-          Progress
+          <CardTitle className="text-xl uppercase tracking-wide">
-        </CardTitle>
+            Progress
-        <Badge variant={isConnected ? 'default' : 'destructive'} className="gap-1">
+          </CardTitle>
-          {isConnected ? (
+          <Badge variant={isConnected ? 'default' : 'destructive'} className="gap-1">
-            <>
+            {isConnected ? (
-              <Wifi size={14} />
+              <>
-              Live
+                <Wifi size={14} />
-            </>
+                Live
-          ) : (
+              </>
-            <>
+            ) : (
-              <WifiOff size={14} />
+              <>
-              Offline
+                <WifiOff size={14} />
-            </>
+                Offline
-          )}
+              </>
-        </Badge>
+            )}
+          </Badge>
+        </div>
+        <div className="flex items-baseline gap-1">
+          <span className="font-mono text-lg font-bold text-primary">
+            {passing}
+          </span>
+          <span className="text-sm text-muted-foreground">/</span>
+          <span className="font-mono text-lg font-bold">
+            {total}
+          </span>
+        </div>
       </CardHeader>
 
-      <CardContent>
+      <CardContent className="pt-3 pb-3">
-        {/* Large Percentage */}
+        <div className="flex items-center gap-4">
-        <div className="text-center mb-6">
+          {/* Progress Bar */}
-          <span className="inline-flex items-baseline">
+          <div className="h-2.5 bg-muted rounded-full overflow-hidden flex-1">
-            <span className="text-6xl font-bold tabular-nums">
+            <div
-              {percentage.toFixed(1)}
+              className="h-full bg-primary rounded-full transition-all duration-500 ease-out"
-            </span>
+              style={{ width: `${percentage}%` }}
-            <span className="text-3xl font-semibold text-muted-foreground">
+            />
-              %
+          </div>
-            </span>
+          {/* Percentage */}
+          <span className="text-sm font-bold tabular-nums text-muted-foreground w-12 text-right">
+            {percentage.toFixed(1)}%
           </span>
         </div>
 
-        {/* Progress Bar */}
+        {/* Agent Thought */}
-        <div className="h-3 bg-muted rounded-full overflow-hidden mb-6">
+        <div
-          <div
+          className={`
-            className="h-full bg-primary rounded-full transition-all duration-500 ease-out"
+            transition-all duration-300 ease-out overflow-hidden
-            style={{ width: `${percentage}%` }}
+            ${showThought && displayedThought ? 'opacity-100 max-h-10 mt-3' : 'opacity-0 max-h-0 mt-0'}
-          />
+          `}
-        </div>
+        >
-
+          <div className="flex items-center gap-2">
-        {/* Stats */}
+            <div className="relative shrink-0">
-        <div className="flex justify-center gap-8 text-center">
+              <Brain size={16} className="text-primary" strokeWidth={2.5} />
-          <div>
+              {isRunning && (
-            <span className="font-mono text-3xl font-bold text-primary">
+                <Sparkles size={8} className="absolute -top-1 -right-1 text-yellow-500 animate-pulse" />
-              {passing}
+              )}
-            </span>
+            </div>
-            <span className="block text-sm text-muted-foreground uppercase">
+            <p
-              Passing
+              className="font-mono text-sm truncate text-muted-foreground transition-all duration-150 ease-out"
-            </span>
+              style={{
-          </div>
+                opacity: textVisible ? 1 : 0,
-          <div className="text-4xl text-muted-foreground">/</div>
+                transform: textVisible ? 'translateY(0)' : 'translateY(-4px)',
-          <div>
+              }}
-            <span className="font-mono text-3xl font-bold">
+            >
-              {total}
+              {displayedThought?.replace(/:$/, '')}
-            </span>
+            </p>
-            <span className="block text-sm text-muted-foreground uppercase">
-              Total
-            </span>
           </div>
         </div>
       </CardContent>

ui/src/components/ProjectSelector.tsx

@@ -120,7 +120,7 @@ export function ProjectSelector({
                   <Button
                     variant="ghost"
                     size="icon-xs"
-                    onClick={(e) => handleDeleteClick(e, project.name)}
+                    onClick={(e: React.MouseEvent) => handleDeleteClick(e, project.name)}
                     className="text-muted-foreground hover:text-destructive"
                   >
                     <Trash2 size={14} />

ui/src/components/ProjectSetupRequired.tsx

@@ -0,0 +1,90 @@
+import { Sparkles, FileEdit, FolderOpen } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
+
+interface ProjectSetupRequiredProps {
+  projectName: string
+  projectPath?: string
+  onCreateWithClaude: () => void
+  onEditManually: () => void
+}
+
+export function ProjectSetupRequired({
+  projectName,
+  projectPath,
+  onCreateWithClaude,
+  onEditManually,
+}: ProjectSetupRequiredProps) {
+  return (
+    <div className="max-w-2xl mx-auto mt-8">
+      <Card className="border-2">
+        <CardHeader className="text-center">
+          <CardTitle className="text-2xl font-display">
+            Project Setup Required
+          </CardTitle>
+          <CardDescription className="text-base">
+            <span className="font-semibold">{projectName}</span> needs an app spec to get started
+          </CardDescription>
+          {projectPath && (
+            <div className="flex items-center justify-center gap-2 text-sm text-muted-foreground mt-2">
+              <FolderOpen size={14} />
+              <code className="bg-muted px-2 py-0.5 rounded text-xs">{projectPath}</code>
+            </div>
+          )}
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <p className="text-center text-muted-foreground">
+            Choose how you want to create your app specification:
+          </p>
+
+          <div className="grid gap-4 md:grid-cols-2">
+            {/* Create with Claude Option */}
+            <Card
+              className="cursor-pointer border-2 transition-all hover:border-primary hover:shadow-md"
+              onClick={onCreateWithClaude}
+            >
+              <CardContent className="pt-6 text-center space-y-3">
+                <div className="w-12 h-12 mx-auto bg-primary/10 rounded-full flex items-center justify-center">
+                  <Sparkles className="text-primary" size={24} />
+                </div>
+                <h3 className="font-semibold text-lg">Create with Claude</h3>
+                <p className="text-sm text-muted-foreground">
+                  Describe your app idea and Claude will help create a detailed specification
+                </p>
+                <Button className="w-full">
+                  <Sparkles size={16} className="mr-2" />
+                  Start Chat
+                </Button>
+              </CardContent>
+            </Card>
+
+            {/* Edit Manually Option */}
+            <Card
+              className="cursor-pointer border-2 transition-all hover:border-primary hover:shadow-md"
+              onClick={onEditManually}
+            >
+              <CardContent className="pt-6 text-center space-y-3">
+                <div className="w-12 h-12 mx-auto bg-muted rounded-full flex items-center justify-center">
+                  <FileEdit className="text-muted-foreground" size={24} />
+                </div>
+                <h3 className="font-semibold text-lg">Edit Templates Manually</h3>
+                <p className="text-sm text-muted-foreground">
+                  Create the prompts directory and edit template files yourself
+                </p>
+                <Button variant="outline" className="w-full">
+                  <FileEdit size={16} className="mr-2" />
+                  View Templates
+                </Button>
+              </CardContent>
+            </Card>
+          </div>
+
+          <p className="text-center text-xs text-muted-foreground pt-4">
+            The app spec tells the agent what to build. It includes the application name,
+            description, tech stack, and feature requirements.
+          </p>
+        </CardContent>
+      </Card>
+    </div>
+  )
+}

ui/src/components/ResetProjectModal.tsx

@@ -0,0 +1,194 @@
+import { useState } from 'react'
+import { Loader2, AlertTriangle, RotateCcw, Trash2, Check, X } from 'lucide-react'
+import { useResetProject } from '../hooks/useProjects'
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogFooter,
+} from '@/components/ui/dialog'
+import { Button } from '@/components/ui/button'
+import { Alert, AlertDescription } from '@/components/ui/alert'
+
+interface ResetProjectModalProps {
+  isOpen: boolean
+  projectName: string
+  onClose: () => void
+  onResetComplete?: (wasFullReset: boolean) => void
+}
+
+export function ResetProjectModal({
+  isOpen,
+  projectName,
+  onClose,
+  onResetComplete,
+}: ResetProjectModalProps) {
+  const [resetType, setResetType] = useState<'quick' | 'full'>('quick')
+  const resetProject = useResetProject(projectName)
+
+  const handleReset = async () => {
+    const isFullReset = resetType === 'full'
+    try {
+      await resetProject.mutateAsync(isFullReset)
+      onResetComplete?.(isFullReset)
+      onClose()
+    } catch {
+      // Error is handled by the mutation state
+    }
+  }
+
+  const handleClose = () => {
+    if (!resetProject.isPending) {
+      resetProject.reset()
+      setResetType('quick')
+      onClose()
+    }
+  }
+
+  return (
+    <Dialog open={isOpen} onOpenChange={(open) => !open && handleClose()}>
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            <RotateCcw size={20} />
+            Reset Project
+          </DialogTitle>
+          <DialogDescription>
+            Reset <span className="font-semibold">{projectName}</span> to start fresh
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-4 py-4">
+          {/* Reset Type Toggle */}
+          <div className="flex rounded-lg border-2 border-border overflow-hidden">
+            <button
+              onClick={() => setResetType('quick')}
+              disabled={resetProject.isPending}
+              className={`flex-1 py-3 px-4 text-sm font-medium transition-colors flex items-center justify-center gap-2 ${
+                resetType === 'quick'
+                  ? 'bg-primary text-primary-foreground'
+                  : 'bg-background text-foreground hover:bg-muted'
+              } ${resetProject.isPending ? 'opacity-50 cursor-not-allowed' : ''}`}
+            >
+              <RotateCcw size={16} />
+              Quick Reset
+            </button>
+            <button
+              onClick={() => setResetType('full')}
+              disabled={resetProject.isPending}
+              className={`flex-1 py-3 px-4 text-sm font-medium transition-colors flex items-center justify-center gap-2 ${
+                resetType === 'full'
+                  ? 'bg-destructive text-destructive-foreground'
+                  : 'bg-background text-foreground hover:bg-muted'
+              } ${resetProject.isPending ? 'opacity-50 cursor-not-allowed' : ''}`}
+            >
+              <Trash2 size={16} />
+              Full Reset
+            </button>
+          </div>
+
+          {/* Warning Box */}
+          <Alert variant={resetType === 'full' ? 'destructive' : 'default'} className="border-2">
+            <AlertTriangle className="h-4 w-4" />
+            <AlertDescription>
+              <div className="font-semibold mb-2">
+                {resetType === 'quick' ? 'What will be deleted:' : 'What will be deleted:'}
+              </div>
+              <ul className="list-none space-y-1 text-sm">
+                <li className="flex items-center gap-2">
+                  <X size={14} className="text-destructive" />
+                  All features and progress
+                </li>
+                <li className="flex items-center gap-2">
+                  <X size={14} className="text-destructive" />
+                  Assistant chat history
+                </li>
+                <li className="flex items-center gap-2">
+                  <X size={14} className="text-destructive" />
+                  Agent settings
+                </li>
+                {resetType === 'full' && (
+                  <li className="flex items-center gap-2">
+                    <X size={14} className="text-destructive" />
+                    App spec and prompts
+                  </li>
+                )}
+              </ul>
+            </AlertDescription>
+          </Alert>
+
+          {/* What will be preserved */}
+          <div className="bg-muted/50 rounded-lg border-2 border-border p-3">
+            <div className="font-semibold mb-2 text-sm">
+              {resetType === 'quick' ? 'What will be preserved:' : 'What will be preserved:'}
+            </div>
+            <ul className="list-none space-y-1 text-sm text-muted-foreground">
+              {resetType === 'quick' ? (
+                <>
+                  <li className="flex items-center gap-2">
+                    <Check size={14} className="text-green-600" />
+                    App spec and prompts
+                  </li>
+                  <li className="flex items-center gap-2">
+                    <Check size={14} className="text-green-600" />
+                    Project code and files
+                  </li>
+                </>
+              ) : (
+                <>
+                  <li className="flex items-center gap-2">
+                    <Check size={14} className="text-green-600" />
+                    Project code and files
+                  </li>
+                  <li className="flex items-center gap-2 text-muted-foreground/70">
+                    <AlertTriangle size={14} />
+                    Setup wizard will appear
+                  </li>
+                </>
+              )}
+            </ul>
+          </div>
+
+          {/* Error Message */}
+          {resetProject.isError && (
+            <Alert variant="destructive">
+              <AlertDescription>
+                {resetProject.error instanceof Error
+                  ? resetProject.error.message
+                  : 'Failed to reset project. Please try again.'}
+              </AlertDescription>
+            </Alert>
+          )}
+        </div>
+
+        <DialogFooter className="gap-2">
+          <Button
+            variant="outline"
+            onClick={handleClose}
+            disabled={resetProject.isPending}
+          >
+            Cancel
+          </Button>
+          <Button
+            variant={resetType === 'full' ? 'destructive' : 'default'}
+            onClick={handleReset}
+            disabled={resetProject.isPending}
+          >
+            {resetProject.isPending ? (
+              <>
+                <Loader2 className="animate-spin mr-2" size={16} />
+                Resetting...
+              </>
+            ) : (
+              <>
+                {resetType === 'quick' ? 'Quick Reset' : 'Full Reset'}
+              </>
+            )}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}

ui/src/components/ScheduleModal.tsx

@@ -335,7 +335,7 @@ export function ScheduleModal({ projectName, isOpen, onClose }: ScheduleModalPro
               <Checkbox
                 id="yolo-mode"
                 checked={newSchedule.yolo_mode}
-                onCheckedChange={(checked) =>
+                onCheckedChange={(checked: boolean | 'indeterminate') =>
                   setNewSchedule((prev) => ({ ...prev, yolo_mode: checked === true }))
                 }
               />

ui/src/components/SettingsModal.tsx

@@ -41,6 +41,12 @@ export function SettingsModal({ isOpen, onClose }: SettingsModalProps) {
     }
   }
 
+  const handleBatchSizeChange = (size: number) => {
+    if (!updateSettings.isPending) {
+      updateSettings.mutate({ batch_size: size })
+    }
+  }
+
   const models = modelsData?.models ?? []
   const isSaving = updateSettings.isPending
 
@@ -171,6 +177,24 @@ export function SettingsModal({ isOpen, onClose }: SettingsModalProps) {
               />
             </div>
 
+            {/* Headless Browser Toggle */}
+            <div className="flex items-center justify-between">
+              <div className="space-y-0.5">
+                <Label htmlFor="playwright-headless" className="font-medium">
+                  Headless Browser
+                </Label>
+                <p className="text-sm text-muted-foreground">
+                  Run browser without visible window (saves CPU)
+                </p>
+              </div>
+              <Switch
+                id="playwright-headless"
+                checked={settings.playwright_headless}
+                onCheckedChange={() => updateSettings.mutate({ playwright_headless: !settings.playwright_headless })}
+                disabled={isSaving}
+              />
+            </div>
+
             {/* Model Selection */}
             <div className="space-y-2">
               <Label className="font-medium">Model</Label>
@@ -216,6 +240,30 @@ export function SettingsModal({ isOpen, onClose }: SettingsModalProps) {
               </div>
             </div>
 
+            {/* Features per Agent */}
+            <div className="space-y-2">
+              <Label className="font-medium">Features per Agent</Label>
+              <p className="text-sm text-muted-foreground">
+                Number of features assigned to each coding agent
+              </p>
+              <div className="flex rounded-lg border overflow-hidden">
+                {[1, 2, 3].map((size) => (
+                  <button
+                    key={size}
+                    onClick={() => handleBatchSizeChange(size)}
+                    disabled={isSaving}
+                    className={`flex-1 py-2 px-3 text-sm font-medium transition-colors ${
+                      (settings.batch_size ?? 1) === size
+                        ? 'bg-primary text-primary-foreground'
+                        : 'bg-background text-foreground hover:bg-muted'
+                    } ${isSaving ? 'opacity-50 cursor-not-allowed' : ''}`}
+                  >
+                    {size}
+                  </button>
+                ))}
+              </div>
+            </div>
+
             {/* Update Error */}
             {updateSettings.isError && (
               <Alert variant="destructive">

ui/src/components/SpecCreationChat.tsx

@@ -12,6 +12,7 @@ import { ChatMessage } from './ChatMessage'
 import { QuestionOptions } from './QuestionOptions'
 import { TypingIndicator } from './TypingIndicator'
 import type { ImageAttachment } from '../lib/types'
+import { isSubmitEnter } from '../lib/keyboard'
 import { Button } from '@/components/ui/button'
 import { Textarea } from '@/components/ui/textarea'
 import { Card, CardContent } from '@/components/ui/card'
@@ -127,7 +128,7 @@ export function SpecCreationChat({
   }
 
   const handleKeyDown = (e: React.KeyboardEvent) => {
-    if (e.key === 'Enter' && !e.shiftKey) {
+    if (isSubmitEnter(e)) {
       e.preventDefault()
       handleSendMessage()
     }
@@ -227,7 +228,7 @@ export function SpecCreationChat({
   }
 
   return (
-    <div className="flex flex-col h-full bg-background">
+    <div className="flex flex-col h-screen bg-background">
       {/* Header */}
       <div className="flex items-center justify-between p-4 border-b-2 border-border bg-card">
         <div className="flex items-center gap-3">
@@ -302,7 +303,7 @@ export function SpecCreationChat({
       )}
 
       {/* Messages area */}
-      <div className="flex-1 overflow-y-auto py-4">
+      <div className="flex-1 overflow-y-auto py-4 min-h-0">
         {messages.length === 0 && !isLoading && (
           <div className="flex flex-col items-center justify-center h-full text-center p-8">
             <Card className="p-6 max-w-md">
@@ -450,9 +451,8 @@ export function SpecCreationChat({
 
       {/* Completion footer */}
       {isComplete && (
-        <div className={`p-4 border-t-2 border-border ${
+        <div className={`p-4 border-t-2 border-border ${initializerStatus === 'error' ? 'bg-destructive' : 'bg-green-500'
-          initializerStatus === 'error' ? 'bg-destructive' : 'bg-green-500'
+          }`}>
-        }`}>
           <div className="flex items-center justify-between">
             <div className="flex items-center gap-2">
               {initializerStatus === 'starting' ? (

ui/src/components/TerminalTabs.tsx

@@ -8,6 +8,7 @@
 import { useState, useRef, useEffect, useCallback } from 'react'
 import { Plus, X } from 'lucide-react'
 import type { TerminalInfo } from '@/lib/types'
+import { isSubmitEnter } from '@/lib/keyboard'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
 
@@ -96,7 +97,7 @@ export function TerminalTabs({
   // Handle key events during editing
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
-      if (e.key === 'Enter') {
+      if (isSubmitEnter(e, false)) {
         e.preventDefault()
         submitEdit()
       } else if (e.key === 'Escape') {

ui/src/components/ThemeSelector.tsx

@@ -13,7 +13,7 @@ export function ThemeSelector({ themes, currentTheme, onThemeChange }: ThemeSele
   const [isOpen, setIsOpen] = useState(false)
   const [previewTheme, setPreviewTheme] = useState<ThemeId | null>(null)
   const containerRef = useRef<HTMLDivElement>(null)
-  const timeoutRef = useRef<NodeJS.Timeout | null>(null)
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
 
   // Close dropdown when clicking outside
   useEffect(() => {
@@ -32,7 +32,7 @@ export function ThemeSelector({ themes, currentTheme, onThemeChange }: ThemeSele
   useEffect(() => {
     if (previewTheme) {
       const root = document.documentElement
-      root.classList.remove('theme-claude', 'theme-neo-brutalism', 'theme-retro-arcade', 'theme-aurora')
+      root.classList.remove('theme-claude', 'theme-neo-brutalism', 'theme-retro-arcade', 'theme-aurora', 'theme-business')
       if (previewTheme === 'claude') {
         root.classList.add('theme-claude')
       } else if (previewTheme === 'neo-brutalism') {
@@ -41,6 +41,8 @@ export function ThemeSelector({ themes, currentTheme, onThemeChange }: ThemeSele
         root.classList.add('theme-retro-arcade')
       } else if (previewTheme === 'aurora') {
         root.classList.add('theme-aurora')
+      } else if (previewTheme === 'business') {
+        root.classList.add('theme-business')
       }
     }
 
@@ -48,7 +50,7 @@ export function ThemeSelector({ themes, currentTheme, onThemeChange }: ThemeSele
     return () => {
       if (previewTheme) {
         const root = document.documentElement
-        root.classList.remove('theme-claude', 'theme-neo-brutalism', 'theme-retro-arcade', 'theme-aurora')
+        root.classList.remove('theme-claude', 'theme-neo-brutalism', 'theme-retro-arcade', 'theme-aurora', 'theme-business')
         if (currentTheme === 'claude') {
           root.classList.add('theme-claude')
         } else if (currentTheme === 'neo-brutalism') {
@@ -57,6 +59,8 @@ export function ThemeSelector({ themes, currentTheme, onThemeChange }: ThemeSele
           root.classList.add('theme-retro-arcade')
         } else if (currentTheme === 'aurora') {
           root.classList.add('theme-aurora')
+        } else if (currentTheme === 'business') {
+          root.classList.add('theme-business')
         }
       }
     }

ui/src/components/mascotData.tsx

@@ -0,0 +1,529 @@
+/**
+ * SVG mascot definitions and color palettes for agent avatars.
+ *
+ * Each mascot is a simple, cute SVG character rendered as a React component.
+ * Colors are keyed by AgentMascot name so avatars stay visually distinct
+ * when multiple agents run in parallel.
+ */
+
+import type { AgentMascot } from '../lib/types'
+
+// ---------------------------------------------------------------------------
+// Color types and palettes
+// ---------------------------------------------------------------------------
+
+export interface MascotColorPalette {
+  primary: string
+  secondary: string
+  accent: string
+}
+
+/** Props shared by every mascot SVG component. */
+export interface MascotSVGProps {
+  colors: MascotColorPalette
+  size: number
+}
+
+/** Fallback colors for unknown / untracked agents (neutral gray). */
+export const UNKNOWN_COLORS: MascotColorPalette = {
+  primary: '#6B7280',
+  secondary: '#9CA3AF',
+  accent: '#F3F4F6',
+}
+
+export const AVATAR_COLORS: Record<AgentMascot, MascotColorPalette> = {
+  // Original 5
+  Spark: { primary: '#3B82F6', secondary: '#60A5FA', accent: '#DBEAFE' },  // Blue robot
+  Fizz: { primary: '#F97316', secondary: '#FB923C', accent: '#FFEDD5' },   // Orange fox
+  Octo: { primary: '#8B5CF6', secondary: '#A78BFA', accent: '#EDE9FE' },   // Purple octopus
+  Hoot: { primary: '#22C55E', secondary: '#4ADE80', accent: '#DCFCE7' },   // Green owl
+  Buzz: { primary: '#EAB308', secondary: '#FACC15', accent: '#FEF9C3' },   // Yellow bee
+  // Tech-inspired
+  Pixel: { primary: '#EC4899', secondary: '#F472B6', accent: '#FCE7F3' },  // Pink
+  Byte: { primary: '#06B6D4', secondary: '#22D3EE', accent: '#CFFAFE' },   // Cyan
+  Nova: { primary: '#F43F5E', secondary: '#FB7185', accent: '#FFE4E6' },   // Rose
+  Chip: { primary: '#84CC16', secondary: '#A3E635', accent: '#ECFCCB' },   // Lime
+  Bolt: { primary: '#FBBF24', secondary: '#FCD34D', accent: '#FEF3C7' },   // Amber
+  // Energetic
+  Dash: { primary: '#14B8A6', secondary: '#2DD4BF', accent: '#CCFBF1' },   // Teal
+  Zap: { primary: '#A855F7', secondary: '#C084FC', accent: '#F3E8FF' },    // Violet
+  Gizmo: { primary: '#64748B', secondary: '#94A3B8', accent: '#F1F5F9' },  // Slate
+  Turbo: { primary: '#EF4444', secondary: '#F87171', accent: '#FEE2E2' },  // Red
+  Blip: { primary: '#10B981', secondary: '#34D399', accent: '#D1FAE5' },   // Emerald
+  // Playful
+  Neon: { primary: '#D946EF', secondary: '#E879F9', accent: '#FAE8FF' },   // Fuchsia
+  Widget: { primary: '#6366F1', secondary: '#818CF8', accent: '#E0E7FF' }, // Indigo
+  Zippy: { primary: '#F59E0B', secondary: '#FBBF24', accent: '#FEF3C7' },  // Orange-yellow
+  Quirk: { primary: '#0EA5E9', secondary: '#38BDF8', accent: '#E0F2FE' },  // Sky
+  Flux: { primary: '#7C3AED', secondary: '#8B5CF6', accent: '#EDE9FE' },   // Purple
+}
+
+// ---------------------------------------------------------------------------
+// SVG mascot components - simple cute characters
+// ---------------------------------------------------------------------------
+
+function SparkSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Robot body */}
+      <rect x="16" y="20" width="32" height="28" rx="4" fill={colors.primary} />
+      {/* Robot head */}
+      <rect x="12" y="8" width="40" height="24" rx="4" fill={colors.secondary} />
+      {/* Antenna */}
+      <circle cx="32" cy="4" r="4" fill={colors.primary} className="animate-pulse" />
+      <rect x="30" y="4" width="4" height="8" fill={colors.primary} />
+      {/* Eyes */}
+      <circle cx="24" cy="18" r="4" fill="white" />
+      <circle cx="40" cy="18" r="4" fill="white" />
+      <circle cx="25" cy="18" r="2" fill={colors.primary} />
+      <circle cx="41" cy="18" r="2" fill={colors.primary} />
+      {/* Mouth */}
+      <rect x="26" y="24" width="12" height="2" rx="1" fill="white" />
+      {/* Arms */}
+      <rect x="6" y="24" width="8" height="4" rx="2" fill={colors.primary} />
+      <rect x="50" y="24" width="8" height="4" rx="2" fill={colors.primary} />
+    </svg>
+  )
+}
+
+function FizzSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Ears */}
+      <polygon points="12,12 20,28 4,28" fill={colors.primary} />
+      <polygon points="52,12 60,28 44,28" fill={colors.primary} />
+      <polygon points="14,14 18,26 8,26" fill={colors.accent} />
+      <polygon points="50,14 56,26 44,26" fill={colors.accent} />
+      {/* Head */}
+      <ellipse cx="32" cy="36" rx="24" ry="22" fill={colors.primary} />
+      {/* Face */}
+      <ellipse cx="32" cy="40" rx="18" ry="14" fill={colors.accent} />
+      {/* Eyes */}
+      <ellipse cx="24" cy="32" rx="4" ry="5" fill="white" />
+      <ellipse cx="40" cy="32" rx="4" ry="5" fill="white" />
+      <circle cx="25" cy="33" r="2" fill="#1a1a1a" />
+      <circle cx="41" cy="33" r="2" fill="#1a1a1a" />
+      {/* Nose */}
+      <ellipse cx="32" cy="42" rx="4" ry="3" fill={colors.primary} />
+      {/* Whiskers */}
+      <line x1="8" y1="38" x2="18" y2="40" stroke={colors.primary} strokeWidth="2" />
+      <line x1="8" y1="44" x2="18" y2="44" stroke={colors.primary} strokeWidth="2" />
+      <line x1="46" y1="40" x2="56" y2="38" stroke={colors.primary} strokeWidth="2" />
+      <line x1="46" y1="44" x2="56" y2="44" stroke={colors.primary} strokeWidth="2" />
+    </svg>
+  )
+}
+
+function OctoSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Tentacles */}
+      <path d="M12,48 Q8,56 12,60 Q16,64 20,58" fill={colors.secondary} />
+      <path d="M22,50 Q20,58 24,62" fill={colors.secondary} />
+      <path d="M32,52 Q32,60 36,62" fill={colors.secondary} />
+      <path d="M42,50 Q44,58 40,62" fill={colors.secondary} />
+      <path d="M52,48 Q56,56 52,60 Q48,64 44,58" fill={colors.secondary} />
+      {/* Head */}
+      <ellipse cx="32" cy="32" rx="22" ry="24" fill={colors.primary} />
+      {/* Eyes */}
+      <ellipse cx="24" cy="28" rx="6" ry="8" fill="white" />
+      <ellipse cx="40" cy="28" rx="6" ry="8" fill="white" />
+      <ellipse cx="25" cy="30" rx="3" ry="4" fill={colors.primary} />
+      <ellipse cx="41" cy="30" rx="3" ry="4" fill={colors.primary} />
+      {/* Smile */}
+      <path d="M24,42 Q32,48 40,42" stroke={colors.accent} strokeWidth="2" fill="none" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+function HootSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Ear tufts */}
+      <polygon points="14,8 22,24 6,20" fill={colors.primary} />
+      <polygon points="50,8 58,20 42,24" fill={colors.primary} />
+      {/* Body */}
+      <ellipse cx="32" cy="40" rx="20" ry="18" fill={colors.primary} />
+      {/* Head */}
+      <circle cx="32" cy="28" r="20" fill={colors.secondary} />
+      {/* Eye circles */}
+      <circle cx="24" cy="26" r="10" fill={colors.accent} />
+      <circle cx="40" cy="26" r="10" fill={colors.accent} />
+      {/* Eyes */}
+      <circle cx="24" cy="26" r="6" fill="white" />
+      <circle cx="40" cy="26" r="6" fill="white" />
+      <circle cx="25" cy="27" r="3" fill="#1a1a1a" />
+      <circle cx="41" cy="27" r="3" fill="#1a1a1a" />
+      {/* Beak */}
+      <polygon points="32,32 28,40 36,40" fill="#F97316" />
+      {/* Belly */}
+      <ellipse cx="32" cy="46" rx="10" ry="8" fill={colors.accent} />
+    </svg>
+  )
+}
+
+function BuzzSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Wings */}
+      <ellipse cx="14" cy="32" rx="10" ry="14" fill={colors.accent} opacity="0.8" className="animate-pulse" />
+      <ellipse cx="50" cy="32" rx="10" ry="14" fill={colors.accent} opacity="0.8" className="animate-pulse" />
+      {/* Body stripes */}
+      <ellipse cx="32" cy="36" rx="14" ry="20" fill={colors.primary} />
+      <ellipse cx="32" cy="30" rx="12" ry="6" fill="#1a1a1a" />
+      <ellipse cx="32" cy="44" rx="12" ry="6" fill="#1a1a1a" />
+      {/* Head */}
+      <circle cx="32" cy="16" r="12" fill={colors.primary} />
+      {/* Antennae */}
+      <line x1="26" y1="8" x2="22" y2="2" stroke="#1a1a1a" strokeWidth="2" />
+      <line x1="38" y1="8" x2="42" y2="2" stroke="#1a1a1a" strokeWidth="2" />
+      <circle cx="22" cy="2" r="2" fill="#1a1a1a" />
+      <circle cx="42" cy="2" r="2" fill="#1a1a1a" />
+      {/* Eyes */}
+      <circle cx="28" cy="14" r="4" fill="white" />
+      <circle cx="36" cy="14" r="4" fill="white" />
+      <circle cx="29" cy="15" r="2" fill="#1a1a1a" />
+      <circle cx="37" cy="15" r="2" fill="#1a1a1a" />
+      {/* Smile */}
+      <path d="M28,20 Q32,24 36,20" stroke="#1a1a1a" strokeWidth="1.5" fill="none" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+function PixelSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Blocky body */}
+      <rect x="20" y="28" width="24" height="28" fill={colors.primary} />
+      <rect x="16" y="32" width="8" height="20" fill={colors.secondary} />
+      <rect x="40" y="32" width="8" height="20" fill={colors.secondary} />
+      {/* Head */}
+      <rect x="16" y="8" width="32" height="24" fill={colors.primary} />
+      {/* Eyes */}
+      <rect x="20" y="14" width="8" height="8" fill="white" />
+      <rect x="36" y="14" width="8" height="8" fill="white" />
+      <rect x="24" y="16" width="4" height="4" fill="#1a1a1a" />
+      <rect x="38" y="16" width="4" height="4" fill="#1a1a1a" />
+      {/* Mouth */}
+      <rect x="26" y="26" width="12" height="4" fill={colors.accent} />
+    </svg>
+  )
+}
+
+function ByteSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* 3D cube body */}
+      <polygon points="32,8 56,20 56,44 32,56 8,44 8,20" fill={colors.primary} />
+      <polygon points="32,8 56,20 32,32 8,20" fill={colors.secondary} />
+      <polygon points="32,32 56,20 56,44 32,56" fill={colors.accent} opacity="0.6" />
+      {/* Face */}
+      <circle cx="24" cy="28" r="4" fill="white" />
+      <circle cx="40" cy="28" r="4" fill="white" />
+      <circle cx="25" cy="29" r="2" fill="#1a1a1a" />
+      <circle cx="41" cy="29" r="2" fill="#1a1a1a" />
+      <path d="M26,38 Q32,42 38,38" stroke="white" strokeWidth="2" fill="none" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+function NovaSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Star points */}
+      <polygon points="32,2 38,22 58,22 42,36 48,56 32,44 16,56 22,36 6,22 26,22" fill={colors.primary} />
+      <circle cx="32" cy="32" r="14" fill={colors.secondary} />
+      {/* Face */}
+      <circle cx="27" cy="30" r="3" fill="white" />
+      <circle cx="37" cy="30" r="3" fill="white" />
+      <circle cx="28" cy="31" r="1.5" fill="#1a1a1a" />
+      <circle cx="38" cy="31" r="1.5" fill="#1a1a1a" />
+      <path d="M28,37 Q32,40 36,37" stroke="#1a1a1a" strokeWidth="1.5" fill="none" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+function ChipSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Chip body */}
+      <rect x="16" y="16" width="32" height="32" rx="4" fill={colors.primary} />
+      {/* Pins */}
+      <rect x="20" y="10" width="4" height="8" fill={colors.secondary} />
+      <rect x="30" y="10" width="4" height="8" fill={colors.secondary} />
+      <rect x="40" y="10" width="4" height="8" fill={colors.secondary} />
+      <rect x="20" y="46" width="4" height="8" fill={colors.secondary} />
+      <rect x="30" y="46" width="4" height="8" fill={colors.secondary} />
+      <rect x="40" y="46" width="4" height="8" fill={colors.secondary} />
+      {/* Face */}
+      <circle cx="26" cy="28" r="4" fill={colors.accent} />
+      <circle cx="38" cy="28" r="4" fill={colors.accent} />
+      <circle cx="26" cy="28" r="2" fill="#1a1a1a" />
+      <circle cx="38" cy="28" r="2" fill="#1a1a1a" />
+      <rect x="26" y="38" width="12" height="3" rx="1" fill={colors.accent} />
+    </svg>
+  )
+}
+
+function BoltSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Lightning bolt body */}
+      <polygon points="36,4 20,28 30,28 24,60 48,32 36,32 44,4" fill={colors.primary} />
+      <polygon points="34,8 24,26 32,26 28,52 42,34 34,34 40,8" fill={colors.secondary} />
+      {/* Face */}
+      <circle cx="30" cy="30" r="3" fill="white" />
+      <circle cx="38" cy="26" r="3" fill="white" />
+      <circle cx="31" cy="31" r="1.5" fill="#1a1a1a" />
+      <circle cx="39" cy="27" r="1.5" fill="#1a1a1a" />
+    </svg>
+  )
+}
+
+function DashSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Speed lines */}
+      <rect x="4" y="28" width="12" height="3" rx="1" fill={colors.accent} opacity="0.6" />
+      <rect x="8" y="34" width="10" height="3" rx="1" fill={colors.accent} opacity="0.4" />
+      {/* Aerodynamic body */}
+      <ellipse cx="36" cy="32" rx="20" ry="16" fill={colors.primary} />
+      <ellipse cx="40" cy="32" rx="14" ry="12" fill={colors.secondary} />
+      {/* Face */}
+      <circle cx="38" cy="28" r="4" fill="white" />
+      <circle cx="48" cy="28" r="4" fill="white" />
+      <circle cx="39" cy="29" r="2" fill="#1a1a1a" />
+      <circle cx="49" cy="29" r="2" fill="#1a1a1a" />
+      <path d="M40,36 Q44,39 48,36" stroke="#1a1a1a" strokeWidth="1.5" fill="none" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+function ZapSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Electric sparks */}
+      <path d="M12,32 L20,28 L16,32 L22,30" stroke={colors.secondary} strokeWidth="2" className="animate-pulse" />
+      <path d="M52,32 L44,28 L48,32 L42,30" stroke={colors.secondary} strokeWidth="2" className="animate-pulse" />
+      {/* Orb */}
+      <circle cx="32" cy="32" r="18" fill={colors.primary} />
+      <circle cx="32" cy="32" r="14" fill={colors.secondary} />
+      {/* Face */}
+      <circle cx="26" cy="30" r="4" fill="white" />
+      <circle cx="38" cy="30" r="4" fill="white" />
+      <circle cx="27" cy="31" r="2" fill={colors.primary} />
+      <circle cx="39" cy="31" r="2" fill={colors.primary} />
+      <path d="M28,40 Q32,44 36,40" stroke="white" strokeWidth="2" fill="none" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+function GizmoSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Gear teeth */}
+      <rect x="28" y="4" width="8" height="8" fill={colors.primary} />
+      <rect x="28" y="52" width="8" height="8" fill={colors.primary} />
+      <rect x="4" y="28" width="8" height="8" fill={colors.primary} />
+      <rect x="52" y="28" width="8" height="8" fill={colors.primary} />
+      {/* Gear body */}
+      <circle cx="32" cy="32" r="20" fill={colors.primary} />
+      <circle cx="32" cy="32" r="14" fill={colors.secondary} />
+      {/* Face */}
+      <circle cx="26" cy="30" r="4" fill="white" />
+      <circle cx="38" cy="30" r="4" fill="white" />
+      <circle cx="27" cy="31" r="2" fill="#1a1a1a" />
+      <circle cx="39" cy="31" r="2" fill="#1a1a1a" />
+      <path d="M28,40 Q32,43 36,40" stroke="#1a1a1a" strokeWidth="2" fill="none" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+function TurboSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Flames */}
+      <ellipse cx="32" cy="58" rx="8" ry="6" fill="#FBBF24" className="animate-pulse" />
+      <ellipse cx="32" cy="56" rx="5" ry="4" fill="#FCD34D" />
+      {/* Rocket body */}
+      <ellipse cx="32" cy="32" rx="14" ry="24" fill={colors.primary} />
+      {/* Nose cone */}
+      <ellipse cx="32" cy="12" rx="8" ry="10" fill={colors.secondary} />
+      {/* Fins */}
+      <polygon points="18,44 10,56 18,52" fill={colors.secondary} />
+      <polygon points="46,44 54,56 46,52" fill={colors.secondary} />
+      {/* Window/Face */}
+      <circle cx="32" cy="28" r="8" fill={colors.accent} />
+      <circle cx="29" cy="27" r="2" fill="#1a1a1a" />
+      <circle cx="35" cy="27" r="2" fill="#1a1a1a" />
+      <path d="M29,32 Q32,34 35,32" stroke="#1a1a1a" strokeWidth="1" fill="none" />
+    </svg>
+  )
+}
+
+function BlipSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Radar rings */}
+      <circle cx="32" cy="32" r="28" stroke={colors.accent} strokeWidth="2" fill="none" opacity="0.3" />
+      <circle cx="32" cy="32" r="22" stroke={colors.accent} strokeWidth="2" fill="none" opacity="0.5" />
+      {/* Main dot */}
+      <circle cx="32" cy="32" r="14" fill={colors.primary} />
+      <circle cx="32" cy="32" r="10" fill={colors.secondary} />
+      {/* Face */}
+      <circle cx="28" cy="30" r="3" fill="white" />
+      <circle cx="36" cy="30" r="3" fill="white" />
+      <circle cx="29" cy="31" r="1.5" fill="#1a1a1a" />
+      <circle cx="37" cy="31" r="1.5" fill="#1a1a1a" />
+      <path d="M29,37 Q32,40 35,37" stroke="white" strokeWidth="1.5" fill="none" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+function NeonSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Glow effect */}
+      <circle cx="32" cy="32" r="26" fill={colors.accent} opacity="0.3" />
+      <circle cx="32" cy="32" r="22" fill={colors.accent} opacity="0.5" />
+      {/* Body */}
+      <circle cx="32" cy="32" r="18" fill={colors.primary} />
+      {/* Inner glow */}
+      <circle cx="32" cy="32" r="12" fill={colors.secondary} />
+      {/* Face */}
+      <circle cx="27" cy="30" r="4" fill="white" />
+      <circle cx="37" cy="30" r="4" fill="white" />
+      <circle cx="28" cy="31" r="2" fill={colors.primary} />
+      <circle cx="38" cy="31" r="2" fill={colors.primary} />
+      <path d="M28,38 Q32,42 36,38" stroke="white" strokeWidth="2" fill="none" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+function WidgetSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Window frame */}
+      <rect x="8" y="12" width="48" height="40" rx="4" fill={colors.primary} />
+      {/* Title bar */}
+      <rect x="8" y="12" width="48" height="10" rx="4" fill={colors.secondary} />
+      <circle cx="16" cy="17" r="2" fill="#EF4444" />
+      <circle cx="24" cy="17" r="2" fill="#FBBF24" />
+      <circle cx="32" cy="17" r="2" fill="#22C55E" />
+      {/* Content area / Face */}
+      <rect x="12" y="26" width="40" height="22" rx="2" fill={colors.accent} />
+      <circle cx="24" cy="34" r="4" fill="white" />
+      <circle cx="40" cy="34" r="4" fill="white" />
+      <circle cx="25" cy="35" r="2" fill={colors.primary} />
+      <circle cx="41" cy="35" r="2" fill={colors.primary} />
+      <rect x="28" y="42" width="8" height="3" rx="1" fill={colors.primary} />
+    </svg>
+  )
+}
+
+function ZippySVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Ears */}
+      <ellipse cx="22" cy="14" rx="6" ry="14" fill={colors.primary} />
+      <ellipse cx="42" cy="14" rx="6" ry="14" fill={colors.primary} />
+      <ellipse cx="22" cy="14" rx="3" ry="10" fill={colors.accent} />
+      <ellipse cx="42" cy="14" rx="3" ry="10" fill={colors.accent} />
+      {/* Head */}
+      <circle cx="32" cy="38" r="20" fill={colors.primary} />
+      {/* Face */}
+      <circle cx="24" cy="34" r="5" fill="white" />
+      <circle cx="40" cy="34" r="5" fill="white" />
+      <circle cx="25" cy="35" r="2.5" fill="#1a1a1a" />
+      <circle cx="41" cy="35" r="2.5" fill="#1a1a1a" />
+      {/* Nose and mouth */}
+      <ellipse cx="32" cy="44" rx="3" ry="2" fill={colors.secondary} />
+      <path d="M32,46 L32,50 M28,52 Q32,56 36,52" stroke="#1a1a1a" strokeWidth="1.5" fill="none" />
+    </svg>
+  )
+}
+
+function QuirkSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Question mark body */}
+      <path d="M24,20 Q24,8 32,8 Q44,8 44,20 Q44,28 32,32 L32,40"
+            stroke={colors.primary} strokeWidth="8" fill="none" strokeLinecap="round" />
+      <circle cx="32" cy="52" r="6" fill={colors.primary} />
+      {/* Face on the dot */}
+      <circle cx="29" cy="51" r="1.5" fill="white" />
+      <circle cx="35" cy="51" r="1.5" fill="white" />
+      <circle cx="29" cy="51" r="0.75" fill="#1a1a1a" />
+      <circle cx="35" cy="51" r="0.75" fill="#1a1a1a" />
+      {/* Decorative swirl */}
+      <circle cx="32" cy="20" r="4" fill={colors.secondary} />
+    </svg>
+  )
+}
+
+function FluxSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none">
+      {/* Wave body */}
+      <path d="M8,32 Q16,16 32,32 Q48,48 56,32" stroke={colors.primary} strokeWidth="16" fill="none" strokeLinecap="round" />
+      <path d="M8,32 Q16,16 32,32 Q48,48 56,32" stroke={colors.secondary} strokeWidth="10" fill="none" strokeLinecap="round" />
+      {/* Face */}
+      <circle cx="28" cy="28" r="4" fill="white" />
+      <circle cx="40" cy="36" r="4" fill="white" />
+      <circle cx="29" cy="29" r="2" fill="#1a1a1a" />
+      <circle cx="41" cy="37" r="2" fill="#1a1a1a" />
+      {/* Sparkles */}
+      <circle cx="16" cy="24" r="2" fill={colors.accent} className="animate-pulse" />
+      <circle cx="48" cy="40" r="2" fill={colors.accent} className="animate-pulse" />
+    </svg>
+  )
+}
+
+/** Fallback icon for unknown / untracked agents. */
+function UnknownSVG({ colors, size }: MascotSVGProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg">
+      {/* Circle background */}
+      <circle cx="32" cy="32" r="28" fill={colors.primary} />
+      <circle cx="32" cy="32" r="24" fill={colors.secondary} />
+      {/* Question mark */}
+      <text x="32" y="44" textAnchor="middle" fontSize="32" fontWeight="bold" fill="white">?</text>
+    </svg>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Mascot component lookup
+// ---------------------------------------------------------------------------
+
+/** Maps each mascot name to its SVG component. */
+export const MASCOT_SVGS: Record<AgentMascot, React.FC<MascotSVGProps>> = {
+  // Original 5
+  Spark: SparkSVG,
+  Fizz: FizzSVG,
+  Octo: OctoSVG,
+  Hoot: HootSVG,
+  Buzz: BuzzSVG,
+  // Tech-inspired
+  Pixel: PixelSVG,
+  Byte: ByteSVG,
+  Nova: NovaSVG,
+  Chip: ChipSVG,
+  Bolt: BoltSVG,
+  // Energetic
+  Dash: DashSVG,
+  Zap: ZapSVG,
+  Gizmo: GizmoSVG,
+  Turbo: TurboSVG,
+  Blip: BlipSVG,
+  // Playful
+  Neon: NeonSVG,
+  Widget: WidgetSVG,
+  Zippy: ZippySVG,
+  Quirk: QuirkSVG,
+  Flux: FluxSVG,
+}
+
+/** The SVG component for unknown agents. Exported separately because
+ *  it is not part of the AgentMascot union type. */
+export const UnknownMascotSVG: React.FC<MascotSVGProps> = UnknownSVG

ui/src/components/ui/popover.tsx

@@ -1,87 +0,0 @@
-import * as React from "react"
-import * as PopoverPrimitive from "@radix-ui/react-popover"
-
-import { cn } from "@/lib/utils"
-
-function Popover({
-  ...props
-}: React.ComponentProps<typeof PopoverPrimitive.Root>) {
-  return <PopoverPrimitive.Root data-slot="popover" {...props} />
-}
-
-function PopoverTrigger({
-  ...props
-}: React.ComponentProps<typeof PopoverPrimitive.Trigger>) {
-  return <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />
-}
-
-function PopoverContent({
-  className,
-  align = "center",
-  sideOffset = 4,
-  ...props
-}: React.ComponentProps<typeof PopoverPrimitive.Content>) {
-  return (
-    <PopoverPrimitive.Portal>
-      <PopoverPrimitive.Content
-        data-slot="popover-content"
-        align={align}
-        sideOffset={sideOffset}
-        className={cn(
-          "bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-72 origin-(--radix-popover-content-transform-origin) rounded-md border p-4 shadow-md outline-hidden",
-          className
-        )}
-        {...props}
-      />
-    </PopoverPrimitive.Portal>
-  )
-}
-
-function PopoverAnchor({
-  ...props
-}: React.ComponentProps<typeof PopoverPrimitive.Anchor>) {
-  return <PopoverPrimitive.Anchor data-slot="popover-anchor" {...props} />
-}
-
-function PopoverHeader({ className, ...props }: React.ComponentProps<"div">) {
-  return (
-    <div
-      data-slot="popover-header"
-      className={cn("flex flex-col gap-1 text-sm", className)}
-      {...props}
-    />
-  )
-}
-
-function PopoverTitle({ className, ...props }: React.ComponentProps<"h2">) {
-  return (
-    <div
-      data-slot="popover-title"
-      className={cn("font-medium", className)}
-      {...props}
-    />
-  )
-}
-
-function PopoverDescription({
-  className,
-  ...props
-}: React.ComponentProps<"p">) {
-  return (
-    <p
-      data-slot="popover-description"
-      className={cn("text-muted-foreground", className)}
-      {...props}
-    />
-  )
-}
-
-export {
-  Popover,
-  PopoverTrigger,
-  PopoverContent,
-  PopoverAnchor,
-  PopoverHeader,
-  PopoverTitle,
-  PopoverDescription,
-}

ui/src/components/ui/radio-group.tsx

@@ -1,45 +0,0 @@
-"use client"
-
-import * as React from "react"
-import * as RadioGroupPrimitive from "@radix-ui/react-radio-group"
-import { CircleIcon } from "lucide-react"
-
-import { cn } from "@/lib/utils"
-
-function RadioGroup({
-  className,
-  ...props
-}: React.ComponentProps<typeof RadioGroupPrimitive.Root>) {
-  return (
-    <RadioGroupPrimitive.Root
-      data-slot="radio-group"
-      className={cn("grid gap-3", className)}
-      {...props}
-    />
-  )
-}
-
-function RadioGroupItem({
-  className,
-  ...props
-}: React.ComponentProps<typeof RadioGroupPrimitive.Item>) {
-  return (
-    <RadioGroupPrimitive.Item
-      data-slot="radio-group-item"
-      className={cn(
-        "border-input text-primary focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 aspect-square size-4 shrink-0 rounded-full border shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50",
-        className
-      )}
-      {...props}
-    >
-      <RadioGroupPrimitive.Indicator
-        data-slot="radio-group-indicator"
-        className="relative flex items-center justify-center"
-      >
-        <CircleIcon className="fill-primary absolute top-1/2 left-1/2 size-2 -translate-x-1/2 -translate-y-1/2" />
-      </RadioGroupPrimitive.Indicator>
-    </RadioGroupPrimitive.Item>
-  )
-}
-
-export { RadioGroup, RadioGroupItem }

ui/src/components/ui/scroll-area.tsx

@@ -1,56 +0,0 @@
-import * as React from "react"
-import * as ScrollAreaPrimitive from "@radix-ui/react-scroll-area"
-
-import { cn } from "@/lib/utils"
-
-function ScrollArea({
-  className,
-  children,
-  ...props
-}: React.ComponentProps<typeof ScrollAreaPrimitive.Root>) {
-  return (
-    <ScrollAreaPrimitive.Root
-      data-slot="scroll-area"
-      className={cn("relative", className)}
-      {...props}
-    >
-      <ScrollAreaPrimitive.Viewport
-        data-slot="scroll-area-viewport"
-        className="focus-visible:ring-ring/50 size-full rounded-[inherit] transition-[color,box-shadow] outline-none focus-visible:ring-[3px] focus-visible:outline-1"
-      >
-        {children}
-      </ScrollAreaPrimitive.Viewport>
-      <ScrollBar />
-      <ScrollAreaPrimitive.Corner />
-    </ScrollAreaPrimitive.Root>
-  )
-}
-
-function ScrollBar({
-  className,
-  orientation = "vertical",
-  ...props
-}: React.ComponentProps<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>) {
-  return (
-    <ScrollAreaPrimitive.ScrollAreaScrollbar
-      data-slot="scroll-area-scrollbar"
-      orientation={orientation}
-      className={cn(
-        "flex touch-none p-px transition-colors select-none",
-        orientation === "vertical" &&
-          "h-full w-2.5 border-l border-l-transparent",
-        orientation === "horizontal" &&
-          "h-2.5 flex-col border-t border-t-transparent",
-        className
-      )}
-      {...props}
-    >
-      <ScrollAreaPrimitive.ScrollAreaThumb
-        data-slot="scroll-area-thumb"
-        className="bg-border relative flex-1 rounded-full"
-      />
-    </ScrollAreaPrimitive.ScrollAreaScrollbar>
-  )
-}
-
-export { ScrollArea, ScrollBar }

ui/src/components/ui/select.tsx

@@ -1,190 +0,0 @@
-"use client"
-
-import * as React from "react"
-import * as SelectPrimitive from "@radix-ui/react-select"
-import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from "lucide-react"
-
-import { cn } from "@/lib/utils"
-
-function Select({
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Root>) {
-  return <SelectPrimitive.Root data-slot="select" {...props} />
-}
-
-function SelectGroup({
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Group>) {
-  return <SelectPrimitive.Group data-slot="select-group" {...props} />
-}
-
-function SelectValue({
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Value>) {
-  return <SelectPrimitive.Value data-slot="select-value" {...props} />
-}
-
-function SelectTrigger({
-  className,
-  size = "default",
-  children,
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
-  size?: "sm" | "default"
-}) {
-  return (
-    <SelectPrimitive.Trigger
-      data-slot="select-trigger"
-      data-size={size}
-      className={cn(
-        "border-input data-[placeholder]:text-muted-foreground [&_svg:not([class*='text-'])]:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 dark:hover:bg-input/50 flex w-fit items-center justify-between gap-2 rounded-md border bg-transparent px-3 py-2 text-sm whitespace-nowrap shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 data-[size=default]:h-9 data-[size=sm]:h-8 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-2 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
-        className
-      )}
-      {...props}
-    >
-      {children}
-      <SelectPrimitive.Icon asChild>
-        <ChevronDownIcon className="size-4 opacity-50" />
-      </SelectPrimitive.Icon>
-    </SelectPrimitive.Trigger>
-  )
-}
-
-function SelectContent({
-  className,
-  children,
-  position = "item-aligned",
-  align = "center",
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Content>) {
-  return (
-    <SelectPrimitive.Portal>
-      <SelectPrimitive.Content
-        data-slot="select-content"
-        className={cn(
-          "bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 relative z-50 max-h-(--radix-select-content-available-height) min-w-[8rem] origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border shadow-md",
-          position === "popper" &&
-            "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1",
-          className
-        )}
-        position={position}
-        align={align}
-        {...props}
-      >
-        <SelectScrollUpButton />
-        <SelectPrimitive.Viewport
-          className={cn(
-            "p-1",
-            position === "popper" &&
-              "h-[var(--radix-select-trigger-height)] w-full min-w-[var(--radix-select-trigger-width)] scroll-my-1"
-          )}
-        >
-          {children}
-        </SelectPrimitive.Viewport>
-        <SelectScrollDownButton />
-      </SelectPrimitive.Content>
-    </SelectPrimitive.Portal>
-  )
-}
-
-function SelectLabel({
-  className,
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Label>) {
-  return (
-    <SelectPrimitive.Label
-      data-slot="select-label"
-      className={cn("text-muted-foreground px-2 py-1.5 text-xs", className)}
-      {...props}
-    />
-  )
-}
-
-function SelectItem({
-  className,
-  children,
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Item>) {
-  return (
-    <SelectPrimitive.Item
-      data-slot="select-item"
-      className={cn(
-        "focus:bg-accent focus:text-accent-foreground [&_svg:not([class*='text-'])]:text-muted-foreground relative flex w-full cursor-default items-center gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
-        className
-      )}
-      {...props}
-    >
-      <span
-        data-slot="select-item-indicator"
-        className="absolute right-2 flex size-3.5 items-center justify-center"
-      >
-        <SelectPrimitive.ItemIndicator>
-          <CheckIcon className="size-4" />
-        </SelectPrimitive.ItemIndicator>
-      </span>
-      <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
-    </SelectPrimitive.Item>
-  )
-}
-
-function SelectSeparator({
-  className,
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.Separator>) {
-  return (
-    <SelectPrimitive.Separator
-      data-slot="select-separator"
-      className={cn("bg-border pointer-events-none -mx-1 my-1 h-px", className)}
-      {...props}
-    />
-  )
-}
-
-function SelectScrollUpButton({
-  className,
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.ScrollUpButton>) {
-  return (
-    <SelectPrimitive.ScrollUpButton
-      data-slot="select-scroll-up-button"
-      className={cn(
-        "flex cursor-default items-center justify-center py-1",
-        className
-      )}
-      {...props}
-    >
-      <ChevronUpIcon className="size-4" />
-    </SelectPrimitive.ScrollUpButton>
-  )
-}
-
-function SelectScrollDownButton({
-  className,
-  ...props
-}: React.ComponentProps<typeof SelectPrimitive.ScrollDownButton>) {
-  return (
-    <SelectPrimitive.ScrollDownButton
-      data-slot="select-scroll-down-button"
-      className={cn(
-        "flex cursor-default items-center justify-center py-1",
-        className
-      )}
-      {...props}
-    >
-      <ChevronDownIcon className="size-4" />
-    </SelectPrimitive.ScrollDownButton>
-  )
-}
-
-export {
-  Select,
-  SelectContent,
-  SelectGroup,
-  SelectItem,
-  SelectLabel,
-  SelectScrollDownButton,
-  SelectScrollUpButton,
-  SelectSeparator,
-  SelectTrigger,
-  SelectValue,
-}

ui/src/components/ui/tabs.tsx

@@ -1,89 +0,0 @@
-import * as React from "react"
-import * as TabsPrimitive from "@radix-ui/react-tabs"
-import { cva, type VariantProps } from "class-variance-authority"
-
-import { cn } from "@/lib/utils"
-
-function Tabs({
-  className,
-  orientation = "horizontal",
-  ...props
-}: React.ComponentProps<typeof TabsPrimitive.Root>) {
-  return (
-    <TabsPrimitive.Root
-      data-slot="tabs"
-      data-orientation={orientation}
-      orientation={orientation}
-      className={cn(
-        "group/tabs flex gap-2 data-[orientation=horizontal]:flex-col",
-        className
-      )}
-      {...props}
-    />
-  )
-}
-
-const tabsListVariants = cva(
-  "rounded-lg p-[3px] group-data-[orientation=horizontal]/tabs:h-9 data-[variant=line]:rounded-none group/tabs-list text-muted-foreground inline-flex w-fit items-center justify-center group-data-[orientation=vertical]/tabs:h-fit group-data-[orientation=vertical]/tabs:flex-col",
-  {
-    variants: {
-      variant: {
-        default: "bg-muted",
-        line: "gap-1 bg-transparent",
-      },
-    },
-    defaultVariants: {
-      variant: "default",
-    },
-  }
-)
-
-function TabsList({
-  className,
-  variant = "default",
-  ...props
-}: React.ComponentProps<typeof TabsPrimitive.List> &
-  VariantProps<typeof tabsListVariants>) {
-  return (
-    <TabsPrimitive.List
-      data-slot="tabs-list"
-      data-variant={variant}
-      className={cn(tabsListVariants({ variant }), className)}
-      {...props}
-    />
-  )
-}
-
-function TabsTrigger({
-  className,
-  ...props
-}: React.ComponentProps<typeof TabsPrimitive.Trigger>) {
-  return (
-    <TabsPrimitive.Trigger
-      data-slot="tabs-trigger"
-      className={cn(
-        "focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:outline-ring text-foreground/60 hover:text-foreground dark:text-muted-foreground dark:hover:text-foreground relative inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-2 py-1 text-sm font-medium whitespace-nowrap transition-all group-data-[orientation=vertical]/tabs:w-full group-data-[orientation=vertical]/tabs:justify-start focus-visible:ring-[3px] focus-visible:outline-1 disabled:pointer-events-none disabled:opacity-50 group-data-[variant=default]/tabs-list:data-[state=active]:shadow-sm group-data-[variant=line]/tabs-list:data-[state=active]:shadow-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
-        "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent dark:group-data-[variant=line]/tabs-list:data-[state=active]:border-transparent dark:group-data-[variant=line]/tabs-list:data-[state=active]:bg-transparent",
-        "data-[state=active]:bg-background dark:data-[state=active]:text-foreground dark:data-[state=active]:border-input dark:data-[state=active]:bg-input/30 data-[state=active]:text-foreground",
-        "after:bg-foreground after:absolute after:opacity-0 after:transition-opacity group-data-[orientation=horizontal]/tabs:after:inset-x-0 group-data-[orientation=horizontal]/tabs:after:bottom-[-5px] group-data-[orientation=horizontal]/tabs:after:h-0.5 group-data-[orientation=vertical]/tabs:after:inset-y-0 group-data-[orientation=vertical]/tabs:after:-right-1 group-data-[orientation=vertical]/tabs:after:w-0.5 group-data-[variant=line]/tabs-list:data-[state=active]:after:opacity-100",
-        className
-      )}
-      {...props}
-    />
-  )
-}
-
-function TabsContent({
-  className,
-  ...props
-}: React.ComponentProps<typeof TabsPrimitive.Content>) {
-  return (
-    <TabsPrimitive.Content
-      data-slot="tabs-content"
-      className={cn("flex-1 outline-none", className)}
-      {...props}
-    />
-  )
-}
-
-export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants }

ui/src/components/ui/toggle.tsx

@@ -1,47 +0,0 @@
-"use client"
-
-import * as React from "react"
-import * as TogglePrimitive from "@radix-ui/react-toggle"
-import { cva, type VariantProps } from "class-variance-authority"
-
-import { cn } from "@/lib/utils"
-
-const toggleVariants = cva(
-  "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium hover:bg-muted hover:text-muted-foreground disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 [&_svg]:shrink-0 focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] outline-none transition-[color,box-shadow] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive whitespace-nowrap",
-  {
-    variants: {
-      variant: {
-        default: "bg-transparent",
-        outline:
-          "border border-input bg-transparent shadow-xs hover:bg-accent hover:text-accent-foreground",
-      },
-      size: {
-        default: "h-9 px-2 min-w-9",
-        sm: "h-8 px-1.5 min-w-8",
-        lg: "h-10 px-2.5 min-w-10",
-      },
-    },
-    defaultVariants: {
-      variant: "default",
-      size: "default",
-    },
-  }
-)
-
-function Toggle({
-  className,
-  variant,
-  size,
-  ...props
-}: React.ComponentProps<typeof TogglePrimitive.Root> &
-  VariantProps<typeof toggleVariants>) {
-  return (
-    <TogglePrimitive.Root
-      data-slot="toggle"
-      className={cn(toggleVariants({ variant, size, className }))}
-      {...props}
-    />
-  )
-}
-
-export { Toggle, toggleVariants }

ui/src/components/ui/tooltip.tsx

@@ -1,61 +0,0 @@
-"use client"
-
-import * as React from "react"
-import * as TooltipPrimitive from "@radix-ui/react-tooltip"
-
-import { cn } from "@/lib/utils"
-
-function TooltipProvider({
-  delayDuration = 0,
-  ...props
-}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
-  return (
-    <TooltipPrimitive.Provider
-      data-slot="tooltip-provider"
-      delayDuration={delayDuration}
-      {...props}
-    />
-  )
-}
-
-function Tooltip({
-  ...props
-}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
-  return (
-    <TooltipProvider>
-      <TooltipPrimitive.Root data-slot="tooltip" {...props} />
-    </TooltipProvider>
-  )
-}
-
-function TooltipTrigger({
-  ...props
-}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
-  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
-}
-
-function TooltipContent({
-  className,
-  sideOffset = 0,
-  children,
-  ...props
-}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
-  return (
-    <TooltipPrimitive.Portal>
-      <TooltipPrimitive.Content
-        data-slot="tooltip-content"
-        sideOffset={sideOffset}
-        className={cn(
-          "bg-foreground text-background animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-fit origin-(--radix-tooltip-content-transform-origin) rounded-md px-3 py-1.5 text-xs text-balance",
-          className
-        )}
-        {...props}
-      >
-        {children}
-        <TooltipPrimitive.Arrow className="bg-foreground fill-foreground z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px]" />
-      </TooltipPrimitive.Content>
-    </TooltipPrimitive.Portal>
-  )
-}
-
-export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }

ui/src/hooks/useConversations.ts

@@ -26,6 +26,16 @@ export function useConversation(projectName: string | null, conversationId: numb
     queryFn: () => api.getAssistantConversation(projectName!, conversationId!),
     enabled: !!projectName && !!conversationId,
     staleTime: 30_000, // Cache for 30 seconds
+    retry: (failureCount, error) => {
+      // Don't retry on "not found" errors (404) - conversation doesn't exist
+      if (error instanceof Error && (
+        error.message.toLowerCase().includes('not found') ||
+        error.message === 'HTTP 404'
+      )) {
+        return false
+      }
+      return failureCount < 3
+    },
   })
 }
 

ui/src/hooks/useProjects.ts

@@ -4,7 +4,7 @@
 
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
 import * as api from '../lib/api'
-import type { FeatureCreate, FeatureUpdate, ModelsResponse, Settings, SettingsUpdate } from '../lib/types'
+import type { FeatureCreate, FeatureUpdate, ModelsResponse, ProjectSettingsUpdate, Settings, SettingsUpdate } from '../lib/types'
 
 // ============================================================================
 // Projects
@@ -48,6 +48,33 @@ export function useDeleteProject() {
   })
 }
 
+export function useResetProject(projectName: string) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: (fullReset: boolean) => api.resetProject(projectName, fullReset),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['projects'] })
+      queryClient.invalidateQueries({ queryKey: ['project', projectName] })
+      queryClient.invalidateQueries({ queryKey: ['features', projectName] })
+      queryClient.invalidateQueries({ queryKey: ['agent-status', projectName] })
+    },
+  })
+}
+
+export function useUpdateProjectSettings(projectName: string) {
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: (settings: ProjectSettingsUpdate) =>
+      api.updateProjectSettings(projectName, settings),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['projects'] })
+      queryClient.invalidateQueries({ queryKey: ['project', projectName] })
+    },
+  })
+}
+
 // ============================================================================
 // Features
 // ============================================================================
@@ -239,6 +266,8 @@ const DEFAULT_SETTINGS: Settings = {
   glm_mode: false,
   ollama_mode: false,
   testing_agent_ratio: 1,
+  playwright_headless: true,
+  batch_size: 3,
 }
 
 export function useAvailableModels() {

ui/src/hooks/useTheme.ts

@@ -1,6 +1,6 @@
 import { useState, useEffect, useCallback } from 'react'
 
-export type ThemeId = 'twitter' | 'claude' | 'neo-brutalism' | 'retro-arcade' | 'aurora'
+export type ThemeId = 'twitter' | 'claude' | 'neo-brutalism' | 'retro-arcade' | 'aurora' | 'business'
 
 export interface ThemeOption {
   id: ThemeId
@@ -43,6 +43,12 @@ export const THEMES: ThemeOption[] = [
     name: 'Aurora',
     description: 'Deep violet and teal, like northern lights',
     previewColors: { primary: '#8b5cf6', background: '#faf8ff', accent: '#2dd4bf' }
+  },
+  {
+    id: 'business',
+    name: 'Business',
+    description: 'Deep navy (#000e4e) and gray monochrome',
+    previewColors: { primary: '#000e4e', background: '#eaecef', accent: '#6b7280' }
   }
 ]
 
@@ -61,6 +67,8 @@ function getThemeClass(themeId: ThemeId): string {
       return 'theme-retro-arcade'
     case 'aurora':
       return 'theme-aurora'
+    case 'business':
+      return 'theme-business'
     default:
       return ''
   }
@@ -70,7 +78,7 @@ export function useTheme() {
   const [theme, setThemeState] = useState<ThemeId>(() => {
     try {
       const stored = localStorage.getItem(THEME_STORAGE_KEY)
-      if (stored === 'twitter' || stored === 'claude' || stored === 'neo-brutalism' || stored === 'retro-arcade' || stored === 'aurora') {
+      if (stored === 'twitter' || stored === 'claude' || stored === 'neo-brutalism' || stored === 'retro-arcade' || stored === 'aurora' || stored === 'business') {
         return stored
       }
     } catch {
@@ -92,7 +100,7 @@ export function useTheme() {
     const root = document.documentElement
 
     // Remove all theme classes
-    root.classList.remove('theme-claude', 'theme-neo-brutalism', 'theme-retro-arcade', 'theme-aurora')
+    root.classList.remove('theme-claude', 'theme-neo-brutalism', 'theme-retro-arcade', 'theme-aurora', 'theme-business')
 
     // Add current theme class (if not twitter/default)
     const themeClass = getThemeClass(theme)

ui/src/hooks/useWebSocket.ts

@@ -210,6 +210,7 @@ export function useProjectWebSocket(projectName: string | null) {
                     agentName: message.agentName,
                     agentType: message.agentType || 'coding',  // Default to coding for backwards compat
                     featureId: message.featureId,
+                    featureIds: message.featureIds || [message.featureId],
                     featureName: message.featureName,
                     state: message.state,
                     thought: message.thought,
@@ -225,6 +226,7 @@ export function useProjectWebSocket(projectName: string | null) {
                       agentName: message.agentName,
                       agentType: message.agentType || 'coding',  // Default to coding for backwards compat
                       featureId: message.featureId,
+                      featureIds: message.featureIds || [message.featureId],
                       featureName: message.featureName,
                       state: message.state,
                       thought: message.thought,

ui/src/lib/api.ts

@@ -6,6 +6,7 @@ import type {
   ProjectSummary,
   ProjectDetail,
   ProjectPrompts,
+  ProjectSettingsUpdate,
   FeatureListResponse,
   Feature,
   FeatureCreate,
@@ -100,6 +101,33 @@ export async function updateProjectPrompts(
   })
 }
 
+export async function updateProjectSettings(
+  name: string,
+  settings: ProjectSettingsUpdate
+): Promise<ProjectDetail> {
+  return fetchJSON(`/projects/${encodeURIComponent(name)}/settings`, {
+    method: 'PATCH',
+    body: JSON.stringify(settings),
+  })
+}
+
+export interface ResetProjectResponse {
+  success: boolean
+  reset_type: 'quick' | 'full'
+  deleted_files: string[]
+  message: string
+}
+
+export async function resetProject(
+  name: string,
+  fullReset: boolean = false
+): Promise<ResetProjectResponse> {
+  const params = fullReset ? '?full_reset=true' : ''
+  return fetchJSON(`/projects/${encodeURIComponent(name)}/reset${params}`, {
+    method: 'POST',
+  })
+}
+
 // ============================================================================
 // Features API
 // ============================================================================

ui/src/lib/keyboard.ts

@@ -0,0 +1,38 @@
+/**
+ * Keyboard event utilities
+ *
+ * Helpers for handling keyboard events, particularly for IME-aware input handling.
+ */
+
+/**
+ * Check if an Enter keypress should trigger form submission.
+ *
+ * Returns false during IME composition (e.g., Japanese, Chinese, Korean input)
+ * to prevent accidental submission while selecting characters.
+ *
+ * @param e - The keyboard event from React
+ * @param allowShiftEnter - If true, Shift+Enter returns false (for multiline input)
+ * @returns true if Enter should submit, false if it should be ignored
+ *
+ * @example
+ * // In a chat input (Shift+Enter for newline)
+ * if (isSubmitEnter(e)) {
+ *   e.preventDefault()
+ *   handleSend()
+ * }
+ *
+ * @example
+ * // In a single-line input (Enter always submits)
+ * if (isSubmitEnter(e, false)) {
+ *   handleSubmit()
+ * }
+ */
+export function isSubmitEnter(
+  e: React.KeyboardEvent,
+  allowShiftEnter: boolean = true
+): boolean {
+  if (e.key !== 'Enter') return false
+  if (allowShiftEnter && e.shiftKey) return false
+  if (e.nativeEvent.isComposing) return false
+  return true
+}

ui/src/lib/types.ts

@@ -15,6 +15,7 @@ export interface ProjectSummary {
   path: string
   has_spec: boolean
   stats: ProjectStats
+  default_concurrency: number
 }
 
 export interface ProjectDetail extends ProjectSummary {
@@ -198,7 +199,8 @@ export interface ActiveAgent {
   agentIndex: number  // -1 for synthetic completions
   agentName: AgentMascot | 'Unknown'
   agentType: AgentType  // "coding" or "testing"
-  featureId: number
+  featureId: number        // Current/primary feature (backward compat)
+  featureIds: number[]     // All features in batch
   featureName: string
   state: AgentState
   thought?: string
@@ -269,6 +271,7 @@ export interface WSAgentUpdateMessage {
   agentName: AgentMascot | 'Unknown'
   agentType: AgentType  // "coding" or "testing"
   featureId: number
+  featureIds?: number[]  // All features in batch (may be absent for backward compat)
   featureName: string
   state: AgentState
   thought?: string
@@ -528,12 +531,20 @@ export interface Settings {
   glm_mode: boolean
   ollama_mode: boolean
   testing_agent_ratio: number  // Regression testing agents (0-3)
+  playwright_headless: boolean
+  batch_size: number  // Features per coding agent batch (1-3)
 }
 
 export interface SettingsUpdate {
   yolo_mode?: boolean
   model?: string
   testing_agent_ratio?: number
+  playwright_headless?: boolean
+  batch_size?: number
+}
+
+export interface ProjectSettingsUpdate {
+  default_concurrency?: number
 }
 
 // ============================================================================