fix: enable pytest in worktrees for pre-commit hook

Remove the worktree skip since path resolution is now handled by running pytest from project root. This catches test failures locally before CI.
fix: update all test fixtures to use proper QA approval structure
2026-02-12 15:03:23 +02:00 · 2026-02-12 14:57:10 +02:00 · 2026-02-12 14:51:11 +02:00 · 2026-02-12 14:36:33 +02:00 · 2026-02-12 14:21:20 +02:00 · 2026-02-12 14:06:02 +02:00
713 changed files with 120509 additions and 22914 deletions
@@ -0,0 +1,12 @@
+[run]
+parallel = true
+source = apps/backend/cli
+omit =
+    */tests/*
+    */__pycache__/*
+    */.venv/*
+
+[report]
+exclude_lines =
+    pragma: no cover
+    if __name__ == "__main__":
@@ -33,13 +33,27 @@ 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
 - [ ] I've tested my changes locally
 - [ ] I've followed the code principles (SOLID, DRY, KISS)
 - [ ] My PR is small and focused (< 400 lines ideally)
- [ ] **(Python only)** All file operations specify `encoding="utf-8"` for text files

 ## Platform Testing Checklist

@@ -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
@@ -70,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'

@@ -89,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');
@@ -149,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
@@ -7,6 +7,7 @@
 Thumbs.db
 ehthumbs.db
 Desktop.ini
+nul

 # ===========================
 # Security - Environment & Secrets
@@ -57,6 +58,7 @@ lerna-debug.log*
 # ===========================
 .auto-claude/
 .planning/
+.planning-archive/
 .auto-build-security.json
 .auto-claude-security.json
 .auto-claude-status
@@ -1,52 +1,36 @@
 #!/bin/sh

 # =============================================================================
-# GIT WORKTREE CONTEXT HANDLING
+# GIT WORKTREE ENVIRONMENT CLEANUP
 # =============================================================================
-# When running in a worktree, we need to preserve git context to prevent HEAD
-# corruption. However, we must also CLEAR these variables when NOT in a worktree
-# to prevent cross-worktree contamination (files leaking between worktrees).
+# Git automatically sets GIT_DIR (and CWD to the working tree root) before
+# running hooks -- even in worktrees. We do NOT need to manually parse .git
+# files or export GIT_DIR/GIT_WORK_TREE.
 #
-# The bug: If GIT_DIR/GIT_WORK_TREE are set from a previous worktree session
-# and this hook runs in the main repo (where .git is a directory, not a file),
-# git commands will target the wrong repository, causing files to appear as
-# untracked in the wrong location.
-#
-# Fix: Explicitly unset these variables when NOT in a worktree context.
+# However, external tools (IDEs, agents, parent shells) may leave stale
+# GIT_DIR/GIT_WORK_TREE values in the environment. If these point to a
+# different repo or worktree, git commands in this hook would target the
+# wrong repository. Unsetting them lets git re-resolve the correct values
+# from the working directory.
 # =============================================================================
-
-if [ -f ".git" ]; then
-  # We're in a worktree (.git is a file pointing to the actual git dir)
-  # Use -n with /p to only print lines that match the gitdir: prefix, head -1 for safety
-  WORKTREE_GIT_DIR=$(sed -n 's/^gitdir: //p' .git | head -1)
-  if [ -n "$WORKTREE_GIT_DIR" ] && [ -d "$WORKTREE_GIT_DIR" ]; then
-    export GIT_DIR="$WORKTREE_GIT_DIR"
-    export GIT_WORK_TREE="$(pwd)"
-  else
-    # .git file exists but is malformed or points to non-existent directory
-    # CRITICAL: Clear any inherited GIT_DIR/GIT_WORK_TREE to prevent cross-worktree leakage
-    unset GIT_DIR
-    unset GIT_WORK_TREE
-  fi
-else
-  # We're in the main repo (.git is a directory)
-  # CRITICAL: Clear any inherited GIT_DIR/GIT_WORK_TREE to prevent cross-worktree leakage
-  unset GIT_DIR
-  unset GIT_WORK_TREE
-fi
+unset GIT_DIR
+unset GIT_WORK_TREE

 # =============================================================================
 # SAFETY CHECK: Detect and fix corrupted core.worktree configuration
 # =============================================================================
-# If core.worktree is set in the main repo's config (pointing to a worktree),
-# this indicates previous corruption. Fix it automatically.
-if [ ! -f ".git" ]; then
-  CORE_WORKTREE=$(git config --get core.worktree 2>/dev/null || true)
-  if [ -n "$CORE_WORKTREE" ]; then
-    echo "Warning: Detected corrupted core.worktree setting, removing it..."
-    if ! git config --unset core.worktree 2>/dev/null; then
-      echo "Warning: Failed to unset core.worktree. Manual intervention may be needed."
-    fi
+# core.worktree lives in the SHARED .git/config (not per-worktree). If any
+# process accidentally writes it (e.g., running `git init` with a leaked
+# GIT_WORK_TREE), ALL repos and worktrees see the wrong working tree root,
+# causing files from one worktree to "leak" into others.
+#
+# This check runs from both main repo and worktree contexts since the config
+# is shared and corruption can happen from either.
+CORE_WORKTREE=$(git config --get core.worktree 2>/dev/null || true)
+if [ -n "$CORE_WORKTREE" ]; then
+  echo "Warning: Detected corrupted core.worktree setting ('$CORE_WORKTREE'), removing it..."
+  if ! git config --unset core.worktree 2>/dev/null; then
+    echo "Warning: Failed to unset core.worktree. Manual intervention may be needed."
  fi
 fi

@@ -178,37 +162,39 @@ if git diff --cached --name-only | grep -q "^apps/backend/.*\.py$"; then
  fi

  # Run pytest (skip slow/integration tests and Windows-incompatible tests for pre-commit speed)
-  # Use subshell to isolate directory changes and prevent worktree corruption
+  # Run from repo root (not apps/backend) so tests that use Path.resolve() get correct CWD.
+  # PYTHONPATH includes apps/backend so imports resolve correctly.
  echo "Running Python tests..."
  (
-    cd apps/backend
    # Tests to skip: graphiti (external deps), merge_file_tracker/service_orchestrator/worktree/workspace (Windows path/git issues)
    # Also skip tests that require optional dependencies (pydantic structured outputs)
-    IGNORE_TESTS="--ignore=../../tests/test_graphiti.py --ignore=../../tests/test_merge_file_tracker.py --ignore=../../tests/test_service_orchestrator.py --ignore=../../tests/test_worktree.py --ignore=../../tests/test_workspace.py --ignore=../../tests/test_finding_validation.py --ignore=../../tests/test_sdk_structured_output.py --ignore=../../tests/test_structured_outputs.py"
-    
+    # Also skip gitlab_e2e (e2e test sensitive to test-ordering env contamination, validated by CI)
+    IGNORE_TESTS="--ignore=tests/test_graphiti.py --ignore=tests/test_merge_file_tracker.py --ignore=tests/test_service_orchestrator.py --ignore=tests/test_worktree.py --ignore=tests/test_workspace.py --ignore=tests/test_finding_validation.py --ignore=tests/test_sdk_structured_output.py --ignore=tests/test_structured_outputs.py --ignore=tests/test_gitlab_e2e.py"
    # Determine Python executable from venv
    VENV_PYTHON=""
-    if [ -f ".venv/bin/python" ]; then
-      VENV_PYTHON=".venv/bin/python"
-    elif [ -f ".venv/Scripts/python.exe" ]; then
-      VENV_PYTHON=".venv/Scripts/python.exe"
+    if [ -f "apps/backend/.venv/bin/python" ]; then
+      VENV_PYTHON="apps/backend/.venv/bin/python"
+    elif [ -f "apps/backend/.venv/Scripts/python.exe" ]; then
+      VENV_PYTHON="apps/backend/.venv/Scripts/python.exe"
    fi
-    
+
+    # -k "not windows_path": skip tests using fake Windows paths that break
+    # Path.resolve() on macOS/Linux. These are validated by CI on all platforms.
    if [ -n "$VENV_PYTHON" ]; then
      # Check if pytest is installed in venv
      if $VENV_PYTHON -c "import pytest" 2>/dev/null; then
-        PYTHONPATH=. $VENV_PYTHON -m pytest ../../tests/ -v --tb=short -x -m "not slow and not integration" $IGNORE_TESTS
+        PYTHONPATH=apps/backend $VENV_PYTHON -m pytest tests/ -v --tb=short -x -m "not slow and not integration" -k "not windows_path" $IGNORE_TESTS
      else
        echo "Warning: pytest not installed in venv. Installing test dependencies..."
-        $VENV_PYTHON -m pip install -q -r ../../tests/requirements-test.txt
-        PYTHONPATH=. $VENV_PYTHON -m pytest ../../tests/ -v --tb=short -x -m "not slow and not integration" $IGNORE_TESTS
+        $VENV_PYTHON -m pip install -q -r tests/requirements-test.txt
+        PYTHONPATH=apps/backend $VENV_PYTHON -m pytest tests/ -v --tb=short -x -m "not slow and not integration" -k "not windows_path" $IGNORE_TESTS
      fi
-    elif [ -d ".venv" ]; then
+    elif [ -d "apps/backend/.venv" ]; then
      echo "Warning: venv exists but Python not found in it, using system Python"
-      PYTHONPATH=. python -m pytest ../../tests/ -v --tb=short -x -m "not slow and not integration" $IGNORE_TESTS
+      PYTHONPATH=apps/backend python -m pytest tests/ -v --tb=short -x -m "not slow and not integration" -k "not windows_path" $IGNORE_TESTS
    else
      echo "Warning: No .venv found in apps/backend, using system Python"
-      PYTHONPATH=. python -m pytest ../../tests/ -v --tb=short -x -m "not slow and not integration" $IGNORE_TESTS
+      PYTHONPATH=apps/backend python -m pytest tests/ -v --tb=short -x -m "not slow and not integration" -k "not windows_path" $IGNORE_TESTS
    fi
  )
  if [ $? -ne 0 ]; then
@@ -97,9 +97,8 @@ repos:
      - id: ruff-format
        files: ^apps/backend/

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

 ### 🐛 Bug Fixes

+- Fixed task logs disappearing after app restart in development mode (issue #1657)
+
 - Fixed Kanban board status flip-flopping and multi-location task deletion

 - Fixed Windows CLI detection and version selection UX issues
@@ -1,643 +1,295 @@
 # 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`.
+
+## Work Approach
+
+**Investigate before speculating** — Always read the actual code before proposing root causes. Spawn agents to grep and read relevant source files before forming any hypothesis. Never guess at causes without evidence from the codebase.
+
+**Spawn agents for complex tasks** — When tackling complex tasks, spawn sub-agents/agent teams immediately rather than trying to handle everything in a single context window. Never attempt to analyze large codebases or multiple features monolithically.
+
+**Minimal fixes only** — Prefer the simplest approach (e.g., prompt-only changes, single guard clause) before suggesting multi-component solutions. If the user asks for X, implement X — don't bundle additional fixes they didn't request.
+
+## Known Gotchas
+
+**Electron path resolution** — For bug fixes in the Electron app, always check path resolution differences between dev and production builds (`app.isPackaged`, `process.resourcesPath`). Paths that work in dev often break when Electron is bundled for production — verify both contexts.

 ## 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
-
-# Authenticate (token auto-saved to Keychain)
-claude
-# Then type: /login
-# Press Enter to open browser and complete OAuth
-```
-
-### Creating and Running Specs
-```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
-```
-
-### Workspace Management
-```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
 ```

 ### 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/)
-
-**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)
-
-**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
-
-**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
-
-**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
-
-### 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
+npm run dev:debug  # Debug mode with verbose output
+npm run dev:mcp    # Electron MCP server for AI debugging
+
+# 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,15 +2,35 @@

 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)
@@ -151,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>
@@ -16,18 +16,18 @@
 ### Stable Release

 <!-- STABLE_VERSION_BADGE -->
-[![Stable](https://img.shields.io/badge/stable-2.7.4-blue?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.4)
+[![Stable](https://img.shields.io/badge/stable-2.7.5-blue?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.5)
 <!-- STABLE_VERSION_BADGE_END -->

 <!-- STABLE_DOWNLOADS -->
 | Platform | Download |
 |----------|----------|
-| **Windows** | [Auto-Claude-2.7.4-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.4/Auto-Claude-2.7.4-win32-x64.exe) |
-| **macOS (Apple Silicon)** | [Auto-Claude-2.7.4-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.4/Auto-Claude-2.7.4-darwin-arm64.dmg) |
-| **macOS (Intel)** | [Auto-Claude-2.7.4-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.4/Auto-Claude-2.7.4-darwin-x64.dmg) |
-| **Linux** | [Auto-Claude-2.7.4-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.4/Auto-Claude-2.7.4-linux-x86_64.AppImage) |
-| **Linux (Debian)** | [Auto-Claude-2.7.4-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.4/Auto-Claude-2.7.4-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) |
+| **Windows** | [Auto-Claude-2.7.5-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.5/Auto-Claude-2.7.5-win32-x64.exe) |
+| **macOS (Apple Silicon)** | [Auto-Claude-2.7.5-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.5/Auto-Claude-2.7.5-darwin-arm64.dmg) |
+| **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.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.3-orange?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.6-beta.3)
 <!-- 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.3-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.3/Auto-Claude-2.7.6-beta.3-win32-x64.exe) |
+| **macOS (Apple Silicon)** | [Auto-Claude-2.7.6-beta.3-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.3/Auto-Claude-2.7.6-beta.3-darwin-arm64.dmg) |
+| **macOS (Intel)** | [Auto-Claude-2.7.6-beta.3-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.3/Auto-Claude-2.7.6-beta.3-darwin-x64.dmg) |
+| **Linux** | [Auto-Claude-2.7.6-beta.3-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.3/Auto-Claude-2.7.6-beta.3-linux-x86_64.AppImage) |
+| **Linux (Debian)** | [Auto-Claude-2.7.6-beta.3-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.3/Auto-Claude-2.7.6-beta.3-linux-amd64.deb) |
+| **Linux (Flatpak)** | [Auto-Claude-2.7.6-beta.3-linux-x86_64.flatpak](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.3/Auto-Claude-2.7.6-beta.3-linux-x86_64.flatpak) |
 <!-- BETA_DOWNLOADS_END -->

 > All releases include SHA256 checksums and VirusTotal scan results for security verification.
@@ -32,8 +32,8 @@
 # API_TIMEOUT_MS=600000

 # Model override (OPTIONAL)
-# Default: claude-opus-4-5-20251101
-# AUTO_BUILD_MODEL=claude-opus-4-5-20251101
+# Default: claude-opus-4-6
+# AUTO_BUILD_MODEL=claude-opus-4-6


 # =============================================================================
@@ -62,5 +62,15 @@ Thumbs.db
 # Tests (development only)
 tests/

+# Exception: Allow colocated tests within integrations/graphiti
+!integrations/graphiti/tests/
+
 # Auto Claude data directory
 .auto-claude/
+
+# Auto Claude generated files
+.auto-claude-security.json
+.auto-claude-status
+.security-key
+logs/security/
+coverage.json
@@ -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)
@@ -19,5 +19,5 @@ Quick Start:
 See README.md for full documentation.
 """

-__version__ = "2.7.5"
+__version__ = "2.7.6-beta.3"
 __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,86 @@ logger = logging.getLogger(__name__)
 # Configuration constants
 AUTO_CONTINUE_DELAY_SECONDS = 3
 HUMAN_INTERVENTION_FILE = "PAUSE"
+
+# Retry configuration for subtask execution
+MAX_SUBTASK_RETRIES = 5  # Maximum attempts before marking subtask as stuck
+
+# 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,198 @@
-"""
-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_fast_mode,
+    get_phase_client_thinking_kwargs,
+    get_phase_model,
+    get_phase_model_betas,
+)
+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_betas = get_phase_model_betas(spec_dir, "planning", model)
+    thinking_kwargs = get_phase_client_thinking_kwargs(
+        spec_dir, "planning", planning_model
+    )
+    fast_mode = get_fast_mode(spec_dir)
+    logger.info(
+        f"[Planner] [Fast Mode] {'ENABLED' if fast_mode else 'disabled'} for follow-up planning"
+    )
+    client = create_client(
+        project_dir,
+        spec_dir,
+        planning_model,
+        agent_type="planner",
+        betas=planning_betas,
+        fast_mode=fast_mode,
+        **thinking_kwargs,
+    )
+
+    # 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
@@ -1,159 +0,0 @@
-#!/usr/bin/env python3
-"""
-Verification script for agent module refactoring.
-
-This script verifies that:
-1. All modules can be imported
-2. All public API functions are accessible
-3. Backwards compatibility is maintained
-"""
-
-import sys
-from pathlib import Path
-
-# Add parent directory to path
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
-
-def test_imports():
-    """Test that all modules can be imported."""
-    print("Testing module imports...")
-
-    # Test base module
-    from agents import base
-
-    assert hasattr(base, "AUTO_CONTINUE_DELAY_SECONDS")
-    assert hasattr(base, "HUMAN_INTERVENTION_FILE")
-    print("  ✓ agents.base")
-
-    # Test utils module
-    from agents import utils
-
-    assert hasattr(utils, "get_latest_commit")
-    assert hasattr(utils, "load_implementation_plan")
-    print("  ✓ agents.utils")
-
-    # Test memory module
-    from agents import memory
-
-    assert hasattr(memory, "save_session_memory")
-    assert hasattr(memory, "get_graphiti_context")
-    print("  ✓ agents.memory")
-
-    # Test session module
-    from agents import session
-
-    assert hasattr(session, "run_agent_session")
-    assert hasattr(session, "post_session_processing")
-    print("  ✓ agents.session")
-
-    # Test planner module
-    from agents import planner
-
-    assert hasattr(planner, "run_followup_planner")
-    print("  ✓ agents.planner")
-
-    # Test coder module
-    from agents import coder
-
-    assert hasattr(coder, "run_autonomous_agent")
-    print("  ✓ agents.coder")
-
-    print("\n✓ All module imports successful!\n")
-
-
-def test_public_api():
-    """Test that the public API is accessible."""
-    print("Testing public API...")
-
-    # Test main agent module exports
-    import agents
-
-    required_functions = [
-        "run_autonomous_agent",
-        "run_followup_planner",
-        "save_session_memory",
-        "get_graphiti_context",
-        "run_agent_session",
-        "post_session_processing",
-        "get_latest_commit",
-        "load_implementation_plan",
-    ]
-
-    for func_name in required_functions:
-        assert hasattr(agents, func_name), f"Missing function: {func_name}"
-        print(f"  ✓ agents.{func_name}")
-
-    print("\n✓ All public API functions accessible!\n")
-
-
-def test_backwards_compatibility():
-    """Test that the old agent.py facade maintains backwards compatibility."""
-    print("Testing backwards compatibility...")
-
-    # Test that agent.py can be imported
-    import agent
-
-    required_functions = [
-        "run_autonomous_agent",
-        "run_followup_planner",
-        "save_session_memory",
-        "save_session_to_graphiti",
-        "run_agent_session",
-        "post_session_processing",
-    ]
-
-    for func_name in required_functions:
-        assert hasattr(agent, func_name), (
-            f"Missing function in agent module: {func_name}"
-        )
-        print(f"  ✓ agent.{func_name}")
-
-    print("\n✓ Backwards compatibility maintained!\n")
-
-
-def test_module_structure():
-    """Test that the module structure is correct."""
-    print("Testing module structure...")
-
-    from pathlib import Path
-
-    agents_dir = Path(__file__).parent
-
-    required_files = [
-        "__init__.py",
-        "base.py",
-        "utils.py",
-        "memory.py",
-        "session.py",
-        "planner.py",
-        "coder.py",
-    ]
-
-    for filename in required_files:
-        filepath = agents_dir / filename
-        assert filepath.exists(), f"Missing file: {filename}"
-        print(f"  ✓ agents/{filename}")
-
-    print("\n✓ Module structure correct!\n")
-
-
-if __name__ == "__main__":
-    try:
-        test_module_structure()
-        test_imports()
-        test_public_api()
-        test_backwards_compatibility()
-
-        print("=" * 60)
-        print("✓ ALL TESTS PASSED - Refactoring verified!")
-        print("=" * 60)
-
-    except AssertionError as e:
-        print(f"\n✗ TEST FAILED: {e}")
-        sys.exit(1)
-    except ImportError as e:
-        print(f"\n✗ IMPORT ERROR: {e}")
-        print("Note: Some imports may fail due to missing dependencies.")
-        print("This is expected in test environments.")
-        sys.exit(0)  # Don't fail on import errors (expected in test env)
@@ -46,7 +46,7 @@ TOOL_UPDATE_QA_STATUS = "mcp__auto-claude__update_qa_status"
 # Context7 MCP tools for documentation lookup (always enabled)
 CONTEXT7_TOOLS = [
    "mcp__context7__resolve-library-id",
-    "mcp__context7__get-library-docs",
+    "mcp__context7__query-docs",
 ]

 # Linear MCP tools for project management (when LINEAR_API_KEY is set)
@@ -158,7 +158,7 @@ AGENT_CONFIGS = {
        "tools": BASE_READ_TOOLS,
        "mcp_servers": [],  # Self-critique, no external tools
        "auto_claude_tools": [],
-        "thinking_default": "ultrathink",
+        "thinking_default": "high",
    },
    "spec_discovery": {
        "tools": BASE_READ_TOOLS + WEB_TOOLS,
@@ -210,7 +210,7 @@ AGENT_CONFIGS = {
            TOOL_RECORD_GOTCHA,
            TOOL_GET_SESSION_CONTEXT,
        ],
-        "thinking_default": "none",  # Coding doesn't use extended thinking
+        "thinking_default": "low",  # Coding uses minimal thinking (effort: low for Opus, 1024 tokens for Sonnet/Haiku)
    },
    # ═══════════════════════════════════════════════════════════════════════
    # QA PHASES (Read + test + browser + Graphiti memory)
@@ -247,9 +247,9 @@ AGENT_CONFIGS = {
        "tools": BASE_READ_TOOLS + WEB_TOOLS,
        "mcp_servers": [],
        "auto_claude_tools": [],
-        # Note: Default to "none" because insight_extractor uses Haiku which doesn't support thinking
-        # If using Sonnet/Opus models, override max_thinking_tokens in create_simple_client()
-        "thinking_default": "none",
+        # Note: Default to "low" for minimal thinking overhead
+        # Haiku doesn't support thinking; create_simple_client() handles this
+        "thinking_default": "low",
    },
    "merge_resolver": {
        "tools": [],  # Text-only analysis
@@ -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
    # ═══════════════════════════════════════════════════════════════════════
@@ -506,7 +524,7 @@ def get_default_thinking_level(agent_type: str) -> str:
        agent_type: The agent type identifier

    Returns:
-        Thinking level string (none, low, medium, high, ultrathink)
+        Thinking level string (low, medium, high)
    """
    config = get_agent_config(agent_type)
    return config.get("thinking_default", "medium")
@@ -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

@@ -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()

@@ -23,7 +23,8 @@ from .ci_discovery import CIDiscovery
 from .project_analyzer import ProjectAnalyzer
 from .risk_classifier import RiskClassifier
 from .security_scanner import SecurityScanner
-from .test_discovery import TestDiscovery
+
+# TestDiscovery was removed - tests are now co-located in their respective modules

 # insight_extractor is a module with functions, not a class, so don't import it here
 # Import it directly when needed: from analysis import insight_extractor
@@ -37,5 +38,5 @@ __all__ = [
    "RiskClassifier",
    "SecurityScanner",
    "CIDiscovery",
-    "TestDiscovery",
+    # "TestDiscovery",  # Removed - tests now co-located in their modules
 ]
@@ -235,10 +235,15 @@ class FrameworkAnalyzer(BaseAnalyzer):

        # Scripts
        scripts = pkg.get("scripts", {})
+        pkg_mgr = self.analysis.get("package_manager", "npm")
        if "dev" in scripts:
-            self.analysis["dev_command"] = "npm run dev"
+            self.analysis["dev_command"] = f"{pkg_mgr} run dev"
        elif "start" in scripts:
-            self.analysis["dev_command"] = "npm run start"
+            self.analysis["dev_command"] = f"{pkg_mgr} run start"
+
+        # Capture available scripts for downstream consumers (QA agents, init.sh)
+        if scripts:
+            self.analysis["scripts"] = dict(scripts)

    def _detect_go_framework(self, content: str) -> None:
        """Detect Go framework."""
@@ -1,690 +0,0 @@
-#!/usr/bin/env python3
-"""
-Test Discovery Module
-=====================
-
-Detects test frameworks, test commands, and test directories in a project.
-This module analyzes project configuration files to discover how tests
-should be run.
-
-The test discovery results are used by:
- QA Agent: To determine what test commands to run
- Test Creator: To know what framework to use when creating tests
- Planner: To include correct test commands in verification strategy
-
-Usage:
-    from test_discovery import TestDiscovery
-
-    discovery = TestDiscovery()
-    result = discovery.discover(project_dir)
-
-    print(f"Test frameworks: {result['frameworks']}")
-    print(f"Test command: {result['test_command']}")
-"""
-
-from __future__ import annotations
-
-import json
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any
-
-# =============================================================================
-# DATA CLASSES
-# =============================================================================
-
-
-@dataclass
-class TestFramework:
-    """
-    Represents a detected test framework.
-
-    Attributes:
-        name: Name of the framework (e.g., "pytest", "jest", "vitest")
-        type: Type of testing (unit, integration, e2e, all)
-        command: Command to run tests
-        config_file: Configuration file if found
-        version: Version if detected
-        coverage_command: Command for coverage if available
-    """
-
-    __test__ = False  # Prevent pytest from collecting this as a test class
-
-    name: str
-    type: str  # unit, integration, e2e, all
-    command: str
-    config_file: str | None = None
-    version: str | None = None
-    coverage_command: str | None = None
-
-
-@dataclass
-class TestDiscoveryResult:
-    """
-    Result of test framework discovery.
-
-    Attributes:
-        frameworks: List of detected test frameworks
-        test_command: Primary test command to run
-        test_directories: Discovered test directories
-        package_manager: Detected package manager
-        has_tests: Whether any test files were found
-        coverage_command: Command for coverage if available
-    """
-
-    __test__ = False  # Prevent pytest from collecting this as a test class
-
-    frameworks: list[TestFramework] = field(default_factory=list)
-    test_command: str = ""
-    test_directories: list[str] = field(default_factory=list)
-    package_manager: str = ""
-    has_tests: bool = False
-    coverage_command: str | None = None
-
-
-# =============================================================================
-# FRAMEWORK DETECTORS
-# =============================================================================
-
-
-# Pattern-based framework detection
-FRAMEWORK_PATTERNS = {
-    # JavaScript/TypeScript
-    "jest": {
-        "config_files": [
-            "jest.config.js",
-            "jest.config.ts",
-            "jest.config.mjs",
-            "jest.config.cjs",
-        ],
-        "package_key": "jest",
-        "type": "unit",
-        "command": "npx jest",
-        "coverage_command": "npx jest --coverage",
-    },
-    "vitest": {
-        "config_files": ["vitest.config.js", "vitest.config.ts", "vitest.config.mjs"],
-        "package_key": "vitest",
-        "type": "unit",
-        "command": "npx vitest run",
-        "coverage_command": "npx vitest run --coverage",
-    },
-    "mocha": {
-        "config_files": [
-            ".mocharc.js",
-            ".mocharc.json",
-            ".mocharc.yaml",
-            ".mocharc.yml",
-        ],
-        "package_key": "mocha",
-        "type": "unit",
-        "command": "npx mocha",
-        "coverage_command": "npx nyc mocha",
-    },
-    "playwright": {
-        "config_files": ["playwright.config.js", "playwright.config.ts"],
-        "package_key": "@playwright/test",
-        "type": "e2e",
-        "command": "npx playwright test",
-        "coverage_command": None,
-    },
-    "cypress": {
-        "config_files": ["cypress.config.js", "cypress.config.ts", "cypress.json"],
-        "package_key": "cypress",
-        "type": "e2e",
-        "command": "npx cypress run",
-        "coverage_command": None,
-    },
-    # Python
-    "pytest": {
-        "config_files": ["pytest.ini", "pyproject.toml", "setup.cfg", "conftest.py"],
-        "pyproject_key": "pytest",
-        "requirements_key": "pytest",
-        "type": "all",
-        "command": "pytest",
-        "coverage_command": "pytest --cov",
-    },
-    "unittest": {
-        "config_files": [],
-        "type": "unit",
-        "command": "python -m unittest discover",
-        "coverage_command": "coverage run -m unittest discover",
-    },
-    # Rust
-    "cargo_test": {
-        "config_files": ["Cargo.toml"],
-        "type": "all",
-        "command": "cargo test",
-        "coverage_command": "cargo tarpaulin",
-    },
-    # Go
-    "go_test": {
-        "config_files": ["go.mod"],
-        "type": "all",
-        "command": "go test ./...",
-        "coverage_command": "go test -cover ./...",
-    },
-    # Ruby
-    "rspec": {
-        "config_files": [".rspec", "spec/spec_helper.rb"],
-        "gemfile_key": "rspec",
-        "type": "all",
-        "command": "bundle exec rspec",
-        "coverage_command": "bundle exec rspec --format documentation",
-    },
-    "minitest": {
-        "config_files": [],
-        "gemfile_key": "minitest",
-        "type": "unit",
-        "command": "bundle exec rake test",
-        "coverage_command": None,
-    },
-}
-
-
-# =============================================================================
-# TEST DISCOVERY
-# =============================================================================
-
-
-class TestDiscovery:
-    """
-    Discovers test frameworks and configurations in a project.
-
-    Analyzes:
-    - Package files (package.json, pyproject.toml, Cargo.toml, etc.)
-    - Configuration files (jest.config.js, pytest.ini, etc.)
-    - Directory structure (tests/, spec/, __tests__/)
-    """
-
-    __test__ = False  # Prevent pytest from collecting this as a test class
-
-    def __init__(self) -> None:
-        """Initialize the test discovery."""
-        self._cache: dict[str, TestDiscoveryResult] = {}
-
-    def discover(self, project_dir: Path) -> TestDiscoveryResult:
-        """
-        Discover test frameworks and configuration in the project.
-
-        Args:
-            project_dir: Path to the project root
-
-        Returns:
-            TestDiscoveryResult with detected frameworks and commands
-        """
-        project_dir = Path(project_dir)
-        cache_key = str(project_dir.resolve())
-
-        if cache_key in self._cache:
-            return self._cache[cache_key]
-
-        result = TestDiscoveryResult()
-
-        # Detect package manager
-        result.package_manager = self._detect_package_manager(project_dir)
-
-        # Discover frameworks based on project type
-        if (project_dir / "package.json").exists():
-            self._discover_js_frameworks(project_dir, result)
-
-        # Check for Python project indicators
-        python_indicators = [
-            project_dir / "pyproject.toml",
-            project_dir / "requirements.txt",
-            project_dir / "setup.py",
-            project_dir / "pytest.ini",
-            project_dir / "conftest.py",
-            project_dir / "tests" / "conftest.py",
-        ]
-        if any(p.exists() for p in python_indicators):
-            self._discover_python_frameworks(project_dir, result)
-
-        if (project_dir / "Cargo.toml").exists():
-            self._discover_rust_frameworks(project_dir, result)
-        if (project_dir / "go.mod").exists():
-            self._discover_go_frameworks(project_dir, result)
-        if (project_dir / "Gemfile").exists():
-            self._discover_ruby_frameworks(project_dir, result)
-
-        # Find test directories
-        result.test_directories = self._find_test_directories(project_dir)
-
-        # Check if tests exist
-        result.has_tests = self._has_test_files(project_dir, result.test_directories)
-
-        # Set primary test command
-        if result.frameworks:
-            result.test_command = result.frameworks[0].command
-
-        # Set coverage command from first framework that has one
-        if not result.coverage_command:
-            for framework in result.frameworks:
-                if framework.coverage_command:
-                    result.coverage_command = framework.coverage_command
-                    break
-
-        self._cache[cache_key] = result
-        return result
-
-    def _detect_package_manager(self, project_dir: Path) -> str:
-        """Detect the package manager used by the project."""
-        if (project_dir / "pnpm-lock.yaml").exists():
-            return "pnpm"
-        if (project_dir / "yarn.lock").exists():
-            return "yarn"
-        if (project_dir / "package-lock.json").exists():
-            return "npm"
-        if (project_dir / "bun.lockb").exists() or (project_dir / "bun.lock").exists():
-            return "bun"
-        if (project_dir / "uv.lock").exists():
-            return "uv"
-        if (project_dir / "poetry.lock").exists():
-            return "poetry"
-        if (project_dir / "Pipfile.lock").exists():
-            return "pipenv"
-        if (project_dir / "Cargo.lock").exists():
-            return "cargo"
-        if (project_dir / "go.sum").exists():
-            return "go"
-        if (project_dir / "Gemfile.lock").exists():
-            return "bundler"
-        return ""
-
-    def _discover_js_frameworks(
-        self, project_dir: Path, result: TestDiscoveryResult
-    ) -> None:
-        """Discover JavaScript/TypeScript test frameworks."""
-        package_json = project_dir / "package.json"
-        if not package_json.exists():
-            return
-
-        try:
-            with open(package_json, encoding="utf-8") as f:
-                pkg = json.load(f)
-        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
-            return
-
-        deps = pkg.get("dependencies", {})
-        dev_deps = pkg.get("devDependencies", {})
-        all_deps = {**deps, **dev_deps}
-        scripts = pkg.get("scripts", {})
-
-        # Check for test frameworks in dependencies
-        for name, pattern in FRAMEWORK_PATTERNS.items():
-            if "package_key" not in pattern:
-                continue
-
-            if pattern["package_key"] in all_deps:
-                # Check for config file
-                config_file = None
-                for cf in pattern.get("config_files", []):
-                    if (project_dir / cf).exists():
-                        config_file = cf
-                        break
-
-                # Get version
-                version = all_deps.get(pattern["package_key"], "")
-                if version.startswith("^") or version.startswith("~"):
-                    version = version[1:]
-
-                # Determine command - prefer npm scripts if available
-                command = pattern["command"]
-                if "test" in scripts and pattern["package_key"] in scripts.get(
-                    "test", ""
-                ):
-                    command = f"{result.package_manager or 'npm'} test"
-
-                result.frameworks.append(
-                    TestFramework(
-                        name=name,
-                        type=pattern["type"],
-                        command=command,
-                        config_file=config_file,
-                        version=version,
-                        coverage_command=pattern.get("coverage_command"),
-                    )
-                )
-
-        # Check npm scripts for test commands
-        if not result.frameworks and "test" in scripts:
-            test_script = scripts["test"]
-            if (
-                test_script
-                and test_script != 'echo "Error: no test specified" && exit 1'
-            ):
-                # Try to infer framework from script
-                framework_name = "npm_test"
-                framework_type = "unit"
-
-                if "jest" in test_script:
-                    framework_name = "jest"
-                elif "vitest" in test_script:
-                    framework_name = "vitest"
-                elif "mocha" in test_script:
-                    framework_name = "mocha"
-                elif "playwright" in test_script:
-                    framework_name = "playwright"
-                    framework_type = "e2e"
-                elif "cypress" in test_script:
-                    framework_name = "cypress"
-                    framework_type = "e2e"
-
-                result.frameworks.append(
-                    TestFramework(
-                        name=framework_name,
-                        type=framework_type,
-                        command=f"{result.package_manager or 'npm'} test",
-                        config_file=None,
-                    )
-                )
-
-    def _discover_python_frameworks(
-        self, project_dir: Path, result: TestDiscoveryResult
-    ) -> None:
-        """Discover Python test frameworks."""
-        # Check for pytest.ini first (explicit pytest config)
-        if (project_dir / "pytest.ini").exists():
-            if not any(f.name == "pytest" for f in result.frameworks):
-                result.frameworks.append(
-                    TestFramework(
-                        name="pytest",
-                        type="all",
-                        command="pytest",
-                        config_file="pytest.ini",
-                    )
-                )
-
-        # Check pyproject.toml
-        pyproject = project_dir / "pyproject.toml"
-        if pyproject.exists():
-            content = pyproject.read_text(encoding="utf-8")
-
-            # Check for pytest
-            if "pytest" in content:
-                if not any(f.name == "pytest" for f in result.frameworks):
-                    config_file = (
-                        "pyproject.toml" if "[tool.pytest" in content else None
-                    )
-                    result.frameworks.append(
-                        TestFramework(
-                            name="pytest",
-                            type="all",
-                            command="pytest",
-                            config_file=config_file,
-                        )
-                    )
-
-        # Check requirements.txt
-        requirements = project_dir / "requirements.txt"
-        if requirements.exists():
-            content = requirements.read_text(encoding="utf-8").lower()
-            if "pytest" in content and not any(
-                f.name == "pytest" for f in result.frameworks
-            ):
-                result.frameworks.append(
-                    TestFramework(
-                        name="pytest",
-                        type="all",
-                        command="pytest",
-                        config_file=None,
-                    )
-                )
-
-        # Check for conftest.py (pytest marker)
-        conftest_root = project_dir / "conftest.py"
-        conftest_tests = project_dir / "tests" / "conftest.py"
-        if conftest_root.exists() or conftest_tests.exists():
-            if not any(f.name == "pytest" for f in result.frameworks):
-                result.frameworks.append(
-                    TestFramework(
-                        name="pytest",
-                        type="all",
-                        command="pytest",
-                        config_file="conftest.py",
-                    )
-                )
-
-        # Fall back to unittest if test files exist but no framework detected
-        if not result.frameworks:
-            test_dirs = self._find_test_directories(project_dir)
-            if test_dirs:
-                result.frameworks.append(
-                    TestFramework(
-                        name="unittest",
-                        type="unit",
-                        command="python -m unittest discover",
-                        config_file=None,
-                    )
-                )
-
-    def _discover_rust_frameworks(
-        self, project_dir: Path, result: TestDiscoveryResult
-    ) -> None:
-        """Discover Rust test frameworks."""
-        cargo_toml = project_dir / "Cargo.toml"
-        if cargo_toml.exists():
-            result.frameworks.append(
-                TestFramework(
-                    name="cargo_test",
-                    type="all",
-                    command="cargo test",
-                    config_file="Cargo.toml",
-                )
-            )
-
-    def _discover_go_frameworks(
-        self, project_dir: Path, result: TestDiscoveryResult
-    ) -> None:
-        """Discover Go test frameworks."""
-        go_mod = project_dir / "go.mod"
-        if go_mod.exists():
-            result.frameworks.append(
-                TestFramework(
-                    name="go_test",
-                    type="all",
-                    command="go test ./...",
-                    config_file="go.mod",
-                )
-            )
-
-    def _discover_ruby_frameworks(
-        self, project_dir: Path, result: TestDiscoveryResult
-    ) -> None:
-        """Discover Ruby test frameworks."""
-        gemfile = project_dir / "Gemfile"
-        if not gemfile.exists():
-            return
-
-        content = gemfile.read_text(encoding="utf-8").lower()
-
-        if "rspec" in content or (project_dir / ".rspec").exists():
-            result.frameworks.append(
-                TestFramework(
-                    name="rspec",
-                    type="all",
-                    command="bundle exec rspec",
-                    config_file=".rspec" if (project_dir / ".rspec").exists() else None,
-                )
-            )
-        elif "minitest" in content:
-            result.frameworks.append(
-                TestFramework(
-                    name="minitest",
-                    type="unit",
-                    command="bundle exec rake test",
-                    config_file=None,
-                )
-            )
-
-    def _find_test_directories(self, project_dir: Path) -> list[str]:
-        """Find test directories in the project."""
-        test_dir_patterns = [
-            "tests",
-            "test",
-            "spec",
-            "__tests__",
-            "specs",
-            "test_*",
-        ]
-
-        found_dirs = []
-        for pattern in test_dir_patterns:
-            if pattern.endswith("*"):
-                # Glob pattern
-                for d in project_dir.glob(pattern):
-                    if d.is_dir():
-                        found_dirs.append(str(d.relative_to(project_dir)))
-            else:
-                # Exact name
-                test_dir = project_dir / pattern
-                if test_dir.is_dir():
-                    found_dirs.append(pattern)
-
-        return found_dirs
-
-    def _has_test_files(self, project_dir: Path, test_directories: list[str]) -> bool:
-        """Check if any test files exist."""
-        test_file_patterns = [
-            "**/test_*.py",
-            "**/*_test.py",
-            "**/*.test.js",
-            "**/*.test.ts",
-            "**/*.test.tsx",
-            "**/*.spec.js",
-            "**/*.spec.ts",
-            "**/*.spec.tsx",
-            "**/test_*.go",
-            "**/*_test.go",
-            "**/*_test.rs",
-            "**/spec/**/*_spec.rb",
-        ]
-
-        # Check in test directories
-        for test_dir in test_directories:
-            test_path = project_dir / test_dir
-            if test_path.exists():
-                for pattern in test_file_patterns:
-                    if list(test_path.glob(pattern.replace("**/", ""))):
-                        return True
-
-        # Check project-wide
-        for pattern in test_file_patterns:
-            if list(project_dir.glob(pattern)):
-                return True
-
-        return False
-
-    def to_dict(self, result: TestDiscoveryResult) -> dict[str, Any]:
-        """Convert result to dictionary for JSON serialization."""
-        return {
-            "frameworks": [
-                {
-                    "name": f.name,
-                    "type": f.type,
-                    "command": f.command,
-                    "config_file": f.config_file,
-                    "version": f.version,
-                    "coverage_command": f.coverage_command,
-                }
-                for f in result.frameworks
-            ],
-            "test_command": result.test_command,
-            "test_directories": result.test_directories,
-            "package_manager": result.package_manager,
-            "has_tests": result.has_tests,
-            "coverage_command": result.coverage_command,
-        }
-
-    def clear_cache(self) -> None:
-        """Clear the internal cache."""
-        self._cache.clear()
-
-
-# =============================================================================
-# CONVENIENCE FUNCTIONS
-# =============================================================================
-
-
-def discover_tests(project_dir: Path) -> TestDiscoveryResult:
-    """
-    Convenience function to discover tests in a project.
-
-    Args:
-        project_dir: Path to project root
-
-    Returns:
-        TestDiscoveryResult with detected frameworks
-    """
-    discovery = TestDiscovery()
-    return discovery.discover(project_dir)
-
-
-def get_test_command(project_dir: Path) -> str:
-    """
-    Get the primary test command for a project.
-
-    Args:
-        project_dir: Path to project root
-
-    Returns:
-        Test command string, or empty string if not found
-    """
-    discovery = TestDiscovery()
-    result = discovery.discover(project_dir)
-    return result.test_command
-
-
-def get_test_frameworks(project_dir: Path) -> list[str]:
-    """
-    Get list of test framework names in a project.
-
-    Args:
-        project_dir: Path to project root
-
-    Returns:
-        List of framework names
-    """
-    discovery = TestDiscovery()
-    result = discovery.discover(project_dir)
-    return [f.name for f in result.frameworks]
-
-
-# =============================================================================
-# CLI
-# =============================================================================
-
-
-def main() -> None:
-    """CLI entry point for testing."""
-    import argparse
-
-    parser = argparse.ArgumentParser(description="Discover test frameworks")
-    parser.add_argument("project_dir", type=Path, help="Path to project root")
-    parser.add_argument("--json", action="store_true", help="Output as JSON")
-
-    args = parser.parse_args()
-
-    discovery = TestDiscovery()
-    result = discovery.discover(args.project_dir)
-
-    if args.json:
-        print(json.dumps(discovery.to_dict(result), indent=2))
-    else:
-        print(f"Package Manager: {result.package_manager or 'unknown'}")
-        print(f"Has Tests: {result.has_tests}")
-        print(f"Test Command: {result.test_command or 'none'}")
-        print(f"Test Directories: {', '.join(result.test_directories) or 'none'}")
-        print(f"Coverage Command: {result.coverage_command or 'none'}")
-        print(f"\nFrameworks ({len(result.frameworks)}):")
-        for f in result.frameworks:
-            print(f"  - {f.name} ({f.type})")
-            print(f"    Command: {f.command}")
-            if f.config_file:
-                print(f"    Config: {f.config_file}")
-            if f.version:
-                print(f"    Version: {f.version}")
-
-
-if __name__ == "__main__":
-    main()
@@ -10,6 +10,7 @@ import shutil
 import subprocess
 from pathlib import Path

+from qa.criteria import is_fixes_applied, is_qa_approved, is_qa_rejected
 from ui import highlight, print_status


@@ -151,13 +152,22 @@ def handle_batch_status_command(project_dir: str) -> bool:
            except json.JSONDecodeError:
                pass

-        # Determine status
-        if (spec_dir / "spec.md").exists():
-            status = "spec_created"
-        elif (spec_dir / "implementation_plan.json").exists():
-            status = "building"
-        elif (spec_dir / "qa_report.md").exists():
+        # Determine status (highest priority first)
+        # Use authoritative QA status check, not just file existence
+        if is_qa_approved(spec_dir):
            status = "qa_approved"
+        elif is_qa_rejected(spec_dir):
+            status = "qa_rejected"
+        elif is_fixes_applied(spec_dir):
+            status = "fixes_applied"
+        elif (spec_dir / "implementation_plan.json").exists():
+            # Check if there's a qa_report.md but no approval yet (QA in progress)
+            if (spec_dir / "qa_report.md").exists():
+                status = "qa_in_progress"
+            else:
+                status = "building"
+        elif (spec_dir / "spec.md").exists():
+            status = "spec_created"
        else:
            status = "pending_spec"

@@ -165,7 +175,10 @@ def handle_batch_status_command(project_dir: str) -> bool:
            "pending_spec": "⏳",
            "spec_created": "📋",
            "building": "⚙️",
+            "qa_in_progress": "🔍",
            "qa_approved": "✅",
+            "qa_rejected": "❌",
+            "fixes_applied": "🔧",
            "unknown": "❓",
        }.get(status, "❓")

@@ -192,10 +205,10 @@ def handle_batch_cleanup_command(project_dir: str, dry_run: bool = True) -> bool
        print_status("No specs directory found", "info")
        return True

-    # Find completed specs
+    # Find completed specs (only QA-approved, matching status display logic)
    completed = []
    for spec_dir in specs_dir.iterdir():
-        if spec_dir.is_dir() and (spec_dir / "qa_report.md").exists():
+        if spec_dir.is_dir() and is_qa_approved(spec_dir):
            completed.append(spec_dir.name)

    if not completed:
@@ -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:
@@ -442,7 +449,7 @@ def _handle_build_interrupt(
        if choice == "skip":
            print()
            print_status("Resuming build...", "info")
-            status_manager.update(state=BuildState.RUNNING)
+            status_manager.update(state=BuildState.BUILDING)
            asyncio.run(
                run_autonomous_agent(
                    project_dir=working_dir,
@@ -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
@@ -6,6 +6,7 @@ for multiple environment variables, and SDK environment variable passthrough
 for custom API endpoints.
 """

+import hashlib
 import json
 import logging
 import os
@@ -14,6 +15,7 @@ import subprocess
 from typing import TYPE_CHECKING

 from core.platform import (
+    get_where_exe_path,
    is_linux,
    is_macos,
    is_windows,
@@ -65,6 +67,48 @@ SDK_ENV_VARS = [
 ]


+def _calculate_config_dir_hash(config_dir: str) -> str:
+    """
+    Calculate hash of config directory path for Keychain service name.
+
+    This MUST match the frontend's calculateConfigDirHash() in credential-utils.ts.
+    The frontend uses SHA256 hash of the config dir path, taking first 8 hex chars.
+
+    Args:
+        config_dir: Path to the config directory (should be absolute/expanded)
+
+    Returns:
+        8-character hex hash string (e.g., "d74c9506")
+    """
+    return hashlib.sha256(config_dir.encode()).hexdigest()[:8]
+
+
+def _get_keychain_service_name(config_dir: str | None = None) -> str:
+    """
+    Get the Keychain service name for credential storage.
+
+    This MUST match the frontend's getKeychainServiceName() in credential-utils.ts.
+    All profiles use hash-based keychain entries for isolation:
+    - Profile with configDir: "Claude Code-credentials-{hash}"
+    - No configDir (legacy/default): "Claude Code-credentials"
+
+    Args:
+        config_dir: Optional CLAUDE_CONFIG_DIR path. If provided, uses hash-based name.
+
+    Returns:
+        Keychain service name (e.g., "Claude Code-credentials-d74c9506")
+    """
+    if not config_dir:
+        return "Claude Code-credentials"
+
+    # Expand ~ to home directory (matching frontend normalization)
+    expanded_dir = os.path.expanduser(config_dir)
+
+    # Calculate hash and return hash-based service name
+    hash_suffix = _calculate_config_dir_hash(expanded_dir)
+    return f"Claude Code-credentials-{hash_suffix}"
+
+
 def is_encrypted_token(token: str | None) -> bool:
    """
    Check if a token is encrypted (has "enc:" prefix).
@@ -346,36 +390,50 @@ def _try_decrypt_token(token: str | None) -> str | None:
    return token


-def get_token_from_keychain() -> str | None:
+def get_token_from_keychain(config_dir: str | None = None) -> str | None:
    """
    Get authentication token from system credential store.

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

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


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

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

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

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

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

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


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

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

        return None
@@ -434,7 +531,7 @@ def _get_token_from_windows_credential_files() -> str | None:
        return None


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

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

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

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

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

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

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

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

    except (
@@ -589,13 +704,37 @@ def get_auth_token(config_dir: str | None = None) -> str | None:
    env_config_dir = os.environ.get("CLAUDE_CONFIG_DIR")
    effective_config_dir = config_dir or env_config_dir

-    # If a custom config directory is specified, read from there
+    # Debug: Log which config_dir is being used for credential resolution
+    debug = os.environ.get("DEBUG", "").lower() in ("true", "1")
+    if debug and effective_config_dir:
+        service_name = _get_keychain_service_name(effective_config_dir)
+        logger.info(
+            f"[Auth] Resolving credentials for profile config_dir: {effective_config_dir} "
+            f"(Keychain service: {service_name})"
+        )
+
+    # If a custom config directory is specified, read from there first
    if effective_config_dir:
+        # Try reading from .credentials.json file in the config directory
        token = _get_token_from_config_dir(effective_config_dir)
        if token:
            return _try_decrypt_token(token)

-    # Fallback to system credential store (default locations)
+        # Also try the system credential store with hash-based service name
+        # This is needed because macOS stores credentials in Keychain, not files
+        token = get_token_from_keychain(effective_config_dir)
+        if token:
+            return _try_decrypt_token(token)
+
+        # If config_dir was explicitly provided, DON'T fall back to default keychain
+        # - that would return the wrong profile's token
+        logger.debug(
+            f"No credentials found for config_dir '{effective_config_dir}' "
+            "in file or keychain"
+        )
+        return None
+
+    # No config_dir specified - use default system credential store
    return _try_decrypt_token(get_token_from_keychain())


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

-    # Check if token came from system credential store
+    # Check if token came from default system credential store
    if get_token_from_keychain():
        if is_macos():
            return "macOS Keychain"
@@ -706,9 +855,9 @@ def _find_git_bash_path() -> str | None:

    # Method 1: Use 'where' command to find git.exe
    try:
-        # Use where.exe explicitly for reliability
+        # Use full path to where.exe for reliability (works even when System32 isn't in PATH)
        result = subprocess.run(
-            ["where.exe", "git"],
+            [get_where_exe_path(), "git"],
            capture_output=True,
            text=True,
            timeout=5,
@@ -800,6 +949,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).
@@ -21,6 +21,7 @@ import time
 from pathlib import Path
 from typing import Any

+from core.fast_mode import ensure_fast_mode_in_user_settings
 from core.platform import (
    is_windows,
    validate_cli_path,
@@ -139,9 +140,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
@@ -450,6 +450,9 @@ def create_client(
    max_thinking_tokens: int | None = None,
    output_format: dict | None = None,
    agents: dict | None = None,
+    betas: list[str] | None = None,
+    effort_level: str | None = None,
+    fast_mode: bool = False,
 ) -> ClaudeSDKClient:
    """
    Create a Claude Agent SDK client with multi-layered security.
@@ -465,10 +468,9 @@ def create_client(
        agent_type: Agent type identifier from AGENT_CONFIGS
                   (e.g., 'coder', 'planner', 'qa_reviewer', 'spec_gatherer')
        max_thinking_tokens: Token budget for extended thinking (None = disabled)
-                            - ultrathink: 16000 (spec creation)
-                            - high: 10000 (QA review)
-                            - medium: 5000 (planning, validation)
-                            - None: disabled (coding)
+                            - high: 16384 (spec creation, QA review)
+                            - medium: 4096 (planning, validation)
+                            - low: 1024 (coding)
        output_format: Optional structured output format for validated JSON responses.
                      Use {"type": "json_schema", "schema": Model.model_json_schema()}
                      See: https://platform.claude.com/docs/en/agent-sdk/structured-outputs
@@ -476,6 +478,16 @@ def create_client(
               Format: {"agent-name": {"description": "...", "prompt": "...",
                        "tools": [...], "model": "inherit"}}
               See: https://platform.claude.com/docs/en/agent-sdk/subagents
+        betas: Optional list of SDK beta header strings (e.g., ["context-1m-2025-08-07"]
+               for 1M context window). Use get_phase_model_betas() to compute from config.
+        effort_level: Optional effort level for adaptive thinking models (e.g., "low",
+                     "medium", "high"). When set, injected as CLAUDE_CODE_EFFORT_LEVEL
+                     env var for the SDK subprocess. Only meaningful for models that
+                     support adaptive thinking (e.g., Opus 4.6).
+        fast_mode: Enable Fast Mode for faster Opus 4.6 output. When True, enables
+                  the "user" setting source so the CLI reads fastMode from
+                  ~/.claude/settings.json. Requires extra usage enabled on Claude
+                  subscription; falls back to standard speed automatically.

    Returns:
        Configured ClaudeSDKClient
@@ -490,20 +502,37 @@ def create_client(
       (see security.py for ALLOWED_COMMANDS)
    4. Tool filtering - Each agent type only sees relevant tools (prevents misuse)
    """
-    # Get OAuth token - Claude CLI handles token lifecycle internally
-    oauth_token = require_auth_token()
-
-    # Validate token is not encrypted before passing to SDK
-    # Encrypted tokens (enc:...) should have been decrypted by require_auth_token()
-    # If we still have an encrypted token here, it means decryption failed or was skipped
-    validate_token_not_encrypted(oauth_token)
-
-    # Ensure SDK can access it via its expected env var
-    os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = oauth_token
-
-    # Collect env vars to pass to SDK (ANTHROPIC_BASE_URL, etc.)
+    # Collect env vars to pass to SDK (ANTHROPIC_BASE_URL, CLAUDE_CONFIG_DIR, etc.)
    sdk_env = get_sdk_env_vars()

+    # Get the config dir for profile-specific credential lookup
+    # CLAUDE_CONFIG_DIR enables per-profile Keychain entries with SHA256-hashed service names
+    config_dir = sdk_env.get("CLAUDE_CONFIG_DIR")
+
+    # Configure SDK authentication (OAuth or API profile mode)
+    configure_sdk_authentication(config_dir)
+
+    if config_dir:
+        logger.info(f"Using CLAUDE_CONFIG_DIR for profile: {config_dir}")
+
+    # Inject effort level for adaptive thinking models (e.g., Opus 4.6)
+    if effort_level:
+        sdk_env["CLAUDE_CODE_EFFORT_LEVEL"] = effort_level
+
+    # Fast mode requires the CLI to read "fastMode" from user settings.
+    # The SDK default (setting_sources=None) passes --setting-sources "" which
+    # blocks ALL filesystem settings. We must explicitly enable "user" source
+    # so the CLI reads ~/.claude/settings.json where fastMode: true lives.
+    # See: https://code.claude.com/docs/en/fast-mode
+    if fast_mode:
+        ensure_fast_mode_in_user_settings()
+        logger.info("[Fast Mode] ACTIVE — will enable user setting source for fastMode")
+        print(
+            "[Fast Mode] ACTIVE — enabling user settings source for CLI to read fastMode"
+        )
+    else:
+        logger.info("[Fast Mode] inactive — not requested for this client")
+
    # 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']}")
@@ -667,7 +696,12 @@ def create_client(
        print("   - Worktree permissions: granted for original project directories")
    print("   - Bash commands restricted to allowlist")
    if max_thinking_tokens:
-        print(f"   - Extended thinking: {max_thinking_tokens:,} tokens")
+        thinking_info = f"{max_thinking_tokens:,} tokens"
+        if effort_level:
+            thinking_info += f" + effort={effort_level}"
+        if fast_mode:
+            thinking_info += " + fast mode"
+        print(f"   - Extended thinking: {thinking_info}")
    else:
        print("   - Extended thinking: disabled")

@@ -819,6 +853,12 @@ def create_client(
        "enable_file_checkpointing": True,
    }

+    # Fast mode: enable user setting source so CLI reads fastMode from
+    # ~/.claude/settings.json. Without this, the SDK's default --setting-sources ""
+    # blocks all filesystem settings and the CLI never sees fastMode: true.
+    if fast_mode:
+        options_kwargs["setting_sources"] = ["user"]
+
    # 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")
@@ -836,4 +876,8 @@ def create_client(
    if agents:
        options_kwargs["agents"] = agents

+    # Add beta headers if specified (e.g., for 1M context window)
+    if betas:
+        options_kwargs["betas"] = betas
+
    return ClaudeSDKClient(options=ClaudeAgentOptions(**options_kwargs))
@@ -0,0 +1,120 @@
+"""
+Shared Error Utilities
+======================
+
+Common error detection and classification functions used across
+agent sessions, QA, and other modules.
+"""
+
+import re
+
+
+def is_tool_concurrency_error(error: Exception) -> bool:
+    """
+    Check if an error is a 400 tool concurrency error from Claude API.
+
+    Tool concurrency errors occur when too many tools are used simultaneously
+    in a single API request, hitting Claude's concurrent tool use limit.
+
+    Args:
+        error: The exception to check
+
+    Returns:
+        True if this is a tool concurrency error, False otherwise
+    """
+    error_str = str(error).lower()
+    # Check for 400 status AND tool concurrency keywords
+    return "400" in error_str and (
+        ("tool" in error_str and "concurrency" in error_str)
+        or "too many tools" in error_str
+        or "concurrent tool" in error_str
+    )
+
+
+def is_rate_limit_error(error: Exception) -> bool:
+    """
+    Check if an error is a rate limit error (429 or similar).
+
+    Rate limit errors occur when the API usage quota is exceeded,
+    either for session limits or weekly limits.
+
+    Args:
+        error: The exception to check
+
+    Returns:
+        True if this is a rate limit error, False otherwise
+    """
+    error_str = str(error).lower()
+
+    # Check for HTTP 429 with word boundaries to avoid false positives
+    if re.search(r"\b429\b", error_str):
+        return True
+
+    # Check for other rate limit indicators
+    return any(
+        p in error_str
+        for p in [
+            "limit reached",
+            "rate limit",
+            "too many requests",
+            "usage limit",
+            "quota exceeded",
+        ]
+    )
+
+
+def is_authentication_error(error: Exception) -> bool:
+    """
+    Check if an error is an authentication error (401, token expired, etc.).
+
+    Authentication errors occur when OAuth tokens are invalid, expired,
+    or have been revoked (e.g., after token refresh on another process).
+
+    Validation approach:
+    - HTTP 401 status code is checked with word boundaries to minimize false positives
+    - Additional string patterns are validated against lowercase error messages
+    - Patterns are designed to match known Claude API and OAuth error formats
+
+    Known false positive risks:
+    - Generic error messages containing "unauthorized" or "access denied" may match
+      even if not related to authentication (e.g., file permission errors)
+    - Error messages containing these keywords in user-provided content could match
+    - Mitigation: HTTP 401 check provides strong signal; string patterns are secondary
+
+    Real-world validation:
+    - Pattern matching has been tested against actual Claude API error responses
+    - False positive rate is acceptable given the recovery mechanism (prompt user to re-auth)
+    - If false positive occurs, user can simply resume without re-authenticating
+
+    Args:
+        error: The exception to check
+
+    Returns:
+        True if this is an authentication error, False otherwise
+    """
+    error_str = str(error).lower()
+
+    # Check for HTTP 401 with word boundaries to avoid false positives
+    if re.search(r"\b401\b", error_str):
+        return True
+
+    # Check for other authentication indicators
+    # NOTE: "authentication failed" and "authentication error" are more specific patterns
+    # to reduce false positives from generic "authentication" mentions
+    return any(
+        p in error_str
+        for p in [
+            "authentication failed",
+            "authentication error",
+            "unauthorized",
+            "invalid token",
+            "token expired",
+            "authentication_error",
+            "invalid_token",
+            "token_expired",
+            "not authenticated",
+            "http 401",
+            "does not have access to claude",
+            "please login again",
+        ]
+    )
@@ -0,0 +1,76 @@
+"""
+Fast Mode Settings Helper
+=========================
+
+Manages the fastMode flag in ~/.claude/settings.json for temporary
+per-task fast mode overrides. Shared by both client.py and simple_client.py.
+"""
+
+import json
+import logging
+from pathlib import Path
+
+from core.file_utils import write_json_atomic
+
+logger = logging.getLogger(__name__)
+
+_fast_mode_atexit_registered = False
+
+
+def _write_fast_mode_setting(enabled: bool) -> None:
+    """Write fastMode value to ~/.claude/settings.json (atomic read-modify-write).
+
+    Uses write_json_atomic from core.file_utils to prevent corruption when
+    multiple concurrent task processes modify the file simultaneously.
+    """
+    settings_file = Path.home() / ".claude" / "settings.json"
+    try:
+        settings: dict = {}
+        if settings_file.exists():
+            settings = json.loads(settings_file.read_text(encoding="utf-8"))
+
+        if settings.get("fastMode") != enabled:
+            settings["fastMode"] = enabled
+            settings_file.parent.mkdir(parents=True, exist_ok=True)
+            # Atomic write using shared utility
+            write_json_atomic(settings_file, settings)
+            state = "true" if enabled else "false"
+            logger.info(
+                f"[Fast Mode] Wrote fastMode={state} to ~/.claude/settings.json"
+            )
+    except Exception as e:
+        logger.warning(f"[Fast Mode] Could not update ~/.claude/settings.json: {e}")
+
+
+def _disable_fast_mode_on_exit() -> None:
+    """atexit handler: restore fastMode=false so interactive CLI sessions stay standard."""
+    _write_fast_mode_setting(False)
+
+
+def ensure_fast_mode_in_user_settings() -> None:
+    """
+    Enable fastMode in ~/.claude/settings.json and register cleanup.
+
+    The CLI reads fastMode from user settings (loaded via --setting-sources user).
+    This function:
+    1. Writes fastMode=true before spawning the CLI subprocess
+    2. Registers an atexit handler to restore fastMode=false when the process exits
+
+    This ensures fast mode is a temporary override per task process, not a permanent
+    setting change. The CLI subprocess reads settings at startup, so restoring false
+    after exit doesn't affect running tasks — only prevents fast mode from leaking
+    into subsequent interactive CLI sessions or non-fast-mode tasks.
+    """
+    global _fast_mode_atexit_registered
+
+    _write_fast_mode_setting(True)
+
+    # Register cleanup once per process — idempotent on repeated calls
+    if not _fast_mode_atexit_registered:
+        import atexit
+
+        atexit.register(_disable_fast_mode_on_exit)
+        _fast_mode_atexit_registered = True
+        logger.info(
+            "[Fast Mode] Registered atexit cleanup (will restore fastMode=false)"
+        )
@@ -10,6 +10,8 @@ import os
 import shutil
 import subprocess

+from core.platform import get_where_exe_path
+
 _cached_gh_path: str | None = None


@@ -53,12 +55,11 @@ def _run_where_command() -> str | None:
    """
    try:
        result = subprocess.run(
-            "where gh",
+            [get_where_exe_path(), "gh"],
            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()
@@ -133,7 +134,7 @@ def _find_gh_executable() -> str | None:
            if os.path.isfile(path) and _verify_gh_executable(path):
                return path

-        # 5. Try 'where' command with shell=True (more reliable on Windows)
+        # 5. Try 'where' command with full path (works even when System32 isn't in PATH)
        return _run_where_command()

    return None
@@ -15,6 +15,8 @@ import shutil
 import subprocess
 from pathlib import Path

+from core.platform import get_where_exe_path
+
 # Git environment variables that can interfere with worktree operations
 # when set by pre-commit hooks or other git configurations.
 # These must be cleared to prevent cross-worktree contamination.
@@ -124,14 +126,13 @@ def _find_git_executable() -> str:
            except OSError:
                continue

-        # 4. Try 'where' command with shell=True (more reliable on Windows)
+        # 4. Try 'where' command with full path (works even when System32 isn't in PATH)
        try:
            result = subprocess.run(
-                "where git",
+                [get_where_exe_path(), "git"],
                capture_output=True,
                text=True,
                timeout=5,
-                shell=True,
            )
            if result.returncode == 0 and result.stdout.strip():
                found_path = result.stdout.strip().split("\n")[0].strip()
@@ -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,193 @@
+#!/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
+
+from core.platform import get_where_exe_path
+
+_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(
+            [get_where_exe_path(), "glab"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            timeout=5,
+        )
+        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 full path (works even when System32 isn't in PATH)
+        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:
@@ -430,6 +430,22 @@ def requires_shell(command: str) -> bool:
    return ext.lower() in {".cmd", ".bat", ".ps1"}


+def get_where_exe_path() -> str:
+    """Get full path to where.exe on Windows.
+
+    Using the full path ensures where.exe works even when System32 isn't in PATH,
+    which can happen in restricted environments or when the app doesn't inherit
+    the full system PATH.
+
+    Returns:
+        Full path to where.exe (e.g., C:\\Windows\\System32\\where.exe)
+    """
+    system_root = os.environ.get(
+        "SystemRoot", os.environ.get("SYSTEMROOT", "C:\\Windows")
+    )
+    return os.path.join(system_root, "System32", "where.exe")
+
+
 def get_comspec_path() -> str:
    """
    Get the path to cmd.exe on Windows.
@@ -22,15 +22,16 @@ Example usage:
 """

 import logging
+import os
 from pathlib import Path

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

@@ -44,6 +45,9 @@ def create_simple_client(
    cwd: Path | None = None,
    max_turns: int = 1,
    max_thinking_tokens: int | None = None,
+    betas: list[str] | None = None,
+    effort_level: str | None = None,
+    fast_mode: bool = False,
 ) -> ClaudeSDKClient:
    """
    Create a minimal Claude SDK client for single-turn utility operations.
@@ -65,6 +69,11 @@ def create_simple_client(
        max_turns: Maximum conversation turns (default: 1 for single-turn)
        max_thinking_tokens: Override thinking budget (None = use agent default from
                            AGENT_CONFIGS, converted using phase_config.THINKING_BUDGET_MAP)
+        betas: Optional list of SDK beta header strings (e.g., ["context-1m-2025-08-07"])
+        effort_level: Optional effort level for adaptive thinking models (e.g., "low",
+                     "medium", "high"). Injected as CLAUDE_CODE_EFFORT_LEVEL env var.
+        fast_mode: Enable Fast Mode for faster Opus 4.6 output. Enables the "user"
+                  setting source so the CLI reads fastMode from ~/.claude/settings.json.

    Returns:
        Configured ClaudeSDKClient for single-turn operations
@@ -72,21 +81,27 @@ 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)
+
+    # Inject effort level for adaptive thinking models (e.g., Opus 4.6)
+    if effort_level:
+        sdk_env["CLAUDE_CODE_EFFORT_LEVEL"] = effort_level
+
+    # Fast mode: the CLI reads "fastMode" from user settings (~/.claude/settings.json).
+    # By default the SDK passes --setting-sources "" which blocks all filesystem settings.
+    # We enable "user" source so the CLI can read fastMode from user settings.
+    if fast_mode:
+        ensure_fast_mode_in_user_settings()
+        logger.info("[Fast Mode] ACTIVE — will enable user setting source for fastMode")
+
    # Get agent configuration (raises ValueError if unknown type)
    config = get_agent_config(agent_type)

@@ -109,10 +124,19 @@ def create_simple_client(
        "env": sdk_env,
    }

+    # Fast mode: enable user setting source so CLI reads fastMode from
+    # ~/.claude/settings.json. Without this, --setting-sources "" blocks it.
+    if fast_mode:
+        options_kwargs["setting_sources"] = ["user"]
+
    # Only add max_thinking_tokens if not None (Haiku doesn't support extended thinking)
    if max_thinking_tokens is not None:
        options_kwargs["max_thinking_tokens"] = max_thinking_tokens

+    # Add beta headers if specified (e.g., for 1M context window)
+    if betas:
+        options_kwargs["betas"] = betas
+
    # 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):
@@ -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:
@@ -17,7 +17,6 @@ Public API exported from sub-modules.
 """

 import importlib.util
-import sys
 from pathlib import Path

 # Import merge functions from workspace.py (which coexists with this package)
@@ -28,10 +27,17 @@ _workspace_module = importlib.util.module_from_spec(_spec)
 _spec.loader.exec_module(_workspace_module)
 merge_existing_build = _workspace_module.merge_existing_build
 _run_parallel_merges = _workspace_module._run_parallel_merges
+_resolve_git_conflicts_with_ai = _workspace_module._resolve_git_conflicts_with_ai
 AI_MERGE_SYSTEM_PROMPT = _workspace_module.AI_MERGE_SYSTEM_PROMPT
 _build_merge_prompt = _workspace_module._build_merge_prompt
 _check_git_conflicts = _workspace_module._check_git_conflicts
 _rebase_spec_branch = _workspace_module._rebase_spec_branch
+_create_merge_progress_callback = _workspace_module._create_merge_progress_callback
+_infer_language_from_path = _workspace_module._infer_language_from_path
+_strip_code_fences = _workspace_module._strip_code_fences
+_try_simple_3way_merge = _workspace_module._try_simple_3way_merge
+_attempt_ai_merge = _workspace_module._attempt_ai_merge
+_merge_file_with_ai_async = _workspace_module._merge_file_with_ai_async

 # Models and Enums
 # Display Functions
@@ -74,7 +80,9 @@ from .git_utils import (
    # Export private names for backward compatibility
    _is_process_running,
    _validate_merged_syntax,
+    apply_path_mapping,
    create_conflict_file_with_git,
+    detect_file_renames,
    get_binary_file_content_from_ref,
    get_changed_files_from_branch,
    get_current_branch,
@@ -91,6 +99,8 @@ from .models import (
    MergeLockError,
    ParallelMergeResult,
    ParallelMergeTask,
+    SpecNumberLock,
+    SpecNumberLockError,
    WorkspaceChoice,
    WorkspaceMode,
 )
@@ -110,11 +120,9 @@ from .setup import (
 __all__ = [
    # Merge Operations (from workspace.py)
    "merge_existing_build",
-    "_run_parallel_merges",  # Private but used internally
-    "AI_MERGE_SYSTEM_PROMPT",  # System prompt for AI merge (ACS-194)
-    "_build_merge_prompt",  # Internal prompt builder (ACS-194)
-    "_check_git_conflicts",  # Internal git conflict detection (ACS-224)
-    "_rebase_spec_branch",  # Internal rebase function (ACS-224)
+    # Note: Private functions (_run_parallel_merges, _resolve_git_conflicts_with_ai, etc.)
+    # are kept as module-level assignments for internal use but not exported in __all__
+    # to maintain the underscore convention for private/internal APIs
    # Models
    "WorkspaceMode",
    "WorkspaceChoice",
@@ -122,6 +130,8 @@ __all__ = [
    "ParallelMergeResult",
    "MergeLock",
    "MergeLockError",
+    "SpecNumberLock",
+    "SpecNumberLockError",
    # Git Utils
    "has_uncommitted_changes",
    "get_current_branch",
@@ -131,8 +141,11 @@ __all__ = [
    "get_changed_files_from_branch",
    "is_process_running",
    "is_binary_file",
+    "is_lock_file",
    "validate_merged_syntax",
    "create_conflict_file_with_git",
+    "detect_file_renames",  # File rename detection
+    "apply_path_mapping",  # Path mapping for renamed files
    # Setup
    "choose_workspace",
    "copy_spec_to_worktree",
@@ -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
@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+"""
+Pytest Configuration and Shared Fixtures for Workspace Tests
+==============================================================
+
+Provides test fixtures for the workspace module tests.
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from collections.abc import Generator
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+# =============================================================================
+# MODULE MOCK CLEANUP - Prevents test isolation issues
+# =============================================================================
+
+# List of modules that might be mocked by test files
+_POTENTIALLY_MOCKED_MODULES = [
+    "claude_code_sdk",
+    "claude_code_sdk.types",
+    "claude_agent_sdk",
+    "claude_agent_sdk.types",
+]
+
+# Store original module references at import time (BEFORE pre-mocking)
+_original_module_state = {}
+for _name in _POTENTIALLY_MOCKED_MODULES:
+    if _name in sys.modules:
+        _original_module_state[_name] = sys.modules[_name]
+
+
+# =============================================================================
+# PRE-MOCK EXTERNAL SDK MODULES - Must happen BEFORE adding auto-claude to path
+# =============================================================================
+# These SDK modules may not be installed, so we mock them before any imports
+# that might trigger loading code that depends on them.
+
+
+def _create_sdk_mock():
+    """Create a comprehensive mock for SDK modules."""
+    mock = MagicMock()
+    mock.ClaudeAgentOptions = MagicMock
+    mock.ClaudeSDKClient = MagicMock
+    mock.HookMatcher = MagicMock
+    return mock
+
+
+# Pre-mock claude_agent_sdk if not installed
+if "claude_agent_sdk" not in sys.modules:
+    sys.modules["claude_agent_sdk"] = _create_sdk_mock()
+    sys.modules["claude_agent_sdk.types"] = MagicMock()
+
+# Pre-mock claude_code_sdk if not installed
+if "claude_code_sdk" not in sys.modules:
+    sys.modules["claude_code_sdk"] = _create_sdk_mock()
+    sys.modules["claude_code_sdk.types"] = MagicMock()
+
+# Add backend directory to path for imports
+# When co-located at workspace/tests/, go up to backend directory
+# workspace/tests -> workspace -> core -> backend (4 levels up)
+_backend = Path(__file__).resolve().parent.parent.parent.parent
+sys.path.insert(0, str(_backend))
+
+# Add repo root to sys.path for test_fixtures import fallback
+_repo_root = _backend.parent.parent
+sys.path.insert(0, str(_repo_root))
+
+
+def _cleanup_mocked_modules():
+    """Remove any MagicMock modules from sys.modules."""
+    for name in _POTENTIALLY_MOCKED_MODULES:
+        if name in sys.modules:
+            module = sys.modules[name]
+            if isinstance(module, MagicMock):
+                if name in _original_module_state:
+                    sys.modules[name] = _original_module_state[name]
+                else:
+                    del sys.modules[name]
+
+
+def pytest_sessionstart(session):
+    """Clean up any mocked modules before the test session starts."""
+    _cleanup_mocked_modules()
+
+
+# =============================================================================
+# DIRECTORY FIXTURES
+# =============================================================================
+
+
+@pytest.fixture
+def temp_dir() -> Generator[Path, None, None]:
+    """Create a temporary directory that's cleaned up after the test."""
+    temp_path = Path(tempfile.mkdtemp())
+    yield temp_path
+    shutil.rmtree(temp_path, ignore_errors=True)
+
+
+@pytest.fixture
+def temp_git_repo(temp_dir: Path) -> Generator[Path, None, None]:
+    """Create a temporary git repository with initial commit.
+
+    IMPORTANT: This fixture properly isolates git operations by clearing
+    git environment variables that may be set by pre-commit hooks. Without
+    this isolation, git operations could affect the parent repository when
+    tests run inside a git worktree (e.g., during pre-commit validation).
+
+    See: https://git-scm.com/docs/git#_environment_variables
+    """
+    # Save original environment values to restore later
+    orig_env = {}
+
+    # These git env vars may be set by pre-commit hooks and MUST be cleared
+    # to avoid git operations affecting the parent repository instead of
+    # our isolated test repo. This is critical when running inside worktrees.
+    git_vars_to_clear = [
+        "GIT_DIR",
+        "GIT_WORK_TREE",
+        "GIT_INDEX_FILE",
+        "GIT_OBJECT_DIRECTORY",
+        "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+    ]
+
+    # Clear interfering git environment variables
+    for key in git_vars_to_clear:
+        orig_env[key] = os.environ.get(key)
+        if key in os.environ:
+            del os.environ[key]
+
+    # Set GIT_CEILING_DIRECTORIES to prevent git from discovering parent .git
+    # directories. This is critical for test isolation when running inside
+    # another git repo (like during pre-commit hooks in worktrees).
+    orig_env["GIT_CEILING_DIRECTORIES"] = os.environ.get("GIT_CEILING_DIRECTORIES")
+    os.environ["GIT_CEILING_DIRECTORIES"] = str(temp_dir.parent)
+
+    try:
+        # Initialize git repo
+        subprocess.run(["git", "init"], cwd=temp_dir, capture_output=True, check=True)
+        subprocess.run(
+            ["git", "config", "user.email", "test@example.com"],
+            cwd=temp_dir,
+            capture_output=True,
+        )
+        subprocess.run(
+            ["git", "config", "user.name", "Test User"],
+            cwd=temp_dir,
+            capture_output=True,
+        )
+
+        # Create initial commit
+        test_file = temp_dir / "README.md"
+        test_file.write_text("# Test Project\n", encoding="utf-8")
+        subprocess.run(["git", "add", "."], cwd=temp_dir, capture_output=True)
+        subprocess.run(
+            ["git", "commit", "-m", "Initial commit"], cwd=temp_dir, capture_output=True
+        )
+
+        # Ensure branch is named 'main' (some git configs default to 'master')
+        subprocess.run(
+            ["git", "branch", "-M", "main"], cwd=temp_dir, capture_output=True
+        )
+
+        yield temp_dir
+    finally:
+        # Restore original environment variables
+        for key, value in orig_env.items():
+            if value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = value
+
+
+@pytest.fixture
+def spec_dir(temp_dir: Path) -> Path:
+    """Create a spec directory inside temp_dir."""
+    spec_path = temp_dir / "spec"
+    spec_path.mkdir(parents=True)
+    return spec_path
+
+
+@pytest.fixture
+def project_dir(temp_dir: Path) -> Path:
+    """Create a project directory inside temp_dir."""
+    project_path = temp_dir / "project"
+    project_path.mkdir(parents=True)
+    return project_path
+
+
+@pytest.fixture
+def make_commit(temp_git_repo: Path):
+    """Fixture to make commits in the test git repo.
+
+    Usage:
+        def test_something(make_commit):
+            make_commit("message", files={"file.txt": "content"})
+    """
+
+    def _make_commit(message: str, files: dict[str, str] | None = None):
+        """Create a commit with the given message and files.
+
+        Args:
+            message: Commit message
+            files: Optional dict of {filepath: content} to create before committing
+        """
+        if files:
+            for file_path, content in files.items():
+                full_path = temp_git_repo / file_path
+                full_path.parent.mkdir(parents=True, exist_ok=True)
+                full_path.write_text(content, encoding="utf-8")
+
+        subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
+        subprocess.run(
+            ["git", "commit", "-m", message],
+            cwd=temp_git_repo,
+            capture_output=True,
+        )
+
+    return _make_commit
+
+
+@pytest.fixture
+def stage_files(temp_git_repo: Path):
+    """Fixture to stage files in the test git repo.
+
+    Usage:
+        def test_something(stage_files):
+            stage_files({"file.txt": "content"})
+    """
+
+    def _stage_files(files: dict[str, str]):
+        """Stage files for commit.
+
+        Args:
+            files: Dict of {filepath: content} to create and stage
+        """
+        for file_path, content in files.items():
+            full_path = temp_git_repo / file_path
+            full_path.parent.mkdir(parents=True, exist_ok=True)
+            full_path.write_text(content, encoding="utf-8")
+
+        subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
+
+    return _stage_files
@@ -0,0 +1,10 @@
+[pytest]
+# Pytest configuration for workspace module tests
+
+# Async test mode
+asyncio_mode = auto
+
+# Register custom markers
+markers =
+    slow: marks tests as slow (deselect with '-m "not slow"')
+    integration: marks tests as integration tests (deselect with '-m "not integration"')
@@ -0,0 +1,856 @@
+#!/usr/bin/env python3
+"""
+Tests for Workspace Display Functions
+======================================
+
+Tests the display.py module functionality including:
+- Build summary display
+- Changed files display
+- Merge success printing
+- Conflict info display
+- Environment file operations
+- Node modules symlink operations
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+# Test constant - in the new per-spec architecture, each spec has its own worktree
+# named after the spec itself. This constant is used for test assertions.
+TEST_SPEC_NAME = "test-spec"
+
+
+class TestShowBuildSummary:
+    """Tests for show_build_summary display function."""
+
+    def test_show_build_summary_no_changes(self, capsys):
+        """show_build_summary prints info message when no changes."""
+        from unittest.mock import MagicMock
+
+        from core.workspace.display import show_build_summary
+
+        mock_manager = MagicMock()
+        mock_manager.get_change_summary.return_value = {
+            "new_files": 0,
+            "modified_files": 0,
+            "deleted_files": 0,
+        }
+        mock_manager.get_changed_files.return_value = []
+
+        show_build_summary(mock_manager, "test-spec")
+
+        captured = capsys.readouterr()
+        assert "No changes were made" in captured.out
+
+    def test_show_build_summary_with_new_files(self, capsys):
+        """show_build_summary displays new files count correctly."""
+        from unittest.mock import MagicMock
+
+        from core.workspace.display import show_build_summary
+
+        mock_manager = MagicMock()
+        mock_manager.get_change_summary.return_value = {
+            "new_files": 3,
+            "modified_files": 0,
+            "deleted_files": 0,
+        }
+        mock_manager.get_changed_files.return_value = [
+            ("A", "file1.py"),
+            ("A", "file2.py"),
+            ("A", "file3.py"),
+        ]
+
+        show_build_summary(mock_manager, "test-spec")
+
+        captured = capsys.readouterr()
+        assert "What was built" in captured.out
+        assert "+ 3 new files" in captured.out
+
+    def test_show_build_summary_singular_new_file(self, capsys):
+        """show_build_summary uses singular form for one new file."""
+        from unittest.mock import MagicMock
+
+        from core.workspace.display import show_build_summary
+
+        mock_manager = MagicMock()
+        mock_manager.get_change_summary.return_value = {
+            "new_files": 1,
+            "modified_files": 0,
+            "deleted_files": 0,
+        }
+        mock_manager.get_changed_files.return_value = [("A", "file1.py")]
+
+        show_build_summary(mock_manager, "test-spec")
+
+        captured = capsys.readouterr()
+        assert "+ 1 new file" in captured.out
+        assert "files" not in captured.out.split("new file")[1].split("\n")[0]
+
+    def test_show_build_summary_with_modified_files(self, capsys):
+        """show_build_summary displays modified files count correctly."""
+        from unittest.mock import MagicMock
+
+        from core.workspace.display import show_build_summary
+
+        mock_manager = MagicMock()
+        mock_manager.get_change_summary.return_value = {
+            "new_files": 0,
+            "modified_files": 2,
+            "deleted_files": 0,
+        }
+        mock_manager.get_changed_files.return_value = [
+            ("M", "file1.py"),
+            ("M", "file2.py"),
+        ]
+
+        show_build_summary(mock_manager, "test-spec")
+
+        captured = capsys.readouterr()
+        assert "~ 2 modified files" in captured.out
+
+    def test_show_build_summary_with_deleted_files(self, capsys):
+        """show_build_summary displays deleted files count correctly."""
+        from unittest.mock import MagicMock
+
+        from core.workspace.display import show_build_summary
+
+        mock_manager = MagicMock()
+        mock_manager.get_change_summary.return_value = {
+            "new_files": 0,
+            "modified_files": 0,
+            "deleted_files": 1,
+        }
+        mock_manager.get_changed_files.return_value = [("D", "old.py")]
+
+        show_build_summary(mock_manager, "test-spec")
+
+        captured = capsys.readouterr()
+        assert "- 1 deleted file" in captured.out
+
+    def test_show_build_summary_mixed_changes(self, capsys):
+        """show_build_summary displays all change types together."""
+        from unittest.mock import MagicMock
+
+        from core.workspace.display import show_build_summary
+
+        mock_manager = MagicMock()
+        mock_manager.get_change_summary.return_value = {
+            "new_files": 2,
+            "modified_files": 3,
+            "deleted_files": 1,
+        }
+        mock_manager.get_changed_files.return_value = [
+            ("A", "new1.py"),
+            ("A", "new2.py"),
+            ("M", "mod1.py"),
+            ("M", "mod2.py"),
+            ("M", "mod3.py"),
+            ("D", "old.py"),
+        ]
+
+        show_build_summary(mock_manager, "test-spec")
+
+        captured = capsys.readouterr()
+        assert "+ 2 new files" in captured.out
+        assert "~ 3 modified files" in captured.out
+        assert "- 1 deleted file" in captured.out
+
+
+class TestShowChangedFiles:
+    """Tests for show_changed_files display function."""
+
+    def test_show_changed_files_empty_list(self, capsys):
+        """show_changed_files prints info message when no files changed."""
+        from unittest.mock import MagicMock
+
+        from core.workspace.display import show_changed_files
+
+        mock_manager = MagicMock()
+        mock_manager.get_changed_files.return_value = []
+
+        show_changed_files(mock_manager, "test-spec")
+
+        captured = capsys.readouterr()
+        assert "No changes" in captured.out
+
+    def test_show_changed_files_with_added_file(self, capsys):
+        """show_changed_files displays added file with + prefix."""
+        from unittest.mock import MagicMock
+
+        from core.workspace.display import show_changed_files
+
+        mock_manager = MagicMock()
+        mock_manager.get_changed_files.return_value = [("A", "new_file.py")]
+
+        show_changed_files(mock_manager, "test-spec")
+
+        captured = capsys.readouterr()
+        assert "Changed files" in captured.out
+        assert "+ new_file.py" in captured.out
+
+    def test_show_changed_files_with_modified_file(self, capsys):
+        """show_changed_files displays modified file with ~ prefix."""
+        from unittest.mock import MagicMock
+
+        from core.workspace.display import show_changed_files
+
+        mock_manager = MagicMock()
+        mock_manager.get_changed_files.return_value = [("M", "changed.py")]
+
+        show_changed_files(mock_manager, "test-spec")
+
+        captured = capsys.readouterr()
+        assert "~ changed.py" in captured.out
+
+    def test_show_changed_files_with_deleted_file(self, capsys):
+        """show_changed_files displays deleted file with - prefix."""
+        from unittest.mock import MagicMock
+
+        from core.workspace.display import show_changed_files
+
+        mock_manager = MagicMock()
+        mock_manager.get_changed_files.return_value = [("D", "removed.py")]
+
+        show_changed_files(mock_manager, "test-spec")
+
+        captured = capsys.readouterr()
+        assert "- removed.py" in captured.out
+
+    def test_show_changed_files_with_unknown_status(self, capsys):
+        """show_changed_files displays unknown status code without decoration."""
+        from unittest.mock import MagicMock
+
+        from core.workspace.display import show_changed_files
+
+        mock_manager = MagicMock()
+        mock_manager.get_changed_files.return_value = [("R", "renamed.py")]
+
+        show_changed_files(mock_manager, "test-spec")
+
+        captured = capsys.readouterr()
+        assert "R renamed.py" in captured.out
+
+    def test_show_changed_files_multiple_files(self, capsys):
+        """show_changed_files displays all changed files."""
+        from unittest.mock import MagicMock
+
+        from core.workspace.display import show_changed_files
+
+        mock_manager = MagicMock()
+        mock_manager.get_changed_files.return_value = [
+            ("A", "new.py"),
+            ("M", "modified.py"),
+            ("D", "deleted.py"),
+            ("R", "renamed.py"),
+        ]
+
+        show_changed_files(mock_manager, "test-spec")
+
+        captured = capsys.readouterr()
+        assert "+ new.py" in captured.out
+        assert "~ modified.py" in captured.out
+        assert "- deleted.py" in captured.out
+        assert "R renamed.py" in captured.out
+
+
+class TestPrintMergeSuccess:
+    """Tests for print_merge_success display function."""
+
+    def test_print_merge_success_no_commit_basic(self, capsys):
+        """print_merge_success with no_commit=True shows basic message."""
+        from core.workspace.display import print_merge_success
+
+        print_merge_success(no_commit=True)
+
+        captured = capsys.readouterr()
+        assert "CHANGES ADDED TO YOUR PROJECT" in captured.out
+        assert "working directory" in captured.out
+        assert "Review the changes" in captured.out
+        assert "commit when ready" in captured.out
+
+    def test_print_merge_success_no_commit_with_lock_files(self, capsys):
+        """print_merge_success with lock_files_excluded shows lock file note."""
+        from core.workspace.display import print_merge_success
+
+        stats = {"lock_files_excluded": 2}
+        print_merge_success(no_commit=True, stats=stats)
+
+        captured = capsys.readouterr()
+        assert "CHANGES ADDED TO YOUR PROJECT" in captured.out
+        assert "Lock files kept from main" in captured.out
+        assert "npm install" in captured.out
+
+    def test_print_merge_success_no_commit_with_keep_worktree(self, capsys):
+        """print_merge_success with keep_worktree shows discard command."""
+        from core.workspace.display import print_merge_success
+
+        print_merge_success(no_commit=True, spec_name="spec-001", keep_worktree=True)
+
+        captured = capsys.readouterr()
+        assert "CHANGES ADDED TO YOUR PROJECT" in captured.out
+        assert "Worktree kept for testing" in captured.out
+        assert "python auto-claude/run.py --spec spec-001 --discard" in captured.out
+
+    def test_print_merge_success_no_commit_full_scenario(self, capsys):
+        """print_merge_success with all optional parameters."""
+        from core.workspace.display import print_merge_success
+
+        stats = {"lock_files_excluded": 1}
+        print_merge_success(
+            no_commit=True,
+            stats=stats,
+            spec_name="test-spec",
+            keep_worktree=True,
+        )
+
+        captured = capsys.readouterr()
+        assert "CHANGES ADDED TO YOUR PROJECT" in captured.out
+        assert "Lock files kept from main" in captured.out
+        assert "Worktree kept for testing" in captured.out
+        assert "--spec test-spec --discard" in captured.out
+
+    def test_print_merge_success_with_commit_basic(self, capsys):
+        """print_merge_success with no_commit=False shows commit message."""
+        from core.workspace.display import print_merge_success
+
+        print_merge_success(no_commit=False)
+
+        captured = capsys.readouterr()
+        assert "FEATURE ADDED TO YOUR PROJECT" in captured.out
+        assert "separate workspace has been cleaned up" in captured.out
+
+    def test_print_merge_success_with_commit_and_stats(self, capsys):
+        """print_merge_success with stats shows file counts."""
+        from core.workspace.display import print_merge_success
+
+        stats = {
+            "files_added": 5,
+            "files_modified": 3,
+            "files_deleted": 1,
+        }
+        print_merge_success(no_commit=False, stats=stats)
+
+        captured = capsys.readouterr()
+        assert "FEATURE ADDED TO YOUR PROJECT" in captured.out
+        assert "What changed" in captured.out
+        assert "+ 5 files added" in captured.out
+        assert "~ 3 files modified" in captured.out
+        assert "- 1 file deleted" in captured.out
+
+    def test_print_merge_success_singular_file_counts(self, capsys):
+        """print_merge_success uses singular form for single file counts."""
+        from core.workspace.display import print_merge_success
+
+        stats = {
+            "files_added": 1,
+            "files_modified": 1,
+            "files_deleted": 1,
+        }
+        print_merge_success(no_commit=False, stats=stats)
+
+        captured = capsys.readouterr()
+        assert "+ 1 file added" in captured.out
+        assert "~ 1 file modified" in captured.out
+        assert "- 1 file deleted" in captured.out
+
+    def test_print_merge_success_with_keep_worktree(self, capsys):
+        """print_merge_success with keep_worktree shows discard command."""
+        from core.workspace.display import print_merge_success
+
+        print_merge_success(no_commit=False, keep_worktree=True, spec_name="my-spec")
+
+        captured = capsys.readouterr()
+        assert "FEATURE ADDED TO YOUR PROJECT" in captured.out
+        assert "Worktree kept for testing" in captured.out
+        assert "--spec my-spec --discard" in captured.out
+        assert "separate workspace has been cleaned up" not in captured.out
+
+    def test_print_merge_success_zero_file_counts_not_shown(self, capsys):
+        """print_merge_success doesn't show file types with zero count."""
+        from core.workspace.display import print_merge_success
+
+        stats = {
+            "files_added": 2,
+            "files_modified": 0,
+            "files_deleted": 0,
+        }
+        print_merge_success(no_commit=False, stats=stats)
+
+        captured = capsys.readouterr()
+        assert "+ 2 files added" in captured.out
+        assert "files modified" not in captured.out
+        assert "files deleted" not in captured.out
+
+
+class TestPrintConflictInfoExtended:
+    """Extended tests for print_conflict_info display function."""
+
+    def test_print_conflict_info_empty_conflicts(self, capsys):
+        """print_conflict_info returns early with empty conflicts list."""
+        from core.workspace.display import print_conflict_info
+
+        result = {"conflicts": []}
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        assert captured.out == ""
+
+    def test_print_conflict_info_no_conflicts_key(self, capsys):
+        """print_conflict_info returns early when conflicts key missing."""
+        from core.workspace.display import print_conflict_info
+
+        result = {}
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        assert captured.out == ""
+
+    def test_print_conflict_info_critical_severity(self, capsys):
+        """print_conflict_info shows critical severity icon."""
+        from core.workspace.display import print_conflict_info
+
+        result = {
+            "conflicts": [
+                {
+                    "file": "critical.py",
+                    "reason": "Breaking change",
+                    "severity": "critical",
+                }
+            ]
+        }
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        assert "critical.py" in captured.out
+        assert "⛔" in captured.out
+        assert "Breaking change" in captured.out
+
+    def test_print_conflict_info_high_severity(self, capsys):
+        """print_conflict_info shows high severity icon."""
+        from core.workspace.display import print_conflict_info
+
+        result = {
+            "conflicts": [
+                {"file": "high.py", "reason": "Major conflict", "severity": "high"}
+            ]
+        }
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        assert "high.py" in captured.out
+        assert "🔴" in captured.out
+        assert "Major conflict" in captured.out
+
+    def test_print_conflict_info_medium_severity(self, capsys):
+        """print_conflict_info shows medium severity icon."""
+        from core.workspace.display import print_conflict_info
+
+        result = {
+            "conflicts": [
+                {"file": "medium.py", "reason": "Minor conflict", "severity": "medium"}
+            ]
+        }
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        assert "medium.py" in captured.out
+        assert "🟡" in captured.out
+        assert "Minor conflict" in captured.out
+
+    def test_print_conflict_info_low_severity_no_icon(self, capsys):
+        """print_conflict_info shows no icon for low severity."""
+        from core.workspace.display import print_conflict_info
+
+        result = {
+            "conflicts": [
+                {"file": "low.py", "reason": "Trivial issue", "severity": "low"}
+            ]
+        }
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        assert "low.py" in captured.out
+        assert "Trivial issue" in captured.out
+        assert "⛔" not in captured.out
+        assert "🔴" not in captured.out
+        assert "🟡" not in captured.out
+
+    def test_print_conflict_info_unknown_severity(self, capsys):
+        """print_conflict_info handles unknown severity gracefully."""
+        from core.workspace.display import print_conflict_info
+
+        result = {
+            "conflicts": [
+                {"file": "unknown.py", "reason": "Unknown", "severity": "unknown"}
+            ]
+        }
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        assert "unknown.py" in captured.out
+        assert "Unknown" in captured.out
+
+    def test_print_conflict_info_missing_file_key(self, capsys):
+        """print_conflict_info handles missing file key."""
+        from core.workspace.display import print_conflict_info
+
+        result = {"conflicts": [{"reason": "No file specified", "severity": "high"}]}
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        assert "unknown" in captured.out
+        assert "No file specified" in captured.out
+
+    def test_print_conflict_info_missing_reason_key(self, capsys):
+        """print_conflict_info handles missing reason key."""
+        from core.workspace.display import print_conflict_info
+
+        result = {"conflicts": [{"file": "noreason.py", "severity": "medium"}]}
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        assert "noreason.py" in captured.out
+
+    def test_print_conflict_info_dict_no_reason(self, capsys):
+        """print_conflict_info with dict missing reason."""
+        from core.workspace.display import print_conflict_info
+
+        result = {"conflicts": [{"file": "test.py", "severity": "high"}]}
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        assert "test.py" in captured.out
+        assert "🔴" in captured.out
+
+    def test_print_conflict_info_multiple_conflicts(self, capsys):
+        """print_conflict_info handles multiple conflicts."""
+        from core.workspace.display import print_conflict_info
+
+        result = {
+            "conflicts": [
+                {"file": "critical.py", "reason": "Critical", "severity": "critical"},
+                {"file": "high.py", "reason": "High", "severity": "high"},
+                {"file": "medium.py", "reason": "Medium", "severity": "medium"},
+            ]
+        }
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        assert "3 file" in captured.out
+        assert "⛔" in captured.out
+        assert "🔴" in captured.out
+        assert "🟡" in captured.out
+
+    def test_print_conflict_info_shows_marker_conflict_message(self, capsys):
+        """print_conflict_info shows marker conflict message for string conflicts."""
+        from core.workspace.display import print_conflict_info
+
+        result = {"conflicts": ["conflict.py"]}
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        assert "conflict markers" in captured.out
+        # Check that the conflict markers are mentioned in the message
+
+    def test_print_conflict_info_shows_ai_conflict_message(self, capsys):
+        """print_conflict_info shows AI conflict message for dict conflicts."""
+        from core.workspace.display import print_conflict_info
+
+        result = {
+            "conflicts": [
+                {
+                    "file": "ai-conflict.py",
+                    "reason": "AI merge failed",
+                    "severity": "high",
+                }
+            ]
+        }
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        assert "could not be auto-merged" in captured.out
+
+    def test_print_conflict_info_shows_both_messages_mixed(self, capsys):
+        """print_conflict_info shows both messages for mixed conflicts."""
+        from core.workspace.display import print_conflict_info
+
+        result = {
+            "conflicts": [
+                "marker.py",
+                {"file": "ai.py", "reason": "AI failed", "severity": "high"},
+            ]
+        }
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        assert "conflict markers" in captured.out
+        assert "could not be auto-merged" in captured.out
+
+    def test_print_conflict_info_shows_git_commands(self, capsys):
+        """print_conflict_info shows git add and commit commands."""
+        from core.workspace.display import print_conflict_info
+
+        result = {"conflicts": ["file1.py", "file2.py"]}
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        assert "git add" in captured.out
+        assert "git commit" in captured.out
+
+    def test_print_conflict_info_quotes_special_paths(self, capsys):
+        """print_conflict_info properly quotes file paths with special characters."""
+        from core.workspace.display import print_conflict_info
+
+        result = {"conflicts": ["file with spaces.py", "file'with'quotes.py"]}
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        # shlex.quote should quote paths with spaces
+        assert "git add" in captured.out
+        assert "file with spaces.py" in captured.out
+
+    def test_print_conflict_info_deduplicates_files(self, capsys):
+        """print_conflict_info deduplicates file paths in git command."""
+        from core.workspace.display import print_conflict_info
+
+        result = {
+            "conflicts": [
+                "file1.py",
+                {"file": "file1.py", "reason": "Also here", "severity": "medium"},
+                "file2.py",
+            ]
+        }
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        # Count occurrences of file1.py
+        count = captured.out.count("file1.py")
+        assert count == 3  # Display shows it twice (string + dict), once in git add
+
+    def test_print_conflict_info_preserves_order(self, capsys):
+        """print_conflict_info preserves file order while deduplicating."""
+        from core.workspace.display import print_conflict_info
+
+        result = {
+            "conflicts": [
+                "first.py",
+                {"file": "second.py", "severity": "high"},
+                "first.py",  # Duplicate
+                {"file": "third.py", "severity": "medium"},
+            ]
+        }
+
+        print_conflict_info(result)
+
+        captured = capsys.readouterr()
+        # First occurrence should be preserved
+        lines = captured.out.split("\n")
+        first_idx = None
+        second_idx = None
+        for i, line in enumerate(lines):
+            if "first.py" in line:
+                if first_idx is None:
+                    first_idx = i
+            if "second.py" in line:
+                if second_idx is None:
+                    second_idx = i
+        assert first_idx is not None
+        assert second_idx is not None
+
+
+class TestCopyEnvFilesToWorktree:
+    """Tests for copy_env_files_to_worktree function."""
+
+    def test_copies_all_env_files(self, temp_git_repo: Path):
+        """Copies all .env files when they exist in project dir."""
+        from core.workspace.setup import copy_env_files_to_worktree
+
+        # Create .env files in project
+        (temp_git_repo / ".env").write_text("FOO=bar", encoding="utf-8")
+        (temp_git_repo / ".env.local").write_text("LOCAL=1", encoding="utf-8")
+        (temp_git_repo / ".env.development").write_text("DEV=1", encoding="utf-8")
+
+        # Create worktree directory
+        worktree_path = (
+            temp_git_repo / ".auto-claude" / "worktrees" / "tasks" / "test-spec"
+        )
+        worktree_path.mkdir(parents=True)
+
+        # Copy env files
+        copied = copy_env_files_to_worktree(temp_git_repo, worktree_path)
+
+        # Check all files were copied
+        assert ".env" in copied
+        assert ".env.local" in copied
+        assert ".env.development" in copied
+        assert len(copied) == 3
+
+        # Verify files exist in worktree
+        assert (worktree_path / ".env").exists()
+        assert (worktree_path / ".env.local").exists()
+        assert (worktree_path / ".env.development").exists()
+
+    def test_skips_nonexistent_env_files(self, temp_git_repo: Path):
+        """Only copies env files that exist."""
+        from core.workspace.setup import copy_env_files_to_worktree
+
+        worktree_path = (
+            temp_git_repo / ".auto-claude" / "worktrees" / "tasks" / "test-spec"
+        )
+        worktree_path.mkdir(parents=True)
+
+        copied = copy_env_files_to_worktree(temp_git_repo, worktree_path)
+
+        assert len(copied) == 0
+
+    def test_does_not_overwrite_existing_env_files(self, temp_git_repo: Path):
+        """Does not overwrite .env files that already exist in worktree."""
+        from core.workspace.setup import copy_env_files_to_worktree
+
+        # Create .env in project
+        (temp_git_repo / ".env").write_text("PROJECT=1", encoding="utf-8")
+
+        worktree_path = (
+            temp_git_repo / ".auto-claude" / "worktrees" / "tasks" / "test-spec"
+        )
+        worktree_path.mkdir(parents=True)
+
+        # Create existing .env in worktree with different content
+        (worktree_path / ".env").write_text("WORKTREE=1", encoding="utf-8")
+
+        copied = copy_env_files_to_worktree(temp_git_repo, worktree_path)
+
+        # .env should not be in copied list since it already existed
+        assert ".env" not in copied
+
+        # Worktree .env should keep its original content
+        assert (worktree_path / ".env").read_text(encoding="utf-8") == "WORKTREE=1"
+
+
+class TestSymlinkNodeModulesToWorktree:
+    """Tests for symlink_node_modules_to_worktree function."""
+
+    @pytest.mark.skipif(sys.platform != "linux", reason="Unix-specific test")
+    def test_symlinks_node_modules_on_unix(self, temp_git_repo: Path):
+        """Creates relative symlinks on Unix systems."""
+        from core.workspace.setup import symlink_node_modules_to_worktree
+
+        # Create node_modules in project
+        node_modules = temp_git_repo / "node_modules"
+        node_modules.mkdir()
+        (node_modules / "test.txt").write_text("test", encoding="utf-8")
+
+        # Create apps/frontend/node_modules
+        frontend_node_modules = temp_git_repo / "apps" / "frontend" / "node_modules"
+        frontend_node_modules.mkdir(parents=True)
+        (frontend_node_modules / "test2.txt").write_text("test2", encoding="utf-8")
+
+        # Create worktree
+        worktree_path = (
+            temp_git_repo / ".auto-claude" / "worktrees" / "tasks" / "test-spec"
+        )
+        worktree_path.mkdir(parents=True)
+        (worktree_path / "apps" / "frontend").mkdir(parents=True)
+
+        # Create symlinks
+        symlinked = symlink_node_modules_to_worktree(temp_git_repo, worktree_path)
+
+        assert len(symlinked) == 2
+        assert "node_modules" in symlinked
+        assert "apps/frontend/node_modules" in symlinked
+
+        # Verify symlinks exist and point to correct location
+        assert (worktree_path / "node_modules").is_symlink()
+        assert (worktree_path / "apps" / "frontend" / "node_modules").is_symlink()
+
+    @pytest.mark.skipif(sys.platform != "win32", reason="Windows-specific test")
+    def test_creates_junctions_on_windows(self, temp_git_repo: Path, monkeypatch):
+        """Creates junctions on Windows systems."""
+        from unittest.mock import patch
+
+        from core.workspace.setup import symlink_node_modules_to_worktree
+
+        # Create node_modules in project
+        node_modules = temp_git_repo / "node_modules"
+        node_modules.mkdir()
+        (node_modules / "test.txt").write_text("test", encoding="utf-8")
+
+        # Create worktree
+        worktree_path = (
+            temp_git_repo / ".auto-claude" / "worktrees" / "tasks" / "test-spec"
+        )
+        worktree_path.mkdir(parents=True)
+
+        # Mock subprocess.run to simulate mklink /J success
+        def mock_subprocess_run(cmd, capture_output=False, text=False):
+            result = type("obj", (object,), {"returncode": 0, "stderr": ""})()
+            return result
+
+        with patch("subprocess.run", side_effect=mock_subprocess_run):
+            with monkeypatch.context() as m:
+                m.setattr("sys.platform", "win32")
+                symlinked = symlink_node_modules_to_worktree(
+                    temp_git_repo, worktree_path
+                )
+
+        assert "node_modules" in symlinked
+
+    def test_skips_nonexistent_node_modules(self, temp_git_repo: Path):
+        """Skips node_modules that don't exist in project."""
+        from core.workspace.setup import symlink_node_modules_to_worktree
+
+        worktree_path = (
+            temp_git_repo / ".auto-claude" / "worktrees" / "tasks" / "test-spec"
+        )
+        worktree_path.mkdir(parents=True)
+
+        symlinked = symlink_node_modules_to_worktree(temp_git_repo, worktree_path)
+
+        assert len(symlinked) == 0
+
+    def test_skips_existing_symlinks(self, temp_git_repo: Path):
+        """Does not recreate symlinks that already exist."""
+        from core.workspace.setup import symlink_node_modules_to_worktree
+
+        # Create node_modules in project
+        node_modules = temp_git_repo / "node_modules"
+        node_modules.mkdir()
+        (node_modules / "test.txt").write_text("test", encoding="utf-8")
+
+        # Create worktree
+        worktree_path = (
+            temp_git_repo / ".auto-claude" / "worktrees" / "tasks" / "test-spec"
+        )
+        worktree_path.mkdir(parents=True)
+
+        # Create existing symlink
+        if sys.platform != "win32":
+            os.symlink(temp_git_repo / "node_modules", worktree_path / "node_modules")
+
+        symlinked = symlink_node_modules_to_worktree(temp_git_repo, worktree_path)
+
+        # Should skip existing symlink
+        assert "node_modules" not in symlinked
@@ -0,0 +1,805 @@
+#!/usr/bin/env python3
+"""
+Tests for Workspace Selection and Management
+=============================================
+
+Tests the workspace.py module functionality including:
+- Workspace mode selection (isolated vs direct)
+- Uncommitted changes detection
+- Workspace setup
+- Build finalization workflows
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+# Add parent directory to path so we can import the workspace module
+# When co-located at workspace/tests/, we need to add backend to path
+# workspace/tests -> workspace -> core -> backend (4 levels up)
+_backend = Path(__file__).resolve().parent.parent.parent.parent
+sys.path.insert(0, str(_backend))
+
+from core.workspace import (
+    WorkspaceChoice,
+    WorkspaceMode,
+    get_current_branch,
+    get_existing_build_worktree,
+    has_uncommitted_changes,
+    setup_workspace,
+)
+from worktree import WorktreeError, WorktreeManager
+
+# Test constant - in the new per-spec architecture, each spec has its own worktree
+# named after the spec itself. This constant is used for test assertions.
+TEST_SPEC_NAME = "test-spec"
+
+# =============================================================================
+# TESTS FOR finalization.py
+# =============================================================================
+
+
+class TestFinalizeWorkspace:
+    """Tests for finalize_workspace function."""
+
+    def test_direct_mode_returns_merge(self, temp_git_repo: Path, monkeypatch, capsys):
+        """Direct mode returns MERGE choice and shows completion message."""
+        from core.workspace.finalization import finalize_workspace
+
+        # Mock the UI functions
+        def mock_box(content, width=60, style="heavy"):
+            return content
+
+        monkeypatch.setattr("core.workspace.finalization.box", mock_box)
+
+        result = finalize_workspace(
+            temp_git_repo,
+            "test-spec",
+            manager=None,
+            auto_continue=False,
+        )
+
+        assert result == WorkspaceChoice.MERGE
+
+        captured = capsys.readouterr()
+        assert "BUILD COMPLETE" in captured.out
+        assert "directly to your project" in captured.out
+
+    def test_auto_continue_mode_returns_later(self, temp_git_repo: Path):
+        """Auto-continue mode returns LATER choice."""
+        from core.workspace.finalization import finalize_workspace
+
+        manager = WorktreeManager(temp_git_repo)
+        spec_name = "test-spec"
+
+        # Create worktree info
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        result = finalize_workspace(
+            temp_git_repo,
+            spec_name,
+            manager=manager,
+            auto_continue=True,
+        )
+
+        assert result == WorkspaceChoice.LATER
+
+    def test_isolated_mode_shows_menu(self, temp_git_repo: Path, monkeypatch):
+        """Isolated mode shows menu with test/review/merge/later options."""
+        from core.workspace.finalization import finalize_workspace
+
+        manager = WorktreeManager(temp_git_repo)
+        spec_name = "test-spec"
+
+        # Create worktree
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        # Mock select_menu to return "test"
+        def mock_select_menu(title, options, allow_quit):
+            return "test"
+
+        monkeypatch.setattr("core.workspace.finalization.select_menu", mock_select_menu)
+
+        result = finalize_workspace(
+            temp_git_repo,
+            spec_name,
+            manager=manager,
+            auto_continue=False,
+        )
+
+        assert result == WorkspaceChoice.TEST
+
+
+class TestHandleWorkspaceChoice:
+    """Tests for handle_workspace_choice function."""
+
+    def test_choice_test_shows_instructions(
+        self, temp_git_repo: Path, monkeypatch, capsys
+    ):
+        """TEST choice shows testing instructions."""
+        from core.workspace.finalization import handle_workspace_choice
+
+        manager = WorktreeManager(temp_git_repo)
+        spec_name = "test-spec"
+
+        # Create worktree
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        handle_workspace_choice(WorkspaceChoice.TEST, temp_git_repo, spec_name, manager)
+
+        captured = capsys.readouterr()
+        assert "TEST YOUR FEATURE" in captured.out
+        assert str(worktree_path) in captured.out
+
+    def test_choice_merge_calls_merge_worktree(
+        self, temp_git_repo: Path, monkeypatch, capsys
+    ):
+        """MERGE choice calls manager.merge_worktree."""
+        from core.workspace.finalization import handle_workspace_choice
+
+        manager = WorktreeManager(temp_git_repo)
+        spec_name = "test-spec"
+
+        # Create worktree and commit something
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+        (worktree_path / "test.py").write_text("test", encoding="utf-8")
+
+        # Initialize git in worktree and commit
+        subprocess.run(["git", "init"], cwd=worktree_path, capture_output=True)
+        subprocess.run(
+            ["git", "config", "user.email", "test@example.com"],
+            cwd=worktree_path,
+            capture_output=True,
+        )
+        subprocess.run(
+            ["git", "config", "user.name", "Test"],
+            cwd=worktree_path,
+            capture_output=True,
+        )
+        subprocess.run(["git", "add", "."], cwd=worktree_path, capture_output=True)
+        subprocess.run(
+            ["git", "commit", "-m", "Test"], cwd=worktree_path, capture_output=True
+        )
+
+        handle_workspace_choice(
+            WorkspaceChoice.MERGE, temp_git_repo, spec_name, manager
+        )
+
+        captured = capsys.readouterr()
+        assert "Adding changes" in captured.out
+
+    def test_choice_review_shows_changed_files(
+        self, temp_git_repo: Path, monkeypatch, capsys
+    ):
+        """REVIEW choice shows changed files."""
+        from core.workspace.finalization import handle_workspace_choice
+
+        manager = WorktreeManager(temp_git_repo)
+        spec_name = "test-spec"
+
+        # Create worktree
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        # Mock show_changed_files
+        mock_shown = []
+
+        def mock_show_changed_files(manager, spec_name):
+            mock_shown.append(spec_name)
+
+        monkeypatch.setattr(
+            "core.workspace.finalization.show_changed_files", mock_show_changed_files
+        )
+
+        handle_workspace_choice(
+            WorkspaceChoice.REVIEW, temp_git_repo, spec_name, manager
+        )
+
+        assert len(mock_shown) == 1
+        assert mock_shown[0] == spec_name
+
+        captured = capsys.readouterr()
+        assert "To see full details" in captured.out
+
+    def test_choice_later_shows_deferred_message(
+        self, temp_git_repo: Path, monkeypatch, capsys
+    ):
+        """LATER choice shows deferral message."""
+        from core.workspace.finalization import handle_workspace_choice
+
+        manager = WorktreeManager(temp_git_repo)
+        spec_name = "test-spec"
+
+        # Create worktree
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        handle_workspace_choice(
+            WorkspaceChoice.LATER, temp_git_repo, spec_name, manager
+        )
+
+        captured = capsys.readouterr()
+        assert "No problem!" in captured.out
+        assert "saved" in captured.out
+
+
+class TestReviewExistingBuild:
+    """Tests for review_existing_build function."""
+
+    def test_no_existing_build_shows_warning(self, temp_git_repo: Path, capsys):
+        """Shows warning when no existing build found."""
+        from core.workspace.finalization import review_existing_build
+
+        result = review_existing_build(temp_git_repo, "nonexistent-spec")
+
+        assert result is False
+
+        captured = capsys.readouterr()
+        assert "No existing build found" in captured.out
+
+    def test_shows_build_contents(self, temp_git_repo: Path, capsys):
+        """Shows build summary and changed files when build exists."""
+        from core.workspace.finalization import review_existing_build
+
+        spec_name = "test-spec"
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        result = review_existing_build(temp_git_repo, spec_name)
+
+        assert result is True
+
+        captured = capsys.readouterr()
+        assert "BUILD CONTENTS" in captured.out
+
+
+class TestDiscardExistingBuild:
+    """Tests for discard_existing_build function."""
+
+    def test_no_existing_build_returns_false(self, temp_git_repo: Path, capsys):
+        """Returns False when no existing build found."""
+        from core.workspace.finalization import discard_existing_build
+
+        result = discard_existing_build(temp_git_repo, "nonexistent-spec")
+
+        assert result is False
+
+        captured = capsys.readouterr()
+        assert "No existing build found" in captured.out
+
+    def test_confirmation_deletes_build(self, temp_git_repo: Path, monkeypatch, capsys):
+        """Deletes build when user types 'delete' to confirm."""
+        from core.workspace.finalization import discard_existing_build
+
+        spec_name = "test-spec"
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        # Mock input to return "delete"
+        monkeypatch.setattr("builtins.input", lambda: "delete")
+
+        result = discard_existing_build(temp_git_repo, spec_name)
+
+        assert result is True
+        captured = capsys.readouterr()
+        assert "Build deleted" in captured.out
+
+    def test_cancelled_confirmation_returns_false(
+        self, temp_git_repo: Path, monkeypatch, capsys
+    ):
+        """Returns False when user doesn't confirm."""
+        from core.workspace.finalization import discard_existing_build
+
+        spec_name = "test-spec"
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        # Mock input to return "no"
+        monkeypatch.setattr("builtins.input", lambda: "no")
+
+        result = discard_existing_build(temp_git_repo, spec_name)
+
+        assert result is False
+        captured = capsys.readouterr()
+        assert "Cancelled" in captured.out
+
+
+class TestCheckExistingBuild:
+    """Tests for check_existing_build function."""
+
+    def test_no_existing_build_returns_false(self, temp_git_repo: Path):
+        """Returns False when no existing build."""
+        from core.workspace.finalization import check_existing_build
+
+        result = check_existing_build(temp_git_repo, "nonexistent-spec")
+
+        assert result is False
+
+    def test_shows_menu_for_existing_build(self, temp_git_repo: Path, monkeypatch):
+        """Shows menu when existing build found."""
+        from core.workspace.finalization import check_existing_build
+
+        spec_name = "test-spec"
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        # Mock select_menu to return "continue"
+        def mock_select_menu(title, options, allow_quit):
+            return "continue"
+
+        monkeypatch.setattr("core.workspace.finalization.select_menu", mock_select_menu)
+
+        result = check_existing_build(temp_git_repo, spec_name)
+
+        assert result is True
+
+    def test_review_choice_reviews_and_continues(
+        self, temp_git_repo: Path, monkeypatch
+    ):
+        """Review choice reviews build then continues."""
+        from core.workspace.finalization import check_existing_build
+
+        spec_name = "test-spec"
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        review_called = []
+
+        def mock_review(project_dir, spec_name):
+            review_called.append(spec_name)
+            return True
+
+        def mock_select_menu(title, options, allow_quit):
+            return "review"
+
+        def mock_input(prompt):
+            return ""
+
+        monkeypatch.setattr(
+            "core.workspace.finalization.review_existing_build", mock_review
+        )
+        monkeypatch.setattr("core.workspace.finalization.select_menu", mock_select_menu)
+        monkeypatch.setattr("builtins.input", mock_input)
+
+        result = check_existing_build(temp_git_repo, spec_name)
+
+        assert result is True
+        assert spec_name in review_called
+
+
+class TestListAllWorktrees:
+    """Tests for list_all_worktrees function."""
+
+    def test_returns_empty_list_when_no_worktrees(self, temp_git_repo: Path):
+        """Returns empty list when no worktrees exist."""
+        from core.workspace.finalization import list_all_worktrees
+
+        result = list_all_worktrees(temp_git_repo)
+
+        assert result == []
+
+    def test_lists_existing_worktrees(self, temp_git_repo: Path):
+        """Returns list of existing worktrees."""
+        from core.workspace.finalization import list_all_worktrees
+
+        # Create worktrees
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        (worktrees_dir / "spec-001").mkdir()
+        (worktrees_dir / "spec-002").mkdir()
+
+        result = list_all_worktrees(temp_git_repo)
+
+        assert len(result) == 2
+        spec_names = {wt.spec_name for wt in result}
+        assert "spec-001" in spec_names
+        assert "spec-002" in spec_names
+
+
+class TestCleanupAllWorktrees:
+    """Tests for cleanup_all_worktrees function."""
+
+    def test_no_worktrees_returns_false(self, temp_git_repo: Path, capsys):
+        """Returns False when no worktrees found."""
+        from core.workspace.finalization import cleanup_all_worktrees
+
+        result = cleanup_all_worktrees(temp_git_repo, confirm=False)
+
+        assert result is False
+
+        captured = capsys.readouterr()
+        assert "No worktrees found" in captured.out
+
+    def test_cleanup_without_confirmation(self, temp_git_repo: Path):
+        """Cleans up worktrees when confirm=False."""
+        from core.workspace.finalization import cleanup_all_worktrees
+
+        # Create worktrees
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        spec1_path = worktrees_dir / "spec-001"
+        spec1_path.mkdir()
+        spec2_path = worktrees_dir / "spec-002"
+        spec2_path.mkdir()
+
+        result = cleanup_all_worktrees(temp_git_repo, confirm=False)
+
+        assert result is True
+        assert not spec1_path.exists()
+        assert not spec2_path.exists()
+
+    def test_cleanup_with_confirmation_yes(self, temp_git_repo: Path, monkeypatch):
+        """Cleans up worktrees when user confirms with 'yes'."""
+        from core.workspace.finalization import cleanup_all_worktrees
+
+        # Create worktrees
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        spec1_path = worktrees_dir / "spec-001"
+        spec1_path.mkdir()
+
+        # Mock input to return "yes"
+        monkeypatch.setattr("builtins.input", lambda: "yes")
+
+        result = cleanup_all_worktrees(temp_git_repo, confirm=True)
+
+        assert result is True
+        assert not spec1_path.exists()
+
+    def test_cleanup_with_confirmation_no(self, temp_git_repo: Path, monkeypatch):
+        """Cancels cleanup when user doesn't confirm."""
+        from core.workspace.finalization import cleanup_all_worktrees
+
+        # Create worktrees
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        spec1_path = worktrees_dir / "spec-001"
+        spec1_path.mkdir()
+
+        # Mock input to return "no"
+        monkeypatch.setattr("builtins.input", lambda: "no")
+
+        result = cleanup_all_worktrees(temp_git_repo, confirm=True)
+
+        assert result is False
+        assert spec1_path.exists()  # Should still exist
+
+    def test_cleanup_with_confirmation_keyboard_interrupt(
+        self, temp_git_repo: Path, monkeypatch, capsys
+    ):
+        """Cancels cleanup when user presses Ctrl+C (KeyboardInterrupt)."""
+        from core.workspace.finalization import cleanup_all_worktrees
+
+        # Create worktrees
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        spec1_path = worktrees_dir / "spec-001"
+        spec1_path.mkdir()
+
+        # Mock input to raise KeyboardInterrupt
+        def mock_input(prompt=""):
+            raise KeyboardInterrupt()
+
+        monkeypatch.setattr("builtins.input", mock_input)
+
+        result = cleanup_all_worktrees(temp_git_repo, confirm=True)
+
+        assert result is False
+        assert spec1_path.exists()  # Should still exist
+
+        captured = capsys.readouterr()
+        assert "Cancelled" in captured.out
+
+
+class TestFinalizeWorkspaceBranchCoverage:
+    """Additional tests for finalize_workspace to cover missing branches."""
+
+    def test_isolated_mode_merge_choice(self, temp_git_repo: Path, monkeypatch):
+        """Isolated mode returns MERGE when user selects merge."""
+        from core.workspace.finalization import finalize_workspace
+
+        manager = WorktreeManager(temp_git_repo)
+        spec_name = "test-spec"
+
+        # Create worktree
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        # Mock select_menu to return "merge"
+        def mock_select_menu(title, options, allow_quit):
+            return "merge"
+
+        monkeypatch.setattr("core.workspace.finalization.select_menu", mock_select_menu)
+
+        result = finalize_workspace(
+            temp_git_repo,
+            spec_name,
+            manager=manager,
+            auto_continue=False,
+        )
+
+        assert result == WorkspaceChoice.MERGE
+
+    def test_isolated_mode_review_choice(self, temp_git_repo: Path, monkeypatch):
+        """Isolated mode returns REVIEW when user selects review."""
+        from core.workspace.finalization import finalize_workspace
+
+        manager = WorktreeManager(temp_git_repo)
+        spec_name = "test-spec"
+
+        # Create worktree
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        # Mock select_menu to return "review"
+        def mock_select_menu(title, options, allow_quit):
+            return "review"
+
+        monkeypatch.setattr("core.workspace.finalization.select_menu", mock_select_menu)
+
+        result = finalize_workspace(
+            temp_git_repo,
+            spec_name,
+            manager=manager,
+            auto_continue=False,
+        )
+
+        assert result == WorkspaceChoice.REVIEW
+
+    def test_isolated_mode_later_choice(self, temp_git_repo: Path, monkeypatch):
+        """Isolated mode returns LATER when user selects later."""
+        from core.workspace.finalization import finalize_workspace
+
+        manager = WorktreeManager(temp_git_repo)
+        spec_name = "test-spec"
+
+        # Create worktree
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        # Mock select_menu to return "later"
+        def mock_select_menu(title, options, allow_quit):
+            return "later"
+
+        monkeypatch.setattr("core.workspace.finalization.select_menu", mock_select_menu)
+
+        result = finalize_workspace(
+            temp_git_repo,
+            spec_name,
+            manager=manager,
+            auto_continue=False,
+        )
+
+        assert result == WorkspaceChoice.LATER
+
+
+class TestHandleWorkspaceChoiceBranchCoverage:
+    """Additional tests for handle_workspace_choice to cover missing branches."""
+
+    def test_choice_test_without_staging_path(self, temp_git_repo: Path, capsys):
+        """TEST choice shows fallback instructions when staging_path is None."""
+        from core.workspace.finalization import handle_workspace_choice
+
+        manager = WorktreeManager(temp_git_repo)
+        spec_name = "test-spec"
+
+        # Create worktree directory (but not through manager, so no staging_path)
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        handle_workspace_choice(WorkspaceChoice.TEST, temp_git_repo, spec_name, manager)
+
+        captured = capsys.readouterr()
+        assert "TEST YOUR FEATURE" in captured.out
+        # Should show the fallback path
+        assert (
+            str(worktree_path) in captured.out
+            or f".auto-claude/worktrees/tasks/{spec_name}" in captured.out
+        )
+
+    def test_choice_merge_success(self, temp_git_repo: Path, capsys):
+        """MERGE choice shows success message when merge succeeds."""
+        from core.workspace.finalization import handle_workspace_choice
+        from worktree import WorktreeManager
+
+        # Setup a proper isolated workspace with git worktree
+        working_dir, manager, _ = setup_workspace(
+            temp_git_repo,
+            "test-spec",
+            WorkspaceMode.ISOLATED,
+        )
+
+        # Make changes and commit
+        (working_dir / "test.py").write_text("test content", encoding="utf-8")
+        subprocess.run(["git", "add", "."], cwd=working_dir, capture_output=True)
+        subprocess.run(
+            ["git", "commit", "-m", "Add test"], cwd=working_dir, capture_output=True
+        )
+
+        handle_workspace_choice(
+            WorkspaceChoice.MERGE, temp_git_repo, "test-spec", manager
+        )
+
+        captured = capsys.readouterr()
+        assert "Your feature has been added" in captured.out
+
+    def test_choice_later_without_staging_path(self, temp_git_repo: Path, capsys):
+        """LATER choice shows fallback path when staging_path is None."""
+        from core.workspace.finalization import handle_workspace_choice
+
+        manager = WorktreeManager(temp_git_repo)
+        spec_name = "test-spec"
+
+        # Create worktree directory (but not through manager, so no staging_path)
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        handle_workspace_choice(
+            WorkspaceChoice.LATER, temp_git_repo, spec_name, manager
+        )
+
+        captured = capsys.readouterr()
+        assert "No problem!" in captured.out
+        # Should show the fallback path
+        assert (
+            str(worktree_path) in captured.out
+            or f".auto-claude/worktrees/tasks/{spec_name}" in captured.out
+        )
+
+
+class TestDiscardExistingBuildBranchCoverage:
+    """Additional tests for discard_existing_build to cover missing branches."""
+
+    def test_keyboard_interrupt_cancels_discard(
+        self, temp_git_repo: Path, monkeypatch, capsys
+    ):
+        """KeyboardInterrupt during confirmation returns False."""
+        from core.workspace.finalization import discard_existing_build
+
+        spec_name = "test-spec"
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        # Mock input to raise KeyboardInterrupt
+        def mock_input(prompt=""):
+            raise KeyboardInterrupt()
+
+        monkeypatch.setattr("builtins.input", mock_input)
+
+        result = discard_existing_build(temp_git_repo, spec_name)
+
+        assert result is False
+
+        captured = capsys.readouterr()
+        assert "Cancelled" in captured.out
+
+
+class TestCheckExistingBuildBranchCoverage:
+    """Additional tests for check_existing_build to cover missing branches."""
+
+    def test_none_choice_exits(self, temp_git_repo: Path, monkeypatch):
+        """None choice (quit) calls sys.exit(0)."""
+        import sys
+
+        from core.workspace.finalization import check_existing_build
+
+        spec_name = "test-spec"
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        # Mock select_menu to return None (quit)
+        def mock_select_menu(title, options, allow_quit):
+            return None
+
+        monkeypatch.setattr("core.workspace.finalization.select_menu", mock_select_menu)
+
+        # Should raise SystemExit
+        with pytest.raises(SystemExit) as exc_info:
+            check_existing_build(temp_git_repo, spec_name)
+
+        assert exc_info.value.code == 0
+
+    def test_merge_choice_merges_and_returns_false(
+        self, temp_git_repo: Path, monkeypatch
+    ):
+        """Merge choice calls merge_existing_build and returns False."""
+        from unittest.mock import MagicMock
+
+        from core.workspace.finalization import check_existing_build
+
+        spec_name = "test-spec"
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        merge_called = []
+
+        def mock_merge_existing_build(project_dir, spec_name):
+            merge_called.append(spec_name)
+
+        def mock_select_menu(title, options, allow_quit):
+            return "merge"
+
+        monkeypatch.setattr("core.workspace.finalization.select_menu", mock_select_menu)
+
+        # Mock the workspace module import
+        import workspace as ws
+
+        original_merge = getattr(ws, "merge_existing_build", None)
+        ws.merge_existing_build = mock_merge_existing_build
+
+        try:
+            result = check_existing_build(temp_git_repo, spec_name)
+            assert result is False
+            assert spec_name in merge_called
+        finally:
+            if original_merge:
+                ws.merge_existing_build = original_merge
+
+    def test_fresh_choice_discards_and_returns_false(
+        self, temp_git_repo: Path, monkeypatch
+    ):
+        """Fresh choice discards build and returns False (start fresh)."""
+        from core.workspace.finalization import check_existing_build
+
+        spec_name = "test-spec"
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_path = worktrees_dir / spec_name
+        worktree_path.mkdir(parents=True)
+
+        def mock_select_menu(title, options, allow_quit):
+            return "fresh"
+
+        monkeypatch.setattr("core.workspace.finalization.select_menu", mock_select_menu)
+        # Mock input to return "delete" for confirmation
+        monkeypatch.setattr("builtins.input", lambda: "delete")
+
+        result = check_existing_build(temp_git_repo, spec_name)
+        assert result is False, "Fresh choice should return False"
@@ -0,0 +1,638 @@
+#!/usr/bin/env python3
+"""
+Tests for Workspace Models
+==========================
+
+Tests the workspace.py module models including:
+- WorkspaceMode enum
+- WorkspaceChoice enum
+- ParallelMergeTask
+- ParallelMergeResult
+- MergeLock and MergeLockError
+- SpecNumberLock and SpecNumberLockError
+"""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+# Add parent directory to path so we can import the workspace module
+# When co-located at workspace/tests/, we need to add backend to path
+# workspace/tests -> workspace -> core -> backend (4 levels up)
+_backend = Path(__file__).resolve().parent.parent.parent.parent
+sys.path.insert(0, str(_backend))
+
+from core.workspace.models import (
+    MergeLock,
+    MergeLockError,
+    ParallelMergeResult,
+    ParallelMergeTask,
+    SpecNumberLock,
+    SpecNumberLockError,
+)
+from worktree import WorktreeError, WorktreeManager
+
+# Test constant - in the new per-spec architecture, each spec has its own worktree
+# named after the spec itself. This constant is used for test assertions.
+TEST_SPEC_NAME = "test-spec"
+
+
+class TestWorkspaceMode:
+    """Tests for WorkspaceMode enum."""
+
+    def test_isolated_mode(self):
+        """ISOLATED mode value is correct."""
+        from core.workspace.models import WorkspaceMode
+
+        assert WorkspaceMode.ISOLATED.value == "isolated"
+
+    def test_direct_mode(self):
+        """DIRECT mode value is correct."""
+        from core.workspace.models import WorkspaceMode
+
+        assert WorkspaceMode.DIRECT.value == "direct"
+
+
+class TestWorkspaceChoice:
+    """Tests for WorkspaceChoice enum."""
+
+    def test_merge_choice(self):
+        """MERGE choice value is correct."""
+        from core.workspace.models import WorkspaceChoice
+
+        assert WorkspaceChoice.MERGE.value == "merge"
+
+    def test_review_choice(self):
+        """REVIEW choice value is correct."""
+        from core.workspace.models import WorkspaceChoice
+
+        assert WorkspaceChoice.REVIEW.value == "review"
+
+    def test_test_choice(self):
+        """TEST choice value is correct."""
+        from core.workspace.models import WorkspaceChoice
+
+        assert WorkspaceChoice.TEST.value == "test"
+
+    def test_later_choice(self):
+        """LATER choice value is correct."""
+        from core.workspace.models import WorkspaceChoice
+
+        assert WorkspaceChoice.LATER.value == "later"
+
+
+class TestParallelMergeTask:
+    """Tests for ParallelMergeTask dataclass."""
+
+    def test_create_merge_task(self):
+        """ParallelMergeTask can be instantiated with all fields."""
+        task = ParallelMergeTask(
+            file_path="src/example.py",
+            main_content="main content",
+            worktree_content="worktree content",
+            base_content="base content",
+            spec_name="test-spec",
+            project_dir=Path("/project"),
+        )
+
+        assert task.file_path == "src/example.py"
+        assert task.main_content == "main content"
+        assert task.worktree_content == "worktree content"
+        assert task.base_content == "base content"
+        assert task.spec_name == "test-spec"
+        assert task.project_dir == Path("/project")
+
+    def test_merge_task_with_none_base(self):
+        """ParallelMergeTask can have None for base_content."""
+        task = ParallelMergeTask(
+            file_path="src/example.py",
+            main_content="main content",
+            worktree_content="worktree content",
+            base_content=None,
+            spec_name="test-spec",
+            project_dir=Path("/project"),
+        )
+
+        assert task.base_content is None
+
+    def test_merge_task_field_assignment(self):
+        """ParallelMergeTask fields can be reassigned."""
+        task = ParallelMergeTask(
+            file_path="src/example.py",
+            main_content="main",
+            worktree_content="worktree",
+            base_content=None,
+            spec_name="spec-1",
+            project_dir=Path("/project"),
+        )
+
+        task.file_path = "src/updated.py"
+        task.main_content = "updated main"
+        task.worktree_content = "updated worktree"
+        task.base_content = "updated base"
+        task.spec_name = "spec-2"
+        task.project_dir = Path("/updated")
+
+        assert task.file_path == "src/updated.py"
+        assert task.main_content == "updated main"
+        assert task.worktree_content == "updated worktree"
+        assert task.base_content == "updated base"
+        assert task.spec_name == "spec-2"
+        assert task.project_dir == Path("/updated")
+
+
+class TestParallelMergeResult:
+    """Tests for ParallelMergeResult dataclass."""
+
+    def test_create_successful_result(self):
+        """ParallelMergeResult can represent a successful merge."""
+        result = ParallelMergeResult(
+            file_path="src/example.py",
+            merged_content="merged content",
+            success=True,
+            error=None,
+            was_auto_merged=True,
+        )
+
+        assert result.file_path == "src/example.py"
+        assert result.merged_content == "merged content"
+        assert result.success is True
+        assert result.error is None
+        assert result.was_auto_merged is True
+
+    def test_create_failed_result(self):
+        """ParallelMergeResult can represent a failed merge."""
+        result = ParallelMergeResult(
+            file_path="src/example.py",
+            merged_content=None,
+            success=False,
+            error="Merge conflict occurred",
+            was_auto_merged=False,
+        )
+
+        assert result.file_path == "src/example.py"
+        assert result.merged_content is None
+        assert result.success is False
+        assert result.error == "Merge conflict occurred"
+        assert result.was_auto_merged is False
+
+    def test_result_default_values(self):
+        """ParallelMergeResult has correct default values."""
+        result = ParallelMergeResult(
+            file_path="src/example.py",
+            merged_content="content",
+            success=True,
+        )
+
+        assert result.error is None
+        assert result.was_auto_merged is False
+
+    def test_result_field_assignment(self):
+        """ParallelMergeResult fields can be reassigned."""
+        result = ParallelMergeResult(
+            file_path="src/example.py",
+            merged_content="merged",
+            success=True,
+            error=None,
+            was_auto_merged=False,
+        )
+
+        result.file_path = "src/updated.py"
+        result.merged_content = "updated merged"
+        result.success = False
+        result.error = "New error"
+        result.was_auto_merged = True
+
+        assert result.file_path == "src/updated.py"
+        assert result.merged_content == "updated merged"
+        assert result.success is False
+        assert result.error == "New error"
+        assert result.was_auto_merged is True
+
+
+class TestMergeLockError:
+    """Tests for MergeLockError exception."""
+
+    def test_merge_lock_error_creation(self):
+        """MergeLockError can be instantiated with a message."""
+        error = MergeLockError("Could not acquire lock")
+        assert str(error) == "Could not acquire lock"
+
+    def test_merge_lock_error_is_exception(self):
+        """MergeLockError is an Exception subclass."""
+        error = MergeLockError("test")
+        assert isinstance(error, Exception)
+        assert isinstance(error, MergeLockError)
+
+    def test_raise_merge_lock_error(self):
+        """MergeLockError can be raised and caught."""
+        with pytest.raises(MergeLockError) as exc_info:
+            raise MergeLockError("Lock timeout")
+            assert str(exc_info.value) == "Lock timeout"
+
+
+class TestMergeLock:
+    """Tests for MergeLock context manager."""
+
+    def test_merge_lock_initialization(self, temp_git_repo: Path):
+        """MergeLock initializes with correct paths."""
+        lock = MergeLock(temp_git_repo, "test-spec")
+
+        assert lock.project_dir == temp_git_repo
+        assert lock.spec_name == "test-spec"
+        assert lock.lock_dir == temp_git_repo / ".auto-claude" / ".locks"
+        assert lock.lock_file == lock.lock_dir / "merge-test-spec.lock"
+        assert lock.acquired is False
+
+    def test_merge_lock_acquire_and_release(self, temp_git_repo: Path):
+        """MergeLock can be acquired and released."""
+        lock = MergeLock(temp_git_repo, "test-spec")
+
+        with lock:
+            assert lock.acquired is True
+            assert lock.lock_file.exists()
+
+        # After context, lock should be released
+        assert lock.lock_file.exists() is False
+
+    def test_merge_lock_creates_lock_dir(self, temp_git_repo: Path):
+        """MergeLock creates lock directory if it doesn't exist."""
+        lock = MergeLock(temp_git_repo, "test-spec")
+
+        # Remove lock dir if it exists
+        if lock.lock_dir.exists():
+            lock.lock_dir.rmdir()
+
+        with lock:
+            assert lock.lock_dir.exists()
+
+    def test_merge_lock_writes_pid(self, temp_git_repo: Path):
+        """MergeLock writes current PID to lock file."""
+        lock = MergeLock(temp_git_repo, "test-spec")
+
+        with lock:
+            pid_content = lock.lock_file.read_text(encoding="utf-8").strip()
+            assert pid_content == str(os.getpid())
+
+    @pytest.mark.slow
+    def test_merge_lock_timeout_on_contention(self, temp_git_repo: Path):
+        """MergeLock raises MergeLockError when lock is held by another process."""
+        lock1 = MergeLock(temp_git_repo, "test-spec")
+
+        # Acquire first lock
+        lock1.__enter__()
+
+        try:
+            # Create a second lock for the same spec
+            lock2 = MergeLock(temp_git_repo, "test-spec")
+
+            # This should timeout because lock1 holds the lock
+            with pytest.raises(MergeLockError) as exc_info:
+                lock2.__enter__()
+
+            assert "Could not acquire merge lock" in str(exc_info.value)
+            assert "test-spec" in str(exc_info.value)
+            assert "after 30s" in str(exc_info.value)
+        finally:
+            lock1.__exit__(None, None, None)
+
+    def test_merge_lock_removes_stale_lock(self, temp_git_repo: Path):
+        """MergeLock removes stale lock from dead process."""
+        lock1 = MergeLock(temp_git_repo, "test-spec")
+
+        with lock1:
+            # Write a fake PID that doesn't exist
+            fake_pid = 999999
+            lock1.lock_file.write_text(str(fake_pid), encoding="utf-8")
+
+            # Create a new lock - it should remove the stale lock
+            lock2 = MergeLock(temp_git_repo, "test-spec")
+            with lock2:
+                assert lock2.acquired is True
+
+    def test_merge_lock_handles_invalid_pid(self, temp_git_repo: Path):
+        """MergeLock handles invalid PID in lock file."""
+        lock1 = MergeLock(temp_git_repo, "test-spec")
+
+        with lock1:
+            # Write invalid content to lock file
+            lock1.lock_file.write_text("invalid-pid", encoding="utf-8")
+
+            # Create a new lock - it should remove the invalid lock
+            lock2 = MergeLock(temp_git_repo, "test-spec")
+            with lock2:
+                assert lock2.acquired is True
+
+    def test_merge_lock_cleanup_on_exception(self, temp_git_repo: Path):
+        """MergeLock releases lock even if exception occurs in context."""
+        lock = MergeLock(temp_git_repo, "test-spec")
+
+        try:
+            with lock:
+                assert lock.acquired is True
+                raise ValueError("Test exception")
+        except ValueError:
+            pass
+
+        # Lock should be released despite exception
+        assert lock.lock_file.exists() is False
+
+    def test_merge_lock_idempotent_release(self, temp_git_repo: Path):
+        """MergeLock __exit__ can be called multiple times safely."""
+        lock = MergeLock(temp_git_repo, "test-spec")
+
+        with lock:
+            pass
+
+        # Call __exit__ again - should not raise
+        lock.__exit__(None, None, None)
+        lock.__exit__(None, None, None)
+
+    def test_merge_lock_different_specs_dont_conflict(self, temp_git_repo: Path):
+        """MergeLock for different specs can be held simultaneously."""
+        lock1 = MergeLock(temp_git_repo, "spec-1")
+        lock2 = MergeLock(temp_git_repo, "spec-2")
+
+        with lock1:
+            with lock2:
+                assert lock1.acquired is True
+                assert lock2.acquired is True
+                assert lock1.lock_file != lock2.lock_file
+
+
+class TestSpecNumberLockError:
+    """Tests for SpecNumberLockError exception."""
+
+    def test_spec_number_lock_error_creation(self):
+        """SpecNumberLockError can be instantiated with a message."""
+        error = SpecNumberLockError("Could not acquire spec numbering lock")
+        assert str(error) == "Could not acquire spec numbering lock"
+
+    def test_spec_number_lock_error_is_exception(self):
+        """SpecNumberLockError is an Exception subclass."""
+        error = SpecNumberLockError("test")
+        assert isinstance(error, Exception)
+        assert isinstance(error, SpecNumberLockError)
+
+    def test_raise_spec_number_lock_error(self):
+        """SpecNumberLockError can be raised and caught."""
+        with pytest.raises(SpecNumberLockError) as exc_info:
+            raise SpecNumberLockError("Lock timeout")
+            assert str(exc_info.value) == "Lock timeout"
+
+
+class TestSpecNumberLock:
+    """Tests for SpecNumberLock context manager."""
+
+    def test_spec_number_lock_initialization(self, temp_git_repo: Path):
+        """SpecNumberLock initializes with correct paths."""
+        lock = SpecNumberLock(temp_git_repo)
+
+        assert lock.project_dir == temp_git_repo
+        assert lock.lock_dir == temp_git_repo / ".auto-claude" / ".locks"
+        assert lock.lock_file == lock.lock_dir / "spec-numbering.lock"
+        assert lock.acquired is False
+        assert lock._global_max is None
+
+    def test_spec_number_lock_acquire_and_release(self, temp_git_repo: Path):
+        """SpecNumberLock can be acquired and released."""
+        lock = SpecNumberLock(temp_git_repo)
+
+        with lock:
+            assert lock.acquired is True
+            assert lock.lock_file.exists()
+
+        # After context, lock should be released
+        assert lock.lock_file.exists() is False
+
+    def test_spec_number_lock_creates_lock_dir(self, temp_git_repo: Path):
+        """SpecNumberLock creates lock directory if it doesn't exist."""
+        lock = SpecNumberLock(temp_git_repo)
+
+        # Remove lock dir if it exists
+        if lock.lock_dir.exists():
+            lock.lock_dir.rmdir()
+
+        with lock:
+            assert lock.lock_dir.exists()
+
+    def test_spec_number_lock_writes_pid(self, temp_git_repo: Path):
+        """SpecNumberLock writes current PID to lock file."""
+        lock = SpecNumberLock(temp_git_repo)
+
+        with lock:
+            pid_content = lock.lock_file.read_text(encoding="utf-8").strip()
+            assert pid_content == str(os.getpid())
+
+    def test_get_next_spec_number_no_existing_specs(self, temp_git_repo: Path):
+        """get_next_spec_number returns 1 when no specs exist."""
+        lock = SpecNumberLock(temp_git_repo)
+
+        with lock:
+            next_num = lock.get_next_spec_number()
+            assert next_num == 1
+
+    def test_get_next_spec_number_with_existing_specs(self, temp_git_repo: Path):
+        """get_next_spec_number returns max existing spec number + 1."""
+        # Create spec directories
+        specs_dir = temp_git_repo / ".auto-claude" / "specs"
+        specs_dir.mkdir(parents=True)
+        (specs_dir / "001-first").mkdir()
+        (specs_dir / "003-third").mkdir()
+
+        lock = SpecNumberLock(temp_git_repo)
+
+        with lock:
+            next_num = lock.get_next_spec_number()
+            assert next_num == 4
+
+    def test_get_next_spec_number_caches_result(self, temp_git_repo: Path):
+        """get_next_spec_number caches the global max."""
+        specs_dir = temp_git_repo / ".auto-claude" / "specs"
+        specs_dir.mkdir(parents=True)
+        (specs_dir / "005-test").mkdir()
+
+        lock = SpecNumberLock(temp_git_repo)
+
+        with lock:
+            next_num1 = lock.get_next_spec_number()
+            next_num2 = lock.get_next_spec_number()
+
+            # Should return the same value (cached)
+            assert next_num1 == next_num2 == 6
+            assert lock._global_max == 5
+
+    def test_get_next_spec_number_requires_lock(self, temp_git_repo: Path):
+        """get_next_spec_number raises SpecNumberLockError if lock not acquired."""
+        lock = SpecNumberLock(temp_git_repo)
+
+        with pytest.raises(SpecNumberLockError) as exc_info:
+            lock.get_next_spec_number()
+
+        assert "Lock must be acquired" in str(exc_info.value)
+
+    def test_get_next_spec_number_scans_worktrees(self, temp_git_repo: Path):
+        """get_next_spec_number scans all worktree spec directories."""
+        # Create main project specs
+        main_specs = temp_git_repo / ".auto-claude" / "specs"
+        main_specs.mkdir(parents=True)
+        (main_specs / "002-main").mkdir()
+
+        # Create worktree with specs
+        worktrees_dir = temp_git_repo / ".auto-claude" / "worktrees" / "tasks"
+        worktrees_dir.mkdir(parents=True)
+        worktree_spec_dir = worktrees_dir / "test-worktree" / ".auto-claude" / "specs"
+        worktree_spec_dir.mkdir(parents=True)
+        (worktree_spec_dir / "005-worktree").mkdir()
+
+        lock = SpecNumberLock(temp_git_repo)
+
+        with lock:
+            next_num = lock.get_next_spec_number()
+            # Should find max of 2 and 5, return 6
+            assert next_num == 6
+
+    def test_scan_specs_dir_nonexistent(self, temp_git_repo: Path):
+        """_scan_specs_dir returns 0 for nonexistent directory."""
+        lock = SpecNumberLock(temp_git_repo)
+
+        with lock:
+            # Use a path inside temp_dir that doesn't exist
+            nonexistent = temp_git_repo / "this_does_not_exist_specs"
+            result = lock._scan_specs_dir(nonexistent)
+            assert result == 0
+
+    def test_scan_specs_dir_ignores_invalid_names(self, temp_git_repo: Path):
+        """_scan_specs_dir ignores directories with invalid spec names."""
+        specs_dir = temp_git_repo / ".auto-claude" / "specs"
+        specs_dir.mkdir(parents=True)
+        (specs_dir / "001-valid").mkdir()
+        (specs_dir / "invalid-name").mkdir()
+        (specs_dir / "abc").mkdir()
+        (specs_dir / "100-valid").mkdir()
+
+        lock = SpecNumberLock(temp_git_repo)
+
+        with lock:
+            result = lock._scan_specs_dir(specs_dir)
+            # Should only count 001 and 100
+            assert result == 100
+
+    @pytest.mark.slow
+    def test_spec_number_lock_timeout_on_contention(self, temp_git_repo: Path):
+        """SpecNumberLock raises SpecNumberLockError when lock is held."""
+        lock1 = SpecNumberLock(temp_git_repo)
+
+        # Acquire first lock
+        lock1.__enter__()
+
+        try:
+            # Create a second lock
+            lock2 = SpecNumberLock(temp_git_repo)
+
+            # This should timeout because lock1 holds the lock
+            with pytest.raises(SpecNumberLockError) as exc_info:
+                lock2.__enter__()
+
+            assert "Could not acquire spec numbering lock" in str(exc_info.value)
+            assert "after 30s" in str(exc_info.value)
+        finally:
+            lock1.__exit__(None, None, None)
+
+    def test_spec_number_lock_removes_stale_lock(self, temp_git_repo: Path):
+        """SpecNumberLock removes stale lock from dead process."""
+        lock1 = SpecNumberLock(temp_git_repo)
+
+        with lock1:
+            # Write a fake PID that doesn't exist
+            fake_pid = 999999
+            lock1.lock_file.write_text(str(fake_pid), encoding="utf-8")
+
+            # Create a new lock - it should remove the stale lock
+            lock2 = SpecNumberLock(temp_git_repo)
+            with lock2:
+                assert lock2.acquired is True
+
+    def test_spec_number_lock_handles_invalid_pid(self, temp_git_repo: Path):
+        """SpecNumberLock handles invalid PID in lock file."""
+        lock1 = SpecNumberLock(temp_git_repo)
+
+        with lock1:
+            # Write invalid content to lock file
+            lock1.lock_file.write_text("invalid-pid", encoding="utf-8")
+
+            # Create a new lock - it should remove the invalid lock
+            lock2 = SpecNumberLock(temp_git_repo)
+            with lock2:
+                assert lock2.acquired is True
+
+    def test_spec_number_lock_cleanup_on_exception(self, temp_git_repo: Path):
+        """SpecNumberLock releases lock even if exception occurs in context."""
+        lock = SpecNumberLock(temp_git_repo)
+
+        try:
+            with lock:
+                assert lock.acquired is True
+                raise ValueError("Test exception")
+        except ValueError:
+            pass
+
+        # Lock should be released despite exception
+        assert lock.lock_file.exists() is False
+
+    def test_spec_number_lock_idempotent_release(self, temp_git_repo: Path):
+        """SpecNumberLock __exit__ can be called multiple times safely."""
+        lock = SpecNumberLock(temp_git_repo)
+
+        with lock:
+            pass
+
+        # Call __exit__ again - should not raise
+        lock.__exit__(None, None, None)
+        lock.__exit__(None, None, None)
+
+    def test_spec_number_lock_returns_self(self, temp_git_repo: Path):
+        """SpecNumberLock __enter__ returns self."""
+        lock = SpecNumberLock(temp_git_repo)
+
+        with lock as entered_lock:
+            assert entered_lock is lock
+
+    def test_merge_success_returns_true(self, temp_git_repo: Path):
+        """Successful merge returns True (ACS-163 verification)."""
+        manager = WorktreeManager(temp_git_repo)
+        manager.setup()
+
+        # Create a worktree with non-conflicting changes
+        worker_info = manager.create_worktree("worker-spec")
+        (worker_info.path / "worker-file.txt").write_text(
+            "worker content", encoding="utf-8"
+        )
+        subprocess.run(["git", "add", "."], cwd=worker_info.path, capture_output=True)
+        subprocess.run(
+            ["git", "commit", "-m", "Worker commit"],
+            cwd=worker_info.path,
+            capture_output=True,
+        )
+
+        # Merge should succeed
+        result = manager.merge_worktree("worker-spec", delete_after=False)
+
+        assert result is True
+
+        # Verify the file was merged into base branch
+        subprocess.run(
+            ["git", "checkout", manager.base_branch],
+            cwd=temp_git_repo,
+            capture_output=True,
+        )
+        assert (temp_git_repo / "worker-file.txt").exists(), (
+            "Merged file should exist in base branch"
+        )
+        merged_content = (temp_git_repo / "worker-file.txt").read_text(encoding="utf-8")
+        assert merged_content == "worker content", (
+            "Merged file should have worktree content"
+        )
@@ -1,539 +1,31 @@
 #!/usr/bin/env python3
 """
-Tests for Workspace Selection and Management
-=============================================
+Tests for Workspace Rebase Operations
+======================================

-Tests the workspace.py module functionality including:
- Workspace mode selection (isolated vs direct)
- Uncommitted changes detection
- Workspace setup
- Build finalization workflows
+Tests the rebase functionality including:
+- Rebase detection (_check_git_conflicts)
+- Spec branch rebase operations
+- Rebase integration tests
+- Rebase error handling
 """

+import json
+import os
+import shutil
 import subprocess
+import sys
 from pathlib import Path

 import pytest
-from workspace import (
-    WorkspaceChoice,
-    WorkspaceMode,
-    get_current_branch,
-    get_existing_build_worktree,
-    has_uncommitted_changes,
-    setup_workspace,
-)
-from worktree import WorktreeManager
+from worktree import WorktreeError, WorktreeManager

 # Test constant - in the new per-spec architecture, each spec has its own worktree
 # named after the spec itself. This constant is used for test assertions.
 TEST_SPEC_NAME = "test-spec"


-class TestWorkspaceMode:
-    """Tests for WorkspaceMode enum."""
-
-    def test_isolated_mode(self):
-        """ISOLATED mode value is correct."""
-        assert WorkspaceMode.ISOLATED.value == "isolated"
-
-    def test_direct_mode(self):
-        """DIRECT mode value is correct."""
-        assert WorkspaceMode.DIRECT.value == "direct"
-
-
-class TestWorkspaceChoice:
-    """Tests for WorkspaceChoice enum."""
-
-    def test_merge_choice(self):
-        """MERGE choice value is correct."""
-        assert WorkspaceChoice.MERGE.value == "merge"
-
-    def test_review_choice(self):
-        """REVIEW choice value is correct."""
-        assert WorkspaceChoice.REVIEW.value == "review"
-
-    def test_test_choice(self):
-        """TEST choice value is correct."""
-        assert WorkspaceChoice.TEST.value == "test"
-
-    def test_later_choice(self):
-        """LATER choice value is correct."""
-        assert WorkspaceChoice.LATER.value == "later"
-
-
-class TestHasUncommittedChanges:
-    """Tests for uncommitted changes detection."""
-
-    def test_clean_repo_no_changes(self, temp_git_repo: Path):
-        """Clean repo returns False."""
-        result = has_uncommitted_changes(temp_git_repo)
-        assert result is False
-
-    def test_untracked_file_has_changes(self, temp_git_repo: Path):
-        """Untracked file counts as changes."""
-        (temp_git_repo / "new_file.txt").write_text("content")
-
-        result = has_uncommitted_changes(temp_git_repo)
-        assert result is True
-
-    def test_modified_file_has_changes(self, temp_git_repo: Path):
-        """Modified tracked file counts as changes."""
-        (temp_git_repo / "README.md").write_text("modified content")
-
-        result = has_uncommitted_changes(temp_git_repo)
-        assert result is True
-
-    def test_staged_file_has_changes(self, temp_git_repo: Path):
-        """Staged file counts as changes."""
-        (temp_git_repo / "README.md").write_text("modified")
-        subprocess.run(["git", "add", "README.md"], cwd=temp_git_repo, capture_output=True)
-
-        result = has_uncommitted_changes(temp_git_repo)
-        assert result is True
-
-
-class TestGetCurrentBranch:
-    """Tests for current branch detection."""
-
-    def test_gets_main_branch(self, temp_git_repo: Path):
-        """Gets the main/master branch."""
-        branch = get_current_branch(temp_git_repo)
-
-        # Could be main or master depending on git config
-        assert branch in ["main", "master"]
-
-    def test_gets_feature_branch(self, temp_git_repo: Path):
-        """Gets feature branch name."""
-        subprocess.run(
-            ["git", "checkout", "-b", "feature/test-branch"],
-            cwd=temp_git_repo, capture_output=True
-        )
-
-        branch = get_current_branch(temp_git_repo)
-        assert branch == "feature/test-branch"
-
-
-class TestGetExistingBuildWorktree:
-    """Tests for existing build worktree detection."""
-
-    def test_no_existing_worktree(self, temp_git_repo: Path):
-        """Returns None when no worktree exists."""
-        result = get_existing_build_worktree(temp_git_repo, "test-spec")
-        assert result is None
-
-    def test_existing_worktree(self, temp_git_repo: Path):
-        """Returns path when worktree exists."""
-        # Create the worktree directory structure (per-spec architecture)
-        worktree_path = temp_git_repo / ".worktrees" / TEST_SPEC_NAME
-        worktree_path.mkdir(parents=True)
-
-        result = get_existing_build_worktree(temp_git_repo, TEST_SPEC_NAME)
-        assert result == worktree_path
-
-
-class TestSetupWorkspace:
-    """Tests for workspace setup."""
-
-    def test_setup_direct_mode(self, temp_git_repo: Path):
-        """Direct mode returns project dir and no manager."""
-        working_dir, manager, _ = setup_workspace(
-            temp_git_repo,
-            "test-spec",
-            WorkspaceMode.DIRECT,
-        )
-
-        assert working_dir == temp_git_repo
-        assert manager is None
-
-    def test_setup_isolated_mode(self, temp_git_repo: Path):
-        """Isolated mode creates worktree and returns manager."""
-        working_dir, manager, _ = setup_workspace(
-            temp_git_repo,
-            TEST_SPEC_NAME,
-            WorkspaceMode.ISOLATED,
-        )
-
-        assert working_dir != temp_git_repo
-        assert manager is not None
-        assert working_dir.exists()
-        # Per-spec architecture: worktree is named after the spec
-        assert working_dir.name == TEST_SPEC_NAME
-
-    def test_setup_isolated_creates_worktrees_dir(self, temp_git_repo: Path):
-        """Isolated mode creates worktrees directory."""
-        setup_workspace(
-            temp_git_repo,
-            "test-spec",
-            WorkspaceMode.ISOLATED,
-        )
-
-        assert (temp_git_repo / ".auto-claude" / "worktrees" / "tasks").exists()
-
-
-class TestWorkspaceUtilities:
-    """Tests for workspace utility functions."""
-
-    def test_per_spec_worktree_naming(self, temp_git_repo: Path):
-        """Per-spec architecture uses spec name for worktree directory."""
-        spec_name = "my-spec-001"
-        working_dir, manager, _ = setup_workspace(
-            temp_git_repo,
-            spec_name,
-            WorkspaceMode.ISOLATED,
-        )
-
-        # Worktree should be named after the spec
-        assert working_dir.name == spec_name
-        # New path: .auto-claude/worktrees/tasks/{spec_name}
-        assert working_dir.parent.name == "tasks"
-
-
-class TestWorkspaceIntegration:
-    """Integration tests for workspace management."""
-
-    def test_isolated_workflow(self, temp_git_repo: Path):
-        """Full isolated workflow: setup -> work -> finalize."""
-        # Setup isolated workspace
-        working_dir, manager, _ = setup_workspace(
-            temp_git_repo,
-            "test-spec",
-            WorkspaceMode.ISOLATED,
-        )
-
-        # Make changes in workspace
-        (working_dir / "feature.py").write_text("# New feature\n")
-
-        # Verify changes are in workspace
-        assert (working_dir / "feature.py").exists()
-
-        # Verify changes are NOT in main project
-        assert not (temp_git_repo / "feature.py").exists()
-
-    def test_direct_workflow(self, temp_git_repo: Path):
-        """Full direct workflow: setup -> work."""
-        # Setup direct workspace
-        working_dir, manager, _ = setup_workspace(
-            temp_git_repo,
-            "test-spec",
-            WorkspaceMode.DIRECT,
-        )
-
-        # Working dir is the project dir
-        assert working_dir == temp_git_repo
-
-        # Make changes directly
-        (working_dir / "feature.py").write_text("# New feature\n")
-
-        # Changes are in main project
-        assert (temp_git_repo / "feature.py").exists()
-
-    def test_isolated_merge(self, temp_git_repo: Path):
-        """Can merge isolated workspace back to main."""
-        # Setup
-        working_dir, manager, _ = setup_workspace(
-            temp_git_repo,
-            "test-spec",
-            WorkspaceMode.ISOLATED,
-        )
-
-        # Make changes and commit using git directly
-        (working_dir / "feature.py").write_text("# New feature\n")
-        subprocess.run(["git", "add", "."], cwd=working_dir, capture_output=True)
-        subprocess.run(
-            ["git", "commit", "-m", "Add feature"],
-            cwd=working_dir, capture_output=True
-        )
-
-        # Merge back using merge_worktree
-        result = manager.merge_worktree("test-spec", delete_after=False)
-
-        assert result is True
-
-        # Check changes are in main
-        subprocess.run(
-            ["git", "checkout", manager.base_branch],
-            cwd=temp_git_repo, capture_output=True
-        )
-        assert (temp_git_repo / "feature.py").exists()
-
-
-class TestWorkspaceCleanup:
-    """Tests for workspace cleanup."""
-
-    def test_cleanup_after_merge(self, temp_git_repo: Path):
-        """Workspace is cleaned up after merge with delete_after=True."""
-        working_dir, manager, _ = setup_workspace(
-            temp_git_repo,
-            "test-spec",
-            WorkspaceMode.ISOLATED,
-        )
-
-        # Commit changes using git directly
-        (working_dir / "test.py").write_text("test")
-        subprocess.run(["git", "add", "."], cwd=working_dir, capture_output=True)
-        subprocess.run(
-            ["git", "commit", "-m", "Test"],
-            cwd=working_dir, capture_output=True
-        )
-
-        # Merge with cleanup
-        manager.merge_worktree("test-spec", delete_after=True)
-
-        # Workspace should be removed
-        assert not working_dir.exists()
-
-    def test_workspace_preserved_after_merge_no_delete(self, temp_git_repo: Path):
-        """Workspace preserved after merge with delete_after=False."""
-        working_dir, manager, _ = setup_workspace(
-            temp_git_repo,
-            "test-spec",
-            WorkspaceMode.ISOLATED,
-        )
-
-        # Commit changes using git directly
-        (working_dir / "test.py").write_text("test")
-        subprocess.run(["git", "add", "."], cwd=working_dir, capture_output=True)
-        subprocess.run(
-            ["git", "commit", "-m", "Test"],
-            cwd=working_dir, capture_output=True
-        )
-
-        # Merge without cleanup
-        manager.merge_worktree("test-spec", delete_after=False)
-
-        # Workspace should still exist
-        assert working_dir.exists()
-
-
-class TestWorkspaceReuse:
-    """Tests for reusing existing workspaces."""
-
-    def test_reuse_existing_workspace(self, temp_git_repo: Path):
-        """Can reuse existing workspace on second setup."""
-        # First setup
-        working_dir1, manager1, _ = setup_workspace(
-            temp_git_repo,
-            "test-spec",
-            WorkspaceMode.ISOLATED,
-        )
-
-        # Add a marker file
-        (working_dir1 / "marker.txt").write_text("marker")
-
-        # Second setup (should reuse)
-        working_dir2, manager2, _ = setup_workspace(
-            temp_git_repo,
-            "test-spec",
-            WorkspaceMode.ISOLATED,
-        )
-
-        # Should be the same directory
-        assert working_dir1 == working_dir2
-
-        # Marker should still exist
-        assert (working_dir2 / "marker.txt").exists()
-
-
-class TestWorkspaceErrors:
-    """Tests for workspace error handling."""
-
-    def test_setup_non_git_directory(self, temp_dir: Path):
-        """Handles non-git directories gracefully."""
-        with pytest.raises(Exception):
-            # This should fail because temp_dir is not a git repo
-            setup_workspace(
-                temp_dir,
-                "test-spec",
-                WorkspaceMode.ISOLATED,
-            )
-
-
-class TestPerSpecWorktreeName:
-    """Tests for per-spec worktree naming (new architecture)."""
-
-    def test_worktree_named_after_spec(self, temp_git_repo: Path):
-        """Worktree is named after the spec."""
-        spec_name = "spec-1"
-        working_dir, _, _ = setup_workspace(
-            temp_git_repo,
-            spec_name,
-            WorkspaceMode.ISOLATED,
-        )
-
-        # Per-spec architecture: worktree directory matches spec name
-        assert working_dir.name == spec_name
-
-    def test_different_specs_get_different_worktrees(self, temp_git_repo: Path):
-        """Different specs create separate worktrees."""
-        working_dir1, _, _ = setup_workspace(
-            temp_git_repo,
-            "spec-1",
-            WorkspaceMode.ISOLATED,
-        )
-
-        working_dir2, _, _ = setup_workspace(
-            temp_git_repo,
-            "spec-2",
-            WorkspaceMode.ISOLATED,
-        )
-
-        # Each spec has its own worktree
-        assert working_dir1.name == "spec-1"
-        assert working_dir2.name == "spec-2"
-        assert working_dir1 != working_dir2
-
-    def test_worktree_path_in_worktrees_dir(self, temp_git_repo: Path):
-        """Worktree is created in worktrees directory."""
-        working_dir, _, _ = setup_workspace(
-            temp_git_repo,
-            "test-spec",
-            WorkspaceMode.ISOLATED,
-        )
-
-        # New path: .auto-claude/worktrees/tasks/{spec_name}
-        assert "worktrees" in str(working_dir)
-        assert working_dir.parent.name == "tasks"
-
-
-class TestConflictInfoDisplay:
-    """Tests for conflict info display function (ACS-179)."""
-
-    def test_print_conflict_info_with_string_list(self, capsys):
-        """print_conflict_info handles string list of file paths (ACS-179)."""
-        from core.workspace.display import print_conflict_info
-
-        result = {
-            "conflicts": ["file1.txt", "file2.py", "file3.js"]
-        }
-
-        print_conflict_info(result)
-
-        captured = capsys.readouterr()
-        assert "3 file" in captured.out
-        assert "file1.txt" in captured.out
-        assert "file2.py" in captured.out
-        assert "file3.js" in captured.out
-        assert "git add" in captured.out
-
-    def test_print_conflict_info_with_dict_list(self, capsys):
-        """print_conflict_info handles dict list with file/reason/severity (ACS-179)."""
-        from core.workspace.display import print_conflict_info
-
-        result = {
-            "conflicts": [
-                {"file": "file1.txt", "reason": "Syntax error", "severity": "high"},
-                {"file": "file2.py", "reason": "Merge conflict", "severity": "medium"},
-                {"file": "file3.js", "reason": "Unknown error", "severity": "low"},
-            ]
-        }
-
-        print_conflict_info(result)
-
-        captured = capsys.readouterr()
-        assert "3 file" in captured.out
-        assert "file1.txt" in captured.out
-        assert "file2.py" in captured.out
-        assert "file3.js" in captured.out
-        assert "Syntax error" in captured.out
-        assert "Merge conflict" in captured.out
-        # Verify severity emoji indicators
-        assert "🔴" in captured.out  # High severity
-        assert "🟡" in captured.out  # Medium severity
-
-    def test_print_conflict_info_mixed_formats(self, capsys):
-        """print_conflict_info handles mixed string and dict conflicts (ACS-179)."""
-        from core.workspace.display import print_conflict_info
-
-        result = {
-            "conflicts": [
-                "simple-file.txt",
-                {"file": "complex-file.py", "reason": "AI merge failed", "severity": "high"},
-            ]
-        }
-
-        print_conflict_info(result)
-
-        captured = capsys.readouterr()
-        assert "2 file" in captured.out
-        assert "simple-file.txt" in captured.out
-        assert "complex-file.py" in captured.out
-        assert "AI merge failed" in captured.out
-
-
-class TestMergeErrorHandling:
-    """Tests for merge error handling (ACS-163)."""
-
-    def test_merge_failure_returns_false_immediately(self, temp_git_repo: Path):
-        """Failed merge returns False without falling through (ACS-163)."""
-        manager = WorktreeManager(temp_git_repo)
-        manager.setup()
-
-        # Create a worktree with changes
-        worker_info = manager.create_worktree("worker-spec")
-        (worker_info.path / "worker-file.txt").write_text("worker content")
-        subprocess.run(["git", "add", "."], cwd=worker_info.path, capture_output=True)
-        subprocess.run(
-            ["git", "commit", "-m", "Worker commit"],
-            cwd=worker_info.path, capture_output=True
-        )
-
-        # Create a conflicting change on main
-        subprocess.run(["git", "checkout", manager.base_branch], cwd=temp_git_repo, capture_output=True)
-        (temp_git_repo / "worker-file.txt").write_text("main content")
-        subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
-        subprocess.run(
-            ["git", "commit", "-m", "Main commit"],
-            cwd=temp_git_repo, capture_output=True
-        )
-
-        # Merge should fail (conflict) and return False
-        # This tests the fix for ACS-163 where failed merge would fall through
-        result = manager.merge_worktree("worker-spec", delete_after=False)
-
-        # Should return False on merge conflict
-        assert result is False
-
-        # Verify side effects: base branch content is unchanged
-        subprocess.run(["git", "checkout", manager.base_branch], cwd=temp_git_repo, capture_output=True)
-        base_content = (temp_git_repo / "worker-file.txt").read_text()
-        assert base_content == "main content", "Base branch should be unchanged after failed merge"
-
-        # Verify worktree still exists (delete_after=False)
-        assert worker_info.path.exists(), "Worktree should still exist after failed merge"
-
-        # Verify worktree content is unchanged
-        worktree_content = (worker_info.path / "worker-file.txt").read_text()
-        assert worktree_content == "worker content", "Worktree content should be unchanged"
-
-    def test_merge_success_returns_true(self, temp_git_repo: Path):
-        """Successful merge returns True (ACS-163 verification)."""
-        manager = WorktreeManager(temp_git_repo)
-        manager.setup()
-
-        # Create a worktree with non-conflicting changes
-        worker_info = manager.create_worktree("worker-spec")
-        (worker_info.path / "worker-file.txt").write_text("worker content")
-        subprocess.run(["git", "add", "."], cwd=worker_info.path, capture_output=True)
-        subprocess.run(
-            ["git", "commit", "-m", "Worker commit"],
-            cwd=worker_info.path, capture_output=True
-        )
-
-        # Merge should succeed
-        result = manager.merge_worktree("worker-spec", delete_after=False)
-
-        assert result is True
-
-        # Verify the file was merged into base branch
-        subprocess.run(["git", "checkout", manager.base_branch], cwd=temp_git_repo, capture_output=True)
-        assert (temp_git_repo / "worker-file.txt").exists(), "Merged file should exist in base branch"
-        merged_content = (temp_git_repo / "worker-file.txt").read_text()
-        assert merged_content == "worker content", "Merged file should have worktree content"
-
-
 class TestRebaseDetection:
-    """Tests for automatic rebase detection (ACS-224)."""
-
    def test_check_git_conflicts_detects_branch_behind(self, temp_git_repo: Path):
        """_check_git_conflicts detects when spec branch is behind base branch (ACS-224)."""
        from core.workspace import _check_git_conflicts
@@ -547,7 +39,7 @@ class TestRebaseDetection:
        )

        # Add a commit to spec branch
-        (temp_git_repo / "spec-file.txt").write_text("spec content")
+        (temp_git_repo / "spec-file.txt").write_text("spec content", encoding="utf-8")
        subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
        subprocess.run(
            ["git", "commit", "-m", "Spec commit"],
@@ -561,7 +53,7 @@ class TestRebaseDetection:
            cwd=temp_git_repo,
            capture_output=True,
        )
-        (temp_git_repo / "main-file.txt").write_text("main content")
+        (temp_git_repo / "main-file.txt").write_text("main content", encoding="utf-8")
        subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
        subprocess.run(
            ["git", "commit", "-m", "Main commit after spec"],
@@ -574,7 +66,9 @@ class TestRebaseDetection:

        assert result is not None
        assert result.get("needs_rebase") is True, "Should detect branch is behind"
-        assert result.get("commits_behind") == 1, "Should count commits behind correctly"
+        assert result.get("commits_behind") == 1, (
+            "Should count commits behind correctly"
+        )
        assert result.get("spec_branch") == spec_branch

    def test_check_git_conflicts_no_commits_behind(self, temp_git_repo: Path):
@@ -588,7 +82,7 @@ class TestRebaseDetection:
            cwd=temp_git_repo,
            capture_output=True,
        )
-        (temp_git_repo / "spec-file.txt").write_text("spec content")
+        (temp_git_repo / "spec-file.txt").write_text("spec content", encoding="utf-8")
        subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
        subprocess.run(
            ["git", "commit", "-m", "Spec commit"],
@@ -624,7 +118,7 @@ class TestRebaseDetection:
        )

        # Add a commit to spec branch
-        (temp_git_repo / "spec-file.txt").write_text("spec content")
+        (temp_git_repo / "spec-file.txt").write_text("spec content", encoding="utf-8")
        subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
        subprocess.run(
            ["git", "commit", "-m", "Spec commit"],
@@ -639,7 +133,9 @@ class TestRebaseDetection:
            capture_output=True,
        )
        for i in range(3):
-            (temp_git_repo / f"main-file-{i}.txt").write_text(f"main content {i}")
+            (temp_git_repo / f"main-file-{i}.txt").write_text(
+                f"main content {i}", encoding="utf-8"
+            )
            subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
            subprocess.run(
                ["git", "commit", "-m", f"Main commit {i}"],
@@ -671,7 +167,7 @@ class TestRebaseSpecBranch:
        )

        # Add a commit to spec branch
-        (temp_git_repo / "spec-file.txt").write_text("spec content")
+        (temp_git_repo / "spec-file.txt").write_text("spec content", encoding="utf-8")
        subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
        subprocess.run(
            ["git", "commit", "-m", "Spec commit"],
@@ -685,7 +181,7 @@ class TestRebaseSpecBranch:
            cwd=temp_git_repo,
            capture_output=True,
        )
-        (temp_git_repo / "main-file.txt").write_text("main content")
+        (temp_git_repo / "main-file.txt").write_text("main content", encoding="utf-8")
        subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
        subprocess.run(
            ["git", "commit", "-m", "Main commit"],
@@ -726,7 +222,9 @@ class TestRebaseSpecBranch:
        ).stdout
        assert "Main commit" in log, "Spec branch should have main commit after rebase"

-    def test_rebase_spec_branch_with_conflicts_aborts_cleanly(self, temp_git_repo: Path):
+    def test_rebase_spec_branch_with_conflicts_aborts_cleanly(
+        self, temp_git_repo: Path
+    ):
        """_rebase_spec_branch handles conflicts by aborting and returning False (ACS-224)."""
        from core.workspace import _rebase_spec_branch

@@ -739,7 +237,7 @@ class TestRebaseSpecBranch:
        )

        # Create a file that will conflict
-        (temp_git_repo / "conflict.txt").write_text("spec version")
+        (temp_git_repo / "conflict.txt").write_text("spec version", encoding="utf-8")
        subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
        subprocess.run(
            ["git", "commit", "-m", "Spec conflict"],
@@ -753,7 +251,7 @@ class TestRebaseSpecBranch:
            cwd=temp_git_repo,
            capture_output=True,
        )
-        (temp_git_repo / "conflict.txt").write_text("main version")
+        (temp_git_repo / "conflict.txt").write_text("main version", encoding="utf-8")
        subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
        subprocess.run(
            ["git", "commit", "-m", "Main conflict"],
@@ -823,7 +321,7 @@ class TestRebaseSpecBranch:
            cwd=temp_git_repo,
            capture_output=True,
        )
-        (temp_git_repo / "spec-file.txt").write_text("spec content")
+        (temp_git_repo / "spec-file.txt").write_text("spec content", encoding="utf-8")
        subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
        subprocess.run(
            ["git", "commit", "-m", "Spec commit"],
@@ -842,7 +340,9 @@ class TestRebaseSpecBranch:
        # (branch already up-to-date is a success condition)
        result = _rebase_spec_branch(temp_git_repo, "test-spec", "main")

-        assert result is True, "Rebase should return True when branch is already up-to-date"
+        assert result is True, (
+            "Rebase should return True when branch is already up-to-date"
+        )


 class TestRebaseIntegration:
@@ -859,7 +359,9 @@ class TestRebaseIntegration:
        worker_info = manager.create_worktree("test-spec")

        # Add a file in spec worktree and commit
-        (worker_info.path / "spec-file.txt").write_text("spec content")
+        (worker_info.path / "spec-file.txt").write_text(
+            "spec content", encoding="utf-8"
+        )
        subprocess.run(["git", "add", "."], cwd=worker_info.path, capture_output=True)
        subprocess.run(
            ["git", "commit", "-m", "Spec commit"],
@@ -874,7 +376,7 @@ class TestRebaseIntegration:
            capture_output=True,
        )
        for i in range(2):
-            (temp_git_repo / f"main-{i}.txt").write_text(f"main {i}")
+            (temp_git_repo / f"main-{i}.txt").write_text(f"main {i}", encoding="utf-8")
            subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
            subprocess.run(
                ["git", "commit", "-m", f"Main {i}"],
@@ -906,7 +408,7 @@ class TestRebaseIntegration:
        )

        # Add a commit to spec
-        (temp_git_repo / "spec.txt").write_text("spec")
+        (temp_git_repo / "spec.txt").write_text("spec", encoding="utf-8")
        subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
        subprocess.run(
            ["git", "commit", "-m", "Spec"],
@@ -920,7 +422,7 @@ class TestRebaseIntegration:
            cwd=temp_git_repo,
            capture_output=True,
        )
-        (temp_git_repo / "main.txt").write_text("main")
+        (temp_git_repo / "main.txt").write_text("main", encoding="utf-8")
        subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
        subprocess.run(
            ["git", "commit", "-m", "Main"],
@@ -966,7 +468,7 @@ class TestRebaseErrorHandling:
            cwd=temp_git_repo,
            capture_output=True,
        )
-        (temp_git_repo / "spec-file.txt").write_text("spec content")
+        (temp_git_repo / "spec-file.txt").write_text("spec content", encoding="utf-8")
        subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
        subprocess.run(
            ["git", "commit", "-m", "Spec commit"],
@@ -1007,7 +509,6 @@ class TestRebaseErrorHandling:

    def test_check_git_conflicts_handles_corrupted_repo(self, temp_git_repo: Path):
        """_check_git_conflicts handles corrupted repo metadata gracefully (ACS-224)."""
-        import shutil

        from core.workspace import _check_git_conflicts

@@ -1018,7 +519,7 @@ class TestRebaseErrorHandling:
            cwd=temp_git_repo,
            capture_output=True,
        )
-        (temp_git_repo / "spec-file.txt").write_text("spec content")
+        (temp_git_repo / "spec-file.txt").write_text("spec content", encoding="utf-8")
        subprocess.run(["git", "add", "."], cwd=temp_git_repo, capture_output=True)
        subprocess.run(
            ["git", "commit", "-m", "Spec commit"],
@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""
+Tests for Workspace Setup Operations
+=====================================
+
+Tests the setup functionality including:
+- Spec copy to workspace operations
+- Timeline hook installation
+- Timeline tracking initialization
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+# Test constant - in the new per-spec architecture, each spec has its own worktree
+# named after the spec itself. This constant is used for test assertions.
+TEST_SPEC_NAME = "test-spec"
+
+
+class TestCopySpecToWorktree:
+    """Tests for copy_spec_to_worktree function."""
+
+    def test_copies_spec_files_to_worktree(self, temp_git_repo: Path):
+        """Copies spec directory to worktree .auto-claude/specs/ location."""
+        from core.workspace.setup import copy_spec_to_worktree
+
+        # Create source spec directory
+        source_spec = temp_git_repo / "specs" / "test-spec"
+        source_spec.mkdir(parents=True)
+        (source_spec / "spec.md").write_text("# Test Spec", encoding="utf-8")
+        (source_spec / "requirements.json").write_text("{}", encoding="utf-8")
+
+        # Create worktree
+        worktree_path = (
+            temp_git_repo / ".auto-claude" / "worktrees" / "tasks" / "test-spec"
+        )
+        worktree_path.mkdir(parents=True)
+
+        # Copy spec
+        result = copy_spec_to_worktree(source_spec, worktree_path, "test-spec")
+
+        # Verify path is correct
+        expected = worktree_path / ".auto-claude" / "specs" / "test-spec"
+        assert result == expected
+
+        # Verify files were copied
+        assert (expected / "spec.md").exists()
+        assert (expected / "requirements.json").exists()
+        assert (expected / "spec.md").read_text(encoding="utf-8") == "# Test Spec"
+
+    def test_overwrites_existing_spec_in_worktree(self, temp_git_repo: Path):
+        """Overwrites spec files if they already exist in worktree."""
+        from core.workspace.setup import copy_spec_to_worktree
+
+        # Create source spec
+        source_spec = temp_git_repo / "specs" / "test-spec"
+        source_spec.mkdir(parents=True)
+        (source_spec / "spec.md").write_text("# New Spec", encoding="utf-8")
+
+        # Create worktree with existing spec
+        worktree_path = (
+            temp_git_repo / ".auto-claude" / "worktrees" / "tasks" / "test-spec"
+        )
+        worktree_path.mkdir(parents=True)
+        existing_spec = worktree_path / ".auto-claude" / "specs" / "test-spec"
+        existing_spec.mkdir(parents=True)
+        (existing_spec / "spec.md").write_text("# Old Spec", encoding="utf-8")
+
+        # Copy spec
+        result = copy_spec_to_worktree(source_spec, worktree_path, "test-spec")
+
+        # Verify new content was copied
+        assert (result / "spec.md").read_text(encoding="utf-8") == "# New Spec"
+
+    def test_creates_parent_directories(self, temp_git_repo: Path):
+        """Creates .auto-claude/specs directory if it doesn't exist."""
+        from core.workspace.setup import copy_spec_to_worktree
+
+        source_spec = temp_git_repo / "specs" / "test-spec"
+        source_spec.mkdir(parents=True)
+        (source_spec / "spec.md").write_text("# Test", encoding="utf-8")
+
+        worktree_path = (
+            temp_git_repo / ".auto-claude" / "worktrees" / "tasks" / "test-spec"
+        )
+        worktree_path.mkdir(parents=True)
+
+        result = copy_spec_to_worktree(source_spec, worktree_path, "test-spec")
+
+        # Parent directories should be created
+        assert result.exists()
+        assert (result.parent).exists()
+
+
+class TestEnsureTimelineHookInstalled:
+    """Tests for ensure_timeline_hook_installed function."""
+
+    def test_skips_if_not_git_repo(self, temp_dir: Path):
+        """Skips hook installation if directory is not a git repo."""
+        from core.workspace.setup import ensure_timeline_hook_installed
+
+        # Should not raise exception
+        ensure_timeline_hook_installed(temp_dir)
+
+    def test_skips_if_hook_already_installed(self, temp_git_repo: Path, monkeypatch):
+        """Skips if FileTimelineTracker hook is already installed."""
+        from core.workspace.setup import ensure_timeline_hook_installed
+
+        # Create hooks directory
+        hooks_dir = temp_git_repo / ".git" / "hooks"
+        hooks_dir.mkdir(parents=True, exist_ok=True)
+
+        # Create hook with FileTimelineTracker marker
+        hook_file = hooks_dir / "post-commit"
+        hook_file.write_text(
+            "#!/bin/sh\n# FileTimelineTracker hook\necho 'tracked'", encoding="utf-8"
+        )
+
+        # Mock install_hook to track if it was called
+        install_called = []
+
+        def mock_install_hook(project_dir):
+            install_called.append(True)
+
+        monkeypatch.setattr("merge.install_hook.install_hook", mock_install_hook)
+
+        ensure_timeline_hook_installed(temp_git_repo)
+
+        # install_hook should not be called
+        assert len(install_called) == 0
+
+    def test_installs_hook_if_missing(self, temp_git_repo: Path):
+        """Installs hook if it doesn't exist."""
+        from core.workspace.setup import ensure_timeline_hook_installed
+
+        # Create hooks directory but no hook file
+        hooks_dir = temp_git_repo / ".git" / "hooks"
+        hooks_dir.mkdir(parents=True, exist_ok=True)
+
+        # This test verifies the function runs without error
+        # The actual install_hook call is hard to mock because it's imported locally
+        # In production, the real install_hook would be called
+        ensure_timeline_hook_installed(temp_git_repo)
+
+        # Verify hooks directory exists (function ran)
+        assert hooks_dir.exists()
+
+
+class TestInitializeTimelineTracking:
+    """Tests for initialize_timeline_tracking function."""
+
+    def test_with_implementation_plan(self, temp_git_repo: Path, monkeypatch):
+        """Initializes tracking with files from implementation plan."""
+        from core.workspace.setup import initialize_timeline_tracking
+
+        # Create source spec with implementation plan
+        spec_name = "test-spec"
+        source_spec = temp_git_repo / ".auto-claude" / "specs" / spec_name
+        source_spec.mkdir(parents=True)
+
+        plan = {
+            "title": "Test Feature",
+            "description": "Test description",
+            "phases": [
+                {
+                    "subtasks": [
+                        {"files": ["app/main.py", "app/utils.py"]},
+                        {"files": ["tests/test_main.py"]},
+                    ]
+                }
+            ],
+        }
+        (source_spec / "implementation_plan.json").write_text(
+            json.dumps(plan), encoding="utf-8"
+        )
+
+        # Create worktree
+        worktree_path = (
+            temp_git_repo / ".auto-claude" / "worktrees" / "tasks" / spec_name
+        )
+        worktree_path.mkdir(parents=True)
+
+        # Mock FileTimelineTracker
+        mock_tracker_calls = []
+
+        class MockTracker:
+            def __init__(self, project_dir):
+                pass
+
+            def on_task_start(
+                self,
+                task_id,
+                files_to_modify,
+                branch_point_commit,
+                task_intent,
+                task_title,
+            ):
+                mock_tracker_calls.append(
+                    {
+                        "task_id": task_id,
+                        "files": files_to_modify,
+                        "branch": branch_point_commit,
+                        "intent": task_intent,
+                        "title": task_title,
+                    }
+                )
+
+        monkeypatch.setattr("core.workspace.setup.FileTimelineTracker", MockTracker)
+
+        initialize_timeline_tracking(
+            temp_git_repo, spec_name, worktree_path, source_spec
+        )
+
+        # Verify tracker was called with correct parameters
+        assert len(mock_tracker_calls) == 1
+        call = mock_tracker_calls[0]
+        assert call["task_id"] == spec_name
+        assert set(call["files"]) == {
+            "app/main.py",
+            "app/utils.py",
+            "tests/test_main.py",
+        }
+        assert call["title"] == "Test Feature"
+        assert call["intent"] == "Test description"
+
+    def test_without_implementation_plan(self, temp_git_repo: Path, monkeypatch):
+        """Initializes tracking retroactively from worktree if no plan."""
+        from core.workspace.setup import initialize_timeline_tracking
+
+        spec_name = "test-spec"
+        worktree_path = (
+            temp_git_repo / ".auto-claude" / "worktrees" / "tasks" / spec_name
+        )
+        worktree_path.mkdir(parents=True)
+
+        # Mock FileTimelineTracker
+        mock_calls = []
+
+        class MockTracker:
+            def __init__(self, project_dir):
+                pass
+
+            def initialize_from_worktree(
+                self, task_id, worktree_path, task_intent, task_title
+            ):
+                mock_calls.append(
+                    {
+                        "task_id": task_id,
+                        "worktree": worktree_path,
+                        "intent": task_intent,
+                        "title": task_title,
+                    }
+                )
+
+        monkeypatch.setattr("core.workspace.setup.FileTimelineTracker", MockTracker)
+
+        initialize_timeline_tracking(temp_git_repo, spec_name, worktree_path, None)
+
+        # Should use retroactive initialization
+        assert len(mock_calls) == 1
+        assert mock_calls[0]["task_id"] == spec_name
+
+    def test_handles_exception_gracefully(
+        self, temp_git_repo: Path, monkeypatch, capsys
+    ):
+        """Logs warning but doesn't raise exception on error."""
+        from core.workspace.setup import initialize_timeline_tracking
+
+        spec_name = "test-spec"
+        worktree_path = (
+            temp_git_repo / ".auto-claude" / "worktrees" / "tasks" / spec_name
+        )
+        worktree_path.mkdir(parents=True)
+
+        # Mock FileTimelineTracker to raise exception
+        class FailingTracker:
+            def __init__(self, project_dir):
+                raise Exception("Tracker init failed")
+
+        monkeypatch.setattr("core.workspace.setup.FileTimelineTracker", FailingTracker)
+
+        # Should not raise
+        initialize_timeline_tracking(temp_git_repo, spec_name, worktree_path, None)
+
+        # Should print warning
+        captured = capsys.readouterr()
+        assert "Timeline tracking" in captured.out or "Note:" in captured.out
@@ -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,51 @@ 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:
+                    # File system comparison errors are handled by fallback below
+                    pass
+                # Fallback to normalized case comparison
+                if os.path.normcase(str(resolved_path)) == os.path.normcase(
+                    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 +459,67 @@ 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:
+                # File system errors handled by fallback comparison below
+                pass
+            # Fallback to normalized case comparison for non-existent paths
+            if os.path.normcase(str(resolved_path)) == os.path.normcase(
+                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 +609,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 +635,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 +652,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 +695,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 +1063,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 +1213,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 +1271,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 +1347,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 +1743,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 +1762,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 +1822,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 +1837,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 +1847,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"),
@@ -29,6 +29,7 @@ class IdeationConfigManager:
        thinking_level: str = "medium",
        refresh: bool = False,
        append: bool = False,
+        fast_mode: bool = False,
    ):
        """Initialize configuration manager.

@@ -64,6 +65,7 @@ class IdeationConfigManager:
            self.model,
            self.thinking_level,
            self.max_ideas_per_type,
+            fast_mode=fast_mode,
        )
        self.analyzer = ProjectAnalyzer(
            self.project_dir,
@@ -17,7 +17,12 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).parent.parent))

 from client import create_client
-from phase_config import get_thinking_budget, resolve_model_id
+from phase_config import (
+    get_model_betas,
+    get_thinking_budget,
+    get_thinking_kwargs_for_model,
+    resolve_model_id,
+)
 from ui import print_status

 # Ideation types
@@ -59,6 +64,7 @@ class IdeationGenerator:
        model: str = "sonnet",  # Changed from "opus" (fix #433)
        thinking_level: str = "medium",
        max_ideas_per_type: int = 5,
+        fast_mode: bool = False,
    ):
        self.project_dir = Path(project_dir)
        self.output_dir = Path(output_dir)
@@ -66,6 +72,7 @@ class IdeationGenerator:
        self.thinking_level = thinking_level
        self.thinking_budget = get_thinking_budget(thinking_level)
        self.max_ideas_per_type = max_ideas_per_type
+        self.fast_mode = fast_mode
        self.prompts_dir = Path(__file__).parent.parent / "prompts"

    async def run_agent(
@@ -91,11 +98,21 @@ 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
+        resolved_model = resolve_model_id(self.model)
+        betas = get_model_betas(self.model)
+        thinking_kwargs = get_thinking_kwargs_for_model(
+            resolved_model, self.thinking_level
+        )
        client = create_client(
            self.project_dir,
            self.output_dir,
-            resolve_model_id(self.model),
-            max_thinking_tokens=self.thinking_budget,
+            resolved_model,
+            agent_type="ideation",
+            betas=betas,
+            fast_mode=self.fast_mode,
+            **thinking_kwargs,
        )

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

+        # Use agent_type="ideation" for recovery agent as well
+        resolved_model = resolve_model_id(self.model)
+        betas = get_model_betas(self.model)
+        thinking_kwargs = get_thinking_kwargs_for_model(
+            resolved_model, self.thinking_level
+        )
        client = create_client(
            self.project_dir,
            self.output_dir,
-            resolve_model_id(self.model),
-            max_thinking_tokens=self.thinking_budget,
+            resolved_model,
+            agent_type="ideation",
+            betas=betas,
+            fast_mode=self.fast_mode,
+            **thinking_kwargs,
        )

        try:
@@ -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:
@@ -45,6 +46,7 @@ class IdeationOrchestrator:
        thinking_level: str = "medium",
        refresh: bool = False,
        append: bool = False,
+        fast_mode: bool = False,
    ):
        """Initialize the ideation orchestrator.

@@ -59,6 +61,7 @@ class IdeationOrchestrator:
            thinking_level: Thinking level for extended reasoning
            refresh: Force regeneration of existing files
            append: Preserve existing ideas when merging
+            fast_mode: Enable Fast Mode for faster Opus 4.6 output
        """
        # Initialize configuration manager
        self.config_manager = IdeationConfigManager(
@@ -72,6 +75,7 @@ class IdeationOrchestrator:
            thinking_level=thinking_level,
            refresh=refresh,
            append=append,
+            fast_mode=fast_mode,
        )

        # Expose configuration for convenience
@@ -173,16 +177,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):
@@ -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
@@ -145,7 +145,7 @@ class GraphitiConfig:

    # OpenRouter settings (multi-provider aggregator)
    openrouter_api_key: str = ""
-    openrouter_base_url: str = "https://openrouter.ai/api/v1"
+    openrouter_base_url: str = "https://openrouter.ai/api"
    openrouter_llm_model: str = "anthropic/claude-sonnet-4"
    openrouter_embedding_model: str = "openai/text-embedding-3-small"

@@ -207,7 +207,7 @@ class GraphitiConfig:
        # OpenRouter settings
        openrouter_api_key = os.environ.get("OPENROUTER_API_KEY", "")
        openrouter_base_url = os.environ.get(
-            "OPENROUTER_BASE_URL", "https://openrouter.ai/api/v1"
+            "OPENROUTER_BASE_URL", "https://openrouter.ai/api"
        )
        openrouter_llm_model = os.environ.get(
            "OPENROUTER_LLM_MODEL", "anthropic/claude-sonnet-4"
@@ -624,7 +624,10 @@ def get_graphiti_status() -> dict:

    # CRITICAL FIX: Actually verify packages are importable before reporting available
    # Don't just check config.is_valid() - actually try to import the module
-    if not config.is_valid():
+    # Note: This branch is currently unreachable because is_valid() returns True
+    # whenever enabled is True. Kept for defensive purposes in case is_valid()
+    # logic changes in the future.
+    if not config.is_valid():  # pragma: no cover
        status["reason"] = errors[0] if errors else "Configuration invalid"
        return status

@@ -635,7 +638,7 @@ def get_graphiti_status() -> dict:
        from graphiti_core.driver.falkordb_driver import FalkorDriver  # noqa: F401

        # If we got here, packages are importable
-        status["available"] = True
+        status["available"] = True  # pragma: no cover
    except ImportError as e:
        status["available"] = False
        status["reason"] = f"Graphiti packages not installed: {e}"
@@ -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.
@@ -76,6 +72,8 @@ async def test_graphiti_connection() -> tuple[bool, str]:
    """
    Test if LadybugDB is available and Graphiti can connect.

+    Uses the embedded LadybugDB via the patched KuzuDriver (no remote connection).
+
    Returns:
        Tuple of (success: bool, message: str)
    """
@@ -91,43 +89,48 @@ async def test_graphiti_connection() -> tuple[bool, str]:

    try:
        from graphiti_core import Graphiti
-        from graphiti_core.driver.falkordb_driver import FalkorDriver
        from graphiti_providers import ProviderError, create_embedder, create_llm_client

+        # Import the patched driver creator (handles LadybugDB monkeypatch internally)
+        from integrations.graphiti.queries_pkg.client import _apply_ladybug_monkeypatch
+        from integrations.graphiti.queries_pkg.kuzu_driver_patched import (
+            create_patched_kuzu_driver,
+        )
+
        # Create providers
        try:
-            llm_client = create_llm_client(config)
-            embedder = create_embedder(config)
+            llm_client = create_llm_client(config)  # pragma: no cover
+            embedder = create_embedder(config)  # pragma: no cover
        except ProviderError as e:
            return False, f"Provider error: {e}"

-        # Try to connect
-        driver = FalkorDriver(
-            host=config.falkordb_host,
-            port=config.falkordb_port,
-            password=config.falkordb_password or None,
-            database=config.database,
-        )
+        # Apply LadybugDB monkeypatch for embedded database
+        if not _apply_ladybug_monkeypatch():  # pragma: no cover
+            return False, "LadybugDB not installed (requires Python 3.12+)"

-        graphiti = Graphiti(
+        # Create embedded database driver
+        db_path = config.get_db_path()
+        driver = create_patched_kuzu_driver(db=str(db_path))  # pragma: no cover
+
+        graphiti = Graphiti(  # pragma: no cover
            graph_driver=driver,
            llm_client=llm_client,
            embedder=embedder,
        )

        # Try a simple operation
-        await graphiti.build_indices_and_constraints()
-        await graphiti.close()
+        await graphiti.build_indices_and_constraints()  # pragma: no cover
+        await graphiti.close()  # pragma: no cover

-        return True, (
-            f"Connected to LadybugDB at {config.falkordb_host}:{config.falkordb_port} "
+        return True, (  # pragma: no cover
+            f"Connected to LadybugDB at {db_path} "
            f"(providers: {config.get_provider_summary()})"
        )

    except ImportError as e:
        return False, f"Graphiti packages not installed: {e}"

-    except Exception as e:
+    except Exception as e:  # pragma: no cover
        return False, f"Connection failed: {e}"


@@ -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

@@ -15,7 +15,10 @@ from typing import Any
 # Import kuzu (might be real_ladybug via monkeypatch)
 try:
    import kuzu
-except ImportError:
+except ImportError:  # pragma: no cover
+    # Fallback to real_ladybug if kuzu is not available.
+    # This import-time fallback is hard to test in normal unit tests
+    # since the module is imported once before tests can mock anything.
    import real_ladybug as kuzu  # type: ignore

 logger = logging.getLogger(__name__)
@@ -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,
@@ -65,7 +67,8 @@ class GraphitiSearch:
        Args:
            query: Search query
            num_results: Maximum number of results to return
-            include_project_context: If True and in PROJECT mode, search project-wide
+            include_project_context: If True and in SPEC mode, also search project-wide
+            min_score: Minimum relevance score threshold (0.0 to 1.0)

        Returns:
            List of relevant context items with content, score, and type
@@ -99,10 +102,14 @@ class GraphitiSearch:
                    or str(result)
                )

+                # Normalize score to float, treating None as 0.0
+                raw_score = getattr(result, "score", None)
+                score = raw_score if raw_score is not None else 0.0
+
                context_items.append(
                    {
                        "content": content,
-                        "score": getattr(result, "score", 0.0),
+                        "score": score,
                        "type": getattr(result, "type", "unknown"),
                    }
                )
@@ -110,7 +117,9 @@ class GraphitiSearch:
            # Filter by minimum score if specified
            if min_score > 0:
                context_items = [
-                    item for item in context_items if item.get("score", 0) >= min_score
+                    item
+                    for item in context_items
+                    if (item.get("score", 0.0)) >= min_score
                ]

            logger.info(
@@ -120,6 +129,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 +189,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(
@@ -212,12 +232,14 @@ class GraphitiSearch:
                        if not isinstance(data, dict):
                            continue
                        if data.get("type") == EPISODE_TYPE_TASK_OUTCOME:
+                            raw_score = getattr(result, "score", None)
+                            score = raw_score if raw_score is not None else 0.0
                            outcomes.append(
                                {
                                    "task_id": data.get("task_id"),
                                    "success": data.get("success"),
                                    "outcome": data.get("outcome"),
-                                    "score": getattr(result, "score", 0.0),
+                                    "score": score,
                                }
                            )
                    except (json.JSONDecodeError, TypeError, AttributeError):
@@ -227,6 +249,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(
@@ -265,7 +293,8 @@ class GraphitiSearch:
                content = getattr(result, "content", None) or getattr(
                    result, "fact", None
                )
-                score = getattr(result, "score", 0.0)
+                raw_score = getattr(result, "score", None)
+                score = raw_score if raw_score is not None else 0.0

                if score < min_score:
                    continue
@@ -301,7 +330,8 @@ class GraphitiSearch:
                content = getattr(result, "content", None) or getattr(
                    result, "fact", None
                )
-                score = getattr(result, "score", 0.0)
+                raw_score = getattr(result, "score", None)
+                score = raw_score if raw_score is not None else 0.0

                if score < min_score:
                    continue
@@ -337,4 +367,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 [], []
@@ -22,13 +22,13 @@ Usage:

    # Run the test:
    cd auto-claude
-    python integrations/graphiti/test_graphiti_memory.py
+    python integrations/graphiti/run_graphiti_memory_test.py

    # Or run specific tests:
-    python integrations/graphiti/test_graphiti_memory.py --test connection
-    python integrations/graphiti/test_graphiti_memory.py --test save
-    python integrations/graphiti/test_graphiti_memory.py --test search
-    python integrations/graphiti/test_graphiti_memory.py --test ollama
+    python integrations/graphiti/run_graphiti_memory_test.py --test connection
+    python integrations/graphiti/run_graphiti_memory_test.py --test save
+    python integrations/graphiti/run_graphiti_memory_test.py --test search
+    python integrations/graphiti/run_graphiti_memory_test.py --test ollama
 """

 import argparse
@@ -36,18 +36,15 @@ import asyncio
 import json
 import os
 import sys
+import tempfile
 from datetime import datetime, timezone
 from pathlib import Path

-# Add auto-claude to path
-auto_claude_dir = Path(__file__).parent.parent.parent
-sys.path.insert(0, str(auto_claude_dir))
-
 # Load .env file
 try:
    from dotenv import load_dotenv

-    env_file = auto_claude_dir / ".env"
+    env_file = Path(__file__).parent.parent.parent.parent / ".env"
    if env_file.exists():
        load_dotenv(env_file)
        print(f"Loaded .env from {env_file}")
@@ -170,7 +167,9 @@ async def test_save_episode(db_path: str, database: str) -> tuple[str, str]:
            "embedder": config.embedder_provider,
        }

-        episode_name = f"test_episode_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+        episode_name = (
+            f"test_episode_{datetime.now(timezone.utc).strftime('%Y%m%d_%H%M%S')}"
+        )
        group_id = "ladybug_test_group"

        print(f"  Episode name: {episode_name}")
@@ -186,7 +185,7 @@ async def test_save_episode(db_path: str, database: str) -> tuple[str, str]:
            name=episode_name,
            episode_body=json.dumps(test_data),
            source=EpisodeType.text,
-            source_description="Test episode from test_graphiti_memory.py",
+            source_description="Test episode from run_graphiti_memory_test.py",
            reference_time=datetime.now(timezone.utc),
            group_id=group_id,
        )
@@ -432,11 +431,8 @@ async def test_graphiti_memory_class(db_path: str, database: str) -> bool:
        from integrations.graphiti.memory import GraphitiMemory

        # Create temporary directories for testing
-        test_spec_dir = Path("/tmp/graphiti_test_spec")
-        test_spec_dir.mkdir(parents=True, exist_ok=True)
-
-        test_project_dir = Path("/tmp/graphiti_test_project")
-        test_project_dir.mkdir(parents=True, exist_ok=True)
+        test_spec_dir = Path(tempfile.mkdtemp(prefix="graphiti_test_spec_"))
+        test_project_dir = Path(tempfile.mkdtemp(prefix="graphiti_test_project_"))

        print(f"  Spec dir: {test_spec_dir}")
        print(f"  Project dir: {test_project_dir}")
@@ -704,14 +700,14 @@ async def main():
    print()
    print("  Quick commands:")
    print("    # Run all tests:")
-    print("    python integrations/graphiti/test_graphiti_memory.py")
+    print("    python integrations/graphiti/run_graphiti_memory_test.py")
    print()
    print("    # Test just Ollama embeddings:")
-    print("    python integrations/graphiti/test_graphiti_memory.py --test ollama")
+    print("    python integrations/graphiti/run_graphiti_memory_test.py --test ollama")
    print()
    print("    # Test with production database:")
    print(
-        "    python integrations/graphiti/test_graphiti_memory.py --database auto_claude_memory"
+        "    python integrations/graphiti/run_graphiti_memory_test.py --database auto_claude_memory"
    )
    print()

@@ -36,13 +36,13 @@ NOTE: graphiti-core internally uses an OpenAI reranker for search ranking.

 Usage:
    cd apps/backend
-    python integrations/graphiti/test_ollama_embedding_memory.py
+    python integrations/graphiti/run_ollama_embedding_test.py

    # Run specific tests:
-    python integrations/graphiti/test_ollama_embedding_memory.py --test embeddings
-    python integrations/graphiti/test_ollama_embedding_memory.py --test create
-    python integrations/graphiti/test_ollama_embedding_memory.py --test retrieve
-    python integrations/graphiti/test_ollama_embedding_memory.py --test full-cycle
+    python integrations/graphiti/run_ollama_embedding_test.py --test embeddings
+    python integrations/graphiti/run_ollama_embedding_test.py --test create
+    python integrations/graphiti/run_ollama_embedding_test.py --test retrieve
+    python integrations/graphiti/run_ollama_embedding_test.py --test full-cycle
 """

 import argparse
@@ -54,15 +54,15 @@ import tempfile
 from datetime import datetime
 from pathlib import Path

-# Add auto-claude to path
-auto_claude_dir = Path(__file__).parent.parent.parent
-sys.path.insert(0, str(auto_claude_dir))
+# Add backend to path
+backend_dir = Path(__file__).parent.parent.parent.parent
+sys.path.insert(0, str(backend_dir))

 # Load .env file
 try:
    from dotenv import load_dotenv

-    env_file = auto_claude_dir / ".env"
+    env_file = backend_dir / ".env"
    if env_file.exists():
        load_dotenv(env_file)
        print(f"Loaded .env from {env_file}")
@@ -843,18 +843,18 @@ async def main():
    print()
    print("  Commands:")
    print("    # Run all tests:")
-    print("    python integrations/graphiti/test_ollama_embedding_memory.py")
+    print("    python integrations/graphiti/run_ollama_embedding_test.py")
    print()
    print("    # Run specific test:")
    print(
-        "    python integrations/graphiti/test_ollama_embedding_memory.py --test embeddings"
+        "    python integrations/graphiti/run_ollama_embedding_test.py --test embeddings"
    )
    print(
-        "    python integrations/graphiti/test_ollama_embedding_memory.py --test full-cycle"
+        "    python integrations/graphiti/run_ollama_embedding_test.py --test full-cycle"
    )
    print()
    print("    # Keep database for inspection:")
-    print("    python integrations/graphiti/test_ollama_embedding_memory.py --keep-db")
+    print("    python integrations/graphiti/run_ollama_embedding_test.py --keep-db")
    print()


@@ -1,68 +0,0 @@
-#!/usr/bin/env python3
-"""
-Quick test to demonstrate provider-specific database naming.
-
-Shows how Auto Claude automatically generates provider-specific database names
-to prevent embedding dimension mismatches.
-"""
-
-import os
-import sys
-from pathlib import Path
-
-# Add auto-claude to path
-sys.path.insert(0, str(Path(__file__).parent.parent.parent))
-
-from integrations.graphiti.config import GraphitiConfig
-
-
-def test_provider_naming():
-    """Demonstrate provider-specific database naming."""
-
-    print("\n" + "=" * 70)
-    print("  PROVIDER-SPECIFIC DATABASE NAMING")
-    print("=" * 70 + "\n")
-
-    providers = [
-        ("openai", None, None),
-        ("ollama", "embeddinggemma", 768),
-        ("ollama", "qwen3-embedding:0.6b", 1024),
-        ("voyage", None, None),
-        ("google", None, None),
-    ]
-
-    for provider, model, dim in providers:
-        # Create config
-        config = GraphitiConfig.from_env()
-        config.embedder_provider = provider
-
-        if provider == "ollama" and model:
-            config.ollama_embedding_model = model
-            if dim:
-                config.ollama_embedding_dim = dim
-
-        # Get naming info
-        dimension = config.get_embedding_dimension()
-        signature = config.get_provider_signature()
-        db_name = config.get_provider_specific_database_name("auto_claude_memory")
-
-        print(f"Provider: {provider}")
-        if model:
-            print(f"  Model: {model}")
-        print(f"  Embedding Dimension: {dimension}")
-        print(f"  Provider Signature: {signature}")
-        print(f"  Database Name: {db_name}")
-        print(f"  Full Path: ~/.auto-claude/memories/{db_name}/")
-        print()
-
-    print("=" * 70)
-    print("\nKey Benefits:")
-    print("  ✅ No dimension mismatch errors")
-    print("  ✅ Each provider uses its own database")
-    print("  ✅ Can switch providers without conflicts")
-    print("  ✅ Migration utility available for data transfer")
-    print()
-
-
-if __name__ == "__main__":
-    test_provider_naming()
@@ -0,0 +1 @@
+"""Tests for Graphiti memory integration."""
@@ -0,0 +1,610 @@
+"""
+Pytest configuration and fixtures for graphiti integration tests.
+
+This module provides shared fixtures for testing the memory system integration,
+including mocks for external dependencies, test configurations, and client fixtures.
+"""
+
+import os
+import sys
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, Mock, patch
+
+import pytest
+
+# Add the backend directory to sys.path to allow imports
+backend_dir = Path(__file__).parent.parent.parent.parent
+sys.path.insert(0, str(backend_dir))
+
+
+def pytest_collection_modifyitems(config, items):
+    """
+    Exclude validator functions from test collection.
+
+    The validators.py module contains functions named test_llm_connection and
+    test_embedder_connection which are not pytest tests but validator functions.
+    """
+    # Filter out items that are from validators.py and are not in test classes
+    filtered_items = []
+    for item in items:
+        # Get the full path of the test
+        item_path = str(item.fspath) if hasattr(item, "fspath") else str(item.path)
+
+        # Skip the standalone test_llm_connection and test_embedder_connection
+        # functions from validators.py (they're not pytest tests)
+        if item.name in [
+            "test_llm_connection",
+            "test_embedder_connection",
+            "test_ollama_connection",
+        ]:
+            # Check if it's from validators.py
+            if "validators.py" in item_path or "test_providers.py" in item_path:
+                # Only skip if it's a standalone function (not in a TestClass)
+                if not item.parent.name.startswith("Test"):
+                    continue
+
+        filtered_items.append(item)
+
+    items[:] = filtered_items
+
+
+# =============================================================================
+# External Dependency Mocks
+# =============================================================================
+
+
+@pytest.fixture
+def mock_graphiti_core():
+    """Mock graphiti_core.Graphiti and related classes.
+
+    Patches the graphiti_core library to prevent actual graph database connections
+    during tests.
+
+    Yields:
+        tuple: (mock_graphiti_class, mock_graphiti_instance)
+    """
+    with patch(
+        "integrations.graphiti.queries_pkg.graphiti.graphiti_core.Graphiti"
+    ) as mock_graphiti:
+        # Configure the mock to return a mock instance
+        mock_instance = MagicMock()
+        mock_graphiti.return_value = mock_instance
+
+        # Mock common methods that might be called
+        mock_instance.add_edges = AsyncMock()
+        mock_instance.add_nodes = AsyncMock()
+        mock_instance.search = AsyncMock(return_value=[])
+        mock_instance.delete_graph = AsyncMock()
+        mock_instance.close = AsyncMock()
+
+        yield mock_graphiti, mock_instance
+
+
+@pytest.fixture
+def mock_falkor_driver():
+    """Mock graphiti_core.driver.falkordb_driver.FalkorDriver.
+
+    Prevents actual FalkorDB connections during tests.
+
+    Yields:
+        tuple: (mock_driver_class, mock_driver_instance)
+    """
+    with patch(
+        "integrations.graphiti.queries_pkg.graphiti.graphiti_core.driver.falkordb_driver.FalkorDriver"
+    ) as mock_driver:
+        mock_instance = MagicMock()
+        mock_driver.return_value = mock_instance
+
+        # Mock driver methods
+        mock_instance.close = MagicMock()
+        mock_instance.execute_query = MagicMock(return_value=[])
+
+        yield mock_driver, mock_instance
+
+
+@pytest.fixture
+def mock_graphiti_providers():
+    """Mock graphiti_providers module.
+
+    Patches the graphiti_providers module to prevent actual LLM/embedder calls.
+
+    Yields:
+        tuple: (mock_get_client, mock_client_instance)
+    """
+    with patch(
+        "integrations.graphiti.providers_pkg.providers.get_client"
+    ) as mock_get_client:
+        mock_client = MagicMock()
+        mock_get_client.return_value = mock_client
+        yield mock_get_client, mock_client
+
+
+@pytest.fixture
+def mock_ladybug_db():
+    """Mock real_ladybug and kuzu database connections.
+
+    Prevents actual database connections during tests.
+
+    Yields:
+        dict: Dictionary with 'ladybug' and 'kuzu' keys, each containing
+              (mock_class, mock_instance) tuples.
+    """
+    with (
+        patch(
+            "integrations.graphiti.queries_pkg.client.real_ladybug.Ladybug"
+        ) as mock_ladybug,
+        patch("integrations.graphiti.queries_pkg.client.kuzu.Connection") as mock_kuzu,
+    ):
+        # Mock Ladybug instance
+        ladybug_instance = MagicMock()
+        mock_ladybug.return_value = ladybug_instance
+        ladybug_instance.close = MagicMock()
+
+        # Mock Kuzu connection
+        kuzu_instance = MagicMock()
+        mock_kuzu.return_value = kuzu_instance
+        kuzu_instance.close = MagicMock()
+
+        yield {
+            "ladybug": (mock_ladybug, ladybug_instance),
+            "kuzu": (mock_kuzu, kuzu_instance),
+        }
+
+
+# =============================================================================
+# Config Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def mock_config():
+    """Return a GraphitiConfig with test values.
+
+    Provides a test configuration that doesn't require real environment variables
+    or database connections.
+
+    Returns:
+        GraphitiConfig: Configuration with test values.
+    """
+    from integrations.graphiti.config import GraphitiConfig
+
+    config = GraphitiConfig(
+        enabled=True,
+        database="test_dataset",
+        db_path="/tmp/test_graphiti.db",
+        llm_provider="openai",
+        openai_model="gpt-5-mini",
+        embedder_provider="openai",
+        openai_embedding_model="text-embedding-3-small",
+        openai_api_key="sk-test-key-for-testing",
+    )
+
+    return config
+
+
+@pytest.fixture
+def mock_env_vars(tmp_path):
+    """Set test environment variables for Graphiti configuration.
+
+    Sets up a clean environment with test values for all Graphiti-related
+    environment variables.
+
+    Yields:
+        dict: Dictionary of environment variables that were set.
+    """
+    test_db_path = str(tmp_path / "test_graphiti.db")
+
+    env_vars = {
+        "GRAPHITI_ENABLED": "true",
+        "GRAPHITI_LLM_PROVIDER": "openai",
+        "GRAPHITI_EMBEDDER_PROVIDER": "openai",
+        "GRAPHITI_DATABASE": "test_dataset",
+        "GRAPHITI_DB_PATH": test_db_path,
+        "OPENAI_MODEL": "gpt-5-mini",
+        "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
+        "OPENAI_API_KEY": "sk-test-key-for-testing",
+    }
+
+    # Save original values
+    original = {k: os.environ.get(k) for k in env_vars}
+
+    # Set test values
+    for key, value in env_vars.items():
+        os.environ[key] = value
+
+    yield env_vars
+
+    # Restore original values
+    for key, original_value in original.items():
+        if original_value is None:
+            os.environ.pop(key, None)
+        else:
+            os.environ[key] = original_value
+
+
+# =============================================================================
+# Client Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def mock_graphiti_client():
+    """Mock GraphitiClient with all necessary methods.
+
+    Provides a mock client that simulates the behavior of the GraphitiClient
+    without requiring actual graph database connections.
+
+    Returns:
+        Mock: Mocked GraphitiClient with typical methods mocked.
+    """
+    client = Mock()
+    client.graphiti = Mock()
+
+    # Core client methods
+    client.is_initialized = Mock(return_value=True)
+    client.initialize = AsyncMock()
+    client.get_session_id = Mock(return_value="test_session")
+    client.get_user_id = Mock(return_value="test_user")
+    client.get_project_id = Mock(return_value="test_project")
+
+    # Memory operations (async)
+    client.add_episode = AsyncMock(return_value="episode_id_123")
+    client.add_episodic_memories = AsyncMock(return_value=["mem_id_1", "mem_id_2"])
+    client.add_abstract_memories = AsyncMock(return_value=["abstract_id_1"])
+    client.search = AsyncMock(return_value=[])
+    client.delete_graph = AsyncMock()
+
+    # Graphiti instance methods
+    client.graphiti.search = AsyncMock(return_value=[])
+
+    # Configuration
+    client.get_config = Mock(
+        return_value=Mock(
+            enabled=True, database="test_dataset", db_path="/tmp/test_graphiti.db"
+        )
+    )
+
+    return client
+
+
+@pytest.fixture
+def mock_graphiti_instance():
+    """Mock the Graphiti instance from graphiti_core.
+
+    Provides a mock of the actual Graphiti core instance with all methods
+    that might be called during operations.
+
+    Returns:
+        Mock: Mocked Graphiti instance with typical methods mocked.
+    """
+    instance = MagicMock()
+
+    # Search methods (async)
+    instance.search = AsyncMock(return_value=[])
+    instance.search_by_abstract = AsyncMock(return_value=[])
+    instance.search_by_vector = AsyncMock(return_value=[])
+
+    # Add methods (async)
+    instance.add_episode = AsyncMock(return_value="episode_id")
+    instance.add_edges = AsyncMock()
+    instance.add_nodes = AsyncMock()
+
+    # Graph management
+    instance.delete_graph = AsyncMock()
+    instance.close = AsyncMock()
+    instance.get_graph_summary = Mock(return_value={"nodes": 0, "edges": 0})
+
+    # Configuration
+    instance.database = "test_dataset"
+
+    return instance
+
+
+# =============================================================================
+# Test Directory Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def temp_spec_dir(tmp_path):
+    """Create a temporary directory for spec testing.
+
+    Provides a temporary directory with spec-like structure for testing
+    spec-related functionality.
+
+    Args:
+        tmp_path: pytest's built-in tmp_path fixture.
+
+    Returns:
+        Path: Path to the temporary spec directory.
+    """
+    spec_dir = tmp_path / "spec_001_test"
+    spec_dir.mkdir()
+
+    # Create common spec subdirectories
+    (spec_dir / ".auto-claude").mkdir()
+    (spec_dir / "context").mkdir()
+
+    return spec_dir
+
+
+@pytest.fixture
+def temp_project_dir(tmp_path):
+    """Create a temporary directory for project testing.
+
+    Provides a temporary directory with project-like structure for testing
+    project-related functionality.
+
+    Args:
+        tmp_path: pytest's built-in tmp_path fixture.
+
+    Returns:
+        Path: Path to the temporary project directory.
+    """
+    project_dir = tmp_path / "test_project"
+    project_dir.mkdir()
+
+    # Create common project subdirectories
+    (project_dir / "src").mkdir()
+    (project_dir / "tests").mkdir()
+    (project_dir / ".auto-claude").mkdir()
+
+    return project_dir
+
+
+@pytest.fixture
+def temp_db_path(tmp_path):
+    """Create a temporary path for test database.
+
+    Provides a temporary file path that can be used for database testing
+    without affecting real databases.
+
+    Args:
+        tmp_path: pytest's built-in tmp_path fixture.
+
+    Returns:
+        str: Path to temporary database file.
+    """
+    db_path = str(tmp_path / "test_graphiti.db")
+    return db_path
+
+
+# =============================================================================
+# Provider Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def mock_llm_client():
+    """Mocked LLM client for testing.
+
+    Provides a mock client that simulates LLM responses without making
+    actual API calls.
+
+    Returns:
+        Mock: Mocked LLM client.
+    """
+    client = Mock()
+
+    # Message methods
+    client.messages = Mock()
+    mock_response = Mock()
+    mock_response.id = "msg_test_123"
+    mock_response.content = []
+    mock_response.model = "claude-3-5-sonnet-20241022"
+    mock_response.role = "assistant"
+    client.messages.create = Mock(return_value=mock_response)
+
+    # Streaming support
+    client.messages.stream = Mock(return_value=iter([]))
+
+    # Token counting
+    client.count_tokens = Mock(return_value=100)
+
+    return client
+
+
+@pytest.fixture
+def mock_embedder():
+    """Mocked embedder with get_embedding() method.
+
+    Provides a mock embedder that returns fake embeddings without making
+    actual API calls. Uses deterministic values for reproducibility.
+
+    Returns:
+        tuple: (mock_embedder, test_embedding_list)
+    """
+    embedder = Mock()
+
+    # Return a deterministic embedding vector (1536 dimensions is common for OpenAI)
+    # Using 0.1 for all values makes tests reproducible
+    test_embedding = [0.1] * 1536
+
+    embedder.get_embedding = Mock(return_value=test_embedding)
+    embedder.get_embeddings = Mock(return_value=[test_embedding])
+
+    return embedder, test_embedding
+
+
+# =============================================================================
+# State Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def mock_state():
+    """GraphitiState with test values.
+
+    Provides a mock state object with typical values for testing state-related
+    functionality.
+
+    Returns:
+        Mock: Mocked GraphitiState with test values.
+    """
+    from integrations.graphiti.config import GraphitiState
+
+    state = GraphitiState(
+        initialized=True,
+        database="test_dataset",
+        indices_built=True,
+        llm_provider="openai",
+        embedder_provider="openai",
+    )
+
+    return state
+
+
+@pytest.fixture
+def mock_empty_state():
+    """Empty GraphitiState.
+
+    Provides a mock state object with default/uninitialized values for testing
+    initialization logic.
+
+    Returns:
+        Mock: Mocked GraphitiState with empty/default values.
+    """
+    from integrations.graphiti.config import GraphitiState
+
+    state = GraphitiState()
+
+    return state
+
+
+# =============================================================================
+# Test Data Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def sample_episode_data():
+    """Sample episode data for testing.
+
+    Provides realistic episode data structure for testing memory operations.
+
+    Returns:
+        dict: Sample episode data.
+    """
+    return {
+        "episode_id": "episode_123",
+        "content": "Test episode content about a feature implementation",
+        "metadata": {
+            "task_id": "task_001",
+            "timestamp": "2024-01-01T00:00:00Z",
+            "type": "implementation",
+        },
+        "session_id": "test_session",
+        "user_id": "test_user",
+    }
+
+
+@pytest.fixture
+def sample_memory_nodes():
+    """Sample memory nodes for testing.
+
+    Provides realistic node data for testing graph operations.
+
+    Returns:
+        list: List of sample memory node dictionaries.
+    """
+    return [
+        {
+            "uuid": "node_1",
+            "name": "Feature Implementation",
+            "label": "CONCEPT",
+            "summary": "Implementation of new feature",
+            "created_at": "2024-01-01T00:00:00Z",
+        },
+        {
+            "uuid": "node_2",
+            "name": "Bug Fix",
+            "label": "CONCEPT",
+            "summary": "Fixed critical bug",
+            "created_at": "2024-01-02T00:00:00Z",
+        },
+    ]
+
+
+@pytest.fixture
+def sample_search_results():
+    """Sample search results for testing.
+
+    Provides realistic search result data for testing search operations.
+
+    Returns:
+        list: List of sample search result dictionaries.
+    """
+    return [
+        {
+            "uuid": "result_1",
+            "name": "Search Result 1",
+            "summary": "First search result",
+            "score": 0.95,
+        },
+        {
+            "uuid": "result_2",
+            "name": "Search Result 2",
+            "summary": "Second search result",
+            "score": 0.87,
+        },
+    ]
+
+
+# =============================================================================
+# Helper Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def clean_env():
+    """Fixture to ensure clean environment for each test.
+
+    Removes all Graphiti-related environment variables before the test
+    and restores them afterward.
+
+    Yields:
+        dict: Dictionary of original environment values.
+    """
+    # Store original env vars
+    env_keys = [
+        "GRAPHITI_ENABLED",
+        "GRAPHITI_LLM_PROVIDER",
+        "GRAPHITI_EMBEDDER_PROVIDER",
+        "GRAPHITI_DATABASE",
+        "GRAPHITI_DB_PATH",
+        "OPENAI_API_KEY",
+        "OPENAI_MODEL",
+        "OPENAI_EMBEDDING_MODEL",
+        "ANTHROPIC_API_KEY",
+        "GRAPHITI_ANTHROPIC_MODEL",
+        "AZURE_OPENAI_API_KEY",
+        "AZURE_OPENAI_BASE_URL",
+        "AZURE_OPENAI_LLM_DEPLOYMENT",
+        "AZURE_OPENAI_EMBEDDING_DEPLOYMENT",
+        "VOYAGE_API_KEY",
+        "VOYAGE_EMBEDDING_MODEL",
+        "GOOGLE_API_KEY",
+        "GOOGLE_LLM_MODEL",
+        "GOOGLE_EMBEDDING_MODEL",
+        "OPENROUTER_API_KEY",
+        "OPENROUTER_BASE_URL",
+        "OPENROUTER_LLM_MODEL",
+        "OPENROUTER_EMBEDDING_MODEL",
+        "OLLAMA_BASE_URL",
+        "OLLAMA_LLM_MODEL",
+        "OLLAMA_EMBEDDING_MODEL",
+        "OLLAMA_EMBEDDING_DIM",
+    ]
+
+    original = {}
+    for key in env_keys:
+        original[key] = os.environ.get(key)
+        if key in os.environ:
+            os.environ.pop(key)
+
+    yield original
+
+    # Restore original values
+    for key, value in original.items():
+        if value is not None:
+            os.environ[key] = value
@@ -0,0 +1,216 @@
+"""
+Tests for integrations.graphiti.providers_pkg.cross_encoder module.
+
+Tests cover:
+1. create_cross_encoder():
+   - Returns None for non-Ollama providers
+   - Returns None when llm_client is None
+   - Returns None on ImportError (graphiti_core not available)
+   - Returns None on Exception during creation
+   - Creates correct base_url for Ollama
+   - Creates LLMConfig with correct parameters
+"""
+
+import builtins
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+# =============================================================================
+# Test Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def mock_config():
+    """Mock GraphitiConfig."""
+    config = MagicMock()
+    config.llm_provider = "ollama"
+    config.ollama_base_url = "http://localhost:11434"
+    config.ollama_llm_model = "llama3.2"
+    return config
+
+
+@pytest.fixture
+def mock_llm_client():
+    """Mock LLM client."""
+    return MagicMock()
+
+
+@pytest.fixture
+def graphiti_core_mocks():
+    """Mock graphiti_core modules and capture LLMConfig calls."""
+    captured_config = {}
+
+    def capture_llm_config(**kwargs):
+        captured_config.update(kwargs)
+        return MagicMock()
+
+    with patch.dict(
+        "sys.modules",
+        {
+            "graphiti_core": MagicMock(),
+            "graphiti_core.cross_encoder": MagicMock(),
+            "graphiti_core.cross_encoder.openai_reranker_client": MagicMock(),
+            "graphiti_core.llm_client": MagicMock(),
+            "graphiti_core.llm_client.config": MagicMock(),
+        },
+    ):
+        from graphiti_core.cross_encoder.openai_reranker_client import (
+            OpenAIRerankerClient,
+        )
+        from graphiti_core.llm_client.config import LLMConfig
+
+        LLMConfig.side_effect = capture_llm_config
+        OpenAIRerankerClient.return_value = MagicMock()
+
+        yield captured_config
+
+
+# =============================================================================
+# Test create_cross_encoder()
+# =============================================================================
+
+
+class TestCreateCrossEncoder:
+    """Tests for create_cross_encoder() function."""
+
+    def test_returns_none_for_non_ollama_provider(self, mock_config, mock_llm_client):
+        """Test create_cross_encoder returns None for non-Ollama providers."""
+        mock_config.llm_provider = "openai"
+
+        import integrations.graphiti.providers_pkg.cross_encoder as ce_module
+
+        # The function returns None for non-ollama providers
+        result = ce_module.create_cross_encoder(mock_config, mock_llm_client)
+
+        assert result is None
+
+    def test_returns_none_for_anthropic_provider(self, mock_config, mock_llm_client):
+        """Test create_cross_encoder returns None for Anthropic provider."""
+        mock_config.llm_provider = "anthropic"
+
+        from integrations.graphiti.providers_pkg.cross_encoder import (
+            create_cross_encoder,
+        )
+
+        result = create_cross_encoder(mock_config, mock_llm_client)
+
+        assert result is None
+
+    def test_returns_none_for_google_provider(self, mock_config, mock_llm_client):
+        """Test create_cross_encoder returns None for Google provider."""
+        mock_config.llm_provider = "google"
+
+        from integrations.graphiti.providers_pkg.cross_encoder import (
+            create_cross_encoder,
+        )
+
+        result = create_cross_encoder(mock_config, mock_llm_client)
+
+        assert result is None
+
+    def test_returns_none_when_llm_client_is_none(self, mock_config):
+        """Test create_cross_encoder returns None when llm_client is None."""
+        from integrations.graphiti.providers_pkg.cross_encoder import (
+            create_cross_encoder,
+        )
+
+        result = create_cross_encoder(mock_config, llm_client=None)
+
+        assert result is None
+
+    def test_base_url_without_v1_gets_suffix_added(
+        self, mock_config, mock_llm_client, graphiti_core_mocks
+    ):
+        """Test that base_url without /v1 gets /v1 suffix added."""
+        mock_config.ollama_base_url = "http://localhost:11434"
+
+        from integrations.graphiti.providers_pkg.cross_encoder import (
+            create_cross_encoder,
+        )
+
+        _ = create_cross_encoder(mock_config, mock_llm_client)
+
+        # Verify base_url was captured and has /v1 suffix added
+        assert "base_url" in graphiti_core_mocks
+        assert graphiti_core_mocks["base_url"] == "http://localhost:11434/v1"
+
+    def test_base_url_with_v1_is_preserved(
+        self, mock_config, mock_llm_client, graphiti_core_mocks
+    ):
+        """Test that base_url with /v1 suffix is preserved."""
+        mock_config.ollama_base_url = "http://localhost:11434/v1"
+
+        from integrations.graphiti.providers_pkg.cross_encoder import (
+            create_cross_encoder,
+        )
+
+        _ = create_cross_encoder(mock_config, mock_llm_client)
+
+        # Verify base_url was preserved with /v1 suffix
+        assert "base_url" in graphiti_core_mocks
+        assert graphiti_core_mocks["base_url"] == "http://localhost:11434/v1"
+
+    def test_import_error_returns_none(self, mock_config, mock_llm_client):
+        """Test create_cross_encoder returns None when graphiti_core modules not available."""
+        from integrations.graphiti.providers_pkg.cross_encoder import (
+            create_cross_encoder,
+        )
+
+        # Mock the import to raise ImportError
+        original_import = builtins.__import__
+
+        def mock_import(name, *args, **kwargs):
+            if name == "graphiti_core.cross_encoder.openai_reranker_client":
+                raise ImportError("graphiti_core not installed")
+            if name == "graphiti_core.llm_client.config":
+                raise ImportError("graphiti_core not installed")
+            return original_import(name, *args, **kwargs)
+
+        with patch("builtins.__import__", side_effect=mock_import):
+            result = create_cross_encoder(mock_config, mock_llm_client)
+
+        assert result is None
+
+    def test_exception_during_creation_returns_none(self, mock_config, mock_llm_client):
+        """Test create_cross_encoder returns None on exception during creation."""
+        from integrations.graphiti.providers_pkg.cross_encoder import (
+            create_cross_encoder,
+        )
+
+        # Mock the graphiti_core modules but make LLMConfig raise an exception
+        with patch.dict(
+            "sys.modules",
+            {
+                "graphiti_core": MagicMock(),
+                "graphiti_core.cross_encoder": MagicMock(),
+                "graphiti_core.cross_encoder.openai_reranker_client": MagicMock(),
+                "graphiti_core.llm_client": MagicMock(),
+                "graphiti_core.llm_client.config": MagicMock(),
+            },
+        ):
+            from graphiti_core.llm_client.config import LLMConfig
+
+            # Make LLMConfig raise an exception
+            LLMConfig.side_effect = Exception("Config creation failed")
+
+            result = create_cross_encoder(mock_config, mock_llm_client)
+
+        assert result is None
+
+
+# =============================================================================
+# Test module exports
+# =============================================================================
+
+
+class TestModuleExports:
+    """Tests for cross_encoder module exports."""
+
+    def test_create_cross_encoder_is_exported(self):
+        """Test that create_cross_encoder is exported from module."""
+        from integrations.graphiti.providers_pkg import cross_encoder
+
+        assert hasattr(cross_encoder, "create_cross_encoder")
+        assert callable(cross_encoder.create_cross_encoder)
@@ -0,0 +1,238 @@
+"""
+Tests for integrations.graphiti.__init__ module.
+
+Tests cover:
+- __getattr__ lazy import functionality
+- Direct imports (GraphitiConfig, validate_graphiti_config)
+- Invalid attribute access raises AttributeError
+"""
+
+import sys
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+
+class TestInitModuleDirectImports:
+    """Test direct imports that don't require lazy loading."""
+
+    def test_import_graphiti_config_directly(self):
+        """Test GraphitiConfig can be imported directly."""
+        from integrations.graphiti import GraphitiConfig
+
+        assert GraphitiConfig is not None
+
+    def test_import_validate_graphiti_config_directly(self):
+        """Test validate_graphiti_config can be imported directly."""
+        from integrations.graphiti import validate_graphiti_config
+
+        assert validate_graphiti_config is not None
+
+    def test___all___exports(self):
+        """Test __all__ contains expected exports."""
+        import integrations.graphiti as graphiti_module
+
+        expected_all = [
+            "GraphitiConfig",
+            "validate_graphiti_config",
+            "GraphitiMemory",
+            "create_llm_client",
+            "create_embedder",
+        ]
+        assert graphiti_module.__all__ == expected_all
+
+
+class TestInitModuleLazyImports:
+    """Test __getattr__ lazy import functionality."""
+
+    @pytest.fixture
+    def mock_memory_module(self):
+        """Mock the memory module."""
+        memory_mock = MagicMock()
+        memory_mock.GraphitiMemory = MagicMock
+        return memory_mock
+
+    @pytest.fixture
+    def mock_providers_module(self):
+        """Mock the providers module."""
+        providers_mock = MagicMock()
+        providers_mock.create_llm_client = MagicMock(return_value=AsyncMock())
+        providers_mock.create_embedder = MagicMock(return_value=AsyncMock())
+        return providers_mock
+
+    def test_getattr_graphiti_memory_lazy_import(self, mock_memory_module):
+        """Test accessing GraphitiMemory triggers lazy import."""
+        import integrations.graphiti as graphiti_module
+
+        with patch.dict(
+            "sys.modules",
+            {
+                "integrations.graphiti.memory": mock_memory_module,
+            },
+        ):
+            # Access the attribute via __getattr__
+            result = graphiti_module.__getattr__("GraphitiMemory")
+
+            assert result == mock_memory_module.GraphitiMemory
+
+    def test_getattr_create_llm_client_lazy_import(self, mock_providers_module):
+        """Test accessing create_llm_client triggers lazy import."""
+        import integrations.graphiti as graphiti_module
+
+        with patch.dict(
+            "sys.modules",
+            {
+                "integrations.graphiti.providers": mock_providers_module,
+            },
+        ):
+            result = graphiti_module.__getattr__("create_llm_client")
+
+            assert result == mock_providers_module.create_llm_client
+
+    def test_getattr_create_embedder_lazy_import(self, mock_providers_module):
+        """Test accessing create_embedder triggers lazy import."""
+        import integrations.graphiti as graphiti_module
+
+        with patch.dict(
+            "sys.modules",
+            {
+                "integrations.graphiti.providers": mock_providers_module,
+            },
+        ):
+            result = graphiti_module.__getattr__("create_embedder")
+
+            assert result == mock_providers_module.create_embedder
+
+    def test_getattr_invalid_attribute_raises_attribute_error(self):
+        """Test accessing invalid attribute raises AttributeError."""
+        import integrations.graphiti as graphiti_module
+
+        with pytest.raises(AttributeError) as exc_info:
+            graphiti_module.__getattr__("NonExistentAttribute")
+
+        assert "has no attribute" in str(exc_info.value)
+        assert "NonExistentAttribute" in str(exc_info.value)
+
+    def test_getattr_empty_string_attribute(self):
+        """Test accessing empty string attribute raises AttributeError."""
+        import integrations.graphiti as graphiti_module
+
+        with pytest.raises(AttributeError):
+            graphiti_module.__getattr__("")
+
+    def test_getattr_case_sensitive(self):
+        """Test that __getattr__ is case-sensitive."""
+        import integrations.graphiti as graphiti_module
+
+        # lowercase should fail
+        with pytest.raises(AttributeError):
+            graphiti_module.__getattr__("graphitimemory")
+
+        # mixed case should fail
+        with pytest.raises(AttributeError):
+            graphiti_module.__getattr__("Graphiti_Memory")
+
+
+class TestInitModuleAccessPatterns:
+    """Test various access patterns for the init module."""
+
+    def test_hasattr_on_graphiti_memory(self):
+        """Test hasattr works correctly with lazy imports."""
+        import integrations.graphiti as graphiti_module
+
+        # Mock the import
+        with patch.dict(
+            "sys.modules",
+            {
+                "integrations.graphiti.memory": MagicMock(GraphitiMemory=MagicMock),
+            },
+        ):
+            # hasattr should call __getattr__ and not raise
+            result = hasattr(graphiti_module, "GraphitiMemory")
+            assert result is True
+
+    def test_hasattr_on_invalid_attribute(self):
+        """Test hasattr returns False for invalid attributes."""
+        import integrations.graphiti as graphiti_module
+
+        result = hasattr(graphiti_module, "InvalidAttribute")
+        assert result is False
+
+    def test_getattr_on_existing_direct_import(self):
+        """Test __getattr__ is not called for direct imports."""
+        import integrations.graphiti as graphiti_module
+
+        # GraphitiConfig is imported directly, so __getattr__ shouldn't be called
+        # This tests that the normal import mechanism works
+        assert hasattr(graphiti_module, "GraphitiConfig")
+
+    def test_module_docstring(self):
+        """Test the module has a docstring."""
+        import integrations.graphiti as graphiti_module
+
+        assert graphiti_module.__doc__ is not None
+        assert "Graphiti" in graphiti_module.__doc__
+
+
+class TestInitModuleIntegration:
+    """Integration tests for the init module."""
+
+    def test_import_star(self):
+        """Test 'from integrations.graphiti import *' includes direct imports."""
+        # Create a new namespace for the import
+        namespace = {}
+        exec("from integrations.graphiti import *", namespace)
+
+        # Direct imports should be available
+        assert "GraphitiConfig" in namespace
+        assert "validate_graphiti_config" in namespace
+
+    def test_reimport_does_not_fail(self):
+        """Test that re-importing the module doesn't cause issues."""
+        import importlib
+
+        import integrations.graphiti
+
+        # Reload the module
+        importlib.reload(integrations.graphiti)
+
+        # Should still work
+        assert hasattr(integrations.graphiti, "GraphitiConfig")
+
+    @pytest.mark.slow
+    def test_concurrent_attribute_access(self):
+        """Test that concurrent attribute access doesn't cause issues."""
+        import concurrent.futures
+
+        import integrations.graphiti as graphiti_module
+
+        # Mock the imports
+        with patch.dict(
+            "sys.modules",
+            {
+                "integrations.graphiti.memory": MagicMock(GraphitiMemory=MagicMock),
+                "integrations.graphiti.providers": MagicMock(
+                    create_llm_client=MagicMock(return_value=AsyncMock()),
+                    create_embedder=MagicMock(return_value=AsyncMock()),
+                ),
+            },
+        ):
+
+            def access_attribute(attr_name):
+                try:
+                    return getattr(graphiti_module, attr_name)
+                except AttributeError:
+                    return None
+
+            # Access multiple attributes concurrently
+            with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
+                futures = [
+                    executor.submit(access_attribute, "GraphitiMemory"),
+                    executor.submit(access_attribute, "create_llm_client"),
+                    executor.submit(access_attribute, "create_embedder"),
+                ]
+                results = [f.result() for f in concurrent.futures.as_completed(futures)]
+
+            # All should succeed
+            assert len(results) == 3
+            assert all(r is not None for r in results)
@@ -0,0 +1,425 @@
+"""
+Tests for integrations.graphiti.memory module.
+
+This module is a backward compatibility facade that re-exports from
+queries_pkg and provides convenience functions.
+"""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+# =============================================================================
+# Test Fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def mock_spec_dir(tmp_path):
+    """Create a temporary spec directory."""
+    spec_dir = tmp_path / "specs" / "001-test"
+    spec_dir.mkdir(parents=True)
+    return spec_dir
+
+
+@pytest.fixture
+def mock_project_dir(tmp_path):
+    """Create a temporary project directory."""
+    project_dir = tmp_path / "project"
+    project_dir.mkdir(parents=True)
+    return project_dir
+
+
+# =============================================================================
+# Tests for module imports
+# =============================================================================
+
+
+class TestModuleImports:
+    """Test that all expected exports are available."""
+
+    def test_import_GraphitiMemory(self):
+        """Test GraphitiMemory can be imported."""
+        from integrations.graphiti.memory import GraphitiMemory
+
+        assert GraphitiMemory is not None
+
+    def test_import_GroupIdMode(self):
+        """Test GroupIdMode can be imported."""
+        from integrations.graphiti.memory import GroupIdMode
+
+        assert GroupIdMode is not None
+        assert hasattr(GroupIdMode, "SPEC")
+        assert hasattr(GroupIdMode, "PROJECT")
+
+    def test_import_is_graphiti_enabled(self):
+        """Test is_graphiti_enabled can be imported."""
+        from integrations.graphiti.memory import is_graphiti_enabled
+
+        assert is_graphiti_enabled is not None
+
+    def test_import_get_graphiti_memory(self):
+        """Test get_graphiti_memory can be imported."""
+        from integrations.graphiti.memory import get_graphiti_memory
+
+        assert get_graphiti_memory is not None
+
+    def test_import_test_graphiti_connection(self):
+        """Test test_graphiti_connection can be imported."""
+        from integrations.graphiti.memory import test_graphiti_connection
+
+        assert test_graphiti_connection is not None
+
+    def test_import_test_provider_configuration(self):
+        """Test test_provider_configuration can be imported."""
+        from integrations.graphiti.memory import test_provider_configuration
+
+        assert test_provider_configuration is not None
+
+    def test_import_episode_types(self):
+        """Test all episode type constants can be imported."""
+        from integrations.graphiti.memory import (
+            EPISODE_TYPE_CODEBASE_DISCOVERY,
+            EPISODE_TYPE_GOTCHA,
+            EPISODE_TYPE_HISTORICAL_CONTEXT,
+            EPISODE_TYPE_PATTERN,
+            EPISODE_TYPE_QA_RESULT,
+            EPISODE_TYPE_SESSION_INSIGHT,
+            EPISODE_TYPE_TASK_OUTCOME,
+        )
+
+        assert EPISODE_TYPE_SESSION_INSIGHT == "session_insight"
+        assert EPISODE_TYPE_CODEBASE_DISCOVERY == "codebase_discovery"
+        assert EPISODE_TYPE_PATTERN == "pattern"
+        assert EPISODE_TYPE_GOTCHA == "gotcha"
+        assert EPISODE_TYPE_TASK_OUTCOME == "task_outcome"
+        assert EPISODE_TYPE_QA_RESULT == "qa_result"
+        assert EPISODE_TYPE_HISTORICAL_CONTEXT == "historical_context"
+
+    def test_import_MAX_CONTEXT_RESULTS(self):
+        """Test MAX_CONTEXT_RESULTS can be imported."""
+        from integrations.graphiti.memory import MAX_CONTEXT_RESULTS
+
+        assert MAX_CONTEXT_RESULTS is not None
+
+
+# =============================================================================
+# Tests for get_graphiti_memory()
+# =============================================================================
+
+
+class TestGetGraphitiMemory:
+    """Tests for get_graphiti_memory convenience function."""
+
+    def test_returns_graphiti_memory_instance(self, mock_spec_dir, mock_project_dir):
+        """Test get_graphiti_memory returns GraphitiMemory instance."""
+        from integrations.graphiti.memory import get_graphiti_memory
+
+        memory = get_graphiti_memory(mock_spec_dir, mock_project_dir)
+
+        assert memory is not None
+        assert hasattr(memory, "spec_dir")
+        assert hasattr(memory, "project_dir")
+
+    def test_default_group_id_mode_is_project(self, mock_spec_dir, mock_project_dir):
+        """Test default group_id_mode is PROJECT."""
+        from integrations.graphiti.memory import get_graphiti_memory
+        from integrations.graphiti.queries_pkg.schema import GroupIdMode
+
+        memory = get_graphiti_memory(mock_spec_dir, mock_project_dir)
+
+        # Check that group_id_mode defaults to PROJECT
+        assert memory.group_id_mode == GroupIdMode.PROJECT
+
+    def test_spec_group_id_mode(self, mock_spec_dir, mock_project_dir):
+        """Test SPEC group_id_mode can be set."""
+        from integrations.graphiti.memory import get_graphiti_memory
+        from integrations.graphiti.queries_pkg.schema import GroupIdMode
+
+        memory = get_graphiti_memory(mock_spec_dir, mock_project_dir, GroupIdMode.SPEC)
+
+        assert memory.group_id_mode == GroupIdMode.SPEC
+
+    def test_project_group_id_mode(self, mock_spec_dir, mock_project_dir):
+        """Test PROJECT group_id_mode can be set."""
+        from integrations.graphiti.memory import get_graphiti_memory
+        from integrations.graphiti.queries_pkg.schema import GroupIdMode
+
+        memory = get_graphiti_memory(
+            mock_spec_dir, mock_project_dir, GroupIdMode.PROJECT
+        )
+
+        assert memory.group_id_mode == GroupIdMode.PROJECT
+
+
+# =============================================================================
+# Tests for test_graphiti_connection()
+# =============================================================================
+
+
+class TestTestGraphitiConnection:
+    """Tests for test_graphiti_connection function."""
+
+    @pytest.mark.asyncio
+    async def test_returns_false_when_not_enabled(self):
+        """Test returns False when Graphiti not enabled."""
+        from integrations.graphiti.memory import test_graphiti_connection
+
+        with patch("integrations.graphiti.memory.GraphitiConfig") as mock_config_class:
+            mock_config = MagicMock()
+            mock_config.enabled = False
+            mock_config_class.from_env.return_value = mock_config
+
+            success, message = await test_graphiti_connection()
+
+            assert success is False
+            assert "not enabled" in message.lower()
+
+    @pytest.mark.asyncio
+    async def test_returns_false_with_validation_errors(self):
+        """Test returns False when config has validation errors."""
+        from integrations.graphiti.memory import test_graphiti_connection
+
+        with patch("integrations.graphiti.memory.GraphitiConfig") as mock_config_class:
+            mock_config = MagicMock()
+            mock_config.enabled = True
+            mock_config.get_validation_errors.return_value = ["API key missing"]
+            mock_config_class.from_env.return_value = mock_config
+
+            success, message = await test_graphiti_connection()
+
+            assert success is False
+            assert "Configuration errors" in message
+
+    @pytest.mark.asyncio
+    async def test_returns_false_on_import_error(self):
+        """Test returns False when graphiti_core not installed."""
+        from integrations.graphiti.memory import test_graphiti_connection
+
+        with patch("integrations.graphiti.memory.GraphitiConfig") as mock_config_class:
+            mock_config = MagicMock()
+            mock_config.enabled = True
+            mock_config.get_validation_errors.return_value = []
+            mock_config_class.from_env.return_value = mock_config
+
+            # Only raise ImportError for graphiti_core imports
+            import builtins
+
+            original_import = builtins.__import__
+
+            def selective_import_error(name, *args, **kwargs):
+                if "graphiti_core" in name:
+                    raise ImportError(f"No module named '{name}'")
+                return original_import(name, *args, **kwargs)
+
+            with patch("builtins.__import__", side_effect=selective_import_error):
+                success, message = await test_graphiti_connection()
+
+                assert success is False
+                assert "not installed" in message.lower()
+
+    @pytest.mark.slow
+    @pytest.mark.asyncio
+    async def test_returns_true_on_successful_connection(self):
+        """Test returns True when connection succeeds (requires graphiti_core)."""
+        from integrations.graphiti.memory import test_graphiti_connection
+
+        # This test requires graphiti_core to be installed
+        # Marked as slow since it connects to actual database
+        try:
+            success, message = await test_graphiti_connection()
+
+            # If graphiti_core is not installed, success will be False
+            if "not installed" in message.lower():
+                assert success is False
+            # If installed but DB not available, check for connection error
+            elif "connection failed" in message.lower():
+                assert success is False
+            # If everything is set up, should succeed
+            else:
+                # Concrete assertion for successful connection
+                assert success is True, (
+                    f"Expected success=True, got {success} with message: {message}"
+                )
+                assert message, "Message should not be empty for successful connection"
+
+        except AssertionError as e:
+            # Re-raise AssertionError to properly surface test failures
+            raise
+        except Exception as e:
+            # If there's an unexpected error, fail the test with useful info
+            pytest.skip(f"Graphiti connection test failed: {e}")
+
+    @pytest.mark.asyncio
+    async def test_handles_provider_error(self):
+        """Test handles ProviderError during provider creation."""
+        from integrations.graphiti.memory import test_graphiti_connection
+        from integrations.graphiti.providers_pkg.exceptions import ProviderError
+
+        with patch("integrations.graphiti.memory.GraphitiConfig") as mock_config_class:
+            mock_config = MagicMock()
+            mock_config.enabled = True
+            mock_config.get_validation_errors.return_value = []
+            mock_config_class.from_env.return_value = mock_config
+
+            # Mock graphiti_core imports to succeed
+            mock_graphiti = MagicMock()
+            mock_falkordb_driver = MagicMock()
+
+            # Mock provider creation to raise ProviderError
+            with patch("graphiti_providers.create_llm_client") as mock_create_llm:
+                mock_create_llm.side_effect = ProviderError("Test provider error")
+
+                with patch.dict(
+                    "sys.modules",
+                    {
+                        "graphiti_core": MagicMock(Graphiti=mock_graphiti),
+                        "graphiti_core.driver": MagicMock(),
+                        "graphiti_core.driver.falkordb_driver": mock_falkordb_driver,
+                        "graphiti_providers": MagicMock(
+                            ProviderError=ProviderError,
+                            create_embedder=MagicMock(),
+                            create_llm_client=mock_create_llm,
+                        ),
+                    },
+                ):
+                    success, message = await test_graphiti_connection()
+
+                    assert success is False
+                    assert "Provider error" in message
+
+
+# =============================================================================
+# Tests for test_provider_configuration()
+# =============================================================================
+
+
+class TestTestProviderConfiguration:
+    """Tests for test_provider_configuration function."""
+
+    @pytest.mark.asyncio
+    async def test_returns_configuration_status(self):
+        """Test returns dict with configuration status."""
+        pytest.importorskip("graphiti_providers")
+        from integrations.graphiti.memory import test_provider_configuration
+
+        with patch("integrations.graphiti.memory.GraphitiConfig") as mock_config_class:
+            mock_config = MagicMock()
+            mock_config.is_valid.return_value = True
+            mock_config.get_validation_errors.return_value = []
+            mock_config.llm_provider = "openai"
+            mock_config.embedder_provider = "openai"
+            mock_config_class.from_env.return_value = mock_config
+
+            # Mock the test functions
+            with patch(
+                "graphiti_providers.test_llm_connection",
+                return_value=(True, "LLM OK"),
+            ):
+                with patch(
+                    "graphiti_providers.test_embedder_connection",
+                    return_value=(True, "Embedder OK"),
+                ):
+                    results = await test_provider_configuration()
+
+                    assert isinstance(results, dict)
+                    assert results["config_valid"] is True
+                    assert results["validation_errors"] == []
+                    assert results["llm_provider"] == "openai"
+                    assert results["embedder_provider"] == "openai"
+                    assert results["llm_test"]["success"] is True
+                    assert results["embedder_test"]["success"] is True
+
+    @pytest.mark.asyncio
+    async def test_includes_ollama_test_when_ollama_provider(self):
+        """Test includes ollama_test when using ollama provider."""
+        pytest.importorskip("graphiti_providers")
+        from integrations.graphiti.memory import test_provider_configuration
+
+        with patch("integrations.graphiti.memory.GraphitiConfig") as mock_config_class:
+            mock_config = MagicMock()
+            mock_config.is_valid.return_value = True
+            mock_config.get_validation_errors.return_value = []
+            mock_config.llm_provider = "ollama"
+            mock_config.embedder_provider = "openai"
+            mock_config.ollama_base_url = "http://localhost:11434"
+            mock_config_class.from_env.return_value = mock_config
+
+            with patch(
+                "graphiti_providers.test_llm_connection",
+                return_value=(True, "LLM OK"),
+            ):
+                with patch(
+                    "graphiti_providers.test_embedder_connection",
+                    return_value=(True, "Embedder OK"),
+                ):
+                    with patch(
+                        "graphiti_providers.test_ollama_connection",
+                        return_value=(True, "Ollama OK"),
+                    ):
+                        results = await test_provider_configuration()
+
+                        assert "ollama_test" in results
+                        assert results["ollama_test"]["success"] is True
+
+    @pytest.mark.asyncio
+    async def test_omits_ollama_test_when_not_ollama_provider(self):
+        """Test omits ollama_test when not using ollama provider."""
+        pytest.importorskip("graphiti_providers")
+        from integrations.graphiti.memory import test_provider_configuration
+
+        with patch("integrations.graphiti.memory.GraphitiConfig") as mock_config_class:
+            mock_config = MagicMock()
+            mock_config.is_valid.return_value = True
+            mock_config.get_validation_errors.return_value = []
+            mock_config.llm_provider = "openai"
+            mock_config.embedder_provider = "openai"
+            mock_config_class.from_env.return_value = mock_config
+
+            with patch(
+                "graphiti_providers.test_llm_connection",
+                return_value=(True, "LLM OK"),
+            ):
+                with patch(
+                    "graphiti_providers.test_embedder_connection",
+                    return_value=(True, "Embedder OK"),
+                ):
+                    results = await test_provider_configuration()
+
+                    assert "ollama_test" not in results
+
+
+# =============================================================================
+# Tests for __all__ export list
+# =============================================================================
+
+
+class TestAllExports:
+    """Test __all__ contains expected exports."""
+
+    def test_all_exports_defined(self):
+        """Test __all__ is defined and contains expected items."""
+        from integrations.graphiti import memory
+
+        assert hasattr(memory, "__all__")
+        assert isinstance(memory.__all__, list)
+
+        expected_exports = [
+            "GraphitiMemory",
+            "GroupIdMode",
+            "get_graphiti_memory",
+            "is_graphiti_enabled",
+            "test_graphiti_connection",
+            "test_provider_configuration",
+            "MAX_CONTEXT_RESULTS",
+            "EPISODE_TYPE_SESSION_INSIGHT",
+            "EPISODE_TYPE_CODEBASE_DISCOVERY",
+            "EPISODE_TYPE_PATTERN",
+            "EPISODE_TYPE_GOTCHA",
+            "EPISODE_TYPE_TASK_OUTCOME",
+            "EPISODE_TYPE_QA_RESULT",
+            "EPISODE_TYPE_HISTORICAL_CONTEXT",
+        ]
+
+        for export in expected_exports:
+            assert export in memory.__all__, f"{export} not in __all__"
@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""
+Quick test to demonstrate provider-specific database naming.
+
+Shows how Auto Claude automatically generates provider-specific database names
+to prevent embedding dimension mismatches.
+"""
+
+import pytest
+from integrations.graphiti.config import GraphitiConfig
+
+
+@pytest.mark.parametrize(
+    "provider,model,dim",
+    [
+        ("openai", None, None),
+        ("ollama", "embeddinggemma", 768),
+        ("ollama", "qwen3-embedding:0.6b", 1024),
+        ("voyage", None, None),
+        ("google", None, None),
+    ],
+)
+def test_provider_naming(provider, model, dim):
+    """Demonstrate provider-specific database naming."""
+    # Create explicit config without relying on environment
+    config = GraphitiConfig()
+    config.embedder_provider = provider
+    config.openai_embedding_model = "text-embedding-3-small"
+
+    if provider == "ollama" and model:
+        config.ollama_embedding_model = model
+        if dim is not None:
+            config.ollama_embedding_dim = dim
+    elif provider == "voyage":
+        config.voyage_embedding_model = "voyage-3"
+    elif provider == "google":
+        config.google_embedding_model = "text-embedding-004"
+
+    # Get naming info
+    dimension = config.get_embedding_dimension()
+    signature = config.get_provider_signature()
+    db_name = config.get_provider_specific_database_name("auto_claude_memory")
+
+    # Strengthened assertions with exact expected values where known
+    if provider == "openai":
+        assert dimension == 1536, f"OpenAI dimension should be 1536, got {dimension}"
+        assert "openai" in signature.lower(), "OpenAI signature should contain 'openai'"
+        # Signature format is provider_dimension for openai
+        assert signature == "openai_1536", f"Expected 'openai_1536', got '{signature}'"
+    elif provider == "ollama" and model == "embeddinggemma":
+        assert dimension == 768, (
+            f"Ollama gemma dimension should be 768, got {dimension}"
+        )
+        assert signature == f"ollama_{model}_{dimension}", (
+            f"Expected 'ollama_{model}_{dimension}', got '{signature}'"
+        )
+    elif provider == "ollama" and model == "qwen3-embedding:0.6b":
+        assert dimension == 1024, (
+            f"Ollama qwen dimension should be 1024, got {dimension}"
+        )
+        # Colons in model names are replaced with underscores in signature
+        assert signature == "ollama_qwen3-embedding_0_6b_1024", (
+            f"Expected 'ollama_qwen3-embedding_0_6b_1024', got '{signature}'"
+        )
+    elif provider == "voyage":
+        assert dimension == 1024, f"Voyage dimension should be 1024, got {dimension}"
+        assert signature == "voyage_1024", f"Expected 'voyage_1024', got '{signature}'"
+    elif provider == "google":
+        assert dimension == 768, f"Google dimension should be 768, got {dimension}"
+        assert signature == "google_768", f"Expected 'google_768', got '{signature}'"
+
+    # Verify signature appears in db_name
+    assert signature is not None and signature != "", (
+        f"Signature should be non-empty for {provider}"
+    )
+    assert signature in db_name, (
+        f"Signature '{signature}' should appear in db_name '{db_name}' for {provider}"
+    )
@@ -0,0 +1,149 @@
+"""
+Unit tests for Azure OpenAI embedder provider.
+
+Tests cover:
+- create_azure_openai_embedder factory function
+- ProviderNotInstalled exception handling
+- ProviderError for missing configuration
+"""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+from integrations.graphiti.providers_pkg.embedder_providers.azure_openai_embedder import (
+    create_azure_openai_embedder,
+)
+from integrations.graphiti.providers_pkg.exceptions import (
+    ProviderError,
+    ProviderNotInstalled,
+)
+
+# =============================================================================
+# Test create_azure_openai_embedder
+# =============================================================================
+
+
+class TestCreateAzureOpenAIEmbedder:
+    """Test create_azure_openai_embedder factory function."""
+
+    @pytest.fixture
+    def mock_config(self):
+        """Create a mock GraphitiConfig."""
+        config = MagicMock()
+        config.azure_openai_api_key = "test-azure-key"
+        config.azure_openai_base_url = "https://test.openai.azure.com"
+        config.azure_openai_embedding_deployment = "test-embedding-deployment"
+        return config
+
+    @pytest.mark.slow
+    def test_create_azure_openai_embedder_success(self, mock_config):
+        """Test create_azure_openai_embedder returns embedder with valid config."""
+        mock_azure_client = MagicMock()
+        mock_embedder = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.embedder_providers.azure_openai_embedder.AsyncOpenAI",
+            return_value=mock_azure_client,
+        ):
+            with patch(
+                "graphiti_core.embedder.azure_openai.AzureOpenAIEmbedderClient",
+                return_value=mock_embedder,
+            ):
+                result = create_azure_openai_embedder(mock_config)
+                assert result == mock_embedder
+
+    def test_create_azure_openai_embedder_success_fast(self, mock_config):
+        """Fast test for create_azure_openai_embedder success path."""
+        mock_embedder = MagicMock()
+
+        # Mock the graphiti_core imports
+        with patch.dict(
+            "sys.modules",
+            {
+                "graphiti_core": MagicMock(),
+                "graphiti_core.embedder": MagicMock(),
+                "graphiti_core.embedder.azure_openai": MagicMock(),
+            },
+        ):
+            from graphiti_core.embedder.azure_openai import AzureOpenAIEmbedderClient
+
+            AzureOpenAIEmbedderClient.return_value = mock_embedder
+
+            result = create_azure_openai_embedder(mock_config)
+
+            # Verify the embedder was created and returned
+            AzureOpenAIEmbedderClient.assert_called_once()
+            assert result == mock_embedder
+
+    def test_create_azure_openai_embedder_missing_api_key(self, mock_config):
+        """Test create_azure_openai_embedder raises ProviderError for missing API key."""
+        mock_config.azure_openai_api_key = None
+
+        with pytest.raises(ProviderError) as exc_info:
+            create_azure_openai_embedder(mock_config)
+
+        assert "AZURE_OPENAI_API_KEY" in str(exc_info.value)
+
+    def test_create_azure_openai_embedder_missing_base_url(self, mock_config):
+        """Test create_azure_openai_embedder raises ProviderError for missing base URL."""
+        mock_config.azure_openai_base_url = None
+
+        with pytest.raises(ProviderError) as exc_info:
+            create_azure_openai_embedder(mock_config)
+
+        assert "AZURE_OPENAI_BASE_URL" in str(exc_info.value)
+
+    def test_create_azure_openai_embedder_missing_deployment(self, mock_config):
+        """Test create_azure_openai_embedder raises ProviderError for missing deployment."""
+        mock_config.azure_openai_embedding_deployment = None
+
+        with pytest.raises(ProviderError) as exc_info:
+            create_azure_openai_embedder(mock_config)
+
+        assert "AZURE_OPENAI_EMBEDDING_DEPLOYMENT" in str(exc_info.value)
+
+    def test_create_azure_openai_embedder_import_error(self, mock_config):
+        """Test create_azure_openai_embedder raises ProviderNotInstalled on ImportError."""
+        # Mock the import to raise ImportError
+        import builtins
+
+        original_import = builtins.__import__
+
+        def mock_import(name, *args, **kwargs):
+            if name == "graphiti_core.embedder.azure_openai":
+                raise ImportError("graphiti-core not installed")
+            return original_import(name, *args, **kwargs)
+
+        with patch("builtins.__import__", side_effect=mock_import):
+            with pytest.raises(ProviderNotInstalled) as exc_info:
+                create_azure_openai_embedder(mock_config)
+
+            assert "graphiti-core" in str(exc_info.value)
+
+    @pytest.mark.slow
+    def test_create_azure_openai_embedder_passes_config_correctly(self, mock_config):
+        """Test create_azure_openai_embedder passes config values correctly."""
+        mock_azure_client = MagicMock()
+        mock_embedder = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.embedder_providers.azure_openai_embedder.AsyncOpenAI",
+            return_value=mock_azure_client,
+        ) as mock_openai:
+            with patch(
+                "graphiti_core.embedder.azure_openai.AzureOpenAIEmbedderClient",
+                return_value=mock_embedder,
+            ) as mock_azure_embedder:
+                create_azure_openai_embedder(mock_config)
+
+                # Verify AsyncOpenAI was called with correct arguments
+                mock_openai.assert_called_once_with(
+                    base_url=mock_config.azure_openai_base_url,
+                    api_key=mock_config.azure_openai_api_key,
+                )
+
+                # Verify AzureOpenAIEmbedderClient was called with correct arguments
+                mock_azure_embedder.assert_called_once_with(
+                    azure_client=mock_azure_client,
+                    model=mock_config.azure_openai_embedding_deployment,
+                )
@@ -0,0 +1,252 @@
+"""
+Tests for integrations.graphiti.providers module.
+
+This module is a re-export facade that re-exports all public APIs
+from the graphiti_providers package.
+"""
+
+import pytest
+
+# Expected exports from integrations.graphiti.providers module
+EXPECTED_EXPORTS = [
+    "ProviderError",
+    "ProviderNotInstalled",
+    "create_llm_client",
+    "create_embedder",
+    "create_cross_encoder",
+    "EMBEDDING_DIMENSIONS",
+    "get_expected_embedding_dim",
+    "validate_embedding_config",
+    "test_llm_connection",
+    "test_embedder_connection",
+    "test_ollama_connection",
+    "is_graphiti_enabled",
+    "get_graph_hints",
+]
+
+# =============================================================================
+# Tests for module imports
+# =============================================================================
+
+
+class TestModuleImports:
+    """Test that all expected exports are available."""
+
+    def test_import_ProviderError(self):
+        """Test ProviderError can be imported."""
+        from integrations.graphiti.providers import ProviderError
+
+        assert ProviderError is not None
+        # Should be an exception class
+        assert issubclass(ProviderError, Exception)
+
+    def test_import_ProviderNotInstalled(self):
+        """Test ProviderNotInstalled can be imported."""
+        from integrations.graphiti.providers import ProviderNotInstalled
+
+        assert ProviderNotInstalled is not None
+        # Should be an exception class
+        assert issubclass(ProviderNotInstalled, Exception)
+
+    def test_import_create_llm_client(self):
+        """Test create_llm_client can be imported."""
+        from integrations.graphiti.providers import create_llm_client
+
+        assert create_llm_client is not None
+        assert callable(create_llm_client)
+
+    def test_import_create_embedder(self):
+        """Test create_embedder can be imported."""
+        from integrations.graphiti.providers import create_embedder
+
+        assert create_embedder is not None
+        assert callable(create_embedder)
+
+    def test_import_create_cross_encoder(self):
+        """Test create_cross_encoder can be imported."""
+        from integrations.graphiti.providers import create_cross_encoder
+
+        assert create_cross_encoder is not None
+        assert callable(create_cross_encoder)
+
+    def test_import_EMBEDDING_DIMENSIONS(self):
+        """Test EMBEDDING_DIMENSIONS can be imported."""
+        from integrations.graphiti.providers import EMBEDDING_DIMENSIONS
+
+        assert EMBEDDING_DIMENSIONS is not None
+        assert isinstance(EMBEDDING_DIMENSIONS, dict)
+
+    def test_import_get_expected_embedding_dim(self):
+        """Test get_expected_embedding_dim can be imported."""
+        from integrations.graphiti.providers import get_expected_embedding_dim
+
+        assert get_expected_embedding_dim is not None
+        assert callable(get_expected_embedding_dim)
+
+    def test_import_validate_embedding_config(self):
+        """Test validate_embedding_config can be imported."""
+        from integrations.graphiti.providers import validate_embedding_config
+
+        assert validate_embedding_config is not None
+        assert callable(validate_embedding_config)
+
+    def test_import_test_llm_connection(self):
+        """Test test_llm_connection can be imported."""
+        from integrations.graphiti.providers import test_llm_connection
+
+        assert test_llm_connection is not None
+        assert callable(test_llm_connection)
+
+    def test_import_test_embedder_connection(self):
+        """Test test_embedder_connection can be imported."""
+        from integrations.graphiti.providers import test_embedder_connection
+
+        assert test_embedder_connection is not None
+        assert callable(test_embedder_connection)
+
+    def test_import_test_ollama_connection(self):
+        """Test test_ollama_connection can be imported."""
+        from integrations.graphiti.providers import test_ollama_connection
+
+        assert test_ollama_connection is not None
+        assert callable(test_ollama_connection)
+
+    def test_import_is_graphiti_enabled(self):
+        """Test is_graphiti_enabled can be imported."""
+        from integrations.graphiti.providers import is_graphiti_enabled
+
+        assert is_graphiti_enabled is not None
+        assert callable(is_graphiti_enabled)
+
+    def test_import_get_graph_hints(self):
+        """Test get_graph_hints can be imported."""
+        from integrations.graphiti.providers import get_graph_hints
+
+        assert get_graph_hints is not None
+        assert callable(get_graph_hints)
+
+
+# =============================================================================
+# Tests for __all__ export list
+# =============================================================================
+
+
+class TestAllExports:
+    """Test __all__ contains expected exports."""
+
+    def test_all_exports_defined(self):
+        """Test __all__ is defined and contains expected items."""
+        from integrations.graphiti import providers
+
+        assert hasattr(providers, "__all__")
+        assert isinstance(providers.__all__, list)
+
+        for export in EXPECTED_EXPORTS:
+            assert export in providers.__all__, f"{export} not in __all__"
+
+    def test_all_exports_count(self):
+        """Test __all__ contains the expected number of exports."""
+        from integrations.graphiti import providers
+
+        # Should have same number of exports as EXPECTED_EXPORTS list
+        assert len(providers.__all__) == len(EXPECTED_EXPORTS)
+
+
+# =============================================================================
+# Tests for module docstring and metadata
+# =============================================================================
+
+
+class TestModuleMetadata:
+    """Test module has proper documentation."""
+
+    def test_module_has_docstring(self):
+        """Test module has docstring."""
+        import integrations.graphiti.providers
+
+        assert integrations.graphiti.providers.__doc__ is not None
+        assert len(integrations.graphiti.providers.__doc__) > 0
+
+
+# =============================================================================
+# Tests for re-export behavior
+# =============================================================================
+
+
+class TestReExportBehavior:
+    """Test that re-exports work correctly."""
+
+    def test_ProviderError_is_exception(self):
+        """Test ProviderError can be raised and caught."""
+        from integrations.graphiti.providers import ProviderError
+
+        with pytest.raises(ProviderError):
+            raise ProviderError("Test error")
+
+    def test_ProviderNotInstalled_is_exception(self):
+        """Test ProviderNotInstalled can be raised and caught."""
+        from integrations.graphiti.providers import ProviderNotInstalled
+
+        with pytest.raises(ProviderNotInstalled):
+            raise ProviderNotInstalled("Test error")
+
+    def test_ProviderNotInstalled_subclass_of_ProviderError(self):
+        """Test ProviderNotInstalled is a subclass of ProviderError."""
+        from integrations.graphiti.providers import ProviderError, ProviderNotInstalled
+
+        assert issubclass(ProviderNotInstalled, ProviderError)
+
+    def test_EMBEDDING_DIMENSIONS_has_expected_keys(self):
+        """Test EMBEDDING_DIMENSIONS has expected model keys."""
+        from integrations.graphiti.providers import EMBEDDING_DIMENSIONS
+
+        # Check that expected model names exist in EMBEDDING_DIMENSIONS
+        # Note: EMBEDDING_DIMENSIONS is keyed by model name, not provider name
+        expected_models = [
+            "text-embedding-3-small",  # OpenAI
+            "voyage-3",  # Voyage AI
+            "nomic-embed-text",  # Ollama
+            "all-minilm",  # Ollama
+        ]
+
+        for model in expected_models:
+            assert model in EMBEDDING_DIMENSIONS, f"{model} not in EMBEDDING_DIMENSIONS"
+            assert isinstance(EMBEDDING_DIMENSIONS[model], int)
+
+
+# =============================================================================
+# Tests for namespace integrity
+# =============================================================================
+
+
+class TestNamespaceIntegrity:
+    """Test module namespace remains consistent."""
+
+    def test_exports_are_accessible(self):
+        """Test all exports in __all__ are accessible."""
+        from integrations.graphiti import providers
+
+        for name in providers.__all__:
+            # Each export should be accessible
+            assert hasattr(providers, name), f"{name} not accessible"
+
+    def test_import_from_module_works(self):
+        """Test 'from' imports work correctly."""
+        # This tests the re-export mechanism
+        from integrations.graphiti.providers import (
+            ProviderError,
+            create_embedder,
+            create_llm_client,
+        )
+
+        assert ProviderError is not None
+        assert create_llm_client is not None
+        assert create_embedder is not None
+
+    def test_module_level_import_works(self):
+        """Test module-level import works."""
+        import integrations.graphiti.providers as providers
+
+        assert providers.ProviderError is not None
+        assert providers.create_llm_client is not None
+        assert providers.create_embedder is not None
@@ -0,0 +1,256 @@
+"""
+Unit tests for Google embedder provider.
+
+Tests cover:
+- create_google_embedder factory function
+- GoogleEmbedder class (create, create_batch methods)
+- ProviderNotInstalled exception handling
+- ProviderError for missing configuration
+"""
+
+import sys
+from unittest.mock import MagicMock, patch
+
+import pytest
+from integrations.graphiti.providers_pkg.embedder_providers.google_embedder import (
+    DEFAULT_GOOGLE_EMBEDDING_MODEL,
+    GoogleEmbedder,
+    create_google_embedder,
+)
+from integrations.graphiti.providers_pkg.exceptions import (
+    ProviderError,
+    ProviderNotInstalled,
+)
+
+# =============================================================================
+# Pytest fixtures
+# =============================================================================
+
+
+@pytest.fixture
+def google_genai_mock():
+    """Mock google.generativeai module with common setup."""
+    mock_genai = MagicMock()
+    mock_genai.configure = MagicMock()
+    mock_genai.embed_content = MagicMock(return_value={"embedding": [0.1, 0.2, 0.3]})
+    return mock_genai
+
+
+# =============================================================================
+# Test GoogleEmbedder class
+# =============================================================================
+
+
+class TestGoogleEmbedder:
+    """Test GoogleEmbedder class."""
+
+    def test_google_embedder_init_success(self, google_genai_mock):
+        """Test GoogleEmbedder initializes with API key and model."""
+        # Inject mock into sys.modules before importing
+        with patch.dict(sys.modules, {"google.generativeai": google_genai_mock}):
+            embedder = GoogleEmbedder(api_key="test-key", model="test-model")
+
+            assert embedder.api_key == "test-key"
+            assert embedder.model == "test-model"
+            google_genai_mock.configure.assert_called_once_with(api_key="test-key")
+
+    def test_google_embedder_init_default_model(self, google_genai_mock):
+        """Test GoogleEmbedder uses default model when not specified."""
+        # Inject mock into sys.modules before importing
+        with patch.dict(sys.modules, {"google.generativeai": google_genai_mock}):
+            embedder = GoogleEmbedder(api_key="test-key")
+
+            assert embedder.model == DEFAULT_GOOGLE_EMBEDDING_MODEL
+
+    def test_google_embedder_init_import_error(self):
+        """Test GoogleEmbedder raises ProviderNotInstalled on ImportError."""
+        import builtins
+
+        original_import = builtins.__import__
+
+        def mock_import(name, *args, **kwargs):
+            if name == "google.generativeai" or name.startswith("google.generativeai."):
+                raise ImportError("google-generativeai not installed")
+            return original_import(name, *args, **kwargs)
+
+        # Remove google.generativeai from sys.modules if present
+        # to ensure the import actually goes through __import__
+        with patch.dict(sys.modules, {"google.generativeai": None}):
+            with patch("builtins.__import__", side_effect=mock_import):
+                with pytest.raises(ProviderNotInstalled) as exc_info:
+                    GoogleEmbedder(api_key="test-key")
+
+                assert "google-generativeai" in str(exc_info.value)
+
+    @pytest.mark.asyncio
+    async def test_google_embedder_create_with_string(self, google_genai_mock):
+        """Test GoogleEmbedder.create with string input."""
+        with patch.dict(sys.modules, {"google.generativeai": google_genai_mock}):
+            embedder = GoogleEmbedder(api_key="test-key")
+            result = await embedder.create("test text")
+
+            assert result == [0.1, 0.2, 0.3]
+            # Assert embed_content was called
+            google_genai_mock.embed_content.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_google_embedder_create_with_list(self, google_genai_mock):
+        """Test GoogleEmbedder.create with list input."""
+        with patch.dict(sys.modules, {"google.generativeai": google_genai_mock}):
+            embedder = GoogleEmbedder(api_key="test-key")
+            result = await embedder.create(["test", "text"])
+
+            assert result == [0.1, 0.2, 0.3]
+
+    @pytest.mark.asyncio
+    async def test_google_embedder_create_with_non_string_list(self, google_genai_mock):
+        """Test GoogleEmbedder.create with non-string list items (lines 71-73)."""
+        with patch.dict(sys.modules, {"google.generativeai": google_genai_mock}):
+            embedder = GoogleEmbedder(api_key="test-key")
+            # List with non-string items - should convert to string
+            result = await embedder.create([123, 456])
+
+            assert result == [0.1, 0.2, 0.3]
+
+    @pytest.mark.asyncio
+    async def test_google_embedder_create_with_empty_list(self, google_genai_mock):
+        """Test GoogleEmbedder.create with empty or invalid input (line 75)."""
+        with patch.dict(sys.modules, {"google.generativeai": google_genai_mock}):
+            embedder = GoogleEmbedder(api_key="test-key")
+            # Empty list - should be converted to string
+            result = await embedder.create([])
+
+            assert result == [0.1, 0.2, 0.3]
+
+    @pytest.mark.asyncio
+    async def test_google_embedder_create_batch(self, google_genai_mock):
+        """Test GoogleEmbedder.create_batch with multiple inputs (lines 100-127)."""
+        # Override embed_content return value for batch test
+        google_genai_mock.embed_content = MagicMock(
+            return_value={"embedding": [[0.1, 0.2], [0.3, 0.4]]}
+        )
+
+        with patch.dict(sys.modules, {"google.generativeai": google_genai_mock}):
+            embedder = GoogleEmbedder(api_key="test-key")
+            result = await embedder.create_batch(["text1", "text2"])
+
+            # Should handle nested list response (lines 122-125)
+            assert len(result) == 2
+
+    @pytest.mark.asyncio
+    async def test_google_embedder_create_batch_single_response(
+        self, google_genai_mock
+    ):
+        """Test GoogleEmbedder.create_batch with single embedding response (lines 124-125)."""
+        # Override embed_content return value for single response test
+        google_genai_mock.embed_content = MagicMock(
+            return_value={"embedding": [0.1, 0.2, 0.3]}
+        )
+
+        with patch.dict(sys.modules, {"google.generativeai": google_genai_mock}):
+            embedder = GoogleEmbedder(api_key="test-key")
+            result = await embedder.create_batch(["text1"])
+
+            # Should handle single embedding response (line 125)
+            assert len(result) == 1
+            assert result[0] == [0.1, 0.2, 0.3]
+
+    @pytest.mark.slow
+    @pytest.mark.asyncio
+    async def test_google_embedder_create_batch_large_input(self, google_genai_mock):
+        """Test GoogleEmbedder.create_batch with >100 items (batching)."""
+        # Override embed_content return value for large batch test
+        google_genai_mock.embed_content = MagicMock(
+            return_value={"embedding": [[0.1, 0.2]]}
+        )
+
+        with patch.dict(sys.modules, {"google.generativeai": google_genai_mock}):
+            embedder = GoogleEmbedder(api_key="test-key")
+            # Create 250 items - should be split into 3 batches (100, 100, 50)
+            result = await embedder.create_batch([f"text{i}" for i in range(250)])
+
+            # Should call embed_content 3 times
+            assert google_genai_mock.embed_content.call_count == 3
+
+
+# =============================================================================
+# Test create_google_embedder
+# =============================================================================
+
+
+class TestCreateGoogleEmbedder:
+    """Test create_google_embedder factory function."""
+
+    @pytest.fixture
+    def mock_config(self):
+        """Create a mock GraphitiConfig."""
+        config = MagicMock()
+        config.google_api_key = "test-google-key"
+        config.google_embedding_model = None
+        return config
+
+    def test_create_google_embedder_success(self, mock_config):
+        """Test create_google_embedder returns embedder with valid config."""
+        mock_embedder = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.embedder_providers.google_embedder.GoogleEmbedder",
+            return_value=mock_embedder,
+        ):
+            result = create_google_embedder(mock_config)
+            assert result == mock_embedder
+
+    def test_create_google_embedder_missing_api_key(self, mock_config):
+        """Test create_google_embedder raises ProviderError for missing API key."""
+        mock_config.google_api_key = None
+
+        with pytest.raises(ProviderError) as exc_info:
+            create_google_embedder(mock_config)
+
+        assert "GOOGLE_API_KEY" in str(exc_info.value)
+
+    def test_create_google_embedder_with_custom_model(self, mock_config):
+        """Test create_google_embedder uses custom model when specified."""
+        mock_config.google_embedding_model = "custom-model"
+        mock_embedder = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.embedder_providers.google_embedder.GoogleEmbedder",
+            return_value=mock_embedder,
+        ) as mock_google_embedder:
+            create_google_embedder(mock_config)
+
+            mock_google_embedder.assert_called_once_with(
+                api_key=mock_config.google_api_key,
+                model="custom-model",
+            )
+
+    def test_create_google_embedder_with_default_model(self, mock_config):
+        """Test create_google_embedder uses default model when not specified."""
+        mock_config.google_embedding_model = None
+        mock_embedder = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.embedder_providers.google_embedder.GoogleEmbedder",
+            return_value=mock_embedder,
+        ) as mock_google_embedder:
+            create_google_embedder(mock_config)
+
+            mock_google_embedder.assert_called_once_with(
+                api_key=mock_config.google_api_key,
+                model=DEFAULT_GOOGLE_EMBEDDING_MODEL,
+            )
+
+
+# =============================================================================
+# Test Constants
+# =============================================================================
+
+
+class TestGoogleEmbedderConstants:
+    """Test Google embedder constants."""
+
+    def test_default_google_embedding_model(self):
+        # Note: This test verifies the default Google embedding model.
+        # The value should match the model used in production.
+        assert DEFAULT_GOOGLE_EMBEDDING_MODEL == "text-embedding-004"
@@ -0,0 +1,146 @@
+"""
+Unit tests for Anthropic LLM provider.
+
+Tests cover:
+- create_anthropic_llm_client factory function
+- ProviderNotInstalled exception handling
+- ProviderError for missing configuration
+"""
+
+import sys
+from unittest.mock import MagicMock, patch
+
+import pytest
+from integrations.graphiti.providers_pkg.exceptions import (
+    ProviderError,
+    ProviderNotInstalled,
+)
+from integrations.graphiti.providers_pkg.llm_providers.anthropic_llm import (
+    create_anthropic_llm_client,
+)
+
+# =============================================================================
+# Test create_anthropic_llm_client
+# =============================================================================
+
+
+class TestCreateAnthropicLLMClient:
+    """Test create_anthropic_llm_client factory function."""
+
+    @pytest.fixture
+    def mock_config(self):
+        """Create a mock GraphitiConfig."""
+        config = MagicMock()
+        config.anthropic_api_key = "sk-ant-test-key"
+        config.anthropic_model = "claude-sonnet-4-20250514"
+        return config
+
+    @pytest.mark.slow
+    def test_create_anthropic_llm_client_success(self, mock_config):
+        """Test create_anthropic_llm_client returns client with valid config."""
+        mock_client = MagicMock()
+
+        # Patch at the location where the import happens (local import inside function)
+        with patch(
+            "integrations.graphiti.providers_pkg.llm_providers.anthropic_llm.AnthropicClient",
+            return_value=mock_client,
+        ):
+            result = create_anthropic_llm_client(mock_config)
+            assert result == mock_client
+
+    def test_create_anthropic_llm_client_success_fast(self, mock_config):
+        """Fast test for create_anthropic_llm_client success path."""
+        mock_llm_client = MagicMock()
+
+        # Create the config mock
+        mock_config_module = MagicMock()
+        mock_config_module.LLMConfig = MagicMock
+
+        # Mock the graphiti_core imports
+        with patch.dict(
+            "sys.modules",
+            {
+                "graphiti_core": MagicMock(),
+                "graphiti_core.llm_client": MagicMock(),
+                "graphiti_core.llm_client.anthropic_client": MagicMock(),
+                "graphiti_core.llm_client.config": mock_config_module,
+            },
+        ):
+            from graphiti_core.llm_client.anthropic_client import AnthropicClient
+
+            AnthropicClient.return_value = mock_llm_client
+
+            result = create_anthropic_llm_client(mock_config)
+
+            # Verify the client was created and returned
+            AnthropicClient.assert_called_once()
+            assert result == mock_llm_client
+
+    def test_create_anthropic_llm_client_missing_api_key_fast(self, mock_config):
+        """Fast test for API key validation (line 41)."""
+        # Mock the graphiti_core imports first to avoid ImportError
+        mock_config_module = MagicMock()
+        mock_config_module.LLMConfig = MagicMock
+
+        with patch.dict(
+            "sys.modules",
+            {
+                "graphiti_core": MagicMock(),
+                "graphiti_core.llm_client": MagicMock(),
+                "graphiti_core.llm_client.anthropic_client": MagicMock(),
+                "graphiti_core.llm_client.config": mock_config_module,
+            },
+        ):
+            from graphiti_core.llm_client.anthropic_client import AnthropicClient
+
+            AnthropicClient.return_value = MagicMock()
+
+            # Now set API key to None to test validation
+            mock_config.anthropic_api_key = None
+
+            with pytest.raises(ProviderError) as exc_info:
+                create_anthropic_llm_client(mock_config)
+
+            assert "ANTHROPIC_API_KEY" in str(exc_info.value)
+
+    def test_create_anthropic_llm_client_import_error(self, mock_config):
+        """Test create_anthropic_llm_client raises ProviderNotInstalled on ImportError."""
+        from types import ModuleType
+
+        # Create a broken module that raises ImportError on attribute access
+        def broken_getattr(name):
+            if name in ("llm_client", "anthropic_client", "config"):
+                raise ImportError("graphiti-core[anthropic] not installed")
+            raise AttributeError(f"module has no attribute '{name}'")
+
+        broken_module = ModuleType("graphiti_core")
+        broken_module.__getattr__ = broken_getattr
+
+        # Patch both modules that are imported
+        with patch.dict(sys.modules, {"graphiti_core": broken_module}):
+            with pytest.raises(ProviderNotInstalled) as exc_info:
+                create_anthropic_llm_client(mock_config)
+
+            assert "graphiti-core[anthropic]" in str(exc_info.value)
+
+    @pytest.mark.slow
+    def test_create_anthropic_llm_client_passes_config_correctly(self, mock_config):
+        """Test create_anthropic_llm_client passes config values correctly."""
+        mock_config.anthropic_api_key = "sk-ant-test-key-123"
+        mock_config.anthropic_model = "claude-opus-4-20250514"
+        mock_client = MagicMock()
+
+        # Patch at the location where the imports happen (local imports inside function)
+        with patch(
+            "integrations.graphiti.providers_pkg.llm_providers.anthropic_llm.LLMConfig",
+        ) as mock_config_class:
+            with patch(
+                "integrations.graphiti.providers_pkg.llm_providers.anthropic_llm.AnthropicClient",
+                return_value=mock_client,
+            ):
+                create_anthropic_llm_client(mock_config)
+
+                # Verify LLMConfig was called with correct arguments
+                call_kwargs = mock_config_class.call_args.kwargs
+                assert call_kwargs["api_key"] == "sk-ant-test-key-123"
+                assert call_kwargs["model"] == "claude-opus-4-20250514"
@@ -0,0 +1,163 @@
+"""
+Unit tests for Azure OpenAI LLM provider.
+
+Tests cover:
+- create_azure_openai_llm_client factory function
+- ProviderNotInstalled exception handling
+- ProviderError for missing configuration
+"""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+from integrations.graphiti.providers_pkg.exceptions import (
+    ProviderError,
+    ProviderNotInstalled,
+)
+from integrations.graphiti.providers_pkg.llm_providers.azure_openai_llm import (
+    create_azure_openai_llm_client,
+)
+
+# =============================================================================
+# Test create_azure_openai_llm_client
+# =============================================================================
+
+
+class TestCreateAzureOpenAILLMClient:
+    """Test create_azure_openai_llm_client factory function."""
+
+    @pytest.fixture
+    def mock_config(self):
+        """Create a mock GraphitiConfig."""
+        config = MagicMock()
+        config.azure_openai_api_key = "test-azure-key"
+        config.azure_openai_base_url = "https://test.openai.azure.com"
+        config.azure_openai_llm_deployment = "test-llm-deployment"
+        return config
+
+    @pytest.mark.slow
+    def test_create_azure_openai_llm_client_success(self, mock_config):
+        """Test create_azure_openai_llm_client returns client with valid config."""
+        mock_azure_client = MagicMock()
+        mock_client = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.llm_providers.azure_openai_llm.AsyncOpenAI",
+            return_value=mock_azure_client,
+        ):
+            with patch(
+                "graphiti_core.llm_client.azure_openai_client.AzureOpenAILLMClient",
+                return_value=mock_client,
+            ):
+                result = create_azure_openai_llm_client(mock_config)
+                assert result == mock_client
+
+    def test_create_azure_openai_llm_client_success_fast(self, mock_config):
+        """Fast test for create_azure_openai_llm_client success path."""
+        mock_llm_client = MagicMock()
+
+        # Mock the graphiti_core imports
+        with patch.dict(
+            "sys.modules",
+            {
+                "graphiti_core": MagicMock(),
+                "graphiti_core.llm_client": MagicMock(),
+                "graphiti_core.llm_client.azure_openai_client": MagicMock(),
+                "graphiti_core.llm_client.config": MagicMock(),
+            },
+        ):
+            from graphiti_core.llm_client.azure_openai_client import (
+                AzureOpenAILLMClient,
+            )
+
+            AzureOpenAILLMClient.return_value = mock_llm_client
+
+            result = create_azure_openai_llm_client(mock_config)
+
+            # Verify the client was created and returned
+            AzureOpenAILLMClient.assert_called_once()
+            assert result == mock_llm_client
+
+    def test_create_azure_openai_llm_client_missing_api_key(self, mock_config):
+        """Test create_azure_openai_llm_client raises ProviderError for missing API key."""
+        mock_config.azure_openai_api_key = None
+
+        with pytest.raises(ProviderError) as exc_info:
+            create_azure_openai_llm_client(mock_config)
+
+        assert "AZURE_OPENAI_API_KEY" in str(exc_info.value)
+
+    def test_create_azure_openai_llm_client_missing_base_url(self, mock_config):
+        """Test create_azure_openai_llm_client raises ProviderError for missing base URL."""
+        mock_config.azure_openai_base_url = None
+
+        with pytest.raises(ProviderError) as exc_info:
+            create_azure_openai_llm_client(mock_config)
+
+        assert "AZURE_OPENAI_BASE_URL" in str(exc_info.value)
+
+    def test_create_azure_openai_llm_client_missing_deployment(self, mock_config):
+        """Test create_azure_openai_llm_client raises ProviderError for missing deployment."""
+        mock_config.azure_openai_llm_deployment = None
+
+        with pytest.raises(ProviderError) as exc_info:
+            create_azure_openai_llm_client(mock_config)
+
+        assert "AZURE_OPENAI_LLM_DEPLOYMENT" in str(exc_info.value)
+
+    def test_create_azure_openai_llm_client_import_error(self, mock_config):
+        """Test create_azure_openai_llm_client raises ProviderNotInstalled on ImportError."""
+        import builtins
+
+        original_import = builtins.__import__
+
+        def mock_import(name, *args, **kwargs):
+            if (
+                name.startswith("graphiti_core.llm_client")
+                or name == "openai"
+                or name.startswith("openai.")
+            ):
+                raise ImportError("Required package not installed")
+            return original_import(name, *args, **kwargs)
+
+        with patch("builtins.__import__", side_effect=mock_import):
+            with pytest.raises(ProviderNotInstalled) as exc_info:
+                create_azure_openai_llm_client(mock_config)
+
+            assert "graphiti-core" in str(exc_info.value)
+            assert "openai" in str(exc_info.value)
+
+    @pytest.mark.slow
+    def test_create_azure_openai_llm_client_passes_config_correctly(self, mock_config):
+        """Test create_azure_openai_llm_client passes config values correctly."""
+        mock_azure_client = MagicMock()
+        mock_client = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.llm_providers.azure_openai_llm.AsyncOpenAI",
+            return_value=mock_azure_client,
+        ) as mock_openai:
+            with patch(
+                "integrations.graphiti.providers_pkg.llm_providers.azure_openai_llm.LLMConfig",
+            ) as mock_config_class:
+                with patch(
+                    "graphiti_core.llm_client.azure_openai_client.AzureOpenAILLMClient",
+                    return_value=mock_client,
+                ):
+                    create_azure_openai_llm_client(mock_config)
+
+                    # Verify AsyncOpenAI was called with correct arguments
+                    mock_openai.assert_called_once_with(
+                        base_url=mock_config.azure_openai_base_url,
+                        api_key=mock_config.azure_openai_api_key,
+                    )
+
+                    # Verify LLMConfig was called with correct arguments
+                    call_kwargs = mock_config_class.call_args.kwargs
+                    assert (
+                        call_kwargs["model"] == mock_config.azure_openai_llm_deployment
+                    )
+                    assert (
+                        call_kwargs["small_model"]
+                        == mock_config.azure_openai_llm_deployment
+                    )
@@ -0,0 +1,410 @@
+"""
+Unit tests for Google LLM provider.
+
+Tests cover:
+- create_google_llm_client factory function
+- GoogleLLMClient class (generate_response, generate_response_with_tools)
+- ProviderNotInstalled exception handling
+- ProviderError for missing configuration
+"""
+
+import sys
+from unittest.mock import MagicMock, patch
+
+import pytest
+from integrations.graphiti.providers_pkg.exceptions import (
+    ProviderError,
+    ProviderNotInstalled,
+)
+from integrations.graphiti.providers_pkg.llm_providers.google_llm import (
+    DEFAULT_GOOGLE_LLM_MODEL,
+    GoogleLLMClient,
+    create_google_llm_client,
+)
+
+# =============================================================================
+# Test GoogleLLMClient class
+# =============================================================================
+
+
+class TestGoogleLLMClient:
+    """Test GoogleLLMClient class."""
+
+    def test_google_llm_client_init_success(self):
+        """Test GoogleLLMClient initializes with API key and model."""
+        mock_genai = MagicMock()
+        mock_genai.configure = MagicMock()
+        mock_model = MagicMock()
+        mock_genai.GenerativeModel = MagicMock(return_value=mock_model)
+
+        with patch.dict(sys.modules, {"google.generativeai": mock_genai}):
+            client = GoogleLLMClient(api_key="test-key", model="test-model")
+
+            assert client.api_key == "test-key"
+            assert client.model == "test-model"
+            mock_genai.configure.assert_called_once_with(api_key="test-key")
+            mock_genai.GenerativeModel.assert_called_once_with("test-model")
+
+    def test_google_llm_client_init_default_model(self):
+        """Test GoogleLLMClient uses default model when not specified."""
+        mock_genai = MagicMock()
+        mock_genai.configure = MagicMock()
+        mock_model = MagicMock()
+        mock_genai.GenerativeModel = MagicMock(return_value=mock_model)
+
+        with patch.dict(sys.modules, {"google.generativeai": mock_genai}):
+            client = GoogleLLMClient(api_key="test-key")
+
+            assert client.model == DEFAULT_GOOGLE_LLM_MODEL
+
+    def test_google_llm_client_init_import_error(self):
+        """Test GoogleLLMClient raises ProviderNotInstalled on ImportError."""
+        import builtins
+
+        original_import = builtins.__import__
+
+        def mock_import(name, *args, **kwargs):
+            if name == "google.generativeai" or name.startswith("google.generativeai."):
+                raise ImportError("google-generativeai not installed")
+            return original_import(name, *args, **kwargs)
+
+        with patch("builtins.__import__", side_effect=mock_import):
+            with pytest.raises(ProviderNotInstalled) as exc_info:
+                GoogleLLMClient(api_key="test-key")
+
+            assert "google-generativeai" in str(exc_info.value)
+
+    @pytest.mark.asyncio
+    async def test_google_llm_client_generate_response_with_user_message(self):
+        """Test GoogleLLMClient.generate_response with user message (lines 73-133)."""
+        mock_genai = MagicMock()
+        mock_genai.configure = MagicMock()
+        mock_model = MagicMock()
+        mock_genai.GenerativeModel = MagicMock(return_value=mock_model)
+        mock_response = MagicMock()
+        mock_response.text = "Test response"
+        mock_model.generate_content = MagicMock(return_value=mock_response)
+
+        with patch.dict(sys.modules, {"google.generativeai": mock_genai}):
+            client = GoogleLLMClient(api_key="test-key")
+            result = await client.generate_response(
+                [{"role": "user", "content": "Hello"}]
+            )
+
+            assert result == "Test response"
+
+    @pytest.mark.slow
+    @pytest.mark.asyncio
+    async def test_google_llm_client_generate_response_with_user_message_slow(self):
+        """Test GoogleLLMClient.generate_response with user message (slow variant)."""
+        mock_genai = MagicMock()
+        mock_genai.configure = MagicMock()
+        mock_model = MagicMock()
+        mock_genai.GenerativeModel = MagicMock(return_value=mock_model)
+        mock_response = MagicMock()
+        mock_response.text = "Test response"
+        mock_model.generate_content = MagicMock(return_value=mock_response)
+
+        with patch.dict(sys.modules, {"google.generativeai": mock_genai}):
+            client = GoogleLLMClient(api_key="test-key")
+            result = await client.generate_response(
+                [{"role": "user", "content": "Hello"}]
+            )
+
+            assert result == "Test response"
+
+    @pytest.mark.asyncio
+    async def test_google_llm_client_generate_response_with_system_message(self):
+        """Test GoogleLLMClient.generate_response with system instruction (lines 84-98)."""
+        mock_genai = MagicMock()
+        mock_genai.configure = MagicMock()
+        mock_model_with_sys = MagicMock()
+        mock_model_without_sys = MagicMock()
+        mock_genai.GenerativeModel = MagicMock(
+            side_effect=[mock_model_without_sys, mock_model_with_sys]
+        )
+        mock_response = MagicMock()
+        mock_response.text = "Test response"
+        mock_model_with_sys.generate_content = MagicMock(return_value=mock_response)
+
+        with patch.dict(sys.modules, {"google.generativeai": mock_genai}):
+            client = GoogleLLMClient(api_key="test-key")
+            result = await client.generate_response(
+                [
+                    {"role": "system", "content": "You are helpful"},
+                    {"role": "user", "content": "Hello"},
+                ]
+            )
+
+            assert result == "Test response"
+
+    @pytest.mark.slow
+    @pytest.mark.asyncio
+    async def test_google_llm_client_generate_response_with_system_message_slow(self):
+        """Test GoogleLLMClient.generate_response with system instruction (slow variant)."""
+        mock_genai = MagicMock()
+        mock_genai.configure = MagicMock()
+        mock_model_with_sys = MagicMock()
+        mock_model_without_sys = MagicMock()
+        mock_genai.GenerativeModel = MagicMock(
+            side_effect=[mock_model_without_sys, mock_model_with_sys]
+        )
+        mock_response = MagicMock()
+        mock_response.text = "Test response"
+        mock_model_with_sys.generate_content = MagicMock(return_value=mock_response)
+
+        with patch.dict(sys.modules, {"google.generativeai": mock_genai}):
+            client = GoogleLLMClient(api_key="test-key")
+            result = await client.generate_response(
+                [
+                    {"role": "system", "content": "You are helpful"},
+                    {"role": "user", "content": "Hello"},
+                ]
+            )
+
+            assert result == "Test response"
+
+    @pytest.mark.asyncio
+    async def test_google_llm_client_generate_response_with_assistant_message(self):
+        """Test GoogleLLMClient.generate_response with assistant role (lines 87-88)."""
+        mock_genai = MagicMock()
+        mock_genai.configure = MagicMock()
+        mock_model = MagicMock()
+        mock_genai.GenerativeModel = MagicMock(return_value=mock_model)
+        mock_response = MagicMock()
+        mock_response.text = "Test response"
+        mock_model.generate_content = MagicMock(return_value=mock_response)
+
+        with patch.dict(sys.modules, {"google.generativeai": mock_genai}):
+            client = GoogleLLMClient(api_key="test-key")
+            result = await client.generate_response(
+                [
+                    {"role": "user", "content": "Hello"},
+                    {"role": "assistant", "content": "Hi there"},
+                    {"role": "user", "content": "How are you?"},
+                ]
+            )
+
+            assert result == "Test response"
+
+    @pytest.mark.asyncio
+    async def test_google_llm_client_generate_response_with_response_model(self):
+        """Test GoogleLLMClient.generate_response with structured output (lines 103-127)."""
+        mock_genai = MagicMock()
+        mock_genai.configure = MagicMock()
+        mock_model = MagicMock()
+        mock_genai.GenerativeModel = MagicMock(return_value=mock_model)
+        mock_response = MagicMock()
+        mock_response.text = '{"key": "value"}'
+        mock_model.generate_content = MagicMock(return_value=mock_response)
+        mock_genai.GenerationConfig = MagicMock()
+
+        with patch.dict(sys.modules, {"google.generativeai": mock_genai}):
+            from pydantic import BaseModel
+
+            class TestModel(BaseModel):
+                key: str
+
+            client = GoogleLLMClient(api_key="test-key")
+            result = await client.generate_response(
+                [{"role": "user", "content": "Hello"}],
+                response_model=TestModel,
+            )
+
+            assert isinstance(result, TestModel)
+            assert result.key == "value"
+
+    @pytest.mark.slow
+    @pytest.mark.asyncio
+    async def test_google_llm_client_generate_response_with_response_model_slow(self):
+        """Test GoogleLLMClient.generate_response with structured output (slow variant)."""
+        mock_genai = MagicMock()
+        mock_genai.configure = MagicMock()
+        mock_model = MagicMock()
+        mock_genai.GenerativeModel = MagicMock(return_value=mock_model)
+        mock_response = MagicMock()
+        mock_response.text = '{"key": "value"}'
+        mock_model.generate_content = MagicMock(return_value=mock_response)
+        mock_genai.GenerationConfig = MagicMock()
+
+        with patch.dict(sys.modules, {"google.generativeai": mock_genai}):
+            from pydantic import BaseModel
+
+            class TestModel(BaseModel):
+                key: str
+
+            client = GoogleLLMClient(api_key="test-key")
+            result = await client.generate_response(
+                [{"role": "user", "content": "Hello"}],
+                response_model=TestModel,
+            )
+
+            assert isinstance(result, TestModel)
+            assert result.key == "value"
+
+    @pytest.mark.asyncio
+    async def test_google_llm_client_generate_response_json_decode_error(self):
+        """Test GoogleLLMClient.generate_response with JSON decode error (lines 122-127)."""
+        mock_genai = MagicMock()
+        mock_genai.configure = MagicMock()
+        mock_model = MagicMock()
+        mock_genai.GenerativeModel = MagicMock(return_value=mock_model)
+        mock_response = MagicMock()
+        mock_response.text = "Not valid JSON"
+        mock_model.generate_content = MagicMock(return_value=mock_response)
+        mock_genai.GenerationConfig = MagicMock()
+
+        with patch.dict(sys.modules, {"google.generativeai": mock_genai}):
+            from pydantic import BaseModel
+
+            class TestModel(BaseModel):
+                key: str
+
+            client = GoogleLLMClient(api_key="test-key")
+            result = await client.generate_response(
+                [{"role": "user", "content": "Hello"}],
+                response_model=TestModel,
+            )
+
+            # Should return raw text when JSON parsing fails
+            assert result == "Not valid JSON"
+
+    @pytest.mark.asyncio
+    async def test_google_llm_client_generate_response_with_tools(self):
+        """Test GoogleLLMClient.generate_response_with_tools (lines 155-160)."""
+        mock_genai = MagicMock()
+        mock_genai.configure = MagicMock()
+        mock_model = MagicMock()
+        mock_genai.GenerativeModel = MagicMock(return_value=mock_model)
+        mock_response = MagicMock()
+        mock_response.text = "Test response"
+        mock_model.generate_content = MagicMock(return_value=mock_response)
+
+        with patch.dict(sys.modules, {"google.generativeai": mock_genai}):
+            client = GoogleLLMClient(api_key="test-key")
+
+            with patch(
+                "integrations.graphiti.providers_pkg.llm_providers.google_llm.logger"
+            ) as mock_logger:
+                result = await client.generate_response_with_tools(
+                    [{"role": "user", "content": "Hello"}],
+                    tools=[{"name": "test_tool"}],
+                )
+
+                # Should log warning about tools not being supported
+                mock_logger.warning.assert_called_once()
+                assert "does not yet support tool calling" in str(
+                    mock_logger.warning.call_args
+                )
+                assert result == "Test response"
+
+    @pytest.mark.slow
+    @pytest.mark.asyncio
+    async def test_google_llm_client_generate_response_with_tools_slow(self):
+        """Test GoogleLLMClient.generate_response_with_tools (slow variant)."""
+        mock_genai = MagicMock()
+        mock_genai.configure = MagicMock()
+        mock_model = MagicMock()
+        mock_genai.GenerativeModel = MagicMock(return_value=mock_model)
+        mock_response = MagicMock()
+        mock_response.text = "Test response"
+        mock_model.generate_content = MagicMock(return_value=mock_response)
+
+        with patch.dict(sys.modules, {"google.generativeai": mock_genai}):
+            client = GoogleLLMClient(api_key="test-key")
+
+            with patch(
+                "integrations.graphiti.providers_pkg.llm_providers.google_llm.logger"
+            ) as mock_logger:
+                result = await client.generate_response_with_tools(
+                    [{"role": "user", "content": "Hello"}],
+                    tools=[{"name": "test_tool"}],
+                )
+
+                mock_logger.warning.assert_called_once()
+                assert "does not yet support tool calling" in str(
+                    mock_logger.warning.call_args
+                )
+                assert result == "Test response"
+
+
+# =============================================================================
+# Test create_google_llm_client
+# =============================================================================
+
+
+class TestCreateGoogleLLMClient:
+    """Test create_google_llm_client factory function."""
+
+    @pytest.fixture
+    def mock_config(self):
+        """Create a mock GraphitiConfig."""
+        config = MagicMock()
+        config.google_api_key = "test-google-key"
+        config.google_llm_model = None
+        return config
+
+    def test_create_google_llm_client_success(self, mock_config):
+        """Test create_google_llm_client returns client with valid config."""
+        mock_client = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.llm_providers.google_llm.GoogleLLMClient",
+            return_value=mock_client,
+        ):
+            result = create_google_llm_client(mock_config)
+            assert result == mock_client
+
+    def test_create_google_llm_client_missing_api_key(self, mock_config):
+        """Test create_google_llm_client raises ProviderError for missing API key."""
+        mock_config.google_api_key = None
+
+        with pytest.raises(ProviderError) as exc_info:
+            create_google_llm_client(mock_config)
+
+        assert "GOOGLE_API_KEY" in str(exc_info.value)
+
+    def test_create_google_llm_client_with_custom_model(self, mock_config):
+        """Test create_google_llm_client uses custom model when specified."""
+        mock_config.google_llm_model = "custom-model"
+        mock_client = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.llm_providers.google_llm.GoogleLLMClient",
+            return_value=mock_client,
+        ) as mock_google_client:
+            create_google_llm_client(mock_config)
+
+            mock_google_client.assert_called_once_with(
+                api_key=mock_config.google_api_key,
+                model="custom-model",
+            )
+
+    def test_create_google_llm_client_with_default_model(self, mock_config):
+        """Test create_google_llm_client uses default model when not specified."""
+        mock_config.google_llm_model = None
+        mock_client = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.llm_providers.google_llm.GoogleLLMClient",
+            return_value=mock_client,
+        ) as mock_google_client:
+            create_google_llm_client(mock_config)
+
+            mock_google_client.assert_called_once_with(
+                api_key=mock_config.google_api_key,
+                model=DEFAULT_GOOGLE_LLM_MODEL,
+            )
+
+
+# =============================================================================
+# Test Constants
+# =============================================================================
+
+
+class TestGoogleLLMConstants:
+    """Test Google LLM constants."""
+
+    def test_default_google_llm_model(self):
+        """Test DEFAULT_GOOGLE_LLM_MODEL is set correctly."""
+        assert DEFAULT_GOOGLE_LLM_MODEL == "gemini-2.0-flash"
@@ -0,0 +1,181 @@
+"""
+Unit tests for Ollama LLM provider.
+
+Tests cover:
+- create_ollama_llm_client factory function
+- ProviderNotInstalled exception handling
+- ProviderError for missing configuration
+"""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+from integrations.graphiti.providers_pkg.exceptions import (
+    ProviderError,
+    ProviderNotInstalled,
+)
+from integrations.graphiti.providers_pkg.llm_providers.ollama_llm import (
+    create_ollama_llm_client,
+)
+
+# =============================================================================
+# Test create_ollama_llm_client
+# =============================================================================
+
+
+class TestCreateOllamaLLMClient:
+    """Test create_ollama_llm_client factory function."""
+
+    @pytest.fixture
+    def mock_config(self):
+        """Create a mock GraphitiConfig."""
+        config = MagicMock()
+        config.ollama_llm_model = "llama3.2"
+        config.ollama_base_url = "http://localhost:11434"
+        return config
+
+    @pytest.mark.slow
+    def test_create_ollama_llm_client_success(self, mock_config):
+        """Test create_ollama_llm_client returns client with valid config."""
+        mock_client = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.llm_providers.ollama_llm.OpenAIGenericClient",
+            return_value=mock_client,
+        ):
+            result = create_ollama_llm_client(mock_config)
+            assert result == mock_client
+
+    def test_create_ollama_llm_client_success_fast(self, mock_config):
+        """Fast test for create_ollama_llm_client success path."""
+        mock_llm_client = MagicMock()
+
+        # Create the config mock
+        mock_config_module = MagicMock()
+        mock_config_module.LLMConfig = MagicMock
+
+        # Mock the graphiti_core imports
+        with patch.dict(
+            "sys.modules",
+            {
+                "graphiti_core": MagicMock(),
+                "graphiti_core.llm_client": MagicMock(),
+                "graphiti_core.llm_client.config": mock_config_module,
+                "graphiti_core.llm_client.openai_generic_client": MagicMock(),
+            },
+        ):
+            from graphiti_core.llm_client.openai_generic_client import (
+                OpenAIGenericClient,
+            )
+
+            OpenAIGenericClient.return_value = mock_llm_client
+
+            result = create_ollama_llm_client(mock_config)
+
+            # Verify the client was created and returned
+            OpenAIGenericClient.assert_called_once()
+            assert result == mock_llm_client
+
+    def test_create_ollama_llm_client_missing_model(self, mock_config):
+        """Test create_ollama_llm_client raises ProviderError for missing model."""
+        mock_config.ollama_llm_model = None
+
+        with pytest.raises(ProviderError) as exc_info:
+            create_ollama_llm_client(mock_config)
+
+        assert "OLLAMA_LLM_MODEL" in str(exc_info.value)
+
+    def test_create_ollama_llm_client_import_error(self, mock_config):
+        """Test create_ollama_llm_client raises ProviderNotInstalled on ImportError."""
+        import builtins
+
+        original_import = builtins.__import__
+
+        def mock_import(name, *args, **kwargs):
+            if name.startswith("graphiti_core.llm_client"):
+                raise ImportError("graphiti-core not installed")
+            return original_import(name, *args, **kwargs)
+
+        with patch("builtins.__import__", side_effect=mock_import):
+            with pytest.raises(ProviderNotInstalled) as exc_info:
+                create_ollama_llm_client(mock_config)
+
+            assert "graphiti-core" in str(exc_info.value)
+
+    @pytest.mark.slow
+    def test_create_ollama_llm_client_base_url_without_v1(self, mock_config):
+        """Test create_ollama_llm_client appends /v1 to base URL if missing."""
+        mock_config.ollama_base_url = "http://localhost:11434"
+        mock_client = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.llm_providers.ollama_llm.LLMConfig",
+        ) as mock_config_class:
+            with patch(
+                "integrations.graphiti.providers_pkg.llm_providers.ollama_llm.OpenAIGenericClient",
+                return_value=mock_client,
+            ):
+                create_ollama_llm_client(mock_config)
+
+                # Verify base_url has /v1 appended
+                call_kwargs = mock_config_class.call_args.kwargs
+                assert call_kwargs["base_url"] == "http://localhost:11434/v1"
+
+    @pytest.mark.slow
+    def test_create_ollama_llm_client_base_url_with_v1(self, mock_config):
+        """Test create_ollama_llm_client doesn't duplicate /v1 in base URL."""
+        mock_config.ollama_base_url = "http://localhost:11434/v1"
+        mock_client = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.llm_providers.ollama_llm.LLMConfig",
+        ) as mock_config_class:
+            with patch(
+                "integrations.graphiti.providers_pkg.llm_providers.ollama_llm.OpenAIGenericClient",
+                return_value=mock_client,
+            ):
+                create_ollama_llm_client(mock_config)
+
+                # Verify base_url is not duplicated
+                call_kwargs = mock_config_class.call_args.kwargs
+                assert call_kwargs["base_url"] == "http://localhost:11434/v1"
+
+    @pytest.mark.slow
+    def test_create_ollama_llm_client_base_url_with_trailing_slash(self, mock_config):
+        """Test create_ollama_llm_client handles trailing slash correctly."""
+        mock_config.ollama_base_url = "http://localhost:11434/"
+        mock_client = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.llm_providers.ollama_llm.LLMConfig",
+        ) as mock_config_class:
+            with patch(
+                "integrations.graphiti.providers_pkg.llm_providers.ollama_llm.OpenAIGenericClient",
+                return_value=mock_client,
+            ):
+                create_ollama_llm_client(mock_config)
+
+                # Verify trailing slash is handled
+                call_kwargs = mock_config_class.call_args.kwargs
+                assert call_kwargs["base_url"] == "http://localhost:11434/v1"
+
+    @pytest.mark.slow
+    def test_create_ollama_llm_client_passes_config_correctly(self, mock_config):
+        """Test create_ollama_llm_client passes config values correctly."""
+        mock_config.ollama_llm_model = "qwen2.5"
+        mock_client = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.llm_providers.ollama_llm.LLMConfig",
+        ) as mock_config_class:
+            with patch(
+                "integrations.graphiti.providers_pkg.llm_providers.ollama_llm.OpenAIGenericClient",
+                return_value=mock_client,
+            ):
+                create_ollama_llm_client(mock_config)
+
+                # Verify LLMConfig was called with correct arguments
+                call_kwargs = mock_config_class.call_args.kwargs
+                assert call_kwargs["api_key"] == "ollama"
+                assert call_kwargs["model"] == "qwen2.5"
+                assert call_kwargs["small_model"] == "qwen2.5"
@@ -0,0 +1,207 @@
+"""
+Unit tests for OpenAI LLM provider.
+
+Tests cover:
+- create_openai_llm_client factory function
+- ProviderNotInstalled exception handling
+- ProviderError for missing configuration
+"""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+from integrations.graphiti.providers_pkg.exceptions import (
+    ProviderError,
+    ProviderNotInstalled,
+)
+from integrations.graphiti.providers_pkg.llm_providers.openai_llm import (
+    create_openai_llm_client,
+)
+
+# =============================================================================
+# Test create_openai_llm_client
+# =============================================================================
+
+
+class TestCreateOpenAILLMClient:
+    """Test create_openai_llm_client factory function."""
+
+    @pytest.fixture
+    def mock_config(self):
+        """Create a mock GraphitiConfig."""
+        config = MagicMock()
+        config.openai_api_key = "sk-test-key"
+        config.openai_model = "gpt-4o"
+        return config
+
+    @pytest.mark.slow
+    def test_create_openai_llm_client_success(self, mock_config):
+        """Test create_openai_llm_client returns client with valid config."""
+        mock_client = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.llm_providers.openai_llm.OpenAIClient",
+            return_value=mock_client,
+        ):
+            result = create_openai_llm_client(mock_config)
+            assert result == mock_client
+
+    def test_create_openai_llm_client_success_fast(self, mock_config):
+        """Fast test for create_openai_llm_client success path."""
+        mock_llm_client = MagicMock()
+
+        # Create the config mock
+        mock_config_module = MagicMock()
+        mock_config_module.LLMConfig = MagicMock
+
+        # Mock the graphiti_core imports
+        with patch.dict(
+            "sys.modules",
+            {
+                "graphiti_core": MagicMock(),
+                "graphiti_core.llm_client": MagicMock(),
+                "graphiti_core.llm_client.config": mock_config_module,
+                "graphiti_core.llm_client.openai_client": MagicMock(),
+            },
+        ):
+            from graphiti_core.llm_client.openai_client import OpenAIClient
+
+            OpenAIClient.return_value = mock_llm_client
+
+            result = create_openai_llm_client(mock_config)
+
+            # Verify the client was created and returned
+            OpenAIClient.assert_called_once()
+            assert result == mock_llm_client
+
+    def test_create_openai_llm_client_missing_api_key(self, mock_config):
+        """Test create_openai_llm_client raises ProviderError for missing API key."""
+        mock_config.openai_api_key = None
+
+        with pytest.raises(ProviderError) as exc_info:
+            create_openai_llm_client(mock_config)
+
+        assert "OPENAI_API_KEY" in str(exc_info.value)
+
+    def test_create_openai_llm_client_import_error(self, mock_config):
+        """Test create_openai_llm_client raises ProviderNotInstalled on ImportError."""
+        import builtins
+
+        original_import = builtins.__import__
+
+        def mock_import(name, *args, **kwargs):
+            if name.startswith("graphiti_core.llm_client"):
+                raise ImportError("graphiti-core not installed")
+            return original_import(name, *args, **kwargs)
+
+        with patch("builtins.__import__", side_effect=mock_import):
+            with pytest.raises(ProviderNotInstalled) as exc_info:
+                create_openai_llm_client(mock_config)
+
+            assert "graphiti-core" in str(exc_info.value)
+
+    def test_create_openai_llm_client_gpt5_model_with_reasoning_fast(self, mock_config):
+        """Fast test for GPT-5 model with reasoning (line 58)."""
+        mock_config.openai_model = "gpt-5-turbo"
+        mock_client = MagicMock()
+
+        # Create the config mock
+        mock_config_module = MagicMock()
+        mock_config_module.LLMConfig = MagicMock
+
+        # Mock the graphiti_core imports
+        with patch.dict(
+            "sys.modules",
+            {
+                "graphiti_core": MagicMock(),
+                "graphiti_core.llm_client": MagicMock(),
+                "graphiti_core.llm_client.config": mock_config_module,
+                "graphiti_core.llm_client.openai_client": MagicMock(),
+            },
+        ):
+            from graphiti_core.llm_client.openai_client import OpenAIClient
+
+            OpenAIClient.return_value = mock_client
+
+            result = create_openai_llm_client(mock_config)
+
+            # Verify the client was created with default config (no extra params)
+            OpenAIClient.assert_called_once()
+            call_kwargs = OpenAIClient.call_args.kwargs
+            # Should not have reasoning/verbosity params set to None for GPT-5
+            assert (
+                "reasoning" not in call_kwargs
+                or call_kwargs.get("reasoning") is not False
+            )
+            assert (
+                "verbosity" not in call_kwargs
+                or call_kwargs.get("verbosity") is not False
+            )
+            assert result == mock_client
+
+    @pytest.mark.slow
+    @pytest.mark.parametrize(
+        "model,expected_reasoning,expected_verbosity",
+        [
+            pytest.param("gpt-5-turbo", True, None, id="gpt5"),
+            pytest.param("o1-preview", True, None, id="o1"),
+            pytest.param("o3-mini", True, None, id="o3"),
+        ],
+    )
+    def test_create_openai_llm_client_reasoning_models(
+        self, mock_config, model, expected_reasoning, expected_verbosity
+    ):
+        """Test create_openai_llm_client with reasoning-capable models."""
+        mock_config.openai_model = model
+        mock_client = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.llm_providers.openai_llm.OpenAIClient",
+            return_value=mock_client,
+        ) as mock_openai_client:
+            create_openai_llm_client(mock_config)
+
+            mock_openai_client.assert_called_once()
+            call_kwargs = mock_openai_client.call_args.kwargs
+            # Verify reasoning is set to True for reasoning models
+            assert call_kwargs.get("reasoning") is expected_reasoning
+            # Verify verbosity matches expected value (None for these models)
+            assert call_kwargs.get("verbosity") == expected_verbosity
+
+    @pytest.mark.slow
+    def test_create_openai_llm_client_gpt4_model_without_reasoning(self, mock_config):
+        """Test create_openai_llm_client with GPT-4 model disables reasoning."""
+        mock_config.openai_model = "gpt-4o"
+        mock_client = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.llm_providers.openai_llm.OpenAIClient",
+            return_value=mock_client,
+        ) as mock_openai_client:
+            create_openai_llm_client(mock_config)
+
+            # GPT-4 models should be created with reasoning=None, verbosity=None
+            call_kwargs = mock_openai_client.call_args.kwargs
+            assert call_kwargs.get("reasoning") is None
+            assert call_kwargs.get("verbosity") is None
+
+    @pytest.mark.slow
+    def test_create_openai_llm_client_passes_config_correctly(self, mock_config):
+        """Test create_openai_llm_client passes config values correctly."""
+        mock_config.openai_api_key = "sk-test-key-123"
+        mock_config.openai_model = "gpt-4o-mini"
+        mock_client = MagicMock()
+
+        with patch(
+            "integrations.graphiti.providers_pkg.llm_providers.openai_llm.LLMConfig",
+        ) as mock_config_class:
+            with patch(
+                "integrations.graphiti.providers_pkg.llm_providers.openai_llm.OpenAIClient",
+                return_value=mock_client,
+            ):
+                create_openai_llm_client(mock_config)
+
+                # Verify LLMConfig was called with correct arguments
+                call_kwargs = mock_config_class.call_args.kwargs
+                assert call_kwargs["api_key"] == "sk-test-key-123"
+                assert call_kwargs["model"] == "gpt-4o-mini"
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				`"""Tests for Graphiti memory integration."""`