hotfix(ci): install libarchive-tools for Linux package verification

The verify:linux step requires bsdtar (from libarchive-tools) to verify
AppImage contents. This was missing from the CI runners, causing beta
releases to fail with "bsdtar not available" error.

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

.github/workflows/beta-release.yml

@@ -405,11 +405,11 @@ jobs:
       - name: Setup Node.js and install dependencies
         uses: ./.github/actions/setup-node-frontend
 
-      - name: Setup Flatpak
+      - name: Setup Flatpak and verification tools
         run: |
           set -e
           sudo apt-get update
-          sudo apt-get install -y flatpak flatpak-builder
+          sudo apt-get install -y flatpak flatpak-builder libarchive-tools
           flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
           flatpak install -y --user flathub org.freedesktop.Platform//25.08 org.freedesktop.Sdk//25.08
           flatpak install -y --user flathub org.electronjs.Electron2.BaseApp//25.08
@@ -447,6 +447,9 @@ jobs:
           SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
           SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
 
+      - name: Verify Linux packages
+        run: cd apps/frontend && npm run verify:linux
+
       - name: Upload artifacts
         uses: actions/upload-artifact@v4
         with:

.github/workflows/release.yml

@@ -344,10 +344,10 @@ jobs:
       - name: Setup Node.js and install dependencies
         uses: ./.github/actions/setup-node-frontend
 
-      - name: Setup Flatpak
+      - name: Setup Flatpak and verification tools
         run: |
           sudo apt-get update
-          sudo apt-get install -y flatpak flatpak-builder
+          sudo apt-get install -y flatpak flatpak-builder libarchive-tools
           flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
           flatpak install -y --user flathub org.freedesktop.Platform//25.08 org.freedesktop.Sdk//25.08
           flatpak install -y --user flathub org.electronjs.Electron2.BaseApp//25.08
@@ -383,6 +383,9 @@ jobs:
           SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
           SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}
 
+      - name: Verify Linux packages
+        run: cd apps/frontend && npm run verify:linux
+
       - name: Upload artifacts
         uses: actions/upload-artifact@v4
         with:

.gitignore

@@ -174,3 +174,4 @@ OPUS_ANALYSIS_AND_IDEAS.md
 /shared_docs
 logs/security/
 Agents.md
+packages/

README.md

@@ -35,18 +35,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.2--beta.10-orange?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.2-beta.10)
+[![Beta](https://img.shields.io/badge/beta-2.7.6--beta.1-orange?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.6-beta.1)
 <!-- BETA_VERSION_BADGE_END -->
 
 <!-- BETA_DOWNLOADS -->
 | Platform | Download |
 |----------|----------|
-| **Windows** | [Auto-Claude-2.7.2-beta.10-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-win32-x64.exe) |
-| **macOS (Apple Silicon)** | [Auto-Claude-2.7.2-beta.10-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-darwin-arm64.dmg) |
-| **macOS (Intel)** | [Auto-Claude-2.7.2-beta.10-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-darwin-x64.dmg) |
-| **Linux** | [Auto-Claude-2.7.2-beta.10-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-linux-x86_64.AppImage) |
-| **Linux (Debian)** | [Auto-Claude-2.7.2-beta.10-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-linux-amd64.deb) |
-| **Linux (Flatpak)** | [Auto-Claude-2.7.2-beta.10-linux-x86_64.flatpak](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-linux-x86_64.flatpak) |
+| **Windows** | [Auto-Claude-2.7.6-beta.1-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.1/Auto-Claude-2.7.6-beta.1-win32-x64.exe) |
+| **macOS (Apple Silicon)** | [Auto-Claude-2.7.6-beta.1-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.1/Auto-Claude-2.7.6-beta.1-darwin-arm64.dmg) |
+| **macOS (Intel)** | [Auto-Claude-2.7.6-beta.1-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.1/Auto-Claude-2.7.6-beta.1-darwin-x64.dmg) |
+| **Linux** | [Auto-Claude-2.7.6-beta.1-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.1/Auto-Claude-2.7.6-beta.1-linux-x86_64.AppImage) |
+| **Linux (Debian)** | [Auto-Claude-2.7.6-beta.1-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.1/Auto-Claude-2.7.6-beta.1-linux-amd64.deb) |
+| **Linux (Flatpak)** | [Auto-Claude-2.7.6-beta.1-linux-x86_64.flatpak](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.1/Auto-Claude-2.7.6-beta.1-linux-x86_64.flatpak) |
 <!-- BETA_DOWNLOADS_END -->
 
 > All releases include SHA256 checksums and VirusTotal scan results for security verification.

apps/backend/INVESTIGATION.md

@@ -1,421 +0,0 @@
-# Token Encryption Investigation
-
-## Issue Summary
-
-Auto-Claude users are experiencing API 401 errors ("Invalid bearer token") because the Python backend is passing encrypted tokens (with `enc:` prefix) directly to the Claude Agent SDK without decryption. Standalone Claude Code terminals work correctly because they decrypt these tokens before use.
-
-**Key insight from user thehaffk:** "python cant unencrypt claude token and it launches session with CLAUDE_CODE_OAUTH_TOKEN=enc:djEwtxMGISt3tQ..."
-
-## Token Storage Format
-
-### Encrypted Token Format
-
-Claude Code CLI stores OAuth tokens in an encrypted format with the prefix `enc:`:
-
-```text
-enc:djEwtxMGISt3tQ...
-```
-
-This format is used when tokens are stored in:
-- **macOS**: Keychain (service: "Claude Code-credentials")
-- **Linux**: Secret Service API (DBus, via secretstorage library)
-- **Windows**: Credential Manager / .credentials.json files
-
-### Decrypted Token Format
-
-Valid Claude OAuth tokens have the format:
-```text
-sk-ant-oat01-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-```
-
-## Current Token Flow (BROKEN)
-
-1. **Token Storage**: Claude Code CLI stores encrypted token with `enc:` prefix in system keychain
-2. **Token Retrieval**: `apps/backend/core/auth.py::get_auth_token()` retrieves token from:
-   - Environment variable `CLAUDE_CODE_OAUTH_TOKEN`
-   - OR system keychain via `get_token_from_keychain()`
-3. **❌ NO DECRYPTION**: Token is returned as-is with `enc:` prefix intact
-4. **SDK Initialization**: Encrypted token passed to Claude Agent SDK
-5. **API Call Fails**: SDK sends encrypted token to API → 401 error
-
-### Proof of Broken Flow
-
-Test in `apps/backend`:
-```python
-import os
-os.environ['CLAUDE_CODE_OAUTH_TOKEN'] = 'enc:test123'
-
-from core.auth import get_auth_token
-token = get_auth_token()
-print(f"Token: {token}")  # Output: "enc:test123"
-print(f"Encrypted: {token.startswith('enc:')}")  # Output: True
-```
-
-## How Standalone Claude Code CLI Handles Tokens
-
-### Current Understanding
-
-1. **Token Detection**: CLI checks if token starts with `enc:` prefix
-2. **Decryption**: If encrypted, CLI decrypts using platform-specific keyring access
-3. **Authentication**: Decrypted `sk-ant-oat01-` token is used for API calls
-
-### Missing Documentation
-
-Web search for "Claude Code CLI encrypted token enc: prefix decryption" found:
-- Token storage formats (JSON with accessToken, refreshToken, expiresAt)
-- Security issues (tokens exposed in debug logs before v2.1.0)
-- Keychain access patterns for macOS/Linux/Windows
-
-**❌ NOT FOUND**: Specific documentation on how Claude Code CLI decrypts `enc:` tokens
-
-Sources:
-- [Claude Code CLI over SSH on macOS: Fixing Keychain Access](https://phoenixtrap.com/2025/10/26/claude-code-cli-over-ssh-on-macos-fixing-keychain-access/)
-- [Identity and Access Management - Claude Code Docs](https://code.claude.com/docs/en/iam)
-- [Claude Code sessions should be encrypted | yoav.blog](https://yoav.blog/2026/01/09/claude-code-sessions-should-be-encrypted/)
-
-## Decryption Approach Options
-
-### Option 1: Claude Agent SDK Built-in Decryption
-
-**Status**: NEEDS VERIFICATION
-
-The Claude Agent SDK (`claude-agent-sdk>=0.1.19`) may handle decryption internally if:
-- Token is passed to SDK still encrypted
-- SDK detects `enc:` prefix
-- SDK has access to system keyring for decryption
-
-**Action Required**: Check if SDK has decryption capabilities by examining:
-- SDK source code or documentation
-- Whether SDK expects encrypted vs decrypted tokens
-- If SDK requires specific environment variables for decryption
-
-### Option 2: Python Backend Decryption (Recommended)
-
-**Approach**: Implement decryption in `apps/backend/core/auth.py` before passing to SDK
-
-**Implementation Pattern**:
-```python
-def get_auth_token() -> str | None:
-    """Get authentication token (decrypted if necessary)."""
-    token = _retrieve_token_from_sources()  # From env or keychain
-
-    if token and token.startswith("enc:"):
-        # Decrypt the token
-        token = decrypt_token(token)
-
-    return token
-
-def decrypt_token(encrypted_token: str) -> str:
-    """
-    Decrypt Claude Code encrypted token.
-
-    Args:
-        encrypted_token: Token with 'enc:' prefix
-
-    Returns:
-        Decrypted token in format 'sk-ant-oat01-...'
-    """
-    # Remove 'enc:' prefix
-    encrypted_data = encrypted_token[4:]
-
-    # TODO: Implement decryption logic
-    # Questions to answer:
-    # 1. What encryption algorithm does Claude Code use?
-    # 2. Where is the decryption key stored?
-    # 3. Is the decryption key platform-specific (per-user)?
-    # 4. Can we reuse Claude Code's decryption mechanism?
-
-    raise NotImplementedError("Token decryption not yet implemented")
-```
-
-### Option 3: Call Claude Code CLI for Decryption
-
-**Approach**: Use the Claude Code CLI binary to decrypt tokens
-
-```python
-def decrypt_token(encrypted_token: str) -> str:
-    """Decrypt token by invoking Claude Code CLI."""
-    # Find claude binary
-    claude_path = shutil.which("claude") or "~/.local/bin/claude"
-
-    # Use CLI command to get decrypted token
-    # (if such a command exists - needs research)
-    result = subprocess.run(
-        [claude_path, "auth", "decrypt", encrypted_token],
-        capture_output=True,
-        text=True
-    )
-
-    return result.stdout.strip()
-```
-
-**Issues**:
-- Requires Claude Code CLI to be installed
-- No documented CLI command for token decryption
-- Adds external dependency
-
-## Required Investigation Steps
-
-### 1. Verify SDK Decryption Capabilities
-
-**Task**: Check if `claude-agent-sdk` handles `enc:` tokens automatically
-
-**Method**:
-```bash
-# In environment with SDK installed
-python3 << 'EOF'
-import os
-os.environ['CLAUDE_CODE_OAUTH_TOKEN'] = 'enc:...'  # Real encrypted token
-
-from claude_agent_sdk import Client
-# Try creating client - does it decrypt internally?
-client = Client()
-# Check if authentication works
-EOF
-```
-
-### 2. Reverse Engineer Claude Code CLI Decryption
-
-**Task**: Understand how Claude CLI decrypts tokens
-
-**Method**:
-- Examine Claude CLI binary (if possible)
-- Trace system calls when CLI runs (strace on Linux, dtruss on macOS)
-- Check if CLI accesses specific keychain entries for decryption keys
-- Look for encryption/decryption libraries used by CLI
-
-### 3. Find Decryption Key Storage
-
-**Task**: Locate where decryption keys are stored
-
-**Hypothesis**: Decryption key stored in:
-- macOS: Keychain (separate entry from encrypted token)
-- Linux: Secret Service API
-- Windows: Credential Manager
-
-**Verification**:
-```bash
-# macOS: List all keychain entries
-security find-generic-password -a "$(whoami)" | grep -i claude
-
-# Linux: Use secretstorage to list all items
-python3 -c "import secretstorage; ..."
-```
-
-## Recommended Decryption Approach for Python Backend
-
-Based on investigation so far, the recommended approach is:
-
-1. **Detect encrypted tokens**: Check for `enc:` prefix in `get_auth_token()`
-2. **Decrypt before use**: Implement `decrypt_token()` function
-3. **Platform-specific decryption**: Use appropriate keyring library:
-   - macOS: Use `subprocess` with `/usr/bin/security` to access decryption key
-   - Linux: Use `secretstorage` library to access Secret Service API
-   - Windows: Access Credential Manager or credentials.json
-4. **Backward compatibility**: Support both encrypted and plaintext tokens
-5. **Error handling**: Provide clear error messages if decryption fails
-
-## Complete Token Flow Trace (Frontend → Backend)
-
-### 1. Token Retrieval (Frontend)
-
-**File**: `apps/frontend/src/main/services/profile-service.ts`
-
-The frontend retrieves the OAuth token from the system keychain but **does not decrypt it**. When no API profile is active (OAuth mode), the frontend returns an empty environment object, which means it relies on:
-- The token already being in the environment as `CLAUDE_CODE_OAUTH_TOKEN`
-- OR the Python backend retrieving it from the keychain
-
-**Key Code**:
-```typescript
-// Line 223: Returns empty object in OAuth mode, allowing
-// CLAUDE_CODE_OAUTH_TOKEN to be used from system keychain
-```
-
-### 2. Environment Variable Passing (Frontend → PTY)
-
-**File**: `apps/frontend/src/main/terminal/pty-manager.ts`
-
-The PTY manager spawns the terminal shell with environment variables, including `CLAUDE_CODE_OAUTH_TOKEN`:
-
-**Key Code** (Lines 149-152):
-```typescript
-// Remove ANTHROPIC_API_KEY to ensure Claude Code uses OAuth tokens
-// (CLAUDE_CODE_OAUTH_TOKEN from profileEnv) instead of API keys
-const { DEBUG: _DEBUG, ANTHROPIC_API_KEY: _ANTHROPIC_API_KEY, ...cleanEnv } = process.env;
-```
-
-**Important**: The frontend passes through whatever token value exists in the environment - it does NOT check for `enc:` prefix or decrypt it.
-
-### 3. Token Retrieval (Backend)
-
-**File**: `apps/backend/core/auth.py`
-
-#### 3.1. get_auth_token()
-
-This function retrieves the token from multiple sources:
-
-```python
-def get_auth_token() -> str | None:
-    # First check environment variables
-    for var in AUTH_TOKEN_ENV_VARS:  # CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_AUTH_TOKEN
-        token = os.environ.get(var)
-        if token:
-            return token  # ❌ Returns immediately without checking for enc: prefix
-
-    # Fallback to system credential store
-    return get_token_from_keychain()  # ❌ Also returns without decryption
-```
-
-**Issue**: Returns token as-is with `enc:` prefix intact.
-
-#### 3.2. require_auth_token()
-
-This function calls `get_auth_token()` and raises an error if no token is found:
-
-```python
-def require_auth_token() -> str:
-    token = get_auth_token()  # ❌ Gets encrypted token
-    if not token:
-        raise ValueError("No OAuth token found...")
-    return token  # ❌ Returns encrypted token
-```
-
-**Issue**: No decryption step between retrieval and return.
-
-#### 3.3. ensure_claude_code_oauth_token()
-
-This function ensures the environment variable is set:
-
-```python
-def ensure_claude_code_oauth_token() -> None:
-    if os.environ.get("CLAUDE_CODE_OAUTH_TOKEN"):
-        return
-
-    token = get_auth_token()  # ❌ Gets encrypted token
-    if token:
-        os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = token  # ❌ Sets encrypted token
-```
-
-**Issue**: Propagates encrypted token to environment variable.
-
-### 4. Token Usage in SDK Client Creation (Backend)
-
-#### 4.1. Full Client Creation
-
-**File**: `apps/backend/core/client.py` (see `create_client()` function)
-
-```python
-def create_client(...):
-    oauth_token = require_auth_token()  # ❌ Gets encrypted token
-    # Ensure SDK can access it via its expected env var
-    os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = oauth_token  # ❌ Sets encrypted token
-```
-
-**Issue**: Encrypted token is passed to the Claude Agent SDK, which expects a decrypted `sk-ant-oat01-` token.
-
-#### 4.2. Simple Client Creation
-
-**File**: `apps/backend/core/simple_client.py` (see `create_simple_client()` function)
-
-```python
-def create_simple_client(...):
-    # Get authentication
-    oauth_token = require_auth_token()  # ❌ Gets encrypted token
-    import os
-    os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = oauth_token  # ❌ Sets encrypted token
-```
-
-**Issue**: Same problem - encrypted token passed to SDK.
-
-#### 4.3. Other Usages
-
-**Files**:
-- `apps/backend/core/workspace.py` (Line 1966) - AI merge operations
-- `apps/backend/runners/insights_runner.py` - Insights analysis
-- `apps/backend/runners/github/batch_issues.py` - GitHub batch operations
-- `apps/backend/integrations/linear/updater.py` - Linear integration
-- `apps/backend/commit_message.py` - Commit message generation
-- `apps/backend/analysis/insight_extractor.py` - Code insights
-- `apps/backend/merge/ai_resolver/claude_client.py` - Merge resolution
-
-**All follow the same pattern**: Call `ensure_claude_code_oauth_token()` → encrypted token in environment → SDK receives encrypted token → API 401 error.
-
-### 5. Where Decryption Should Be Inserted
-
-Based on the flow analysis, decryption should be added at **the earliest point of token retrieval** to avoid duplicating decryption logic:
-
-**RECOMMENDED INSERTION POINT**: `apps/backend/core/auth.py::get_auth_token()`
-
-```python
-def get_auth_token() -> str | None:
-    # First check environment variables
-    for var in AUTH_TOKEN_ENV_VARS:
-        token = os.environ.get(var)
-        if token:
-            # ✅ INSERT DECRYPTION HERE
-            if token.startswith("enc:"):
-                token = decrypt_token(token)
-            return token
-
-    # Fallback to system credential store
-    token = get_token_from_keychain()
-    # ✅ ALSO DECRYPT KEYCHAIN TOKENS
-    if token and token.startswith("enc:"):
-        token = decrypt_token(token)
-    return token
-```
-
-**Benefits of this approach**:
-1. Single location for decryption logic
-2. All downstream functions automatically get decrypted tokens
-3. Backward compatible (plaintext tokens pass through unchanged)
-4. Consistent behavior across all token sources (env vars and keychain)
-
-**Alternative insertion points** (NOT recommended):
-- `require_auth_token()` - Would need similar logic in `get_auth_token()` for non-required usage
-- `create_client()` - Would need duplication in `create_simple_client()` and all other clients
-- `ensure_claude_code_oauth_token()` - Would miss direct `get_auth_token()` calls
-
-## Next Steps
-
-1. ✅ Document current token flow and identify issue (THIS FILE - COMPLETED)
-2. ✅ Trace token flow from frontend to backend (THIS FILE - COMPLETED)
-3. ✅ Identify where decryption should be inserted (THIS FILE - COMPLETED)
-4. ⏳ Verify if Claude Agent SDK handles decryption internally
-5. ⏳ Reverse engineer or document Claude Code CLI decryption mechanism
-6. ⏳ Implement `decrypt_token()` function in `apps/backend/core/auth.py`
-7. ⏳ Add encryption detection and auto-decryption to `get_auth_token()`
-8. ⏳ Test with real encrypted tokens on macOS and Linux
-9. ⏳ Add comprehensive error handling for decryption failures
-
-## Open Questions
-
-1. **What encryption algorithm does Claude Code use for `enc:` tokens?**
-   - Possible: AES-256, ChaCha20, or similar
-   - Key derivation method?
-
-2. **Where is the decryption key stored?**
-   - Same keychain entry as encrypted token?
-   - Separate keychain entry?
-   - Derived from system/user credentials?
-
-3. **Does Claude Agent SDK expect encrypted or decrypted tokens?**
-   - If it expects decrypted: we must decrypt before passing
-   - If it handles encryption: we may be missing SDK configuration
-
-4. **Is there a Claude Code CLI command to decrypt tokens?**
-   - `claude auth decrypt <token>`?
-   - `claude auth get-token`?
-   - No documented command found in research
-
-5. **Can we reuse Claude Code's decryption mechanism?**
-   - Import decryption functions from CLI?
-   - Call CLI as subprocess?
-   - Implement decryption ourselves?
-
-## References
-
-- Issue: [GitHub #1223: API Error 401](https://github.com/AndyMik90/Auto-Claude/issues/1223)
-- Current auth implementation: `apps/backend/core/auth.py`
-- SDK client initialization: `apps/backend/core/client.py`
-- Requirements: `apps/backend/requirements.txt` (includes `secretstorage>=3.3.3` for Linux)

apps/backend/__init__.py

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

apps/backend/agents/base.py

@@ -13,3 +13,10 @@ logger = logging.getLogger(__name__)
 # Configuration constants
 AUTO_CONTINUE_DELAY_SECONDS = 3
 HUMAN_INTERVENTION_FILE = "PAUSE"
+
+# Retry configuration for 400 tool concurrency errors
+MAX_CONCURRENCY_RETRIES = 5  # Maximum number of retries for tool concurrency errors
+INITIAL_RETRY_DELAY_SECONDS = (
+    2  # Initial retry delay (doubles each retry: 2s, 4s, 8s, 16s, 32s)
+)
+MAX_RETRY_DELAY_SECONDS = 32  # Cap retry delay at 32 seconds

apps/backend/agents/planner.py

@@ -1,183 +1,183 @@
-"""
-Planner Agent Module
-====================
-
-Handles follow-up planner sessions for adding new subtasks to completed specs.
-"""
-
-import logging
-from pathlib import Path
-
-from core.client import create_client
-from phase_config import get_phase_model, get_phase_thinking_budget
-from phase_event import ExecutionPhase, emit_phase
-from task_logger import (
-    LogPhase,
-    get_task_logger,
-)
-from ui import (
-    BuildState,
-    Icons,
-    StatusManager,
-    bold,
-    box,
-    highlight,
-    icon,
-    muted,
-    print_status,
-)
-
-from .session import run_agent_session
-
-logger = logging.getLogger(__name__)
-
-
-async def run_followup_planner(
-    project_dir: Path,
-    spec_dir: Path,
-    model: str,
-    verbose: bool = False,
-) -> bool:
-    """
-    Run the follow-up planner to add new subtasks to a completed spec.
-
-    This is a simplified version of run_autonomous_agent that:
-    1. Creates a client
-    2. Loads the followup planner prompt
-    3. Runs a single planning session
-    4. Returns after the plan is updated (doesn't enter coding loop)
-
-    The planner agent will:
-    - Read FOLLOWUP_REQUEST.md for the new task
-    - Read the existing implementation_plan.json
-    - Add new phase(s) with pending subtasks
-    - Update the plan status back to in_progress
-
-    Args:
-        project_dir: Root directory for the project
-        spec_dir: Directory containing the completed spec
-        model: Claude model to use
-        verbose: Whether to show detailed output
-
-    Returns:
-        bool: True if planning completed successfully
-    """
-    from implementation_plan import ImplementationPlan
-    from prompts import get_followup_planner_prompt
-
-    # Initialize status manager for ccstatusline
-    status_manager = StatusManager(project_dir)
-    status_manager.set_active(spec_dir.name, BuildState.PLANNING)
-    emit_phase(ExecutionPhase.PLANNING, "Follow-up planning")
-
-    # Initialize task logger for persistent logging
-    task_logger = get_task_logger(spec_dir)
-
-    # Show header
-    content = [
-        bold(f"{icon(Icons.GEAR)} FOLLOW-UP PLANNER SESSION"),
-        "",
-        f"Spec: {highlight(spec_dir.name)}",
-        muted("Adding follow-up work to completed spec."),
-        "",
-        muted("The agent will read your FOLLOWUP_REQUEST.md and add new subtasks."),
-    ]
-    print()
-    print(box(content, width=70, style="heavy"))
-    print()
-
-    # Start planning phase in task logger
-    if task_logger:
-        task_logger.start_phase(LogPhase.PLANNING, "Starting follow-up planning...")
-        task_logger.set_session(1)
-
-    # Create client with phase-specific model and thinking budget
-    # Respects task_metadata.json configuration when no CLI override
-    planning_model = get_phase_model(spec_dir, "planning", model)
-    planning_thinking_budget = get_phase_thinking_budget(spec_dir, "planning")
-    client = create_client(
-        project_dir,
-        spec_dir,
-        planning_model,
-        max_thinking_tokens=planning_thinking_budget,
-    )
-
-    # Generate follow-up planner prompt
-    prompt = get_followup_planner_prompt(spec_dir)
-
-    print_status("Running follow-up planner...", "progress")
-    print()
-
-    try:
-        # Run single planning session
-        async with client:
-            status, response = await run_agent_session(
-                client, prompt, spec_dir, verbose, phase=LogPhase.PLANNING
-            )
-
-        # End planning phase in task logger
-        if task_logger:
-            task_logger.end_phase(
-                LogPhase.PLANNING,
-                success=(status != "error"),
-                message="Follow-up planning session completed",
-            )
-
-        if status == "error":
-            print()
-            print_status("Follow-up planning failed", "error")
-            status_manager.update(state=BuildState.ERROR)
-            return False
-
-        # Verify the plan was updated (should have pending subtasks now)
-        plan_file = spec_dir / "implementation_plan.json"
-        if plan_file.exists():
-            plan = ImplementationPlan.load(plan_file)
-
-            # Check if there are any pending subtasks
-            all_subtasks = [c for p in plan.phases for c in p.subtasks]
-            pending_subtasks = [c for c in all_subtasks if c.status.value == "pending"]
-
-            if pending_subtasks:
-                # Reset the plan status to in_progress (in case planner didn't)
-                plan.reset_for_followup()
-                await plan.async_save(plan_file)
-
-                print()
-                content = [
-                    bold(f"{icon(Icons.SUCCESS)} FOLLOW-UP PLANNING COMPLETE"),
-                    "",
-                    f"New pending subtasks: {highlight(str(len(pending_subtasks)))}",
-                    f"Total subtasks: {len(all_subtasks)}",
-                    "",
-                    muted("Next steps:"),
-                    f"  Run: {highlight(f'python auto-claude/run.py --spec {spec_dir.name}')}",
-                ]
-                print(box(content, width=70, style="heavy"))
-                print()
-                status_manager.update(state=BuildState.PAUSED)
-                return True
-            else:
-                print()
-                print_status(
-                    "Warning: No pending subtasks found after planning", "warning"
-                )
-                print(muted("The planner may not have added new subtasks."))
-                print(muted("Check implementation_plan.json manually."))
-                status_manager.update(state=BuildState.PAUSED)
-                return False
-        else:
-            print()
-            print_status(
-                "Error: implementation_plan.json not found after planning", "error"
-            )
-            status_manager.update(state=BuildState.ERROR)
-            return False
-
-    except Exception as e:
-        print()
-        print_status(f"Follow-up planning error: {e}", "error")
-        if task_logger:
-            task_logger.log_error(f"Follow-up planning error: {e}", LogPhase.PLANNING)
-        status_manager.update(state=BuildState.ERROR)
-        return False
+"""
+Planner Agent Module
+====================
+
+Handles follow-up planner sessions for adding new subtasks to completed specs.
+"""
+
+import logging
+from pathlib import Path
+
+from core.client import create_client
+from phase_config import get_phase_model, get_phase_thinking_budget
+from phase_event import ExecutionPhase, emit_phase
+from task_logger import (
+    LogPhase,
+    get_task_logger,
+)
+from ui import (
+    BuildState,
+    Icons,
+    StatusManager,
+    bold,
+    box,
+    highlight,
+    icon,
+    muted,
+    print_status,
+)
+
+from .session import run_agent_session
+
+logger = logging.getLogger(__name__)
+
+
+async def run_followup_planner(
+    project_dir: Path,
+    spec_dir: Path,
+    model: str,
+    verbose: bool = False,
+) -> bool:
+    """
+    Run the follow-up planner to add new subtasks to a completed spec.
+
+    This is a simplified version of run_autonomous_agent that:
+    1. Creates a client
+    2. Loads the followup planner prompt
+    3. Runs a single planning session
+    4. Returns after the plan is updated (doesn't enter coding loop)
+
+    The planner agent will:
+    - Read FOLLOWUP_REQUEST.md for the new task
+    - Read the existing implementation_plan.json
+    - Add new phase(s) with pending subtasks
+    - Update the plan status back to in_progress
+
+    Args:
+        project_dir: Root directory for the project
+        spec_dir: Directory containing the completed spec
+        model: Claude model to use
+        verbose: Whether to show detailed output
+
+    Returns:
+        bool: True if planning completed successfully
+    """
+    from implementation_plan import ImplementationPlan
+    from prompts import get_followup_planner_prompt
+
+    # Initialize status manager for ccstatusline
+    status_manager = StatusManager(project_dir)
+    status_manager.set_active(spec_dir.name, BuildState.PLANNING)
+    emit_phase(ExecutionPhase.PLANNING, "Follow-up planning")
+
+    # Initialize task logger for persistent logging
+    task_logger = get_task_logger(spec_dir)
+
+    # Show header
+    content = [
+        bold(f"{icon(Icons.GEAR)} FOLLOW-UP PLANNER SESSION"),
+        "",
+        f"Spec: {highlight(spec_dir.name)}",
+        muted("Adding follow-up work to completed spec."),
+        "",
+        muted("The agent will read your FOLLOWUP_REQUEST.md and add new subtasks."),
+    ]
+    print()
+    print(box(content, width=70, style="heavy"))
+    print()
+
+    # Start planning phase in task logger
+    if task_logger:
+        task_logger.start_phase(LogPhase.PLANNING, "Starting follow-up planning...")
+        task_logger.set_session(1)
+
+    # Create client with phase-specific model and thinking budget
+    # Respects task_metadata.json configuration when no CLI override
+    planning_model = get_phase_model(spec_dir, "planning", model)
+    planning_thinking_budget = get_phase_thinking_budget(spec_dir, "planning")
+    client = create_client(
+        project_dir,
+        spec_dir,
+        planning_model,
+        max_thinking_tokens=planning_thinking_budget,
+    )
+
+    # Generate follow-up planner prompt
+    prompt = get_followup_planner_prompt(spec_dir)
+
+    print_status("Running follow-up planner...", "progress")
+    print()
+
+    try:
+        # Run single planning session
+        async with client:
+            status, response, error_info = await run_agent_session(
+                client, prompt, spec_dir, verbose, phase=LogPhase.PLANNING
+            )
+
+        # End planning phase in task logger
+        if task_logger:
+            task_logger.end_phase(
+                LogPhase.PLANNING,
+                success=(status != "error"),
+                message="Follow-up planning session completed",
+            )
+
+        if status == "error":
+            print()
+            print_status("Follow-up planning failed", "error")
+            status_manager.update(state=BuildState.ERROR)
+            return False
+
+        # Verify the plan was updated (should have pending subtasks now)
+        plan_file = spec_dir / "implementation_plan.json"
+        if plan_file.exists():
+            plan = ImplementationPlan.load(plan_file)
+
+            # Check if there are any pending subtasks
+            all_subtasks = [c for p in plan.phases for c in p.subtasks]
+            pending_subtasks = [c for c in all_subtasks if c.status.value == "pending"]
+
+            if pending_subtasks:
+                # Reset the plan status to in_progress (in case planner didn't)
+                plan.reset_for_followup()
+                await plan.async_save(plan_file)
+
+                print()
+                content = [
+                    bold(f"{icon(Icons.SUCCESS)} FOLLOW-UP PLANNING COMPLETE"),
+                    "",
+                    f"New pending subtasks: {highlight(str(len(pending_subtasks)))}",
+                    f"Total subtasks: {len(all_subtasks)}",
+                    "",
+                    muted("Next steps:"),
+                    f"  Run: {highlight(f'python auto-claude/run.py --spec {spec_dir.name}')}",
+                ]
+                print(box(content, width=70, style="heavy"))
+                print()
+                status_manager.update(state=BuildState.PAUSED)
+                return True
+            else:
+                print()
+                print_status(
+                    "Warning: No pending subtasks found after planning", "warning"
+                )
+                print(muted("The planner may not have added new subtasks."))
+                print(muted("Check implementation_plan.json manually."))
+                status_manager.update(state=BuildState.PAUSED)
+                return False
+        else:
+            print()
+            print_status(
+                "Error: implementation_plan.json not found after planning", "error"
+            )
+            status_manager.update(state=BuildState.ERROR)
+            return False
+
+    except Exception as e:
+        print()
+        print_status(f"Follow-up planning error: {e}", "error")
+        if task_logger:
+            task_logger.log_error(f"Follow-up planning error: {e}", LogPhase.PLANNING)
+        status_manager.update(state=BuildState.ERROR)
+        return False

apps/backend/agents/pr_template_filler.py

@@ -0,0 +1,347 @@
+"""
+PR Template Filler Agent Module
+================================
+
+Detects GitHub PR templates in a project and uses Claude to intelligently
+fill them based on code changes, spec context, commit history, and branch info.
+"""
+
+import logging
+from pathlib import Path
+
+from core.client import create_client
+from task_logger import LogPhase, get_task_logger
+
+from .session import run_agent_session
+
+logger = logging.getLogger(__name__)
+
+# Maximum diff size (in characters) before truncating to file-level summaries
+MAX_DIFF_CHARS = 30_000
+
+
+def detect_pr_template(project_dir: Path | str) -> str | None:
+    """
+    Detect a GitHub PR template in the project.
+
+    Searches for:
+    1. .github/PULL_REQUEST_TEMPLATE.md (single template)
+    2. .github/PULL_REQUEST_TEMPLATE/ directory (picks the first .md file)
+
+    Args:
+        project_dir: Root directory of the project
+
+    Returns:
+        The template content as a string, or None if no template is found.
+    """
+    project_dir = Path(project_dir)
+    # Check for single template file
+    single_template = project_dir / ".github" / "PULL_REQUEST_TEMPLATE.md"
+    if single_template.is_file():
+        try:
+            content = single_template.read_text(encoding="utf-8")
+            if content.strip():
+                logger.info(f"Found PR template: {single_template}")
+                return content
+        except Exception as e:
+            logger.warning(f"Failed to read PR template {single_template}: {e}")
+
+    # Check for template directory (pick first .md file alphabetically)
+    template_dir = project_dir / ".github" / "PULL_REQUEST_TEMPLATE"
+    if template_dir.is_dir():
+        try:
+            md_files = sorted(template_dir.glob("*.md"))
+            if md_files:
+                content = md_files[0].read_text(encoding="utf-8")
+                if content.strip():
+                    logger.info(f"Found PR template: {md_files[0]}")
+                    return content
+        except Exception as e:
+            logger.warning(f"Failed to read PR template from {template_dir}: {e}")
+
+    logger.info("No GitHub PR template found in project")
+    return None
+
+
+def _truncate_diff(diff_summary: str) -> str:
+    """
+    Truncate a large diff to file-level summaries to stay within token limits.
+
+    If the diff is within MAX_DIFF_CHARS, return it unchanged.
+    Otherwise, extract only file-level change summaries (e.g. file names
+    with insertions/deletions counts) and discard line-level detail.
+
+    Args:
+        diff_summary: The full diff summary text
+
+    Returns:
+        The original or truncated diff summary.
+    """
+    if len(diff_summary) <= MAX_DIFF_CHARS:
+        return diff_summary
+
+    lines = diff_summary.splitlines()
+    summary_lines: list[str] = []
+    summary_lines.append("(Diff truncated to file-level summaries due to size)")
+    summary_lines.append("")
+
+    for line in lines:
+        # Keep file-level summary lines (stat lines, file headers, etc.)
+        stripped = line.strip()
+        if (
+            stripped.startswith("diff --git")
+            or stripped.startswith("---")
+            or stripped.startswith("+++")
+            or "file changed" in stripped.lower()
+            or "files changed" in stripped.lower()
+            or "insertion" in stripped.lower()
+            or "deletion" in stripped.lower()
+            or stripped.startswith("rename")
+            or stripped.startswith("new file")
+            or stripped.startswith("deleted file")
+            or stripped.startswith("Binary files")
+        ):
+            summary_lines.append(line)
+
+    # If we couldn't extract meaningful summaries, take the first chunk
+    if len(summary_lines) <= 2:
+        truncated = diff_summary[:MAX_DIFF_CHARS]
+        return truncated + "\n\n(... diff truncated due to size)"
+
+    return "\n".join(summary_lines)
+
+
+def _strip_markdown_fences(content: str) -> str:
+    """
+    Strip markdown code fences from the response if present.
+
+    The AI sometimes wraps the output in ```markdown ... ``` even when instructed
+    not to. This ensures the PR body renders correctly on GitHub.
+
+    Args:
+        content: The response content to clean
+
+    Returns:
+        The content with markdown fences stripped.
+    """
+    result = content
+
+    # Strip opening fence (```markdown or just ```)
+    if result.startswith("```markdown"):
+        result = result[len("```markdown") :].lstrip("\n")
+    elif result.startswith("```md"):
+        result = result[len("```md") :].lstrip("\n")
+    elif result.startswith("```"):
+        result = result[3:].lstrip("\n")
+
+    # Strip closing fence
+    if result.endswith("```"):
+        result = result[:-3].rstrip("\n")
+
+    return result.strip()
+
+
+def _build_prompt(
+    template_content: str,
+    diff_summary: str,
+    spec_overview: str,
+    commit_log: str,
+    branch_name: str,
+    target_branch: str,
+) -> str:
+    """
+    Build the prompt for the PR template filler agent.
+
+    Combines the system prompt context variables into a single message
+    that includes the template and all change context.
+
+    Args:
+        template_content: The PR template markdown
+        diff_summary: Git diff summary (possibly truncated)
+        spec_overview: Spec.md content or summary
+        commit_log: Git log of commits in the PR
+        branch_name: Source branch name
+        target_branch: Target branch name
+
+    Returns:
+        The assembled prompt string.
+    """
+    return f"""Fill out the following GitHub PR template using the provided context.
+Return ONLY the filled template markdown — no preamble, no explanation, no code fences.
+
+## Checkbox Guidelines
+
+IMPORTANT: Be accurate and honest about what has and hasn't been verified.
+
+**Check these based on context (you can infer from the diff/spec):**
+- Base Branch targeting — check based on target_branch value
+- Type of Change (bug fix, feature, docs, refactor, test) — infer from diff and spec
+- Area (Frontend, Backend, Fullstack) — infer from changed file paths
+- Feature Toggle "N/A" — if the feature appears complete and not behind a flag
+- Breaking Changes "No" — if changes appear backward compatible
+
+**Leave UNCHECKED (these require human verification you cannot perform):**
+- "I've tested my changes locally" — you have not tested anything
+- "All CI checks pass" — CI has not run yet
+- "Windows/macOS/Linux tested" — requires manual testing on each platform
+- "All existing tests pass" — CI has not run yet
+- "New features include test coverage" — unless test files are clearly visible in the diff
+- "Bug fixes include regression tests" — unless test files are clearly visible in the diff
+
+**For platform/code quality checkboxes:**
+- "Used centralized platform/ module" — leave unchecked unless you can verify from the diff
+- "No hardcoded paths" — leave unchecked unless you can verify from the diff
+- "PR is small and focused (< 400 lines)" — check only if diff stats show < 400 lines changed
+
+**For the "I've synced with develop branch" checkbox:**
+- Leave unchecked — you cannot verify the sync status
+
+## PR Template
+
+{template_content}
+
+## Change Context
+
+### Branch Information
+- **Source branch:** {branch_name}
+- **Target branch:** {target_branch}
+
+### Git Diff Summary
+```
+{diff_summary}
+```
+
+### Spec Overview
+{spec_overview}
+
+### Commit History
+```
+{commit_log}
+```
+
+Fill every section of the PR template. Follow the checkbox guidelines above carefully.
+Output ONLY the completed template — no code fences, no preamble."""
+
+
+def _load_spec_overview(spec_dir: Path) -> str:
+    """
+    Load the spec.md content for context. Falls back to a brief note if unavailable.
+
+    Args:
+        spec_dir: Directory containing the spec files
+
+    Returns:
+        The spec content or a fallback message.
+    """
+    spec_file = spec_dir / "spec.md"
+    if spec_file.is_file():
+        try:
+            content = spec_file.read_text(encoding="utf-8")
+            # Truncate very long specs to keep prompt manageable
+            if len(content) > 8000:
+                return content[:8000] + "\n\n(... spec truncated for brevity)"
+            return content
+        except Exception as e:
+            logger.warning(f"Failed to read spec.md: {e}")
+    return "(No spec overview available)"
+
+
+async def run_pr_template_filler(
+    project_dir: Path,
+    spec_dir: Path,
+    model: str,
+    thinking_budget: int | None = None,
+    branch_name: str = "",
+    target_branch: str = "develop",
+    diff_summary: str = "",
+    commit_log: str = "",
+    verbose: bool = False,
+) -> str | None:
+    """
+    Run the PR template filler agent to generate a filled PR body.
+
+    Detects the project's PR template, gathers change context, and invokes
+    Claude to intelligently fill out the template sections.
+
+    Args:
+        project_dir: Root directory of the project
+        spec_dir: Directory containing the spec files
+        model: Claude model to use
+        thinking_budget: Max thinking tokens (None to disable extended thinking)
+        branch_name: Source branch name for the PR
+        target_branch: Target branch name for the PR
+        diff_summary: Git diff summary of changes
+        commit_log: Git log of commits included in the PR
+        verbose: Whether to show detailed output
+
+    Returns:
+        The filled template markdown string, or None if template detection fails
+        or the agent encounters an error.
+    """
+    # Detect PR template
+    template_content = detect_pr_template(project_dir)
+    if template_content is None:
+        logger.info("No PR template detected — skipping template filler")
+        return None
+
+    # Load spec overview
+    spec_overview = _load_spec_overview(spec_dir)
+
+    # Truncate diff if too large
+    truncated_diff = _truncate_diff(diff_summary)
+
+    # Build the prompt
+    prompt = _build_prompt(
+        template_content=template_content,
+        diff_summary=truncated_diff,
+        spec_overview=spec_overview,
+        commit_log=commit_log,
+        branch_name=branch_name,
+        target_branch=target_branch,
+    )
+
+    # Initialize task logger
+    task_logger = get_task_logger(spec_dir)
+    if task_logger:
+        task_logger.start_phase(LogPhase.CODING, "PR template filling")
+
+    # Create client following the pattern from planner.py
+    client = create_client(
+        project_dir,
+        spec_dir,
+        model,
+        agent_type="pr_template_filler",
+        max_thinking_tokens=thinking_budget,
+    )
+
+    try:
+        async with client:
+            status, response, _ = await run_agent_session(
+                client, prompt, spec_dir, verbose, phase=LogPhase.CODING
+            )
+
+        if task_logger:
+            task_logger.end_phase(
+                LogPhase.CODING,
+                success=(status != "error"),
+                message="PR template filling completed",
+            )
+
+        if status == "error":
+            logger.error("PR template filler agent returned an error")
+            return None
+
+        # The agent should return only the filled template markdown
+        if response and response.strip():
+            result = _strip_markdown_fences(response.strip())
+            logger.info("PR template filled successfully")
+            return result
+
+        logger.warning("PR template filler returned empty response")
+        return None
+
+    except Exception as e:
+        logger.error(f"PR template filler error: {e}")
+        if task_logger:
+            task_logger.log_error(f"PR template filler error: {e}", LogPhase.CODING)
+        return None

apps/backend/agents/tools_pkg/models.py

@@ -263,6 +263,12 @@ AGENT_CONFIGS = {
         "auto_claude_tools": [],
         "thinking_default": "low",
     },
+    "pr_template_filler": {
+        "tools": BASE_READ_TOOLS,  # Read-only — reads diff, template, spec
+        "mcp_servers": [],  # No MCP needed, context passed via prompt
+        "auto_claude_tools": [],
+        "thinking_default": "low",  # Fast utility task for structured fill-in
+    },
     "pr_reviewer": {
         "tools": BASE_READ_TOOLS + WEB_TOOLS,  # Read-only
         "mcp_servers": ["context7"],
@@ -270,18 +276,30 @@ AGENT_CONFIGS = {
         "thinking_default": "high",
     },
     "pr_orchestrator_parallel": {
-        "tools": BASE_READ_TOOLS + WEB_TOOLS,  # Read-only for parallel PR orchestrator
+        # Read-only for parallel PR orchestrator
+        # NOTE: Do NOT add "Task" here - the SDK auto-allows Task when agents are defined
+        # via the --agents flag. Explicitly adding it interferes with agent registration.
+        "tools": BASE_READ_TOOLS + WEB_TOOLS,
         "mcp_servers": ["context7"],
         "auto_claude_tools": [],
         "thinking_default": "high",
     },
     "pr_followup_parallel": {
-        "tools": BASE_READ_TOOLS
-        + WEB_TOOLS,  # Read-only for parallel followup reviewer
+        # Read-only for parallel followup reviewer
+        # NOTE: Do NOT add "Task" here - same reason as pr_orchestrator_parallel
+        "tools": BASE_READ_TOOLS + WEB_TOOLS,
         "mcp_servers": ["context7"],
         "auto_claude_tools": [],
         "thinking_default": "high",
     },
+    "pr_finding_validator": {
+        # Standalone validator for re-checking findings against actual code
+        # Called separately from orchestrator to validate findings with fresh context
+        "tools": BASE_READ_TOOLS,
+        "mcp_servers": [],
+        "auto_claude_tools": [],
+        "thinking_default": "medium",
+    },
     # ═══════════════════════════════════════════════════════════════════════
     # ANALYSIS PHASES
     # ═══════════════════════════════════════════════════════════════════════

apps/backend/cli/workspace_commands.py

@@ -536,6 +536,175 @@ def handle_cleanup_worktrees_command(project_dir: Path) -> None:
     cleanup_all_worktrees(project_dir, confirm=True)
 
 
+def _detect_conflict_scenario(
+    project_dir: Path,
+    conflicting_files: list[str],
+    spec_branch: str,
+    base_branch: str,
+) -> dict:
+    """
+    Analyze conflicting files to determine the conflict scenario.
+
+    This helps distinguish between:
+    - 'already_merged': Task changes already identical in target branch
+    - 'superseded': Target has newer version of same feature
+    - 'diverged': Standard diverged branches (AI can resolve)
+    - 'normal_conflict': Actual conflicting changes
+
+    Returns dict with:
+    - scenario: 'already_merged' | 'superseded' | 'diverged' | 'normal_conflict'
+    - already_merged_files: files identical in task and target
+    - details: additional context
+    """
+    if not conflicting_files:
+        return {
+            "scenario": "normal_conflict",
+            "already_merged_files": [],
+            "details": "No conflicting files to analyze",
+        }
+
+    already_merged_files = []
+    superseded_files = []
+    diverged_files = []
+
+    try:
+        # Get the merge-base commit
+        merge_base_result = subprocess.run(
+            ["git", "merge-base", base_branch, spec_branch],
+            cwd=project_dir,
+            capture_output=True,
+            text=True,
+        )
+        if merge_base_result.returncode != 0:
+            debug_warning(
+                MODULE, "Could not find merge base for conflict scenario detection"
+            )
+            return {
+                "scenario": "normal_conflict",
+                "already_merged_files": [],
+                "details": "Could not determine merge base",
+            }
+
+        merge_base = merge_base_result.stdout.strip()
+
+        for file_path in conflicting_files:
+            try:
+                # Get content from spec branch (task's changes)
+                spec_content_result = subprocess.run(
+                    ["git", "show", f"{spec_branch}:{file_path}"],
+                    cwd=project_dir,
+                    capture_output=True,
+                    text=True,
+                )
+                # Get content from base branch (target)
+                base_content_result = subprocess.run(
+                    ["git", "show", f"{base_branch}:{file_path}"],
+                    cwd=project_dir,
+                    capture_output=True,
+                    text=True,
+                )
+                # Get content from merge-base (original state)
+                merge_base_content_result = subprocess.run(
+                    ["git", "show", f"{merge_base}:{file_path}"],
+                    cwd=project_dir,
+                    capture_output=True,
+                    text=True,
+                )
+
+                # Check file existence in each ref
+                spec_exists = spec_content_result.returncode == 0
+                base_exists = base_content_result.returncode == 0
+                merge_base_exists = merge_base_content_result.returncode == 0
+
+                if spec_exists and base_exists:
+                    spec_content = spec_content_result.stdout
+                    base_content = base_content_result.stdout
+
+                    # If contents are identical, the changes are already merged
+                    if spec_content == base_content:
+                        already_merged_files.append(file_path)
+                        debug(
+                            MODULE,
+                            f"File {file_path}: already merged (identical content)",
+                        )
+                    elif merge_base_exists:
+                        merge_base_content = merge_base_content_result.stdout
+                        # If base has changed from merge_base but spec matches merge_base,
+                        # the task's changes are superseded by newer changes
+                        if spec_content == merge_base_content:
+                            superseded_files.append(file_path)
+                            debug(
+                                MODULE,
+                                f"File {file_path}: superseded (base has newer changes)",
+                            )
+                        else:
+                            diverged_files.append(file_path)
+                            debug(
+                                MODULE,
+                                f"File {file_path}: diverged (both branches modified)",
+                            )
+                    else:
+                        diverged_files.append(file_path)
+                else:
+                    diverged_files.append(file_path)
+
+            except Exception as e:
+                debug_warning(
+                    MODULE, f"Error analyzing file {file_path} for scenario: {e}"
+                )
+                diverged_files.append(file_path)
+
+        # Determine overall scenario based on dominant pattern
+        total_files = len(conflicting_files)
+
+        if len(already_merged_files) == total_files:
+            scenario = "already_merged"
+            details = "All conflicting files have identical content in both branches"
+        elif len(already_merged_files) > total_files / 2:
+            scenario = "already_merged"
+            details = f"{len(already_merged_files)} of {total_files} files already have the same content"
+        elif len(superseded_files) == total_files:
+            scenario = "superseded"
+            details = "All task changes have been superseded by newer changes in the target branch"
+        elif len(superseded_files) > total_files / 2:
+            scenario = "superseded"
+            details = (
+                f"{len(superseded_files)} of {total_files} files have been superseded"
+            )
+        elif diverged_files:
+            scenario = "diverged"
+            details = f"{len(diverged_files)} files have diverged and need AI merge"
+        else:
+            scenario = "normal_conflict"
+            details = "Standard merge conflicts detected"
+
+        debug(
+            MODULE,
+            f"Conflict scenario: {scenario}",
+            already_merged=len(already_merged_files),
+            superseded=len(superseded_files),
+            diverged=len(diverged_files),
+        )
+
+        return {
+            "scenario": scenario,
+            "already_merged_files": already_merged_files,
+            "superseded_files": superseded_files,
+            "diverged_files": diverged_files,
+            "details": details,
+        }
+
+    except Exception as e:
+        debug_error(MODULE, f"Error detecting conflict scenario: {e}")
+        return {
+            "scenario": "normal_conflict",
+            "already_merged_files": [],
+            "superseded_files": [],
+            "diverged_files": [],
+            "details": f"Error during analysis: {e}",
+        }
+
+
 def _check_git_merge_conflicts(
     project_dir: Path, spec_name: str, base_branch: str | None = None
 ) -> dict:
@@ -879,6 +1048,24 @@ def handle_merge_preview_command(
             f for f in git_conflicts.get("conflicting_files", []) if not is_lock_file(f)
         ]
 
+        # Detect conflict scenario (already_merged, superseded, diverged, normal_conflict)
+        # This helps the UI show appropriate messaging and actions
+        conflict_scenario = None
+        if non_lock_conflicting_files:
+            conflict_scenario = _detect_conflict_scenario(
+                project_dir,
+                non_lock_conflicting_files,
+                git_conflicts["spec_branch"],
+                git_conflicts["base_branch"],
+            )
+            debug(
+                MODULE,
+                f"Conflict scenario detected: {conflict_scenario.get('scenario')}",
+                already_merged_files=len(
+                    conflict_scenario.get("already_merged_files", [])
+                ),
+            )
+
         # Use git diff file count as the authoritative totalFiles count
         # The semantic tracker may not track all files (e.g., test files, config files)
         # but we want to show the user all files that will be merged
@@ -952,6 +1139,16 @@ def handle_merge_preview_command(
                 # Path-mapped files that need AI merge due to renames
                 "pathMappedAIMerges": path_mapped_ai_merges,
                 "totalRenames": len(path_mappings),
+                # Conflict scenario detection for better UX messaging
+                "scenario": conflict_scenario.get("scenario")
+                if conflict_scenario
+                else None,
+                "alreadyMergedFiles": conflict_scenario.get("already_merged_files", [])
+                if conflict_scenario
+                else [],
+                "scenarioMessage": conflict_scenario.get("details")
+                if conflict_scenario
+                else None,
             },
             "summary": {
                 # Use git diff count, not semantic tracker count

apps/backend/core/auth.py

@@ -6,6 +6,7 @@ for multiple environment variables, and SDK environment variable passthrough
 for custom API endpoints.
 """
 
+import hashlib
 import json
 import logging
 import os
@@ -65,6 +66,48 @@ SDK_ENV_VARS = [
 ]
 
 
+def _calculate_config_dir_hash(config_dir: str) -> str:
+    """
+    Calculate hash of config directory path for Keychain service name.
+
+    This MUST match the frontend's calculateConfigDirHash() in credential-utils.ts.
+    The frontend uses SHA256 hash of the config dir path, taking first 8 hex chars.
+
+    Args:
+        config_dir: Path to the config directory (should be absolute/expanded)
+
+    Returns:
+        8-character hex hash string (e.g., "d74c9506")
+    """
+    return hashlib.sha256(config_dir.encode()).hexdigest()[:8]
+
+
+def _get_keychain_service_name(config_dir: str | None = None) -> str:
+    """
+    Get the Keychain service name for credential storage.
+
+    This MUST match the frontend's getKeychainServiceName() in credential-utils.ts.
+    All profiles use hash-based keychain entries for isolation:
+    - Profile with configDir: "Claude Code-credentials-{hash}"
+    - No configDir (legacy/default): "Claude Code-credentials"
+
+    Args:
+        config_dir: Optional CLAUDE_CONFIG_DIR path. If provided, uses hash-based name.
+
+    Returns:
+        Keychain service name (e.g., "Claude Code-credentials-d74c9506")
+    """
+    if not config_dir:
+        return "Claude Code-credentials"
+
+    # Expand ~ to home directory (matching frontend normalization)
+    expanded_dir = os.path.expanduser(config_dir)
+
+    # Calculate hash and return hash-based service name
+    hash_suffix = _calculate_config_dir_hash(expanded_dir)
+    return f"Claude Code-credentials-{hash_suffix}"
+
+
 def is_encrypted_token(token: str | None) -> bool:
     """
     Check if a token is encrypted (has "enc:" prefix).
@@ -346,36 +389,50 @@ def _try_decrypt_token(token: str | None) -> str | None:
     return token
 
 
-def get_token_from_keychain() -> str | None:
+def get_token_from_keychain(config_dir: str | None = None) -> str | None:
     """
     Get authentication token from system credential store.
 
     Reads Claude Code credentials from:
-    - macOS: Keychain
+    - macOS: Keychain (uses hash-based service name if config_dir provided)
     - Windows: Credential Manager
     - Linux: Secret Service API (via dbus/secretstorage)
 
+    Args:
+        config_dir: Optional CLAUDE_CONFIG_DIR path for profile-specific credentials.
+                   When provided, reads from hash-based keychain entry matching
+                   the frontend's storage location.
+
     Returns:
         Token string if found, None otherwise
     """
     if is_macos():
-        return _get_token_from_macos_keychain()
+        return _get_token_from_macos_keychain(config_dir)
     elif is_windows():
-        return _get_token_from_windows_credential_files()
+        return _get_token_from_windows_credential_files(config_dir)
     else:
         # Linux: use secret-service API via DBus
-        return _get_token_from_linux_secret_service()
+        return _get_token_from_linux_secret_service(config_dir)
 
 
-def _get_token_from_macos_keychain() -> str | None:
-    """Get token from macOS Keychain."""
+def _get_token_from_macos_keychain(config_dir: str | None = None) -> str | None:
+    """Get token from macOS Keychain.
+
+    Args:
+        config_dir: Optional CLAUDE_CONFIG_DIR path. When provided, uses hash-based
+                   service name (e.g., "Claude Code-credentials-d74c9506") matching
+                   the frontend's credential storage location.
+    """
+    # Get the correct service name (hash-based if config_dir provided)
+    service_name = _get_keychain_service_name(config_dir)
+
     try:
         result = subprocess.run(
             [
                 "/usr/bin/security",
                 "find-generic-password",
                 "-s",
-                "Claude Code-credentials",
+                service_name,
                 "-w",
             ],
             capture_output=True,
@@ -384,6 +441,14 @@ def _get_token_from_macos_keychain() -> str | None:
         )
 
         if result.returncode != 0:
+            # If hash-based lookup fails and we have a config_dir, DON'T fall back
+            # to default service name - that would return the wrong profile's token.
+            # The config_dir was provided explicitly, so we should only use that.
+            if config_dir:
+                logger.debug(
+                    f"No keychain entry found for service '{service_name}' "
+                    f"(config_dir: {config_dir})"
+                )
             return None
 
         credentials_json = result.stdout.strip()
@@ -397,22 +462,51 @@ def _get_token_from_macos_keychain() -> str | None:
             return None
 
         # Validate token format (Claude OAuth tokens start with sk-ant-oat01-)
-        if not token.startswith("sk-ant-oat01-"):
+        # Also accept encrypted tokens (enc:) which will be decrypted later
+        if not (token.startswith("sk-ant-oat01-") or token.startswith("enc:")):
             return None
 
+        logger.debug(f"Found token in keychain service '{service_name}'")
         return token
 
     except (subprocess.TimeoutExpired, json.JSONDecodeError, KeyError, Exception):
         return None
 
 
-def _get_token_from_windows_credential_files() -> str | None:
+def _get_token_from_windows_credential_files(
+    config_dir: str | None = None,
+) -> str | None:
     """Get token from Windows credential files.
 
     Claude Code on Windows stores credentials in ~/.claude/.credentials.json
+    For custom profiles, uses the config_dir's .credentials.json file.
+
+    Args:
+        config_dir: Optional CLAUDE_CONFIG_DIR path for profile-specific credentials.
     """
     try:
-        # Claude Code stores credentials in ~/.claude/.credentials.json
+        # If config_dir is provided, read from that directory first
+        if config_dir:
+            expanded_dir = os.path.expanduser(config_dir)
+            profile_cred_paths = [
+                os.path.join(expanded_dir, ".credentials.json"),
+                os.path.join(expanded_dir, "credentials.json"),
+            ]
+            for cred_path in profile_cred_paths:
+                if os.path.exists(cred_path):
+                    with open(cred_path, encoding="utf-8") as f:
+                        data = json.load(f)
+                        token = data.get("claudeAiOauth", {}).get("accessToken")
+                        if token and (
+                            token.startswith("sk-ant-oat01-")
+                            or token.startswith("enc:")
+                        ):
+                            logger.debug(f"Found token in {cred_path}")
+                            return token
+            # If config_dir provided but no token found, don't fall back to default
+            return None
+
+        # Default Claude Code credential paths (no profile specified)
         cred_paths = [
             os.path.expandvars(r"%USERPROFILE%\.claude\.credentials.json"),
             os.path.expandvars(r"%USERPROFILE%\.claude\credentials.json"),
@@ -425,7 +519,9 @@ def _get_token_from_windows_credential_files() -> str | None:
                 with open(cred_path, encoding="utf-8") as f:
                     data = json.load(f)
                     token = data.get("claudeAiOauth", {}).get("accessToken")
-                    if token and token.startswith("sk-ant-oat01-"):
+                    if token and (
+                        token.startswith("sk-ant-oat01-") or token.startswith("enc:")
+                    ):
                         return token
 
         return None
@@ -434,7 +530,7 @@ def _get_token_from_windows_credential_files() -> str | None:
         return None
 
 
-def _get_token_from_linux_secret_service() -> str | None:
+def _get_token_from_linux_secret_service(config_dir: str | None = None) -> str | None:
     """Get token from Linux Secret Service API via DBus.
 
     Claude Code on Linux stores credentials in the Secret Service API
@@ -442,9 +538,12 @@ def _get_token_from_linux_secret_service() -> str | None:
     uses the secretstorage library which communicates via DBus.
 
     The credential is stored with:
-    - Label: "Claude Code-credentials"
+    - Label: "Claude Code-credentials" or "Claude Code-credentials-{hash}" for profiles
     - Attributes: {application: "claude-code"}
 
+    Args:
+        config_dir: Optional CLAUDE_CONFIG_DIR path for profile-specific credentials.
+
     Returns:
         Token string if found, None otherwise
     """
@@ -452,6 +551,9 @@ def _get_token_from_linux_secret_service() -> str | None:
         # secretstorage not installed, fall back to env var
         return None
 
+    # Get the correct service name (hash-based if config_dir provided)
+    target_label = _get_keychain_service_name(config_dir)
+
     try:
         # Get the default collection (typically "login" keyring)
         # secretstorage handles DBus communication internally
@@ -476,10 +578,10 @@ def _get_token_from_linux_secret_service() -> str | None:
         items = collection.search_items({"application": "claude-code"})
 
         for item in items:
-            # Check if this is the Claude Code credentials item
+            # Check if this is the correct Claude Code credentials item
             label = item.get_label()
-            # Use exact match for "Claude Code-credentials" to avoid false positives
-            if label == "Claude Code-credentials":
+            # Use exact match for target label (profile-specific or default)
+            if label == target_label:
                 # Get the secret (stored as JSON string)
                 secret = item.get_secret()
                 if not secret:
@@ -492,11 +594,23 @@ def _get_token_from_linux_secret_service() -> str | None:
                     data = json.loads(secret)
                     token = data.get("claudeAiOauth", {}).get("accessToken")
 
-                    if token and token.startswith("sk-ant-oat01-"):
+                    if token and (
+                        token.startswith("sk-ant-oat01-") or token.startswith("enc:")
+                    ):
+                        logger.debug(
+                            f"Found token in secret service with label '{target_label}'"
+                        )
                         return token
                 except json.JSONDecodeError:
                     continue
 
+        # If config_dir was provided but no token found, don't fall back
+        if config_dir:
+            logger.debug(
+                f"No secret service entry found with label '{target_label}' "
+                f"(config_dir: {config_dir})"
+            )
+
         return None
 
     except (
@@ -589,13 +703,37 @@ def get_auth_token(config_dir: str | None = None) -> str | None:
     env_config_dir = os.environ.get("CLAUDE_CONFIG_DIR")
     effective_config_dir = config_dir or env_config_dir
 
-    # If a custom config directory is specified, read from there
+    # 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:
+        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})"
+        )
+
+    # If a custom config directory is specified, read from there first
     if effective_config_dir:
+        # Try reading from .credentials.json file in the config directory
         token = _get_token_from_config_dir(effective_config_dir)
         if token:
             return _try_decrypt_token(token)
 
-    # Fallback to system credential store (default locations)
+        # 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:
+            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"
+        )
+        return None
+
+    # No config_dir specified - use default system credential store
     return _try_decrypt_token(get_token_from_keychain())
 
 
@@ -616,10 +754,20 @@ def get_auth_token_source(config_dir: str | None = None) -> str | None:
     # Check if token came from custom config directory (profile's configDir)
     env_config_dir = os.environ.get("CLAUDE_CONFIG_DIR")
     effective_config_dir = config_dir or env_config_dir
-    if effective_config_dir and _get_token_from_config_dir(effective_config_dir):
-        return "CLAUDE_CONFIG_DIR"
+    if effective_config_dir:
+        # Check file-based storage
+        if _get_token_from_config_dir(effective_config_dir):
+            return "CLAUDE_CONFIG_DIR"
+        # Check hash-based keychain entry for this profile
+        if get_token_from_keychain(effective_config_dir):
+            if is_macos():
+                return "macOS Keychain (profile)"
+            elif is_windows():
+                return "Windows Credential Files (profile)"
+            else:
+                return "Linux Secret Service (profile)"
 
-    # Check if token came from system credential store
+    # Check if token came from default system credential store
     if get_token_from_keychain():
         if is_macos():
             return "macOS Keychain"
@@ -800,6 +948,57 @@ def get_sdk_env_vars() -> dict[str, str]:
     return env
 
 
+def configure_sdk_authentication(config_dir: str | None = None) -> None:
+    """
+    Configure SDK authentication based on environment variables.
+
+    Supports two authentication modes:
+    - API Profile mode (ANTHROPIC_BASE_URL set): uses ANTHROPIC_AUTH_TOKEN
+    - OAuth mode (default): uses CLAUDE_CODE_OAUTH_TOKEN
+
+    In API profile mode, explicitly removes CLAUDE_CODE_OAUTH_TOKEN from the
+    environment because the SDK gives OAuth priority over API keys when both
+    are present.
+
+    Args:
+        config_dir: Optional profile config directory for per-profile Keychain
+                    lookup. When set, enables multi-profile token storage.
+
+    Raises:
+        ValueError: If required tokens are missing for the active mode.
+                   - API profile mode: requires ANTHROPIC_AUTH_TOKEN
+                   - OAuth mode: requires CLAUDE_CODE_OAUTH_TOKEN (from Keychain or env)
+    """
+    api_profile_mode = bool(os.environ.get("ANTHROPIC_BASE_URL", "").strip())
+
+    if api_profile_mode:
+        # API profile mode: ensure ANTHROPIC_AUTH_TOKEN is present
+        if not os.environ.get("ANTHROPIC_AUTH_TOKEN"):
+            raise ValueError(
+                "API profile mode active (ANTHROPIC_BASE_URL is set) "
+                "but ANTHROPIC_AUTH_TOKEN is not set"
+            )
+        # Explicitly remove CLAUDE_CODE_OAUTH_TOKEN so SDK uses ANTHROPIC_AUTH_TOKEN
+        # SDK gives OAuth priority over API keys when both are present
+        os.environ.pop("CLAUDE_CODE_OAUTH_TOKEN", None)
+        logger.info("Using API profile authentication")
+    else:
+        # OAuth mode: require and validate OAuth token
+        # Get OAuth token - uses profile-specific Keychain lookup when config_dir is set
+        # This correctly reads from "Claude Code-credentials-{hash}" for non-default profiles
+        oauth_token = require_auth_token(config_dir)
+
+        # Validate token is not encrypted before passing to SDK
+        # Encrypted tokens (enc:...) should have been decrypted by require_auth_token()
+        # If we still have an encrypted token here, it means decryption failed or was skipped
+        validate_token_not_encrypted(oauth_token)
+
+        # Ensure SDK can access it via its expected env var
+        # This is required because the SDK doesn't know about per-profile Keychain naming
+        os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = oauth_token
+        logger.info("Using OAuth authentication")
+
+
 def ensure_claude_code_oauth_token() -> None:
     """
     Ensure CLAUDE_CODE_OAUTH_TOKEN is set (for SDK compatibility).

apps/backend/core/client.py

@@ -139,9 +139,8 @@ from agents.tools_pkg import (
 from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient
 from claude_agent_sdk.types import HookMatcher
 from core.auth import (
+    configure_sdk_authentication,
     get_sdk_env_vars,
-    require_auth_token,
-    validate_token_not_encrypted,
 )
 from linear_updater import is_linear_enabled
 from prompts_pkg.project_context import detect_project_capabilities, load_project_index
@@ -490,20 +489,19 @@ def create_client(
        (see security.py for ALLOWED_COMMANDS)
     4. Tool filtering - Each agent type only sees relevant tools (prevents misuse)
     """
-    # Get OAuth token - Claude CLI handles token lifecycle internally
-    oauth_token = require_auth_token()
-
-    # Validate token is not encrypted before passing to SDK
-    # Encrypted tokens (enc:...) should have been decrypted by require_auth_token()
-    # If we still have an encrypted token here, it means decryption failed or was skipped
-    validate_token_not_encrypted(oauth_token)
-
-    # Ensure SDK can access it via its expected env var
-    os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = oauth_token
-
-    # Collect env vars to pass to SDK (ANTHROPIC_BASE_URL, etc.)
+    # Collect env vars to pass to SDK (ANTHROPIC_BASE_URL, CLAUDE_CONFIG_DIR, etc.)
     sdk_env = get_sdk_env_vars()
 
+    # Get the config dir for profile-specific credential lookup
+    # CLAUDE_CONFIG_DIR enables per-profile Keychain entries with SHA256-hashed service names
+    config_dir = sdk_env.get("CLAUDE_CONFIG_DIR")
+
+    # Configure SDK authentication (OAuth or API profile mode)
+    configure_sdk_authentication(config_dir)
+
+    if config_dir:
+        logger.info(f"Using CLAUDE_CONFIG_DIR for profile: {config_dir}")
+
     # Debug: Log git-bash path detection on Windows
     if "CLAUDE_CODE_GIT_BASH_PATH" in sdk_env:
         logger.info(f"Git Bash path found: {sdk_env['CLAUDE_CODE_GIT_BASH_PATH']}")

apps/backend/core/git_provider.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""
+Git Provider Detection
+======================
+
+Utility to detect git hosting provider (GitHub, GitLab, or unknown) from git remote URLs.
+Supports both SSH and HTTPS remote formats, and self-hosted GitLab instances.
+"""
+
+import re
+from pathlib import Path
+
+from .git_executable import run_git
+
+
+def detect_git_provider(project_dir: str | Path, remote_name: str | None = None) -> str:
+    """Detect the git hosting provider from the git remote URL.
+
+    Args:
+        project_dir: Path to the git repository
+        remote_name: Name of the remote to check (defaults to "origin")
+
+    Returns:
+        'github' if GitHub remote detected
+        'gitlab' if GitLab remote detected (cloud or self-hosted)
+        'unknown' if no remote or unsupported provider
+
+    Examples:
+        >>> detect_git_provider('/path/to/repo')
+        'github'  # for git@github.com:user/repo.git
+        'gitlab'  # for git@gitlab.com:user/repo.git
+        'gitlab'  # for https://gitlab.company.com/user/repo.git
+        'unknown' # for no remote or other providers
+    """
+    try:
+        # Get the remote URL (use specified remote or default to origin)
+        remote = remote_name if remote_name else "origin"
+        result = run_git(
+            ["remote", "get-url", remote],
+            cwd=project_dir,
+            timeout=5,
+        )
+
+        # If command failed or no output, return unknown
+        if result.returncode != 0 or not result.stdout.strip():
+            return "unknown"
+
+        remote_url = result.stdout.strip()
+
+        # Parse ssh:// URL format: ssh://[user@]host[:port]/path
+        ssh_url_match = re.match(r"^ssh://(?:[^@]+@)?([^:/]+)(?::\d+)?/", remote_url)
+        if ssh_url_match:
+            hostname = ssh_url_match.group(1)
+            return _classify_hostname(hostname)
+
+        # Parse HTTPS/HTTP format: https://host/path or http://host/path
+        # Must check before scp-like format to avoid matching "https" as hostname
+        https_match = re.match(r"^https?://([^/]+)/", remote_url)
+        if https_match:
+            hostname = https_match.group(1)
+            return _classify_hostname(hostname)
+
+        # Parse scp-like format: [user@]host:path (any username, not just 'git')
+        # This handles git@github.com:user/repo.git and similar formats
+        scp_match = re.match(r"^(?:[^@]+@)?([^:]+):", remote_url)
+        if scp_match:
+            hostname = scp_match.group(1)
+            # Exclude paths that look like Windows drives (e.g., C:)
+            if len(hostname) > 1:
+                return _classify_hostname(hostname)
+
+        # Unrecognized URL format
+        return "unknown"
+
+    except Exception:
+        # Any error (subprocess issues, etc.) -> unknown
+        return "unknown"
+
+
+def _classify_hostname(hostname: str) -> str:
+    """Classify a hostname as github, gitlab, or unknown.
+
+    Args:
+        hostname: The git remote hostname (e.g., 'github.com', 'gitlab.example.com')
+
+    Returns:
+        'github', 'gitlab', or 'unknown'
+    """
+    hostname_lower = hostname.lower()
+
+    # Check for GitHub (cloud and self-hosted/enterprise)
+    # Match github.com, *.github.com, or domains where a segment is or starts with 'github'
+    hostname_parts = hostname_lower.split(".")
+    if (
+        hostname_lower == "github.com"
+        or hostname_lower.endswith(".github.com")
+        or any(
+            part == "github" or part.startswith("github-") for part in hostname_parts
+        )
+    ):
+        return "github"
+
+    # Check for GitLab (cloud and self-hosted)
+    # Match gitlab.com, *.gitlab.com, or domains where a segment is or starts with 'gitlab'
+    if (
+        hostname_lower == "gitlab.com"
+        or hostname_lower.endswith(".gitlab.com")
+        or any(
+            part == "gitlab" or part.startswith("gitlab-") for part in hostname_parts
+        )
+    ):
+        return "gitlab"
+
+    # Unknown provider
+    return "unknown"

apps/backend/core/glab_executable.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""
+GitLab CLI Executable Finder
+============================
+
+Utility to find the glab (GitLab CLI) executable, with platform-specific fallbacks.
+"""
+
+import os
+import shutil
+import subprocess
+
+_cached_glab_path: str | None = None
+
+
+def invalidate_glab_cache() -> None:
+    """Invalidate the cached glab executable path.
+
+    Useful when glab may have been uninstalled, updated, or when
+    GITLAB_CLI_PATH environment variable has changed.
+    """
+    global _cached_glab_path
+    _cached_glab_path = None
+
+
+def _verify_glab_executable(path: str) -> bool:
+    """Verify that a path is a valid glab executable by checking version.
+
+    Args:
+        path: Path to the potential glab executable
+
+    Returns:
+        True if the path points to a valid glab executable, False otherwise
+    """
+    try:
+        result = subprocess.run(
+            [path, "--version"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            timeout=5,
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, OSError):
+        return False
+
+
+def _run_where_command() -> str | None:
+    """Run Windows 'where glab' command to find glab executable.
+
+    Returns:
+        First path found, or None if command failed
+    """
+    try:
+        result = subprocess.run(
+            "where glab",
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            timeout=5,
+            shell=True,  # Required: 'where' command must be executed through shell on Windows
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            found_path = result.stdout.strip().split("\n")[0].strip()
+            if (
+                found_path
+                and os.path.isfile(found_path)
+                and _verify_glab_executable(found_path)
+            ):
+                return found_path
+    except (subprocess.TimeoutExpired, OSError):
+        # 'where' command failed or timed out - fall through to return None
+        pass
+    return None
+
+
+def get_glab_executable() -> str | None:
+    """Find the glab executable, with platform-specific fallbacks.
+
+    Returns the path to glab executable, or None if not found.
+
+    Priority order:
+    1. GITLAB_CLI_PATH env var (user-configured path from frontend)
+    2. shutil.which (if glab is in PATH)
+    3. Homebrew paths on macOS
+    4. Windows Program Files paths
+    5. Windows 'where' command
+
+    Caches the result after first successful find. Use invalidate_glab_cache()
+    to force re-detection (e.g., after glab installation/uninstallation).
+    """
+    global _cached_glab_path
+
+    # Return cached result if available AND still exists
+    if _cached_glab_path is not None and os.path.isfile(_cached_glab_path):
+        return _cached_glab_path
+
+    _cached_glab_path = _find_glab_executable()
+    return _cached_glab_path
+
+
+def _find_glab_executable() -> str | None:
+    """Internal function to find glab executable."""
+    # 1. Check GITLAB_CLI_PATH env var (set by Electron frontend)
+    env_path = os.environ.get("GITLAB_CLI_PATH")
+    if env_path and os.path.isfile(env_path) and _verify_glab_executable(env_path):
+        return env_path
+
+    # 2. Try shutil.which (works if glab is in PATH)
+    glab_path = shutil.which("glab")
+    if glab_path and _verify_glab_executable(glab_path):
+        return glab_path
+
+    # 3. macOS-specific: check Homebrew paths
+    if os.name != "nt":  # Unix-like systems (macOS, Linux)
+        homebrew_paths = [
+            "/opt/homebrew/bin/glab",  # Apple Silicon
+            "/usr/local/bin/glab",  # Intel Mac
+            "/home/linuxbrew/.linuxbrew/bin/glab",  # Linux Homebrew
+        ]
+        for path in homebrew_paths:
+            if os.path.isfile(path) and _verify_glab_executable(path):
+                return path
+
+    # 4. Windows-specific: check Program Files paths
+    # glab uses Inno Setup with DefaultDirName={autopf}\glab
+    if os.name == "nt":
+        windows_paths = [
+            os.path.expandvars(r"%PROGRAMFILES%\glab\glab.exe"),
+            os.path.expandvars(r"%PROGRAMFILES(X86)%\glab\glab.exe"),
+            os.path.expandvars(r"%LOCALAPPDATA%\Programs\glab\glab.exe"),
+        ]
+        for path in windows_paths:
+            if os.path.isfile(path) and _verify_glab_executable(path):
+                return path
+
+        # 5. Try 'where' command with shell=True (more reliable on Windows)
+        return _run_where_command()
+
+    return None
+
+
+def run_glab(
+    args: list[str],
+    cwd: str | None = None,
+    timeout: int = 60,
+    input_data: str | None = None,
+) -> subprocess.CompletedProcess:
+    """Run a glab command with proper executable finding.
+
+    Args:
+        args: glab command arguments (without 'glab' prefix)
+        cwd: Working directory for the command
+        timeout: Command timeout in seconds (default: 60)
+        input_data: Optional string data to pass to stdin
+
+    Returns:
+        CompletedProcess with command results.
+    """
+    glab = get_glab_executable()
+    if not glab:
+        return subprocess.CompletedProcess(
+            args=["glab"] + args,
+            returncode=-1,
+            stdout="",
+            stderr="GitLab CLI (glab) not found. Install from https://gitlab.com/gitlab-org/cli",
+        )
+    try:
+        return subprocess.run(
+            [glab] + args,
+            cwd=cwd,
+            input=input_data,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired:
+        return subprocess.CompletedProcess(
+            args=[glab] + args,
+            returncode=-1,
+            stdout="",
+            stderr=f"Command timed out after {timeout} seconds",
+        )
+    except FileNotFoundError:
+        return subprocess.CompletedProcess(
+            args=[glab] + args,
+            returncode=-1,
+            stdout="",
+            stderr="GitLab CLI (glab) executable not found. Install from https://gitlab.com/gitlab-org/cli",
+        )

apps/backend/core/simple_client.py

@@ -22,14 +22,14 @@ Example usage:
 """
 
 import logging
+import os
 from pathlib import Path
 
 from agents.tools_pkg import get_agent_config, get_default_thinking_level
 from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient
 from core.auth import (
+    configure_sdk_authentication,
     get_sdk_env_vars,
-    require_auth_token,
-    validate_token_not_encrypted,
 )
 from core.platform import validate_cli_path
 from phase_config import get_thinking_budget
@@ -72,21 +72,16 @@ def create_simple_client(
     Raises:
         ValueError: If agent_type is not found in AGENT_CONFIGS
     """
-    # Get authentication
-    oauth_token = require_auth_token()
-
-    # Validate token is not encrypted before passing to SDK
-    # Encrypted tokens (enc:...) should have been decrypted by require_auth_token()
-    # If we still have an encrypted token here, it means decryption failed or was skipped
-    validate_token_not_encrypted(oauth_token)
-
-    import os
-
-    os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = oauth_token
-
-    # Get environment variables for SDK
+    # Get environment variables for SDK (including CLAUDE_CONFIG_DIR if set)
     sdk_env = get_sdk_env_vars()
 
+    # Get the config dir for profile-specific credential lookup
+    # CLAUDE_CONFIG_DIR enables per-profile Keychain entries with SHA256-hashed service names
+    config_dir = sdk_env.get("CLAUDE_CONFIG_DIR")
+
+    # Configure SDK authentication (OAuth or API profile mode)
+    configure_sdk_authentication(config_dir)
+
     # Get agent configuration (raises ValueError if unknown type)
     config = get_agent_config(agent_type)
 

apps/backend/core/task_event.py

@@ -0,0 +1,101 @@
+"""
+Task event protocol for frontend XState synchronization.
+
+Protocol: __TASK_EVENT__:{...}
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from uuid import uuid4
+
+TASK_EVENT_PREFIX = "__TASK_EVENT__:"
+_DEBUG = os.environ.get("DEBUG", "").lower() in ("1", "true", "yes")
+
+
+@dataclass
+class TaskEventContext:
+    task_id: str
+    spec_id: str
+    project_id: str
+    sequence_start: int = 0
+
+
+def _load_task_metadata(spec_dir: Path) -> dict:
+    metadata_path = spec_dir / "task_metadata.json"
+    if not metadata_path.exists():
+        return {}
+    try:
+        with open(metadata_path, encoding="utf-8") as f:
+            return json.load(f)
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+        return {}
+
+
+def _load_last_sequence(spec_dir: Path) -> int:
+    plan_path = spec_dir / "implementation_plan.json"
+    if not plan_path.exists():
+        return 0
+    try:
+        with open(plan_path, encoding="utf-8") as f:
+            plan = json.load(f)
+        last_event = plan.get("lastEvent") or {}
+        seq = last_event.get("sequence")
+        if isinstance(seq, int) and seq >= 0:
+            return seq + 1
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+        return 0
+    return 0
+
+
+def load_task_event_context(spec_dir: Path) -> TaskEventContext:
+    metadata = _load_task_metadata(spec_dir)
+    task_id = metadata.get("taskId") or metadata.get("task_id") or spec_dir.name
+    spec_id = metadata.get("specId") or metadata.get("spec_id") or spec_dir.name
+    project_id = metadata.get("projectId") or metadata.get("project_id") or ""
+    sequence_start = _load_last_sequence(spec_dir)
+    return TaskEventContext(
+        task_id=str(task_id),
+        spec_id=str(spec_id),
+        project_id=str(project_id),
+        sequence_start=sequence_start,
+    )
+
+
+class TaskEventEmitter:
+    def __init__(self, context: TaskEventContext) -> None:
+        self._context = context
+        self._sequence = context.sequence_start
+
+    @classmethod
+    def from_spec_dir(cls, spec_dir: Path) -> TaskEventEmitter:
+        return cls(load_task_event_context(spec_dir))
+
+    def emit(self, event_type: str, payload: dict | None = None) -> None:
+        event = {
+            "type": event_type,
+            "taskId": self._context.task_id,
+            "specId": self._context.spec_id,
+            "projectId": self._context.project_id,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "eventId": str(uuid4()),
+            "sequence": self._sequence,
+        }
+        if payload:
+            event.update(payload)
+
+        try:
+            print(f"{TASK_EVENT_PREFIX}{json.dumps(event, default=str)}", flush=True)
+            self._sequence += 1
+        except (OSError, UnicodeEncodeError) as e:
+            if _DEBUG:
+                try:
+                    sys.stderr.write(f"[task_event] emit failed: {e}\n")
+                    sys.stderr.flush()
+                except (OSError, UnicodeEncodeError):
+                    pass  # Silent on complete I/O failure

apps/backend/core/workspace.py

@@ -121,6 +121,7 @@ from merge import (
     FileTimelineTracker,
     MergeOrchestrator,
 )
+from merge.progress import MergeProgressCallback, MergeProgressStage, emit_progress
 
 MODULE = "workspace"
 
@@ -145,6 +146,26 @@ MODULE = "workspace"
 # - _heuristic_merge
 
 
+def _create_merge_progress_callback() -> MergeProgressCallback | None:
+    """
+    Create a progress callback for merge operations when running as a subprocess.
+
+    Returns emit_progress (writing JSON to stdout) only when stdout is piped
+    (i.e., running as a subprocess from the Electron frontend). Returns None
+    when running interactively in a terminal to avoid polluting CLI output.
+
+    This function must be called at runtime (not at import time) to ensure
+    sys.stdout state is accurate.
+    """
+    import sys
+
+    # Only emit progress JSON when stdout is piped (subprocess mode).
+    # In interactive CLI mode (TTY), progress JSON would clutter the output.
+    if not sys.stdout.isatty():
+        return emit_progress
+    return None
+
+
 def merge_existing_build(
     project_dir: Path,
     spec_name: str,
@@ -252,10 +273,11 @@ def merge_existing_build(
                 had_conflicts = stats.get("conflicts_resolved", 0) > 0
                 ai_assisted = stats.get("ai_assisted", 0) > 0
                 direct_copy = stats.get("direct_copy", False)
+                git_merge_used = stats.get("git_merge", False)
 
-                if had_conflicts or ai_assisted or direct_copy:
-                    # AI resolved conflicts, assisted with merges, or direct copy was used
-                    # Changes are already written and staged - no need for git merge
+                if had_conflicts or ai_assisted or direct_copy or git_merge_used:
+                    # AI resolved conflicts, assisted with merges, git merge was used, or direct copy was used
+                    # Changes are already written and staged - no need for additional git merge
                     _print_merge_success(
                         no_commit, stats, spec_name=spec_name, keep_worktree=True
                     )
@@ -402,9 +424,20 @@ def _try_smart_merge_inner(
         no_commit=no_commit,
     )
 
+    # Create progress callback for subprocess mode (Electron frontend).
+    # Only emits JSON to stdout when piped, not in interactive CLI.
+    progress_callback = _create_merge_progress_callback()
+
     try:
         print(muted("  Analyzing changes with intent-aware merge..."))
 
+        if progress_callback is not None:
+            progress_callback(
+                MergeProgressStage.ANALYZING,
+                0,
+                "Starting merge analysis",
+            )
+
         # Capture worktree state in FileTimelineTracker before merge
         try:
             timeline_tracker = FileTimelineTracker(project_dir)
@@ -440,6 +473,13 @@ def _try_smart_merge_inner(
         )
 
         # Check for git-level conflicts first (branch divergence)
+        if progress_callback is not None:
+            progress_callback(
+                MergeProgressStage.DETECTING_CONFLICTS,
+                25,
+                "Checking for git-level conflicts",
+            )
+
         debug(MODULE, "Checking for git-level conflicts")
         git_conflicts = _check_git_conflicts(project_dir, spec_name)
 
@@ -492,12 +532,11 @@ def _try_smart_merge_inner(
                 # If rebase succeeded and now there are no conflicts,
                 # the diverged_but_no_conflicts path will handle the merge
             else:
-                # Rebase failed - continue with conflict resolution as before
-                # The AI resolver will handle the conflicts
-                print(
-                    warning(
-                        "  Rebase encountered issues, using AI conflict resolution..."
-                    )
+                # Rebase failed (likely due to worktree lock) - continue with merge
+                # Git merge or AI resolver will handle it depending on conflict state
+                debug(
+                    MODULE,
+                    "Rebase skipped or failed, continuing with merge flow",
                 )
 
         if git_conflicts.get("has_conflicts"):
@@ -518,6 +557,18 @@ def _try_smart_merge_inner(
                 num_conflicts=len(git_conflicts.get("conflicting_files", [])),
             )
 
+            if progress_callback is not None:
+                progress_callback(
+                    MergeProgressStage.RESOLVING,
+                    50,
+                    f"Resolving {len(git_conflicts.get('conflicting_files', []))} conflicting files with AI",
+                    {
+                        "conflicts_found": len(
+                            git_conflicts.get("conflicting_files", [])
+                        )
+                    },
+                )
+
             # Try to resolve git conflicts with AI
             resolution_result = _resolve_git_conflicts_with_ai(
                 project_dir,
@@ -535,6 +586,22 @@ def _try_smart_merge_inner(
                     resolved_files=resolution_result.get("resolved_files", []),
                     stats=resolution_result.get("stats", {}),
                 )
+
+                if progress_callback is not None:
+                    stats = resolution_result.get("stats", {})
+                    original_conflict_count = len(
+                        git_conflicts.get("conflicting_files", [])
+                    )
+                    progress_callback(
+                        MergeProgressStage.COMPLETE,
+                        100,
+                        "Merge complete",
+                        {
+                            "conflicts_found": original_conflict_count,
+                            "conflicts_resolved": stats.get("conflicts_resolved", 0),
+                        },
+                    )
+
                 return resolution_result
             else:
                 # AI couldn't resolve all conflicts
@@ -547,6 +614,26 @@ def _try_smart_merge_inner(
                     resolved_files=resolution_result.get("resolved_files", []),
                     error=resolution_result.get("error"),
                 )
+
+                if progress_callback is not None:
+                    original_conflict_count = len(
+                        git_conflicts.get("conflicting_files", [])
+                    )
+                    remaining_count = len(
+                        resolution_result.get("remaining_conflicts", [])
+                    )
+                    progress_callback(
+                        MergeProgressStage.ERROR,
+                        0,
+                        "Some conflicts could not be resolved",
+                        {
+                            "conflicts_found": original_conflict_count,
+                            "conflicts_resolved": original_conflict_count
+                            - remaining_count,
+                            "conflicts_remaining": remaining_count,
+                        },
+                    )
+
                 return {
                     "success": False,
                     "conflicts": resolution_result.get("remaining_conflicts", []),
@@ -555,148 +642,81 @@ def _try_smart_merge_inner(
                     "error": resolution_result.get("error"),
                 }
 
-        # Check if branches diverged but no actual conflicts (can do direct copy)
+        # Check if branches diverged but no actual conflicts (use git merge)
         if git_conflicts.get("diverged_but_no_conflicts"):
-            debug(MODULE, "Branches diverged but no conflicts - doing direct file copy")
+            debug(MODULE, "Branches diverged but no conflicts - using git merge")
             print(muted("  Branches diverged but no conflicts detected"))
-            print(muted("  Copying changed files directly from worktree..."))
+            print(muted("  Using git merge to combine changes..."))
 
-            # Get changed files from spec branch
             spec_branch = f"auto-claude/{spec_name}"
-            base_branch = git_conflicts.get("base_branch", "main")
 
-            # Get merge-base for diff
-            merge_base_result = run_git(
-                ["merge-base", base_branch, spec_branch],
+            # Use git merge --no-commit to combine changes from both branches
+            # Since merge-tree confirmed no conflicts, this should succeed cleanly
+            merge_result = run_git(
+                ["merge", "--no-commit", "--no-ff", spec_branch],
                 cwd=project_dir,
             )
-            merge_base = (
-                merge_base_result.stdout.strip()
-                if merge_base_result.returncode == 0
-                else None
-            )
 
-            if merge_base:
-                # Get list of changed files in spec branch
-                changed_files = _get_changed_files_from_branch(
-                    project_dir, merge_base, spec_branch
+            if merge_result.returncode == 0:
+                # Merge succeeded - get list of files that were merged
+                # Use git diff --cached to see what's staged
+                diff_result = run_git(
+                    ["diff", "--cached", "--name-only"],
+                    cwd=project_dir,
+                )
+                merged_files = [
+                    f.strip()
+                    for f in diff_result.stdout.splitlines()
+                    if f.strip() and not _is_auto_claude_file(f.strip())
+                ]
+
+                debug_success(
+                    MODULE,
+                    "Git merge succeeded",
+                    merged_files_count=len(merged_files),
                 )
 
-                resolved_files = []
-                skipped_files = []  # Track files that failed to copy
-                files_to_stage = []
-                for file_path, status in changed_files:
-                    if _is_auto_claude_file(file_path):
-                        continue
+                for file_path in merged_files:
+                    print(success(f"    ✓ {file_path}"))
 
-                    try:
-                        target_path = project_dir / file_path
-
-                        if status == "D":
-                            # Deleted in worktree
-                            if target_path.exists():
-                                target_path.unlink()
-                            files_to_stage.append(file_path)
-                            resolved_files.append(file_path)
-                            print(success(f"    ✓ {file_path} (deleted)"))
-                        else:
-                            # New or modified - copy from spec branch
-                            target_path.parent.mkdir(parents=True, exist_ok=True)
-
-                            if _is_binary_file(file_path):
-                                binary_content = _get_binary_file_content_from_ref(
-                                    project_dir, spec_branch, file_path
-                                )
-                                if binary_content is not None:
-                                    target_path.write_bytes(binary_content)
-                                    files_to_stage.append(file_path)
-                                    resolved_files.append(file_path)
-                                    status_label = (
-                                        "new file" if status == "A" else "updated"
-                                    )
-                                    print(
-                                        success(f"    ✓ {file_path} ({status_label})")
-                                    )
-                                else:
-                                    skipped_files.append(file_path)
-                                    debug_warning(
-                                        MODULE,
-                                        f"Could not retrieve binary content for {file_path}",
-                                    )
-                            else:
-                                content = _get_file_content_from_ref(
-                                    project_dir, spec_branch, file_path
-                                )
-                                if content is not None:
-                                    target_path.write_text(content, encoding="utf-8")
-                                    files_to_stage.append(file_path)
-                                    resolved_files.append(file_path)
-                                    status_label = (
-                                        "new file" if status == "A" else "updated"
-                                    )
-                                    print(
-                                        success(f"    ✓ {file_path} ({status_label})")
-                                    )
-                                else:
-                                    skipped_files.append(file_path)
-                                    debug_warning(
-                                        MODULE,
-                                        f"Could not retrieve content for {file_path}",
-                                    )
-
-                    except Exception as e:
-                        skipped_files.append(file_path)
-                        debug_warning(MODULE, f"Could not copy {file_path}: {e}")
-
-                # Stage all files in a single git add call for efficiency
-                if files_to_stage:
-                    add_result = run_git(
-                        ["add"] + files_to_stage,
-                        cwd=project_dir,
+                if progress_callback is not None:
+                    progress_callback(
+                        MergeProgressStage.COMPLETE,
+                        100,
+                        f"Git merge complete ({len(merged_files)} files)",
                     )
-                    if add_result.returncode != 0:
-                        debug_warning(
-                            MODULE,
-                            f"Failed to stage files for direct copy: {add_result.stderr}",
-                        )
-                        # Return failure - files were written but not staged
-                        return {
-                            "success": False,
-                            "error": f"Failed to stage files: {add_result.stderr}",
-                            "resolved_files": [],
-                        }
 
-                # Build result - check for skipped files to detect partial merges
-                result = {
-                    "success": len(skipped_files) == 0,
-                    "resolved_files": resolved_files,
+                return {
+                    "success": True,
+                    "resolved_files": merged_files,
                     "stats": {
-                        "files_merged": len(resolved_files),
+                        "files_merged": len(merged_files),
                         "conflicts_resolved": 0,
                         "ai_assisted": 0,
-                        "auto_merged": len(resolved_files),
-                        "direct_copy": True,  # Flag indicating direct copy was used
-                        "skipped_count": len(skipped_files),
+                        "auto_merged": len(merged_files),
+                        "git_merge": True,  # Flag indicating git merge was used
                     },
                 }
-                if skipped_files:
-                    result["skipped_files"] = skipped_files
-                    result["partial_success"] = len(resolved_files) > 0
-                    print()
-                    print(
-                        warning(
-                            f"  ⚠ {len(skipped_files)} file(s) could not be retrieved:"
-                        )
-                    )
-                    for skipped_file in skipped_files:
-                        print(muted(f"    - {skipped_file}"))
-                    print(muted("  These files may need manual review."))
-                return result
             else:
-                # merge-base failed - branches may not share history
+                # Merge failed unexpectedly - abort and fall back to semantic analysis
                 debug_warning(
                     MODULE,
-                    "Could not find merge-base between branches - falling back to semantic analysis",
+                    "Git merge failed unexpectedly despite no conflicts detected",
+                    stderr=merge_result.stderr[:500] if merge_result.stderr else "",
+                )
+                # Abort the merge to restore clean state
+                abort_result = run_git(["merge", "--abort"], cwd=project_dir)
+                if abort_result.returncode != 0:
+                    debug_error(
+                        MODULE,
+                        "Failed to abort merge - repo may be in inconsistent state",
+                        stderr=abort_result.stderr,
+                    )
+                    return None  # Trigger fallback to avoid operating on inconsistent state
+                print(
+                    warning(
+                        "  Git merge failed unexpectedly, falling back to semantic analysis..."
+                    )
                 )
 
         # No git conflicts - proceed with semantic analysis
@@ -725,6 +745,14 @@ def _try_smart_merge_inner(
 
         # All conflicts can be auto-merged or no conflicts
         print(muted("  All changes compatible, proceeding with merge..."))
+
+        if progress_callback is not None:
+            progress_callback(
+                MergeProgressStage.COMPLETE,
+                100,
+                f"Analysis complete ({files_to_merge} files compatible)",
+            )
+
         return {
             "success": True,
             "stats": {
@@ -737,6 +765,13 @@ def _try_smart_merge_inner(
         # If smart merge fails, fall back to git
         import traceback
 
+        if progress_callback is not None:
+            progress_callback(
+                MergeProgressStage.ERROR,
+                0,
+                f"Smart merge error: {e}",
+            )
+
         print(muted(f"  Smart merge error: {e}"))
         traceback.print_exc()
         return None
@@ -748,14 +783,11 @@ def _rebase_spec_branch(
     base_branch: str,
 ) -> bool:
     """
-    Rebase the spec branch onto the latest base branch.
+    Attempt to rebase the spec branch onto the latest base branch.
 
-    This performs an automatic rebase of the spec branch onto the current
-    base branch (main/develop) to bring it up to date before merging.
-    If conflicts occur during rebase, the function aborts and returns False
-    so that the caller can fall back to AI conflict resolution.
-
-    The function preserves the current HEAD by restoring it after completion.
+    NOTE: This will fail if the spec branch is checked out in a worktree,
+    which is the normal case. The caller should handle failure gracefully
+    by falling back to git merge or AI conflict resolution.
 
     Args:
         project_dir: The project directory
@@ -764,22 +796,36 @@ def _rebase_spec_branch(
 
     Returns:
         True if rebase succeeded cleanly or branch was already up-to-date,
-        False if rebase failed due to conflicts or other errors (aborted, no ref movement)
+        False if rebase failed (worktree lock, conflicts, or other errors)
     """
     spec_branch = f"auto-claude/{spec_name}"
 
     debug(
         MODULE,
-        "Rebasing spec branch",
+        "Attempting to rebase spec branch",
         spec_branch=spec_branch,
         base_branch=base_branch,
     )
 
-    # Save original branch to restore after rebase (HIGH: prevents leaving repo on spec branch)
+    # Check if spec branch is used by a worktree (common case)
+    # In this case, we can't checkout/rebase from the main repo
+    worktree_list_result = run_git(["worktree", "list", "--porcelain"], cwd=project_dir)
+    if worktree_list_result.returncode == 0:
+        # Check if spec_branch is in use by a worktree
+        output = worktree_list_result.stdout
+        if f"branch refs/heads/{spec_branch}" in output:
+            debug(
+                MODULE,
+                "Spec branch is checked out in a worktree - skipping rebase",
+                spec_branch=spec_branch,
+            )
+            # This is expected - return False to let caller use git merge instead
+            return False
+
+    # Save original branch to restore after rebase
     original_branch_result = run_git(
         ["rev-parse", "--abbrev-ref", "HEAD"], cwd=project_dir
     )
-    # Check returncode and validate stdout before using original_branch
     if original_branch_result.returncode != 0:
         debug_error(
             MODULE,
@@ -795,7 +841,6 @@ def _rebase_spec_branch(
         )
         return False
 
-    # Save current state for recovery
     # Get the current commit of spec_branch before rebase
     before_commit_result = run_git(["rev-parse", spec_branch], cwd=project_dir)
     if before_commit_result.returncode != 0:
@@ -804,8 +849,6 @@ def _rebase_spec_branch(
             "Could not get spec branch commit before rebase",
             stderr=before_commit_result.stderr,
         )
-        # Restore original branch before returning
-        run_git(["checkout", original_branch], cwd=project_dir)
         return False
     before_commit = before_commit_result.stdout.strip()
 
@@ -813,22 +856,18 @@ def _rebase_spec_branch(
     print(muted(f"  Rebasing {spec_branch} onto {base_branch}..."))
 
     try:
-        # Perform the rebase using safe/standard invocation:
-        # 1. Checkout the spec branch first
-        # 2. Run standard rebase (no strategy options - let conflicts stop the rebase)
-        # If conflicts occur, we'll abort and let AI handle them during merge
+        # Try to checkout the spec branch
         checkout_result = run_git(["checkout", spec_branch], cwd=project_dir)
         if checkout_result.returncode != 0:
-            debug_error(
+            # Checkout failed - likely due to worktree lock
+            debug(
                 MODULE,
-                "Could not checkout spec branch for rebase",
-                stderr=checkout_result.stderr,
+                "Could not checkout spec branch for rebase (likely worktree lock)",
+                stderr=checkout_result.stderr[:200] if checkout_result.stderr else "",
             )
             return False
 
-        # Run standard rebase - will stop on conflicts so we can detect them
-        # Git syntax: git rebase [options] <upstream>
-        # where <upstream> is the branch to rebase onto
+        # Run standard rebase
         rebase_result = run_git(
             ["rebase", base_branch],
             cwd=project_dir,
@@ -838,9 +877,6 @@ def _rebase_spec_branch(
             # Rebase failed - check if it was due to conflicts
             status_result = run_git(["status", "--porcelain"], cwd=project_dir)
 
-            # MEDIUM: Properly parse git status output for conflict markers
-            # Git status --porcelain uses two-character status codes:
-            # UU = both modified, AA = both added, DD = both deleted, etc.
             has_unmerged = any(
                 line[:2] in ("UU", "AA", "DD", "AU", "UA", "DU", "UD")
                 for line in status_result.stdout.splitlines()
@@ -848,7 +884,6 @@ def _rebase_spec_branch(
             )
 
             # Abort the rebase to return to clean state
-            # NEW-002: If abort fails, immediately return False (repo in bad state)
             abort_result = run_git(["rebase", "--abort"], cwd=project_dir)
             if abort_result.returncode != 0:
                 debug_error(
@@ -856,19 +891,16 @@ def _rebase_spec_branch(
                     "Failed to abort rebase - repo may be in inconsistent state",
                     stderr=abort_result.stderr,
                 )
-                return False  # Abort failed - cannot safely continue
-
-            if has_unmerged:
-                # Rebase failed due to conflicts - we aborted, so no ref movement happened
-                debug_warning(
-                    MODULE,
-                    "Rebase encountered conflicts - aborted, will use AI conflict resolution",
-                    stderr=rebase_result.stderr[:200] if rebase_result.stderr else "",
-                )
-                # Return False since we aborted - no rebase occurred, caller should use AI
                 return False
 
-            # Other error (not conflict-related)
+            if has_unmerged:
+                debug_warning(
+                    MODULE,
+                    "Rebase encountered conflicts - aborted, will use alternative merge",
+                    stderr=rebase_result.stderr[:200] if rebase_result.stderr else "",
+                )
+                return False
+
             debug_error(
                 MODULE,
                 "Rebase failed with unexpected error",
@@ -882,9 +914,7 @@ def _rebase_spec_branch(
         if after_commit_result.returncode == 0:
             after_commit_hash = after_commit_result.stdout.strip()
 
-            # Verify the branch actually moved (commit changed)
             if before_commit == after_commit_hash:
-                # MEDIUM: Branch already up-to-date is a success condition, not failure
                 debug(
                     MODULE,
                     "Branch already up-to-date, no rebase needed",
@@ -904,8 +934,7 @@ def _rebase_spec_branch(
         debug_error(MODULE, "Could not verify spec branch commit after rebase")
         return False
     finally:
-        # HIGH: Always restore original branch, even on error/exception
-        # NEW-001: Log restoration failure (cannot modify return from finally block)
+        # Always restore original branch
         if original_branch:
             restore_result = run_git(["checkout", original_branch], cwd=project_dir)
             if restore_result.returncode != 0:
@@ -914,8 +943,6 @@ def _rebase_spec_branch(
                     f"Failed to restore original branch '{original_branch}'",
                     stderr=restore_result.stderr,
                 )
-                # Note: Cannot modify return value from finally block,
-                # but restoration failure is rare and non-critical (user can manually switch back)
 
 
 def _check_git_conflicts(project_dir: Path, spec_name: str) -> dict:

apps/backend/core/worktree.py

@@ -15,6 +15,8 @@ This allows:
 """
 
 import asyncio
+import json
+import logging
 import os
 import re
 import shutil
@@ -28,8 +30,13 @@ from typing import TypedDict, TypeVar
 
 from core.gh_executable import get_gh_executable, invalidate_gh_cache
 from core.git_executable import get_git_executable, get_isolated_git_env, run_git
+from core.git_provider import detect_git_provider
+from core.glab_executable import get_glab_executable, invalidate_glab_cache
+from core.model_config import get_utility_model_config
 from debug import debug_warning
 
+logger = logging.getLogger(__name__)
+
 T = TypeVar("T")
 
 
@@ -136,6 +143,7 @@ class PushAndCreatePRResult(TypedDict, total=False):
     pushed: bool
     remote: str
     branch: str
+    provider: str  # 'github', 'gitlab', or 'unknown'
     pr_url: str | None  # None when PR was created but URL couldn't be extracted
     already_exists: bool
     error: str
@@ -175,8 +183,8 @@ class WorktreeManager:
 
     # Timeout constants for subprocess operations
     GIT_PUSH_TIMEOUT = 120  # 2 minutes for git push (network operations)
-    GH_CLI_TIMEOUT = 60  # 1 minute for gh CLI commands
-    GH_QUERY_TIMEOUT = 30  # 30 seconds for gh CLI queries
+    CLI_TIMEOUT = 60  # 1 minute for CLI commands (gh/glab)
+    CLI_QUERY_TIMEOUT = 30  # 30 seconds for CLI queries (gh/glab)
 
     def __init__(self, project_dir: Path, base_branch: str | None = None):
         self.project_dir = project_dir
@@ -1192,8 +1200,22 @@ class WorktreeManager:
         target = target_branch or self.base_branch
         pr_title = title or f"auto-claude: {spec_name}"
 
-        # Get PR body from spec.md if available
-        pr_body = self._extract_spec_summary(spec_name)
+        # Try AI-powered PR body from project's PR template, fall back to spec summary
+        pr_body: str | None = None
+        try:
+            diff_summary, commit_log = self._gather_pr_context(spec_name, target)
+            pr_body = self._try_ai_pr_body(
+                spec_name=spec_name,
+                target_branch=target,
+                branch_name=info.branch,
+                diff_summary=diff_summary,
+                commit_log=commit_log,
+            )
+        except Exception as e:
+            logger.warning(f"AI PR body generation encountered an error: {e}")
+
+        if not pr_body:
+            pr_body = self._extract_spec_summary(spec_name)
 
         # Find gh executable before attempting PR creation
         gh_executable = get_gh_executable()
@@ -1236,7 +1258,7 @@ class WorktreeManager:
                     text=True,
                     encoding="utf-8",
                     errors="replace",
-                    timeout=self.GH_CLI_TIMEOUT,
+                    timeout=self.CLI_TIMEOUT,
                     env=get_isolated_git_env(),
                 )
 
@@ -1312,9 +1334,328 @@ class WorktreeManager:
             invalidate_gh_cache()
             return PullRequestResult(
                 success=False,
-                error="gh CLI not found. Install from https://cli.github.com/",
+                error="GitHub CLI (gh) not found. Install from https://cli.github.com/",
             )
 
+    def create_merge_request(
+        self,
+        spec_name: str,
+        target_branch: str | None = None,
+        title: str | None = None,
+        draft: bool = False,
+    ) -> PullRequestResult:
+        """
+        Create a GitLab merge request for a spec's branch using glab CLI with retry logic.
+
+        Args:
+            spec_name: The spec folder name
+            target_branch: Target branch for MR (defaults to base_branch)
+            title: MR title (defaults to spec name)
+            draft: Whether to create as draft MR
+
+        Returns:
+            PullRequestResult with keys:
+                - success: bool
+                - pr_url: str (if created)
+                - already_exists: bool (if MR already exists)
+                - error: str (if failed)
+        """
+        info = self.get_worktree_info(spec_name)
+        if not info:
+            return PullRequestResult(
+                success=False,
+                error=f"No worktree found for spec: {spec_name}",
+            )
+
+        target = target_branch or self.base_branch
+        mr_title = title or f"auto-claude: {spec_name}"
+
+        # Get MR body from spec.md if available
+        mr_body = self._extract_spec_summary(spec_name)
+
+        # Find glab executable before attempting MR creation
+        glab_executable = get_glab_executable()
+        if not glab_executable:
+            return PullRequestResult(
+                success=False,
+                error="GitLab CLI (glab) not found. Install from https://gitlab.com/gitlab-org/cli",
+            )
+
+        # Build glab mr create command
+        glab_args = [
+            glab_executable,
+            "mr",
+            "create",
+            "--target-branch",
+            target,
+            "--source-branch",
+            info.branch,
+            "--title",
+            mr_title,
+            "--description",
+            mr_body,
+        ]
+        if draft:
+            glab_args.append("--draft")
+
+        def is_mr_retryable(stderr: str) -> bool:
+            """Check if MR creation error is retryable (network or HTTP 5xx)."""
+            return _is_retryable_network_error(stderr) or _is_retryable_http_error(
+                stderr
+            )
+
+        def do_create_mr() -> tuple[bool, PullRequestResult | None, str]:
+            """Execute MR creation for retry wrapper."""
+            try:
+                result = subprocess.run(
+                    glab_args,
+                    cwd=info.path,
+                    capture_output=True,
+                    text=True,
+                    encoding="utf-8",
+                    errors="replace",
+                    timeout=self.CLI_TIMEOUT,
+                    env=get_isolated_git_env(),
+                )
+
+                # Check for "already exists" case (success, no retry needed)
+                if result.returncode != 0 and "already exists" in result.stderr.lower():
+                    existing_url = self._get_existing_mr_url(spec_name, target)
+                    result_dict = PullRequestResult(
+                        success=True,
+                        pr_url=existing_url,
+                        already_exists=True,
+                    )
+                    if existing_url is None:
+                        result_dict["message"] = (
+                            "MR already exists but URL could not be retrieved"
+                        )
+                    return (True, result_dict, "")
+
+                if result.returncode == 0:
+                    # Extract MR URL from output
+                    mr_url: str | None = result.stdout.strip()
+                    if not mr_url.startswith("http"):
+                        # Try to find URL in output
+                        # GitLab URL pattern: matches any HTTPS URL with /merge_requests/<number> or /-/merge_requests/<number> path
+                        match = re.search(
+                            r"https://[^\s]+(?:/merge_requests/|/-/merge_requests/)\d+",
+                            result.stdout,
+                        )
+                        if match:
+                            mr_url = match.group(0)
+                        else:
+                            # Invalid output - no valid URL found
+                            mr_url = None
+
+                    return (
+                        True,
+                        PullRequestResult(
+                            success=True,
+                            pr_url=mr_url,
+                            already_exists=False,
+                        ),
+                        "",
+                    )
+
+                return (False, None, result.stderr)
+
+            except FileNotFoundError:
+                # glab CLI not installed - not retryable, raise to exit retry loop
+                raise
+
+        max_retries = 3
+        try:
+            result, last_error = _with_retry(
+                operation=do_create_mr,
+                max_retries=max_retries,
+                is_retryable=is_mr_retryable,
+            )
+
+            if result:
+                return result
+
+            # Handle timeout error message
+            if last_error == "Operation timed out":
+                return PullRequestResult(
+                    success=False,
+                    error=f"MR creation timed out after {max_retries} attempts.",
+                )
+
+            return PullRequestResult(
+                success=False,
+                error=f"Failed to create MR: {last_error}",
+            )
+
+        except FileNotFoundError:
+            # Cached glab path became invalid - clear cache so next call re-discovers
+            invalidate_glab_cache()
+            return PullRequestResult(
+                success=False,
+                error="GitLab CLI (glab) not found. Install from https://gitlab.com/gitlab-org/cli",
+            )
+
+    def _gather_pr_context(self, spec_name: str, target_branch: str) -> tuple[str, str]:
+        """
+        Gather diff summary and commit log for PR template filling.
+
+        Args:
+            spec_name: The spec folder name
+            target_branch: The target branch for the PR
+
+        Returns:
+            Tuple of (diff_summary, commit_log)
+        """
+        worktree_path = self.get_worktree_path(spec_name)
+        info = self.get_worktree_info(spec_name)
+        branch = info.branch if info else self.get_branch_name(spec_name)
+
+        # Get diff summary (stat for overview)
+        diff_result = self._run_git(
+            ["diff", "--stat", f"{target_branch}...{branch}"],
+            cwd=worktree_path,
+            timeout=30,
+        )
+        diff_summary = diff_result.stdout.strip() if diff_result.returncode == 0 else ""
+
+        # Get shortstat for quick summary
+        shortstat_result = self._run_git(
+            ["diff", "--shortstat", f"{target_branch}...{branch}"],
+            cwd=worktree_path,
+            timeout=30,
+        )
+        if shortstat_result.returncode == 0 and shortstat_result.stdout.strip():
+            diff_summary += "\n\n" + shortstat_result.stdout.strip()
+
+        # Get actual code changes (patch format) for better AI context
+        # Truncate to 30k chars to avoid token limits while still providing meaningful context
+        patch_result = self._run_git(
+            ["diff", "-p", "--stat-width=999", f"{target_branch}...{branch}"],
+            cwd=worktree_path,
+            timeout=30,
+        )
+        if patch_result.returncode == 0 and patch_result.stdout.strip():
+            patch_content = patch_result.stdout.strip()
+            MAX_DIFF_CHARS = 30_000
+
+            if len(patch_content) > MAX_DIFF_CHARS:
+                # Truncate patch and add notice
+                truncated_patch = patch_content[:MAX_DIFF_CHARS]
+                diff_summary += (
+                    "\n\n" + truncated_patch + "\n\n(... diff truncated due to size)"
+                )
+            else:
+                diff_summary += "\n\n" + patch_content
+
+        # Get commit log
+        log_result = self._run_git(
+            [
+                "log",
+                "--oneline",
+                "--no-merges",
+                f"{target_branch}..{branch}",
+            ],
+            cwd=worktree_path,
+            timeout=30,
+        )
+        commit_log = log_result.stdout.strip() if log_result.returncode == 0 else ""
+
+        return diff_summary, commit_log
+
+    def _try_ai_pr_body(
+        self,
+        spec_name: str,
+        target_branch: str,
+        branch_name: str,
+        diff_summary: str,
+        commit_log: str,
+    ) -> str | None:
+        """
+        Attempt to generate a PR body using the AI template filler agent.
+
+        Runs the async agent synchronously with a 30-second timeout.
+        Returns None on any failure so the caller can fall back gracefully.
+
+        Args:
+            spec_name: The spec folder name
+            target_branch: The target branch for the PR
+            branch_name: The source branch name
+            diff_summary: Git diff summary of changes
+            commit_log: Git log of commits
+
+        Returns:
+            The AI-generated PR body string, or None if unavailable.
+        """
+        try:
+            from agents.pr_template_filler import (
+                detect_pr_template,
+                run_pr_template_filler,
+            )
+        except ImportError:
+            logger.warning(
+                "PR template filler module not available, skipping AI PR body"
+            )
+            return None
+
+        # Check if a PR template exists before doing any heavy lifting
+        template = detect_pr_template(self.project_dir)
+        if template is None:
+            return None
+
+        # Resolve spec directory
+        spec_dir = self.project_dir / ".auto-claude" / "specs" / spec_name
+        if not spec_dir.is_dir():
+            # Try worktree-local spec path
+            worktree_path = self.get_worktree_path(spec_name)
+            spec_dir = worktree_path / ".auto-claude" / "specs" / spec_name
+            if not spec_dir.is_dir():
+                logger.warning("Spec directory not found for AI PR body generation")
+                return None
+
+        # Get model configuration from environment (respects user settings)
+        model, thinking_budget = get_utility_model_config()
+
+        async def _run_with_timeout() -> str | None:
+            try:
+                return await asyncio.wait_for(
+                    run_pr_template_filler(
+                        project_dir=self.project_dir,
+                        spec_dir=spec_dir,
+                        model=model,
+                        thinking_budget=thinking_budget,
+                        branch_name=branch_name,
+                        target_branch=target_branch,
+                        diff_summary=diff_summary,
+                        commit_log=commit_log,
+                        verbose=False,
+                    ),
+                    timeout=30.0,
+                )
+            except asyncio.TimeoutError:
+                logger.warning("PR template filler timed out after 30s")
+                return None
+
+        try:
+            # Check if there's already a running event loop
+            try:
+                loop = asyncio.get_running_loop()
+            except RuntimeError:
+                loop = None
+
+            if loop and loop.is_running():
+                # We're already inside an async context — run in a new thread
+                import concurrent.futures
+
+                with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                    future = pool.submit(asyncio.run, _run_with_timeout())
+                    return future.result(timeout=35)
+            else:
+                return asyncio.run(_run_with_timeout())
+
+        except Exception as e:
+            logger.warning(f"AI PR body generation failed: {e}")
+            return None
+
     def _extract_spec_summary(self, spec_name: str) -> str:
         """Extract a summary from spec.md for PR body."""
         worktree_path = self.get_worktree_path(spec_name)
@@ -1389,7 +1730,7 @@ class WorktreeManager:
                 text=True,
                 encoding="utf-8",
                 errors="replace",
-                timeout=self.GH_QUERY_TIMEOUT,
+                timeout=self.CLI_QUERY_TIMEOUT,
                 env=get_isolated_git_env(),
             )
             if result.returncode == 0:
@@ -1408,6 +1749,57 @@ class WorktreeManager:
 
         return None
 
+    def _get_existing_mr_url(self, spec_name: str, target_branch: str) -> str | None:
+        """Get the URL of an existing MR for this branch."""
+        info = self.get_worktree_info(spec_name)
+        if not info:
+            return None
+
+        glab_executable = get_glab_executable()
+        if not glab_executable:
+            # glab CLI not found - return None and let caller handle it
+            return None
+
+        try:
+            result = subprocess.run(
+                [
+                    glab_executable,
+                    "mr",
+                    "view",
+                    info.branch,
+                    "--output",
+                    "json",
+                ],
+                cwd=info.path,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=self.CLI_QUERY_TIMEOUT,
+                env=get_isolated_git_env(),
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                # Parse JSON output to extract web_url (glab uses snake_case)
+                try:
+                    data = json.loads(result.stdout)
+                    return data.get("web_url")
+                except json.JSONDecodeError:
+                    # If JSON parsing fails, return None
+                    pass
+        except (
+            subprocess.TimeoutExpired,
+            FileNotFoundError,
+            subprocess.SubprocessError,
+        ) as e:
+            # Silently ignore errors when fetching existing MR URL - this is a best-effort
+            # lookup that may fail due to network issues, missing glab CLI, or auth problems.
+            # Returning None allows the caller to handle missing URLs gracefully.
+            if isinstance(e, FileNotFoundError):
+                invalidate_glab_cache()
+            debug_warning("worktree", f"Could not get existing MR URL: {e}")
+
+        return None
+
     def push_and_create_pr(
         self,
         spec_name: str,
@@ -1417,13 +1809,14 @@ class WorktreeManager:
         force_push: bool = False,
     ) -> PushAndCreatePRResult:
         """
-        Push branch and create a pull request in one operation.
+        Push branch and create a pull request/merge request in one operation.
+        Automatically detects git provider (GitHub or GitLab) and routes to the appropriate CLI.
 
         Args:
             spec_name: The spec folder name
-            target_branch: Target branch for PR (defaults to base_branch)
-            title: PR title (defaults to spec name)
-            draft: Whether to create as draft PR
+            target_branch: Target branch for PR/MR (defaults to base_branch)
+            title: PR/MR title (defaults to spec name)
+            draft: Whether to create as draft PR/MR
             force_push: Whether to force push the branch
 
         Returns:
@@ -1431,7 +1824,8 @@ class WorktreeManager:
                 - success: bool
                 - pr_url: str (if created)
                 - pushed: bool (if push succeeded)
-                - already_exists: bool (if PR already exists)
+                - provider: str ('github', 'gitlab', or 'unknown')
+                - already_exists: bool (if PR/MR already exists)
                 - error: str (if failed)
         """
         # Step 1: Push the branch
@@ -1445,20 +1839,44 @@ class WorktreeManager:
                 error=push_result.get("error", "Push failed"),
             )
 
-        # Step 2: Create the PR
-        pr_result = self.create_pull_request(
-            spec_name=spec_name,
-            target_branch=target_branch,
-            title=title,
-            draft=draft,
+        # Step 2: Detect git provider (use the remote that was pushed to)
+        provider = detect_git_provider(
+            self.project_dir, remote_name=push_result.get("remote")
         )
 
+        # Step 3: Create the PR/MR based on provider
+        if provider == "github":
+            pr_result = self.create_pull_request(
+                spec_name=spec_name,
+                target_branch=target_branch,
+                title=title,
+                draft=draft,
+            )
+        elif provider == "gitlab":
+            pr_result = self.create_merge_request(
+                spec_name=spec_name,
+                target_branch=target_branch,
+                title=title,
+                draft=draft,
+            )
+        else:
+            # Unknown provider
+            return PushAndCreatePRResult(
+                success=False,
+                pushed=True,
+                remote=push_result.get("remote"),
+                branch=push_result.get("branch"),
+                provider=provider,
+                error="Unable to determine git hosting provider. Supported: GitHub, GitLab.",
+            )
+
         # Combine results
         return PushAndCreatePRResult(
             success=pr_result.get("success", False),
             pushed=True,
             remote=push_result.get("remote"),
             branch=push_result.get("branch"),
+            provider=provider,
             pr_url=pr_result.get("pr_url"),
             already_exists=pr_result.get("already_exists", False),
             error=pr_result.get("error"),

apps/backend/merge/conflict_resolver.py

@@ -17,6 +17,7 @@ import logging
 from .ai_resolver import AIResolver
 from .auto_merger import AutoMerger, MergeContext
 from .file_merger import apply_ai_merge, extract_location_content
+from .progress import MergeProgressCallback, MergeProgressStage
 from .types import (
     ConflictRegion,
     ConflictSeverity,
@@ -60,6 +61,7 @@ class ConflictResolver:
         baseline_content: str,
         task_snapshots: list[TaskSnapshot],
         conflicts: list[ConflictRegion],
+        progress_callback: MergeProgressCallback | None = None,
     ) -> MergeResult:
         """
         Resolve conflicts using AutoMerger and AIResolver.
@@ -69,6 +71,8 @@ class ConflictResolver:
             baseline_content: Original file content
             task_snapshots: Snapshots from all tasks modifying this file
             conflicts: List of detected conflicts
+            progress_callback: Optional callback for emitting per-conflict
+                resolution progress with details about current file and conflict count
 
         Returns:
             MergeResult with resolution details
@@ -78,8 +82,23 @@ class ConflictResolver:
         remaining: list[ConflictRegion] = []
         ai_calls = 0
         tokens_used = 0
+        total_conflicts = len(conflicts)
 
-        for conflict in conflicts:
+        for idx, conflict in enumerate(conflicts):
+            if progress_callback:
+                # Emit per-conflict progress within the resolving stage (50-75%)
+                # Calculate progress after processing (idx + 1) to reach 75% on last conflict
+                conflict_percent = 50 + int(((idx + 1) / max(total_conflicts, 1)) * 25)
+                progress_callback(
+                    stage=MergeProgressStage.RESOLVING,
+                    percent=conflict_percent,
+                    message=f"Resolving conflict {idx + 1}/{total_conflicts} in {file_path}",
+                    details={
+                        "current_file": file_path,
+                        "conflicts_found": total_conflicts,
+                        "conflicts_resolved": len(resolved),
+                    },
+                )
             # Try auto-merge first
             if conflict.can_auto_merge and conflict.merge_strategy:
                 context = MergeContext(

apps/backend/merge/merge_pipeline.py

@@ -18,6 +18,7 @@ import logging
 from .conflict_detector import ConflictDetector
 from .conflict_resolver import ConflictResolver
 from .file_merger import apply_single_task_changes, combine_non_conflicting_changes
+from .progress import MergeProgressCallback, MergeProgressStage
 from .types import (
     ChangeType,
     FileAnalysis,
@@ -57,6 +58,7 @@ class MergePipeline:
         file_path: str,
         baseline_content: str,
         task_snapshots: list[TaskSnapshot],
+        progress_callback: MergeProgressCallback | None = None,
     ) -> MergeResult:
         """
         Merge changes from multiple tasks for a single file.
@@ -65,6 +67,8 @@ class MergePipeline:
             file_path: Path to the file
             baseline_content: Original baseline content
             task_snapshots: Snapshots from tasks that modified this file
+            progress_callback: Optional callback for emitting per-file progress
+                within the 'resolving' stage (50-75% range)
 
         Returns:
             MergeResult with merged content or conflict info
@@ -72,6 +76,14 @@ class MergePipeline:
         task_ids = [s.task_id for s in task_snapshots]
         logger.info(f"Merging {file_path} with {len(task_snapshots)} task(s)")
 
+        if progress_callback:
+            progress_callback(
+                stage=MergeProgressStage.RESOLVING,
+                percent=50,
+                message=f"Merging file: {file_path}",
+                details={"current_file": file_path},
+            )
+
         # If only one task modified the file, no conflict possible
         if len(task_snapshots) == 1:
             snapshot = task_snapshots[0]
@@ -119,6 +131,7 @@ class MergePipeline:
             baseline_content=baseline_content,
             task_snapshots=task_snapshots,
             conflicts=conflicts,
+            progress_callback=progress_callback,
         )
 
     def _build_task_analyses(

apps/backend/merge/orchestrator.py

@@ -33,6 +33,7 @@ from .merge_pipeline import MergePipeline
 
 # Re-export models for backwards compatibility
 from .models import MergeReport, MergeStats, TaskMergeRequest
+from .progress import MergeProgressCallback, MergeProgressStage
 from .semantic_analyzer import SemanticAnalyzer
 from .types import (
     ConflictRegion,
@@ -260,6 +261,7 @@ class MergeOrchestrator:
         task_id: str,
         worktree_path: Path | None = None,
         target_branch: str = "main",
+        progress_callback: MergeProgressCallback | None = None,
     ) -> MergeReport:
         """
         Merge a single task's changes into the target branch.
@@ -268,6 +270,8 @@ class MergeOrchestrator:
             task_id: The task identifier
             worktree_path: Path to the task's worktree (auto-detected if not provided)
             target_branch: Branch to merge into
+            progress_callback: Optional callback for progress updates.
+                Called with (stage, percent, message, details) at key pipeline stages.
 
         Returns:
             MergeReport with results
@@ -284,7 +288,20 @@ class MergeOrchestrator:
         report = MergeReport(started_at=datetime.now(), tasks_merged=[task_id])
         start_time = datetime.now()
 
+        def _emit(
+            stage: MergeProgressStage,
+            percent: int,
+            message: str,
+            details: dict[str, Any] | None = None,
+        ) -> None:
+            """Emit progress if a callback is provided."""
+            if progress_callback is not None:
+                progress_callback(stage, percent, message, details)
+
         try:
+            # --- ANALYZING stage (0-25%) ---
+            _emit(MergeProgressStage.ANALYZING, 0, "Starting merge analysis")
+
             # Find worktree if not provided
             if worktree_path is None:
                 debug_detailed(MODULE, "Auto-detecting worktree path...")
@@ -293,16 +310,23 @@ class MergeOrchestrator:
                     debug_error(MODULE, f"Could not find worktree for task {task_id}")
                     report.success = False
                     report.error = f"Could not find worktree for task {task_id}"
+                    _emit(
+                        MergeProgressStage.ERROR,
+                        0,
+                        f"Could not find worktree for task {task_id}",
+                    )
                     return report
                 debug_detailed(MODULE, f"Found worktree: {worktree_path}")
 
             # Ensure evolution data is up to date
+            _emit(MergeProgressStage.ANALYZING, 5, "Loading file evolution data")
             debug(MODULE, "Refreshing evolution data from git...")
             self.evolution_tracker.refresh_from_git(
                 task_id, worktree_path, target_branch=target_branch
             )
 
             # Get files modified by this task
+            _emit(MergeProgressStage.ANALYZING, 15, "Running semantic analysis")
             modifications = self.evolution_tracker.get_task_modifications(task_id)
             debug(
                 MODULE,
@@ -312,11 +336,39 @@ class MergeOrchestrator:
             if not modifications:
                 debug_warning(MODULE, f"No modifications found for task {task_id}")
                 logger.info(f"No modifications found for task {task_id}")
+                _emit(
+                    MergeProgressStage.COMPLETE,
+                    100,
+                    "No modifications found",
+                )
                 report.completed_at = datetime.now()
                 return report
 
-            # Process each modified file
-            for file_path, snapshot in modifications:
+            _emit(
+                MergeProgressStage.ANALYZING,
+                25,
+                f"Found {len(modifications)} modified files",
+            )
+
+            # --- DETECTING_CONFLICTS stage (25-50%) ---
+            _emit(
+                MergeProgressStage.DETECTING_CONFLICTS,
+                25,
+                "Detecting conflicts",
+            )
+
+            # --- RESOLVING stage (50-75%) ---
+            total_files = len(modifications)
+            for idx, (file_path, snapshot) in enumerate(modifications):
+                # Calculate progress after processing (idx + 1) to reach 75% on last file
+                file_percent = 50 + int(((idx + 1) / max(total_files, 1)) * 25)
+                _emit(
+                    MergeProgressStage.RESOLVING,
+                    file_percent,
+                    f"Merging file {idx + 1}/{total_files}",
+                    {"current_file": file_path},
+                )
+
                 debug_detailed(
                     MODULE,
                     f"Processing file: {file_path}",
@@ -349,13 +401,31 @@ class MergeOrchestrator:
                     file=file_path,
                 )
 
+            # --- VALIDATING stage (75-100%) ---
+            _emit(
+                MergeProgressStage.VALIDATING,
+                75,
+                "Validating merge results",
+                {
+                    "conflicts_found": report.stats.conflicts_detected,
+                    "conflicts_resolved": report.stats.conflicts_auto_resolved,
+                },
+            )
+
             report.success = report.stats.files_failed == 0
 
+            _emit(
+                MergeProgressStage.VALIDATING,
+                90,
+                "Validation complete",
+            )
+
         except Exception as e:
             debug_error(MODULE, f"Merge failed for task {task_id}", error=str(e))
             logger.exception(f"Merge failed for task {task_id}")
             report.success = False
             report.error = str(e)
+            _emit(MergeProgressStage.ERROR, 0, f"Merge failed: {e}")
 
         report.completed_at = datetime.now()
         report.stats.duration_seconds = (
@@ -366,6 +436,18 @@ class MergeOrchestrator:
         if not self.dry_run:
             self._save_report(report, task_id)
 
+        # --- COMPLETE stage (100%) ---
+        if report.success:
+            _emit(
+                MergeProgressStage.COMPLETE,
+                100,
+                f"Merge complete for {task_id}",
+                {
+                    "conflicts_found": report.stats.conflicts_detected,
+                    "conflicts_resolved": report.stats.conflicts_auto_resolved,
+                },
+            )
+
         debug_success(
             MODULE,
             f"Merge complete for {task_id}",
@@ -382,6 +464,7 @@ class MergeOrchestrator:
         self,
         requests: list[TaskMergeRequest],
         target_branch: str = "main",
+        progress_callback: MergeProgressCallback | None = None,
     ) -> MergeReport:
         """
         Merge multiple tasks' changes.
@@ -392,6 +475,8 @@ class MergeOrchestrator:
         Args:
             requests: List of merge requests (one per task)
             target_branch: Branch to merge into
+            progress_callback: Optional callback for progress updates.
+                Called with (stage, percent, message, details) at key pipeline stages.
 
         Returns:
             MergeReport with combined results
@@ -402,11 +487,33 @@ class MergeOrchestrator:
         )
         start_time = datetime.now()
 
+        def _emit(
+            stage: MergeProgressStage,
+            percent: int,
+            message: str,
+            details: dict[str, Any] | None = None,
+        ) -> None:
+            """Emit progress if a callback is provided."""
+            if progress_callback is not None:
+                progress_callback(stage, percent, message, details)
+
         try:
+            # --- ANALYZING stage (0-25%) ---
+            _emit(
+                MergeProgressStage.ANALYZING,
+                0,
+                f"Starting merge analysis for {len(requests)} tasks",
+            )
+
             # Sort by priority (higher first)
             requests = sorted(requests, key=lambda r: -r.priority)
 
             # Refresh evolution data for all tasks
+            _emit(
+                MergeProgressStage.ANALYZING,
+                5,
+                "Loading file evolution data",
+            )
             for request in requests:
                 if request.worktree_path and request.worktree_path.exists():
                     self.evolution_tracker.refresh_from_git(
@@ -416,11 +523,38 @@ class MergeOrchestrator:
                     )
 
             # Find all files modified by any task
+            _emit(
+                MergeProgressStage.ANALYZING,
+                15,
+                "Running semantic analysis",
+            )
             task_ids = [r.task_id for r in requests]
             file_tasks = self.evolution_tracker.get_files_modified_by_tasks(task_ids)
 
-            # Process each file
-            for file_path, modifying_tasks in file_tasks.items():
+            _emit(
+                MergeProgressStage.ANALYZING,
+                25,
+                f"Found {len(file_tasks)} files to merge",
+            )
+
+            # --- DETECTING_CONFLICTS stage (25-50%) ---
+            _emit(
+                MergeProgressStage.DETECTING_CONFLICTS,
+                25,
+                "Detecting conflicts across tasks",
+            )
+
+            # --- RESOLVING stage (50-75%) ---
+            total_files = len(file_tasks)
+            for idx, (file_path, modifying_tasks) in enumerate(file_tasks.items()):
+                file_percent = 50 + int((idx / max(total_files, 1)) * 25)
+                _emit(
+                    MergeProgressStage.RESOLVING,
+                    file_percent,
+                    f"Merging file {idx + 1}/{total_files}",
+                    {"current_file": file_path},
+                )
+
                 # Get snapshots from all tasks that modified this file
                 evolution = self.evolution_tracker.get_file_evolution(file_path)
                 if not evolution:
@@ -466,8 +600,25 @@ class MergeOrchestrator:
                 report.file_results[file_path] = result
                 self._update_stats(report.stats, result)
 
+            # --- VALIDATING stage (75-100%) ---
+            _emit(
+                MergeProgressStage.VALIDATING,
+                75,
+                "Validating merge results",
+                {
+                    "conflicts_found": report.stats.conflicts_detected,
+                    "conflicts_resolved": report.stats.conflicts_auto_resolved,
+                },
+            )
+
             report.success = report.stats.files_failed == 0
 
+            _emit(
+                MergeProgressStage.VALIDATING,
+                90,
+                "Validation complete",
+            )
+
         except Exception as e:
             debug_error(
                 MODULE,
@@ -478,6 +629,7 @@ class MergeOrchestrator:
             logger.exception("Merge failed")
             report.success = False
             report.error = str(e)
+            _emit(MergeProgressStage.ERROR, 0, f"Merge failed: {e}")
 
         report.completed_at = datetime.now()
         report.stats.duration_seconds = (
@@ -489,6 +641,18 @@ class MergeOrchestrator:
             timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
             self._save_report(report, f"multi_{timestamp}")
 
+        # --- COMPLETE stage (100%) ---
+        if report.success:
+            _emit(
+                MergeProgressStage.COMPLETE,
+                100,
+                f"Merge complete for {len(requests)} tasks",
+                {
+                    "conflicts_found": report.stats.conflicts_detected,
+                    "conflicts_resolved": report.stats.conflicts_auto_resolved,
+                },
+            )
+
         return report
 
     def _merge_file(

apps/backend/merge/progress.py

@@ -0,0 +1,105 @@
+"""
+Merge Progress Emission
+=======================
+
+Structured progress event emission for the merge pipeline.
+
+This module provides the progress reporting infrastructure used by the
+merge orchestrator to communicate real-time status updates to the
+Electron frontend via stdout JSON lines.
+
+Progress events are emitted as JSON lines to stdout with type='progress',
+allowing the frontend to parse them separately from the final merge result.
+
+Components:
+- MergeProgressStage: Enum of pipeline stages
+- MergeProgressCallback: Protocol for type-safe callback threading
+- emit_progress: Function to emit structured progress events to stdout
+"""
+
+from __future__ import annotations
+
+import json
+from enum import Enum
+from typing import Any, Protocol
+
+
+class MergeProgressStage(Enum):
+    """
+    Stages of the merge pipeline.
+
+    Each stage corresponds to a phase of the merge process and maps
+    to a percentage range for progress reporting:
+    - ANALYZING: 0-25% — Loading file evolution, running semantic analysis
+    - DETECTING_CONFLICTS: 25-50% — Conflict detection and compatibility checks
+    - RESOLVING: 50-75% — Auto-merge and AI resolution of conflicts
+    - VALIDATING: 75-100% — Final validation of merged results
+    - COMPLETE: 100% — Merge finished successfully
+    - ERROR: N/A — Merge failed with an error
+    """
+
+    ANALYZING = "analyzing"
+    DETECTING_CONFLICTS = "detecting_conflicts"
+    RESOLVING = "resolving"
+    VALIDATING = "validating"
+    COMPLETE = "complete"
+    ERROR = "error"
+
+
+class MergeProgressCallback(Protocol):
+    """
+    Protocol for type-safe progress callback threading.
+
+    Implementations receive structured progress updates from the merge
+    pipeline stages and can forward them to any output channel.
+
+    Args:
+        stage: Current pipeline stage
+        percent: Progress percentage (0-100)
+        message: Human-readable status message
+        details: Optional additional context (conflicts_found, conflicts_resolved, current_file)
+    """
+
+    def __call__(
+        self,
+        stage: MergeProgressStage,
+        percent: int,
+        message: str,
+        details: dict[str, Any] | None = None,
+    ) -> None: ...
+
+
+def emit_progress(
+    stage: MergeProgressStage,
+    percent: int,
+    message: str,
+    details: dict[str, Any] | None = None,
+) -> None:
+    """
+    Emit a progress event as a JSON line to stdout.
+
+    The Electron main process parses these JSON lines from the merge
+    subprocess stdout and forwards them to the renderer via IPC.
+
+    Args:
+        stage: Current pipeline stage
+        percent: Progress percentage (0-100), clamped to valid range
+        message: Human-readable status message
+        details: Optional dict with additional context. Supported keys:
+            - conflicts_found (int): Number of conflicts detected
+            - conflicts_resolved (int): Number of conflicts resolved so far
+            - current_file (str): File currently being processed
+    """
+    percent = max(0, min(100, percent))
+
+    event: dict[str, Any] = {
+        "type": "progress",
+        "stage": stage.value,
+        "percent": percent,
+        "message": message,
+    }
+
+    if details:
+        event["details"] = details
+
+    print(json.dumps(event), flush=True)

apps/backend/prompts/coder.md

@@ -13,15 +13,58 @@ environment at the start of each prompt in the "YOUR ENVIRONMENT" section. Pay c
 
 - **Working Directory**: This is your root - all paths are relative to here
 - **Spec Location**: Where your spec files live (usually `./auto-claude/specs/{spec-name}/`)
+- **Isolation Mode**: If present, you are in an isolated worktree (see below)
 
 **RULES:**
 1. ALWAYS use relative paths starting with `./`
-2. NEVER use absolute paths (like `/Users/...`)
+2. NEVER use absolute paths (like `/Users/...` or `/e/projects/...`)
 3. NEVER assume paths exist - check with `ls` first
 4. If a file doesn't exist where expected, check the spec location from YOUR ENVIRONMENT section
 
 ---
 
+## ⛔ WORKTREE ISOLATION (When Applicable)
+
+If your environment shows **"Isolation Mode: WORKTREE"**, you are working in an **isolated git worktree**.
+This is a complete copy of the project created for safe, isolated development.
+
+### Critical Rules for Worktree Mode:
+
+1. **NEVER navigate to the parent project path** shown in "FORBIDDEN PATH"
+   - If you see `cd /path/to/main/project` in your context, DO NOT run it
+   - The parent project is OFF LIMITS
+
+2. **All files exist locally via relative paths**
+   - `./prod/...` ✅ CORRECT
+   - `/path/to/main/project/prod/...` ❌ WRONG (escapes isolation)
+
+3. **Git commits in the wrong location = disaster**
+   - Commits made after escaping go to the WRONG branch
+   - This defeats the entire isolation system
+
+### Why You Might Be Tempted to Escape:
+
+You may see absolute paths like `/e/projects/myapp/prod/src/file.ts` in:
+- `spec.md` (file references)
+- `context.json` (discovered files)
+- Error messages
+
+**DO NOT** `cd` to these paths. Instead, convert them to relative paths:
+- `/e/projects/myapp/prod/src/file.ts` → `./prod/src/file.ts`
+
+### Quick Check:
+
+```bash
+# Verify you're still in the worktree
+pwd
+# Should show: .../.auto-claude/worktrees/tasks/{spec-name}/
+# Or (legacy): .../.worktrees/{spec-name}/
+# Or (PR review): .../.auto-claude/github/pr/worktrees/{pr-number}/
+# NOT: /path/to/main/project
+```
+
+---
+
 ## 🚨 CRITICAL: PATH CONFUSION PREVENTION 🚨
 
 **THE #1 BUG IN MONOREPOS: Doubled paths after `cd` commands**
@@ -84,65 +127,6 @@ git add [verified-path]
 
 ---
 
-## 🚨 CRITICAL: WORKTREE ISOLATION 🚨
-
-**You may be in an ISOLATED GIT WORKTREE environment.**
-
-Check the "YOUR ENVIRONMENT" section at the top of this prompt. If you see an
-**"ISOLATED WORKTREE - CRITICAL"** section, you are in a worktree.
-
-### What is a Worktree?
-
-A worktree is a **complete copy of the project** isolated from the main project.
-This allows safe development without affecting the main branch.
-
-### Worktree Rules (CRITICAL)
-
-**If you are in a worktree, the environment section will show:**
-
-* **YOUR LOCATION:** The path to your isolated worktree
-* **FORBIDDEN:** The parent project path you must NEVER `cd` to
-
-**CRITICAL RULES:**
-* **NEVER** `cd` to the forbidden parent path
-* **NEVER** use `cd ../..` to escape the worktree
-* **STAY** within your working directory at all times
-* **ALL** file operations use paths relative to your current location
-
-### Why This Matters
-
-Escaping the worktree causes:
-* ❌ Git commits going to the wrong branch
-* ❌ Files created/modified in the wrong location
-* ❌ Breaking worktree isolation guarantees
-* ❌ Losing the safety of isolated development
-
-### How to Stay Safe
-
-**Before ANY `cd` command:**
-
-```bash
-# 1. Check where you are
-pwd
-
-# 2. Verify the target is within your worktree
-# If pwd shows: /path/to/.auto-claude/worktrees/tasks/spec-name/
-# Then: cd ./apps/backend  ✅ SAFE
-# But:  cd /path/to/parent/project  ❌ FORBIDDEN - ESCAPES ISOLATION
-
-# 3. When in doubt, don't use cd at all
-# Use relative paths from your current directory instead
-git add ./apps/backend/file.py  # Works from anywhere in worktree
-```
-
-### The Golden Rule in Worktrees
-
-**If you're in a worktree, pretend the parent project doesn't exist.**
-
-Everything you need is in your worktree, accessible via relative paths.
-
----
-
 ## STEP 1: GET YOUR BEARINGS (MANDATORY)
 
 First, check your environment. The prompt should tell you your working directory and spec location.

apps/backend/prompts/github/QA_REVIEW_SYSTEM_PROMPT.md

@@ -0,0 +1,192 @@
+# PR Review System Quality Control Prompt
+
+You are a senior software architect tasked with quality-controlling an AI-powered PR review system. Your goal is to analyze the system holistically, identify gaps between intent and implementation, and provide actionable feedback.
+
+## System Overview
+
+This is a **parallel orchestrator PR review system** that:
+1. An orchestrator AI analyzes a PR and delegates to specialist agents
+2. Specialist agents (security, quality, logic, codebase-fit) perform deep reviews
+3. A finding-validator agent validates all findings against actual code
+4. The orchestrator synthesizes results into a final verdict
+
+**Key Design Principles (from vision document):**
+- Evidence-based validation (NOT confidence-based)
+- Pattern-triggered mandatory exploration (6 semantic triggers)
+- Understand intent BEFORE looking for issues
+- The diff is the question, not the answer
+
+---
+
+## FILES TO EXAMINE
+
+### Vision & Architecture
+- `docs/PR_REVIEW_99_TRUST.md` - The vision document defining 99% trust goal
+
+### Orchestrator Prompts
+- `apps/backend/prompts/github/pr_parallel_orchestrator.md` - Main orchestrator prompt
+- `apps/backend/prompts/github/pr_followup_orchestrator.md` - Follow-up review orchestrator
+
+### Specialist Agent Prompts
+- `apps/backend/prompts/github/pr_security_agent.md` - Security review agent
+- `apps/backend/prompts/github/pr_quality_agent.md` - Code quality agent
+- `apps/backend/prompts/github/pr_logic_agent.md` - Logic/correctness agent
+- `apps/backend/prompts/github/pr_codebase_fit_agent.md` - Codebase fit agent
+- `apps/backend/prompts/github/pr_finding_validator.md` - Finding validator agent
+
+### Implementation Code
+- `apps/backend/runners/github/services/parallel_orchestrator_reviewer.py` - Orchestrator implementation
+- `apps/backend/runners/github/services/parallel_followup_reviewer.py` - Follow-up implementation
+- `apps/backend/runners/github/services/pydantic_models.py` - Schema definitions (VerificationEvidence, etc.)
+- `apps/backend/runners/github/services/sdk_utils.py` - SDK utilities for running agents
+- `apps/backend/runners/github/services/review_tools.py` - Tools available to review agents
+- `apps/backend/runners/github/context_gatherer.py` - Gathers PR context (files, callers, dependents)
+
+### Models & Configuration
+- `apps/backend/runners/github/models.py` - Data models
+- `apps/backend/agents/tools_pkg/models.py` - Tool models
+
+---
+
+## ANALYSIS TASKS
+
+### 1. Vision Alignment Check
+Compare the implementation against `PR_REVIEW_99_TRUST.md`:
+
+- [ ] **Evidence-based validation**: Is the system truly evidence-based or does it still use confidence scores anywhere?
+- [ ] **6 Mandatory Triggers**: Are all 6 semantic triggers properly defined and enforced?
+  1. Output contract changed
+  2. Input contract changed
+  3. Behavioral contract changed
+  4. Side effect contract changed
+  5. Failure contract changed
+  6. Null/undefined contract changed
+- [ ] **Phase 0 (Understand Intent)**: Is it mandatory? Is it enforced before delegation?
+- [ ] **Phase 1 (Trigger Detection)**: Is it mandatory? Does it output explicit trigger analysis?
+- [ ] **Bounded Exploration**: Is exploration limited to depth 1 (direct callers only)?
+
+### 2. Prompt Quality Analysis
+For each agent prompt, check:
+
+- [ ] Does it explain WHAT to look for?
+- [ ] Does it explain HOW to verify findings?
+- [ ] Does it require evidence (code snippets, line numbers)?
+- [ ] Does it define when to STOP exploring?
+- [ ] Does it distinguish between "in scope" and "out of scope"?
+- [ ] Does it handle the "no issues found" case properly?
+
+### 3. Schema Enforcement
+Check `pydantic_models.py`:
+
+- [ ] Is `VerificationEvidence` required (not optional) on all finding types?
+- [ ] Does `VerificationEvidence` require:
+  - `code_examined` (actual code, not description)
+  - `line_range_examined` (specific lines)
+  - `verification_method` (how it was verified)
+- [ ] Are there any finding types that bypass evidence requirements?
+
+### 4. Information Flow
+Trace how information flows:
+
+- [ ] PR Context → Orchestrator: What context is provided?
+- [ ] Orchestrator → Specialists: Are triggers passed? Are known callers passed?
+- [ ] Specialists → Validator: Are all findings validated?
+- [ ] Validator → Final Output: Are false positives properly dismissed?
+
+### 5. False Positive Prevention
+Check mechanisms to prevent false positives:
+
+- [ ] Do specialists verify issues exist before reporting?
+- [ ] Does the validator re-read the actual code?
+- [ ] Are "missing X" claims (missing error handling, etc.) verified?
+- [ ] Are dismissed findings tracked for transparency?
+
+### 6. Log Analysis (ATTACH LOGS BELOW)
+When reviewing logs, check:
+
+- [ ] Did the orchestrator output PR UNDERSTANDING before delegating?
+- [ ] Did the orchestrator output TRIGGER DETECTION before delegating?
+- [ ] Were triggers passed to specialists in delegation prompts?
+- [ ] Did specialists actually explore when triggers were present?
+- [ ] Were findings validated with real code evidence?
+- [ ] Were any false positives caught by the validator?
+
+---
+
+## SPECIFIC QUESTIONS TO ANSWER
+
+1. **Trigger System Effectiveness**: Did the trigger detection system correctly identify semantic contract changes? Were there any missed triggers or false triggers?
+
+2. **Exploration Quality**: When exploration was mandated by a trigger, did specialists explore effectively? Did they stop at the right time?
+
+3. **Evidence Quality**: Are the `code_examined` fields in findings actual code snippets or just descriptions? Are line numbers accurate?
+
+4. **False Positive Rate**: How many findings were dismissed as false positives? What caused them?
+
+5. **Missing Issues**: Based on your understanding of the PR, were there any issues that SHOULD have been caught but weren't?
+
+6. **Prompt Gaps**: Are there any scenarios not covered by the current prompts?
+
+7. **Schema Gaps**: Are there any ways findings could bypass evidence requirements?
+
+---
+
+## OUTPUT FORMAT
+
+Provide your analysis in this structure:
+
+```markdown
+## Executive Summary
+[2-3 sentences on overall system health]
+
+## Vision Alignment Score: X/10
+[Brief explanation]
+
+## Critical Issues (Must Fix)
+1. [Issue]: [Description] → [Suggested Fix]
+2. ...
+
+## High Priority Improvements
+1. [Improvement]: [Why it matters] → [How to implement]
+2. ...
+
+## Medium Priority Improvements
+1. ...
+
+## Low Priority / Nice to Have
+1. ...
+
+## Log Analysis Findings
+### What Worked Well
+- ...
+
+### What Didn't Work
+- ...
+
+### Specific Recommendations from Log Analysis
+1. ...
+
+## Questions for the Team
+1. [Question that needs human input]
+2. ...
+```
+
+---
+
+## ATTACH LOGS BELOW
+
+Paste the PR review debug logs here for analysis:
+
+```
+[PASTE LOGS HERE]
+```
+
+---
+
+## IMPORTANT NOTES
+
+- Focus on **systemic issues**, not one-off bugs
+- Prioritize issues that cause **false positives** (annoying) over false negatives (missed issues)
+- Consider **language-agnostic** design - the system should work for any codebase
+- Think about **edge cases**: empty PRs, huge PRs, refactor-only PRs, CSS-only PRs
+- The goal is **99% trust** - developers should trust the review enough to act on it immediately

apps/backend/prompts/github/pr_codebase_fit_agent.md

@@ -6,6 +6,81 @@ You are a focused codebase fit review agent. You have been spawned by the orches
 
 Ensure new code integrates well with the existing codebase. Check for consistency with project conventions, reuse of existing utilities, and architectural alignment. Focus ONLY on codebase fit - not security, logic correctness, or general quality.
 
+## Phase 1: Understand the PR Intent (BEFORE Looking for Issues)
+
+**MANDATORY** - Before searching for issues, understand what this PR is trying to accomplish.
+
+1. **Read the provided context**
+   - PR description: What does the author say this does?
+   - Changed files: What areas of code are affected?
+   - Commits: How did the PR evolve?
+
+2. **Identify the change type**
+   - Bug fix: Correcting broken behavior
+   - New feature: Adding new capability
+   - Refactor: Restructuring without behavior change
+   - Performance: Optimizing existing code
+   - Cleanup: Removing dead code or improving organization
+
+3. **State your understanding** (include in your analysis)
+   ```
+   PR INTENT: This PR [verb] [what] by [how].
+   RISK AREAS: [what could go wrong specific to this change type]
+   ```
+
+**Only AFTER completing Phase 1, proceed to looking for issues.**
+
+Why this matters: Understanding intent prevents flagging intentional design decisions as bugs.
+
+## TRIGGER-DRIVEN EXPLORATION (CHECK YOUR DELEGATION PROMPT)
+
+**FIRST**: Check if your delegation prompt contains a `TRIGGER:` instruction.
+
+- **If TRIGGER is present** → Exploration is **MANDATORY**, even if the diff looks correct
+- **If no TRIGGER** → Use your judgment to explore or not
+
+### How to Explore (Bounded)
+
+1. **Read the trigger** - What pattern did the orchestrator identify?
+2. **Form the specific question** - "Do similar functions elsewhere follow the same pattern?" (not "what's in the codebase?")
+3. **Use Grep** to find similar patterns, usages, or implementations
+4. **Use Read** to examine 3-5 relevant files
+5. **Answer the question** - Yes (report issue) or No (move on)
+6. **Stop** - Do not explore beyond the immediate question
+
+### Codebase-Fit-Specific Trigger Questions
+
+| Trigger | Codebase Fit Question to Answer |
+|---------|--------------------------------|
+| **Output contract changed** | Do other similar functions return the same type/structure? |
+| **Input contract changed** | Is this parameter change consistent with similar functions? |
+| **New pattern introduced** | Does this pattern already exist elsewhere that should be reused? |
+| **Naming changed** | Is the new naming consistent with project conventions? |
+| **Architecture changed** | Does this architectural change align with existing patterns? |
+
+### Example Exploration
+
+```
+TRIGGER: New pattern introduced (custom date formatter)
+QUESTION: Does a date formatting utility already exist?
+
+1. Grep for "formatDate\|dateFormat\|toDateString" → found utils/date.ts
+2. Read utils/date.ts → exports formatDate(date, format) with same functionality
+3. STOP - Found existing utility
+
+FINDINGS:
+- src/components/Report.tsx:45 - Implements custom date formatting
+  Existing utility: utils/date.ts exports formatDate() with same functionality
+  Suggestion: Use existing formatDate() instead of duplicating logic
+```
+
+### When NO Trigger is Given
+
+If the orchestrator doesn't specify a trigger, use your judgment:
+- Focus on pattern consistency in the changed code
+- Search for existing utilities that could be reused
+- Don't explore "just to be thorough"
+
 ## CRITICAL: PR Scope and Context
 
 ### What IS in scope (report these issues):
@@ -119,6 +194,92 @@ Before reporting ANY finding, you MUST:
 
 **Your evidence must prove the issue exists - not just that you suspect it.**
 
+## Evidence Requirements (MANDATORY)
+
+Every finding you report MUST include a `verification` object with ALL of these fields:
+
+### Required Fields
+
+**code_examined** (string, min 1 character)
+The **exact code snippet** you examined. Copy-paste directly from the file:
+```
+CORRECT: "cursor.execute(f'SELECT * FROM users WHERE id={user_id}')"
+WRONG:   "SQL query that uses string interpolation"
+```
+
+**line_range_examined** (array of 2 integers)
+The exact line numbers [start, end] where the issue exists:
+```
+CORRECT: [45, 47]
+WRONG:   [1, 100]  // Too broad - you didn't examine all 100 lines
+```
+
+**verification_method** (one of these exact values)
+How you verified the issue:
+- `"direct_code_inspection"` - Found the issue directly in the code at the location
+- `"cross_file_trace"` - Traced through imports/calls to confirm the issue
+- `"test_verification"` - Verified through examination of test code
+- `"dependency_analysis"` - Verified through analyzing dependencies
+
+### Conditional Fields
+
+**is_impact_finding** (boolean, default false)
+Set to `true` ONLY if this finding is about impact on OTHER files (not the changed file):
+```
+TRUE:  "This change in utils.ts breaks the caller in auth.ts"
+FALSE: "This code in utils.ts has a bug" (issue is in the changed file)
+```
+
+**checked_for_handling_elsewhere** (boolean, default false)
+For ANY claim about existing utilities or patterns:
+- Set `true` ONLY if you used Grep/Read tools to verify patterns exist/don't exist
+- Set `false` if you didn't search the codebase
+- **When true, include the search in your description:**
+  - "Searched `Grep('formatDate|dateFormat', 'src/utils/')` - found existing helper"
+  - "Searched `Grep('class.*Service', 'src/services/')` - confirmed naming pattern"
+
+```
+TRUE:  "Searched for date formatting helpers - found utils/date.ts:formatDate()"
+FALSE: "This should use an existing utility" (didn't verify one exists)
+```
+
+**If you cannot provide real evidence, you do not have a verified finding - do not report it.**
+
+**Search Before Claiming:** Never claim something "should use existing X" without first verifying X exists and fits the use case.
+
+## Valid Outputs
+
+Finding issues is NOT the goal. Accurate review is the goal.
+
+### Valid: No Significant Issues Found
+If the code is well-implemented, say so:
+```json
+{
+  "findings": [],
+  "summary": "Reviewed [files]. No codebase_fit issues found. The implementation correctly [positive observation about the code]."
+}
+```
+
+### Valid: Only Low-Severity Suggestions
+Minor improvements that don't block merge:
+```json
+{
+  "findings": [
+    {"severity": "low", "title": "Consider extracting magic number to constant", ...}
+  ],
+  "summary": "Code is sound. One minor suggestion for readability."
+}
+```
+
+### INVALID: Forced Issues
+Do NOT report issues just to have something to say:
+- Theoretical edge cases without evidence they're reachable
+- Style preferences not backed by project conventions
+- "Could be improved" without concrete problem
+- Pre-existing issues not introduced by this PR
+
+**Reporting nothing is better than reporting noise.** False positives erode trust faster than false negatives.
+
 ## Code Patterns to Flag
 
 ### Reinventing Existing Utilities
@@ -189,6 +350,13 @@ Provide findings in JSON format:
     "description": "This file implements custom date formatting, but the codebase already has `formatDate()` in `src/utils/date.ts` that does the same thing.",
     "category": "codebase_fit",
     "severity": "high",
+    "verification": {
+      "code_examined": "const formatted = `${date.getMonth()}/${date.getDate()}/${date.getFullYear()}`;",
+      "line_range_examined": [15, 15],
+      "verification_method": "cross_file_trace"
+    },
+    "is_impact_finding": false,
+    "checked_for_handling_elsewhere": false,
     "existing_code": "src/utils/date.ts:formatDate()",
     "suggested_fix": "Replace custom implementation with: import { formatDate } from '@/utils/date';",
     "confidence": 92
@@ -200,6 +368,13 @@ Provide findings in JSON format:
     "description": "This file uses 'customer' terminology but the rest of the codebase consistently uses 'user'. This creates confusion and makes search/navigation harder.",
     "category": "codebase_fit",
     "severity": "medium",
+    "verification": {
+      "code_examined": "export interface Customer { id: string; name: string; email: string; }",
+      "line_range_examined": [1, 5],
+      "verification_method": "direct_code_inspection"
+    },
+    "is_impact_finding": false,
+    "checked_for_handling_elsewhere": false,
     "codebase_pattern": "src/models/user.ts, src/api/users.ts, src/services/userService.ts",
     "suggested_fix": "Rename to use 'user' terminology to match codebase conventions",
     "confidence": 88
@@ -211,6 +386,13 @@ Provide findings in JSON format:
     "description": "This file is 847 lines and contains order validation, payment processing, inventory management, and notification sending. Each should be separate.",
     "category": "codebase_fit",
     "severity": "high",
+    "verification": {
+      "code_examined": "// File contains: validateOrder(), processPayment(), updateInventory(), sendNotification() - all in one file",
+      "line_range_examined": [1, 847],
+      "verification_method": "direct_code_inspection"
+    },
+    "is_impact_finding": false,
+    "checked_for_handling_elsewhere": false,
     "current_lines": 847,
     "suggested_fix": "Split into: orderValidator.ts, paymentProcessor.ts, inventoryManager.ts, notificationService.ts",
     "confidence": 95

apps/backend/prompts/github/pr_finding_validator.md

@@ -33,6 +33,165 @@ For each finding you receive:
 4. **PROVIDE** concrete code evidence - the actual code that proves or disproves the issue
 5. **RETURN** validation status with evidence (binary decision based on what the code shows)
 
+## Batch Processing (Multiple Findings)
+
+You may receive multiple findings to validate at once. When processing batches:
+
+1. **Group by file** - Read each file once, validate all findings in that file together
+2. **Process systematically** - Validate each finding in order, don't skip any
+3. **Return all results** - Your response must include a validation result for EVERY finding received
+4. **Optimize reads** - If 3 findings are in the same file, read it once with enough context for all
+
+**Example batch input:**
+```
+Validate these findings:
+1. SEC-001: SQL injection at auth/login.ts:45
+2. QUAL-001: Missing error handling at auth/login.ts:78
+3. LOGIC-001: Off-by-one at utils/array.ts:23
+```
+
+**Expected output:** 3 separate validation results, one for each finding ID.
+
+## Hypothesis-Validation Structure (MANDATORY)
+
+For EACH finding you investigate, use this structured approach. This prevents rubber-stamping findings as valid without actually verifying them.
+
+### Step 1: State the Hypothesis
+
+Before reading any code, clearly state what you're testing:
+
+```
+HYPOTHESIS: The finding claims "{title}" at {file}:{line}
+
+This hypothesis is TRUE if:
+1. The code at {line} contains the specific pattern described
+2. No mitigation exists in surrounding context (+/- 20 lines)
+3. The issue is actually reachable/exploitable in this codebase
+
+This hypothesis is FALSE if:
+1. The code at {line} is different than described
+2. Mitigation exists (validation, sanitization, framework protection)
+3. The code is unreachable or purely theoretical
+```
+
+### Step 2: Gather Evidence
+
+Read the actual code. Copy-paste it into `code_evidence`.
+
+```
+FILE: {file}
+LINES: {line-20} to {line+20}
+ACTUAL CODE:
+[paste the code here - this is your proof]
+```
+
+### Step 3: Test Each Condition
+
+For each condition in your hypothesis:
+
+```
+CONDITION 1: Code contains {specific pattern from finding}
+EVIDENCE: [specific line from code_evidence that proves/disproves]
+RESULT: TRUE / FALSE / INCONCLUSIVE
+
+CONDITION 2: No mitigation in surrounding context
+EVIDENCE: [what you found or didn't find in ±20 lines]
+RESULT: TRUE / FALSE / INCONCLUSIVE
+
+CONDITION 3: Issue is reachable/exploitable
+EVIDENCE: [how input reaches this code, or why it doesn't]
+RESULT: TRUE / FALSE / INCONCLUSIVE
+```
+
+### Step 4: Conclude Based on Evidence
+
+Apply these rules strictly:
+
+| Conditions | Conclusion |
+|------------|------------|
+| ALL conditions TRUE | `confirmed_valid` |
+| ANY condition FALSE | `dismissed_false_positive` |
+| ANY condition INCONCLUSIVE, none FALSE | `needs_human_review` |
+
+**CRITICAL: Your conclusion MUST match your condition results.** If you found mitigation (Condition 2 = FALSE), you MUST conclude `dismissed_false_positive`, not `confirmed_valid`.
+
+### Worked Example
+
+```
+HYPOTHESIS: SQL injection at auth.py:45
+
+Conditions to test:
+1. User input directly in SQL string (not parameterized)
+2. No sanitization before this point
+3. Input reachable from HTTP request
+
+Evidence gathered:
+FILE: auth.py, lines 25-65
+ACTUAL CODE:
+```python
+def get_user(user_id: str) -> User:
+    # user_id comes from request.args["id"]
+    query = f"SELECT * FROM users WHERE id = {user_id}"  # Line 45
+    return db.execute(query).fetchone()
+```
+
+Testing conditions:
+CONDITION 1: User input in SQL string
+EVIDENCE: Line 45 uses f-string interpolation: f"SELECT * FROM users WHERE id = {user_id}"
+RESULT: TRUE
+
+CONDITION 2: No sanitization
+EVIDENCE: No validation between request.args["id"] (line 43) and query construction (line 45)
+RESULT: TRUE
+
+CONDITION 3: Input reachable
+EVIDENCE: Comment says "user_id comes from request.args", confirmed by caller on line 12
+RESULT: TRUE
+
+CONCLUSION: confirmed_valid (all conditions TRUE)
+CODE_EVIDENCE: "query = f\"SELECT * FROM users WHERE id = {user_id}\""
+LINE_RANGE: [45, 45]
+EXPLANATION: SQL injection confirmed - user input from request.args is interpolated directly into SQL query without parameterization or sanitization.
+```
+
+### Counter-Example: Dismissing a False Positive
+
+```
+HYPOTHESIS: XSS vulnerability at render.py:89
+
+Conditions to test:
+1. User input reaches output without encoding
+2. No sanitization in the call chain
+3. Output context allows script execution
+
+Evidence gathered:
+FILE: render.py, lines 70-110
+ACTUAL CODE:
+```python
+def render_comment(user_input: str) -> str:
+    sanitized = bleach.clean(user_input, tags=[], strip=True)  # Line 85
+    return f"<div class='comment'>{sanitized}</div>"  # Line 89
+```
+
+Testing conditions:
+CONDITION 1: User input reaches output
+EVIDENCE: Line 89 outputs user_input into HTML
+RESULT: TRUE
+
+CONDITION 2: No sanitization
+EVIDENCE: Line 85 uses bleach.clean() with tags=[] (strips ALL tags)
+RESULT: FALSE - sanitization exists
+
+CONDITION 3: Output allows scripts
+EVIDENCE: Even if injected, bleach.clean removes script tags
+RESULT: FALSE - mitigation prevents exploitation
+
+CONCLUSION: dismissed_false_positive (Condition 2 and 3 are FALSE)
+CODE_EVIDENCE: "sanitized = bleach.clean(user_input, tags=[], strip=True)"
+LINE_RANGE: [85, 89]
+EXPLANATION: The original finding missed the sanitization at line 85. bleach.clean() with tags=[] strips all HTML tags including script tags, making XSS impossible.
+```
+
 ## Investigation Process
 
 ### Step 1: Fetch the Code
@@ -47,6 +206,8 @@ Focus on lines around: {finding.line}
 
 ### Step 2: Analyze with Fresh Eyes - NEVER ASSUME
 
+**Follow the Hypothesis-Validation Structure above for each finding.** State your hypothesis, gather evidence, test each condition, then conclude based on the evidence. This structure prevents you from confirming findings just because they "sound plausible."
+
 **CRITICAL: Do NOT assume the original finding is correct.** The original reviewer may have:
 - Hallucinated line numbers that don't exist
 - Misread or misunderstood the code
@@ -194,6 +355,45 @@ These patterns often confirm the issue is real:
 4. **Missing error handling** in critical paths
 5. **Race conditions** with clear concurrent access
 
+## Cross-File Validation (For Specific Finding Types)
+
+Some findings require checking the CODEBASE, not just the flagged file:
+
+### Duplication Findings ("code is duplicated 3 times")
+
+**Before confirming a duplication finding, you MUST:**
+
+1. **Verify the duplicated code exists** - Read all locations mentioned
+2. **Check for existing helpers** - Use Grep to search for:
+   - Similar function names in `/utils/`, `/helpers/`, `/shared/`
+   - Common patterns that might already be abstracted
+   - Example: `Grep("formatDate|dateFormat|toDateString", "**/*.{ts,js}")`
+
+3. **Decide based on evidence:**
+   - If existing helper found → `dismissed_false_positive` (they should use it)
+   - Wait, no - if helper exists and they're NOT using it → `confirmed_valid` (finding is correct)
+   - If no helper exists → `confirmed_valid` (suggest creating one)
+
+**Example:**
+```
+Finding: "Duplicated YOLO mode check repeated 3 times"
+
+CROSS-FILE CHECK:
+1. Grep for "YOLO_MODE|yoloMode|bypassSecurity" in utils/ → No results
+2. Grep for existing env var pattern helpers → Found: utils/env.ts:getEnvFlag()
+3. CONCLUSION: confirmed_valid - getEnvFlag() exists but isn't being used
+   SUGGESTED_FIX: "Use existing getEnvFlag() helper from utils/env.ts"
+```
+
+### "Should Use Existing X" Findings
+
+**Before confirming, verify the existing X actually fits the use case:**
+
+1. Read the suggested existing code
+2. Check if it has the required interface/behavior
+3. If it doesn't match → `dismissed_false_positive` (can't use it)
+4. If it matches → `confirmed_valid` (should use it)
+
 ## Critical Rules
 
 1. **ALWAYS read the actual code** - Never rely on memory or the original finding description
@@ -204,6 +404,10 @@ These patterns often confirm the issue is real:
 6. **Look for mitigations** - Check surrounding code for sanitization/validation
 7. **Check the full context** - Read ±20 lines, not just the flagged line
 8. **Verify code exists** - Set `evidence_verified_in_file` to false if the code/line doesn't exist
+9. **SEARCH BEFORE CLAIMING ABSENCE** - If you claim something doesn't exist (no helper, no validation, no error handling), you MUST show the search you performed:
+   - Use Grep to search for the pattern
+   - Include the search command in your explanation
+   - Example: "Searched for `Grep('validateInput|sanitize', 'src/**/*.ts')` - no results found"
 
 ## Anti-Patterns to Avoid
 

apps/backend/prompts/github/pr_followup_orchestrator.md

@@ -45,13 +45,77 @@ Note: GitHub's API tells us IF there are conflicts but not WHICH files. The find
 
 ## Available Specialist Agents
 
-You have access to these specialist agents via the Task tool:
+You have access to these specialist agents via the Task tool.
+
+**You MUST use the Task tool with the exact `subagent_type` names listed below.** Do NOT use `general-purpose` or any other built-in agent - always use our custom specialists.
+
+### Exact Agent Names (use these in subagent_type)
+
+| Agent | subagent_type value |
+|-------|---------------------|
+| Resolution verifier | `resolution-verifier` |
+| New code reviewer | `new-code-reviewer` |
+| Comment analyzer | `comment-analyzer` |
+| Finding validator | `finding-validator` |
+
+### Task Tool Invocation Format
+
+When you invoke a specialist, use the Task tool like this:
+
+```
+Task(
+  subagent_type="resolution-verifier",
+  prompt="Verify resolution of these previous findings:\n\n1. [SEC-001] SQL injection in user.ts:45 - Check if parameterized queries now used\n2. [QUAL-002] Missing error handling in api.ts:89 - Check if try/catch was added",
+  description="Verify previous findings resolved"
+)
+```
+
+### Example: Complete Follow-up Review Workflow
+
+**Step 1: Verify previous findings are resolved**
+```
+Task(
+  subagent_type="resolution-verifier",
+  prompt="Previous findings to verify:\n\n1. [HIGH] is_impact_finding not propagated (parallel_orchestrator_reviewer.py:630)\n   - Original issue: Field not extracted from structured output\n   - Expected fix: Add is_impact_finding extraction and pass to PRReviewFinding\n\nCheck if the new commits resolve this issue. Examine the actual code.",
+  description="Verify previous findings"
+)
+```
+
+**Step 2: Validate unresolved findings (MANDATORY)**
+```
+Task(
+  subagent_type="finding-validator",
+  prompt="Validate these unresolved findings from resolution-verifier:\n\n1. [HIGH] is_impact_finding not propagated (parallel_orchestrator_reviewer.py:630)\n   - Status from resolution-verifier: unresolved\n   - Claimed issue: Field not extracted\n\nRead the ACTUAL code at line 630 and verify if this issue truly exists. Check for is_impact_finding extraction.",
+  description="Validate unresolved findings"
+)
+```
+
+**Step 3: Review new code (if substantial changes)**
+```
+Task(
+  subagent_type="new-code-reviewer",
+  prompt="Review new code in this diff for issues:\n- Security vulnerabilities\n- Logic errors\n- Edge cases not handled\n\nFocus on files: models.py, parallel_orchestrator_reviewer.py",
+  description="Review new code changes"
+)
+```
+
+### DO NOT USE
+
+- ❌ `general-purpose` - This is a generic built-in agent, NOT our specialist
+- ❌ `Explore` - This is for codebase exploration, NOT for PR review
+- ❌ `Plan` - This is for planning, NOT for PR review
+
+**Always use our specialist agents** (`resolution-verifier`, `new-code-reviewer`, `comment-analyzer`, `finding-validator`) for follow-up review tasks.
+
+---
+
+## Agent Descriptions
 
 ### 1. resolution-verifier
 **Use for**: Verifying whether previous findings have been addressed
 - Analyzes diffs to determine if issues are truly fixed
 - Checks for incomplete or incorrect fixes
-- Provides confidence scores for each resolution
+- Provides evidence-based verification for each resolution
 - **Invoke when**: There are previous findings to verify
 
 ### 2. new-code-reviewer
@@ -93,34 +157,85 @@ Evaluate the follow-up context:
 - Are there previous findings to verify?
 - Are there new comments to process?
 
-### Phase 2: Delegate to Agents
-Based on your analysis, invoke the appropriate agents:
+### Phase 2: Delegate to Agents (USE TASK TOOL)
 
-**Always invoke** `resolution-verifier` if there are previous findings.
+**You MUST use the Task tool to invoke agents.** Simply saying "invoke resolution-verifier" does nothing - you must call the Task tool.
 
-**ALWAYS invoke** `finding-validator` for ALL unresolved findings from resolution-verifier.
-This is CRITICAL to prevent false positives from persisting.
+**If there are previous findings, invoke resolution-verifier FIRST:**
 
-**Invoke** `new-code-reviewer` if:
-- Diff is substantial (>50 lines)
-- Changes touch security-sensitive areas
-- New files were added
-- Complex logic was modified
+```
+Task(
+  subagent_type="resolution-verifier",
+  prompt="Verify resolution of these previous findings:\n\n[COPY THE PREVIOUS FINDINGS LIST HERE WITH IDs, FILES, LINES, AND DESCRIPTIONS]",
+  description="Verify previous findings resolved"
+)
+```
 
-**Invoke** `comment-analyzer` if:
-- There are contributor comments since last review
-- There are AI tool reviews to triage
-- Questions remain unanswered
+**THEN invoke finding-validator for ALL unresolved findings:**
+
+```
+Task(
+  subagent_type="finding-validator",
+  prompt="Validate these unresolved findings:\n\n[COPY THE UNRESOLVED FINDINGS FROM RESOLUTION-VERIFIER]",
+  description="Validate unresolved findings"
+)
+```
+
+**Invoke new-code-reviewer if substantial changes:**
+
+```
+Task(
+  subagent_type="new-code-reviewer",
+  prompt="Review new code changes:\n\n[INCLUDE FILE LIST AND KEY CHANGES]",
+  description="Review new code"
+)
+```
+
+**Invoke comment-analyzer if there are comments:**
+
+```
+Task(
+  subagent_type="comment-analyzer",
+  prompt="Analyze these comments:\n\n[INCLUDE COMMENT LIST]",
+  description="Analyze comments"
+)
+```
+
+### Decision Matrix
+
+| Condition | Agent to Invoke |
+|-----------|-----------------|
+| Previous findings exist | `resolution-verifier` (ALWAYS) |
+| Unresolved findings exist | `finding-validator` (ALWAYS - MANDATORY) |
+| Diff > 50 lines | `new-code-reviewer` |
+| New comments exist | `comment-analyzer` |
+
+### Phase 3: Validate ALL Findings (MANDATORY)
+
+**⚠️ ABSOLUTE RULE: You MUST invoke finding-validator for EVERY finding, regardless of severity.**
+This includes unresolved findings from resolution-verifier AND any new findings from new-code-reviewer.
+- CRITICAL/HIGH/MEDIUM/LOW: ALL must be validated
+- There are NO exceptions — every finding the user sees must be independently verified
+
+After resolution-verifier and new-code-reviewer return their findings:
+1. **Batch findings for validation:**
+   - For ≤10 findings: Send all to finding-validator in one call
+   - For >10 findings: Group by file or category, invoke 2-4 validator calls in parallel
+   - This reduces overhead while maintaining thorough validation
 
-### Phase 3: Validate Unresolved Findings
-After resolution-verifier returns findings marked as unresolved:
-1. Pass ALL unresolved findings to finding-validator
 2. finding-validator will read the actual code at each location
 3. For each finding, it returns:
-   - `confirmed_valid`: Issue IS real → keep as unresolved
+   - `confirmed_valid`: Issue IS real → keep as finding
    - `dismissed_false_positive`: Original finding was WRONG → remove from findings
    - `needs_human_review`: Cannot determine → flag for human
 
+**Every finding in the final output MUST have:**
+- `validation_status`: One of "confirmed_valid" or "needs_human_review"
+- `validation_evidence`: The actual code snippet examined during validation
+- `validation_explanation`: Why the finding was confirmed or flagged
+
+**If any finding is missing validation_status in the final output, the review is INVALID.**
+
 ### Phase 4: Synthesize Results
 After all agents complete:
 1. Combine resolution verifications
@@ -177,9 +292,10 @@ After all agents complete:
 ## Cross-Validation
 
 When multiple agents report on the same area:
-- **Agreement boosts confidence**: If resolution-verifier and new-code-reviewer both flag an issue, increase severity
+- **Agreement strengthens evidence**: If resolution-verifier and new-code-reviewer both flag an issue, this is strong signal
 - **Conflicts need resolution**: If agents disagree, investigate and document your reasoning
 - **Track consensus**: Note which findings have cross-agent validation
+- **Evidence-based, not confidence-based**: Multiple agents agreeing doesn't skip validation - all findings still verified
 
 ## Output Format
 
@@ -198,16 +314,14 @@ Provide your synthesis as a structured response matching the ParallelFollowupRes
       "validation_status": "confirmed_valid",
       "code_evidence": "const query = `SELECT * FROM users WHERE id = ${userId}`;",
       "line_range": [45, 45],
-      "explanation": "SQL injection is present - user input is concatenated...",
-      "confidence": 0.92
+      "explanation": "SQL injection is present - user input is concatenated directly into query"
     },
     {
       "finding_id": "QUAL-002",
       "validation_status": "dismissed_false_positive",
       "code_evidence": "const sanitized = DOMPurify.sanitize(data);",
       "line_range": [23, 26],
-      "explanation": "Original finding claimed XSS but code uses DOMPurify...",
-      "confidence": 0.88
+      "explanation": "Original finding claimed XSS but code uses DOMPurify for sanitization"
     }
   ],
   "new_findings": [...],

apps/backend/prompts/github/pr_logic_agent.md

@@ -6,6 +6,83 @@ You are a focused logic and correctness review agent. You have been spawned by t
 
 Verify that the code logic is correct, handles all edge cases, and doesn't introduce subtle bugs. Focus ONLY on logic and correctness issues - not style, security, or general quality.
 
+## Phase 1: Understand the PR Intent (BEFORE Looking for Issues)
+
+**MANDATORY** - Before searching for issues, understand what this PR is trying to accomplish.
+
+1. **Read the provided context**
+   - PR description: What does the author say this does?
+   - Changed files: What areas of code are affected?
+   - Commits: How did the PR evolve?
+
+2. **Identify the change type**
+   - Bug fix: Correcting broken behavior
+   - New feature: Adding new capability
+   - Refactor: Restructuring without behavior change
+   - Performance: Optimizing existing code
+   - Cleanup: Removing dead code or improving organization
+
+3. **State your understanding** (include in your analysis)
+   ```
+   PR INTENT: This PR [verb] [what] by [how].
+   RISK AREAS: [what could go wrong specific to this change type]
+   ```
+
+**Only AFTER completing Phase 1, proceed to looking for issues.**
+
+Why this matters: Understanding intent prevents flagging intentional design decisions as bugs.
+
+## TRIGGER-DRIVEN EXPLORATION (CHECK YOUR DELEGATION PROMPT)
+
+**FIRST**: Check if your delegation prompt contains a `TRIGGER:` instruction.
+
+- **If TRIGGER is present** → Exploration is **MANDATORY**, even if the diff looks correct
+- **If no TRIGGER** → Use your judgment to explore or not
+
+### How to Explore (Bounded)
+
+1. **Read the trigger** - What pattern did the orchestrator identify?
+2. **Form the specific question** - "Do callers handle the new return type?" (not "what do callers do?")
+3. **Use Grep** to find call sites of the changed function/method
+4. **Use Read** to examine 3-5 callers
+5. **Answer the question** - Yes (report issue) or No (move on)
+6. **Stop** - Do not explore callers of callers (depth > 1)
+
+### Trigger-Specific Questions
+
+| Trigger | What to Check in Callers |
+|---------|-------------------------|
+| **Output contract changed** | Do callers assume the old return type/structure? |
+| **Input contract changed** | Do callers pass the old arguments/defaults? |
+| **Behavioral contract changed** | Does code after the call assume old ordering/timing? |
+| **Side effect removed** | Did callers depend on the removed effect? |
+| **Failure contract changed** | Can callers handle the new failure mode? |
+| **Null contract changed** | Do callers have explicit null checks or tri-state logic? |
+
+### Example Exploration
+
+```
+TRIGGER: Output contract changed (array → single object)
+QUESTION: Do callers use array methods?
+
+1. Grep for "getUserSettings(" → found 8 call sites
+2. Read dashboard.tsx:45 → uses .find() on result → ISSUE
+3. Read profile.tsx:23 → uses result.email directly → OK
+4. Read settings.tsx:67 → uses .map() on result → ISSUE
+5. STOP - Found 2 confirmed issues, pattern established
+
+FINDINGS:
+- dashboard.tsx:45 - uses .find() which doesn't exist on object
+- settings.tsx:67 - uses .map() which doesn't exist on object
+```
+
+### When NO Trigger is Given
+
+If the orchestrator doesn't specify a trigger, use your judgment:
+- Focus on the changed code first
+- Only explore callers if you suspect an issue from the diff
+- Don't explore "just to be thorough"
+
 ## CRITICAL: PR Scope and Context
 
 ### What IS in scope (report these issues):
@@ -140,6 +217,92 @@ Before reporting ANY finding, you MUST:
 
 **Your evidence must prove the issue exists - not just that you suspect it.**
 
+## Evidence Requirements (MANDATORY)
+
+Every finding you report MUST include a `verification` object with ALL of these fields:
+
+### Required Fields
+
+**code_examined** (string, min 1 character)
+The **exact code snippet** you examined. Copy-paste directly from the file:
+```
+CORRECT: "cursor.execute(f'SELECT * FROM users WHERE id={user_id}')"
+WRONG:   "SQL query that uses string interpolation"
+```
+
+**line_range_examined** (array of 2 integers)
+The exact line numbers [start, end] where the issue exists:
+```
+CORRECT: [45, 47]
+WRONG:   [1, 100]  // Too broad - you didn't examine all 100 lines
+```
+
+**verification_method** (one of these exact values)
+How you verified the issue:
+- `"direct_code_inspection"` - Found the issue directly in the code at the location
+- `"cross_file_trace"` - Traced through imports/calls to confirm the issue
+- `"test_verification"` - Verified through examination of test code
+- `"dependency_analysis"` - Verified through analyzing dependencies
+
+### Conditional Fields
+
+**is_impact_finding** (boolean, default false)
+Set to `true` ONLY if this finding is about impact on OTHER files (not the changed file):
+```
+TRUE:  "This change in utils.ts breaks the caller in auth.ts"
+FALSE: "This code in utils.ts has a bug" (issue is in the changed file)
+```
+
+**checked_for_handling_elsewhere** (boolean, default false)
+For ANY "missing X" claim (missing null check, missing bounds check, missing edge case handling):
+- Set `true` ONLY if you used Grep/Read tools to verify X is not handled elsewhere
+- Set `false` if you didn't search other files
+- **When true, include the search in your description:**
+  - "Searched `Grep('if.*null|!= null|\?\?', 'src/utils/')` - no null check found"
+  - "Checked callers via `Grep('processArray\(', '**/*.ts')` - none validate input"
+
+```
+TRUE:  "Searched for null checks in this file and callers - none found"
+FALSE: "This function should check for null" (didn't verify it's missing)
+```
+
+**If you cannot provide real evidence, you do not have a verified finding - do not report it.**
+
+**Search Before Claiming Absence:** Never claim a check is "missing" without searching for it first. Validation may exist in callers, guards, or type system constraints.
+
+## Valid Outputs
+
+Finding issues is NOT the goal. Accurate review is the goal.
+
+### Valid: No Significant Issues Found
+If the code is well-implemented, say so:
+```json
+{
+  "findings": [],
+  "summary": "Reviewed [files]. No logic issues found. The implementation correctly [positive observation about the code]."
+}
+```
+
+### Valid: Only Low-Severity Suggestions
+Minor improvements that don't block merge:
+```json
+{
+  "findings": [
+    {"severity": "low", "title": "Consider extracting magic number to constant", ...}
+  ],
+  "summary": "Code is sound. One minor suggestion for readability."
+}
+```
+
+### INVALID: Forced Issues
+Do NOT report issues just to have something to say:
+- Theoretical edge cases without evidence they're reachable
+- Style preferences not backed by project conventions
+- "Could be improved" without concrete problem
+- Pre-existing issues not introduced by this PR
+
+**Reporting nothing is better than reporting noise.** False positives erode trust faster than false negatives.
+
 ## Code Patterns to Flag
 
 ### Off-By-One Errors
@@ -217,6 +380,13 @@ Provide findings in JSON format:
     "description": "Loop uses `i < arr.length - 1` which skips the last element. For array [1, 2, 3], only processes [1, 2].",
     "category": "logic",
     "severity": "high",
+    "verification": {
+      "code_examined": "for (let i = 0; i < arr.length - 1; i++) { result.push(arr[i]); }",
+      "line_range_examined": [23, 25],
+      "verification_method": "direct_code_inspection"
+    },
+    "is_impact_finding": false,
+    "checked_for_handling_elsewhere": false,
     "example": {
       "input": "[1, 2, 3]",
       "actual_output": "Processes [1, 2]",
@@ -232,6 +402,13 @@ Provide findings in JSON format:
     "description": "Multiple async operations increment `count` without synchronization. With 10 concurrent increments, final count could be less than 10.",
     "category": "logic",
     "severity": "critical",
+    "verification": {
+      "code_examined": "await Promise.all(items.map(async () => { count++; }));",
+      "line_range_examined": [45, 47],
+      "verification_method": "direct_code_inspection"
+    },
+    "is_impact_finding": false,
+    "checked_for_handling_elsewhere": false,
     "example": {
       "input": "10 concurrent increments",
       "actual_output": "count might be 7, 8, or 9",

apps/backend/prompts/github/pr_parallel_orchestrator.md

@@ -2,6 +2,17 @@
 
 You are an expert PR reviewer orchestrating a comprehensive, parallel code review. Your role is to analyze the PR, delegate to specialized review agents, and synthesize their findings into a final verdict.
 
+## CRITICAL: Tool Execution Strategy
+
+**IMPORTANT: Execute tool calls ONE AT A TIME, waiting for each result before making the next call.**
+
+When you need to use multiple tools (Read, Grep, Glob, Task):
+- ✅ Make ONE tool call, wait for the result
+- ✅ Process the result, then make the NEXT tool call
+- ❌ Do NOT make multiple tool calls in a single response
+
+**Why this matters:** Parallel tool execution can cause API errors when some tools fail while others succeed. Sequential execution ensures reliable operation and proper error handling.
+
 ## Core Principle
 
 **YOU decide which agents to invoke based on YOUR analysis of the PR.** There are no programmatic rules - you evaluate the PR's content, complexity, and risk areas, then delegate to the appropriate specialists.
@@ -45,6 +56,7 @@ You have access to these specialized review agents via the Task tool:
 ### quality-reviewer
 **Description**: Code quality expert for complexity, duplication, error handling, maintainability, and pattern adherence.
 **When to use**: PRs with complex logic, large functions, new patterns, or significant business logic changes.
+**Special check**: If the PR adds similar logic in multiple files, flag it as a candidate for a shared utility.
 
 ### logic-reviewer
 **Description**: Logic and correctness specialist for algorithm verification, edge cases, state management, and race conditions.
@@ -62,9 +74,314 @@ You have access to these specialized review agents via the Task tool:
 **Description**: Finding validation specialist that re-investigates findings to confirm they are real issues, not false positives.
 **When to use**: After ALL specialist agents have reported their findings. Invoke for EVERY finding to validate it exists in the actual code.
 
+## CRITICAL: How to Invoke Specialist Agents
+
+**You MUST use the Task tool with the exact `subagent_type` names listed below.** Do NOT use `general-purpose` or any other built-in agent - always use our custom specialists.
+
+### Exact Agent Names (use these in subagent_type)
+
+| Agent | subagent_type value |
+|-------|---------------------|
+| Security reviewer | `security-reviewer` |
+| Quality reviewer | `quality-reviewer` |
+| Logic reviewer | `logic-reviewer` |
+| Codebase fit reviewer | `codebase-fit-reviewer` |
+| AI comment triage | `ai-triage-reviewer` |
+| Finding validator | `finding-validator` |
+
+### Task Tool Invocation Format
+
+When you invoke a specialist, use the Task tool like this:
+
+```
+Task(
+  subagent_type="security-reviewer",
+  prompt="This PR adds /api/login endpoint. Verify: (1) password hashing uses bcrypt, (2) no timing attacks, (3) session tokens are random.",
+  description="Security review of auth changes"
+)
+```
+
+### Example: Invoking Multiple Specialists in Parallel
+
+For a PR that adds authentication, invoke multiple agents in the SAME response:
+
+```
+Task(
+  subagent_type="security-reviewer",
+  prompt="This PR adds password auth to /api/login. Verify password hashing, timing attacks, token generation.",
+  description="Security review"
+)
+
+Task(
+  subagent_type="logic-reviewer",
+  prompt="This PR implements login with sessions. Check edge cases: empty password, wrong user, concurrent logins.",
+  description="Logic review"
+)
+
+Task(
+  subagent_type="quality-reviewer",
+  prompt="This PR adds auth code. Verify error messages don't leak info, no password logging.",
+  description="Quality review"
+)
+```
+
+### DO NOT USE
+
+- ❌ `general-purpose` - This is a generic built-in agent, NOT our specialist
+- ❌ `Explore` - This is for codebase exploration, NOT for PR review
+- ❌ `Plan` - This is for planning, NOT for PR review
+
+**Always use our specialist agents** (`security-reviewer`, `logic-reviewer`, `quality-reviewer`, `codebase-fit-reviewer`, `ai-triage-reviewer`, `finding-validator`) for PR review tasks.
+
 ## Your Workflow
 
-### Phase 1: Analysis
+### Phase 0: Understand the PR Holistically (BEFORE Delegation)
+
+**MANDATORY** - Before invoking ANY specialist agent, you MUST understand what this PR is trying to accomplish.
+
+1. **Check for Merge Conflicts FIRST** - If `has_merge_conflicts` is `true` in the PR context:
+   - Add a CRITICAL finding immediately
+   - Include in your PR UNDERSTANDING output: "⚠️ MERGE CONFLICTS: PR cannot be merged until resolved"
+   - Still proceed with review (conflicts don't skip the review)
+
+2. **Read the PR Description** - What is the stated goal?
+3. **Review the Commit Timeline** - How did the PR evolve? Were issues fixed in later commits?
+4. **Examine Related Files** - What tests, imports, and dependents are affected?
+5. **Identify the PR Intent** - Bug fix? Feature? Refactor? Breaking change?
+
+**Create a mental model:**
+- "This PR [adds/fixes/refactors] X by [changing] Y, which is [used by/depends on] Z"
+- Identify what COULD go wrong based on the change type
+
+**Output your synthesis before delegating:**
+```
+PR UNDERSTANDING:
+- Intent: [one sentence describing what this PR does]
+- Critical changes: [2-3 most important files and what changed]
+- Risk areas: [security, logic, breaking changes, etc.]
+- Files to verify: [related files that might be impacted]
+```
+
+**Only AFTER completing Phase 0, proceed to Phase 1 (Trigger Detection).**
+
+## What the Diff Is For
+
+**The diff is the question, not the answer.**
+
+The code changes show what the author is asking you to review. Before delegating to specialists:
+
+### Answer These Questions
+1. **What is this diff trying to accomplish?**
+   - Read the PR description
+   - Look at the file names and change patterns
+   - Understand the author's intent
+
+2. **What could go wrong with this approach?**
+   - Security: Does it handle user input? Auth? Secrets?
+   - Logic: Are there edge cases? State changes? Async issues?
+   - Quality: Is it maintainable? Does it follow patterns?
+   - Fit: Does it reinvent existing utilities?
+
+3. **What should specialists verify?**
+   - Specific concerns, not generic "check for bugs"
+   - Files to examine beyond the changed files
+   - Questions the diff raises but doesn't answer
+
+### Delegate with Context
+
+When invoking specialists, include:
+- Your synthesis of what the PR does
+- Specific concerns to investigate
+- Related files they should examine
+
+**Never delegate blind.** "Review this code" without context leads to noise. "This PR adds user auth - verify password hashing and session management" leads to signal.
+
+## MANDATORY EXPLORATION TRIGGERS (Language-Agnostic)
+
+**CRITICAL**: Certain change patterns ALWAYS require checking callers/dependents, even if the diff looks correct. The issue may only be visible in how OTHER code uses the changed code.
+
+When you identify these patterns in the diff, instruct specialists to explore direct callers:
+
+### 1. OUTPUT CONTRACT CHANGED
+**Detect:** Function/method returns different value, type, or structure than before
+- Return type changed (array → single item, nullable → non-null, wrapped → unwrapped)
+- Return value semantics changed (empty array vs null, false vs undefined)
+- Structure changed (object shape different, fields added/removed)
+
+**Instruct specialists:** "Check how callers USE the return value. Look for operations that assume the old structure."
+
+**Stop when:** Checked 3-5 direct callers OR found a confirmed issue
+
+### 2. INPUT CONTRACT CHANGED
+**Detect:** Parameters added, removed, reordered, or defaults changed
+- New required parameters
+- Default parameter values changed
+- Parameter types changed
+
+**Instruct specialists:** "Find callers that don't pass [parameter] - they rely on the old default. Check callers passing arguments in the old order."
+
+**Stop when:** Identified implicit callers (those not passing the changed parameter)
+
+### 3. BEHAVIORAL CONTRACT CHANGED
+**Detect:** Same inputs/outputs but different internal behavior
+- Operations reordered (sequential → parallel, different order)
+- Timing changed (sync → async, immediate → deferred)
+- Performance characteristics changed (O(1) → O(n), single query → N+1)
+
+**Instruct specialists:** "Check if code AFTER the call assumes the old behavior (ordering, timing, completion)."
+
+**Stop when:** Verified 3-5 call sites for ordering dependencies
+
+### 4. SIDE EFFECT CONTRACT CHANGED
+**Detect:** Observable effects added or removed
+- No longer writes to cache/database/file
+- No longer emits events/notifications
+- No longer cleans up related resources (sessions, connections)
+
+**Instruct specialists:** "Check if callers depended on the removed effect. Verify replacement mechanism actually exists."
+
+**Stop when:** Confirmed callers don't depend on removed effect OR found dependency
+
+### 5. FAILURE CONTRACT CHANGED
+**Detect:** How the function handles errors changed
+- Now throws/returns error where it didn't before (permissive → strict)
+- Now succeeds silently where it used to fail (strict → permissive)
+- Different error type/code returned
+- Return value changes on failure (e.g., `return true` → `return false`, `return null` → `throw Error`)
+
+**Examples:**
+- `validateEmail()` used to return `true` on service error (permissive), now returns `false` (strict)
+- `processPayment()` used to throw on failure, now returns `{success: false, error: ...}` (different failure mode)
+- `fetchUser()` used to return `null` for not-found, now throws `NotFoundError` (exception vs return value)
+
+**Instruct specialists:** "Check if callers can handle the new failure mode. Look for missing error handling in critical paths. Verify callers don't assume the old success/failure behavior."
+
+**Stop when:** Verified caller resilience OR found unhandled failure case
+
+### 6. NULL/UNDEFINED CONTRACT CHANGED
+**Detect:** Null handling changed
+- Now returns null where it returned a value before
+- Now returns a value where it returned null before
+- Null checks added or removed
+
+**Instruct specialists:** "Find callers with explicit null checks (`=== null`, `!= null`). Check for tri-state logic (true/false/null as different states)."
+
+**Stop when:** Checked callers for null-dependent logic
+
+### Phase 1: Detect Semantic Change Patterns (MANDATORY)
+
+**MANDATORY** - After understanding the PR, you MUST analyze the diff for semantic contract changes before delegating to ANY specialist.
+
+**For EACH changed function, method, or component in the diff, check:**
+
+1. Does it return something different? → **OUTPUT CONTRACT CHANGED**
+2. Do its parameters/defaults change? → **INPUT CONTRACT CHANGED**
+3. Does it behave differently internally? → **BEHAVIORAL CONTRACT CHANGED**
+4. Were side effects added or removed? → **SIDE EFFECT CONTRACT CHANGED**
+5. Does it handle errors differently? → **FAILURE CONTRACT CHANGED**
+6. Did null/undefined handling change? → **NULL CONTRACT CHANGED**
+
+**Output your analysis explicitly:**
+```
+TRIGGER DETECTION:
+- getUserSettings(): OUTPUT CONTRACT CHANGED (returns object instead of array)
+- processOrder(): BEHAVIORAL CONTRACT CHANGED (sequential → parallel execution)
+- validateInput(): NO TRIGGERS (internal logic change only, same contract)
+```
+
+**If NO triggers apply:**
+```
+TRIGGER DETECTION: No semantic contract changes detected.
+Changes are internal-only (logic, style, CSS, refactor without API changes).
+```
+
+**This phase is MANDATORY. Do not skip it even for "simple" PRs.**
+
+## ENFORCEMENT: Required Output Before Delegation
+
+**You CANNOT invoke the Task tool until you have output BOTH Phase 0 and Phase 1.**
+
+Your response MUST include these sections BEFORE any Task tool invocation:
+
+```
+PR UNDERSTANDING:
+- Intent: [one sentence describing what this PR does]
+- Critical changes: [2-3 most important files and what changed]
+- Risk areas: [security, logic, breaking changes, etc.]
+- Files to verify: [related files that might be impacted]
+
+TRIGGER DETECTION:
+- [function1](): [TRIGGER_TYPE] (description) OR NO TRIGGERS
+- [function2](): [TRIGGER_TYPE] (description) OR NO TRIGGERS
+...
+```
+
+**Why this is enforced:** Without understanding intent, specialists receive context-free code and produce false positives. Without trigger detection, contract-breaking changes slip through because "the diff looks fine."
+
+**Only AFTER outputting both sections, proceed to Phase 2 (Analysis).**
+
+### Trigger Detection Examples
+
+**Function signature change:**
+```
+TRIGGER DETECTION:
+- getUser(id): INPUT CONTRACT CHANGED (added optional `options` param with default)
+- getUser(id): OUTPUT CONTRACT CHANGED (returns User instead of User[])
+```
+
+**Error handling change:**
+```
+TRIGGER DETECTION:
+- validateEmail(): FAILURE CONTRACT CHANGED (now returns false on service error instead of true)
+```
+
+**Refactor with no contract change:**
+```
+TRIGGER DETECTION: No semantic contract changes detected.
+extractHelper() is a new internal function, no existing callers.
+processData() internal logic changed but input/output contract is identical.
+```
+
+### How Triggers Flow to Specialists (MANDATORY)
+
+**CRITICAL: When triggers ARE detected, you MUST include them in delegation prompts.**
+
+This is NOT optional. Every Task invocation MUST follow this checklist:
+
+**Pre-Delegation Checklist (verify before EACH Task call):**
+```
+□ Does the prompt include PR intent summary?
+□ Does the prompt include specific concerns to verify?
+□ If triggers were detected → Does the prompt include "TRIGGER: [TYPE] - [description]"?
+□ If triggers were detected → Does the prompt include "Stop when: [condition]"?
+□ Are known callers/dependents included (if available in PR context)?
+```
+
+**Required Format When Triggers Exist:**
+```
+Task(
+  subagent_type="logic-reviewer",
+  prompt="This PR changes getUserSettings() to return a single object instead of an array.
+
+          TRIGGER: OUTPUT CONTRACT CHANGED - returns object instead of array
+          EXPLORATION REQUIRED: Check 3-5 direct callers for array method usage (.map, .filter, .find, .forEach).
+          Stop when: Found callers using array methods OR verified 5 callers handle it correctly.
+
+          Known callers: [list from PR context if available]",
+  description="Logic review - output contract change"
+)
+```
+
+**If you detect triggers in Phase 1 but don't pass them to specialists, the review is INCOMPLETE.**
+
+### Exploration Boundaries
+
+❌ Explore because "I want to be thorough"
+❌ Check callers of callers (depth > 1) unless a confirmed issue needs tracing
+❌ Keep exploring after the trigger-specific question is answered
+❌ Skip exploration because "the diff looks fine" - triggers override this
+
+### Phase 2: Analysis
 
 Analyze the PR thoroughly:
 
@@ -73,7 +390,7 @@ Analyze the PR thoroughly:
 3. **Identify Risk Areas**: Security-sensitive? Complex logic? New patterns?
 4. **Check for AI Comments**: Are there existing AI reviewer comments to triage?
 
-### Phase 2: Delegation
+### Phase 3: Delegation
 
 Based on your analysis, invoke the appropriate specialist agents. You can invoke multiple agents in parallel by calling the Task tool multiple times in the same response.
 
@@ -87,36 +404,124 @@ Based on your analysis, invoke the appropriate specialist agents. You can invoke
 - **New patterns/large additions**: Always invoke codebase-fit-reviewer.
 - **Existing AI comments**: Always invoke ai-triage-reviewer.
 
-**Example delegation**:
+**Context-Rich Delegation (CRITICAL):**
+
+When you invoke a specialist, your prompt to them MUST include:
+
+1. **PR Intent Summary** - One sentence from your Phase 0 synthesis
+   - Example: "This PR adds JWT authentication to the API endpoints"
+
+2. **Specific Concerns** - What you want them to verify
+   - Security: "Verify token validation, check for secret exposure"
+   - Logic: "Check for race conditions in token refresh"
+   - Quality: "Verify error handling in auth middleware"
+   - Fit: "Check if existing auth helpers were considered"
+
+3. **Files of Interest** - Beyond just the changed files
+   - "Also examine tests/auth.test.ts for coverage gaps"
+   - "Check if utils/crypto.ts has relevant helpers"
+
+4. **Trigger Instructions** (from Phase 1) - **MANDATORY if triggers were detected:**
+   - "TRIGGER: [TYPE] - [description of what changed]"
+   - "EXPLORATION REQUIRED: [what to check in callers]"
+   - "Stop when: [condition to stop exploring]"
+   - **You MUST include ALL THREE lines for each trigger**
+   - If no triggers were detected in Phase 1, you may omit this section.
+
+5. **Known Callers/Dependents** (from PR context) - If the PR context includes related files:
+   - Include any known callers of the changed functions
+   - Include files that import/depend on the changed files
+   - Example: "Known callers: dashboard.tsx:45, settings.tsx:67, api/users.ts:23"
+   - This gives specialists starting points for exploration instead of searching blind
+
+**Anti-pattern:** "Review src/auth/login.ts for security issues"
+**Good pattern:** "This PR adds password-based login. Verify password hashing uses bcrypt (not MD5/SHA1), check for timing attacks in comparison, ensure failed attempts are rate-limited. Also check if existing RateLimiter in utils/ was considered."
+
+**Example delegation with triggers and known callers:**
+
 ```
-For a PR adding a new authentication endpoint:
-- Invoke security-reviewer for auth logic
-- Invoke quality-reviewer for code structure
-- Invoke logic-reviewer for edge cases in auth flow
+Task(
+  subagent_type="logic-reviewer",
+  prompt="This PR changes getUserSettings() to return a single object instead of an array.
+          TRIGGER: Output contract changed.
+          Check 3-5 direct callers for array method usage (.map, .filter, .find, .forEach).
+          Stop when: Found callers using array methods OR verified 5 callers handle it correctly.
+          Known callers from PR context: dashboard.tsx:45, settings.tsx:67, components/UserPanel.tsx:89
+          Also verify edge cases in the new implementation.",
+  description="Logic review - output contract change"
+)
 ```
 
-### Phase 3: Synthesis
+**Example delegation without triggers:**
+
+```
+Task(
+  subagent_type="security-reviewer",
+  prompt="This PR adds /api/login endpoint with password auth. Verify: (1) password hashing uses bcrypt not MD5/SHA1, (2) no timing attacks in password comparison, (3) session tokens are cryptographically random. Also check utils/crypto.ts for existing helpers.",
+  description="Security review of auth endpoint"
+)
+
+Task(
+  subagent_type="quality-reviewer",
+  prompt="This PR adds auth code. Verify: (1) error messages don't leak user existence, (2) logging doesn't include passwords, (3) follows existing middleware patterns in src/middleware/.",
+  description="Quality review of auth code"
+)
+```
+
+### Phase 4: Synthesis
 
 After receiving agent results, synthesize findings:
 
-1. **Aggregate**: Collect all findings from all agents
+1. **Aggregate**: Collect ALL findings from all agents (no filtering at this stage!)
 2. **Cross-validate** (see "Multi-Agent Agreement" section):
    - Group findings by (file, line, category)
-   - If 2+ agents report same issue → merge into one, boost confidence by +0.15
+   - If 2+ agents report same issue → merge into one finding
    - Set `cross_validated: true` and populate `source_agents` list
    - Track agreed finding IDs in `agent_agreement.agreed_findings`
 3. **Deduplicate**: Remove overlapping findings (same file + line + issue type)
-4. **Route by Confidence** (see "Confidence Tiers" section):
-   - HIGH (>=0.8): Include as-is
-   - MEDIUM (0.5-0.8): Include with "[Potential]" prefix
-   - LOW (<0.5): Log and exclude
-5. **Generate Verdict**: Based on severity of remaining findings
+4. **Send ALL to Validator**: Every finding goes to finding-validator (see Phase 4.5)
+   - Do NOT filter by confidence before validation
+   - Do NOT drop "low confidence" findings
+   - The validator determines what's real, not the orchestrator
+5. **Generate Verdict**: Based on VALIDATED findings only
 
-### Phase 3.5: Finding Validation (CRITICAL - Prevent False Positives)
+### Phase 4.5: Finding Validation (CRITICAL - Prevent False Positives)
 
-**MANDATORY STEP** - After synthesis, validate ALL findings before generating verdict:
+**MANDATORY STEP** - After synthesis, validate ALL findings before generating verdict.
+
+**⚠️ ABSOLUTE RULE: You MUST invoke finding-validator for EVERY finding, regardless of severity.**
+- CRITICAL findings: MUST validate
+- HIGH findings: MUST validate
+- MEDIUM findings: MUST validate
+- LOW findings: MUST validate
+- Style suggestions: MUST validate
+
+There are NO exceptions. A LOW-severity finding that is a false positive is still noise for the developer. Every finding the user sees must have been independently verified against the actual code. Do NOT skip validation for any finding — not for "obvious" ones, not for "style" ones, not for "low-risk" ones. If it appears in the findings array, it must have a `validation_status`.
+
+1. **Invoke finding-validator** for findings from specialist agents:
+
+   **For small PRs (≤10 findings):** Invoke validator once with ALL findings in a single prompt.
+
+   **For large PRs (>10 findings):** Batch findings by file or category:
+   - Group findings in the same file together (validator can read file once)
+   - Group findings of the same category together (security, quality, logic)
+   - Invoke 2-4 validator calls in parallel, each handling a batch
+
+   **Example batch invocation:**
+   ```
+   Task(
+     subagent_type="finding-validator",
+     prompt="Validate these 5 findings in src/auth/:\n
+             1. SEC-001: SQL injection at login.ts:45\n
+             2. SEC-002: Hardcoded secret at config.ts:12\n
+             3. QUAL-001: Missing error handling at login.ts:78\n
+             4. QUAL-002: Code duplication at auth.ts:90\n
+             5. LOGIC-001: Off-by-one at validate.ts:23\n
+             Read the actual code and validate each. Return a validation result for EACH finding.",
+     description="Validate auth-related findings batch"
+   )
+   ```
 
-1. **Invoke finding-validator** for EACH finding from specialist agents
 2. For each finding, the validator returns one of:
    - `confirmed_valid` - Issue IS real, keep in findings list
    - `dismissed_false_positive` - Original finding was WRONG, remove from findings
@@ -131,65 +536,92 @@ After receiving agent results, synthesize findings:
    - A finding dismissed as false positive does NOT count toward verdict
    - Only confirmed issues determine severity
 
-**Why this matters:** Specialist agents sometimes flag issues that don't exist in the actual code. The validator reads the code with fresh eyes to catch these false positives before they're reported.
+5. **Every finding in the final output MUST have:**
+   - `validation_status`: One of "confirmed_valid" or "needs_human_review"
+   - `validation_evidence`: The actual code snippet examined during validation
+   - `validation_explanation`: Why the finding was confirmed or flagged
+
+**If any finding is missing validation_status in the final output, the review is INVALID.**
+
+**Why this matters:** Specialist agents sometimes flag issues that don't exist in the actual code. The validator reads the code with fresh eyes to catch these false positives before they're reported. This applies to ALL severity levels — a LOW false positive wastes developer time just like a HIGH one.
 
 **Example workflow:**
 ```
-Specialist finds 3 issues → finding-validator validates each →
-Result: 2 confirmed, 1 dismissed → Verdict based on 2 issues
+Specialist finds 3 issues (1 MEDIUM, 2 LOW) → finding-validator validates ALL 3 →
+Result: 2 confirmed, 1 dismissed → Verdict based on 2 validated issues
 ```
 
-## Confidence Tiers
+**Example validation invocation:**
+```
+Task(
+  subagent_type="finding-validator",
+  prompt="Validate this finding: 'SQL injection in user lookup at src/auth/login.ts:45'. Read the actual code at that location and determine if the issue exists. Return confirmed_valid, dismissed_false_positive, or needs_human_review.",
+  description="Validate SQL injection finding"
+)
+```
 
-After validation, findings are routed based on confidence scores:
+## Evidence-Based Validation (NOT Confidence-Based)
 
-| Tier | Score Range | Treatment |
-|------|-------------|-----------|
-| HIGH | >= 0.8 | Included as reported, affects verdict |
-| MEDIUM | 0.5 - 0.8 | Included with "[Potential]" prefix, affects verdict |
-| LOW | < 0.5 | Logged for monitoring, excluded from output |
+**CRITICAL: This system does NOT use confidence scores to filter findings.**
 
-**Guidelines for assigning confidence:**
-- 0.9+ : Direct evidence in code, multiple indicators, clear violation
-- 0.8-0.9 : Strong evidence, clear pattern, high certainty
-- 0.6-0.8 : Likely issue but some uncertainty, may need context
-- 0.4-0.6 : Possible issue, limited evidence, context-dependent
-- < 0.4 : Speculation, no direct evidence, likely false positive
+All findings are validated against actual code. The validator determines what's real:
+
+| Validation Status | Meaning | Treatment |
+|-------------------|---------|-----------|
+| `confirmed_valid` | Evidence proves issue EXISTS | Include in findings |
+| `dismissed_false_positive` | Evidence proves issue does NOT exist | Move to `dismissed_findings` |
+| `needs_human_review` | Evidence is ambiguous | Include with flag for human |
+
+**Why evidence-based, not confidence-based:**
+- A "90% confidence" finding can be WRONG (false positive)
+- A "70% confidence" finding can be RIGHT (real issue)
+- Only actual code examination determines validity
+- Confidence scores are subjective; evidence is objective
+
+**What the validator checks:**
+1. Does the problematic code actually exist at the stated location?
+2. Is there mitigation elsewhere that the specialist missed?
+3. Does the finding accurately describe what the code does?
+4. Is this a real issue or a misunderstanding of intent?
 
 **Example:**
-- SQL injection with `userId` in query string: 0.95 (direct evidence)
-- Missing null check where input could be null: 0.75 (likely but depends on callers)
-- "This might cause issues" without specifics: 0.3 (speculation, will be dropped)
+```
+Specialist claims: "SQL injection at line 45"
+Validator reads line 45, finds: parameterized query with $1 placeholder
+Result: dismissed_false_positive - "Code uses parameterized queries, not string concat"
+```
 
 ## Multi-Agent Agreement
 
 When multiple specialist agents flag the same issue (same file + line + category), this is strong signal:
 
-### Confidence Boost
-- If 2+ agents agree: confidence boosted by +0.15 (max 0.95)
-- cross_validated field set to true
-- source_agents lists all agents that flagged the issue
+### Cross-Validation Signal
+- If 2+ agents independently find the same issue → stronger evidence
+- Set `cross_validated: true` on the merged finding
+- Populate `source_agents` with all agents that flagged it
+- This doesn't skip validation - validator still checks the code
 
 ### Why This Matters
-- Independent verification increases certainty
+- Independent verification from different perspectives
 - False positives rarely get flagged by multiple specialized agents
-- Multi-agent agreement often indicates real issues
+- Helps prioritize which findings to fix first
 
 ### Example
 ```
-security-reviewer finds: XSS vulnerability at line 45 (confidence: 0.75)
-quality-reviewer finds: Unsafe string interpolation at line 45 (confidence: 0.70)
+security-reviewer finds: XSS vulnerability at line 45
+quality-reviewer finds: Unsafe string interpolation at line 45
 
-Result: Single finding with confidence 0.90 (0.75 + 0.15 boost)
+Result: Single finding merged
         source_agents: ["security-reviewer", "quality-reviewer"]
         cross_validated: true
+        → Still sent to validator for evidence-based confirmation
 ```
 
 ### Agent Agreement Tracking
 The `agent_agreement` field in structured output tracks:
-- `agreed_findings`: Finding IDs where 2+ agents agreed
-- `conflicting_findings`: Finding IDs where agents disagreed (reserved for future)
-- `resolution_notes`: How conflicts were resolved (reserved for future)
+- `agreed_findings`: Finding IDs where 2+ agents agreed (stronger evidence)
+- `conflicting_findings`: Finding IDs where agents disagreed
+- `resolution_notes`: How conflicts were resolved
 
 **Note:** Agent agreement data is logged for monitoring. The cross-validation results
 are reflected in each finding's source_agents, cross_validated, and confidence fields.
@@ -203,7 +635,7 @@ After synthesis and validation, output your final review in this JSON format:
   "analysis_summary": "Brief description of what you analyzed and why you chose those agents",
   "agents_invoked": ["security-reviewer", "quality-reviewer", "finding-validator"],
   "validation_summary": {
-    "total_findings": 5,
+    "total_findings_from_specialists": 5,
     "confirmed_valid": 3,
     "dismissed_false_positive": 2,
     "needs_human_review": 0
@@ -218,7 +650,6 @@ After synthesis and validation, output your final review in this JSON format:
       "description": "User input directly interpolated into SQL query",
       "category": "security",
       "severity": "critical",
-      "confidence": 0.95,
       "suggested_fix": "Use parameterized queries",
       "fixable": true,
       "source_agents": ["security-reviewer"],
@@ -227,6 +658,17 @@ After synthesis and validation, output your final review in this JSON format:
       "validation_evidence": "Actual code: `const query = 'SELECT * FROM users WHERE id = ' + userId`"
     }
   ],
+  "dismissed_findings": [
+    {
+      "id": "finding-2",
+      "original_title": "Timing attack in token comparison",
+      "original_severity": "low",
+      "original_file": "src/auth/token.ts",
+      "original_line": 120,
+      "dismissal_reason": "Validator found this is a cache check, not authentication decision",
+      "validation_evidence": "Code at line 120: `if (cachedToken === newToken) return cached;` - Only affects caching, not auth"
+    }
+  ],
   "agent_agreement": {
     "agreed_findings": ["finding-1", "finding-3"],
     "conflicting_findings": [],
@@ -237,12 +679,18 @@ After synthesis and validation, output your final review in this JSON format:
 }
 ```
 
-**Note on validation fields:**
-- `validation_summary` at top level tracks validation statistics
-- Each finding includes `validation_status` ("confirmed_valid", "dismissed_false_positive", or "needs_human_review")
-- Each finding includes `validation_evidence` with actual code snippet from validation
-- Only include findings with `validation_status: "confirmed_valid"` or `"needs_human_review"` in the final output
-- Dismissed findings should be removed from the findings array entirely
+**CRITICAL: Transparency Requirements**
+- `findings` array: Contains ONLY `confirmed_valid` and `needs_human_review` findings
+- `dismissed_findings` array: Contains ALL findings that were validated and dismissed as false positives
+  - Users can see what was investigated and why it was dismissed
+  - This prevents hidden filtering and builds trust
+- `validation_summary`: Counts must match: `total = confirmed + dismissed + needs_human_review`
+
+**Evidence-Based Validation:**
+- Every finding in `findings` MUST have `validation_status` and `validation_evidence`
+- Every entry in `dismissed_findings` MUST have `dismissal_reason` and `validation_evidence`
+- If a specialist reported something, it MUST appear in either `findings` OR `dismissed_findings`
+- Nothing should silently disappear
 
 ## Verdict Types (Strict Quality Gates)
 
@@ -261,13 +709,15 @@ We use strict quality gates because AI can fix issues quickly. Only LOW severity
 
 ## Key Principles
 
-1. **YOU Decide**: No hardcoded rules - you analyze and choose agents based on content
-2. **Parallel Execution**: Invoke multiple agents in the same turn for speed
-3. **Thoroughness**: Every PR deserves analysis - never skip because it "looks simple"
-4. **Cross-Validation**: Multiple agents agreeing increases confidence
-5. **High Confidence**: Only report findings with ≥80% confidence
-6. **Actionable**: Every finding must have a specific, actionable fix
-7. **Project Agnostic**: Works for any project type - backend, frontend, fullstack, any language
+1. **Understand First**: Never delegate until you understand PR intent - findings without context lead to false positives
+2. **YOU Decide**: No hardcoded rules - you analyze and choose agents based on content
+3. **Parallel Execution**: Invoke multiple agents in the same turn for speed
+4. **Thoroughness**: Every PR deserves analysis - never skip because it "looks simple"
+5. **Cross-Validation**: Multiple agents agreeing strengthens evidence
+6. **Evidence-Based**: Every finding must be validated against actual code - no filtering by "confidence"
+7. **Transparent**: Include dismissed findings in output so users see complete picture
+8. **Actionable**: Every finding must have a specific, actionable fix
+9. **Project Agnostic**: Works for any project type - backend, frontend, fullstack, any language
 
 ## Remember
 

apps/backend/prompts/github/pr_quality_agent.md

@@ -6,6 +6,82 @@ You are a focused code quality review agent. You have been spawned by the orches
 
 Perform a thorough code quality review of the provided code changes. Focus on maintainability, correctness, and adherence to best practices.
 
+## Phase 1: Understand the PR Intent (BEFORE Looking for Issues)
+
+**MANDATORY** - Before searching for issues, understand what this PR is trying to accomplish.
+
+1. **Read the provided context**
+   - PR description: What does the author say this does?
+   - Changed files: What areas of code are affected?
+   - Commits: How did the PR evolve?
+
+2. **Identify the change type**
+   - Bug fix: Correcting broken behavior
+   - New feature: Adding new capability
+   - Refactor: Restructuring without behavior change
+   - Performance: Optimizing existing code
+   - Cleanup: Removing dead code or improving organization
+
+3. **State your understanding** (include in your analysis)
+   ```
+   PR INTENT: This PR [verb] [what] by [how].
+   RISK AREAS: [what could go wrong specific to this change type]
+   ```
+
+**Only AFTER completing Phase 1, proceed to looking for issues.**
+
+Why this matters: Understanding intent prevents flagging intentional design decisions as bugs.
+
+## TRIGGER-DRIVEN EXPLORATION (CHECK YOUR DELEGATION PROMPT)
+
+**FIRST**: Check if your delegation prompt contains a `TRIGGER:` instruction.
+
+- **If TRIGGER is present** → Exploration is **MANDATORY**, even if the diff looks correct
+- **If no TRIGGER** → Use your judgment to explore or not
+
+### How to Explore (Bounded)
+
+1. **Read the trigger** - What pattern did the orchestrator identify?
+2. **Form the specific question** - "Do callers handle error cases from this function?" (not "what do callers do?")
+3. **Use Grep** to find call sites of the changed function/method
+4. **Use Read** to examine 3-5 callers
+5. **Answer the question** - Yes (report issue) or No (move on)
+6. **Stop** - Do not explore callers of callers (depth > 1)
+
+### Quality-Specific Trigger Questions
+
+| Trigger | Quality Question to Answer |
+|---------|---------------------------|
+| **Output contract changed** | Do callers have proper type handling for the new return type? |
+| **Behavioral contract changed** | Does the timing change cause callers to have race conditions or stale data? |
+| **Side effect removed** | Do callers now need to handle what the function used to do automatically? |
+| **Failure contract changed** | Do callers have proper error handling for the new failure mode? |
+| **Performance changed** | Do callers operate at scale where the performance change compounds? |
+
+### Example Exploration
+
+```
+TRIGGER: Behavioral contract changed (sequential → parallel operations)
+QUESTION: Do callers depend on the old sequential ordering?
+
+1. Grep for "processOrder(" → found 6 call sites
+2. Read checkout.ts:89 → reads database immediately after call → ISSUE (race condition)
+3. Read batch-job.ts:34 → awaits and then processes result → OK
+4. Read api/orders.ts:56 → sends confirmation after call → ISSUE (email before DB write)
+5. STOP - Found 2 quality issues
+
+FINDINGS:
+- checkout.ts:89 - Race condition: reads from DB before parallel write completes
+- api/orders.ts:56 - Email sent before order is persisted (ordering dependency broken)
+```
+
+### When NO Trigger is Given
+
+If the orchestrator doesn't specify a trigger, use your judgment:
+- Focus on quality issues in the changed code first
+- Only explore callers if you suspect an issue from the diff
+- Don't explore "just to be thorough"
+
 ## CRITICAL: PR Scope and Context
 
 ### What IS in scope (report these issues):
@@ -44,6 +120,7 @@ Perform a thorough code quality review of the provided code changes. Focus on ma
 - **Copy-Paste Code**: Similar functions with minor differences
 - **Redundant Implementations**: Re-implementing existing functionality
 - **Should Use Library**: Reinventing standard functionality
+- **PR-Internal Duplication**: Same new logic added to multiple files in this PR (should be a shared utility)
 
 ### 4. Maintainability
 - **Magic Numbers**: Hardcoded numbers without explanation
@@ -141,6 +218,92 @@ Before reporting ANY finding, you MUST:
 
 **Your evidence must prove the issue exists - not just that you suspect it.**
 
+## Evidence Requirements (MANDATORY)
+
+Every finding you report MUST include a `verification` object with ALL of these fields:
+
+### Required Fields
+
+**code_examined** (string, min 1 character)
+The **exact code snippet** you examined. Copy-paste directly from the file:
+```
+CORRECT: "cursor.execute(f'SELECT * FROM users WHERE id={user_id}')"
+WRONG:   "SQL query that uses string interpolation"
+```
+
+**line_range_examined** (array of 2 integers)
+The exact line numbers [start, end] where the issue exists:
+```
+CORRECT: [45, 47]
+WRONG:   [1, 100]  // Too broad - you didn't examine all 100 lines
+```
+
+**verification_method** (one of these exact values)
+How you verified the issue:
+- `"direct_code_inspection"` - Found the issue directly in the code at the location
+- `"cross_file_trace"` - Traced through imports/calls to confirm the issue
+- `"test_verification"` - Verified through examination of test code
+- `"dependency_analysis"` - Verified through analyzing dependencies
+
+### Conditional Fields
+
+**is_impact_finding** (boolean, default false)
+Set to `true` ONLY if this finding is about impact on OTHER files (not the changed file):
+```
+TRUE:  "This change in utils.ts breaks the caller in auth.ts"
+FALSE: "This code in utils.ts has a bug" (issue is in the changed file)
+```
+
+**checked_for_handling_elsewhere** (boolean, default false)
+For ANY "missing X" claim (missing error handling, missing validation, missing null check):
+- Set `true` ONLY if you used Grep/Read tools to verify X is not handled elsewhere
+- Set `false` if you didn't search other files
+- **When true, include the search in your description:**
+  - "Searched `Grep('try.*catch|\.catch\(', 'src/auth/')` - no error handling found"
+  - "Checked callers via `Grep('processPayment\(', '**/*.ts')` - none handle errors"
+
+```
+TRUE:  "Searched for try/catch patterns in this file and callers - none found"
+FALSE: "This function should have error handling" (didn't verify it's missing)
+```
+
+**If you cannot provide real evidence, you do not have a verified finding - do not report it.**
+
+**Search Before Claiming Absence:** Never claim something is "missing" without searching for it first. If you claim there's no error handling, show the search that confirmed its absence.
+
+## Valid Outputs
+
+Finding issues is NOT the goal. Accurate review is the goal.
+
+### Valid: No Significant Issues Found
+If the code is well-implemented, say so:
+```json
+{
+  "findings": [],
+  "summary": "Reviewed [files]. No quality issues found. The implementation correctly [positive observation about the code]."
+}
+```
+
+### Valid: Only Low-Severity Suggestions
+Minor improvements that don't block merge:
+```json
+{
+  "findings": [
+    {"severity": "low", "title": "Consider extracting magic number to constant", ...}
+  ],
+  "summary": "Code is sound. One minor suggestion for readability."
+}
+```
+
+### INVALID: Forced Issues
+Do NOT report issues just to have something to say:
+- Theoretical edge cases without evidence they're reachable
+- Style preferences not backed by project conventions
+- "Could be improved" without concrete problem
+- Pre-existing issues not introduced by this PR
+
+**Reporting nothing is better than reporting noise.** False positives erode trust faster than false negatives.
+
 ## Code Patterns to Flag
 
 ### JavaScript/TypeScript
@@ -238,6 +401,13 @@ Provide findings in JSON format:
     "description": "The paymentGateway.charge() call is async but has no error handling. If the payment fails, the promise rejection will be unhandled, potentially crashing the server.",
     "category": "quality",
     "severity": "critical",
+    "verification": {
+      "code_examined": "const result = await paymentGateway.charge(order.total, order.paymentMethod);",
+      "line_range_examined": [34, 34],
+      "verification_method": "direct_code_inspection"
+    },
+    "is_impact_finding": false,
+    "checked_for_handling_elsewhere": true,
     "suggested_fix": "Wrap in try/catch: try { await paymentGateway.charge(...) } catch (error) { logger.error('Payment failed', error); throw new PaymentError(error); }",
     "confidence": 95
   },
@@ -248,6 +418,13 @@ Provide findings in JSON format:
     "description": "This email validation regex is duplicated in 4 other files (user.ts, auth.ts, profile.ts, settings.ts). Changes to validation rules require updating all copies.",
     "category": "quality",
     "severity": "high",
+    "verification": {
+      "code_examined": "const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$/;",
+      "line_range_examined": [15, 15],
+      "verification_method": "cross_file_trace"
+    },
+    "is_impact_finding": false,
+    "checked_for_handling_elsewhere": false,
     "suggested_fix": "Extract to shared utility: export const isValidEmail = (email) => /regex/.test(email); and import where needed",
     "confidence": 90
   }

apps/backend/prompts/github/pr_security_agent.md

@@ -6,6 +6,82 @@ You are a focused security review agent. You have been spawned by the orchestrat
 
 Perform a thorough security review of the provided code changes, focusing ONLY on security vulnerabilities. Do not review code quality, style, or other non-security concerns.
 
+## Phase 1: Understand the PR Intent (BEFORE Looking for Issues)
+
+**MANDATORY** - Before searching for issues, understand what this PR is trying to accomplish.
+
+1. **Read the provided context**
+   - PR description: What does the author say this does?
+   - Changed files: What areas of code are affected?
+   - Commits: How did the PR evolve?
+
+2. **Identify the change type**
+   - Bug fix: Correcting broken behavior
+   - New feature: Adding new capability
+   - Refactor: Restructuring without behavior change
+   - Performance: Optimizing existing code
+   - Cleanup: Removing dead code or improving organization
+
+3. **State your understanding** (include in your analysis)
+   ```
+   PR INTENT: This PR [verb] [what] by [how].
+   RISK AREAS: [what could go wrong specific to this change type]
+   ```
+
+**Only AFTER completing Phase 1, proceed to looking for issues.**
+
+Why this matters: Understanding intent prevents flagging intentional design decisions as bugs.
+
+## TRIGGER-DRIVEN EXPLORATION (CHECK YOUR DELEGATION PROMPT)
+
+**FIRST**: Check if your delegation prompt contains a `TRIGGER:` instruction.
+
+- **If TRIGGER is present** → Exploration is **MANDATORY**, even if the diff looks correct
+- **If no TRIGGER** → Use your judgment to explore or not
+
+### How to Explore (Bounded)
+
+1. **Read the trigger** - What pattern did the orchestrator identify?
+2. **Form the specific question** - "Do callers validate input before passing it here?" (not "what do callers do?")
+3. **Use Grep** to find call sites of the changed function/method
+4. **Use Read** to examine 3-5 callers
+5. **Answer the question** - Yes (report issue) or No (move on)
+6. **Stop** - Do not explore callers of callers (depth > 1)
+
+### Security-Specific Trigger Questions
+
+| Trigger | Security Question to Answer |
+|---------|----------------------------|
+| **Output contract changed** | Does the new output expose sensitive data that was previously hidden? |
+| **Input contract changed** | Do callers now pass unvalidated input where validation was assumed? |
+| **Failure contract changed** | Does the new failure mode leak security information or bypass checks? |
+| **Side effect removed** | Was the removed effect a security control (logging, audit, cleanup)? |
+| **Auth/validation removed** | Do callers assume this function validates/authorizes? |
+
+### Example Exploration
+
+```
+TRIGGER: Failure contract changed (now throws instead of returning null)
+QUESTION: Do callers handle the new exception securely?
+
+1. Grep for "authenticateUser(" → found 5 call sites
+2. Read api/login.ts:34 → catches exception, logs full error to response → ISSUE (info leak)
+3. Read api/admin.ts:12 → catches exception, returns generic error → OK
+4. Read middleware/auth.ts:78 → no try/catch, exception propagates → ISSUE (500 with stack trace)
+5. STOP - Found 2 security issues
+
+FINDINGS:
+- api/login.ts:34 - Exception message leaked to client (information disclosure)
+- middleware/auth.ts:78 - Unhandled exception exposes stack trace in production
+```
+
+### When NO Trigger is Given
+
+If the orchestrator doesn't specify a trigger, use your judgment:
+- Focus on security issues in the changed code first
+- Only explore callers if you suspect a security boundary issue
+- Don't explore "just to be thorough"
+
 ## CRITICAL: PR Scope and Context
 
 ### What IS in scope (report these issues):
@@ -135,6 +211,92 @@ Before reporting ANY finding, you MUST:
 
 **Your evidence must prove the issue exists - not just that you suspect it.**
 
+## Evidence Requirements (MANDATORY)
+
+Every finding you report MUST include a `verification` object with ALL of these fields:
+
+### Required Fields
+
+**code_examined** (string, min 1 character)
+The **exact code snippet** you examined. Copy-paste directly from the file:
+```
+CORRECT: "cursor.execute(f'SELECT * FROM users WHERE id={user_id}')"
+WRONG:   "SQL query that uses string interpolation"
+```
+
+**line_range_examined** (array of 2 integers)
+The exact line numbers [start, end] where the issue exists:
+```
+CORRECT: [45, 47]
+WRONG:   [1, 100]  // Too broad - you didn't examine all 100 lines
+```
+
+**verification_method** (one of these exact values)
+How you verified the issue:
+- `"direct_code_inspection"` - Found the issue directly in the code at the location
+- `"cross_file_trace"` - Traced through imports/calls to confirm the issue
+- `"test_verification"` - Verified through examination of test code
+- `"dependency_analysis"` - Verified through analyzing dependencies
+
+### Conditional Fields
+
+**is_impact_finding** (boolean, default false)
+Set to `true` ONLY if this finding is about impact on OTHER files (not the changed file):
+```
+TRUE:  "This change in utils.ts breaks the caller in auth.ts"
+FALSE: "This code in utils.ts has a bug" (issue is in the changed file)
+```
+
+**checked_for_handling_elsewhere** (boolean, default false)
+For ANY "missing X" claim (missing validation, missing sanitization, missing auth check):
+- Set `true` ONLY if you used Grep/Read tools to verify X is not handled elsewhere
+- Set `false` if you didn't search other files
+- **When true, include the search in your description:**
+  - "Searched `Grep('sanitize|escape|validate', 'src/api/')` - no input validation found"
+  - "Checked middleware via `Grep('authMiddleware|requireAuth', '**/*.ts')` - endpoint unprotected"
+
+```
+TRUE:  "Searched for sanitization in this file and callers - none found"
+FALSE: "This input should be sanitized" (didn't verify it's missing)
+```
+
+**If you cannot provide real evidence, you do not have a verified finding - do not report it.**
+
+**Search Before Claiming Absence:** Never claim protection is "missing" without searching for it first. Validation may exist in middleware, callers, or framework-level code.
+
+## Valid Outputs
+
+Finding issues is NOT the goal. Accurate review is the goal.
+
+### Valid: No Significant Issues Found
+If the code is well-implemented, say so:
+```json
+{
+  "findings": [],
+  "summary": "Reviewed [files]. No security issues found. The implementation correctly [positive observation about the code]."
+}
+```
+
+### Valid: Only Low-Severity Suggestions
+Minor improvements that don't block merge:
+```json
+{
+  "findings": [
+    {"severity": "low", "title": "Consider extracting magic number to constant", ...}
+  ],
+  "summary": "Code is sound. One minor suggestion for readability."
+}
+```
+
+### INVALID: Forced Issues
+Do NOT report issues just to have something to say:
+- Theoretical edge cases without evidence they're reachable
+- Style preferences not backed by project conventions
+- "Could be improved" without concrete problem
+- Pre-existing issues not introduced by this PR
+
+**Reporting nothing is better than reporting noise.** False positives erode trust faster than false negatives.
+
 ## Code Patterns to Flag
 
 ### JavaScript/TypeScript
@@ -189,6 +351,13 @@ Provide findings in JSON format:
     "description": "User input from req.params.id is directly interpolated into SQL query without sanitization. An attacker could inject malicious SQL to extract sensitive data or modify the database.",
     "category": "security",
     "severity": "critical",
+    "verification": {
+      "code_examined": "const query = `SELECT * FROM users WHERE id = ${req.params.id}`;",
+      "line_range_examined": [45, 45],
+      "verification_method": "direct_code_inspection"
+    },
+    "is_impact_finding": false,
+    "checked_for_handling_elsewhere": false,
     "suggested_fix": "Use parameterized queries: db.query('SELECT * FROM users WHERE id = ?', [req.params.id])",
     "confidence": 95
   },
@@ -199,6 +368,13 @@ Provide findings in JSON format:
     "description": "API secret is hardcoded as a string literal. If this code is committed to version control, the secret is exposed to anyone with repository access.",
     "category": "security",
     "severity": "critical",
+    "verification": {
+      "code_examined": "const API_SECRET = 'sk-prod-abc123xyz789';",
+      "line_range_examined": [12, 12],
+      "verification_method": "direct_code_inspection"
+    },
+    "is_impact_finding": false,
+    "checked_for_handling_elsewhere": false,
     "suggested_fix": "Move secret to environment variable: const API_SECRET = process.env.API_SECRET",
     "confidence": 100
   }

apps/backend/prompts/github/pr_template_filler.md

@@ -0,0 +1,138 @@
+# PR Template Filler Agent
+
+## Your Role
+
+You are an expert developer filling out a GitHub Pull Request template. You receive the repository's PR template along with comprehensive context about the changes — git diff summary, spec overview, commit history, and branch information. Your job is to produce a complete, accurate PR body that matches the template structure exactly, with every section filled intelligently and every relevant checkbox checked.
+
+## Input Context
+
+You will receive:
+
+1. **PR Template** — The repository's `.github/PULL_REQUEST_TEMPLATE.md` content
+2. **Git Diff Summary** — A summary of all code changes (files changed, insertions, deletions)
+3. **Spec Overview** — The specification document describing the feature/fix being implemented
+4. **Commit History** — The list of commits included in this PR
+5. **Branch Context** — Source branch name, target branch name
+
+## Methodology
+
+### Step 1: Understand the Changes
+
+Before filling anything:
+
+1. **Read the spec overview** to understand the purpose and scope of the work
+2. **Analyze the diff summary** to identify what files changed and what kind of changes were made
+3. **Review the commit history** to understand the progression of work
+4. **Note the branch names** to infer the PR target and type of change
+
+### Step 2: Fill Every Section
+
+For each section in the template:
+
+1. **Identify the section type** — Is it a description field, a checkbox list, a free-text area, or a conditional section?
+2. **Select the appropriate content** based on the change context
+3. **Be specific and accurate** — Reference actual files, components, and behaviors from the diff
+4. **Never leave a section empty** — If a section is not applicable, explicitly state "N/A" or "Not applicable"
+
+### Step 3: Check Appropriate Checkboxes
+
+For checkbox lists (`- [ ]` items):
+
+1. **Check boxes that apply** by changing `- [ ]` to `- [x]`
+2. **Leave unchecked** boxes that don't apply
+3. **Base decisions on evidence** from the diff and spec, not assumptions
+4. **When uncertain**, leave unchecked rather than incorrectly checking
+
+### Step 4: Validate Output
+
+Before returning:
+
+1. **Verify markdown structure** matches the template exactly (same headings, same order)
+2. **Ensure no template placeholders remain** (no `<!-- comments -->` left unfilled where content is expected)
+3. **Check that descriptions are concise** but informative (2-3 sentences for summaries)
+4. **Confirm all checkboxes reflect reality** based on the provided context
+
+## Section-Specific Guidelines
+
+### Description Sections
+
+- Write 2-3 clear sentences explaining what the PR does and why
+- Reference the spec or task if available
+- Focus on the "what" and "why", not implementation details
+
+### Type of Change
+
+- Determine from the spec and diff whether this is a bug fix, feature, refactor, docs, or test change
+- Check exactly one type unless the PR genuinely spans multiple types
+- Use the spec's `workflow_type` field as a strong signal
+
+### Area / Service
+
+- Analyze which directories were modified in the diff
+- `frontend` = changes in `apps/frontend/`
+- `backend` = changes in `apps/backend/`
+- `fullstack` = changes in both
+
+### Related Issues
+
+- Extract issue numbers from branch names (e.g., `feature/123-description` → `#123`)
+- Extract from spec metadata if available
+- Use `Closes #N` format for issues that will be closed by this PR
+
+### Checklists
+
+- **Testing checklists**: Check items that the commit history and diff evidence support
+- **Platform checklists**: Check platforms that CI covers; note if manual testing is needed
+- **Code quality checklists**: Check if the diff shows adherence to the principles mentioned
+
+### AI Disclosure
+
+- Always check the AI disclosure box — this PR is generated by Auto Claude
+- Set tool to "Auto Claude (Claude Agent SDK)"
+- Set testing level based on whether QA was run (check spec context for QA status)
+- Always check "I understand what this PR does" — the AI agent analyzed the changes
+
+### Screenshots
+
+- If the diff includes UI changes (frontend components, styles), note that screenshots should be added
+- If no UI changes, write "N/A - No UI changes" or remove the section if the template allows
+
+### Breaking Changes
+
+- Analyze the diff for API changes, removed exports, changed interfaces, or modified database schemas
+- If no breaking changes are evident, mark as "No"
+- If breaking changes exist, describe what breaks and suggest migration steps
+
+### Feature Toggle
+
+- Check the spec for mentions of feature flags, localStorage flags, or environment variables
+- If the feature is complete and ready, check "N/A - Feature is complete and ready for all users"
+
+## Output Format
+
+Return **only** the filled PR template as valid markdown. Do not include any preamble, explanation, or wrapper — just the completed template content ready to be used as a GitHub PR body.
+
+## Quality Standards
+
+1. **Accuracy over completeness** — It's better to leave a checkbox unchecked than to incorrectly check it
+2. **Evidence-based** — Every filled section should be traceable to the provided context
+3. **Professional tone** — Write as a senior developer would in a real PR
+4. **Concise but informative** — Don't pad sections with filler text
+5. **Valid markdown** — The output must render correctly on GitHub
+
+## Anti-Patterns to Avoid
+
+### DO NOT:
+
+- **Invent information** not present in the provided context
+- **Leave template placeholders** like `<!-- What does this PR do? -->` without replacing them with actual content
+- **Check every checkbox** — only check those supported by evidence
+- **Write vague descriptions** like "This PR makes some changes" — be specific
+- **Add sections** not present in the original template
+- **Remove sections** from the original template — fill or mark as N/A
+- **Hallucinate file names** or components not mentioned in the diff
+- **Guess issue numbers** — only reference issues you can confirm from the branch name or spec
+
+---
+
+Remember: Your output becomes the PR body on GitHub. It should be professional, accurate, and immediately useful for reviewers. Every section should help a reviewer understand what changed, why it changed, and what to look for during review.

apps/backend/prompts/qa_fixer.md

@@ -159,7 +159,7 @@ This allows safe development without affecting the main branch.
 **If you are in a worktree, the environment section will show:**
 
 * **YOUR LOCATION:** The path to your isolated worktree
-* **FORBIDDEN:** The parent project path you must NEVER `cd` to
+* **FORBIDDEN PATH:** The parent project path you must NEVER `cd` to
 
 **CRITICAL RULES:**
 * **NEVER** `cd` to the forbidden parent path

apps/backend/prompts_pkg/prompt_generator.py

@@ -13,40 +13,103 @@ This approach:
 """
 
 import json
+import re
 from pathlib import Path
 
+# Worktree path patterns for detection
+# Matches paths like: .auto-claude/worktrees/tasks/{spec-name}/
+WORKTREE_PATH_PATTERNS = [
+    r"[/\\]\.auto-claude[/\\]worktrees[/\\]tasks[/\\]",
+    r"[/\\]\.auto-claude[/\\]github[/\\]pr[/\\]worktrees[/\\]",  # PR review worktrees
+    r"[/\\]\.worktrees[/\\]",  # Legacy worktree location
+]
 
-def detect_worktree_mode(spec_dir: Path) -> tuple[bool, str | None]:
+
+def detect_worktree_isolation(project_dir: Path) -> tuple[bool, Path | None]:
     """
-    Detect if running in isolated worktree mode.
+    Detect if the project_dir is inside an isolated worktree.
+
+    When running in a worktree, the agent should NOT escape to the parent project.
+    This function detects worktree mode and extracts the forbidden parent path.
 
     Args:
-        spec_dir: Absolute path to spec directory
+        project_dir: The working directory for the AI
 
     Returns:
-        (is_worktree, forbidden_parent_path) tuple:
-        - is_worktree: True if running in a worktree
-        - forbidden_parent_path: The parent project path to forbid, or None
+        Tuple of (is_worktree, parent_project_path)
+        - is_worktree: True if running in an isolated worktree
+        - parent_project_path: The forbidden parent project path (None if not in worktree)
     """
-    # Check if spec_dir contains worktree path patterns
-    # Normalize path separators to forward slashes for consistent matching
-    spec_str = str(spec_dir).replace("\\", "/")
+    # Resolve the path first for consistent matching across platforms
+    # This handles Windows drive letters, symlinks, and relative paths
+    resolved_dir = project_dir.resolve()
+    project_str = str(resolved_dir)
 
-    # New worktree location: .auto-claude/worktrees/tasks/{spec-name}/
-    new_worktree_marker = "/.auto-claude/worktrees/tasks/"
-    if new_worktree_marker in spec_str:
-        parent_path = spec_str.split(new_worktree_marker, 1)[0]
-        return True, parent_path
-
-    # Legacy worktree location: .worktrees/{spec-name}/
-    legacy_worktree_marker = "/.worktrees/"
-    if legacy_worktree_marker in spec_str:
-        parent_path = spec_str.split(legacy_worktree_marker, 1)[0]
-        return True, parent_path
+    for pattern in WORKTREE_PATH_PATTERNS:
+        match = re.search(pattern, project_str)
+        if match:
+            # Extract the parent project path (everything before the worktree marker)
+            parent_path = project_str[: match.start()]
+            # Handle edge case where worktree is at filesystem root
+            if not parent_path:
+                parent_path = resolved_dir.anchor
+            return True, Path(parent_path)
 
     return False, None
 
 
+def generate_worktree_isolation_warning(
+    project_dir: Path, parent_project_path: Path
+) -> str:
+    """
+    Generate the worktree isolation warning section for prompts.
+
+    This warning explicitly tells the agent that it's in an isolated worktree
+    and must NOT escape to the parent project directory.
+
+    Args:
+        project_dir: The worktree directory (agent's working directory)
+        parent_project_path: The forbidden parent project path
+
+    Returns:
+        Markdown string with isolation warning
+    """
+    return f"""## ⛔ ISOLATED WORKTREE - CRITICAL
+
+You are in an **ISOLATED GIT WORKTREE** - a complete copy of the project for safe development.
+
+**YOUR LOCATION:** `{project_dir}`
+**FORBIDDEN PATH:** `{parent_project_path}`
+
+### Rules:
+1. **NEVER** use `cd {parent_project_path}` or any path starting with `{parent_project_path}`
+2. **NEVER** use absolute paths that reference the parent project
+3. **ALL** project files exist HERE via relative paths
+
+### Why This Matters:
+- Git commits made in the parent project go to the WRONG branch
+- File changes in the parent project escape isolation
+- This defeats the entire purpose of safe, isolated development
+
+### Correct Usage:
+```bash
+# ✅ CORRECT - Use relative paths from your worktree
+./prod/src/file.ts
+./apps/frontend/src/component.tsx
+
+# ❌ WRONG - These escape isolation!
+cd {parent_project_path}
+{parent_project_path}/prod/src/file.ts
+```
+
+If you see absolute paths in spec.md or context.json that reference `{parent_project_path}`,
+convert them to relative paths from YOUR current location.
+
+---
+
+"""
+
+
 def get_relative_spec_path(spec_dir: Path, project_dir: Path) -> str:
     """
     Get the spec directory path relative to the project/working directory.
@@ -75,6 +138,7 @@ def generate_environment_context(project_dir: Path, spec_dir: Path) -> str:
     Generate environment context header for prompts.
 
     This explicitly tells the AI where it is working, preventing path confusion.
+    When running in a worktree, includes an isolation warning to prevent escaping.
 
     Args:
         project_dir: The working directory for the AI
@@ -85,14 +149,21 @@ def generate_environment_context(project_dir: Path, spec_dir: Path) -> str:
     """
     relative_spec = get_relative_spec_path(spec_dir, project_dir)
 
-    # Detect worktree mode and get forbidden parent path
-    is_worktree, forbidden_parent = detect_worktree_mode(spec_dir)
+    # Check if we're in an isolated worktree
+    is_worktree, parent_project_path = detect_worktree_isolation(project_dir)
 
-    # Build the environment context
-    context = f"""## YOUR ENVIRONMENT
+    # Start with worktree isolation warning if applicable
+    sections = []
+    if is_worktree and parent_project_path:
+        sections.append(
+            generate_worktree_isolation_warning(project_dir, parent_project_path)
+        )
+
+    sections.append(f"""## YOUR ENVIRONMENT
 
 **Working Directory:** `{project_dir}`
 **Spec Location:** `{relative_spec}/`
+{"**Isolation Mode:** WORKTREE (changes are isolated from main project)" if is_worktree else ""}
 
 Your filesystem is restricted to your working directory. All file paths should be
 relative to this location. Do NOT use absolute paths.
@@ -110,35 +181,9 @@ coder prompt for detailed examples.
 
 ---
 
-"""
+""")
 
-    # Add worktree isolation warning if in worktree mode
-    if is_worktree and forbidden_parent:
-        context += f"""## 🚨 ISOLATED WORKTREE - CRITICAL
-
-You are in an **ISOLATED GIT WORKTREE** - a complete copy of the project.
-
-**YOUR LOCATION:** `{project_dir}`
-**FORBIDDEN:** Do NOT use `cd {forbidden_parent}` or `cd ../..` - this **ESCAPES ISOLATION**
-
-All project files exist HERE via relative paths from your working directory.
-
-**CRITICAL RULES:**
-* **NEVER** `cd {forbidden_parent}` or any path traversal outside your worktree
-* **STAY** within your working directory at all times
-* **ALL** file operations use paths relative to your current location
-* Before any `cd` command, run `pwd` and verify the target is within your worktree
-
-**VIOLATION WARNING:** Escaping the worktree will cause:
-* Git commits going to wrong branch
-* Files created/modified in the wrong location
-* Breaking worktree isolation guarantees
-
----
-
-"""
-
-    return context
+    return "".join(sections)
 
 
 def generate_subtask_prompt(

apps/backend/requirements.txt

@@ -1,5 +1,7 @@
 # Auto-Build Framework Dependencies
-claude-agent-sdk>=0.1.19
+# SDK 0.1.25+ required for improved tool use concurrency handling
+# Earlier versions had 400 errors when tool_use blocks had partial failures
+claude-agent-sdk>=0.1.25
 python-dotenv>=1.0.0
 
 # TOML parsing fallback for Python < 3.11

apps/backend/runners/github/bot_detection.py

@@ -10,6 +10,8 @@ Key Features:
 - Skips re-reviewing bot commits
 - Implements "cooling off" period to prevent rapid re-reviews
 - Tracks reviewed commits to avoid duplicate reviews
+- In-progress tracking to prevent concurrent reviews
+- Stale review detection with automatic cleanup
 
 Usage:
     detector = BotDetector(bot_token="ghp_...")
@@ -20,13 +22,22 @@ Usage:
         print(f"Skipping PR: {reason}")
         return
 
+    # Mark review as started (prevents concurrent reviews)
+    detector.mark_review_started(pr_number)
+
+    # Perform review...
+
     # After successful review, mark as reviewed
     detector.mark_reviewed(pr_number, head_sha)
+
+    # Or if review failed:
+    detector.mark_review_finished(pr_number, success=False)
 """
 
 from __future__ import annotations
 
 import json
+import logging
 import os
 import subprocess
 import sys
@@ -36,6 +47,8 @@ from pathlib import Path
 
 from core.gh_executable import get_gh_executable
 
+logger = logging.getLogger(__name__)
+
 try:
     from .file_lock import FileLock, atomic_write
 except (ImportError, ValueError, SystemError):
@@ -52,11 +65,15 @@ class BotDetectionState:
     # PR number -> last review timestamp (ISO format)
     last_review_times: dict[int, str] = field(default_factory=dict)
 
+    # PR number -> in-progress review start time (ISO format)
+    in_progress_reviews: dict[int, str] = field(default_factory=dict)
+
     def to_dict(self) -> dict:
         """Convert to dictionary for JSON serialization."""
         return {
             "reviewed_commits": self.reviewed_commits,
             "last_review_times": self.last_review_times,
+            "in_progress_reviews": self.in_progress_reviews,
         }
 
     @classmethod
@@ -65,6 +82,7 @@ class BotDetectionState:
         return cls(
             reviewed_commits=data.get("reviewed_commits", {}),
             last_review_times=data.get("last_review_times", {}),
+            in_progress_reviews=data.get("in_progress_reviews", {}),
         )
 
     def save(self, state_dir: Path) -> None:
@@ -101,11 +119,16 @@ class BotDetector:
         - 1-minute cooling off period between reviews of same PR (for testing)
         - Tracks reviewed commit SHAs to avoid duplicate reviews
         - Identifies bot user from token to skip bot-authored content
+        - In-progress tracking to prevent concurrent reviews
+        - Stale review detection (30-minute timeout)
     """
 
     # Cooling off period in minutes (reduced to 1 for testing large PRs)
     COOLING_OFF_MINUTES = 1
 
+    # Timeout for in-progress reviews in minutes (after this, review is considered stale/crashed)
+    IN_PROGRESS_TIMEOUT_MINUTES = 30
+
     def __init__(
         self,
         state_dir: Path,
@@ -298,6 +321,104 @@ class BotDetector:
         reviewed = self.state.reviewed_commits.get(str(pr_number), [])
         return commit_sha in reviewed
 
+    def is_review_in_progress(self, pr_number: int) -> tuple[bool, str]:
+        """
+        Check if a review is currently in progress for this PR.
+
+        Also detects stale reviews (started > IN_PROGRESS_TIMEOUT_MINUTES ago).
+
+        Args:
+            pr_number: The PR number
+
+        Returns:
+            Tuple of (is_in_progress, reason_message)
+        """
+        pr_key = str(pr_number)
+        start_time_str = self.state.in_progress_reviews.get(pr_key)
+
+        if not start_time_str:
+            return False, ""
+
+        try:
+            start_time = datetime.fromisoformat(start_time_str)
+            time_elapsed = datetime.now() - start_time
+
+            # Check if review is stale (timeout exceeded)
+            if time_elapsed > timedelta(minutes=self.IN_PROGRESS_TIMEOUT_MINUTES):
+                # Mark as stale and clear the in-progress state
+                print(
+                    f"[BotDetector] Review for PR #{pr_number} is stale "
+                    f"(started {int(time_elapsed.total_seconds() / 60)}m ago, "
+                    f"timeout: {self.IN_PROGRESS_TIMEOUT_MINUTES}m) - clearing in-progress state",
+                    file=sys.stderr,
+                )
+                self.mark_review_finished(pr_number, success=False)
+                return False, ""
+
+            # Review is actively in progress
+            minutes_elapsed = int(time_elapsed.total_seconds() / 60)
+            reason = f"Review already in progress (started {minutes_elapsed}m ago)"
+            print(f"[BotDetector] PR #{pr_number}: {reason}", file=sys.stderr)
+            return True, reason
+
+        except (ValueError, TypeError) as e:
+            print(
+                f"[BotDetector] Error parsing in-progress start time: {e}",
+                file=sys.stderr,
+            )
+            # Clear invalid state
+            self.mark_review_finished(pr_number, success=False)
+            return False, ""
+
+    def mark_review_started(self, pr_number: int) -> None:
+        """
+        Mark a review as started for this PR.
+
+        This should be called when beginning a review to prevent concurrent reviews.
+
+        Args:
+            pr_number: The PR number
+        """
+        pr_key = str(pr_number)
+
+        # Record start time
+        self.state.in_progress_reviews[pr_key] = datetime.now().isoformat()
+
+        # Save state
+        self.state.save(self.state_dir)
+
+        logger.info(f"[BotDetector] Marked PR #{pr_number} review as started")
+        print(f"[BotDetector] Started review for PR #{pr_number}", file=sys.stderr)
+
+    def mark_review_finished(self, pr_number: int, success: bool = True) -> None:
+        """
+        Mark a review as finished for this PR.
+
+        This clears the in-progress state. Should be called when review completes
+        (successfully or with error) or when detected as stale.
+
+        Args:
+            pr_number: The PR number
+            success: Whether the review completed successfully
+        """
+        pr_key = str(pr_number)
+
+        # Clear in-progress state
+        if pr_key in self.state.in_progress_reviews:
+            del self.state.in_progress_reviews[pr_key]
+
+            # Save state
+            self.state.save(self.state_dir)
+
+            status = "successfully" if success else "with error/timeout"
+            logger.info(
+                f"[BotDetector] Marked PR #{pr_number} review as finished ({status})"
+            )
+            print(
+                f"[BotDetector] Finished review for PR #{pr_number} ({status})",
+                file=sys.stderr,
+            )
+
     def should_skip_pr_review(
         self,
         pr_number: int,
@@ -332,13 +453,19 @@ class BotDetector:
                 print(f"[BotDetector] SKIP PR #{pr_number}: {reason}")
                 return True, reason
 
-        # Check 3: Are we in the cooling off period?
+        # Check 3: Is a review already in progress?
+        is_in_progress, reason = self.is_review_in_progress(pr_number)
+        if is_in_progress:
+            print(f"[BotDetector] SKIP PR #{pr_number}: {reason}")
+            return True, reason
+
+        # Check 4: Are we in the cooling off period?
         is_cooling, reason = self.is_within_cooling_off(pr_number)
         if is_cooling:
             print(f"[BotDetector] SKIP PR #{pr_number}: {reason}")
             return True, reason
 
-        # Check 4: Have we already reviewed this exact commit?
+        # Check 5: Have we already reviewed this exact commit?
         head_sha = self.get_last_commit_sha(commits) if commits else None
         if head_sha and self.has_reviewed_commit(pr_number, head_sha):
             reason = f"Already reviewed commit {head_sha[:8]}"
@@ -354,6 +481,7 @@ class BotDetector:
         Mark a PR as reviewed at a specific commit.
 
         This should be called after successfully posting a review.
+        Also clears the in-progress state.
 
         Args:
             pr_number: The PR number
@@ -371,10 +499,14 @@ class BotDetector:
         # Update last review time
         self.state.last_review_times[pr_key] = datetime.now().isoformat()
 
+        # Clear in-progress state
+        if pr_key in self.state.in_progress_reviews:
+            del self.state.in_progress_reviews[pr_key]
+
         # Save state
         self.state.save(self.state_dir)
 
-        print(
+        logger.info(
             f"[BotDetector] Marked PR #{pr_number} as reviewed at {commit_sha[:8]} "
             f"({len(self.state.reviewed_commits[pr_key])} total commits reviewed)"
         )
@@ -394,6 +526,9 @@ class BotDetector:
         if pr_key in self.state.last_review_times:
             del self.state.last_review_times[pr_key]
 
+        if pr_key in self.state.in_progress_reviews:
+            del self.state.in_progress_reviews[pr_key]
+
         self.state.save(self.state_dir)
 
         print(f"[BotDetector] Cleared state for PR #{pr_number}")
@@ -409,13 +544,16 @@ class BotDetector:
         total_reviews = sum(
             len(commits) for commits in self.state.reviewed_commits.values()
         )
+        in_progress_count = len(self.state.in_progress_reviews)
 
         return {
             "bot_username": self.bot_username,
             "review_own_prs": self.review_own_prs,
             "total_prs_tracked": total_prs,
             "total_reviews_performed": total_reviews,
+            "in_progress_reviews": in_progress_count,
             "cooling_off_minutes": self.COOLING_OFF_MINUTES,
+            "in_progress_timeout_minutes": self.IN_PROGRESS_TIMEOUT_MINUTES,
         }
 
     def cleanup_stale_prs(self, max_age_days: int = 30) -> int:
@@ -425,6 +563,9 @@ class BotDetector:
         This prevents unbounded growth of the state file by cleaning up
         entries for PRs that are likely closed/merged.
 
+        Also cleans up stale in-progress reviews (reviews that have been
+        in progress for longer than IN_PROGRESS_TIMEOUT_MINUTES).
+
         Args:
             max_age_days: Remove PRs not reviewed in this many days (default: 30)
 
@@ -432,8 +573,13 @@ class BotDetector:
             Number of PRs cleaned up
         """
         cutoff = datetime.now() - timedelta(days=max_age_days)
+        in_progress_cutoff = datetime.now() - timedelta(
+            minutes=self.IN_PROGRESS_TIMEOUT_MINUTES
+        )
         prs_to_remove: list[str] = []
+        stale_in_progress: list[str] = []
 
+        # Find stale reviewed PRs
         for pr_key, last_review_str in self.state.last_review_times.items():
             try:
                 last_review = datetime.fromisoformat(last_review_str)
@@ -443,18 +589,43 @@ class BotDetector:
                 # Invalid timestamp - mark for removal
                 prs_to_remove.append(pr_key)
 
+        # Find stale in-progress reviews
+        for pr_key, start_time_str in self.state.in_progress_reviews.items():
+            try:
+                start_time = datetime.fromisoformat(start_time_str)
+                if start_time < in_progress_cutoff:
+                    stale_in_progress.append(pr_key)
+            except (ValueError, TypeError):
+                # Invalid timestamp - mark for removal
+                stale_in_progress.append(pr_key)
+
         # Remove stale PRs
         for pr_key in prs_to_remove:
             if pr_key in self.state.reviewed_commits:
                 del self.state.reviewed_commits[pr_key]
             if pr_key in self.state.last_review_times:
                 del self.state.last_review_times[pr_key]
+            if pr_key in self.state.in_progress_reviews:
+                del self.state.in_progress_reviews[pr_key]
 
-        if prs_to_remove:
+        # Remove stale in-progress reviews
+        for pr_key in stale_in_progress:
+            if pr_key in self.state.in_progress_reviews:
+                del self.state.in_progress_reviews[pr_key]
+
+        total_cleaned = len(prs_to_remove) + len(stale_in_progress)
+
+        if total_cleaned > 0:
             self.state.save(self.state_dir)
-            print(
-                f"[BotDetector] Cleaned up {len(prs_to_remove)} stale PRs "
-                f"(older than {max_age_days} days)"
-            )
+            if prs_to_remove:
+                print(
+                    f"[BotDetector] Cleaned up {len(prs_to_remove)} stale PRs "
+                    f"(older than {max_age_days} days)"
+                )
+            if stale_in_progress:
+                print(
+                    f"[BotDetector] Cleaned up {len(stale_in_progress)} stale in-progress reviews "
+                    f"(older than {self.IN_PROGRESS_TIMEOUT_MINUTES} minutes)"
+                )
 
-        return len(prs_to_remove)
+        return total_cleaned

apps/backend/runners/github/context_gatherer.py

@@ -19,7 +19,6 @@ from __future__ import annotations
 import ast
 import asyncio
 import json
-import os
 import re
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -825,41 +824,11 @@ class PRContextGatherer:
         """
         Find files related to the changes.
 
-        This includes:
-        - Test files for changed source files
-        - Imported modules and dependencies
-        - Configuration files in the same directory
-        - Related type definition files
-        - Reverse dependencies (files that import changed files)
+        DEPRECATED: LLM agents now discover related files themselves using Read, Grep, and Glob tools.
+        This method returns an empty list - agents have domain expertise to find what's relevant.
         """
-        related = set()
-
-        for changed_file in changed_files:
-            path = Path(changed_file.path)
-
-            # Find test files
-            related.update(self._find_test_files(path))
-
-            # Find imported files (for supported languages)
-            if path.suffix in [".ts", ".tsx", ".js", ".jsx", ".py"]:
-                related.update(self._find_imports(changed_file.content, path))
-
-            # Find config files in same directory
-            related.update(self._find_config_files(path.parent))
-
-            # Find type definition files
-            if path.suffix in [".ts", ".tsx"]:
-                related.update(self._find_type_definitions(path))
-
-            # Find reverse dependencies (files that import this file)
-            related.update(self._find_dependents(changed_file.path))
-
-        # Remove files that are already in changed_files
-        changed_paths = {cf.path for cf in changed_files}
-        related = {r for r in related if r not in changed_paths}
-
-        # Use smart prioritization with increased limit (50 instead of 20)
-        return self._prioritize_related_files(related, limit=50)
+        # Return empty list - LLM agents will discover files via their tools
+        return []
 
     def _find_test_files(self, source_path: Path) -> set[str]:
         """Find test files related to a source file."""
@@ -1071,168 +1040,35 @@ class PRContextGatherer:
         """
         Find files that import the given file (reverse dependencies).
 
-        Uses pure Python to search for import statements referencing this file.
-        Cross-platform compatible (Windows, macOS, Linux).
-        Limited to prevent performance issues on large codebases.
+        DEPRECATED: LLM agents now discover reverse dependencies themselves using Grep and Read tools.
+        Returns empty set - agents can search the codebase with their domain expertise.
 
         Args:
             file_path: Path of the file to find dependents for
             max_results: Maximum number of dependents to return
 
         Returns:
-            Set of file paths that import this file.
+            Empty set - LLM agents will discover dependents via Grep tool.
         """
-        dependents: set[str] = set()
-        path_obj = Path(file_path)
-        stem = path_obj.stem  # e.g., 'helpers' from 'utils/helpers.ts'
-
-        # Skip if stem is too generic (would match too many files)
-        if stem in ["index", "main", "app", "utils", "helpers", "types", "constants"]:
-            return dependents
-
-        # Build regex patterns and file extensions based on file type
-        pattern = None
-        file_extensions = []
-
-        if path_obj.suffix in [".ts", ".tsx", ".js", ".jsx"]:
-            # Match various import styles for JS/TS
-            # from './helpers', from '../utils/helpers', from '@/utils/helpers'
-            # Escape stem for regex safety
-            escaped_stem = re.escape(stem)
-            pattern = re.compile(rf"['\"].*{escaped_stem}['\"]")
-            file_extensions = [".ts", ".tsx", ".js", ".jsx"]
-        elif path_obj.suffix == ".py":
-            # Match Python imports: from .helpers import, import helpers
-            escaped_stem = re.escape(stem)
-            pattern = re.compile(rf"(from.*{escaped_stem}|import.*{escaped_stem})")
-            file_extensions = [".py"]
-        else:
-            return dependents
-
-        # Directories to exclude
-        exclude_dirs = {
-            "node_modules",
-            ".git",
-            "dist",
-            "build",
-            "__pycache__",
-            ".venv",
-            "venv",
-        }
-
-        # Walk the project directory
-        project_path = Path(self.project_dir)
-        files_checked = 0
-        max_files_to_check = 2000  # Prevent infinite scanning on large codebases
-
-        try:
-            for root, dirs, files in os.walk(project_path):
-                # Modify dirs in-place to exclude certain directories
-                dirs[:] = [d for d in dirs if d not in exclude_dirs]
-
-                for filename in files:
-                    # Check if we've hit the file limit
-                    if files_checked >= max_files_to_check:
-                        safe_print(
-                            f"[Context] File limit reached finding dependents for {file_path}"
-                        )
-                        return dependents
-
-                    # Check if file has the right extension
-                    if not any(filename.endswith(ext) for ext in file_extensions):
-                        continue
-
-                    file_full_path = Path(root) / filename
-                    files_checked += 1
-
-                    # Get relative path from project root
-                    try:
-                        relative_path = file_full_path.relative_to(project_path)
-                        relative_path_str = str(relative_path).replace("\\", "/")
-
-                        # Don't include the file itself
-                        if relative_path_str == file_path:
-                            continue
-
-                        # Search for the pattern in the file
-                        try:
-                            with open(
-                                file_full_path, encoding="utf-8", errors="ignore"
-                            ) as f:
-                                content = f.read()
-                                if pattern.search(content):
-                                    dependents.add(relative_path_str)
-                                    if len(dependents) >= max_results:
-                                        return dependents
-                        except (OSError, UnicodeDecodeError):
-                            # Skip files that can't be read
-                            continue
-
-                    except ValueError:
-                        # File is not relative to project_path, skip it
-                        continue
-
-        except Exception as e:
-            safe_print(f"[Context] Error finding dependents: {e}")
-
-        return dependents
+        # Return empty set - LLM agents will use Grep to find importers when needed
+        return set()
 
     def _prioritize_related_files(self, files: set[str], limit: int = 50) -> list[str]:
         """
         Prioritize related files by relevance.
 
-        Priority order:
-        1. Test files (most important for review context)
-        2. Type definition files (.d.ts)
-        3. Configuration files
-        4. Direct imports/dependents
-        5. Other files
+        DEPRECATED: LLM agents now prioritize exploration based on their domain expertise.
+        Returns empty list since _find_related_files no longer populates files.
 
         Args:
             files: Set of file paths to prioritize
             limit: Maximum number of files to return
 
         Returns:
-            List of files sorted by priority, limited to `limit`.
+            Empty list - LLM agents handle prioritization via their tools.
         """
-        test_files = []
-        type_files = []
-        config_files = []
-        other_files = []
-
-        for f in files:
-            path = Path(f)
-            name_lower = path.name.lower()
-
-            # Test files
-            if (
-                ".test." in name_lower
-                or ".spec." in name_lower
-                or name_lower.startswith("test_")
-                or name_lower.endswith("_test.py")
-                or "__tests__" in f
-            ):
-                test_files.append(f)
-            # Type definition files
-            elif name_lower.endswith(".d.ts") or "types" in name_lower:
-                type_files.append(f)
-            # Config files
-            elif name_lower in [
-                n.lower() for n in CONFIG_FILE_NAMES
-            ] or name_lower.endswith((".config.js", ".config.ts", "rc", "rc.json")):
-                config_files.append(f)
-            else:
-                other_files.append(f)
-
-        # Sort within each category alphabetically for consistency, then combine
-        prioritized = (
-            sorted(test_files)
-            + sorted(type_files)
-            + sorted(config_files)
-            + sorted(other_files)
-        )
-
-        return prioritized[:limit]
+        # Return empty list - LLM agents will prioritize exploration themselves
+        return []
 
     def _load_json_safe(self, filename: str) -> dict | None:
         """
@@ -1460,59 +1296,18 @@ class PRContextGatherer:
         """
         Find files related to the changes using a specific project root.
 
-        This static method allows finding related files AFTER a worktree
-        has been created, ensuring files exist in the worktree filesystem.
+        DEPRECATED: LLM agents now discover related files themselves using Read, Grep, and Glob tools.
+        This method returns an empty list - agents have domain expertise to find what's relevant.
 
         Args:
             changed_files: List of changed files from the PR
             project_root: Path to search for related files (e.g., worktree path)
 
         Returns:
-            List of related file paths (relative to project root)
+            Empty list - LLM agents will discover files via their tools.
         """
-        related: set[str] = set()
-
-        for changed_file in changed_files:
-            path = Path(changed_file.path)
-
-            # Find test files
-            test_patterns = [
-                # Jest/Vitest patterns
-                path.parent / f"{path.stem}.test{path.suffix}",
-                path.parent / f"{path.stem}.spec{path.suffix}",
-                path.parent / "__tests__" / f"{path.name}",
-                # Python patterns
-                path.parent / f"test_{path.stem}.py",
-                path.parent / f"{path.stem}_test.py",
-                # Go patterns
-                path.parent / f"{path.stem}_test.go",
-            ]
-
-            for test_path in test_patterns:
-                full_path = project_root / test_path
-                if full_path.exists() and full_path.is_file():
-                    related.add(str(test_path))
-
-            # Find config files in same directory
-            for name in CONFIG_FILE_NAMES:
-                config_path = path.parent / name
-                full_path = project_root / config_path
-                if full_path.exists() and full_path.is_file():
-                    related.add(str(config_path))
-
-            # Find type definition files
-            if path.suffix in [".ts", ".tsx"]:
-                type_def = path.parent / f"{path.stem}.d.ts"
-                full_path = project_root / type_def
-                if full_path.exists() and full_path.is_file():
-                    related.add(str(type_def))
-
-        # Remove files that are already in changed_files
-        changed_paths = {cf.path for cf in changed_files}
-        related = {r for r in related if r not in changed_paths}
-
-        # Limit to 50 most relevant files (increased from 20)
-        return sorted(related)[:50]
+        # Return empty list - LLM agents will discover files via their tools
+        return []
 
 
 class FollowupContextGatherer:

apps/backend/runners/github/models.py

@@ -367,12 +367,21 @@ class PRReviewFinding:
     validation_evidence: str | None = None  # Code snippet examined during validation
     validation_explanation: str | None = None  # Why finding was validated/dismissed
 
-    # Cross-validation and confidence routing fields
-    confidence: float = 0.5  # Confidence score (0.0-1.0), defaults to medium confidence
+    # Cross-validation fields
+    # NOTE: confidence field is DEPRECATED - we use evidence-based validation, not confidence scores
+    # The finding-validator determines validity by examining actual code, not by confidence thresholds
+    confidence: float = 0.5  # DEPRECATED: No longer used for filtering
     source_agents: list[str] = field(
         default_factory=list
     )  # Which agents reported this finding
-    cross_validated: bool = False  # Whether multiple agents agreed on this finding
+    cross_validated: bool = (
+        False  # Whether multiple agents agreed on this finding (signal, not filter)
+    )
+
+    # Impact finding flag - indicates this finding is about code OUTSIDE the PR's changed files
+    # (e.g., callers affected by contract changes). Used by _is_finding_in_scope() to allow
+    # findings about related files that aren't directly in the PR diff.
+    is_impact_finding: bool = False
 
     def to_dict(self) -> dict:
         return {
@@ -398,6 +407,8 @@ class PRReviewFinding:
             "confidence": self.confidence,
             "source_agents": self.source_agents,
             "cross_validated": self.cross_validated,
+            # Impact finding flag
+            "is_impact_finding": self.is_impact_finding,
         }
 
     @classmethod
@@ -425,6 +436,8 @@ class PRReviewFinding:
             confidence=data.get("confidence", 0.5),
             source_agents=data.get("source_agents", []),
             cross_validated=data.get("cross_validated", False),
+            # Impact finding flag
+            is_impact_finding=data.get("is_impact_finding", False),
         )
 
 

apps/backend/runners/github/orchestrator.py

@@ -396,9 +396,15 @@ class GitHubOrchestrator:
                         # No existing review found, create skip result
                         return await self._create_skip_result(pr_number, skip_reason)
                 else:
-                    # For other skip reasons (bot-authored, cooling off), create a skip result
+                    # For other skip reasons (bot-authored, cooling off, in-progress), create a skip result
                     return await self._create_skip_result(pr_number, skip_reason)
 
+            # Mark review as started (prevents concurrent reviews)
+            self.bot_detector.mark_review_started(pr_number)
+            safe_print(
+                f"[BOT DETECTION] Marked PR #{pr_number} review as started", flush=True
+            )
+
             self._report_progress(
                 "analyzing", 30, "Running multi-pass review...", pr_number=pr_number
             )
@@ -572,6 +578,13 @@ class GitHubOrchestrator:
         except Exception as e:
             import traceback
 
+            # Mark review as finished with error
+            self.bot_detector.mark_review_finished(pr_number, success=False)
+            safe_print(
+                f"[BOT DETECTION] Marked PR #{pr_number} review as finished (error)",
+                flush=True,
+            )
+
             # Log full exception details for debugging
             error_details = f"{type(e).__name__}: {e}"
             full_traceback = traceback.format_exc()
@@ -634,6 +647,13 @@ class GitHubOrchestrator:
             pr_number=pr_number,
         )
 
+        # Mark review as started (prevents concurrent reviews)
+        self.bot_detector.mark_review_started(pr_number)
+        safe_print(
+            f"[BOT DETECTION] Marked PR #{pr_number} follow-up review as started",
+            flush=True,
+        )
+
         try:
             # Import here to avoid circular imports at module level
             try:
@@ -956,6 +976,13 @@ class GitHubOrchestrator:
             return result
 
         except Exception as e:
+            # Mark review as finished with error
+            self.bot_detector.mark_review_finished(pr_number, success=False)
+            safe_print(
+                f"[BOT DETECTION] Marked PR #{pr_number} follow-up review as finished (error)",
+                flush=True,
+            )
+
             result = PRReviewResult(
                 pr_number=pr_number,
                 repo=self.config.repo,

apps/backend/runners/github/output_validator.py

@@ -22,30 +22,6 @@ except (ImportError, ValueError, SystemError):
 class FindingValidator:
     """Validates and filters AI-generated PR review findings."""
 
-    # Vague patterns that indicate low-quality findings
-    VAGUE_PATTERNS = [
-        "could be improved",
-        "consider using",
-        "might want to",
-        "you may want",
-        "it would be better",
-        "possibly consider",
-        "perhaps use",
-        "potentially add",
-        "you should consider",
-        "it might be good",
-    ]
-
-    # Generic suggestions without specifics
-    GENERIC_PATTERNS = [
-        "improve this",
-        "fix this",
-        "change this",
-        "update this",
-        "refactor this",
-        "review this",
-    ]
-
     # Minimum lengths for quality checks
     MIN_DESCRIPTION_LENGTH = 30
     MIN_SUGGESTED_FIX_LENGTH = 20
@@ -123,10 +99,6 @@ class FindingValidator:
             # Update the finding with corrected line
             finding.line = corrected.line
 
-        # Check for false positives
-        if self._is_false_positive(finding):
-            return False
-
         # Check confidence threshold
         if not self._meets_confidence_threshold(finding):
             return False
@@ -294,51 +266,6 @@ class FindingValidator:
 
         return finding
 
-    def _is_false_positive(self, finding: PRReviewFinding) -> bool:
-        """
-        Detect likely false positives.
-
-        Args:
-            finding: Finding to check
-
-        Returns:
-            True if likely a false positive, False otherwise
-        """
-        description_lower = finding.description.lower()
-
-        # Check for vague descriptions
-        for pattern in self.VAGUE_PATTERNS:
-            if pattern in description_lower:
-                # Vague low/medium findings are likely FPs
-                if finding.severity in [ReviewSeverity.LOW, ReviewSeverity.MEDIUM]:
-                    return True
-
-        # Check for generic suggestions
-        for pattern in self.GENERIC_PATTERNS:
-            if pattern in description_lower:
-                if finding.severity == ReviewSeverity.LOW:
-                    return True
-
-        # Check for generic suggestions without specifics
-        if (
-            not finding.suggested_fix
-            or len(finding.suggested_fix) < self.MIN_SUGGESTED_FIX_LENGTH
-        ):
-            if finding.severity == ReviewSeverity.LOW:
-                return True
-
-        # Check for style findings without clear justification
-        if finding.category.value == "style":
-            # Style findings should have good suggestions
-            if not finding.suggested_fix or len(finding.suggested_fix) < 30:
-                return True
-
-        # Check for overly short descriptions
-        if len(finding.description) < 50 and finding.severity == ReviewSeverity.LOW:
-            return True
-
-        return False
-
     def _score_actionability(self, finding: PRReviewFinding) -> float:
         """
         Score how actionable a finding is (0.0 to 1.0).

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

@@ -0,0 +1,33 @@
+"""
+Agent Utilities
+===============
+
+Shared utility functions for GitHub PR review agents.
+"""
+
+from pathlib import Path
+
+
+def create_working_dir_injector(working_dir: Path):
+    """Factory that creates a prompt injector with working directory context.
+
+    Args:
+        working_dir: The working directory path to inject into prompts
+
+    Returns:
+        A function that takes (prompt, fallback) and returns the prompt with
+        working directory prefix prepended.
+    """
+    working_dir_prefix = (
+        f"## Working Directory\n\n"
+        f"Your working directory is: `{working_dir.resolve()}`\n"
+        f"All file paths should be relative to this directory.\n"
+        f"Use the Read, Grep, and Glob tools to examine files.\n\n"
+    )
+
+    def with_working_dir(prompt: str | None, fallback: str) -> str:
+        """Inject working directory context into agent prompt."""
+        base = prompt or fallback
+        return f"{working_dir_prefix}{base}"
+
+    return with_working_dir

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

@@ -43,6 +43,7 @@ try:
         PRReviewResult,
         ReviewSeverity,
     )
+    from .agent_utils import create_working_dir_injector
     from .category_utils import map_category
     from .io_utils import safe_print
     from .pr_worktree_manager import PRWorktreeManager
@@ -62,6 +63,7 @@ except (ImportError, ValueError, SystemError):
         ReviewSeverity,
     )
     from phase_config import get_thinking_budget, resolve_model_id
+    from services.agent_utils import create_working_dir_injector
     from services.category_utils import map_category
     from services.io_utils import safe_print
     from services.pr_worktree_manager import PRWorktreeManager
@@ -183,22 +185,35 @@ class ParallelFollowupReviewer:
         """
         self.worktree_manager.remove_worktree(worktree_path)
 
-    def _define_specialist_agents(self) -> dict[str, AgentDefinition]:
+    def _define_specialist_agents(
+        self, project_root: Path | None = None
+    ) -> dict[str, AgentDefinition]:
         """
         Define specialist agents for follow-up review.
 
         Each agent has:
         - description: When the orchestrator should invoke this agent
-        - prompt: System prompt for the agent
+        - prompt: System prompt for the agent (includes working directory)
         - tools: Tools the agent can use (read-only for PR review)
         - model: "inherit" = use same model as orchestrator (user's choice)
+
+        Args:
+            project_root: Working directory for the agents (worktree path).
+                         If None, falls back to self.project_dir.
         """
+        # Use provided project_root or fall back to default
+        working_dir = project_root or self.project_dir
+
         # Load agent prompts from files
         resolution_prompt = self._load_prompt("pr_followup_resolution_agent.md")
         newcode_prompt = self._load_prompt("pr_followup_newcode_agent.md")
         comment_prompt = self._load_prompt("pr_followup_comment_agent.md")
         validator_prompt = self._load_prompt("pr_finding_validator.md")
 
+        # CRITICAL: Inject working directory into all prompts
+        # Subagents don't inherit cwd from parent, so they need explicit path info
+        with_working_dir = create_working_dir_injector(working_dir)
+
         return {
             "resolution-verifier": AgentDefinition(
                 description=(
@@ -207,8 +222,10 @@ class ParallelFollowupReviewer:
                     "are truly fixed, partially fixed, or still unresolved. "
                     "Invoke when: There are previous findings to verify."
                 ),
-                prompt=resolution_prompt
-                or "You verify whether previous findings are resolved.",
+                prompt=with_working_dir(
+                    resolution_prompt,
+                    "You verify whether previous findings are resolved.",
+                ),
                 tools=["Read", "Grep", "Glob"],
                 model="inherit",
             ),
@@ -219,7 +236,9 @@ class ParallelFollowupReviewer:
                     "Invoke when: There are substantial code changes (>50 lines diff) or "
                     "changes to security-sensitive areas."
                 ),
-                prompt=newcode_prompt or "You review new code for issues.",
+                prompt=with_working_dir(
+                    newcode_prompt, "You review new code for issues."
+                ),
                 tools=["Read", "Grep", "Glob"],
                 model="inherit",
             ),
@@ -230,7 +249,9 @@ class ParallelFollowupReviewer:
                     "unanswered questions and valid concerns. "
                     "Invoke when: There are comments or formal reviews since last review."
                 ),
-                prompt=comment_prompt or "You analyze comments and feedback.",
+                prompt=with_working_dir(
+                    comment_prompt, "You analyze comments and feedback."
+                ),
                 tools=["Read", "Grep", "Glob"],
                 model="inherit",
             ),
@@ -243,8 +264,10 @@ class ParallelFollowupReviewer:
                     "CRITICAL: Invoke for ALL unresolved findings after resolution-verifier runs. "
                     "Invoke when: There are findings marked as unresolved that need validation."
                 ),
-                prompt=validator_prompt
-                or "You validate whether unresolved findings are real issues.",
+                prompt=with_working_dir(
+                    validator_prompt,
+                    "You validate whether unresolved findings are real issues.",
+                ),
                 tools=["Read", "Grep", "Glob"],
                 model="inherit",
             ),
@@ -487,6 +510,9 @@ The SDK will run invoked agents in parallel automatically.
                     "using local checkout"
                 )
 
+            # Capture agent definitions for debug logging (AFTER worktree creation)
+            agent_defs = self._define_specialist_agents(project_root)
+
             # Use model and thinking level from config (user settings)
             # Resolve model shorthand via environment variable override if configured
             model_shorthand = self.config.model or "sonnet"
@@ -499,14 +525,14 @@ The SDK will run invoked agents in parallel automatically.
                 f"thinking_level={thinking_level}, thinking_budget={thinking_budget}"
             )
 
-            # Create client with subagents defined
+            # Create client with subagents defined (using worktree path)
             client = create_client(
                 project_dir=project_root,
                 spec_dir=self.github_dir,
                 model=model,
                 agent_type="pr_followup_parallel",
                 max_thinking_tokens=thinking_budget,
-                agents=self._define_specialist_agents(),
+                agents=self._define_specialist_agents(project_root),
                 output_format={
                     "type": "json_schema",
                     "schema": ParallelFollowupResponse.model_json_schema(),
@@ -534,6 +560,8 @@ The SDK will run invoked agents in parallel automatically.
                     client=client,
                     context_name="ParallelFollowup",
                     model=model,
+                    system_prompt=prompt,
+                    agent_definitions=agent_defs,
                 )
 
                 # Check for stream processing errors
@@ -883,6 +911,7 @@ The SDK will run invoked agents in parallel automatically.
                                     validation_status=validation_status,
                                     validation_evidence=validation_evidence,
                                     validation_explanation=validation_explanation,
+                                    is_impact_finding=original.is_impact_finding,
                                 )
                             )
 
@@ -903,6 +932,7 @@ The SDK will run invoked agents in parallel automatically.
                         line=nf.line,
                         suggested_fix=nf.suggested_fix,
                         fixable=nf.fixable,
+                        is_impact_finding=getattr(nf, "is_impact_finding", False),
                     )
                 )
 

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

@@ -139,18 +139,9 @@ class PRReviewEngine:
             files_list.append(f"- ... and {len(context.changed_files) - 20} more files")
         files_str = "\n".join(files_list)
 
-        # NEW: Format related files (imports, tests, etc.)
+        # Removed: Related files section
+        # LLM agents now discover relevant files themselves via Read, Grep, Glob tools
         related_files_str = ""
-        if context.related_files:
-            related_files_list = [f"- `{f}`" for f in context.related_files[:10]]
-            if len(context.related_files) > 10:
-                related_files_list.append(
-                    f"- ... and {len(context.related_files) - 10} more"
-                )
-            related_files_str = f"""
-### Related Files (imports, tests, configs)
-{chr(10).join(related_files_list)}
-"""
 
         # NEW: Format commits for context
         commits_str = ""

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

@@ -28,6 +28,50 @@ from typing import Literal
 
 from pydantic import BaseModel, Field
 
+# =============================================================================
+# Verification Evidence (Required for All Findings)
+# =============================================================================
+
+
+class VerificationEvidence(BaseModel):
+    """Evidence that a finding was verified against actual code.
+
+    All fields are required - schema enforcement guarantees evidence exists.
+    This shifts quality control from programmatic filters to schema enforcement.
+    """
+
+    code_examined: str = Field(
+        min_length=1,
+        description=(
+            "REQUIRED: Exact code snippet that was examined. "
+            "Must be actual code from the file, not a description of code. "
+            "Copy-paste the relevant lines directly."
+        ),
+    )
+    line_range_examined: list[int] = Field(
+        min_length=2,
+        max_length=2,
+        description=(
+            "Start and end line numbers [start, end] of the examined code. "
+            "Must match the code in code_examined."
+        ),
+    )
+    verification_method: Literal[
+        "direct_code_inspection",
+        "cross_file_trace",
+        "test_verification",
+        "dependency_analysis",
+    ] = Field(
+        description=(
+            "How the issue was verified: "
+            "direct_code_inspection = found issue directly in the code shown; "
+            "cross_file_trace = traced through imports/calls to find the issue; "
+            "test_verification = verified through examination of test code; "
+            "dependency_analysis = verified through analyzing dependencies"
+        )
+    )
+
+
 # =============================================================================
 # Common Finding Types
 # =============================================================================
@@ -48,7 +92,10 @@ class BaseFinding(BaseModel):
     fixable: bool = Field(False, description="Whether this can be auto-fixed")
     evidence: str | None = Field(
         None,
-        description="Actual code snippet proving the issue exists. Required for validation.",
+        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"
     )
 
 
@@ -155,6 +202,9 @@ class FollowupFinding(BaseModel):
     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"
+    )
 
 
 class FollowupReviewResponse(BaseModel):
@@ -323,7 +373,10 @@ class OrchestratorFinding(BaseModel):
     suggestion: str | None = Field(None, description="How to fix this issue")
     evidence: str | None = Field(
         None,
-        description="Actual code snippet proving the issue exists. Required for validation.",
+        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"
     )
 
 
@@ -399,7 +452,25 @@ class ParallelOrchestratorFinding(BaseModel):
     )
     evidence: str | None = Field(
         None,
-        description="Actual code snippet proving the issue exists. Required for validation.",
+        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"
+    )
+    is_impact_finding: bool = Field(
+        False,
+        description=(
+            "True if this finding is about impact on OTHER files (not the changed file). "
+            "Impact findings may reference files outside the PR's changed files list."
+        ),
+    )
+    checked_for_handling_elsewhere: bool = Field(
+        False,
+        description=(
+            "For 'missing X' claims (missing error handling, missing validation, etc.), "
+            "True if the agent verified X is not handled elsewhere in the codebase. "
+            "False if this is a 'missing X' claim but other locations were not checked."
+        ),
     )
     suggested_fix: str | None = Field(None, description="How to fix this issue")
     fixable: bool = Field(False, description="Whether this can be auto-fixed")
@@ -428,6 +499,44 @@ class AgentAgreement(BaseModel):
     )
 
 
+class DismissedFinding(BaseModel):
+    """A finding that was validated and dismissed as a false positive.
+
+    Included in output for transparency - users can see what was investigated and why it was dismissed.
+    """
+
+    id: str = Field(description="Original finding ID")
+    original_title: str = Field(description="Original finding title")
+    original_severity: Literal["critical", "high", "medium", "low"] = Field(
+        description="Original severity assigned by specialist"
+    )
+    original_file: str = Field(description="File where issue was claimed")
+    original_line: int = Field(0, description="Line where issue was claimed")
+    dismissal_reason: str = Field(
+        description="Why this finding was dismissed as a false positive"
+    )
+    validation_evidence: str = Field(
+        description="Actual code examined that disproved the finding"
+    )
+
+
+class ValidationSummary(BaseModel):
+    """Summary of validation results for transparency."""
+
+    total_findings_from_specialists: int = Field(
+        description="Total findings reported by all specialist agents"
+    )
+    confirmed_valid: int = Field(
+        description="Findings confirmed as real issues by validator"
+    )
+    dismissed_false_positive: int = Field(
+        description="Findings dismissed as false positives by validator"
+    )
+    needs_human_review: int = Field(
+        0, description="Findings that couldn't be definitively validated"
+    )
+
+
 class ParallelOrchestratorResponse(BaseModel):
     """Complete response schema for parallel orchestrator PR review."""
 
@@ -438,8 +547,20 @@ class ParallelOrchestratorResponse(BaseModel):
         default_factory=list,
         description="List of agent names that were invoked",
     )
+    validation_summary: ValidationSummary | None = Field(
+        None,
+        description="Summary of validation results (total, confirmed, dismissed, needs_review)",
+    )
     findings: list[ParallelOrchestratorFinding] = Field(
-        default_factory=list, description="All findings from synthesis"
+        default_factory=list,
+        description="Validated findings only (confirmed_valid or needs_human_review)",
+    )
+    dismissed_findings: list[DismissedFinding] = Field(
+        default_factory=list,
+        description=(
+            "Findings that were validated and dismissed as false positives. "
+            "Included for transparency - users can see what was investigated."
+        ),
     )
     agent_agreement: AgentAgreement = Field(
         default_factory=AgentAgreement,
@@ -495,7 +616,10 @@ class ParallelFollowupFinding(BaseModel):
     )
     evidence: str | None = Field(
         None,
-        description="Actual code snippet proving the issue exists. Required for validation.",
+        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"
     )
     suggested_fix: str | None = Field(None, description="How to fix this issue")
     fixable: bool = Field(False, description="Whether this can be auto-fixed")
@@ -505,6 +629,14 @@ class ParallelFollowupFinding(BaseModel):
     related_to_previous: str | None = Field(
         None, description="ID of related previous finding if this is a regression"
     )
+    is_impact_finding: bool = Field(
+        False,
+        description=(
+            "True if this finding is about impact on OTHER files (callers, dependents) "
+            "outside the PR's changed files. Used by _is_finding_in_scope() to allow "
+            "findings about related files that aren't directly in the PR diff."
+        ),
+    )
 
 
 class CommentAnalysis(BaseModel):

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

@@ -594,7 +594,7 @@ Focus on:
 - Insecure cryptography
 - Input validation issues
 
-Output findings in JSON format with high confidence (>80%) only.
+Output findings in JSON format with evidence from the actual code.
 """
 
 
@@ -611,5 +611,5 @@ Focus on:
 - Pattern adherence
 - Maintainability
 
-Output findings in JSON format with high confidence (>80%) only.
+Output findings in JSON format with evidence from the actual code.
 """

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

@@ -124,6 +124,49 @@ def _get_tool_detail(tool_name: str, tool_input: dict[str, Any]) -> str:
     return f"Using tool: {tool_name}"
 
 
+# Circuit breaker threshold - abort if message count exceeds this
+# Prevents runaway retry loops from consuming unbounded resources
+MAX_MESSAGE_COUNT = 500
+
+
+def _is_tool_concurrency_error(text: str) -> bool:
+    """
+    Detect the specific tool use concurrency error pattern.
+
+    This error occurs when Claude makes multiple parallel tool_use blocks
+    and some fail, corrupting the tool_use/tool_result message pairing.
+
+    Args:
+        text: Text to check for error pattern
+
+    Returns:
+        True if this is the tool concurrency error, False otherwise
+    """
+    text_lower = text.lower()
+    # Check for the specific error message pattern
+    # Pattern 1: Explicit concurrency or tool_use errors with 400
+    has_400 = "400" in text_lower
+    has_tool = "tool" in text_lower
+
+    if has_400 and has_tool:
+        # Look for specific keywords indicating tool concurrency issues
+        error_keywords = [
+            "concurrency",
+            "tool_use",
+            "tool use",
+            "tool_result",
+            "tool result",
+        ]
+        if any(keyword in text_lower for keyword in error_keywords):
+            return True
+
+    # Pattern 2: API error with 400 and tool mention
+    if "api error" in text_lower and has_400 and has_tool:
+        return True
+
+    return False
+
+
 async def process_sdk_stream(
     client: Any,
     on_thinking: Callable[[str], None] | None = None,
@@ -133,6 +176,10 @@ async def process_sdk_stream(
     on_structured_output: Callable[[dict[str, Any]], None] | None = None,
     context_name: str = "SDK",
     model: str | None = None,
+    max_messages: int | None = None,
+    # Deprecated parameters (kept for backwards compatibility, no longer used)
+    system_prompt: str | None = None,  # noqa: ARG001
+    agent_definitions: dict | None = None,  # noqa: ARG001
 ) -> dict[str, Any]:
     """
     Process SDK response stream with customizable callbacks.
@@ -153,6 +200,7 @@ async def process_sdk_stream(
         on_structured_output: Callback for structured output - receives dict
         context_name: Name for logging (e.g., "ParallelOrchestrator", "ParallelFollowup")
         model: Model name for logging (e.g., "claude-sonnet-4-5-20250929")
+        max_messages: Optional override for max message count circuit breaker (default: MAX_MESSAGE_COUNT)
 
     Returns:
         Dictionary with:
@@ -171,6 +219,11 @@ async def process_sdk_stream(
     # Track subagent tool IDs to log their results
     subagent_tool_ids: dict[str, str] = {}  # tool_id -> agent_name
     completed_agent_tool_ids: set[str] = set()  # tool_ids of completed agents
+    # Track tool concurrency errors for retry logic
+    detected_concurrency_error = False
+
+    # Circuit breaker: max messages before aborting
+    message_limit = max_messages if max_messages is not None else MAX_MESSAGE_COUNT
 
     safe_print(f"[{context_name}] Processing SDK stream...")
     if DEBUG_MODE:
@@ -186,6 +239,17 @@ async def process_sdk_stream(
                 msg_type = type(msg).__name__
                 msg_count += 1
 
+                # CIRCUIT BREAKER: Abort if message count exceeds threshold
+                # This prevents runaway retry loops (e.g., 400 errors causing infinite retries)
+                if msg_count > message_limit:
+                    stream_error = (
+                        f"Circuit breaker triggered: message count ({msg_count}) "
+                        f"exceeded limit ({message_limit}). Possible retry loop detected."
+                    )
+                    logger.error(f"[{context_name}] {stream_error}")
+                    safe_print(f"[{context_name}] ERROR: {stream_error}")
+                    break
+
                 # Log progress periodically so user knows AI is working
                 if msg_count - last_progress_log >= PROGRESS_LOG_INTERVAL:
                     if subagent_tool_ids:
@@ -258,6 +322,16 @@ async def process_sdk_stream(
                         safe_print(
                             f"[{context_name}] Invoking agent: {agent_name}{model_info}"
                         )
+                        # Log delegation prompt for debugging trigger system
+                        delegation_prompt = tool_input.get("prompt", "")
+                        if delegation_prompt:
+                            # Show first 300 chars of delegation prompt
+                            prompt_preview = delegation_prompt[:300]
+                            if len(delegation_prompt) > 300:
+                                prompt_preview += "..."
+                            safe_print(
+                                f"[{context_name}] Delegation prompt for {agent_name}: {prompt_preview}"
+                            )
                     elif tool_name != "StructuredOutput":
                         # Log meaningful tool info (not just tool name)
                         tool_detail = _get_tool_detail(tool_name, tool_input)
@@ -349,6 +423,15 @@ async def process_sdk_stream(
                         block_type = type(block).__name__
                         if block_type == "TextBlock" and hasattr(block, "text"):
                             result_text += block.text
+                            # Check for tool concurrency error pattern in text output
+                            if _is_tool_concurrency_error(block.text):
+                                detected_concurrency_error = True
+                                logger.warning(
+                                    f"[{context_name}] Detected tool use concurrency error in response"
+                                )
+                                safe_print(
+                                    f"[{context_name}] WARNING: Tool concurrency error detected"
+                                )
                             # Always print text content preview (not just in DEBUG_MODE)
                             text_preview = block.text[:500].replace("\n", " ").strip()
                             if text_preview:
@@ -465,6 +548,13 @@ async def process_sdk_stream(
 
     safe_print(f"[{context_name}] Session ended. Total messages: {msg_count}")
 
+    # Set error flag if tool concurrency error was detected
+    if detected_concurrency_error and not stream_error:
+        stream_error = "tool_use_concurrency_error"
+        logger.warning(
+            f"[{context_name}] Tool use concurrency error detected - caller should retry"
+        )
+
     return {
         "result_text": result_text,
         "structured_output": structured_output,

apps/backend/runners/github/test_bot_detection.py

@@ -532,5 +532,176 @@ class TestGhExecutableDetection:
             mock_run.assert_not_called()
 
 
+class TestInProgressTracking:
+    """Test in-progress review tracking."""
+
+    def test_mark_review_started(self, mock_bot_detector, temp_state_dir):
+        """Test marking review as started."""
+        mock_bot_detector.mark_review_started(123)
+
+        # Check state
+        assert "123" in mock_bot_detector.state.in_progress_reviews
+        start_time_str = mock_bot_detector.state.in_progress_reviews["123"]
+        start_time = datetime.fromisoformat(start_time_str)
+
+        # Should be very recent (within last 5 seconds)
+        time_diff = datetime.now() - start_time
+        assert time_diff.total_seconds() < 5
+
+        # Check persistence
+        loaded = BotDetectionState.load(temp_state_dir)
+        assert "123" in loaded.in_progress_reviews
+
+    def test_mark_review_finished_success(self, mock_bot_detector, temp_state_dir):
+        """Test marking review as finished successfully."""
+        mock_bot_detector.mark_review_started(123)
+        assert "123" in mock_bot_detector.state.in_progress_reviews
+
+        mock_bot_detector.mark_review_finished(123, success=True)
+
+        # In-progress state should be cleared
+        assert "123" not in mock_bot_detector.state.in_progress_reviews
+
+        # Check persistence
+        loaded = BotDetectionState.load(temp_state_dir)
+        assert "123" not in loaded.in_progress_reviews
+
+    def test_mark_review_finished_error(self, mock_bot_detector):
+        """Test marking review as finished with error."""
+        mock_bot_detector.mark_review_started(123)
+        mock_bot_detector.mark_review_finished(123, success=False)
+
+        # In-progress state should be cleared
+        assert "123" not in mock_bot_detector.state.in_progress_reviews
+
+    def test_is_review_in_progress_active(self, mock_bot_detector):
+        """Test detecting active in-progress review."""
+        mock_bot_detector.mark_review_started(123)
+
+        is_in_progress, reason = mock_bot_detector.is_review_in_progress(123)
+
+        assert is_in_progress is True
+        assert "already in progress" in reason.lower()
+
+    def test_is_review_in_progress_not_started(self, mock_bot_detector):
+        """Test checking in-progress when review not started."""
+        is_in_progress, reason = mock_bot_detector.is_review_in_progress(999)
+
+        assert is_in_progress is False
+        assert reason == ""
+
+    def test_is_review_in_progress_stale(self, mock_bot_detector):
+        """Test detecting stale in-progress review."""
+        # Set review start time to 31 minutes ago (past timeout)
+        stale_time = datetime.now() - timedelta(minutes=31)
+        mock_bot_detector.state.in_progress_reviews["123"] = stale_time.isoformat()
+
+        is_in_progress, reason = mock_bot_detector.is_review_in_progress(123)
+
+        # Should detect as stale and clear it
+        assert is_in_progress is False
+        assert reason == ""
+        # Should be removed from state
+        assert "123" not in mock_bot_detector.state.in_progress_reviews
+
+    def test_is_review_in_progress_invalid_timestamp(self, mock_bot_detector):
+        """Test handling invalid timestamp in in-progress state."""
+        mock_bot_detector.state.in_progress_reviews["123"] = "invalid-timestamp"
+
+        is_in_progress, reason = mock_bot_detector.is_review_in_progress(123)
+
+        # Should clear invalid state
+        assert is_in_progress is False
+        assert reason == ""
+        assert "123" not in mock_bot_detector.state.in_progress_reviews
+
+    def test_should_skip_review_in_progress(self, mock_bot_detector):
+        """Test skipping PR when review is in progress."""
+        mock_bot_detector.mark_review_started(123)
+
+        pr_data = {"author": {"login": "alice"}}
+        commits = [{"author": {"login": "alice"}, "oid": "abc123"}]
+
+        should_skip, reason = mock_bot_detector.should_skip_pr_review(
+            pr_number=123,
+            pr_data=pr_data,
+            commits=commits,
+        )
+
+        assert should_skip is True
+        assert "already in progress" in reason.lower()
+
+    def test_mark_reviewed_clears_in_progress(self, mock_bot_detector):
+        """Test that mark_reviewed also clears in-progress state."""
+        mock_bot_detector.mark_review_started(123)
+        assert "123" in mock_bot_detector.state.in_progress_reviews
+
+        mock_bot_detector.mark_reviewed(123, "abc123")
+
+        # In-progress should be cleared
+        assert "123" not in mock_bot_detector.state.in_progress_reviews
+        # Reviewed state should be set
+        assert "123" in mock_bot_detector.state.reviewed_commits
+        assert "abc123" in mock_bot_detector.state.reviewed_commits["123"]
+
+    def test_clear_pr_state_clears_in_progress(self, mock_bot_detector):
+        """Test that clear_pr_state also clears in-progress state."""
+        mock_bot_detector.mark_review_started(123)
+        mock_bot_detector.mark_reviewed(123, "abc123")
+
+        assert (
+            "123" in mock_bot_detector.state.in_progress_reviews or True
+        )  # May be cleared by mark_reviewed
+        assert "123" in mock_bot_detector.state.reviewed_commits
+
+        # Start another review
+        mock_bot_detector.mark_review_started(123)
+        assert "123" in mock_bot_detector.state.in_progress_reviews
+
+        mock_bot_detector.clear_pr_state(123)
+
+        # Everything should be cleared
+        assert "123" not in mock_bot_detector.state.in_progress_reviews
+        assert "123" not in mock_bot_detector.state.reviewed_commits
+        assert "123" not in mock_bot_detector.state.last_review_times
+
+    def test_get_stats_includes_in_progress(self, mock_bot_detector):
+        """Test that get_stats includes in-progress count."""
+        mock_bot_detector.mark_review_started(123)
+        mock_bot_detector.mark_review_started(456)
+        mock_bot_detector.mark_reviewed(789, "abc123")
+
+        stats = mock_bot_detector.get_stats()
+
+        assert stats["in_progress_reviews"] == 2
+        assert stats["total_prs_tracked"] == 1  # Only 789 is tracked as reviewed
+        assert stats["in_progress_timeout_minutes"] == 30
+
+    def test_cleanup_stale_prs_removes_stale_in_progress(self, mock_bot_detector):
+        """Test that cleanup_stale_prs removes stale in-progress reviews."""
+        # Add a stale in-progress review (32 minutes ago)
+        stale_time = datetime.now() - timedelta(minutes=32)
+        mock_bot_detector.state.in_progress_reviews["123"] = stale_time.isoformat()
+
+        # Add an active in-progress review (5 minutes ago)
+        active_time = datetime.now() - timedelta(minutes=5)
+        mock_bot_detector.state.in_progress_reviews["456"] = active_time.isoformat()
+
+        # Add a stale reviewed PR (40 days ago)
+        stale_review_time = datetime.now() - timedelta(days=40)
+        mock_bot_detector.state.reviewed_commits["789"] = ["abc123"]
+        mock_bot_detector.state.last_review_times["789"] = stale_review_time.isoformat()
+
+        cleaned = mock_bot_detector.cleanup_stale_prs(max_age_days=30)
+
+        # Should remove stale in-progress and stale reviewed PR
+        assert cleaned == 2  # 1 stale in-progress + 1 stale reviewed
+        assert "123" not in mock_bot_detector.state.in_progress_reviews
+        assert (
+            "456" in mock_bot_detector.state.in_progress_reviews
+        )  # Active one remains
+        assert "789" not in mock_bot_detector.state.reviewed_commits
+
+
 if __name__ == "__main__":
     pytest.main([__file__, "-v"])

apps/backend/runners/spec_runner.py

@@ -46,6 +46,7 @@ if sys.version_info < (3, 10):  # noqa: UP036
 
 import asyncio
 import io
+import json
 import os
 import subprocess
 from pathlib import Path
@@ -252,9 +253,17 @@ Examples:
     # Find project root (look for auto-claude folder)
     project_dir = args.project_dir
 
-    # Auto-detect if running from within auto-claude directory (the source code)
-    if project_dir.name == "auto-claude" and (project_dir / "run.py").exists():
-        # Running from within auto-claude/ source directory, go up 1 level
+    # Auto-detect if running from within auto-claude/apps/backend/ source directory.
+    # This must be specific: check for run.py FILE (not dir) AND core/client.py to confirm
+    # we're in the actual backend source tree, not just a project named "auto-claude".
+    run_py_path = project_dir / "run.py"
+    if (
+        project_dir.name == "auto-claude"
+        and run_py_path.exists()
+        and run_py_path.is_file()
+        and (project_dir / "core" / "client.py").exists()
+    ):
+        # Running from within auto-claude/apps/backend/ source directory, go up 1 level
         project_dir = project_dir.parent
     elif not (project_dir / ".auto-claude").exists():
         # No .auto-claude folder found - try to find project root
@@ -351,6 +360,36 @@ Examples:
                 "--auto-continue",  # Non-interactive mode for chained execution
             ]
 
+            # Bypass approval re-validation when all conditions are met:
+            # 1. Spec was auto-approved (no human review required)
+            # 2. Spec creation succeeded (we're past the success check above)
+            # 3. No review-before-coding gate was requested
+            # This prevents hash mismatch failures when spec files are
+            # touched between auto-approval and run.py startup.
+            if args.auto_approve:
+                # Default to requiring review (fail-closed) - only skip if explicitly disabled
+                require_review = True
+                task_meta_path = orchestrator.spec_dir / "task_metadata.json"
+                if task_meta_path.exists():
+                    try:
+                        with open(task_meta_path, encoding="utf-8") as f:
+                            task_meta = json.load(f)
+                        require_review = task_meta.get(
+                            "requireReviewBeforeCoding", False
+                        )
+                    except (json.JSONDecodeError, OSError) as e:
+                        # On parse error, keep require_review=True (fail-closed)
+                        debug(
+                            "spec_runner",
+                            f"Failed to parse task_metadata.json, not adding --force: {e}",
+                        )
+                if not require_review:
+                    run_cmd.append("--force")
+                    debug(
+                        "spec_runner",
+                        "Adding --force: auto-approved, no review required, spec completed",
+                    )
+
             # Pass base branch if specified (for worktree creation)
             if args.base_branch:
                 run_cmd.extend(["--base-branch", args.base_branch])

apps/backend/security/hooks.py

@@ -38,7 +38,7 @@ async def bash_security_hook(
         context: Optional context
 
     Returns:
-        Empty dict to allow, or {"decision": "block", "reason": "..."} to block
+        Empty dict to allow, or hookSpecificOutput with permissionDecision "deny" to block
     """
     if input_data.get("tool_name") != "Bash":
         return {}
@@ -49,15 +49,21 @@ async def bash_security_hook(
     # Check if tool_input is None (malformed tool call)
     if tool_input is None:
         return {
-            "decision": "block",
-            "reason": "Bash tool_input is None - malformed tool call from SDK",
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": "Bash tool_input is None - malformed tool call from SDK",
+            }
         }
 
     # Check if tool_input is a dict
     if not isinstance(tool_input, dict):
         return {
-            "decision": "block",
-            "reason": f"Bash tool_input must be dict, got {type(tool_input).__name__}",
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": f"Bash tool_input must be dict, got {type(tool_input).__name__}",
+            }
         }
 
     # Now safe to access command
@@ -97,8 +103,11 @@ async def bash_security_hook(
     if not commands:
         # Could not parse - fail safe by blocking
         return {
-            "decision": "block",
-            "reason": f"Could not parse command for security validation: {command}",
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": f"Could not parse command for security validation: {command}",
+            }
         }
 
     # Split into segments for per-command validation
@@ -114,8 +123,11 @@ async def bash_security_hook(
 
         if not is_allowed:
             return {
-                "decision": "block",
-                "reason": reason,
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": reason,
+                }
             }
 
         # Additional validation for sensitive commands
@@ -127,7 +139,13 @@ async def bash_security_hook(
             validator = VALIDATORS[cmd]
             allowed, reason = validator(cmd_segment)
             if not allowed:
-                return {"decision": "block", "reason": reason}
+                return {
+                    "hookSpecificOutput": {
+                        "hookEventName": "PreToolUse",
+                        "permissionDecision": "deny",
+                        "permissionDecisionReason": reason,
+                    }
+                }
 
     return {}
 

apps/backend/spec/pipeline/orchestrator.py

@@ -10,6 +10,7 @@ from collections.abc import Callable
 from pathlib import Path
 
 from analysis.analyzers import analyze_project
+from core.task_event import TaskEventEmitter
 from core.workspace.models import SpecNumberLock
 from phase_config import get_thinking_budget
 from prompts_pkg.project_context import should_refresh_project_index
@@ -234,6 +235,7 @@ class SpecOrchestrator:
         # Initialize task logger for planning phase
         task_logger = get_task_logger(self.spec_dir)
         task_logger.start_phase(LogPhase.PLANNING, "Starting spec creation process")
+        TaskEventEmitter.from_spec_dir(self.spec_dir).emit("PLANNING_STARTED")
 
         print(
             box(
@@ -408,6 +410,28 @@ class SpecOrchestrator:
             LogPhase.PLANNING, success=True, message="Spec creation complete"
         )
 
+        # Load task metadata to check requireReviewBeforeCoding setting
+        task_metadata_file = self.spec_dir / "task_metadata.json"
+        require_review_before_coding = False
+        if task_metadata_file.exists():
+            with open(task_metadata_file, encoding="utf-8") as f:
+                task_metadata = json.load(f)
+                require_review_before_coding = task_metadata.get(
+                    "requireReviewBeforeCoding", False
+                )
+
+        # Emit PLANNING_COMPLETE event for XState machine transition
+        # This signals the frontend that spec creation is done
+        task_emitter = TaskEventEmitter.from_spec_dir(self.spec_dir)
+        task_emitter.emit(
+            "PLANNING_COMPLETE",
+            {
+                "hasSubtasks": False,  # Spec creation doesn't have subtasks yet
+                "subtaskCount": 0,
+                "requireReviewBeforeCoding": require_review_before_coding,
+            },
+        )
+
         # === HUMAN REVIEW CHECKPOINT ===
         return self._run_review_checkpoint(auto_approve)
 

apps/frontend/XSTATE_MIGRATION_SUMMARY.md

@@ -0,0 +1,172 @@
+# XState Task State Machine Migration - Summary
+
+**Issue:** #1338
+**PR:** #1575
+**Date:** 2026-01-28
+**Branch:** fix/1524-xstate-clean
+
+## Overview
+
+Migrated task status management from scattered decision logic across multiple handler files to a centralized XState v5 state machine. This eliminates race conditions, inconsistent status updates, and makes the task lifecycle formally defined and testable.
+
+## Critical Dependencies & Blockers
+
+### 1. Windows Credential Manager Fix (Required for Testing)
+**PR:** #1569 - fix(windows): fix Windows Credential Manager authentication
+**Issue:** #1525
+
+This PR includes changes that depend on the Windows authentication fix. We could not complete end-to-end testing without this fix in place. If a different solution is implemented for #1525, we can remove these changes and resubmit.
+
+### 2. spec_runner.py Project Detection Fix
+**Issue:** #1570 - spec_runner.py incorrectly detects auto-claude project as source directory
+
+We encountered and fixed this bug during development as it was blocking our test workflow. The fix is included in this PR.
+
+## Implementation Phases
+
+| Phase | Description | Status |
+|-------|-------------|--------|
+| Phase 1 | Create XState machine definition (task-machine.ts) | ✅ Complete |
+| Phase 2 | Create TaskStateManager singleton wrapper | ✅ Complete |
+| Phase 3 | Integrate into agent-events-handlers.ts | ⏸️ Partially done |
+| Phase 4 | Remove legacy TaskStateMachine class | ❌ Not started |
+
+### Why We Stopped at Phase 2
+
+The original scope was to introduce XState as the new state management approach. Full integration (Phase 3-4) requires:
+
+- Extensive refactoring of agent-events-handlers.ts to remove all legacy decision logic
+- Removing the old TaskStateMachine class entirely
+- Migration of all status persistence to go through XState
+
+We delivered Phases 1-2 to establish the foundation. The current state has both systems running in parallel with XState as primary:
+
+- **XState is primary:** When TaskStateManager returns a valid state transition, that decision is used
+- **Legacy as fallback:** The old TaskStateMachine logic only applies when XState doesn't produce a decision
+- **Safe rollback:** If XState causes issues, the legacy system is still present and can take over
+
+This dual-system approach allows:
+- Validation that XState produces correct state transitions in production
+- Safe rollback if issues arise
+- Incremental adoption path for Phase 3-4
+
+## What Changed
+
+### Before (Old Architecture)
+- Status decisions scattered across agent-events-handlers.ts, execution-handlers.ts, worktree-handlers.ts
+- `validateStatusTransition()` function with complex conditional logic
+- TaskStateMachine class that was essentially an event emitter wrapper
+- Multiple places persisting status to implementation_plan.json
+- Race conditions possible when multiple handlers tried to update status
+
+### After (New Architecture)
+- **Single source of truth:** TaskStateManager (XState-based singleton)
+- **Formal state machine:** taskMachine with explicit states and transitions
+- **Centralized persistence:** Status written to JSON from one place
+- **Testable:** Unit tests verify all state transitions
+- **Observable:** XState actors can be inspected/visualized
+
+## State Machine States
+
+```
+backlog → planning → coding → qa_review → qa_fixing → human_review → done
+                  ↘ plan_review ↗              ↓
+                                             error
+```
+
+| State | Maps to Legacy Status | reviewReason |
+|-------|----------------------|--------------|
+| backlog | backlog | - |
+| planning | in_progress | - |
+| coding | in_progress | - |
+| plan_review | human_review | plan_review |
+| qa_review | ai_review | - |
+| qa_fixing | ai_review | - |
+| human_review | human_review | completed or stopped |
+| creating_pr | human_review | completed |
+| pr_created | pr_created | - |
+| error | human_review | errors |
+| done | done | - |
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `apps/frontend/src/shared/state-machines/task-machine.ts` | XState machine definition |
+| `apps/frontend/src/main/task-state-manager.ts` | Singleton service wrapping XState actors |
+| `apps/frontend/src/shared/state-machines/__tests__/task-machine.test.ts` | State machine unit tests (35 tests) |
+| `apps/frontend/src/main/__tests__/task-state-manager.test.ts` | Manager service unit tests (20 tests) |
+| `apps/frontend/src/main/ipc-handlers/agent-events-handlers.ts` | Refactored to call TaskStateManager |
+
+## Events
+
+The state machine responds to these events:
+
+| Event | Triggered By |
+|-------|-------------|
+| PLANNING_STARTED | Execution progress phase=planning |
+| PLANNING_COMPLETE | Execution progress moving past planning |
+| PLAN_APPROVED | User clicks "Proceed to Coding" from plan_review |
+| CODING_STARTED | Execution progress phase=coding |
+| QA_STARTED | Execution progress phase=qa_review |
+| QA_PASSED | Execution progress phase=complete |
+| QA_FAILED | Execution progress phase=qa_fixing |
+| PROCESS_EXITED | Agent process exit event |
+| USER_STOPPED | User clicks stop |
+| USER_RESUMED | User resumes task |
+| MARK_DONE | User marks task as done |
+| CREATE_PR | User initiates PR creation |
+| PR_CREATED | PR successfully created |
+
+## Rollback Plan
+
+If issues arise post-merge:
+
+1. **Quick rollback:** `git revert <merge-commit>`
+2. **Restore point:** Commit 3e5f004a has old code intact
+3. **Legacy persistence still works:** implementation_plan.json continues to store status
+
+## Testing
+
+| Test Suite | Result |
+|------------|--------|
+| Frontend unit tests | ✅ 2579 passed |
+| TypeScript strict mode | ✅ Pass |
+| Biome lint | ✅ Pass |
+| XState machine tests | ✅ 35 passed |
+| TaskStateManager tests | ✅ 20 passed |
+| Python backend tests | ✅ Pass |
+
+## Session Fixes (2026-01-28)
+
+### Fixed Issues
+
+1. **Badge showing "Needs Review" instead of "Complete"** - Added `effectiveReviewReason` logic in TaskCard.tsx that sets 'completed' when phase === 'complete'
+
+2. **Task showing "Incomplete" badge for plan_review** - Added 'plan_review' to exclusion list in `isIncompleteHumanReview`
+
+3. **Missing "Proceed to Coding" button** - Restored in WorkspaceMessages.tsx for plan_review flow
+
+4. **Wrong XState event for plan_review → coding** - Fixed to send PLAN_APPROVED instead of PLANNING_STARTED when starting from plan_review state
+
+5. **Stuck detection logic** - Reverted useTaskDetail.ts to simpler logic from working branch (only skip 'planning' phase, 2s timeout)
+
+## Outstanding Items (Requires PM Input)
+
+### 1. Future: Subtask XState Migration
+- **Issue:** `subtask.status` is checked directly in UI code
+- **Recommendation:** Should be managed by state machine for consistency
+- **Status:** Out of scope for current PR, document for future work
+
+## Future Improvements
+
+- Add @stately-ai/inspect for runtime devtools
+- **Subtask state management** - Track individual subtask states within the machine using XState parallel states
+- Add more granular QA states (qa_round_1, qa_round_2, etc.)
+- Complete Phase 3-4: Full integration and removal of legacy TaskStateMachine class
+
+## Visualization
+
+The state machine can be visualized at [Stately.ai Editor](https://stately.ai/editor):
+1. Paste the contents of task-machine.ts
+2. Click "Visualize" to see the state diagram

apps/frontend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-claude-ui",
-  "version": "2.7.5",
+  "version": "2.7.6-beta.1",
   "type": "module",
   "description": "Desktop UI for Auto Claude autonomous coding framework",
   "homepage": "https://github.com/AndyMik90/Auto-Claude",
@@ -36,6 +36,8 @@
     "package:win": "node scripts/package-with-python.cjs --win",
     "package:linux": "node scripts/package-with-python.cjs --linux",
     "package:flatpak": "node scripts/package-with-python.cjs --linux flatpak",
+    "verify:linux": "node scripts/verify-linux-packages.cjs dist",
+    "test:verify-linux": "node --test scripts/verify-linux-packages.test.mjs",
     "start:packaged:mac": "open dist/mac-arm64/Auto-Claude.app || open dist/mac/Auto-Claude.app",
     "start:packaged:win": "start \"\" \"dist\\win-unpacked\\Auto-Claude.exe\"",
     "start:packaged:linux": "./dist/linux-unpacked/auto-claude",
@@ -98,6 +100,7 @@
     "semver": "^7.7.3",
     "tailwind-merge": "^3.4.0",
     "uuid": "^13.0.0",
+    "xstate": "^5.26.0",
     "zod": "^4.2.1",
     "zustand": "^5.0.9"
   },
@@ -165,14 +168,6 @@
         "from": "resources/icon.ico",
         "to": "icon.ico"
       },
-      {
-        "from": "python-runtime/${os}-${arch}/python",
-        "to": "python"
-      },
-      {
-        "from": "python-runtime/${os}-${arch}/site-packages",
-        "to": "python-site-packages"
-      },
       {
         "from": "../backend",
         "to": "backend",
@@ -202,6 +197,16 @@
       "target": [
         "dmg",
         "zip"
+      ],
+      "extraResources": [
+        {
+          "from": "python-runtime/${os}-${arch}/python",
+          "to": "python"
+        },
+        {
+          "from": "python-runtime/${os}-${arch}/site-packages",
+          "to": "python-site-packages"
+        }
       ]
     },
     "win": {
@@ -209,6 +214,16 @@
       "target": [
         "nsis",
         "zip"
+      ],
+      "extraResources": [
+        {
+          "from": "python-runtime/${os}-${arch}/python",
+          "to": "python"
+        },
+        {
+          "from": "python-runtime/${os}-${arch}/site-packages",
+          "to": "python-site-packages"
+        }
       ]
     },
     "linux": {
@@ -218,7 +233,17 @@
         "deb",
         "flatpak"
       ],
-      "category": "Development"
+      "category": "Development",
+      "extraResources": [
+        {
+          "from": "python-runtime/${os}-${arch}/python",
+          "to": "python"
+        },
+        {
+          "from": "python-runtime/${os}-${arch}/site-packages",
+          "to": "python-site-packages"
+        }
+      ]
     },
     "flatpak": {
       "runtime": "org.freedesktop.Platform",

apps/frontend/scripts/verify-linux-packages.cjs

@@ -0,0 +1,406 @@
+#!/usr/bin/env node
+/**
+ * Verify Linux package contents to ensure alignment between AppImage, deb, and Flatpak.
+ *
+ * This script extracts and inspects each Linux package format to verify that critical
+ * files (Python binary, backend code, Python packages) are present and correctly bundled.
+ *
+ * Usage: node scripts/verify-linux-packages.cjs [dist-dir]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// Critical Python packages that must be present
+const CRITICAL_PACKAGES = [
+  'secretstorage', // Linux OAuth token storage
+  'pydantic_core',
+  'claude_agent_sdk',
+  'dotenv',
+];
+
+// Minimum expected Flatpak file size (50 MB)
+// Flatpak files are large OCI archives; anything smaller is suspicious
+// Based on observed minimum sizes of valid builds
+const FLATPAK_MIN_SIZE_MB = 50;
+
+// Colors for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+};
+
+function log(message, color = colors.reset) {
+  console.log(`${color}${message}${colors.reset}`);
+}
+
+function logSuccess(message) {
+  log(`✓ ${message}`, colors.green);
+}
+
+function logError(message) {
+  log(`✗ ${message}`, colors.red);
+}
+
+function logWarning(message) {
+  log(`⚠ ${message}`, colors.yellow);
+}
+
+function logInfo(message) {
+  log(`ℹ ${message}`, colors.cyan);
+}
+
+/**
+ * Check if a command exists
+ * Uses 'which' directly without shell interpolation to prevent command injection
+ */
+function commandExists(cmd) {
+  const result = spawnSync('which', [cmd], { stdio: 'ignore' });
+  return result.status === 0;
+}
+
+/**
+ * Find all Linux packages in the dist directory
+ */
+function findPackages(distDir) {
+  const packages = {
+    appImage: null,
+    deb: null,
+    flatpak: null,
+  };
+
+  if (!fs.existsSync(distDir)) {
+    logError(`Distribution directory not found: ${distDir}`);
+    return packages;
+  }
+
+  const files = fs.readdirSync(distDir);
+
+  for (const file of files) {
+    const fullPath = path.join(distDir, file);
+
+    if (file.endsWith('.AppImage')) {
+      if (!packages.appImage) {
+        packages.appImage = fullPath;
+      } else {
+        logWarning(`Multiple AppImage files found, using first: ${path.basename(packages.appImage)}`);
+      }
+    } else if (file.endsWith('.deb')) {
+      if (!packages.deb) {
+        packages.deb = fullPath;
+      } else {
+        logWarning(`Multiple deb files found, using first: ${path.basename(packages.deb)}`);
+      }
+    } else if (file.endsWith('.flatpak')) {
+      if (!packages.flatpak) {
+        packages.flatpak = fullPath;
+      } else {
+        logWarning(`Multiple Flatpak files found, using first: ${path.basename(packages.flatpak)}`);
+      }
+    }
+  }
+
+  return packages;
+}
+
+/**
+ * Common file list verification logic
+ * @param {string[]} files - List of files from package
+ * @param {string} packageType - Type of package (for error messages)
+ * @returns {Object} Verification result with verified flag and issues array
+ *
+ * File formats:
+ * - AppImage (bsdtar): './resources/python', './resources/backend/file.py'
+ * - deb (dpkg-deb -c): 'resources/python', 'resources/backend/file.py' (in last column)
+ */
+function verifyFileList(files, packageType) {
+  const issues = [];
+
+  // Normalize paths by removing trailing slashes (archive tools commonly add these)
+  const normalizePath = (p) => p.replace(/\/+$/, '');
+
+  // Check for Python binary directory
+  // AppImage: './resources/python' or './resources/python/' (with trailing slash)
+  // deb: 'resources/python' or 'resources/python/' (with trailing slash)
+  // Must NOT match 'resources/python-site-packages'
+  const pythonBinFound = files.some((f) => {
+    const normalized = normalizePath(f);
+    return (
+      (normalized === './resources/python' ||
+        normalized === 'resources/python' ||
+        normalized.endsWith('/resources/python')) &&
+      !f.includes('python-site-packages')
+    );
+  });
+  if (!pythonBinFound) {
+    issues.push(`Python binary directory not found in ${packageType}`);
+  }
+
+  // Check for backend directory (must be under resources/)
+  const backendFound = files.some((f) => {
+    const normalized = normalizePath(f);
+    return (
+      f.includes('./resources/backend/') ||
+      f.includes('resources/backend/') ||
+      normalized === './resources/backend' ||
+      normalized === 'resources/backend'
+    );
+  });
+  if (!backendFound) {
+    issues.push(`Backend directory not found in ${packageType}`);
+  }
+
+  // Check for critical Python packages (must be under python-site-packages/)
+  for (const pkg of CRITICAL_PACKAGES) {
+    // Match: './resources/python-site-packages/secretstorage/__init__.py'
+    // Match: 'resources/python-site-packages/secretstorage/__init__.py'
+    // Don't match: '/some/other/path/secretstorage/'
+    const found = files.some(
+      (f) => f.includes(`python-site-packages/${pkg}/`) || f.includes(`python-site-packages/${pkg}.`),
+    );
+    if (!found) {
+      issues.push(`Python package not found: ${pkg}`);
+    }
+  }
+
+  return {
+    verified: issues.length === 0,
+    issues,
+    fileCount: files.filter((f) => f.trim()).length,
+  };
+}
+
+/**
+ * Verify AppImage contents using bsdtar (libarchive)
+ */
+function verifyAppImage(appImagePath) {
+  logInfo(`Verifying AppImage: ${path.basename(appImagePath)}`);
+
+  // Check if bsdtar is available
+  if (!commandExists('bsdtar')) {
+    logWarning('bsdtar not found. Install with: sudo apt-get install libarchive-tools');
+    logWarning('Skipping AppImage verification');
+    return { verified: false, reason: 'bsdtar not available', critical: true };
+  }
+
+  // Extract file list from AppImage using bsdtar
+  const result = spawnSync('bsdtar', ['-t', '-f', appImagePath], {
+    stdio: 'pipe',
+    encoding: 'utf-8',
+    maxBuffer: 50 * 1024 * 1024, // 50MB buffer for large file listings
+  });
+
+  // Check for spawn errors (e.g., permission denied, memory issues)
+  if (result.error) {
+    logError(`Failed to execute bsdtar: ${result.error.message}`);
+    return { verified: false, reason: `Command execution failed: ${result.error.message}` };
+  }
+
+  if (result.status !== 0) {
+    logError(`Failed to read AppImage: ${result.stderr}`);
+    return { verified: false, reason: 'Failed to extract file list' };
+  }
+
+  const files = result.stdout.split('\n');
+  return verifyFileList(files, 'AppImage');
+}
+
+/**
+ * Verify deb package contents
+ */
+function verifyDeb(debPath) {
+  logInfo(`Verifying deb package: ${path.basename(debPath)}`);
+
+  // Check if dpkg is available
+  if (!commandExists('dpkg-deb')) {
+    logWarning('dpkg-deb not found. Skipping deb verification');
+    return { verified: false, reason: 'dpkg-deb not available', critical: true };
+  }
+
+  // List contents of deb package
+  const result = spawnSync('dpkg-deb', ['-c', debPath], {
+    stdio: 'pipe',
+    encoding: 'utf-8',
+    maxBuffer: 50 * 1024 * 1024, // 50MB buffer for large file listings
+  });
+
+  // Check for spawn errors (e.g., permission denied, memory issues)
+  if (result.error) {
+    logError(`Failed to execute dpkg-deb: ${result.error.message}`);
+    return { verified: false, reason: `Command execution failed: ${result.error.message}` };
+  }
+
+  if (result.status !== 0) {
+    logError(`Failed to read deb package: ${result.stderr}`);
+    return { verified: false, reason: 'Failed to extract file list' };
+  }
+
+  const files = result.stdout.split('\n');
+  return verifyFileList(files, 'deb package');
+}
+
+/**
+ * Verify Flatpak package contents
+ * Note: Flatpak is more complex to inspect, so we do basic validation
+ */
+function verifyFlatpak(flatpakPath) {
+  logInfo(`Verifying Flatpak package: ${path.basename(flatpakPath)}`);
+
+  const issues = [];
+
+  // Check if flatpak command is available for detailed validation
+  const hasFlatpakCli = commandExists('flatpak');
+  if (!hasFlatpakCli) {
+    logWarning('flatpak command not found. Skipping detailed Flatpak verification');
+    // Continue with basic file existence/size checks
+  }
+
+  // Check if file exists and is not empty
+  if (!fs.existsSync(flatpakPath)) {
+    return { verified: false, issues: ['Flatpak file does not exist'] };
+  }
+
+  const stats = fs.statSync(flatpakPath);
+  if (stats.size === 0) {
+    return { verified: false, issues: ['Flatpak file is empty'] };
+  }
+
+  // Flatpak files are large OCI archives, so we just verify file size and basic structure
+  // Detailed content inspection would require mounting or extracting the flatpak
+  if (stats.size < FLATPAK_MIN_SIZE_MB * 1024 * 1024) {
+    // Less than minimum size is suspicious
+    issues.push(
+      `Flatpak file seems too small (${(stats.size / 1024 / 1024).toFixed(2)} MB, expected at least ${FLATPAK_MIN_SIZE_MB} MB)`,
+    );
+  }
+
+  return {
+    verified: issues.length === 0,
+    issues,
+    size: stats.size,
+  };
+}
+
+/**
+ * Main verification function
+ */
+function main() {
+  const distDir = process.argv[2] || path.join(__dirname, '..', 'dist');
+
+  log('\n=== Linux Package Verification ===\n', colors.blue);
+  logInfo(`Distribution directory: ${distDir}\n`);
+
+  const packages = findPackages(distDir);
+
+  // Report found packages
+  if (packages.appImage) {
+    logSuccess(`Found AppImage: ${path.basename(packages.appImage)}`);
+  } else {
+    logWarning('No AppImage found');
+  }
+
+  if (packages.deb) {
+    logSuccess(`Found deb: ${path.basename(packages.deb)}`);
+  } else {
+    logWarning('No deb package found');
+  }
+
+  if (packages.flatpak) {
+    logSuccess(`Found Flatpak: ${path.basename(packages.flatpak)}`);
+  } else {
+    logWarning('No Flatpak package found');
+  }
+
+  if (!packages.appImage && !packages.deb && !packages.flatpak) {
+    logError('\nNo Linux packages found to verify!');
+    process.exit(1);
+  }
+
+  log('');
+
+  // Verify each package
+  const results = {};
+
+  if (packages.appImage) {
+    results.appImage = verifyAppImage(packages.appImage);
+  }
+
+  if (packages.deb) {
+    results.deb = verifyDeb(packages.deb);
+  }
+
+  if (packages.flatpak) {
+    results.flatpak = verifyFlatpak(packages.flatpak);
+  }
+
+  // Print results
+  log('\n=== Verification Results ===\n', colors.blue);
+
+  let hasFailures = false;
+  let hasCriticalSkips = false;
+
+  for (const [type, result] of Object.entries(results)) {
+    if (result.reason) {
+      if (result.critical) {
+        logError(`${type}: CRITICAL - SKIPPED (${result.reason})`);
+        hasCriticalSkips = true;
+      } else {
+        logWarning(`${type}: SKIPPED (${result.reason})`);
+      }
+    } else if (result.verified) {
+      logSuccess(`${type}: VERIFIED`);
+      if (result.fileCount) {
+        logInfo(`  Files: ${result.fileCount}`);
+      }
+      if (result.size) {
+        logInfo(`  Size: ${(result.size / 1024 / 1024).toFixed(2)} MB`);
+      }
+    } else {
+      logError(`${type}: FAILED`);
+      hasFailures = true;
+      for (const issue of result.issues || []) {
+        logError(`  - ${issue}`);
+      }
+    }
+  }
+
+  log('');
+
+  if (hasFailures || hasCriticalSkips) {
+    logError('\n=== VERIFICATION FAILED ===\n');
+    if (hasFailures) {
+      log('Some packages are missing critical files. This will cause runtime errors.\n', colors.red);
+    }
+    if (hasCriticalSkips) {
+      log('Some packages could not be verified due to missing required tools.\n', colors.red);
+      log('Install required tools:\n', colors.red);
+      log('  - bsdtar: sudo apt-get install libarchive-tools\n', colors.red);
+      log('  - dpkg-deb: sudo apt-get install dpkg\n', colors.red);
+    }
+    process.exit(1);
+  } else {
+    logSuccess('\n=== ALL PACKAGES VERIFIED ===\n');
+    log('All Linux packages contain the required files.\n', colors.green);
+    process.exit(0);
+  }
+}
+
+// Only run main if this file is executed directly (not imported)
+if (require.main === module) {
+  main();
+}
+
+// Export for testing
+module.exports = {
+  CRITICAL_PACKAGES,
+  findPackages,
+  verifyFileList,
+  verifyAppImage,
+  verifyDeb,
+  verifyFlatpak,
+};

apps/frontend/scripts/verify-linux-packages.test.mjs

@@ -0,0 +1,533 @@
+/**
+ * Tests for verify-linux-packages.cjs
+ *
+ * These tests cover the core logic by calling the actual exported functions.
+ */
+
+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const require = createRequire(import.meta.url);
+
+// Get child_process and save original spawnSync
+const childProcess = require('child_process');
+const originalSpawnSync = childProcess.spawnSync;
+
+// Helper to reload the verification module with a mocked spawnSync
+function loadWithMockedSpawnSync(mockFn) {
+  // Set the mock before requiring
+  childProcess.spawnSync = mockFn;
+  // Clear the module cache
+  delete require.cache[require.resolve('./verify-linux-packages.cjs')];
+  // Re-require the module
+  return require('./verify-linux-packages.cjs');
+}
+
+function restoreSpawnSync() {
+  childProcess.spawnSync = originalSpawnSync;
+  delete require.cache[require.resolve('./verify-linux-packages.cjs')];
+}
+
+// Load the module normally for tests that don't need spawnSync mocking
+const {
+  CRITICAL_PACKAGES,
+  findPackages,
+  verifyFileList,
+  verifyFlatpak,
+} = require('./verify-linux-packages.cjs');
+
+describe('verify-linux-packages', () => {
+  describe('package finding logic', () => {
+    it('should identify all three Linux package types', () => {
+      // Test that findPackages correctly identifies .AppImage, .deb, and .flatpak files
+      const mockFiles = [
+        'Auto-Claude-2.7.5-linux-x86_64.AppImage',
+        'auto-claude_2.7.5_amd64.deb',
+        'com.autoclaude.ui_2.7.5_linux_x86_64.flatpak',
+        'latest-mac.yml',
+        'latest.yml',
+      ];
+
+      const distDir = '/test/dist';
+
+      // Mock fs.existsSync to return true (directory exists)
+      const existsSync = mock.method(fs, 'existsSync', mock.fn(() => true));
+      // Mock fs.readdirSync to return our test files
+      const readdirSync = mock.method(fs, 'readdirSync', mock.fn(() => mockFiles));
+
+      try {
+        const result = findPackages(distDir);
+
+        // Verify the expected results
+        assert.equal(result.appImage, '/test/dist/Auto-Claude-2.7.5-linux-x86_64.AppImage');
+        assert.equal(result.deb, '/test/dist/auto-claude_2.7.5_amd64.deb');
+        assert.equal(result.flatpak, '/test/dist/com.autoclaude.ui_2.7.5_linux_x86_64.flatpak');
+      } finally {
+        existsSync.mock.restore();
+        readdirSync.mock.restore();
+      }
+    });
+
+    it('should handle missing packages gracefully', () => {
+      // Test behavior when packages are missing
+      const mockFiles = ['latest-mac.yml', 'latest.yml'];
+      const distDir = '/test/dist';
+
+      const existsSync = mock.method(fs, 'existsSync', mock.fn(() => true));
+      const readdirSync = mock.method(fs, 'readdirSync', mock.fn(() => mockFiles));
+
+      try {
+        const result = findPackages(distDir);
+
+        assert.equal(result.appImage, null);
+        assert.equal(result.deb, null);
+        assert.equal(result.flatpak, null);
+      } finally {
+        existsSync.mock.restore();
+        readdirSync.mock.restore();
+      }
+    });
+
+    it('should handle missing dist directory', () => {
+      // Test behavior when dist directory doesn't exist
+      const distDir = '/test/dist';
+
+      const existsSync = mock.method(fs, 'existsSync', mock.fn(() => false));
+
+      try {
+        const result = findPackages(distDir);
+
+        // Should return empty packages object without error
+        assert.equal(result.appImage, null);
+        assert.equal(result.deb, null);
+        assert.equal(result.flatpak, null);
+      } finally {
+        existsSync.mock.restore();
+      }
+    });
+
+    it('should warn about duplicate packages', () => {
+      // Test behavior when multiple packages of same type exist
+      const mockFiles = [
+        'Auto-Claude-2.7.5-linux-x86_64.AppImage',
+        'Auto-Claude-2.7.5-linux-x86_64.AppImage', // Duplicate
+        'auto-claude_2.7.5_amd64.deb',
+        'auto-claude_2.7.5_amd64.deb', // Duplicate
+        'com.autoclaude.ui_2.7.5_linux_x86_64.flatpak',
+      ];
+      const distDir = '/test/dist';
+
+      const existsSync = mock.method(fs, 'existsSync', mock.fn(() => true));
+      const readdirSync = mock.method(fs, 'readdirSync', mock.fn(() => mockFiles));
+
+      try {
+        const result = findPackages(distDir);
+
+        // Should still find packages, using first occurrence
+        assert.equal(result.appImage, '/test/dist/Auto-Claude-2.7.5-linux-x86_64.AppImage');
+        assert.equal(result.deb, '/test/dist/auto-claude_2.7.5_amd64.deb');
+        assert.equal(result.flatpak, '/test/dist/com.autoclaude.ui_2.7.5_linux_x86_64.flatpak');
+      } finally {
+        existsSync.mock.restore();
+        readdirSync.mock.restore();
+      }
+    });
+  });
+
+  describe('critical packages list', () => {
+    it('should contain all required Linux packages', () => {
+      assert.ok(CRITICAL_PACKAGES.includes('secretstorage'), 'secretstorage must be present for Linux OAuth');
+      assert.ok(CRITICAL_PACKAGES.includes('pydantic_core'), 'pydantic_core must be present');
+      assert.ok(CRITICAL_PACKAGES.includes('claude_agent_sdk'), 'claude_agent_sdk must be present');
+      assert.ok(CRITICAL_PACKAGES.includes('dotenv'), 'dotenv must be present');
+    });
+  });
+
+  describe('file content verification logic', () => {
+    it('should detect Python binary in file list', () => {
+      // AppImage format uses './' prefix
+      const mockFiles = [
+        'usr/bin/auto-claude',
+        './resources/python',
+        './resources/backend/core/client.py',
+        './resources/python-site-packages/secretstorage/__init__.py',
+        './resources/python-site-packages/pydantic_core/__init__.py',
+        './resources/python-site-packages/claude_agent_sdk/__init__.py',
+        './resources/python-site-packages/dotenv/__init__.py',
+      ];
+
+      const result = verifyFileList(mockFiles, 'test-package');
+      assert.ok(result.verified, 'Should detect Python binary directory');
+      assert.equal(result.issues.length, 0);
+    });
+
+    it('should detect Python binary with trailing slashes', () => {
+      // Archive tools like bsdtar/dpkg-deb commonly output directories with trailing slashes
+      const mockFiles = [
+        'usr/bin/auto-claude',
+        './resources/python/',  // Trailing slash
+        'resources/backend/',   // Trailing slash
+        './resources/python-site-packages/secretstorage/__init__.py',
+        './resources/python-site-packages/pydantic_core/__init__.py',
+        './resources/python-site-packages/claude_agent_sdk/__init__.py',
+        './resources/python-site-packages/dotenv/__init__.py',
+      ];
+
+      const result = verifyFileList(mockFiles, 'test-package');
+      assert.ok(result.verified, 'Should detect Python binary directory with trailing slash');
+      assert.equal(result.issues.length, 0);
+    });
+
+    it('should detect backend directory in file list', () => {
+      const mockFiles = [
+        'usr/bin/auto-claude',
+        './resources/python',
+        './resources/backend/core/client.py',
+        './resources/python-site-packages/secretstorage/__init__.py',
+        './resources/python-site-packages/pydantic_core/__init__.py',
+        './resources/python-site-packages/claude_agent_sdk/__init__.py',
+        './resources/python-site-packages/dotenv/__init__.py',
+      ];
+
+      const result = verifyFileList(mockFiles, 'test-package');
+      assert.ok(result.verified, 'Should detect backend directory');
+      assert.equal(result.issues.length, 0);
+    });
+
+    it('should detect critical Python packages', () => {
+      const mockFiles = [
+        'usr/bin/auto-claude',
+        './resources/python',
+        './resources/backend/core/client.py',
+        './resources/python-site-packages/secretstorage/__init__.py',
+        './resources/python-site-packages/pydantic_core/__init__.py',
+        './resources/python-site-packages/claude_agent_sdk/__init__.py',
+        './resources/python-site-packages/dotenv/__init__.py',
+      ];
+
+      const result = verifyFileList(mockFiles, 'test-package');
+      assert.ok(result.verified, 'Should detect all critical packages');
+      assert.equal(result.issues.length, 0);
+    });
+
+    it('should report missing packages', () => {
+      const mockFiles = [
+        'usr/bin/auto-claude',
+        './resources/python',
+        './resources/backend/core/client.py',
+        './resources/python-site-packages/dotenv/__init__.py',
+      ];
+
+      const result = verifyFileList(mockFiles, 'test-package');
+
+      assert.ok(!result.verified, 'Should fail verification');
+      assert.ok(result.issues.includes('Python package not found: secretstorage'));
+      assert.ok(result.issues.includes('Python package not found: pydantic_core'));
+      assert.ok(result.issues.includes('Python package not found: claude_agent_sdk'));
+      assert.ok(!result.issues.some((i) => i.includes('dotenv')));
+    });
+
+    it('should not match python-site-packages when looking for python binary', () => {
+      const mockFiles = [
+        'usr/bin/auto-claude',
+        './resources/python-site-packages/secretstorage/__init__.py',
+        './resources/python-site-packages/pydantic_core/__init__.py',
+        './resources/python-site-packages/claude_agent_sdk/__init__.py',
+        './resources/python-site-packages/dotenv/__init__.py',
+        // Note: NO './resources/python' entry
+      ];
+
+      const result = verifyFileList(mockFiles, 'test-package');
+
+      assert.ok(!result.verified, 'Should fail verification');
+      assert.ok(result.issues.some((i) => i.includes('Python binary directory not found')));
+    });
+
+    it('should not match unrelated paths when looking for packages', () => {
+      const mockFiles = [
+        'usr/bin/auto-claude',
+        './resources/python',
+        './resources/backend/core/client.py',
+        // These paths end with package names but are NOT under python-site-packages
+        './some/other/path/secretstorage/file.txt',
+        './unrelated/dotenv/config',
+        './another/pydantic_core/standalone/__init__.py',
+      ];
+
+      const result = verifyFileList(mockFiles, 'test-package');
+
+      assert.ok(!result.verified, 'Should fail verification');
+      assert.ok(result.issues.some((i) => i.includes('Python package not found: secretstorage')));
+    });
+  });
+
+  describe('Flatpak file validation', () => {
+    it('should reject empty Flatpak files', () => {
+      const flatpakPath = '/test/app.flatpak';
+      const mockStat = { size: 0 };
+
+      // Mock fs.existsSync to return true
+      const existsSync = mock.method(fs, 'existsSync', mock.fn(() => true));
+      // Mock fs.statSync to return empty file stats
+      const statSync = mock.method(fs, 'statSync', mock.fn(() => mockStat));
+
+      try {
+        const result = verifyFlatpak(flatpakPath);
+
+        assert.ok(!result.verified, 'Should reject empty Flatpak files');
+        assert.ok(result.issues.includes('Flatpak file is empty'));
+      } finally {
+        existsSync.mock.restore();
+        statSync.mock.restore();
+      }
+    });
+
+    it('should warn about suspiciously small Flatpak files', () => {
+      const flatpakPath = '/test/app.flatpak';
+      const mockStat = { size: 10 * 1024 * 1024 }; // 10 MB
+
+      const existsSync = mock.method(fs, 'existsSync', mock.fn(() => true));
+      const statSync = mock.method(fs, 'statSync', mock.fn(() => mockStat));
+
+      try {
+        const result = verifyFlatpak(flatpakPath);
+
+        assert.ok(!result.verified, 'Should fail verification for too-small files');
+        assert.ok(result.issues.some((i) => i.includes('too small')));
+      } finally {
+        existsSync.mock.restore();
+        statSync.mock.restore();
+      }
+    });
+
+    it('should accept reasonable Flatpak file sizes', () => {
+      const flatpakPath = '/test/app.flatpak';
+      const mockStat = { size: 133 * 1024 * 1024 }; // 133 MB (typical size)
+
+      const existsSync = mock.method(fs, 'existsSync', mock.fn(() => true));
+      const statSync = mock.method(fs, 'statSync', mock.fn(() => mockStat));
+
+      try {
+        const result = verifyFlatpak(flatpakPath);
+
+        assert.ok(result.verified, 'Should accept reasonable Flatpak file sizes');
+        assert.equal(result.issues.length, 0);
+      } finally {
+        existsSync.mock.restore();
+        statSync.mock.restore();
+      }
+    });
+
+    it('should handle non-existent Flatpak files', () => {
+      const flatpakPath = '/test/nonexistent.flatpak';
+
+      const existsSync = mock.method(fs, 'existsSync', mock.fn(() => false));
+
+      try {
+        const result = verifyFlatpak(flatpakPath);
+
+        assert.ok(!result.verified, 'Should reject non-existent Flatpak files');
+        assert.ok(result.issues.includes('Flatpak file does not exist'));
+      } finally {
+        existsSync.mock.restore();
+      }
+    });
+  });
+
+  describe('AppImage verification', () => {
+    const appImagePath = '/test/Auto-Claude-2.7.5-linux-x86_64.AppImage';
+
+    it('should successfully verify valid AppImage', () => {
+      const mockFiles = [
+        './resources/python',
+        './resources/backend/core/client.py',
+        './resources/python-site-packages/secretstorage/__init__.py',
+        './resources/python-site-packages/pydantic_core/__init__.py',
+        './resources/python-site-packages/claude_agent_sdk/__init__.py',
+        './resources/python-site-packages/dotenv/__init__.py',
+      ];
+
+      const mockFn = (cmd, args) => {
+        if (cmd === 'which' && args[0] === 'bsdtar') {
+          return { status: 0, stdout: '/usr/bin/bsdtar', stderr: '' };
+        }
+        if (cmd === 'bsdtar') {
+          return { status: 0, stdout: mockFiles.join('\n'), stderr: '', error: undefined };
+        }
+        return { status: 1, stderr: 'Unknown command' };
+      };
+
+      const { verifyAppImage } = loadWithMockedSpawnSync(mockFn);
+      const result = verifyAppImage(appImagePath);
+
+      restoreSpawnSync();
+
+      assert.ok(result.verified, 'Should verify valid AppImage');
+      assert.equal(result.issues.length, 0);
+      assert.equal(result.fileCount, mockFiles.length);
+    });
+
+    it('should handle spawn errors (OS-level failures)', () => {
+      const spawnError = new Error('EACCES: permission denied');
+
+      const mockFn = (cmd) => {
+        if (cmd === 'which') {
+          return { status: 0, stdout: '/usr/bin/bsdtar', stderr: '', error: undefined };
+        }
+        if (cmd === 'bsdtar') {
+          return { status: null, stdout: '', stderr: '', error: spawnError };
+        }
+        return { status: 1, stderr: 'Unknown command' };
+      };
+
+      const { verifyAppImage } = loadWithMockedSpawnSync(mockFn);
+      const result = verifyAppImage(appImagePath);
+
+      restoreSpawnSync();
+
+      assert.ok(!result.verified, 'Should fail on spawn error');
+      assert.ok(result.reason.includes('Command execution failed'));
+      assert.ok(result.reason.includes('permission denied'));
+    });
+
+    it('should handle non-zero exit status from bsdtar', () => {
+      const mockFn = (cmd) => {
+        if (cmd === 'which') {
+          return { status: 0, stdout: '/usr/bin/bsdtar', stderr: '', error: undefined };
+        }
+        if (cmd === 'bsdtar') {
+          return { status: 1, stdout: '', stderr: 'bsdtar: Error: Not an AppImage file', error: undefined };
+        }
+        return { status: 1, stderr: 'Unknown command' };
+      };
+
+      const { verifyAppImage } = loadWithMockedSpawnSync(mockFn);
+      const result = verifyAppImage(appImagePath);
+
+      restoreSpawnSync();
+
+      assert.ok(!result.verified, 'Should fail on non-zero status');
+      assert.equal(result.reason, 'Failed to extract file list');
+    });
+
+    it('should handle missing bsdtar tool', () => {
+      const mockFn = (cmd) => {
+        if (cmd === 'which') {
+          return { status: 1, stdout: '', stderr: '', error: undefined };
+        }
+        return { status: 1, stderr: 'Unknown command' };
+      };
+
+      const { verifyAppImage } = loadWithMockedSpawnSync(mockFn);
+      const result = verifyAppImage(appImagePath);
+
+      restoreSpawnSync();
+
+      assert.ok(!result.verified, 'Should fail when bsdtar is missing');
+      assert.equal(result.reason, 'bsdtar not available');
+      assert.ok(result.critical, 'Should be marked as critical');
+    });
+  });
+
+  describe('deb package verification', () => {
+    const debPath = '/test/auto-claude_2.7.5_amd64.deb';
+
+    it('should successfully verify valid deb package', () => {
+      const mockFiles = [
+        'drwxr-xr-x root/root         0 2025-01-01 00:00 ./resources/python',
+        '-rw-r--r-- root/root      1234 2025-01-01 00:00 ./resources/backend/core/client.py',
+        '-rw-r--r-- root/root       567 2025-01-01 00:00 ./resources/python-site-packages/secretstorage/__init__.py',
+        '-rw-r--r-- root/root       789 2025-01-01 00:00 ./resources/python-site-packages/pydantic_core/__init__.py',
+        '-rw-r--r-- root/root       456 2025-01-01 00:00 ./resources/python-site-packages/claude_agent_sdk/__init__.py',
+        '-rw-r--r-- root/root       321 2025-01-01 00:00 ./resources/python-site-packages/dotenv/__init__.py',
+      ];
+
+      const mockFn = (cmd, args) => {
+        if (cmd === 'which' && args[0] === 'dpkg-deb') {
+          return { status: 0, stdout: '/usr/bin/dpkg-deb', stderr: '', error: undefined };
+        }
+        if (cmd === 'dpkg-deb') {
+          return { status: 0, stdout: mockFiles.join('\n'), stderr: '', error: undefined };
+        }
+        return { status: 1, stderr: 'Unknown command' };
+      };
+
+      const { verifyDeb } = loadWithMockedSpawnSync(mockFn);
+      const result = verifyDeb(debPath);
+
+      restoreSpawnSync();
+
+      assert.ok(result.verified, 'Should verify valid deb package');
+      assert.equal(result.issues.length, 0);
+      assert.equal(result.fileCount, mockFiles.length);
+    });
+
+    it('should handle spawn errors (OS-level failures)', () => {
+      const spawnError = new Error('ENOMEM: Cannot allocate memory');
+
+      const mockFn = (cmd) => {
+        if (cmd === 'which') {
+          return { status: 0, stdout: '/usr/bin/dpkg-deb', stderr: '', error: undefined };
+        }
+        if (cmd === 'dpkg-deb') {
+          return { status: null, stdout: '', stderr: '', error: spawnError };
+        }
+        return { status: 1, stderr: 'Unknown command' };
+      };
+
+      const { verifyDeb } = loadWithMockedSpawnSync(mockFn);
+      const result = verifyDeb(debPath);
+
+      restoreSpawnSync();
+
+      assert.ok(!result.verified, 'Should fail on spawn error');
+      assert.ok(result.reason.includes('Command execution failed'));
+      assert.ok(result.reason.includes('Cannot allocate memory'));
+    });
+
+    it('should handle non-zero exit status from dpkg-deb', () => {
+      const mockFn = (cmd) => {
+        if (cmd === 'which') {
+          return { status: 0, stdout: '/usr/bin/dpkg-deb', stderr: '', error: undefined };
+        }
+        if (cmd === 'dpkg-deb') {
+          return { status: 2, stdout: '', stderr: 'dpkg-deb: error: cannot read archive', error: undefined };
+        }
+        return { status: 1, stderr: 'Unknown command' };
+      };
+
+      const { verifyDeb } = loadWithMockedSpawnSync(mockFn);
+      const result = verifyDeb(debPath);
+
+      restoreSpawnSync();
+
+      assert.ok(!result.verified, 'Should fail on non-zero status');
+      assert.equal(result.reason, 'Failed to extract file list');
+    });
+
+    it('should handle missing dpkg-deb tool', () => {
+      const mockFn = (cmd) => {
+        if (cmd === 'which') {
+          return { status: 1, stdout: '', stderr: '', error: undefined };
+        }
+        return { status: 1, stderr: 'Unknown command' };
+      };
+
+      const { verifyDeb } = loadWithMockedSpawnSync(mockFn);
+      const result = verifyDeb(debPath);
+
+      restoreSpawnSync();
+
+      assert.ok(!result.verified, 'Should fail when dpkg-deb is missing');
+      assert.equal(result.reason, 'dpkg-deb not available');
+      assert.ok(result.critical, 'Should be marked as critical');
+    });
+  });
+});

apps/frontend/src/__tests__/e2e/smoke.test.ts

@@ -396,7 +396,7 @@ describe('E2E Smoke Tests', () => {
         statusHandler({}, 'task-001', 'in_progress');
       }
 
-      expect(statusCallback).toHaveBeenCalledWith('task-001', 'in_progress', undefined);
+      expect(statusCallback).toHaveBeenCalledWith('task-001', 'in_progress', undefined, undefined);
 
       // Cleanup listeners
       cleanupProgress();
@@ -656,6 +656,7 @@ describe('E2E Smoke Tests', () => {
           index + 1,
           'task-001',
           status,
+          undefined,
           undefined
         );
       });

apps/frontend/src/__tests__/integration/subprocess-spawn.test.ts

@@ -395,19 +395,20 @@ describe('Subprocess Spawn Integration', () => {
         expect(manager.getRunningTasks()).toHaveLength(2);
       }, { timeout: 5000 });
 
-      // Wait for spawn to complete (ensures exit handlers are attached)
-      await new Promise(resolve => setImmediate(resolve));
+      // Wait for both spawn promises to fully resolve — this ensures the exit
+      // handlers are attached to mockProcess. A single setImmediate is NOT enough
+      // on Windows CI because spawnProcess has async operations (getAPIProfileEnv,
+      // getRecoveryCoordinator) between addProcess and the .on('exit') listener.
+      // Waiting for the promises guarantees spawnProcess has completed fully.
+      await Promise.allSettled([promise1, promise2]);
 
-      // Emit exit for task-1 (first task's handler)
+      // Both tasks share the same mockProcess, so one emit fires both exit handlers
       mockProcess.emit('exit', 0);
-      await promise1;
 
-      // Emit exit for task-2 (second task's handler replaces first due to shared mock process)
-      mockProcess.emit('exit', 0);
-      await promise2;
-
-      // Tasks should be removed from tracking after exit
-      expect(manager.getRunningTasks()).toHaveLength(0);
+      // Wait for tasks to be removed from tracking (cleanup may be async)
+      await vi.waitFor(() => {
+        expect(manager.getRunningTasks()).toHaveLength(0);
+      }, { timeout: 5000 });
     }, 15000);
 
     it('should use configured Python path', async () => {

apps/frontend/src/__tests__/integration/task-lifecycle.test.ts

@@ -241,12 +241,12 @@ describe('Task Lifecycle Integration', () => {
       )?.[1];
 
       if (eventHandler) {
-        eventHandler({}, 'task-001', 'spec_complete');
+        eventHandler({}, 'task-001', 'spec_complete', undefined, undefined);
       }
 
-      // Verify callback was invoked with correct parameters (taskId, status, projectId)
-      // Note: projectId is optional and undefined when not provided
-      expect(callback).toHaveBeenCalledWith('task-001', 'spec_complete', undefined);
+      // Verify callback was invoked with correct parameters (taskId, status, projectId, reviewReason)
+      // Note: projectId/reviewReason are optional and undefined when not provided
+      expect(callback).toHaveBeenCalledWith('task-001', 'spec_complete', undefined, undefined);
     });
 
     it('should emit task:progress event with updated plan during spec creation', async () => {
@@ -379,4 +379,4 @@ describe('Task Lifecycle Integration', () => {
     });
   });
 
-});
+});

apps/frontend/src/main/__tests__/ipc-handlers.test.ts

@@ -689,7 +689,8 @@ describe("IPC Handlers", { timeout: 30000 }, () => {
         "task:statusChange",
         "task-1",
         "human_review",
-        expect.any(String) // projectId for multi-project filtering
+        expect.any(String), // projectId for multi-project filtering
+        "errors"
       );
     });
   });

apps/frontend/src/main/__tests__/project-store.test.ts

@@ -292,6 +292,7 @@ describe('ProjectStore', () => {
         feature: 'Test Feature',
         workflow_type: 'feature',
         services_involved: [],
+        status: 'in_progress',
         phases: [
           {
             phase: 1,
@@ -338,6 +339,7 @@ describe('ProjectStore', () => {
         feature: 'Pending Feature',
         workflow_type: 'feature',
         services_involved: [],
+        status: 'backlog',
         phases: [
           {
             phase: 1,
@@ -377,6 +379,7 @@ describe('ProjectStore', () => {
         feature: 'Complete Feature',
         workflow_type: 'feature',
         services_involved: [],
+        status: 'ai_review',
         phases: [
           {
             phase: 1,
@@ -408,7 +411,7 @@ describe('ProjectStore', () => {
       expect(tasks[0].status).toBe('ai_review');
     });
 
-    it('should determine status as human_review when QA report rejected', async () => {
+    it('should determine status as human_review when plan status is human_review', async () => {
       const specsDir = path.join(TEST_PROJECT_PATH, '.auto-claude', 'specs', '004-rejected');
       mkdirSync(specsDir, { recursive: true });
 
@@ -416,6 +419,8 @@ describe('ProjectStore', () => {
         feature: 'Rejected Feature',
         workflow_type: 'feature',
         services_involved: [],
+        status: 'human_review',
+        reviewReason: 'qa_rejected',
         phases: [
           {
             phase: 1,
@@ -437,11 +442,6 @@ describe('ProjectStore', () => {
         JSON.stringify(plan)
       );
 
-      writeFileSync(
-        path.join(specsDir, 'qa_report.md'),
-        '# QA Report\n\nStatus: REJECTED\n'
-      );
-
       const { ProjectStore } = await import('../project-store');
       const store = new ProjectStore();
 
@@ -451,8 +451,7 @@ describe('ProjectStore', () => {
       expect(tasks[0].status).toBe('human_review');
     });
 
-    it('should determine status as human_review when QA report approved', async () => {
-      // QA approval moves task to human_review (user needs to review before marking done)
+    it('should determine reviewReason from plan when status is human_review', async () => {
       const specsDir = path.join(TEST_PROJECT_PATH, '.auto-claude', 'specs', '005-approved');
       mkdirSync(specsDir, { recursive: true });
 
@@ -460,6 +459,8 @@ describe('ProjectStore', () => {
         feature: 'Approved Feature',
         workflow_type: 'feature',
         services_involved: [],
+        status: 'human_review',
+        reviewReason: 'completed',
         phases: [
           {
             phase: 1,
@@ -481,11 +482,6 @@ describe('ProjectStore', () => {
         JSON.stringify(plan)
       );
 
-      writeFileSync(
-        path.join(specsDir, 'qa_report.md'),
-        '# QA Report\n\nStatus: APPROVED\n'
-      );
-
       const { ProjectStore } = await import('../project-store');
       const store = new ProjectStore();
 

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

@@ -99,7 +99,7 @@ describe('Rate Limit Detector', () => {
     it('should return false for non-rate-limit errors', async () => {
       const { isRateLimitError } = await import('../rate-limit-detector');
 
-      expect(isRateLimitError('authentication required')).toBe(false);
+      expect(isRateLimitError('[CLI] authentication required')).toBe(false);
       expect(isRateLimitError('Task completed')).toBe(false);
     });
   });
@@ -135,10 +135,10 @@ describe('Auth Failure Detection', () => {
   });
 
   describe('detectAuthFailure', () => {
-    it('should detect "authentication required" pattern', async () => {
+    it('should detect "authentication required" pattern with bracket prefix', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'Error: authentication required';
+      const output = '[CLI] authentication required';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
@@ -146,40 +146,40 @@ describe('Auth Failure Detection', () => {
       expect(result.message).toContain('authentication required');
     });
 
-    it('should detect "authentication is required" pattern', async () => {
+    it('should detect "authentication is required" pattern with bracket prefix', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'Authentication is required to proceed';
+      const output = '[Auth] Authentication is required to proceed';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
       expect(result.failureType).toBe('missing');
     });
 
-    it('should detect "not authenticated" pattern', async () => {
+    it('should detect "not authenticated" pattern with bracket prefix', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'Error: not authenticated';
+      const output = '[Error] not authenticated';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
       expect(result.failureType).toBe('missing');
     });
 
-    it('should detect "not yet authenticated" pattern', async () => {
+    it('should detect "not yet authenticated" pattern with bracket prefix', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'You are not yet authenticated';
+      const output = '[CLI] not yet authenticated';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
       expect(result.failureType).toBe('missing');
     });
 
-    it('should detect "login required" pattern', async () => {
+    it('should detect "login required" pattern with bracket prefix', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'Login required';
+      const output = '[CLI] Login required';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
@@ -189,7 +189,7 @@ describe('Auth Failure Detection', () => {
     it('should detect "oauth token invalid" pattern', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'OAuth token is invalid';
+      const output = 'Error: invalid token';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
@@ -199,7 +199,7 @@ describe('Auth Failure Detection', () => {
     it('should detect "oauth token expired" pattern', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'OAuth token expired';
+      const output = 'OAuth token has expired';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
@@ -209,7 +209,7 @@ describe('Auth Failure Detection', () => {
     it('should detect "oauth token missing" pattern', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'OAuth token missing';
+      const output = '[CLI] authentication required - OAuth token missing';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
@@ -219,39 +219,39 @@ describe('Auth Failure Detection', () => {
     it('should detect "unauthorized" pattern', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'Error: Unauthorized';
+      const output = 'Error: unauthorized access';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
       expect(result.failureType).toBe('invalid');
     });
 
-    it('should detect "please log in" pattern', async () => {
+    it('should detect "please log in" pattern with CLI format', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'Please log in to continue';
+      const output = '· Please run /login to continue';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
-      // "please log in" doesn't contain 'required' keyword, so classified as 'unknown'
+      // Contains 'login' pattern
       expect(result.failureType).toBeDefined();
     });
 
-    it('should detect "please authenticate" pattern', async () => {
+    it('should detect "please authenticate" pattern with Error prefix', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'Please authenticate before proceeding';
+      const output = 'Error: authentication required before proceeding';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
-      // "please authenticate" doesn't contain 'required' keyword, so classified as 'unknown'
+      // "Error: ... authentication" matches the pattern
       expect(result.failureType).toBeDefined();
     });
 
     it('should detect "invalid credentials" pattern', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'Invalid credentials provided';
+      const output = 'Error: invalid token credentials provided';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
@@ -261,26 +261,26 @@ describe('Auth Failure Detection', () => {
     it('should detect "invalid token" pattern', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'Invalid token';
+      const output = 'Error: invalid token';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
       expect(result.failureType).toBe('invalid');
     });
 
-    it('should detect "auth failed" pattern', async () => {
+    it('should detect "auth failed" pattern with authentication_error type', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'Auth failed';
+      const output = '{"type":"authentication_error","message":"Auth failed"}';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
     });
 
-    it('should detect "authentication error" pattern', async () => {
+    it('should detect "authentication error" pattern with JSON type', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'Authentication error occurred';
+      const output = '{"type": "authentication_error", "message": "Authentication error occurred"}';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
@@ -289,7 +289,7 @@ describe('Auth Failure Detection', () => {
     it('should detect "session expired" pattern', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'Your session expired';
+      const output = 'Please obtain a new token - your session expired';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
@@ -299,7 +299,7 @@ describe('Auth Failure Detection', () => {
     it('should detect "access denied" pattern', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'Access denied';
+      const output = 'status: 401 - Access denied';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
@@ -309,7 +309,7 @@ describe('Auth Failure Detection', () => {
     it('should detect "permission denied" pattern', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'Permission denied';
+      const output = 'HTTP 401 - Permission denied';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
@@ -329,7 +329,7 @@ describe('Auth Failure Detection', () => {
     it('should detect "credentials missing" pattern', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'Credentials are missing';
+      const output = '[CLI] authentication required - credentials are missing';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
@@ -339,7 +339,7 @@ describe('Auth Failure Detection', () => {
     it('should detect "credentials expired" pattern', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = 'Credentials expired';
+      const output = 'Please refresh your existing token - credentials expired';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
@@ -375,7 +375,7 @@ describe('Auth Failure Detection', () => {
     it('should include profile ID in result', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const result = detectAuthFailure('authentication required', 'custom-profile');
+      const result = detectAuthFailure('[CLI] authentication required', 'custom-profile');
 
       expect(result.isAuthFailure).toBe(true);
       expect(result.profileId).toBe('custom-profile');
@@ -384,7 +384,7 @@ describe('Auth Failure Detection', () => {
     it('should use active profile ID when not specified', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const result = detectAuthFailure('authentication required');
+      const result = detectAuthFailure('[Auth] authentication required');
 
       expect(result.isAuthFailure).toBe(true);
       expect(result.profileId).toBe('test-profile-id');
@@ -403,7 +403,7 @@ describe('Auth Failure Detection', () => {
     it('should provide user-friendly message for missing auth', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const result = detectAuthFailure('authentication required');
+      const result = detectAuthFailure('[CLI] authentication required');
 
       expect(result.isAuthFailure).toBe(true);
       expect(result.message).toContain('Settings');
@@ -413,7 +413,7 @@ describe('Auth Failure Detection', () => {
     it('should provide user-friendly message for expired auth', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const result = detectAuthFailure('session expired');
+      const result = detectAuthFailure('Please obtain a new token - session expired');
 
       expect(result.isAuthFailure).toBe(true);
       expect(result.message).toContain('expired');
@@ -423,7 +423,7 @@ describe('Auth Failure Detection', () => {
     it('should provide user-friendly message for invalid auth', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const result = detectAuthFailure('unauthorized');
+      const result = detectAuthFailure('Error: unauthorized');
 
       expect(result.isAuthFailure).toBe(true);
       expect(result.message).toContain('Invalid');
@@ -434,10 +434,10 @@ describe('Auth Failure Detection', () => {
     it('should return true for auth failure errors', async () => {
       const { isAuthFailureError } = await import('../rate-limit-detector');
 
-      expect(isAuthFailureError('authentication required')).toBe(true);
-      expect(isAuthFailureError('not authenticated')).toBe(true);
-      expect(isAuthFailureError('unauthorized')).toBe(true);
-      expect(isAuthFailureError('invalid token')).toBe(true);
+      expect(isAuthFailureError('[CLI] authentication required')).toBe(true);
+      expect(isAuthFailureError('[Auth] not authenticated')).toBe(true);
+      expect(isAuthFailureError('Error: unauthorized')).toBe(true);
+      expect(isAuthFailureError('Error: invalid token')).toBe(true);
     });
 
     it('should return false for non-auth-failure errors', async () => {
@@ -454,12 +454,12 @@ describe('Auth Failure Detection', () => {
       const { detectRateLimit } = await import('../rate-limit-detector');
 
       const authErrors = [
-        'authentication required',
-        'not authenticated',
-        'unauthorized',
-        'invalid token',
-        'session expired',
-        'please log in'
+        '[CLI] authentication required',
+        '[Auth] not authenticated',
+        'Error: unauthorized',
+        'Error: invalid token',
+        'Please obtain a new token - session expired',
+        '· Please run /login'
       ];
 
       for (const error of authErrors) {
@@ -503,12 +503,12 @@ Please authenticate and try again.`;
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
       const testCases = [
-        'AUTHENTICATION REQUIRED',
-        'Authentication Required',
-        'UNAUTHORIZED',
-        'Unauthorized',
-        'NOT AUTHENTICATED',
-        'Not Authenticated'
+        '[CLI] AUTHENTICATION REQUIRED',
+        '[Auth] Authentication Required',
+        'ERROR: UNAUTHORIZED',
+        'Error: Unauthorized',
+        '[API] NOT AUTHENTICATED',
+        '[Error] Not Authenticated'
       ];
 
       for (const output of testCases) {
@@ -538,7 +538,7 @@ Please authenticate and try again.`;
     it('should handle JSON error responses', async () => {
       const { detectAuthFailure } = await import('../rate-limit-detector');
 
-      const output = '{"error": "unauthorized", "message": "Please authenticate"}';
+      const output = '{"type":"authentication_error", "error": "unauthorized", "message": "Please authenticate"}';
       const result = detectAuthFailure(output);
 
       expect(result.isAuthFailure).toBe(true);
@@ -609,3 +609,392 @@ Please authenticate and try again.`;
     });
   });
 });
+
+describe('Billing Failure Detection', () => {
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('detectBillingFailure - spec appendix messages', () => {
+    it('should detect "Your credit balance is too low to access the Anthropic API"', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const result = detectBillingFailure('Your credit balance is too low to access the Anthropic API');
+
+      expect(result.isBillingFailure).toBe(true);
+      expect(result.failureType).toBe('insufficient_credits');
+      expect(result.message).toBeDefined();
+    });
+
+    it('should detect "insufficient credits"', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const result = detectBillingFailure('insufficient credits');
+
+      expect(result.isBillingFailure).toBe(true);
+      expect(result.failureType).toBe('insufficient_credits');
+    });
+
+    it('should detect "billing error"', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const result = detectBillingFailure('billing error');
+
+      expect(result.isBillingFailure).toBe(true);
+      expect(result.failureType).toBe('payment_required');
+    });
+
+    it('should detect "extra_usage exceeded"', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const result = detectBillingFailure('extra_usage exceeded');
+
+      expect(result.isBillingFailure).toBe(true);
+      expect(result.failureType).toBe('insufficient_credits');
+    });
+
+    it('should detect standalone "extra_usage"', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const result = detectBillingFailure('extra_usage');
+
+      expect(result.isBillingFailure).toBe(true);
+    });
+
+    it('should detect "payment required"', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const result = detectBillingFailure('payment required');
+
+      expect(result.isBillingFailure).toBe(true);
+      expect(result.failureType).toBe('payment_required');
+    });
+
+    it('should detect "subscription expired"', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const result = detectBillingFailure('subscription expired');
+
+      expect(result.isBillingFailure).toBe(true);
+      expect(result.failureType).toBe('subscription_inactive');
+    });
+
+    it('should detect credit balance variations', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const messages = [
+        'credit balance is insufficient',
+        'credit balance is empty',
+        'credit balance is zero',
+        'credit balance is exhausted',
+        'credit balance is too low',
+      ];
+
+      for (const msg of messages) {
+        const result = detectBillingFailure(msg);
+        expect(result.isBillingFailure).toBe(true);
+      }
+    });
+  });
+
+  describe('detectBillingFailure - negative cases', () => {
+    it('should return false for normal output', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const normalMessages = [
+        'Task completed successfully',
+        'Processing 100 files',
+        'Build succeeded',
+        'Deploying to production',
+        '',
+      ];
+
+      for (const msg of normalMessages) {
+        const result = detectBillingFailure(msg);
+        expect(result.isBillingFailure).toBe(false);
+      }
+    });
+
+    it('should NOT detect rate limit errors as billing failures', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const rateLimitMessages = [
+        'Limit reached · resets Dec 17 at 6am',
+        'rate limit exceeded',
+        'too many requests',
+      ];
+
+      for (const msg of rateLimitMessages) {
+        const result = detectBillingFailure(msg);
+        expect(result.isBillingFailure).toBe(false);
+      }
+    });
+
+    it('should NOT detect auth errors as billing failures', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const authMessages = [
+        'authentication required',
+        'not authenticated',
+        'unauthorized',
+        'invalid token',
+        'session expired',
+      ];
+
+      for (const msg of authMessages) {
+        const result = detectBillingFailure(msg);
+        expect(result.isBillingFailure).toBe(false);
+      }
+    });
+
+    it('should NOT match "line 402" as billing failure (false positive check)', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const falsePositives = [
+        'line 402',
+        'Processing line 402 of 1000',
+        'Found 4020 records',
+        'Error on line 402',
+        'The user has 402 files',
+      ];
+
+      for (const msg of falsePositives) {
+        const result = detectBillingFailure(msg);
+        expect(result.isBillingFailure).toBe(false);
+      }
+    });
+  });
+
+  describe('detectBillingFailure - 402 with proper context', () => {
+    it('should detect "HTTP 402 Payment Required"', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const result = detectBillingFailure('HTTP 402 Payment Required');
+
+      expect(result.isBillingFailure).toBe(true);
+    });
+
+    it('should detect "API Error: 402"', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const result = detectBillingFailure('API Error: 402');
+
+      expect(result.isBillingFailure).toBe(true);
+    });
+
+    it('should detect "status: 402"', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const result = detectBillingFailure('status: 402');
+
+      expect(result.isBillingFailure).toBe(true);
+    });
+
+    it('should detect "error 402"', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const result = detectBillingFailure('error 402');
+
+      expect(result.isBillingFailure).toBe(true);
+    });
+
+    it('should detect "402 payment required" (lowercase)', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const result = detectBillingFailure('402 payment required');
+
+      expect(result.isBillingFailure).toBe(true);
+    });
+  });
+
+  describe('isBillingFailureError', () => {
+    it('should return true for billing failure errors', async () => {
+      const { isBillingFailureError } = await import('../rate-limit-detector');
+
+      expect(isBillingFailureError('credit balance is too low')).toBe(true);
+      expect(isBillingFailureError('insufficient credits')).toBe(true);
+      expect(isBillingFailureError('billing error')).toBe(true);
+      expect(isBillingFailureError('extra_usage exceeded')).toBe(true);
+    });
+
+    it('should return false for non-billing errors', async () => {
+      const { isBillingFailureError } = await import('../rate-limit-detector');
+
+      expect(isBillingFailureError('Task completed')).toBe(false);
+      expect(isBillingFailureError('')).toBe(false);
+      expect(isBillingFailureError('rate limit exceeded')).toBe(false);
+    });
+  });
+
+  describe('classifyBillingFailureType via detectBillingFailure', () => {
+    it('should classify credit-related failures as insufficient_credits', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const creditMessages = [
+        'Your credit balance is too low',
+        'insufficient credits',
+        'out of credits',
+        'extra_usage exceeded',
+      ];
+
+      for (const msg of creditMessages) {
+        const result = detectBillingFailure(msg);
+        expect(result.isBillingFailure).toBe(true);
+        expect(result.failureType).toBe('insufficient_credits');
+      }
+    });
+
+    it('should classify payment failures as payment_required', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const paymentMessages = [
+        'payment required',
+        'billing error',
+        'billing failure',
+      ];
+
+      for (const msg of paymentMessages) {
+        const result = detectBillingFailure(msg);
+        expect(result.isBillingFailure).toBe(true);
+        expect(result.failureType).toBe('payment_required');
+      }
+    });
+
+    it('should classify subscription failures as subscription_inactive', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const subscriptionMessages = [
+        'subscription expired',
+        'subscription inactive',
+        'subscription cancelled',
+        'account suspended',
+      ];
+
+      for (const msg of subscriptionMessages) {
+        const result = detectBillingFailure(msg);
+        expect(result.isBillingFailure).toBe(true);
+        expect(result.failureType).toBe('subscription_inactive');
+      }
+    });
+  });
+
+  describe('detectBillingFailure - result structure', () => {
+    it('should include profile ID in result', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const result = detectBillingFailure('credit balance is too low', 'custom-profile');
+
+      expect(result.isBillingFailure).toBe(true);
+      expect(result.profileId).toBe('custom-profile');
+    });
+
+    it('should use active profile ID when not specified', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const result = detectBillingFailure('credit balance is too low');
+
+      expect(result.isBillingFailure).toBe(true);
+      expect(result.profileId).toBe('test-profile-id');
+    });
+
+    it('should include original error in result', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const output = 'Error: credit balance is too low to access the API';
+      const result = detectBillingFailure(output);
+
+      expect(result.isBillingFailure).toBe(true);
+      expect(result.originalError).toBe(output);
+    });
+
+    it('should include user-friendly message', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const result = detectBillingFailure('credit balance is too low');
+
+      expect(result.isBillingFailure).toBe(true);
+      expect(result.message).toContain('credit');
+      expect(result.message).toContain('Settings');
+    });
+  });
+
+  describe('cross-detection tests', () => {
+    it('should not detect billing errors as auth failures', async () => {
+      const { detectAuthFailure } = await import('../rate-limit-detector');
+
+      const billingMessages = [
+        'credit balance is too low',
+        'insufficient credits',
+        'billing error',
+        'extra_usage exceeded',
+        'payment required',
+      ];
+
+      for (const msg of billingMessages) {
+        const result = detectAuthFailure(msg);
+        expect(result.isAuthFailure).toBe(false);
+      }
+    });
+
+    it('should not detect billing errors as rate limits', async () => {
+      const { detectRateLimit } = await import('../rate-limit-detector');
+
+      const billingMessages = [
+        'credit balance is too low',
+        'insufficient credits',
+        'billing error',
+        'extra_usage exceeded',
+      ];
+
+      for (const msg of billingMessages) {
+        const result = detectRateLimit(msg);
+        expect(result.isRateLimited).toBe(false);
+      }
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle case-insensitive billing messages', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const testCases = [
+        'CREDIT BALANCE IS TOO LOW',
+        'Credit Balance Is Too Low',
+        'BILLING ERROR',
+        'Insufficient Credits',
+        'EXTRA_USAGE EXCEEDED',
+      ];
+
+      for (const output of testCases) {
+        const result = detectBillingFailure(output);
+        expect(result.isBillingFailure).toBe(true);
+      }
+    });
+
+    it('should handle multiline output with billing failure', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const output = `Starting API call...
+Processing request...
+Error: Your credit balance is too low to access the Anthropic API
+Please add credits to continue.`;
+
+      const result = detectBillingFailure(output);
+
+      expect(result.isBillingFailure).toBe(true);
+    });
+
+    it('should handle JSON error responses with billing failure', async () => {
+      const { detectBillingFailure } = await import('../rate-limit-detector');
+
+      const output = '{"type":"billing_error","message":"Insufficient credits"}';
+      const result = detectBillingFailure(output);
+
+      expect(result.isBillingFailure).toBe(true);
+    });
+  });
+});

apps/frontend/src/main/__tests__/task-state-manager.test.ts

@@ -0,0 +1,444 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { TaskStateManager } from '../task-state-manager';
+import type { Task, Project } from '../../shared/types';
+
+// Mock dependencies
+vi.mock('../ipc-handlers/utils', () => ({
+  safeSendToRenderer: vi.fn()
+}));
+
+vi.mock('../ipc-handlers/task/plan-file-utils', () => ({
+  getPlanPath: vi.fn(() => '/mock/path/implementation_plan.json'),
+  persistPlanStatusAndReasonSync: vi.fn()
+}));
+
+vi.mock('../worktree-paths', () => ({
+  findTaskWorktree: vi.fn(() => null)
+}));
+
+vi.mock('fs', () => ({
+  existsSync: vi.fn(() => false)
+}));
+
+// Create mock task and project
+function createMockTask(overrides: Partial<Task> = {}): Task {
+  return {
+    id: 'test-task-id',
+    specId: '001-test-spec',
+    projectId: 'test-project-id',
+    title: 'Test Task',
+    description: 'Test description',
+    status: 'backlog',
+    subtasks: [],
+    logs: [],
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides
+  };
+}
+
+function createMockProject(overrides: Partial<Project> = {}): Project {
+  return {
+    id: 'test-project-id',
+    name: 'Test Project',
+    path: '/mock/project/path',
+    createdAt: new Date().toISOString(),
+    lastOpenedAt: new Date().toISOString(),
+    ...overrides
+  } as Project;
+}
+
+describe('TaskStateManager', () => {
+  let manager: TaskStateManager;
+  let mockTask: Task;
+  let mockProject: Project;
+
+  beforeEach(() => {
+    manager = new TaskStateManager();
+    mockTask = createMockTask();
+    mockProject = createMockProject();
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    manager.clearAllTasks();
+  });
+
+  describe('handleTaskEvent', () => {
+    it('should accept events with increasing sequence numbers', () => {
+      const event1 = {
+        type: 'PLANNING_STARTED',
+        taskId: mockTask.id,
+        specId: mockTask.specId,
+        projectId: mockProject.id,
+        timestamp: new Date().toISOString(),
+        eventId: 'evt-1',
+        sequence: 0
+      };
+
+      const event2 = {
+        type: 'PLANNING_COMPLETE',
+        taskId: mockTask.id,
+        specId: mockTask.specId,
+        projectId: mockProject.id,
+        timestamp: new Date().toISOString(),
+        eventId: 'evt-2',
+        sequence: 1,
+        hasSubtasks: true,
+        subtaskCount: 1,
+        requireReviewBeforeCoding: false
+      };
+
+      const result1 = manager.handleTaskEvent(mockTask.id, event1, mockTask, mockProject);
+      const result2 = manager.handleTaskEvent(mockTask.id, event2, mockTask, mockProject);
+
+      expect(result1).toBe(true);
+      expect(result2).toBe(true);
+    });
+
+    it('should reject events with stale sequence numbers', () => {
+      const event1 = {
+        type: 'PLANNING_STARTED',
+        taskId: mockTask.id,
+        specId: mockTask.specId,
+        projectId: mockProject.id,
+        timestamp: new Date().toISOString(),
+        eventId: 'evt-1',
+        sequence: 5
+      };
+
+      const event2 = {
+        type: 'PLANNING_COMPLETE',
+        taskId: mockTask.id,
+        specId: mockTask.specId,
+        projectId: mockProject.id,
+        timestamp: new Date().toISOString(),
+        eventId: 'evt-2',
+        sequence: 3, // Older than event1
+        hasSubtasks: true,
+        subtaskCount: 1,
+        requireReviewBeforeCoding: false
+      };
+
+      const result1 = manager.handleTaskEvent(mockTask.id, event1, mockTask, mockProject);
+      const result2 = manager.handleTaskEvent(mockTask.id, event2, mockTask, mockProject);
+
+      expect(result1).toBe(true);
+      expect(result2).toBe(false); // Should be rejected
+    });
+
+    it('should accept events with equal sequence numbers (edge case)', () => {
+      // This handles reload scenarios where we might see the same sequence
+      const event1 = {
+        type: 'PLANNING_STARTED',
+        taskId: mockTask.id,
+        specId: mockTask.specId,
+        projectId: mockProject.id,
+        timestamp: new Date().toISOString(),
+        eventId: 'evt-1',
+        sequence: 5
+      };
+
+      const event2 = {
+        type: 'PLANNING_COMPLETE',
+        taskId: mockTask.id,
+        specId: mockTask.specId,
+        projectId: mockProject.id,
+        timestamp: new Date().toISOString(),
+        eventId: 'evt-2',
+        sequence: 5, // Same as event1
+        hasSubtasks: true,
+        subtaskCount: 1,
+        requireReviewBeforeCoding: false
+      };
+
+      const result1 = manager.handleTaskEvent(mockTask.id, event1, mockTask, mockProject);
+      const result2 = manager.handleTaskEvent(mockTask.id, event2, mockTask, mockProject);
+
+      expect(result1).toBe(true);
+      expect(result2).toBe(true); // Should be accepted (>= comparison)
+    });
+  });
+
+  describe('handleUiEvent', () => {
+    it('should send PLAN_APPROVED event correctly', () => {
+      // First, set up the task in plan_review state
+      const planningEvent = {
+        type: 'PLANNING_STARTED',
+        taskId: mockTask.id,
+        specId: mockTask.specId,
+        projectId: mockProject.id,
+        timestamp: new Date().toISOString(),
+        eventId: 'evt-1',
+        sequence: 0
+      };
+
+      const planCompleteEvent = {
+        type: 'PLANNING_COMPLETE',
+        taskId: mockTask.id,
+        specId: mockTask.specId,
+        projectId: mockProject.id,
+        timestamp: new Date().toISOString(),
+        eventId: 'evt-2',
+        sequence: 1,
+        hasSubtasks: true,
+        subtaskCount: 1,
+        requireReviewBeforeCoding: true // This will cause plan_review state
+      };
+
+      manager.handleTaskEvent(mockTask.id, planningEvent, mockTask, mockProject);
+      manager.handleTaskEvent(mockTask.id, planCompleteEvent, mockTask, mockProject);
+
+      // Now send PLAN_APPROVED
+      manager.handleUiEvent(mockTask.id, { type: 'PLAN_APPROVED' }, mockTask, mockProject);
+
+      // The actor should now be in 'coding' state
+      // We can't easily check the state directly, but we can verify no errors occurred
+    });
+
+    it('should send USER_STOPPED event correctly', () => {
+      const event = {
+        type: 'PLANNING_STARTED',
+        taskId: mockTask.id,
+        specId: mockTask.specId,
+        projectId: mockProject.id,
+        timestamp: new Date().toISOString(),
+        eventId: 'evt-1',
+        sequence: 0
+      };
+
+      manager.handleTaskEvent(mockTask.id, event, mockTask, mockProject);
+      manager.handleUiEvent(mockTask.id, { type: 'USER_STOPPED', hasPlan: false }, mockTask, mockProject);
+
+      // Should not throw
+    });
+  });
+
+  describe('handleManualStatusChange', () => {
+    it('should handle done status', () => {
+      const result = manager.handleManualStatusChange(mockTask.id, 'done', mockTask, mockProject);
+      expect(result).toBe(true);
+    });
+
+    it('should handle pr_created status', () => {
+      const taskWithPrUrl = createMockTask({ metadata: { prUrl: 'https://github.com/test/pr/1' } });
+      const result = manager.handleManualStatusChange(mockTask.id, 'pr_created', taskWithPrUrl, mockProject);
+      expect(result).toBe(true);
+    });
+
+    it('should handle in_progress status with plan_review', () => {
+      const taskInPlanReview = createMockTask({
+        status: 'human_review',
+        reviewReason: 'plan_review'
+      });
+      const result = manager.handleManualStatusChange(mockTask.id, 'in_progress', taskInPlanReview, mockProject);
+      expect(result).toBe(true);
+    });
+
+    it('should handle in_progress status without plan_review', () => {
+      const stoppedTask = createMockTask({
+        status: 'human_review',
+        reviewReason: 'stopped'
+      });
+      const result = manager.handleManualStatusChange(mockTask.id, 'in_progress', stoppedTask, mockProject);
+      expect(result).toBe(true);
+    });
+
+    it('should handle backlog status', () => {
+      const result = manager.handleManualStatusChange(mockTask.id, 'backlog', mockTask, mockProject);
+      expect(result).toBe(true);
+    });
+
+    it('should handle human_review status (stage-only merge keeps task in review)', () => {
+      const taskInReview = createMockTask({
+        status: 'human_review',
+        reviewReason: 'completed'
+      });
+      const result = manager.handleManualStatusChange(mockTask.id, 'human_review', taskInReview, mockProject);
+      expect(result).toBe(true);
+    });
+
+    it('should handle human_review with default reviewReason when task has none', () => {
+      const taskNoReason = createMockTask({
+        status: 'human_review'
+        // no reviewReason set
+      });
+      const result = manager.handleManualStatusChange(mockTask.id, 'human_review', taskNoReason, mockProject);
+      expect(result).toBe(true);
+    });
+
+    it('should return false for unhandled status', () => {
+      const result = manager.handleManualStatusChange(mockTask.id, 'ai_review', mockTask, mockProject);
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('sequence management', () => {
+    it('should set and get last sequence', () => {
+      manager.setLastSequence(mockTask.id, 42);
+      expect(manager.getLastSequence(mockTask.id)).toBe(42);
+    });
+
+    it('should return undefined for unknown task', () => {
+      expect(manager.getLastSequence('unknown-task')).toBeUndefined();
+    });
+  });
+
+  describe('clearTask', () => {
+    it('should clear task state', () => {
+      // Set up some state
+      manager.setLastSequence(mockTask.id, 10);
+
+      const event = {
+        type: 'PLANNING_STARTED',
+        taskId: mockTask.id,
+        specId: mockTask.specId,
+        projectId: mockProject.id,
+        timestamp: new Date().toISOString(),
+        eventId: 'evt-1',
+        sequence: 0
+      };
+      manager.handleTaskEvent(mockTask.id, event, mockTask, mockProject);
+
+      // Clear
+      manager.clearTask(mockTask.id);
+
+      // Verify cleared
+      expect(manager.getLastSequence(mockTask.id)).toBeUndefined();
+    });
+  });
+
+  describe('clearAllTasks', () => {
+    it('should clear all task state', () => {
+      // Set up state for multiple tasks
+      manager.setLastSequence('task-1', 10);
+      manager.setLastSequence('task-2', 20);
+
+      const event1 = {
+        type: 'PLANNING_STARTED',
+        taskId: 'task-1',
+        specId: '001',
+        projectId: mockProject.id,
+        timestamp: new Date().toISOString(),
+        eventId: 'evt-1',
+        sequence: 0
+      };
+      const event2 = {
+        type: 'PLANNING_STARTED',
+        taskId: 'task-2',
+        specId: '002',
+        projectId: mockProject.id,
+        timestamp: new Date().toISOString(),
+        eventId: 'evt-2',
+        sequence: 0
+      };
+
+      manager.handleTaskEvent('task-1', event1, createMockTask({ id: 'task-1' }), mockProject);
+      manager.handleTaskEvent('task-2', event2, createMockTask({ id: 'task-2' }), mockProject);
+
+      // Clear all
+      manager.clearAllTasks();
+
+      // Verify actors and state are cleared, but sequence tracking is preserved
+      // (to prevent duplicate event processing during refresh window)
+      expect(manager.getLastSequence('task-1')).toBe(10);
+      expect(manager.getLastSequence('task-2')).toBe(20);
+    });
+  });
+
+  describe('handleProcessExited', () => {
+    it('should NOT mark as error if terminal event was already seen', () => {
+      // First send a terminal event (like QA_PASSED)
+      const qaPassedEvent = {
+        type: 'QA_PASSED',
+        taskId: mockTask.id,
+        specId: mockTask.specId,
+        projectId: mockProject.id,
+        timestamp: new Date().toISOString(),
+        eventId: 'evt-1',
+        sequence: 0,
+        iteration: 1,
+        testsRun: {}
+      };
+
+      manager.handleTaskEvent(mockTask.id, qaPassedEvent, mockTask, mockProject);
+
+      // Now process exits - this should NOT trigger error state
+      manager.handleProcessExited(mockTask.id, 0, mockTask, mockProject);
+
+      // Should not throw and should not transition to error
+      // (We can't easily verify the state, but the important thing is no crash)
+    });
+
+    it('should mark as error on unexpected exit when no terminal event seen', () => {
+      // Start a task
+      const planningEvent = {
+        type: 'PLANNING_STARTED',
+        taskId: mockTask.id,
+        specId: mockTask.specId,
+        projectId: mockProject.id,
+        timestamp: new Date().toISOString(),
+        eventId: 'evt-1',
+        sequence: 0
+      };
+
+      manager.handleTaskEvent(mockTask.id, planningEvent, mockTask, mockProject);
+
+      // Process exits unexpectedly (no terminal event seen)
+      manager.handleProcessExited(mockTask.id, 1, mockTask, mockProject);
+
+      // Should have sent PROCESS_EXITED event with unexpected=true
+      // This should transition to error state
+    });
+  });
+
+  describe('actor state restoration', () => {
+    it('should restore actor state from task with in_progress status', () => {
+      const taskInProgress = createMockTask({
+        status: 'in_progress',
+        executionProgress: { phase: 'coding', phaseProgress: 50, overallProgress: 50 }
+      });
+
+      const event = {
+        type: 'QA_STARTED',
+        taskId: taskInProgress.id,
+        specId: taskInProgress.specId,
+        projectId: mockProject.id,
+        timestamp: new Date().toISOString(),
+        eventId: 'evt-1',
+        sequence: 0,
+        iteration: 1,
+        maxIterations: 3
+      };
+
+      // This should create an actor restored to 'coding' state, then transition to 'qa_review'
+      manager.handleTaskEvent(taskInProgress.id, event, taskInProgress, mockProject);
+
+      // No error should occur
+    });
+
+    it('should restore actor state from task with human_review/plan_review', () => {
+      const taskInPlanReview = createMockTask({
+        status: 'human_review',
+        reviewReason: 'plan_review'
+      });
+
+      // Actor should be created in plan_review state
+      manager.handleUiEvent(taskInPlanReview.id, { type: 'PLAN_APPROVED' }, taskInPlanReview, mockProject);
+
+      // Should transition from plan_review to coding without error
+    });
+
+    it('should restore actor state from task with error status', () => {
+      const taskInError = createMockTask({
+        status: 'error',
+        reviewReason: 'errors'
+      });
+
+      // Actor should be created in error state
+      manager.handleUiEvent(taskInError.id, { type: 'USER_RESUMED' }, taskInError, mockProject);
+
+      // Should transition from error to coding without error
+    });
+  });
+});

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

@@ -43,6 +43,7 @@ export class AgentEvents {
     const lowerLog = log.toLowerCase();
 
     // Spec runner phase detection (all part of "planning")
+    // IMPORTANT: Spec runner should NEVER transition to coding/qa phases via fallback matching
     if (isSpecRunner) {
       if (lowerLog.includes('discovering') || lowerLog.includes('discovery')) {
         return { phase: 'planning', message: 'Discovering project context...' };
@@ -59,6 +60,8 @@ export class AgentEvents {
       if (lowerLog.includes('spec complete') || lowerLog.includes('specification complete')) {
         return { phase: 'planning', message: 'Specification complete' };
       }
+      // Spec runner: don't fall through to run.py patterns (would incorrectly detect coding phase)
+      return null;
     }
 
     // Run.py phase detection

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

@@ -12,6 +12,7 @@ import { AgentState } from './agent-state';
 import { AgentEvents } from './agent-events';
 import { ProcessType, ExecutionProgressData } from './types';
 import type { CompletablePhase } from '../../shared/constants/phase-protocol';
+import { parseTaskEvent } from './task-event-parser';
 import { detectRateLimit, createSDKRateLimitInfo, getBestAvailableProfileEnv, detectAuthFailure } from '../rate-limit-detector';
 import { getAPIProfileEnv } from '../services/profile';
 import { projectStore } from '../project-store';
@@ -29,7 +30,7 @@ import { killProcessGracefully, isWindows } from '../platform';
 /**
  * Type for supported CLI tools
  */
-type CliTool = 'claude' | 'gh';
+type CliTool = 'claude' | 'gh' | 'glab';
 
 /**
  * Mapping of CLI tools to their environment variable names
@@ -37,7 +38,8 @@ type CliTool = 'claude' | 'gh';
  */
 const CLI_TOOL_ENV_MAP: Readonly<Record<CliTool, string>> = {
   claude: 'CLAUDE_CLI_PATH',
-  gh: 'GITHUB_CLI_PATH'
+  gh: 'GITHUB_CLI_PATH',
+  glab: 'GITLAB_CLI_PATH'
 } as const;
 
 
@@ -201,12 +203,14 @@ export class AgentProcessManager {
     // Detect and pass CLI tool paths to Python backend
     const claudeCliEnv = this.detectAndSetCliPath('claude');
     const ghCliEnv = this.detectAndSetCliPath('gh');
+    const glabCliEnv = this.detectAndSetCliPath('glab');
 
     return {
       ...augmentedEnv,
       ...gitBashEnv,
       ...claudeCliEnv,
       ...ghCliEnv,
+      ...glabCliEnv,
       ...extraEnv,
       ...profileEnv,
       PYTHONUNBUFFERED: '1',
@@ -617,6 +621,17 @@ export class AgentProcessManager {
         console.log(`[PhaseDebug:${taskId}] Found marker in line: "${line.substring(0, 200)}"`);
       }
 
+      // Log all task event markers for debugging
+      if (line.includes('__TASK_EVENT__')) {
+        console.log(`[AgentProcess:${taskId}] Found __TASK_EVENT__ marker in line:`, line.substring(0, 300));
+      }
+
+      const taskEvent = parseTaskEvent(line);
+      if (taskEvent) {
+        console.log(`[AgentProcess:${taskId}] Parsed task event:`, taskEvent.type, taskEvent);
+        this.emitter.emit('task-event', taskId, taskEvent);
+      }
+
       const phaseUpdate = this.events.parseExecutionPhase(line, currentPhase, isSpecRunner);
 
       if (isDebug && hasMarker) {

apps/frontend/src/main/agent/task-event-parser.ts

@@ -0,0 +1,120 @@
+/**
+ * Structured task event parser for Python -> TypeScript protocol.
+ * Protocol: __TASK_EVENT__:{...}
+ */
+
+import { validateTaskEvent, type TaskEventPayload } from './task-event-schema';
+
+export const TASK_EVENT_PREFIX = '__TASK_EVENT__:';
+
+const DEBUG = process.env.DEBUG?.toLowerCase() === 'true' || process.env.DEBUG === '1';
+
+export type TaskEvent = TaskEventPayload;
+
+export function parseTaskEvent(line: string): TaskEventPayload | null {
+  const markerIndex = line.indexOf(TASK_EVENT_PREFIX);
+  if (markerIndex === -1) {
+    return null;
+  }
+
+  if (DEBUG) {
+    console.log('[task-event-parser] Found marker at index', markerIndex, 'in line:', line.substring(0, 200));
+  }
+
+  const rawJsonStr = line.slice(markerIndex + TASK_EVENT_PREFIX.length).trim();
+  if (!rawJsonStr) {
+    if (DEBUG) {
+      console.log('[task-event-parser] Empty JSON string after marker');
+    }
+    return null;
+  }
+
+  const jsonStr = extractJsonObject(rawJsonStr);
+  if (!jsonStr) {
+    if (DEBUG) {
+      console.log('[task-event-parser] Could not extract JSON object from:', rawJsonStr.substring(0, 200));
+    }
+    return null;
+  }
+
+  if (DEBUG) {
+    console.log('[task-event-parser] Attempting to parse JSON:', jsonStr.substring(0, 200));
+  }
+
+  try {
+    const rawPayload = JSON.parse(jsonStr) as unknown;
+    const result = validateTaskEvent(rawPayload);
+
+    if (!result.success) {
+      if (DEBUG) {
+        console.log('[task-event-parser] Validation failed:', result.error.format());
+      }
+      return null;
+    }
+
+    if (DEBUG) {
+      console.log('[task-event-parser] Successfully parsed event:', result.data);
+    }
+
+    return result.data;
+  } catch (e) {
+    if (DEBUG) {
+      console.log('[task-event-parser] JSON parse FAILED for:', jsonStr);
+      console.log('[task-event-parser] Error:', e);
+    }
+    return null;
+  }
+}
+
+export function hasTaskMarker(line: string): boolean {
+  return line.includes(TASK_EVENT_PREFIX);
+}
+
+/**
+ * Extract a JSON object from a string that may have trailing garbage.
+ * Finds the matching closing brace for the first opening brace.
+ */
+function extractJsonObject(str: string): string | null {
+  const firstBrace = str.indexOf('{');
+  if (firstBrace === -1) {
+    return null;
+  }
+
+  let depth = 0;
+  let inString = false;
+  let isEscaped = false;
+
+  for (let i = firstBrace; i < str.length; i++) {
+    const char = str[i];
+
+    if (isEscaped) {
+      isEscaped = false;
+      continue;
+    }
+
+    if (char === '\\' && inString) {
+      isEscaped = true;
+      continue;
+    }
+
+    if (char === '"') {
+      inString = !inString;
+      continue;
+    }
+
+    if (inString) {
+      continue;
+    }
+
+    if (char === '{') {
+      depth++;
+    } else if (char === '}') {
+      depth--;
+      if (depth === 0) {
+        return str.slice(firstBrace, i + 1);
+      }
+    }
+  }
+
+  return null;
+}

apps/frontend/src/main/agent/task-event-schema.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+
+export const TaskEventSchema = z.object({
+  type: z.string(),
+  taskId: z.string(),
+  specId: z.string(),
+  projectId: z.string(),
+  timestamp: z.string(),
+  eventId: z.string(),
+  sequence: z.number().int().min(0)
+}).passthrough();
+
+export type TaskEventPayload = z.infer<typeof TaskEventSchema>;
+
+export interface ValidationResult {
+  success: true;
+  data: TaskEventPayload;
+}
+
+export interface ValidationError {
+  success: false;
+  error: z.ZodError;
+}
+
+export type ParseResult = ValidationResult | ValidationError;
+
+export function validateTaskEvent(data: unknown): ParseResult {
+  const result = TaskEventSchema.safeParse(data);
+  if (result.success) {
+    return { success: true, data: result.data as TaskEventPayload };
+  }
+  return { success: false, error: result.error };
+}

apps/frontend/src/main/agent/types.ts

@@ -1,6 +1,7 @@
 import { ChildProcess } from 'child_process';
 import type { IdeationConfig } from '../../shared/types';
 import type { CompletablePhase } from '../../shared/constants/phase-protocol';
+import type { TaskEventPayload } from './task-event-schema';
 
 /**
  * Agent-specific types for process and state management
@@ -34,6 +35,7 @@ export interface AgentManagerEvents {
   error: (taskId: string, error: string) => void;
   exit: (taskId: string, code: number | null, processType: ProcessType) => void;
   'execution-progress': (taskId: string, progress: ExecutionProgressData) => void;
+  'task-event': (taskId: string, event: TaskEventPayload) => void;
 }
 
 // IdeationConfig now imported from shared types to maintain consistency

apps/frontend/src/main/app-language.ts

@@ -0,0 +1,45 @@
+/**
+ * App language tracking module for main process.
+ *
+ * Tracks the user's in-app language setting (not OS locale) for use in
+ * main process code that needs localized strings (e.g., context menus).
+ *
+ * Updated via IPC when user changes language in settings.
+ */
+
+import { app } from 'electron';
+
+// Current app language, defaults to 'en'
+// Updated via setAppLanguage() when renderer notifies of language change
+let currentAppLanguage = 'en';
+
+/**
+ * Get the current app language.
+ * Falls back to 'en' if not set.
+ */
+export function getAppLanguage(): string {
+  return currentAppLanguage;
+}
+
+/**
+ * Set the current app language.
+ * Called by IPC handler when renderer changes language.
+ */
+export function setAppLanguage(language: string): void {
+  currentAppLanguage = language;
+}
+
+/**
+ * Initialize app language from OS locale as a starting point.
+ * The renderer will update this once i18n initializes.
+ */
+export function initAppLanguage(): void {
+  try {
+    // app.getLocale() may not be available in test environments
+    const osLocale = app?.getLocale?.() || 'en';
+    // Extract base language (e.g., 'en-US' -> 'en')
+    currentAppLanguage = osLocale.split('-')[0] || 'en';
+  } catch {
+    currentAppLanguage = 'en';
+  }
+}

apps/frontend/src/main/changelog/changelog-service.ts

@@ -8,7 +8,7 @@ import { app } from 'electron';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 import { AUTO_BUILD_PATHS, DEFAULT_CHANGELOG_PATH } from '../../shared/constants';
-import { getToolPath } from '../cli-tool-manager';
+import { getToolPath, getToolInfo } from '../cli-tool-manager';
 import type {
   ChangelogTask,
   TaskSpecContent,
@@ -175,26 +175,40 @@ export class ChangelogService extends EventEmitter {
     }
   }
 
+  /**
+   * Ensure prerequisites are met for changelog generation
+   * Validates auto-build source path and Claude CLI availability
+   * Returns the resolved Claude CLI path to ensure we use the freshly validated path
+   */
+  private ensurePrerequisites(): { autoBuildSource: string; claudePath: string } {
+    const autoBuildSource = this.getAutoBuildSourcePath();
+    if (!autoBuildSource) {
+      throw new Error('Auto-build source path not found');
+    }
+
+    const claudeInfo = getToolInfo('claude');
+    if (!claudeInfo.found || !claudeInfo.path) {
+      // Use claudeInfo.message directly to avoid redundant text
+      throw new Error(claudeInfo.message || 'Claude CLI not found. Install from https://claude.ai/download');
+    }
+
+    // Update cached path with freshly resolved value
+    this.claudePath = claudeInfo.path;
+    return { autoBuildSource, claudePath: claudeInfo.path };
+  }
+
   /**
    * Get or create the generator instance
    */
   private getGenerator(): ChangelogGenerator {
     if (!this.generator) {
-      const autoBuildSource = this.getAutoBuildSourcePath();
-      if (!autoBuildSource) {
-        throw new Error('Auto-build source path not found');
-      }
-
-      // Verify claude CLI is available
-      if (this.claudePath !== 'claude' && !existsSync(this.claudePath)) {
-        throw new Error(`Claude CLI not found. Please ensure Claude Code is installed. Looked for: ${this.claudePath}`);
-      }
+      const { autoBuildSource, claudePath } = this.ensurePrerequisites();
 
       const autoBuildEnv = this.loadAutoBuildEnv();
 
       this.generator = new ChangelogGenerator(
         this.pythonPath,
-        this.claudePath,
+        claudePath,
         autoBuildSource,
         autoBuildEnv,
         this.isDebugEnabled()
@@ -226,19 +240,11 @@ export class ChangelogService extends EventEmitter {
    */
   private getVersionSuggester(): VersionSuggester {
     if (!this.versionSuggester) {
-      const autoBuildSource = this.getAutoBuildSourcePath();
-      if (!autoBuildSource) {
-        throw new Error('Auto-build source path not found');
-      }
-
-      // Verify claude CLI is available
-      if (this.claudePath !== 'claude' && !existsSync(this.claudePath)) {
-        throw new Error(`Claude CLI not found. Please ensure Claude Code is installed. Looked for: ${this.claudePath}`);
-      }
+      const { autoBuildSource, claudePath } = this.ensurePrerequisites();
 
       this.versionSuggester = new VersionSuggester(
         this.pythonPath,
-        this.claudePath,
+        claudePath,
         autoBuildSource,
         this.isDebugEnabled()
       );

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

@@ -43,7 +43,7 @@ import {
   shouldProactivelySwitch as shouldProactivelySwitchImpl,
   getProfilesSortedByAvailability as getProfilesSortedByAvailabilityImpl
 } from './claude-profile/profile-scorer';
-import { getCredentialsFromKeychain } from './claude-profile/credential-utils';
+import { getCredentialsFromKeychain, normalizeWindowsPath } from './claude-profile/credential-utils';
 import {
   CLAUDE_PROFILES_DIR,
   generateProfileId as generateProfileIdImpl,
@@ -498,9 +498,12 @@ export class ClaudeProfileManager {
     // This prevents interference with external Claude Code CLI usage
     if (profile?.configDir) {
       // Expand ~ to home directory for the environment variable
-      const expandedConfigDir = profile.configDir.startsWith('~')
-        ? profile.configDir.replace(/^~/, homedir())
-        : profile.configDir;
+      const expandedConfigDir = normalizeWindowsPath(
+        profile.configDir.startsWith('~')
+          ? profile.configDir.replace(/^~/, homedir())
+          : profile.configDir
+      );
+
       env.CLAUDE_CONFIG_DIR = expandedConfigDir;
       if (process.env.DEBUG === 'true') {
         console.warn('[ClaudeProfileManager] Using CLAUDE_CONFIG_DIR for profile:', profile.name, expandedConfigDir);
@@ -719,9 +722,11 @@ export class ClaudeProfileManager {
     }
 
     // Expand ~ to home directory for the environment variable
-    const expandedConfigDir = profile.configDir.startsWith('~')
-      ? profile.configDir.replace(/^~/, require('os').homedir())
-      : profile.configDir;
+    const expandedConfigDir = normalizeWindowsPath(
+      profile.configDir.startsWith('~')
+        ? profile.configDir.replace(/^~/, require('os').homedir())
+        : profile.configDir
+    );
 
     if (process.env.DEBUG === 'true') {
       console.warn('[ClaudeProfileManager] getProfileEnv:', {

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

@@ -34,6 +34,7 @@ import {
   getKeychainServiceName,
   getWindowsCredentialTarget,
   getCredentialsFromKeychain,
+  getFullCredentialsFromKeychain,
   getCredentials,
   clearKeychainCache,
   clearCredentialCache,
@@ -358,19 +359,24 @@ describe('credential-utils', () => {
       vi.mocked(homedir).mockReturnValue('C:\\Users\\TestUser');
     });
 
-    it('should return null when PowerShell not found', () => {
+    it('should return null when PowerShell not found and no credentials file exists', () => {
+      // Neither PowerShell nor credentials file exists
       vi.mocked(existsSync).mockReturnValue(false);
 
       const result = getCredentialsFromKeychain();
 
       expect(result.token).toBeNull();
       expect(result.email).toBeNull();
-      expect(result.error).toBe('PowerShell not found');
+      // No error because file fallback returns null gracefully when file doesn't exist
     });
 
-    it('should return credentials from Windows Credential Manager', () => {
-      // Mock PowerShell path found
-      vi.mocked(existsSync).mockReturnValue(true);
+    it('should return credentials from Windows Credential Manager when file is empty', () => {
+      // Mock PowerShell path found, but credentials file doesn't exist
+      vi.mocked(existsSync).mockImplementation((path: unknown) => {
+        const pathStr = String(path);
+        // PowerShell exists, but credentials file doesn't
+        return pathStr.includes('PowerShell') || pathStr.includes('powershell');
+      });
       vi.mocked(execFileSync).mockReturnValue(JSON.stringify({
         claudeAiOauth: {
           accessToken: 'sk-ant-windows-token-789',
@@ -384,9 +390,33 @@ describe('credential-utils', () => {
       expect(result.email).toBe('windows@example.com');
     });
 
-    it('should return null when credential not found', () => {
+    it('should fall back to file when Credential Manager returns empty', () => {
+      // Mock PowerShell exists but returns empty (no credential in Credential Manager)
+      // Mock file exists with valid credentials
       vi.mocked(existsSync).mockReturnValue(true);
-      vi.mocked(execFileSync).mockReturnValue('');
+      vi.mocked(execFileSync).mockReturnValue(''); // Credential Manager empty
+      vi.mocked(readFileSync).mockReturnValue(JSON.stringify({
+        claudeAiOauth: {
+          accessToken: 'sk-ant-file-fallback-token',
+          email: 'file@example.com',
+        },
+      }));
+
+      const result = getCredentialsFromKeychain();
+
+      expect(result.token).toBe('sk-ant-file-fallback-token');
+      expect(result.email).toBe('file@example.com');
+    });
+
+    it('should return null when both Credential Manager and file have no credentials', () => {
+      // Mock PowerShell exists but returns empty
+      // Mock credentials file doesn't exist
+      vi.mocked(existsSync).mockImplementation((path: unknown) => {
+        const pathStr = String(path);
+        // PowerShell exists, but credentials file doesn't
+        return pathStr.includes('PowerShell') || pathStr.includes('powershell');
+      });
+      vi.mocked(execFileSync).mockReturnValue(''); // Credential Manager empty
 
       const result = getCredentialsFromKeychain();
 
@@ -394,14 +424,137 @@ describe('credential-utils', () => {
       expect(result.email).toBeNull();
     });
 
-    it('should handle invalid JSON from Credential Manager', () => {
+    it('should handle invalid JSON from Credential Manager by falling back to file', () => {
       vi.mocked(existsSync).mockReturnValue(true);
-      vi.mocked(execFileSync).mockReturnValue('invalid json');
+      vi.mocked(execFileSync).mockReturnValue('invalid json'); // Invalid JSON from Credential Manager
+      vi.mocked(readFileSync).mockReturnValue(JSON.stringify({
+        claudeAiOauth: {
+          accessToken: 'sk-ant-file-token-after-cm-failure',
+          email: 'fallback@example.com',
+        },
+      }));
 
       const result = getCredentialsFromKeychain();
 
+      // Should fall back to file and get valid credentials
+      expect(result.token).toBe('sk-ant-file-token-after-cm-failure');
+      expect(result.email).toBe('fallback@example.com');
+    });
+
+    it('should prefer file credentials when both sources have tokens', () => {
+      vi.mocked(existsSync).mockReturnValue(true);
+      vi.mocked(readFileSync).mockReturnValue(JSON.stringify({
+        claudeAiOauth: {
+          accessToken: 'sk-ant-windows-file-token',
+          email: 'windowsfile@example.com',
+        },
+      }));
+      vi.mocked(execFileSync).mockReturnValue(JSON.stringify({
+        claudeAiOauth: {
+          accessToken: 'sk-ant-credman-token',
+          email: 'credman@example.com',
+        },
+      }));
+
+      const result = getCredentialsFromKeychain();
+
+      // Should prefer file since Claude CLI writes there after login
+      expect(result.token).toBe('sk-ant-windows-file-token');
+      expect(result.email).toBe('windowsfile@example.com');
+    });
+  });
+
+  describe('getFullCredentialsFromKeychain (Windows)', () => {
+    beforeEach(() => {
+      vi.mocked(isMacOS).mockReturnValue(false);
+      vi.mocked(isWindows).mockReturnValue(true);
+      vi.mocked(isLinux).mockReturnValue(false);
+      vi.mocked(homedir).mockReturnValue('C:\\Users\\TestUser');
+      clearCredentialCache();
+    });
+
+    it('should return full credentials from file when available', () => {
+      vi.mocked(existsSync).mockReturnValue(true);
+      vi.mocked(readFileSync).mockReturnValue(JSON.stringify({
+        claudeAiOauth: {
+          accessToken: 'sk-ant-full-creds-token',
+          refreshToken: 'refresh-token-123',
+          expiresAt: 1700000000000,
+          email: 'full@example.com',
+          scopes: ['user:read', 'user:write'],
+        },
+      }));
+      vi.mocked(execFileSync).mockReturnValue(''); // Credential Manager empty
+
+      const result = getFullCredentialsFromKeychain();
+
+      expect(result.token).toBe('sk-ant-full-creds-token');
+      expect(result.refreshToken).toBe('refresh-token-123');
+      expect(result.expiresAt).toBe(1700000000000);
+      expect(result.email).toBe('full@example.com');
+      expect(result.scopes).toEqual(['user:read', 'user:write']);
+    });
+
+    it('should return credentials from Credential Manager when file is empty', () => {
+      vi.mocked(existsSync).mockImplementation((path: unknown) => {
+        const pathStr = String(path);
+        return pathStr.includes('PowerShell') || pathStr.includes('powershell');
+      });
+      vi.mocked(execFileSync).mockReturnValue(JSON.stringify({
+        claudeAiOauth: {
+          accessToken: 'sk-ant-credman-full-token',
+          refreshToken: 'credman-refresh',
+          expiresAt: 1700000000000,
+          email: 'credman@example.com',
+        },
+      }));
+
+      const result = getFullCredentialsFromKeychain();
+
+      expect(result.token).toBe('sk-ant-credman-full-token');
+      expect(result.refreshToken).toBe('credman-refresh');
+      expect(result.email).toBe('credman@example.com');
+    });
+
+    it('should prefer file credentials when both sources have tokens (consistent with basic API)', () => {
+      vi.mocked(existsSync).mockReturnValue(true);
+      vi.mocked(readFileSync).mockReturnValue(JSON.stringify({
+        claudeAiOauth: {
+          accessToken: 'sk-ant-file-full-token',
+          refreshToken: 'file-refresh',
+          expiresAt: 1700000000000,
+          email: 'file@example.com',
+        },
+      }));
+      vi.mocked(execFileSync).mockReturnValue(JSON.stringify({
+        claudeAiOauth: {
+          accessToken: 'sk-ant-credman-full-token',
+          refreshToken: 'credman-refresh',
+          expiresAt: 1800000000000, // Later expiry
+          email: 'credman@example.com',
+        },
+      }));
+
+      const result = getFullCredentialsFromKeychain();
+
+      // Should prefer file since Claude CLI writes there after login
+      // This is consistent with getCredentialsFromKeychain behavior
+      expect(result.token).toBe('sk-ant-file-full-token');
+      expect(result.refreshToken).toBe('file-refresh');
+      expect(result.email).toBe('file@example.com');
+    });
+
+    it('should return null when both sources have no credentials', () => {
+      vi.mocked(existsSync).mockImplementation((path: unknown) => {
+        const pathStr = String(path);
+        return pathStr.includes('PowerShell') || pathStr.includes('powershell');
+      });
+      vi.mocked(execFileSync).mockReturnValue('');
+
+      const result = getFullCredentialsFromKeychain();
+
       expect(result.token).toBeNull();
-      expect(result.email).toBeNull();
+      expect(result.refreshToken).toBeNull();
     });
   });
 

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

@@ -17,9 +17,9 @@
 
 import { execFileSync } from 'child_process';
 import { createHash } from 'crypto';
-import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'fs';
 import { homedir, userInfo } from 'os';
-import { join } from 'path';
+import { dirname, join } from 'path';
 import { isMacOS, isWindows, isLinux } from '../platform';
 
 /**
@@ -157,6 +157,28 @@ export function calculateConfigDirHash(configDir: string): string {
   return createHash('sha256').update(configDir).digest('hex').slice(0, 8);
 }
 
+/**
+ * Normalize Windows path separators for hash consistency with Claude CLI.
+ *
+ * Claude CLI on Windows uses backslashes, so we must too for hash consistency.
+ * Mixed slashes (C:\Users\bill/.claude-profiles) produce different hashes than
+ * consistent slashes (C:\Users\bill\.claude-profiles).
+ *
+ * Supports:
+ * - Drive letter paths: C:\Users\...
+ * - UNC paths with backslashes: \\server\share
+ * - UNC paths with forward slashes: //server/share (normalized to \\server\share)
+ *
+ * @param path - The path to normalize
+ * @returns The path with forward slashes replaced by backslashes on Windows
+ */
+export function normalizeWindowsPath(path: string): string {
+  if (!isWindows()) return path;
+  // Match: drive letter (C:), UNC with backslashes (\\), or UNC with forward slashes (//)
+  if (!/^[A-Za-z]:|^[\\/]{2}/.test(path)) return path;
+  return path.replace(/\//g, '\\');
+}
+
 /**
  * Get the Keychain service name for a config directory (macOS).
  *
@@ -176,9 +198,11 @@ export function getKeychainServiceName(configDir?: string): string {
   }
 
   // Normalize the configDir: expand ~ and resolve to absolute path
-  const normalizedConfigDir = configDir.startsWith('~')
-    ? join(homedir(), configDir.slice(1))
-    : configDir;
+  const normalizedConfigDir = normalizeWindowsPath(
+    configDir.startsWith('~')
+      ? join(homedir(), configDir.slice(1))
+      : configDir
+  );
 
   // ALL profiles now use hash-based keychain entries for isolation
   // This prevents interference with external Claude Code CLI
@@ -385,6 +409,195 @@ function parseCredentialJson<T extends PlatformCredentials>(
   return extractFn(data);
 }
 
+// =============================================================================
+// File-Based Credential Helpers (Shared for Linux and Windows)
+// =============================================================================
+
+/**
+ * Shared implementation for reading credentials from a JSON file.
+ * Used by both Linux and Windows file-based credential storage.
+ *
+ * @param credentialsPath - Path to the credentials file
+ * @param cacheKey - Cache key for storing results
+ * @param logPrefix - Prefix for log messages (e.g., "Linux", "Windows:File")
+ * @param forceRefresh - Whether to bypass cache
+ * @returns Platform credentials with token and email
+ */
+function getCredentialsFromFile(
+  credentialsPath: string,
+  cacheKey: string,
+  logPrefix: string,
+  forceRefresh = false
+): PlatformCredentials {
+  const isDebug = process.env.DEBUG === 'true';
+  const now = Date.now();
+
+  // Return cached credentials if available and fresh
+  const cached = credentialCache.get(cacheKey);
+  if (!forceRefresh && cached) {
+    const ttl = cached.credentials.error ? ERROR_CACHE_TTL_MS : CACHE_TTL_MS;
+    if ((now - cached.timestamp) < ttl) {
+      if (isDebug) {
+        const cacheAge = now - cached.timestamp;
+        console.warn(`[CredentialUtils:${logPrefix}:CACHE] Returning cached credentials:`, {
+          credentialsPath,
+          hasToken: !!cached.credentials.token,
+          tokenFingerprint: getTokenFingerprint(cached.credentials.token),
+          cacheAge: Math.round(cacheAge / 1000) + 's'
+        });
+      }
+      return cached.credentials;
+    }
+  }
+
+  // Defense-in-depth: Validate credentials path is within expected boundaries
+  if (!isValidCredentialsPath(credentialsPath)) {
+    if (isDebug) {
+      console.warn(`[CredentialUtils:${logPrefix}] Invalid credentials path rejected:`, { credentialsPath });
+    }
+    const invalidResult = { token: null, email: null, error: 'Invalid credentials path' };
+    credentialCache.set(cacheKey, { credentials: invalidResult, timestamp: now });
+    return invalidResult;
+  }
+
+  // Check if credentials file exists
+  if (!existsSync(credentialsPath)) {
+    if (isDebug) {
+      console.warn(`[CredentialUtils:${logPrefix}] Credentials file not found:`, credentialsPath);
+    }
+    const notFoundResult = { token: null, email: null };
+    credentialCache.set(cacheKey, { credentials: notFoundResult, timestamp: now });
+    return notFoundResult;
+  }
+
+  try {
+    const content = readFileSync(credentialsPath, 'utf-8');
+
+    // Parse JSON
+    let data: unknown;
+    try {
+      data = JSON.parse(content);
+    } catch {
+      console.warn(`[CredentialUtils:${logPrefix}] Failed to parse credentials JSON:`, credentialsPath);
+      const errorResult = { token: null, email: null };
+      credentialCache.set(cacheKey, { credentials: errorResult, timestamp: now });
+      return errorResult;
+    }
+
+    // Validate JSON structure
+    if (!validateCredentialData(data)) {
+      console.warn(`[CredentialUtils:${logPrefix}] Invalid credentials data structure:`, credentialsPath);
+      const invalidResult = { token: null, email: null };
+      credentialCache.set(cacheKey, { credentials: invalidResult, timestamp: now });
+      return invalidResult;
+    }
+
+    const { token, email } = extractCredentials(data);
+
+    // Validate token format if present
+    if (token && !isValidTokenFormat(token)) {
+      console.warn(`[CredentialUtils:${logPrefix}] Invalid token format in:`, credentialsPath);
+      const result = { token: null, email };
+      credentialCache.set(cacheKey, { credentials: result, timestamp: now });
+      return result;
+    }
+
+    const credentials = { token, email };
+    credentialCache.set(cacheKey, { credentials, timestamp: now });
+
+    if (isDebug) {
+      console.warn(`[CredentialUtils:${logPrefix}] Retrieved credentials from file:`, credentialsPath, {
+        hasToken: !!token,
+        hasEmail: !!email,
+        tokenFingerprint: getTokenFingerprint(token),
+        forceRefresh
+      });
+    }
+    return credentials;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    console.warn(`[CredentialUtils:${logPrefix}] Failed to read credentials file:`, credentialsPath, errorMessage);
+    const errorResult = { token: null, email: null, error: `Failed to read credentials: ${errorMessage}` };
+    credentialCache.set(cacheKey, { credentials: errorResult, timestamp: now });
+    return errorResult;
+  }
+}
+
+/**
+ * Shared implementation for reading full credentials from a JSON file.
+ * Used by both Linux and Windows file-based credential storage.
+ *
+ * @param credentialsPath - Path to the credentials file
+ * @param logPrefix - Prefix for log messages (e.g., "Linux:Full", "Windows:File:Full")
+ * @returns Full OAuth credentials including refresh token
+ */
+function getFullCredentialsFromFile(
+  credentialsPath: string,
+  logPrefix: string
+): FullOAuthCredentials {
+  const isDebug = process.env.DEBUG === 'true';
+
+  // Defense-in-depth: Validate credentials path is within expected boundaries
+  if (!isValidCredentialsPath(credentialsPath)) {
+    if (isDebug) {
+      console.warn(`[CredentialUtils:${logPrefix}] Invalid credentials path rejected:`, { credentialsPath });
+    }
+    return { token: null, email: null, refreshToken: null, expiresAt: null, scopes: null, subscriptionType: null, rateLimitTier: null, error: 'Invalid credentials path' };
+  }
+
+  // Check if credentials file exists
+  if (!existsSync(credentialsPath)) {
+    if (isDebug) {
+      console.warn(`[CredentialUtils:${logPrefix}] Credentials file not found:`, credentialsPath);
+    }
+    return { token: null, email: null, refreshToken: null, expiresAt: null, scopes: null, subscriptionType: null, rateLimitTier: null };
+  }
+
+  try {
+    const content = readFileSync(credentialsPath, 'utf-8');
+
+    // Parse JSON
+    let data: unknown;
+    try {
+      data = JSON.parse(content);
+    } catch {
+      console.warn(`[CredentialUtils:${logPrefix}] Failed to parse credentials JSON:`, credentialsPath);
+      return { token: null, email: null, refreshToken: null, expiresAt: null, scopes: null, subscriptionType: null, rateLimitTier: null };
+    }
+
+    // Validate JSON structure
+    if (!validateCredentialData(data)) {
+      console.warn(`[CredentialUtils:${logPrefix}] Invalid credentials data structure:`, credentialsPath);
+      return { token: null, email: null, refreshToken: null, expiresAt: null, scopes: null, subscriptionType: null, rateLimitTier: null };
+    }
+
+    const { token, email, refreshToken, expiresAt, scopes, subscriptionType, rateLimitTier } = extractFullCredentials(data);
+
+    // Validate token format if present
+    if (token && !isValidTokenFormat(token)) {
+      console.warn(`[CredentialUtils:${logPrefix}] Invalid token format in:`, credentialsPath);
+      return { token: null, email, refreshToken, expiresAt, scopes, subscriptionType, rateLimitTier };
+    }
+
+    if (isDebug) {
+      console.warn(`[CredentialUtils:${logPrefix}] Retrieved full credentials from file:`, credentialsPath, {
+        hasToken: !!token,
+        hasEmail: !!email,
+        hasRefreshToken: !!refreshToken,
+        expiresAt: expiresAt ? new Date(expiresAt).toISOString() : null,
+        tokenFingerprint: getTokenFingerprint(token),
+        subscriptionType,
+        rateLimitTier
+      });
+    }
+    return { token, email, refreshToken, expiresAt, scopes, subscriptionType, rateLimitTier };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    console.warn(`[CredentialUtils:${logPrefix}] Failed to read credentials file:`, credentialsPath, errorMessage);
+    return { token: null, email: null, refreshToken: null, expiresAt: null, scopes: null, subscriptionType: null, rateLimitTier: null, error: `Failed to read credentials: ${errorMessage}` };
+  }
+}
+
 // =============================================================================
 // macOS Keychain Implementation
 // =============================================================================
@@ -653,98 +866,7 @@ function getLinuxCredentialsPath(configDir?: string): string {
 function getCredentialsFromLinuxFile(configDir?: string, forceRefresh = false): PlatformCredentials {
   const credentialsPath = getLinuxCredentialsPath(configDir);
   const cacheKey = `linux:${credentialsPath}`;
-  const isDebug = process.env.DEBUG === 'true';
-  const now = Date.now();
-
-  // Return cached credentials if available and fresh
-  const cached = credentialCache.get(cacheKey);
-  if (!forceRefresh && cached) {
-    const ttl = cached.credentials.error ? ERROR_CACHE_TTL_MS : CACHE_TTL_MS;
-    if ((now - cached.timestamp) < ttl) {
-      if (isDebug) {
-        const cacheAge = now - cached.timestamp;
-        console.warn('[CredentialUtils:Linux:CACHE] Returning cached credentials:', {
-          credentialsPath,
-          hasToken: !!cached.credentials.token,
-          tokenFingerprint: getTokenFingerprint(cached.credentials.token),
-          cacheAge: Math.round(cacheAge / 1000) + 's'
-        });
-      }
-      return cached.credentials;
-    }
-  }
-
-  // Defense-in-depth: Validate credentials path is within expected boundaries
-  if (!isValidCredentialsPath(credentialsPath)) {
-    if (isDebug) {
-      console.warn('[CredentialUtils:Linux] Invalid credentials path rejected:', { credentialsPath });
-    }
-    const invalidResult = { token: null, email: null, error: 'Invalid credentials path' };
-    credentialCache.set(cacheKey, { credentials: invalidResult, timestamp: now });
-    return invalidResult;
-  }
-
-  // Check if credentials file exists
-  if (!existsSync(credentialsPath)) {
-    if (isDebug) {
-      console.warn('[CredentialUtils:Linux] Credentials file not found:', credentialsPath);
-    }
-    const notFoundResult = { token: null, email: null };
-    credentialCache.set(cacheKey, { credentials: notFoundResult, timestamp: now });
-    return notFoundResult;
-  }
-
-  try {
-    const content = readFileSync(credentialsPath, 'utf-8');
-
-    // Parse JSON
-    let data: unknown;
-    try {
-      data = JSON.parse(content);
-    } catch {
-      console.warn('[CredentialUtils:Linux] Failed to parse credentials JSON:', credentialsPath);
-      const errorResult = { token: null, email: null };
-      credentialCache.set(cacheKey, { credentials: errorResult, timestamp: now });
-      return errorResult;
-    }
-
-    // Validate JSON structure
-    if (!validateCredentialData(data)) {
-      console.warn('[CredentialUtils:Linux] Invalid credentials data structure:', credentialsPath);
-      const invalidResult = { token: null, email: null };
-      credentialCache.set(cacheKey, { credentials: invalidResult, timestamp: now });
-      return invalidResult;
-    }
-
-    const { token, email } = extractCredentials(data);
-
-    // Validate token format if present
-    if (token && !isValidTokenFormat(token)) {
-      console.warn('[CredentialUtils:Linux] Invalid token format in:', credentialsPath);
-      const result = { token: null, email };
-      credentialCache.set(cacheKey, { credentials: result, timestamp: now });
-      return result;
-    }
-
-    const credentials = { token, email };
-    credentialCache.set(cacheKey, { credentials, timestamp: now });
-
-    if (isDebug) {
-      console.warn('[CredentialUtils:Linux] Retrieved credentials from file:', credentialsPath, {
-        hasToken: !!token,
-        hasEmail: !!email,
-        tokenFingerprint: getTokenFingerprint(token),
-        forceRefresh
-      });
-    }
-    return credentials;
-  } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    console.warn('[CredentialUtils:Linux] Failed to read credentials file:', credentialsPath, errorMessage);
-    const errorResult = { token: null, email: null, error: `Failed to read credentials: ${errorMessage}` };
-    credentialCache.set(cacheKey, { credentials: errorResult, timestamp: now });
-    return errorResult;
-  }
+  return getCredentialsFromFile(credentialsPath, cacheKey, 'Linux', forceRefresh);
 }
 
 // =============================================================================
@@ -804,29 +926,60 @@ function getCredentialsFromWindowsCredentialManager(configDir?: string, forceRef
   try {
     // PowerShell script to read from Credential Manager
     // Uses the Windows Credential Manager API via .NET
+    // NOTE: The CREDENTIAL struct must use IntPtr for string fields (blittable requirement)
+    // and strings must be manually marshaled after PtrToStructure
+    //
+    // NOTE: This CREDENTIAL struct uses IntPtr for string fields (TargetName, Comment, etc.)
+    // because CredRead returns a pointer to Windows-allocated memory. We must use a "blittable"
+    // struct layout where strings are IntPtr, then manually marshal strings via PtrToStringUni.
+    // This differs from the CredWrite struct (see updateWindowsCredentialManagerCredentials)
+    // which uses string types because the .NET marshaler can automatically convert strings
+    // to pointers when CALLING Windows APIs (but not when RECEIVING data from them).
     const psScript = `
       $ErrorActionPreference = 'Stop'
-      Add-Type -AssemblyName System.Runtime.WindowsRuntime
 
-      # Use CredRead from advapi32.dll to read generic credentials
-      $sig = @'
-      [DllImport("advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
-      public static extern bool CredRead(string target, int type, int reservedFlag, out IntPtr credentialPtr);
+      # Define the CREDENTIAL struct with IntPtr for string fields (required for CredRead marshaling)
+      # See comment above for why this differs from the CredWrite struct definition.
+      Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
 
-      [DllImport("advapi32.dll", SetLastError = true)]
-      public static extern bool CredFree(IntPtr cred);
+[StructLayout(LayoutKind.Sequential)]
+public struct CREDENTIAL {
+    public uint Flags;
+    public uint Type;
+    public IntPtr TargetName;
+    public IntPtr Comment;
+    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+    public uint CredentialBlobSize;
+    public IntPtr CredentialBlob;
+    public uint Persist;
+    public uint AttributeCount;
+    public IntPtr Attributes;
+    public IntPtr TargetAlias;
+    public IntPtr UserName;
+}
 '@
-      Add-Type -MemberDefinition $sig -Namespace Win32 -Name Credential
+
+      # Import CredRead and CredFree from advapi32.dll
+      Add-Type -MemberDefinition @'
+[DllImport("advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
+public static extern bool CredRead(string target, uint type, uint reservedFlag, out IntPtr credentialPtr);
+
+[DllImport("advapi32.dll", SetLastError = true)]
+public static extern bool CredFree(IntPtr cred);
+'@ -Namespace Win32 -Name CredApi
 
       $credPtr = [IntPtr]::Zero
       # CRED_TYPE_GENERIC = 1
-      $success = [Win32.Credential]::CredRead("${escapePowerShellString(targetName)}", 1, 0, [ref]$credPtr)
+      $success = [Win32.CredApi]::CredRead("${escapePowerShellString(targetName)}", 1, 0, [ref]$credPtr)
 
       if ($success) {
         try {
-          $cred = [Runtime.InteropServices.Marshal]::PtrToStructure($credPtr, [Type][System.Management.Automation.PSCredential].Assembly.GetType('Microsoft.PowerShell.Commands.CREDENTIAL'))
+          # Marshal the pointer to our CREDENTIAL struct
+          $cred = [Runtime.InteropServices.Marshal]::PtrToStructure($credPtr, [Type][CREDENTIAL])
 
-          # Read the credential blob (password field)
+          # Read the credential blob (password field) - contains the JSON
           $blobSize = $cred.CredentialBlobSize
           if ($blobSize -gt 0) {
             $blob = [byte[]]::new($blobSize)
@@ -835,7 +988,7 @@ function getCredentialsFromWindowsCredentialManager(configDir?: string, forceRef
             Write-Output $password
           }
         } finally {
-          [Win32.Credential]::CredFree($credPtr) | Out-Null
+          [Win32.CredApi]::CredFree($credPtr) | Out-Null
         }
       } else {
         # Credential not found - this is expected if user hasn't authenticated
@@ -911,6 +1064,67 @@ function findPowerShellPath(): string | null {
   return null;
 }
 
+// =============================================================================
+// Windows Credentials File Implementation (Fallback)
+// =============================================================================
+
+/**
+ * Get the credentials file path for Windows
+ * Claude CLI on Windows stores credentials in .credentials.json files, not Windows Credential Manager
+ */
+function getWindowsCredentialsPath(configDir?: string): string {
+  const baseDir = configDir || join(homedir(), '.claude');
+  return join(baseDir, '.credentials.json');
+}
+
+/**
+ * Retrieve credentials from Windows .credentials.json file
+ * This is the primary storage mechanism used by Claude CLI on Windows
+ */
+function getCredentialsFromWindowsFile(configDir?: string, forceRefresh = false): PlatformCredentials {
+  const credentialsPath = getWindowsCredentialsPath(configDir);
+  const cacheKey = `windows-file:${credentialsPath}`;
+  return getCredentialsFromFile(credentialsPath, cacheKey, 'Windows:File', forceRefresh);
+}
+
+/**
+ * Retrieve credentials from Windows - checks both file and Credential Manager, uses the most recent valid token.
+ * Claude CLI on Windows can store credentials in either location, and they may get out of sync.
+ * We compare both sources and return the one with the most recent/valid token.
+ */
+function getCredentialsFromWindows(configDir?: string, forceRefresh = false): PlatformCredentials {
+  const isDebug = process.env.DEBUG === 'true';
+
+  // Get credentials from both sources
+  const fileResult = getCredentialsFromWindowsFile(configDir, forceRefresh);
+  const credManagerResult = getCredentialsFromWindowsCredentialManager(configDir, forceRefresh);
+
+  // If only one has a token, use that one
+  if (fileResult.token && !credManagerResult.token) {
+    if (isDebug) {
+      console.warn('[CredentialUtils:Windows] Using file credentials (Credential Manager empty)');
+    }
+    return fileResult;
+  }
+  if (credManagerResult.token && !fileResult.token) {
+    if (isDebug) {
+      console.warn('[CredentialUtils:Windows] Using Credential Manager credentials (file empty)');
+    }
+    return credManagerResult;
+  }
+
+  // If neither has a token, return file result (which has the appropriate error)
+  if (!fileResult.token && !credManagerResult.token) {
+    return fileResult;
+  }
+
+  // Both have tokens - prefer file since Claude CLI writes there after login
+  if (isDebug) {
+    console.warn('[CredentialUtils:Windows] Both sources have tokens, preferring file (Claude CLI primary storage)');
+  }
+  return fileResult;
+}
+
 // =============================================================================
 // Cross-Platform Public API
 // =============================================================================
@@ -920,8 +1134,8 @@ function findPowerShellPath(): string | null {
  * secure storage.
  *
  * - macOS: Reads from Keychain
- * - Linux: Reads from .credentials.json file
- * - Windows: Reads from Windows Credential Manager
+ * - Linux: Tries Secret Service (via secret-tool), falls back to .credentials.json
+ * - Windows: Checks both .credentials.json and Credential Manager, prefers file
  *
  * For default profile: reads from "Claude Code-credentials" or default config dir
  * For custom profiles: uses SHA256(configDir).slice(0,8) hash suffix
@@ -942,7 +1156,7 @@ export function getCredentialsFromKeychain(configDir?: string, forceRefresh = fa
   }
 
   if (isWindows()) {
-    return getCredentialsFromWindowsCredentialManager(configDir, forceRefresh);
+    return getCredentialsFromWindows(configDir, forceRefresh);
   }
 
   // Unknown platform - return empty
@@ -967,11 +1181,13 @@ export function clearKeychainCache(configDir?: string): void {
     const linuxSecretKey = `linux-secret:${getSecretServiceAttribute(configDir)}`;
     const linuxFileKey = `linux:${getLinuxCredentialsPath(configDir)}`;
     const windowsKey = `windows:${getWindowsCredentialTarget(configDir)}`;
+    const windowsFileKey = `windows-file:${getWindowsCredentialsPath(configDir)}`;
 
     credentialCache.delete(macOSKey);
     credentialCache.delete(linuxSecretKey);
     credentialCache.delete(linuxFileKey);
     credentialCache.delete(windowsKey);
+    credentialCache.delete(windowsFileKey);
   } else {
     credentialCache.clear();
   }
@@ -1136,67 +1352,7 @@ function getFullCredentialsFromLinux(configDir?: string): FullOAuthCredentials {
  */
 function getFullCredentialsFromLinuxFile(configDir?: string): FullOAuthCredentials {
   const credentialsPath = getLinuxCredentialsPath(configDir);
-  const isDebug = process.env.DEBUG === 'true';
-
-  // Defense-in-depth: Validate credentials path is within expected boundaries
-  if (!isValidCredentialsPath(credentialsPath)) {
-    if (isDebug) {
-      console.warn('[CredentialUtils:Linux:Full] Invalid credentials path rejected:', { credentialsPath });
-    }
-    return { token: null, email: null, refreshToken: null, expiresAt: null, scopes: null, subscriptionType: null, rateLimitTier: null, error: 'Invalid credentials path' };
-  }
-
-  // Check if credentials file exists
-  if (!existsSync(credentialsPath)) {
-    if (isDebug) {
-      console.warn('[CredentialUtils:Linux:Full] Credentials file not found:', credentialsPath);
-    }
-    return { token: null, email: null, refreshToken: null, expiresAt: null, scopes: null, subscriptionType: null, rateLimitTier: null };
-  }
-
-  try {
-    const content = readFileSync(credentialsPath, 'utf-8');
-
-    // Parse JSON
-    let data: unknown;
-    try {
-      data = JSON.parse(content);
-    } catch {
-      console.warn('[CredentialUtils:Linux:Full] Failed to parse credentials JSON:', credentialsPath);
-      return { token: null, email: null, refreshToken: null, expiresAt: null, scopes: null, subscriptionType: null, rateLimitTier: null };
-    }
-
-    // Validate JSON structure
-    if (!validateCredentialData(data)) {
-      console.warn('[CredentialUtils:Linux:Full] Invalid credentials data structure:', credentialsPath);
-      return { token: null, email: null, refreshToken: null, expiresAt: null, scopes: null, subscriptionType: null, rateLimitTier: null };
-    }
-
-    const { token, email, refreshToken, expiresAt, scopes, subscriptionType, rateLimitTier } = extractFullCredentials(data);
-
-    // Validate token format if present
-    if (token && !isValidTokenFormat(token)) {
-      console.warn('[CredentialUtils:Linux:Full] Invalid token format in:', credentialsPath);
-      return { token: null, email, refreshToken, expiresAt, scopes, subscriptionType, rateLimitTier };
-    }
-
-    if (isDebug) {
-      console.warn('[CredentialUtils:Linux:Full] Retrieved full credentials from file:', credentialsPath, {
-        hasToken: !!token,
-        hasEmail: !!email,
-        hasRefreshToken: !!refreshToken,
-        expiresAt: expiresAt ? new Date(expiresAt).toISOString() : null,
-        tokenFingerprint: getTokenFingerprint(token),
-        subscriptionType,
-        rateLimitTier
-      });
-    }
-    return { token, email, refreshToken, expiresAt, scopes, subscriptionType, rateLimitTier };
-  } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    console.warn('[CredentialUtils:Linux:Full] Failed to read credentials file:', credentialsPath, errorMessage);
-    return { token: null, email: null, refreshToken: null, expiresAt: null, scopes: null, subscriptionType: null, rateLimitTier: null, error: `Failed to read credentials: ${errorMessage}` };
-  }
+  return getFullCredentialsFromFile(credentialsPath, 'Linux:Full');
 }
 
 /**
@@ -1223,29 +1379,51 @@ function getFullCredentialsFromWindowsCredentialManager(configDir?: string): Ful
 
   try {
     // PowerShell script to read from Credential Manager (same as basic credentials)
+    // NOTE: The CREDENTIAL struct must use IntPtr for string fields (blittable requirement)
     const psScript = `
       $ErrorActionPreference = 'Stop'
-      Add-Type -AssemblyName System.Runtime.WindowsRuntime
 
-      # Use CredRead from advapi32.dll to read generic credentials
-      $sig = @'
-      [DllImport("advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
-      public static extern bool CredRead(string target, int type, int reservedFlag, out IntPtr credentialPtr);
+      # Define the CREDENTIAL struct with IntPtr for string fields (required for marshaling)
+      Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
 
-      [DllImport("advapi32.dll", SetLastError = true)]
-      public static extern bool CredFree(IntPtr cred);
+[StructLayout(LayoutKind.Sequential)]
+public struct CREDENTIAL {
+    public uint Flags;
+    public uint Type;
+    public IntPtr TargetName;
+    public IntPtr Comment;
+    public System.Runtime.InteropServices.ComTypes.FILETIME LastWritten;
+    public uint CredentialBlobSize;
+    public IntPtr CredentialBlob;
+    public uint Persist;
+    public uint AttributeCount;
+    public IntPtr Attributes;
+    public IntPtr TargetAlias;
+    public IntPtr UserName;
+}
 '@
-      Add-Type -MemberDefinition $sig -Namespace Win32 -Name Credential
+
+      # Import CredRead and CredFree from advapi32.dll
+      Add-Type -MemberDefinition @'
+[DllImport("advapi32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
+public static extern bool CredRead(string target, uint type, uint reservedFlag, out IntPtr credentialPtr);
+
+[DllImport("advapi32.dll", SetLastError = true)]
+public static extern bool CredFree(IntPtr cred);
+'@ -Namespace Win32 -Name CredApi
 
       $credPtr = [IntPtr]::Zero
       # CRED_TYPE_GENERIC = 1
-      $success = [Win32.Credential]::CredRead("${escapePowerShellString(targetName)}", 1, 0, [ref]$credPtr)
+      $success = [Win32.CredApi]::CredRead("${escapePowerShellString(targetName)}", 1, 0, [ref]$credPtr)
 
       if ($success) {
         try {
-          $cred = [Runtime.InteropServices.Marshal]::PtrToStructure($credPtr, [Type][System.Management.Automation.PSCredential].Assembly.GetType('Microsoft.PowerShell.Commands.CREDENTIAL'))
+          # Marshal the pointer to our CREDENTIAL struct
+          $cred = [Runtime.InteropServices.Marshal]::PtrToStructure($credPtr, [Type][CREDENTIAL])
 
-          # Read the credential blob (password field)
+          # Read the credential blob (password field) - contains the JSON
           $blobSize = $cred.CredentialBlobSize
           if ($blobSize -gt 0) {
             $blob = [byte[]]::new($blobSize)
@@ -1254,7 +1432,7 @@ function getFullCredentialsFromWindowsCredentialManager(configDir?: string): Ful
             Write-Output $password
           }
         } finally {
-          [Win32.Credential]::CredFree($credPtr) | Out-Null
+          [Win32.CredApi]::CredFree($credPtr) | Out-Null
         }
       } else {
         # Credential not found - this is expected if user hasn't authenticated
@@ -1306,6 +1484,56 @@ function getFullCredentialsFromWindowsCredentialManager(configDir?: string): Ful
   }
 }
 
+/**
+ * Retrieve full credentials (including refresh token) from Windows .credentials.json file
+ * This is the primary storage mechanism used by Claude CLI on Windows
+ */
+function getFullCredentialsFromWindowsFile(configDir?: string): FullOAuthCredentials {
+  const credentialsPath = getWindowsCredentialsPath(configDir);
+  return getFullCredentialsFromFile(credentialsPath, 'Windows:File:Full');
+}
+
+/**
+ * Retrieve full credentials from Windows - checks both file and Credential Manager, uses the most recent valid token.
+ * Claude CLI on Windows can store credentials in either location, and they may get out of sync.
+ * We compare both sources and return the one with the later expiry time (most recently refreshed).
+ */
+function getFullCredentialsFromWindows(configDir?: string): FullOAuthCredentials {
+  const isDebug = process.env.DEBUG === 'true';
+
+  // Get credentials from both sources
+  const fileResult = getFullCredentialsFromWindowsFile(configDir);
+  const credManagerResult = getFullCredentialsFromWindowsCredentialManager(configDir);
+
+  // If only one has a token, use that one
+  if (fileResult.token && !credManagerResult.token) {
+    if (isDebug) {
+      console.warn('[CredentialUtils:Windows:Full] Using file credentials (Credential Manager empty)');
+    }
+    return fileResult;
+  }
+  if (credManagerResult.token && !fileResult.token) {
+    if (isDebug) {
+      console.warn('[CredentialUtils:Windows:Full] Using Credential Manager credentials (file empty)');
+    }
+    return credManagerResult;
+  }
+
+  // If neither has a token, return file result (which has the appropriate error)
+  if (!fileResult.token && !credManagerResult.token) {
+    return fileResult;
+  }
+
+  // Both have tokens - prefer file since Claude CLI writes there after login
+  // This is consistent with getCredentialsFromWindows() which also prefers file.
+  // Using file as primary ensures consistency: the same token is returned whether
+  // calling getCredentialsFromKeychain() or getFullCredentialsFromKeychain().
+  if (isDebug) {
+    console.warn('[CredentialUtils:Windows:Full] Both sources have tokens, preferring file (Claude CLI primary storage)');
+  }
+  return fileResult;
+}
+
 /**
  * Get full credentials including refresh token and expiry from platform-specific secure storage.
  * This is an extended version of getCredentialsFromKeychain that returns all credential data
@@ -1324,7 +1552,7 @@ export function getFullCredentialsFromKeychain(configDir?: string): FullOAuthCre
   }
 
   if (isWindows()) {
-    return getFullCredentialsFromWindowsCredentialManager(configDir);
+    return getFullCredentialsFromWindows(configDir);
   }
 
   // Unknown platform - return empty
@@ -1589,6 +1817,12 @@ function updateLinuxFileCredentials(
 
     const credentialsJson = JSON.stringify(newCredentialData, null, 2);
 
+    // Ensure directory exists (matching Windows behavior)
+    const dirPath = dirname(credentialsPath);
+    if (!existsSync(dirPath)) {
+      mkdirSync(dirPath, { recursive: true, mode: 0o700 });
+    }
+
     // Write to file with secure permissions (0600)
     writeFileSync(credentialsPath, credentialsJson, { mode: 0o600, encoding: 'utf-8' });
 
@@ -1658,10 +1892,18 @@ function updateWindowsCredentialManagerCredentials(
     const base64Json = encodeBase64ForPowerShell(credentialsJson);
 
     // PowerShell script to write to Credential Manager
+    //
+    // NOTE: This CREDENTIAL struct uses string types for TargetName, Comment, etc.
+    // because CredWrite accepts data FROM us, and the .NET marshaler can automatically
+    // convert string fields to the appropriate Unicode pointers when CALLING Windows APIs.
+    // This differs from the CredRead struct (see getCredentialsFromWindowsCredentialManager)
+    // which must use IntPtr because we're RECEIVING data from Windows and need to manually
+    // marshal the strings from Windows-allocated memory.
     const psScript = `
       $ErrorActionPreference = 'Stop'
 
       # Use CredWrite from advapi32.dll to write generic credentials
+      # This struct uses string types (auto-marshaled) unlike CredRead which needs IntPtr.
       $sig = @'
       [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
       public struct CREDENTIAL {
@@ -1738,6 +1980,197 @@ function updateWindowsCredentialManagerCredentials(
   }
 }
 
+/**
+ * Restrict Windows file permissions to current user only using icacls.
+ * This is a best-effort operation - if it fails, we log a warning but don't fail the overall operation.
+ *
+ * @param filePath - Path to the file to secure
+ */
+function restrictWindowsFilePermissions(filePath: string): void {
+  const isDebug = process.env.DEBUG === 'true';
+
+  try {
+    // Use icacls to:
+    // 1. Disable inheritance and remove all inherited permissions (/inheritance:r)
+    // 2. Grant full control to the current user only (/grant:r %USERNAME%:F)
+    // This mimics Unix 0600 permissions (owner read/write only)
+    const username = userInfo().username;
+
+    // First, disable inheritance and remove inherited permissions
+    execFileSync('icacls', [filePath, '/inheritance:r'], {
+      windowsHide: true,
+      timeout: 5000,
+    });
+
+    // Then grant full control to current user only
+    execFileSync('icacls', [filePath, '/grant:r', `${username}:F`], {
+      windowsHide: true,
+      timeout: 5000,
+    });
+
+    if (isDebug) {
+      console.warn('[CredentialUtils:Windows] Set restrictive permissions on:', filePath);
+    }
+  } catch (error) {
+    // Non-fatal: log warning but don't fail the operation
+    // The file is still protected by the user's home directory permissions
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    console.warn('[CredentialUtils:Windows] Could not set restrictive file permissions:', errorMessage);
+  }
+}
+
+/**
+ * Update credentials in Windows .credentials.json file with new tokens (fallback).
+ *
+ * This is the fallback method for Windows when Credential Manager is unavailable.
+ * Claude CLI on Windows primarily uses file-based storage (.credentials.json),
+ * so this fallback ensures credentials are persisted even if Credential Manager fails.
+ *
+ * Security: We use icacls to restrict file permissions to the current user only,
+ * mimicking Unix 0600 permissions. This prevents other users on multi-user systems
+ * from reading the OAuth tokens.
+ *
+ * @param configDir - Config directory for the profile (undefined for default profile)
+ * @param credentials - New credentials to store
+ * @returns Result indicating success or failure
+ */
+function updateWindowsFileCredentials(
+  configDir: string | undefined,
+  credentials: {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    scopes?: string[];
+  }
+): UpdateCredentialsResult {
+  const credentialsPath = getWindowsCredentialsPath(configDir);
+  const isDebug = process.env.DEBUG === 'true';
+
+  // Defense-in-depth: Validate credentials path
+  if (!isValidCredentialsPath(credentialsPath)) {
+    return { success: false, error: 'Invalid credentials path' };
+  }
+
+  try {
+    // Read existing credentials to preserve email and other fields
+    const existing = getFullCredentialsFromWindowsFile(configDir);
+
+    // Build new credential JSON with all fields
+    const newCredentialData = {
+      claudeAiOauth: {
+        accessToken: credentials.accessToken,
+        refreshToken: credentials.refreshToken,
+        expiresAt: credentials.expiresAt,
+        scopes: credentials.scopes || existing.scopes || [],
+        email: existing.email || undefined,
+        emailAddress: existing.email || undefined,
+        subscriptionType: existing.subscriptionType || undefined,
+        rateLimitTier: existing.rateLimitTier || undefined
+      },
+      email: existing.email || undefined
+    };
+
+    const credentialsJson = JSON.stringify(newCredentialData, null, 2);
+
+    // Ensure directory exists with secure permissions
+    const dirPath = dirname(credentialsPath);
+    if (!existsSync(dirPath)) {
+      mkdirSync(dirPath, { recursive: true });
+      // Restrict directory permissions to current user only (mimics Unix 0700)
+      restrictWindowsFilePermissions(dirPath);
+    }
+
+    // Atomic file write: write to temp file, set permissions, then rename.
+    // This prevents a race condition where the file briefly exists with default permissions.
+    const tempPath = `${credentialsPath}.${Date.now()}.tmp`;
+    try {
+      // Write to temp file
+      writeFileSync(tempPath, credentialsJson, { encoding: 'utf-8' });
+
+      // Restrict temp file permissions to current user only (mimics Unix 0600)
+      restrictWindowsFilePermissions(tempPath);
+
+      // Atomic rename (on same filesystem, this is atomic on Windows)
+      renameSync(tempPath, credentialsPath);
+    } catch (writeError) {
+      // Clean up temp file on error
+      try {
+        if (existsSync(tempPath)) {
+          unlinkSync(tempPath);
+        }
+      } catch {
+        // Ignore cleanup errors
+      }
+      throw writeError;
+    }
+
+    if (isDebug) {
+      console.warn('[CredentialUtils:Windows:Update] Successfully updated credentials file:', credentialsPath);
+    }
+
+    // Clear cached credentials to ensure fresh values are read
+    clearCredentialCache(configDir);
+
+    return { success: true };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    console.error('[CredentialUtils:Windows:Update] Failed to update credentials file:', errorMessage);
+    return { success: false, error: `File update failed: ${errorMessage}` };
+  }
+}
+
+/**
+ * Update credentials in Windows - writes to file FIRST (primary storage), then Credential Manager.
+ *
+ * Claude CLI on Windows primarily uses file-based storage (.credentials.json).
+ * We write to file first to ensure Claude CLI always has the latest tokens,
+ * then update Credential Manager for forward compatibility.
+ *
+ * IMPORTANT: The write order matters! If we wrote to Credential Manager first and file
+ * write failed, Claude CLI would read stale tokens from the file while Credential Manager
+ * has the new tokens - an inconsistent state. By writing to file first, we ensure the
+ * primary storage is always up-to-date.
+ *
+ * @param configDir - Config directory for the profile (undefined for default profile)
+ * @param credentials - New credentials to store
+ * @returns Result indicating success or failure
+ */
+function updateWindowsCredentials(
+  configDir: string | undefined,
+  credentials: {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    scopes?: string[];
+  }
+): UpdateCredentialsResult {
+  const isDebug = process.env.DEBUG === 'true';
+
+  // Write to file FIRST - this is what Claude CLI reads on Windows
+  const fileResult = updateWindowsFileCredentials(configDir, credentials);
+  if (!fileResult.success) {
+    // File write failed - don't proceed with Credential Manager to avoid inconsistent state
+    console.error('[CredentialUtils:Windows:Update] File update failed:', fileResult.error);
+    return fileResult;
+  }
+
+  // File write succeeded - now update Credential Manager for forward compatibility
+  const psPath = findPowerShellPath();
+  if (psPath) {
+    const credManagerResult = updateWindowsCredentialManagerCredentials(configDir, credentials);
+    if (!credManagerResult.success) {
+      // Credential Manager failed but file succeeded - this is acceptable
+      // Claude CLI will use the file, which has the latest tokens
+      if (isDebug) {
+        console.warn('[CredentialUtils:Windows:Update] Credential Manager update failed (file update succeeded):', credManagerResult.error);
+      }
+    }
+  }
+
+  // Return success since file (primary storage) was updated successfully
+  return { success: true };
+}
+
 /**
  * Update credentials in the platform-specific secure storage with new tokens.
  * Called after a successful OAuth token refresh to persist the new tokens.
@@ -1767,7 +2200,7 @@ export function updateKeychainCredentials(
   }
 
   if (isWindows()) {
-    return updateWindowsCredentialManagerCredentials(configDir, credentials);
+    return updateWindowsCredentials(configDir, credentials);
   }
 
   return { success: false, error: `Unsupported platform: ${process.platform}` };

apps/frontend/src/main/cli-tool-manager.ts

@@ -46,6 +46,7 @@ import {
   getWindowsExecutablePaths,
   getWindowsExecutablePathsAsync,
   WINDOWS_GIT_PATHS,
+  WINDOWS_GLAB_PATHS,
   findWindowsExecutableViaWhere,
   findWindowsExecutableViaWhereAsync,
   isSecurePath,
@@ -54,7 +55,7 @@ import {
 /**
  * Supported CLI tools managed by this system
  */
-export type CLITool = 'python' | 'git' | 'gh' | 'claude';
+export type CLITool = 'python' | 'git' | 'gh' | 'glab' | 'claude';
 
 /**
  * User configuration for CLI tool paths
@@ -64,6 +65,7 @@ export interface ToolConfig {
   pythonPath?: string;
   gitPath?: string;
   githubCLIPath?: string;
+  gitlabCLIPath?: string;
   claudePath?: string;
 }
 
@@ -370,6 +372,8 @@ class CLIToolManager {
         return this.detectGit();
       case 'gh':
         return this.detectGitHubCLI();
+      case 'glab':
+        return this.detectGitLabCLI();
       case 'claude':
         return this.detectClaude();
       default:
@@ -719,6 +723,105 @@ class CLIToolManager {
     };
   }
 
+  /**
+   * Detect GitLab CLI with multi-level priority
+   *
+   * Priority order:
+   * 1. User configuration (if valid for current platform)
+   * 2. Homebrew glab (macOS)
+   * 3. System PATH
+   * 4. Windows Program Files
+   *
+   * @returns Detection result for GitLab CLI
+   */
+  private detectGitLabCLI(): ToolDetectionResult {
+    // 1. User configuration
+    if (this.userConfig.gitlabCLIPath) {
+      // Check if path is from wrong platform (e.g., Windows path on macOS)
+      if (isWrongPlatformPath(this.userConfig.gitlabCLIPath)) {
+        console.warn(
+          `[GitLab CLI] User-configured path is from different platform, ignoring: ${this.userConfig.gitlabCLIPath}`
+        );
+      } else {
+        const validation = this.validateGitLabCLI(this.userConfig.gitlabCLIPath);
+        if (validation.valid) {
+          return {
+            found: true,
+            path: this.userConfig.gitlabCLIPath,
+            version: validation.version,
+            source: 'user-config',
+            message: `Using user-configured GitLab CLI: ${this.userConfig.gitlabCLIPath}`,
+          };
+        }
+        console.warn(
+          `[GitLab CLI] User-configured path invalid: ${validation.message}`
+        );
+      }
+    }
+
+    // 2. Homebrew (macOS)
+    if (isMacOS()) {
+      const homebrewPaths = [
+        '/opt/homebrew/bin/glab', // Apple Silicon
+        '/usr/local/bin/glab', // Intel Mac
+      ];
+
+      for (const glabPath of homebrewPaths) {
+        if (existsSync(glabPath)) {
+          const validation = this.validateGitLabCLI(glabPath);
+          if (validation.valid) {
+            return {
+              found: true,
+              path: glabPath,
+              version: validation.version,
+              source: 'homebrew',
+              message: `Using Homebrew GitLab CLI: ${glabPath}`,
+            };
+          }
+        }
+      }
+    }
+
+    // 3. System PATH (augmented)
+    const glabPath = findExecutable('glab');
+    if (glabPath) {
+      const validation = this.validateGitLabCLI(glabPath);
+      if (validation.valid) {
+        return {
+          found: true,
+          path: glabPath,
+          version: validation.version,
+          source: 'system-path',
+          message: `Using system GitLab CLI: ${glabPath}`,
+        };
+      }
+    }
+
+    // 4. Windows Program Files
+    if (isWindows()) {
+      const windowsPaths = getWindowsExecutablePaths(WINDOWS_GLAB_PATHS, '[GitLab CLI]');
+      for (const glabPath of windowsPaths) {
+        const validation = this.validateGitLabCLI(glabPath);
+        if (validation.valid) {
+          return {
+            found: true,
+            path: glabPath,
+            version: validation.version,
+            source: 'system-path',
+            message: `Using Windows GitLab CLI: ${glabPath}`,
+          };
+        }
+      }
+    }
+
+    // 5. Not found
+    return {
+      found: false,
+      source: 'fallback',
+      message: 'GitLab CLI (glab) not found. Install from https://gitlab.com/gitlab-org/cli',
+    };
+  }
+
   /**
    * Detect Claude CLI with multi-level priority
    *
@@ -846,6 +949,7 @@ class CLIToolManager {
         encoding: 'utf-8',
         timeout: 5000,
         windowsHide: true,
+        env: getAugmentedEnv(),
       }).trim();
 
       const match = version.match(/Python (\d+\.\d+\.\d+)/);
@@ -896,6 +1000,7 @@ class CLIToolManager {
         encoding: 'utf-8',
         timeout: 5000,
         windowsHide: true,
+        env: getAugmentedEnv(),
       }).trim();
 
       const match = version.match(/git version (\d+\.\d+\.\d+)/);
@@ -926,6 +1031,7 @@ class CLIToolManager {
         encoding: 'utf-8',
         timeout: 5000,
         windowsHide: true,
+        env: getAugmentedEnv(),
       }).trim();
 
       const match = version.match(/gh version (\d+\.\d+\.\d+)/);
@@ -944,6 +1050,38 @@ class CLIToolManager {
     }
   }
 
+  /**
+   * Validate GitLab CLI availability and version
+   *
+   * @param glabCmd - The GitLab CLI command to validate
+   * @returns Validation result with version information
+   */
+  private validateGitLabCLI(glabCmd: string): ToolValidation {
+    try {
+      const version = execFileSync(glabCmd, ['--version'], {
+        encoding: 'utf-8',
+        timeout: 5000,
+        windowsHide: true,
+        env: getAugmentedEnv(),
+      }).trim();
+
+      // glab version output format: "glab X.Y.Z (hash)" - note: no "version" word
+      const match = version.match(/glab\s+(\d+\.\d+\.\d+)/);
+      const versionStr = match ? match[1] : version.split('\n')[0];
+
+      return {
+        valid: true,
+        version: versionStr,
+        message: `GitLab CLI ${versionStr} is available`,
+      };
+    } catch (error) {
+      return {
+        valid: false,
+        message: `Failed to validate GitLab CLI: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  }
+
   /**
    * Validate Claude CLI availability and version
    *
@@ -1097,6 +1235,8 @@ class CLIToolManager {
         return this.detectGitAsync();
       case 'gh':
         return this.detectGitHubCLIAsync();
+      case 'glab':
+        return this.detectGitLabCLIAsync();
       default:
         return {
           found: false,
@@ -1298,6 +1438,39 @@ class CLIToolManager {
     }
   }
 
+  /**
+   * Validate GitLab CLI availability and version asynchronously (non-blocking)
+   *
+   * @param glabCmd - The GitLab CLI command to validate
+   * @returns Promise resolving to validation result
+   */
+  private async validateGitLabCLIAsync(glabCmd: string): Promise<ToolValidation> {
+    try {
+      const { stdout } = await execFileAsync(glabCmd, ['--version'], {
+        encoding: 'utf-8',
+        timeout: 5000,
+        windowsHide: true,
+        env: await getAugmentedEnvAsync(),
+      });
+
+      const version = stdout.trim();
+      // glab version output format: "glab X.Y.Z (hash)" - note: no "version" word
+      const match = version.match(/glab\s+(\d+\.\d+\.\d+)/);
+      const versionStr = match ? match[1] : version.split('\n')[0];
+
+      return {
+        valid: true,
+        version: versionStr,
+        message: `GitLab CLI ${versionStr} is available`,
+      };
+    } catch (error) {
+      return {
+        valid: false,
+        message: `Failed to validate GitLab CLI: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  }
+
   /**
    * Detect Claude CLI asynchronously (non-blocking)
    *
@@ -1724,6 +1897,98 @@ class CLIToolManager {
     };
   }
 
+  /**
+   * Detect GitLab CLI asynchronously (non-blocking)
+   *
+   * Same detection logic as detectGitLabCLI but uses async validation.
+   *
+   * @returns Promise resolving to detection result
+   */
+  private async detectGitLabCLIAsync(): Promise<ToolDetectionResult> {
+    // 1. User configuration
+    if (this.userConfig.gitlabCLIPath) {
+      if (isWrongPlatformPath(this.userConfig.gitlabCLIPath)) {
+        console.warn(
+          `[GitLab CLI] User-configured path is from different platform, ignoring: ${this.userConfig.gitlabCLIPath}`
+        );
+      } else {
+        const validation = await this.validateGitLabCLIAsync(this.userConfig.gitlabCLIPath);
+        if (validation.valid) {
+          return {
+            found: true,
+            path: this.userConfig.gitlabCLIPath,
+            version: validation.version,
+            source: 'user-config',
+            message: `Using user-configured GitLab CLI: ${this.userConfig.gitlabCLIPath}`,
+          };
+        }
+        console.warn(`[GitLab CLI] User-configured path invalid: ${validation.message}`);
+      }
+    }
+
+    // 2. Homebrew (macOS)
+    if (isMacOS()) {
+      const homebrewPaths = [
+        '/opt/homebrew/bin/glab',
+        '/usr/local/bin/glab',
+      ];
+
+      for (const glabPath of homebrewPaths) {
+        if (await existsAsync(glabPath)) {
+          const validation = await this.validateGitLabCLIAsync(glabPath);
+          if (validation.valid) {
+            return {
+              found: true,
+              path: glabPath,
+              version: validation.version,
+              source: 'homebrew',
+              message: `Using Homebrew GitLab CLI: ${glabPath}`,
+            };
+          }
+        }
+      }
+    }
+
+    // 3. System PATH (augmented)
+    const glabPath = await findExecutableAsync('glab');
+    if (glabPath) {
+      const validation = await this.validateGitLabCLIAsync(glabPath);
+      if (validation.valid) {
+        return {
+          found: true,
+          path: glabPath,
+          version: validation.version,
+          source: 'system-path',
+          message: `Using system GitLab CLI: ${glabPath}`,
+        };
+      }
+    }
+
+    // 4. Windows Program Files
+    if (isWindows()) {
+      const windowsPaths = await getWindowsExecutablePathsAsync(WINDOWS_GLAB_PATHS, '[GitLab CLI]');
+      for (const winGlabPath of windowsPaths) {
+        const validation = await this.validateGitLabCLIAsync(winGlabPath);
+        if (validation.valid) {
+          return {
+            found: true,
+            path: winGlabPath,
+            version: validation.version,
+            source: 'system-path',
+            message: `Using Windows GitLab CLI: ${winGlabPath}`,
+          };
+        }
+      }
+    }
+
+    // 5. Not found
+    return {
+      found: false,
+      source: 'fallback',
+      message: 'GitLab CLI (glab) not found. Install from https://gitlab.com/gitlab-org/cli',
+    };
+  }
+
   /**
    * Get bundled Python path for packaged apps
    *

apps/frontend/src/main/index.ts

@@ -35,7 +35,7 @@ for (const envPath of possibleEnvPaths) {
   }
 }
 
-import { app, BrowserWindow, shell, nativeImage, session, screen } from 'electron';
+import { app, BrowserWindow, shell, nativeImage, session, screen, Menu, MenuItem } from 'electron';
 import { join } from 'path';
 import { accessSync, readFileSync, writeFileSync, rmSync } from 'fs';
 import { electronApp, optimizer, is } from '@electron-toolkit/utils';
@@ -46,13 +46,16 @@ import { pythonEnvManager } from './python-env-manager';
 import { getUsageMonitor } from './claude-profile/usage-monitor';
 import { initializeUsageMonitorForwarding } from './ipc-handlers/terminal-handlers';
 import { initializeAppUpdater, stopPeriodicUpdates } from './app-updater';
-import { DEFAULT_APP_SETTINGS, IPC_CHANNELS } from '../shared/constants';
+import { DEFAULT_APP_SETTINGS, IPC_CHANNELS, SPELL_CHECK_LANGUAGE_MAP, DEFAULT_SPELL_CHECK_LANGUAGE, ADD_TO_DICTIONARY_LABELS } from '../shared/constants';
+import { getAppLanguage, initAppLanguage } from './app-language';
 import { readSettingsFile } from './settings-utils';
 import { setupErrorLogging } from './app-logger';
 import { initSentryMain } from './sentry';
 import { preWarmToolCache } from './cli-tool-manager';
 import { initializeClaudeProfileManager, getClaudeProfileManager } from './claude-profile-manager';
+import { isProfileAuthenticated } from './claude-profile/profile-utils';
 import { isMacOS, isWindows } from './platform';
+import { ptyDaemonClient } from './terminal/pty-daemon-client';
 import type { AppSettings, AuthFailureInfo } from '../shared/types';
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -140,6 +143,12 @@ let mainWindow: BrowserWindow | null = null;
 let agentManager: AgentManager | null = null;
 let terminalManager: TerminalManager | null = null;
 
+// Re-entrancy guard for before-quit handler.
+// The first before-quit call pauses quit for async cleanup, then calls app.quit() again.
+// The second call sees isQuitting=true and allows quit to proceed immediately.
+// Fixes: pty.node SIGABRT crash caused by environment teardown before PTY cleanup (GitHub #1469)
+let isQuitting = false;
+
 function createWindow(): void {
   // Get the primary display's work area (accounts for taskbar, dock, etc.)
   // Wrapped in try/catch to handle potential failures with fallback to safe defaults
@@ -196,7 +205,8 @@ function createWindow(): void {
       sandbox: false,
       contextIsolation: true,
       nodeIntegration: false,
-      backgroundThrottling: false // Prevent terminal lag when window loses focus
+      backgroundThrottling: false, // Prevent terminal lag when window loses focus
+      spellcheck: true // Enable spell check for text inputs
     }
   });
 
@@ -205,6 +215,87 @@ function createWindow(): void {
     mainWindow?.show();
   });
 
+  // Configure initial spell check languages with proper fallback logic
+  // Uses shared constant for consistency with the IPC handler
+  const defaultLanguage = 'en';
+  const defaultSpellCheckLanguages = SPELL_CHECK_LANGUAGE_MAP[defaultLanguage] || [DEFAULT_SPELL_CHECK_LANGUAGE];
+  const availableSpellCheckLanguages = session.defaultSession.availableSpellCheckerLanguages;
+  const validSpellCheckLanguages = defaultSpellCheckLanguages.filter(lang =>
+    availableSpellCheckLanguages.includes(lang)
+  );
+  const initialSpellCheckLanguages = validSpellCheckLanguages.length > 0
+    ? validSpellCheckLanguages
+    : (availableSpellCheckLanguages.includes(DEFAULT_SPELL_CHECK_LANGUAGE) ? [DEFAULT_SPELL_CHECK_LANGUAGE] : []);
+
+  if (initialSpellCheckLanguages.length > 0) {
+    session.defaultSession.setSpellCheckerLanguages(initialSpellCheckLanguages);
+    console.log(`[SPELLCHECK] Initial languages set to: ${initialSpellCheckLanguages.join(', ')}`);
+  } else {
+    console.warn('[SPELLCHECK] No spell check languages available on this system');
+  }
+
+  // Handle context menu with spell check and standard editing options
+  mainWindow.webContents.on('context-menu', (_event, params) => {
+    const menu = new Menu();
+
+    // Add spelling suggestions if there's a misspelled word
+    if (params.misspelledWord) {
+      for (const suggestion of params.dictionarySuggestions) {
+        menu.append(new MenuItem({
+          label: suggestion,
+          click: () => mainWindow?.webContents.replaceMisspelling(suggestion)
+        }));
+      }
+
+      if (params.dictionarySuggestions.length > 0) {
+        menu.append(new MenuItem({ type: 'separator' }));
+      }
+
+      // Use localized label for "Add to Dictionary" based on app language (not OS locale)
+      // getAppLanguage() tracks the user's in-app language setting, updated via SPELLCHECK_SET_LANGUAGES IPC
+      const addToDictionaryLabel = ADD_TO_DICTIONARY_LABELS[getAppLanguage()] || ADD_TO_DICTIONARY_LABELS['en'];
+      menu.append(new MenuItem({
+        label: addToDictionaryLabel,
+        click: () => mainWindow?.webContents.session.addWordToSpellCheckerDictionary(params.misspelledWord)
+      }));
+
+      menu.append(new MenuItem({ type: 'separator' }));
+    }
+
+    // Standard editing options for editable fields
+    // Using role without explicit label allows Electron to provide localized labels
+    if (params.isEditable) {
+      menu.append(new MenuItem({
+        role: 'cut',
+        enabled: params.editFlags.canCut
+      }));
+      menu.append(new MenuItem({
+        role: 'copy',
+        enabled: params.editFlags.canCopy
+      }));
+      menu.append(new MenuItem({
+        role: 'paste',
+        enabled: params.editFlags.canPaste
+      }));
+      menu.append(new MenuItem({
+        role: 'selectAll',
+        enabled: params.editFlags.canSelectAll
+      }));
+    } else if (params.selectionText?.trim()) {
+      // Non-editable text selection (e.g., labels, paragraphs)
+      // Use .trim() to avoid showing menu for whitespace-only selections
+      menu.append(new MenuItem({
+        role: 'copy',
+        enabled: params.editFlags.canCopy
+      }));
+    }
+
+    // Only show menu if there are items
+    if (menu.items.length > 0) {
+      menu.popup();
+    }
+  });
+
   // Handle external links with URL scheme allowlist for security
   // Note: Terminal links now use IPC via WebLinksAddon callback, but this handler
   // catches any other window.open() calls (e.g., from third-party libraries)
@@ -270,6 +361,9 @@ app.whenReady().then(() => {
       .catch((err) => console.warn('[main] Failed to clear cache:', err));
   }
 
+  // Initialize app language from OS locale for main process i18n (context menus)
+  initAppLanguage();
+
   // Clean up stale update metadata from the old source updater system
   // This prevents version display desync after electron-updater installs a new version
   cleanupStaleUpdateMetadata();
@@ -416,9 +510,22 @@ app.whenReady().then(() => {
         if (migratedProfileIds.length > 0) {
           console.warn('[main] Found migrated profiles that need re-authentication:', migratedProfileIds);
 
-          // If the active profile was migrated, show auth failure modal immediately
-          if (migratedProfileIds.includes(activeProfile.id)) {
-            // Wait for renderer to be ready before sending the event
+          // Check ALL migrated profiles for valid credentials, not just the active one
+          // This prevents stale migrated flags from triggering unnecessary re-auth prompts
+          // when the user switches to a different profile later
+          for (const profileId of migratedProfileIds) {
+            const profile = profileManager.getProfile(profileId);
+            if (profile && isProfileAuthenticated(profile)) {
+              // Credentials are valid - clear the migrated flag
+              console.warn('[main] Migrated profile has valid credentials via file fallback, clearing migrated flag:', profile.name);
+              profileManager.clearMigratedProfile(profileId);
+            }
+          }
+
+          // Re-check if the active profile still needs re-auth after clearing valid ones
+          const remainingMigratedIds = profileManager.getMigratedProfileIds();
+          if (remainingMigratedIds.includes(activeProfile.id)) {
+            // Active profile still needs re-auth - show the modal
             mainWindow.webContents.once('did-finish-load', () => {
               // Small delay to ensure stores are initialized
               setTimeout(() => {
@@ -494,24 +601,50 @@ app.on('window-all-closed', () => {
   }
 });
 
-// Cleanup before quit
-app.on('before-quit', async () => {
-  // Stop periodic update checks
+// Cleanup before quit — uses event.preventDefault() to allow async PTY cleanup
+// before the JS environment tears down. Without this, pty.node's native
+// ThreadSafeFunction callbacks fire after teardown, causing SIGABRT (GitHub #1469).
+app.on('before-quit', (event) => {
+  // Re-entrancy guard: the second app.quit() call (after cleanup) must pass through
+  if (isQuitting) {
+    return;
+  }
+  isQuitting = true;
+
+  // Pause quit to perform async cleanup
+  event.preventDefault();
+
+  // Stop synchronous services immediately
   stopPeriodicUpdates();
 
-  // Stop usage monitor
   const usageMonitor = getUsageMonitor();
   usageMonitor.stop();
   console.warn('[main] Usage monitor stopped');
 
-  // Kill all running agent processes
-  if (agentManager) {
-    await agentManager.killAll();
-  }
-  // Kill all terminal processes
-  if (terminalManager) {
-    await terminalManager.killAll();
-  }
+  // Perform async cleanup, then allow quit to proceed
+  (async () => {
+    try {
+      // Kill all running agent processes
+      if (agentManager) {
+        await agentManager.killAll();
+      }
+
+      // Kill all terminal processes — waits for PTY exit with bounded timeout
+      if (terminalManager) {
+        await terminalManager.killAll();
+      }
+
+      // Shut down PTY daemon client AFTER terminal cleanup completes,
+      // ensuring all kill commands reach PTY processes before the daemon disconnects
+      ptyDaemonClient.shutdown();
+      console.warn('[main] PTY daemon client shutdown complete');
+    } catch (error) {
+      console.error('[main] Error during pre-quit cleanup:', error);
+    } finally {
+      // Always allow quit to proceed, even if cleanup fails
+      app.quit();
+    }
+  })();
 });
 
 // Note: Uncaught exceptions and unhandled rejections are now

apps/frontend/src/main/ipc-handlers/agent-events-handlers.ts

@@ -1,106 +1,23 @@
 import type { BrowserWindow } from "electron";
 import path from "path";
-import { existsSync } from "fs";
+import { existsSync, readFileSync } from "fs";
 import { IPC_CHANNELS, AUTO_BUILD_PATHS, getSpecsDir } from "../../shared/constants";
-import {
-  wouldPhaseRegress,
-  isTerminalPhase,
-  isValidExecutionPhase,
-  isValidPhaseTransition,
-  type ExecutionPhase,
-} from "../../shared/constants/phase-protocol";
 import type {
   SDKRateLimitInfo,
   AuthFailureInfo,
-  Task,
-  TaskStatus,
-  Project,
   ImplementationPlan,
 } from "../../shared/types";
 import { AgentManager } from "../agent";
 import type { ProcessType, ExecutionProgressData } from "../agent";
 import { titleGenerator } from "../title-generator";
 import { fileWatcher } from "../file-watcher";
-import { projectStore } from "../project-store";
 import { notificationService } from "../notification-service";
-import { persistPlanStatusSync, getPlanPath } from "./task/plan-file-utils";
+import { persistPlanLastEventSync, getPlanPath, persistPlanPhaseSync } from "./task/plan-file-utils";
 import { findTaskWorktree } from "../worktree-paths";
 import { findTaskAndProject } from "./task/shared";
 import { safeSendToRenderer } from "./utils";
 import { getClaudeProfileManager } from "../claude-profile-manager";
-
-/**
- * Validates status transitions to prevent invalid state changes.
- * FIX (ACS-55, ACS-71): Adds guardrails against bad status transitions.
- * FIX (PR Review): Uses comprehensive wouldPhaseRegress() utility instead of hardcoded checks.
- * FIX (ACS-203): Adds phase completion validation to prevent phase overlaps.
- *
- * @param task - The current task (may be undefined if not found)
- * @param newStatus - The proposed new status
- * @param phase - The execution phase that triggered this transition
- * @returns true if transition is valid, false if it should be blocked
- */
-function validateStatusTransition(
-  task: Task | undefined,
-  newStatus: TaskStatus,
-  phase: string
-): boolean {
-  // Can't validate without task data - allow the transition
-  if (!task) return true;
-
-  // Don't allow human_review without subtasks
-  // This prevents tasks from jumping to review before planning is complete
-  if (newStatus === "human_review" && (!task.subtasks || task.subtasks.length === 0)) {
-    console.warn(
-      `[validateStatusTransition] Blocking human_review - task ${task.id} has no subtasks (phase: ${phase})`
-    );
-    return false;
-  }
-
-  // FIX (PR Review): Use comprehensive phase regression check instead of hardcoded checks
-  // This handles all phase regressions (qa_review→coding, complete→coding, etc.)
-  // not just the specific coding→planning case
-  const currentPhase = task.executionProgress?.phase;
-  const completedPhases = task.executionProgress?.completedPhases || [];
-
-  if (currentPhase && isValidExecutionPhase(currentPhase) && isValidExecutionPhase(phase)) {
-    // Block transitions from terminal phases (complete/failed)
-    if (isTerminalPhase(currentPhase)) {
-      console.warn(
-        `[validateStatusTransition] Blocking transition from terminal phase: ${currentPhase} for task ${task.id}`
-      );
-      return false;
-    }
-
-    // Block any phase regression (going backwards in the workflow)
-    // Note: Cast phase to ExecutionPhase since isValidExecutionPhase() type guard doesn't narrow through function calls
-    if (wouldPhaseRegress(currentPhase, phase as ExecutionPhase)) {
-      console.warn(
-        `[validateStatusTransition] Blocking phase regression: ${currentPhase} -> ${phase} for task ${task.id}`
-      );
-      return false;
-    }
-
-    // FIX (ACS-203): Validate phase transitions based on completed phases
-    // This prevents multiple phases from being active simultaneously
-    // e.g., coding starting while planning is still marked as active
-    const newPhase = phase as ExecutionPhase;
-    if (!isValidPhaseTransition(currentPhase, newPhase, completedPhases)) {
-      console.warn(
-        `[validateStatusTransition] Blocking invalid phase transition: ${currentPhase} -> ${newPhase} for task ${task.id}`,
-        {
-          currentPhase,
-          newPhase,
-          completedPhases,
-          reason: "Prerequisite phases not completed",
-        }
-      );
-      return false;
-    }
-  }
-
-  return true;
-}
+import { taskStateManager } from "../task-state-manager";
 
 /**
  * Register all agent-events-related IPC handlers
@@ -109,6 +26,8 @@ export function registerAgenteventsHandlers(
   agentManager: AgentManager,
   getMainWindow: () => BrowserWindow | null
 ): void {
+  taskStateManager.configure(getMainWindow);
+
   // ============================================
   // Agent Manager Events → Renderer
   // ============================================
@@ -164,10 +83,12 @@ export function registerAgenteventsHandlers(
   });
 
   agentManager.on("exit", (taskId: string, code: number | null, processType: ProcessType) => {
-    // Get project info early for multi-project filtering (issue #723)
-    const { project: exitProject } = findTaskAndProject(taskId);
+    // Get task + project for context and multi-project filtering (issue #723)
+    const { task: exitTask, project: exitProject } = findTaskAndProject(taskId);
     const exitProjectId = exitProject?.id;
 
+    taskStateManager.handleProcessExited(taskId, code, exitTask, exitProject);
+
     // Send final plan state to renderer BEFORE unwatching
     // This ensures the renderer has the final subtask data (fixes 0/0 subtask bug)
     const finalPlan = fileWatcher.getCurrentPlan(taskId);
@@ -188,113 +109,70 @@ export function registerAgenteventsHandlers(
       return;
     }
 
-    let task: Task | undefined;
-    let project: Project | undefined;
+    const { task, project } = findTaskAndProject(taskId);
+    if (!task || !project) return;
 
-    try {
-      const projects = projectStore.getProjects();
+    const taskTitle = task.title || task.specId;
+    if (code === 0) {
+      notificationService.notifyReviewNeeded(taskTitle, project.id, taskId);
+    } else {
+      notificationService.notifyTaskFailed(taskTitle, project.id, taskId);
+    }
+  });
 
-      // IMPORTANT: Invalidate cache for all projects to ensure we get fresh data
-      // This prevents race conditions where cached task data has stale status
-      for (const p of projects) {
-        projectStore.invalidateTasksCache(p.id);
-      }
-
-      for (const p of projects) {
-        const tasks = projectStore.getTasks(p.id);
-        task = tasks.find((t) => t.id === taskId || t.specId === taskId);
-        if (task) {
-          project = p;
-          break;
-        }
-      }
+  agentManager.on("task-event", (taskId: string, event) => {
+    console.log(`[agent-events-handlers] Received task-event for ${taskId}:`, event.type, event);
 
+    if (taskStateManager.getLastSequence(taskId) === undefined) {
+      const { task, project } = findTaskAndProject(taskId);
       if (task && project) {
-        const taskTitle = task.title || task.specId;
-        const mainPlanPath = getPlanPath(project, task);
-        const projectId = project.id; // Capture for closure
-
-        // Capture task values for closure
-        const taskSpecId = task.specId;
-        const projectPath = project.path;
-        const autoBuildPath = project.autoBuildPath;
-
-        // Use shared utility for persisting status (prevents race conditions)
-        // Persist to both main project AND worktree (if exists) for consistency
-        const persistStatus = (status: TaskStatus) => {
-          // Persist to main project
-          const mainPersisted = persistPlanStatusSync(mainPlanPath, status, projectId);
-          if (mainPersisted) {
-            console.warn(`[Task ${taskId}] Persisted status to main plan: ${status}`);
+        try {
+          const planPath = getPlanPath(project, task);
+          const planContent = readFileSync(planPath, "utf-8");
+          const plan = JSON.parse(planContent);
+          const lastSeq = plan?.lastEvent?.sequence;
+          if (typeof lastSeq === "number" && lastSeq >= 0) {
+            taskStateManager.setLastSequence(taskId, lastSeq);
           }
-
-          // Also persist to worktree if it exists
-          const worktreePath = findTaskWorktree(projectPath, taskSpecId);
-          if (worktreePath) {
-            const specsBaseDir = getSpecsDir(autoBuildPath);
-            const worktreePlanPath = path.join(
-              worktreePath,
-              specsBaseDir,
-              taskSpecId,
-              AUTO_BUILD_PATHS.IMPLEMENTATION_PLAN
-            );
-            if (existsSync(worktreePlanPath)) {
-              const worktreePersisted = persistPlanStatusSync(worktreePlanPath, status, projectId);
-              if (worktreePersisted) {
-                console.warn(`[Task ${taskId}] Persisted status to worktree plan: ${status}`);
-              }
-            }
-          }
-        };
-
-        if (code === 0) {
-          notificationService.notifyReviewNeeded(taskTitle, project.id, taskId);
-
-          // Fallback: Ensure status is updated even if COMPLETE phase event was missed
-          // This prevents tasks from getting stuck in ai_review status
-          // FIX (ACS-71): Only move to human_review if subtasks exist AND are all completed
-          // If no subtasks exist, the task is still in planning and shouldn't move to human_review
-          const isActiveStatus = task.status === "in_progress" || task.status === "ai_review";
-          const hasSubtasks = task.subtasks && task.subtasks.length > 0;
-          const hasIncompleteSubtasks =
-            hasSubtasks && task.subtasks.some((s) => s.status !== "completed");
-
-          if (isActiveStatus && hasSubtasks && !hasIncompleteSubtasks) {
-            // All subtasks completed - safe to move to human_review
-            console.warn(
-              `[Task ${taskId}] Fallback: Moving to human_review (process exited successfully, all ${task.subtasks.length} subtasks completed)`
-            );
-            persistStatus("human_review");
-            // Include projectId for multi-project filtering (issue #723)
-            safeSendToRenderer(
-              getMainWindow,
-              IPC_CHANNELS.TASK_STATUS_CHANGE,
-              taskId,
-              "human_review" as TaskStatus,
-              projectId
-            );
-          } else if (isActiveStatus && !hasSubtasks) {
-            // No subtasks yet - task is still in planning phase, don't change status
-            // This prevents the bug where tasks jump to human_review before planning completes
-            console.warn(
-              `[Task ${taskId}] Process exited but no subtasks created yet - keeping current status (${task.status})`
-            );
-          }
-        } else {
-          notificationService.notifyTaskFailed(taskTitle, project.id, taskId);
-          persistStatus("human_review");
-          // Include projectId for multi-project filtering (issue #723)
-          safeSendToRenderer(
-            getMainWindow,
-            IPC_CHANNELS.TASK_STATUS_CHANGE,
-            taskId,
-            "human_review" as TaskStatus,
-            projectId
-          );
+        } catch {
+          // Ignore missing/invalid plan files
         }
       }
-    } catch (error) {
-      console.error(`[Task ${taskId}] Exit handler error:`, error);
+    }
+
+    const { task, project } = findTaskAndProject(taskId);
+    if (!task || !project) {
+      console.log(`[agent-events-handlers] No task/project found for ${taskId}`);
+      return;
+    }
+
+    console.log(`[agent-events-handlers] Task state before handleTaskEvent:`, {
+      status: task.status,
+      reviewReason: task.reviewReason,
+      phase: task.executionProgress?.phase
+    });
+
+    const accepted = taskStateManager.handleTaskEvent(taskId, event, task, project);
+    console.log(`[agent-events-handlers] Event ${event.type} accepted: ${accepted}`);
+    if (!accepted) {
+      return;
+    }
+
+    const mainPlanPath = getPlanPath(project, task);
+    persistPlanLastEventSync(mainPlanPath, event);
+
+    const worktreePath = findTaskWorktree(project.path, task.specId);
+    if (worktreePath) {
+      const specsBaseDir = getSpecsDir(project.autoBuildPath);
+      const worktreePlanPath = path.join(
+        worktreePath,
+        specsBaseDir,
+        task.specId,
+        AUTO_BUILD_PATHS.IMPLEMENTATION_PLAN
+      );
+      if (existsSync(worktreePlanPath)) {
+        persistPlanLastEventSync(worktreePlanPath, event);
+      }
     }
   });
 
@@ -303,6 +181,28 @@ export function registerAgenteventsHandlers(
     const { task, project } = findTaskAndProject(taskId);
     const taskProjectId = project?.id;
 
+    // Persist phase to plan file for restoration on app refresh
+    // Must persist to BOTH main project and worktree (if exists) since task may be loaded from either
+    if (task && project && progress.phase) {
+      const mainPlanPath = getPlanPath(project, task);
+      persistPlanPhaseSync(mainPlanPath, progress.phase, project.id);
+
+      // Also persist to worktree if task has one
+      const worktreePath = findTaskWorktree(project.path, task.specId);
+      if (worktreePath) {
+        const specsBaseDir = getSpecsDir(project.autoBuildPath);
+        const worktreePlanPath = path.join(
+          worktreePath,
+          specsBaseDir,
+          task.specId,
+          AUTO_BUILD_PATHS.IMPLEMENTATION_PLAN
+        );
+        if (existsSync(worktreePlanPath)) {
+          persistPlanPhaseSync(worktreePlanPath, progress.phase, project.id);
+        }
+      }
+    }
+
     // Include projectId in execution progress event for multi-project filtering
     safeSendToRenderer(
       getMainWindow,
@@ -311,62 +211,6 @@ export function registerAgenteventsHandlers(
       progress,
       taskProjectId
     );
-
-    const phaseToStatus: Record<string, TaskStatus | null> = {
-      idle: null,
-      planning: "in_progress",
-      coding: "in_progress",
-      qa_review: "ai_review",
-      qa_fixing: "ai_review",
-      complete: "human_review",
-      failed: "human_review",
-    };
-
-    const newStatus = phaseToStatus[progress.phase];
-    // FIX (ACS-55, ACS-71): Validate status transition before sending/persisting
-    if (newStatus && validateStatusTransition(task, newStatus, progress.phase)) {
-      // Include projectId in status change event for multi-project filtering
-      safeSendToRenderer(
-        getMainWindow,
-        IPC_CHANNELS.TASK_STATUS_CHANGE,
-        taskId,
-        newStatus,
-        taskProjectId
-      );
-
-      // CRITICAL: Persist status to plan file(s) to prevent flip-flop on task list refresh
-      // When getTasks() is called, it reads status from the plan file. Without persisting,
-      // the status in the file might differ from the UI, causing inconsistent state.
-      // Uses shared utility with locking to prevent race conditions.
-      // IMPORTANT: We persist to BOTH main project AND worktree (if exists) to ensure
-      // consistency, since getTasks() prefers the worktree version.
-      if (task && project) {
-        try {
-          // Persist to main project plan file
-          const mainPlanPath = getPlanPath(project, task);
-          persistPlanStatusSync(mainPlanPath, newStatus, project.id);
-
-          // Also persist to worktree plan file if it exists
-          // This ensures consistency since getTasks() prefers worktree version
-          const worktreePath = findTaskWorktree(project.path, task.specId);
-          if (worktreePath) {
-            const specsBaseDir = getSpecsDir(project.autoBuildPath);
-            const worktreePlanPath = path.join(
-              worktreePath,
-              specsBaseDir,
-              task.specId,
-              AUTO_BUILD_PATHS.IMPLEMENTATION_PLAN
-            );
-            if (existsSync(worktreePlanPath)) {
-              persistPlanStatusSync(worktreePlanPath, newStatus, project.id);
-            }
-          }
-        } catch (err) {
-          // Ignore persistence errors - UI will still work, just might flip on refresh
-          console.warn("[execution-progress] Could not persist status:", err);
-        }
-      }
-    }
   });
 
   // ============================================

apps/frontend/src/main/ipc-handlers/claude-code-handlers.ts

@@ -23,7 +23,7 @@ import { isSecurePath } from '../utils/windows-paths';
 import { isWindows, isMacOS, isLinux } from '../platform';
 import { getClaudeProfileManager } from '../claude-profile-manager';
 import { isValidConfigDir } from '../utils/config-path-validator';
-import { clearKeychainCache } from '../claude-profile/credential-utils';
+import { clearKeychainCache, getCredentialsFromKeychain } from '../claude-profile/credential-utils';
 import { getUsageMonitor } from '../claude-profile/usage-monitor';
 import semver from 'semver';
 
@@ -855,7 +855,7 @@ interface AuthCheckResult {
  * Checks multiple locations based on platform:
  * - macOS: .claude.json with oauthAccount containing emailAddress
  * - Linux: .credentials.json OR .claude.json (Claude uses different storage on Linux)
- * - Windows: .claude.json with oauthAccount containing emailAddress
+ * - Windows: .claude.json, .credentials.json, AND Windows Credential Manager
  *
  * Also returns the full oauthAccount data so we can update the profile token.
  */
@@ -890,8 +890,8 @@ function checkProfileAuthentication(configDir: string): AuthCheckResult {
       }
     }
 
-    // On Linux, also check .credentials.json (Claude CLI may store tokens here)
-    if (isLinux() && existsSync(credentialsJsonPath)) {
+    // On Linux and Windows, also check .credentials.json (Claude CLI stores tokens here)
+    if ((isLinux() || isWindows()) && existsSync(credentialsJsonPath)) {
       const content = readFileSync(credentialsJsonPath, 'utf-8');
       const data = JSON.parse(content);
 
@@ -928,6 +928,22 @@ function checkProfileAuthentication(configDir: string): AuthCheckResult {
       }
     }
 
+    // On Windows, also check Windows Credential Manager as a fallback
+    // Credentials may be stored ONLY in Credential Manager (not in files)
+    if (isWindows()) {
+      const keychainCreds = getCredentialsFromKeychain(expandedConfigDir);
+      if (keychainCreds.token) {
+        return {
+          authenticated: true,
+          email: keychainCreds.email || undefined,
+          oauthAccount: {
+            accessToken: keychainCreds.token,
+            emailAddress: keychainCreds.email || undefined
+          }
+        };
+      }
+    }
+
     return { authenticated: false };
   } catch (error) {
     console.error('[Claude Code] Error checking authentication:', error);

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

@@ -505,11 +505,11 @@ export interface PRReviewProgress {
 interface CIWaitResult {
   /** Whether we successfully waited (no timeout) */
   success: boolean;
-  /** Whether any checks are still in progress */
+  /** Whether any checks are still pending (queued or in_progress) */
   hasInProgress: boolean;
-  /** Number of checks currently in progress */
+  /** Number of checks currently pending (queued or in_progress) */
   inProgressCount: number;
-  /** Names of checks still in progress (if any) */
+  /** Names of checks still pending (if any) */
   inProgressChecks: string[];
   /** Whether we timed out waiting */
   timedOut: boolean;
@@ -520,9 +520,13 @@ interface CIWaitResult {
 /**
  * Wait for CI checks to complete before starting AI review.
  *
- * Polls GitHub API to check if any CI checks are "in_progress".
- * Only blocks on "in_progress" status - does NOT block on "queued" status
- * (which could be CLA, licensing workflows that may never run).
+ * Polls GitHub API to check if any CI checks are "queued" or "in_progress".
+ * Blocks on BOTH statuses because:
+ * - "queued" = CI has been triggered but not started yet
+ * - "in_progress" = CI is actively running
+ *
+ * We wait for all checks to reach "completed" status before reviewing,
+ * so our review doesn't report "CI is pending" when it will finish soon.
  *
  * @param token GitHub API token
  * @param repo Repository in "owner/repo" format
@@ -581,10 +585,10 @@ async function waitForCIChecks(
         }>;
       };
 
-      // Find checks that are actively running (in_progress)
-      // We do NOT block on "queued" status - those could be CLA/licensing workflows
+      // Find checks that are not yet completed (queued or in_progress)
+      // We block on BOTH statuses to ensure CI is fully done before reviewing
       const inProgressChecks = checkRuns.check_runs.filter(
-        (cr) => cr.status === "in_progress"
+        (cr) => cr.status === "queued" || cr.status === "in_progress"
       );
 
       const inProgressCount = inProgressChecks.length;
@@ -602,10 +606,10 @@ async function waitForCIChecks(
         inProgressNames,
       });
 
-      // If no checks are in_progress, we can proceed
+      // If no checks are pending (queued or in_progress), we can proceed
       if (inProgressCount === 0) {
         const waitTimeSeconds = Math.floor((Date.now() - startTime) / 1000);
-        debugLog("No CI checks in progress, proceeding with review", {
+        debugLog("All CI checks completed, proceeding with review", {
           prNumber,
           waitTimeSeconds,
         });

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

@@ -16,9 +16,9 @@ import fs from 'fs';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 import type { Project } from '../../../../shared/types';
-import type { AuthFailureInfo } from '../../../../shared/types/terminal';
+import type { AuthFailureInfo, BillingFailureInfo } from '../../../../shared/types/terminal';
 import { parsePythonCommand } from '../../../python-detector';
-import { detectAuthFailure } from '../../../rate-limit-detector';
+import { detectAuthFailure, detectBillingFailure } from '../../../rate-limit-detector';
 import { getClaudeProfileManager } from '../../../claude-profile-manager';
 import { isWindows, isMacOS } from '../../../platform';
 
@@ -68,6 +68,8 @@ export interface SubprocessOptions {
   onError?: (error: string) => void;
   /** Callback when auth failure (401) is detected in output */
   onAuthFailure?: (authFailureInfo: AuthFailureInfo) => void;
+  /** Callback when billing/credit exhaustion failure is detected in output */
+  onBillingFailure?: (billingFailureInfo: BillingFailureInfo) => void;
   progressPattern?: RegExp;
   /** Additional environment variables to pass to the subprocess */
   env?: Record<string, string>;
@@ -130,6 +132,8 @@ export function runPythonSubprocess<T = unknown>(
     let stderr = '';
     let authFailureEmitted = false; // Track if we've already emitted an auth failure
     let killedDueToAuthFailure = false; // Track if subprocess was killed due to auth failure
+    let billingFailureEmitted = false; // Track if we've already emitted a billing failure
+    let killedDueToBillingFailure = false; // Track if subprocess was killed due to billing failure
 
     // Default progress pattern: [ 30%] message OR [30%] message
     const progressPattern = options.progressPattern ?? /\[\s*(\d+)%\]\s*(.+)/;
@@ -193,6 +197,65 @@ export function runPythonSubprocess<T = unknown>(
       }
     };
 
+    // Helper to check for billing/credit failures in output and emit once
+    const checkBillingFailure = (line: string) => {
+      if (billingFailureEmitted || !options.onBillingFailure) return;
+
+      const billingResult = detectBillingFailure(line);
+      if (billingResult.isBillingFailure) {
+        billingFailureEmitted = true;
+        console.log('[SubprocessRunner] Billing failure detected in real-time:', billingResult);
+
+        // Get profile info for display
+        const profileManager = getClaudeProfileManager();
+        const profile = billingResult.profileId
+          ? profileManager.getProfile(billingResult.profileId)
+          : profileManager.getActiveProfile();
+
+        const billingFailureInfo: BillingFailureInfo = {
+          profileId: billingResult.profileId || profile?.id || 'unknown',
+          profileName: profile?.name,
+          failureType: billingResult.failureType || 'unknown',
+          message: billingResult.message || 'Billing or credit error. Please check your account.',
+          originalError: billingResult.originalError,
+          detectedAt: new Date(),
+        };
+
+        try {
+          options.onBillingFailure(billingFailureInfo);
+        } catch (e) {
+          console.error('[SubprocessRunner] onBillingFailure callback threw:', e);
+        }
+
+        // Kill the subprocess to stop the billing failure spam
+        killedDueToBillingFailure = true;
+        // The process is stuck in billing errors - no point continuing
+        console.log('[SubprocessRunner] Killing subprocess due to billing failure, pid:', child.pid);
+
+        // Use process.kill with negative PID to kill the entire process group on Unix
+        // This ensures child processes (like the Claude SDK subprocess) are also killed
+        if (child.pid) {
+          try {
+            // On Unix, negative PID kills the process group
+            if (!isWindows()) {
+              process.kill(-child.pid, 'SIGKILL');
+            } else {
+              // On Windows, use taskkill to kill the process tree
+              execFile('taskkill', ['/pid', String(child.pid), '/T', '/F'], (err: Error | null) => {
+                if (err) console.warn('[SubprocessRunner] taskkill error (process may have already exited):', err.message);
+              });
+            }
+          } catch (err) {
+            // Fallback to regular kill if process group kill fails
+            console.log('[SubprocessRunner] Process group kill failed, using regular kill:', err);
+            child.kill('SIGKILL');
+          }
+        } else {
+          child.kill('SIGKILL');
+        }
+      }
+    };
+
     child.stdout.on('data', (data: Buffer) => {
       const text = data.toString('utf-8');
       stdout += text;
@@ -206,6 +269,9 @@ export function runPythonSubprocess<T = unknown>(
           // Check for auth failures in real-time (only emit once)
           checkAuthFailure(line);
 
+          // Check for billing/credit failures in real-time (only emit once)
+          checkBillingFailure(line);
+
           // Parse progress updates
           const match = line.match(progressPattern);
           if (match && options.onProgress) {
@@ -228,6 +294,9 @@ export function runPythonSubprocess<T = unknown>(
 
           // Also check stderr for auth failures
           checkAuthFailure(line);
+
+          // Also check stderr for billing/credit failures
+          checkBillingFailure(line);
         }
       }
     });
@@ -260,6 +329,18 @@ export function runPythonSubprocess<T = unknown>(
         return;
       }
 
+      // Check if subprocess was killed due to billing/credit failure
+      if (killedDueToBillingFailure) {
+        resolve({
+          success: false,
+          exitCode: exitCode,
+          stdout,
+          stderr,
+          error: 'Billing or credit error. Please check your account.',
+        });
+        return;
+      }
+
       if (exitCode === 0) {
         try {
           const data = options.onComplete?.(stdout, stderr);

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

@@ -239,7 +239,7 @@ export function registerLinearHandlers(
 
       try {
         const query = `
-          query($teamId: ID!) {
+          query($teamId: String!) {
             team(id: $teamId) {
               projects {
                 nodes {

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

@@ -286,6 +286,44 @@ export function registerProjectHandlers(
     }
   );
 
+  // ============================================
+  // Kanban Preferences Operations (persisted in main process)
+  // ============================================
+
+  ipcMain.handle(
+    IPC_CHANNELS.KANBAN_PREFS_GET,
+    async (_, projectId: string): Promise<IPCResult<Record<string, { width: number; isCollapsed: boolean; isLocked: boolean }> | null>> => {
+      try {
+        const preferences = projectStore.getKanbanPreferences(projectId);
+        return { success: true, data: preferences };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Unknown error'
+        };
+      }
+    }
+  );
+
+  ipcMain.handle(
+    IPC_CHANNELS.KANBAN_PREFS_SAVE,
+    async (
+      _,
+      projectId: string,
+      preferences: Record<string, { width: number; isCollapsed: boolean; isLocked: boolean }>
+    ): Promise<IPCResult> => {
+      try {
+        projectStore.saveKanbanPreferences(projectId, preferences);
+        return { success: true };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Unknown error'
+        };
+      }
+    }
+  );
+
   // ============================================
   // Project Initialization Operations
   // ============================================

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

@@ -1,4 +1,4 @@
-import { ipcMain, dialog, app, shell } from 'electron';
+import { ipcMain, dialog, app, shell, session } from 'electron';
 import { existsSync, writeFileSync, mkdirSync, statSync, readFileSync } from 'fs';
 import { execFileSync } from 'node:child_process';
 import path from 'path';
@@ -8,7 +8,8 @@ import { is } from '@electron-toolkit/utils';
 // ESM-compatible __dirname
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-import { IPC_CHANNELS, DEFAULT_APP_SETTINGS, DEFAULT_AGENT_PROFILES } from '../../shared/constants';
+import { IPC_CHANNELS, DEFAULT_APP_SETTINGS, DEFAULT_AGENT_PROFILES, SPELL_CHECK_LANGUAGE_MAP, DEFAULT_SPELL_CHECK_LANGUAGE } from '../../shared/constants';
+import { setAppLanguage } from '../app-language';
 import type {
   AppSettings,
   IPCResult,
@@ -138,7 +139,7 @@ export function registerSettingsHandlers(
       // Fixes issue where Windows paths persisted on macOS (and vice versa)
       // when settings were synced/transferred between platforms
       // See: https://github.com/AndyMik90/Auto-Claude/issues/XXX
-      const pathFields = ['pythonPath', 'gitPath', 'githubCLIPath', 'claudePath', 'autoBuildPath'] as const;
+      const pathFields = ['pythonPath', 'gitPath', 'githubCLIPath', 'gitlabCLIPath', 'claudePath', 'autoBuildPath'] as const;
       for (const field of pathFields) {
         const pathValue = settings[field];
         if (pathValue && isPathFromWrongPlatform(pathValue)) {
@@ -173,6 +174,7 @@ export function registerSettingsHandlers(
         pythonPath: settings.pythonPath,
         gitPath: settings.gitPath,
         githubCLIPath: settings.githubCLIPath,
+        gitlabCLIPath: settings.gitlabCLIPath,
         claudePath: settings.claudePath,
       });
 
@@ -214,12 +216,14 @@ export function registerSettingsHandlers(
           settings.pythonPath !== undefined ||
           settings.gitPath !== undefined ||
           settings.githubCLIPath !== undefined ||
+          settings.gitlabCLIPath !== undefined ||
           settings.claudePath !== undefined
         ) {
           configureTools({
             pythonPath: newSettings.pythonPath,
             gitPath: newSettings.gitPath,
             githubCLIPath: newSettings.githubCLIPath,
+            gitlabCLIPath: newSettings.gitlabCLIPath,
             claudePath: newSettings.claudePath,
           });
 
@@ -259,6 +263,7 @@ export function registerSettingsHandlers(
       python: ReturnType<typeof getToolInfo>;
       git: ReturnType<typeof getToolInfo>;
       gh: ReturnType<typeof getToolInfo>;
+      glab: ReturnType<typeof getToolInfo>;
       claude: ReturnType<typeof getToolInfo>;
     }>> => {
       try {
@@ -268,6 +273,7 @@ export function registerSettingsHandlers(
             python: getToolInfo('python'),
             git: getToolInfo('git'),
             gh: getToolInfo('gh'),
+            glab: getToolInfo('glab'),
             claude: getToolInfo('claude'),
           },
         };
@@ -801,4 +807,64 @@ export function registerSettingsHandlers(
       }
     }
   );
+
+  // ============================================
+  // Spell Check Operations
+  // ============================================
+
+  /**
+   * Set spell check languages based on app language.
+   * Called when renderer's i18n language changes to sync spell checker.
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.SPELLCHECK_SET_LANGUAGES,
+    async (_, language: string): Promise<IPCResult<{ success: boolean }>> => {
+      try {
+        // Validate language parameter
+        if (!language || typeof language !== 'string') {
+          return {
+            success: false,
+            error: 'Invalid language parameter'
+          };
+        }
+
+        // Update tracked app language for context menu labels
+        setAppLanguage(language);
+
+        // Get spell check languages for this app language
+        const spellCheckLanguages = SPELL_CHECK_LANGUAGE_MAP[language] || [DEFAULT_SPELL_CHECK_LANGUAGE];
+
+        // Get available languages on this system
+        const availableLanguages = session.defaultSession.availableSpellCheckerLanguages;
+
+        // Filter to only available languages
+        const validLanguages = spellCheckLanguages.filter(lang =>
+          availableLanguages.includes(lang)
+        );
+
+        // Fallback to default if none of the preferred languages are available
+        const languagesToSet = validLanguages.length > 0
+          ? validLanguages
+          : (availableLanguages.includes(DEFAULT_SPELL_CHECK_LANGUAGE) ? [DEFAULT_SPELL_CHECK_LANGUAGE] : []);
+
+        if (languagesToSet.length > 0) {
+          session.defaultSession.setSpellCheckerLanguages(languagesToSet);
+          console.log(`[SPELLCHECK] Languages set to: ${languagesToSet.join(', ')} for app language: ${language}`);
+        } else {
+          console.warn(`[SPELLCHECK] No valid spell check languages available for: ${language}`);
+        }
+
+        return {
+          success: true,
+          data: { success: true }
+        };
+      } catch (error) {
+        console.error('[SPELLCHECK_SET_LANGUAGES] Error:', error);
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Failed to set spell check languages'
+        };
+      }
+    }
+  );
 }

apps/frontend/src/main/ipc-handlers/task/__tests__/worktree-branch-validation.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Tests for worktree branch validation logic.
+ *
+ * Issue #1479: When cleaning up a corrupted worktree, git rev-parse walks up
+ * to the main project and returns its current branch instead of the worktree's branch.
+ * This could cause deletion of the wrong branch.
+ *
+ * These tests verify the validation logic that prevents this.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { GIT_BRANCH_REGEX, validateWorktreeBranch } from '../worktree-handlers';
+
+describe('GIT_BRANCH_REGEX', () => {
+  it('should accept valid auto-claude branch names', () => {
+    expect(GIT_BRANCH_REGEX.test('auto-claude/my-feature')).toBe(true);
+    expect(GIT_BRANCH_REGEX.test('auto-claude/123-fix-bug')).toBe(true);
+    expect(GIT_BRANCH_REGEX.test('auto-claude/feature_with_underscore')).toBe(true);
+  });
+
+  it('should accept valid feature branch names', () => {
+    expect(GIT_BRANCH_REGEX.test('feature/my-feature')).toBe(true);
+    expect(GIT_BRANCH_REGEX.test('fix/bug-123')).toBe(true);
+    expect(GIT_BRANCH_REGEX.test('main')).toBe(true);
+    expect(GIT_BRANCH_REGEX.test('develop')).toBe(true);
+  });
+
+  it('should accept single character branch names', () => {
+    expect(GIT_BRANCH_REGEX.test('a')).toBe(true);
+    expect(GIT_BRANCH_REGEX.test('1')).toBe(true);
+  });
+
+  it('should reject invalid branch names', () => {
+    expect(GIT_BRANCH_REGEX.test('')).toBe(false);
+    expect(GIT_BRANCH_REGEX.test('-invalid')).toBe(false);
+    expect(GIT_BRANCH_REGEX.test('invalid-')).toBe(false);
+    expect(GIT_BRANCH_REGEX.test('.invalid')).toBe(false);
+  });
+
+  it('should accept HEAD as syntactically valid (handled specially in validation logic)', () => {
+    // HEAD is technically valid as a git branch name syntactically,
+    // but when detected from rev-parse it indicates detached state.
+    // The validateWorktreeBranch function handles this case specially.
+    expect(GIT_BRANCH_REGEX.test('HEAD')).toBe(true);
+  });
+});
+
+describe('validateWorktreeBranch', () => {
+  const expectedBranch = 'auto-claude/my-feature-123';
+
+  describe('exact match scenarios', () => {
+    it('should use detected branch when it matches expected exactly', () => {
+      const result = validateWorktreeBranch('auto-claude/my-feature-123', expectedBranch);
+      expect(result.branchToDelete).toBe('auto-claude/my-feature-123');
+      expect(result.usedFallback).toBe(false);
+      expect(result.reason).toBe('exact_match');
+    });
+  });
+
+  describe('pattern match scenarios', () => {
+    it('should allow other auto-claude branches (specId renamed)', () => {
+      const result = validateWorktreeBranch('auto-claude/renamed-feature', expectedBranch);
+      expect(result.branchToDelete).toBe('auto-claude/renamed-feature');
+      expect(result.usedFallback).toBe(false);
+      expect(result.reason).toBe('pattern_match');
+    });
+
+    it('should allow auto-claude branches with different formats', () => {
+      const result = validateWorktreeBranch('auto-claude/001-task', expectedBranch);
+      expect(result.branchToDelete).toBe('auto-claude/001-task');
+      expect(result.usedFallback).toBe(false);
+      expect(result.reason).toBe('pattern_match');
+    });
+  });
+
+  describe('security: corrupted worktree scenarios (issue #1479)', () => {
+    it('should reject main project branch and use expected pattern', () => {
+      // This is the critical case: corrupted worktree returns main project's branch
+      const result = validateWorktreeBranch('feature/xstate-task-machine', expectedBranch);
+      expect(result.branchToDelete).toBe(expectedBranch);
+      expect(result.usedFallback).toBe(true);
+      expect(result.reason).toBe('invalid_pattern');
+    });
+
+    it('should reject develop branch', () => {
+      const result = validateWorktreeBranch('develop', expectedBranch);
+      expect(result.branchToDelete).toBe(expectedBranch);
+      expect(result.usedFallback).toBe(true);
+      expect(result.reason).toBe('invalid_pattern');
+    });
+
+    it('should reject main branch', () => {
+      const result = validateWorktreeBranch('main', expectedBranch);
+      expect(result.branchToDelete).toBe(expectedBranch);
+      expect(result.usedFallback).toBe(true);
+      expect(result.reason).toBe('invalid_pattern');
+    });
+
+    it('should reject master branch', () => {
+      const result = validateWorktreeBranch('master', expectedBranch);
+      expect(result.branchToDelete).toBe(expectedBranch);
+      expect(result.usedFallback).toBe(true);
+      expect(result.reason).toBe('invalid_pattern');
+    });
+
+    it('should reject fix/ branches from main project', () => {
+      const result = validateWorktreeBranch('fix/some-bug', expectedBranch);
+      expect(result.branchToDelete).toBe(expectedBranch);
+      expect(result.usedFallback).toBe(true);
+      expect(result.reason).toBe('invalid_pattern');
+    });
+
+    it('should reject feature/ branches from main project', () => {
+      const result = validateWorktreeBranch('feature/new-feature', expectedBranch);
+      expect(result.branchToDelete).toBe(expectedBranch);
+      expect(result.usedFallback).toBe(true);
+      expect(result.reason).toBe('invalid_pattern');
+    });
+  });
+
+  describe('detection failure scenarios', () => {
+    it('should use expected pattern when detection returns null', () => {
+      const result = validateWorktreeBranch(null, expectedBranch);
+      expect(result.branchToDelete).toBe(expectedBranch);
+      expect(result.usedFallback).toBe(true);
+      expect(result.reason).toBe('detection_failed');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty detected branch', () => {
+      const result = validateWorktreeBranch('', expectedBranch);
+      expect(result.branchToDelete).toBe(expectedBranch);
+      expect(result.usedFallback).toBe(true);
+      expect(result.reason).toBe('invalid_pattern');
+    });
+
+    it('should handle HEAD (detached state)', () => {
+      const result = validateWorktreeBranch('HEAD', expectedBranch);
+      expect(result.branchToDelete).toBe(expectedBranch);
+      expect(result.usedFallback).toBe(true);
+      expect(result.reason).toBe('invalid_pattern');
+    });
+
+    it('should handle branch that starts with auto-claude but is malformed', () => {
+      // "auto-claude" without a slash should still be rejected
+      const result = validateWorktreeBranch('auto-claude', expectedBranch);
+      expect(result.branchToDelete).toBe(expectedBranch);
+      expect(result.usedFallback).toBe(true);
+      expect(result.reason).toBe('invalid_pattern');
+    });
+
+    it('should reject auto-claude/ with no suffix (invalid branch name)', () => {
+      // "auto-claude/" alone is not a valid branch name - needs actual specId
+      const result = validateWorktreeBranch('auto-claude/', expectedBranch);
+      expect(result.branchToDelete).toBe(expectedBranch);
+      expect(result.usedFallback).toBe(true);
+      expect(result.reason).toBe('invalid_pattern');
+    });
+  });
+});

apps/frontend/src/main/ipc-handlers/task/crud-handlers.ts

@@ -8,7 +8,9 @@ import { titleGenerator } from '../../title-generator';
 import { AgentManager } from '../../agent';
 import { findTaskAndProject } from './shared';
 import { findAllSpecPaths, isValidTaskId } from '../../utils/spec-path-helpers';
-import { isPathWithinBase } from '../../worktree-paths';
+import { isPathWithinBase, findTaskWorktree } from '../../worktree-paths';
+import { cleanupWorktree } from '../../utils/worktree-cleanup';
+import { taskStateManager } from '../../task-state-manager';
 
 /**
  * Register task CRUD (Create, Read, Update, Delete) handlers
@@ -25,11 +27,13 @@ export function registerTaskCRUDHandlers(agentManager: AgentManager): void {
     async (_, projectId: string, options?: { forceRefresh?: boolean }): Promise<IPCResult<Task[]>> => {
       console.warn('[IPC] TASK_LIST called with projectId:', projectId, 'options:', options);
 
-      // If forceRefresh is requested, invalidate cache first
+      // If forceRefresh is requested, invalidate cache and clear XState actors
       // This ensures the refresh button always returns fresh data from disk
+      // and actors are recreated with fresh task data
       if (options?.forceRefresh) {
         projectStore.invalidateTasksCache(projectId);
-        console.warn('[IPC] TASK_LIST cache invalidated for forceRefresh');
+        taskStateManager.clearAllTasks();
+        console.warn('[IPC] TASK_LIST cache and task state cleared for forceRefresh');
       }
 
       const tasks = projectStore.getTasks(projectId);
@@ -124,28 +128,52 @@ export function registerTaskCRUDHandlers(agentManager: AgentManager): void {
       if (taskMetadata.attachedImages && taskMetadata.attachedImages.length > 0) {
         const attachmentsDir = path.join(specDir, 'attachments');
         mkdirSync(attachmentsDir, { recursive: true });
+        const resolvedAttachmentsDir = path.resolve(attachmentsDir);
+
+        // MIME type allowlist (defense in depth - frontend also validates)
+        const ALLOWED_MIME_TYPES = ['image/png', 'image/jpeg', 'image/jpg', 'image/gif', 'image/webp', 'image/svg+xml'];
 
         const savedImages: typeof taskMetadata.attachedImages = [];
 
         for (const image of taskMetadata.attachedImages) {
           if (image.data) {
+            // Validate MIME type
+            if (!image.mimeType || !ALLOWED_MIME_TYPES.includes(image.mimeType)) {
+              console.warn(`[TASK_CREATE] Skipping image with missing or disallowed MIME type: ${image.mimeType}`);
+              continue;
+            }
+
+            // Sanitize filename to prevent path traversal attacks
+            const sanitizedFilename = path.basename(image.filename);
+            if (!sanitizedFilename || sanitizedFilename === '.' || sanitizedFilename === '..') {
+              console.warn(`[TASK_CREATE] Skipping image with invalid filename: ${image.filename}`);
+              continue;
+            }
+
+            // Validate resolved path stays within attachments directory
+            const imagePath = path.join(attachmentsDir, sanitizedFilename);
+            const resolvedPath = path.resolve(imagePath);
+            if (!resolvedPath.startsWith(resolvedAttachmentsDir + path.sep)) {
+              console.warn(`[TASK_CREATE] Skipping image with path traversal attempt: ${image.filename}`);
+              continue;
+            }
+
             try {
               // Decode base64 and save to file
               const buffer = Buffer.from(image.data, 'base64');
-              const imagePath = path.join(attachmentsDir, image.filename);
               writeFileSync(imagePath, buffer);
 
               // Store relative path instead of base64 data
               savedImages.push({
                 id: image.id,
-                filename: image.filename,
+                filename: sanitizedFilename,
                 mimeType: image.mimeType,
                 size: image.size,
-                path: `attachments/${image.filename}`
+                path: `attachments/${sanitizedFilename}`
                 // Don't include data or thumbnail to save space
               });
             } catch (err) {
-              console.error(`Failed to save image ${image.filename}:`, err);
+              console.error(`Failed to save image ${sanitizedFilename}:`, err);
             }
           }
         }
@@ -216,6 +244,15 @@ export function registerTaskCRUDHandlers(agentManager: AgentManager): void {
 
   /**
    * Delete a task
+   *
+   * This handler:
+   * 1. Checks if task exists and is not running
+   * 2. Cleans up the worktree (auto-commits, deletes directory, prunes refs, deletes branch)
+   * 3. Deletes all spec directories (main project + any remaining worktree locations)
+   *
+   * Note: Worktree cleanup uses manual deletion instead of `git worktree remove --force`
+   * because the latter fails on Windows when the directory contains untracked files
+   * (node_modules, build artifacts, etc.). See: https://github.com/AndyMik90/Auto-Claude/issues/1539
    */
   ipcMain.handle(
     IPC_CHANNELS.TASK_DELETE,
@@ -235,21 +272,49 @@ export function registerTaskCRUDHandlers(agentManager: AgentManager): void {
         return { success: false, error: 'Cannot delete a running task. Stop the task first.' };
       }
 
-      // Find ALL locations where this task exists (main + worktrees)
+      let hasErrors = false;
+      const errors: string[] = [];
+
+      // Clean up the worktree first if it exists
+      // This uses the robust cleanup that handles Windows file locking issues
+      const worktreePath = findTaskWorktree(project.path, task.specId);
+      if (worktreePath) {
+        console.warn(`[TASK_DELETE] Found worktree at: ${worktreePath}`);
+        const cleanupResult = await cleanupWorktree({
+          worktreePath,
+          projectPath: project.path,
+          specId: task.specId,
+          commitMessage: 'Auto-save before task deletion',
+          logPrefix: '[TASK_DELETE]',
+          deleteBranch: true
+        });
+
+        if (!cleanupResult.success) {
+          console.error(`[TASK_DELETE] Worktree cleanup failed:`, cleanupResult.warnings);
+          hasErrors = true;
+          errors.push(`Worktree cleanup: ${cleanupResult.warnings.join('; ')}`);
+        } else {
+          if (cleanupResult.autoCommitted) {
+            console.warn(`[TASK_DELETE] Auto-committed uncommitted work before deletion`);
+          }
+          if (cleanupResult.warnings.length > 0) {
+            console.warn(`[TASK_DELETE] Cleanup warnings:`, cleanupResult.warnings);
+          }
+        }
+      }
+
+      // Find ALL locations where this task exists (main + any remaining worktree dirs)
       // Following the archiveTasks() pattern from project-store.ts
       const specsBaseDir = getSpecsDir(project.autoBuildPath);
       const specPaths = findAllSpecPaths(project.path, specsBaseDir, task.specId);
 
       // If spec directory doesn't exist anywhere, return success (already removed)
-      if (specPaths.length === 0) {
+      if (specPaths.length === 0 && !hasErrors) {
         console.warn(`[TASK_DELETE] No spec directories found for task ${taskId} - already removed`);
         projectStore.invalidateTasksCache(project.id);
         return { success: true };
       }
 
-      let hasErrors = false;
-      const errors: string[] = [];
-
       // Delete from ALL locations
       for (const specDir of specPaths) {
         try {
@@ -390,26 +455,50 @@ export function registerTaskCRUDHandlers(agentManager: AgentManager): void {
           if (updates.metadata.attachedImages && updates.metadata.attachedImages.length > 0) {
             const attachmentsDir = path.join(specDir, 'attachments');
             mkdirSync(attachmentsDir, { recursive: true });
+            const resolvedAttachmentsDir = path.resolve(attachmentsDir);
+
+            // MIME type allowlist (defense in depth - frontend also validates)
+            const ALLOWED_MIME_TYPES = ['image/png', 'image/jpeg', 'image/jpg', 'image/gif', 'image/webp', 'image/svg+xml'];
 
             const savedImages: typeof updates.metadata.attachedImages = [];
 
             for (const image of updates.metadata.attachedImages) {
               // If image has data (new image), save it
               if (image.data) {
+                // Validate MIME type
+                if (!image.mimeType || !ALLOWED_MIME_TYPES.includes(image.mimeType)) {
+                  console.warn(`[TASK_UPDATE] Skipping image with missing or disallowed MIME type: ${image.mimeType}`);
+                  continue;
+                }
+
+                // Sanitize filename to prevent path traversal attacks
+                const sanitizedFilename = path.basename(image.filename);
+                if (!sanitizedFilename || sanitizedFilename === '.' || sanitizedFilename === '..') {
+                  console.warn(`[TASK_UPDATE] Skipping image with invalid filename: ${image.filename}`);
+                  continue;
+                }
+
+                // Validate resolved path stays within attachments directory
+                const imagePath = path.join(attachmentsDir, sanitizedFilename);
+                const resolvedPath = path.resolve(imagePath);
+                if (!resolvedPath.startsWith(resolvedAttachmentsDir + path.sep)) {
+                  console.warn(`[TASK_UPDATE] Skipping image with path traversal attempt: ${image.filename}`);
+                  continue;
+                }
+
                 try {
                   const buffer = Buffer.from(image.data, 'base64');
-                  const imagePath = path.join(attachmentsDir, image.filename);
                   writeFileSync(imagePath, buffer);
 
                   savedImages.push({
                     id: image.id,
-                    filename: image.filename,
+                    filename: sanitizedFilename,
                     mimeType: image.mimeType,
                     size: image.size,
-                    path: `attachments/${image.filename}`
+                    path: `attachments/${sanitizedFilename}`
                   });
                 } catch (err) {
-                  console.error(`Failed to save image ${image.filename}:`, err);
+                  console.error(`Failed to save image ${sanitizedFilename}:`, err);
                 }
               } else if (image.path) {
                 // Existing image, keep it

apps/frontend/src/main/ipc-handlers/task/execution-handlers.ts

@@ -10,6 +10,7 @@ import { fileWatcher } from '../../file-watcher';
 import { findTaskAndProject } from './shared';
 import { checkGitStatus } from '../../project-initializer';
 import { initializeClaudeProfileManager, type ClaudeProfileManager } from '../../claude-profile-manager';
+import { taskStateManager } from '../../task-state-manager';
 import {
   getPlanPath,
   persistPlanStatus,
@@ -177,7 +178,42 @@ export function registerTaskExecutionHandlers(
         return;
       }
 
-      console.warn('[TASK_START] Found task:', task.specId, 'status:', task.status, 'subtasks:', task.subtasks.length);
+      console.warn('[TASK_START] Found task:', task.specId, 'status:', task.status, 'reviewReason:', task.reviewReason, 'subtasks:', task.subtasks.length);
+
+      // Immediately mark as started so the UI moves the card to In Progress.
+      // Use XState actor state as source of truth (if actor exists), with task data as fallback.
+      // - plan_review: User approved the plan, send PLAN_APPROVED to transition to coding
+      // - human_review/error: User resuming, send USER_RESUMED
+      // - backlog/other: Fresh start, send PLANNING_STARTED
+      const currentXState = taskStateManager.getCurrentState(taskId);
+      console.warn('[TASK_START] Current XState:', currentXState, '| Task status:', task.status, task.reviewReason);
+
+      if (currentXState === 'plan_review') {
+        // XState says plan_review - send PLAN_APPROVED
+        console.warn('[TASK_START] XState: plan_review -> coding via PLAN_APPROVED');
+        taskStateManager.handleUiEvent(taskId, { type: 'PLAN_APPROVED' }, task, project);
+      } else if (currentXState === 'human_review' || currentXState === 'error') {
+        // XState says human_review or error - send USER_RESUMED
+        console.warn('[TASK_START] XState:', currentXState, '-> coding via USER_RESUMED');
+        taskStateManager.handleUiEvent(taskId, { type: 'USER_RESUMED' }, task, project);
+      } else if (currentXState) {
+        // XState actor exists but in another state (coding, planning, etc.)
+        // This shouldn't happen normally, but handle gracefully
+        console.warn('[TASK_START] XState in unexpected state:', currentXState, '- sending PLANNING_STARTED');
+        taskStateManager.handleUiEvent(taskId, { type: 'PLANNING_STARTED' }, task, project);
+      } else if (task.status === 'human_review' && task.reviewReason === 'plan_review') {
+        // No XState actor - fallback to task data (e.g., after app restart)
+        console.warn('[TASK_START] No XState actor, task data: plan_review -> coding via PLAN_APPROVED');
+        taskStateManager.handleUiEvent(taskId, { type: 'PLAN_APPROVED' }, task, project);
+      } else if (task.status === 'human_review' || task.status === 'error') {
+        // No XState actor - fallback to task data for resuming
+        console.warn('[TASK_START] No XState actor, task data:', task.status, '-> coding via USER_RESUMED');
+        taskStateManager.handleUiEvent(taskId, { type: 'USER_RESUMED' }, task, project);
+      } else {
+        // Fresh start - PLANNING_STARTED transitions from backlog to planning
+        console.warn('[TASK_START] Fresh start via PLANNING_STARTED');
+        taskStateManager.handleUiEvent(taskId, { type: 'PLANNING_STARTED' }, task, project);
+      }
 
       // Start file watcher for this task
       const specsBaseDir = getSpecsDir(project.autoBuildPath);
@@ -252,45 +288,6 @@ export function registerTaskExecutionHandlers(
           }
         );
       }
-
-      // Notify status change IMMEDIATELY (don't wait for file write)
-      // This provides instant UI feedback while file persistence happens in background
-      const ipcSentAt = Date.now();
-      mainWindow.webContents.send(
-        IPC_CHANNELS.TASK_STATUS_CHANGE,
-        taskId,
-        'in_progress'
-      );
-
-      const DEBUG = process.env.DEBUG === 'true';
-      if (DEBUG) {
-        console.log(`[TASK_START] IPC sent immediately for task ${taskId}, deferring file persistence`);
-      }
-
-      // CRITICAL: Persist status to implementation_plan.json to prevent status flip-flop
-      // When getTasks() is called (on refresh), it reads status from the plan file.
-      // Without persisting here, the old status (e.g., 'human_review') would override
-      // the in-memory 'in_progress' status, causing the task to flip back and forth.
-      // Uses shared utility for consistency with agent-events-handlers.ts
-      // NOTE: This is now async and non-blocking for better UI responsiveness
-      const planPath = path.join(specDir, AUTO_BUILD_PATHS.IMPLEMENTATION_PLAN);
-      setImmediate(async () => {
-        const persistStart = Date.now();
-        try {
-          const persisted = await persistPlanStatus(planPath, 'in_progress', project.id);
-          if (persisted) {
-            console.warn('[TASK_START] Updated plan status to: in_progress');
-          }
-          if (DEBUG) {
-            const delay = persistStart - ipcSentAt;
-            const duration = Date.now() - persistStart;
-            console.log(`[TASK_START] File persistence: delayed ${delay}ms after IPC, completed in ${duration}ms`);
-          }
-        } catch (err) {
-          console.error('[TASK_START] Failed to persist plan status:', err);
-        }
-      });
-      // Note: Plan file may not exist yet for new tasks - that's fine (persistPlanStatus handles ENOENT)
     }
   );
 
@@ -298,52 +295,33 @@ export function registerTaskExecutionHandlers(
    * Stop a task
    */
   ipcMain.on(IPC_CHANNELS.TASK_STOP, (_, taskId: string) => {
-    const DEBUG = process.env.DEBUG === 'true';
-
     agentManager.killTask(taskId);
     fileWatcher.unwatch(taskId);
 
-    // Notify status change IMMEDIATELY for instant UI feedback
-    const ipcSentAt = Date.now();
-    const mainWindow = getMainWindow();
-    if (mainWindow) {
-      mainWindow.webContents.send(
-        IPC_CHANNELS.TASK_STATUS_CHANGE,
-        taskId,
-        'backlog'
-      );
-    }
-
-    if (DEBUG) {
-      console.log(`[TASK_STOP] IPC sent immediately for task ${taskId}, deferring file persistence`);
-    }
-
-    // Find task and project to update the plan file (async, non-blocking)
+    // Find task and project to emit USER_STOPPED with plan context
     const { task, project } = findTaskAndProject(taskId);
 
-    if (task && project) {
-      // Persist status to implementation_plan.json to prevent status flip-flop on refresh
-      // Uses shared utility for consistency with agent-events-handlers.ts
-      // NOTE: This is now async and non-blocking for better UI responsiveness
+    if (!task || !project) return;
+
+    let hasPlan = false;
+    try {
       const planPath = getPlanPath(project, task);
-      setImmediate(async () => {
-        const persistStart = Date.now();
-        try {
-          const persisted = await persistPlanStatus(planPath, 'backlog', project.id);
-          if (persisted) {
-            console.warn('[TASK_STOP] Updated plan status to backlog');
-          }
-          if (DEBUG) {
-            const delay = persistStart - ipcSentAt;
-            const duration = Date.now() - persistStart;
-            console.log(`[TASK_STOP] File persistence: delayed ${delay}ms after IPC, completed in ${duration}ms`);
-          }
-        } catch (err) {
-          console.error('[TASK_STOP] Failed to persist plan status:', err);
-        }
-      });
-      // Note: File not found is expected for tasks without a plan file (persistPlanStatus handles ENOENT)
+      const planContent = safeReadFileSync(planPath);
+      if (planContent) {
+        const plan = JSON.parse(planContent);
+        const { totalCount } = checkSubtasksCompletion(plan);
+        hasPlan = totalCount > 0;
+      }
+    } catch {
+      hasPlan = false;
     }
+
+    taskStateManager.handleUiEvent(
+      taskId,
+      { type: 'USER_STOPPED', hasPlan },
+      task,
+      project
+    );
   });
 
   /**
@@ -392,29 +370,12 @@ export function registerTaskExecutionHandlers(
           return { success: false, error: 'Failed to write QA report file' };
         }
 
-        // Notify UI immediately for instant feedback
-        const mainWindow = getMainWindow();
-        if (mainWindow) {
-          mainWindow.webContents.send(
-            IPC_CHANNELS.TASK_STATUS_CHANGE,
-            taskId,
-            'done'
-          );
-        }
-
-        // CRITICAL: Persist 'done' status to implementation_plan.json
-        // Without this, the old status would be shown after page refresh since
-        // getTasks() reads status from the plan file, not from the Zustand store.
-        const planPath = getPlanPath(project, task);
-        try {
-          const persisted = await persistPlanStatus(planPath, 'done', project.id);
-          if (persisted) {
-            console.warn('[TASK_REVIEW] Persisted approved status (done) to implementation_plan.json');
-          }
-        } catch (err) {
-          console.error('[TASK_REVIEW] Failed to persist approved status:', err);
-          // Non-fatal: UI already updated, file persistence is best-effort
-        }
+        taskStateManager.handleUiEvent(
+          taskId,
+          { type: 'MARK_DONE' },
+          task,
+          project
+        );
       } else {
         // Reset and discard all changes from worktree merge in main
         // The worktree still has all changes, so nothing is lost
@@ -536,29 +497,12 @@ export function registerTaskExecutionHandlers(
         console.warn('[TASK_REVIEW] Starting QA process with projectPath:', qaProjectPath);
         agentManager.startQAProcess(taskId, qaProjectPath, task.specId);
 
-        // Notify UI immediately for instant feedback
-        const mainWindow = getMainWindow();
-        if (mainWindow) {
-          mainWindow.webContents.send(
-            IPC_CHANNELS.TASK_STATUS_CHANGE,
-            taskId,
-            'in_progress'
-          );
-        }
-
-        // CRITICAL: Persist 'in_progress' status to implementation_plan.json
-        // Without this, the old status (e.g., 'human_review') would be shown after page refresh
-        // since getTasks() reads status from the plan file, not from the Zustand store.
-        const planPath = getPlanPath(project, task);
-        try {
-          const persisted = await persistPlanStatus(planPath, 'in_progress', project.id);
-          if (persisted) {
-            console.warn('[TASK_REVIEW] Persisted rejected status (in_progress) to implementation_plan.json');
-          }
-        } catch (err) {
-          console.error('[TASK_REVIEW] Failed to persist rejected status:', err);
-          // Non-fatal: UI already updated, file persistence is best-effort
-        }
+        taskStateManager.handleUiEvent(
+          taskId,
+          { type: 'USER_RESUMED' },
+          task,
+          project
+        );
       }
 
       return { success: true };
@@ -699,14 +643,17 @@ export function registerTaskExecutionHandlers(
       const planPath = getPlanPath(project, task);
 
       try {
-        // Use shared utility for thread-safe plan file updates
-        const persisted = await persistPlanStatus(planPath, status, project.id);
+        const handledByMachine = taskStateManager.handleManualStatusChange(taskId, status, task, project);
+        if (!handledByMachine) {
+          // Use shared utility for thread-safe plan file updates (legacy/manual override)
+          const persisted = await persistPlanStatus(planPath, status, project.id);
 
-        if (!persisted) {
-          // If no implementation plan exists yet, create a basic one
-          await createPlanIfNotExists(planPath, task, status);
-          // Invalidate cache after creating new plan
-          projectStore.invalidateTasksCache(project.id);
+          if (!persisted) {
+            // If no implementation plan exists yet, create a basic one
+            await createPlanIfNotExists(planPath, task, status);
+            // Invalidate cache after creating new plan
+            projectStore.invalidateTasksCache(project.id);
+          }
         }
 
         // Auto-stop task when status changes AWAY from 'in_progress' and process IS running
@@ -817,7 +764,8 @@ export function registerTaskExecutionHandlers(
             mainWindow.webContents.send(
               IPC_CHANNELS.TASK_STATUS_CHANGE,
               taskId,
-              'in_progress'
+              'in_progress',
+              project.id
             );
           }
         }
@@ -1191,7 +1139,8 @@ export function registerTaskExecutionHandlers(
           mainWindow.webContents.send(
             IPC_CHANNELS.TASK_STATUS_CHANGE,
             taskId,
-            newStatus
+            newStatus,
+            project.id
           );
         }
 

apps/frontend/src/main/ipc-handlers/task/plan-file-utils.ts

@@ -22,6 +22,7 @@ import { readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { AUTO_BUILD_PATHS, getSpecsDir } from '../../../shared/constants';
 import type { TaskStatus, Project, Task } from '../../../shared/types';
 import { projectStore } from '../../project-store';
+import type { TaskEventPayload } from '../../agent/task-event-schema';
 
 // In-memory locks for plan file operations
 // Key: plan file path, Value: Promise chain for serializing operations
@@ -185,6 +186,160 @@ export function persistPlanStatusSync(planPath: string, status: TaskStatus, proj
   }
 }
 
+/**
+ * Persist lastEvent metadata synchronously.
+ *
+ * WARNING: This bypasses async locking. Use only in sync event handlers where
+ * async isn't practical. Prefer updatePlanFile when possible.
+ */
+export function persistPlanLastEventSync(planPath: string, event: TaskEventPayload): boolean {
+  try {
+    const planContent = readFileSync(planPath, 'utf-8');
+    const plan = JSON.parse(planContent);
+
+    plan.lastEvent = {
+      eventId: event.eventId,
+      sequence: event.sequence,
+      type: event.type,
+      timestamp: event.timestamp
+    };
+    plan.updated_at = new Date().toISOString();
+
+    writeFileSync(planPath, JSON.stringify(plan, null, 2), 'utf-8');
+    return true;
+  } catch (err) {
+    if (isFileNotFoundError(err)) {
+      return false;
+    }
+    console.warn(`[plan-file-utils] Could not persist lastEvent to ${planPath}:`, err);
+    return false;
+  }
+}
+
+/**
+ * Persist task status, reviewReason, XState state, and execution phase synchronously.
+ * The xstateState and executionPhase are used to restore the exact machine state on reload,
+ * distinguishing between e.g. 'planning' vs 'coding' when both have status 'in_progress'.
+ *
+ * If the plan file doesn't exist, creates a minimal plan with the status fields.
+ * This ensures XState state is persisted even during early phases like spec creation.
+ */
+export function persistPlanStatusAndReasonSync(
+  planPath: string,
+  status: TaskStatus,
+  reviewReason?: string,
+  projectId?: string,
+  xstateState?: string,
+  executionPhase?: string
+): boolean {
+  try {
+    let plan: Record<string, unknown>;
+
+    try {
+      const planContent = readFileSync(planPath, 'utf-8');
+      plan = JSON.parse(planContent);
+    } catch (readErr) {
+      if (!isFileNotFoundError(readErr)) {
+        throw readErr;
+      }
+      // File doesn't exist - create a minimal plan with just status fields
+      // The spec runner will populate the full plan later
+      const planDir = path.dirname(planPath);
+      mkdirSync(planDir, { recursive: true });
+      plan = {
+        created_at: new Date().toISOString(),
+        phases: []
+      };
+      console.log(`[plan-file-utils] Creating minimal plan for XState persistence: ${planPath}`);
+    }
+
+    plan.status = status;
+    plan.planStatus = mapStatusToPlanStatus(status);
+    plan.reviewReason = reviewReason;
+    if (xstateState) {
+      plan.xstateState = xstateState;
+    }
+    if (executionPhase) {
+      plan.executionPhase = executionPhase;
+    }
+    plan.updated_at = new Date().toISOString();
+
+    writeFileSync(planPath, JSON.stringify(plan, null, 2), 'utf-8');
+
+    if (projectId) {
+      projectStore.invalidateTasksCache(projectId);
+    }
+
+    return true;
+  } catch (err) {
+    console.warn(`[plan-file-utils] Could not persist status/reason to ${planPath}:`, err);
+    return false;
+  }
+}
+
+/**
+ * Persist execution phase to the plan file synchronously.
+ * This is called when execution progress updates to ensure the phase
+ * is persisted for restoration on app refresh.
+ */
+export function persistPlanPhaseSync(
+  planPath: string,
+  phase: string,
+  projectId?: string
+): boolean {
+  try {
+    let plan: Record<string, unknown>;
+
+    try {
+      const planContent = readFileSync(planPath, 'utf-8');
+      plan = JSON.parse(planContent);
+    } catch (readErr) {
+      if (!isFileNotFoundError(readErr)) {
+        throw readErr;
+      }
+      // File doesn't exist - create minimal plan
+      const planDir = path.dirname(planPath);
+      mkdirSync(planDir, { recursive: true });
+      plan = {
+        created_at: new Date().toISOString(),
+        phases: []
+      };
+    }
+
+    // Store the execution phase for restoration
+    plan.executionPhase = phase;
+
+    // Also update status to match the phase so the card stays in the correct column on refresh
+    // Map execution phase to TaskStatus for column placement
+    const phaseToStatus: Record<string, TaskStatus> = {
+      'planning': 'in_progress',
+      'coding': 'in_progress',
+      'qa_review': 'in_progress',
+      'qa_fixing': 'in_progress',
+      'complete': 'human_review',
+      'failed': 'error'
+    };
+    const mappedStatus = phaseToStatus[phase];
+    if (mappedStatus) {
+      plan.status = mappedStatus;
+      plan.planStatus = mapStatusToPlanStatus(mappedStatus);
+    }
+
+    plan.updated_at = new Date().toISOString();
+
+    writeFileSync(planPath, JSON.stringify(plan, null, 2), 'utf-8');
+
+    if (projectId) {
+      projectStore.invalidateTasksCache(projectId);
+    }
+
+    return true;
+  } catch (err) {
+    console.warn(`[plan-file-utils] Could not persist phase to ${planPath}:`, err);
+    return false;
+  }
+}
+
 /**
  * Read and update the plan file atomically.
  *
@@ -228,11 +383,13 @@ export async function updatePlanFile<T extends Record<string, unknown>>(
  * @param planPath - Path to the implementation_plan.json file
  * @param task - The task to create the plan for
  * @param status - Initial status for the plan
+ * @param xstateState - Optional XState machine state for restoration
  */
 export async function createPlanIfNotExists(
   planPath: string,
   task: Task,
-  status: TaskStatus
+  status: TaskStatus,
+  xstateState?: string
 ): Promise<void> {
   return withPlanLock(planPath, async () => {
     // Try to read the file first - if it exists, do nothing
@@ -246,7 +403,7 @@ export async function createPlanIfNotExists(
       // File doesn't exist, continue to create it
     }
 
-    const plan = {
+    const plan: Record<string, unknown> = {
       feature: task.title,
       description: task.description || '',
       created_at: task.createdAt.toISOString(),
@@ -256,6 +413,11 @@ export async function createPlanIfNotExists(
       phases: []
     };
 
+    // Include xstateState for accurate restoration on reload
+    if (xstateState) {
+      plan.xstateState = xstateState;
+    }
+
     // Ensure directory exists - use try/catch pattern
     const planDir = path.dirname(planPath);
     try {

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

@@ -3,7 +3,7 @@ import { IPC_CHANNELS, AUTO_BUILD_PATHS, DEFAULT_APP_SETTINGS, DEFAULT_FEATURE_M
 import type { IPCResult, WorktreeStatus, WorktreeDiff, WorktreeDiffFile, WorktreeMergeResult, WorktreeDiscardResult, WorktreeListResult, WorktreeListItem, WorktreeCreatePROptions, WorktreeCreatePRResult, SupportedIDE, SupportedTerminal, AppSettings } from '../../../shared/types';
 import path from 'path';
 import { minimatch } from 'minimatch';
-import { existsSync, readdirSync, statSync, readFileSync } from 'fs';
+import { existsSync, readdirSync, statSync, readFileSync, promises as fsPromises } from 'fs';
 import { execSync, execFileSync, spawn, spawnSync, exec, execFile } from 'child_process';
 import { homedir } from 'os';
 import { projectStore } from '../../project-store';
@@ -20,11 +20,68 @@ import {
 } from '../../worktree-paths';
 import { persistPlanStatus, updateTaskMetadataPrUrl } from './plan-file-utils';
 import { getIsolatedGitEnv, detectWorktreeBranch, refreshGitIndex } from '../../utils/git-isolation';
+import { cleanupWorktree } from '../../utils/worktree-cleanup';
 import { killProcessGracefully } from '../../platform';
 import { stripAnsiCodes } from '../../../shared/utils/ansi-sanitizer';
+import { taskStateManager } from '../../task-state-manager';
 
 // Regex pattern for validating git branch names
-const GIT_BRANCH_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9._/-]*[a-zA-Z0-9]$|^[a-zA-Z0-9]$/;
+export const GIT_BRANCH_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9._/-]*[a-zA-Z0-9]$|^[a-zA-Z0-9]$/;
+
+/**
+ * Validates a detected branch name and returns the safe branch to delete.
+ *
+ * Why `auto-claude/` prefix is considered safe:
+ * - All task worktrees use branches named `auto-claude/{specId}`
+ * - This pattern is controlled by Auto-Claude, not user input
+ * - If detected branch matches this pattern, it's a valid task branch
+ * - If it doesn't match (e.g., `main`, `develop`, `feature/xxx`), it's likely
+ *   the main project's branch being incorrectly detected from a corrupted worktree
+ *
+ * Issue #1479: When cleaning up a corrupted worktree, git rev-parse walks up
+ * to the main project and returns its current branch instead of the worktree's branch.
+ * This could cause deletion of the wrong branch.
+ */
+export function validateWorktreeBranch(
+  detectedBranch: string | null,
+  expectedBranch: string
+): { branchToDelete: string; usedFallback: boolean; reason: string } {
+  // If detection failed, use expected pattern
+  if (detectedBranch === null) {
+    return {
+      branchToDelete: expectedBranch,
+      usedFallback: true,
+      reason: 'detection_failed',
+    };
+  }
+
+  // Exact match - ideal case
+  if (detectedBranch === expectedBranch) {
+    return {
+      branchToDelete: detectedBranch,
+      usedFallback: false,
+      reason: 'exact_match',
+    };
+  }
+
+  // Matches auto-claude pattern with valid specId (not just "auto-claude/")
+  // The specId must be non-empty for this to be a valid task branch
+  if (detectedBranch.startsWith('auto-claude/') && detectedBranch.length > 'auto-claude/'.length) {
+    return {
+      branchToDelete: detectedBranch,
+      usedFallback: false,
+      reason: 'pattern_match',
+    };
+  }
+
+  // Detected branch doesn't match expected pattern - use fallback
+  // This is the critical security fix for issue #1479
+  return {
+    branchToDelete: expectedBranch,
+    usedFallback: true,
+    reason: 'invalid_pattern',
+  };
+}
 
 // Maximum PR title length (GitHub's limit is 256 characters)
 const MAX_PR_TITLE_LENGTH = 256;
@@ -1297,6 +1354,12 @@ async function openInTerminal(dirPath: string, terminal: SupportedTerminal, cust
  * This is the branch the task was created from (set by user during task creation)
  */
 function getTaskBaseBranch(specDir: string): string | undefined {
+  // Defensive check for undefined input
+  if (!specDir || typeof specDir !== 'string') {
+    console.error('[getTaskBaseBranch] specDir is undefined or not a string');
+    return undefined;
+  }
+
   try {
     const metadataPath = path.join(specDir, 'task_metadata.json');
     if (existsSync(metadataPath)) {
@@ -1327,6 +1390,16 @@ function getTaskBaseBranch(specDir: string): string | undefined {
  * as the user may be on a feature branch when viewing worktree status.
  */
 function getEffectiveBaseBranch(projectPath: string, specId: string, projectMainBranch?: string): string {
+  // Defensive check for undefined inputs
+  if (!projectPath || typeof projectPath !== 'string') {
+    console.error('[getEffectiveBaseBranch] projectPath is undefined or not a string');
+    return 'main';
+  }
+  if (!specId || typeof specId !== 'string') {
+    console.error('[getEffectiveBaseBranch] specId is undefined or not a string');
+    return 'main';
+  }
+
   // 1. Try task metadata baseBranch
   const specDir = path.join(projectPath, '.auto-claude', 'specs', specId);
   const taskBaseBranch = getTaskBaseBranch(specDir);
@@ -2009,6 +2082,18 @@ export function registerWorktreeHandlers(
               debug('TIMEOUT: Merge process exceeded', MERGE_TIMEOUT_MS, 'ms, killing...');
               resolved = true;
 
+              // Send timeout error progress event to the renderer
+              const mainWindow = getMainWindow();
+              if (mainWindow) {
+                mainWindow.webContents.send(IPC_CHANNELS.TASK_MERGE_PROGRESS, taskId, {
+                  type: 'progress',
+                  stage: 'error',
+                  percent: 0,
+                  message: 'Merge process timed out after 10 minutes',
+                  details: {}
+                });
+              }
+
               // Platform-specific process termination with fallback
               killProcessGracefully(mergeProcess, {
                 debugPrefix: '[MERGE]',
@@ -2042,10 +2127,47 @@ export function registerWorktreeHandlers(
             }
           }, MERGE_TIMEOUT_MS);
 
+          let lineBuffer = ''; // Buffer for partial JSON lines spanning data chunks
+
           mergeProcess.stdout.on('data', (data: Buffer) => {
             const chunk = data.toString('utf-8');
-            stdout += chunk;
             debug('STDOUT:', chunk);
+
+            // Prepend any buffered partial line from previous chunk
+            const combined = lineBuffer + chunk;
+            const lines = combined.split('\n');
+
+            // Last element may be a partial line - buffer it for next chunk
+            lineBuffer = lines.pop() || '';
+
+            for (const line of lines) {
+              const trimmed = line.trim();
+              if (!trimmed) continue;
+
+              try {
+                const parsed = JSON.parse(trimmed);
+                // Validate parsed object has expected MergeProgress structure before forwarding
+                if (
+                  parsed &&
+                  parsed.type === 'progress' &&
+                  typeof parsed.stage === 'string' &&
+                  typeof parsed.percent === 'number' &&
+                  typeof parsed.message === 'string'
+                ) {
+                  const mainWindow = getMainWindow();
+                  if (mainWindow) {
+                    mainWindow.webContents.send(IPC_CHANNELS.TASK_MERGE_PROGRESS, taskId, parsed);
+                  }
+                  // Don't accumulate progress lines in stdout - they are not part of the final result
+                  continue;
+                }
+              } catch {
+                // Not valid JSON - treat as regular output
+              }
+
+              // Accumulate non-progress lines for final result parsing
+              stdout += line + '\n';
+            }
           });
 
           mergeProcess.stderr.on('data', (data: Buffer) => {
@@ -2060,6 +2182,24 @@ export function registerWorktreeHandlers(
             resolved = true;
             if (timeoutId) clearTimeout(timeoutId);
 
+            // Flush any remaining buffered line
+            if (lineBuffer.trim()) {
+              try {
+                const parsed = JSON.parse(lineBuffer.trim());
+                if (parsed && parsed.type === 'progress') {
+                  const mainWindow = getMainWindow();
+                  if (mainWindow) {
+                    mainWindow.webContents.send(IPC_CHANNELS.TASK_MERGE_PROGRESS, taskId, parsed);
+                  }
+                } else {
+                  stdout += lineBuffer;
+                }
+              } catch {
+                stdout += lineBuffer;
+              }
+              lineBuffer = '';
+            }
+
             debug('Process exited with code:', code, 'signal:', signal);
             debug('Full stdout:', stdout);
             debug('Full stderr:', stderr);
@@ -2164,33 +2304,36 @@ export function registerWorktreeHandlers(
 
                 // Clean up worktree after successful full merge (fixes #243)
                 // This allows drag-to-Done workflow since TASK_UPDATE_STATUS blocks 'done' when worktree exists
-                try {
-                  if (worktreePath && existsSync(worktreePath)) {
-                    execFileSync(getToolPath('git'), ['worktree', 'remove', '--force', worktreePath], {
-                      cwd: project.path,
-                      encoding: 'utf-8'
-                    });
-                    debug('Worktree cleaned up after full merge:', worktreePath);
+                // Uses shared cleanup utility for robust Windows support (fixes #1539)
+                if (worktreePath && existsSync(worktreePath)) {
+                  const cleanupResult = await cleanupWorktree({
+                    worktreePath,
+                    projectPath: project.path,
+                    specId: task.specId,
+                    commitMessage: 'Auto-save before merge cleanup',
+                    logPrefix: '[TASK_WORKTREE_MERGE]',
+                    deleteBranch: true
+                  });
 
-                    // Also delete the task branch since we merged successfully
-                    const taskBranch = `auto-claude/${task.specId}`;
-                    try {
-                      execFileSync(getToolPath('git'), ['branch', '-D', taskBranch], {
-                        cwd: project.path,
-                        encoding: 'utf-8'
-                      });
-                      debug('Task branch deleted:', taskBranch);
-                    } catch {
-                      // Branch might not exist or already deleted
+                  if (cleanupResult.success) {
+                    debug('Worktree cleaned up after full merge:', worktreePath);
+                    if (cleanupResult.branch) {
+                      debug('Task branch deleted:', cleanupResult.branch);
                     }
+                  } else {
+                    debug('Worktree cleanup failed (non-fatal):', cleanupResult.warnings);
+                    // Non-fatal - merge succeeded, cleanup can be done manually
+                  }
+
+                  // Log any warnings for debugging
+                  if (cleanupResult.warnings.length > 0) {
+                    debug('Cleanup warnings:', cleanupResult.warnings);
                   }
-                } catch (cleanupErr) {
-                  debug('Worktree cleanup failed (non-fatal):', cleanupErr);
-                  // Non-fatal - merge succeeded, cleanup can be done manually
                 }
               }
 
               debug('Merge result. isStageOnly:', isStageOnly, 'newStatus:', newStatus, 'staged:', staged);
+              const reviewReason = newStatus === 'human_review' ? 'completed' : undefined;
 
               // Read suggested commit message if staging succeeded
               // OPTIMIZATION: Use async I/O to prevent blocking
@@ -2238,6 +2381,7 @@ export function registerWorktreeHandlers(
                       const plan = JSON.parse(planContent);
                       plan.status = newStatus;
                       plan.planStatus = planStatus;
+                      plan.reviewReason = reviewReason;
                       plan.updated_at = new Date().toISOString();
                       if (staged) {
                         plan.stagedAt = new Date().toISOString();
@@ -2296,10 +2440,8 @@ export function registerWorktreeHandlers(
                 // Non-fatal: UI will still update, but status may not persist across refresh
               }
 
-              const mainWindow = getMainWindow();
-              if (mainWindow) {
-                mainWindow.webContents.send(IPC_CHANNELS.TASK_STATUS_CHANGE, taskId, newStatus);
-              }
+              // Route status change through TaskStateManager (XState) to avoid dual emission
+              taskStateManager.handleManualStatusChange(taskId, newStatus as any, task, project);
 
               resolve({
                 success: true,
@@ -2353,6 +2495,19 @@ export function registerWorktreeHandlers(
             resolved = true;
             if (timeoutId) clearTimeout(timeoutId);
             console.error('[MERGE] Process spawn error:', err);
+
+            // Send error progress event to the renderer
+            const mainWindow = getMainWindow();
+            if (mainWindow) {
+              mainWindow.webContents.send(IPC_CHANNELS.TASK_MERGE_PROGRESS, taskId, {
+                type: 'progress',
+                stage: 'error',
+                percent: 0,
+                message: `Merge process crashed: ${err.message}`,
+                details: {}
+              });
+            }
+
             resolve({
               success: false,
               error: `Failed to run merge: ${err.message}`
@@ -2566,6 +2721,10 @@ export function registerWorktreeHandlers(
   /**
    * Discard the worktree changes
    * Per-spec architecture: Each spec has its own worktree at .auto-claude/worktrees/tasks/{spec-name}/
+   *
+   * Note: Uses the shared cleanupWorktree utility which handles Windows-specific issues
+   * where `git worktree remove --force` fails when the directory contains untracked files.
+   * See: https://github.com/AndyMik90/Auto-Claude/issues/1539
    */
   ipcMain.handle(
     IPC_CHANNELS.TASK_WORKTREE_DISCARD,
@@ -2589,64 +2748,47 @@ export function registerWorktreeHandlers(
           };
         }
 
-        try {
-          // Get the branch name before removing
-          // Use shared utility to validate detected branch matches expected pattern
-          // This prevents deleting wrong branch when worktree is corrupted/orphaned
-          const { branch, usingFallback } = detectWorktreeBranch(
-            worktreePath,
-            task.specId,
-            { timeout: 30000, logPrefix: '[TASK_WORKTREE_DISCARD]' }
-          );
+        // Use the shared cleanup utility for robust, cross-platform worktree deletion
+        const cleanupResult = await cleanupWorktree({
+          worktreePath,
+          projectPath: project.path,
+          specId: task.specId,
+          commitMessage: 'Auto-save before discard',
+          logPrefix: '[TASK_WORKTREE_DISCARD]',
+          deleteBranch: true
+        });
 
-          // Remove the worktree
-          execFileSync(getToolPath('git'), ['worktree', 'remove', '--force', worktreePath], {
-            cwd: project.path,
-            encoding: 'utf-8',
-            env: getIsolatedGitEnv(),
-            timeout: 30000
-          });
-
-          // Delete the branch
-          try {
-            execFileSync(getToolPath('git'), ['branch', '-D', branch], {
-              cwd: project.path,
-              encoding: 'utf-8',
-              env: getIsolatedGitEnv(),
-              timeout: 30000
-            });
-          } catch (branchDeleteError) {
-            // Branch might already be deleted or not exist
-            if (usingFallback) {
-              console.warn(`[TASK_WORKTREE_DISCARD] Could not delete branch ${branch} using fallback pattern. Actual branch may still exist and need manual cleanup.`, branchDeleteError);
-            } else {
-              console.warn(`[TASK_WORKTREE_DISCARD] Could not delete branch ${branch} (may not exist or be checked out elsewhere)`, branchDeleteError);
-            }
-          }
-
-          // Only send status change to backlog if not skipped
-          // (skip when caller will set a different status, e.g., 'done')
-          if (!skipStatusChange) {
-            const mainWindow = getMainWindow();
-            if (mainWindow) {
-              mainWindow.webContents.send(IPC_CHANNELS.TASK_STATUS_CHANGE, taskId, 'backlog');
-            }
-          }
-
-          return {
-            success: true,
-            data: {
-              success: true,
-              message: 'Worktree discarded successfully'
-            }
-          };
-        } catch (gitError) {
-          console.error('Git error discarding worktree:', gitError);
+        if (!cleanupResult.success) {
+          console.error('[TASK_WORKTREE_DISCARD] Cleanup failed:', cleanupResult.warnings);
           return {
             success: false,
-            error: `Failed to discard worktree: ${gitError instanceof Error ? gitError.message : 'Unknown error'}`
+            error: `Failed to discard worktree: ${cleanupResult.warnings.join('; ')}`
           };
         }
+
+        // Log any non-fatal warnings
+        if (cleanupResult.warnings.length > 0) {
+          console.warn('[TASK_WORKTREE_DISCARD] Cleanup warnings:', cleanupResult.warnings);
+        }
+        if (cleanupResult.autoCommitted) {
+          console.warn('[TASK_WORKTREE_DISCARD] Auto-committed uncommitted work before discard');
+        }
+
+
+        // Only send status change to backlog if not skipped
+        // (skip when caller will set a different status, e.g., 'done')
+        if (!skipStatusChange) {
+          // Route through TaskStateManager (XState) to avoid dual emission
+          taskStateManager.handleManualStatusChange(taskId, 'backlog', task, project);
+        }
+
+        return {
+          success: true,
+          data: {
+            success: true,
+            message: 'Worktree discarded successfully'
+          }
+        };
       } catch (error) {
         console.error('Failed to discard worktree:', error);
         return {
@@ -2657,154 +2799,232 @@ export function registerWorktreeHandlers(
     }
   );
 
+  // Promisified execFile for async git operations
+  const execFileAsync = promisify(execFile);
+
   /**
-   * List all spec worktrees for a project
-   * Per-spec architecture: Each spec has its own worktree at .auto-claude/worktrees/tasks/{spec-name}/
-   *
-   * Options:
-   * - includeStats: When true, fetches commit count, files changed, additions, deletions per worktree.
-   *   When false (default), only fetches branch and base branch info for faster listing.
+   * Discard an orphaned worktree by spec name (no task association required)
+   * Used when the worktree exists but the task is missing or git state is corrupted
    */
   ipcMain.handle(
-    IPC_CHANNELS.TASK_LIST_WORKTREES,
-    async (_, projectId: string, options?: { includeStats?: boolean }): Promise<IPCResult<WorktreeListResult>> => {
+    IPC_CHANNELS.TASK_WORKTREE_DISCARD_ORPHAN,
+    async (_, projectId: string, specName: string): Promise<IPCResult<WorktreeDiscardResult>> => {
       try {
+        // Validate inputs
+        if (!projectId || typeof projectId !== 'string') {
+          console.error('discardOrphanedWorktree: Invalid projectId:', projectId);
+          return { success: false, error: 'Invalid projectId' };
+        }
+        if (!specName || typeof specName !== 'string') {
+          console.error('discardOrphanedWorktree: Invalid specName:', specName);
+          return { success: false, error: 'Invalid specName' };
+        }
+
         const project = projectStore.getProject(projectId);
         if (!project) {
           return { success: false, error: 'Project not found' };
         }
 
-        const includeStats = options?.includeStats ?? false;
-        const worktreesDir = getTaskWorktreeDir(project.path);
-        const gitPath = getToolPath('git');
-
-        // Detect the project's default branch once (main/master) instead of per-worktree
-        let projectDefaultBranch: string | undefined;
-        if (!project.settings?.mainBranch || !GIT_BRANCH_REGEX.test(project.settings.mainBranch)) {
-          for (const branch of ['main', 'master']) {
-            try {
-              await execFileAsync(gitPath, ['rev-parse', '--verify', branch], {
-                cwd: project.path,
-                encoding: 'utf-8',
-              });
-              projectDefaultBranch = branch;
-              break;
-            } catch {
-              // Branch doesn't exist, try next
-            }
-          }
-          if (!projectDefaultBranch) {
-            projectDefaultBranch = 'main'; // fallback
-          }
+        // Validate project.path
+        if (!project.path || typeof project.path !== 'string') {
+          console.error('discardOrphanedWorktree: Project path is invalid:', project.path);
+          return { success: false, error: 'Project path is invalid' };
         }
 
-        // Helper to get effective base branch using cached project default
-        const getBaseBranchForEntry = (entry: string): string => {
-          // 1. Try task metadata baseBranch
-          const specDir = path.join(project.path, '.auto-claude', 'specs', entry);
-          const taskBaseBranch = getTaskBaseBranch(specDir);
-          if (taskBaseBranch) return taskBaseBranch;
+        // Find worktree at .auto-claude/worktrees/tasks/{spec-name}/
+        const worktreePath = findTaskWorktree(project.path, specName);
 
-          // 2. Try project settings mainBranch
-          if (project.settings?.mainBranch && GIT_BRANCH_REGEX.test(project.settings.mainBranch)) {
-            return project.settings.mainBranch;
+        if (!worktreePath) {
+          return {
+            success: true,
+            data: {
+              success: true,
+              message: 'No worktree to discard'
+            }
+          };
+        }
+
+        // Use cleanupWorktree which auto-commits any uncommitted changes before deletion
+        // This preserves work in git history (recoverable via reflog for ~90 days)
+        const cleanupResult = await cleanupWorktree({
+          worktreePath,
+          projectPath: project.path,
+          specId: specName,
+          commitMessage: 'Auto-save before orphaned worktree deletion',
+          logPrefix: '[ORPHAN_CLEANUP]',
+          deleteBranch: true
+        });
+
+        if (!cleanupResult.success) {
+          return {
+            success: false,
+            error: cleanupResult.warnings.join(', ') || 'Failed to cleanup orphaned worktree'
+          };
+        }
+
+        return {
+          success: true,
+          data: {
+            success: true,
+            message: cleanupResult.autoCommitted
+              ? 'Orphaned worktree deleted (uncommitted changes were auto-saved)'
+              : 'Orphaned worktree deleted successfully'
           }
-
-          // 3. Use pre-detected project default branch
-          return projectDefaultBranch || 'main';
         };
+      } catch (error) {
+        console.error('Failed to discard orphaned worktree:', error);
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Failed to discard orphaned worktree'
+        };
+      }
+    }
+  );
 
-        // Async helper to process a single worktree entry
-        const processWorktreeEntryAsync = async (entry: string, entryPath: string): Promise<WorktreeListItem | null> => {
+  /**
+   * List all spec worktrees for a project
+   * Per-spec architecture: Each spec has its own worktree at .auto-claude/worktrees/tasks/{spec-name}/
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.TASK_LIST_WORKTREES,
+    async (_, projectId: string): Promise<IPCResult<WorktreeListResult>> => {
+      try {
+        // Validate projectId
+        if (!projectId || typeof projectId !== 'string') {
+          console.error('listWorktrees: Invalid projectId:', projectId);
+          return { success: false, error: 'Invalid projectId' };
+        }
+
+        const project = projectStore.getProject(projectId);
+        if (!project) {
+          return { success: false, error: 'Project not found' };
+        }
+
+// Validate project.path
+        if (!project.path || typeof project.path !== 'string') {
+          console.error('listWorktrees: Project path is invalid:', project.path);
+          return { success: false, error: 'Project path is invalid' };
+        }
+
+        const worktreesDir = getTaskWorktreeDir(project.path);
+
+        // Fetch tasks once before iterating (avoids repeated lookups per entry)
+        // Used for orphan detection - worktrees without a matching task are orphaned
+        const tasks = projectStore.getTasks(projectId);
+        // Track if task lookup was successful (empty array with existing specs dir = lookup failed)
+        const mainSpecsDir = path.join(project.path, '.auto-claude', 'specs');
+        const taskLookupSuccessful = tasks.length > 0 || !existsSync(mainSpecsDir);
+
+        // Helper to process a single worktree entry (async)
+        const processWorktreeEntry = async (entry: string, entryPath: string): Promise<WorktreeListItem | null> => {
           try {
-            // Get branch info (always needed)
-            const { stdout: branchOutput } = await execFileAsync(gitPath, ['rev-parse', '--abbrev-ref', 'HEAD'], {
+            // Get branch info (async)
+            const branchResult = await execFileAsync(getToolPath('git'), ['rev-parse', '--abbrev-ref', 'HEAD'], {
               cwd: entryPath,
               encoding: 'utf-8'
             });
-            const branch = branchOutput.trim();
+            const branch = (branchResult.stdout as string).trim();
 
-            const baseBranch = getBaseBranchForEntry(entry);
+            // Get base branch using proper fallback chain:
+            // 1. Task metadata baseBranch, 2. Project settings mainBranch, 3. main/master detection
+            // Note: We do NOT use current HEAD as that may be a feature branch
+            const baseBranch = getEffectiveBaseBranch(project.path, entry, project.settings?.mainBranch);
 
-            const item: WorktreeListItem = {
+// Get commit count (async, cross-platform - no shell syntax)
+            let commitCount = 0;
+            try {
+              const countResult = await execFileAsync(getToolPath('git'), ['rev-list', '--count', `${baseBranch}..HEAD`], {
+                cwd: entryPath,
+                encoding: 'utf-8'
+              });
+              commitCount = parseInt((countResult.stdout as string).trim(), 10) || 0;
+            } catch {
+              commitCount = 0;
+            }
+
+            // Get diff stats (async, cross-platform - no shell syntax)
+            let filesChanged = 0;
+            let additions = 0;
+            let deletions = 0;
+
+            try {
+              const diffResult = await execFileAsync(getToolPath('git'), ['diff', '--shortstat', `${baseBranch}...HEAD`], {
+                cwd: entryPath,
+                encoding: 'utf-8'
+              });
+              const diffStat = (diffResult.stdout as string).trim();
+
+              const filesMatch = diffStat.match(/(\d+) files? changed/);
+              const addMatch = diffStat.match(/(\d+) insertions?/);
+              const delMatch = diffStat.match(/(\d+) deletions?/);
+
+              if (filesMatch) filesChanged = parseInt(filesMatch[1], 10) || 0;
+              if (addMatch) additions = parseInt(addMatch[1], 10) || 0;
+              if (delMatch) deletions = parseInt(delMatch[1], 10) || 0;
+            } catch {
+              // Ignore diff errors
+            }
+
+            // Check if there's a task associated with this worktree
+            // A worktree without a task is considered orphaned (can happen if task was deleted)
+            // Only mark as orphaned if task lookup was successful (avoid false positives)
+            const hasTask = tasks.some(t => t.specId === entry);
+
+            return {
               specName: entry,
               path: entryPath,
               branch,
               baseBranch,
+              commitCount,
+              filesChanged,
+              additions,
+              deletions,
+              isOrphaned: taskLookupSuccessful ? !hasTask : false
             };
-
-            // Only fetch stats when requested
-            if (includeStats) {
-              // Run commit count and diff stats in parallel
-              const [countResult, diffResult] = await Promise.allSettled([
-                execFileAsync(gitPath, ['rev-list', '--count', `${baseBranch}..HEAD`], {
-                  cwd: entryPath,
-                  encoding: 'utf-8',
-                }),
-                execFileAsync(gitPath, ['diff', '--shortstat', `${baseBranch}...HEAD`], {
-                  cwd: entryPath,
-                  encoding: 'utf-8',
-                }),
-              ]);
-
-              if (countResult.status === 'fulfilled') {
-                item.commitCount = parseInt(countResult.value.stdout.trim(), 10) || 0;
-              } else {
-                item.commitCount = 0;
-              }
-
-              if (diffResult.status === 'fulfilled') {
-                const diffStat = diffResult.value.stdout.trim();
-                const filesMatch = diffStat.match(/(\d+) files? changed/);
-                const addMatch = diffStat.match(/(\d+) insertions?/);
-                const delMatch = diffStat.match(/(\d+) deletions?/);
-
-                item.filesChanged = filesMatch ? parseInt(filesMatch[1], 10) || 0 : 0;
-                item.additions = addMatch ? parseInt(addMatch[1], 10) || 0 : 0;
-                item.deletions = delMatch ? parseInt(delMatch[1], 10) || 0 : 0;
-              } else {
-                item.filesChanged = 0;
-                item.additions = 0;
-                item.deletions = 0;
-              }
-            }
-
-            return item;
           } catch (gitError) {
-            console.error(`Error getting info for worktree ${entry}:`, gitError);
-            return null;
+            // FIX: Don't skip worktree if git fails - it may be orphaned/corrupted
+            // Include it so it can be managed (deleted if orphaned)
+            const hasTask = tasks.some(t => t.specId === entry);
+            console.warn(`[Worktree] Git commands failed for ${entry}, hasTask=${hasTask}:`, gitError);
+            // Note: branch is empty - renderer should handle based on isOrphaned flag
+            return {
+              specName: entry,
+              path: entryPath,
+              branch: '',
+              baseBranch: '',
+              commitCount: 0,
+              filesChanged: 0,
+              additions: 0,
+              deletions: 0,
+              isOrphaned: taskLookupSuccessful ? !hasTask : false
+            };
           }
         };
 
-        // Scan worktrees directory and process all entries in parallel
-        let worktrees: WorktreeListItem[] = [];
-        if (existsSync(worktreesDir)) {
-          const entries = readdirSync(worktreesDir);
-          const dirEntries: Array<{ entry: string; entryPath: string }> = [];
-
-          for (const entry of entries) {
-            const entryPath = path.join(worktreesDir, entry);
-            try {
-              const stat = statSync(entryPath);
-              if (stat.isDirectory()) {
-                dirEntries.push({ entry, entryPath });
-              }
-            } catch {
-              // Skip entries that can't be stat'd
-            }
-          }
-
-          // Process all worktrees in parallel
-          const results = await Promise.allSettled(
-            dirEntries.map(({ entry, entryPath }) => processWorktreeEntryAsync(entry, entryPath))
-          );
-
-          worktrees = results
-            .filter((r): r is PromiseFulfilledResult<WorktreeListItem | null> => r.status === 'fulfilled')
-            .map(r => r.value)
-            .filter((item): item is WorktreeListItem => item !== null);
+        // Scan worktrees directory (async)
+        if (!existsSync(worktreesDir)) {
+          return { success: true, data: { worktrees: [] } };
         }
 
+        const entries = await fsPromises.readdir(worktreesDir);
+
+        // Process all worktrees in parallel for better performance
+        const worktreePromises = entries.map(async (entry) => {
+          const entryPath = path.join(worktreesDir, entry);
+          try {
+            const stat = await fsPromises.stat(entryPath);
+            if (stat.isDirectory()) {
+              return processWorktreeEntry(entry, entryPath);
+            }
+          } catch {
+            // Skip entries that can't be stat'd
+          }
+          return null;
+        });
+
+        const results = await Promise.all(worktreePromises);
+        const worktrees = results.filter((w): w is WorktreeListItem => w !== null);
+
         return { success: true, data: { worktrees } };
       } catch (error) {
         console.error('Failed to list worktrees:', error);

apps/frontend/src/main/project-store.ts

@@ -2,7 +2,7 @@ import { app } from 'electron';
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, Dirent } from 'fs';
 import path from 'path';
 import { v4 as uuidv4 } from 'uuid';
-import type { Project, ProjectSettings, Task, TaskStatus, TaskMetadata, ImplementationPlan, ReviewReason, PlanSubtask } from '../shared/types';
+import type { Project, ProjectSettings, Task, TaskStatus, TaskMetadata, ImplementationPlan, ReviewReason, PlanSubtask, KanbanPreferences, ExecutionPhase } from '../shared/types';
 import { DEFAULT_PROJECT_SETTINGS, AUTO_BUILD_PATHS, getSpecsDir, JSON_ERROR_PREFIX, JSON_ERROR_TITLE_SUFFIX } from '../shared/constants';
 import { getAutoBuildPath, isInitialized } from './project-initializer';
 import { getTaskWorktreeDir } from './worktree-paths';
@@ -18,6 +18,7 @@ interface StoreData {
   projects: Project[];
   settings: Record<string, unknown>;
   tabState?: TabState;
+  kanbanPreferences?: Record<string, KanbanPreferences>;
 }
 
 interface TasksCacheEntry {
@@ -137,6 +138,10 @@ export class ProjectStore {
     const index = this.data.projects.findIndex((p) => p.id === projectId);
     if (index !== -1) {
       this.data.projects.splice(index, 1);
+      // Clean up kanban preferences to avoid orphaned data
+      if (this.data.kanbanPreferences?.[projectId]) {
+        delete this.data.kanbanPreferences[projectId];
+      }
       this.save();
       return true;
     }
@@ -177,6 +182,24 @@ export class ProjectStore {
     this.save();
   }
 
+  /**
+   * Get kanban column preferences for a specific project
+   */
+  getKanbanPreferences(projectId: string): KanbanPreferences | null {
+    return this.data.kanbanPreferences?.[projectId] ?? null;
+  }
+
+  /**
+   * Save kanban column preferences for a specific project
+   */
+  saveKanbanPreferences(projectId: string, preferences: KanbanPreferences): void {
+    if (!this.data.kanbanPreferences) {
+      this.data.kanbanPreferences = {};
+    }
+    this.data.kanbanPreferences[projectId] = preferences;
+    this.save();
+  }
+
   /**
    * Validate all projects to ensure their .auto-claude folders still exist.
    * If a project has autoBuildPath set but the folder was deleted,
@@ -438,7 +461,7 @@ export class ProjectStore {
         // Tasks with JSON errors go to human_review with errors reason
         const { status: finalStatus, reviewReason: finalReviewReason } = hasJsonError
           ? { status: 'human_review' as TaskStatus, reviewReason: 'errors' as ReviewReason }
-          : this.determineTaskStatusAndReason(plan, specPath, metadata);
+          : this.determineTaskStatusAndReason(plan);
 
         // Extract subtasks from plan (handle both 'subtasks' and 'chunks' naming)
         const subtasks = plan?.phases?.flatMap((phase) => {
@@ -477,6 +500,16 @@ export class ProjectStore {
           }
         }
 
+        // Use persisted executionPhase (from text parser) or xstateState for exact restoration
+        // Priority: executionPhase > xstateState > inferred from status
+        const persistedPhase = (plan as { executionPhase?: string } | null)?.executionPhase as ExecutionPhase | undefined;
+        const xstateState = (plan as { xstateState?: string } | null)?.xstateState;
+        const executionProgress = persistedPhase
+          ? { phase: persistedPhase, phaseProgress: 50, overallProgress: 50 }
+          : xstateState
+            ? this.inferExecutionProgressFromXState(xstateState)
+            : this.inferExecutionProgress(plan?.status);
+
         tasks.push({
           id: dir.name, // Use spec directory name as ID
           specId: dir.name,
@@ -488,6 +521,7 @@ export class ProjectStore {
           logs: [],
           metadata,
           ...(finalReviewReason !== undefined && { reviewReason: finalReviewReason }),
+          ...(executionProgress && { executionProgress }),
           stagedInMainProject,
           stagedAt,
           location, // Add location metadata (main vs worktree)
@@ -505,30 +539,19 @@ export class ProjectStore {
   }
 
   /**
-   * Determine task status and review reason based on plan and files.
+   * Determine task status and review reason from the plan file.
    *
-   * PRIORITY ORDER (to prevent status flip-flop during execution):
-   * 1. Terminal statuses (done, pr_created, error) - ALWAYS respected
-   * 2. Active process statuses (planning, coding, in_progress) - respected during execution
-   * 3. Explicit human_review with reviewReason - respected to prevent recalculation
-   * 4. QA report file status
-   * 5. Calculated status from subtask analysis (fallback only)
-   *
-   * Review reasons:
-   * - 'completed': All subtasks done, QA passed - ready for merge
-   * - 'errors': Subtasks failed during execution - needs attention
-   * - 'qa_rejected': QA found issues that need fixing
-   * - 'plan_review': Spec creation complete, awaiting user approval
+   * With the XState refactor, status and reviewReason are authoritative fields
+   * written by the TaskStateManager. The renderer should not recompute status
+   * from subtasks or QA files.
    */
   private determineTaskStatusAndReason(
-    plan: ImplementationPlan | null,
-    specPath: string,
-    metadata?: TaskMetadata
+    plan: ImplementationPlan | null
   ): { status: TaskStatus; reviewReason?: ReviewReason } {
-    // Handle both 'subtasks' and 'chunks' naming conventions, filter out undefined
-    const allSubtasks = plan?.phases?.flatMap((p) => p.subtasks || (p as { chunks?: PlanSubtask[] }).chunks || []).filter(Boolean) || [];
+    if (!plan?.status) {
+      return { status: 'backlog' };
+    }
 
-    // Status mapping from plan.status values to TaskStatus
     const statusMap: Record<string, TaskStatus> = {
       'pending': 'backlog',
       'planning': 'in_progress',
@@ -541,120 +564,82 @@ export class ProjectStore {
       'ai_review': 'ai_review',
       'pr_created': 'pr_created',
       'backlog': 'backlog',
-      'error': 'error'
+      'error': 'error',
+      'queue': 'queue',
+      'queued': 'queue'
     };
 
-    // Terminal statuses that should NEVER be overridden by calculation
-    const TERMINAL_STATUSES = new Set<TaskStatus>(['done', 'pr_created', 'error']);
+    const storedStatus = statusMap[plan.status] || 'backlog';
+    const reviewReason = storedStatus === 'human_review' ? plan.reviewReason : undefined;
 
-    // ========================================================================
-    // STEP 1: Check for terminal statuses (highest priority - always respected)
-    // ========================================================================
-    if (plan?.status) {
-      const storedStatus = statusMap[plan.status];
-      if (storedStatus && TERMINAL_STATUSES.has(storedStatus)) {
-        return { status: storedStatus };
-      }
-    }
+    return { status: storedStatus, reviewReason };
+  }
 
-    // ========================================================================
-    // STEP 2: Check for active process statuses during execution
-    // These prevent status flip-flop while backend is actively running
-    // ========================================================================
-    if (plan?.status) {
-      const storedStatus = statusMap[plan.status];
-      const rawStatus = plan.status as string;
-      const isActiveProcessStatus = rawStatus === 'planning' || rawStatus === 'coding' || rawStatus === 'in_progress';
+  /**
+   * Infer execution progress from plan status for XState snapshot restoration.
+   * Maps plan status values to ExecutionPhase so buildSnapshotFromTask can
+   * correctly determine the XState state (planning vs coding vs qa_review, etc.).
+   */
+  private inferExecutionProgress(planStatus: string | undefined): { phase: ExecutionPhase; phaseProgress: number; overallProgress: number } | undefined {
+    if (!planStatus) return undefined;
 
-      // Check if this is a plan review stage (spec creation complete, awaiting approval)
-      const isPlanReviewStage = (plan as unknown as { planStatus?: string })?.planStatus === 'review';
+    // Map plan status to execution phase
+    const phaseMap: Record<string, ExecutionPhase> = {
+      'pending': 'idle',
+      'backlog': 'idle',
+      'queue': 'idle',
+      'queued': 'idle',
+      'planning': 'planning',
+      'coding': 'coding',
+      'in_progress': 'coding', // Default in_progress to coding
+      'review': 'qa_review',
+      'ai_review': 'qa_review',
+      'qa_review': 'qa_review',
+      'qa_fixing': 'qa_fixing',
+      'human_review': 'complete',
+      'completed': 'complete',
+      'done': 'complete',
+      'error': 'failed'
+    };
 
-      // During active execution, respect the stored status to prevent jumping
-      if (isActiveProcessStatus && storedStatus === 'in_progress') {
-        return { status: 'in_progress' };
-      }
+    const phase = phaseMap[planStatus];
+    if (!phase) return undefined;
 
-      // Plan review stage (human approval of spec before coding starts)
-      if (isPlanReviewStage && storedStatus === 'human_review') {
-        return { status: 'human_review', reviewReason: 'plan_review' };
-      }
+    return {
+      phase,
+      phaseProgress: 50,
+      overallProgress: 50
+    };
+  }
 
-      // Explicit human_review status should be preserved unless we have evidence to change it
-      if (storedStatus === 'human_review') {
-        // Infer review reason from subtask/QA state
-        const hasFailedSubtasks = allSubtasks.some((s) => s.status === 'failed');
-        const allCompleted = allSubtasks.length > 0 && allSubtasks.every((s) => s.status === 'completed');
-        let reviewReason: ReviewReason | undefined;
-        if (hasFailedSubtasks) {
-          reviewReason = 'errors';
-        } else if (allCompleted) {
-          reviewReason = 'completed';
-        }
-        return { status: 'human_review', reviewReason };
-      }
+  /**
+   * Infer execution progress from persisted XState state.
+   * This is more precise than inferring from plan status since it uses the exact machine state.
+   */
+  private inferExecutionProgressFromXState(xstateState: string): { phase: ExecutionPhase; phaseProgress: number; overallProgress: number } | undefined {
+    // Map XState state directly to execution phase
+    const phaseMap: Record<string, ExecutionPhase> = {
+      'backlog': 'idle',
+      'planning': 'planning',
+      'plan_review': 'planning',
+      'coding': 'coding',
+      'qa_review': 'qa_review',
+      'qa_fixing': 'qa_fixing',
+      'human_review': 'complete',
+      'error': 'failed',
+      'creating_pr': 'complete',
+      'pr_created': 'complete',
+      'done': 'complete'
+    };
 
-      // Explicit ai_review status should be preserved
-      if (storedStatus === 'ai_review') {
-        return { status: 'ai_review' };
-      }
-    }
+    const phase = phaseMap[xstateState];
+    if (!phase) return undefined;
 
-    // ========================================================================
-    // STEP 3: Check QA report file for status info
-    // ========================================================================
-    const qaReportPath = path.join(specPath, AUTO_BUILD_PATHS.QA_REPORT);
-    if (existsSync(qaReportPath)) {
-      try {
-        const content = readFileSync(qaReportPath, 'utf-8');
-        if (content.includes('REJECTED') || content.includes('FAILED')) {
-          return { status: 'human_review', reviewReason: 'qa_rejected' };
-        }
-        if (content.includes('PASSED') || content.includes('APPROVED')) {
-          // QA passed - if all subtasks done, move to human_review
-          if (allSubtasks.length > 0 && allSubtasks.every((s) => s.status === 'completed')) {
-            return { status: 'human_review', reviewReason: 'completed' };
-          }
-        }
-      } catch {
-        // Ignore read errors
-      }
-    }
-
-    // ========================================================================
-    // STEP 4: Calculate status from subtask analysis (fallback only)
-    // This is the lowest priority - only used when no explicit status is set
-    // ========================================================================
-    let calculatedStatus: TaskStatus = 'backlog';
-    let reviewReason: ReviewReason | undefined;
-
-    if (allSubtasks.length > 0) {
-      const completed = allSubtasks.filter((s) => s.status === 'completed').length;
-      const inProgress = allSubtasks.filter((s) => s.status === 'in_progress').length;
-      const failed = allSubtasks.filter((s) => s.status === 'failed').length;
-
-      if (completed === allSubtasks.length) {
-        // All subtasks completed - check QA status
-        const qaSignoff = (plan as unknown as Record<string, unknown>)?.qa_signoff as { status?: string } | undefined;
-        if (qaSignoff?.status === 'approved') {
-          calculatedStatus = 'human_review';
-          reviewReason = 'completed';
-        } else {
-          // Manual tasks skip AI review and go directly to human review
-          calculatedStatus = metadata?.sourceType === 'manual' ? 'human_review' : 'ai_review';
-          if (metadata?.sourceType === 'manual') {
-            reviewReason = 'completed';
-          }
-        }
-      } else if (failed > 0) {
-        // Some subtasks failed - needs human attention
-        calculatedStatus = 'human_review';
-        reviewReason = 'errors';
-      } else if (inProgress > 0 || completed > 0) {
-        calculatedStatus = 'in_progress';
-      }
-    }
-
-    return { status: calculatedStatus, reviewReason: calculatedStatus === 'human_review' ? reviewReason : undefined };
+    return {
+      phase,
+      phaseProgress: phase === 'complete' ? 100 : 50,
+      overallProgress: phase === 'complete' ? 100 : 50
+    };
   }
 
   /**

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

@@ -26,29 +26,70 @@ const RATE_LIMIT_INDICATORS = [
 /**
  * Patterns that indicate authentication failures
  * These patterns detect when Claude CLI/SDK fails due to missing or invalid auth
+ *
+ * IMPORTANT: These patterns must be specific enough to NOT match on AI response
+ * content that discusses authentication topics (e.g., PRs about auth features).
+ * The patterns should only match actual API error messages.
  */
 const AUTH_FAILURE_PATTERNS = [
-  /authentication\s*(is\s*)?required/i,
-  /not\s*(yet\s*)?authenticated/i,
-  /login\s*(is\s*)?required/i,
-  /oauth\s*token\s*(is\s*)?(invalid|expired|missing)/i,
-  /unauthorized/i,
-  /please\s*(log\s*in|login|authenticate)/i,
-  /invalid\s*(credentials|token|api\s*key)/i,
-  /auth(entication)?\s+(failed|error|failure)/i,
-  /session\s*(expired|invalid)/i,
-  /access\s*denied/i,
-  /permission\s*denied/i,
-  /401\s*unauthorized/i,
-  /credentials\s*(are\s*)?(missing|invalid|expired)/i,
-  // Match "OAuth token has expired" format from Claude API
-  /oauth\s*token\s+has\s+expired/i,
-  // Match Claude API authentication_error type in JSON responses
+  // Match Claude API authentication_error type in JSON responses (most reliable)
   /["']?type["']?\s*:\s*["']?authentication_error["']?/i,
-  // Match plain "API Error: 401" without requiring "unauthorized"
+  // Match plain "API Error: 401" - this is a structured error format
   /API\s*Error:\s*401/i,
-  // Match "Please obtain a new token" message from Claude API
-  /please\s*(obtain|get|refresh)\s*(a\s*)?new\s*token/i
+  // Match "OAuth token has expired" format from Claude API (specific phrasing)
+  /oauth\s*token\s+has\s+expired/i,
+  // Match "Please obtain a new token" or "refresh your existing token" - API specific
+  /please\s+(obtain\s+a\s+new|refresh\s+your)\s+(existing\s+)?token/i,
+  // Match Claude CLI specific auth messages (with context markers)
+  /\[.*\]\s*authentication\s*(is\s*)?required/i,
+  /\[.*\]\s*not\s*(yet\s*)?authenticated/i,
+  /\[.*\]\s*login\s*(is\s*)?required/i,
+  // Match 401 status codes in structured error output
+  /status[:\s]+401/i,
+  /HTTP\s*401/i,
+  // Match specific error prefixes that indicate actual errors (not AI discussion)
+  /Error:\s*.*(?:unauthorized|authentication|invalid\s*token)/i,
+  // Match · Please run /login format from Claude CLI
+  /·\s*Please\s+run\s+\/login/i,
+];
+
+/**
+ * Patterns that indicate billing/credit failures
+ * These patterns detect when Claude API fails due to insufficient credits or billing issues
+ */
+const BILLING_FAILURE_PATTERNS = [
+  // Credit balance patterns
+  /credit\s*balance\s*(is\s+)?(too\s+)?(insufficient|low|empty|zero|exhausted)/i,
+  /insufficient\s*credit(s)?/i,
+  /no\s*(remaining\s*)?credit(s)?/i,
+  /credit(s)?\s*(are\s*)?(exhausted|depleted|used\s*up)/i,
+  /out\s*of\s*credit(s)?/i,
+  /credit\s*limit\s*(reached|exceeded)/i,
+  // Billing error patterns
+  /billing\s*(error|issue|problem|failure)/i,
+  /payment\s*(required|failed|issue|problem)/i,
+  /subscription\s*(expired|inactive|cancelled|canceled)/i,
+  /account\s*(suspended|inactive)\s*(due\s*to\s*billing)?/i,
+  // Usage limit patterns (billing-related, not rate limits)
+  /usage\s*quota\s*(exceeded|reached)/i,
+  /monthly\s*(usage\s*)?(limit|quota)\s*(exceeded|reached)/i,
+  /plan\s*(limit|quota)\s*(exceeded|reached)/i,
+  // API error patterns for billing
+  /["']?type["']?\s*:\s*["']?billing_error["']?/i,
+  /["']?type["']?\s*:\s*["']?insufficient_credits["']?/i,
+  /["']?error["']?\s*:\s*["']?insufficient_credits["']?/i,
+  // extra_usage patterns from Claude API
+  /extra_usage\s*(exceeded|limit|error)?/i,
+  // Match HTTP 402 Payment Required (require context to avoid false positives on "line 402" etc.)
+  /(?:HTTP|status|code|error)\s*:?\s*402\b/i,
+  /\b402\s+payment\s+required/i,
+  /API\s*Error:\s*402/i,
+  // Balance/funds patterns
+  /insufficient\s*(funds|balance)/i,
+  /balance\s*(is\s*)?(zero|empty|insufficient)/i,
+  // Add funds/credits messages
+  /please\s*(add|purchase)\s*(more\s*)?(credits?|funds)/i,
+  /top\s*up\s*(your\s*)?(account|credits|balance)/i
 ];
 
 /**
@@ -88,6 +129,22 @@ export interface AuthFailureDetectionResult {
   originalError?: string;
 }
 
+/**
+ * Result of billing failure detection
+ */
+export interface BillingFailureDetectionResult {
+  /** Whether a billing failure was detected */
+  isBillingFailure: boolean;
+  /** The profile ID that has billing issues (if known) */
+  profileId?: string;
+  /** The type of billing failure detected */
+  failureType?: 'insufficient_credits' | 'payment_required' | 'subscription_inactive' | 'unknown';
+  /** User-friendly message describing the failure */
+  message?: string;
+  /** Original error message from the process output */
+  originalError?: string;
+}
+
 /**
  * Classify rate limit type based on reset time string
  */
@@ -214,6 +271,44 @@ function getAuthFailureMessage(failureType: 'missing' | 'invalid' | 'expired' |
   }
 }
 
+/**
+ * Classify the type of billing failure based on the error message
+ */
+function classifyBillingFailureType(output: string): 'insufficient_credits' | 'payment_required' | 'subscription_inactive' | 'unknown' {
+  const lowerOutput = output.toLowerCase();
+
+  // Check for credit-related failures (including extra_usage which indicates usage exhaustion)
+  if (/credit\s*(balance|s)?|insufficient\s*(credit|funds|balance)|out\s*of\s*credit|no\s*(remaining\s*)?credit|extra_usage/.test(lowerOutput)) {
+    return 'insufficient_credits';
+  }
+  // Check for subscription-related failures
+  if (/subscription\s*(expired|inactive|cancelled|canceled)|account\s*(suspended|inactive)/.test(lowerOutput)) {
+    return 'subscription_inactive';
+  }
+  // Check for payment-related failures
+  if (/payment\s*(required|failed)|402|billing\s*(error|issue|problem|failure)/.test(lowerOutput)) {
+    return 'payment_required';
+  }
+  return 'unknown';
+}
+
+/**
+ * Get a user-friendly message for the billing failure
+ */
+function getBillingFailureMessage(failureType: 'insufficient_credits' | 'payment_required' | 'subscription_inactive' | 'unknown'): string {
+  switch (failureType) {
+    case 'insufficient_credits':
+      return 'Your Claude API credit balance is too low. Please add credits to your account or switch to another profile in Settings > Claude Profiles.';
+    case 'payment_required':
+      return 'A billing error occurred with your Claude API account. Please check your payment method or switch to another profile in Settings > Claude Profiles.';
+    case 'subscription_inactive':
+      return 'Your Claude API subscription is inactive or expired. Please renew your subscription or switch to another profile in Settings > Claude Profiles.';
+    case 'unknown':
+    default:
+      return 'A billing issue was detected with your Claude API account. Please check your account status or switch to another profile in Settings > Claude Profiles.';
+  }
+}
+
 /**
  * Detect authentication failure from output (stdout + stderr combined)
  */
@@ -253,6 +348,48 @@ export function isAuthFailureError(output: string): boolean {
   return detectAuthFailure(output).isAuthFailure;
 }
 
+/**
+ * Detect billing failure from output (stdout + stderr combined)
+ */
+export function detectBillingFailure(
+  output: string,
+  profileId?: string
+): BillingFailureDetectionResult {
+  // First, make sure this isn't a rate limit or auth error (those should be handled separately)
+  if (detectRateLimit(output).isRateLimited) {
+    return { isBillingFailure: false };
+  }
+  if (detectAuthFailure(output).isAuthFailure) {
+    return { isBillingFailure: false };
+  }
+
+  // Check for billing failure patterns
+  for (const pattern of BILLING_FAILURE_PATTERNS) {
+    if (pattern.test(output)) {
+      const profileManager = getClaudeProfileManager();
+      const effectiveProfileId = profileId || profileManager.getActiveProfile().id;
+      const failureType = classifyBillingFailureType(output);
+
+      return {
+        isBillingFailure: true,
+        profileId: effectiveProfileId,
+        failureType,
+        message: getBillingFailureMessage(failureType),
+        originalError: output
+      };
+    }
+  }
+
+  return { isBillingFailure: false };
+}
+
+/**
+ * Check if output contains billing failure error
+ */
+export function isBillingFailureError(output: string): boolean {
+  return detectBillingFailure(output).isBillingFailure;
+}
+
 /**
  * Get environment variables for a specific Claude profile.
  *

apps/frontend/src/main/task-state-manager.ts

@@ -0,0 +1,473 @@
+import { createActor } from 'xstate';
+import type { ActorRefFrom } from 'xstate';
+import type { BrowserWindow } from 'electron';
+import type { TaskEventPayload } from './agent/task-event-schema';
+import type { Project, Task, TaskStatus, ReviewReason, ExecutionPhase } from '../shared/types';
+import { taskMachine, type TaskEvent } from '../shared/state-machines';
+import { IPC_CHANNELS } from '../shared/constants';
+import { safeSendToRenderer } from './ipc-handlers/utils';
+import { getPlanPath, persistPlanStatusAndReasonSync } from './ipc-handlers/task/plan-file-utils';
+import { findTaskWorktree } from './worktree-paths';
+import { getSpecsDir, AUTO_BUILD_PATHS } from '../shared/constants';
+import { existsSync } from 'fs';
+import path from 'path';
+
+type TaskActor = ActorRefFrom<typeof taskMachine>;
+
+/** Maps XState states to execution phases. Shared by mapStateToExecutionPhase and emitPhaseFromState. */
+const XSTATE_TO_PHASE: Record<string, ExecutionPhase> = {
+  'backlog': 'idle',
+  'planning': 'planning',
+  'plan_review': 'planning',
+  'coding': 'coding',
+  'qa_review': 'qa_review',
+  'qa_fixing': 'qa_fixing',
+  'human_review': 'complete',
+  'error': 'failed',
+  'creating_pr': 'complete',
+  'pr_created': 'complete',
+  'done': 'complete'
+};
+
+interface TaskContextEntry {
+  task: Task;
+  project: Project;
+}
+
+const TERMINAL_EVENTS = new Set<string>([
+  'QA_PASSED',
+  'PLANNING_FAILED',
+  'CODING_FAILED',
+  'QA_MAX_ITERATIONS',
+  'QA_AGENT_ERROR',
+  'ALL_SUBTASKS_DONE'
+]);
+
+export class TaskStateManager {
+  private actors = new Map<string, TaskActor>();
+  private lastSequenceByTask = new Map<string, number>();
+  private lastStateByTask = new Map<string, string>();
+  private taskContextById = new Map<string, TaskContextEntry>();
+  private terminalEventSeen = new Set<string>();
+  private getMainWindow: (() => BrowserWindow | null) | null = null;
+
+  configure(getMainWindow: () => BrowserWindow | null): void {
+    this.getMainWindow = getMainWindow;
+  }
+
+  handleTaskEvent(taskId: string, event: TaskEventPayload, task: Task, project: Project): boolean {
+    const lastSeq = this.lastSequenceByTask.get(taskId);
+    console.log(`[TaskStateManager] handleTaskEvent: ${event.type} seq=${event.sequence}, lastSeq=${lastSeq}`);
+
+    if (!this.isNewSequence(taskId, event.sequence)) {
+      console.log(`[TaskStateManager] Event ${event.type} DROPPED - sequence ${event.sequence} not newer than ${lastSeq}`);
+      return false;
+    }
+    this.setTaskContext(taskId, task, project);
+    this.lastSequenceByTask.set(taskId, event.sequence);
+
+    if (TERMINAL_EVENTS.has(event.type)) {
+      this.terminalEventSeen.add(taskId);
+    }
+
+    const actor = this.getOrCreateActor(taskId);
+    const stateBefore = String(actor.getSnapshot().value);
+    console.log(`[TaskStateManager] Sending ${event.type} to actor in state: ${stateBefore}`);
+    actor.send(event as TaskEvent);
+    const stateAfter = String(actor.getSnapshot().value);
+    console.log(`[TaskStateManager] After ${event.type}: state ${stateBefore} -> ${stateAfter}`);
+    return true;
+  }
+
+  handleProcessExited(
+    taskId: string,
+    exitCode: number | null,
+    task?: Task,
+    project?: Project
+  ): void {
+    if (task && project) {
+      this.setTaskContext(taskId, task, project);
+    }
+    if (this.terminalEventSeen.has(taskId)) {
+      return;
+    }
+    const actor = this.getOrCreateActor(taskId);
+    actor.send({
+      type: 'PROCESS_EXITED',
+      exitCode: exitCode ?? -1,
+      unexpected: true
+    } satisfies TaskEvent);
+  }
+
+  handleUiEvent(taskId: string, event: TaskEvent, task: Task, project: Project): void {
+    console.log(`[TaskStateManager] handleUiEvent: ${event.type} for task ${taskId}`);
+    this.setTaskContext(taskId, task, project);
+    const actor = this.getOrCreateActor(taskId);
+    const stateBefore = String(actor.getSnapshot().value);
+    console.log(`[TaskStateManager] Sending UI event ${event.type} to actor in state: ${stateBefore}`);
+    actor.send(event);
+    const stateAfter = String(actor.getSnapshot().value);
+    console.log(`[TaskStateManager] After UI event ${event.type}: state ${stateBefore} -> ${stateAfter}`);
+  }
+
+  handleManualStatusChange(taskId: string, status: TaskStatus, task: Task, project: Project): boolean {
+    switch (status) {
+      case 'done':
+        this.handleUiEvent(taskId, { type: 'MARK_DONE' }, task, project);
+        return true;
+      case 'pr_created':
+        this.handleUiEvent(
+          taskId,
+          { type: 'PR_CREATED', prUrl: task.metadata?.prUrl ?? '' },
+          task,
+          project
+        );
+        return true;
+      case 'in_progress': {
+        // Use XState as source of truth for determining correct event
+        const currentState = this.getCurrentState(taskId);
+        if (currentState === 'plan_review') {
+          this.handleUiEvent(taskId, { type: 'PLAN_APPROVED' }, task, project);
+        } else if (currentState === 'human_review' || currentState === 'error') {
+          this.handleUiEvent(taskId, { type: 'USER_RESUMED' }, task, project);
+        } else if (!currentState && task.reviewReason === 'plan_review') {
+          // Fallback: No actor exists (e.g., after app restart), use task data
+          this.handleUiEvent(taskId, { type: 'PLAN_APPROVED' }, task, project);
+        } else {
+          this.handleUiEvent(taskId, { type: 'USER_RESUMED' }, task, project);
+        }
+        return true;
+      }
+      case 'backlog':
+        this.handleUiEvent(taskId, { type: 'USER_STOPPED', hasPlan: false }, task, project);
+        return true;
+      case 'human_review':
+        // Already in human_review (e.g., stage-only merge keeps task in review).
+        // Emit status directly since there's no XState transition needed.
+        this.emitStatus(taskId, 'human_review', task.reviewReason ?? 'completed', project.id);
+        return true;
+      default:
+        return false;
+    }
+  }
+
+  setLastSequence(taskId: string, sequence: number): void {
+    this.lastSequenceByTask.set(taskId, sequence);
+  }
+
+  getLastSequence(taskId: string): number | undefined {
+    return this.lastSequenceByTask.get(taskId);
+  }
+
+  /**
+   * Get the current XState state for a task.
+   * Returns undefined if no actor exists for the task.
+   */
+  getCurrentState(taskId: string): string | undefined {
+    const actor = this.actors.get(taskId);
+    if (!actor) {
+      return undefined;
+    }
+    return String(actor.getSnapshot().value);
+  }
+
+  /**
+   * Check if the task is currently in plan_review state.
+   * Used by TASK_START to determine correct event to send.
+   */
+  isInPlanReview(taskId: string): boolean {
+    return this.getCurrentState(taskId) === 'plan_review';
+  }
+
+  clearTask(taskId: string): void {
+    this.lastSequenceByTask.delete(taskId);
+    this.lastStateByTask.delete(taskId);
+    this.terminalEventSeen.delete(taskId);
+    this.taskContextById.delete(taskId);
+    const actor = this.actors.get(taskId);
+    if (actor) {
+      actor.stop();
+      this.actors.delete(taskId);
+    }
+  }
+
+  /**
+   * Clear all task state. Called by TASK_LIST handler when forceRefresh is true.
+   * This ensures actors are recreated with fresh task data when the user
+   * triggers a manual refresh from the UI.
+   *
+   * Note: lastSequenceByTask is preserved to prevent duplicate event processing
+   * if backend events arrive during the refresh window. Sequence numbers are
+   * specific to task execution sessions and should remain valid across UI refreshes.
+   */
+  clearAllTasks(): void {
+    for (const [_taskId, actor] of this.actors) {
+      actor.stop();
+    }
+    this.actors.clear();
+    // Preserve lastSequenceByTask to prevent duplicate event processing during refresh
+    // Only clear state that needs to be rebuilt from fresh task data
+    this.lastStateByTask.clear();
+    this.terminalEventSeen.clear();
+    this.taskContextById.clear();
+    console.log('[TaskStateManager] Cleared task actors and state for refresh (preserved sequence tracking)');
+  }
+
+  private setTaskContext(taskId: string, task: Task, project: Project): void {
+    this.taskContextById.set(taskId, { task, project });
+  }
+
+  private getOrCreateActor(taskId: string): TaskActor {
+    const existing = this.actors.get(taskId);
+    if (existing) {
+      console.log(`[TaskStateManager] Using existing actor for ${taskId}, current state:`, String(existing.getSnapshot().value));
+      return existing;
+    }
+
+    const contextEntry = this.taskContextById.get(taskId);
+    const snapshot = contextEntry
+      ? this.buildSnapshotFromTask(contextEntry.task)
+      : undefined;
+
+    if (contextEntry) {
+      console.log(`[TaskStateManager] Creating new actor for ${taskId} from task:`, {
+        status: contextEntry.task.status,
+        reviewReason: contextEntry.task.reviewReason,
+        phase: contextEntry.task.executionProgress?.phase,
+        initialState: snapshot ? String(snapshot.value) : 'default (backlog)'
+      });
+    } else {
+      console.log(`[TaskStateManager] Creating new actor for ${taskId} with default state (no context entry)`);
+    }
+
+    const actor = snapshot
+      ? createActor(taskMachine, { snapshot })
+      : createActor(taskMachine);
+    actor.subscribe((snapshot) => {
+      const stateValue = String(snapshot.value);
+      const lastState = this.lastStateByTask.get(taskId);
+
+      // Debug: Log all state transitions
+      console.log(`[TaskStateManager] XState transition for ${taskId}:`, {
+        from: lastState,
+        to: stateValue,
+        contextReviewReason: snapshot.context.reviewReason
+      });
+
+      if (lastState === stateValue) {
+        return;
+      }
+      this.lastStateByTask.set(taskId, stateValue);
+
+      const contextEntry = this.taskContextById.get(taskId);
+      if (!contextEntry) {
+        console.debug(`[TaskStateManager] No context for task ${taskId} during state transition to ${stateValue} - skipping emit (may occur after clearTask during event processing)`);
+        return;
+      }
+      const { task, project } = contextEntry;
+      const { status, reviewReason } = mapStateToLegacy(
+        stateValue,
+        snapshot.context.reviewReason
+      );
+
+      // Map XState state to execution phase for persistence
+      const executionPhase = this.mapStateToExecutionPhase(stateValue);
+
+      // Debug: Log the mapped status and reviewReason
+      console.log(`[TaskStateManager] Emitting status for ${taskId}:`, {
+        status,
+        reviewReason,
+        xstateState: stateValue,
+        executionPhase,
+        projectId: project.id
+      });
+
+      this.persistStatus(task, project, status, reviewReason, stateValue, executionPhase);
+      this.emitStatus(taskId, status, reviewReason, project.id);
+
+      // Also emit execution progress to sync phase display with column
+      // This ensures crisp transitions - phase and column update together
+      this.emitPhaseFromState(taskId, stateValue, project.id);
+    });
+
+    actor.start();
+    this.actors.set(taskId, actor);
+    return actor;
+  }
+
+  private persistStatus(
+    task: Task,
+    project: Project,
+    status: TaskStatus,
+    reviewReason?: ReviewReason,
+    xstateState?: string,
+    executionPhase?: string
+  ): void {
+    const mainPlanPath = getPlanPath(project, task);
+    persistPlanStatusAndReasonSync(mainPlanPath, status, reviewReason, project.id, xstateState, executionPhase);
+
+    const worktreePath = findTaskWorktree(project.path, task.specId);
+    if (!worktreePath) return;
+
+    const specsBaseDir = getSpecsDir(project.autoBuildPath);
+    const worktreePlanPath = path.join(
+      worktreePath,
+      specsBaseDir,
+      task.specId,
+      AUTO_BUILD_PATHS.IMPLEMENTATION_PLAN
+    );
+    if (existsSync(worktreePlanPath)) {
+      persistPlanStatusAndReasonSync(worktreePlanPath, status, reviewReason, project.id, xstateState, executionPhase);
+    }
+  }
+
+  /**
+   * Map XState state to execution phase string
+   */
+  private mapStateToExecutionPhase(xstateState: string): ExecutionPhase {
+    return XSTATE_TO_PHASE[xstateState] || 'idle';
+  }
+
+  private emitStatus(
+    taskId: string,
+    status: TaskStatus,
+    reviewReason: ReviewReason | undefined,
+    projectId?: string
+  ): void {
+    if (!this.getMainWindow) {
+      console.warn(`[TaskStateManager] emitStatus: No main window, cannot emit status ${status} for ${taskId}`);
+      return;
+    }
+    console.log(`[TaskStateManager] emitStatus: Sending TASK_STATUS_CHANGE for ${taskId}:`, { status, reviewReason, projectId });
+    safeSendToRenderer(
+      this.getMainWindow,
+      IPC_CHANNELS.TASK_STATUS_CHANGE,
+      taskId,
+      status,
+      projectId,
+      reviewReason
+    );
+  }
+
+  /**
+   * Emit execution progress to sync phase display with XState state.
+   * This ensures the card shows the correct phase when XState transitions.
+   */
+  private emitPhaseFromState(
+    taskId: string,
+    xstateState: string,
+    projectId?: string
+  ): void {
+    if (!this.getMainWindow) return;
+
+    const phase = XSTATE_TO_PHASE[xstateState] || 'idle';
+
+    // Emit execution progress with the phase derived from XState
+    safeSendToRenderer(
+      this.getMainWindow,
+      IPC_CHANNELS.TASK_EXECUTION_PROGRESS,
+      taskId,
+      {
+        phase,
+        phaseProgress: phase === 'complete' ? 100 : 50,
+        overallProgress: phase === 'complete' ? 100 : 50,
+        message: `State: ${xstateState}`,
+        sequenceNumber: Date.now()  // Use timestamp as sequence to ensure it's newer
+      },
+      projectId
+    );
+  }
+
+  private isNewSequence(taskId: string, sequence: number): boolean {
+    const last = this.lastSequenceByTask.get(taskId);
+    // Use >= to accept the first event when sequence equals last (e.g., both are 0)
+    // This handles the case where we reload lastSequence from plan file and the next
+    // event has the same sequence number (which shouldn't happen, but we should be lenient)
+    return last === undefined || sequence >= last;
+  }
+
+  private buildSnapshotFromTask(task: Task) {
+    const status = task.status;
+    const reviewReason = task.reviewReason;
+    const executionPhase = task.executionProgress?.phase;
+    let stateValue: string = 'backlog';
+    let contextReviewReason: ReviewReason | undefined;
+
+    switch (status) {
+      case 'in_progress':
+        // Use executionProgress.phase to determine if we're in planning or coding
+        // This is important because both phases have status 'in_progress'
+        if (executionPhase === 'planning') {
+          stateValue = 'planning';
+        } else if (executionPhase === 'qa_review') {
+          stateValue = 'qa_review';
+        } else if (executionPhase === 'qa_fixing') {
+          stateValue = 'qa_fixing';
+        } else {
+          // Default to coding for 'coding', 'complete', or unknown phases
+          stateValue = 'coding';
+        }
+        break;
+      case 'ai_review':
+        stateValue = 'qa_review';
+        break;
+      case 'human_review':
+        stateValue = reviewReason === 'plan_review' ? 'plan_review' : 'human_review';
+        contextReviewReason = reviewReason;
+        break;
+      case 'pr_created':
+        stateValue = 'pr_created';
+        break;
+      case 'done':
+        stateValue = 'done';
+        break;
+      case 'error':
+        stateValue = 'error';
+        contextReviewReason = reviewReason ?? 'errors';
+        break;
+      case 'backlog':
+      default:
+        stateValue = 'backlog';
+        break;
+    }
+
+    return taskMachine.resolveState({
+      value: stateValue,
+      context: {
+        reviewReason: contextReviewReason
+      }
+    });
+  }
+}
+
+export const taskStateManager = new TaskStateManager();
+
+function mapStateToLegacy(
+  state: string,
+  reviewReason?: ReviewReason
+): { status: TaskStatus; reviewReason?: ReviewReason } {
+  switch (state) {
+    case 'backlog':
+      return { status: 'backlog' };
+    case 'planning':
+    case 'coding':
+      return { status: 'in_progress' };
+    case 'plan_review':
+      return { status: 'human_review', reviewReason: 'plan_review' };
+    case 'qa_review':
+    case 'qa_fixing':
+      return { status: 'ai_review' };
+    case 'human_review':
+      return { status: 'human_review', reviewReason };
+    case 'error':
+      return { status: 'human_review', reviewReason: 'errors' };
+    case 'creating_pr':
+      return { status: 'human_review', reviewReason: 'completed' };
+    case 'pr_created':
+      return { status: 'pr_created' };
+    case 'done':
+      return { status: 'done' };
+    default:
+      return { status: 'backlog' };
+  }
+}

apps/frontend/src/main/terminal/pty-daemon-client.ts

@@ -11,6 +11,7 @@ import { fileURLToPath } from 'url';
 import { spawn, ChildProcess } from 'child_process';
 import { app } from 'electron';
 import { isWindows, GRACEFUL_KILL_TIMEOUT_MS } from '../platform';
+import { getIsShuttingDown } from './pty-manager';
 
 // ESM-compatible __dirname
 const __filename = fileURLToPath(import.meta.url);
@@ -69,7 +70,7 @@ class PtyDaemonClient {
    * Connect to daemon, spawning if necessary
    */
   async connect(): Promise<void> {
-    if (this.isShuttingDown) {
+    if (this.shuttingDown) {
       throw new Error('Client is shutting down');
     }
 
@@ -174,7 +175,7 @@ class PtyDaemonClient {
     this.socket.on('close', () => {
       console.warn('[PtyDaemonClient] Disconnected from daemon');
       this.socket = null;
-      if (!this.isShuttingDown) {
+      if (!this.shuttingDown) {
         this.attemptReconnect();
       }
     });
@@ -222,7 +223,7 @@ class PtyDaemonClient {
    * Attempt to reconnect with exponential backoff
    */
   private attemptReconnect(): void {
-    if (this.isShuttingDown) return;
+    if (this.shuttingDown) return;
 
     if (this.reconnectAttempts >= this.maxReconnectAttempts) {
       console.error('[PtyDaemonClient] Max reconnect attempts reached');
@@ -287,10 +288,22 @@ class PtyDaemonClient {
 
   // ===== Public API =====
 
+  /**
+   * Check if shutdown is in progress (either locally or globally via pty-manager)
+   */
+  private get shuttingDown(): boolean {
+    return this.isShuttingDown || getIsShuttingDown();
+  }
+
   /**
    * Create a new PTY in the daemon
    */
   async createPty(config: PtyConfig): Promise<string> {
+    // Guard against spawning new PTY processes after shutdown
+    if (this.shuttingDown) {
+      throw new Error('Cannot create PTY: client is shutting down');
+    }
+
     const response = await this.request<{ type: 'created'; id: string }>({
       type: 'create',
       data: config,
@@ -302,14 +315,24 @@ class PtyDaemonClient {
    * Write data to a PTY
    */
   write(id: string, data: string): void {
-    this.send({ type: 'write', id, data });
+    if (this.shuttingDown) return;
+    try {
+      this.send({ type: 'write', id, data });
+    } catch {
+      // Socket may be closed during teardown
+    }
   }
 
   /**
    * Resize a PTY
    */
   resize(id: string, cols: number, rows: number): void {
-    this.send({ type: 'resize', id, data: { cols, rows } });
+    if (this.shuttingDown) return;
+    try {
+      this.send({ type: 'resize', id, data: { cols, rows } });
+    } catch {
+      // Socket may be closed during teardown
+    }
   }
 
   /**
@@ -441,8 +464,3 @@ class PtyDaemonClient {
 
 // Singleton instance
 export const ptyDaemonClient = new PtyDaemonClient();
-
-// Cleanup on app quit
-app.on('before-quit', () => {
-  ptyDaemonClient.shutdown();
-});

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

@@ -23,6 +23,18 @@ const MAX_BUFFER_SIZE = 100_000;
 // Ring buffer to prevent memory growth
 const RING_BUFFER_MAX_CHUNKS = 1000;
 
+/**
+ * Sanitize an ID for safe logging to prevent log injection attacks.
+ * Uses JSON.stringify which CodeQL recognizes as a sanitizer, then
+ * removes the surrounding quotes for cleaner log output.
+ */
+function sanitizeIdForLog(id: string): string {
+  // JSON.stringify escapes control characters and is recognized by CodeQL
+  // as a sanitizer for log injection. We slice off the quotes for cleaner output.
+  const escaped = JSON.stringify(String(id).slice(0, 100));
+  return escaped.slice(1, -1);
+}
+
 interface ManagedPty {
   id: string;
   process: pty.IPty;
@@ -71,6 +83,7 @@ interface DaemonResponse {
 class PtyDaemon {
   private ptys = new Map<string, ManagedPty>();
   private server: net.Server | null = null;
+  private isShuttingDown = false;
 
   constructor() {
     console.error('[PTY Daemon] Starting...');
@@ -236,6 +249,11 @@ class PtyDaemon {
    * Create a new PTY
    */
   private createPty(config: PtyConfig): string {
+    // Guard against spawning new PTY processes after shutdown has begun
+    if (this.isShuttingDown) {
+      throw new Error('Cannot create PTY: daemon is shutting down');
+    }
+
     const id = `pty-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
 
     try {
@@ -290,7 +308,7 @@ class PtyDaemon {
       });
 
       ptyProcess.onExit(({ exitCode, signal }) => {
-        console.error(`[PTY Daemon] PTY ${id} exited: code=${exitCode}, signal=${signal}`);
+        console.error('[PTY Daemon] PTY exited:', { id: sanitizeIdForLog(id), exitCode, signal });
         managed.isDead = true;
 
         // Notify all subscribers
@@ -302,7 +320,7 @@ class PtyDaemon {
       });
 
       this.ptys.set(id, managed);
-      console.error(`[PTY Daemon] Created PTY ${id} (${config.shell})`);
+      console.error('[PTY Daemon] Created PTY:', { id: sanitizeIdForLog(id), shell: config.shell });
 
       return id;
     } catch (error) {
@@ -322,7 +340,13 @@ class PtyDaemon {
     if (managed.isDead) {
       throw new Error(`PTY ${id} is dead`);
     }
-    managed.process.write(data);
+    try {
+      managed.process.write(data);
+    } catch (error) {
+      // PTY process may have been destroyed during teardown
+      console.error('[PTY Daemon] Error writing to PTY:', sanitizeIdForLog(id), error);
+      managed.isDead = true;
+    }
   }
 
   /**
@@ -334,12 +358,18 @@ class PtyDaemon {
       throw new Error(`PTY ${id} not found`);
     }
     if (managed.isDead) {
-      console.warn(`[PTY Daemon] Cannot resize dead PTY ${id}`);
+      console.warn('[PTY Daemon] Cannot resize dead PTY:', sanitizeIdForLog(id));
       return;
     }
-    managed.process.resize(cols, rows);
-    managed.config.cols = cols;
-    managed.config.rows = rows;
+    try {
+      managed.process.resize(cols, rows);
+      managed.config.cols = cols;
+      managed.config.rows = rows;
+    } catch (error) {
+      // PTY process may have been destroyed during teardown
+      console.error('[PTY Daemon] Error resizing PTY:', sanitizeIdForLog(id), error);
+      managed.isDead = true;
+    }
   }
 
   /**
@@ -348,7 +378,7 @@ class PtyDaemon {
   private killPty(id: string): void {
     const managed = this.ptys.get(id);
     if (!managed) {
-      console.warn(`[PTY Daemon] PTY ${id} not found for kill`);
+      console.warn('[PTY Daemon] PTY not found for kill:', sanitizeIdForLog(id));
       return;
     }
 
@@ -356,12 +386,12 @@ class PtyDaemon {
       try {
         managed.process.kill();
       } catch (error) {
-        console.error(`[PTY Daemon] Error killing PTY ${id}:`, error);
+        console.error('[PTY Daemon] Error killing PTY:', sanitizeIdForLog(id), error);
       }
     }
 
     this.ptys.delete(id);
-    console.error(`[PTY Daemon] Removed PTY ${id}`);
+    console.error('[PTY Daemon] Removed PTY:', sanitizeIdForLog(id));
   }
 
   /**
@@ -394,7 +424,7 @@ class PtyDaemon {
       throw new Error(`PTY ${id} not found`);
     }
     managed.clients.add(socket);
-    console.error(`[PTY Daemon] Client subscribed to PTY ${id}`);
+    console.error('[PTY Daemon] Client subscribed to PTY:', sanitizeIdForLog(id));
   }
 
   /**
@@ -404,7 +434,7 @@ class PtyDaemon {
     const managed = this.ptys.get(id);
     if (managed) {
       managed.clients.delete(socket);
-      console.error(`[PTY Daemon] Client unsubscribed from PTY ${id}`);
+      console.error('[PTY Daemon] Client unsubscribed from PTY:', sanitizeIdForLog(id));
     }
   }
 
@@ -448,13 +478,16 @@ class PtyDaemon {
     const shutdown = (signal: string) => {
       console.error(`[PTY Daemon] Received ${signal}, shutting down...`);
 
+      // Set shutdown flag to prevent new PTY creation and guard operations
+      this.isShuttingDown = true;
+
       // Kill all PTYs
       this.ptys.forEach((managed) => {
         if (!managed.isDead) {
           try {
             managed.process.kill();
           } catch (error) {
-            console.error(`[PTY Daemon] Error killing PTY ${managed.id}:`, error);
+            console.error('[PTY Daemon] Error killing PTY:', sanitizeIdForLog(managed.id), error);
           }
         }
       });

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

@@ -16,6 +16,32 @@ import type { SupportedTerminal } from '../../shared/types/settings';
 
 // Windows shell paths are now imported from the platform module via getWindowsShellPaths()
 
+/**
+ * Shutdown flag to prevent PTY handlers from accessing destroyed resources
+ * (e.g., BrowserWindow.webContents) during app shutdown.
+ * Follows the same pattern as isShuttingDown in pty-daemon-client.ts.
+ *
+ * Part of the shutdown guard pattern for GitHub issue #1469: without this flag,
+ * PTY onData/onExit callbacks can fire after BrowserWindow is destroyed,
+ * causing pty.node's native ThreadSafeFunction to SIGABRT.
+ */
+let isShuttingDown = false;
+
+/**
+ * Set the shutting down flag. Call this during app quit/before-quit
+ * to prevent PTY handlers from accessing destroyed resources.
+ */
+export function setShuttingDown(value: boolean): void {
+  isShuttingDown = value;
+}
+
+/**
+ * Check if the PTY manager is in shutting down state.
+ */
+export function getIsShuttingDown(): boolean {
+  return isShuttingDown;
+}
+
 /**
  * Result of spawning a PTY process
  */
@@ -184,6 +210,10 @@ export function setupPtyHandlers(
 
   // Handle data from terminal
   ptyProcess.onData((data) => {
+    // Shutdown guard (GitHub #1469): skip processing to avoid accessing
+    // destroyed BrowserWindow.webContents, which triggers pty.node SIGABRT
+    if (isShuttingDown) return;
+
     // Append to output buffer (limit to 100KB)
     terminal.outputBuffer = (terminal.outputBuffer + data).slice(-100000);
 
@@ -201,7 +231,8 @@ export function setupPtyHandlers(
   ptyProcess.onExit(({ exitCode }) => {
     debugLog('[PtyManager] Terminal exited:', id, 'code:', exitCode);
 
-    // Resolve any pending exit promise FIRST (before other cleanup)
+    // Always resolve pending exit promises, even during shutdown
+    // (needed for waitForPtyExit callers to complete)
     const pendingExit = pendingExitPromises.get(id);
     if (pendingExit) {
       clearTimeout(pendingExit.timeoutId);
@@ -209,6 +240,10 @@ export function setupPtyHandlers(
       pendingExit.resolve();
     }
 
+    // Shutdown guard (GitHub #1469): skip accessing win.webContents and callbacks
+    // to avoid pty.node SIGABRT from destroyed BrowserWindow resources
+    if (isShuttingDown) return;
+
     const win = getWindow();
     if (win) {
       win.webContents.send(IPC_CHANNELS.TERMINAL_EXIT, id, exitCode);

apps/frontend/src/main/terminal/terminal-lifecycle.ts

@@ -294,12 +294,27 @@ export async function destroyTerminal(
 }
 
 /**
- * Kill all terminal processes
+ * Global timeout for destroyAllTerminals to prevent shutdown from hanging (ms).
+ */
+const DESTROY_ALL_TIMEOUT = 3000;
+
+/**
+ * Kill all terminal processes.
+ * Sets the shutdown flag first to prevent PTY handlers from accessing destroyed
+ * resources, then waits for all PTY processes to exit (with a global timeout).
+ *
+ * This is the core fix for GitHub issue #1469: by setting the shutdown flag and
+ * awaiting PTY exit before returning, we ensure pty.node's native callbacks
+ * don't fire after the JS environment tears down (which causes SIGABRT).
  */
 export async function destroyAllTerminals(
   terminals: Map<string, TerminalProcess>,
   saveTimer: NodeJS.Timeout | null
 ): Promise<NodeJS.Timeout | null> {
+  // Set shutdown flag first — prevents PTY onData/onExit from accessing
+  // destroyed BrowserWindow.webContents (GitHub #1469 shutdown guard pattern)
+  PtyManager.setShuttingDown(true);
+
   await SessionHandler.persistAllSessionsAsync(terminals);
 
   if (saveTimer) {
@@ -307,25 +322,24 @@ export async function destroyAllTerminals(
     saveTimer = null;
   }
 
-  const promises: Promise<void>[] = [];
+  // Kill all terminals and wait for PTY exit to avoid pty.node SIGABRT on shutdown (GitHub #1469)
+  const killPromises: Promise<void>[] = [];
 
   terminals.forEach((terminal) => {
-    promises.push(
-      new Promise((resolve) => {
-        try {
-          // Note: We intentionally don't wait for PTY exit here (unlike destroyTerminal)
-          // because this function is only called during app shutdown when no terminals
-          // will be recreated. Waiting would only delay shutdown unnecessarily.
-          PtyManager.killPty(terminal);
-        } catch {
-          // Ignore errors during cleanup
-        }
-        resolve();
+    killPromises.push(
+      PtyManager.killPty(terminal, true).catch((error) => {
+        console.warn('[TerminalLifecycle] Error during PTY cleanup:', error);
       })
     );
   });
 
-  await Promise.all(promises);
+  // Wait for all PTY processes to exit, but cap with a global timeout
+  // so shutdown never hangs indefinitely
+  await Promise.race([
+    Promise.all(killPromises),
+    new Promise<void>((resolve) => setTimeout(resolve, DESTROY_ALL_TIMEOUT))
+  ]);
+
   terminals.clear();
 
   return saveTimer;

apps/frontend/src/main/utils/windows-paths.ts

@@ -37,6 +37,17 @@ export const WINDOWS_GIT_PATHS: WindowsToolPaths = {
   ],
 };
 
+export const WINDOWS_GLAB_PATHS: WindowsToolPaths = {
+  toolName: 'GitLab CLI',
+  executable: 'glab.exe',
+  patterns: [
+    // Official Inno Setup installer path (DefaultDirName={autopf}\glab)
+    '%PROGRAMFILES%\\glab',
+    '%PROGRAMFILES(X86)%\\glab',
+    '%LOCALAPPDATA%\\Programs\\glab',
+  ],
+};
+
 export function isSecurePath(pathStr: string): boolean {
   const dangerousPatterns = [
     /[;&|`${}[\]<>!"^]/,  // Shell metacharacters (parentheses removed - safe when quoted)

apps/frontend/src/main/utils/worktree-cleanup.ts

@@ -0,0 +1,307 @@
+/**
+ * Worktree Cleanup Utility
+ *
+ * Provides a robust, cross-platform worktree cleanup implementation that handles
+ * Windows-specific issues with git worktree deletion when untracked files exist.
+ *
+ * The standard `git worktree remove --force` fails on Windows when the worktree
+ * contains untracked files (node_modules, build artifacts, etc.). This utility:
+ *
+ * 1. Auto-commits any uncommitted work (preserves in git history for ~90 days via reflog)
+ * 2. Manually deletes the worktree directory with retry logic for Windows file locks
+ * 3. Prunes git's internal worktree references
+ * 4. Optionally deletes the associated branch
+ *
+ * Related issue: https://github.com/AndyMik90/Auto-Claude/issues/1539
+ */
+
+import { execFileSync } from 'child_process';
+import { rm } from 'fs/promises';
+import { existsSync } from 'fs';
+import { getToolPath } from '../cli-tool-manager';
+import { getIsolatedGitEnv } from './git-isolation';
+import { getTaskWorktreeDir, isPathWithinBase } from '../worktree-paths';
+
+/**
+ * Options for worktree cleanup operation
+ */
+export interface WorktreeCleanupOptions {
+  /** Absolute path to the worktree directory to delete */
+  worktreePath: string;
+  /** Absolute path to the main project directory (for git operations) */
+  projectPath: string;
+  /** Spec ID for generating branch name (e.g., "001-my-feature") */
+  specId: string;
+  /** Custom commit message for auto-commit (default: "Auto-save before deletion") */
+  commitMessage?: string;
+  /** Log prefix for console messages (e.g., "[TASK_DELETE]") */
+  logPrefix?: string;
+  /** Whether to delete the associated branch (default: true) */
+  deleteBranch?: boolean;
+  /** Timeout in milliseconds for git operations (default: 30000) */
+  timeout?: number;
+  /** Maximum retries for directory deletion on Windows (default: 3) */
+  maxRetries?: number;
+  /** Delay between retries in milliseconds (default: 500) */
+  retryDelay?: number;
+}
+
+/**
+ * Result of the cleanup operation
+ */
+export interface WorktreeCleanupResult {
+  /** Whether the cleanup was successful */
+  success: boolean;
+  /** The branch that was deleted (if deleteBranch was true) */
+  branch?: string;
+  /** Whether uncommitted changes were auto-committed */
+  autoCommitted?: boolean;
+  /** Warnings that occurred during cleanup (non-fatal issues) */
+  warnings: string[];
+}
+
+/**
+ * Gets the worktree branch name based on spec ID
+ */
+function getWorktreeBranch(worktreePath: string, specId: string, timeout: number): string | null {
+  // First try to get branch from the worktree's HEAD
+  if (existsSync(worktreePath)) {
+    try {
+      const branch = execFileSync(getToolPath('git'), ['rev-parse', '--abbrev-ref', 'HEAD'], {
+        cwd: worktreePath,
+        encoding: 'utf-8',
+        env: getIsolatedGitEnv(),
+        timeout
+      }).trim();
+
+      if (branch && branch !== 'HEAD') {
+        return branch;
+      }
+    } catch {
+      // Worktree might be corrupted, fall back to naming convention
+    }
+  }
+
+  // Fall back to the naming convention: auto-claude/{spec-id}
+  return `auto-claude/${specId}`;
+}
+
+/**
+ * Delays execution for specified milliseconds
+ */
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Deletes a directory with retry logic for Windows file locking issues
+ *
+ * On Windows, files can be locked by other processes (IDE, build tools, etc.)
+ * which causes immediate deletion to fail. This function retries with linear
+ * backoff to handle transient file locks.
+ */
+async function deleteDirectoryWithRetry(
+  dirPath: string,
+  maxRetries: number,
+  retryDelay: number,
+  logPrefix: string
+): Promise<void> {
+  let lastError: Error | null = null;
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      await rm(dirPath, { recursive: true, force: true });
+      return; // Success
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      if (attempt < maxRetries) {
+        const waitTime = retryDelay * attempt; // Linear backoff
+        console.warn(
+          `${logPrefix} Directory deletion attempt ${attempt}/${maxRetries} failed, ` +
+          `retrying in ${waitTime}ms: ${lastError.message}`
+        );
+        await delay(waitTime);
+      }
+    }
+  }
+
+  // All retries exhausted
+  throw lastError || new Error('Failed to delete directory after retries');
+}
+
+/**
+ * Cleans up a worktree directory in a robust, cross-platform manner
+ *
+ * This function handles the Windows-specific issue where `git worktree remove --force`
+ * fails when the worktree contains untracked files. The approach is:
+ *
+ * 1. Auto-commit any uncommitted changes (preserves work in git history)
+ * 2. Manually delete the directory with retry logic for file locks
+ * 3. Run `git worktree prune` to clean up git's internal references
+ * 4. Optionally delete the associated branch
+ *
+ * All errors except directory deletion are logged but don't fail the operation.
+ *
+ * @param options - Cleanup configuration options
+ * @returns Result object with success status and any warnings
+ *
+ * @example
+ * ```typescript
+ * const result = await cleanupWorktree({
+ *   worktreePath: 'C:/projects/my-app/.auto-claude/worktrees/tasks/001-feature',
+ *   projectPath: 'C:/projects/my-app',
+ *   specId: '001-feature',
+ *   logPrefix: '[TASK_DELETE]'
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Cleanup successful');
+ *   if (result.autoCommitted) {
+ *     console.log('Note: Uncommitted work was auto-saved');
+ *   }
+ * }
+ * ```
+ */
+export async function cleanupWorktree(options: WorktreeCleanupOptions): Promise<WorktreeCleanupResult> {
+  const {
+    worktreePath,
+    projectPath,
+    specId,
+    commitMessage = 'Auto-save before deletion',
+    logPrefix = '[WORKTREE_CLEANUP]',
+    deleteBranch = true,
+    timeout = 30000,
+    maxRetries = 3,
+    retryDelay = 500
+  } = options;
+
+  const warnings: string[] = [];
+  let autoCommitted = false;
+
+  // Security: Validate that worktreePath is within the expected worktree directory
+  // This prevents path traversal attacks and accidental deletion of wrong directories
+  const expectedBase = getTaskWorktreeDir(projectPath);
+  if (!isPathWithinBase(worktreePath, expectedBase)) {
+    console.error(`${logPrefix} Security: Path validation failed - worktree path is outside expected directory`);
+    return {
+      success: false,
+      warnings: ['Invalid worktree path']
+    };
+  }
+
+  // 1. Get the branch name before we delete the directory
+  const branch = getWorktreeBranch(worktreePath, specId, timeout);
+  console.warn(`${logPrefix} Starting cleanup for worktree: ${worktreePath}`);
+  if (branch) {
+    console.warn(`${logPrefix} Associated branch: ${branch}`);
+  }
+
+  // 2. Auto-commit any uncommitted changes to preserve work
+  // This ensures the user can recover their work via `git reflog` for ~90 days
+  if (existsSync(worktreePath)) {
+    try {
+      // Check if there are any changes to commit
+      const status = execFileSync(getToolPath('git'), ['status', '--porcelain'], {
+        cwd: worktreePath,
+        encoding: 'utf-8',
+        env: getIsolatedGitEnv(),
+        timeout
+      });
+
+      if (status.trim()) {
+        // There are uncommitted changes - commit them before deletion
+        console.warn(`${logPrefix} Found uncommitted changes, auto-committing...`);
+
+        execFileSync(getToolPath('git'), ['add', '-A'], {
+          cwd: worktreePath,
+          encoding: 'utf-8',
+          env: getIsolatedGitEnv(),
+          timeout
+        });
+
+        execFileSync(getToolPath('git'), ['commit', '-m', commitMessage], {
+          cwd: worktreePath,
+          encoding: 'utf-8',
+          env: getIsolatedGitEnv(),
+          timeout
+        });
+
+        console.warn(`${logPrefix} Auto-committed changes before deletion`);
+        autoCommitted = true;
+      }
+    } catch (commitError) {
+      // Non-critical - log and continue with deletion
+      const msg = commitError instanceof Error ? commitError.message : String(commitError);
+      console.warn(`${logPrefix} Failed to auto-commit changes (non-critical): ${msg}`);
+      warnings.push(`Auto-commit failed: ${msg}`);
+    }
+  }
+
+  // 3. Delete the worktree directory manually
+  // This is required because `git worktree remove --force` fails on Windows
+  // when the directory contains untracked files (node_modules, build artifacts, etc.)
+  if (existsSync(worktreePath)) {
+    console.warn(`${logPrefix} Deleting worktree directory...`);
+    try {
+      await deleteDirectoryWithRetry(worktreePath, maxRetries, retryDelay, logPrefix);
+      console.warn(`${logPrefix} Worktree directory deleted successfully`);
+    } catch (deleteError) {
+      // This IS critical - if we can't delete the directory, the cleanup failed
+      const msg = deleteError instanceof Error ? deleteError.message : String(deleteError);
+      console.error(`${logPrefix} Failed to delete worktree directory: ${msg}`);
+      return {
+        success: false,
+        branch: branch || undefined,
+        autoCommitted,
+        warnings: [...warnings, `Directory deletion failed: ${msg}`]
+      };
+    }
+  } else {
+    console.warn(`${logPrefix} Worktree directory already deleted`);
+  }
+
+  // 4. Prune git's internal worktree references
+  // After manual deletion, git still thinks the worktree exists in .git/worktrees/
+  // Running prune cleans up these stale references
+  try {
+    execFileSync(getToolPath('git'), ['worktree', 'prune'], {
+      cwd: projectPath,
+      encoding: 'utf-8',
+      env: getIsolatedGitEnv(),
+      timeout
+    });
+    console.warn(`${logPrefix} Git worktree references pruned`);
+  } catch (pruneError) {
+    // Non-critical - the worktree is already gone, prune is just cleanup
+    const msg = pruneError instanceof Error ? pruneError.message : String(pruneError);
+    console.warn(`${logPrefix} Failed to prune worktree references (non-critical): ${msg}`);
+    warnings.push(`Worktree prune failed: ${msg}`);
+  }
+
+  // 5. Delete the branch if requested
+  if (deleteBranch && branch) {
+    try {
+      execFileSync(getToolPath('git'), ['branch', '-D', branch], {
+        cwd: projectPath,
+        encoding: 'utf-8',
+        env: getIsolatedGitEnv(),
+        timeout
+      });
+      console.warn(`${logPrefix} Branch deleted: ${branch}`);
+    } catch (branchError) {
+      // Non-critical - branch might not exist or already deleted
+      const msg = branchError instanceof Error ? branchError.message : String(branchError);
+      console.warn(`${logPrefix} Failed to delete branch (non-critical): ${msg}`);
+      warnings.push(`Branch deletion failed: ${msg}`);
+    }
+  }
+
+  console.warn(`${logPrefix} Cleanup completed successfully`);
+  return {
+    success: true,
+    branch: branch || undefined,
+    autoCommitted,
+    warnings
+  };
+}

apps/frontend/src/main/worktree-paths.ts

@@ -22,6 +22,10 @@ export const LEGACY_WORKTREE_DIR = '.worktrees';
  * Get the task worktrees directory path
  */
 export function getTaskWorktreeDir(projectPath: string): string {
+  if (!projectPath || typeof projectPath !== 'string') {
+    console.error('[worktree-paths] getTaskWorktreeDir: projectPath is undefined or not a string');
+    return '';
+  }
   return path.join(projectPath, TASK_WORKTREE_DIR);
 }
 
@@ -29,6 +33,14 @@ export function getTaskWorktreeDir(projectPath: string): string {
  * Get the full path for a specific task worktree
  */
 export function getTaskWorktreePath(projectPath: string, specId: string): string {
+  if (!projectPath || typeof projectPath !== 'string') {
+    console.error('[worktree-paths] getTaskWorktreePath: projectPath is undefined or not a string');
+    return '';
+  }
+  if (!specId || typeof specId !== 'string') {
+    console.error('[worktree-paths] getTaskWorktreePath: specId is undefined or not a string');
+    return '';
+  }
   return path.join(projectPath, TASK_WORKTREE_DIR, specId);
 }
 
@@ -48,6 +60,16 @@ export function isPathWithinBase(resolvedPath: string, basePath: string): boolea
  * Includes path traversal protection to ensure paths stay within project
  */
 export function findTaskWorktree(projectPath: string, specId: string): string | null {
+  // Defensive check for undefined inputs
+  if (!projectPath || typeof projectPath !== 'string') {
+    console.error('[worktree-paths] findTaskWorktree: projectPath is undefined or not a string');
+    return null;
+  }
+  if (!specId || typeof specId !== 'string') {
+    console.error('[worktree-paths] findTaskWorktree: specId is undefined or not a string');
+    return null;
+  }
+
   const normalizedProject = path.resolve(projectPath);
 
   // Check new path first
@@ -81,6 +103,10 @@ export function findTaskWorktree(projectPath: string, specId: string): string |
  * Get the terminal worktrees directory path
  */
 export function getTerminalWorktreeDir(projectPath: string): string {
+  if (!projectPath || typeof projectPath !== 'string') {
+    console.error('[worktree-paths] getTerminalWorktreeDir: projectPath is undefined or not a string');
+    return '';
+  }
   return path.join(projectPath, TERMINAL_WORKTREE_DIR);
 }
 
@@ -88,6 +114,14 @@ export function getTerminalWorktreeDir(projectPath: string): string {
  * Get the full path for a specific terminal worktree
  */
 export function getTerminalWorktreePath(projectPath: string, name: string): string {
+  if (!projectPath || typeof projectPath !== 'string') {
+    console.error('[worktree-paths] getTerminalWorktreePath: projectPath is undefined or not a string');
+    return '';
+  }
+  if (!name || typeof name !== 'string') {
+    console.error('[worktree-paths] getTerminalWorktreePath: name is undefined or not a string');
+    return '';
+  }
   return path.join(projectPath, TERMINAL_WORKTREE_DIR, name);
 }
 
@@ -97,6 +131,15 @@ export function getTerminalWorktreePath(projectPath: string, name: string): stri
  * Includes path traversal protection to ensure paths stay within project
  */
 export function findTerminalWorktree(projectPath: string, name: string): string | null {
+  if (!projectPath || typeof projectPath !== 'string') {
+    console.error('[worktree-paths] findTerminalWorktree: projectPath is undefined or not a string');
+    return null;
+  }
+  if (!name || typeof name !== 'string') {
+    console.error('[worktree-paths] findTerminalWorktree: name is undefined or not a string');
+    return null;
+  }
+
   const normalizedProject = path.resolve(projectPath);
 
   // Check new path first
@@ -131,6 +174,10 @@ export function findTerminalWorktree(projectPath: string, name: string): string
  * This is separate from the git worktree to avoid uncommitted files
  */
 export function getTerminalWorktreeMetadataDir(projectPath: string): string {
+  if (!projectPath || typeof projectPath !== 'string') {
+    console.error('[worktree-paths] getTerminalWorktreeMetadataDir: projectPath is undefined or not a string');
+    return '';
+  }
   return path.join(projectPath, TERMINAL_WORKTREE_METADATA_DIR);
 }
 
@@ -138,5 +185,13 @@ export function getTerminalWorktreeMetadataDir(projectPath: string): string {
  * Get the metadata file path for a specific terminal worktree
  */
 export function getTerminalWorktreeMetadataPath(projectPath: string, name: string): string {
+  if (!projectPath || typeof projectPath !== 'string') {
+    console.error('[worktree-paths] getTerminalWorktreeMetadataPath: projectPath is undefined or not a string');
+    return '';
+  }
+  if (!name || typeof name !== 'string') {
+    console.error('[worktree-paths] getTerminalWorktreeMetadataPath: name is undefined or not a string');
+    return '';
+  }
   return path.join(projectPath, TERMINAL_WORKTREE_METADATA_DIR, `${name}.json`);
 }