fix: enhance execution phase handling in ProjectStore

- Added logic to correct stale execution phases when a task reaches a terminal status (human_review, done, pr_created) but the persisted executionPhase is outdated. - Improved the determination of execution progress to ensure accurate representation of task status, particularly for tasks that have transitioned from running to completed states. These changes improve the reliability of task status updates and enhance user experience by ensuring accurate visual feedback on task execution phases.
adjust for claude mem
2026-02-05 22:18:43 +01:00 · 2026-02-05 22:18:25 +01:00 · 2026-02-05 20:34:56 +01:00 · 2026-02-05 20:10:54 +01:00 · 2026-02-05 19:47:34 +01:00 · 2026-02-05 15:10:39 +01:00
673 changed files with 74859 additions and 15067 deletions
@@ -33,6 +33,21 @@ Follow conventional commits: `<type>: <subject>`

 **Example:** `feat: add user authentication system`

+## AI Disclosure
+
+<!-- Check the box below if any part of this PR was written with AI assistance. -->
+
+- [ ] This PR includes AI-generated code (Claude, Codex, Copilot, etc.)
+
+<!-- If checked, please also fill in: -->
+**Tool(s) used:** <!-- e.g., Claude Code, GitHub Copilot, ChatGPT -->
+**Testing level:**
+- [ ] Untested -- AI output not yet verified
+- [ ] Lightly tested -- ran the app / spot-checked key paths
+- [ ] Fully tested -- all tests pass, manually verified behavior
+
+- [ ] I understand what this PR does and how the underlying code works
+
 ## Checklist

 - [ ] I've synced with `develop` branch
@@ -80,11 +80,12 @@ runs:
          echo "Installed yq version:"
          yq --version

-          # Merge the files arrays from both manifests using eval-all
-          # This avoids shell expansion issues with multiline YAML
-          yq eval-all '
-            select(fileIndex == 0) * {"files": ([.[].files] | add)}
-          ' "$intel_manifest" "$arm64_manifest" > "${{ inputs.output-path }}/latest-mac.yml"
+          # Merge the files arrays from both manifests using two-step approach
+          # Step 1: Collect all files from both manifests into a temp file
+          yq eval-all '[.files] | flatten' "$intel_manifest" "$arm64_manifest" > /tmp/merged-files.yml
+
+          # Step 2: Replace files array in first manifest with merged files
+          yq eval '.files = load("/tmp/merged-files.yml")' "$intel_manifest" > "${{ inputs.output-path }}/latest-mac.yml"

          echo "Merged manifest contents:"
          cat "${{ inputs.output-path }}/latest-mac.yml"
@@ -34,15 +34,93 @@ runs:
      uses: actions/cache@v4
      with:
        path: ${{ steps.npm-cache-dir.outputs.dir }}
-        key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json', 'apps/frontend/package-lock.json') }}
+        key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
        restore-keys: ${{ runner.os }}-npm-

    - name: Install dependencies
-      working-directory: apps/frontend
      shell: bash
+      # Run npm ci from root to properly handle workspace dependencies.
+      # With npm workspaces, the lock file is at root and dependencies are hoisted there.
+      # Running npm ci in apps/frontend would fail to populate node_modules correctly.
      run: |
        if [ "${{ inputs.ignore-scripts }}" == "true" ]; then
          npm ci --ignore-scripts
        else
          npm ci
        fi
+
+    - name: Link node_modules for electron-builder
+      shell: bash
+      # electron-builder expects node_modules in apps/frontend for native module rebuilding.
+      # With npm workspaces, packages are hoisted to root. Create a link so electron-builder
+      # can find the modules during packaging and code signing.
+      # Uses symlink on Unix, directory junction on Windows (works without admin privileges).
+      #
+      # IMPORTANT: npm workspaces may create a partial node_modules in apps/frontend for
+      # packages that couldn't be hoisted. We must remove it and create a proper link to root.
+      run: |
+        # Verify npm ci succeeded
+        if [ ! -d "node_modules" ]; then
+          echo "::error::Root node_modules does not exist. npm ci may have failed."
+          exit 1
+        fi
+
+        # Remove any existing node_modules in apps/frontend
+        # This handles: partial directories from npm workspaces, AND broken symlinks
+        if [ -e "apps/frontend/node_modules" ] || [ -L "apps/frontend/node_modules" ]; then
+          # Check if it's a valid symlink pointing to root node_modules
+          if [ -L "apps/frontend/node_modules" ]; then
+            target=$(readlink apps/frontend/node_modules 2>/dev/null || echo "")
+            if [ "$target" = "../../node_modules" ] && [ -d "apps/frontend/node_modules" ]; then
+              echo "Correct symlink already exists: apps/frontend/node_modules -> ../../node_modules"
+            else
+              echo "Removing incorrect/broken symlink (was: $target)..."
+              rm -f "apps/frontend/node_modules"
+            fi
+          else
+            echo "Removing partial node_modules directory created by npm workspaces..."
+            rm -rf "apps/frontend/node_modules"
+          fi
+        fi
+
+        # Create link if it doesn't exist or was removed
+        if [ ! -L "apps/frontend/node_modules" ]; then
+          if [ "$RUNNER_OS" == "Windows" ]; then
+            # Use directory junction on Windows (works without admin privileges)
+            # Use PowerShell's New-Item -ItemType Junction for reliable path handling
+            abs_target=$(cygpath -w "$(pwd)/node_modules")
+            link_path=$(cygpath -w "$(pwd)/apps/frontend/node_modules")
+            powershell -Command "New-Item -ItemType Junction -Path '$link_path' -Target '$abs_target'" > /dev/null
+            if [ $? -eq 0 ]; then
+              echo "Created junction: apps/frontend/node_modules -> $abs_target"
+            else
+              echo "::error::Failed to create directory junction on Windows"
+              exit 1
+            fi
+          else
+            # Use symlink on Unix (macOS/Linux)
+            if ln -s ../../node_modules apps/frontend/node_modules; then
+              echo "Created symlink: apps/frontend/node_modules -> ../../node_modules"
+            else
+              echo "::error::Failed to create symlink"
+              exit 1
+            fi
+          fi
+        fi
+
+        # Final verification - the link must exist and resolve correctly
+        # Note: On Windows, junctions don't show as symlinks (-L), so we check if the directory exists
+        # and can be listed. On Unix, we also verify it's a symlink.
+        if [ "$RUNNER_OS" != "Windows" ] && [ ! -L "apps/frontend/node_modules" ]; then
+          echo "::error::apps/frontend/node_modules symlink was not created"
+          exit 1
+        fi
+        # Verify the link resolves to a valid directory with content
+        if ! ls apps/frontend/node_modules/electron >/dev/null 2>&1; then
+          echo "::error::apps/frontend/node_modules does not resolve correctly (electron not found)"
+          ls -la apps/frontend/ || true
+          ls apps/frontend/node_modules 2>&1 | head -5 || true
+          exit 1
+        fi
+        count=$(ls apps/frontend/node_modules 2>/dev/null | wc -l)
+        echo "Verified: apps/frontend/node_modules resolves correctly ($count entries)"
@@ -75,7 +75,7 @@ jobs:
          ref: ${{ github.event.inputs.dry_run == 'true' && 'develop' || format('v{0}', needs.create-tag.outputs.version) }}

      - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
        with:
          python-version: '3.11'

@@ -86,7 +86,7 @@ jobs:
        uses: dtolnay/rust-toolchain@stable

      - name: Cache pip wheel cache (for compiled packages like real_ladybug)
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: ~/Library/Caches/pip
          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
@@ -94,7 +94,7 @@ jobs:
            pip-wheel-${{ runner.os }}-x64-

      - name: Cache bundled Python
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: apps/frontend/python-runtime
          key: python-bundle-${{ runner.os }}-x64-3.12.8-rust-${{ hashFiles('apps/backend/requirements.txt') }}
@@ -151,7 +151,7 @@ jobs:
          ref: ${{ github.event.inputs.dry_run == 'true' && 'develop' || format('v{0}', needs.create-tag.outputs.version) }}

      - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
        with:
          python-version: '3.11'

@@ -159,7 +159,7 @@ jobs:
        uses: ./.github/actions/setup-node-frontend

      - name: Cache pip wheel cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: ~/Library/Caches/pip
          key: pip-wheel-${{ runner.os }}-arm64-${{ hashFiles('apps/backend/requirements.txt') }}
@@ -167,7 +167,7 @@ jobs:
            pip-wheel-${{ runner.os }}-arm64-

      - name: Cache bundled Python
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: apps/frontend/python-runtime
          key: python-bundle-${{ runner.os }}-arm64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
@@ -226,7 +226,7 @@ jobs:
          ref: ${{ github.event.inputs.dry_run == 'true' && 'develop' || format('v{0}', needs.create-tag.outputs.version) }}

      - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
        with:
          python-version: '3.11'

@@ -234,7 +234,7 @@ jobs:
        uses: ./.github/actions/setup-node-frontend

      - name: Cache pip wheel cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: ~\AppData\Local\pip\Cache
          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
@@ -242,7 +242,7 @@ jobs:
            pip-wheel-${{ runner.os }}-x64-

      - name: Cache bundled Python
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: apps/frontend/python-runtime
          key: python-bundle-${{ runner.os }}-x64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
@@ -398,24 +398,24 @@ jobs:
          ref: ${{ github.event.inputs.dry_run == 'true' && 'develop' || format('v{0}', needs.create-tag.outputs.version) }}

      - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
        with:
          python-version: '3.11'

      - name: Setup Node.js and install dependencies
        uses: ./.github/actions/setup-node-frontend

-      - name: Setup Flatpak
+      - name: Setup Flatpak and verification tools
        run: |
          set -e
          sudo apt-get update
-          sudo apt-get install -y flatpak flatpak-builder
+          sudo apt-get install -y flatpak flatpak-builder libarchive-tools
          flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
          flatpak install -y --user flathub org.freedesktop.Platform//25.08 org.freedesktop.Sdk//25.08
          flatpak install -y --user flathub org.electronjs.Electron2.BaseApp//25.08

      - name: Cache pip wheel cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: ~/.cache/pip
          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
@@ -423,7 +423,7 @@ jobs:
            pip-wheel-${{ runner.os }}-x64-

      - name: Cache bundled Python
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: apps/frontend/python-runtime
          key: python-bundle-${{ runner.os }}-x64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
@@ -447,6 +447,9 @@ jobs:
          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}

+      - name: Verify Linux packages
+        run: cd apps/frontend && npm run verify:linux
+
      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
@@ -465,13 +468,13 @@ jobs:
      - uses: actions/checkout@v4

      - name: Download Intel DMG
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
        with:
          name: macos-intel-builds
          path: intel

      - name: Download ARM64 DMG
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
        with:
          name: macos-arm64-builds
          path: arm64
@@ -512,7 +515,7 @@ jobs:
          fetch-depth: 0

      - name: Download all artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
        with:
          path: dist

@@ -661,7 +664,7 @@ jobs:
      - uses: actions/checkout@v4

      - name: Download all artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
        with:
          path: dist

@@ -10,11 +10,11 @@ on:
      electron_version:
        description: 'Electron version to build for'
        required: false
-        default: '39.2.6'
+        default: '40.0.0'

 env:
  # Default Electron version - update when upgrading Electron in package.json
-  ELECTRON_VERSION: ${{ github.event.inputs.electron_version || '39.2.6' }}
+  ELECTRON_VERSION: ${{ github.event.inputs.electron_version || '40.0.0' }}

 jobs:
  build-windows:
@@ -30,7 +30,7 @@ jobs:
        uses: actions/checkout@v4

      - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
        with:
          node-version: '24'

@@ -110,7 +110,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Download all artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
        with:
          path: artifacts

@@ -11,7 +11,7 @@ jobs:
      issues: write
    steps:
      - name: Add area label from form
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
        with:
          script: |
            const issue = context.payload.issue;
@@ -34,7 +34,7 @@ jobs:
        uses: actions/checkout@v4

      - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
        with:
          python-version: '3.12'

@@ -22,7 +22,7 @@ jobs:

    steps:
      - name: Label PR
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
        with:
          retries: 3
          retry-exempt-status-codes: 400,401,403,404,422
@@ -1,9 +1,8 @@
 name: Quality Security

-# CodeQL is slow (20-30 min per language), so:
-# - Run on push to main only (not PRs or develop)
-# - Run weekly scheduled scan
-# Bandit is fast (5-10 min), so keep it on all PRs
+# CodeQL runs on all PRs, pushes to main, and weekly schedule
+# Note: CodeQL takes 20-30 min per language (40-60 min total)
+# Bandit is fast (5-10 min)

 on:
  push:
@@ -35,13 +34,10 @@ permissions:
  actions: read

 jobs:
-  # CodeQL only on push to main or scheduled (NOT on PRs - saves 40-60 min per PR)
  codeql:
    name: CodeQL (${{ matrix.language }})
    runs-on: ubuntu-latest
    timeout-minutes: 30
-    # Only run on push to main or scheduled - skip PRs for speed
-    if: github.event_name == 'push' || github.event_name == 'schedule'
    strategy:
      fail-fast: false
      matrix:
@@ -74,7 +70,7 @@ jobs:
        uses: actions/checkout@v4

      - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
        with:
          python-version: '3.12'

@@ -93,7 +89,7 @@ jobs:
          echo "::endgroup::"

      - name: Analyze Bandit results
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
        with:
          script: |
            const fs = require('fs');
@@ -153,7 +149,7 @@ jobs:
    timeout-minutes: 5
    steps:
      - name: Check security results
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
        with:
          script: |
            const codeql = '${{ needs.codeql.result }}';
@@ -30,7 +30,7 @@ jobs:
      - uses: actions/checkout@v4

      - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
        with:
          python-version: '3.11'

@@ -41,7 +41,7 @@ jobs:
        uses: dtolnay/rust-toolchain@stable

      - name: Cache pip wheel cache (for compiled packages like real_ladybug)
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: ~/Library/Caches/pip
          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
@@ -49,7 +49,7 @@ jobs:
            pip-wheel-${{ runner.os }}-x64-

      - name: Cache bundled Python
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: apps/frontend/python-runtime
          key: python-bundle-${{ runner.os }}-x64-3.12.8-rust-${{ hashFiles('apps/backend/requirements.txt') }}
@@ -101,7 +101,7 @@ jobs:
      - uses: actions/checkout@v4

      - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
        with:
          python-version: '3.11'

@@ -109,7 +109,7 @@ jobs:
        uses: ./.github/actions/setup-node-frontend

      - name: Cache pip wheel cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: ~/Library/Caches/pip
          key: pip-wheel-${{ runner.os }}-arm64-${{ hashFiles('apps/backend/requirements.txt') }}
@@ -117,7 +117,7 @@ jobs:
            pip-wheel-${{ runner.os }}-arm64-

      - name: Cache bundled Python
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: apps/frontend/python-runtime
          key: python-bundle-${{ runner.os }}-arm64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
@@ -171,7 +171,7 @@ jobs:
      - uses: actions/checkout@v4

      - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
        with:
          python-version: '3.11'

@@ -179,7 +179,7 @@ jobs:
        uses: ./.github/actions/setup-node-frontend

      - name: Cache pip wheel cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: ~\AppData\Local\pip\Cache
          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
@@ -187,7 +187,7 @@ jobs:
            pip-wheel-${{ runner.os }}-x64-

      - name: Cache bundled Python
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: apps/frontend/python-runtime
          key: python-bundle-${{ runner.os }}-x64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
@@ -337,23 +337,23 @@ jobs:
      - uses: actions/checkout@v4

      - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
        with:
          python-version: '3.11'

      - name: Setup Node.js and install dependencies
        uses: ./.github/actions/setup-node-frontend

-      - name: Setup Flatpak
+      - name: Setup Flatpak and verification tools
        run: |
          sudo apt-get update
-          sudo apt-get install -y flatpak flatpak-builder
+          sudo apt-get install -y flatpak flatpak-builder libarchive-tools
          flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
          flatpak install -y --user flathub org.freedesktop.Platform//25.08 org.freedesktop.Sdk//25.08
          flatpak install -y --user flathub org.electronjs.Electron2.BaseApp//25.08

      - name: Cache pip wheel cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: ~/.cache/pip
          key: pip-wheel-${{ runner.os }}-x64-${{ hashFiles('apps/backend/requirements.txt') }}
@@ -361,7 +361,7 @@ jobs:
            pip-wheel-${{ runner.os }}-x64-

      - name: Cache bundled Python
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: apps/frontend/python-runtime
          key: python-bundle-${{ runner.os }}-x64-3.12.8-${{ hashFiles('apps/backend/requirements.txt') }}
@@ -383,6 +383,9 @@ jobs:
          SENTRY_TRACES_SAMPLE_RATE: ${{ secrets.SENTRY_TRACES_SAMPLE_RATE }}
          SENTRY_PROFILES_SAMPLE_RATE: ${{ secrets.SENTRY_PROFILES_SAMPLE_RATE }}

+      - name: Verify Linux packages
+        run: cd apps/frontend && npm run verify:linux
+
      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
@@ -402,13 +405,13 @@ jobs:
      - uses: actions/checkout@v4

      - name: Download Intel DMG
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
        with:
          name: macos-intel-builds
          path: intel

      - name: Download ARM64 DMG
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
        with:
          name: macos-arm64-builds
          path: arm64
@@ -447,7 +450,7 @@ jobs:
          fetch-depth: 0

      - name: Download all artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v7
        with:
          path: dist

@@ -631,7 +634,8 @@ jobs:
      - uses: actions/checkout@v4
        with:
          ref: main
-          token: ${{ secrets.GITHUB_TOKEN }}
+          # Use PAT_TOKEN to bypass branch protection rules on main
+          token: ${{ secrets.PAT_TOKEN }}

      - name: Extract version and detect release type
        id: version
@@ -56,6 +56,8 @@ lerna-debug.log*
 # Auto Claude Generated
 # ===========================
 .auto-claude/
+.planning/
+.planning-archive/
 .auto-build-security.json
 .auto-claude-security.json
 .auto-claude-status
@@ -170,4 +172,5 @@ OPUS_ANALYSIS_AND_IDEAS.md
 # Auto Claude generated files
 .security-key
 /shared_docs
-Agents.md
+logs/security/
+Agents.md
@@ -290,11 +290,14 @@ if git diff --cached --name-only | grep -q "^apps/frontend/"; then
        exit 1
      fi

-      # Check for vulnerabilities (only high severity)
+      # Check for vulnerabilities (only critical severity)
+      # Note: Using critical level because electron-builder has a known high-severity
+      # tar vulnerability (CVE-2026-23745) that cannot be fixed until electron-builder
+      # releases an update with tar@7.x support. This is a build dependency, not runtime.
      echo "Checking for vulnerabilities..."
-      npm audit --audit-level=high
+      npm audit --audit-level=critical
      if [ $? -ne 0 ]; then
-        echo "High severity vulnerabilities found. Run 'npm audit fix' to resolve."
+        echo "Critical severity vulnerabilities found. Run 'npm audit fix' to resolve."
        exit 1
      fi
    )
@@ -76,6 +76,17 @@ repos:
        files: ^package\.json$
        pass_filenames: false

+  # Python encoding check - prevent regression of UTF-8 encoding fixes (PR #782)
+  - repo: local
+    hooks:
+      - id: check-file-encoding
+        name: Check file encoding parameters
+        entry: python scripts/check_encoding.py
+        language: system
+        types: [python]
+        files: ^apps/backend/
+        description: Ensures all file operations specify encoding="utf-8"
+
  # Python linting (apps/backend/)
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.14.10
@@ -1,3 +1,394 @@
+## 2.7.5 - Security & Platform Improvements
+
+### ✨ New Features
+
+- One-time version 2.7.5 reauthentication warning modal for improved security awareness
+
+- Enhanced authentication failure detection and handling with improved error recovery
+
+- PR review validation pipeline with context enrichment and cross-validation support
+
+- Terminal "Others" section in worktree dropdown for better organization
+
+- Keyboard shortcut to toggle terminal expand/collapse for improved usability
+
+- Searchable branch combobox in worktree creation dialog for easier branch selection
+
+- Update Branch button in PR detail view for streamlined workflow
+
+- Bulk select and create PR functionality for human review column
+
+- Draggable Kanban task reordering for flexible task management
+
+- YOLO mode to invoke Claude with --dangerously-skip-permissions for advanced users
+
+- File and screenshot upload to QA feedback interface for better feedback submission
+
+- Task worktrees section with terminal limit removal for expanded parallel work
+
+- Claude Code version rollback feature for version management
+
+- Linux secret-service support for OAuth token storage (ACS-293)
+
+### 🛠️ Improvements
+
+- Replace setup-token with embedded /login terminal flow for streamlined authentication
+
+- Refactored authentication using platform abstraction for cross-platform reliability
+
+- Removed redundant backend CLI detection (~230 lines) for cleaner codebase
+
+- Replaced Select with Combobox for branch selection UI improvements
+
+- Replace dangerouslySetInnerHTML with Trans component for better security practice
+
+- Wait for CI checks before starting AI PR review for more accurate results
+
+- Improved Claude CLI detection with installation selector
+
+- Terminal rendering, persistence, and link handling improvements
+
+- Enhanced terminal recreation logic with retry mechanism for reliability
+
+- Improved worktree name input UX with better validation
+
+- Made worktree isolation prominent in UI for user awareness
+
+- Reduce ultrathink value from 65536 to 60000 for Opus 4.5 compatibility
+
+- Standardized workflow naming and consolidated linting workflow
+
+- Added gate jobs to CI/CD pipeline for better quality control
+
+- Fast-path detection for merge commits without finding overlap in PR review
+
+- Show progress percentage during planning phase on task cards
+
+- PTY write improvements using PtyManager.writeToPty for safer terminal operations
+
+- Consolidated package-lock.json to root level for simpler dependency management
+
+- Graphiti memory feature fixes on macOS
+
+- Model versions updated to Claude 4.5 with connected insights to frontend settings
+
+### 🐛 Bug Fixes
+
+- Fixed Kanban board status flip-flopping and multi-location task deletion
+
+- Fixed Windows CLI detection and version selection UX issues
+
+- Fixed Windows coding phase not starting after spec/planning
+
+- Fixed Windows UTF-8 encoding errors across entire backend (251 instances)
+
+- Fixed 401 authentication errors by reading tokens from profile configDir
+
+- Fixed Windows packaging by using SDK bundled Claude CLI
+
+- Fixed false stuck detection during planning phase
+
+- Fixed PR list update on post status click
+
+- Fixed screenshot state persistence bug in task modals
+
+- Fixed non-functional '+ Add' button for multiple Claude accounts
+
+- Fixed GitHub Issues/PRs infinite scroll auto-fetch behavior
+
+- Fixed GitHub PR state management and follow-up review trigger bug
+
+- Fixed terminal output freezing on project switch
+
+- Fixed terminal rendering on app close to prevent zombie processes
+
+- Fixed stale terminal metadata filtering with auto-cleanup
+
+- Fixed worktree configuration sync after PTY creation
+
+- Fixed cross-worktree file leakage via environment variables
+
+- Fixed .gitignore auto-commit during project initialization
+
+- Fixed PR review verdict message contradiction and blocked status limbo
+
+- Fixed re-review functionality when previous review failed
+
+- Fixed agent profile resolution before falling back to defaults
+
+- Fixed Windows shell command support in Claude CLI invocation
+
+- Fixed model resolution using resolve_model_id() instead of hardcoded fallbacks
+
+- Fixed ultrathink token budget correction from 64000 to 63999
+
+- Fixed Windows pywin32 DLL loading failure on Python 3.8+
+
+- Fixed circular import between spec.pipeline and core.client
+
+- Fixed pywin32 bundling in Windows binary
+
+- Fixed secretstorage bundling in Linux binary
+
+- Fixed gh CLI detection for PR creation
+
+- Fixed PYTHONPATH isolation to prevent pollution of external projects
+
+- Fixed structured output capture from SDK ResultMessage in PR review
+
+- Fixed CI status refresh before returning cached verdict
+
+- Fixed Python environment readiness before spawning tasks
+
+- Fixed pywintypes import errors during dependency validation
+
+- Fixed Node.js and npm path detection on Windows packaged apps
+
+- Fixed Windows PowerShell command separator usage
+
+- Fixed require is not defined error in terminal handler
+
+- Fixed Sentry DSN initialization error handling
+
+- Fixed requestAnimationFrame fallback for flaky Ubuntu CI tests
+
+- Fixed file drag-and-drop to terminals and task modals with branch status refresh
+
+- Fixed GitHub issues pagination and infinite scroll
+
+- Fixed delete worktree status regression
+
+- Fixed Mac crash on Invoke Claude button
+
+- Fixed worktree symlink for node_modules to enable TypeScript support
+
+- Fixed PTY wait on Windows before recreating terminal
+
+- Fixed terminal aggressive renaming on Claude invocation
+
+- Fixed worktree dropdown scroll area to prevent overflow
+
+- Fixed GitHub PR preloading currently under review
+
+- Fixed actual base branch name display instead of hardcoded main
+
+- Fixed Claude CLI detection with improved installation selector
+
+- Fixed broken pipe errors with Sentry integration
+
+- Fixed app update persistence for Install button visibility
+
+- Fixed Claude exit detection and label reset
+
+- Fixed file merging to include files with content changes
+
+- Fixed worktree config sync on terminal restoration
+
+- Fixed security profile inheritance in worktrees and shell -c validation
+
+- Fixed terminal drag and drop reordering collision detection
+
+- Fixed "already up to date" case handling in worktree operations
+
+- Fixed Windows UTF-8 encoding and path handling issues
+
+- Fixed Terminal label persistence after app restart
+
+- Fixed worktree dropdown enhancement with scrolling support
+
+- Fixed enforcement of 12 terminal limit per project
+
+- Fixed macOS UTF-8 encoding errors (251 instances)
+
+### 📚 Documentation
+
+- Added fork configuration guidance to CONTRIBUTING.md
+
+- Updated README download links to v2.7.4
+
+### 🔧 Other Changes
+
+- Removed node_modules symlink and cleaned up package-lock.json
+
+- Added .planning/ to gitignore
+
+- Migrated ESLint to Biome with optimized workflows
+
+- Fixed tar vulnerability in dependencies
+
+- Added minimatch to externalized dependencies
+
+- Added exception handling for malformed DSN during Sentry initialization
+
+- Corrected roadmap import path in roadmap_runner.py
+
+- Added require polyfill for ESM/Sentry compatibility
+
+- Addressed CodeQL security alerts and code quality issues
+
+- Added shell: true and argument sanitization for Windows packaging
+
+- Packaged runtime dependencies with pydantic_core validation
+
+---
+
+## What's Changed
+
+- test(subprocess): add comprehensive auth failure detection tests by @AndyMik90 in ccaf82db
+- fix(security): replace dangerouslySetInnerHTML with Trans component and persist version warning by @AndyMik90 in 7aec35c3
+- chore: remove node_modules symlink and clean up package-lock.json by @AndyMik90 in 9768af8e
+- fix: address PR review issues and improve code quality by @AndyMik90 in 23a7e5a2
+- fix(auth): read tokens from profile configDir to fix 401 errors (#1385) by @Andy in 55857d6d
+- fix: Kanban board status flip-flopping and multi-location task deletion (#1387) by @Adam Slaker in 7dcb7bbe
+- fix(windows): use SDK bundled Claude CLI for Windows packaged apps (#1382) by @Andy in cd4e2d38
+- feat(auth): enhance authentication failure detection and handling by @AndyMik90 in 7ab10cd5
+- refactor(subprocess): use platform abstraction for auth failure process killing by @AndyMik90 in 17cffecc
+- feat(ui): add one-time version 2.7.5 reauthentication warning modal by @AndyMik90 in f49ef92a
+- refactor: remove redundant backend CLI detection (~230 lines) (#1367) by @Andy in c7bc01d5
+- feat(pr-review): add validation pipeline, context enrichment, and cross-validation (#1354) by @Andy in d8f4de9a
+- fix(terminal): rename Claude terminals only once on initial message (#1366) by @Andy in b2d2d7e9
+- feat(auth): add auth failure detection modal for Claude CLI 401 errors (#1361) by @Andy in 317d5e94
+- docs: add fork configuration guidance to CONTRIBUTING.md (#1364) by @Andy in c57534c3
+- Fix #609: Windows coding phase not starting after spec/planning (#1347) by @TamerineSky in 6da1b170
+- Fix Windows UTF-8 encoding errors across entire backend (251 instances) (#782) by @TamerineSky in 6a6247bb
+- chore: add .planning/ to gitignore by @AndyMik90 in 8df66245
+- feat(auth): replace setup-token with embedded /login terminal flow (#1321) by @Andy in 11f8d572
+- fix: Windows CLI detection and version selection UX improvements (#1341) by @StillKnotKnown in 8a2f3acd
+- fix: add shell: true and argument sanitization for Windows packaging (#1340) by @StillKnotKnown in e482fdf1
+- fix: package runtime deps and validate pydantic_core (#1336) by @StillKnotKnown in 141f44f6
+- fix(test): update mock profile manager and relax audit level by @Test User in 86ba0246
+- 2.7.4 release stable by @Test User in 3e2d6ef4
+- fix(tests): update claude-integration-handler tests for PtyManager.writeToPty by @Test User in 56743ff7
+- chore: consolidate package-lock.json to root level by @Test User in d4044d26
+- build: add minimatch to externalized dependencies by @Test User in 95f7f222
+- refactor(terminal): use PtyManager.writeToPty for safer PTY writes by @Test User in 4637a1a9
+- fix: correct ultrathink token budget from 64000 to 63999 by @Test User in efdb8c71
+- ci: migrate ESLint to Biome, optimize workflows, fix tar vulnerability (#1289) by @Andy in 0b2cf9b0
+- Fix API 401 - Token Decryption Before SDK Initialization (#1283) by @Andy in 4b740928
+- Fix Ultrathink Token Limit Bug (#1284) by @Andy in e989300b
+- fix(security): address CodeQL security alerts and code quality issues (#1286) by @Andy in f700b18d
+- fix(ui): make prose-invert conditional on dark mode for light theme support (#1160) by @youngmrz in 439ed86a
+- fix(terminal): add require polyfill for ESM/Sentry compatibility (#1275) by @VDT-91 in eb739afe
+- fix: add retry logic for planning-to-coding transition (#1276) by @kaigler in b8655904
+- fix(worktree): prevent cross-worktree file leakage via environment variables (#1267) by @Andy in 7cb9e0a3
+- Fix/cleanup 2.7.5 (#1271) by @Andy in f0c3e508
+- Fix False Stuck Detection During Planning Phase (#1236) by @Andy in 44304a61
+- fix(pr-review): allow re-review when previous review failed (#1268) by @Andy in 4cc8f4db
+- fix: enforce 12 terminal limit per project (#1264) by @Andy in d7ed770e
+- Draggable Kanban Task Reordering (#1217) by @Andy in 3606a632
+- fix(terminal): sync worktree config after PTY creation to fix first-attempt failure (#1213) by @Andy in 39236f18
+- fix: auto-commit .gitignore changes during project initialization (#1087) (#1124) by @youngmrz in ba089c5b
+- Fix terminal rendering, persistence, and link handling (#1215) by @Andy in 75a3684c
+- fix(windows): prevent zombie process accumulation on app close (#1259) by @VDT-91 in 90204469
+- update gitignore by @AndyMik90 in c13d9a40
+- Fix PR List Update on Post Status Click (#1207) by @Andy in 3085e392
+- Fix screenshot state persistence bug in task modals (#1235) by @Andy in 3024d547
+- Fix non-functional '+ Add' button for multiple Claude accounts (#1216) by @Andy in e27ff344
+- Fix GitHub Issues/PRs Infinite Scroll Auto-Fetch (#1239) by @Andy in b74b628b
+- Add bulk delete functionality to worktree overview (#1208) by @Andy in 8833feb2
+- Fix GitHub PR State Management - Follow-up Review Trigger Bug (#1238) by @Andy in 76f07720
+- auto-claude: subtask-1-1 - Add useEffect hook to reset expandedTerminalId when projectPath changes (#1240) by @Andy in d1131080
+- Fix Terminal Output Freezing on Project Switch (#1241) by @Andy in 193d2ed9
+- Add Update Branch Button to PR Detail View (#1242) by @Andy in 87c84073
+- Bulk Select All & Create PR for Human Review Column (#1248) by @Andy in 715202b8
+- fix(windows): resolve pywin32 DLL loading failure on Python 3.8+ (#1244) by @VDT-91 in cb786cac
+- fix(gh-cli): use get_gh_executable() and pass GITHUB_CLI_PATH from GUI (ACS-321) (#1232) by @StillKnotKnown in 14fbc2eb
+- auto-claude: subtask-1-1 - Replace Select with Combobox for branch selection (#1250) by @Andy in ed45ece5
+- fix(sentry): add exception handling for malformed DSN during Sentry initialization by @AndyMik90 in 4f86742b
+- dev dependecnies using npm install all by @AndyMik90 in e52a1ba4
+- hotfix/dev-dependency-missing by @AndyMik90 in a0033b1e
+- fix(frontend): resolve require is not defined error in terminal handler (#1243) by @Antti in 9117b59e
+- hotfix/node by @AndyMik90 in bb620044
+- fix(windows): add Node.js and npm paths to COMMON_BIN_PATHS for packaged apps (#1158) by @youngmrz in f0319bc8
+- fix/stale-task-creation by @AndyMik90 in 9612cf8d
+- fix/sentry-local-build by @AndyMik90 in b822797f
+- hotfix/tar-vurnability by @AndyMik90 in 2096b0e2
+- fix(tests): add requestAnimationFrame fallback for flaky Ubuntu CI tests by @AndyMik90 in 9739b338
+- fix(windows): use correct command separator for PowerShell terminals (#1159) by @youngmrz in cb8e46ca
+- fix(ui): show progress percentage during planning phase on task cards (#1162) by @youngmrz in 515aada1
+- fix(tests): isolate git operations in test fixtures from parent repository (#1205) by @Andy in 596b1e0c
+- feat(terminal): add "Others" section to worktree dropdown (#1209) by @Andy in 219cc068
+- fix(linux): ensure secretstorage is bundled in Linux binary (ACS-310) (#1211) by @StillKnotKnown in 48bd4a9c
+- fix(terminal): persist worktree label after app restart (#1210) by @Andy in ba7358af
+- fix: Graphiti memory feature on macOS (#1174) by @Alexander Penzin in c2e53d58
+- fix(windows): ensure pywin32 is bundled in Windows binary (ACS-306) (#1197) by @StillKnotKnown in 76af0aaa
+- fix(spec): resolve circular import between spec.pipeline and core.client (ACS-302) (#1192) by @StillKnotKnown in 648cf3fc
+- Fix Mac Crash on Invoke Claude Button (#1185) by @Andy in ae40f819
+- fix(worktree): symlink node_modules to worktrees for TypeScript support (#1148) by @Andy in d7c7ce8e
+- fix(terminal): wait for PTY exit on Windows before recreating terminal (#1184) by @Andy in d5d56975
+- fix(runners): use resolve_model_id() for model resolution instead of hardcoded fallbacks (ACS-294) (#1170) by @StillKnotKnown in 5199fdbf
+- fix(frontend): support Windows shell commands in Claude CLI invocation (ACS-261) (#1152) by @StillKnotKnown in 3a1966bd
+- feat(terminal): add keyboard shortcut to toggle expand/collapse (#1180) by @Andy in 1edfe333
+- fix(kanban): remove error column and add backend JSON repair (#1143) by @Andy in 51f67c5d
+- fix(ci): add gate jobs and consolidate linting workflow (#1182) by @Andy in 4b43f074
+- fix(ci): standardize workflow naming and remove redundant workflows (#1178) by @Andy in 4a3391b2
+- fix(terminal): enable scrolling in worktree dropdown when many items exist (#1175) by @Andy in 5525f36d
+- fix: windows (#1056) by @Alex in d6234f52
+- fix(backend): reduce ultrathink value from 65536 to 60000 for Opus 4.5 compatibility (#1173) by @StillKnotKnown in 30638c2f
+- feat(backend): add Linux secret-service support for OAuth token storage (ACS-293) (#1168) by @StillKnotKnown in a6934a8e
+- fix(terminal): prevent aggressive renaming on Claude invocation (#1147) by @Andy in 10bceac9
+- fix(pr-review): resolve verdict message contradiction and blocked status limbo (#1151) by @Andy in 8b269fea
+- feat(pr-review): add fast-path detection for merge commits without finding overlap (#1145) by @Andy in 32811142
+- fix(frontend): resolve agent profile before falling back to defaults (ACS-255) (#1068) by @StillKnotKnown in 33014682
+- fix(terminal): add scroll area to worktree dropdown to prevent overflow (#1146) by @Andy in 200bb3bc
+- fix(frontend): add windowsVerbatimArguments for Windows .cmd validation (ACS-252) (#1075) by @StillKnotKnown in 658f26cb
+- fix(backend): improve gh CLI detection for PR creation (ACS-247) (#1071) by @StillKnotKnown in 2eef82bf
+- fix(terminal): filter stale worktree metadata and auto-cleanup (#1038) by @Andy in 16bc37ce
+- Fix Delete Worktree Status Regression (#1076) by @Andy in 97f98ed7
+- 117-sidebar-update-banner (#1078) by @Andy in 4fd25b01
+- fix(ci): add beta manifest renaming and validation (#1002) (#1080) by @Andy in c6c6525b
+- fix: update all model versions to Claude 4.5 and connect insights to frontend settings (#1082) by @Andy in 58f4f30b
+- fix: file drag-and-drop to terminals and task modals + branch status refresh (#1092) by @Andy in b5c0e631
+- fix(github-issues): add pagination and infinite scroll for issues tab (#1042) by @Andy in f1674923
+- fix(ci): enable automatic release workflow triggering (#1043) by @Andy in 2ff9ccab
+- fix(backend): isolate PYTHONPATH to prevent pollution of external projects (ACS-251) (#1065) by @StillKnotKnown in 18d9b6cf
+- add time sensitive AI review logic (#1137) by @Andy in 5fb7574b
+- fix(pr-review): use list instead of tuple for line_range to fix SDK structured output (#1140) by @Andy in 45060ca3
+- feat(github-review): wait for CI checks before starting AI PR review (#1131) by @Andy in a55e4f68
+- fix(frontend): pass CLAUDE_CLI_PATH to Python backend subprocess (ACS-230) (#1081) by @StillKnotKnown in 5e91c3a7
+- fix(runners): correct roadmap import path in roadmap_runner.py (ACS-264) (#1091) by @StillKnotKnown in 767dd5c3
+- fix(pr-review): properly capture structured output from SDK ResultMessage (#1133) by @Andy in f28d2298
+- fix(github-review): refresh CI status before returning cached verdict (#1083) by @Andy in c3bdd4f8
+- fix(agent): ensure Python env is ready before spawning tasks (ACS-254) (#1061) by @StillKnotKnown in 7dc54f23
+- fix(windows): prevent pywintypes import errors before dependency validation (ACS-253) (#1057) by @StillKnotKnown in 71a9fc84
+- fix(docs): update README download links to v2.7.4 by @Test User in 67b39e52
+- fix readme for 2.7.4 by @Test User in a0800646
+- changelog 2.7.4 by @AndyMik90 in 1b5aecdd
+- 2.7.4 release by @AndyMik90 in 72797ac0
+- fix(frontend): validate Windows claude.cmd reliably in GUI (#1023) by @Umaru in 1ae3359b
+- fix(auth): await profile manager initialization before auth check (#1010) by @StillKnotKnown in c8374bc1
+- Add file/screenshot upload to QA feedback interface (#1018) by @Andy in 88277f84
+- feat(terminal): add task worktrees section and remove terminal limit (#1033) by @Andy in 17118b07
+- fix(terminal): enhance terminal recreation logic with retry mechanism (#1013) by @Andy in df1b8a3f
+- fix(terminal): improve worktree name input UX (#1012) by @Andy in 54e9f228
+- Make worktree isolation prominent in UI (#1020) by @Andy in 4dbb7ee4
+- feat(terminal): add YOLO mode to invoke Claude with --dangerously-skip-permissions (#1016) by @Andy in d48e5f68
+- Fix Duplicate Kanban Task Creation on Rapid Button Clicks (#1021) by @Andy in 2d1d3ef1
+- feat(sentry): embed Sentry DSN at build time for packaged apps (#1025) by @Andy in aed28c5f
+- fix(github): resolve circular import issues in context_gatherer and services (#1026) by @Andy in 0307a4a9
+- hotfix/sentry-backend-build by @AndyMik90 in e7b38d49
+- chore: bump version to 2.7.4 by @AndyMik90 in 432e985b
+- fix(github-prs): prevent preloading of PRs currently under review (#1006) by @Andy in 1babcc86
+- fix(ui): display actual base branch name instead of hardcoded main (#969) by @Andy in 5d07d5f1
+- ci(release): move VirusTotal scan to separate post-release workflow (#980) by @Andy in 553d1e8d
+- fix: improve Claude CLI detection and add installation selector (#1004) by @Andy in e07a0dbd
+- fix(backend): add Sentry integration and fix broken pipe errors (#991) by @Andy in aa9fbe9d
+- fix(app-update): persist downloaded update state for Install button visibility (#992) by @Andy in 6f059bb5
+- fix(terminal): detect Claude exit and reset label when user closes Claude (#990) by @Andy in 14982e66
+- fix(merge): include files with content changes even when semantic analysis is empty (#986) by @Andy in 4736b6b6
+- fix(frontend): sync worktree config to renderer on terminal restoration (#982) by @Andy in 68fe0860
+- feat(frontend): add searchable branch combobox to worktree creation dialog (#979) by @Andy in 2a2dc3b8
+- fix(security): inherit security profiles in worktrees and validate shell -c commands (#971) by @Andy in 750ea8d1
+- feat(frontend): add Claude Code version rollback feature (#983) by @Andy in 8d21978f
+- fix(ACS-181): enable auto-switch on 401 auth errors & OAuth-only profiles (#900) by @Michael Ludlow in e7427321
+- fix(terminal): add collision detection for terminal drag and drop reordering (#985) by @Andy in 1701160b
+- fix(worktree): handle "already up to date" case correctly (ACS-226) (#961) by @StillKnotKnown in 74ed4320
+- ci: add Azure auth test workflow by @AndyMik90 in d12eb523
+
+## Thanks to all contributors
+
+@AndyMik90, @Andy, @Adam Slaker, @TamerineSky, @StillKnotKnown, @Test User, @youngmrz, @VDT-91, @kaigler, @Alexander Penzin, @Antti, @Alex, @Michael Ludlow, @Umaru
+
 ## 2.7.4 - Terminal & Workflow Enhancements

 ### ✨ New Features
@@ -1,642 +1,339 @@
 # CLAUDE.md

-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to Claude Code when working with this repository.

-## Project Overview
+Auto Claude is an autonomous multi-agent coding framework that plans, builds, and validates software for you. It's a monorepo with a Python backend (CLI + agent logic) and an Electron/React frontend (desktop UI).

-Auto Claude is a multi-agent autonomous coding framework that builds software through coordinated AI agent sessions. It uses the Claude Agent SDK to run agents in isolated workspaces with security controls.
+> **Deep-dive reference:** [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md) | **Frontend contributing:** [apps/frontend/CONTRIBUTING.md](apps/frontend/CONTRIBUTING.md)

-**CRITICAL: All AI interactions use the Claude Agent SDK (`claude-agent-sdk` package), NOT the Anthropic API directly.**
+## Product Overview
+
+Auto Claude is a desktop application (+ CLI) where users describe a goal and AI agents autonomously handle planning, implementation, and QA validation. All work happens in isolated git worktrees so the main branch stays safe.
+
+**Core workflow:** User creates a task → Spec creation pipeline assesses complexity and writes a specification → Planner agent breaks it into subtasks → Coder agent implements (can spawn parallel subagents) → QA reviewer validates → QA fixer resolves issues → User reviews and merges.
+
+**Main features:**
+
+- **Autonomous Tasks** — Multi-agent pipeline (planner, coder, QA) that builds features end-to-end
+- **Kanban Board** — Visual task management from planning through completion
+- **Agent Terminals** — Up to 12 parallel AI-powered terminals with task context injection
+- **Insights** — AI chat interface for exploring and understanding your codebase
+- **Roadmap** — AI-assisted feature planning with strategic roadmap generation
+- **Ideation** — Discover improvements, performance issues, and security vulnerabilities
+- **GitHub/GitLab Integration** — Import issues, AI-powered investigation, PR/MR review and creation
+- **Changelog** — Generate release notes from completed tasks
+- **Memory System** — Graphiti-based knowledge graph retains insights across sessions
+- **Isolated Workspaces** — Git worktree isolation for every build; AI-powered semantic merge
+- **Flexible Authentication** — Use a Claude Code subscription (OAuth) or API profiles with any Anthropic-compatible endpoint (e.g., Anthropic API, z.ai for GLM models)
+- **Multi-Account Swapping** — Register multiple Claude accounts; when one hits a rate limit, Auto Claude automatically switches to an available account
+- **Cross-Platform** — Native desktop app for Windows, macOS, and Linux with auto-updates
+
+## Critical Rules
+
+**Claude Agent SDK only** — All AI interactions use `claude-agent-sdk`. NEVER use `anthropic.Anthropic()` directly. Always use `create_client()` from `core.client`.
+
+**i18n required** — All frontend user-facing text MUST use `react-i18next` translation keys. Never hardcode strings in JSX/TSX. Add keys to both `en/*.json` and `fr/*.json`.
+
+**Platform abstraction** — Never use `process.platform` directly. Import from `apps/frontend/src/main/platform/` or `apps/backend/core/platform/`. CI tests all three platforms.
+
+**No time estimates** — Never provide duration predictions. Use priority-based ordering instead.
+
+**PR target** — Always target the `develop` branch for PRs to AndyMik90/Auto-Claude, NOT `main`.
+
+## Memory (claude-mem)
+
+This project uses claude-mem for persistent memory across sessions. MCP search tools are available — use them proactively:
+
+- **Before modifying code** — Search for past work on the same files/features: `search(query="<file or feature>")`. Check if there are known bugs, decisions, or patterns to follow.
+- **When debugging** — Search for prior encounters with the same error or symptom: `search(query="<error message>", type="bugfix")`.
+- **When making architectural decisions** — Check for past decisions: `search(query="<topic>", type="decision")`.
+- **When resuming work** — Use `timeline(anchor=<recent_id>)` to understand where things left off.
+
+Follow the 3-layer workflow: `search` (cheap index) → `timeline` (context) → `get_observations` (full details only for relevant IDs). Never fetch full details without filtering first.

 ## Project Structure

 ```
 autonomous-coding/
 ├── apps/
-│   ├── backend/           # Python backend/CLI - ALL agent logic lives here
-│   │   ├── core/          # Client, auth, security
-│   │   ├── agents/        # Agent implementations
-│   │   ├── spec_agents/   # Spec creation agents
-│   │   ├── integrations/  # Graphiti, Linear, GitHub
-│   │   └── prompts/       # Agent system prompts
-│   └── frontend/          # Electron desktop UI
-├── guides/                # Documentation
-├── tests/                 # Test suite
-└── scripts/               # Build and utility scripts
+│   ├── backend/                 # Python backend/CLI — ALL agent logic
+│   │   ├── core/                # client.py, auth.py, worktree.py, platform/
+│   │   ├── security/            # Command allowlisting, validators, hooks
+│   │   ├── agents/              # planner, coder, session management
+│   │   ├── qa/                  # reviewer, fixer, loop, criteria
+│   │   ├── spec/                # Spec creation pipeline
+│   │   ├── cli/                 # CLI commands (spec, build, workspace, QA)
+│   │   ├── context/             # Task context building, semantic search
+│   │   ├── runners/             # Standalone runners (spec, roadmap, insights, github)
+│   │   ├── services/            # Background services, recovery orchestration
+│   │   ├── integrations/        # graphiti/, linear, github
+│   │   ├── project/             # Project analysis, security profiles
+│   │   ├── merge/               # Intent-aware semantic merge for parallel agents
+│   │   └── prompts/             # Agent system prompts (.md)
+│   └── frontend/                # Electron desktop UI
+│       └── src/
+│           ├── main/            # Electron main process
+│           │   ├── agent/       # Agent queue, process, state, events
+│           │   ├── claude-profile/ # Multi-profile credentials, token refresh, usage
+│           │   ├── terminal/    # PTY daemon, lifecycle, Claude integration
+│           │   ├── platform/    # Cross-platform abstraction
+│           │   ├── ipc-handlers/# 40+ handler modules by domain
+│           │   ├── services/    # SDK session recovery, profile service
+│           │   └── changelog/   # Changelog generation and formatting
+│           ├── preload/         # Electron preload scripts (electronAPI bridge)
+│           ├── renderer/        # React UI
+│           │   ├── components/  # UI components (onboarding, settings, task, terminal, github, etc.)
+│           │   ├── stores/      # 24+ Zustand state stores
+│           │   ├── contexts/    # React contexts (ViewStateContext)
+│           │   ├── hooks/       # Custom hooks (useIpc, useTerminal, etc.)
+│           │   ├── styles/      # CSS / Tailwind styles
+│           │   └── App.tsx      # Root component
+│           ├── shared/          # Shared types, i18n, constants, utils
+│           │   ├── i18n/locales/# en/*.json, fr/*.json
+│           │   ├── constants/   # themes.ts, etc.
+│           │   ├── types/       # 19+ type definition files
+│           │   └── utils/       # ANSI sanitizer, shell escape, provider detection
+│           └── types/           # TypeScript type definitions
+├── guides/                      # Documentation
+├── tests/                       # Backend test suite
+└── scripts/                     # Build and utility scripts
 ```

-**When working with AI/LLM code:**
- Look in `apps/backend/core/client.py` for the Claude SDK client setup
- Reference `apps/backend/agents/` for working agent implementations
- Check `apps/backend/spec_agents/` for spec creation agent examples
- NEVER use `anthropic.Anthropic()` directly - always use `create_client()` from `core.client`
-
-**Frontend (Electron Desktop App):**
- Built with Electron, React, TypeScript
- AI agents can perform E2E testing using the Electron MCP server
- When bug fixing or implementing features, use the Electron MCP server for automated testing
- See "End-to-End Testing" section below for details
-
-## Commands
+## Commands Quick Reference

 ### Setup
-
-**Requirements:**
- Python 3.12+ (required for backend)
- Node.js (for frontend)
-
 ```bash
-# Install all dependencies from root
-npm run install:all
-
-# Or install separately:
-# Backend (from apps/backend/)
+npm run install:all              # Install all dependencies from root
+# Or separately:
 cd apps/backend && uv venv && uv pip install -r requirements.txt
-
-# Frontend (from apps/frontend/)
 cd apps/frontend && npm install
-
-# Set up OAuth token
-claude setup-token
-# Add to apps/backend/.env: CLAUDE_CODE_OAUTH_TOKEN=your-token
 ```

-### Creating and Running Specs
+### Backend
 ```bash
 cd apps/backend
-
-# Create a spec interactively
-python spec_runner.py --interactive
-
-# Create spec from task description
-python spec_runner.py --task "Add user authentication"
-
-# Force complexity level (simple/standard/complex)
-python spec_runner.py --task "Fix button" --complexity simple
-
-# Run autonomous build
-python run.py --spec 001
-
-# List all specs
-python run.py --list
+python spec_runner.py --interactive            # Create spec interactively
+python spec_runner.py --task "description"      # Create from task
+python run.py --spec 001                        # Run autonomous build
+python run.py --spec 001 --qa                   # Run QA validation
+python run.py --spec 001 --merge                # Merge completed build
+python run.py --list                            # List all specs
 ```

-### Workspace Management
+### Frontend
 ```bash
-cd apps/backend
-
-# Review changes in isolated worktree
-python run.py --spec 001 --review
-
-# Merge completed build into project
-python run.py --spec 001 --merge
-
-# Discard build
-python run.py --spec 001 --discard
-```
-
-### QA Validation
-```bash
-cd apps/backend
-
-# Run QA manually
-python run.py --spec 001 --qa
-
-# Check QA status
-python run.py --spec 001 --qa-status
+cd apps/frontend
+npm run dev              # Dev mode (Electron + Vite HMR)
+npm run build            # Production build
+npm run test             # Vitest unit tests
+npm run test:watch       # Vitest watch mode
+npm run lint             # Biome check
+npm run lint:fix         # Biome auto-fix
+npm run typecheck        # TypeScript strict check
+npm run package          # Package for distribution
 ```

 ### Testing
-```bash
-# Install test dependencies (required first time)
-cd apps/backend && uv pip install -r ../../tests/requirements-test.txt

-# Run all tests (use virtual environment pytest)
-apps/backend/.venv/bin/pytest tests/ -v
-
-# Run single test file
-apps/backend/.venv/bin/pytest tests/test_security.py -v
-
-# Run specific test
-apps/backend/.venv/bin/pytest tests/test_security.py::test_bash_command_validation -v
-
-# Skip slow tests
-apps/backend/.venv/bin/pytest tests/ -m "not slow"
-
-# Or from root
-npm run test:backend
-```
-
-### Spec Validation
-```bash
-python apps/backend/validate_spec.py --spec-dir apps/backend/specs/001-feature --checkpoint all
-```
+| Stack | Command | Tool |
+|-------|---------|------|
+| Backend | `apps/backend/.venv/bin/pytest tests/ -v` | pytest |
+| Frontend unit | `cd apps/frontend && npm test` | Vitest |
+| Frontend E2E | `cd apps/frontend && npm run test:e2e` | Playwright |
+| All backend | `npm run test:backend` (from root) | pytest |

 ### Releases
 ```bash
-# 1. Bump version on your branch (creates commit, no tag)
-node scripts/bump-version.js patch   # 2.8.0 -> 2.8.1
-node scripts/bump-version.js minor   # 2.8.0 -> 2.9.0
-node scripts/bump-version.js major   # 2.8.0 -> 3.0.0
-
-# 2. Push and create PR to main
-git push origin your-branch
-gh pr create --base main
-
-# 3. Merge PR → GitHub Actions automatically:
-#    - Creates tag
-#    - Builds all platforms
-#    - Creates release with changelog
-#    - Updates README
+node scripts/bump-version.js patch|minor|major  # Bump version
+git push && gh pr create --base main             # PR to main triggers release
 ```

-See [RELEASE.md](RELEASE.md) for detailed release process documentation.
+See [RELEASE.md](RELEASE.md) for full release process.

-## Architecture
+## Backend Development

-### Core Pipeline
+### Claude Agent SDK Usage

-**Spec Creation (spec_runner.py)** - Dynamic 3-8 phase pipeline based on task complexity:
- SIMPLE (3 phases): Discovery → Quick Spec → Validate
- STANDARD (6-7 phases): Discovery → Requirements → [Research] → Context → Spec → Plan → Validate
- COMPLEX (8 phases): Full pipeline with Research and Self-Critique phases
+Client: `apps/backend/core/client.py` — `create_client()` returns a configured `ClaudeSDKClient` with security hooks, tool permissions, and MCP server integration.

-**Implementation (run.py → agent.py)** - Multi-session build:
-1. Planner Agent creates subtask-based implementation plan
-2. Coder Agent implements subtasks (can spawn subagents for parallel work)
-3. QA Reviewer validates acceptance criteria (can perform E2E testing via Electron MCP for frontend changes)
-4. QA Fixer resolves issues in a loop (with E2E testing to verify fixes)
+Model and thinking level are user-configurable (via the Electron UI settings or CLI override). Use `phase_config.py` helpers to resolve the correct values:

-### Key Components (apps/backend/)
+```python
+from core.client import create_client
+from phase_config import get_phase_model, get_phase_thinking_budget

-**Core Infrastructure:**
- **core/client.py** - Claude Agent SDK client factory with security hooks and tool permissions
- **core/security.py** - Dynamic command allowlisting based on detected project stack
- **core/auth.py** - OAuth token management for Claude SDK authentication
- **agents/** - Agent implementations (planner, coder, qa_reviewer, qa_fixer)
- **spec_agents/** - Spec creation agents (gatherer, researcher, writer, critic)
+# Resolve model/thinking from user settings (Electron UI or CLI override)
+phase_model = get_phase_model(spec_dir, "coding", cli_model=None)
+phase_thinking = get_phase_thinking_budget(spec_dir, "coding", cli_thinking=None)

-**Memory & Context:**
- **integrations/graphiti/** - Graphiti memory system (mandatory)
-  - `queries_pkg/graphiti.py` - Main GraphitiMemory class
-  - `queries_pkg/client.py` - LadybugDB client wrapper
-  - `queries_pkg/queries.py` - Graph query operations
-  - `queries_pkg/search.py` - Semantic search logic
-  - `queries_pkg/schema.py` - Graph schema definitions
- **graphiti_config.py** - Configuration and validation for Graphiti integration
- **graphiti_providers.py** - Multi-provider factory (OpenAI, Anthropic, Azure, Ollama, Google AI)
- **agents/memory_manager.py** - Session memory orchestration
+client = create_client(
+    project_dir=project_dir,
+    spec_dir=spec_dir,
+    model=phase_model,
+    agent_type="coder",          # planner | coder | qa_reviewer | qa_fixer
+    max_thinking_tokens=phase_thinking,
+)

-**Workspace & Security:**
- **cli/worktree.py** - Git worktree isolation for safe feature development
- **context/project_analyzer.py** - Project stack detection for dynamic tooling
- **auto_claude_tools.py** - Custom MCP tools integration
+# Run agent session (uses context manager + run_agent_session helper)
+async with client:
+    status, response = await run_agent_session(client, prompt, spec_dir)
+```

-**Integrations:**
- **linear_updater.py** - Optional Linear integration for progress tracking
- **runners/github/** - GitHub Issues & PRs automation
- **Electron MCP** - E2E testing integration for QA agents (Chrome DevTools Protocol)
-  - Enabled with `ELECTRON_MCP_ENABLED=true` in `.env`
-  - Allows QA agents to interact with running Electron app
-  - See "End-to-End Testing" section for details
+Working examples: `agents/planner.py`, `agents/coder.py`, `qa/reviewer.py`, `qa/fixer.py`, `spec/`

-### Agent Prompts (apps/backend/prompts/)
+### Agent Prompts (`apps/backend/prompts/`)

 | Prompt | Purpose |
 |--------|---------|
-| planner.md | Creates implementation plan with subtasks |
-| coder.md | Implements individual subtasks |
-| coder_recovery.md | Recovers from stuck/failed subtasks |
-| qa_reviewer.md | Validates acceptance criteria |
-| qa_fixer.md | Fixes QA-reported issues |
-| spec_gatherer.md | Collects user requirements |
-| spec_researcher.md | Validates external integrations |
-| spec_writer.md | Creates spec.md document |
-| spec_critic.md | Self-critique using ultrathink |
+| planner.md | Implementation plan with subtasks |
+| coder.md / coder_recovery.md | Subtask implementation / recovery |
+| qa_reviewer.md / qa_fixer.md | Acceptance validation / issue fixes |
+| spec_gatherer/researcher/writer/critic.md | Spec creation pipeline |
 | complexity_assessor.md | AI-based complexity assessment |

 ### Spec Directory Structure

-Each spec in `.auto-claude/specs/XXX-name/` contains:
- `spec.md` - Feature specification
- `requirements.json` - Structured user requirements
- `context.json` - Discovered codebase context
- `implementation_plan.json` - Subtask-based plan with status tracking
- `qa_report.md` - QA validation results
- `QA_FIX_REQUEST.md` - Issues to fix (when rejected)
+Each spec in `.auto-claude/specs/XXX-name/` contains: `spec.md`, `requirements.json`, `context.json`, `implementation_plan.json`, `qa_report.md`, `QA_FIX_REQUEST.md`

-### Branching & Worktree Strategy
+### Memory System (Graphiti)

-Auto Claude uses git worktrees for isolated builds. All branches stay LOCAL until user explicitly pushes:
+Graph-based semantic memory in `integrations/graphiti/`. Configured through the Electron app's onboarding/settings UI (CLI users can alternatively set `GRAPHITI_ENABLED=true` in `.env`). See [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md#memory-system) for details.

-```
-main (user's branch)
-└── auto-claude/{spec-name}  ← spec branch (isolated worktree)
-```
+## Frontend Development

-**Key principles:**
- ONE branch per spec (`auto-claude/{spec-name}`)
- Parallel work uses subagents (agent decides when to spawn)
- NO automatic pushes to GitHub - user controls when to push
- User reviews in spec worktree (`.worktrees/{spec-name}/`)
- Final merge: spec branch → main (after user approval)
+### Tech Stack

-**Workflow:**
-1. Build runs in isolated worktree on spec branch
-2. Agent implements subtasks (can spawn subagents for parallel work)
-3. User tests feature in `.worktrees/{spec-name}/`
-4. User runs `--merge` to add to their project
-5. User pushes to remote when ready
+React 19, TypeScript (strict), Electron 39, Zustand 5, Tailwind CSS v4, Radix UI, xterm.js 6, Vite 7, Vitest 4, Biome 2, Motion (Framer Motion)

-### Contributing to Upstream
+### Path Aliases (tsconfig.json)

-**CRITICAL: When submitting PRs to AndyMik90/Auto-Claude, always target the `develop` branch, NOT `main`.**
+| Alias | Maps to |
+|-------|---------|
+| `@/*` | `src/renderer/*` |
+| `@shared/*` | `src/shared/*` |
+| `@preload/*` | `src/preload/*` |
+| `@features/*` | `src/renderer/features/*` |
+| `@components/*` | `src/renderer/shared/components/*` |
+| `@hooks/*` | `src/renderer/shared/hooks/*` |
+| `@lib/*` | `src/renderer/shared/lib/*` |

-**Correct workflow for contributions:**
-1. Fetch upstream: `git fetch upstream`
-2. Create feature branch from upstream/develop: `git checkout -b fix/my-fix upstream/develop`
-3. Make changes and commit with sign-off: `git commit -s -m "fix: description"`
-4. Push to your fork: `git push origin fix/my-fix`
-5. Create PR targeting `develop`: `gh pr create --repo AndyMik90/Auto-Claude --base develop`
+### State Management (Zustand)

-**Verify before PR:**
-```bash
-# Ensure only your commits are included
-git log --oneline upstream/develop..HEAD
-```
+All state lives in `src/renderer/stores/`. Key stores:

-### Security Model
+- `project-store.ts` — Active project, project list
+- `task-store.ts` — Tasks/specs management
+- `terminal-store.ts` — Terminal sessions and state
+- `settings-store.ts` — User preferences
+- `github/issues-store.ts`, `github/pr-review-store.ts` — GitHub integration
+- `insights-store.ts`, `roadmap-store.ts`, `kanban-settings-store.ts`

-Three-layer defense:
-1. **OS Sandbox** - Bash command isolation
-2. **Filesystem Permissions** - Operations restricted to project directory
-3. **Command Allowlist** - Dynamic allowlist from project analysis (security.py + project_analyzer.py)
+Main process also has stores: `src/main/project-store.ts`, `src/main/terminal-session-store.ts`

-Security profile cached in `.auto-claude-security.json`.
+### Styling

-### Claude Agent SDK Integration
+- **Tailwind CSS v4** with `@tailwindcss/postcss` plugin
+- **7 color themes** (Default, Dusk, Lime, Ocean, Retro, Neo + more) defined in `src/shared/constants/themes.ts`
+- Each theme has light/dark mode variants via CSS custom properties
+- Utility: `clsx` + `tailwind-merge` via `cn()` helper
+- Component variants: `class-variance-authority` (CVA)

-**CRITICAL: Auto Claude uses the Claude Agent SDK for ALL AI interactions. Never use the Anthropic API directly.**
+### IPC Communication

-**Client Location:** `apps/backend/core/client.py`
+Main ↔ Renderer communication via Electron IPC:
+- **Handlers:** `src/main/ipc-handlers/` — organized by domain (github, gitlab, ideation, context, etc.)
+- **Preload:** `src/preload/` — exposes safe APIs to renderer
+- Pattern: renderer calls via `window.electronAPI.*`, main handles in IPC handler modules

-The `create_client()` function creates a configured `ClaudeSDKClient` instance with:
- Multi-layered security (sandbox, permissions, security hooks)
- Agent-specific tool permissions (planner, coder, qa_reviewer, qa_fixer)
- Dynamic MCP server integration based on project capabilities
- Extended thinking token budget control
+### Agent Management (`src/main/agent/`)

-**Example usage in agents:**
-```python
-from core.client import create_client
+The frontend manages agent lifecycle end-to-end:
+- **`agent-queue.ts`** — Queue routing, prioritization, spec number locking
+- **`agent-process.ts`** — Spawns and manages agent subprocess communication
+- **`agent-state.ts`** — Tracks running agent state and status
+- **`agent-events.ts`** — Agent lifecycle events and state transitions

-# Create SDK client (NOT raw Anthropic API client)
-client = create_client(
-    project_dir=project_dir,
-    spec_dir=spec_dir,
-    model="claude-sonnet-4-5-20250929",
-    agent_type="coder",
-    max_thinking_tokens=None  # or 5000/10000/16000
-)
+### Claude Profile System (`src/main/claude-profile/`)

-# Run agent session
-response = client.create_agent_session(
-    name="coder-agent-session",
-    starting_message="Implement the authentication feature"
-)
-```
+Multi-profile credential management for switching between Claude accounts:
+- **`credential-utils.ts`** — OS credential storage (Keychain/Windows Credential Manager)
+- **`token-refresh.ts`** — OAuth token lifecycle and automatic refresh
+- **`usage-monitor.ts`** — API usage tracking and rate limiting per profile
+- **`profile-scorer.ts`** — Scores profiles by usage and availability

-**Why use the SDK:**
- Pre-configured security (sandbox, allowlists, hooks)
- Automatic MCP server integration (Context7, Linear, Graphiti, Electron, Puppeteer)
- Tool permissions based on agent role
- Session management and recovery
- Unified API across all agent types
+### Terminal System (`src/main/terminal/`)

-**Where to find working examples:**
- `apps/backend/agents/planner.py` - Planner agent
- `apps/backend/agents/coder.py` - Coder agent
- `apps/backend/agents/qa_reviewer.py` - QA reviewer
- `apps/backend/agents/qa_fixer.py` - QA fixer
- `apps/backend/spec_agents/` - Spec creation agents
+Full PTY-based terminal integration:
+- **`pty-daemon.ts`** / **`pty-manager.ts`** — Background PTY process management
+- **`terminal-lifecycle.ts`** — Session creation, cleanup, event handling
+- **`claude-integration-handler.ts`** — Claude SDK integration within terminals
+- Renderer: xterm.js 6 with WebGL, fit, web-links, serialize addons. Store: `terminal-store.ts`

-### Memory System
+## Code Quality

-**Graphiti Memory (Mandatory)** - `integrations/graphiti/`
+### Frontend
+- **Linting:** Biome (`npm run lint` / `npm run lint:fix`)
+- **Type checking:** `npm run typecheck` (strict mode)
+- **Pre-commit:** Husky + lint-staged runs Biome on staged `.ts/.tsx/.js/.jsx/.json`
+- **Testing:** Vitest + React Testing Library + jsdom

-Auto Claude uses Graphiti as its primary memory system with embedded LadybugDB (no Docker required):
+### Backend
+- **Linting:** Ruff
+- **Testing:** pytest (`apps/backend/.venv/bin/pytest tests/ -v`)

- **Graph database with semantic search** - Knowledge graph for cross-session context
- **Session insights** - Patterns, gotchas, discoveries automatically extracted
- **Multi-provider support:**
-  - LLM: OpenAI, Anthropic, Azure OpenAI, Ollama, Google AI (Gemini)
-  - Embedders: OpenAI, Voyage AI, Azure OpenAI, Ollama, Google AI
- **Modular architecture:** (`integrations/graphiti/queries_pkg/`)
-  - `graphiti.py` - Main GraphitiMemory class
-  - `client.py` - LadybugDB client wrapper
-  - `queries.py` - Graph query operations
-  - `search.py` - Semantic search logic
-  - `schema.py` - Graph schema definitions
+## i18n Guidelines

-**Configuration:**
- Set provider credentials in `apps/backend/.env` (see `.env.example`)
- Required env vars: `GRAPHITI_ENABLED=true`, `ANTHROPIC_API_KEY` or other provider keys
- Memory data stored in `.auto-claude/specs/XXX/graphiti/`
+All frontend UI text uses `react-i18next`. Translation files: `apps/frontend/src/shared/i18n/locales/{en,fr}/*.json`

-**Usage in agents:**
-```python
-from integrations.graphiti.memory import get_graphiti_memory
+**Namespaces:** `common`, `navigation`, `settings`, `dialogs`, `tasks`, `errors`, `onboarding`, `welcome`

-memory = get_graphiti_memory(spec_dir, project_dir)
-context = memory.get_context_for_session("Implementing feature X")
-memory.add_session_insight("Pattern: use React hooks for state")
-```
-
-## Development Guidelines
-
-### Frontend Internationalization (i18n)
-
-**CRITICAL: Always use i18n translation keys for all user-facing text in the frontend.**
-
-The frontend uses `react-i18next` for internationalization. All labels, buttons, messages, and user-facing text MUST use translation keys.
-
-**Translation file locations:**
- `apps/frontend/src/shared/i18n/locales/en/*.json` - English translations
- `apps/frontend/src/shared/i18n/locales/fr/*.json` - French translations
-
-**Translation namespaces:**
- `common.json` - Shared labels, buttons, common terms
- `navigation.json` - Sidebar navigation items, sections
- `settings.json` - Settings page content
- `dialogs.json` - Dialog boxes and modals
- `tasks.json` - Task/spec related content
- `errors.json` - Error messages (structured error information with substitution support)
- `onboarding.json` - Onboarding wizard content
- `welcome.json` - Welcome screen content
-
-**Usage pattern:**
 ```tsx
 import { useTranslation } from 'react-i18next';
-
-// In component
 const { t } = useTranslation(['navigation', 'common']);

-// Use translation keys, NOT hardcoded strings
-<span>{t('navigation:items.githubPRs')}</span>  // ✅ CORRECT
-<span>GitHub PRs</span>                          // ❌ WRONG
+<span>{t('navigation:items.githubPRs')}</span>     // CORRECT
+<span>GitHub PRs</span>                             // WRONG
+
+// With interpolation:
+<span>{t('errors:task.parseError', { error })}</span>
 ```

-**Error messages with substitution:**
+When adding new UI text: add keys to ALL language files, use `namespace:section.key` format.

-```tsx
-// For error messages with dynamic content, use interpolation
-const { t } = useTranslation(['errors']);
+## Cross-Platform

-// errors.json: { "task": { "parseError": "Failed to parse: {{error}}" } }
-<span>{t('errors:task.parseError', { error: errorMessage })}</span>
-```
+Supports Windows, macOS, Linux. CI tests all three.

-**When adding new UI text:**
-1. Add the translation key to ALL language files (at minimum: `en/*.json` and `fr/*.json`)
-2. Use `namespace:section.key` format (e.g., `navigation:items.githubPRs`)
-3. Never use hardcoded strings in JSX/TSX files
-
-### Cross-Platform Development
-
-**CRITICAL: This project supports Windows, macOS, and Linux. Platform-specific bugs are the #1 source of breakage.**
-
-#### The Problem
-
-When developers on macOS fix something using Mac-specific assumptions, it breaks on Windows. When Windows developers fix something, it breaks on macOS. This happens because:
-
-1. **CI only tested on Linux** - Platform-specific bugs weren't caught until after merge
-2. **Scattered platform checks** - `process.platform === 'win32'` checks were spread across 50+ files
-3. **Hardcoded paths** - Direct paths like `C:\Program Files` or `/opt/homebrew/bin` throughout code
-
-#### The Solution
-
-**1. Centralized Platform Abstraction**
-
-All platform-specific code now lives in dedicated modules:
-
- **Frontend:** `apps/frontend/src/main/platform/`
- **Backend:** `apps/backend/core/platform/`
-
-**Import from these modules instead of checking `process.platform` directly:**
-
-```typescript
-// ❌ WRONG - Direct platform check
-if (process.platform === 'win32') {
-  // Windows logic
-}
-
-// ✅ CORRECT - Use abstraction
-import { isWindows, getPathDelimiter } from './platform';
-
-if (isWindows()) {
-  // Windows logic
-}
-```
-
-**2. Multi-Platform CI**
-
-CI now tests on **all three platforms** (Windows, macOS, Linux). A PR cannot merge unless all platforms pass:
-
-```yaml
-# .github/workflows/ci.yml
-strategy:
-  matrix:
-    os: [ubuntu-latest, windows-latest, macos-latest]
-```
-
-**3. Platform Module API**
-
-The platform module provides:
+**Platform modules:** `apps/frontend/src/main/platform/` and `apps/backend/core/platform/`

 | Function | Purpose |
 |----------|---------|
 | `isWindows()` / `isMacOS()` / `isLinux()` | OS detection |
-| `getPathDelimiter()` | Get `;` (Windows) or `:` (Unix) |
-| `getExecutableExtension()` | Get `.exe` (Windows) or `` (Unix) |
-| `findExecutable(name)` | Find executables across platforms |
-| `getBinaryDirectories()` | Get platform-specific bin paths |
-| `requiresShell(command)` | Check if .cmd/.bat needs shell on Windows |
+| `getPathDelimiter()` | `;` (Win) or `:` (Unix) |
+| `findExecutable(name)` | Cross-platform executable lookup |
+| `requiresShell(command)` | `.cmd/.bat` shell detection (Win) |

-**4. Path Handling Best Practices**
+Never hardcode paths. Use `findExecutable()` and `joinPaths()`. See [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md#cross-platform-development) for extended guide.

-```typescript
-// ❌ WRONG - Hardcoded Windows path
-const claudePath = 'C:\\Program Files\\Claude\\claude.exe';
+## E2E Testing (Electron MCP)

-// ❌ WRONG - Hardcoded macOS path
-const brewPath = '/opt/homebrew/bin/python3';
+QA agents can interact with the running Electron app via Chrome DevTools Protocol:

-// ❌ WRONG - Manual path joining
-const fullPath = dir + '/subdir/file.txt';
+1. Start app: `npm run dev:debug` (debug mode for AI self-validation via Electron MCP)
+2. Set `ELECTRON_MCP_ENABLED=true` in `apps/backend/.env`
+3. Run QA: `python run.py --spec 001 --qa`

-// ✅ CORRECT - Use platform abstraction
-import { findExecutable, joinPaths } from './platform';
-
-const claudePath = await findExecutable('claude');
-const fullPath = joinPaths(dir, 'subdir', 'file.txt');
-```
-
-**5. Testing Platform-Specific Code**
-
-```typescript
-// Mock process.platform for testing
-import { isWindows } from './platform';
-
-// In tests, use jest.mock or similar
-jest.mock('./platform', () => ({
-  isWindows: () => true  // Simulate Windows
-}));
-```
-
-**6. When You Need Platform-Specific Code**
-
-If you must write platform-specific code:
-
-1. **Add it to the platform module** - Not scattered in your feature code
-2. **Write tests for all platforms** - Mock `process.platform` to test each case
-3. **Use feature detection** - Check for file/path existence, not just OS name
-4. **Document why** - Explain the platform difference in comments
-
-**7. Submitting Platform-Specific Fixes**
-
-When fixing a platform-specific bug:
-
-1. Ensure your fix doesn't break other platforms
-2. Test locally if you have access to other OSs
-3. Rely on CI to catch issues you can't test
-4. Consider adding a test that mocks other platforms
-
-**Example: Adding a New Tool Detection**
-
-```typescript
-// ✅ CORRECT - Add to platform/paths.ts
-export function getMyToolPaths(): string[] {
-  if (isWindows()) {
-    return [
-      joinPaths('C:', 'Program Files', 'MyTool', 'tool.exe'),
-      // ... more Windows paths
-    ];
-  }
-  return [
-    joinPaths('/usr', 'local', 'bin', 'mytool'),
-    // ... more Unix paths
-  ];
-}
-
-// ✅ CORRECT - Use in your code
-import { findExecutable, getMyToolPaths } from './platform';
-
-const toolPath = await findExecutable('mytool', getMyToolPaths());
-```
-
-### End-to-End Testing (Electron App)
-
-**IMPORTANT: When bug fixing or implementing new features in the frontend, AI agents can perform automated E2E testing using the Electron MCP server.**
-
-The Electron MCP server allows QA agents to interact with the running Electron app via Chrome DevTools Protocol:
-
-**Setup:**
-1. Start the Electron app with remote debugging enabled:
-   ```bash
-   npm run dev  # Already configured with --remote-debugging-port=9222
-   ```
-
-2. Enable Electron MCP in `apps/backend/.env`:
-   ```bash
-   ELECTRON_MCP_ENABLED=true
-   ELECTRON_DEBUG_PORT=9222  # Default port
-   ```
-
-**Available Testing Capabilities:**
-
-QA agents (`qa_reviewer` and `qa_fixer`) automatically get access to Electron MCP tools:
-
-1. **Window Management**
-   - `mcp__electron__get_electron_window_info` - Get info about running windows
-   - `mcp__electron__take_screenshot` - Capture screenshots for visual verification
-
-2. **UI Interaction**
-   - `mcp__electron__send_command_to_electron` with commands:
-     - `click_by_text` - Click buttons/links by visible text
-     - `click_by_selector` - Click elements by CSS selector
-     - `fill_input` - Fill form fields by placeholder or selector
-     - `select_option` - Select dropdown options
-     - `send_keyboard_shortcut` - Send keyboard shortcuts (Enter, Ctrl+N, etc.)
-     - `navigate_to_hash` - Navigate to hash routes (#settings, #create, etc.)
-
-3. **Page Inspection**
-   - `get_page_structure` - Get organized overview of page elements
-   - `debug_elements` - Get debugging info about buttons and forms
-   - `verify_form_state` - Check form state and validation
-   - `eval` - Execute custom JavaScript code
-
-4. **Logging**
-   - `mcp__electron__read_electron_logs` - Read console logs for debugging
-
-**Example E2E Test Flow:**
-
-```python
-# 1. Agent takes screenshot to see current state
-agent: "Take a screenshot to see the current UI"
-# Uses: mcp__electron__take_screenshot
-
-# 2. Agent inspects page structure
-agent: "Get page structure to find available buttons"
-# Uses: mcp__electron__send_command_to_electron (command: "get_page_structure")
-
-# 3. Agent clicks a button to navigate
-agent: "Click the 'Create New Spec' button"
-# Uses: mcp__electron__send_command_to_electron (command: "click_by_text", args: {text: "Create New Spec"})
-
-# 4. Agent fills out a form
-agent: "Fill the task description field"
-# Uses: mcp__electron__send_command_to_electron (command: "fill_input", args: {placeholder: "Describe your task", value: "Add login feature"})
-
-# 5. Agent submits and verifies
-agent: "Click Submit and verify success"
-# Uses: click_by_text → take_screenshot → verify result
-```
-
-**When to Use E2E Testing:**
-
- **Bug Fixes**: Reproduce the bug, apply fix, verify it's resolved
- **New Features**: Implement feature, test the UI flow end-to-end
- **UI Changes**: Verify visual changes and interactions work correctly
- **Form Validation**: Test form submission, validation, error handling
-
-**Configuration in `core/client.py`:**
-
-The client automatically enables Electron MCP tools for QA agents when:
- Project is detected as Electron (`is_electron` capability)
- `ELECTRON_MCP_ENABLED=true` is set
- Agent type is `qa_reviewer` or `qa_fixer`
-
-**Note:** Screenshots are automatically compressed (1280x720, quality 60, JPEG) to stay under Claude SDK's 1MB JSON message buffer limit.
+Tools: `take_screenshot`, `click_by_text`, `fill_input`, `get_page_structure`, `send_keyboard_shortcut`, `eval`. See [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md#end-to-end-testing) for full capabilities.

 ## Running the Application

-**As a standalone CLI tool**:
 ```bash
-cd apps/backend
-python run.py --spec 001
+# CLI only
+cd apps/backend && python run.py --spec 001
+
+# Desktop app
+npm start          # Production build + run
+npm run dev        # Development mode with HMR
+
+# Project data: .auto-claude/specs/ (gitignored)
 ```
-
-**With the Electron frontend**:
-```bash
-npm start        # Build and run desktop app
-npm run dev      # Run in development mode (includes --remote-debugging-port=9222 for E2E testing)
-```
-
-**For E2E Testing with QA Agents:**
-1. Start the Electron app: `npm run dev`
-2. Enable Electron MCP in `apps/backend/.env`: `ELECTRON_MCP_ENABLED=true`
-3. Run QA: `python run.py --spec 001 --qa`
-4. QA agents will automatically interact with the running app for testing
-
-**Project data storage:**
- `.auto-claude/specs/` - Per-project data (specs, plans, QA reports, memory) - gitignored
@@ -2,20 +2,41 @@

 Thank you for your interest in contributing to Auto Claude! This document provides guidelines and instructions for contributing to the project.

+## How to Contribute
+
+| What you want to do | Where to start |
+|----------------------|----------------|
+| Bug fixes & small improvements | Open a PR directly |
+| New features / architecture changes | Start a [GitHub Discussion](https://github.com/AndyMik90/Auto-Claude/discussions) or ask in [Discord](https://discord.com/channels/1448614759996854284/1451298184612548779) first |
+| Questions & setup help | [Discord #setup-help](https://discord.com/channels/1448614759996854284/1451298184612548779) |
+
+## AI-Assisted Contributions
+
+PRs built with AI tools (Claude, Codex, Copilot, etc.) are welcome here -- given what this project does, it would be odd if they weren't.
+
+That said, we've seen AI-generated PRs that introduce regressions because the contributor didn't verify what the code actually does. To keep quality high, we ask that AI-assisted PRs include the following:
+
+- **Flag it** -- mention AI assistance in the PR description (the PR template has a section for this)
+- **State your testing level** -- untested, lightly tested, or fully tested
+- **Share context if you can** -- prompts or session logs help reviewers understand intent
+- **Confirm you understand the code** -- you should be able to describe what the PR does and how the underlying code works
+
+AI-assisted PRs go through the same review process as any other contribution. Transparency just helps reviewers know where to look more carefully.
+
 ## Table of Contents

+- [How to Contribute](#how-to-contribute)
+- [AI-Assisted Contributions](#ai-assisted-contributions)
 - [Contributor License Agreement (CLA)](#contributor-license-agreement-cla)
 - [Prerequisites](#prerequisites)
 - [Quick Start](#quick-start)
 - [Development Setup](#development-setup)
-  - [Python Backend](#python-backend)
-  - [Electron Frontend](#electron-frontend)
- [Running from Source](#running-from-source)
 - [Pre-commit Hooks](#pre-commit-hooks)
 - [Code Style](#code-style)
 - [Testing](#testing)
 - [Continuous Integration](#continuous-integration)
 - [Git Workflow](#git-workflow)
+  - [Working with Forks](#working-with-forks)
  - [Branch Overview](#branch-overview)
  - [Main Branches](#main-branches)
  - [Supporting Branches](#supporting-branches)
@@ -150,92 +171,40 @@ npm start
 The project consists of two main components:

 1. **Python Backend** (`apps/backend/`) - The core autonomous coding framework
-2. **Electron Frontend** (`apps/frontend/`) - Optional desktop UI
+2. **Electron Frontend** (`apps/frontend/`) - Desktop UI

-### Python Backend
-
-The recommended way is to use `npm run install:backend` (or `npm run install:all` from the root), which automatically installs both runtime and test dependencies. You can also set up manually:
+From the repository root, two commands handle everything:

 ```bash
-# Navigate to the backend directory
-cd apps/backend
+# Install all dependencies (Python backend + Electron frontend)
+npm run install:all

-# Create virtual environment
-# Windows:
-py -3.12 -m venv .venv
-.venv\Scripts\activate
-
-# macOS/Linux:
-python3.12 -m venv .venv
-source .venv/bin/activate
-
-# Install dependencies
-pip install -r requirements.txt
-
-# Install test dependencies
-pip install -r ../../tests/requirements-test.txt
-
-# Set up environment
-cp .env.example .env
-# Edit .env and add your CLAUDE_CODE_OAUTH_TOKEN (get it via: claude setup-token)
-```
-
-### Electron Frontend
-
-```bash
-# Navigate to the frontend directory
-cd apps/frontend
-
-# Install dependencies
-npm install
-
-# Start development server
+# Start development mode (hot reload)
 npm run dev
-
-# Build for production
-npm run build
-
-# Package for distribution
-npm run package
 ```

-## Running from Source
-
-If you want to run Auto Claude from source (for development or testing unreleased features), follow these steps:
-
-### Step 1: Clone and Set Up
+`npm run install:all` automatically:
+- Detects Python 3.12+ on your system
+- Creates a virtual environment (`apps/backend/.venv`)
+- Installs backend runtime and test dependencies
+- Copies `.env.example` to `.env` (if not already present)
+- Installs frontend npm dependencies

+After install, configure your credentials in `apps/backend/.env`:
 ```bash
-git clone https://github.com/AndyMik90/Auto-Claude.git
-cd Auto-Claude/apps/backend
+# Get your Claude Code OAuth token
+claude setup-token

-# Using uv (recommended)
-uv venv && uv pip install -r requirements.txt
-
-# Or using standard Python
-python3 -m venv .venv
-source .venv/bin/activate  # On Windows: .venv\Scripts\activate
-pip install -r requirements.txt
-
-# Set up environment
-cd apps/backend
-cp .env.example .env
-# Edit .env and add your CLAUDE_CODE_OAUTH_TOKEN (get it via: claude setup-token)
+# Then edit apps/backend/.env with your token and any other provider keys
 ```

-### Step 2: Run the Desktop UI
+### Other Useful Commands

 ```bash
-cd ../frontend
-
-# Install dependencies
-npm install
-
-# Development mode (hot reload)
-npm run dev
-
-# Or production build
-npm run build && npm run start
+npm start              # Build and run production
+npm run build          # Build frontend for production
+npm run package        # Package for distribution
+npm run test:backend   # Run Python tests
 ```

 <details>
@@ -357,6 +326,64 @@ export default function(props) {
 - End files with a newline
 - Keep line length under 100 characters when practical

+### File Encoding (Python)
+
+**Always specify `encoding="utf-8"` for text file operations** to ensure Windows compatibility.
+
+Windows Python defaults to `cp1252` encoding instead of UTF-8, causing errors with:
+- Emoji (🚀, ✅, ❌)
+- International characters (ñ, é, 中文, العربية)
+- Special symbols (™, ©, ®)
+
+**DO:**
+
+```python
+# Reading files
+with open(path, encoding="utf-8") as f:
+    content = f.read()
+
+# Writing files
+with open(path, "w", encoding="utf-8") as f:
+    f.write(content)
+
+# Path methods
+from pathlib import Path
+content = Path(file).read_text(encoding="utf-8")
+Path(file).write_text(content, encoding="utf-8")
+
+# JSON files - reading
+import json
+with open(path, encoding="utf-8") as f:
+    data = json.load(f)
+
+# JSON files - writing
+with open(path, "w", encoding="utf-8") as f:
+    json.dump(data, f, ensure_ascii=False, indent=2)
+```
+
+**DON'T:**
+
+```python
+# Wrong - platform-dependent encoding
+with open(path) as f:
+    content = f.read()
+
+# Wrong - Path methods without encoding
+content = Path(file).read_text()
+
+# Wrong - encoding on json.dump (not open!)
+json.dump(data, f, encoding="utf-8")  # ERROR
+```
+
+**Binary files - NO encoding:**
+
+```python
+with open(path, "rb") as f:  # Correct
+    data = f.read()
+```
+
+Our pre-commit hooks automatically check for missing encoding parameters. See [PR #782](https://github.com/AndyMik90/Auto-Claude/pull/782) for the comprehensive encoding fix and [guides/windows-development.md](guides/windows-development.md) for Windows-specific development guidance.
+
 ## Testing

 ### Python Tests
@@ -459,6 +486,72 @@ npm run typecheck

 We use a **Git Flow** branching strategy to manage releases and parallel development.

+### Working with Forks
+
+When contributing to Auto Claude, you'll typically fork the repository first. Proper fork configuration is essential to avoid sync issues.
+
+#### Initial Fork Setup
+
+```bash
+# 1. Fork on GitHub (click the Fork button on the repo page)
+
+# 2. Clone YOUR fork (not the original repo)
+git clone https://github.com/YOUR-USERNAME/Auto-Claude.git
+cd Auto-Claude
+
+# 3. Verify your remotes point to YOUR fork
+git remote -v
+# Should show:
+# origin  https://github.com/YOUR-USERNAME/Auto-Claude.git (fetch)
+# origin  https://github.com/YOUR-USERNAME/Auto-Claude.git (push)
+
+# 4. Add upstream remote to sync with the original repo
+git remote add upstream https://github.com/AndyMik90/Auto-Claude.git
+```
+
+#### Keeping Your Fork Updated
+
+```bash
+# Fetch latest changes from upstream
+git fetch upstream
+
+# Sync your develop branch with upstream
+git checkout develop
+git merge upstream/develop
+git push origin develop
+```
+
+#### Converting a Fork to Standalone
+
+> ⚠️ **Common Issue:** After making a fork standalone (e.g., disconnecting from the original repo on GitHub), your local git configuration may still reference the original forked repository, causing push/pull issues.
+
+If you convert your fork to a standalone repository:
+
+```bash
+# 1. Update origin to point to your standalone repo
+git remote set-url origin https://github.com/YOUR-USERNAME/Your-Standalone-Repo.git
+
+# 2. Remove the upstream remote (no longer applicable)
+git remote remove upstream
+
+# 3. Verify your configuration
+git remote -v
+# Should only show your standalone repo as origin
+
+# 4. Update your default branch tracking if needed
+git branch --set-upstream-to=origin/main main
+git branch --set-upstream-to=origin/develop develop
+```
+
+#### Troubleshooting Fork Issues
+
+| Problem | Cause | Solution |
+|---------|-------|----------|
+| `Permission denied` on push | Origin points to upstream repo | `git remote set-url origin <your-fork-url>` |
+| `Repository not found` | Fork was deleted or made standalone | Update remote URL to current repo location |
+| Can't push to develop | Local branch tracks wrong remote | `git branch --set-upstream-to=origin/develop` |
+| Commits show wrong author | Git config not set | `git config user.email "you@example.com"` |
+
 ### Branch Overview

 ```
@@ -27,7 +27,7 @@
 | **macOS (Intel)** | [Auto-Claude-2.7.5-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.5/Auto-Claude-2.7.5-darwin-x64.dmg) |
 | **Linux** | [Auto-Claude-2.7.5-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.5/Auto-Claude-2.7.5-linux-x86_64.AppImage) |
 | **Linux (Debian)** | [Auto-Claude-2.7.5-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.5/Auto-Claude-2.7.5-linux-amd64.deb) |
-| **Linux (Flatpak)** | [Auto-Claude-2.7.4-linux-x86_64.flatpak](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.4/Auto-Claude-2.7.4-linux-x86_64.flatpak) |
+| **Linux (Flatpak)** | [Auto-Claude-2.7.5-linux-x86_64.flatpak](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.5/Auto-Claude-2.7.5-linux-x86_64.flatpak) |
 <!-- STABLE_DOWNLOADS_END -->

 ### Beta Release
@@ -35,18 +35,18 @@
 > ⚠️ Beta releases may contain bugs and breaking changes. [View all releases](https://github.com/AndyMik90/Auto-Claude/releases)

 <!-- BETA_VERSION_BADGE -->
-[![Beta](https://img.shields.io/badge/beta-2.7.2--beta.10-orange?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.2-beta.10)
+[![Beta](https://img.shields.io/badge/beta-2.7.6--beta.2-orange?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.6-beta.2)
 <!-- BETA_VERSION_BADGE_END -->

 <!-- BETA_DOWNLOADS -->
 | Platform | Download |
 |----------|----------|
-| **Windows** | [Auto-Claude-2.7.2-beta.10-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-win32-x64.exe) |
-| **macOS (Apple Silicon)** | [Auto-Claude-2.7.2-beta.10-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-darwin-arm64.dmg) |
-| **macOS (Intel)** | [Auto-Claude-2.7.2-beta.10-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-darwin-x64.dmg) |
-| **Linux** | [Auto-Claude-2.7.2-beta.10-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-linux-x86_64.AppImage) |
-| **Linux (Debian)** | [Auto-Claude-2.7.2-beta.10-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-linux-amd64.deb) |
-| **Linux (Flatpak)** | [Auto-Claude-2.7.2-beta.10-linux-x86_64.flatpak](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.2-beta.10/Auto-Claude-2.7.2-beta.10-linux-x86_64.flatpak) |
+| **Windows** | [Auto-Claude-2.7.6-beta.2-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.2/Auto-Claude-2.7.6-beta.2-win32-x64.exe) |
+| **macOS (Apple Silicon)** | [Auto-Claude-2.7.6-beta.2-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.2/Auto-Claude-2.7.6-beta.2-darwin-arm64.dmg) |
+| **macOS (Intel)** | [Auto-Claude-2.7.6-beta.2-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.2/Auto-Claude-2.7.6-beta.2-darwin-x64.dmg) |
+| **Linux** | [Auto-Claude-2.7.6-beta.2-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.2/Auto-Claude-2.7.6-beta.2-linux-x86_64.AppImage) |
+| **Linux (Debian)** | [Auto-Claude-2.7.6-beta.2-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.2/Auto-Claude-2.7.6-beta.2-linux-amd64.deb) |
+| **Linux (Flatpak)** | [Auto-Claude-2.7.6-beta.2-linux-x86_64.flatpak](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.2/Auto-Claude-2.7.6-beta.2-linux-x86_64.flatpak) |
 <!-- BETA_DOWNLOADS_END -->

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

-Set your Claude API token in `.env`:
-```
-CLAUDE_CODE_OAUTH_TOKEN=your-token-here
+Authenticate with Claude Code (token auto-saved to Keychain):
+```bash
+claude
+# Type: /login
+# Press Enter to open browser
 ```

-Get your token by running: `claude setup-token`
+Token is auto-detected from macOS Keychain / Windows Credential Manager.

 ### 3. Run

@@ -19,5 +19,5 @@ Quick Start:
 See README.md for full documentation.
 """

-__version__ = "2.7.5"
+__version__ = "2.7.6-beta.2"
 __author__ = "Auto Claude Team"
@@ -6,6 +6,7 @@ Shared imports, types, and constants used across agent modules.
 """

 import logging
+import re

 # Configure logging
 logger = logging.getLogger(__name__)
@@ -13,3 +14,83 @@ logger = logging.getLogger(__name__)
 # Configuration constants
 AUTO_CONTINUE_DELAY_SECONDS = 3
 HUMAN_INTERVENTION_FILE = "PAUSE"
+
+# Retry configuration for 400 tool concurrency errors
+MAX_CONCURRENCY_RETRIES = 5  # Maximum number of retries for tool concurrency errors
+INITIAL_RETRY_DELAY_SECONDS = (
+    2  # Initial retry delay (doubles each retry: 2s, 4s, 8s, 16s, 32s)
+)
+MAX_RETRY_DELAY_SECONDS = 32  # Cap retry delay at 32 seconds
+
+# Pause file constants for intelligent error recovery
+# These files signal pause/resume between frontend and backend
+RATE_LIMIT_PAUSE_FILE = "RATE_LIMIT_PAUSE"  # Created when rate limited
+AUTH_FAILURE_PAUSE_FILE = "AUTH_PAUSE"  # Created when auth fails
+RESUME_FILE = "RESUME"  # Created by frontend to signal resume
+
+# Maximum time to wait for rate limit reset (2 hours)
+# If reset time is beyond this, task should fail rather than wait indefinitely
+MAX_RATE_LIMIT_WAIT_SECONDS = 7200
+
+# Wait intervals for pause/resume checking
+RATE_LIMIT_CHECK_INTERVAL_SECONDS = (
+    30  # Check for RESUME file every 30 seconds during rate limit wait
+)
+AUTH_RESUME_CHECK_INTERVAL_SECONDS = 10  # Check for re-authentication every 10 seconds
+AUTH_RESUME_MAX_WAIT_SECONDS = 86400  # Maximum wait for re-authentication (24 hours)
+
+
+def sanitize_error_message(error_message: str, max_length: int = 500) -> str:
+    """
+    Sanitize error messages to remove potentially sensitive information.
+
+    Redacts:
+    - API keys (sk-..., key-...)
+    - Bearer tokens
+    - Token/secret values
+
+    Args:
+        error_message: The raw error message to sanitize
+        max_length: Maximum length to truncate to (default 500)
+
+    Returns:
+        Sanitized and truncated error message
+    """
+    if not error_message:
+        return ""
+
+    # Redact patterns that look like API keys or tokens
+    # Pattern: sk-... (OpenAI/Anthropic keys like sk-ant-api03-...)
+    sanitized = re.sub(
+        r"\bsk-[a-zA-Z0-9._\-]{20,}\b", "[REDACTED_API_KEY]", error_message
+    )
+
+    # Pattern: key-... (generic API keys)
+    sanitized = re.sub(r"\bkey-[a-zA-Z0-9._\-]{20,}\b", "[REDACTED_API_KEY]", sanitized)
+
+    # Pattern: Bearer ... (bearer tokens)
+    sanitized = re.sub(
+        r"\bBearer\s+[a-zA-Z0-9._\-]{20,}\b", "Bearer [REDACTED_TOKEN]", sanitized
+    )
+
+    # Pattern: token= or token: followed by long strings
+    sanitized = re.sub(
+        r"(token[=:]\s*)[a-zA-Z0-9._\-]{20,}\b",
+        r"\1[REDACTED_TOKEN]",
+        sanitized,
+        flags=re.IGNORECASE,
+    )
+
+    # Pattern: secret= or secret: followed by strings
+    sanitized = re.sub(
+        r"(secret[=:]\s*)[a-zA-Z0-9._\-]{20,}\b",
+        r"\1[REDACTED_SECRET]",
+        sanitized,
+        flags=re.IGNORECASE,
+    )
+
+    # Truncate to max length
+    if len(sanitized) > max_length:
+        sanitized = sanitized[:max_length] + "..."
+
+    return sanitized
@@ -10,6 +10,7 @@ Handles session memory storage using dual-layer approach:
 import logging
 from pathlib import Path

+from core.sentry import capture_exception
 from debug import (
    debug,
    debug_detailed,
@@ -116,12 +117,15 @@ async def get_graphiti_context(

    memory = None
    try:
-        # Use centralized helper for GraphitiMemory instantiation
-        memory = get_graphiti_memory(spec_dir, project_dir)
+        # Use centralized helper for GraphitiMemory instantiation (async)
+        memory = await get_graphiti_memory(spec_dir, project_dir)
        if memory is None:
            if is_debug_enabled():
-                debug_warning("memory", "GraphitiMemory not available")
+                debug_warning(
+                    "memory", "GraphitiMemory not available for context retrieval"
+                )
            return None
+
        # Build search query from subtask description
        subtask_desc = subtask.get("description", "")
        subtask_id = subtask.get("id", "")
@@ -228,6 +232,15 @@ async def get_graphiti_context(
        logger.warning(f"Failed to get Graphiti context: {e}")
        if is_debug_enabled():
            debug_error("memory", "Graphiti context retrieval failed", error=str(e))
+        # Capture exception to Sentry with full context
+        capture_exception(
+            e,
+            operation="get_graphiti_context",
+            subtask_id=subtask.get("id", "unknown"),
+            subtask_desc=subtask.get("description", "")[:200],
+            spec_dir=str(spec_dir),
+            project_dir=str(project_dir),
+        )
        return None
    finally:
        # Always close the memory connection (swallow exceptions to avoid overriding)
@@ -324,21 +337,16 @@ async def save_session_memory(

        memory = None
        try:
-            # Use centralized helper for GraphitiMemory instantiation
-            memory = get_graphiti_memory(spec_dir, project_dir)
+            # Use centralized helper for GraphitiMemory instantiation (async)
+            memory = await get_graphiti_memory(spec_dir, project_dir)
            if memory is None:
                if is_debug_enabled():
                    debug_warning("memory", "GraphitiMemory not available")
-                # Continue to file-based fallback
-            else:
-                if is_debug_enabled():
-                    debug_detailed(
+                    debug(
                        "memory",
-                        "GraphitiMemory instance created",
-                        is_enabled=memory.is_enabled,
-                        group_id=getattr(memory, "group_id", "unknown"),
+                        "get_graphiti_memory() returned None - this usually means Graphiti is disabled or provider config is invalid",
                    )
-
+                # Continue to file-based fallback
            if memory is not None and memory.is_enabled:
                if is_debug_enabled():
                    debug("memory", "Saving to Graphiti...")
@@ -393,6 +401,17 @@ async def save_session_memory(
            logger.warning(f"Graphiti save failed: {e}, falling back to file-based")
            if is_debug_enabled():
                debug_error("memory", "Graphiti save failed", error=str(e))
+            # Capture exception to Sentry with full context
+            capture_exception(
+                e,
+                operation="save_session_memory_graphiti",
+                subtask_id=subtask_id,
+                session_num=session_num,
+                success=success,
+                subtasks_completed=subtasks_completed,
+                spec_dir=str(spec_dir),
+                project_dir=str(project_dir),
+            )
        finally:
            # Always close the memory connection (swallow exceptions to avoid overriding)
            if memory is not None:
@@ -438,6 +457,17 @@ async def save_session_memory(
        logger.error(f"File-based memory save also failed: {e}")
        if is_debug_enabled():
            debug_error("memory", "File-based memory save FAILED", error=str(e))
+        # Capture exception to Sentry with full context
+        capture_exception(
+            e,
+            operation="save_session_memory_file",
+            subtask_id=subtask_id,
+            session_num=session_num,
+            success=success,
+            subtasks_completed=subtasks_completed,
+            spec_dir=str(spec_dir),
+            project_dir=str(project_dir),
+        )
        return False, "none"


@@ -1,183 +1,183 @@
-"""
-Planner Agent Module
-====================
-
-Handles follow-up planner sessions for adding new subtasks to completed specs.
-"""
-
-import logging
-from pathlib import Path
-
-from core.client import create_client
-from phase_config import get_phase_model, get_phase_thinking_budget
-from phase_event import ExecutionPhase, emit_phase
-from task_logger import (
-    LogPhase,
-    get_task_logger,
-)
-from ui import (
-    BuildState,
-    Icons,
-    StatusManager,
-    bold,
-    box,
-    highlight,
-    icon,
-    muted,
-    print_status,
-)
-
-from .session import run_agent_session
-
-logger = logging.getLogger(__name__)
-
-
-async def run_followup_planner(
-    project_dir: Path,
-    spec_dir: Path,
-    model: str,
-    verbose: bool = False,
-) -> bool:
-    """
-    Run the follow-up planner to add new subtasks to a completed spec.
-
-    This is a simplified version of run_autonomous_agent that:
-    1. Creates a client
-    2. Loads the followup planner prompt
-    3. Runs a single planning session
-    4. Returns after the plan is updated (doesn't enter coding loop)
-
-    The planner agent will:
-    - Read FOLLOWUP_REQUEST.md for the new task
-    - Read the existing implementation_plan.json
-    - Add new phase(s) with pending subtasks
-    - Update the plan status back to in_progress
-
-    Args:
-        project_dir: Root directory for the project
-        spec_dir: Directory containing the completed spec
-        model: Claude model to use
-        verbose: Whether to show detailed output
-
-    Returns:
-        bool: True if planning completed successfully
-    """
-    from implementation_plan import ImplementationPlan
-    from prompts import get_followup_planner_prompt
-
-    # Initialize status manager for ccstatusline
-    status_manager = StatusManager(project_dir)
-    status_manager.set_active(spec_dir.name, BuildState.PLANNING)
-    emit_phase(ExecutionPhase.PLANNING, "Follow-up planning")
-
-    # Initialize task logger for persistent logging
-    task_logger = get_task_logger(spec_dir)
-
-    # Show header
-    content = [
-        bold(f"{icon(Icons.GEAR)} FOLLOW-UP PLANNER SESSION"),
-        "",
-        f"Spec: {highlight(spec_dir.name)}",
-        muted("Adding follow-up work to completed spec."),
-        "",
-        muted("The agent will read your FOLLOWUP_REQUEST.md and add new subtasks."),
-    ]
-    print()
-    print(box(content, width=70, style="heavy"))
-    print()
-
-    # Start planning phase in task logger
-    if task_logger:
-        task_logger.start_phase(LogPhase.PLANNING, "Starting follow-up planning...")
-        task_logger.set_session(1)
-
-    # Create client with phase-specific model and thinking budget
-    # Respects task_metadata.json configuration when no CLI override
-    planning_model = get_phase_model(spec_dir, "planning", model)
-    planning_thinking_budget = get_phase_thinking_budget(spec_dir, "planning")
-    client = create_client(
-        project_dir,
-        spec_dir,
-        planning_model,
-        max_thinking_tokens=planning_thinking_budget,
-    )
-
-    # Generate follow-up planner prompt
-    prompt = get_followup_planner_prompt(spec_dir)
-
-    print_status("Running follow-up planner...", "progress")
-    print()
-
-    try:
-        # Run single planning session
-        async with client:
-            status, response = await run_agent_session(
-                client, prompt, spec_dir, verbose, phase=LogPhase.PLANNING
-            )
-
-        # End planning phase in task logger
-        if task_logger:
-            task_logger.end_phase(
-                LogPhase.PLANNING,
-                success=(status != "error"),
-                message="Follow-up planning session completed",
-            )
-
-        if status == "error":
-            print()
-            print_status("Follow-up planning failed", "error")
-            status_manager.update(state=BuildState.ERROR)
-            return False
-
-        # Verify the plan was updated (should have pending subtasks now)
-        plan_file = spec_dir / "implementation_plan.json"
-        if plan_file.exists():
-            plan = ImplementationPlan.load(plan_file)
-
-            # Check if there are any pending subtasks
-            all_subtasks = [c for p in plan.phases for c in p.subtasks]
-            pending_subtasks = [c for c in all_subtasks if c.status.value == "pending"]
-
-            if pending_subtasks:
-                # Reset the plan status to in_progress (in case planner didn't)
-                plan.reset_for_followup()
-                await plan.async_save(plan_file)
-
-                print()
-                content = [
-                    bold(f"{icon(Icons.SUCCESS)} FOLLOW-UP PLANNING COMPLETE"),
-                    "",
-                    f"New pending subtasks: {highlight(str(len(pending_subtasks)))}",
-                    f"Total subtasks: {len(all_subtasks)}",
-                    "",
-                    muted("Next steps:"),
-                    f"  Run: {highlight(f'python auto-claude/run.py --spec {spec_dir.name}')}",
-                ]
-                print(box(content, width=70, style="heavy"))
-                print()
-                status_manager.update(state=BuildState.PAUSED)
-                return True
-            else:
-                print()
-                print_status(
-                    "Warning: No pending subtasks found after planning", "warning"
-                )
-                print(muted("The planner may not have added new subtasks."))
-                print(muted("Check implementation_plan.json manually."))
-                status_manager.update(state=BuildState.PAUSED)
-                return False
-        else:
-            print()
-            print_status(
-                "Error: implementation_plan.json not found after planning", "error"
-            )
-            status_manager.update(state=BuildState.ERROR)
-            return False
-
-    except Exception as e:
-        print()
-        print_status(f"Follow-up planning error: {e}", "error")
-        if task_logger:
-            task_logger.log_error(f"Follow-up planning error: {e}", LogPhase.PLANNING)
-        status_manager.update(state=BuildState.ERROR)
-        return False
+"""
+Planner Agent Module
+====================
+
+Handles follow-up planner sessions for adding new subtasks to completed specs.
+"""
+
+import logging
+from pathlib import Path
+
+from core.client import create_client
+from phase_config import get_phase_model, get_phase_thinking_budget
+from phase_event import ExecutionPhase, emit_phase
+from task_logger import (
+    LogPhase,
+    get_task_logger,
+)
+from ui import (
+    BuildState,
+    Icons,
+    StatusManager,
+    bold,
+    box,
+    highlight,
+    icon,
+    muted,
+    print_status,
+)
+
+from .session import run_agent_session
+
+logger = logging.getLogger(__name__)
+
+
+async def run_followup_planner(
+    project_dir: Path,
+    spec_dir: Path,
+    model: str,
+    verbose: bool = False,
+) -> bool:
+    """
+    Run the follow-up planner to add new subtasks to a completed spec.
+
+    This is a simplified version of run_autonomous_agent that:
+    1. Creates a client
+    2. Loads the followup planner prompt
+    3. Runs a single planning session
+    4. Returns after the plan is updated (doesn't enter coding loop)
+
+    The planner agent will:
+    - Read FOLLOWUP_REQUEST.md for the new task
+    - Read the existing implementation_plan.json
+    - Add new phase(s) with pending subtasks
+    - Update the plan status back to in_progress
+
+    Args:
+        project_dir: Root directory for the project
+        spec_dir: Directory containing the completed spec
+        model: Claude model to use
+        verbose: Whether to show detailed output
+
+    Returns:
+        bool: True if planning completed successfully
+    """
+    from implementation_plan import ImplementationPlan
+    from prompts import get_followup_planner_prompt
+
+    # Initialize status manager for ccstatusline
+    status_manager = StatusManager(project_dir)
+    status_manager.set_active(spec_dir.name, BuildState.PLANNING)
+    emit_phase(ExecutionPhase.PLANNING, "Follow-up planning")
+
+    # Initialize task logger for persistent logging
+    task_logger = get_task_logger(spec_dir)
+
+    # Show header
+    content = [
+        bold(f"{icon(Icons.GEAR)} FOLLOW-UP PLANNER SESSION"),
+        "",
+        f"Spec: {highlight(spec_dir.name)}",
+        muted("Adding follow-up work to completed spec."),
+        "",
+        muted("The agent will read your FOLLOWUP_REQUEST.md and add new subtasks."),
+    ]
+    print()
+    print(box(content, width=70, style="heavy"))
+    print()
+
+    # Start planning phase in task logger
+    if task_logger:
+        task_logger.start_phase(LogPhase.PLANNING, "Starting follow-up planning...")
+        task_logger.set_session(1)
+
+    # Create client with phase-specific model and thinking budget
+    # Respects task_metadata.json configuration when no CLI override
+    planning_model = get_phase_model(spec_dir, "planning", model)
+    planning_thinking_budget = get_phase_thinking_budget(spec_dir, "planning")
+    client = create_client(
+        project_dir,
+        spec_dir,
+        planning_model,
+        max_thinking_tokens=planning_thinking_budget,
+    )
+
+    # Generate follow-up planner prompt
+    prompt = get_followup_planner_prompt(spec_dir)
+
+    print_status("Running follow-up planner...", "progress")
+    print()
+
+    try:
+        # Run single planning session
+        async with client:
+            status, response, error_info = await run_agent_session(
+                client, prompt, spec_dir, verbose, phase=LogPhase.PLANNING
+            )
+
+        # End planning phase in task logger
+        if task_logger:
+            task_logger.end_phase(
+                LogPhase.PLANNING,
+                success=(status != "error"),
+                message="Follow-up planning session completed",
+            )
+
+        if status == "error":
+            print()
+            print_status("Follow-up planning failed", "error")
+            status_manager.update(state=BuildState.ERROR)
+            return False
+
+        # Verify the plan was updated (should have pending subtasks now)
+        plan_file = spec_dir / "implementation_plan.json"
+        if plan_file.exists():
+            plan = ImplementationPlan.load(plan_file)
+
+            # Check if there are any pending subtasks
+            all_subtasks = [c for p in plan.phases for c in p.subtasks]
+            pending_subtasks = [c for c in all_subtasks if c.status.value == "pending"]
+
+            if pending_subtasks:
+                # Reset the plan status to in_progress (in case planner didn't)
+                plan.reset_for_followup()
+                await plan.async_save(plan_file)
+
+                print()
+                content = [
+                    bold(f"{icon(Icons.SUCCESS)} FOLLOW-UP PLANNING COMPLETE"),
+                    "",
+                    f"New pending subtasks: {highlight(str(len(pending_subtasks)))}",
+                    f"Total subtasks: {len(all_subtasks)}",
+                    "",
+                    muted("Next steps:"),
+                    f"  Run: {highlight(f'python auto-claude/run.py --spec {spec_dir.name}')}",
+                ]
+                print(box(content, width=70, style="heavy"))
+                print()
+                status_manager.update(state=BuildState.PAUSED)
+                return True
+            else:
+                print()
+                print_status(
+                    "Warning: No pending subtasks found after planning", "warning"
+                )
+                print(muted("The planner may not have added new subtasks."))
+                print(muted("Check implementation_plan.json manually."))
+                status_manager.update(state=BuildState.PAUSED)
+                return False
+        else:
+            print()
+            print_status(
+                "Error: implementation_plan.json not found after planning", "error"
+            )
+            status_manager.update(state=BuildState.ERROR)
+            return False
+
+    except Exception as e:
+        print()
+        print_status(f"Follow-up planning error: {e}", "error")
+        if task_logger:
+            task_logger.log_error(f"Follow-up planning error: {e}", LogPhase.PLANNING)
+        status_manager.update(state=BuildState.ERROR)
+        return False
@@ -0,0 +1,347 @@
+"""
+PR Template Filler Agent Module
+================================
+
+Detects GitHub PR templates in a project and uses Claude to intelligently
+fill them based on code changes, spec context, commit history, and branch info.
+"""
+
+import logging
+from pathlib import Path
+
+from core.client import create_client
+from task_logger import LogPhase, get_task_logger
+
+from .session import run_agent_session
+
+logger = logging.getLogger(__name__)
+
+# Maximum diff size (in characters) before truncating to file-level summaries
+MAX_DIFF_CHARS = 30_000
+
+
+def detect_pr_template(project_dir: Path | str) -> str | None:
+    """
+    Detect a GitHub PR template in the project.
+
+    Searches for:
+    1. .github/PULL_REQUEST_TEMPLATE.md (single template)
+    2. .github/PULL_REQUEST_TEMPLATE/ directory (picks the first .md file)
+
+    Args:
+        project_dir: Root directory of the project
+
+    Returns:
+        The template content as a string, or None if no template is found.
+    """
+    project_dir = Path(project_dir)
+    # Check for single template file
+    single_template = project_dir / ".github" / "PULL_REQUEST_TEMPLATE.md"
+    if single_template.is_file():
+        try:
+            content = single_template.read_text(encoding="utf-8")
+            if content.strip():
+                logger.info(f"Found PR template: {single_template}")
+                return content
+        except Exception as e:
+            logger.warning(f"Failed to read PR template {single_template}: {e}")
+
+    # Check for template directory (pick first .md file alphabetically)
+    template_dir = project_dir / ".github" / "PULL_REQUEST_TEMPLATE"
+    if template_dir.is_dir():
+        try:
+            md_files = sorted(template_dir.glob("*.md"))
+            if md_files:
+                content = md_files[0].read_text(encoding="utf-8")
+                if content.strip():
+                    logger.info(f"Found PR template: {md_files[0]}")
+                    return content
+        except Exception as e:
+            logger.warning(f"Failed to read PR template from {template_dir}: {e}")
+
+    logger.info("No GitHub PR template found in project")
+    return None
+
+
+def _truncate_diff(diff_summary: str) -> str:
+    """
+    Truncate a large diff to file-level summaries to stay within token limits.
+
+    If the diff is within MAX_DIFF_CHARS, return it unchanged.
+    Otherwise, extract only file-level change summaries (e.g. file names
+    with insertions/deletions counts) and discard line-level detail.
+
+    Args:
+        diff_summary: The full diff summary text
+
+    Returns:
+        The original or truncated diff summary.
+    """
+    if len(diff_summary) <= MAX_DIFF_CHARS:
+        return diff_summary
+
+    lines = diff_summary.splitlines()
+    summary_lines: list[str] = []
+    summary_lines.append("(Diff truncated to file-level summaries due to size)")
+    summary_lines.append("")
+
+    for line in lines:
+        # Keep file-level summary lines (stat lines, file headers, etc.)
+        stripped = line.strip()
+        if (
+            stripped.startswith("diff --git")
+            or stripped.startswith("---")
+            or stripped.startswith("+++")
+            or "file changed" in stripped.lower()
+            or "files changed" in stripped.lower()
+            or "insertion" in stripped.lower()
+            or "deletion" in stripped.lower()
+            or stripped.startswith("rename")
+            or stripped.startswith("new file")
+            or stripped.startswith("deleted file")
+            or stripped.startswith("Binary files")
+        ):
+            summary_lines.append(line)
+
+    # If we couldn't extract meaningful summaries, take the first chunk
+    if len(summary_lines) <= 2:
+        truncated = diff_summary[:MAX_DIFF_CHARS]
+        return truncated + "\n\n(... diff truncated due to size)"
+
+    return "\n".join(summary_lines)
+
+
+def _strip_markdown_fences(content: str) -> str:
+    """
+    Strip markdown code fences from the response if present.
+
+    The AI sometimes wraps the output in ```markdown ... ``` even when instructed
+    not to. This ensures the PR body renders correctly on GitHub.
+
+    Args:
+        content: The response content to clean
+
+    Returns:
+        The content with markdown fences stripped.
+    """
+    result = content
+
+    # Strip opening fence (```markdown or just ```)
+    if result.startswith("```markdown"):
+        result = result[len("```markdown") :].lstrip("\n")
+    elif result.startswith("```md"):
+        result = result[len("```md") :].lstrip("\n")
+    elif result.startswith("```"):
+        result = result[3:].lstrip("\n")
+
+    # Strip closing fence
+    if result.endswith("```"):
+        result = result[:-3].rstrip("\n")
+
+    return result.strip()
+
+
+def _build_prompt(
+    template_content: str,
+    diff_summary: str,
+    spec_overview: str,
+    commit_log: str,
+    branch_name: str,
+    target_branch: str,
+) -> str:
+    """
+    Build the prompt for the PR template filler agent.
+
+    Combines the system prompt context variables into a single message
+    that includes the template and all change context.
+
+    Args:
+        template_content: The PR template markdown
+        diff_summary: Git diff summary (possibly truncated)
+        spec_overview: Spec.md content or summary
+        commit_log: Git log of commits in the PR
+        branch_name: Source branch name
+        target_branch: Target branch name
+
+    Returns:
+        The assembled prompt string.
+    """
+    return f"""Fill out the following GitHub PR template using the provided context.
+Return ONLY the filled template markdown — no preamble, no explanation, no code fences.
+
+## Checkbox Guidelines
+
+IMPORTANT: Be accurate and honest about what has and hasn't been verified.
+
+**Check these based on context (you can infer from the diff/spec):**
+- Base Branch targeting — check based on target_branch value
+- Type of Change (bug fix, feature, docs, refactor, test) — infer from diff and spec
+- Area (Frontend, Backend, Fullstack) — infer from changed file paths
+- Feature Toggle "N/A" — if the feature appears complete and not behind a flag
+- Breaking Changes "No" — if changes appear backward compatible
+
+**Leave UNCHECKED (these require human verification you cannot perform):**
+- "I've tested my changes locally" — you have not tested anything
+- "All CI checks pass" — CI has not run yet
+- "Windows/macOS/Linux tested" — requires manual testing on each platform
+- "All existing tests pass" — CI has not run yet
+- "New features include test coverage" — unless test files are clearly visible in the diff
+- "Bug fixes include regression tests" — unless test files are clearly visible in the diff
+
+**For platform/code quality checkboxes:**
+- "Used centralized platform/ module" — leave unchecked unless you can verify from the diff
+- "No hardcoded paths" — leave unchecked unless you can verify from the diff
+- "PR is small and focused (< 400 lines)" — check only if diff stats show < 400 lines changed
+
+**For the "I've synced with develop branch" checkbox:**
+- Leave unchecked — you cannot verify the sync status
+
+## PR Template
+
+{template_content}
+
+## Change Context
+
+### Branch Information
+- **Source branch:** {branch_name}
+- **Target branch:** {target_branch}
+
+### Git Diff Summary
+```
+{diff_summary}
+```
+
+### Spec Overview
+{spec_overview}
+
+### Commit History
+```
+{commit_log}
+```
+
+Fill every section of the PR template. Follow the checkbox guidelines above carefully.
+Output ONLY the completed template — no code fences, no preamble."""
+
+
+def _load_spec_overview(spec_dir: Path) -> str:
+    """
+    Load the spec.md content for context. Falls back to a brief note if unavailable.
+
+    Args:
+        spec_dir: Directory containing the spec files
+
+    Returns:
+        The spec content or a fallback message.
+    """
+    spec_file = spec_dir / "spec.md"
+    if spec_file.is_file():
+        try:
+            content = spec_file.read_text(encoding="utf-8")
+            # Truncate very long specs to keep prompt manageable
+            if len(content) > 8000:
+                return content[:8000] + "\n\n(... spec truncated for brevity)"
+            return content
+        except Exception as e:
+            logger.warning(f"Failed to read spec.md: {e}")
+    return "(No spec overview available)"
+
+
+async def run_pr_template_filler(
+    project_dir: Path,
+    spec_dir: Path,
+    model: str,
+    thinking_budget: int | None = None,
+    branch_name: str = "",
+    target_branch: str = "develop",
+    diff_summary: str = "",
+    commit_log: str = "",
+    verbose: bool = False,
+) -> str | None:
+    """
+    Run the PR template filler agent to generate a filled PR body.
+
+    Detects the project's PR template, gathers change context, and invokes
+    Claude to intelligently fill out the template sections.
+
+    Args:
+        project_dir: Root directory of the project
+        spec_dir: Directory containing the spec files
+        model: Claude model to use
+        thinking_budget: Max thinking tokens (None to disable extended thinking)
+        branch_name: Source branch name for the PR
+        target_branch: Target branch name for the PR
+        diff_summary: Git diff summary of changes
+        commit_log: Git log of commits included in the PR
+        verbose: Whether to show detailed output
+
+    Returns:
+        The filled template markdown string, or None if template detection fails
+        or the agent encounters an error.
+    """
+    # Detect PR template
+    template_content = detect_pr_template(project_dir)
+    if template_content is None:
+        logger.info("No PR template detected — skipping template filler")
+        return None
+
+    # Load spec overview
+    spec_overview = _load_spec_overview(spec_dir)
+
+    # Truncate diff if too large
+    truncated_diff = _truncate_diff(diff_summary)
+
+    # Build the prompt
+    prompt = _build_prompt(
+        template_content=template_content,
+        diff_summary=truncated_diff,
+        spec_overview=spec_overview,
+        commit_log=commit_log,
+        branch_name=branch_name,
+        target_branch=target_branch,
+    )
+
+    # Initialize task logger
+    task_logger = get_task_logger(spec_dir)
+    if task_logger:
+        task_logger.start_phase(LogPhase.CODING, "PR template filling")
+
+    # Create client following the pattern from planner.py
+    client = create_client(
+        project_dir,
+        spec_dir,
+        model,
+        agent_type="pr_template_filler",
+        max_thinking_tokens=thinking_budget,
+    )
+
+    try:
+        async with client:
+            status, response, _ = await run_agent_session(
+                client, prompt, spec_dir, verbose, phase=LogPhase.CODING
+            )
+
+        if task_logger:
+            task_logger.end_phase(
+                LogPhase.CODING,
+                success=(status != "error"),
+                message="PR template filling completed",
+            )
+
+        if status == "error":
+            logger.error("PR template filler agent returned an error")
+            return None
+
+        # The agent should return only the filled template markdown
+        if response and response.strip():
+            result = _strip_markdown_fences(response.strip())
+            logger.info("PR template filled successfully")
+            return result
+
+        logger.warning("PR template filler returned empty response")
+        return None
+
+    except Exception as e:
+        logger.error(f"PR template filler error: {e}")
+        if task_logger:
+            task_logger.log_error(f"PR template filler error: {e}", LogPhase.CODING)
+        return None
@@ -263,6 +263,12 @@ AGENT_CONFIGS = {
        "auto_claude_tools": [],
        "thinking_default": "low",
    },
+    "pr_template_filler": {
+        "tools": BASE_READ_TOOLS,  # Read-only — reads diff, template, spec
+        "mcp_servers": [],  # No MCP needed, context passed via prompt
+        "auto_claude_tools": [],
+        "thinking_default": "low",  # Fast utility task for structured fill-in
+    },
    "pr_reviewer": {
        "tools": BASE_READ_TOOLS + WEB_TOOLS,  # Read-only
        "mcp_servers": ["context7"],
@@ -270,18 +276,30 @@ AGENT_CONFIGS = {
        "thinking_default": "high",
    },
    "pr_orchestrator_parallel": {
-        "tools": BASE_READ_TOOLS + WEB_TOOLS,  # Read-only for parallel PR orchestrator
+        # Read-only for parallel PR orchestrator
+        # NOTE: Do NOT add "Task" here - the SDK auto-allows Task when agents are defined
+        # via the --agents flag. Explicitly adding it interferes with agent registration.
+        "tools": BASE_READ_TOOLS + WEB_TOOLS,
        "mcp_servers": ["context7"],
        "auto_claude_tools": [],
        "thinking_default": "high",
    },
    "pr_followup_parallel": {
-        "tools": BASE_READ_TOOLS
-        + WEB_TOOLS,  # Read-only for parallel followup reviewer
+        # Read-only for parallel followup reviewer
+        # NOTE: Do NOT add "Task" here - same reason as pr_orchestrator_parallel
+        "tools": BASE_READ_TOOLS + WEB_TOOLS,
        "mcp_servers": ["context7"],
        "auto_claude_tools": [],
        "thinking_default": "high",
    },
+    "pr_finding_validator": {
+        # Standalone validator for re-checking findings against actual code
+        # Called separately from orchestrator to validate findings with fresh context
+        "tools": BASE_READ_TOOLS,
+        "mcp_servers": [],
+        "auto_claude_tools": [],
+        "thinking_default": "medium",
+    },
    # ═══════════════════════════════════════════════════════════════════════
    # ANALYSIS PHASES
    # ═══════════════════════════════════════════════════════════════════════
@@ -52,7 +52,7 @@ async def _save_to_graphiti_async(
        # The helper handles enablement checks internally
        from memory.graphiti_helpers import get_graphiti_memory

-        memory = get_graphiti_memory(spec_dir, project_dir)
+        memory = await get_graphiti_memory(spec_dir, project_dir)
        if memory is None:
            return False

@@ -171,7 +171,7 @@ def create_memory_tools(spec_dir: Path, project_dir: Path) -> list:
            # PRIMARY: Save to file-based storage (always works)
            # Load existing map or create new
            if codebase_map_file.exists():
-                with open(codebase_map_file) as f:
+                with open(codebase_map_file, encoding="utf-8") as f:
                    codebase_map = json.load(f)
            else:
                codebase_map = {
@@ -187,7 +187,7 @@ def create_memory_tools(spec_dir: Path, project_dir: Path) -> list:
            }
            codebase_map["last_updated"] = datetime.now(timezone.utc).isoformat()

-            with open(codebase_map_file, "w") as f:
+            with open(codebase_map_file, "w", encoding="utf-8") as f:
                json.dump(codebase_map, f, indent=2)

            # SECONDARY: Also save to Graphiti/LadybugDB (for Memory UI)
@@ -246,7 +246,7 @@ def create_memory_tools(spec_dir: Path, project_dir: Path) -> list:
                entry += f"\n\n_Context: {context}_"
            entry += "\n"

-            with open(gotchas_file, "a") as f:
+            with open(gotchas_file, "a", encoding="utf-8") as f:
                if not gotchas_file.exists() or gotchas_file.stat().st_size == 0:
                    f.write(
                        "# Gotchas & Pitfalls\n\nThings to watch out for in this codebase.\n"
@@ -303,7 +303,7 @@ def create_memory_tools(spec_dir: Path, project_dir: Path) -> list:
        codebase_map_file = memory_dir / "codebase_map.json"
        if codebase_map_file.exists():
            try:
-                with open(codebase_map_file) as f:
+                with open(codebase_map_file, encoding="utf-8") as f:
                    codebase_map = json.load(f)

                discoveries = codebase_map.get("discovered_files", {})
@@ -319,7 +319,7 @@ def create_memory_tools(spec_dir: Path, project_dir: Path) -> list:
        gotchas_file = memory_dir / "gotchas.md"
        if gotchas_file.exists():
            try:
-                content = gotchas_file.read_text()
+                content = gotchas_file.read_text(encoding="utf-8")
                if content.strip():
                    result_parts.append("\n## Gotchas")
                    # Take last 1000 chars to avoid too much context
@@ -333,7 +333,7 @@ def create_memory_tools(spec_dir: Path, project_dir: Path) -> list:
        patterns_file = memory_dir / "patterns.md"
        if patterns_file.exists():
            try:
-                content = patterns_file.read_text()
+                content = patterns_file.read_text(encoding="utf-8")
                if content.strip():
                    result_parts.append("\n## Patterns")
                    result_parts.append(
@@ -57,7 +57,7 @@ def create_progress_tools(spec_dir: Path, project_dir: Path) -> list:
            }

        try:
-            with open(plan_file) as f:
+            with open(plan_file, encoding="utf-8") as f:
                plan = json.load(f)

            stats = {
@@ -56,14 +56,10 @@ def _apply_qa_update(
        "ready_for_qa_revalidation": status == "fixes_applied",
    }

-    # Update plan status to match QA result
-    # This ensures the UI shows the correct column after QA
-    if status == "approved":
-        plan["status"] = "human_review"
-        plan["planStatus"] = "review"
-    elif status == "rejected":
-        plan["status"] = "human_review"
-        plan["planStatus"] = "review"
+    # NOTE: Do NOT write plan["status"] or plan["planStatus"] here.
+    # The frontend XState task state machine owns status transitions.
+    # Writing status here races with XState's persistPlanStatusAndReasonSync()
+    # and can clobber the reviewReason field, causing tasks to appear "incomplete".

    plan["last_updated"] = datetime.now(timezone.utc).isoformat()

@@ -140,7 +136,7 @@ def create_qa_tools(spec_dir: Path, project_dir: Path) -> list:
            except json.JSONDecodeError:
                tests_passed = {}

-            with open(plan_file) as f:
+            with open(plan_file, encoding="utf-8") as f:
                plan = json.load(f)

            qa_session = _apply_qa_update(plan, status, issues, tests_passed)
@@ -162,7 +158,7 @@ def create_qa_tools(spec_dir: Path, project_dir: Path) -> list:
            if auto_fix_plan(spec_dir):
                # Retry after fix
                try:
-                    with open(plan_file) as f:
+                    with open(plan_file, encoding="utf-8") as f:
                        plan = json.load(f)

                    qa_session = _apply_qa_update(plan, status, issues, tests_passed)
@@ -113,7 +113,7 @@ def create_subtask_tools(spec_dir: Path, project_dir: Path) -> list:
            }

        try:
-            with open(plan_file) as f:
+            with open(plan_file, encoding="utf-8") as f:
                plan = json.load(f)

            subtask_found = _update_subtask_in_plan(plan, subtask_id, status, notes)
@@ -145,7 +145,7 @@ def create_subtask_tools(spec_dir: Path, project_dir: Path) -> list:
            if auto_fix_plan(spec_dir):
                # Retry after fix
                try:
-                    with open(plan_file) as f:
+                    with open(plan_file, encoding="utf-8") as f:
                        plan = json.load(f)

                    subtask_found = _update_subtask_in_plan(
@@ -48,9 +48,9 @@ def load_implementation_plan(spec_dir: Path) -> dict | None:
    if not plan_file.exists():
        return None
    try:
-        with open(plan_file) as f:
+        with open(plan_file, encoding="utf-8") as f:
            return json.load(f)
-    except (OSError, json.JSONDecodeError):
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
        return None


@@ -46,7 +46,7 @@ def analyze_project(project_dir: Path, output_file: Path | None = None) -> dict:

    if output_file:
        output_file.parent.mkdir(parents=True, exist_ok=True)
-        with open(output_file, "w") as f:
+        with open(output_file, "w", encoding="utf-8") as f:
            json.dump(results, f, indent=2)
        print(f"Project index saved to: {output_file}")

@@ -87,7 +87,7 @@ def analyze_service(

    if output_file:
        output_file.parent.mkdir(parents=True, exist_ok=True)
-        with open(output_file, "w") as f:
+        with open(output_file, "w", encoding="utf-8") as f:
            json.dump(results, f, indent=2)
        print(f"Service analysis saved to: {output_file}")

@@ -99,7 +99,7 @@ class BaseAnalyzer:
    def _read_file(self, path: str) -> str:
        """Read a file relative to the analyzer's path."""
        try:
-            return (self.path / path).read_text()
+            return (self.path / path).read_text(encoding="utf-8")
        except (OSError, UnicodeDecodeError):
            return ""

@@ -126,7 +126,7 @@ class AuthDetector(BaseAnalyzer):

        for py_file in all_py_files:
            try:
-                content = py_file.read_text()
+                content = py_file.read_text(encoding="utf-8")
                # Find custom decorators
                if (
                    "@require" in content
@@ -52,7 +52,7 @@ class JobsDetector(BaseAnalyzer):
        tasks = []
        for task_file in celery_files:
            try:
-                content = task_file.read_text()
+                content = task_file.read_text(encoding="utf-8")
                # Find @celery.task or @shared_task decorators
                task_pattern = r"@(?:celery\.task|shared_task|app\.task)\s*(?:\([^)]*\))?\s*def\s+(\w+)"
                task_matches = re.findall(task_pattern, content)
@@ -77,7 +77,7 @@ class MonitoringDetector(BaseAnalyzer):
                continue

            try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
                # Look for actual Prometheus imports or usage patterns
                prometheus_patterns = [
                    "from prometheus_client import",
@@ -52,7 +52,7 @@ class DatabaseDetector(BaseAnalyzer):

        for file_path in py_files:
            try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
            except (OSError, UnicodeDecodeError):
                continue

@@ -119,7 +119,7 @@ class DatabaseDetector(BaseAnalyzer):

        for file_path in model_files:
            try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
            except (OSError, UnicodeDecodeError):
                continue

@@ -168,7 +168,7 @@ class DatabaseDetector(BaseAnalyzer):
            return models

        try:
-            content = schema_file.read_text()
+            content = schema_file.read_text(encoding="utf-8")
        except (OSError, UnicodeDecodeError):
            return models

@@ -216,7 +216,7 @@ class DatabaseDetector(BaseAnalyzer):

        for file_path in ts_files:
            try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
            except (OSError, UnicodeDecodeError):
                continue

@@ -265,7 +265,7 @@ class DatabaseDetector(BaseAnalyzer):

        for file_path in schema_files:
            try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
            except (OSError, UnicodeDecodeError):
                continue

@@ -295,7 +295,7 @@ class DatabaseDetector(BaseAnalyzer):

        for file_path in model_files:
            try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
            except (OSError, UnicodeDecodeError):
                continue

@@ -287,6 +287,6 @@ class ProjectAnalyzer:

    def _read_file(self, path: str) -> str:
        try:
-            return (self.project_dir / path).read_text()
+            return (self.project_dir / path).read_text(encoding="utf-8")
        except (OSError, UnicodeDecodeError):
            return ""
@@ -66,7 +66,7 @@ class RouteDetector(BaseAnalyzer):

        for file_path in files_to_check:
            try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
            except (OSError, UnicodeDecodeError):
                continue

@@ -130,7 +130,7 @@ class RouteDetector(BaseAnalyzer):

        for file_path in files_to_check:
            try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
            except (OSError, UnicodeDecodeError):
                continue

@@ -179,7 +179,7 @@ class RouteDetector(BaseAnalyzer):

        for file_path in url_files:
            try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
            except (OSError, UnicodeDecodeError):
                continue

@@ -218,7 +218,7 @@ class RouteDetector(BaseAnalyzer):
        files_to_check = js_files + ts_files
        for file_path in files_to_check:
            try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
            except (OSError, UnicodeDecodeError):
                continue

@@ -283,7 +283,7 @@ class RouteDetector(BaseAnalyzer):
                route_path = re.sub(r"\[([^\]]+)\]", r":\1", route_path)

                try:
-                    content = route_file.read_text()
+                    content = route_file.read_text(encoding="utf-8")
                    # Detect exported methods: export async function GET(request)
                    methods = re.findall(
                        r"export\s+(?:async\s+)?function\s+(GET|POST|PUT|DELETE|PATCH)",
@@ -348,7 +348,7 @@ class RouteDetector(BaseAnalyzer):

        for file_path in go_files:
            try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
            except (OSError, UnicodeDecodeError):
                continue

@@ -384,7 +384,7 @@ class RouteDetector(BaseAnalyzer):

        for file_path in rust_files:
            try:
-                content = file_path.read_text()
+                content = file_path.read_text(encoding="utf-8")
            except (OSError, UnicodeDecodeError):
                continue

@@ -163,7 +163,7 @@ class CIDiscovery:
            )

            try:
-                content = wf_file.read_text()
+                content = wf_file.read_text(encoding="utf-8")
                workflow_data = self._parse_yaml(content)

                if not workflow_data:
@@ -242,7 +242,7 @@ class CIDiscovery:
        )

        try:
-            content = config_file.read_text()
+            content = config_file.read_text(encoding="utf-8")
            data = self._parse_yaml(content)

            if not data:
@@ -312,7 +312,7 @@ class CIDiscovery:
        )

        try:
-            content = config_file.read_text()
+            content = config_file.read_text(encoding="utf-8")
            data = self._parse_yaml(content)

            if not data:
@@ -370,7 +370,7 @@ class CIDiscovery:
        )

        try:
-            content = jenkinsfile.read_text()
+            content = jenkinsfile.read_text(encoding="utf-8")

            # Extract sh commands using regex
            sh_pattern = re.compile(r'sh\s+[\'"]([^\'"]+)[\'"]')
@@ -237,7 +237,7 @@ def _get_subtask_description(spec_dir: Path, subtask_id: str) -> str:
        return f"Subtask: {subtask_id}"

    try:
-        with open(plan_file) as f:
+        with open(plan_file, encoding="utf-8") as f:
            plan = json.load(f)

        # Search through phases for the subtask
@@ -280,7 +280,7 @@ def _build_extraction_prompt(inputs: dict) -> str:
    prompt_file = Path(__file__).parent / "prompts" / "insight_extractor.md"

    if prompt_file.exists():
-        base_prompt = prompt_file.read_text()
+        base_prompt = prompt_file.read_text(encoding="utf-8")
    else:
        # Fallback if prompt file missing
        base_prompt = """Extract structured insights from this coding session.
@@ -302,7 +302,7 @@ class TestDiscovery:
        try:
            with open(package_json, encoding="utf-8") as f:
                pkg = json.load(f)
-        except (OSError, json.JSONDecodeError):
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
            return

        deps = pkg.get("dependencies", {})
@@ -398,7 +398,7 @@ class TestDiscovery:
        # Check pyproject.toml
        pyproject = project_dir / "pyproject.toml"
        if pyproject.exists():
-            content = pyproject.read_text()
+            content = pyproject.read_text(encoding="utf-8")

            # Check for pytest
            if "pytest" in content:
@@ -418,7 +418,7 @@ class TestDiscovery:
        # Check requirements.txt
        requirements = project_dir / "requirements.txt"
        if requirements.exists():
-            content = requirements.read_text().lower()
+            content = requirements.read_text(encoding="utf-8").lower()
            if "pytest" in content and not any(
                f.name == "pytest" for f in result.frameworks
            ):
@@ -496,7 +496,7 @@ class TestDiscovery:
        if not gemfile.exists():
            return

-        content = gemfile.read_text().lower()
+        content = gemfile.read_text(encoding="utf-8").lower()

        if "rspec" in content or (project_dir / ".rspec").exists():
            result.frameworks.append(
@@ -31,7 +31,7 @@ def handle_batch_create_command(batch_file: str, project_dir: str) -> bool:
        return False

    try:
-        with open(batch_path) as f:
+        with open(batch_path, encoding="utf-8") as f:
            batch_data = json.load(f)
    except json.JSONDecodeError as e:
        print_status(f"Invalid JSON in batch file: {e}", "error")
@@ -81,7 +81,7 @@ def handle_batch_create_command(batch_file: str, project_dir: str) -> bool:
        }

        req_file = spec_dir / "requirements.json"
-        with open(req_file, "w") as f:
+        with open(req_file, "w", encoding="utf-8") as f:
            json.dump(requirements, f, indent=2, default=str)

        created_specs.append(
@@ -145,7 +145,7 @@ def handle_batch_status_command(project_dir: str) -> bool:

        if req_file.exists():
            try:
-                with open(req_file) as f:
+                with open(req_file, encoding="utf-8") as f:
                    req = json.load(f)
                    title = req.get("task_description", title)
            except json.JSONDecodeError:
@@ -87,7 +87,10 @@ def handle_build_command(
        debug_success,
    )
    from phase_config import get_phase_model
-    from prompts_pkg.prompts import get_base_branch_from_metadata
+    from prompts_pkg.prompts import (
+        get_base_branch_from_metadata,
+        get_use_local_branch_from_metadata,
+    )
    from qa_loop import run_qa_validation_loop, should_run_qa

    from .utils import print_banner, validate_environment
@@ -203,6 +206,9 @@ def handle_build_command(
            base_branch = metadata_branch
            debug("run.py", f"Using base branch from task metadata: {base_branch}")

+    # Check if user requested local branch (preserves gitignored files like .env)
+    use_local_branch = get_use_local_branch_from_metadata(spec_dir)
+
    if workspace_mode == WorkspaceMode.ISOLATED:
        # Keep reference to original spec directory for syncing progress back
        source_spec_dir = spec_dir
@@ -213,6 +219,7 @@ def handle_build_command(
            workspace_mode,
            source_spec_dir=spec_dir,
            base_branch=base_branch,
+            use_local_branch=use_local_branch,
        )
        # Use the localized spec directory (inside worktree) for AI access
        if localized_spec_dir:
@@ -421,7 +428,7 @@ def _handle_build_interrupt(
        if human_input:
            # Save to HUMAN_INPUT.md
            input_file = spec_dir / "HUMAN_INPUT.md"
-            input_file.write_text(human_input)
+            input_file.write_text(human_input, encoding="utf-8")

            content = [
                success(f"{icon(Icons.SUCCESS)} INSTRUCTIONS SAVED"),
@@ -121,7 +121,7 @@ def collect_followup_task(spec_dir: Path, max_retries: int = 3) -> str | None:
                # Expand ~ and resolve path
                file_path = Path(file_path_str).expanduser().resolve()
                if file_path.exists():
-                    followup_task = file_path.read_text().strip()
+                    followup_task = file_path.read_text(encoding="utf-8").strip()
                    if followup_task:
                        print_status(
                            f"Loaded {len(followup_task)} characters from file",
@@ -195,7 +195,7 @@ def collect_followup_task(spec_dir: Path, max_retries: int = 3) -> str | None:

        # Save to FOLLOWUP_REQUEST.md
        request_file = spec_dir / "FOLLOWUP_REQUEST.md"
-        request_file.write_text(followup_task)
+        request_file.write_text(followup_task, encoding="utf-8")

        # Show confirmation
        content = [
@@ -285,7 +285,7 @@ def handle_followup_command(
    # Check for prior follow-ups (for sequential follow-up context)
    prior_followup_count = 0
    try:
-        with open(plan_file) as f:
+        with open(plan_file, encoding="utf-8") as f:
            plan_data = json.load(f)
        phases = plan_data.get("phases", [])
        # Count phases that look like follow-up phases (name contains "Follow" or high phase number)
@@ -149,7 +149,7 @@ def read_from_file() -> str | None:
        # Expand ~ and resolve path
        file_path = Path(file_path_input).expanduser().resolve()
        if file_path.exists():
-            content = file_path.read_text().strip()
+            content = file_path.read_text(encoding="utf-8").strip()
            if content:
                print_status(
                    f"Loaded {len(content)} characters from file",
@@ -74,12 +74,12 @@ Examples:
  python auto-claude/run.py --spec 001 --qa-status      # Check QA validation status

 Prerequisites:
-  1. Create a spec first: claude /spec
-  2. Run 'claude setup-token' and set CLAUDE_CODE_OAUTH_TOKEN
+  1. Authenticate: Run 'claude' and type '/login'
+  2. Create a spec first: claude /spec

 Environment Variables:
-  CLAUDE_CODE_OAUTH_TOKEN  Your Claude Code OAuth token (required)
-                           Get it by running: claude setup-token
+  CLAUDE_CODE_OAUTH_TOKEN  Your Claude Code OAuth token (auto-detected from Keychain)
+                           Or authenticate via: claude → /login
  AUTO_BUILD_MODEL         Override default model (optional)
        """,
    )
@@ -182,7 +182,7 @@ def _detect_worktree_base_branch(
    config_path = worktree_path / ".auto-claude" / "worktree-config.json"
    if config_path.exists():
        try:
-            config = json.loads(config_path.read_text())
+            config = json.loads(config_path.read_text(encoding="utf-8"))
            if config.get("base_branch"):
                debug(
                    MODULE,
@@ -536,6 +536,175 @@ def handle_cleanup_worktrees_command(project_dir: Path) -> None:
    cleanup_all_worktrees(project_dir, confirm=True)


+def _detect_conflict_scenario(
+    project_dir: Path,
+    conflicting_files: list[str],
+    spec_branch: str,
+    base_branch: str,
+) -> dict:
+    """
+    Analyze conflicting files to determine the conflict scenario.
+
+    This helps distinguish between:
+    - 'already_merged': Task changes already identical in target branch
+    - 'superseded': Target has newer version of same feature
+    - 'diverged': Standard diverged branches (AI can resolve)
+    - 'normal_conflict': Actual conflicting changes
+
+    Returns dict with:
+    - scenario: 'already_merged' | 'superseded' | 'diverged' | 'normal_conflict'
+    - already_merged_files: files identical in task and target
+    - details: additional context
+    """
+    if not conflicting_files:
+        return {
+            "scenario": "normal_conflict",
+            "already_merged_files": [],
+            "details": "No conflicting files to analyze",
+        }
+
+    already_merged_files = []
+    superseded_files = []
+    diverged_files = []
+
+    try:
+        # Get the merge-base commit
+        merge_base_result = subprocess.run(
+            ["git", "merge-base", base_branch, spec_branch],
+            cwd=project_dir,
+            capture_output=True,
+            text=True,
+        )
+        if merge_base_result.returncode != 0:
+            debug_warning(
+                MODULE, "Could not find merge base for conflict scenario detection"
+            )
+            return {
+                "scenario": "normal_conflict",
+                "already_merged_files": [],
+                "details": "Could not determine merge base",
+            }
+
+        merge_base = merge_base_result.stdout.strip()
+
+        for file_path in conflicting_files:
+            try:
+                # Get content from spec branch (task's changes)
+                spec_content_result = subprocess.run(
+                    ["git", "show", f"{spec_branch}:{file_path}"],
+                    cwd=project_dir,
+                    capture_output=True,
+                    text=True,
+                )
+                # Get content from base branch (target)
+                base_content_result = subprocess.run(
+                    ["git", "show", f"{base_branch}:{file_path}"],
+                    cwd=project_dir,
+                    capture_output=True,
+                    text=True,
+                )
+                # Get content from merge-base (original state)
+                merge_base_content_result = subprocess.run(
+                    ["git", "show", f"{merge_base}:{file_path}"],
+                    cwd=project_dir,
+                    capture_output=True,
+                    text=True,
+                )
+
+                # Check file existence in each ref
+                spec_exists = spec_content_result.returncode == 0
+                base_exists = base_content_result.returncode == 0
+                merge_base_exists = merge_base_content_result.returncode == 0
+
+                if spec_exists and base_exists:
+                    spec_content = spec_content_result.stdout
+                    base_content = base_content_result.stdout
+
+                    # If contents are identical, the changes are already merged
+                    if spec_content == base_content:
+                        already_merged_files.append(file_path)
+                        debug(
+                            MODULE,
+                            f"File {file_path}: already merged (identical content)",
+                        )
+                    elif merge_base_exists:
+                        merge_base_content = merge_base_content_result.stdout
+                        # If base has changed from merge_base but spec matches merge_base,
+                        # the task's changes are superseded by newer changes
+                        if spec_content == merge_base_content:
+                            superseded_files.append(file_path)
+                            debug(
+                                MODULE,
+                                f"File {file_path}: superseded (base has newer changes)",
+                            )
+                        else:
+                            diverged_files.append(file_path)
+                            debug(
+                                MODULE,
+                                f"File {file_path}: diverged (both branches modified)",
+                            )
+                    else:
+                        diverged_files.append(file_path)
+                else:
+                    diverged_files.append(file_path)
+
+            except Exception as e:
+                debug_warning(
+                    MODULE, f"Error analyzing file {file_path} for scenario: {e}"
+                )
+                diverged_files.append(file_path)
+
+        # Determine overall scenario based on dominant pattern
+        total_files = len(conflicting_files)
+
+        if len(already_merged_files) == total_files:
+            scenario = "already_merged"
+            details = "All conflicting files have identical content in both branches"
+        elif len(already_merged_files) > total_files / 2:
+            scenario = "already_merged"
+            details = f"{len(already_merged_files)} of {total_files} files already have the same content"
+        elif len(superseded_files) == total_files:
+            scenario = "superseded"
+            details = "All task changes have been superseded by newer changes in the target branch"
+        elif len(superseded_files) > total_files / 2:
+            scenario = "superseded"
+            details = (
+                f"{len(superseded_files)} of {total_files} files have been superseded"
+            )
+        elif diverged_files:
+            scenario = "diverged"
+            details = f"{len(diverged_files)} files have diverged and need AI merge"
+        else:
+            scenario = "normal_conflict"
+            details = "Standard merge conflicts detected"
+
+        debug(
+            MODULE,
+            f"Conflict scenario: {scenario}",
+            already_merged=len(already_merged_files),
+            superseded=len(superseded_files),
+            diverged=len(diverged_files),
+        )
+
+        return {
+            "scenario": scenario,
+            "already_merged_files": already_merged_files,
+            "superseded_files": superseded_files,
+            "diverged_files": diverged_files,
+            "details": details,
+        }
+
+    except Exception as e:
+        debug_error(MODULE, f"Error detecting conflict scenario: {e}")
+        return {
+            "scenario": "normal_conflict",
+            "already_merged_files": [],
+            "superseded_files": [],
+            "diverged_files": [],
+            "details": f"Error during analysis: {e}",
+        }
+
+
 def _check_git_merge_conflicts(
    project_dir: Path, spec_name: str, base_branch: str | None = None
 ) -> dict:
@@ -879,6 +1048,24 @@ def handle_merge_preview_command(
            f for f in git_conflicts.get("conflicting_files", []) if not is_lock_file(f)
        ]

+        # Detect conflict scenario (already_merged, superseded, diverged, normal_conflict)
+        # This helps the UI show appropriate messaging and actions
+        conflict_scenario = None
+        if non_lock_conflicting_files:
+            conflict_scenario = _detect_conflict_scenario(
+                project_dir,
+                non_lock_conflicting_files,
+                git_conflicts["spec_branch"],
+                git_conflicts["base_branch"],
+            )
+            debug(
+                MODULE,
+                f"Conflict scenario detected: {conflict_scenario.get('scenario')}",
+                already_merged_files=len(
+                    conflict_scenario.get("already_merged_files", [])
+                ),
+            )
+
        # Use git diff file count as the authoritative totalFiles count
        # The semantic tracker may not track all files (e.g., test files, config files)
        # but we want to show the user all files that will be merged
@@ -952,6 +1139,16 @@ def handle_merge_preview_command(
                # Path-mapped files that need AI merge due to renames
                "pathMappedAIMerges": path_mapped_ai_merges,
                "totalRenames": len(path_mappings),
+                # Conflict scenario detection for better UX messaging
+                "scenario": conflict_scenario.get("scenario")
+                if conflict_scenario
+                else None,
+                "alreadyMergedFiles": conflict_scenario.get("already_merged_files", [])
+                if conflict_scenario
+                else [],
+                "scenarioMessage": conflict_scenario.get("details")
+                if conflict_scenario
+                else None,
            },
            "summary": {
                # Use git diff count, not semantic tracker count
@@ -37,8 +37,12 @@ class ContextBuilder:
        """Load project index from file or create new one (.auto-claude is the installed instance)."""
        index_file = self.project_dir / ".auto-claude" / "project_index.json"
        if index_file.exists():
-            with open(index_file) as f:
-                return json.load(f)
+            try:
+                with open(index_file, encoding="utf-8") as f:
+                    return json.load(f)
+            except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+                # Corrupted or legacy-encoded file, regenerate
+                pass

        # Try to create one
        from analyzer import analyze_project
@@ -230,7 +234,9 @@ class ContextBuilder:
        if context_file.exists():
            return {
                "source": "SERVICE_CONTEXT.md",
-                "content": context_file.read_text()[:2000],  # First 2000 chars
+                "content": context_file.read_text(encoding="utf-8")[
+                    :2000
+                ],  # First 2000 chars
            }

        # Generate basic context from service info
@@ -72,7 +72,7 @@ def build_task_context(

    if output_file:
        output_file.parent.mkdir(parents=True, exist_ok=True)
-        with open(output_file, "w") as f:
+        with open(output_file, "w", encoding="utf-8") as f:
            json.dump(result, f, indent=2)
        print(f"Task context saved to: {output_file}")

@@ -38,7 +38,7 @@ class PatternDiscoverer:
        for match in reference_files[:max_files]:
            try:
                file_path = self.project_dir / match.path
-                content = file_path.read_text(errors="ignore")
+                content = file_path.read_text(encoding="utf-8", errors="ignore")

                # Look for common patterns
                for keyword in keywords:
@@ -41,7 +41,7 @@ class CodeSearcher:

        for file_path in self._iter_code_files(service_path):
            try:
-                content = file_path.read_text(errors="ignore")
+                content = file_path.read_text(encoding="utf-8", errors="ignore")
                content_lower = content.lower()

                # Score this file
@@ -41,7 +41,7 @@ def save_context(context: TaskContext, output_file: Path) -> None:
        output_file: Path to output JSON file
    """
    output_file.parent.mkdir(parents=True, exist_ok=True)
-    with open(output_file, "w") as f:
+    with open(output_file, "w", encoding="utf-8") as f:
        json.dump(serialize_context(context), f, indent=2)


@@ -55,5 +55,5 @@ def load_context(input_file: Path) -> dict:
    Returns:
        Context dictionary
    """
-    with open(input_file) as f:
+    with open(input_file, encoding="utf-8") as f:
        return json.load(f)
@@ -6,15 +6,15 @@ for multiple environment variables, and SDK environment variable passthrough
 for custom API endpoints.
 """

+import hashlib
 import json
 import logging
 import os
+import shutil
 import subprocess
 from typing import TYPE_CHECKING

 from core.platform import (
-    find_executable,
-    get_claude_detection_paths,
    is_linux,
    is_macos,
    is_windows,
@@ -59,9 +59,55 @@ SDK_ENV_VARS = [
    "API_TIMEOUT_MS",
    # Windows-specific: Git Bash path for Claude Code CLI
    "CLAUDE_CODE_GIT_BASH_PATH",
+    # Claude CLI path override (allows frontend to pass detected CLI path to SDK)
+    "CLAUDE_CLI_PATH",
+    # Profile's custom config directory (for multi-profile token storage)
+    "CLAUDE_CONFIG_DIR",
 ]


+def _calculate_config_dir_hash(config_dir: str) -> str:
+    """
+    Calculate hash of config directory path for Keychain service name.
+
+    This MUST match the frontend's calculateConfigDirHash() in credential-utils.ts.
+    The frontend uses SHA256 hash of the config dir path, taking first 8 hex chars.
+
+    Args:
+        config_dir: Path to the config directory (should be absolute/expanded)
+
+    Returns:
+        8-character hex hash string (e.g., "d74c9506")
+    """
+    return hashlib.sha256(config_dir.encode()).hexdigest()[:8]
+
+
+def _get_keychain_service_name(config_dir: str | None = None) -> str:
+    """
+    Get the Keychain service name for credential storage.
+
+    This MUST match the frontend's getKeychainServiceName() in credential-utils.ts.
+    All profiles use hash-based keychain entries for isolation:
+    - Profile with configDir: "Claude Code-credentials-{hash}"
+    - No configDir (legacy/default): "Claude Code-credentials"
+
+    Args:
+        config_dir: Optional CLAUDE_CONFIG_DIR path. If provided, uses hash-based name.
+
+    Returns:
+        Keychain service name (e.g., "Claude Code-credentials-d74c9506")
+    """
+    if not config_dir:
+        return "Claude Code-credentials"
+
+    # Expand ~ to home directory (matching frontend normalization)
+    expanded_dir = os.path.expanduser(config_dir)
+
+    # Calculate hash and return hash-based service name
+    hash_suffix = _calculate_config_dir_hash(expanded_dir)
+    return f"Claude Code-credentials-{hash_suffix}"
+
+
 def is_encrypted_token(token: str | None) -> bool:
    """
    Check if a token is encrypted (has "enc:" prefix).
@@ -239,7 +285,7 @@ def _decrypt_token_macos(encrypted_data: str) -> str:
        ValueError: If decryption fails or Claude CLI not available
    """
    # Verify Claude CLI is installed (required for future decryption implementation)
-    if not find_executable("claude", get_claude_detection_paths()):
+    if not shutil.which("claude"):
        raise ValueError(
            "Claude Code CLI not found. Please install it from https://code.claude.com"
        )
@@ -313,36 +359,80 @@ def _decrypt_token_windows(encrypted_data: str) -> str:
    )


-def get_token_from_keychain() -> str | None:
+def _try_decrypt_token(token: str | None) -> str | None:
+    """
+    Attempt to decrypt an encrypted token, returning original if decryption fails.
+
+    This helper centralizes the decrypt-or-return-as-is logic used when resolving
+    tokens from various sources (env vars, config dir, keychain).
+
+    Args:
+        token: Token string (may be encrypted with "enc:" prefix, plaintext, or None)
+
+    Returns:
+        - Decrypted token if successfully decrypted
+        - Original token if decryption fails (allows client validation to report error)
+        - Original token if not encrypted
+        - None if token is None
+    """
+    if not token:
+        return None
+
+    if is_encrypted_token(token):
+        try:
+            return decrypt_token(token)
+        except ValueError:
+            # Decryption failed - return encrypted token so client validation
+            # (validate_token_not_encrypted) can provide specific error message.
+            return token
+
+    return token
+
+
+def get_token_from_keychain(config_dir: str | None = None) -> str | None:
    """
    Get authentication token from system credential store.

    Reads Claude Code credentials from:
-    - macOS: Keychain
+    - macOS: Keychain (uses hash-based service name if config_dir provided)
    - Windows: Credential Manager
    - Linux: Secret Service API (via dbus/secretstorage)

+    Args:
+        config_dir: Optional CLAUDE_CONFIG_DIR path for profile-specific credentials.
+                   When provided, reads from hash-based keychain entry matching
+                   the frontend's storage location.
+
    Returns:
        Token string if found, None otherwise
    """
    if is_macos():
-        return _get_token_from_macos_keychain()
+        return _get_token_from_macos_keychain(config_dir)
    elif is_windows():
-        return _get_token_from_windows_credential_files()
+        return _get_token_from_windows_credential_files(config_dir)
    else:
        # Linux: use secret-service API via DBus
-        return _get_token_from_linux_secret_service()
+        return _get_token_from_linux_secret_service(config_dir)


-def _get_token_from_macos_keychain() -> str | None:
-    """Get token from macOS Keychain."""
+def _get_token_from_macos_keychain(config_dir: str | None = None) -> str | None:
+    """Get token from macOS Keychain.
+
+    Args:
+        config_dir: Optional CLAUDE_CONFIG_DIR path. When provided, uses hash-based
+                   service name (e.g., "Claude Code-credentials-d74c9506") matching
+                   the frontend's credential storage location.
+    """
+    # Get the correct service name (hash-based if config_dir provided)
+    service_name = _get_keychain_service_name(config_dir)
+
    try:
        result = subprocess.run(
            [
                "/usr/bin/security",
                "find-generic-password",
                "-s",
-                "Claude Code-credentials",
+                service_name,
                "-w",
            ],
            capture_output=True,
@@ -351,6 +441,14 @@ def _get_token_from_macos_keychain() -> str | None:
        )

        if result.returncode != 0:
+            # If hash-based lookup fails and we have a config_dir, DON'T fall back
+            # to default service name - that would return the wrong profile's token.
+            # The config_dir was provided explicitly, so we should only use that.
+            if config_dir:
+                logger.debug(
+                    f"No keychain entry found for service '{service_name}' "
+                    f"(config_dir: {config_dir})"
+                )
            return None

        credentials_json = result.stdout.strip()
@@ -364,22 +462,51 @@ def _get_token_from_macos_keychain() -> str | None:
            return None

        # Validate token format (Claude OAuth tokens start with sk-ant-oat01-)
-        if not token.startswith("sk-ant-oat01-"):
+        # Also accept encrypted tokens (enc:) which will be decrypted later
+        if not (token.startswith("sk-ant-oat01-") or token.startswith("enc:")):
            return None

+        logger.debug(f"Found token in keychain service '{service_name}'")
        return token

    except (subprocess.TimeoutExpired, json.JSONDecodeError, KeyError, Exception):
        return None


-def _get_token_from_windows_credential_files() -> str | None:
+def _get_token_from_windows_credential_files(
+    config_dir: str | None = None,
+) -> str | None:
    """Get token from Windows credential files.

    Claude Code on Windows stores credentials in ~/.claude/.credentials.json
+    For custom profiles, uses the config_dir's .credentials.json file.
+
+    Args:
+        config_dir: Optional CLAUDE_CONFIG_DIR path for profile-specific credentials.
    """
    try:
-        # Claude Code stores credentials in ~/.claude/.credentials.json
+        # If config_dir is provided, read from that directory first
+        if config_dir:
+            expanded_dir = os.path.expanduser(config_dir)
+            profile_cred_paths = [
+                os.path.join(expanded_dir, ".credentials.json"),
+                os.path.join(expanded_dir, "credentials.json"),
+            ]
+            for cred_path in profile_cred_paths:
+                if os.path.exists(cred_path):
+                    with open(cred_path, encoding="utf-8") as f:
+                        data = json.load(f)
+                        token = data.get("claudeAiOauth", {}).get("accessToken")
+                        if token and (
+                            token.startswith("sk-ant-oat01-")
+                            or token.startswith("enc:")
+                        ):
+                            logger.debug(f"Found token in {cred_path}")
+                            return token
+            # If config_dir provided but no token found, don't fall back to default
+            return None
+
+        # Default Claude Code credential paths (no profile specified)
        cred_paths = [
            os.path.expandvars(r"%USERPROFILE%\.claude\.credentials.json"),
            os.path.expandvars(r"%USERPROFILE%\.claude\credentials.json"),
@@ -392,7 +519,9 @@ def _get_token_from_windows_credential_files() -> str | None:
                with open(cred_path, encoding="utf-8") as f:
                    data = json.load(f)
                    token = data.get("claudeAiOauth", {}).get("accessToken")
-                    if token and token.startswith("sk-ant-oat01-"):
+                    if token and (
+                        token.startswith("sk-ant-oat01-") or token.startswith("enc:")
+                    ):
                        return token

        return None
@@ -401,7 +530,7 @@ def _get_token_from_windows_credential_files() -> str | None:
        return None


-def _get_token_from_linux_secret_service() -> str | None:
+def _get_token_from_linux_secret_service(config_dir: str | None = None) -> str | None:
    """Get token from Linux Secret Service API via DBus.

    Claude Code on Linux stores credentials in the Secret Service API
@@ -409,9 +538,12 @@ def _get_token_from_linux_secret_service() -> str | None:
    uses the secretstorage library which communicates via DBus.

    The credential is stored with:
-    - Label: "Claude Code-credentials"
+    - Label: "Claude Code-credentials" or "Claude Code-credentials-{hash}" for profiles
    - Attributes: {application: "claude-code"}

+    Args:
+        config_dir: Optional CLAUDE_CONFIG_DIR path for profile-specific credentials.
+
    Returns:
        Token string if found, None otherwise
    """
@@ -419,6 +551,9 @@ def _get_token_from_linux_secret_service() -> str | None:
        # secretstorage not installed, fall back to env var
        return None

+    # Get the correct service name (hash-based if config_dir provided)
+    target_label = _get_keychain_service_name(config_dir)
+
    try:
        # Get the default collection (typically "login" keyring)
        # secretstorage handles DBus communication internally
@@ -443,10 +578,10 @@ def _get_token_from_linux_secret_service() -> str | None:
        items = collection.search_items({"application": "claude-code"})

        for item in items:
-            # Check if this is the Claude Code credentials item
+            # Check if this is the correct Claude Code credentials item
            label = item.get_label()
-            # Use exact match for "Claude Code-credentials" to avoid false positives
-            if label == "Claude Code-credentials":
+            # Use exact match for target label (profile-specific or default)
+            if label == target_label:
                # Get the secret (stored as JSON string)
                secret = item.get_secret()
                if not secret:
@@ -459,11 +594,23 @@ def _get_token_from_linux_secret_service() -> str | None:
                    data = json.loads(secret)
                    token = data.get("claudeAiOauth", {}).get("accessToken")

-                    if token and token.startswith("sk-ant-oat01-"):
+                    if token and (
+                        token.startswith("sk-ant-oat01-") or token.startswith("enc:")
+                    ):
+                        logger.debug(
+                            f"Found token in secret service with label '{target_label}'"
+                        )
                        return token
                except json.JSONDecodeError:
                    continue

+        # If config_dir was provided but no token found, don't fall back
+        if config_dir:
+            logger.debug(
+                f"No secret service entry found with label '{target_label}' "
+                f"(config_dir: {config_dir})"
+            )
+
        return None

    except (
@@ -477,14 +624,65 @@ def _get_token_from_linux_secret_service() -> str | None:
        return None


-def get_auth_token() -> str | None:
+def _get_token_from_config_dir(config_dir: str) -> str | None:
    """
-    Get authentication token from environment variables or system credential store.
+    Read token from a custom config directory's credentials file.
+
+    Claude Code stores credentials in .credentials.json within the config directory.
+    This function reads from a profile's custom configDir instead of the default location.
+
+    Args:
+        config_dir: Path to the config directory (e.g., ~/.auto-claude/profiles/work)
+
+    Returns:
+        Token string if found, None otherwise
+    """
+    # Expand ~ if present
+    expanded_dir = os.path.expanduser(config_dir)
+
+    # Claude stores credentials in these files within the config dir
+    cred_files = [
+        os.path.join(expanded_dir, ".credentials.json"),
+        os.path.join(expanded_dir, "credentials.json"),
+    ]
+
+    for cred_path in cred_files:
+        if os.path.exists(cred_path):
+            try:
+                with open(cred_path, encoding="utf-8") as f:
+                    data = json.load(f)
+
+                # Try both credential structures
+                oauth_data = data.get("claudeAiOauth") or data.get("oauthAccount") or {}
+                token = oauth_data.get("accessToken")
+
+                # Accept both plaintext tokens (sk-ant-oat01-) and encrypted tokens (enc:)
+                if token and (
+                    token.startswith("sk-ant-oat01-") or token.startswith("enc:")
+                ):
+                    logger.debug(f"Found token in {cred_path}")
+                    return token
+            except (json.JSONDecodeError, KeyError, Exception) as e:
+                logger.debug(f"Failed to read {cred_path}: {e}")
+                continue
+
+    return None
+
+
+def get_auth_token(config_dir: str | None = None) -> str | None:
+    """
+    Get authentication token from environment variables or credential store.
+
+    Args:
+        config_dir: Optional custom config directory (profile's configDir).
+                   If provided, reads credentials from this directory.
+                   If None, checks CLAUDE_CONFIG_DIR env var, then uses default locations.

    Checks multiple sources in priority order:
    1. CLAUDE_CODE_OAUTH_TOKEN (env var)
    2. ANTHROPIC_AUTH_TOKEN (CCR/proxy env var for enterprise setups)
-    3. System credential store (macOS Keychain, Windows Credential Manager, Linux Secret Service)
+    3. Custom config directory (config_dir param or CLAUDE_CONFIG_DIR env var)
+    4. System credential store (macOS Keychain, Windows Credential Manager, Linux Secret Service)

    NOTE: ANTHROPIC_API_KEY is intentionally NOT supported to prevent
    silent billing to user's API credits when OAuth is misconfigured.
@@ -495,41 +693,81 @@ def get_auth_token() -> str | None:
    Returns:
        Token string if found, None otherwise
    """
-    # First check environment variables
+    # First check environment variables (highest priority)
    for var in AUTH_TOKEN_ENV_VARS:
        token = os.environ.get(var)
        if token:
-            # Decrypt if token is encrypted
-            if is_encrypted_token(token):
-                try:
-                    token = decrypt_token(token)
-                except ValueError:
-                    # Decryption failed - return encrypted token so client validation
-                    # can provide specific error message about encrypted format
-                    return token
-            return token
+            return _try_decrypt_token(token)

-    # Fallback to system credential store
-    token = get_token_from_keychain()
-    if token and is_encrypted_token(token):
-        try:
-            token = decrypt_token(token)
-        except ValueError:
-            # Decryption failed - return encrypted token so client validation
-            # (validate_token_not_encrypted) can provide specific error message.
-            # This is consistent with env var handling above.
-            return token
-    return token
+    # Check CLAUDE_CONFIG_DIR environment variable (profile's custom config directory)
+    env_config_dir = os.environ.get("CLAUDE_CONFIG_DIR")
+    effective_config_dir = config_dir or env_config_dir
+
+    # Debug: Log which config_dir is being used for credential resolution
+    debug = os.environ.get("DEBUG", "").lower() in ("true", "1")
+    if debug and effective_config_dir:
+        service_name = _get_keychain_service_name(effective_config_dir)
+        logger.info(
+            f"[Auth] Resolving credentials for profile config_dir: {effective_config_dir} "
+            f"(Keychain service: {service_name})"
+        )
+
+    # If a custom config directory is specified, read from there first
+    if effective_config_dir:
+        # Try reading from .credentials.json file in the config directory
+        token = _get_token_from_config_dir(effective_config_dir)
+        if token:
+            return _try_decrypt_token(token)
+
+        # Also try the system credential store with hash-based service name
+        # This is needed because macOS stores credentials in Keychain, not files
+        token = get_token_from_keychain(effective_config_dir)
+        if token:
+            return _try_decrypt_token(token)
+
+        # If config_dir was explicitly provided, DON'T fall back to default keychain
+        # - that would return the wrong profile's token
+        logger.debug(
+            f"No credentials found for config_dir '{effective_config_dir}' "
+            "in file or keychain"
+        )
+        return None
+
+    # No config_dir specified - use default system credential store
+    return _try_decrypt_token(get_token_from_keychain())


-def get_auth_token_source() -> str | None:
-    """Get the name of the source that provided the auth token."""
+def get_auth_token_source(config_dir: str | None = None) -> str | None:
+    """
+    Get the name of the source that provided the auth token.
+
+    Args:
+        config_dir: Optional custom config directory (profile's configDir).
+                   If provided, checks this directory for credentials.
+                   If None, checks CLAUDE_CONFIG_DIR env var.
+    """
    # Check environment variables first
    for var in AUTH_TOKEN_ENV_VARS:
        if os.environ.get(var):
            return var

-    # Check if token came from system credential store
+    # Check if token came from custom config directory (profile's configDir)
+    env_config_dir = os.environ.get("CLAUDE_CONFIG_DIR")
+    effective_config_dir = config_dir or env_config_dir
+    if effective_config_dir:
+        # Check file-based storage
+        if _get_token_from_config_dir(effective_config_dir):
+            return "CLAUDE_CONFIG_DIR"
+        # Check hash-based keychain entry for this profile
+        if get_token_from_keychain(effective_config_dir):
+            if is_macos():
+                return "macOS Keychain (profile)"
+            elif is_windows():
+                return "Windows Credential Files (profile)"
+            else:
+                return "Linux Secret Service (profile)"
+
+    # Check if token came from default system credential store
    if get_token_from_keychain():
        if is_macos():
            return "macOS Keychain"
@@ -541,14 +779,19 @@ def get_auth_token_source() -> str | None:
    return None


-def require_auth_token() -> str:
+def require_auth_token(config_dir: str | None = None) -> str:
    """
    Get authentication token or raise ValueError.

+    Args:
+        config_dir: Optional custom config directory (profile's configDir).
+                   If provided, reads credentials from this directory.
+                   If None, checks CLAUDE_CONFIG_DIR env var, then uses default locations.
+
    Raises:
        ValueError: If no auth token is found in any supported source
    """
-    token = get_auth_token()
+    token = get_auth_token(config_dir)
    if not token:
        error_msg = (
            "No OAuth token found.\n\n"
@@ -559,25 +802,30 @@ def require_auth_token() -> str:
        if is_macos():
            error_msg += (
                "To authenticate:\n"
-                "  1. Run: claude setup-token\n"
-                "  2. The token will be saved to macOS Keychain automatically\n\n"
-                "Or set CLAUDE_CODE_OAUTH_TOKEN in your .env file."
+                "  1. Run: claude\n"
+                "  2. Type: /login\n"
+                "  3. Press Enter to open browser\n"
+                "  4. Complete OAuth login in browser\n\n"
+                "The token will be saved to macOS Keychain automatically."
            )
        elif is_windows():
            error_msg += (
                "To authenticate:\n"
-                "  1. Run: claude setup-token\n"
-                "  2. The token should be saved to Windows Credential Manager\n\n"
-                "If auto-detection fails, set CLAUDE_CODE_OAUTH_TOKEN in your .env file.\n"
-                "Check: %LOCALAPPDATA%\\Claude\\credentials.json"
+                "  1. Run: claude\n"
+                "  2. Type: /login\n"
+                "  3. Press Enter to open browser\n"
+                "  4. Complete OAuth login in browser\n\n"
+                "The token will be saved to Windows Credential Manager."
            )
        else:
            # Linux
            error_msg += (
                "To authenticate:\n"
-                "  1. Run: claude setup-token\n"
-                "  2. The token will be saved to the system secret service (gnome-keyring/kwallet)\n\n"
-                "If secret-service is not available, set CLAUDE_CODE_OAUTH_TOKEN in your .env file."
+                "  1. Run: claude\n"
+                "  2. Type: /login\n"
+                "  3. Press Enter to open browser\n"
+                "  4. Complete OAuth login in browser\n\n"
+                "Or set CLAUDE_CODE_OAUTH_TOKEN in your .env file."
            )
        raise ValueError(error_msg)
    return token
@@ -700,6 +948,57 @@ def get_sdk_env_vars() -> dict[str, str]:
    return env


+def configure_sdk_authentication(config_dir: str | None = None) -> None:
+    """
+    Configure SDK authentication based on environment variables.
+
+    Supports two authentication modes:
+    - API Profile mode (ANTHROPIC_BASE_URL set): uses ANTHROPIC_AUTH_TOKEN
+    - OAuth mode (default): uses CLAUDE_CODE_OAUTH_TOKEN
+
+    In API profile mode, explicitly removes CLAUDE_CODE_OAUTH_TOKEN from the
+    environment because the SDK gives OAuth priority over API keys when both
+    are present.
+
+    Args:
+        config_dir: Optional profile config directory for per-profile Keychain
+                    lookup. When set, enables multi-profile token storage.
+
+    Raises:
+        ValueError: If required tokens are missing for the active mode.
+                   - API profile mode: requires ANTHROPIC_AUTH_TOKEN
+                   - OAuth mode: requires CLAUDE_CODE_OAUTH_TOKEN (from Keychain or env)
+    """
+    api_profile_mode = bool(os.environ.get("ANTHROPIC_BASE_URL", "").strip())
+
+    if api_profile_mode:
+        # API profile mode: ensure ANTHROPIC_AUTH_TOKEN is present
+        if not os.environ.get("ANTHROPIC_AUTH_TOKEN"):
+            raise ValueError(
+                "API profile mode active (ANTHROPIC_BASE_URL is set) "
+                "but ANTHROPIC_AUTH_TOKEN is not set"
+            )
+        # Explicitly remove CLAUDE_CODE_OAUTH_TOKEN so SDK uses ANTHROPIC_AUTH_TOKEN
+        # SDK gives OAuth priority over API keys when both are present
+        os.environ.pop("CLAUDE_CODE_OAUTH_TOKEN", None)
+        logger.info("Using API profile authentication")
+    else:
+        # OAuth mode: require and validate OAuth token
+        # Get OAuth token - uses profile-specific Keychain lookup when config_dir is set
+        # This correctly reads from "Claude Code-credentials-{hash}" for non-default profiles
+        oauth_token = require_auth_token(config_dir)
+
+        # Validate token is not encrypted before passing to SDK
+        # Encrypted tokens (enc:...) should have been decrypted by require_auth_token()
+        # If we still have an encrypted token here, it means decryption failed or was skipped
+        validate_token_not_encrypted(oauth_token)
+
+        # Ensure SDK can access it via its expected env var
+        # This is required because the SDK doesn't know about per-profile Keychain naming
+        os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = oauth_token
+        logger.info("Using OAuth authentication")
+
+
 def ensure_claude_code_oauth_token() -> None:
    """
    Ensure CLAUDE_CODE_OAUTH_TOKEN is set (for SDK compatibility).
@@ -713,3 +1012,181 @@ def ensure_claude_code_oauth_token() -> None:
    token = get_auth_token()
    if token:
        os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = token
+
+
+def trigger_login() -> bool:
+    """
+    Trigger Claude Code OAuth login flow.
+
+    Opens the Claude Code CLI and sends /login command to initiate
+    browser-based OAuth authentication. The token is automatically
+    saved to the system credential store (macOS Keychain, Windows
+    Credential Manager).
+
+    Returns:
+        True if login was successful, False otherwise
+    """
+    if is_macos():
+        return _trigger_login_macos()
+    elif is_windows():
+        return _trigger_login_windows()
+    else:
+        # Linux: fall back to manual instructions
+        print("\nTo authenticate, run 'claude' and type '/login'")
+        return False
+
+
+def _trigger_login_macos() -> bool:
+    """Trigger login on macOS using expect."""
+    import shutil
+    import tempfile
+
+    # Check if expect is available
+    if not shutil.which("expect"):
+        print("\nTo authenticate, run 'claude' and type '/login'")
+        return False
+
+    # Create expect script
+    expect_script = """#!/usr/bin/expect -f
+set timeout 120
+spawn claude
+expect {
+    -re ".*" {
+        send "/login\\r"
+        expect {
+            "Press Enter" {
+                send "\\r"
+            }
+            -re ".*login.*" {
+                send "\\r"
+            }
+            timeout {
+                send "\\r"
+            }
+        }
+    }
+}
+# Keep running until user completes login or exits
+interact
+"""
+
+    # Use TemporaryDirectory context manager for automatic cleanup
+    # This prevents information leakage about authentication activity
+    # Directory created with mode 0o700 (owner read/write/execute only)
+    try:
+        with tempfile.TemporaryDirectory() as temp_dir:
+            # Ensure directory has owner-only permissions
+            os.chmod(temp_dir, 0o700)
+
+            # Write expect script to temp file in our private directory
+            script_path = os.path.join(temp_dir, "login.exp")
+            with open(script_path, "w", encoding="utf-8") as f:
+                f.write(expect_script)
+
+            # Set script permissions to owner-only (0o700)
+            os.chmod(script_path, 0o700)
+
+            print("\n" + "=" * 60)
+            print("CLAUDE CODE LOGIN")
+            print("=" * 60)
+            print("\nOpening Claude Code for authentication...")
+            print("A browser window will open for OAuth login.")
+            print("After completing login in the browser, press Ctrl+C to exit.\n")
+
+            # Run expect script
+            subprocess.run(
+                ["expect", script_path],
+                timeout=300,  # 5 minute timeout
+            )
+
+            # Verify token was saved
+            token = get_token_from_keychain()
+            if token:
+                print("\n✓ Login successful! Token saved to macOS Keychain.")
+                return True
+            else:
+                print(
+                    "\n✗ Login may not have completed. Try running 'claude' and type '/login'"
+                )
+                return False
+
+    except subprocess.TimeoutExpired:
+        print("\nLogin timed out. Try running 'claude' manually and type '/login'")
+        return False
+    except KeyboardInterrupt:
+        # User pressed Ctrl+C - check if login completed
+        token = get_token_from_keychain()
+        if token:
+            print("\n✓ Login successful! Token saved to macOS Keychain.")
+            return True
+        return False
+    except Exception as e:
+        print(f"\nLogin failed: {e}")
+        print("Try running 'claude' manually and type '/login'")
+        return False
+
+
+def _trigger_login_windows() -> bool:
+    """Trigger login on Windows."""
+    # Windows doesn't have expect by default, so we use a simpler approach
+    # that just launches claude and tells the user what to type
+    print("\n" + "=" * 60)
+    print("CLAUDE CODE LOGIN")
+    print("=" * 60)
+    print("\nLaunching Claude Code...")
+    print("Please type '/login' and press Enter.")
+    print("A browser window will open for OAuth login.\n")
+
+    try:
+        # Launch claude interactively
+        subprocess.run(["claude"], timeout=300)
+
+        # Verify token was saved
+        token = _get_token_from_windows_credential_files()
+        if token:
+            print("\n✓ Login successful!")
+            return True
+        else:
+            print("\n✗ Login may not have completed.")
+            return False
+
+    except Exception as e:
+        print(f"\nLogin failed: {e}")
+        return False
+
+
+def ensure_authenticated() -> str:
+    """
+    Ensure the user is authenticated, prompting for login if needed.
+
+    Checks for existing token and triggers login flow if not found.
+
+    Returns:
+        The authentication token
+
+    Raises:
+        ValueError: If authentication fails after login attempt
+    """
+    # First check if already authenticated
+    token = get_auth_token()
+    if token:
+        return token
+
+    # No token found - trigger login
+    print("\nNo OAuth token found. Starting login flow...")
+
+    if trigger_login():
+        # Re-check for token after login
+        token = get_auth_token()
+        if token:
+            return token
+
+    # Login failed or was cancelled
+    raise ValueError(
+        "Authentication required.\n\n"
+        "To authenticate:\n"
+        "  1. Run: claude\n"
+        "  2. Type: /login\n"
+        "  3. Press Enter to open browser\n"
+        "  4. Complete OAuth login in browser"
+    )
@@ -16,17 +16,12 @@ import copy
 import json
 import logging
 import os
-import shutil
-import subprocess
 import threading
 import time
 from pathlib import Path
 from typing import Any

 from core.platform import (
-    get_claude_detection_paths_structured,
-    get_comspec_path,
-    is_macos,
    is_windows,
    validate_cli_path,
 )
@@ -130,220 +125,6 @@ def invalidate_project_cache(project_dir: Path | None = None) -> None:
                logger.debug(f"Invalidated project index cache for {project_dir}")


-# =============================================================================
-# Claude CLI Path Detection
-# =============================================================================
-# Cross-platform detection of Claude Code CLI binary.
-# This mirrors the frontend's cli-tool-manager.ts logic to ensure consistency.
-
-_CLAUDE_CLI_CACHE: dict[str, str | None] = {}
-_CLI_CACHE_LOCK = threading.Lock()
-
-
-def _get_claude_detection_paths() -> dict[str, list[str] | str]:
-    """
-    Get all candidate paths for Claude CLI detection.
-
-    This is a thin wrapper around the platform module's implementation.
-    See core/platform/__init__.py:get_claude_detection_paths_structured()
-    for the canonical implementation.
-
-    Returns:
-        Dict with 'homebrew', 'platform', and 'nvm_versions_dir' keys
-    """
-    return get_claude_detection_paths_structured()
-
-
-def _validate_claude_cli(cli_path: str) -> tuple[bool, str | None]:
-    """
-    Validate that a Claude CLI path is executable and returns a version.
-
-    Includes security validation to prevent command injection attacks.
-
-    Args:
-        cli_path: Path to the Claude CLI executable
-
-    Returns:
-        Tuple of (is_valid, version_string or None)
-
-    Note:
-        Cross-references with frontend's validateClaudeCliAsync() in
-        apps/frontend/src/main/ipc-handlers/claude-code-handlers.ts
-        Both should be kept in sync for consistent behavior.
-    """
-    import re
-
-    # Security validation: reject paths with shell metacharacters or directory traversal
-    if not validate_cli_path(cli_path):
-        logger.warning(f"Rejecting insecure Claude CLI path: {cli_path}")
-        return False, None
-
-    try:
-        # Augment PATH with the CLI directory for proper resolution
-        env = os.environ.copy()
-        cli_dir = os.path.dirname(cli_path)
-        if cli_dir:
-            env["PATH"] = cli_dir + os.pathsep + env.get("PATH", "")
-
-        # For Windows .cmd/.bat files, use cmd.exe with proper quoting
-        # /d = disable AutoRun registry commands
-        # /s = strip first and last quotes, preserving inner quotes
-        # /c = run command then terminate
-        if is_windows() and cli_path.lower().endswith((".cmd", ".bat")):
-            # Get cmd.exe path from platform module
-            cmd_exe = get_comspec_path()
-            # Use double-quoted command line for paths with spaces
-            cmd_line = f'""{cli_path}" --version"'
-            result = subprocess.run(
-                [cmd_exe, "/d", "/s", "/c", cmd_line],
-                capture_output=True,
-                text=True,
-                timeout=5,
-                env=env,
-                creationflags=subprocess.CREATE_NO_WINDOW,
-            )
-        else:
-            result = subprocess.run(
-                [cli_path, "--version"],
-                capture_output=True,
-                text=True,
-                timeout=5,
-                env=env,
-                creationflags=subprocess.CREATE_NO_WINDOW if is_windows() else 0,
-            )
-
-        if result.returncode == 0:
-            # Extract version from output (e.g., "claude-code version 1.0.0")
-            output = result.stdout.strip()
-            match = re.search(r"(\d+\.\d+\.\d+)", output)
-            version = match.group(1) if match else output.split("\n")[0]
-            return True, version
-
-        return False, None
-    except (subprocess.TimeoutExpired, FileNotFoundError, OSError) as e:
-        logger.debug(f"Claude CLI validation failed for {cli_path}: {e}")
-        return False, None
-
-
-def find_claude_cli() -> str | None:
-    """
-    Find the Claude Code CLI binary path.
-
-    Uses cross-platform detection with the following priority:
-    1. CLAUDE_CLI_PATH environment variable (user override)
-    2. shutil.which() - system PATH lookup
-    3. Homebrew paths (macOS)
-    4. NVM paths (Unix - checks Node.js version manager)
-    5. Platform-specific standard locations
-
-    Returns:
-        Path to Claude CLI if found and valid, None otherwise
-    """
-    # Check cache first
-    cache_key = "claude_cli"
-    with _CLI_CACHE_LOCK:
-        if cache_key in _CLAUDE_CLI_CACHE:
-            cached = _CLAUDE_CLI_CACHE[cache_key]
-            logger.debug(f"Using cached Claude CLI path: {cached}")
-            return cached
-
-    paths = _get_claude_detection_paths()
-
-    # 1. Check environment variable override
-    env_path = os.environ.get("CLAUDE_CLI_PATH")
-    if env_path:
-        if Path(env_path).exists():
-            valid, version = _validate_claude_cli(env_path)
-            if valid:
-                logger.info(f"Using CLAUDE_CLI_PATH: {env_path} (v{version})")
-                with _CLI_CACHE_LOCK:
-                    _CLAUDE_CLI_CACHE[cache_key] = env_path
-                return env_path
-        logger.warning(f"CLAUDE_CLI_PATH is set but invalid: {env_path}")
-
-    # 2. Try shutil.which() - most reliable cross-platform PATH lookup
-    which_path = shutil.which("claude")
-    if which_path:
-        valid, version = _validate_claude_cli(which_path)
-        if valid:
-            logger.info(f"Found Claude CLI in PATH: {which_path} (v{version})")
-            with _CLI_CACHE_LOCK:
-                _CLAUDE_CLI_CACHE[cache_key] = which_path
-            return which_path
-
-    # 3. Homebrew paths (macOS)
-    if is_macos():
-        for hb_path in paths["homebrew"]:
-            if Path(hb_path).exists():
-                valid, version = _validate_claude_cli(hb_path)
-                if valid:
-                    logger.info(f"Found Claude CLI (Homebrew): {hb_path} (v{version})")
-                    with _CLI_CACHE_LOCK:
-                        _CLAUDE_CLI_CACHE[cache_key] = hb_path
-                    return hb_path
-
-    # 4. NVM paths (Unix only) - check Node.js version manager installations
-    if not is_windows():
-        nvm_dir = Path(paths["nvm_versions_dir"])
-        if nvm_dir.exists():
-            try:
-                # Get all version directories and sort by version (newest first)
-                version_dirs = []
-                for entry in nvm_dir.iterdir():
-                    if entry.is_dir() and entry.name.startswith("v"):
-                        # Parse version: v20.0.0 -> (20, 0, 0)
-                        try:
-                            parts = entry.name[1:].split(".")
-                            if len(parts) == 3:
-                                version_dirs.append(
-                                    (tuple(int(p) for p in parts), entry.name)
-                                )
-                        except ValueError:
-                            continue
-
-                # Sort by version descending (newest first)
-                version_dirs.sort(reverse=True)
-
-                for _, version_name in version_dirs:
-                    nvm_claude = nvm_dir / version_name / "bin" / "claude"
-                    if nvm_claude.exists():
-                        valid, version = _validate_claude_cli(str(nvm_claude))
-                        if valid:
-                            logger.info(
-                                f"Found Claude CLI (NVM): {nvm_claude} (v{version})"
-                            )
-                            with _CLI_CACHE_LOCK:
-                                _CLAUDE_CLI_CACHE[cache_key] = str(nvm_claude)
-                            return str(nvm_claude)
-            except OSError as e:
-                logger.debug(f"Error scanning NVM directory: {e}")
-
-    # 5. Platform-specific standard locations
-    for plat_path in paths["platform"]:
-        if Path(plat_path).exists():
-            valid, version = _validate_claude_cli(plat_path)
-            if valid:
-                logger.info(f"Found Claude CLI: {plat_path} (v{version})")
-                with _CLI_CACHE_LOCK:
-                    _CLAUDE_CLI_CACHE[cache_key] = plat_path
-                return plat_path
-
-    # Not found
-    logger.warning(
-        "Claude CLI not found. Install with: npm install -g @anthropic-ai/claude-code"
-    )
-    with _CLI_CACHE_LOCK:
-        _CLAUDE_CLI_CACHE[cache_key] = None
-    return None
-
-
-def clear_claude_cli_cache() -> None:
-    """Clear the Claude CLI path cache, forcing re-detection on next call."""
-    with _CLI_CACHE_LOCK:
-        _CLAUDE_CLI_CACHE.clear()
-    logger.debug("Claude CLI cache cleared")
-
-
 from agents.tools_pkg import (
    CONTEXT7_TOOLS,
    ELECTRON_TOOLS,
@@ -358,9 +139,8 @@ from agents.tools_pkg import (
 from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient
 from claude_agent_sdk.types import HookMatcher
 from core.auth import (
+    configure_sdk_authentication,
    get_sdk_env_vars,
-    require_auth_token,
-    validate_token_not_encrypted,
 )
 from linear_updater import is_linear_enabled
 from prompts_pkg.project_context import detect_project_capabilities, load_project_index
@@ -709,19 +489,19 @@ def create_client(
       (see security.py for ALLOWED_COMMANDS)
    4. Tool filtering - Each agent type only sees relevant tools (prevents misuse)
    """
-    oauth_token = require_auth_token()
-
-    # Validate token is not encrypted before passing to SDK
-    # Encrypted tokens (enc:...) should have been decrypted by require_auth_token()
-    # If we still have an encrypted token here, it means decryption failed or was skipped
-    validate_token_not_encrypted(oauth_token)
-
-    # Ensure SDK can access it via its expected env var
-    os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = oauth_token
-
-    # Collect env vars to pass to SDK (ANTHROPIC_BASE_URL, etc.)
+    # Collect env vars to pass to SDK (ANTHROPIC_BASE_URL, CLAUDE_CONFIG_DIR, etc.)
    sdk_env = get_sdk_env_vars()

+    # Get the config dir for profile-specific credential lookup
+    # CLAUDE_CONFIG_DIR enables per-profile Keychain entries with SHA256-hashed service names
+    config_dir = sdk_env.get("CLAUDE_CONFIG_DIR")
+
+    # Configure SDK authentication (OAuth or API profile mode)
+    configure_sdk_authentication(config_dir)
+
+    if config_dir:
+        logger.info(f"Using CLAUDE_CONFIG_DIR for profile: {config_dir}")
+
    # Debug: Log git-bash path detection on Windows
    if "CLAUDE_CODE_GIT_BASH_PATH" in sdk_env:
        logger.info(f"Git Bash path found: {sdk_env['CLAUDE_CODE_GIT_BASH_PATH']}")
@@ -875,7 +655,7 @@ def create_client(

    # Write settings to a file in the project directory
    settings_file = project_dir / ".claude_settings.json"
-    with open(settings_file, "w") as f:
+    with open(settings_file, "w", encoding="utf-8") as f:
        json.dump(security_settings, f, indent=2)

    print(f"Security settings: {settings_file}")
@@ -1013,14 +793,6 @@ def create_client(
        print("   - CLAUDE.md: disabled by project settings")
    print()

-    # Find Claude CLI path for SDK
-    # This ensures the SDK can find the Claude Code binary even if it's not in PATH
-    cli_path = find_claude_cli()
-    if cli_path:
-        print(f"   - Claude CLI: {cli_path}")
-    else:
-        print("   - Claude CLI: using SDK default detection")
-
    # Build options dict, conditionally including output_format
    options_kwargs: dict[str, Any] = {
        "model": model,
@@ -1045,9 +817,12 @@ def create_client(
        "enable_file_checkpointing": True,
    }

-    # Add CLI path if found (helps SDK find Claude Code in non-standard locations)
-    if cli_path:
-        options_kwargs["cli_path"] = cli_path
+    # Optional: Allow CLI path override via environment variable
+    # The SDK bundles its own CLI, but users can override if needed
+    env_cli_path = os.environ.get("CLAUDE_CLI_PATH")
+    if env_cli_path and validate_cli_path(env_cli_path):
+        options_kwargs["cli_path"] = env_cli_path
+        logger.info(f"Using CLAUDE_CLI_PATH override: {env_cli_path}")

    # Add structured output format if specified
    # See: https://platform.claude.com/docs/en/agent-sdk/structured-outputs
@@ -110,7 +110,7 @@ def _write_log(message: str, to_file: bool = True) -> None:
                import re

                clean_message = re.sub(r"\033\[[0-9;]*m", "", message)
-                with open(log_file, "a") as f:
+                with open(log_file, "a", encoding="utf-8") as f:
                    f.write(clean_message + "\n")
            except Exception:
                pass  # Silently fail file logging
@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""
+Git Provider Detection
+======================
+
+Utility to detect git hosting provider (GitHub, GitLab, or unknown) from git remote URLs.
+Supports both SSH and HTTPS remote formats, and self-hosted GitLab instances.
+"""
+
+import re
+from pathlib import Path
+
+from .git_executable import run_git
+
+
+def detect_git_provider(project_dir: str | Path, remote_name: str | None = None) -> str:
+    """Detect the git hosting provider from the git remote URL.
+
+    Args:
+        project_dir: Path to the git repository
+        remote_name: Name of the remote to check (defaults to "origin")
+
+    Returns:
+        'github' if GitHub remote detected
+        'gitlab' if GitLab remote detected (cloud or self-hosted)
+        'unknown' if no remote or unsupported provider
+
+    Examples:
+        >>> detect_git_provider('/path/to/repo')
+        'github'  # for git@github.com:user/repo.git
+        'gitlab'  # for git@gitlab.com:user/repo.git
+        'gitlab'  # for https://gitlab.company.com/user/repo.git
+        'unknown' # for no remote or other providers
+    """
+    try:
+        # Get the remote URL (use specified remote or default to origin)
+        remote = remote_name if remote_name else "origin"
+        result = run_git(
+            ["remote", "get-url", remote],
+            cwd=project_dir,
+            timeout=5,
+        )
+
+        # If command failed or no output, return unknown
+        if result.returncode != 0 or not result.stdout.strip():
+            return "unknown"
+
+        remote_url = result.stdout.strip()
+
+        # Parse ssh:// URL format: ssh://[user@]host[:port]/path
+        ssh_url_match = re.match(r"^ssh://(?:[^@]+@)?([^:/]+)(?::\d+)?/", remote_url)
+        if ssh_url_match:
+            hostname = ssh_url_match.group(1)
+            return _classify_hostname(hostname)
+
+        # Parse HTTPS/HTTP format: https://host/path or http://host/path
+        # Must check before scp-like format to avoid matching "https" as hostname
+        https_match = re.match(r"^https?://([^/]+)/", remote_url)
+        if https_match:
+            hostname = https_match.group(1)
+            return _classify_hostname(hostname)
+
+        # Parse scp-like format: [user@]host:path (any username, not just 'git')
+        # This handles git@github.com:user/repo.git and similar formats
+        scp_match = re.match(r"^(?:[^@]+@)?([^:]+):", remote_url)
+        if scp_match:
+            hostname = scp_match.group(1)
+            # Exclude paths that look like Windows drives (e.g., C:)
+            if len(hostname) > 1:
+                return _classify_hostname(hostname)
+
+        # Unrecognized URL format
+        return "unknown"
+
+    except Exception:
+        # Any error (subprocess issues, etc.) -> unknown
+        return "unknown"
+
+
+def _classify_hostname(hostname: str) -> str:
+    """Classify a hostname as github, gitlab, or unknown.
+
+    Args:
+        hostname: The git remote hostname (e.g., 'github.com', 'gitlab.example.com')
+
+    Returns:
+        'github', 'gitlab', or 'unknown'
+    """
+    hostname_lower = hostname.lower()
+
+    # Check for GitHub (cloud and self-hosted/enterprise)
+    # Match github.com, *.github.com, or domains where a segment is or starts with 'github'
+    hostname_parts = hostname_lower.split(".")
+    if (
+        hostname_lower == "github.com"
+        or hostname_lower.endswith(".github.com")
+        or any(
+            part == "github" or part.startswith("github-") for part in hostname_parts
+        )
+    ):
+        return "github"
+
+    # Check for GitLab (cloud and self-hosted)
+    # Match gitlab.com, *.gitlab.com, or domains where a segment is or starts with 'gitlab'
+    if (
+        hostname_lower == "gitlab.com"
+        or hostname_lower.endswith(".gitlab.com")
+        or any(
+            part == "gitlab" or part.startswith("gitlab-") for part in hostname_parts
+        )
+    ):
+        return "gitlab"
+
+    # Unknown provider
+    return "unknown"
@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""
+GitLab CLI Executable Finder
+============================
+
+Utility to find the glab (GitLab CLI) executable, with platform-specific fallbacks.
+"""
+
+import os
+import shutil
+import subprocess
+
+_cached_glab_path: str | None = None
+
+
+def invalidate_glab_cache() -> None:
+    """Invalidate the cached glab executable path.
+
+    Useful when glab may have been uninstalled, updated, or when
+    GITLAB_CLI_PATH environment variable has changed.
+    """
+    global _cached_glab_path
+    _cached_glab_path = None
+
+
+def _verify_glab_executable(path: str) -> bool:
+    """Verify that a path is a valid glab executable by checking version.
+
+    Args:
+        path: Path to the potential glab executable
+
+    Returns:
+        True if the path points to a valid glab executable, False otherwise
+    """
+    try:
+        result = subprocess.run(
+            [path, "--version"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            timeout=5,
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, OSError):
+        return False
+
+
+def _run_where_command() -> str | None:
+    """Run Windows 'where glab' command to find glab executable.
+
+    Returns:
+        First path found, or None if command failed
+    """
+    try:
+        result = subprocess.run(
+            "where glab",
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            timeout=5,
+            shell=True,  # Required: 'where' command must be executed through shell on Windows
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            found_path = result.stdout.strip().split("\n")[0].strip()
+            if (
+                found_path
+                and os.path.isfile(found_path)
+                and _verify_glab_executable(found_path)
+            ):
+                return found_path
+    except (subprocess.TimeoutExpired, OSError):
+        # 'where' command failed or timed out - fall through to return None
+        pass
+    return None
+
+
+def get_glab_executable() -> str | None:
+    """Find the glab executable, with platform-specific fallbacks.
+
+    Returns the path to glab executable, or None if not found.
+
+    Priority order:
+    1. GITLAB_CLI_PATH env var (user-configured path from frontend)
+    2. shutil.which (if glab is in PATH)
+    3. Homebrew paths on macOS
+    4. Windows Program Files paths
+    5. Windows 'where' command
+
+    Caches the result after first successful find. Use invalidate_glab_cache()
+    to force re-detection (e.g., after glab installation/uninstallation).
+    """
+    global _cached_glab_path
+
+    # Return cached result if available AND still exists
+    if _cached_glab_path is not None and os.path.isfile(_cached_glab_path):
+        return _cached_glab_path
+
+    _cached_glab_path = _find_glab_executable()
+    return _cached_glab_path
+
+
+def _find_glab_executable() -> str | None:
+    """Internal function to find glab executable."""
+    # 1. Check GITLAB_CLI_PATH env var (set by Electron frontend)
+    env_path = os.environ.get("GITLAB_CLI_PATH")
+    if env_path and os.path.isfile(env_path) and _verify_glab_executable(env_path):
+        return env_path
+
+    # 2. Try shutil.which (works if glab is in PATH)
+    glab_path = shutil.which("glab")
+    if glab_path and _verify_glab_executable(glab_path):
+        return glab_path
+
+    # 3. macOS-specific: check Homebrew paths
+    if os.name != "nt":  # Unix-like systems (macOS, Linux)
+        homebrew_paths = [
+            "/opt/homebrew/bin/glab",  # Apple Silicon
+            "/usr/local/bin/glab",  # Intel Mac
+            "/home/linuxbrew/.linuxbrew/bin/glab",  # Linux Homebrew
+        ]
+        for path in homebrew_paths:
+            if os.path.isfile(path) and _verify_glab_executable(path):
+                return path
+
+    # 4. Windows-specific: check Program Files paths
+    # glab uses Inno Setup with DefaultDirName={autopf}\glab
+    if os.name == "nt":
+        windows_paths = [
+            os.path.expandvars(r"%PROGRAMFILES%\glab\glab.exe"),
+            os.path.expandvars(r"%PROGRAMFILES(X86)%\glab\glab.exe"),
+            os.path.expandvars(r"%LOCALAPPDATA%\Programs\glab\glab.exe"),
+        ]
+        for path in windows_paths:
+            if os.path.isfile(path) and _verify_glab_executable(path):
+                return path
+
+        # 5. Try 'where' command with shell=True (more reliable on Windows)
+        return _run_where_command()
+
+    return None
+
+
+def run_glab(
+    args: list[str],
+    cwd: str | None = None,
+    timeout: int = 60,
+    input_data: str | None = None,
+) -> subprocess.CompletedProcess:
+    """Run a glab command with proper executable finding.
+
+    Args:
+        args: glab command arguments (without 'glab' prefix)
+        cwd: Working directory for the command
+        timeout: Command timeout in seconds (default: 60)
+        input_data: Optional string data to pass to stdin
+
+    Returns:
+        CompletedProcess with command results.
+    """
+    glab = get_glab_executable()
+    if not glab:
+        return subprocess.CompletedProcess(
+            args=["glab"] + args,
+            returncode=-1,
+            stdout="",
+            stderr="GitLab CLI (glab) not found. Install from https://gitlab.com/gitlab-org/cli",
+        )
+    try:
+        return subprocess.run(
+            [glab] + args,
+            cwd=cwd,
+            input=input_data,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired:
+        return subprocess.CompletedProcess(
+            args=[glab] + args,
+            returncode=-1,
+            stdout="",
+            stderr=f"Command timed out after {timeout} seconds",
+        )
+    except FileNotFoundError:
+        return subprocess.CompletedProcess(
+            args=[glab] + args,
+            returncode=-1,
+            stdout="",
+            stderr="GitLab CLI (glab) executable not found. Install from https://gitlab.com/gitlab-org/cli",
+        )
@@ -23,6 +23,9 @@ class ExecutionPhase(str, Enum):
    QA_FIXING = "qa_fixing"
    COMPLETE = "complete"
    FAILED = "failed"
+    # Pause states for intelligent error recovery
+    RATE_LIMIT_PAUSED = "rate_limit_paused"
+    AUTH_FAILURE_PAUSED = "auth_failure_paused"


 def emit_phase(
@@ -31,8 +34,19 @@ def emit_phase(
    *,
    progress: int | None = None,
    subtask: str | None = None,
+    reset_timestamp: int | None = None,
+    profile_id: str | None = None,
 ) -> None:
-    """Emit structured phase event to stdout for frontend parsing."""
+    """Emit structured phase event to stdout for frontend parsing.
+
+    Args:
+        phase: The execution phase (e.g., PLANNING, CODING, RATE_LIMIT_PAUSED)
+        message: Optional message describing the phase state
+        progress: Optional progress percentage (0-100)
+        subtask: Optional subtask identifier
+        reset_timestamp: Optional Unix timestamp for rate limit reset time
+        profile_id: Optional profile ID that triggered the pause
+    """
    phase_value = phase.value if isinstance(phase, ExecutionPhase) else phase

    payload: dict[str, Any] = {
@@ -48,6 +62,12 @@ def emit_phase(
    if subtask is not None:
        payload["subtask"] = subtask

+    if reset_timestamp is not None:
+        payload["reset_timestamp"] = reset_timestamp
+
+    if profile_id is not None:
+        payload["profile_id"] = profile_id
+
    try:
        print(f"{PHASE_MARKER_PREFIX}{json.dumps(payload, default=str)}", flush=True)
    except (OSError, UnicodeEncodeError) as e:
@@ -371,7 +371,7 @@ def validate_cli_path(cli_path: str) -> bool:
    Returns:
        True if path is secure, False otherwise
    """
-    if not cli_path:
+    if not cli_path or not cli_path.strip():
        return False

    # Security validation: reject paths with shell metacharacters or other dangerous patterns
@@ -380,7 +380,7 @@ def validate_cli_path(cli_path: str) -> bool:
        r"%[^%]+%",  # Windows environment variable expansion
        r"\.\./",  # Unix directory traversal
        r"\.\.\\",  # Windows directory traversal
-        r"[\r\n]",  # Newlines (command injection)
+        r"[\r\n\x00]",  # Newlines (command injection), null bytes (path truncation)
    ]

    for pattern in dangerous_patterns:
@@ -43,7 +43,7 @@ def count_subtasks(spec_dir: Path) -> tuple[int, int]:
        return 0, 0

    try:
-        with open(plan_file) as f:
+        with open(plan_file, encoding="utf-8") as f:
            plan = json.load(f)

        total = 0
@@ -56,7 +56,7 @@ def count_subtasks(spec_dir: Path) -> tuple[int, int]:
                    completed += 1

        return completed, total
-    except (OSError, json.JSONDecodeError):
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
        return 0, 0


@@ -81,7 +81,7 @@ def count_subtasks_detailed(spec_dir: Path) -> dict:
        return result

    try:
-        with open(plan_file) as f:
+        with open(plan_file, encoding="utf-8") as f:
            plan = json.load(f)

        for phase in plan.get("phases", []):
@@ -94,7 +94,7 @@ def count_subtasks_detailed(spec_dir: Path) -> dict:
                    result["pending"] += 1

        return result
-    except (OSError, json.JSONDecodeError):
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
        return result


@@ -182,7 +182,7 @@ def print_progress_summary(spec_dir: Path, show_next: bool = True) -> None:

        # Phase summary
        try:
-            with open(spec_dir / "implementation_plan.json") as f:
+            with open(spec_dir / "implementation_plan.json", encoding="utf-8") as f:
                plan = json.load(f)

            print("\nPhases:")
@@ -230,8 +230,8 @@ def print_progress_summary(spec_dir: Path, show_next: bool = True) -> None:
                        f"  {icon(Icons.ARROW_RIGHT)} Next: {highlight(next_id)} - {next_desc}"
                    )

-        except (OSError, json.JSONDecodeError):
-            pass
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+            pass  # Ignore corrupted/unreadable progress files
    else:
        print()
        print_status("No implementation subtasks yet - planner needs to run", "pending")
@@ -302,7 +302,7 @@ def get_plan_summary(spec_dir: Path) -> dict:
        }

    try:
-        with open(plan_file) as f:
+        with open(plan_file, encoding="utf-8") as f:
            plan = json.load(f)

        summary = {
@@ -355,7 +355,7 @@ def get_plan_summary(spec_dir: Path) -> dict:

        return summary

-    except (OSError, json.JSONDecodeError):
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
        return {
            "workflow_type": None,
            "total_phases": 0,
@@ -376,7 +376,7 @@ def get_current_phase(spec_dir: Path) -> dict | None:
        return None

    try:
-        with open(plan_file) as f:
+        with open(plan_file, encoding="utf-8") as f:
            plan = json.load(f)

        for phase in plan.get("phases", []):
@@ -396,7 +396,7 @@ def get_current_phase(spec_dir: Path) -> dict | None:

        return None

-    except (OSError, json.JSONDecodeError):
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
        return None


@@ -470,7 +470,7 @@ def get_next_subtask(spec_dir: Path) -> dict | None:

        return None

-    except (OSError, json.JSONDecodeError):
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
        return None


@@ -53,7 +53,7 @@ def _get_version() -> str:
        if package_json.exists():
            import json

-            with open(package_json) as f:
+            with open(package_json, encoding="utf-8") as f:
                data = json.load(f)
                return data.get("version", "0.0.0")
    except Exception as e:
@@ -21,18 +21,21 @@ Example usage:
    client = create_simple_client(agent_type="insights", cwd=project_dir)
 """

+import logging
+import os
 from pathlib import Path

 from agents.tools_pkg import get_agent_config, get_default_thinking_level
 from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient
 from core.auth import (
+    configure_sdk_authentication,
    get_sdk_env_vars,
-    require_auth_token,
-    validate_token_not_encrypted,
 )
-from core.client import find_claude_cli
+from core.platform import validate_cli_path
 from phase_config import get_thinking_budget

+logger = logging.getLogger(__name__)
+

 def create_simple_client(
    agent_type: str = "merge_resolver",
@@ -69,21 +72,16 @@ def create_simple_client(
    Raises:
        ValueError: If agent_type is not found in AGENT_CONFIGS
    """
-    # Get authentication
-    oauth_token = require_auth_token()
-
-    # Validate token is not encrypted before passing to SDK
-    # Encrypted tokens (enc:...) should have been decrypted by require_auth_token()
-    # If we still have an encrypted token here, it means decryption failed or was skipped
-    validate_token_not_encrypted(oauth_token)
-
-    import os
-
-    os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = oauth_token
-
-    # Get environment variables for SDK
+    # Get environment variables for SDK (including CLAUDE_CONFIG_DIR if set)
    sdk_env = get_sdk_env_vars()

+    # Get the config dir for profile-specific credential lookup
+    # CLAUDE_CONFIG_DIR enables per-profile Keychain entries with SHA256-hashed service names
+    config_dir = sdk_env.get("CLAUDE_CONFIG_DIR")
+
+    # Configure SDK authentication (OAuth or API profile mode)
+    configure_sdk_authentication(config_dir)
+
    # Get agent configuration (raises ValueError if unknown type)
    config = get_agent_config(agent_type)

@@ -95,10 +93,8 @@ def create_simple_client(
        thinking_level = get_default_thinking_level(agent_type)
        max_thinking_tokens = get_thinking_budget(thinking_level)

-    # Find Claude CLI path (handles non-standard installations)
-    cli_path = find_claude_cli()
-
    # Build options dict
+    # Note: SDK bundles its own CLI, so no cli_path detection needed
    options_kwargs = {
        "model": model,
        "system_prompt": system_prompt,
@@ -112,8 +108,10 @@ def create_simple_client(
    if max_thinking_tokens is not None:
        options_kwargs["max_thinking_tokens"] = max_thinking_tokens

-    # Add CLI path if found
-    if cli_path:
-        options_kwargs["cli_path"] = cli_path
+    # Optional: Allow CLI path override via environment variable
+    env_cli_path = os.environ.get("CLAUDE_CLI_PATH")
+    if env_cli_path and validate_cli_path(env_cli_path):
+        options_kwargs["cli_path"] = env_cli_path
+        logger.info(f"Using CLAUDE_CLI_PATH override: {env_cli_path}")

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

 MODULE = "workspace"

@@ -145,6 +146,26 @@ MODULE = "workspace"
 # - _heuristic_merge


+def _create_merge_progress_callback() -> MergeProgressCallback | None:
+    """
+    Create a progress callback for merge operations when running as a subprocess.
+
+    Returns emit_progress (writing JSON to stdout) only when stdout is piped
+    (i.e., running as a subprocess from the Electron frontend). Returns None
+    when running interactively in a terminal to avoid polluting CLI output.
+
+    This function must be called at runtime (not at import time) to ensure
+    sys.stdout state is accurate.
+    """
+    import sys
+
+    # Only emit progress JSON when stdout is piped (subprocess mode).
+    # In interactive CLI mode (TTY), progress JSON would clutter the output.
+    if not sys.stdout.isatty():
+        return emit_progress
+    return None
+
+
 def merge_existing_build(
    project_dir: Path,
    spec_name: str,
@@ -252,10 +273,11 @@ def merge_existing_build(
                had_conflicts = stats.get("conflicts_resolved", 0) > 0
                ai_assisted = stats.get("ai_assisted", 0) > 0
                direct_copy = stats.get("direct_copy", False)
+                git_merge_used = stats.get("git_merge", False)

-                if had_conflicts or ai_assisted or direct_copy:
-                    # AI resolved conflicts, assisted with merges, or direct copy was used
-                    # Changes are already written and staged - no need for git merge
+                if had_conflicts or ai_assisted or direct_copy or git_merge_used:
+                    # AI resolved conflicts, assisted with merges, git merge was used, or direct copy was used
+                    # Changes are already written and staged - no need for additional git merge
                    _print_merge_success(
                        no_commit, stats, spec_name=spec_name, keep_worktree=True
                    )
@@ -402,9 +424,20 @@ def _try_smart_merge_inner(
        no_commit=no_commit,
    )

+    # Create progress callback for subprocess mode (Electron frontend).
+    # Only emits JSON to stdout when piped, not in interactive CLI.
+    progress_callback = _create_merge_progress_callback()
+
    try:
        print(muted("  Analyzing changes with intent-aware merge..."))

+        if progress_callback is not None:
+            progress_callback(
+                MergeProgressStage.ANALYZING,
+                0,
+                "Starting merge analysis",
+            )
+
        # Capture worktree state in FileTimelineTracker before merge
        try:
            timeline_tracker = FileTimelineTracker(project_dir)
@@ -440,6 +473,13 @@ def _try_smart_merge_inner(
        )

        # Check for git-level conflicts first (branch divergence)
+        if progress_callback is not None:
+            progress_callback(
+                MergeProgressStage.DETECTING_CONFLICTS,
+                25,
+                "Checking for git-level conflicts",
+            )
+
        debug(MODULE, "Checking for git-level conflicts")
        git_conflicts = _check_git_conflicts(project_dir, spec_name)

@@ -492,12 +532,11 @@ def _try_smart_merge_inner(
                # If rebase succeeded and now there are no conflicts,
                # the diverged_but_no_conflicts path will handle the merge
            else:
-                # Rebase failed - continue with conflict resolution as before
-                # The AI resolver will handle the conflicts
-                print(
-                    warning(
-                        "  Rebase encountered issues, using AI conflict resolution..."
-                    )
+                # Rebase failed (likely due to worktree lock) - continue with merge
+                # Git merge or AI resolver will handle it depending on conflict state
+                debug(
+                    MODULE,
+                    "Rebase skipped or failed, continuing with merge flow",
                )

        if git_conflicts.get("has_conflicts"):
@@ -518,6 +557,18 @@ def _try_smart_merge_inner(
                num_conflicts=len(git_conflicts.get("conflicting_files", [])),
            )

+            if progress_callback is not None:
+                progress_callback(
+                    MergeProgressStage.RESOLVING,
+                    50,
+                    f"Resolving {len(git_conflicts.get('conflicting_files', []))} conflicting files with AI",
+                    {
+                        "conflicts_found": len(
+                            git_conflicts.get("conflicting_files", [])
+                        )
+                    },
+                )
+
            # Try to resolve git conflicts with AI
            resolution_result = _resolve_git_conflicts_with_ai(
                project_dir,
@@ -535,6 +586,22 @@ def _try_smart_merge_inner(
                    resolved_files=resolution_result.get("resolved_files", []),
                    stats=resolution_result.get("stats", {}),
                )
+
+                if progress_callback is not None:
+                    stats = resolution_result.get("stats", {})
+                    original_conflict_count = len(
+                        git_conflicts.get("conflicting_files", [])
+                    )
+                    progress_callback(
+                        MergeProgressStage.COMPLETE,
+                        100,
+                        "Merge complete",
+                        {
+                            "conflicts_found": original_conflict_count,
+                            "conflicts_resolved": stats.get("conflicts_resolved", 0),
+                        },
+                    )
+
                return resolution_result
            else:
                # AI couldn't resolve all conflicts
@@ -547,6 +614,26 @@ def _try_smart_merge_inner(
                    resolved_files=resolution_result.get("resolved_files", []),
                    error=resolution_result.get("error"),
                )
+
+                if progress_callback is not None:
+                    original_conflict_count = len(
+                        git_conflicts.get("conflicting_files", [])
+                    )
+                    remaining_count = len(
+                        resolution_result.get("remaining_conflicts", [])
+                    )
+                    progress_callback(
+                        MergeProgressStage.ERROR,
+                        0,
+                        "Some conflicts could not be resolved",
+                        {
+                            "conflicts_found": original_conflict_count,
+                            "conflicts_resolved": original_conflict_count
+                            - remaining_count,
+                            "conflicts_remaining": remaining_count,
+                        },
+                    )
+
                return {
                    "success": False,
                    "conflicts": resolution_result.get("remaining_conflicts", []),
@@ -555,148 +642,81 @@ def _try_smart_merge_inner(
                    "error": resolution_result.get("error"),
                }

-        # Check if branches diverged but no actual conflicts (can do direct copy)
+        # Check if branches diverged but no actual conflicts (use git merge)
        if git_conflicts.get("diverged_but_no_conflicts"):
-            debug(MODULE, "Branches diverged but no conflicts - doing direct file copy")
+            debug(MODULE, "Branches diverged but no conflicts - using git merge")
            print(muted("  Branches diverged but no conflicts detected"))
-            print(muted("  Copying changed files directly from worktree..."))
+            print(muted("  Using git merge to combine changes..."))

-            # Get changed files from spec branch
            spec_branch = f"auto-claude/{spec_name}"
-            base_branch = git_conflicts.get("base_branch", "main")

-            # Get merge-base for diff
-            merge_base_result = run_git(
-                ["merge-base", base_branch, spec_branch],
+            # Use git merge --no-commit to combine changes from both branches
+            # Since merge-tree confirmed no conflicts, this should succeed cleanly
+            merge_result = run_git(
+                ["merge", "--no-commit", "--no-ff", spec_branch],
                cwd=project_dir,
            )
-            merge_base = (
-                merge_base_result.stdout.strip()
-                if merge_base_result.returncode == 0
-                else None
-            )

-            if merge_base:
-                # Get list of changed files in spec branch
-                changed_files = _get_changed_files_from_branch(
-                    project_dir, merge_base, spec_branch
+            if merge_result.returncode == 0:
+                # Merge succeeded - get list of files that were merged
+                # Use git diff --cached to see what's staged
+                diff_result = run_git(
+                    ["diff", "--cached", "--name-only"],
+                    cwd=project_dir,
+                )
+                merged_files = [
+                    f.strip()
+                    for f in diff_result.stdout.splitlines()
+                    if f.strip() and not _is_auto_claude_file(f.strip())
+                ]
+
+                debug_success(
+                    MODULE,
+                    "Git merge succeeded",
+                    merged_files_count=len(merged_files),
                )

-                resolved_files = []
-                skipped_files = []  # Track files that failed to copy
-                files_to_stage = []
-                for file_path, status in changed_files:
-                    if _is_auto_claude_file(file_path):
-                        continue
+                for file_path in merged_files:
+                    print(success(f"    ✓ {file_path}"))

-                    try:
-                        target_path = project_dir / file_path
-
-                        if status == "D":
-                            # Deleted in worktree
-                            if target_path.exists():
-                                target_path.unlink()
-                            files_to_stage.append(file_path)
-                            resolved_files.append(file_path)
-                            print(success(f"    ✓ {file_path} (deleted)"))
-                        else:
-                            # New or modified - copy from spec branch
-                            target_path.parent.mkdir(parents=True, exist_ok=True)
-
-                            if _is_binary_file(file_path):
-                                binary_content = _get_binary_file_content_from_ref(
-                                    project_dir, spec_branch, file_path
-                                )
-                                if binary_content is not None:
-                                    target_path.write_bytes(binary_content)
-                                    files_to_stage.append(file_path)
-                                    resolved_files.append(file_path)
-                                    status_label = (
-                                        "new file" if status == "A" else "updated"
-                                    )
-                                    print(
-                                        success(f"    ✓ {file_path} ({status_label})")
-                                    )
-                                else:
-                                    skipped_files.append(file_path)
-                                    debug_warning(
-                                        MODULE,
-                                        f"Could not retrieve binary content for {file_path}",
-                                    )
-                            else:
-                                content = _get_file_content_from_ref(
-                                    project_dir, spec_branch, file_path
-                                )
-                                if content is not None:
-                                    target_path.write_text(content, encoding="utf-8")
-                                    files_to_stage.append(file_path)
-                                    resolved_files.append(file_path)
-                                    status_label = (
-                                        "new file" if status == "A" else "updated"
-                                    )
-                                    print(
-                                        success(f"    ✓ {file_path} ({status_label})")
-                                    )
-                                else:
-                                    skipped_files.append(file_path)
-                                    debug_warning(
-                                        MODULE,
-                                        f"Could not retrieve content for {file_path}",
-                                    )
-
-                    except Exception as e:
-                        skipped_files.append(file_path)
-                        debug_warning(MODULE, f"Could not copy {file_path}: {e}")
-
-                # Stage all files in a single git add call for efficiency
-                if files_to_stage:
-                    add_result = run_git(
-                        ["add"] + files_to_stage,
-                        cwd=project_dir,
+                if progress_callback is not None:
+                    progress_callback(
+                        MergeProgressStage.COMPLETE,
+                        100,
+                        f"Git merge complete ({len(merged_files)} files)",
                    )
-                    if add_result.returncode != 0:
-                        debug_warning(
-                            MODULE,
-                            f"Failed to stage files for direct copy: {add_result.stderr}",
-                        )
-                        # Return failure - files were written but not staged
-                        return {
-                            "success": False,
-                            "error": f"Failed to stage files: {add_result.stderr}",
-                            "resolved_files": [],
-                        }

-                # Build result - check for skipped files to detect partial merges
-                result = {
-                    "success": len(skipped_files) == 0,
-                    "resolved_files": resolved_files,
+                return {
+                    "success": True,
+                    "resolved_files": merged_files,
                    "stats": {
-                        "files_merged": len(resolved_files),
+                        "files_merged": len(merged_files),
                        "conflicts_resolved": 0,
                        "ai_assisted": 0,
-                        "auto_merged": len(resolved_files),
-                        "direct_copy": True,  # Flag indicating direct copy was used
-                        "skipped_count": len(skipped_files),
+                        "auto_merged": len(merged_files),
+                        "git_merge": True,  # Flag indicating git merge was used
                    },
                }
-                if skipped_files:
-                    result["skipped_files"] = skipped_files
-                    result["partial_success"] = len(resolved_files) > 0
-                    print()
-                    print(
-                        warning(
-                            f"  ⚠ {len(skipped_files)} file(s) could not be retrieved:"
-                        )
-                    )
-                    for skipped_file in skipped_files:
-                        print(muted(f"    - {skipped_file}"))
-                    print(muted("  These files may need manual review."))
-                return result
            else:
-                # merge-base failed - branches may not share history
+                # Merge failed unexpectedly - abort and fall back to semantic analysis
                debug_warning(
                    MODULE,
-                    "Could not find merge-base between branches - falling back to semantic analysis",
+                    "Git merge failed unexpectedly despite no conflicts detected",
+                    stderr=merge_result.stderr[:500] if merge_result.stderr else "",
+                )
+                # Abort the merge to restore clean state
+                abort_result = run_git(["merge", "--abort"], cwd=project_dir)
+                if abort_result.returncode != 0:
+                    debug_error(
+                        MODULE,
+                        "Failed to abort merge - repo may be in inconsistent state",
+                        stderr=abort_result.stderr,
+                    )
+                    return None  # Trigger fallback to avoid operating on inconsistent state
+                print(
+                    warning(
+                        "  Git merge failed unexpectedly, falling back to semantic analysis..."
+                    )
                )

        # No git conflicts - proceed with semantic analysis
@@ -725,6 +745,14 @@ def _try_smart_merge_inner(

        # All conflicts can be auto-merged or no conflicts
        print(muted("  All changes compatible, proceeding with merge..."))
+
+        if progress_callback is not None:
+            progress_callback(
+                MergeProgressStage.COMPLETE,
+                100,
+                f"Analysis complete ({files_to_merge} files compatible)",
+            )
+
        return {
            "success": True,
            "stats": {
@@ -737,6 +765,13 @@ def _try_smart_merge_inner(
        # If smart merge fails, fall back to git
        import traceback

+        if progress_callback is not None:
+            progress_callback(
+                MergeProgressStage.ERROR,
+                0,
+                f"Smart merge error: {e}",
+            )
+
        print(muted(f"  Smart merge error: {e}"))
        traceback.print_exc()
        return None
@@ -748,14 +783,11 @@ def _rebase_spec_branch(
    base_branch: str,
 ) -> bool:
    """
-    Rebase the spec branch onto the latest base branch.
+    Attempt to rebase the spec branch onto the latest base branch.

-    This performs an automatic rebase of the spec branch onto the current
-    base branch (main/develop) to bring it up to date before merging.
-    If conflicts occur during rebase, the function aborts and returns False
-    so that the caller can fall back to AI conflict resolution.
-
-    The function preserves the current HEAD by restoring it after completion.
+    NOTE: This will fail if the spec branch is checked out in a worktree,
+    which is the normal case. The caller should handle failure gracefully
+    by falling back to git merge or AI conflict resolution.

    Args:
        project_dir: The project directory
@@ -764,22 +796,36 @@ def _rebase_spec_branch(

    Returns:
        True if rebase succeeded cleanly or branch was already up-to-date,
-        False if rebase failed due to conflicts or other errors (aborted, no ref movement)
+        False if rebase failed (worktree lock, conflicts, or other errors)
    """
    spec_branch = f"auto-claude/{spec_name}"

    debug(
        MODULE,
-        "Rebasing spec branch",
+        "Attempting to rebase spec branch",
        spec_branch=spec_branch,
        base_branch=base_branch,
    )

-    # Save original branch to restore after rebase (HIGH: prevents leaving repo on spec branch)
+    # Check if spec branch is used by a worktree (common case)
+    # In this case, we can't checkout/rebase from the main repo
+    worktree_list_result = run_git(["worktree", "list", "--porcelain"], cwd=project_dir)
+    if worktree_list_result.returncode == 0:
+        # Check if spec_branch is in use by a worktree
+        output = worktree_list_result.stdout
+        if f"branch refs/heads/{spec_branch}" in output:
+            debug(
+                MODULE,
+                "Spec branch is checked out in a worktree - skipping rebase",
+                spec_branch=spec_branch,
+            )
+            # This is expected - return False to let caller use git merge instead
+            return False
+
+    # Save original branch to restore after rebase
    original_branch_result = run_git(
        ["rev-parse", "--abbrev-ref", "HEAD"], cwd=project_dir
    )
-    # Check returncode and validate stdout before using original_branch
    if original_branch_result.returncode != 0:
        debug_error(
            MODULE,
@@ -795,7 +841,6 @@ def _rebase_spec_branch(
        )
        return False

-    # Save current state for recovery
    # Get the current commit of spec_branch before rebase
    before_commit_result = run_git(["rev-parse", spec_branch], cwd=project_dir)
    if before_commit_result.returncode != 0:
@@ -804,8 +849,6 @@ def _rebase_spec_branch(
            "Could not get spec branch commit before rebase",
            stderr=before_commit_result.stderr,
        )
-        # Restore original branch before returning
-        run_git(["checkout", original_branch], cwd=project_dir)
        return False
    before_commit = before_commit_result.stdout.strip()

@@ -813,22 +856,18 @@ def _rebase_spec_branch(
    print(muted(f"  Rebasing {spec_branch} onto {base_branch}..."))

    try:
-        # Perform the rebase using safe/standard invocation:
-        # 1. Checkout the spec branch first
-        # 2. Run standard rebase (no strategy options - let conflicts stop the rebase)
-        # If conflicts occur, we'll abort and let AI handle them during merge
+        # Try to checkout the spec branch
        checkout_result = run_git(["checkout", spec_branch], cwd=project_dir)
        if checkout_result.returncode != 0:
-            debug_error(
+            # Checkout failed - likely due to worktree lock
+            debug(
                MODULE,
-                "Could not checkout spec branch for rebase",
-                stderr=checkout_result.stderr,
+                "Could not checkout spec branch for rebase (likely worktree lock)",
+                stderr=checkout_result.stderr[:200] if checkout_result.stderr else "",
            )
            return False

-        # Run standard rebase - will stop on conflicts so we can detect them
-        # Git syntax: git rebase [options] <upstream>
-        # where <upstream> is the branch to rebase onto
+        # Run standard rebase
        rebase_result = run_git(
            ["rebase", base_branch],
            cwd=project_dir,
@@ -838,9 +877,6 @@ def _rebase_spec_branch(
            # Rebase failed - check if it was due to conflicts
            status_result = run_git(["status", "--porcelain"], cwd=project_dir)

-            # MEDIUM: Properly parse git status output for conflict markers
-            # Git status --porcelain uses two-character status codes:
-            # UU = both modified, AA = both added, DD = both deleted, etc.
            has_unmerged = any(
                line[:2] in ("UU", "AA", "DD", "AU", "UA", "DU", "UD")
                for line in status_result.stdout.splitlines()
@@ -848,7 +884,6 @@ def _rebase_spec_branch(
            )

            # Abort the rebase to return to clean state
-            # NEW-002: If abort fails, immediately return False (repo in bad state)
            abort_result = run_git(["rebase", "--abort"], cwd=project_dir)
            if abort_result.returncode != 0:
                debug_error(
@@ -856,19 +891,16 @@ def _rebase_spec_branch(
                    "Failed to abort rebase - repo may be in inconsistent state",
                    stderr=abort_result.stderr,
                )
-                return False  # Abort failed - cannot safely continue
-
-            if has_unmerged:
-                # Rebase failed due to conflicts - we aborted, so no ref movement happened
-                debug_warning(
-                    MODULE,
-                    "Rebase encountered conflicts - aborted, will use AI conflict resolution",
-                    stderr=rebase_result.stderr[:200] if rebase_result.stderr else "",
-                )
-                # Return False since we aborted - no rebase occurred, caller should use AI
                return False

-            # Other error (not conflict-related)
+            if has_unmerged:
+                debug_warning(
+                    MODULE,
+                    "Rebase encountered conflicts - aborted, will use alternative merge",
+                    stderr=rebase_result.stderr[:200] if rebase_result.stderr else "",
+                )
+                return False
+
            debug_error(
                MODULE,
                "Rebase failed with unexpected error",
@@ -882,9 +914,7 @@ def _rebase_spec_branch(
        if after_commit_result.returncode == 0:
            after_commit_hash = after_commit_result.stdout.strip()

-            # Verify the branch actually moved (commit changed)
            if before_commit == after_commit_hash:
-                # MEDIUM: Branch already up-to-date is a success condition, not failure
                debug(
                    MODULE,
                    "Branch already up-to-date, no rebase needed",
@@ -904,8 +934,7 @@ def _rebase_spec_branch(
        debug_error(MODULE, "Could not verify spec branch commit after rebase")
        return False
    finally:
-        # HIGH: Always restore original branch, even on error/exception
-        # NEW-001: Log restoration failure (cannot modify return from finally block)
+        # Always restore original branch
        if original_branch:
            restore_result = run_git(["checkout", original_branch], cwd=project_dir)
            if restore_result.returncode != 0:
@@ -914,8 +943,6 @@ def _rebase_spec_branch(
                    f"Failed to restore original branch '{original_branch}'",
                    stderr=restore_result.stderr,
                )
-                # Note: Cannot modify return value from finally block,
-                # but restoration failure is rare and non-critical (user can manually switch back)


 def _check_git_conflicts(project_dir: Path, spec_name: str) -> dict:
@@ -93,7 +93,7 @@ class MergeLock:
                os.close(fd)

                # Write our PID to the lock file
-                self.lock_file.write_text(str(os.getpid()))
+                self.lock_file.write_text(str(os.getpid()), encoding="utf-8")
                self.acquired = True
                return self

@@ -101,7 +101,7 @@ class MergeLock:
                # Lock file exists - check if process is still running
                if self.lock_file.exists():
                    try:
-                        pid = int(self.lock_file.read_text().strip())
+                        pid = int(self.lock_file.read_text(encoding="utf-8").strip())
                        # Import locally to avoid circular dependency
                        import os as _os

@@ -183,7 +183,7 @@ class SpecNumberLock:
                os.close(fd)

                # Write our PID to the lock file
-                self.lock_file.write_text(str(os.getpid()))
+                self.lock_file.write_text(str(os.getpid()), encoding="utf-8")
                self.acquired = True
                return self

@@ -191,7 +191,7 @@ class SpecNumberLock:
                # Lock file exists - check if process is still running
                if self.lock_file.exists():
                    try:
-                        pid = int(self.lock_file.read_text().strip())
+                        pid = int(self.lock_file.read_text(encoding="utf-8").strip())
                        import os as _os

                        try:
@@ -325,6 +325,7 @@ def setup_workspace(
    mode: WorkspaceMode,
    source_spec_dir: Path | None = None,
    base_branch: str | None = None,
+    use_local_branch: bool = False,
 ) -> tuple[Path, WorktreeManager | None, Path | None]:
    """
    Set up the workspace based on user's choice.
@@ -337,6 +338,7 @@ def setup_workspace(
        mode: The workspace mode to use
        source_spec_dir: Optional source spec directory to copy to worktree
        base_branch: Base branch for worktree creation (default: current branch)
+        use_local_branch: If True, use local branch directly instead of preferring origin/branch

    Returns:
        Tuple of (working_directory, worktree_manager or None, localized_spec_dir or None)
@@ -357,7 +359,9 @@ def setup_workspace(
    # Ensure timeline tracking hook is installed (once per session)
    ensure_timeline_hook_installed(project_dir)

-    manager = WorktreeManager(project_dir, base_branch=base_branch)
+    manager = WorktreeManager(
+        project_dir, base_branch=base_branch, use_local_branch=use_local_branch
+    )
    manager.setup()

    # Get or create worktree for THIS SPECIFIC SPEC
@@ -412,10 +416,10 @@ def setup_workspace(
        if PROFILE_FILENAME in security_files_copied:
            profile_path = worktree_info.path / PROFILE_FILENAME
            try:
-                with open(profile_path) as f:
+                with open(profile_path, encoding="utf-8") as f:
                    profile_data = json.load(f)
                profile_data["inherited_from"] = str(project_dir.resolve())
-                with open(profile_path, "w") as f:
+                with open(profile_path, "w", encoding="utf-8") as f:
                    json.dump(profile_data, f, indent=2)
                debug(
                    MODULE, f"Marked security profile as inherited from {project_dir}"
@@ -474,7 +478,7 @@ def ensure_timeline_hook_installed(project_dir: Path) -> None:

        # Handle worktrees (where .git is a file, not directory)
        if git_dir.is_file():
-            content = git_dir.read_text().strip()
+            content = git_dir.read_text(encoding="utf-8").strip()
            if content.startswith("gitdir:"):
                git_dir = Path(content.split(":", 1)[1].strip())
            else:
@@ -484,7 +488,7 @@ def ensure_timeline_hook_installed(project_dir: Path) -> None:

        # Check if hook already installed
        if hook_path.exists():
-            if "FileTimelineTracker" in hook_path.read_text():
+            if "FileTimelineTracker" in hook_path.read_text(encoding="utf-8"):
                debug(MODULE, "FileTimelineTracker hook already installed")
                return

@@ -522,7 +526,7 @@ def initialize_timeline_tracking(
        if source_spec_dir:
            plan_path = source_spec_dir / "implementation_plan.json"
            if plan_path.exists():
-                with open(plan_path) as f:
+                with open(plan_path, encoding="utf-8") as f:
                    plan = json.load(f)
                task_title = plan.get("title", spec_name)
                task_intent = plan.get("description", "")
@@ -533,6 +537,7 @@ def initialize_timeline_tracking(
                        files_to_modify.extend(subtask.get("files", []))

        # Get the current branch point commit
+        # Note: run_git() already handles capture_output and encoding internally
        result = run_git(
            ["rev-parse", "HEAD"],
            cwd=project_dir,
@@ -15,6 +15,8 @@ This allows:
 """

 import asyncio
+import json
+import logging
 import os
 import re
 import shutil
@@ -28,8 +30,13 @@ from typing import TypedDict, TypeVar

 from core.gh_executable import get_gh_executable, invalidate_gh_cache
 from core.git_executable import get_git_executable, get_isolated_git_env, run_git
+from core.git_provider import detect_git_provider
+from core.glab_executable import get_glab_executable, invalidate_glab_cache
+from core.model_config import get_utility_model_config
 from debug import debug_warning

+logger = logging.getLogger(__name__)
+
 T = TypeVar("T")


@@ -136,6 +143,7 @@ class PushAndCreatePRResult(TypedDict, total=False):
    pushed: bool
    remote: str
    branch: str
+    provider: str  # 'github', 'gitlab', or 'unknown'
    pr_url: str | None  # None when PR was created but URL couldn't be extracted
    already_exists: bool
    error: str
@@ -175,12 +183,18 @@ class WorktreeManager:

    # Timeout constants for subprocess operations
    GIT_PUSH_TIMEOUT = 120  # 2 minutes for git push (network operations)
-    GH_CLI_TIMEOUT = 60  # 1 minute for gh CLI commands
-    GH_QUERY_TIMEOUT = 30  # 30 seconds for gh CLI queries
+    CLI_TIMEOUT = 60  # 1 minute for CLI commands (gh/glab)
+    CLI_QUERY_TIMEOUT = 30  # 30 seconds for CLI queries (gh/glab)

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

@@ -349,6 +363,28 @@ class WorktreeManager:

        actual_branch = result.stdout.strip()

+        # Handle detached HEAD state: rev-parse --abbrev-ref returns literal "HEAD"
+        # when the worktree is in detached HEAD (e.g. after rebase, merge conflict, etc.)
+        # First try to resolve the branch from git's worktree registry, then fall back
+        # to the expected branch name derived from the spec name.
+        if actual_branch == "HEAD":
+            registered_branch = self._get_worktree_registered_branch(worktree_path)
+            if registered_branch:
+                debug_warning(
+                    "worktree",
+                    f"Worktree '{spec_name}' is in detached HEAD state. "
+                    f"Resolved branch from git worktree registry: {registered_branch}",
+                )
+                actual_branch = registered_branch
+            else:
+                expected_branch = self.get_branch_name(spec_name)
+                debug_warning(
+                    "worktree",
+                    f"Worktree '{spec_name}' is in detached HEAD state. "
+                    f"Using expected branch name: {expected_branch}",
+                )
+                actual_branch = expected_branch
+
        # Get statistics
        stats = self._get_worktree_stats(spec_name)

@@ -361,6 +397,50 @@ class WorktreeManager:
            **stats,
        )

+    def _get_worktree_registered_branch(self, worktree_path: Path) -> str | None:
+        """
+        Get the branch name for a worktree from git's worktree registry.
+
+        Uses `git worktree list --porcelain` to find the branch associated with
+        a worktree path. This works even when the worktree is in detached HEAD state,
+        as git tracks the original branch association in its registry.
+
+        Args:
+            worktree_path: The path to the worktree directory.
+
+        Returns:
+            The branch name (without refs/heads/ prefix) if found, None otherwise.
+        """
+        result = self._run_git(["worktree", "list", "--porcelain"])
+        if result.returncode != 0:
+            return None
+
+        resolved_path = worktree_path.resolve()
+
+        # Parse porcelain output: entries are separated by blank lines,
+        # each entry has "worktree <path>", "HEAD <sha>", "branch refs/heads/<name>"
+        # (or "detached" instead of "branch" if truly detached in registry too)
+        current_path = None
+        for line in result.stdout.split("\n"):
+            if line.startswith("worktree "):
+                current_path = Path(line.split(" ", 1)[1])
+            elif line.startswith("branch refs/heads/") and current_path is not None:
+                try:
+                    if current_path.exists() and resolved_path.exists():
+                        if os.path.samefile(resolved_path, current_path):
+                            return line[len("branch refs/heads/") :]
+                except OSError:
+                    pass
+                # Fallback to normalized case comparison
+                if os.path.normcase(str(resolved_path)) == os.path.normcase(
+                    str(current_path)
+                ):
+                    return line[len("branch refs/heads/") :]
+            elif line == "":
+                current_path = None
+
+        return None
+
    def _check_branch_namespace_conflict(self) -> str | None:
        """
        Check if a branch named 'auto-claude' exists, which would block creating
@@ -378,6 +458,66 @@ class WorktreeManager:
            return "auto-claude"
        return None

+    def _branch_exists(self, branch_name: str) -> bool:
+        """
+        Check if a local branch exists in the repository.
+
+        Uses git show-ref to specifically check for local branches, avoiding
+        false positives from tags or other refs with the same name.
+
+        Args:
+            branch_name: The name of the branch to check (e.g., 'auto-claude/my-spec')
+
+        Returns:
+            True if the local branch exists, False otherwise.
+        """
+        result = self._run_git(["show-ref", "--verify", f"refs/heads/{branch_name}"])
+        return result.returncode == 0
+
+    def _worktree_is_registered(self, worktree_path: Path) -> bool:
+        """
+        Check if a worktree path is registered with git.
+
+        This determines if git tracks the worktree even if the directory exists.
+        Useful for detecting orphaned worktree directories that need cleanup.
+
+        Args:
+            worktree_path: The path to the worktree directory to check.
+
+        Returns:
+            True if the worktree is registered with git, False otherwise.
+        """
+        result = self._run_git(["worktree", "list", "--porcelain"])
+        if result.returncode != 0:
+            return False
+
+        # Parse porcelain output to get registered worktree paths
+        # Format: "worktree /path/to/worktree" for each worktree
+        registered_paths = set()
+        for line in result.stdout.split("\n"):
+            if line.startswith("worktree "):
+                parts = line.split(" ", 1)
+                if len(parts) == 2:
+                    registered_paths.add(Path(parts[1]))
+
+        # Check if worktree_path matches any registered path
+        # Use samefile() for accurate comparison on case-insensitive filesystems
+        resolved_path = worktree_path.resolve()
+        for registered_path in registered_paths:
+            # Try samefile first (handles case-insensitivity and symlinks)
+            try:
+                if resolved_path.exists() and registered_path.exists():
+                    if os.path.samefile(resolved_path, registered_path):
+                        return True
+            except OSError:
+                pass
+            # Fallback to normalized case comparison for non-existent paths
+            if os.path.normcase(str(resolved_path)) == os.path.normcase(
+                str(registered_path)
+            ):
+                return True
+        return False
+
    def _get_worktree_stats(self, spec_name: str) -> dict:
        """Get diff statistics for a worktree."""
        worktree_path = self.get_worktree_path(spec_name)
@@ -467,13 +607,25 @@ class WorktreeManager:

    def create_worktree(self, spec_name: str) -> WorktreeInfo:
        """
-        Create a worktree for a spec.
+        Create a worktree for a spec (idempotent).
+
+        This method is idempotent - calling it multiple times with the same spec_name
+        will succeed regardless of prior state. It handles:
+        - Existing valid worktrees (returns existing)
+        - Corrupted worktrees (force removes and recreates)
+        - Orphaned worktree references (prunes them)
+        - Stale worktree directories (cleans them up)
+        - Existing branches without worktrees (reuses the branch)
+
+        Note:
+            This method is NOT thread-safe for concurrent calls with the same spec_name.
+            If concurrent access is needed, implement external locking.

        Args:
            spec_name: The spec folder name (e.g., "002-implement-memory")

        Returns:
-            WorktreeInfo for the created worktree
+            WorktreeInfo for the created or existing worktree

        Raises:
            WorktreeError: If a branch namespace conflict exists or worktree creation fails
@@ -481,7 +633,11 @@ class WorktreeManager:
        worktree_path = self.get_worktree_path(spec_name)
        branch_name = self.get_branch_name(spec_name)

-        # Check for branch namespace conflict (e.g., 'auto-claude' blocking 'auto-claude/*')
+        # Step 1: Prune orphaned worktree references first
+        # This cleans up any stale references that might block operations
+        self._run_git(["worktree", "prune"])
+
+        # Step 2: Check for branch namespace conflict (e.g., 'auto-claude' blocking 'auto-claude/*')
        conflicting_branch = self._check_branch_namespace_conflict()
        if conflicting_branch:
            raise WorktreeError(
@@ -494,14 +650,41 @@ class WorktreeManager:
                f"  git branch -m {conflicting_branch} {conflicting_branch}-backup"
            )

-        # Remove existing if present (from crashed previous run)
-        if worktree_path.exists():
-            self._run_git(["worktree", "remove", "--force", str(worktree_path)])
+        # Step 3: Check if worktree already exists and is valid
+        if worktree_path.exists() and self._worktree_is_registered(worktree_path):
+            # Worktree exists and is tracked by git - return existing (idempotent)
+            existing = self.get_worktree_info(spec_name)
+            if existing:
+                print(
+                    f"Using existing worktree: {worktree_path.name} on branch {existing.branch}"
+                )
+                return existing
+            else:
+                # Worktree is registered but corrupted (e.g., unreadable HEAD)
+                # Force remove the registration and let it be recreated
+                print(f"Removing corrupted worktree registration: {worktree_path.name}")
+                remove_result = self._run_git(
+                    ["worktree", "remove", "--force", str(worktree_path)]
+                )
+                if remove_result.returncode != 0:
+                    raise WorktreeError(
+                        f"Failed to remove corrupted worktree: {remove_result.stderr}"
+                    )

-        # Delete branch if it exists (from previous attempt)
-        self._run_git(["branch", "-D", branch_name])
+        # Step 4: Handle stale worktree directory (exists but not registered with git)
+        if worktree_path.exists() and not self._worktree_is_registered(worktree_path):
+            print(f"Removing stale worktree directory: {worktree_path.name}")
+            shutil.rmtree(worktree_path, ignore_errors=True)
+            if worktree_path.exists():
+                raise WorktreeError(
+                    f"Failed to remove stale worktree directory: {worktree_path}\n"
+                    f"This may be due to permission issues or file locks."
+                )

-        # Fetch latest from remote to ensure we have the most up-to-date code
+        # Step 5: Check if branch already exists
+        branch_exists = self._branch_exists(branch_name)
+
+        # Step 6: Fetch latest from remote to ensure we have the most up-to-date code
        # GitHub/remote is the source of truth, not the local branch
        fetch_result = self._run_git(["fetch", "origin", self.base_branch])
        if fetch_result.returncode != 0:
@@ -510,25 +693,36 @@ class WorktreeManager:
            )
            print("Falling back to local branch...")

-        # Determine the start point for the worktree
-        # Prefer origin/{base_branch} (remote) over local branch to ensure we have latest code
-        remote_ref = f"origin/{self.base_branch}"
-        start_point = self.base_branch  # Default to local branch
-
-        # Check if remote ref exists and use it as the source of truth
-        check_remote = self._run_git(["rev-parse", "--verify", remote_ref])
-        if check_remote.returncode == 0:
-            start_point = remote_ref
-            print(f"Creating worktree from remote: {remote_ref}")
+        # Step 7: Create the worktree
+        if branch_exists:
+            # Branch exists - attach worktree to existing branch (no -b flag)
+            print(f"Reusing existing branch: {branch_name}")
+            result = self._run_git(["worktree", "add", str(worktree_path), branch_name])
        else:
-            print(
-                f"Remote ref {remote_ref} not found, using local branch: {self.base_branch}"
-            )
+            # Branch doesn't exist - create new branch from remote or local base
+            # Determine the start point for the worktree
+            start_point = self.base_branch  # Default to local branch

-        # Create worktree with new branch from the start point (remote preferred)
-        result = self._run_git(
-            ["worktree", "add", "-b", branch_name, str(worktree_path), start_point]
-        )
+            if self.use_local_branch:
+                # User explicitly requested local branch - skip auto-switch to remote
+                # This preserves gitignored files (.env, configs) that may not exist on remote
+                print(f"Creating worktree from local branch: {self.base_branch}")
+            else:
+                # Check if remote ref exists and use it as the source of truth
+                remote_ref = f"origin/{self.base_branch}"
+                check_remote = self._run_git(["rev-parse", "--verify", remote_ref])
+                if check_remote.returncode == 0:
+                    start_point = remote_ref
+                    print(f"Creating worktree from remote: {remote_ref}")
+                else:
+                    print(
+                        f"Remote ref {remote_ref} not found, using local branch: {self.base_branch}"
+                    )
+
+            # Create worktree with new branch from the start point
+            result = self._run_git(
+                ["worktree", "add", "-b", branch_name, str(worktree_path), start_point]
+            )

        if result.returncode != 0:
            raise WorktreeError(
@@ -867,6 +1061,65 @@ class WorktreeManager:
                error=f"No worktree found for spec: {spec_name}",
            )

+        # Verify we have an actual branch name (not detached HEAD)
+        # get_worktree_info already falls back to expected branch name for detached HEAD,
+        # but we also need to re-attach HEAD to the branch in the worktree so git push works.
+        head_check = self._run_git(["rev-parse", "--abbrev-ref", "HEAD"], cwd=info.path)
+        if head_check.returncode == 0 and head_check.stdout.strip() == "HEAD":
+            # Resolve the target branch: first check git's worktree registry (which
+            # tracks the original branch even when detached), then fall back to the
+            # expected branch name derived from the spec name.
+            target_branch = self._get_worktree_registered_branch(info.path)
+            if not target_branch:
+                target_branch = self.get_branch_name(spec_name)
+            debug_warning(
+                "worktree",
+                f"Re-attaching detached HEAD to branch '{target_branch}' before push",
+            )
+            # Check if the target branch exists locally
+            if self._branch_exists(target_branch):
+                # Move the branch ref to current commit and switch to it
+                current_commit = self._run_git(["rev-parse", "HEAD"], cwd=info.path)
+                if current_commit.returncode != 0:
+                    return PushBranchResult(
+                        success=False,
+                        branch=target_branch,
+                        error=f"Failed to resolve HEAD commit: {current_commit.stderr}",
+                    )
+                commit_sha = current_commit.stdout.strip()
+                # Update the branch to point to current commit
+                branch_update = self._run_git(
+                    ["branch", "-f", target_branch, commit_sha],
+                    cwd=info.path,
+                )
+                if branch_update.returncode != 0:
+                    return PushBranchResult(
+                        success=False,
+                        branch=target_branch,
+                        error=f"Failed to update branch '{target_branch}' to commit {commit_sha}: {branch_update.stderr}",
+                    )
+                # Switch to the branch
+                switch_result = self._run_git(
+                    ["checkout", target_branch], cwd=info.path
+                )
+                if switch_result.returncode != 0:
+                    return PushBranchResult(
+                        success=False,
+                        branch=target_branch,
+                        error=f"Failed to re-attach to branch '{target_branch}': {switch_result.stderr}",
+                    )
+            else:
+                # Branch doesn't exist locally - create it at current HEAD
+                checkout_result = self._run_git(
+                    ["checkout", "-b", target_branch], cwd=info.path
+                )
+                if checkout_result.returncode != 0:
+                    return PushBranchResult(
+                        success=False,
+                        branch=target_branch,
+                        error=f"Failed to create branch '{target_branch}': {checkout_result.stderr}",
+                    )
+
        # Push the branch to origin
        push_args = ["push", "-u", "origin", info.branch]
        if force:
@@ -958,8 +1211,22 @@ class WorktreeManager:
        target = target_branch or self.base_branch
        pr_title = title or f"auto-claude: {spec_name}"

-        # Get PR body from spec.md if available
-        pr_body = self._extract_spec_summary(spec_name)
+        # Try AI-powered PR body from project's PR template, fall back to spec summary
+        pr_body: str | None = None
+        try:
+            diff_summary, commit_log = self._gather_pr_context(spec_name, target)
+            pr_body = self._try_ai_pr_body(
+                spec_name=spec_name,
+                target_branch=target,
+                branch_name=info.branch,
+                diff_summary=diff_summary,
+                commit_log=commit_log,
+            )
+        except Exception as e:
+            logger.warning(f"AI PR body generation encountered an error: {e}")
+
+        if not pr_body:
+            pr_body = self._extract_spec_summary(spec_name)

        # Find gh executable before attempting PR creation
        gh_executable = get_gh_executable()
@@ -1002,7 +1269,7 @@ class WorktreeManager:
                    text=True,
                    encoding="utf-8",
                    errors="replace",
-                    timeout=self.GH_CLI_TIMEOUT,
+                    timeout=self.CLI_TIMEOUT,
                    env=get_isolated_git_env(),
                )

@@ -1078,9 +1345,328 @@ class WorktreeManager:
            invalidate_gh_cache()
            return PullRequestResult(
                success=False,
-                error="gh CLI not found. Install from https://cli.github.com/",
+                error="GitHub CLI (gh) not found. Install from https://cli.github.com/",
            )

+    def create_merge_request(
+        self,
+        spec_name: str,
+        target_branch: str | None = None,
+        title: str | None = None,
+        draft: bool = False,
+    ) -> PullRequestResult:
+        """
+        Create a GitLab merge request for a spec's branch using glab CLI with retry logic.
+
+        Args:
+            spec_name: The spec folder name
+            target_branch: Target branch for MR (defaults to base_branch)
+            title: MR title (defaults to spec name)
+            draft: Whether to create as draft MR
+
+        Returns:
+            PullRequestResult with keys:
+                - success: bool
+                - pr_url: str (if created)
+                - already_exists: bool (if MR already exists)
+                - error: str (if failed)
+        """
+        info = self.get_worktree_info(spec_name)
+        if not info:
+            return PullRequestResult(
+                success=False,
+                error=f"No worktree found for spec: {spec_name}",
+            )
+
+        target = target_branch or self.base_branch
+        mr_title = title or f"auto-claude: {spec_name}"
+
+        # Get MR body from spec.md if available
+        mr_body = self._extract_spec_summary(spec_name)
+
+        # Find glab executable before attempting MR creation
+        glab_executable = get_glab_executable()
+        if not glab_executable:
+            return PullRequestResult(
+                success=False,
+                error="GitLab CLI (glab) not found. Install from https://gitlab.com/gitlab-org/cli",
+            )
+
+        # Build glab mr create command
+        glab_args = [
+            glab_executable,
+            "mr",
+            "create",
+            "--target-branch",
+            target,
+            "--source-branch",
+            info.branch,
+            "--title",
+            mr_title,
+            "--description",
+            mr_body,
+        ]
+        if draft:
+            glab_args.append("--draft")
+
+        def is_mr_retryable(stderr: str) -> bool:
+            """Check if MR creation error is retryable (network or HTTP 5xx)."""
+            return _is_retryable_network_error(stderr) or _is_retryable_http_error(
+                stderr
+            )
+
+        def do_create_mr() -> tuple[bool, PullRequestResult | None, str]:
+            """Execute MR creation for retry wrapper."""
+            try:
+                result = subprocess.run(
+                    glab_args,
+                    cwd=info.path,
+                    capture_output=True,
+                    text=True,
+                    encoding="utf-8",
+                    errors="replace",
+                    timeout=self.CLI_TIMEOUT,
+                    env=get_isolated_git_env(),
+                )
+
+                # Check for "already exists" case (success, no retry needed)
+                if result.returncode != 0 and "already exists" in result.stderr.lower():
+                    existing_url = self._get_existing_mr_url(spec_name, target)
+                    result_dict = PullRequestResult(
+                        success=True,
+                        pr_url=existing_url,
+                        already_exists=True,
+                    )
+                    if existing_url is None:
+                        result_dict["message"] = (
+                            "MR already exists but URL could not be retrieved"
+                        )
+                    return (True, result_dict, "")
+
+                if result.returncode == 0:
+                    # Extract MR URL from output
+                    mr_url: str | None = result.stdout.strip()
+                    if not mr_url.startswith("http"):
+                        # Try to find URL in output
+                        # GitLab URL pattern: matches any HTTPS URL with /merge_requests/<number> or /-/merge_requests/<number> path
+                        match = re.search(
+                            r"https://[^\s]+(?:/merge_requests/|/-/merge_requests/)\d+",
+                            result.stdout,
+                        )
+                        if match:
+                            mr_url = match.group(0)
+                        else:
+                            # Invalid output - no valid URL found
+                            mr_url = None
+
+                    return (
+                        True,
+                        PullRequestResult(
+                            success=True,
+                            pr_url=mr_url,
+                            already_exists=False,
+                        ),
+                        "",
+                    )
+
+                return (False, None, result.stderr)
+
+            except FileNotFoundError:
+                # glab CLI not installed - not retryable, raise to exit retry loop
+                raise
+
+        max_retries = 3
+        try:
+            result, last_error = _with_retry(
+                operation=do_create_mr,
+                max_retries=max_retries,
+                is_retryable=is_mr_retryable,
+            )
+
+            if result:
+                return result
+
+            # Handle timeout error message
+            if last_error == "Operation timed out":
+                return PullRequestResult(
+                    success=False,
+                    error=f"MR creation timed out after {max_retries} attempts.",
+                )
+
+            return PullRequestResult(
+                success=False,
+                error=f"Failed to create MR: {last_error}",
+            )
+
+        except FileNotFoundError:
+            # Cached glab path became invalid - clear cache so next call re-discovers
+            invalidate_glab_cache()
+            return PullRequestResult(
+                success=False,
+                error="GitLab CLI (glab) not found. Install from https://gitlab.com/gitlab-org/cli",
+            )
+
+    def _gather_pr_context(self, spec_name: str, target_branch: str) -> tuple[str, str]:
+        """
+        Gather diff summary and commit log for PR template filling.
+
+        Args:
+            spec_name: The spec folder name
+            target_branch: The target branch for the PR
+
+        Returns:
+            Tuple of (diff_summary, commit_log)
+        """
+        worktree_path = self.get_worktree_path(spec_name)
+        info = self.get_worktree_info(spec_name)
+        branch = info.branch if info else self.get_branch_name(spec_name)
+
+        # Get diff summary (stat for overview)
+        diff_result = self._run_git(
+            ["diff", "--stat", f"{target_branch}...{branch}"],
+            cwd=worktree_path,
+            timeout=30,
+        )
+        diff_summary = diff_result.stdout.strip() if diff_result.returncode == 0 else ""
+
+        # Get shortstat for quick summary
+        shortstat_result = self._run_git(
+            ["diff", "--shortstat", f"{target_branch}...{branch}"],
+            cwd=worktree_path,
+            timeout=30,
+        )
+        if shortstat_result.returncode == 0 and shortstat_result.stdout.strip():
+            diff_summary += "\n\n" + shortstat_result.stdout.strip()
+
+        # Get actual code changes (patch format) for better AI context
+        # Truncate to 30k chars to avoid token limits while still providing meaningful context
+        patch_result = self._run_git(
+            ["diff", "-p", "--stat-width=999", f"{target_branch}...{branch}"],
+            cwd=worktree_path,
+            timeout=30,
+        )
+        if patch_result.returncode == 0 and patch_result.stdout.strip():
+            patch_content = patch_result.stdout.strip()
+            MAX_DIFF_CHARS = 30_000
+
+            if len(patch_content) > MAX_DIFF_CHARS:
+                # Truncate patch and add notice
+                truncated_patch = patch_content[:MAX_DIFF_CHARS]
+                diff_summary += (
+                    "\n\n" + truncated_patch + "\n\n(... diff truncated due to size)"
+                )
+            else:
+                diff_summary += "\n\n" + patch_content
+
+        # Get commit log
+        log_result = self._run_git(
+            [
+                "log",
+                "--oneline",
+                "--no-merges",
+                f"{target_branch}..{branch}",
+            ],
+            cwd=worktree_path,
+            timeout=30,
+        )
+        commit_log = log_result.stdout.strip() if log_result.returncode == 0 else ""
+
+        return diff_summary, commit_log
+
+    def _try_ai_pr_body(
+        self,
+        spec_name: str,
+        target_branch: str,
+        branch_name: str,
+        diff_summary: str,
+        commit_log: str,
+    ) -> str | None:
+        """
+        Attempt to generate a PR body using the AI template filler agent.
+
+        Runs the async agent synchronously with a 30-second timeout.
+        Returns None on any failure so the caller can fall back gracefully.
+
+        Args:
+            spec_name: The spec folder name
+            target_branch: The target branch for the PR
+            branch_name: The source branch name
+            diff_summary: Git diff summary of changes
+            commit_log: Git log of commits
+
+        Returns:
+            The AI-generated PR body string, or None if unavailable.
+        """
+        try:
+            from agents.pr_template_filler import (
+                detect_pr_template,
+                run_pr_template_filler,
+            )
+        except ImportError:
+            logger.warning(
+                "PR template filler module not available, skipping AI PR body"
+            )
+            return None
+
+        # Check if a PR template exists before doing any heavy lifting
+        template = detect_pr_template(self.project_dir)
+        if template is None:
+            return None
+
+        # Resolve spec directory
+        spec_dir = self.project_dir / ".auto-claude" / "specs" / spec_name
+        if not spec_dir.is_dir():
+            # Try worktree-local spec path
+            worktree_path = self.get_worktree_path(spec_name)
+            spec_dir = worktree_path / ".auto-claude" / "specs" / spec_name
+            if not spec_dir.is_dir():
+                logger.warning("Spec directory not found for AI PR body generation")
+                return None
+
+        # Get model configuration from environment (respects user settings)
+        model, thinking_budget = get_utility_model_config()
+
+        async def _run_with_timeout() -> str | None:
+            try:
+                return await asyncio.wait_for(
+                    run_pr_template_filler(
+                        project_dir=self.project_dir,
+                        spec_dir=spec_dir,
+                        model=model,
+                        thinking_budget=thinking_budget,
+                        branch_name=branch_name,
+                        target_branch=target_branch,
+                        diff_summary=diff_summary,
+                        commit_log=commit_log,
+                        verbose=False,
+                    ),
+                    timeout=30.0,
+                )
+            except asyncio.TimeoutError:
+                logger.warning("PR template filler timed out after 30s")
+                return None
+
+        try:
+            # Check if there's already a running event loop
+            try:
+                loop = asyncio.get_running_loop()
+            except RuntimeError:
+                loop = None
+
+            if loop and loop.is_running():
+                # We're already inside an async context — run in a new thread
+                import concurrent.futures
+
+                with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                    future = pool.submit(asyncio.run, _run_with_timeout())
+                    return future.result(timeout=35)
+            else:
+                return asyncio.run(_run_with_timeout())
+
+        except Exception as e:
+            logger.warning(f"AI PR body generation failed: {e}")
+            return None
+
    def _extract_spec_summary(self, spec_name: str) -> str:
        """Extract a summary from spec.md for PR body."""
        worktree_path = self.get_worktree_path(spec_name)
@@ -1155,7 +1741,7 @@ class WorktreeManager:
                text=True,
                encoding="utf-8",
                errors="replace",
-                timeout=self.GH_QUERY_TIMEOUT,
+                timeout=self.CLI_QUERY_TIMEOUT,
                env=get_isolated_git_env(),
            )
            if result.returncode == 0:
@@ -1174,6 +1760,57 @@ class WorktreeManager:

        return None

+    def _get_existing_mr_url(self, spec_name: str, target_branch: str) -> str | None:
+        """Get the URL of an existing MR for this branch."""
+        info = self.get_worktree_info(spec_name)
+        if not info:
+            return None
+
+        glab_executable = get_glab_executable()
+        if not glab_executable:
+            # glab CLI not found - return None and let caller handle it
+            return None
+
+        try:
+            result = subprocess.run(
+                [
+                    glab_executable,
+                    "mr",
+                    "view",
+                    info.branch,
+                    "--output",
+                    "json",
+                ],
+                cwd=info.path,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=self.CLI_QUERY_TIMEOUT,
+                env=get_isolated_git_env(),
+            )
+            if result.returncode == 0 and result.stdout.strip():
+                # Parse JSON output to extract web_url (glab uses snake_case)
+                try:
+                    data = json.loads(result.stdout)
+                    return data.get("web_url")
+                except json.JSONDecodeError:
+                    # If JSON parsing fails, return None
+                    pass
+        except (
+            subprocess.TimeoutExpired,
+            FileNotFoundError,
+            subprocess.SubprocessError,
+        ) as e:
+            # Silently ignore errors when fetching existing MR URL - this is a best-effort
+            # lookup that may fail due to network issues, missing glab CLI, or auth problems.
+            # Returning None allows the caller to handle missing URLs gracefully.
+            if isinstance(e, FileNotFoundError):
+                invalidate_glab_cache()
+            debug_warning("worktree", f"Could not get existing MR URL: {e}")
+
+        return None
+
    def push_and_create_pr(
        self,
        spec_name: str,
@@ -1183,13 +1820,14 @@ class WorktreeManager:
        force_push: bool = False,
    ) -> PushAndCreatePRResult:
        """
-        Push branch and create a pull request in one operation.
+        Push branch and create a pull request/merge request in one operation.
+        Automatically detects git provider (GitHub or GitLab) and routes to the appropriate CLI.

        Args:
            spec_name: The spec folder name
-            target_branch: Target branch for PR (defaults to base_branch)
-            title: PR title (defaults to spec name)
-            draft: Whether to create as draft PR
+            target_branch: Target branch for PR/MR (defaults to base_branch)
+            title: PR/MR title (defaults to spec name)
+            draft: Whether to create as draft PR/MR
            force_push: Whether to force push the branch

        Returns:
@@ -1197,7 +1835,8 @@ class WorktreeManager:
                - success: bool
                - pr_url: str (if created)
                - pushed: bool (if push succeeded)
-                - already_exists: bool (if PR already exists)
+                - provider: str ('github', 'gitlab', or 'unknown')
+                - already_exists: bool (if PR/MR already exists)
                - error: str (if failed)
        """
        # Step 1: Push the branch
@@ -1206,23 +1845,49 @@ class WorktreeManager:
            return PushAndCreatePRResult(
                success=False,
                pushed=False,
+                branch=push_result.get("branch", ""),
+                remote=push_result.get("remote", ""),
                error=push_result.get("error", "Push failed"),
            )

-        # Step 2: Create the PR
-        pr_result = self.create_pull_request(
-            spec_name=spec_name,
-            target_branch=target_branch,
-            title=title,
-            draft=draft,
+        # Step 2: Detect git provider (use the remote that was pushed to)
+        provider = detect_git_provider(
+            self.project_dir, remote_name=push_result.get("remote")
        )

+        # Step 3: Create the PR/MR based on provider
+        if provider == "github":
+            pr_result = self.create_pull_request(
+                spec_name=spec_name,
+                target_branch=target_branch,
+                title=title,
+                draft=draft,
+            )
+        elif provider == "gitlab":
+            pr_result = self.create_merge_request(
+                spec_name=spec_name,
+                target_branch=target_branch,
+                title=title,
+                draft=draft,
+            )
+        else:
+            # Unknown provider
+            return PushAndCreatePRResult(
+                success=False,
+                pushed=True,
+                remote=push_result.get("remote"),
+                branch=push_result.get("branch"),
+                provider=provider,
+                error="Unable to determine git hosting provider. Supported: GitHub, GitLab.",
+            )
+
        # Combine results
        return PushAndCreatePRResult(
            success=pr_result.get("success", False),
            pushed=True,
            remote=push_result.get("remote"),
            branch=push_result.get("branch"),
+            provider=provider,
            pr_url=pr_result.get("pr_url"),
            already_exists=pr_result.get("already_exists", False),
            error=pr_result.get("error"),
@@ -51,7 +51,7 @@ class ProjectAnalyzer:
        project_index_path = self.project_dir / ".auto-claude" / "project_index.json"
        if project_index_path.exists():
            try:
-                with open(project_index_path) as f:
+                with open(project_index_path, encoding="utf-8") as f:
                    index = json.load(f)
                    # Extract tech stack from services
                    for service_name, service_info in index.get("services", {}).items():
@@ -70,7 +70,7 @@ class ProjectAnalyzer:
            )
            if roadmap_path.exists():
                try:
-                    with open(roadmap_path) as f:
+                    with open(roadmap_path, encoding="utf-8") as f:
                        roadmap = json.load(f)
                        # Extract planned features
                        for feature in roadmap.get("features", []):
@@ -87,7 +87,7 @@ class ProjectAnalyzer:
            )
            if discovery_path.exists() and not context["target_audience"]:
                try:
-                    with open(discovery_path) as f:
+                    with open(discovery_path, encoding="utf-8") as f:
                        discovery = json.load(f)
                        audience = discovery.get("target_audience", {})
                        context["target_audience"] = audience.get("primary_persona")
@@ -109,7 +109,7 @@ class ProjectAnalyzer:
                        spec_file = spec_dir / "spec.md"
                        if spec_file.exists():
                            # Extract title from spec
-                            content = spec_file.read_text()
+                            content = spec_file.read_text(encoding="utf-8")
                            lines = content.split("\n")
                            for line in lines:
                                if line.startswith("# "):
@@ -39,7 +39,7 @@ class IdeationFormatter:
        existing_session = None
        if append and ideation_file.exists():
            try:
-                with open(ideation_file) as f:
+                with open(ideation_file, encoding="utf-8") as f:
                    existing_session = json.load(f)
                    existing_ideas = existing_session.get("ideas", [])
                    print_status(
@@ -56,7 +56,7 @@ class IdeationFormatter:
            type_file = self.output_dir / f"{ideation_type}_ideas.json"
            if type_file.exists():
                try:
-                    with open(type_file) as f:
+                    with open(type_file, encoding="utf-8") as f:
                        data = json.load(f)
                        ideas = data.get(ideation_type, [])
                        new_ideas.extend(ideas)
@@ -123,7 +123,7 @@ class IdeationFormatter:
                ideation_session["summary"]["by_status"].get(idea_status, 0) + 1
            )

-        with open(ideation_file, "w") as f:
+        with open(ideation_file, "w", encoding="utf-8") as f:
            json.dump(ideation_session, f, indent=2)

        action = "Updated" if append else "Created"
@@ -139,7 +139,7 @@ class IdeationFormatter:
        context_data = {}
        if context_file.exists():
            try:
-                with open(context_file) as f:
+                with open(context_file, encoding="utf-8") as f:
                    context_data = json.load(f)
            except json.JSONDecodeError:
                pass
@@ -80,7 +80,7 @@ class IdeationGenerator:
            return False, f"Prompt not found: {prompt_path}"

        # Load prompt
-        prompt = prompt_path.read_text()
+        prompt = prompt_path.read_text(encoding="utf-8")

        # Add context
        prompt += f"\n\n---\n\n**Output Directory**: {self.output_dir}\n"
@@ -91,11 +91,14 @@ class IdeationGenerator:
            prompt += f"\n{additional_context}\n"

        # Create client with thinking budget
+        # Use agent_type="ideation" to avoid loading unnecessary MCP servers
+        # which can cause 60-second timeout delays
        client = create_client(
            self.project_dir,
            self.output_dir,
            resolve_model_id(self.model),
            max_thinking_tokens=self.thinking_budget,
+            agent_type="ideation",
        )

        try:
@@ -184,11 +187,13 @@ Common fixes:
 Write the fixed JSON to the file now.
 """

+        # Use agent_type="ideation" for recovery agent as well
        client = create_client(
            self.project_dir,
            self.output_dir,
            resolve_model_id(self.model),
            max_thinking_tokens=self.thinking_budget,
+            agent_type="ideation",
        )

        try:
@@ -85,7 +85,7 @@ class PhaseExecutor:

        if not is_graphiti_enabled():
            print_status("Graphiti not enabled, skipping graph hints", "info")
-            with open(hints_file, "w") as f:
+            with open(hints_file, "w", encoding="utf-8") as f:
                json.dump(
                    {
                        "enabled": False,
@@ -131,7 +131,7 @@ class PhaseExecutor:
                total_hints += len(result)

        # Save hints
-        with open(hints_file, "w") as f:
+        with open(hints_file, "w", encoding="utf-8") as f:
            json.dump(
                {
                    "enabled": True,
@@ -178,11 +178,11 @@ class PhaseExecutor:
        graph_hints = {}
        if hints_file.exists():
            try:
-                with open(hints_file) as f:
+                with open(hints_file, encoding="utf-8") as f:
                    hints_data = json.load(f)
                    graph_hints = hints_data.get("hints_by_type", {})
-            except (OSError, json.JSONDecodeError):
-                pass
+            except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+                pass  # Use empty hints if file is corrupted/unreadable

        # Write context file
        context_data = {
@@ -200,7 +200,7 @@ class PhaseExecutor:
            "created_at": datetime.now().isoformat(),
        }

-        with open(context_file, "w") as f:
+        with open(context_file, "w", encoding="utf-8") as f:
            json.dump(context_data, f, indent=2)

        print_status("Created ideation_context.json", "success")
@@ -252,7 +252,7 @@ class PhaseExecutor:
        if output_file.exists() and not self.refresh:
            # Load and validate existing ideas - only skip if we have valid ideas
            try:
-                with open(output_file) as f:
+                with open(output_file, encoding="utf-8") as f:
                    data = json.load(f)
                    count = len(data.get(ideation_type, []))

@@ -48,7 +48,7 @@ class IdeaPrioritizer:
            }

        try:
-            content = output_file.read_text()
+            content = output_file.read_text(encoding="utf-8")
            data = json.loads(content)
            debug_verbose(
                "ideation_prioritizer",
@@ -102,7 +102,7 @@ class IdeaPrioritizer:
            return {
                "success": False,
                "error": f"Invalid JSON: {e}",
-                "current_content": output_file.read_text()
+                "current_content": output_file.read_text(encoding="utf-8")
                if output_file.exists()
                else "",
                "count": 0,
@@ -28,6 +28,7 @@ from .types import IdeationPhaseResult

 # Configuration
 MAX_RETRIES = 3
+IDEATION_TIMEOUT_SECONDS = 5 * 60  # 5 minutes max for all ideation types


 class IdeationOrchestrator:
@@ -173,16 +174,45 @@ class IdeationOrchestrator:
            "progress",
        )

-        # Create tasks for all enabled types
-        ideation_tasks = [
-            self.output_streamer.stream_ideation_result(
-                ideation_type, self.phase_executor, MAX_RETRIES
+        # Create tasks explicitly so we can cancel them on timeout
+        ideation_task_objs = [
+            asyncio.create_task(
+                self.output_streamer.stream_ideation_result(
+                    ideation_type, self.phase_executor, MAX_RETRIES
+                )
            )
            for ideation_type in self.enabled_types
        ]

-        # Run all ideation types concurrently
-        ideation_results = await asyncio.gather(*ideation_tasks, return_exceptions=True)
+        # Run all ideation types concurrently with timeout protection
+        # 5 minute timeout prevents infinite hangs if one type stalls
+        try:
+            ideation_results = await asyncio.wait_for(
+                asyncio.gather(*ideation_task_objs, return_exceptions=True),
+                timeout=IDEATION_TIMEOUT_SECONDS,
+            )
+        except asyncio.TimeoutError:
+            print_status(
+                "Ideation generation timed out after 5 minutes",
+                "error",
+            )
+            # Cancel all pending tasks to prevent resource leaks
+            for task in ideation_task_objs:
+                if not task.done():
+                    task.cancel()
+            # Wait for cancellation to complete and preserve results from completed tasks
+            # Tasks that finished before timeout will return their results;
+            # cancelled tasks will return CancelledError
+            results_after_cancel = await asyncio.gather(
+                *ideation_task_objs, return_exceptions=True
+            )
+            # Convert CancelledError to timeout exception, preserve completed results
+            ideation_results = [
+                Exception("Ideation timed out")
+                if isinstance(res, asyncio.CancelledError)
+                else res
+                for res in results_after_cancel
+            ]

        # Process results
        for i, result in enumerate(ideation_results):
@@ -232,7 +262,7 @@ class IdeationOrchestrator:
        """Print summary of ideation generation results."""
        ideation_file = self.output_dir / "ideation.json"
        if ideation_file.exists():
-            with open(ideation_file) as f:
+            with open(ideation_file, encoding="utf-8") as f:
                ideation = json.load(f)

            ideas = ideation.get("ideas", [])
@@ -25,9 +25,8 @@ Package Structure:
 - factories.py: Factory functions for creating different plan types
 """

-# Export all public types and functions for backwards compatibility
+# Export all public types and functions
 from .enums import (
-    ChunkStatus,  # Backwards compatibility
    PhaseType,
    SubtaskStatus,
    VerificationType,
@@ -40,7 +39,7 @@ from .factories import (
 )
 from .phase import Phase
 from .plan import ImplementationPlan
-from .subtask import Chunk, Subtask  # Chunk is backwards compatibility alias
+from .subtask import Subtask
 from .verification import Verification

 __all__ = [
@@ -58,7 +57,4 @@ __all__ = [
    "create_feature_plan",
    "create_investigation_plan",
    "create_refactor_plan",
-    # Backwards compatibility
-    "Chunk",
-    "ChunkStatus",
 ]
@@ -51,7 +51,3 @@ class VerificationType(str, Enum):
    COMPONENT = "component"  # Component renders correctly
    MANUAL = "manual"  # Requires human verification
    NONE = "none"  # No verification needed (investigation)
-
-
-# Backwards compatibility aliases
-ChunkStatus = SubtaskStatus
@@ -126,7 +126,3 @@ class Subtask:
        self.completed_at = None  # Clear to maintain consistency (failed != completed)
        if reason:
            self.actual_output = f"FAILED: {reason}"
-
-
-# Backwards compatibility alias
-Chunk = Subtask
@@ -57,7 +57,7 @@ def ensure_gitignore_entry(project_dir: Path, entry: str = ".auto-claude/") -> b

    # Check if .gitignore exists and if entry is already present
    if gitignore_path.exists():
-        content = gitignore_path.read_text()
+        content = gitignore_path.read_text(encoding="utf-8")
        lines = content.splitlines()

        if _entry_exists_in_gitignore(lines, entry):
@@ -72,14 +72,14 @@ def ensure_gitignore_entry(project_dir: Path, entry: str = ".auto-claude/") -> b
        content += "\n# Auto Claude data directory\n"
        content += entry + "\n"

-        gitignore_path.write_text(content)
+        gitignore_path.write_text(content, encoding="utf-8")
        return True
    else:
        # Create new .gitignore with the entry
        content = "# Auto Claude data directory\n"
        content += entry + "\n"

-        gitignore_path.write_text(content)
+        gitignore_path.write_text(content, encoding="utf-8")
        return True


@@ -177,7 +177,7 @@ def ensure_all_gitignore_entries(

    # Read existing content or start fresh
    if gitignore_path.exists():
-        content = gitignore_path.read_text()
+        content = gitignore_path.read_text(encoding="utf-8")
        lines = content.splitlines()
    else:
        content = ""
@@ -203,7 +203,7 @@ def ensure_all_gitignore_entries(
        content += entry + "\n"
        added_entries.append(entry)

-    gitignore_path.write_text(content)
+    gitignore_path.write_text(content, encoding="utf-8")

    # Auto-commit if requested and entries were added
    if auto_commit and added_entries:
@@ -507,7 +507,7 @@ class GraphitiState:
    def save(self, spec_dir: Path) -> None:
        """Save state to the spec directory."""
        marker_file = spec_dir / GRAPHITI_STATE_MARKER
-        with open(marker_file, "w") as f:
+        with open(marker_file, "w", encoding="utf-8") as f:
            json.dump(self.to_dict(), f, indent=2)

    @classmethod
@@ -518,9 +518,9 @@ class GraphitiState:
            return None

        try:
-            with open(marker_file) as f:
+            with open(marker_file, encoding="utf-8") as f:
                return cls.from_dict(json.load(f))
-        except (OSError, json.JSONDecodeError):
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
            return None

    def record_error(self, error_msg: str) -> None:
@@ -12,12 +12,8 @@ The refactored code is now organized as:
 - graphiti/search.py - Semantic search logic
 - graphiti/schema.py - Graph schema definitions

-This facade ensures existing imports continue to work:
-    from graphiti_memory import GraphitiMemory, is_graphiti_enabled
-
-New code should prefer importing from the graphiti package:
-    from graphiti import GraphitiMemory
-    from graphiti.schema import GroupIdMode
+Import from this module:
+    from integrations.graphiti.memory import GraphitiMemory, is_graphiti_enabled, GroupIdMode

 For detailed documentation on the memory system architecture and usage,
 see graphiti/graphiti.py.
@@ -62,7 +62,7 @@ async def get_graph_hints(
    try:
        from pathlib import Path

-        from graphiti_memory import GraphitiMemory, GroupIdMode
+        from integrations.graphiti.memory import GraphitiMemory, GroupIdMode

        # Determine project directory from project_id or use current dir
        project_dir = Path.cwd()
@@ -9,6 +9,7 @@ import logging
 import sys
 from datetime import datetime, timezone

+from core.sentry import capture_exception
 from graphiti_config import GraphitiConfig, GraphitiState

 logger = logging.getLogger(__name__)
@@ -133,9 +134,23 @@ class GraphitiClient:
                )
            except ProviderNotInstalled as e:
                logger.warning(f"LLM provider packages not installed: {e}")
+                capture_exception(
+                    e,
+                    error_type="ProviderNotInstalled",
+                    provider_type="llm",
+                    llm_provider=self.config.llm_provider,
+                    embedder_provider=self.config.embedder_provider,
+                )
                return False
            except ProviderError as e:
                logger.warning(f"LLM provider configuration error: {e}")
+                capture_exception(
+                    e,
+                    error_type="ProviderError",
+                    provider_type="llm",
+                    llm_provider=self.config.llm_provider,
+                    embedder_provider=self.config.embedder_provider,
+                )
                return False

            try:
@@ -145,9 +160,23 @@ class GraphitiClient:
                )
            except ProviderNotInstalled as e:
                logger.warning(f"Embedder provider packages not installed: {e}")
+                capture_exception(
+                    e,
+                    error_type="ProviderNotInstalled",
+                    provider_type="embedder",
+                    llm_provider=self.config.llm_provider,
+                    embedder_provider=self.config.embedder_provider,
+                )
                return False
            except ProviderError as e:
                logger.warning(f"Embedder provider configuration error: {e}")
+                capture_exception(
+                    e,
+                    error_type="ProviderError",
+                    provider_type="embedder",
+                    llm_provider=self.config.llm_provider,
+                    embedder_provider=self.config.embedder_provider,
+                )
                return False

            # Apply LadybugDB monkeypatch to use it via graphiti's KuzuDriver
@@ -173,15 +202,36 @@ class GraphitiClient:
                    logger.warning(
                        f"Failed to initialize LadybugDB driver at {db_path}: {e}"
                    )
+                    capture_exception(
+                        e,
+                        error_type=type(e).__name__,
+                        db_path=str(db_path),
+                        llm_provider=self.config.llm_provider,
+                        embedder_provider=self.config.embedder_provider,
+                    )
                    return False
                except Exception as e:
                    logger.warning(
                        f"Unexpected error initializing LadybugDB driver at {db_path}: {e}"
                    )
+                    capture_exception(
+                        e,
+                        error_type=type(e).__name__,
+                        db_path=str(db_path),
+                        llm_provider=self.config.llm_provider,
+                        embedder_provider=self.config.embedder_provider,
+                    )
                    return False
                logger.info(f"Initialized LadybugDB driver (patched) at: {db_path}")
            except ImportError as e:
                logger.warning(f"KuzuDriver not available: {e}")
+                capture_exception(
+                    e,
+                    error_type="ImportError",
+                    component="kuzu_driver_patched",
+                    llm_provider=self.config.llm_provider,
+                    embedder_provider=self.config.embedder_provider,
+                )
                return False

            # Initialize Graphiti with the custom providers
@@ -216,10 +266,23 @@ class GraphitiClient:
                f"Graphiti packages not installed: {e}. "
                "Install with: pip install real_ladybug graphiti-core"
            )
+            capture_exception(
+                e,
+                error_type="ImportError",
+                component="graphiti_core",
+                llm_provider=self.config.llm_provider,
+                embedder_provider=self.config.embedder_provider,
+            )
            return False

        except Exception as e:
            logger.warning(f"Failed to initialize Graphiti client: {e}")
+            capture_exception(
+                e,
+                error_type=type(e).__name__,
+                llm_provider=self.config.llm_provider,
+                embedder_provider=self.config.embedder_provider,
+            )
            return False

    async def close(self) -> None:
@@ -13,6 +13,7 @@ import logging
 from datetime import datetime, timezone
 from pathlib import Path

+from core.sentry import capture_exception
 from graphiti_config import GraphitiConfig, GraphitiState

 from .client import GraphitiClient
@@ -196,6 +197,13 @@ class GraphitiMemory:
        except Exception as e:
            logger.warning(f"Failed to initialize Graphiti: {e}")
            self._record_error(f"Initialization failed: {e}")
+            capture_exception(
+                e,
+                component="graphiti",
+                operation="initialize",
+                group_id=self.group_id,
+                group_id_mode=self.group_id_mode,
+            )
            self._available = False
            return False

@@ -220,14 +228,25 @@ class GraphitiMemory:
        if not await self._ensure_initialized():
            return False

-        result = await self._queries.add_session_insight(session_num, insights)
+        try:
+            result = await self._queries.add_session_insight(session_num, insights)

-        if result and self.state:
-            self.state.last_session = session_num
-            self.state.episode_count += 1
-            self.state.save(self.spec_dir)
+            if result and self.state:
+                self.state.last_session = session_num
+                self.state.episode_count += 1
+                self.state.save(self.spec_dir)

-        return result
+            return result
+        except Exception as e:
+            logger.warning(f"Failed to save session insights: {e}")
+            self._record_error(f"save_session_insights failed: {e}")
+            capture_exception(
+                e,
+                component="graphiti",
+                operation="save_session_insights",
+                session_num=session_num,
+            )
+            return False

    async def save_codebase_discoveries(
        self,
@@ -237,39 +256,69 @@ class GraphitiMemory:
        if not await self._ensure_initialized():
            return False

-        result = await self._queries.add_codebase_discoveries(discoveries)
+        try:
+            result = await self._queries.add_codebase_discoveries(discoveries)

-        if result and self.state:
-            self.state.episode_count += 1
-            self.state.save(self.spec_dir)
+            if result and self.state:
+                self.state.episode_count += 1
+                self.state.save(self.spec_dir)

-        return result
+            return result
+        except Exception as e:
+            logger.warning(f"Failed to save codebase discoveries: {e}")
+            self._record_error(f"save_codebase_discoveries failed: {e}")
+            capture_exception(
+                e,
+                component="graphiti",
+                operation="save_codebase_discoveries",
+            )
+            return False

    async def save_pattern(self, pattern: str) -> bool:
        """Save a code pattern to the knowledge graph."""
        if not await self._ensure_initialized():
            return False

-        result = await self._queries.add_pattern(pattern)
+        try:
+            result = await self._queries.add_pattern(pattern)

-        if result and self.state:
-            self.state.episode_count += 1
-            self.state.save(self.spec_dir)
+            if result and self.state:
+                self.state.episode_count += 1
+                self.state.save(self.spec_dir)

-        return result
+            return result
+        except Exception as e:
+            logger.warning(f"Failed to save pattern: {e}")
+            self._record_error(f"save_pattern failed: {e}")
+            capture_exception(
+                e,
+                component="graphiti",
+                operation="save_pattern",
+            )
+            return False

    async def save_gotcha(self, gotcha: str) -> bool:
        """Save a gotcha (pitfall) to the knowledge graph."""
        if not await self._ensure_initialized():
            return False

-        result = await self._queries.add_gotcha(gotcha)
+        try:
+            result = await self._queries.add_gotcha(gotcha)

-        if result and self.state:
-            self.state.episode_count += 1
-            self.state.save(self.spec_dir)
+            if result and self.state:
+                self.state.episode_count += 1
+                self.state.save(self.spec_dir)

-        return result
+            return result
+        except Exception as e:
+            logger.warning(f"Failed to save gotcha: {e}")
+            self._record_error(f"save_gotcha failed: {e}")
+            capture_exception(
+                e,
+                component="graphiti",
+                operation="save_gotcha",
+            )
+            return False

    async def save_task_outcome(
        self,
@@ -282,28 +331,49 @@ class GraphitiMemory:
        if not await self._ensure_initialized():
            return False

-        result = await self._queries.add_task_outcome(
-            task_id, success, outcome, metadata
-        )
+        try:
+            result = await self._queries.add_task_outcome(
+                task_id, success, outcome, metadata
+            )

-        if result and self.state:
-            self.state.episode_count += 1
-            self.state.save(self.spec_dir)
+            if result and self.state:
+                self.state.episode_count += 1
+                self.state.save(self.spec_dir)

-        return result
+            return result
+        except Exception as e:
+            logger.warning(f"Failed to save task outcome: {e}")
+            self._record_error(f"save_task_outcome failed: {e}")
+            capture_exception(
+                e,
+                component="graphiti",
+                operation="save_task_outcome",
+                task_id=task_id,
+            )
+            return False

    async def save_structured_insights(self, insights: dict) -> bool:
        """Save extracted insights as multiple focused episodes."""
        if not await self._ensure_initialized():
            return False

-        result = await self._queries.add_structured_insights(insights)
+        try:
+            result = await self._queries.add_structured_insights(insights)

-        if result and self.state:
-            # Episode count updated in queries module
-            pass
+            if result and self.state:
+                # Episode count updated in queries module
+                pass

-        return result
+            return result
+        except Exception as e:
+            logger.warning(f"Failed to save structured insights: {e}")
+            self._record_error(f"save_structured_insights failed: {e}")
+            capture_exception(
+                e,
+                component="graphiti",
+                operation="save_structured_insights",
+            )
+            return False

    # Delegate methods to search module

@@ -317,9 +387,19 @@ class GraphitiMemory:
        if not await self._ensure_initialized():
            return []

-        return await self._search.get_relevant_context(
-            query, num_results, include_project_context
-        )
+        try:
+            return await self._search.get_relevant_context(
+                query, num_results, include_project_context
+            )
+        except Exception as e:
+            logger.warning(f"Failed to get relevant context: {e}")
+            self._record_error(f"get_relevant_context failed: {e}")
+            capture_exception(
+                e,
+                component="graphiti",
+                operation="get_relevant_context",
+            )
+            return []

    async def get_session_history(
        self,
@@ -330,7 +410,17 @@ class GraphitiMemory:
        if not await self._ensure_initialized():
            return []

-        return await self._search.get_session_history(limit, spec_only)
+        try:
+            return await self._search.get_session_history(limit, spec_only)
+        except Exception as e:
+            logger.warning(f"Failed to get session history: {e}")
+            self._record_error(f"get_session_history failed: {e}")
+            capture_exception(
+                e,
+                component="graphiti",
+                operation="get_session_history",
+            )
+            return []

    async def get_similar_task_outcomes(
        self,
@@ -341,7 +431,17 @@ class GraphitiMemory:
        if not await self._ensure_initialized():
            return []

-        return await self._search.get_similar_task_outcomes(task_description, limit)
+        try:
+            return await self._search.get_similar_task_outcomes(task_description, limit)
+        except Exception as e:
+            logger.warning(f"Failed to get similar task outcomes: {e}")
+            self._record_error(f"get_similar_task_outcomes failed: {e}")
+            capture_exception(
+                e,
+                component="graphiti",
+                operation="get_similar_task_outcomes",
+            )
+            return []

    async def get_patterns_and_gotchas(
        self,
@@ -367,9 +467,19 @@ class GraphitiMemory:
        if not await self._ensure_initialized():
            return [], []

-        return await self._search.get_patterns_and_gotchas(
-            query, num_results, min_score
-        )
+        try:
+            return await self._search.get_patterns_and_gotchas(
+                query, num_results, min_score
+            )
+        except Exception as e:
+            logger.warning(f"Failed to get patterns and gotchas: {e}")
+            self._record_error(f"get_patterns_and_gotchas failed: {e}")
+            capture_exception(
+                e,
+                component="graphiti",
+                operation="get_patterns_and_gotchas",
+            )
+            return [], []

    # Status and utility methods

@@ -8,6 +8,8 @@ import json
 import logging
 from datetime import datetime, timezone

+from core.sentry import capture_exception
+
 from .schema import (
    EPISODE_TYPE_CODEBASE_DISCOVERY,
    EPISODE_TYPE_GOTCHA,
@@ -82,6 +84,13 @@ class GraphitiQueries:

        except Exception as e:
            logger.warning(f"Failed to save session insights: {e}")
+            capture_exception(
+                e,
+                operation="add_session_insight",
+                group_id=self.group_id,
+                spec_id=self.spec_context_id,
+                session_number=session_num,
+            )
            return False

    async def add_codebase_discoveries(
@@ -124,6 +133,13 @@ class GraphitiQueries:

        except Exception as e:
            logger.warning(f"Failed to save codebase discoveries: {e}")
+            capture_exception(
+                e,
+                operation="add_codebase_discoveries",
+                group_id=self.group_id,
+                spec_id=self.spec_context_id,
+                discovery_count=len(discoveries),
+            )
            return False

    async def add_pattern(self, pattern: str) -> bool:
@@ -160,6 +176,13 @@ class GraphitiQueries:

        except Exception as e:
            logger.warning(f"Failed to save pattern: {e}")
+            capture_exception(
+                e,
+                operation="add_pattern",
+                group_id=self.group_id,
+                spec_id=self.spec_context_id,
+                content_summary=pattern[:100] if pattern else "",
+            )
            return False

    async def add_gotcha(self, gotcha: str) -> bool:
@@ -196,6 +219,13 @@ class GraphitiQueries:

        except Exception as e:
            logger.warning(f"Failed to save gotcha: {e}")
+            capture_exception(
+                e,
+                operation="add_gotcha",
+                group_id=self.group_id,
+                spec_id=self.spec_context_id,
+                content_summary=gotcha[:100] if gotcha else "",
+            )
            return False

    async def add_task_outcome(
@@ -245,6 +275,15 @@ class GraphitiQueries:

        except Exception as e:
            logger.warning(f"Failed to save task outcome: {e}")
+            capture_exception(
+                e,
+                operation="add_task_outcome",
+                group_id=self.group_id,
+                spec_id=self.spec_context_id,
+                task_id=task_id,
+                success=success,
+                content_summary=outcome[:100] if outcome else "",
+            )
            return False

    async def add_structured_insights(self, insights: dict) -> bool:
@@ -459,4 +498,26 @@ class GraphitiQueries:

        except Exception as e:
            logger.warning(f"Failed to save structured insights: {e}")
+            # Build content summary of insight types
+            insight_types = []
+            if insights.get("file_insights"):
+                insight_types.append(f"files:{len(insights['file_insights'])}")
+            if insights.get("patterns_discovered"):
+                insight_types.append(f"patterns:{len(insights['patterns_discovered'])}")
+            if insights.get("gotchas_discovered"):
+                insight_types.append(f"gotchas:{len(insights['gotchas_discovered'])}")
+            if insights.get("approach_outcome"):
+                insight_types.append("outcome:1")
+            if insights.get("recommendations"):
+                insight_types.append(
+                    f"recommendations:{len(insights['recommendations'])}"
+                )
+
+            capture_exception(
+                e,
+                operation="add_structured_insights",
+                group_id=self.group_id,
+                spec_id=self.spec_context_id,
+                content_summary=", ".join(insight_types) if insight_types else "empty",
+            )
            return False
@@ -9,6 +9,8 @@ import json
 import logging
 from pathlib import Path

+from core.sentry import capture_exception
+
 from .schema import (
    EPISODE_TYPE_GOTCHA,
    EPISODE_TYPE_PATTERN,
@@ -120,6 +122,12 @@ class GraphitiSearch:

        except Exception as e:
            logger.warning(f"Failed to search context: {e}")
+            capture_exception(
+                e,
+                query_summary=query[:100] if query else "",
+                group_id=self.group_id,
+                operation="get_relevant_context",
+            )
            return []

    async def get_session_history(
@@ -174,6 +182,11 @@ class GraphitiSearch:

        except Exception as e:
            logger.warning(f"Failed to get session history: {e}")
+            capture_exception(
+                e,
+                group_id=self.group_id,
+                operation="get_session_history",
+            )
            return []

    async def get_similar_task_outcomes(
@@ -227,6 +240,12 @@ class GraphitiSearch:

        except Exception as e:
            logger.warning(f"Failed to get similar task outcomes: {e}")
+            capture_exception(
+                e,
+                query_summary=task_description[:100] if task_description else "",
+                group_id=self.group_id,
+                operation="get_similar_task_outcomes",
+            )
            return []

    async def get_patterns_and_gotchas(
@@ -337,4 +356,10 @@ class GraphitiSearch:

        except Exception as e:
            logger.warning(f"Failed to get patterns/gotchas: {e}")
+            capture_exception(
+                e,
+                query_summary=query[:100] if query else "",
+                group_id=self.group_id,
+                operation="get_patterns_and_gotchas",
+            )
            return [], []
@@ -126,7 +126,7 @@ class LinearProjectState:
    def save(self, spec_dir: Path) -> None:
        """Save state to the spec directory."""
        marker_file = spec_dir / LINEAR_PROJECT_MARKER
-        with open(marker_file, "w") as f:
+        with open(marker_file, "w", encoding="utf-8") as f:
            json.dump(self.to_dict(), f, indent=2)

    @classmethod
@@ -137,9 +137,9 @@ class LinearProjectState:
            return None

        try:
-            with open(marker_file) as f:
+            with open(marker_file, encoding="utf-8") as f:
                return cls.from_dict(json.load(f))
-        except (OSError, json.JSONDecodeError):
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
            return None


@@ -158,9 +158,9 @@ class LinearManager:
            return None

        try:
-            with open(plan_file) as f:
+            with open(plan_file, encoding="utf-8") as f:
                return json.load(f)
-        except (OSError, json.JSONDecodeError):
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
            return None

    def get_subtasks_for_sync(self) -> list[dict]:
@@ -81,7 +81,7 @@ class LinearTaskState:
    def save(self, spec_dir: Path) -> None:
        """Save state to the spec directory."""
        state_file = spec_dir / LINEAR_TASK_FILE
-        with open(state_file, "w") as f:
+        with open(state_file, "w", encoding="utf-8") as f:
            json.dump(self.to_dict(), f, indent=2)

    @classmethod
@@ -92,9 +92,9 @@ class LinearTaskState:
            return None

        try:
-            with open(state_file) as f:
+            with open(state_file, encoding="utf-8") as f:
                return cls.from_dict(json.load(f))
-        except (OSError, json.JSONDecodeError):
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
            return None


@@ -38,9 +38,9 @@ def update_codebase_map(spec_dir: Path, discoveries: dict[str, str]) -> None:
    # Load existing map or create new
    if map_file.exists():
        try:
-            with open(map_file) as f:
+            with open(map_file, encoding="utf-8") as f:
                codebase_map = json.load(f)
-        except (OSError, json.JSONDecodeError):
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
            codebase_map = {}
    else:
        codebase_map = {}
@@ -58,15 +58,16 @@ def update_codebase_map(spec_dir: Path, discoveries: dict[str, str]) -> None:
    )

    # Write back
-    with open(map_file, "w") as f:
+    with open(map_file, "w", encoding="utf-8") as f:
        json.dump(codebase_map, f, indent=2, sort_keys=True)

    # Also save to Graphiti if enabled
    if is_graphiti_memory_enabled() and discoveries:
        try:
-            graphiti = get_graphiti_memory(spec_dir)
+            graphiti = run_async(get_graphiti_memory(spec_dir))
            if graphiti:
                run_async(graphiti.save_codebase_discoveries(discoveries))
+                run_async(graphiti.close())
                logger.info("Codebase discoveries also saved to Graphiti")
        except Exception as e:
            logger.warning(f"Graphiti codebase save failed: {e}")
@@ -90,12 +91,12 @@ def load_codebase_map(spec_dir: Path) -> dict[str, str]:
        return {}

    try:
-        with open(map_file) as f:
+        with open(map_file, encoding="utf-8") as f:
            codebase_map = json.load(f)

        # Remove metadata before returning
        codebase_map.pop("_metadata", None)
        return codebase_map

-    except (OSError, json.JSONDecodeError):
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
        return {}
@@ -12,10 +12,12 @@ import logging
 from pathlib import Path
 from typing import TYPE_CHECKING, Any

+from core.sentry import capture_exception
+
 logger = logging.getLogger(__name__)

 if TYPE_CHECKING:
-    from graphiti_memory import GraphitiMemory
+    from integrations.graphiti.memory import GraphitiMemory


 def is_graphiti_memory_enabled() -> bool:
@@ -37,51 +39,80 @@ def is_graphiti_memory_enabled() -> bool:
        return False


-def get_graphiti_memory(
+async def get_graphiti_memory(
    spec_dir: Path, project_dir: Path | None = None
 ) -> "GraphitiMemory | None":
    """
-    Get a GraphitiMemory instance if available.
+    Get an initialized GraphitiMemory instance if available.

    Args:
        spec_dir: Spec directory
        project_dir: Project root directory (defaults to spec_dir.parent.parent)

    Returns:
-        GraphitiMemory instance or None if not available
+        Initialized GraphitiMemory instance or None if not available
+
+    Note:
+        This function is async and calls initialize() on the memory instance
+        before returning, following the GitHub pattern for proper initialization.
    """
    if not is_graphiti_memory_enabled():
        return None

    try:
-        from graphiti_memory import GraphitiMemory, GroupIdMode
+        from integrations.graphiti.memory import GraphitiMemory, GroupIdMode

        if project_dir is None:
            project_dir = spec_dir.parent.parent
        # Use project-wide shared memory for cross-spec learning
-        return GraphitiMemory(spec_dir, project_dir, group_id_mode=GroupIdMode.PROJECT)
+        memory = GraphitiMemory(
+            spec_dir, project_dir, group_id_mode=GroupIdMode.PROJECT
+        )
+
+        # Initialize the memory instance (following GitHub pattern)
+        await memory.initialize()
+
+        return memory
    except ImportError:
        return None
+    except Exception as e:
+        logger.warning(f"Failed to initialize Graphiti memory: {e}")
+        capture_exception(
+            e,
+            function="get_graphiti_memory",
+            spec_dir=str(spec_dir),
+            project_dir=str(project_dir) if project_dir else None,
+        )
+        return None


 def run_async(coro):
    """
    Run an async coroutine synchronously.

-    Handles the case where we're already in an event loop.
+    NOTE: This should only be called from synchronous code. For async callers,
+    use the async function directly with await to ensure proper execution.

    Args:
        coro: Async coroutine to run

    Returns:
-        Result of the coroutine or a Future if already in event loop
+        Result of the coroutine, or None if already in an async context
    """
    try:
-        loop = asyncio.get_running_loop()
-        # Already in an event loop - create a task
-        return asyncio.ensure_future(coro)
+        asyncio.get_running_loop()
+        # Already in an async context - caller should use await directly
+        # Log a warning and return None to avoid returning a Future that
+        # callers would incorrectly try to use as the actual result
+        logger.warning(
+            "run_async called from async context. "
+            "Use await directly for proper execution."
+        )
+        # Close the coroutine to avoid "coroutine was never awaited" warning
+        coro.close()
+        return None
    except RuntimeError:
-        # No event loop running - create one
+        # No event loop running - safe to create one
        return asyncio.run(coro)


@@ -105,7 +136,7 @@ async def save_to_graphiti_async(
    Returns:
        True if save succeeded, False otherwise
    """
-    graphiti = get_graphiti_memory(spec_dir, project_dir)
+    graphiti = await get_graphiti_memory(spec_dir, project_dir)
    if graphiti is None:
        return False

@@ -130,13 +161,27 @@ async def save_to_graphiti_async(

    except Exception as e:
        logger.warning(f"Failed to save to Graphiti: {e}")
+        capture_exception(
+            e,
+            function="save_to_graphiti_async",
+            spec_dir=str(spec_dir),
+            session_num=session_num,
+            project_dir=str(project_dir) if project_dir else None,
+        )
        return False
    finally:
        # Always close the graphiti connection (swallow exceptions to avoid overriding)
        if graphiti is not None:
            try:
                await graphiti.close()
-            except Exception as e:
+            except Exception as close_error:
                logger.debug(
                    "Failed to close Graphiti memory connection", exc_info=True
                )
+                capture_exception(
+                    close_error,
+                    function="save_to_graphiti_async",
+                    context="closing_connection",
+                    spec_dir=str(spec_dir),
+                    session_num=session_num,
+                )
@@ -36,7 +36,7 @@ def append_gotcha(spec_dir: Path, gotcha: str) -> None:
    # Load existing gotchas
    existing_gotchas = set()
    if gotchas_file.exists():
-        content = gotchas_file.read_text()
+        content = gotchas_file.read_text(encoding="utf-8")
        # Extract bullet points
        for line in content.split("\n"):
            line = line.strip()
@@ -47,7 +47,7 @@ def append_gotcha(spec_dir: Path, gotcha: str) -> None:
    gotcha_stripped = gotcha.strip()
    if gotcha_stripped and gotcha_stripped not in existing_gotchas:
        # Append to file
-        with open(gotchas_file, "a") as f:
+        with open(gotchas_file, "a", encoding="utf-8") as f:
            if gotchas_file.stat().st_size == 0:
                # First entry - add header
                f.write("# Gotchas and Pitfalls\n\n")
@@ -57,9 +57,10 @@ def append_gotcha(spec_dir: Path, gotcha: str) -> None:
        # Also save to Graphiti if enabled
        if is_graphiti_memory_enabled():
            try:
-                graphiti = get_graphiti_memory(spec_dir)
+                graphiti = run_async(get_graphiti_memory(spec_dir))
                if graphiti:
                    run_async(graphiti.save_gotcha(gotcha_stripped))
+                    run_async(graphiti.close())
            except Exception as e:
                logger.warning(f"Graphiti gotcha save failed: {e}")

@@ -80,7 +81,7 @@ def load_gotchas(spec_dir: Path) -> list[str]:
    if not gotchas_file.exists():
        return []

-    content = gotchas_file.read_text()
+    content = gotchas_file.read_text(encoding="utf-8")
    gotchas = []

    for line in content.split("\n"):
@@ -112,7 +113,7 @@ def append_pattern(spec_dir: Path, pattern: str) -> None:
    # Load existing patterns
    existing_patterns = set()
    if patterns_file.exists():
-        content = patterns_file.read_text()
+        content = patterns_file.read_text(encoding="utf-8")
        # Extract bullet points
        for line in content.split("\n"):
            line = line.strip()
@@ -123,7 +124,7 @@ def append_pattern(spec_dir: Path, pattern: str) -> None:
    pattern_stripped = pattern.strip()
    if pattern_stripped and pattern_stripped not in existing_patterns:
        # Append to file
-        with open(patterns_file, "a") as f:
+        with open(patterns_file, "a", encoding="utf-8") as f:
            if patterns_file.stat().st_size == 0:
                # First entry - add header
                f.write("# Code Patterns\n\n")
@@ -133,9 +134,10 @@ def append_pattern(spec_dir: Path, pattern: str) -> None:
        # Also save to Graphiti if enabled
        if is_graphiti_memory_enabled():
            try:
-                graphiti = get_graphiti_memory(spec_dir)
+                graphiti = run_async(get_graphiti_memory(spec_dir))
                if graphiti:
                    run_async(graphiti.save_pattern(pattern_stripped))
+                    run_async(graphiti.close())
            except Exception as e:
                logger.warning(f"Graphiti pattern save failed: {e}")

@@ -156,7 +158,7 @@ def load_patterns(spec_dir: Path) -> list[str]:
    if not patterns_file.exists():
        return []

-    content = patterns_file.read_text()
+    content = patterns_file.read_text(encoding="utf-8")
    patterns = []

    for line in content.split("\n"):
@@ -76,7 +76,7 @@ def save_session_insights(
    }

    # Write to file (always use file-based storage)
-    with open(session_file, "w") as f:
+    with open(session_file, "w", encoding="utf-8") as f:
        json.dump(session_data, f, indent=2)

    # Also save to Graphiti if enabled (non-blocking, errors logged but not raised)
@@ -110,9 +110,9 @@ def load_all_insights(spec_dir: Path) -> list[dict[str, Any]]:
    insights = []
    for session_file in session_files:
        try:
-            with open(session_file) as f:
+            with open(session_file, encoding="utf-8") as f:
                insights.append(json.load(f))
-        except (OSError, json.JSONDecodeError):
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
            # Skip corrupted files
            continue

@@ -17,6 +17,7 @@ import logging
 from .ai_resolver import AIResolver
 from .auto_merger import AutoMerger, MergeContext
 from .file_merger import apply_ai_merge, extract_location_content
+from .progress import MergeProgressCallback, MergeProgressStage
 from .types import (
    ConflictRegion,
    ConflictSeverity,
@@ -60,6 +61,7 @@ class ConflictResolver:
        baseline_content: str,
        task_snapshots: list[TaskSnapshot],
        conflicts: list[ConflictRegion],
+        progress_callback: MergeProgressCallback | None = None,
    ) -> MergeResult:
        """
        Resolve conflicts using AutoMerger and AIResolver.
@@ -69,6 +71,8 @@ class ConflictResolver:
            baseline_content: Original file content
            task_snapshots: Snapshots from all tasks modifying this file
            conflicts: List of detected conflicts
+            progress_callback: Optional callback for emitting per-conflict
+                resolution progress with details about current file and conflict count

        Returns:
            MergeResult with resolution details
@@ -78,8 +82,23 @@ class ConflictResolver:
        remaining: list[ConflictRegion] = []
        ai_calls = 0
        tokens_used = 0
+        total_conflicts = len(conflicts)

-        for conflict in conflicts:
+        for idx, conflict in enumerate(conflicts):
+            if progress_callback:
+                # Emit per-conflict progress within the resolving stage (50-75%)
+                # Calculate progress after processing (idx + 1) to reach 75% on last conflict
+                conflict_percent = 50 + int(((idx + 1) / max(total_conflicts, 1)) * 25)
+                progress_callback(
+                    stage=MergeProgressStage.RESOLVING,
+                    percent=conflict_percent,
+                    message=f"Resolving conflict {idx + 1}/{total_conflicts} in {file_path}",
+                    details={
+                        "current_file": file_path,
+                        "conflicts_found": total_conflicts,
+                        "conflicts_resolved": len(resolved),
+                    },
+                )
            # Try auto-merge first
            if conflict.can_auto_merge and conflict.merge_strategy:
                context = MergeContext(
@@ -61,7 +61,7 @@ class EvolutionStorage:
            return {}

        try:
-            with open(self.evolution_file) as f:
+            with open(self.evolution_file, encoding="utf-8") as f:
                data = json.load(f)

            evolutions = {}
@@ -88,7 +88,7 @@ class EvolutionStorage:
                for file_path, evolution in evolutions.items()
            }

-            with open(self.evolution_file, "w") as f:
+            with open(self.evolution_file, "w", encoding="utf-8") as f:
                json.dump(data, f, indent=2)

            logger.debug(f"Saved evolution data for {len(evolutions)} files")
@@ -83,10 +83,16 @@ def apply_single_task_changes(
            # Addition - need to determine where to add
            if change.change_type == ChangeType.ADD_IMPORT:
                # Add import at top
+                # Content is already normalized to LF, so only check for \n
+                has_trailing_newline = content.endswith("\n")
                lines = content.splitlines()
                import_end = find_import_end(lines, file_path)
-                lines.insert(import_end, change.content_after)
+                # Strip trailing newline from content_after to prevent double newlines
+                # (content_after may include newline from diff generation)
+                lines.insert(import_end, change.content_after.rstrip("\n\r"))
                content = line_ending.join(lines)
+                if has_trailing_newline:
+                    content += line_ending
            elif change.change_type == ChangeType.ADD_FUNCTION:
                # Add function at end (before exports)
                content += f"{line_ending}{line_ending}{change.content_after}"
@@ -149,13 +155,21 @@ def combine_non_conflicting_changes(

    # Add imports
    if imports:
+        # Content is already normalized to LF, so only check for \n
+        has_trailing_newline = content.endswith("\n")
        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:
-                lines.insert(import_end, imp.content_after)
+            # Strip trailing newline from content_after to prevent double newlines
+            import_content = (
+                imp.content_after.rstrip("\n\r") if imp.content_after else ""
+            )
+            if import_content and import_content not in content:
+                lines.insert(import_end, import_content)
                import_end += 1
        content = line_ending.join(lines)
+        if has_trailing_newline:
+            content += line_ending

    # Apply modifications
    for mod in modifications:
@@ -75,7 +75,7 @@ def install_hook(project_path: Path) -> bool:
    # Handle worktrees (where .git is a file, not directory)
    if git_dir.is_file():
        # Read the gitdir from the file
-        content = git_dir.read_text().strip()
+        content = git_dir.read_text(encoding="utf-8").strip()
        if content.startswith("gitdir:"):
            git_dir = Path(content.split(":", 1)[1].strip())
        else:
@@ -93,7 +93,7 @@ def install_hook(project_path: Path) -> bool:

    # Check if hook already exists
    if hook_path.exists():
-        existing = hook_path.read_text()
+        existing = hook_path.read_text(encoding="utf-8")
        if "FileTimelineTracker" in existing:
            print(f"Hook already installed at {hook_path}")
            return True
@@ -104,13 +104,13 @@ def install_hook(project_path: Path) -> bool:
        print(f"Backed up existing hook to {backup_path}")

        # Append our hook to existing
-        with open(hook_path, "a") as f:
+        with open(hook_path, "a", encoding="utf-8") as f:
            f.write("\n\n# FileTimelineTracker integration\n")
            f.write(HOOK_SCRIPT.split("#!/bin/bash", 1)[1])  # Skip shebang
        print(f"Appended FileTimelineTracker hook to {hook_path}")
    else:
        # Write new hook
-        hook_path.write_text(HOOK_SCRIPT)
+        hook_path.write_text(HOOK_SCRIPT, encoding="utf-8")
        print(f"Created new hook at {hook_path}")

    # Make executable
@@ -127,7 +127,7 @@ def uninstall_hook(project_path: Path) -> bool:
    git_dir = project_path / ".git"

    if git_dir.is_file():
-        content = git_dir.read_text().strip()
+        content = git_dir.read_text(encoding="utf-8").strip()
        if content.startswith("gitdir:"):
            git_dir = Path(content.split(":", 1)[1].strip())

@@ -137,7 +137,7 @@ def uninstall_hook(project_path: Path) -> bool:
        print("No hook to uninstall")
        return True

-    content = hook_path.read_text()
+    content = hook_path.read_text(encoding="utf-8")
    if "FileTimelineTracker" not in content:
        print("Hook does not contain FileTimelineTracker integration")
        return True
@@ -18,6 +18,7 @@ import logging
 from .conflict_detector import ConflictDetector
 from .conflict_resolver import ConflictResolver
 from .file_merger import apply_single_task_changes, combine_non_conflicting_changes
+from .progress import MergeProgressCallback, MergeProgressStage
 from .types import (
    ChangeType,
    FileAnalysis,
@@ -57,6 +58,7 @@ class MergePipeline:
        file_path: str,
        baseline_content: str,
        task_snapshots: list[TaskSnapshot],
+        progress_callback: MergeProgressCallback | None = None,
    ) -> MergeResult:
        """
        Merge changes from multiple tasks for a single file.
@@ -65,6 +67,8 @@ class MergePipeline:
            file_path: Path to the file
            baseline_content: Original baseline content
            task_snapshots: Snapshots from tasks that modified this file
+            progress_callback: Optional callback for emitting per-file progress
+                within the 'resolving' stage (50-75% range)

        Returns:
            MergeResult with merged content or conflict info
@@ -72,6 +76,14 @@ class MergePipeline:
        task_ids = [s.task_id for s in task_snapshots]
        logger.info(f"Merging {file_path} with {len(task_snapshots)} task(s)")

+        if progress_callback:
+            progress_callback(
+                stage=MergeProgressStage.RESOLVING,
+                percent=50,
+                message=f"Merging file: {file_path}",
+                details={"current_file": file_path},
+            )
+
        # If only one task modified the file, no conflict possible
        if len(task_snapshots) == 1:
            snapshot = task_snapshots[0]
@@ -119,6 +131,7 @@ class MergePipeline:
            baseline_content=baseline_content,
            task_snapshots=task_snapshots,
            conflicts=conflicts,
+            progress_callback=progress_callback,
        )

    def _build_task_analyses(
@@ -108,5 +108,5 @@ class MergeReport:

    def save(self, path: Path) -> None:
        """Save report to JSON file."""
-        with open(path, "w") as f:
+        with open(path, "w", encoding="utf-8") as f:
            json.dump(self.to_dict(), f, indent=2)
@@ -33,6 +33,7 @@ from .merge_pipeline import MergePipeline

 # Re-export models for backwards compatibility
 from .models import MergeReport, MergeStats, TaskMergeRequest
+from .progress import MergeProgressCallback, MergeProgressStage
 from .semantic_analyzer import SemanticAnalyzer
 from .types import (
    ConflictRegion,
@@ -260,6 +261,7 @@ class MergeOrchestrator:
        task_id: str,
        worktree_path: Path | None = None,
        target_branch: str = "main",
+        progress_callback: MergeProgressCallback | None = None,
    ) -> MergeReport:
        """
        Merge a single task's changes into the target branch.
@@ -268,6 +270,8 @@ class MergeOrchestrator:
            task_id: The task identifier
            worktree_path: Path to the task's worktree (auto-detected if not provided)
            target_branch: Branch to merge into
+            progress_callback: Optional callback for progress updates.
+                Called with (stage, percent, message, details) at key pipeline stages.

        Returns:
            MergeReport with results
@@ -284,7 +288,20 @@ class MergeOrchestrator:
        report = MergeReport(started_at=datetime.now(), tasks_merged=[task_id])
        start_time = datetime.now()

+        def _emit(
+            stage: MergeProgressStage,
+            percent: int,
+            message: str,
+            details: dict[str, Any] | None = None,
+        ) -> None:
+            """Emit progress if a callback is provided."""
+            if progress_callback is not None:
+                progress_callback(stage, percent, message, details)
+
        try:
+            # --- ANALYZING stage (0-25%) ---
+            _emit(MergeProgressStage.ANALYZING, 0, "Starting merge analysis")
+
            # Find worktree if not provided
            if worktree_path is None:
                debug_detailed(MODULE, "Auto-detecting worktree path...")
@@ -293,16 +310,23 @@ class MergeOrchestrator:
                    debug_error(MODULE, f"Could not find worktree for task {task_id}")
                    report.success = False
                    report.error = f"Could not find worktree for task {task_id}"
+                    _emit(
+                        MergeProgressStage.ERROR,
+                        0,
+                        f"Could not find worktree for task {task_id}",
+                    )
                    return report
                debug_detailed(MODULE, f"Found worktree: {worktree_path}")

            # Ensure evolution data is up to date
+            _emit(MergeProgressStage.ANALYZING, 5, "Loading file evolution data")
            debug(MODULE, "Refreshing evolution data from git...")
            self.evolution_tracker.refresh_from_git(
                task_id, worktree_path, target_branch=target_branch
            )

            # Get files modified by this task
+            _emit(MergeProgressStage.ANALYZING, 15, "Running semantic analysis")
            modifications = self.evolution_tracker.get_task_modifications(task_id)
            debug(
                MODULE,
@@ -312,11 +336,39 @@ class MergeOrchestrator:
            if not modifications:
                debug_warning(MODULE, f"No modifications found for task {task_id}")
                logger.info(f"No modifications found for task {task_id}")
+                _emit(
+                    MergeProgressStage.COMPLETE,
+                    100,
+                    "No modifications found",
+                )
                report.completed_at = datetime.now()
                return report

-            # Process each modified file
-            for file_path, snapshot in modifications:
+            _emit(
+                MergeProgressStage.ANALYZING,
+                25,
+                f"Found {len(modifications)} modified files",
+            )
+
+            # --- DETECTING_CONFLICTS stage (25-50%) ---
+            _emit(
+                MergeProgressStage.DETECTING_CONFLICTS,
+                25,
+                "Detecting conflicts",
+            )
+
+            # --- RESOLVING stage (50-75%) ---
+            total_files = len(modifications)
+            for idx, (file_path, snapshot) in enumerate(modifications):
+                # Calculate progress after processing (idx + 1) to reach 75% on last file
+                file_percent = 50 + int(((idx + 1) / max(total_files, 1)) * 25)
+                _emit(
+                    MergeProgressStage.RESOLVING,
+                    file_percent,
+                    f"Merging file {idx + 1}/{total_files}",
+                    {"current_file": file_path},
+                )
+
                debug_detailed(
                    MODULE,
                    f"Processing file: {file_path}",
@@ -349,13 +401,31 @@ class MergeOrchestrator:
                    file=file_path,
                )

+            # --- VALIDATING stage (75-100%) ---
+            _emit(
+                MergeProgressStage.VALIDATING,
+                75,
+                "Validating merge results",
+                {
+                    "conflicts_found": report.stats.conflicts_detected,
+                    "conflicts_resolved": report.stats.conflicts_auto_resolved,
+                },
+            )
+
            report.success = report.stats.files_failed == 0

+            _emit(
+                MergeProgressStage.VALIDATING,
+                90,
+                "Validation complete",
+            )
+
        except Exception as e:
            debug_error(MODULE, f"Merge failed for task {task_id}", error=str(e))
            logger.exception(f"Merge failed for task {task_id}")
            report.success = False
            report.error = str(e)
+            _emit(MergeProgressStage.ERROR, 0, f"Merge failed: {e}")

        report.completed_at = datetime.now()
        report.stats.duration_seconds = (
@@ -366,6 +436,18 @@ class MergeOrchestrator:
        if not self.dry_run:
            self._save_report(report, task_id)

+        # --- COMPLETE stage (100%) ---
+        if report.success:
+            _emit(
+                MergeProgressStage.COMPLETE,
+                100,
+                f"Merge complete for {task_id}",
+                {
+                    "conflicts_found": report.stats.conflicts_detected,
+                    "conflicts_resolved": report.stats.conflicts_auto_resolved,
+                },
+            )
+
        debug_success(
            MODULE,
            f"Merge complete for {task_id}",
@@ -382,6 +464,7 @@ class MergeOrchestrator:
        self,
        requests: list[TaskMergeRequest],
        target_branch: str = "main",
+        progress_callback: MergeProgressCallback | None = None,
    ) -> MergeReport:
        """
        Merge multiple tasks' changes.
@@ -392,6 +475,8 @@ class MergeOrchestrator:
        Args:
            requests: List of merge requests (one per task)
            target_branch: Branch to merge into
+            progress_callback: Optional callback for progress updates.
+                Called with (stage, percent, message, details) at key pipeline stages.

        Returns:
            MergeReport with combined results
@@ -402,11 +487,33 @@ class MergeOrchestrator:
        )
        start_time = datetime.now()

+        def _emit(
+            stage: MergeProgressStage,
+            percent: int,
+            message: str,
+            details: dict[str, Any] | None = None,
+        ) -> None:
+            """Emit progress if a callback is provided."""
+            if progress_callback is not None:
+                progress_callback(stage, percent, message, details)
+
        try:
+            # --- ANALYZING stage (0-25%) ---
+            _emit(
+                MergeProgressStage.ANALYZING,
+                0,
+                f"Starting merge analysis for {len(requests)} tasks",
+            )
+
            # Sort by priority (higher first)
            requests = sorted(requests, key=lambda r: -r.priority)

            # Refresh evolution data for all tasks
+            _emit(
+                MergeProgressStage.ANALYZING,
+                5,
+                "Loading file evolution data",
+            )
            for request in requests:
                if request.worktree_path and request.worktree_path.exists():
                    self.evolution_tracker.refresh_from_git(
@@ -416,11 +523,38 @@ class MergeOrchestrator:
                    )

            # Find all files modified by any task
+            _emit(
+                MergeProgressStage.ANALYZING,
+                15,
+                "Running semantic analysis",
+            )
            task_ids = [r.task_id for r in requests]
            file_tasks = self.evolution_tracker.get_files_modified_by_tasks(task_ids)

-            # Process each file
-            for file_path, modifying_tasks in file_tasks.items():
+            _emit(
+                MergeProgressStage.ANALYZING,
+                25,
+                f"Found {len(file_tasks)} files to merge",
+            )
+
+            # --- DETECTING_CONFLICTS stage (25-50%) ---
+            _emit(
+                MergeProgressStage.DETECTING_CONFLICTS,
+                25,
+                "Detecting conflicts across tasks",
+            )
+
+            # --- RESOLVING stage (50-75%) ---
+            total_files = len(file_tasks)
+            for idx, (file_path, modifying_tasks) in enumerate(file_tasks.items()):
+                file_percent = 50 + int((idx / max(total_files, 1)) * 25)
+                _emit(
+                    MergeProgressStage.RESOLVING,
+                    file_percent,
+                    f"Merging file {idx + 1}/{total_files}",
+                    {"current_file": file_path},
+                )
+
                # Get snapshots from all tasks that modified this file
                evolution = self.evolution_tracker.get_file_evolution(file_path)
                if not evolution:
@@ -466,8 +600,25 @@ class MergeOrchestrator:
                report.file_results[file_path] = result
                self._update_stats(report.stats, result)

+            # --- VALIDATING stage (75-100%) ---
+            _emit(
+                MergeProgressStage.VALIDATING,
+                75,
+                "Validating merge results",
+                {
+                    "conflicts_found": report.stats.conflicts_detected,
+                    "conflicts_resolved": report.stats.conflicts_auto_resolved,
+                },
+            )
+
            report.success = report.stats.files_failed == 0

+            _emit(
+                MergeProgressStage.VALIDATING,
+                90,
+                "Validation complete",
+            )
+
        except Exception as e:
            debug_error(
                MODULE,
@@ -478,6 +629,7 @@ class MergeOrchestrator:
            logger.exception("Merge failed")
            report.success = False
            report.error = str(e)
+            _emit(MergeProgressStage.ERROR, 0, f"Merge failed: {e}")

        report.completed_at = datetime.now()
        report.stats.duration_seconds = (
@@ -489,6 +641,18 @@ class MergeOrchestrator:
            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
            self._save_report(report, f"multi_{timestamp}")

+        # --- COMPLETE stage (100%) ---
+        if report.success:
+            _emit(
+                MergeProgressStage.COMPLETE,
+                100,
+                f"Merge complete for {len(requests)} tasks",
+                {
+                    "conflicts_found": report.stats.conflicts_detected,
+                    "conflicts_resolved": report.stats.conflicts_auto_resolved,
+                },
+            )
+
        return report

    def _merge_file(
--- a/Show More
+++ b/Show More