fix windows issue

fix(settings): allow toggle deselection and improve embedding model name matching (#661 )
* fix(settings): allow toggle deselection and improve embedding model name matching Fixes #650 - Can't select embedding model Changes: - Add toggle behavior: clicking selected model now deselects it - Improve model name matching to handle Ollama quantization variants (e.g., qwen3-embedding:8b-q4_K_M now matches qwen3-embedding:8b) - Added installedVersionNames set to match base:version ignoring suffixes This fixes two issues: 1. Users couldn't unselect a model once selected (no toggle) 2. Users couldn't select models when Ollama returned names with quantization suffixes that didn't match the recommended models list * refactor: remove redundant :latest check per Gemini review The installedBaseNames set already handles the case where a model without a tag (e.g., 'embeddinggemma') matches an installed model with :latest suffix. This simplifies the matching logic. --------- Co-authored-by: Alex <63423455+AlexMadera@users.noreply.github.com>
2026-01-05 17:30:36 +01:00 · 2026-01-05 08:08:22 +01:00 · 2026-01-05 08:05:43 +01:00 · 2026-01-04 20:35:38 +01:00 · 2026-01-04 18:15:32 +01:00 · 2026-01-03 23:57:10 +01:00
194 changed files with 33261 additions and 3582 deletions
@@ -97,13 +97,21 @@ jobs:
      - name: Install Rust toolchain (for building native Python packages)
        uses: dtolnay/rust-toolchain@stable

+      - name: Cache pip wheel cache (for compiled packages like real_ladybug)
+        uses: actions/cache@v4
+        with:
+          path: ~/Library/Caches/pip
+          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            pip-wheel-${{ runner.os }}-x64-
+
      - name: Cache bundled Python
        uses: actions/cache@v4
        with:
          path: apps/frontend/python-runtime
-          key: python-bundle-${{ runner.os }}-x64-3.12.8-rust
+          key: python-bundle-${{ runner.os }}-x64-3.12.8-rust-${{ hashFiles('apps/backend/requirements.txt') }}
          restore-keys: |
-            python-bundle-${{ runner.os }}-x64-
+            python-bundle-${{ runner.os }}-x64-3.12.8-rust-

      - name: Build application
        run: cd apps/frontend && npm run build
@@ -181,13 +189,21 @@ jobs:
      - name: Install dependencies
        run: cd apps/frontend && npm ci

+      - name: Cache pip wheel cache
+        uses: actions/cache@v4
+        with:
+          path: ~/Library/Caches/pip
+          key: pip-wheel-${{ runner.os }}-arm64-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            pip-wheel-${{ runner.os }}-arm64-
+
      - name: Cache bundled Python
        uses: actions/cache@v4
        with:
          path: apps/frontend/python-runtime
-          key: python-bundle-${{ runner.os }}-arm64-3.12.8
+          key: python-bundle-${{ runner.os }}-arm64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
          restore-keys: |
-            python-bundle-${{ runner.os }}-arm64-
+            python-bundle-${{ runner.os }}-arm64-3.12.8-

      - name: Build application
        run: cd apps/frontend && npm run build
@@ -265,13 +281,21 @@ jobs:
      - name: Install dependencies
        run: cd apps/frontend && npm ci

+      - name: Cache pip wheel cache
+        uses: actions/cache@v4
+        with:
+          path: ~\AppData\Local\pip\Cache
+          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            pip-wheel-${{ runner.os }}-x64-
+
      - name: Cache bundled Python
        uses: actions/cache@v4
        with:
          path: apps/frontend/python-runtime
-          key: python-bundle-${{ runner.os }}-x64-3.12.8
+          key: python-bundle-${{ runner.os }}-x64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
          restore-keys: |
-            python-bundle-${{ runner.os }}-x64-
+            python-bundle-${{ runner.os }}-x64-3.12.8-

      - name: Build application
        run: cd apps/frontend && npm run build
@@ -335,13 +359,21 @@ jobs:
          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

+      - name: Cache pip wheel cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            pip-wheel-${{ runner.os }}-x64-
+
      - name: Cache bundled Python
        uses: actions/cache@v4
        with:
          path: apps/frontend/python-runtime
-          key: python-bundle-${{ runner.os }}-x64-3.12.8
+          key: python-bundle-${{ runner.os }}-x64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
          restore-keys: |
-            python-bundle-${{ runner.os }}-x64-
+            python-bundle-${{ runner.os }}-x64-3.12.8-

      - name: Build application
        run: cd apps/frontend && npm run build
@@ -1,8 +1,10 @@
 name: Prepare Release

 # Triggers when code is pushed to main (e.g., merging develop → main)
-# If package.json version is newer than the latest tag, creates a new tag
-# which then triggers the release.yml workflow
+# If package.json version is newer than the latest tag:
+# 1. Validates CHANGELOG.md has an entry for this version (FAILS if missing)
+# 2. Extracts release notes from CHANGELOG.md
+# 3. Creates a new tag which triggers release.yml

 on:
  push:
@@ -67,8 +69,122 @@ jobs:
            echo "⏭️ No release needed (package version not newer than latest tag)"
          fi

-      - name: Create and push tag
+      # CRITICAL: Validate CHANGELOG.md has entry for this version BEFORE creating tag
+      - name: Validate and extract changelog
        if: steps.check.outputs.should_release == 'true'
+        id: changelog
+        run: |
+          VERSION="${{ steps.check.outputs.new_version }}"
+          CHANGELOG_FILE="CHANGELOG.md"
+
+          echo "🔍 Validating CHANGELOG.md for version $VERSION..."
+
+          if [ ! -f "$CHANGELOG_FILE" ]; then
+            echo "::error::CHANGELOG.md not found! Please create CHANGELOG.md with release notes."
+            exit 1
+          fi
+
+          # Extract changelog section for this version
+          # Looks for "## X.Y.Z" header and captures until next "## " or "---" or end
+          CHANGELOG_CONTENT=$(awk -v ver="$VERSION" '
+            BEGIN { found=0; content="" }
+            /^## / {
+              if (found) exit
+              # Match version at start of header (e.g., "## 2.7.3 -" or "## 2.7.3")
+              if ($2 == ver || $2 ~ "^"ver"[[:space:]]*-") {
+                found=1
+                # Skip the header line itself, we will add our own
+                next
+              }
+            }
+            /^---$/ { if (found) exit }
+            found { content = content $0 "\n" }
+            END {
+              if (!found) {
+                print "NOT_FOUND"
+                exit 1
+              }
+              # Trim leading/trailing whitespace
+              gsub(/^[[:space:]]+|[[:space:]]+$/, "", content)
+              print content
+            }
+          ' "$CHANGELOG_FILE")
+
+          if [ "$CHANGELOG_CONTENT" = "NOT_FOUND" ] || [ -z "$CHANGELOG_CONTENT" ]; then
+            echo ""
+            echo "::error::═══════════════════════════════════════════════════════════════════════"
+            echo "::error::  CHANGELOG VALIDATION FAILED"
+            echo "::error::═══════════════════════════════════════════════════════════════════════"
+            echo "::error::"
+            echo "::error::  Version $VERSION not found in CHANGELOG.md!"
+            echo "::error::"
+            echo "::error::  Before releasing, please update CHANGELOG.md with an entry like:"
+            echo "::error::"
+            echo "::error::    ## $VERSION - Your Release Title"
+            echo "::error::"
+            echo "::error::    ### ✨ New Features"
+            echo "::error::    - Feature description"
+            echo "::error::"
+            echo "::error::    ### 🐛 Bug Fixes"
+            echo "::error::    - Fix description"
+            echo "::error::"
+            echo "::error::═══════════════════════════════════════════════════════════════════════"
+            echo ""
+
+            # Also add to job summary for visibility
+            echo "## ❌ Release Blocked: Missing Changelog" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "Version **$VERSION** was not found in CHANGELOG.md." >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "### How to fix:" >> $GITHUB_STEP_SUMMARY
+            echo "1. Update CHANGELOG.md with release notes for version $VERSION" >> $GITHUB_STEP_SUMMARY
+            echo "2. Commit and push the changes" >> $GITHUB_STEP_SUMMARY
+            echo "3. The release will automatically retry" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "### Expected format:" >> $GITHUB_STEP_SUMMARY
+            echo "\`\`\`markdown" >> $GITHUB_STEP_SUMMARY
+            echo "## $VERSION - Release Title" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "### ✨ New Features" >> $GITHUB_STEP_SUMMARY
+            echo "- Feature description" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "### 🐛 Bug Fixes" >> $GITHUB_STEP_SUMMARY
+            echo "- Fix description" >> $GITHUB_STEP_SUMMARY
+            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+
+            exit 1
+          fi
+
+          echo "✅ Found changelog entry for version $VERSION"
+          echo ""
+          echo "--- Extracted Release Notes ---"
+          echo "$CHANGELOG_CONTENT"
+          echo "--- End Release Notes ---"
+
+          # Save changelog to file for artifact upload
+          echo "$CHANGELOG_CONTENT" > changelog-extract.md
+
+          # Also save to output (for short changelogs)
+          # Using heredoc for multiline output
+          {
+            echo "content<<CHANGELOG_EOF"
+            echo "$CHANGELOG_CONTENT"
+            echo "CHANGELOG_EOF"
+          } >> $GITHUB_OUTPUT
+
+          echo "changelog_valid=true" >> $GITHUB_OUTPUT
+
+      # Upload changelog as artifact for release.yml to use
+      - name: Upload changelog artifact
+        if: steps.check.outputs.should_release == 'true' && steps.changelog.outputs.changelog_valid == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: changelog-${{ steps.check.outputs.new_version }}
+          path: changelog-extract.md
+          retention-days: 1
+
+      - name: Create and push tag
+        if: steps.check.outputs.should_release == 'true' && steps.changelog.outputs.changelog_valid == 'true'
        run: |
          VERSION="${{ steps.check.outputs.new_version }}"
          TAG="v$VERSION"
@@ -85,17 +201,19 @@ jobs:

      - name: Summary
        run: |
-          if [ "${{ steps.check.outputs.should_release }}" = "true" ]; then
+          if [ "${{ steps.check.outputs.should_release }}" = "true" ] && [ "${{ steps.changelog.outputs.changelog_valid }}" = "true" ]; then
            echo "## 🚀 Release Triggered" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "**Version:** v${{ steps.check.outputs.new_version }}" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "✅ Changelog validated and extracted from CHANGELOG.md" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
            echo "The release workflow has been triggered and will:" >> $GITHUB_STEP_SUMMARY
            echo "1. Build binaries for all platforms" >> $GITHUB_STEP_SUMMARY
-            echo "2. Generate changelog from PRs" >> $GITHUB_STEP_SUMMARY
+            echo "2. Use changelog from CHANGELOG.md" >> $GITHUB_STEP_SUMMARY
            echo "3. Create GitHub release" >> $GITHUB_STEP_SUMMARY
            echo "4. Update README with new version" >> $GITHUB_STEP_SUMMARY
-          else
+          elif [ "${{ steps.check.outputs.should_release }}" = "false" ]; then
            echo "## ⏭️ No Release Needed" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "**Package version:** ${{ steps.package.outputs.version }}" >> $GITHUB_STEP_SUMMARY
@@ -46,13 +46,21 @@ jobs:
      - name: Install Rust toolchain (for building native Python packages)
        uses: dtolnay/rust-toolchain@stable

+      - name: Cache pip wheel cache (for compiled packages like real_ladybug)
+        uses: actions/cache@v4
+        with:
+          path: ~/Library/Caches/pip
+          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            pip-wheel-${{ runner.os }}-x64-
+
      - name: Cache bundled Python
        uses: actions/cache@v4
        with:
          path: apps/frontend/python-runtime
-          key: python-bundle-${{ runner.os }}-x64-3.12.8-rust
+          key: python-bundle-${{ runner.os }}-x64-3.12.8-rust-${{ hashFiles('apps/backend/requirements.txt') }}
          restore-keys: |
-            python-bundle-${{ runner.os }}-x64-
+            python-bundle-${{ runner.os }}-x64-3.12.8-rust-

      - name: Build application
        run: cd apps/frontend && npm run build
@@ -93,6 +101,8 @@ jobs:
          path: |
            apps/frontend/dist/*.dmg
            apps/frontend/dist/*.zip
+            apps/frontend/dist/*.yml
+            apps/frontend/dist/*.blockmap

  # Apple Silicon build on ARM64 runner for native compilation
  build-macos-arm64:
@@ -123,13 +133,21 @@ jobs:
      - name: Install dependencies
        run: cd apps/frontend && npm ci

+      - name: Cache pip wheel cache
+        uses: actions/cache@v4
+        with:
+          path: ~/Library/Caches/pip
+          key: pip-wheel-${{ runner.os }}-arm64-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            pip-wheel-${{ runner.os }}-arm64-
+
      - name: Cache bundled Python
        uses: actions/cache@v4
        with:
          path: apps/frontend/python-runtime
-          key: python-bundle-${{ runner.os }}-arm64-3.12.8
+          key: python-bundle-${{ runner.os }}-arm64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
          restore-keys: |
-            python-bundle-${{ runner.os }}-arm64-
+            python-bundle-${{ runner.os }}-arm64-3.12.8-

      - name: Build application
        run: cd apps/frontend && npm run build
@@ -170,6 +188,8 @@ jobs:
          path: |
            apps/frontend/dist/*.dmg
            apps/frontend/dist/*.zip
+            apps/frontend/dist/*.yml
+            apps/frontend/dist/*.blockmap

  build-windows:
    runs-on: windows-latest
@@ -200,13 +220,21 @@ jobs:
      - name: Install dependencies
        run: cd apps/frontend && npm ci

+      - name: Cache pip wheel cache
+        uses: actions/cache@v4
+        with:
+          path: ~\AppData\Local\pip\Cache
+          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            pip-wheel-${{ runner.os }}-x64-
+
      - name: Cache bundled Python
        uses: actions/cache@v4
        with:
          path: apps/frontend/python-runtime
-          key: python-bundle-${{ runner.os }}-x64-3.12.8
+          key: python-bundle-${{ runner.os }}-x64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
          restore-keys: |
-            python-bundle-${{ runner.os }}-x64-
+            python-bundle-${{ runner.os }}-x64-3.12.8-

      - name: Build application
        run: cd apps/frontend && npm run build
@@ -224,6 +252,8 @@ jobs:
          name: windows-builds
          path: |
            apps/frontend/dist/*.exe
+            apps/frontend/dist/*.yml
+            apps/frontend/dist/*.blockmap

  build-linux:
    runs-on: ubuntu-latest
@@ -261,13 +291,21 @@ jobs:
          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

+      - name: Cache pip wheel cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
+          restore-keys: |
+            pip-wheel-${{ runner.os }}-x64-
+
      - name: Cache bundled Python
        uses: actions/cache@v4
        with:
          path: apps/frontend/python-runtime
-          key: python-bundle-${{ runner.os }}-x64-3.12.8
+          key: python-bundle-${{ runner.os }}-x64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
          restore-keys: |
-            python-bundle-${{ runner.os }}-x64-
+            python-bundle-${{ runner.os }}-x64-3.12.8-

      - name: Build application
        run: cd apps/frontend && npm run build
@@ -285,6 +323,8 @@ jobs:
            apps/frontend/dist/*.AppImage
            apps/frontend/dist/*.deb
            apps/frontend/dist/*.flatpak
+            apps/frontend/dist/*.yml
+            apps/frontend/dist/*.blockmap

  create-release:
    needs: [build-macos-intel, build-macos-arm64, build-windows, build-linux]
@@ -304,16 +344,30 @@ jobs:
      - name: Flatten and validate artifacts
        run: |
          mkdir -p release-assets
-          find dist -type f \( -name "*.dmg" -o -name "*.zip" -o -name "*.exe" -o -name "*.AppImage" -o -name "*.deb" -o -name "*.flatpak" \) -exec cp {} release-assets/ \;
+          find dist -type f \( -name "*.dmg" -o -name "*.zip" -o -name "*.exe" -o -name "*.AppImage" -o -name "*.deb" -o -name "*.flatpak" -o -name "*.yml" -o -name "*.blockmap" \) -exec cp {} release-assets/ \;

-          # Validate that at least one artifact was copied
-          artifact_count=$(find release-assets -type f \( -name "*.dmg" -o -name "*.zip" -o -name "*.exe" -o -name "*.AppImage" -o -name "*.deb" -o -name "*.flatpak" \) | wc -l)
-          if [ "$artifact_count" -eq 0 ]; then
-            echo "::error::No build artifacts found! Expected .dmg, .zip, .exe, .AppImage, .deb, or .flatpak files."
+          # Validate that installer files exist (not just manifests)
+          installer_count=$(find release-assets -type f \( -name "*.dmg" -o -name "*.zip" -o -name "*.exe" -o -name "*.AppImage" -o -name "*.deb" -o -name "*.flatpak" \) | wc -l)
+          if [ "$installer_count" -eq 0 ]; then
+            echo "::error::No installer artifacts found! Expected .dmg, .zip, .exe, .AppImage, .deb, or .flatpak files."
            exit 1
          fi

-          echo "Found $artifact_count artifact(s):"
+          echo "Found $installer_count installer(s):"
+          find release-assets -type f \( -name "*.dmg" -o -name "*.zip" -o -name "*.exe" -o -name "*.AppImage" -o -name "*.deb" -o -name "*.flatpak" \) -exec basename {} \;
+
+          # Validate that electron-updater manifest files are present (required for auto-updates)
+          yml_count=$(find release-assets -type f -name "*.yml" | wc -l)
+          if [ "$yml_count" -eq 0 ]; then
+            echo "::error::No update manifest (.yml) files found! Auto-update architecture detection will not work."
+            exit 1
+          fi
+
+          echo "Found $yml_count manifest file(s):"
+          find release-assets -type f -name "*.yml" -exec basename {} \;
+
+          echo ""
+          echo "All release assets:"
          ls -la release-assets/

      - name: Generate checksums
@@ -473,23 +527,78 @@ jobs:
          cat release-assets/checksums.sha256 >> $GITHUB_STEP_SUMMARY
          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY

-      - name: Generate changelog
-        if: ${{ github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.dry_run != true) }}
+      - name: Extract changelog from CHANGELOG.md
+        if: ${{ github.event_name == 'push' }}
        id: changelog
-        uses: release-drafter/release-drafter@v6
-        with:
-          config-name: release-drafter.yml
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Extract version from tag (v2.7.2 -> 2.7.2)
+          VERSION=${GITHUB_REF_NAME#v}
+          CHANGELOG_FILE="CHANGELOG.md"
+
+          echo "📋 Extracting release notes for version $VERSION from CHANGELOG.md..."
+
+          if [ ! -f "$CHANGELOG_FILE" ]; then
+            echo "::warning::CHANGELOG.md not found, using minimal release notes"
+            echo "body=Release v$VERSION" >> $GITHUB_OUTPUT
+            exit 0
+          fi
+
+          # Extract changelog section for this version
+          # Looks for "## X.Y.Z" header and captures until next "## " or "---"
+          CHANGELOG_CONTENT=$(awk -v ver="$VERSION" '
+            BEGIN { found=0; content="" }
+            /^## / {
+              if (found) exit
+              # Match version at start of header (e.g., "## 2.7.3 -" or "## 2.7.3")
+              if ($2 == ver || $2 ~ "^"ver"[[:space:]]*-") {
+                found=1
+                next
+              }
+            }
+            /^---$/ { if (found) exit }
+            found { content = content $0 "\n" }
+            END {
+              if (!found) {
+                print "NOT_FOUND"
+                exit 0
+              }
+              # Trim leading/trailing whitespace
+              gsub(/^[[:space:]]+|[[:space:]]+$/, "", content)
+              print content
+            }
+          ' "$CHANGELOG_FILE")
+
+          if [ "$CHANGELOG_CONTENT" = "NOT_FOUND" ] || [ -z "$CHANGELOG_CONTENT" ]; then
+            echo "::warning::Version $VERSION not found in CHANGELOG.md, using minimal release notes"
+            CHANGELOG_CONTENT="Release v$VERSION
+
+See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details."
+          fi
+
+          echo "✅ Extracted changelog content"
+
+          # Save to file first (more reliable for multiline)
+          echo "$CHANGELOG_CONTENT" > changelog-body.md
+
+          # Use file-based output for multiline content
+          {
+            echo "body<<CHANGELOG_EOF"
+            cat changelog-body.md
+            echo "CHANGELOG_EOF"
+          } >> $GITHUB_OUTPUT

      - name: Create Release
-        if: ${{ github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.dry_run != true) }}
+        if: ${{ github.event_name == 'push' }}
        uses: softprops/action-gh-release@v2
        with:
          body: |
            ${{ steps.changelog.outputs.body }}

+            ---
+
            ${{ steps.virustotal.outputs.vt_results }}
+
+            **Full Changelog**: https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md
          files: release-assets/*
          draft: false
          prerelease: ${{ contains(github.ref, 'beta') || contains(github.ref, 'alpha') }}
@@ -500,7 +609,8 @@ jobs:
  update-readme:
    needs: [create-release]
    runs-on: ubuntu-latest
-    if: ${{ github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.dry_run != true) }}
+    # Only update README on actual releases (tag push), not dry runs
+    if: ${{ github.event_name == 'push' }}
    permissions:
      contents: write
    steps:
@@ -163,3 +163,4 @@ _bmad-output/
 .claude/
 /docs
 OPUS_ANALYSIS_AND_IDEAS.md
+/.github/agents
@@ -1,3 +1,283 @@
+## 2.7.2 - Stability & Performance Enhancements
+
+### ✨ New Features
+
+- Added refresh button to Kanban board for manually reloading tasks
+
+- Terminal dropdown with built-in and external options in task review
+
+- Centralized CLI tool path management with customizable settings
+
+- Files tab in task details panel for better file organization
+
+- Enhanced PR review page with filtering capabilities
+
+- GitLab integration support
+
+- Automated PR review with follow-up support and structured outputs
+
+- UI scale feature with 75-200% range for accessibility
+
+- Python 3.12 bundled with packaged Electron app
+
+- OpenRouter support as LLM/embedding provider
+
+- Internationalization (i18n) system for multi-language support
+
+- Flatpak packaging support for Linux
+
+- Path-aware AI merge resolution with device code streaming
+
+### 🛠️ Improvements
+
+- Improved terminal experience with persistent state when switching projects
+
+- Enhanced PR review with structured outputs and fork support
+
+- Better UX for display and scaling changes
+
+- Convert synchronous I/O to async operations in worktree handlers
+
+- Enhanced logs for commit linting stage
+
+- Remove top navigation bars for cleaner UI
+
+- Enhanced PR detail area visual design
+
+- Improved CLI tool detection with more language support
+
+- Added iOS/Swift project detection
+
+- Optimize performance by removing projectTabs from useEffect dependencies
+
+- Improved Python detection and version validation for compatibility
+
+### 🐛 Bug Fixes
+
+- Fixed CI Python setup and PR status gate checks
+
+- Fixed cross-platform CLI path detection and clearing in settings
+
+- Preserve original task description after spec creation
+
+- Fixed learning loop to retrieve patterns and gotchas from memory
+
+- Resolved frontend lag and updated dependencies
+
+- Fixed Content-Security-Policy to allow external HTTPS images
+
+- Fixed PR review isolation by using temporary worktree
+
+- Fixed Homebrew Python detection to prefer versioned Python over system python3
+
+- Added support for Bun 1.2.0+ lock file format detection
+
+- Fixed infinite re-render loop in task selection
+
+- Fixed infinite loop in task detail merge preview loading
+
+- Resolved Windows EINVAL error when opening worktree in VS Code
+
+- Fixed fallback to prevent tasks stuck in ai_review status
+
+- Fixed SDK permissions to include spec_dir
+
+- Added --base-branch argument support to spec_runner
+
+- Allow Windows to run CC PR Reviewer
+
+- Fixed model selection to respect task_metadata.json
+
+- Improved GitHub PR review by passing repo parameter explicitly
+
+- Fixed electron-log imports with .js extension
+
+- Fixed Swift detection order in project analyzer
+
+- Prevent TaskEditDialog from unmounting when opened
+
+- Fixed subprocess handling for Python paths with spaces
+
+- Fixed file system race conditions and unused variables in security scanning
+
+- Resolved Python detection and backend packaging issues
+
+- Fixed version-specific links in README and pre-commit hooks
+
+- Fixed task status persistence reverting on refresh
+
+- Proper semver comparison for pre-release versions
+
+- Use virtual environment Python for all services to fix dotenv errors
+
+- Fixed explicit Windows System32 tar path for builds
+
+- Added augmented PATH environment to all GitHub CLI calls
+
+- Use PowerShell for tar extraction on Windows
+
+- Added --force-local flag to tar on Windows
+
+- Stop tracking spec files in git
+
+- Fixed GitHub API calls with explicit GET method for comment fetches
+
+- Support archiving tasks across all worktree locations
+
+- Validated backend source path before using it
+
+- Resolved spawn Python ENOENT error on Linux
+
+- Fixed CodeQL alerts for uncontrolled command line
+
+- Resolved GitHub follow-up review API issues
+
+- Fixed relative path normalization to POSIX format
+
+- Accepted bug_fix workflow_type alias during planning
+
+- Added global spec numbering lock to prevent collisions
+
+- Fixed ideation status sync
+
+- Stopped running process when task status changes away from in_progress
+
+- Removed legacy path from auto-claude source detection
+
+- Resolved Python environment race condition
+
+---
+
+## What's Changed
+
+- fix(ci): add Python setup to beta-release and fix PR status gate checks (#565) by @Andy in c2148bb9
+- fix: detect and clear cross-platform CLI paths in settings (#535) by @Andy in 29e45505
+- fix(ui): preserve original task description after spec creation (#536) by @Andy in 7990dcb4
+- fix(memory): fix learning loop to retrieve patterns and gotchas (#530) by @Andy in f58c2578
+- fix: resolve frontend lag and update dependencies (#526) by @Andy in 30f7951a
+- feat(kanban): add refresh button to manually reload tasks (#548) by @Adryan Serage in 252242f9
+- fix(csp): allow external HTTPS images in Content-Security-Policy (#549) by @Michael Ludlow in 3db02c5d
+- fix(pr-review): use temporary worktree for PR review isolation (#532) by @Andy in 344ec65e
+- fix: prefer versioned Homebrew Python over system python3 (#494) by @Navid in 8d58dd6f
+- fix(detection): support bun.lock text format for Bun 1.2.0+ (#525) by @Andy in 4da8cd66
+- chore: bump version to 2.7.2-beta.12 (#460) by @Andy in 8e5c11ac
+- Fix/windows issues (#471) by @Andy in 72106109
+- fix(ci): add Rust toolchain for Intel Mac builds (#459) by @Andy in 52a4fcc6
+- fix: create spec.md during roadmap-to-task conversion (#446) by @Mulaveesala Pranaveswar in fb6b7fc6
+- fix(pr-review): treat LOW-only findings as ready to merge (#455) by @Andy in 0f9c5b84
+- Fix/2.7.2 beta12 (#424) by @Andy in 5d8ede23
+- feat: remove top bars (#386) by @Vinícius Santos in da31b687
+- fix: prevent infinite re-render loop in task selection useEffect (#442) by @Abe Diaz in 2effa535
+- fix: accept Python 3.12+ in install-backend.js (#443) by @Abe Diaz in c15bb311
+- fix: infinite loop in useTaskDetail merge preview loading (#444) by @Abe Diaz in 203a970a
+- fix(windows): resolve EINVAL error when opening worktree in VS Code (#434) by @Vinícius Santos in 3c0708b7
+- feat(frontend): Add Files tab to task details panel (#430) by @Mitsu in 666794b5
+- refactor: remove deprecated TaskDetailPanel component (#432) by @Mitsu in ac8dfcac
+- fix(ui): add fallback to prevent tasks stuck in ai_review status (#397) by @Michael Ludlow in 798ca79d
+- feat: Enhance the look of the PR Detail area (#427) by @Alex in bdb01549
+- ci: remove conventional commits PR title validation workflow by @AndyMik90 in 515b73b5
+- fix(client): add spec_dir to SDK permissions (#429) by @Mitsu in 88c76059
+- fix(spec_runner): add --base-branch argument support (#428) by @Mitsu in 62a75515
+- feat: enhance pr review page to include PRs filters (#423) by @Alex in 717fba04
+- feat: add gitlab integration (#254) by @Mitsu in 0a571d3a
+- fix: Allow windows to run CC PR Reviewer (#406) by @Alex in 2f662469
+- fix(model): respect task_metadata.json model selection (#415) by @Andy in e7e6b521
+- feat(build): add Flatpak packaging support for Linux (#404) by @Mitsu in 230de5fc
+- fix(github): pass repo parameter to GHClient for explicit PR resolution (#413) by @Andy in 4bdf7a0c
+- chore(ci): remove redundant CLA GitHub Action workflow by @AndyMik90 in a39ea49d
+- fix(frontend): add .js extension to electron-log/main imports by @AndyMik90 in 9aef0dd0
+- fix: 2.7.2 bug fixes and improvements (#388) by @Andy in 05131217
+- fix(analyzer): move Swift detection before Ruby detection (#401) by @Michael Ludlow in 321c9712
+- fix(ui): prevent TaskEditDialog from unmounting when opened (#395) by @Michael Ludlow in 98b12ed8
+- fix: improve CLI tool detection and add Claude CLI path settings (#393) by @Joe in aaa83131
+- feat(analyzer): add iOS/Swift project detection (#389) by @Michael Ludlow in 68548e33
+- fix(github): improve PR review with structured outputs and fork support (#363) by @Andy in 7751588e
+- fix(ideation): update progress calculation to include just-completed ideation type (#381) by @Illia Filippov in 8b4ce58c
+- Fixes failing spec - "gh CLI Check Handler - should return installed: true when gh CLI is found" (#370) by @Ian in bc220645
+- fix: Memory Status card respects configured embedding provider (#336) (#373) by @Michael Ludlow in db0cbea3
+- fix: fixed version-specific links in readme and pre-commit hook that updates them (#378) by @Ian in 0ca2e3f6
+- docs: add security research documentation (#361) by @Brian in 2d3b7fb4
+- fix/Improving UX for Display/Scaling Changes (#332) by @Kevin Rajan in 9bbdef09
+- fix(perf): remove projectTabs from useEffect deps to fix re-render loop (#362) by @Michael Ludlow in 753dc8bb
+- fix(security): invalidate profile cache when file is created/modified (#355) by @Michael Ludlow in 20f20fa3
+- fix(subprocess): handle Python paths with spaces (#352) by @Michael Ludlow in eabe7c7d
+- fix: Resolve pre-commit hook failures with version sync, pytest path, ruff version, and broken quality-dco workflow (#334) by @Ian in 1fa7a9c7
+- fix(terminal): preserve terminal state when switching projects (#358) by @Andy in 7881b2d1
+- fix(analyzer): add C#/Java/Swift/Kotlin project files to security hash (#351) by @Michael Ludlow in 4e71361b
+- fix: make backend tests pass on Windows (#282) by @Oluwatosin Oyeladun in 4dcc5afa
+- fix(ui): close parent modal when Edit dialog opens (#354) by @Michael Ludlow in e9782db0
+- chore: bump version to 2.7.2-beta.10 by @AndyMik90 in 40d04d7c
+- feat: add terminal dropdown with inbuilt and external options in task review (#347) by @JoshuaRileyDev in fef07c95
+- refactor: remove deprecated code across backend and frontend (#348) by @Mitsu in 9d43abed
+- feat: centralize CLI tool path management (#341) by @HSSAINI Saad in d51f4562
+- refactor(components): remove deprecated TaskDetailPanel re-export (#344) by @Mitsu in 787667e9
+- chore: Refactor/kanban realtime status sync (#249) by @souky-byte in 9734b70b
+- refactor(settings): remove deprecated ProjectSettings modal and hooks (#343) by @Mitsu in fec6b9f3
+- perf: convert synchronous I/O to async operations in worktree handlers (#337) by @JoshuaRileyDev in d3a63b09
+- feat: bump version (#329) by @Alex in 50e3111a
+- fix(ci): remove version bump to fix branch protection conflict (#325) by @Michael Ludlow in 8a80b1d5
+- fix(tasks): sync status to worktree implementation plan to prevent reset (#243) (#323) by @Alex in cb6b2165
+- fix(ci): add auto-updater manifest files and version auto-update (#317) by @Michael Ludlow in 661e47c3
+- fix(project): fix task status persistence reverting on refresh (#246) (#318) by @Michael Ludlow in e80ef79d
+- fix(updater): proper semver comparison for pre-release versions (#313) by @Michael Ludlow in e1b0f743
+- fix(python): use venv Python for all services to fix dotenv errors (#311) by @Alex in 92c6f278
+- chore(ci): cancel in-progress runs (#302) by @Oluwatosin Oyeladun in 1c142273
+- fix(build): use explicit Windows System32 tar path (#308) by @Andy in c0a02a45
+- fix(github): add augmented PATH env to all gh CLI calls by @AndyMik90 in 086429cb
+- fix(build): use PowerShell for tar extraction on Windows by @AndyMik90 in d9fb8f29
+- fix(build): add --force-local flag to tar on Windows (#303) by @Andy in d0b0b3df
+- fix: stop tracking spec files in git (#295) by @Andy in 937a60f8
+- Fix/2.7.2 fixes (#300) by @Andy in 7a51cbd5
+- feat(merge,oauth): add path-aware AI merge resolution and device code streaming (#296) by @Andy in 26beefe3
+- feat: enhance the logs for the commit linting stage (#293) by @Alex in 8416f307
+- fix(github): add explicit GET method to gh api comment fetches (#294) by @Andy in 217249c8
+- fix(frontend): support archiving tasks across all worktree locations (#286) by @Andy in 8bb3df91
+- Potential fix for code scanning alert no. 224: Uncontrolled command line (#285) by @Andy in 5106c6e9
+- fix(frontend): validate backend source path before using it (#287) by @Andy in 3ff61274
+- feat(python): bundle Python 3.12 with packaged Electron app (#284) by @Andy in 7f19c2e1
+- fix: resolve spawn python ENOENT error on Linux by using getAugmentedEnv() (#281) by @Todd W. Bucy in d98e2830
+- fix(ci): add write permissions to beta-release update-version job by @AndyMik90 in 0b874d4b
+- chore(deps): bump @xterm/xterm from 5.5.0 to 6.0.0 in /apps/frontend (#270) by @dependabot[bot] in 50dd1078
+- fix(github): resolve follow-up review API issues by @AndyMik90 in f1cc5a09
+- fix(security): resolve CodeQL file system race conditions and unused variables (#277) by @Andy in b005fa5c
+- fix(ci): use correct electron-builder arch flags (#278) by @Andy in d79f2da4
+- chore(deps): bump jsdom from 26.1.0 to 27.3.0 in /apps/frontend (#268) by @dependabot[bot] in 5ac566e2
+- chore(deps): bump typescript-eslint in /apps/frontend (#269) by @dependabot[bot] in f49d4817
+- fix(ci): use develop branch for dry-run builds in beta-release workflow (#276) by @Andy in 1e1d7d9b
+- fix: accept bug_fix workflow_type alias during planning (#240) by @Daniel Frey in e74a3dff
+- fix(paths): normalize relative paths to posix (#239) by @Daniel Frey in 6ac8250b
+- chore(deps): bump @electron/rebuild in /apps/frontend (#271) by @dependabot[bot] in a2cee694
+- chore(deps): bump vitest from 4.0.15 to 4.0.16 in /apps/frontend (#272) by @dependabot[bot] in d4cad80a
+- feat(github): add automated PR review with follow-up support (#252) by @Andy in 596e9513
+- ci: implement enterprise-grade PR quality gates and security scanning (#266) by @Alex in d42041c5
+- fix: update path resolution for ollama_model_detector.py in memory handlers (#263) by @delyethan in a3f87540
+- feat: add i18n internationalization system (#248) by @Mitsu in f8438112
+- Revert "Feat/Auto Fix Github issues and do extensive AI PR reviews (#250)" (#251) by @Andy in 5e8c5308
+- Feat/Auto Fix Github issues and do extensive AI PR reviews (#250) by @Andy in 348de6df
+- fix: resolve Python detection and backend packaging issues (#241) by @HSSAINI Saad in 0f7d6e05
+- fix: add future annotations import to discovery.py (#229) by @Joris Slagter in 5ccdb6ab
+- Fix/ideation status sync (#212) by @souky-byte in 6ec8549f
+- fix(core): add global spec numbering lock to prevent collisions (#209) by @Andy in 53527293
+- feat: Add OpenRouter as LLM/embedding provider (#162) by @Fernando Possebon in 02bef954
+- fix: Add Python 3.10+ version validation and GitHub Actions Python setup (#180 #167) (#208) by @Fernando Possebon in f168bdc3
+- fix(ci): correct welcome workflow PR message (#206) by @Andy in e3eec68a
+- Feat/beta release (#193) by @Andy in 407a0bee
+- feat/beta-release (#190) by @Andy in 8f766ad1
+- fix/PRs from old main setup to apps structure (#185) by @Andy in ced2ad47
+- fix: hide status badge when execution phase badge is showing (#154) by @Andy in 05f5d303
+- feat: Add UI scale feature with 75-200% range (#125) by @Enes Cingöz in 6951251b
+- fix(task): stop running process when task status changes away from in_progress by @AndyMik90 in 30e7536b
+- Fix/linear 400 error by @Andy in 220faf0f
+- fix: remove legacy path from auto-claude source detection (#148) by @Joris Slagter in f96c6301
+- fix: resolve Python environment race condition (#142) by @Joris Slagter in ebd8340d
+- Feat: Ollama download progress tracking with new apps structure (#141) by @rayBlock in df779530
+- Feature/apps restructure v2.7.2 (#138) by @Andy in 0adaddac
+- docs: Add Git Flow branching strategy to CONTRIBUTING.md by @AndyMik90 in 91f7051d
+
+## Thanks to all contributors
+
+@Andy, @Adryan Serage, @Michael Ludlow, @Navid, @Mulaveesala Pranaveswar, @Vinícius Santos, @Abe Diaz, @Mitsu, @Alex, @AndyMik90, @Joe, @Illia Filippov, @Ian, @Brian, @Kevin Rajan, @Oluwatosin Oyeladun, @JoshuaRileyDev, @HSSAINI Saad, @souky-byte, @Todd W. Bucy, @dependabot[bot], @Daniel Frey, @delyethan, @Joris Slagter, @Fernando Possebon, @Enes Cingöz, @rayBlock
+
 ## 2.7.1 - Build Pipeline Enhancements

 ### 🛠️ Improvements
@@ -24,11 +24,11 @@
 <!-- STABLE_DOWNLOADS -->
 | Platform | Download |
 |----------|----------|
-| **Windows** | [Auto-Claude-2.7.1-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.1/Auto-Claude-2.7.1-win32-x64.exe) |
-| **macOS (Apple Silicon)** | [Auto-Claude-2.7.1-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.1/Auto-Claude-2.7.1-darwin-arm64.dmg) |
-| **macOS (Intel)** | [Auto-Claude-2.7.1-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.1/Auto-Claude-2.7.1-darwin-x64.dmg) |
-| **Linux** | [Auto-Claude-2.7.1-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.1/Auto-Claude-2.7.1-linux-x86_64.AppImage) |
-| **Linux (Debian)** | [Auto-Claude-2.7.1-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.1/Auto-Claude-2.7.1-linux-amd64.deb) |
+| **Windows** | [Auto-Claude-2.7.2-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2/Auto-Claude-2.7.2-win32-x64.exe) |
+| **macOS (Apple Silicon)** | [Auto-Claude-2.7.2-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2/Auto-Claude-2.7.2-darwin-arm64.dmg) |
+| **macOS (Intel)** | [Auto-Claude-2.7.2-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2/Auto-Claude-2.7.2-darwin-x64.dmg) |
+| **Linux** | [Auto-Claude-2.7.2-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2/Auto-Claude-2.7.2-linux-x86_64.AppImage) |
+| **Linux (Debian)** | [Auto-Claude-2.7.2-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2/Auto-Claude-2.7.2-linux-amd64.deb) |
 <!-- STABLE_DOWNLOADS_END -->

 ### Beta Release
@@ -69,9 +69,38 @@ This will:
 - Update `apps/frontend/package.json`
 - Update `package.json` (root)
 - Update `apps/backend/__init__.py`
+- Check if `CHANGELOG.md` has an entry for the new version (warns if missing)
 - Create a commit with message `chore: bump version to X.Y.Z`

-### Step 2: Push and Create PR
+### Step 2: Update CHANGELOG.md (REQUIRED)
+
+**IMPORTANT: The release will fail if CHANGELOG.md doesn't have an entry for the new version.**
+
+Add release notes to `CHANGELOG.md` at the top of the file:
+
+```markdown
+## 2.8.0 - Your Release Title
+
+### ✨ New Features
+- Feature description
+
+### 🛠️ Improvements
+- Improvement description
+
+### 🐛 Bug Fixes
+- Fix description
+
+---
+```
+
+Then amend the version bump commit:
+
+```bash
+git add CHANGELOG.md
+git commit --amend --no-edit
+```
+
+### Step 3: Push and Create PR

 ```bash
 # Push your branch
@@ -81,24 +110,25 @@ git push origin your-branch
 gh pr create --base main --title "Release v2.8.0"
 ```

-### Step 3: Merge to Main
+### Step 4: Merge to Main

 Once the PR is approved and merged to `main`, GitHub Actions will automatically:

 1. **Detect the version bump** (`prepare-release.yml`)
-2. **Create a git tag** (e.g., `v2.8.0`)
-3. **Trigger the release workflow** (`release.yml`)
-4. **Build binaries** for all platforms:
+2. **Validate CHANGELOG.md** has an entry for the new version (FAILS if missing)
+3. **Extract release notes** from CHANGELOG.md
+4. **Create a git tag** (e.g., `v2.8.0`)
+5. **Trigger the release workflow** (`release.yml`)
+6. **Build binaries** for all platforms:
   - macOS Intel (x64) - code signed & notarized
   - macOS Apple Silicon (arm64) - code signed & notarized
   - Windows (NSIS installer) - code signed
   - Linux (AppImage + .deb)
-5. **Generate changelog** from merged PRs (using release-drafter)
-6. **Scan binaries** with VirusTotal
-7. **Create GitHub release** with all artifacts
-8. **Update README** with new version badge and download links
+7. **Scan binaries** with VirusTotal
+8. **Create GitHub release** with release notes from CHANGELOG.md
+9. **Update README** with new version badge and download links

-### Step 4: Verify
+### Step 5: Verify

 After merging, check:
 - [GitHub Actions](https://github.com/AndyMik90/Auto-Claude/actions) - ensure all workflows pass
@@ -113,28 +143,49 @@ We follow [Semantic Versioning](https://semver.org/):
 - **MINOR** (0.X.0): New features, backwards compatible
 - **PATCH** (0.0.X): Bug fixes, backwards compatible

-## Changelog Generation
+## Changelog Management

-Changelogs are automatically generated from merged PRs using [Release Drafter](https://github.com/release-drafter/release-drafter).
+Release notes are managed in `CHANGELOG.md` and used for GitHub releases.

-### PR Labels for Changelog Categories
+### Changelog Format

-| Label | Category |
-|-------|----------|
-| `feature`, `enhancement` | New Features |
-| `bug`, `fix` | Bug Fixes |
-| `improvement`, `refactor` | Improvements |
-| `documentation` | Documentation |
-| (any other) | Other Changes |
+Each version entry in `CHANGELOG.md` should follow this format:

-**Tip:** Add appropriate labels to your PRs for better changelog organization.
+```markdown
+## X.Y.Z - Release Title
+
+### ✨ New Features
+- Feature description with context
+
+### 🛠️ Improvements
+- Improvement description
+
+### 🐛 Bug Fixes
+- Fix description
+
+---
+```
+
+### Changelog Validation
+
+The release workflow **validates** that `CHANGELOG.md` has an entry for the version being released:
+
+- If the entry is **missing**, the release is **blocked** with a clear error message
+- If the entry **exists**, its content is used for the GitHub release notes
+
+### Writing Good Release Notes
+
+- **Be specific**: Instead of "Fixed bug", write "Fixed crash when opening large files"
+- **Group by impact**: Features first, then improvements, then fixes
+- **Credit contributors**: Mention contributors for significant changes
+- **Link issues**: Reference GitHub issues where relevant (e.g., "Fixes #123")

 ## Workflows

 | Workflow | Trigger | Purpose |
 |----------|---------|---------|
-| `prepare-release.yml` | Push to `main` | Detects version bump, creates tag |
-| `release.yml` | Tag `v*` pushed | Builds binaries, creates release |
+| `prepare-release.yml` | Push to `main` | Detects version bump, **validates CHANGELOG.md**, creates tag |
+| `release.yml` | Tag `v*` pushed | Builds binaries, extracts changelog, creates release |
 | `validate-version.yml` | Tag `v*` pushed | Validates tag matches package.json |
 | `update-readme` (in release.yml) | After release | Updates README with new version |

@@ -153,6 +204,22 @@ Changelogs are automatically generated from merged PRs using [Release Drafter](h
   git diff HEAD~1 --name-only | grep package.json
   ```

+### Release blocked: Missing changelog entry
+
+If you see "CHANGELOG VALIDATION FAILED" in the workflow:
+
+1. The `prepare-release.yml` workflow validated that `CHANGELOG.md` doesn't have an entry for the new version
+2. **Fix**: Add an entry to `CHANGELOG.md` with the format `## X.Y.Z - Title`
+3. Commit and push the changelog update
+4. The workflow will automatically retry when the changes are pushed to `main`
+
+```bash
+# Add changelog entry, then:
+git add CHANGELOG.md
+git commit -m "docs: add changelog for vX.Y.Z"
+git push origin main
+```
+
 ### Build failed after tag was created

 - The release won't be published if builds fail
@@ -11,14 +11,17 @@ import shutil
 import subprocess
 from pathlib import Path

+from core.git_bash import get_git_executable_path
+
 logger = logging.getLogger(__name__)


 def get_latest_commit(project_dir: Path) -> str | None:
    """Get the hash of the latest git commit."""
    try:
+        git_path = get_git_executable_path()
        result = subprocess.run(
-            ["git", "rev-parse", "HEAD"],
+            [git_path, "rev-parse", "HEAD"],
            cwd=project_dir,
            capture_output=True,
            text=True,
@@ -32,8 +35,9 @@ def get_latest_commit(project_dir: Path) -> str | None:
 def get_commit_count(project_dir: Path) -> int:
    """Get the total number of commits."""
    try:
+        git_path = get_git_executable_path()
        result = subprocess.run(
-            ["git", "rev-list", "--count", "HEAD"],
+            [git_path, "rev-list", "--count", "HEAD"],
            cwd=project_dir,
            capture_output=True,
            text=True,
@@ -18,6 +18,8 @@ import subprocess
 from pathlib import Path
 from typing import Any

+from core.git_bash import get_git_executable_path
+
 logger = logging.getLogger(__name__)

 # Check for Claude SDK availability
@@ -86,8 +88,9 @@ def get_session_diff(
        return "(No changes - same commit)"

    try:
+        git_path = get_git_executable_path()
        result = subprocess.run(
-            ["git", "diff", commit_before, commit_after],
+            [git_path, "diff", commit_before, commit_after],
            cwd=project_dir,
            capture_output=True,
            text=True,
@@ -131,8 +134,9 @@ def get_changed_files(
        return []

    try:
+        git_path = get_git_executable_path()
        result = subprocess.run(
-            ["git", "diff", "--name-only", commit_before, commit_after],
+            [git_path, "diff", "--name-only", commit_before, commit_after],
            cwd=project_dir,
            capture_output=True,
            text=True,
@@ -156,8 +160,9 @@ def get_commit_messages(
        return "(No commits)"

    try:
+        git_path = get_git_executable_path()
        result = subprocess.run(
-            ["git", "log", "--oneline", f"{commit_before}..{commit_after}"],
+            [git_path, "log", "--oneline", f"{commit_before}..{commit_after}"],
            cwd=project_dir,
            capture_output=True,
            text=True,
@@ -184,7 +184,7 @@ def handle_batch_cleanup_command(project_dir: str, dry_run: bool = True) -> bool
        True if successful
    """
    specs_dir = Path(project_dir) / ".auto-claude" / "specs"
-    worktrees_dir = Path(project_dir) / ".worktrees"
+    worktrees_dir = Path(project_dir) / ".auto-claude" / "worktrees" / "tasks"

    if not specs_dir.exists():
        print_status("No specs directory found", "info")
@@ -209,7 +209,7 @@ def handle_batch_cleanup_command(project_dir: str, dry_run: bool = True) -> bool
            print(f"  - {spec_name}")
            wt_path = worktrees_dir / spec_name
            if wt_path.exists():
-                print(f"    └─ .worktrees/{spec_name}/")
+                print(f"    └─ .auto-claude/worktrees/tasks/{spec_name}/")
        print()
        print("Run with --no-dry-run to actually delete")

@@ -28,8 +28,8 @@ from ui import (
    muted,
 )

-# Configuration
-DEFAULT_MODEL = "claude-opus-4-5-20251101"
+# Configuration - uses shorthand that resolves via API Profile if configured
+DEFAULT_MODEL = "sonnet"  # Changed from "opus" (fix #433)


 def setup_environment() -> Path:
@@ -82,7 +82,7 @@ def find_spec(project_dir: Path, spec_identifier: str) -> Path | None:
                    return spec_folder

    # Check worktree specs (for merge-preview, merge, review, discard operations)
-    worktree_base = project_dir / ".worktrees"
+    worktree_base = project_dir / ".auto-claude" / "worktrees" / "tasks"
    if worktree_base.exists():
        # Try exact match in worktree
        worktree_spec = (
@@ -9,6 +9,8 @@ import subprocess
 import sys
 from pathlib import Path

+from core.git_bash import get_git_executable_path
+
 # Ensure parent directory is in path for imports (before other imports)
 _PARENT_DIR = Path(__file__).parent.parent
 if str(_PARENT_DIR) not in sys.path:
@@ -58,12 +60,14 @@ def _detect_default_branch(project_dir: Path) -> str:
    """
    import os

+    git_path = get_git_executable_path()
+
    # 1. Check for DEFAULT_BRANCH env var
    env_branch = os.getenv("DEFAULT_BRANCH")
    if env_branch:
        # Verify the branch exists
        result = subprocess.run(
-            ["git", "rev-parse", "--verify", env_branch],
+            [git_path, "rev-parse", "--verify", env_branch],
            cwd=project_dir,
            capture_output=True,
            text=True,
@@ -74,7 +78,7 @@ def _detect_default_branch(project_dir: Path) -> str:
    # 2. Auto-detect main/master
    for branch in ["main", "master"]:
        result = subprocess.run(
-            ["git", "rev-parse", "--verify", branch],
+            [git_path, "rev-parse", "--verify", branch],
            cwd=project_dir,
            capture_output=True,
            text=True,
@@ -99,9 +103,10 @@ def _get_changed_files_from_git(
    Returns:
        List of changed file paths
    """
+    git_path = get_git_executable_path()
    try:
        result = subprocess.run(
-            ["git", "diff", "--name-only", f"{base_branch}...HEAD"],
+            [git_path, "diff", "--name-only", f"{base_branch}...HEAD"],
            cwd=worktree_path,
            capture_output=True,
            text=True,
@@ -119,7 +124,7 @@ def _get_changed_files_from_git(
        # Fallback: try without the three-dot notation
        try:
            result = subprocess.run(
-                ["git", "diff", "--name-only", base_branch, "HEAD"],
+                [git_path, "diff", "--name-only", base_branch, "HEAD"],
                cwd=worktree_path,
                capture_output=True,
                text=True,
@@ -226,8 +231,9 @@ def _generate_and_save_commit_message(project_dir: Path, spec_name: str) -> None
        diff_summary = ""
        files_changed = []
        try:
+            git_path = get_git_executable_path()
            result = subprocess.run(
-                ["git", "diff", "--staged", "--stat"],
+                [git_path, "diff", "--staged", "--stat"],
                cwd=project_dir,
                capture_output=True,
                text=True,
@@ -237,7 +243,7 @@ def _generate_and_save_commit_message(project_dir: Path, spec_name: str) -> None

            # Get list of changed files
            result = subprocess.run(
-                ["git", "diff", "--staged", "--name-only"],
+                [git_path, "diff", "--staged", "--name-only"],
                cwd=project_dir,
                capture_output=True,
                text=True,
@@ -375,6 +381,7 @@ def _check_git_merge_conflicts(project_dir: Path, spec_name: str) -> dict:

    debug(MODULE, "Checking for git-level merge conflicts (non-destructive)...")

+    git_path = get_git_executable_path()
    spec_branch = f"auto-claude/{spec_name}"
    result = {
        "has_conflicts": False,
@@ -388,7 +395,7 @@ def _check_git_merge_conflicts(project_dir: Path, spec_name: str) -> dict:
    try:
        # Get the current branch (base branch)
        base_result = subprocess.run(
-            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            [git_path, "rev-parse", "--abbrev-ref", "HEAD"],
            cwd=project_dir,
            capture_output=True,
            text=True,
@@ -398,7 +405,7 @@ def _check_git_merge_conflicts(project_dir: Path, spec_name: str) -> dict:

        # Get the merge base commit
        merge_base_result = subprocess.run(
-            ["git", "merge-base", result["base_branch"], spec_branch],
+            [git_path, "merge-base", result["base_branch"], spec_branch],
            cwd=project_dir,
            capture_output=True,
            text=True,
@@ -411,7 +418,7 @@ def _check_git_merge_conflicts(project_dir: Path, spec_name: str) -> dict:

        # Count commits main is ahead
        ahead_result = subprocess.run(
-            ["git", "rev-list", "--count", f"{merge_base}..{result['base_branch']}"],
+            [git_path, "rev-list", "--count", f"{merge_base}..{result['base_branch']}"],
            cwd=project_dir,
            capture_output=True,
            text=True,
@@ -430,7 +437,7 @@ def _check_git_merge_conflicts(project_dir: Path, spec_name: str) -> dict:
        # Note: --write-tree mode only accepts 2 branches (it auto-finds the merge base)
        merge_tree_result = subprocess.run(
            [
-                "git",
+                git_path,
                "merge-tree",
                "--write-tree",
                "--no-messages",
@@ -474,7 +481,7 @@ def _check_git_merge_conflicts(project_dir: Path, spec_name: str) -> dict:
            if not result["conflicting_files"]:
                # Files changed in main since merge-base
                main_files_result = subprocess.run(
-                    ["git", "diff", "--name-only", merge_base, result["base_branch"]],
+                    [git_path, "diff", "--name-only", merge_base, result["base_branch"]],
                    cwd=project_dir,
                    capture_output=True,
                    text=True,
@@ -487,7 +494,7 @@ def _check_git_merge_conflicts(project_dir: Path, spec_name: str) -> dict:

                # Files changed in spec branch since merge-base
                spec_files_result = subprocess.run(
-                    ["git", "diff", "--name-only", merge_base, spec_branch],
+                    [git_path, "diff", "--name-only", merge_base, spec_branch],
                    cwd=project_dir,
                    capture_output=True,
                    text=True,
@@ -7,10 +7,15 @@ for custom API endpoints.
 """

 import json
+import logging
 import os
 import platform
 import subprocess

+from core.git_bash import get_git_bash_env
+
+logger = logging.getLogger(__name__)
+
 # Priority order for auth token resolution
 # NOTE: We intentionally do NOT fall back to ANTHROPIC_API_KEY.
 # Auto Claude is designed to use Claude Code OAuth tokens only.
@@ -23,8 +28,15 @@ AUTH_TOKEN_ENV_VARS = [
 # Environment variables to pass through to SDK subprocess
 # NOTE: ANTHROPIC_API_KEY is intentionally excluded to prevent silent API billing
 SDK_ENV_VARS = [
+    # API endpoint configuration
    "ANTHROPIC_BASE_URL",
    "ANTHROPIC_AUTH_TOKEN",
+    # Model overrides (from API Profile custom model mappings)
+    "ANTHROPIC_MODEL",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL",
+    # SDK behavior configuration
    "NO_PROXY",
    "DISABLE_TELEMETRY",
    "DISABLE_COST_WARNINGS",
@@ -215,6 +227,8 @@ def get_sdk_env_vars() -> dict[str, str]:
    Collects relevant env vars (ANTHROPIC_BASE_URL, etc.) that should
    be passed through to the claude-agent-sdk subprocess.

+    On Windows, also includes CLAUDE_CODE_GIT_BASH_PATH if git-bash is found.
+
    Returns:
        Dict of env var name -> value for non-empty vars
    """
@@ -223,6 +237,12 @@ def get_sdk_env_vars() -> dict[str, str]:
        value = os.environ.get(var)
        if value:
            env[var] = value
+
+    # On Windows, add git-bash path for Claude SDK sandbox
+    git_bash_env = get_git_bash_env()
+    if git_bash_env:
+        env.update(git_bash_env)
+
    return env


@@ -0,0 +1,434 @@
+"""
+Windows Git Bash Detection
+
+Detects git-bash (bash.exe from Git for Windows) for Claude Agent SDK.
+The SDK requires bash.exe on Windows for its sandbox functionality.
+
+Detection Priority:
+1. CLAUDE_CODE_GIT_BASH_PATH environment variable (user override)
+2. Standard Git installation paths (Program Files)
+3. User-specific installations (LocalAppData, Scoop, Chocolatey)
+
+Note: This detects bash.exe, NOT git.exe. They are different executables:
+- git.exe: The Git CLI
+- bash.exe: Unix shell bundled with Git for Windows (required by Claude SDK)
+"""
+
+import logging
+import os
+import platform
+from dataclasses import dataclass
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# Environment variable for user override
+ENV_VAR_NAME = "CLAUDE_CODE_GIT_BASH_PATH"
+
+
+@dataclass
+class GitBashDetectionResult:
+    """Result of git-bash detection attempt."""
+    found: bool
+    path: Optional[str] = None
+    source: str = "not-found"
+    message: str = ""
+
+
+# Module-level cache (persists for process lifetime)
+_cache: Optional[GitBashDetectionResult] = None
+
+
+def _find_git_executable() -> Optional[str]:
+    """
+    Find git.exe using multiple methods.
+
+    GUI apps on Windows often have different PATH than terminal sessions.
+    We try multiple approaches to find git.
+
+    Returns:
+        Path to git.exe if found, None otherwise
+    """
+    import shutil
+    import subprocess
+
+    debug = os.environ.get("DEBUG", "").lower() in ("true", "1")
+
+    # Method 1: shutil.which (standard PATH lookup)
+    git_path = shutil.which("git")
+    if git_path:
+        if debug:
+            print(f"[GitBash] Found git via shutil.which: {git_path}")
+        return git_path
+
+    # Method 2: Windows 'where' command (searches PATH differently)
+    try:
+        result = subprocess.run(
+            ["where", "git"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            creationflags=subprocess.CREATE_NO_WINDOW if hasattr(subprocess, 'CREATE_NO_WINDOW') else 0
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            git_path = result.stdout.strip().split('\n')[0].strip()
+            if os.path.isfile(git_path):
+                if debug:
+                    print(f"[GitBash] Found git via 'where' command: {git_path}")
+                return git_path
+    except Exception as e:
+        if debug:
+            print(f"[GitBash] 'where git' failed: {e}")
+
+    # Method 3: Check Windows Registry for Git install location
+    try:
+        import winreg
+        for hive in [winreg.HKEY_LOCAL_MACHINE, winreg.HKEY_CURRENT_USER]:
+            for key_path in [
+                r"SOFTWARE\GitForWindows",
+                r"SOFTWARE\WOW6432Node\GitForWindows",
+            ]:
+                try:
+                    with winreg.OpenKey(hive, key_path) as key:
+                        install_path, _ = winreg.QueryValueEx(key, "InstallPath")
+                        if install_path:
+                            # Try multiple possible git.exe locations
+                            for subpath in ["cmd\\git.exe", "bin\\git.exe", "mingw64\\bin\\git.exe"]:
+                                git_exe = os.path.join(install_path, subpath)
+                                if os.path.isfile(git_exe):
+                                    if debug:
+                                        print(f"[GitBash] Found git via registry: {git_exe}")
+                                    return git_exe
+                except (FileNotFoundError, OSError):
+                    continue
+    except ImportError:
+        pass  # winreg not available (non-Windows)
+
+    return None
+
+
+def _find_bash_from_registry() -> Optional[str]:
+    """
+    Find bash.exe directly from Windows Registry Git InstallPath.
+
+    This is more reliable than PATH-based detection for GUI apps.
+
+    Returns:
+        Path to bash.exe if found via registry, None otherwise
+    """
+    debug = os.environ.get("DEBUG", "").lower() in ("true", "1")
+
+    try:
+        import winreg
+        for hive in [winreg.HKEY_LOCAL_MACHINE, winreg.HKEY_CURRENT_USER]:
+            for key_path in [
+                r"SOFTWARE\GitForWindows",
+                r"SOFTWARE\WOW6432Node\GitForWindows",
+            ]:
+                try:
+                    with winreg.OpenKey(hive, key_path) as key:
+                        install_path, _ = winreg.QueryValueEx(key, "InstallPath")
+                        if install_path:
+                            # Check for bash.exe in standard locations
+                            bash_exe = os.path.join(install_path, "bin", "bash.exe")
+                            if os.path.isfile(bash_exe):
+                                if debug:
+                                    print(f"[GitBash] Found bash.exe via registry: {bash_exe}")
+                                return bash_exe
+                            # Try usr/bin as fallback
+                            bash_exe = os.path.join(install_path, "usr", "bin", "bash.exe")
+                            if os.path.isfile(bash_exe):
+                                if debug:
+                                    print(f"[GitBash] Found bash.exe via registry: {bash_exe}")
+                                return bash_exe
+                except (FileNotFoundError, OSError):
+                    continue
+    except ImportError:
+        pass  # winreg not available (non-Windows)
+
+    return None
+
+
+def _derive_bash_from_git(git_path: str) -> Optional[str]:
+    """
+    Derive bash.exe location from git.exe path.
+
+    Git for Windows structure:
+      <install>/cmd/git.exe
+      <install>/bin/bash.exe
+      <install>/mingw64/bin/git.exe
+
+    Args:
+        git_path: Path to git.exe
+
+    Returns:
+        Path to bash.exe if found, None otherwise
+    """
+    git_dir = os.path.dirname(git_path)
+    git_parent = os.path.dirname(git_dir)
+
+    # Build list of possible bash locations
+    possible_paths = []
+
+    # If git is in cmd/ folder
+    if git_dir.endswith("cmd"):
+        possible_paths.extend([
+            os.path.join(git_parent, "bin", "bash.exe"),
+            os.path.join(git_parent, "usr", "bin", "bash.exe"),
+        ])
+
+    # If git is in mingw64/bin/ folder
+    if "mingw64" in git_dir:
+        git_root = git_parent
+        while git_root and not git_root.endswith("mingw64"):
+            git_root = os.path.dirname(git_root)
+        if git_root:
+            install_root = os.path.dirname(git_root)
+            possible_paths.extend([
+                os.path.join(install_root, "bin", "bash.exe"),
+                os.path.join(install_root, "usr", "bin", "bash.exe"),
+            ])
+
+    # Generic fallbacks
+    possible_paths.extend([
+        os.path.join(git_parent, "bin", "bash.exe"),
+        os.path.join(git_parent, "usr", "bin", "bash.exe"),
+    ])
+
+    for bash_path in possible_paths:
+        if os.path.isfile(bash_path):
+            return bash_path
+
+    return None
+
+
+def _find_git_from_path() -> Optional[str]:
+    """
+    Find bash.exe by first locating git.exe.
+
+    Returns:
+        Path to bash.exe if found via git location, None otherwise
+    """
+    git_path = _find_git_executable()
+    if not git_path:
+        return None
+
+    return _derive_bash_from_git(git_path)
+
+
+def _get_candidate_paths() -> list[str]:
+    """
+    Get list of candidate paths for bash.exe on Windows.
+
+    Returns paths in priority order (most common first).
+    """
+    candidates = [
+        # Standard 64-bit Git installation
+        r"C:\Program Files\Git\bin\bash.exe",
+        # Standard 32-bit Git installation
+        r"C:\Program Files (x86)\Git\bin\bash.exe",
+        # User-specific installation (Git installer option)
+        os.path.expandvars(r"%LOCALAPPDATA%\Programs\Git\bin\bash.exe"),
+        # Chocolatey installation
+        r"C:\ProgramData\chocolatey\lib\git\tools\bin\bash.exe",
+        # Scoop installation
+        os.path.expandvars(r"%USERPROFILE%\scoop\apps\git\current\bin\bash.exe"),
+        # Git for Windows SDK
+        r"C:\Git\bin\bash.exe",
+        # Alternative usr/bin location (some Git versions)
+        r"C:\Program Files\Git\usr\bin\bash.exe",
+    ]
+    return candidates
+
+
+def detect_git_bash(force_refresh: bool = False) -> GitBashDetectionResult:
+    """
+    Detect git-bash installation on Windows.
+
+    Args:
+        force_refresh: If True, bypass cache and re-detect
+
+    Returns:
+        GitBashDetectionResult with detection outcome
+    """
+    global _cache
+
+    # Non-Windows: not applicable
+    if platform.system() != "Windows":
+        return GitBashDetectionResult(
+            found=False,
+            source="not-applicable",
+            message="Git Bash detection only applies to Windows"
+        )
+
+    # Return cached result if available
+    if _cache is not None and not force_refresh:
+        logger.debug(f"[GitBash] Using cached result: {_cache.path} ({_cache.source})")
+        return _cache
+
+    debug = os.environ.get("DEBUG", "").lower() in ("true", "1")
+    if debug:
+        print("[GitBash] Starting detection...")
+
+    # Priority 1: Environment variable override
+    env_path = os.environ.get(ENV_VAR_NAME)
+    if env_path:
+        if os.path.isfile(env_path):
+            result = GitBashDetectionResult(
+                found=True,
+                path=env_path,
+                source="env-var",
+                message=f"Using {ENV_VAR_NAME}: {env_path}"
+            )
+            print(f"[GitBash] {result.message}")
+            _cache = result
+            return result
+        else:
+            print(f"[GitBash] WARNING: {ENV_VAR_NAME} set but path does not exist: {env_path}")
+
+    # Priority 2: Windows Registry (most reliable for GUI apps)
+    if debug:
+        print("[GitBash] Checking Windows Registry...")
+
+    registry_bash = _find_bash_from_registry()
+    if registry_bash:
+        result = GitBashDetectionResult(
+            found=True,
+            path=registry_bash,
+            source="windows-registry",
+            message=f"Found git-bash via registry: {registry_bash}"
+        )
+        print(f"[GitBash] {result.message}")
+        _cache = result
+        return result
+
+    # Priority 3: Check standard candidate paths
+    candidates = _get_candidate_paths()
+    if debug:
+        print(f"[GitBash] Checking {len(candidates)} standard paths...")
+
+    for candidate_path in candidates:
+        resolved = os.path.expandvars(candidate_path)
+        if os.path.isfile(resolved):
+            result = GitBashDetectionResult(
+                found=True,
+                path=resolved,
+                source="standard-path",
+                message=f"Found git-bash at standard path: {resolved}"
+            )
+            print(f"[GitBash] {result.message}")
+            _cache = result
+            return result
+        elif debug:
+            print(f"[GitBash] Not found: {resolved}")
+
+    # Priority 4: Derive from git.exe in PATH (handles custom PATH setups)
+    if debug:
+        print("[GitBash] Checking PATH-based git installation...")
+
+    path_based_bash = _find_git_from_path()
+    if path_based_bash:
+        result = GitBashDetectionResult(
+            found=True,
+            path=path_based_bash,
+            source="derived-from-path",
+            message=f"Found git-bash via PATH: {path_based_bash}"
+        )
+        print(f"[GitBash] {result.message}")
+        _cache = result
+        return result
+    elif debug:
+        print("[GitBash] Could not derive bash.exe from git PATH")
+
+    # Not found
+    result = GitBashDetectionResult(
+        found=False,
+        source="not-found",
+        message=(
+            "Git Bash not found. Install Git for Windows from https://git-scm.com/downloads/win "
+            f"or set {ENV_VAR_NAME} environment variable."
+        )
+    )
+    print(f"[GitBash] WARNING: {result.message}")
+    _cache = result
+    return result
+
+
+def get_git_bash_path() -> Optional[str]:
+    """
+    Get the path to bash.exe if available.
+
+    Convenience function that returns just the path or None.
+
+    Returns:
+        Path to bash.exe or None if not found
+    """
+    result = detect_git_bash()
+    return result.path if result.found else None
+
+
+def get_git_bash_env() -> dict[str, str]:
+    """
+    Get environment variables for Claude SDK with git-bash path.
+
+    Returns a dict suitable for merging into SDK environment variables.
+    Only returns the variable if git-bash was found.
+
+    Returns:
+        Dict with CLAUDE_CODE_GIT_BASH_PATH if found, empty dict otherwise
+    """
+    # Skip on non-Windows
+    if platform.system() != "Windows":
+        return {}
+
+    result = detect_git_bash()
+    if result.found and result.path:
+        return {ENV_VAR_NAME: result.path}
+
+    return {}
+
+
+def clear_cache() -> None:
+    """Clear the detection cache. Useful for testing."""
+    global _cache
+    _cache = None
+    logger.debug("[GitBash] Cache cleared")
+
+
+# Module-level cache for git executable path
+_git_cache: Optional[str] = None
+
+
+def get_git_executable_path() -> str:
+    """
+    Get the path to git executable.
+
+    On Windows, uses multi-method detection (shutil.which, registry, standard paths).
+    On other platforms, returns "git" and relies on PATH.
+
+    Returns:
+        Path to git executable, or "git" as fallback
+    """
+    global _git_cache
+
+    # Return cached result if available
+    if _git_cache is not None:
+        return _git_cache
+
+    # On non-Windows, just use "git" from PATH
+    if platform.system() != "Windows":
+        _git_cache = "git"
+        return _git_cache
+
+    # On Windows, try to find the full path
+    git_path = _find_git_executable()
+    if git_path:
+        _git_cache = git_path
+        debug = os.environ.get("DEBUG", "").lower() in ("true", "1")
+        if debug:
+            print(f"[Git] Using detected git: {git_path}")
+        return _git_cache
+
+    # Fallback to "git" and hope it's in PATH
+    _git_cache = "git"
+    return _git_cache
@@ -4,7 +4,7 @@ Workspace Management - Per-Spec Architecture
 =============================================

 Handles workspace isolation through Git worktrees, where each spec
-gets its own isolated worktree in .worktrees/{spec-name}/.
+gets its own isolated worktree in .auto-claude/worktrees/tasks/{spec-name}/.

 This module has been refactored for better maintainability:
 - Models and enums: workspace/models.py
@@ -20,6 +20,7 @@ Public API is exported via workspace/__init__.py for backward compatibility.
 import subprocess
 from pathlib import Path

+from core.git_bash import get_git_executable_path
 from ui import (
    Icons,
    bold,
@@ -180,8 +181,9 @@ def merge_existing_build(
    # Detect current branch - this is where user wants changes merged
    # Normal workflow: user is on their feature branch (e.g., version/2.5.5)
    # and wants to merge the spec changes into it, then PR to main
+    git_path = get_git_executable_path()
    current_branch_result = subprocess.run(
-        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+        [git_path, "rev-parse", "--abbrev-ref", "HEAD"],
        cwd=project_dir,
        capture_output=True,
        text=True,
@@ -545,6 +547,7 @@ def _check_git_conflicts(project_dir: Path, spec_name: str) -> dict:
    """
    import re

+    git_path = get_git_executable_path()
    spec_branch = f"auto-claude/{spec_name}"
    result = {
        "has_conflicts": False,
@@ -556,7 +559,7 @@ def _check_git_conflicts(project_dir: Path, spec_name: str) -> dict:
    try:
        # Get current branch
        base_result = subprocess.run(
-            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            [git_path, "rev-parse", "--abbrev-ref", "HEAD"],
            cwd=project_dir,
            capture_output=True,
            text=True,
@@ -566,7 +569,7 @@ def _check_git_conflicts(project_dir: Path, spec_name: str) -> dict:

        # Get merge base
        merge_base_result = subprocess.run(
-            ["git", "merge-base", result["base_branch"], spec_branch],
+            [git_path, "merge-base", result["base_branch"], spec_branch],
            cwd=project_dir,
            capture_output=True,
            text=True,
@@ -579,13 +582,13 @@ def _check_git_conflicts(project_dir: Path, spec_name: str) -> dict:

        # Get commit hashes
        main_commit_result = subprocess.run(
-            ["git", "rev-parse", result["base_branch"]],
+            [git_path, "rev-parse", result["base_branch"]],
            cwd=project_dir,
            capture_output=True,
            text=True,
        )
        spec_commit_result = subprocess.run(
-            ["git", "rev-parse", spec_branch],
+            [git_path, "rev-parse", spec_branch],
            cwd=project_dir,
            capture_output=True,
            text=True,
@@ -602,7 +605,7 @@ def _check_git_conflicts(project_dir: Path, spec_name: str) -> dict:
        # Note: --write-tree mode only accepts 2 branches (it auto-finds the merge base)
        merge_tree_result = subprocess.run(
            [
-                "git",
+                git_path,
                "merge-tree",
                "--write-tree",
                "--no-messages",
@@ -639,7 +642,7 @@ def _check_git_conflicts(project_dir: Path, spec_name: str) -> dict:
            # Fallback: if we didn't parse conflicts, use diff to find files changed in both branches
            if not result["conflicting_files"]:
                main_files_result = subprocess.run(
-                    ["git", "diff", "--name-only", merge_base, main_commit],
+                    [git_path, "diff", "--name-only", merge_base, main_commit],
                    cwd=project_dir,
                    capture_output=True,
                    text=True,
@@ -651,7 +654,7 @@ def _check_git_conflicts(project_dir: Path, spec_name: str) -> dict:
                )

                spec_files_result = subprocess.run(
-                    ["git", "diff", "--name-only", merge_base, spec_commit],
+                    [git_path, "diff", "--name-only", merge_base, spec_commit],
                    cwd=project_dir,
                    capture_output=True,
                    text=True,
@@ -728,8 +731,9 @@ def _resolve_git_conflicts_with_ai(
    )

    # Get merge-base commit
+    git_path = get_git_executable_path()
    merge_base_result = subprocess.run(
-        ["git", "merge-base", base_branch, spec_branch],
+        [git_path, "merge-base", base_branch, spec_branch],
        cwd=project_dir,
        capture_output=True,
        text=True,
@@ -783,7 +787,7 @@ def _resolve_git_conflicts_with_ai(
                    target_path.parent.mkdir(parents=True, exist_ok=True)
                    target_path.write_text(content, encoding="utf-8")
                    subprocess.run(
-                        ["git", "add", target_file_path],
+                        [git_path, "add", target_file_path],
                        cwd=project_dir,
                        capture_output=True,
                    )
@@ -904,7 +908,7 @@ def _resolve_git_conflicts_with_ai(
                    target_path.parent.mkdir(parents=True, exist_ok=True)
                    target_path.write_text(merged_content, encoding="utf-8")
                    subprocess.run(
-                        ["git", "add", file_path], cwd=project_dir, capture_output=True
+                        [git_path, "add", file_path], cwd=project_dir, capture_output=True
                    )
                    resolved_files.append(file_path)
                    print(success(f"    ✓ {file_path} (new file)"))
@@ -914,7 +918,7 @@ def _resolve_git_conflicts_with_ai(
                    if target_path.exists():
                        target_path.unlink()
                        subprocess.run(
-                            ["git", "add", file_path],
+                            [git_path, "add", file_path],
                            cwd=project_dir,
                            capture_output=True,
                        )
@@ -960,7 +964,7 @@ def _resolve_git_conflicts_with_ai(
                target_path.parent.mkdir(parents=True, exist_ok=True)
                target_path.write_text(result.merged_content, encoding="utf-8")
                subprocess.run(
-                    ["git", "add", result.file_path],
+                    [git_path, "add", result.file_path],
                    cwd=project_dir,
                    capture_output=True,
                )
@@ -1079,7 +1083,7 @@ def _resolve_git_conflicts_with_ai(
                target_path.parent.mkdir(parents=True, exist_ok=True)
                target_path.write_text(result.merged_content, encoding="utf-8")
                subprocess.run(
-                    ["git", "add", result.file_path],
+                    [git_path, "add", result.file_path],
                    cwd=project_dir,
                    capture_output=True,
                )
@@ -1112,7 +1116,7 @@ def _resolve_git_conflicts_with_ai(
                if target_path.exists():
                    target_path.unlink()
                    subprocess.run(
-                        ["git", "add", target_file_path],
+                        [git_path, "add", target_file_path],
                        cwd=project_dir,
                        capture_output=True,
                    )
@@ -1126,7 +1130,7 @@ def _resolve_git_conflicts_with_ai(
                    target_path.parent.mkdir(parents=True, exist_ok=True)
                    target_path.write_text(content, encoding="utf-8")
                    subprocess.run(
-                        ["git", "add", target_file_path],
+                        [git_path, "add", target_file_path],
                        cwd=project_dir,
                        capture_output=True,
                    )
@@ -4,7 +4,7 @@ Workspace Management Package
 =============================

 Handles workspace isolation through Git worktrees, where each spec
-gets its own isolated worktree in .worktrees/{spec-name}/.
+gets its own isolated worktree in .auto-claude/worktrees/tasks/{spec-name}/.

 This package provides:
 - Workspace setup and configuration
@@ -169,7 +169,15 @@ def handle_workspace_choice(
        if staging_path:
            print(highlight(f"  cd {staging_path}"))
        else:
-            print(highlight(f"  cd {project_dir}/.worktrees/{spec_name}"))
+            worktree_path = get_existing_build_worktree(project_dir, spec_name)
+            if worktree_path:
+                print(highlight(f"  cd {worktree_path}"))
+            else:
+                print(
+                    highlight(
+                        f"  cd {project_dir}/.auto-claude/worktrees/tasks/{spec_name}"
+                    )
+                )

        # Show likely test/run commands
        if staging_path:
@@ -232,7 +240,15 @@ def handle_workspace_choice(
        if staging_path:
            print(highlight(f"  cd {staging_path}"))
        else:
-            print(highlight(f"  cd {project_dir}/.worktrees/{spec_name}"))
+            worktree_path = get_existing_build_worktree(project_dir, spec_name)
+            if worktree_path:
+                print(highlight(f"  cd {worktree_path}"))
+            else:
+                print(
+                    highlight(
+                        f"  cd {project_dir}/.auto-claude/worktrees/tasks/{spec_name}"
+                    )
+                )
        print()
        print("When you're ready to add it:")
        print(highlight(f"  python auto-claude/run.py --spec {spec_name} --merge"))
@@ -10,6 +10,8 @@ import json
 import subprocess
 from pathlib import Path

+from core.git_bash import get_git_executable_path
+
 # Constants for merge limits
 MAX_FILE_LINES_FOR_AI = 5000  # Skip AI for files larger than this
 MAX_PARALLEL_AI_MERGES = 5  # Limit concurrent AI merge operations
@@ -113,9 +115,10 @@ def detect_file_renames(
        # -M flag enables rename detection
        # --diff-filter=R shows only renames
        # --name-status shows status and file names
+        git_path = get_git_executable_path()
        result = subprocess.run(
            [
-                "git",
+                git_path,
                "log",
                "--name-status",
                "-M",
@@ -176,8 +179,9 @@ def get_merge_base(project_dir: Path, ref1: str, ref2: str) -> str | None:
        Merge-base commit hash, or None if not found
    """
    try:
+        git_path = get_git_executable_path()
        result = subprocess.run(
-            ["git", "merge-base", ref1, ref2],
+            [git_path, "merge-base", ref1, ref2],
            cwd=project_dir,
            capture_output=True,
            text=True,
@@ -191,8 +195,9 @@ def get_merge_base(project_dir: Path, ref1: str, ref2: str) -> str | None:

 def has_uncommitted_changes(project_dir: Path) -> bool:
    """Check if user has unsaved work."""
+    git_path = get_git_executable_path()
    result = subprocess.run(
-        ["git", "status", "--porcelain"],
+        [git_path, "status", "--porcelain"],
        cwd=project_dir,
        capture_output=True,
        text=True,
@@ -202,8 +207,9 @@ def has_uncommitted_changes(project_dir: Path) -> bool:

 def get_current_branch(project_dir: Path) -> str:
    """Get the current branch name."""
+    git_path = get_git_executable_path()
    result = subprocess.run(
-        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+        [git_path, "rev-parse", "--abbrev-ref", "HEAD"],
        cwd=project_dir,
        capture_output=True,
        text=True,
@@ -222,10 +228,16 @@ def get_existing_build_worktree(project_dir: Path, spec_name: str) -> Path | Non
    Returns:
        Path to the worktree if it exists for this spec, None otherwise
    """
-    # Per-spec worktree path: .worktrees/{spec-name}/
-    worktree_path = project_dir / ".worktrees" / spec_name
-    if worktree_path.exists():
-        return worktree_path
+    # New path first
+    new_path = project_dir / ".auto-claude" / "worktrees" / "tasks" / spec_name
+    if new_path.exists():
+        return new_path
+
+    # Legacy fallback
+    legacy_path = project_dir / ".worktrees" / spec_name
+    if legacy_path.exists():
+        return legacy_path
+
    return None


@@ -233,8 +245,9 @@ def get_file_content_from_ref(
    project_dir: Path, ref: str, file_path: str
 ) -> str | None:
    """Get file content from a git ref (branch, commit, etc.)."""
+    git_path = get_git_executable_path()
    result = subprocess.run(
-        ["git", "show", f"{ref}:{file_path}"],
+        [git_path, "show", f"{ref}:{file_path}"],
        cwd=project_dir,
        capture_output=True,
        text=True,
@@ -262,8 +275,9 @@ def get_changed_files_from_branch(
    Returns:
        List of (file_path, status) tuples
    """
+    git_path = get_git_executable_path()
    result = subprocess.run(
-        ["git", "diff", "--name-status", f"{base_branch}...{spec_branch}"],
+        [git_path, "diff", "--name-status", f"{base_branch}...{spec_branch}"],
        cwd=project_dir,
        capture_output=True,
        text=True,
@@ -485,8 +499,9 @@ def create_conflict_file_with_git(
        try:
            # git merge-file <current> <base> <other>
            # Exit codes: 0 = clean merge, 1 = conflicts, >1 = error
+            git_path = get_git_executable_path()
            result = subprocess.run(
-                ["git", "merge-file", "-p", main_path, base_path, wt_path],
+                [git_path, "merge-file", "-p", main_path, base_path, wt_path],
                cwd=project_dir,
                capture_output=True,
                text=True,
@@ -249,7 +249,7 @@ class SpecNumberLock:
        max_number = max(max_number, self._scan_specs_dir(main_specs_dir))

        # 2. Scan all worktree specs
-        worktrees_dir = self.project_dir / ".worktrees"
+        worktrees_dir = self.project_dir / ".auto-claude" / "worktrees" / "tasks"
        if worktrees_dir.exists():
            for worktree in worktrees_dir.iterdir():
                if worktree.is_dir():
@@ -12,6 +12,7 @@ import subprocess
 import sys
 from pathlib import Path

+from core.git_bash import get_git_executable_path
 from merge import FileTimelineTracker
 from ui import (
    Icons,
@@ -368,8 +369,9 @@ def initialize_timeline_tracking(
                        files_to_modify.extend(subtask.get("files", []))

        # Get the current branch point commit
+        git_path = get_git_executable_path()
        result = subprocess.run(
-            ["git", "rev-parse", "HEAD"],
+            [git_path, "rev-parse", "HEAD"],
            cwd=project_dir,
            capture_output=True,
            text=True,
@@ -4,7 +4,7 @@ Git Worktree Manager - Per-Spec Architecture
 =============================================

 Each spec gets its own worktree:
- Worktree path: .worktrees/{spec-name}/
+- Worktree path: .auto-claude/worktrees/tasks/{spec-name}/
 - Branch name: auto-claude/{spec-name}

 This allows:
@@ -22,6 +22,8 @@ import subprocess
 from dataclasses import dataclass
 from pathlib import Path

+from core.git_bash import get_git_executable_path
+

 class WorktreeError(Exception):
    """Error during worktree operations."""
@@ -48,14 +50,14 @@ class WorktreeManager:
    """
    Manages per-spec Git worktrees.

-    Each spec gets its own worktree in .worktrees/{spec-name}/ with
+    Each spec gets its own worktree in .auto-claude/worktrees/tasks/{spec-name}/ with
    a corresponding branch auto-claude/{spec-name}.
    """

    def __init__(self, project_dir: Path, base_branch: str | None = None):
        self.project_dir = project_dir
        self.base_branch = base_branch or self._detect_base_branch()
-        self.worktrees_dir = project_dir / ".worktrees"
+        self.worktrees_dir = project_dir / ".auto-claude" / "worktrees" / "tasks"
        self._merge_lock = asyncio.Lock()

    def _detect_base_branch(self) -> str:
@@ -70,12 +72,14 @@ class WorktreeManager:
        Returns:
            The detected base branch name
        """
+        git_path = get_git_executable_path()
+
        # 1. Check for DEFAULT_BRANCH env var
        env_branch = os.getenv("DEFAULT_BRANCH")
        if env_branch:
            # Verify the branch exists
            result = subprocess.run(
-                ["git", "rev-parse", "--verify", env_branch],
+                [git_path, "rev-parse", "--verify", env_branch],
                cwd=self.project_dir,
                capture_output=True,
                text=True,
@@ -92,7 +96,7 @@ class WorktreeManager:
        # 2. Auto-detect main/master
        for branch in ["main", "master"]:
            result = subprocess.run(
-                ["git", "rev-parse", "--verify", branch],
+                [git_path, "rev-parse", "--verify", branch],
                cwd=self.project_dir,
                capture_output=True,
                text=True,
@@ -111,8 +115,9 @@ class WorktreeManager:

    def _get_current_branch(self) -> str:
        """Get the current git branch."""
+        git_path = get_git_executable_path()
        result = subprocess.run(
-            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            [git_path, "rev-parse", "--abbrev-ref", "HEAD"],
            cwd=self.project_dir,
            capture_output=True,
            text=True,
@@ -127,8 +132,9 @@ class WorktreeManager:
        self, args: list[str], cwd: Path | None = None
    ) -> subprocess.CompletedProcess:
        """Run a git command and return the result."""
+        git_path = get_git_executable_path()
        return subprocess.run(
-            ["git"] + args,
+            [git_path] + args,
            cwd=cwd or self.project_dir,
            capture_output=True,
            text=True,
@@ -157,8 +163,9 @@ class WorktreeManager:

        # 1. Check which staged files are gitignored
        # git check-ignore returns the files that ARE ignored
+        git_path = get_git_executable_path()
        result = subprocess.run(
-            ["git", "check-ignore", "--stdin"],
+            [git_path, "check-ignore", "--stdin"],
            cwd=self.project_dir,
            input="\n".join(staged_files),
            capture_output=True,
@@ -194,7 +201,7 @@ class WorktreeManager:

    def setup(self) -> None:
        """Create worktrees directory if needed."""
-        self.worktrees_dir.mkdir(exist_ok=True)
+        self.worktrees_dir.mkdir(parents=True, exist_ok=True)

    # ==================== Per-Spec Worktree Methods ====================

@@ -478,14 +485,12 @@ class WorktreeManager:
        """List all spec worktrees."""
        worktrees = []

-        if not self.worktrees_dir.exists():
-            return worktrees
-
-        for item in self.worktrees_dir.iterdir():
-            if item.is_dir():
-                info = self.get_worktree_info(item.name)
-                if info:
-                    worktrees.append(info)
+        if self.worktrees_dir.exists():
+            for item in self.worktrees_dir.iterdir():
+                if item.is_dir():
+                    info = self.get_worktree_info(item.name)
+                    if info:
+                        worktrees.append(info)

        return worktrees

@@ -587,81 +592,12 @@ class WorktreeManager:

        return commands

-    # ==================== Backward Compatibility ====================
-    # These methods provide backward compatibility with the old single-worktree API
-
-    def get_staging_path(self) -> Path | None:
-        """
-        Backward compatibility: Get path to any existing spec worktree.
-        Prefer using get_worktree_path(spec_name) instead.
-        """
-        worktrees = self.list_all_worktrees()
-        if worktrees:
-            return worktrees[0].path
-        return None
-
-    def get_staging_info(self) -> WorktreeInfo | None:
-        """
-        Backward compatibility: Get info about any existing spec worktree.
-        Prefer using get_worktree_info(spec_name) instead.
-        """
-        worktrees = self.list_all_worktrees()
-        if worktrees:
-            return worktrees[0]
-        return None
-
-    def merge_staging(self, delete_after: bool = True) -> bool:
-        """
-        Backward compatibility: Merge first found worktree.
-        Prefer using merge_worktree(spec_name) instead.
-        """
-        worktrees = self.list_all_worktrees()
-        if worktrees:
-            return self.merge_worktree(worktrees[0].spec_name, delete_after)
-        return False
-
-    def remove_staging(self, delete_branch: bool = True) -> None:
-        """
-        Backward compatibility: Remove first found worktree.
-        Prefer using remove_worktree(spec_name) instead.
-        """
-        worktrees = self.list_all_worktrees()
-        if worktrees:
-            self.remove_worktree(worktrees[0].spec_name, delete_branch)
-
-    def get_or_create_staging(self, spec_name: str) -> WorktreeInfo:
-        """
-        Backward compatibility: Alias for get_or_create_worktree.
-        """
-        return self.get_or_create_worktree(spec_name)
-
-    def staging_exists(self) -> bool:
-        """
-        Backward compatibility: Check if any spec worktree exists.
-        Prefer using worktree_exists(spec_name) instead.
-        """
-        return len(self.list_all_worktrees()) > 0
-
-    def commit_in_staging(self, message: str) -> bool:
-        """
-        Backward compatibility: Commit in first found worktree.
-        Prefer using commit_in_worktree(spec_name, message) instead.
-        """
-        worktrees = self.list_all_worktrees()
-        if worktrees:
-            return self.commit_in_worktree(worktrees[0].spec_name, message)
-        return False
-
-    def has_uncommitted_changes(self, in_staging: bool = False) -> bool:
+    def has_uncommitted_changes(self, spec_name: str | None = None) -> bool:
        """Check if there are uncommitted changes."""
-        worktrees = self.list_all_worktrees()
-        if in_staging and worktrees:
-            cwd = worktrees[0].path
-        else:
-            cwd = None
+        cwd = None
+        if spec_name:
+            worktree_path = self.get_worktree_path(spec_name)
+            if worktree_path.exists():
+                cwd = worktree_path
        result = self._run_git(["status", "--porcelain"], cwd=cwd)
        return bool(result.stdout.strip())
-
-
-# Keep STAGING_WORKTREE_NAME for backward compatibility in imports
-STAGING_WORKTREE_NAME = "auto-claude"
@@ -25,7 +25,7 @@ class IdeationConfigManager:
        include_roadmap_context: bool = True,
        include_kanban_context: bool = True,
        max_ideas_per_type: int = 5,
-        model: str = "claude-opus-4-5-20251101",
+        model: str = "sonnet",  # Changed from "opus" (fix #433)
        thinking_level: str = "medium",
        refresh: bool = False,
        append: bool = False,
@@ -17,7 +17,7 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).parent.parent))

 from client import create_client
-from phase_config import get_thinking_budget
+from phase_config import get_thinking_budget, resolve_model_id
 from ui import print_status

 # Ideation types
@@ -56,7 +56,7 @@ class IdeationGenerator:
        self,
        project_dir: Path,
        output_dir: Path,
-        model: str = "claude-opus-4-5-20251101",
+        model: str = "sonnet",  # Changed from "opus" (fix #433)
        thinking_level: str = "medium",
        max_ideas_per_type: int = 5,
    ):
@@ -94,7 +94,7 @@ class IdeationGenerator:
        client = create_client(
            self.project_dir,
            self.output_dir,
-            self.model,
+            resolve_model_id(self.model),
            max_thinking_tokens=self.thinking_budget,
        )

@@ -187,7 +187,7 @@ Write the fixed JSON to the file now.
        client = create_client(
            self.project_dir,
            self.output_dir,
-            self.model,
+            resolve_model_id(self.model),
            max_thinking_tokens=self.thinking_budget,
        )

@@ -41,7 +41,7 @@ class IdeationOrchestrator:
        include_roadmap_context: bool = True,
        include_kanban_context: bool = True,
        max_ideas_per_type: int = 5,
-        model: str = "claude-opus-4-5-20251101",
+        model: str = "sonnet",  # Changed from "opus" (fix #433)
        thinking_level: str = "medium",
        refresh: bool = False,
        append: bool = False,
@@ -31,6 +31,6 @@ class IdeationConfig:
    include_roadmap_context: bool = True
    include_kanban_context: bool = True
    max_ideas_per_type: int = 5
-    model: str = "claude-opus-4-5-20251101"
+    model: str = "sonnet"  # Changed from "opus" (fix #433)
    refresh: bool = False
    append: bool = False  # If True, preserve existing ideas when merging
@@ -118,6 +118,7 @@ def _create_linear_client() -> ClaudeSDKClient:
        get_sdk_env_vars,
        require_auth_token,
    )
+    from phase_config import resolve_model_id

    require_auth_token()  # Raises ValueError if no token found
    ensure_claude_code_oauth_token()
@@ -130,7 +131,7 @@ def _create_linear_client() -> ClaudeSDKClient:

    return ClaudeSDKClient(
        options=ClaudeAgentOptions(
-            model="claude-haiku-4-5",  # Fast & cheap model for simple API calls
+            model=resolve_model_id("haiku"),  # Resolves via API Profile if configured
            system_prompt="You are a Linear API assistant. Execute the requested Linear operation precisely.",
            allowed_tools=LINEAR_TOOLS,
            mcp_servers={
@@ -15,6 +15,8 @@ import subprocess
 from datetime import datetime
 from pathlib import Path

+from core.git_bash import get_git_executable_path
+
 from ..types import FileEvolution, TaskSnapshot, compute_content_hash
 from .storage import EvolutionStorage

@@ -93,8 +95,9 @@ class BaselineCapture:
            List of absolute paths to trackable files
        """
        try:
+            git_path = get_git_executable_path()
            result = subprocess.run(
-                ["git", "ls-files"],
+                [git_path, "ls-files"],
                cwd=self.storage.project_dir,
                capture_output=True,
                text=True,
@@ -124,8 +127,9 @@ class BaselineCapture:
            Git commit SHA, or "unknown" if not available
        """
        try:
+            git_path = get_git_executable_path()
            result = subprocess.run(
-                ["git", "rev-parse", "HEAD"],
+                [git_path, "rev-parse", "HEAD"],
                cwd=self.storage.project_dir,
                capture_output=True,
                text=True,
@@ -15,6 +15,8 @@ import subprocess
 from datetime import datetime
 from pathlib import Path

+from core.git_bash import get_git_executable_path
+
 from ..semantic_analyzer import SemanticAnalyzer
 from ..types import FileEvolution, TaskSnapshot, compute_content_hash
 from .storage import EvolutionStorage
@@ -157,9 +159,10 @@ class ModificationTracker:
        )

        try:
+            git_path = get_git_executable_path()
            # Get list of files changed in the worktree vs target branch
            result = subprocess.run(
-                ["git", "diff", "--name-only", f"{target_branch}...HEAD"],
+                [git_path, "diff", "--name-only", f"{target_branch}...HEAD"],
                cwd=worktree_path,
                capture_output=True,
                text=True,
@@ -178,7 +181,7 @@ class ModificationTracker:
            for file_path in changed_files:
                # Get the diff for this file
                diff_result = subprocess.run(
-                    ["git", "diff", f"{target_branch}...HEAD", "--", file_path],
+                    [git_path, "diff", f"{target_branch}...HEAD", "--", file_path],
                    cwd=worktree_path,
                    capture_output=True,
                    text=True,
@@ -188,7 +191,7 @@ class ModificationTracker:
                # Get content before (from target branch) and after (current)
                try:
                    show_result = subprocess.run(
-                        ["git", "show", f"{target_branch}:{file_path}"],
+                        [git_path, "show", f"{target_branch}:{file_path}"],
                        cwd=worktree_path,
                        capture_output=True,
                        text=True,
@@ -259,10 +262,12 @@ class ModificationTracker:
        Returns:
            The detected target branch name, defaults to 'main' if detection fails
        """
+        git_path = get_git_executable_path()
+
        # Try to get the upstream tracking branch
        try:
            result = subprocess.run(
-                ["git", "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"],
+                [git_path, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"],
                cwd=worktree_path,
                capture_output=True,
                text=True,
@@ -280,7 +285,7 @@ class ModificationTracker:
        for branch in ["main", "master", "develop"]:
            try:
                result = subprocess.run(
-                    ["git", "merge-base", branch, "HEAD"],
+                    [git_path, "merge-base", branch, "HEAD"],
                    cwd=worktree_path,
                    capture_output=True,
                    text=True,
@@ -45,7 +45,8 @@ def apply_single_task_changes(
            # Addition - need to determine where to add
            if change.change_type == ChangeType.ADD_IMPORT:
                # Add import at top
-                lines = content.split("\n")
+                # Use splitlines() to handle all line ending styles (LF, CRLF, CR)
+                lines = content.splitlines()
                import_end = find_import_end(lines, file_path)
                lines.insert(import_end, change.content_after)
                content = "\n".join(lines)
@@ -96,7 +97,8 @@ def combine_non_conflicting_changes(

    # Add imports
    if imports:
-        lines = content.split("\n")
+        # Use splitlines() to handle all line ending styles (LF, CRLF, CR)
+        lines = content.splitlines()
        import_end = find_import_end(lines, file_path)
        for imp in imports:
            if imp.content_after and imp.content_after not in content:
@@ -15,6 +15,8 @@ from __future__ import annotations
 import subprocess
 from pathlib import Path

+from core.git_bash import get_git_executable_path
+

 def find_worktree(project_dir: Path, task_id: str) -> Path | None:
    """
@@ -27,28 +29,19 @@ def find_worktree(project_dir: Path, task_id: str) -> Path | None:
    Returns:
        Path to the worktree, or None if not found
    """
-    # Check common locations
-    worktrees_dir = project_dir / ".worktrees"
-    if worktrees_dir.exists():
-        # Look for worktree with task_id in name
-        for entry in worktrees_dir.iterdir():
+    # Check new path first
+    new_worktrees_dir = project_dir / ".auto-claude" / "worktrees" / "tasks"
+    if new_worktrees_dir.exists():
+        for entry in new_worktrees_dir.iterdir():
            if entry.is_dir() and task_id in entry.name:
                return entry

-    # Try git worktree list
-    try:
-        result = subprocess.run(
-            ["git", "worktree", "list", "--porcelain"],
-            cwd=project_dir,
-            capture_output=True,
-            text=True,
-            check=True,
-        )
-        for line in result.stdout.split("\n"):
-            if line.startswith("worktree ") and task_id in line:
-                return Path(line.split(" ", 1)[1])
-    except subprocess.CalledProcessError:
-        pass
+    # Legacy fallback for backwards compatibility
+    legacy_worktrees_dir = project_dir / ".worktrees"
+    if legacy_worktrees_dir.exists():
+        for entry in legacy_worktrees_dir.iterdir():
+            if entry.is_dir() and task_id in entry.name:
+                return entry

    return None

@@ -66,8 +59,9 @@ def get_file_from_branch(project_dir: Path, file_path: str, branch: str) -> str
        File content as string, or None if file doesn't exist on branch
    """
    try:
+        git_path = get_git_executable_path()
        result = subprocess.run(
-            ["git", "show", f"{branch}:{file_path}"],
+            [git_path, "show", f"{branch}:{file_path}"],
            cwd=project_dir,
            capture_output=True,
            text=True,
@@ -30,11 +30,16 @@ def analyze_with_regex(
    """
    changes: list[SemanticChange] = []

+    # Normalize line endings to LF for consistent cross-platform behavior
+    # This handles Windows CRLF, old Mac CR, and Unix LF
+    before_normalized = before.replace("\r\n", "\n").replace("\r", "\n")
+    after_normalized = after.replace("\r\n", "\n").replace("\r", "\n")
+
    # Get a unified diff
    diff = list(
        difflib.unified_diff(
-            before.splitlines(keepends=True),
-            after.splitlines(keepends=True),
+            before_normalized.splitlines(keepends=True),
+            after_normalized.splitlines(keepends=True),
            lineterm="",
        )
    )
@@ -89,8 +94,22 @@ def analyze_with_regex(
    # Detect function changes (simplified)
    func_pattern = get_function_pattern(ext)
    if func_pattern:
-        funcs_before = set(func_pattern.findall(before))
-        funcs_after = set(func_pattern.findall(after))
+        # For JS/TS patterns with alternation, findall() returns tuples
+        # Extract the non-empty match from each tuple
+        def extract_func_names(matches):
+            names = set()
+            for match in matches:
+                if isinstance(match, tuple):
+                    # Get the first non-empty group from the tuple
+                    name = next((m for m in match if m), None)
+                    if name:
+                        names.add(name)
+                elif match:
+                    names.add(match)
+            return names
+
+        funcs_before = extract_func_names(func_pattern.findall(before_normalized))
+        funcs_after = extract_func_names(func_pattern.findall(after_normalized))

        for func in funcs_after - funcs_before:
            changes.append(
@@ -211,12 +211,18 @@ class SemanticAnalyzer:
        """Analyze using tree-sitter AST parsing."""
        parser = self._parsers[ext]

-        tree_before = parser.parse(bytes(before, "utf-8"))
-        tree_after = parser.parse(bytes(after, "utf-8"))
+        # Normalize line endings to LF for consistent cross-platform behavior
+        # This ensures byte positions and line counts work correctly on all platforms
+        before_normalized = before.replace("\r\n", "\n").replace("\r", "\n")
+        after_normalized = after.replace("\r\n", "\n").replace("\r", "\n")
+
+        tree_before = parser.parse(bytes(before_normalized, "utf-8"))
+        tree_after = parser.parse(bytes(after_normalized, "utf-8"))

        # Extract structural elements from both versions
-        elements_before = self._extract_elements(tree_before, before, ext)
-        elements_after = self._extract_elements(tree_after, after, ext)
+        # Use normalized content to match tree-sitter byte positions
+        elements_before = self._extract_elements(tree_before, before_normalized, ext)
+        elements_after = self._extract_elements(tree_after, after_normalized, ext)

        # Compare and generate semantic changes
        changes = compare_elements(elements_before, elements_after, ext)
@@ -17,6 +17,8 @@ import logging
 import subprocess
 from pathlib import Path

+from core.git_bash import get_git_executable_path
+
 logger = logging.getLogger(__name__)

 # Import debug utilities
@@ -56,8 +58,9 @@ class TimelineGitHelper:
    def get_current_main_commit(self) -> str:
        """Get the current HEAD commit on main branch."""
        try:
+            git_path = get_git_executable_path()
            result = subprocess.run(
-                ["git", "rev-parse", "HEAD"],
+                [git_path, "rev-parse", "HEAD"],
                cwd=self.project_path,
                capture_output=True,
                text=True,
@@ -81,8 +84,9 @@ class TimelineGitHelper:
            File content as string, or None if file doesn't exist at that commit
        """
        try:
+            git_path = get_git_executable_path()
            result = subprocess.run(
-                ["git", "show", f"{commit_hash}:{file_path}"],
+                [git_path, "show", f"{commit_hash}:{file_path}"],
                cwd=self.project_path,
                capture_output=True,
                text=True,
@@ -104,9 +108,10 @@ class TimelineGitHelper:
            List of file paths changed in the commit
        """
        try:
+            git_path = get_git_executable_path()
            result = subprocess.run(
                [
-                    "git",
+                    git_path,
                    "diff-tree",
                    "--no-commit-id",
                    "--name-only",
@@ -134,9 +139,11 @@ class TimelineGitHelper:
        """
        info = {}
        try:
+            git_path = get_git_executable_path()
+
            # Get commit message
            result = subprocess.run(
-                ["git", "log", "-1", "--format=%s", commit_hash],
+                [git_path, "log", "-1", "--format=%s", commit_hash],
                cwd=self.project_path,
                capture_output=True,
                text=True,
@@ -146,7 +153,7 @@ class TimelineGitHelper:

            # Get author
            result = subprocess.run(
-                ["git", "log", "-1", "--format=%an", commit_hash],
+                [git_path, "log", "-1", "--format=%an", commit_hash],
                cwd=self.project_path,
                capture_output=True,
                text=True,
@@ -156,7 +163,7 @@ class TimelineGitHelper:

            # Get diff stat
            result = subprocess.run(
-                ["git", "diff-tree", "--stat", "--no-commit-id", commit_hash],
+                [git_path, "diff-tree", "--stat", "--no-commit-id", commit_hash],
                cwd=self.project_path,
                capture_output=True,
                text=True,
@@ -189,7 +196,14 @@ class TimelineGitHelper:
            task_id.replace("task-", "") if task_id.startswith("task-") else task_id
        )

-        worktree_path = self.project_path / ".worktrees" / spec_name / file_path
+        worktree_path = (
+            self.project_path
+            / ".auto-claude"
+            / "worktrees"
+            / "tasks"
+            / spec_name
+            / file_path
+        )
        if worktree_path.exists():
            try:
                return worktree_path.read_text(encoding="utf-8")
@@ -214,8 +228,9 @@ class TimelineGitHelper:
            target_branch = self._detect_target_branch(worktree_path)

        try:
+            git_path = get_git_executable_path()
            result = subprocess.run(
-                ["git", "diff", "--name-only", f"{target_branch}...HEAD"],
+                [git_path, "diff", "--name-only", f"{target_branch}...HEAD"],
                cwd=worktree_path,
                capture_output=True,
                text=True,
@@ -247,8 +262,9 @@ class TimelineGitHelper:
            target_branch = self._detect_target_branch(worktree_path)

        try:
+            git_path = get_git_executable_path()
            result = subprocess.run(
-                ["git", "merge-base", target_branch, "HEAD"],
+                [git_path, "merge-base", target_branch, "HEAD"],
                cwd=worktree_path,
                capture_output=True,
                text=True,
@@ -277,10 +293,12 @@ class TimelineGitHelper:
        Returns:
            The detected target branch name, defaults to 'main' if detection fails
        """
+        git_path = get_git_executable_path()
+
        # Try to get the upstream tracking branch
        try:
            result = subprocess.run(
-                ["git", "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"],
+                [git_path, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"],
                cwd=worktree_path,
                capture_output=True,
                text=True,
@@ -298,7 +316,7 @@ class TimelineGitHelper:
        for branch in ["main", "master", "develop"]:
            try:
                result = subprocess.run(
-                    ["git", "merge-base", branch, "HEAD"],
+                    [git_path, "merge-base", branch, "HEAD"],
                    cwd=worktree_path,
                    capture_output=True,
                    text=True,
@@ -323,8 +341,9 @@ class TimelineGitHelper:
            Number of commits between the two points
        """
        try:
+            git_path = get_git_executable_path()
            result = subprocess.run(
-                ["git", "rev-list", "--count", f"{from_commit}..{to_commit}"],
+                [git_path, "rev-list", "--count", f"{from_commit}..{to_commit}"],
                cwd=self.project_path,
                capture_output=True,
                text=True,
@@ -7,6 +7,7 @@ Reads configuration from task_metadata.json and provides resolved model IDs.
 """

 import json
+import os
 from pathlib import Path
 from typing import Literal, TypedDict

@@ -46,10 +47,10 @@ SPEC_PHASE_THINKING_LEVELS: dict[str, str] = {
    "complexity_assessment": "medium",
 }

-# Default phase configuration (matches UI defaults)
+# Default phase configuration (fallback, matches 'Balanced' profile)
 DEFAULT_PHASE_MODELS: dict[str, str] = {
    "spec": "sonnet",
-    "planning": "opus",
+    "planning": "sonnet",  # Changed from "opus" (fix #433)
    "coding": "sonnet",
    "qa": "sonnet",
 }
@@ -94,17 +95,34 @@ def resolve_model_id(model: str) -> str:
    Resolve a model shorthand (haiku, sonnet, opus) to a full model ID.
    If the model is already a full ID, return it unchanged.

+    Priority:
+    1. Environment variable override (from API Profile)
+    2. Hardcoded MODEL_ID_MAP
+    3. Pass through unchanged (assume full model ID)
+
    Args:
        model: Model shorthand or full ID

    Returns:
        Full Claude model ID
    """
-    # Check if it's a shorthand
+    # Check for environment variable override (from API Profile custom model mappings)
    if model in MODEL_ID_MAP:
+        env_var_map = {
+            "haiku": "ANTHROPIC_DEFAULT_HAIKU_MODEL",
+            "sonnet": "ANTHROPIC_DEFAULT_SONNET_MODEL",
+            "opus": "ANTHROPIC_DEFAULT_OPUS_MODEL",
+        }
+        env_var = env_var_map.get(model)
+        if env_var:
+            env_value = os.environ.get(env_var)
+            if env_value:
+                return env_value
+
+        # Fall back to hardcoded mapping
        return MODEL_ID_MAP[model]

-    # Already a full model ID
+    # Already a full model ID or unknown shorthand
    return model


@@ -173,12 +173,16 @@ LANGUAGE_COMMANDS: dict[str, set[str]] = {
        "zig",
    },
    "dart": {
+        # Core Dart CLI (modern unified tool)
        "dart",
+        "pub",
+        # Flutter CLI (included in Dart language for SDK detection)
+        "flutter",
+        # Legacy commands (deprecated but may exist in older projects)
        "dart2js",
        "dartanalyzer",
        "dartdoc",
        "dartfmt",
-        "pub",
    },
 }

@@ -33,6 +33,9 @@ PACKAGE_MANAGER_COMMANDS: dict[str, set[str]] = {
    "brew": {"brew"},
    "apt": {"apt", "apt-get", "dpkg"},
    "nix": {"nix", "nix-shell", "nix-build", "nix-env"},
+    # Dart/Flutter package managers
+    "pub": {"pub", "dart"},
+    "melos": {"melos", "dart", "flutter"},
 }


@@ -23,6 +23,8 @@ VERSION_MANAGER_COMMANDS: dict[str, set[str]] = {
    "rustup": {"rustup"},
    "sdkman": {"sdk"},
    "jabba": {"jabba"},
+    # Dart/Flutter version managers
+    "fvm": {"fvm", "flutter"},
 }


@@ -164,6 +164,12 @@ class StackDetector:
        if self.parser.file_exists("build.gradle", "build.gradle.kts"):
            self.stack.package_managers.append("gradle")

+        # Dart/Flutter package managers
+        if self.parser.file_exists("pubspec.yaml", "pubspec.lock"):
+            self.stack.package_managers.append("pub")
+        if self.parser.file_exists("melos.yaml"):
+            self.stack.package_managers.append("melos")
+
    def detect_databases(self) -> None:
        """Detect databases from config files and dependencies."""
        # Check for database config files
@@ -358,3 +364,6 @@ class StackDetector:
            self.stack.version_managers.append("rbenv")
        if self.parser.file_exists("rust-toolchain.toml", "rust-toolchain"):
            self.stack.version_managers.append("rustup")
+        # Flutter Version Manager
+        if self.parser.file_exists(".fvm", ".fvmrc", "fvm_config.json"):
+            self.stack.version_managers.append("fvm")
@@ -6,6 +6,23 @@ 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.

+## CRITICAL: PR Scope and Context
+
+### What IS in scope (report these issues):
+1. **Codebase fit issues in changed code** - New code not following project patterns
+2. **Missed reuse opportunities** - "Existing `utils.ts` has a helper for this"
+3. **Inconsistent with PR's own changes** - "You used `camelCase` here but `snake_case` elsewhere in the PR"
+4. **Breaking conventions in touched areas** - "Your change deviates from the pattern in this file"
+
+### What is NOT in scope (do NOT report):
+1. **Pre-existing inconsistencies** - Old code that doesn't follow patterns
+2. **Unrelated suggestions** - Don't suggest patterns for code the PR didn't touch
+
+**Key distinction:**
+- ✅ "Your new component doesn't follow the existing pattern in `components/`" - GOOD
+- ✅ "Consider using existing `formatDate()` helper instead of new implementation" - GOOD
+- ❌ "The old `legacy/` folder uses different naming conventions" - BAD (pre-existing)
+
 ## Codebase Fit Focus Areas

 ### 1. Naming Conventions
@@ -1,16 +1,37 @@
 # Finding Validator Agent

-You are a finding re-investigator. For each unresolved finding from a previous PR review, you must actively investigate whether it is a REAL issue or a FALSE POSITIVE.
+You are a finding re-investigator using EVIDENCE-BASED VALIDATION. For each unresolved finding from a previous PR review, you must actively investigate whether it is a REAL issue or a FALSE POSITIVE.
+
+**Core Principle: Evidence, not confidence scores.** Either you can prove the issue exists with actual code, or you can't. There is no middle ground.

 Your job is to prevent false positives from persisting indefinitely by actually reading the code and verifying the issue exists.

+## CRITICAL: Check PR Scope First
+
+**Before investigating any finding, verify it's within THIS PR's scope:**
+
+1. **Check if the file is in the PR's changed files list** - If not, likely out-of-scope
+2. **Check if the line number exists** - If finding cites line 710 but file has 600 lines, it's hallucinated
+3. **Check for PR references in commit messages** - Commits like `fix: something (#584)` are from OTHER PRs
+
+**Dismiss findings as `dismissed_false_positive` if:**
+- The finding references a file NOT in the PR's changed files list AND is not about impact on that file
+- The line number doesn't exist in the file (hallucinated)
+- The finding is about code from a merged branch commit (not this PR's work)
+
+**Keep findings valid if they're about:**
+- Issues in code the PR actually changed
+- Impact of PR changes on other code (e.g., "this change breaks callers in X")
+- Missing updates to related code (e.g., "you updated A but forgot B")
+
 ## Your Mission

 For each finding you receive:
-1. **READ** the actual code at the file/line location using the Read tool
-2. **ANALYZE** whether the described issue actually exists in the code
-3. **PROVIDE** concrete code evidence for your conclusion
-4. **RETURN** validation status with evidence
+1. **VERIFY SCOPE** - Is this file/line actually part of this PR?
+2. **READ** the actual code at the file/line location using the Read tool
+3. **ANALYZE** whether the described issue actually exists in the code
+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)

 ## Investigation Process

@@ -24,45 +45,61 @@ Read the file: {finding.file}
 Focus on lines around: {finding.line}
 ```

-### Step 2: Analyze with Fresh Eyes
+### Step 2: Analyze with Fresh Eyes - NEVER ASSUME

-**Do NOT assume the original finding is correct.** Ask yourself:
- Does the code ACTUALLY have this issue?
- Is the described vulnerability/bug/problem present?
- Could the original reviewer have misunderstood the code?
- Is there context that makes this NOT an issue (e.g., sanitization elsewhere)?
+**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
+- Missed validation/sanitization in callers or surrounding code
+- Made assumptions without actually reading the implementation
+- Confused similar-looking code patterns

-Be skeptical. The original review may have hallucinated this finding.
+**You MUST actively verify by asking:**
+- Does the code at this exact line ACTUALLY have this issue?
+- Did I READ the actual implementation, not just the function name?
+- Is there validation/sanitization BEFORE this code is reached?
+- Is there framework protection I'm not accounting for?
+- Does this line number even EXIST in the file?
+
+**NEVER:**
+- Trust the finding description without reading the code
+- Assume a function is vulnerable based on its name
+- Skip checking surrounding context (±20 lines minimum)
+- Confirm a finding just because "it sounds plausible"
+
+Be HIGHLY skeptical. AI reviews frequently produce false positives. Your job is to catch them.

 ### Step 3: Document Evidence

 You MUST provide concrete evidence:
- **Exact code snippet** you examined (copy-paste from the file)
+- **Exact code snippet** you examined (copy-paste from the file) - this is the PROOF
 - **Line numbers** where you found (or didn't find) the issue
- **Your analysis** of whether the issue exists
- **Confidence level** (0.0-1.0) in your conclusion
+- **Your analysis** connecting the code to your conclusion
+- **Verification flag** - did this code actually exist at the specified location?

 ## Validation Statuses

 ### `confirmed_valid`
-Use when you verify the issue IS real:
+Use when your code evidence PROVES the issue IS real:
 - The problematic code pattern exists exactly as described
- The vulnerability/bug is present and exploitable
+- You can point to the specific lines showing the vulnerability/bug
 - The code quality issue genuinely impacts the codebase
+- **Key question**: Does your code_evidence field contain the actual problematic code?

 ### `dismissed_false_positive`
-Use when you verify the issue does NOT exist:
- The described code pattern is not actually present
- The original finding misunderstood the code
- There is mitigating code that prevents the issue (e.g., input validation elsewhere)
- The finding was based on incorrect assumptions
+Use when your code evidence PROVES the issue does NOT exist:
+- The described code pattern is not actually present (code_evidence shows different code)
+- There is mitigating code that prevents the issue (code_evidence shows the mitigation)
+- The finding was based on incorrect assumptions (code_evidence shows reality)
+- The line number doesn't exist or contains different code than claimed
+- **Key question**: Does your code_evidence field show code that disproves the original finding?

 ### `needs_human_review`
-Use when you cannot determine with confidence:
- The issue requires runtime analysis to verify
+Use when you CANNOT find definitive evidence either way:
+- The issue requires runtime analysis to verify (static code doesn't prove/disprove)
 - The code is too complex to analyze statically
- You have conflicting evidence
- Your confidence is below 0.70
+- You found the code but can't determine if it's actually a problem
+- **Key question**: Is your code_evidence inconclusive?

 ## Output Format

@@ -75,7 +112,7 @@ Return one result per finding:
  "code_evidence": "const query = `SELECT * FROM users WHERE id = ${userId}`;",
  "line_range": [45, 45],
  "explanation": "SQL injection vulnerability confirmed. User input 'userId' is directly interpolated into the SQL query at line 45 without any sanitization. The query is executed via db.execute() on line 46.",
-  "confidence": 0.95
+  "evidence_verified_in_file": true
 }
 ```

@@ -85,8 +122,8 @@ Return one result per finding:
  "validation_status": "dismissed_false_positive",
  "code_evidence": "function processInput(data: string): string {\n  const sanitized = DOMPurify.sanitize(data);\n  return sanitized;\n}",
  "line_range": [23, 26],
-  "explanation": "The original finding claimed XSS vulnerability, but the code uses DOMPurify.sanitize() before output. The input is properly sanitized at line 24 before being returned.",
-  "confidence": 0.88
+  "explanation": "The original finding claimed XSS vulnerability, but the code uses DOMPurify.sanitize() before output. The input is properly sanitized at line 24 before being returned. The code evidence proves the issue does NOT exist.",
+  "evidence_verified_in_file": true
 }
 ```

@@ -96,38 +133,56 @@ Return one result per finding:
  "validation_status": "needs_human_review",
  "code_evidence": "async function handleRequest(req) {\n  // Complex async logic...\n}",
  "line_range": [100, 150],
-  "explanation": "The original finding claims a race condition, but verifying this requires understanding the runtime behavior and concurrency model. Cannot determine statically.",
-  "confidence": 0.45
+  "explanation": "The original finding claims a race condition, but verifying this requires understanding the runtime behavior and concurrency model. The static code doesn't provide definitive evidence either way.",
+  "evidence_verified_in_file": true
 }
 ```

-## Confidence Guidelines
+```json
+{
+  "finding_id": "HALLUC-004",
+  "validation_status": "dismissed_false_positive",
+  "code_evidence": "// Line 710 does not exist - file only has 600 lines",
+  "line_range": [600, 600],
+  "explanation": "The original finding claimed an issue at line 710, but the file only has 600 lines. This is a hallucinated finding - the code doesn't exist.",
+  "evidence_verified_in_file": false
+}
+```

-Rate your confidence based on how certain you are:
+## Evidence Guidelines

-| Confidence | Meaning |
-|------------|---------|
-| 0.90-1.00 | Definitive evidence - code clearly shows the issue exists/doesn't exist |
-| 0.80-0.89 | Strong evidence - high confidence with minor uncertainty |
-| 0.70-0.79 | Moderate evidence - likely correct but some ambiguity |
-| 0.50-0.69 | Uncertain - use `needs_human_review` |
-| Below 0.50 | Insufficient evidence - must use `needs_human_review` |
+Validation is binary based on what the code evidence shows:

-**Minimum thresholds:**
- To confirm as `confirmed_valid`: confidence >= 0.70
- To dismiss as `dismissed_false_positive`: confidence >= 0.80 (higher bar for dismissal)
- If below thresholds: must use `needs_human_review`
+| Scenario | Status | Evidence Required |
+|----------|--------|-------------------|
+| Code shows the exact problem claimed | `confirmed_valid` | Problematic code snippet |
+| Code shows issue doesn't exist or is mitigated | `dismissed_false_positive` | Code proving issue is absent |
+| Code couldn't be found (hallucinated line/file) | `dismissed_false_positive` | Note that code doesn't exist |
+| Code found but can't prove/disprove statically | `needs_human_review` | The inconclusive code |
+
+**Decision rules:**
+- If `code_evidence` contains problematic code → `confirmed_valid`
+- If `code_evidence` proves issue doesn't exist → `dismissed_false_positive`
+- If `evidence_verified_in_file` is false → `dismissed_false_positive` (hallucinated finding)
+- If you can't determine from the code → `needs_human_review`

 ## Common False Positive Patterns

 Watch for these patterns that often indicate false positives:

-1. **Sanitization elsewhere**: Input is validated/sanitized before reaching the flagged code
-2. **Internal-only code**: Code only handles trusted internal data, not user input
-3. **Framework protection**: Framework provides automatic protection (e.g., ORM parameterization)
-4. **Dead code**: The flagged code is never executed in the current codebase
-5. **Test code**: The issue is in test files where it's acceptable
-6. **Misread syntax**: Original reviewer misunderstood the language syntax
+1. **Non-existent line number**: The line number cited doesn't exist or is beyond EOF - hallucinated finding
+2. **Merged branch code**: Finding is about code from a commit like `fix: something (#584)` - another PR
+3. **Pre-existing issue, not impact**: Finding flags old bug in untouched code without showing how PR changes relate
+4. **Sanitization elsewhere**: Input is validated/sanitized before reaching the flagged code
+5. **Internal-only code**: Code only handles trusted internal data, not user input
+6. **Framework protection**: Framework provides automatic protection (e.g., ORM parameterization)
+7. **Dead code**: The flagged code is never executed in the current codebase
+8. **Test code**: The issue is in test files where it's acceptable
+9. **Misread syntax**: Original reviewer misunderstood the language syntax
+
+**Note**: Findings about files outside the PR's changed list are NOT automatically false positives if they're about:
+- Impact of PR changes on that file (e.g., "your change breaks X")
+- Missing related updates (e.g., "you forgot to update Y")

 ## Common Valid Issue Patterns

@@ -144,15 +199,16 @@ These patterns often confirm the issue is real:
 1. **ALWAYS read the actual code** - Never rely on memory or the original finding description
 2. **ALWAYS provide code_evidence** - No empty strings. Quote the actual code.
 3. **Be skeptical of original findings** - Many AI reviews produce false positives
-4. **Higher bar for dismissal** - Need 0.80 confidence to dismiss (vs 0.70 to confirm)
-5. **When uncertain, escalate** - Use `needs_human_review` rather than guessing
+4. **Evidence is binary** - The code either shows the problem or it doesn't
+5. **When evidence is inconclusive, escalate** - Use `needs_human_review` rather than guessing
 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

 ## Anti-Patterns to Avoid

- **Trusting the original finding blindly** - Always verify
- **Dismissing without reading code** - Must provide code_evidence
- **Low confidence dismissals** - Needs 0.80+ confidence to dismiss
- **Vague explanations** - Be specific about what you found
+- **Trusting the original finding blindly** - Always verify with actual code
+- **Dismissing without reading code** - Must provide code_evidence that proves your point
+- **Vague explanations** - Be specific about what the code shows and why it proves/disproves the issue
 - **Missing line numbers** - Always include line_range
+- **Speculative conclusions** - Only conclude what the code evidence actually proves
@@ -71,10 +71,12 @@ Review the diff since the last review for NEW issues:
 - Regressions that break previously working code
 - Missing error handling in new code paths

-**Apply the 80% confidence threshold:**
- Only report issues you're confident about
+**NEVER ASSUME - ALWAYS VERIFY:**
+- Actually READ the code before reporting any finding
+- Verify the issue exists at the exact line you cite
+- Check for validation/mitigation in surrounding code
 - Don't re-report issues from the previous review
- Focus on genuinely new problems
+- Focus on genuinely new problems with code EVIDENCE

 ### Phase 3: Comment Review

@@ -137,11 +139,11 @@ Return a JSON object with this structure:
      "id": "new-finding-1",
      "severity": "medium",
      "category": "security",
-      "confidence": 0.85,
      "title": "New hardcoded API key in config",
      "description": "A new API key was added in config.ts line 45 without using environment variables.",
      "file": "src/config.ts",
      "line": 45,
+      "evidence": "const API_KEY = 'sk-prod-abc123xyz789';",
      "suggested_fix": "Move to environment variable: process.env.EXTERNAL_API_KEY"
    }
  ],
@@ -175,11 +177,11 @@ Same format as initial review findings:
 - **id**: Unique identifier for new finding
 - **severity**: `critical` | `high` | `medium` | `low`
 - **category**: `security` | `quality` | `logic` | `test` | `docs` | `pattern` | `performance`
- **confidence**: Float 0.80-1.0
 - **title**: Short summary (max 80 chars)
 - **description**: Detailed explanation
 - **file**: Relative file path
 - **line**: Line number
+- **evidence**: **REQUIRED** - Actual code snippet proving the issue exists
 - **suggested_fix**: How to resolve

 ### verdict
@@ -11,6 +11,23 @@ Review the incremental diff for:
 4. Potential regressions
 5. Incomplete implementations

+## CRITICAL: PR Scope and Context
+
+### What IS in scope (report these issues):
+1. **Issues in changed code** - Problems in files/lines actually modified by this PR
+2. **Impact on unchanged code** - "This change breaks callers in `other_file.ts`"
+3. **Missing related changes** - "Similar pattern in `utils.ts` wasn't updated"
+4. **Incomplete implementations** - "New field added but not handled in serializer"
+
+### What is NOT in scope (do NOT report):
+1. **Pre-existing bugs** - Old bugs in code this PR didn't touch
+2. **Code from merged branches** - Commits with PR references like `(#584)` are from other PRs
+3. **Unrelated improvements** - Don't suggest refactoring untouched code
+
+**Key distinction:**
+- ✅ "Your change breaks the caller in `auth.ts`" - GOOD (impact analysis)
+- ❌ "The old code in `legacy.ts` has a bug" - BAD (pre-existing, not this PR)
+
 ## Focus Areas

 Since this is a follow-up review, focus on:
@@ -74,15 +91,29 @@ Since this is a follow-up review, focus on:
 - Minor optimizations
 - Documentation gaps

-## Confidence Scoring
+## NEVER ASSUME - ALWAYS VERIFY

-Rate confidence (0.0-1.0) based on:
- **>0.9**: Obvious, verifiable issue
- **0.8-0.9**: High confidence with clear evidence
- **0.7-0.8**: Likely issue but some uncertainty
- **<0.7**: Possible issue, needs verification
+**Before reporting ANY new finding:**

-Only report findings with confidence >0.7.
+1. **NEVER assume code is vulnerable** - Read the actual implementation
+2. **NEVER assume validation is missing** - Check callers and surrounding code
+3. **NEVER assume based on function names** - `unsafeQuery()` might actually be safe
+4. **NEVER report without reading the code** - Verify the issue exists at the exact line
+
+**You MUST:**
+- Actually READ the code at the file/line you cite
+- Verify there's no sanitization/validation before this code
+- Check for framework protections you might miss
+- Provide the actual code snippet as evidence
+
+## Evidence Requirements
+
+Every finding MUST include an `evidence` field with:
+- The actual problematic code copy-pasted from the diff
+- The specific line numbers where the issue exists
+- Proof that the issue is real, not speculative
+
+**No evidence = No finding**

 ## Output Format

@@ -99,7 +130,7 @@ Return findings in this structure:
    "description": "The new login validation query concatenates user input directly into the SQL string without sanitization.",
    "category": "security",
    "severity": "critical",
-    "confidence": 0.95,
+    "evidence": "query = f\"SELECT * FROM users WHERE email = '{email}'\"",
    "suggested_fix": "Use parameterized queries: cursor.execute('SELECT * FROM users WHERE email = ?', (email,))",
    "fixable": true,
    "source_agent": "new-code-reviewer",
@@ -113,7 +144,7 @@ Return findings in this structure:
    "description": "The fix for LOGIC-003 removed a null check that was protecting against undefined input. Now input.data can be null.",
    "category": "regression",
    "severity": "high",
-    "confidence": 0.88,
+    "evidence": "result = input.data.process()  # input.data can be null, was previously: if input and input.data:",
    "suggested_fix": "Restore null check: if (input && input.data) { ... }",
    "fixable": true,
    "source_agent": "new-code-reviewer",
@@ -9,6 +9,40 @@ Perform a focused, efficient follow-up review by:
 2. Delegating to specialized agents based on what needs verification
 3. Synthesizing findings into a final merge verdict

+## CRITICAL: PR Scope and Context
+
+### What IS in scope (report these issues):
+1. **Issues in changed code** - Problems in files/lines actually modified by this PR
+2. **Impact on unchanged code** - "You changed X but forgot to update Y that depends on it"
+3. **Missing related changes** - "This pattern also exists in Z, did you mean to update it too?"
+4. **Breaking changes** - "This change breaks callers in other files"
+
+### What is NOT in scope (do NOT report):
+1. **Pre-existing issues in unchanged code** - If old code has a bug but this PR didn't touch it, don't flag it
+2. **Code from merged branches** - Commits with PR references like `(#584)` are from OTHER already-reviewed PRs
+3. **Unrelated improvements** - Don't suggest refactoring code the PR didn't touch
+
+**Key distinction:**
+- ✅ "Your change to `validateUser()` breaks the caller in `auth.ts:45`" - GOOD (impact of PR changes)
+- ✅ "You updated this validation but similar logic in `utils.ts` wasn't updated" - GOOD (incomplete change)
+- ❌ "The existing code in `legacy.ts` has a SQL injection" - BAD (pre-existing issue, not this PR)
+- ❌ "This code from commit `fix: something (#584)` has an issue" - BAD (different PR)
+
+**Why this matters:**
+When authors merge the base branch into their feature branch, the commit range includes commits from other PRs. The context gathering system filters these out, but if any slip through, recognize them as out-of-scope.
+
+## Merge Conflicts
+
+**Check for merge conflicts in the follow-up context.** If `has_merge_conflicts` is `true`:
+
+1. **Report this prominently** - Merge conflicts block the PR from being merged
+2. **Add a CRITICAL finding** with category "merge_conflict" and severity "critical"
+3. **Include in verdict reasoning** - The PR cannot be merged until conflicts are resolved
+4. **This may be NEW since last review** - Base branch may have changed
+
+Note: GitHub's API tells us IF there are conflicts but not WHICH files. The finding should state:
+> "This PR has merge conflicts with the base branch that must be resolved before merging."
+
 ## Available Specialist Agents

 You have access to these specialist agents via the Task tool:
@@ -171,11 +205,30 @@ Provide your synthesis as a structured response matching the ParallelFollowupRes
 }
 ```

+## CRITICAL: NEVER ASSUME - ALWAYS VERIFY
+
+**This applies to ALL agents you invoke:**
+
+1. **NEVER assume a finding is valid** - The finding-validator MUST read the actual code
+2. **NEVER assume a fix is correct** - The resolution-verifier MUST verify the change
+3. **NEVER assume line numbers are accurate** - Files may be shorter than cited lines
+4. **NEVER assume validation is missing** - Check callers and surrounding code
+5. **NEVER trust the original finding's description** - It may have been hallucinated
+
+**Before ANY finding blocks merge:**
+- The actual code at that location MUST be read
+- The problematic pattern MUST exist as described
+- There MUST NOT be mitigation/validation elsewhere
+- The evidence MUST be copy-pasted from the actual file
+
+**Why this matters:** AI reviewers sometimes hallucinate findings. Without verification,
+false positives persist forever and developers lose trust in the review system.
+
 ## Important Notes

 1. **Be efficient**: Follow-up reviews should be faster than initial reviews
 2. **Focus on changes**: Only review what changed since last review
-3. **Trust but verify**: Don't assume fixes are correct just because files changed
+3. **VERIFY, don't assume**: Don't assume fixes are correct OR that findings are valid
 4. **Acknowledge progress**: Recognize genuine effort to address feedback
 5. **Be specific**: Clearly state what blocks merge if verdict is not READY_TO_MERGE

@@ -10,6 +10,23 @@ For each previous finding, determine whether it has been:
 - **unresolved**: The issue remains or wasn't addressed
 - **cant_verify**: Not enough information to determine status

+## CRITICAL: Verify Finding is In-Scope
+
+**Before verifying any finding, check if it's within THIS PR's scope:**
+
+1. **Is the file in the PR's changed files list?** - If not AND the finding isn't about impact, mark as `cant_verify`
+2. **Does the line number exist?** - If finding cites line 710 but file has 600 lines, it was hallucinated
+3. **Was this from a merged branch?** - Commits with PR references like `(#584)` are from other PRs
+
+**Mark as `cant_verify` if:**
+- Finding references a file not in PR AND is not about impact of PR changes on that file
+- Line number doesn't exist (hallucinated finding)
+- Finding is about code from another PR's commits
+
+**Findings can reference files outside the PR if they're about:**
+- Impact of PR changes (e.g., "change to X breaks caller in Y")
+- Missing related updates (e.g., "you updated A but forgot B")
+
 ## Verification Process

 For each previous finding:
@@ -31,12 +48,26 @@ If the file was modified:
 - Is the fix approach sound?
 - Are there edge cases the fix misses?

-### 4. Assign Confidence
-Rate your confidence (0.0-1.0):
- **>0.9**: Clear evidence of resolution/non-resolution
- **0.7-0.9**: Strong indicators but some uncertainty
- **0.5-0.7**: Mixed signals, moderate confidence
- **<0.5**: Unclear, consider marking as cant_verify
+### 4. Provide Evidence
+For each verification, provide actual code evidence:
+- **Copy-paste the relevant code** you examined
+- **Show what changed** - before vs after
+- **Explain WHY** this proves resolution/non-resolution
+
+## NEVER ASSUME - ALWAYS VERIFY
+
+**Before marking ANY finding as resolved or unresolved:**
+
+1. **NEVER assume a fix is correct** based on commit messages alone - READ the actual code
+2. **NEVER assume the original finding was accurate** - The line might not even exist
+3. **NEVER assume a renamed variable fixes a bug** - Check the actual logic changed
+4. **NEVER assume "file was modified" means "issue was fixed"** - Verify the specific fix
+
+**You MUST:**
+- Read the actual code at the cited location
+- Verify the problematic pattern no longer exists (for resolved)
+- Verify the pattern still exists (for unresolved)
+- Check surrounding context for alternative fixes you might miss

 ## Resolution Criteria

@@ -84,23 +115,20 @@ Return verifications in this structure:
  {
    "finding_id": "SEC-001",
    "status": "resolved",
-    "confidence": 0.92,
-    "evidence": "The SQL query at line 45 now uses parameterized queries instead of string concatenation. The fix properly escapes all user inputs.",
-    "resolution_notes": "Changed from f-string to cursor.execute() with parameters"
+    "evidence": "cursor.execute('SELECT * FROM users WHERE id = ?', (user_id,))",
+    "resolution_notes": "Changed from f-string to cursor.execute() with parameters. The code at line 45 now uses parameterized queries."
  },
  {
    "finding_id": "QUAL-002",
    "status": "partially_resolved",
-    "confidence": 0.75,
-    "evidence": "Error handling was added for the main path, but the fallback path at line 78 still lacks try-catch.",
+    "evidence": "try:\n    result = process(data)\nexcept Exception as e:\n    log.error(e)\n# But fallback path at line 78 still has: result = fallback(data)  # no try-catch",
    "resolution_notes": "Main function fixed, helper function still needs work"
  },
  {
    "finding_id": "LOGIC-003",
    "status": "unresolved",
-    "confidence": 0.88,
-    "evidence": "The off-by-one error remains. The loop still uses `<= length` instead of `< length`.",
-    "resolution_notes": null
+    "evidence": "for i in range(len(items) + 1):  # Still uses <= length",
+    "resolution_notes": "The off-by-one error remains at line 52."
  }
 ]
 ```
@@ -6,6 +6,23 @@ 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.

+## CRITICAL: PR Scope and Context
+
+### What IS in scope (report these issues):
+1. **Logic issues in changed code** - Bugs in files/lines modified by this PR
+2. **Logic impact of changes** - "This change breaks the assumption in `caller.ts:50`"
+3. **Incomplete state changes** - "You updated state X but forgot to reset Y"
+4. **Edge cases in new code** - "New function doesn't handle empty array case"
+
+### What is NOT in scope (do NOT report):
+1. **Pre-existing bugs** - Old logic issues in untouched code
+2. **Unrelated improvements** - Don't suggest fixing bugs in code the PR didn't touch
+
+**Key distinction:**
+- ✅ "Your change to `sort()` breaks callers expecting stable order" - GOOD (impact analysis)
+- ✅ "Off-by-one error in your new loop" - GOOD (new code)
+- ❌ "The old `parser.ts` has a race condition" - BAD (pre-existing, not this PR)
+
 ## Logic Focus Areas

 ### 1. Algorithm Correctness
@@ -6,6 +6,34 @@ You are an expert PR reviewer orchestrating a comprehensive, parallel code revie

 **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.

+## CRITICAL: PR Scope and Context
+
+### What IS in scope (report these issues):
+1. **Issues in changed code** - Problems in files/lines actually modified by this PR
+2. **Impact on unchanged code** - "You changed X but forgot to update Y that depends on it"
+3. **Missing related changes** - "This pattern also exists in Z, did you mean to update it too?"
+4. **Breaking changes** - "This change breaks callers in other files"
+
+### What is NOT in scope (do NOT report):
+1. **Pre-existing issues** - Old bugs/issues in code this PR didn't touch
+2. **Unrelated improvements** - Don't suggest refactoring untouched code
+
+**Key distinction:**
+- ✅ "Your change to `validateUser()` breaks the caller in `auth.ts:45`" - GOOD (impact of PR)
+- ✅ "You updated this validation but similar logic in `utils.ts` wasn't updated" - GOOD (incomplete)
+- ❌ "The existing code in `legacy.ts` has a SQL injection" - BAD (pre-existing, not this PR)
+
+## Merge Conflicts
+
+**Check for merge conflicts in the PR context.** If `has_merge_conflicts` is `true`:
+
+1. **Report this prominently** - Merge conflicts block the PR from being merged
+2. **Add a CRITICAL finding** with category "merge_conflict" and severity "critical"
+3. **Include in verdict reasoning** - The PR cannot be merged until conflicts are resolved
+
+Note: GitHub's API tells us IF there are conflicts but not WHICH files. The finding should state:
+> "This PR has merge conflicts with the base branch that must be resolved before merging."
+
 ## Available Specialist Agents

 You have access to these specialized review agents via the Task tool:
@@ -6,6 +6,23 @@ 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.

+## CRITICAL: PR Scope and Context
+
+### What IS in scope (report these issues):
+1. **Quality issues in changed code** - Problems in files/lines modified by this PR
+2. **Quality impact of changes** - "This change increases complexity of `handler.ts`"
+3. **Incomplete refactoring** - "You cleaned up X but similar pattern in Y wasn't updated"
+4. **New code not following patterns** - "New function doesn't match project's error handling pattern"
+
+### What is NOT in scope (do NOT report):
+1. **Pre-existing quality issues** - Old code smells in untouched code
+2. **Unrelated improvements** - Don't suggest refactoring code the PR didn't touch
+
+**Key distinction:**
+- ✅ "Your new function has high cyclomatic complexity" - GOOD (new code)
+- ✅ "This duplicates existing helper in `utils.ts`, consider reusing it" - GOOD (guidance)
+- ❌ "The old `legacy.ts` file has 1000 lines" - BAD (pre-existing, not this PR)
+
 ## Quality Focus Areas

 ### 1. Code Complexity
@@ -4,24 +4,49 @@

 You are a senior software engineer and security specialist performing a comprehensive code review. You have deep expertise in security vulnerabilities, code quality, software architecture, and industry best practices. Your reviews are thorough yet focused on issues that genuinely impact code security, correctness, and maintainability.

-## Review Methodology: Chain-of-Thought Analysis
+## Review Methodology: Evidence-Based Analysis

 For each potential issue you consider:

 1. **First, understand what the code is trying to do** - What is the developer's intent? What problem are they solving?
 2. **Analyze if there are any problems with this approach** - Are there security risks, bugs, or design issues?
 3. **Assess the severity and real-world impact** - Can this be exploited? Will this cause production issues? How likely is it to occur?
-4. **Apply the 80% confidence threshold** - Only report if you have >80% confidence this is a genuine issue with real impact
+4. **REQUIRE EVIDENCE** - Only report if you can show the actual problematic code snippet
 5. **Provide a specific, actionable fix** - Give the developer exactly what they need to resolve the issue

-## Confidence Requirements
+## Evidence Requirements

-**CRITICAL: Quality over quantity**
+**CRITICAL: No evidence = No finding**

- Only report findings where you have **>80% confidence** this is a real issue
- If uncertain or it "could be a problem in theory," **DO NOT include it**
- **5 high-quality findings are far better than 15 low-quality ones**
- Each finding should pass the test: "Would I stake my reputation on this being a genuine issue?"
+- **Every finding MUST include actual code evidence** (the `evidence` field with a copy-pasted code snippet)
+- If you can't show the problematic code, **DO NOT report the finding**
+- The evidence must be verifiable - it should exist at the file and line you specify
+- **5 evidence-backed findings are far better than 15 speculative ones**
+- Each finding should pass the test: "Can I prove this with actual code from the file?"
+
+## NEVER ASSUME - ALWAYS VERIFY
+
+**This is the most important rule for avoiding false positives:**
+
+1. **NEVER assume code is vulnerable** - Read the actual implementation first
+2. **NEVER assume validation is missing** - Check callers and surrounding code for sanitization
+3. **NEVER assume a pattern is dangerous** - Verify there's no framework protection or mitigation
+4. **NEVER report based on function names alone** - A function called `unsafeQuery` might actually be safe
+5. **NEVER extrapolate from one line** - Read ±20 lines of context minimum
+
+**Before reporting ANY finding, you MUST:**
+- Actually read the code at the file/line you're about to cite
+- Verify the problematic pattern exists exactly as you describe
+- Check if there's validation/sanitization before or after
+- Confirm the code path is actually reachable
+- Verify the line number exists (file might be shorter than you think)
+
+**Common false positive causes to avoid:**
+- Reporting line 500 when the file only has 400 lines (hallucination)
+- Claiming "no validation" when validation exists in the caller
+- Flagging parameterized queries as SQL injection (framework protection)
+- Reporting XSS when output is auto-escaped by the framework
+- Citing code that was already fixed in an earlier commit

 ## Anti-Patterns to Avoid

@@ -214,14 +239,13 @@ Return a JSON array with this structure:
    "id": "finding-1",
    "severity": "critical",
    "category": "security",
-    "confidence": 0.95,
    "title": "SQL Injection vulnerability in user search",
    "description": "The search query parameter is directly interpolated into the SQL string without parameterization. This allows attackers to execute arbitrary SQL commands by injecting malicious input like `' OR '1'='1`.",
    "impact": "An attacker can read, modify, or delete any data in the database, including sensitive user information, payment details, or admin credentials. This could lead to complete data breach.",
    "file": "src/api/users.ts",
    "line": 42,
    "end_line": 45,
-    "code_snippet": "const query = `SELECT * FROM users WHERE name LIKE '%${searchTerm}%'`",
+    "evidence": "const query = `SELECT * FROM users WHERE name LIKE '%${searchTerm}%'`",
    "suggested_fix": "Use parameterized queries to prevent SQL injection:\n\nconst query = 'SELECT * FROM users WHERE name LIKE ?';\nconst results = await db.query(query, [`%${searchTerm}%`]);",
    "fixable": true,
    "references": ["https://owasp.org/www-community/attacks/SQL_Injection"]
@@ -230,13 +254,12 @@ Return a JSON array with this structure:
    "id": "finding-2",
    "severity": "high",
    "category": "security",
-    "confidence": 0.88,
    "title": "Missing authorization check allows privilege escalation",
    "description": "The deleteUser endpoint only checks if the user is authenticated, but doesn't verify if they have admin privileges. Any logged-in user can delete other user accounts.",
    "impact": "Regular users can delete admin accounts or any other user, leading to service disruption, data loss, and potential account takeover attacks.",
    "file": "src/api/admin.ts",
    "line": 78,
-    "code_snippet": "router.delete('/users/:id', authenticate, async (req, res) => {\n  await User.delete(req.params.id);\n});",
+    "evidence": "router.delete('/users/:id', authenticate, async (req, res) => {\n  await User.delete(req.params.id);\n});",
    "suggested_fix": "Add authorization check:\n\nrouter.delete('/users/:id', authenticate, requireAdmin, async (req, res) => {\n  await User.delete(req.params.id);\n});\n\n// Or inline:\nif (!req.user.isAdmin) {\n  return res.status(403).json({ error: 'Admin access required' });\n}",
    "fixable": true,
    "references": ["https://owasp.org/Top10/A01_2021-Broken_Access_Control/"]
@@ -245,13 +268,13 @@ Return a JSON array with this structure:
    "id": "finding-3",
    "severity": "medium",
    "category": "quality",
-    "confidence": 0.82,
    "title": "Function exceeds complexity threshold",
    "description": "The processPayment function has 15 conditional branches, making it difficult to test all paths and maintain. High cyclomatic complexity increases bug risk.",
    "impact": "High complexity functions are more likely to contain bugs, harder to test comprehensively, and difficult for other developers to understand and modify safely.",
    "file": "src/payments/processor.ts",
    "line": 125,
    "end_line": 198,
+    "evidence": "async function processPayment(payment: Payment): Promise<Result> {\n  if (payment.type === 'credit') { ... } else if (payment.type === 'debit') { ... }\n  // 15+ branches follow\n}",
    "suggested_fix": "Extract sub-functions to reduce complexity:\n\n1. validatePaymentData(payment) - handle all validation\n2. calculateFees(amount, type) - fee calculation logic\n3. processRefund(payment) - refund-specific logic\n4. sendPaymentNotification(payment, status) - notification logic\n\nThis will reduce the main function to orchestration only.",
    "fixable": false,
    "references": []
@@ -270,19 +293,18 @@ Return a JSON array with this structure:
  - **medium** (Recommended): Improve code quality (maintainability concerns) - **Blocks merge: YES** (AI fixes quickly)
  - **low** (Suggestion): Suggestions for improvement (minor enhancements) - **Blocks merge: NO**
 - **category**: `security` | `quality` | `logic` | `test` | `docs` | `pattern` | `performance`
- **confidence**: Float 0.0-1.0 representing your confidence this is a genuine issue (must be ≥0.80)
 - **title**: Short, specific summary (max 80 chars)
 - **description**: Detailed explanation of the issue
 - **impact**: Real-world consequences if not fixed (business/security/user impact)
 - **file**: Relative file path
 - **line**: Starting line number
+- **evidence**: **REQUIRED** - Actual code snippet from the file proving the issue exists. Must be copy-pasted from the actual code.
 - **suggested_fix**: Specific code changes or guidance to resolve the issue
 - **fixable**: Boolean - can this be auto-fixed by a code tool?

 ### Optional Fields

 - **end_line**: Ending line number for multi-line issues
- **code_snippet**: The problematic code excerpt
 - **references**: Array of relevant URLs (OWASP, CVE, documentation)

 ## Guidelines for High-Quality Reviews
@@ -292,7 +314,7 @@ Return a JSON array with this structure:
 3. **Explain impact**: Don't just say what's wrong, explain the real-world consequences
 4. **Prioritize ruthlessly**: Focus on issues that genuinely matter
 5. **Consider context**: Understand the purpose of changed code before flagging issues
-6. **Validate confidence**: If you're not >80% sure, don't report it
+6. **Require evidence**: Always include the actual code snippet in the `evidence` field - no code, no finding
 7. **Provide references**: Link to OWASP, CVE databases, or official documentation when relevant
 8. **Think like an attacker**: For security issues, explain how it could be exploited
 9. **Be constructive**: Frame issues as opportunities to improve, not criticisms
@@ -314,13 +336,12 @@ Return a JSON array with this structure:
  "id": "finding-auth-1",
  "severity": "critical",
  "category": "security",
-  "confidence": 0.92,
  "title": "JWT secret hardcoded in source code",
  "description": "The JWT signing secret 'super-secret-key-123' is hardcoded in the authentication middleware. Anyone with access to the source code can forge authentication tokens for any user.",
  "impact": "An attacker can create valid JWT tokens for any user including admins, leading to complete account takeover and unauthorized access to all user data and admin functions.",
  "file": "src/middleware/auth.ts",
  "line": 12,
-  "code_snippet": "const SECRET = 'super-secret-key-123';\njwt.sign(payload, SECRET);",
+  "evidence": "const SECRET = 'super-secret-key-123';\njwt.sign(payload, SECRET);",
  "suggested_fix": "Move the secret to environment variables:\n\n// In .env file:\nJWT_SECRET=<generate-random-256-bit-secret>\n\n// In auth.ts:\nconst SECRET = process.env.JWT_SECRET;\nif (!SECRET) {\n  throw new Error('JWT_SECRET not configured');\n}\njwt.sign(payload, SECRET);",
  "fixable": true,
  "references": [
@@ -332,4 +353,4 @@ Return a JSON array with this structure:

 ---

-Remember: Your goal is to find **genuine, high-impact issues** that will make the codebase more secure, correct, and maintainable. Quality over quantity. Be thorough but focused.
+Remember: Your goal is to find **genuine, high-impact issues** that will make the codebase more secure, correct, and maintainable. **Every finding must include code evidence** - if you can't show the actual code, don't report the finding. Quality over quantity. Be thorough but focused.
@@ -6,6 +6,23 @@ 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.

+## CRITICAL: PR Scope and Context
+
+### What IS in scope (report these issues):
+1. **Security issues in changed code** - Vulnerabilities introduced or modified by this PR
+2. **Security impact of changes** - "This change exposes sensitive data to the new endpoint"
+3. **Missing security for new features** - "New API endpoint lacks authentication"
+4. **Broken security assumptions** - "Change to auth.ts invalidates security check in handler.ts"
+
+### What is NOT in scope (do NOT report):
+1. **Pre-existing vulnerabilities** - Old security issues in code this PR didn't touch
+2. **Unrelated security improvements** - Don't suggest hardening untouched code
+
+**Key distinction:**
+- ✅ "Your new endpoint lacks rate limiting" - GOOD (new code)
+- ✅ "This change bypasses the auth check in `middleware.ts`" - GOOD (impact analysis)
+- ❌ "The old `legacy_auth.ts` uses MD5 for passwords" - BAD (pre-existing, not this PR)
+
 ## Security Focus Areas

 ### 1. Injection Vulnerabilities
@@ -8,6 +8,7 @@ from typing import Any

 try:
    from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient
+    from phase_config import resolve_model_id

    CLAUDE_SDK_AVAILABLE = True
 except ImportError:
@@ -17,7 +18,7 @@ except ImportError:
 class ClaudeAnalysisClient:
    """Wrapper for Claude SDK client with analysis-specific configuration."""

-    DEFAULT_MODEL = "claude-sonnet-4-5-20250929"
+    DEFAULT_MODEL = "sonnet"  # Shorthand - resolved via API Profile if configured
    ALLOWED_TOOLS = ["Read", "Glob", "Grep"]
    MAX_TURNS = 50

@@ -110,7 +111,7 @@ class ClaudeAnalysisClient:

        return ClaudeSDKClient(
            options=ClaudeAgentOptions(
-                model=self.DEFAULT_MODEL,
+                model=resolve_model_id(self.DEFAULT_MODEL),  # Resolve via API Profile
                system_prompt=system_prompt,
                allowed_tools=self.ALLOWED_TOOLS,
                max_turns=self.MAX_TURNS,
@@ -1,16 +1,18 @@
 """
-Review Confidence Scoring
-=========================
+DEPRECATED: Review Confidence Scoring
+=====================================

-Adds confidence scores to review findings to help users prioritize.
+This module is DEPRECATED and will be removed in a future version.

-Features:
- Confidence scoring based on pattern matching, historical accuracy
- Risk assessment (false positive likelihood)
- Evidence tracking for transparency
- Calibration based on outcome tracking
+The confidence scoring approach has been replaced with EVIDENCE-BASED VALIDATION:
+- Instead of assigning confidence scores (0-100), findings now require concrete
+  code evidence proving the issue exists.
+- Simple rule: If you can't show the actual problematic code, don't report it.
+- Validation is binary: either the evidence exists in the file or it doesn't.

-Usage:
+For new code, use evidence-based validation in pydantic_models.py and models.py instead.
+
+Legacy Usage (deprecated):
    scorer = ConfidenceScorer(learning_tracker=tracker)

    # Score a finding
@@ -20,10 +22,24 @@ Usage:

    # Get explanation
    print(scorer.explain_confidence(scored))
+
+Migration:
+    - Instead of `confidence: float`, use `evidence: str` with actual code snippets
+    - Instead of filtering by confidence threshold, verify evidence exists in file
+    - See pr_finding_validator.md for the new evidence-based approach
 """

 from __future__ import annotations

+import warnings
+
+warnings.warn(
+    "The confidence module is deprecated. Use evidence-based validation instead. "
+    "See models.py 'evidence' field and pr_finding_validator.md for the new approach.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
 from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any
@@ -204,6 +204,11 @@ class PRContext:
    # Commit SHAs for worktree creation (PR review isolation)
    head_sha: str = ""  # Commit SHA of PR head (headRefOid)
    base_sha: str = ""  # Commit SHA of PR base (baseRefOid)
+    # Merge conflict status
+    has_merge_conflicts: bool = False  # True if PR has conflicts with base branch
+    merge_state_status: str = (
+        ""  # BEHIND, BLOCKED, CLEAN, DIRTY, HAS_HOOKS, UNKNOWN, UNSTABLE
+    )


 class PRContextGatherer:
@@ -276,6 +281,17 @@ class PRContextGatherer:
        # Check if diff was truncated (empty diff but files were changed)
        diff_truncated = len(diff) == 0 and len(changed_files) > 0

+        # Check merge conflict status
+        mergeable = pr_data.get("mergeable", "UNKNOWN")
+        merge_state_status = pr_data.get("mergeStateStatus", "UNKNOWN")
+        has_merge_conflicts = mergeable == "CONFLICTING"
+
+        if has_merge_conflicts:
+            print(
+                f"[Context] ⚠️  PR has merge conflicts (mergeStateStatus: {merge_state_status})",
+                flush=True,
+            )
+
        return PRContext(
            pr_number=self.pr_number,
            title=pr_data["title"],
@@ -296,6 +312,8 @@ class PRContextGatherer:
            diff_truncated=diff_truncated,
            head_sha=pr_data.get("headRefOid", ""),
            base_sha=pr_data.get("baseRefOid", ""),
+            has_merge_conflicts=has_merge_conflicts,
+            merge_state_status=merge_state_status,
        )

    async def _fetch_pr_metadata(self) -> dict:
@@ -317,6 +335,8 @@ class PRContextGatherer:
                "deletions",
                "changedFiles",
                "labels",
+                "mergeable",  # MERGEABLE, CONFLICTING, or UNKNOWN
+                "mergeStateStatus",  # BEHIND, BLOCKED, CLEAN, DIRTY, HAS_HOOKS, UNKNOWN, UNSTABLE
            ],
        )

@@ -1036,28 +1056,56 @@ class FollowupContextGatherer:
            f"[Followup] Comparing {previous_sha[:8]}...{current_sha[:8]}", flush=True
        )

-        # Get commit comparison
+        # Get PR-scoped files and commits (excludes merge-introduced changes)
+        # This solves the problem where merging develop into a feature branch
+        # would include commits from other PRs in the follow-up review.
+        # Pass reviewed_file_blobs for rebase-resistant comparison
+        reviewed_file_blobs = getattr(self.previous_review, "reviewed_file_blobs", {})
        try:
-            comparison = await self.gh_client.compare_commits(previous_sha, current_sha)
-        except Exception as e:
-            print(f"[Followup] Error comparing commits: {e}", flush=True)
-            return FollowupReviewContext(
-                pr_number=self.pr_number,
-                previous_review=self.previous_review,
-                previous_commit_sha=previous_sha,
-                current_commit_sha=current_sha,
-                error=f"Failed to compare commits: {e}",
+            pr_files, new_commits = await self.gh_client.get_pr_files_changed_since(
+                self.pr_number, previous_sha, reviewed_file_blobs=reviewed_file_blobs
            )
+            print(
+                f"[Followup] PR has {len(pr_files)} files, "
+                f"{len(new_commits)} commits since last review"
+                + (" (blob comparison used)" if reviewed_file_blobs else ""),
+                flush=True,
+            )
+        except Exception as e:
+            print(f"[Followup] Error getting PR files/commits: {e}", flush=True)
+            # Fallback to compare_commits if PR endpoints fail
+            print("[Followup] Falling back to commit comparison...", flush=True)
+            try:
+                comparison = await self.gh_client.compare_commits(
+                    previous_sha, current_sha
+                )
+                new_commits = comparison.get("commits", [])
+                pr_files = comparison.get("files", [])
+                print(
+                    f"[Followup] Fallback: Found {len(new_commits)} commits, "
+                    f"{len(pr_files)} files (may include merge-introduced changes)",
+                    flush=True,
+                )
+            except Exception as e2:
+                print(f"[Followup] Fallback also failed: {e2}", flush=True)
+                return FollowupReviewContext(
+                    pr_number=self.pr_number,
+                    previous_review=self.previous_review,
+                    previous_commit_sha=previous_sha,
+                    current_commit_sha=current_sha,
+                    error=f"Failed to get PR context: {e}, fallback: {e2}",
+                )

-        # Extract data from comparison
-        commits = comparison.get("commits", [])
-        files = comparison.get("files", [])
+        # Use PR files as the canonical list (excludes files from merged branches)
+        commits = new_commits
+        files = pr_files
        print(
            f"[Followup] Found {len(commits)} new commits, {len(files)} changed files",
            flush=True,
        )

        # Build diff from file patches
+        # Note: PR files endpoint returns 'filename' key, compare returns 'filename' too
        diff_parts = []
        files_changed = []
        for file_info in files:
@@ -1139,6 +1187,26 @@ class FollowupContextGatherer:
            flush=True,
        )

+        # Fetch current merge conflict status
+        has_merge_conflicts = False
+        merge_state_status = "UNKNOWN"
+        try:
+            pr_status = await self.gh_client.pr_get(
+                self.pr_number,
+                json_fields=["mergeable", "mergeStateStatus"],
+            )
+            mergeable = pr_status.get("mergeable", "UNKNOWN")
+            merge_state_status = pr_status.get("mergeStateStatus", "UNKNOWN")
+            has_merge_conflicts = mergeable == "CONFLICTING"
+
+            if has_merge_conflicts:
+                print(
+                    f"[Followup] ⚠️  PR has merge conflicts (mergeStateStatus: {merge_state_status})",
+                    flush=True,
+                )
+        except Exception as e:
+            print(f"[Followup] Could not fetch merge status: {e}", flush=True)
+
        return FollowupReviewContext(
            pr_number=self.pr_number,
            previous_review=self.previous_review,
@@ -1151,4 +1219,6 @@ class FollowupContextGatherer:
            + contributor_reviews,
            ai_bot_comments_since_review=ai_comments,
            pr_reviews_since_review=pr_reviews,
+            has_merge_conflicts=has_merge_conflicts,
+            merge_state_status=merge_state_status,
        )
@@ -822,14 +822,17 @@ class GHClient:

        Returns:
            Dict with:
-            - checks: List of check runs with name, status, conclusion
+            - checks: List of check runs with name, state
            - passing: Number of passing checks
            - failing: Number of failing checks
            - pending: Number of pending checks
            - failed_checks: List of failed check names
        """
        try:
-            args = ["pr", "checks", str(pr_number), "--json", "name,state,conclusion"]
+            # Note: gh pr checks --json only supports: bucket, completedAt, description,
+            # event, link, name, startedAt, state, workflow
+            # The 'state' field directly contains the result (SUCCESS, FAILURE, PENDING, etc.)
+            args = ["pr", "checks", str(pr_number), "--json", "name,state"]
            args = self._add_repo_flag(args)

            result = await self.run(args, timeout=30.0)
@@ -842,15 +845,14 @@ class GHClient:

            for check in checks:
                state = check.get("state", "").upper()
-                conclusion = check.get("conclusion", "").upper()
                name = check.get("name", "Unknown")

-                if state == "COMPLETED":
-                    if conclusion in ("SUCCESS", "NEUTRAL", "SKIPPED"):
-                        passing += 1
-                    elif conclusion in ("FAILURE", "TIMED_OUT", "CANCELLED"):
-                        failing += 1
-                        failed_checks.append(name)
+                # gh pr checks 'state' directly contains: SUCCESS, FAILURE, PENDING, NEUTRAL, etc.
+                if state in ("SUCCESS", "NEUTRAL", "SKIPPED"):
+                    passing += 1
+                elif state in ("FAILURE", "TIMED_OUT", "CANCELLED", "STARTUP_FAILURE"):
+                    failing += 1
+                    failed_checks.append(name)
                else:
                    # PENDING, QUEUED, IN_PROGRESS, etc.
                    pending += 1
@@ -872,3 +874,210 @@ class GHClient:
                "failed_checks": [],
                "error": str(e),
            }
+
+    async def get_pr_files(self, pr_number: int) -> list[dict[str, Any]]:
+        """
+        Get files changed by a PR using the PR files endpoint.
+
+        IMPORTANT: This returns only files that are part of the PR's actual changes,
+        NOT files that came in from merging another branch (e.g., develop).
+        This is crucial for follow-up reviews to avoid reviewing code from other PRs.
+
+        Uses: GET /repos/{owner}/{repo}/pulls/{pr_number}/files
+
+        Args:
+            pr_number: PR number
+
+        Returns:
+            List of file objects with:
+            - filename: Path to the file
+            - status: added, removed, modified, renamed, copied, changed
+            - additions: Number of lines added
+            - deletions: Number of lines deleted
+            - changes: Total number of line changes
+            - patch: The unified diff patch for this file (may be absent for large files)
+        """
+        files = []
+        page = 1
+        per_page = 100
+
+        while True:
+            endpoint = f"repos/{{owner}}/{{repo}}/pulls/{pr_number}/files?page={page}&per_page={per_page}"
+            args = ["api", "--method", "GET", endpoint]
+
+            result = await self.run(args, timeout=60.0)
+            page_files = json.loads(result.stdout) if result.stdout.strip() else []
+
+            if not page_files:
+                break
+
+            files.extend(page_files)
+
+            # Check if we got a full page (more pages might exist)
+            if len(page_files) < per_page:
+                break
+
+            page += 1
+
+            # Safety limit to prevent infinite loops
+            if page > 50:
+                logger.warning(
+                    f"PR #{pr_number} has more than 5000 files, stopping pagination"
+                )
+                break
+
+        return files
+
+    async def get_pr_commits(self, pr_number: int) -> list[dict[str, Any]]:
+        """
+        Get commits that are part of a PR using the PR commits endpoint.
+
+        IMPORTANT: This returns only commits that are part of the PR's branch,
+        NOT commits that came in from merging another branch (e.g., develop).
+        This is crucial for follow-up reviews to avoid reviewing commits from other PRs.
+
+        Uses: GET /repos/{owner}/{repo}/pulls/{pr_number}/commits
+
+        Args:
+            pr_number: PR number
+
+        Returns:
+            List of commit objects with:
+            - sha: Commit SHA
+            - commit: Object with message, author, committer info
+            - author: GitHub user who authored the commit
+            - committer: GitHub user who committed
+            - parents: List of parent commit SHAs
+        """
+        commits = []
+        page = 1
+        per_page = 100
+
+        while True:
+            endpoint = f"repos/{{owner}}/{{repo}}/pulls/{pr_number}/commits?page={page}&per_page={per_page}"
+            args = ["api", "--method", "GET", endpoint]
+
+            result = await self.run(args, timeout=60.0)
+            page_commits = json.loads(result.stdout) if result.stdout.strip() else []
+
+            if not page_commits:
+                break
+
+            commits.extend(page_commits)
+
+            # Check if we got a full page (more pages might exist)
+            if len(page_commits) < per_page:
+                break
+
+            page += 1
+
+            # Safety limit
+            if page > 10:
+                logger.warning(
+                    f"PR #{pr_number} has more than 1000 commits, stopping pagination"
+                )
+                break
+
+        return commits
+
+    async def get_pr_files_changed_since(
+        self,
+        pr_number: int,
+        base_sha: str,
+        reviewed_file_blobs: dict[str, str] | None = None,
+    ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+        """
+        Get files and commits that are part of the PR and changed since a specific commit.
+
+        This method solves the "merge introduced commits" problem by:
+        1. Getting the canonical list of PR files (excludes files from merged branches)
+        2. Getting the canonical list of PR commits (excludes commits from merged branches)
+        3. Filtering to only include commits after base_sha
+
+        When a rebase/force-push is detected (base_sha not found in commits), and
+        reviewed_file_blobs is provided, uses blob SHA comparison to identify which
+        files actually changed content. This prevents re-reviewing unchanged files.
+
+        Args:
+            pr_number: PR number
+            base_sha: The commit SHA to compare from (e.g., last reviewed commit)
+            reviewed_file_blobs: Optional dict mapping filename -> blob SHA from the
+                previous review. Used as fallback when base_sha is not found (rebase).
+
+        Returns:
+            Tuple of:
+            - List of file objects that are part of the PR (filtered if blob comparison used)
+            - List of commit objects that are part of the PR and after base_sha
+        """
+        # Get PR's canonical files (these are the actual PR changes)
+        pr_files = await self.get_pr_files(pr_number)
+
+        # Get PR's canonical commits
+        pr_commits = await self.get_pr_commits(pr_number)
+
+        # Find the position of base_sha in PR commits
+        # Use minimum 7-char prefix comparison (git's default short SHA length)
+        base_index = -1
+        min_prefix_len = 7
+        base_prefix = (
+            base_sha[:min_prefix_len] if len(base_sha) >= min_prefix_len else base_sha
+        )
+        for i, commit in enumerate(pr_commits):
+            commit_prefix = commit["sha"][:min_prefix_len]
+            if commit_prefix == base_prefix:
+                base_index = i
+                break
+
+        # Commits after base_sha (these are the new commits to review)
+        if base_index >= 0:
+            new_commits = pr_commits[base_index + 1 :]
+            return pr_files, new_commits
+
+        # base_sha not found in PR commits - this happens when:
+        # 1. The base_sha was from a merge commit (not a direct PR commit)
+        # 2. The PR was rebased/force-pushed
+        logger.warning(
+            f"base_sha {base_sha[:8]} not found in PR #{pr_number} commits. "
+            "PR was likely rebased or force-pushed."
+        )
+
+        # If we have blob SHAs from the previous review, use them to filter files
+        # Blob SHAs persist across rebases - same content = same blob SHA
+        if reviewed_file_blobs:  # Only use blob comparison if we have actual blob data
+            changed_files = []
+            unchanged_count = 0
+            for file in pr_files:
+                filename = file.get("filename", "")
+                current_blob_sha = file.get("sha", "")
+                file_status = file.get("status", "")
+                previous_blob_sha = reviewed_file_blobs.get(filename, "")
+
+                # Always include files that were added, removed, or renamed
+                # These are significant changes regardless of blob SHA
+                if file_status in ("added", "removed", "renamed"):
+                    changed_files.append(file)
+                elif not previous_blob_sha:
+                    # File wasn't in previous review - include it
+                    changed_files.append(file)
+                elif current_blob_sha != previous_blob_sha:
+                    # File content changed - include it
+                    changed_files.append(file)
+                else:
+                    # Same blob SHA = same content - skip it
+                    unchanged_count += 1
+
+            if unchanged_count > 0:
+                logger.info(
+                    f"Blob comparison: {len(changed_files)} files changed, "
+                    f"{unchanged_count} unchanged (skipped)"
+                )
+
+            # Return filtered files but all commits (can't filter commits after rebase)
+            return changed_files, pr_commits
+
+        # No blob data available - return all files and commits
+        logger.warning(
+            "No reviewed_file_blobs available for blob comparison. "
+            "Returning all PR files."
+        )
+        return pr_files, pr_commits
@@ -214,19 +214,18 @@ class PRReviewFinding:
    end_line: int | None = None
    suggested_fix: str | None = None
    fixable: bool = False
-    # NEW: Support for verification and redundancy detection
-    confidence: float = 0.85  # AI's confidence in this finding (0.0-1.0)
+    # Evidence-based validation: actual code proving the issue exists
+    evidence: str | None = None  # Actual code snippet showing the issue
    verification_note: str | None = (
        None  # What evidence is missing or couldn't be verified
    )
    redundant_with: str | None = None  # Reference to duplicate code (file:line)

-    # NEW: Finding validation fields (from finding-validator re-investigation)
+    # Finding validation fields (from finding-validator re-investigation)
    validation_status: str | None = (
        None  # confirmed_valid, dismissed_false_positive, needs_human_review
    )
    validation_evidence: str | None = None  # Code snippet examined during validation
-    validation_confidence: float | None = None  # Confidence of validation (0.0-1.0)
    validation_explanation: str | None = None  # Why finding was validated/dismissed

    def to_dict(self) -> dict:
@@ -241,14 +240,13 @@ class PRReviewFinding:
            "end_line": self.end_line,
            "suggested_fix": self.suggested_fix,
            "fixable": self.fixable,
-            # NEW fields
-            "confidence": self.confidence,
+            # Evidence-based validation fields
+            "evidence": self.evidence,
            "verification_note": self.verification_note,
            "redundant_with": self.redundant_with,
            # Validation fields
            "validation_status": self.validation_status,
            "validation_evidence": self.validation_evidence,
-            "validation_confidence": self.validation_confidence,
            "validation_explanation": self.validation_explanation,
        }

@@ -265,14 +263,13 @@ class PRReviewFinding:
            end_line=data.get("end_line"),
            suggested_fix=data.get("suggested_fix"),
            fixable=data.get("fixable", False),
-            # NEW fields
-            confidence=data.get("confidence", 0.85),
+            # Evidence-based validation fields
+            evidence=data.get("evidence"),
            verification_note=data.get("verification_note"),
            redundant_with=data.get("redundant_with"),
            # Validation fields
            validation_status=data.get("validation_status"),
            validation_evidence=data.get("validation_evidence"),
-            validation_confidence=data.get("validation_confidence"),
            validation_explanation=data.get("validation_explanation"),
        )

@@ -383,6 +380,9 @@ class PRReviewResult:

    # Follow-up review tracking
    reviewed_commit_sha: str | None = None  # HEAD SHA at time of review
+    reviewed_file_blobs: dict[str, str] = field(
+        default_factory=dict
+    )  # filename → blob SHA at time of review (survives rebases)
    is_followup_review: bool = False  # True if this is a follow-up review
    previous_review_id: int | None = None  # Reference to the review this follows up on
    resolved_findings: list[str] = field(default_factory=list)  # Finding IDs now fixed
@@ -421,6 +421,7 @@ class PRReviewResult:
            "quick_scan_summary": self.quick_scan_summary,
            # Follow-up review fields
            "reviewed_commit_sha": self.reviewed_commit_sha,
+            "reviewed_file_blobs": self.reviewed_file_blobs,
            "is_followup_review": self.is_followup_review,
            "previous_review_id": self.previous_review_id,
            "resolved_findings": self.resolved_findings,
@@ -465,6 +466,7 @@ class PRReviewResult:
            quick_scan_summary=data.get("quick_scan_summary", {}),
            # Follow-up review fields
            reviewed_commit_sha=data.get("reviewed_commit_sha"),
+            reviewed_file_blobs=data.get("reviewed_file_blobs", {}),
            is_followup_review=data.get("is_followup_review", False),
            previous_review_id=data.get("previous_review_id"),
            resolved_findings=data.get("resolved_findings", []),
@@ -562,6 +564,12 @@ class FollowupReviewContext:
    # These are different from comments - they're full review submissions with body text
    pr_reviews_since_review: list[dict] = field(default_factory=list)

+    # Merge conflict status
+    has_merge_conflicts: bool = False  # True if PR has conflicts with base branch
+    merge_state_status: str = (
+        ""  # BEHIND, BLOCKED, CLEAN, DIRTY, HAS_HOOKS, UNKNOWN, UNSTABLE
+    )
+
    # Error flag - if set, context gathering failed and data may be incomplete
    error: str | None = None

@@ -435,6 +435,25 @@ class GitHubOrchestrator:
            # Get HEAD SHA for follow-up review tracking
            head_sha = self.bot_detector.get_last_commit_sha(pr_context.commits)

+            # Get file blob SHAs for rebase-resistant follow-up reviews
+            # Blob SHAs persist across rebases - same content = same blob SHA
+            file_blobs: dict[str, str] = {}
+            try:
+                pr_files = await self.gh_client.get_pr_files(pr_number)
+                for file in pr_files:
+                    filename = file.get("filename", "")
+                    blob_sha = file.get("sha", "")
+                    if filename and blob_sha:
+                        file_blobs[filename] = blob_sha
+                print(
+                    f"[Review] Captured {len(file_blobs)} file blob SHAs for follow-up tracking",
+                    flush=True,
+                )
+            except Exception as e:
+                print(
+                    f"[Review] Warning: Could not capture file blobs: {e}", flush=True
+                )
+
            # Create result
            result = PRReviewResult(
                pr_number=pr_number,
@@ -452,6 +471,8 @@ class GitHubOrchestrator:
                quick_scan_summary=quick_scan,
                # Track the commit SHA for follow-up reviews
                reviewed_commit_sha=head_sha,
+                # Track file blobs for rebase-resistant follow-up reviews
+                reviewed_file_blobs=file_blobs,
            )

            # Post review if configured
@@ -26,6 +26,7 @@ if TYPE_CHECKING:
    from ..models import FollowupReviewContext, GitHubRunnerConfig

 try:
+    from ..gh_client import GHClient
    from ..models import (
        MergeVerdict,
        PRReviewFinding,
@@ -37,6 +38,7 @@ try:
    from .prompt_manager import PromptManager
    from .pydantic_models import FollowupReviewResponse
 except (ImportError, ValueError, SystemError):
+    from gh_client import GHClient
    from models import (
        MergeVerdict,
        PRReviewFinding,
@@ -230,6 +232,27 @@ class FollowupReviewer:
            "complete", 100, "Follow-up review complete!", context.pr_number
        )

+        # Get file blob SHAs for rebase-resistant follow-up reviews
+        # Blob SHAs persist across rebases - same content = same blob SHA
+        file_blobs: dict[str, str] = {}
+        try:
+            gh_client = GHClient(
+                project_dir=self.project_dir,
+                default_timeout=30.0,
+                repo=self.config.repo,
+            )
+            pr_files = await gh_client.get_pr_files(context.pr_number)
+            for file in pr_files:
+                filename = file.get("filename", "")
+                blob_sha = file.get("sha", "")
+                if filename and blob_sha:
+                    file_blobs[filename] = blob_sha
+            logger.info(
+                f"Captured {len(file_blobs)} file blob SHAs for follow-up tracking"
+            )
+        except Exception as e:
+            logger.warning(f"Could not capture file blobs: {e}")
+
        return PRReviewResult(
            pr_number=context.pr_number,
            repo=self.config.repo,
@@ -243,6 +266,7 @@ class FollowupReviewer:
            reviewed_at=datetime.now().isoformat(),
            # Follow-up specific fields
            reviewed_commit_sha=context.current_commit_sha,
+            reviewed_file_blobs=file_blobs,
            is_followup_review=True,
            previous_review_id=context.previous_review.review_id,
            resolved_findings=[f.id for f in resolved],
@@ -32,6 +32,7 @@ from claude_agent_sdk import AgentDefinition
 try:
    from ...core.client import create_client
    from ...phase_config import get_thinking_budget
+    from ..gh_client import GHClient
    from ..models import (
        GitHubRunnerConfig,
        MergeVerdict,
@@ -44,6 +45,7 @@ try:
    from .sdk_utils import process_sdk_stream
 except (ImportError, ValueError, SystemError):
    from core.client import create_client
+    from gh_client import GHClient
    from models import (
        GitHubRunnerConfig,
        MergeVerdict,
@@ -498,6 +500,27 @@ The SDK will run invoked agents in parallel automatically.
                ):
                    blockers.append(f"{finding.category.value}: {finding.title}")

+            # Get file blob SHAs for rebase-resistant follow-up reviews
+            # Blob SHAs persist across rebases - same content = same blob SHA
+            file_blobs: dict[str, str] = {}
+            try:
+                gh_client = GHClient(
+                    project_dir=self.project_dir,
+                    default_timeout=30.0,
+                    repo=self.config.repo,
+                )
+                pr_files = await gh_client.get_pr_files(context.pr_number)
+                for file in pr_files:
+                    filename = file.get("filename", "")
+                    blob_sha = file.get("sha", "")
+                    if filename and blob_sha:
+                        file_blobs[filename] = blob_sha
+                logger.info(
+                    f"Captured {len(file_blobs)} file blob SHAs for follow-up tracking"
+                )
+            except Exception as e:
+                logger.warning(f"Could not capture file blobs: {e}")
+
            result = PRReviewResult(
                pr_number=context.pr_number,
                repo=self.config.repo,
@@ -509,6 +532,7 @@ The SDK will run invoked agents in parallel automatically.
                verdict_reasoning=verdict_reasoning,
                blockers=blockers,
                reviewed_commit_sha=context.current_commit_sha,
+                reviewed_file_blobs=file_blobs,
                is_followup_review=True,
                previous_review_id=context.previous_review.review_id
                or context.previous_review.pr_number,
@@ -614,13 +638,11 @@ The SDK will run invoked agents in parallel automatically.
                            validation = validation_map.get(rv.finding_id)
                            validation_status = None
                            validation_evidence = None
-                            validation_confidence = None
                            validation_explanation = None

                            if validation:
                                validation_status = validation.validation_status
                                validation_evidence = validation.code_evidence
-                                validation_confidence = validation.confidence
                                validation_explanation = validation.explanation

                            findings.append(
@@ -636,7 +658,6 @@ The SDK will run invoked agents in parallel automatically.
                                    fixable=original.fixable,
                                    validation_status=validation_status,
                                    validation_evidence=validation_evidence,
-                                    validation_confidence=validation_confidence,
                                    validation_explanation=validation_explanation,
                                )
                            )
@@ -27,11 +27,13 @@ from pathlib import Path
 from typing import Any

 from claude_agent_sdk import AgentDefinition
+from core.git_bash import get_git_executable_path

 try:
    from ...core.client import create_client
    from ...phase_config import get_thinking_budget
    from ..context_gatherer import PRContext, _validate_git_ref
+    from ..gh_client import GHClient
    from ..models import (
        GitHubRunnerConfig,
        MergeVerdict,
@@ -45,6 +47,7 @@ try:
 except (ImportError, ValueError, SystemError):
    from context_gatherer import PRContext, _validate_git_ref
    from core.client import create_client
+    from gh_client import GHClient
    from models import (
        GitHubRunnerConfig,
        MergeVerdict,
@@ -162,8 +165,9 @@ class ParallelOrchestratorReviewer:
            )

        # Fetch the commit if not available locally (handles fork PRs)
+        git_path = get_git_executable_path()
        fetch_result = subprocess.run(
-            ["git", "fetch", "origin", head_sha],
+            [git_path, "fetch", "origin", head_sha],
            cwd=self.project_dir,
            capture_output=True,
            text=True,
@@ -182,7 +186,7 @@ class ParallelOrchestratorReviewer:

        # Create detached worktree at the PR commit
        result = subprocess.run(
-            ["git", "worktree", "add", "--detach", str(worktree_path), head_sha],
+            [git_path, "worktree", "add", "--detach", str(worktree_path), head_sha],
            cwd=self.project_dir,
            capture_output=True,
            text=True,
@@ -243,8 +247,9 @@ class ParallelOrchestratorReviewer:
            )

        # Try 1: git worktree remove
+        git_path = get_git_executable_path()
        result = subprocess.run(
-            ["git", "worktree", "remove", "--force", str(worktree_path)],
+            [git_path, "worktree", "remove", "--force", str(worktree_path)],
            cwd=self.project_dir,
            capture_output=True,
            text=True,
@@ -265,7 +270,7 @@ class ParallelOrchestratorReviewer:
        try:
            shutil.rmtree(worktree_path, ignore_errors=True)
            subprocess.run(
-                ["git", "worktree", "prune"],
+                [git_path, "worktree", "prune"],
                cwd=self.project_dir,
                capture_output=True,
                timeout=30,
@@ -281,8 +286,9 @@ class ParallelOrchestratorReviewer:
            return

        # Get registered worktrees from git
+        git_path = get_git_executable_path()
        result = subprocess.run(
-            ["git", "worktree", "list", "--porcelain"],
+            [git_path, "worktree", "list", "--porcelain"],
            cwd=self.project_dir,
            capture_output=True,
            text=True,
@@ -306,7 +312,7 @@ class ParallelOrchestratorReviewer:

        if stale_count > 0:
            subprocess.run(
-                ["git", "worktree", "prune"],
+                [git_path, "worktree", "prune"],
                cwd=self.project_dir,
                capture_output=True,
                timeout=30,
@@ -584,7 +590,7 @@ The SDK will run invoked agents in parallel automatically.
            category=category,
            severity=severity,
            suggested_fix=finding_data.suggested_fix or "",
-            confidence=self._normalize_confidence(finding_data.confidence),
+            evidence=finding_data.evidence,
        )

    async def review(self, context: PRContext) -> PRReviewResult:
@@ -799,6 +805,27 @@ The SDK will run invoked agents in parallel automatically.
                latest_commit = context.commits[-1]
                head_sha = latest_commit.get("oid") or latest_commit.get("sha")

+            # Get file blob SHAs for rebase-resistant follow-up reviews
+            # Blob SHAs persist across rebases - same content = same blob SHA
+            file_blobs: dict[str, str] = {}
+            try:
+                gh_client = GHClient(
+                    project_dir=self.project_dir,
+                    default_timeout=30.0,
+                    repo=self.config.repo,
+                )
+                pr_files = await gh_client.get_pr_files(context.pr_number)
+                for file in pr_files:
+                    filename = file.get("filename", "")
+                    blob_sha = file.get("sha", "")
+                    if filename and blob_sha:
+                        file_blobs[filename] = blob_sha
+                logger.info(
+                    f"Captured {len(file_blobs)} file blob SHAs for follow-up tracking"
+                )
+            except Exception as e:
+                logger.warning(f"Could not capture file blobs: {e}")
+
            result = PRReviewResult(
                pr_number=context.pr_number,
                repo=self.config.repo,
@@ -810,6 +837,7 @@ The SDK will run invoked agents in parallel automatically.
                verdict_reasoning=verdict_reasoning,
                blockers=blockers,
                reviewed_commit_sha=head_sha,
+                reviewed_file_blobs=file_blobs,
            )

            self._report_progress(
@@ -945,7 +973,7 @@ The SDK will run invoked agents in parallel automatically.
            category=category,
            severity=severity,
            suggested_fix=f_data.get("suggested_fix", ""),
-            confidence=self._normalize_confidence(f_data.get("confidence", 85)),
+            evidence=f_data.get("evidence"),
        )

    def _parse_text_output(self, output: str) -> list[PRReviewFinding]:
@@ -26,7 +26,7 @@ from __future__ import annotations

 from typing import Literal

-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, Field

 # =============================================================================
 # Common Finding Types
@@ -46,6 +46,10 @@ class BaseFinding(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")
+    evidence: str | None = Field(
+        None,
+        description="Actual code snippet proving the issue exists. Required for validation.",
+    )


 class SecurityFinding(BaseFinding):
@@ -78,9 +82,6 @@ class DeepAnalysisFinding(BaseFinding):
        "performance",
        "logic",
    ] = Field(description="Issue category")
-    confidence: float = Field(
-        0.85, ge=0.0, le=1.0, description="AI's confidence in this finding (0.0-1.0)"
-    )
    verification_note: str | None = Field(
        None, description="What evidence is missing or couldn't be verified"
    )
@@ -315,21 +316,11 @@ class OrchestratorFinding(BaseModel):
        description="Issue severity level"
    )
    suggestion: str | None = Field(None, description="How to fix this issue")
-    confidence: float = Field(
-        0.85,
-        ge=0.0,
-        le=1.0,
-        description="Confidence (0.0-1.0 or 0-100, normalized to 0.0-1.0)",
+    evidence: str | None = Field(
+        None,
+        description="Actual code snippet proving the issue exists. Required for validation.",
    )

-    @field_validator("confidence", mode="before")
-    @classmethod
-    def normalize_confidence(cls, v: int | float) -> float:
-        """Normalize confidence to 0.0-1.0 range (accepts 0-100 or 0.0-1.0)."""
-        if v > 1:
-            return v / 100.0
-        return float(v)
-

 class OrchestratorReviewResponse(BaseModel):
    """Complete response schema for orchestrator PR review."""
@@ -355,9 +346,6 @@ class LogicFinding(BaseFinding):
    category: Literal["logic"] = Field(
        default="logic", description="Always 'logic' for logic findings"
    )
-    confidence: float = Field(
-        0.85, ge=0.0, le=1.0, description="Confidence in this finding (0.0-1.0)"
-    )
    example_input: str | None = Field(
        None, description="Concrete input that triggers the bug"
    )
@@ -366,14 +354,6 @@ class LogicFinding(BaseFinding):
        None, description="What the code should produce"
    )

-    @field_validator("confidence", mode="before")
-    @classmethod
-    def normalize_confidence(cls, v: int | float) -> float:
-        """Normalize confidence to 0.0-1.0 range."""
-        if v > 1:
-            return v / 100.0
-        return float(v)
-

 class CodebaseFitFinding(BaseFinding):
    """A codebase fit finding from the codebase fit review agent."""
@@ -381,9 +361,6 @@ class CodebaseFitFinding(BaseFinding):
    category: Literal["codebase_fit"] = Field(
        default="codebase_fit", description="Always 'codebase_fit' for fit findings"
    )
-    confidence: float = Field(
-        0.85, ge=0.0, le=1.0, description="Confidence in this finding (0.0-1.0)"
-    )
    existing_code: str | None = Field(
        None, description="Reference to existing code that should be used instead"
    )
@@ -391,14 +368,6 @@ class CodebaseFitFinding(BaseFinding):
        None, description="Description of the established pattern being violated"
    )

-    @field_validator("confidence", mode="before")
-    @classmethod
-    def normalize_confidence(cls, v: int | float) -> float:
-        """Normalize confidence to 0.0-1.0 range."""
-        if v > 1:
-            return v / 100.0
-        return float(v)
-

 class ParallelOrchestratorFinding(BaseModel):
    """A finding from the parallel orchestrator with source agent tracking."""
@@ -423,8 +392,9 @@ class ParallelOrchestratorFinding(BaseModel):
    severity: Literal["critical", "high", "medium", "low"] = Field(
        description="Issue severity level"
    )
-    confidence: float = Field(
-        0.85, ge=0.0, le=1.0, description="Confidence in this finding (0.0-1.0)"
+    evidence: str | None = Field(
+        None,
+        description="Actual code snippet proving the issue exists. Required for validation.",
    )
    suggested_fix: str | None = Field(None, description="How to fix this issue")
    fixable: bool = Field(False, description="Whether this can be auto-fixed")
@@ -436,14 +406,6 @@ class ParallelOrchestratorFinding(BaseModel):
        False, description="Whether multiple agents agreed on this finding"
    )

-    @field_validator("confidence", mode="before")
-    @classmethod
-    def normalize_confidence(cls, v: int | float) -> float:
-        """Normalize confidence to 0.0-1.0 range."""
-        if v > 1:
-            return v / 100.0
-        return float(v)
-

 class AgentAgreement(BaseModel):
    """Tracks agreement between agents on findings."""
@@ -496,22 +458,14 @@ class ResolutionVerification(BaseModel):
    status: Literal["resolved", "partially_resolved", "unresolved", "cant_verify"] = (
        Field(description="Resolution status after AI verification")
    )
-    confidence: float = Field(
-        0.85, ge=0.0, le=1.0, description="Confidence in the resolution status"
+    evidence: str = Field(
+        min_length=1,
+        description="Actual code snippet showing the resolution status. Required.",
    )
-    evidence: str = Field(description="What evidence supports this resolution status")
    resolution_notes: str | None = Field(
        None, description="Detailed notes on how the issue was addressed"
    )

-    @field_validator("confidence", mode="before")
-    @classmethod
-    def normalize_confidence(cls, v: int | float) -> float:
-        """Normalize confidence to 0.0-1.0 range."""
-        if v > 1:
-            return v / 100.0
-        return float(v)
-

 class ParallelFollowupFinding(BaseModel):
    """A finding from parallel follow-up review with source agent tracking."""
@@ -534,8 +488,9 @@ class ParallelFollowupFinding(BaseModel):
    severity: Literal["critical", "high", "medium", "low"] = Field(
        description="Issue severity level"
    )
-    confidence: float = Field(
-        0.85, ge=0.0, le=1.0, description="Confidence in this finding (0.0-1.0)"
+    evidence: str | None = Field(
+        None,
+        description="Actual code snippet proving the issue exists. Required for validation.",
    )
    suggested_fix: str | None = Field(None, description="How to fix this issue")
    fixable: bool = Field(False, description="Whether this can be auto-fixed")
@@ -546,14 +501,6 @@ class ParallelFollowupFinding(BaseModel):
        None, description="ID of related previous finding if this is a regression"
    )

-    @field_validator("confidence", mode="before")
-    @classmethod
-    def normalize_confidence(cls, v: int | float) -> float:
-        """Normalize confidence to 0.0-1.0 range."""
-        if v > 1:
-            return v / 100.0
-        return float(v)
-

 class CommentAnalysis(BaseModel):
    """Analysis of a contributor or AI comment."""
@@ -640,6 +587,9 @@ class FindingValidationResult(BaseModel):

    The finding-validator agent uses this to report whether a previous finding
    is a genuine issue or a false positive that should be dismissed.
+
+    EVIDENCE-BASED VALIDATION: No confidence scores - validation is binary.
+    Either the evidence shows the issue exists, or it doesn't.
    """

    finding_id: str = Field(description="ID of the finding being validated")
@@ -648,16 +598,17 @@ class FindingValidationResult(BaseModel):
    ] = Field(
        description=(
            "Validation result: "
-            "confirmed_valid = issue IS real, keep as unresolved; "
-            "dismissed_false_positive = original finding was incorrect, remove; "
-            "needs_human_review = cannot determine with confidence"
+            "confirmed_valid = code evidence proves issue IS real; "
+            "dismissed_false_positive = code evidence proves issue does NOT exist; "
+            "needs_human_review = cannot find definitive evidence either way"
        )
    )
    code_evidence: str = Field(
        min_length=1,
        description=(
            "REQUIRED: Exact code snippet examined from the file. "
-            "Must be actual code, not a description."
+            "Must be actual code copy-pasted from the file, not a description. "
+            "This is the proof that determines the validation status."
        ),
    )
    line_range: tuple[int, int] = Field(
@@ -666,27 +617,18 @@ class FindingValidationResult(BaseModel):
    explanation: str = Field(
        min_length=20,
        description=(
-            "Detailed explanation of why the finding is valid/invalid. "
-            "Must reference specific code and explain the reasoning."
+            "Detailed explanation connecting the code_evidence to the validation_status. "
+            "Must explain: (1) what the original finding claimed, (2) what the actual code shows, "
+            "(3) why this proves/disproves the issue."
        ),
    )
-    confidence: float = Field(
-        ge=0.0,
-        le=1.0,
+    evidence_verified_in_file: bool = Field(
        description=(
-            "Confidence in the validation result (0.0-1.0). "
-            "Must be >= 0.80 to dismiss as false positive, >= 0.70 to confirm valid."
-        ),
+            "True if the code_evidence was verified to exist at the specified line_range. "
+            "False if the code couldn't be found (indicates hallucination in original finding)."
+        )
    )

-    @field_validator("confidence", mode="before")
-    @classmethod
-    def normalize_confidence(cls, v: int | float) -> float:
-        """Normalize confidence to 0.0-1.0 range (accepts 0-100 or 0.0-1.0)."""
-        if v > 1:
-            return v / 100.0
-        return float(v)
-

 class FindingValidationResponse(BaseModel):
    """Complete response from the finding-validator agent."""
@@ -33,8 +33,9 @@ except (ImportError, ValueError, SystemError):
        TriageResult,
    )

-# Confidence threshold for filtering findings (GitHub Copilot standard)
-CONFIDENCE_THRESHOLD = 0.80
+# Evidence-based validation replaces confidence scoring
+# Findings without evidence are filtered out instead of using confidence thresholds
+MIN_EVIDENCE_LENGTH = 20  # Minimum chars for evidence to be considered valid


 class ResponseParser:
@@ -65,9 +66,13 @@ class ResponseParser:

    @staticmethod
    def parse_review_findings(
-        response_text: str, apply_confidence_filter: bool = True
+        response_text: str, require_evidence: bool = True
    ) -> list[PRReviewFinding]:
-        """Parse findings from AI response with optional confidence filtering."""
+        """Parse findings from AI response with optional evidence validation.
+
+        Evidence-based validation: Instead of confidence scores, findings
+        require actual code evidence proving the issue exists.
+        """
        findings = []

        try:
@@ -77,14 +82,14 @@ class ResponseParser:
            if json_match:
                findings_data = json.loads(json_match.group(1))
                for i, f in enumerate(findings_data):
-                    # Get confidence (default to 0.85 if not provided for backward compat)
-                    confidence = float(f.get("confidence", 0.85))
+                    # Get evidence (code snippet proving the issue)
+                    evidence = f.get("evidence") or f.get("code_snippet") or ""

-                    # Apply confidence threshold filter
-                    if apply_confidence_filter and confidence < CONFIDENCE_THRESHOLD:
+                    # Apply evidence-based validation
+                    if require_evidence and len(evidence.strip()) < MIN_EVIDENCE_LENGTH:
                        print(
                            f"[AI] Dropped finding '{f.get('title', 'unknown')}': "
-                            f"confidence {confidence:.2f} < {CONFIDENCE_THRESHOLD}",
+                            f"insufficient evidence ({len(evidence.strip())} chars < {MIN_EVIDENCE_LENGTH})",
                            flush=True,
                        )
                        continue
@@ -105,8 +110,8 @@ class ResponseParser:
                            end_line=f.get("end_line"),
                            suggested_fix=f.get("suggested_fix"),
                            fixable=f.get("fixable", False),
-                            # NEW: Support verification and redundancy fields
-                            confidence=confidence,
+                            # Evidence-based validation fields
+                            evidence=evidence if evidence.strip() else None,
                            verification_note=f.get("verification_note"),
                            redundant_with=f.get("redundant_with"),
                        )
@@ -94,8 +94,8 @@ def main():
    parser.add_argument(
        "--model",
        type=str,
-        default="claude-opus-4-5-20251101",
-        help="Model to use (default: claude-opus-4-5-20251101)",
+        default="sonnet",  # Changed from "opus" (fix #433)
+        help="Model to use (haiku, sonnet, opus, or full model ID)",
    )
    parser.add_argument(
        "--thinking-level",
@@ -39,6 +39,7 @@ from debug import (
    debug_section,
    debug_success,
 )
+from phase_config import resolve_model_id


 def load_project_context(project_dir: str) -> str:
@@ -132,7 +133,7 @@ async def run_with_sdk(
    project_dir: str,
    message: str,
    history: list,
-    model: str = "claude-sonnet-4-5-20250929",
+    model: str = "sonnet",  # Shorthand - resolved via API Profile if configured
    thinking_level: str = "medium",
 ) -> None:
    """Run the chat using Claude SDK with streaming."""
@@ -180,7 +181,7 @@ Current question: {message}"""
        # Create Claude SDK client with appropriate settings for insights
        client = ClaudeSDKClient(
            options=ClaudeAgentOptions(
-                model=model,  # Use configured model
+                model=resolve_model_id(model),  # Resolve via API Profile if configured
                system_prompt=system_prompt,
                allowed_tools=[
                    "Read",
@@ -336,8 +337,8 @@ def main():
    )
    parser.add_argument(
        "--model",
-        default="claude-sonnet-4-5-20250929",
-        help="Claude model ID (default: claude-sonnet-4-5-20250929)",
+        default="sonnet",
+        help="Model to use (haiku, sonnet, opus, or full model ID)",
    )
    parser.add_argument(
        "--thinking-level",
@@ -23,6 +23,6 @@ class RoadmapConfig:

    project_dir: Path
    output_dir: Path
-    model: str = "claude-opus-4-5-20251101"
+    model: str = "sonnet"  # Changed from "opus" (fix #433)
    refresh: bool = False  # Force regeneration even if roadmap exists
    enable_competitor_analysis: bool = False  # Enable competitor analysis phase
@@ -27,7 +27,7 @@ class RoadmapOrchestrator:
        self,
        project_dir: Path,
        output_dir: Path | None = None,
-        model: str = "claude-opus-4-5-20251101",
+        model: str = "sonnet",  # Changed from "opus" (fix #433)
        thinking_level: str = "medium",
        refresh: bool = False,
        enable_competitor_analysis: bool = False,
@@ -55,8 +55,8 @@ def main():
    parser.add_argument(
        "--model",
        type=str,
-        default="claude-opus-4-5-20251101",
-        help="Model to use (default: claude-opus-4-5-20251101)",
+        default="sonnet",  # Changed from "opus" (fix #433)
+        help="Model to use (haiku, sonnet, opus, or full model ID)",
    )
    parser.add_argument(
        "--thinking-level",
@@ -47,6 +47,8 @@ if sys.version_info < (3, 10):  # noqa: UP036
 import asyncio
 import io
 import os
+import platform
+import subprocess
 from pathlib import Path

 # Configure safe encoding on Windows BEFORE any imports that might print
@@ -340,8 +342,15 @@ Examples:
            print(f"  {muted('Running:')} {' '.join(run_cmd)}")
            print()

-            # Execute run.py - replace current process
-            os.execv(sys.executable, run_cmd)
+            # Execute run.py
+            # On Windows, use subprocess.run() to properly handle paths with spaces
+            # os.execv() on Windows has issues with argument quoting for paths containing spaces
+            if platform.system() == "Windows":
+                result = subprocess.run(run_cmd)
+                sys.exit(result.returncode)
+            else:
+                # On Unix, os.execv() replaces the current process (more efficient)
+                os.execv(sys.executable, run_cmd)

        sys.exit(0)

@@ -65,11 +65,8 @@ async def bash_security_hook(
    if not command:
        return {}

-    # Get the working directory from context or use current directory
-    # In the actual client, this would be set by the ClaudeSDKClient
-    cwd = os.getcwd()
-    if context and hasattr(context, "cwd"):
-        cwd = context.cwd
+    # Get the working directory from input_data (SDK passes it there, not in context)
+    cwd = input_data.get("cwd") or os.getcwd()

    # Get or create security profile
    # Note: In actual use, spec_dir would be passed through context
@@ -22,6 +22,8 @@ import sys
 from dataclasses import dataclass
 from pathlib import Path

+from core.git_bash import get_git_executable_path
+
 # =============================================================================
 # SECRET PATTERNS
 # =============================================================================
@@ -364,8 +366,9 @@ def scan_content(content: str, file_path: str) -> list[SecretMatch]:
 def get_staged_files() -> list[str]:
    """Get list of staged files from git (excluding deleted files)."""
    try:
+        git_path = get_git_executable_path()
        result = subprocess.run(
-            ["git", "diff", "--cached", "--name-only", "--diff-filter=ACM"],
+            [git_path, "diff", "--cached", "--name-only", "--diff-filter=ACM"],
            capture_output=True,
            text=True,
            check=True,
@@ -379,8 +382,9 @@ def get_staged_files() -> list[str]:
 def get_all_tracked_files() -> list[str]:
    """Get all tracked files in the repository."""
    try:
+        git_path = get_git_executable_path()
        result = subprocess.run(
-            ["git", "ls-files"],
+            [git_path, "ls-files"],
            capture_output=True,
            text=True,
            check=True,
@@ -20,6 +20,8 @@ from datetime import datetime
 from enum import Enum
 from pathlib import Path

+from core.git_bash import get_git_executable_path
+

 class FailureType(Enum):
    """Types of failures that can occur during autonomous builds."""
@@ -425,8 +427,9 @@ class RecoveryManager:
        """
        try:
            # Use git reset --hard to rollback
+            git_path = get_git_executable_path()
            result = subprocess.run(
-                ["git", "reset", "--hard", commit_hash],
+                [git_path, "reset", "--hard", commit_hash],
                cwd=self.project_dir,
                capture_output=True,
                text=True,
@@ -16,7 +16,7 @@ from core.simple_client import create_simple_client
 async def summarize_phase_output(
    phase_name: str,
    phase_output: str,
-    model: str = "claude-sonnet-4-5-20250929",
+    model: str = "sonnet",  # Shorthand - resolved via API Profile if configured
    target_words: int = 500,
 ) -> str:
    """
@@ -57,7 +57,7 @@ class SpecOrchestrator:
        spec_name: str | None = None,
        spec_dir: Path
        | None = None,  # Use existing spec directory (for UI integration)
-        model: str = "claude-sonnet-4-5-20250929",
+        model: str = "sonnet",  # Shorthand - resolved via API Profile if configured
        thinking_level: str = "medium",  # Thinking level for extended thinking
        complexity_override: str | None = None,  # Force a specific complexity
        use_ai_assessment: bool = True,  # Use AI for complexity assessment (vs heuristics)
@@ -173,10 +173,11 @@ class SpecOrchestrator:
                return

            # Summarize the output
+            # Use sonnet shorthand - will resolve via API Profile if configured
            summary = await summarize_phase_output(
                phase_name,
                phase_output,
-                model="claude-sonnet-4-5-20250929",  # Use Sonnet for efficiency
+                model="sonnet",
                target_words=500,
            )

@@ -48,6 +48,7 @@
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
+    "@anthropic-ai/sdk": "^0.71.2",
    "@dnd-kit/core": "^6.3.1",
    "@dnd-kit/sortable": "^10.0.0",
    "@dnd-kit/utilities": "^3.2.2",
@@ -83,6 +84,7 @@
    "i18next": "^25.7.3",
    "lucide-react": "^0.562.0",
    "motion": "^12.23.26",
+    "proper-lockfile": "^4.1.2",
    "react": "^19.2.3",
    "react-dom": "^19.2.3",
    "react-i18next": "^16.5.0",
@@ -102,6 +104,7 @@
    "@eslint/js": "^9.39.1",
    "@playwright/test": "^1.52.0",
    "@tailwindcss/postcss": "^4.1.17",
+    "@testing-library/jest-dom": "^6.9.1",
    "@testing-library/react": "^16.1.0",
    "@types/node": "^25.0.0",
    "@types/react": "^19.2.7",
@@ -111,7 +114,7 @@
    "@vitejs/plugin-react": "^5.1.2",
    "autoprefixer": "^10.4.22",
    "cross-env": "^10.1.0",
-    "electron": "^39.2.7",
+    "electron": "39.2.7",
    "electron-builder": "^26.0.12",
    "electron-vite": "^5.0.0",
    "eslint": "^9.39.1",
@@ -609,12 +609,12 @@ function installPackages(pythonBin, requirementsPath, targetSitePackages) {

  // Install packages directly to target directory
  // --no-compile: Don't create .pyc files (saves space, Python will work without them)
-  // --no-cache-dir: Don't use pip cache
  // --target: Install to specific directory
+  // Note: We intentionally DO use pip's cache to preserve built wheels for packages
+  // like real_ladybug that must be compiled from source on Intel Mac (no PyPI wheel)
  const pipArgs = [
    '-m', 'pip', 'install',
    '--no-compile',
-    '--no-cache-dir',
    '--target', targetSitePackages,
    '-r', requirementsPath,
  ];
@@ -42,13 +42,36 @@ To install:
 ================================================================================
 `;

+/**
+ * Get electron version from package.json
+ */
+function getElectronVersion() {
+  const pkgPath = path.join(__dirname, '..', 'package.json');
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const electronVersion = pkg.devDependencies?.electron || pkg.dependencies?.electron;
+  if (!electronVersion) {
+    return null;
+  }
+  // Strip leading ^ or ~ from version
+  return electronVersion.replace(/^[\^~]/, '');
+}
+
 /**
 * Run electron-rebuild
 */
 function runElectronRebuild() {
  return new Promise((resolve, reject) => {
    const npx = isWindows ? 'npx.cmd' : 'npx';
-    const child = spawn(npx, ['electron-rebuild'], {
+    const electronVersion = getElectronVersion();
+    const args = ['electron-rebuild'];
+
+    // Explicitly pass electron version if detected
+    if (electronVersion) {
+      args.push('-v', electronVersion);
+      console.log(`[postinstall] Using Electron version: ${electronVersion}`);
+    }
+
+    const child = spawn(npx, args, {
      stdio: 'inherit',
      shell: isWindows,
      cwd: path.join(__dirname, '..'),
@@ -30,9 +30,13 @@ const mockProcess = Object.assign(new EventEmitter(), {
  })
 });

-vi.mock('child_process', () => ({
-  spawn: vi.fn(() => mockProcess)
-}));
+vi.mock('child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('child_process')>();
+  return {
+    ...actual,
+    spawn: vi.fn(() => mockProcess)
+  };
+});

 // Mock claude-profile-manager to bypass auth checks in tests
 vi.mock('../../main/claude-profile-manager', () => ({
@@ -107,7 +111,7 @@ describe('Subprocess Spawn Integration', () => {

      const manager = new AgentManager();
      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
-      manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test task description');
+      await manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test task description');

      expect(spawn).toHaveBeenCalledWith(
        EXPECTED_PYTHON_COMMAND,
@@ -132,7 +136,7 @@ describe('Subprocess Spawn Integration', () => {

      const manager = new AgentManager();
      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
-      manager.startTaskExecution('task-1', TEST_PROJECT_PATH, 'spec-001');
+      await manager.startTaskExecution('task-1', TEST_PROJECT_PATH, 'spec-001');

      expect(spawn).toHaveBeenCalledWith(
        EXPECTED_PYTHON_COMMAND,
@@ -154,7 +158,7 @@ describe('Subprocess Spawn Integration', () => {

      const manager = new AgentManager();
      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
-      manager.startQAProcess('task-1', TEST_PROJECT_PATH, 'spec-001');
+      await manager.startQAProcess('task-1', TEST_PROJECT_PATH, 'spec-001');

      expect(spawn).toHaveBeenCalledWith(
        EXPECTED_PYTHON_COMMAND,
@@ -178,7 +182,7 @@ describe('Subprocess Spawn Integration', () => {

      const manager = new AgentManager();
      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
-      manager.startTaskExecution('task-1', TEST_PROJECT_PATH, 'spec-001', {
+      await manager.startTaskExecution('task-1', TEST_PROJECT_PATH, 'spec-001', {
        parallel: true,
        workers: 4
      });
@@ -204,7 +208,7 @@ describe('Subprocess Spawn Integration', () => {
      const logHandler = vi.fn();
      manager.on('log', logHandler);

-      manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test');
+      await manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test');

      // Simulate stdout data (must include newline for buffered output processing)
      mockStdout.emit('data', Buffer.from('Test log output\n'));
@@ -220,7 +224,7 @@ describe('Subprocess Spawn Integration', () => {
      const logHandler = vi.fn();
      manager.on('log', logHandler);

-      manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test');
+      await manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test');

      // Simulate stderr data (must include newline for buffered output processing)
      mockStderr.emit('data', Buffer.from('Progress: 50%\n'));
@@ -236,7 +240,7 @@ describe('Subprocess Spawn Integration', () => {
      const exitHandler = vi.fn();
      manager.on('exit', exitHandler);

-      manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test');
+      await manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test');

      // Simulate process exit
      mockProcess.emit('exit', 0);
@@ -253,7 +257,7 @@ describe('Subprocess Spawn Integration', () => {
      const errorHandler = vi.fn();
      manager.on('error', errorHandler);

-      manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test');
+      await manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test');

      // Simulate process error
      mockProcess.emit('error', new Error('Spawn failed'));
@@ -266,7 +270,7 @@ describe('Subprocess Spawn Integration', () => {

      const manager = new AgentManager();
      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
-      manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test');
+      await manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test');

      expect(manager.isRunning('task-1')).toBe(true);

@@ -293,10 +297,10 @@ describe('Subprocess Spawn Integration', () => {
      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
      expect(manager.getRunningTasks()).toHaveLength(0);

-      manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test 1');
+      await manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test 1');
      expect(manager.getRunningTasks()).toContain('task-1');

-      manager.startTaskExecution('task-2', TEST_PROJECT_PATH, 'spec-001');
+      await manager.startTaskExecution('task-2', TEST_PROJECT_PATH, 'spec-001');
      expect(manager.getRunningTasks()).toHaveLength(2);
    });

@@ -307,7 +311,7 @@ describe('Subprocess Spawn Integration', () => {
      const manager = new AgentManager();
      manager.configure('/custom/python3', AUTO_CLAUDE_SOURCE);

-      manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test');
+      await manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test');

      expect(spawn).toHaveBeenCalledWith(
        '/custom/python3',
@@ -321,8 +325,8 @@ describe('Subprocess Spawn Integration', () => {

      const manager = new AgentManager();
      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
-      manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test 1');
-      manager.startTaskExecution('task-2', TEST_PROJECT_PATH, 'spec-001');
+      await manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test 1');
+      await manager.startTaskExecution('task-2', TEST_PROJECT_PATH, 'spec-001');

      await manager.killAll();

@@ -334,10 +338,10 @@ describe('Subprocess Spawn Integration', () => {

      const manager = new AgentManager();
      manager.configure(undefined, AUTO_CLAUDE_SOURCE);
-      manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test 1');
+      await manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test 1');

      // Start another process for same task
-      manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test 2');
+      await manager.startSpecCreation('task-1', TEST_PROJECT_PATH, 'Test 2');

      // Should have killed the first one
      expect(mockProcess.kill).toHaveBeenCalled();
@@ -88,7 +88,14 @@ if (typeof window !== 'undefined') {
      success: true,
      data: { openProjectIds: [], activeProjectId: null, tabOrder: [] }
    }),
-    saveTabState: vi.fn().mockResolvedValue({ success: true })
+    saveTabState: vi.fn().mockResolvedValue({ success: true }),
+    // Profile-related API methods (API Profile feature)
+    getAPIProfiles: vi.fn(),
+    saveAPIProfile: vi.fn(),
+    updateAPIProfile: vi.fn(),
+    deleteAPIProfile: vi.fn(),
+    setActiveAPIProfile: vi.fn(),
+    testConnection: vi.fn()
  };
 }

@@ -139,7 +139,8 @@ function cleanupTestDirs(): void {
  }
 }

-describe('IPC Handlers', () => {
+// Increase timeout for all tests in this file due to dynamic imports and setup overhead
+describe('IPC Handlers', { timeout: 15000 }, () => {
  let ipcMain: EventEmitter & {
    handlers: Map<string, Function>;
    invokeHandler: (channel: string, event: unknown, ...args: unknown[]) => Promise<unknown>;
@@ -87,14 +87,14 @@ export class AgentManager extends EventEmitter {
  /**
   * Start spec creation process
   */
-  startSpecCreation(
+  async startSpecCreation(
    taskId: string,
    projectPath: string,
    taskDescription: string,
    specDir?: string,
    metadata?: SpecCreationMetadata,
    baseBranch?: string
-  ): void {
+  ): Promise<void> {
    // Pre-flight auth check: Verify active profile has valid authentication
    const profileManager = getClaudeProfileManager();
    if (!profileManager.hasValidAuth()) {
@@ -156,18 +156,18 @@ export class AgentManager extends EventEmitter {
    this.storeTaskContext(taskId, projectPath, '', {}, true, taskDescription, specDir, metadata, baseBranch);

    // Note: This is spec-creation but it chains to task-execution via run.py
-    this.processManager.spawnProcess(taskId, autoBuildSource, args, combinedEnv, 'task-execution');
+    await this.processManager.spawnProcess(taskId, autoBuildSource, args, combinedEnv, 'task-execution');
  }

  /**
   * Start task execution (run.py)
   */
-  startTaskExecution(
+  async startTaskExecution(
    taskId: string,
    projectPath: string,
    specId: string,
    options: TaskExecutionOptions = {}
-  ): void {
+  ): Promise<void> {
    // Pre-flight auth check: Verify active profile has valid authentication
    const profileManager = getClaudeProfileManager();
    if (!profileManager.hasValidAuth()) {
@@ -213,17 +213,17 @@ export class AgentManager extends EventEmitter {
    // Store context for potential restart
    this.storeTaskContext(taskId, projectPath, specId, options, false);

-    this.processManager.spawnProcess(taskId, autoBuildSource, args, combinedEnv, 'task-execution');
+    await this.processManager.spawnProcess(taskId, autoBuildSource, args, combinedEnv, 'task-execution');
  }

  /**
   * Start QA process
   */
-  startQAProcess(
+  async startQAProcess(
    taskId: string,
    projectPath: string,
    specId: string
-  ): void {
+  ): Promise<void> {
    const autoBuildSource = this.processManager.getAutoBuildSourcePath();

    if (!autoBuildSource) {
@@ -243,7 +243,7 @@ export class AgentManager extends EventEmitter {

    const args = [runPath, '--spec', specId, '--project-dir', projectPath, '--qa'];

-    this.processManager.spawnProcess(taskId, autoBuildSource, args, combinedEnv, 'qa-process');
+    await this.processManager.spawnProcess(taskId, autoBuildSource, args, combinedEnv, 'qa-process');
  }

  /**
@@ -0,0 +1,494 @@
+/**
+ * Integration tests for AgentProcessManager
+ * Tests API profile environment variable injection into spawnProcess
+ *
+ * Story 2.3: Env Var Injection - AC1, AC2, AC3, AC4
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { EventEmitter } from 'events';
+
+// Create a mock process object that will be returned by spawn
+function createMockProcess() {
+  return {
+    stdout: { on: vi.fn() },
+    stderr: { on: vi.fn() },
+    on: vi.fn((event: string, callback: any) => {
+      if (event === 'exit') {
+        // Simulate immediate exit with code 0
+        setTimeout(() => callback(0), 10);
+      }
+    }),
+    kill: vi.fn()
+  };
+}
+
+// Mock child_process - must be BEFORE imports of modules that use it
+const spawnCalls: Array<{ command: string; args: string[]; options: { env: Record<string, string>; cwd?: string; [key: string]: unknown } }> = [];
+
+vi.mock('child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('child_process')>();
+  const mockSpawn = vi.fn((command: string, args: string[], options: { env: Record<string, string>; cwd?: string; [key: string]: unknown }) => {
+    // Record the call for test assertions
+    spawnCalls.push({ command, args, options });
+    return createMockProcess();
+  });
+
+  return {
+    ...actual,
+    spawn: mockSpawn,
+    execSync: vi.fn((command: string) => {
+      if (command.includes('git')) {
+        return '/fake/path';
+      }
+      return '';
+    })
+  };
+});
+
+// Mock project-initializer to avoid child_process.execSync issues
+vi.mock('../project-initializer', () => ({
+  getAutoBuildPath: vi.fn(() => '/fake/auto-build'),
+  isInitialized: vi.fn(() => true),
+  initializeProject: vi.fn(),
+  getProjectStorePath: vi.fn(() => '/fake/store/path')
+}));
+
+// Mock project-store BEFORE agent-process imports it
+vi.mock('../project-store', () => ({
+  projectStore: {
+    getProject: vi.fn(),
+    listProjects: vi.fn(),
+    createProject: vi.fn(),
+    updateProject: vi.fn(),
+    deleteProject: vi.fn(),
+    getProjectSettings: vi.fn(),
+    updateProjectSettings: vi.fn()
+  }
+}));
+
+// Mock claude-profile-manager
+vi.mock('../claude-profile-manager', () => ({
+  getClaudeProfileManager: vi.fn(() => ({
+    getProfilePath: vi.fn(() => '/fake/profile/path'),
+    ensureProfileDir: vi.fn(),
+    readProfile: vi.fn(),
+    writeProfile: vi.fn(),
+    deleteProfile: vi.fn()
+  }))
+}));
+
+// Mock dependencies
+vi.mock('../services/profile', () => ({
+  getAPIProfileEnv: vi.fn()
+}));
+
+vi.mock('../rate-limit-detector', () => ({
+  getProfileEnv: vi.fn(() => ({})),
+  detectRateLimit: vi.fn(() => ({ isRateLimited: false })),
+  createSDKRateLimitInfo: vi.fn(),
+  detectAuthFailure: vi.fn(() => ({ isAuthFailure: false }))
+}));
+
+vi.mock('../python-detector', () => ({
+  findPythonCommand: vi.fn(() => 'python'),
+  parsePythonCommand: vi.fn(() => ['python', []])
+}));
+
+vi.mock('electron', () => ({
+  app: {
+    getAppPath: vi.fn(() => '/fake/app/path')
+  }
+}));
+
+// Import AFTER all mocks are set up
+import { AgentProcessManager } from './agent-process';
+import { AgentState } from './agent-state';
+import { AgentEvents } from './agent-events';
+import * as profileService from '../services/profile';
+import * as rateLimitDetector from '../rate-limit-detector';
+
+describe('AgentProcessManager - API Profile Env Injection (Story 2.3)', () => {
+  let processManager: AgentProcessManager;
+  let state: AgentState;
+  let events: AgentEvents;
+  let emitter: EventEmitter;
+
+  beforeEach(() => {
+    // Reset all mocks and spawn calls
+    vi.clearAllMocks();
+    spawnCalls.length = 0;
+
+    // Clear environment variables that could interfere with tests
+    delete process.env.ANTHROPIC_AUTH_TOKEN;
+    delete process.env.ANTHROPIC_BASE_URL;
+    delete process.env.CLAUDE_CODE_OAUTH_TOKEN;
+
+    // Initialize components
+    state = new AgentState();
+    events = new AgentEvents();
+    emitter = new EventEmitter();
+    processManager = new AgentProcessManager(state, events, emitter);
+  });
+
+  afterEach(() => {
+    processManager.killAllProcesses();
+  });
+
+  describe('AC1: API Profile Env Var Injection', () => {
+    it('should inject ANTHROPIC_BASE_URL when active profile has baseUrl', async () => {
+      const mockApiProfileEnv = {
+        ANTHROPIC_BASE_URL: 'https://custom.api.com',
+        ANTHROPIC_AUTH_TOKEN: 'sk-test-key'
+      };
+
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValue(mockApiProfileEnv);
+
+      await processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], {}, 'task-execution');
+
+      expect(spawnCalls).toHaveLength(1);
+      expect(spawnCalls[0].command).toBe('python');
+      expect(spawnCalls[0].args).toContain('run.py');
+      expect(spawnCalls[0].options.env).toMatchObject({
+        ANTHROPIC_BASE_URL: 'https://custom.api.com',
+        ANTHROPIC_AUTH_TOKEN: 'sk-test-key'
+      });
+    });
+
+    it('should inject ANTHROPIC_AUTH_TOKEN when active profile has apiKey', async () => {
+      const mockApiProfileEnv = {
+        ANTHROPIC_AUTH_TOKEN: 'sk-custom-key-12345678'
+      };
+
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValue(mockApiProfileEnv);
+
+      await processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], {}, 'task-execution');
+
+      expect(spawnCalls).toHaveLength(1);
+      expect(spawnCalls[0].options.env.ANTHROPIC_AUTH_TOKEN).toBe('sk-custom-key-12345678');
+    });
+
+    it('should inject model env vars when active profile has models configured', async () => {
+      const mockApiProfileEnv = {
+        ANTHROPIC_MODEL: 'claude-3-5-sonnet-20241022',
+        ANTHROPIC_DEFAULT_HAIKU_MODEL: 'claude-3-5-haiku-20241022',
+        ANTHROPIC_DEFAULT_SONNET_MODEL: 'claude-3-5-sonnet-20241022',
+        ANTHROPIC_DEFAULT_OPUS_MODEL: 'claude-3-5-opus-20241022'
+      };
+
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValue(mockApiProfileEnv);
+
+      await processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], {}, 'task-execution');
+
+      expect(spawnCalls).toHaveLength(1);
+      expect(spawnCalls[0].options.env).toMatchObject({
+        ANTHROPIC_MODEL: 'claude-3-5-sonnet-20241022',
+        ANTHROPIC_DEFAULT_HAIKU_MODEL: 'claude-3-5-haiku-20241022',
+        ANTHROPIC_DEFAULT_SONNET_MODEL: 'claude-3-5-sonnet-20241022',
+        ANTHROPIC_DEFAULT_OPUS_MODEL: 'claude-3-5-opus-20241022'
+      });
+    });
+
+    it('should give API profile env vars highest precedence over extraEnv', async () => {
+      const extraEnv = {
+        ANTHROPIC_AUTH_TOKEN: 'sk-extra-token',
+        ANTHROPIC_BASE_URL: 'https://extra.com'
+      };
+
+      const mockApiProfileEnv = {
+        ANTHROPIC_AUTH_TOKEN: 'sk-profile-token',
+        ANTHROPIC_BASE_URL: 'https://profile.com'
+      };
+
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValue(mockApiProfileEnv);
+
+      await processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], extraEnv, 'task-execution');
+
+      expect(spawnCalls).toHaveLength(1);
+      // API profile should override extraEnv
+      expect(spawnCalls[0].options.env.ANTHROPIC_AUTH_TOKEN).toBe('sk-profile-token');
+      expect(spawnCalls[0].options.env.ANTHROPIC_BASE_URL).toBe('https://profile.com');
+    });
+  });
+
+  describe('AC2: OAuth Mode (No Active Profile)', () => {
+    let originalEnv: NodeJS.ProcessEnv;
+
+    beforeEach(() => {
+      // Save original environment before each test
+      originalEnv = { ...process.env };
+    });
+
+    afterEach(() => {
+      // Restore original environment after each test
+      process.env = originalEnv;
+    });
+
+    it('should NOT set ANTHROPIC_AUTH_TOKEN when no active profile (OAuth mode)', async () => {
+      // Return empty object = OAuth mode
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValue({});
+
+      // Set OAuth token via getProfileEnv (existing flow)
+      vi.mocked(rateLimitDetector.getProfileEnv).mockReturnValue({
+        CLAUDE_CODE_OAUTH_TOKEN: 'oauth-token-123'
+      });
+
+      await processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], {}, 'task-execution');
+
+      expect(spawnCalls).toHaveLength(1);
+      const envArg = spawnCalls[0].options.env as Record<string, unknown>;
+      expect(envArg.CLAUDE_CODE_OAUTH_TOKEN).toBe('oauth-token-123');
+      // OAuth mode clears ANTHROPIC_AUTH_TOKEN with empty string (not undefined)
+      expect(envArg.ANTHROPIC_AUTH_TOKEN).toBe('');
+    });
+
+    it('should return empty object from getAPIProfileEnv when activeProfileId is null', async () => {
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValue({});
+
+      const result = await profileService.getAPIProfileEnv();
+      expect(result).toEqual({});
+    });
+
+    it('should clear stale ANTHROPIC_AUTH_TOKEN from process.env when switching to OAuth mode', async () => {
+      // Simulate process.env having stale ANTHROPIC_* vars from previous session
+      process.env = {
+        ...originalEnv,
+        ANTHROPIC_AUTH_TOKEN: 'stale-token-from-env',
+        ANTHROPIC_BASE_URL: 'https://stale.example.com'
+      };
+
+      // OAuth mode - no active API profile
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValue({});
+
+      // Set OAuth token
+      vi.mocked(rateLimitDetector.getProfileEnv).mockReturnValue({
+        CLAUDE_CODE_OAUTH_TOKEN: 'oauth-token-456'
+      });
+
+      await processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], {}, 'task-execution');
+
+      const envArg = spawnCalls[0].options.env as Record<string, unknown>;
+      
+      // OAuth token should be present
+      expect(envArg.CLAUDE_CODE_OAUTH_TOKEN).toBe('oauth-token-456');
+      
+      // Stale ANTHROPIC_* vars should be cleared (empty string overrides process.env)
+      expect(envArg.ANTHROPIC_AUTH_TOKEN).toBe('');
+      expect(envArg.ANTHROPIC_BASE_URL).toBe('');
+    });
+
+    it('should clear stale ANTHROPIC_BASE_URL when switching to OAuth mode', async () => {
+      process.env = {
+        ...originalEnv,
+        ANTHROPIC_BASE_URL: 'https://old-custom-endpoint.com'
+      };
+
+      // OAuth mode
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValue({});
+      vi.mocked(rateLimitDetector.getProfileEnv).mockReturnValue({
+        CLAUDE_CODE_OAUTH_TOKEN: 'oauth-token-789'
+      });
+
+      await processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], {}, 'task-execution');
+
+      const envArg = spawnCalls[0].options.env as Record<string, unknown>;
+      
+      // Should clear the base URL (so Python uses default api.anthropic.com)
+      expect(envArg.ANTHROPIC_BASE_URL).toBe('');
+      expect(envArg.CLAUDE_CODE_OAUTH_TOKEN).toBe('oauth-token-789');
+    });
+
+    it('should NOT clear ANTHROPIC_* vars when API Profile is active', async () => {
+      process.env = {
+        ...originalEnv,
+        ANTHROPIC_AUTH_TOKEN: 'old-token-in-env'
+      };
+
+      // API Profile mode - active profile
+      const mockApiProfileEnv = {
+        ANTHROPIC_AUTH_TOKEN: 'sk-profile-active',
+        ANTHROPIC_BASE_URL: 'https://active-profile.com'
+      };
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValue(mockApiProfileEnv);
+
+      await processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], {}, 'task-execution');
+
+      const envArg = spawnCalls[0].options.env as Record<string, unknown>;
+      
+      // Should use API profile vars, NOT clear them
+      expect(envArg.ANTHROPIC_AUTH_TOKEN).toBe('sk-profile-active');
+      expect(envArg.ANTHROPIC_BASE_URL).toBe('https://active-profile.com');
+    });
+  });
+
+  describe('AC4: No API Key Logging', () => {
+    it('should never log full API keys in spawn env vars', async () => {
+      const mockApiProfileEnv = {
+        ANTHROPIC_AUTH_TOKEN: 'sk-sensitive-api-key-12345678',
+        ANTHROPIC_BASE_URL: 'https://api.example.com'
+      };
+
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValue(mockApiProfileEnv);
+
+      // Mock ALL console methods to capture any debug/error output
+      const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const consoleDebugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+
+      await processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], {}, 'task-execution');
+
+      // Get the env object passed to spawn
+      const envArg = spawnCalls[0].options.env as Record<string, unknown>;
+
+      // Verify the full API key is in the env (for Python subprocess)
+      expect(envArg.ANTHROPIC_AUTH_TOKEN).toBe('sk-sensitive-api-key-12345678');
+
+      // Collect ALL console output from all methods
+      const allLogCalls = [
+        ...consoleLogSpy.mock.calls,
+        ...consoleErrorSpy.mock.calls,
+        ...consoleWarnSpy.mock.calls,
+        ...consoleDebugSpy.mock.calls
+      ].flatMap(call => call.map(String));
+      const logString = JSON.stringify(allLogCalls);
+
+      // The full API key should NOT appear in any logs (AC4 compliance)
+      expect(logString).not.toContain('sk-sensitive-api-key-12345678');
+
+      // Restore all spies
+      consoleLogSpy.mockRestore();
+      consoleErrorSpy.mockRestore();
+      consoleWarnSpy.mockRestore();
+      consoleDebugSpy.mockRestore();
+    });
+
+    it('should not log API key even in error scenarios', async () => {
+      const mockApiProfileEnv = {
+        ANTHROPIC_AUTH_TOKEN: 'sk-secret-key-for-error-test',
+        ANTHROPIC_BASE_URL: 'https://api.example.com'
+      };
+
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValue(mockApiProfileEnv);
+
+      // Mock console methods
+      const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+      const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+      await processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], {}, 'task-execution');
+
+      // Collect all error and log output
+      const allOutput = [
+        ...consoleErrorSpy.mock.calls,
+        ...consoleLogSpy.mock.calls
+      ].flatMap(call => call.map(arg => typeof arg === 'object' ? JSON.stringify(arg) : String(arg)));
+      const outputString = allOutput.join(' ');
+
+      // Verify API key is never exposed in logs
+      expect(outputString).not.toContain('sk-secret-key-for-error-test');
+
+      consoleErrorSpy.mockRestore();
+      consoleLogSpy.mockRestore();
+    });
+  });
+
+  describe('AC3: Profile Switching Between Builds', () => {
+    it('should allow different profiles for different spawn calls', async () => {
+      // First spawn with Profile A
+      const profileAEnv = {
+        ANTHROPIC_AUTH_TOKEN: 'sk-profile-a',
+        ANTHROPIC_BASE_URL: 'https://api-a.com'
+      };
+
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValueOnce(profileAEnv);
+
+      await processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], {}, 'task-execution');
+
+      const firstEnv = spawnCalls[0].options.env as Record<string, unknown>;
+      expect(firstEnv.ANTHROPIC_AUTH_TOKEN).toBe('sk-profile-a');
+
+      // Second spawn with Profile B (user switched active profile)
+      const profileBEnv = {
+        ANTHROPIC_AUTH_TOKEN: 'sk-profile-b',
+        ANTHROPIC_BASE_URL: 'https://api-b.com'
+      };
+
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValueOnce(profileBEnv);
+
+      await processManager.spawnProcess('task-2', '/fake/cwd', ['run.py'], {}, 'task-execution');
+
+      const secondEnv = spawnCalls[1].options.env as Record<string, unknown>;
+      expect(secondEnv.ANTHROPIC_AUTH_TOKEN).toBe('sk-profile-b');
+
+      // Verify first spawn's env is NOT affected by second spawn
+      expect(firstEnv.ANTHROPIC_AUTH_TOKEN).toBe('sk-profile-a');
+    });
+  });
+
+  describe('Integration: Combined env precedence', () => {
+    it('should merge env vars in correct precedence order', async () => {
+      const extraEnv = {
+        CUSTOM_VAR: 'from-extra'
+      };
+
+      const profileEnv = {
+        CLAUDE_CONFIG_DIR: '/custom/config'
+      };
+
+      const apiProfileEnv = {
+        ANTHROPIC_AUTH_TOKEN: 'sk-api-profile',
+        ANTHROPIC_BASE_URL: 'https://api-profile.com'
+      };
+
+      vi.mocked(rateLimitDetector.getProfileEnv).mockReturnValue(profileEnv);
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValue(apiProfileEnv);
+
+      await processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], extraEnv, 'task-execution');
+
+      const envArg = spawnCalls[0].options.env as Record<string, unknown>;
+
+      // Verify all sources are included
+      expect(envArg.CUSTOM_VAR).toBe('from-extra'); // From extraEnv
+      expect(envArg.CLAUDE_CONFIG_DIR).toBe('/custom/config'); // From profileEnv
+      expect(envArg.ANTHROPIC_AUTH_TOKEN).toBe('sk-api-profile'); // From apiProfileEnv (highest for ANTHROPIC_*)
+
+      // Verify standard Python env vars
+      expect(envArg.PYTHONUNBUFFERED).toBe('1');
+      expect(envArg.PYTHONIOENCODING).toBe('utf-8');
+      expect(envArg.PYTHONUTF8).toBe('1');
+    });
+
+    it('should call getOAuthModeClearVars and apply clearing when in OAuth mode', async () => {
+      // OAuth mode - empty API profile
+      vi.mocked(profileService.getAPIProfileEnv).mockResolvedValue({});
+
+      await processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], {}, 'task-execution');
+
+      const envArg = spawnCalls[0].options.env as Record<string, unknown>;
+
+      // Verify clearing vars are applied (empty strings for ANTHROPIC_* vars)
+      expect(envArg.ANTHROPIC_AUTH_TOKEN).toBe('');
+      expect(envArg.ANTHROPIC_BASE_URL).toBe('');
+      expect(envArg.ANTHROPIC_MODEL).toBe('');
+      expect(envArg.ANTHROPIC_DEFAULT_HAIKU_MODEL).toBe('');
+      expect(envArg.ANTHROPIC_DEFAULT_SONNET_MODEL).toBe('');
+      expect(envArg.ANTHROPIC_DEFAULT_OPUS_MODEL).toBe('');
+    });
+
+    it('should handle getAPIProfileEnv errors gracefully', async () => {
+      // Simulate service error
+      vi.mocked(profileService.getAPIProfileEnv).mockRejectedValue(new Error('Service unavailable'));
+
+      // Should not throw - should fall back to OAuth mode
+      await expect(
+        processManager.spawnProcess('task-1', '/fake/cwd', ['run.py'], {}, 'task-execution')
+      ).resolves.not.toThrow();
+
+      const envArg = spawnCalls[0].options.env as Record<string, unknown>;
+
+      // Should have clearing vars (falls back to OAuth mode on error)
+      expect(envArg.ANTHROPIC_AUTH_TOKEN).toBe('');
+      expect(envArg.ANTHROPIC_BASE_URL).toBe('');
+    });
+  });
+});
@@ -7,6 +7,7 @@ import { AgentState } from './agent-state';
 import { AgentEvents } from './agent-events';
 import { ProcessType, ExecutionProgressData } from './types';
 import { detectRateLimit, createSDKRateLimitInfo, getProfileEnv, detectAuthFailure } from '../rate-limit-detector';
+import { getAPIProfileEnv } from '../services/profile';
 import { projectStore } from '../project-store';
 import { getClaudeProfileManager } from '../claude-profile-manager';
 import { parsePythonCommand, validatePythonPath } from '../python-detector';
@@ -14,6 +15,8 @@ import { pythonEnvManager, getConfiguredPythonPath } from '../python-env-manager
 import { buildMemoryEnvVars } from '../memory-env-builder';
 import { readSettingsFile } from '../settings-utils';
 import type { AppSettings } from '../../shared/types/settings';
+import { getOAuthModeClearVars } from './env-utils';
+import { getAugmentedEnv } from '../env-utils';

 /**
 * Process spawning and lifecycle management
@@ -53,8 +56,11 @@ export class AgentProcessManager {
    extraEnv: Record<string, string>
  ): NodeJS.ProcessEnv {
    const profileEnv = getProfileEnv();
+    // Use getAugmentedEnv() to ensure common tool paths (dotnet, homebrew, etc.)
+    // are available even when app is launched from Finder/Dock
+    const augmentedEnv = getAugmentedEnv();
    return {
-      ...process.env,
+      ...augmentedEnv,
      ...extraEnv,
      ...profileEnv,
      PYTHONUNBUFFERED: '1',
@@ -195,6 +201,8 @@ export class AgentProcessManager {

    // Auto-detect from app location (configured path was invalid or not set)
    const possiblePaths = [
+      // Packaged app: backend is in extraResources (process.resourcesPath/backend)
+      ...(app.isPackaged ? [path.join(process.resourcesPath, 'backend')] : []),
      // Dev mode: from dist/main -> ../../backend (apps/frontend/out/main -> apps/backend)
      path.resolve(__dirname, '..', '..', '..', 'backend'),
      // Alternative: from app root -> apps/backend
@@ -237,6 +245,51 @@ export class AgentProcessManager {
    return env;
  }

+  /**
+   * Parse environment variables from a .env file content.
+   * Filters out empty values to prevent overriding valid tokens from profiles.
+   */
+  private parseEnvFile(envPath: string): Record<string, string> {
+    if (!existsSync(envPath)) {
+      return {};
+    }
+
+    try {
+      const envContent = readFileSync(envPath, 'utf-8');
+      const envVars: Record<string, string> = {};
+
+      // Handle both Unix (\n) and Windows (\r\n) line endings
+      for (const line of envContent.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        // Skip comments and empty lines
+        if (!trimmed || trimmed.startsWith('#')) {
+          continue;
+        }
+
+        const eqIndex = trimmed.indexOf('=');
+        if (eqIndex > 0) {
+          const key = trimmed.substring(0, eqIndex).trim();
+          let value = trimmed.substring(eqIndex + 1).trim();
+
+          // Remove quotes if present
+          if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+          }
+
+          // Skip empty values to prevent overriding valid values from other sources
+          if (value) {
+            envVars[key] = value;
+          }
+        }
+      }
+
+      return envVars;
+    } catch {
+      return {};
+    }
+  }
+
  /**
   * Load environment variables from project's .auto-claude/.env file
   * This contains frontend-configured settings like memory/Graphiti configuration
@@ -251,41 +304,7 @@ export class AgentProcessManager {
    }

    const envPath = path.join(projectPath, project.autoBuildPath, '.env');
-    if (!existsSync(envPath)) {
-      return {};
-    }
-
-    try {
-      const envContent = readFileSync(envPath, 'utf-8');
-      const envVars: Record<string, string> = {};
-
-      // Handle both Unix (\n) and Windows (\r\n) line endings
-      for (const line of envContent.split(/\r?\n/)) {
-        const trimmed = line.trim();
-        // Skip comments and empty lines
-        if (!trimmed || trimmed.startsWith('#')) {
-          continue;
-        }
-
-        const eqIndex = trimmed.indexOf('=');
-        if (eqIndex > 0) {
-          const key = trimmed.substring(0, eqIndex).trim();
-          let value = trimmed.substring(eqIndex + 1).trim();
-
-          // Remove quotes if present
-          if ((value.startsWith('"') && value.endsWith('"')) ||
-              (value.startsWith("'") && value.endsWith("'"))) {
-            value = value.slice(1, -1);
-          }
-
-          envVars[key] = value;
-        }
-      }
-
-      return envVars;
-    } catch {
-      return {};
-    }
+    return this.parseEnvFile(envPath);
  }

  /**
@@ -298,50 +317,19 @@ export class AgentProcessManager {
    }

    const envPath = path.join(autoBuildSource, '.env');
-    if (!existsSync(envPath)) {
-      return {};
-    }
-
-    try {
-      const envContent = readFileSync(envPath, 'utf-8');
-      const envVars: Record<string, string> = {};
-
-      // Handle both Unix (\n) and Windows (\r\n) line endings
-      for (const line of envContent.split(/\r?\n/)) {
-        const trimmed = line.trim();
-        // Skip comments and empty lines
-        if (!trimmed || trimmed.startsWith('#')) {
-          continue;
-        }
-
-        const eqIndex = trimmed.indexOf('=');
-        if (eqIndex > 0) {
-          const key = trimmed.substring(0, eqIndex).trim();
-          let value = trimmed.substring(eqIndex + 1).trim();
-
-          // Remove quotes if present
-          if ((value.startsWith('"') && value.endsWith('"')) ||
-              (value.startsWith("'") && value.endsWith("'"))) {
-            value = value.slice(1, -1);
-          }
-
-          envVars[key] = value;
-        }
-      }
-
-      return envVars;
-    } catch {
-      return {};
-    }
+    return this.parseEnvFile(envPath);
  }

-  spawnProcess(
+  /**
+   * Spawn a Python process for task execution
+   */
+  async spawnProcess(
    taskId: string,
    cwd: string,
    args: string[],
    extraEnv: Record<string, string> = {},
    processType: ProcessType = 'task-execution'
-  ): void {
+  ): Promise<void> {
    const isSpecRunner = processType === 'spec-creation';
    this.killProcess(taskId);

@@ -351,13 +339,27 @@ export class AgentProcessManager {
    // Get Python environment (PYTHONPATH for bundled packages, etc.)
    const pythonEnv = pythonEnvManager.getPythonEnv();

-    // Parse Python command to handle space-separated commands like "py -3"
+    // Get active API profile environment variables
+    let apiProfileEnv: Record<string, string> = {};
+    try {
+      apiProfileEnv = await getAPIProfileEnv();
+    } catch (error) {
+      console.error('[Agent Process] Failed to get API profile env:', error);
+      // Continue with empty profile env (falls back to OAuth mode)
+    }
+
+    // Get OAuth mode clearing vars (clears stale ANTHROPIC_* vars when in OAuth mode)
+    const oauthModeClearVars = getOAuthModeClearVars(apiProfileEnv);
+
+    // Parse Python commandto handle space-separated commands like "py -3"
    const [pythonCommand, pythonBaseArgs] = parsePythonCommand(this.getPythonPath());
    const childProcess = spawn(pythonCommand, [...pythonBaseArgs, ...args], {
      cwd,
      env: {
        ...env, // Already includes process.env, extraEnv, profileEnv, PYTHONUNBUFFERED, PYTHONUTF8
-        ...pythonEnv // Include Python environment (PYTHONPATH for bundled packages)
+        ...pythonEnv, // Include Python environment (PYTHONPATH for bundled packages)
+        ...oauthModeClearVars, // Clear stale ANTHROPIC_* vars when in OAuth mode
+        ...apiProfileEnv // Include active API profile config (highest priority for ANTHROPIC_* vars)
      }
    });

@@ -9,6 +9,8 @@ import { RoadmapConfig } from './types';
 import type { IdeationConfig, Idea } from '../../shared/types';
 import { MODEL_ID_MAP } from '../../shared/constants';
 import { detectRateLimit, createSDKRateLimitInfo, getProfileEnv } from '../rate-limit-detector';
+import { getAPIProfileEnv } from '../services/profile';
+import { getOAuthModeClearVars } from './env-utils';
 import { debugLog, debugError } from '../../shared/utils/debug-logger';
 import { parsePythonCommand } from '../python-detector';
 import { pythonEnvManager } from '../python-env-manager';
@@ -44,14 +46,14 @@ export class AgentQueueManager {
   *   This allows refreshing competitor data independently of the general roadmap refresh.
   *   Use when user explicitly wants new competitor research.
   */
-  startRoadmapGeneration(
+  async startRoadmapGeneration(
    projectId: string,
    projectPath: string,
    refresh: boolean = false,
    enableCompetitorAnalysis: boolean = false,
    refreshCompetitorAnalysis: boolean = false,
    config?: RoadmapConfig
-  ): void {
+  ): Promise<void> {
    debugLog('[Agent Queue] Starting roadmap generation:', {
      projectId,
      projectPath,
@@ -105,18 +107,18 @@ export class AgentQueueManager {
    debugLog('[Agent Queue] Spawning roadmap process with args:', args);

    // Use projectId as taskId for roadmap operations
-    this.spawnRoadmapProcess(projectId, projectPath, args);
+    await this.spawnRoadmapProcess(projectId, projectPath, args);
  }

  /**
   * Start ideation generation process
   */
-  startIdeationGeneration(
+  async startIdeationGeneration(
    projectId: string,
    projectPath: string,
    config: IdeationConfig,
    refresh: boolean = false
-  ): void {
+  ): Promise<void> {
    debugLog('[Agent Queue] Starting ideation generation:', {
      projectId,
      projectPath,
@@ -181,17 +183,17 @@ export class AgentQueueManager {
    debugLog('[Agent Queue] Spawning ideation process with args:', args);

    // Use projectId as taskId for ideation operations
-    this.spawnIdeationProcess(projectId, projectPath, args);
+    await this.spawnIdeationProcess(projectId, projectPath, args);
  }

  /**
   * Spawn a Python process for ideation generation
   */
-  private spawnIdeationProcess(
+  private async spawnIdeationProcess(
    projectId: string,
    projectPath: string,
    args: string[]
-  ): void {
+  ): Promise<void> {
    debugLog('[Agent Queue] Spawning ideation process:', { projectId, projectPath });

    // Kill existing process for this project if any
@@ -214,6 +216,12 @@ export class AgentQueueManager {
    // Get active Claude profile environment (CLAUDE_CODE_OAUTH_TOKEN if not default)
    const profileEnv = getProfileEnv();

+    // Get active API profile environment variables
+    const apiProfileEnv = await getAPIProfileEnv();
+
+    // Get OAuth mode clearing vars (clears stale ANTHROPIC_* vars when in OAuth mode)
+    const oauthModeClearVars = getOAuthModeClearVars(apiProfileEnv);
+
    // Get Python path from process manager (uses venv if configured)
    const pythonPath = this.processManager.getPythonPath();

@@ -234,28 +242,30 @@ export class AgentQueueManager {
    // 1. process.env (system)
    // 2. pythonEnv (bundled packages environment)
    // 3. combinedEnv (auto-claude/.env for CLI usage)
-    // 4. profileEnv (Electron app OAuth token - highest priority)
-    // 5. Our specific overrides
+    // 4. oauthModeClearVars (clear stale ANTHROPIC_* vars when in OAuth mode)
+    // 5. profileEnv (Electron app OAuth token)
+    // 6. apiProfileEnv (Active API profile config - highest priority for ANTHROPIC_* vars)
+    // 7. Our specific overrides
    const finalEnv = {
      ...process.env,
      ...pythonEnv,
      ...combinedEnv,
+      ...oauthModeClearVars,
      ...profileEnv,
+      ...apiProfileEnv,
      PYTHONPATH: combinedPythonPath,
      PYTHONUNBUFFERED: '1',
      PYTHONUTF8: '1'
    };

-    // Debug: Show OAuth token source
+    // Debug: Show OAuth token source (token values intentionally omitted for security - AC4)
    const tokenSource = profileEnv['CLAUDE_CODE_OAUTH_TOKEN']
      ? 'Electron app profile'
      : (combinedEnv['CLAUDE_CODE_OAUTH_TOKEN'] ? 'auto-claude/.env' : 'not found');
-    const oauthToken = (finalEnv as Record<string, string | undefined>)['CLAUDE_CODE_OAUTH_TOKEN'];
-    const hasToken = !!oauthToken;
+    const hasToken = !!(finalEnv as Record<string, string | undefined>)['CLAUDE_CODE_OAUTH_TOKEN'];
    debugLog('[Agent Queue] OAuth token status:', {
      source: tokenSource,
-      hasToken,
-      tokenPreview: hasToken ? oauthToken?.substring(0, 20) + '...' : 'none'
+      hasToken
    });

    // Parse Python command to handle space-separated commands like "py -3"
@@ -500,11 +510,11 @@ export class AgentQueueManager {
  /**
   * Spawn a Python process for roadmap generation
   */
-  private spawnRoadmapProcess(
+  private async spawnRoadmapProcess(
    projectId: string,
    projectPath: string,
    args: string[]
-  ): void {
+  ): Promise<void> {
    debugLog('[Agent Queue] Spawning roadmap process:', { projectId, projectPath });

    // Kill existing process for this project if any
@@ -527,6 +537,12 @@ export class AgentQueueManager {
    // Get active Claude profile environment (CLAUDE_CODE_OAUTH_TOKEN if not default)
    const profileEnv = getProfileEnv();

+    // Get active API profile environment variables
+    const apiProfileEnv = await getAPIProfileEnv();
+
+    // Get OAuth mode clearing vars (clears stale ANTHROPIC_* vars when in OAuth mode)
+    const oauthModeClearVars = getOAuthModeClearVars(apiProfileEnv);
+
    // Get Python path from process manager (uses venv if configured)
    const pythonPath = this.processManager.getPythonPath();

@@ -547,28 +563,30 @@ export class AgentQueueManager {
    // 1. process.env (system)
    // 2. pythonEnv (bundled packages environment)
    // 3. combinedEnv (auto-claude/.env for CLI usage)
-    // 4. profileEnv (Electron app OAuth token - highest priority)
-    // 5. Our specific overrides
+    // 4. oauthModeClearVars (clear stale ANTHROPIC_* vars when in OAuth mode)
+    // 5. profileEnv (Electron app OAuth token)
+    // 6. apiProfileEnv (Active API profile config - highest priority for ANTHROPIC_* vars)
+    // 7. Our specific overrides
    const finalEnv = {
      ...process.env,
      ...pythonEnv,
      ...combinedEnv,
+      ...oauthModeClearVars,
      ...profileEnv,
+      ...apiProfileEnv,
      PYTHONPATH: combinedPythonPath,
      PYTHONUNBUFFERED: '1',
      PYTHONUTF8: '1'
    };

-    // Debug: Show OAuth token source
+    // Debug: Show OAuth token source (token values intentionally omitted for security - AC4)
    const tokenSource = profileEnv['CLAUDE_CODE_OAUTH_TOKEN']
      ? 'Electron app profile'
      : (combinedEnv['CLAUDE_CODE_OAUTH_TOKEN'] ? 'auto-claude/.env' : 'not found');
-    const oauthToken = (finalEnv as Record<string, string | undefined>)['CLAUDE_CODE_OAUTH_TOKEN'];
-    const hasToken = !!oauthToken;
+    const hasToken = !!(finalEnv as Record<string, string | undefined>)['CLAUDE_CODE_OAUTH_TOKEN'];
    debugLog('[Agent Queue] OAuth token status:', {
      source: tokenSource,
-      hasToken,
-      tokenPreview: hasToken ? oauthToken?.substring(0, 20) + '...' : 'none'
+      hasToken
    });

    // Parse Python command to handle space-separated commands like "py -3"
@@ -0,0 +1,129 @@
+/**
+ * Unit tests for env-utils
+ * Tests OAuth mode environment variable clearing functionality
+ */
+
+import { describe, it, expect } from 'vitest';
+import { getOAuthModeClearVars } from './env-utils';
+
+describe('getOAuthModeClearVars', () => {
+  describe('OAuth mode (no active API profile)', () => {
+    it('should return clearing vars when apiProfileEnv is empty', () => {
+      const result = getOAuthModeClearVars({});
+
+      expect(result).toEqual({
+        ANTHROPIC_AUTH_TOKEN: '',
+        ANTHROPIC_BASE_URL: '',
+        ANTHROPIC_MODEL: '',
+        ANTHROPIC_DEFAULT_HAIKU_MODEL: '',
+        ANTHROPIC_DEFAULT_SONNET_MODEL: '',
+        ANTHROPIC_DEFAULT_OPUS_MODEL: ''
+      });
+    });
+
+    it('should clear all ANTHROPIC_* environment variables', () => {
+      const result = getOAuthModeClearVars({});
+
+      // Verify all known ANTHROPIC_* vars are cleared
+      expect(result.ANTHROPIC_AUTH_TOKEN).toBe('');
+      expect(result.ANTHROPIC_BASE_URL).toBe('');
+      expect(result.ANTHROPIC_MODEL).toBe('');
+      expect(result.ANTHROPIC_DEFAULT_HAIKU_MODEL).toBe('');
+      expect(result.ANTHROPIC_DEFAULT_SONNET_MODEL).toBe('');
+      expect(result.ANTHROPIC_DEFAULT_OPUS_MODEL).toBe('');
+    });
+  });
+
+  describe('API Profile mode (active profile)', () => {
+    it('should return empty object when apiProfileEnv has values', () => {
+      const apiProfileEnv = {
+        ANTHROPIC_AUTH_TOKEN: 'sk-active-profile',
+        ANTHROPIC_BASE_URL: 'https://custom.api.com'
+      };
+
+      const result = getOAuthModeClearVars(apiProfileEnv);
+
+      expect(result).toEqual({});
+    });
+
+    it('should NOT clear vars when API profile is active', () => {
+      const apiProfileEnv = {
+        ANTHROPIC_AUTH_TOKEN: 'sk-test',
+        ANTHROPIC_BASE_URL: 'https://test.com',
+        ANTHROPIC_MODEL: 'claude-3-opus'
+      };
+
+      const result = getOAuthModeClearVars(apiProfileEnv);
+
+      // Should not return any clearing vars
+      expect(Object.keys(result)).toHaveLength(0);
+    });
+
+    it('should detect non-empty profile even with single property', () => {
+      const apiProfileEnv = {
+        ANTHROPIC_AUTH_TOKEN: 'sk-minimal'
+      };
+
+      const result = getOAuthModeClearVars(apiProfileEnv);
+
+      expect(result).toEqual({});
+    });
+  });
+
+  describe('Edge cases', () => {
+    it('should handle undefined gracefully (treat as empty)', () => {
+      // TypeScript should prevent this, but runtime safety
+      const result = getOAuthModeClearVars(undefined as any);
+
+      // Should treat undefined as empty object -> OAuth mode
+      expect(result).toBeDefined();
+    });
+
+    it('should handle null gracefully (treat as empty)', () => {
+      // Runtime safety for null values
+      const result = getOAuthModeClearVars(null as any);
+
+      // Should treat null as OAuth mode and return clearing vars
+      expect(result).toEqual({
+        ANTHROPIC_AUTH_TOKEN: '',
+        ANTHROPIC_BASE_URL: '',
+        ANTHROPIC_MODEL: '',
+        ANTHROPIC_DEFAULT_HAIKU_MODEL: '',
+        ANTHROPIC_DEFAULT_SONNET_MODEL: '',
+        ANTHROPIC_DEFAULT_OPUS_MODEL: ''
+      });
+    });
+
+    it('should return consistent object shape for OAuth mode', () => {
+      const result1 = getOAuthModeClearVars({});
+      const result2 = getOAuthModeClearVars({});
+
+      expect(result1).toEqual(result2);
+      // Use specific expected keys instead of magic number
+      const expectedKeys = [
+        'ANTHROPIC_AUTH_TOKEN',
+        'ANTHROPIC_BASE_URL',
+        'ANTHROPIC_MODEL',
+        'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+        'ANTHROPIC_DEFAULT_SONNET_MODEL',
+        'ANTHROPIC_DEFAULT_OPUS_MODEL'
+      ];
+      expect(Object.keys(result1).sort()).toEqual(expectedKeys.sort());
+    });
+
+    it('should NOT clear if apiProfileEnv has non-ANTHROPIC keys only', () => {
+      // Edge case: service returns metadata but no ANTHROPIC_* vars
+      const result = getOAuthModeClearVars({ SOME_OTHER_VAR: 'value' });
+
+      // Should treat as OAuth mode since no ANTHROPIC_* keys present
+      expect(result).toEqual({
+        ANTHROPIC_AUTH_TOKEN: '',
+        ANTHROPIC_BASE_URL: '',
+        ANTHROPIC_MODEL: '',
+        ANTHROPIC_DEFAULT_HAIKU_MODEL: '',
+        ANTHROPIC_DEFAULT_SONNET_MODEL: '',
+        ANTHROPIC_DEFAULT_OPUS_MODEL: ''
+      });
+    });
+  });
+});
@@ -0,0 +1,39 @@
+/**
+ * Utility functions for managing environment variables in agent spawning
+ */
+
+/**
+ * Get environment variables to clear ANTHROPIC_* vars when in OAuth mode
+ * 
+ * When switching from API Profile mode to OAuth mode, residual ANTHROPIC_* 
+ * environment variables from process.env can cause authentication failures.
+ * This function returns an object with empty strings for these vars when
+ * no API profile is active, ensuring OAuth tokens are used correctly.
+ * 
+ * **Why empty strings?** Setting environment variables to empty strings (rather than
+ * undefined) ensures they override any stale values from process.env. Python's SDK
+ * treats empty strings as falsy in conditional checks like `if token:`, so empty
+ * strings effectively disable these authentication parameters without leaving
+ * undefined values that might be ignored during object spreading.
+ * 
+ * @param apiProfileEnv - Environment variables from getAPIProfileEnv()
+ * @returns Object with empty ANTHROPIC_* vars if in OAuth mode, empty object otherwise
+ */
+export function getOAuthModeClearVars(apiProfileEnv: Record<string, string>): Record<string, string> {
+  // If API profile is active (has ANTHROPIC_* vars), don't clear anything
+  if (apiProfileEnv && Object.keys(apiProfileEnv).some(key => key.startsWith('ANTHROPIC_'))) {
+    return {};
+  }
+
+  // In OAuth mode (no API profile), clear all ANTHROPIC_* vars
+  // Setting to empty string ensures they override any values from process.env
+  // Python's `if token:` checks treat empty strings as falsy
+  return {
+    ANTHROPIC_AUTH_TOKEN: '',
+    ANTHROPIC_BASE_URL: '',
+    ANTHROPIC_MODEL: '',
+    ANTHROPIC_DEFAULT_HAIKU_MODEL: '',
+    ANTHROPIC_DEFAULT_SONNET_MODEL: '',
+    ANTHROPIC_DEFAULT_OPUS_MODEL: ''
+  };
+}
@@ -13,6 +13,7 @@ import { extractChangelog } from './parser';
 import { getCommits, getBranchDiffCommits } from './git-integration';
 import { detectRateLimit, createSDKRateLimitInfo, getProfileEnv } from '../rate-limit-detector';
 import { parsePythonCommand } from '../python-detector';
+import { getAugmentedEnv } from '../env-utils';

 /**
 * Core changelog generation logic
@@ -246,21 +247,9 @@ export class ChangelogGenerator extends EventEmitter {
    const homeDir = os.homedir();
    const isWindows = process.platform === 'win32';

-    // Build PATH with platform-appropriate separator and locations
-    const pathAdditions = isWindows
-      ? [
-          path.join(homeDir, 'AppData', 'Local', 'Programs', 'claude'),
-          path.join(homeDir, 'AppData', 'Roaming', 'npm'),
-          path.join(homeDir, '.local', 'bin'),
-          'C:\\Program Files\\Claude',
-          'C:\\Program Files (x86)\\Claude'
-        ]
-      : [
-          '/usr/local/bin',
-          '/opt/homebrew/bin',
-          path.join(homeDir, '.local', 'bin'),
-          path.join(homeDir, 'bin')
-        ];
+    // Use getAugmentedEnv() to ensure common tool paths are available
+    // even when app is launched from Finder/Dock
+    const augmentedEnv = getAugmentedEnv();

    // Get active Claude profile environment (OAuth token preferred, falls back to CLAUDE_CONFIG_DIR)
    const profileEnv = getProfileEnv();
@@ -271,15 +260,13 @@ export class ChangelogGenerator extends EventEmitter {
    });

    const spawnEnv: Record<string, string> = {
-      ...process.env as Record<string, string>,
+      ...augmentedEnv,
      ...this.autoBuildEnv,
      ...profileEnv, // Include active Claude profile config
      // Ensure critical env vars are set for claude CLI
      // Use USERPROFILE on Windows, HOME on Unix
      ...(isWindows ? { USERPROFILE: homeDir } : { HOME: homeDir }),
      USER: process.env.USER || process.env.USERNAME || 'user',
-      // Add common binary locations to PATH for claude CLI
-      PATH: [process.env.PATH || '', ...pathAdditions].filter(Boolean).join(path.delimiter),
      PYTHONUNBUFFERED: '1',
      PYTHONIOENCODING: 'utf-8',
      PYTHONUTF8: '1'
@@ -4,6 +4,7 @@ import * as os from 'os';
 import type { GitCommit } from '../../shared/types';
 import { getProfileEnv } from '../rate-limit-detector';
 import { parsePythonCommand } from '../python-detector';
+import { getAugmentedEnv } from '../env-utils';

 interface VersionSuggestion {
  version: string;
@@ -215,31 +216,19 @@ except Exception as e:
    const homeDir = os.homedir();
    const isWindows = process.platform === 'win32';

-    // Build PATH with platform-appropriate separator and locations
-    const pathAdditions = isWindows
-      ? [
-          path.join(homeDir, 'AppData', 'Local', 'Programs', 'claude'),
-          path.join(homeDir, 'AppData', 'Roaming', 'npm'),
-          path.join(homeDir, '.local', 'bin'),
-          'C:\\Program Files\\Claude',
-          'C:\\Program Files (x86)\\Claude'
-        ]
-      : [
-          '/usr/local/bin',
-          '/opt/homebrew/bin',
-          path.join(homeDir, '.local', 'bin'),
-          path.join(homeDir, 'bin')
-        ];
+    // Use getAugmentedEnv() to ensure common tool paths are available
+    // even when app is launched from Finder/Dock
+    const augmentedEnv = getAugmentedEnv();

    // Get active Claude profile environment
    const profileEnv = getProfileEnv();

    const spawnEnv: Record<string, string> = {
-      ...process.env as Record<string, string>,
+      ...augmentedEnv,
      ...profileEnv,
+      // Ensure critical env vars are set for claude CLI
      ...(isWindows ? { USERPROFILE: homeDir } : { HOME: homeDir }),
      USER: process.env.USER || process.env.USERNAME || 'user',
-      PATH: [process.env.PATH || '', ...pathAdditions].filter(Boolean).join(path.delimiter),
      PYTHONUNBUFFERED: '1',
      PYTHONIOENCODING: 'utf-8',
      PYTHONUTF8: '1'
@@ -56,7 +56,7 @@ export async function createProfileDirectory(profileName: string): Promise<strin

 /**
 * Check if a profile has valid authentication
- * (checks if the config directory has credential files)
+ * (checks if the config directory has credential files or OAuth account info)
 */
 export function isProfileAuthenticated(profile: ClaudeProfile): boolean {
  const configDir = profile.configDir;
@@ -64,7 +64,24 @@ export function isProfileAuthenticated(profile: ClaudeProfile): boolean {
    return false;
  }

-  // Claude stores auth in .claude/credentials or similar files
+  // Check for .claude.json with OAuth account info (modern Claude Code CLI)
+  // This is how Claude Code CLI stores OAuth authentication since v1.0
+  const claudeJsonPath = join(configDir, '.claude.json');
+  if (existsSync(claudeJsonPath)) {
+    try {
+      const content = readFileSync(claudeJsonPath, 'utf-8');
+      const data = JSON.parse(content);
+      // Check for oauthAccount which indicates successful OAuth authentication
+      if (data && typeof data === 'object' && (data.oauthAccount?.accountUuid || data.oauthAccount?.emailAddress)) {
+        return true;
+      }
+    } catch (error) {
+      // Log parse errors for debugging, but fall through to legacy checks
+      console.warn(`[profile-utils] Failed to read or parse ${claudeJsonPath}:`, error);
+    }
+  }
+
+  // Legacy: Claude stores auth in .claude/credentials or similar files
  // Check for common auth indicators
  const possibleAuthFiles = [
    join(configDir, 'credentials'),
@@ -377,7 +377,24 @@ class CLIToolManager {
      }
    }

-    // 3. System PATH (augmented)
+    // 3. Windows Registry (most reliable for GUI apps on Windows)
+    if (process.platform === 'win32') {
+      const registryGit = this.findGitFromWindowsRegistry();
+      if (registryGit) {
+        const validation = this.validateGit(registryGit);
+        if (validation.valid) {
+          return {
+            found: true,
+            path: registryGit,
+            version: validation.version,
+            source: 'windows-registry',
+            message: `Using Git from registry: ${registryGit}`,
+          };
+        }
+      }
+    }
+
+    // 4. System PATH (augmented)
    const gitPath = findExecutable('git');
    if (gitPath) {
      const validation = this.validateGit(gitPath);
@@ -392,7 +409,7 @@ class CLIToolManager {
      }
    }

-    // 4. Not found - fallback to 'git'
+    // 5. Not found - fallback to 'git'
    return {
      found: false,
      source: 'fallback',
@@ -678,6 +695,64 @@ class CLIToolManager {
    }
  }

+  /**
+   * Find Git installation from Windows Registry
+   *
+   * Git for Windows registers its install path in the registry.
+   * This is more reliable than PATH for GUI apps.
+   *
+   * @returns Path to git.exe if found via registry, null otherwise
+   */
+  private findGitFromWindowsRegistry(): string | null {
+    if (process.platform !== 'win32') {
+      return null;
+    }
+
+    try {
+      // Use reg.exe to query the registry (works without native modules)
+      const registryPaths = [
+        'HKLM\\SOFTWARE\\GitForWindows',
+        'HKCU\\SOFTWARE\\GitForWindows',
+        'HKLM\\SOFTWARE\\WOW6432Node\\GitForWindows',
+      ];
+
+      for (const regPath of registryPaths) {
+        try {
+          const result = execFileSync('reg', ['query', regPath, '/v', 'InstallPath'], {
+            encoding: 'utf-8',
+            timeout: 5000,
+            windowsHide: true,
+          });
+
+          // Parse the registry output to get InstallPath
+          const match = result.match(/InstallPath\s+REG_SZ\s+(.+)/);
+          if (match && match[1]) {
+            const installPath = match[1].trim();
+            // Check for git.exe in cmd folder
+            const gitExe = path.join(installPath, 'cmd', 'git.exe');
+            if (existsSync(gitExe)) {
+              console.warn(`[Git] Found via registry: ${gitExe}`);
+              return gitExe;
+            }
+            // Fallback to bin folder
+            const gitExeBin = path.join(installPath, 'bin', 'git.exe');
+            if (existsSync(gitExeBin)) {
+              console.warn(`[Git] Found via registry: ${gitExeBin}`);
+              return gitExeBin;
+            }
+          }
+        } catch {
+          // Registry key not found, try next
+          continue;
+        }
+      }
+    } catch (error) {
+      console.warn('[Git] Registry lookup failed:', error);
+    }
+
+    return null;
+  }
+
  /**
   * Validate Git availability and version
   *
@@ -64,15 +64,18 @@ const COMMON_BIN_PATHS: Record<string, string[]> = {
  darwin: [
    '/opt/homebrew/bin',      // Apple Silicon Homebrew
    '/usr/local/bin',         // Intel Homebrew / system
+    '/usr/local/share/dotnet', // .NET SDK
    '/opt/homebrew/sbin',     // Apple Silicon Homebrew sbin
    '/usr/local/sbin',        // Intel Homebrew sbin
    '~/.local/bin',           // User-local binaries (Claude CLI)
+    '~/.dotnet/tools',        // .NET global tools
  ],
  linux: [
    '/usr/local/bin',
    '/usr/bin',               // System binaries (Python, etc.)
    '/snap/bin',              // Snap packages
    '~/.local/bin',           // User-local binaries
+    '~/.dotnet/tools',        // .NET global tools
    '/usr/sbin',              // System admin binaries
  ],
  win32: [
@@ -1,4 +1,4 @@
-import { app, BrowserWindow, shell, nativeImage } from 'electron';
+import { app, BrowserWindow, shell, nativeImage, session } from 'electron';
 import { join } from 'path';
 import { accessSync, readFileSync, writeFileSync } from 'fs';
 import { electronApp, optimizer, is } from '@electron-toolkit/utils';
@@ -110,11 +110,25 @@ if (process.platform === 'darwin') {
  app.name = 'Auto Claude';
 }

+// Fix Windows GPU cache permission errors (0x5 Access Denied)
+if (process.platform === 'win32') {
+  app.commandLine.appendSwitch('disable-gpu-shader-disk-cache');
+  app.commandLine.appendSwitch('disable-gpu-program-cache');
+  console.log('[main] Applied Windows GPU cache fixes');
+}
+
 // Initialize the application
 app.whenReady().then(() => {
  // Set app user model id for Windows
  electronApp.setAppUserModelId('com.autoclaude.ui');

+  // Clear cache on Windows to prevent permission errors from stale cache
+  if (process.platform === 'win32') {
+    session.defaultSession.clearCache()
+      .then(() => console.log('[main] Cleared cache on startup'))
+      .catch((err) => console.warn('[main] Failed to clear cache:', err));
+  }
+
  // Set dock icon on macOS
  if (process.platform === 'darwin') {
    const iconPath = getIconPath();
@@ -3,7 +3,9 @@ import { existsSync, readFileSync } from 'fs';
 import { app } from 'electron';
 import { getProfileEnv } from '../rate-limit-detector';
 import { getValidatedPythonPath } from '../python-detector';
-import { getConfiguredPythonPath } from '../python-env-manager';
+import { getConfiguredPythonPath, pythonEnvManager } from '../python-env-manager';
+import { getAugmentedEnv } from '../env-utils';
+import { getEffectiveSourcePath } from '../updater/path-resolver';

 /**
 * Configuration manager for insights service
@@ -40,24 +42,23 @@ export class InsightsConfig {

  /**
   * Get the auto-claude source path (detects automatically if not configured)
+   * Uses getEffectiveSourcePath() which handles userData override for user-updated backend
   */
  getAutoBuildSourcePath(): string | null {
    if (this.autoBuildSourcePath && existsSync(this.autoBuildSourcePath)) {
      return this.autoBuildSourcePath;
    }

-    const possiblePaths = [
-      // Apps structure: from out/main -> apps/backend
-      path.resolve(__dirname, '..', '..', '..', 'backend'),
-      path.resolve(app.getAppPath(), '..', 'backend'),
-      path.resolve(process.cwd(), 'apps', 'backend')
-    ];
-
-    for (const p of possiblePaths) {
-      if (existsSync(p) && existsSync(path.join(p, 'runners', 'spec_runner.py'))) {
-        return p;
-      }
+    // Use shared path resolver which handles:
+    // 1. User settings (autoBuildPath)
+    // 2. userData override (backend-source) for user-updated backend
+    // 3. Bundled backend (process.resourcesPath/backend)
+    // 4. Development paths
+    const effectivePath = getEffectiveSourcePath();
+    if (existsSync(effectivePath) && existsSync(path.join(effectivePath, 'runners', 'spec_runner.py'))) {
+      return effectivePath;
    }
+
    return null;
  }

@@ -107,9 +108,15 @@ export class InsightsConfig {
  getProcessEnv(): Record<string, string> {
    const autoBuildEnv = this.loadAutoBuildEnv();
    const profileEnv = getProfileEnv();
+    // Get Python environment (PYTHONPATH for bundled packages like python-dotenv)
+    const pythonEnv = pythonEnvManager.getPythonEnv();
+    // Use getAugmentedEnv() to ensure common tool paths (claude, dotnet, etc.)
+    // are available even when app is launched from Finder/Dock
+    const augmentedEnv = getAugmentedEnv();

    return {
-      ...process.env as Record<string, string>,
+      ...augmentedEnv,
+      ...pythonEnv, // Include PYTHONPATH for bundled site-packages
      ...autoBuildEnv,
      ...profileEnv,
      PYTHONUNBUFFERED: '1',
@@ -130,6 +130,7 @@ export class InsightsExecutor extends EventEmitter {
      let suggestedTask: InsightsChatMessage['suggestedTask'] | undefined;
      const toolsUsed: InsightsToolUsage[] = [];
      let allInsightsOutput = '';
+      let stderrOutput = '';

      proc.stdout?.on('data', (data: Buffer) => {
        const text = data.toString();
@@ -159,8 +160,9 @@ export class InsightsExecutor extends EventEmitter {

      proc.stderr?.on('data', (data: Buffer) => {
        const text = data.toString();
-        // Collect stderr for rate limit detection too
+        // Collect stderr for rate limit detection and error reporting
        allInsightsOutput = (allInsightsOutput + text).slice(-10000);
+        stderrOutput = (stderrOutput + text).slice(-2000);
        console.error('[Insights]', text);
      });

@@ -196,7 +198,11 @@ export class InsightsExecutor extends EventEmitter {
            toolsUsed
          });
        } else {
-          const error = `Process exited with code ${code}`;
+          // Include stderr output in error message for debugging
+          const stderrSummary = stderrOutput.trim()
+            ? `\n\nError output:\n${stderrOutput.slice(-500)}`
+            : '';
+          const error = `Process exited with code ${code}${stderrSummary}`;
          this.emit('stream-chunk', projectId, {
            type: 'error',
            error
@@ -10,11 +10,15 @@ const mockSpawn = vi.fn();
 const mockExecSync = vi.fn();
 const mockExecFileSync = vi.fn();

-vi.mock('child_process', () => ({
-  spawn: (...args: unknown[]) => mockSpawn(...args),
-  execSync: (...args: unknown[]) => mockExecSync(...args),
-  execFileSync: (...args: unknown[]) => mockExecFileSync(...args)
-}));
+vi.mock('child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('child_process')>();
+  return {
+    ...actual,
+    spawn: (...args: unknown[]) => mockSpawn(...args),
+    execSync: (...args: unknown[]) => mockExecSync(...args),
+    execFileSync: (...args: unknown[]) => mockExecFileSync(...args)
+  };
+});

 // Mock shell.openExternal
 const mockOpenExternal = vi.fn();
@@ -82,6 +86,13 @@ vi.mock('../../../env-utils', () => ({
  isCommandAvailable: vi.fn((cmd: string) => mockFindExecutable(cmd) !== null)
 }));

+// Mock cli-tool-manager to avoid child_process import issues
+vi.mock('../../../cli-tool-manager', () => ({
+  getToolPath: vi.fn(() => '/usr/local/bin/gh'),
+  detectCLITools: vi.fn(),
+  getAllToolStatus: vi.fn()
+}));
+
 // Create mock process for spawn
 function createMockProcess(): EventEmitter & {
  stdout: EventEmitter | null;
@@ -101,6 +101,7 @@ export interface PRReviewResult {
  error?: string;
  // Follow-up review fields
  reviewedCommitSha?: string;
+  reviewedFileBlobs?: Record<string, string>; // filename → blob SHA for rebase-resistant follow-ups
  isFollowupReview?: boolean;
  previousReviewId?: number;
  resolvedFindings?: string[];
@@ -542,6 +543,7 @@ function getReviewResult(project: Project, prNumber: number): PRReviewResult | n
      error: data.error,
      // Follow-up review fields (snake_case -> camelCase)
      reviewedCommitSha: data.reviewed_commit_sha,
+      reviewedFileBlobs: data.reviewed_file_blobs,
      isFollowupReview: data.is_followup_review ?? false,
      previousReviewId: data.previous_review_id,
      resolvedFindings: data.resolved_findings ?? [],
@@ -4,11 +4,15 @@ import { runPythonSubprocess } from './subprocess-runner';
 import * as childProcess from 'child_process';
 import EventEmitter from 'events';

-// Mock child_process.spawn
-vi.mock('child_process', () => ({
-  spawn: vi.fn(),
-  exec: vi.fn(),
-}));
+// Mock child_process with importOriginal to preserve all exports
+vi.mock('child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('child_process')>();
+  return {
+    ...actual,
+    spawn: vi.fn(),
+    exec: vi.fn(),
+  };
+});

 // Mock parsePythonCommand
 vi.mock('../../../python-detector', () => ({
@@ -32,6 +32,8 @@ import { registerAppUpdateHandlers } from './app-update-handlers';
 import { registerDebugHandlers } from './debug-handlers';
 import { registerClaudeCodeHandlers } from './claude-code-handlers';
 import { registerMcpHandlers } from './mcp-handlers';
+import { registerProfileHandlers } from './profile-handlers';
+import { registerTerminalWorktreeIpcHandlers } from './terminal';
 import { notificationService } from '../notification-service';

 /**
@@ -60,6 +62,9 @@ export function setupIpcHandlers(
  // Terminal and Claude profile handlers
  registerTerminalHandlers(terminalManager, getMainWindow);

+  // Terminal worktree handlers (isolated development in worktrees)
+  registerTerminalWorktreeIpcHandlers();
+
  // Agent event handlers (event forwarding from agent manager to renderer)
  registerAgenteventsHandlers(agentManager, getMainWindow);

@@ -114,6 +119,9 @@ export function setupIpcHandlers(
  // MCP server health check handlers
  registerMcpHandlers();

+  // API Profile handlers (custom Anthropic-compatible endpoints)
+  registerProfileHandlers();
+
  console.warn('[IPC] All handler modules registered successfully');
 }

@@ -122,6 +130,7 @@ export {
  registerProjectHandlers,
  registerTaskHandlers,
  registerTerminalHandlers,
+  registerTerminalWorktreeIpcHandlers,
  registerAgenteventsHandlers,
  registerSettingsHandlers,
  registerFileHandlers,
@@ -139,5 +148,6 @@ export {
  registerAppUpdateHandlers,
  registerDebugHandlers,
  registerClaudeCodeHandlers,
-  registerMcpHandlers
+  registerMcpHandlers,
+  registerProfileHandlers
 };
@@ -28,6 +28,12 @@ const DANGEROUS_FLAGS = new Set([
  '--require', '-r'
 ]);

+/**
+ * Defense-in-depth: Shell metacharacters that could enable command injection
+ * when shell: true is used on Windows
+ */
+const SHELL_METACHARACTERS = ['&', '|', '>', '<', '^', '%', ';', '$', '`', '\n', '\r'];
+
 /**
 * Validate that a command is in the safe allowlist
 */
@@ -39,11 +45,22 @@ function isCommandSafe(command: string | undefined): boolean {
 }

 /**
- * Validate that args don't contain dangerous interpreter flags
+ * Validate that args don't contain dangerous interpreter flags or shell metacharacters
 */
 function areArgsSafe(args: string[] | undefined): boolean {
  if (!args || args.length === 0) return true;
-  return !args.some(arg => DANGEROUS_FLAGS.has(arg));
+
+  // Check for dangerous interpreter flags
+  if (args.some(arg => DANGEROUS_FLAGS.has(arg))) return false;
+
+  // On Windows with shell: true, check for shell metacharacters that could enable injection
+  if (process.platform === 'win32') {
+    if (args.some(arg => SHELL_METACHARACTERS.some(char => arg.includes(char)))) {
+      return false;
+    }
+  }
+
+  return true;
 }

 /**
@@ -171,7 +188,7 @@ async function checkCommandHealth(server: CustomMcpServer, startTime: number): P
      return resolve({
        serverId: server.id,
        status: 'unhealthy',
-        message: 'Args contain dangerous interpreter flags',
+        message: 'Args contain dangerous flags or shell metacharacters',
        checkedAt: new Date().toISOString(),
      });
    }
@@ -394,14 +411,17 @@ async function testCommandConnection(server: CustomMcpServer, startTime: number)
      return resolve({
        serverId: server.id,
        success: false,
-        message: 'Args contain dangerous interpreter flags',
+        message: 'Args contain dangerous flags or shell metacharacters',
      });
    }

    const args = server.args || [];
+
+    // On Windows, use shell: true to properly handle .cmd/.bat scripts like npx
    const proc = spawn(server.command!, args, {
      stdio: ['pipe', 'pipe', 'pipe'],
      timeout: 15000, // OS-level timeout for reliable process termination
+      shell: process.platform === 'win32', // Required for Windows to run npx.cmd
    });

    let stdout = '';
@@ -25,7 +25,7 @@ import {
 } from '../memory-service';
 import { validateOpenAIApiKey } from '../api-validation-service';
 import { parsePythonCommand } from '../python-detector';
-import { getConfiguredPythonPath } from '../python-env-manager';
+import { getConfiguredPythonPath, pythonEnvManager } from '../python-env-manager';
 import { openTerminalWithCommand } from './claude-code-handlers';

 /**
@@ -296,6 +296,9 @@ async function executeOllamaDetector(
    let resolved = false;
    const proc = spawn(pythonExe, args, {
      stdio: ['ignore', 'pipe', 'pipe'],
+      // Use sanitized Python environment to prevent PYTHONHOME contamination
+      // Fixes "Could not find platform independent libraries" error on Windows
+      env: pythonEnvManager.getPythonEnv(),
    });

    let stdout = '';
@@ -769,6 +772,9 @@ export function registerMemoryHandlers(): void {
          const proc = spawn(pythonExe, args, {
            stdio: ['ignore', 'pipe', 'pipe'],
            timeout: 600000, // 10 minute timeout for large models
+            // Use sanitized Python environment to prevent PYTHONHOME contamination
+            // Fixes "Could not find platform independent libraries" error on Windows
+            env: pythonEnvManager.getPythonEnv(),
          });

          let stdout = '';
@@ -0,0 +1,341 @@
+/**
+ * Tests for profile IPC handlers
+ *
+ * Tests profiles:set-active handler with support for:
+ * - Setting valid profile as active
+ * - Switching to OAuth (null profileId)
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { APIProfile, ProfilesFile } from '@shared/types/profile';
+
+// Hoist mocked functions to avoid circular dependency in atomicModifyProfiles
+const { mockedLoadProfilesFile, mockedSaveProfilesFile } = vi.hoisted(() => ({
+  mockedLoadProfilesFile: vi.fn(),
+  mockedSaveProfilesFile: vi.fn()
+}));
+
+// Mock electron before importing
+vi.mock('electron', () => ({
+  ipcMain: {
+    handle: vi.fn(),
+    on: vi.fn()
+  }
+}));
+
+// Mock profile service
+vi.mock('../services/profile', () => ({
+  loadProfilesFile: mockedLoadProfilesFile,
+  saveProfilesFile: mockedSaveProfilesFile,
+  validateFilePermissions: vi.fn(),
+  getProfilesFilePath: vi.fn(() => '/test/profiles.json'),
+  createProfile: vi.fn(),
+  updateProfile: vi.fn(),
+  deleteProfile: vi.fn(),
+  testConnection: vi.fn(),
+  discoverModels: vi.fn(),
+  atomicModifyProfiles: vi.fn(async (modifier: (file: unknown) => unknown) => {
+    const file = await mockedLoadProfilesFile();
+    const modified = modifier(file);
+    await mockedSaveProfilesFile(modified as never);
+    return modified;
+  })
+}));
+
+import { registerProfileHandlers } from './profile-handlers';
+import { ipcMain } from 'electron';
+import { IPC_CHANNELS } from '../../shared/constants';
+import {
+  loadProfilesFile,
+  saveProfilesFile,
+  validateFilePermissions,
+  testConnection
+} from '../services/profile';
+import type { TestConnectionResult } from '@shared/types/profile';
+
+// Get the handler function for testing
+function getSetActiveHandler() {
+  const calls = (ipcMain.handle as unknown as ReturnType<typeof vi.fn>).mock.calls;
+  const setActiveCall = calls.find(
+    (call) => call[0] === IPC_CHANNELS.PROFILES_SET_ACTIVE
+  );
+  return setActiveCall?.[1];
+}
+
+// Get the testConnection handler function for testing
+function getTestConnectionHandler() {
+  const calls = (ipcMain.handle as unknown as ReturnType<typeof vi.fn>).mock.calls;
+  const testConnectionCall = calls.find(
+    (call) => call[0] === IPC_CHANNELS.PROFILES_TEST_CONNECTION
+  );
+  return testConnectionCall?.[1];
+}
+
+describe('profile-handlers - setActiveProfile', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    registerProfileHandlers();
+  });
+  const mockProfiles: APIProfile[] = [
+    {
+      id: 'profile-1',
+      name: 'Test Profile 1',
+      baseUrl: 'https://api.anthropic.com',
+      apiKey: 'sk-ant-test-key-1',
+      createdAt: Date.now(),
+      updatedAt: Date.now()
+    },
+    {
+      id: 'profile-2',
+      name: 'Test Profile 2',
+      baseUrl: 'https://custom.api.com',
+      apiKey: 'sk-custom-key-2',
+      createdAt: Date.now(),
+      updatedAt: Date.now()
+    }
+  ];
+
+  describe('setting valid profile as active', () => {
+    it('should set active profile with valid profileId', async () => {
+      const mockFile: ProfilesFile = {
+        profiles: mockProfiles,
+        activeProfileId: null,
+        version: 1
+      };
+
+      vi.mocked(loadProfilesFile).mockResolvedValue(mockFile);
+      vi.mocked(saveProfilesFile).mockResolvedValue(undefined);
+      vi.mocked(validateFilePermissions).mockResolvedValue(true);
+
+      const handler = getSetActiveHandler();
+      const result = await handler({}, 'profile-1');
+
+      expect(result).toEqual({ success: true });
+      expect(saveProfilesFile).toHaveBeenCalledWith(
+        expect.objectContaining({
+          activeProfileId: 'profile-1'
+        })
+      );
+    });
+
+    it('should return error for non-existent profile', async () => {
+      const mockFile: ProfilesFile = {
+        profiles: mockProfiles,
+        activeProfileId: null,
+        version: 1
+      };
+
+      vi.mocked(loadProfilesFile).mockResolvedValue(mockFile);
+
+      const handler = getSetActiveHandler();
+      const result = await handler({}, 'non-existent-id');
+
+      expect(result).toEqual({
+        success: false,
+        error: 'Profile not found'
+      });
+    });
+  });
+
+  describe('switching to OAuth (null profileId)', () => {
+    it('should accept null profileId to switch to OAuth', async () => {
+      const mockFile: ProfilesFile = {
+        profiles: mockProfiles,
+        activeProfileId: 'profile-1',
+        version: 1
+      };
+
+      vi.mocked(loadProfilesFile).mockResolvedValue(mockFile);
+      vi.mocked(saveProfilesFile).mockResolvedValue(undefined);
+      vi.mocked(validateFilePermissions).mockResolvedValue(true);
+
+      const handler = getSetActiveHandler();
+      const result = await handler({}, null);
+
+      // Should succeed and clear activeProfileId
+      expect(result).toEqual({ success: true });
+      expect(saveProfilesFile).toHaveBeenCalledWith(
+        expect.objectContaining({
+          activeProfileId: null
+        })
+      );
+    });
+
+    it('should handle null when no profile was active', async () => {
+      const mockFile: ProfilesFile = {
+        profiles: mockProfiles,
+        activeProfileId: null,
+        version: 1
+      };
+
+      vi.mocked(loadProfilesFile).mockResolvedValue(mockFile);
+      vi.mocked(saveProfilesFile).mockResolvedValue(undefined);
+      vi.mocked(validateFilePermissions).mockResolvedValue(true);
+
+      const handler = getSetActiveHandler();
+      const result = await handler({}, null);
+
+      // Should succeed (idempotent operation)
+      expect(result).toEqual({ success: true });
+      expect(saveProfilesFile).toHaveBeenCalled();
+    });
+  });
+
+  describe('error handling', () => {
+    it('should handle loadProfilesFile errors', async () => {
+      vi.mocked(loadProfilesFile).mockRejectedValue(
+        new Error('Failed to load profiles')
+      );
+
+      const handler = getSetActiveHandler();
+      const result = await handler({}, 'profile-1');
+
+      expect(result).toEqual({
+        success: false,
+        error: 'Failed to load profiles'
+      });
+    });
+
+    it('should handle saveProfilesFile errors', async () => {
+      const mockFile: ProfilesFile = {
+        profiles: mockProfiles,
+        activeProfileId: null,
+        version: 1
+      };
+
+      vi.mocked(loadProfilesFile).mockResolvedValue(mockFile);
+      vi.mocked(saveProfilesFile).mockRejectedValue(
+        new Error('Failed to save')
+      );
+
+      const handler = getSetActiveHandler();
+      const result = await handler({}, 'profile-1');
+
+      expect(result).toEqual({
+        success: false,
+        error: 'Failed to save'
+      });
+    });
+  });
+});
+
+describe('profile-handlers - testConnection', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    registerProfileHandlers();
+  });
+
+  describe('successful connection tests', () => {
+    it('should return success result for valid connection', async () => {
+      const mockResult: TestConnectionResult = {
+        success: true,
+        message: 'Connection successful'
+      };
+
+      vi.mocked(testConnection).mockResolvedValue(mockResult);
+
+      const handler = getTestConnectionHandler();
+      const result = await handler({}, 'https://api.anthropic.com', 'sk-test-key-12chars');
+
+      expect(result).toEqual({
+        success: true,
+        data: mockResult
+      });
+      expect(testConnection).toHaveBeenCalledWith(
+        'https://api.anthropic.com',
+        'sk-test-key-12chars',
+        expect.any(AbortSignal)
+      );
+    });
+  });
+
+  describe('input validation', () => {
+    it('should return error for empty baseUrl', async () => {
+      const handler = getTestConnectionHandler();
+      const result = await handler({}, '', 'sk-test-key-12chars');
+
+      expect(result).toEqual({
+        success: false,
+        error: 'Base URL is required'
+      });
+      expect(testConnection).not.toHaveBeenCalled();
+    });
+
+    it('should return error for whitespace-only baseUrl', async () => {
+      const handler = getTestConnectionHandler();
+      const result = await handler({}, '   ', 'sk-test-key-12chars');
+
+      expect(result).toEqual({
+        success: false,
+        error: 'Base URL is required'
+      });
+      expect(testConnection).not.toHaveBeenCalled();
+    });
+
+    it('should return error for empty apiKey', async () => {
+      const handler = getTestConnectionHandler();
+      const result = await handler({}, 'https://api.anthropic.com', '');
+
+      expect(result).toEqual({
+        success: false,
+        error: 'API key is required'
+      });
+      expect(testConnection).not.toHaveBeenCalled();
+    });
+
+    it('should return error for whitespace-only apiKey', async () => {
+      const handler = getTestConnectionHandler();
+      const result = await handler({}, 'https://api.anthropic.com', '   ');
+
+      expect(result).toEqual({
+        success: false,
+        error: 'API key is required'
+      });
+      expect(testConnection).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('error handling', () => {
+    it('should return IPCResult with TestConnectionResult data for service errors', async () => {
+      const mockResult: TestConnectionResult = {
+        success: false,
+        errorType: 'auth',
+        message: 'Authentication failed. Please check your API key.'
+      };
+
+      vi.mocked(testConnection).mockResolvedValue(mockResult);
+
+      const handler = getTestConnectionHandler();
+      const result = await handler({}, 'https://api.anthropic.com', 'invalid-key');
+
+      expect(result).toEqual({
+        success: true,
+        data: mockResult
+      });
+    });
+
+    it('should return error for unexpected exceptions', async () => {
+      vi.mocked(testConnection).mockRejectedValue(new Error('Unexpected error'));
+
+      const handler = getTestConnectionHandler();
+      const result = await handler({}, 'https://api.anthropic.com', 'sk-test-key-12chars');
+
+      expect(result).toEqual({
+        success: false,
+        error: 'Unexpected error'
+      });
+    });
+
+    it('should return error for non-Error exceptions', async () => {
+      vi.mocked(testConnection).mockRejectedValue('String error');
+
+      const handler = getTestConnectionHandler();
+      const result = await handler({}, 'https://api.anthropic.com', 'sk-test-key-12chars');
+
+      expect(result).toEqual({
+        success: false,
+        error: 'Failed to test connection'
+      });
+    });
+  });
+});
@@ -0,0 +1,358 @@
+/**
+ * Profile IPC Handlers
+ *
+ * IPC handlers for API profile management:
+ * - profiles:get - Get all profiles
+ * - profiles:save - Save/create a profile
+ * - profiles:update - Update an existing profile
+ * - profiles:delete - Delete a profile
+ * - profiles:setActive - Set active profile
+ * - profiles:test-connection - Test API profile connection
+ */
+
+import { ipcMain } from 'electron';
+import { IPC_CHANNELS } from '../../shared/constants';
+import type { IPCResult } from '../../shared/types';
+import type { APIProfile, ProfileFormData, ProfilesFile, TestConnectionResult, DiscoverModelsResult } from '@shared/types/profile';
+import {
+  loadProfilesFile,
+  saveProfilesFile,
+  validateFilePermissions,
+  getProfilesFilePath,
+  atomicModifyProfiles,
+  createProfile,
+  updateProfile,
+  deleteProfile,
+  testConnection,
+  discoverModels
+} from '../services/profile';
+
+// Track active test connection requests for cancellation
+const activeTestConnections = new Map<number, AbortController>();
+
+// Track active discover models requests for cancellation
+const activeDiscoverModelsRequests = new Map<number, AbortController>();
+
+/**
+ * Register all profile-related IPC handlers
+ */
+export function registerProfileHandlers(): void {
+  /**
+   * Get all profiles
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.PROFILES_GET,
+    async (): Promise<IPCResult<ProfilesFile>> => {
+      try {
+        const profiles = await loadProfilesFile();
+        return { success: true, data: profiles };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Failed to load profiles'
+        };
+      }
+    }
+  );
+
+  /**
+   * Save/create a profile
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.PROFILES_SAVE,
+    async (
+      _,
+      profileData: ProfileFormData
+    ): Promise<IPCResult<APIProfile>> => {
+      try {
+        // Use createProfile from service layer (handles validation)
+        const newProfile = await createProfile(profileData);
+
+        // Set file permissions to user-readable only
+        await validateFilePermissions(getProfilesFilePath()).catch((err) => {
+          console.warn('[profile-handlers] Failed to set secure file permissions:', err);
+        });
+
+        return { success: true, data: newProfile };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Failed to save profile'
+        };
+      }
+    }
+  );
+
+  /**
+   * Update an existing profile
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.PROFILES_UPDATE,
+    async (_, profileData: APIProfile): Promise<IPCResult<APIProfile>> => {
+      try {
+        // Use updateProfile from service layer (handles validation)
+        const updatedProfile = await updateProfile({
+          id: profileData.id,
+          name: profileData.name,
+          baseUrl: profileData.baseUrl,
+          apiKey: profileData.apiKey,
+          models: profileData.models
+        });
+
+        // Set file permissions to user-readable only
+        await validateFilePermissions(getProfilesFilePath()).catch((err) => {
+          console.warn('[profile-handlers] Failed to set secure file permissions:', err);
+        });
+
+        return { success: true, data: updatedProfile };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Failed to update profile'
+        };
+      }
+    }
+  );
+
+  /**
+   * Delete a profile
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.PROFILES_DELETE,
+    async (_, profileId: string): Promise<IPCResult> => {
+      try {
+        // Use deleteProfile from service layer (handles validation)
+        await deleteProfile(profileId);
+
+        return { success: true };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Failed to delete profile'
+        };
+      }
+    }
+  );
+
+  /**
+   * Set active profile
+   * - If profileId is provided, set that profile as active
+   * - If profileId is null, clear active profile (switch to OAuth)
+   * Uses atomic operation to prevent race conditions
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.PROFILES_SET_ACTIVE,
+    async (_, profileId: string | null): Promise<IPCResult> => {
+      try {
+        await atomicModifyProfiles((file) => {
+          // If switching to OAuth (null), clear active profile
+          if (profileId === null) {
+            file.activeProfileId = null;
+            return file;
+          }
+
+          // Check if profile exists
+          const profileExists = file.profiles.some((p) => p.id === profileId);
+          if (!profileExists) {
+            throw new Error('Profile not found');
+          }
+
+          // Set active profile
+          file.activeProfileId = profileId;
+          return file;
+        });
+
+        return { success: true };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Failed to set active profile'
+        };
+      }
+    }
+  );
+
+  /**
+   * Test API profile connection
+   * - Tests credentials by making a minimal API request
+   * - Returns detailed error information for different failure types
+   * - Includes configurable timeout (defaults to 15 seconds)
+   * - Supports cancellation via PROFILES_TEST_CONNECTION_CANCEL
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.PROFILES_TEST_CONNECTION,
+    async (_event, baseUrl: string, apiKey: string, requestId: number): Promise<IPCResult<TestConnectionResult>> => {
+      // Create AbortController for timeout and cancellation
+      const controller = new AbortController();
+      const timeoutMs = 15000; // 15 seconds
+
+      // Track this request for cancellation
+      activeTestConnections.set(requestId, controller);
+
+      // Set timeout to abort the request
+      const timeoutId = setTimeout(() => {
+        controller.abort();
+      }, timeoutMs);
+
+      try {
+        // Validate inputs (null/empty checks)
+        if (!baseUrl || baseUrl.trim() === '') {
+          clearTimeout(timeoutId);
+          activeTestConnections.delete(requestId);
+          return {
+            success: false,
+            error: 'Base URL is required'
+          };
+        }
+
+        if (!apiKey || apiKey.trim() === '') {
+          clearTimeout(timeoutId);
+          activeTestConnections.delete(requestId);
+          return {
+            success: false,
+            error: 'API key is required'
+          };
+        }
+
+        // Call testConnection from service layer with abort signal
+        const result = await testConnection(baseUrl, apiKey, controller.signal);
+
+        // Clear timeout on success
+        clearTimeout(timeoutId);
+        activeTestConnections.delete(requestId);
+
+        return { success: true, data: result };
+      } catch (error) {
+        // Clear timeout on error
+        clearTimeout(timeoutId);
+        activeTestConnections.delete(requestId);
+
+        // Handle abort errors (timeout or explicit cancellation)
+        if (error instanceof Error && error.name === 'AbortError') {
+          return {
+            success: false,
+            error: 'Connection timeout. The request took too long to complete.'
+          };
+        }
+
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Failed to test connection'
+        };
+      }
+    }
+  );
+
+  /**
+   * Cancel an active test connection request
+   */
+  ipcMain.on(
+    IPC_CHANNELS.PROFILES_TEST_CONNECTION_CANCEL,
+    (_event, requestId: number) => {
+      const controller = activeTestConnections.get(requestId);
+      if (controller) {
+        controller.abort();
+        activeTestConnections.delete(requestId);
+      }
+    }
+  );
+
+  /**
+   * Discover available models from API endpoint
+   * - Fetches list of models from /v1/models endpoint
+   * - Returns model IDs and display names for dropdown selection
+   * - Supports cancellation via PROFILES_DISCOVER_MODELS_CANCEL
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.PROFILES_DISCOVER_MODELS,
+    async (_event, baseUrl: string, apiKey: string, requestId: number): Promise<IPCResult<DiscoverModelsResult>> => {
+      console.log('[discoverModels] Called with:', { baseUrl, requestId });
+
+      // Create AbortController for timeout and cancellation
+      const controller = new AbortController();
+      const timeoutMs = 15000; // 15 seconds
+
+      // Track this request for cancellation
+      activeDiscoverModelsRequests.set(requestId, controller);
+
+      // Set timeout to abort the request
+      const timeoutId = setTimeout(() => {
+        controller.abort();
+      }, timeoutMs);
+
+      try {
+        // Validate inputs (null/empty checks)
+        if (!baseUrl || baseUrl.trim() === '') {
+          clearTimeout(timeoutId);
+          activeDiscoverModelsRequests.delete(requestId);
+          return {
+            success: false,
+            error: 'Base URL is required'
+          };
+        }
+
+        if (!apiKey || apiKey.trim() === '') {
+          clearTimeout(timeoutId);
+          activeDiscoverModelsRequests.delete(requestId);
+          return {
+            success: false,
+            error: 'API key is required'
+          };
+        }
+
+        // Call discoverModels from service layer with abort signal
+        const result = await discoverModels(baseUrl, apiKey, controller.signal);
+
+        // Clear timeout on success
+        clearTimeout(timeoutId);
+        activeDiscoverModelsRequests.delete(requestId);
+
+        return { success: true, data: result };
+      } catch (error) {
+        // Clear timeout on error
+        clearTimeout(timeoutId);
+        activeDiscoverModelsRequests.delete(requestId);
+
+        // Handle abort errors (timeout or explicit cancellation)
+        if (error instanceof Error && error.name === 'AbortError') {
+          return {
+            success: false,
+            error: 'Connection timeout. The request took too long to complete.'
+          };
+        }
+
+        // Extract error type if available
+        const errorType = (error as any).errorType;
+        const errorMessage = error instanceof Error ? error.message : 'Failed to discover models';
+
+        // Log for debugging
+        console.error('[discoverModels] Error:', {
+          name: error instanceof Error ? error.name : 'unknown',
+          message: errorMessage,
+          errorType,
+          originalError: error
+        });
+
+        // Include error type in error message for UI to handle appropriately
+        return {
+          success: false,
+          error: errorMessage
+        };
+      }
+    }
+  );
+
+  /**
+   * Cancel an active discover models request
+   */
+  ipcMain.on(
+    IPC_CHANNELS.PROFILES_DISCOVER_MODELS_CANCEL,
+    (_event, requestId: number) => {
+      const controller = activeDiscoverModelsRequests.get(requestId);
+      if (controller) {
+        controller.abort();
+        activeDiscoverModelsRequests.delete(requestId);
+      }
+    }
+  );
+}
--- a/Show More
+++ b/Show More