fix: singleton services + comprehensive test suite for MCP server

- Fix ExecutionService singleton: build_stop/get_progress/get_logs now
  share state with build_start via module-level lazy singleton
- Fix MemoryService singleton: cached Graphiti connection preserved
  across tool calls instead of re-initializing each time
- Fix MemoryService private API: use public get_relevant_context()
  instead of private _search attribute
- Add 380 tests across 12 test files covering all MCP server modules:
  config, operations, server, tasks, specs, execution, QA, workspace,
  project, ops, github, and feature tools (insights/roadmap/ideation/memory)

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

.husky/pre-commit

@@ -127,6 +127,13 @@ fi
 if git diff --cached --name-only | grep -q "^apps/backend/.*\.py$"; then
   echo "Python changes detected, running backend checks..."
 
+  # Detect if we're in a worktree
+  IS_WORKTREE=false
+  if [ -f ".git" ]; then
+    # .git is a file (not directory) in worktrees
+    IS_WORKTREE=true
+  fi
+
   # Determine ruff command (venv or global)
   RUFF=""
   if [ -f "apps/backend/.venv/bin/ruff" ]; then
@@ -158,7 +165,16 @@ if git diff --cached --name-only | grep -q "^apps/backend/.*\.py$"; then
       echo "$STAGED_PY_FILES" | xargs git add
     fi
   else
-    echo "Warning: ruff not found, skipping Python linting. Install with: uv pip install ruff"
+    if [ "$IS_WORKTREE" = true ]; then
+      echo ""
+      echo "⚠️  WARNING: ruff not available in this worktree."
+      echo "   Python linting checks will be skipped."
+      echo "   This is expected for auto-claude worktrees."
+      echo "   Full validation will occur when PR is created/merged."
+      echo ""
+    else
+      echo "Warning: ruff not found, skipping Python linting. Install with: uv pip install ruff"
+    fi
   fi
 
   # Run pytest (skip slow/integration tests and Windows-incompatible tests for pre-commit speed)
@@ -192,17 +208,28 @@ if git diff --cached --name-only | grep -q "^apps/backend/.*\.py$"; then
     elif [ -d "apps/backend/.venv" ]; then
       echo "Warning: venv exists but Python not found in it, using system Python"
       PYTHONPATH=apps/backend python -m pytest tests/ -v --tb=short -x -m "not slow and not integration" -k "not windows_path" $IGNORE_TESTS
+    elif [ "$IS_WORKTREE" = true ]; then
+      echo ""
+      echo "⚠️  WARNING: Python venv not available in this worktree."
+      echo "   Python tests will be skipped."
+      echo "   This is expected for auto-claude worktrees."
+      echo "   Full validation will occur when PR is created/merged."
+      echo ""
+      exit 77  # GNU convention for 'test skipped' (avoids pytest exit-code collision)
     else
       echo "Warning: No .venv found in apps/backend, using system Python"
       PYTHONPATH=apps/backend python -m pytest tests/ -v --tb=short -x -m "not slow and not integration" -k "not windows_path" $IGNORE_TESTS
     fi
   )
-  if [ $? -ne 0 ]; then
+  PYTHON_EXIT=$?
+  if [ $PYTHON_EXIT -eq 77 ]; then
+    echo "Backend checks passed! (Python tests skipped — worktree)"
+  elif [ $PYTHON_EXIT -ne 0 ]; then
     echo "Python tests failed. Please fix failing tests before committing."
     exit 1
+  else
+    echo "Backend checks passed!"
   fi
-
-  echo "Backend checks passed!"
 fi
 
 # =============================================================================

.pre-commit-config.yaml

@@ -97,9 +97,8 @@ repos:
       - id: ruff-format
         files: ^apps/backend/
 
-  # Python tests (apps/backend/) - skip slow/integration tests for pre-commit speed
+  # Python tests (apps/backend/) - run full test suite from project root
   # Tests to skip: graphiti (external deps), merge_file_tracker/service_orchestrator/worktree/workspace (Windows path/git issues)
-  # NOTE: Skip this hook in worktrees (where .git is a file, not a directory)
   - repo: local
     hooks:
       - id: pytest
@@ -108,31 +107,24 @@ repos:
         args:
           - -c
           - |
-            # Skip in worktrees - .git is a file pointing to main repo, not a directory
-            # This prevents path resolution issues with ../../tests/ in worktree context
-            if [ -f ".git" ]; then
-              echo "Skipping pytest in worktree (path resolution would fail)"
-              exit 0
-            fi
-            cd apps/backend
-            if [ -f ".venv/bin/pytest" ]; then
-              PYTEST_CMD=".venv/bin/pytest"
-            elif [ -f ".venv/Scripts/pytest.exe" ]; then
-              PYTEST_CMD=".venv/Scripts/pytest.exe"
+            # Run pytest directly from project root
+            if [ -f "apps/backend/.venv/bin/pytest" ]; then
+              PYTEST_CMD="apps/backend/.venv/bin/pytest"
+            elif [ -f "apps/backend/.venv/Scripts/pytest.exe" ]; then
+              PYTEST_CMD="apps/backend/.venv/Scripts/pytest.exe"
             else
               PYTEST_CMD="python -m pytest"
             fi
-            PYTHONPATH=. $PYTEST_CMD \
-              ../../tests/ \
+            $PYTEST_CMD tests/ \
               -v \
               --tb=short \
               -x \
               -m "not slow and not integration" \
-              --ignore=../../tests/test_graphiti.py \
-              --ignore=../../tests/test_merge_file_tracker.py \
-              --ignore=../../tests/test_service_orchestrator.py \
-              --ignore=../../tests/test_worktree.py \
-              --ignore=../../tests/test_workspace.py
+              --ignore=tests/test_graphiti.py \
+              --ignore=tests/test_merge_file_tracker.py \
+              --ignore=tests/test_service_orchestrator.py \
+              --ignore=tests/test_worktree.py \
+              --ignore=tests/test_workspace.py
         language: system
         files: ^(apps/backend/.*\.py$|tests/.*\.py$)
         pass_filenames: false

CLAUDE.md

@@ -52,6 +52,15 @@ Auto Claude is a desktop application (+ CLI) where users describe a goal and AI
 
 **Electron path resolution** — For bug fixes in the Electron app, always check path resolution differences between dev and production builds (`app.isPackaged`, `process.resourcesPath`). Paths that work in dev often break when Electron is bundled for production — verify both contexts.
 
+### Resetting PR Review State
+
+To fully clear all PR review data so reviews run fresh, delete/reset these three things in `.auto-claude/github/`:
+
+1. `rm .auto-claude/github/pr/logs_*.json` — review log files
+2. `rm .auto-claude/github/pr/review_*.json` — review result files
+3. Reset `pr/index.json` to `{"reviews": [], "last_updated": null}`
+4. Reset `bot_detection_state.json` to `{"reviewed_commits": {}}` — this is the gatekeeper; without clearing it, the bot detector skips already-seen commits
+
 ## Project Structure
 
 ```

README.md

@@ -8,6 +8,7 @@
 [![Discord](https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/KCXaPBr4Dj)
 [![YouTube](https://img.shields.io/badge/YouTube-Subscribe-FF0000?style=flat-square&logo=youtube&logoColor=white)](https://www.youtube.com/@AndreMikalsen)
 [![CI](https://img.shields.io/github/actions/workflow/status/AndyMik90/Auto-Claude/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/AndyMik90/Auto-Claude/actions)
+[![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/hesreallyhim/awesome-claude-code)
 
 ---
 
@@ -35,18 +36,18 @@
 > ⚠️ Beta releases may contain bugs and breaking changes. [View all releases](https://github.com/AndyMik90/Auto-Claude/releases)
 
 <!-- BETA_VERSION_BADGE -->
-[![Beta](https://img.shields.io/badge/beta-2.7.6--beta.4-orange?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.6-beta.4)
+[![Beta](https://img.shields.io/badge/beta-2.7.6--beta.5-orange?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.6-beta.5)
 <!-- BETA_VERSION_BADGE_END -->
 
 <!-- BETA_DOWNLOADS -->
 | Platform | Download |
 |----------|----------|
-| **Windows** | [Auto-Claude-2.7.6-beta.4-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.4/Auto-Claude-2.7.6-beta.4-win32-x64.exe) |
-| **macOS (Apple Silicon)** | [Auto-Claude-2.7.6-beta.4-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.4/Auto-Claude-2.7.6-beta.4-darwin-arm64.dmg) |
-| **macOS (Intel)** | [Auto-Claude-2.7.6-beta.4-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.4/Auto-Claude-2.7.6-beta.4-darwin-x64.dmg) |
-| **Linux** | [Auto-Claude-2.7.6-beta.4-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.4/Auto-Claude-2.7.6-beta.4-linux-x86_64.AppImage) |
-| **Linux (Debian)** | [Auto-Claude-2.7.6-beta.4-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.4/Auto-Claude-2.7.6-beta.4-linux-amd64.deb) |
-| **Linux (Flatpak)** | [Auto-Claude-2.7.6-beta.4-linux-x86_64.flatpak](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.4/Auto-Claude-2.7.6-beta.4-linux-x86_64.flatpak) |
+| **Windows** | [Auto-Claude-2.7.6-beta.5-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.5/Auto-Claude-2.7.6-beta.5-win32-x64.exe) |
+| **macOS (Apple Silicon)** | [Auto-Claude-2.7.6-beta.5-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.5/Auto-Claude-2.7.6-beta.5-darwin-arm64.dmg) |
+| **macOS (Intel)** | [Auto-Claude-2.7.6-beta.5-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.5/Auto-Claude-2.7.6-beta.5-darwin-x64.dmg) |
+| **Linux** | [Auto-Claude-2.7.6-beta.5-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.5/Auto-Claude-2.7.6-beta.5-linux-x86_64.AppImage) |
+| **Linux (Debian)** | [Auto-Claude-2.7.6-beta.5-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.5/Auto-Claude-2.7.6-beta.5-linux-amd64.deb) |
+| **Linux (Flatpak)** | [Auto-Claude-2.7.6-beta.5-linux-x86_64.flatpak](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.5/Auto-Claude-2.7.6-beta.5-linux-x86_64.flatpak) |
 <!-- BETA_DOWNLOADS_END -->
 
 > All releases include SHA256 checksums and VirusTotal scan results for security verification.

apps/backend/.gitignore

@@ -67,4 +67,9 @@ tests/
 
 # Auto Claude data directory
 .auto-claude/
-coverage.json
+
+# Auto Claude generated files
+.auto-claude-security.json
+.auto-claude-status
+.security-key
+logs/security/

apps/backend/__init__.py

@@ -19,5 +19,5 @@ Quick Start:
 See README.md for full documentation.
 """
 
-__version__ = "2.7.6-beta.4"
+__version__ = "2.7.6-beta.5"
 __author__ = "Auto Claude Team"

apps/backend/analysis/analyzers/project_analyzer_module.py

@@ -31,6 +31,7 @@ class ProjectAnalyzer:
         """Run full project analysis."""
         self._detect_project_type()
         self._find_and_analyze_services()
+        self._aggregate_dependency_locations()
         self._analyze_infrastructure()
         self._detect_conventions()
         self._map_dependencies()
@@ -124,6 +125,63 @@ class ProjectAnalyzer:
 
         self.index["services"] = services
 
+    def _aggregate_dependency_locations(self) -> None:
+        """Aggregate dependency location metadata from all services.
+
+        Collects dependency_locations from each service and stores them as
+        paths relative to the project root (e.g., 'apps/backend/.venv'
+        instead of just '.venv').
+        """
+        aggregated: list[dict[str, Any]] = []
+
+        for service_name, service_info in self.index.get("services", {}).items():
+            service_deps = service_info.get("dependency_locations", [])
+            service_path = service_info.get("path", "")
+
+            # Compute service-relative prefix once per service
+            service_rel: Path | None = None
+            if service_path:
+                try:
+                    service_rel = Path(service_path).relative_to(self.project_dir)
+                except ValueError:
+                    # Service path is outside the project root — skip its deps
+                    # to avoid producing absolute paths that bypass containment
+                    continue
+
+            for dep in service_deps:
+                dep_path = dep.get("path")
+                if not dep_path:
+                    continue
+
+                # Build project-relative path from service path + dep path
+                if service_rel is not None:
+                    project_relative = str(service_rel / dep_path)
+                else:
+                    project_relative = dep_path
+
+                entry: dict[str, Any] = {
+                    "type": dep.get("type", "unknown"),
+                    "path": project_relative,
+                    "exists": dep.get("exists", False),
+                    "service": service_name,
+                }
+                if dep.get("requirements_file"):
+                    # Convert to project-relative path like we do for "path"
+                    if service_rel is not None:
+                        entry["requirements_file"] = str(
+                            service_rel / dep["requirements_file"]
+                        )
+                    else:
+                        entry["requirements_file"] = dep["requirements_file"]
+                pkg_mgr = dep.get("package_manager") or service_info.get(
+                    "package_manager"
+                )
+                if pkg_mgr:
+                    entry["package_manager"] = pkg_mgr
+                aggregated.append(entry)
+
+        self.index["dependency_locations"] = aggregated
+
     def _analyze_infrastructure(self) -> None:
         """Analyze infrastructure configuration."""
         infra = {}

apps/backend/analysis/analyzers/service_analyzer.py

@@ -40,6 +40,8 @@ class ServiceAnalyzer(BaseAnalyzer):
         self._find_key_directories()
         self._find_entry_points()
         self._detect_dependencies()
+        self._detect_dependency_locations()
+        self._detect_package_manager()
         self._detect_testing()
         self._find_dockerfile()
 
@@ -209,6 +211,121 @@ class ServiceAnalyzer(BaseAnalyzer):
                         deps.append(match.group(1))
             self.analysis["dependencies"] = deps[:20]
 
+    def _detect_dependency_locations(self) -> None:
+        """Detect where dependencies live on disk for this service."""
+        locations: list[dict[str, Any]] = []
+
+        # Node.js: node_modules (only if package.json exists)
+        if self._exists("package.json"):
+            node_modules = self.path / "node_modules"
+            locations.append(
+                {
+                    "type": "node_modules",
+                    "path": "node_modules",
+                    "exists": node_modules.exists() and node_modules.is_dir(),
+                }
+            )
+
+        # Python: .venv or venv
+        for venv_dir in [".venv", "venv"]:
+            venv_path = self.path / venv_dir
+            if venv_path.exists() and venv_path.is_dir():
+                entry: dict[str, Any] = {
+                    "type": "venv",
+                    "path": venv_dir,
+                    "exists": True,
+                }
+                # Find requirements file
+                for req_file in ["requirements.txt", "pyproject.toml", "Pipfile"]:
+                    if self._exists(req_file):
+                        entry["requirements_file"] = req_file
+                        break
+                locations.append(entry)
+                break
+        else:
+            # No venv found, still record requirements file if present
+            for req_file in ["requirements.txt", "pyproject.toml", "Pipfile"]:
+                if self._exists(req_file):
+                    locations.append(
+                        {
+                            "type": "venv",
+                            "path": ".venv",
+                            "exists": False,
+                            "requirements_file": req_file,
+                        }
+                    )
+                    break
+
+        # PHP: vendor
+        vendor_path = self.path / "vendor"
+        if vendor_path.exists() and vendor_path.is_dir():
+            locations.append(
+                {
+                    "type": "vendor_php",
+                    "path": "vendor",
+                    "exists": True,
+                }
+            )
+
+        # Rust: target
+        target_path = self.path / "target"
+        if target_path.exists() and target_path.is_dir():
+            locations.append(
+                {
+                    "type": "cargo_target",
+                    "path": "target",
+                    "exists": True,
+                }
+            )
+
+        # Ruby: vendor/bundle
+        bundle_path = self.path / "vendor" / "bundle"
+        if bundle_path.exists() and bundle_path.is_dir():
+            locations.append(
+                {
+                    "type": "vendor_bundle",
+                    "path": "vendor/bundle",
+                    "exists": True,
+                }
+            )
+
+        self.analysis["dependency_locations"] = locations
+
+    def _detect_package_manager(self) -> None:
+        """Detect the package manager used by this service."""
+        # Node.js package managers
+        if self._exists("package-lock.json"):
+            self.analysis["package_manager"] = "npm"
+        elif self._exists("yarn.lock"):
+            self.analysis["package_manager"] = "yarn"
+        elif self._exists("pnpm-lock.yaml"):
+            self.analysis["package_manager"] = "pnpm"
+        elif self._exists("bun.lockb") or self._exists("bun.lock"):
+            self.analysis["package_manager"] = "bun"
+        # Python package managers
+        elif self._exists("Pipfile"):
+            self.analysis["package_manager"] = "pipenv"
+        elif self._exists("pyproject.toml"):
+            if self._exists("uv.lock"):
+                self.analysis["package_manager"] = "uv"
+            elif self._exists("poetry.lock"):
+                self.analysis["package_manager"] = "poetry"
+            else:
+                self.analysis["package_manager"] = "pip"
+        elif self._exists("requirements.txt"):
+            self.analysis["package_manager"] = "pip"
+        # Other
+        elif self._exists("Cargo.toml"):
+            self.analysis["package_manager"] = "cargo"
+        elif self._exists("go.mod"):
+            self.analysis["package_manager"] = "go_mod"
+        elif self._exists("Gemfile"):
+            self.analysis["package_manager"] = "gem"
+        elif self._exists("composer.json"):
+            self.analysis["package_manager"] = "composer"
+        else:
+            self.analysis["package_manager"] = None
+
     def _detect_testing(self) -> None:
         """Detect testing framework and configuration."""
         if self._exists("package.json"):

apps/backend/cli/batch_commands.py

@@ -10,6 +10,7 @@ import shutil
 import subprocess
 from pathlib import Path
 
+from qa.criteria import is_fixes_applied, is_qa_approved, is_qa_rejected
 from ui import highlight, print_status
 
 
@@ -151,13 +152,22 @@ def handle_batch_status_command(project_dir: str) -> bool:
             except json.JSONDecodeError:
                 pass
 
-        # Determine status
-        if (spec_dir / "spec.md").exists():
-            status = "spec_created"
-        elif (spec_dir / "implementation_plan.json").exists():
-            status = "building"
-        elif (spec_dir / "qa_report.md").exists():
+        # Determine status (highest priority first)
+        # Use authoritative QA status check, not just file existence
+        if is_qa_approved(spec_dir):
             status = "qa_approved"
+        elif is_qa_rejected(spec_dir):
+            status = "qa_rejected"
+        elif is_fixes_applied(spec_dir):
+            status = "fixes_applied"
+        elif (spec_dir / "implementation_plan.json").exists():
+            # Check if there's a qa_report.md but no approval yet (QA in progress)
+            if (spec_dir / "qa_report.md").exists():
+                status = "qa_in_progress"
+            else:
+                status = "building"
+        elif (spec_dir / "spec.md").exists():
+            status = "spec_created"
         else:
             status = "pending_spec"
 
@@ -165,7 +175,10 @@ def handle_batch_status_command(project_dir: str) -> bool:
             "pending_spec": "⏳",
             "spec_created": "📋",
             "building": "⚙️",
+            "qa_in_progress": "🔍",
             "qa_approved": "✅",
+            "qa_rejected": "❌",
+            "fixes_applied": "🔧",
             "unknown": "❓",
         }.get(status, "❓")
 
@@ -192,10 +205,10 @@ def handle_batch_cleanup_command(project_dir: str, dry_run: bool = True) -> bool
         print_status("No specs directory found", "info")
         return True
 
-    # Find completed specs
+    # Find completed specs (only QA-approved, matching status display logic)
     completed = []
     for spec_dir in specs_dir.iterdir():
-        if spec_dir.is_dir() and (spec_dir / "qa_report.md").exists():
+        if spec_dir.is_dir() and is_qa_approved(spec_dir):
             completed.append(spec_dir.name)
 
     if not completed:

apps/backend/cli/build_commands.py

@@ -449,7 +449,7 @@ def _handle_build_interrupt(
         if choice == "skip":
             print()
             print_status("Resuming build...", "info")
-            status_manager.update(state=BuildState.RUNNING)
+            status_manager.update(state=BuildState.BUILDING)
             asyncio.run(
                 run_autonomous_agent(
                     project_dir=working_dir,

apps/backend/core/auth.py

@@ -694,10 +694,25 @@ def get_auth_token(config_dir: str | None = None) -> str | None:
     Returns:
         Token string if found, None otherwise
     """
+    _debug = os.environ.get("DEBUG", "").lower() in ("true", "1")
+
+    if _debug:
+        # Log which auth env vars are set (presence only, never values)
+        set_vars = [v for v in AUTH_TOKEN_ENV_VARS if os.environ.get(v)]
+        logger.info(
+            "[Auth] get_auth_token() called — config_dir param=%s, "
+            "env vars present: %s, CLAUDE_CONFIG_DIR env=%s",
+            repr(config_dir),
+            set_vars or "(none)",
+            "set" if os.environ.get("CLAUDE_CONFIG_DIR") else "unset",
+        )
+
     # First check environment variables (highest priority)
     for var in AUTH_TOKEN_ENV_VARS:
         token = os.environ.get(var)
         if token:
+            if _debug:
+                logger.info("[Auth] Token resolved from env var: %s", var)
             return _try_decrypt_token(token)
 
     # Check CLAUDE_CONFIG_DIR environment variable (profile's custom config directory)
@@ -705,12 +720,13 @@ def get_auth_token(config_dir: str | None = None) -> str | None:
     effective_config_dir = config_dir or env_config_dir
 
     # Debug: Log which config_dir is being used for credential resolution
-    debug = os.environ.get("DEBUG", "").lower() in ("true", "1")
-    if debug and effective_config_dir:
+    if _debug and effective_config_dir:
         service_name = _get_keychain_service_name(effective_config_dir)
         logger.info(
-            f"[Auth] Resolving credentials for profile config_dir: {effective_config_dir} "
-            f"(Keychain service: {service_name})"
+            "[Auth] Resolving credentials for profile config_dir: %s "
+            "(Keychain service: %s)",
+            effective_config_dir,
+            service_name,
         )
 
     # If a custom config directory is specified, read from there first
@@ -718,24 +734,37 @@ def get_auth_token(config_dir: str | None = None) -> str | None:
         # Try reading from .credentials.json file in the config directory
         token = _get_token_from_config_dir(effective_config_dir)
         if token:
+            if _debug:
+                logger.info(
+                    "[Auth] Token resolved from config dir file: %s",
+                    effective_config_dir,
+                )
             return _try_decrypt_token(token)
 
         # Also try the system credential store with hash-based service name
         # This is needed because macOS stores credentials in Keychain, not files
         token = get_token_from_keychain(effective_config_dir)
         if token:
+            if _debug:
+                logger.info("[Auth] Token resolved from Keychain (profile-specific)")
             return _try_decrypt_token(token)
 
         # If config_dir was explicitly provided, DON'T fall back to default keychain
         # - that would return the wrong profile's token
         logger.debug(
-            f"No credentials found for config_dir '{effective_config_dir}' "
-            "in file or keychain"
+            "No credentials found for config_dir '%s' in file or keychain",
+            effective_config_dir,
         )
         return None
 
     # No config_dir specified - use default system credential store
-    return _try_decrypt_token(get_token_from_keychain())
+    keychain_token = get_token_from_keychain()
+    if _debug:
+        logger.info(
+            "[Auth] Token resolved from default Keychain: %s",
+            "found" if keychain_token else "not found",
+        )
+    return _try_decrypt_token(keychain_token)
 
 
 def get_auth_token_source(config_dir: str | None = None) -> str | None:
@@ -970,8 +999,18 @@ def configure_sdk_authentication(config_dir: str | None = None) -> None:
                    - API profile mode: requires ANTHROPIC_AUTH_TOKEN
                    - OAuth mode: requires CLAUDE_CODE_OAUTH_TOKEN (from Keychain or env)
     """
+    _debug = os.environ.get("DEBUG", "").lower() in ("true", "1")
     api_profile_mode = bool(os.environ.get("ANTHROPIC_BASE_URL", "").strip())
 
+    if _debug:
+        logger.info(
+            "[Auth] configure_sdk_authentication() — mode=%s, config_dir=%s, "
+            "CLAUDE_CONFIG_DIR env=%s",
+            "api_profile" if api_profile_mode else "oauth",
+            repr(config_dir),
+            "set" if os.environ.get("CLAUDE_CONFIG_DIR") else "unset",
+        )
+
     if api_profile_mode:
         # API profile mode: ensure ANTHROPIC_AUTH_TOKEN is present
         if not os.environ.get("ANTHROPIC_AUTH_TOKEN"):
@@ -999,6 +1038,14 @@ def configure_sdk_authentication(config_dir: str | None = None) -> None:
         os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = oauth_token
         logger.info("Using OAuth authentication")
 
+        if _debug:
+            logger.info(
+                "[Auth] SDK env check — CLAUDE_CONFIG_DIR=%s, "
+                "CLAUDE_CODE_OAUTH_TOKEN=%s",
+                "set" if os.environ.get("CLAUDE_CONFIG_DIR") else "unset",
+                "set" if os.environ.get("CLAUDE_CODE_OAUTH_TOKEN") else "unset",
+            )
+
 
 def ensure_claude_code_oauth_token() -> None:
     """

apps/backend/core/progress.py

@@ -9,8 +9,11 @@ Enhanced with colored output, icons, and better visual formatting.
 """
 
 import json
+import logging
 from pathlib import Path
 
+logger = logging.getLogger(__name__)
+
 from core.plan_normalization import normalize_subtask_aliases
 from ui import (
     Icons,
@@ -230,8 +233,8 @@ def print_progress_summary(spec_dir: Path, show_next: bool = True) -> None:
                         f"  {icon(Icons.ARROW_RIGHT)} Next: {highlight(next_id)} - {next_desc}"
                     )
 
-        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
-            pass  # Ignore corrupted/unreadable progress files
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError) as e:
+            logger.debug(f"Failed to load plan file for phase summary: {e}")
     else:
         print()
         print_status("No implementation subtasks yet - planner needs to run", "pending")
@@ -404,6 +407,8 @@ def get_next_subtask(spec_dir: Path) -> dict | None:
     """
     Find the next subtask to work on, respecting phase dependencies.
 
+    Skips subtasks that are marked as stuck in the recovery manager's attempt history.
+
     Args:
         spec_dir: Directory containing implementation_plan.json
 
@@ -415,6 +420,23 @@ def get_next_subtask(spec_dir: Path) -> dict | None:
     if not plan_file.exists():
         return None
 
+    # Load stuck subtasks from recovery manager's attempt history
+    stuck_subtask_ids = set()
+    attempt_history_file = spec_dir / "memory" / "attempt_history.json"
+    if attempt_history_file.exists():
+        try:
+            with open(attempt_history_file, encoding="utf-8") as f:
+                attempt_history = json.load(f)
+            # Collect IDs of subtasks marked as stuck
+            stuck_subtask_ids = {
+                entry["subtask_id"]
+                for entry in attempt_history.get("stuck_subtasks", [])
+                if "subtask_id" in entry
+            }
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+            # If we can't read the file, continue without stuck checking
+            pass
+
     try:
         with open(plan_file, encoding="utf-8") as f:
             plan = json.load(f)
@@ -455,9 +477,15 @@ def get_next_subtask(spec_dir: Path) -> dict | None:
             if not deps_satisfied:
                 continue
 
-            # Find first pending subtask in this phase
+            # Find first pending subtask in this phase (skip stuck subtasks)
             for subtask in phase.get("subtasks", phase.get("chunks", [])):
                 status = subtask.get("status", "pending")
+                subtask_id = subtask.get("id")
+
+                # Skip stuck subtasks
+                if subtask_id in stuck_subtask_ids:
+                    continue
+
                 if status in {"pending", "not_started", "not started"}:
                     subtask_out, _changed = normalize_subtask_aliases(subtask)
                     subtask_out["status"] = "pending"

apps/backend/core/workspace/dependency_strategy.py

@@ -0,0 +1,176 @@
+"""
+Dependency Strategy Mapping
+============================
+
+Maps dependency types to sharing strategies for worktree creation.
+
+Each dependency ecosystem has different constraints:
+
+- **node_modules**: Safe to symlink. Node's resolution algorithm follows symlinks
+  correctly, and the directory is self-contained.
+
+- **venv / .venv**: Must be recreated. Python's ``pyvenv.cfg`` discovery walks the
+  real directory hierarchy without resolving symlinks (CPython bug #106045), so a
+  symlinked venv resolves paths relative to the *target*, not the worktree.
+
+- **vendor (PHP)**: Safe to symlink. Composer's autoloader uses ``__DIR__``-relative
+  paths that resolve correctly through symlinks.
+
+- **cargo target / go modules**: Skip entirely. Rust's ``target/`` dir contains
+  per-machine build artifacts that must be rebuilt. Go uses a global module cache
+  (``$GOPATH/pkg/mod``), so there is nothing in-tree to share.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path, PurePosixPath, PureWindowsPath
+
+logger = logging.getLogger(__name__)
+
+from .models import DependencyShareConfig, DependencyStrategy
+
+# ---------------------------------------------------------------------------
+# Default strategy map
+# ---------------------------------------------------------------------------
+# Maps dependency type identifiers to the strategy that should be used when
+# sharing that dependency across worktrees.  Data-driven — add new entries
+# here rather than writing if/else branches.
+# ---------------------------------------------------------------------------
+
+DEFAULT_STRATEGY_MAP: dict[str, DependencyStrategy] = {
+    # JavaScript / Node.js — symlink is safe and fast
+    "node_modules": DependencyStrategy.SYMLINK,
+    # Python — venvs MUST be recreated (pyvenv.cfg symlink bug)
+    "venv": DependencyStrategy.RECREATE,
+    ".venv": DependencyStrategy.RECREATE,
+    # PHP — Composer vendor dir is safe to symlink
+    "vendor_php": DependencyStrategy.SYMLINK,
+    # Ruby — Bundler vendor/bundle is safe to symlink
+    "vendor_bundle": DependencyStrategy.SYMLINK,
+    # Rust — build output dir, skip (rebuilt per-worktree)
+    "cargo_target": DependencyStrategy.SKIP,
+    # Go — global module cache, nothing in-tree to share
+    "go_modules": DependencyStrategy.SKIP,
+}
+
+
+def get_dependency_configs(
+    project_index: dict | None,
+    project_dir: Path | None = None,
+) -> list[DependencyShareConfig]:
+    """Derive dependency share configs from a project index.
+
+    If *project_index* is ``None`` or lacks ``dependency_locations``,
+    falls back to a hardcoded node_modules config for backward compatibility
+    with existing worktree setups.
+
+    Args:
+        project_index: Parsed ``project_index.json`` dict, or ``None``.
+        project_dir: Project root directory for resolved-path containment
+            checks (defense-in-depth).  Should always be provided when
+            *project_index* is not ``None`` — omitting it disables the
+            resolved-path security check.
+
+    Returns:
+        List of :class:`DependencyShareConfig` objects — one per discovered
+        dependency location.
+    """
+
+    configs: list[DependencyShareConfig] = []
+    seen: set[str] = set()
+
+    if project_index is not None:
+        if project_dir is None:
+            logger.warning(
+                "get_dependency_configs called with project_index but no "
+                "project_dir — resolved-path containment check is disabled"
+            )
+
+        # Use the aggregated top-level dependency_locations which already
+        # contain project-relative paths (e.g. "apps/backend/.venv" instead
+        # of just ".venv").  This avoids a monorepo path resolution bug
+        # where service-relative paths were incorrectly treated as project-
+        # relative.
+        dep_locations = project_index.get("dependency_locations") or []
+        for dep in dep_locations:
+            if not isinstance(dep, dict):
+                continue
+
+            dep_type = dep.get("type", "")
+            rel_path = dep.get("path", "")
+
+            if not dep_type or not rel_path:
+                continue
+
+            # Path containment: reject absolute paths and traversals.
+            # Check both POSIX and Windows path styles for cross-platform safety.
+            p = PurePosixPath(rel_path)
+            if p.is_absolute() or PureWindowsPath(rel_path).is_absolute():
+                continue
+            if ".." in p.parts or ".." in PureWindowsPath(rel_path).parts:
+                continue
+
+            # Defense-in-depth: verify the resolved path stays within project_dir
+            if project_dir is not None:
+                resolved = (project_dir / rel_path).resolve()
+                if not str(resolved).startswith(str(project_dir.resolve()) + os.sep):
+                    continue
+
+            # Deduplicate by relative path
+            if rel_path in seen:
+                continue
+            seen.add(rel_path)
+
+            strategy = DEFAULT_STRATEGY_MAP.get(dep_type, DependencyStrategy.SKIP)
+
+            # Validate requirements_file path containment too
+            req_file = dep.get("requirements_file")
+            if req_file:
+                rp = PurePosixPath(req_file)
+                if (
+                    rp.is_absolute()
+                    or PureWindowsPath(req_file).is_absolute()
+                    or ".." in rp.parts
+                    or ".." in PureWindowsPath(req_file).parts
+                ):
+                    req_file = None
+
+                # Defense-in-depth: resolved-path containment (matches rel_path check)
+                if req_file and project_dir is not None:
+                    resolved_req = (project_dir / req_file).resolve()
+                    if not str(resolved_req).startswith(
+                        str(project_dir.resolve()) + os.sep
+                    ):
+                        req_file = None
+
+            configs.append(
+                DependencyShareConfig(
+                    dep_type=dep_type,
+                    strategy=strategy,
+                    source_rel_path=rel_path,
+                    requirements_file=req_file,
+                    package_manager=dep.get("package_manager"),
+                )
+            )
+
+    # Fallback: if no configs were discovered, default to node_modules-only
+    # so existing worktree behaviour is preserved.
+    if not configs:
+        configs.append(
+            DependencyShareConfig(
+                dep_type="node_modules",
+                strategy=DependencyStrategy.SYMLINK,
+                source_rel_path="node_modules",
+            )
+        )
+        configs.append(
+            DependencyShareConfig(
+                dep_type="node_modules",
+                strategy=DependencyStrategy.SYMLINK,
+                source_rel_path="apps/frontend/node_modules",
+            )
+        )
+
+    return configs

apps/backend/core/workspace/models.py

@@ -273,3 +273,31 @@ class SpecNumberLock:
                 pass
 
         return max_num
+
+
+class DependencyStrategy(Enum):
+    """Strategy for sharing dependency directories across worktrees.
+
+    SYMLINK is fast but unsafe for certain ecosystems. Notably, Python venv
+    breaks when symlinked because CPython's pyvenv.cfg discovery walks the
+    real directory hierarchy without resolving symlinks first
+    (CPython bug #106045). This means a symlinked venv resolves its home
+    path relative to the symlink target's parent, not the worktree, causing
+    import failures and broken interpreters.
+    """
+
+    SYMLINK = "symlink"  # Create a symlink to the source (fast, works for node_modules)
+    RECREATE = "recreate"  # Re-run the package manager to create a fresh copy
+    COPY = "copy"  # Deep-copy the directory (slow but always correct)
+    SKIP = "skip"  # Do nothing; let the agent handle it
+
+
+@dataclass
+class DependencyShareConfig:
+    """Configuration for how a specific dependency type should be shared."""
+
+    dep_type: str  # e.g. "node_modules", "venv", ".venv"
+    strategy: DependencyStrategy
+    source_rel_path: str  # Relative path from project root, e.g. "node_modules"
+    requirements_file: str | None = None  # e.g. "requirements.txt", "pyproject.toml"
+    package_manager: str | None = None  # e.g. "npm", "uv", "pip"

apps/backend/core/workspace/setup.py

@@ -14,6 +14,7 @@ import sys
 from pathlib import Path
 
 from core.git_executable import run_git
+from core.platform import is_windows
 from merge import FileTimelineTracker
 from security.constants import ALLOWLIST_FILENAME, PROFILE_FILENAME
 from ui import (
@@ -28,8 +29,9 @@ from ui import (
 )
 from worktree import WorktreeManager
 
+from .dependency_strategy import get_dependency_configs
 from .git_utils import has_uncommitted_changes
-from .models import WorkspaceMode
+from .models import DependencyShareConfig, DependencyStrategy, WorkspaceMode
 
 # Import debug utilities
 try:
@@ -189,11 +191,37 @@ def symlink_node_modules_to_worktree(
     """
     Symlink node_modules directories from project root to worktree.
 
-    This ensures the worktree has access to dependencies for TypeScript checks
-    and other tooling without requiring a separate npm install.
+    .. deprecated::
+        Use :func:`setup_worktree_dependencies` instead, which handles all
+        dependency types (node_modules, venvs, vendor dirs, etc.) via
+        strategy-based dispatch.
 
-    Works with npm workspace hoisting where dependencies are hoisted to root
-    and workspace-specific dependencies remain in nested node_modules.
+    This is a thin backward-compatibility wrapper that delegates to
+    ``setup_worktree_dependencies()`` with no project index (fallback mode).
+
+    Args:
+        project_dir: The main project directory
+        worktree_path: Path to the worktree
+
+    Returns:
+        List of symlinked paths (relative to worktree)
+    """
+    results = setup_worktree_dependencies(
+        project_dir, worktree_path, project_index=None
+    )
+    # Flatten all processed paths for backward-compatible return value
+    return [path for paths in results.values() for path in paths]
+
+
+def symlink_claude_config_to_worktree(
+    project_dir: Path, worktree_path: Path
+) -> list[str]:
+    """
+    Symlink .claude/ directory from project root to worktree.
+
+    This ensures the worktree has access to Claude Code configuration
+    (settings, CLAUDE.md, MCP servers, etc.) so that terminals opened
+    in the worktree behave identically to the project root.
 
     Args:
         project_dir: The main project directory
@@ -204,81 +232,52 @@ def symlink_node_modules_to_worktree(
     """
     symlinked = []
 
-    # Node modules locations to symlink for TypeScript and tooling support.
-    # These are the standard locations for this monorepo structure.
-    #
-    # Design rationale:
-    # - Hardcoded paths are intentional for simplicity and reliability
-    # - Dynamic discovery (reading workspaces from package.json) would add complexity
-    #   and potential failure points without significant benefit
-    # - This monorepo uses npm workspaces with hoisting, so dependencies are primarily
-    #   in root node_modules with workspace-specific deps in apps/frontend/node_modules
-    #
-    # To add new workspace locations:
-    # 1. Add (source_rel, target_rel) tuple below
-    # 2. Update the parallel TypeScript implementation in
-    #    apps/frontend/src/main/ipc-handlers/terminal/worktree-handlers.ts
-    # 3. Update the pre-commit hook check in .husky/pre-commit if needed
-    node_modules_locations = [
-        ("node_modules", "node_modules"),
-        ("apps/frontend/node_modules", "apps/frontend/node_modules"),
-    ]
+    source_path = project_dir / ".claude"
+    target_path = worktree_path / ".claude"
 
-    for source_rel, target_rel in node_modules_locations:
-        source_path = project_dir / source_rel
-        target_path = worktree_path / target_rel
+    # Skip if source doesn't exist
+    if not source_path.exists():
+        debug(MODULE, "Skipping .claude/ - source does not exist")
+        return symlinked
 
-        # Skip if source doesn't exist
-        if not source_path.exists():
-            debug(MODULE, f"Skipping {source_rel} - source does not exist")
-            continue
+    # Skip if target already exists
+    if target_path.exists():
+        debug(MODULE, "Skipping .claude/ - target already exists")
+        return symlinked
 
-        # Skip if target already exists (don't overwrite existing node_modules)
-        if target_path.exists():
-            debug(MODULE, f"Skipping {target_rel} - target already exists")
-            continue
+    # Also skip if target is a symlink (even if broken)
+    if target_path.is_symlink():
+        debug(MODULE, "Skipping .claude/ - symlink already exists (possibly broken)")
+        return symlinked
 
-        # Also skip if target is a symlink (even if broken - exists() returns False for broken symlinks)
-        if target_path.is_symlink():
-            debug(
-                MODULE,
-                f"Skipping {target_rel} - symlink already exists (possibly broken)",
-            )
-            continue
-
-        # Ensure parent directory exists
-        target_path.parent.mkdir(parents=True, exist_ok=True)
-
-        try:
-            if sys.platform == "win32":
-                # On Windows, use junctions instead of symlinks (no admin rights required)
-                # Junctions require absolute paths
-                result = subprocess.run(
-                    ["cmd", "/c", "mklink", "/J", str(target_path), str(source_path)],
-                    capture_output=True,
-                    text=True,
-                )
-                if result.returncode != 0:
-                    raise OSError(result.stderr or "mklink /J failed")
-            else:
-                # On macOS/Linux, use relative symlinks for portability
-                relative_source = os.path.relpath(source_path, target_path.parent)
-                os.symlink(relative_source, target_path)
-            symlinked.append(target_rel)
-            debug(MODULE, f"Symlinked {target_rel} -> {source_path}")
-        except OSError as e:
-            # Symlink/junction creation can fail on some systems (e.g., FAT32 filesystem)
-            # Log warning but don't fail - worktree is still usable, just without
-            # TypeScript checking
-            debug_warning(
-                MODULE,
-                f"Could not symlink {target_rel}: {e}. TypeScript checks may fail.",
-            )
-            # Warn user - pre-commit hooks may fail without dependencies
-            print_status(
-                f"Warning: Could not link {target_rel} - TypeScript checks may fail",
-                "warning",
+    # Ensure parent directory exists
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        if sys.platform == "win32":
+            # On Windows, use junctions instead of symlinks (no admin rights required)
+            result = subprocess.run(
+                ["cmd", "/c", "mklink", "/J", str(target_path), str(source_path)],
+                capture_output=True,
+                text=True,
             )
+            if result.returncode != 0:
+                raise OSError(result.stderr or "mklink /J failed")
+        else:
+            # On macOS/Linux, use relative symlinks for portability
+            relative_source = os.path.relpath(source_path, target_path.parent)
+            os.symlink(relative_source, target_path)
+        symlinked.append(".claude")
+        debug(MODULE, f"Symlinked .claude/ -> {source_path}")
+    except OSError as e:
+        debug_warning(
+            MODULE,
+            f"Could not symlink .claude/: {e}. Claude Code features may not work in worktree terminals.",
+        )
+        print_status(
+            "Warning: Could not link .claude/ - Claude Code features may not work in terminals",
+            "warning",
+        )
 
     return symlinked
 
@@ -374,13 +373,33 @@ def setup_workspace(
             f"Environment files copied: {', '.join(copied_env_files)}", "success"
         )
 
-    # Symlink node_modules to worktree for TypeScript and tooling support
-    # This allows pre-commit hooks to run typecheck without npm install in worktree
-    symlinked_modules = symlink_node_modules_to_worktree(
+    # Set up dependencies in worktree using strategy-based dispatch
+    # Load project index if available for ecosystem-aware dependency handling
+    project_index = None
+    project_index_path = project_dir / ".auto-claude" / "project_index.json"
+    if project_index_path.is_file():
+        try:
+            with open(project_index_path, encoding="utf-8") as f:
+                project_index = json.load(f)
+            debug(MODULE, "Loaded project_index.json for dependency setup")
+        except (OSError, json.JSONDecodeError) as e:
+            debug_warning(MODULE, f"Could not load project_index.json: {e}")
+
+    dep_results = setup_worktree_dependencies(
+        project_dir, worktree_info.path, project_index=project_index
+    )
+    for strategy_name, paths in dep_results.items():
+        if paths:
+            print_status(
+                f"Dependencies ({strategy_name}): {', '.join(paths)}", "success"
+            )
+
+    # Symlink .claude/ config to worktree for Claude Code features (settings, commands, etc.)
+    symlinked_claude = symlink_claude_config_to_worktree(
         project_dir, worktree_info.path
     )
-    if symlinked_modules:
-        print_status(f"Dependencies linked: {', '.join(symlinked_modules)}", "success")
+    if symlinked_claude:
+        print_status(f"Claude config linked: {', '.join(symlinked_claude)}", "success")
 
     # Copy security configuration files if they exist
     # Note: Unlike env files, security files always overwrite to ensure
@@ -574,6 +593,299 @@ def initialize_timeline_tracking(
         print(muted(f"  Note: Timeline tracking could not be initialized: {e}"))
 
 
+def setup_worktree_dependencies(
+    project_dir: Path,
+    worktree_path: Path,
+    project_index: dict | None = None,
+) -> dict[str, list[str]]:
+    """
+    Set up dependencies in a worktree using strategy-based dispatch.
+
+    Reads dependency configs from the project index and applies the correct
+    strategy for each: symlink, recreate, copy, or skip.
+
+    All operations are non-blocking — failures produce warnings but do not
+    prevent worktree creation.
+
+    Args:
+        project_dir: The main project directory
+        worktree_path: Path to the worktree
+        project_index: Parsed project_index.json dict, or None
+
+    Returns:
+        Dict mapping strategy names to lists of paths that were processed.
+    """
+    configs = get_dependency_configs(project_index, project_dir=project_dir)
+    results: dict[str, list[str]] = {}
+
+    for config in configs:
+        strategy_name = config.strategy.value
+        if strategy_name not in results:
+            results[strategy_name] = []
+
+        try:
+            performed = True
+            if config.strategy == DependencyStrategy.SYMLINK:
+                performed = _apply_symlink_strategy(project_dir, worktree_path, config)
+            elif config.strategy == DependencyStrategy.RECREATE:
+                performed = _apply_recreate_strategy(project_dir, worktree_path, config)
+            elif config.strategy == DependencyStrategy.COPY:
+                performed = _apply_copy_strategy(project_dir, worktree_path, config)
+            elif config.strategy == DependencyStrategy.SKIP:
+                _apply_skip_strategy(config)
+                # Don't record skipped entries — only report actual work
+                continue
+            if performed:
+                results[strategy_name].append(config.source_rel_path)
+        except Exception as e:
+            debug_warning(
+                MODULE,
+                f"Failed to apply {strategy_name} strategy for "
+                f"{config.source_rel_path}: {e}",
+            )
+
+    return results
+
+
+def _apply_symlink_strategy(
+    project_dir: Path,
+    worktree_path: Path,
+    config: DependencyShareConfig,
+) -> bool:
+    """Create a symlink (or Windows junction) from worktree to project source.
+
+    Returns True if a symlink was created, False if skipped.
+    """
+    source_path = project_dir / config.source_rel_path
+    target_path = worktree_path / config.source_rel_path
+
+    if not source_path.exists():
+        debug(MODULE, f"Skipping symlink {config.source_rel_path} - source missing")
+        return False
+
+    if target_path.exists() or target_path.is_symlink():
+        debug(MODULE, f"Skipping symlink {config.source_rel_path} - target exists")
+        return False
+
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        if is_windows():
+            # Windows: use directory junctions (no admin rights required).
+            # os.symlink creates a directory symlink that needs admin/DevMode,
+            # so we use mklink /J which creates a junction without privileges.
+            result = subprocess.run(
+                ["cmd", "/c", "mklink", "/J", str(target_path), str(source_path)],
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+            if result.returncode != 0:
+                raise OSError(result.stderr or "mklink /J failed")
+        else:
+            # macOS/Linux: relative symlinks for portability
+            relative_source = os.path.relpath(source_path, target_path.parent)
+            os.symlink(relative_source, target_path)
+        debug(MODULE, f"Symlinked {config.source_rel_path} -> {source_path}")
+        return True
+    except subprocess.TimeoutExpired:
+        debug_warning(
+            MODULE,
+            f"Symlink creation timed out for {config.source_rel_path}",
+        )
+        print_status(
+            f"Warning: Symlink creation timed out for {config.source_rel_path}",
+            "warning",
+        )
+        return False
+    except OSError as e:
+        debug_warning(
+            MODULE,
+            f"Could not symlink {config.source_rel_path}: {e}",
+        )
+        print_status(f"Warning: Could not link {config.source_rel_path}", "warning")
+        return False
+
+
+def _apply_recreate_strategy(
+    project_dir: Path,
+    worktree_path: Path,
+    config: DependencyShareConfig,
+) -> bool:
+    """Create a fresh virtual environment in the worktree and install deps.
+
+    Returns True if the venv was successfully created, False if skipped or failed.
+    """
+    venv_path = worktree_path / config.source_rel_path
+
+    if venv_path.exists():
+        debug(MODULE, f"Skipping recreate {config.source_rel_path} - already exists")
+        return False
+
+    # Detect Python executable from the source venv or fall back to sys.executable
+    source_venv = project_dir / config.source_rel_path
+    python_exec = sys.executable
+
+    if source_venv.exists():
+        # Try to use the same Python version as the source venv
+        for candidate in ("bin/python", "Scripts/python.exe"):
+            candidate_path = source_venv / candidate
+            if candidate_path.exists():
+                python_exec = str(candidate_path.resolve())
+                break
+
+    # Create the venv
+    try:
+        debug(MODULE, f"Creating venv at {venv_path}")
+        result = subprocess.run(
+            [python_exec, "-m", "venv", str(venv_path)],
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+        if result.returncode != 0:
+            debug_warning(MODULE, f"venv creation failed: {result.stderr}")
+            print_status(
+                f"Warning: Could not create venv at {config.source_rel_path}",
+                "warning",
+            )
+            # Clean up partial venv so retries aren't blocked
+            if venv_path.exists():
+                shutil.rmtree(venv_path, ignore_errors=True)
+            return False
+    except subprocess.TimeoutExpired:
+        debug_warning(MODULE, f"venv creation timed out for {config.source_rel_path}")
+        print_status(
+            f"Warning: venv creation timed out for {config.source_rel_path}",
+            "warning",
+        )
+        # Clean up partial venv so retries aren't blocked
+        if venv_path.exists():
+            shutil.rmtree(venv_path, ignore_errors=True)
+        return False
+
+    # Install from requirements file if specified
+    req_file = config.requirements_file
+    if req_file:
+        req_path = project_dir / req_file
+        if req_path.is_file():
+            # Determine pip executable inside the new venv
+            if is_windows():
+                pip_exec = str(venv_path / "Scripts" / "pip.exe")
+            else:
+                pip_exec = str(venv_path / "bin" / "pip")
+
+            # Build install command based on file type
+            req_basename = Path(req_file).name
+            if req_basename == "pyproject.toml":
+                # pyproject.toml: snapshot-install from the worktree copy.
+                # Non-editable so the venv doesn't symlink back to the source.
+                worktree_req = worktree_path / req_file
+                install_dir = str(
+                    worktree_req.parent if worktree_req.is_file() else req_path.parent
+                )
+                install_cmd = [pip_exec, "install", install_dir]
+            elif req_basename == "Pipfile":
+                # Pipfile: not directly installable via pip, skip
+                debug(
+                    MODULE,
+                    f"Skipping Pipfile-based install for {req_file} "
+                    "(use pipenv in the worktree)",
+                )
+                install_cmd = None
+            else:
+                # requirements.txt or similar: pip install -r
+                install_cmd = [pip_exec, "install", "-r", str(req_path)]
+
+            if install_cmd:
+                try:
+                    debug(MODULE, f"Installing deps from {req_file}")
+                    pip_result = subprocess.run(
+                        install_cmd,
+                        capture_output=True,
+                        text=True,
+                        timeout=120,
+                    )
+                    if pip_result.returncode != 0:
+                        debug_warning(
+                            MODULE,
+                            f"pip install failed (exit {pip_result.returncode}): "
+                            f"{pip_result.stderr}",
+                        )
+                        print_status(
+                            f"Warning: Dependency install failed for {req_file}",
+                            "warning",
+                        )
+                        # Clean up broken venv so retries aren't blocked
+                        if venv_path.exists():
+                            shutil.rmtree(venv_path, ignore_errors=True)
+                        return False
+                except subprocess.TimeoutExpired:
+                    debug_warning(
+                        MODULE,
+                        f"pip install timed out for {req_file}",
+                    )
+                    print_status(
+                        f"Warning: Dependency install timed out for {req_file}",
+                        "warning",
+                    )
+                    # Clean up broken venv so retries aren't blocked
+                    if venv_path.exists():
+                        shutil.rmtree(venv_path, ignore_errors=True)
+                    return False
+                except OSError as e:
+                    debug_warning(MODULE, f"pip install failed: {e}")
+                    # Clean up broken venv so retries aren't blocked
+                    if venv_path.exists():
+                        shutil.rmtree(venv_path, ignore_errors=True)
+                    return False
+
+    debug(MODULE, f"Recreated venv at {config.source_rel_path}")
+    return True
+
+
+def _apply_copy_strategy(
+    project_dir: Path,
+    worktree_path: Path,
+    config: DependencyShareConfig,
+) -> bool:
+    """Deep-copy a dependency directory from project to worktree.
+
+    Returns True if the copy was performed, False if skipped.
+    """
+    source_path = project_dir / config.source_rel_path
+    target_path = worktree_path / config.source_rel_path
+
+    if not source_path.exists():
+        debug(MODULE, f"Skipping copy {config.source_rel_path} - source missing")
+        return False
+
+    if target_path.exists():
+        debug(MODULE, f"Skipping copy {config.source_rel_path} - target exists")
+        return False
+
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        if source_path.is_file():
+            shutil.copy2(source_path, target_path)
+        else:
+            shutil.copytree(source_path, target_path)
+        debug(MODULE, f"Copied {config.source_rel_path} to worktree")
+        return True
+    except (OSError, shutil.Error) as e:
+        debug_warning(MODULE, f"Could not copy {config.source_rel_path}: {e}")
+        print_status(f"Warning: Could not copy {config.source_rel_path}", "warning")
+        return False
+
+
+def _apply_skip_strategy(config: DependencyShareConfig) -> None:
+    """Skip — nothing to do for this dependency type."""
+    debug(
+        MODULE, f"Skipping {config.dep_type} ({config.source_rel_path}) - skip strategy"
+    )
+
+
 # Export private functions for backward compatibility
 _ensure_timeline_hook_installed = ensure_timeline_hook_installed
 _initialize_timeline_tracking = initialize_timeline_tracking

apps/backend/core/worktree.py

@@ -430,6 +430,7 @@ class WorktreeManager:
                         if os.path.samefile(resolved_path, current_path):
                             return line[len("branch refs/heads/") :]
                 except OSError:
+                    # File system comparison errors are handled by fallback below
                     pass
                 # Fallback to normalized case comparison
                 if os.path.normcase(str(resolved_path)) == os.path.normcase(
@@ -510,6 +511,7 @@ class WorktreeManager:
                     if os.path.samefile(resolved_path, registered_path):
                         return True
             except OSError:
+                # File system errors handled by fallback comparison below
                 pass
             # Fallback to normalized case comparison for non-existent paths
             if os.path.normcase(str(resolved_path)) == os.path.normcase(

apps/backend/integrations/graphiti/queries_pkg/client.py

@@ -5,7 +5,9 @@ Handles database connection, initialization, and lifecycle management.
 Uses LadybugDB as the embedded graph database (no Docker required, Python 3.12+).
 """
 
+import asyncio
 import logging
+import random
 import sys
 from datetime import datetime, timezone
 
@@ -14,6 +16,27 @@ from graphiti_config import GraphitiConfig, GraphitiState
 
 logger = logging.getLogger(__name__)
 
+# Retry configuration for LadybugDB lock contention
+MAX_LOCK_RETRIES = 5
+INITIAL_BACKOFF_SECONDS = 0.5
+MAX_BACKOFF_SECONDS = 8.0
+JITTER_PERCENT = 0.2
+
+
+def _is_lock_error(error: Exception) -> bool:
+    """Check if an error indicates database lock contention."""
+    error_msg = str(error).lower()
+    return "could not set lock" in error_msg or (
+        "lock" in error_msg and ("file" in error_msg or "database" in error_msg)
+    )
+
+
+def _backoff_with_jitter(attempt: int) -> float:
+    """Calculate exponential backoff with jitter for retry delays."""
+    backoff = min(INITIAL_BACKOFF_SECONDS * (2**attempt), MAX_BACKOFF_SECONDS)
+    jitter = backoff * JITTER_PERCENT * (2 * random.random() - 1)
+    return max(0.01, backoff + jitter)
+
 
 def _apply_ladybug_monkeypatch() -> bool:
     """
@@ -196,32 +219,36 @@ class GraphitiClient:
                 )
 
                 db_path = self.config.get_db_path()
-                try:
-                    self._driver = create_patched_kuzu_driver(db=str(db_path))
-                except (OSError, PermissionError) as e:
-                    logger.warning(
-                        f"Failed to initialize LadybugDB driver at {db_path}: {e}"
-                    )
-                    capture_exception(
-                        e,
-                        error_type=type(e).__name__,
-                        db_path=str(db_path),
-                        llm_provider=self.config.llm_provider,
-                        embedder_provider=self.config.embedder_provider,
-                    )
-                    return False
-                except Exception as e:
-                    logger.warning(
-                        f"Unexpected error initializing LadybugDB driver at {db_path}: {e}"
-                    )
-                    capture_exception(
-                        e,
-                        error_type=type(e).__name__,
-                        db_path=str(db_path),
-                        llm_provider=self.config.llm_provider,
-                        embedder_provider=self.config.embedder_provider,
-                    )
-                    return False
+
+                # Retry with exponential backoff for lock contention
+                for attempt in range(MAX_LOCK_RETRIES + 1):
+                    try:
+                        self._driver = create_patched_kuzu_driver(db=str(db_path))
+                        if attempt > 0:
+                            logger.info(
+                                f"LadybugDB lock acquired after {attempt} retries"
+                            )
+                        break  # Success
+                    except Exception as e:
+                        if _is_lock_error(e) and attempt < MAX_LOCK_RETRIES:
+                            wait_time = _backoff_with_jitter(attempt)
+                            logger.debug(
+                                f"LadybugDB lock contention (attempt {attempt + 1}/{MAX_LOCK_RETRIES}), retrying in {wait_time:.2f}s"
+                            )
+                            await asyncio.sleep(wait_time)
+                            continue
+                        logger.warning(
+                            f"Failed to initialize LadybugDB driver at {db_path}: {e}"
+                        )
+                        capture_exception(
+                            e,
+                            error_type=type(e).__name__,
+                            db_path=str(db_path),
+                            llm_provider=self.config.llm_provider,
+                            embedder_provider=self.config.embedder_provider,
+                        )
+                        return False
+
                 logger.info(f"Initialized LadybugDB driver (patched) at: {db_path}")
             except ImportError as e:
                 logger.warning(f"KuzuDriver not available: {e}")

apps/backend/mcp_server/__init__.py

@@ -0,0 +1,9 @@
+"""
+Auto Claude MCP Server
+======================
+
+Control plane for the Auto Claude autonomous coding pipeline.
+Exposes all backend capabilities via the Model Context Protocol (MCP).
+"""
+
+__version__ = "0.1.0"

apps/backend/mcp_server/__main__.py

@@ -0,0 +1,95 @@
+"""
+Auto Claude MCP Server Entry Point
+===================================
+
+Usage:
+    python -m mcp_server --project-dir /path/to/project
+    python -m mcp_server --project-dir /path/to/project --transport sse --port 8642
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+# Configure logging to stderr (stdout is reserved for MCP protocol over stdio)
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(name)s] %(levelname)s: %(message)s",
+    stream=sys.stderr,
+)
+logger = logging.getLogger("mcp_server")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Auto Claude MCP Server - control plane for the autonomous coding pipeline",
+    )
+    parser.add_argument(
+        "--project-dir",
+        required=True,
+        help="Path to the project directory to manage",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "sse", "streamable-http"],
+        default="stdio",
+        help="MCP transport to use (default: stdio)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8642,
+        help="Port for SSE/HTTP transport (default: 8642)",
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Host for SSE/HTTP transport (default: 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable debug logging",
+    )
+    args = parser.parse_args()
+
+    if args.debug:
+        logging.getLogger().setLevel(logging.DEBUG)
+
+    # Initialize project context (adds backend to sys.path, loads .env)
+    from mcp_server.config import initialize
+
+    initialize(args.project_dir)
+
+    # Import server and register tools AFTER initialization
+    # (tools need backend modules on sys.path)
+    from mcp_server.server import mcp, register_all_tools
+
+    register_all_tools()
+
+    logger.info(
+        "Starting Auto Claude MCP server (transport=%s, project=%s)",
+        args.transport,
+        args.project_dir,
+    )
+
+    # For stdio transport, redirect any stray stdout prints to stderr
+    # to prevent corrupting the MCP JSON-RPC protocol
+    if args.transport == "stdio":
+        # Capture any prints from backend modules that write to stdout
+        _original_stdout = sys.stdout
+        sys.stdout = sys.stderr
+
+    # Run the server
+    if args.transport == "stdio":
+        mcp.run(transport="stdio")
+    elif args.transport == "sse":
+        mcp.run(transport="sse", host=args.host, port=args.port)
+    elif args.transport == "streamable-http":
+        mcp.run(transport="streamable-http", host=args.host, port=args.port)
+
+
+if __name__ == "__main__":
+    main()

apps/backend/mcp_server/config.py

@@ -0,0 +1,114 @@
+"""
+MCP Server Configuration
+========================
+
+Manages project context and backend initialization for the MCP server.
+The project directory is set once at startup and used by all tools.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Global project context - set once at server startup
+_project_dir: Path | None = None
+_auto_claude_dir: Path | None = None
+
+
+def initialize(project_dir: str | Path) -> None:
+    """Initialize the MCP server with a project directory.
+
+    This sets up the Python path so backend modules can be imported,
+    loads the .env file, and validates the project structure.
+
+    Args:
+        project_dir: Path to the user's project directory
+    """
+    global _project_dir, _auto_claude_dir
+
+    _project_dir = Path(project_dir).resolve()
+    if not _project_dir.is_dir():
+        raise ValueError(f"Project directory does not exist: {_project_dir}")
+
+    # Add backend to sys.path so existing modules can be imported
+    backend_dir = Path(__file__).parent.parent
+    if str(backend_dir) not in sys.path:
+        sys.path.insert(0, str(backend_dir))
+
+    # Load .env if present
+    try:
+        from cli.utils import import_dotenv
+
+        load_dotenv = import_dotenv()
+        env_file = backend_dir / ".env"
+        if env_file.exists():
+            load_dotenv(env_file)
+    except Exception:
+        logger.debug("Could not load .env file (non-critical)")
+
+    # Determine .auto-claude directory
+    auto_claude = _project_dir / ".auto-claude"
+    if not auto_claude.is_dir():
+        # Also check legacy 'auto-claude' (no dot prefix)
+        alt = _project_dir / "auto-claude"
+        if alt.is_dir():
+            auto_claude = alt
+        else:
+            logger.warning(
+                "No .auto-claude directory found in %s. "
+                "Some tools may not work until the project is initialized.",
+                _project_dir,
+            )
+    _auto_claude_dir = auto_claude
+
+    logger.info("MCP server initialized for project: %s", _project_dir)
+
+
+def get_project_dir() -> Path:
+    """Get the active project directory. Raises if not initialized."""
+    if _project_dir is None:
+        raise RuntimeError(
+            "MCP server not initialized. Call config.initialize() first."
+        )
+    return _project_dir
+
+
+def get_auto_claude_dir() -> Path:
+    """Get the .auto-claude directory for the active project."""
+    if _auto_claude_dir is None:
+        raise RuntimeError(
+            "MCP server not initialized. Call config.initialize() first."
+        )
+    return _auto_claude_dir
+
+
+def get_specs_dir() -> Path:
+    """Get the specs directory for the active project."""
+    return get_auto_claude_dir() / "specs"
+
+
+def get_project_index() -> dict:
+    """Load and return the project index if available."""
+    index_path = get_auto_claude_dir() / "project_index.json"
+    if not index_path.exists():
+        return {}
+    try:
+        with open(index_path, encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError) as e:
+        logger.warning("Failed to load project index: %s", e)
+        return {}
+
+
+def is_initialized() -> bool:
+    """Check if the project has been initialized with .auto-claude."""
+    try:
+        ac_dir = get_auto_claude_dir()
+        return ac_dir.is_dir()
+    except RuntimeError:
+        return False

apps/backend/mcp_server/operations.py

@@ -0,0 +1,158 @@
+"""
+Long-Running Operation Tracker
+===============================
+
+Tracks async operations (spec creation, builds, QA, etc.) so MCP clients
+can poll for progress. Tools that start long-running work return an
+operation_id immediately; clients poll operation_get_status() for updates.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+import uuid
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class OperationStatus(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+@dataclass
+class Operation:
+    """Represents a long-running operation."""
+
+    id: str
+    type: str  # e.g. "spec_create", "build", "qa_review"
+    status: OperationStatus = OperationStatus.PENDING
+    progress: int = 0  # 0-100
+    message: str = ""
+    result: Any = None
+    error: str | None = None
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+    _task: asyncio.Task | None = field(default=None, repr=False)
+
+    def to_dict(self) -> dict:
+        """Serialize for MCP response."""
+        return {
+            "id": self.id,
+            "type": self.type,
+            "status": self.status.value,
+            "progress": self.progress,
+            "message": self.message,
+            "result": self.result,
+            "error": self.error,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "elapsed_seconds": round(time.time() - self.created_at, 1),
+        }
+
+
+class OperationTracker:
+    """Manages the lifecycle of long-running operations."""
+
+    def __init__(self, max_completed: int = 100):
+        self._operations: dict[str, Operation] = {}
+        self._max_completed = max_completed
+
+    def create(self, operation_type: str, message: str = "") -> Operation:
+        """Create a new operation and return it."""
+        op = Operation(
+            id=str(uuid.uuid4()),
+            type=operation_type,
+            status=OperationStatus.PENDING,
+            message=message or f"Starting {operation_type}...",
+        )
+        self._operations[op.id] = op
+        self._cleanup_old()
+        return op
+
+    def get(self, operation_id: str) -> Operation | None:
+        """Get an operation by ID."""
+        return self._operations.get(operation_id)
+
+    def update(
+        self,
+        operation_id: str,
+        *,
+        status: OperationStatus | None = None,
+        progress: int | None = None,
+        message: str | None = None,
+        result: Any = None,
+        error: str | None = None,
+    ) -> Operation | None:
+        """Update an operation's state."""
+        op = self._operations.get(operation_id)
+        if op is None:
+            return None
+
+        if status is not None:
+            op.status = status
+        if progress is not None:
+            op.progress = max(0, min(100, progress))
+        if message is not None:
+            op.message = message
+        if result is not None:
+            op.result = result
+        if error is not None:
+            op.error = error
+        op.updated_at = time.time()
+        return op
+
+    def cancel(self, operation_id: str) -> bool:
+        """Cancel a running operation."""
+        op = self._operations.get(operation_id)
+        if op is None:
+            return False
+        if op.status in (OperationStatus.COMPLETED, OperationStatus.FAILED):
+            return False
+
+        # Cancel the asyncio task if it exists
+        if op._task and not op._task.done():
+            op._task.cancel()
+
+        op.status = OperationStatus.CANCELLED
+        op.message = "Operation cancelled by user"
+        op.updated_at = time.time()
+        return True
+
+    def list_active(self) -> list[Operation]:
+        """List all active (non-terminal) operations."""
+        return [
+            op
+            for op in self._operations.values()
+            if op.status in (OperationStatus.PENDING, OperationStatus.RUNNING)
+        ]
+
+    def _cleanup_old(self) -> None:
+        """Remove old completed operations to prevent memory growth."""
+        completed = [
+            op
+            for op in self._operations.values()
+            if op.status
+            in (
+                OperationStatus.COMPLETED,
+                OperationStatus.FAILED,
+                OperationStatus.CANCELLED,
+            )
+        ]
+        if len(completed) > self._max_completed:
+            # Sort by created_at, remove oldest
+            completed.sort(key=lambda o: o.created_at)
+            for op in completed[: len(completed) - self._max_completed]:
+                del self._operations[op.id]
+
+
+# Global singleton
+tracker = OperationTracker()

apps/backend/mcp_server/server.py

@@ -0,0 +1,56 @@
+"""
+Auto Claude MCP Server
+======================
+
+FastMCP server instance with all tool registrations.
+Tools are organized into modules under mcp_server/tools/.
+Each module's register() function adds tools to the server.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from fastmcp import FastMCP
+
+logger = logging.getLogger(__name__)
+
+# Create the FastMCP server instance
+mcp = FastMCP(
+    "Auto Claude",
+    instructions=(
+        "Auto Claude is an autonomous multi-agent coding framework. "
+        "Use these tools to manage tasks, create specs, run builds, "
+        "perform QA reviews, manage workspaces, and more. "
+        "Long-running operations return an operation_id - "
+        "poll with operation_get_status() for progress."
+    ),
+)
+
+
+def register_all_tools() -> None:
+    """Register all tool modules with the MCP server.
+
+    Each tool module defines functions decorated with @mcp.tool()
+    that are imported here to trigger registration.
+    """
+    # Phase 1: Project & Task management
+    # Phase 2: Core autonomous pipeline
+    # Phase 3: Feature tools
+    # Operations management (poll long-running ops)
+    from mcp_server.tools import (
+        execution,  # noqa: F401
+        github,  # noqa: F401
+        ideation,  # noqa: F401
+        insights,  # noqa: F401
+        memory,  # noqa: F401
+        ops,  # noqa: F401
+        project,  # noqa: F401
+        qa,  # noqa: F401
+        roadmap,  # noqa: F401
+        specs,  # noqa: F401
+        tasks,  # noqa: F401
+        workspace,  # noqa: F401
+    )
+
+    logger.info("All MCP tools registered successfully")

apps/backend/mcp_server/services/__init__.py

@@ -0,0 +1 @@
+"""Service layer - thin adapters wrapping existing backend modules."""

apps/backend/mcp_server/services/execution_service.py

@@ -0,0 +1,337 @@
+"""
+Execution Service
+==================
+
+Service layer for spawning and managing build processes.
+Wraps the run.py subprocess and parses task events from stdout.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import sys
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Matches core/task_event.py
+TASK_EVENT_PREFIX = "__TASK_EVENT__:"
+
+# Module-level singleton
+_instance: ExecutionService | None = None
+
+
+def get_execution_service(project_dir: Path) -> ExecutionService:
+    """Return a lazily-created singleton ExecutionService.
+
+    If project_dir changes (e.g. user switches projects), a new instance
+    is created so in-memory state matches the active project.
+    """
+    global _instance
+    if _instance is None or _instance.project_dir != project_dir:
+        _instance = ExecutionService(project_dir)
+    return _instance
+
+
+class ExecutionService:
+    """Manages build execution as a subprocess of run.py."""
+
+    def __init__(self, project_dir: Path):
+        self.project_dir = project_dir
+        self._processes: dict[str, asyncio.subprocess.Process] = {}
+        self._logs: dict[str, list[str]] = {}
+        self._events: dict[str, list[dict]] = {}
+
+    async def start_build(
+        self,
+        spec_id: str,
+        model: str = "sonnet",
+        thinking_level: str = "medium",
+    ) -> asyncio.subprocess.Process:
+        """Spawn a build subprocess for the given spec.
+
+        Args:
+            spec_id: The spec folder name
+            model: Model shorthand
+            thinking_level: Thinking level
+
+        Returns:
+            The subprocess handle
+
+        Raises:
+            RuntimeError: If a build is already running for this spec
+        """
+        if spec_id in self._processes:
+            proc = self._processes[spec_id]
+            if proc.returncode is None:
+                raise RuntimeError(
+                    f"Build already running for spec '{spec_id}'. "
+                    "Stop it first with build_stop()."
+                )
+
+        backend_dir = Path(__file__).parent.parent.parent  # apps/backend/
+        run_py = backend_dir / "run.py"
+        if not run_py.exists():
+            raise FileNotFoundError(f"run.py not found at {run_py}")
+
+        cmd = [
+            sys.executable,
+            str(run_py),
+            "--spec",
+            spec_id,
+            "--project-dir",
+            str(self.project_dir),
+            "--model",
+            model,
+            "--thinking",
+            thinking_level,
+        ]
+
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=str(backend_dir),
+        )
+
+        self._processes[spec_id] = proc
+        self._logs[spec_id] = []
+        self._events[spec_id] = []
+
+        # Start background reader for stdout
+        asyncio.create_task(self._read_output(spec_id, proc))
+
+        return proc
+
+    async def _read_output(
+        self, spec_id: str, proc: asyncio.subprocess.Process
+    ) -> None:
+        """Read stdout from the build process, parsing task events.
+
+        Args:
+            spec_id: The spec being built
+            proc: The subprocess to read from
+        """
+        if proc.stdout is None:
+            return
+
+        try:
+            while True:
+                line_bytes = await proc.stdout.readline()
+                if not line_bytes:
+                    break
+                line = line_bytes.decode("utf-8", errors="replace").rstrip("\n")
+
+                # Store the log line
+                log_list = self._logs.get(spec_id)
+                if log_list is not None:
+                    log_list.append(line)
+                    # Cap stored logs to prevent unbounded growth
+                    if len(log_list) > 5000:
+                        del log_list[:1000]
+
+                # Parse task events
+                event = self.parse_event(line)
+                if event is not None:
+                    events_list = self._events.get(spec_id)
+                    if events_list is not None:
+                        events_list.append(event)
+        except Exception as e:
+            logger.warning("Error reading build output for %s: %s", spec_id, e)
+
+    def parse_event(self, line: str) -> dict | None:
+        """Parse a task event line from build stdout.
+
+        Args:
+            line: A line of stdout output
+
+        Returns:
+            Parsed event dict or None if not an event line
+        """
+        if not line.startswith(TASK_EVENT_PREFIX):
+            return None
+        try:
+            return json.loads(line[len(TASK_EVENT_PREFIX) :])
+        except (json.JSONDecodeError, ValueError):
+            return None
+
+    def stop_build(self, spec_id: str) -> dict:
+        """Stop a running build process.
+
+        Args:
+            spec_id: The spec being built
+
+        Returns:
+            Status dict
+        """
+        proc = self._processes.get(spec_id)
+        if proc is None:
+            return {"success": False, "error": f"No build found for spec '{spec_id}'"}
+
+        if proc.returncode is not None:
+            return {
+                "success": False,
+                "error": f"Build for '{spec_id}' already finished (exit code {proc.returncode})",
+            }
+
+        try:
+            proc.terminate()
+            return {"success": True, "message": f"Build for '{spec_id}' terminated"}
+        except ProcessLookupError:
+            return {"success": False, "error": "Process already exited"}
+
+    def get_progress(self, spec_id: str) -> dict:
+        """Get progress of a build by inspecting events and process state.
+
+        Args:
+            spec_id: The spec being built
+
+        Returns:
+            Dict with status, events, and process info
+        """
+        proc = self._processes.get(spec_id)
+        events = self._events.get(spec_id, [])
+
+        if proc is None:
+            # Check if there's a completed implementation plan on disk
+            return self._get_disk_progress(spec_id)
+
+        is_running = proc.returncode is None
+        latest_event = events[-1] if events else None
+
+        return {
+            "spec_id": spec_id,
+            "running": is_running,
+            "exit_code": proc.returncode,
+            "event_count": len(events),
+            "latest_event": latest_event,
+            "log_lines": len(self._logs.get(spec_id, [])),
+        }
+
+    def get_logs(self, spec_id: str, tail: int = 50) -> dict:
+        """Get recent build logs.
+
+        Args:
+            spec_id: The spec being built
+            tail: Number of recent lines to return
+
+        Returns:
+            Dict with log lines
+        """
+        logs = self._logs.get(spec_id, [])
+        if not logs:
+            # Try to find logs on disk
+            return self._get_disk_logs(spec_id, tail)
+
+        return {
+            "spec_id": spec_id,
+            "total_lines": len(logs),
+            "lines": logs[-tail:],
+        }
+
+    def _get_disk_progress(self, spec_id: str) -> dict:
+        """Check on-disk state for build progress when no process is tracked.
+
+        Args:
+            spec_id: The spec folder name
+
+        Returns:
+            Progress dict from disk state
+        """
+        specs_dir = self.project_dir / ".auto-claude" / "specs"
+        spec_dir = self._resolve_spec_dir(specs_dir, spec_id)
+        if spec_dir is None:
+            return {"error": f"Spec '{spec_id}' not found"}
+
+        plan_file = spec_dir / "implementation_plan.json"
+        if not plan_file.exists():
+            return {
+                "spec_id": spec_id,
+                "running": False,
+                "status": "no_plan",
+                "message": "No implementation plan found. Create a spec first.",
+            }
+
+        try:
+            with open(plan_file, encoding="utf-8") as f:
+                plan = json.load(f)
+        except (json.JSONDecodeError, OSError):
+            return {
+                "spec_id": spec_id,
+                "running": False,
+                "status": "error",
+                "message": "Could not read implementation plan",
+            }
+
+        subtasks = plan.get("subtasks", [])
+        completed = sum(1 for s in subtasks if s.get("status") == "completed")
+        total = len(subtasks)
+
+        qa_signoff = plan.get("qa_signoff")
+        if qa_signoff and qa_signoff.get("status") == "approved":
+            status = "qa_approved"
+        elif qa_signoff and qa_signoff.get("status") == "rejected":
+            status = "qa_rejected"
+        elif completed == total and total > 0:
+            status = "build_complete"
+        elif completed > 0:
+            status = "building"
+        else:
+            status = "not_started"
+
+        return {
+            "spec_id": spec_id,
+            "running": False,
+            "status": status,
+            "subtasks_completed": completed,
+            "subtasks_total": total,
+            "qa_signoff": qa_signoff,
+        }
+
+    def _get_disk_logs(self, spec_id: str, tail: int) -> dict:
+        """Try to find build logs on disk.
+
+        Args:
+            spec_id: The spec folder name
+            tail: Number of lines to return
+
+        Returns:
+            Dict with log content
+        """
+        specs_dir = self.project_dir / ".auto-claude" / "specs"
+        spec_dir = self._resolve_spec_dir(specs_dir, spec_id)
+        if spec_dir is None:
+            return {"error": f"Spec '{spec_id}' not found", "lines": []}
+
+        # Check for task log file
+        log_file = spec_dir / "task_log.jsonl"
+        if not log_file.exists():
+            return {
+                "spec_id": spec_id,
+                "lines": [],
+                "message": "No build logs found",
+            }
+
+        try:
+            lines = log_file.read_text(encoding="utf-8").strip().split("\n")
+            return {
+                "spec_id": spec_id,
+                "total_lines": len(lines),
+                "lines": lines[-tail:],
+            }
+        except OSError as e:
+            return {"error": str(e), "lines": []}
+
+    def _resolve_spec_dir(self, specs_dir: Path, spec_id: str) -> Path | None:
+        """Resolve spec_id to directory with prefix matching."""
+        exact = specs_dir / spec_id
+        if exact.is_dir():
+            return exact
+
+        if specs_dir.is_dir():
+            for item in specs_dir.iterdir():
+                if item.is_dir() and item.name.startswith(spec_id):
+                    return item
+        return None

apps/backend/mcp_server/services/github_service.py

@@ -0,0 +1,202 @@
+"""
+GitHub Service
+==============
+
+Wraps the backend GitHubOrchestrator for MCP tool access.
+Handles repo detection, config creation, and result serialization.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import subprocess
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class GitHubService:
+    """Service layer for GitHub automation features."""
+
+    def __init__(self, project_dir: Path):
+        self.project_dir = project_dir
+        self.github_dir = project_dir / ".auto-claude" / "github"
+
+    def _detect_repo(self) -> str | None:
+        """Detect owner/repo from git remote origin."""
+        try:
+            result = subprocess.run(
+                ["git", "remote", "get-url", "origin"],
+                capture_output=True,
+                text=True,
+                cwd=str(self.project_dir),
+                timeout=10,
+            )
+            if result.returncode != 0:
+                return None
+
+            url = result.stdout.strip()
+            # Handle SSH: git@github.com:owner/repo.git
+            if url.startswith("git@"):
+                parts = url.split(":")[-1]
+                return parts.removesuffix(".git")
+            # Handle HTTPS: https://github.com/owner/repo.git
+            if "github.com" in url:
+                parts = url.split("github.com/")[-1]
+                return parts.removesuffix(".git")
+            return None
+        except Exception as e:
+            logger.warning("Failed to detect repo from git remote: %s", e)
+            return None
+
+    def _get_repo(self, repo: str | None) -> str:
+        """Get repo string, falling back to auto-detection."""
+        if repo:
+            return repo
+        detected = self._detect_repo()
+        if not detected:
+            raise ValueError(
+                "Could not detect repository. Provide 'repo' parameter "
+                "in owner/repo format, or ensure a GitHub remote is configured."
+            )
+        return detected
+
+    def _create_config(self, repo: str, model: str = "sonnet"):
+        """Create a GitHubRunnerConfig with sensible defaults."""
+        # Get GitHub token from environment
+        import os
+
+        from runners.github.models import GitHubRunnerConfig
+
+        token = os.environ.get("GITHUB_TOKEN", "")
+        if not token:
+            # Try gh CLI auth token
+            try:
+                result = subprocess.run(
+                    ["gh", "auth", "token"],
+                    capture_output=True,
+                    text=True,
+                    timeout=10,
+                )
+                if result.returncode == 0:
+                    token = result.stdout.strip()
+            except Exception:
+                pass
+
+        return GitHubRunnerConfig(
+            token=token,
+            repo=repo,
+            model=model,
+            thinking_level="medium",
+            pr_review_enabled=True,
+            triage_enabled=True,
+        )
+
+    async def review_pr(
+        self, pr_number: int, repo: str | None = None, model: str = "sonnet"
+    ) -> dict:
+        """Review a pull request with AI."""
+        try:
+            from runners.github.orchestrator import GitHubOrchestrator
+
+            resolved_repo = self._get_repo(repo)
+            config = self._create_config(resolved_repo, model)
+            orchestrator = GitHubOrchestrator(
+                project_dir=self.project_dir, config=config
+            )
+            result = await orchestrator.review_pr(pr_number)
+            return {"success": True, "data": result.to_dict()}
+        except ImportError:
+            return {"error": "GitHub runner module not available"}
+        except Exception as e:
+            return {"error": str(e)}
+
+    async def list_issues(
+        self, state: str = "open", limit: int = 30, repo: str | None = None
+    ) -> dict:
+        """List GitHub issues using gh CLI."""
+        try:
+            resolved_repo = self._get_repo(repo)
+            cmd = [
+                "gh",
+                "issue",
+                "list",
+                "--repo",
+                resolved_repo,
+                "--state",
+                state,
+                "--limit",
+                str(limit),
+                "--json",
+                "number,title,state,labels,author,createdAt,updatedAt",
+            ]
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                cwd=str(self.project_dir),
+                timeout=30,
+            )
+            if result.returncode != 0:
+                return {"error": f"gh CLI failed: {result.stderr.strip()}"}
+            issues = json.loads(result.stdout)
+            return {"success": True, "issues": issues, "count": len(issues)}
+        except Exception as e:
+            return {"error": str(e)}
+
+    async def auto_fix_issue(self, issue_number: int, repo: str | None = None) -> dict:
+        """Auto-fix a GitHub issue."""
+        try:
+            from runners.github.orchestrator import GitHubOrchestrator
+
+            resolved_repo = self._get_repo(repo)
+            config = self._create_config(resolved_repo)
+            config.auto_fix_enabled = True
+            orchestrator = GitHubOrchestrator(
+                project_dir=self.project_dir, config=config
+            )
+            state = await orchestrator.auto_fix_issue(issue_number)
+            return {"success": True, "data": state.to_dict()}
+        except ImportError:
+            return {"error": "GitHub runner module not available"}
+        except Exception as e:
+            return {"error": str(e)}
+
+    def get_review(self, pr_number: int) -> dict:
+        """Get the most recent review result for a PR."""
+        try:
+            from runners.github.models import PRReviewResult
+
+            result = PRReviewResult.load(self.github_dir, pr_number)
+            if result is None:
+                return {"error": f"No review found for PR #{pr_number}"}
+            return {"success": True, "data": result.to_dict()}
+        except ImportError:
+            return {"error": "GitHub runner module not available"}
+        except Exception as e:
+            return {"error": str(e)}
+
+    async def triage_issues(
+        self, issue_numbers: list[int], repo: str | None = None
+    ) -> dict:
+        """Triage and classify GitHub issues."""
+        try:
+            from runners.github.orchestrator import GitHubOrchestrator
+
+            resolved_repo = self._get_repo(repo)
+            config = self._create_config(resolved_repo)
+            config.triage_enabled = True
+            orchestrator = GitHubOrchestrator(
+                project_dir=self.project_dir, config=config
+            )
+            results = await orchestrator.triage_issues(issue_numbers=issue_numbers)
+            return {
+                "success": True,
+                "data": [r.to_dict() for r in results],
+                "count": len(results),
+            }
+        except ImportError:
+            return {"error": "GitHub runner module not available"}
+        except Exception as e:
+            return {"error": str(e)}

apps/backend/mcp_server/services/ideation_service.py

@@ -0,0 +1,82 @@
+"""
+Ideation Service
+=================
+
+Wraps the backend IdeationOrchestrator for MCP tool access.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Valid ideation types
+VALID_IDEATION_TYPES = [
+    "low_hanging_fruit",
+    "ui_ux_improvements",
+    "high_value_features",
+]
+
+
+class IdeationService:
+    """Service layer for AI-powered ideation generation."""
+
+    def __init__(self, project_dir: Path):
+        self.project_dir = project_dir
+        self.ideation_dir = project_dir / ".auto-claude" / "ideation"
+
+    async def generate(
+        self,
+        types: list[str] | None = None,
+        refresh: bool = False,
+        model: str = "sonnet",
+        thinking_level: str = "medium",
+    ) -> dict:
+        """Generate ideas for project improvements."""
+        try:
+            from ideation import IdeationOrchestrator
+
+            # Validate types
+            enabled_types = types or VALID_IDEATION_TYPES
+            invalid = [t for t in enabled_types if t not in VALID_IDEATION_TYPES]
+            if invalid:
+                return {
+                    "error": f"Invalid ideation types: {invalid}. "
+                    f"Valid types: {VALID_IDEATION_TYPES}"
+                }
+
+            orchestrator = IdeationOrchestrator(
+                project_dir=self.project_dir,
+                enabled_types=enabled_types,
+                model=model,
+                thinking_level=thinking_level,
+                refresh=refresh,
+            )
+            success = await orchestrator.run()
+
+            if success:
+                return self.get_ideation()
+            return {"error": "Ideation generation failed. Check logs for details."}
+        except ImportError:
+            return {"error": "Ideation module not available"}
+        except Exception as e:
+            return {"error": str(e)}
+
+    def get_ideation(self) -> dict:
+        """Get previously generated ideation results from disk."""
+        ideation_file = self.ideation_dir / "ideation.json"
+        if not ideation_file.exists():
+            return {
+                "success": True,
+                "data": None,
+                "message": "No ideation data yet. Use ideation_generate first.",
+            }
+        try:
+            with open(ideation_file, encoding="utf-8") as f:
+                ideation = json.load(f)
+            return {"success": True, "data": ideation}
+        except (json.JSONDecodeError, OSError) as e:
+            return {"error": f"Failed to load ideation data: {e}"}

apps/backend/mcp_server/services/insights_service.py

@@ -0,0 +1,116 @@
+"""
+Insights Service
+=================
+
+Wraps the backend InsightsRunner for MCP tool access.
+Captures stdout output since run_with_sdk prints to stdout.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class InsightsService:
+    """Service layer for codebase insights / AI chat."""
+
+    def __init__(self, project_dir: Path):
+        self.project_dir = project_dir
+
+    async def ask(
+        self,
+        question: str,
+        history: list | None = None,
+        model: str = "sonnet",
+        thinking_level: str = "medium",
+    ) -> dict:
+        """Ask an AI question about the codebase.
+
+        IMPORTANT: run_with_sdk prints to stdout, so we capture it.
+        """
+        try:
+            from runners.insights_runner import run_with_sdk
+
+            history = history or []
+            captured = io.StringIO()
+            with contextlib.redirect_stdout(captured):
+                await run_with_sdk(
+                    project_dir=str(self.project_dir),
+                    message=question,
+                    history=history,
+                    model=model,
+                    thinking_level=thinking_level,
+                )
+
+            output = captured.getvalue()
+
+            # Parse out any task suggestions from the output
+            task_suggestions = []
+            response_lines = []
+            for line in output.split("\n"):
+                if line.startswith("__TASK_SUGGESTION__:"):
+                    try:
+                        suggestion_json = line.split("__TASK_SUGGESTION__:", 1)[1]
+                        task_suggestions.append(json.loads(suggestion_json))
+                    except (json.JSONDecodeError, IndexError):
+                        pass
+                elif line.startswith("__TOOL_START__:") or line.startswith(
+                    "__TOOL_END__:"
+                ):
+                    # Skip tool markers - they're for the Electron UI
+                    pass
+                else:
+                    response_lines.append(line)
+
+            response_text = "\n".join(response_lines).strip()
+
+            return {
+                "success": True,
+                "response": response_text,
+                "task_suggestions": task_suggestions,
+            }
+        except ImportError:
+            return {"error": "Insights runner module not available"}
+        except Exception as e:
+            return {"error": str(e)}
+
+    def suggest_tasks(self) -> dict:
+        """Get AI-suggested tasks based on project analysis.
+
+        Reads the most recent ideation/insights data if available.
+        """
+        try:
+            ideation_file = (
+                self.project_dir / ".auto-claude" / "ideation" / "ideation.json"
+            )
+            if ideation_file.exists():
+                with open(ideation_file, encoding="utf-8") as f:
+                    ideation = json.load(f)
+                ideas = ideation.get("ideas", [])
+                # Convert top ideas to task suggestions
+                suggestions = []
+                for idea in ideas[:10]:
+                    suggestions.append(
+                        {
+                            "title": idea.get("title", ""),
+                            "description": idea.get("description", ""),
+                            "category": idea.get("type", "feature"),
+                            "impact": idea.get("impact", "medium"),
+                            "effort": idea.get("effort", "medium"),
+                        }
+                    )
+                return {"success": True, "suggestions": suggestions}
+
+            return {
+                "success": True,
+                "suggestions": [],
+                "message": "No ideation data available. Run ideation_generate first.",
+            }
+        except Exception as e:
+            return {"error": str(e)}

apps/backend/mcp_server/services/memory_service.py

@@ -0,0 +1,161 @@
+"""
+Memory Service
+===============
+
+Wraps the Graphiti memory system for MCP tool access.
+Gracefully handles the case where Graphiti is not enabled/configured.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Module-level singleton
+_instance: MemoryService | None = None
+
+
+def get_memory_service(project_dir: Path) -> MemoryService:
+    """Return a lazily-created singleton MemoryService.
+
+    Preserves the cached Graphiti connection across tool calls.
+    If project_dir changes, a new instance is created.
+    """
+    global _instance
+    if _instance is None or _instance.project_dir != project_dir:
+        _instance = MemoryService(project_dir)
+    return _instance
+
+
+def _is_graphiti_enabled() -> bool:
+    """Check if Graphiti memory is enabled via environment variable."""
+    return os.environ.get("GRAPHITI_ENABLED", "").lower() in ("true", "1")
+
+
+class MemoryService:
+    """Service layer for Graphiti-based semantic memory."""
+
+    def __init__(self, project_dir: Path):
+        self.project_dir = project_dir
+        self._memory = None
+
+    def _get_disabled_message(self) -> dict:
+        """Return a helpful error when Graphiti is not enabled."""
+        return {
+            "error": "Graphiti memory is not enabled. "
+            "Set GRAPHITI_ENABLED=true in your .env file and configure "
+            "the required provider settings (LLM and embedder). "
+            "See the project documentation for setup instructions."
+        }
+
+    async def _get_memory(self):
+        """Lazily initialize and return a GraphitiMemory instance."""
+        if self._memory is not None:
+            return self._memory
+
+        if not _is_graphiti_enabled():
+            return None
+
+        try:
+            from integrations.graphiti.memory import (
+                GraphitiMemory,
+                GroupIdMode,
+            )
+
+            # Use a dummy spec_dir since we're in project-wide mode
+            spec_dir = self.project_dir / ".auto-claude" / "mcp_memory"
+            spec_dir.mkdir(parents=True, exist_ok=True)
+
+            memory = GraphitiMemory(
+                spec_dir=spec_dir,
+                project_dir=self.project_dir,
+                group_id_mode=GroupIdMode.PROJECT,
+            )
+
+            if not await memory.initialize():
+                logger.warning("Failed to initialize Graphiti memory")
+                return None
+
+            self._memory = memory
+            return memory
+        except ImportError:
+            logger.warning("Graphiti modules not available")
+            return None
+        except Exception as e:
+            logger.warning("Failed to create Graphiti memory: %s", e)
+            return None
+
+    async def search(self, query: str, limit: int = 10) -> dict:
+        """Search the project's semantic memory."""
+        if not _is_graphiti_enabled():
+            return self._get_disabled_message()
+
+        try:
+            memory = await self._get_memory()
+            if memory is None:
+                return {"error": "Could not initialize Graphiti memory"}
+
+            results = await memory.get_relevant_context(
+                query=query,
+                num_results=limit,
+            )
+
+            return {
+                "success": True,
+                "results": results,
+                "count": len(results),
+            }
+        except Exception as e:
+            return {"error": f"Memory search failed: {e}"}
+
+    async def add_episode(self, content: str, source: str = "mcp") -> dict:
+        """Add a new episode/fact to the project's memory."""
+        if not _is_graphiti_enabled():
+            return self._get_disabled_message()
+
+        try:
+            memory = await self._get_memory()
+            if memory is None:
+                return {"error": "Could not initialize Graphiti memory"}
+
+            success = await memory.save_session_insights(
+                session_num=0,
+                insights={
+                    "content": content,
+                    "source": source,
+                    "type": "mcp_episode",
+                },
+            )
+
+            if success:
+                return {"success": True, "message": "Episode added to memory"}
+            return {"error": "Failed to save episode to memory"}
+        except Exception as e:
+            return {"error": f"Failed to add episode: {e}"}
+
+    async def get_recent(self, limit: int = 10) -> dict:
+        """Get recent memory entries."""
+        if not _is_graphiti_enabled():
+            return self._get_disabled_message()
+
+        try:
+            memory = await self._get_memory()
+            if memory is None:
+                return {"error": "Could not initialize Graphiti memory"}
+
+            # Use a broad search to get recent entries
+            results = await memory.get_relevant_context(
+                query="recent project activity and insights",
+                num_results=limit,
+            )
+
+            return {
+                "success": True,
+                "results": results,
+                "count": len(results),
+            }
+        except Exception as e:
+            return {"error": f"Failed to get recent memory: {e}"}

apps/backend/mcp_server/services/qa_service.py

@@ -0,0 +1,236 @@
+"""
+QA Service
+===========
+
+Service layer wrapping the backend QA reviewer for MCP tool consumption.
+Handles client creation, stdout isolation, and error management.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class QAService:
+    """Wraps QA review and approval operations for MCP server use."""
+
+    def __init__(self, project_dir: Path):
+        self.project_dir = project_dir
+
+    async def start_review(
+        self,
+        spec_id: str,
+        model: str = "sonnet",
+        thinking_level: str = "medium",
+        max_iterations: int = 3,
+    ) -> dict:
+        """Run a QA review session for a completed build.
+
+        Args:
+            spec_id: The spec folder name
+            model: Model shorthand
+            thinking_level: Thinking level
+            max_iterations: Maximum QA loop iterations
+
+        Returns:
+            Dict with review outcome (approved/rejected/error)
+        """
+        spec_dir = self._resolve_spec_dir(spec_id)
+        if spec_dir is None:
+            return {"error": f"Spec '{spec_id}' not found"}
+
+        # Verify the build is complete before starting QA
+        plan_file = spec_dir / "implementation_plan.json"
+        if not plan_file.exists():
+            return {
+                "error": "No implementation plan found. Build the spec first.",
+            }
+
+        try:
+            from core.client import create_client
+            from qa.reviewer import run_qa_agent_session
+        except ImportError as e:
+            logger.error("Failed to import QA modules: %s", e)
+            return {"error": f"Backend module not available: {e}"}
+
+        try:
+            # Determine QA session number from existing state
+            qa_session = self._get_next_qa_session(spec_dir)
+
+            # Create a Claude SDK client for the QA agent
+            captured = io.StringIO()
+            with contextlib.redirect_stdout(captured):
+                client = create_client(
+                    project_dir=self.project_dir,
+                    spec_dir=spec_dir,
+                    model=model,
+                    phase="qa_reviewer",
+                )
+
+                status, response_text, error_info = await run_qa_agent_session(
+                    client=client,
+                    project_dir=self.project_dir,
+                    spec_dir=spec_dir,
+                    qa_session=qa_session,
+                    max_iterations=max_iterations,
+                )
+
+            return {
+                "spec_id": spec_id,
+                "status": status,
+                "qa_session": qa_session,
+                "response_preview": response_text[:1000] if response_text else "",
+                "error_info": error_info if error_info else None,
+                "output": captured.getvalue()[-1000:] if captured.getvalue() else "",
+            }
+        except Exception as e:
+            logger.exception("QA review failed for %s", spec_id)
+            return {
+                "spec_id": spec_id,
+                "status": "error",
+                "error": str(e),
+            }
+
+    def get_report(self, spec_id: str) -> dict:
+        """Get the QA report for a spec.
+
+        Args:
+            spec_id: The spec folder name
+
+        Returns:
+            Dict with QA report content and status
+        """
+        spec_dir = self._resolve_spec_dir(spec_id)
+        if spec_dir is None:
+            return {"error": f"Spec '{spec_id}' not found"}
+
+        result: dict = {"spec_id": spec_id}
+
+        # Read qa_report.md
+        qa_report = spec_dir / "qa_report.md"
+        if qa_report.exists():
+            try:
+                result["report"] = qa_report.read_text(encoding="utf-8")
+            except OSError as e:
+                result["report_error"] = str(e)
+
+        # Read QA fix request if present
+        fix_request = spec_dir / "QA_FIX_REQUEST.md"
+        if fix_request.exists():
+            try:
+                result["fix_request"] = fix_request.read_text(encoding="utf-8")
+            except OSError as e:
+                result["fix_request_error"] = str(e)
+
+        # Read qa_signoff from implementation plan
+        plan_file = spec_dir / "implementation_plan.json"
+        if plan_file.exists():
+            try:
+                with open(plan_file, encoding="utf-8") as f:
+                    plan = json.load(f)
+                qa_signoff = plan.get("qa_signoff")
+                if qa_signoff:
+                    result["qa_signoff"] = qa_signoff
+            except (json.JSONDecodeError, OSError):
+                pass
+
+        if "report" not in result and "qa_signoff" not in result:
+            result["message"] = "No QA report found. Run QA review first."
+
+        return result
+
+    def approve(self, spec_id: str) -> dict:
+        """Manually approve a spec's QA status.
+
+        Args:
+            spec_id: The spec folder name
+
+        Returns:
+            Dict with approval result
+        """
+        spec_dir = self._resolve_spec_dir(spec_id)
+        if spec_dir is None:
+            return {"error": f"Spec '{spec_id}' not found"}
+
+        plan_file = spec_dir / "implementation_plan.json"
+        if not plan_file.exists():
+            return {"error": "No implementation plan found"}
+
+        try:
+            with open(plan_file, encoding="utf-8") as f:
+                plan = json.load(f)
+        except (json.JSONDecodeError, OSError) as e:
+            return {"error": f"Could not read implementation plan: {e}"}
+
+        from datetime import datetime, timezone
+
+        plan["qa_signoff"] = {
+            "status": "approved",
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "qa_session": plan.get("qa_signoff", {}).get("qa_session", 0),
+            "verified_by": "manual_approval",
+            "note": "Manually approved via MCP tool",
+        }
+
+        try:
+            with open(plan_file, "w", encoding="utf-8") as f:
+                json.dump(plan, f, indent=2)
+        except OSError as e:
+            return {"error": f"Could not write implementation plan: {e}"}
+
+        return {
+            "success": True,
+            "spec_id": spec_id,
+            "message": "Spec manually approved",
+        }
+
+    def _get_next_qa_session(self, spec_dir: Path) -> int:
+        """Get the next QA session number.
+
+        Args:
+            spec_dir: Path to the spec directory
+
+        Returns:
+            Next session number (1-based)
+        """
+        plan_file = spec_dir / "implementation_plan.json"
+        if not plan_file.exists():
+            return 1
+        try:
+            with open(plan_file, encoding="utf-8") as f:
+                plan = json.load(f)
+            qa_signoff = plan.get("qa_signoff", {})
+            current = qa_signoff.get("qa_session", 0)
+            return current + 1
+        except (json.JSONDecodeError, OSError):
+            return 1
+
+    def _resolve_spec_dir(self, spec_id: str) -> Path | None:
+        """Resolve spec_id to its directory path.
+
+        Args:
+            spec_id: Full or prefix spec identifier
+
+        Returns:
+            Path to spec directory or None
+        """
+        specs_dir = self.project_dir / ".auto-claude" / "specs"
+
+        # Direct match
+        exact = specs_dir / spec_id
+        if exact.is_dir():
+            return exact
+
+        # Prefix match
+        if specs_dir.is_dir():
+            for item in specs_dir.iterdir():
+                if item.is_dir() and item.name.startswith(spec_id):
+                    return item
+
+        return None

apps/backend/mcp_server/services/roadmap_service.py

@@ -0,0 +1,65 @@
+"""
+Roadmap Service
+================
+
+Wraps the backend RoadmapOrchestrator for MCP tool access.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class RoadmapService:
+    """Service layer for roadmap generation features."""
+
+    def __init__(self, project_dir: Path):
+        self.project_dir = project_dir
+        self.roadmap_dir = project_dir / ".auto-claude" / "roadmap"
+
+    async def generate(
+        self,
+        refresh: bool = False,
+        model: str = "sonnet",
+        thinking_level: str = "medium",
+    ) -> dict:
+        """Generate a strategic roadmap for the project."""
+        try:
+            from runners.roadmap.orchestrator import RoadmapOrchestrator
+
+            orchestrator = RoadmapOrchestrator(
+                project_dir=self.project_dir,
+                model=model,
+                thinking_level=thinking_level,
+                refresh=refresh,
+            )
+            success = await orchestrator.run()
+
+            if success:
+                # Load and return the generated roadmap
+                return self.get_roadmap()
+            return {"error": "Roadmap generation failed. Check logs for details."}
+        except ImportError:
+            return {"error": "Roadmap runner module not available"}
+        except Exception as e:
+            return {"error": str(e)}
+
+    def get_roadmap(self) -> dict:
+        """Get the current roadmap data from disk."""
+        roadmap_file = self.roadmap_dir / "roadmap.json"
+        if not roadmap_file.exists():
+            return {
+                "success": True,
+                "data": None,
+                "message": "No roadmap generated yet. Use roadmap_generate first.",
+            }
+        try:
+            with open(roadmap_file, encoding="utf-8") as f:
+                roadmap = json.load(f)
+            return {"success": True, "data": roadmap}
+        except (json.JSONDecodeError, OSError) as e:
+            return {"error": f"Failed to load roadmap: {e}"}

apps/backend/mcp_server/services/spec_service.py

@@ -0,0 +1,242 @@
+"""
+Spec Service
+=============
+
+Service layer wrapping the backend SpecOrchestrator for MCP tool consumption.
+Handles stdout isolation and error management.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class SpecService:
+    """Wraps backend spec creation pipeline for MCP server use."""
+
+    def __init__(self, project_dir: Path):
+        self.project_dir = project_dir
+
+    async def create_spec(
+        self,
+        task_description: str,
+        model: str = "sonnet",
+        thinking_level: str = "medium",
+        complexity_override: str | None = None,
+    ) -> dict:
+        """Create a spec using the SpecOrchestrator.
+
+        Redirects stdout to prevent protocol corruption when running
+        under stdio transport.
+
+        Args:
+            task_description: Description of the task to spec out
+            model: Model shorthand (sonnet, opus, etc.)
+            thinking_level: Thinking level (low, medium, high)
+            complexity_override: Force a specific complexity level
+
+        Returns:
+            Dict with success status, spec_dir, spec_id, and any captured output
+        """
+        try:
+            from spec.pipeline.orchestrator import SpecOrchestrator
+        except ImportError as e:
+            logger.error("Failed to import SpecOrchestrator: %s", e)
+            return {
+                "success": False,
+                "error": f"Backend module not available: {e}",
+            }
+
+        try:
+            captured = io.StringIO()
+            with contextlib.redirect_stdout(captured):
+                orchestrator = SpecOrchestrator(
+                    project_dir=self.project_dir,
+                    task_description=task_description,
+                    model=model,
+                    thinking_level=thinking_level,
+                    complexity_override=complexity_override,
+                    use_ai_assessment=True,
+                )
+                # Run non-interactively with auto-approve for MCP
+                success = await orchestrator.run(interactive=False, auto_approve=True)
+
+            spec_dir = orchestrator.spec_dir
+            return {
+                "success": success,
+                "spec_dir": str(spec_dir),
+                "spec_id": spec_dir.name,
+                "output": captured.getvalue()[-2000:] if captured.getvalue() else "",
+            }
+        except Exception as e:
+            logger.exception("Spec creation failed")
+            return {
+                "success": False,
+                "error": str(e),
+            }
+
+    def get_spec_status(self, spec_id: str) -> dict:
+        """Get the status of a spec by checking which phase files exist.
+
+        Args:
+            spec_id: The spec folder name (e.g. '001-my-feature')
+
+        Returns:
+            Dict describing which phases are complete and current state
+        """
+        specs_dir = self.project_dir / ".auto-claude" / "specs"
+        spec_dir = self._resolve_spec_dir(specs_dir, spec_id)
+        if spec_dir is None:
+            return {"error": f"Spec '{spec_id}' not found"}
+
+        phases = {
+            "discovery": (spec_dir / "discovery.md").exists(),
+            "requirements": (spec_dir / "requirements.json").exists(),
+            "complexity_assessment": (spec_dir / "complexity_assessment.json").exists(),
+            "spec": (spec_dir / "spec.md").exists(),
+            "implementation_plan": (spec_dir / "implementation_plan.json").exists(),
+        }
+
+        # Determine overall status
+        if phases["implementation_plan"]:
+            plan = self._load_json(spec_dir / "implementation_plan.json")
+            qa_signoff = plan.get("qa_signoff") if plan else None
+            if qa_signoff and qa_signoff.get("status") == "approved":
+                status = "qa_approved"
+            elif qa_signoff and qa_signoff.get("status") == "rejected":
+                status = "qa_rejected"
+            elif (spec_dir / "qa_report.md").exists():
+                status = "qa_reviewed"
+            else:
+                status = "ready_to_build"
+        elif phases["spec"]:
+            status = "spec_complete"
+        elif phases["requirements"]:
+            status = "requirements_gathered"
+        elif phases["discovery"]:
+            status = "discovery_complete"
+        else:
+            status = "pending"
+
+        return {
+            "spec_id": spec_dir.name,
+            "spec_dir": str(spec_dir),
+            "status": status,
+            "phases": phases,
+        }
+
+    def get_spec_content(self, spec_id: str) -> dict:
+        """Get the full content of a spec.
+
+        Args:
+            spec_id: The spec folder name
+
+        Returns:
+            Dict with spec.md content, requirements, implementation plan, etc.
+        """
+        specs_dir = self.project_dir / ".auto-claude" / "specs"
+        spec_dir = self._resolve_spec_dir(specs_dir, spec_id)
+        if spec_dir is None:
+            return {"error": f"Spec '{spec_id}' not found"}
+
+        content: dict = {
+            "spec_id": spec_dir.name,
+            "spec_dir": str(spec_dir),
+        }
+
+        # Read spec.md
+        spec_md = spec_dir / "spec.md"
+        if spec_md.exists():
+            try:
+                content["spec_md"] = spec_md.read_text(encoding="utf-8")
+            except OSError as e:
+                content["spec_md_error"] = str(e)
+
+        # Read requirements.json
+        req = self._load_json(spec_dir / "requirements.json")
+        if req is not None:
+            content["requirements"] = req
+
+        # Read implementation_plan.json
+        plan = self._load_json(spec_dir / "implementation_plan.json")
+        if plan is not None:
+            content["implementation_plan"] = plan
+
+        # Read complexity_assessment.json
+        assessment = self._load_json(spec_dir / "complexity_assessment.json")
+        if assessment is not None:
+            content["complexity_assessment"] = assessment
+
+        # Read QA report if present
+        qa_report = spec_dir / "qa_report.md"
+        if qa_report.exists():
+            try:
+                content["qa_report"] = qa_report.read_text(encoding="utf-8")
+            except OSError:
+                pass
+
+        return content
+
+    def list_specs(self) -> list[dict]:
+        """List all specs in the project.
+
+        Returns:
+            List of spec summary dicts
+        """
+        specs_dir = self.project_dir / ".auto-claude" / "specs"
+        if not specs_dir.is_dir():
+            return []
+
+        specs = []
+        for item in sorted(specs_dir.iterdir()):
+            if item.is_dir() and not item.name.startswith("."):
+                status_info = self.get_spec_status(item.name)
+                specs.append(status_info)
+        return specs
+
+    def _resolve_spec_dir(self, specs_dir: Path, spec_id: str) -> Path | None:
+        """Resolve a spec_id to its directory, supporting prefix matching.
+
+        Args:
+            specs_dir: Parent specs directory
+            spec_id: Full or prefix spec identifier
+
+        Returns:
+            Path to spec directory or None
+        """
+        # Direct match
+        exact = specs_dir / spec_id
+        if exact.is_dir():
+            return exact
+
+        # Prefix match (e.g. '001' matches '001-my-feature')
+        if specs_dir.is_dir():
+            for item in specs_dir.iterdir():
+                if item.is_dir() and item.name.startswith(spec_id):
+                    return item
+
+        return None
+
+    def _load_json(self, path: Path) -> dict | None:
+        """Safely load a JSON file.
+
+        Args:
+            path: Path to the JSON file
+
+        Returns:
+            Parsed dict or None
+        """
+        if not path.exists():
+            return None
+        try:
+            with open(path, encoding="utf-8") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, OSError) as e:
+            logger.warning("Failed to load %s: %s", path, e)
+            return None

apps/backend/mcp_server/services/task_service.py

@@ -0,0 +1,429 @@
+"""
+Task Service
+=============
+
+Loads, creates, updates, and deletes tasks by scanning spec directories.
+Ported from the TypeScript ProjectStore.loadTasksFromSpecsDir() logic.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Valid task statuses used by the backend pipeline
+VALID_STATUSES = frozenset(
+    {
+        "pending",
+        "spec_creating",
+        "planning",
+        "in_progress",
+        "qa_review",
+        "qa_fixing",
+        "human_review",
+        "done",
+        "failed",
+        "cancelled",
+    }
+)
+
+# Status priority for deduplication (higher = more "complete")
+_STATUS_PRIORITY: dict[str, int] = {
+    "done": 100,
+    "human_review": 80,
+    "qa_fixing": 70,
+    "qa_review": 65,
+    "in_progress": 50,
+    "planning": 40,
+    "spec_creating": 35,
+    "pending": 20,
+    "cancelled": 15,
+    "failed": 10,
+}
+
+
+def _slugify(text: str) -> str:
+    """Convert a title into a filesystem-safe slug."""
+    slug = text.lower().strip()
+    slug = re.sub(r"[^\w\s-]", "", slug)
+    slug = re.sub(r"[\s_]+", "-", slug)
+    slug = re.sub(r"-+", "-", slug)
+    return slug.strip("-")[:80]
+
+
+def _safe_read_json(path: Path) -> dict | None:
+    """Read a JSON file, returning None on any error."""
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError, ValueError):
+        return None
+
+
+def _extract_spec_heading(spec_path: Path) -> str | None:
+    """Extract the first markdown heading from a spec.md file."""
+    try:
+        content = spec_path.read_text(encoding="utf-8")
+        match = re.search(
+            r"^#\s+(?:Quick Spec:|Specification:)?\s*(.+)$", content, re.MULTILINE
+        )
+        if match:
+            return match.group(1).strip()
+    except OSError:
+        pass
+    return None
+
+
+def _extract_spec_overview(spec_path: Path) -> str | None:
+    """Extract the Overview section from a spec.md file."""
+    try:
+        content = spec_path.read_text(encoding="utf-8")
+        match = re.search(r"## Overview\s*\n+([\s\S]*?)(?=\n#{1,6}\s|$)", content)
+        if match:
+            return match.group(1).strip()
+    except OSError:
+        pass
+    return None
+
+
+class TaskService:
+    """Manages task lifecycle by reading/writing spec directories."""
+
+    def __init__(self, project_dir: Path) -> None:
+        self.project_dir = project_dir
+        self.specs_dir = project_dir / ".auto-claude" / "specs"
+        self.worktrees_dir = project_dir / ".auto-claude" / "worktrees" / "tasks"
+
+    # ------------------------------------------------------------------
+    # Read operations
+    # ------------------------------------------------------------------
+
+    def list_tasks(self) -> list[dict]:
+        """Scan spec directories and build a deduplicated task list.
+
+        Scans both the main project specs dir and worktree specs dirs.
+        Main project tasks take priority over worktree duplicates.
+        """
+        all_tasks: list[dict] = []
+        main_spec_ids: set[str] = set()
+
+        # 1. Scan main project specs
+        if self.specs_dir.is_dir():
+            main_tasks = self._load_tasks_from_specs_dir(self.specs_dir, "main")
+            all_tasks.extend(main_tasks)
+            main_spec_ids = {t["spec_id"] for t in main_tasks}
+
+        # 2. Scan worktree specs (only include if spec exists in main)
+        if self.worktrees_dir.is_dir():
+            try:
+                for worktree_dir in sorted(self.worktrees_dir.iterdir()):
+                    if not worktree_dir.is_dir():
+                        continue
+                    wt_specs = worktree_dir / ".auto-claude" / "specs"
+                    if wt_specs.is_dir():
+                        wt_tasks = self._load_tasks_from_specs_dir(wt_specs, "worktree")
+                        valid = [t for t in wt_tasks if t["spec_id"] in main_spec_ids]
+                        all_tasks.extend(valid)
+            except OSError as exc:
+                logger.warning("Error scanning worktrees: %s", exc)
+
+        # 3. Deduplicate — prefer main over worktree
+        task_map: dict[str, dict] = {}
+        for task in all_tasks:
+            existing = task_map.get(task["spec_id"])
+            if existing is None:
+                task_map[task["spec_id"]] = task
+            else:
+                existing_is_main = existing.get("location") == "main"
+                new_is_main = task.get("location") == "main"
+
+                if existing_is_main and not new_is_main:
+                    # Keep existing main
+                    continue
+                elif not existing_is_main and new_is_main:
+                    # Replace worktree with main
+                    task_map[task["spec_id"]] = task
+                else:
+                    # Same location — use status priority
+                    ep = _STATUS_PRIORITY.get(existing.get("status", ""), 0)
+                    np = _STATUS_PRIORITY.get(task.get("status", ""), 0)
+                    if np > ep:
+                        task_map[task["spec_id"]] = task
+
+        return list(task_map.values())
+
+    def get_task(self, spec_id: str) -> dict | None:
+        """Get full details for a single task by spec_id."""
+        spec_dir = self.specs_dir / spec_id
+        if not spec_dir.is_dir():
+            # Try worktrees
+            spec_dir = self._find_spec_dir_in_worktrees(spec_id)
+            if spec_dir is None:
+                return None
+        return self._load_single_task(spec_dir, "main")
+
+    def create_task(self, title: str, description: str) -> dict:
+        """Create a new spec directory with initial files.
+
+        Returns the created task dict.
+        """
+        self.specs_dir.mkdir(parents=True, exist_ok=True)
+
+        next_num = self._next_spec_number()
+        slug = _slugify(title)
+        dir_name = f"{next_num:03d}-{slug}" if slug else f"{next_num:03d}"
+        spec_dir = self.specs_dir / dir_name
+
+        spec_dir.mkdir(parents=True, exist_ok=True)
+
+        now = datetime.now(timezone.utc).isoformat()
+
+        # Write requirements.json
+        requirements = {"task_description": description}
+        (spec_dir / "requirements.json").write_text(
+            json.dumps(requirements, indent=2), encoding="utf-8"
+        )
+
+        # Write implementation_plan.json
+        plan = {
+            "feature": title,
+            "title": title,
+            "description": description,
+            "status": "pending",
+            "phases": [],
+            "created_at": now,
+            "updated_at": now,
+        }
+        (spec_dir / "implementation_plan.json").write_text(
+            json.dumps(plan, indent=2), encoding="utf-8"
+        )
+
+        # Write task_metadata.json
+        metadata = {
+            "created_at": now,
+            "source": "mcp",
+        }
+        (spec_dir / "task_metadata.json").write_text(
+            json.dumps(metadata, indent=2), encoding="utf-8"
+        )
+
+        return self._load_single_task(spec_dir, "main") or {
+            "spec_id": dir_name,
+            "title": title,
+            "description": description,
+            "status": "pending",
+        }
+
+    def update_task(
+        self,
+        spec_id: str,
+        *,
+        title: str | None = None,
+        description: str | None = None,
+        status: str | None = None,
+    ) -> dict | None:
+        """Update task metadata/plan fields."""
+        spec_dir = self.specs_dir / spec_id
+        if not spec_dir.is_dir():
+            return None
+
+        plan_path = spec_dir / "implementation_plan.json"
+        plan = _safe_read_json(plan_path) or {}
+        changed = False
+
+        if title is not None:
+            plan["feature"] = title
+            plan["title"] = title
+            changed = True
+
+        if description is not None:
+            plan["description"] = description
+            # Also update requirements
+            req_path = spec_dir / "requirements.json"
+            reqs = _safe_read_json(req_path) or {}
+            reqs["task_description"] = description
+            req_path.write_text(json.dumps(reqs, indent=2), encoding="utf-8")
+            changed = True
+
+        if status is not None:
+            if status not in VALID_STATUSES:
+                return None
+            plan["status"] = status
+            changed = True
+
+        if changed:
+            plan["updated_at"] = datetime.now(timezone.utc).isoformat()
+            plan_path.write_text(json.dumps(plan, indent=2), encoding="utf-8")
+
+        return self._load_single_task(spec_dir, "main")
+
+    def delete_task(self, spec_id: str) -> bool:
+        """Delete a spec directory. Returns True if deleted."""
+        spec_dir = self.specs_dir / spec_id
+        if not spec_dir.is_dir():
+            return False
+
+        # Safety: ensure it's actually within specs_dir (prevent traversal)
+        try:
+            spec_dir.resolve().relative_to(self.specs_dir.resolve())
+        except ValueError:
+            logger.error("Path traversal detected for spec_id: %s", spec_id)
+            return False
+
+        shutil.rmtree(spec_dir)
+        return True
+
+    def update_status(self, spec_id: str, status: str) -> dict | None:
+        """Update just the status field in implementation_plan.json."""
+        if status not in VALID_STATUSES:
+            return None
+        return self.update_task(spec_id, status=status)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _next_spec_number(self) -> int:
+        """Find the highest existing spec number and return next."""
+        max_num = 0
+        if self.specs_dir.is_dir():
+            for entry in self.specs_dir.iterdir():
+                if entry.is_dir():
+                    match = re.match(r"^(\d{3})-", entry.name)
+                    if match:
+                        max_num = max(max_num, int(match.group(1)))
+        return max_num + 1
+
+    def _find_spec_dir_in_worktrees(self, spec_id: str) -> Path | None:
+        """Search worktree directories for a spec."""
+        if not self.worktrees_dir.is_dir():
+            return None
+        for wt_dir in self.worktrees_dir.iterdir():
+            if not wt_dir.is_dir():
+                continue
+            candidate = wt_dir / ".auto-claude" / "specs" / spec_id
+            if candidate.is_dir():
+                return candidate
+        return None
+
+    def _load_tasks_from_specs_dir(self, specs_dir: Path, location: str) -> list[dict]:
+        """Load all tasks from a specs directory."""
+        tasks: list[dict] = []
+
+        try:
+            entries = sorted(specs_dir.iterdir())
+        except OSError as exc:
+            logger.warning("Error reading specs directory %s: %s", specs_dir, exc)
+            return []
+
+        for entry in entries:
+            if not entry.is_dir() or entry.name == ".gitkeep":
+                continue
+            try:
+                task = self._load_single_task(entry, location)
+                if task:
+                    tasks.append(task)
+            except Exception as exc:
+                logger.warning("Error loading spec %s: %s", entry.name, exc)
+
+        return tasks
+
+    def _load_single_task(self, spec_dir: Path, location: str) -> dict | None:
+        """Load a single task from its spec directory."""
+        dir_name = spec_dir.name
+
+        # Read implementation plan
+        plan = _safe_read_json(spec_dir / "implementation_plan.json")
+
+        # Read requirements
+        requirements = _safe_read_json(spec_dir / "requirements.json")
+
+        # Read metadata
+        metadata = _safe_read_json(spec_dir / "task_metadata.json")
+
+        # Determine title (priority: plan.feature > plan.title > dir name)
+        title = (plan or {}).get("feature") or (plan or {}).get("title") or dir_name
+
+        # If title looks like a spec ID (e.g. "054-some-slug"), try spec.md heading
+        if re.match(r"^\d{3}-", title):
+            spec_heading = _extract_spec_heading(spec_dir / "spec.md")
+            if spec_heading:
+                title = spec_heading
+
+        # Determine description (priority: plan.description > requirements.task_description > spec.md overview)
+        description = ""
+        if plan and plan.get("description"):
+            description = plan["description"]
+        if not description and requirements and requirements.get("task_description"):
+            description = requirements["task_description"]
+        if not description:
+            overview = _extract_spec_overview(spec_dir / "spec.md")
+            if overview:
+                description = overview
+
+        # Determine status
+        status = "pending"
+        if plan and plan.get("status"):
+            raw_status = plan["status"]
+            # Map frontend-style statuses to valid backend statuses
+            status_map: dict[str, str] = {
+                "pending": "pending",
+                "backlog": "pending",
+                "queue": "pending",
+                "queued": "pending",
+                "spec_creating": "spec_creating",
+                "planning": "planning",
+                "coding": "in_progress",
+                "in_progress": "in_progress",
+                "review": "qa_review",
+                "ai_review": "qa_review",
+                "qa_review": "qa_review",
+                "qa_fixing": "qa_fixing",
+                "human_review": "human_review",
+                "completed": "done",
+                "done": "done",
+                "pr_created": "done",
+                "error": "failed",
+                "failed": "failed",
+                "cancelled": "cancelled",
+            }
+            status = status_map.get(raw_status, "pending")
+
+        # Extract subtasks from plan phases
+        subtasks: list[dict] = []
+        if plan and plan.get("phases"):
+            for phase in plan["phases"]:
+                items = phase.get("subtasks") or phase.get("chunks") or []
+                for st in items:
+                    subtasks.append(
+                        {
+                            "id": st.get("id", ""),
+                            "title": st.get("description", ""),
+                            "status": st.get("status", "pending"),
+                        }
+                    )
+
+        # Build result
+        created_at = (plan or {}).get("created_at", "")
+        updated_at = (plan or {}).get("updated_at", "")
+
+        return {
+            "spec_id": dir_name,
+            "title": title,
+            "description": description,
+            "status": status,
+            "subtasks": subtasks,
+            "metadata": metadata,
+            "location": location,
+            "specs_path": str(spec_dir),
+            "has_spec": (spec_dir / "spec.md").exists(),
+            "has_plan": (spec_dir / "implementation_plan.json").exists(),
+            "has_qa_report": (spec_dir / "qa_report.md").exists(),
+            "created_at": created_at,
+            "updated_at": updated_at,
+        }

apps/backend/mcp_server/services/workspace_service.py

@@ -0,0 +1,245 @@
+"""
+Workspace Service
+==================
+
+Service layer wrapping the backend WorktreeManager for MCP tool consumption.
+Handles git worktree operations: list, diff, merge, discard, and PR creation.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class WorkspaceService:
+    """Wraps WorktreeManager operations for MCP server use."""
+
+    def __init__(self, project_dir: Path):
+        self.project_dir = project_dir
+
+    def _get_manager(self):
+        """Lazily create a WorktreeManager instance.
+
+        Returns:
+            WorktreeManager instance
+
+        Raises:
+            ImportError: If backend module is not available
+        """
+        from core.worktree import WorktreeManager
+
+        return WorktreeManager(self.project_dir)
+
+    def list_worktrees(self) -> dict:
+        """List all active git worktrees for the project.
+
+        Returns:
+            Dict with list of worktree info dicts
+        """
+        try:
+            manager = self._get_manager()
+        except ImportError as e:
+            return {"error": f"Backend module not available: {e}"}
+
+        try:
+            captured = io.StringIO()
+            with contextlib.redirect_stdout(captured):
+                worktrees = manager.list_all_worktrees()
+
+            result = []
+            for wt in worktrees:
+                entry = {
+                    "spec_name": wt.spec_name,
+                    "branch": wt.branch,
+                    "path": str(wt.path),
+                    "base_branch": wt.base_branch,
+                    "is_active": wt.is_active,
+                    "commit_count": wt.commit_count,
+                    "files_changed": wt.files_changed,
+                    "additions": wt.additions,
+                    "deletions": wt.deletions,
+                }
+                if wt.days_since_last_commit is not None:
+                    entry["days_since_last_commit"] = wt.days_since_last_commit
+                if wt.last_commit_date is not None:
+                    entry["last_commit_date"] = wt.last_commit_date.isoformat()
+                result.append(entry)
+
+            return {"worktrees": result, "count": len(result)}
+        except Exception as e:
+            logger.exception("Failed to list worktrees")
+            return {"error": str(e)}
+
+    def get_diff(self, spec_id: str) -> dict:
+        """Get the git diff for a spec's worktree.
+
+        Args:
+            spec_id: The spec folder name
+
+        Returns:
+            Dict with diff content and change summary
+        """
+        try:
+            manager = self._get_manager()
+        except ImportError as e:
+            return {"error": f"Backend module not available: {e}"}
+
+        try:
+            captured = io.StringIO()
+            with contextlib.redirect_stdout(captured):
+                info = manager.get_worktree_info(spec_id)
+
+            if info is None:
+                return {"error": f"No worktree found for spec '{spec_id}'"}
+
+            # Get changed files
+            files = manager.get_changed_files(spec_id)
+            summary = manager.get_change_summary(spec_id)
+
+            # Get actual diff content
+            from core.git_executable import run_git
+
+            diff_result = run_git(
+                ["diff", f"{info.base_branch}...HEAD"],
+                cwd=info.path,
+            )
+            diff_content = ""
+            if diff_result.returncode == 0:
+                diff_content = diff_result.stdout
+                # Truncate very large diffs
+                if len(diff_content) > 50000:
+                    diff_content = (
+                        diff_content[:50000]
+                        + "\n\n... (diff truncated, total length: "
+                        + str(len(diff_result.stdout))
+                        + " chars)"
+                    )
+
+            return {
+                "spec_id": spec_id,
+                "branch": info.branch,
+                "base_branch": info.base_branch,
+                "changed_files": [
+                    {"status": status, "path": path} for status, path in files
+                ],
+                "summary": summary,
+                "diff": diff_content,
+            }
+        except Exception as e:
+            logger.exception("Failed to get diff for %s", spec_id)
+            return {"error": str(e)}
+
+    async def merge(self, spec_id: str, strategy: str = "auto") -> dict:
+        """Merge a spec's worktree changes back to the main branch.
+
+        Args:
+            spec_id: The spec folder name
+            strategy: Merge strategy - 'auto' (git merge), 'no-commit' (stage only)
+
+        Returns:
+            Dict with merge result
+        """
+        try:
+            manager = self._get_manager()
+        except ImportError as e:
+            return {"error": f"Backend module not available: {e}"}
+
+        try:
+            no_commit = strategy == "no-commit"
+
+            captured = io.StringIO()
+            with contextlib.redirect_stdout(captured):
+                success = manager.merge_worktree(
+                    spec_id,
+                    delete_after=False,
+                    no_commit=no_commit,
+                )
+
+            return {
+                "success": success,
+                "spec_id": spec_id,
+                "strategy": strategy,
+                "output": captured.getvalue()[-2000:] if captured.getvalue() else "",
+            }
+        except Exception as e:
+            logger.exception("Failed to merge worktree for %s", spec_id)
+            return {"success": False, "error": str(e)}
+
+    def discard(self, spec_id: str) -> dict:
+        """Discard a spec's worktree and optionally its branch.
+
+        Args:
+            spec_id: The spec folder name
+
+        Returns:
+            Dict with discard result
+        """
+        try:
+            manager = self._get_manager()
+        except ImportError as e:
+            return {"error": f"Backend module not available: {e}"}
+
+        try:
+            captured = io.StringIO()
+            with contextlib.redirect_stdout(captured):
+                manager.remove_worktree(spec_id, delete_branch=True)
+
+            return {
+                "success": True,
+                "spec_id": spec_id,
+                "message": f"Worktree and branch for '{spec_id}' removed",
+                "output": captured.getvalue() if captured.getvalue() else "",
+            }
+        except Exception as e:
+            logger.exception("Failed to discard worktree for %s", spec_id)
+            return {"success": False, "error": str(e)}
+
+    async def create_pr(
+        self,
+        spec_id: str,
+        title: str | None = None,
+        body: str | None = None,
+    ) -> dict:
+        """Push branch and create a pull request from a spec's worktree.
+
+        Automatically detects the git provider (GitHub/GitLab).
+
+        Args:
+            spec_id: The spec folder name
+            title: PR title (defaults to spec name)
+            body: PR body (defaults to spec summary)
+
+        Returns:
+            Dict with PR URL and status
+        """
+        try:
+            manager = self._get_manager()
+        except ImportError as e:
+            return {"error": f"Backend module not available: {e}"}
+
+        try:
+            captured = io.StringIO()
+            with contextlib.redirect_stdout(captured):
+                result = manager.push_and_create_pr(
+                    spec_name=spec_id,
+                    title=title,
+                )
+
+            return {
+                "success": result.get("success", False),
+                "spec_id": spec_id,
+                "pr_url": result.get("pr_url"),
+                "branch": result.get("branch"),
+                "provider": result.get("provider"),
+                "already_exists": result.get("already_exists", False),
+                "error": result.get("error"),
+                "output": captured.getvalue()[-1000:] if captured.getvalue() else "",
+            }
+        except Exception as e:
+            logger.exception("Failed to create PR for %s", spec_id)
+            return {"success": False, "error": str(e)}

apps/backend/mcp_server/tools/__init__.py

@@ -0,0 +1 @@
+"""MCP tool modules - each module registers tools with the FastMCP server."""

apps/backend/mcp_server/tools/execution.py

@@ -0,0 +1,159 @@
+"""
+Execution Tools
+================
+
+MCP tools for starting, stopping, and monitoring builds.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from mcp_server.config import get_project_dir
+from mcp_server.operations import OperationStatus, tracker
+from mcp_server.server import mcp
+
+logger = logging.getLogger(__name__)
+
+
+@mcp.tool()
+async def build_start(
+    spec_id: str,
+    model: str = "sonnet",
+    thinking_level: str = "medium",
+) -> dict:
+    """Start building/implementing a spec. This is a long-running operation.
+
+    Spawns the autonomous coding pipeline which creates a worktree, runs
+    the planner, then executes each subtask with parallel agents.
+
+    Args:
+        spec_id: Spec folder name or prefix (e.g. '001' or '001-my-feature')
+        model: Model to use - 'sonnet' (fast), 'opus' (thorough)
+        thinking_level: Reasoning depth - 'low', 'medium', 'high'
+
+    Returns:
+        An operation_id to poll with operation_get_status() for progress
+    """
+    op = tracker.create("build", f"Building spec: {spec_id}")
+
+    async def _run() -> None:
+        try:
+            from mcp_server.services.execution_service import get_execution_service
+
+            service = get_execution_service(get_project_dir())
+
+            tracker.update(
+                op.id,
+                status=OperationStatus.RUNNING,
+                progress=5,
+                message="Spawning build process...",
+            )
+
+            proc = await service.start_build(
+                spec_id=spec_id,
+                model=model,
+                thinking_level=thinking_level,
+            )
+
+            tracker.update(
+                op.id,
+                status=OperationStatus.RUNNING,
+                progress=10,
+                message="Build process started, waiting for completion...",
+            )
+
+            # Wait for the process to complete
+            await proc.wait()
+
+            if proc.returncode == 0:
+                progress_info = service.get_progress(spec_id)
+                tracker.update(
+                    op.id,
+                    status=OperationStatus.COMPLETED,
+                    progress=100,
+                    message="Build completed successfully",
+                    result=progress_info,
+                )
+            else:
+                logs = service.get_logs(spec_id, tail=20)
+                tracker.update(
+                    op.id,
+                    status=OperationStatus.FAILED,
+                    error=f"Build exited with code {proc.returncode}",
+                    result={
+                        "exit_code": proc.returncode,
+                        "tail_logs": logs.get("lines", []),
+                    },
+                )
+        except Exception as e:
+            logger.exception("build_start operation failed")
+            tracker.update(
+                op.id,
+                status=OperationStatus.FAILED,
+                error=str(e),
+            )
+
+    op._task = asyncio.create_task(_run())
+    return {
+        "operation_id": op.id,
+        "message": "Build started. Poll operation_get_status() for progress.",
+    }
+
+
+@mcp.tool()
+def build_stop(spec_id: str) -> dict:
+    """Stop a running build.
+
+    Terminates the build subprocess. The worktree and any partial changes
+    are preserved so the build can be resumed later.
+
+    Args:
+        spec_id: Spec folder name or prefix
+
+    Returns:
+        Whether the build was successfully stopped
+    """
+    from mcp_server.services.execution_service import get_execution_service
+
+    service = get_execution_service(get_project_dir())
+    return service.stop_build(spec_id)
+
+
+@mcp.tool()
+def build_get_progress(spec_id: str) -> dict:
+    """Get progress of a running or completed build.
+
+    Shows subtask completion status, QA state, and whether the build
+    is still running.
+
+    Args:
+        spec_id: Spec folder name or prefix
+
+    Returns:
+        Build progress including subtask completion and QA status
+    """
+    from mcp_server.services.execution_service import get_execution_service
+
+    service = get_execution_service(get_project_dir())
+    return service.get_progress(spec_id)
+
+
+@mcp.tool()
+def build_get_logs(spec_id: str, tail: int = 50) -> dict:
+    """Get recent build logs for a spec.
+
+    Returns the most recent log lines from the build process output.
+
+    Args:
+        spec_id: Spec folder name or prefix
+        tail: Number of recent lines to return (default 50)
+
+    Returns:
+        Recent log lines from the build
+    """
+    from mcp_server.services.execution_service import get_execution_service
+
+    service = get_execution_service(get_project_dir())
+    return service.get_logs(spec_id, tail=tail)

apps/backend/mcp_server/tools/github.py

@@ -0,0 +1,208 @@
+"""
+GitHub Tools
+=============
+
+MCP tools for GitHub automation: PR review, issue triage, auto-fix.
+Long-running operations return an operation_id for polling.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from mcp_server.config import get_project_dir
+from mcp_server.operations import OperationStatus, tracker
+from mcp_server.server import mcp
+from mcp_server.services.github_service import GitHubService
+
+
+def _get_service() -> GitHubService:
+    return GitHubService(get_project_dir())
+
+
+@mcp.tool()
+async def github_review_pr(
+    pr_number: int, repo: str | None = None, model: str = "sonnet"
+) -> dict:
+    """Review a pull request with AI. Long-running operation - returns operation_id.
+
+    Performs a multi-pass AI code review including security, quality,
+    structural analysis, and AI comment triage.
+
+    Args:
+        pr_number: The PR number to review
+        repo: Repository in owner/repo format (auto-detected from git remote if omitted)
+        model: Model to use (haiku, sonnet, opus)
+
+    Returns:
+        Operation ID to poll with operation_get_status()
+    """
+    service = _get_service()
+    op = tracker.create("github_review_pr", f"Starting review of PR #{pr_number}...")
+
+    async def _run():
+        try:
+            tracker.update(
+                op.id,
+                status=OperationStatus.RUNNING,
+                progress=10,
+                message=f"Reviewing PR #{pr_number}...",
+            )
+            result = await service.review_pr(pr_number, repo, model)
+            if "error" in result:
+                tracker.update(
+                    op.id, status=OperationStatus.FAILED, error=result["error"]
+                )
+            else:
+                tracker.update(
+                    op.id,
+                    status=OperationStatus.COMPLETED,
+                    progress=100,
+                    message="Review complete",
+                    result=result,
+                )
+        except Exception as e:
+            tracker.update(op.id, status=OperationStatus.FAILED, error=str(e))
+
+    op._task = asyncio.create_task(_run())
+    return {
+        "operation_id": op.id,
+        "message": f"PR #{pr_number} review started. Poll operation_get_status() for progress.",
+    }
+
+
+@mcp.tool()
+async def github_list_issues(
+    state: str = "open", limit: int = 30, repo: str | None = None
+) -> dict:
+    """List GitHub issues for the project.
+
+    Args:
+        state: Issue state filter: open, closed, or all
+        limit: Maximum number of issues to return
+        repo: Repository in owner/repo format (auto-detected if omitted)
+
+    Returns:
+        List of issues with number, title, state, labels, author
+    """
+    service = _get_service()
+    return await service.list_issues(state, limit, repo)
+
+
+@mcp.tool()
+async def github_auto_fix(issue_number: int, repo: str | None = None) -> dict:
+    """Automatically fix a GitHub issue by creating a spec and building it. Long-running.
+
+    Creates a specification from the issue, builds it through the autonomous
+    pipeline (planner -> coder -> QA), and optionally creates a PR.
+
+    Args:
+        issue_number: The issue number to auto-fix
+        repo: Repository in owner/repo format (auto-detected if omitted)
+
+    Returns:
+        Operation ID to poll with operation_get_status()
+    """
+    service = _get_service()
+    op = tracker.create(
+        "github_auto_fix", f"Starting auto-fix for issue #{issue_number}..."
+    )
+
+    async def _run():
+        try:
+            tracker.update(
+                op.id,
+                status=OperationStatus.RUNNING,
+                progress=10,
+                message=f"Auto-fixing issue #{issue_number}...",
+            )
+            result = await service.auto_fix_issue(issue_number, repo)
+            if "error" in result:
+                tracker.update(
+                    op.id, status=OperationStatus.FAILED, error=result["error"]
+                )
+            else:
+                tracker.update(
+                    op.id,
+                    status=OperationStatus.COMPLETED,
+                    progress=100,
+                    message="Auto-fix complete",
+                    result=result,
+                )
+        except Exception as e:
+            tracker.update(op.id, status=OperationStatus.FAILED, error=str(e))
+
+    op._task = asyncio.create_task(_run())
+    return {
+        "operation_id": op.id,
+        "message": f"Auto-fix for issue #{issue_number} started. Poll operation_get_status() for progress.",
+    }
+
+
+@mcp.tool()
+def github_get_review(pr_number: int) -> dict:
+    """Get the most recent review result for a PR.
+
+    Returns the saved review data including findings, verdict, and summary.
+
+    Args:
+        pr_number: The PR number to get the review for
+
+    Returns:
+        Review result with findings, verdict, blockers, and summary
+    """
+    service = _get_service()
+    return service.get_review(pr_number)
+
+
+@mcp.tool()
+async def github_triage_issues(
+    issue_numbers: list[int], repo: str | None = None
+) -> dict:
+    """Triage and classify GitHub issues. Long-running.
+
+    Analyzes issues for duplicates, spam, feature creep, and assigns
+    categories, priority, and suggested labels.
+
+    Args:
+        issue_numbers: List of issue numbers to triage
+        repo: Repository in owner/repo format (auto-detected if omitted)
+
+    Returns:
+        Operation ID to poll with operation_get_status()
+    """
+    service = _get_service()
+    op = tracker.create(
+        "github_triage_issues",
+        f"Starting triage of {len(issue_numbers)} issues...",
+    )
+
+    async def _run():
+        try:
+            tracker.update(
+                op.id,
+                status=OperationStatus.RUNNING,
+                progress=10,
+                message=f"Triaging {len(issue_numbers)} issues...",
+            )
+            result = await service.triage_issues(issue_numbers, repo)
+            if "error" in result:
+                tracker.update(
+                    op.id, status=OperationStatus.FAILED, error=result["error"]
+                )
+            else:
+                tracker.update(
+                    op.id,
+                    status=OperationStatus.COMPLETED,
+                    progress=100,
+                    message=f"Triaged {result.get('count', 0)} issues",
+                    result=result,
+                )
+        except Exception as e:
+            tracker.update(op.id, status=OperationStatus.FAILED, error=str(e))
+
+    op._task = asyncio.create_task(_run())
+    return {
+        "operation_id": op.id,
+        "message": f"Triage of {len(issue_numbers)} issues started. Poll operation_get_status() for progress.",
+    }

apps/backend/mcp_server/tools/ideation.py

@@ -0,0 +1,87 @@
+"""
+Ideation Tools
+===============
+
+MCP tools for AI-powered project ideation and improvement discovery.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from mcp_server.config import get_project_dir
+from mcp_server.operations import OperationStatus, tracker
+from mcp_server.server import mcp
+from mcp_server.services.ideation_service import IdeationService
+
+
+def _get_service() -> IdeationService:
+    return IdeationService(get_project_dir())
+
+
+@mcp.tool()
+async def ideation_generate(
+    types: list[str] | None = None,
+    refresh: bool = False,
+    model: str = "sonnet",
+) -> dict:
+    """Generate ideas for project improvements. Long-running.
+
+    Analyzes the codebase and generates actionable improvement ideas
+    across multiple categories.
+
+    Args:
+        types: Ideation types to generate. Options: low_hanging_fruit,
+               ui_ux_improvements, high_value_features. Defaults to all.
+        refresh: Force regeneration of existing ideation data
+        model: Model to use (haiku, sonnet, opus)
+
+    Returns:
+        Operation ID to poll with operation_get_status()
+    """
+    service = _get_service()
+    op = tracker.create("ideation_generate", "Starting ideation generation...")
+
+    async def _run():
+        try:
+            tracker.update(
+                op.id,
+                status=OperationStatus.RUNNING,
+                progress=10,
+                message="Analyzing project for improvement ideas...",
+            )
+            result = await service.generate(types=types, refresh=refresh, model=model)
+            if "error" in result:
+                tracker.update(
+                    op.id, status=OperationStatus.FAILED, error=result["error"]
+                )
+            else:
+                tracker.update(
+                    op.id,
+                    status=OperationStatus.COMPLETED,
+                    progress=100,
+                    message="Ideation complete",
+                    result=result,
+                )
+        except Exception as e:
+            tracker.update(op.id, status=OperationStatus.FAILED, error=str(e))
+
+    op._task = asyncio.create_task(_run())
+    return {
+        "operation_id": op.id,
+        "message": "Ideation generation started. Poll operation_get_status() for progress.",
+    }
+
+
+@mcp.tool()
+def ideation_get() -> dict:
+    """Get previously generated ideation results.
+
+    Returns all generated ideas with their categories, priorities,
+    effort estimates, and implementation suggestions.
+
+    Returns:
+        Ideation data with ideas grouped by type and priority
+    """
+    service = _get_service()
+    return service.get_ideation()

apps/backend/mcp_server/tools/insights.py

@@ -0,0 +1,84 @@
+"""
+Insights Tools
+===============
+
+MCP tools for AI-powered codebase insights and Q&A.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from mcp_server.config import get_project_dir
+from mcp_server.operations import OperationStatus, tracker
+from mcp_server.server import mcp
+from mcp_server.services.insights_service import InsightsService
+
+
+def _get_service() -> InsightsService:
+    return InsightsService(get_project_dir())
+
+
+@mcp.tool()
+async def insights_ask(
+    question: str, history: list | None = None, model: str = "sonnet"
+) -> dict:
+    """Ask an AI question about the codebase. Long-running operation.
+
+    The AI agent has access to the codebase and can read files, search,
+    and explore to answer questions about architecture, patterns, bugs, etc.
+
+    Args:
+        question: The question to ask about the codebase
+        history: Optional conversation history as list of {role, content} dicts
+        model: Model to use (haiku, sonnet, opus)
+
+    Returns:
+        Operation ID to poll with operation_get_status()
+    """
+    service = _get_service()
+    op = tracker.create("insights_ask", "Processing question...")
+
+    async def _run():
+        try:
+            tracker.update(
+                op.id,
+                status=OperationStatus.RUNNING,
+                progress=10,
+                message="AI is exploring the codebase...",
+            )
+            result = await service.ask(question, history, model)
+            if "error" in result:
+                tracker.update(
+                    op.id, status=OperationStatus.FAILED, error=result["error"]
+                )
+            else:
+                tracker.update(
+                    op.id,
+                    status=OperationStatus.COMPLETED,
+                    progress=100,
+                    message="Question answered",
+                    result=result,
+                )
+        except Exception as e:
+            tracker.update(op.id, status=OperationStatus.FAILED, error=str(e))
+
+    op._task = asyncio.create_task(_run())
+    return {
+        "operation_id": op.id,
+        "message": "Insights query started. Poll operation_get_status() for the answer.",
+    }
+
+
+@mcp.tool()
+def insights_suggest_tasks() -> dict:
+    """Get AI-suggested tasks based on recent insights conversations.
+
+    Returns task suggestions derived from ideation data or previous
+    insights conversations.
+
+    Returns:
+        List of task suggestions with title, description, category, impact
+    """
+    service = _get_service()
+    return service.suggest_tasks()

apps/backend/mcp_server/tools/memory.py

@@ -0,0 +1,71 @@
+"""
+Memory Tools
+=============
+
+MCP tools for Graphiti-based semantic memory (knowledge graph).
+Requires GRAPHITI_ENABLED=true in the environment.
+"""
+
+from __future__ import annotations
+
+from mcp_server.config import get_project_dir
+from mcp_server.server import mcp
+from mcp_server.services.memory_service import get_memory_service
+
+
+@mcp.tool()
+async def memory_search(query: str, limit: int = 10) -> dict:
+    """Search the project's semantic memory (Graphiti knowledge graph).
+
+    Finds relevant stored knowledge including codebase discoveries,
+    session insights, patterns, gotchas, and task outcomes.
+
+    Requires GRAPHITI_ENABLED=true in environment.
+
+    Args:
+        query: Search query describing what you're looking for
+        limit: Maximum number of results to return (default 10)
+
+    Returns:
+        List of relevant memory entries with content and relevance scores
+    """
+    service = get_memory_service(get_project_dir())
+    return await service.search(query, limit)
+
+
+@mcp.tool()
+async def memory_add_episode(content: str, source: str = "mcp") -> dict:
+    """Add a new episode/fact to the project's memory.
+
+    Stores information in the knowledge graph for future retrieval.
+    Use this to record insights, patterns, or important findings.
+
+    Requires GRAPHITI_ENABLED=true in environment.
+
+    Args:
+        content: The information to store (insight, pattern, discovery, etc.)
+        source: Source identifier for the episode (default: mcp)
+
+    Returns:
+        Confirmation of successful storage
+    """
+    service = get_memory_service(get_project_dir())
+    return await service.add_episode(content, source)
+
+
+@mcp.tool()
+async def memory_get_recent(limit: int = 10) -> dict:
+    """Get recent memory entries.
+
+    Retrieves the most recent entries from the project's knowledge graph.
+
+    Requires GRAPHITI_ENABLED=true in environment.
+
+    Args:
+        limit: Maximum number of entries to return (default 10)
+
+    Returns:
+        List of recent memory entries
+    """
+    service = get_memory_service(get_project_dir())
+    return await service.get_recent(limit)

apps/backend/mcp_server/tools/ops.py

@@ -0,0 +1,52 @@
+"""
+Operations Management Tools
+============================
+
+Tools for polling long-running operation status and cancelling operations.
+"""
+
+from __future__ import annotations
+
+from mcp_server.operations import tracker
+from mcp_server.server import mcp
+
+
+@mcp.tool()
+def operation_get_status(operation_id: str) -> dict:
+    """Get the status of a long-running operation.
+
+    Use this to poll for progress on operations started by tools like
+    spec_create, build_start, qa_start_review, etc.
+
+    Args:
+        operation_id: The operation ID returned by the tool that started the operation
+
+    Returns:
+        Operation status including progress (0-100), message, and result when complete
+    """
+    op = tracker.get(operation_id)
+    if op is None:
+        return {"error": f"Operation {operation_id} not found"}
+    return op.to_dict()
+
+
+@mcp.tool()
+def operation_cancel(operation_id: str) -> dict:
+    """Cancel a running operation.
+
+    Args:
+        operation_id: The operation ID to cancel
+
+    Returns:
+        Whether the cancellation was successful
+    """
+    success = tracker.cancel(operation_id)
+    if not success:
+        op = tracker.get(operation_id)
+        if op is None:
+            return {"success": False, "error": "Operation not found"}
+        return {
+            "success": False,
+            "error": f"Cannot cancel operation in {op.status.value} state",
+        }
+    return {"success": True, "message": "Operation cancelled"}

apps/backend/mcp_server/tools/project.py

@@ -0,0 +1,148 @@
+"""
+Project Management Tools
+=========================
+
+MCP tools for managing the active project: switching projects,
+getting status, listing specs, and reading the project index.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from mcp_server import config
+from mcp_server.server import mcp
+
+logger = logging.getLogger(__name__)
+
+
+@mcp.tool()
+def project_set_active(project_dir: str) -> dict:
+    """Switch the MCP server to a different project directory.
+
+    Re-initializes the server to point at a new project.
+    All subsequent tool calls will operate on this project.
+
+    Args:
+        project_dir: Absolute path to the project directory
+    """
+    try:
+        config.initialize(project_dir)
+        project_path = config.get_project_dir()
+        initialized = config.is_initialized()
+
+        return {
+            "success": True,
+            "project_dir": str(project_path),
+            "initialized": initialized,
+            "message": f"Active project set to {project_path}",
+        }
+    except (ValueError, RuntimeError) as exc:
+        return {"success": False, "error": str(exc)}
+
+
+@mcp.tool()
+def project_get_status() -> dict:
+    """Get the current project status.
+
+    Returns the active project directory, initialization state,
+    specs count, and project index summary.
+    """
+    try:
+        project_dir = config.get_project_dir()
+    except RuntimeError:
+        return {
+            "initialized": False,
+            "error": "No project set. Use project_set_active() first.",
+        }
+
+    initialized = config.is_initialized()
+    specs_count = 0
+
+    if initialized:
+        specs_dir = config.get_specs_dir()
+        if specs_dir.is_dir():
+            specs_count = sum(
+                1
+                for entry in specs_dir.iterdir()
+                if entry.is_dir() and entry.name != ".gitkeep"
+            )
+
+    index = config.get_project_index()
+
+    return {
+        "project_dir": str(project_dir),
+        "initialized": initialized,
+        "specs_count": specs_count,
+        "has_project_index": bool(index),
+        "project_name": index.get("name", project_dir.name),
+    }
+
+
+@mcp.tool()
+def project_list_specs() -> dict:
+    """List all spec directories with their basic info.
+
+    Returns each spec's name, whether it has a plan/spec file,
+    and status from the implementation plan.
+    """
+    try:
+        specs_dir = config.get_specs_dir()
+    except RuntimeError:
+        return {"error": "No project set. Use project_set_active() first.", "specs": []}
+
+    if not specs_dir.is_dir():
+        return {"specs": [], "message": "No specs directory found."}
+
+    specs: list[dict] = []
+    for entry in sorted(specs_dir.iterdir()):
+        if not entry.is_dir() or entry.name == ".gitkeep":
+            continue
+
+        has_plan = (entry / "implementation_plan.json").exists()
+        has_spec = (entry / "spec.md").exists()
+
+        status = "pending"
+        title = entry.name
+        if has_plan:
+            try:
+                import json
+
+                plan = json.loads(
+                    (entry / "implementation_plan.json").read_text(encoding="utf-8")
+                )
+                status = plan.get("status", "pending")
+                title = plan.get("feature") or plan.get("title") or entry.name
+            except (json.JSONDecodeError, OSError):
+                pass
+
+        specs.append(
+            {
+                "name": entry.name,
+                "title": title,
+                "has_plan": has_plan,
+                "has_spec": has_spec,
+                "has_qa_report": (entry / "qa_report.md").exists(),
+                "status": status,
+            }
+        )
+
+    return {"specs": specs, "count": len(specs)}
+
+
+@mcp.tool()
+def project_get_index() -> dict:
+    """Return the full project_index.json content.
+
+    The project index contains metadata about the project
+    such as file summaries, dependency info, and analysis results.
+    """
+    try:
+        index = config.get_project_index()
+    except RuntimeError:
+        return {"error": "No project set. Use project_set_active() first."}
+
+    if not index:
+        return {"message": "No project index found. Run indexing first.", "index": {}}
+
+    return {"index": index}

apps/backend/mcp_server/tools/qa.py

@@ -0,0 +1,125 @@
+"""
+QA Tools
+=========
+
+MCP tools for running QA reviews, getting reports, and manual approval.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from mcp_server.config import get_project_dir
+from mcp_server.operations import OperationStatus, tracker
+from mcp_server.server import mcp
+
+logger = logging.getLogger(__name__)
+
+
+@mcp.tool()
+async def qa_start_review(spec_id: str) -> dict:
+    """Start QA review for a completed build. This is a long-running operation.
+
+    Runs the QA reviewer agent which validates the implementation against
+    the spec's acceptance criteria. The agent reads code, runs tests, and
+    produces a detailed QA report.
+
+    Args:
+        spec_id: Spec folder name or prefix (e.g. '001' or '001-my-feature')
+
+    Returns:
+        An operation_id to poll with operation_get_status() for progress
+    """
+    op = tracker.create("qa_review", f"QA review for: {spec_id}")
+
+    async def _run() -> None:
+        try:
+            from mcp_server.services.qa_service import QAService
+
+            service = QAService(get_project_dir())
+
+            tracker.update(
+                op.id,
+                status=OperationStatus.RUNNING,
+                progress=10,
+                message="Starting QA review session...",
+            )
+
+            result = await service.start_review(spec_id=spec_id)
+
+            status = result.get("status", "error")
+            if status == "approved":
+                tracker.update(
+                    op.id,
+                    status=OperationStatus.COMPLETED,
+                    progress=100,
+                    message="QA approved - all acceptance criteria validated",
+                    result=result,
+                )
+            elif status == "rejected":
+                tracker.update(
+                    op.id,
+                    status=OperationStatus.COMPLETED,
+                    progress=100,
+                    message="QA rejected - issues found, see report",
+                    result=result,
+                )
+            else:
+                tracker.update(
+                    op.id,
+                    status=OperationStatus.FAILED,
+                    error=result.get("error", "QA review failed"),
+                    result=result,
+                )
+        except Exception as e:
+            logger.exception("qa_start_review operation failed")
+            tracker.update(
+                op.id,
+                status=OperationStatus.FAILED,
+                error=str(e),
+            )
+
+    op._task = asyncio.create_task(_run())
+    return {
+        "operation_id": op.id,
+        "message": "QA review started. Poll operation_get_status() for progress.",
+    }
+
+
+@mcp.tool()
+def qa_get_report(spec_id: str) -> dict:
+    """Get the QA report for a spec.
+
+    Returns the full QA report including validation results, issues found,
+    and the qa_signoff status from the implementation plan.
+
+    Args:
+        spec_id: Spec folder name or prefix
+
+    Returns:
+        QA report content, fix requests, and signoff status
+    """
+    from mcp_server.services.qa_service import QAService
+
+    service = QAService(get_project_dir())
+    return service.get_report(spec_id)
+
+
+@mcp.tool()
+def qa_approve(spec_id: str) -> dict:
+    """Manually approve a spec that's in QA review.
+
+    Use this to bypass the automated QA review and mark a spec as approved.
+    This updates the implementation_plan.json qa_signoff status.
+
+    Args:
+        spec_id: Spec folder name or prefix
+
+    Returns:
+        Whether the approval was successful
+    """
+    from mcp_server.services.qa_service import QAService
+
+    service = QAService(get_project_dir())
+    return service.approve(spec_id)

apps/backend/mcp_server/tools/roadmap.py

@@ -0,0 +1,128 @@
+"""
+Roadmap Tools
+==============
+
+MCP tools for AI-powered strategic roadmap generation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from mcp_server.config import get_project_dir
+from mcp_server.operations import OperationStatus, tracker
+from mcp_server.server import mcp
+from mcp_server.services.roadmap_service import RoadmapService
+
+
+def _get_service() -> RoadmapService:
+    return RoadmapService(get_project_dir())
+
+
+@mcp.tool()
+async def roadmap_generate(refresh: bool = False, model: str = "sonnet") -> dict:
+    """Generate a strategic roadmap for the project. Long-running.
+
+    Analyzes the project structure, existing features, and codebase to
+    generate a phased roadmap with prioritized features.
+
+    Args:
+        refresh: Force regeneration even if a roadmap already exists
+        model: Model to use (haiku, sonnet, opus)
+
+    Returns:
+        Operation ID to poll with operation_get_status()
+    """
+    service = _get_service()
+    op = tracker.create("roadmap_generate", "Starting roadmap generation...")
+
+    async def _run():
+        try:
+            tracker.update(
+                op.id,
+                status=OperationStatus.RUNNING,
+                progress=10,
+                message="Analyzing project for roadmap generation...",
+            )
+            result = await service.generate(refresh=refresh, model=model)
+            if "error" in result:
+                tracker.update(
+                    op.id, status=OperationStatus.FAILED, error=result["error"]
+                )
+            else:
+                tracker.update(
+                    op.id,
+                    status=OperationStatus.COMPLETED,
+                    progress=100,
+                    message="Roadmap generated",
+                    result=result,
+                )
+        except Exception as e:
+            tracker.update(op.id, status=OperationStatus.FAILED, error=str(e))
+
+    op._task = asyncio.create_task(_run())
+    return {
+        "operation_id": op.id,
+        "message": "Roadmap generation started. Poll operation_get_status() for progress.",
+    }
+
+
+@mcp.tool()
+def roadmap_get() -> dict:
+    """Get the current roadmap data.
+
+    Returns the previously generated roadmap including vision, phases,
+    features with priorities, and implementation details.
+
+    Returns:
+        Roadmap data with vision, phases, features, and priority breakdown
+    """
+    service = _get_service()
+    return service.get_roadmap()
+
+
+@mcp.tool()
+async def roadmap_refresh(model: str = "sonnet") -> dict:
+    """Refresh/regenerate the roadmap. Long-running.
+
+    Forces a complete regeneration of the roadmap, analyzing current
+    project state and creating updated phases and features.
+
+    Args:
+        model: Model to use (haiku, sonnet, opus)
+
+    Returns:
+        Operation ID to poll with operation_get_status()
+    """
+    service = _get_service()
+    op = tracker.create("roadmap_refresh", "Starting roadmap refresh...")
+
+    async def _run():
+        try:
+            tracker.update(
+                op.id,
+                status=OperationStatus.RUNNING,
+                progress=10,
+                message="Refreshing roadmap...",
+            )
+            result = await service.generate(refresh=True, model=model)
+            if "error" in result:
+                tracker.update(
+                    op.id, status=OperationStatus.FAILED, error=result["error"]
+                )
+            else:
+                tracker.update(
+                    op.id,
+                    status=OperationStatus.COMPLETED,
+                    progress=100,
+                    message="Roadmap refreshed",
+                    result=result,
+                )
+        except Exception as e:
+            tracker.update(op.id, status=OperationStatus.FAILED, error=str(e))
+
+    op._task = asyncio.create_task(_run())
+    return {
+        "operation_id": op.id,
+        "message": "Roadmap refresh started. Poll operation_get_status() for progress.",
+    }

apps/backend/mcp_server/tools/specs.py

@@ -0,0 +1,149 @@
+"""
+Spec Tools
+===========
+
+MCP tools for creating and inspecting specifications.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from mcp_server.config import get_project_dir
+from mcp_server.operations import OperationStatus, tracker
+from mcp_server.server import mcp
+
+logger = logging.getLogger(__name__)
+
+
+@mcp.tool()
+async def spec_create(
+    task_description: str,
+    model: str = "sonnet",
+    thinking_level: str = "medium",
+) -> dict:
+    """Create a specification for a task. This is a long-running operation.
+
+    The spec creation pipeline runs multiple AI phases (discovery, requirements,
+    complexity assessment, spec writing, planning) to produce a complete
+    implementation-ready specification.
+
+    Args:
+        task_description: What you want to build (be specific and detailed)
+        model: Model to use - 'sonnet' (fast), 'opus' (thorough)
+        thinking_level: How much the AI reasons - 'low', 'medium', 'high'
+
+    Returns:
+        An operation_id to poll with operation_get_status() for progress
+    """
+    op = tracker.create("spec_create", f"Creating spec for: {task_description[:80]}")
+
+    async def _run() -> None:
+        try:
+            from mcp_server.services.spec_service import SpecService
+
+            tracker.update(
+                op.id,
+                status=OperationStatus.RUNNING,
+                progress=5,
+                message="Initializing spec pipeline...",
+            )
+
+            service = SpecService(get_project_dir())
+
+            tracker.update(
+                op.id,
+                status=OperationStatus.RUNNING,
+                progress=10,
+                message="Running spec creation phases...",
+            )
+
+            result = await service.create_spec(
+                task_description=task_description,
+                model=model,
+                thinking_level=thinking_level,
+            )
+
+            if result.get("success"):
+                tracker.update(
+                    op.id,
+                    status=OperationStatus.COMPLETED,
+                    progress=100,
+                    message="Spec created successfully",
+                    result=result,
+                )
+            else:
+                tracker.update(
+                    op.id,
+                    status=OperationStatus.FAILED,
+                    progress=100,
+                    message="Spec creation failed",
+                    error=result.get("error", "Unknown error"),
+                    result=result,
+                )
+        except Exception as e:
+            logger.exception("spec_create operation failed")
+            tracker.update(
+                op.id,
+                status=OperationStatus.FAILED,
+                error=str(e),
+            )
+
+    op._task = asyncio.create_task(_run())
+    return {
+        "operation_id": op.id,
+        "message": "Spec creation started. Poll operation_get_status() for progress.",
+    }
+
+
+@mcp.tool()
+def spec_get_status(spec_id: str) -> dict:
+    """Get the current status of a spec (which phases have completed).
+
+    Shows whether discovery, requirements, spec writing, and planning
+    phases are complete, and the overall readiness state.
+
+    Args:
+        spec_id: Spec folder name or prefix (e.g. '001' or '001-my-feature')
+
+    Returns:
+        Status including completed phases and overall state
+    """
+    from mcp_server.services.spec_service import SpecService
+
+    service = SpecService(get_project_dir())
+    return service.get_spec_status(spec_id)
+
+
+@mcp.tool()
+def spec_get_content(spec_id: str) -> dict:
+    """Get the full content of a spec including spec.md, requirements, and plan.
+
+    Returns the complete specification content so you can understand what
+    will be built and how.
+
+    Args:
+        spec_id: Spec folder name or prefix (e.g. '001' or '001-my-feature')
+
+    Returns:
+        Full spec content including spec.md, requirements.json, implementation_plan.json
+    """
+    from mcp_server.services.spec_service import SpecService
+
+    service = SpecService(get_project_dir())
+    return service.get_spec_content(spec_id)
+
+
+@mcp.tool()
+def spec_list() -> dict:
+    """List all specs in the project with their status.
+
+    Returns:
+        List of specs with their current status and phase completion
+    """
+    from mcp_server.services.spec_service import SpecService
+
+    service = SpecService(get_project_dir())
+    specs = service.list_specs()
+    return {"specs": specs, "count": len(specs)}

apps/backend/mcp_server/tools/tasks.py

@@ -0,0 +1,179 @@
+"""
+Task Management Tools
+======================
+
+MCP tools for CRUD operations on tasks (specs).
+Tasks are stored as spec directories under .auto-claude/specs/.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from mcp_server import config
+from mcp_server.server import mcp
+from mcp_server.services.task_service import VALID_STATUSES, TaskService
+
+logger = logging.getLogger(__name__)
+
+
+def _get_task_service() -> TaskService:
+    """Get a TaskService instance for the active project."""
+    return TaskService(config.get_project_dir())
+
+
+@mcp.tool()
+def task_list() -> dict:
+    """List all tasks with id, title, status, and description preview.
+
+    Scans both the main project and worktree spec directories,
+    deduplicating with main project taking priority.
+    """
+    try:
+        service = _get_task_service()
+    except RuntimeError as exc:
+        return {"error": str(exc), "tasks": []}
+
+    tasks = service.list_tasks()
+
+    # Return a concise view for listing
+    summary = []
+    for t in tasks:
+        desc = t.get("description", "")
+        preview = (desc[:200] + "...") if len(desc) > 200 else desc
+        summary.append(
+            {
+                "spec_id": t["spec_id"],
+                "title": t["title"],
+                "status": t["status"],
+                "description_preview": preview,
+                "has_spec": t.get("has_spec", False),
+                "has_plan": t.get("has_plan", False),
+                "subtask_count": len(t.get("subtasks", [])),
+            }
+        )
+
+    return {"tasks": summary, "count": len(summary)}
+
+
+@mcp.tool()
+def task_create(title: str, description: str) -> dict:
+    """Create a new task (spec directory) with initial files.
+
+    Generates the next spec number automatically and creates
+    the directory with requirements.json, implementation_plan.json,
+    and task_metadata.json.
+
+    Args:
+        title: The task title (used for the directory name slug)
+        description: Full description of what needs to be done
+    """
+    try:
+        service = _get_task_service()
+    except RuntimeError as exc:
+        return {"error": str(exc)}
+
+    if not title or not title.strip():
+        return {"error": "Title is required"}
+    if not description or not description.strip():
+        return {"error": "Description is required"}
+
+    task = service.create_task(title.strip(), description.strip())
+    return {"success": True, "task": task}
+
+
+@mcp.tool()
+def task_get(spec_id: str) -> dict:
+    """Get full task details including subtasks, metadata, and file info.
+
+    Args:
+        spec_id: The spec directory name (e.g., "001-my-feature")
+    """
+    try:
+        service = _get_task_service()
+    except RuntimeError as exc:
+        return {"error": str(exc)}
+
+    task = service.get_task(spec_id)
+    if task is None:
+        return {"error": f"Task '{spec_id}' not found"}
+
+    return {"task": task}
+
+
+@mcp.tool()
+def task_update(
+    spec_id: str,
+    title: str | None = None,
+    description: str | None = None,
+    status: str | None = None,
+) -> dict:
+    """Update task metadata (title, description, and/or status).
+
+    Args:
+        spec_id: The spec directory name (e.g., "001-my-feature")
+        title: New title (optional)
+        description: New description (optional)
+        status: New status (optional) - must be a valid status
+    """
+    try:
+        service = _get_task_service()
+    except RuntimeError as exc:
+        return {"error": str(exc)}
+
+    if status is not None and status not in VALID_STATUSES:
+        return {"error": f"Invalid status '{status}'. Valid: {sorted(VALID_STATUSES)}"}
+
+    task = service.update_task(
+        spec_id, title=title, description=description, status=status
+    )
+    if task is None:
+        return {"error": f"Task '{spec_id}' not found or invalid update"}
+
+    return {"success": True, "task": task}
+
+
+@mcp.tool()
+def task_delete(spec_id: str) -> dict:
+    """Delete a task by removing its spec directory.
+
+    WARNING: This permanently deletes the spec directory and all its contents.
+
+    Args:
+        spec_id: The spec directory name (e.g., "001-my-feature")
+    """
+    try:
+        service = _get_task_service()
+    except RuntimeError as exc:
+        return {"error": str(exc)}
+
+    deleted = service.delete_task(spec_id)
+    if not deleted:
+        return {"error": f"Task '{spec_id}' not found"}
+
+    return {"success": True, "message": f"Task '{spec_id}' deleted"}
+
+
+@mcp.tool()
+def task_update_status(spec_id: str, status: str) -> dict:
+    """Update just the status field of a task.
+
+    Args:
+        spec_id: The spec directory name (e.g., "001-my-feature")
+        status: New status value. Valid statuses: pending, spec_creating,
+                planning, in_progress, qa_review, qa_fixing, human_review,
+                done, failed, cancelled
+    """
+    try:
+        service = _get_task_service()
+    except RuntimeError as exc:
+        return {"error": str(exc)}
+
+    if status not in VALID_STATUSES:
+        return {"error": f"Invalid status '{status}'. Valid: {sorted(VALID_STATUSES)}"}
+
+    task = service.update_status(spec_id, status)
+    if task is None:
+        return {"error": f"Task '{spec_id}' not found"}
+
+    return {"success": True, "task": task}

apps/backend/mcp_server/tools/workspace.py

@@ -0,0 +1,159 @@
+"""
+Workspace Tools
+================
+
+MCP tools for managing git worktrees: list, diff, merge, discard, and PR creation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from mcp_server.config import get_project_dir
+from mcp_server.operations import OperationStatus, tracker
+from mcp_server.server import mcp
+
+logger = logging.getLogger(__name__)
+
+
+@mcp.tool()
+def workspace_list() -> dict:
+    """List all active git worktrees for the project.
+
+    Each spec gets its own isolated worktree. This shows all active
+    worktrees with their branch, change stats, and age.
+
+    Returns:
+        List of worktrees with branch, stats, and age information
+    """
+    from mcp_server.services.workspace_service import WorkspaceService
+
+    service = WorkspaceService(get_project_dir())
+    return service.list_worktrees()
+
+
+@mcp.tool()
+def workspace_diff(spec_id: str) -> dict:
+    """Get the git diff for a spec's worktree.
+
+    Shows all changes made in the spec's branch compared to the base branch,
+    including a file-level summary and the full diff content.
+
+    Args:
+        spec_id: Spec folder name or prefix (e.g. '001' or '001-my-feature')
+
+    Returns:
+        Changed files summary and full diff content
+    """
+    from mcp_server.services.workspace_service import WorkspaceService
+
+    service = WorkspaceService(get_project_dir())
+    return service.get_diff(spec_id)
+
+
+@mcp.tool()
+async def workspace_merge(spec_id: str, strategy: str = "auto") -> dict:
+    """Merge a spec's worktree changes back to the main branch.
+
+    Args:
+        spec_id: Spec folder name or prefix
+        strategy: 'auto' for standard git merge, 'no-commit' to stage without committing
+
+    Returns:
+        Whether the merge was successful
+    """
+    from mcp_server.services.workspace_service import WorkspaceService
+
+    service = WorkspaceService(get_project_dir())
+    return await service.merge(spec_id, strategy=strategy)
+
+
+@mcp.tool()
+def workspace_discard(spec_id: str) -> dict:
+    """Discard a spec's worktree and its branch.
+
+    Permanently removes the worktree directory and deletes the associated
+    git branch. This cannot be undone.
+
+    Args:
+        spec_id: Spec folder name or prefix
+
+    Returns:
+        Whether the discard was successful
+    """
+    from mcp_server.services.workspace_service import WorkspaceService
+
+    service = WorkspaceService(get_project_dir())
+    return service.discard(spec_id)
+
+
+@mcp.tool()
+async def workspace_create_pr(
+    spec_id: str,
+    title: str | None = None,
+    body: str | None = None,
+) -> dict:
+    """Create a pull request from a spec's worktree branch.
+
+    Pushes the branch to origin and creates a PR/MR on the detected
+    git hosting provider (GitHub or GitLab). This is a long-running operation.
+
+    Args:
+        spec_id: Spec folder name or prefix
+        title: PR title (defaults to spec name)
+        body: PR body (defaults to spec summary)
+
+    Returns:
+        An operation_id to poll with operation_get_status() for progress
+    """
+    op = tracker.create("create_pr", f"Creating PR for: {spec_id}")
+
+    async def _run() -> None:
+        try:
+            from mcp_server.services.workspace_service import WorkspaceService
+
+            service = WorkspaceService(get_project_dir())
+
+            tracker.update(
+                op.id,
+                status=OperationStatus.RUNNING,
+                progress=20,
+                message="Pushing branch and creating PR...",
+            )
+
+            result = await service.create_pr(
+                spec_id=spec_id,
+                title=title,
+                body=body,
+            )
+
+            if result.get("success"):
+                pr_url = result.get("pr_url", "")
+                tracker.update(
+                    op.id,
+                    status=OperationStatus.COMPLETED,
+                    progress=100,
+                    message=f"PR created: {pr_url}" if pr_url else "PR created",
+                    result=result,
+                )
+            else:
+                tracker.update(
+                    op.id,
+                    status=OperationStatus.FAILED,
+                    error=result.get("error", "PR creation failed"),
+                    result=result,
+                )
+        except Exception as e:
+            logger.exception("workspace_create_pr operation failed")
+            tracker.update(
+                op.id,
+                status=OperationStatus.FAILED,
+                error=str(e),
+            )
+
+    op._task = asyncio.create_task(_run())
+    return {
+        "operation_id": op.id,
+        "message": "PR creation started. Poll operation_get_status() for progress.",
+    }

apps/backend/qa/loop.py

@@ -215,6 +215,7 @@ async def run_qa_validation_loop(
                         "Removed QA_FIX_REQUEST.md after permanent fixer error",
                     )
                 except OSError:
+                    # File removal failure is not critical here
                     pass
             return False
 
@@ -230,6 +231,7 @@ async def run_qa_validation_loop(
             fix_request_file.unlink()
             debug("qa_loop", "Removed processed QA_FIX_REQUEST.md")
         except OSError:
+            # File removal failure is not critical here
             pass  # Ignore if file removal fails
 
     # Check for no-test projects

apps/backend/runners/github/models.py

@@ -572,6 +572,9 @@ class PRReviewResult:
     )  # IDs of posted findings
     posted_at: str | None = None  # Timestamp when findings were posted
 
+    # In-progress review tracking
+    in_progress_since: str | None = None  # ISO timestamp when active review started
+
     def to_dict(self) -> dict:
         return {
             "pr_number": self.pr_number,
@@ -603,6 +606,8 @@ class PRReviewResult:
             "has_posted_findings": self.has_posted_findings,
             "posted_finding_ids": self.posted_finding_ids,
             "posted_at": self.posted_at,
+            # In-progress review tracking
+            "in_progress_since": self.in_progress_since,
         }
 
     @classmethod
@@ -650,6 +655,8 @@ class PRReviewResult:
             has_posted_findings=data.get("has_posted_findings", False),
             posted_finding_ids=data.get("posted_finding_ids", []),
             posted_at=data.get("posted_at"),
+            # In-progress review tracking
+            in_progress_since=data.get("in_progress_since"),
         )
 
     async def save(self, github_dir: Path) -> None:

apps/backend/runners/github/orchestrator.py

@@ -395,8 +395,28 @@ class GitHubOrchestrator:
                     else:
                         # No existing review found, create skip result
                         return await self._create_skip_result(pr_number, skip_reason)
+                elif "Review already in progress" in skip_reason:
+                    # Return an in-progress result WITHOUT saving to disk
+                    # to avoid overwriting the partial result being written by the active review
+                    started_at = self.bot_detector.state.in_progress_reviews.get(
+                        str(pr_number)
+                    )
+                    safe_print(
+                        f"[BOT DETECTION] Review in progress for PR #{pr_number} "
+                        f"(started: {started_at})",
+                        flush=True,
+                    )
+                    return PRReviewResult(
+                        pr_number=pr_number,
+                        repo=self.config.repo,
+                        success=True,
+                        findings=[],
+                        summary="Review in progress",
+                        overall_status="in_progress",
+                        in_progress_since=started_at,
+                    )
                 else:
-                    # For other skip reasons (bot-authored, cooling off, in-progress), create a skip result
+                    # For other skip reasons (bot-authored, cooling off), create a skip result
                     return await self._create_skip_result(pr_number, skip_reason)
 
             # Mark review as started (prevents concurrent reviews)

apps/backend/runners/github/runner.py

@@ -235,6 +235,12 @@ async def cmd_review_pr(args) -> int:
         safe_print(f"[DEBUG] review_pr returned, success={result.success}")
 
     if result.success:
+        # For in_progress results (not saved to disk), output JSON so the frontend
+        # can parse it from stdout instead of relying on the disk file.
+        if result.overall_status == "in_progress":
+            safe_print(f"__RESULT_JSON__:{json.dumps(result.to_dict())}")
+            return 0
+
         safe_print(f"\n{'=' * 60}")
         safe_print(f"PR #{result.pr_number} Review Complete")
         safe_print(f"{'=' * 60}")

apps/backend/runners/github/services/followup_reviewer.py

@@ -25,6 +25,8 @@ if TYPE_CHECKING:
     from ..models import FollowupReviewContext, GitHubRunnerConfig
 
 try:
+    from ...core.client import create_client
+    from ...phase_config import resolve_model_id
     from ..gh_client import GHClient
     from ..models import (
         MergeVerdict,
@@ -37,8 +39,11 @@ try:
     from .category_utils import map_category
     from .io_utils import safe_print
     from .prompt_manager import PromptManager
-    from .pydantic_models import FollowupReviewResponse
+    from .pydantic_models import FollowupExtractionResponse, FollowupReviewResponse
+    from .recovery_utils import create_finding_from_summary
+    from .sdk_utils import process_sdk_stream
 except (ImportError, ValueError, SystemError):
+    from core.client import create_client
     from gh_client import GHClient
     from models import (
         MergeVerdict,
@@ -48,10 +53,16 @@ except (ImportError, ValueError, SystemError):
         ReviewSeverity,
         _utc_now_iso,
     )
+    from phase_config import resolve_model_id
     from services.category_utils import map_category
     from services.io_utils import safe_print
     from services.prompt_manager import PromptManager
-    from services.pydantic_models import FollowupReviewResponse
+    from services.pydantic_models import (
+        FollowupExtractionResponse,
+        FollowupReviewResponse,
+    )
+    from services.recovery_utils import create_finding_from_summary
+    from services.sdk_utils import process_sdk_stream
 
 logger = logging.getLogger(__name__)
 
@@ -698,6 +709,9 @@ Analyze this follow-up review context and provide your structured response.
             )
             safe_print(f"[Followup] SDK query with output_format, model={model}")
 
+            # Capture assistant text for extraction fallback
+            captured_text = ""
+
             # Iterate through messages from the query
             # Note: max_turns=2 because structured output uses a tool call + response
             async for message in query(
@@ -722,7 +736,9 @@ Analyze this follow-up review context and provide your structured response.
                     content = getattr(message, "content", [])
                     for block in content:
                         block_type = type(block).__name__
-                        if block_type == "ToolUseBlock":
+                        if block_type == "TextBlock":
+                            captured_text += getattr(block, "text", "")
+                        elif block_type == "ToolUseBlock":
                             tool_name = getattr(block, "name", "")
                             if tool_name == "StructuredOutput":
                                 # Extract structured data from tool input
@@ -765,9 +781,31 @@ Analyze this follow-up review context and provide your structured response.
                         logger.warning(
                             "Claude could not produce valid structured output after retries"
                         )
+                        # Attempt extraction call recovery before giving up
+                        if captured_text:
+                            safe_print(
+                                "[Followup] Attempting extraction call recovery...",
+                                flush=True,
+                            )
+                            extraction_result = await self._attempt_extraction_call(
+                                captured_text, context
+                            )
+                            if extraction_result is not None:
+                                return extraction_result
                         return None
 
             logger.warning("No structured output received from AI")
+            # Attempt extraction call recovery before giving up
+            if captured_text:
+                safe_print(
+                    "[Followup] No structured output — attempting extraction call recovery...",
+                    flush=True,
+                )
+                extraction_result = await self._attempt_extraction_call(
+                    captured_text, context
+                )
+                if extraction_result is not None:
+                    return extraction_result
             return None
 
         except ValueError as e:
@@ -840,6 +878,115 @@ Analyze this follow-up review context and provide your structured response.
             "verdict_reasoning": result.verdict_reasoning,
         }
 
+    async def _attempt_extraction_call(
+        self,
+        text: str,
+        context: FollowupReviewContext,
+    ) -> dict[str, Any] | None:
+        """Attempt a short SDK call with minimal schema to recover review data.
+
+        This is the extraction recovery step when full structured output validation fails.
+        Uses FollowupExtractionResponse (~6 flat fields) which has near-100% success rate.
+
+        Uses create_client() + process_sdk_stream() for proper OAuth handling,
+        matching the pattern in parallel_followup_reviewer.py.
+
+        Returns parsed result dict on success, None on failure.
+        """
+        if not text or not text.strip():
+            return None
+
+        try:
+            extraction_prompt = (
+                "Extract the key review data from the following AI analysis output. "
+                "Return the verdict, reasoning, resolved finding IDs, unresolved finding IDs, "
+                "one-line summaries of any new findings, and counts of confirmed/dismissed findings.\n\n"
+                f"--- AI ANALYSIS OUTPUT ---\n{text[:8000]}\n--- END ---"
+            )
+
+            model_shorthand = self.config.model or "sonnet"
+            model = resolve_model_id(model_shorthand)
+
+            extraction_client = create_client(
+                project_dir=self.project_dir,
+                spec_dir=self.github_dir,
+                model=model,
+                agent_type="pr_followup_extraction",
+                output_format={
+                    "type": "json_schema",
+                    "schema": FollowupExtractionResponse.model_json_schema(),
+                },
+            )
+
+            async with extraction_client:
+                await extraction_client.query(extraction_prompt)
+
+                stream_result = await process_sdk_stream(
+                    client=extraction_client,
+                    context_name="FollowupExtraction",
+                    model=model,
+                    system_prompt=extraction_prompt,
+                    max_messages=20,
+                )
+
+            if stream_result.get("error"):
+                logger.warning(
+                    f"[Followup] Extraction call also failed: {stream_result['error']}"
+                )
+                return None
+
+            extraction_output = stream_result.get("structured_output")
+            if not extraction_output:
+                logger.warning(
+                    "[Followup] Extraction call returned no structured output"
+                )
+                return None
+
+            extracted = FollowupExtractionResponse.model_validate(extraction_output)
+
+            # Convert extraction to internal format with reconstructed findings
+            new_findings = []
+            for i, summary in enumerate(extracted.new_finding_summaries):
+                new_findings.append(
+                    create_finding_from_summary(summary, i, id_prefix="FR")
+                )
+
+            # Build finding_resolutions from extraction data for _apply_ai_resolutions
+            # (unresolved findings are handled via finding_resolutions + _apply_ai_resolutions)
+            finding_resolutions = []
+            for fid in extracted.resolved_finding_ids:
+                finding_resolutions.append(
+                    {"finding_id": fid, "status": "resolved", "resolution_notes": None}
+                )
+            for fid in extracted.unresolved_finding_ids:
+                finding_resolutions.append(
+                    {
+                        "finding_id": fid,
+                        "status": "unresolved",
+                        "resolution_notes": None,
+                    }
+                )
+
+            safe_print(
+                f"[Followup] Extraction recovered: verdict={extracted.verdict}, "
+                f"{len(extracted.resolved_finding_ids)} resolved, "
+                f"{len(extracted.unresolved_finding_ids)} unresolved, "
+                f"{len(new_findings)} new findings",
+                flush=True,
+            )
+
+            return {
+                "finding_resolutions": finding_resolutions,
+                "new_findings": new_findings,
+                "comment_findings": [],
+                "verdict": extracted.verdict,
+                "verdict_reasoning": f"[Recovered via extraction] {extracted.verdict_reasoning}",
+            }
+
+        except Exception as e:
+            logger.warning(f"[Followup] Extraction call failed: {e}")
+            return None
+
     def _apply_ai_resolutions(
         self,
         previous_findings: list[PRReviewFinding],

apps/backend/runners/github/services/parallel_followup_reviewer.py

@@ -52,6 +52,7 @@ try:
     from .io_utils import safe_print
     from .pr_worktree_manager import PRWorktreeManager
     from .pydantic_models import FollowupExtractionResponse, ParallelFollowupResponse
+    from .recovery_utils import create_finding_from_summary
     from .sdk_utils import process_sdk_stream
 except (ImportError, ValueError, SystemError):
     from context_gatherer import _validate_git_ref
@@ -79,6 +80,7 @@ except (ImportError, ValueError, SystemError):
         FollowupExtractionResponse,
         ParallelFollowupResponse,
     )
+    from services.recovery_utils import create_finding_from_summary
     from services.sdk_utils import process_sdk_stream
 
 
@@ -1199,18 +1201,52 @@ The SDK will run invoked agents in parallel automatically.
             }
             verdict = verdict_map.get(extracted.verdict, MergeVerdict.NEEDS_REVISION)
 
+            # Reconstruct findings from extraction data
+            findings = []
+            new_finding_ids = []
+
+            # 1. Convert new_finding_summaries to minimal PRReviewFinding objects
+            # Uses shared helper for "SEVERITY: description" parsing and ID generation
+            for i, summary in enumerate(extracted.new_finding_summaries):
+                finding = create_finding_from_summary(summary, i, id_prefix="FU")
+                new_finding_ids.append(finding.id)
+                findings.append(finding)
+
+            # 2. Reconstruct unresolved findings from previous review context
+            if extracted.unresolved_finding_ids and context.previous_review.findings:
+                previous_map = {f.id: f for f in context.previous_review.findings}
+                for uid in extracted.unresolved_finding_ids:
+                    original = previous_map.get(uid)
+                    if original:
+                        findings.append(
+                            PRReviewFinding(
+                                id=original.id,
+                                severity=original.severity,
+                                category=original.category,
+                                title=f"[UNRESOLVED] {original.title}",
+                                description=original.description,
+                                file=original.file,
+                                line=original.line,
+                                suggested_fix=original.suggested_fix,
+                                fixable=original.fixable,
+                                is_impact_finding=original.is_impact_finding,
+                            )
+                        )
+
             safe_print(
                 f"[ParallelFollowup] Extraction recovered: verdict={extracted.verdict}, "
                 f"{len(extracted.resolved_finding_ids)} resolved, "
-                f"{len(extracted.new_finding_summaries)} new findings",
+                f"{len(extracted.unresolved_finding_ids)} unresolved, "
+                f"{len(new_finding_ids)} new findings, "
+                f"{len(findings)} total findings reconstructed",
                 flush=True,
             )
 
             return {
-                "findings": [],  # Full findings not recoverable via extraction
+                "findings": findings,
                 "resolved_ids": extracted.resolved_finding_ids,
                 "unresolved_ids": extracted.unresolved_finding_ids,
-                "new_finding_ids": [],
+                "new_finding_ids": new_finding_ids,
                 "dismissed_false_positive_ids": [],
                 "confirmed_valid_count": extracted.confirmed_finding_count,
                 "dismissed_finding_count": extracted.dismissed_finding_count,
@@ -1250,6 +1286,7 @@ The SDK will run invoked agents in parallel automatically.
 
         This handles cases where the AI produced valid data but it doesn't exactly
         match the expected schema (missing optional fields, type mismatches, etc.).
+        Defensively extracts findings from the raw dict so partial results are preserved.
         """
         if not isinstance(data, dict):
             return None
@@ -1257,6 +1294,7 @@ The SDK will run invoked agents in parallel automatically.
         resolved_ids = []
         unresolved_ids = []
         new_finding_ids = []
+        findings = []
 
         # Try to extract resolution verifications
         resolution_verifications = data.get("resolution_verifications", [])
@@ -1275,14 +1313,68 @@ The SDK will run invoked agents in parallel automatically.
                         ):
                             unresolved_ids.append(finding_id)
 
-        # Try to extract new findings
-        new_findings = data.get("new_findings", [])
-        if isinstance(new_findings, list):
-            for nf in new_findings:
-                if isinstance(nf, dict):
-                    finding_id = nf.get("id", "")
-                    if finding_id:
-                        new_finding_ids.append(finding_id)
+        # Try to extract new findings as PRReviewFinding objects
+        new_findings_raw = data.get("new_findings", [])
+        if isinstance(new_findings_raw, list):
+            for nf in new_findings_raw:
+                if not isinstance(nf, dict):
+                    continue
+                try:
+                    finding_id = nf.get("id", "") or self._generate_finding_id(
+                        nf.get("file", "unknown"),
+                        nf.get("line", 0),
+                        nf.get("title", "unknown"),
+                    )
+                    new_finding_ids.append(finding_id)
+                    findings.append(
+                        PRReviewFinding(
+                            id=finding_id,
+                            severity=_map_severity(nf.get("severity", "medium")),
+                            category=map_category(nf.get("category", "quality")),
+                            title=nf.get("title", "Unknown issue"),
+                            description=nf.get("description", ""),
+                            file=nf.get("file", "unknown"),
+                            line=nf.get("line", 0) or 0,
+                            suggested_fix=nf.get("suggested_fix"),
+                            fixable=bool(nf.get("fixable", False)),
+                            is_impact_finding=bool(nf.get("is_impact_finding", False)),
+                        )
+                    )
+                except Exception as e:
+                    logger.debug(
+                        f"[ParallelFollowup] Skipping malformed new finding: {e}"
+                    )
+
+        # Try to extract comment findings as PRReviewFinding objects
+        comment_findings_raw = data.get("comment_findings", [])
+        if isinstance(comment_findings_raw, list):
+            for cf in comment_findings_raw:
+                if not isinstance(cf, dict):
+                    continue
+                try:
+                    finding_id = cf.get("id", "") or self._generate_finding_id(
+                        cf.get("file", "unknown"),
+                        cf.get("line", 0),
+                        cf.get("title", "unknown"),
+                    )
+                    new_finding_ids.append(finding_id)
+                    findings.append(
+                        PRReviewFinding(
+                            id=finding_id,
+                            severity=_map_severity(cf.get("severity", "medium")),
+                            category=map_category(cf.get("category", "quality")),
+                            title=f"[FROM COMMENTS] {cf.get('title', 'Unknown issue')}",
+                            description=cf.get("description", ""),
+                            file=cf.get("file", "unknown"),
+                            line=cf.get("line", 0) or 0,
+                            suggested_fix=cf.get("suggested_fix"),
+                            fixable=bool(cf.get("fixable", False)),
+                        )
+                    )
+                except Exception as e:
+                    logger.debug(
+                        f"[ParallelFollowup] Skipping malformed comment finding: {e}"
+                    )
 
         # Try to extract verdict
         verdict_str = data.get("verdict", "NEEDS_REVISION")
@@ -1297,14 +1389,15 @@ The SDK will run invoked agents in parallel automatically.
         verdict_reasoning = data.get("verdict_reasoning", "Extracted from partial data")
 
         # Only return if we got any useful data
-        if resolved_ids or unresolved_ids or new_finding_ids:
+        if resolved_ids or unresolved_ids or new_finding_ids or findings:
             return {
-                "findings": [],  # Can't reliably extract full findings without validation
+                "findings": findings,
                 "resolved_ids": resolved_ids,
                 "unresolved_ids": unresolved_ids,
                 "new_finding_ids": new_finding_ids,
                 "dismissed_false_positive_ids": [],
                 "confirmed_valid_count": 0,
+                "dismissed_finding_count": 0,
                 "needs_human_review_count": 0,
                 "verdict": verdict,
                 "verdict_reasoning": f"[Partial extraction] {verdict_reasoning}",

apps/backend/runners/github/services/parallel_orchestrator_reviewer.py

@@ -633,7 +633,14 @@ Report findings with specific file paths, line numbers, and code evidence.
                 logger.error(
                     f"[Specialist:{specialist_name}] Failed to parse structured output: {e}"
                 )
-                # Fall through to text parsing
+                # Attempt to extract findings from raw dict before falling to text parsing
+                findings = self._extract_specialist_partial_data(
+                    specialist_name, structured_output
+                )
+                if findings:
+                    logger.info(
+                        f"[Specialist:{specialist_name}] Recovered {len(findings)} findings from partial extraction"
+                    )
 
         if not findings and result_text:
             # Fallback to text parsing
@@ -643,6 +650,63 @@ Report findings with specific file paths, line numbers, and code evidence.
 
         return findings
 
+    def _extract_specialist_partial_data(
+        self,
+        specialist_name: str,
+        data: dict[str, Any],
+    ) -> list[PRReviewFinding]:
+        """Extract findings from raw specialist dict when Pydantic validation fails.
+
+        Defensively extracts each finding individually so partial results are preserved
+        even if some findings have validation issues.
+        """
+        findings = []
+        raw_findings = data.get("findings", [])
+        if not isinstance(raw_findings, list):
+            return findings
+
+        for f in raw_findings:
+            if not isinstance(f, dict):
+                continue
+            try:
+                file_path = f.get("file", "unknown")
+                line = f.get("line", 0) or 0
+                title = f.get("title", "Unknown issue")
+
+                finding_id = hashlib.md5(
+                    f"{file_path}:{line}:{title}".encode(),
+                    usedforsecurity=False,
+                ).hexdigest()[:12]
+
+                category = map_category(f.get("category", "quality"))
+
+                try:
+                    severity = ReviewSeverity(str(f.get("severity", "medium")).lower())
+                except ValueError:
+                    severity = ReviewSeverity.MEDIUM
+
+                finding = PRReviewFinding(
+                    id=finding_id,
+                    file=file_path,
+                    line=line,
+                    end_line=f.get("end_line"),
+                    title=title,
+                    description=f.get("description", ""),
+                    category=category,
+                    severity=severity,
+                    suggested_fix=f.get("suggested_fix", ""),
+                    evidence=f.get("evidence"),
+                    source_agents=[specialist_name],
+                    is_impact_finding=bool(f.get("is_impact_finding", False)),
+                )
+                findings.append(finding)
+            except Exception as e:
+                logger.debug(
+                    f"[Specialist:{specialist_name}] Skipping malformed finding: {e}"
+                )
+
+        return findings
+
     async def _run_parallel_specialists(
         self,
         context: PRContext,
@@ -910,13 +974,15 @@ The SDK will run invoked agents in parallel automatically.
         except ValueError:
             severity = ReviewSeverity.MEDIUM
 
-        # Extract evidence: prefer verification.code_examined, fallback to evidence field
-        evidence = finding_data.evidence
+        # Extract evidence from verification.code_examined if available
+        evidence = None
         if hasattr(finding_data, "verification") and finding_data.verification:
-            # Structured verification has more detailed evidence
             verification = finding_data.verification
             if hasattr(verification, "code_examined") and verification.code_examined:
                 evidence = verification.code_examined
+        # Fallback to evidence field if present (e.g. from dict-based parsing)
+        if not evidence:
+            evidence = getattr(finding_data, "evidence", None)
 
         # Extract end_line if present
         end_line = getattr(finding_data, "end_line", None)
@@ -1806,6 +1872,7 @@ For EACH finding above:
                         break
 
             except Exception as e:
+                # Part of retry loop structure - handles retryable errors
                 error_str = str(e).lower()
                 is_retryable = (
                     "400" in error_str

apps/backend/runners/github/services/pydantic_models.py

@@ -26,10 +26,10 @@ from __future__ import annotations
 
 from typing import Literal
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
 
 # =============================================================================
-# Verification Evidence (Required for All Findings)
+# Verification Evidence (Optional for findings — only code_examined is consumed)
 # =============================================================================
 
 
@@ -50,102 +50,28 @@ class VerificationEvidence(BaseModel):
 
 
 # =============================================================================
-# Common Finding Types
+# Severity / Category Validators
 # =============================================================================
 
-
-class BaseFinding(BaseModel):
-    """Base class for all finding types."""
-
-    id: str = Field(description="Unique identifier for this finding")
-    severity: Literal["critical", "high", "medium", "low"] = Field(
-        description="Issue severity level"
-    )
-    title: str = Field(description="Brief issue title (max 80 chars)")
-    description: str = Field(description="Detailed explanation of the issue")
-    file: str = Field(description="File path where issue was found")
-    line: int = Field(0, description="Line number of the issue")
-    suggested_fix: str | None = Field(None, description="How to fix this issue")
-    fixable: bool = Field(False, description="Whether this can be auto-fixed")
-    evidence: str | None = Field(
-        None,
-        description="DEPRECATED: Use verification.code_examined instead. Will be removed in Phase 5.",
-    )
-    verification: VerificationEvidence = Field(
-        description="Evidence that this finding was verified against actual code"
-    )
+_VALID_SEVERITIES = {"critical", "high", "medium", "low"}
 
 
-class SecurityFinding(BaseFinding):
-    """A security vulnerability finding."""
-
-    category: Literal["security"] = Field(
-        default="security", description="Always 'security' for security findings"
-    )
+def _normalize_severity(v: str) -> str:
+    """Normalize severity to a valid value, defaulting to 'medium'."""
+    if isinstance(v, str):
+        v = v.lower().strip()
+    if v not in _VALID_SEVERITIES:
+        return "medium"
+    return v
 
 
-class QualityFinding(BaseFinding):
-    """A code quality or redundancy finding."""
-
-    category: Literal[
-        "redundancy", "quality", "test", "performance", "pattern", "docs"
-    ] = Field(description="Issue category")
-    redundant_with: str | None = Field(
-        None, description="Reference to duplicate code (file:line) if redundant"
-    )
-
-
-class DeepAnalysisFinding(BaseFinding):
-    """A finding from deep analysis with verification info."""
-
-    category: Literal[
-        "verification_failed",
-        "redundancy",
-        "quality",
-        "pattern",
-        "performance",
-        "logic",
-    ] = Field(description="Issue category")
-    verification_note: str | None = Field(
-        None, description="What evidence is missing or couldn't be verified"
-    )
-
-
-class StructuralIssue(BaseModel):
-    """A structural issue with the PR."""
-
-    id: str = Field(description="Unique identifier")
-    issue_type: Literal[
-        "feature_creep", "scope_creep", "architecture_violation", "poor_structure"
-    ] = Field(description="Type of structural issue")
-    severity: Literal["critical", "high", "medium", "low"] = Field(
-        description="Issue severity"
-    )
-    title: str = Field(description="Brief issue title")
-    description: str = Field(description="Detailed explanation")
-    impact: str = Field(description="Why this matters")
-    suggestion: str = Field(description="How to fix")
-
-
-class AICommentTriage(BaseModel):
-    """Triage result for an AI tool comment."""
-
-    comment_id: int = Field(description="GitHub comment ID")
-    tool_name: str = Field(
-        description="AI tool name (CodeRabbit, Cursor, Greptile, etc.)"
-    )
-    verdict: Literal[
-        "critical",
-        "important",
-        "nice_to_have",
-        "trivial",
-        "addressed",
-        "false_positive",
-    ] = Field(description="Verdict on the comment")
-    reasoning: str = Field(description="Why this verdict was chosen")
-    response_comment: str | None = Field(
-        None, description="Optional comment to post in reply"
-    )
+def _normalize_category(v: str, valid_set: set[str], default: str = "quality") -> str:
+    """Normalize category to a valid value, defaulting to given default."""
+    if isinstance(v, str):
+        v = v.lower().strip().replace("-", "_")
+    if v not in valid_set:
+        return default
+    return v
 
 
 # =============================================================================
@@ -163,25 +89,34 @@ class FindingResolution(BaseModel):
     )
 
 
+_FOLLOWUP_CATEGORIES = {"security", "quality", "logic", "test", "docs"}
+
+
 class FollowupFinding(BaseModel):
-    """A new finding from follow-up review (simpler than initial review)."""
+    """A new finding from follow-up review (simpler than initial review).
+
+    verification is intentionally omitted — not consumed by followup_reviewer.py.
+    """
 
     id: str = Field(description="Unique identifier for this finding")
-    severity: Literal["critical", "high", "medium", "low"] = Field(
-        description="Issue severity level"
-    )
-    category: Literal["security", "quality", "logic", "test", "docs"] = Field(
-        description="Issue category"
-    )
+    severity: str = Field(description="Issue severity level")
+    category: str = Field(description="Issue category")
     title: str = Field(description="Brief issue title")
     description: str = Field(description="Detailed explanation of the issue")
     file: str = Field(description="File path where issue was found")
     line: int = Field(0, description="Line number of the issue")
     suggested_fix: str | None = Field(None, description="How to fix this issue")
     fixable: bool = Field(False, description="Whether this can be auto-fixed")
-    verification: VerificationEvidence = Field(
-        description="Evidence that this finding was verified against actual code"
-    )
+
+    @field_validator("severity", mode="before")
+    @classmethod
+    def _normalize_severity(cls, v: str) -> str:
+        return _normalize_severity(v)
+
+    @field_validator("category", mode="before")
+    @classmethod
+    def _normalize_category(cls, v: str) -> str:
+        return _normalize_category(v, _FOLLOWUP_CATEGORIES)
 
 
 class FollowupReviewResponse(BaseModel):
@@ -203,81 +138,6 @@ class FollowupReviewResponse(BaseModel):
     verdict_reasoning: str = Field(description="Explanation for the verdict")
 
 
-# =============================================================================
-# Initial Review Responses (Multi-Pass)
-# =============================================================================
-
-
-class QuickScanResult(BaseModel):
-    """Result from the quick scan pass."""
-
-    purpose: str = Field(description="Brief description of what the PR claims to do")
-    actual_changes: str = Field(
-        description="Brief description of what the code actually does"
-    )
-    purpose_match: bool = Field(
-        description="Whether actual changes match the claimed purpose"
-    )
-    purpose_match_note: str | None = Field(
-        None, description="Explanation if purpose doesn't match actual changes"
-    )
-    risk_areas: list[str] = Field(
-        default_factory=list, description="Areas needing careful review"
-    )
-    red_flags: list[str] = Field(
-        default_factory=list, description="Obvious issues or concerns"
-    )
-    requires_deep_verification: bool = Field(
-        description="Whether deep verification is needed"
-    )
-    complexity: Literal["low", "medium", "high"] = Field(description="PR complexity")
-
-
-class SecurityPassResult(BaseModel):
-    """Result from the security pass - array of security findings."""
-
-    findings: list[SecurityFinding] = Field(
-        default_factory=list, description="Security vulnerabilities found"
-    )
-
-
-class QualityPassResult(BaseModel):
-    """Result from the quality pass - array of quality findings."""
-
-    findings: list[QualityFinding] = Field(
-        default_factory=list, description="Quality and redundancy issues found"
-    )
-
-
-class DeepAnalysisResult(BaseModel):
-    """Result from the deep analysis pass."""
-
-    findings: list[DeepAnalysisFinding] = Field(
-        default_factory=list,
-        description="Deep analysis findings with verification info",
-    )
-
-
-class StructuralPassResult(BaseModel):
-    """Result from the structural pass."""
-
-    issues: list[StructuralIssue] = Field(
-        default_factory=list, description="Structural issues found"
-    )
-    verdict: Literal[
-        "READY_TO_MERGE", "MERGE_WITH_CHANGES", "NEEDS_REVISION", "BLOCKED"
-    ] = Field(description="Structural verdict")
-    verdict_reasoning: str = Field(description="Explanation for the verdict")
-
-
-class AICommentTriageResult(BaseModel):
-    """Result from AI comment triage pass."""
-
-    triages: list[AICommentTriage] = Field(
-        default_factory=list, description="Triage results for each AI comment"
-    )
-
-
 # =============================================================================
 # Issue Triage Response
 # =============================================================================
@@ -320,88 +180,21 @@ class IssueTriageResponse(BaseModel):
     comment: str | None = Field(None, description="Optional bot comment to post")
 
 
-# =============================================================================
-# Orchestrator Review Response
-# =============================================================================
-
-
-class OrchestratorFinding(BaseModel):
-    """A finding from the orchestrator review."""
-
-    file: str = Field(description="File path where issue was found")
-    line: int = Field(0, description="Line number of the issue")
-    title: str = Field(description="Brief issue title")
-    description: str = Field(description="Detailed explanation of the issue")
-    category: Literal[
-        "security",
-        "quality",
-        "style",
-        "docs",
-        "redundancy",
-        "verification_failed",
-        "pattern",
-        "performance",
-        "logic",
-        "test",
-    ] = Field(description="Issue category")
-    severity: Literal["critical", "high", "medium", "low"] = Field(
-        description="Issue severity level"
-    )
-    suggestion: str | None = Field(None, description="How to fix this issue")
-    evidence: str | None = Field(
-        None,
-        description="DEPRECATED: Use verification.code_examined instead. Will be removed in Phase 5.",
-    )
-    verification: VerificationEvidence = Field(
-        description="Evidence that this finding was verified against actual code"
-    )
-
-
-class OrchestratorReviewResponse(BaseModel):
-    """Complete response schema for orchestrator PR review."""
-
-    verdict: Literal[
-        "READY_TO_MERGE", "MERGE_WITH_CHANGES", "NEEDS_REVISION", "BLOCKED"
-    ] = Field(description="Overall merge verdict")
-    verdict_reasoning: str = Field(description="Explanation for the verdict")
-    findings: list[OrchestratorFinding] = Field(
-        default_factory=list, description="Issues found during review"
-    )
-    summary: str = Field(description="Brief summary of the review")
-
-
 # =============================================================================
 # Parallel Orchestrator Review Response (SDK Subagents)
 # =============================================================================
 
-
-class LogicFinding(BaseFinding):
-    """A logic/correctness finding from the logic review agent."""
-
-    category: Literal["logic"] = Field(
-        default="logic", description="Always 'logic' for logic findings"
-    )
-    example_input: str | None = Field(
-        None, description="Concrete input that triggers the bug"
-    )
-    actual_output: str | None = Field(None, description="What the buggy code produces")
-    expected_output: str | None = Field(
-        None, description="What the code should produce"
-    )
-
-
-class CodebaseFitFinding(BaseFinding):
-    """A codebase fit finding from the codebase fit review agent."""
-
-    category: Literal["codebase_fit"] = Field(
-        default="codebase_fit", description="Always 'codebase_fit' for fit findings"
-    )
-    existing_code: str | None = Field(
-        None, description="Reference to existing code that should be used instead"
-    )
-    codebase_pattern: str | None = Field(
-        None, description="Description of the established pattern being violated"
-    )
+_ORCHESTRATOR_CATEGORIES = {
+    "security",
+    "quality",
+    "logic",
+    "codebase_fit",
+    "test",
+    "docs",
+    "redundancy",
+    "pattern",
+    "performance",
+}
 
 
 class ParallelOrchestratorFinding(BaseModel):
@@ -413,26 +206,11 @@ class ParallelOrchestratorFinding(BaseModel):
     end_line: int | None = Field(None, description="End line for multi-line issues")
     title: str = Field(description="Brief issue title (max 80 chars)")
     description: str = Field(description="Detailed explanation of the issue")
-    category: Literal[
-        "security",
-        "quality",
-        "logic",
-        "codebase_fit",
-        "test",
-        "docs",
-        "redundancy",
-        "pattern",
-        "performance",
-    ] = Field(description="Issue category")
-    severity: Literal["critical", "high", "medium", "low"] = Field(
-        description="Issue severity level"
-    )
-    evidence: str | None = Field(
+    category: str = Field(description="Issue category")
+    severity: str = Field(description="Issue severity level")
+    verification: VerificationEvidence | None = Field(
         None,
-        description="DEPRECATED: Use verification.code_examined instead. Will be removed in Phase 5.",
-    )
-    verification: VerificationEvidence = Field(
-        description="Evidence that this finding was verified against actual code"
+        description="Evidence that this finding was verified against actual code",
     )
     is_impact_finding: bool = Field(
         False,
@@ -459,6 +237,16 @@ class ParallelOrchestratorFinding(BaseModel):
         False, description="Whether multiple agents agreed on this finding"
     )
 
+    @field_validator("severity", mode="before")
+    @classmethod
+    def _normalize_severity(cls, v: str) -> str:
+        return _normalize_severity(v)
+
+    @field_validator("category", mode="before")
+    @classmethod
+    def _normalize_category(cls, v: str) -> str:
+        return _normalize_category(v, _ORCHESTRATOR_CATEGORIES)
+
 
 class AgentAgreement(BaseModel):
     """Tracks agreement between agents on findings."""
@@ -514,15 +302,22 @@ class ValidationSummary(BaseModel):
     )
 
 
+_SPECIALIST_CATEGORIES = {
+    "security",
+    "quality",
+    "logic",
+    "performance",
+    "pattern",
+    "test",
+    "docs",
+}
+
+
 class SpecialistFinding(BaseModel):
     """A finding from a specialist agent (used in parallel SDK sessions)."""
 
-    severity: Literal["critical", "high", "medium", "low"] = Field(
-        description="Issue severity level"
-    )
-    category: Literal[
-        "security", "quality", "logic", "performance", "pattern", "test", "docs"
-    ] = Field(description="Issue category")
+    severity: str = Field(description="Issue severity level")
+    category: str = Field(description="Issue category")
     title: str = Field(description="Brief issue title (max 80 chars)")
     description: str = Field(description="Detailed explanation of the issue")
     file: str = Field(description="File path where issue was found")
@@ -530,14 +325,24 @@ class SpecialistFinding(BaseModel):
     end_line: int | None = Field(None, description="End line number if multi-line")
     suggested_fix: str | None = Field(None, description="How to fix this issue")
     evidence: str = Field(
-        min_length=1,
-        description="Actual code snippet examined that shows the issue. Required.",
+        default="",
+        description="Actual code snippet examined that shows the issue.",
     )
     is_impact_finding: bool = Field(
         False,
         description="True if this is about affected code outside the PR (callers, dependencies)",
     )
 
+    @field_validator("severity", mode="before")
+    @classmethod
+    def _normalize_severity(cls, v: str) -> str:
+        return _normalize_severity(v)
+
+    @field_validator("category", mode="before")
+    @classmethod
+    def _normalize_category(cls, v: str) -> str:
+        return _normalize_category(v, _SPECIALIST_CATEGORIES)
+
 
 class SpecialistResponse(BaseModel):
     """Response schema for individual specialist agent (parallel SDK sessions).
@@ -611,6 +416,17 @@ class ResolutionVerification(BaseModel):
     )
 
 
+_PARALLEL_FOLLOWUP_CATEGORIES = {
+    "security",
+    "quality",
+    "logic",
+    "test",
+    "docs",
+    "regression",
+    "incomplete_fix",
+}
+
+
 class ParallelFollowupFinding(BaseModel):
     """A finding from parallel follow-up review."""
 
@@ -619,18 +435,8 @@ class ParallelFollowupFinding(BaseModel):
     line: int = Field(0, description="Line number of the issue")
     title: str = Field(description="Brief issue title")
     description: str = Field(description="Detailed explanation of the issue")
-    category: Literal[
-        "security",
-        "quality",
-        "logic",
-        "test",
-        "docs",
-        "regression",
-        "incomplete_fix",
-    ] = Field(description="Issue category")
-    severity: Literal["critical", "high", "medium", "low"] = Field(
-        description="Issue severity level"
-    )
+    category: str = Field(description="Issue category")
+    severity: str = Field(description="Issue severity level")
     suggested_fix: str | None = Field(None, description="How to fix this issue")
     fixable: bool = Field(False, description="Whether this can be auto-fixed")
     is_impact_finding: bool = Field(
@@ -638,6 +444,16 @@ class ParallelFollowupFinding(BaseModel):
         description="True if this finding is about impact on OTHER files outside the PR diff",
     )
 
+    @field_validator("severity", mode="before")
+    @classmethod
+    def _normalize_severity(cls, v: str) -> str:
+        return _normalize_severity(v)
+
+    @field_validator("category", mode="before")
+    @classmethod
+    def _normalize_category(cls, v: str) -> str:
+        return _normalize_category(v, _PARALLEL_FOLLOWUP_CATEGORIES)
+
 
 class ParallelFollowupResponse(BaseModel):
     """Complete response schema for parallel follow-up PR review.

apps/backend/runners/github/services/recovery_utils.py

@@ -0,0 +1,108 @@
+"""
+Recovery Utilities for PR Review
+=================================
+
+Shared helpers for extraction recovery in followup and parallel followup reviewers.
+
+These utilities consolidate duplicated logic for:
+- Parsing "SEVERITY: description" patterns from extraction summaries
+- Generating consistent, traceable finding IDs with prefixes
+- Creating PRReviewFinding objects from extraction data
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+try:
+    from ..models import (
+        PRReviewFinding,
+        ReviewCategory,
+        ReviewSeverity,
+    )
+except (ImportError, ValueError, SystemError):
+    from models import (
+        PRReviewFinding,
+        ReviewCategory,
+        ReviewSeverity,
+    )
+
+# Severity mapping for parsing "SEVERITY: description" patterns
+_EXTRACTION_SEVERITY_MAP: list[tuple[str, ReviewSeverity]] = [
+    ("CRITICAL:", ReviewSeverity.CRITICAL),
+    ("HIGH:", ReviewSeverity.HIGH),
+    ("MEDIUM:", ReviewSeverity.MEDIUM),
+    ("LOW:", ReviewSeverity.LOW),
+]
+
+
+def parse_severity_from_summary(
+    summary: str,
+) -> tuple[ReviewSeverity, str]:
+    """Parse a "SEVERITY: description" pattern from an extraction summary.
+
+    Args:
+        summary: Raw summary string, e.g. "HIGH: Missing null check in parser.py"
+
+    Returns:
+        Tuple of (severity, cleaned_description).
+        Defaults to MEDIUM severity if no prefix is found.
+    """
+    upper_summary = summary.upper()
+    for sev_name, sev_val in _EXTRACTION_SEVERITY_MAP:
+        if upper_summary.startswith(sev_name):
+            return sev_val, summary[len(sev_name) :].strip()
+    return ReviewSeverity.MEDIUM, summary
+
+
+def generate_recovery_finding_id(
+    index: int, description: str, prefix: str = "FR"
+) -> str:
+    """Generate a consistent, traceable finding ID for recovery findings.
+
+    Args:
+        index: The index of the finding in the extraction list.
+        description: The finding description (used for hash uniqueness).
+        prefix: ID prefix for traceability. Default "FR" (Followup Recovery).
+                Use "FU" for parallel followup findings.
+
+    Returns:
+        A prefixed finding ID like "FR-A1B2C3D4" or "FU-A1B2C3D4".
+    """
+    content = f"extraction-{index}-{description}"
+    hex_hash = (
+        hashlib.md5(content.encode(), usedforsecurity=False).hexdigest()[:8].upper()
+    )
+    return f"{prefix}-{hex_hash}"
+
+
+def create_finding_from_summary(
+    summary: str,
+    index: int,
+    id_prefix: str = "FR",
+) -> PRReviewFinding:
+    """Create a PRReviewFinding from an extraction summary string.
+
+    Parses "SEVERITY: description" patterns, generates a traceable finding ID,
+    and returns a fully constructed PRReviewFinding.
+
+    Args:
+        summary: Raw summary string, e.g. "HIGH: Missing null check in parser.py"
+        index: The index of the finding in the extraction list.
+        id_prefix: ID prefix for traceability. Default "FR" (Followup Recovery).
+
+    Returns:
+        A PRReviewFinding with parsed severity, generated ID, and description.
+    """
+    severity, description = parse_severity_from_summary(summary)
+    finding_id = generate_recovery_finding_id(index, description, prefix=id_prefix)
+
+    return PRReviewFinding(
+        id=finding_id,
+        severity=severity,
+        category=ReviewCategory.QUALITY,
+        title=description[:80],
+        description=f"[Recovered via extraction] {description}",
+        file="unknown",
+        line=0,
+    )

apps/backend/services/recovery.py

@@ -14,12 +14,19 @@ Key Features:
 """
 
 import json
+import logging
 import subprocess
 from dataclasses import dataclass
-from datetime import datetime
+from datetime import datetime, timedelta, timezone
 from enum import Enum
 from pathlib import Path
 
+# Recovery manager configuration
+ATTEMPT_WINDOW_SECONDS = 7200  # Only count attempts within last 2 hours
+MAX_ATTEMPT_HISTORY_PER_SUBTASK = 50  # Cap stored attempts per subtask
+
+logger = logging.getLogger(__name__)
+
 
 class FailureType(Enum):
     """Types of failures that can occur during autonomous builds."""
@@ -82,8 +89,8 @@ class RecoveryManager:
             "subtasks": {},
             "stuck_subtasks": [],
             "metadata": {
-                "created_at": datetime.now().isoformat(),
-                "last_updated": datetime.now().isoformat(),
+                "created_at": datetime.now(timezone.utc).isoformat(),
+                "last_updated": datetime.now(timezone.utc).isoformat(),
             },
         }
         with open(self.attempt_history_file, "w", encoding="utf-8") as f:
@@ -95,8 +102,8 @@ class RecoveryManager:
             "commits": [],
             "last_good_commit": None,
             "metadata": {
-                "created_at": datetime.now().isoformat(),
-                "last_updated": datetime.now().isoformat(),
+                "created_at": datetime.now(timezone.utc).isoformat(),
+                "last_updated": datetime.now(timezone.utc).isoformat(),
             },
         }
         with open(self.build_commits_file, "w", encoding="utf-8") as f:
@@ -114,7 +121,7 @@ class RecoveryManager:
 
     def _save_attempt_history(self, data: dict) -> None:
         """Save attempt history to JSON file."""
-        data["metadata"]["last_updated"] = datetime.now().isoformat()
+        data["metadata"]["last_updated"] = datetime.now(timezone.utc).isoformat()
         with open(self.attempt_history_file, "w", encoding="utf-8") as f:
             json.dump(data, f, indent=2)
 
@@ -130,7 +137,7 @@ class RecoveryManager:
 
     def _save_build_commits(self, data: dict) -> None:
         """Save build commits to JSON file."""
-        data["metadata"]["last_updated"] = datetime.now().isoformat()
+        data["metadata"]["last_updated"] = datetime.now(timezone.utc).isoformat()
         with open(self.build_commits_file, "w", encoding="utf-8") as f:
             json.dump(data, f, indent=2)
 
@@ -185,17 +192,44 @@ class RecoveryManager:
 
     def get_attempt_count(self, subtask_id: str) -> int:
         """
-        Get how many times this subtask has been attempted.
+        Get how many times this subtask has been attempted within the time window.
+
+        Only counts attempts within ATTEMPT_WINDOW_SECONDS (default: 2 hours).
+        This prevents unbounded accumulation across crash/restart cycles.
 
         Args:
             subtask_id: ID of the subtask
 
         Returns:
-            Number of attempts
+            Number of attempts within the time window
         """
         history = self._load_attempt_history()
         subtask_data = history["subtasks"].get(subtask_id, {})
-        return len(subtask_data.get("attempts", []))
+        attempts = subtask_data.get("attempts", [])
+
+        # Calculate cutoff time for the window
+        cutoff_time = datetime.now(timezone.utc) - timedelta(
+            seconds=ATTEMPT_WINDOW_SECONDS
+        )
+        # For backward compatibility with naive timestamps, also create naive cutoff
+        cutoff_time_naive = datetime.now() - timedelta(seconds=ATTEMPT_WINDOW_SECONDS)
+
+        # Count only attempts within the time window
+        recent_count = 0
+        for attempt in attempts:
+            try:
+                attempt_time = datetime.fromisoformat(attempt["timestamp"])
+                # Use appropriate cutoff based on whether timestamp is naive or aware
+                cutoff = (
+                    cutoff_time_naive if attempt_time.tzinfo is None else cutoff_time
+                )
+                if attempt_time >= cutoff:
+                    recent_count += 1
+            except (KeyError, ValueError):
+                # If timestamp is missing or invalid, count it (backward compatibility)
+                recent_count += 1
+
+        return recent_count
 
     def record_attempt(
         self,
@@ -208,6 +242,8 @@ class RecoveryManager:
         """
         Record an attempt at a subtask.
 
+        Automatically trims old attempts if the history exceeds MAX_ATTEMPT_HISTORY_PER_SUBTASK.
+
         Args:
             subtask_id: ID of the subtask
             session: Session number
@@ -224,13 +260,24 @@ class RecoveryManager:
         # Add the attempt
         attempt = {
             "session": session,
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
             "approach": approach,
             "success": success,
             "error": error,
         }
         history["subtasks"][subtask_id]["attempts"].append(attempt)
 
+        # Hard cap: trim oldest attempts if we exceed the maximum
+        attempts = history["subtasks"][subtask_id]["attempts"]
+        if len(attempts) > MAX_ATTEMPT_HISTORY_PER_SUBTASK:
+            trimmed_count = len(attempts) - MAX_ATTEMPT_HISTORY_PER_SUBTASK
+            history["subtasks"][subtask_id]["attempts"] = attempts[
+                -MAX_ATTEMPT_HISTORY_PER_SUBTASK:
+            ]
+            logger.debug(
+                f"Trimmed {trimmed_count} old attempts for subtask {subtask_id} (cap: {MAX_ATTEMPT_HISTORY_PER_SUBTASK})"
+            )
+
         # Update status
         if success:
             history["subtasks"][subtask_id]["status"] = "completed"
@@ -405,7 +452,7 @@ class RecoveryManager:
         commit_record = {
             "hash": commit_hash,
             "subtask_id": subtask_id,
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
         }
 
         commits["commits"].append(commit_record)
@@ -450,7 +497,7 @@ class RecoveryManager:
         stuck_entry = {
             "subtask_id": subtask_id,
             "reason": reason,
-            "escalated_at": datetime.now().isoformat(),
+            "escalated_at": datetime.now(timezone.utc).isoformat(),
             "attempt_count": self.get_attempt_count(subtask_id),
         }
 

apps/frontend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-claude-ui",
-  "version": "2.7.6-beta.4",
+  "version": "2.7.6-beta.5",
   "type": "module",
   "description": "Desktop UI for Auto Claude autonomous coding framework",
   "homepage": "https://github.com/AndyMik90/Auto-Claude",

apps/frontend/src/main/__tests__/rate-limit-detector.test.ts

@@ -1012,3 +1012,115 @@ Please add credits to continue.`;
     });
   });
 });
+
+describe('ensureCleanProfileEnv', () => {
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('with CLAUDE_CONFIG_DIR set', () => {
+    it('should preserve CLAUDE_CONFIG_DIR while clearing CLAUDE_CODE_OAUTH_TOKEN', async () => {
+      const { ensureCleanProfileEnv } = await import('../rate-limit-detector');
+
+      const env = {
+        CLAUDE_CONFIG_DIR: '/tmp/profile-1',
+        CLAUDE_CODE_OAUTH_TOKEN: 'oauth-token-123',
+        ANTHROPIC_API_KEY: 'sk-ant-key-456'
+      };
+      const result = ensureCleanProfileEnv(env);
+
+      expect(result.CLAUDE_CONFIG_DIR).toBe('/tmp/profile-1');
+      expect(result.CLAUDE_CODE_OAUTH_TOKEN).toBe('');
+      expect(result.ANTHROPIC_API_KEY).toBe('');
+    });
+
+    it('should preserve other environment variables', async () => {
+      const { ensureCleanProfileEnv } = await import('../rate-limit-detector');
+
+      const env = {
+        CLAUDE_CONFIG_DIR: '/tmp/profile-1',
+        CLAUDE_CODE_OAUTH_TOKEN: 'token',
+        ANTHROPIC_API_KEY: 'key',
+        SOME_OTHER_VAR: 'value'
+      };
+      const result = ensureCleanProfileEnv(env);
+
+      expect(result.CLAUDE_CONFIG_DIR).toBe('/tmp/profile-1');
+      expect(result.SOME_OTHER_VAR).toBe('value');
+      expect(result.CLAUDE_CODE_OAUTH_TOKEN).toBe('');
+      expect(result.ANTHROPIC_API_KEY).toBe('');
+    });
+
+    it('should clear tokens even if they are not present in input', async () => {
+      const { ensureCleanProfileEnv } = await import('../rate-limit-detector');
+
+      const env = {
+        CLAUDE_CONFIG_DIR: '/tmp/profile-1'
+      };
+      const result = ensureCleanProfileEnv(env);
+
+      expect(result.CLAUDE_CONFIG_DIR).toBe('/tmp/profile-1');
+      expect(result.CLAUDE_CODE_OAUTH_TOKEN).toBe('');
+      expect(result.ANTHROPIC_API_KEY).toBe('');
+    });
+  });
+
+  describe('without CLAUDE_CONFIG_DIR', () => {
+    it('should return env unchanged when CLAUDE_CONFIG_DIR is not set', async () => {
+      const { ensureCleanProfileEnv } = await import('../rate-limit-detector');
+
+      const env = {
+        CLAUDE_CODE_OAUTH_TOKEN: 'oauth-token-123',
+        ANTHROPIC_API_KEY: 'sk-ant-key-456'
+      };
+      const result = ensureCleanProfileEnv(env);
+
+      expect(result).toEqual(env);
+      expect(result.CLAUDE_CODE_OAUTH_TOKEN).toBe('oauth-token-123');
+      expect(result.ANTHROPIC_API_KEY).toBe('sk-ant-key-456');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty profile env', async () => {
+      const { ensureCleanProfileEnv } = await import('../rate-limit-detector');
+
+      const result = ensureCleanProfileEnv({});
+
+      // Empty env has no CLAUDE_CONFIG_DIR, so should return as-is
+      expect(result).toEqual({});
+    });
+
+    it('should handle env with empty string CLAUDE_CONFIG_DIR', async () => {
+      const { ensureCleanProfileEnv } = await import('../rate-limit-detector');
+
+      const env = {
+        CLAUDE_CONFIG_DIR: '',
+        CLAUDE_CODE_OAUTH_TOKEN: 'token'
+      };
+      const result = ensureCleanProfileEnv(env);
+
+      // Empty string is falsy, so should not trigger clearing
+      expect(result.CLAUDE_CODE_OAUTH_TOKEN).toBe('token');
+    });
+
+    it('should return a new object when clearing (not mutate input)', async () => {
+      const { ensureCleanProfileEnv } = await import('../rate-limit-detector');
+
+      const env = {
+        CLAUDE_CONFIG_DIR: '/tmp/profile-1',
+        CLAUDE_CODE_OAUTH_TOKEN: 'token'
+      };
+      const result = ensureCleanProfileEnv(env);
+
+      // Original should not be mutated
+      expect(env.CLAUDE_CODE_OAUTH_TOKEN).toBe('token');
+      expect(result.CLAUDE_CODE_OAUTH_TOKEN).toBe('');
+      expect(result).not.toBe(env);
+    });
+  });
+});

apps/frontend/src/main/agent/agent-process.test.ts

@@ -799,4 +799,127 @@ describe('AgentProcessManager - API Profile Env Injection (Story 2.3)', () => {
       expect(envArg.GITHUB_CLI_PATH).toBe('/opt/homebrew/bin/gh');
     });
   });
+
+  describe('CLAUDE_CONFIG_DIR Propagation', () => {
+    let originalEnv: NodeJS.ProcessEnv;
+
+    beforeEach(() => {
+      originalEnv = { ...process.env };
+      delete process.env.CLAUDE_CONFIG_DIR;
+    });
+
+    afterEach(() => {
+      process.env = originalEnv;
+    });
+
+    it('should propagate CLAUDE_CONFIG_DIR from profile env in OAuth mode', async () => {
+      // OAuth mode - no active API profile
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValue({});
+
+      // Profile provides CLAUDE_CONFIG_DIR (OAuth subscription profile)
+      vi.mocked(rateLimitDetector.getBestAvailableProfileEnv).mockReturnValue({
+        env: {
+          CLAUDE_CONFIG_DIR: '/home/user/.config/claude-profile-1',
+          CLAUDE_CODE_OAUTH_TOKEN: 'oauth-token-abc'
+        },
+        profileId: 'profile-1',
+        profileName: 'Profile 1',
+        wasSwapped: false
+      });
+
+      await processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], {}, 'task-execution');
+
+      expect(spawnCalls).toHaveLength(1);
+      const envArg = spawnCalls[0].options.env as Record<string, unknown>;
+
+      // CLAUDE_CONFIG_DIR should be present in spawn env
+      expect(envArg.CLAUDE_CONFIG_DIR).toBe('/home/user/.config/claude-profile-1');
+    });
+
+    it('should clear ANTHROPIC_API_KEY in OAuth mode with CLAUDE_CONFIG_DIR', async () => {
+      // Simulate stale ANTHROPIC_API_KEY in process.env
+      process.env.ANTHROPIC_API_KEY = 'sk-stale-key';
+
+      // OAuth mode - no active API profile
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValue({});
+
+      // Profile provides CLAUDE_CONFIG_DIR
+      vi.mocked(rateLimitDetector.getBestAvailableProfileEnv).mockReturnValue({
+        env: {
+          CLAUDE_CONFIG_DIR: '/home/user/.config/claude-profile-2',
+          CLAUDE_CODE_OAUTH_TOKEN: 'oauth-token-def'
+        },
+        profileId: 'profile-2',
+        profileName: 'Profile 2',
+        wasSwapped: false
+      });
+
+      await processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], {}, 'task-execution');
+
+      expect(spawnCalls).toHaveLength(1);
+      const envArg = spawnCalls[0].options.env as Record<string, unknown>;
+
+      // ANTHROPIC_API_KEY should be cleared (empty string) in OAuth mode
+      expect(envArg.ANTHROPIC_API_KEY).toBe('');
+      // CLAUDE_CONFIG_DIR should still be set
+      expect(envArg.CLAUDE_CONFIG_DIR).toBe('/home/user/.config/claude-profile-2');
+    });
+
+    it('should pass ANTHROPIC_* vars without CLAUDE_CONFIG_DIR interference in API profile mode', async () => {
+      // API Profile mode - active profile with custom endpoint
+      const mockApiProfileEnv = {
+        ANTHROPIC_AUTH_TOKEN: 'sk-api-profile-key',
+        ANTHROPIC_BASE_URL: 'https://custom-api.example.com',
+        ANTHROPIC_MODEL: 'claude-sonnet-4-5-20250929'
+      };
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValue(mockApiProfileEnv);
+
+      // Profile env without CLAUDE_CONFIG_DIR (API profile mode)
+      vi.mocked(rateLimitDetector.getBestAvailableProfileEnv).mockReturnValue({
+        env: {},
+        profileId: 'api-profile-1',
+        profileName: 'Custom API',
+        wasSwapped: false
+      });
+
+      await processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], {}, 'task-execution');
+
+      expect(spawnCalls).toHaveLength(1);
+      const envArg = spawnCalls[0].options.env as Record<string, unknown>;
+
+      // ANTHROPIC_* vars from API profile should be passed through
+      expect(envArg.ANTHROPIC_AUTH_TOKEN).toBe('sk-api-profile-key');
+      expect(envArg.ANTHROPIC_BASE_URL).toBe('https://custom-api.example.com');
+      expect(envArg.ANTHROPIC_MODEL).toBe('claude-sonnet-4-5-20250929');
+
+      // CLAUDE_CONFIG_DIR should NOT be present since profile didn't provide it
+      expect(envArg.CLAUDE_CONFIG_DIR).toBeUndefined();
+    });
+
+    it('should clear CLAUDE_CODE_OAUTH_TOKEN when CLAUDE_CONFIG_DIR is provided by profile', async () => {
+      // OAuth mode
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValue({});
+
+      // Profile provides CLAUDE_CONFIG_DIR - agent should use config dir for auth
+      vi.mocked(rateLimitDetector.getBestAvailableProfileEnv).mockReturnValue({
+        env: {
+          CLAUDE_CONFIG_DIR: '/home/user/.config/claude-profile-3',
+          CLAUDE_CODE_OAUTH_TOKEN: 'oauth-token-ghi'
+        },
+        profileId: 'profile-3',
+        profileName: 'Profile 3',
+        wasSwapped: false
+      });
+
+      await processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], {}, 'task-execution');
+
+      expect(spawnCalls).toHaveLength(1);
+      const envArg = spawnCalls[0].options.env as Record<string, unknown>;
+
+      // When CLAUDE_CONFIG_DIR is present, CLAUDE_CODE_OAUTH_TOKEN should be cleared
+      // because Claude Code resolves auth from the config dir instead
+      expect(envArg.CLAUDE_CONFIG_DIR).toBe('/home/user/.config/claude-profile-3');
+      expect(envArg.CLAUDE_CODE_OAUTH_TOKEN).toBeFalsy();
+    });
+  });
 });

apps/frontend/src/main/agent/agent-process.ts

@@ -26,6 +26,7 @@ import { getOAuthModeClearVars } from './env-utils';
 import { getAugmentedEnv } from '../env-utils';
 import { getToolInfo, getClaudeCliPathForSdk } from '../cli-tool-manager';
 import { killProcessGracefully, isWindows } from '../platform';
+import { debugLog } from '../../shared/utils/debug-logger';
 
 /**
  * Type for supported CLI tools
@@ -178,6 +179,29 @@ export class AgentProcessManager {
     // Get best available Claude profile environment (automatically handles rate limits)
     const profileResult = getBestAvailableProfileEnv();
     const profileEnv = profileResult.env;
+
+    debugLog('[AgentProcess:setupEnv] Profile result:', {
+      profileId: profileResult.profileId,
+      hasOAuthToken: !!profileEnv.CLAUDE_CODE_OAUTH_TOKEN,
+      hasApiKey: !!profileEnv.ANTHROPIC_API_KEY,
+      hasConfigDir: !!profileEnv.CLAUDE_CONFIG_DIR,
+      configDir: profileEnv.CLAUDE_CONFIG_DIR || '(not set)',
+      oauthTokenPrefix: profileEnv.CLAUDE_CODE_OAUTH_TOKEN?.substring(0, 8) || '(not set)',
+      apiKeyPrefix: profileEnv.ANTHROPIC_API_KEY?.substring(0, 8) || '(not set)',
+    });
+
+    // Warn if profile lacks CLAUDE_CONFIG_DIR - this means the profile has no configDir
+    // and subscription metadata may not propagate correctly to the agent subprocess
+    if (!profileEnv.CLAUDE_CONFIG_DIR) {
+      console.warn('[AgentProcess:setupEnv] WARNING: Profile env lacks CLAUDE_CONFIG_DIR - profile may not have a configDir set. Subscription metadata may not reach agent subprocess.');
+    }
+
+    debugLog('[AgentProcess:setupEnv] extraEnv auth keys:', {
+      hasOAuthToken: !!extraEnv.CLAUDE_CODE_OAUTH_TOKEN,
+      hasApiKey: !!extraEnv.ANTHROPIC_API_KEY,
+      hasConfigDir: !!extraEnv.CLAUDE_CONFIG_DIR,
+    });
+
     // Use getAugmentedEnv() to ensure common tool paths (dotnet, homebrew, etc.)
     // are available even when app is launched from Finder/Dock
     const augmentedEnv = getAugmentedEnv();
@@ -205,7 +229,9 @@ export class AgentProcessManager {
     const ghCliEnv = this.detectAndSetCliPath('gh');
     const glabCliEnv = this.detectAndSetCliPath('glab');
 
-    return {
+    // Profile env is spread last to ensure CLAUDE_CONFIG_DIR and auth vars
+    // from the active profile always win over extraEnv or augmentedEnv.
+    const mergedEnv = {
       ...augmentedEnv,
       ...gitBashEnv,
       ...claudeCliEnv,
@@ -217,6 +243,29 @@ export class AgentProcessManager {
       PYTHONIOENCODING: 'utf-8',
       PYTHONUTF8: '1'
     } as NodeJS.ProcessEnv;
+
+    // When the active profile provides CLAUDE_CONFIG_DIR, clear CLAUDE_CODE_OAUTH_TOKEN
+    // from the spawn environment. CLAUDE_CONFIG_DIR lets Claude Code resolve its own
+    // OAuth tokens from the config directory, making an explicit token unnecessary.
+    // This matches the terminal pattern in claude-integration-handler.ts where
+    // configDir is preferred over direct token injection.
+    // We check profileEnv specifically (not mergedEnv) to avoid clearing the token
+    // when CLAUDE_CONFIG_DIR comes from the shell environment rather than the profile.
+    if (profileEnv.CLAUDE_CONFIG_DIR) {
+      mergedEnv.CLAUDE_CODE_OAUTH_TOKEN = '';
+      debugLog('[AgentProcess:setupEnv] Profile provides CLAUDE_CONFIG_DIR, cleared CLAUDE_CODE_OAUTH_TOKEN from spawn env');
+    }
+
+    debugLog('[AgentProcess:setupEnv] Final merged env auth state:', {
+      hasOAuthToken: !!mergedEnv.CLAUDE_CODE_OAUTH_TOKEN,
+      hasApiKey: !!mergedEnv.ANTHROPIC_API_KEY,
+      hasConfigDir: !!mergedEnv.CLAUDE_CONFIG_DIR,
+      configDir: mergedEnv.CLAUDE_CONFIG_DIR || '(not set)',
+      oauthTokenPrefix: mergedEnv.CLAUDE_CODE_OAUTH_TOKEN?.substring(0, 8) || '(not set)',
+      apiKeyPrefix: mergedEnv.ANTHROPIC_API_KEY?.substring(0, 8) || '(not set)',
+    });
+
+    return mergedEnv;
   }
 
   private handleProcessFailure(
@@ -615,6 +664,21 @@ export class AgentProcessManager {
     // Get OAuth mode clearing vars (clears stale ANTHROPIC_* vars when in OAuth mode)
     const oauthModeClearVars = getOAuthModeClearVars(apiProfileEnv);
 
+    debugLog('[AgentProcess:spawnProcess] Environment merge chain for task:', taskId, {
+      baseEnv: {
+        hasOAuthToken: !!env.CLAUDE_CODE_OAUTH_TOKEN,
+        hasApiKey: !!env.ANTHROPIC_API_KEY,
+        hasConfigDir: !!env.CLAUDE_CONFIG_DIR,
+        configDir: env.CLAUDE_CONFIG_DIR || '(not set)',
+      },
+      oauthModeClearVars: Object.keys(oauthModeClearVars),
+      apiProfileEnv: {
+        hasApiKey: !!apiProfileEnv.ANTHROPIC_API_KEY,
+        hasBaseUrl: !!apiProfileEnv.ANTHROPIC_BASE_URL,
+        apiKeyPrefix: apiProfileEnv.ANTHROPIC_API_KEY?.substring(0, 8) || '(not set)',
+      },
+    });
+
     // Parse Python commandto handle space-separated commands like "py -3"
     const [pythonCommand, pythonBaseArgs] = parsePythonCommand(this.getPythonPath());
     let childProcess;

apps/frontend/src/main/claude-profile-manager.ts

@@ -56,6 +56,7 @@ import {
   expandHomePath,
   getEmailFromConfigDir
 } from './claude-profile/profile-utils';
+import { debugLog } from '../shared/utils/debug-logger';
 
 /**
  * Manages Claude Code profiles for multi-account support.
@@ -86,6 +87,8 @@ export class ClaudeProfileManager {
       return;
     }
 
+    console.log('[ClaudeProfileManager] Starting initialization...');
+
     // Ensure directory exists (async) - mkdir with recursive:true is idempotent
     await mkdir(this.configDir, { recursive: true });
 
@@ -93,6 +96,9 @@ export class ClaudeProfileManager {
     const loadedData = await loadProfileStoreAsync(this.storePath);
     if (loadedData) {
       this.data = loadedData;
+      debugLog('[ClaudeProfileManager] Loaded profile store with', this.data.profiles.length, 'profiles');
+    } else {
+      debugLog('[ClaudeProfileManager] No existing profile store found, using defaults');
     }
 
     // Run one-time migration to fix corrupted emails
@@ -104,6 +110,7 @@ export class ClaudeProfileManager {
     this.populateSubscriptionMetadata();
 
     this.initialized = true;
+    console.log('[ClaudeProfileManager] Initialization complete');
   }
 
   /**
@@ -149,13 +156,20 @@ export class ClaudeProfileManager {
   private populateSubscriptionMetadata(): void {
     let needsSave = false;
 
+    debugLog('[ClaudeProfileManager] populateSubscriptionMetadata: checking', this.data.profiles.length, 'profiles');
+
     for (const profile of this.data.profiles) {
       if (!profile.configDir) {
+        debugLog('[ClaudeProfileManager] populateSubscriptionMetadata: skipping profile', profile.id, '(no configDir)');
         continue;
       }
 
       // Skip if profile already has subscription metadata
       if (profile.subscriptionType && profile.rateLimitTier) {
+        debugLog('[ClaudeProfileManager] populateSubscriptionMetadata: profile', profile.id, 'already has metadata:', {
+          subscriptionType: profile.subscriptionType,
+          rateLimitTier: profile.rateLimitTier
+        });
         continue;
       }
 
@@ -542,8 +556,27 @@ export class ClaudeProfileManager {
       if (process.env.DEBUG === 'true') {
         console.warn('[ClaudeProfileManager] Using CLAUDE_CONFIG_DIR for profile:', profile.name, expandedConfigDir);
       }
-    } else {
-      console.warn('[ClaudeProfileManager] Profile has no configDir configured:', profile?.name);
+    } else if (profile) {
+      // Fallback: retrieve OAuth token directly from Keychain when configDir is missing.
+      // Without configDir, Claude CLI cannot resolve credentials automatically,
+      // so we inject CLAUDE_CODE_OAUTH_TOKEN as a direct override.
+      debugLog(
+        '[ClaudeProfileManager] Profile has no configDir configured:',
+        profile.name,
+        '- falling back to Keychain token lookup. Subscription display may be degraded.'
+      );
+
+      const credentials = getCredentialsFromKeychain(undefined, true);
+      if (credentials.token) {
+        env.CLAUDE_CODE_OAUTH_TOKEN = credentials.token;
+        debugLog('[ClaudeProfileManager] Injected CLAUDE_CODE_OAUTH_TOKEN from Keychain for profile:', profile.name);
+      } else {
+        debugLog(
+          '[ClaudeProfileManager] No token found in Keychain for profile without configDir:',
+          profile.name,
+          credentials.error ? `(error: ${credentials.error})` : ''
+        );
+      }
     }
 
     return env;
@@ -801,8 +834,26 @@ export class ClaudeProfileManager {
       return {};
     }
 
-    // If no configDir is defined, fall back to default
     if (!profile.configDir) {
+      // Fallback: retrieve OAuth token directly from Keychain when configDir is missing.
+      // Without configDir, Claude CLI cannot resolve credentials automatically,
+      // so we inject CLAUDE_CODE_OAUTH_TOKEN as a direct override.
+      // This mirrors the fallback in getActiveProfileEnv().
+      debugLog(
+        '[ClaudeProfileManager] getProfileEnv: profile has no configDir:',
+        profile.name,
+        '- falling back to Keychain token lookup.'
+      );
+
+      const credentials = getCredentialsFromKeychain(undefined, true);
+      if (credentials.token) {
+        debugLog('[ClaudeProfileManager] getProfileEnv: injected CLAUDE_CODE_OAUTH_TOKEN from Keychain for profile:', profile.name);
+        return { CLAUDE_CODE_OAUTH_TOKEN: credentials.token };
+      }
+      debugLog(
+        '[ClaudeProfileManager] getProfileEnv: no token found in Keychain for profile without configDir:',
+        profile.name
+      );
       return {};
     }
 

apps/frontend/src/main/claude-profile/credential-utils.ts

@@ -1825,6 +1825,7 @@ function updateLinuxFileCredentials(
     }
 
     // Write to file with secure permissions (0600)
+    // lgtm[js/http-to-file-access] - credentialsPath is from controlled configDir
     writeFileSync(credentialsPath, credentialsJson, { mode: 0o600, encoding: 'utf-8' });
 
     if (isDebug) {
@@ -2086,6 +2087,7 @@ function updateWindowsFileCredentials(
     const tempPath = `${credentialsPath}.${Date.now()}.tmp`;
     try {
       // Write to temp file
+      // lgtm[js/http-to-file-access] - credentialsPath is from controlled configDir
       writeFileSync(tempPath, credentialsJson, { encoding: 'utf-8' });
 
       // Restrict temp file permissions to current user only (mimics Unix 0600)

apps/frontend/src/main/index.ts

@@ -330,6 +330,10 @@ function createWindow(): void {
 
   // Clean up on close
   mainWindow.on('closed', () => {
+    // Kill all agents when window closes (prevents orphaned processes)
+    agentManager?.killAll?.()?.catch((err: unknown) => {
+      console.warn('[main] Error killing agents on window close:', err);
+    });
     mainWindow = null;
   });
 }

apps/frontend/src/main/ipc-handlers/github/pr-handlers.ts

@@ -112,6 +112,7 @@ async function githubGraphQL<T>(
   query: string,
   variables: Record<string, unknown> = {}
 ): Promise<T> {
+  // lgtm[js/file-access-to-http] - Official GitHub GraphQL API endpoint
   const response = await fetch("https://api.github.com/graphql", {
     method: "POST",
     headers: {
@@ -278,7 +279,7 @@ export interface PRReviewResult {
   success: boolean;
   findings: PRReviewFinding[];
   summary: string;
-  overallStatus: "approve" | "request_changes" | "comment";
+  overallStatus: "approve" | "request_changes" | "comment" | "in_progress";
   reviewId?: number;
   reviewedAt: string;
   error?: string;
@@ -294,6 +295,8 @@ export interface PRReviewResult {
   hasPostedFindings?: boolean;
   postedFindingIds?: string[];
   postedAt?: string;
+  // In-progress review tracking
+  inProgressSince?: string;
 }
 
 /**
@@ -1356,6 +1359,8 @@ function getReviewResult(project: Project, prNumber: number): PRReviewResult | n
       hasPostedFindings: data.has_posted_findings ?? false,
       postedFindingIds: data.posted_finding_ids ?? [],
       postedAt: data.posted_at,
+      // In-progress review tracking
+      inProgressSince: data.in_progress_since,
     };
   } catch {
     // File doesn't exist or couldn't be read
@@ -1514,7 +1519,32 @@ async function runPRReview(
       debugLog("Auth failure detected in PR review", authFailureInfo);
       mainWindow.webContents.send(IPC_CHANNELS.CLAUDE_AUTH_FAILURE, authFailureInfo);
     },
-    onComplete: () => {
+    onComplete: (stdout: string) => {
+      // Check stdout for in_progress JSON marker (not saved to disk by backend)
+      const inProgressMarker = "__RESULT_JSON__:";
+      for (const line of stdout.split("\n")) {
+        if (line.startsWith(inProgressMarker)) {
+          try {
+            const data = JSON.parse(line.slice(inProgressMarker.length));
+            if (data.overall_status === "in_progress") {
+              debugLog("In-progress result parsed from stdout", { prNumber });
+              return {
+                prNumber: data.pr_number,
+                repo: data.repo,
+                success: data.success,
+                findings: [],
+                summary: data.summary ?? "",
+                overallStatus: "in_progress" as const,
+                reviewedAt: data.reviewed_at ?? new Date().toISOString(),
+                inProgressSince: data.in_progress_since,
+              };
+            }
+          } catch {
+            debugLog("Failed to parse __RESULT_JSON__ line", { line });
+          }
+        }
+      }
+
       // Load the result from disk
       const reviewResult = getReviewResult(project, prNumber);
       if (!reviewResult) {
@@ -1864,9 +1894,15 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v
           projectId
         );
 
-        // Check if already running
+        // Check if already running — notify renderer so it can display ongoing logs
         if (runningReviews.has(reviewKey)) {
-          debugLog("Review already running", { reviewKey });
+          debugLog("Review already running, notifying renderer", { reviewKey });
+          sendProgress({
+            phase: "analyzing",
+            prNumber,
+            progress: 50,
+            message: "Review is already in progress. Reconnecting to ongoing review...",
+          });
           return;
         }
 
@@ -1936,6 +1972,20 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v
 
           const result = await runPRReview(project, prNumber, mainWindow);
 
+          if (result.overallStatus === "in_progress") {
+            // Review is already running externally (detected by BotDetector).
+            // Send the result as-is so the renderer can activate external review polling.
+            debugLog("PR review already in progress externally", { prNumber });
+            sendProgress({
+              phase: "complete",
+              prNumber,
+              progress: 100,
+              message: "Review already in progress",
+            });
+            sendComplete(result);
+            return;
+          }
+
           debugLog("PR review completed", { prNumber, findingsCount: result.findings.length });
           sendProgress({
             phase: "complete",

apps/frontend/src/main/ipc-handlers/github/spec-utils.ts

@@ -137,6 +137,7 @@ export async function createSpecForIssue(
       status: 'pending',
       phases: []
     };
+    // lgtm[js/http-to-file-access] - specDir is controlled, slugifiedTitle sanitizes input
     writeFileSync(
       path.join(specDir, AUTO_BUILD_PATHS.IMPLEMENTATION_PLAN),
       JSON.stringify(implementationPlan, null, 2),
@@ -148,6 +149,7 @@ export async function createSpecForIssue(
       task_description: safeDescription,
       workflow_type: 'feature'
     };
+    // lgtm[js/http-to-file-access] - specDir is controlled, slugifiedTitle sanitizes input
     writeFileSync(
       path.join(specDir, AUTO_BUILD_PATHS.REQUIREMENTS),
       JSON.stringify(requirements, null, 2),
@@ -167,6 +169,7 @@ export async function createSpecForIssue(
       // This comes from project.settings.mainBranch or task-level override
       ...(baseBranch && { baseBranch })
     };
+    // lgtm[js/http-to-file-access] - specDir is controlled, slugifiedTitle sanitizes input
     writeFileSync(
       path.join(specDir, 'task_metadata.json'),
       JSON.stringify(metadata, null, 2),

apps/frontend/src/main/ipc-handlers/gitlab/investigation-handlers.ts

@@ -8,8 +8,8 @@ import { IPC_CHANNELS } from '../../../shared/constants';
 import type { GitLabInvestigationStatus, GitLabInvestigationResult } from '../../../shared/types';
 import { projectStore } from '../../project-store';
 import { getGitLabConfig, gitlabFetch, encodeProjectPath } from './utils';
-import type { GitLabAPIIssue, GitLabAPINote } from './types';
-import { buildIssueContext, createSpecForIssue } from './spec-utils';
+import type { GitLabAPIIssue, GitLabAPINoteBasic } from './types';
+import { createSpecForIssue, fetchAllIssueNotes } from './spec-utils';
 import type { AgentManager } from '../../agent';
 
 // Debug logging helper
@@ -109,51 +109,31 @@ export function registerInvestigateIssue(
           `/projects/${encodedProject}/issues/${issueIid}`
         ) as GitLabAPIIssue;
 
-        // Fetch notes if any selected
-        let selectedNotes: GitLabAPINote[] = [];
+        // Fetch notes if any selected (with pagination to get all notes)
+        let filteredNotes: GitLabAPINoteBasic[] = [];
         if (selectedNoteIds && selectedNoteIds.length > 0) {
-          const allNotes = await gitlabFetch(
-            config.token,
-            config.instanceUrl,
-            `/projects/${encodedProject}/issues/${issueIid}/notes`
-          ) as GitLabAPINote[];
-
-          selectedNotes = allNotes.filter(note => selectedNoteIds.includes(note.id));
+          // Fetch all notes using the paginated utility function
+          const allNotes = await fetchAllIssueNotes(config, encodedProject, issueIid);
+          // Filter notes based on selection
+          filteredNotes = allNotes.filter(note => selectedNoteIds.includes(note.id));
         }
 
-        // Phase 2: Analyzing
-        sendProgress(getMainWindow, project.id, {
-          phase: 'analyzing',
-          issueIid,
-          progress: 30,
-          message: 'Analyzing issue with AI...'
-        });
-
-        // Note: Context building previously done here has been moved to createSpecForIssue utility.
-        // The buildIssueContext() function and selectedNotes processing are now handled internally
-        // by the spec creation pipeline. This avoids duplicate context generation.
-        // TODO: If advanced context customization is needed in the future, consider extracting
-        // context building into a reusable utility function.
-
-        // Use agent manager to investigate
-        // Note: This is a simplified version - full implementation would use Claude SDK
-        sendProgress(getMainWindow, project.id, {
-          phase: 'analyzing',
-          issueIid,
-          progress: 50,
-          message: 'AI analyzing the issue...'
-        });
-
-        // Phase 3: Creating task
+        // Phase 2: Creating task
         sendProgress(getMainWindow, project.id, {
           phase: 'creating_task',
           issueIid,
-          progress: 80,
-          message: 'Creating task from analysis...'
+          progress: 50,
+          message: 'Creating task from issue...'
         });
 
-        // Create spec for the issue
-        const task = await createSpecForIssue(project, issue, config, project.settings?.mainBranch);
+        // Create spec for the issue with notes
+        const task = await createSpecForIssue(
+          project,
+          issue,
+          config,
+          project.settings?.mainBranch,
+          filteredNotes
+        );
 
         if (!task) {
           sendError(getMainWindow, project.id, 'Failed to create task from issue');

apps/frontend/src/main/ipc-handlers/gitlab/spec-utils.ts

@@ -6,7 +6,7 @@
 import { mkdir, writeFile, readFile, stat } from 'fs/promises';
 import path from 'path';
 import type { Project } from '../../../shared/types';
-import type { GitLabAPIIssue, GitLabConfig } from './types';
+import type { GitLabAPIIssue, GitLabAPINoteBasic, GitLabConfig } from './types';
 import { labelMatchesWholeWord } from '../shared/label-utils';
 import { sanitizeText, sanitizeStringArray } from '../shared/sanitize';
 
@@ -208,7 +208,12 @@ function generateSpecDirName(issueIid: number, title: string): string {
 /**
  * Build issue context for spec creation
  */
-export function buildIssueContext(issue: IssueLike, projectPath: string, instanceUrl: string): string {
+export function buildIssueContext(
+  issue: IssueLike,
+  projectPath: string,
+  instanceUrl: string,
+  notes?: GitLabAPINoteBasic[]
+): string {
   const lines: string[] = [];
   const safeProjectPath = sanitizeText(projectPath, 200);
   const safeIssue = sanitizeIssueForSpec(issue, instanceUrl);
@@ -238,6 +243,19 @@ export function buildIssueContext(issue: IssueLike, projectPath: string, instanc
   lines.push('');
   lines.push(`**Web URL:** ${safeIssue.web_url}`);
 
+  // Add notes section if notes are provided
+  if (notes && notes.length > 0) {
+    lines.push('');
+    lines.push(`## Notes (${notes.length})`);
+    lines.push('');
+    for (const note of notes) {
+      const safeAuthor = sanitizeText(note.author?.username || 'unknown', 100);
+      const safeBody = sanitizeText(note.body, 20000, true);
+      lines.push(`**${safeAuthor}:** ${safeBody}`);
+      lines.push('');
+    }
+  }
+
   return lines.join('\n');
 }
 
@@ -253,6 +271,103 @@ async function pathExists(filePath: string): Promise<boolean> {
   }
 }
 
+/**
+ * Fetches all notes for a GitLab issue with pagination.
+ * Handles rate limiting and authentication errors gracefully.
+ *
+ * @param config GitLab configuration with token and instance URL
+ * @param encodedProject URL-encoded project path
+ * @param issueIid Issue IID to fetch notes for
+ * @returns Array of basic note objects with id, body, and author
+ */
+export async function fetchAllIssueNotes(
+  config: { token: string; instanceUrl: string },
+  encodedProject: string,
+  issueIid: number
+): Promise<GitLabAPINoteBasic[]> {
+  const { gitlabFetch } = await import('./utils');
+  const { GitLabAPIError } = await import('./utils');
+
+  const allNotes: GitLabAPINoteBasic[] = [];
+  let page = 1;
+  const perPage = 100;
+  const MAX_PAGES = 50; // Safety limit: max 5000 notes
+  let hasMore = true;
+
+  while (hasMore && page <= MAX_PAGES) {
+    try {
+      const notesPage = await gitlabFetch(
+        config.token,
+        config.instanceUrl,
+        `/projects/${encodedProject}/issues/${issueIid}/notes?page=${page}&per_page=${perPage}`
+      ) as unknown[];
+
+      // Runtime validation: ensure we got an array
+      if (!Array.isArray(notesPage)) {
+        debugLog('GitLab notes API returned non-array, stopping pagination');
+        break;
+      }
+
+      if (notesPage.length === 0) {
+        hasMore = false;
+      } else {
+        // Extract only needed fields with null-safe defaults
+        const noteSummaries: GitLabAPINoteBasic[] = notesPage
+          .filter((note: unknown): note is Record<string, unknown> =>
+            note !== null && typeof note === 'object' && typeof (note as Record<string, unknown>).id === 'number'
+          )
+          .map((note) => {
+            // Validate author structure defensively
+            const author = note.author;
+            const username = (author !== null && typeof author === 'object' && typeof (author as Record<string, unknown>).username === 'string')
+              ? (author as Record<string, unknown>).username as string
+              : 'unknown';
+            return {
+              id: note.id as number,
+              body: (note.body as string | undefined) || '',
+              author: { username },
+            };
+          });
+        allNotes.push(...noteSummaries);
+        if (notesPage.length < perPage) {
+          hasMore = false;
+        } else {
+          page++;
+        }
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+
+      // Check for authentication/rate-limit errors using structured status codes
+      const isAuthError = error instanceof GitLabAPIError && (error.statusCode === 401 || error.statusCode === 403);
+      const isRateLimited = error instanceof GitLabAPIError && error.statusCode === 429;
+
+      if (isAuthError || isRateLimited) {
+        // Re-throw critical errors to let the caller surface them to the user
+        const statusCode = error instanceof GitLabAPIError ? error.statusCode : undefined;
+        console.warn(`[GitLab Notes] ${isAuthError ? 'Authentication' : 'Rate limit'} error during notes fetch`, { page, error: errorMessage, statusCode });
+        throw error;
+      }
+
+      // For transient errors on page 1, warn the user but continue
+      if (page === 1 && allNotes.length === 0) {
+        console.warn('[GitLab Notes] Failed to fetch any notes, proceeding without notes context', { error: errorMessage });
+      } else {
+        // Log pagination failure for subsequent pages
+        debugLog('Failed to fetch notes page, using partial notes', { page, error: errorMessage, notesRetrieved: allNotes.length });
+      }
+      hasMore = false;
+    }
+  }
+
+  // Warn if we hit the pagination limit
+  if (page > MAX_PAGES && hasMore) {
+    debugLog('Pagination limit reached, some notes may be missing', { maxPages: MAX_PAGES, notesRetrieved: allNotes.length });
+  }
+
+  return allNotes;
+}
+
 /**
  * Create a task spec from a GitLab issue
  */
@@ -260,7 +375,8 @@ export async function createSpecForIssue(
   project: Project,
   issue: GitLabAPIIssue,
   config: GitLabConfig,
-  baseBranch?: string
+  baseBranch?: string,
+  notes?: GitLabAPINoteBasic[]
 ): Promise<GitLabTaskInfo | null> {
   try {
     // Validate and sanitize network data before writing to disk
@@ -319,8 +435,8 @@ export async function createSpecForIssue(
     // Create spec directory
     await mkdir(specDir, { recursive: true });
 
-    // Create TASK.md with issue context
-    const taskContent = buildIssueContext(safeIssue, safeProject, config.instanceUrl);
+    // Create TASK.md with issue context (including selected notes)
+    const taskContent = buildIssueContext(safeIssue, safeProject, safeInstanceUrl, notes);
     await writeFile(path.join(specDir, 'TASK.md'), taskContent, 'utf-8');
 
     // Create metadata.json (legacy format for GitLab-specific data)

apps/frontend/src/main/ipc-handlers/gitlab/triage-handlers.ts

@@ -420,6 +420,7 @@ export function registerTriageHandlers(
             }
 
             // Save result
+            // lgtm[js/http-to-file-access] - triageDir from controlled project path, issue_iid is numeric
             fs.writeFileSync(
               path.join(triageDir, `triage_${sanitizedResult.issue_iid}.json`),
               JSON.stringify(sanitizedResult, null, 2),

apps/frontend/src/main/ipc-handlers/gitlab/types.ts

@@ -51,6 +51,13 @@ export interface GitLabAPINote {
   system: boolean;
 }
 
+// Basic note type with only fields needed by investigation handlers
+export interface GitLabAPINoteBasic {
+  id: number;
+  body: string;
+  author: { username: string };
+}
+
 export interface GitLabAPIMergeRequest {
   id: number;
   iid: number;

apps/frontend/src/main/ipc-handlers/gitlab/utils.ts

@@ -13,6 +13,19 @@ import { getIsolatedGitEnv } from '../../utils/git-isolation';
 
 const DEFAULT_GITLAB_URL = 'https://gitlab.com';
 
+/**
+ * Custom error class for GitLab API errors with structured status code
+ */
+export class GitLabAPIError extends Error {
+  public readonly statusCode: number;
+
+  constructor(message: string, statusCode: number) {
+    super(message);
+    this.name = 'GitLabAPIError';
+    this.statusCode = statusCode;
+  }
+}
+
 function parseInstanceUrl(value: string): string | null {
   const candidate = value.trim();
   if (!candidate) return null;
@@ -261,13 +274,16 @@ export async function gitlabFetch(
 
     if (!response.ok) {
       const errorBody = await response.text();
-      throw new Error(`GitLab API error: ${response.status} ${response.statusText} - ${errorBody}`);
+      throw new GitLabAPIError(
+        `GitLab API error: ${response.status} ${response.statusText} - ${errorBody}`,
+        response.status
+      );
     }
 
     return response.json();
   } catch (error) {
     if (error instanceof Error && error.name === 'AbortError') {
-      throw new Error(`GitLab API timeout after ${GITLAB_API_TIMEOUT_MS / 1000}s: ${url}`);
+      throw new GitLabAPIError(`GitLab API timeout after ${GITLAB_API_TIMEOUT_MS / 1000}s: ${url}`, 0);
     }
     throw error;
   } finally {
@@ -316,7 +332,10 @@ export async function gitlabFetchWithCount(
 
     if (!response.ok) {
       const errorBody = await response.text();
-      throw new Error(`GitLab API error: ${response.status} ${response.statusText} - ${errorBody}`);
+      throw new GitLabAPIError(
+        `GitLab API error: ${response.status} ${response.statusText} - ${errorBody}`,
+        response.status
+      );
     }
 
     // Get total count from X-Total header (GitLab's pagination header)
@@ -327,7 +346,7 @@ export async function gitlabFetchWithCount(
     return { data, totalCount };
   } catch (error) {
     if (error instanceof Error && error.name === 'AbortError') {
-      throw new Error(`GitLab API timeout after ${GITLAB_API_TIMEOUT_MS / 1000}s: ${url}`);
+      throw new GitLabAPIError(`GitLab API timeout after ${GITLAB_API_TIMEOUT_MS / 1000}s: ${url}`, 0);
     }
     throw error;
   } finally {

apps/frontend/src/main/ipc-handlers/index.ts

@@ -35,6 +35,7 @@ import { registerProfileHandlers } from './profile-handlers';
 import { registerScreenshotHandlers } from './screenshot-handlers';
 import { registerTerminalWorktreeIpcHandlers } from './terminal';
 import { notificationService } from '../notification-service';
+import { setAgentManagerRef } from './utils';
 
 /**
  * Setup all IPC handlers across all domains
@@ -53,6 +54,9 @@ export function setupIpcHandlers(
   // Initialize notification service
   notificationService.initialize(getMainWindow);
 
+  // Wire up agent manager for circuit breaker cleanup
+  setAgentManagerRef(agentManager);
+
   // Project handlers (including Python environment setup)
   registerProjectHandlers(pythonEnvManager, agentManager, getMainWindow);
 

apps/frontend/src/main/ipc-handlers/linear-handlers.ts

@@ -507,6 +507,7 @@ ${safeDescription || 'No description provided.'}
               status: 'pending',
               phases: []
             };
+            // lgtm[js/http-to-file-access] - specDir is controlled, Linear data sanitized
             writeFileSync(path.join(specDir, AUTO_BUILD_PATHS.IMPLEMENTATION_PLAN), JSON.stringify(implementationPlan, null, 2), 'utf-8');
 
             // Create requirements.json
@@ -514,6 +515,7 @@ ${safeDescription || 'No description provided.'}
               task_description: description,
               workflow_type: 'feature'
             };
+            // lgtm[js/http-to-file-access] - specDir is controlled, Linear data sanitized
             writeFileSync(path.join(specDir, AUTO_BUILD_PATHS.REQUIREMENTS), JSON.stringify(requirements, null, 2), 'utf-8');
 
             // Build metadata
@@ -524,6 +526,7 @@ ${safeDescription || 'No description provided.'}
               linearUrl: safeUrl,
               category: 'feature'
             };
+            // lgtm[js/http-to-file-access] - specDir is controlled, Linear data sanitized
             writeFileSync(path.join(specDir, 'task_metadata.json'), JSON.stringify(metadata, null, 2), 'utf-8');
 
             // Start spec creation with the existing spec directory

apps/frontend/src/main/ipc-handlers/project-handlers.ts

@@ -1,6 +1,5 @@
-import { ipcMain, app } from 'electron';
-import { existsSync, } from 'fs';
-import path from 'path';
+import { ipcMain } from 'electron';
+import { existsSync } from 'fs';
 import { execFileSync } from 'child_process';
 import { IPC_CHANNELS } from '../../shared/constants';
 import type {

apps/frontend/src/main/ipc-handlers/terminal/worktree-handlers.ts

@@ -8,7 +8,7 @@ import type {
   OtherWorktreeInfo,
 } from '../../../shared/types';
 import path from 'path';
-import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync, symlinkSync, lstatSync } from 'fs';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync, symlinkSync, lstatSync, copyFileSync, cpSync, statSync } from 'fs';
 import { execFileSync, execFile } from 'child_process';
 import { promisify } from 'util';
 import { minimatch } from 'minimatch';
@@ -226,87 +226,405 @@ function getDefaultBranch(projectPath: string): string {
 }
 
 /**
- * Symlink node_modules from project root to worktree for TypeScript and tooling support.
- * This allows pre-commit hooks and IDE features to work without npm install in the worktree.
+ * Configuration for a single dependency to be shared in a worktree.
+ */
+interface DependencyConfig {
+  /** Dependency type identifier (e.g., 'node_modules', 'venv') */
+  depType: string;
+  /** Strategy for sharing this dependency in worktrees */
+  strategy: 'symlink' | 'recreate' | 'copy' | 'skip';
+  /** Relative path from project root to the dependency directory */
+  sourceRelPath: string;
+  /** Path to requirements file for recreate strategy (e.g., 'requirements.txt') */
+  requirementsFile?: string;
+  /** Package manager used (e.g., 'npm', 'pip', 'uv') */
+  packageManager?: string;
+}
+
+/**
+ * Default mapping from dependency type to sharing strategy.
+ *
+ * Data-driven — add new entries here rather than writing if/else branches.
+ * Mirrors the Python implementation in apps/backend/core/workspace/dependency_strategy.py.
+ */
+const DEFAULT_STRATEGY_MAP: Record<string, 'symlink' | 'recreate' | 'copy' | 'skip'> = {
+  // JavaScript / Node.js — symlink is safe and fast
+  node_modules: 'symlink',
+  // Python — venvs MUST be recreated, not symlinked.
+  // CPython bug #106045: pyvenv.cfg discovery does not resolve symlinks,
+  // so a symlinked venv resolves paths relative to the target, not the worktree.
+  venv: 'recreate',
+  '.venv': 'recreate',
+  // PHP — Composer vendor dir is safe to symlink
+  vendor_php: 'symlink',
+  // Ruby — Bundler vendor/bundle is safe to symlink
+  vendor_bundle: 'symlink',
+  // Rust — build output dir, skip (rebuilt per-worktree)
+  cargo_target: 'skip',
+  // Go — global module cache, nothing in-tree to share
+  go_modules: 'skip',
+};
+
+/**
+ * Load dependency configs from the project index, or fall back to hardcoded
+ * node_modules-only behavior for backward compatibility.
+ */
+function loadDependencyConfigs(projectPath: string): DependencyConfig[] {
+  const indexPath = path.join(projectPath, '.auto-claude', 'project_index.json');
+
+  if (existsSync(indexPath)) {
+    try {
+      const index = JSON.parse(readFileSync(indexPath, 'utf-8'));
+      // Use the aggregated top-level dependency_locations which already
+      // contain project-relative paths (e.g. "apps/backend/.venv" instead
+      // of just ".venv"), avoiding a monorepo path resolution bug.
+      const depLocations = index?.dependency_locations;
+      if (Array.isArray(depLocations)) {
+        const configs: DependencyConfig[] = [];
+        const seen = new Set<string>();
+
+        for (const dep of depLocations) {
+          if (!dep || typeof dep !== 'object') continue;
+          const depObj = dep as Record<string, unknown>;
+          const depType = String(depObj.type || '');
+          const relPath = String(depObj.path || '');
+          if (!depType || !relPath || seen.has(relPath)) continue;
+
+          // Path containment: reject absolute paths and traversals
+          if (path.isAbsolute(relPath)) continue;
+          if (relPath.split('/').includes('..') || relPath.split('\\').includes('..')) continue;
+
+          // Defense-in-depth: verify resolved path stays within project
+          const resolved = path.resolve(projectPath, relPath);
+          if (!resolved.startsWith(path.resolve(projectPath) + path.sep)) continue;
+
+          seen.add(relPath);
+
+          const strategy = DEFAULT_STRATEGY_MAP[depType] ?? 'skip';
+
+          // Validate requirementsFile path containment
+          let reqFile: string | undefined;
+          if (depObj.requirements_file) {
+            const rf = String(depObj.requirements_file);
+            const rfParts = rf.split('/');
+            const rfPartsWin = rf.split('\\');
+            if (!path.isAbsolute(rf) && !rfParts.includes('..') && !rfPartsWin.includes('..')) {
+              // Defense-in-depth: resolved-path containment (matches relPath check)
+              const resolvedReq = path.resolve(projectPath, rf);
+              if (resolvedReq.startsWith(path.resolve(projectPath) + path.sep)) {
+                reqFile = rf;
+              }
+            }
+          }
+
+          configs.push({
+            depType,
+            strategy,
+            sourceRelPath: relPath,
+            requirementsFile: reqFile,
+            packageManager: depObj.package_manager ? String(depObj.package_manager) : undefined,
+          });
+        }
+
+        if (configs.length > 0) {
+          return configs;
+        }
+      }
+    } catch (error) {
+      debugError('[TerminalWorktree] Failed to read project index:', error);
+    }
+  }
+
+  // Fallback: hardcoded node_modules-only behavior (same as legacy)
+  return [
+    { depType: 'node_modules', strategy: 'symlink', sourceRelPath: 'node_modules' },
+    { depType: 'node_modules', strategy: 'symlink', sourceRelPath: 'apps/frontend/node_modules' },
+  ];
+}
+
+/**
+ * Set up dependencies in a worktree using strategy-based dispatch.
+ *
+ * Reads dependency configs from the project index and applies the correct
+ * strategy for each: symlink, recreate, copy, or skip.
+ *
+ * All operations are non-blocking on failure — errors are logged but never thrown.
  *
  * @param projectPath - The main project directory
  * @param worktreePath - Path to the worktree
- * @returns Array of symlinked paths (relative to worktree)
+ * @returns Array of successfully processed dependency relative paths
  */
-function symlinkNodeModulesToWorktree(projectPath: string, worktreePath: string): string[] {
+async function setupWorktreeDependencies(projectPath: string, worktreePath: string): Promise<string[]> {
+  const configs = loadDependencyConfigs(projectPath);
+  const processed: string[] = [];
+
+  for (const config of configs) {
+    try {
+      let performed = false;
+      switch (config.strategy) {
+        case 'symlink':
+          performed = applySymlinkStrategy(projectPath, worktreePath, config);
+          break;
+        case 'recreate':
+          performed = await applyRecreateStrategy(projectPath, worktreePath, config);
+          break;
+        case 'copy':
+          performed = applyCopyStrategy(projectPath, worktreePath, config);
+          break;
+        case 'skip':
+          debugLog('[TerminalWorktree] Skipping', config.depType, `(${config.sourceRelPath}) - skip strategy`);
+          continue; // Don't record skipped entries in processed list
+      }
+      if (performed) processed.push(config.sourceRelPath);
+    } catch (error) {
+      debugError('[TerminalWorktree] Failed to apply', config.strategy, 'strategy for', config.sourceRelPath, ':', error);
+      console.warn(`[TerminalWorktree] Warning: Failed to set up ${config.sourceRelPath}`);
+    }
+  }
+
+  return processed;
+}
+
+/**
+ * Apply symlink strategy: create a symlink (or Windows junction) from worktree to project source.
+ * Reuses the existing platform-specific symlink creation pattern.
+ */
+function applySymlinkStrategy(projectPath: string, worktreePath: string, config: DependencyConfig): boolean {
+  const sourcePath = path.join(projectPath, config.sourceRelPath);
+  const targetPath = path.join(worktreePath, config.sourceRelPath);
+
+  if (!existsSync(sourcePath)) {
+    debugLog('[TerminalWorktree] Skipping symlink', config.sourceRelPath, '- source missing');
+    return false;
+  }
+
+  if (existsSync(targetPath)) {
+    debugLog('[TerminalWorktree] Skipping symlink', config.sourceRelPath, '- target exists');
+    return false;
+  }
+
+  // Check for broken symlinks
+  try {
+    lstatSync(targetPath);
+    debugLog('[TerminalWorktree] Skipping symlink', config.sourceRelPath, '- target exists (possibly broken symlink)');
+    return false;
+  } catch {
+    // Target doesn't exist at all — good, we can create symlink
+  }
+
+  const targetDir = path.dirname(targetPath);
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+  }
+
+  try {
+    if (isWindows()) {
+      symlinkSync(sourcePath, targetPath, 'junction');
+      debugLog('[TerminalWorktree] Created junction (Windows):', config.sourceRelPath, '->', sourcePath);
+    } else {
+      const relativePath = path.relative(path.dirname(targetPath), sourcePath);
+      symlinkSync(relativePath, targetPath);
+      debugLog('[TerminalWorktree] Created symlink (Unix):', config.sourceRelPath, '->', relativePath);
+    }
+    return true;
+  } catch (error) {
+    debugError('[TerminalWorktree] Could not create symlink for', config.sourceRelPath, ':', error);
+    console.warn(`[TerminalWorktree] Warning: Failed to link ${config.sourceRelPath}`);
+    return false;
+  }
+}
+
+/**
+ * Apply recreate strategy: create a fresh virtual environment in the worktree.
+ *
+ * Python venvs cannot be symlinked due to CPython bug #106045 — pyvenv.cfg
+ * discovery does not resolve symlinks, so paths resolve relative to the
+ * symlink target instead of the worktree.
+ */
+async function applyRecreateStrategy(projectPath: string, worktreePath: string, config: DependencyConfig): Promise<boolean> {
+  const venvPath = path.join(worktreePath, config.sourceRelPath);
+
+  if (existsSync(venvPath)) {
+    debugLog('[TerminalWorktree] Skipping recreate', config.sourceRelPath, '- already exists');
+    return false;
+  }
+
+  // Detect Python executable from the source venv or fall back to system Python
+  const sourceVenv = path.join(projectPath, config.sourceRelPath);
+  let pythonExec = isWindows() ? 'python' : 'python3';
+
+  if (existsSync(sourceVenv)) {
+    const unixCandidate = path.join(sourceVenv, 'bin', 'python');
+    const winCandidate = path.join(sourceVenv, 'Scripts', 'python.exe');
+    if (existsSync(unixCandidate)) {
+      pythonExec = unixCandidate;
+    } else if (existsSync(winCandidate)) {
+      pythonExec = winCandidate;
+    }
+  }
+
+  // Create the venv
+  try {
+    debugLog('[TerminalWorktree] Creating venv at', config.sourceRelPath);
+    await execFileAsync(pythonExec, ['-m', 'venv', venvPath], {
+      encoding: 'utf-8',
+      timeout: 120000,
+    });
+  } catch (error) {
+    if (isTimeoutError(error)) {
+      debugError('[TerminalWorktree] venv creation timed out for', config.sourceRelPath);
+      console.warn(`[TerminalWorktree] Warning: venv creation timed out for ${config.sourceRelPath}`);
+    } else {
+      debugError('[TerminalWorktree] venv creation failed for', config.sourceRelPath, ':', error);
+      console.warn(`[TerminalWorktree] Warning: Could not create venv at ${config.sourceRelPath}`);
+    }
+    // Clean up partial venv so retries aren't blocked
+    if (existsSync(venvPath)) {
+      try { rmSync(venvPath, { recursive: true, force: true }); } catch { /* best-effort */ }
+    }
+    return false;
+  }
+
+  // Install from requirements file if specified
+  if (config.requirementsFile) {
+    const reqPath = path.join(projectPath, config.requirementsFile);
+    if (existsSync(reqPath)) {
+      const pipExec = isWindows()
+        ? path.join(venvPath, 'Scripts', 'pip.exe')
+        : path.join(venvPath, 'bin', 'pip');
+
+      // Build install command based on file type
+      const reqBasename = path.basename(config.requirementsFile);
+      let installArgs: string[] | null;
+      if (reqBasename === 'pyproject.toml') {
+        // Snapshot-install from worktree copy (non-editable to avoid
+        // symlinking back to the main project source tree).
+        const worktreeReq = path.join(worktreePath, config.requirementsFile!);
+        const installDir = existsSync(worktreeReq) ? path.dirname(worktreeReq) : path.dirname(reqPath);
+        installArgs = ['install', installDir];
+      } else if (reqBasename === 'Pipfile') {
+        debugLog('[TerminalWorktree] Skipping Pipfile-based install (use pipenv in worktree)');
+        installArgs = null;
+      } else {
+        installArgs = ['install', '-r', reqPath];
+      }
+
+      if (installArgs) {
+        try {
+          debugLog('[TerminalWorktree] Installing deps from', config.requirementsFile);
+          await execFileAsync(pipExec, installArgs, {
+            encoding: 'utf-8',
+            timeout: 120000,
+          });
+        } catch (error) {
+          if (isTimeoutError(error)) {
+            debugError('[TerminalWorktree] pip install timed out for', config.requirementsFile);
+            console.warn(`[TerminalWorktree] Warning: Dependency install timed out for ${config.requirementsFile}`);
+          } else {
+            debugError('[TerminalWorktree] pip install failed:', error);
+          }
+          // Clean up broken venv so retries aren't blocked
+          if (existsSync(venvPath)) {
+            try { rmSync(venvPath, { recursive: true, force: true }); } catch { /* best-effort */ }
+          }
+          return false;
+        }
+      }
+    }
+  }
+
+  debugLog('[TerminalWorktree] Recreated venv at', config.sourceRelPath);
+  return true;
+}
+
+/**
+ * Apply copy strategy: copy a file or directory from project to worktree.
+ */
+function applyCopyStrategy(projectPath: string, worktreePath: string, config: DependencyConfig): boolean {
+  const sourcePath = path.join(projectPath, config.sourceRelPath);
+  const targetPath = path.join(worktreePath, config.sourceRelPath);
+
+  if (!existsSync(sourcePath)) {
+    debugLog('[TerminalWorktree] Skipping copy', config.sourceRelPath, '- source missing');
+    return false;
+  }
+
+  if (existsSync(targetPath)) {
+    debugLog('[TerminalWorktree] Skipping copy', config.sourceRelPath, '- target exists');
+    return false;
+  }
+
+  const targetDir = path.dirname(targetPath);
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+  }
+
+  try {
+    if (statSync(sourcePath).isDirectory()) {
+      cpSync(sourcePath, targetPath, { recursive: true });
+    } else {
+      copyFileSync(sourcePath, targetPath);
+    }
+    debugLog('[TerminalWorktree] Copied', config.sourceRelPath, 'to worktree');
+    return true;
+  } catch (error) {
+    debugError('[TerminalWorktree] Could not copy', config.sourceRelPath, ':', error);
+    console.warn(`[TerminalWorktree] Warning: Could not copy ${config.sourceRelPath}`);
+    return false;
+  }
+}
+
+/**
+ * Symlink the project root's .claude/ directory into a terminal worktree.
+ * This enables Claude Code features (settings, commands, memory) in worktree terminals.
+ * Follows the same pattern as setupWorktreeDependencies().
+ */
+function symlinkClaudeConfigToWorktree(projectPath: string, worktreePath: string): string[] {
   const symlinked: string[] = [];
 
-  // Node modules locations to symlink for TypeScript and tooling support.
-  // These are the standard locations for this monorepo structure.
-  //
-  // Design rationale:
-  // - Hardcoded paths are intentional for simplicity and reliability
-  // - Dynamic discovery (reading workspaces from package.json) would add complexity
-  //   and potential failure points without significant benefit
-  // - This monorepo uses npm workspaces with hoisting, so dependencies are primarily
-  //   in root node_modules with workspace-specific deps in apps/frontend/node_modules
-  //
-  // To add new workspace locations:
-  // 1. Add [sourceRelPath, targetRelPath] tuple below
-  // 2. Update the parallel Python implementation in apps/backend/core/workspace/setup.py
-  // 3. Update the pre-commit hook check in .husky/pre-commit if needed
-  const nodeModulesLocations = [
-    ['node_modules', 'node_modules'],
-    ['apps/frontend/node_modules', 'apps/frontend/node_modules'],
-  ];
+  const sourceRel = '.claude';
+  const sourcePath = path.join(projectPath, sourceRel);
+  const targetPath = path.join(worktreePath, sourceRel);
 
-  for (const [sourceRel, targetRel] of nodeModulesLocations) {
-    const sourcePath = path.join(projectPath, sourceRel);
-    const targetPath = path.join(worktreePath, targetRel);
+  // Skip if source doesn't exist
+  if (!existsSync(sourcePath)) {
+    debugLog('[TerminalWorktree] Skipping .claude symlink - source does not exist:', sourcePath);
+    return symlinked;
+  }
 
-    // Skip if source doesn't exist
-    if (!existsSync(sourcePath)) {
-      debugLog('[TerminalWorktree] Skipping symlink - source does not exist:', sourceRel);
-      continue;
-    }
-
-    // Skip if target already exists (don't overwrite existing node_modules)
-    if (existsSync(targetPath)) {
-      debugLog('[TerminalWorktree] Skipping symlink - target already exists:', targetRel);
-      continue;
-    }
-
-    // Also skip if target is a symlink (even if broken)
-    try {
-      lstatSync(targetPath);
-      debugLog('[TerminalWorktree] Skipping symlink - target exists (possibly broken symlink):', targetRel);
-      continue;
-    } catch {
-      // Target doesn't exist at all - good, we can create symlink
-    }
-
-    // Ensure parent directory exists
-    const targetDir = path.dirname(targetPath);
-    if (!existsSync(targetDir)) {
-      mkdirSync(targetDir, { recursive: true });
-    }
-
-    try {
-      // Platform-specific symlink creation:
-      // - Windows: Use 'junction' type which requires absolute paths (no admin rights required)
-      // - Unix (macOS/Linux): Use relative paths for portability (worktree can be moved)
-      if (isWindows()) {
-        symlinkSync(sourcePath, targetPath, 'junction');
-        debugLog('[TerminalWorktree] Created junction (Windows):', targetRel, '->', sourcePath);
-      } else {
-        // On Unix, use relative symlinks for portability (matches Python implementation)
-        const relativePath = path.relative(path.dirname(targetPath), sourcePath);
-        symlinkSync(relativePath, targetPath);
-        debugLog('[TerminalWorktree] Created symlink (Unix):', targetRel, '->', relativePath);
-      }
-      symlinked.push(targetRel);
-    } catch (error) {
-      // Symlink creation can fail on some systems (e.g., FAT32 filesystem, or permission issues)
-      // Log warning but don't fail - worktree is still usable, just without TypeScript checking
-      // Note: This warning appears in dev console. Users may see TypeScript errors in pre-commit hooks.
-      debugError('[TerminalWorktree] Could not create symlink for', targetRel, ':', error);
-      console.warn(`[TerminalWorktree] Warning: Failed to link ${targetRel} - TypeScript checks may fail in this worktree`);
+  // Skip if target already exists
+  if (existsSync(targetPath)) {
+    debugLog('[TerminalWorktree] Skipping .claude symlink - target already exists:', targetPath);
+    return symlinked;
+  }
+
+  // Also skip if target is a symlink (even if broken)
+  try {
+    lstatSync(targetPath);
+    debugLog('[TerminalWorktree] Skipping .claude symlink - target exists (possibly broken symlink):', targetPath);
+    return symlinked;
+  } catch {
+    // Target doesn't exist at all - good, we can create symlink
+  }
+
+  // Ensure parent directory exists
+  const targetDir = path.dirname(targetPath);
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true });
+  }
+
+  try {
+    if (isWindows()) {
+      symlinkSync(sourcePath, targetPath, 'junction');
+      debugLog('[TerminalWorktree] Created .claude junction (Windows):', sourceRel, '->', sourcePath);
+    } else {
+      const relativePath = path.relative(path.dirname(targetPath), sourcePath);
+      symlinkSync(relativePath, targetPath);
+      debugLog('[TerminalWorktree] Created .claude symlink (Unix):', sourceRel, '->', relativePath);
     }
+    symlinked.push(sourceRel);
+  } catch (error) {
+    debugError('[TerminalWorktree] Could not create symlink for .claude:', error);
   }
 
   return symlinked;
@@ -516,11 +834,17 @@ async function createTerminalWorktree(
       debugLog('[TerminalWorktree] Created worktree in detached HEAD mode from', baseRef);
     }
 
-    // Symlink node_modules for TypeScript and tooling support
+    // Set up dependencies (node_modules, venvs, etc.) for tooling support
     // This allows pre-commit hooks to run typecheck without npm install in worktree
-    const symlinkedModules = symlinkNodeModulesToWorktree(projectPath, worktreePath);
-    if (symlinkedModules.length > 0) {
-      debugLog('[TerminalWorktree] Symlinked dependencies:', symlinkedModules.join(', '));
+    const setupDeps = await setupWorktreeDependencies(projectPath, worktreePath);
+    if (setupDeps.length > 0) {
+      debugLog('[TerminalWorktree] Set up worktree dependencies:', setupDeps.join(', '));
+    }
+
+    // Symlink .claude/ config for Claude Code features (settings, commands, memory)
+    const symlinkedClaude = symlinkClaudeConfigToWorktree(projectPath, worktreePath);
+    if (symlinkedClaude.length > 0) {
+      debugLog('[TerminalWorktree] Symlinked Claude config:', symlinkedClaude.join(', '));
     }
 
     const config: TerminalWorktreeConfig = {

apps/frontend/src/main/ipc-handlers/utils.ts

@@ -12,6 +12,17 @@ import type { BrowserWindow } from "electron";
 const warnTimestamps = new Map<string, number>();
 const WARN_COOLDOWN_MS = 5000; // 5 seconds between warnings per channel
 
+/** Circuit breaker: kill agents after consecutive renderer disposal errors */
+const MAX_CONSECUTIVE_DISPOSAL_ERRORS = 10;
+let consecutiveDisposalErrors = 0;
+let agentManagerRef: { killAll: () => void | Promise<void> } | null = null;
+let circuitBreakerTriggered = false;
+
+/** Set agent manager reference for circuit breaker cleanup */
+export function setAgentManagerRef(manager: { killAll: () => void | Promise<void> }): void {
+  agentManagerRef = manager;
+}
+
 /**
  * Check if a channel is within the warning cooldown period.
  * @returns true if within cooldown (should skip warning), false if cooldown expired
@@ -108,6 +119,9 @@ export function safeSendToRenderer(
 
     // All checks passed - safe to send
     mainWindow.webContents.send(channel, ...args);
+    // On successful send, reset circuit breaker state (allow re-trigger after recovery)
+    consecutiveDisposalErrors = 0;
+    circuitBreakerTriggered = false;
     return true;
   } catch (error) {
     // Catch any disposal errors that might occur between our checks and the actual send
@@ -115,6 +129,16 @@ export function safeSendToRenderer(
 
     // Only log disposal errors once per channel to avoid log spam
     if (errorMessage.includes("disposed") || errorMessage.includes("destroyed")) {
+      // Circuit breaker: track consecutive disposal errors
+      consecutiveDisposalErrors++;
+      if (consecutiveDisposalErrors >= MAX_CONSECUTIVE_DISPOSAL_ERRORS && !circuitBreakerTriggered && agentManagerRef) {
+        circuitBreakerTriggered = true;
+        console.error('[safeSendToRenderer] Circuit breaker triggered: killing all agents after renderer death');
+        Promise.resolve(agentManagerRef.killAll()).catch((err) => {
+          console.error('[safeSendToRenderer] Error killing agents:', err);
+        });
+      }
+
       if (!isWithinCooldown(channel)) {
         console.warn(`[safeSendToRenderer] Frame disposed, skipping send: ${channel}`);
         recordWarning(channel);

apps/frontend/src/main/rate-limit-detector.ts

@@ -5,6 +5,7 @@
 
 import { getClaudeProfileManager } from './claude-profile-manager';
 import { getUsageMonitor } from './claude-profile/usage-monitor';
+import { debugLog } from '../shared/utils/debug-logger';
 
 /**
  * Regex pattern to detect Claude Code rate limit messages
@@ -476,6 +477,14 @@ export function getBestAvailableProfileEnv(): BestProfileEnvResult {
   const profileManager = getClaudeProfileManager();
   const activeProfile = profileManager.getActiveProfile();
 
+  debugLog('[RateLimitDetector] getBestAvailableProfileEnv() called:', {
+    activeProfileId: activeProfile.id,
+    activeProfileName: activeProfile.name,
+    hasConfigDir: !!activeProfile.configDir,
+    configDir: activeProfile.configDir,
+    weeklyUsagePercent: activeProfile.usage?.weeklyUsagePercent,
+  });
+
   // Check for explicit rate limit (from previous API errors)
   const rateLimitStatus = profileManager.isProfileRateLimited(activeProfile.id);
 
@@ -492,28 +501,24 @@ export function getBestAvailableProfileEnv(): BestProfileEnvResult {
       : undefined;
 
   if (needsSwap) {
-    if (process.env.DEBUG === 'true') {
-      console.warn('[RateLimitDetector] Active profile needs swap:', {
-        activeProfile: activeProfile.name,
-        isRateLimited: rateLimitStatus.limited,
-        isAtCapacity,
-        weeklyUsage: activeProfile.usage?.weeklyUsagePercent,
-        limitType: rateLimitStatus.type,
-        resetAt: rateLimitStatus.resetAt
-      });
-    }
+    debugLog('[RateLimitDetector] Active profile needs swap:', {
+      activeProfile: activeProfile.name,
+      isRateLimited: rateLimitStatus.limited,
+      isAtCapacity,
+      weeklyUsage: activeProfile.usage?.weeklyUsagePercent,
+      limitType: rateLimitStatus.type,
+      resetAt: rateLimitStatus.resetAt
+    });
 
     // Try to find a better profile
     const bestProfile = profileManager.getBestAvailableProfile(activeProfile.id);
 
     if (bestProfile) {
-      if (process.env.DEBUG === 'true') {
-        console.warn('[RateLimitDetector] Using alternative profile:', {
-          originalProfile: activeProfile.name,
-          alternativeProfile: bestProfile.name,
-          reason: swapReason
-        });
-      }
+      debugLog('[RateLimitDetector] Using alternative profile:', {
+        originalProfile: activeProfile.name,
+        alternativeProfile: bestProfile.name,
+        reason: swapReason
+      });
 
       // Persist the swap by updating the active profile
       // This ensures the UI reflects which account is actually being used
@@ -564,6 +569,14 @@ export function getBestAvailableProfileEnv(): BestProfileEnvResult {
 
       const profileEnv = profileManager.getProfileEnv(bestProfile.id);
 
+      debugLog('[RateLimitDetector] Profile env for swapped profile:', {
+        profileId: bestProfile.id,
+        hasClaudeConfigDir: !!profileEnv.CLAUDE_CONFIG_DIR,
+        claudeConfigDir: profileEnv.CLAUDE_CONFIG_DIR,
+        hasOAuthToken: !!profileEnv.CLAUDE_CODE_OAUTH_TOKEN,
+        envKeys: Object.keys(profileEnv),
+      });
+
       return {
         env: ensureCleanProfileEnv(profileEnv),
         profileId: bestProfile.id,
@@ -576,14 +589,21 @@ export function getBestAvailableProfileEnv(): BestProfileEnvResult {
         }
       };
     } else {
-      if (process.env.DEBUG === 'true') {
-        console.warn('[RateLimitDetector] No alternative profile available, using rate-limited/at-capacity profile');
-      }
+      debugLog('[RateLimitDetector] No alternative profile available, using rate-limited/at-capacity profile');
     }
   }
 
   // Use active profile (either it's fine, or no better alternative exists)
   const activeEnv = profileManager.getActiveProfileEnv();
+
+  debugLog('[RateLimitDetector] Using active profile env (no swap):', {
+    profileId: activeProfile.id,
+    hasClaudeConfigDir: !!activeEnv.CLAUDE_CONFIG_DIR,
+    claudeConfigDir: activeEnv.CLAUDE_CONFIG_DIR,
+    hasOAuthToken: !!activeEnv.CLAUDE_CODE_OAUTH_TOKEN,
+    envKeys: Object.keys(activeEnv),
+  });
+
   return {
     env: ensureCleanProfileEnv(activeEnv),
     profileId: activeProfile.id,
@@ -595,23 +615,55 @@ export function getBestAvailableProfileEnv(): BestProfileEnvResult {
 /**
  * Ensure the profile environment is clean for subprocess invocation.
  *
- * When CLAUDE_CONFIG_DIR is set, we MUST clear CLAUDE_CODE_OAUTH_TOKEN to prevent
- * the Claude Agent SDK from using a hardcoded/cached token (e.g., from .env file)
- * instead of reading fresh credentials from the specified config directory.
+ * When CLAUDE_CONFIG_DIR is set, we MUST clear both CLAUDE_CODE_OAUTH_TOKEN and
+ * ANTHROPIC_API_KEY to prevent the Claude Agent SDK from using hardcoded/cached
+ * tokens or API keys (e.g., from .env file or shell environment) instead of reading
+ * fresh credentials from the specified config directory.
+ *
+ * ANTHROPIC_API_KEY is cleared to prevent Claude Code from using API keys present
+ * in the shell environment, which would cause it to show "Claude API" instead of
+ * "Claude Max" and bypass the intended config dir credentials.
  *
  * This is critical for multi-account switching: when switching from a rate-limited
  * account to an available one, the subprocess must use the new account's credentials.
  *
+ * Also warns if the profile env is empty, which indicates a misconfigured profile.
+ *
  * @param env - Profile environment from getProfileEnv() or getActiveProfileEnv()
- * @returns Environment with CLAUDE_CODE_OAUTH_TOKEN cleared if CLAUDE_CONFIG_DIR is set
+ * @returns Environment with CLAUDE_CODE_OAUTH_TOKEN and ANTHROPIC_API_KEY cleared if CLAUDE_CONFIG_DIR is set
  */
-function ensureCleanProfileEnv(env: Record<string, string>): Record<string, string> {
+export function ensureCleanProfileEnv(env: Record<string, string>): Record<string, string> {
+  debugLog('[RateLimitDetector] ensureCleanProfileEnv() input:', {
+    hasClaudeConfigDir: !!env.CLAUDE_CONFIG_DIR,
+    claudeConfigDir: env.CLAUDE_CONFIG_DIR,
+    hasOAuthToken: !!env.CLAUDE_CODE_OAUTH_TOKEN,
+    willClearOAuthToken: !!env.CLAUDE_CONFIG_DIR,
+    willClearApiKey: !!env.CLAUDE_CONFIG_DIR,
+  });
+
+  // Warn if the profile environment is empty — this likely indicates a misconfigured profile
+  if (Object.keys(env).length === 0) {
+    console.warn('[RateLimitDetector] ensureCleanProfileEnv() received empty profile env — profile may be misconfigured');
+  }
+
   if (env.CLAUDE_CONFIG_DIR) {
-    // Clear CLAUDE_CODE_OAUTH_TOKEN to ensure SDK uses credentials from CLAUDE_CONFIG_DIR
-    return {
+    // Clear CLAUDE_CODE_OAUTH_TOKEN and ANTHROPIC_API_KEY to ensure SDK uses credentials from CLAUDE_CONFIG_DIR
+    // ANTHROPIC_API_KEY must also be cleared to prevent Claude Code from using
+    // API keys that may be present in the shell environment instead of the config dir credentials.
+    const cleanedEnv = {
       ...env,
-      CLAUDE_CODE_OAUTH_TOKEN: ''
+      CLAUDE_CODE_OAUTH_TOKEN: '',
+      ANTHROPIC_API_KEY: ''
     };
+
+    debugLog('[RateLimitDetector] ensureCleanProfileEnv() output:', {
+      claudeConfigDirPreserved: 'CLAUDE_CONFIG_DIR' in cleanedEnv,
+      claudeConfigDir: (cleanedEnv as Record<string, string>).CLAUDE_CONFIG_DIR,
+      oauthTokenCleared: cleanedEnv.CLAUDE_CODE_OAUTH_TOKEN === '',
+      envKeys: Object.keys(cleanedEnv),
+    });
+
+    return cleanedEnv;
   }
   return env;
 }

apps/frontend/src/main/terminal/pty-manager.ts

@@ -262,11 +262,16 @@ export function setupPtyHandlers(
 
 /**
  * Constants for chunked write behavior
- * CHUNKED_WRITE_THRESHOLD: Data larger than this (bytes) will be written in chunks
- * CHUNK_SIZE: Size of each chunk - smaller chunks yield to event loop more frequently
+ * CHUNKED_WRITE_THRESHOLD: Data larger than this (bytes) will be written in chunks.
+ *   Set high enough that typical pastes go through as a single synchronous write.
+ * CHUNK_SIZE: Size of each chunk. Larger chunks = fewer event-loop yields = less
+ *   GPU pressure when many terminals are rendering simultaneously.
+ *   Previous values (1000/100) caused GPU context exhaustion: a 9KB paste produced
+ *   ~91 setImmediate yields, letting GPU rendering tasks from 8+ terminals pile up
+ *   until ContextResult::kTransientFailure crashed the app.
  */
-const CHUNKED_WRITE_THRESHOLD = 1000;
-const CHUNK_SIZE = 100;
+const CHUNKED_WRITE_THRESHOLD = 16_384;
+const CHUNK_SIZE = 8_192;
 
 /**
  * Write queue per terminal to prevent interleaving of concurrent writes.

apps/frontend/src/preload/api/modules/github-api.ts

@@ -387,7 +387,7 @@ export interface PRReviewResult {
   success: boolean;
   findings: PRReviewFinding[];
   summary: string;
-  overallStatus: 'approve' | 'request_changes' | 'comment';
+  overallStatus: 'approve' | 'request_changes' | 'comment' | 'in_progress';
   reviewId?: number;
   reviewedAt: string;
   error?: string;
@@ -403,6 +403,8 @@ export interface PRReviewResult {
   hasPostedFindings?: boolean;
   postedFindingIds?: string[];
   postedAt?: string;
+  // In-progress review tracking
+  inProgressSince?: string;
 }
 
 /**

apps/frontend/src/renderer/components/Sidebar.tsx

@@ -19,6 +19,7 @@ import {
   Sparkles,
   GitBranch,
   HelpCircle,
+  Heart,
   Wrench,
   PanelLeft,
   PanelLeftClose
@@ -452,6 +453,26 @@ export function Sidebar({
             </Tooltip>
           </div>
 
+          {/* Sponsor link */}
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                onClick={() => window.open('https://github.com/sponsors/AndyMik90', '_blank')}
+                className={cn(
+                  'flex w-full items-center text-xs transition-colors',
+                  'text-amber-500/70 hover:text-amber-400',
+                  isCollapsed ? 'justify-center' : 'gap-1.5 px-3'
+                )}
+              >
+                <Heart className="h-3.5 w-3.5" />
+                {!isCollapsed && <span>{t('actions.sponsor')}</span>}
+              </button>
+            </TooltipTrigger>
+            {isCollapsed && (
+              <TooltipContent side="right">{t('actions.sponsor')}</TooltipContent>
+            )}
+          </Tooltip>
+
           {/* New Task button */}
           <Tooltip>
             <TooltipTrigger asChild>

apps/frontend/src/renderer/components/github-prs/GitHubPRs.tsx

@@ -66,6 +66,7 @@ export function GitHubPRs({ onOpenSettings, isActive = false }: GitHubPRsProps)
     reviewProgress,
     startedAt,
     isReviewing,
+    isExternalReview,
     previousReviewResult,
     hasMore,
     selectPR,
@@ -269,6 +270,7 @@ export function GitHubPRs({ onOpenSettings, isActive = false }: GitHubPRsProps)
               reviewProgress={reviewProgress}
               startedAt={startedAt}
               isReviewing={isReviewing}
+              isExternalReview={isExternalReview}
               initialNewCommitsCheck={storedNewCommitsCheck}
               isActive={isActive}
               isLoadingFiles={isLoadingPRDetails}

apps/frontend/src/renderer/components/github-prs/components/PRDetail.tsx

@@ -35,6 +35,7 @@ import { PRLogs } from './PRLogs';
 
 import type { PRData, PRReviewResult, PRReviewProgress } from '../hooks/useGitHubPRs';
 import type { NewCommitsCheck, MergeReadiness, PRLogs as PRLogsType, WorkflowsAwaitingApprovalResult } from '../../../../preload/api/modules/github-api';
+import { usePRReviewStore } from '../../../stores/github';
 
 interface PRDetailProps {
   pr: PRData;
@@ -44,6 +45,7 @@ interface PRDetailProps {
   reviewProgress: PRReviewProgress | null;
   startedAt: string | null;
   isReviewing: boolean;
+  isExternalReview?: boolean;
   initialNewCommitsCheck?: NewCommitsCheck | null;
   isActive?: boolean;
   isLoadingFiles?: boolean;
@@ -78,6 +80,7 @@ export function PRDetail({
   reviewProgress,
   startedAt,
   isReviewing,
+  isExternalReview = false,
   initialNewCommitsCheck,
   isActive: _isActive = false,
   isLoadingFiles = false,
@@ -398,6 +401,59 @@ export function PRDetail({
     };
   }, [isReviewing, onGetLogs]);
 
+  /**
+   * Completion detection for external (in-progress) reviews
+   *
+   * When the backend reports overallStatus === 'in_progress', the store sets
+   * isExternalReview = true and isReviewing = true. This effect polls the
+   * review result file every 3 seconds to detect when the external review
+   * finishes. Once a completed result is found (overallStatus !== 'in_progress'),
+   * we update the store which will set isReviewing = false and display the result.
+   */
+  useEffect(() => {
+    if (!isReviewing || !isExternalReview) return;
+
+    const POLL_INTERVAL_MS = 3000;
+    const MAX_POLL_DURATION_MS = 30 * 60 * 1000; // 30 minutes
+    const pollStart = Date.now();
+
+    const pollForCompletion = async () => {
+      // Timeout: stop polling after 30 minutes to avoid indefinite polling
+      if (Date.now() - pollStart > MAX_POLL_DURATION_MS) {
+        usePRReviewStore.getState().setPRReviewResult(projectId, {
+          prNumber: pr.number,
+          repo: '',
+          success: false,
+          findings: [],
+          summary: '',
+          overallStatus: 'comment',
+          reviewedAt: new Date().toISOString(),
+          error: 'External review polling timed out after 30 minutes',
+        });
+        return;
+      }
+
+      try {
+        const result = await window.electronAPI.github.getPRReview(projectId, pr.number);
+        if (result && result.overallStatus !== 'in_progress') {
+          // Only accept results that were produced AFTER we detected the external review.
+          // Otherwise this is a stale result from a previous review still on disk
+          // (in-progress results are intentionally NOT saved to disk).
+          if (startedAt && result.reviewedAt && new Date(result.reviewedAt) > new Date(startedAt)) {
+            usePRReviewStore.getState().setPRReviewResult(projectId, result);
+          }
+        }
+      } catch {
+        // Ignore errors — transient file read failures shouldn't stop polling
+      }
+    };
+
+    // Poll immediately, then every 3 seconds
+    pollForCompletion();
+    const interval = setInterval(pollForCompletion, POLL_INTERVAL_MS);
+    return () => clearInterval(interval);
+  }, [isReviewing, isExternalReview, projectId, pr.number, startedAt]);
+
   /**
    * Fallback mechanism: Load logs after review completes if not already loaded
    *
@@ -1067,6 +1123,7 @@ ${t('prReview.blockedStatusMessageFooter')}`;
         <ReviewStatusTree
           status={prStatus.status}
           isReviewing={isReviewing}
+          isExternalReview={isExternalReview}
           startedAt={startedAt}
           reviewResult={reviewResult}
           previousReviewResult={previousReviewResult}

apps/frontend/src/renderer/components/github-prs/components/ReviewStatusTree.tsx

@@ -21,6 +21,7 @@ export type ReviewStatus =
 export interface ReviewStatusTreeProps {
   status: ReviewStatus;
   isReviewing: boolean;
+  isExternalReview?: boolean;
   startedAt: string | null;
   reviewResult: PRReviewResult | null;
   previousReviewResult: PRReviewResult | null;
@@ -39,6 +40,7 @@ export interface ReviewStatusTreeProps {
 export function ReviewStatusTree({
   status,
   isReviewing,
+  isExternalReview = false,
   startedAt,
   reviewResult,
   previousReviewResult,
@@ -137,7 +139,9 @@ export function ReviewStatusTree({
     if (isReviewing) {
       steps.push({
         id: 'analysis',
-        label: t('prReview.analysisInProgress'),
+        label: isExternalReview
+          ? t('prReview.reviewStartedExternally')
+          : t('prReview.analysisInProgress'),
         status: 'current',
         date: null
       });
@@ -255,7 +259,7 @@ export function ReviewStatusTree({
 
   // Status label - explicitly handle all statuses
   const getStatusLabel = (): string => {
-    if (isReviewing) return t('prReview.aiReviewInProgress');
+    if (isReviewing) return isExternalReview ? t('prReview.externalReviewDetected') : t('prReview.aiReviewInProgress');
     switch (status) {
       case 'ready_to_merge':
         return t('prReview.readyToMerge');
@@ -279,7 +283,7 @@ export function ReviewStatusTree({
     <CollapsibleCard
       title={statusLabel}
       icon={<div className={statusDotColor} />}
-      headerAction={isReviewing ? (
+      headerAction={isReviewing && !isExternalReview ? (
         <Button
           variant="ghost"
           size="sm"

apps/frontend/src/renderer/components/github-prs/hooks/useGitHubPRs.ts

@@ -32,6 +32,7 @@ interface UseGitHubPRsResult {
   reviewProgress: PRReviewProgress | null;
   startedAt: string | null;
   isReviewing: boolean;
+  isExternalReview: boolean;
   previousReviewResult: PRReviewResult | null;
   isConnected: boolean;
   repoFullName: string | null;
@@ -113,6 +114,7 @@ export function useGitHubPRs(
   const reviewResult = selectedPRReviewState?.result ?? null;
   const reviewProgress = selectedPRReviewState?.progress ?? null;
   const isReviewing = selectedPRReviewState?.isReviewing ?? false;
+  const isExternalReview = selectedPRReviewState?.isExternalReview ?? false;
   const previousReviewResult = selectedPRReviewState?.previousResult ?? null;
   const startedAt = selectedPRReviewState?.startedAt ?? null;
 
@@ -727,6 +729,7 @@ export function useGitHubPRs(
     reviewProgress,
     startedAt,
     isReviewing,
+    isExternalReview,
     previousReviewResult,
     isConnected,
     repoFullName,

apps/frontend/src/renderer/components/roadmap/PhaseCard.tsx

@@ -1,4 +1,6 @@
-import { CheckCircle2, Circle, ExternalLink, Play, TrendingUp } from 'lucide-react';
+import { useState } from 'react';
+import { CheckCircle2, ChevronDown, ChevronUp, Circle, ExternalLink, Play, TrendingUp } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
 import { TaskOutcomeBadge } from './TaskOutcomeBadge';
 import { Badge } from '../ui/badge';
 import { Button } from '../ui/button';
@@ -7,6 +9,8 @@ import { Progress } from '../ui/progress';
 import { ROADMAP_PRIORITY_COLORS } from '../../../shared/constants';
 import type { PhaseCardProps } from './types';
 
+const INITIAL_VISIBLE_COUNT = 5;
+
 export function PhaseCard({
   phase,
   features,
@@ -15,8 +19,13 @@ export function PhaseCard({
   onConvertToSpec,
   onGoToTask,
 }: PhaseCardProps) {
+  const { t } = useTranslation('common');
+  const [isExpanded, setIsExpanded] = useState(false);
   const completedCount = features.filter((f) => f.status === 'done').length;
   const progress = features.length > 0 ? (completedCount / features.length) * 100 : 0;
+  const visibleFeatures = isExpanded ? features : features.slice(0, INITIAL_VISIBLE_COUNT);
+  const hiddenCount = features.length - INITIAL_VISIBLE_COUNT;
+  const hasMoreFeatures = hiddenCount > 0;
 
   return (
     <Card className="p-4">
@@ -87,13 +96,16 @@ export function PhaseCard({
       <div>
         <h4 className="text-sm font-medium mb-2">Features ({features.length})</h4>
         <div className="grid gap-2">
-          {features.slice(0, 5).map((feature) => (
+          {visibleFeatures.map((feature) => (
             <div
               key={feature.id}
-              className="flex items-center justify-between p-2 rounded-md bg-muted/50 hover:bg-muted cursor-pointer transition-colors"
-              onClick={() => onFeatureSelect(feature)}
+              className="flex items-center justify-between p-2 rounded-md bg-muted/50 hover:bg-muted transition-colors"
             >
-              <div className="flex items-center gap-2 flex-1 min-w-0">
+              <button
+                type="button"
+                className="flex items-center gap-2 flex-1 min-w-0 text-left cursor-pointer rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+                onClick={() => onFeatureSelect(feature)}
+              >
                 <Badge
                   variant="outline"
                   className={`text-xs ${ROADMAP_PRIORITY_COLORS[feature.priority]}`}
@@ -104,7 +116,7 @@ export function PhaseCard({
                 {feature.competitorInsightIds && feature.competitorInsightIds.length > 0 && (
                   <TrendingUp className="h-3 w-3 text-primary flex-shrink-0" />
                 )}
-              </div>
+              </button>
               {feature.taskOutcome ? (
                 <span className="flex-shrink-0">
                   <TaskOutcomeBadge outcome={feature.taskOutcome} size="lg" showLabel={false} />
@@ -140,10 +152,26 @@ export function PhaseCard({
               )}
             </div>
           ))}
-          {features.length > 5 && (
-            <div className="text-sm text-muted-foreground text-center py-1">
-              +{features.length - 5} more features
-            </div>
+          {hasMoreFeatures && (
+            <Button
+              type="button"
+              variant="ghost"
+              onClick={() => setIsExpanded((prev) => !prev)}
+              aria-expanded={isExpanded}
+              className="flex items-center justify-center gap-1 text-sm text-muted-foreground hover:text-foreground w-full"
+            >
+              {isExpanded ? (
+                <>
+                  <ChevronUp className="h-4 w-4" />
+                  {t('roadmap.showLessFeatures')}
+                </>
+              ) : (
+                <>
+                  <ChevronDown className="h-4 w-4" />
+                  {t('roadmap.showMoreFeatures', { count: hiddenCount })}
+                </>
+              )}
+            </Button>
           )}
         </div>
       </div>

apps/frontend/src/renderer/components/terminal/useXterm.ts

@@ -139,11 +139,18 @@ export function useXterm({ terminalId, onCommandEnter, onResize, onDimensionsRea
     };
 
     // Helper function to handle paste from clipboard
+    // Cap paste size to prevent GPU/memory pressure from extremely large clipboard contents.
+    const MAX_PASTE_BYTES = 1_048_576; // 1 MB
     const handlePasteFromClipboard = (): void => {
       navigator.clipboard.readText()
         .then((text) => {
           if (text) {
-            xterm.paste(text);
+            if (text.length > MAX_PASTE_BYTES) {
+              console.warn(`[useXterm] Paste truncated from ${text.length} to ${MAX_PASTE_BYTES} bytes`);
+              xterm.paste(text.slice(0, MAX_PASTE_BYTES));
+            } else {
+              xterm.paste(text);
+            }
           }
         })
         .catch((err) => {

apps/frontend/src/renderer/hooks/useIpc.ts

@@ -7,6 +7,9 @@ import { useAuthFailureStore } from '../stores/auth-failure-store';
 import { useProjectStore } from '../stores/project-store';
 import type { ImplementationPlan, TaskStatus, RoadmapGenerationStatus, Roadmap, ExecutionProgress, RateLimitInfo, SDKRateLimitInfo, AuthFailureInfo } from '../../shared/types';
 
+/** Maximum log entries to buffer in the batch queue between flushes (OOM prevention) */
+const MAX_BATCH_QUEUE_LOGS = 100;
+
 /**
  * Batched update queue for IPC events.
  * Collects updates within a 16ms window (one frame) and flushes them together.
@@ -124,6 +127,10 @@ function queueUpdate(taskId: string, update: BatchedUpdate): void {
   let mergedLogs = existing.logs;
   if (update.logs) {
     mergedLogs = [...(existing.logs || []), ...update.logs];
+    // Cap batch queue logs to prevent OOM when logs arrive faster than flush interval
+    if (mergedLogs.length > MAX_BATCH_QUEUE_LOGS) {
+      mergedLogs = mergedLogs.slice(-MAX_BATCH_QUEUE_LOGS);
+    }
   }
 
   batchQueue.set(taskId, {

apps/frontend/src/renderer/stores/__tests__/task-store-persistence.test.ts

@@ -34,20 +34,6 @@ describe('task-store-persistence', () => {
   let useTaskStore: typeof import('../task-store').useTaskStore;
   let loadTasks: typeof import('../task-store').loadTasks;
   let createTask: typeof import('../task-store').createTask;
-  // Helper to create test tasks with all required fields
-  const makeTask = (overrides: Partial<Task> = {}): Task => ({
-    id: 'task-1',
-    specId: '001-test-task',
-    projectId: 'test-project',
-    title: 'Test Task',
-    description: 'Test description',
-    status: 'backlog' as TaskStatus,
-    logs: [],
-    subtasks: [],
-    createdAt: new Date(),
-    updatedAt: new Date(),
-    ...overrides
-  });
 
 
   beforeEach(async () => {

apps/frontend/src/renderer/stores/github/pr-review-store.ts

@@ -35,6 +35,8 @@ interface PRReviewState {
   mergeableState: MergeableState | null;
   /** Timestamp of last status poll (ISO 8601 string) */
   lastPolled: string | null;
+  /** Whether this review was initiated externally (e.g., from PR list) rather than from detail view */
+  isExternalReview: boolean;
 }
 
 interface PRReviewStoreState {
@@ -59,6 +61,8 @@ interface PRReviewStoreState {
   }) => void;
   /** Clear PR status fields for a specific PR */
   clearPRStatus: (projectId: string, prNumber: number) => void;
+  /** Start an external review (from PR list) - sets isReviewing and isExternalReview */
+  setExternalReviewInProgress: (projectId: string, prNumber: number, inProgressSince?: string) => void;
 
   // Selectors
   getPRReviewState: (projectId: string, prNumber: number) => PRReviewState | null;
@@ -96,7 +100,8 @@ export const usePRReviewStore = create<PRReviewStoreState>((set, get) => ({
           checksStatus: existing?.checksStatus ?? null,
           reviewsStatus: existing?.reviewsStatus ?? null,
           mergeableState: existing?.mergeableState ?? null,
-          lastPolled: existing?.lastPolled ?? null
+          lastPolled: existing?.lastPolled ?? null,
+          isExternalReview: false
         }
       }
     };
@@ -130,7 +135,8 @@ export const usePRReviewStore = create<PRReviewStoreState>((set, get) => ({
           checksStatus: existing?.checksStatus ?? null,
           reviewsStatus: existing?.reviewsStatus ?? null,
           mergeableState: existing?.mergeableState ?? null,
-          lastPolled: existing?.lastPolled ?? null
+          lastPolled: existing?.lastPolled ?? null,
+          isExternalReview: false
         }
       }
     };
@@ -155,7 +161,8 @@ export const usePRReviewStore = create<PRReviewStoreState>((set, get) => ({
           checksStatus: existing?.checksStatus ?? null,
           reviewsStatus: existing?.reviewsStatus ?? null,
           mergeableState: existing?.mergeableState ?? null,
-          lastPolled: existing?.lastPolled ?? null
+          lastPolled: existing?.lastPolled ?? null,
+          isExternalReview: existing?.isExternalReview ?? false
         }
       }
     };
@@ -182,7 +189,8 @@ export const usePRReviewStore = create<PRReviewStoreState>((set, get) => ({
           checksStatus: existing?.checksStatus ?? null,
           reviewsStatus: existing?.reviewsStatus ?? null,
           mergeableState: existing?.mergeableState ?? null,
-          lastPolled: existing?.lastPolled ?? null
+          lastPolled: existing?.lastPolled ?? null,
+          isExternalReview: existing?.isExternalReview ?? false
         }
       }
     };
@@ -207,7 +215,8 @@ export const usePRReviewStore = create<PRReviewStoreState>((set, get) => ({
           checksStatus: existing?.checksStatus ?? null,
           reviewsStatus: existing?.reviewsStatus ?? null,
           mergeableState: existing?.mergeableState ?? null,
-          lastPolled: existing?.lastPolled ?? null
+          lastPolled: existing?.lastPolled ?? null,
+          isExternalReview: existing?.isExternalReview ?? false
         }
       }
     };
@@ -234,7 +243,8 @@ export const usePRReviewStore = create<PRReviewStoreState>((set, get) => ({
             checksStatus: null,
             reviewsStatus: null,
             mergeableState: null,
-            lastPolled: null
+            lastPolled: null,
+            isExternalReview: false
           }
         }
       };
@@ -282,7 +292,8 @@ export const usePRReviewStore = create<PRReviewStoreState>((set, get) => ({
             checksStatus: status.checksStatus,
             reviewsStatus: status.reviewsStatus,
             mergeableState: status.mergeableState,
-            lastPolled: status.lastPolled
+            lastPolled: status.lastPolled,
+            isExternalReview: false
           }
         }
       };
@@ -321,6 +332,32 @@ export const usePRReviewStore = create<PRReviewStoreState>((set, get) => ({
     };
   }),
 
+  setExternalReviewInProgress: (projectId: string, prNumber: number, inProgressSince?: string) => set((state) => {
+    const key = `${projectId}:${prNumber}`;
+    const existing = state.prReviews[key];
+    return {
+      prReviews: {
+        ...state.prReviews,
+        [key]: {
+          prNumber,
+          projectId,
+          isReviewing: true,
+          startedAt: inProgressSince || new Date().toISOString(),
+          progress: null,
+          result: existing?.result ?? null,
+          previousResult: existing?.previousResult ?? null,
+          error: null,
+          newCommitsCheck: existing?.newCommitsCheck ?? null,
+          checksStatus: existing?.checksStatus ?? null,
+          reviewsStatus: existing?.reviewsStatus ?? null,
+          mergeableState: existing?.mergeableState ?? null,
+          lastPolled: existing?.lastPolled ?? null,
+          isExternalReview: true
+        }
+      }
+    };
+  }),
+
   // Selectors
   getPRReviewState: (projectId: string, prNumber: number) => {
     const { prReviews } = get();
@@ -378,6 +415,15 @@ export function initializePRReviewListeners(): void {
   // Listen for PR review completion events
   const cleanupComplete = window.electronAPI.github.onPRReviewComplete(
     (projectId: string, result: PRReviewResult) => {
+      // When the backend detects an already-running review (e.g., started from another
+      // client or the PR list), it returns overallStatus === 'in_progress' instead of
+      // a real result. Transition to external-review-in-progress so the log polling
+      // activates and the UI shows the ongoing review.
+      if (result.overallStatus === 'in_progress') {
+        store.setExternalReviewInProgress(projectId, result.prNumber, result.inProgressSince);
+        return;
+      }
+
       store.setPRReviewResult(projectId, result);
       // Trigger all registered refresh callbacks when review completes
       refreshCallbacks.forEach(callback => {

apps/frontend/src/renderer/stores/task-store.ts

@@ -7,6 +7,9 @@ import { useProjectStore } from './project-store';
 /** Default max parallel tasks when no project setting is configured */
 export const DEFAULT_MAX_PARALLEL_TASKS = 3;
 
+/** Maximum log entries stored per task to prevent renderer OOM */
+export const MAX_LOG_ENTRIES = 5000;
+
 interface TaskState {
   tasks: Task[];
   selectedTaskId: string | null;
@@ -475,7 +478,7 @@ export const useTaskStore = create<TaskState>((set, get) => ({
       return {
         tasks: updateTaskAtIndex(state.tasks, index, (t) => ({
           ...t,
-          logs: [...(t.logs || []), log]
+          logs: [...(t.logs || []), log].slice(-MAX_LOG_ENTRIES)
         }))
       };
     }),
@@ -508,7 +511,7 @@ export const useTaskStore = create<TaskState>((set, get) => ({
       return {
         tasks: updateTaskAtIndex(state.tasks, index, (t) => ({
           ...t,
-          logs: [...(t.logs || []), ...logs]
+          logs: [...(t.logs || []), ...logs].slice(-MAX_LOG_ENTRIES)
         }))
       };
     });

apps/frontend/src/shared/i18n/locales/en/common.json

@@ -292,6 +292,8 @@
     "newIssue": "{{count}} new issue",
     "newIssue_plural": "{{count}} new issues",
     "reviewFailed": "Review Failed",
+    "externalReviewDetected": "External Review Detected",
+    "reviewStartedExternally": "This review was started from another session",
     "description": "Description",
     "noDescription": "No description provided.",
     "followupReviewDetails": "Follow-up Review Details",
@@ -597,7 +599,10 @@
   "roadmap": {
     "taskCompleted": "Completed",
     "taskDeleted": "Deleted",
-    "taskArchived": "Archived"
+    "taskArchived": "Archived",
+    "showMoreFeatures": "Show {{count}} more feature",
+    "showMoreFeatures_plural": "Show {{count}} more features",
+    "showLessFeatures": "Show less"
   },
   "roadmapGeneration": {
     "progress": "Progress",

apps/frontend/src/shared/i18n/locales/en/navigation.json

@@ -23,7 +23,8 @@
     "help": "Help & Feedback",
     "newTask": "New Task",
     "collapseSidebar": "Collapse Sidebar",
-    "expandSidebar": "Expand Sidebar"
+    "expandSidebar": "Expand Sidebar",
+    "sponsor": "Sponsor Us"
   },
   "tooltips": {
     "settings": "Application Settings",

apps/frontend/src/shared/i18n/locales/fr/common.json

@@ -292,6 +292,8 @@
     "newIssue": "{{count}} nouveau problème",
     "newIssue_plural": "{{count}} nouveaux problèmes",
     "reviewFailed": "Révision échouée",
+    "externalReviewDetected": "Révision externe détectée",
+    "reviewStartedExternally": "Cette révision a été lancée depuis une autre session",
     "description": "Description",
     "noDescription": "Aucune description fournie.",
     "followupReviewDetails": "Détails de la révision de suivi",
@@ -597,7 +599,10 @@
   "roadmap": {
     "taskCompleted": "Terminé",
     "taskDeleted": "Supprimé",
-    "taskArchived": "Archivé"
+    "taskArchived": "Archivé",
+    "showMoreFeatures": "Afficher {{count}} fonctionnalité supplémentaire",
+    "showMoreFeatures_plural": "Afficher {{count}} fonctionnalités supplémentaires",
+    "showLessFeatures": "Afficher moins"
   },
   "roadmapGeneration": {
     "progress": "Progression",

apps/frontend/src/shared/i18n/locales/fr/navigation.json

@@ -23,7 +23,8 @@
     "help": "Aide & Feedback",
     "newTask": "Nouvelle tâche",
     "collapseSidebar": "Réduire la barre latérale",
-    "expandSidebar": "Développer la barre latérale"
+    "expandSidebar": "Développer la barre latérale",
+    "sponsor": "Nous sponsoriser"
   },
   "tooltips": {
     "settings": "Paramètres de l'application",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-claude",
-  "version": "2.7.6-beta.4",
+  "version": "2.7.6-beta.5",
   "description": "Autonomous multi-agent coding framework powered by Claude AI",
   "license": "AGPL-3.0",
   "author": "Auto Claude Team",
@@ -20,6 +20,7 @@
     "lint": "cd apps/frontend && npm run lint",
     "test": "cd apps/frontend && npm test",
     "test:backend": "node scripts/test-backend.js",
+    "test:coverage": "node scripts/test-backend.js --cov --cov-report=term-missing --cov-report=html",
     "package": "cd apps/frontend && npm run package",
     "package:mac": "cd apps/frontend && npm run package:mac",
     "package:win": "cd apps/frontend && npm run package:win",

scripts/test-backend.js

@@ -4,7 +4,7 @@
  * Runs pytest using the correct virtual environment path for Windows/Mac/Linux
  */
 
-const { execSync } = require('child_process');
+const { execFileSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
@@ -39,15 +39,30 @@ if (!fs.existsSync(pytestPath)) {
 }
 
 // Get any additional args passed to the script
+// Process args to properly handle -m flag with spaces
 const args = process.argv.slice(2);
-const testArgs = args.length > 0 ? args.join(' ') : '-v';
+const testArgs = [];
 
-// Run pytest
-const cmd = `"${pytestPath}" "${testsDir}" ${testArgs}`;
-console.log(`> ${cmd}\n`);
+if (args.length > 0) {
+  // Reconstruct args, joining -m with its value if separated
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '-m' && i + 1 < args.length) {
+      // Pass -m and its value as separate args (no shell quoting needed with execFileSync)
+      testArgs.push('-m', args[i + 1]);
+      i++; // Skip next arg since we consumed it
+    } else {
+      testArgs.push(args[i]);
+    }
+  }
+} else {
+  testArgs.push('-v');
+}
+
+// Run pytest using execFileSync to avoid shell interpretation
+console.log(`> ${pytestPath} "${testsDir}" ${testArgs.join(' ')}\n`);
 
 try {
-  execSync(cmd, { stdio: 'inherit', cwd: rootDir });
+  execFileSync(pytestPath, [testsDir, ...testArgs], { stdio: 'inherit', cwd: rootDir });
 } catch (error) {
   process.exit(error.status || 1);
 }

tests/conftest.py

@@ -42,6 +42,12 @@ if 'claude_code_sdk' not in sys.modules:
     sys.modules['claude_code_sdk'] = _create_sdk_mock()
     sys.modules['claude_code_sdk.types'] = MagicMock()
 
+# Pre-mock dotenv to prevent sys.exit() in cli.utils.import_dotenv
+# This is needed for CLI tests since cli.utils calls import_dotenv at module level
+if 'dotenv' not in sys.modules:
+    sys.modules['dotenv'] = MagicMock()
+    sys.modules['dotenv'].load_dotenv = MagicMock()
+
 # Add apps/backend directory to path for imports
 sys.path.insert(0, str(Path(__file__).parent.parent / "apps" / "backend"))
 
@@ -57,6 +63,7 @@ _POTENTIALLY_MOCKED_MODULES = [
     'claude_code_sdk.types',
     'claude_agent_sdk',
     'claude_agent_sdk.types',
+    'dotenv',
     'ui',
     'progress',
     'task_logger',
@@ -106,19 +113,23 @@ def pytest_runtest_setup(item):
 
     module_name = item.module.__name__
 
+    # Common mock sets - defined once to reduce duplication and maintenance burden
+    QA_REPORT_MOCKS = {'claude_agent_sdk', 'ui', 'progress', 'task_logger', 'linear_updater', 'client'}
+    SDK_MOCKS = {'claude_code_sdk', 'claude_code_sdk.types', 'claude_agent_sdk', 'claude_agent_sdk.types'}
+
     # Map of which test modules mock which specific modules
     # Each test module should only preserve the mocks it installed
     module_mocks = {
-        'test_qa_criteria': {'claude_agent_sdk', 'ui', 'progress', 'task_logger', 'linear_updater', 'client'},
-        'test_qa_report': {'claude_agent_sdk', 'ui', 'progress', 'task_logger', 'linear_updater', 'client'},
-        'test_qa_report_iteration': {'claude_agent_sdk', 'ui', 'progress', 'task_logger', 'linear_updater', 'client'},
-        'test_qa_report_recurring': {'claude_agent_sdk', 'ui', 'progress', 'task_logger', 'linear_updater', 'client'},
-        'test_qa_report_project_detection': {'claude_agent_sdk', 'ui', 'progress', 'task_logger', 'linear_updater', 'client'},
-        'test_qa_report_manual_plan': {'claude_agent_sdk', 'ui', 'progress', 'task_logger', 'linear_updater', 'client'},
-        'test_qa_report_config': {'claude_agent_sdk', 'ui', 'progress', 'task_logger', 'linear_updater', 'client'},
-        'test_qa_loop': {'claude_code_sdk', 'claude_code_sdk.types', 'claude_agent_sdk', 'claude_agent_sdk.types'},
+        'test_qa_criteria': QA_REPORT_MOCKS,
+        'test_qa_report': QA_REPORT_MOCKS,
+        'test_qa_report_iteration': QA_REPORT_MOCKS,
+        'test_qa_report_recurring': QA_REPORT_MOCKS,
+        'test_qa_report_project_detection': QA_REPORT_MOCKS,
+        'test_qa_report_manual_plan': QA_REPORT_MOCKS,
+        'test_qa_report_config': QA_REPORT_MOCKS,
+        'test_qa_loop': SDK_MOCKS,
         'test_spec_pipeline': {'claude_code_sdk', 'claude_code_sdk.types', 'init', 'client', 'review', 'task_logger', 'ui', 'validate_spec'},
-        'test_spec_complexity': {'claude_code_sdk', 'claude_code_sdk.types', 'claude_agent_sdk', 'claude_agent_sdk.types'},
+        'test_spec_complexity': SDK_MOCKS,
         'test_spec_phases': {'claude_code_sdk', 'claude_code_sdk.types', 'claude_agent_sdk', 'graphiti_providers', 'validate_spec', 'client'},
         'test_qa_fixer': {'claude_agent_sdk', 'ui', 'progress', 'task_logger', 'linear_updater', 'client', 'agents.memory_manager', 'agents.base', 'core.error_utils', 'security.tool_input_validator', 'debug'},
         'test_qa_reviewer': {'claude_agent_sdk', 'ui', 'progress', 'task_logger', 'linear_updater', 'client', 'agents.memory_manager', 'agents.base', 'core.error_utils', 'security.tool_input_validator', 'debug', 'prompts_pkg', 'prompts_pkg.project_context'},
@@ -154,16 +165,19 @@ def pytest_runtest_setup(item):
             if qa_module in sys.modules:
                 try:
                     importlib.reload(sys.modules[qa_module])
-                except Exception:
-                    pass  # Some modules may fail to reload due to circular imports
+                except Exception as e:
+                    # Log reload failures - circular imports are expected but other errors should be visible
+                    import warnings
+                    warnings.warn(f'Failed to reload {qa_module}: {e}')
         # Reload review module chain
         for review_module in ['review.state', 'review.formatters', 'review']:
             if review_module in sys.modules:
                 try:
                     importlib.reload(sys.modules[review_module])
-                except Exception:
-                    # Module reload may fail if dependencies aren't loaded; safe to ignore
-                    pass
+                except Exception as e:
+                    # Log reload failures - some modules may fail if dependencies aren't loaded
+                    import warnings
+                    warnings.warn(f'Failed to reload {review_module}: {e}')
 
 
 # =============================================================================
@@ -257,6 +271,132 @@ def spec_dir(temp_dir: Path) -> Path:
     return spec_path
 
 
+# =============================================================================
+# WORKSPACE COMMAND TEST FIXTURES
+# =============================================================================
+
+# Constants for workspace tests
+TEST_SPEC_NAME = "001-test-spec"
+TEST_SPEC_BRANCH = f"auto-claude/{TEST_SPEC_NAME}"
+
+
+@pytest.fixture
+def mock_project_dir(temp_git_repo: Path) -> Path:
+    """Create a mock project directory with git repo."""
+    return temp_git_repo
+
+
+@pytest.fixture
+def mock_worktree_path(temp_git_repo: Path) -> Path:
+    """Create a mock worktree path."""
+    worktree_path = temp_git_repo / ".worktrees" / TEST_SPEC_NAME
+    worktree_path.mkdir(parents=True, exist_ok=True)
+    return worktree_path
+
+
+@pytest.fixture
+def workspace_spec_dir(temp_git_repo: Path) -> Path:
+    """Create a spec directory inside .auto-claude/specs/ for workspace tests."""
+    spec_dir = temp_git_repo / ".auto-claude" / "specs" / TEST_SPEC_NAME
+    spec_dir.mkdir(parents=True, exist_ok=True)
+    return spec_dir
+
+
+@pytest.fixture
+def with_spec_branch(temp_git_repo: Path) -> Generator[Path, None, None]:
+    """Create a temp git repo with a spec branch.
+
+    Note: temp_git_repo already provides an initialized repo with initial commit,
+    so we only need to create the spec branch and add changes.
+    """
+    # Create spec branch
+    subprocess.run(
+        ["git", "checkout", "-b", TEST_SPEC_BRANCH],
+        cwd=temp_git_repo,
+        capture_output=True,
+        check=True,
+    )
+
+    # Add a change on spec branch
+    (temp_git_repo / "test.txt").write_text("test content")
+    subprocess.run(
+        ["git", "add", "test.txt"],
+        cwd=temp_git_repo,
+        capture_output=True,
+        check=True,
+    )
+    subprocess.run(
+        ["git", "commit", "-m", "Test commit"],
+        cwd=temp_git_repo,
+        capture_output=True,
+        check=True,
+    )
+
+    # Go back to main
+    subprocess.run(
+        ["git", "checkout", "main"],
+        cwd=temp_git_repo,
+        capture_output=True,
+        check=True,
+    )
+
+    yield temp_git_repo
+
+
+@pytest.fixture
+def with_conflicting_branches(temp_git_repo: Path) -> Generator[Path, None, None]:
+    """Create temp git repo with conflicting branches for merge testing.
+
+    Note: temp_git_repo already provides an initialized repo with initial commit,
+    so we only need to create branches with conflicting changes.
+    """
+    # Create spec branch
+    subprocess.run(
+        ["git", "checkout", "-b", TEST_SPEC_BRANCH],
+        cwd=temp_git_repo,
+        capture_output=True,
+        check=True,
+    )
+
+    # Add a file on spec branch
+    (temp_git_repo / "conflict.txt").write_text("spec branch content")
+    subprocess.run(
+        ["git", "add", "conflict.txt"],
+        cwd=temp_git_repo,
+        capture_output=True,
+        check=True,
+    )
+    subprocess.run(
+        ["git", "commit", "-m", "Spec change"],
+        cwd=temp_git_repo,
+        capture_output=True,
+        check=True,
+    )
+
+    # Go back to main and make conflicting change
+    subprocess.run(
+        ["git", "checkout", "main"],
+        cwd=temp_git_repo,
+        capture_output=True,
+        check=True,
+    )
+    (temp_git_repo / "conflict.txt").write_text("main branch content")
+    subprocess.run(
+        ["git", "add", "conflict.txt"],
+        cwd=temp_git_repo,
+        capture_output=True,
+        check=True,
+    )
+    subprocess.run(
+        ["git", "commit", "-m", "Main change"],
+        cwd=temp_git_repo,
+        capture_output=True,
+        check=True,
+    )
+
+    yield temp_git_repo
+
+
 # =============================================================================
 # REVIEW FIXTURES - Import from review_fixtures.py
 # =============================================================================
@@ -639,16 +779,15 @@ def mock_run_agent_fn():
             phase_name: str = None,
         ) -> tuple[bool, str]:
             nonlocal call_count
+            call_count += 1
             if side_effect is not None:
-                if call_count < len(side_effect):
-                    result = side_effect[call_count]
-                    call_count += 1
+                if call_count <= len(side_effect):
+                    result = side_effect[call_count - 1]
                     return result
                 # Fallback to last result if more calls than expected
                 return side_effect[-1]
             return (success, output)
 
-        _mock_agent.call_count = 0
         return _mock_agent
 
     return _create_mock
@@ -706,6 +845,202 @@ def mock_ui_module():
     return ui
 
 
+@pytest.fixture
+def mock_ui_icons():
+    """
+    Mock UI Icons class for CLI input handler tests.
+
+    Provides the complete Icons class with Unicode and ASCII fallbacks.
+    Mirrors the structure in apps/backend/ui/icons.py.
+
+    Usage:
+        def test_something(mock_ui_icons):
+            Icons = mock_ui_icons
+            assert Icons.SUCCESS == ("✓", "[OK]")
+    """
+    class MockIcons:
+        """Mock Icons class - complete with all icons used by the codebase."""
+        # Status icons
+        SUCCESS = ("✓", "[OK]")
+        ERROR = ("✗", "[X]")
+        WARNING = ("⚠", "[!]")
+        INFO = ("ℹ", "[i]")
+        PENDING = ("○", "[ ]")
+        IN_PROGRESS = ("◐", "[.]")
+        COMPLETE = ("●", "[*]")
+        BLOCKED = ("⊘", "[B]")
+
+        # Action icons
+        PLAY = ("▶", ">")
+        PAUSE = ("⏸", "||")
+        STOP = ("⏹", "[]")
+        SKIP = ("⏭", ">>")
+
+        # Navigation
+        ARROW_RIGHT = ("→", "->")
+        ARROW_DOWN = ("↓", "v")
+        ARROW_UP = ("↑", "^")
+        POINTER = ("❯", ">")
+        BULLET = ("•", "*")
+
+        # Objects
+        FOLDER = ("📁", "[D]")
+        FILE = ("📄", "[F]")
+        GEAR = ("⚙", "[*]")
+        SEARCH = ("🔍", "[?]")
+        BRANCH = ("🌿", "[BR]")
+        COMMIT = ("◉", "(@)")
+        LIGHTNING = ("⚡", "!")
+        LINK = ("🔗", "[L]")
+
+        # Progress
+        SUBTASK = ("▣", "#")
+        PHASE = ("◆", "*")
+        WORKER = ("⚡", "W")
+        SESSION = ("▸", ">")
+
+        # Menu
+        EDIT = ("✏️", "[E]")
+        CLIPBOARD = ("📋", "[C]")
+        DOCUMENT = ("📄", "[D]")
+        DOOR = ("🚪", "[Q]")
+        SHIELD = ("🛡️", "[S]")
+
+        # Box drawing
+        BOX_TL = ("╔", "+")
+        BOX_TR = ("╗", "+")
+        BOX_BL = ("╚", "+")
+        BOX_BR = ("╝", "+")
+        BOX_H = ("═", "-")
+        BOX_V = ("║", "|")
+        BOX_ML = ("╠", "+")
+        BOX_MR = ("╣", "+")
+        BOX_TL_LIGHT = ("┌", "+")
+        BOX_TR_LIGHT = ("┐", "+")
+        BOX_BL_LIGHT = ("└", "+")
+        BOX_BR_LIGHT = ("┘", "+")
+        BOX_H_LIGHT = ("─", "-")
+        BOX_V_LIGHT = ("│", "|")
+        BOX_ML_LIGHT = ("├", "+")
+        BOX_MR_LIGHT = ("┤", "+")
+
+        # Progress bar
+        BAR_FULL = ("█", "=")
+        BAR_EMPTY = ("░", "-")
+        BAR_HALF = ("▌", "=")
+
+    return MockIcons
+
+
+@pytest.fixture
+def mock_ui_menu_option():
+    """
+    Mock UI MenuOption class for CLI tests.
+
+    Provides a simple MenuOption class for menu testing.
+
+    Usage:
+        def test_something(mock_ui_menu_option):
+            option = mock_ui_menu_option()("key", "Label")
+            assert option.key == "key"
+    """
+    class MockMenuOption:
+        """Mock MenuOption class."""
+        def __init__(self, key, label, icon=None, description=""):
+            self.key = key
+            self.label = label
+            self.icon = icon or ("", "")
+            self.description = description
+
+    return MockMenuOption
+
+
+@pytest.fixture
+def mock_ui_module_full(mock_ui_icons, mock_ui_menu_option):
+    """
+    Comprehensive mock UI module with all functions and classes.
+
+    Provides a complete mock of the ui module for CLI tests.
+    Includes Icons, MenuOption, and all UI functions.
+
+    Usage:
+        def test_something(mock_ui_module_full):
+            ui = mock_ui_module_full
+            assert ui.Icons.SUCCESS == ("✓", "[OK]")
+            assert ui.icon(ui.Icons.SUCCESS) == "✓"
+    """
+    from unittest.mock import MagicMock
+
+    Icons = mock_ui_icons
+    MenuOption = mock_ui_menu_option
+
+    def mock_icon(icon_tuple):
+        """Mock icon function."""
+        return icon_tuple[0] if icon_tuple else ""
+
+    def mock_bold(text):
+        """Mock bold function."""
+        return f"**{text}**"
+
+    def mock_muted(text):
+        """Mock muted function."""
+        return f"[{text}]"
+
+    def mock_box(content, width=70, style="heavy"):
+        """Mock box function."""
+        lines = ["┌" + "─" * (width - 2) + "┐"]
+        for line in content:
+            lines.append(f"│ {line} │")
+        lines.append("└" + "─" * (width - 2) + "┘")
+        return "\n".join(lines)
+
+    def mock_print_status(message, status="info"):
+        """Mock print_status function."""
+        print(f"[{status.upper()}] {message}")
+
+    def mock_select_menu(title, options, subtitle="", allow_quit=True):
+        """Mock select_menu function."""
+        return options[0].key if options else None
+
+    def mock_error(text):
+        """Mock error function."""
+        return f"ERROR: {text}"
+
+    def mock_success(text):
+        """Mock success function."""
+        return f"SUCCESS: {text}"
+
+    def mock_warning(text):
+        """Mock warning function."""
+        return f"WARNING: {text}"
+
+    def mock_info(text):
+        """Mock info function."""
+        return f"INFO: {text}"
+
+    def mock_highlight(text):
+        """Mock highlight function."""
+        return text
+
+    # Create mock ui module
+    mock_ui = MagicMock()
+    mock_ui.Icons = Icons
+    mock_ui.MenuOption = MenuOption
+    mock_ui.icon = mock_icon
+    mock_ui.bold = mock_bold
+    mock_ui.muted = mock_muted
+    mock_ui.box = mock_box
+    mock_ui.print_status = mock_print_status
+    mock_ui.select_menu = mock_select_menu
+    mock_ui.error = mock_error
+    mock_ui.success = mock_success
+    mock_ui.warning = mock_warning
+    mock_ui.info = mock_info
+    mock_ui.highlight = mock_highlight
+
+    return mock_ui
+
+
 @pytest.fixture
 def mock_spec_validator():
     """
@@ -1240,6 +1575,23 @@ def temp_project_dir(tmp_path):
     return project_dir
 
 
+@pytest.fixture
+def successful_agent_fn():
+    """
+    Reusable async agent function that returns success.
+
+    Replaces the duplicated async def agent_fn(*args, **kwargs): return (True, 'Success')
+    pattern that was copy-pasted 28 times across test_cli_build_commands.py.
+
+    Usage:
+        def test_something(mock_run_agent, successful_agent_fn):
+            mock_run_agent.side_effect = successful_agent_fn
+    """
+    async def _fn(*args, **kwargs):
+        return (True, 'Success')
+    return _fn
+
+
 @pytest.fixture
 def worktree_manager(temp_project_dir):
     """Create a WorktreeManager instance."""

tests/test_ci_discovery.py

@@ -629,7 +629,7 @@ class TestEdgeCases:
 
     def test_nonexistent_directory(self, discovery):
         """Test handling of non-existent directory."""
-        fake_dir = Path("/nonexistent/path")
+        fake_dir = Path("/tmp/test-nonexistent-ci-discovery-123456")
 
         # Should not raise - mock exists to avoid permission error
         with patch.object(Path, 'exists', return_value=False):

tests/test_cli_batch_commands.py

@@ -0,0 +1,741 @@
+#!/usr/bin/env python3
+"""
+Tests for CLI Batch Commands
+=============================
+
+Tests for batch_commands.py module functionality including:
+- handle_batch_create_command() - Create tasks from batch file
+- handle_batch_status_command() - Show status of all specs
+- handle_batch_cleanup_command() - Clean up completed specs
+"""
+
+import json
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from cli.batch_commands import (
+    handle_batch_cleanup_command,
+    handle_batch_create_command,
+    handle_batch_status_command,
+)
+
+
+# =============================================================================
+# FIXTURES
+# =============================================================================
+
+@pytest.fixture
+def sample_batch_file(temp_dir: Path) -> Path:
+    """Create a sample batch JSON file."""
+    batch_data = {
+        "tasks": [
+            {
+                "title": "Add user authentication",
+                "description": "Implement OAuth2 login with Google provider",
+                "workflow_type": "feature",
+                "services": ["backend", "frontend"],
+                "priority": 8,
+                "complexity": "standard",
+                "estimated_hours": 6.0,
+                "estimated_days": 0.75,
+            },
+            {
+                "title": "Add payment processing",
+                "description": "Integrate Stripe for payments",
+                "workflow_type": "feature",
+                "services": ["backend", "worker"],
+                "priority": 7,
+                "complexity": "complex",
+                "estimated_hours": 12.0,
+                "estimated_days": 1.5,
+            },
+            {
+                "title": "Fix navigation bug",
+                "description": "Mobile menu not closing properly",
+                "workflow_type": "bugfix",
+                "services": ["frontend"],
+                "priority": 9,
+                "complexity": "simple",
+            },
+        ]
+    }
+
+    batch_file = temp_dir / "batch.json"
+    batch_file.write_text(json.dumps(batch_data, indent=2))
+    return batch_file
+
+
+@pytest.fixture
+def empty_batch_file(temp_dir: Path) -> Path:
+    """Create an empty batch JSON file."""
+    batch_data = {"tasks": []}
+    batch_file = temp_dir / "empty_batch.json"
+    batch_file.write_text(json.dumps(batch_data))
+    return batch_file
+
+
+@pytest.fixture
+def invalid_json_file(temp_dir: Path) -> Path:
+    """Create a file with invalid JSON."""
+    batch_file = temp_dir / "invalid.json"
+    batch_file.write_text("{ invalid json }")
+    return batch_file
+
+
+@pytest.fixture
+def project_with_specs(temp_git_repo: Path) -> Path:
+    """Create a project with existing specs."""
+    specs_dir = temp_git_repo / ".auto-claude" / "specs"
+    specs_dir.mkdir(parents=True)
+
+    # Spec 001 - with spec.md
+    spec_001 = specs_dir / "001-existing-feature"
+    spec_001.mkdir()
+    (spec_001 / "spec.md").write_text("# Existing Feature\n")
+    (spec_001 / "requirements.json").write_text('{"task_description": "Existing"}')
+
+    # Spec 002 - with implementation plan
+    spec_002 = specs_dir / "002-in-progress"
+    spec_002.mkdir()
+    (spec_002 / "spec.md").write_text("# In Progress\n")
+    (spec_002 / "implementation_plan.json").write_text('{"phases": []}')
+
+    # Spec 003 - complete with QA approval in implementation_plan.json
+    spec_003 = specs_dir / "003-completed"
+    spec_003.mkdir()
+    (spec_003 / "spec.md").write_text("# Completed\n")
+    (spec_003 / "implementation_plan.json").write_text(
+        '{"phases": [], "qa_signoff": {"status": "approved"}}'
+    )
+    (spec_003 / "qa_report.md").write_text("# QA Approved\n")
+
+    return temp_git_repo
+
+
+@pytest.fixture
+def project_with_completed_specs_and_worktrees(temp_git_repo: Path) -> Path:
+    """Create a project with completed specs and worktrees."""
+    specs_dir = temp_git_repo / ".auto-claude" / "specs"
+    specs_dir.mkdir(parents=True)
+
+    worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+    worktrees_dir.mkdir(parents=True)
+
+    # Completed spec 001 with worktree (QA approved)
+    spec_001 = specs_dir / "001-completed-with-wt"
+    spec_001.mkdir()
+    (spec_001 / "qa_report.md").write_text("# QA Approved\n")
+    (spec_001 / "implementation_plan.json").write_text(
+        '{"qa_signoff": {"status": "approved"}}'
+    )
+
+    wt_001 = worktrees_dir / "001-completed-with-wt"
+    wt_001.mkdir(parents=True)
+
+    # Completed spec 002 without worktree (QA approved)
+    spec_002 = specs_dir / "002-completed-no-wt"
+    spec_002.mkdir()
+    (spec_002 / "qa_report.md").write_text("# QA Approved\n")
+    (spec_002 / "implementation_plan.json").write_text(
+        '{"qa_signoff": {"status": "approved"}}'
+    )
+
+    # Incomplete spec 003
+    spec_003 = specs_dir / "003-incomplete"
+    spec_003.mkdir()
+    (spec_003 / "spec.md").write_text("# In Progress\n")
+
+    return temp_git_repo
+
+
+# =============================================================================
+# HANDLE_BATCH_CREATE_COMMAND TESTS
+# =============================================================================
+
+class TestHandleBatchCreateCommand:
+    """Tests for handle_batch_create_command() function."""
+
+    def test_creates_specs_from_batch_file(
+        self, sample_batch_file: Path, temp_git_repo: Path
+    ) -> None:
+        """Creates spec directories from batch file."""
+        result = handle_batch_create_command(str(sample_batch_file), str(temp_git_repo))
+
+        assert result is True
+
+        specs_dir = temp_git_repo / ".auto-claude" / "specs"
+        assert specs_dir.exists()
+
+        # Should create 3 specs
+        spec_dirs = sorted([d for d in specs_dir.iterdir() if d.is_dir()])
+        assert len(spec_dirs) == 3
+
+        # Check spec numbering continues from 001
+        assert spec_dirs[0].name == "001-add-user-authentication"
+        assert spec_dirs[1].name == "002-add-payment-processing"
+        assert spec_dirs[2].name == "003-fix-navigation-bug"
+
+    def test_creates_requirements_json(
+        self, sample_batch_file: Path, temp_git_repo: Path
+    ) -> None:
+        """Creates requirements.json with correct content."""
+        handle_batch_create_command(str(sample_batch_file), str(temp_git_repo))
+
+        specs_dir = temp_git_repo / ".auto-claude" / "specs"
+        spec_001 = specs_dir / "001-add-user-authentication"
+        req_file = spec_001 / "requirements.json"
+
+        assert req_file.exists()
+
+        with open(req_file) as f:
+            req = json.load(f)
+
+        assert req["task_description"] == "Implement OAuth2 login with Google provider"
+        assert req["workflow_type"] == "feature"
+        assert req["services_involved"] == ["backend", "frontend"]
+        assert req["priority"] == 8
+        assert req["complexity_inferred"] == "standard"
+        assert req["estimate"]["estimated_hours"] == 6.0
+        assert req["estimate"]["estimated_days"] == 0.75
+
+    def test_continues_numbering_from_existing_specs(
+        self, project_with_specs: Path, sample_batch_file: Path
+    ) -> None:
+        """Continues spec numbering from existing specs."""
+        handle_batch_create_command(str(sample_batch_file), str(project_with_specs))
+
+        specs_dir = project_with_specs / ".auto-claude" / "specs"
+        spec_dirs = sorted([d for d in specs_dir.iterdir() if d.is_dir()])
+
+        # Should have existing 3 specs + 3 new ones
+        assert len(spec_dirs) == 6
+
+        # New specs should start at 004
+        assert spec_dirs[3].name == "004-add-user-authentication"
+        assert spec_dirs[4].name == "005-add-payment-processing"
+        assert spec_dirs[5].name == "006-fix-navigation-bug"
+
+    def test_returns_false_for_missing_file(self, temp_git_repo: Path) -> None:
+        """Returns False when batch file doesn't exist."""
+        result = handle_batch_create_command(
+            "nonexistent.json", str(temp_git_repo)
+        )
+
+        assert result is False
+
+    def test_returns_false_for_invalid_json(
+        self, invalid_json_file: Path, temp_git_repo: Path
+    ) -> None:
+        """Returns False for invalid JSON."""
+        result = handle_batch_create_command(
+            str(invalid_json_file), str(temp_git_repo)
+        )
+
+        assert result is False
+
+    def test_returns_false_for_empty_tasks(
+        self, empty_batch_file: Path, temp_git_repo: Path
+    ) -> None:
+        """Returns False when batch file has no tasks."""
+        result = handle_batch_create_command(
+            str(empty_batch_file), str(temp_git_repo)
+        )
+
+        assert result is False
+
+    def test_sanitizes_task_title_for_folder_name(
+        self, temp_dir: Path, temp_git_repo: Path
+    ) -> None:
+        """Sanitizes task title when creating folder name."""
+        batch_data = {
+            "tasks": [
+                {
+                    "title": "Task With VERY Long Name That Should Be Truncated Because It Exceeds Fifty Characters",
+                    "description": "Test",
+                }
+            ]
+        }
+        batch_file = temp_dir / "batch.json"
+        batch_file.write_text(json.dumps(batch_data))
+
+        handle_batch_create_command(str(batch_file), str(temp_git_repo))
+
+        specs_dir = temp_git_repo / ".auto-claude" / "specs"
+        spec_dirs = list(specs_dir.iterdir())
+
+        assert len(spec_dirs) == 1
+        # Name should be truncated to 50 chars
+        assert len(spec_dirs[0].name) <= 59  # "001-" + 50 chars
+        assert spec_dirs[0].name.startswith("001-")
+
+    def test_uses_defaults_for_missing_fields(
+        self, temp_dir: Path, temp_git_repo: Path
+    ) -> None:
+        """Uses default values for missing optional fields."""
+        batch_data = {
+            "tasks": [
+                {
+                    "title": "Minimal Task",
+                }
+            ]
+        }
+        batch_file = temp_dir / "batch.json"
+        batch_file.write_text(json.dumps(batch_data))
+
+        handle_batch_create_command(str(batch_file), str(temp_git_repo))
+
+        specs_dir = temp_git_repo / ".auto-claude" / "specs"
+        req_file = specs_dir / "001-minimal-task" / "requirements.json"
+
+        with open(req_file) as f:
+            req = json.load(f)
+
+        assert req["task_description"] == "Minimal Task"
+        assert req["workflow_type"] == "feature"
+        assert req["services_involved"] == ["frontend"]
+        assert req["priority"] == 5
+        assert req["complexity_inferred"] == "standard"
+        assert req["estimate"]["estimated_hours"] == 4.0
+        assert req["estimate"]["estimated_days"] == 0.5
+
+
+# =============================================================================
+# HANDLE_BATCH_STATUS_COMMAND TESTS
+# =============================================================================
+
+class TestHandleBatchStatusCommand:
+    """Tests for handle_batch_status_command() function."""
+
+    def test_shows_status_for_all_specs(
+        self, capsys, project_with_specs: Path
+    ) -> None:
+        """Shows status for all specs in project."""
+        result = handle_batch_status_command(str(project_with_specs))
+
+        assert result is True
+
+        captured = capsys.readouterr()
+        assert "3 spec" in captured.out
+        assert "001-existing-feature" in captured.out
+        assert "002-in-progress" in captured.out
+        assert "003-completed" in captured.out
+
+    def test_shows_correct_status_icons(
+        self, capsys, project_with_specs: Path
+    ) -> None:
+        """Shows appropriate status icons for each spec."""
+        handle_batch_status_command(str(project_with_specs))
+
+        captured = capsys.readouterr()
+        # Status icons for different states:
+        # 001: spec.md only → spec_created (📋)
+        # 002: spec.md + implementation_plan.json → building (⚙️)
+        # 003: qa_report.md → qa_approved (✅)
+        assert "📋" in captured.out
+        assert "⚙️" in captured.out
+        assert "✅" in captured.out
+
+    def test_returns_true_for_no_specs_directory(
+        self, capsys, temp_git_repo: Path
+    ) -> None:
+        """Returns True when no specs directory exists."""
+        result = handle_batch_status_command(str(temp_git_repo))
+
+        assert result is True
+
+        captured = capsys.readouterr()
+        assert "No specs found" in captured.out
+
+    def test_returns_true_for_empty_specs_directory(
+        self, capsys, temp_git_repo: Path
+    ) -> None:
+        """Returns True when specs directory is empty."""
+        specs_dir = temp_git_repo / ".auto-claude" / "specs"
+        specs_dir.mkdir(parents=True)
+
+        result = handle_batch_status_command(str(temp_git_repo))
+
+        assert result is True
+
+        captured = capsys.readouterr()
+        assert "No specs found" in captured.out
+
+    def test_shows_task_description(
+        self, capsys, project_with_specs: Path
+    ) -> None:
+        """Shows task description from requirements.json."""
+        handle_batch_status_command(str(project_with_specs))
+
+        captured = capsys.readouterr()
+        assert "Existing" in captured.out
+
+    def test_detects_spec_created_status(
+        self, temp_git_repo: Path
+    ) -> None:
+        """Correctly detects specs with spec.md as 'spec_created'."""
+        specs_dir = temp_git_repo / ".auto-claude" / "specs"
+        specs_dir.mkdir(parents=True)
+
+        spec_001 = specs_dir / "001-test"
+        spec_001.mkdir()
+        (spec_001 / "spec.md").write_text("# Test\n")
+
+        result = handle_batch_status_command(str(temp_git_repo))
+
+        assert result is True
+
+    def test_detects_building_status(
+        self, temp_git_repo: Path
+    ) -> None:
+        """Correctly detects specs with implementation_plan.json as 'building'."""
+        specs_dir = temp_git_repo / ".auto-claude" / "specs"
+        specs_dir.mkdir(parents=True)
+
+        spec_001 = specs_dir / "001-test"
+        spec_001.mkdir()
+        (spec_001 / "implementation_plan.json").write_text('{"phases": []}')
+
+        result = handle_batch_status_command(str(temp_git_repo))
+
+        assert result is True
+
+    def test_detects_qa_approved_status(
+        self, temp_git_repo: Path
+    ) -> None:
+        """Correctly detects specs with qa_signoff as 'qa_approved'."""
+        specs_dir = temp_git_repo / ".auto-claude" / "specs"
+        specs_dir.mkdir(parents=True)
+
+        spec_001 = specs_dir / "001-test"
+        spec_001.mkdir()
+        (spec_001 / "qa_report.md").write_text("# QA Approved\n")
+        (spec_001 / "implementation_plan.json").write_text(
+            '{"qa_signoff": {"status": "approved"}}'
+        )
+
+        result = handle_batch_status_command(str(temp_git_repo))
+
+        assert result is True
+
+    def test_detects_pending_spec_status(
+        self, temp_git_repo: Path
+    ) -> None:
+        """Correctly detects specs with only requirements.json as 'pending_spec'."""
+        specs_dir = temp_git_repo / ".auto-claude" / "specs"
+        specs_dir.mkdir(parents=True)
+
+        spec_001 = specs_dir / "001-test"
+        spec_001.mkdir()
+        (spec_001 / "requirements.json").write_text('{"task": "test"}')
+
+        result = handle_batch_status_command(str(temp_git_repo))
+
+        assert result is True
+
+    def test_handles_corrupted_requirements_json(
+        self, capsys, temp_git_repo: Path
+    ) -> None:
+        """Handles corrupted requirements.json gracefully."""
+        specs_dir = temp_git_repo / ".auto-claude" / "specs"
+        specs_dir.mkdir(parents=True)
+
+        spec_001 = specs_dir / "001-test"
+        spec_001.mkdir()
+        (spec_001 / "requirements.json").write_text("{ invalid json")
+
+        result = handle_batch_status_command(str(temp_git_repo))
+
+        assert result is True
+        captured = capsys.readouterr()
+        assert "001-test" in captured.out
+
+
+# =============================================================================
+# HANDLE_BATCH_CLEANUP_COMMAND TESTS
+# =============================================================================
+
+class TestHandleBatchCleanupCommand:
+    """Tests for handle_batch_cleanup_command() function."""
+
+    def test_dry_run_shows_what_would_be_deleted(
+        self, capsys, project_with_completed_specs_and_worktrees: Path
+    ) -> None:
+        """Dry run shows what would be deleted without actually deleting."""
+        result = handle_batch_cleanup_command(
+            str(project_with_completed_specs_and_worktrees), dry_run=True
+        )
+
+        assert result is True
+
+        captured = capsys.readouterr()
+        assert "2 completed spec" in captured.out
+        assert "001-completed-with-wt" in captured.out
+        assert "002-completed-no-wt" in captured.out
+        assert "Would remove:" in captured.out
+        assert "Run with --no-dry-run" in captured.out
+
+    def test_dry_run_does_not_delete(
+        self, project_with_completed_specs_and_worktrees: Path
+    ) -> None:
+        """Dry run does not actually delete anything."""
+        specs_dir = project_with_completed_specs_and_worktrees / ".auto-claude" / "specs"
+
+        handle_batch_cleanup_command(
+            str(project_with_completed_specs_and_worktrees), dry_run=True
+        )
+
+        # Specs should still exist
+        assert (specs_dir / "001-completed-with-wt").exists()
+        assert (specs_dir / "002-completed-no-wt").exists()
+
+    def test_cleanup_deletes_specs_and_worktrees(
+        self, project_with_completed_specs_and_worktrees: Path
+    ) -> None:
+        """Actually deletes completed specs and worktrees when dry_run=False."""
+        specs_dir = project_with_completed_specs_and_worktrees / ".auto-claude" / "specs"
+        worktrees_dir = project_with_completed_specs_and_worktrees / ".auto-claude" / "worktrees" / "tasks"
+
+        handle_batch_cleanup_command(
+            str(project_with_completed_specs_and_worktrees), dry_run=False
+        )
+
+        # Completed specs should be deleted
+        assert not (specs_dir / "001-completed-with-wt").exists()
+        assert not (specs_dir / "002-completed-no-wt").exists()
+
+        # Worktree should be deleted
+        assert not (worktrees_dir / "001-completed-with-wt").exists()
+
+    def test_cleanup_preserves_incomplete_specs(
+        self, project_with_completed_specs_and_worktrees: Path
+    ) -> None:
+        """Does not delete specs without qa_report.md."""
+        specs_dir = project_with_completed_specs_and_worktrees / ".auto-claude" / "specs"
+
+        handle_batch_cleanup_command(
+            str(project_with_completed_specs_and_worktrees), dry_run=False
+        )
+
+        # Incomplete spec should still exist
+        assert (specs_dir / "003-incomplete").exists()
+
+    def test_returns_true_for_no_specs_directory(
+        self, capsys, temp_git_repo: Path
+    ) -> None:
+        """Returns True when no specs directory exists."""
+        result = handle_batch_cleanup_command(str(temp_git_repo), dry_run=True)
+
+        assert result is True
+
+        captured = capsys.readouterr()
+        assert "No specs directory found" in captured.out
+
+    def test_returns_true_for_no_completed_specs(
+        self, capsys, temp_git_repo: Path
+    ) -> None:
+        """Returns True when no completed specs exist."""
+        # Create specs without qa_report.md
+        specs_dir = temp_git_repo / ".auto-claude" / "specs"
+        specs_dir.mkdir(parents=True)
+
+        spec_001 = specs_dir / "001-incomplete"
+        spec_001.mkdir()
+        (spec_001 / "spec.md").write_text("# In Progress\n")
+
+        result = handle_batch_cleanup_command(str(temp_git_repo), dry_run=True)
+
+        assert result is True
+
+        captured = capsys.readouterr()
+        assert "No completed specs to clean up" in captured.out
+
+    def test_cleanup_with_git_worktree_remove(
+        self, project_with_completed_specs_and_worktrees: Path
+    ) -> None:
+        """Uses git worktree remove when available."""
+        with patch('subprocess.run') as mock_run:
+            # Mock git worktree remove to succeed
+            mock_run.return_value = MagicMock(returncode=0)
+
+            handle_batch_cleanup_command(
+                str(project_with_completed_specs_and_worktrees), dry_run=False
+            )
+
+            # Should have called git worktree remove
+            # Check that the first argument of any call contains "git", "worktree", "remove"
+            assert any(
+                "git" in str(call.args) and
+                "worktree" in str(call.args) and
+                "remove" in str(call.args)
+                for call in mock_run.call_args_list
+            )
+
+    def test_cleanup_fallback_to_manual_removal(
+        self, project_with_completed_specs_and_worktrees: Path
+    ) -> None:
+        """Falls back to manual removal when git worktree remove fails."""
+        specs_dir = project_with_completed_specs_and_worktrees / ".auto-claude" / "specs"
+
+        with patch('subprocess.run') as mock_run:
+            # Mock git worktree remove to fail
+            mock_run.return_value = MagicMock(returncode=1)
+
+            handle_batch_cleanup_command(
+                str(project_with_completed_specs_and_worktrees), dry_run=False
+            )
+
+            # Should still delete the spec
+            assert not (specs_dir / "001-completed-with-wt").exists()
+
+    def test_cleanup_handles_timeout_gracefully(
+        self, project_with_completed_specs_and_worktrees: Path
+    ) -> None:
+        """Handles git command timeout gracefully."""
+        specs_dir = project_with_completed_specs_and_worktrees / ".auto-claude" / "specs"
+
+        with patch('subprocess.run') as mock_run:
+            # Mock timeout
+            from subprocess import TimeoutExpired
+            mock_run.side_effect = TimeoutExpired("git", 30)
+
+            handle_batch_cleanup_command(
+                str(project_with_completed_specs_and_worktrees), dry_run=False
+            )
+
+            # Should still delete the spec (fallback)
+            assert not (specs_dir / "001-completed-with-wt").exists()
+
+    def test_cleanup_handles_exceptions(
+        self, capsys, project_with_completed_specs_and_worktrees: Path
+    ) -> None:
+        """Handles exceptions during cleanup gracefully."""
+        with patch('subprocess.run') as mock_run:
+            # Mock exception
+            mock_run.side_effect = Exception("Test error")
+
+            handle_batch_cleanup_command(
+                str(project_with_completed_specs_and_worktrees), dry_run=False
+            )
+
+            # Should continue and delete specs
+            captured = capsys.readouterr()
+            assert "Cleaned up" in captured.out
+
+    def test_cleanup_shows_worktree_path_in_dry_run(
+        self, capsys, project_with_completed_specs_and_worktrees: Path
+    ) -> None:
+        """Shows worktree path in dry run output."""
+        handle_batch_cleanup_command(
+            str(project_with_completed_specs_and_worktrees), dry_run=True
+        )
+
+        captured = capsys.readouterr()
+        assert ".auto-claude/worktrees/tasks/001-completed-with-wt" in captured.out
+
+
+# =============================================================================
+# INTEGRATION TESTS
+# =============================================================================
+
+class TestBatchCommandsIntegration:
+    """Integration tests for batch commands."""
+
+    def test_create_then_status_workflow(
+        self, sample_batch_file: Path, temp_git_repo: Path
+    ) -> None:
+        """Test creating specs then checking status."""
+        # Create specs
+        create_result = handle_batch_create_command(
+            str(sample_batch_file), str(temp_git_repo)
+        )
+        assert create_result is True
+
+        # Check status
+        status_result = handle_batch_status_command(str(temp_git_repo))
+        assert status_result is True
+
+    def test_create_then_cleanup_workflow(
+        self, temp_dir: Path, temp_git_repo: Path
+    ) -> None:
+        """Test creating specs, marking complete, then cleanup."""
+        # Create a spec
+        batch_data = {"tasks": [{"title": "Test Task"}]}
+        batch_file = temp_dir / "batch.json"
+        batch_file.write_text(json.dumps(batch_data))
+
+        handle_batch_create_command(str(batch_file), str(temp_git_repo))
+
+        # Mark as complete with proper QA approval
+        specs_dir = temp_git_repo / ".auto-claude" / "specs"
+        spec_001 = specs_dir / "001-test-task"
+        (spec_001 / "qa_report.md").write_text("# QA Approved\n")
+        (spec_001 / "implementation_plan.json").write_text(
+            '{"qa_signoff": {"status": "approved"}}'
+        )
+
+        # Dry run cleanup
+        result = handle_batch_cleanup_command(str(temp_git_repo), dry_run=True)
+        assert result is True
+
+        # Actual cleanup
+        result = handle_batch_cleanup_command(str(temp_git_repo), dry_run=False)
+        assert result is True
+
+        # Spec should be deleted
+        assert not spec_001.exists()
+
+
+class TestBatchCommandsExceptionCoverage:
+    """Tests for exception handling paths to increase coverage."""
+
+    def test_cleanup_with_permission_error(
+        self, temp_dir: Path, temp_git_repo: Path, monkeypatch
+    ) -> None:
+        """Test cleanup handles permission errors gracefully."""
+
+        # Create a completed spec with proper QA approval
+        specs_dir = temp_git_repo / ".auto-claude" / "specs"
+        spec_001 = specs_dir / "001-test-task"
+        spec_001.mkdir(parents=True)
+        (spec_001 / "qa_report.md").write_text("# QA Approved\n")
+        (spec_001 / "implementation_plan.json").write_text(
+            '{"qa_signoff": {"status": "approved"}}'
+        )
+
+        # Mock shutil.rmtree to raise permission error
+        def mock_rmtree_raises(path, *args, **kwargs):
+            if "001-test-task" in str(path):
+                raise PermissionError(f"Permission denied: {path}")
+
+        monkeypatch.setattr("cli.batch_commands.shutil.rmtree", mock_rmtree_raises)
+
+        # Should handle the error gracefully and not crash
+        result = handle_batch_cleanup_command(str(temp_git_repo), dry_run=False)
+        assert result is True
+
+    def test_cleanup_with_generic_exception(
+        self, temp_dir: Path, temp_git_repo: Path, monkeypatch
+    ) -> None:
+        """Test cleanup handles generic exceptions gracefully."""
+
+        # Create a completed spec with proper QA approval
+        specs_dir = temp_git_repo / ".auto-claude" / "specs"
+        spec_001 = specs_dir / "001-test-task"
+        spec_001.mkdir(parents=True)
+        (spec_001 / "qa_report.md").write_text("# QA Approved\n")
+        (spec_001 / "implementation_plan.json").write_text(
+            '{"qa_signoff": {"status": "approved"}}'
+        )
+
+        # Mock shutil.rmtree to raise generic exception
+        def mock_rmtree_raises(path, *args, **kwargs):
+            if "001-test-task" in str(path):
+                raise RuntimeError(f"Cannot delete: {path}")
+
+        monkeypatch.setattr("cli.batch_commands.shutil.rmtree", mock_rmtree_raises)
+
+        # Should handle the error gracefully and not crash
+        result = handle_batch_cleanup_command(str(temp_git_repo), dry_run=False)
+        assert result is True

tests/test_cli_followup_commands.py

@@ -0,0 +1,970 @@
+#!/usr/bin/env python3
+"""
+Tests for CLI Followup Commands (cli/followup_commands.py)
+===========================================================
+
+Tests for follow-up task commands:
+- collect_followup_task()
+- handle_followup_command()
+"""
+
+import json
+import sys
+from pathlib import Path
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+# Note: conftest.py handles apps/backend path
+# Add tests directory to path for test_utils import (conftest doesn't handle this)
+if str(Path(__file__).parent) not in sys.path:
+    sys.path.insert(0, str(Path(__file__).parent))
+
+
+# =============================================================================
+# Mock external dependencies before importing cli.followup_commands
+# =============================================================================
+
+# Import shared helper for creating mock modules
+from test_utils import _create_mock_module
+
+# Mock modules
+if 'progress' not in sys.modules:
+    sys.modules['progress'] = _create_mock_module()
+
+
+# =============================================================================
+# Auto-use fixture to set up mock UI module before importing cli.followup_commands
+# =============================================================================
+
+@pytest.fixture(autouse=True)
+def setup_mock_ui_for_followup(mock_ui_module_full):
+    """Auto-use fixture that replaces sys.modules['ui'] with mock for each test."""
+    sys.modules['ui'] = mock_ui_module_full
+    yield
+
+# =============================================================================
+# Import cli.followup_commands after mocking dependencies
+# =============================================================================
+
+from cli.followup_commands import (
+    collect_followup_task,
+    handle_followup_command,
+)
+
+
+# =============================================================================
+# Tests for collect_followup_task()
+# =============================================================================
+
+class TestCollectFollowupTask:
+    """Tests for collect_followup_task() function."""
+
+    def test_returns_task_description_on_type(self, temp_dir, capsys):
+        """Returns task description when user chooses to type."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        with patch('cli.followup_commands.select_menu', return_value='type'):
+            with patch('builtins.input', side_effect=['First line', 'Second line', '']):
+                result = collect_followup_task(spec_dir)
+
+        assert result is not None
+        assert "First line" in result
+        assert "Second line" in result
+
+        # Check that FOLLOWUP_REQUEST.md was created
+        followup_file = spec_dir / "FOLLOWUP_REQUEST.md"
+        assert followup_file.exists()
+        assert followup_file.read_text() == result
+
+    def test_reads_from_file_when_selected(self, temp_dir, capsys):
+        """Reads task description from file when file option selected."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        # Create a temp file with task description
+        task_file = temp_dir / "task.txt"
+        task_file.write_text("Task from file\nMultiple lines")
+
+        with patch('cli.followup_commands.select_menu', return_value='file'):
+            with patch('builtins.input', return_value=str(task_file)):
+                result = collect_followup_task(spec_dir)
+
+        assert result is not None
+        assert "Task from file" in result
+        assert "Multiple lines" in result
+
+    def test_handles_nonexistent_file(self, temp_dir, capsys):
+        """Handles case when specified file doesn't exist."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        with patch('cli.followup_commands.select_menu', return_value='file'):
+            with patch('builtins.input', return_value='/nonexistent/file.txt'):
+                with patch('cli.followup_commands.select_menu', return_value='quit'):
+                    result = collect_followup_task(spec_dir)
+
+        assert result is None
+
+    def test_handles_empty_file(self, temp_dir, capsys):
+        """Handles case when file is empty."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        # Create empty file
+        task_file = temp_dir / "empty.txt"
+        task_file.write_text("")
+
+        with patch('cli.followup_commands.select_menu', side_effect=['file', 'quit']):
+            with patch('builtins.input', side_effect=[str(task_file)]):
+                result = collect_followup_task(spec_dir)
+
+        assert result is None
+
+    def test_handles_permission_error(self, temp_dir, capsys):
+        """Handles permission denied error when reading file."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        task_file = temp_dir / "restricted.txt"
+        task_file.write_text("Content")
+
+        with patch('cli.followup_commands.select_menu', side_effect=['file', 'quit']):
+            with patch('builtins.input', return_value=str(task_file)):
+                # Mock Path.read_text to raise PermissionError
+                with patch('pathlib.Path.read_text', side_effect=PermissionError("Denied")):
+                    result = collect_followup_task(spec_dir)
+
+        assert result is None
+
+    def test_returns_none_on_quit(self, temp_dir):
+        """Returns None when user selects quit."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        with patch('cli.followup_commands.select_menu', return_value='quit'):
+            result = collect_followup_task(spec_dir)
+
+        assert result is None
+
+    def test_retries_on_empty_input(self, temp_dir, capsys):
+        """Retries when user provides empty input."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        # First attempt: type with empty input
+        # Second attempt: type with actual content
+        with patch('cli.followup_commands.select_menu', side_effect=['type', 'type']):
+            with patch('builtins.input', side_effect=[
+                '',  # First attempt - empty
+                'Actual task content',  # Second attempt - content
+                ''
+            ]):
+                result = collect_followup_task(spec_dir, max_retries=3)
+
+        assert result is not None
+        assert "Actual task content" in result
+
+    def test_respects_max_retries(self, temp_dir, capsys):
+        """Stops retrying after max attempts reached."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        # Always return empty input
+        with patch('cli.followup_commands.select_menu', return_value='type'):
+            with patch('builtins.input', side_effect=['', '', '', '']):
+                result = collect_followup_task(spec_dir, max_retries=2)
+
+        assert result is None
+        captured = capsys.readouterr()
+        assert "Maximum retry" in captured.out or "cancelled" in captured.out.lower()
+
+    def test_handles_keyboard_interrupt(self, temp_dir, capsys):
+        """Handles KeyboardInterrupt during input collection."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        with patch('cli.followup_commands.select_menu', return_value='type'):
+            with patch('builtins.input', side_effect=KeyboardInterrupt):
+                result = collect_followup_task(spec_dir)
+
+        assert result is None
+        captured = capsys.readouterr()
+        assert "Cancelled" in captured.out or "cancel" in captured.out.lower()
+
+    def test_handles_eof_error(self, temp_dir, capsys):
+        """Handles EOFError during input collection."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        with patch('cli.followup_commands.select_menu', return_value='type'):
+            with patch('builtins.input', side_effect=EOFError):
+                result = collect_followup_task(spec_dir)
+
+        # EOFError should break the input loop, returning None if empty
+        # The actual content would be empty, so it should retry or return None
+        assert result is None
+
+    def test_saves_to_followup_request_file(self, temp_dir):
+        """Saves the collected task to FOLLOWUP_REQUEST.md."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        task_description = "This is a test follow-up task"
+
+        with patch('cli.followup_commands.select_menu', return_value='type'):
+            with patch('builtins.input', side_effect=[task_description, '']):
+                collect_followup_task(spec_dir)
+
+        followup_file = spec_dir / "FOLLOWUP_REQUEST.md"
+        assert followup_file.exists()
+        assert followup_file.read_text() == task_description
+
+    def test_handles_empty_file_path(self, temp_dir, capsys):
+        """Handles case when no file path is provided."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        with patch('cli.followup_commands.select_menu', side_effect=['file', 'quit']):
+            with patch('builtins.input', return_value=''):
+                result = collect_followup_task(spec_dir)
+
+        assert result is None
+        captured = capsys.readouterr()
+        assert "No file path" in captured.out or "cancel" in captured.out.lower()
+
+    def test_expands_tilde_in_path(self, temp_dir):
+        """Expands ~ in file path to home directory."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        # Create a file in temp_dir to simulate home
+        task_file = temp_dir / "task.txt"
+        task_file.write_text("Task content")
+
+        with patch('cli.followup_commands.select_menu', return_value='file'):
+            with patch('builtins.input', return_value=str(task_file)):
+                with patch('pathlib.Path.expanduser', return_value=task_file):
+                    result = collect_followup_task(spec_dir)
+
+        assert result is not None
+        assert "Task content" in result
+
+
+# =============================================================================
+# Tests for handle_followup_command()
+# =============================================================================
+
+class TestHandleFollowupCommand:
+    """Tests for handle_followup_command() function."""
+
+    @patch('cli.utils.validate_environment')
+    @patch('agent.run_followup_planner', new_callable=AsyncMock)
+    @patch('progress.is_build_complete')
+    @patch('progress.count_subtasks')
+    @patch('cli.followup_commands.collect_followup_task')
+    def test_exits_when_no_implementation_plan(
+        self,
+        mock_collect,
+        mock_count,
+        mock_is_complete,
+        mock_run_planner,
+        mock_validate,
+        temp_dir,
+        capsys
+    ):
+        """Exits with error when implementation plan doesn't exist."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+        (spec_dir / "spec.md").write_text("# Test")
+
+        # sys.exit is called directly in the function, so we need to catch SystemExit
+        with pytest.raises(SystemExit) as exc_info:
+            handle_followup_command(temp_dir, spec_dir, "sonnet")
+
+        assert exc_info.value.code == 1
+
+        captured = capsys.readouterr()
+        assert "No implementation plan found" in captured.out or "not been built" in captured.out
+
+    @patch('cli.utils.validate_environment')
+    @patch('agent.run_followup_planner', new_callable=AsyncMock)
+    @patch('cli.followup_commands.is_build_complete')
+    @patch('cli.followup_commands.count_subtasks')
+    @patch('cli.followup_commands.collect_followup_task')
+    def test_exits_when_build_not_complete(
+        self,
+        mock_collect,
+        mock_count,
+        mock_is_complete,
+        mock_run_planner,
+        mock_validate,
+        temp_dir,
+        capsys
+    ):
+        """Exits with error when build is not complete."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+        (spec_dir / "spec.md").write_text("# Test")
+        (spec_dir / "implementation_plan.json").write_text('{}')
+
+        mock_is_complete.return_value = False
+        mock_count.return_value = (2, 5)  # 2 completed, 5 total
+
+        # sys.exit is called directly in the function
+        with pytest.raises(SystemExit) as exc_info:
+            handle_followup_command(temp_dir, spec_dir, "sonnet")
+
+        assert exc_info.value.code == 1
+        captured = capsys.readouterr()
+        assert "not complete" in captured.out or "pending" in captured.out
+
+    @patch('cli.utils.validate_environment', return_value=True)
+    @patch('agent.run_followup_planner', new_callable=AsyncMock)
+    @patch('cli.followup_commands.is_build_complete', return_value=True)
+    @patch('cli.followup_commands.collect_followup_task')
+    def test_runs_planner_after_collecting_task(
+        self,
+        mock_collect,
+        mock_is_complete,
+        mock_run_planner,
+        mock_validate,
+        temp_dir,
+        capsys
+    ):
+        """Runs follow-up planner after successfully collecting task."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+        (spec_dir / "spec.md").write_text("# Test")
+        (spec_dir / "implementation_plan.json").write_text('{"phases": []}')
+
+        mock_collect.return_value = "Add new feature"
+        mock_run_planner.return_value = True
+
+        handle_followup_command(temp_dir, spec_dir, "sonnet")
+
+        assert mock_run_planner.called
+        call_kwargs = mock_run_planner.call_args[1]
+        assert call_kwargs['project_dir'] == temp_dir
+        assert call_kwargs['spec_dir'] == spec_dir
+        assert call_kwargs['model'] == "sonnet"
+
+    @patch('cli.utils.validate_environment', return_value=True)
+    @patch('agent.run_followup_planner', new_callable=AsyncMock)
+    @patch('cli.followup_commands.is_build_complete', return_value=True)
+    @patch('cli.followup_commands.collect_followup_task')
+    def test_returns_when_user_cancels(
+        self,
+        mock_collect,
+        mock_is_complete,
+        mock_run_planner,
+        mock_validate,
+        temp_dir,
+        capsys
+    ):
+        """Returns early when user cancels task collection."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+        (spec_dir / "spec.md").write_text("# Test")
+        (spec_dir / "implementation_plan.json").write_text('{"phases": []}')
+
+        mock_collect.return_value = None
+
+        handle_followup_command(temp_dir, spec_dir, "sonnet")
+
+        assert not mock_run_planner.called
+        captured = capsys.readouterr()
+        assert "cancel" in captured.out.lower()
+
+    @patch('cli.utils.validate_environment', return_value=False)
+    @patch('agent.run_followup_planner', new_callable=AsyncMock)
+    @patch('cli.followup_commands.is_build_complete', return_value=True)
+    @patch('cli.followup_commands.collect_followup_task')
+    def test_exits_when_environment_invalid(
+        self,
+        mock_collect,
+        mock_is_complete,
+        mock_run_planner,
+        mock_validate,
+        temp_dir
+    ):
+        """Exits when environment validation fails."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+        (spec_dir / "spec.md").write_text("# Test")
+        (spec_dir / "implementation_plan.json").write_text('{"phases": []}')
+
+        mock_collect.return_value = "Task description"
+
+        # sys.exit is called directly in the function
+        with pytest.raises(SystemExit) as exc_info:
+            handle_followup_command(temp_dir, spec_dir, "sonnet")
+
+        assert exc_info.value.code == 1
+        assert not mock_run_planner.called
+
+    @patch('cli.utils.validate_environment', return_value=True)
+    @patch('agent.run_followup_planner', new_callable=AsyncMock)
+    @patch('cli.followup_commands.is_build_complete', return_value=True)
+    @patch('cli.followup_commands.collect_followup_task')
+    def test_handles_successful_planning(
+        self,
+        mock_collect,
+        mock_is_complete,
+        mock_run_planner,
+        mock_validate,
+        temp_dir,
+        capsys
+    ):
+        """Shows success message when planning completes successfully."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+        (spec_dir / "spec.md").write_text("# Test")
+        (spec_dir / "implementation_plan.json").write_text('{"phases": []}')
+
+        mock_collect.return_value = "Add feature"
+        mock_run_planner.return_value = True
+
+        handle_followup_command(temp_dir, spec_dir, "sonnet")
+
+        captured = capsys.readouterr()
+        assert "COMPLETE" in captured.out or "success" in captured.out.lower()
+
+    @patch('cli.utils.validate_environment', return_value=True)
+    @patch('agent.run_followup_planner', new_callable=AsyncMock)
+    @patch('cli.followup_commands.is_build_complete', return_value=True)
+    @patch('cli.followup_commands.collect_followup_task')
+    def test_handles_planning_failure(
+        self,
+        mock_collect,
+        mock_is_complete,
+        mock_run_planner,
+        mock_validate,
+        temp_dir,
+        capsys
+    ):
+        """Shows warning when planning doesn't fully succeed."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+        (spec_dir / "spec.md").write_text("# Test")
+        (spec_dir / "implementation_plan.json").write_text('{"phases": []}')
+
+        mock_collect.return_value = "Add feature"
+        mock_run_planner.return_value = False
+
+        with pytest.raises(SystemExit):
+            handle_followup_command(temp_dir, spec_dir, "sonnet")
+
+        captured = capsys.readouterr()
+        assert "INCOMPLETE" in captured.out or "warning" in captured.out.lower()
+
+    @patch('cli.utils.validate_environment', return_value=True)
+    @patch('agent.run_followup_planner', new_callable=AsyncMock)
+    @patch('cli.followup_commands.is_build_complete', return_value=True)
+    @patch('cli.followup_commands.collect_followup_task')
+    def test_handles_keyboard_interrupt(
+        self,
+        mock_collect,
+        mock_is_complete,
+        mock_run_planner,
+        mock_validate,
+        temp_dir,
+        capsys
+    ):
+        """Handles KeyboardInterrupt during planning."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+        (spec_dir / "spec.md").write_text("# Test")
+        (spec_dir / "implementation_plan.json").write_text('{"phases": []}')
+
+        mock_collect.return_value = "Add feature"
+        mock_run_planner.side_effect = KeyboardInterrupt()
+
+        with pytest.raises(SystemExit):
+            handle_followup_command(temp_dir, spec_dir, "sonnet")
+
+        captured = capsys.readouterr()
+        assert "paused" in captured.out.lower() or "retry" in captured.out.lower()
+
+    @patch('cli.utils.validate_environment', return_value=True)
+    @patch('agent.run_followup_planner', new_callable=AsyncMock)
+    @patch('cli.followup_commands.is_build_complete', return_value=True)
+    @patch('cli.followup_commands.collect_followup_task')
+    def test_handles_planning_exception(
+        self,
+        mock_collect,
+        mock_is_complete,
+        mock_run_planner,
+        mock_validate,
+        temp_dir,
+        capsys
+    ):
+        """Handles exception during planning."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+        (spec_dir / "spec.md").write_text("# Test")
+        (spec_dir / "implementation_plan.json").write_text('{"phases": []}')
+
+        mock_collect.return_value = "Add feature"
+        mock_run_planner.side_effect = Exception("Planning failed")
+
+        with pytest.raises(SystemExit):
+            handle_followup_command(temp_dir, spec_dir, "sonnet", verbose=False)
+
+        captured = capsys.readouterr()
+        assert "error" in captured.out.lower()
+
+    @patch('cli.utils.validate_environment', return_value=True)
+    @patch('agent.run_followup_planner', new_callable=AsyncMock)
+    @patch('cli.followup_commands.is_build_complete', return_value=True)
+    @patch('cli.followup_commands.collect_followup_task')
+    def test_shows_traceback_in_verbose_mode(
+        self,
+        mock_collect,
+        mock_is_complete,
+        mock_run_planner,
+        mock_validate,
+        temp_dir,
+        capsys
+    ):
+        """Shows traceback in verbose mode."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+        (spec_dir / "spec.md").write_text("# Test")
+        (spec_dir / "implementation_plan.json").write_text('{"phases": []}')
+
+        mock_collect.return_value = "Add feature"
+        test_error = Exception("Test error")
+        mock_run_planner.side_effect = test_error
+
+        with pytest.raises(SystemExit):
+            handle_followup_command(temp_dir, spec_dir, "sonnet", verbose=True)
+
+        captured = capsys.readouterr()
+        # In verbose mode, traceback should be printed
+        assert "error" in captured.out.lower()
+
+    def test_counts_prior_followups(self, temp_dir, capsys):
+        """Counts and displays prior follow-up phases."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+        (spec_dir / "spec.md").write_text("# Test")
+
+        # Create implementation plan with follow-up phases
+        plan = {
+            "phases": [
+                {"name": "Initial Phase"},
+                {"name": "Follow-Up: Bug Fixes"},
+                {"name": "Followup: Enhancement"},
+            ]
+        }
+        (spec_dir / "implementation_plan.json").write_text(json.dumps(plan))
+
+        with patch('cli.followup_commands.is_build_complete', return_value=True):
+            with patch('cli.followup_commands.collect_followup_task', return_value=None):
+                handle_followup_command(temp_dir, spec_dir, "sonnet")
+
+        captured = capsys.readouterr()
+        # Should indicate prior follow-ups were detected
+        # The exact output depends on the implementation
+        assert "complete" in captured.out.lower()
+
+    def test_shows_ready_message_for_first_followup(self, temp_dir, capsys):
+        """Shows appropriate message for first follow-up."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+        (spec_dir / "spec.md").write_text("# Test")
+
+        # Create plan without follow-up phases
+        plan = {"phases": [{"name": "Initial Phase"}]}
+        (spec_dir / "implementation_plan.json").write_text(json.dumps(plan))
+
+        with patch('cli.followup_commands.is_build_complete', return_value=True):
+            with patch('cli.followup_commands.collect_followup_task', return_value=None):
+                handle_followup_command(temp_dir, spec_dir, "sonnet")
+
+        captured = capsys.readouterr()
+        assert "complete" in captured.out.lower() or "ready" in captured.out.lower()
+
+    def test_passes_verbose_flag_to_planner(self, temp_dir):
+        """Passes verbose flag to follow-up planner."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+        (spec_dir / "spec.md").write_text("# Test")
+        (spec_dir / "implementation_plan.json").write_text('{"phases": []}')
+
+        with patch('cli.utils.validate_environment', return_value=True):
+            with patch('agent.run_followup_planner', new_callable=AsyncMock, return_value=True) as mock_planner:
+                with patch('cli.followup_commands.is_build_complete', return_value=True):
+                    with patch('cli.followup_commands.collect_followup_task', return_value="Task"):
+                        handle_followup_command(temp_dir, spec_dir, "sonnet", verbose=True)
+
+        call_kwargs = mock_planner.call_args[1]
+        assert call_kwargs['verbose'] is True
+
+
+# =============================================================================
+# Additional tests for improved coverage (lines 108-111, 139-144, 150-153, 296-297)
+# =============================================================================
+
+    def test_handles_keyboard_interrupt_on_file_path_input(self, temp_dir, capsys):
+        """Handles KeyboardInterrupt when entering file path (lines 108-111)."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        with patch('cli.followup_commands.select_menu', return_value='file'):
+            with patch('builtins.input', side_effect=KeyboardInterrupt):
+                result = collect_followup_task(spec_dir)
+
+        assert result is None
+        captured = capsys.readouterr()
+        assert "Cancelled" in captured.out or "cancel" in captured.out.lower()
+
+    def test_handles_eof_error_on_file_path_input(self, temp_dir, capsys):
+        """Handles EOFError when entering file path (lines 108-111)."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        with patch('cli.followup_commands.select_menu', return_value='file'):
+            with patch('builtins.input', side_effect=EOFError):
+                result = collect_followup_task(spec_dir)
+
+        assert result is None
+        captured = capsys.readouterr()
+        assert "Cancelled" in captured.out or "cancel" in captured.out.lower()
+
+    def test_handles_file_not_found_error(self, temp_dir, capsys):
+        """Handles FileNotFoundError when file doesn't exist (lines 139-144)."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        # Create a path that doesn't exist
+        nonexistent_file = temp_dir / "does_not_exist.txt"
+
+        with patch('cli.followup_commands.select_menu', side_effect=['file', 'quit']):
+            with patch('builtins.input', return_value=str(nonexistent_file)):
+                result = collect_followup_task(spec_dir)
+
+        assert result is None
+        captured = capsys.readouterr()
+        # Should show file not found error
+        assert "not found" in captured.out.lower() or "check that the path" in captured.out.lower()
+
+    def test_handles_generic_exception_on_file_read(self, temp_dir, capsys):
+        """Handles generic exception when reading file (lines 150-153)."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        # Create a file that exists
+        task_file = temp_dir / "task.txt"
+        task_file.write_text("Content")
+
+        with patch('cli.followup_commands.select_menu', side_effect=['file', 'quit']):
+            with patch('builtins.input', return_value=str(task_file)):
+                # Mock read_text to raise a generic exception
+                with patch('pathlib.Path.read_text', side_effect=OSError("Read error")):
+                    result = collect_followup_task(spec_dir)
+
+        assert result is None
+        captured = capsys.readouterr()
+        assert "error" in captured.out.lower()
+
+    def test_handles_unicode_decode_error_on_file_read(self, temp_dir, capsys):
+        """Handles UnicodeDecodeError when reading file (lines 150-153)."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        # Create a file that exists
+        task_file = temp_dir / "task.txt"
+        task_file.write_text("Content")
+
+        with patch('cli.followup_commands.select_menu', side_effect=['file', 'quit']):
+            with patch('builtins.input', return_value=str(task_file)):
+                # Mock read_text to raise UnicodeDecodeError
+                with patch('pathlib.Path.read_text', side_effect=UnicodeDecodeError('utf-8', b'', 0, 1, 'invalid')):
+                    result = collect_followup_task(spec_dir)
+
+        assert result is None
+        captured = capsys.readouterr()
+        assert "error" in captured.out.lower()
+
+    def test_handles_runtime_error_on_file_read(self, temp_dir, capsys):
+        """Handles RuntimeError when reading file (lines 150-153)."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        # Create a file that exists
+        task_file = temp_dir / "task.txt"
+        task_file.write_text("Content")
+
+        with patch('cli.followup_commands.select_menu', side_effect=['file', 'quit']):
+            with patch('builtins.input', return_value=str(task_file)):
+                # Mock read_text to raise RuntimeError
+                with patch('pathlib.Path.read_text', side_effect=RuntimeError("Unexpected error")):
+                    result = collect_followup_task(spec_dir)
+
+        assert result is None
+        captured = capsys.readouterr()
+        assert "error" in captured.out.lower()
+
+
+class TestHandleFollowupCommandEdgeCases:
+    """Additional tests for handle_followup_command() edge cases (lines 296-297)."""
+
+    @patch('cli.utils.validate_environment', return_value=True)
+    @patch('agent.run_followup_planner', new_callable=AsyncMock)
+    @patch('cli.followup_commands.is_build_complete', return_value=True)
+    @patch('cli.followup_commands.collect_followup_task')
+    def test_handles_json_decode_error_in_plan_file(
+        self,
+        mock_collect,
+        mock_is_complete,
+        mock_run_planner,
+        mock_validate,
+        temp_dir,
+        capsys
+    ):
+        """Handles JSONDecodeError when implementation_plan.json is malformed (lines 296-297)."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+        (spec_dir / "spec.md").write_text("# Test")
+
+        # Write invalid JSON to implementation_plan.json
+        (spec_dir / "implementation_plan.json").write_text('{ invalid json }')
+
+        mock_collect.return_value = None
+
+        # Should handle the JSONDecodeError gracefully and continue
+        handle_followup_command(temp_dir, spec_dir, "sonnet")
+
+        captured = capsys.readouterr()
+        # Should complete without error (prior_followup_count just stays 0)
+        assert "complete" in captured.out.lower()
+
+    @patch('cli.utils.validate_environment', return_value=True)
+    @patch('agent.run_followup_planner', new_callable=AsyncMock)
+    @patch('cli.followup_commands.is_build_complete', return_value=True)
+    @patch('cli.followup_commands.collect_followup_task')
+    def test_handles_keyerror_in_plan_file(
+        self,
+        mock_collect,
+        mock_is_complete,
+        mock_run_planner,
+        mock_validate,
+        temp_dir,
+        capsys
+    ):
+        """Handles KeyError when implementation_plan.json is missing expected keys (lines 296-297)."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+        (spec_dir / "spec.md").write_text("# Test")
+
+        # Write JSON without 'phases' key
+        (spec_dir / "implementation_plan.json").write_text('{"other_key": "value"}')
+
+        mock_collect.return_value = None
+
+        # Should handle the missing key gracefully
+        handle_followup_command(temp_dir, spec_dir, "sonnet")
+
+        captured = capsys.readouterr()
+        assert "complete" in captured.out.lower()
+
+    @patch('cli.utils.validate_environment', return_value=True)
+    @patch('agent.run_followup_planner', new_callable=AsyncMock)
+    @patch('cli.followup_commands.is_build_complete', return_value=True)
+    @patch('cli.followup_commands.collect_followup_task')
+    def test_handles_phase_with_missing_name_key(
+        self,
+        mock_collect,
+        mock_is_complete,
+        mock_run_planner,
+        mock_validate,
+        temp_dir,
+        capsys
+    ):
+        """Handles phase dict without 'name' key (lines 296-297)."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+        (spec_dir / "spec.md").write_text("# Test")
+
+        # Write JSON with phase missing 'name' key
+        (spec_dir / "implementation_plan.json").write_text('{"phases": [{"other_key": "value"}, {"name": "Valid Phase"}]}')
+
+        mock_collect.return_value = None
+
+        # Should handle missing name gracefully (uses .get() with default)
+        handle_followup_command(temp_dir, spec_dir, "sonnet")
+
+        captured = capsys.readouterr()
+        assert "complete" in captured.out.lower()
+
+    @patch('cli.utils.validate_environment', return_value=True)
+    @patch('agent.run_followup_planner', new_callable=AsyncMock)
+    @patch('cli.followup_commands.is_build_complete', return_value=True)
+    @patch('cli.followup_commands.collect_followup_task')
+    def test_handles_empty_phases_in_plan(
+        self,
+        mock_collect,
+        mock_is_complete,
+        mock_run_planner,
+        mock_validate,
+        temp_dir,
+        capsys
+    ):
+        """Handles empty phases array in implementation plan (lines 296-297)."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+        (spec_dir / "spec.md").write_text("# Test")
+
+        # Write JSON with empty phases array
+        (spec_dir / "implementation_plan.json").write_text('{"phases": []}')
+
+        mock_collect.return_value = None
+
+        handle_followup_command(temp_dir, spec_dir, "sonnet")
+
+        captured = capsys.readouterr()
+        assert "complete" in captured.out.lower()
+
+
+
+class TestCollectFollowupTaskEdgeCases:
+    """Additional edge case tests for collect_followup_task()."""
+
+    def test_handles_file_with_only_whitespace(self, temp_dir, capsys):
+        """Handles file that contains only whitespace characters."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        # Create file with only whitespace
+        task_file = temp_dir / "whitespace.txt"
+        task_file.write_text("   \n\n\t\n   ")
+
+        with patch('cli.followup_commands.select_menu', side_effect=['file', 'quit']):
+            with patch('builtins.input', return_value=str(task_file)):
+                result = collect_followup_task(spec_dir)
+
+        assert result is None
+        captured = capsys.readouterr()
+        # .strip() would make the content empty, triggering the empty file message
+        assert "empty" in captured.out.lower() or "cancel" in captured.out.lower()
+
+    def test_handles_file_with_newline_only_content(self, temp_dir, capsys):
+        """Handles file that contains only newlines."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        # Create file with only newlines
+        task_file = temp_dir / "newlines.txt"
+        task_file.write_text("\n\n\n")
+
+        with patch('cli.followup_commands.select_menu', side_effect=['file', 'quit']):
+            with patch('builtins.input', return_value=str(task_file)):
+                result = collect_followup_task(spec_dir)
+
+        assert result is None
+
+    def test_handles_file_read_with_os_error(self, temp_dir, capsys):
+        """Handles OSError when reading file."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        task_file = temp_dir / "task.txt"
+        task_file.write_text("Content")
+
+        with patch('cli.followup_commands.select_menu', side_effect=['file', 'quit']):
+            with patch('builtins.input', return_value=str(task_file)):
+                with patch('pathlib.Path.read_text', side_effect=OSError("OS error reading file")):
+                    result = collect_followup_task(spec_dir)
+
+        assert result is None
+        captured = capsys.readouterr()
+        assert "error" in captured.out.lower()
+
+    def test_handles_value_error_on_file_path(self, temp_dir, capsys):
+        """Handles ValueError during file path resolution."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        with patch('cli.followup_commands.select_menu', side_effect=['file', 'quit']):
+            with patch('builtins.input', return_value='/valid/path'):
+                # Mock resolve to raise ValueError
+                with patch('pathlib.Path.resolve', side_effect=ValueError("Invalid path")):
+                    result = collect_followup_task(spec_dir)
+
+        # Should handle gracefully and return None or retry
+        assert result is None
+
+    def test_handles_type_input_with_trailing_whitespace(self, temp_dir):
+        """Properly strips trailing whitespace from typed input."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        task_description = "Task content with trailing spaces   "
+
+        with patch('cli.followup_commands.select_menu', return_value='type'):
+            with patch('builtins.input', side_effect=[task_description, '']):
+                result = collect_followup_task(spec_dir)
+
+        assert result is not None
+        # Should be stripped
+        assert result == "Task content with trailing spaces"
+
+    def test_handles_type_input_with_internal_whitespace(self, temp_dir):
+        """Preserves internal whitespace in typed input."""
+        spec_dir = temp_dir / ".auto-claude" / "specs" / "001-test"
+        spec_dir.mkdir(parents=True)
+
+        # Note: empty line terminates input, so we need non-empty lines only
+        # Then a final empty line to signal completion
+        with patch('cli.followup_commands.select_menu', return_value='type'):
+            with patch('builtins.input', side_effect=["Line 1", "Line 2", "  Line 3", '']):
+                result = collect_followup_task(spec_dir)
+
+        assert result is not None
+        assert "Line 1" in result
+        assert "Line 2" in result
+        assert "Line 3" in result
+
+
+# =============================================================================
+# TESTS: Module-level path insertion (line 16)
+# =============================================================================
+
+
+class TestFollowupCommandsModuleImport:
+    """Tests for covering module-level path insertion (line 16)."""
+
+    def test_module_import_executes_path_insertion(self):
+        """Module import executes sys.path.insert (line 16)."""
+        # Get the module path and parent directory
+        import cli.followup_commands as followup_module
+        module_path = followup_module.__file__
+        parent_dir = str(Path(module_path).parent.parent)
+
+        # Save original sys.path
+        original_path = sys.path.copy()
+
+        # Remove the parent directory from sys.path to make the condition True
+        while parent_dir in sys.path:
+            sys.path.remove(parent_dir)
+
+        # Remove module and its submodules from sys.modules to force re-import
+        modules_to_remove = [k for k in sys.modules.keys() if k.startswith('cli.followup_commands')]
+        for mod_name in modules_to_remove:
+            del sys.modules[mod_name]
+
+        # Now import it fresh - this should execute line 16 under coverage
+        import importlib.util
+        spec = importlib.util.spec_from_file_location("cli.followup_commands", module_path)
+        module = importlib.util.module_from_spec(spec)
+        sys.modules['cli.followup_commands'] = module
+        spec.loader.exec_module(module)
+
+        # Verify the module loaded correctly
+        assert hasattr(module, 'handle_followup_command')
+
+        # Restore original sys.path
+        sys.path[:] = original_path