update lock

PR #158 added temp_cleanup.py and its import in autonomous_agent_demo.py
but did not include the file in the package.json "files" array. This
caused ModuleNotFoundError for npm installations since the module was
missing from the published tarball.

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

.claude/agents/coder.md

@@ -97,7 +97,7 @@ Fix ALL issues before considering the implementation complete. Never leave linti
 
 ## Project-Specific Context
 
-For this project (autocoder):
+For this project (autoforge):
 - **Python Backend**: Uses SQLAlchemy, FastAPI, follows patterns in `api/`, `mcp_server/`
 - **React UI**: Uses React 18, TypeScript, TanStack Query, Tailwind CSS v4, Radix UI
 - **Design System**: Neobrutalism style with specific color tokens and animations

.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/.autoforge/prompts/app_spec.txt` and `$ARGUMENTS/.autoforge/prompts/initializer_prompt.md`
 
 If `$ARGUMENTS` is empty, inform the user they must provide a project path and exit.
 
@@ -347,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/.autoforge/prompts/`
 
 Once the user approves, generate these files:
 
 ## 1. Generate `app_spec.txt`
 
-**Output path:** `$ARGUMENTS/prompts/app_spec.txt`
+**Output path:** `$ARGUMENTS/.autoforge/prompts/app_spec.txt`
 
 Create a new file using this XML structure:
 
@@ -489,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/.autoforge/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.
@@ -512,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/.autoforge/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.
 
@@ -524,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",
+    ".autoforge/prompts/app_spec.txt",
-    "prompts/initializer_prompt.md"
+    ".autoforge/prompts/initializer_prompt.md"
   ],
   "feature_count": [the feature count from Phase 4L]
 }
@@ -539,9 +539,9 @@ Write this JSON file:
   "version": 1,
   "timestamp": "2025-01-15T14:30:00.000Z",
   "files_written": [
-    "prompts/app_spec.txt",
+    ".autoforge/prompts/app_spec.txt",
-    "prompts/initializer_prompt.md",
+    ".autoforge/prompts/initializer_prompt.md",
-    "prompts/coding_prompt.md"
+    ".autoforge/prompts/coding_prompt.md"
   ],
   "feature_count": 35
 }
@@ -559,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/.autoforge/prompts/`!
 >
 > **Files created:**
-> - `$ARGUMENTS/prompts/app_spec.txt`
+> - `$ARGUMENTS/.autoforge/prompts/app_spec.txt`
-> - `$ARGUMENTS/prompts/initializer_prompt.md`
+> - `$ARGUMENTS/.autoforge/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/.autoforge/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/.autoforge/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

@@ -1,10 +0,0 @@
----
-allowed-tools: Read, Write, Bash, Glob, Grep
-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`.
-
-@.claude/skills/gsd-to-autocoder-spec/SKILL.md

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

@@ -0,0 +1,10 @@
+---
+allowed-tools: Read, Write, Bash, Glob, Grep
+description: Convert GSD codebase mapping to AutoForge app_spec.txt
+---
+
+# GSD to AutoForge Spec
+
+Convert `.planning/codebase/*.md` (from `/gsd:map-codebase`) to AutoForge's `.autoforge/prompts/app_spec.txt`.
+
+@.claude/skills/gsd-to-autoforge-spec/SKILL.md

.claude/commands/review-pr.md

@@ -40,15 +40,36 @@ Pull request(s): $ARGUMENTS
    - 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. **Vision Alignment Check**
+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
 
-5. **Safety Assessment**
+6. **Safety Assessment**
    - Provide a review on whether the PR is safe to merge as-is
    - Provide any feedback in terms of risk level
 
-6. **Improvements**
+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-autoforge-spec/SKILL.md

@@ -1,21 +1,21 @@
 ---
-name: gsd-to-autocoder-spec
+name: gsd-to-autoforge-spec
 description: |
-  Convert GSD codebase mapping to Autocoder app_spec.txt. This skill should be used when
+  Convert GSD codebase mapping to AutoForge app_spec.txt. This skill should be used when
-  the user has run /gsd:map-codebase and wants to use Autocoder on an existing project.
+  the user has run /gsd:map-codebase and wants to use AutoForge on an existing project.
-  Triggers: "convert to autocoder", "gsd to spec", "create app_spec from codebase",
+  Triggers: "convert to autoforge", "gsd to spec", "create app_spec from codebase",
-  "use autocoder on existing project", after /gsd:map-codebase completion.
+  "use autoforge on existing project", after /gsd:map-codebase completion.
 ---
 
-# GSD to Autocoder Spec Converter
+# GSD to AutoForge Spec Converter
 
-Converts `.planning/codebase/*.md` (GSD mapping output) to `prompts/app_spec.txt` (Autocoder format).
+Converts `.planning/codebase/*.md` (GSD mapping output) to `.autoforge/prompts/app_spec.txt` (AutoForge format).
 
 ## When to Use
 
 - After running `/gsd:map-codebase` on an existing project
-- When onboarding an existing codebase to Autocoder
+- When onboarding an existing codebase to AutoForge
-- User wants Autocoder to continue development on existing code
+- User wants AutoForge to continue development on existing code
 
 ## Prerequisites
 
@@ -84,12 +84,12 @@ Extract:
 
 Create `prompts/` directory:
 ```bash
-mkdir -p prompts
+mkdir -p .autoforge/prompts
 ```
 
-**Mapping GSD Documents to Autocoder Spec:**
+**Mapping GSD Documents to AutoForge Spec:**
 
-| GSD Source | Autocoder Target |
+| GSD Source | AutoForge Target |
 |------------|------------------|
 | STACK.md Languages | `<technology_stack>` |
 | STACK.md Frameworks | `<frontend>`, `<backend>` |
@@ -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 > .autoforge/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 .autoforge/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" .autoforge/prompts/app_spec.txt || echo "0"
 ```
 
 **Validation checklist:**
@@ -194,15 +194,15 @@ Output:
 app_spec.txt generated from GSD codebase mapping.
 
 Source: .planning/codebase/*.md
-Output: prompts/app_spec.txt
+Output: .autoforge/prompts/app_spec.txt
 
-Next: Start Autocoder
+Next: Start AutoForge
 
   cd {project_dir}
-  python ~/projects/autocoder/start.py
+  python ~/projects/autoforge/start.py
 
 Or via UI:
-  ~/projects/autocoder/start_ui.sh
+  ~/projects/autoforge/start_ui.sh
 
 The Initializer will create features.db from this spec.
 ```

.claude/skills/gsd-to-autoforge-spec/references/app-spec-format.md

@@ -1,6 +1,6 @@
-# Autocoder app_spec.txt XML Format
+# AutoForge app_spec.txt XML Format
 
-Complete reference for the XML structure expected by Autocoder's Initializer agent.
+Complete reference for the XML structure expected by AutoForge's Initializer agent.
 
 ## Root Structure
 
@@ -275,7 +275,7 @@ The Initializer agent expects features distributed across categories:
 | Medium web app | 200-250 | 10-15 |
 | Complex full-stack | 300-400 | 15-20 |
 
-## GSD to Autocoder Mapping
+## GSD to AutoForge Mapping
 
 When converting from GSD codebase mapping:
 

.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,130 +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
-- [ ] **Ran extended mock data grep (STEP 5.6) - no hits in src/ (excluding tests)**
-- [ ] **Verified no globalThis, devStore, or dev-store patterns**
-- [ ] **Server restart test passed (STEP 5.7) - data persists across restart**
-
-#### 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)
 
-**Run ALL these grep checks. Any hits in src/ (excluding test files) require investigation:**
+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.
-
-```bash
-# Common exclusions for test files
-EXCLUDE="--exclude=*.test.* --exclude=*.spec.* --exclude=*__test__* --exclude=*__mocks__*"
-
-# 1. In-memory storage patterns (CRITICAL - catches dev-store)
-grep -r "globalThis\." --include="*.ts" --include="*.tsx" --include="*.js" $EXCLUDE src/
-grep -r "dev-store\|devStore\|DevStore\|mock-db\|mockDb" --include="*.ts" --include="*.tsx" --include="*.js" $EXCLUDE src/
-
-# 2. Mock data variables
-grep -r "mockData\|fakeData\|sampleData\|dummyData\|testData" --include="*.ts" --include="*.tsx" --include="*.js" $EXCLUDE src/
-
-# 3. TODO/incomplete markers
-grep -r "TODO.*real\|TODO.*database\|TODO.*API\|STUB\|MOCK" --include="*.ts" --include="*.tsx" --include="*.js" $EXCLUDE src/
-
-# 4. Development-only conditionals
-grep -r "isDevelopment\|isDev\|process\.env\.NODE_ENV.*development" --include="*.ts" --include="*.tsx" --include="*.js" $EXCLUDE src/
-
-# 5. In-memory collections as data stores
-grep -r "new Map\(\)\|new Set\(\)" --include="*.ts" --include="*.tsx" --include="*.js" $EXCLUDE src/ 2>/dev/null
-```
-
-**Rule:** If ANY grep returns results in production code → investigate → FIX before marking passing.
-
-**Runtime verification:**
-1. Create unique data (e.g., "TEST_12345") → verify in UI → delete → verify gone
-2. Check database directly - all displayed data must come from real DB queries
-3. If unexplained data appears, it's mock data - fix before marking passing.
 
 ### STEP 5.7: SERVER RESTART PERSISTENCE TEST (MANDATORY for data features)
 
-**When required:** Any feature involving CRUD operations or data persistence.
+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.
-
-**This test is NON-NEGOTIABLE. It catches in-memory storage implementations that pass all other tests.**
-
-**Steps:**
-
-1. Create unique test data via UI or API (e.g., item named "RESTART_TEST_12345")
-2. Verify data appears in UI and API response
-
-3. **STOP the server completely:**
-   ```bash
-   # Kill by port (safer - only kills the dev server, not VS Code/Claude Code/etc.)
-   # Unix/macOS:
-   lsof -ti :${PORT:-3000} | xargs kill -TERM 2>/dev/null || true
-   sleep 3
-   lsof -ti :${PORT:-3000} | xargs kill -9 2>/dev/null || true
-   sleep 2
-
-   # Windows alternative (use if lsof not available):
-   # netstat -ano | findstr :${PORT:-3000} | findstr LISTENING
-   # taskkill /F /PID <pid_from_above> 2>nul
-
-   # Verify server is stopped
-   if lsof -ti :${PORT:-3000} > /dev/null 2>&1; then
-     echo "ERROR: Server still running on port ${PORT:-3000}!"
-     exit 1
-   fi
-   ```
-
-4. **RESTART the server:**
-   ```bash
-   ./init.sh &
-   sleep 15  # Allow server to fully start
-   # Verify server is responding
-   if ! curl -f http://localhost:${PORT:-3000}/api/health && ! curl -f http://localhost:${PORT:-3000}; then
-     echo "ERROR: Server failed to start after restart"
-     exit 1
-   fi
-   ```
-
-5. **Query for test data - it MUST still exist**
-   - Via UI: Navigate to data location, verify data appears
-   - Via API: `curl http://localhost:${PORT:-3000}/api/items` - verify data in response
-
-6. **If data is GONE:** Implementation uses in-memory storage → CRITICAL FAIL
-   - Run all grep commands from STEP 5.6 to identify the mock pattern
-   - You MUST fix the in-memory storage implementation before proceeding
-   - Replace in-memory storage with real database queries
-
-7. **Clean up test data** after successful verification
-
-**Why this test exists:** In-memory stores like `globalThis.devStore` pass all other tests because data persists during a single server run. Only a full server restart reveals this bug. Skipping this step WILL allow dev-store implementations to slip through.
-
-**YOLO Mode Note:** Even in YOLO mode, this verification is MANDATORY for data features. Use curl instead of browser automation.
 
 ### STEP 6: UPDATE FEATURE STATUS (CAREFULLY!)
 

.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

@@ -36,7 +36,7 @@
 
 # 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.
+# This only affects AutoForge - your global Claude Code settings remain unchanged.
 # Get an API key at: https://z.ai/subscribe
 #
 # ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic

.gitignore

@@ -2,6 +2,7 @@
 generations/
 automaker/
 temp/
+temp-docs/
 
 nul
 issues/
@@ -76,6 +77,8 @@ ui/playwright-report/
 .dmypy.json
 dmypy.json
 
+.ruff_cache/
+
 # ===================
 # Claude Code
 # ===================
@@ -112,6 +115,7 @@ Desktop.ini
 ui/dist/
 ui/.vite/
 .vite/
+*.tgz
 
 # ===================
 # Environment files

.npmignore

@@ -0,0 +1,32 @@
+venv/
+**/__pycache__/
+**/*.pyc
+.git/
+.github/
+node_modules/
+test_*.py
+tests/
+generations/
+*.db
+.env
+requirements.txt
+CLAUDE.md
+LICENSE.md
+README.md
+ui/src/
+ui/node_modules/
+ui/tsconfig*.json
+ui/vite.config.ts
+ui/eslint.config.js
+ui/index.html
+ui/public/
+ui/playwright.config.ts
+ui/tests/
+start.bat
+start_ui.bat
+start.sh
+start_ui.sh
+start_ui.py
+.claude/agents/
+.claude/skills/
+.claude/settings.json

CLAUDE.md

@@ -17,18 +17,28 @@ This is an autonomous coding agent system with a React-based UI. It uses the Cla
 
 ## Commands
 
-### Quick Start (Recommended)
+### npm Global Install (Recommended)
 
 ```bash
-# Windows - launches CLI menu
+npm install -g autoforge-ai
-start.bat
+autoforge                    # Start server (first run sets up Python venv)
+autoforge config             # Edit ~/.autoforge/.env in $EDITOR
+autoforge config --show      # Print active configuration
+autoforge --port 9999        # Custom port
+autoforge --no-browser       # Don't auto-open browser
+autoforge --repair           # Delete and recreate ~/.autoforge/venv/
+```
 
-# macOS/Linux
+### From Source (Development)
-./start.sh
 
+```bash
 # Launch Web UI (serves pre-built React app)
 start_ui.bat      # Windows
 ./start_ui.sh     # macOS/Linux
+
+# CLI menu
+start.bat         # Windows
+./start.sh        # macOS/Linux
 ```
 
 ### Python Backend (Manual)
@@ -54,6 +64,12 @@ python autonomous_agent_demo.py --project-dir my-app --yolo
 
 # Parallel mode: run multiple agents concurrently (1-5 agents)
 python autonomous_agent_demo.py --project-dir my-app --parallel --max-concurrency 3
+
+# Batch mode: implement multiple features per agent session (1-3)
+python autonomous_agent_demo.py --project-dir my-app --batch-size 3
+
+# Batch specific features by ID
+python autonomous_agent_demo.py --project-dir my-app --batch-features 1,2,3
 ```
 
 ### YOLO Mode (Rapid Prototyping)
@@ -68,7 +84,7 @@ python autonomous_agent_demo.py --project-dir my-app --yolo
 ```
 
 **What's different in YOLO mode:**
-- No regression testing (skips `feature_get_for_regression`)
+- No regression testing
 - No Playwright MCP server (browser automation disabled)
 - Features marked passing after lint/type-check succeeds
 - Faster iteration for prototyping
@@ -97,10 +113,13 @@ npm run lint     # Run ESLint
 ### Python
 
 ```bash
-ruff check .                      # Lint
+ruff check .                          # Lint
-mypy .                            # Type check
+mypy .                                # Type check
-python test_security.py           # Security unit tests (163 tests)
+python test_security.py               # Security unit tests (12 tests)
-python test_security_integration.py  # Integration tests (9 tests)
+python test_security_integration.py   # Integration tests (9 tests)
+python -m pytest test_client.py       # Client tests (20 tests)
+python -m pytest test_dependency_resolver.py  # Dependency resolver tests (12 tests)
+python -m pytest test_rate_limit_utils.py     # Rate limit tests (22 tests)
 ```
 
 ### React UI
@@ -108,11 +127,17 @@ python test_security_integration.py  # Integration tests (9 tests)
 ```bash
 cd ui
 npm run lint          # ESLint
-npm run build         # Type check + build
+npm run build         # Type check + build (Vite 7)
 npm run test:e2e      # Playwright end-to-end tests
 npm run test:e2e:ui   # Playwright tests with UI
 ```
 
+### CI/CD
+
+GitHub Actions (`.github/workflows/ci.yml`) runs on push/PR to master:
+- **Python job**: ruff lint + security tests
+- **UI job**: ESLint + TypeScript build
+
 ### Code Quality
 
 Configuration in `pyproject.toml`:
@@ -121,23 +146,40 @@ Configuration in `pyproject.toml`:
 
 ## Architecture
 
+### npm CLI (bin/, lib/)
+
+The `autoforge` command is a Node.js wrapper that manages the Python environment and server lifecycle:
+- `bin/autoforge.js` - Entry point (shebang script)
+- `lib/cli.js` - Main CLI logic: Python 3.11+ detection (cross-platform), venv management at `~/.autoforge/venv/` with composite marker (requirements hash + Python version), `.env` config loading from `~/.autoforge/.env`, uvicorn server startup with PID file, and signal handling
+- `package.json` - npm package config (`autoforge-ai` on npm), `files` whitelist with `__pycache__` exclusions, `prepublishOnly` builds the UI
+- `requirements-prod.txt` - Runtime-only Python deps (excludes ruff, mypy, pytest)
+- `.npmignore` - Excludes dev files, tests, UI source from the published tarball
+
+Publishing: `npm publish` (triggers `prepublishOnly` which builds UI, then publishes ~600KB tarball with 84 files)
+
 ### Core Python Modules
 
 - `start.py` - CLI launcher with project creation/selection menu
-- `autonomous_agent_demo.py` - Entry point for running the agent
+- `autonomous_agent_demo.py` - Entry point for running the agent (supports `--yolo`, `--parallel`, `--batch-size`, `--batch-features`)
+- `autoforge_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
+- `client.py` - ClaudeSDKClient configuration with security hooks, MCP servers, and Vertex AI support
 - `security.py` - Bash command allowlist validation (ALLOWED_COMMANDS whitelist)
-- `prompts.py` - Prompt template loading with project-specific fallback
+- `prompts.py` - Prompt template loading with project-specific fallback and batch feature prompts
 - `progress.py` - Progress tracking, database queries, webhook notifications
-- `registry.py` - Project registry for mapping names to paths (cross-platform)
+- `registry.py` - Project registry for mapping names to paths (cross-platform), global settings model
 - `parallel_orchestrator.py` - Concurrent agent execution with dependency-aware scheduling
+- `auth.py` - Authentication error detection for Claude CLI
+- `env_constants.py` - Shared environment variable constants (API_ENV_VARS) used by client.py and chat sessions
+- `rate_limit_utils.py` - Rate limit detection, retry parsing, exponential backoff with jitter
+- `api/database.py` - SQLAlchemy models (Feature, Schedule, ScheduleOverride)
 - `api/dependency_resolver.py` - Cycle detection (Kahn's algorithm + DFS) and dependency validation
+- `api/migration.py` - JSON-to-SQLite migration utility
 
 ### Project Registry
 
 Projects can be stored in any directory. The registry maps project names to paths using SQLite:
-- **All platforms**: `~/.autocoder/registry.db`
+- **All platforms**: `~/.autoforge/registry.db`
 
 The registry uses:
 - SQLite database with SQLAlchemy ORM
@@ -146,13 +188,36 @@ The registry uses:
 
 ### Server API (server/)
 
-The FastAPI server provides REST endpoints for the UI:
+The FastAPI server provides REST and WebSocket endpoints for the UI:
 
-- `server/routers/projects.py` - Project CRUD with registry integration
+**Routers** (`server/routers/`):
-- `server/routers/features.py` - Feature management
+- `projects.py` - Project CRUD with registry integration
-- `server/routers/agent.py` - Agent control (start/stop/pause/resume)
+- `features.py` - Feature management
-- `server/routers/filesystem.py` - Filesystem browser API with security controls
+- `agent.py` - Agent control (start/stop/pause/resume)
-- `server/routers/spec_creation.py` - WebSocket for interactive spec creation
+- `filesystem.py` - Filesystem browser API with security controls
+- `spec_creation.py` - WebSocket for interactive spec creation
+- `expand_project.py` - Interactive project expansion via natural language
+- `assistant_chat.py` - Read-only project assistant chat (WebSocket/REST)
+- `terminal.py` - Interactive terminal I/O with PTY support (WebSocket bidirectional)
+- `devserver.py` - Dev server control (start/stop) and config
+- `schedules.py` - CRUD for time-based agent scheduling
+- `settings.py` - Global settings management (model selection, YOLO, batch size, headless browser)
+
+**Services** (`server/services/`):
+- `process_manager.py` - Agent process lifecycle management
+- `project_config.py` - Project type detection and dev command management
+- `terminal_manager.py` - Terminal session management with PTY (`pywinpty` on Windows)
+- `scheduler_service.py` - APScheduler-based automated agent scheduling
+- `dev_server_manager.py` - Dev server lifecycle management
+- `assistant_chat_session.py` / `assistant_database.py` - Assistant chat sessions with SQLite persistence
+- `spec_chat_session.py` - Spec creation chat sessions
+- `expand_chat_session.py` - Expand project chat sessions
+- `chat_constants.py` - Shared constants for chat services
+
+**Utilities** (`server/utils/`):
+- `process_utils.py` - Process management utilities
+- `project_helpers.py` - Project path resolution helpers
+- `validation.py` - Project name validation
 
 ### Feature Management
 
@@ -163,18 +228,26 @@ Features are stored in SQLite (`features.db`) via SQLAlchemy. The agent interact
 
 MCP tools available to the agent:
 - `feature_get_stats` - Progress statistics
-- `feature_get_next` - Get highest-priority pending feature (respects dependencies)
+- `feature_get_by_id` - Get a single feature by ID
-- `feature_claim_next` - Atomically claim next available feature (for parallel mode)
+- `feature_get_summary` - Get summary of all features
-- `feature_get_for_regression` - Random passing features for regression testing
+- `feature_get_ready` - Get features ready to work on (dependencies met)
+- `feature_get_blocked` - Get features blocked by unmet dependencies
+- `feature_get_graph` - Get full dependency graph
+- `feature_claim_and_get` - Atomically claim next available feature (for parallel mode)
+- `feature_mark_in_progress` - Mark feature as in progress
 - `feature_mark_passing` - Mark feature complete
+- `feature_mark_failing` - Mark feature as failing
 - `feature_skip` - Move feature to end of queue
+- `feature_clear_in_progress` - Clear in-progress status
 - `feature_create_bulk` - Initialize all features (used by initializer)
+- `feature_create` - Create a single feature
 - `feature_add_dependency` - Add dependency between features (with cycle detection)
 - `feature_remove_dependency` - Remove a dependency
+- `feature_set_dependencies` - Set all dependencies for a feature at once
 
 ### React UI (ui/)
 
-- Tech stack: React 19, TypeScript, TanStack Query, Tailwind CSS v4, Radix UI, dagre (graph layout)
+- Tech stack: React 19, TypeScript, Vite 7, TanStack Query, Tailwind CSS v4, Radix UI, dagre (graph layout), xterm.js (terminal)
 - `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
@@ -186,6 +259,17 @@ Key components:
 - `DependencyGraph.tsx` - Interactive node graph visualization with dagre layout
 - `CelebrationOverlay.tsx` - Confetti animation on feature completion
 - `FolderBrowser.tsx` - Server-side filesystem browser for project folder selection
+- `Terminal.tsx` / `TerminalTabs.tsx` - xterm.js-based multi-tab terminal
+- `AssistantPanel.tsx` / `AssistantChat.tsx` - AI assistant for project Q&A
+- `ExpandProjectModal.tsx` / `ExpandProjectChat.tsx` - Add features via natural language
+- `DevServerControl.tsx` - Dev server start/stop control
+- `ScheduleModal.tsx` - Schedule management UI
+- `SettingsModal.tsx` - Global settings panel
+
+In-app documentation (`/#/docs` route):
+- `src/components/docs/sections/` - Content for each doc section (GettingStarted.tsx, AgentSystem.tsx, etc.)
+- `src/components/docs/docsData.ts` - Sidebar structure, subsection IDs, search keywords
+- `src/components/docs/DocsPage.tsx` - Page layout; `DocsContent.tsx` - section renderer with scroll tracking
 
 Keyboard shortcuts (press `?` for help):
 - `D` - Toggle debug panel
@@ -196,13 +280,18 @@ 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:
+Projects can be stored in any directory (registered in `~/.autoforge/registry.db`). Each project contains:
-- `prompts/app_spec.txt` - Application specification (XML format)
+- `.autoforge/prompts/app_spec.txt` - Application specification (XML format)
-- `prompts/initializer_prompt.md` - First session prompt
+- `.autoforge/prompts/initializer_prompt.md` - First session prompt
-- `prompts/coding_prompt.md` - Continuation session prompt
+- `.autoforge/prompts/coding_prompt.md` - Continuation session prompt
-- `features.db` - SQLite database with feature test cases
+- `.autoforge/features.db` - SQLite database with feature test cases
-- `.agent.lock` - Lock file to prevent multiple agent instances
+- `.autoforge/.agent.lock` - Lock file to prevent multiple agent instances
-- `.autocoder/allowed_commands.yaml` - Project-specific bash command allowlist (optional)
+- `.autoforge/allowed_commands.yaml` - Project-specific bash command allowlist (optional)
+- `.autoforge/.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 `.autoforge/` on next agent start. Dual-path resolution ensures old and new layouts work transparently.
 
 ### Security Model
 
@@ -242,29 +331,20 @@ The following directories (relative to home) are always blocked:
 - `.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:
 
 **Command Hierarchy (highest to lowest priority):**
 1. **Hardcoded Blocklist** (`security.py`) - NEVER allowed (dd, sudo, shutdown, etc.)
-2. **Org Blocklist** (`~/.autocoder/config.yaml`) - Cannot be overridden by projects
+2. **Org Blocklist** (`~/.autoforge/config.yaml`) - Cannot be overridden by projects
-3. **Org Allowlist** (`~/.autocoder/config.yaml`) - Available to all projects
+3. **Org Allowlist** (`~/.autoforge/config.yaml`) - Available to all projects
 4. **Global Allowlist** (`security.py`) - Default commands (npm, git, curl, etc.)
-5. **Project Allowlist** (`.autocoder/allowed_commands.yaml`) - Project-specific commands
+5. **Project Allowlist** (`.autoforge/allowed_commands.yaml`) - Project-specific commands
 
 **Project Configuration:**
 
-Each project can define custom allowed commands in `.autocoder/allowed_commands.yaml`:
+Each project can define custom allowed commands in `.autoforge/allowed_commands.yaml`:
 
 ```yaml
 version: 1
@@ -284,7 +364,7 @@ commands:
 
 **Organization Configuration:**
 
-System administrators can set org-wide policies in `~/.autocoder/config.yaml`:
+System administrators can set org-wide policies in `~/.autoforge/config.yaml`:
 
 ```yaml
 version: 1
@@ -312,13 +392,28 @@ blocked_commands:
 
 **Files:**
 - `security.py` - Command validation logic and hardcoded blocklist
-- `test_security.py` - Unit tests for security system (136 tests)
+- `test_security.py` - Unit tests for security system
-- `test_security_integration.py` - Integration tests with real hooks (9 tests)
+- `test_security_integration.py` - Integration tests with real hooks
-- `TEST_SECURITY.md` - Quick testing reference guide
 - `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)
+
+### Vertex AI Configuration (Optional)
+
+Run coding agents via Google Cloud Vertex AI:
+
+1. Install and authenticate gcloud CLI: `gcloud auth application-default login`
+2. Configure `.env`:
+   ```
+   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
+   ```
+
+**Note:** Use `@` instead of `-` in model names for Vertex AI.
 
 ### Ollama Local Models (Optional)
 
@@ -336,7 +431,7 @@ Run coding agents using local models via Ollama v0.14.0+:
    ANTHROPIC_DEFAULT_OPUS_MODEL=qwen3-coder
    ANTHROPIC_DEFAULT_HAIKU_MODEL=qwen3-coder
    ```
-5. Run autocoder normally - it will use your local Ollama models
+5. Run AutoForge normally - it will use your local Ollama models
 
 **Recommended coding models:**
 - `qwen3-coder` - Good balance of speed and capability
@@ -355,8 +450,24 @@ Run coding agents using local models via Ollama v0.14.0+:
 
 ## Claude Code Integration
 
-- `.claude/commands/create-spec.md` - `/create-spec` slash command for interactive spec creation
+**Slash commands** (`.claude/commands/`):
-- `.claude/skills/frontend-design/SKILL.md` - Skill for distinctive UI design
+- `/create-spec` - Interactive spec creation for new projects
+- `/expand-project` - Expand existing project with new features
+- `/gsd-to-autoforge-spec` - Convert GSD codebase mapping to app_spec.txt
+- `/check-code` - Run lint and type-check for code quality
+- `/checkpoint` - Create comprehensive checkpoint commit
+- `/review-pr` - Review pull requests
+
+**Custom agents** (`.claude/agents/`):
+- `coder.md` - Elite software architect agent for code implementation (Opus)
+- `code-review.md` - Code review agent for quality/security/performance analysis (Opus)
+- `deep-dive.md` - Technical investigator for deep analysis and debugging (Opus)
+
+**Skills** (`.claude/skills/`):
+- `frontend-design` - Distinctive, production-grade UI design
+- `gsd-to-autoforge-spec` - Convert GSD codebase mapping to AutoForge app_spec format
+
+**Other:**
 - `.claude/templates/` - Prompt templates copied to new projects
 - `examples/` - Configuration examples and documentation for security settings
 
@@ -364,12 +475,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}/.autoforge/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 `.autoforge/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
@@ -387,7 +498,7 @@ The UI receives updates via WebSocket (`/ws/projects/{project_name}`):
 
 When running with `--parallel`, the orchestrator:
 1. Spawns multiple Claude agents as subprocesses (up to `--max-concurrency`)
-2. Each agent claims features atomically via `feature_claim_next`
+2. Each agent claims features atomically via `feature_claim_and_get`
 3. Features blocked by unmet dependencies are skipped
 4. Browser contexts are isolated per agent using `--isolated` flag
 5. AgentTracker parses output and emits `agent_update` messages for UI
@@ -400,6 +511,16 @@ The orchestrator enforces strict bounds on concurrent processes:
 - 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)
 
+### Multi-Feature Batching
+
+Agents can implement multiple features per session using `--batch-size` (1-3, default: 3):
+- `--batch-size N` - Max features per coding agent batch
+- `--testing-batch-size N` - Features per testing batch (1-5, default: 3)
+- `--batch-features 1,2,3` - Specific feature IDs for batch implementation
+- `--testing-batch-features 1,2,3` - Specific feature IDs for batch regression testing
+- `prompts.py` provides `get_batch_feature_prompt()` for multi-feature prompt generation
+- Configurable in UI via settings panel
+
 ### Design System
 
 The UI uses a **neobrutalism** design with Tailwind CSS v4:

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

README.md

@@ -1,4 +1,4 @@
-# AutoCoder
+# AutoForge
 
 [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-FFDD00?style=flat&logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/leonvanzyl)
 
@@ -14,9 +14,11 @@ A long-running autonomous coding agent powered by the Claude Agent SDK. This too
 
 ## Prerequisites
 
-### Claude Code CLI (Required)
+- **Node.js 20+** - Required for the CLI
+- **Python 3.11+** - Auto-detected on first run ([download](https://www.python.org/downloads/))
+- **Claude Code CLI** - Install and authenticate (see below)
 
-This project requires the Claude Code CLI to be installed. Install it using one of these methods:
+### Claude Code CLI (Required)
 
 **macOS / Linux:**
 ```bash
@@ -39,35 +41,63 @@ You need one of the following:
 
 ## Quick Start
 
-### Option 1: Web UI (Recommended)
+### Option 1: npm Install (Recommended)
 
-**Windows:**
-```cmd
-start_ui.bat
-```
-
-**macOS / Linux:**
 ```bash
-./start_ui.sh
+npm install -g autoforge-ai
+autoforge
 ```
 
+On first run, AutoForge automatically:
+1. Checks for Python 3.11+
+2. Creates a virtual environment at `~/.autoforge/venv/`
+3. Installs Python dependencies
+4. Copies a default config file to `~/.autoforge/.env`
+5. Starts the server and opens your browser
+
+### CLI Commands
+
+```
+autoforge                       Start the server (default)
+autoforge config                Open ~/.autoforge/.env in $EDITOR
+autoforge config --path         Print config file path
+autoforge config --show         Show active configuration values
+autoforge --port PORT           Custom port (default: auto from 8888)
+autoforge --host HOST           Custom host (default: 127.0.0.1)
+autoforge --no-browser          Don't auto-open browser
+autoforge --repair              Delete and recreate virtual environment
+autoforge --version             Print version
+autoforge --help                Show help
+```
+
+### Option 2: From Source (Development)
+
+Clone the repository and use the start scripts directly. This is the recommended path if you want to contribute or modify AutoForge itself.
+
+```bash
+git clone https://github.com/leonvanzyl/autoforge.git
+cd autoforge
+```
+
+**Web UI:**
+
+| Platform | Command |
+|---|---|
+| Windows | `start_ui.bat` |
+| macOS / Linux | `./start_ui.sh` |
+
 This launches the React-based web UI at `http://localhost:5173` with:
 - Project selection and creation
 - Kanban board view of features
 - Real-time agent output streaming
 - Start/pause/stop controls
 
-### Option 2: CLI Mode
+**CLI Mode:**
 
-**Windows:**
+| Platform | Command |
-```cmd
+|---|---|
-start.bat
+| Windows | `start.bat` |
-```
+| macOS / Linux | `./start.sh` |
-
-**macOS / Linux:**
-```bash
-./start.sh
-```
 
 The start script will:
 1. Check if Claude CLI is installed
@@ -130,44 +160,43 @@ Features are stored in SQLite via SQLAlchemy and managed through an MCP server t
 ## Project Structure
 
 ```
-autonomous-coding/
+autoforge/
-├── start.bat                 # Windows CLI start script
+├── bin/                         # npm CLI entry point
-├── start.sh                  # macOS/Linux CLI start script
+├── lib/                         # CLI bootstrap and setup logic
-├── start_ui.bat              # Windows Web UI start script
+├── start.py                     # CLI menu and project management
-├── start_ui.sh               # macOS/Linux Web UI start script
+├── start_ui.py                  # Web UI backend (FastAPI server launcher)
-├── start.py                  # CLI menu and project management
+├── autonomous_agent_demo.py     # Agent entry point
-├── start_ui.py               # Web UI backend (FastAPI server launcher)
+├── agent.py                     # Agent session logic
-├── autonomous_agent_demo.py  # Agent entry point
+├── client.py                    # Claude SDK client configuration
-├── agent.py                  # Agent session logic
+├── security.py                  # Bash command allowlist and validation
-├── client.py                 # Claude SDK client configuration
+├── progress.py                  # Progress tracking utilities
-├── security.py               # Bash command allowlist and validation
+├── prompts.py                   # Prompt loading utilities
-├── progress.py               # Progress tracking utilities
-├── prompts.py                # Prompt loading utilities
 ├── api/
-│   └── database.py           # SQLAlchemy models (Feature table)
+│   └── database.py              # SQLAlchemy models (Feature table)
 ├── mcp_server/
-│   └── feature_mcp.py        # MCP server for feature management tools
+│   └── feature_mcp.py           # MCP server for feature management tools
 ├── server/
-│   ├── main.py               # FastAPI REST API server
+│   ├── main.py                  # FastAPI REST API server
-│   ├── websocket.py          # WebSocket handler for real-time updates
+│   ├── websocket.py             # WebSocket handler for real-time updates
-│   ├── schemas.py            # Pydantic schemas
+│   ├── schemas.py               # Pydantic schemas
-│   ├── routers/              # API route handlers
+│   ├── routers/                 # API route handlers
-│   └── services/             # Business logic services
+│   └── services/                # Business logic services
-├── ui/                       # React frontend
+├── ui/                          # React frontend
 │   ├── src/
-│   │   ├── App.tsx           # Main app component
+│   │   ├── App.tsx              # Main app component
-│   │   ├── hooks/            # React Query and WebSocket hooks
+│   │   ├── hooks/               # React Query and WebSocket hooks
-│   │   └── lib/              # API client and types
+│   │   └── lib/                 # API client and types
 │   ├── package.json
 │   └── vite.config.ts
 ├── .claude/
 │   ├── commands/
-│   │   └── create-spec.md    # /create-spec slash command
+│   │   └── create-spec.md       # /create-spec slash command
-│   ├── skills/               # Claude Code skills
+│   ├── skills/                  # Claude Code skills
-│   └── templates/            # Prompt templates
+│   └── templates/               # Prompt templates
-├── generations/              # Generated projects go here
+├── requirements.txt             # Python dependencies (development)
-├── requirements.txt          # Python dependencies
+├── requirements-prod.txt        # Python dependencies (npm install)
-└── .env                      # Optional configuration (N8N webhook)
+├── package.json                 # npm package definition
+└── .env                         # Optional configuration
 ```
 
 ---
@@ -264,11 +293,20 @@ The UI receives live updates via WebSocket (`/ws/projects/{project_name}`):
 
 ---
 
-## Configuration (Optional)
+## Configuration
+
+AutoForge reads configuration from a `.env` file. The file location depends on how you installed AutoForge:
+
+| Install method | Config file location | Edit command |
+|---|---|---|
+| npm (global) | `~/.autoforge/.env` | `autoforge config` |
+| From source | `.env` in the project root | Edit directly |
+
+A default config file is created automatically on first run. Use `autoforge config` to open it in your editor, or `autoforge config --show` to print the active values.
 
 ### N8N Webhook Integration
 
-The agent can send progress notifications to an N8N webhook. Create a `.env` file:
+Add to your `.env` to send progress notifications to an N8N webhook:
 
 ```bash
 # Optional: N8N webhook for progress notifications
@@ -290,7 +328,7 @@ When test progress increases, the agent sends:
 
 ### Using GLM Models (Alternative to Claude)
 
-To use Zhipu AI's GLM models instead of Claude, add these variables to your `.env` file in the AutoCoder directory:
+Add these variables to your `.env` file to use Zhipu AI's GLM models:
 
 ```bash
 ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic
@@ -301,10 +339,40 @@ ANTHROPIC_DEFAULT_OPUS_MODEL=glm-4.7
 ANTHROPIC_DEFAULT_HAIKU_MODEL=glm-4.5-air
 ```
 
-This routes AutoCoder's API requests through Zhipu's Claude-compatible API, allowing you to use GLM-4.7 and other models. **This only affects AutoCoder** - your global Claude Code settings remain unchanged.
+This routes AutoForge's API requests through Zhipu's Claude-compatible API, allowing you to use GLM-4.7 and other models. **This only affects AutoForge** - your global Claude Code settings remain unchanged.
 
 Get an API key at: https://z.ai/subscribe
 
+### Using Ollama Local Models
+
+Add these variables to your `.env` file to run agents with local models via Ollama v0.14.0+:
+
+```bash
+ANTHROPIC_BASE_URL=http://localhost:11434
+ANTHROPIC_AUTH_TOKEN=ollama
+API_TIMEOUT_MS=3000000
+ANTHROPIC_DEFAULT_SONNET_MODEL=qwen3-coder
+ANTHROPIC_DEFAULT_OPUS_MODEL=qwen3-coder
+ANTHROPIC_DEFAULT_HAIKU_MODEL=qwen3-coder
+```
+
+See the [CLAUDE.md](CLAUDE.md) for recommended models and known limitations.
+
+### Using Vertex AI
+
+Add these variables to your `.env` file to run agents via Google Cloud Vertex AI:
+
+```bash
+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
+```
+
+Requires `gcloud auth application-default login` first. Note the `@` separator (not `-`) in Vertex AI model names.
+
 ---
 
 ## Customization
@@ -335,6 +403,18 @@ This is normal. The initializer agent is generating detailed test cases, which t
 **"Command blocked by security hook"**
 The agent tried to run a command not in the allowlist. This is the security system working as intended. If needed, add the command to `ALLOWED_COMMANDS` in `security.py`.
 
+**"Python 3.11+ required but not found"**
+Install Python 3.11 or later from [python.org](https://www.python.org/downloads/). Make sure `python3` (or `python` on Windows) is on your PATH.
+
+**"Python venv module not available"**
+On Debian/Ubuntu, the venv module is packaged separately. Install it with `sudo apt install python3.XX-venv` (replace `XX` with your Python minor version, e.g., `python3.12-venv`).
+
+**"AutoForge is already running"**
+A server instance is already active. Use the browser URL shown in the terminal, or stop the existing instance with Ctrl+C first.
+
+**Virtual environment issues after a Python upgrade**
+Run `autoforge --repair` to delete and recreate the virtual environment from scratch.
+
 ---
 
 ## License

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 autoforge_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,6 +336,35 @@ 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.
@@ -351,21 +384,41 @@ def create_database(project_dir: Path) -> tuple:
         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 .autoforge/ 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)
@@ -417,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.
 
@@ -429,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
@@ -301,19 +302,20 @@ def compute_scheduling_scores(features: list[dict]) -> dict[int, float]:
 
     # 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 in visited:
             continue  # Skip already visited nodes (handles cycles)
         visited.add(node_id)
         depths[node_id] = depth
         for child_id in children[node_id]:
             if child_id not in visited:
-                queue.append((child_id, depth + 1))
+                bfs_queue.append((child_id, depth + 1))
 
     # Handle orphaned nodes (shouldn't happen but be safe)
     for f in features:

autoforge_paths.py

@@ -0,0 +1,315 @@
+"""
+AutoForge Path Resolution
+=========================
+
+Central module for resolving paths to autoforge-generated files within a project.
+
+Implements a tri-path resolution strategy for backward compatibility:
+
+    1. Check ``project_dir / ".autoforge" / X`` (current layout)
+    2. Check ``project_dir / ".autocoder" / X`` (legacy layout)
+    3. Check ``project_dir / X`` (legacy root-level layout)
+    4. 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 ``.autoforge/``.
+Projects using the old ``.autocoder/`` directory are auto-migrated on next start.
+
+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 .autoforge/ directory
+# ---------------------------------------------------------------------------
+_GITIGNORE_CONTENT = """\
+# AutoForge 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 tri-path strategy.
+
+    Checks the new ``.autoforge/`` location first, then the legacy
+    ``.autocoder/`` location, then the root-level location.  If none exist,
+    returns the new location so that newly-created files land in ``.autoforge/``.
+    """
+    new = project_dir / ".autoforge" / filename
+    if new.exists():
+        return new
+    legacy = project_dir / ".autocoder" / filename
+    if legacy.exists():
+        return legacy
+    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 tri-path strategy.
+
+    Same logic as ``_resolve_path`` but intended for directories such as
+    ``prompts/``.
+    """
+    new = project_dir / ".autoforge" / dirname
+    if new.exists():
+        return new
+    legacy = project_dir / ".autocoder" / dirname
+    if legacy.exists():
+        return legacy
+    old = project_dir / dirname
+    if old.exists():
+        return old
+    return new
+
+
+# ---------------------------------------------------------------------------
+# .autoforge directory management
+# ---------------------------------------------------------------------------
+
+def get_autoforge_dir(project_dir: Path) -> Path:
+    """Return the ``.autoforge`` directory path.  Does NOT create it."""
+    return project_dir / ".autoforge"
+
+
+def ensure_autoforge_dir(project_dir: Path) -> Path:
+    """Create the ``.autoforge/`` directory (if needed) and write its ``.gitignore``.
+
+    Returns:
+        The path to the ``.autoforge`` directory.
+    """
+    autoforge_dir = get_autoforge_dir(project_dir)
+    autoforge_dir.mkdir(parents=True, exist_ok=True)
+
+    gitignore_path = autoforge_dir / ".gitignore"
+    gitignore_path.write_text(_GITIGNORE_CONTENT, encoding="utf-8")
+
+    return autoforge_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 ``.autoforge/``.
+    """
+    return project_dir / ".autoforge" / 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 the legacy root-level paths, the old ``.autocoder/`` paths, and
+    the new ``.autoforge/`` 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
+        # Check both old and new directory names for backward compatibility
+        if (project_dir / ".autocoder" / name).exists():
+            return True
+        if (project_dir / ".autoforge" / 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 ``.autoforge/``.
+
+    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/ -> .autoforge/prompts/", "features.db -> .autoforge/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 []
+
+    # --- 0. Migrate .autocoder/ → .autoforge/ directory -------------------
+    old_autocoder_dir = project_dir / ".autocoder"
+    new_autoforge_dir = project_dir / ".autoforge"
+    if old_autocoder_dir.exists() and old_autocoder_dir.is_dir() and not new_autoforge_dir.exists():
+        try:
+            old_autocoder_dir.rename(new_autoforge_dir)
+            logger.info("Migrated .autocoder/ -> .autoforge/")
+            migrated: list[str] = [".autocoder/ -> .autoforge/"]
+        except Exception:
+            logger.warning("Failed to migrate .autocoder/ -> .autoforge/", exc_info=True)
+            migrated = []
+    else:
+        migrated = []
+
+    autoforge_dir = ensure_autoforge_dir(project_dir)
+
+    # --- 1. Migrate prompts/ directory -----------------------------------
+    try:
+        old_prompts = project_dir / "prompts"
+        new_prompts = autoforge_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/ -> .autoforge/prompts/")
+            logger.info("Migrated prompts/ -> .autoforge/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 = autoforge_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} -> .autoforge/{db_name}")
+                logger.info("Migrated %s -> .autoforge/%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 = autoforge_dir / filename
+            if old_file.exists() and not new_file.exists():
+                shutil.move(str(old_file), str(new_file))
+                migrated.append(f"{filename} -> .autoforge/{filename}")
+                logger.info("Migrated %s -> .autoforge/%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 .autoforge/ if needed (idempotent, safe)
+    from autoforge_paths import migrate_project_layout
+    migrated = migrate_project_layout(project_dir)
+    if migrated:
+        print(f"Migrated project files to .autoforge/: {', '.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,12 +255,25 @@ 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:
             # Entry point mode - always use unified orchestrator
+            # Clean up stale temp files before starting (prevents temp folder bloat)
+            from temp_cleanup import cleanup_stale_temp
+            cleanup_stats = cleanup_stale_temp()
+            if cleanup_stats["dirs_deleted"] > 0 or cleanup_stats["files_deleted"] > 0:
+                mb_freed = cleanup_stats["bytes_freed"] / (1024 * 1024)
+                print(
+                    f"[CLEANUP] Removed {cleanup_stats['dirs_deleted']} dirs, "
+                    f"{cleanup_stats['files_deleted']} files ({mb_freed:.1f} MB freed)",
+                    flush=True,
+                )
+
             from parallel_orchestrator import run_parallel_orchestrator
 
             # Clamp concurrency to valid range (1-5)
@@ -223,6 +288,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:

bin/autoforge.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../lib/cli.js';
+run(process.argv.slice(2));

client.py

@@ -16,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()
@@ -31,43 +32,15 @@ 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
-# These allow using alternative API endpoints (e.g., GLM via z.ai, Vertex AI) without
-# affecting the user's global Claude Code settings
-API_ENV_VARS = [
-    "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
-    "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
-]
-
 # Extra read paths for cross-project file access (read-only)
 # Set EXTRA_READ_PATHS environment variable with comma-separated absolute paths
 # Example: EXTRA_READ_PATHS=/Volumes/Data/dev,/Users/shared/libs
 EXTRA_READ_PATHS_VAR = "EXTRA_READ_PATHS"
 
-# Sensitive directories that should never be allowed via EXTRA_READ_PATHS
+# Sensitive directories that should never be allowed via EXTRA_READ_PATHS.
-# These contain credentials, keys, or system-critical files
+# Delegates to the canonical SENSITIVE_DIRECTORIES set in security.py so that
-EXTRA_READ_PATHS_BLOCKLIST = {
+# this blocklist and the filesystem browser API share a single source of truth.
-    ".ssh",
+EXTRA_READ_PATHS_BLOCKLIST = SENSITIVE_DIRECTORIES
-    ".aws",
-    ".azure",
-    ".kube",
-    ".gnupg",
-    ".gpg",
-    ".password-store",
-    ".docker",
-    ".config/gcloud",
-    ".npmrc",
-    ".pypirc",
-    ".netrc",
-}
 
 def convert_model_for_vertex(model: str) -> str:
     """
@@ -209,32 +182,55 @@ def get_extra_read_paths() -> list[Path]:
     return validated_paths
 
 
-# Feature MCP tools for feature/test management
+# Per-agent-type MCP tool lists.
-FEATURE_MCP_TOOLS = [
+# Only expose the tools each agent type actually needs, reducing tool schema
-    # Core feature operations
+# 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",
@@ -247,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",
@@ -258,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",
@@ -285,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.
@@ -295,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)
@@ -308,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(./**)",
@@ -325,11 +347,11 @@ 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)
@@ -360,7 +382,9 @@ 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 autoforge_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)
 
@@ -426,7 +450,7 @@ def create_client(
 
     # Build environment overrides for API endpoint configuration
     # These override system env vars for the Claude CLI subprocess,
-    # allowing AutoCoder to use alternative APIs (e.g., GLM) without
+    # allowing AutoForge to use alternative APIs (e.g., GLM) without
     # affecting the user's global Claude Code settings
     sdk_env = {}
     for var in API_ENV_VARS:
@@ -459,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,
@@ -474,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")
@@ -486,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,
@@ -506,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]),
@@ -518,7 +579,7 @@ 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
@@ -536,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 autoforge 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
+]

examples/OPTIMIZE_CONFIG.md

@@ -179,7 +179,7 @@ To see what you can reduce:
 
 ```bash
 # Count commands by prefix
-grep "^  - name:" .autocoder/allowed_commands.yaml | \
+grep "^  - name:" .autoforge/allowed_commands.yaml | \
   sed 's/^  - name: //' | \
   cut -d' ' -f1 | \
   sort | uniq -c | sort -rn

examples/README.md

@@ -1,4 +1,4 @@
-# AutoCoder Security Configuration Examples
+# AutoForge Security Configuration Examples
 
 This directory contains example configuration files for controlling which bash commands the autonomous coding agent can execute.
 
@@ -18,11 +18,11 @@ This directory contains example configuration files for controlling which bash c
 
 ### For a Single Project (Most Common)
 
-When you create a new project with AutoCoder, it automatically creates:
+When you create a new project with AutoForge, it automatically creates:
 
 ```text
 my-project/
-  .autocoder/
+  .autoforge/
     allowed_commands.yaml    ← Automatically created from template
 ```
 
@@ -34,17 +34,17 @@ If you want commands available across **all projects**, manually create:
 
 ```bash
 # Copy the example to your home directory
-cp examples/org_config.yaml ~/.autocoder/config.yaml
+cp examples/org_config.yaml ~/.autoforge/config.yaml
 
 # Edit it to add org-wide commands
-nano ~/.autocoder/config.yaml
+nano ~/.autoforge/config.yaml
 ```
 
 ---
 
 ## Project-Level Configuration
 
-**File:** `{project_dir}/.autocoder/allowed_commands.yaml`
+**File:** `{project_dir}/.autoforge/allowed_commands.yaml`
 
 **Purpose:** Define commands needed for THIS specific project.
 
@@ -82,7 +82,7 @@ commands:
 
 ## Organization-Level Configuration
 
-**File:** `~/.autocoder/config.yaml`
+**File:** `~/.autoforge/config.yaml`
 
 **Purpose:** Define commands and policies for ALL projects.
 
@@ -127,13 +127,13 @@ When the agent tries to run a command, the system checks in this order:
 └─────────────────────────────────────────────────────┘
                          ↓
 ┌─────────────────────────────────────────────────────┐
-│ 2. ORG BLOCKLIST (~/.autocoder/config.yaml)         │
+│ 2. ORG BLOCKLIST (~/.autoforge/config.yaml)         │
 │    Commands you block organization-wide             │
 │    ❌ Projects CANNOT override these                │
 └─────────────────────────────────────────────────────┘
                          ↓
 ┌─────────────────────────────────────────────────────┐
-│ 3. ORG ALLOWLIST (~/.autocoder/config.yaml)         │
+│ 3. ORG ALLOWLIST (~/.autoforge/config.yaml)         │
 │    Commands available to all projects               │
 │    ✅ Automatically available                       │
 └─────────────────────────────────────────────────────┘
@@ -145,7 +145,7 @@ When the agent tries to run a command, the system checks in this order:
 └─────────────────────────────────────────────────────┘
                          ↓
 ┌─────────────────────────────────────────────────────┐
-│ 5. PROJECT ALLOWLIST (.autocoder/allowed_commands)  │
+│ 5. PROJECT ALLOWLIST (.autoforge/allowed_commands)  │
 │    Project-specific commands                        │
 │    ✅ Available only to this project                │
 └─────────────────────────────────────────────────────┘
@@ -195,7 +195,7 @@ Matches:
 
 ### iOS Development
 
-**Project config** (`.autocoder/allowed_commands.yaml`):
+**Project config** (`.autoforge/allowed_commands.yaml`):
 ```yaml
 version: 1
 commands:
@@ -245,7 +245,7 @@ commands:
 
 ### Enterprise Organization (Restrictive)
 
-**Org config** (`~/.autocoder/config.yaml`):
+**Org config** (`~/.autoforge/config.yaml`):
 ```yaml
 version: 1
 
@@ -265,7 +265,7 @@ blocked_commands:
 
 ### Startup Team (Permissive)
 
-**Org config** (`~/.autocoder/config.yaml`):
+**Org config** (`~/.autoforge/config.yaml`):
 ```yaml
 version: 1
 
@@ -394,7 +394,7 @@ These commands are **NEVER allowed**, even with user approval:
 
 **Solution:** Add the command to your project config:
 ```yaml
-# In .autocoder/allowed_commands.yaml
+# In .autoforge/allowed_commands.yaml
 commands:
   - name: X
     description: What this command does
@@ -405,7 +405,7 @@ commands:
 **Cause:** The command is in the org blocklist or hardcoded blocklist.
 
 **Solution:**
-- If in org blocklist: Edit `~/.autocoder/config.yaml` to remove it
+- If in org blocklist: Edit `~/.autoforge/config.yaml` to remove it
 - If in hardcoded blocklist: Cannot be allowed (by design)
 
 ### Error: "Could not parse YAML config"
@@ -422,8 +422,8 @@ commands:
 **Solution:**
 1. Restart the agent (changes are loaded on startup)
 2. Verify file location:
-   - Project: `{project}/.autocoder/allowed_commands.yaml`
+   - Project: `{project}/.autoforge/allowed_commands.yaml`
-   - Org: `~/.autocoder/config.yaml` (must be manually created)
+   - Org: `~/.autoforge/config.yaml` (must be manually created)
 3. Check YAML is valid (run through a YAML validator)
 
 ---
@@ -432,7 +432,7 @@ commands:
 
 ### Running the Tests
 
-AutoCoder has comprehensive tests for the security system:
+AutoForge has comprehensive tests for the security system:
 
 **Unit Tests** (136 tests - fast):
 ```bash
@@ -481,7 +481,7 @@ python start.py
 cd path/to/security-test
 
 # Edit the config
-nano .autocoder/allowed_commands.yaml
+nano .autoforge/allowed_commands.yaml
 ```
 
 **3. Add a test command (e.g., Swift):**
@@ -509,7 +509,7 @@ Or:
 ```text
 Command 'wget' is not allowed.
 To allow this command:
-  1. Add to .autocoder/allowed_commands.yaml for this project, OR
+  1. Add to .autoforge/allowed_commands.yaml for this project, OR
   2. Request mid-session approval (the agent can ask)
 ```
 

examples/org_config.yaml

@@ -1,6 +1,6 @@
-# Organization-Level AutoCoder Configuration
+# Organization-Level AutoForge Configuration
 # ============================================
-# Location: ~/.autocoder/config.yaml
+# Location: ~/.autoforge/config.yaml
 #
 # IMPORTANT: This file is OPTIONAL and must be manually created by you.
 # It does NOT exist by default.
@@ -22,7 +22,7 @@ version: 1
 # Organization-Wide Allowed Commands
 # ==========================================
 # These commands become available to ALL projects automatically.
-# Projects don't need to add them to their own .autocoder/allowed_commands.yaml
+# Projects don't need to add them to their own .autoforge/allowed_commands.yaml
 #
 # By default, this is empty. Uncomment and add commands as needed.
 
@@ -122,7 +122,7 @@ approval_timeout_minutes: 5
 #    Default commands: npm, git, curl, ls, cat, etc.
 #    Always available to all projects.
 #
-# 5. Project Allowed Commands (.autocoder/allowed_commands.yaml)
+# 5. Project Allowed Commands (.autoforge/allowed_commands.yaml)
 #    Project-specific commands defined in each project.
 #    LOWEST PRIORITY (can't override blocks above).
 #
@@ -165,7 +165,7 @@ approval_timeout_minutes: 5
 # ==========================================
 # To Create This File
 # ==========================================
-# 1. Copy this example to: ~/.autocoder/config.yaml
+# 1. Copy this example to: ~/.autoforge/config.yaml
 # 2. Uncomment and customize the sections you need
 # 3. Leave empty lists if you don't need org-level controls
 #

examples/project_allowed_commands.yaml

@@ -1,12 +1,12 @@
 # Project-Specific Allowed Commands
 # ==================================
-# Location: {project_dir}/.autocoder/allowed_commands.yaml
+# Location: {project_dir}/.autoforge/allowed_commands.yaml
 #
 # This file defines bash commands that the autonomous coding agent can use
 # for THIS SPECIFIC PROJECT, beyond the default allowed commands.
 #
-# When you create a new project, AutoCoder automatically creates this file
+# When you create a new project, AutoForge automatically creates this file
-# in your project's .autocoder/ directory. You can customize it for your
+# in your project's .autoforge/ directory. You can customize it for your
 # project's specific needs (iOS, Rust, Python, etc.).
 
 version: 1
@@ -115,7 +115,7 @@ commands: []
 # Limits:
 #   - Maximum 100 commands per project
 #   - Commands in the blocklist (sudo, dd, shutdown, etc.) can NEVER be allowed
-#   - Org-level blocked commands (see ~/.autocoder/config.yaml) cannot be overridden
+#   - Org-level blocked commands (see ~/.autoforge/config.yaml) cannot be overridden
 #
 # Default Allowed Commands (always available):
 #   File operations: ls, cat, head, tail, wc, grep, cp, mkdir, mv, rm, touch

lib/cli.js

@@ -0,0 +1,791 @@
+/**
+ * AutoForge CLI
+ * =============
+ *
+ * Main CLI module for the AutoForge npm global package.
+ * Handles Python detection, virtual environment management,
+ * config loading, and uvicorn server lifecycle.
+ *
+ * Uses only Node.js built-in modules -- no external dependencies.
+ */
+
+import { execFileSync, spawn, execSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync, rmSync, copyFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { createServer } from 'node:net';
+import { homedir, platform } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// ---------------------------------------------------------------------------
+// Path constants
+// ---------------------------------------------------------------------------
+
+/** Root of the autoforge npm package (one level up from lib/) */
+const PKG_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/** User config home: ~/.autoforge/ */
+const CONFIG_HOME = join(homedir(), '.autoforge');
+
+/** Virtual-environment directory managed by the CLI */
+const VENV_DIR = join(CONFIG_HOME, 'venv');
+
+/** Composite marker written after a successful pip install */
+const DEPS_MARKER = join(VENV_DIR, '.deps-installed');
+
+/** PID file for the running server */
+const PID_FILE = join(CONFIG_HOME, 'server.pid');
+
+/** Path to the production requirements file inside the package */
+const REQUIREMENTS_FILE = join(PKG_DIR, 'requirements-prod.txt');
+
+/** Path to the .env example shipped with the package */
+const ENV_EXAMPLE = join(PKG_DIR, '.env.example');
+
+/** User .env config file */
+const ENV_FILE = join(CONFIG_HOME, '.env');
+
+const IS_WIN = platform() === 'win32';
+
+// ---------------------------------------------------------------------------
+// Package version (read lazily via createRequire)
+// ---------------------------------------------------------------------------
+
+const require = createRequire(import.meta.url);
+const { version: VERSION } = require(join(PKG_DIR, 'package.json'));
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Indented console output matching the spec format. */
+function log(msg = '') {
+  console.log(`  ${msg}`);
+}
+
+/** Print a fatal error and exit. */
+function die(msg) {
+  console.error(`\n  Error: ${msg}\n`);
+  process.exit(1);
+}
+
+/**
+ * Parse a Python version string like "Python 3.13.6" and return
+ * { major, minor, patch, raw } or null on failure.
+ */
+function parsePythonVersion(raw) {
+  const m = raw.match(/Python\s+(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: Number(m[3]),
+    raw: `${m[1]}.${m[2]}.${m[3]}`,
+  };
+}
+
+/**
+ * Try a single Python candidate. Returns { exe, version } or null.
+ * `candidate` is either a bare name or an array of args (e.g. ['py', '-3']).
+ */
+function tryPythonCandidate(candidate) {
+  const args = Array.isArray(candidate) ? candidate : [candidate];
+  const exe = args[0];
+  const extraArgs = args.slice(1);
+
+  try {
+    const out = execFileSync(exe, [...extraArgs, '--version'], {
+      encoding: 'utf8',
+      timeout: 10_000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    const ver = parsePythonVersion(out);
+    if (!ver) return null;
+
+    // Require 3.11+
+    if (ver.major < 3 || (ver.major === 3 && ver.minor < 11)) {
+      return { exe: args.join(' '), version: ver, tooOld: true };
+    }
+
+    return { exe: args.join(' '), version: ver, tooOld: false };
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Python detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Find a suitable Python >= 3.11 interpreter.
+ *
+ * Search order is platform-dependent:
+ *   Windows:     python -> py -3 -> python3
+ *   macOS/Linux: python3 -> python
+ *
+ * The AUTOFORGE_PYTHON env var overrides automatic detection.
+ *
+ * After finding a candidate we also verify that the venv module is
+ * available (Debian/Ubuntu strip it out of the base package).
+ */
+function findPython() {
+  // Allow explicit override via environment variable
+  const override = process.env.AUTOFORGE_PYTHON;
+  if (override) {
+    const result = tryPythonCandidate(override);
+    if (!result) {
+      die(`AUTOFORGE_PYTHON is set to "${override}" but it could not be executed.`);
+    }
+    if (result.tooOld) {
+      die(
+        `Python ${result.version.raw} found (via AUTOFORGE_PYTHON), but 3.11+ required.\n` +
+        '  Install Python 3.11+ from https://python.org'
+      );
+    }
+    return result;
+  }
+
+  // Platform-specific candidate order
+  const candidates = IS_WIN
+    ? ['python', ['py', '-3'], 'python3']
+    : ['python3', 'python'];
+
+  let bestTooOld = null;
+
+  for (const candidate of candidates) {
+    const result = tryPythonCandidate(candidate);
+    if (!result) continue;
+
+    if (result.tooOld) {
+      // Remember the first "too old" result for a better error message
+      if (!bestTooOld) bestTooOld = result;
+      continue;
+    }
+
+    // Verify venv module is available (Debian/Ubuntu may need python3-venv)
+    try {
+      const exeParts = result.exe.split(' ');
+      execFileSync(exeParts[0], [...exeParts.slice(1), '-c', 'import ensurepip'], {
+        encoding: 'utf8',
+        timeout: 10_000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+    } catch {
+      die(
+        `Python venv module not available.\n` +
+        `  Run: sudo apt install python3.${result.version.minor}-venv`
+      );
+    }
+
+    return result;
+  }
+
+  // Provide the most helpful error message we can
+  if (bestTooOld) {
+    die(
+      `Python ${bestTooOld.version.raw} found, but 3.11+ required.\n` +
+      '  Install Python 3.11+ from https://python.org'
+    );
+  }
+  die(
+    'Python 3.11+ required but not found.\n' +
+    '  Install from https://python.org'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Venv management
+// ---------------------------------------------------------------------------
+
+/** Return the path to the Python executable inside the venv. */
+function venvPython() {
+  return IS_WIN
+    ? join(VENV_DIR, 'Scripts', 'python.exe')
+    : join(VENV_DIR, 'bin', 'python');
+}
+
+/** SHA-256 hash of the requirements-prod.txt file contents. */
+function requirementsHash() {
+  const content = readFileSync(REQUIREMENTS_FILE, 'utf8');
+  return createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Read the composite deps marker. Returns the parsed JSON object
+ * or null if the file is missing / corrupt.
+ */
+function readMarker() {
+  try {
+    return JSON.parse(readFileSync(DEPS_MARKER, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Ensure the virtual environment exists and dependencies are installed.
+ * Returns true if all setup steps were already satisfied (fast path).
+ *
+ * @param {object} python - The result of findPython()
+ * @param {boolean} forceRecreate - If true, delete and recreate the venv
+ */
+function ensureVenv(python, forceRecreate) {
+  mkdirSync(CONFIG_HOME, { recursive: true });
+
+  const marker = readMarker();
+  const reqHash = requirementsHash();
+  const pyExe = venvPython();
+
+  // Determine if the venv itself needs to be (re)created
+  let needsCreate = forceRecreate || !existsSync(pyExe);
+
+  if (!needsCreate && marker) {
+    // Recreate if Python major.minor changed
+    const markerMinor = marker.python_version;
+    const currentMinor = `${python.version.major}.${python.version.minor}`;
+    if (markerMinor && markerMinor !== currentMinor) {
+      needsCreate = true;
+    }
+
+    // Recreate if the recorded python path no longer exists
+    if (marker.python_path && !existsSync(marker.python_path)) {
+      needsCreate = true;
+    }
+  }
+
+  let depsUpToDate = false;
+  if (!needsCreate && marker && marker.requirements_hash === reqHash) {
+    depsUpToDate = true;
+  }
+
+  // Fast path: nothing to do
+  if (!needsCreate && depsUpToDate) {
+    return true;
+  }
+
+  // --- Slow path: show setup progress ---
+
+  log('[2/3] Setting up environment...');
+
+  if (needsCreate) {
+    if (existsSync(VENV_DIR)) {
+      log('      Removing old virtual environment...');
+      rmSync(VENV_DIR, { recursive: true, force: true });
+    }
+
+    log(`      Creating virtual environment at ~/.autoforge/venv/`);
+    const exeParts = python.exe.split(' ');
+    try {
+      execFileSync(exeParts[0], [...exeParts.slice(1), '-m', 'venv', VENV_DIR], {
+        encoding: 'utf8',
+        timeout: 120_000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+    } catch (err) {
+      die(`Failed to create virtual environment: ${err.message}`);
+    }
+  }
+
+  // Install / update dependencies
+  log('      Installing dependencies...');
+  try {
+    execFileSync(pyExe, ['-m', 'pip', 'install', '-q', '--upgrade', 'pip'], {
+      encoding: 'utf8',
+      timeout: 300_000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    execFileSync(pyExe, ['-m', 'pip', 'install', '-q', '-r', REQUIREMENTS_FILE], {
+      encoding: 'utf8',
+      timeout: 600_000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch (err) {
+    die(`Failed to install dependencies: ${err.message}`);
+  }
+
+  // Write marker only after pip succeeds to prevent partial state
+  const markerData = {
+    requirements_hash: reqHash,
+    python_version: `${python.version.major}.${python.version.minor}`,
+    python_path: pyExe,
+    created_at: new Date().toISOString(),
+  };
+  writeFileSync(DEPS_MARKER, JSON.stringify(markerData, null, 2), 'utf8');
+
+  log('      Done');
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Config (.env) management
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a .env file into a plain object.
+ * Handles comments, blank lines, and quoted values.
+ */
+function parseEnvFile(filePath) {
+  const env = {};
+  if (!existsSync(filePath)) return env;
+
+  const lines = readFileSync(filePath, 'utf8').split('\n');
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx === -1) continue;
+
+    const key = trimmed.slice(0, eqIdx).trim();
+    let value = trimmed.slice(eqIdx + 1).trim();
+
+    // Strip matching quotes (single or double)
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    if (key) {
+      env[key] = value;
+    }
+  }
+  return env;
+}
+
+/**
+ * Ensure ~/.autoforge/.env exists. On first run, copy .env.example
+ * from the package directory and print a notice.
+ *
+ * Returns true if the file was newly created.
+ */
+function ensureEnvFile() {
+  if (existsSync(ENV_FILE)) return false;
+
+  mkdirSync(CONFIG_HOME, { recursive: true });
+
+  if (existsSync(ENV_EXAMPLE)) {
+    copyFileSync(ENV_EXAMPLE, ENV_FILE);
+  } else {
+    // Fallback: create a minimal placeholder
+    writeFileSync(ENV_FILE, '# AutoForge configuration\n# See documentation for available options.\n', 'utf8');
+  }
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Port detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Find an available TCP port starting from `start`.
+ * Tries by actually binding a socket (most reliable cross-platform approach).
+ */
+function findAvailablePort(start = 8888, maxAttempts = 20) {
+  for (let port = start; port < start + maxAttempts; port++) {
+    try {
+      const server = createServer();
+      // Use a synchronous-like approach: try to listen, then close immediately
+      const result = new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', () => {
+          server.close(() => resolve(port));
+        });
+      });
+      // We cannot await here (sync context), so use the blocking approach:
+      // Try to bind synchronously using a different technique.
+      server.close();
+    } catch {
+      // fall through
+    }
+  }
+  // Synchronous fallback: try to connect; if connection refused, port is free.
+  for (let port = start; port < start + maxAttempts; port++) {
+    try {
+      execFileSync(process.execPath, [
+        '-e',
+        `const s=require("net").createServer();` +
+        `s.listen(${port},"127.0.0.1",()=>{s.close();process.exit(0)});` +
+        `s.on("error",()=>process.exit(1))`,
+      ], { timeout: 3000, stdio: 'pipe' });
+      return port;
+    } catch {
+      continue;
+    }
+  }
+  die(`No available ports found in range ${start}-${start + maxAttempts - 1}`);
+}
+
+// ---------------------------------------------------------------------------
+// PID file management
+// ---------------------------------------------------------------------------
+
+/** Read PID from the PID file. Returns the PID number or null. */
+function readPid() {
+  try {
+    const content = readFileSync(PID_FILE, 'utf8').trim();
+    const pid = Number(content);
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Check whether a process with the given PID is still running. */
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0); // signal 0 = existence check
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Write the PID file. */
+function writePid(pid) {
+  mkdirSync(CONFIG_HOME, { recursive: true });
+  writeFileSync(PID_FILE, String(pid), 'utf8');
+}
+
+/** Remove the PID file. */
+function removePid() {
+  try {
+    unlinkSync(PID_FILE);
+  } catch {
+    // Ignore -- file may already be gone
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Browser opening
+// ---------------------------------------------------------------------------
+
+/** Open a URL in the user's default browser (best-effort). */
+function openBrowser(url) {
+  try {
+    if (IS_WIN) {
+      // "start" is a cmd built-in; the empty title string avoids
+      // issues when the URL contains special characters.
+      execSync(`start "" "${url}"`, { stdio: 'ignore' });
+    } else if (platform() === 'darwin') {
+      execFileSync('open', [url], { stdio: 'ignore' });
+    } else {
+      // Linux: only attempt if a display server is available and
+      // we are not in an SSH session.
+      const hasDisplay = process.env.DISPLAY || process.env.WAYLAND_DISPLAY;
+      const isSSH = !!process.env.SSH_TTY;
+      if (hasDisplay && !isSSH) {
+        execFileSync('xdg-open', [url], { stdio: 'ignore' });
+      }
+    }
+  } catch {
+    // Non-fatal: user can open the URL manually
+  }
+}
+
+/** Detect headless / CI environments where opening a browser is pointless. */
+function isHeadless() {
+  if (process.env.CI) return true;
+  if (process.env.CODESPACES) return true;
+  if (process.env.SSH_TTY) return true;
+  // Linux without a display server
+  if (!IS_WIN && platform() !== 'darwin' && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
+    return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Process cleanup
+// ---------------------------------------------------------------------------
+
+/** Kill a process tree. On Windows uses taskkill; elsewhere sends SIGTERM. */
+function killProcess(pid) {
+  try {
+    if (IS_WIN) {
+      execSync(`taskkill /pid ${pid} /t /f`, { stdio: 'ignore' });
+    } else {
+      process.kill(pid, 'SIGTERM');
+    }
+  } catch {
+    // Process may already be gone
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CLI commands
+// ---------------------------------------------------------------------------
+
+function printVersion() {
+  console.log(`autoforge v${VERSION}`);
+}
+
+function printHelp() {
+  console.log(`
+  AutoForge v${VERSION}
+  Autonomous coding agent with web UI
+
+  Usage:
+    autoforge                       Start the server (default)
+    autoforge config                Open ~/.autoforge/.env in $EDITOR
+    autoforge config --path         Print config file path
+    autoforge config --show         Show effective configuration
+
+  Options:
+    --port PORT                     Custom port (default: auto from 8888)
+    --host HOST                     Custom host (default: 127.0.0.1)
+    --no-browser                    Don't auto-open browser
+    --repair                        Delete and recreate virtual environment
+    --dev                           Development mode (requires cloned repo)
+    --version                       Print version
+    --help                          Show this help
+`);
+}
+
+function handleConfig(args) {
+  ensureEnvFile();
+
+  if (args.includes('--path')) {
+    console.log(ENV_FILE);
+    return;
+  }
+
+  if (args.includes('--show')) {
+    if (!existsSync(ENV_FILE)) {
+      log('No configuration file found.');
+      return;
+    }
+    const lines = readFileSync(ENV_FILE, 'utf8').split('\n');
+    const active = lines.filter(l => {
+      const t = l.trim();
+      return t && !t.startsWith('#');
+    });
+    if (active.length === 0) {
+      log('No active configuration. All lines are commented out.');
+      log(`Edit: ${ENV_FILE}`);
+    } else {
+      for (const line of active) {
+        console.log(line);
+      }
+    }
+    return;
+  }
+
+  // Open in editor
+  const editor = process.env.EDITOR || process.env.VISUAL || (IS_WIN ? 'notepad' : 'vi');
+  try {
+    execFileSync(editor, [ENV_FILE], { stdio: 'inherit' });
+  } catch {
+    log(`Could not open editor "${editor}".`);
+    log(`Edit the file manually: ${ENV_FILE}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main server start
+// ---------------------------------------------------------------------------
+
+function startServer(opts) {
+  const { port: requestedPort, host, noBrowser, repair } = opts;
+
+  // Step 1: Find Python
+  const fastPath = !repair && existsSync(venvPython()) && readMarker()?.requirements_hash === requirementsHash();
+
+  let python;
+  if (fastPath) {
+    // Skip the Python search header on fast path -- we already have a working venv
+    python = null;
+  } else {
+    log(`[1/3] Checking Python...`);
+    python = findPython();
+    log(`      Found Python ${python.version.raw} at ${python.exe}`);
+  }
+
+  // Step 2: Ensure venv and deps
+  if (!python) {
+    // Fast path still needs a python reference for potential repair
+    python = findPython();
+  }
+  const wasAlreadyReady = ensureVenv(python, repair);
+
+  // Step 3: Config file
+  const configCreated = ensureEnvFile();
+
+  // Load .env into process.env for the spawned server
+  const dotenvVars = parseEnvFile(ENV_FILE);
+
+  // Determine port
+  const port = requestedPort || findAvailablePort();
+
+  // Check for already-running instance
+  const existingPid = readPid();
+  if (existingPid && isProcessAlive(existingPid)) {
+    log(`AutoForge is already running at http://${host}:${port}`);
+    log('Opening browser...');
+    if (!noBrowser && !isHeadless()) {
+      openBrowser(`http://${host}:${port}`);
+    }
+    return;
+  }
+
+  // Clean up stale PID file
+  if (existingPid) {
+    removePid();
+  }
+
+  // Show server startup step only on slow path
+  if (!wasAlreadyReady) {
+    log('[3/3] Starting server...');
+  }
+
+  if (configCreated) {
+    log(`      Created config file: ~/.autoforge/.env`);
+    log('      Edit this file to configure API providers (Ollama, Vertex AI, z.ai)');
+    log('');
+  }
+
+  // Security warning for non-localhost host
+  if (host !== '127.0.0.1') {
+    console.log('');
+    console.log('  !! SECURITY WARNING !!');
+    console.log(`  Remote access enabled on host: ${host}`);
+    console.log('  The AutoForge UI will be accessible from other machines.');
+    console.log('  Ensure you understand the security implications.');
+    console.log('');
+  }
+
+  // Build environment for uvicorn
+  const serverEnv = { ...process.env, ...dotenvVars, PYTHONPATH: PKG_DIR };
+
+  // Enable remote access flag for the FastAPI server
+  if (host !== '127.0.0.1') {
+    serverEnv.AUTOFORGE_ALLOW_REMOTE = '1';
+  }
+
+  // Spawn uvicorn
+  const pyExe = venvPython();
+  const child = spawn(
+    pyExe,
+    [
+      '-m', 'uvicorn',
+      'server.main:app',
+      '--host', host,
+      '--port', String(port),
+    ],
+    {
+      cwd: PKG_DIR,
+      env: serverEnv,
+      stdio: 'inherit',
+    }
+  );
+
+  writePid(child.pid);
+
+  // Open browser after a short delay to let the server start
+  if (!noBrowser && !isHeadless()) {
+    setTimeout(() => openBrowser(`http://${host}:${port}`), 2000);
+  }
+
+  const url = `http://${host}:${port}`;
+  console.log('');
+  log(`Server running at ${url}`);
+  log('Press Ctrl+C to stop');
+
+  // Graceful shutdown handlers
+  const cleanup = () => {
+    killProcess(child.pid);
+    removePid();
+  };
+
+  process.on('SIGINT', () => {
+    console.log('');
+    cleanup();
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  // If the child exits on its own, clean up and propagate the exit code
+  child.on('exit', (code) => {
+    removePid();
+    process.exit(code ?? 1);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Main CLI entry point.
+ *
+ * @param {string[]} args - Command-line arguments (process.argv.slice(2))
+ */
+export function run(args) {
+  // --version / -v
+  if (args.includes('--version') || args.includes('-v')) {
+    printVersion();
+    return;
+  }
+
+  // --help / -h
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    return;
+  }
+
+  // --dev guard: this only works from a cloned repository
+  if (args.includes('--dev')) {
+    die(
+      'Dev mode requires a cloned repository.\n' +
+      '  Clone from https://github.com/paperlinguist/autocoder and run start_ui.sh'
+    );
+    return;
+  }
+
+  // "config" subcommand
+  if (args[0] === 'config') {
+    handleConfig(args.slice(1));
+    return;
+  }
+
+  // Parse flags for server start
+  const host = getFlagValue(args, '--host') || '127.0.0.1';
+  const portStr = getFlagValue(args, '--port');
+  const port = portStr ? Number(portStr) : null;
+  const noBrowser = args.includes('--no-browser');
+  const repair = args.includes('--repair');
+
+  if (port !== null && (!Number.isFinite(port) || port < 1 || port > 65535)) {
+    die('Invalid port number. Must be between 1 and 65535.');
+  }
+
+  // Print banner
+  console.log('');
+  log(`AutoForge v${VERSION}`);
+  console.log('');
+
+  startServer({ port, host, noBrowser, repair });
+}
+
+// ---------------------------------------------------------------------------
+// Argument parsing helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the value following a flag from the args array.
+ * E.g. getFlagValue(['--port', '9000', '--host', '0.0.0.0'], '--port') => '9000'
+ */
+function getFlagValue(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx + 1 >= args.length) return null;
+  return args[idx + 1];
+}

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__":

package.json

@@ -0,0 +1,54 @@
+{
+  "name": "autoforge-ai",
+  "version": "0.1.3",
+  "description": "Autonomous coding agent with web UI - build complete apps with AI",
+  "license": "AGPL-3.0",
+  "bin": {
+    "autoforge": "./bin/autoforge.js"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "api/",
+    "server/",
+    "mcp_server/",
+    "ui/dist/",
+    "ui/package.json",
+    ".claude/commands/",
+    ".claude/templates/",
+    "examples/",
+    "start.py",
+    "agent.py",
+    "auth.py",
+    "autoforge_paths.py",
+    "autonomous_agent_demo.py",
+    "client.py",
+    "env_constants.py",
+    "parallel_orchestrator.py",
+    "progress.py",
+    "prompts.py",
+    "registry.py",
+    "rate_limit_utils.py",
+    "security.py",
+    "temp_cleanup.py",
+    "requirements-prod.txt",
+    "pyproject.toml",
+    ".env.example",
+    "!**/__pycache__/",
+    "!**/*.pyc"
+  ],
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "claude",
+    "autonomous",
+    "code-generation"
+  ],
+  "scripts": {
+    "prepublishOnly": "npm --prefix ui install && npm --prefix ui run build"
+  }
+}

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 autoforge_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 autoforge_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 autoforge_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 autoforge_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 autoforge_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 .autoforge directory with .gitignore for runtime files
-    autocoder_dir = project_dir / ".autocoder"
+    from autoforge_paths import ensure_autoforge_dir
-    autocoder_dir.mkdir(parents=True, exist_ok=True)
+    autoforge_dir = ensure_autoforge_dir(project_dir)
 
     # Define template mappings: (source_template, destination_name)
     templates = [
@@ -215,14 +340,14 @@ def scaffold_project_prompts(project_dir: Path) -> Path:
             except (OSError, PermissionError) as e:
                 print(f"  Warning: Could not copy {dest_name}: {e}")
 
-    # Copy allowed_commands.yaml template to .autocoder/
+    # Copy allowed_commands.yaml template to .autoforge/
     examples_dir = Path(__file__).parent / "examples"
     allowed_commands_template = examples_dir / "project_allowed_commands.yaml"
-    allowed_commands_dest = autocoder_dir / "allowed_commands.yaml"
+    allowed_commands_dest = autoforge_dir / "allowed_commands.yaml"
     if allowed_commands_template.exists() and not allowed_commands_dest.exists():
         try:
             shutil.copy(allowed_commands_template, allowed_commands_dest)
-            copied_files.append(".autocoder/allowed_commands.yaml")
+            copied_files.append(".autoforge/allowed_commands.yaml")
         except (OSError, PermissionError) as e:
             print(f"  Warning: Could not copy allowed_commands.yaml: {e}")
 

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

@@ -3,7 +3,7 @@ Project Registry Module
 =======================
 
 Cross-platform project registry for storing project name to path mappings.
-Uses SQLite database stored at ~/.autocoder/registry.db.
+Uses SQLite database stored at ~/.autoforge/registry.db.
 """
 
 import logging
@@ -17,13 +17,28 @@ from pathlib import Path
 from typing import Any
 
 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__)
 
 
+def _migrate_registry_dir() -> None:
+    """Migrate ~/.autocoder/ to ~/.autoforge/ if needed.
+
+    Provides backward compatibility by automatically renaming the old
+    config directory to the new location on first access.
+    """
+    old_dir = Path.home() / ".autocoder"
+    new_dir = Path.home() / ".autoforge"
+    if old_dir.exists() and not new_dir.exists():
+        try:
+            old_dir.rename(new_dir)
+            logger.info("Migrated registry directory: ~/.autocoder/ -> ~/.autoforge/")
+        except Exception:
+            logger.warning("Failed to migrate ~/.autocoder/ to ~/.autoforge/", exc_info=True)
+
+
 # =============================================================================
 # Model Configuration (Single Source of Truth)
 # =============================================================================
@@ -39,7 +54,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 +100,9 @@ class RegistryPermissionDenied(RegistryError):
 # SQLAlchemy Model
 # =============================================================================
 
-Base = declarative_base()
+class Base(DeclarativeBase):
+    """SQLAlchemy 2.0 style declarative base."""
+    pass
 
 
 class Project(Base):
@@ -109,12 +136,15 @@ _engine_lock = threading.Lock()
 
 def get_config_dir() -> Path:
     """
-    Get the config directory: ~/.autocoder/
+    Get the config directory: ~/.autoforge/
+
+    Automatically migrates from ~/.autocoder/ if needed.
 
     Returns:
-        Path to ~/.autocoder/ (created if it doesn't exist)
+        Path to ~/.autoforge/ (created if it doesn't exist)
     """
-    config_dir = Path.home() / ".autocoder"
+    _migrate_registry_dir()
+    config_dir = Path.home() / ".autoforge"
     config_dir.mkdir(parents=True, exist_ok=True)
     return config_dir
 

requirements-prod.txt

@@ -0,0 +1,14 @@
+# Production runtime dependencies only
+# For development, use requirements.txt (includes ruff, mypy, pytest)
+claude-agent-sdk>=0.1.0,<0.2.0
+python-dotenv>=1.0.0
+sqlalchemy>=2.0.0
+fastapi>=0.115.0
+uvicorn[standard]>=0.32.0
+websockets>=13.0
+python-multipart>=0.0.17
+psutil>=6.0.0
+aiofiles>=24.0.0
+apscheduler>=3.10.0,<4.0.0
+pywinpty>=2.0.0; sys_platform == "win32"
+pyyaml>=6.0.0

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

@@ -97,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 = {
@@ -413,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.
@@ -472,19 +479,97 @@ 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.
 
     Returns:
-        Path to ~/.autocoder/config.yaml
+        Path to ~/.autoforge/config.yaml (falls back to ~/.autocoder/config.yaml)
     """
-    return Path.home() / ".autocoder" / "config.yaml"
+    new_path = Path.home() / ".autoforge" / "config.yaml"
+    if new_path.exists():
+        return new_path
+    # Backward compatibility: check old location
+    old_path = Path.home() / ".autocoder" / "config.yaml"
+    if old_path.exists():
+        return old_path
+    return new_path
 
 
 def load_org_config() -> Optional[dict]:
     """
-    Load organization-level config from ~/.autocoder/config.yaml.
+    Load organization-level config from ~/.autoforge/config.yaml.
+
+    Falls back to ~/.autocoder/config.yaml for backward compatibility.
 
     Returns:
         Dict with parsed org config, or None if file doesn't exist or is invalid
@@ -513,21 +598,8 @@ def load_org_config() -> Optional[dict]:
 
         # 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):
-                logger.warning(f"Org config at {config_path}: 'allowed_commands' must be a list")
                 return None
-            for i, cmd in enumerate(allowed):
-                if not isinstance(cmd, dict):
-                    logger.warning(f"Org config at {config_path}: allowed_commands[{i}] must be a dict")
-                    return None
-                if "name" not in cmd:
-                    logger.warning(f"Org config at {config_path}: allowed_commands[{i}] missing 'name'")
-                    return None
-                # Validate that name is a non-empty string
-                if not isinstance(cmd["name"], str) or cmd["name"].strip() == "":
-                    logger.warning(f"Org config at {config_path}: allowed_commands[{i}] has invalid 'name'")
-                    return None
 
         # Validate blocked_commands if present
         if "blocked_commands" in config:
@@ -541,23 +613,10 @@ def load_org_config() -> Optional[dict]:
                     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
-                logger.warning(f"Org config at {config_path}: 'pkill_processes' must be a list")
+        if normalized:
-                return None
-            # Normalize and validate each process name against safe pattern
-            normalized = []
-            for i, proc in enumerate(processes):
-                if not isinstance(proc, str):
-                    logger.warning(f"Org config at {config_path}: pkill_processes[{i}] must be a string")
-                    return None
-                proc = proc.strip()
-                # Block empty strings and regex metacharacters
-                if not proc or not VALID_PROCESS_NAME_PATTERN.fullmatch(proc):
-                    logger.warning(f"Org config at {config_path}: pkill_processes[{i}] has invalid value '{proc}'")
-                    return None
-                normalized.append(proc)
             config["pkill_processes"] = normalized
 
         return config
@@ -580,7 +639,10 @@ 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.resolve() / ".autocoder" / "allowed_commands.yaml"
+    # Check new location first, fall back to old for backward compatibility
+    config_path = project_dir.resolve() / ".autoforge" / "allowed_commands.yaml"
+    if not config_path.exists():
+        config_path = project_dir.resolve() / ".autocoder" / "allowed_commands.yaml"
 
     if not config_path.exists():
         return None
@@ -603,46 +665,21 @@ def load_project_commands(project_dir: Path) -> Optional[dict]:
             return None
 
         commands = config.get("commands", [])
-        if not isinstance(commands, list):
-            logger.warning(f"Project config at {config_path}: 'commands' must be a 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 i, cmd in enumerate(commands):
+        if not _validate_command_list(commands, config_path, "commands"):
-            if not isinstance(cmd, dict):
+            return None
-                logger.warning(f"Project config at {config_path}: commands[{i}] must be a dict")
-                return None
-            if "name" not in cmd:
-                logger.warning(f"Project config at {config_path}: commands[{i}] missing 'name'")
-                return None
-            # Validate name is a non-empty string
-            if not isinstance(cmd["name"], str) or cmd["name"].strip() == "":
-                logger.warning(f"Project config at {config_path}: commands[{i}] has invalid 'name'")
-                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
-                logger.warning(f"Project config at {config_path}: 'pkill_processes' must be a list")
+        if normalized:
-                return None
-            # Normalize and validate each process name against safe pattern
-            normalized = []
-            for i, proc in enumerate(processes):
-                if not isinstance(proc, str):
-                    logger.warning(f"Project config at {config_path}: pkill_processes[{i}] must be a string")
-                    return None
-                proc = proc.strip()
-                # Block empty strings and regex metacharacters
-                if not proc or not VALID_PROCESS_NAME_PATTERN.fullmatch(proc):
-                    logger.warning(f"Project config at {config_path}: pkill_processes[{i}] has invalid value '{proc}'")
-                    return None
-                normalized.append(proc)
             config["pkill_processes"] = normalized
 
         return config
@@ -659,8 +696,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)
@@ -690,15 +731,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, ""
 
 
@@ -889,7 +921,7 @@ async def bash_security_hook(input_data, tool_use_id=None, context=None):
             # Provide helpful error message with config hint
             error_msg = f"Command '{cmd}' is not allowed.\n"
             error_msg += "To allow this command:\n"
-            error_msg += "  1. Add to .autocoder/allowed_commands.yaml for this project, OR\n"
+            error_msg += "  1. Add to .autoforge/allowed_commands.yaml for this project, OR\n"
             error_msg += "  2. Request mid-session approval (the agent can ask)\n"
             error_msg += "Note: Some commands are blocked at org-level and cannot be overridden."
             return {
@@ -899,8 +931,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,9 +89,18 @@ 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")
+ALLOW_REMOTE = os.environ.get("AUTOFORGE_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:
@@ -123,7 +133,7 @@ else:
 if not ALLOW_REMOTE:
     @app.middleware("http")
     async def require_localhost(request: Request, call_next):
-        """Only allow requests from localhost (disabled when AUTOCODER_ALLOW_REMOTE=1)."""
+        """Only allow requests from localhost (disabled when AUTOFORGE_ALLOW_REMOTE=1)."""
         client_host = request.client.host if request.client else None
 
         # Allow localhost connections
@@ -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,8 @@ 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 shlex
 import sys
 from pathlib import Path
 
@@ -26,38 +27,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.
@@ -88,6 +73,116 @@ def get_project_dir(project_name: str) -> Path:
 
     return project_dir
 
+ALLOWED_RUNNERS = {
+    "npm", "pnpm", "yarn", "npx",
+    "uvicorn", "python", "python3",
+    "flask", "poetry",
+    "cargo", "go",
+}
+
+ALLOWED_NPM_SCRIPTS = {"dev", "start", "serve", "develop", "server", "preview"}
+
+# Allowed Python -m modules for dev servers
+ALLOWED_PYTHON_MODULES = {"uvicorn", "flask", "gunicorn", "http.server"}
+
+BLOCKED_SHELLS = {"sh", "bash", "zsh", "cmd", "powershell", "pwsh", "cmd.exe"}
+
+
+def validate_custom_command_strict(cmd: str) -> None:
+    """
+    Strict allowlist validation for dev server commands.
+    Prevents arbitrary command execution (no sh -c, no cmd /c, no python -c, etc.)
+    """
+    if not isinstance(cmd, str) or not cmd.strip():
+        raise ValueError("custom_command cannot be empty")
+
+    argv = shlex.split(cmd, posix=(sys.platform != "win32"))
+    if not argv:
+        raise ValueError("custom_command could not be parsed")
+
+    base = Path(argv[0]).name.lower()
+
+    # Block direct shells / interpreters commonly used for command injection
+    if base in BLOCKED_SHELLS:
+        raise ValueError(f"custom_command runner not allowed: {base}")
+
+    if base not in ALLOWED_RUNNERS:
+        raise ValueError(
+            f"custom_command runner not allowed: {base}. "
+            f"Allowed: {', '.join(sorted(ALLOWED_RUNNERS))}"
+        )
+
+    # Block one-liner execution for python
+    lowered = [a.lower() for a in argv]
+    if base in {"python", "python3"}:
+        if "-c" in lowered:
+            raise ValueError("python -c is not allowed")
+        if len(argv) >= 3 and argv[1] == "-m":
+            # Allow: python -m <allowed_module> ...
+            if argv[2] not in ALLOWED_PYTHON_MODULES:
+                raise ValueError(
+                    f"python -m {argv[2]} is not allowed. "
+                    f"Allowed modules: {', '.join(sorted(ALLOWED_PYTHON_MODULES))}"
+                )
+        elif len(argv) >= 2 and argv[1].endswith(".py"):
+            # Allow: python manage.py runserver, python app.py, etc.
+            pass
+        else:
+            raise ValueError(
+                "Python commands must use 'python -m <module> ...' or 'python <script>.py ...'"
+            )
+
+    if base == "flask":
+        # Allow: flask run [--host ...] [--port ...]
+        if len(argv) < 2 or argv[1] != "run":
+            raise ValueError("flask custom_command must be 'flask run [options]'")
+
+    if base == "poetry":
+        # Allow: poetry run <subcmd> ...
+        if len(argv) < 3 or argv[1] != "run":
+            raise ValueError("poetry custom_command must be 'poetry run <command> ...'")
+
+    if base == "uvicorn":
+        if len(argv) < 2 or ":" not in argv[1]:
+            raise ValueError("uvicorn must specify an app like module:app")
+
+        allowed_flags = {"--host", "--port", "--reload", "--log-level", "--workers"}
+        for a in argv[2:]:
+            if a.startswith("-"):
+                # Handle --flag=value syntax
+                flag_key = a.split("=", 1)[0]
+                if flag_key not in allowed_flags:
+                    raise ValueError(f"uvicorn flag not allowed: {flag_key}")
+
+    if base in {"npm", "pnpm", "yarn"}:
+        # Allow only known safe scripts (no arbitrary exec)
+        if base == "npm":
+            if len(argv) < 3 or argv[1] != "run" or argv[2] not in ALLOWED_NPM_SCRIPTS:
+                raise ValueError(
+                    f"npm custom_command must be 'npm run <script>' where script is one of: "
+                    f"{', '.join(sorted(ALLOWED_NPM_SCRIPTS))}"
+                )
+        elif base == "pnpm":
+            ok = (
+                (len(argv) >= 2 and argv[1] in ALLOWED_NPM_SCRIPTS)
+                or (len(argv) >= 3 and argv[1] == "run" and argv[2] in ALLOWED_NPM_SCRIPTS)
+            )
+            if not ok:
+                raise ValueError(
+                    f"pnpm custom_command must use a known script: "
+                    f"{', '.join(sorted(ALLOWED_NPM_SCRIPTS))}"
+                )
+        elif base == "yarn":
+            ok = (
+                (len(argv) >= 2 and argv[1] in ALLOWED_NPM_SCRIPTS)
+                or (len(argv) >= 3 and argv[1] == "run" and argv[2] in ALLOWED_NPM_SCRIPTS)
+            )
+            if not ok:
+                raise ValueError(
+                    f"yarn custom_command must use a known script: "
+                    f"{', '.join(sorted(ALLOWED_NPM_SCRIPTS))}"
+                )
+
 
 def get_project_devserver_manager(project_name: str):
     """
@@ -106,6 +201,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
 # ============================================================================
@@ -157,9 +291,12 @@ async def start_devserver(
     # Determine which command to use
     command: str | None
     if request.command:
-        command = request.command
+        raise HTTPException(
-    else:
+            status_code=400,
-        command = get_dev_command(project_dir)
+            detail="Direct command execution is disabled. Use /config to set a safe custom_command."
+        )
+
+    command = get_dev_command(project_dir)
 
     if not command:
         raise HTTPException(
@@ -167,7 +304,17 @@ 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)
+
+    # Defense-in-depth: also run strict structural validation at execution time
+    # (catches config file tampering that bypasses the /config endpoint)
+    try:
+        validate_custom_command_strict(command)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    # Now command is definitely str and validated
     success, message = await manager.start(command)
 
     return DevServerActionResponse(
@@ -258,6 +405,15 @@ async def update_devserver_config(
         except ValueError as e:
             raise HTTPException(status_code=400, detail=str(e))
     else:
+        # Strict structural validation first (most specific errors)
+        try:
+            validate_custom_command_strict(update.custom_command)
+        except ValueError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+
+        # Then validate against security allowlist
+        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 autoforge_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 autoforge_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 autoforge_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 autoforge_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
 
@@ -24,11 +25,12 @@ from ..schemas import (
 )
 
 # 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():
@@ -99,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(
@@ -113,6 +116,7 @@ def get_project_stats(project_dir: Path) -> ProjectStats:
 async def list_projects():
     """List all registered projects."""
     _init_imports()
+    assert _check_spec_exists is not None  # guaranteed by _init_imports()
     (_, _, _, list_registered_projects, validate_project_path,
      get_project_concurrency, _) = _get_registry_functions()
 
@@ -145,6 +149,7 @@ async def list_projects():
 async def create_project(project: ProjectCreate):
     """Create a new project at the specified path."""
     _init_imports()
+    assert _scaffold_project_prompts is not None  # guaranteed by _init_imports()
     (register_project, _, get_project_path, list_registered_projects,
      _, _, _) = _get_registry_functions()
 
@@ -225,6 +230,8 @@ async def create_project(project: ProjectCreate):
 async def get_project(name: str):
     """Get detailed information about a project."""
     _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, _) = _get_registry_functions()
 
     name = validate_project_name(name)
@@ -269,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 autoforge_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."
@@ -296,6 +303,7 @@ 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()
+    assert _get_project_prompts_dir is not None  # guaranteed by _init_imports()
     (_, _, get_project_path, _, _, _, _) = _get_registry_functions()
 
     name = validate_project_name(name)
@@ -307,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
@@ -329,6 +337,7 @@ async def get_project_prompts(name: str):
 async def update_project_prompts(name: str, prompts: ProjectPromptsUpdate):
     """Update project prompt files."""
     _init_imports()
+    assert _get_project_prompts_dir is not None  # guaranteed by _init_imports()
     (_, _, get_project_path, _, _, _, _) = _get_registry_functions()
 
     name = validate_project_name(name)
@@ -398,8 +407,8 @@ async def reset_project(name: str, full_reset: bool = False):
         raise HTTPException(status_code=404, detail="Project directory not found")
 
     # Check if agent is running
-    lock_file = project_dir / ".agent.lock"
+    from autoforge_paths import has_agent_running
-    if lock_file.exists():
+    if has_agent_running(project_dir):
         raise HTTPException(
             status_code=409,
             detail="Cannot reset project while agent is running. Stop the agent first."
@@ -415,36 +424,58 @@ async def reset_project(name: str, full_reset: bool = False):
 
     deleted_files: list[str] = []
 
-    # Files to delete in quick reset
+    from autoforge_paths import (
-    quick_reset_files = [
+        get_assistant_db_path,
-        "features.db",
+        get_claude_assistant_settings_path,
-        "features.db-wal",  # WAL mode journal file
+        get_claude_settings_path,
-        "features.db-shm",  # WAL mode shared memory file
+        get_features_db_path,
-        "assistant.db",
+    )
-        "assistant.db-wal",
+
-        "assistant.db-shm",
+    # Build list of files to delete using path helpers (finds files at current location)
-        ".claude_settings.json",
+    # Plus explicit old-location fallbacks for backward compatibility
-        ".claude_assistant_settings.json",
+    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 filename in quick_reset_files:
+    for file_path in reset_files:
-        file_path = project_dir / filename
         if file_path.exists():
             try:
+                relative = file_path.relative_to(project_dir)
                 file_path.unlink()
-                deleted_files.append(filename)
+                deleted_files.append(str(relative))
             except Exception as e:
-                raise HTTPException(status_code=500, detail=f"Failed to delete {filename}: {e}")
+                raise HTTPException(status_code=500, detail=f"Failed to delete {file_path.name}: {e}")
 
     # Full reset: also delete prompts directory
     if full_reset:
-        prompts_dir = project_dir / "prompts"
+        from autoforge_paths import get_prompts_dir
-        if prompts_dir.exists():
+        # Delete prompts from both possible locations
-            try:
+        for prompts_dir in [get_prompts_dir(project_dir), project_dir / "prompts"]:
-                shutil.rmtree(prompts_dir)
+            if prompts_dir.exists():
-                deleted_files.append("prompts/")
+                try:
-            except Exception as e:
+                    relative = prompts_dir.relative_to(project_dir)
-                raise HTTPException(status_code=500, detail=f"Failed to delete prompts/: {e}")
+                    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,
@@ -458,6 +489,8 @@ async def reset_project(name: str, full_reset: bool = False):
 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()
 

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 autoforge_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

@@ -398,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):
@@ -411,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
@@ -426,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 autoforge_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 autoforge_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 autoforge_paths import get_assistant_db_path
+    return get_assistant_db_path(project_dir)
 
 
 def get_engine(project_dir: Path):
@@ -64,17 +73,33 @@ 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]
 

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 autoforge 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

@@ -14,10 +14,11 @@ This is a simplified version of AgentProcessManager, tailored for dev servers:
 import asyncio
 import logging
 import re
+import shlex
 import subprocess
 import sys
 import threading
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Awaitable, Callable, Literal, Set
 
@@ -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 autoforge_paths import get_devserver_lock_path
+        self.lock_file = get_devserver_lock_path(self.project_dir)
 
     @property
     def status(self) -> Literal["stopped", "running", "crashed"]:
@@ -289,39 +291,54 @@ class DevServerProcessManager:
         Start the dev server as a subprocess.
 
         Args:
-            command: The shell command to run (e.g., "npm run dev")
+            command: The command to run (e.g., "npm run dev")
 
         Returns:
             Tuple of (success, message)
         """
-        if self.status == "running":
+        # Already running?
+        if self.process and self.status == "running":
             return False, "Dev server is already running"
 
+        # Lock check (prevents double-start)
         if not self._check_lock():
-            return False, "Another dev server instance is already running for this project"
+            return False, "Dev server already running (lock file present)"
 
-        # Validate that project directory exists
+        command = (command or "").strip()
-        if not self.project_dir.exists():
+        if not command:
-            return False, f"Project directory does not exist: {self.project_dir}"
+            return False, "Empty dev server command"
 
-        self._command = command
+        # SECURITY: block shell operators/metacharacters (defense-in-depth)
-        self._detected_url = None  # Reset URL detection
+        # NOTE: On Windows, .cmd/.bat files are executed via cmd.exe even with
+        # shell=False (CPython limitation), so metacharacter blocking is critical.
+        # Single & is a cmd.exe command separator, ^ is cmd escape, % enables
+        # environment variable expansion, > < enable redirection.
+        dangerous_ops = ["&&", "||", ";", "|", "`", "$(", "&", ">", "<", "^", "%"]
+        if any(op in command for op in dangerous_ops):
+            return False, "Shell operators are not allowed in dev server command"
+        # Block newline injection (cmd.exe interprets newlines as command separators)
+        if "\n" in command or "\r" in command:
+            return False, "Newlines are not allowed in dev server command"
+
+        # Parse into argv and execute without shell
+        argv = shlex.split(command, posix=(sys.platform != "win32"))
+        if not argv:
+            return False, "Empty dev server command"
+
+        base = Path(argv[0]).name.lower()
+
+        # Defense-in-depth: reject direct shells/interpreters commonly used for injection
+        if base in {"sh", "bash", "zsh", "cmd", "powershell", "pwsh"}:
+            return False, f"Shell runner '{base}' is not allowed for dev server commands"
+
+        # Windows: use .cmd shims for Node package managers
+        if sys.platform == "win32" and base in {"npm", "pnpm", "yarn", "npx"} and not argv[0].lower().endswith(".cmd"):
+            argv[0] = argv[0] + ".cmd"
 
         try:
-            # Determine shell based on platform
-            if sys.platform == "win32":
-                # On Windows, use cmd.exe
-                shell_cmd = ["cmd", "/c", command]
-            else:
-                # On Unix-like systems, use sh
-                shell_cmd = ["sh", "-c", command]
-
-            # Start subprocess with piped stdout/stderr
-            # stdin=DEVNULL prevents interactive dev servers from blocking on stdin
-            # On Windows, use CREATE_NO_WINDOW to prevent console window from flashing
             if sys.platform == "win32":
                 self.process = subprocess.Popen(
-                    shell_cmd,
+                    argv,
                     stdin=subprocess.DEVNULL,
                     stdout=subprocess.PIPE,
                     stderr=subprocess.STDOUT,
@@ -330,23 +347,33 @@ class DevServerProcessManager:
                 )
             else:
                 self.process = subprocess.Popen(
-                    shell_cmd,
+                    argv,
                     stdin=subprocess.DEVNULL,
                     stdout=subprocess.PIPE,
                     stderr=subprocess.STDOUT,
                     cwd=str(self.project_dir),
                 )
 
-            self._create_lock()
+            self._command = command
-            self.started_at = datetime.now()
+            self.started_at = datetime.now(timezone.utc)
-            self.status = "running"
+            self._detected_url = None
 
-            # Start output streaming task
+            # Create lock once we have a PID
+            self._create_lock()
+
+            # Start output streaming
+            self.status = "running"
             self._output_task = asyncio.create_task(self._stream_output())
 
-            return True, f"Dev server started with PID {self.process.pid}"
+            return True, "Dev server started"
+
+        except FileNotFoundError:
+            self.status = "stopped"
+            self.process = None
+            return False, f"Command not found: {argv[0]}"
         except Exception as e:
-            logger.exception("Failed to start dev server")
+            self.status = "stopped"
+            self.process = None
             return False, f"Failed to start dev server: {e}"
 
     async def stop(self) -> tuple[bool, str]:
@@ -487,8 +514,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 autoforge_paths import get_autoforge_dir
+            lock_locations = [
+                project_path / ".devserver.lock",
+                get_autoforge_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

@@ -16,28 +16,19 @@ 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
-API_ENV_VARS = [
-    "ANTHROPIC_BASE_URL",
-    "ANTHROPIC_AUTH_TOKEN",
-    "API_TIMEOUT_MS",
-    "ANTHROPIC_DEFAULT_SONNET_MODEL",
-    "ANTHROPIC_DEFAULT_OPUS_MODEL",
-    "ANTHROPIC_DEFAULT_HAIKU_MODEL",
-]
-
 # Feature MCP tools needed for expand session
 EXPAND_FEATURE_TOOLS = [
     "mcp__features__feature_create",
@@ -46,22 +37,6 @@ EXPAND_FEATURE_TOOLS = [
 ]
 
 
-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.
@@ -128,7 +103,8 @@ class ExpandChatSession:
             return
 
         # Verify project has existing spec
-        spec_path = self.project_dir / "prompts" / "app_spec.txt"
+        from autoforge_paths import get_prompts_dir
+        spec_path = get_prompts_dir(self.project_dir) / "app_spec.txt"
         if not spec_path.exists():
             yield {
                 "type": "error",
@@ -162,10 +138,13 @@ class ExpandChatSession:
                 "allow": [
                     "Read(./**)",
                     "Glob(./**)",
+                    *EXPAND_FEATURE_TOOLS,
                 ],
             },
         }
-        settings_file = self.project_dir / f".claude_settings.expand.{uuid.uuid4().hex}.json"
+        from autoforge_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)
@@ -175,7 +154,12 @@ 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
@@ -203,9 +187,12 @@ class ExpandChatSession:
                     allowed_tools=[
                         "Read",
                         "Glob",
+                        "Grep",
+                        "WebFetch",
+                        "WebSearch",
                         *EXPAND_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()),
@@ -299,7 +286,7 @@ class ExpandChatSession:
 
         # 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:
@@ -311,7 +298,7 @@ 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)

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 autoforge_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,18 +350,21 @@ 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
             # stdin=DEVNULL prevents blocking if Claude CLI or child process tries to read stdin
             # CREATE_NO_WINDOW on Windows prevents console window pop-ups
             # PYTHONUNBUFFERED ensures output isn't delayed
-            popen_kwargs = {
+            popen_kwargs: dict[str, Any] = {
                 "stdin": subprocess.DEVNULL,
                 "stdout": subprocess.PIPE,
                 "stderr": subprocess.STDOUT,
                 "cwd": str(self.project_dir),
-                "env": {**os.environ, "PYTHONUNBUFFERED": "1"},
+                "env": {**os.environ, "PYTHONUNBUFFERED": "1", "PLAYWRIGHT_HEADLESS": "true" if playwright_headless else "false"},
             }
             if sys.platform == "win32":
                 popen_kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW
@@ -579,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 autoforge_paths import get_autoforge_dir
+            lock_locations = [
+                project_path / ".agent.lock",
+                get_autoforge_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/project_config.py

@@ -6,7 +6,7 @@ Handles project type detection and dev command configuration.
 Detects project types by scanning for configuration files and provides
 default or custom dev commands for each project.
 
-Configuration is stored in {project_dir}/.autocoder/config.json.
+Configuration is stored in {project_dir}/.autoforge/config.json.
 """
 
 import json
@@ -88,13 +88,22 @@ def _get_config_path(project_dir: Path) -> Path:
     """
     Get the path to the project config file.
 
+    Checks the new .autoforge/ location first, falls back to .autocoder/
+    for backward compatibility.
+
     Args:
         project_dir: Path to the project directory.
 
     Returns:
-        Path to the .autocoder/config.json file.
+        Path to the config.json file in the appropriate directory.
     """
-    return project_dir / ".autocoder" / "config.json"
+    new_path = project_dir / ".autoforge" / "config.json"
+    if new_path.exists():
+        return new_path
+    old_path = project_dir / ".autocoder" / "config.json"
+    if old_path.exists():
+        return old_path
+    return new_path
 
 
 def _load_config(project_dir: Path) -> dict:
@@ -137,7 +146,7 @@ def _save_config(project_dir: Path, config: dict) -> None:
     """
     Save the project configuration to disk.
 
-    Creates the .autocoder directory if it doesn't exist.
+    Creates the .autoforge directory if it doesn't exist.
 
     Args:
         project_dir: Path to the project directory.
@@ -148,7 +157,7 @@ def _save_config(project_dir: Path, config: dict) -> None:
     """
     config_path = _get_config_path(project_dir)
 
-    # Ensure the .autocoder directory exists
+    # Ensure the .autoforge directory exists
     config_path.parent.mkdir(parents=True, exist_ok=True)
 
     try:
@@ -408,11 +417,11 @@ def clear_dev_command(project_dir: Path) -> None:
             config_path.unlink(missing_ok=True)
             logger.info("Removed empty config file for %s", project_dir.name)
 
-            # Also remove .autocoder directory if empty
+            # Also remove .autoforge directory if empty
-            autocoder_dir = config_path.parent
+            autoforge_dir = config_path.parent
-            if autocoder_dir.exists() and not any(autocoder_dir.iterdir()):
+            if autoforge_dir.exists() and not any(autoforge_dir.iterdir()):
-                autocoder_dir.rmdir()
+                autoforge_dir.rmdir()
-                logger.debug("Removed empty .autocoder directory for %s", project_dir.name)
+                logger.debug("Removed empty .autoforge directory for %s", project_dir.name)
         except OSError as e:
             logger.warning("Failed to clean up config for %s: %s", project_dir.name, e)
     else:

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 autoforge_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 autoforge_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 autoforge_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 autoforge_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.bat

@@ -3,7 +3,7 @@ cd /d "%~dp0"
 
 echo.
 echo ========================================
-echo   Autonomous Coding Agent
+echo   AutoForge - Autonomous Coding Agent
 echo ========================================
 echo.
 

start.py

@@ -82,7 +82,7 @@ def get_existing_projects() -> list[tuple[str, Path]]:
 def display_menu(projects: list[tuple[str, Path]]) -> None:
     """Display the main menu."""
     print("\n" + "=" * 50)
-    print("  Autonomous Coding Agent Launcher")
+    print("  AutoForge - Autonomous Coding Agent")
     print("=" * 50)
     print("\n[1] Create new project")
 

start.sh

@@ -3,7 +3,7 @@ cd "$(dirname "$0")"
 
 echo ""
 echo "========================================"
-echo "  Autonomous Coding Agent"
+echo "  AutoForge - Autonomous Coding Agent"
 echo "========================================"
 echo ""
 

start_ui.bat

@@ -1,11 +1,11 @@
 @echo off
 cd /d "%~dp0"
-REM AutoCoder UI Launcher for Windows
+REM AutoForge UI Launcher for Windows
 REM This script launches the web UI for the autonomous coding agent.
 
 echo.
 echo ====================================
-echo   AutoCoder UI
+echo   AutoForge UI
 echo ====================================
 echo.
 

start_ui.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-AutoCoder UI Launcher
+AutoForge UI Launcher
 =====================
 
 Automated launcher that handles all setup:
@@ -202,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():
@@ -265,7 +265,7 @@ def start_dev_server(port: int, host: str = "127.0.0.1") -> tuple:
     # Set environment for remote access if needed
     env = os.environ.copy()
     if host != "127.0.0.1":
-        env["AUTOCODER_ALLOW_REMOTE"] = "1"
+        env["AUTOFORGE_ALLOW_REMOTE"] = "1"
 
     # Start FastAPI
     backend = subprocess.Popen([
@@ -297,7 +297,7 @@ def start_production_server(port: int, host: str = "127.0.0.1"):
 
     # Enable remote access in server if not localhost
     if host != "127.0.0.1":
-        env["AUTOCODER_ALLOW_REMOTE"] = "1"
+        env["AUTOFORGE_ALLOW_REMOTE"] = "1"
 
     # NOTE: --reload is NOT used because on Windows it breaks asyncio subprocess
     # support (uvicorn's reload worker doesn't inherit the ProactorEventLoop policy).
@@ -313,7 +313,7 @@ def start_production_server(port: int, host: str = "127.0.0.1"):
 
 def main() -> None:
     """Main entry point."""
-    parser = argparse.ArgumentParser(description="AutoCoder UI Launcher")
+    parser = argparse.ArgumentParser(description="AutoForge UI Launcher")
     parser.add_argument("--dev", action="store_true", help="Run in development mode with Vite hot reload")
     parser.add_argument("--host", default="127.0.0.1", help="Host to bind to (default: 127.0.0.1)")
     parser.add_argument("--port", type=int, default=None, help="Port to bind to (default: auto-detect from 8888)")
@@ -328,7 +328,7 @@ def main() -> None:
         print("  SECURITY WARNING")
         print("!" * 50)
         print(f"  Remote access enabled on host: {host}")
-        print("  The AutoCoder UI will be accessible from other machines.")
+        print("  The AutoForge UI will be accessible from other machines.")
         print("  Ensure you understand the security implications:")
         print("  - The agent has file system access to project directories")
         print("  - The API can start/stop agents and modify files")
@@ -336,7 +336,7 @@ def main() -> None:
         print("!" * 50 + "\n")
 
     print("=" * 50)
-    print("  AutoCoder UI Setup")
+    print("  AutoForge UI Setup")
     print("=" * 50)
 
     total_steps = 6 if not dev_mode else 5

start_ui.sh

@@ -1,11 +1,11 @@
 #!/bin/bash
 cd "$(dirname "$0")"
-# AutoCoder UI Launcher for Unix/Linux/macOS
+# AutoForge UI Launcher for Unix/Linux/macOS
 # This script launches the web UI for the autonomous coding agent.
 
 echo ""
 echo "===================================="
-echo "  AutoCoder UI"
+echo "  AutoForge UI"
 echo "===================================="
 echo ""
 

temp_cleanup.py

@@ -0,0 +1,148 @@
+"""
+Temp Cleanup Module
+===================
+
+Cleans up stale temporary files and directories created by AutoForge agents,
+Playwright, Node.js, and other development tools.
+
+Called at Maestro (orchestrator) startup to prevent temp folder bloat.
+
+Why this exists:
+- Playwright creates browser profiles and artifacts in %TEMP%
+- Node.js creates .node cache files (~7MB each, can accumulate to GBs)
+- MongoDB Memory Server downloads binaries to temp
+- These are never cleaned up automatically
+
+When cleanup runs:
+- At Maestro startup (when you click Play or auto-restart after rate limits)
+- Only files/folders older than 1 hour are deleted (safe for running processes)
+"""
+
+import logging
+import shutil
+import tempfile
+import time
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Max age in seconds before a temp item is considered stale (1 hour)
+MAX_AGE_SECONDS = 3600
+
+# Directory patterns to clean up (glob patterns)
+DIR_PATTERNS = [
+    "playwright_firefoxdev_profile-*",  # Playwright Firefox profiles
+    "playwright-artifacts-*",           # Playwright test artifacts
+    "playwright-transform-cache",       # Playwright transform cache
+    "mongodb-memory-server*",           # MongoDB Memory Server binaries
+    "ng-*",                             # Angular CLI temp directories
+    "scoped_dir*",                      # Chrome/Chromium temp directories
+]
+
+# File patterns to clean up (glob patterns)
+FILE_PATTERNS = [
+    ".78912*.node",   # Node.js native module cache (major space consumer, ~7MB each)
+    "claude-*-cwd",   # Claude CLI working directory temp files
+    "mat-debug-*.log",  # Material/Angular debug logs
+]
+
+
+def cleanup_stale_temp(max_age_seconds: int = MAX_AGE_SECONDS) -> dict:
+    """
+    Clean up stale temporary files and directories.
+
+    Only deletes items older than max_age_seconds to avoid
+    interfering with currently running processes.
+
+    Args:
+        max_age_seconds: Maximum age in seconds before an item is deleted.
+                        Defaults to 1 hour (3600 seconds).
+
+    Returns:
+        Dictionary with cleanup statistics:
+        - dirs_deleted: Number of directories deleted
+        - files_deleted: Number of files deleted
+        - bytes_freed: Approximate bytes freed
+        - errors: List of error messages (for debugging, not fatal)
+    """
+    temp_dir = Path(tempfile.gettempdir())
+    cutoff_time = time.time() - max_age_seconds
+
+    stats = {
+        "dirs_deleted": 0,
+        "files_deleted": 0,
+        "bytes_freed": 0,
+        "errors": [],
+    }
+
+    # Clean up directories
+    for pattern in DIR_PATTERNS:
+        for item in temp_dir.glob(pattern):
+            if not item.is_dir():
+                continue
+            try:
+                mtime = item.stat().st_mtime
+                if mtime < cutoff_time:
+                    size = _get_dir_size(item)
+                    shutil.rmtree(item, ignore_errors=True)
+                    if not item.exists():
+                        stats["dirs_deleted"] += 1
+                        stats["bytes_freed"] += size
+                        logger.debug(f"Deleted temp directory: {item}")
+            except Exception as e:
+                stats["errors"].append(f"Failed to delete {item}: {e}")
+                logger.debug(f"Failed to delete {item}: {e}")
+
+    # Clean up files
+    for pattern in FILE_PATTERNS:
+        for item in temp_dir.glob(pattern):
+            if not item.is_file():
+                continue
+            try:
+                mtime = item.stat().st_mtime
+                if mtime < cutoff_time:
+                    size = item.stat().st_size
+                    item.unlink(missing_ok=True)
+                    if not item.exists():
+                        stats["files_deleted"] += 1
+                        stats["bytes_freed"] += size
+                        logger.debug(f"Deleted temp file: {item}")
+            except Exception as e:
+                stats["errors"].append(f"Failed to delete {item}: {e}")
+                logger.debug(f"Failed to delete {item}: {e}")
+
+    # Log summary if anything was cleaned
+    if stats["dirs_deleted"] > 0 or stats["files_deleted"] > 0:
+        mb_freed = stats["bytes_freed"] / (1024 * 1024)
+        logger.info(
+            f"Temp cleanup: {stats['dirs_deleted']} dirs, "
+            f"{stats['files_deleted']} files, {mb_freed:.1f} MB freed"
+        )
+
+    return stats
+
+
+def _get_dir_size(path: Path) -> int:
+    """Get total size of a directory in bytes."""
+    total = 0
+    try:
+        for item in path.rglob("*"):
+            if item.is_file():
+                try:
+                    total += item.stat().st_size
+                except (OSError, PermissionError):
+                    pass
+    except (OSError, PermissionError):
+        pass
+    return total
+
+
+if __name__ == "__main__":
+    # Allow running directly for testing/manual cleanup
+    logging.basicConfig(level=logging.DEBUG)
+    print("Running temp cleanup...")
+    stats = cleanup_stale_temp()
+    mb_freed = stats["bytes_freed"] / (1024 * 1024)
+    print(f"Cleanup complete: {stats['dirs_deleted']} dirs, {stats['files_deleted']} files, {mb_freed:.1f} MB freed")
+    if stats["errors"]:
+        print(f"Errors (non-fatal): {len(stats['errors'])}")

test_client.py

@@ -8,9 +8,17 @@ Run with: python test_client.py
 """
 
 import os
+import sys
+import tempfile
 import unittest
+from pathlib import Path
 
-from client import convert_model_for_vertex
+from client import (
+    EXTRA_READ_PATHS_BLOCKLIST,
+    EXTRA_READ_PATHS_VAR,
+    convert_model_for_vertex,
+    get_extra_read_paths,
+)
 
 
 class TestConvertModelForVertex(unittest.TestCase):
@@ -101,5 +109,157 @@ class TestConvertModelForVertex(unittest.TestCase):
         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_devserver_security.py

@@ -0,0 +1,319 @@
+#!/usr/bin/env python3
+"""
+Dev Server Security Tests
+=========================
+
+Tests for dev server command validation and security hardening.
+Run with: python -m pytest test_devserver_security.py -v
+"""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+# Add project root to path
+sys.path.insert(0, str(Path(__file__).parent))
+
+from server.routers.devserver import (
+    ALLOWED_NPM_SCRIPTS,
+    ALLOWED_PYTHON_MODULES,
+    ALLOWED_RUNNERS,
+    BLOCKED_SHELLS,
+    validate_custom_command_strict,
+)
+
+# =============================================================================
+# validate_custom_command_strict - Valid commands
+# =============================================================================
+
+
+class TestValidCommands:
+    """Commands that should pass validation."""
+
+    def test_npm_run_dev(self):
+        validate_custom_command_strict("npm run dev")
+
+    def test_npm_run_start(self):
+        validate_custom_command_strict("npm run start")
+
+    def test_npm_run_serve(self):
+        validate_custom_command_strict("npm run serve")
+
+    def test_npm_run_preview(self):
+        validate_custom_command_strict("npm run preview")
+
+    def test_pnpm_dev(self):
+        validate_custom_command_strict("pnpm dev")
+
+    def test_pnpm_run_dev(self):
+        validate_custom_command_strict("pnpm run dev")
+
+    def test_yarn_start(self):
+        validate_custom_command_strict("yarn start")
+
+    def test_yarn_run_serve(self):
+        validate_custom_command_strict("yarn run serve")
+
+    def test_uvicorn_basic(self):
+        validate_custom_command_strict("uvicorn main:app")
+
+    def test_uvicorn_with_flags(self):
+        validate_custom_command_strict("uvicorn main:app --host 0.0.0.0 --port 8000 --reload")
+
+    def test_uvicorn_flag_equals_syntax(self):
+        validate_custom_command_strict("uvicorn main:app --port=8000 --host=0.0.0.0")
+
+    def test_python_m_uvicorn(self):
+        validate_custom_command_strict("python -m uvicorn main:app --reload")
+
+    def test_python3_m_uvicorn(self):
+        validate_custom_command_strict("python3 -m uvicorn main:app")
+
+    def test_python_m_flask(self):
+        validate_custom_command_strict("python -m flask run")
+
+    def test_python_m_gunicorn(self):
+        validate_custom_command_strict("python -m gunicorn main:app")
+
+    def test_python_m_http_server(self):
+        validate_custom_command_strict("python -m http.server 8000")
+
+    def test_python_script(self):
+        validate_custom_command_strict("python app.py")
+
+    def test_python_manage_py_runserver(self):
+        validate_custom_command_strict("python manage.py runserver")
+
+    def test_python_manage_py_runserver_with_port(self):
+        validate_custom_command_strict("python manage.py runserver 0.0.0.0:8000")
+
+    def test_flask_run(self):
+        validate_custom_command_strict("flask run")
+
+    def test_flask_run_with_options(self):
+        validate_custom_command_strict("flask run --host 0.0.0.0 --port 5000")
+
+    def test_poetry_run_command(self):
+        validate_custom_command_strict("poetry run python app.py")
+
+    def test_cargo_run(self):
+        # cargo is allowed but has no special sub-validation
+        validate_custom_command_strict("cargo run")
+
+    def test_go_run(self):
+        # go is allowed but has no special sub-validation
+        validate_custom_command_strict("go run .")
+
+
+# =============================================================================
+# validate_custom_command_strict - Blocked shells
+# =============================================================================
+
+
+class TestBlockedShells:
+    """Shell interpreters that must be rejected."""
+
+    @pytest.mark.parametrize("shell", ["sh", "bash", "zsh", "cmd", "powershell", "pwsh", "cmd.exe"])
+    def test_blocked_shell(self, shell):
+        with pytest.raises(ValueError, match="runner not allowed"):
+            validate_custom_command_strict(f"{shell} -c 'echo hacked'")
+
+
+# =============================================================================
+# validate_custom_command_strict - Blocked commands
+# =============================================================================
+
+
+class TestBlockedCommands:
+    """Commands that should be rejected."""
+
+    def test_empty_command(self):
+        with pytest.raises(ValueError, match="cannot be empty"):
+            validate_custom_command_strict("")
+
+    def test_whitespace_only(self):
+        with pytest.raises(ValueError, match="cannot be empty"):
+            validate_custom_command_strict("   ")
+
+    def test_python_dash_c(self):
+        with pytest.raises(ValueError, match="python -c is not allowed"):
+            validate_custom_command_strict("python -c 'import os; os.system(\"rm -rf /\")'")
+
+    def test_python3_dash_c(self):
+        with pytest.raises(ValueError, match="python -c is not allowed"):
+            validate_custom_command_strict("python3 -c 'print(1)'")
+
+    def test_python_no_script_or_module(self):
+        with pytest.raises(ValueError, match="must use"):
+            validate_custom_command_strict("python --version")
+
+    def test_python_m_disallowed_module(self):
+        with pytest.raises(ValueError, match="not allowed"):
+            validate_custom_command_strict("python -m pip install something")
+
+    def test_unknown_runner(self):
+        with pytest.raises(ValueError, match="runner not allowed"):
+            validate_custom_command_strict("curl http://evil.com")
+
+    def test_rm_rf(self):
+        with pytest.raises(ValueError, match="runner not allowed"):
+            validate_custom_command_strict("rm -rf /")
+
+    def test_npm_arbitrary_script(self):
+        with pytest.raises(ValueError, match="npm custom_command"):
+            validate_custom_command_strict("npm run postinstall")
+
+    def test_npm_exec(self):
+        with pytest.raises(ValueError, match="npm custom_command"):
+            validate_custom_command_strict("npm exec evil-package")
+
+    def test_pnpm_arbitrary_script(self):
+        with pytest.raises(ValueError, match="pnpm custom_command"):
+            validate_custom_command_strict("pnpm run postinstall")
+
+    def test_yarn_arbitrary_script(self):
+        with pytest.raises(ValueError, match="yarn custom_command"):
+            validate_custom_command_strict("yarn run postinstall")
+
+    def test_uvicorn_no_app(self):
+        with pytest.raises(ValueError, match="must specify an app"):
+            validate_custom_command_strict("uvicorn --reload")
+
+    def test_uvicorn_disallowed_flag(self):
+        with pytest.raises(ValueError, match="flag not allowed"):
+            validate_custom_command_strict("uvicorn main:app --factory")
+
+    def test_flask_no_run(self):
+        with pytest.raises(ValueError, match="flask custom_command"):
+            validate_custom_command_strict("flask shell")
+
+    def test_poetry_no_run(self):
+        with pytest.raises(ValueError, match="poetry custom_command"):
+            validate_custom_command_strict("poetry install")
+
+
+# =============================================================================
+# validate_custom_command_strict - Injection attempts
+# =============================================================================
+
+
+class TestInjectionAttempts:
+    """Adversarial inputs that attempt to bypass validation."""
+
+    def test_shell_via_path_traversal(self):
+        with pytest.raises(ValueError, match="runner not allowed"):
+            validate_custom_command_strict("/bin/sh -c 'echo hacked'")
+
+    def test_shell_via_relative_path(self):
+        with pytest.raises(ValueError, match="runner not allowed"):
+            validate_custom_command_strict("../../bin/bash -c whoami")
+
+    def test_none_input(self):
+        with pytest.raises(ValueError, match="cannot be empty"):
+            validate_custom_command_strict(None)  # type: ignore[arg-type]
+
+    def test_integer_input(self):
+        with pytest.raises(ValueError, match="cannot be empty"):
+            validate_custom_command_strict(123)  # type: ignore[arg-type]
+
+    def test_python_dash_c_uppercase(self):
+        with pytest.raises(ValueError, match="python -c is not allowed"):
+            validate_custom_command_strict("python -C 'exec(evil)'")
+
+    def test_powershell_via_path(self):
+        with pytest.raises(ValueError, match="runner not allowed"):
+            validate_custom_command_strict("C:\\Windows\\System32\\powershell.exe -c Get-Process")
+
+
+# =============================================================================
+# dev_server_manager.py - dangerous_ops blocking
+# =============================================================================
+
+
+class TestDangerousOpsBlocking:
+    """Test the metacharacter blocking in dev_server_manager.start()."""
+
+    @pytest.fixture
+    def manager(self, tmp_path):
+        from server.services.dev_server_manager import DevServerProcessManager
+        return DevServerProcessManager("test-project", tmp_path)
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize("cmd,desc", [
+        ("npm run dev && curl evil.com", "double ampersand"),
+        ("npm run dev & curl evil.com", "single ampersand"),
+        ("npm run dev || curl evil.com", "double pipe"),
+        ("npm run dev | curl evil.com", "single pipe"),
+        ("npm run dev ; curl evil.com", "semicolon"),
+        ("npm run dev `curl evil.com`", "backtick"),
+        ("npm run dev $(curl evil.com)", "dollar paren"),
+        ("npm run dev > /etc/passwd", "output redirect"),
+        ("npm run dev < /etc/passwd", "input redirect"),
+        ("npm run dev ^& calc", "caret escape"),
+        ("npm run %COMSPEC%", "percent env expansion"),
+    ])
+    async def test_blocks_shell_operator(self, manager, cmd, desc):
+        success, message = await manager.start(cmd)
+        assert not success, f"Should block {desc}: {cmd}"
+        assert "not allowed" in message.lower()
+
+    @pytest.mark.asyncio
+    async def test_blocks_newline_injection(self, manager):
+        success, message = await manager.start("npm run dev\ncurl evil.com")
+        assert not success
+        assert "newline" in message.lower()
+
+    @pytest.mark.asyncio
+    async def test_blocks_carriage_return(self, manager):
+        success, message = await manager.start("npm run dev\r\ncurl evil.com")
+        assert not success
+        assert "newline" in message.lower()
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize("shell", ["sh", "bash", "zsh", "cmd", "powershell", "pwsh"])
+    async def test_blocks_shell_runners(self, manager, shell):
+        success, message = await manager.start(f"{shell} -c 'echo hacked'")
+        assert not success
+        assert "not allowed" in message.lower()
+
+    @pytest.mark.asyncio
+    async def test_blocks_empty_command(self, manager):
+        success, message = await manager.start("")
+        assert not success
+        assert "empty" in message.lower()
+
+    @pytest.mark.asyncio
+    async def test_blocks_whitespace_command(self, manager):
+        success, message = await manager.start("   ")
+        assert not success
+        assert "empty" in message.lower()
+
+
+# =============================================================================
+# Constants validation
+# =============================================================================
+
+
+class TestConstants:
+    """Verify security constants are properly defined."""
+
+    def test_all_common_shells_blocked(self):
+        for shell in ["sh", "bash", "zsh", "cmd", "powershell", "pwsh", "cmd.exe"]:
+            assert shell in BLOCKED_SHELLS, f"{shell} should be in BLOCKED_SHELLS"
+
+    def test_common_npm_scripts_allowed(self):
+        for script in ["dev", "start", "serve", "preview"]:
+            assert script in ALLOWED_NPM_SCRIPTS, f"{script} should be in ALLOWED_NPM_SCRIPTS"
+
+    def test_common_python_modules_allowed(self):
+        for mod in ["uvicorn", "flask", "gunicorn"]:
+            assert mod in ALLOWED_PYTHON_MODULES, f"{mod} should be in ALLOWED_PYTHON_MODULES"
+
+    def test_common_runners_allowed(self):
+        for runner in ["npm", "pnpm", "yarn", "python", "python3", "uvicorn", "flask", "cargo", "go"]:
+            assert runner in ALLOWED_RUNNERS, f"{runner} should be in ALLOWED_RUNNERS"
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

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

@@ -273,11 +273,11 @@ def test_yaml_loading():
 
     with tempfile.TemporaryDirectory() as tmpdir:
         project_dir = Path(tmpdir)
-        autocoder_dir = project_dir / ".autocoder"
+        autoforge_dir = project_dir / ".autoforge"
-        autocoder_dir.mkdir()
+        autoforge_dir.mkdir()
 
         # Test 1: Valid YAML
-        config_path = autocoder_dir / "allowed_commands.yaml"
+        config_path = autoforge_dir / "allowed_commands.yaml"
         config_path.write_text("""version: 1
 commands:
   - name: swift
@@ -297,7 +297,7 @@ commands:
             failed += 1
 
         # Test 2: Missing file returns None
-        (project_dir / ".autocoder" / "allowed_commands.yaml").unlink()
+        (project_dir / ".autoforge" / "allowed_commands.yaml").unlink()
         config = load_project_commands(project_dir)
         if config is None:
             print("  PASS: Missing file returns None")
@@ -407,11 +407,11 @@ def test_project_commands():
 
     with tempfile.TemporaryDirectory() as tmpdir:
         project_dir = Path(tmpdir)
-        autocoder_dir = project_dir / ".autocoder"
+        autoforge_dir = project_dir / ".autoforge"
-        autocoder_dir.mkdir()
+        autoforge_dir.mkdir()
 
         # Create a config with Swift commands
-        config_path = autocoder_dir / "allowed_commands.yaml"
+        config_path = autoforge_dir / "allowed_commands.yaml"
         config_path.write_text("""version: 1
 commands:
   - name: swift
@@ -482,7 +482,7 @@ def test_org_config_loading():
     with tempfile.TemporaryDirectory() as tmpdir:
         # Use temporary_home for cross-platform compatibility
         with temporary_home(tmpdir):
-            org_dir = Path(tmpdir) / ".autocoder"
+            org_dir = Path(tmpdir) / ".autoforge"
             org_dir.mkdir()
             org_config_path = org_dir / "config.yaml"
 
@@ -576,7 +576,7 @@ def test_hierarchy_resolution():
         with tempfile.TemporaryDirectory() as tmpproject:
             # Use temporary_home for cross-platform compatibility
             with temporary_home(tmphome):
-                org_dir = Path(tmphome) / ".autocoder"
+                org_dir = Path(tmphome) / ".autoforge"
                 org_dir.mkdir()
                 org_config_path = org_dir / "config.yaml"
 
@@ -593,9 +593,9 @@ blocked_commands:
 """)
 
                 project_dir = Path(tmpproject)
-                project_autocoder = project_dir / ".autocoder"
+                project_autoforge = project_dir / ".autoforge"
-                project_autocoder.mkdir()
+                project_autoforge.mkdir()
-                project_config = project_autocoder / "allowed_commands.yaml"
+                project_config = project_autoforge / "allowed_commands.yaml"
 
                 # Create project config
                 project_config.write_text("""version: 1
@@ -660,7 +660,7 @@ def test_org_blocklist_enforcement():
         with tempfile.TemporaryDirectory() as tmpproject:
             # Use temporary_home for cross-platform compatibility
             with temporary_home(tmphome):
-                org_dir = Path(tmphome) / ".autocoder"
+                org_dir = Path(tmphome) / ".autoforge"
                 org_dir.mkdir()
                 org_config_path = org_dir / "config.yaml"
 
@@ -671,8 +671,8 @@ blocked_commands:
 """)
 
                 project_dir = Path(tmpproject)
-                project_autocoder = project_dir / ".autocoder"
+                project_autoforge = project_dir / ".autoforge"
-                project_autocoder.mkdir()
+                project_autoforge.mkdir()
 
                 # Try to use terraform (should be blocked)
                 input_data = {"tool_name": "Bash", "tool_input": {"command": "terraform apply"}}
@@ -735,7 +735,7 @@ def test_pkill_extensibility():
     with tempfile.TemporaryDirectory() as tmphome:
         with tempfile.TemporaryDirectory() as tmpproject:
             with temporary_home(tmphome):
-                org_dir = Path(tmphome) / ".autocoder"
+                org_dir = Path(tmphome) / ".autoforge"
                 org_dir.mkdir()
                 org_config_path = org_dir / "config.yaml"
 
@@ -762,9 +762,9 @@ pkill_processes:
         with tempfile.TemporaryDirectory() as tmpproject:
             with temporary_home(tmphome):
                 project_dir = Path(tmpproject)
-                project_autocoder = project_dir / ".autocoder"
+                project_autoforge = project_dir / ".autoforge"
-                project_autocoder.mkdir()
+                project_autoforge.mkdir()
-                project_config = project_autocoder / "allowed_commands.yaml"
+                project_config = project_autoforge / "allowed_commands.yaml"
 
                 # Create project config with extra pkill processes
                 project_config.write_text("""version: 1
@@ -804,7 +804,7 @@ pkill_processes:
     with tempfile.TemporaryDirectory() as tmphome:
         with tempfile.TemporaryDirectory() as tmpproject:
             with temporary_home(tmphome):
-                org_dir = Path(tmphome) / ".autocoder"
+                org_dir = Path(tmphome) / ".autoforge"
                 org_dir.mkdir()
                 org_config_path = org_dir / "config.yaml"
 
@@ -829,7 +829,7 @@ pkill_processes:
     with tempfile.TemporaryDirectory() as tmphome:
         with tempfile.TemporaryDirectory() as tmpproject:
             with temporary_home(tmphome):
-                org_dir = Path(tmphome) / ".autocoder"
+                org_dir = Path(tmphome) / ".autoforge"
                 org_dir.mkdir()
                 org_config_path = org_dir / "config.yaml"
 
@@ -851,7 +851,7 @@ pkill_processes:
     with tempfile.TemporaryDirectory() as tmphome:
         with tempfile.TemporaryDirectory() as tmpproject:
             with temporary_home(tmphome):
-                org_dir = Path(tmphome) / ".autocoder"
+                org_dir = Path(tmphome) / ".autoforge"
                 org_dir.mkdir()
                 org_config_path = org_dir / "config.yaml"
 
@@ -875,7 +875,7 @@ pkill_processes:
     with tempfile.TemporaryDirectory() as tmphome:
         with tempfile.TemporaryDirectory() as tmpproject:
             with temporary_home(tmphome):
-                org_dir = Path(tmphome) / ".autocoder"
+                org_dir = Path(tmphome) / ".autoforge"
                 org_dir.mkdir()
                 org_config_path = org_dir / "config.yaml"
 
@@ -992,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:
@@ -1026,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
@@ -1076,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",
     ]
 

test_security_integration.py

@@ -79,9 +79,9 @@ def test_blocked_command_via_hook():
         project_dir = Path(tmpdir)
 
         # Create minimal project structure
-        autocoder_dir = project_dir / ".autocoder"
+        autoforge_dir = project_dir / ".autoforge"
-        autocoder_dir.mkdir()
+        autoforge_dir.mkdir()
-        (autocoder_dir / "allowed_commands.yaml").write_text(
+        (autoforge_dir / "allowed_commands.yaml").write_text(
             "version: 1\ncommands: []"
         )
 
@@ -114,9 +114,9 @@ def test_allowed_command_via_hook():
         project_dir = Path(tmpdir)
 
         # Create minimal project structure
-        autocoder_dir = project_dir / ".autocoder"
+        autoforge_dir = project_dir / ".autoforge"
-        autocoder_dir.mkdir()
+        autoforge_dir.mkdir()
-        (autocoder_dir / "allowed_commands.yaml").write_text(
+        (autoforge_dir / "allowed_commands.yaml").write_text(
             "version: 1\ncommands: []"
         )
 
@@ -145,9 +145,9 @@ def test_non_allowed_command_via_hook():
         project_dir = Path(tmpdir)
 
         # Create minimal project structure
-        autocoder_dir = project_dir / ".autocoder"
+        autoforge_dir = project_dir / ".autoforge"
-        autocoder_dir.mkdir()
+        autoforge_dir.mkdir()
-        (autocoder_dir / "allowed_commands.yaml").write_text(
+        (autoforge_dir / "allowed_commands.yaml").write_text(
             "version: 1\ncommands: []"
         )
 
@@ -179,9 +179,9 @@ def test_project_config_allows_command():
         project_dir = Path(tmpdir)
 
         # Create project config with swift allowed
-        autocoder_dir = project_dir / ".autocoder"
+        autoforge_dir = project_dir / ".autoforge"
-        autocoder_dir.mkdir()
+        autoforge_dir.mkdir()
-        (autocoder_dir / "allowed_commands.yaml").write_text("""version: 1
+        (autoforge_dir / "allowed_commands.yaml").write_text("""version: 1
 commands:
   - name: swift
     description: Swift compiler
@@ -214,9 +214,9 @@ def test_pattern_matching():
         project_dir = Path(tmpdir)
 
         # Create project config with swift* pattern
-        autocoder_dir = project_dir / ".autocoder"
+        autoforge_dir = project_dir / ".autoforge"
-        autocoder_dir.mkdir()
+        autoforge_dir.mkdir()
-        (autocoder_dir / "allowed_commands.yaml").write_text("""version: 1
+        (autoforge_dir / "allowed_commands.yaml").write_text("""version: 1
 commands:
   - name: swift*
     description: All Swift tools
@@ -247,7 +247,7 @@ def test_org_blocklist_enforcement():
         with tempfile.TemporaryDirectory() as tmpproject:
             # Use context manager to safely set and restore HOME
             with temporary_home(tmphome):
-                org_dir = Path(tmphome) / ".autocoder"
+                org_dir = Path(tmphome) / ".autoforge"
                 org_dir.mkdir()
                 (org_dir / "config.yaml").write_text("""version: 1
 allowed_commands: []
@@ -257,11 +257,11 @@ blocked_commands:
 """)
 
                 project_dir = Path(tmpproject)
-                autocoder_dir = project_dir / ".autocoder"
+                autoforge_dir = project_dir / ".autoforge"
-                autocoder_dir.mkdir()
+                autoforge_dir.mkdir()
 
                 # Try to allow terraform in project config (should fail - org blocked)
-                (autocoder_dir / "allowed_commands.yaml").write_text("""version: 1
+                (autoforge_dir / "allowed_commands.yaml").write_text("""version: 1
 commands:
   - name: terraform
     description: Infrastructure as code
@@ -295,7 +295,7 @@ def test_org_allowlist_inheritance():
         with tempfile.TemporaryDirectory() as tmpproject:
             # Use context manager to safely set and restore HOME
             with temporary_home(tmphome):
-                org_dir = Path(tmphome) / ".autocoder"
+                org_dir = Path(tmphome) / ".autoforge"
                 org_dir.mkdir()
                 (org_dir / "config.yaml").write_text("""version: 1
 allowed_commands:
@@ -305,9 +305,9 @@ blocked_commands: []
 """)
 
                 project_dir = Path(tmpproject)
-                autocoder_dir = project_dir / ".autocoder"
+                autoforge_dir = project_dir / ".autoforge"
-                autocoder_dir.mkdir()
+                autoforge_dir.mkdir()
-                (autocoder_dir / "allowed_commands.yaml").write_text(
+                (autoforge_dir / "allowed_commands.yaml").write_text(
                     "version: 1\ncommands: []"
                 )
 
@@ -336,9 +336,9 @@ def test_invalid_yaml_ignored():
         project_dir = Path(tmpdir)
 
         # Create invalid YAML
-        autocoder_dir = project_dir / ".autocoder"
+        autoforge_dir = project_dir / ".autoforge"
-        autocoder_dir.mkdir()
+        autoforge_dir.mkdir()
-        (autocoder_dir / "allowed_commands.yaml").write_text("invalid: yaml: content:")
+        (autoforge_dir / "allowed_commands.yaml").write_text("invalid: yaml: content:")
 
         # Try to run ls (should still work - falls back to defaults)
         input_data = {"tool_name": "Bash", "tool_input": {"command": "ls"}}
@@ -365,13 +365,13 @@ def test_100_command_limit():
         project_dir = Path(tmpdir)
 
         # Create config with 101 commands
-        autocoder_dir = project_dir / ".autocoder"
+        autoforge_dir = project_dir / ".autoforge"
-        autocoder_dir.mkdir()
+        autoforge_dir.mkdir()
 
         commands = [
             f"  - name: cmd{i}\n    description: Command {i}" for i in range(101)
         ]
-        (autocoder_dir / "allowed_commands.yaml").write_text(
+        (autoforge_dir / "allowed_commands.yaml").write_text(
             "version: 1\ncommands:\n" + "\n".join(commands)
         )
 

ui/index.html

@@ -2,9 +2,9 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <link rel="icon" type="image/png" href="/logo.png" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>AutoCoder</title>
+    <title>AutoForge</title>
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Archivo+Black&family=Work+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&family=DM+Sans:wght@400;500;700&family=Space+Mono:wght@400;700&family=Outfit:wght@400;500;600;700&family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">

ui/package-lock.json

@@ -1,32 +1,26 @@
 {
-  "name": "autocoder",
+  "name": "autoforge-ui",
   "version": "1.0.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "autocoder",
+      "name": "autoforge-ui",
       "version": "1.0.0",
       "dependencies": {
         "@radix-ui/react-checkbox": "^1.3.3",
         "@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",
         "@xterm/xterm": "^6.0.0",
         "@xyflow/react": "^12.10.0",
+        "autoforge-ai": "file:..",
         "canvas-confetti": "^1.9.4",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
@@ -57,6 +51,17 @@
         "vite": "^7.3.0"
       }
     },
+    "..": {
+      "name": "autoforge-ai",
+      "version": "0.1.3",
+      "license": "AGPL-3.0",
+      "bin": {
+        "autoforge": "bin/autoforge.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
     "node_modules/@babel/code-frame": {
       "version": "7.27.1",
       "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.27.1.tgz",
@@ -1093,12 +1098,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 +1518,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 +1639,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 +1670,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 +1763,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 +1899,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",
@@ -3458,6 +3148,10 @@
         "node": ">=10"
       }
     },
+    "node_modules/autoforge-ai": {
+      "resolved": "..",
+      "link": true
+    },
     "node_modules/balanced-match": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",

ui/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "autocoder",
+  "name": "autoforge-ui",
   "private": true,
   "version": "1.0.0",
   "type": "module",
@@ -16,21 +16,15 @@
     "@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",
     "@xterm/xterm": "^6.0.0",
     "@xyflow/react": "^12.10.0",
+    "autoforge-ai": "file:..",
     "canvas-confetti": "^1.9.4",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

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'
@@ -28,19 +27,21 @@ import { KeyboardShortcutsHelp } from './components/KeyboardShortcutsHelp'
 import { ThemeSelector } from './components/ThemeSelector'
 import { ResetProjectModal } from './components/ResetProjectModal'
 import { ProjectSetupRequired } from './components/ProjectSetupRequired'
-import { getDependencyGraph } from './lib/api'
+import { getDependencyGraph, startAgent } from './lib/api'
-import { Loader2, Settings, Moon, Sun, RotateCcw } from 'lucide-react'
+import { Loader2, Settings, Moon, Sun, RotateCcw, BookOpen } from 'lucide-react'
 import type { Feature } from './lib/types'
 import { Button } from '@/components/ui/button'
 import { Card, CardContent } from '@/components/ui/card'
 import { Badge } from '@/components/ui/badge'
 
-const STORAGE_KEY = 'autocoder-selected-project'
+const STORAGE_KEY = 'autoforge-selected-project'
-const VIEW_MODE_KEY = 'autocoder-view-mode'
+const VIEW_MODE_KEY = 'autoforge-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>(() => {
@@ -63,6 +64,8 @@ function App() {
   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)
@@ -260,9 +263,12 @@ function App() {
         <div className="max-w-7xl mx-auto px-4 py-4">
           <div className="flex items-center justify-between">
             {/* Logo and Title */}
-            <h1 className="font-display text-2xl font-bold tracking-tight uppercase">
+            <div className="flex items-center gap-3">
-              AutoCoder
+              <img src="/logo.png" alt="AutoForge" className="h-9 w-9 rounded-full" />
-            </h1>
+              <h1 className="font-display text-2xl font-bold tracking-tight uppercase">
+                AutoForge
+              </h1>
+            </div>
 
             {/* Controls */}
             <div className="flex items-center gap-4">
@@ -332,6 +338,17 @@ function App() {
                 </>
               )}
 
+              {/* Docs link */}
+              <Button
+                onClick={() => window.open('https://autoforge.cc', '_blank')}
+                variant="outline"
+                size="sm"
+                title="Documentation"
+                aria-label="Open Documentation"
+              >
+                <BookOpen size={18} />
+              </Button>
+
               {/* Theme selector */}
               <ThemeSelector
                 themes={themes}
@@ -362,7 +379,7 @@ function App() {
         {!selectedProject ? (
           <div className="text-center mt-12">
             <h2 className="font-display text-2xl font-bold mb-2">
-              Welcome to AutoCoder
+              Welcome to AutoForge
             </h2>
             <p className="text-muted-foreground mb-4">
               Select a project from the dropdown above or create a new one to get started.
@@ -386,6 +403,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 */}
@@ -396,13 +415,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 &&
@@ -495,14 +507,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>
       )}

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/AgentMissionControl.tsx

@@ -8,7 +8,7 @@ import { Card, CardContent } from '@/components/ui/card'
 import { Badge } from '@/components/ui/badge'
 import { Button } from '@/components/ui/button'
 
-const ACTIVITY_COLLAPSED_KEY = 'autocoder-activity-collapsed'
+const ACTIVITY_COLLAPSED_KEY = 'autoforge-activity-collapsed'
 
 interface AgentMissionControlProps {
   agents: ActiveAgent[]
@@ -88,8 +88,8 @@ export function AgentMissionControl({
       {/* Content */}
       <div
         className={`
-          transition-all duration-300 ease-out overflow-hidden
+          transition-all duration-300 ease-out
-          ${isExpanded ? 'max-h-[600px] opacity-100' : 'max-h-0 opacity-0'}
+          ${isExpanded ? 'max-h-[600px] opacity-100 overflow-y-auto' : 'max-h-0 opacity-0 overflow-hidden'}
         `}
       >
         <CardContent className="p-4">

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/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/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/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

@@ -228,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">
@@ -303,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">
@@ -451,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/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/dialog.tsx

@@ -59,7 +59,7 @@ function DialogContent({
       <DialogPrimitive.Content
         data-slot="dialog-content"
         className={cn(
-          "bg-background 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 fixed top-[50%] left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] gap-4 rounded-lg border p-6 shadow-lg duration-200 outline-none sm:max-w-lg",
+          "bg-background 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 fixed top-[50%] left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] max-h-[calc(100vh-2rem)] translate-x-[-50%] translate-y-[-50%] gap-4 rounded-lg border p-6 shadow-lg duration-200 outline-none overflow-y-auto sm:max-w-lg",
           className
         )}
         {...props}

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 }