Merge pull request #783 from DhanushSantosh/patchcraft

fix: release workflow assets + missing EventType entry

.github/actions/setup-project/action.yml

@@ -45,6 +45,7 @@ runs:
       run: npm install --ignore-scripts --force
 
     - name: Install Linux native bindings
+      if: runner.os == 'Linux'
       shell: bash
       # Workaround for npm optional dependencies bug (npm/cli#4828)
       # Explicitly install Linux bindings needed for build tools

.github/workflows/release.yml

@@ -95,9 +95,11 @@ jobs:
   upload:
     needs: build
     runs-on: ubuntu-latest
-    if: github.event.release.draft == false
 
     steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
       - name: Download macOS artifacts
         uses: actions/download-artifact@v4
         with:

.gitignore

@@ -90,8 +90,15 @@ pnpm-lock.yaml
 yarn.lock
 
 # Fork-specific workflow files (should never be committed)
+DEVELOPMENT_WORKFLOW.md
+check-sync.sh
 # API key files
 data/.api-key
 data/credentials.json
 data/
 .codex/
+
+# GSD planning docs (local-only)
+.planning/
+.mcp.json
+.planning

.planning/PROJECT.md

@@ -0,0 +1,81 @@
+# AutoModeService Refactoring
+
+## What This Is
+
+A comprehensive refactoring of the `auto-mode-service.ts` file (5k+ lines) into smaller, focused services with clear boundaries. This is an architectural cleanup of accumulated technical debt from rapid development, breaking the "god object" anti-pattern into maintainable, debuggable modules.
+
+## Core Value
+
+All existing auto-mode functionality continues working — features execute, pipelines flow, merges complete — while the codebase becomes maintainable.
+
+## Requirements
+
+### Validated
+
+<!-- Existing functionality that must be preserved -->
+
+- ✓ Single feature execution with AI agent — existing
+- ✓ Concurrent execution with configurable limits — existing
+- ✓ Pipeline orchestration (backlog → in-progress → approval → verified) — existing
+- ✓ Git worktree isolation per feature — existing
+- ✓ Automatic merging of completed work — existing
+- ✓ Custom pipeline support — existing
+- ✓ Test runner integration — existing
+- ✓ Event streaming to frontend — existing
+
+### Active
+
+<!-- Refactoring goals -->
+
+- [ ] No service file exceeds ~500 lines
+- [ ] Each service has single, clear responsibility
+- [ ] Service boundaries make debugging obvious
+- [ ] Changes to one service don't risk breaking unrelated features
+- [ ] Test coverage for critical paths
+
+### Out of Scope
+
+- New auto-mode features — this is cleanup, not enhancement
+- UI changes — backend refactor only
+- Performance optimization — maintain current performance, don't optimize
+- Other service refactoring — focus on auto-mode-service.ts only
+
+## Context
+
+**Current state:** `apps/server/src/services/auto-mode-service.ts` is ~5700 lines handling:
+
+- Worktree management (create, cleanup, track)
+- Agent/task execution coordination
+- Concurrency control and queue management
+- Pipeline state machine (column transitions)
+- Merge handling and conflict resolution
+- Event emission for real-time updates
+
+**Technical environment:**
+
+- Express 5 backend, TypeScript
+- Event-driven architecture via EventEmitter
+- WebSocket streaming to React frontend
+- Git worktrees via @automaker/git-utils
+- Minimal existing test coverage
+
+**Codebase analysis:** See `.planning/codebase/` for full architecture, conventions, and existing patterns.
+
+## Constraints
+
+- **Breaking changes**: Acceptable — other parts of the app can be updated to match new service interfaces
+- **Test coverage**: Currently minimal — must add tests during refactoring to catch regressions
+- **Incremental approach**: Required — can't do big-bang rewrite with everything critical
+- **Existing patterns**: Follow conventions in `.planning/codebase/CONVENTIONS.md`
+
+## Key Decisions
+
+| Decision                  | Rationale                                           | Outcome   |
+| ------------------------- | --------------------------------------------------- | --------- |
+| Accept breaking changes   | Allows cleaner interfaces, worth the migration cost | — Pending |
+| Add tests during refactor | No existing safety net, need to build one           | — Pending |
+| Incremental extraction    | Everything is critical, can't break it all at once  | — Pending |
+
+---
+
+_Last updated: 2026-01-27 after initialization_

.planning/codebase/ARCHITECTURE.md

@@ -0,0 +1,234 @@
+# Architecture
+
+**Analysis Date:** 2026-01-27
+
+## Pattern Overview
+
+**Overall:** Monorepo with layered client-server architecture (Electron-first) and pluggable provider abstraction for AI models.
+
+**Key Characteristics:**
+
+- Event-driven communication via WebSocket between frontend and backend
+- Multi-provider AI model abstraction layer (Claude, Cursor, Codex, Gemini, OpenCode, Copilot)
+- Feature-centric workflow stored in `.automaker/` directories
+- Isolated git worktree execution for each feature
+- State management through Zustand stores with API persistence
+
+## Layers
+
+**Presentation Layer (UI):**
+
+- Purpose: React 19 Electron/web frontend with TanStack Router file-based routing
+- Location: `apps/ui/src/`
+- Contains: Route components, view pages, custom React hooks, Zustand stores, API client
+- Depends on: @automaker/types, @automaker/utils, HTTP API backend
+- Used by: Electron main process (desktop), web browser (web mode)
+
+**API Layer (Server):**
+
+- Purpose: Express 5 backend exposing RESTful and WebSocket endpoints
+- Location: `apps/server/src/`
+- Contains: Route handlers, business logic services, middleware, provider adapters
+- Depends on: @automaker/types, @automaker/utils, @automaker/platform, Claude Agent SDK
+- Used by: UI frontend via HTTP/WebSocket
+
+**Service Layer (Server):**
+
+- Purpose: Business logic and domain operations
+- Location: `apps/server/src/services/`
+- Contains: AgentService, FeatureLoader, AutoModeService, SettingsService, DevServerService, etc.
+- Depends on: Providers, secure filesystem, feature storage
+- Used by: Route handlers
+
+**Provider Abstraction (Server):**
+
+- Purpose: Unified interface for different AI model providers
+- Location: `apps/server/src/providers/`
+- Contains: ProviderFactory, specific provider implementations (ClaudeProvider, CursorProvider, CodexProvider, GeminiProvider, OpencodeProvider, CopilotProvider)
+- Depends on: @automaker/types, provider SDKs
+- Used by: AgentService
+
+**Shared Library Layer:**
+
+- Purpose: Type definitions and utilities shared across apps
+- Location: `libs/`
+- Contains: @automaker/types, @automaker/utils, @automaker/platform, @automaker/prompts, @automaker/model-resolver, @automaker/dependency-resolver, @automaker/git-utils, @automaker/spec-parser
+- Depends on: None (types has no external deps)
+- Used by: All apps and services
+
+## Data Flow
+
+**Feature Execution Flow:**
+
+1. User creates/updates feature via UI (`apps/ui/src/`)
+2. UI sends HTTP request to backend (`POST /api/features`)
+3. Server route handler invokes FeatureLoader to persist to `.automaker/features/{featureId}/`
+4. When executing, AgentService loads feature, creates isolated git worktree via @automaker/git-utils
+5. AgentService invokes ProviderFactory to get appropriate AI provider (Claude, Cursor, etc.)
+6. Provider executes with context from CLAUDE.md files via @automaker/utils loadContextFiles()
+7. Server emits events via EventEmitter throughout execution
+8. Events stream to frontend via WebSocket
+9. UI updates stores and renders real-time progress
+10. Feature results persist back to `.automaker/features/` with generated agent-output.md
+
+**State Management:**
+
+**Frontend State (Zustand):**
+
+- `app-store.ts`: Global app state (projects, features, settings, boards, themes)
+- `setup-store.ts`: First-time setup wizard flow
+- `ideation-store.ts`: Ideation feature state
+- `test-runners-store.ts`: Test runner configurations
+- Settings now persist via API (`/api/settings`) rather than localStorage (see use-settings-sync.ts)
+
+**Backend State (Services):**
+
+- SettingsService: Global and project-specific settings (in-memory with file persistence)
+- AgentService: Active agent sessions and conversation history
+- FeatureLoader: Feature data model operations
+- DevServerService: Development server logs
+- EventHistoryService: Persists event logs for replay
+
+**Real-Time Updates (WebSocket):**
+
+- Server EventEmitter emits TypedEvent (type + payload)
+- WebSocket handler subscribes to events and broadcasts to all clients
+- Frontend listens on multiple WebSocket subscriptions and updates stores
+
+## Key Abstractions
+
+**Feature:**
+
+- Purpose: Represents a development task/story with rich metadata
+- Location: @automaker/types → `libs/types/src/feature.ts`
+- Fields: id, title, description, status, images, tasks, priority, etc.
+- Stored: `.automaker/features/{featureId}/feature.json`
+
+**Provider:**
+
+- Purpose: Abstracts different AI model implementations
+- Location: `apps/server/src/providers/{provider}-provider.ts`
+- Interface: Common execute() method with consistent message format
+- Implementations: Claude, Cursor, Codex, Gemini, OpenCode, Copilot
+- Factory: ProviderFactory picks correct provider based on model ID
+
+**Event:**
+
+- Purpose: Real-time updates streamed to frontend
+- Location: @automaker/types → `libs/types/src/event.ts`
+- Format: { type: EventType, payload: unknown }
+- Examples: agent-started, agent-step, agent-complete, feature-updated, etc.
+
+**AgentSession:**
+
+- Purpose: Represents a conversation between user and AI agent
+- Location: @automaker/types → `libs/types/src/session.ts`
+- Contains: Messages (user + assistant), metadata, creation timestamp
+- Stored: `{DATA_DIR}/agent-sessions/{sessionId}.json`
+
+**Settings:**
+
+- Purpose: Configuration for global and per-project behavior
+- Location: @automaker/types → `libs/types/src/settings.ts`
+- Stored: Global in `{DATA_DIR}/settings.json`, per-project in `.automaker/settings.json`
+- Service: SettingsService in `apps/server/src/services/settings-service.ts`
+
+## Entry Points
+
+**Server:**
+
+- Location: `apps/server/src/index.ts`
+- Triggers: `npm run dev:server` or Docker startup
+- Responsibilities:
+  - Initialize Express app with middleware
+  - Create shared EventEmitter for WebSocket streaming
+  - Bootstrap services (SettingsService, AgentService, FeatureLoader, etc.)
+  - Mount API routes at `/api/*`
+  - Create WebSocket servers for agent streaming and terminal sessions
+  - Load and apply user settings (log level, request logging, etc.)
+
+**UI (Web):**
+
+- Location: `apps/ui/src/main.ts` (Vite entry), `apps/ui/src/app.tsx` (React component)
+- Triggers: `npm run dev:web` or `npm run build`
+- Responsibilities:
+  - Initialize Zustand stores from API settings
+  - Setup React Router with TanStack Router
+  - Render root layout with sidebar and main content area
+  - Handle authentication via verifySession()
+
+**UI (Electron):**
+
+- Location: `apps/ui/src/main.ts` (Vite entry), `apps/ui/electron/main-process.ts` (Electron main process)
+- Triggers: `npm run dev:electron`
+- Responsibilities:
+  - Launch local server via node-pty
+  - Create native Electron window
+  - Bridge IPC between renderer and main process
+  - Provide file system access via preload.ts APIs
+
+## Error Handling
+
+**Strategy:** Layered error classification and user-friendly messaging
+
+**Patterns:**
+
+**Backend Error Handling:**
+
+- Errors classified via `classifyError()` from @automaker/utils
+- Classification: ParseError, NetworkError, AuthenticationError, RateLimitError, etc.
+- Response format: `{ success: false, error: { type, message, code }, details? }`
+- Example: `apps/server/src/lib/error-handler.ts`
+
+**Frontend Error Handling:**
+
+- HTTP errors caught by api-fetch.ts with retry logic
+- WebSocket disconnects trigger reconnection with exponential backoff
+- Errors shown in toast notifications via `sonner` library
+- Validation errors caught and displayed inline in forms
+
+**Agent Execution Errors:**
+
+- AgentService wraps provider calls in try-catch
+- Aborts handled specially via `isAbortError()` check
+- Rate limit errors trigger cooldown before retry
+- Model-specific errors mapped to user guidance
+
+## Cross-Cutting Concerns
+
+**Logging:**
+
+- Framework: @automaker/utils createLogger()
+- Pattern: `const logger = createLogger('ModuleName')`
+- Levels: ERROR, WARN, INFO, DEBUG (configurable via settings)
+- Output: stdout (dev), files (production)
+
+**Validation:**
+
+- File path validation: @automaker/platform initAllowedPaths() enforces restrictions
+- Model ID validation: @automaker/model-resolver resolveModelString()
+- JSON schema validation: Manual checks in route handlers (no JSON schema lib)
+- Authentication: Session token validation via validateWsConnectionToken()
+
+**Authentication:**
+
+- Frontend: Session token stored in httpOnly cookie
+- Backend: authMiddleware checks token on protected routes
+- WebSocket: validateWsConnectionToken() for upgrade requests
+- Providers: API keys stored encrypted in `{DATA_DIR}/credentials.json`
+
+**Internationalization:**
+
+- Not detected - strings are English-only
+
+**Performance:**
+
+- Code splitting: File-based routing via TanStack Router
+- Lazy loading: React.lazy() in route components
+- Caching: React Query for HTTP requests (query-keys.ts defines cache strategy)
+- Image optimization: Automatic base64 encoding for agent context
+- State hydration: Settings loaded once at startup, synced via API
+
+---
+
+_Architecture analysis: 2026-01-27_

.planning/codebase/CONCERNS.md

@@ -0,0 +1,245 @@
+# Codebase Concerns
+
+**Analysis Date:** 2026-01-27
+
+## Tech Debt
+
+**Loose Type Safety in Error Handling:**
+
+- Issue: Multiple uses of `as any` type assertions bypass TypeScript safety, particularly in error context handling and provider responses
+- Files: `apps/server/src/providers/claude-provider.ts` (lines 318-322), `apps/server/src/lib/error-handler.ts`, `apps/server/src/routes/settings/routes/update-global.ts`
+- Impact: Errors could have unchecked properties; refactoring becomes risky without compiler assistance
+- Fix approach: Replace `as any` with proper type guards and discriminated unions; create helper functions for safe property access
+
+**Missing Test Coverage for Critical Services:**
+
+- Issue: Several core services explicitly excluded from test coverage thresholds due to integration complexity
+- Files: `apps/server/vitest.config.ts` (line 22), explicitly excluded: `claude-usage-service.ts`, `mcp-test-service.ts`, `cli-provider.ts`, `cursor-provider.ts`
+- Impact: Usage tracking, MCP integration, and CLI detection could break undetected; regression detection is limited
+- Fix approach: Create integration test fixtures for CLI providers; mock MCP SDK for mcp-test-service tests; add usage tracking unit tests with mocked API calls
+
+**Unused/Stub TODO Item Processing:**
+
+- Issue: TodoWrite tool implementation exists but is partially integrated; tool name constants scattered across codex provider
+- Files: `apps/server/src/providers/codex-tool-mapping.ts`, `apps/server/src/providers/codex-provider.ts`
+- Impact: Todo list updates may not synchronize properly with all providers; unclear which providers support TodoWrite
+- Fix approach: Consolidate tool name constants; add provider capability flags for todo support
+
+**Electron Electron.ts Size and Complexity:**
+
+- Issue: Single 3741-line file handles all Electron IPC, native bindings, and communication
+- Files: `apps/ui/src/lib/electron.ts`
+- Impact: Difficult to test; hard to isolate bugs; changes require full testing of all features; potential memory overhead from monolithic file
+- Fix approach: Split by responsibility (IPC, window management, file operations, debug tools); create separate bridge layers
+
+## Known Bugs
+
+**API Key Management Incomplete for Gemini:**
+
+- Symptoms: Gemini API key verification endpoint not implemented despite other providers having verification
+- Files: `apps/ui/src/components/views/settings-view/api-keys/hooks/use-api-key-management.ts` (line 122)
+- Trigger: User tries to verify Gemini API key in settings
+- Workaround: Key verification skipped for Gemini; settings page still accepts and stores key
+
+**Orphaned Features Detection Vulnerable to False Negatives:**
+
+- Symptoms: Features marked as orphaned when branch matching logic doesn't account for all scenarios
+- Files: `apps/server/src/services/auto-mode-service.ts` (lines 5714-5773)
+- Trigger: Features that were manually switched branches or rebased
+- Workaround: Manual cleanup via feature deletion; branch comparison is basic name matching only
+
+**Terminal Themes Incomplete:**
+
+- Symptoms: Light theme themes (solarizedlight, github) map to same generic lightTheme; no dedicated implementations
+- Files: `apps/ui/src/config/terminal-themes.ts` (lines 593-594)
+- Trigger: User selects solarizedlight or github terminal theme
+- Workaround: Uses generic light theme instead of specific scheme; visual appearance doesn't match expectation
+
+## Security Considerations
+
+**Process Environment Variable Exposure:**
+
+- Risk: Child processes inherit all parent `process.env` including sensitive credentials (API keys, tokens)
+- Files: `apps/server/src/providers/cursor-provider.ts` (line 993), `apps/server/src/providers/codex-provider.ts` (line 1099)
+- Current mitigation: Dotenv provides isolation at app startup; selective env passing to some providers
+- Recommendations: Use explicit allowlists for env vars passed to child processes (only pass REQUIRED_KEYS); audit all spawn calls for env handling; document which providers need which credentials
+
+**Unvalidated Provider Tool Input:**
+
+- Risk: Tool input from CLI providers (Cursor, Copilot, Codex) is partially validated through Record<string, unknown> patterns; execution context could be escaped
+- Files: `apps/server/src/providers/codex-provider.ts` (lines 506-543), `apps/server/src/providers/tool-normalization.ts`
+- Current mitigation: Status enums validated; tool names checked against allow-lists in some providers
+- Recommendations: Implement comprehensive schema validation for all tool inputs before execution; use zod or similar for runtime validation; add security tests for injection patterns
+
+**API Key Storage in Settings Files:**
+
+- Risk: API keys stored in plaintext in `~/.automaker/settings.json` and `data/settings.json`; file permissions may not be restricted
+- Files: `apps/server/src/services/settings-service.ts`, uses `atomicWriteJson` without file permission enforcement
+- Current mitigation: Limited by file system permissions; Electron mode has single-user access
+- Recommendations: Encrypt sensitive settings fields (apiKeys, tokens); use OS credential stores (Keychain/Credential Manager) for production; add file permission checks on startup
+
+## Performance Bottlenecks
+
+**Synchronous Feature Loading at Startup:**
+
+- Problem: All features loaded synchronously at project load; blocks UI with 1000+ features
+- Files: `apps/server/src/services/feature-loader.ts` (line 230 Promise.all, but synchronous enumeration)
+- Cause: Feature directory walk and JSON parsing is not paginated or lazy-loaded
+- Improvement path: Implement lazy loading with pagination (load first 50, fetch more on scroll); add caching layer with TTL; move to background indexing; add feature count limits with warnings
+
+**Auto-Mode Concurrency at Max Can Exceed Rate Limits:**
+
+- Problem: maxConcurrency = 10 can quickly exhaust Claude API rate limits if all features execute simultaneously
+- Files: `apps/server/src/services/auto-mode-service.ts` (line 2931 Promise.all for concurrent agents)
+- Cause: No adaptive backoff; no API usage tracking before queuing; hint mentions reducing concurrency but doesn't enforce it
+- Improvement path: Integrate with claude-usage-service to check remaining quota before starting features; implement exponential backoff on 429 errors; add per-model rate limit tracking
+
+**Terminal Session Memory Leak Risk:**
+
+- Problem: Terminal sessions accumulate in memory; expired sessions not cleaned up reliably
+- Files: `apps/server/src/routes/terminal/common.ts` (line 66 cleanup runs every 5 minutes, but only for tokens)
+- Cause: Cleanup interval is arbitrary; session map not bounded; no session lifespan limit
+- Improvement path: Implement LRU eviction with max session count; reduce cleanup interval to 1 minute; add memory usage monitoring; auto-close idle sessions after 30 minutes
+
+**Large File Content Loading Without Limits:**
+
+- Problem: File content loaded entirely into memory; `describe-file.ts` truncates at 50KB but loads all content first
+- Files: `apps/server/src/routes/context/routes/describe-file.ts` (line 128)
+- Cause: Synchronous file read; no streaming; no check before reading large files
+- Improvement path: Check file size before reading; stream large files; add file size warnings; implement chunked processing for analysis
+
+## Fragile Areas
+
+**Provider Factory Model Resolution:**
+
+- Files: `apps/server/src/providers/provider-factory.ts`, `apps/server/src/providers/simple-query-service.ts`
+- Why fragile: Each provider interprets model strings differently; no central registry; model aliases resolved at multiple layers (model-resolver, provider-specific maps, CLI validation)
+- Safe modification: Add integration tests for each model alias per provider; create model capability matrix; centralize model validation before dispatch
+- Test coverage: No dedicated tests; relies on E2E; no isolated unit tests for model resolution
+
+**WebSocket Session Authentication:**
+
+- Files: `apps/server/src/lib/auth.ts` (line 40 setInterval), `apps/server/src/index.ts` (token validation per message)
+- Why fragile: Session tokens generated and validated at multiple points; no single source of truth; expiration is not atomic
+- Safe modification: Add tests for token expiration edge cases; ensure cleanup removes all references; log all auth failures
+- Test coverage: Auth middleware tested, but not session lifecycle
+
+**Auto-Mode Feature State Machine:**
+
+- Files: `apps/server/src/services/auto-mode-service.ts` (lines 465-600)
+- Why fragile: Multiple states (running, queued, completed, error) managed across different methods; no explicit state transition validation; error recovery is defensive (catches all, logs, continues)
+- Safe modification: Create explicit state enum with valid transitions; add invariant checks; unit test state transitions with all error cases
+- Test coverage: Gaps in error recovery paths; no tests for concurrent state changes
+
+## Scaling Limits
+
+**Feature Count Scalability:**
+
+- Current capacity: ~1000 features tested; UI performance degrades with pagination required
+- Limit: 10K+ features cause >5s load times; memory usage ~100MB for metadata alone
+- Scaling path: Implement feature database instead of file-per-feature; add ElasticSearch indexing for search; paginate API responses (50 per page); add feature archiving
+
+**Concurrent Auto-Mode Executions:**
+
+- Current capacity: maxConcurrency = 10 features; limited by Claude API rate limits
+- Limit: Rate limit hits at ~4-5 simultaneous features with extended context (100K+ tokens)
+- Scaling path: Implement token usage budgeting before feature start; queue features with estimated token cost; add provider-specific rate limit handling
+
+**Terminal Session Count:**
+
+- Current capacity: ~100 active terminal sessions per server
+- Limit: Memory grows unbounded; no session count limit enforced
+- Scaling path: Add max session count with least-recently-used eviction; implement session federation for distributed setup
+
+**Worktree Disk Usage:**
+
+- Current capacity: 10K worktrees (~20GB with typical repos)
+- Limit: `.worktrees` directory grows without cleanup; old worktrees accumulate
+- Scaling path: Add worktree TTL (delete if not used for 30 days); implement cleanup job; add quota warnings at 50/80% disk
+
+## Dependencies at Risk
+
+**node-pty Beta Version:**
+
+- Risk: `node-pty@1.1.0-beta41` used for terminal emulation; beta status indicates possible instability
+- Impact: Terminal features could break on minor platform changes; no guarantees on bug fixes
+- Migration plan: Monitor releases for stable version; pin to specific commit if needed; test extensively on target platforms (macOS, Linux, Windows)
+
+**@anthropic-ai/claude-agent-sdk 0.1.x:**
+
+- Risk: Pre-1.0 version; SDK API may change in future releases; limited version stability guarantees
+- Impact: Breaking changes could require significant refactoring; feature additions in SDK may not align with Automaker roadmap
+- Migration plan: Pin to specific 0.1.x version; review SDK changelogs before upgrades; maintain SDK compatibility tests; consider fallback implementation for critical paths
+
+**@openai/codex-sdk 0.77.x:**
+
+- Risk: Codex model deprecated by OpenAI; SDK may be archived or unsupported
+- Impact: Codex provider could become non-functional; error messages may not be actionable
+- Migration plan: Monitor OpenAI roadmap for migration path; implement fallback to Claude for Codex requests; add deprecation warning in UI
+
+**Express 5.2.x RC Stage:**
+
+- Risk: Express 5 is still in release candidate phase (as of Node 22); full stability not guaranteed
+- Impact: Minor version updates could include breaking changes; middleware compatibility issues possible
+- Migration plan: Maintain compatibility layer for Express 5 API; test with latest major before release; document any version-specific workarounds
+
+## Missing Critical Features
+
+**Persistent Session Storage:**
+
+- Problem: Agent conversation sessions stored only in-memory; restart loses all chat history
+- Blocks: Long-running analysis across server restarts; session recovery not possible
+- Impact: Users must re-run entire analysis if server restarts; lost productivity
+
+**Rate Limit Awareness:**
+
+- Problem: No tracking of API usage relative to rate limits before executing features
+- Blocks: Predictable concurrent feature execution; users frequently hit rate limits unexpectedly
+- Impact: Feature execution fails with cryptic rate limit errors; poor user experience
+
+**Feature Dependency Visualization:**
+
+- Problem: Dependency-resolver package exists but no UI to visualize or manage dependencies
+- Blocks: Users cannot plan feature order; complex dependencies not visible
+- Impact: Features implemented in wrong order; blocking dependencies missed
+
+## Test Coverage Gaps
+
+**CLI Provider Integration:**
+
+- What's not tested: Actual CLI execution paths; environment setup; error recovery from CLI crashes
+- Files: `apps/server/src/providers/cli-provider.ts`, `apps/server/src/lib/cli-detection.ts`
+- Risk: Changes to CLI handling could break silently; detection logic not validated on target platforms
+- Priority: High - affects all CLI-based providers (Cursor, Copilot, Codex)
+
+**Cursor Provider Platform-Specific Paths:**
+
+- What's not tested: Windows/Linux Cursor installation detection; version directory parsing; APPDATA environment variable handling
+- Files: `apps/server/src/providers/cursor-provider.ts` (lines 267-498)
+- Risk: Platform-specific bugs not caught; Cursor detection fails on non-standard installations
+- Priority: High - Cursor is primary provider; platform differences critical
+
+**Event Hook System State Changes:**
+
+- What's not tested: Concurrent hook execution; cleanup on server shutdown; webhook delivery retries
+- Files: `apps/server/src/services/event-hook-service.ts` (line 248 Promise.allSettled)
+- Risk: Hooks may not execute in expected order; memory not cleaned up; webhooks lost on failure
+- Priority: Medium - affects automation workflows
+
+**Error Classification for New Providers:**
+
+- What's not tested: Each provider's unique error patterns mapped to ErrorType enum; new provider errors not classified
+- Files: `apps/server/src/lib/error-handler.ts` (lines 58-80), each provider error mapping
+- Risk: User sees generic "unknown error" instead of actionable message; categorization regresses with new providers
+- Priority: Medium - impacts user experience
+
+**Feature State Corruption Scenarios:**
+
+- What's not tested: Concurrent feature updates; partial writes with power loss; JSON parsing recovery
+- Files: `apps/server/src/services/feature-loader.ts`, `@automaker/utils` (atomicWriteJson)
+- Risk: Feature data corrupted on concurrent access; recovery incomplete; no validation before use
+- Priority: High - data loss risk
+
+---
+
+_Concerns audit: 2026-01-27_

.planning/codebase/CONVENTIONS.md

@@ -0,0 +1,255 @@
+# Coding Conventions
+
+**Analysis Date:** 2026-01-27
+
+## Naming Patterns
+
+**Files:**
+
+- PascalCase for class/service files: `auto-mode-service.ts`, `feature-loader.ts`, `claude-provider.ts`
+- kebab-case for route/handler directories: `auto-mode/`, `features/`, `event-history/`
+- kebab-case for utility files: `secure-fs.ts`, `sdk-options.ts`, `settings-helpers.ts`
+- kebab-case for React components: `card.tsx`, `ansi-output.tsx`, `count-up-timer.tsx`
+- kebab-case for hooks: `use-board-background-settings.ts`, `use-responsive-kanban.ts`, `use-test-logs.ts`
+- kebab-case for store files: `app-store.ts`, `auth-store.ts`, `setup-store.ts`
+- Organized by functionality: `routes/features/routes/list.ts`, `routes/features/routes/get.ts`
+
+**Functions:**
+
+- camelCase for all function names: `createEventEmitter()`, `getAutomakerDir()`, `executeQuery()`
+- Verb-first for action functions: `buildPrompt()`, `classifyError()`, `loadContextFiles()`, `atomicWriteJson()`
+- Prefix with `use` for React hooks: `useBoardBackgroundSettings()`, `useAppStore()`, `useUpdateProjectSettings()`
+- Private methods prefixed with underscore: `_deleteOrphanedImages()`, `_migrateImages()`
+
+**Variables:**
+
+- camelCase for constants and variables: `featureId`, `projectPath`, `modelId`, `tempDir`
+- UPPER_SNAKE_CASE for global constants/enums: `DEFAULT_MAX_CONCURRENCY`, `DEFAULT_PHASE_MODELS`
+- Meaningful naming over abbreviations: `featureDirectory` not `fd`, `featureImages` not `img`
+- Prefixes for computed values: `is*` for booleans: `isClaudeModel`, `isContainerized`, `isAutoLoginEnabled`
+
+**Types:**
+
+- PascalCase for interfaces and types: `Feature`, `ExecuteOptions`, `EventEmitter`, `ProviderConfig`
+- Type files suffixed with `.d.ts`: `paths.d.ts`, `types.d.ts`
+- Organized by domain: `src/store/types/`, `src/lib/`
+- Re-export pattern from main package indexes: `export type { Feature };`
+
+## Code Style
+
+**Formatting:**
+
+- Tool: Prettier 3.7.4
+- Print width: 100 characters
+- Tab width: 2 spaces
+- Single quotes for strings
+- Semicolons required
+- Trailing commas: es5 (trailing in arrays/objects, not in params)
+- Arrow functions always include parentheses: `(x) => x * 2`
+- Line endings: LF (Unix)
+- Bracket spacing: `{ key: value }`
+
+**Linting:**
+
+- Tool: ESLint (flat config in `apps/ui/eslint.config.mjs`)
+- TypeScript ESLint plugin for `.ts`/`.tsx` files
+- Recommended configs: `@eslint/js`, `@typescript-eslint/recommended`
+- Unused variables warning with exception for parameters starting with `_`
+- Type assertions are allowed with description when using `@ts-ignore`
+- `@typescript-eslint/no-explicit-any` is warn-level (allow with caution)
+
+## Import Organization
+
+**Order:**
+
+1. Node.js standard library: `import fs from 'fs/promises'`, `import path from 'path'`
+2. Third-party packages: `import { describe, it } from 'vitest'`, `import { Router } from 'express'`
+3. Shared packages (monorepo): `import type { Feature } from '@automaker/types'`, `import { createLogger } from '@automaker/utils'`
+4. Local relative imports: `import { FeatureLoader } from './feature-loader.js'`, `import * as secureFs from '../lib/secure-fs.js'`
+5. Type imports: separated with `import type { ... } from`
+
+**Path Aliases:**
+
+- `@/` - resolves to `./src` in both UI (`apps/ui/`) and server (`apps/server/`)
+- Shared packages prefixed with `@automaker/`:
+  - `@automaker/types` - core TypeScript definitions
+  - `@automaker/utils` - logging, errors, utilities
+  - `@automaker/prompts` - AI prompt templates
+  - `@automaker/platform` - path management, security, processes
+  - `@automaker/model-resolver` - model alias resolution
+  - `@automaker/dependency-resolver` - feature dependency ordering
+  - `@automaker/git-utils` - git operations
+- Extensions: `.js` extension used in imports for ESM imports
+
+**Import Rules:**
+
+- Always import from shared packages, never from old paths
+- No circular dependencies between layers
+- Services import from providers and utilities
+- Routes import from services
+- Shared packages have strict dependency hierarchy (types → utils → platform → git-utils → server/ui)
+
+## Error Handling
+
+**Patterns:**
+
+- Use `try-catch` blocks for async operations: wraps feature execution, file operations, git commands
+- Throw `new Error(message)` with descriptive messages: `throw new Error('already running')`, `throw new Error('Feature ${featureId} not found')`
+- Classify errors with `classifyError()` from `@automaker/utils` for categorization
+- Log errors with context using `createLogger()`: includes error classification
+- Return error info objects: `{ valid: false, errors: [...], warnings: [...] }`
+- Validation returns structured result: `{ valid, errors, warnings }` from provider `validateConfig()`
+
+**Error Types:**
+
+- Authentication errors: distinguish from validation/runtime errors
+- Path validation errors: caught by middleware in Express routes
+- File system errors: logged and recovery attempted with backups
+- SDK/API errors: classified and wrapped with context
+- Abort/cancellation errors: handled without stack traces (graceful shutdown)
+
+**Error Messages:**
+
+- Descriptive and actionable: not vague error codes
+- Include context when helpful: file paths, feature IDs, model names
+- User-friendly messages via `getUserFriendlyErrorMessage()` for client display
+
+## Logging
+
+**Framework:**
+
+- Built-in `createLogger()` from `@automaker/utils`
+- Each module creates logger: `const logger = createLogger('ModuleName')`
+- Logger functions: `info()`, `warn()`, `error()`, `debug()`
+
+**Patterns:**
+
+- Log operation start and completion for significant operations
+- Log warnings for non-critical issues: file deletion failures, missing optional configs
+- Log errors with full error object: `logger.error('operation failed', error)`
+- Use module name as logger context: `createLogger('AutoMode')`, `createLogger('HttpClient')`
+- Avoid logging sensitive data (API keys, passwords)
+- No console.log in production code - use logger
+
+**What to Log:**
+
+- Feature execution start/completion
+- Error classification and recovery attempts
+- File operations (create, delete, migrate)
+- API calls and responses (in debug mode)
+- Async operation start/end
+- Warnings for deprecated patterns
+
+## Comments
+
+**When to Comment:**
+
+- Complex algorithms or business logic: explain the "why" not the "what"
+- Integration points: explain how modules communicate
+- Workarounds: explain the constraint that made the workaround necessary
+- Non-obvious performance implications
+- Edge cases and their handling
+
+**JSDoc/TSDoc:**
+
+- Used for public functions and classes
+- Document parameters with `@param`
+- Document return types with `@returns`
+- Document exceptions with `@throws`
+- Used for service classes: `/**\n * Module description\n * Manages: ...\n */`
+- Not required for simple getters/setters
+
+**Example JSDoc Pattern:**
+
+```typescript
+/**
+ * Delete images that were removed from a feature
+ */
+private async deleteOrphanedImages(
+  projectPath: string,
+  oldPaths: Array<string>,
+  newPaths: Array<string>
+): Promise<void> {
+  // Implementation
+}
+```
+
+## Function Design
+
+**Size:**
+
+- Keep functions under 100 lines when possible
+- Large services split into multiple related methods
+- Private helper methods extracted for complex logic
+
+**Parameters:**
+
+- Use destructuring for object parameters with multiple properties
+- Document parameter types with TypeScript types
+- Optional parameters marked with `?`
+- Use `Record<string, unknown>` for flexible object parameters
+
+**Return Values:**
+
+- Explicit return types required for all public functions
+- Return structured objects for multiple values
+- Use `Promise<T>` for async functions
+- Async generators use `AsyncGenerator<T>` for streaming responses
+- Never implicitly return `undefined` (explicit return or throw)
+
+## Module Design
+
+**Exports:**
+
+- Default export for class instantiation: `export default class FeatureLoader {}`
+- Named exports for functions: `export function createEventEmitter() {}`
+- Type exports separated: `export type { Feature };`
+- Barrel files (index.ts) re-export from module
+
+**Barrel Files:**
+
+- Used in routes: `routes/features/index.ts` creates router and exports
+- Used in stores: `store/index.ts` exports all store hooks
+- Pattern: group related exports for easier importing
+
+**Service Classes:**
+
+- Instantiated once and dependency injected
+- Public methods for API surface
+- Private methods prefixed with `_`
+- No static methods - prefer instances or functions
+- Constructor takes dependencies: `constructor(config?: ProviderConfig)`
+
+**Provider Pattern:**
+
+- Abstract base class: `BaseProvider` with abstract methods
+- Concrete implementations: `ClaudeProvider`, `CodexProvider`, `CursorProvider`
+- Common interface: `executeQuery()`, `detectInstallation()`, `validateConfig()`
+- Factory for instantiation: `ProviderFactory.create()`
+
+## TypeScript Specific
+
+**Strict Mode:** Always enabled globally
+
+- `strict: true` in all tsconfigs
+- No implicit `any` - declare types explicitly
+- No optional chaining on base types without narrowing
+
+**Type Definitions:**
+
+- Interface for shapes: `interface Feature { ... }`
+- Type for unions/aliases: `type ModelAlias = 'haiku' | 'sonnet' | 'opus'`
+- Type guards for narrowing: `if (typeof x === 'string') { ... }`
+- Generic types for reusable patterns: `EventCallback<T>`
+
+**React Specific (UI):**
+
+- Functional components only
+- React 19 with hooks
+- Type props interface: `interface CardProps extends React.ComponentProps<'div'> { ... }`
+- Zustand stores for state management
+- Custom hooks for shared logic
+
+---
+
+_Convention analysis: 2026-01-27_

.planning/codebase/INTEGRATIONS.md

@@ -0,0 +1,232 @@
+# External Integrations
+
+**Analysis Date:** 2026-01-27
+
+## APIs & External Services
+
+**AI/LLM Providers:**
+
+- Claude (Anthropic)
+  - SDK: `@anthropic-ai/claude-agent-sdk` (0.1.76)
+  - Auth: `ANTHROPIC_API_KEY` environment variable or stored credentials
+  - Features: Extended thinking, vision/images, tools, streaming
+  - Implementation: `apps/server/src/providers/claude-provider.ts`
+  - Models: Opus 4.5, Sonnet 4, Haiku 4.5, and legacy models
+  - Custom endpoints: `ANTHROPIC_BASE_URL` (optional)
+
+- GitHub Copilot
+  - SDK: `@github/copilot-sdk` (0.1.16)
+  - Auth: GitHub OAuth (via `gh` CLI) or `GITHUB_TOKEN` environment variable
+  - Features: Tools, streaming, runtime model discovery
+  - Implementation: `apps/server/src/providers/copilot-provider.ts`
+  - CLI detection: Searches for Copilot CLI binary
+  - Models: Dynamic discovery via `copilot models list`
+
+- OpenAI Codex/GPT-4
+  - SDK: `@openai/codex-sdk` (0.77.0)
+  - Auth: `OPENAI_API_KEY` environment variable or stored credentials
+  - Features: Extended thinking, tools, sandbox execution
+  - Implementation: `apps/server/src/providers/codex-provider.ts`
+  - Execution modes: CLI (with sandbox) or SDK (direct API)
+  - Models: Dynamic discovery via Codex CLI or SDK
+
+- Google Gemini
+  - Implementation: `apps/server/src/providers/gemini-provider.ts`
+  - Features: Vision support, tools, streaming
+
+- OpenCode (AWS/Azure/other)
+  - Implementation: `apps/server/src/providers/opencode-provider.ts`
+  - Supports: Amazon Bedrock, Azure models, local models
+  - Features: Flexible provider architecture
+
+- Cursor Editor
+  - Implementation: `apps/server/src/providers/cursor-provider.ts`
+  - Features: Integration with Cursor IDE
+
+**Model Context Protocol (MCP):**
+
+- SDK: `@modelcontextprotocol/sdk` (1.25.2)
+- Purpose: Connect AI agents to external tools and data sources
+- Implementation: `apps/server/src/services/mcp-test-service.ts`, `apps/server/src/routes/mcp/`
+- Configuration: Per-project in `.automaker/` directory
+
+## Data Storage
+
+**Databases:**
+
+- None - This codebase does NOT use traditional databases (SQL/NoSQL)
+- All data stored as files in local filesystem
+
+**File Storage:**
+
+- Local filesystem only
+- Locations:
+  - `.automaker/` - Project-specific data (features, context, settings)
+  - `./data/` or `DATA_DIR` env var - Global data (settings, credentials, sessions)
+- Secure file operations: `@automaker/platform` exports `secureFs` for restricted file access
+
+**Caching:**
+
+- In-memory caches for:
+  - Model lists (Copilot, Codex runtime discovery)
+  - Feature metadata
+  - Project specifications
+- No distributed/persistent caching system
+
+## Authentication & Identity
+
+**Auth Provider:**
+
+- Custom implementation (no third-party provider)
+- Authentication methods:
+  1. Claude Max Plan (OAuth via Anthropic CLI)
+  2. API Key mode (ANTHROPIC_API_KEY)
+  3. Custom provider profiles with API keys
+  4. Token-based session authentication for WebSocket
+
+**Implementation:**
+
+- `apps/server/src/lib/auth.ts` - Auth middleware
+- `apps/server/src/routes/auth/` - Auth routes
+- Session tokens for WebSocket connections
+- Credential storage in `./data/credentials.json` (encrypted/protected)
+
+## Monitoring & Observability
+
+**Error Tracking:**
+
+- None - No automatic error reporting service integrated
+- Custom error classification: `@automaker/utils` exports `classifyError()`
+- User-friendly error messages: `getUserFriendlyErrorMessage()`
+
+**Logs:**
+
+- Console logging with configurable levels
+- Logger: `@automaker/utils` exports `createLogger()`
+- Log levels: ERROR, WARN, INFO, DEBUG
+- Environment: `LOG_LEVEL` env var (optional)
+- Storage: Logs output to console/stdout (no persistent logging to files)
+
+**Usage Tracking:**
+
+- Claude API usage: `apps/server/src/services/claude-usage-service.ts`
+- Codex API usage: `apps/server/src/services/codex-usage-service.ts`
+- Tracks: Tokens, costs, rates
+
+## CI/CD & Deployment
+
+**Hosting:**
+
+- Local development: Node.js server + Vite dev server
+- Desktop: Electron application (macOS, Windows, Linux)
+- Web: Express server deployed to any Node.js host
+
+**CI Pipeline:**
+
+- GitHub Actions likely (`.github/workflows/` present in repo)
+- Testing: Playwright E2E, Vitest unit tests
+- Linting: ESLint
+- Formatting: Prettier
+
+**Build Process:**
+
+- `npm run build:packages` - Build shared packages
+- `npm run build` - Build web UI
+- `npm run build:electron` - Build Electron apps (platform-specific)
+- Electron Builder handles code signing and distribution
+
+## Environment Configuration
+
+**Required env vars:**
+
+- `ANTHROPIC_API_KEY` - For Claude provider (or provide in settings)
+- `OPENAI_API_KEY` - For Codex provider (optional)
+- `GITHUB_TOKEN` - For GitHub operations (optional)
+
+**Optional env vars:**
+
+- `PORT` - Server port (default 3008)
+- `HOST` - Server bind address (default 0.0.0.0)
+- `HOSTNAME` - Public hostname (default localhost)
+- `DATA_DIR` - Data storage directory (default ./data)
+- `ANTHROPIC_BASE_URL` - Custom Claude endpoint
+- `ALLOWED_ROOT_DIRECTORY` - Restrict file operations to directory
+- `AUTOMAKER_MOCK_AGENT` - Enable mock agent for testing
+- `AUTOMAKER_AUTO_LOGIN` - Skip login prompt in dev
+
+**Secrets location:**
+
+- Runtime: Environment variables (`process.env`)
+- Stored: `./data/credentials.json` (file-based)
+- Retrieval: `apps/server/src/services/settings-service.ts`
+
+## Webhooks & Callbacks
+
+**Incoming:**
+
+- WebSocket connections for real-time agent event streaming
+- GitHub webhook routes (optional): `apps/server/src/routes/github/`
+- Terminal WebSocket connections: `apps/server/src/routes/terminal/`
+
+**Outgoing:**
+
+- GitHub PRs: `apps/server/src/routes/worktree/routes/create-pr.ts`
+- Git operations: `@automaker/git-utils` handles commits, pushes
+- Terminal output streaming via WebSocket to clients
+- Event hooks: `apps/server/src/services/event-hook-service.ts`
+
+## Credential Management
+
+**API Keys Storage:**
+
+- File: `./data/credentials.json`
+- Format: JSON with nested structure for different providers
+  ```json
+  {
+    "apiKeys": {
+      "anthropic": "sk-...",
+      "openai": "sk-...",
+      "github": "ghp_..."
+    }
+  }
+  ```
+- Access: `SettingsService.getCredentials()` from `apps/server/src/services/settings-service.ts`
+- Security: File permissions should restrict to current user only
+
+**Profile/Provider Configuration:**
+
+- File: `./data/settings.json` (global) or `.automaker/settings.json` (per-project)
+- Stores: Alternative provider profiles, model mappings, sandbox settings
+- Types: `ClaudeApiProfile`, `ClaudeCompatibleProvider` from `@automaker/types`
+
+## Third-Party Service Integration Points
+
+**Git/GitHub:**
+
+- `@automaker/git-utils` - Git operations (worktrees, commits, diffs)
+- Codex/Cursor providers can create GitHub PRs
+- GitHub CLI (`gh`) detection for Copilot authentication
+
+**Terminal Access:**
+
+- `node-pty` (1.1.0-beta41) - Pseudo-terminal interface
+- `TerminalService` manages terminal sessions
+- WebSocket streaming to frontend
+
+**AI Models - Multi-Provider Abstraction:**
+
+- `BaseProvider` interface: `apps/server/src/providers/base-provider.ts`
+- Factory pattern: `apps/server/src/providers/provider-factory.ts`
+- Allows swapping providers without changing agent logic
+- All providers implement: `executeQuery()`, `detectInstallation()`, `getAvailableModels()`
+
+**Process Spawning:**
+
+- `@automaker/platform` exports `spawnProcess()`, `spawnJSONLProcess()`
+- Codex CLI execution: JSONL output parsing
+- Copilot CLI execution: Subprocess management
+- Cursor IDE interaction: Process spawning for tool execution
+
+---
+
+_Integration audit: 2026-01-27_

.planning/codebase/STACK.md

@@ -0,0 +1,230 @@
+# Technology Stack
+
+**Analysis Date:** 2026-01-27
+
+## Languages
+
+**Primary:**
+
+- TypeScript 5.9.3 - Used across all packages, apps, and configuration
+- JavaScript (Node.js) - Runtime execution for scripts and tooling
+
+**Secondary:**
+
+- YAML 2.7.0 - Configuration files
+- CSS/Tailwind CSS 4.1.18 - Frontend styling
+
+## Runtime
+
+**Environment:**
+
+- Node.js 22.x (>=22.0.0 <23.0.0) - Required version, specified in `.nvmrc`
+
+**Package Manager:**
+
+- npm - Monorepo workspace management via npm workspaces
+- Lockfile: `package-lock.json` (present)
+
+## Frameworks
+
+**Core - Frontend:**
+
+- React 19.2.3 - UI framework with hooks and concurrent features
+- Vite 7.3.0 - Build tool and dev server (`apps/ui/vite.config.ts`)
+- Electron 39.2.7 - Desktop application runtime (`apps/ui/package.json`)
+- TanStack Router 1.141.6 - File-based routing (React)
+- Zustand 5.0.9 - State management (lightweight alternative to Redux)
+- TanStack Query (React Query) 5.90.17 - Server state management
+
+**Core - Backend:**
+
+- Express 5.2.1 - HTTP server framework (`apps/server/package.json`)
+- WebSocket (ws) 8.18.3 - Real-time bidirectional communication
+- Claude Agent SDK (@anthropic-ai/claude-agent-sdk) 0.1.76 - AI provider integration
+
+**Testing:**
+
+- Playwright 1.57.0 - End-to-end testing (`apps/ui` E2E tests)
+- Vitest 4.0.16 - Unit testing framework (runs on all packages and server)
+- @vitest/ui 4.0.16 - Visual test runner UI
+- @vitest/coverage-v8 4.0.16 - Code coverage reporting
+
+**Build/Dev:**
+
+- electron-builder 26.0.12 - Electron app packaging and distribution
+- @vitejs/plugin-react 5.1.2 - Vite React support
+- vite-plugin-electron 0.29.0 - Vite plugin for Electron main process
+- vite-plugin-electron-renderer 0.14.6 - Vite plugin for Electron renderer
+- ESLint 9.39.2 - Code linting (`apps/ui`)
+- @typescript-eslint/eslint-plugin 8.50.0 - TypeScript ESLint rules
+- Prettier 3.7.4 - Code formatting (root-level config)
+- Tailwind CSS 4.1.18 - Utility-first CSS framework
+- @tailwindcss/vite 4.1.18 - Tailwind Vite integration
+
+**UI Components & Libraries:**
+
+- Radix UI - Unstyled accessible component library (@radix-ui packages)
+  - react-dropdown-menu 2.1.16
+  - react-dialog 1.1.15
+  - react-select 2.2.6
+  - react-tooltip 1.2.8
+  - react-tabs 1.1.13
+  - react-collapsible 1.1.12
+  - react-checkbox 1.3.3
+  - react-radio-group 1.3.8
+  - react-popover 1.1.15
+  - react-slider 1.3.6
+  - react-switch 1.2.6
+  - react-scroll-area 1.2.10
+  - react-label 2.1.8
+- Lucide React 0.562.0 - Icon library
+- Geist 1.5.1 - Design system UI library
+- Sonner 2.0.7 - Toast notifications
+
+**Code Editor & Terminal:**
+
+- @uiw/react-codemirror 4.25.4 - Code editor React component
+- CodeMirror (@codemirror packages) 6.x - Editor toolkit
+- xterm.js (@xterm/xterm) 5.5.0 - Terminal emulator
+- @xterm/addon-fit 0.10.0 - Fit addon for terminal
+- @xterm/addon-search 0.15.0 - Search addon for terminal
+- @xterm/addon-web-links 0.11.0 - Web links addon
+- @xterm/addon-webgl 0.18.0 - WebGL renderer for terminal
+
+**Diagram/Graph Visualization:**
+
+- @xyflow/react 12.10.0 - React flow diagram library
+- dagre 0.8.5 - Graph layout algorithms
+
+**Markdown/Content Rendering:**
+
+- react-markdown 10.1.0 - Markdown parser and renderer
+- remark-gfm 4.0.1 - GitHub Flavored Markdown support
+- rehype-raw 7.0.0 - Raw HTML support in markdown
+- rehype-sanitize 6.0.0 - HTML sanitization
+
+**Data Validation & Parsing:**
+
+- zod 3.24.1 or 4.0.0 - Schema validation and TypeScript type inference
+
+**Utilities:**
+
+- class-variance-authority 0.7.1 - CSS variant utilities
+- clsx 2.1.1 - Conditional className utility
+- cmdk 1.1.1 - Command menu/palette
+- tailwind-merge 3.4.0 - Tailwind CSS conflict resolution
+- usehooks-ts 3.1.1 - TypeScript React hooks
+- @dnd-kit (drag-and-drop) 6.3.1 - Drag and drop library
+
+**Font Libraries:**
+
+- @fontsource - Web font packages (Cascadia Code, Fira Code, IBM Plex, Inconsolata, Inter, etc.)
+
+**Development Utilities:**
+
+- cross-spawn 7.0.6 - Cross-platform process spawning
+- dotenv 17.2.3 - Environment variable loading
+- tsx 4.21.0 - TypeScript execution for Node.js
+- tree-kill 1.2.2 - Process tree killer utility
+- node-pty 1.1.0-beta41 - PTY/terminal interface for Node.js
+
+## Key Dependencies
+
+**Critical - AI/Agent Integration:**
+
+- @anthropic-ai/claude-agent-sdk 0.1.76 - Core Claude AI provider
+- @github/copilot-sdk 0.1.16 - GitHub Copilot integration
+- @openai/codex-sdk 0.77.0 - OpenAI Codex/GPT-4 integration
+- @modelcontextprotocol/sdk 1.25.2 - Model Context Protocol servers
+
+**Infrastructure - Internal Packages:**
+
+- @automaker/types 1.0.0 - Shared TypeScript type definitions
+- @automaker/utils 1.0.0 - Logging, error handling, utilities
+- @automaker/platform 1.0.0 - Path management, security, process spawning
+- @automaker/prompts 1.0.0 - AI prompt templates
+- @automaker/model-resolver 1.0.0 - Claude model alias resolution
+- @automaker/dependency-resolver 1.0.0 - Feature dependency ordering
+- @automaker/git-utils 1.0.0 - Git operations & worktree management
+- @automaker/spec-parser 1.0.0 - Project specification parsing
+
+**Server Utilities:**
+
+- express 5.2.1 - Web framework
+- cors 2.8.5 - CORS middleware
+- morgan 1.10.1 - HTTP request logger
+- cookie-parser 1.4.7 - Cookie parsing middleware
+- yaml 2.7.0 - YAML parsing and generation
+
+**Type Definitions:**
+
+- @types/express 5.0.6
+- @types/node 22.19.3
+- @types/react 19.2.7
+- @types/react-dom 19.2.3
+- @types/dagre 0.7.53
+- @types/ws 8.18.1
+- @types/cookie 0.6.0
+- @types/cookie-parser 1.4.10
+- @types/cors 2.8.19
+- @types/morgan 1.9.10
+
+**Optional Dependencies (Platform-specific):**
+
+- lightningcss (various platforms) 1.29.2 - CSS parser (alternate to PostCSS)
+- dmg-license 1.0.11 - DMG license dialog for macOS
+
+## Configuration
+
+**Environment:**
+
+- `.env` and `.env.example` files in `apps/server/` and `apps/ui/`
+- `dotenv` library loads variables from `.env` files
+- Key env vars:
+  - `ANTHROPIC_API_KEY` - Claude API authentication
+  - `OPENAI_API_KEY` - OpenAI/Codex authentication
+  - `GITHUB_TOKEN` - GitHub API access
+  - `ANTHROPIC_BASE_URL` - Custom Claude endpoint (optional)
+  - `HOST` - Server bind address (default: 0.0.0.0)
+  - `HOSTNAME` - Hostname for URLs (default: localhost)
+  - `PORT` - Server port (default: 3008)
+  - `DATA_DIR` - Data storage directory (default: ./data)
+  - `ALLOWED_ROOT_DIRECTORY` - Restrict file operations
+  - `AUTOMAKER_MOCK_AGENT` - Enable mock agent for testing
+  - `AUTOMAKER_AUTO_LOGIN` - Skip login in dev (disabled in production)
+  - `VITE_HOSTNAME` - Frontend API hostname
+
+**Build:**
+
+- `apps/ui/electron-builder.config.json` or `apps/ui/package.json` build config
+- Electron builder targets:
+  - macOS: DMG and ZIP
+  - Windows: NSIS installer
+  - Linux: AppImage, DEB, RPM
+- Vite config: `apps/ui/vite.config.ts`, `apps/server/tsconfig.json`
+- TypeScript config: `tsconfig.json` files in each package
+
+## Platform Requirements
+
+**Development:**
+
+- Node.js 22.x
+- npm (included with Node.js)
+- Git (for worktree operations)
+- Python (optional, for some dev scripts)
+
+**Production:**
+
+- Electron desktop app: Windows, macOS, Linux
+- Web browser: Modern Chromium-based browsers
+- Server: Any platform supporting Node.js 22.x
+
+**Deployment Target:**
+
+- Local desktop (Electron)
+- Local web server (Express + Vite)
+- Remote server deployment (Docker, systemd, or other orchestration)
+
+---
+
+_Stack analysis: 2026-01-27_

.planning/codebase/STRUCTURE.md

@@ -0,0 +1,340 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-01-27
+
+## Directory Layout
+
+```
+automaker/
+├── apps/                        # Application packages
+│   ├── ui/                      # React + Electron frontend (port 3007)
+│   │   ├── src/
+│   │   │   ├── main.ts          # Electron/Vite entry point
+│   │   │   ├── app.tsx          # Root React component (splash, router)
+│   │   │   ├── renderer.tsx     # Electron renderer entry
+│   │   │   ├── routes/          # TanStack Router file-based routes
+│   │   │   ├── components/      # React components (views, dialogs, UI, layout)
+│   │   │   ├── store/           # Zustand state management
+│   │   │   ├── hooks/           # Custom React hooks
+│   │   │   ├── lib/             # Utilities (API client, electron, queries, etc.)
+│   │   │   ├── electron/        # Electron main & preload process files
+│   │   │   ├── config/          # UI configuration (fonts, themes, routes)
+│   │   │   └── styles/          # CSS and theme files
+│   │   ├── public/              # Static assets
+│   │   └── tests/               # E2E Playwright tests
+│   │
+│   └── server/                  # Express backend (port 3008)
+│       ├── src/
+│       │   ├── index.ts         # Express app initialization, route mounting
+│       │   ├── routes/          # REST API endpoints (30+ route folders)
+│       │   ├── services/        # Business logic services
+│       │   ├── providers/       # AI model provider implementations
+│       │   ├── lib/             # Utilities (events, auth, helpers, etc.)
+│       │   ├── middleware/      # Express middleware
+│       │   └── types/           # Server-specific type definitions
+│       └── tests/               # Unit tests (Vitest)
+│
+├── libs/                        # Shared npm packages (@automaker/*)
+│   ├── types/                   # @automaker/types (no dependencies)
+│   │   └── src/
+│   │       ├── index.ts         # Main export with all type definitions
+│   │       ├── feature.ts       # Feature, FeatureStatus, etc.
+│   │       ├── provider.ts      # Provider interfaces, model definitions
+│   │       ├── settings.ts      # Global and project settings types
+│   │       ├── event.ts         # Event types for real-time updates
+│   │       ├── session.ts       # AgentSession, conversation types
+│   │       ├── model*.ts        # Model-specific types (cursor, codex, gemini, etc.)
+│   │       └── ... 20+ more type files
+│   │
+│   ├── utils/                   # @automaker/utils (logging, errors, images, context)
+│   │   └── src/
+│   │       ├── logger.ts        # createLogger() with LogLevel enum
+│   │       ├── errors.ts        # classifyError(), error types
+│   │       ├── image-utils.ts   # Image processing, base64 encoding
+│   │       ├── context-loader.ts # loadContextFiles() for AI prompts
+│   │       └── ... more utilities
+│   │
+│   ├── platform/                # @automaker/platform (paths, security, OS)
+│   │   └── src/
+│   │       ├── index.ts         # Path getters (getFeatureDir, getFeaturesDir, etc.)
+│   │       ├── secure-fs.ts     # Secure filesystem operations
+│   │       └── config/          # Claude auth detection, allowed paths
+│   │
+│   ├── prompts/                 # @automaker/prompts (AI prompt templates)
+│   │   └── src/
+│   │       ├── index.ts         # Main prompts export
+│   │       └── *-prompt.ts      # Prompt templates for different features
+│   │
+│   ├── model-resolver/          # @automaker/model-resolver
+│   │   └── src/
+│   │       └── index.ts         # resolveModelString() for model aliases
+│   │
+│   ├── dependency-resolver/     # @automaker/dependency-resolver
+│   │   └── src/
+│   │       └── index.ts         # Resolve feature dependencies
+│   │
+│   ├── git-utils/               # @automaker/git-utils (git operations)
+│   │   └── src/
+│   │       ├── index.ts         # getGitRepositoryDiffs(), worktree management
+│   │       └── ... git helpers
+│   │
+│   ├── spec-parser/             # @automaker/spec-parser
+│   │   └── src/
+│   │       └── ... spec parsing utilities
+│   │
+│   └── tsconfig.base.json       # Base TypeScript config for all packages
+│
+├── .automaker/                  # Project data directory (created by app)
+│   ├── features/                # Feature storage
+│   │   └── {featureId}/
+│   │       ├── feature.json     # Feature metadata and content
+│   │       ├── agent-output.md  # Agent execution results
+│   │       └── images/          # Feature images
+│   ├── context/                 # Context files (CLAUDE.md, etc.)
+│   ├── settings.json            # Per-project settings
+│   ├── spec.md                  # Project specification
+│   └── analysis.json            # Project structure analysis
+│
+├── data/                        # Global data directory (default, configurable)
+│   ├── settings.json            # Global settings, profiles
+│   ├── credentials.json         # Encrypted API keys
+│   ├── sessions-metadata.json   # Chat session metadata
+│   └── agent-sessions/          # Conversation histories
+│
+├── .planning/                   # Generated documentation by GSD orchestrator
+│   └── codebase/               # Codebase analysis documents
+│       ├── ARCHITECTURE.md     # Architecture patterns and layers
+│       ├── STRUCTURE.md        # This file
+│       ├── STACK.md            # Technology stack
+│       ├── INTEGRATIONS.md     # External API integrations
+│       ├── CONVENTIONS.md      # Code style and naming
+│       ├── TESTING.md          # Testing patterns
+│       └── CONCERNS.md         # Technical debt and issues
+│
+├── .github/                     # GitHub Actions workflows
+├── scripts/                     # Build and utility scripts
+├── tests/                       # Test data and utilities
+├── docs/                        # Documentation
+├── package.json                 # Root workspace config
+├── package-lock.json            # Lock file
+├── CLAUDE.md                    # Project instructions for Claude Code
+├── DEVELOPMENT_WORKFLOW.md      # Development guidelines
+└── README.md                    # Project overview
+```
+
+## Directory Purposes
+
+**apps/ui/:**
+
+- Purpose: React frontend for desktop (Electron) and web modes
+- Build system: Vite 7 with TypeScript
+- Styling: Tailwind CSS 4
+- State: Zustand 5 with API persistence
+- Routing: TanStack Router with file-based structure
+- Desktop: Electron 39 with preload IPC bridge
+
+**apps/server/:**
+
+- Purpose: Express backend API and service layer
+- Build system: TypeScript → JavaScript
+- Runtime: Node.js 18+
+- WebSocket: ws library for real-time streaming
+- Process management: node-pty for terminal isolation
+
+**libs/types/:**
+
+- Purpose: Central type definitions (no dependencies, fast import)
+- Used by: All other packages and apps
+- Pattern: Single namespace export from index.ts
+- Build: Compiled to ESM only
+
+**libs/utils/:**
+
+- Purpose: Shared utilities for logging, errors, file operations, image processing
+- Used by: Server, UI, other libraries
+- Notable: `createLogger()`, `classifyError()`, `loadContextFiles()`, `readImageAsBase64()`
+
+**libs/platform/:**
+
+- Purpose: OS-agnostic path management and security enforcement
+- Used by: Server services for file operations
+- Notable: Path normalization, allowed directory enforcement, Claude auth detection
+
+**libs/prompts/:**
+
+- Purpose: AI prompt templates injected into agent context
+- Used by: AgentService when executing features
+- Pattern: Function exports that return prompt strings
+
+## Key File Locations
+
+**Entry Points:**
+
+**Server:**
+
+- `apps/server/src/index.ts`: Express server initialization, route mounting, WebSocket setup
+
+**UI (Web):**
+
+- `apps/ui/src/main.ts`: Vite entry point
+- `apps/ui/src/app.tsx`: Root React component
+
+**UI (Electron):**
+
+- `apps/ui/src/main.ts`: Vite entry point
+- `apps/ui/src/electron/main-process.ts`: Electron main process
+- `apps/ui/src/preload.ts`: Electron preload script for IPC bridge
+
+**Configuration:**
+
+- `apps/server/src/index.ts`: PORT, HOST, HOSTNAME, DATA_DIR env vars
+- `apps/ui/src/config/`: Theme options, fonts, model aliases
+- `libs/types/src/settings.ts`: Settings schema
+- `.env.local`: Local development overrides (git-ignored)
+
+**Core Logic:**
+
+**Server:**
+
+- `apps/server/src/services/agent-service.ts`: AI agent execution engine (31KB)
+- `apps/server/src/services/auto-mode-service.ts`: Feature batching and automation (216KB - largest)
+- `apps/server/src/services/feature-loader.ts`: Feature persistence and loading
+- `apps/server/src/services/settings-service.ts`: Settings management
+- `apps/server/src/providers/provider-factory.ts`: AI provider selection
+
+**UI:**
+
+- `apps/ui/src/store/app-store.ts`: Global state (84KB - largest frontend file)
+- `apps/ui/src/lib/http-api-client.ts`: API client with auth (92KB)
+- `apps/ui/src/components/views/board-view.tsx`: Kanban board (70KB)
+- `apps/ui/src/routes/__root.tsx`: Root layout with session init (32KB)
+
+**Testing:**
+
+**E2E Tests:**
+
+- `apps/ui/tests/`: Playwright tests organized by feature area
+  - `settings/`, `features/`, `projects/`, `agent/`, `utils/`, `context/`
+
+**Unit Tests:**
+
+- `libs/*/tests/`: Package-specific Vitest tests
+- `apps/server/src/tests/`: Server integration tests
+
+**Test Config:**
+
+- `vitest.config.ts`: Root Vitest configuration
+- `apps/ui/playwright.config.ts`: Playwright configuration
+
+## Naming Conventions
+
+**Files:**
+
+- **Components:** PascalCase.tsx (e.g., `board-view.tsx`, `session-manager.tsx`)
+- **Services:** camelCase-service.ts (e.g., `agent-service.ts`, `settings-service.ts`)
+- **Hooks:** use-kebab-case.ts (e.g., `use-auto-mode.ts`, `use-settings-sync.ts`)
+- **Utilities:** camelCase.ts (e.g., `api-fetch.ts`, `log-parser.ts`)
+- **Routes:** kebab-case with index.ts pattern (e.g., `routes/agent/index.ts`)
+- **Tests:** _.test.ts or _.spec.ts (co-located with source)
+
+**Directories:**
+
+- **Feature domains:** kebab-case (e.g., `auto-mode/`, `event-history/`, `project-settings-view/`)
+- **Type categories:** kebab-case plural (e.g., `types/`, `services/`, `providers/`, `routes/`)
+- **Shared utilities:** kebab-case (e.g., `lib/`, `utils/`, `hooks/`)
+
+**TypeScript:**
+
+- **Types:** PascalCase (e.g., `Feature`, `AgentSession`, `ProviderMessage`)
+- **Interfaces:** PascalCase (e.g., `EventEmitter`, `ProviderFactory`)
+- **Enums:** PascalCase (e.g., `LogLevel`, `FeatureStatus`)
+- **Functions:** camelCase (e.g., `createLogger()`, `classifyError()`)
+- **Constants:** UPPER_SNAKE_CASE (e.g., `DEFAULT_TIMEOUT_MS`, `MAX_RETRIES`)
+- **Variables:** camelCase (e.g., `featureId`, `settingsService`)
+
+## Where to Add New Code
+
+**New Feature (end-to-end):**
+
+- API Route: `apps/server/src/routes/{feature-name}/index.ts`
+- Service Logic: `apps/server/src/services/{feature-name}-service.ts`
+- UI Route: `apps/ui/src/routes/{feature-name}.tsx` (simple) or `{feature-name}/` (complex with subdir)
+- Store: `apps/ui/src/store/{feature-name}-store.ts` (if complex state)
+- Tests: `apps/ui/tests/{feature-name}/` or `apps/server/src/tests/`
+
+**New Component/Module:**
+
+- View Components: `apps/ui/src/components/views/{component-name}/`
+- Dialog Components: `apps/ui/src/components/dialogs/{dialog-name}.tsx`
+- Shared Components: `apps/ui/src/components/shared/` or `components/ui/` (shadcn)
+- Layout Components: `apps/ui/src/components/layout/`
+
+**Utilities:**
+
+- New Library: Create in `libs/{package-name}/` with package.json and tsconfig.json
+- Server Utilities: `apps/server/src/lib/{utility-name}.ts`
+- Shared Utilities: Extend `libs/utils/src/` or create new lib if self-contained
+- UI Utilities: `apps/ui/src/lib/{utility-name}.ts`
+
+**New Provider (AI Model):**
+
+- Implementation: `apps/server/src/providers/{provider-name}-provider.ts`
+- Types: Add to `libs/types/src/{provider-name}-models.ts`
+- Model Resolver: Update `libs/model-resolver/src/index.ts` with model alias mapping
+- Settings: Update `libs/types/src/settings.ts` for provider-specific config
+
+## Special Directories
+
+**apps/ui/electron/:**
+
+- Purpose: Electron-specific code (main process, IPC handlers, native APIs)
+- Generated: Yes (preload.ts)
+- Committed: Yes
+
+**apps/ui/public/**
+
+- Purpose: Static assets (sounds, images, icons)
+- Generated: No
+- Committed: Yes
+
+**apps/ui/dist/:**
+
+- Purpose: Built web application
+- Generated: Yes
+- Committed: No (.gitignore)
+
+**apps/ui/dist-electron/:**
+
+- Purpose: Built Electron app bundle
+- Generated: Yes
+- Committed: No (.gitignore)
+
+**.automaker/features/{featureId}/:**
+
+- Purpose: Per-feature persistent storage
+- Structure: feature.json, agent-output.md, images/
+- Generated: Yes (at runtime)
+- Committed: Yes (tracked in project git)
+
+**data/:**
+
+- Purpose: Global data directory (global settings, credentials, sessions)
+- Generated: Yes (created at first run)
+- Committed: No (.gitignore)
+- Configurable: Via DATA_DIR env var
+
+**node_modules/:**
+
+- Purpose: Installed dependencies
+- Generated: Yes
+- Committed: No (.gitignore)
+
+**dist/**, **build/:**
+
+- Purpose: Build artifacts
+- Generated: Yes
+- Committed: No (.gitignore)
+
+---
+
+_Structure analysis: 2026-01-27_

.planning/codebase/TESTING.md

@@ -0,0 +1,389 @@
+# Testing Patterns
+
+**Analysis Date:** 2026-01-27
+
+## Test Framework
+
+**Runner:**
+
+- Vitest 4.0.16 (for unit and integration tests)
+- Playwright (for E2E tests)
+- Config: `apps/server/vitest.config.ts`, `libs/*/vitest.config.ts`, `apps/ui/playwright.config.ts`
+
+**Assertion Library:**
+
+- Vitest built-in expect assertions
+- API: `expect().toBe()`, `expect().toEqual()`, `expect().toHaveLength()`, `expect().toHaveProperty()`
+
+**Run Commands:**
+
+```bash
+npm run test                    # E2E tests (Playwright, headless)
+npm run test:headed            # E2E tests with browser visible
+npm run test:packages          # All shared package unit tests (vitest)
+npm run test:server            # Server unit tests (vitest run)
+npm run test:server:coverage   # Server tests with coverage report
+npm run test:all               # All tests (packages + server)
+npm run test:unit              # Vitest run (all projects)
+npm run test:unit:watch        # Vitest watch mode
+```
+
+## Test File Organization
+
+**Location:**
+
+- Co-located with source: `src/module.ts` has `tests/unit/module.test.ts`
+- Server tests: `apps/server/tests/` (separate directory)
+- Library tests: `libs/*/tests/` (each package)
+- E2E tests: `apps/ui/tests/` (Playwright)
+
+**Naming:**
+
+- Pattern: `{moduleName}.test.ts` for unit tests
+- Pattern: `{moduleName}.spec.ts` for specification tests
+- Glob pattern: `tests/**/*.test.ts`, `tests/**/*.spec.ts`
+
+**Structure:**
+
+```
+apps/server/
+├── tests/
+│   ├── setup.ts              # Global test setup
+│   ├── unit/
+│   │   ├── providers/        # Provider tests
+│   │   │   ├── claude-provider.test.ts
+│   │   │   ├── codex-provider.test.ts
+│   │   │   └── base-provider.test.ts
+│   │   └── services/
+│   └── utils/
+│       └── helpers.ts        # Test utilities
+└── src/
+
+libs/platform/
+├── tests/
+│   ├── paths.test.ts
+│   ├── security.test.ts
+│   ├── subprocess.test.ts
+│   └── node-finder.test.ts
+└── src/
+```
+
+## Test Structure
+
+**Suite Organization:**
+
+```typescript
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { FeatureLoader } from '@/services/feature-loader.js';
+
+describe('feature-loader.ts', () => {
+  let featureLoader: FeatureLoader;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    featureLoader = new FeatureLoader();
+  });
+
+  afterEach(async () => {
+    // Cleanup resources
+  });
+
+  describe('methodName', () => {
+    it('should do specific thing', () => {
+      expect(result).toBe(expected);
+    });
+  });
+});
+```
+
+**Patterns:**
+
+- Setup pattern: `beforeEach()` initializes test instance, clears mocks
+- Teardown pattern: `afterEach()` cleans up temp directories, removes created files
+- Assertion pattern: one logical assertion per test (or multiple closely related)
+- Test isolation: each test runs with fresh setup
+
+## Mocking
+
+**Framework:**
+
+- Vitest `vi` module: `vi.mock()`, `vi.mocked()`, `vi.clearAllMocks()`
+- Mock patterns: module mocking, function spying, return value mocking
+
+**Patterns:**
+
+Module mocking:
+
+```typescript
+vi.mock('@anthropic-ai/claude-agent-sdk');
+// In test:
+vi.mocked(sdk.query).mockReturnValue(
+  (async function* () {
+    yield { type: 'text', text: 'Response 1' };
+  })()
+);
+```
+
+Async generator mocking (for streaming APIs):
+
+```typescript
+const generator = provider.executeQuery({
+  prompt: 'Hello',
+  model: 'claude-opus-4-5-20251101',
+  cwd: '/test',
+});
+const results = await collectAsyncGenerator(generator);
+```
+
+Partial mocking with spies:
+
+```typescript
+const provider = new TestProvider();
+const spy = vi.spyOn(provider, 'getName');
+spy.mockReturnValue('mocked-name');
+```
+
+**What to Mock:**
+
+- External APIs (Claude SDK, GitHub SDK, cloud services)
+- File system operations (use temp directories instead when possible)
+- Network calls
+- Process execution
+- Time-dependent operations
+
+**What NOT to Mock:**
+
+- Core business logic (test the actual implementation)
+- Type definitions
+- Internal module dependencies (test integration with real services)
+- Standard library functions (fs, path, etc. - use fixtures instead)
+
+## Fixtures and Factories
+
+**Test Data:**
+
+```typescript
+// Test helper for collecting async generator results
+async function collectAsyncGenerator<T>(generator: AsyncGenerator<T>): Promise<T[]> {
+  const results: T[] = [];
+  for await (const item of generator) {
+    results.push(item);
+  }
+  return results;
+}
+
+// Temporary directory fixture
+beforeEach(async () => {
+  tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'test-'));
+  projectPath = path.join(tempDir, 'test-project');
+  await fs.mkdir(projectPath, { recursive: true });
+});
+
+afterEach(async () => {
+  try {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  } catch (error) {
+    // Ignore cleanup errors
+  }
+});
+```
+
+**Location:**
+
+- Inline in test files for simple fixtures
+- `tests/utils/helpers.ts` for shared test utilities
+- Factory functions for complex test objects: `createTestProvider()`, `createMockFeature()`
+
+## Coverage
+
+**Requirements (Server):**
+
+- Lines: 60%
+- Functions: 75%
+- Branches: 55%
+- Statements: 60%
+- Config: `apps/server/vitest.config.ts` with thresholds
+
+**Excluded from Coverage:**
+
+- Route handlers: tested via integration/E2E tests
+- Type re-exports
+- Middleware: tested via integration tests
+- Prompt templates
+- MCP integration: awaits MCP SDK integration tests
+- Provider CLI integrations: awaits integration tests
+
+**View Coverage:**
+
+```bash
+npm run test:server:coverage   # Generate coverage report
+# Opens HTML report in: apps/server/coverage/index.html
+```
+
+**Coverage Tools:**
+
+- Provider: v8
+- Reporters: text, json, html, lcov
+- File inclusion: `src/**/*.ts`
+- File exclusion: `src/**/*.d.ts`, specific service files in thresholds
+
+## Test Types
+
+**Unit Tests:**
+
+- Scope: Individual functions and methods
+- Approach: Test inputs → outputs with mocked dependencies
+- Location: `apps/server/tests/unit/`
+- Examples:
+  - Provider executeQuery() with mocked SDK
+  - Path construction functions with assertions
+  - Error classification with different error types
+  - Config validation with various inputs
+
+**Integration Tests:**
+
+- Scope: Multiple modules working together
+- Approach: Test actual service calls with real file system or temp directories
+- Pattern: Setup data → call method → verify results
+- Example: Feature loader reading/writing feature.json files
+- Example: Auto-mode service coordinating with multiple services
+
+**E2E Tests:**
+
+- Framework: Playwright
+- Scope: Full user workflows from UI
+- Location: `apps/ui/tests/`
+- Config: `apps/ui/playwright.config.ts`
+- Setup:
+  - Backend server with mock agent enabled
+  - Frontend Vite dev server
+  - Sequential execution (workers: 1) to avoid auth conflicts
+  - Screenshots/traces on failure
+- Auth: Global setup authentication in `tests/global-setup.ts`
+- Fixtures: `tests/e2e-fixtures/` for test project data
+
+## Common Patterns
+
+**Async Testing:**
+
+```typescript
+it('should execute async operation', async () => {
+  const result = await featureLoader.loadFeature(projectPath, featureId);
+  expect(result).toBeDefined();
+  expect(result.id).toBe(featureId);
+});
+
+// For streams/generators:
+const generator = provider.executeQuery({ prompt, model, cwd });
+const results = await collectAsyncGenerator(generator);
+expect(results).toHaveLength(2);
+```
+
+**Error Testing:**
+
+```typescript
+it('should throw error when feature not found', async () => {
+  await expect(featureLoader.getFeature(projectPath, 'nonexistent')).rejects.toThrow('not found');
+});
+
+// Testing error classification:
+const errorInfo = classifyError(new Error('ENOENT'));
+expect(errorInfo.category).toBe('FileSystem');
+```
+
+**Fixture Setup:**
+
+```typescript
+it('should create feature with images', async () => {
+  // Setup: create temp feature directory
+  const featureDir = path.join(projectPath, '.automaker', 'features', featureId);
+  await fs.mkdir(featureDir, { recursive: true });
+
+  // Act: perform operation
+  const result = await featureLoader.updateFeature(projectPath, {
+    id: featureId,
+    imagePaths: ['/temp/image.png'],
+  });
+
+  // Assert: verify file operations
+  const migratedPath = path.join(featureDir, 'images', 'image.png');
+  expect(fs.existsSync(migratedPath)).toBe(true);
+});
+```
+
+**Mock Reset Pattern:**
+
+```typescript
+// In vitest.config.ts:
+mockReset: true,          // Reset all mocks before each test
+restoreMocks: true,       // Restore original implementations
+clearMocks: true,         // Clear mock call history
+
+// In test:
+beforeEach(() => {
+  vi.clearAllMocks();
+  delete process.env.ANTHROPIC_API_KEY;
+});
+```
+
+## Test Configuration
+
+**Vitest Config Patterns:**
+
+Server config (`apps/server/vitest.config.ts`):
+
+- Environment: node
+- Globals: true (describe/it without imports)
+- Setup files: `./tests/setup.ts`
+- Alias resolution: resolves `@automaker/*` to source files for mocking
+
+Library config:
+
+- Simpler setup: just environment and globals
+- Coverage with high thresholds (90%+ lines)
+
+**Global Setup:**
+
+```typescript
+// tests/setup.ts
+import { vi, beforeEach } from 'vitest';
+
+process.env.NODE_ENV = 'test';
+process.env.DATA_DIR = '/tmp/test-data';
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+```
+
+## Testing Best Practices
+
+**Isolation:**
+
+- Each test is independent (no state sharing)
+- Cleanup temp files in afterEach
+- Reset mocks and environment variables in beforeEach
+
+**Clarity:**
+
+- Descriptive test names: "should do X when Y condition"
+- One logical assertion per test
+- Clear arrange-act-assert structure
+
+**Speed:**
+
+- Mock external services
+- Use in-memory temp directories
+- Avoid real network calls
+- Sequential E2E tests to prevent conflicts
+
+**Maintainability:**
+
+- Use beforeEach/afterEach for common setup
+- Extract test helpers to `tests/utils/`
+- Keep test data simple and local
+- Mock consistently across tests
+
+---
+
+_Testing analysis: 2026-01-27_

CLAUDE.md

@@ -161,7 +161,7 @@ Use `resolveModelString()` from `@automaker/model-resolver` to convert model ali
 
 - `haiku` → `claude-haiku-4-5`
 - `sonnet` → `claude-sonnet-4-20250514`
-- `opus` → `claude-opus-4-5-20251101`
+- `opus` → `claude-opus-4-6`
 
 ## Environment Variables
 

DEVELOPMENT_WORKFLOW.md

@@ -1,253 +0,0 @@
-# Development Workflow
-
-This document defines the standard workflow for keeping a branch in sync with the upstream
-release candidate (RC) and for shipping feature work. It is paired with `check-sync.sh`.
-
-## Quick Decision Rule
-
-1. Ask the user to select a workflow:
-   - **Sync Workflow** → you are maintaining the current RC branch with fixes/improvements
-     and will push the same fixes to both origin and upstream RC when you have local
-     commits to publish.
-   - **PR Workflow** → you are starting new feature work on a new branch; upstream updates
-     happen via PR only.
-2. After the user selects, run:
-   ```bash
-   ./check-sync.sh
-   ```
-3. Use the status output to confirm alignment. If it reports **diverged**, default to
-   merging `upstream/<TARGET_RC>` into the current branch and preserving local commits.
-   For Sync Workflow, when the working tree is clean and you are behind upstream RC,
-   proceed with the fetch + merge without asking for additional confirmation.
-
-## Target RC Resolution
-
-The target RC is resolved dynamically so the workflow stays current as the RC changes.
-
-Resolution order:
-
-1. Latest `upstream/v*rc` branch (auto-detected)
-2. `upstream/HEAD` (fallback)
-3. If neither is available, you must pass `--rc <branch>`
-
-Override for a single run:
-
-```bash
-./check-sync.sh --rc <rc-branch>
-```
-
-## Pre-Flight Checklist
-
-1. Confirm a clean working tree:
-   ```bash
-   git status
-   ```
-2. Confirm the current branch:
-   ```bash
-   git branch --show-current
-   ```
-3. Ensure remotes exist (origin + upstream):
-   ```bash
-   git remote -v
-   ```
-
-## Sync Workflow (Upstream Sync)
-
-Use this flow when you are updating the current branch with fixes or improvements and
-intend to keep origin and upstream RC in lockstep.
-
-1. **Check sync status**
-   ```bash
-   ./check-sync.sh
-   ```
-2. **Update from upstream RC before editing (no pulls)**
-   - **Behind upstream RC** → fetch and merge RC into your branch:
-     ```bash
-     git fetch upstream
-     git merge upstream/<TARGET_RC> --no-edit
-     ```
-     When the working tree is clean and the user selected Sync Workflow, proceed without
-     an extra confirmation prompt.
-   - **Diverged** → stop and resolve manually.
-3. **Resolve conflicts if needed**
-   - Handle conflicts intelligently: preserve upstream behavior and your local intent.
-4. **Make changes and commit (if you are delivering fixes)**
-   ```bash
-   git add -A
-   git commit -m "type: description"
-   ```
-5. **Build to verify**
-   ```bash
-   npm run build:packages
-   npm run build
-   ```
-6. **Push after a successful merge to keep remotes aligned**
-   - If you only merged upstream RC changes, push **origin only** to sync your fork:
-     ```bash
-     git push origin <branch>
-     ```
-   - If you have local fixes to publish, push **origin + upstream**:
-     ```bash
-     git push origin <branch>
-     git push upstream <branch>:<TARGET_RC>
-     ```
-   - Always ask the user which push to perform.
-   - Origin (origin-only sync):
-     ```bash
-     git push origin <branch>
-     ```
-   - Upstream RC (publish the same fixes when you have local commits):
-     ```bash
-     git push upstream <branch>:<TARGET_RC>
-     ```
-7. **Re-check sync**
-   ```bash
-   ./check-sync.sh
-   ```
-
-## PR Workflow (Feature Work)
-
-Use this flow only for new feature work on a new branch. Do not push to upstream RC.
-
-1. **Create or switch to a feature branch**
-   ```bash
-   git checkout -b <branch>
-   ```
-2. **Make changes and commit**
-   ```bash
-   git add -A
-   git commit -m "type: description"
-   ```
-3. **Merge upstream RC before shipping**
-   ```bash
-   git merge upstream/<TARGET_RC> --no-edit
-   ```
-4. **Build and/or test**
-   ```bash
-   npm run build:packages
-   npm run build
-   ```
-5. **Push to origin**
-   ```bash
-   git push -u origin <branch>
-   ```
-6. **Create or update the PR**
-   - Use `gh pr create` or the GitHub UI.
-7. **Review and follow-up**
-
-- Apply feedback, commit changes, and push again.
-- Re-run `./check-sync.sh` if additional upstream sync is needed.
-
-## Conflict Resolution Checklist
-
-1. Identify which changes are from upstream vs. local.
-2. Preserve both behaviors where possible; avoid dropping either side.
-3. Prefer minimal, safe integrations over refactors.
-4. Re-run build commands after resolving conflicts.
-5. Re-run `./check-sync.sh` to confirm status.
-
-## Build/Test Matrix
-
-- **Sync Workflow**: `npm run build:packages` and `npm run build`.
-- **PR Workflow**: `npm run build:packages` and `npm run build` (plus relevant tests).
-
-## Post-Sync Verification
-
-1. `git status` should be clean.
-2. `./check-sync.sh` should show expected alignment.
-3. Verify recent commits with:
-   ```bash
-   git log --oneline -5
-   ```
-
-## check-sync.sh Usage
-
-- Uses dynamic Target RC resolution (see above).
-- Override target RC:
-  ```bash
-  ./check-sync.sh --rc <rc-branch>
-  ```
-- Optional preview limit:
-  ```bash
-  ./check-sync.sh --preview 10
-  ```
-- The script prints sync status for both origin and upstream and previews recent commits
-  when you are behind.
-
-## Stop Conditions
-
-Stop and ask for guidance if any of the following are true:
-
-- The working tree is dirty and you are about to merge or push.
-- `./check-sync.sh` reports **diverged** during PR Workflow, or a merge cannot be completed.
-- The script cannot resolve a target RC and requests `--rc`.
-- A build fails after sync or conflict resolution.
-
-## AI Agent Guardrails
-
-- Always run `./check-sync.sh` before merges or pushes.
-- Always ask for explicit user approval before any push command.
-- Do not ask for additional confirmation before a Sync Workflow fetch + merge when the
-  working tree is clean and the user has already selected the Sync Workflow.
-- Choose Sync vs PR workflow based on intent (RC maintenance vs new feature work), not
-  on the script's workflow hint.
-- Only use force push when the user explicitly requests a history rewrite.
-- Ask for explicit approval before dependency installs, branch deletion, or destructive operations.
-- When resolving merge conflicts, preserve both upstream changes and local intent where possible.
-- Do not create or switch to new branches unless the user explicitly requests it.
-
-## AI Agent Decision Guidance
-
-Agents should provide concrete, task-specific suggestions instead of repeatedly asking
-open-ended questions. Use the user's stated goal and the `./check-sync.sh` status to
-propose a default path plus one or two alternatives, and only ask for confirmation when
-an action requires explicit approval.
-
-Default behavior:
-
-- If the intent is RC maintenance, recommend the Sync Workflow and proceed with
-  safe preparation steps (status checks, previews). If the branch is behind upstream RC,
-  fetch and merge without additional confirmation when the working tree is clean, then
-  push to origin to keep the fork aligned. Push upstream only when there are local fixes
-  to publish.
-- If the intent is new feature work, recommend the PR Workflow and proceed with safe
-  preparation steps (status checks, identifying scope). Ask for approval before merges,
-  pushes, or dependency installs.
-- If `./check-sync.sh` reports **diverged** during Sync Workflow, merge
-  `upstream/<TARGET_RC>` into the current branch and preserve local commits.
-- If `./check-sync.sh` reports **diverged** during PR Workflow, stop and ask for guidance
-  with a short explanation of the divergence and the minimal options to resolve it.
-  If the user's intent is RC maintenance, prefer the Sync Workflow regardless of the
-  script hint. When the intent is new feature work, use the PR Workflow and avoid upstream
-  RC pushes.
-
-Suggestion format (keep it short):
-
-- **Recommended**: one sentence with the default path and why it fits the task.
-- **Alternatives**: one or two options with the tradeoff or prerequisite.
-- **Approval points**: mention any upcoming actions that need explicit approval (exclude sync
-  workflow pushes and merges).
-
-## Failure Modes and How to Avoid Them
-
-Sync Workflow:
-
-- Wrong RC target: verify the auto-detected RC in `./check-sync.sh` output before merging.
-- Diverged from upstream RC: stop and resolve manually before any merge or push.
-- Dirty working tree: commit or stash before syncing to avoid accidental merges.
-- Missing remotes: ensure both `origin` and `upstream` are configured before syncing.
-- Build breaks after sync: run `npm run build:packages` and `npm run build` before pushing.
-
-PR Workflow:
-
-- Branch not synced to current RC: re-run `./check-sync.sh` and merge RC before shipping.
-- Pushing the wrong branch: confirm `git branch --show-current` before pushing.
-- Unreviewed changes: always commit and push to origin before opening or updating a PR.
-- Skipped tests/builds: run the build commands before declaring the PR ready.
-
-## Notes
-
-- Avoid merging with uncommitted changes; commit or stash first.
-- Prefer merge over rebase for PR branches; rebases rewrite history and often require a force push,
-  which should only be done with an explicit user request.
-- Use clear, conventional commit messages and split unrelated changes into separate commits.

Dockerfile

@@ -118,6 +118,7 @@ RUN curl -fsSL https://opencode.ai/install | bash && \
     echo "=== Checking OpenCode CLI installation ===" && \
     ls -la /home/automaker/.local/bin/ && \
     (which opencode && opencode --version) || echo "opencode installed (may need auth setup)"
+
 USER root
 
 # Add PATH to profile so it's available in all interactive shells (for login shells)
@@ -147,6 +148,15 @@ COPY --from=server-builder /app/apps/server/package*.json ./apps/server/
 # Copy node_modules (includes symlinks to libs)
 COPY --from=server-builder /app/node_modules ./node_modules
 
+# Install Playwright Chromium browser for AI agent verification tests
+# This adds ~300MB to the image but enables automated testing mode out of the box
+# Using the locally installed playwright ensures we use the pinned version from package-lock.json
+USER automaker
+RUN ./node_modules/.bin/playwright install chromium && \
+    echo "=== Playwright Chromium installed ===" && \
+    ls -la /home/automaker/.cache/ms-playwright/
+USER root
+
 # Create data and projects directories
 RUN mkdir -p /data /projects && chown automaker:automaker /data /projects
 

LICENSE

@@ -1,141 +1,27 @@
-AUTOMAKER LICENSE AGREEMENT
+## Project Status
 
-This License Agreement ("Agreement") is entered into between you ("Licensee") and the copyright holders of Automaker ("Licensor"). By using, copying, modifying, downloading, cloning, or distributing the Software (as defined below), you agree to be bound by the terms of this Agreement.
-
-1. DEFINITIONS
-
-"Software" means the Automaker software, including all source code, object code, documentation, and related materials.
-
-"Generated Files" means files created by the Software during normal operation to store internal state, configuration, or working data, including but not limited to app_spec.txt, feature.json, and similar files generated by the Software. Generated Files are not considered part of the Software for the purposes of this license and are not subject to the restrictions herein.
-
-"Derivative Work" means any work that is based on, derived from, or incorporates the Software or any substantial portion of it, including but not limited to modifications, forks, adaptations, translations, or any altered version of the Software.
-
-"Monetization" means any activity that generates revenue, income, or commercial benefit from the Software itself or any Derivative Work, including but not limited to:
-
-- Reselling, redistributing, or sublicensing the Software, any Derivative Work, or any substantial portion thereof
-- Including the Software, any Derivative Work, or substantial portions thereof in a product or service that you sell or distribute
-- Offering the Software, any Derivative Work, or substantial portions thereof as a standalone product or service for sale
-- Hosting the Software or any Derivative Work as a service (whether free or paid) for use by others, including cloud hosting, Software-as-a-Service (SaaS), or any other form of hosted access for third parties
-- Extracting, reselling, redistributing, or sublicensing any prompts, context, or other instructional content bundled within the Software
-- Creating, distributing, or selling modified versions, forks, or Derivative Works of the Software
-
-Monetization does NOT include:
-
-- Using the Software internally within your organization, regardless of whether your organization is for-profit
-- Using the Software to build products or services that generate revenue, as long as you are not reselling or redistributing the Software itself
-- Using the Software to provide services for which fees are charged, as long as the Software itself is not being resold or redistributed
-- Hosting the Software anywhere for personal use by a single developer, as long as the Software is not made accessible to others
-
-"Core Contributors" means the following individuals who are granted perpetual, royalty-free licenses:
-
-- Cody Seibert (webdevcody)
-- SuperComboGamer (SCG)
-- Kacper Lachowicz (Shironex, Shirone)
-- Ben Scott (trueheads)
-
-2. GRANT OF LICENSE
-
-Subject to the terms and conditions of this Agreement, Licensor hereby grants to Licensee a non-exclusive, non-transferable license to use, copy, modify, and distribute the Software, provided that:
-
-a) Licensee may freely clone, install, and use the Software locally or within an organization for the purpose of building, developing, and maintaining other products, software, or services. There are no restrictions on the products you build _using_ the Software.
-
-b) Licensee may run the Software on personal or organizational infrastructure for internal use.
-
-c) Core Contributors are each individually granted a perpetual, worldwide, royalty-free, non-exclusive license to use, copy, modify, distribute, and sublicense the Software for any purpose, including Monetization, without payment of any fees or royalties. Each Core Contributor may exercise these rights independently and does not require permission, consent, or approval from any other Core Contributor to Monetize the Software in any way they see fit.
-
-d) Commercial licenses for the Software may be discussed and issued to external parties or companies seeking to use the Software for financial gain or Monetization purposes. Core Contributors already have full rights under section 2(c) and do not require commercial licenses. Any commercial license issued to external parties shall require a unanimous vote by all Core Contributors and shall be granted in writing and signed by all Core Contributors.
-
-e) The list of individuals defined as "Core Contributors" in Section 1 shall be amended to reflect any revocation or reinstatement of status made under this section.
-
-3. RESTRICTIONS
-
-Licensee may NOT:
-
-- Engage in any Monetization of the Software or any Derivative Work without explicit written permission from all Core Contributors
-- Resell, redistribute, or sublicense the Software, any Derivative Work, or any substantial portion thereof
-- Create, distribute, or sell modified versions, forks, or Derivative Works of the Software for any commercial purpose
-- Include the Software, any Derivative Work, or substantial portions thereof in a product or service that you sell or distribute
-- Offer the Software, any Derivative Work, or substantial portions thereof as a standalone product or service for sale
-- Extract, resell, redistribute, or sublicense any prompts, context, or other instructional content bundled within the Software
-- Host the Software or any Derivative Work as a service (whether free or paid) for use by others (except Core Contributors)
-- Remove or alter any copyright notices or license terms
-- Use the Software in any manner that violates applicable laws or regulations
-
-Licensee MAY:
-
-- Use the Software internally within their organization (commercial or non-profit)
-- Use the Software to build other commercial products (products that do NOT contain the Software or Derivative Works)
-- Modify the Software for internal use within their organization (commercial or non-profit)
-
-4. CORE CONTRIBUTOR STATUS MANAGEMENT
-
-a) Core Contributor status may be revoked indefinitely by the remaining Core Contributors if:
-
-- A Core Contributor cannot be reached for a period of one (1) month through reasonable means of communication (including but not limited to email, Discord, GitHub, or other project communication channels)
-- AND the Core Contributor has not contributed to the project during that one-month period. For purposes of this section, "contributed" means at least one of the following activities:
-  - Discussing the Software through project communication channels
-  - Committing code changes to the project repository
-  - Submitting bug fixes or patches
-  - Participating in project-related discussions or decision-making
-
-b) Revocation of Core Contributor status requires a unanimous vote by all other Core Contributors (excluding the Core Contributor whose status is being considered for revocation).
-
-c) Upon revocation of Core Contributor status, the individual shall no longer be considered a Core Contributor and shall lose the rights granted under section 2(c) of this Agreement. However, any Contributions made prior to revocation shall remain subject to the terms of section 5 (CONTRIBUTIONS AND RIGHTS ASSIGNMENT).
-
-d) A revoked Core Contributor may be reinstated to Core Contributor status with a unanimous vote by all current Core Contributors. Upon reinstatement, the individual shall regain all rights granted under section 2(c) of this Agreement.
-
-5. CONTRIBUTIONS AND RIGHTS ASSIGNMENT
-
-By submitting, pushing, or contributing any code, documentation, pull requests, issues, or other materials ("Contributions") to the Automaker project, you agree to the following terms without reservation:
-
-a) **Full Ownership Transfer & Rights Grant:** You hereby assign to the Core Contributors all right, title, and interest in and to your Contributions, including all copyrights, patents, and other intellectual property rights. If such assignment is not effective under applicable law, you grant the Core Contributors an unrestricted, perpetual, worldwide, non-exclusive, royalty-free, fully paid-up, irrevocable, sublicensable, and transferable license to use, reproduce, modify, adapt, publish, translate, create derivative works from, distribute, perform, display, and otherwise exploit your Contributions in any manner they see fit, including for any commercial purpose or Monetization.
-
-b) **No Take-Backs:** You understand and agree that this grant of rights is irrevocable ("no take-backs"). You cannot revoke, rescind, or terminate this grant of rights once your Contribution has been submitted.
-
-c) **Waiver of Moral Rights:** You waive any "moral rights" or other rights with respect to attribution of authorship or integrity of materials regarding your Contributions that you may have under any applicable law.
-
-d) **Right to Contribute:** You represent and warrant that you are the original author of the Contributions, or that you have sufficient rights to grant the rights conveyed by this section, and that your Contributions do not infringe upon the rights of any third party.
-
-6. TERMINATION
-
-This license will terminate automatically if Licensee breaches any term of this Agreement. Upon termination, Licensee must immediately cease all use of the Software and destroy all copies in their possession.
-
-7. HIGH RISK DISCLAIMER AND LIMITATION OF LIABILITY
-
-a) **AI RISKS:** THE SOFTWARE UTILIZES ARTIFICIAL INTELLIGENCE TO GENERATE CODE, EXECUTE COMMANDS, AND INTERACT WITH YOUR FILE SYSTEM. YOU ACKNOWLEDGE THAT AI SYSTEMS CAN BE UNPREDICTABLE, MAY GENERATE INCORRECT, INSECURE, OR DESTRUCTIVE CODE, AND MAY TAKE ACTIONS THAT COULD DAMAGE YOUR SYSTEM, FILES, OR HARDWARE.
-
-b) **USE AT YOUR OWN RISK:** YOU AGREE THAT YOUR USE OF THE SOFTWARE IS SOLELY AT YOUR OWN RISK. THE CORE CONTRIBUTORS AND LICENSOR DO NOT GUARANTEE THAT THE SOFTWARE OR ANY CODE GENERATED BY IT WILL BE SAFE, BUG-FREE, OR FUNCTIONAL.
-
-c) **NO WARRANTY:** THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
-
-d) **LIMITATION OF LIABILITY:** IN NO EVENT SHALL THE CORE CONTRIBUTORS, LICENSORS, OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE, INCLUDING BUT NOT LIMITED TO:
-
-- DAMAGE TO HARDWARE OR COMPUTER SYSTEMS
-- DATA LOSS OR CORRUPTION
-- GENERATION OF BAD, VULNERABLE, OR MALICIOUS CODE
-- FINANCIAL LOSSES
-- BUSINESS INTERRUPTION
-
-8. LICENSE AMENDMENTS
-
-Any amendment, modification, or update to this License Agreement must be agreed upon unanimously by all Core Contributors. No changes to this Agreement shall be effective unless all Core Contributors have provided their written consent or approval through a unanimous vote.
-
-9. CONTACT
-
-For inquiries regarding this license or permissions for Monetization, please contact the Core Contributors through the official project channels:
-
-- Agentic Jumpstart Discord: https://discord.gg/JUDWZDN3VT
-- Website: https://automaker.app
-- Email: automakerapp@gmail.com
-
-Any permission for Monetization requires the unanimous written consent of all Core Contributors.
-
-10. GOVERNING LAW
-
-This Agreement shall be governed by and construed in accordance with the laws of the State of Tennessee, USA, without regard to conflict of law principles.
-
-By using the Software, you acknowledge that you have read this Agreement, understand it, and agree to be bound by its terms and conditions.
+**This project is no longer actively maintained.** The codebase is provided as-is for those who wish to use, study, or fork it. No bug fixes, security updates, or new features are being developed. Community contributions may still be accepted, but there is no guarantee of review or merge.
 
 ---
 
+MIT License
+
 Copyright (c) 2025 Automaker Core Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -288,6 +288,31 @@ services:
 
 **Note:** The Claude CLI config must be writable (do not use `:ro` flag) as the CLI writes debug files.
 
+> **⚠️ Important: Linux/WSL Users**
+>
+> The container runs as UID 1001 by default. If your host user has a different UID (common on Linux/WSL where the first user is UID 1000), you must create a `.env` file to match your host user:
+>
+> ```bash
+> # Check your UID/GID
+> id -u  # outputs your UID (e.g., 1000)
+> id -g  # outputs your GID (e.g., 1000)
+> ```
+>
+> Create a `.env` file in the automaker directory:
+>
+> ```
+> UID=1000
+> GID=1000
+> ```
+>
+> Then rebuild the images:
+>
+> ```bash
+> docker compose build
+> ```
+>
+> Without this, files written by the container will be inaccessible to your host user.
+
 ##### GitHub CLI Authentication (For Git Push/PR Operations)
 
 To enable git push and GitHub CLI operations inside the container:
@@ -338,6 +363,42 @@ services:
 
 The Docker image supports both AMD64 and ARM64 architectures. The GitHub CLI and Claude CLI are automatically downloaded for the correct architecture during build.
 
+##### Playwright for Automated Testing
+
+The Docker image includes **Playwright Chromium pre-installed** for AI agent verification tests. When agents implement features in automated testing mode, they use Playwright to verify the implementation works correctly.
+
+**No additional setup required** - Playwright verification works out of the box.
+
+#### Optional: Persist browsers for manual updates
+
+By default, Playwright Chromium is pre-installed in the Docker image. If you need to manually update browsers or want to persist browser installations across container restarts (not image rebuilds), you can mount a volume.
+
+**Important:** When you first add this volume mount to an existing setup, the empty volume will override the pre-installed browsers. You must re-install them:
+
+```bash
+# After adding the volume mount for the first time
+docker exec --user automaker -w /app automaker-server npx playwright install chromium
+```
+
+Add this to your `docker-compose.override.yml`:
+
+```yaml
+services:
+  server:
+    volumes:
+      - playwright-cache:/home/automaker/.cache/ms-playwright
+
+volumes:
+  playwright-cache:
+    name: automaker-playwright-cache
+```
+
+**Updating browsers manually:**
+
+```bash
+docker exec --user automaker -w /app automaker-server npx playwright install chromium
+```
+
 ### Testing
 
 #### End-to-End Tests (Playwright)
@@ -644,26 +705,10 @@ Join the **Agentic Jumpstart** Discord to connect with other builders exploring
 
 👉 [Agentic Jumpstart Discord](https://discord.gg/jjem7aEDKU)
 
+## Project Status
+
+**This project is no longer actively maintained.** The codebase is provided as-is for those who wish to use, study, or fork it. No bug fixes, security updates, or new features are being developed. Community contributions may still be accepted, but there is no guarantee of review or merge.
+
 ## License
 
-This project is licensed under the **Automaker License Agreement**. See [LICENSE](LICENSE) for the full text.
-
-**Summary of Terms:**
-
-- **Allowed:**
-  - **Build Anything:** You can clone and use Automaker locally or in your organization to build ANY product (commercial or free).
-  - **Internal Use:** You can use it internally within your company (commercial or non-profit) without restriction.
-  - **Modify:** You can modify the code for internal use within your organization (commercial or non-profit).
-
-- **Restricted (The "No Monetization of the Tool" Rule):**
-  - **No Resale:** You cannot resell Automaker itself.
-  - **No SaaS:** You cannot host Automaker as a service for others.
-  - **No Monetizing Mods:** You cannot distribute modified versions of Automaker for money.
-
-- **Liability:**
-  - **Use at Own Risk:** This tool uses AI. We are **NOT** responsible if it breaks your computer, deletes your files, or generates bad code. You assume all risk.
-
-- **Contributing:**
-  - By contributing to this repository, you grant the Core Contributors full, irrevocable rights to your code (copyright assignment).
-
-**Core Contributors** (Cody Seibert (webdevcody), SuperComboGamer (SCG), Kacper Lachowicz (Shironex, Shirone), and Ben Scott (trueheads)) are granted perpetual, royalty-free licenses for any use, including monetization.
+This project is licensed under the **MIT License**. See [LICENSE](LICENSE) for the full text.

apps/server/eslint.config.mjs

@@ -0,0 +1,74 @@
+import { defineConfig, globalIgnores } from 'eslint/config';
+import js from '@eslint/js';
+import ts from '@typescript-eslint/eslint-plugin';
+import tsParser from '@typescript-eslint/parser';
+
+const eslintConfig = defineConfig([
+  js.configs.recommended,
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+      },
+      globals: {
+        // Node.js globals
+        console: 'readonly',
+        process: 'readonly',
+        Buffer: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        URL: 'readonly',
+        URLSearchParams: 'readonly',
+        AbortController: 'readonly',
+        AbortSignal: 'readonly',
+        fetch: 'readonly',
+        Response: 'readonly',
+        Request: 'readonly',
+        Headers: 'readonly',
+        FormData: 'readonly',
+        RequestInit: 'readonly',
+        // Timers
+        setTimeout: 'readonly',
+        setInterval: 'readonly',
+        clearTimeout: 'readonly',
+        clearInterval: 'readonly',
+        setImmediate: 'readonly',
+        clearImmediate: 'readonly',
+        queueMicrotask: 'readonly',
+        // Node.js types
+        NodeJS: 'readonly',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': ts,
+    },
+    rules: {
+      ...ts.configs.recommended.rules,
+      '@typescript-eslint/no-unused-vars': [
+        'warn',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          caughtErrorsIgnorePattern: '^_',
+          ignoreRestSiblings: true,
+        },
+      ],
+      '@typescript-eslint/no-explicit-any': 'warn',
+      // Server code frequently works with terminal output containing ANSI escape codes
+      'no-control-regex': 'off',
+      '@typescript-eslint/ban-ts-comment': [
+        'error',
+        {
+          'ts-nocheck': 'allow-with-description',
+          minimumDescriptionLength: 10,
+        },
+      ],
+    },
+  },
+  globalIgnores(['dist/**', 'node_modules/**']),
+]);
+
+export default eslintConfig;

apps/server/package.json

@@ -24,7 +24,7 @@
     "test:unit": "vitest run tests/unit"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.1.76",
+    "@anthropic-ai/claude-agent-sdk": "0.2.32",
     "@automaker/dependency-resolver": "1.0.0",
     "@automaker/git-utils": "1.0.0",
     "@automaker/model-resolver": "1.0.0",
@@ -34,7 +34,7 @@
     "@automaker/utils": "1.0.0",
     "@github/copilot-sdk": "^0.1.16",
     "@modelcontextprotocol/sdk": "1.25.2",
-    "@openai/codex-sdk": "^0.77.0",
+    "@openai/codex-sdk": "^0.98.0",
     "cookie-parser": "1.4.7",
     "cors": "2.8.5",
     "dotenv": "17.2.3",
@@ -45,6 +45,7 @@
     "yaml": "2.7.0"
   },
   "devDependencies": {
+    "@playwright/test": "1.57.0",
     "@types/cookie": "0.6.0",
     "@types/cookie-parser": "1.4.10",
     "@types/cors": "2.8.19",

apps/server/src/index.ts

@@ -56,7 +56,7 @@ import {
 import { createSettingsRoutes } from './routes/settings/index.js';
 import { AgentService } from './services/agent-service.js';
 import { FeatureLoader } from './services/feature-loader.js';
-import { AutoModeService } from './services/auto-mode-service.js';
+import { AutoModeServiceCompat } from './services/auto-mode/index.js';
 import { getTerminalService } from './services/terminal-service.js';
 import { SettingsService } from './services/settings-service.js';
 import { createSpecRegenerationRoutes } from './routes/app-spec/index.js';
@@ -121,21 +121,57 @@ const BOX_CONTENT_WIDTH = 67;
 // The Claude Agent SDK can use either ANTHROPIC_API_KEY or Claude Code CLI authentication
 (async () => {
   const hasAnthropicKey = !!process.env.ANTHROPIC_API_KEY;
+  const hasEnvOAuthToken = !!process.env.CLAUDE_CODE_OAUTH_TOKEN;
+
+  logger.debug('[CREDENTIAL_CHECK] Starting credential detection...');
+  logger.debug('[CREDENTIAL_CHECK] Environment variables:', {
+    hasAnthropicKey,
+    hasEnvOAuthToken,
+  });
 
   if (hasAnthropicKey) {
     logger.info('✓ ANTHROPIC_API_KEY detected');
     return;
   }
 
+  if (hasEnvOAuthToken) {
+    logger.info('✓ CLAUDE_CODE_OAUTH_TOKEN detected');
+    return;
+  }
+
   // Check for Claude Code CLI authentication
+  // Store indicators outside the try block so we can use them in the warning message
+  let cliAuthIndicators: Awaited<ReturnType<typeof getClaudeAuthIndicators>> | null = null;
+
   try {
-    const indicators = await getClaudeAuthIndicators();
+    cliAuthIndicators = await getClaudeAuthIndicators();
+    const indicators = cliAuthIndicators;
+
+    // Log detailed credential detection results
+    const { checks, ...indicatorSummary } = indicators;
+    logger.debug('[CREDENTIAL_CHECK] Claude CLI auth indicators:', indicatorSummary);
+
+    logger.debug('[CREDENTIAL_CHECK] File check details:', checks);
+
     const hasCliAuth =
       indicators.hasStatsCacheWithActivity ||
       (indicators.hasSettingsFile && indicators.hasProjectsSessions) ||
       (indicators.hasCredentialsFile &&
         (indicators.credentials?.hasOAuthToken || indicators.credentials?.hasApiKey));
 
+    logger.debug('[CREDENTIAL_CHECK] Auth determination:', {
+      hasCliAuth,
+      reason: hasCliAuth
+        ? indicators.hasStatsCacheWithActivity
+          ? 'stats cache with activity'
+          : indicators.hasSettingsFile && indicators.hasProjectsSessions
+            ? 'settings file + project sessions'
+            : indicators.credentials?.hasOAuthToken
+              ? 'credentials file with OAuth token'
+              : 'credentials file with API key'
+        : 'no valid credentials found',
+    });
+
     if (hasCliAuth) {
       logger.info('✓ Claude Code CLI authentication detected');
       return;
@@ -145,7 +181,7 @@ const BOX_CONTENT_WIDTH = 67;
     logger.warn('Error checking for Claude Code CLI authentication:', error);
   }
 
-  // No authentication found - show warning
+  // No authentication found - show warning with paths that were checked
   const wHeader = '⚠️  WARNING: No Claude authentication configured'.padEnd(BOX_CONTENT_WIDTH);
   const w1 = 'The Claude Agent SDK requires authentication to function.'.padEnd(BOX_CONTENT_WIDTH);
   const w2 = 'Options:'.padEnd(BOX_CONTENT_WIDTH);
@@ -158,6 +194,33 @@ const BOX_CONTENT_WIDTH = 67;
     BOX_CONTENT_WIDTH
   );
 
+  // Build paths checked summary from the indicators (if available)
+  let pathsCheckedInfo = '';
+  if (cliAuthIndicators) {
+    const pathsChecked: string[] = [];
+
+    // Collect paths that were checked (paths are always populated strings)
+    pathsChecked.push(`Settings: ${cliAuthIndicators.checks.settingsFile.path}`);
+    pathsChecked.push(`Stats cache: ${cliAuthIndicators.checks.statsCache.path}`);
+    pathsChecked.push(`Projects dir: ${cliAuthIndicators.checks.projectsDir.path}`);
+    for (const credFile of cliAuthIndicators.checks.credentialFiles) {
+      pathsChecked.push(`Credentials: ${credFile.path}`);
+    }
+
+    if (pathsChecked.length > 0) {
+      pathsCheckedInfo = `
+║                                                                     ║
+║  ${'Paths checked:'.padEnd(BOX_CONTENT_WIDTH)}║
+${pathsChecked
+  .map((p) => {
+    const maxLen = BOX_CONTENT_WIDTH - 4;
+    const display = p.length > maxLen ? '...' + p.slice(-(maxLen - 3)) : p;
+    return `║    ${display.padEnd(maxLen)}  ║`;
+  })
+  .join('\n')}`;
+    }
+  }
+
   logger.warn(`
 ╔═════════════════════════════════════════════════════════════════════╗
 ║  ${wHeader}║
@@ -169,7 +232,7 @@ const BOX_CONTENT_WIDTH = 67;
 ║  ${w3}║
 ║  ${w4}║
 ║  ${w5}║
-║  ${w6}║
+║  ${w6}║${pathsCheckedInfo}
 ║                                                                     ║
 ╚═════════════════════════════════════════════════════════════════════╝
 `);
@@ -258,7 +321,9 @@ const events: EventEmitter = createEventEmitter();
 const settingsService = new SettingsService(DATA_DIR);
 const agentService = new AgentService(DATA_DIR, events, settingsService);
 const featureLoader = new FeatureLoader();
-const autoModeService = new AutoModeService(events, settingsService);
+
+// Auto-mode services: compatibility layer provides old interface while using new architecture
+const autoModeService = new AutoModeServiceCompat(events, settingsService, featureLoader);
 const claudeUsageService = new ClaudeUsageService();
 const codexAppServerService = new CodexAppServerService();
 const codexModelCacheService = new CodexModelCacheService(DATA_DIR, codexAppServerService);
@@ -303,24 +368,61 @@ eventHookService.initialize(events, settingsService, eventHistoryService, featur
     logger.warn('Failed to check for legacy settings migration:', err);
   }
 
-  // Apply logging settings from saved settings
+  // Fetch global settings once and reuse for logging config and feature reconciliation
+  let globalSettings: Awaited<ReturnType<typeof settingsService.getGlobalSettings>> | null = null;
   try {
-    const settings = await settingsService.getGlobalSettings();
-    if (settings.serverLogLevel && LOG_LEVEL_MAP[settings.serverLogLevel] !== undefined) {
-      setLogLevel(LOG_LEVEL_MAP[settings.serverLogLevel]);
-      logger.info(`Server log level set to: ${settings.serverLogLevel}`);
-    }
-    // Apply request logging setting (default true if not set)
-    const enableRequestLog = settings.enableRequestLogging ?? true;
-    setRequestLoggingEnabled(enableRequestLog);
-    logger.info(`HTTP request logging: ${enableRequestLog ? 'enabled' : 'disabled'}`);
+    globalSettings = await settingsService.getGlobalSettings();
   } catch (err) {
-    logger.warn('Failed to load logging settings, using defaults');
+    logger.warn('Failed to load global settings, using defaults');
+  }
+
+  // Apply logging settings from saved settings
+  if (globalSettings) {
+    try {
+      if (
+        globalSettings.serverLogLevel &&
+        LOG_LEVEL_MAP[globalSettings.serverLogLevel] !== undefined
+      ) {
+        setLogLevel(LOG_LEVEL_MAP[globalSettings.serverLogLevel]);
+        logger.info(`Server log level set to: ${globalSettings.serverLogLevel}`);
+      }
+      // Apply request logging setting (default true if not set)
+      const enableRequestLog = globalSettings.enableRequestLogging ?? true;
+      setRequestLoggingEnabled(enableRequestLog);
+      logger.info(`HTTP request logging: ${enableRequestLog ? 'enabled' : 'disabled'}`);
+    } catch (err) {
+      logger.warn('Failed to apply logging settings, using defaults');
+    }
   }
 
   await agentService.initialize();
   logger.info('Agent service initialized');
 
+  // Reconcile feature states on startup
+  // After any type of restart (clean, forced, crash), features may be stuck in
+  // transient states (in_progress, interrupted, pipeline_*) that don't match reality.
+  // Reconcile them back to resting states before the UI is served.
+  if (globalSettings) {
+    try {
+      if (globalSettings.projects && globalSettings.projects.length > 0) {
+        let totalReconciled = 0;
+        for (const project of globalSettings.projects) {
+          const count = await autoModeService.reconcileFeatureStates(project.path);
+          totalReconciled += count;
+        }
+        if (totalReconciled > 0) {
+          logger.info(
+            `[STARTUP] Reconciled ${totalReconciled} feature(s) across ${globalSettings.projects.length} project(s)`
+          );
+        } else {
+          logger.info('[STARTUP] Feature state reconciliation complete - no stale states found');
+        }
+      }
+    } catch (err) {
+      logger.warn('[STARTUP] Failed to reconcile feature states:', err);
+    }
+  }
+
   // Bootstrap Codex model cache in background (don't block server startup)
   void codexModelCacheService.getModels().catch((err) => {
     logger.error('Failed to bootstrap Codex model cache:', err);
@@ -390,7 +492,7 @@ const server = createServer(app);
 // WebSocket servers using noServer mode for proper multi-path support
 const wss = new WebSocketServer({ noServer: true });
 const terminalWss = new WebSocketServer({ noServer: true });
-const terminalService = getTerminalService();
+const terminalService = getTerminalService(settingsService);
 
 /**
  * Authenticate WebSocket upgrade requests

apps/server/src/lib/sdk-options.ts

@@ -253,11 +253,27 @@ function buildMcpOptions(config: CreateSdkOptionsConfig): McpOptions {
 /**
  * Build thinking options for SDK configuration.
  * Converts ThinkingLevel to maxThinkingTokens for the Claude SDK.
+ * For adaptive thinking (Opus 4.6), omits maxThinkingTokens to let the model
+ * decide its own reasoning depth.
  *
  * @param thinkingLevel - The thinking level to convert
- * @returns Object with maxThinkingTokens if thinking is enabled
+ * @returns Object with maxThinkingTokens if thinking is enabled with a budget
  */
 function buildThinkingOptions(thinkingLevel?: ThinkingLevel): Partial<Options> {
+  if (!thinkingLevel || thinkingLevel === 'none') {
+    return {};
+  }
+
+  // Adaptive thinking (Opus 4.6): don't set maxThinkingTokens
+  // The model will use adaptive thinking by default
+  if (thinkingLevel === 'adaptive') {
+    logger.debug(
+      `buildThinkingOptions: thinkingLevel="adaptive" -> no maxThinkingTokens (model decides)`
+    );
+    return {};
+  }
+
+  // Manual budget-based thinking for Haiku/Sonnet
   const maxThinkingTokens = getThinkingTokenBudget(thinkingLevel);
   logger.debug(
     `buildThinkingOptions: thinkingLevel="${thinkingLevel}" -> maxThinkingTokens=${maxThinkingTokens}`

apps/server/src/lib/terminal-themes-data.ts

@@ -0,0 +1,25 @@
+/**
+ * Terminal Theme Data - Re-export terminal themes from platform package
+ *
+ * This module re-exports terminal theme data for use in the server.
+ */
+
+import { terminalThemeColors, getTerminalThemeColors as getThemeColors } from '@automaker/platform';
+import type { ThemeMode } from '@automaker/types';
+import type { TerminalTheme } from '@automaker/platform';
+
+/**
+ * Get terminal theme colors for a given theme mode
+ */
+export function getTerminalThemeColors(theme: ThemeMode): TerminalTheme {
+  return getThemeColors(theme);
+}
+
+/**
+ * Get all terminal themes
+ */
+export function getAllTerminalThemes(): Record<ThemeMode, TerminalTheme> {
+  return terminalThemeColors;
+}
+
+export default terminalThemeColors;

apps/server/src/providers/claude-provider.ts

@@ -204,7 +204,7 @@ export class ClaudeProvider extends BaseProvider {
       model,
       cwd,
       systemPrompt,
-      maxTurns = 20,
+      maxTurns = 100,
       allowedTools,
       abortController,
       conversationHistory,
@@ -219,8 +219,11 @@ export class ClaudeProvider extends BaseProvider {
     // claudeCompatibleProvider takes precedence over claudeApiProfile
     const providerConfig = claudeCompatibleProvider || claudeApiProfile;
 
-    // Convert thinking level to token budget
-    const maxThinkingTokens = getThinkingTokenBudget(thinkingLevel);
+    // Build thinking configuration
+    // Adaptive thinking (Opus 4.6): don't set maxThinkingTokens, model uses adaptive by default
+    // Manual thinking (Haiku/Sonnet): use budget_tokens
+    const maxThinkingTokens =
+      thinkingLevel === 'adaptive' ? undefined : getThinkingTokenBudget(thinkingLevel);
 
     // Build Claude SDK options
     const sdkOptions: Options = {
@@ -349,13 +352,13 @@ export class ClaudeProvider extends BaseProvider {
   getAvailableModels(): ModelDefinition[] {
     const models = [
       {
-        id: 'claude-opus-4-5-20251101',
-        name: 'Claude Opus 4.5',
-        modelString: 'claude-opus-4-5-20251101',
+        id: 'claude-opus-4-6',
+        name: 'Claude Opus 4.6',
+        modelString: 'claude-opus-4-6',
         provider: 'anthropic',
-        description: 'Most capable Claude model',
+        description: 'Most capable Claude model with adaptive thinking',
         contextWindow: 200000,
-        maxOutputTokens: 16000,
+        maxOutputTokens: 128000,
         supportsVision: true,
         supportsTools: true,
         tier: 'premium' as const,

apps/server/src/providers/codex-models.ts

@@ -19,12 +19,11 @@ const MAX_OUTPUT_16K = 16000;
 export const CODEX_MODELS: ModelDefinition[] = [
   // ========== Recommended Codex Models ==========
   {
-    id: CODEX_MODEL_MAP.gpt52Codex,
-    name: 'GPT-5.2-Codex',
-    modelString: CODEX_MODEL_MAP.gpt52Codex,
+    id: CODEX_MODEL_MAP.gpt53Codex,
+    name: 'GPT-5.3-Codex',
+    modelString: CODEX_MODEL_MAP.gpt53Codex,
     provider: 'openai',
-    description:
-      'Most advanced agentic coding model for complex software engineering (default for ChatGPT users).',
+    description: 'Latest frontier agentic coding model.',
     contextWindow: CONTEXT_WINDOW_256K,
     maxOutputTokens: MAX_OUTPUT_32K,
     supportsVision: true,
@@ -33,12 +32,25 @@ export const CODEX_MODELS: ModelDefinition[] = [
     default: true,
     hasReasoning: true,
   },
+  {
+    id: CODEX_MODEL_MAP.gpt52Codex,
+    name: 'GPT-5.2-Codex',
+    modelString: CODEX_MODEL_MAP.gpt52Codex,
+    provider: 'openai',
+    description: 'Frontier agentic coding model.',
+    contextWindow: CONTEXT_WINDOW_256K,
+    maxOutputTokens: MAX_OUTPUT_32K,
+    supportsVision: true,
+    supportsTools: true,
+    tier: 'premium' as const,
+    hasReasoning: true,
+  },
   {
     id: CODEX_MODEL_MAP.gpt51CodexMax,
     name: 'GPT-5.1-Codex-Max',
     modelString: CODEX_MODEL_MAP.gpt51CodexMax,
     provider: 'openai',
-    description: 'Optimized for long-horizon, agentic coding tasks in Codex.',
+    description: 'Codex-optimized flagship for deep and fast reasoning.',
     contextWindow: CONTEXT_WINDOW_256K,
     maxOutputTokens: MAX_OUTPUT_32K,
     supportsVision: true,
@@ -51,7 +63,7 @@ export const CODEX_MODELS: ModelDefinition[] = [
     name: 'GPT-5.1-Codex-Mini',
     modelString: CODEX_MODEL_MAP.gpt51CodexMini,
     provider: 'openai',
-    description: 'Smaller, more cost-effective version for faster workflows.',
+    description: 'Optimized for codex. Cheaper, faster, but less capable.',
     contextWindow: CONTEXT_WINDOW_128K,
     maxOutputTokens: MAX_OUTPUT_16K,
     supportsVision: true,
@@ -66,7 +78,7 @@ export const CODEX_MODELS: ModelDefinition[] = [
     name: 'GPT-5.2',
     modelString: CODEX_MODEL_MAP.gpt52,
     provider: 'openai',
-    description: 'Best general agentic model for tasks across industries and domains.',
+    description: 'Latest frontier model with improvements across knowledge, reasoning and coding.',
     contextWindow: CONTEXT_WINDOW_256K,
     maxOutputTokens: MAX_OUTPUT_32K,
     supportsVision: true,

apps/server/src/providers/cursor-provider.ts

@@ -14,6 +14,7 @@ import { execSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { findCliInWsl, isWslAvailable } from '@automaker/platform';
 import {
   CliProvider,
   type CliSpawnConfig,
@@ -286,15 +287,113 @@ export class CursorProvider extends CliProvider {
 
   getSpawnConfig(): CliSpawnConfig {
     return {
-      windowsStrategy: 'wsl', // cursor-agent requires WSL on Windows
+      windowsStrategy: 'direct',
       commonPaths: {
         linux: [
           path.join(os.homedir(), '.local/bin/cursor-agent'), // Primary symlink location
           '/usr/local/bin/cursor-agent',
         ],
         darwin: [path.join(os.homedir(), '.local/bin/cursor-agent'), '/usr/local/bin/cursor-agent'],
-        // Windows paths are not used - we check for WSL installation instead
-        win32: [],
+        win32: [
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'Programs',
+            'Cursor',
+            'resources',
+            'app',
+            'bin',
+            'cursor-agent.exe'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'Programs',
+            'Cursor',
+            'resources',
+            'app',
+            'bin',
+            'cursor-agent.cmd'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'Programs',
+            'Cursor',
+            'resources',
+            'app',
+            'bin',
+            'cursor.exe'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'Programs',
+            'Cursor',
+            'cursor.exe'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'Programs',
+            'cursor',
+            'resources',
+            'app',
+            'bin',
+            'cursor-agent.exe'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'Programs',
+            'cursor',
+            'resources',
+            'app',
+            'bin',
+            'cursor-agent.cmd'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'Programs',
+            'cursor',
+            'resources',
+            'app',
+            'bin',
+            'cursor.exe'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'Programs',
+            'cursor',
+            'cursor.exe'
+          ),
+          path.join(
+            process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'),
+            'npm',
+            'cursor-agent.cmd'
+          ),
+          path.join(
+            process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'),
+            'npm',
+            'cursor.cmd'
+          ),
+          path.join(
+            process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'),
+            '.npm-global',
+            'bin',
+            'cursor-agent.cmd'
+          ),
+          path.join(
+            process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'),
+            '.npm-global',
+            'bin',
+            'cursor.cmd'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'pnpm',
+            'cursor-agent.cmd'
+          ),
+          path.join(
+            process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+            'pnpm',
+            'cursor.cmd'
+          ),
+        ],
       },
     };
   }
@@ -487,6 +586,92 @@ export class CursorProvider extends CliProvider {
    * 2. Cursor IDE with 'cursor agent' subcommand support
    */
   protected detectCli(): CliDetectionResult {
+    if (process.platform === 'win32') {
+      const findInPath = (command: string): string | null => {
+        try {
+          const result = execSync(`where ${command}`, {
+            encoding: 'utf8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
+          })
+            .trim()
+            .split(/\r?\n/)[0];
+
+          if (result && fs.existsSync(result)) {
+            return result;
+          }
+        } catch {
+          // Not in PATH
+        }
+
+        return null;
+      };
+
+      const isCursorAgentBinary = (cliPath: string) =>
+        cliPath.toLowerCase().includes('cursor-agent');
+
+      const supportsCursorAgentSubcommand = (cliPath: string) => {
+        try {
+          execSync(`"${cliPath}" agent --version`, {
+            encoding: 'utf8',
+            timeout: 5000,
+            stdio: 'pipe',
+            windowsHide: true,
+          });
+          return true;
+        } catch {
+          return false;
+        }
+      };
+
+      const pathResult = findInPath('cursor-agent') || findInPath('cursor');
+      if (pathResult) {
+        if (isCursorAgentBinary(pathResult) || supportsCursorAgentSubcommand(pathResult)) {
+          return {
+            cliPath: pathResult,
+            useWsl: false,
+            strategy: pathResult.toLowerCase().endsWith('.cmd') ? 'cmd' : 'direct',
+          };
+        }
+      }
+
+      const config = this.getSpawnConfig();
+      for (const candidate of config.commonPaths.win32 || []) {
+        const resolved = candidate;
+        if (!fs.existsSync(resolved)) {
+          continue;
+        }
+        if (isCursorAgentBinary(resolved) || supportsCursorAgentSubcommand(resolved)) {
+          return {
+            cliPath: resolved,
+            useWsl: false,
+            strategy: resolved.toLowerCase().endsWith('.cmd') ? 'cmd' : 'direct',
+          };
+        }
+      }
+
+      const wslLogger = (msg: string) => logger.debug(msg);
+      if (isWslAvailable({ logger: wslLogger })) {
+        const wslResult = findCliInWsl('cursor-agent', { logger: wslLogger });
+        if (wslResult) {
+          logger.debug(
+            `Using cursor-agent via WSL (${wslResult.distribution || 'default'}): ${wslResult.wslPath}`
+          );
+          return {
+            cliPath: 'wsl.exe',
+            useWsl: true,
+            wslCliPath: wslResult.wslPath,
+            wslDistribution: wslResult.distribution,
+            strategy: 'wsl',
+          };
+        }
+      }
+
+      logger.debug('cursor-agent not found on Windows');
+      return { cliPath: null, useWsl: false, strategy: 'direct' };
+    }
+
     // First try standard detection (PATH, common paths, WSL)
     const result = super.detectCli();
     if (result.cliPath) {
@@ -495,7 +680,7 @@ export class CursorProvider extends CliProvider {
 
     // Cursor-specific: Check versions directory for any installed version
     // This handles cases where cursor-agent is installed but not in PATH
-    if (process.platform !== 'win32' && fs.existsSync(CursorProvider.VERSIONS_DIR)) {
+    if (fs.existsSync(CursorProvider.VERSIONS_DIR)) {
       try {
         const versions = fs
           .readdirSync(CursorProvider.VERSIONS_DIR)
@@ -521,33 +706,31 @@ export class CursorProvider extends CliProvider {
 
     // If cursor-agent not found, try to find 'cursor' IDE and use 'cursor agent' subcommand
     // The Cursor IDE includes the agent as a subcommand: cursor agent
-    if (process.platform !== 'win32') {
-      const cursorPaths = [
-        '/usr/bin/cursor',
-        '/usr/local/bin/cursor',
-        path.join(os.homedir(), '.local/bin/cursor'),
-        '/opt/cursor/cursor',
-      ];
+    const cursorPaths = [
+      '/usr/bin/cursor',
+      '/usr/local/bin/cursor',
+      path.join(os.homedir(), '.local/bin/cursor'),
+      '/opt/cursor/cursor',
+    ];
 
-      for (const cursorPath of cursorPaths) {
-        if (fs.existsSync(cursorPath)) {
-          // Verify cursor agent subcommand works
-          try {
-            execSync(`"${cursorPath}" agent --version`, {
-              encoding: 'utf8',
-              timeout: 5000,
-              stdio: 'pipe',
-            });
-            logger.debug(`Using cursor agent via Cursor IDE: ${cursorPath}`);
-            // Return cursor path but we'll use 'cursor agent' subcommand
-            return {
-              cliPath: cursorPath,
-              useWsl: false,
-              strategy: 'native',
-            };
-          } catch {
-            // cursor agent subcommand doesn't work, try next path
-          }
+    for (const cursorPath of cursorPaths) {
+      if (fs.existsSync(cursorPath)) {
+        // Verify cursor agent subcommand works
+        try {
+          execSync(`"${cursorPath}" agent --version`, {
+            encoding: 'utf8',
+            timeout: 5000,
+            stdio: 'pipe',
+          });
+          logger.debug(`Using cursor agent via Cursor IDE: ${cursorPath}`);
+          // Return cursor path but we'll use 'cursor agent' subcommand
+          return {
+            cliPath: cursorPath,
+            useWsl: false,
+            strategy: 'native',
+          };
+        } catch {
+          // cursor agent subcommand doesn't work, try next path
         }
       }
     }

apps/server/src/providers/provider-factory.ts

@@ -103,7 +103,7 @@ export class ProviderFactory {
   /**
    * Get the appropriate provider for a given model ID
    *
-   * @param modelId Model identifier (e.g., "claude-opus-4-5-20251101", "cursor-gpt-4o", "cursor-auto")
+   * @param modelId Model identifier (e.g., "claude-opus-4-6", "cursor-gpt-4o", "cursor-auto")
    * @param options Optional settings
    * @param options.throwOnDisconnected Throw error if provider is disconnected (default: true)
    * @returns Provider instance for the model

apps/server/src/routes/auto-mode/index.ts

@@ -1,11 +1,12 @@
 /**
  * Auto Mode routes - HTTP API for autonomous feature implementation
  *
- * Uses the AutoModeService for real feature execution with Claude Agent SDK
+ * Uses AutoModeServiceCompat which provides the old interface while
+ * delegating to GlobalAutoModeService and per-project facades.
  */
 
 import { Router } from 'express';
-import type { AutoModeService } from '../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../services/auto-mode/index.js';
 import { validatePathParams } from '../../middleware/validate-paths.js';
 import { createStopFeatureHandler } from './routes/stop-feature.js';
 import { createStatusHandler } from './routes/status.js';
@@ -20,8 +21,14 @@ import { createFollowUpFeatureHandler } from './routes/follow-up-feature.js';
 import { createCommitFeatureHandler } from './routes/commit-feature.js';
 import { createApprovePlanHandler } from './routes/approve-plan.js';
 import { createResumeInterruptedHandler } from './routes/resume-interrupted.js';
+import { createReconcileHandler } from './routes/reconcile.js';
 
-export function createAutoModeRoutes(autoModeService: AutoModeService): Router {
+/**
+ * Create auto-mode routes.
+ *
+ * @param autoModeService - AutoModeServiceCompat instance
+ */
+export function createAutoModeRoutes(autoModeService: AutoModeServiceCompat): Router {
   const router = Router();
 
   // Auto loop control routes
@@ -75,6 +82,11 @@ export function createAutoModeRoutes(autoModeService: AutoModeService): Router {
     validatePathParams('projectPath'),
     createResumeInterruptedHandler(autoModeService)
   );
+  router.post(
+    '/reconcile',
+    validatePathParams('projectPath'),
+    createReconcileHandler(autoModeService)
+  );
 
   return router;
 }

apps/server/src/routes/auto-mode/routes/analyze-project.ts

@@ -3,13 +3,13 @@
  */
 
 import type { Request, Response } from 'express';
-import type { AutoModeService } from '../../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../../services/auto-mode/index.js';
 import { createLogger } from '@automaker/utils';
 import { getErrorMessage, logError } from '../common.js';
 
 const logger = createLogger('AutoMode');
 
-export function createAnalyzeProjectHandler(autoModeService: AutoModeService) {
+export function createAnalyzeProjectHandler(autoModeService: AutoModeServiceCompat) {
   return async (req: Request, res: Response): Promise<void> => {
     try {
       const { projectPath } = req.body as { projectPath: string };

apps/server/src/routes/auto-mode/routes/approve-plan.ts

@@ -3,13 +3,13 @@
  */
 
 import type { Request, Response } from 'express';
-import type { AutoModeService } from '../../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../../services/auto-mode/index.js';
 import { createLogger } from '@automaker/utils';
 import { getErrorMessage, logError } from '../common.js';
 
 const logger = createLogger('AutoMode');
 
-export function createApprovePlanHandler(autoModeService: AutoModeService) {
+export function createApprovePlanHandler(autoModeService: AutoModeServiceCompat) {
   return async (req: Request, res: Response): Promise<void> => {
     try {
       const { featureId, approved, editedPlan, feedback, projectPath } = req.body as {
@@ -17,7 +17,7 @@ export function createApprovePlanHandler(autoModeService: AutoModeService) {
         approved: boolean;
         editedPlan?: string;
         feedback?: string;
-        projectPath?: string;
+        projectPath: string;
       };
 
       if (!featureId) {
@@ -36,6 +36,14 @@ export function createApprovePlanHandler(autoModeService: AutoModeService) {
         return;
       }
 
+      if (!projectPath) {
+        res.status(400).json({
+          success: false,
+          error: 'projectPath is required',
+        });
+        return;
+      }
+
       // Note: We no longer check hasPendingApproval here because resolvePlanApproval
       // can handle recovery when pending approval is not in Map but feature has planSpec.status='generated'
       // This supports cases where the server restarted while waiting for approval
@@ -48,11 +56,11 @@ export function createApprovePlanHandler(autoModeService: AutoModeService) {
 
       // Resolve the pending approval (with recovery support)
       const result = await autoModeService.resolvePlanApproval(
+        projectPath,
         featureId,
         approved,
         editedPlan,
-        feedback,
-        projectPath
+        feedback
       );
 
       if (!result.success) {

apps/server/src/routes/auto-mode/routes/commit-feature.ts

@@ -3,10 +3,10 @@
  */
 
 import type { Request, Response } from 'express';
-import type { AutoModeService } from '../../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../../services/auto-mode/index.js';
 import { getErrorMessage, logError } from '../common.js';
 
-export function createCommitFeatureHandler(autoModeService: AutoModeService) {
+export function createCommitFeatureHandler(autoModeService: AutoModeServiceCompat) {
   return async (req: Request, res: Response): Promise<void> => {
     try {
       const { projectPath, featureId, worktreePath } = req.body as {

apps/server/src/routes/auto-mode/routes/context-exists.ts

@@ -3,10 +3,10 @@
  */
 
 import type { Request, Response } from 'express';
-import type { AutoModeService } from '../../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../../services/auto-mode/index.js';
 import { getErrorMessage, logError } from '../common.js';
 
-export function createContextExistsHandler(autoModeService: AutoModeService) {
+export function createContextExistsHandler(autoModeService: AutoModeServiceCompat) {
   return async (req: Request, res: Response): Promise<void> => {
     try {
       const { projectPath, featureId } = req.body as {

apps/server/src/routes/auto-mode/routes/follow-up-feature.ts

@@ -3,13 +3,13 @@
  */
 
 import type { Request, Response } from 'express';
-import type { AutoModeService } from '../../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../../services/auto-mode/index.js';
 import { createLogger } from '@automaker/utils';
 import { getErrorMessage, logError } from '../common.js';
 
 const logger = createLogger('AutoMode');
 
-export function createFollowUpFeatureHandler(autoModeService: AutoModeService) {
+export function createFollowUpFeatureHandler(autoModeService: AutoModeServiceCompat) {
   return async (req: Request, res: Response): Promise<void> => {
     try {
       const { projectPath, featureId, prompt, imagePaths, useWorktrees } = req.body as {
@@ -30,16 +30,12 @@ export function createFollowUpFeatureHandler(autoModeService: AutoModeService) {
 
       // Start follow-up in background
       // followUpFeature derives workDir from feature.branchName
+      // Default to false to match run-feature/resume-feature behavior.
+      // Worktrees should only be used when explicitly enabled by the user.
       autoModeService
-        // Default to false to match run-feature/resume-feature behavior.
-        // Worktrees should only be used when explicitly enabled by the user.
         .followUpFeature(projectPath, featureId, prompt, imagePaths, useWorktrees ?? false)
         .catch((error) => {
           logger.error(`[AutoMode] Follow up feature ${featureId} error:`, error);
-        })
-        .finally(() => {
-          // Release the starting slot when follow-up completes (success or error)
-          // Note: The feature should be in runningFeatures by this point
         });
 
       res.json({ success: true });

apps/server/src/routes/auto-mode/routes/reconcile.ts

@@ -0,0 +1,53 @@
+/**
+ * Reconcile Feature States Handler
+ *
+ * On-demand endpoint to reconcile all feature states for a project.
+ * Resets features stuck in transient states (in_progress, interrupted, pipeline_*)
+ * back to resting states (ready/backlog) and emits events to update the UI.
+ *
+ * This is useful when:
+ * - The UI reconnects after a server restart
+ * - A client detects stale feature states
+ * - An admin wants to force-reset stuck features
+ */
+
+import type { Request, Response } from 'express';
+import { createLogger } from '@automaker/utils';
+import type { AutoModeServiceCompat } from '../../../services/auto-mode/index.js';
+
+const logger = createLogger('ReconcileFeatures');
+
+interface ReconcileRequest {
+  projectPath: string;
+}
+
+export function createReconcileHandler(autoModeService: AutoModeServiceCompat) {
+  return async (req: Request, res: Response): Promise<void> => {
+    const { projectPath } = req.body as ReconcileRequest;
+
+    if (!projectPath) {
+      res.status(400).json({ error: 'Project path is required' });
+      return;
+    }
+
+    logger.info(`Reconciling feature states for ${projectPath}`);
+
+    try {
+      const reconciledCount = await autoModeService.reconcileFeatureStates(projectPath);
+
+      res.json({
+        success: true,
+        reconciledCount,
+        message:
+          reconciledCount > 0
+            ? `Reconciled ${reconciledCount} feature(s)`
+            : 'No features needed reconciliation',
+      });
+    } catch (error) {
+      logger.error('Error reconciling feature states:', error);
+      res.status(500).json({
+        error: error instanceof Error ? error.message : 'Unknown error',
+      });
+    }
+  };
+}

apps/server/src/routes/auto-mode/routes/resume-feature.ts

@@ -3,13 +3,13 @@
  */
 
 import type { Request, Response } from 'express';
-import type { AutoModeService } from '../../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../../services/auto-mode/index.js';
 import { createLogger } from '@automaker/utils';
 import { getErrorMessage, logError } from '../common.js';
 
 const logger = createLogger('AutoMode');
 
-export function createResumeFeatureHandler(autoModeService: AutoModeService) {
+export function createResumeFeatureHandler(autoModeService: AutoModeServiceCompat) {
   return async (req: Request, res: Response): Promise<void> => {
     try {
       const { projectPath, featureId, useWorktrees } = req.body as {

apps/server/src/routes/auto-mode/routes/resume-interrupted.ts

@@ -7,7 +7,7 @@
 
 import type { Request, Response } from 'express';
 import { createLogger } from '@automaker/utils';
-import type { AutoModeService } from '../../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../../services/auto-mode/index.js';
 
 const logger = createLogger('ResumeInterrupted');
 
@@ -15,7 +15,7 @@ interface ResumeInterruptedRequest {
   projectPath: string;
 }
 
-export function createResumeInterruptedHandler(autoModeService: AutoModeService) {
+export function createResumeInterruptedHandler(autoModeService: AutoModeServiceCompat) {
   return async (req: Request, res: Response): Promise<void> => {
     const { projectPath } = req.body as ResumeInterruptedRequest;
 
@@ -28,6 +28,7 @@ export function createResumeInterruptedHandler(autoModeService: AutoModeService)
 
     try {
       await autoModeService.resumeInterruptedFeatures(projectPath);
+
       res.json({
         success: true,
         message: 'Resume check completed',

apps/server/src/routes/auto-mode/routes/run-feature.ts

@@ -3,13 +3,13 @@
  */
 
 import type { Request, Response } from 'express';
-import type { AutoModeService } from '../../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../../services/auto-mode/index.js';
 import { createLogger } from '@automaker/utils';
 import { getErrorMessage, logError } from '../common.js';
 
 const logger = createLogger('AutoMode');
 
-export function createRunFeatureHandler(autoModeService: AutoModeService) {
+export function createRunFeatureHandler(autoModeService: AutoModeServiceCompat) {
   return async (req: Request, res: Response): Promise<void> => {
     try {
       const { projectPath, featureId, useWorktrees } = req.body as {
@@ -50,10 +50,6 @@ export function createRunFeatureHandler(autoModeService: AutoModeService) {
         .executeFeature(projectPath, featureId, useWorktrees ?? false, false)
         .catch((error) => {
           logger.error(`Feature ${featureId} error:`, error);
-        })
-        .finally(() => {
-          // Release the starting slot when execution completes (success or error)
-          // Note: The feature should be in runningFeatures by this point
         });
 
       res.json({ success: true });

apps/server/src/routes/auto-mode/routes/start.ts

@@ -3,13 +3,13 @@
  */
 
 import type { Request, Response } from 'express';
-import type { AutoModeService } from '../../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../../services/auto-mode/index.js';
 import { createLogger } from '@automaker/utils';
 import { getErrorMessage, logError } from '../common.js';
 
 const logger = createLogger('AutoMode');
 
-export function createStartHandler(autoModeService: AutoModeService) {
+export function createStartHandler(autoModeService: AutoModeServiceCompat) {
   return async (req: Request, res: Response): Promise<void> => {
     try {
       const { projectPath, branchName, maxConcurrency } = req.body as {

apps/server/src/routes/auto-mode/routes/status.ts

@@ -6,10 +6,13 @@
  */
 
 import type { Request, Response } from 'express';
-import type { AutoModeService } from '../../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../../services/auto-mode/index.js';
 import { getErrorMessage, logError } from '../common.js';
 
-export function createStatusHandler(autoModeService: AutoModeService) {
+/**
+ * Create status handler.
+ */
+export function createStatusHandler(autoModeService: AutoModeServiceCompat) {
   return async (req: Request, res: Response): Promise<void> => {
     try {
       const { projectPath, branchName } = req.body as {
@@ -21,7 +24,8 @@ export function createStatusHandler(autoModeService: AutoModeService) {
       if (projectPath) {
         // Normalize branchName: undefined becomes null
         const normalizedBranchName = branchName ?? null;
-        const projectStatus = autoModeService.getStatusForProject(
+
+        const projectStatus = await autoModeService.getStatusForProject(
           projectPath,
           normalizedBranchName
         );
@@ -38,7 +42,7 @@ export function createStatusHandler(autoModeService: AutoModeService) {
         return;
       }
 
-      // Fall back to global status for backward compatibility
+      // Global status for backward compatibility
       const status = autoModeService.getStatus();
       const activeProjects = autoModeService.getActiveAutoLoopProjects();
       const activeWorktrees = autoModeService.getActiveAutoLoopWorktrees();

apps/server/src/routes/auto-mode/routes/stop-feature.ts

@@ -3,10 +3,10 @@
  */
 
 import type { Request, Response } from 'express';
-import type { AutoModeService } from '../../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../../services/auto-mode/index.js';
 import { getErrorMessage, logError } from '../common.js';
 
-export function createStopFeatureHandler(autoModeService: AutoModeService) {
+export function createStopFeatureHandler(autoModeService: AutoModeServiceCompat) {
   return async (req: Request, res: Response): Promise<void> => {
     try {
       const { featureId } = req.body as { featureId: string };

apps/server/src/routes/auto-mode/routes/stop.ts

@@ -3,13 +3,13 @@
  */
 
 import type { Request, Response } from 'express';
-import type { AutoModeService } from '../../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../../services/auto-mode/index.js';
 import { createLogger } from '@automaker/utils';
 import { getErrorMessage, logError } from '../common.js';
 
 const logger = createLogger('AutoMode');
 
-export function createStopHandler(autoModeService: AutoModeService) {
+export function createStopHandler(autoModeService: AutoModeServiceCompat) {
   return async (req: Request, res: Response): Promise<void> => {
     try {
       const { projectPath, branchName } = req.body as {

apps/server/src/routes/auto-mode/routes/verify-feature.ts

@@ -3,10 +3,10 @@
  */
 
 import type { Request, Response } from 'express';
-import type { AutoModeService } from '../../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../../services/auto-mode/index.js';
 import { getErrorMessage, logError } from '../common.js';
 
-export function createVerifyFeatureHandler(autoModeService: AutoModeService) {
+export function createVerifyFeatureHandler(autoModeService: AutoModeServiceCompat) {
   return async (req: Request, res: Response): Promise<void> => {
     try {
       const { projectPath, featureId } = req.body as {

apps/server/src/routes/enhance-prompt/routes/enhance.ts

@@ -10,14 +10,23 @@ import type { Request, Response } from 'express';
 import { createLogger } from '@automaker/utils';
 import { resolveModelString } from '@automaker/model-resolver';
 import { CLAUDE_MODEL_MAP, type ThinkingLevel } from '@automaker/types';
+import { getAppSpecPath } from '@automaker/platform';
 import { simpleQuery } from '../../../providers/simple-query-service.js';
 import type { SettingsService } from '../../../services/settings-service.js';
 import { getPromptCustomization, getProviderByModelId } from '../../../lib/settings-helpers.js';
+import { FeatureLoader } from '../../../services/feature-loader.js';
+import * as secureFs from '../../../lib/secure-fs.js';
 import {
   buildUserPrompt,
   isValidEnhancementMode,
   type EnhancementMode,
 } from '../../../lib/enhancement-prompts.js';
+import {
+  extractTechnologyStack,
+  extractXmlElements,
+  extractXmlSection,
+  unescapeXml,
+} from '../../../lib/xml-extractor.js';
 
 const logger = createLogger('EnhancePrompt');
 
@@ -53,6 +62,66 @@ interface EnhanceErrorResponse {
   error: string;
 }
 
+async function buildProjectContext(projectPath: string): Promise<string | null> {
+  const contextBlocks: string[] = [];
+
+  try {
+    const appSpecPath = getAppSpecPath(projectPath);
+    const specContent = (await secureFs.readFile(appSpecPath, 'utf-8')) as string;
+
+    const projectName = extractXmlSection(specContent, 'project_name');
+    const overview = extractXmlSection(specContent, 'overview');
+    const techStack = extractTechnologyStack(specContent);
+    const coreSection = extractXmlSection(specContent, 'core_capabilities');
+    const coreCapabilities = coreSection ? extractXmlElements(coreSection, 'capability') : [];
+
+    const summaryLines: string[] = [];
+    if (projectName) {
+      summaryLines.push(`Name: ${unescapeXml(projectName.trim())}`);
+    }
+    if (overview) {
+      summaryLines.push(`Overview: ${unescapeXml(overview.trim())}`);
+    }
+    if (techStack.length > 0) {
+      summaryLines.push(`Tech Stack: ${techStack.join(', ')}`);
+    }
+    if (coreCapabilities.length > 0) {
+      summaryLines.push(`Core Capabilities: ${coreCapabilities.slice(0, 10).join(', ')}`);
+    }
+
+    if (summaryLines.length > 0) {
+      contextBlocks.push(`PROJECT CONTEXT:\n${summaryLines.map((line) => `- ${line}`).join('\n')}`);
+    }
+  } catch (error) {
+    logger.debug('No app_spec.txt context available for enhancement', error);
+  }
+
+  try {
+    const featureLoader = new FeatureLoader();
+    const features = await featureLoader.getAll(projectPath);
+    const featureTitles = features
+      .map((feature) => feature.title || feature.name || feature.id)
+      .filter((title) => Boolean(title));
+
+    if (featureTitles.length > 0) {
+      const listed = featureTitles.slice(0, 30).map((title) => `- ${title}`);
+      contextBlocks.push(
+        `EXISTING FEATURES (avoid duplicates):\n${listed.join('\n')}${
+          featureTitles.length > 30 ? '\n- ...' : ''
+        }`
+      );
+    }
+  } catch (error) {
+    logger.debug('Failed to load existing features for enhancement context', error);
+  }
+
+  if (contextBlocks.length === 0) {
+    return null;
+  }
+
+  return contextBlocks.join('\n\n');
+}
+
 /**
  * Create the enhance request handler
  *
@@ -122,6 +191,10 @@ export function createEnhanceHandler(
 
       // Build the user prompt with few-shot examples
       const userPrompt = buildUserPrompt(validMode, trimmedText, true);
+      const projectContext = projectPath ? await buildProjectContext(projectPath) : null;
+      if (projectContext) {
+        logger.debug('Including project context in enhancement prompt');
+      }
 
       // Check if the model is a provider model (like "GLM-4.5-Air")
       // If so, get the provider config and resolved Claude model
@@ -146,18 +219,21 @@ export function createEnhanceHandler(
         }
       }
 
-      // Resolve the model - use provider resolved model, passed model, or default to sonnet
-      const resolvedModel =
-        providerResolvedModel || resolveModelString(model, CLAUDE_MODEL_MAP.sonnet);
+      // Resolve the model for API call.
+      // CRITICAL: For custom providers (GLM, MiniMax), pass the provider's model ID (e.g. "GLM-4.7")
+      // to the API, NOT the resolved Claude model - otherwise we get "model not found"
+      const modelForApi = claudeCompatibleProvider
+        ? model
+        : providerResolvedModel || resolveModelString(model, CLAUDE_MODEL_MAP.sonnet);
 
-      logger.debug(`Using model: ${resolvedModel}`);
+      logger.debug(`Using model: ${modelForApi}`);
 
       // Use simpleQuery - provider abstraction handles routing to correct provider
       // The system prompt is combined with user prompt since some providers
       // don't have a separate system prompt concept
       const result = await simpleQuery({
-        prompt: `${systemPrompt}\n\n${userPrompt}`,
-        model: resolvedModel,
+        prompt: [systemPrompt, projectContext, userPrompt].filter(Boolean).join('\n\n'),
+        model: modelForApi,
         cwd: process.cwd(), // Enhancement doesn't need a specific working directory
         maxTurns: 1,
         allowedTools: [],

apps/server/src/routes/features/index.ts

@@ -5,7 +5,7 @@
 import { Router } from 'express';
 import { FeatureLoader } from '../../services/feature-loader.js';
 import type { SettingsService } from '../../services/settings-service.js';
-import type { AutoModeService } from '../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../services/auto-mode/index.js';
 import type { EventEmitter } from '../../lib/events.js';
 import { validatePathParams } from '../../middleware/validate-paths.js';
 import { createListHandler } from './routes/list.js';
@@ -24,7 +24,7 @@ export function createFeaturesRoutes(
   featureLoader: FeatureLoader,
   settingsService?: SettingsService,
   events?: EventEmitter,
-  autoModeService?: AutoModeService
+  autoModeService?: AutoModeServiceCompat
 ): Router {
   const router = Router();
 

apps/server/src/routes/features/routes/create.ts

@@ -24,19 +24,6 @@ export function createCreateHandler(featureLoader: FeatureLoader, events?: Event
         return;
       }
 
-      // Check for duplicate title if title is provided
-      if (feature.title && feature.title.trim()) {
-        const duplicate = await featureLoader.findDuplicateTitle(projectPath, feature.title);
-        if (duplicate) {
-          res.status(409).json({
-            success: false,
-            error: `A feature with title "${feature.title}" already exists`,
-            duplicateFeatureId: duplicate.id,
-          });
-          return;
-        }
-      }
-
       const created = await featureLoader.create(projectPath, feature);
 
       // Emit feature_created event for hooks

apps/server/src/routes/features/routes/list.ts

@@ -7,13 +7,16 @@
 
 import type { Request, Response } from 'express';
 import { FeatureLoader } from '../../../services/feature-loader.js';
-import type { AutoModeService } from '../../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../../services/auto-mode/index.js';
 import { getErrorMessage, logError } from '../common.js';
 import { createLogger } from '@automaker/utils';
 
 const logger = createLogger('FeaturesListRoute');
 
-export function createListHandler(featureLoader: FeatureLoader, autoModeService?: AutoModeService) {
+export function createListHandler(
+  featureLoader: FeatureLoader,
+  autoModeService?: AutoModeServiceCompat
+) {
   return async (req: Request, res: Response): Promise<void> => {
     try {
       const { projectPath } = req.body as { projectPath: string };
@@ -30,18 +33,23 @@ export function createListHandler(featureLoader: FeatureLoader, autoModeService?
       // We don't await this to keep the list response fast
       // Note: detectOrphanedFeatures handles errors internally and always resolves
       if (autoModeService) {
-        autoModeService.detectOrphanedFeatures(projectPath).then((orphanedFeatures) => {
-          if (orphanedFeatures.length > 0) {
-            logger.info(
-              `[ProjectLoad] Detected ${orphanedFeatures.length} orphaned feature(s) in ${projectPath}`
-            );
-            for (const { feature, missingBranch } of orphanedFeatures) {
+        autoModeService
+          .detectOrphanedFeatures(projectPath)
+          .then((orphanedFeatures) => {
+            if (orphanedFeatures.length > 0) {
               logger.info(
-                `[ProjectLoad] Orphaned: ${feature.title || feature.id} - branch "${missingBranch}" no longer exists`
+                `[ProjectLoad] Detected ${orphanedFeatures.length} orphaned feature(s) in ${projectPath}`
               );
+              for (const { feature, missingBranch } of orphanedFeatures) {
+                logger.info(
+                  `[ProjectLoad] Orphaned: ${feature.title || feature.id} - branch "${missingBranch}" no longer exists`
+                );
+              }
             }
-          }
-        });
+          })
+          .catch((error) => {
+            logger.warn(`[ProjectLoad] Orphan detection failed for ${projectPath}:`, error);
+          });
       }
 
       res.json({ success: true, features });

apps/server/src/routes/features/routes/update.ts

@@ -40,23 +40,6 @@ export function createUpdateHandler(featureLoader: FeatureLoader) {
         return;
       }
 
-      // Check for duplicate title if title is being updated
-      if (updates.title && updates.title.trim()) {
-        const duplicate = await featureLoader.findDuplicateTitle(
-          projectPath,
-          updates.title,
-          featureId // Exclude the current feature from duplicate check
-        );
-        if (duplicate) {
-          res.status(409).json({
-            success: false,
-            error: `A feature with title "${updates.title}" already exists`,
-            duplicateFeatureId: duplicate.id,
-          });
-          return;
-        }
-      }
-
       // Get the current feature to detect status changes
       const currentFeature = await featureLoader.get(projectPath, featureId);
       const previousStatus = currentFeature?.status as FeatureStatus | undefined;

apps/server/src/routes/fs/routes/save-image.ts

@@ -7,6 +7,7 @@ import * as secureFs from '../../../lib/secure-fs.js';
 import path from 'path';
 import { getErrorMessage, logError } from '../common.js';
 import { getImagesDir } from '@automaker/platform';
+import { sanitizeFilename } from '@automaker/utils';
 
 export function createSaveImageHandler() {
   return async (req: Request, res: Response): Promise<void> => {
@@ -39,7 +40,7 @@ export function createSaveImageHandler() {
       // Generate unique filename with timestamp
       const timestamp = Date.now();
       const ext = path.extname(filename) || '.png';
-      const baseName = path.basename(filename, ext);
+      const baseName = sanitizeFilename(path.basename(filename, ext), 'image');
       const uniqueFilename = `${baseName}-${timestamp}${ext}`;
       const filePath = path.join(imagesDir, uniqueFilename);
 

apps/server/src/routes/github/routes/validate-issue.ts

@@ -25,7 +25,7 @@ import {
   isOpencodeModel,
   supportsStructuredOutput,
 } from '@automaker/types';
-import { resolvePhaseModel } from '@automaker/model-resolver';
+import { resolvePhaseModel, resolveModelString } from '@automaker/model-resolver';
 import { extractJson } from '../../../lib/json-extractor.js';
 import { writeValidation } from '../../../lib/validation-storage.js';
 import { streamingQuery } from '../../../providers/simple-query-service.js';
@@ -188,8 +188,12 @@ ${basePrompt}`;
       }
     }
 
-    // Use provider resolved model if available, otherwise use original model
-    const effectiveModel = providerResolvedModel || (model as string);
+    // CRITICAL: For custom providers (GLM, MiniMax), pass the provider's model ID (e.g. "GLM-4.7")
+    // to the API, NOT the resolved Claude model - otherwise we get "model not found"
+    // For standard Claude models, resolve aliases (e.g., 'opus' -> 'claude-opus-4-20250514')
+    const effectiveModel = claudeCompatibleProvider
+      ? (model as string)
+      : providerResolvedModel || resolveModelString(model as string);
     logger.info(`Using model: ${effectiveModel}`);
 
     // Use streamingQuery with event callbacks

apps/server/src/routes/projects/index.ts

@@ -4,14 +4,14 @@
 
 import { Router } from 'express';
 import type { FeatureLoader } from '../../services/feature-loader.js';
-import type { AutoModeService } from '../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../services/auto-mode/index.js';
 import type { SettingsService } from '../../services/settings-service.js';
 import type { NotificationService } from '../../services/notification-service.js';
 import { createOverviewHandler } from './routes/overview.js';
 
 export function createProjectsRoutes(
   featureLoader: FeatureLoader,
-  autoModeService: AutoModeService,
+  autoModeService: AutoModeServiceCompat,
   settingsService: SettingsService,
   notificationService: NotificationService
 ): Router {

apps/server/src/routes/projects/routes/overview.ts

@@ -9,7 +9,11 @@
 
 import type { Request, Response } from 'express';
 import type { FeatureLoader } from '../../../services/feature-loader.js';
-import type { AutoModeService } from '../../../services/auto-mode-service.js';
+import type {
+  AutoModeServiceCompat,
+  RunningAgentInfo,
+  ProjectAutoModeStatus,
+} from '../../../services/auto-mode/index.js';
 import type { SettingsService } from '../../../services/settings-service.js';
 import type { NotificationService } from '../../../services/notification-service.js';
 import type {
@@ -147,7 +151,7 @@ function getLastActivityAt(features: Feature[]): string | undefined {
 
 export function createOverviewHandler(
   featureLoader: FeatureLoader,
-  autoModeService: AutoModeService,
+  autoModeService: AutoModeServiceCompat,
   settingsService: SettingsService,
   notificationService: NotificationService
 ) {
@@ -158,7 +162,7 @@ export function createOverviewHandler(
       const projectRefs: ProjectRef[] = settings.projects || [];
 
       // Get all running agents once to count live running features per project
-      const allRunningAgents = await autoModeService.getRunningAgents();
+      const allRunningAgents: RunningAgentInfo[] = await autoModeService.getRunningAgents();
 
       // Collect project statuses in parallel
       const projectStatusPromises = projectRefs.map(async (projectRef): Promise<ProjectStatus> => {
@@ -169,7 +173,10 @@ export function createOverviewHandler(
           const totalFeatures = features.length;
 
           // Get auto-mode status for this project (main worktree, branchName = null)
-          const autoModeStatus = autoModeService.getStatusForProject(projectRef.path, null);
+          const autoModeStatus: ProjectAutoModeStatus = await autoModeService.getStatusForProject(
+            projectRef.path,
+            null
+          );
           const isAutoModeRunning = autoModeStatus.isAutoLoopRunning;
 
           // Count live running features for this project (across all branches)

apps/server/src/routes/running-agents/index.ts

@@ -3,10 +3,10 @@
  */
 
 import { Router } from 'express';
-import type { AutoModeService } from '../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../services/auto-mode/index.js';
 import { createIndexHandler } from './routes/index.js';
 
-export function createRunningAgentsRoutes(autoModeService: AutoModeService): Router {
+export function createRunningAgentsRoutes(autoModeService: AutoModeServiceCompat): Router {
   const router = Router();
 
   router.get('/', createIndexHandler(autoModeService));

apps/server/src/routes/running-agents/routes/index.ts

@@ -3,16 +3,17 @@
  */
 
 import type { Request, Response } from 'express';
-import type { AutoModeService } from '../../../services/auto-mode-service.js';
+import type { AutoModeServiceCompat } from '../../../services/auto-mode/index.js';
 import { getBacklogPlanStatus, getRunningDetails } from '../../backlog-plan/common.js';
 import { getAllRunningGenerations } from '../../app-spec/common.js';
 import path from 'path';
 import { getErrorMessage, logError } from '../common.js';
 
-export function createIndexHandler(autoModeService: AutoModeService) {
+export function createIndexHandler(autoModeService: AutoModeServiceCompat) {
   return async (_req: Request, res: Response): Promise<void> => {
     try {
       const runningAgents = [...(await autoModeService.getRunningAgents())];
+
       const backlogPlanStatus = getBacklogPlanStatus();
       const backlogPlanDetails = getRunningDetails();
 

apps/server/src/routes/settings/routes/update-global.ts

@@ -14,6 +14,7 @@ import type { GlobalSettings } from '../../../types/settings.js';
 import { getErrorMessage, logError, logger } from '../common.js';
 import { setLogLevel, LogLevel } from '@automaker/utils';
 import { setRequestLoggingEnabled } from '../../../index.js';
+import { getTerminalService } from '../../../services/terminal-service.js';
 
 /**
  * Map server log level string to LogLevel enum
@@ -57,6 +58,10 @@ export function createUpdateGlobalHandler(settingsService: SettingsService) {
         }, localStorageMigrated=${(updates as any).localStorageMigrated ?? 'n/a'}`
       );
 
+      // Get old settings to detect theme changes
+      const oldSettings = await settingsService.getGlobalSettings();
+      const oldTheme = oldSettings?.theme;
+
       logger.info('[SERVER_SETTINGS_UPDATE] Calling updateGlobalSettings...');
       const settings = await settingsService.updateGlobalSettings(updates);
       logger.info(
@@ -64,6 +69,37 @@ export function createUpdateGlobalHandler(settingsService: SettingsService) {
         settings.projects?.length ?? 0
       );
 
+      // Handle theme change - regenerate terminal RC files for all projects
+      if ('theme' in updates && updates.theme && updates.theme !== oldTheme) {
+        const terminalService = getTerminalService(settingsService);
+        const newTheme = updates.theme;
+
+        logger.info(
+          `[TERMINAL_CONFIG] Theme changed from ${oldTheme} to ${newTheme}, regenerating RC files`
+        );
+
+        // Regenerate RC files for all projects with terminal config enabled
+        const projects = settings.projects || [];
+        for (const project of projects) {
+          try {
+            const projectSettings = await settingsService.getProjectSettings(project.path);
+            // Check if terminal config is enabled (global or project-specific)
+            const terminalConfigEnabled =
+              projectSettings.terminalConfig?.enabled !== false &&
+              settings.terminalConfig?.enabled === true;
+
+            if (terminalConfigEnabled) {
+              await terminalService.onThemeChange(project.path, newTheme);
+              logger.info(`[TERMINAL_CONFIG] Regenerated RC files for project: ${project.name}`);
+            }
+          } catch (error) {
+            logger.warn(
+              `[TERMINAL_CONFIG] Failed to regenerate RC files for project ${project.name}: ${error}`
+            );
+          }
+        }
+      }
+
       // Apply server log level if it was updated
       if ('serverLogLevel' in updates && updates.serverLogLevel) {
         const level = LOG_LEVEL_MAP[updates.serverLogLevel];

apps/server/src/routes/setup/routes/verify-claude-auth.ts

@@ -6,6 +6,7 @@
 import type { Request, Response } from 'express';
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import { createLogger } from '@automaker/utils';
+import { getClaudeAuthIndicators } from '@automaker/platform';
 import { getApiKey } from '../common.js';
 import {
   createSecureAuthEnv,
@@ -320,9 +321,28 @@ export function createVerifyClaudeAuthHandler() {
         authMethod,
       });
 
+      // Determine specific auth type for success messages
+      const effectiveAuthMethod = authMethod ?? 'api_key';
+      let authType: 'oauth' | 'api_key' | 'cli' | undefined;
+      if (authenticated) {
+        if (effectiveAuthMethod === 'api_key') {
+          authType = 'api_key';
+        } else if (effectiveAuthMethod === 'cli') {
+          // Check if CLI auth is via OAuth (Claude Code subscription) or generic CLI
+          try {
+            const indicators = await getClaudeAuthIndicators();
+            authType = indicators.credentials?.hasOAuthToken ? 'oauth' : 'cli';
+          } catch {
+            // Fall back to generic CLI if credential check fails
+            authType = 'cli';
+          }
+        }
+      }
+
       res.json({
         success: true,
         authenticated,
+        authType,
         error: errorMessage || undefined,
       });
     } catch (error) {

apps/server/src/routes/worktree/index.ts

@@ -101,7 +101,12 @@ export function createWorktreeRoutes(
     requireValidWorktree,
     createPullHandler()
   );
-  router.post('/checkout-branch', requireValidWorktree, createCheckoutBranchHandler());
+  router.post(
+    '/checkout-branch',
+    validatePathParams('worktreePath'),
+    requireValidWorktree,
+    createCheckoutBranchHandler()
+  );
   router.post(
     '/list-branches',
     validatePathParams('worktreePath'),

apps/server/src/routes/worktree/routes/checkout-branch.ts

@@ -2,15 +2,15 @@
  * POST /checkout-branch endpoint - Create and checkout a new branch
  *
  * Note: Git repository validation (isGitRepo, hasCommits) is handled by
- * the requireValidWorktree middleware in index.ts
+ * the requireValidWorktree middleware in index.ts.
+ * Path validation (ALLOWED_ROOT_DIRECTORY) is handled by validatePathParams
+ * middleware in index.ts.
  */
 
 import type { Request, Response } from 'express';
-import { exec } from 'child_process';
-import { promisify } from 'util';
-import { getErrorMessage, logError } from '../common.js';
-
-const execAsync = promisify(exec);
+import path from 'path';
+import { stat } from 'fs/promises';
+import { getErrorMessage, logError, isValidBranchName, execGitCommand } from '../common.js';
 
 export function createCheckoutBranchHandler() {
   return async (req: Request, res: Response): Promise<void> => {
@@ -36,27 +36,47 @@ export function createCheckoutBranchHandler() {
         return;
       }
 
-      // Validate branch name (basic validation)
-      const invalidChars = /[\s~^:?*\[\\]/;
-      if (invalidChars.test(branchName)) {
+      // Validate branch name using shared allowlist: /^[a-zA-Z0-9._\-/]+$/
+      if (!isValidBranchName(branchName)) {
         res.status(400).json({
           success: false,
-          error: 'Branch name contains invalid characters',
+          error:
+            'Invalid branch name. Must contain only letters, numbers, dots, dashes, underscores, or slashes.',
         });
         return;
       }
 
-      // Get current branch for reference
-      const { stdout: currentBranchOutput } = await execAsync('git rev-parse --abbrev-ref HEAD', {
-        cwd: worktreePath,
-      });
+      // Resolve and validate worktreePath to prevent traversal attacks.
+      // The validatePathParams middleware checks against ALLOWED_ROOT_DIRECTORY,
+      // but we also resolve the path and verify it exists as a directory.
+      const resolvedPath = path.resolve(worktreePath);
+      try {
+        const stats = await stat(resolvedPath);
+        if (!stats.isDirectory()) {
+          res.status(400).json({
+            success: false,
+            error: 'worktreePath is not a directory',
+          });
+          return;
+        }
+      } catch {
+        res.status(400).json({
+          success: false,
+          error: 'worktreePath does not exist or is not accessible',
+        });
+        return;
+      }
+
+      // Get current branch for reference (using argument array to avoid shell injection)
+      const currentBranchOutput = await execGitCommand(
+        ['rev-parse', '--abbrev-ref', 'HEAD'],
+        resolvedPath
+      );
       const currentBranch = currentBranchOutput.trim();
 
       // Check if branch already exists
       try {
-        await execAsync(`git rev-parse --verify ${branchName}`, {
-          cwd: worktreePath,
-        });
+        await execGitCommand(['rev-parse', '--verify', branchName], resolvedPath);
         // Branch exists
         res.status(400).json({
           success: false,
@@ -67,10 +87,8 @@ export function createCheckoutBranchHandler() {
         // Branch doesn't exist, good to create
       }
 
-      // Create and checkout the new branch
-      await execAsync(`git checkout -b ${branchName}`, {
-        cwd: worktreePath,
-      });
+      // Create and checkout the new branch (using argument array to avoid shell injection)
+      await execGitCommand(['checkout', '-b', branchName], resolvedPath);
 
       res.json({
         success: true,

apps/server/src/routes/worktree/routes/init-git.ts

@@ -43,10 +43,14 @@ export function createInitGitHandler() {
         // .git doesn't exist, continue with initialization
       }
 
-      // Initialize git and create an initial empty commit
-      await execAsync(`git init && git commit --allow-empty -m "Initial commit"`, {
-        cwd: projectPath,
-      });
+      // Initialize git with 'main' as the default branch (matching GitHub's standard since 2020)
+      // and create an initial empty commit
+      await execAsync(
+        `git init --initial-branch=main && git commit --allow-empty -m "Initial commit"`,
+        {
+          cwd: projectPath,
+        }
+      );
 
       res.json({
         success: true,

apps/server/src/routes/worktree/routes/open-in-editor.ts

@@ -125,19 +125,14 @@ export function createOpenInEditorHandler() {
           `Failed to open in editor, falling back to file manager: ${getErrorMessage(editorError)}`
         );
 
-        try {
-          const result = await openInFileManager(worktreePath);
-          res.json({
-            success: true,
-            result: {
-              message: `Opened ${worktreePath} in ${result.editorName}`,
-              editorName: result.editorName,
-            },
-          });
-        } catch (fallbackError) {
-          // Both editor and file manager failed
-          throw fallbackError;
-        }
+        const result = await openInFileManager(worktreePath);
+        res.json({
+          success: true,
+          result: {
+            message: `Opened ${worktreePath} in ${result.editorName}`,
+            editorName: result.editorName,
+          },
+        });
       }
     } catch (error) {
       logError(error, 'Open in editor failed');

apps/server/src/routes/worktree/routes/switch-branch.ts

@@ -16,6 +16,21 @@ import { getErrorMessage, logError } from '../common.js';
 
 const execAsync = promisify(exec);
 
+function isUntrackedLine(line: string): boolean {
+  return line.startsWith('?? ');
+}
+
+function isExcludedWorktreeLine(line: string): boolean {
+  return line.includes('.worktrees/') || line.endsWith('.worktrees');
+}
+
+function isBlockingChangeLine(line: string): boolean {
+  if (!line.trim()) return false;
+  if (isExcludedWorktreeLine(line)) return false;
+  if (isUntrackedLine(line)) return false;
+  return true;
+}
+
 /**
  * Check if there are uncommitted changes in the working directory
  * Excludes .worktrees/ directory which is created by automaker
@@ -23,15 +38,7 @@ const execAsync = promisify(exec);
 async function hasUncommittedChanges(cwd: string): Promise<boolean> {
   try {
     const { stdout } = await execAsync('git status --porcelain', { cwd });
-    const lines = stdout
-      .trim()
-      .split('\n')
-      .filter((line) => {
-        if (!line.trim()) return false;
-        // Exclude .worktrees/ directory (created by automaker)
-        if (line.includes('.worktrees/') || line.endsWith('.worktrees')) return false;
-        return true;
-      });
+    const lines = stdout.trim().split('\n').filter(isBlockingChangeLine);
     return lines.length > 0;
   } catch {
     return false;
@@ -45,15 +52,7 @@ async function hasUncommittedChanges(cwd: string): Promise<boolean> {
 async function getChangesSummary(cwd: string): Promise<string> {
   try {
     const { stdout } = await execAsync('git status --short', { cwd });
-    const lines = stdout
-      .trim()
-      .split('\n')
-      .filter((line) => {
-        if (!line.trim()) return false;
-        // Exclude .worktrees/ directory
-        if (line.includes('.worktrees/') || line.endsWith('.worktrees')) return false;
-        return true;
-      });
+    const lines = stdout.trim().split('\n').filter(isBlockingChangeLine);
     if (lines.length === 0) return '';
     if (lines.length <= 5) return lines.join(', ');
     return `${lines.slice(0, 5).join(', ')} and ${lines.length - 5} more files`;

apps/server/src/services/agent-executor-types.ts

@@ -0,0 +1,83 @@
+/**
+ * AgentExecutor Types - Type definitions for agent execution
+ */
+
+import type {
+  PlanningMode,
+  ThinkingLevel,
+  ParsedTask,
+  ClaudeCompatibleProvider,
+  Credentials,
+} from '@automaker/types';
+import type { BaseProvider } from '../providers/base-provider.js';
+
+export interface AgentExecutionOptions {
+  workDir: string;
+  featureId: string;
+  prompt: string;
+  projectPath: string;
+  abortController: AbortController;
+  imagePaths?: string[];
+  model?: string;
+  planningMode?: PlanningMode;
+  requirePlanApproval?: boolean;
+  previousContent?: string;
+  systemPrompt?: string;
+  autoLoadClaudeMd?: boolean;
+  thinkingLevel?: ThinkingLevel;
+  branchName?: string | null;
+  credentials?: Credentials;
+  claudeCompatibleProvider?: ClaudeCompatibleProvider;
+  mcpServers?: Record<string, unknown>;
+  sdkOptions?: {
+    maxTurns?: number;
+    allowedTools?: string[];
+    systemPrompt?: string | { type: 'preset'; preset: 'claude_code'; append?: string };
+    settingSources?: Array<'user' | 'project' | 'local'>;
+  };
+  provider: BaseProvider;
+  effectiveBareModel: string;
+  specAlreadyDetected?: boolean;
+  existingApprovedPlanContent?: string;
+  persistedTasks?: ParsedTask[];
+}
+
+export interface AgentExecutionResult {
+  responseText: string;
+  specDetected: boolean;
+  tasksCompleted: number;
+  aborted: boolean;
+}
+
+export type WaitForApprovalFn = (
+  featureId: string,
+  projectPath: string
+) => Promise<{ approved: boolean; feedback?: string; editedPlan?: string }>;
+
+export type SaveFeatureSummaryFn = (
+  projectPath: string,
+  featureId: string,
+  summary: string
+) => Promise<void>;
+
+export type UpdateFeatureSummaryFn = (
+  projectPath: string,
+  featureId: string,
+  summary: string
+) => Promise<void>;
+
+export type BuildTaskPromptFn = (
+  task: ParsedTask,
+  allTasks: ParsedTask[],
+  taskIndex: number,
+  planContent: string,
+  taskPromptTemplate: string,
+  userFeedback?: string
+) => string;
+
+export interface AgentExecutorCallbacks {
+  waitForApproval: WaitForApprovalFn;
+  saveFeatureSummary: SaveFeatureSummaryFn;
+  updateFeatureSummary: UpdateFeatureSummaryFn;
+  buildTaskPrompt: BuildTaskPromptFn;
+}

apps/server/src/services/agent-executor.ts

@@ -0,0 +1,689 @@
+/**
+ * AgentExecutor - Core agent execution engine with streaming support
+ */
+
+import path from 'path';
+import type { ExecuteOptions, ParsedTask } from '@automaker/types';
+import { buildPromptWithImages, createLogger, isAuthenticationError } from '@automaker/utils';
+import { getFeatureDir } from '@automaker/platform';
+import * as secureFs from '../lib/secure-fs.js';
+import { TypedEventBus } from './typed-event-bus.js';
+import { FeatureStateManager } from './feature-state-manager.js';
+import { PlanApprovalService } from './plan-approval-service.js';
+import type { SettingsService } from './settings-service.js';
+import {
+  parseTasksFromSpec,
+  detectTaskStartMarker,
+  detectTaskCompleteMarker,
+  detectPhaseCompleteMarker,
+  detectSpecFallback,
+  extractSummary,
+} from './spec-parser.js';
+import { getPromptCustomization } from '../lib/settings-helpers.js';
+import type {
+  AgentExecutionOptions,
+  AgentExecutionResult,
+  AgentExecutorCallbacks,
+} from './agent-executor-types.js';
+
+// Re-export types for backward compatibility
+export type {
+  AgentExecutionOptions,
+  AgentExecutionResult,
+  WaitForApprovalFn,
+  SaveFeatureSummaryFn,
+  UpdateFeatureSummaryFn,
+  BuildTaskPromptFn,
+} from './agent-executor-types.js';
+
+const logger = createLogger('AgentExecutor');
+
+export class AgentExecutor {
+  private static readonly WRITE_DEBOUNCE_MS = 500;
+  private static readonly STREAM_HEARTBEAT_MS = 15_000;
+
+  constructor(
+    private eventBus: TypedEventBus,
+    private featureStateManager: FeatureStateManager,
+    private planApprovalService: PlanApprovalService,
+    private settingsService: SettingsService | null = null
+  ) {}
+
+  async execute(
+    options: AgentExecutionOptions,
+    callbacks: AgentExecutorCallbacks
+  ): Promise<AgentExecutionResult> {
+    const {
+      workDir,
+      featureId,
+      projectPath,
+      abortController,
+      branchName = null,
+      provider,
+      effectiveBareModel,
+      previousContent,
+      planningMode = 'skip',
+      requirePlanApproval = false,
+      specAlreadyDetected = false,
+      existingApprovedPlanContent,
+      persistedTasks,
+      credentials,
+      claudeCompatibleProvider,
+      mcpServers,
+      sdkOptions,
+    } = options;
+    const { content: promptContent } = await buildPromptWithImages(
+      options.prompt,
+      options.imagePaths,
+      workDir,
+      false
+    );
+    const executeOptions: ExecuteOptions = {
+      prompt: promptContent,
+      model: effectiveBareModel,
+      maxTurns: sdkOptions?.maxTurns,
+      cwd: workDir,
+      allowedTools: sdkOptions?.allowedTools as string[] | undefined,
+      abortController,
+      systemPrompt: sdkOptions?.systemPrompt,
+      settingSources: sdkOptions?.settingSources,
+      mcpServers:
+        mcpServers && Object.keys(mcpServers).length > 0
+          ? (mcpServers as Record<string, { command: string }>)
+          : undefined,
+      thinkingLevel: options.thinkingLevel,
+      credentials,
+      claudeCompatibleProvider,
+    };
+    const featureDirForOutput = getFeatureDir(projectPath, featureId);
+    const outputPath = path.join(featureDirForOutput, 'agent-output.md');
+    const rawOutputPath = path.join(featureDirForOutput, 'raw-output.jsonl');
+    const enableRawOutput =
+      process.env.AUTOMAKER_DEBUG_RAW_OUTPUT === 'true' ||
+      process.env.AUTOMAKER_DEBUG_RAW_OUTPUT === '1';
+    let responseText = previousContent
+      ? `${previousContent}\n\n---\n\n## Follow-up Session\n\n`
+      : '';
+    let specDetected = specAlreadyDetected,
+      tasksCompleted = 0,
+      aborted = false;
+    let writeTimeout: ReturnType<typeof setTimeout> | null = null,
+      rawOutputLines: string[] = [],
+      rawWriteTimeout: ReturnType<typeof setTimeout> | null = null;
+
+    const writeToFile = async (): Promise<void> => {
+      try {
+        await secureFs.mkdir(path.dirname(outputPath), { recursive: true });
+        await secureFs.writeFile(outputPath, responseText);
+      } catch (error) {
+        logger.error(`Failed to write agent output for ${featureId}:`, error);
+      }
+    };
+    const scheduleWrite = (): void => {
+      if (writeTimeout) clearTimeout(writeTimeout);
+      writeTimeout = setTimeout(() => writeToFile(), AgentExecutor.WRITE_DEBOUNCE_MS);
+    };
+    const appendRawEvent = (event: unknown): void => {
+      if (!enableRawOutput) return;
+      try {
+        rawOutputLines.push(JSON.stringify({ timestamp: new Date().toISOString(), event }));
+        if (rawWriteTimeout) clearTimeout(rawWriteTimeout);
+        rawWriteTimeout = setTimeout(async () => {
+          try {
+            await secureFs.mkdir(path.dirname(rawOutputPath), { recursive: true });
+            await secureFs.appendFile(rawOutputPath, rawOutputLines.join('\n') + '\n');
+            rawOutputLines = [];
+          } catch {
+            /* ignore */
+          }
+        }, AgentExecutor.WRITE_DEBOUNCE_MS);
+      } catch {
+        /* ignore */
+      }
+    };
+
+    const streamStartTime = Date.now();
+    let receivedAnyStreamMessage = false;
+    const streamHeartbeat = setInterval(() => {
+      if (!receivedAnyStreamMessage)
+        logger.info(
+          `Waiting for first model response for feature ${featureId} (${Math.round((Date.now() - streamStartTime) / 1000)}s elapsed)...`
+        );
+    }, AgentExecutor.STREAM_HEARTBEAT_MS);
+    const planningModeRequiresApproval =
+      planningMode === 'spec' ||
+      planningMode === 'full' ||
+      (planningMode === 'lite' && requirePlanApproval);
+    const requiresApproval = planningModeRequiresApproval && requirePlanApproval;
+
+    if (existingApprovedPlanContent && persistedTasks && persistedTasks.length > 0) {
+      const result = await this.executeTasksLoop(
+        options,
+        persistedTasks,
+        existingApprovedPlanContent,
+        responseText,
+        scheduleWrite,
+        callbacks
+      );
+      clearInterval(streamHeartbeat);
+      if (writeTimeout) clearTimeout(writeTimeout);
+      if (rawWriteTimeout) clearTimeout(rawWriteTimeout);
+      await writeToFile();
+      return {
+        responseText: result.responseText,
+        specDetected: true,
+        tasksCompleted: result.tasksCompleted,
+        aborted: result.aborted,
+      };
+    }
+
+    logger.info(`Starting stream for feature ${featureId}...`);
+
+    try {
+      const stream = provider.executeQuery(executeOptions);
+      streamLoop: for await (const msg of stream) {
+        receivedAnyStreamMessage = true;
+        appendRawEvent(msg);
+        if (abortController.signal.aborted) {
+          aborted = true;
+          throw new Error('Feature execution aborted');
+        }
+        if (msg.type === 'assistant' && msg.message?.content) {
+          for (const block of msg.message.content) {
+            if (block.type === 'text') {
+              const newText = block.text || '';
+              if (!newText) continue;
+              if (responseText.length > 0 && newText.length > 0) {
+                const endsWithSentence = /[.!?:]\s*$/.test(responseText),
+                  endsWithNewline = /\n\s*$/.test(responseText);
+                if (
+                  !endsWithNewline &&
+                  (endsWithSentence || /^[\n#\-*>]/.test(newText)) &&
+                  !/[a-zA-Z0-9]/.test(responseText.slice(-1))
+                )
+                  responseText += '\n\n';
+              }
+              responseText += newText;
+              // Check for authentication errors using provider-agnostic utility
+              if (block.text && isAuthenticationError(block.text))
+                throw new Error(
+                  'Authentication failed: Invalid or expired API key. Please check your API key configuration or re-authenticate with your provider.'
+                );
+              scheduleWrite();
+              const hasExplicitMarker = responseText.includes('[SPEC_GENERATED]'),
+                hasFallbackSpec = !hasExplicitMarker && detectSpecFallback(responseText);
+              if (
+                planningModeRequiresApproval &&
+                !specDetected &&
+                (hasExplicitMarker || hasFallbackSpec)
+              ) {
+                specDetected = true;
+                const planContent = hasExplicitMarker
+                  ? responseText.substring(0, responseText.indexOf('[SPEC_GENERATED]')).trim()
+                  : responseText.trim();
+                if (!hasExplicitMarker)
+                  logger.info(`Using fallback spec detection for feature ${featureId}`);
+                const result = await this.handleSpecGenerated(
+                  options,
+                  planContent,
+                  responseText,
+                  requiresApproval,
+                  scheduleWrite,
+                  callbacks
+                );
+                responseText = result.responseText;
+                tasksCompleted = result.tasksCompleted;
+                break streamLoop;
+              }
+              if (!specDetected)
+                this.eventBus.emitAutoModeEvent('auto_mode_progress', {
+                  featureId,
+                  branchName,
+                  content: block.text,
+                });
+            } else if (block.type === 'tool_use') {
+              this.eventBus.emitAutoModeEvent('auto_mode_tool', {
+                featureId,
+                branchName,
+                tool: block.name,
+                input: block.input,
+              });
+              if (responseText.length > 0 && !responseText.endsWith('\n')) responseText += '\n';
+              responseText += `\n🔧 Tool: ${block.name}\n`;
+              if (block.input) responseText += `Input: ${JSON.stringify(block.input, null, 2)}\n`;
+              scheduleWrite();
+            }
+          }
+        } else if (msg.type === 'error') {
+          throw new Error(msg.error || 'Unknown error');
+        } else if (msg.type === 'result' && msg.subtype === 'success') scheduleWrite();
+      }
+      await writeToFile();
+      if (enableRawOutput && rawOutputLines.length > 0) {
+        try {
+          await secureFs.mkdir(path.dirname(rawOutputPath), { recursive: true });
+          await secureFs.appendFile(rawOutputPath, rawOutputLines.join('\n') + '\n');
+        } catch {
+          /* ignore */
+        }
+      }
+    } finally {
+      clearInterval(streamHeartbeat);
+      if (writeTimeout) clearTimeout(writeTimeout);
+      if (rawWriteTimeout) clearTimeout(rawWriteTimeout);
+    }
+    return { responseText, specDetected, tasksCompleted, aborted };
+  }
+
+  private async executeTasksLoop(
+    options: AgentExecutionOptions,
+    tasks: ParsedTask[],
+    planContent: string,
+    initialResponseText: string,
+    scheduleWrite: () => void,
+    callbacks: AgentExecutorCallbacks,
+    userFeedback?: string
+  ): Promise<{ responseText: string; tasksCompleted: number; aborted: boolean }> {
+    const {
+      featureId,
+      projectPath,
+      abortController,
+      branchName = null,
+      provider,
+      sdkOptions,
+    } = options;
+    logger.info(`Starting task execution for feature ${featureId} with ${tasks.length} tasks`);
+    const taskPrompts = await getPromptCustomization(this.settingsService, '[AutoMode]');
+    let responseText = initialResponseText,
+      tasksCompleted = 0;
+
+    for (let taskIndex = 0; taskIndex < tasks.length; taskIndex++) {
+      const task = tasks[taskIndex];
+      if (task.status === 'completed') {
+        tasksCompleted++;
+        continue;
+      }
+      if (abortController.signal.aborted) return { responseText, tasksCompleted, aborted: true };
+      await this.featureStateManager.updateTaskStatus(
+        projectPath,
+        featureId,
+        task.id,
+        'in_progress'
+      );
+      this.eventBus.emitAutoModeEvent('auto_mode_task_started', {
+        featureId,
+        projectPath,
+        branchName,
+        taskId: task.id,
+        taskDescription: task.description,
+        taskIndex,
+        tasksTotal: tasks.length,
+      });
+      await this.featureStateManager.updateFeaturePlanSpec(projectPath, featureId, {
+        currentTaskId: task.id,
+      });
+      const taskPrompt = callbacks.buildTaskPrompt(
+        task,
+        tasks,
+        taskIndex,
+        planContent,
+        taskPrompts.taskExecution.taskPromptTemplate,
+        userFeedback
+      );
+      const taskStream = provider.executeQuery(
+        this.buildExecOpts(options, taskPrompt, Math.min(sdkOptions?.maxTurns ?? 100, 100))
+      );
+      let taskOutput = '',
+        taskStartDetected = false,
+        taskCompleteDetected = false;
+
+      for await (const msg of taskStream) {
+        if (msg.type === 'assistant' && msg.message?.content) {
+          for (const b of msg.message.content) {
+            if (b.type === 'text') {
+              const text = b.text || '';
+              taskOutput += text;
+              responseText += text;
+              this.eventBus.emitAutoModeEvent('auto_mode_progress', {
+                featureId,
+                branchName,
+                content: text,
+              });
+              scheduleWrite();
+              if (!taskStartDetected) {
+                const sid = detectTaskStartMarker(taskOutput);
+                if (sid) {
+                  taskStartDetected = true;
+                  await this.featureStateManager.updateTaskStatus(
+                    projectPath,
+                    featureId,
+                    sid,
+                    'in_progress'
+                  );
+                }
+              }
+              if (!taskCompleteDetected) {
+                const cid = detectTaskCompleteMarker(taskOutput);
+                if (cid) {
+                  taskCompleteDetected = true;
+                  await this.featureStateManager.updateTaskStatus(
+                    projectPath,
+                    featureId,
+                    cid,
+                    'completed'
+                  );
+                }
+              }
+              const pn = detectPhaseCompleteMarker(text);
+              if (pn !== null)
+                this.eventBus.emitAutoModeEvent('auto_mode_phase_complete', {
+                  featureId,
+                  projectPath,
+                  branchName,
+                  phaseNumber: pn,
+                });
+            } else if (b.type === 'tool_use')
+              this.eventBus.emitAutoModeEvent('auto_mode_tool', {
+                featureId,
+                branchName,
+                tool: b.name,
+                input: b.input,
+              });
+          }
+        } else if (msg.type === 'error')
+          throw new Error(msg.error || `Error during task ${task.id}`);
+        else if (msg.type === 'result' && msg.subtype === 'success') {
+          taskOutput += msg.result || '';
+          responseText += msg.result || '';
+        }
+      }
+      if (!taskCompleteDetected)
+        await this.featureStateManager.updateTaskStatus(
+          projectPath,
+          featureId,
+          task.id,
+          'completed'
+        );
+      tasksCompleted = taskIndex + 1;
+      this.eventBus.emitAutoModeEvent('auto_mode_task_complete', {
+        featureId,
+        projectPath,
+        branchName,
+        taskId: task.id,
+        tasksCompleted,
+        tasksTotal: tasks.length,
+      });
+      await this.featureStateManager.updateFeaturePlanSpec(projectPath, featureId, {
+        tasksCompleted,
+      });
+      if (task.phase) {
+        const next = tasks[taskIndex + 1];
+        if (!next || next.phase !== task.phase) {
+          const m = task.phase.match(/Phase\s*(\d+)/i);
+          if (m)
+            this.eventBus.emitAutoModeEvent('auto_mode_phase_complete', {
+              featureId,
+              projectPath,
+              branchName,
+              phaseNumber: parseInt(m[1], 10),
+            });
+        }
+      }
+    }
+    const summary = extractSummary(responseText);
+    if (summary) await callbacks.saveFeatureSummary(projectPath, featureId, summary);
+    return { responseText, tasksCompleted, aborted: false };
+  }
+
+  private async handleSpecGenerated(
+    options: AgentExecutionOptions,
+    planContent: string,
+    initialResponseText: string,
+    requiresApproval: boolean,
+    scheduleWrite: () => void,
+    callbacks: AgentExecutorCallbacks
+  ): Promise<{ responseText: string; tasksCompleted: number }> {
+    const {
+      workDir,
+      featureId,
+      projectPath,
+      abortController,
+      branchName = null,
+      planningMode = 'skip',
+      provider,
+      effectiveBareModel,
+      credentials,
+      claudeCompatibleProvider,
+      mcpServers,
+      sdkOptions,
+    } = options;
+    let responseText = initialResponseText,
+      parsedTasks = parseTasksFromSpec(planContent);
+    logger.info(`Parsed ${parsedTasks.length} tasks from spec for feature ${featureId}`);
+    await this.featureStateManager.updateFeaturePlanSpec(projectPath, featureId, {
+      status: 'generated',
+      content: planContent,
+      version: 1,
+      generatedAt: new Date().toISOString(),
+      reviewedByUser: false,
+      tasks: parsedTasks,
+      tasksTotal: parsedTasks.length,
+      tasksCompleted: 0,
+    });
+    const planSummary = extractSummary(planContent);
+    if (planSummary) await callbacks.updateFeatureSummary(projectPath, featureId, planSummary);
+    let approvedPlanContent = planContent,
+      userFeedback: string | undefined,
+      currentPlanContent = planContent,
+      planVersion = 1;
+
+    if (requiresApproval) {
+      let planApproved = false;
+      while (!planApproved) {
+        logger.info(
+          `Spec v${planVersion} generated for feature ${featureId}, waiting for approval`
+        );
+        this.eventBus.emitAutoModeEvent('plan_approval_required', {
+          featureId,
+          projectPath,
+          branchName,
+          planContent: currentPlanContent,
+          planningMode,
+          planVersion,
+        });
+        const approvalResult = await callbacks.waitForApproval(featureId, projectPath);
+        if (approvalResult.approved) {
+          planApproved = true;
+          userFeedback = approvalResult.feedback;
+          approvedPlanContent = approvalResult.editedPlan || currentPlanContent;
+          if (approvalResult.editedPlan) {
+            // Re-parse tasks from edited plan to ensure we execute the updated tasks
+            const editedTasks = parseTasksFromSpec(approvalResult.editedPlan);
+            parsedTasks = editedTasks;
+            await this.featureStateManager.updateFeaturePlanSpec(projectPath, featureId, {
+              content: approvalResult.editedPlan,
+              tasks: editedTasks,
+              tasksTotal: editedTasks.length,
+              tasksCompleted: 0,
+            });
+          }
+          this.eventBus.emitAutoModeEvent('plan_approved', {
+            featureId,
+            projectPath,
+            branchName,
+            hasEdits: !!approvalResult.editedPlan,
+            planVersion,
+          });
+        } else {
+          const hasFeedback = approvalResult.feedback?.trim().length,
+            hasEdits = approvalResult.editedPlan?.trim().length;
+          if (!hasFeedback && !hasEdits) throw new Error('Plan cancelled by user');
+          planVersion++;
+          this.eventBus.emitAutoModeEvent('plan_revision_requested', {
+            featureId,
+            projectPath,
+            branchName,
+            feedback: approvalResult.feedback,
+            hasEdits: !!hasEdits,
+            planVersion,
+          });
+          const revPrompts = await getPromptCustomization(this.settingsService, '[AutoMode]');
+          const taskEx =
+            planningMode === 'full'
+              ? '```tasks\n## Phase 1: Foundation\n- [ ] T001: [Description] | File: [path/to/file]\n```'
+              : '```tasks\n- [ ] T001: [Description] | File: [path/to/file]\n```';
+          let revPrompt = revPrompts.taskExecution.planRevisionTemplate
+            .replace(/\{\{planVersion\}\}/g, String(planVersion - 1))
+            .replace(
+              /\{\{previousPlan\}\}/g,
+              hasEdits ? approvalResult.editedPlan || currentPlanContent : currentPlanContent
+            )
+            .replace(
+              /\{\{userFeedback\}\}/g,
+              approvalResult.feedback || 'Please revise the plan based on the edits above.'
+            )
+            .replace(/\{\{planningMode\}\}/g, planningMode)
+            .replace(/\{\{taskFormatExample\}\}/g, taskEx);
+          await this.featureStateManager.updateFeaturePlanSpec(projectPath, featureId, {
+            status: 'generating',
+            version: planVersion,
+          });
+          let revText = '';
+          for await (const msg of provider.executeQuery(
+            this.buildExecOpts(options, revPrompt, sdkOptions?.maxTurns ?? 100)
+          )) {
+            if (msg.type === 'assistant' && msg.message?.content)
+              for (const b of msg.message.content)
+                if (b.type === 'text') {
+                  revText += b.text || '';
+                  this.eventBus.emitAutoModeEvent('auto_mode_progress', {
+                    featureId,
+                    branchName,
+                    content: b.text,
+                  });
+                }
+            if (msg.type === 'error') throw new Error(msg.error || 'Error during plan revision');
+            if (msg.type === 'result' && msg.subtype === 'success') revText += msg.result || '';
+          }
+          const mi = revText.indexOf('[SPEC_GENERATED]');
+          currentPlanContent = mi > 0 ? revText.substring(0, mi).trim() : revText.trim();
+          const revisedTasks = parseTasksFromSpec(currentPlanContent);
+          if (revisedTasks.length === 0 && (planningMode === 'spec' || planningMode === 'full'))
+            this.eventBus.emitAutoModeEvent('plan_revision_warning', {
+              featureId,
+              projectPath,
+              branchName,
+              planningMode,
+              warning: 'Revised plan missing tasks block',
+            });
+          await this.featureStateManager.updateFeaturePlanSpec(projectPath, featureId, {
+            status: 'generated',
+            content: currentPlanContent,
+            version: planVersion,
+            tasks: revisedTasks,
+            tasksTotal: revisedTasks.length,
+            tasksCompleted: 0,
+          });
+          parsedTasks = revisedTasks;
+          responseText += revText;
+        }
+      }
+    } else {
+      this.eventBus.emitAutoModeEvent('plan_auto_approved', {
+        featureId,
+        projectPath,
+        branchName,
+        planContent,
+        planningMode,
+      });
+    }
+    await this.featureStateManager.updateFeaturePlanSpec(projectPath, featureId, {
+      status: 'approved',
+      approvedAt: new Date().toISOString(),
+      reviewedByUser: requiresApproval,
+    });
+    let tasksCompleted = 0;
+    if (parsedTasks.length > 0) {
+      const r = await this.executeTasksLoop(
+        options,
+        parsedTasks,
+        approvedPlanContent,
+        responseText,
+        scheduleWrite,
+        callbacks,
+        userFeedback
+      );
+      responseText = r.responseText;
+      tasksCompleted = r.tasksCompleted;
+    } else {
+      const r = await this.executeSingleAgentContinuation(
+        options,
+        approvedPlanContent,
+        userFeedback,
+        responseText
+      );
+      responseText = r.responseText;
+    }
+    const summary = extractSummary(responseText);
+    if (summary) await callbacks.saveFeatureSummary(projectPath, featureId, summary);
+    return { responseText, tasksCompleted };
+  }
+
+  private buildExecOpts(o: AgentExecutionOptions, prompt: string, maxTurns?: number) {
+    return {
+      prompt,
+      model: o.effectiveBareModel,
+      maxTurns,
+      cwd: o.workDir,
+      allowedTools: o.sdkOptions?.allowedTools as string[] | undefined,
+      abortController: o.abortController,
+      thinkingLevel: o.thinkingLevel,
+      mcpServers:
+        o.mcpServers && Object.keys(o.mcpServers).length > 0
+          ? (o.mcpServers as Record<string, { command: string }>)
+          : undefined,
+      credentials: o.credentials,
+      claudeCompatibleProvider: o.claudeCompatibleProvider,
+    };
+  }
+
+  private async executeSingleAgentContinuation(
+    options: AgentExecutionOptions,
+    planContent: string,
+    userFeedback: string | undefined,
+    initialResponseText: string
+  ): Promise<{ responseText: string }> {
+    const { featureId, branchName = null, provider } = options;
+    logger.info(`No parsed tasks, using single-agent execution for feature ${featureId}`);
+    const prompts = await getPromptCustomization(this.settingsService, '[AutoMode]');
+    const contPrompt = prompts.taskExecution.continuationAfterApprovalTemplate
+      .replace(/\{\{userFeedback\}\}/g, userFeedback || '')
+      .replace(/\{\{approvedPlan\}\}/g, planContent);
+    let responseText = initialResponseText;
+    for await (const msg of provider.executeQuery(
+      this.buildExecOpts(options, contPrompt, options.sdkOptions?.maxTurns)
+    )) {
+      if (msg.type === 'assistant' && msg.message?.content)
+        for (const b of msg.message.content) {
+          if (b.type === 'text') {
+            responseText += b.text || '';
+            this.eventBus.emitAutoModeEvent('auto_mode_progress', {
+              featureId,
+              branchName,
+              content: b.text,
+            });
+          } else if (b.type === 'tool_use')
+            this.eventBus.emitAutoModeEvent('auto_mode_tool', {
+              featureId,
+              branchName,
+              tool: b.name,
+              input: b.input,
+            });
+        }
+      else if (msg.type === 'error')
+        throw new Error(msg.error || 'Unknown error during implementation');
+      else if (msg.type === 'result' && msg.subtype === 'success') responseText += msg.result || '';
+    }
+    return { responseText };
+  }
+}

apps/server/src/services/agent-service.ts

@@ -325,8 +325,9 @@ export class AgentService {
       const effectiveThinkingLevel = thinkingLevel ?? session.thinkingLevel;
       const effectiveReasoningEffort = reasoningEffort ?? session.reasoningEffort;
 
-      // When using a provider model, use the resolved Claude model (from mapsToClaudeModel)
-      // e.g., "GLM-4.5-Air" -> "claude-haiku-4-5"
+      // When using a custom provider (GLM, MiniMax), use resolved Claude model for SDK config
+      // (thinking level budgets, allowedTools) but we MUST pass the provider's model ID
+      // (e.g. "GLM-4.7") to the API - not "claude-sonnet-4-20250514" which causes "model not found"
       const modelForSdk = providerResolvedModel || model;
       const sessionModelForSdk = providerResolvedModel ? undefined : session.model;
 
@@ -387,10 +388,18 @@ export class AgentService {
       }
 
       // Get provider for this model (with prefix)
-      const provider = ProviderFactory.getProviderForModel(effectiveModel);
+      // When using custom provider (GLM, MiniMax), requestedModel routes to Claude provider
+      const modelForProvider = claudeCompatibleProvider
+        ? (requestedModel ?? effectiveModel)
+        : effectiveModel;
+      const provider = ProviderFactory.getProviderForModel(modelForProvider);
 
       // Strip provider prefix - providers should receive bare model IDs
-      const bareModel = stripProviderPrefix(effectiveModel);
+      // CRITICAL: For custom providers (GLM, MiniMax), pass the provider's model ID (e.g. "GLM-4.7")
+      // to the API, NOT the resolved Claude model - otherwise we get "model not found"
+      const bareModel: string = claudeCompatibleProvider
+        ? (requestedModel ?? effectiveModel)
+        : stripProviderPrefix(effectiveModel);
 
       // Build options for provider
       const options: ExecuteOptions = {

apps/server/src/services/auto-loop-coordinator.ts

@@ -0,0 +1,426 @@
+/**
+ * AutoLoopCoordinator - Manages the auto-mode loop lifecycle and failure tracking
+ */
+
+import type { Feature } from '@automaker/types';
+import { createLogger, classifyError } from '@automaker/utils';
+import type { TypedEventBus } from './typed-event-bus.js';
+import type { ConcurrencyManager } from './concurrency-manager.js';
+import type { SettingsService } from './settings-service.js';
+import { DEFAULT_MAX_CONCURRENCY } from '@automaker/types';
+
+const logger = createLogger('AutoLoopCoordinator');
+
+const CONSECUTIVE_FAILURE_THRESHOLD = 3;
+const FAILURE_WINDOW_MS = 60000;
+
+export interface AutoModeConfig {
+  maxConcurrency: number;
+  useWorktrees: boolean;
+  projectPath: string;
+  branchName: string | null;
+}
+
+export interface ProjectAutoLoopState {
+  abortController: AbortController;
+  config: AutoModeConfig;
+  isRunning: boolean;
+  consecutiveFailures: { timestamp: number; error: string }[];
+  pausedDueToFailures: boolean;
+  hasEmittedIdleEvent: boolean;
+  branchName: string | null;
+}
+
+/**
+ * Generate a unique key for a worktree auto-loop instance.
+ *
+ * When branchName is null, this represents the main worktree (uses '__main__' sentinel).
+ * The string 'main' is also normalized to '__main__' for consistency.
+ * Named branches always use their exact name.
+ */
+export function getWorktreeAutoLoopKey(projectPath: string, branchName: string | null): string {
+  const normalizedBranch = branchName === 'main' ? null : branchName;
+  return `${projectPath}::${normalizedBranch ?? '__main__'}`;
+}
+
+export type ExecuteFeatureFn = (
+  projectPath: string,
+  featureId: string,
+  useWorktrees: boolean,
+  isAutoMode: boolean
+) => Promise<void>;
+export type LoadPendingFeaturesFn = (
+  projectPath: string,
+  branchName: string | null
+) => Promise<Feature[]>;
+export type SaveExecutionStateFn = (
+  projectPath: string,
+  branchName: string | null,
+  maxConcurrency: number
+) => Promise<void>;
+export type ClearExecutionStateFn = (
+  projectPath: string,
+  branchName: string | null
+) => Promise<void>;
+export type ResetStuckFeaturesFn = (projectPath: string) => Promise<void>;
+export type IsFeatureFinishedFn = (feature: Feature) => boolean;
+
+export class AutoLoopCoordinator {
+  private autoLoopsByProject = new Map<string, ProjectAutoLoopState>();
+
+  constructor(
+    private eventBus: TypedEventBus,
+    private concurrencyManager: ConcurrencyManager,
+    private settingsService: SettingsService | null,
+    private executeFeatureFn: ExecuteFeatureFn,
+    private loadPendingFeaturesFn: LoadPendingFeaturesFn,
+    private saveExecutionStateFn: SaveExecutionStateFn,
+    private clearExecutionStateFn: ClearExecutionStateFn,
+    private resetStuckFeaturesFn: ResetStuckFeaturesFn,
+    private isFeatureFinishedFn: IsFeatureFinishedFn,
+    private isFeatureRunningFn: (featureId: string) => boolean
+  ) {}
+
+  /**
+   * Start the auto mode loop for a specific project/worktree (supports multiple concurrent projects and worktrees)
+   * @param projectPath - The project to start auto mode for
+   * @param branchName - The branch name for worktree scoping, null for main worktree
+   * @param maxConcurrency - Maximum concurrent features (default: DEFAULT_MAX_CONCURRENCY)
+   */
+  async startAutoLoopForProject(
+    projectPath: string,
+    branchName: string | null = null,
+    maxConcurrency?: number
+  ): Promise<number> {
+    const resolvedMaxConcurrency = await this.resolveMaxConcurrency(
+      projectPath,
+      branchName,
+      maxConcurrency
+    );
+
+    // Use worktree-scoped key
+    const worktreeKey = getWorktreeAutoLoopKey(projectPath, branchName);
+
+    // Check if this project/worktree already has an active autoloop
+    const existingState = this.autoLoopsByProject.get(worktreeKey);
+    if (existingState?.isRunning) {
+      const worktreeDesc = branchName ? `worktree ${branchName}` : 'main worktree';
+      throw new Error(
+        `Auto mode is already running for ${worktreeDesc} in project: ${projectPath}`
+      );
+    }
+
+    // Create new project/worktree autoloop state
+    const abortController = new AbortController();
+    const config: AutoModeConfig = {
+      maxConcurrency: resolvedMaxConcurrency,
+      useWorktrees: true,
+      projectPath,
+      branchName,
+    };
+
+    const projectState: ProjectAutoLoopState = {
+      abortController,
+      config,
+      isRunning: true,
+      consecutiveFailures: [],
+      pausedDueToFailures: false,
+      hasEmittedIdleEvent: false,
+      branchName,
+    };
+
+    this.autoLoopsByProject.set(worktreeKey, projectState);
+    try {
+      await this.resetStuckFeaturesFn(projectPath);
+    } catch {
+      /* ignore */
+    }
+    this.eventBus.emitAutoModeEvent('auto_mode_started', {
+      message: `Auto mode started with max ${resolvedMaxConcurrency} concurrent features`,
+      projectPath,
+      branchName,
+      maxConcurrency: resolvedMaxConcurrency,
+    });
+    await this.saveExecutionStateFn(projectPath, branchName, resolvedMaxConcurrency);
+    this.runAutoLoopForProject(worktreeKey).catch((error) => {
+      const errorInfo = classifyError(error);
+      this.eventBus.emitAutoModeEvent('auto_mode_error', {
+        error: errorInfo.message,
+        errorType: errorInfo.type,
+        projectPath,
+        branchName,
+      });
+    });
+    return resolvedMaxConcurrency;
+  }
+
+  private async runAutoLoopForProject(worktreeKey: string): Promise<void> {
+    const projectState = this.autoLoopsByProject.get(worktreeKey);
+    if (!projectState) return;
+    const { projectPath, branchName } = projectState.config;
+    let iterationCount = 0;
+
+    while (projectState.isRunning && !projectState.abortController.signal.aborted) {
+      iterationCount++;
+      try {
+        const runningCount = await this.getRunningCountForWorktree(projectPath, branchName);
+        if (runningCount >= projectState.config.maxConcurrency) {
+          await this.sleep(5000, projectState.abortController.signal);
+          continue;
+        }
+        const pendingFeatures = await this.loadPendingFeaturesFn(projectPath, branchName);
+        if (pendingFeatures.length === 0) {
+          if (runningCount === 0 && !projectState.hasEmittedIdleEvent) {
+            this.eventBus.emitAutoModeEvent('auto_mode_idle', {
+              message: 'No pending features - auto mode idle',
+              projectPath,
+              branchName,
+            });
+            projectState.hasEmittedIdleEvent = true;
+          }
+          await this.sleep(10000, projectState.abortController.signal);
+          continue;
+        }
+        const nextFeature = pendingFeatures.find(
+          (f) => !this.isFeatureRunningFn(f.id) && !this.isFeatureFinishedFn(f)
+        );
+        if (nextFeature) {
+          projectState.hasEmittedIdleEvent = false;
+          this.executeFeatureFn(
+            projectPath,
+            nextFeature.id,
+            projectState.config.useWorktrees,
+            true
+          ).catch((error) => {
+            const errorInfo = classifyError(error);
+            logger.error(`Auto-loop feature ${nextFeature.id} failed:`, errorInfo.message);
+            if (this.trackFailureAndCheckPauseForProject(projectPath, branchName, errorInfo)) {
+              this.signalShouldPauseForProject(projectPath, branchName, errorInfo);
+            }
+          });
+        }
+        await this.sleep(2000, projectState.abortController.signal);
+      } catch {
+        if (projectState.abortController.signal.aborted) break;
+        await this.sleep(5000, projectState.abortController.signal);
+      }
+    }
+    projectState.isRunning = false;
+  }
+
+  async stopAutoLoopForProject(
+    projectPath: string,
+    branchName: string | null = null
+  ): Promise<number> {
+    const worktreeKey = getWorktreeAutoLoopKey(projectPath, branchName);
+    const projectState = this.autoLoopsByProject.get(worktreeKey);
+    if (!projectState) return 0;
+    const wasRunning = projectState.isRunning;
+    projectState.isRunning = false;
+    projectState.abortController.abort();
+    await this.clearExecutionStateFn(projectPath, branchName);
+    if (wasRunning)
+      this.eventBus.emitAutoModeEvent('auto_mode_stopped', {
+        message: 'Auto mode stopped',
+        projectPath,
+        branchName,
+      });
+    this.autoLoopsByProject.delete(worktreeKey);
+    return await this.getRunningCountForWorktree(projectPath, branchName);
+  }
+
+  isAutoLoopRunningForProject(projectPath: string, branchName: string | null = null): boolean {
+    const worktreeKey = getWorktreeAutoLoopKey(projectPath, branchName);
+    const projectState = this.autoLoopsByProject.get(worktreeKey);
+    return projectState?.isRunning ?? false;
+  }
+
+  /**
+   * Get auto loop config for a specific project/worktree
+   * @param projectPath - The project path
+   * @param branchName - The branch name, or null for main worktree
+   */
+  getAutoLoopConfigForProject(
+    projectPath: string,
+    branchName: string | null = null
+  ): AutoModeConfig | null {
+    const worktreeKey = getWorktreeAutoLoopKey(projectPath, branchName);
+    const projectState = this.autoLoopsByProject.get(worktreeKey);
+    return projectState?.config ?? null;
+  }
+
+  /**
+   * Get all active auto loop worktrees with their project paths and branch names
+   */
+  getActiveWorktrees(): Array<{ projectPath: string; branchName: string | null }> {
+    const activeWorktrees: Array<{ projectPath: string; branchName: string | null }> = [];
+    for (const [, state] of this.autoLoopsByProject) {
+      if (state.isRunning) {
+        activeWorktrees.push({
+          projectPath: state.config.projectPath,
+          branchName: state.branchName,
+        });
+      }
+    }
+    return activeWorktrees;
+  }
+
+  getActiveProjects(): string[] {
+    const activeProjects = new Set<string>();
+    for (const [, state] of this.autoLoopsByProject) {
+      if (state.isRunning) activeProjects.add(state.config.projectPath);
+    }
+    return Array.from(activeProjects);
+  }
+
+  async getRunningCountForWorktree(
+    projectPath: string,
+    branchName: string | null
+  ): Promise<number> {
+    return this.concurrencyManager.getRunningCountForWorktree(projectPath, branchName);
+  }
+
+  trackFailureAndCheckPauseForProject(
+    projectPath: string,
+    branchNameOrError: string | null | { type: string; message: string },
+    errorInfo?: { type: string; message: string }
+  ): boolean {
+    // Support both old (projectPath, errorInfo) and new (projectPath, branchName, errorInfo) signatures
+    let branchName: string | null;
+    let actualErrorInfo: { type: string; message: string };
+    if (
+      typeof branchNameOrError === 'object' &&
+      branchNameOrError !== null &&
+      'type' in branchNameOrError
+    ) {
+      // Old signature: (projectPath, errorInfo)
+      branchName = null;
+      actualErrorInfo = branchNameOrError;
+    } else {
+      // New signature: (projectPath, branchName, errorInfo)
+      branchName = branchNameOrError;
+      actualErrorInfo = errorInfo!;
+    }
+    const projectState = this.autoLoopsByProject.get(
+      getWorktreeAutoLoopKey(projectPath, branchName)
+    );
+    if (!projectState) return false;
+    const now = Date.now();
+    projectState.consecutiveFailures.push({ timestamp: now, error: actualErrorInfo.message });
+    projectState.consecutiveFailures = projectState.consecutiveFailures.filter(
+      (f) => now - f.timestamp < FAILURE_WINDOW_MS
+    );
+    return (
+      projectState.consecutiveFailures.length >= CONSECUTIVE_FAILURE_THRESHOLD ||
+      actualErrorInfo.type === 'quota_exhausted' ||
+      actualErrorInfo.type === 'rate_limit'
+    );
+  }
+
+  signalShouldPauseForProject(
+    projectPath: string,
+    branchNameOrError: string | null | { type: string; message: string },
+    errorInfo?: { type: string; message: string }
+  ): void {
+    // Support both old (projectPath, errorInfo) and new (projectPath, branchName, errorInfo) signatures
+    let branchName: string | null;
+    let actualErrorInfo: { type: string; message: string };
+    if (
+      typeof branchNameOrError === 'object' &&
+      branchNameOrError !== null &&
+      'type' in branchNameOrError
+    ) {
+      branchName = null;
+      actualErrorInfo = branchNameOrError;
+    } else {
+      branchName = branchNameOrError;
+      actualErrorInfo = errorInfo!;
+    }
+
+    const projectState = this.autoLoopsByProject.get(
+      getWorktreeAutoLoopKey(projectPath, branchName)
+    );
+    if (!projectState || projectState.pausedDueToFailures) return;
+    projectState.pausedDueToFailures = true;
+    const failureCount = projectState.consecutiveFailures.length;
+    this.eventBus.emitAutoModeEvent('auto_mode_paused_failures', {
+      message:
+        failureCount >= CONSECUTIVE_FAILURE_THRESHOLD
+          ? `Auto Mode paused: ${failureCount} consecutive failures detected.`
+          : 'Auto Mode paused: Usage limit or API error detected.',
+      errorType: actualErrorInfo.type,
+      originalError: actualErrorInfo.message,
+      failureCount,
+      projectPath,
+      branchName,
+    });
+    this.stopAutoLoopForProject(projectPath, branchName);
+  }
+
+  resetFailureTrackingForProject(projectPath: string, branchName: string | null = null): void {
+    const projectState = this.autoLoopsByProject.get(
+      getWorktreeAutoLoopKey(projectPath, branchName)
+    );
+    if (projectState) {
+      projectState.consecutiveFailures = [];
+      projectState.pausedDueToFailures = false;
+    }
+  }
+
+  recordSuccessForProject(projectPath: string, branchName: string | null = null): void {
+    const projectState = this.autoLoopsByProject.get(
+      getWorktreeAutoLoopKey(projectPath, branchName)
+    );
+    if (projectState) projectState.consecutiveFailures = [];
+  }
+
+  async resolveMaxConcurrency(
+    projectPath: string,
+    branchName: string | null,
+    provided?: number
+  ): Promise<number> {
+    if (typeof provided === 'number' && Number.isFinite(provided)) return provided;
+    if (!this.settingsService) return DEFAULT_MAX_CONCURRENCY;
+    try {
+      const settings = await this.settingsService.getGlobalSettings();
+      const globalMax =
+        typeof settings.maxConcurrency === 'number'
+          ? settings.maxConcurrency
+          : DEFAULT_MAX_CONCURRENCY;
+      const projectId = settings.projects?.find((p) => p.path === projectPath)?.id;
+      const autoModeByWorktree = settings.autoModeByWorktree;
+      if (projectId && autoModeByWorktree && typeof autoModeByWorktree === 'object') {
+        const normalizedBranch =
+          branchName === null || branchName === 'main' ? '__main__' : branchName;
+        const worktreeId = `${projectId}::${normalizedBranch}`;
+        if (
+          worktreeId in autoModeByWorktree &&
+          typeof autoModeByWorktree[worktreeId]?.maxConcurrency === 'number'
+        ) {
+          return autoModeByWorktree[worktreeId].maxConcurrency;
+        }
+      }
+      return globalMax;
+    } catch {
+      return DEFAULT_MAX_CONCURRENCY;
+    }
+  }
+
+  private sleep(ms: number, signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (signal?.aborted) {
+        reject(new Error('Aborted'));
+        return;
+      }
+      const onAbort = () => {
+        clearTimeout(timeout);
+        reject(new Error('Aborted'));
+      };
+      const timeout = setTimeout(() => {
+        signal?.removeEventListener('abort', onAbort);
+        resolve();
+      }, ms);
+      signal?.addEventListener('abort', onAbort);
+    });
+  }
+}

apps/server/src/services/auto-mode/compat.ts

@@ -0,0 +1,240 @@
+/**
+ * Compatibility Shim - Provides AutoModeService-like interface using the new architecture
+ *
+ * This allows existing routes to work without major changes during the transition.
+ * Routes receive this shim which delegates to GlobalAutoModeService and facades.
+ *
+ * This is a TEMPORARY shim - routes should be updated to use the new interface directly.
+ */
+
+import type { Feature } from '@automaker/types';
+import type { EventEmitter } from '../../lib/events.js';
+import { GlobalAutoModeService } from './global-service.js';
+import { AutoModeServiceFacade } from './facade.js';
+import type { SettingsService } from '../settings-service.js';
+import type { FeatureLoader } from '../feature-loader.js';
+import type { ClaudeUsageService } from '../claude-usage-service.js';
+import type { FacadeOptions, AutoModeStatus, RunningAgentInfo } from './types.js';
+
+/**
+ * AutoModeServiceCompat wraps GlobalAutoModeService and facades to provide
+ * the old AutoModeService interface that routes expect.
+ */
+export class AutoModeServiceCompat {
+  private readonly globalService: GlobalAutoModeService;
+  private readonly facadeOptions: FacadeOptions;
+  private readonly facadeCache = new Map<string, AutoModeServiceFacade>();
+
+  constructor(
+    events: EventEmitter,
+    settingsService: SettingsService | null,
+    featureLoader: FeatureLoader,
+    claudeUsageService?: ClaudeUsageService | null
+  ) {
+    this.globalService = new GlobalAutoModeService(events, settingsService, featureLoader);
+    const sharedServices = this.globalService.getSharedServices();
+
+    this.facadeOptions = {
+      events,
+      settingsService,
+      featureLoader,
+      sharedServices,
+      claudeUsageService: claudeUsageService ?? null,
+    };
+  }
+
+  /**
+   * Get the global service for direct access
+   */
+  getGlobalService(): GlobalAutoModeService {
+    return this.globalService;
+  }
+
+  /**
+   * Get or create a facade for a specific project.
+   * Facades are cached by project path so that auto loop state
+   * (stored in the facade's AutoLoopCoordinator) persists across API calls.
+   */
+  createFacade(projectPath: string): AutoModeServiceFacade {
+    let facade = this.facadeCache.get(projectPath);
+    if (!facade) {
+      facade = AutoModeServiceFacade.create(projectPath, this.facadeOptions);
+      this.facadeCache.set(projectPath, facade);
+    }
+    return facade;
+  }
+
+  // ===========================================================================
+  // GLOBAL OPERATIONS (delegated to GlobalAutoModeService)
+  // ===========================================================================
+
+  getStatus(): AutoModeStatus {
+    return this.globalService.getStatus();
+  }
+
+  getActiveAutoLoopProjects(): string[] {
+    return this.globalService.getActiveAutoLoopProjects();
+  }
+
+  getActiveAutoLoopWorktrees(): Array<{ projectPath: string; branchName: string | null }> {
+    return this.globalService.getActiveAutoLoopWorktrees();
+  }
+
+  async getRunningAgents(): Promise<RunningAgentInfo[]> {
+    return this.globalService.getRunningAgents();
+  }
+
+  async markAllRunningFeaturesInterrupted(reason?: string): Promise<void> {
+    return this.globalService.markAllRunningFeaturesInterrupted(reason);
+  }
+
+  async reconcileFeatureStates(projectPath: string): Promise<number> {
+    return this.globalService.reconcileFeatureStates(projectPath);
+  }
+
+  // ===========================================================================
+  // PER-PROJECT OPERATIONS (delegated to facades)
+  // ===========================================================================
+
+  async getStatusForProject(
+    projectPath: string,
+    branchName: string | null = null
+  ): Promise<{
+    isAutoLoopRunning: boolean;
+    runningFeatures: string[];
+    runningCount: number;
+    maxConcurrency: number;
+    branchName: string | null;
+  }> {
+    const facade = this.createFacade(projectPath);
+    return facade.getStatusForProject(branchName);
+  }
+
+  isAutoLoopRunningForProject(projectPath: string, branchName: string | null = null): boolean {
+    const facade = this.createFacade(projectPath);
+    return facade.isAutoLoopRunning(branchName);
+  }
+
+  async startAutoLoopForProject(
+    projectPath: string,
+    branchName: string | null = null,
+    maxConcurrency?: number
+  ): Promise<number> {
+    const facade = this.createFacade(projectPath);
+    return facade.startAutoLoop(branchName, maxConcurrency);
+  }
+
+  async stopAutoLoopForProject(
+    projectPath: string,
+    branchName: string | null = null
+  ): Promise<number> {
+    const facade = this.createFacade(projectPath);
+    return facade.stopAutoLoop(branchName);
+  }
+
+  async executeFeature(
+    projectPath: string,
+    featureId: string,
+    useWorktrees = false,
+    isAutoMode = false,
+    providedWorktreePath?: string,
+    options?: { continuationPrompt?: string; _calledInternally?: boolean }
+  ): Promise<void> {
+    const facade = this.createFacade(projectPath);
+    return facade.executeFeature(
+      featureId,
+      useWorktrees,
+      isAutoMode,
+      providedWorktreePath,
+      options
+    );
+  }
+
+  async stopFeature(featureId: string): Promise<boolean> {
+    // Stop feature is tricky - we need to find which project the feature is running in
+    // The concurrency manager tracks this
+    const runningAgents = await this.getRunningAgents();
+    const agent = runningAgents.find((a) => a.featureId === featureId);
+    if (agent) {
+      const facade = this.createFacade(agent.projectPath);
+      return facade.stopFeature(featureId);
+    }
+    return false;
+  }
+
+  async resumeFeature(projectPath: string, featureId: string, useWorktrees = false): Promise<void> {
+    const facade = this.createFacade(projectPath);
+    return facade.resumeFeature(featureId, useWorktrees);
+  }
+
+  async followUpFeature(
+    projectPath: string,
+    featureId: string,
+    prompt: string,
+    imagePaths?: string[],
+    useWorktrees = true
+  ): Promise<void> {
+    const facade = this.createFacade(projectPath);
+    return facade.followUpFeature(featureId, prompt, imagePaths, useWorktrees);
+  }
+
+  async verifyFeature(projectPath: string, featureId: string): Promise<boolean> {
+    const facade = this.createFacade(projectPath);
+    return facade.verifyFeature(featureId);
+  }
+
+  async commitFeature(
+    projectPath: string,
+    featureId: string,
+    providedWorktreePath?: string
+  ): Promise<string | null> {
+    const facade = this.createFacade(projectPath);
+    return facade.commitFeature(featureId, providedWorktreePath);
+  }
+
+  async contextExists(projectPath: string, featureId: string): Promise<boolean> {
+    const facade = this.createFacade(projectPath);
+    return facade.contextExists(featureId);
+  }
+
+  async analyzeProject(projectPath: string): Promise<void> {
+    const facade = this.createFacade(projectPath);
+    return facade.analyzeProject();
+  }
+
+  async resolvePlanApproval(
+    projectPath: string,
+    featureId: string,
+    approved: boolean,
+    editedPlan?: string,
+    feedback?: string
+  ): Promise<{ success: boolean; error?: string }> {
+    const facade = this.createFacade(projectPath);
+    return facade.resolvePlanApproval(featureId, approved, editedPlan, feedback);
+  }
+
+  async resumeInterruptedFeatures(projectPath: string): Promise<void> {
+    const facade = this.createFacade(projectPath);
+    return facade.resumeInterruptedFeatures();
+  }
+
+  async checkWorktreeCapacity(
+    projectPath: string,
+    featureId: string
+  ): Promise<{
+    hasCapacity: boolean;
+    currentAgents: number;
+    maxAgents: number;
+    branchName: string | null;
+  }> {
+    const facade = this.createFacade(projectPath);
+    return facade.checkWorktreeCapacity(featureId);
+  }
+
+  async detectOrphanedFeatures(
+    projectPath: string
+  ): Promise<Array<{ feature: Feature; missingBranch: string }>> {
+    const facade = this.createFacade(projectPath);
+    return facade.detectOrphanedFeatures();
+  }
+}

apps/server/src/services/auto-mode/global-service.ts

@@ -0,0 +1,225 @@
+/**
+ * GlobalAutoModeService - Global operations for auto-mode that span across all projects
+ *
+ * This service manages global state and operations that are not project-specific:
+ * - Overall status (all running features across all projects)
+ * - Active auto loop projects and worktrees
+ * - Graceful shutdown (mark all features as interrupted)
+ *
+ * Per-project operations should use AutoModeServiceFacade instead.
+ */
+
+import path from 'path';
+import type { Feature } from '@automaker/types';
+import { createLogger } from '@automaker/utils';
+import type { EventEmitter } from '../../lib/events.js';
+import { TypedEventBus } from '../typed-event-bus.js';
+import { ConcurrencyManager } from '../concurrency-manager.js';
+import { WorktreeResolver } from '../worktree-resolver.js';
+import { AutoLoopCoordinator } from '../auto-loop-coordinator.js';
+import { FeatureStateManager } from '../feature-state-manager.js';
+import { FeatureLoader } from '../feature-loader.js';
+import type { SettingsService } from '../settings-service.js';
+import type { SharedServices, AutoModeStatus, RunningAgentInfo } from './types.js';
+
+const logger = createLogger('GlobalAutoModeService');
+
+/**
+ * GlobalAutoModeService provides global operations for auto-mode.
+ *
+ * Created once at server startup, shared across all facades.
+ */
+export class GlobalAutoModeService {
+  private readonly eventBus: TypedEventBus;
+  private readonly concurrencyManager: ConcurrencyManager;
+  private readonly autoLoopCoordinator: AutoLoopCoordinator;
+  private readonly worktreeResolver: WorktreeResolver;
+  private readonly featureStateManager: FeatureStateManager;
+  private readonly featureLoader: FeatureLoader;
+
+  constructor(
+    events: EventEmitter,
+    settingsService: SettingsService | null,
+    featureLoader: FeatureLoader = new FeatureLoader()
+  ) {
+    this.featureLoader = featureLoader;
+    this.eventBus = new TypedEventBus(events);
+    this.worktreeResolver = new WorktreeResolver();
+    this.concurrencyManager = new ConcurrencyManager((p) =>
+      this.worktreeResolver.getCurrentBranch(p)
+    );
+    this.featureStateManager = new FeatureStateManager(events, featureLoader);
+
+    // Create AutoLoopCoordinator with callbacks
+    // IMPORTANT: This coordinator is for MONITORING ONLY (getActiveProjects, getActiveWorktrees).
+    // Facades MUST create their own AutoLoopCoordinator for actual execution.
+    // The executeFeatureFn here is a safety guard - it should never be called.
+    this.autoLoopCoordinator = new AutoLoopCoordinator(
+      this.eventBus,
+      this.concurrencyManager,
+      settingsService,
+      // executeFeatureFn - throws because facades must use their own coordinator for execution
+      async () => {
+        throw new Error(
+          'executeFeatureFn not available in GlobalAutoModeService. ' +
+            'Facades must create their own AutoLoopCoordinator for execution.'
+        );
+      },
+      // getBacklogFeaturesFn
+      async (pPath, branchName) => {
+        const features = await featureLoader.getAll(pPath);
+        // For main worktree (branchName === null), resolve the actual primary branch name
+        // so features with branchName matching the primary branch are included
+        let primaryBranch: string | null = null;
+        if (branchName === null) {
+          primaryBranch = await this.worktreeResolver.getCurrentBranch(pPath);
+        }
+        return features.filter(
+          (f) =>
+            (f.status === 'backlog' || f.status === 'ready') &&
+            (branchName === null
+              ? !f.branchName || (primaryBranch && f.branchName === primaryBranch)
+              : f.branchName === branchName)
+        );
+      },
+      // saveExecutionStateFn - placeholder
+      async () => {},
+      // clearExecutionStateFn - placeholder
+      async () => {},
+      // resetStuckFeaturesFn
+      (pPath) => this.featureStateManager.resetStuckFeatures(pPath),
+      // isFeatureDoneFn
+      (feature) =>
+        feature.status === 'completed' ||
+        feature.status === 'verified' ||
+        feature.status === 'waiting_approval',
+      // isFeatureRunningFn
+      (featureId) => this.concurrencyManager.isRunning(featureId)
+    );
+  }
+
+  /**
+   * Get the shared services for use by facades.
+   * This allows facades to share state with the global service.
+   */
+  getSharedServices(): SharedServices {
+    return {
+      eventBus: this.eventBus,
+      concurrencyManager: this.concurrencyManager,
+      autoLoopCoordinator: this.autoLoopCoordinator,
+      worktreeResolver: this.worktreeResolver,
+    };
+  }
+
+  // ===========================================================================
+  // GLOBAL STATUS (3 methods)
+  // ===========================================================================
+
+  /**
+   * Get global status (all projects combined)
+   */
+  getStatus(): AutoModeStatus {
+    const allRunning = this.concurrencyManager.getAllRunning();
+    return {
+      isRunning: allRunning.length > 0,
+      runningFeatures: allRunning.map((rf) => rf.featureId),
+      runningCount: allRunning.length,
+    };
+  }
+
+  /**
+   * Get all active auto loop projects (unique project paths)
+   */
+  getActiveAutoLoopProjects(): string[] {
+    return this.autoLoopCoordinator.getActiveProjects();
+  }
+
+  /**
+   * Get all active auto loop worktrees
+   */
+  getActiveAutoLoopWorktrees(): Array<{ projectPath: string; branchName: string | null }> {
+    return this.autoLoopCoordinator.getActiveWorktrees();
+  }
+
+  // ===========================================================================
+  // RUNNING AGENTS (1 method)
+  // ===========================================================================
+
+  /**
+   * Get detailed info about all running agents
+   */
+  async getRunningAgents(): Promise<RunningAgentInfo[]> {
+    const agents = await Promise.all(
+      this.concurrencyManager.getAllRunning().map(async (rf) => {
+        let title: string | undefined;
+        let description: string | undefined;
+        let branchName: string | undefined;
+
+        try {
+          const feature = await this.featureLoader.get(rf.projectPath, rf.featureId);
+          if (feature) {
+            title = feature.title;
+            description = feature.description;
+            branchName = feature.branchName;
+          }
+        } catch {
+          // Silently ignore
+        }
+
+        return {
+          featureId: rf.featureId,
+          projectPath: rf.projectPath,
+          projectName: path.basename(rf.projectPath),
+          isAutoMode: rf.isAutoMode,
+          model: rf.model,
+          provider: rf.provider,
+          title,
+          description,
+          branchName,
+        };
+      })
+    );
+    return agents;
+  }
+
+  // ===========================================================================
+  // LIFECYCLE (1 method)
+  // ===========================================================================
+
+  /**
+   * Mark all running features as interrupted.
+   * Called during graceful shutdown.
+   *
+   * @param reason - Optional reason for the interruption
+   */
+  async markAllRunningFeaturesInterrupted(reason?: string): Promise<void> {
+    const allRunning = this.concurrencyManager.getAllRunning();
+
+    for (const rf of allRunning) {
+      await this.featureStateManager.markFeatureInterrupted(rf.projectPath, rf.featureId, reason);
+    }
+
+    if (allRunning.length > 0) {
+      logger.info(
+        `Marked ${allRunning.length} running feature(s) as interrupted: ${reason || 'no reason provided'}`
+      );
+    }
+  }
+
+  /**
+   * Reconcile all feature states for a project on server startup.
+   *
+   * Resets features stuck in transient states (in_progress, interrupted, pipeline_*)
+   * back to a resting state and emits events so the UI reflects corrected states.
+   *
+   * This should be called during server initialization to handle:
+   * - Clean shutdown: features already marked as interrupted
+   * - Forced kill / crash: features left in in_progress or pipeline_* states
+   *
+   * @param projectPath - The project path to reconcile
+   * @returns The number of features that were reconciled
+   */
+  async reconcileFeatureStates(projectPath: string): Promise<number> {
+    return this.featureStateManager.reconcileAllFeatureStates(projectPath);
+  }
+}

apps/server/src/services/auto-mode/index.ts

@@ -0,0 +1,77 @@
+/**
+ * Auto Mode Service Module
+ *
+ * Entry point for auto-mode functionality. Exports:
+ * - GlobalAutoModeService: Global operations that span all projects
+ * - AutoModeServiceFacade: Per-project facade for auto-mode operations
+ * - createAutoModeFacade: Convenience factory function
+ * - Types for route consumption
+ */
+
+// Main exports
+export { GlobalAutoModeService } from './global-service.js';
+export { AutoModeServiceFacade } from './facade.js';
+export { AutoModeServiceCompat } from './compat.js';
+
+// Convenience factory function
+import { AutoModeServiceFacade } from './facade.js';
+import type { FacadeOptions } from './types.js';
+
+/**
+ * Create an AutoModeServiceFacade instance for a specific project.
+ *
+ * This is a convenience wrapper around AutoModeServiceFacade.create().
+ *
+ * @param projectPath - The project path this facade operates on
+ * @param options - Configuration options including events, settingsService, featureLoader
+ * @returns A new AutoModeServiceFacade instance
+ *
+ * @example
+ * ```typescript
+ * import { createAutoModeFacade } from './services/auto-mode';
+ *
+ * const facade = createAutoModeFacade('/path/to/project', {
+ *   events: eventEmitter,
+ *   settingsService,
+ * });
+ *
+ * // Start auto mode
+ * await facade.startAutoLoop(null, 3);
+ *
+ * // Check status
+ * const status = facade.getStatusForProject();
+ * ```
+ */
+export function createAutoModeFacade(
+  projectPath: string,
+  options: FacadeOptions
+): AutoModeServiceFacade {
+  return AutoModeServiceFacade.create(projectPath, options);
+}
+
+// Type exports from types.ts
+export type {
+  FacadeOptions,
+  SharedServices,
+  AutoModeStatus,
+  ProjectAutoModeStatus,
+  WorktreeCapacityInfo,
+  RunningAgentInfo,
+  OrphanedFeatureInfo,
+  FacadeError,
+  GlobalAutoModeOperations,
+} from './types.js';
+
+// Re-export types from extracted services for route convenience
+export type {
+  AutoModeConfig,
+  ProjectAutoLoopState,
+  RunningFeature,
+  AcquireParams,
+  WorktreeInfo,
+  PipelineContext,
+  PipelineStatusInfo,
+  PlanApprovalResult,
+  ResolveApprovalResult,
+  ExecutionState,
+} from './types.js';

apps/server/src/services/auto-mode/types.ts

@@ -0,0 +1,148 @@
+/**
+ * Facade Types - Type definitions for AutoModeServiceFacade
+ *
+ * Contains:
+ * - FacadeOptions interface for factory configuration
+ * - Re-exports of types from extracted services that routes might need
+ * - Additional types for facade method signatures
+ */
+
+import type { EventEmitter } from '../../lib/events.js';
+import type { Feature, ModelProvider } from '@automaker/types';
+import type { SettingsService } from '../settings-service.js';
+import type { FeatureLoader } from '../feature-loader.js';
+import type { ConcurrencyManager } from '../concurrency-manager.js';
+import type { AutoLoopCoordinator } from '../auto-loop-coordinator.js';
+import type { WorktreeResolver } from '../worktree-resolver.js';
+import type { TypedEventBus } from '../typed-event-bus.js';
+import type { ClaudeUsageService } from '../claude-usage-service.js';
+
+// Re-export types from extracted services for route consumption
+export type { AutoModeConfig, ProjectAutoLoopState } from '../auto-loop-coordinator.js';
+
+export type { RunningFeature, AcquireParams } from '../concurrency-manager.js';
+
+export type { WorktreeInfo } from '../worktree-resolver.js';
+
+export type { PipelineContext, PipelineStatusInfo } from '../pipeline-orchestrator.js';
+
+export type { PlanApprovalResult, ResolveApprovalResult } from '../plan-approval-service.js';
+
+export type { ExecutionState } from '../recovery-service.js';
+
+/**
+ * Shared services that can be passed to facades to enable state sharing
+ */
+export interface SharedServices {
+  /** TypedEventBus for typed event emission */
+  eventBus: TypedEventBus;
+  /** ConcurrencyManager for tracking running features across all projects */
+  concurrencyManager: ConcurrencyManager;
+  /** AutoLoopCoordinator for managing auto loop state across all projects */
+  autoLoopCoordinator: AutoLoopCoordinator;
+  /** WorktreeResolver for git worktree operations */
+  worktreeResolver: WorktreeResolver;
+}
+
+/**
+ * Options for creating an AutoModeServiceFacade instance
+ */
+export interface FacadeOptions {
+  /** EventEmitter for broadcasting events to clients */
+  events: EventEmitter;
+  /** SettingsService for reading project/global settings (optional) */
+  settingsService?: SettingsService | null;
+  /** FeatureLoader for loading feature data (optional, defaults to new FeatureLoader()) */
+  featureLoader?: FeatureLoader;
+  /** Shared services for state sharing across facades (optional) */
+  sharedServices?: SharedServices;
+  /** ClaudeUsageService for checking usage limits before picking up features (optional) */
+  claudeUsageService?: ClaudeUsageService | null;
+}
+
+/**
+ * Status returned by getStatus()
+ */
+export interface AutoModeStatus {
+  isRunning: boolean;
+  runningFeatures: string[];
+  runningCount: number;
+}
+
+/**
+ * Status returned by getStatusForProject()
+ */
+export interface ProjectAutoModeStatus {
+  isAutoLoopRunning: boolean;
+  runningFeatures: string[];
+  runningCount: number;
+  maxConcurrency: number;
+  branchName: string | null;
+}
+
+/**
+ * Capacity info returned by checkWorktreeCapacity()
+ */
+export interface WorktreeCapacityInfo {
+  hasCapacity: boolean;
+  currentAgents: number;
+  maxAgents: number;
+  branchName: string | null;
+}
+
+/**
+ * Running agent info returned by getRunningAgents()
+ */
+export interface RunningAgentInfo {
+  featureId: string;
+  projectPath: string;
+  projectName: string;
+  isAutoMode: boolean;
+  model?: string;
+  provider?: ModelProvider;
+  title?: string;
+  description?: string;
+  branchName?: string;
+}
+
+/**
+ * Orphaned feature info returned by detectOrphanedFeatures()
+ */
+export interface OrphanedFeatureInfo {
+  feature: Feature;
+  missingBranch: string;
+}
+
+/**
+ * Structured error object returned/emitted by facade methods.
+ * Provides consistent error information for callers and UI consumers.
+ */
+export interface FacadeError {
+  /** The facade method where the error originated */
+  method: string;
+  /** Classified error type from the error handler */
+  errorType: import('@automaker/types').ErrorType;
+  /** Human-readable error message */
+  message: string;
+  /** Feature ID if the error is associated with a specific feature */
+  featureId?: string;
+  /** Project path where the error occurred */
+  projectPath: string;
+}
+
+/**
+ * Interface describing global auto-mode operations (not project-specific).
+ * Used by routes that need global state access.
+ */
+export interface GlobalAutoModeOperations {
+  /** Get global status (all projects combined) */
+  getStatus(): AutoModeStatus;
+  /** Get all active auto loop projects (unique project paths) */
+  getActiveAutoLoopProjects(): string[];
+  /** Get all active auto loop worktrees */
+  getActiveAutoLoopWorktrees(): Array<{ projectPath: string; branchName: string | null }>;
+  /** Get detailed info about all running agents */
+  getRunningAgents(): Promise<RunningAgentInfo[]>;
+  /** Mark all running features as interrupted (for graceful shutdown) */
+  markAllRunningFeaturesInterrupted(reason?: string): Promise<void>;
+}

apps/server/src/services/claude-usage-service.ts

@@ -294,7 +294,16 @@ export class ClaudeUsageService {
             this.killPtyProcess(ptyProcess);
           }
           // Don't fail if we have data - return it instead
-          if (output.includes('Current session')) {
+          // Check cleaned output since raw output has ANSI codes between words
+          // eslint-disable-next-line no-control-regex
+          const cleanedForCheck = output
+            .replace(/\x1B\[(\d+)C/g, (_m: string, n: string) => ' '.repeat(parseInt(n, 10)))
+            .replace(/\x1B\[[0-9;?]*[A-Za-z@]/g, '');
+          if (
+            cleanedForCheck.includes('Current session') ||
+            cleanedForCheck.includes('% used') ||
+            cleanedForCheck.includes('% left')
+          ) {
             resolve(output);
           } else if (hasSeenTrustPrompt) {
             // Trust prompt was shown but we couldn't auto-approve it
@@ -320,8 +329,13 @@ export class ClaudeUsageService {
         output += data;
 
         // Strip ANSI codes for easier matching
+        // Convert cursor forward (ESC[nC) to spaces first to preserve word boundaries,
+        // then strip remaining ANSI sequences. Without this, the Claude CLI TUI output
+        // like "Current week (all models)" becomes "Currentweek(allmodels)".
         // eslint-disable-next-line no-control-regex
-        const cleanOutput = output.replace(/\x1B\[[0-9;]*[A-Za-z]/g, '');
+        const cleanOutput = output
+          .replace(/\x1B\[(\d+)C/g, (_match: string, n: string) => ' '.repeat(parseInt(n, 10)))
+          .replace(/\x1B\[[0-9;?]*[A-Za-z@]/g, '');
 
         // Check for specific authentication/permission errors
         // Must be very specific to avoid false positives from garbled terminal encoding
@@ -356,7 +370,8 @@ export class ClaudeUsageService {
         const hasUsageIndicators =
           cleanOutput.includes('Current session') ||
           (cleanOutput.includes('Usage') && cleanOutput.includes('% left')) ||
-          // Additional patterns for winpty - look for percentage patterns
+          // Look for percentage patterns - allow optional whitespace between % and left/used
+          // since cursor movement codes may or may not create spaces after stripping
           /\d+%\s*(left|used|remaining)/i.test(cleanOutput) ||
           cleanOutput.includes('Resets in') ||
           cleanOutput.includes('Current week');
@@ -382,12 +397,15 @@ export class ClaudeUsageService {
         // Handle Trust Dialog - multiple variants:
         // - "Do you want to work in this folder?"
         // - "Ready to code here?" / "I'll need permission to work with your files"
+        // - "Quick safety check" / "Yes, I trust this folder"
         // Since we are running in cwd (project dir), it is safe to approve.
         if (
           !hasApprovedTrust &&
           (cleanOutput.includes('Do you want to work in this folder?') ||
             cleanOutput.includes('Ready to code here') ||
-            cleanOutput.includes('permission to work with your files'))
+            cleanOutput.includes('permission to work with your files') ||
+            cleanOutput.includes('trust this folder') ||
+            cleanOutput.includes('safety check'))
         ) {
           hasApprovedTrust = true;
           hasSeenTrustPrompt = true;
@@ -471,10 +489,17 @@ export class ClaudeUsageService {
    * Handles CSI, OSC, and other common ANSI sequences
    */
   private stripAnsiCodes(text: string): string {
-    // First strip ANSI sequences (colors, etc) and handle CR
+    // First, convert cursor movement sequences to whitespace to preserve word boundaries.
+    // The Claude CLI TUI uses ESC[nC (cursor forward) instead of actual spaces between words.
+    // Without this, "Current week (all models)" becomes "Currentweek(allmodels)" after stripping.
     // eslint-disable-next-line no-control-regex
     let clean = text
-      // CSI sequences: ESC [ ... (letter or @)
+      // Cursor forward (CSI n C): replace with n spaces to preserve word separation
+      .replace(/\x1B\[(\d+)C/g, (_match, n) => ' '.repeat(parseInt(n, 10)))
+      // Cursor movement (up/down/back/position): replace with newline or nothing
+      .replace(/\x1B\[\d*[ABD]/g, '') // cursor up (A), down (B), back (D)
+      .replace(/\x1B\[\d+;\d+[Hf]/g, '\n') // cursor position (H/f)
+      // Now strip remaining CSI sequences (colors, modes, etc.)
       .replace(/\x1B\[[0-9;?]*[A-Za-z@]/g, '')
       // OSC sequences: ESC ] ... terminated by BEL, ST, or another ESC
       .replace(/\x1B\][^\x07\x1B]*(?:\x07|\x1B\\)?/g, '')
@@ -637,7 +662,7 @@ export class ClaudeUsageService {
 
       resetTime = this.parseResetTime(resetText, type);
       // Strip timezone like "(Asia/Dubai)" from the display text
-      resetText = resetText.replace(/\s*\([A-Za-z_\/]+\)\s*$/, '').trim();
+      resetText = resetText.replace(/\s*\([A-Za-z_/]+\)\s*$/, '').trim();
     }
 
     return { percentage: percentage ?? 0, resetTime, resetText };

apps/server/src/services/concurrency-manager.ts

@@ -0,0 +1,261 @@
+/**
+ * ConcurrencyManager - Manages running feature slots with lease-based reference counting
+ *
+ * Extracted from AutoModeService to provide a standalone service for tracking
+ * running feature execution with proper lease counting to support nested calls
+ * (e.g., resumeFeature -> executeFeature).
+ *
+ * Key behaviors:
+ * - acquire() with existing entry + allowReuse: increment leaseCount, return existing
+ * - acquire() with existing entry + no allowReuse: throw Error('already running')
+ * - release() decrements leaseCount, only deletes at 0
+ * - release() with force:true bypasses leaseCount check
+ */
+
+import type { ModelProvider } from '@automaker/types';
+
+/**
+ * Function type for getting the current branch of a project.
+ * Injected to allow for testing and decoupling from git operations.
+ */
+export type GetCurrentBranchFn = (projectPath: string) => Promise<string | null>;
+
+/**
+ * Represents a running feature execution with all tracking metadata
+ */
+export interface RunningFeature {
+  featureId: string;
+  projectPath: string;
+  worktreePath: string | null;
+  branchName: string | null;
+  abortController: AbortController;
+  isAutoMode: boolean;
+  startTime: number;
+  leaseCount: number;
+  model?: string;
+  provider?: ModelProvider;
+}
+
+/**
+ * Parameters for acquiring a running feature slot
+ */
+export interface AcquireParams {
+  featureId: string;
+  projectPath: string;
+  isAutoMode: boolean;
+  allowReuse?: boolean;
+  abortController?: AbortController;
+}
+
+/**
+ * ConcurrencyManager manages the running features Map with lease-based reference counting.
+ *
+ * This supports nested execution patterns where a feature may be acquired multiple times
+ * (e.g., during resume operations) and should only be released when all references are done.
+ */
+export class ConcurrencyManager {
+  private runningFeatures = new Map<string, RunningFeature>();
+  private getCurrentBranch: GetCurrentBranchFn;
+
+  /**
+   * @param getCurrentBranch - Function to get the current branch for a project.
+   *                           If not provided, defaults to returning 'main'.
+   */
+  constructor(getCurrentBranch?: GetCurrentBranchFn) {
+    this.getCurrentBranch = getCurrentBranch ?? (() => Promise.resolve('main'));
+  }
+
+  /**
+   * Acquire a slot in the runningFeatures map for a feature.
+   * Implements reference counting via leaseCount to support nested calls
+   * (e.g., resumeFeature -> executeFeature).
+   *
+   * @param params.featureId - ID of the feature to track
+   * @param params.projectPath - Path to the project
+   * @param params.isAutoMode - Whether this is an auto-mode execution
+   * @param params.allowReuse - If true, allows incrementing leaseCount for already-running features
+   * @param params.abortController - Optional abort controller to use
+   * @returns The RunningFeature entry (existing or newly created)
+   * @throws Error if feature is already running and allowReuse is false
+   */
+  acquire(params: AcquireParams): RunningFeature {
+    const existing = this.runningFeatures.get(params.featureId);
+    if (existing) {
+      if (!params.allowReuse) {
+        throw new Error('already running');
+      }
+      existing.leaseCount += 1;
+      return existing;
+    }
+
+    const abortController = params.abortController ?? new AbortController();
+    const entry: RunningFeature = {
+      featureId: params.featureId,
+      projectPath: params.projectPath,
+      worktreePath: null,
+      branchName: null,
+      abortController,
+      isAutoMode: params.isAutoMode,
+      startTime: Date.now(),
+      leaseCount: 1,
+    };
+    this.runningFeatures.set(params.featureId, entry);
+    return entry;
+  }
+
+  /**
+   * Release a slot in the runningFeatures map for a feature.
+   * Decrements leaseCount and only removes the entry when it reaches zero,
+   * unless force option is used.
+   *
+   * @param featureId - ID of the feature to release
+   * @param options.force - If true, immediately removes the entry regardless of leaseCount
+   */
+  release(featureId: string, options?: { force?: boolean }): void {
+    const entry = this.runningFeatures.get(featureId);
+    if (!entry) {
+      return;
+    }
+
+    if (options?.force) {
+      this.runningFeatures.delete(featureId);
+      return;
+    }
+
+    entry.leaseCount -= 1;
+    if (entry.leaseCount <= 0) {
+      this.runningFeatures.delete(featureId);
+    }
+  }
+
+  /**
+   * Check if a feature is currently running
+   *
+   * @param featureId - ID of the feature to check
+   * @returns true if the feature is in the runningFeatures map
+   */
+  isRunning(featureId: string): boolean {
+    return this.runningFeatures.has(featureId);
+  }
+
+  /**
+   * Get the RunningFeature entry for a feature
+   *
+   * @param featureId - ID of the feature
+   * @returns The RunningFeature entry or undefined if not running
+   */
+  getRunningFeature(featureId: string): RunningFeature | undefined {
+    return this.runningFeatures.get(featureId);
+  }
+
+  /**
+   * Get count of running features for a specific project
+   *
+   * @param projectPath - The project path to count features for
+   * @returns Number of running features for the project
+   */
+  getRunningCount(projectPath: string): number {
+    let count = 0;
+    for (const [, feature] of this.runningFeatures) {
+      if (feature.projectPath === projectPath) {
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Get count of running features for a specific worktree
+   *
+   * @param projectPath - The project path
+   * @param branchName - The branch name, or null for main worktree
+   *                     (features without branchName or matching primary branch)
+   * @returns Number of running features for the worktree
+   */
+  async getRunningCountForWorktree(
+    projectPath: string,
+    branchName: string | null
+  ): Promise<number> {
+    // Get the actual primary branch name for the project
+    const primaryBranch = await this.getCurrentBranch(projectPath);
+
+    let count = 0;
+    for (const [, feature] of this.runningFeatures) {
+      // Filter by project path AND branchName to get accurate worktree-specific count
+      const featureBranch = feature.branchName ?? null;
+      if (branchName === null) {
+        // Main worktree: match features with branchName === null OR branchName matching primary branch
+        const isPrimaryBranch =
+          featureBranch === null || (primaryBranch && featureBranch === primaryBranch);
+        if (feature.projectPath === projectPath && isPrimaryBranch) {
+          count++;
+        }
+      } else {
+        // Feature worktree: exact match
+        if (feature.projectPath === projectPath && featureBranch === branchName) {
+          count++;
+        }
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Get all currently running features
+   *
+   * @returns Array of all RunningFeature entries
+   */
+  getAllRunning(): RunningFeature[] {
+    return Array.from(this.runningFeatures.values());
+  }
+
+  /**
+   * Get running feature IDs for a specific worktree, with proper primary branch normalization.
+   *
+   * When branchName is null (main worktree), matches features with branchName === null
+   * OR branchName matching the primary branch (e.g., "main", "master").
+   *
+   * @param projectPath - The project path
+   * @param branchName - The branch name, or null for main worktree
+   * @returns Array of feature IDs running in the specified worktree
+   */
+  async getRunningFeaturesForWorktree(
+    projectPath: string,
+    branchName: string | null
+  ): Promise<string[]> {
+    const primaryBranch = await this.getCurrentBranch(projectPath);
+    const featureIds: string[] = [];
+
+    for (const [, feature] of this.runningFeatures) {
+      if (feature.projectPath !== projectPath) continue;
+      const featureBranch = feature.branchName ?? null;
+
+      if (branchName === null) {
+        // Main worktree: match features with null branchName OR primary branch name
+        const isPrimaryBranch =
+          featureBranch === null || (primaryBranch && featureBranch === primaryBranch);
+        if (isPrimaryBranch) featureIds.push(feature.featureId);
+      } else {
+        // Feature worktree: exact match
+        if (featureBranch === branchName) featureIds.push(feature.featureId);
+      }
+    }
+
+    return featureIds;
+  }
+
+  /**
+   * Update properties of a running feature
+   *
+   * @param featureId - ID of the feature to update
+   * @param updates - Partial RunningFeature properties to update
+   */
+  updateRunningFeature(featureId: string, updates: Partial<RunningFeature>): void {
+    const entry = this.runningFeatures.get(featureId);
+    if (!entry) {
+      return;
+    }
+
+    Object.assign(entry, updates);
+  }
+}

apps/server/src/services/dev-server-service.ts

@@ -37,6 +37,8 @@ export interface DevServerInfo {
   flushTimeout: NodeJS.Timeout | null;
   // Flag to indicate server is stopping (prevents output after stop)
   stopping: boolean;
+  // Flag to indicate if URL has been detected from output
+  urlDetected: boolean;
 }
 
 // Port allocation starts at 3001 to avoid conflicts with common dev ports
@@ -103,6 +105,54 @@ class DevServerService {
     }
   }
 
+  /**
+   * Detect actual server URL from output
+   * Parses stdout/stderr for common URL patterns from dev servers
+   */
+  private detectUrlFromOutput(server: DevServerInfo, content: string): void {
+    // Skip if URL already detected
+    if (server.urlDetected) {
+      return;
+    }
+
+    // Common URL patterns from various dev servers:
+    // - Vite: "Local:   http://localhost:5173/"
+    // - Next.js: "ready - started server on 0.0.0.0:3000, url: http://localhost:3000"
+    // - CRA/Webpack: "On Your Network:  http://192.168.1.1:3000"
+    // - Generic: Any http:// or https:// URL
+    const urlPatterns = [
+      /(?:Local|Network):\s+(https?:\/\/[^\s]+)/i, // Vite format
+      /(?:ready|started server).*?(?:url:\s*)?(https?:\/\/[^\s,]+)/i, // Next.js format
+      /(https?:\/\/(?:localhost|127\.0\.0\.1|\[::\]):\d+)/i, // Generic localhost URL
+      /(https?:\/\/[^\s<>"{}|\\^`[\]]+)/i, // Any HTTP(S) URL
+    ];
+
+    for (const pattern of urlPatterns) {
+      const match = content.match(pattern);
+      if (match && match[1]) {
+        const detectedUrl = match[1].trim();
+        // Validate it looks like a reasonable URL
+        if (detectedUrl.startsWith('http://') || detectedUrl.startsWith('https://')) {
+          server.url = detectedUrl;
+          server.urlDetected = true;
+          logger.info(
+            `Detected actual server URL: ${detectedUrl} (allocated port was ${server.port})`
+          );
+
+          // Emit URL update event
+          if (this.emitter) {
+            this.emitter.emit('dev-server:url-detected', {
+              worktreePath: server.worktreePath,
+              url: detectedUrl,
+              timestamp: new Date().toISOString(),
+            });
+          }
+          break;
+        }
+      }
+    }
+  }
+
   /**
    * Handle incoming stdout/stderr data from dev server process
    * Buffers data for scrollback replay and schedules throttled emission
@@ -115,6 +165,9 @@ class DevServerService {
 
     const content = data.toString();
 
+    // Try to detect actual server URL from output
+    this.detectUrlFromOutput(server, content);
+
     // Append to scrollback buffer for replay on reconnect
     this.appendToScrollback(server, content);
 
@@ -446,13 +499,14 @@ class DevServerService {
     const serverInfo: DevServerInfo = {
       worktreePath,
       port,
-      url: `http://${hostname}:${port}`,
+      url: `http://${hostname}:${port}`, // Initial URL, may be updated by detectUrlFromOutput
       process: devProcess,
       startedAt: new Date(),
       scrollbackBuffer: '',
       outputBuffer: '',
       flushTimeout: null,
       stopping: false,
+      urlDetected: false, // Will be set to true when actual URL is detected from output
     };
 
     // Capture stdout with buffer management and event emission

apps/server/src/services/execution-service.ts

@@ -0,0 +1,470 @@
+/**
+ * ExecutionService - Feature execution lifecycle coordination
+ */
+
+import path from 'path';
+import type { Feature } from '@automaker/types';
+import { createLogger, classifyError, loadContextFiles, recordMemoryUsage } from '@automaker/utils';
+import { resolveModelString, DEFAULT_MODELS } from '@automaker/model-resolver';
+import { getFeatureDir } from '@automaker/platform';
+import { ProviderFactory } from '../providers/provider-factory.js';
+import * as secureFs from '../lib/secure-fs.js';
+import {
+  getPromptCustomization,
+  getAutoLoadClaudeMdSetting,
+  filterClaudeMdFromContext,
+} from '../lib/settings-helpers.js';
+import { validateWorkingDirectory } from '../lib/sdk-options.js';
+import { extractSummary } from './spec-parser.js';
+import type { TypedEventBus } from './typed-event-bus.js';
+import type { ConcurrencyManager, RunningFeature } from './concurrency-manager.js';
+import type { WorktreeResolver } from './worktree-resolver.js';
+import type { SettingsService } from './settings-service.js';
+import type { PipelineContext } from './pipeline-orchestrator.js';
+import { pipelineService } from './pipeline-service.js';
+
+// Re-export callback types from execution-types.ts for backward compatibility
+export type {
+  RunAgentFn,
+  ExecutePipelineFn,
+  UpdateFeatureStatusFn,
+  LoadFeatureFn,
+  GetPlanningPromptPrefixFn,
+  SaveFeatureSummaryFn,
+  RecordLearningsFn,
+  ContextExistsFn,
+  ResumeFeatureFn,
+  TrackFailureFn,
+  SignalPauseFn,
+  RecordSuccessFn,
+  SaveExecutionStateFn,
+  LoadContextFilesFn,
+} from './execution-types.js';
+
+import type {
+  RunAgentFn,
+  ExecutePipelineFn,
+  UpdateFeatureStatusFn,
+  LoadFeatureFn,
+  GetPlanningPromptPrefixFn,
+  SaveFeatureSummaryFn,
+  RecordLearningsFn,
+  ContextExistsFn,
+  ResumeFeatureFn,
+  TrackFailureFn,
+  SignalPauseFn,
+  RecordSuccessFn,
+  SaveExecutionStateFn,
+  LoadContextFilesFn,
+} from './execution-types.js';
+
+const logger = createLogger('ExecutionService');
+
+export class ExecutionService {
+  constructor(
+    private eventBus: TypedEventBus,
+    private concurrencyManager: ConcurrencyManager,
+    private worktreeResolver: WorktreeResolver,
+    private settingsService: SettingsService | null,
+    // Callback dependencies for delegation
+    private runAgentFn: RunAgentFn,
+    private executePipelineFn: ExecutePipelineFn,
+    private updateFeatureStatusFn: UpdateFeatureStatusFn,
+    private loadFeatureFn: LoadFeatureFn,
+    private getPlanningPromptPrefixFn: GetPlanningPromptPrefixFn,
+    private saveFeatureSummaryFn: SaveFeatureSummaryFn,
+    private recordLearningsFn: RecordLearningsFn,
+    private contextExistsFn: ContextExistsFn,
+    private resumeFeatureFn: ResumeFeatureFn,
+    private trackFailureFn: TrackFailureFn,
+    private signalPauseFn: SignalPauseFn,
+    private recordSuccessFn: RecordSuccessFn,
+    private saveExecutionStateFn: SaveExecutionStateFn,
+    private loadContextFilesFn: LoadContextFilesFn
+  ) {}
+
+  private acquireRunningFeature(options: {
+    featureId: string;
+    projectPath: string;
+    isAutoMode: boolean;
+    allowReuse?: boolean;
+  }): RunningFeature {
+    return this.concurrencyManager.acquire(options);
+  }
+
+  private releaseRunningFeature(featureId: string, options?: { force?: boolean }): void {
+    this.concurrencyManager.release(featureId, options);
+  }
+
+  private extractTitleFromDescription(description: string | undefined): string {
+    if (!description?.trim()) return 'Untitled Feature';
+    const firstLine = description.split('\n')[0].trim();
+    return firstLine.length <= 60 ? firstLine : firstLine.substring(0, 57) + '...';
+  }
+
+  buildFeaturePrompt(
+    feature: Feature,
+    taskExecutionPrompts: {
+      implementationInstructions: string;
+      playwrightVerificationInstructions: string;
+    }
+  ): string {
+    const title = this.extractTitleFromDescription(feature.description);
+
+    let prompt = `## Feature Implementation Task
+
+**Feature ID:** ${feature.id}
+**Title:** ${title}
+**Description:** ${feature.description}
+`;
+
+    if (feature.spec) {
+      prompt += `
+**Specification:**
+${feature.spec}
+`;
+    }
+
+    if (feature.imagePaths && feature.imagePaths.length > 0) {
+      const imagesList = feature.imagePaths
+        .map((img, idx) => {
+          const imgPath = typeof img === 'string' ? img : img.path;
+          const filename =
+            typeof img === 'string'
+              ? imgPath.split('/').pop()
+              : img.filename || imgPath.split('/').pop();
+          const mimeType = typeof img === 'string' ? 'image/*' : img.mimeType || 'image/*';
+          return `   ${idx + 1}. ${filename} (${mimeType})\n      Path: ${imgPath}`;
+        })
+        .join('\n');
+      prompt += `\n**Context Images Attached:**\n${feature.imagePaths.length} image(s) attached:\n${imagesList}\n`;
+    }
+
+    prompt += feature.skipTests
+      ? `\n${taskExecutionPrompts.implementationInstructions}`
+      : `\n${taskExecutionPrompts.implementationInstructions}\n\n${taskExecutionPrompts.playwrightVerificationInstructions}`;
+    return prompt;
+  }
+
+  async executeFeature(
+    projectPath: string,
+    featureId: string,
+    useWorktrees = false,
+    isAutoMode = false,
+    providedWorktreePath?: string,
+    options?: { continuationPrompt?: string; _calledInternally?: boolean }
+  ): Promise<void> {
+    const tempRunningFeature = this.acquireRunningFeature({
+      featureId,
+      projectPath,
+      isAutoMode,
+      allowReuse: options?._calledInternally,
+    });
+    const abortController = tempRunningFeature.abortController;
+    if (isAutoMode) await this.saveExecutionStateFn(projectPath);
+    let feature: Feature | null = null;
+
+    try {
+      validateWorkingDirectory(projectPath);
+      feature = await this.loadFeatureFn(projectPath, featureId);
+      if (!feature) throw new Error(`Feature ${featureId} not found`);
+
+      if (!options?.continuationPrompt) {
+        if (feature.planSpec?.status === 'approved') {
+          const prompts = await getPromptCustomization(this.settingsService, '[ExecutionService]');
+          let continuationPrompt = prompts.taskExecution.continuationAfterApprovalTemplate;
+          continuationPrompt = continuationPrompt
+            .replace(/\{\{userFeedback\}\}/g, '')
+            .replace(/\{\{approvedPlan\}\}/g, feature.planSpec.content || '');
+          return await this.executeFeature(
+            projectPath,
+            featureId,
+            useWorktrees,
+            isAutoMode,
+            providedWorktreePath,
+            { continuationPrompt, _calledInternally: true }
+          );
+        }
+        if (await this.contextExistsFn(projectPath, featureId)) {
+          return await this.resumeFeatureFn(projectPath, featureId, useWorktrees, true);
+        }
+      }
+
+      let worktreePath: string | null = providedWorktreePath ?? null;
+      const branchName = feature.branchName;
+      if (!worktreePath && useWorktrees && branchName) {
+        worktreePath = await this.worktreeResolver.findWorktreeForBranch(projectPath, branchName);
+        if (worktreePath) logger.info(`Using worktree for branch "${branchName}": ${worktreePath}`);
+      }
+      const workDir = worktreePath ? path.resolve(worktreePath) : path.resolve(projectPath);
+      validateWorkingDirectory(workDir);
+      tempRunningFeature.worktreePath = worktreePath;
+      tempRunningFeature.branchName = branchName ?? null;
+      await this.updateFeatureStatusFn(projectPath, featureId, 'in_progress');
+      this.eventBus.emitAutoModeEvent('auto_mode_feature_start', {
+        featureId,
+        projectPath,
+        branchName: feature.branchName ?? null,
+        feature: {
+          id: featureId,
+          title: feature.title || 'Loading...',
+          description: feature.description || 'Feature is starting',
+        },
+      });
+
+      const autoLoadClaudeMd = await getAutoLoadClaudeMdSetting(
+        projectPath,
+        this.settingsService,
+        '[ExecutionService]'
+      );
+      const prompts = await getPromptCustomization(this.settingsService, '[ExecutionService]');
+      let prompt: string;
+      const contextResult = await this.loadContextFilesFn({
+        projectPath,
+        fsModule: secureFs as Parameters<typeof loadContextFiles>[0]['fsModule'],
+        taskContext: {
+          title: feature.title ?? '',
+          description: feature.description ?? '',
+        },
+      });
+      const combinedSystemPrompt = filterClaudeMdFromContext(contextResult, autoLoadClaudeMd);
+
+      if (options?.continuationPrompt) {
+        prompt = options.continuationPrompt;
+      } else {
+        prompt =
+          (await this.getPlanningPromptPrefixFn(feature)) +
+          this.buildFeaturePrompt(feature, prompts.taskExecution);
+        if (feature.planningMode && feature.planningMode !== 'skip') {
+          this.eventBus.emitAutoModeEvent('planning_started', {
+            featureId: feature.id,
+            mode: feature.planningMode,
+            message: `Starting ${feature.planningMode} planning phase`,
+          });
+        }
+      }
+
+      const imagePaths = feature.imagePaths?.map((img) =>
+        typeof img === 'string' ? img : img.path
+      );
+      const model = resolveModelString(feature.model, DEFAULT_MODELS.claude);
+      tempRunningFeature.model = model;
+      tempRunningFeature.provider = ProviderFactory.getProviderNameForModel(model);
+
+      await this.runAgentFn(
+        workDir,
+        featureId,
+        prompt,
+        abortController,
+        projectPath,
+        imagePaths,
+        model,
+        {
+          projectPath,
+          planningMode: feature.planningMode,
+          requirePlanApproval: feature.requirePlanApproval,
+          systemPrompt: combinedSystemPrompt || undefined,
+          autoLoadClaudeMd,
+          thinkingLevel: feature.thinkingLevel,
+          branchName: feature.branchName ?? null,
+        }
+      );
+
+      // Check for incomplete tasks after agent execution.
+      // The agent may have finished early (hit max turns, decided it was done, etc.)
+      // while tasks are still pending. If so, re-run the agent to complete remaining tasks.
+      const MAX_TASK_RETRY_ATTEMPTS = 3;
+      let taskRetryAttempts = 0;
+      while (!abortController.signal.aborted && taskRetryAttempts < MAX_TASK_RETRY_ATTEMPTS) {
+        const currentFeature = await this.loadFeatureFn(projectPath, featureId);
+        if (!currentFeature?.planSpec?.tasks) break;
+
+        const pendingTasks = currentFeature.planSpec.tasks.filter(
+          (t) => t.status === 'pending' || t.status === 'in_progress'
+        );
+        if (pendingTasks.length === 0) break;
+
+        taskRetryAttempts++;
+        const totalTasks = currentFeature.planSpec.tasks.length;
+        const completedTasks = currentFeature.planSpec.tasks.filter(
+          (t) => t.status === 'completed'
+        ).length;
+        logger.info(
+          `[executeFeature] Feature ${featureId} has ${pendingTasks.length} incomplete tasks (${completedTasks}/${totalTasks} completed). Re-running agent (attempt ${taskRetryAttempts}/${MAX_TASK_RETRY_ATTEMPTS})`
+        );
+
+        this.eventBus.emitAutoModeEvent('auto_mode_progress', {
+          featureId,
+          branchName: feature.branchName ?? null,
+          content: `Agent finished with ${pendingTasks.length} tasks remaining. Re-running to complete tasks (attempt ${taskRetryAttempts}/${MAX_TASK_RETRY_ATTEMPTS})...`,
+          projectPath,
+        });
+
+        // Build a continuation prompt that tells the agent to finish remaining tasks
+        const remainingTasksList = pendingTasks
+          .map((t) => `- ${t.id}: ${t.description} (${t.status})`)
+          .join('\n');
+
+        const continuationPrompt = `## Continue Implementation - Incomplete Tasks
+
+The previous agent session ended before all tasks were completed. Please continue implementing the remaining tasks.
+
+**Completed:** ${completedTasks}/${totalTasks} tasks
+**Remaining tasks:**
+${remainingTasksList}
+
+Please continue from where you left off and complete all remaining tasks. Use the same [TASK_START:ID] and [TASK_COMPLETE:ID] markers for each task.`;
+
+        await this.runAgentFn(
+          workDir,
+          featureId,
+          continuationPrompt,
+          abortController,
+          projectPath,
+          undefined,
+          model,
+          {
+            projectPath,
+            planningMode: 'skip',
+            requirePlanApproval: false,
+            systemPrompt: combinedSystemPrompt || undefined,
+            autoLoadClaudeMd,
+            thinkingLevel: feature.thinkingLevel,
+            branchName: feature.branchName ?? null,
+          }
+        );
+      }
+
+      // Log if tasks are still incomplete after retry attempts
+      if (taskRetryAttempts >= MAX_TASK_RETRY_ATTEMPTS) {
+        const finalFeature = await this.loadFeatureFn(projectPath, featureId);
+        const stillPending = finalFeature?.planSpec?.tasks?.filter(
+          (t) => t.status === 'pending' || t.status === 'in_progress'
+        );
+        if (stillPending && stillPending.length > 0) {
+          logger.warn(
+            `[executeFeature] Feature ${featureId} still has ${stillPending.length} incomplete tasks after ${MAX_TASK_RETRY_ATTEMPTS} retry attempts. Moving to final status.`
+          );
+        }
+      }
+
+      const pipelineConfig = await pipelineService.getPipelineConfig(projectPath);
+      const excludedStepIds = new Set(feature.excludedPipelineSteps || []);
+      const sortedSteps = [...(pipelineConfig?.steps || [])]
+        .sort((a, b) => a.order - b.order)
+        .filter((step) => !excludedStepIds.has(step.id));
+      if (sortedSteps.length > 0) {
+        await this.executePipelineFn({
+          projectPath,
+          featureId,
+          feature,
+          steps: sortedSteps,
+          workDir,
+          worktreePath,
+          branchName: feature.branchName ?? null,
+          abortController,
+          autoLoadClaudeMd,
+          testAttempts: 0,
+          maxTestAttempts: 5,
+        });
+        // Check if pipeline set a terminal status (e.g., merge_conflict) — don't overwrite it
+        const refreshed = await this.loadFeatureFn(projectPath, featureId);
+        if (refreshed?.status === 'merge_conflict') {
+          return;
+        }
+      }
+
+      const finalStatus = feature.skipTests ? 'waiting_approval' : 'verified';
+      await this.updateFeatureStatusFn(projectPath, featureId, finalStatus);
+      this.recordSuccessFn();
+
+      // Check final task completion state for accurate reporting
+      const completedFeature = await this.loadFeatureFn(projectPath, featureId);
+      const totalTasks = completedFeature?.planSpec?.tasks?.length ?? 0;
+      const completedTasks =
+        completedFeature?.planSpec?.tasks?.filter((t) => t.status === 'completed').length ?? 0;
+      const hasIncompleteTasks = totalTasks > 0 && completedTasks < totalTasks;
+
+      try {
+        const outputPath = path.join(getFeatureDir(projectPath, featureId), 'agent-output.md');
+        let agentOutput = '';
+        try {
+          agentOutput = (await secureFs.readFile(outputPath, 'utf-8')) as string;
+        } catch {
+          /* */
+        }
+        if (agentOutput) {
+          const summary = extractSummary(agentOutput);
+          if (summary) await this.saveFeatureSummaryFn(projectPath, featureId, summary);
+        }
+        if (contextResult.memoryFiles.length > 0 && agentOutput) {
+          await recordMemoryUsage(
+            projectPath,
+            contextResult.memoryFiles,
+            agentOutput,
+            true,
+            secureFs as Parameters<typeof recordMemoryUsage>[4]
+          );
+        }
+        await this.recordLearningsFn(projectPath, feature, agentOutput);
+      } catch {
+        /* learnings recording failed */
+      }
+
+      const elapsedSeconds = Math.round((Date.now() - tempRunningFeature.startTime) / 1000);
+      let completionMessage = `Feature completed in ${elapsedSeconds}s`;
+      if (finalStatus === 'verified') completionMessage += ' - auto-verified';
+      if (hasIncompleteTasks)
+        completionMessage += ` (${completedTasks}/${totalTasks} tasks completed)`;
+
+      this.eventBus.emitAutoModeEvent('auto_mode_feature_complete', {
+        featureId,
+        featureName: feature.title,
+        branchName: feature.branchName ?? null,
+        passes: true,
+        message: completionMessage,
+        projectPath,
+        model: tempRunningFeature.model,
+        provider: tempRunningFeature.provider,
+      });
+    } catch (error) {
+      const errorInfo = classifyError(error);
+      if (errorInfo.isAbort) {
+        await this.updateFeatureStatusFn(projectPath, featureId, 'interrupted');
+        this.eventBus.emitAutoModeEvent('auto_mode_feature_complete', {
+          featureId,
+          featureName: feature?.title,
+          branchName: feature?.branchName ?? null,
+          passes: false,
+          message: 'Feature stopped by user',
+          projectPath,
+        });
+      } else {
+        logger.error(`Feature ${featureId} failed:`, error);
+        await this.updateFeatureStatusFn(projectPath, featureId, 'backlog');
+        this.eventBus.emitAutoModeEvent('auto_mode_error', {
+          featureId,
+          featureName: feature?.title,
+          branchName: feature?.branchName ?? null,
+          error: errorInfo.message,
+          errorType: errorInfo.type,
+          projectPath,
+        });
+        if (this.trackFailureFn({ type: errorInfo.type, message: errorInfo.message })) {
+          this.signalPauseFn({ type: errorInfo.type, message: errorInfo.message });
+        }
+      }
+    } finally {
+      this.releaseRunningFeature(featureId);
+      if (isAutoMode && projectPath) await this.saveExecutionStateFn(projectPath);
+    }
+  }
+
+  async stopFeature(featureId: string): Promise<boolean> {
+    const running = this.concurrencyManager.getRunningFeature(featureId);
+    if (!running) return false;
+    running.abortController.abort();
+    this.releaseRunningFeature(featureId, { force: true });
+    return true;
+  }
+}

apps/server/src/services/execution-types.ts

@@ -0,0 +1,212 @@
+/**
+ * Execution Types - Type definitions for ExecutionService and related services
+ *
+ * Contains callback types used by ExecutionService for dependency injection,
+ * allowing the service to delegate to other services without circular dependencies.
+ */
+
+import type { Feature, PlanningMode, ThinkingLevel } from '@automaker/types';
+import type { loadContextFiles } from '@automaker/utils';
+import type { PipelineContext } from './pipeline-orchestrator.js';
+
+// =============================================================================
+// ExecutionService Callback Types
+// =============================================================================
+
+/**
+ * Function to run the agent with a prompt
+ */
+export type RunAgentFn = (
+  workDir: string,
+  featureId: string,
+  prompt: string,
+  abortController: AbortController,
+  projectPath: string,
+  imagePaths?: string[],
+  model?: string,
+  options?: {
+    projectPath?: string;
+    planningMode?: PlanningMode;
+    requirePlanApproval?: boolean;
+    previousContent?: string;
+    systemPrompt?: string;
+    autoLoadClaudeMd?: boolean;
+    thinkingLevel?: ThinkingLevel;
+    branchName?: string | null;
+  }
+) => Promise<void>;
+
+/**
+ * Function to execute pipeline steps
+ */
+export type ExecutePipelineFn = (context: PipelineContext) => Promise<void>;
+
+/**
+ * Function to update feature status
+ */
+export type UpdateFeatureStatusFn = (
+  projectPath: string,
+  featureId: string,
+  status: string
+) => Promise<void>;
+
+/**
+ * Function to load a feature by ID
+ */
+export type LoadFeatureFn = (projectPath: string, featureId: string) => Promise<Feature | null>;
+
+/**
+ * Function to get the planning prompt prefix based on feature's planning mode
+ */
+export type GetPlanningPromptPrefixFn = (feature: Feature) => Promise<string>;
+
+/**
+ * Function to save a feature summary
+ */
+export type SaveFeatureSummaryFn = (
+  projectPath: string,
+  featureId: string,
+  summary: string
+) => Promise<void>;
+
+/**
+ * Function to record learnings from a completed feature
+ */
+export type RecordLearningsFn = (
+  projectPath: string,
+  feature: Feature,
+  agentOutput: string
+) => Promise<void>;
+
+/**
+ * Function to check if context exists for a feature
+ */
+export type ContextExistsFn = (projectPath: string, featureId: string) => Promise<boolean>;
+
+/**
+ * Function to resume a feature (continues from saved context or starts fresh)
+ */
+export type ResumeFeatureFn = (
+  projectPath: string,
+  featureId: string,
+  useWorktrees: boolean,
+  _calledInternally: boolean
+) => Promise<void>;
+
+/**
+ * Function to track failure and check if pause threshold is reached
+ * Returns true if auto-mode should pause
+ */
+export type TrackFailureFn = (errorInfo: { type: string; message: string }) => boolean;
+
+/**
+ * Function to signal that auto-mode should pause due to failures
+ */
+export type SignalPauseFn = (errorInfo: { type: string; message: string }) => void;
+
+/**
+ * Function to record a successful execution (resets failure tracking)
+ */
+export type RecordSuccessFn = () => void;
+
+/**
+ * Function to save execution state
+ */
+export type SaveExecutionStateFn = (projectPath: string) => Promise<void>;
+
+/**
+ * Type alias for loadContextFiles function
+ */
+export type LoadContextFilesFn = typeof loadContextFiles;
+
+// =============================================================================
+// PipelineOrchestrator Callback Types
+// =============================================================================
+
+/**
+ * Function to build feature prompt
+ */
+export type BuildFeaturePromptFn = (
+  feature: Feature,
+  prompts: { implementationInstructions: string; playwrightVerificationInstructions: string }
+) => string;
+
+/**
+ * Function to execute a feature
+ */
+export type ExecuteFeatureFn = (
+  projectPath: string,
+  featureId: string,
+  useWorktrees: boolean,
+  isAutoMode: boolean,
+  providedWorktreePath?: string,
+  options?: { continuationPrompt?: string; _calledInternally?: boolean }
+) => Promise<void>;
+
+/**
+ * Function to run agent (for PipelineOrchestrator)
+ */
+export type PipelineRunAgentFn = (
+  workDir: string,
+  featureId: string,
+  prompt: string,
+  abortController: AbortController,
+  projectPath: string,
+  imagePaths?: string[],
+  model?: string,
+  options?: Record<string, unknown>
+) => Promise<void>;
+
+// =============================================================================
+// AutoLoopCoordinator Callback Types
+// =============================================================================
+
+/**
+ * Function to execute a feature in auto-loop
+ */
+export type AutoLoopExecuteFeatureFn = (
+  projectPath: string,
+  featureId: string,
+  useWorktrees: boolean,
+  isAutoMode: boolean
+) => Promise<void>;
+
+/**
+ * Function to load pending features for a worktree
+ */
+export type LoadPendingFeaturesFn = (
+  projectPath: string,
+  branchName: string | null
+) => Promise<Feature[]>;
+
+/**
+ * Function to save execution state for auto-loop
+ */
+export type AutoLoopSaveExecutionStateFn = (
+  projectPath: string,
+  branchName: string | null,
+  maxConcurrency: number
+) => Promise<void>;
+
+/**
+ * Function to clear execution state
+ */
+export type ClearExecutionStateFn = (
+  projectPath: string,
+  branchName: string | null
+) => Promise<void>;
+
+/**
+ * Function to reset stuck features
+ */
+export type ResetStuckFeaturesFn = (projectPath: string) => Promise<void>;
+
+/**
+ * Function to check if a feature is finished
+ */
+export type IsFeatureFinishedFn = (feature: Feature) => boolean;
+
+/**
+ * Function to check if a feature is running
+ */
+export type IsFeatureRunningFn = (featureId: string) => boolean;

apps/server/src/services/feature-state-manager.ts

@@ -0,0 +1,644 @@
+/**
+ * FeatureStateManager - Manages feature status updates with proper persistence
+ *
+ * Extracted from AutoModeService to provide a standalone service for:
+ * - Updating feature status with proper disk persistence
+ * - Handling corrupted JSON with backup recovery
+ * - Emitting events AFTER successful persistence (prevent stale data on refresh)
+ * - Resetting stuck features after server restart
+ *
+ * Key behaviors:
+ * - Persist BEFORE emit (Pitfall 2 from research)
+ * - Use readJsonWithRecovery for all reads
+ * - markInterrupted preserves pipeline_* statuses
+ */
+
+import path from 'path';
+import type { Feature, ParsedTask, PlanSpec } from '@automaker/types';
+import {
+  atomicWriteJson,
+  readJsonWithRecovery,
+  logRecoveryWarning,
+  DEFAULT_BACKUP_COUNT,
+  createLogger,
+} from '@automaker/utils';
+import { getFeatureDir, getFeaturesDir } from '@automaker/platform';
+import * as secureFs from '../lib/secure-fs.js';
+import type { EventEmitter } from '../lib/events.js';
+import type { AutoModeEventType } from './typed-event-bus.js';
+import { getNotificationService } from './notification-service.js';
+import { FeatureLoader } from './feature-loader.js';
+
+const logger = createLogger('FeatureStateManager');
+
+/**
+ * FeatureStateManager handles feature status updates with persistence guarantees.
+ *
+ * This service is responsible for:
+ * 1. Updating feature status and persisting to disk BEFORE emitting events
+ * 2. Handling corrupted JSON with automatic backup recovery
+ * 3. Resetting stuck features after server restarts
+ * 4. Managing justFinishedAt timestamps for UI badges
+ */
+export class FeatureStateManager {
+  private events: EventEmitter;
+  private featureLoader: FeatureLoader;
+
+  constructor(events: EventEmitter, featureLoader: FeatureLoader) {
+    this.events = events;
+    this.featureLoader = featureLoader;
+  }
+
+  /**
+   * Load a feature from disk with recovery support
+   *
+   * @param projectPath - Path to the project
+   * @param featureId - ID of the feature to load
+   * @returns The feature data, or null if not found/recoverable
+   */
+  async loadFeature(projectPath: string, featureId: string): Promise<Feature | null> {
+    const featureDir = getFeatureDir(projectPath, featureId);
+    const featurePath = path.join(featureDir, 'feature.json');
+
+    try {
+      const result = await readJsonWithRecovery<Feature | null>(featurePath, null, {
+        maxBackups: DEFAULT_BACKUP_COUNT,
+        autoRestore: true,
+      });
+      logRecoveryWarning(result, `Feature ${featureId}`, logger);
+      return result.data;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Update feature status with proper persistence and event ordering.
+   *
+   * IMPORTANT: Persists to disk BEFORE emitting events to prevent stale data
+   * on client refresh (Pitfall 2 from research).
+   *
+   * @param projectPath - Path to the project
+   * @param featureId - ID of the feature to update
+   * @param status - New status value
+   */
+  async updateFeatureStatus(projectPath: string, featureId: string, status: string): Promise<void> {
+    const featureDir = getFeatureDir(projectPath, featureId);
+    const featurePath = path.join(featureDir, 'feature.json');
+
+    try {
+      // Use recovery-enabled read for corrupted file handling
+      const result = await readJsonWithRecovery<Feature | null>(featurePath, null, {
+        maxBackups: DEFAULT_BACKUP_COUNT,
+        autoRestore: true,
+      });
+
+      logRecoveryWarning(result, `Feature ${featureId}`, logger);
+
+      const feature = result.data;
+      if (!feature) {
+        logger.warn(`Feature ${featureId} not found or could not be recovered`);
+        return;
+      }
+
+      feature.status = status;
+      feature.updatedAt = new Date().toISOString();
+
+      // Set justFinishedAt timestamp when moving to waiting_approval (agent just completed)
+      // Badge will show for 2 minutes after this timestamp
+      if (status === 'waiting_approval') {
+        feature.justFinishedAt = new Date().toISOString();
+
+        // Finalize task statuses when feature is done:
+        // - Mark any in_progress tasks as completed (agent finished but didn't explicitly complete them)
+        // - Do NOT mark pending tasks as completed (they were never started)
+        // - Clear currentTaskId since no task is actively running
+        // This prevents cards in "waiting for review" from appearing to still have running tasks
+        if (feature.planSpec?.tasks) {
+          let tasksFinalized = 0;
+          let tasksPending = 0;
+          for (const task of feature.planSpec.tasks) {
+            if (task.status === 'in_progress') {
+              task.status = 'completed';
+              tasksFinalized++;
+            } else if (task.status === 'pending') {
+              tasksPending++;
+            }
+          }
+          if (tasksFinalized > 0) {
+            logger.info(
+              `[updateFeatureStatus] Finalized ${tasksFinalized} in_progress tasks for feature ${featureId} moving to waiting_approval`
+            );
+          }
+          if (tasksPending > 0) {
+            logger.warn(
+              `[updateFeatureStatus] Feature ${featureId} moving to waiting_approval with ${tasksPending} pending (never started) tasks out of ${feature.planSpec.tasks.length} total`
+            );
+          }
+          // Update tasksCompleted count to reflect actual completed tasks
+          feature.planSpec.tasksCompleted = feature.planSpec.tasks.filter(
+            (t) => t.status === 'completed'
+          ).length;
+          feature.planSpec.currentTaskId = undefined;
+        }
+      } else if (status === 'verified') {
+        // Also finalize in_progress tasks when moving directly to verified (skipTests=false)
+        // Do NOT mark pending tasks as completed - they were never started
+        if (feature.planSpec?.tasks) {
+          let tasksFinalized = 0;
+          let tasksPending = 0;
+          for (const task of feature.planSpec.tasks) {
+            if (task.status === 'in_progress') {
+              task.status = 'completed';
+              tasksFinalized++;
+            } else if (task.status === 'pending') {
+              tasksPending++;
+            }
+          }
+          if (tasksFinalized > 0) {
+            logger.info(
+              `[updateFeatureStatus] Finalized ${tasksFinalized} in_progress tasks for feature ${featureId} moving to verified`
+            );
+          }
+          if (tasksPending > 0) {
+            logger.warn(
+              `[updateFeatureStatus] Feature ${featureId} moving to verified with ${tasksPending} pending (never started) tasks out of ${feature.planSpec.tasks.length} total`
+            );
+          }
+          feature.planSpec.tasksCompleted = feature.planSpec.tasks.filter(
+            (t) => t.status === 'completed'
+          ).length;
+          feature.planSpec.currentTaskId = undefined;
+        }
+        // Clear the timestamp when moving to other statuses
+        feature.justFinishedAt = undefined;
+      } else {
+        // Clear the timestamp when moving to other statuses
+        feature.justFinishedAt = undefined;
+      }
+
+      // PERSIST BEFORE EMIT (Pitfall 2)
+      await atomicWriteJson(featurePath, feature, { backupCount: DEFAULT_BACKUP_COUNT });
+
+      // Emit status change event so UI can react without polling
+      this.emitAutoModeEvent('feature_status_changed', {
+        featureId,
+        projectPath,
+        status,
+      });
+
+      // Create notifications for important status changes
+      // Wrapped in try-catch so failures don't block syncFeatureToAppSpec below
+      try {
+        const notificationService = getNotificationService();
+        if (status === 'waiting_approval') {
+          await notificationService.createNotification({
+            type: 'feature_waiting_approval',
+            title: 'Feature Ready for Review',
+            message: `"${feature.name || featureId}" is ready for your review and approval.`,
+            featureId,
+            projectPath,
+          });
+        } else if (status === 'verified') {
+          await notificationService.createNotification({
+            type: 'feature_verified',
+            title: 'Feature Verified',
+            message: `"${feature.name || featureId}" has been verified and is complete.`,
+            featureId,
+            projectPath,
+          });
+        }
+      } catch (notificationError) {
+        logger.warn(`Failed to create notification for feature ${featureId}:`, notificationError);
+      }
+
+      // Sync completed/verified features to app_spec.txt
+      if (status === 'verified' || status === 'completed') {
+        try {
+          await this.featureLoader.syncFeatureToAppSpec(projectPath, feature);
+        } catch (syncError) {
+          // Log but don't fail the status update if sync fails
+          logger.warn(`Failed to sync feature ${featureId} to app_spec.txt:`, syncError);
+        }
+      }
+    } catch (error) {
+      logger.error(`Failed to update feature status for ${featureId}:`, error);
+    }
+  }
+
+  /**
+   * Mark a feature as interrupted due to server restart or other interruption.
+   *
+   * This is a convenience helper that updates the feature status to 'interrupted',
+   * indicating the feature was in progress but execution was disrupted (e.g., server
+   * restart, process crash, or manual stop). Features with this status can be
+   * resumed later using the resume functionality.
+   *
+   * Note: Features with pipeline_* statuses are preserved rather than overwritten
+   * to 'interrupted'. This ensures that resumePipelineFeature() can pick up from
+   * the correct pipeline step after a restart.
+   *
+   * @param projectPath - Path to the project
+   * @param featureId - ID of the feature to mark as interrupted
+   * @param reason - Optional reason for the interruption (logged for debugging)
+   */
+  async markFeatureInterrupted(
+    projectPath: string,
+    featureId: string,
+    reason?: string
+  ): Promise<void> {
+    // Load the feature to check its current status
+    const feature = await this.loadFeature(projectPath, featureId);
+    const currentStatus = feature?.status;
+
+    // Preserve pipeline_* statuses so resumePipelineFeature can resume from the correct step
+    if (currentStatus && currentStatus.startsWith('pipeline_')) {
+      logger.info(
+        `Feature ${featureId} was in ${currentStatus}; preserving pipeline status for resume`
+      );
+      return;
+    }
+
+    if (reason) {
+      logger.info(`Marking feature ${featureId} as interrupted: ${reason}`);
+    } else {
+      logger.info(`Marking feature ${featureId} as interrupted`);
+    }
+
+    await this.updateFeatureStatus(projectPath, featureId, 'interrupted');
+  }
+
+  /**
+   * Shared helper that scans features in a project directory and resets any stuck
+   * in transient states (in_progress, interrupted, pipeline_*) back to resting states.
+   *
+   * Also resets:
+   * - generating planSpec status back to pending
+   * - in_progress tasks back to pending
+   *
+   * @param projectPath - The project path to scan
+   * @param callerLabel - Label for log messages (e.g., 'resetStuckFeatures', 'reconcileAllFeatureStates')
+   * @returns Object with reconciledFeatures (id + status info), reconciledCount, and scanned count
+   */
+  private async scanAndResetFeatures(
+    projectPath: string,
+    callerLabel: string
+  ): Promise<{
+    reconciledFeatures: Array<{
+      id: string;
+      previousStatus: string | undefined;
+      newStatus: string | undefined;
+    }>;
+    reconciledFeatureIds: string[];
+    reconciledCount: number;
+    scanned: number;
+  }> {
+    const featuresDir = getFeaturesDir(projectPath);
+    let scanned = 0;
+    let reconciledCount = 0;
+    const reconciledFeatureIds: string[] = [];
+    const reconciledFeatures: Array<{
+      id: string;
+      previousStatus: string | undefined;
+      newStatus: string | undefined;
+    }> = [];
+
+    try {
+      const entries = await secureFs.readdir(featuresDir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+
+        scanned++;
+        const featurePath = path.join(featuresDir, entry.name, 'feature.json');
+        const result = await readJsonWithRecovery<Feature | null>(featurePath, null, {
+          maxBackups: DEFAULT_BACKUP_COUNT,
+          autoRestore: true,
+        });
+
+        const feature = result.data;
+        if (!feature) continue;
+
+        let needsUpdate = false;
+        const originalStatus = feature.status;
+
+        // Reset features in active execution states back to a resting state
+        // After a server restart, no processes are actually running
+        const isActiveState =
+          originalStatus === 'in_progress' ||
+          originalStatus === 'interrupted' ||
+          (originalStatus != null && originalStatus.startsWith('pipeline_'));
+
+        if (isActiveState) {
+          const hasApprovedPlan = feature.planSpec?.status === 'approved';
+          feature.status = hasApprovedPlan ? 'ready' : 'backlog';
+          needsUpdate = true;
+          logger.info(
+            `[${callerLabel}] Reset feature ${feature.id} from ${originalStatus} to ${feature.status}`
+          );
+        }
+
+        // Reset generating planSpec status back to pending (spec generation was interrupted)
+        if (feature.planSpec?.status === 'generating') {
+          feature.planSpec.status = 'pending';
+          needsUpdate = true;
+          logger.info(
+            `[${callerLabel}] Reset feature ${feature.id} planSpec status from generating to pending`
+          );
+        }
+
+        // Reset any in_progress tasks back to pending (task execution was interrupted)
+        if (feature.planSpec?.tasks) {
+          for (const task of feature.planSpec.tasks) {
+            if (task.status === 'in_progress') {
+              task.status = 'pending';
+              needsUpdate = true;
+              logger.info(
+                `[${callerLabel}] Reset task ${task.id} for feature ${feature.id} from in_progress to pending`
+              );
+              // Clear currentTaskId if it points to this reverted task
+              if (feature.planSpec?.currentTaskId === task.id) {
+                feature.planSpec.currentTaskId = undefined;
+                logger.info(
+                  `[${callerLabel}] Cleared planSpec.currentTaskId for feature ${feature.id} (was pointing to reverted task ${task.id})`
+                );
+              }
+            }
+          }
+        }
+
+        if (needsUpdate) {
+          feature.updatedAt = new Date().toISOString();
+          await atomicWriteJson(featurePath, feature, { backupCount: DEFAULT_BACKUP_COUNT });
+          reconciledCount++;
+          reconciledFeatureIds.push(feature.id);
+          reconciledFeatures.push({
+            id: feature.id,
+            previousStatus: originalStatus,
+            newStatus: feature.status,
+          });
+        }
+      }
+    } catch (error) {
+      // If features directory doesn't exist, that's fine
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+        logger.error(`[${callerLabel}] Error resetting features for ${projectPath}:`, error);
+      }
+    }
+
+    return { reconciledFeatures, reconciledFeatureIds, reconciledCount, scanned };
+  }
+
+  /**
+   * Reset features that were stuck in transient states due to server crash.
+   * Called when auto mode is enabled to clean up from previous session.
+   *
+   * Resets:
+   * - in_progress features back to ready (if has plan) or backlog (if no plan)
+   * - interrupted features back to ready (if has plan) or backlog (if no plan)
+   * - pipeline_* features back to ready (if has plan) or backlog (if no plan)
+   * - generating planSpec status back to pending
+   * - in_progress tasks back to pending
+   *
+   * @param projectPath - The project path to reset features for
+   */
+  async resetStuckFeatures(projectPath: string): Promise<void> {
+    const { reconciledCount, scanned } = await this.scanAndResetFeatures(
+      projectPath,
+      'resetStuckFeatures'
+    );
+
+    logger.info(
+      `[resetStuckFeatures] Scanned ${scanned} features, reset ${reconciledCount} features for ${projectPath}`
+    );
+  }
+
+  /**
+   * Reconcile all feature states on server startup.
+   *
+   * This method resets all features stuck in transient states (in_progress,
+   * interrupted, pipeline_*) and emits events so connected UI clients
+   * immediately reflect the corrected states.
+   *
+   * Should be called once during server initialization, before the UI is served,
+   * to ensure feature state consistency after any type of restart (clean, forced, crash).
+   *
+   * @param projectPath - The project path to reconcile features for
+   * @returns The number of features that were reconciled
+   */
+  async reconcileAllFeatureStates(projectPath: string): Promise<number> {
+    logger.info(`[reconcileAllFeatureStates] Starting reconciliation for ${projectPath}`);
+
+    const { reconciledFeatures, reconciledFeatureIds, reconciledCount, scanned } =
+      await this.scanAndResetFeatures(projectPath, 'reconcileAllFeatureStates');
+
+    // Emit per-feature status change events so UI invalidates its cache
+    for (const { id, previousStatus, newStatus } of reconciledFeatures) {
+      this.emitAutoModeEvent('feature_status_changed', {
+        featureId: id,
+        projectPath,
+        status: newStatus,
+        previousStatus,
+        reason: 'server_restart_reconciliation',
+      });
+    }
+
+    // Emit a bulk reconciliation event for the UI
+    if (reconciledCount > 0) {
+      this.emitAutoModeEvent('features_reconciled', {
+        projectPath,
+        reconciledCount,
+        reconciledFeatureIds,
+        message: `Reconciled ${reconciledCount} feature(s) after server restart`,
+      });
+    }
+
+    logger.info(
+      `[reconcileAllFeatureStates] Scanned ${scanned} features, reconciled ${reconciledCount} for ${projectPath}`
+    );
+
+    return reconciledCount;
+  }
+
+  /**
+   * Update the planSpec of a feature with partial updates.
+   *
+   * @param projectPath - The project path
+   * @param featureId - The feature ID
+   * @param updates - Partial PlanSpec updates to apply
+   */
+  async updateFeaturePlanSpec(
+    projectPath: string,
+    featureId: string,
+    updates: Partial<PlanSpec>
+  ): Promise<void> {
+    const featureDir = getFeatureDir(projectPath, featureId);
+    const featurePath = path.join(featureDir, 'feature.json');
+
+    try {
+      const result = await readJsonWithRecovery<Feature | null>(featurePath, null, {
+        maxBackups: DEFAULT_BACKUP_COUNT,
+        autoRestore: true,
+      });
+
+      logRecoveryWarning(result, `Feature ${featureId}`, logger);
+
+      const feature = result.data;
+      if (!feature) {
+        logger.warn(`Feature ${featureId} not found or could not be recovered`);
+        return;
+      }
+
+      // Initialize planSpec if it doesn't exist
+      if (!feature.planSpec) {
+        feature.planSpec = {
+          status: 'pending',
+          version: 1,
+          reviewedByUser: false,
+        };
+      }
+
+      // Capture old content BEFORE applying updates for version comparison
+      const oldContent = feature.planSpec.content;
+
+      // Apply updates
+      Object.assign(feature.planSpec, updates);
+
+      // If content is being updated and it's different from old content, increment version
+      if (updates.content !== undefined && updates.content !== oldContent) {
+        feature.planSpec.version = (feature.planSpec.version || 0) + 1;
+      }
+
+      feature.updatedAt = new Date().toISOString();
+
+      // PERSIST BEFORE EMIT
+      await atomicWriteJson(featurePath, feature, { backupCount: DEFAULT_BACKUP_COUNT });
+
+      // Emit event for UI update
+      this.emitAutoModeEvent('plan_spec_updated', {
+        featureId,
+        projectPath,
+        planSpec: feature.planSpec,
+      });
+    } catch (error) {
+      logger.error(`Failed to update planSpec for ${featureId}:`, error);
+    }
+  }
+
+  /**
+   * Save the extracted summary to a feature's summary field.
+   * This is called after agent execution completes to save a summary
+   * extracted from the agent's output using <summary> tags.
+   *
+   * @param projectPath - The project path
+   * @param featureId - The feature ID
+   * @param summary - The summary text to save
+   */
+  async saveFeatureSummary(projectPath: string, featureId: string, summary: string): Promise<void> {
+    const featureDir = getFeatureDir(projectPath, featureId);
+    const featurePath = path.join(featureDir, 'feature.json');
+
+    try {
+      const result = await readJsonWithRecovery<Feature | null>(featurePath, null, {
+        maxBackups: DEFAULT_BACKUP_COUNT,
+        autoRestore: true,
+      });
+
+      logRecoveryWarning(result, `Feature ${featureId}`, logger);
+
+      const feature = result.data;
+      if (!feature) {
+        logger.warn(`Feature ${featureId} not found or could not be recovered`);
+        return;
+      }
+
+      feature.summary = summary;
+      feature.updatedAt = new Date().toISOString();
+
+      // PERSIST BEFORE EMIT
+      await atomicWriteJson(featurePath, feature, { backupCount: DEFAULT_BACKUP_COUNT });
+
+      // Emit event for UI update
+      this.emitAutoModeEvent('auto_mode_summary', {
+        featureId,
+        projectPath,
+        summary,
+      });
+    } catch (error) {
+      logger.error(`Failed to save summary for ${featureId}:`, error);
+    }
+  }
+
+  /**
+   * Update the status of a specific task within planSpec.tasks
+   *
+   * @param projectPath - The project path
+   * @param featureId - The feature ID
+   * @param taskId - The task ID to update
+   * @param status - The new task status
+   */
+  async updateTaskStatus(
+    projectPath: string,
+    featureId: string,
+    taskId: string,
+    status: ParsedTask['status']
+  ): Promise<void> {
+    const featureDir = getFeatureDir(projectPath, featureId);
+    const featurePath = path.join(featureDir, 'feature.json');
+
+    try {
+      const result = await readJsonWithRecovery<Feature | null>(featurePath, null, {
+        maxBackups: DEFAULT_BACKUP_COUNT,
+        autoRestore: true,
+      });
+
+      logRecoveryWarning(result, `Feature ${featureId}`, logger);
+
+      const feature = result.data;
+      if (!feature || !feature.planSpec?.tasks) {
+        logger.warn(`Feature ${featureId} not found or has no tasks`);
+        return;
+      }
+
+      // Find and update the task
+      const task = feature.planSpec.tasks.find((t) => t.id === taskId);
+      if (task) {
+        task.status = status;
+        feature.updatedAt = new Date().toISOString();
+
+        // PERSIST BEFORE EMIT
+        await atomicWriteJson(featurePath, feature, { backupCount: DEFAULT_BACKUP_COUNT });
+
+        // Emit event for UI update
+        this.emitAutoModeEvent('auto_mode_task_status', {
+          featureId,
+          projectPath,
+          taskId,
+          status,
+          tasks: feature.planSpec.tasks,
+        });
+      } else {
+        const availableIds = feature.planSpec.tasks.map((t) => t.id).join(', ');
+        logger.warn(
+          `[updateTaskStatus] Task ${taskId} not found in feature ${featureId} (${projectPath}). Available task IDs: [${availableIds}]`
+        );
+      }
+    } catch (error) {
+      logger.error(`Failed to update task ${taskId} status for ${featureId}:`, error);
+    }
+  }
+
+  /**
+   * Emit an auto-mode event via the event emitter
+   *
+   * @param eventType - The event type (e.g., 'auto_mode_summary')
+   * @param data - The event payload
+   */
+  private emitAutoModeEvent(eventType: AutoModeEventType, data: Record<string, unknown>): void {
+    // Wrap the event in auto-mode:event format expected by the client
+    this.events.emit('auto-mode:event', {
+      type: eventType,
+      ...data,
+    });
+  }
+}

apps/server/src/services/ideation-service.ts

@@ -230,10 +230,9 @@ export class IdeationService {
         );
         if (providerResult.provider) {
           claudeCompatibleProvider = providerResult.provider;
-          // Use resolved model from provider if available (maps to Claude model)
-          if (providerResult.resolvedModel) {
-            modelId = providerResult.resolvedModel;
-          }
+          // CRITICAL: For custom providers, use the provider's model ID (e.g. "GLM-4.7")
+          // for the API call, NOT the resolved Claude model - otherwise we get "model not found"
+          modelId = options.model;
           credentials = providerResult.credentials ?? credentials;
         }
       }
@@ -889,7 +888,7 @@ ${contextSection}${existingWorkSection}`;
 
     for (const line of lines) {
       // Check for numbered items or markdown headers
-      const titleMatch = line.match(/^(?:\d+[\.\)]\s*\*{0,2}|#{1,3}\s+)(.+)/);
+      const titleMatch = line.match(/^(?:\d+[.)]\s*\*{0,2}|#{1,3}\s+)(.+)/);
 
       if (titleMatch) {
         // Save previous suggestion

apps/server/src/services/merge-service.ts

@@ -0,0 +1,185 @@
+/**
+ * MergeService - Direct merge operations without HTTP
+ *
+ * Extracted from worktree merge route to allow internal service calls.
+ */
+
+import { createLogger } from '@automaker/utils';
+import { spawnProcess } from '@automaker/platform';
+const logger = createLogger('MergeService');
+
+export interface MergeOptions {
+  squash?: boolean;
+  message?: string;
+  deleteWorktreeAndBranch?: boolean;
+}
+
+export interface MergeServiceResult {
+  success: boolean;
+  error?: string;
+  hasConflicts?: boolean;
+  mergedBranch?: string;
+  targetBranch?: string;
+  deleted?: {
+    worktreeDeleted: boolean;
+    branchDeleted: boolean;
+  };
+}
+
+/**
+ * Execute git command with array arguments to prevent command injection.
+ */
+async function execGitCommand(args: string[], cwd: string): Promise<string> {
+  const result = await spawnProcess({
+    command: 'git',
+    args,
+    cwd,
+  });
+
+  if (result.exitCode === 0) {
+    return result.stdout;
+  } else {
+    const errorMessage = result.stderr || `Git command failed with code ${result.exitCode}`;
+    throw new Error(errorMessage);
+  }
+}
+
+/**
+ * Validate branch name to prevent command injection.
+ */
+function isValidBranchName(name: string): boolean {
+  return /^[a-zA-Z0-9._\-/]+$/.test(name) && name.length < 250;
+}
+
+/**
+ * Perform a git merge operation directly without HTTP.
+ *
+ * @param projectPath - Path to the git repository
+ * @param branchName - Source branch to merge
+ * @param worktreePath - Path to the worktree (used for deletion if requested)
+ * @param targetBranch - Branch to merge into (defaults to 'main')
+ * @param options - Merge options (squash, message, deleteWorktreeAndBranch)
+ */
+export async function performMerge(
+  projectPath: string,
+  branchName: string,
+  worktreePath: string,
+  targetBranch: string = 'main',
+  options?: MergeOptions
+): Promise<MergeServiceResult> {
+  if (!projectPath || !branchName || !worktreePath) {
+    return {
+      success: false,
+      error: 'projectPath, branchName, and worktreePath are required',
+    };
+  }
+
+  const mergeTo = targetBranch || 'main';
+
+  // Validate branch names early to reject invalid input before any git operations
+  if (!isValidBranchName(branchName)) {
+    return {
+      success: false,
+      error: `Invalid source branch name: "${branchName}"`,
+    };
+  }
+  if (!isValidBranchName(mergeTo)) {
+    return {
+      success: false,
+      error: `Invalid target branch name: "${mergeTo}"`,
+    };
+  }
+
+  // Validate source branch exists (using safe array-based command)
+  try {
+    await execGitCommand(['rev-parse', '--verify', branchName], projectPath);
+  } catch {
+    return {
+      success: false,
+      error: `Branch "${branchName}" does not exist`,
+    };
+  }
+
+  // Validate target branch exists (using safe array-based command)
+  try {
+    await execGitCommand(['rev-parse', '--verify', mergeTo], projectPath);
+  } catch {
+    return {
+      success: false,
+      error: `Target branch "${mergeTo}" does not exist`,
+    };
+  }
+
+  // Merge the feature branch into the target branch (using safe array-based commands)
+  const mergeMessage = options?.message || `Merge ${branchName} into ${mergeTo}`;
+  const mergeArgs = options?.squash
+    ? ['merge', '--squash', branchName]
+    : ['merge', branchName, '-m', mergeMessage];
+
+  try {
+    await execGitCommand(mergeArgs, projectPath);
+  } catch (mergeError: unknown) {
+    // Check if this is a merge conflict
+    const err = mergeError as { stdout?: string; stderr?: string; message?: string };
+    const output = `${err.stdout || ''} ${err.stderr || ''} ${err.message || ''}`;
+    const hasConflicts = output.includes('CONFLICT') || output.includes('Automatic merge failed');
+
+    if (hasConflicts) {
+      return {
+        success: false,
+        error: `Merge CONFLICT: Automatic merge of "${branchName}" into "${mergeTo}" failed. Please resolve conflicts manually.`,
+        hasConflicts: true,
+      };
+    }
+
+    // Re-throw non-conflict errors
+    throw mergeError;
+  }
+
+  // If squash merge, need to commit (using safe array-based command)
+  if (options?.squash) {
+    const squashMessage = options?.message || `Merge ${branchName} (squash)`;
+    await execGitCommand(['commit', '-m', squashMessage], projectPath);
+  }
+
+  // Optionally delete the worktree and branch after merging
+  let worktreeDeleted = false;
+  let branchDeleted = false;
+
+  if (options?.deleteWorktreeAndBranch) {
+    // Remove the worktree
+    try {
+      await execGitCommand(['worktree', 'remove', worktreePath, '--force'], projectPath);
+      worktreeDeleted = true;
+    } catch {
+      // Try with prune if remove fails
+      try {
+        await execGitCommand(['worktree', 'prune'], projectPath);
+        worktreeDeleted = true;
+      } catch {
+        logger.warn(`Failed to remove worktree: ${worktreePath}`);
+      }
+    }
+
+    // Delete the branch (but not main/master)
+    if (branchName !== 'main' && branchName !== 'master') {
+      if (!isValidBranchName(branchName)) {
+        logger.warn(`Invalid branch name detected, skipping deletion: ${branchName}`);
+      } else {
+        try {
+          await execGitCommand(['branch', '-D', branchName], projectPath);
+          branchDeleted = true;
+        } catch {
+          logger.warn(`Failed to delete branch: ${branchName}`);
+        }
+      }
+    }
+  }
+
+  return {
+    success: true,
+    mergedBranch: branchName,
+    targetBranch: mergeTo,
+    deleted: options?.deleteWorktreeAndBranch ? { worktreeDeleted, branchDeleted } : undefined,
+  };
+}

apps/server/src/services/pipeline-orchestrator.ts

@@ -0,0 +1,612 @@
+/**
+ * PipelineOrchestrator - Pipeline step execution and coordination
+ */
+
+import path from 'path';
+import type {
+  Feature,
+  PipelineStep,
+  PipelineConfig,
+  FeatureStatusWithPipeline,
+} from '@automaker/types';
+import { createLogger, loadContextFiles, classifyError } from '@automaker/utils';
+import { getFeatureDir } from '@automaker/platform';
+import { resolveModelString, DEFAULT_MODELS } from '@automaker/model-resolver';
+import * as secureFs from '../lib/secure-fs.js';
+import {
+  getPromptCustomization,
+  getAutoLoadClaudeMdSetting,
+  filterClaudeMdFromContext,
+} from '../lib/settings-helpers.js';
+import { validateWorkingDirectory } from '../lib/sdk-options.js';
+import type { TypedEventBus } from './typed-event-bus.js';
+import type { FeatureStateManager } from './feature-state-manager.js';
+import type { AgentExecutor } from './agent-executor.js';
+import type { WorktreeResolver } from './worktree-resolver.js';
+import type { SettingsService } from './settings-service.js';
+import type { ConcurrencyManager } from './concurrency-manager.js';
+import { pipelineService } from './pipeline-service.js';
+import type { TestRunnerService, TestRunStatus } from './test-runner-service.js';
+import { performMerge } from './merge-service.js';
+import type {
+  PipelineContext,
+  PipelineStatusInfo,
+  StepResult,
+  MergeResult,
+  UpdateFeatureStatusFn,
+  BuildFeaturePromptFn,
+  ExecuteFeatureFn,
+  RunAgentFn,
+} from './pipeline-types.js';
+
+// Re-export types for backward compatibility
+export type {
+  PipelineContext,
+  PipelineStatusInfo,
+  StepResult,
+  MergeResult,
+  UpdateFeatureStatusFn,
+  BuildFeaturePromptFn,
+  ExecuteFeatureFn,
+  RunAgentFn,
+} from './pipeline-types.js';
+
+const logger = createLogger('PipelineOrchestrator');
+
+export class PipelineOrchestrator {
+  constructor(
+    private eventBus: TypedEventBus,
+    private featureStateManager: FeatureStateManager,
+    private agentExecutor: AgentExecutor,
+    private testRunnerService: TestRunnerService,
+    private worktreeResolver: WorktreeResolver,
+    private concurrencyManager: ConcurrencyManager,
+    private settingsService: SettingsService | null,
+    private updateFeatureStatusFn: UpdateFeatureStatusFn,
+    private loadContextFilesFn: typeof loadContextFiles,
+    private buildFeaturePromptFn: BuildFeaturePromptFn,
+    private executeFeatureFn: ExecuteFeatureFn,
+    private runAgentFn: RunAgentFn
+  ) {}
+
+  async executePipeline(ctx: PipelineContext): Promise<void> {
+    const { projectPath, featureId, feature, steps, workDir, abortController, autoLoadClaudeMd } =
+      ctx;
+    const prompts = await getPromptCustomization(this.settingsService, '[AutoMode]');
+    const contextResult = await this.loadContextFilesFn({
+      projectPath,
+      fsModule: secureFs as Parameters<typeof loadContextFiles>[0]['fsModule'],
+      taskContext: { title: feature.title ?? '', description: feature.description ?? '' },
+    });
+    const contextFilesPrompt = filterClaudeMdFromContext(contextResult, autoLoadClaudeMd);
+    const contextPath = path.join(getFeatureDir(projectPath, featureId), 'agent-output.md');
+    let previousContext = '';
+    try {
+      previousContext = (await secureFs.readFile(contextPath, 'utf-8')) as string;
+    } catch {
+      /* */
+    }
+
+    for (let i = 0; i < steps.length; i++) {
+      const step = steps[i];
+      if (abortController.signal.aborted) throw new Error('Pipeline execution aborted');
+      await this.updateFeatureStatusFn(projectPath, featureId, `pipeline_${step.id}`);
+      this.eventBus.emitAutoModeEvent('auto_mode_progress', {
+        featureId,
+        branchName: feature.branchName ?? null,
+        content: `Starting pipeline step ${i + 1}/${steps.length}: ${step.name}`,
+        projectPath,
+      });
+      this.eventBus.emitAutoModeEvent('pipeline_step_started', {
+        featureId,
+        stepId: step.id,
+        stepName: step.name,
+        stepIndex: i,
+        totalSteps: steps.length,
+        projectPath,
+      });
+      const model = resolveModelString(feature.model, DEFAULT_MODELS.claude);
+      await this.runAgentFn(
+        workDir,
+        featureId,
+        this.buildPipelineStepPrompt(step, feature, previousContext, prompts.taskExecution),
+        abortController,
+        projectPath,
+        undefined,
+        model,
+        {
+          projectPath,
+          planningMode: 'skip',
+          requirePlanApproval: false,
+          previousContent: previousContext,
+          systemPrompt: contextFilesPrompt || undefined,
+          autoLoadClaudeMd,
+          thinkingLevel: feature.thinkingLevel,
+        }
+      );
+      try {
+        previousContext = (await secureFs.readFile(contextPath, 'utf-8')) as string;
+      } catch {
+        /* */
+      }
+      this.eventBus.emitAutoModeEvent('pipeline_step_complete', {
+        featureId,
+        stepId: step.id,
+        stepName: step.name,
+        stepIndex: i,
+        totalSteps: steps.length,
+        projectPath,
+      });
+    }
+    if (ctx.branchName) {
+      const mergeResult = await this.attemptMerge(ctx);
+      if (!mergeResult.success && mergeResult.hasConflicts) return;
+    }
+  }
+
+  buildPipelineStepPrompt(
+    step: PipelineStep,
+    feature: Feature,
+    previousContext: string,
+    taskPrompts: { implementationInstructions: string; playwrightVerificationInstructions: string }
+  ): string {
+    let prompt = `## Pipeline Step: ${step.name}\n\nThis is an automated pipeline step.\n\n### Feature Context\n${this.buildFeaturePromptFn(feature, taskPrompts)}\n\n`;
+    if (previousContext) prompt += `### Previous Work\n${previousContext}\n\n`;
+    return (
+      prompt +
+      `### Pipeline Step Instructions\n${step.instructions}\n\n### Task\nComplete the pipeline step instructions above.`
+    );
+  }
+
+  async detectPipelineStatus(
+    projectPath: string,
+    featureId: string,
+    currentStatus: FeatureStatusWithPipeline
+  ): Promise<PipelineStatusInfo> {
+    const isPipeline = pipelineService.isPipelineStatus(currentStatus);
+    if (!isPipeline)
+      return {
+        isPipeline: false,
+        stepId: null,
+        stepIndex: -1,
+        totalSteps: 0,
+        step: null,
+        config: null,
+      };
+    const stepId = pipelineService.getStepIdFromStatus(currentStatus);
+    if (!stepId)
+      return {
+        isPipeline: true,
+        stepId: null,
+        stepIndex: -1,
+        totalSteps: 0,
+        step: null,
+        config: null,
+      };
+    const config = await pipelineService.getPipelineConfig(projectPath);
+    if (!config || config.steps.length === 0)
+      return { isPipeline: true, stepId, stepIndex: -1, totalSteps: 0, step: null, config: null };
+    const sortedSteps = [...config.steps].sort((a, b) => a.order - b.order);
+    const stepIndex = sortedSteps.findIndex((s) => s.id === stepId);
+    return {
+      isPipeline: true,
+      stepId,
+      stepIndex,
+      totalSteps: sortedSteps.length,
+      step: stepIndex === -1 ? null : sortedSteps[stepIndex],
+      config,
+    };
+  }
+
+  async resumePipeline(
+    projectPath: string,
+    feature: Feature,
+    useWorktrees: boolean,
+    pipelineInfo: PipelineStatusInfo
+  ): Promise<void> {
+    const featureId = feature.id;
+    const contextPath = path.join(getFeatureDir(projectPath, featureId), 'agent-output.md');
+    let hasContext = false;
+    try {
+      await secureFs.access(contextPath);
+      hasContext = true;
+    } catch {
+      /* No context */
+    }
+
+    if (!hasContext) {
+      logger.warn(`No context for feature ${featureId}, restarting pipeline`);
+      await this.updateFeatureStatusFn(projectPath, featureId, 'in_progress');
+      return this.executeFeatureFn(projectPath, featureId, useWorktrees, false, undefined, {
+        _calledInternally: true,
+      });
+    }
+
+    if (pipelineInfo.stepIndex === -1) {
+      logger.warn(`Step ${pipelineInfo.stepId} no longer exists, completing feature`);
+      const finalStatus = feature.skipTests ? 'waiting_approval' : 'verified';
+      await this.updateFeatureStatusFn(projectPath, featureId, finalStatus);
+      this.eventBus.emitAutoModeEvent('auto_mode_feature_complete', {
+        featureId,
+        featureName: feature.title,
+        branchName: feature.branchName ?? null,
+        passes: true,
+        message: 'Pipeline step no longer exists',
+        projectPath,
+      });
+      return;
+    }
+
+    if (!pipelineInfo.config) throw new Error('Pipeline config is null but stepIndex is valid');
+    return this.resumeFromStep(
+      projectPath,
+      feature,
+      useWorktrees,
+      pipelineInfo.stepIndex,
+      pipelineInfo.config
+    );
+  }
+
+  /** Resume from a specific step index */
+  async resumeFromStep(
+    projectPath: string,
+    feature: Feature,
+    useWorktrees: boolean,
+    startFromStepIndex: number,
+    pipelineConfig: PipelineConfig
+  ): Promise<void> {
+    const featureId = feature.id;
+    const allSortedSteps = [...pipelineConfig.steps].sort((a, b) => a.order - b.order);
+    if (startFromStepIndex < 0 || startFromStepIndex >= allSortedSteps.length)
+      throw new Error(`Invalid step index: ${startFromStepIndex}`);
+
+    const excludedStepIds = new Set(feature.excludedPipelineSteps || []);
+    let currentStep = allSortedSteps[startFromStepIndex];
+
+    if (excludedStepIds.has(currentStep.id)) {
+      const nextStatus = pipelineService.getNextStatus(
+        `pipeline_${currentStep.id}`,
+        pipelineConfig,
+        feature.skipTests ?? false,
+        feature.excludedPipelineSteps
+      );
+      if (!pipelineService.isPipelineStatus(nextStatus)) {
+        await this.updateFeatureStatusFn(projectPath, featureId, nextStatus);
+        this.eventBus.emitAutoModeEvent('auto_mode_feature_complete', {
+          featureId,
+          featureName: feature.title,
+          branchName: feature.branchName ?? null,
+          passes: true,
+          message: 'Pipeline completed (remaining steps excluded)',
+          projectPath,
+        });
+        return;
+      }
+      const nextStepId = pipelineService.getStepIdFromStatus(nextStatus);
+      const nextStepIndex = allSortedSteps.findIndex((s) => s.id === nextStepId);
+      if (nextStepIndex === -1) throw new Error(`Next step ${nextStepId} not found`);
+      startFromStepIndex = nextStepIndex;
+    }
+
+    const stepsToExecute = allSortedSteps
+      .slice(startFromStepIndex)
+      .filter((step) => !excludedStepIds.has(step.id));
+    if (stepsToExecute.length === 0) {
+      const finalStatus = feature.skipTests ? 'waiting_approval' : 'verified';
+      await this.updateFeatureStatusFn(projectPath, featureId, finalStatus);
+      this.eventBus.emitAutoModeEvent('auto_mode_feature_complete', {
+        featureId,
+        featureName: feature.title,
+        branchName: feature.branchName ?? null,
+        passes: true,
+        message: 'Pipeline completed (all steps excluded)',
+        projectPath,
+      });
+      return;
+    }
+
+    const runningEntry = this.concurrencyManager.acquire({
+      featureId,
+      projectPath,
+      isAutoMode: false,
+      allowReuse: true,
+    });
+    const abortController = runningEntry.abortController;
+    runningEntry.branchName = feature.branchName ?? null;
+
+    try {
+      validateWorkingDirectory(projectPath);
+      let worktreePath: string | null = null;
+      const branchName = feature.branchName;
+
+      if (useWorktrees && branchName) {
+        worktreePath = await this.worktreeResolver.findWorktreeForBranch(projectPath, branchName);
+        if (worktreePath) logger.info(`Using worktree for branch "${branchName}": ${worktreePath}`);
+      }
+
+      const workDir = worktreePath ? path.resolve(worktreePath) : path.resolve(projectPath);
+      validateWorkingDirectory(workDir);
+      runningEntry.worktreePath = worktreePath;
+      runningEntry.branchName = branchName ?? null;
+
+      this.eventBus.emitAutoModeEvent('auto_mode_feature_start', {
+        featureId,
+        projectPath,
+        branchName: branchName ?? null,
+        feature: {
+          id: featureId,
+          title: feature.title || 'Resuming Pipeline',
+          description: feature.description,
+        },
+      });
+
+      const autoLoadClaudeMd = await getAutoLoadClaudeMdSetting(
+        projectPath,
+        this.settingsService,
+        '[AutoMode]'
+      );
+      const context: PipelineContext = {
+        projectPath,
+        featureId,
+        feature,
+        steps: stepsToExecute,
+        workDir,
+        worktreePath,
+        branchName: branchName ?? null,
+        abortController,
+        autoLoadClaudeMd,
+        testAttempts: 0,
+        maxTestAttempts: 5,
+      };
+
+      await this.executePipeline(context);
+
+      // Re-fetch feature to check if executePipeline set a terminal status (e.g., merge_conflict)
+      const reloadedFeature = await this.featureStateManager.loadFeature(projectPath, featureId);
+      const finalStatus = feature.skipTests ? 'waiting_approval' : 'verified';
+
+      // Only update status if not already in a terminal state
+      if (reloadedFeature && reloadedFeature.status !== 'merge_conflict') {
+        await this.updateFeatureStatusFn(projectPath, featureId, finalStatus);
+      }
+      logger.info(`Pipeline resume completed for feature ${featureId}`);
+      this.eventBus.emitAutoModeEvent('auto_mode_feature_complete', {
+        featureId,
+        featureName: feature.title,
+        branchName: feature.branchName ?? null,
+        passes: true,
+        message: 'Pipeline resumed successfully',
+        projectPath,
+      });
+    } catch (error) {
+      const errorInfo = classifyError(error);
+      if (errorInfo.isAbort) {
+        this.eventBus.emitAutoModeEvent('auto_mode_feature_complete', {
+          featureId,
+          featureName: feature.title,
+          branchName: feature.branchName ?? null,
+          passes: false,
+          message: 'Pipeline stopped by user',
+          projectPath,
+        });
+      } else {
+        logger.error(`Pipeline resume failed for ${featureId}:`, error);
+        await this.updateFeatureStatusFn(projectPath, featureId, 'backlog');
+        this.eventBus.emitAutoModeEvent('auto_mode_error', {
+          featureId,
+          featureName: feature.title,
+          branchName: feature.branchName ?? null,
+          error: errorInfo.message,
+          errorType: errorInfo.type,
+          projectPath,
+        });
+      }
+    } finally {
+      this.concurrencyManager.release(featureId);
+    }
+  }
+
+  /** Execute test step with agent fix loop (REQ-F07) */
+  async executeTestStep(context: PipelineContext, testCommand: string): Promise<StepResult> {
+    const { featureId, projectPath, workDir, abortController, maxTestAttempts } = context;
+
+    for (let attempt = 1; attempt <= maxTestAttempts; attempt++) {
+      if (abortController.signal.aborted)
+        return { success: false, message: 'Test execution aborted' };
+      logger.info(`Running tests for ${featureId} (attempt ${attempt}/${maxTestAttempts})`);
+
+      const testResult = await this.testRunnerService.startTests(workDir, { command: testCommand });
+      if (!testResult.success || !testResult.result?.sessionId)
+        return {
+          success: false,
+          testsPassed: false,
+          message: testResult.error || 'Failed to start tests',
+        };
+
+      const completionResult = await this.waitForTestCompletion(
+        testResult.result.sessionId,
+        abortController.signal
+      );
+      if (completionResult.status === 'passed') return { success: true, testsPassed: true };
+
+      const sessionOutput = this.testRunnerService.getSessionOutput(testResult.result.sessionId);
+      const scrollback = sessionOutput.result?.output || '';
+      this.eventBus.emitAutoModeEvent('pipeline_test_failed', {
+        featureId,
+        attempt,
+        maxAttempts: maxTestAttempts,
+        failedTests: this.extractFailedTestNames(scrollback),
+        projectPath,
+      });
+
+      if (attempt < maxTestAttempts) {
+        const fixPrompt = `## Test Failures - Please Fix\n\n${this.buildTestFailureSummary(scrollback)}\n\nFix the failing tests without modifying test code unless clearly wrong.`;
+        await this.runAgentFn(
+          workDir,
+          featureId,
+          fixPrompt,
+          abortController,
+          projectPath,
+          undefined,
+          undefined,
+          { projectPath, planningMode: 'skip', requirePlanApproval: false }
+        );
+      }
+    }
+    return {
+      success: false,
+      testsPassed: false,
+      message: `Tests failed after ${maxTestAttempts} attempts`,
+    };
+  }
+
+  /** Wait for test completion */
+  private async waitForTestCompletion(
+    sessionId: string,
+    signal: AbortSignal
+  ): Promise<{ status: TestRunStatus; exitCode: number | null; duration: number }> {
+    return new Promise((resolve) => {
+      const checkInterval = setInterval(() => {
+        // Check for abort
+        if (signal.aborted) {
+          clearInterval(checkInterval);
+          clearTimeout(timeoutId);
+          resolve({ status: 'failed', exitCode: null, duration: 0 });
+          return;
+        }
+
+        const session = this.testRunnerService.getSession(sessionId);
+        if (session && session.status !== 'running' && session.status !== 'pending') {
+          clearInterval(checkInterval);
+          clearTimeout(timeoutId);
+          resolve({
+            status: session.status,
+            exitCode: session.exitCode,
+            duration: session.finishedAt
+              ? session.finishedAt.getTime() - session.startedAt.getTime()
+              : 0,
+          });
+        }
+      }, 1000);
+      const timeoutId = setTimeout(() => {
+        // Check for abort before timeout resolution
+        if (signal.aborted) {
+          clearInterval(checkInterval);
+          resolve({ status: 'failed', exitCode: null, duration: 0 });
+          return;
+        }
+        clearInterval(checkInterval);
+        resolve({ status: 'failed', exitCode: null, duration: 600000 });
+      }, 600000);
+    });
+  }
+
+  /** Attempt to merge feature branch (REQ-F05) */
+  async attemptMerge(context: PipelineContext): Promise<MergeResult> {
+    const { projectPath, featureId, branchName, worktreePath, feature } = context;
+    if (!branchName) return { success: false, error: 'No branch name for merge' };
+
+    logger.info(`Attempting auto-merge for feature ${featureId} (branch: ${branchName})`);
+    try {
+      // Get the primary branch dynamically instead of hardcoding 'main'
+      const targetBranch = await this.worktreeResolver.getCurrentBranch(projectPath);
+
+      // Call merge service directly instead of HTTP fetch
+      const result = await performMerge(
+        projectPath,
+        branchName,
+        worktreePath || projectPath,
+        targetBranch || 'main',
+        {
+          deleteWorktreeAndBranch: false,
+        }
+      );
+
+      if (!result.success) {
+        if (result.hasConflicts) {
+          await this.updateFeatureStatusFn(projectPath, featureId, 'merge_conflict');
+          this.eventBus.emitAutoModeEvent('pipeline_merge_conflict', {
+            featureId,
+            branchName,
+            projectPath,
+          });
+          return { success: false, hasConflicts: true, needsAgentResolution: true };
+        }
+        return { success: false, error: result.error };
+      }
+
+      logger.info(`Auto-merge successful for feature ${featureId}`);
+      this.eventBus.emitAutoModeEvent('auto_mode_feature_complete', {
+        featureId,
+        featureName: feature.title,
+        branchName,
+        passes: true,
+        message: 'Pipeline completed and merged',
+        projectPath,
+      });
+      return { success: true };
+    } catch (error) {
+      logger.error(`Merge failed for ${featureId}:`, error);
+      return { success: false, error: (error as Error).message };
+    }
+  }
+
+  /** Shared helper to parse test output lines and extract failure information */
+  private parseTestLines(scrollback: string): {
+    failedTests: string[];
+    passCount: number;
+    failCount: number;
+  } {
+    const lines = scrollback.split('\n');
+    const failedTests: string[] = [];
+    let passCount = 0;
+    let failCount = 0;
+
+    let inFailureContext = false;
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.includes('FAIL') || trimmed.includes('FAILED')) {
+        const match = trimmed.match(/(?:FAIL|FAILED)\s+(.+)/);
+        if (match) failedTests.push(match[1].trim());
+        failCount++;
+        inFailureContext = true;
+      } else if (trimmed.includes('PASS') || trimmed.includes('PASSED')) {
+        passCount++;
+        inFailureContext = false;
+      }
+      if (trimmed.match(/^>\s+.*\.(test|spec)\./)) {
+        failedTests.push(trimmed.replace(/^>\s+/, ''));
+      }
+      // Only capture assertion details when they appear in failure context
+      // or match explicit assertion error / expect patterns
+      if (trimmed.includes('AssertionError') || trimmed.includes('AssertionError')) {
+        failedTests.push(trimmed);
+      } else if (
+        inFailureContext &&
+        /expect\(.+\)\.(toBe|toEqual|toMatch|toThrow|toContain)\s*\(/.test(trimmed)
+      ) {
+        failedTests.push(trimmed);
+      } else if (
+        inFailureContext &&
+        (trimmed.startsWith('Expected') || trimmed.startsWith('Received'))
+      ) {
+        failedTests.push(trimmed);
+      }
+    }
+
+    return { failedTests, passCount, failCount };
+  }
+
+  /** Build a concise test failure summary for the agent */
+  buildTestFailureSummary(scrollback: string): string {
+    const { failedTests, passCount, failCount } = this.parseTestLines(scrollback);
+    const unique = [...new Set(failedTests)].slice(0, 10);
+    return `Test Results: ${passCount} passed, ${failCount} failed.\n\nFailed tests:\n${unique.map((t) => `- ${t}`).join('\n')}\n\nOutput (last 2000 chars):\n${scrollback.slice(-2000)}`;
+  }
+
+  /** Extract failed test names from scrollback */
+  private extractFailedTestNames(scrollback: string): string[] {
+    const { failedTests } = this.parseTestLines(scrollback);
+    return [...new Set(failedTests)].slice(0, 20);
+  }
+}

apps/server/src/services/pipeline-types.ts

@@ -0,0 +1,72 @@
+/**
+ * Pipeline Types - Type definitions for PipelineOrchestrator
+ */
+
+import type { Feature, PipelineStep, PipelineConfig } from '@automaker/types';
+
+export interface PipelineContext {
+  projectPath: string;
+  featureId: string;
+  feature: Feature;
+  steps: PipelineStep[];
+  workDir: string;
+  worktreePath: string | null;
+  branchName: string | null;
+  abortController: AbortController;
+  autoLoadClaudeMd: boolean;
+  testAttempts: number;
+  maxTestAttempts: number;
+}
+
+export interface PipelineStatusInfo {
+  isPipeline: boolean;
+  stepId: string | null;
+  stepIndex: number;
+  totalSteps: number;
+  step: PipelineStep | null;
+  config: PipelineConfig | null;
+}
+
+export interface StepResult {
+  success: boolean;
+  testsPassed?: boolean;
+  message?: string;
+}
+
+export interface MergeResult {
+  success: boolean;
+  hasConflicts?: boolean;
+  needsAgentResolution?: boolean;
+  error?: string;
+}
+
+export type UpdateFeatureStatusFn = (
+  projectPath: string,
+  featureId: string,
+  status: string
+) => Promise<void>;
+
+export type BuildFeaturePromptFn = (
+  feature: Feature,
+  prompts: { implementationInstructions: string; playwrightVerificationInstructions: string }
+) => string;
+
+export type ExecuteFeatureFn = (
+  projectPath: string,
+  featureId: string,
+  useWorktrees: boolean,
+  useScreenshots: boolean,
+  model?: string,
+  options?: { _calledInternally?: boolean }
+) => Promise<void>;
+
+export type RunAgentFn = (
+  workDir: string,
+  featureId: string,
+  prompt: string,
+  abortController: AbortController,
+  projectPath: string,
+  imagePaths?: string[],
+  model?: string,
+  options?: Record<string, unknown>
+) => Promise<void>;

apps/server/src/services/plan-approval-service.ts

@@ -0,0 +1,332 @@
+/**
+ * PlanApprovalService - Manages plan approval workflow with timeout and recovery
+ *
+ * Key behaviors:
+ * - Timeout stored in closure, wrapped resolve/reject ensures cleanup
+ * - Recovery returns needsRecovery flag (caller handles execution)
+ * - Auto-reject on timeout (safety feature, not auto-approve)
+ */
+
+import { createLogger } from '@automaker/utils';
+import type { TypedEventBus } from './typed-event-bus.js';
+import type { FeatureStateManager } from './feature-state-manager.js';
+import type { SettingsService } from './settings-service.js';
+
+const logger = createLogger('PlanApprovalService');
+
+/** Result returned when approval is resolved */
+export interface PlanApprovalResult {
+  approved: boolean;
+  editedPlan?: string;
+  feedback?: string;
+}
+
+/** Result returned from resolveApproval method */
+export interface ResolveApprovalResult {
+  success: boolean;
+  error?: string;
+  needsRecovery?: boolean;
+}
+
+/** Represents an orphaned approval that needs recovery after server restart */
+export interface OrphanedApproval {
+  featureId: string;
+  projectPath: string;
+  generatedAt?: string;
+  planContent?: string;
+}
+
+/** Internal: timeoutId stored in closure, NOT in this object */
+interface PendingApproval {
+  resolve: (result: PlanApprovalResult) => void;
+  reject: (error: Error) => void;
+  featureId: string;
+  projectPath: string;
+}
+
+/** Default timeout: 30 minutes */
+const DEFAULT_APPROVAL_TIMEOUT_MS = 30 * 60 * 1000;
+
+/**
+ * PlanApprovalService handles the plan approval workflow with lifecycle management.
+ */
+export class PlanApprovalService {
+  private pendingApprovals = new Map<string, PendingApproval>();
+  private eventBus: TypedEventBus;
+  private featureStateManager: FeatureStateManager;
+  private settingsService: SettingsService | null;
+
+  constructor(
+    eventBus: TypedEventBus,
+    featureStateManager: FeatureStateManager,
+    settingsService: SettingsService | null
+  ) {
+    this.eventBus = eventBus;
+    this.featureStateManager = featureStateManager;
+    this.settingsService = settingsService;
+  }
+
+  /** Generate project-scoped key to prevent collisions across projects */
+  private approvalKey(projectPath: string, featureId: string): string {
+    return `${projectPath}::${featureId}`;
+  }
+
+  /** Wait for plan approval with timeout (default 30 min). Rejects on timeout/cancellation. */
+  async waitForApproval(featureId: string, projectPath: string): Promise<PlanApprovalResult> {
+    const timeoutMs = await this.getTimeoutMs(projectPath);
+    const timeoutMinutes = Math.round(timeoutMs / 60000);
+    const key = this.approvalKey(projectPath, featureId);
+
+    logger.info(`Registering pending approval for feature ${featureId} in project ${projectPath}`);
+    logger.info(
+      `Current pending approvals: ${Array.from(this.pendingApprovals.keys()).join(', ') || 'none'}`
+    );
+
+    return new Promise((resolve, reject) => {
+      // Prevent duplicate registrations for the same key — reject and clean up existing entry
+      const existing = this.pendingApprovals.get(key);
+      if (existing) {
+        existing.reject(new Error('Superseded by a new waitForApproval call'));
+        this.pendingApprovals.delete(key);
+      }
+
+      // Wrap resolve/reject to clear timeout when approval is resolved
+      // This ensures timeout is ALWAYS cleared on any resolution path
+      // Define wrappers BEFORE setTimeout so they can be used in timeout callback
+      let timeoutId: NodeJS.Timeout;
+      const wrappedResolve = (result: PlanApprovalResult) => {
+        clearTimeout(timeoutId);
+        resolve(result);
+      };
+
+      const wrappedReject = (error: Error) => {
+        clearTimeout(timeoutId);
+        reject(error);
+      };
+
+      // Set up timeout to prevent indefinite waiting and memory leaks
+      // Now timeoutId assignment happens after wrappers are defined
+      timeoutId = setTimeout(() => {
+        const pending = this.pendingApprovals.get(key);
+        if (pending) {
+          logger.warn(
+            `Plan approval for feature ${featureId} timed out after ${timeoutMinutes} minutes`
+          );
+          this.pendingApprovals.delete(key);
+          wrappedReject(
+            new Error(
+              `Plan approval timed out after ${timeoutMinutes} minutes - feature execution cancelled`
+            )
+          );
+        }
+      }, timeoutMs);
+
+      this.pendingApprovals.set(key, {
+        resolve: wrappedResolve,
+        reject: wrappedReject,
+        featureId,
+        projectPath,
+      });
+
+      logger.info(
+        `Pending approval registered for feature ${featureId} (timeout: ${timeoutMinutes} minutes)`
+      );
+    });
+  }
+
+  /** Resolve approval. Recovery path: returns needsRecovery=true if planSpec.status='generated'. */
+  async resolveApproval(
+    featureId: string,
+    approved: boolean,
+    options?: { editedPlan?: string; feedback?: string; projectPath?: string }
+  ): Promise<ResolveApprovalResult> {
+    const { editedPlan, feedback, projectPath: projectPathFromClient } = options ?? {};
+
+    logger.info(`resolveApproval called for feature ${featureId}, approved=${approved}`);
+    logger.info(
+      `Current pending approvals: ${Array.from(this.pendingApprovals.keys()).join(', ') || 'none'}`
+    );
+
+    // Try to find pending approval using project-scoped key if projectPath is available
+    let foundKey: string | undefined;
+    let pending: PendingApproval | undefined;
+
+    if (projectPathFromClient) {
+      foundKey = this.approvalKey(projectPathFromClient, featureId);
+      pending = this.pendingApprovals.get(foundKey);
+    } else {
+      // Fallback: search by featureId (backward compatibility)
+      for (const [key, approval] of this.pendingApprovals) {
+        if (approval.featureId === featureId) {
+          foundKey = key;
+          pending = approval;
+          break;
+        }
+      }
+    }
+
+    if (!pending) {
+      logger.info(`No pending approval in Map for feature ${featureId}`);
+
+      // RECOVERY: If no pending approval but we have projectPath from client,
+      // check if feature's planSpec.status is 'generated' and handle recovery
+      if (projectPathFromClient) {
+        logger.info(`Attempting recovery with projectPath: ${projectPathFromClient}`);
+        const feature = await this.featureStateManager.loadFeature(
+          projectPathFromClient,
+          featureId
+        );
+
+        if (feature?.planSpec?.status === 'generated') {
+          logger.info(`Feature ${featureId} has planSpec.status='generated', performing recovery`);
+
+          if (approved) {
+            // Update planSpec to approved
+            await this.featureStateManager.updateFeaturePlanSpec(projectPathFromClient, featureId, {
+              status: 'approved',
+              approvedAt: new Date().toISOString(),
+              reviewedByUser: true,
+              content: editedPlan || feature.planSpec.content,
+            });
+
+            logger.info(`Recovery approval complete for feature ${featureId}`);
+
+            // Return needsRecovery flag - caller (AutoModeService) handles execution
+            return { success: true, needsRecovery: true };
+          } else {
+            // Rejection recovery
+            await this.featureStateManager.updateFeaturePlanSpec(projectPathFromClient, featureId, {
+              status: 'rejected',
+              reviewedByUser: true,
+            });
+
+            await this.featureStateManager.updateFeatureStatus(
+              projectPathFromClient,
+              featureId,
+              'backlog'
+            );
+
+            this.eventBus.emitAutoModeEvent('plan_rejected', {
+              featureId,
+              projectPath: projectPathFromClient,
+              feedback,
+            });
+
+            return { success: true };
+          }
+        }
+      }
+
+      logger.info(
+        `ERROR: No pending approval found for feature ${featureId} and recovery not possible`
+      );
+      return {
+        success: false,
+        error: `No pending approval for feature ${featureId}`,
+      };
+    }
+
+    logger.info(`Found pending approval for feature ${featureId}, proceeding...`);
+
+    const { projectPath } = pending;
+
+    // Update feature's planSpec status
+    await this.featureStateManager.updateFeaturePlanSpec(projectPath, featureId, {
+      status: approved ? 'approved' : 'rejected',
+      approvedAt: approved ? new Date().toISOString() : undefined,
+      reviewedByUser: true,
+      ...(editedPlan !== undefined && { content: editedPlan }), // Only update content if user provided an edited version
+    });
+
+    // If rejected, emit event so client knows the rejection reason (even without feedback)
+    if (!approved) {
+      this.eventBus.emitAutoModeEvent('plan_rejected', {
+        featureId,
+        projectPath,
+        feedback,
+      });
+    }
+
+    // Resolve the promise with all data including feedback
+    // This triggers the wrapped resolve which clears the timeout
+    pending.resolve({ approved, editedPlan, feedback });
+    if (foundKey) {
+      this.pendingApprovals.delete(foundKey);
+    }
+
+    return { success: true };
+  }
+
+  /** Cancel approval (e.g., when feature stopped). Timeout cleared via wrapped reject. */
+  cancelApproval(featureId: string, projectPath?: string): void {
+    logger.info(`cancelApproval called for feature ${featureId}`);
+    logger.info(
+      `Current pending approvals: ${Array.from(this.pendingApprovals.keys()).join(', ') || 'none'}`
+    );
+
+    // If projectPath provided, use project-scoped key; otherwise search by featureId
+    let foundKey: string | undefined;
+    let pending: PendingApproval | undefined;
+
+    if (projectPath) {
+      foundKey = this.approvalKey(projectPath, featureId);
+      pending = this.pendingApprovals.get(foundKey);
+    } else {
+      // Fallback: search for any approval with this featureId (backward compatibility)
+      for (const [key, approval] of this.pendingApprovals) {
+        if (approval.featureId === featureId) {
+          foundKey = key;
+          pending = approval;
+          break;
+        }
+      }
+    }
+
+    if (pending && foundKey) {
+      logger.info(`Found and cancelling pending approval for feature ${featureId}`);
+      // Wrapped reject clears timeout automatically
+      pending.reject(new Error('Plan approval cancelled - feature was stopped'));
+      this.pendingApprovals.delete(foundKey);
+    } else {
+      logger.info(`No pending approval to cancel for feature ${featureId}`);
+    }
+  }
+
+  /** Check if a feature has a pending plan approval. */
+  hasPendingApproval(featureId: string, projectPath?: string): boolean {
+    if (projectPath) {
+      return this.pendingApprovals.has(this.approvalKey(projectPath, featureId));
+    }
+    // Fallback: search by featureId (backward compatibility)
+    for (const approval of this.pendingApprovals.values()) {
+      if (approval.featureId === featureId) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /** Get timeout from project settings or default (30 min). */
+  private async getTimeoutMs(projectPath: string): Promise<number> {
+    if (!this.settingsService) {
+      return DEFAULT_APPROVAL_TIMEOUT_MS;
+    }
+
+    try {
+      const projectSettings = await this.settingsService.getProjectSettings(projectPath);
+      // Check for planApprovalTimeoutMs in project settings
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const timeoutMs = (projectSettings as any).planApprovalTimeoutMs;
+      if (typeof timeoutMs === 'number' && timeoutMs > 0) {
+        return timeoutMs;
+      }
+    } catch (error) {
+      logger.warn(
+        `Failed to get project settings for ${projectPath}, using default timeout`,
+        error
+      );
+    }
+
+    return DEFAULT_APPROVAL_TIMEOUT_MS;
+  }
+}

apps/server/src/services/recovery-service.ts

@@ -0,0 +1,302 @@
+/**
+ * RecoveryService - Crash recovery and feature resumption
+ */
+
+import path from 'path';
+import type { Feature, FeatureStatusWithPipeline } from '@automaker/types';
+import { DEFAULT_MAX_CONCURRENCY } from '@automaker/types';
+import {
+  createLogger,
+  readJsonWithRecovery,
+  logRecoveryWarning,
+  DEFAULT_BACKUP_COUNT,
+} from '@automaker/utils';
+import {
+  getFeatureDir,
+  getFeaturesDir,
+  getExecutionStatePath,
+  ensureAutomakerDir,
+} from '@automaker/platform';
+import * as secureFs from '../lib/secure-fs.js';
+import { getPromptCustomization } from '../lib/settings-helpers.js';
+import type { TypedEventBus } from './typed-event-bus.js';
+import type { ConcurrencyManager, RunningFeature } from './concurrency-manager.js';
+import type { SettingsService } from './settings-service.js';
+import type { PipelineStatusInfo } from './pipeline-orchestrator.js';
+
+const logger = createLogger('RecoveryService');
+
+export interface ExecutionState {
+  version: 1;
+  autoLoopWasRunning: boolean;
+  maxConcurrency: number;
+  projectPath: string;
+  branchName: string | null;
+  runningFeatureIds: string[];
+  savedAt: string;
+}
+
+export const DEFAULT_EXECUTION_STATE: ExecutionState = {
+  version: 1,
+  autoLoopWasRunning: false,
+  maxConcurrency: DEFAULT_MAX_CONCURRENCY,
+  projectPath: '',
+  branchName: null,
+  runningFeatureIds: [],
+  savedAt: '',
+};
+
+export type ExecuteFeatureFn = (
+  projectPath: string,
+  featureId: string,
+  useWorktrees: boolean,
+  isAutoMode: boolean,
+  providedWorktreePath?: string,
+  options?: { continuationPrompt?: string; _calledInternally?: boolean }
+) => Promise<void>;
+export type LoadFeatureFn = (projectPath: string, featureId: string) => Promise<Feature | null>;
+export type DetectPipelineStatusFn = (
+  projectPath: string,
+  featureId: string,
+  status: FeatureStatusWithPipeline
+) => Promise<PipelineStatusInfo>;
+export type ResumePipelineFn = (
+  projectPath: string,
+  feature: Feature,
+  useWorktrees: boolean,
+  pipelineInfo: PipelineStatusInfo
+) => Promise<void>;
+export type IsFeatureRunningFn = (featureId: string) => boolean;
+export type AcquireRunningFeatureFn = (options: {
+  featureId: string;
+  projectPath: string;
+  isAutoMode: boolean;
+  allowReuse?: boolean;
+}) => RunningFeature;
+export type ReleaseRunningFeatureFn = (featureId: string) => void;
+
+export class RecoveryService {
+  constructor(
+    private eventBus: TypedEventBus,
+    private concurrencyManager: ConcurrencyManager,
+    private settingsService: SettingsService | null,
+    private executeFeatureFn: ExecuteFeatureFn,
+    private loadFeatureFn: LoadFeatureFn,
+    private detectPipelineStatusFn: DetectPipelineStatusFn,
+    private resumePipelineFn: ResumePipelineFn,
+    private isFeatureRunningFn: IsFeatureRunningFn,
+    private acquireRunningFeatureFn: AcquireRunningFeatureFn,
+    private releaseRunningFeatureFn: ReleaseRunningFeatureFn
+  ) {}
+
+  async saveExecutionStateForProject(
+    projectPath: string,
+    branchName: string | null,
+    maxConcurrency: number
+  ): Promise<void> {
+    try {
+      await ensureAutomakerDir(projectPath);
+      const runningFeatureIds = this.concurrencyManager
+        .getAllRunning()
+        .filter((f) => f.projectPath === projectPath)
+        .map((f) => f.featureId);
+      const state: ExecutionState = {
+        version: 1,
+        autoLoopWasRunning: true,
+        maxConcurrency,
+        projectPath,
+        branchName,
+        runningFeatureIds,
+        savedAt: new Date().toISOString(),
+      };
+      await secureFs.writeFile(
+        getExecutionStatePath(projectPath),
+        JSON.stringify(state, null, 2),
+        'utf-8'
+      );
+    } catch {
+      /* ignore */
+    }
+  }
+
+  async saveExecutionState(
+    projectPath: string,
+    autoLoopWasRunning = false,
+    maxConcurrency = DEFAULT_MAX_CONCURRENCY
+  ): Promise<void> {
+    try {
+      await ensureAutomakerDir(projectPath);
+      const state: ExecutionState = {
+        version: 1,
+        autoLoopWasRunning,
+        maxConcurrency,
+        projectPath,
+        branchName: null,
+        runningFeatureIds: this.concurrencyManager.getAllRunning().map((rf) => rf.featureId),
+        savedAt: new Date().toISOString(),
+      };
+      await secureFs.writeFile(
+        getExecutionStatePath(projectPath),
+        JSON.stringify(state, null, 2),
+        'utf-8'
+      );
+    } catch {
+      /* ignore */
+    }
+  }
+
+  async loadExecutionState(projectPath: string): Promise<ExecutionState> {
+    try {
+      const content = (await secureFs.readFile(
+        getExecutionStatePath(projectPath),
+        'utf-8'
+      )) as string;
+      return JSON.parse(content) as ExecutionState;
+    } catch {
+      return DEFAULT_EXECUTION_STATE;
+    }
+  }
+
+  async clearExecutionState(projectPath: string, _branchName: string | null = null): Promise<void> {
+    try {
+      await secureFs.unlink(getExecutionStatePath(projectPath));
+    } catch {
+      /* ignore */
+    }
+  }
+
+  async contextExists(projectPath: string, featureId: string): Promise<boolean> {
+    try {
+      await secureFs.access(path.join(getFeatureDir(projectPath, featureId), 'agent-output.md'));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private async executeFeatureWithContext(
+    projectPath: string,
+    featureId: string,
+    context: string,
+    useWorktrees: boolean
+  ): Promise<void> {
+    const feature = await this.loadFeatureFn(projectPath, featureId);
+    if (!feature) throw new Error(`Feature ${featureId} not found`);
+    const prompts = await getPromptCustomization(this.settingsService, '[RecoveryService]');
+    const featurePrompt = `## Feature Implementation Task\n\n**Feature ID:** ${feature.id}\n**Title:** ${feature.title || 'Untitled Feature'}\n**Description:** ${feature.description}\n`;
+    let prompt = prompts.taskExecution.resumeFeatureTemplate;
+    prompt = prompt
+      .replace(/\{\{featurePrompt\}\}/g, featurePrompt)
+      .replace(/\{\{previousContext\}\}/g, context);
+    return this.executeFeatureFn(projectPath, featureId, useWorktrees, false, undefined, {
+      continuationPrompt: prompt,
+      _calledInternally: true,
+    });
+  }
+
+  async resumeFeature(
+    projectPath: string,
+    featureId: string,
+    useWorktrees = false,
+    _calledInternally = false
+  ): Promise<void> {
+    if (!_calledInternally && this.isFeatureRunningFn(featureId)) return;
+    this.acquireRunningFeatureFn({
+      featureId,
+      projectPath,
+      isAutoMode: false,
+      allowReuse: _calledInternally,
+    });
+    try {
+      const feature = await this.loadFeatureFn(projectPath, featureId);
+      if (!feature) throw new Error(`Feature ${featureId} not found`);
+      const pipelineInfo = await this.detectPipelineStatusFn(
+        projectPath,
+        featureId,
+        (feature.status || '') as FeatureStatusWithPipeline
+      );
+      if (pipelineInfo.isPipeline)
+        return await this.resumePipelineFn(projectPath, feature, useWorktrees, pipelineInfo);
+      const hasContext = await this.contextExists(projectPath, featureId);
+      if (hasContext) {
+        const context = (await secureFs.readFile(
+          path.join(getFeatureDir(projectPath, featureId), 'agent-output.md'),
+          'utf-8'
+        )) as string;
+        this.eventBus.emitAutoModeEvent('auto_mode_feature_resuming', {
+          featureId,
+          featureName: feature.title,
+          projectPath,
+          hasContext: true,
+          message: `Resuming feature "${feature.title}" from saved context`,
+        });
+        return await this.executeFeatureWithContext(projectPath, featureId, context, useWorktrees);
+      }
+      this.eventBus.emitAutoModeEvent('auto_mode_feature_resuming', {
+        featureId,
+        featureName: feature.title,
+        projectPath,
+        hasContext: false,
+        message: `Starting fresh execution for interrupted feature "${feature.title}"`,
+      });
+      return await this.executeFeatureFn(projectPath, featureId, useWorktrees, false, undefined, {
+        _calledInternally: true,
+      });
+    } finally {
+      this.releaseRunningFeatureFn(featureId);
+    }
+  }
+
+  async resumeInterruptedFeatures(projectPath: string): Promise<void> {
+    const featuresDir = getFeaturesDir(projectPath);
+    try {
+      const entries = await secureFs.readdir(featuresDir, { withFileTypes: true });
+      const featuresWithContext: Feature[] = [];
+      const featuresWithoutContext: Feature[] = [];
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const result = await readJsonWithRecovery<Feature | null>(
+            path.join(featuresDir, entry.name, 'feature.json'),
+            null,
+            { maxBackups: DEFAULT_BACKUP_COUNT, autoRestore: true }
+          );
+          logRecoveryWarning(result, `Feature ${entry.name}`, logger);
+          const feature = result.data;
+          if (!feature) continue;
+          if (
+            feature.status === 'in_progress' ||
+            (feature.status && feature.status.startsWith('pipeline_'))
+          ) {
+            (await this.contextExists(projectPath, feature.id))
+              ? featuresWithContext.push(feature)
+              : featuresWithoutContext.push(feature);
+          }
+        }
+      }
+      const allInterruptedFeatures = [...featuresWithContext, ...featuresWithoutContext];
+      if (allInterruptedFeatures.length === 0) return;
+      this.eventBus.emitAutoModeEvent('auto_mode_resuming_features', {
+        message: `Resuming ${allInterruptedFeatures.length} interrupted feature(s)`,
+        projectPath,
+        featureIds: allInterruptedFeatures.map((f) => f.id),
+        features: allInterruptedFeatures.map((f) => ({
+          id: f.id,
+          title: f.title,
+          status: f.status,
+          branchName: f.branchName ?? null,
+          hasContext: featuresWithContext.some((fc) => fc.id === f.id),
+        })),
+      });
+      for (const feature of allInterruptedFeatures) {
+        try {
+          if (!this.isFeatureRunningFn(feature.id))
+            await this.resumeFeature(projectPath, feature.id, true);
+        } catch {
+          /* continue */
+        }
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+}

apps/server/src/services/spec-parser.ts

@@ -0,0 +1,227 @@
+/**
+ * Spec Parser - Pure functions for parsing spec content and detecting markers
+ *
+ * Extracts tasks from generated specs, detects progress markers,
+ * and extracts summary content from various formats.
+ */
+
+import type { ParsedTask } from '@automaker/types';
+
+/**
+ * Parse a single task line
+ * Format: - [ ] T###: Description | File: path/to/file
+ */
+function parseTaskLine(line: string, currentPhase?: string): ParsedTask | null {
+  // Match pattern: - [ ] T###: Description | File: path
+  const taskMatch = line.match(/- \[ \] (T\d{3}):\s*([^|]+)(?:\|\s*File:\s*(.+))?$/);
+  if (!taskMatch) {
+    // Try simpler pattern without file
+    const simpleMatch = line.match(/- \[ \] (T\d{3}):\s*(.+)$/);
+    if (simpleMatch) {
+      return {
+        id: simpleMatch[1],
+        description: simpleMatch[2].trim(),
+        phase: currentPhase,
+        status: 'pending',
+      };
+    }
+    return null;
+  }
+
+  return {
+    id: taskMatch[1],
+    description: taskMatch[2].trim(),
+    filePath: taskMatch[3]?.trim(),
+    phase: currentPhase,
+    status: 'pending',
+  };
+}
+
+/**
+ * Parse tasks from generated spec content
+ * Looks for the ```tasks code block and extracts task lines
+ * Format: - [ ] T###: Description | File: path/to/file
+ */
+export function parseTasksFromSpec(specContent: string): ParsedTask[] {
+  const tasks: ParsedTask[] = [];
+
+  // Extract content within ```tasks ... ``` block
+  const tasksBlockMatch = specContent.match(/```tasks\s*([\s\S]*?)```/);
+  if (!tasksBlockMatch) {
+    // Try fallback: look for task lines anywhere in content
+    const taskLines = specContent.match(/- \[ \] T\d{3}:.*$/gm);
+    if (!taskLines) {
+      return tasks;
+    }
+    // Parse fallback task lines
+    let currentPhase: string | undefined;
+    for (const line of taskLines) {
+      const parsed = parseTaskLine(line, currentPhase);
+      if (parsed) {
+        tasks.push(parsed);
+      }
+    }
+    return tasks;
+  }
+
+  const tasksContent = tasksBlockMatch[1];
+  const lines = tasksContent.split('\n');
+
+  let currentPhase: string | undefined;
+
+  for (const line of lines) {
+    const trimmedLine = line.trim();
+
+    // Check for phase header (e.g., "## Phase 1: Foundation")
+    const phaseMatch = trimmedLine.match(/^##\s*(.+)$/);
+    if (phaseMatch) {
+      currentPhase = phaseMatch[1].trim();
+      continue;
+    }
+
+    // Check for task line
+    if (trimmedLine.startsWith('- [ ]')) {
+      const parsed = parseTaskLine(trimmedLine, currentPhase);
+      if (parsed) {
+        tasks.push(parsed);
+      }
+    }
+  }
+
+  return tasks;
+}
+
+/**
+ * Detect [TASK_START] marker in text and extract task ID
+ * Format: [TASK_START] T###: Description
+ */
+export function detectTaskStartMarker(text: string): string | null {
+  const match = text.match(/\[TASK_START\]\s*(T\d{3})/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Detect [TASK_COMPLETE] marker in text and extract task ID
+ * Format: [TASK_COMPLETE] T###: Brief summary
+ */
+export function detectTaskCompleteMarker(text: string): string | null {
+  const match = text.match(/\[TASK_COMPLETE\]\s*(T\d{3})/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Detect [PHASE_COMPLETE] marker in text and extract phase number
+ * Format: [PHASE_COMPLETE] Phase N complete
+ */
+export function detectPhaseCompleteMarker(text: string): number | null {
+  const match = text.match(/\[PHASE_COMPLETE\]\s*Phase\s*(\d+)/i);
+  return match ? parseInt(match[1], 10) : null;
+}
+
+/**
+ * Fallback spec detection when [SPEC_GENERATED] marker is missing
+ * Looks for structural elements that indicate a spec was generated.
+ * This is especially important for non-Claude models that may not output
+ * the explicit [SPEC_GENERATED] marker.
+ *
+ * @param text - The text content to check for spec structure
+ * @returns true if the text appears to be a generated spec
+ */
+export function detectSpecFallback(text: string): boolean {
+  // Check for key structural elements of a spec
+  const hasTasksBlock = /```tasks[\s\S]*```/.test(text);
+  const hasTaskLines = /- \[ \] T\d{3}:/.test(text);
+
+  // Check for common spec sections (case-insensitive)
+  const hasAcceptanceCriteria = /acceptance criteria/i.test(text);
+  const hasTechnicalContext = /technical context/i.test(text);
+  const hasProblemStatement = /problem statement/i.test(text);
+  const hasUserStory = /user story/i.test(text);
+  // Additional patterns for different model outputs
+  const hasGoal = /\*\*Goal\*\*:/i.test(text);
+  const hasSolution = /\*\*Solution\*\*:/i.test(text);
+  const hasImplementation = /implementation\s*(plan|steps|approach)/i.test(text);
+  const hasOverview = /##\s*(overview|summary)/i.test(text);
+
+  // Spec is detected if we have task structure AND at least some spec content
+  const hasTaskStructure = hasTasksBlock || hasTaskLines;
+  const hasSpecContent =
+    hasAcceptanceCriteria ||
+    hasTechnicalContext ||
+    hasProblemStatement ||
+    hasUserStory ||
+    hasGoal ||
+    hasSolution ||
+    hasImplementation ||
+    hasOverview;
+
+  return hasTaskStructure && hasSpecContent;
+}
+
+/**
+ * Extract summary from text content
+ * Checks for multiple formats in order of priority:
+ * 1. Explicit <summary> tags
+ * 2. ## Summary section (markdown)
+ * 3. **Goal**: section (lite planning mode)
+ * 4. **Problem**: or **Problem Statement**: section (spec/full modes)
+ * 5. **Solution**: section as fallback
+ *
+ * Note: Uses last match for each pattern to avoid stale summaries
+ * when agent output accumulates across multiple runs.
+ *
+ * @param text - The text content to extract summary from
+ * @returns The extracted summary string, or null if no summary found
+ */
+export function extractSummary(text: string): string | null {
+  // Helper to truncate content to first paragraph with max length
+  const truncate = (content: string, maxLength: number): string => {
+    const firstPara = content.split(/\n\n/)[0];
+    return firstPara.length > maxLength ? `${firstPara.substring(0, maxLength)}...` : firstPara;
+  };
+
+  // Helper to get last match from matchAll results
+  const getLastMatch = (matches: IterableIterator<RegExpMatchArray>): RegExpMatchArray | null => {
+    const arr = [...matches];
+    return arr.length > 0 ? arr[arr.length - 1] : null;
+  };
+
+  // Check for explicit <summary> tags first (use last match to avoid stale summaries)
+  const summaryMatches = text.matchAll(/<summary>([\s\S]*?)<\/summary>/g);
+  const summaryMatch = getLastMatch(summaryMatches);
+  if (summaryMatch) {
+    return summaryMatch[1].trim();
+  }
+
+  // Check for ## Summary section (use last match)
+  const sectionMatches = text.matchAll(/##\s*Summary\s*\n+([\s\S]*?)(?=\n##|\n\*\*|$)/gi);
+  const sectionMatch = getLastMatch(sectionMatches);
+  if (sectionMatch) {
+    return truncate(sectionMatch[1].trim(), 500);
+  }
+
+  // Check for **Goal**: section (lite mode, use last match)
+  const goalMatches = text.matchAll(/\*\*Goal\*\*:\s*(.+?)(?:\n|$)/gi);
+  const goalMatch = getLastMatch(goalMatches);
+  if (goalMatch) {
+    return goalMatch[1].trim();
+  }
+
+  // Check for **Problem**: or **Problem Statement**: section (spec/full modes, use last match)
+  const problemMatches = text.matchAll(
+    /\*\*Problem(?:\s*Statement)?\*\*:\s*([\s\S]*?)(?=\n\d+\.|\n\*\*|$)/gi
+  );
+  const problemMatch = getLastMatch(problemMatches);
+  if (problemMatch) {
+    return truncate(problemMatch[1].trim(), 500);
+  }
+
+  // Check for **Solution**: section as fallback (use last match)
+  const solutionMatches = text.matchAll(/\*\*Solution\*\*:\s*([\s\S]*?)(?=\n\d+\.|\n\*\*|$)/gi);
+  const solutionMatch = getLastMatch(solutionMatches);
+  if (solutionMatch) {
+    return truncate(solutionMatch[1].trim(), 300);
+  }
+
+  return null;
+}

apps/server/src/services/terminal-service.ts

@@ -13,6 +13,14 @@ import * as path from 'path';
 // to enforce ALLOWED_ROOT_DIRECTORY security boundary
 import * as secureFs from '../lib/secure-fs.js';
 import { createLogger } from '@automaker/utils';
+import type { SettingsService } from './settings-service.js';
+import { getTerminalThemeColors, getAllTerminalThemes } from '../lib/terminal-themes-data.js';
+import {
+  getRcFilePath,
+  getTerminalDir,
+  ensureRcFilesUpToDate,
+  type TerminalConfig,
+} from '@automaker/platform';
 
 const logger = createLogger('Terminal');
 // System paths module handles shell binary checks and WSL detection
@@ -24,6 +32,27 @@ import {
   getShellPaths,
 } from '@automaker/platform';
 
+const BASH_LOGIN_ARG = '--login';
+const BASH_RCFILE_ARG = '--rcfile';
+const SHELL_NAME_BASH = 'bash';
+const SHELL_NAME_ZSH = 'zsh';
+const SHELL_NAME_SH = 'sh';
+const DEFAULT_SHOW_USER_HOST = true;
+const DEFAULT_SHOW_PATH = true;
+const DEFAULT_SHOW_TIME = false;
+const DEFAULT_SHOW_EXIT_STATUS = false;
+const DEFAULT_PATH_DEPTH = 0;
+const DEFAULT_PATH_STYLE: TerminalConfig['pathStyle'] = 'full';
+const DEFAULT_CUSTOM_PROMPT = true;
+const DEFAULT_PROMPT_FORMAT: TerminalConfig['promptFormat'] = 'standard';
+const DEFAULT_SHOW_GIT_BRANCH = true;
+const DEFAULT_SHOW_GIT_STATUS = true;
+const DEFAULT_CUSTOM_ALIASES = '';
+const DEFAULT_CUSTOM_ENV_VARS: Record<string, string> = {};
+const PROMPT_THEME_CUSTOM = 'custom';
+const PROMPT_THEME_PREFIX = 'omp-';
+const OMP_THEME_ENV_VAR = 'AUTOMAKER_OMP_THEME';
+
 // Maximum scrollback buffer size (characters)
 const MAX_SCROLLBACK_SIZE = 50000; // ~50KB per terminal
 
@@ -42,6 +71,114 @@ let maxSessions = parseInt(process.env.TERMINAL_MAX_SESSIONS || '1000', 10);
 const OUTPUT_THROTTLE_MS = 4; // ~250fps max update rate for responsive input
 const OUTPUT_BATCH_SIZE = 4096; // Smaller batches for lower latency
 
+function applyBashRcFileArgs(args: string[], rcFilePath: string): string[] {
+  const sanitizedArgs: string[] = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === BASH_LOGIN_ARG) {
+      continue;
+    }
+    if (arg === BASH_RCFILE_ARG) {
+      index += 1;
+      continue;
+    }
+    sanitizedArgs.push(arg);
+  }
+
+  sanitizedArgs.push(BASH_RCFILE_ARG, rcFilePath);
+  return sanitizedArgs;
+}
+
+function normalizePathStyle(
+  pathStyle: TerminalConfig['pathStyle'] | undefined
+): TerminalConfig['pathStyle'] {
+  if (pathStyle === 'short' || pathStyle === 'basename') {
+    return pathStyle;
+  }
+  return DEFAULT_PATH_STYLE;
+}
+
+function normalizePathDepth(pathDepth: number | undefined): number {
+  const depth =
+    typeof pathDepth === 'number' && Number.isFinite(pathDepth) ? pathDepth : DEFAULT_PATH_DEPTH;
+  return Math.max(DEFAULT_PATH_DEPTH, Math.floor(depth));
+}
+
+function getShellBasename(shellPath: string): string {
+  const lastSep = Math.max(shellPath.lastIndexOf('/'), shellPath.lastIndexOf('\\'));
+  return lastSep >= 0 ? shellPath.slice(lastSep + 1) : shellPath;
+}
+
+function getShellArgsForPath(shellPath: string): string[] {
+  const shellName = getShellBasename(shellPath).toLowerCase().replace('.exe', '');
+  if (shellName === 'powershell' || shellName === 'pwsh' || shellName === 'cmd') {
+    return [];
+  }
+  if (shellName === SHELL_NAME_SH) {
+    return [];
+  }
+  return [BASH_LOGIN_ARG];
+}
+
+function resolveOmpThemeName(promptTheme: string | undefined): string | null {
+  if (!promptTheme || promptTheme === PROMPT_THEME_CUSTOM) {
+    return null;
+  }
+  if (promptTheme.startsWith(PROMPT_THEME_PREFIX)) {
+    return promptTheme.slice(PROMPT_THEME_PREFIX.length);
+  }
+  return null;
+}
+
+function buildEffectiveTerminalConfig(
+  globalTerminalConfig: TerminalConfig | undefined,
+  projectTerminalConfig: Partial<TerminalConfig> | undefined
+): TerminalConfig {
+  const mergedEnvVars = {
+    ...(globalTerminalConfig?.customEnvVars ?? DEFAULT_CUSTOM_ENV_VARS),
+    ...(projectTerminalConfig?.customEnvVars ?? DEFAULT_CUSTOM_ENV_VARS),
+  };
+
+  return {
+    enabled: projectTerminalConfig?.enabled ?? globalTerminalConfig?.enabled ?? false,
+    customPrompt: globalTerminalConfig?.customPrompt ?? DEFAULT_CUSTOM_PROMPT,
+    promptFormat: globalTerminalConfig?.promptFormat ?? DEFAULT_PROMPT_FORMAT,
+    showGitBranch:
+      projectTerminalConfig?.showGitBranch ??
+      globalTerminalConfig?.showGitBranch ??
+      DEFAULT_SHOW_GIT_BRANCH,
+    showGitStatus:
+      projectTerminalConfig?.showGitStatus ??
+      globalTerminalConfig?.showGitStatus ??
+      DEFAULT_SHOW_GIT_STATUS,
+    showUserHost:
+      projectTerminalConfig?.showUserHost ??
+      globalTerminalConfig?.showUserHost ??
+      DEFAULT_SHOW_USER_HOST,
+    showPath:
+      projectTerminalConfig?.showPath ?? globalTerminalConfig?.showPath ?? DEFAULT_SHOW_PATH,
+    pathStyle: normalizePathStyle(
+      projectTerminalConfig?.pathStyle ?? globalTerminalConfig?.pathStyle
+    ),
+    pathDepth: normalizePathDepth(
+      projectTerminalConfig?.pathDepth ?? globalTerminalConfig?.pathDepth
+    ),
+    showTime:
+      projectTerminalConfig?.showTime ?? globalTerminalConfig?.showTime ?? DEFAULT_SHOW_TIME,
+    showExitStatus:
+      projectTerminalConfig?.showExitStatus ??
+      globalTerminalConfig?.showExitStatus ??
+      DEFAULT_SHOW_EXIT_STATUS,
+    customAliases:
+      projectTerminalConfig?.customAliases ??
+      globalTerminalConfig?.customAliases ??
+      DEFAULT_CUSTOM_ALIASES,
+    customEnvVars: mergedEnvVars,
+    rcFileVersion: globalTerminalConfig?.rcFileVersion,
+  };
+}
+
 export interface TerminalSession {
   id: string;
   pty: pty.IPty;
@@ -77,6 +214,12 @@ export class TerminalService extends EventEmitter {
     !!(process.versions && (process.versions as Record<string, string>).electron) ||
     !!process.env.ELECTRON_RUN_AS_NODE;
   private useConptyFallback = false; // Track if we need to use winpty fallback on Windows
+  private settingsService: SettingsService | null = null;
+
+  constructor(settingsService?: SettingsService) {
+    super();
+    this.settingsService = settingsService || null;
+  }
 
   /**
    * Kill a PTY process with platform-specific handling.
@@ -102,37 +245,19 @@ export class TerminalService extends EventEmitter {
     const platform = os.platform();
     const shellPaths = getShellPaths();
 
-    // Helper to get basename handling both path separators
-    const getBasename = (shellPath: string): string => {
-      const lastSep = Math.max(shellPath.lastIndexOf('/'), shellPath.lastIndexOf('\\'));
-      return lastSep >= 0 ? shellPath.slice(lastSep + 1) : shellPath;
-    };
-
-    // Helper to get shell args based on shell name
-    const getShellArgs = (shell: string): string[] => {
-      const shellName = getBasename(shell).toLowerCase().replace('.exe', '');
-      // PowerShell and cmd don't need --login
-      if (shellName === 'powershell' || shellName === 'pwsh' || shellName === 'cmd') {
-        return [];
-      }
-      // sh doesn't support --login in all implementations
-      if (shellName === 'sh') {
-        return [];
-      }
-      // bash, zsh, and other POSIX shells support --login
-      return ['--login'];
-    };
-
     // Check if running in WSL - prefer user's shell or bash with --login
     if (platform === 'linux' && this.isWSL()) {
       const userShell = process.env.SHELL;
       if (userShell) {
         // Try to find userShell in allowed paths
         for (const allowedShell of shellPaths) {
-          if (allowedShell === userShell || getBasename(allowedShell) === getBasename(userShell)) {
+          if (
+            allowedShell === userShell ||
+            getShellBasename(allowedShell) === getShellBasename(userShell)
+          ) {
             try {
               if (systemPathExists(allowedShell)) {
-                return { shell: allowedShell, args: getShellArgs(allowedShell) };
+                return { shell: allowedShell, args: getShellArgsForPath(allowedShell) };
               }
             } catch {
               // Path not allowed, continue searching
@@ -144,7 +269,7 @@ export class TerminalService extends EventEmitter {
       for (const shell of shellPaths) {
         try {
           if (systemPathExists(shell)) {
-            return { shell, args: getShellArgs(shell) };
+            return { shell, args: getShellArgsForPath(shell) };
           }
         } catch {
           // Path not allowed, continue
@@ -158,10 +283,13 @@ export class TerminalService extends EventEmitter {
     if (userShell && platform !== 'win32') {
       // Try to find userShell in allowed paths
       for (const allowedShell of shellPaths) {
-        if (allowedShell === userShell || getBasename(allowedShell) === getBasename(userShell)) {
+        if (
+          allowedShell === userShell ||
+          getShellBasename(allowedShell) === getShellBasename(userShell)
+        ) {
           try {
             if (systemPathExists(allowedShell)) {
-              return { shell: allowedShell, args: getShellArgs(allowedShell) };
+              return { shell: allowedShell, args: getShellArgsForPath(allowedShell) };
             }
           } catch {
             // Path not allowed, continue searching
@@ -174,7 +302,7 @@ export class TerminalService extends EventEmitter {
     for (const shell of shellPaths) {
       try {
         if (systemPathExists(shell)) {
-          return { shell, args: getShellArgs(shell) };
+          return { shell, args: getShellArgsForPath(shell) };
         }
       } catch {
         // Path not allowed or doesn't exist, continue to next
@@ -313,8 +441,9 @@ export class TerminalService extends EventEmitter {
 
     const id = `term-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
 
-    const { shell: detectedShell, args: shellArgs } = this.detectShell();
+    const { shell: detectedShell, args: detectedShellArgs } = this.detectShell();
     const shell = options.shell || detectedShell;
+    let shellArgs = options.shell ? getShellArgsForPath(shell) : [...detectedShellArgs];
 
     // Validate and resolve working directory
     // Uses secureFs internally to enforce ALLOWED_ROOT_DIRECTORY
@@ -332,6 +461,89 @@ export class TerminalService extends EventEmitter {
       }
     }
 
+    // Terminal config injection (custom prompts, themes)
+    const terminalConfigEnv: Record<string, string> = {};
+    if (this.settingsService) {
+      try {
+        logger.info(
+          `[createSession] Checking terminal config for session ${id}, cwd: ${options.cwd || cwd}`
+        );
+        const globalSettings = await this.settingsService.getGlobalSettings();
+        const projectSettings = options.cwd
+          ? await this.settingsService.getProjectSettings(options.cwd)
+          : null;
+
+        const globalTerminalConfig = globalSettings?.terminalConfig;
+        const projectTerminalConfig = projectSettings?.terminalConfig;
+        const effectiveConfig = buildEffectiveTerminalConfig(
+          globalTerminalConfig,
+          projectTerminalConfig
+        );
+
+        logger.info(
+          `[createSession] Terminal config: global.enabled=${globalTerminalConfig?.enabled}, project.enabled=${projectTerminalConfig?.enabled}`
+        );
+        logger.info(
+          `[createSession] Terminal config effective enabled: ${effectiveConfig.enabled}`
+        );
+
+        if (effectiveConfig.enabled && globalTerminalConfig) {
+          const currentTheme = globalSettings?.theme || 'dark';
+          const themeColors = getTerminalThemeColors(currentTheme);
+          const allThemes = getAllTerminalThemes();
+          const promptTheme =
+            projectTerminalConfig?.promptTheme ?? globalTerminalConfig.promptTheme;
+          const ompThemeName = resolveOmpThemeName(promptTheme);
+
+          // Ensure RC files are up to date
+          await ensureRcFilesUpToDate(
+            options.cwd || cwd,
+            currentTheme,
+            effectiveConfig,
+            themeColors,
+            allThemes
+          );
+
+          // Set shell-specific env vars
+          const shellName = getShellBasename(shell).toLowerCase();
+          if (ompThemeName && effectiveConfig.customPrompt) {
+            terminalConfigEnv[OMP_THEME_ENV_VAR] = ompThemeName;
+          }
+
+          if (shellName.includes(SHELL_NAME_BASH)) {
+            const bashRcFilePath = getRcFilePath(options.cwd || cwd, SHELL_NAME_BASH);
+            terminalConfigEnv.BASH_ENV = bashRcFilePath;
+            terminalConfigEnv.AUTOMAKER_CUSTOM_PROMPT = effectiveConfig.customPrompt
+              ? 'true'
+              : 'false';
+            terminalConfigEnv.AUTOMAKER_THEME = currentTheme;
+            shellArgs = applyBashRcFileArgs(shellArgs, bashRcFilePath);
+          } else if (shellName.includes(SHELL_NAME_ZSH)) {
+            terminalConfigEnv.ZDOTDIR = getTerminalDir(options.cwd || cwd);
+            terminalConfigEnv.AUTOMAKER_CUSTOM_PROMPT = effectiveConfig.customPrompt
+              ? 'true'
+              : 'false';
+            terminalConfigEnv.AUTOMAKER_THEME = currentTheme;
+          } else if (shellName === SHELL_NAME_SH) {
+            terminalConfigEnv.ENV = getRcFilePath(options.cwd || cwd, SHELL_NAME_SH);
+            terminalConfigEnv.AUTOMAKER_CUSTOM_PROMPT = effectiveConfig.customPrompt
+              ? 'true'
+              : 'false';
+            terminalConfigEnv.AUTOMAKER_THEME = currentTheme;
+          }
+
+          // Add custom env vars from config
+          Object.assign(terminalConfigEnv, effectiveConfig.customEnvVars);
+
+          logger.info(
+            `[createSession] Terminal config enabled for session ${id}, shell: ${shellName}`
+          );
+        }
+      } catch (error) {
+        logger.warn(`[createSession] Failed to apply terminal config: ${error}`);
+      }
+    }
+
     const env: Record<string, string> = {
       ...cleanEnv,
       TERM: 'xterm-256color',
@@ -341,6 +553,7 @@ export class TerminalService extends EventEmitter {
       LANG: process.env.LANG || 'en_US.UTF-8',
       LC_ALL: process.env.LC_ALL || process.env.LANG || 'en_US.UTF-8',
       ...options.env,
+      ...terminalConfigEnv, // Apply terminal config env vars last (highest priority)
     };
 
     logger.info(`Creating session ${id} with shell: ${shell} in ${cwd}`);
@@ -652,6 +865,44 @@ export class TerminalService extends EventEmitter {
     return () => this.exitCallbacks.delete(callback);
   }
 
+  /**
+   * Handle theme change - regenerate RC files with new theme colors
+   */
+  async onThemeChange(projectPath: string, newTheme: string): Promise<void> {
+    if (!this.settingsService) {
+      logger.warn('[onThemeChange] SettingsService not available');
+      return;
+    }
+
+    try {
+      const globalSettings = await this.settingsService.getGlobalSettings();
+      const terminalConfig = globalSettings?.terminalConfig;
+      const projectSettings = await this.settingsService.getProjectSettings(projectPath);
+      const projectTerminalConfig = projectSettings?.terminalConfig;
+      const effectiveConfig = buildEffectiveTerminalConfig(terminalConfig, projectTerminalConfig);
+
+      if (effectiveConfig.enabled && terminalConfig) {
+        const themeColors = getTerminalThemeColors(
+          newTheme as import('@automaker/types').ThemeMode
+        );
+        const allThemes = getAllTerminalThemes();
+
+        // Regenerate RC files with new theme
+        await ensureRcFilesUpToDate(
+          projectPath,
+          newTheme as import('@automaker/types').ThemeMode,
+          effectiveConfig,
+          themeColors,
+          allThemes
+        );
+
+        logger.info(`[onThemeChange] Regenerated RC files for theme: ${newTheme}`);
+      }
+    } catch (error) {
+      logger.error(`[onThemeChange] Failed to regenerate RC files: ${error}`);
+    }
+  }
+
   /**
    * Clean up all sessions
    */
@@ -676,9 +927,9 @@ export class TerminalService extends EventEmitter {
 // Singleton instance
 let terminalService: TerminalService | null = null;
 
-export function getTerminalService(): TerminalService {
+export function getTerminalService(settingsService?: SettingsService): TerminalService {
   if (!terminalService) {
-    terminalService = new TerminalService();
+    terminalService = new TerminalService(settingsService);
   }
   return terminalService;
 }

apps/server/src/services/typed-event-bus.ts

@@ -0,0 +1,112 @@
+/**
+ * TypedEventBus - Type-safe event emission wrapper for AutoModeService
+ *
+ * This class wraps the existing EventEmitter to provide type-safe event emission,
+ * specifically encapsulating the `emitAutoModeEvent` pattern used throughout AutoModeService.
+ *
+ * Key behavior:
+ * - emitAutoModeEvent wraps events in 'auto-mode:event' format for frontend consumption
+ * - Preserves all existing event emission patterns for backward compatibility
+ * - Frontend receives events in the exact same format as before (no breaking changes)
+ */
+
+import type { EventEmitter, EventType, EventCallback } from '../lib/events.js';
+
+/**
+ * Auto-mode event types that can be emitted through the TypedEventBus.
+ * These correspond to the event types expected by the frontend.
+ */
+export type AutoModeEventType =
+  | 'auto_mode_started'
+  | 'auto_mode_stopped'
+  | 'auto_mode_idle'
+  | 'auto_mode_error'
+  | 'auto_mode_paused_failures'
+  | 'auto_mode_feature_start'
+  | 'auto_mode_feature_complete'
+  | 'auto_mode_feature_resuming'
+  | 'auto_mode_progress'
+  | 'auto_mode_tool'
+  | 'auto_mode_task_started'
+  | 'auto_mode_task_complete'
+  | 'auto_mode_task_status'
+  | 'auto_mode_phase_complete'
+  | 'auto_mode_summary'
+  | 'auto_mode_resuming_features'
+  | 'planning_started'
+  | 'plan_approval_required'
+  | 'plan_approved'
+  | 'plan_auto_approved'
+  | 'plan_rejected'
+  | 'plan_revision_requested'
+  | 'plan_revision_warning'
+  | 'plan_spec_updated'
+  | 'pipeline_step_started'
+  | 'pipeline_step_complete'
+  | 'pipeline_test_failed'
+  | 'pipeline_merge_conflict'
+  | 'feature_status_changed'
+  | 'features_reconciled';
+
+/**
+ * TypedEventBus wraps an EventEmitter to provide type-safe event emission
+ * with the auto-mode event wrapping pattern.
+ */
+export class TypedEventBus {
+  private events: EventEmitter;
+
+  /**
+   * Create a TypedEventBus wrapping an existing EventEmitter.
+   * @param events - The underlying EventEmitter to wrap
+   */
+  constructor(events: EventEmitter) {
+    this.events = events;
+  }
+
+  /**
+   * Emit a raw event directly to subscribers.
+   * Use this for non-auto-mode events that don't need wrapping.
+   * @param type - The event type
+   * @param payload - The event payload
+   */
+  emit(type: EventType, payload: unknown): void {
+    this.events.emit(type, payload);
+  }
+
+  /**
+   * Emit an auto-mode event wrapped in the correct format for the client.
+   * All auto-mode events are sent as type "auto-mode:event" with the actual
+   * event type and data in the payload.
+   *
+   * This produces the exact same event format that the frontend expects:
+   * { type: eventType, ...data }
+   *
+   * @param eventType - The auto-mode event type (e.g., 'auto_mode_started')
+   * @param data - Additional data to include in the event payload
+   */
+  emitAutoModeEvent(eventType: AutoModeEventType, data: Record<string, unknown>): void {
+    // Wrap the event in auto-mode:event format expected by the client
+    this.events.emit('auto-mode:event', {
+      type: eventType,
+      ...data,
+    });
+  }
+
+  /**
+   * Subscribe to all events from the underlying emitter.
+   * @param callback - Function called with (type, payload) for each event
+   * @returns Unsubscribe function
+   */
+  subscribe(callback: EventCallback): () => void {
+    return this.events.subscribe(callback);
+  }
+
+  /**
+   * Get the underlying EventEmitter for cases where direct access is needed.
+   * Use sparingly - prefer the typed methods when possible.
+   * @returns The wrapped EventEmitter
+   */
+  getUnderlyingEmitter(): EventEmitter {
+    return this.events;
+  }
+}

apps/server/src/services/worktree-resolver.ts

@@ -0,0 +1,170 @@
+/**
+ * WorktreeResolver - Git worktree discovery and resolution
+ *
+ * Extracted from AutoModeService to provide a standalone service for:
+ * - Finding existing worktrees for a given branch
+ * - Getting the current branch of a repository
+ * - Listing all worktrees with their metadata
+ *
+ * Key behaviors:
+ * - Parses `git worktree list --porcelain` output
+ * - Always resolves paths to absolute (cross-platform compatibility)
+ * - Handles detached HEAD and bare worktrees gracefully
+ */
+
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import path from 'path';
+
+const execAsync = promisify(exec);
+
+/**
+ * Information about a git worktree
+ */
+export interface WorktreeInfo {
+  /** Absolute path to the worktree directory */
+  path: string;
+  /** Branch name (without refs/heads/ prefix), or null if detached HEAD */
+  branch: string | null;
+  /** Whether this is the main worktree (first in git worktree list) */
+  isMain: boolean;
+}
+
+/**
+ * WorktreeResolver handles git worktree discovery and path resolution.
+ *
+ * This service is responsible for:
+ * 1. Finding existing worktrees by branch name
+ * 2. Getting the current branch of a repository
+ * 3. Listing all worktrees with normalized paths
+ */
+export class WorktreeResolver {
+  /**
+   * Get the current branch name for a git repository
+   *
+   * @param projectPath - Path to the git repository
+   * @returns The current branch name, or null if not in a git repo or on detached HEAD
+   */
+  async getCurrentBranch(projectPath: string): Promise<string | null> {
+    try {
+      const { stdout } = await execAsync('git branch --show-current', { cwd: projectPath });
+      const branch = stdout.trim();
+      return branch || null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Find an existing worktree for a given branch name
+   *
+   * @param projectPath - Path to the git repository (main worktree)
+   * @param branchName - Branch name to find worktree for
+   * @returns Absolute path to the worktree, or null if not found
+   */
+  async findWorktreeForBranch(projectPath: string, branchName: string): Promise<string | null> {
+    try {
+      const { stdout } = await execAsync('git worktree list --porcelain', {
+        cwd: projectPath,
+      });
+
+      const lines = stdout.split('\n');
+      let currentPath: string | null = null;
+      let currentBranch: string | null = null;
+
+      for (const line of lines) {
+        if (line.startsWith('worktree ')) {
+          currentPath = line.slice(9);
+        } else if (line.startsWith('branch ')) {
+          currentBranch = line.slice(7).replace('refs/heads/', '');
+        } else if (line === '' && currentPath && currentBranch) {
+          // End of a worktree entry
+          if (currentBranch === branchName) {
+            // Resolve to absolute path - git may return relative paths
+            // On Windows, this is critical for cwd to work correctly
+            // On all platforms, absolute paths ensure consistent behavior
+            return this.resolvePath(projectPath, currentPath);
+          }
+          currentPath = null;
+          currentBranch = null;
+        }
+      }
+
+      // Check the last entry (if file doesn't end with newline)
+      if (currentPath && currentBranch && currentBranch === branchName) {
+        return this.resolvePath(projectPath, currentPath);
+      }
+
+      return null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * List all worktrees for a repository
+   *
+   * @param projectPath - Path to the git repository
+   * @returns Array of WorktreeInfo objects with normalized paths
+   */
+  async listWorktrees(projectPath: string): Promise<WorktreeInfo[]> {
+    try {
+      const { stdout } = await execAsync('git worktree list --porcelain', {
+        cwd: projectPath,
+      });
+
+      const worktrees: WorktreeInfo[] = [];
+      const lines = stdout.split('\n');
+      let currentPath: string | null = null;
+      let currentBranch: string | null = null;
+      let isFirstWorktree = true;
+
+      for (const line of lines) {
+        if (line.startsWith('worktree ')) {
+          currentPath = line.slice(9);
+        } else if (line.startsWith('branch ')) {
+          currentBranch = line.slice(7).replace('refs/heads/', '');
+        } else if (line.startsWith('detached')) {
+          // Detached HEAD - branch is null
+          currentBranch = null;
+        } else if (line === '' && currentPath) {
+          // End of a worktree entry
+          worktrees.push({
+            path: this.resolvePath(projectPath, currentPath),
+            branch: currentBranch,
+            isMain: isFirstWorktree,
+          });
+          currentPath = null;
+          currentBranch = null;
+          isFirstWorktree = false;
+        }
+      }
+
+      // Handle last entry if file doesn't end with newline
+      if (currentPath) {
+        worktrees.push({
+          path: this.resolvePath(projectPath, currentPath),
+          branch: currentBranch,
+          isMain: isFirstWorktree,
+        });
+      }
+
+      return worktrees;
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Resolve a path to absolute, handling both relative and absolute inputs
+   *
+   * @param projectPath - Base path for relative resolution
+   * @param worktreePath - Path from git worktree list output
+   * @returns Absolute path
+   */
+  private resolvePath(projectPath: string, worktreePath: string): string {
+    return path.isAbsolute(worktreePath)
+      ? path.resolve(worktreePath)
+      : path.resolve(projectPath, worktreePath);
+  }
+}

apps/server/tests/integration/helpers/git-test-repo.ts

@@ -20,8 +20,8 @@ export interface TestRepo {
 export async function createTestGitRepo(): Promise<TestRepo> {
   const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'automaker-test-'));
 
-  // Initialize git repo
-  await execAsync('git init', { cwd: tmpDir });
+  // Initialize git repo with 'main' as the default branch (matching GitHub's standard)
+  await execAsync('git init --initial-branch=main', { cwd: tmpDir });
 
   // Use environment variables instead of git config to avoid affecting user's git config
   // These env vars override git config without modifying it
@@ -38,9 +38,6 @@ export async function createTestGitRepo(): Promise<TestRepo> {
   await execAsync('git add .', { cwd: tmpDir, env: gitEnv });
   await execAsync('git commit -m "Initial commit"', { cwd: tmpDir, env: gitEnv });
 
-  // Create main branch explicitly
-  await execAsync('git branch -M main', { cwd: tmpDir });
-
   return {
     path: tmpDir,
     cleanup: async () => {

apps/server/tests/integration/routes/worktree/create.integration.test.ts

@@ -14,7 +14,8 @@ describe('worktree create route - repositories without commits', () => {
 
   async function initRepoWithoutCommit() {
     repoPath = await fs.mkdtemp(path.join(os.tmpdir(), 'automaker-no-commit-'));
-    await execAsync('git init', { cwd: repoPath });
+    // Initialize with 'main' as the default branch (matching GitHub's standard)
+    await execAsync('git init --initial-branch=main', { cwd: repoPath });
     // Don't set git config - use environment variables in commit operations instead
     // to avoid affecting user's git config
     // Intentionally skip creating an initial commit

apps/server/tests/integration/services/auto-mode-service.integration.test.ts

@@ -1,694 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { AutoModeService } from '@/services/auto-mode-service.js';
-import { ProviderFactory } from '@/providers/provider-factory.js';
-import { FeatureLoader } from '@/services/feature-loader.js';
-import {
-  createTestGitRepo,
-  createTestFeature,
-  listBranches,
-  listWorktrees,
-  branchExists,
-  worktreeExists,
-  type TestRepo,
-} from '../helpers/git-test-repo.js';
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import { exec } from 'child_process';
-import { promisify } from 'util';
-
-const execAsync = promisify(exec);
-
-vi.mock('@/providers/provider-factory.js');
-
-describe('auto-mode-service.ts (integration)', () => {
-  let service: AutoModeService;
-  let testRepo: TestRepo;
-  let featureLoader: FeatureLoader;
-  const mockEvents = {
-    subscribe: vi.fn(),
-    emit: vi.fn(),
-  };
-
-  beforeEach(async () => {
-    vi.clearAllMocks();
-    service = new AutoModeService(mockEvents as any);
-    featureLoader = new FeatureLoader();
-    testRepo = await createTestGitRepo();
-  });
-
-  afterEach(async () => {
-    // Stop any running auto loops
-    await service.stopAutoLoop();
-
-    // Cleanup test repo
-    if (testRepo) {
-      await testRepo.cleanup();
-    }
-  });
-
-  describe('worktree operations', () => {
-    it('should use existing git worktree for feature', async () => {
-      const branchName = 'feature/test-feature-1';
-
-      // Create a test feature with branchName set
-      await createTestFeature(testRepo.path, 'test-feature-1', {
-        id: 'test-feature-1',
-        category: 'test',
-        description: 'Test feature',
-        status: 'pending',
-        branchName: branchName,
-      });
-
-      // Create worktree before executing (worktrees are now created when features are added/edited)
-      const worktreesDir = path.join(testRepo.path, '.worktrees');
-      const worktreePath = path.join(worktreesDir, 'test-feature-1');
-      await fs.mkdir(worktreesDir, { recursive: true });
-      await execAsync(`git worktree add -b ${branchName} "${worktreePath}" HEAD`, {
-        cwd: testRepo.path,
-      });
-
-      // Mock provider to complete quickly
-      const mockProvider = {
-        getName: () => 'claude',
-        executeQuery: async function* () {
-          yield {
-            type: 'assistant',
-            message: {
-              role: 'assistant',
-              content: [{ type: 'text', text: 'Feature implemented' }],
-            },
-          };
-          yield {
-            type: 'result',
-            subtype: 'success',
-          };
-        },
-      };
-
-      vi.mocked(ProviderFactory.getProviderForModel).mockReturnValue(mockProvider as any);
-
-      // Execute feature with worktrees enabled
-      await service.executeFeature(
-        testRepo.path,
-        'test-feature-1',
-        true, // useWorktrees
-        false // isAutoMode
-      );
-
-      // Verify branch exists (was created when worktree was created)
-      const branches = await listBranches(testRepo.path);
-      expect(branches).toContain(branchName);
-
-      // Verify worktree exists and is being used
-      // The service should have found and used the worktree (check via logs)
-      // We can verify the worktree exists by checking git worktree list
-      const worktrees = await listWorktrees(testRepo.path);
-      expect(worktrees.length).toBeGreaterThan(0);
-      // Verify that at least one worktree path contains our feature ID
-      const worktreePathsMatch = worktrees.some(
-        (wt) => wt.includes('test-feature-1') || wt.includes('.worktrees')
-      );
-      expect(worktreePathsMatch).toBe(true);
-
-      // Note: Worktrees are not automatically cleaned up by the service
-      // This is expected behavior - manual cleanup is required
-    }, 30000);
-
-    it('should handle error gracefully', async () => {
-      await createTestFeature(testRepo.path, 'test-feature-error', {
-        id: 'test-feature-error',
-        category: 'test',
-        description: 'Test feature that errors',
-        status: 'pending',
-      });
-
-      // Mock provider that throws error
-      const mockProvider = {
-        getName: () => 'claude',
-        executeQuery: async function* () {
-          throw new Error('Provider error');
-        },
-      };
-
-      vi.mocked(ProviderFactory.getProviderForModel).mockReturnValue(mockProvider as any);
-
-      // Execute feature (should handle error)
-      await service.executeFeature(testRepo.path, 'test-feature-error', true, false);
-
-      // Verify feature status was updated to backlog (error status)
-      const feature = await featureLoader.get(testRepo.path, 'test-feature-error');
-      expect(feature?.status).toBe('backlog');
-    }, 30000);
-
-    it('should work without worktrees', async () => {
-      await createTestFeature(testRepo.path, 'test-no-worktree', {
-        id: 'test-no-worktree',
-        category: 'test',
-        description: 'Test without worktree',
-        status: 'pending',
-        skipTests: true,
-      });
-
-      const mockProvider = {
-        getName: () => 'claude',
-        executeQuery: async function* () {
-          yield {
-            type: 'result',
-            subtype: 'success',
-          };
-        },
-      };
-
-      vi.mocked(ProviderFactory.getProviderForModel).mockReturnValue(mockProvider as any);
-
-      // Execute without worktrees
-      await service.executeFeature(
-        testRepo.path,
-        'test-no-worktree',
-        false, // useWorktrees = false
-        false
-      );
-
-      // Feature should be updated successfully
-      const feature = await featureLoader.get(testRepo.path, 'test-no-worktree');
-      expect(feature?.status).toBe('waiting_approval');
-    }, 30000);
-  });
-
-  describe('feature execution', () => {
-    it('should execute feature and update status', async () => {
-      await createTestFeature(testRepo.path, 'feature-exec-1', {
-        id: 'feature-exec-1',
-        category: 'ui',
-        description: 'Execute this feature',
-        status: 'pending',
-        skipTests: true,
-      });
-
-      const mockProvider = {
-        getName: () => 'claude',
-        executeQuery: async function* () {
-          yield {
-            type: 'assistant',
-            message: {
-              role: 'assistant',
-              content: [{ type: 'text', text: 'Implemented the feature' }],
-            },
-          };
-          yield {
-            type: 'result',
-            subtype: 'success',
-          };
-        },
-      };
-
-      vi.mocked(ProviderFactory.getProviderForModel).mockReturnValue(mockProvider as any);
-
-      await service.executeFeature(
-        testRepo.path,
-        'feature-exec-1',
-        false, // Don't use worktrees so agent output is saved to main project
-        false
-      );
-
-      // Check feature status was updated
-      const feature = await featureLoader.get(testRepo.path, 'feature-exec-1');
-      expect(feature?.status).toBe('waiting_approval');
-
-      // Check agent output was saved
-      const agentOutput = await featureLoader.getAgentOutput(testRepo.path, 'feature-exec-1');
-      expect(agentOutput).toBeTruthy();
-      expect(agentOutput).toContain('Implemented the feature');
-    }, 30000);
-
-    it('should handle feature not found', async () => {
-      const mockProvider = {
-        getName: () => 'claude',
-        executeQuery: async function* () {
-          yield {
-            type: 'result',
-            subtype: 'success',
-          };
-        },
-      };
-
-      vi.mocked(ProviderFactory.getProviderForModel).mockReturnValue(mockProvider as any);
-
-      // Try to execute non-existent feature
-      await service.executeFeature(testRepo.path, 'nonexistent-feature', true, false);
-
-      // Should emit error event
-      expect(mockEvents.emit).toHaveBeenCalledWith(
-        expect.any(String),
-        expect.objectContaining({
-          featureId: 'nonexistent-feature',
-          error: expect.stringContaining('not found'),
-        })
-      );
-    }, 30000);
-
-    it('should prevent duplicate feature execution', async () => {
-      await createTestFeature(testRepo.path, 'feature-dup', {
-        id: 'feature-dup',
-        category: 'test',
-        description: 'Duplicate test',
-        status: 'pending',
-      });
-
-      const mockProvider = {
-        getName: () => 'claude',
-        executeQuery: async function* () {
-          // Simulate slow execution
-          await new Promise((resolve) => setTimeout(resolve, 500));
-          yield {
-            type: 'result',
-            subtype: 'success',
-          };
-        },
-      };
-
-      vi.mocked(ProviderFactory.getProviderForModel).mockReturnValue(mockProvider as any);
-
-      // Start first execution
-      const promise1 = service.executeFeature(testRepo.path, 'feature-dup', false, false);
-
-      // Try to start second execution (should throw)
-      await expect(
-        service.executeFeature(testRepo.path, 'feature-dup', false, false)
-      ).rejects.toThrow('already running');
-
-      await promise1;
-    }, 30000);
-
-    it('should use feature-specific model', async () => {
-      await createTestFeature(testRepo.path, 'feature-model', {
-        id: 'feature-model',
-        category: 'test',
-        description: 'Model test',
-        status: 'pending',
-        model: 'claude-sonnet-4-20250514',
-      });
-
-      const mockProvider = {
-        getName: () => 'claude',
-        executeQuery: async function* () {
-          yield {
-            type: 'result',
-            subtype: 'success',
-          };
-        },
-      };
-
-      vi.mocked(ProviderFactory.getProviderForModel).mockReturnValue(mockProvider as any);
-
-      await service.executeFeature(testRepo.path, 'feature-model', false, false);
-
-      // Should have used claude-sonnet-4-20250514
-      expect(ProviderFactory.getProviderForModel).toHaveBeenCalledWith('claude-sonnet-4-20250514');
-    }, 30000);
-  });
-
-  describe('auto loop', () => {
-    it('should start and stop auto loop', async () => {
-      const startPromise = service.startAutoLoop(testRepo.path, 2);
-
-      // Give it time to start
-      await new Promise((resolve) => setTimeout(resolve, 100));
-
-      // Stop the loop
-      const runningCount = await service.stopAutoLoop();
-
-      expect(runningCount).toBe(0);
-      await startPromise.catch(() => {}); // Cleanup
-    }, 10000);
-
-    it('should process pending features in auto loop', async () => {
-      // Create multiple pending features
-      await createTestFeature(testRepo.path, 'auto-1', {
-        id: 'auto-1',
-        category: 'test',
-        description: 'Auto feature 1',
-        status: 'pending',
-        skipTests: true,
-      });
-
-      await createTestFeature(testRepo.path, 'auto-2', {
-        id: 'auto-2',
-        category: 'test',
-        description: 'Auto feature 2',
-        status: 'pending',
-        skipTests: true,
-      });
-
-      const mockProvider = {
-        getName: () => 'claude',
-        executeQuery: async function* () {
-          yield {
-            type: 'result',
-            subtype: 'success',
-          };
-        },
-      };
-
-      vi.mocked(ProviderFactory.getProviderForModel).mockReturnValue(mockProvider as any);
-
-      // Start auto loop
-      const startPromise = service.startAutoLoop(testRepo.path, 2);
-
-      // Wait for features to be processed
-      await new Promise((resolve) => setTimeout(resolve, 3000));
-
-      // Stop the loop
-      await service.stopAutoLoop();
-      await startPromise.catch(() => {});
-
-      // Check that features were updated
-      const feature1 = await featureLoader.get(testRepo.path, 'auto-1');
-      const feature2 = await featureLoader.get(testRepo.path, 'auto-2');
-
-      // At least one should have been processed
-      const processedCount = [feature1, feature2].filter(
-        (f) => f?.status === 'waiting_approval' || f?.status === 'in_progress'
-      ).length;
-
-      expect(processedCount).toBeGreaterThan(0);
-    }, 15000);
-
-    it('should respect max concurrency', async () => {
-      // Create 5 features
-      for (let i = 1; i <= 5; i++) {
-        await createTestFeature(testRepo.path, `concurrent-${i}`, {
-          id: `concurrent-${i}`,
-          category: 'test',
-          description: `Concurrent feature ${i}`,
-          status: 'pending',
-        });
-      }
-
-      let concurrentCount = 0;
-      let maxConcurrent = 0;
-
-      const mockProvider = {
-        getName: () => 'claude',
-        executeQuery: async function* () {
-          concurrentCount++;
-          maxConcurrent = Math.max(maxConcurrent, concurrentCount);
-
-          // Simulate work
-          await new Promise((resolve) => setTimeout(resolve, 500));
-
-          concurrentCount--;
-
-          yield {
-            type: 'result',
-            subtype: 'success',
-          };
-        },
-      };
-
-      vi.mocked(ProviderFactory.getProviderForModel).mockReturnValue(mockProvider as any);
-
-      // Start with max concurrency of 2
-      const startPromise = service.startAutoLoop(testRepo.path, 2);
-
-      // Wait for some features to be processed
-      await new Promise((resolve) => setTimeout(resolve, 3000));
-
-      await service.stopAutoLoop();
-      await startPromise.catch(() => {});
-
-      // Max concurrent should not exceed 2
-      expect(maxConcurrent).toBeLessThanOrEqual(2);
-    }, 15000);
-
-    it('should emit auto mode events', async () => {
-      const startPromise = service.startAutoLoop(testRepo.path, 1);
-
-      // Wait for start event
-      await new Promise((resolve) => setTimeout(resolve, 100));
-
-      // Check start event was emitted
-      const startEvent = mockEvents.emit.mock.calls.find((call) =>
-        call[1]?.message?.includes('Auto mode started')
-      );
-      expect(startEvent).toBeTruthy();
-
-      await service.stopAutoLoop();
-      await startPromise.catch(() => {});
-
-      // Check stop event was emitted (emitted immediately by stopAutoLoop)
-      const stopEvent = mockEvents.emit.mock.calls.find(
-        (call) =>
-          call[1]?.type === 'auto_mode_stopped' || call[1]?.message?.includes('Auto mode stopped')
-      );
-      expect(stopEvent).toBeTruthy();
-    }, 10000);
-  });
-
-  describe('error handling', () => {
-    it('should handle provider errors gracefully', async () => {
-      await createTestFeature(testRepo.path, 'error-feature', {
-        id: 'error-feature',
-        category: 'test',
-        description: 'Error test',
-        status: 'pending',
-      });
-
-      const mockProvider = {
-        getName: () => 'claude',
-        executeQuery: async function* () {
-          throw new Error('Provider execution failed');
-        },
-      };
-
-      vi.mocked(ProviderFactory.getProviderForModel).mockReturnValue(mockProvider as any);
-
-      // Should not throw
-      await service.executeFeature(testRepo.path, 'error-feature', true, false);
-
-      // Feature should be marked as backlog (error status)
-      const feature = await featureLoader.get(testRepo.path, 'error-feature');
-      expect(feature?.status).toBe('backlog');
-    }, 30000);
-
-    it('should continue auto loop after feature error', async () => {
-      await createTestFeature(testRepo.path, 'fail-1', {
-        id: 'fail-1',
-        category: 'test',
-        description: 'Will fail',
-        status: 'pending',
-      });
-
-      await createTestFeature(testRepo.path, 'success-1', {
-        id: 'success-1',
-        category: 'test',
-        description: 'Will succeed',
-        status: 'pending',
-      });
-
-      let callCount = 0;
-      const mockProvider = {
-        getName: () => 'claude',
-        executeQuery: async function* () {
-          callCount++;
-          if (callCount === 1) {
-            throw new Error('First feature fails');
-          }
-          yield {
-            type: 'result',
-            subtype: 'success',
-          };
-        },
-      };
-
-      vi.mocked(ProviderFactory.getProviderForModel).mockReturnValue(mockProvider as any);
-
-      const startPromise = service.startAutoLoop(testRepo.path, 1);
-
-      // Wait for both features to be attempted
-      await new Promise((resolve) => setTimeout(resolve, 5000));
-
-      await service.stopAutoLoop();
-      await startPromise.catch(() => {});
-
-      // Both features should have been attempted
-      expect(callCount).toBeGreaterThanOrEqual(1);
-    }, 15000);
-  });
-
-  describe('planning mode', () => {
-    it('should execute feature with skip planning mode', async () => {
-      await createTestFeature(testRepo.path, 'skip-plan-feature', {
-        id: 'skip-plan-feature',
-        category: 'test',
-        description: 'Feature with skip planning',
-        status: 'pending',
-        planningMode: 'skip',
-        skipTests: true,
-      });
-
-      const mockProvider = {
-        getName: () => 'claude',
-        executeQuery: async function* () {
-          yield {
-            type: 'assistant',
-            message: {
-              role: 'assistant',
-              content: [{ type: 'text', text: 'Feature implemented' }],
-            },
-          };
-          yield {
-            type: 'result',
-            subtype: 'success',
-          };
-        },
-      };
-
-      vi.mocked(ProviderFactory.getProviderForModel).mockReturnValue(mockProvider as any);
-
-      await service.executeFeature(testRepo.path, 'skip-plan-feature', false, false);
-
-      const feature = await featureLoader.get(testRepo.path, 'skip-plan-feature');
-      expect(feature?.status).toBe('waiting_approval');
-    }, 30000);
-
-    it('should execute feature with lite planning mode without approval', async () => {
-      await createTestFeature(testRepo.path, 'lite-plan-feature', {
-        id: 'lite-plan-feature',
-        category: 'test',
-        description: 'Feature with lite planning',
-        status: 'pending',
-        planningMode: 'lite',
-        requirePlanApproval: false,
-        skipTests: true,
-      });
-
-      const mockProvider = {
-        getName: () => 'claude',
-        executeQuery: async function* () {
-          yield {
-            type: 'assistant',
-            message: {
-              role: 'assistant',
-              content: [
-                {
-                  type: 'text',
-                  text: '[PLAN_GENERATED] Planning outline complete.\n\nFeature implemented',
-                },
-              ],
-            },
-          };
-          yield {
-            type: 'result',
-            subtype: 'success',
-          };
-        },
-      };
-
-      vi.mocked(ProviderFactory.getProviderForModel).mockReturnValue(mockProvider as any);
-
-      await service.executeFeature(testRepo.path, 'lite-plan-feature', false, false);
-
-      const feature = await featureLoader.get(testRepo.path, 'lite-plan-feature');
-      expect(feature?.status).toBe('waiting_approval');
-    }, 30000);
-
-    it('should emit planning_started event for spec mode', async () => {
-      await createTestFeature(testRepo.path, 'spec-plan-feature', {
-        id: 'spec-plan-feature',
-        category: 'test',
-        description: 'Feature with spec planning',
-        status: 'pending',
-        planningMode: 'spec',
-        requirePlanApproval: false,
-      });
-
-      const mockProvider = {
-        getName: () => 'claude',
-        executeQuery: async function* () {
-          yield {
-            type: 'assistant',
-            message: {
-              role: 'assistant',
-              content: [
-                { type: 'text', text: 'Spec generated\n\n[SPEC_GENERATED] Review the spec.' },
-              ],
-            },
-          };
-          yield {
-            type: 'result',
-            subtype: 'success',
-          };
-        },
-      };
-
-      vi.mocked(ProviderFactory.getProviderForModel).mockReturnValue(mockProvider as any);
-
-      await service.executeFeature(testRepo.path, 'spec-plan-feature', false, false);
-
-      // Check planning_started event was emitted
-      const planningEvent = mockEvents.emit.mock.calls.find((call) => call[1]?.mode === 'spec');
-      expect(planningEvent).toBeTruthy();
-    }, 30000);
-
-    it('should handle feature with full planning mode', async () => {
-      await createTestFeature(testRepo.path, 'full-plan-feature', {
-        id: 'full-plan-feature',
-        category: 'test',
-        description: 'Feature with full planning',
-        status: 'pending',
-        planningMode: 'full',
-        requirePlanApproval: false,
-      });
-
-      const mockProvider = {
-        getName: () => 'claude',
-        executeQuery: async function* () {
-          yield {
-            type: 'assistant',
-            message: {
-              role: 'assistant',
-              content: [
-                { type: 'text', text: 'Full spec with phases\n\n[SPEC_GENERATED] Review.' },
-              ],
-            },
-          };
-          yield {
-            type: 'result',
-            subtype: 'success',
-          };
-        },
-      };
-
-      vi.mocked(ProviderFactory.getProviderForModel).mockReturnValue(mockProvider as any);
-
-      await service.executeFeature(testRepo.path, 'full-plan-feature', false, false);
-
-      // Check planning_started event was emitted with full mode
-      const planningEvent = mockEvents.emit.mock.calls.find((call) => call[1]?.mode === 'full');
-      expect(planningEvent).toBeTruthy();
-    }, 30000);
-
-    it('should track pending approval correctly', async () => {
-      // Initially no pending approvals
-      expect(service.hasPendingApproval('non-existent')).toBe(false);
-    });
-
-    it('should cancel pending approval gracefully', () => {
-      // Should not throw when cancelling non-existent approval
-      expect(() => service.cancelPlanApproval('non-existent')).not.toThrow();
-    });
-
-    it('should resolve approval with error for non-existent feature', async () => {
-      const result = await service.resolvePlanApproval(
-        'non-existent',
-        true,
-        undefined,
-        undefined,
-        undefined
-      );
-      expect(result.success).toBe(false);
-      expect(result.error).toContain('No pending approval');
-    });
-  });
-});

apps/server/tests/unit/lib/model-resolver.test.ts

@@ -35,7 +35,7 @@ describe('model-resolver.ts', () => {
 
     it("should resolve 'opus' alias to full model string", () => {
       const result = resolveModelString('opus');
-      expect(result).toBe('claude-opus-4-5-20251101');
+      expect(result).toBe('claude-opus-4-6');
       expect(consoleSpy.log).toHaveBeenCalledWith(
         expect.stringContaining('Migrated legacy ID: "opus" -> "claude-opus"')
       );
@@ -117,7 +117,7 @@ describe('model-resolver.ts', () => {
   describe('getEffectiveModel', () => {
     it('should prioritize explicit model over session and default', () => {
       const result = getEffectiveModel('opus', 'haiku', 'gpt-5.2');
-      expect(result).toBe('claude-opus-4-5-20251101');
+      expect(result).toBe('claude-opus-4-6');
     });
 
     it('should use session model when explicit is not provided', () => {

apps/server/tests/unit/lib/sdk-options.test.ts

@@ -491,5 +491,29 @@ describe('sdk-options.ts', () => {
         expect(options.maxThinkingTokens).toBeUndefined();
       });
     });
+
+    describe('adaptive thinking for Opus 4.6', () => {
+      it('should not set maxThinkingTokens for adaptive thinking (model decides)', async () => {
+        const { createAutoModeOptions } = await import('@/lib/sdk-options.js');
+
+        const options = createAutoModeOptions({
+          cwd: '/test/path',
+          thinkingLevel: 'adaptive',
+        });
+
+        expect(options.maxThinkingTokens).toBeUndefined();
+      });
+
+      it('should not include maxThinkingTokens when thinkingLevel is "none"', async () => {
+        const { createAutoModeOptions } = await import('@/lib/sdk-options.js');
+
+        const options = createAutoModeOptions({
+          cwd: '/test/path',
+          thinkingLevel: 'none',
+        });
+
+        expect(options.maxThinkingTokens).toBeUndefined();
+      });
+    });
   });
 });

apps/server/tests/unit/providers/claude-provider.test.ts

@@ -39,7 +39,7 @@ describe('claude-provider.ts', () => {
 
       const generator = provider.executeQuery({
         prompt: 'Hello',
-        model: 'claude-opus-4-5-20251101',
+        model: 'claude-opus-4-6',
         cwd: '/test',
       });
 
@@ -59,7 +59,7 @@ describe('claude-provider.ts', () => {
 
       const generator = provider.executeQuery({
         prompt: 'Test prompt',
-        model: 'claude-opus-4-5-20251101',
+        model: 'claude-opus-4-6',
         cwd: '/test/dir',
         systemPrompt: 'You are helpful',
         maxTurns: 10,
@@ -71,7 +71,7 @@ describe('claude-provider.ts', () => {
       expect(sdk.query).toHaveBeenCalledWith({
         prompt: 'Test prompt',
         options: expect.objectContaining({
-          model: 'claude-opus-4-5-20251101',
+          model: 'claude-opus-4-6',
           systemPrompt: 'You are helpful',
           maxTurns: 10,
           cwd: '/test/dir',
@@ -91,7 +91,7 @@ describe('claude-provider.ts', () => {
 
       const generator = provider.executeQuery({
         prompt: 'Test',
-        model: 'claude-opus-4-5-20251101',
+        model: 'claude-opus-4-6',
         cwd: '/test',
       });
 
@@ -116,7 +116,7 @@ describe('claude-provider.ts', () => {
 
       const generator = provider.executeQuery({
         prompt: 'Test',
-        model: 'claude-opus-4-5-20251101',
+        model: 'claude-opus-4-6',
         cwd: '/test',
         abortController,
       });
@@ -145,7 +145,7 @@ describe('claude-provider.ts', () => {
 
       const generator = provider.executeQuery({
         prompt: 'Current message',
-        model: 'claude-opus-4-5-20251101',
+        model: 'claude-opus-4-6',
         cwd: '/test',
         conversationHistory,
         sdkSessionId: 'test-session-id',
@@ -176,7 +176,7 @@ describe('claude-provider.ts', () => {
 
       const generator = provider.executeQuery({
         prompt: arrayPrompt as any,
-        model: 'claude-opus-4-5-20251101',
+        model: 'claude-opus-4-6',
         cwd: '/test',
       });
 
@@ -187,7 +187,7 @@ describe('claude-provider.ts', () => {
       expect(typeof callArgs.prompt).not.toBe('string');
     });
 
-    it('should use maxTurns default of 20', async () => {
+    it('should use maxTurns default of 100', async () => {
       vi.mocked(sdk.query).mockReturnValue(
         (async function* () {
           yield { type: 'text', text: 'test' };
@@ -196,7 +196,7 @@ describe('claude-provider.ts', () => {
 
       const generator = provider.executeQuery({
         prompt: 'Test',
-        model: 'claude-opus-4-5-20251101',
+        model: 'claude-opus-4-6',
         cwd: '/test',
       });
 
@@ -205,7 +205,7 @@ describe('claude-provider.ts', () => {
       expect(sdk.query).toHaveBeenCalledWith({
         prompt: 'Test',
         options: expect.objectContaining({
-          maxTurns: 20,
+          maxTurns: 100,
         }),
       });
     });
@@ -222,7 +222,7 @@ describe('claude-provider.ts', () => {
 
       const generator = provider.executeQuery({
         prompt: 'Test',
-        model: 'claude-opus-4-5-20251101',
+        model: 'claude-opus-4-6',
         cwd: '/test',
       });
 
@@ -286,7 +286,7 @@ describe('claude-provider.ts', () => {
 
       const generator = provider.executeQuery({
         prompt: 'Test',
-        model: 'claude-opus-4-5-20251101',
+        model: 'claude-opus-4-6',
         cwd: '/test',
       });
 
@@ -313,7 +313,7 @@ describe('claude-provider.ts', () => {
 
       const generator = provider.executeQuery({
         prompt: 'Test',
-        model: 'claude-opus-4-5-20251101',
+        model: 'claude-opus-4-6',
         cwd: '/test',
       });
 
@@ -341,7 +341,7 @@ describe('claude-provider.ts', () => {
 
       const generator = provider.executeQuery({
         prompt: 'Test',
-        model: 'claude-opus-4-5-20251101',
+        model: 'claude-opus-4-6',
         cwd: '/test',
       });
 
@@ -366,12 +366,12 @@ describe('claude-provider.ts', () => {
       expect(models).toHaveLength(4);
     });
 
-    it('should include Claude Opus 4.5', () => {
+    it('should include Claude Opus 4.6', () => {
       const models = provider.getAvailableModels();
 
-      const opus = models.find((m) => m.id === 'claude-opus-4-5-20251101');
+      const opus = models.find((m) => m.id === 'claude-opus-4-6');
       expect(opus).toBeDefined();
-      expect(opus?.name).toBe('Claude Opus 4.5');
+      expect(opus?.name).toBe('Claude Opus 4.6');
       expect(opus?.provider).toBe('anthropic');
     });
 
@@ -400,7 +400,7 @@ describe('claude-provider.ts', () => {
     it('should mark Opus as default', () => {
       const models = provider.getAvailableModels();
 
-      const opus = models.find((m) => m.id === 'claude-opus-4-5-20251101');
+      const opus = models.find((m) => m.id === 'claude-opus-4-6');
       expect(opus?.default).toBe(true);
     });
 

apps/server/tests/unit/providers/provider-factory.test.ts

@@ -54,8 +54,8 @@ describe('provider-factory.ts', () => {
 
   describe('getProviderForModel', () => {
     describe('Claude models (claude-* prefix)', () => {
-      it('should return ClaudeProvider for claude-opus-4-5-20251101', () => {
-        const provider = ProviderFactory.getProviderForModel('claude-opus-4-5-20251101');
+      it('should return ClaudeProvider for claude-opus-4-6', () => {
+        const provider = ProviderFactory.getProviderForModel('claude-opus-4-6');
         expect(provider).toBeInstanceOf(ClaudeProvider);
       });
 
@@ -70,7 +70,7 @@ describe('provider-factory.ts', () => {
       });
 
       it('should be case-insensitive for claude models', () => {
-        const provider = ProviderFactory.getProviderForModel('CLAUDE-OPUS-4-5-20251101');
+        const provider = ProviderFactory.getProviderForModel('CLAUDE-OPUS-4-6');
         expect(provider).toBeInstanceOf(ClaudeProvider);
       });
     });

apps/server/tests/unit/routes/worktree/switch-branch.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
+import type { Request, Response } from 'express';
+import { createMockExpressContext } from '../../../utils/mocks.js';
+
+vi.mock('child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('child_process')>();
+  return {
+    ...actual,
+    exec: vi.fn(),
+  };
+});
+
+vi.mock('util', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('util')>();
+  return {
+    ...actual,
+    promisify: (fn: unknown) => fn,
+  };
+});
+
+import { exec } from 'child_process';
+import { createSwitchBranchHandler } from '@/routes/worktree/routes/switch-branch.js';
+
+const mockExec = exec as Mock;
+
+describe('switch-branch route', () => {
+  let req: Request;
+  let res: Response;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    const context = createMockExpressContext();
+    req = context.req;
+    res = context.res;
+  });
+
+  it('should allow switching when only untracked files exist', async () => {
+    req.body = {
+      worktreePath: '/repo/path',
+      branchName: 'feature/test',
+    };
+
+    mockExec.mockImplementation(async (command: string) => {
+      if (command === 'git rev-parse --abbrev-ref HEAD') {
+        return { stdout: 'main\n', stderr: '' };
+      }
+      if (command === 'git rev-parse --verify feature/test') {
+        return { stdout: 'abc123\n', stderr: '' };
+      }
+      if (command === 'git status --porcelain') {
+        return { stdout: '?? .automaker/\n?? notes.txt\n', stderr: '' };
+      }
+      if (command === 'git checkout "feature/test"') {
+        return { stdout: '', stderr: '' };
+      }
+      return { stdout: '', stderr: '' };
+    });
+
+    const handler = createSwitchBranchHandler();
+    await handler(req, res);
+
+    expect(res.json).toHaveBeenCalledWith({
+      success: true,
+      result: {
+        previousBranch: 'main',
+        currentBranch: 'feature/test',
+        message: "Switched to branch 'feature/test'",
+      },
+    });
+    expect(mockExec).toHaveBeenCalledWith('git checkout "feature/test"', { cwd: '/repo/path' });
+  });
+
+  it('should block switching when tracked files are modified', async () => {
+    req.body = {
+      worktreePath: '/repo/path',
+      branchName: 'feature/test',
+    };
+
+    mockExec.mockImplementation(async (command: string) => {
+      if (command === 'git rev-parse --abbrev-ref HEAD') {
+        return { stdout: 'main\n', stderr: '' };
+      }
+      if (command === 'git rev-parse --verify feature/test') {
+        return { stdout: 'abc123\n', stderr: '' };
+      }
+      if (command === 'git status --porcelain') {
+        return { stdout: ' M src/index.ts\n?? notes.txt\n', stderr: '' };
+      }
+      if (command === 'git status --short') {
+        return { stdout: ' M src/index.ts\n?? notes.txt\n', stderr: '' };
+      }
+      return { stdout: '', stderr: '' };
+    });
+
+    const handler = createSwitchBranchHandler();
+    await handler(req, res);
+
+    expect(res.status).toHaveBeenCalledWith(400);
+    expect(res.json).toHaveBeenCalledWith({
+      success: false,
+      error:
+        'Cannot switch branches: you have uncommitted changes (M src/index.ts). Please commit your changes first.',
+      code: 'UNCOMMITTED_CHANGES',
+    });
+  });
+});

apps/server/tests/unit/services/agent-executor.test.ts

@@ -0,0 +1,935 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  AgentExecutor,
+  type AgentExecutionOptions,
+  type AgentExecutionResult,
+  type WaitForApprovalFn,
+  type SaveFeatureSummaryFn,
+  type UpdateFeatureSummaryFn,
+  type BuildTaskPromptFn,
+} from '../../../src/services/agent-executor.js';
+import type { TypedEventBus } from '../../../src/services/typed-event-bus.js';
+import type { FeatureStateManager } from '../../../src/services/feature-state-manager.js';
+import type { PlanApprovalService } from '../../../src/services/plan-approval-service.js';
+import type { SettingsService } from '../../../src/services/settings-service.js';
+import type { BaseProvider } from '../../../src/providers/base-provider.js';
+
+/**
+ * Unit tests for AgentExecutor
+ *
+ * Note: Full integration tests for execute() require complex mocking of
+ * @automaker/utils and @automaker/platform which have module hoisting issues.
+ * These tests focus on:
+ * - Constructor injection
+ * - Interface exports
+ * - Type correctness
+ *
+ * Integration tests for streaming/marker detection are covered in E2E tests
+ * and auto-mode-service tests.
+ */
+describe('AgentExecutor', () => {
+  // Mock dependencies
+  let mockEventBus: TypedEventBus;
+  let mockFeatureStateManager: FeatureStateManager;
+  let mockPlanApprovalService: PlanApprovalService;
+  let mockSettingsService: SettingsService | null;
+
+  beforeEach(() => {
+    // Reset mocks
+    mockEventBus = {
+      emitAutoModeEvent: vi.fn(),
+    } as unknown as TypedEventBus;
+
+    mockFeatureStateManager = {
+      updateTaskStatus: vi.fn().mockResolvedValue(undefined),
+      updateFeaturePlanSpec: vi.fn().mockResolvedValue(undefined),
+      saveFeatureSummary: vi.fn().mockResolvedValue(undefined),
+    } as unknown as FeatureStateManager;
+
+    mockPlanApprovalService = {
+      waitForApproval: vi.fn(),
+    } as unknown as PlanApprovalService;
+
+    mockSettingsService = null;
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('constructor', () => {
+    it('should create instance with all dependencies', () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+      expect(executor).toBeInstanceOf(AgentExecutor);
+    });
+
+    it('should accept null settingsService', () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        null
+      );
+      expect(executor).toBeInstanceOf(AgentExecutor);
+    });
+
+    it('should accept undefined settingsService', () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService
+      );
+      expect(executor).toBeInstanceOf(AgentExecutor);
+    });
+
+    it('should store eventBus dependency', () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+      // Verify executor was created - actual use tested via execute()
+      expect(executor).toBeDefined();
+    });
+
+    it('should store featureStateManager dependency', () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+      expect(executor).toBeDefined();
+    });
+
+    it('should store planApprovalService dependency', () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+      expect(executor).toBeDefined();
+    });
+  });
+
+  describe('interface exports', () => {
+    it('should export AgentExecutionOptions type', () => {
+      // Type assertion test - if this compiles, the type is exported correctly
+      const options: AgentExecutionOptions = {
+        workDir: '/test',
+        featureId: 'test-feature',
+        prompt: 'Test prompt',
+        projectPath: '/project',
+        abortController: new AbortController(),
+        provider: {} as BaseProvider,
+        effectiveBareModel: 'claude-sonnet-4-20250514',
+      };
+      expect(options.featureId).toBe('test-feature');
+    });
+
+    it('should export AgentExecutionResult type', () => {
+      const result: AgentExecutionResult = {
+        responseText: 'test response',
+        specDetected: false,
+        tasksCompleted: 0,
+        aborted: false,
+      };
+      expect(result.aborted).toBe(false);
+    });
+
+    it('should export callback types', () => {
+      const waitForApproval: WaitForApprovalFn = async () => ({ approved: true });
+      const saveFeatureSummary: SaveFeatureSummaryFn = async () => {};
+      const updateFeatureSummary: UpdateFeatureSummaryFn = async () => {};
+      const buildTaskPrompt: BuildTaskPromptFn = () => 'prompt';
+
+      expect(typeof waitForApproval).toBe('function');
+      expect(typeof saveFeatureSummary).toBe('function');
+      expect(typeof updateFeatureSummary).toBe('function');
+      expect(typeof buildTaskPrompt).toBe('function');
+    });
+  });
+
+  describe('AgentExecutionOptions', () => {
+    it('should accept required options', () => {
+      const options: AgentExecutionOptions = {
+        workDir: '/test/workdir',
+        featureId: 'feature-123',
+        prompt: 'Test prompt',
+        projectPath: '/test/project',
+        abortController: new AbortController(),
+        provider: {} as BaseProvider,
+        effectiveBareModel: 'claude-sonnet-4-20250514',
+      };
+
+      expect(options.workDir).toBe('/test/workdir');
+      expect(options.featureId).toBe('feature-123');
+      expect(options.prompt).toBe('Test prompt');
+      expect(options.projectPath).toBe('/test/project');
+      expect(options.abortController).toBeInstanceOf(AbortController);
+      expect(options.effectiveBareModel).toBe('claude-sonnet-4-20250514');
+    });
+
+    it('should accept optional options', () => {
+      const options: AgentExecutionOptions = {
+        workDir: '/test/workdir',
+        featureId: 'feature-123',
+        prompt: 'Test prompt',
+        projectPath: '/test/project',
+        abortController: new AbortController(),
+        provider: {} as BaseProvider,
+        effectiveBareModel: 'claude-sonnet-4-20250514',
+        // Optional fields
+        imagePaths: ['/image1.png', '/image2.png'],
+        model: 'claude-sonnet-4-20250514',
+        planningMode: 'spec',
+        requirePlanApproval: true,
+        previousContent: 'Previous content',
+        systemPrompt: 'System prompt',
+        autoLoadClaudeMd: true,
+        thinkingLevel: 'medium',
+        branchName: 'feature-branch',
+        specAlreadyDetected: false,
+        existingApprovedPlanContent: 'Approved plan',
+        persistedTasks: [{ id: 'T001', description: 'Task 1', status: 'pending' }],
+        sdkOptions: {
+          maxTurns: 100,
+          allowedTools: ['read', 'write'],
+        },
+      };
+
+      expect(options.imagePaths).toHaveLength(2);
+      expect(options.planningMode).toBe('spec');
+      expect(options.requirePlanApproval).toBe(true);
+      expect(options.branchName).toBe('feature-branch');
+    });
+  });
+
+  describe('AgentExecutionResult', () => {
+    it('should contain responseText', () => {
+      const result: AgentExecutionResult = {
+        responseText: 'Full response text from agent',
+        specDetected: true,
+        tasksCompleted: 5,
+        aborted: false,
+      };
+      expect(result.responseText).toBe('Full response text from agent');
+    });
+
+    it('should contain specDetected flag', () => {
+      const result: AgentExecutionResult = {
+        responseText: '',
+        specDetected: true,
+        tasksCompleted: 0,
+        aborted: false,
+      };
+      expect(result.specDetected).toBe(true);
+    });
+
+    it('should contain tasksCompleted count', () => {
+      const result: AgentExecutionResult = {
+        responseText: '',
+        specDetected: true,
+        tasksCompleted: 10,
+        aborted: false,
+      };
+      expect(result.tasksCompleted).toBe(10);
+    });
+
+    it('should contain aborted flag', () => {
+      const result: AgentExecutionResult = {
+        responseText: '',
+        specDetected: false,
+        tasksCompleted: 3,
+        aborted: true,
+      };
+      expect(result.aborted).toBe(true);
+    });
+  });
+
+  describe('execute method signature', () => {
+    it('should have execute method', () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+      expect(typeof executor.execute).toBe('function');
+    });
+
+    it('should accept options and callbacks', () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+
+      // Type check - verifying the signature accepts the expected parameters
+      // Actual execution would require mocking external modules
+      const executeSignature = executor.execute.length;
+      // execute(options, callbacks) = 2 parameters
+      expect(executeSignature).toBe(2);
+    });
+  });
+
+  describe('callback types', () => {
+    it('WaitForApprovalFn should return approval result', async () => {
+      const waitForApproval: WaitForApprovalFn = vi.fn().mockResolvedValue({
+        approved: true,
+        feedback: 'Looks good',
+        editedPlan: undefined,
+      });
+
+      const result = await waitForApproval('feature-123', '/project');
+      expect(result.approved).toBe(true);
+      expect(result.feedback).toBe('Looks good');
+    });
+
+    it('WaitForApprovalFn should handle rejection with feedback', async () => {
+      const waitForApproval: WaitForApprovalFn = vi.fn().mockResolvedValue({
+        approved: false,
+        feedback: 'Please add more tests',
+        editedPlan: '## Revised Plan\n...',
+      });
+
+      const result = await waitForApproval('feature-123', '/project');
+      expect(result.approved).toBe(false);
+      expect(result.feedback).toBe('Please add more tests');
+      expect(result.editedPlan).toBeDefined();
+    });
+
+    it('SaveFeatureSummaryFn should accept parameters', async () => {
+      const saveSummary: SaveFeatureSummaryFn = vi.fn().mockResolvedValue(undefined);
+
+      await saveSummary('/project', 'feature-123', 'Feature summary text');
+      expect(saveSummary).toHaveBeenCalledWith('/project', 'feature-123', 'Feature summary text');
+    });
+
+    it('UpdateFeatureSummaryFn should accept parameters', async () => {
+      const updateSummary: UpdateFeatureSummaryFn = vi.fn().mockResolvedValue(undefined);
+
+      await updateSummary('/project', 'feature-123', 'Updated summary');
+      expect(updateSummary).toHaveBeenCalledWith('/project', 'feature-123', 'Updated summary');
+    });
+
+    it('BuildTaskPromptFn should return prompt string', () => {
+      const buildPrompt: BuildTaskPromptFn = vi.fn().mockReturnValue('Execute T001: Create file');
+
+      const task = { id: 'T001', description: 'Create file', status: 'pending' as const };
+      const allTasks = [task];
+      const prompt = buildPrompt(task, allTasks, 0, 'Plan content', 'Template', undefined);
+
+      expect(typeof prompt).toBe('string');
+      expect(prompt).toBe('Execute T001: Create file');
+    });
+  });
+
+  describe('dependency injection patterns', () => {
+    it('should allow different eventBus implementations', () => {
+      const customEventBus = {
+        emitAutoModeEvent: vi.fn(),
+        emit: vi.fn(),
+        on: vi.fn(),
+      } as unknown as TypedEventBus;
+
+      const executor = new AgentExecutor(
+        customEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+
+      expect(executor).toBeInstanceOf(AgentExecutor);
+    });
+
+    it('should allow different featureStateManager implementations', () => {
+      const customStateManager = {
+        updateTaskStatus: vi.fn().mockResolvedValue(undefined),
+        updateFeaturePlanSpec: vi.fn().mockResolvedValue(undefined),
+        saveFeatureSummary: vi.fn().mockResolvedValue(undefined),
+        loadFeature: vi.fn().mockResolvedValue(null),
+      } as unknown as FeatureStateManager;
+
+      const executor = new AgentExecutor(
+        mockEventBus,
+        customStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+
+      expect(executor).toBeInstanceOf(AgentExecutor);
+    });
+
+    it('should work with mock settingsService', () => {
+      const customSettingsService = {
+        getGlobalSettings: vi.fn().mockResolvedValue({}),
+        getCredentials: vi.fn().mockResolvedValue({}),
+      } as unknown as SettingsService;
+
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        customSettingsService
+      );
+
+      expect(executor).toBeInstanceOf(AgentExecutor);
+    });
+  });
+
+  describe('execute() behavior', () => {
+    /**
+     * Execution tests focus on verifiable behaviors without requiring
+     * full stream mocking. Complex integration scenarios are tested in E2E.
+     */
+
+    it('should return aborted=true when abort signal is already aborted', async () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+
+      // Create an already-aborted controller
+      const abortController = new AbortController();
+      abortController.abort();
+
+      // Mock provider that yields nothing (would check signal first)
+      const mockProvider = {
+        getName: () => 'mock',
+        executeQuery: vi.fn().mockImplementation(function* () {
+          // Generator yields nothing, simulating immediate abort check
+        }),
+      } as unknown as BaseProvider;
+
+      const options: AgentExecutionOptions = {
+        workDir: '/test',
+        featureId: 'test-feature',
+        prompt: 'Test prompt',
+        projectPath: '/project',
+        abortController,
+        provider: mockProvider,
+        effectiveBareModel: 'claude-sonnet-4-20250514',
+        planningMode: 'skip',
+      };
+
+      const callbacks = {
+        waitForApproval: vi.fn().mockResolvedValue({ approved: true }),
+        saveFeatureSummary: vi.fn(),
+        updateFeatureSummary: vi.fn(),
+        buildTaskPrompt: vi.fn().mockReturnValue('task prompt'),
+      };
+
+      // Execute - should complete without error even with aborted signal
+      const result = await executor.execute(options, callbacks);
+
+      // When stream is empty and signal is aborted before stream starts,
+      // the result depends on whether abort was checked
+      expect(result).toBeDefined();
+      expect(result.responseText).toBeDefined();
+    });
+
+    it('should initialize with previousContent when provided', async () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+
+      const mockProvider = {
+        getName: () => 'mock',
+        executeQuery: vi.fn().mockImplementation(function* () {
+          // Empty stream
+        }),
+      } as unknown as BaseProvider;
+
+      const options: AgentExecutionOptions = {
+        workDir: '/test',
+        featureId: 'test-feature',
+        prompt: 'Test prompt',
+        projectPath: '/project',
+        abortController: new AbortController(),
+        provider: mockProvider,
+        effectiveBareModel: 'claude-sonnet-4-20250514',
+        previousContent: 'Previous context from earlier session',
+      };
+
+      const callbacks = {
+        waitForApproval: vi.fn().mockResolvedValue({ approved: true }),
+        saveFeatureSummary: vi.fn(),
+        updateFeatureSummary: vi.fn(),
+        buildTaskPrompt: vi.fn().mockReturnValue('task prompt'),
+      };
+
+      const result = await executor.execute(options, callbacks);
+
+      // Response should start with previous content
+      expect(result.responseText).toContain('Previous context from earlier session');
+      expect(result.responseText).toContain('Follow-up Session');
+    });
+
+    it('should return specDetected=false when no spec markers in content', async () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+
+      const mockProvider = {
+        getName: () => 'mock',
+        executeQuery: vi.fn().mockImplementation(function* () {
+          yield {
+            type: 'assistant',
+            message: {
+              content: [{ type: 'text', text: 'Simple response without spec markers' }],
+            },
+          };
+          yield { type: 'result', subtype: 'success' };
+        }),
+      } as unknown as BaseProvider;
+
+      const options: AgentExecutionOptions = {
+        workDir: '/test',
+        featureId: 'test-feature',
+        prompt: 'Test prompt',
+        projectPath: '/project',
+        abortController: new AbortController(),
+        provider: mockProvider,
+        effectiveBareModel: 'claude-sonnet-4-20250514',
+        planningMode: 'skip', // No spec detection in skip mode
+      };
+
+      const callbacks = {
+        waitForApproval: vi.fn().mockResolvedValue({ approved: true }),
+        saveFeatureSummary: vi.fn(),
+        updateFeatureSummary: vi.fn(),
+        buildTaskPrompt: vi.fn().mockReturnValue('task prompt'),
+      };
+
+      const result = await executor.execute(options, callbacks);
+
+      expect(result.specDetected).toBe(false);
+      expect(result.responseText).toContain('Simple response without spec markers');
+    });
+
+    it('should emit auto_mode_progress events for text content', async () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+
+      const mockProvider = {
+        getName: () => 'mock',
+        executeQuery: vi.fn().mockImplementation(function* () {
+          yield {
+            type: 'assistant',
+            message: {
+              content: [{ type: 'text', text: 'First chunk of text' }],
+            },
+          };
+          yield {
+            type: 'assistant',
+            message: {
+              content: [{ type: 'text', text: 'Second chunk of text' }],
+            },
+          };
+          yield { type: 'result', subtype: 'success' };
+        }),
+      } as unknown as BaseProvider;
+
+      const options: AgentExecutionOptions = {
+        workDir: '/test',
+        featureId: 'test-feature',
+        prompt: 'Test prompt',
+        projectPath: '/project',
+        abortController: new AbortController(),
+        provider: mockProvider,
+        effectiveBareModel: 'claude-sonnet-4-20250514',
+        planningMode: 'skip',
+      };
+
+      const callbacks = {
+        waitForApproval: vi.fn().mockResolvedValue({ approved: true }),
+        saveFeatureSummary: vi.fn(),
+        updateFeatureSummary: vi.fn(),
+        buildTaskPrompt: vi.fn().mockReturnValue('task prompt'),
+      };
+
+      await executor.execute(options, callbacks);
+
+      // Should emit progress events for each text chunk
+      expect(mockEventBus.emitAutoModeEvent).toHaveBeenCalledWith('auto_mode_progress', {
+        featureId: 'test-feature',
+        branchName: null,
+        content: 'First chunk of text',
+      });
+      expect(mockEventBus.emitAutoModeEvent).toHaveBeenCalledWith('auto_mode_progress', {
+        featureId: 'test-feature',
+        branchName: null,
+        content: 'Second chunk of text',
+      });
+    });
+
+    it('should emit auto_mode_tool events for tool use', async () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+
+      const mockProvider = {
+        getName: () => 'mock',
+        executeQuery: vi.fn().mockImplementation(function* () {
+          yield {
+            type: 'assistant',
+            message: {
+              content: [
+                {
+                  type: 'tool_use',
+                  name: 'write_file',
+                  input: { path: '/test/file.ts', content: 'test content' },
+                },
+              ],
+            },
+          };
+          yield { type: 'result', subtype: 'success' };
+        }),
+      } as unknown as BaseProvider;
+
+      const options: AgentExecutionOptions = {
+        workDir: '/test',
+        featureId: 'test-feature',
+        prompt: 'Test prompt',
+        projectPath: '/project',
+        abortController: new AbortController(),
+        provider: mockProvider,
+        effectiveBareModel: 'claude-sonnet-4-20250514',
+        planningMode: 'skip',
+      };
+
+      const callbacks = {
+        waitForApproval: vi.fn().mockResolvedValue({ approved: true }),
+        saveFeatureSummary: vi.fn(),
+        updateFeatureSummary: vi.fn(),
+        buildTaskPrompt: vi.fn().mockReturnValue('task prompt'),
+      };
+
+      await executor.execute(options, callbacks);
+
+      // Should emit tool event
+      expect(mockEventBus.emitAutoModeEvent).toHaveBeenCalledWith('auto_mode_tool', {
+        featureId: 'test-feature',
+        branchName: null,
+        tool: 'write_file',
+        input: { path: '/test/file.ts', content: 'test content' },
+      });
+    });
+
+    it('should throw error when provider stream yields error message', async () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+
+      const mockProvider = {
+        getName: () => 'mock',
+        executeQuery: vi.fn().mockImplementation(function* () {
+          yield {
+            type: 'assistant',
+            message: {
+              content: [{ type: 'text', text: 'Starting...' }],
+            },
+          };
+          yield {
+            type: 'error',
+            error: 'API rate limit exceeded',
+          };
+        }),
+      } as unknown as BaseProvider;
+
+      const options: AgentExecutionOptions = {
+        workDir: '/test',
+        featureId: 'test-feature',
+        prompt: 'Test prompt',
+        projectPath: '/project',
+        abortController: new AbortController(),
+        provider: mockProvider,
+        effectiveBareModel: 'claude-sonnet-4-20250514',
+        planningMode: 'skip',
+      };
+
+      const callbacks = {
+        waitForApproval: vi.fn().mockResolvedValue({ approved: true }),
+        saveFeatureSummary: vi.fn(),
+        updateFeatureSummary: vi.fn(),
+        buildTaskPrompt: vi.fn().mockReturnValue('task prompt'),
+      };
+
+      await expect(executor.execute(options, callbacks)).rejects.toThrow('API rate limit exceeded');
+    });
+
+    it('should throw error when authentication fails in response', async () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+
+      const mockProvider = {
+        getName: () => 'mock',
+        executeQuery: vi.fn().mockImplementation(function* () {
+          yield {
+            type: 'assistant',
+            message: {
+              content: [{ type: 'text', text: 'Error: Invalid API key' }],
+            },
+          };
+        }),
+      } as unknown as BaseProvider;
+
+      const options: AgentExecutionOptions = {
+        workDir: '/test',
+        featureId: 'test-feature',
+        prompt: 'Test prompt',
+        projectPath: '/project',
+        abortController: new AbortController(),
+        provider: mockProvider,
+        effectiveBareModel: 'claude-sonnet-4-20250514',
+        planningMode: 'skip',
+      };
+
+      const callbacks = {
+        waitForApproval: vi.fn().mockResolvedValue({ approved: true }),
+        saveFeatureSummary: vi.fn(),
+        updateFeatureSummary: vi.fn(),
+        buildTaskPrompt: vi.fn().mockReturnValue('task prompt'),
+      };
+
+      await expect(executor.execute(options, callbacks)).rejects.toThrow('Authentication failed');
+    });
+
+    it('should accumulate responseText from multiple text blocks', async () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+
+      const mockProvider = {
+        getName: () => 'mock',
+        executeQuery: vi.fn().mockImplementation(function* () {
+          yield {
+            type: 'assistant',
+            message: {
+              content: [
+                { type: 'text', text: 'Part 1.' },
+                { type: 'text', text: ' Part 2.' },
+              ],
+            },
+          };
+          yield {
+            type: 'assistant',
+            message: {
+              content: [{ type: 'text', text: ' Part 3.' }],
+            },
+          };
+          yield { type: 'result', subtype: 'success' };
+        }),
+      } as unknown as BaseProvider;
+
+      const options: AgentExecutionOptions = {
+        workDir: '/test',
+        featureId: 'test-feature',
+        prompt: 'Test prompt',
+        projectPath: '/project',
+        abortController: new AbortController(),
+        provider: mockProvider,
+        effectiveBareModel: 'claude-sonnet-4-20250514',
+        planningMode: 'skip',
+      };
+
+      const callbacks = {
+        waitForApproval: vi.fn().mockResolvedValue({ approved: true }),
+        saveFeatureSummary: vi.fn(),
+        updateFeatureSummary: vi.fn(),
+        buildTaskPrompt: vi.fn().mockReturnValue('task prompt'),
+      };
+
+      const result = await executor.execute(options, callbacks);
+
+      // All parts should be in response text
+      expect(result.responseText).toContain('Part 1');
+      expect(result.responseText).toContain('Part 2');
+      expect(result.responseText).toContain('Part 3');
+    });
+
+    it('should return tasksCompleted=0 when no tasks executed', async () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+
+      const mockProvider = {
+        getName: () => 'mock',
+        executeQuery: vi.fn().mockImplementation(function* () {
+          yield {
+            type: 'assistant',
+            message: {
+              content: [{ type: 'text', text: 'Simple response' }],
+            },
+          };
+          yield { type: 'result', subtype: 'success' };
+        }),
+      } as unknown as BaseProvider;
+
+      const options: AgentExecutionOptions = {
+        workDir: '/test',
+        featureId: 'test-feature',
+        prompt: 'Test prompt',
+        projectPath: '/project',
+        abortController: new AbortController(),
+        provider: mockProvider,
+        effectiveBareModel: 'claude-sonnet-4-20250514',
+        planningMode: 'skip',
+      };
+
+      const callbacks = {
+        waitForApproval: vi.fn().mockResolvedValue({ approved: true }),
+        saveFeatureSummary: vi.fn(),
+        updateFeatureSummary: vi.fn(),
+        buildTaskPrompt: vi.fn().mockReturnValue('task prompt'),
+      };
+
+      const result = await executor.execute(options, callbacks);
+
+      expect(result.tasksCompleted).toBe(0);
+      expect(result.aborted).toBe(false);
+    });
+
+    it('should pass branchName to event payloads', async () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+
+      const mockProvider = {
+        getName: () => 'mock',
+        executeQuery: vi.fn().mockImplementation(function* () {
+          yield {
+            type: 'assistant',
+            message: {
+              content: [{ type: 'text', text: 'Response' }],
+            },
+          };
+          yield { type: 'result', subtype: 'success' };
+        }),
+      } as unknown as BaseProvider;
+
+      const options: AgentExecutionOptions = {
+        workDir: '/test',
+        featureId: 'test-feature',
+        prompt: 'Test prompt',
+        projectPath: '/project',
+        abortController: new AbortController(),
+        provider: mockProvider,
+        effectiveBareModel: 'claude-sonnet-4-20250514',
+        planningMode: 'skip',
+        branchName: 'feature/my-feature',
+      };
+
+      const callbacks = {
+        waitForApproval: vi.fn().mockResolvedValue({ approved: true }),
+        saveFeatureSummary: vi.fn(),
+        updateFeatureSummary: vi.fn(),
+        buildTaskPrompt: vi.fn().mockReturnValue('task prompt'),
+      };
+
+      await executor.execute(options, callbacks);
+
+      // Branch name should be passed to progress event
+      expect(mockEventBus.emitAutoModeEvent).toHaveBeenCalledWith(
+        'auto_mode_progress',
+        expect.objectContaining({
+          branchName: 'feature/my-feature',
+        })
+      );
+    });
+
+    it('should return correct result structure', async () => {
+      const executor = new AgentExecutor(
+        mockEventBus,
+        mockFeatureStateManager,
+        mockPlanApprovalService,
+        mockSettingsService
+      );
+
+      const mockProvider = {
+        getName: () => 'mock',
+        executeQuery: vi.fn().mockImplementation(function* () {
+          yield {
+            type: 'assistant',
+            message: {
+              content: [{ type: 'text', text: 'Test response' }],
+            },
+          };
+          yield { type: 'result', subtype: 'success' };
+        }),
+      } as unknown as BaseProvider;
+
+      const options: AgentExecutionOptions = {
+        workDir: '/test',
+        featureId: 'test-feature',
+        prompt: 'Test prompt',
+        projectPath: '/project',
+        abortController: new AbortController(),
+        provider: mockProvider,
+        effectiveBareModel: 'claude-sonnet-4-20250514',
+        planningMode: 'skip',
+      };
+
+      const callbacks = {
+        waitForApproval: vi.fn().mockResolvedValue({ approved: true }),
+        saveFeatureSummary: vi.fn(),
+        updateFeatureSummary: vi.fn(),
+        buildTaskPrompt: vi.fn().mockReturnValue('task prompt'),
+      };
+
+      const result = await executor.execute(options, callbacks);
+
+      // Verify result has all expected properties
+      expect(result).toHaveProperty('responseText');
+      expect(result).toHaveProperty('specDetected');
+      expect(result).toHaveProperty('tasksCompleted');
+      expect(result).toHaveProperty('aborted');
+
+      // Verify types
+      expect(typeof result.responseText).toBe('string');
+      expect(typeof result.specDetected).toBe('boolean');
+      expect(typeof result.tasksCompleted).toBe('number');
+      expect(typeof result.aborted).toBe('boolean');
+    });
+  });
+});

apps/server/tests/unit/services/auto-loop-coordinator.test.ts

@@ -0,0 +1,610 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import {
+  AutoLoopCoordinator,
+  getWorktreeAutoLoopKey,
+  type AutoModeConfig,
+  type ProjectAutoLoopState,
+  type ExecuteFeatureFn,
+  type LoadPendingFeaturesFn,
+  type SaveExecutionStateFn,
+  type ClearExecutionStateFn,
+  type ResetStuckFeaturesFn,
+  type IsFeatureFinishedFn,
+} from '../../../src/services/auto-loop-coordinator.js';
+import type { TypedEventBus } from '../../../src/services/typed-event-bus.js';
+import type { ConcurrencyManager } from '../../../src/services/concurrency-manager.js';
+import type { SettingsService } from '../../../src/services/settings-service.js';
+import type { Feature } from '@automaker/types';
+
+describe('auto-loop-coordinator.ts', () => {
+  // Mock dependencies
+  let mockEventBus: TypedEventBus;
+  let mockConcurrencyManager: ConcurrencyManager;
+  let mockSettingsService: SettingsService | null;
+
+  // Callback mocks
+  let mockExecuteFeature: ExecuteFeatureFn;
+  let mockLoadPendingFeatures: LoadPendingFeaturesFn;
+  let mockSaveExecutionState: SaveExecutionStateFn;
+  let mockClearExecutionState: ClearExecutionStateFn;
+  let mockResetStuckFeatures: ResetStuckFeaturesFn;
+  let mockIsFeatureFinished: IsFeatureFinishedFn;
+  let mockIsFeatureRunning: (featureId: string) => boolean;
+
+  let coordinator: AutoLoopCoordinator;
+
+  const testFeature: Feature = {
+    id: 'feature-1',
+    title: 'Test Feature',
+    category: 'test',
+    description: 'Test description',
+    status: 'ready',
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+
+    mockEventBus = {
+      emitAutoModeEvent: vi.fn(),
+    } as unknown as TypedEventBus;
+
+    mockConcurrencyManager = {
+      getRunningCountForWorktree: vi.fn().mockResolvedValue(0),
+      isRunning: vi.fn().mockReturnValue(false),
+    } as unknown as ConcurrencyManager;
+
+    mockSettingsService = {
+      getGlobalSettings: vi.fn().mockResolvedValue({
+        maxConcurrency: 3,
+        projects: [{ id: 'proj-1', path: '/test/project' }],
+        autoModeByWorktree: {},
+      }),
+    } as unknown as SettingsService;
+
+    // Callback mocks
+    mockExecuteFeature = vi.fn().mockResolvedValue(undefined);
+    mockLoadPendingFeatures = vi.fn().mockResolvedValue([]);
+    mockSaveExecutionState = vi.fn().mockResolvedValue(undefined);
+    mockClearExecutionState = vi.fn().mockResolvedValue(undefined);
+    mockResetStuckFeatures = vi.fn().mockResolvedValue(undefined);
+    mockIsFeatureFinished = vi.fn().mockReturnValue(false);
+    mockIsFeatureRunning = vi.fn().mockReturnValue(false);
+
+    coordinator = new AutoLoopCoordinator(
+      mockEventBus,
+      mockConcurrencyManager,
+      mockSettingsService,
+      mockExecuteFeature,
+      mockLoadPendingFeatures,
+      mockSaveExecutionState,
+      mockClearExecutionState,
+      mockResetStuckFeatures,
+      mockIsFeatureFinished,
+      mockIsFeatureRunning
+    );
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('getWorktreeAutoLoopKey', () => {
+    it('returns correct key for main worktree (null branch)', () => {
+      const key = getWorktreeAutoLoopKey('/test/project', null);
+      expect(key).toBe('/test/project::__main__');
+    });
+
+    it('returns correct key for named branch', () => {
+      const key = getWorktreeAutoLoopKey('/test/project', 'feature/test-1');
+      expect(key).toBe('/test/project::feature/test-1');
+    });
+
+    it("normalizes 'main' branch to null", () => {
+      const key = getWorktreeAutoLoopKey('/test/project', 'main');
+      expect(key).toBe('/test/project::__main__');
+    });
+  });
+
+  describe('startAutoLoopForProject', () => {
+    it('throws if loop already running for project/worktree', async () => {
+      // Start the first loop
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+
+      // Try to start another - should throw
+      await expect(coordinator.startAutoLoopForProject('/test/project', null, 1)).rejects.toThrow(
+        'Auto mode is already running for main worktree in project'
+      );
+    });
+
+    it('creates ProjectAutoLoopState with correct config', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', 'feature-branch', 2);
+
+      const config = coordinator.getAutoLoopConfigForProject('/test/project', 'feature-branch');
+      expect(config).toEqual({
+        maxConcurrency: 2,
+        useWorktrees: true,
+        projectPath: '/test/project',
+        branchName: 'feature-branch',
+      });
+    });
+
+    it('emits auto_mode_started event', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', null, 3);
+
+      expect(mockEventBus.emitAutoModeEvent).toHaveBeenCalledWith('auto_mode_started', {
+        message: 'Auto mode started with max 3 concurrent features',
+        projectPath: '/test/project',
+        branchName: null,
+        maxConcurrency: 3,
+      });
+    });
+
+    it('calls saveExecutionState', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', null, 3);
+
+      expect(mockSaveExecutionState).toHaveBeenCalledWith('/test/project', null, 3);
+    });
+
+    it('resets stuck features on start', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+
+      expect(mockResetStuckFeatures).toHaveBeenCalledWith('/test/project');
+    });
+
+    it('uses settings maxConcurrency when not provided', async () => {
+      const result = await coordinator.startAutoLoopForProject('/test/project', null);
+
+      expect(result).toBe(3); // from mockSettingsService
+    });
+
+    it('uses worktree-specific maxConcurrency from settings', async () => {
+      vi.mocked(mockSettingsService!.getGlobalSettings).mockResolvedValue({
+        maxConcurrency: 5,
+        projects: [{ id: 'proj-1', path: '/test/project' }],
+        autoModeByWorktree: {
+          'proj-1::__main__': { maxConcurrency: 7 },
+        },
+      });
+
+      const result = await coordinator.startAutoLoopForProject('/test/project', null);
+
+      expect(result).toBe(7);
+    });
+  });
+
+  describe('stopAutoLoopForProject', () => {
+    it('aborts running loop', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+
+      const result = await coordinator.stopAutoLoopForProject('/test/project', null);
+
+      expect(result).toBe(0);
+      expect(coordinator.isAutoLoopRunningForProject('/test/project', null)).toBe(false);
+    });
+
+    it('emits auto_mode_stopped event', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+      vi.mocked(mockEventBus.emitAutoModeEvent).mockClear();
+
+      await coordinator.stopAutoLoopForProject('/test/project', null);
+
+      expect(mockEventBus.emitAutoModeEvent).toHaveBeenCalledWith('auto_mode_stopped', {
+        message: 'Auto mode stopped',
+        projectPath: '/test/project',
+        branchName: null,
+      });
+    });
+
+    it('calls clearExecutionState', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+
+      await coordinator.stopAutoLoopForProject('/test/project', null);
+
+      expect(mockClearExecutionState).toHaveBeenCalledWith('/test/project', null);
+    });
+
+    it('returns 0 when no loop running', async () => {
+      const result = await coordinator.stopAutoLoopForProject('/test/project', null);
+
+      expect(result).toBe(0);
+      expect(mockClearExecutionState).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('isAutoLoopRunningForProject', () => {
+    it('returns true when running', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+
+      expect(coordinator.isAutoLoopRunningForProject('/test/project', null)).toBe(true);
+    });
+
+    it('returns false when not running', () => {
+      expect(coordinator.isAutoLoopRunningForProject('/test/project', null)).toBe(false);
+    });
+
+    it('returns false for different worktree', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', 'branch-a', 1);
+
+      expect(coordinator.isAutoLoopRunningForProject('/test/project', 'branch-b')).toBe(false);
+    });
+  });
+
+  describe('runAutoLoopForProject', () => {
+    it('loads pending features each iteration', async () => {
+      vi.mocked(mockLoadPendingFeatures).mockResolvedValue([]);
+
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+
+      // Advance time to trigger loop iterations
+      await vi.advanceTimersByTimeAsync(11000);
+
+      // Stop the loop to avoid hanging
+      await coordinator.stopAutoLoopForProject('/test/project', null);
+
+      expect(mockLoadPendingFeatures).toHaveBeenCalled();
+    });
+
+    it('executes features within concurrency limit', async () => {
+      vi.mocked(mockLoadPendingFeatures).mockResolvedValue([testFeature]);
+      vi.mocked(mockConcurrencyManager.getRunningCountForWorktree).mockResolvedValue(0);
+
+      await coordinator.startAutoLoopForProject('/test/project', null, 2);
+
+      // Advance time to trigger loop iteration
+      await vi.advanceTimersByTimeAsync(3000);
+
+      // Stop the loop
+      await coordinator.stopAutoLoopForProject('/test/project', null);
+
+      expect(mockExecuteFeature).toHaveBeenCalledWith('/test/project', 'feature-1', true, true);
+    });
+
+    it('emits idle event when no work remains (running=0, pending=0)', async () => {
+      vi.mocked(mockLoadPendingFeatures).mockResolvedValue([]);
+      vi.mocked(mockConcurrencyManager.getRunningCountForWorktree).mockResolvedValue(0);
+
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+
+      // Clear the initial event mock calls
+      vi.mocked(mockEventBus.emitAutoModeEvent).mockClear();
+
+      // Advance time to trigger loop iteration and idle event
+      await vi.advanceTimersByTimeAsync(11000);
+
+      // Stop the loop
+      await coordinator.stopAutoLoopForProject('/test/project', null);
+
+      expect(mockEventBus.emitAutoModeEvent).toHaveBeenCalledWith('auto_mode_idle', {
+        message: 'No pending features - auto mode idle',
+        projectPath: '/test/project',
+        branchName: null,
+      });
+    });
+
+    it('skips already-running features', async () => {
+      const feature2: Feature = { ...testFeature, id: 'feature-2' };
+      vi.mocked(mockLoadPendingFeatures).mockResolvedValue([testFeature, feature2]);
+      vi.mocked(mockIsFeatureRunning)
+        .mockReturnValueOnce(true) // feature-1 is running
+        .mockReturnValueOnce(false); // feature-2 is not running
+
+      await coordinator.startAutoLoopForProject('/test/project', null, 2);
+
+      await vi.advanceTimersByTimeAsync(3000);
+
+      await coordinator.stopAutoLoopForProject('/test/project', null);
+
+      // Should execute feature-2, not feature-1
+      expect(mockExecuteFeature).toHaveBeenCalledWith('/test/project', 'feature-2', true, true);
+    });
+
+    it('stops when aborted', async () => {
+      vi.mocked(mockLoadPendingFeatures).mockResolvedValue([testFeature]);
+
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+
+      // Stop immediately
+      await coordinator.stopAutoLoopForProject('/test/project', null);
+
+      // Should not have executed many features
+      expect(mockExecuteFeature.mock.calls.length).toBeLessThanOrEqual(1);
+    });
+
+    it('waits when at capacity', async () => {
+      vi.mocked(mockLoadPendingFeatures).mockResolvedValue([testFeature]);
+      vi.mocked(mockConcurrencyManager.getRunningCountForWorktree).mockResolvedValue(2); // At capacity for maxConcurrency=2
+
+      await coordinator.startAutoLoopForProject('/test/project', null, 2);
+
+      await vi.advanceTimersByTimeAsync(6000);
+
+      await coordinator.stopAutoLoopForProject('/test/project', null);
+
+      // Should not have executed features because at capacity
+      expect(mockExecuteFeature).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('failure tracking', () => {
+    it('trackFailureAndCheckPauseForProject returns true after threshold', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+
+      // Track 3 failures (threshold)
+      const result1 = coordinator.trackFailureAndCheckPauseForProject('/test/project', {
+        type: 'agent_error',
+        message: 'Error 1',
+      });
+      expect(result1).toBe(false);
+
+      const result2 = coordinator.trackFailureAndCheckPauseForProject('/test/project', {
+        type: 'agent_error',
+        message: 'Error 2',
+      });
+      expect(result2).toBe(false);
+
+      const result3 = coordinator.trackFailureAndCheckPauseForProject('/test/project', {
+        type: 'agent_error',
+        message: 'Error 3',
+      });
+      expect(result3).toBe(true); // Should pause after 3
+
+      await coordinator.stopAutoLoopForProject('/test/project', null);
+    });
+
+    it('agent errors count as failures', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+
+      const result = coordinator.trackFailureAndCheckPauseForProject('/test/project', {
+        type: 'agent_error',
+        message: 'Agent failed',
+      });
+
+      // First error should not pause
+      expect(result).toBe(false);
+
+      await coordinator.stopAutoLoopForProject('/test/project', null);
+    });
+
+    it('clears failures on success (recordSuccessForProject)', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+
+      // Add 2 failures
+      coordinator.trackFailureAndCheckPauseForProject('/test/project', {
+        type: 'agent_error',
+        message: 'Error 1',
+      });
+      coordinator.trackFailureAndCheckPauseForProject('/test/project', {
+        type: 'agent_error',
+        message: 'Error 2',
+      });
+
+      // Record success - should clear failures
+      coordinator.recordSuccessForProject('/test/project');
+
+      // Next failure should return false (not hitting threshold)
+      const result = coordinator.trackFailureAndCheckPauseForProject('/test/project', {
+        type: 'agent_error',
+        message: 'Error 3',
+      });
+      expect(result).toBe(false);
+
+      await coordinator.stopAutoLoopForProject('/test/project', null);
+    });
+
+    it('signalShouldPauseForProject emits event and stops loop', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+      vi.mocked(mockEventBus.emitAutoModeEvent).mockClear();
+
+      coordinator.signalShouldPauseForProject('/test/project', {
+        type: 'quota_exhausted',
+        message: 'Rate limited',
+      });
+
+      expect(mockEventBus.emitAutoModeEvent).toHaveBeenCalledWith(
+        'auto_mode_paused_failures',
+        expect.objectContaining({
+          errorType: 'quota_exhausted',
+          projectPath: '/test/project',
+        })
+      );
+
+      // Loop should be stopped
+      expect(coordinator.isAutoLoopRunningForProject('/test/project', null)).toBe(false);
+    });
+
+    it('quota/rate limit errors pause immediately', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+
+      const result = coordinator.trackFailureAndCheckPauseForProject('/test/project', {
+        type: 'quota_exhausted',
+        message: 'API quota exceeded',
+      });
+
+      expect(result).toBe(true); // Should pause immediately
+
+      await coordinator.stopAutoLoopForProject('/test/project', null);
+    });
+
+    it('rate_limit type also pauses immediately', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+
+      const result = coordinator.trackFailureAndCheckPauseForProject('/test/project', {
+        type: 'rate_limit',
+        message: 'Rate limited',
+      });
+
+      expect(result).toBe(true);
+
+      await coordinator.stopAutoLoopForProject('/test/project', null);
+    });
+  });
+
+  describe('multiple projects', () => {
+    it('runs concurrent loops for different projects', async () => {
+      await coordinator.startAutoLoopForProject('/project-a', null, 1);
+      await coordinator.startAutoLoopForProject('/project-b', null, 1);
+
+      expect(coordinator.isAutoLoopRunningForProject('/project-a', null)).toBe(true);
+      expect(coordinator.isAutoLoopRunningForProject('/project-b', null)).toBe(true);
+
+      await coordinator.stopAutoLoopForProject('/project-a', null);
+      await coordinator.stopAutoLoopForProject('/project-b', null);
+    });
+
+    it('runs concurrent loops for different worktrees of same project', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+      await coordinator.startAutoLoopForProject('/test/project', 'feature-branch', 1);
+
+      expect(coordinator.isAutoLoopRunningForProject('/test/project', null)).toBe(true);
+      expect(coordinator.isAutoLoopRunningForProject('/test/project', 'feature-branch')).toBe(true);
+
+      await coordinator.stopAutoLoopForProject('/test/project', null);
+      await coordinator.stopAutoLoopForProject('/test/project', 'feature-branch');
+    });
+
+    it('stopping one loop does not affect others', async () => {
+      await coordinator.startAutoLoopForProject('/project-a', null, 1);
+      await coordinator.startAutoLoopForProject('/project-b', null, 1);
+
+      await coordinator.stopAutoLoopForProject('/project-a', null);
+
+      expect(coordinator.isAutoLoopRunningForProject('/project-a', null)).toBe(false);
+      expect(coordinator.isAutoLoopRunningForProject('/project-b', null)).toBe(true);
+
+      await coordinator.stopAutoLoopForProject('/project-b', null);
+    });
+  });
+
+  describe('getAutoLoopConfigForProject', () => {
+    it('returns config when loop is running', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', null, 5);
+
+      const config = coordinator.getAutoLoopConfigForProject('/test/project', null);
+
+      expect(config).toEqual({
+        maxConcurrency: 5,
+        useWorktrees: true,
+        projectPath: '/test/project',
+        branchName: null,
+      });
+
+      await coordinator.stopAutoLoopForProject('/test/project', null);
+    });
+
+    it('returns null when no loop running', () => {
+      const config = coordinator.getAutoLoopConfigForProject('/test/project', null);
+
+      expect(config).toBeNull();
+    });
+  });
+
+  describe('getRunningCountForWorktree', () => {
+    it('delegates to ConcurrencyManager', async () => {
+      vi.mocked(mockConcurrencyManager.getRunningCountForWorktree).mockResolvedValue(3);
+
+      const count = await coordinator.getRunningCountForWorktree('/test/project', null);
+
+      expect(count).toBe(3);
+      expect(mockConcurrencyManager.getRunningCountForWorktree).toHaveBeenCalledWith(
+        '/test/project',
+        null
+      );
+    });
+  });
+
+  describe('resetFailureTrackingForProject', () => {
+    it('clears consecutive failures and paused flag', async () => {
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+
+      // Add failures
+      coordinator.trackFailureAndCheckPauseForProject('/test/project', {
+        type: 'agent_error',
+        message: 'Error',
+      });
+      coordinator.trackFailureAndCheckPauseForProject('/test/project', {
+        type: 'agent_error',
+        message: 'Error',
+      });
+
+      // Reset failure tracking
+      coordinator.resetFailureTrackingForProject('/test/project');
+
+      // Next 3 failures should be needed to trigger pause again
+      const result1 = coordinator.trackFailureAndCheckPauseForProject('/test/project', {
+        type: 'agent_error',
+        message: 'Error',
+      });
+      expect(result1).toBe(false);
+
+      await coordinator.stopAutoLoopForProject('/test/project', null);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('handles null settingsService gracefully', async () => {
+      const coordWithoutSettings = new AutoLoopCoordinator(
+        mockEventBus,
+        mockConcurrencyManager,
+        null, // No settings service
+        mockExecuteFeature,
+        mockLoadPendingFeatures,
+        mockSaveExecutionState,
+        mockClearExecutionState,
+        mockResetStuckFeatures,
+        mockIsFeatureFinished,
+        mockIsFeatureRunning
+      );
+
+      // Should use default concurrency
+      const result = await coordWithoutSettings.startAutoLoopForProject('/test/project', null);
+
+      expect(result).toBe(1); // DEFAULT_MAX_CONCURRENCY
+
+      await coordWithoutSettings.stopAutoLoopForProject('/test/project', null);
+    });
+
+    it('handles resetStuckFeatures error gracefully', async () => {
+      vi.mocked(mockResetStuckFeatures).mockRejectedValue(new Error('Reset failed'));
+
+      // Should not throw
+      await coordinator.startAutoLoopForProject('/test/project', null, 1);
+
+      expect(mockResetStuckFeatures).toHaveBeenCalled();
+
+      await coordinator.stopAutoLoopForProject('/test/project', null);
+    });
+
+    it('trackFailureAndCheckPauseForProject returns false when no loop', () => {
+      const result = coordinator.trackFailureAndCheckPauseForProject('/nonexistent', {
+        type: 'agent_error',
+        message: 'Error',
+      });
+
+      expect(result).toBe(false);
+    });
+
+    it('signalShouldPauseForProject does nothing when no loop', () => {
+      // Should not throw
+      coordinator.signalShouldPauseForProject('/nonexistent', {
+        type: 'quota_exhausted',
+        message: 'Error',
+      });
+
+      expect(mockEventBus.emitAutoModeEvent).not.toHaveBeenCalledWith(
+        'auto_mode_paused_failures',
+        expect.anything()
+      );
+    });
+
+    it('does not emit stopped event when loop was not running', async () => {
+      const result = await coordinator.stopAutoLoopForProject('/test/project', null);
+
+      expect(result).toBe(0);
+      expect(mockEventBus.emitAutoModeEvent).not.toHaveBeenCalledWith(
+        'auto_mode_stopped',
+        expect.anything()
+      );
+    });
+  });
+});

apps/server/tests/unit/services/auto-mode-service-planning.test.ts

@@ -1,346 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { AutoModeService } from '@/services/auto-mode-service.js';
-
-describe('auto-mode-service.ts - Planning Mode', () => {
-  let service: AutoModeService;
-  const mockEvents = {
-    subscribe: vi.fn(),
-    emit: vi.fn(),
-  };
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    service = new AutoModeService(mockEvents as any);
-  });
-
-  afterEach(async () => {
-    // Clean up any running processes
-    await service.stopAutoLoop().catch(() => {});
-  });
-
-  describe('getPlanningPromptPrefix', () => {
-    // Access private method through any cast for testing
-    const getPlanningPromptPrefix = (svc: any, feature: any) => {
-      return svc.getPlanningPromptPrefix(feature);
-    };
-
-    it('should return empty string for skip mode', async () => {
-      const feature = { id: 'test', planningMode: 'skip' as const };
-      const result = await getPlanningPromptPrefix(service, feature);
-      expect(result).toBe('');
-    });
-
-    it('should return empty string when planningMode is undefined', async () => {
-      const feature = { id: 'test' };
-      const result = await getPlanningPromptPrefix(service, feature);
-      expect(result).toBe('');
-    });
-
-    it('should return lite prompt for lite mode without approval', async () => {
-      const feature = {
-        id: 'test',
-        planningMode: 'lite' as const,
-        requirePlanApproval: false,
-      };
-      const result = await getPlanningPromptPrefix(service, feature);
-      expect(result).toContain('Planning Phase (Lite Mode)');
-      expect(result).toContain('[PLAN_GENERATED]');
-      expect(result).toContain('Feature Request');
-    });
-
-    it('should return lite_with_approval prompt for lite mode with approval', async () => {
-      const feature = {
-        id: 'test',
-        planningMode: 'lite' as const,
-        requirePlanApproval: true,
-      };
-      const result = await getPlanningPromptPrefix(service, feature);
-      expect(result).toContain('## Planning Phase (Lite Mode)');
-      expect(result).toContain('[SPEC_GENERATED]');
-      expect(result).toContain(
-        'DO NOT proceed with implementation until you receive explicit approval'
-      );
-    });
-
-    it('should return spec prompt for spec mode', async () => {
-      const feature = {
-        id: 'test',
-        planningMode: 'spec' as const,
-      };
-      const result = await getPlanningPromptPrefix(service, feature);
-      expect(result).toContain('## Specification Phase (Spec Mode)');
-      expect(result).toContain('```tasks');
-      expect(result).toContain('T001');
-      expect(result).toContain('[TASK_START]');
-      expect(result).toContain('[TASK_COMPLETE]');
-    });
-
-    it('should return full prompt for full mode', async () => {
-      const feature = {
-        id: 'test',
-        planningMode: 'full' as const,
-      };
-      const result = await getPlanningPromptPrefix(service, feature);
-      expect(result).toContain('## Full Specification Phase (Full SDD Mode)');
-      expect(result).toContain('Phase 1: Foundation');
-      expect(result).toContain('Phase 2: Core Implementation');
-      expect(result).toContain('Phase 3: Integration & Testing');
-    });
-
-    it('should include the separator and Feature Request header', async () => {
-      const feature = {
-        id: 'test',
-        planningMode: 'spec' as const,
-      };
-      const result = await getPlanningPromptPrefix(service, feature);
-      expect(result).toContain('---');
-      expect(result).toContain('## Feature Request');
-    });
-
-    it('should instruct agent to NOT output exploration text', async () => {
-      const modes = ['lite', 'spec', 'full'] as const;
-      for (const mode of modes) {
-        const feature = { id: 'test', planningMode: mode };
-        const result = await getPlanningPromptPrefix(service, feature);
-        // All modes should have the IMPORTANT instruction about not outputting exploration text
-        expect(result).toContain('IMPORTANT: Do NOT output exploration text');
-        expect(result).toContain('Silently analyze the codebase first');
-      }
-    });
-  });
-
-  describe('parseTasksFromSpec (via module)', () => {
-    // We need to test the module-level function
-    // Import it directly for testing
-    it('should parse tasks from a valid tasks block', async () => {
-      // This tests the internal logic through integration
-      // The function is module-level, so we verify behavior through the service
-      const specContent = `
-## Specification
-
-\`\`\`tasks
-- [ ] T001: Create user model | File: src/models/user.ts
-- [ ] T002: Add API endpoint | File: src/routes/users.ts
-- [ ] T003: Write unit tests | File: tests/user.test.ts
-\`\`\`
-`;
-      // Since parseTasksFromSpec is a module-level function,
-      // we verify its behavior indirectly through plan parsing
-      expect(specContent).toContain('T001');
-      expect(specContent).toContain('T002');
-      expect(specContent).toContain('T003');
-    });
-
-    it('should handle tasks block with phases', () => {
-      const specContent = `
-\`\`\`tasks
-## Phase 1: Setup
-- [ ] T001: Initialize project | File: package.json
-- [ ] T002: Configure TypeScript | File: tsconfig.json
-
-## Phase 2: Implementation
-- [ ] T003: Create main module | File: src/index.ts
-\`\`\`
-`;
-      expect(specContent).toContain('Phase 1');
-      expect(specContent).toContain('Phase 2');
-      expect(specContent).toContain('T001');
-      expect(specContent).toContain('T003');
-    });
-  });
-
-  describe('plan approval flow', () => {
-    it('should track pending approvals correctly', () => {
-      expect(service.hasPendingApproval('test-feature')).toBe(false);
-    });
-
-    it('should allow cancelling non-existent approval without error', () => {
-      expect(() => service.cancelPlanApproval('non-existent')).not.toThrow();
-    });
-
-    it('should return running features count after stop', async () => {
-      const count = await service.stopAutoLoop();
-      expect(count).toBe(0);
-    });
-  });
-
-  describe('resolvePlanApproval', () => {
-    it('should return error when no pending approval exists', async () => {
-      const result = await service.resolvePlanApproval(
-        'non-existent-feature',
-        true,
-        undefined,
-        undefined,
-        undefined
-      );
-      expect(result.success).toBe(false);
-      expect(result.error).toContain('No pending approval');
-    });
-
-    it('should handle approval with edited plan', async () => {
-      // Without a pending approval, this should fail gracefully
-      const result = await service.resolvePlanApproval(
-        'test-feature',
-        true,
-        'Edited plan content',
-        undefined,
-        undefined
-      );
-      expect(result.success).toBe(false);
-    });
-
-    it('should handle rejection with feedback', async () => {
-      const result = await service.resolvePlanApproval(
-        'test-feature',
-        false,
-        undefined,
-        'Please add more details',
-        undefined
-      );
-      expect(result.success).toBe(false);
-    });
-  });
-
-  describe('buildFeaturePrompt', () => {
-    const defaultTaskExecutionPrompts = {
-      implementationInstructions: 'Test implementation instructions',
-      playwrightVerificationInstructions: 'Test playwright instructions',
-    };
-
-    const buildFeaturePrompt = (
-      svc: any,
-      feature: any,
-      taskExecutionPrompts = defaultTaskExecutionPrompts
-    ) => {
-      return svc.buildFeaturePrompt(feature, taskExecutionPrompts);
-    };
-
-    it('should include feature ID and description', () => {
-      const feature = {
-        id: 'feat-123',
-        description: 'Add user authentication',
-      };
-      const result = buildFeaturePrompt(service, feature);
-      expect(result).toContain('feat-123');
-      expect(result).toContain('Add user authentication');
-    });
-
-    it('should include specification when present', () => {
-      const feature = {
-        id: 'feat-123',
-        description: 'Test feature',
-        spec: 'Detailed specification here',
-      };
-      const result = buildFeaturePrompt(service, feature);
-      expect(result).toContain('Specification:');
-      expect(result).toContain('Detailed specification here');
-    });
-
-    it('should include image paths when present', () => {
-      const feature = {
-        id: 'feat-123',
-        description: 'Test feature',
-        imagePaths: [
-          { path: '/tmp/image1.png', filename: 'image1.png', mimeType: 'image/png' },
-          '/tmp/image2.jpg',
-        ],
-      };
-      const result = buildFeaturePrompt(service, feature);
-      expect(result).toContain('Context Images Attached');
-      expect(result).toContain('image1.png');
-      expect(result).toContain('/tmp/image2.jpg');
-    });
-
-    it('should include implementation instructions', () => {
-      const feature = {
-        id: 'feat-123',
-        description: 'Test feature',
-      };
-      const result = buildFeaturePrompt(service, feature);
-      // The prompt should include the implementation instructions passed to it
-      expect(result).toContain('Test implementation instructions');
-      expect(result).toContain('Test playwright instructions');
-    });
-  });
-
-  describe('extractTitleFromDescription', () => {
-    const extractTitle = (svc: any, description: string) => {
-      return svc.extractTitleFromDescription(description);
-    };
-
-    it("should return 'Untitled Feature' for empty description", () => {
-      expect(extractTitle(service, '')).toBe('Untitled Feature');
-      expect(extractTitle(service, '   ')).toBe('Untitled Feature');
-    });
-
-    it('should return first line if under 60 characters', () => {
-      const description = 'Add user login\nWith email validation';
-      expect(extractTitle(service, description)).toBe('Add user login');
-    });
-
-    it('should truncate long first lines to 60 characters', () => {
-      const description =
-        'This is a very long feature description that exceeds the sixty character limit significantly';
-      const result = extractTitle(service, description);
-      expect(result.length).toBe(60);
-      expect(result).toContain('...');
-    });
-  });
-
-  describe('PLANNING_PROMPTS structure', () => {
-    const getPlanningPromptPrefix = (svc: any, feature: any) => {
-      return svc.getPlanningPromptPrefix(feature);
-    };
-
-    it('should have all required planning modes', async () => {
-      const modes = ['lite', 'spec', 'full'] as const;
-      for (const mode of modes) {
-        const feature = { id: 'test', planningMode: mode };
-        const result = await getPlanningPromptPrefix(service, feature);
-        expect(result.length).toBeGreaterThan(100);
-      }
-    });
-
-    it('lite prompt should include correct structure', async () => {
-      const feature = { id: 'test', planningMode: 'lite' as const };
-      const result = await getPlanningPromptPrefix(service, feature);
-      expect(result).toContain('Goal');
-      expect(result).toContain('Approach');
-      expect(result).toContain('Files to Touch');
-      expect(result).toContain('Tasks');
-      expect(result).toContain('Risks');
-    });
-
-    it('spec prompt should include task format instructions', async () => {
-      const feature = { id: 'test', planningMode: 'spec' as const };
-      const result = await getPlanningPromptPrefix(service, feature);
-      expect(result).toContain('Problem');
-      expect(result).toContain('Solution');
-      expect(result).toContain('Acceptance Criteria');
-      expect(result).toContain('GIVEN-WHEN-THEN');
-      expect(result).toContain('Implementation Tasks');
-      expect(result).toContain('Verification');
-    });
-
-    it('full prompt should include phases', async () => {
-      const feature = { id: 'test', planningMode: 'full' as const };
-      const result = await getPlanningPromptPrefix(service, feature);
-      expect(result).toContain('1. **Problem Statement**');
-      expect(result).toContain('2. **User Story**');
-      expect(result).toContain('4. **Technical Context**');
-      expect(result).toContain('5. **Non-Goals**');
-      expect(result).toContain('Phase 1');
-      expect(result).toContain('Phase 2');
-      expect(result).toContain('Phase 3');
-    });
-  });
-
-  describe('status management', () => {
-    it('should report correct status', () => {
-      const status = service.getStatus();
-      expect(status.runningFeatures).toEqual([]);
-      expect(status.isRunning).toBe(false);
-      expect(status.runningCount).toBe(0);
-    });
-  });
-});

apps/server/tests/unit/services/auto-mode-service.test.ts

@@ -1,845 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { AutoModeService } from '@/services/auto-mode-service.js';
-import type { Feature } from '@automaker/types';
-
-describe('auto-mode-service.ts', () => {
-  let service: AutoModeService;
-  const mockEvents = {
-    subscribe: vi.fn(),
-    emit: vi.fn(),
-  };
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    service = new AutoModeService(mockEvents as any);
-  });
-
-  describe('constructor', () => {
-    it('should initialize with event emitter', () => {
-      expect(service).toBeDefined();
-    });
-  });
-
-  describe('startAutoLoop', () => {
-    it('should throw if auto mode is already running', async () => {
-      // Start first loop
-      const promise1 = service.startAutoLoop('/test/project', 3);
-
-      // Try to start second loop
-      await expect(service.startAutoLoop('/test/project', 3)).rejects.toThrow('already running');
-
-      // Cleanup
-      await service.stopAutoLoop();
-      await promise1.catch(() => {});
-    });
-
-    it('should emit auto mode start event', async () => {
-      const promise = service.startAutoLoop('/test/project', 3);
-
-      // Give it time to emit the event
-      await new Promise((resolve) => setTimeout(resolve, 10));
-
-      expect(mockEvents.emit).toHaveBeenCalledWith(
-        expect.any(String),
-        expect.objectContaining({
-          message: expect.stringContaining('Auto mode started'),
-        })
-      );
-
-      // Cleanup
-      await service.stopAutoLoop();
-      await promise.catch(() => {});
-    });
-  });
-
-  describe('stopAutoLoop', () => {
-    it('should stop the auto loop', async () => {
-      const promise = service.startAutoLoop('/test/project', 3);
-
-      const runningCount = await service.stopAutoLoop();
-
-      expect(runningCount).toBe(0);
-      await promise.catch(() => {});
-    });
-
-    it('should return 0 when not running', async () => {
-      const runningCount = await service.stopAutoLoop();
-      expect(runningCount).toBe(0);
-    });
-  });
-
-  describe('getRunningAgents', () => {
-    // Helper to access private runningFeatures Map
-    const getRunningFeaturesMap = (svc: AutoModeService) =>
-      (svc as any).runningFeatures as Map<
-        string,
-        { featureId: string; projectPath: string; isAutoMode: boolean }
-      >;
-
-    // Helper to get the featureLoader and mock its get method
-    const mockFeatureLoaderGet = (svc: AutoModeService, mockFn: ReturnType<typeof vi.fn>) => {
-      (svc as any).featureLoader = { get: mockFn };
-    };
-
-    it('should return empty array when no agents are running', async () => {
-      const result = await service.getRunningAgents();
-
-      expect(result).toEqual([]);
-    });
-
-    it('should return running agents with basic info when feature data is not available', async () => {
-      // Arrange: Add a running feature to the Map
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      runningFeaturesMap.set('feature-123', {
-        featureId: 'feature-123',
-        projectPath: '/test/project/path',
-        isAutoMode: true,
-      });
-
-      // Mock featureLoader.get to return null (feature not found)
-      const getMock = vi.fn().mockResolvedValue(null);
-      mockFeatureLoaderGet(service, getMock);
-
-      // Act
-      const result = await service.getRunningAgents();
-
-      // Assert
-      expect(result).toHaveLength(1);
-      expect(result[0]).toEqual({
-        featureId: 'feature-123',
-        projectPath: '/test/project/path',
-        projectName: 'path',
-        isAutoMode: true,
-        title: undefined,
-        description: undefined,
-      });
-    });
-
-    it('should return running agents with title and description when feature data is available', async () => {
-      // Arrange
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      runningFeaturesMap.set('feature-456', {
-        featureId: 'feature-456',
-        projectPath: '/home/user/my-project',
-        isAutoMode: false,
-      });
-
-      const mockFeature: Partial<Feature> = {
-        id: 'feature-456',
-        title: 'Implement user authentication',
-        description: 'Add login and signup functionality',
-        category: 'auth',
-      };
-
-      const getMock = vi.fn().mockResolvedValue(mockFeature);
-      mockFeatureLoaderGet(service, getMock);
-
-      // Act
-      const result = await service.getRunningAgents();
-
-      // Assert
-      expect(result).toHaveLength(1);
-      expect(result[0]).toEqual({
-        featureId: 'feature-456',
-        projectPath: '/home/user/my-project',
-        projectName: 'my-project',
-        isAutoMode: false,
-        title: 'Implement user authentication',
-        description: 'Add login and signup functionality',
-      });
-      expect(getMock).toHaveBeenCalledWith('/home/user/my-project', 'feature-456');
-    });
-
-    it('should handle multiple running agents', async () => {
-      // Arrange
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      runningFeaturesMap.set('feature-1', {
-        featureId: 'feature-1',
-        projectPath: '/project-a',
-        isAutoMode: true,
-      });
-      runningFeaturesMap.set('feature-2', {
-        featureId: 'feature-2',
-        projectPath: '/project-b',
-        isAutoMode: false,
-      });
-
-      const getMock = vi
-        .fn()
-        .mockResolvedValueOnce({
-          id: 'feature-1',
-          title: 'Feature One',
-          description: 'Description one',
-        })
-        .mockResolvedValueOnce({
-          id: 'feature-2',
-          title: 'Feature Two',
-          description: 'Description two',
-        });
-      mockFeatureLoaderGet(service, getMock);
-
-      // Act
-      const result = await service.getRunningAgents();
-
-      // Assert
-      expect(result).toHaveLength(2);
-      expect(getMock).toHaveBeenCalledTimes(2);
-    });
-
-    it('should silently handle errors when fetching feature data', async () => {
-      // Arrange
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      runningFeaturesMap.set('feature-error', {
-        featureId: 'feature-error',
-        projectPath: '/project-error',
-        isAutoMode: true,
-      });
-
-      const getMock = vi.fn().mockRejectedValue(new Error('Database connection failed'));
-      mockFeatureLoaderGet(service, getMock);
-
-      // Act - should not throw
-      const result = await service.getRunningAgents();
-
-      // Assert
-      expect(result).toHaveLength(1);
-      expect(result[0]).toEqual({
-        featureId: 'feature-error',
-        projectPath: '/project-error',
-        projectName: 'project-error',
-        isAutoMode: true,
-        title: undefined,
-        description: undefined,
-      });
-    });
-
-    it('should handle feature with title but no description', async () => {
-      // Arrange
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      runningFeaturesMap.set('feature-title-only', {
-        featureId: 'feature-title-only',
-        projectPath: '/project',
-        isAutoMode: false,
-      });
-
-      const getMock = vi.fn().mockResolvedValue({
-        id: 'feature-title-only',
-        title: 'Only Title',
-        // description is undefined
-      });
-      mockFeatureLoaderGet(service, getMock);
-
-      // Act
-      const result = await service.getRunningAgents();
-
-      // Assert
-      expect(result[0].title).toBe('Only Title');
-      expect(result[0].description).toBeUndefined();
-    });
-
-    it('should handle feature with description but no title', async () => {
-      // Arrange
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      runningFeaturesMap.set('feature-desc-only', {
-        featureId: 'feature-desc-only',
-        projectPath: '/project',
-        isAutoMode: false,
-      });
-
-      const getMock = vi.fn().mockResolvedValue({
-        id: 'feature-desc-only',
-        description: 'Only description, no title',
-        // title is undefined
-      });
-      mockFeatureLoaderGet(service, getMock);
-
-      // Act
-      const result = await service.getRunningAgents();
-
-      // Assert
-      expect(result[0].title).toBeUndefined();
-      expect(result[0].description).toBe('Only description, no title');
-    });
-
-    it('should extract projectName from nested paths correctly', async () => {
-      // Arrange
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      runningFeaturesMap.set('feature-nested', {
-        featureId: 'feature-nested',
-        projectPath: '/home/user/workspace/projects/my-awesome-project',
-        isAutoMode: true,
-      });
-
-      const getMock = vi.fn().mockResolvedValue(null);
-      mockFeatureLoaderGet(service, getMock);
-
-      // Act
-      const result = await service.getRunningAgents();
-
-      // Assert
-      expect(result[0].projectName).toBe('my-awesome-project');
-    });
-
-    it('should fetch feature data in parallel for multiple agents', async () => {
-      // Arrange: Add multiple running features
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      for (let i = 1; i <= 5; i++) {
-        runningFeaturesMap.set(`feature-${i}`, {
-          featureId: `feature-${i}`,
-          projectPath: `/project-${i}`,
-          isAutoMode: i % 2 === 0,
-        });
-      }
-
-      // Track call order
-      const callOrder: string[] = [];
-      const getMock = vi.fn().mockImplementation(async (projectPath: string, featureId: string) => {
-        callOrder.push(featureId);
-        // Simulate async delay to verify parallel execution
-        await new Promise((resolve) => setTimeout(resolve, 10));
-        return { id: featureId, title: `Title for ${featureId}` };
-      });
-      mockFeatureLoaderGet(service, getMock);
-
-      // Act
-      const startTime = Date.now();
-      const result = await service.getRunningAgents();
-      const duration = Date.now() - startTime;
-
-      // Assert
-      expect(result).toHaveLength(5);
-      expect(getMock).toHaveBeenCalledTimes(5);
-      // If executed in parallel, total time should be ~10ms (one batch)
-      // If sequential, it would be ~50ms (5 * 10ms)
-      // Allow some buffer for execution overhead
-      expect(duration).toBeLessThan(40);
-    });
-  });
-
-  describe('detectOrphanedFeatures', () => {
-    // Helper to mock featureLoader.getAll
-    const mockFeatureLoaderGetAll = (svc: AutoModeService, mockFn: ReturnType<typeof vi.fn>) => {
-      (svc as any).featureLoader = { getAll: mockFn };
-    };
-
-    // Helper to mock getExistingBranches
-    const mockGetExistingBranches = (svc: AutoModeService, branches: string[]) => {
-      (svc as any).getExistingBranches = vi.fn().mockResolvedValue(new Set(branches));
-    };
-
-    it('should return empty array when no features have branch names', async () => {
-      const getAllMock = vi.fn().mockResolvedValue([
-        { id: 'f1', title: 'Feature 1', description: 'desc', category: 'test' },
-        { id: 'f2', title: 'Feature 2', description: 'desc', category: 'test' },
-      ] satisfies Feature[]);
-      mockFeatureLoaderGetAll(service, getAllMock);
-      mockGetExistingBranches(service, ['main', 'develop']);
-
-      const result = await service.detectOrphanedFeatures('/test/project');
-
-      expect(result).toEqual([]);
-    });
-
-    it('should return empty array when all feature branches exist', async () => {
-      const getAllMock = vi.fn().mockResolvedValue([
-        {
-          id: 'f1',
-          title: 'Feature 1',
-          description: 'desc',
-          category: 'test',
-          branchName: 'feature-1',
-        },
-        {
-          id: 'f2',
-          title: 'Feature 2',
-          description: 'desc',
-          category: 'test',
-          branchName: 'feature-2',
-        },
-      ] satisfies Feature[]);
-      mockFeatureLoaderGetAll(service, getAllMock);
-      mockGetExistingBranches(service, ['main', 'feature-1', 'feature-2']);
-
-      const result = await service.detectOrphanedFeatures('/test/project');
-
-      expect(result).toEqual([]);
-    });
-
-    it('should detect orphaned features with missing branches', async () => {
-      const features: Feature[] = [
-        {
-          id: 'f1',
-          title: 'Feature 1',
-          description: 'desc',
-          category: 'test',
-          branchName: 'feature-1',
-        },
-        {
-          id: 'f2',
-          title: 'Feature 2',
-          description: 'desc',
-          category: 'test',
-          branchName: 'deleted-branch',
-        },
-        { id: 'f3', title: 'Feature 3', description: 'desc', category: 'test' }, // No branch
-      ];
-      const getAllMock = vi.fn().mockResolvedValue(features);
-      mockFeatureLoaderGetAll(service, getAllMock);
-      mockGetExistingBranches(service, ['main', 'feature-1']); // deleted-branch not in list
-
-      const result = await service.detectOrphanedFeatures('/test/project');
-
-      expect(result).toHaveLength(1);
-      expect(result[0].feature.id).toBe('f2');
-      expect(result[0].missingBranch).toBe('deleted-branch');
-    });
-
-    it('should detect multiple orphaned features', async () => {
-      const features: Feature[] = [
-        {
-          id: 'f1',
-          title: 'Feature 1',
-          description: 'desc',
-          category: 'test',
-          branchName: 'orphan-1',
-        },
-        {
-          id: 'f2',
-          title: 'Feature 2',
-          description: 'desc',
-          category: 'test',
-          branchName: 'orphan-2',
-        },
-        {
-          id: 'f3',
-          title: 'Feature 3',
-          description: 'desc',
-          category: 'test',
-          branchName: 'valid-branch',
-        },
-      ];
-      const getAllMock = vi.fn().mockResolvedValue(features);
-      mockFeatureLoaderGetAll(service, getAllMock);
-      mockGetExistingBranches(service, ['main', 'valid-branch']);
-
-      const result = await service.detectOrphanedFeatures('/test/project');
-
-      expect(result).toHaveLength(2);
-      expect(result.map((r) => r.feature.id)).toContain('f1');
-      expect(result.map((r) => r.feature.id)).toContain('f2');
-    });
-
-    it('should return empty array when getAll throws error', async () => {
-      const getAllMock = vi.fn().mockRejectedValue(new Error('Failed to load features'));
-      mockFeatureLoaderGetAll(service, getAllMock);
-
-      const result = await service.detectOrphanedFeatures('/test/project');
-
-      expect(result).toEqual([]);
-    });
-
-    it('should ignore empty branchName strings', async () => {
-      const features: Feature[] = [
-        { id: 'f1', title: 'Feature 1', description: 'desc', category: 'test', branchName: '' },
-        { id: 'f2', title: 'Feature 2', description: 'desc', category: 'test', branchName: '   ' },
-      ];
-      const getAllMock = vi.fn().mockResolvedValue(features);
-      mockFeatureLoaderGetAll(service, getAllMock);
-      mockGetExistingBranches(service, ['main']);
-
-      const result = await service.detectOrphanedFeatures('/test/project');
-
-      expect(result).toEqual([]);
-    });
-
-    it('should skip features whose branchName matches the primary branch', async () => {
-      const features: Feature[] = [
-        { id: 'f1', title: 'Feature 1', description: 'desc', category: 'test', branchName: 'main' },
-        {
-          id: 'f2',
-          title: 'Feature 2',
-          description: 'desc',
-          category: 'test',
-          branchName: 'orphaned',
-        },
-      ];
-      const getAllMock = vi.fn().mockResolvedValue(features);
-      mockFeatureLoaderGetAll(service, getAllMock);
-      mockGetExistingBranches(service, ['main', 'develop']);
-      // Mock getCurrentBranch to return 'main'
-      (service as any).getCurrentBranch = vi.fn().mockResolvedValue('main');
-
-      const result = await service.detectOrphanedFeatures('/test/project');
-
-      // Only f2 should be orphaned (orphaned branch doesn't exist)
-      expect(result).toHaveLength(1);
-      expect(result[0].feature.id).toBe('f2');
-    });
-  });
-
-  describe('markFeatureInterrupted', () => {
-    // Helper to mock updateFeatureStatus
-    const mockUpdateFeatureStatus = (svc: AutoModeService, mockFn: ReturnType<typeof vi.fn>) => {
-      (svc as any).updateFeatureStatus = mockFn;
-    };
-
-    // Helper to mock loadFeature
-    const mockLoadFeature = (svc: AutoModeService, mockFn: ReturnType<typeof vi.fn>) => {
-      (svc as any).loadFeature = mockFn;
-    };
-
-    it('should call updateFeatureStatus with interrupted status for non-pipeline features', async () => {
-      const loadMock = vi.fn().mockResolvedValue({ id: 'feature-123', status: 'in_progress' });
-      const updateMock = vi.fn().mockResolvedValue(undefined);
-      mockLoadFeature(service, loadMock);
-      mockUpdateFeatureStatus(service, updateMock);
-
-      await service.markFeatureInterrupted('/test/project', 'feature-123');
-
-      expect(updateMock).toHaveBeenCalledWith('/test/project', 'feature-123', 'interrupted');
-    });
-
-    it('should call updateFeatureStatus with reason when provided', async () => {
-      const loadMock = vi.fn().mockResolvedValue({ id: 'feature-123', status: 'in_progress' });
-      const updateMock = vi.fn().mockResolvedValue(undefined);
-      mockLoadFeature(service, loadMock);
-      mockUpdateFeatureStatus(service, updateMock);
-
-      await service.markFeatureInterrupted('/test/project', 'feature-123', 'server shutdown');
-
-      expect(updateMock).toHaveBeenCalledWith('/test/project', 'feature-123', 'interrupted');
-    });
-
-    it('should propagate errors from updateFeatureStatus', async () => {
-      const loadMock = vi.fn().mockResolvedValue({ id: 'feature-123', status: 'in_progress' });
-      const updateMock = vi.fn().mockRejectedValue(new Error('Update failed'));
-      mockLoadFeature(service, loadMock);
-      mockUpdateFeatureStatus(service, updateMock);
-
-      await expect(service.markFeatureInterrupted('/test/project', 'feature-123')).rejects.toThrow(
-        'Update failed'
-      );
-    });
-
-    it('should preserve pipeline_implementation status instead of marking as interrupted', async () => {
-      const loadMock = vi
-        .fn()
-        .mockResolvedValue({ id: 'feature-123', status: 'pipeline_implementation' });
-      const updateMock = vi.fn().mockResolvedValue(undefined);
-      mockLoadFeature(service, loadMock);
-      mockUpdateFeatureStatus(service, updateMock);
-
-      await service.markFeatureInterrupted('/test/project', 'feature-123', 'server shutdown');
-
-      // updateFeatureStatus should NOT be called for pipeline statuses
-      expect(updateMock).not.toHaveBeenCalled();
-    });
-
-    it('should preserve pipeline_testing status instead of marking as interrupted', async () => {
-      const loadMock = vi.fn().mockResolvedValue({ id: 'feature-123', status: 'pipeline_testing' });
-      const updateMock = vi.fn().mockResolvedValue(undefined);
-      mockLoadFeature(service, loadMock);
-      mockUpdateFeatureStatus(service, updateMock);
-
-      await service.markFeatureInterrupted('/test/project', 'feature-123');
-
-      expect(updateMock).not.toHaveBeenCalled();
-    });
-
-    it('should preserve pipeline_review status instead of marking as interrupted', async () => {
-      const loadMock = vi.fn().mockResolvedValue({ id: 'feature-123', status: 'pipeline_review' });
-      const updateMock = vi.fn().mockResolvedValue(undefined);
-      mockLoadFeature(service, loadMock);
-      mockUpdateFeatureStatus(service, updateMock);
-
-      await service.markFeatureInterrupted('/test/project', 'feature-123');
-
-      expect(updateMock).not.toHaveBeenCalled();
-    });
-
-    it('should mark feature as interrupted when loadFeature returns null', async () => {
-      const loadMock = vi.fn().mockResolvedValue(null);
-      const updateMock = vi.fn().mockResolvedValue(undefined);
-      mockLoadFeature(service, loadMock);
-      mockUpdateFeatureStatus(service, updateMock);
-
-      await service.markFeatureInterrupted('/test/project', 'feature-123');
-
-      expect(updateMock).toHaveBeenCalledWith('/test/project', 'feature-123', 'interrupted');
-    });
-
-    it('should mark feature as interrupted for pending status', async () => {
-      const loadMock = vi.fn().mockResolvedValue({ id: 'feature-123', status: 'pending' });
-      const updateMock = vi.fn().mockResolvedValue(undefined);
-      mockLoadFeature(service, loadMock);
-      mockUpdateFeatureStatus(service, updateMock);
-
-      await service.markFeatureInterrupted('/test/project', 'feature-123');
-
-      expect(updateMock).toHaveBeenCalledWith('/test/project', 'feature-123', 'interrupted');
-    });
-  });
-
-  describe('markAllRunningFeaturesInterrupted', () => {
-    // Helper to access private runningFeatures Map
-    const getRunningFeaturesMap = (svc: AutoModeService) =>
-      (svc as any).runningFeatures as Map<
-        string,
-        { featureId: string; projectPath: string; isAutoMode: boolean }
-      >;
-
-    // Helper to mock updateFeatureStatus
-    const mockUpdateFeatureStatus = (svc: AutoModeService, mockFn: ReturnType<typeof vi.fn>) => {
-      (svc as any).updateFeatureStatus = mockFn;
-    };
-
-    // Helper to mock loadFeature
-    const mockLoadFeature = (svc: AutoModeService, mockFn: ReturnType<typeof vi.fn>) => {
-      (svc as any).loadFeature = mockFn;
-    };
-
-    it('should do nothing when no features are running', async () => {
-      const updateMock = vi.fn().mockResolvedValue(undefined);
-      mockUpdateFeatureStatus(service, updateMock);
-
-      await service.markAllRunningFeaturesInterrupted();
-
-      expect(updateMock).not.toHaveBeenCalled();
-    });
-
-    it('should mark a single running feature as interrupted', async () => {
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      runningFeaturesMap.set('feature-1', {
-        featureId: 'feature-1',
-        projectPath: '/project/path',
-        isAutoMode: true,
-      });
-
-      const loadMock = vi.fn().mockResolvedValue({ id: 'feature-1', status: 'in_progress' });
-      const updateMock = vi.fn().mockResolvedValue(undefined);
-      mockLoadFeature(service, loadMock);
-      mockUpdateFeatureStatus(service, updateMock);
-
-      await service.markAllRunningFeaturesInterrupted();
-
-      expect(updateMock).toHaveBeenCalledWith('/project/path', 'feature-1', 'interrupted');
-    });
-
-    it('should mark multiple running features as interrupted', async () => {
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      runningFeaturesMap.set('feature-1', {
-        featureId: 'feature-1',
-        projectPath: '/project-a',
-        isAutoMode: true,
-      });
-      runningFeaturesMap.set('feature-2', {
-        featureId: 'feature-2',
-        projectPath: '/project-b',
-        isAutoMode: false,
-      });
-      runningFeaturesMap.set('feature-3', {
-        featureId: 'feature-3',
-        projectPath: '/project-a',
-        isAutoMode: true,
-      });
-
-      const loadMock = vi.fn().mockResolvedValue({ status: 'in_progress' });
-      const updateMock = vi.fn().mockResolvedValue(undefined);
-      mockLoadFeature(service, loadMock);
-      mockUpdateFeatureStatus(service, updateMock);
-
-      await service.markAllRunningFeaturesInterrupted();
-
-      expect(updateMock).toHaveBeenCalledTimes(3);
-      expect(updateMock).toHaveBeenCalledWith('/project-a', 'feature-1', 'interrupted');
-      expect(updateMock).toHaveBeenCalledWith('/project-b', 'feature-2', 'interrupted');
-      expect(updateMock).toHaveBeenCalledWith('/project-a', 'feature-3', 'interrupted');
-    });
-
-    it('should mark features in parallel', async () => {
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      for (let i = 1; i <= 5; i++) {
-        runningFeaturesMap.set(`feature-${i}`, {
-          featureId: `feature-${i}`,
-          projectPath: `/project-${i}`,
-          isAutoMode: true,
-        });
-      }
-
-      const loadMock = vi.fn().mockResolvedValue({ status: 'in_progress' });
-      const callOrder: string[] = [];
-      const updateMock = vi.fn().mockImplementation(async (_path: string, featureId: string) => {
-        callOrder.push(featureId);
-        await new Promise((resolve) => setTimeout(resolve, 10));
-      });
-      mockLoadFeature(service, loadMock);
-      mockUpdateFeatureStatus(service, updateMock);
-
-      const startTime = Date.now();
-      await service.markAllRunningFeaturesInterrupted();
-      const duration = Date.now() - startTime;
-
-      expect(updateMock).toHaveBeenCalledTimes(5);
-      // If executed in parallel, total time should be ~10ms
-      // If sequential, it would be ~50ms (5 * 10ms)
-      expect(duration).toBeLessThan(40);
-    });
-
-    it('should continue marking other features when one fails', async () => {
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      runningFeaturesMap.set('feature-1', {
-        featureId: 'feature-1',
-        projectPath: '/project-a',
-        isAutoMode: true,
-      });
-      runningFeaturesMap.set('feature-2', {
-        featureId: 'feature-2',
-        projectPath: '/project-b',
-        isAutoMode: false,
-      });
-
-      const loadMock = vi.fn().mockResolvedValue({ status: 'in_progress' });
-      const updateMock = vi
-        .fn()
-        .mockResolvedValueOnce(undefined)
-        .mockRejectedValueOnce(new Error('Failed to update'));
-      mockLoadFeature(service, loadMock);
-      mockUpdateFeatureStatus(service, updateMock);
-
-      // Should not throw even though one feature failed
-      await expect(service.markAllRunningFeaturesInterrupted()).resolves.not.toThrow();
-
-      expect(updateMock).toHaveBeenCalledTimes(2);
-    });
-
-    it('should use provided reason in logging', async () => {
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      runningFeaturesMap.set('feature-1', {
-        featureId: 'feature-1',
-        projectPath: '/project/path',
-        isAutoMode: true,
-      });
-
-      const loadMock = vi.fn().mockResolvedValue({ id: 'feature-1', status: 'in_progress' });
-      const updateMock = vi.fn().mockResolvedValue(undefined);
-      mockLoadFeature(service, loadMock);
-      mockUpdateFeatureStatus(service, updateMock);
-
-      await service.markAllRunningFeaturesInterrupted('manual stop');
-
-      expect(updateMock).toHaveBeenCalledWith('/project/path', 'feature-1', 'interrupted');
-    });
-
-    it('should use default reason when none provided', async () => {
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      runningFeaturesMap.set('feature-1', {
-        featureId: 'feature-1',
-        projectPath: '/project/path',
-        isAutoMode: true,
-      });
-
-      const loadMock = vi.fn().mockResolvedValue({ id: 'feature-1', status: 'in_progress' });
-      const updateMock = vi.fn().mockResolvedValue(undefined);
-      mockLoadFeature(service, loadMock);
-      mockUpdateFeatureStatus(service, updateMock);
-
-      await service.markAllRunningFeaturesInterrupted();
-
-      expect(updateMock).toHaveBeenCalledWith('/project/path', 'feature-1', 'interrupted');
-    });
-
-    it('should preserve pipeline statuses for running features', async () => {
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      runningFeaturesMap.set('feature-1', {
-        featureId: 'feature-1',
-        projectPath: '/project-a',
-        isAutoMode: true,
-      });
-      runningFeaturesMap.set('feature-2', {
-        featureId: 'feature-2',
-        projectPath: '/project-b',
-        isAutoMode: false,
-      });
-      runningFeaturesMap.set('feature-3', {
-        featureId: 'feature-3',
-        projectPath: '/project-c',
-        isAutoMode: true,
-      });
-
-      // feature-1 has in_progress (should be interrupted)
-      // feature-2 has pipeline_testing (should be preserved)
-      // feature-3 has pipeline_implementation (should be preserved)
-      const loadMock = vi
-        .fn()
-        .mockImplementation(async (_projectPath: string, featureId: string) => {
-          if (featureId === 'feature-1') return { id: 'feature-1', status: 'in_progress' };
-          if (featureId === 'feature-2') return { id: 'feature-2', status: 'pipeline_testing' };
-          if (featureId === 'feature-3')
-            return { id: 'feature-3', status: 'pipeline_implementation' };
-          return null;
-        });
-      const updateMock = vi.fn().mockResolvedValue(undefined);
-      mockLoadFeature(service, loadMock);
-      mockUpdateFeatureStatus(service, updateMock);
-
-      await service.markAllRunningFeaturesInterrupted();
-
-      // Only feature-1 should be marked as interrupted
-      expect(updateMock).toHaveBeenCalledTimes(1);
-      expect(updateMock).toHaveBeenCalledWith('/project-a', 'feature-1', 'interrupted');
-    });
-  });
-
-  describe('isFeatureRunning', () => {
-    // Helper to access private runningFeatures Map
-    const getRunningFeaturesMap = (svc: AutoModeService) =>
-      (svc as any).runningFeatures as Map<
-        string,
-        { featureId: string; projectPath: string; isAutoMode: boolean }
-      >;
-
-    it('should return false when no features are running', () => {
-      expect(service.isFeatureRunning('feature-123')).toBe(false);
-    });
-
-    it('should return true when the feature is running', () => {
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      runningFeaturesMap.set('feature-123', {
-        featureId: 'feature-123',
-        projectPath: '/project/path',
-        isAutoMode: true,
-      });
-
-      expect(service.isFeatureRunning('feature-123')).toBe(true);
-    });
-
-    it('should return false for non-running feature when others are running', () => {
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      runningFeaturesMap.set('feature-other', {
-        featureId: 'feature-other',
-        projectPath: '/project/path',
-        isAutoMode: true,
-      });
-
-      expect(service.isFeatureRunning('feature-123')).toBe(false);
-    });
-
-    it('should correctly track multiple running features', () => {
-      const runningFeaturesMap = getRunningFeaturesMap(service);
-      runningFeaturesMap.set('feature-1', {
-        featureId: 'feature-1',
-        projectPath: '/project-a',
-        isAutoMode: true,
-      });
-      runningFeaturesMap.set('feature-2', {
-        featureId: 'feature-2',
-        projectPath: '/project-b',
-        isAutoMode: false,
-      });
-
-      expect(service.isFeatureRunning('feature-1')).toBe(true);
-      expect(service.isFeatureRunning('feature-2')).toBe(true);
-      expect(service.isFeatureRunning('feature-3')).toBe(false);
-    });
-  });
-});

apps/server/tests/unit/services/claude-usage-service.test.ts

@@ -177,6 +177,66 @@ describe('claude-usage-service.ts', () => {
       // BEL is stripped, newlines and tabs preserved
       expect(result).toBe('Line 1\nLine 2\tTabbed with bell');
     });
+
+    it('should convert cursor forward (ESC[nC) to spaces', () => {
+      const service = new ClaudeUsageService();
+      // Claude CLI TUI uses ESC[1C instead of space between words
+      const input = 'Current\x1B[1Csession';
+      // @ts-expect-error - accessing private method for testing
+      const result = service.stripAnsiCodes(input);
+
+      expect(result).toBe('Current session');
+    });
+
+    it('should handle multi-character cursor forward sequences', () => {
+      const service = new ClaudeUsageService();
+      // ESC[3C = move cursor forward 3 positions = 3 spaces
+      const input = 'Hello\x1B[3Cworld';
+      // @ts-expect-error - accessing private method for testing
+      const result = service.stripAnsiCodes(input);
+
+      expect(result).toBe('Hello   world');
+    });
+
+    it('should handle real Claude CLI TUI output with cursor movement codes', () => {
+      const service = new ClaudeUsageService();
+      // Simulates actual Claude CLI /usage output where words are separated by ESC[1C
+      const input =
+        'Current\x1B[1Cweek\x1B[1C(all\x1B[1Cmodels)\n' +
+        '\x1B[32m█████████████████████████▌\x1B[0m\x1B[1C51%\x1B[1Cused\n' +
+        'Resets\x1B[1CFeb\x1B[1C19\x1B[1Cat\x1B[1C3pm\x1B[1C(America/Los_Angeles)';
+      // @ts-expect-error - accessing private method for testing
+      const result = service.stripAnsiCodes(input);
+
+      expect(result).toContain('Current week (all models)');
+      expect(result).toContain('51% used');
+      expect(result).toContain('Resets Feb 19 at 3pm (America/Los_Angeles)');
+    });
+
+    it('should parse usage output with cursor movement codes between words', () => {
+      const service = new ClaudeUsageService();
+      // Simulates the full /usage TUI output with ESC[1C between every word
+      const output =
+        'Current\x1B[1Csession\n' +
+        '\x1B[32m█████████████▌\x1B[0m\x1B[1C27%\x1B[1Cused\n' +
+        'Resets\x1B[1C9pm\x1B[1C(America/Los_Angeles)\n' +
+        '\n' +
+        'Current\x1B[1Cweek\x1B[1C(all\x1B[1Cmodels)\n' +
+        '\x1B[32m█████████████████████████▌\x1B[0m\x1B[1C51%\x1B[1Cused\n' +
+        'Resets\x1B[1CFeb\x1B[1C19\x1B[1Cat\x1B[1C3pm\x1B[1C(America/Los_Angeles)\n' +
+        '\n' +
+        'Current\x1B[1Cweek\x1B[1C(Sonnet\x1B[1Conly)\n' +
+        '\x1B[32m██▌\x1B[0m\x1B[1C5%\x1B[1Cused\n' +
+        'Resets\x1B[1CFeb\x1B[1C19\x1B[1Cat\x1B[1C11pm\x1B[1C(America/Los_Angeles)';
+      // @ts-expect-error - accessing private method for testing
+      const result = service.parseUsageOutput(output);
+
+      expect(result.sessionPercentage).toBe(27);
+      expect(result.weeklyPercentage).toBe(51);
+      expect(result.sonnetWeeklyPercentage).toBe(5);
+      expect(result.weeklyResetText).toContain('Resets Feb 19 at 3pm');
+      expect(result.weeklyResetText).not.toContain('America/Los_Angeles');
+    });
   });
 
   describe('parseResetTime', () => {

apps/server/tests/unit/services/concurrency-manager.test.ts

@@ -0,0 +1,609 @@
+import { describe, it, expect, beforeEach, vi, type Mock } from 'vitest';
+import {
+  ConcurrencyManager,
+  type RunningFeature,
+  type GetCurrentBranchFn,
+} from '@/services/concurrency-manager.js';
+
+describe('ConcurrencyManager', () => {
+  let manager: ConcurrencyManager;
+  let mockGetCurrentBranch: Mock<GetCurrentBranchFn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Default: primary branch is 'main'
+    mockGetCurrentBranch = vi.fn().mockResolvedValue('main');
+    manager = new ConcurrencyManager(mockGetCurrentBranch);
+  });
+
+  describe('acquire', () => {
+    it('should create new entry with leaseCount: 1 on first acquire', () => {
+      const result = manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      expect(result.featureId).toBe('feature-1');
+      expect(result.projectPath).toBe('/test/project');
+      expect(result.isAutoMode).toBe(true);
+      expect(result.leaseCount).toBe(1);
+      expect(result.worktreePath).toBeNull();
+      expect(result.branchName).toBeNull();
+      expect(result.startTime).toBeDefined();
+      expect(result.abortController).toBeInstanceOf(AbortController);
+    });
+
+    it('should increment leaseCount when allowReuse is true for existing feature', () => {
+      // First acquire
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      // Second acquire with allowReuse
+      const result = manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+        allowReuse: true,
+      });
+
+      expect(result.leaseCount).toBe(2);
+    });
+
+    it('should throw "already running" when allowReuse is false for existing feature', () => {
+      // First acquire
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      // Second acquire without allowReuse
+      expect(() =>
+        manager.acquire({
+          featureId: 'feature-1',
+          projectPath: '/test/project',
+          isAutoMode: true,
+        })
+      ).toThrow('already running');
+    });
+
+    it('should throw "already running" when allowReuse is explicitly false', () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      expect(() =>
+        manager.acquire({
+          featureId: 'feature-1',
+          projectPath: '/test/project',
+          isAutoMode: true,
+          allowReuse: false,
+        })
+      ).toThrow('already running');
+    });
+
+    it('should use provided abortController', () => {
+      const customAbortController = new AbortController();
+
+      const result = manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+        abortController: customAbortController,
+      });
+
+      expect(result.abortController).toBe(customAbortController);
+    });
+
+    it('should return the existing entry when allowReuse is true', () => {
+      const first = manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      const second = manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+        allowReuse: true,
+      });
+
+      // Should be the same object reference
+      expect(second).toBe(first);
+    });
+
+    it('should allow multiple nested acquire calls with allowReuse', () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+        allowReuse: true,
+      });
+
+      const result = manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+        allowReuse: true,
+      });
+
+      expect(result.leaseCount).toBe(3);
+    });
+  });
+
+  describe('release', () => {
+    it('should decrement leaseCount on release', () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+        allowReuse: true,
+      });
+
+      manager.release('feature-1');
+
+      const entry = manager.getRunningFeature('feature-1');
+      expect(entry?.leaseCount).toBe(1);
+    });
+
+    it('should delete entry when leaseCount reaches 0', () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      manager.release('feature-1');
+
+      expect(manager.isRunning('feature-1')).toBe(false);
+      expect(manager.getRunningFeature('feature-1')).toBeUndefined();
+    });
+
+    it('should delete entry immediately when force is true regardless of leaseCount', () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+        allowReuse: true,
+      });
+
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+        allowReuse: true,
+      });
+
+      // leaseCount is 3, but force should still delete
+      manager.release('feature-1', { force: true });
+
+      expect(manager.isRunning('feature-1')).toBe(false);
+    });
+
+    it('should do nothing when releasing non-existent feature', () => {
+      // Should not throw
+      manager.release('non-existent-feature');
+      manager.release('non-existent-feature', { force: true });
+    });
+
+    it('should only delete entry after all leases are released', () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+        allowReuse: true,
+      });
+
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+        allowReuse: true,
+      });
+
+      // leaseCount is 3
+      manager.release('feature-1');
+      expect(manager.isRunning('feature-1')).toBe(true);
+
+      manager.release('feature-1');
+      expect(manager.isRunning('feature-1')).toBe(true);
+
+      manager.release('feature-1');
+      expect(manager.isRunning('feature-1')).toBe(false);
+    });
+  });
+
+  describe('isRunning', () => {
+    it('should return false when feature is not running', () => {
+      expect(manager.isRunning('feature-1')).toBe(false);
+    });
+
+    it('should return true when feature is running', () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      expect(manager.isRunning('feature-1')).toBe(true);
+    });
+
+    it('should return false after feature is released', () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      manager.release('feature-1');
+
+      expect(manager.isRunning('feature-1')).toBe(false);
+    });
+  });
+
+  describe('getRunningFeature', () => {
+    it('should return undefined for non-existent feature', () => {
+      expect(manager.getRunningFeature('feature-1')).toBeUndefined();
+    });
+
+    it('should return the RunningFeature entry', () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      const entry = manager.getRunningFeature('feature-1');
+      expect(entry).toBeDefined();
+      expect(entry?.featureId).toBe('feature-1');
+      expect(entry?.projectPath).toBe('/test/project');
+    });
+  });
+
+  describe('getRunningCount (project-level)', () => {
+    it('should return 0 when no features are running', () => {
+      expect(manager.getRunningCount('/test/project')).toBe(0);
+    });
+
+    it('should count features for specific project', () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      manager.acquire({
+        featureId: 'feature-2',
+        projectPath: '/test/project',
+        isAutoMode: false,
+      });
+
+      expect(manager.getRunningCount('/test/project')).toBe(2);
+    });
+
+    it('should only count features for the specified project', () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/project-a',
+        isAutoMode: true,
+      });
+
+      manager.acquire({
+        featureId: 'feature-2',
+        projectPath: '/project-b',
+        isAutoMode: true,
+      });
+
+      manager.acquire({
+        featureId: 'feature-3',
+        projectPath: '/project-a',
+        isAutoMode: false,
+      });
+
+      expect(manager.getRunningCount('/project-a')).toBe(2);
+      expect(manager.getRunningCount('/project-b')).toBe(1);
+      expect(manager.getRunningCount('/project-c')).toBe(0);
+    });
+  });
+
+  describe('getRunningCountForWorktree', () => {
+    it('should return 0 when no features are running', async () => {
+      const count = await manager.getRunningCountForWorktree('/test/project', null);
+      expect(count).toBe(0);
+    });
+
+    it('should count features with null branchName as main worktree', async () => {
+      const entry = manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+      // entry.branchName is null by default
+
+      const count = await manager.getRunningCountForWorktree('/test/project', null);
+      expect(count).toBe(1);
+    });
+
+    it('should count features matching primary branch as main worktree', async () => {
+      mockGetCurrentBranch.mockResolvedValue('main');
+
+      const entry = manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+      manager.updateRunningFeature('feature-1', { branchName: 'main' });
+
+      const count = await manager.getRunningCountForWorktree('/test/project', null);
+      expect(count).toBe(1);
+    });
+
+    it('should count features with exact branch match for feature worktrees', async () => {
+      const entry = manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+      manager.updateRunningFeature('feature-1', { branchName: 'feature-branch' });
+
+      manager.acquire({
+        featureId: 'feature-2',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+      // feature-2 has null branchName
+
+      const featureBranchCount = await manager.getRunningCountForWorktree(
+        '/test/project',
+        'feature-branch'
+      );
+      expect(featureBranchCount).toBe(1);
+
+      const mainWorktreeCount = await manager.getRunningCountForWorktree('/test/project', null);
+      expect(mainWorktreeCount).toBe(1);
+    });
+
+    it('should respect branch normalization (main is treated as null)', async () => {
+      mockGetCurrentBranch.mockResolvedValue('main');
+
+      // Feature with branchName 'main' should count as main worktree
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+      manager.updateRunningFeature('feature-1', { branchName: 'main' });
+
+      // Feature with branchName null should also count as main worktree
+      manager.acquire({
+        featureId: 'feature-2',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      const mainCount = await manager.getRunningCountForWorktree('/test/project', null);
+      expect(mainCount).toBe(2);
+    });
+
+    it('should filter by both projectPath and branchName', async () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/project-a',
+        isAutoMode: true,
+      });
+      manager.updateRunningFeature('feature-1', { branchName: 'feature-x' });
+
+      manager.acquire({
+        featureId: 'feature-2',
+        projectPath: '/project-b',
+        isAutoMode: true,
+      });
+      manager.updateRunningFeature('feature-2', { branchName: 'feature-x' });
+
+      const countA = await manager.getRunningCountForWorktree('/project-a', 'feature-x');
+      const countB = await manager.getRunningCountForWorktree('/project-b', 'feature-x');
+
+      expect(countA).toBe(1);
+      expect(countB).toBe(1);
+    });
+  });
+
+  describe('getAllRunning', () => {
+    it('should return empty array when no features are running', () => {
+      expect(manager.getAllRunning()).toEqual([]);
+    });
+
+    it('should return array with all running features', () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/project-a',
+        isAutoMode: true,
+      });
+
+      manager.acquire({
+        featureId: 'feature-2',
+        projectPath: '/project-b',
+        isAutoMode: false,
+      });
+
+      const running = manager.getAllRunning();
+      expect(running).toHaveLength(2);
+      expect(running.map((r) => r.featureId)).toContain('feature-1');
+      expect(running.map((r) => r.featureId)).toContain('feature-2');
+    });
+
+    it('should include feature metadata', () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/project-a',
+        isAutoMode: true,
+      });
+      manager.updateRunningFeature('feature-1', { model: 'claude-sonnet-4', provider: 'claude' });
+
+      const running = manager.getAllRunning();
+      expect(running[0].model).toBe('claude-sonnet-4');
+      expect(running[0].provider).toBe('claude');
+    });
+  });
+
+  describe('updateRunningFeature', () => {
+    it('should update worktreePath and branchName', () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      manager.updateRunningFeature('feature-1', {
+        worktreePath: '/worktrees/feature-1',
+        branchName: 'feature-1-branch',
+      });
+
+      const entry = manager.getRunningFeature('feature-1');
+      expect(entry?.worktreePath).toBe('/worktrees/feature-1');
+      expect(entry?.branchName).toBe('feature-1-branch');
+    });
+
+    it('should update model and provider', () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      manager.updateRunningFeature('feature-1', {
+        model: 'claude-opus-4-5-20251101',
+        provider: 'claude',
+      });
+
+      const entry = manager.getRunningFeature('feature-1');
+      expect(entry?.model).toBe('claude-opus-4-5-20251101');
+      expect(entry?.provider).toBe('claude');
+    });
+
+    it('should do nothing for non-existent feature', () => {
+      // Should not throw
+      manager.updateRunningFeature('non-existent', { model: 'test' });
+    });
+
+    it('should preserve other properties when updating partial fields', () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      const original = manager.getRunningFeature('feature-1');
+      const originalStartTime = original?.startTime;
+
+      manager.updateRunningFeature('feature-1', { model: 'claude-sonnet-4' });
+
+      const updated = manager.getRunningFeature('feature-1');
+      expect(updated?.startTime).toBe(originalStartTime);
+      expect(updated?.projectPath).toBe('/test/project');
+      expect(updated?.isAutoMode).toBe(true);
+      expect(updated?.model).toBe('claude-sonnet-4');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle multiple features for same project', () => {
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      manager.acquire({
+        featureId: 'feature-2',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      manager.acquire({
+        featureId: 'feature-3',
+        projectPath: '/test/project',
+        isAutoMode: false,
+      });
+
+      expect(manager.getRunningCount('/test/project')).toBe(3);
+      expect(manager.isRunning('feature-1')).toBe(true);
+      expect(manager.isRunning('feature-2')).toBe(true);
+      expect(manager.isRunning('feature-3')).toBe(true);
+    });
+
+    it('should handle features across different worktrees', async () => {
+      // Main worktree feature
+      manager.acquire({
+        featureId: 'feature-1',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+
+      // Worktree A feature
+      manager.acquire({
+        featureId: 'feature-2',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+      manager.updateRunningFeature('feature-2', {
+        worktreePath: '/worktrees/a',
+        branchName: 'branch-a',
+      });
+
+      // Worktree B feature
+      manager.acquire({
+        featureId: 'feature-3',
+        projectPath: '/test/project',
+        isAutoMode: true,
+      });
+      manager.updateRunningFeature('feature-3', {
+        worktreePath: '/worktrees/b',
+        branchName: 'branch-b',
+      });
+
+      expect(await manager.getRunningCountForWorktree('/test/project', null)).toBe(1);
+      expect(await manager.getRunningCountForWorktree('/test/project', 'branch-a')).toBe(1);
+      expect(await manager.getRunningCountForWorktree('/test/project', 'branch-b')).toBe(1);
+      expect(manager.getRunningCount('/test/project')).toBe(3);
+    });
+
+    it('should return 0 counts and empty arrays for empty state', () => {
+      expect(manager.getRunningCount('/any/project')).toBe(0);
+      expect(manager.getAllRunning()).toEqual([]);
+      expect(manager.isRunning('any-feature')).toBe(false);
+      expect(manager.getRunningFeature('any-feature')).toBeUndefined();
+    });
+  });
+});

apps/server/tests/unit/services/dev-server-service.test.ts

@@ -30,11 +30,16 @@ import net from 'net';
 
 describe('dev-server-service.ts', () => {
   let testDir: string;
+  let originalHostname: string | undefined;
 
   beforeEach(async () => {
     vi.clearAllMocks();
     vi.resetModules();
 
+    // Store and set HOSTNAME for consistent test behavior
+    originalHostname = process.env.HOSTNAME;
+    process.env.HOSTNAME = 'localhost';
+
     testDir = path.join(os.tmpdir(), `dev-server-test-${Date.now()}`);
     await fs.mkdir(testDir, { recursive: true });
 
@@ -56,6 +61,13 @@ describe('dev-server-service.ts', () => {
   });
 
   afterEach(async () => {
+    // Restore original HOSTNAME
+    if (originalHostname === undefined) {
+      delete process.env.HOSTNAME;
+    } else {
+      process.env.HOSTNAME = originalHostname;
+    }
+
     try {
       await fs.rm(testDir, { recursive: true, force: true });
     } catch {
@@ -368,6 +380,148 @@ describe('dev-server-service.ts', () => {
       expect(service.listDevServers().result.servers).toHaveLength(0);
     });
   });
+
+  describe('URL detection from output', () => {
+    it('should detect Vite format URL', async () => {
+      vi.mocked(secureFs.access).mockResolvedValue(undefined);
+
+      const mockProcess = createMockProcess();
+      vi.mocked(spawn).mockReturnValue(mockProcess as any);
+
+      const { getDevServerService } = await import('@/services/dev-server-service.js');
+      const service = getDevServerService();
+
+      // Start server
+      await service.startDevServer(testDir, testDir);
+
+      // Simulate Vite output
+      mockProcess.stdout.emit('data', Buffer.from('  VITE v5.0.0  ready in 123 ms\n'));
+      mockProcess.stdout.emit('data', Buffer.from('  ➜  Local:   http://localhost:5173/\n'));
+
+      // Give it a moment to process
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      const serverInfo = service.getServerInfo(testDir);
+      expect(serverInfo?.url).toBe('http://localhost:5173/');
+      expect(serverInfo?.urlDetected).toBe(true);
+    });
+
+    it('should detect Next.js format URL', async () => {
+      vi.mocked(secureFs.access).mockResolvedValue(undefined);
+
+      const mockProcess = createMockProcess();
+      vi.mocked(spawn).mockReturnValue(mockProcess as any);
+
+      const { getDevServerService } = await import('@/services/dev-server-service.js');
+      const service = getDevServerService();
+
+      await service.startDevServer(testDir, testDir);
+
+      // Simulate Next.js output
+      mockProcess.stdout.emit(
+        'data',
+        Buffer.from('ready - started server on 0.0.0.0:3000, url: http://localhost:3000\n')
+      );
+
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      const serverInfo = service.getServerInfo(testDir);
+      expect(serverInfo?.url).toBe('http://localhost:3000');
+      expect(serverInfo?.urlDetected).toBe(true);
+    });
+
+    it('should detect generic localhost URL', async () => {
+      vi.mocked(secureFs.access).mockResolvedValue(undefined);
+
+      const mockProcess = createMockProcess();
+      vi.mocked(spawn).mockReturnValue(mockProcess as any);
+
+      const { getDevServerService } = await import('@/services/dev-server-service.js');
+      const service = getDevServerService();
+
+      await service.startDevServer(testDir, testDir);
+
+      // Simulate generic output with URL
+      mockProcess.stdout.emit('data', Buffer.from('Server running at http://localhost:8080\n'));
+
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      const serverInfo = service.getServerInfo(testDir);
+      expect(serverInfo?.url).toBe('http://localhost:8080');
+      expect(serverInfo?.urlDetected).toBe(true);
+    });
+
+    it('should keep initial URL if no URL detected in output', async () => {
+      vi.mocked(secureFs.access).mockResolvedValue(undefined);
+
+      const mockProcess = createMockProcess();
+      vi.mocked(spawn).mockReturnValue(mockProcess as any);
+
+      const { getDevServerService } = await import('@/services/dev-server-service.js');
+      const service = getDevServerService();
+
+      const result = await service.startDevServer(testDir, testDir);
+
+      // Simulate output without URL
+      mockProcess.stdout.emit('data', Buffer.from('Server starting...\n'));
+      mockProcess.stdout.emit('data', Buffer.from('Ready!\n'));
+
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      const serverInfo = service.getServerInfo(testDir);
+      // Should keep the initial allocated URL
+      expect(serverInfo?.url).toBe(result.result?.url);
+      expect(serverInfo?.urlDetected).toBe(false);
+    });
+
+    it('should detect HTTPS URLs', async () => {
+      vi.mocked(secureFs.access).mockResolvedValue(undefined);
+
+      const mockProcess = createMockProcess();
+      vi.mocked(spawn).mockReturnValue(mockProcess as any);
+
+      const { getDevServerService } = await import('@/services/dev-server-service.js');
+      const service = getDevServerService();
+
+      await service.startDevServer(testDir, testDir);
+
+      // Simulate HTTPS dev server
+      mockProcess.stdout.emit('data', Buffer.from('Server at https://localhost:3443\n'));
+
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      const serverInfo = service.getServerInfo(testDir);
+      expect(serverInfo?.url).toBe('https://localhost:3443');
+      expect(serverInfo?.urlDetected).toBe(true);
+    });
+
+    it('should only detect URL once (not update after first detection)', async () => {
+      vi.mocked(secureFs.access).mockResolvedValue(undefined);
+
+      const mockProcess = createMockProcess();
+      vi.mocked(spawn).mockReturnValue(mockProcess as any);
+
+      const { getDevServerService } = await import('@/services/dev-server-service.js');
+      const service = getDevServerService();
+
+      await service.startDevServer(testDir, testDir);
+
+      // First URL
+      mockProcess.stdout.emit('data', Buffer.from('Local: http://localhost:5173/\n'));
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      const firstUrl = service.getServerInfo(testDir)?.url;
+
+      // Try to emit another URL
+      mockProcess.stdout.emit('data', Buffer.from('Network: http://192.168.1.1:5173/\n'));
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      // Should keep the first detected URL
+      const serverInfo = service.getServerInfo(testDir);
+      expect(serverInfo?.url).toBe(firstUrl);
+      expect(serverInfo?.url).toBe('http://localhost:5173/');
+    });
+  });
 });
 
 // Helper to create a mock child process