Merge branch 'develop' into feat-gitlab-parity

docs: update README beta download links to 2.8.0-beta.5
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-18 14:39:58 +01:00 · 2026-03-17 20:32:15 +01:00 · 2026-03-16 21:20:56 +01:00 · 2026-03-15 11:05:27 +01:00 · 2026-03-14 10:16:40 +02:00 · 2026-03-14 09:15:03 +01:00
183 changed files with 14850 additions and 3066 deletions
@@ -338,7 +338,7 @@ jobs:
        run: |
          set -e
          sudo apt-get update
-          sudo apt-get install -y flatpak flatpak-builder libarchive-tools
+          sudo apt-get install -y flatpak flatpak-builder squashfs-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
@@ -34,6 +34,7 @@ concurrency:
 permissions:
  contents: read
  actions: read
+  pull-requests: write

 jobs:
  # --------------------------------------------------------------------------
@@ -61,9 +62,35 @@ jobs:
        working-directory: apps/desktop
        run: npm run typecheck

-      - name: Run unit tests
+      - name: Run unit tests with coverage
+        if: matrix.os == 'ubuntu-latest'
        working-directory: apps/desktop
-        run: npm run test
+        run: npm run test:coverage
+
+      - name: Run unit tests
+        if: matrix.os != 'ubuntu-latest'
+        working-directory: apps/desktop
+        run: npm run test:unit
+
+      - name: Run integration tests
+        working-directory: apps/desktop
+        run: npm run test:integration
+
+      - name: Upload coverage report
+        if: matrix.os == 'ubuntu-latest' && always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: apps/desktop/coverage/
+          retention-days: 14
+
+      - name: Coverage PR comment
+        if: matrix.os == 'ubuntu-latest' && github.event_name == 'pull_request'
+        uses: davelosert/vitest-coverage-report-action@v2
+        with:
+          working-directory: apps/desktop
+          json-summary-path: coverage/coverage-summary.json
+          json-final-path: coverage/coverage-final.json

      - name: Build application
        working-directory: apps/desktop
@@ -0,0 +1,62 @@
+# E2E Tests
+#
+# Runs Playwright E2E tests for the Electron desktop app on Linux.
+# Ubuntu-only since Electron E2E is platform-agnostic (Chromium renderer).
+# Non-blocking initially — separate from ci-complete gate while stabilizing.
+
+name: E2E
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - 'apps/**'
+      - '.github/workflows/e2e.yml'
+  pull_request:
+    branches: [main, develop]
+    paths:
+      - 'apps/**'
+      - '.github/workflows/e2e.yml'
+
+concurrency:
+  group: e2e-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  e2e:
+    name: E2E Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js frontend
+        uses: ./.github/actions/setup-node-frontend
+
+      - name: Install Playwright browsers
+        working-directory: apps/desktop
+        run: npx playwright install --with-deps chromium
+
+      - name: Build application
+        working-directory: apps/desktop
+        run: npm run build
+
+      - name: Run E2E tests
+        working-directory: apps/desktop
+        continue-on-error: true  # Non-blocking while stabilizing — pre-existing __dirname ESM issue
+        run: xvfb-run --auto-servernum npm run test:e2e
+
+      - name: Upload E2E report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-report
+          path: |
+            apps/desktop/e2e/playwright-report/
+            apps/desktop/e2e/test-results/
+          retention-days: 14
@@ -276,7 +276,7 @@ jobs:
      - name: Setup Flatpak and verification tools
        run: |
          sudo apt-get update
-          sudo apt-get install -y flatpak flatpak-builder libarchive-tools
+          sudo apt-get install -y flatpak flatpak-builder squashfs-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
@@ -572,9 +572,9 @@ jobs:
          IS_PRERELEASE="${{ steps.version.outputs.is_prerelease }}"

          if [ "$IS_PRERELEASE" = "true" ]; then
-            python3 scripts/update-readme.py "$VERSION" --prerelease
+            node scripts/update-readme.mjs "$VERSION" --prerelease
          else
-            python3 scripts/update-readme.py "$VERSION"
+            node scripts/update-readme.mjs "$VERSION"
          fi

          echo "--- Verifying update ---"
@@ -36,18 +36,18 @@
 > ⚠️ Beta releases may contain bugs and breaking changes. [View all releases](https://github.com/AndyMik90/Auto-Claude/releases)

 <!-- BETA_VERSION_BADGE -->
-[![Beta](https://img.shields.io/badge/beta-2.8.0--beta.1-orange?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.8.0-beta.1)
+[![Beta](https://img.shields.io/badge/beta-2.8.0--beta.5-orange?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.8.0-beta.5)
 <!-- BETA_VERSION_BADGE_END -->

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

 > All releases include SHA256 checksums and VirusTotal scan results for security verification.
@@ -45,7 +45,8 @@
        "noProcessEnv": "off",
        "useNodejsImportProtocol": "off",
        "useImportType": "off",
-        "useTemplate": "off"
+        "useTemplate": "off",
+        "noNonNullAssertion": "warn"
      },
      "suspicious": {
        "recommended": true,
@@ -78,7 +78,9 @@ export default defineConfig({
          // spawned via `new Worker(path)` from WorkerBridge
          'ai/agent/worker': resolve(__dirname, 'src/main/ai/agent/worker.ts'),
        },
-        // Only node-pty needs to be external (native module rebuilt by electron-builder)
+        // Native modules that must remain external (loaded from disk, not bundled).
+        // @libsql/client is loaded lazily via globalThis.require() and resolved
+        // from extraResources/node_modules via Module.globalPaths (see index.ts).
        external: ['@lydell/node-pty']
      }
    }
@@ -1,16 +1,16 @@
 {
-  "name": "auto-claude-ui",
+  "name": "aperant",
  "version": "2.8.0-beta.1",
  "type": "module",
-  "description": "Desktop UI for Auto Claude autonomous coding framework",
-  "homepage": "https://github.com/AndyMik90/Auto-Claude",
+  "description": "Autonomous multi-agent coding framework",
+  "homepage": "https://github.com/AndyMik90/Aperant",
  "repository": {
    "type": "git",
-    "url": "https://github.com/AndyMik90/Auto-Claude.git"
+    "url": "https://github.com/AndyMik90/Aperant.git"
  },
  "main": "./out/main/index.js",
  "author": {
-    "name": "Auto Claude Team",
+    "name": "Aperant Team",
    "email": "119136210+AndyMik90@users.noreply.github.com"
  },
  "license": "AGPL-3.0",
@@ -35,10 +35,12 @@
    "package:flatpak": "electron-builder --linux flatpak",
    "verify:linux": "node scripts/verify-linux-packages.cjs dist",
    "test:verify-linux": "node --test scripts/verify-linux-packages.test.mjs",
-    "start:packaged:mac": "open dist/mac-arm64/Auto-Claude.app || open dist/mac/Auto-Claude.app",
-    "start:packaged:win": "start \"\" \"dist\\win-unpacked\\Auto-Claude.exe\"",
-    "start:packaged:linux": "./dist/linux-unpacked/auto-claude",
+    "start:packaged:mac": "open dist/mac-arm64/Aperant.app || open dist/mac/Aperant.app",
+    "start:packaged:win": "start \"\" \"dist\\win-unpacked\\Aperant.exe\"",
+    "start:packaged:linux": "./dist/linux-unpacked/aperant",
    "test": "vitest run",
+    "test:unit": "vitest run --exclude src/__tests__/integration/ --exclude src/__tests__/e2e/",
+    "test:integration": "vitest run src/__tests__/integration/",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage",
    "test:e2e": "npx playwright test --config=e2e/playwright.config.ts",
@@ -48,27 +50,27 @@
    "typecheck": "tsc --noEmit --incremental"
  },
  "dependencies": {
-    "@ai-sdk/amazon-bedrock": "^4.0.61",
-    "@ai-sdk/anthropic": "^3.0.45",
-    "@ai-sdk/azure": "^3.0.31",
-    "@ai-sdk/google": "^3.0.29",
-    "@ai-sdk/groq": "^3.0.24",
-    "@ai-sdk/mcp": "^1.0.21",
-    "@ai-sdk/mistral": "^2.0.28",
-    "@ai-sdk/openai": "^3.0.30",
-    "@ai-sdk/openai-compatible": "^2.0.30",
-    "@ai-sdk/xai": "^3.0.57",
-    "@anthropic-ai/sdk": "^0.71.2",
+    "@ai-sdk/amazon-bedrock": "^4.0.77",
+    "@ai-sdk/anthropic": "^3.0.58",
+    "@ai-sdk/azure": "^3.0.42",
+    "@ai-sdk/google": "^3.0.43",
+    "@ai-sdk/groq": "^3.0.29",
+    "@ai-sdk/mcp": "^1.0.25",
+    "@ai-sdk/mistral": "^3.0.24",
+    "@ai-sdk/openai": "^3.0.41",
+    "@ai-sdk/openai-compatible": "^2.0.35",
+    "@ai-sdk/xai": "^3.0.67",
+    "@anthropic-ai/sdk": "^0.78.0",
    "@dnd-kit/core": "^6.3.1",
    "@dnd-kit/sortable": "^10.0.0",
    "@dnd-kit/utilities": "^3.2.2",
    "@libsql/client": "^0.17.0",
    "@lydell/node-pty": "^1.1.0",
-    "@modelcontextprotocol/sdk": "^1.26.0",
-    "@openrouter/ai-sdk-provider": "^2.2.3",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@openrouter/ai-sdk-provider": "^2.3.1",
    "@radix-ui/react-alert-dialog": "^1.1.15",
-    "@radix-ui/react-checkbox": "^1.1.4",
-    "@radix-ui/react-collapsible": "^1.1.3",
+    "@radix-ui/react-checkbox": "^1.3.3",
+    "@radix-ui/react-collapsible": "^1.1.12",
    "@radix-ui/react-dialog": "^1.1.15",
    "@radix-ui/react-dropdown-menu": "^2.1.16",
    "@radix-ui/react-popover": "^1.1.15",
@@ -82,88 +84,89 @@
    "@radix-ui/react-tabs": "^1.1.13",
    "@radix-ui/react-toast": "^1.2.15",
    "@radix-ui/react-tooltip": "^1.2.8",
-    "@sentry/electron": "^7.5.0",
+    "@sentry/electron": "^7.10.0",
    "@tailwindcss/typography": "^0.5.19",
-    "@tanstack/react-virtual": "^3.13.13",
+    "@tanstack/react-virtual": "^3.13.22",
    "@tavily/core": "^0.7.2",
    "@xterm/addon-fit": "^0.11.0",
    "@xterm/addon-serialize": "^0.14.0",
    "@xterm/addon-web-links": "^0.12.0",
    "@xterm/addon-webgl": "^0.19.0",
    "@xterm/xterm": "^6.0.0",
-    "ai": "^6.0.91",
+    "ai": "^6.0.116",
    "chokidar": "^5.0.0",
    "class-variance-authority": "^0.7.1",
    "clsx": "^2.1.1",
-    "dotenv": "^17.2.3",
+    "dotenv": "^17.3.1",
    "electron-log": "^5.4.3",
-    "electron-updater": "^6.6.2",
-    "i18next": "^25.7.3",
-    "lucide-react": "^0.562.0",
-    "minimatch": "^10.1.1",
-    "motion": "^12.23.26",
+    "electron-updater": "^6.8.3",
+    "i18next": "^25.8.18",
+    "lucide-react": "^0.577.0",
+    "minimatch": "^10.2.4",
+    "motion": "^12.36.0",
    "proper-lockfile": "^4.1.2",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
-    "react-i18next": "^16.5.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-i18next": "^16.5.8",
    "react-markdown": "^10.1.0",
    "rehype-raw": "^7.0.0",
    "rehype-sanitize": "^6.0.0",
    "remark-gfm": "^4.0.1",
-    "semver": "^7.7.3",
-    "tailwind-merge": "^3.4.0",
+    "semver": "^7.7.4",
+    "tailwind-merge": "^3.5.0",
    "uuid": "^13.0.0",
-    "web-tree-sitter": "^0.26.5",
-    "xstate": "^5.26.0",
-    "zod": "^4.2.1",
-    "zustand": "^5.0.9"
+    "web-tree-sitter": "^0.26.7",
+    "xstate": "^5.28.0",
+    "zod": "^4.3.6",
+    "zustand": "^5.0.11"
  },
  "devDependencies": {
-    "@biomejs/biome": "2.3.11",
+    "@biomejs/biome": "2.4.7",
    "@electron-toolkit/preload": "^3.0.2",
    "@electron-toolkit/utils": "^4.0.0",
-    "@electron/rebuild": "^4.0.2",
-    "@playwright/test": "^1.52.0",
-    "@tailwindcss/postcss": "^4.1.17",
-    "@testing-library/dom": "^10.0.0",
+    "@electron/rebuild": "^4.0.3",
+    "@playwright/test": "^1.58.2",
+    "@tailwindcss/postcss": "^4.2.1",
+    "@testing-library/dom": "^10.4.1",
    "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.1.0",
+    "@testing-library/react": "^16.3.2",
    "@types/minimatch": "^6.0.0",
-    "@types/node": "^25.0.0",
-    "@types/react": "^19.2.7",
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.2.14",
    "@types/react-dom": "^19.2.3",
    "@types/semver": "^7.7.1",
    "@types/uuid": "^11.0.0",
    "@vitejs/plugin-react": "^5.1.2",
-    "autoprefixer": "^10.4.22",
+    "@vitest/coverage-v8": "^4.1.0",
+    "autoprefixer": "^10.4.27",
    "cross-env": "^10.1.0",
    "electron": "40.0.0",
-    "electron-builder": "^26.4.0",
+    "electron-builder": "^26.8.1",
    "electron-vite": "^5.0.0",
    "husky": "^9.1.7",
    "jsdom": "^27.3.0",
-    "lint-staged": "^16.2.7",
-    "postcss": "^8.5.6",
-    "tailwindcss": "^4.1.17",
+    "lint-staged": "^16.4.0",
+    "postcss": "^8.5.8",
+    "tailwindcss": "^4.2.1",
    "typescript": "^5.9.3",
    "vite": "^7.2.7",
-    "vitest": "^4.0.16"
+    "vitest": "^4.1.0"
  },
  "overrides": {
    "electron-builder-squirrel-windows": "^26.0.12",
    "dmg-builder": "^26.0.12",
-    "@electron/rebuild": "4.0.2"
+    "@electron/rebuild": "4.0.3"
  },
  "build": {
-    "appId": "com.autoclaude.ui",
-    "productName": "Auto-Claude",
+    "appId": "com.aperant.app",
+    "productName": "Aperant",
    "npmRebuild": false,
    "artifactName": "${productName}-${version}-${platform}-${arch}.${ext}",
    "publish": [
      {
        "provider": "github",
        "owner": "AndyMik90",
-        "repo": "Auto-Claude"
+        "repo": "Aperant"
      }
    ],
    "directories": {
@@ -185,6 +188,22 @@
      {
        "from": "prompts",
        "to": "prompts"
+      },
+      {
+        "from": "../../node_modules/@libsql",
+        "to": "node_modules/@libsql"
+      },
+      {
+        "from": "../../node_modules/libsql",
+        "to": "node_modules/libsql"
+      },
+      {
+        "from": "../../node_modules/@neon-rs",
+        "to": "node_modules/@neon-rs"
+      },
+      {
+        "from": "../../node_modules/detect-libc",
+        "to": "node_modules/detect-libc"
      }
    ],
    "mac": {
@@ -0,0 +1,407 @@
+#!/usr/bin/env node
+/**
+ * Verify Linux package contents to ensure AppImage, deb, and Flatpak were built correctly.
+ *
+ * This script inspects each Linux package format to verify that the bundled Electron
+ * application (app.asar) is present and packages are valid.
+ *
+ * Usage: node scripts/verify-linux-packages.cjs [dist-dir]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// Minimum expected Flatpak file size (50 MB)
+// Flatpak files are large OCI archives; anything smaller is suspicious
+const FLATPAK_MIN_SIZE_MB = 50;
+
+// Colors for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+};
+
+function log(message, color = colors.reset) {
+  console.log(`${color}${message}${colors.reset}`);
+}
+
+function logSuccess(message) {
+  log(`\u2713 ${message}`, colors.green);
+}
+
+function logError(message) {
+  log(`\u2717 ${message}`, colors.red);
+}
+
+function logWarning(message) {
+  log(`\u26A0 ${message}`, colors.yellow);
+}
+
+function logInfo(message) {
+  log(`\u2139 ${message}`, colors.cyan);
+}
+
+/**
+ * Check if a command exists
+ * Uses 'which' directly without shell interpolation to prevent command injection
+ */
+function commandExists(cmd) {
+  const result = spawnSync('which', [cmd], { stdio: 'ignore' });
+  return result.status === 0;
+}
+
+/**
+ * Find all Linux packages in the dist directory
+ */
+function findPackages(distDir) {
+  const packages = {
+    appImage: null,
+    deb: null,
+    flatpak: null,
+  };
+
+  if (!fs.existsSync(distDir)) {
+    logError(`Distribution directory not found: ${distDir}`);
+    return packages;
+  }
+
+  const files = fs.readdirSync(distDir);
+
+  for (const file of files) {
+    const fullPath = path.join(distDir, file);
+
+    if (file.endsWith('.AppImage')) {
+      if (!packages.appImage) {
+        packages.appImage = fullPath;
+      } else {
+        logWarning(`Multiple AppImage files found, using first: ${path.basename(packages.appImage)}`);
+      }
+    } else if (file.endsWith('.deb')) {
+      if (!packages.deb) {
+        packages.deb = fullPath;
+      } else {
+        logWarning(`Multiple deb files found, using first: ${path.basename(packages.deb)}`);
+      }
+    } else if (file.endsWith('.flatpak')) {
+      if (!packages.flatpak) {
+        packages.flatpak = fullPath;
+      } else {
+        logWarning(`Multiple Flatpak files found, using first: ${path.basename(packages.flatpak)}`);
+      }
+    }
+  }
+
+  return packages;
+}
+
+/**
+ * Verify that a file listing contains the bundled Electron app (app.asar)
+ * @param {string[]} files - List of files from package
+ * @param {string} packageType - Type of package (for error messages)
+ * @returns {Object} Verification result with verified flag and issues array
+ */
+function verifyFileList(files, packageType) {
+  const issues = [];
+
+  // Check for app.asar (the bundled Electron application)
+  // Use boundary-safe match to avoid false positives from resources/app.asar.unpacked
+  const appAsarPattern = /[\\/]resources[\\/]app\.asar$/;
+  const appAsarFound = files.some((f) => appAsarPattern.test(f.trim()));
+  if (!appAsarFound) {
+    issues.push(`app.asar not found in ${packageType} — the Electron app bundle is missing`);
+  }
+
+  return {
+    verified: issues.length === 0,
+    issues,
+    fileCount: files.filter((f) => f.trim()).length,
+  };
+}
+
+// Minimum expected AppImage file size (50 MB)
+const APPIMAGE_MIN_SIZE_MB = 50;
+
+/**
+ * Verify AppImage contents.
+ * AppImages are ELF executables with an embedded SquashFS filesystem.
+ * We try unsquashfs first (can list SquashFS contents), then fall back
+ * to the AppImage's own --appimage-extract, and finally to a size check.
+ */
+function verifyAppImage(appImagePath) {
+  logInfo(`Verifying AppImage: ${path.basename(appImagePath)}`);
+
+  // Try unsquashfs -l (lists squashfs contents without extracting)
+  if (commandExists('unsquashfs')) {
+    const result = spawnSync('unsquashfs', ['-l', appImagePath], {
+      stdio: 'pipe',
+      encoding: 'utf-8',
+      maxBuffer: 50 * 1024 * 1024,
+    });
+
+    if (result.error) {
+      logWarning(`unsquashfs failed: ${result.error.message}, falling back to size check`);
+    } else if (result.status !== 0) {
+      logWarning(`unsquashfs could not read AppImage, falling back to size check`);
+    } else {
+      const files = result.stdout.split('\n');
+      return verifyFileList(files, 'AppImage');
+    }
+  }
+
+  // Try self-extraction to list contents (AppImages support --appimage-extract-and-run)
+  // Make the AppImage executable first
+  try {
+    fs.chmodSync(appImagePath, 0o755);
+  } catch (_) {
+    // Ignore chmod errors
+  }
+
+  const extractResult = spawnSync(appImagePath, ['--appimage-extract', '--stdout'], {
+    stdio: 'pipe',
+    encoding: 'utf-8',
+    maxBuffer: 50 * 1024 * 1024,
+    timeout: 30000,
+    env: { ...process.env, APPIMAGE_EXTRACT_AND_RUN: '1' },
+  });
+
+  // --appimage-extract creates a squashfs-root directory; check if it exists
+  const squashfsRoot = path.join(path.dirname(appImagePath), 'squashfs-root');
+  if (fs.existsSync(squashfsRoot)) {
+    try {
+      const collectFiles = (dir, prefix = '') => {
+        const entries = [];
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+          const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+          entries.push(rel);
+          if (entry.isDirectory()) {
+            entries.push(...collectFiles(path.join(dir, entry.name), rel));
+          }
+        }
+        return entries;
+      };
+      const files = collectFiles(squashfsRoot);
+      const verifyResult = verifyFileList(files, 'AppImage');
+      // Clean up extracted directory
+      fs.rmSync(squashfsRoot, { recursive: true, force: true });
+      return verifyResult;
+    } catch (e) {
+      logWarning(`Failed to read extracted AppImage contents: ${e.message}`);
+      fs.rmSync(squashfsRoot, { recursive: true, force: true });
+    }
+  }
+
+  // Fall back to basic size validation (same approach as Flatpak)
+  logWarning('Could not inspect AppImage contents (unsquashfs not available). Using size validation.');
+  const issues = [];
+  const stats = fs.statSync(appImagePath);
+
+  if (stats.size === 0) {
+    return { verified: false, issues: ['AppImage file is empty'] };
+  }
+
+  if (stats.size < APPIMAGE_MIN_SIZE_MB * 1024 * 1024) {
+    issues.push(
+      `AppImage file seems too small (${(stats.size / 1024 / 1024).toFixed(2)} MB, expected at least ${APPIMAGE_MIN_SIZE_MB} MB)`,
+    );
+  }
+
+  if (issues.length === 0) {
+    logInfo('AppImage passed size validation (content inspection was not possible)');
+  }
+
+  return {
+    verified: issues.length === 0,
+    issues,
+    size: stats.size,
+  };
+}
+
+/**
+ * Verify deb package contents
+ */
+function verifyDeb(debPath) {
+  logInfo(`Verifying deb package: ${path.basename(debPath)}`);
+
+  if (!commandExists('dpkg-deb')) {
+    logWarning('dpkg-deb not found. Skipping deb verification');
+    return { verified: false, reason: 'dpkg-deb not available', critical: true };
+  }
+
+  const result = spawnSync('dpkg-deb', ['-c', debPath], {
+    stdio: 'pipe',
+    encoding: 'utf-8',
+    maxBuffer: 50 * 1024 * 1024,
+  });
+
+  if (result.error) {
+    logError(`Failed to execute dpkg-deb: ${result.error.message}`);
+    return { verified: false, issues: [`Command execution failed: ${result.error.message}`] };
+  }
+
+  if (result.status !== 0) {
+    logError(`Failed to read deb package: ${result.stderr}`);
+    return { verified: false, issues: ['Failed to extract file list'] };
+  }
+
+  const files = result.stdout.split('\n');
+  return verifyFileList(files, 'deb package');
+}
+
+/**
+ * Verify Flatpak package contents
+ * Flatpak OCI archives are complex to inspect, so we do basic validation
+ */
+function verifyFlatpak(flatpakPath) {
+  logInfo(`Verifying Flatpak package: ${path.basename(flatpakPath)}`);
+
+  const issues = [];
+
+  if (!fs.existsSync(flatpakPath)) {
+    return { verified: false, issues: ['Flatpak file does not exist'] };
+  }
+
+  const stats = fs.statSync(flatpakPath);
+  if (stats.size === 0) {
+    return { verified: false, issues: ['Flatpak file is empty'] };
+  }
+
+  if (stats.size < FLATPAK_MIN_SIZE_MB * 1024 * 1024) {
+    issues.push(
+      `Flatpak file seems too small (${(stats.size / 1024 / 1024).toFixed(2)} MB, expected at least ${FLATPAK_MIN_SIZE_MB} MB)`,
+    );
+  }
+
+  return {
+    verified: issues.length === 0,
+    issues,
+    size: stats.size,
+  };
+}
+
+/**
+ * Main verification function
+ */
+function main() {
+  const distDir = process.argv[2] || path.join(__dirname, '..', 'dist');
+
+  log('\n=== Linux Package Verification ===\n', colors.blue);
+  logInfo(`Distribution directory: ${distDir}\n`);
+
+  const packages = findPackages(distDir);
+
+  // Report found packages — all three targets are required
+  let missingTargets = false;
+
+  if (packages.appImage) {
+    logSuccess(`Found AppImage: ${path.basename(packages.appImage)}`);
+  } else {
+    logError('No AppImage found — expected build target is missing');
+    missingTargets = true;
+  }
+
+  if (packages.deb) {
+    logSuccess(`Found deb: ${path.basename(packages.deb)}`);
+  } else {
+    logError('No deb package found — expected build target is missing');
+    missingTargets = true;
+  }
+
+  if (packages.flatpak) {
+    logSuccess(`Found Flatpak: ${path.basename(packages.flatpak)}`);
+  } else {
+    logError('No Flatpak package found — expected build target is missing');
+    missingTargets = true;
+  }
+
+  if (missingTargets) {
+    logError('\nOne or more expected Linux package targets are missing!');
+    process.exit(1);
+  }
+
+  log('');
+
+  // Verify each package
+  const results = {};
+
+  if (packages.appImage) {
+    results.appImage = verifyAppImage(packages.appImage);
+  }
+
+  if (packages.deb) {
+    results.deb = verifyDeb(packages.deb);
+  }
+
+  if (packages.flatpak) {
+    results.flatpak = verifyFlatpak(packages.flatpak);
+  }
+
+  // Print results
+  log('\n=== Verification Results ===\n', colors.blue);
+
+  let hasFailures = false;
+  let hasCriticalSkips = false;
+
+  for (const [type, result] of Object.entries(results)) {
+    if (result.reason) {
+      if (result.critical) {
+        logError(`${type}: CRITICAL - SKIPPED (${result.reason})`);
+        hasCriticalSkips = true;
+      } else {
+        logWarning(`${type}: SKIPPED (${result.reason})`);
+      }
+    } else if (result.verified) {
+      logSuccess(`${type}: VERIFIED`);
+      if (result.fileCount) {
+        logInfo(`  Files: ${result.fileCount}`);
+      }
+      if (result.size) {
+        logInfo(`  Size: ${(result.size / 1024 / 1024).toFixed(2)} MB`);
+      }
+    } else {
+      logError(`${type}: FAILED`);
+      hasFailures = true;
+      for (const issue of result.issues || []) {
+        logError(`  - ${issue}`);
+      }
+    }
+  }
+
+  log('');
+
+  if (hasFailures || hasCriticalSkips) {
+    logError('\n=== VERIFICATION FAILED ===\n');
+    if (hasFailures) {
+      log('Some packages are missing critical files. This will cause runtime errors.\n', colors.red);
+    }
+    if (hasCriticalSkips) {
+      log('Some packages could not be verified due to missing required tools.\n', colors.red);
+      log('Install required tools:\n', colors.red);
+      log('  - unsquashfs: sudo apt-get install squashfs-tools\n', colors.red);
+      log('  - dpkg-deb: sudo apt-get install dpkg\n', colors.red);
+    }
+    process.exit(1);
+  } else {
+    logSuccess('\n=== ALL PACKAGES VERIFIED ===\n');
+    log('All Linux packages contain the required files.\n', colors.green);
+    process.exit(0);
+  }
+}
+
+// Only run main if this file is executed directly (not imported)
+if (require.main === module) {
+  main();
+}
+
+// Export for testing
+module.exports = {
+  findPackages,
+  verifyFileList,
+  verifyAppImage,
+  verifyDeb,
+  verifyFlatpak,
+};
@@ -7,17 +7,20 @@ import { EventEmitter } from 'events';
 // Mock app
 export const app = {
  getPath: vi.fn((name: string) => {
+    const os = require('os');
+    const path = require('path');
    const paths: Record<string, string> = {
-      userData: '/tmp/test-app-data',
-      home: '/tmp/test-home',
-      temp: '/tmp'
+      userData: path.join(os.homedir(), '.aperant-test-data'),
+      home: os.homedir(),
+      temp: os.tmpdir()
    };
-    return paths[name] || '/tmp';
+    return paths[name] || path.join(os.homedir(), '.aperant-test');
  }),
  getAppPath: vi.fn(() => '/tmp/test-app'),
  getVersion: vi.fn(() => '0.1.0'),
  isPackaged: false,
  on: vi.fn(),
+  whenReady: vi.fn(() => Promise.resolve()),
  quit: vi.fn()
 };

@@ -209,7 +209,6 @@ describe('Claude Profile IPC Integration', () => {

      await handleProfileSave?.(null, profile);

-      // biome-ignore lint/style/noNonNullAssertion: Test file - configDir is set in createTestProfile
      expect(existsSync(profile.configDir!)).toBe(true);
    });

@@ -224,7 +223,6 @@ describe('Claude Profile IPC Integration', () => {

      await handleProfileSave?.(null, profile);

-      // biome-ignore lint/style/noNonNullAssertion: Test file - configDir is set in createTestProfile
      expect(existsSync(profile.configDir!)).toBe(false);
    });

@@ -302,7 +302,7 @@ describe('Application Logger', () => {
      const { generateDebugReport } = await import('../app-logger');
      const report = generateDebugReport();

-      expect(report).toContain('=== Auto Claude Debug Report ===');
+      expect(report).toContain('=== Aperant Debug Report ===');
      expect(report).toContain('--- System Information ---');
      expect(report).toContain('--- Recent Errors ---');
      expect(report).toContain('=== End Debug Report ===');
@@ -0,0 +1,227 @@
+/**
+ * Tests for ensureOnboardingComplete function in cli-integration-handler.ts
+ *
+ * Tests the exported ensureOnboardingComplete() which reads/writes .claude.json
+ * to set hasCompletedOnboarding: true, suppressing Claude's onboarding wizard
+ * for already-authenticated profiles.
+ */
+
+import { describe, test, expect, vi, beforeEach } from 'vitest';
+import * as path from 'path';
+import * as os from 'os';
+
+// ---- fs mock (sync only — the function uses fs, not fs/promises) ----
+const mockFiles: Map<string, string | Error> = new Map();
+
+vi.mock('fs', () => {
+  const readFileSync = vi.fn((filePath: string, _encoding?: string): string => {
+    const entry = mockFiles.get(filePath);
+    if (entry === undefined) {
+      const err = new Error(`ENOENT: no such file or directory, open '${filePath}'`) as NodeJS.ErrnoException;
+      err.code = 'ENOENT';
+      throw err;
+    }
+    if (entry instanceof Error) {
+      throw entry;
+    }
+    return entry;
+  });
+
+  const writeFileSync = vi.fn();
+  const renameSync = vi.fn();
+
+  return { default: { readFileSync, writeFileSync, renameSync }, readFileSync, writeFileSync, renameSync };
+});
+
+// ---- stubs for heavy transitive dependencies ----
+vi.mock('electron', () => ({
+  ipcMain: { handle: vi.fn() },
+  app: { getPath: vi.fn(() => os.tmpdir()), getAppPath: vi.fn(() => os.tmpdir()) },
+  dialog: { showOpenDialog: vi.fn() },
+  shell: { openExternal: vi.fn() },
+}));
+
+vi.mock('@electron-toolkit/utils', () => ({ is: { dev: true } }));
+
+vi.mock('../../shared/constants', async () => {
+  const actual = await vi.importActual<typeof import('../../shared/constants')>('../../shared/constants');
+  return { ...actual };
+});
+
+vi.mock('../claude-profile-manager', () => ({
+  getClaudeProfileManager: vi.fn(),
+  initializeClaudeProfileManager: vi.fn(),
+}));
+
+vi.mock('../claude-profile/credential-utils', () => ({
+  getFullCredentialsFromKeychain: vi.fn(),
+  clearKeychainCache: vi.fn(),
+  updateProfileSubscriptionMetadata: vi.fn(),
+}));
+
+vi.mock('../claude-profile/usage-monitor', () => ({
+  getUsageMonitor: vi.fn(),
+}));
+
+vi.mock('../claude-profile/profile-utils', () => ({
+  getEmailFromConfigDir: vi.fn(),
+}));
+
+vi.mock('../terminal/output-parser', () => ({}));
+vi.mock('../terminal/session-handler', () => ({}));
+
+vi.mock('./pty-manager', () => ({
+  writeToPty: vi.fn(),
+  resizePty: vi.fn(),
+}));
+
+vi.mock('../ipc-handlers/utils', () => ({
+  safeSendToRenderer: vi.fn(),
+}));
+
+vi.mock('../../shared/utils/debug-logger', () => ({
+  debugLog: vi.fn(),
+  debugError: vi.fn(),
+}));
+
+vi.mock('../../shared/utils/shell-escape', () => ({
+  escapeShellArg: vi.fn((s: string) => s),
+  escapeForWindowsDoubleQuote: vi.fn((s: string) => s),
+  buildCdCommand: vi.fn((cwd: string) => `cd ${cwd}`),
+}));
+
+vi.mock('../cli-utils', () => ({
+  getClaudeCliInvocation: vi.fn(() => 'claude'),
+  getClaudeCliInvocationAsync: vi.fn(async () => 'claude'),
+}));
+
+vi.mock('../platform', () => ({
+  isWindows: vi.fn(() => false),
+}));
+
+vi.mock('../settings-utils', () => ({
+  readSettingsFileAsync: vi.fn(async () => ({})),
+  readSettingsFile: vi.fn(() => ({})),
+}));
+
+// ---- import the function under test ----
+import { ensureOnboardingComplete } from '../terminal/cli-integration-handler';
+import * as fs from 'fs';
+
+// ---- helpers ----
+function claudeJsonPath(configDir: string): string {
+  const expanded = configDir.startsWith('~')
+    ? configDir.replace(/^~/, os.homedir())
+    : configDir;
+  return path.join(path.resolve(expanded), '.claude.json');
+}
+
+const TEST_DIR = '/tmp/test-profile';
+
+describe('ensureOnboardingComplete', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockFiles.clear();
+  });
+
+  // ---- ENOENT: file does not exist ----
+  test('returns early (no write) when .claude.json does not exist', () => {
+    // mockFiles is empty → readFileSync will throw ENOENT
+    ensureOnboardingComplete(TEST_DIR);
+
+    expect(fs.writeFileSync).not.toHaveBeenCalled();
+  });
+
+  // ---- already set ----
+  test('returns early (no write) when hasCompletedOnboarding is already true', () => {
+    const filePath = claudeJsonPath(TEST_DIR);
+    mockFiles.set(filePath, JSON.stringify({ hasCompletedOnboarding: true }));
+
+    ensureOnboardingComplete(TEST_DIR);
+
+    expect(fs.writeFileSync).not.toHaveBeenCalled();
+  });
+
+  // ---- missing flag → should write ----
+  test('writes hasCompletedOnboarding: true when flag is absent', () => {
+    const filePath = claudeJsonPath(TEST_DIR);
+    mockFiles.set(filePath, JSON.stringify({ someOtherField: 'value' }));
+
+    ensureOnboardingComplete(TEST_DIR);
+
+    expect(fs.writeFileSync).toHaveBeenCalledOnce();
+    const written = JSON.parse((fs.writeFileSync as ReturnType<typeof vi.fn>).mock.calls[0][1] as string);
+    expect(written.hasCompletedOnboarding).toBe(true);
+    expect(written.someOtherField).toBe('value');
+  });
+
+  // ---- flag is false → should write ----
+  test('writes hasCompletedOnboarding: true when flag is false', () => {
+    const filePath = claudeJsonPath(TEST_DIR);
+    mockFiles.set(filePath, JSON.stringify({ hasCompletedOnboarding: false }));
+
+    ensureOnboardingComplete(TEST_DIR);
+
+    expect(fs.writeFileSync).toHaveBeenCalledOnce();
+    const written = JSON.parse((fs.writeFileSync as ReturnType<typeof vi.fn>).mock.calls[0][1] as string);
+    expect(written.hasCompletedOnboarding).toBe(true);
+  });
+
+  // ---- non-object JSON (string) → should return silently ----
+  test('returns early (no write) when .claude.json contains a JSON string', () => {
+    const filePath = claudeJsonPath(TEST_DIR);
+    mockFiles.set(filePath, JSON.stringify('just a string'));
+
+    ensureOnboardingComplete(TEST_DIR);
+
+    expect(fs.writeFileSync).not.toHaveBeenCalled();
+  });
+
+  // ---- array JSON → should return silently ----
+  test('returns early (no write) when .claude.json contains a JSON array', () => {
+    const filePath = claudeJsonPath(TEST_DIR);
+    mockFiles.set(filePath, JSON.stringify([1, 2, 3]));
+
+    ensureOnboardingComplete(TEST_DIR);
+
+    expect(fs.writeFileSync).not.toHaveBeenCalled();
+  });
+
+  // ---- corrupted / invalid JSON → outer catch swallows error ----
+  test('handles corrupted JSON gracefully without throwing', () => {
+    const filePath = claudeJsonPath(TEST_DIR);
+    mockFiles.set(filePath, '{ invalid json }');
+
+    expect(() => ensureOnboardingComplete(TEST_DIR)).not.toThrow();
+    expect(fs.writeFileSync).not.toHaveBeenCalled();
+  });
+
+  // ---- tilde expansion ----
+  test('expands leading tilde to home directory', () => {
+    const tildeDir = '~/myprofile';
+    const resolvedDir = path.resolve(tildeDir.replace(/^~/, os.homedir()));
+    const filePath = path.join(resolvedDir, '.claude.json');
+
+    mockFiles.set(filePath, JSON.stringify({}));
+
+    ensureOnboardingComplete(tildeDir);
+
+    expect(fs.writeFileSync).toHaveBeenCalledOnce();
+    // Writes to a temp file (claudeJsonPath + UUID + .tmp), then renames to target
+    const writtenPath = (fs.writeFileSync as ReturnType<typeof vi.fn>).mock.calls[0][0] as string;
+    expect(writtenPath).toMatch(new RegExp(`^${filePath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\..*\\.tmp$`));
+    expect(fs.renameSync).toHaveBeenCalledWith(writtenPath, filePath);
+  });
+
+  // ---- write error → outer catch swallows error ----
+  test('handles write error gracefully without throwing', () => {
+    const filePath = claudeJsonPath(TEST_DIR);
+    mockFiles.set(filePath, JSON.stringify({}));
+
+    (fs.writeFileSync as ReturnType<typeof vi.fn>).mockImplementationOnce(() => {
+      throw new Error('EACCES: permission denied');
+    });
+
+    expect(() => ensureOnboardingComplete(TEST_DIR)).not.toThrow();
+  });
+});
@@ -140,10 +140,6 @@ export class AgentManager extends EventEmitter {
    provider: string;
    modelId: string;
    configDir?: string;
-    /** Full ordered account queue for worker-side auto-swap */
-    accountQueue?: ProviderAccount[];
-    /** The account ID selected for this session */
-    currentAccountId?: string;
  }> {
    // Read provider accounts and priority order from settings
    const settings = readSettingsFile();
@@ -185,8 +181,6 @@ export class AgentManager extends EventEmitter {
          provider: resolved.resolvedProvider,
          modelId: resolved.resolvedModelId,
          configDir: undefined, // Queue-based auth handles its own token refresh
-          accountQueue: orderedQueue,
-          currentAccountId: resolved.accountId,
        };
      }
      console.warn('[AgentManager] No available account in provider queue, falling back to legacy profile');
@@ -419,8 +413,6 @@ export class AgentManager extends EventEmitter {
      projectId,
      processType: 'spec-creation',
      session: sessionConfig,
-      accountQueue: resolved.accountQueue,
-      currentAccountId: resolved.currentAccountId,
    };

    // Store context for potential restart
@@ -545,8 +537,6 @@ export class AgentManager extends EventEmitter {
      projectId,
      processType: 'task-execution',
      session: sessionConfig,
-      accountQueue: resolved.accountQueue,
-      currentAccountId: resolved.currentAccountId,
    };

    // Store context for potential restart
@@ -650,8 +640,6 @@ export class AgentManager extends EventEmitter {
      projectId,
      processType: 'qa-process',
      session: sessionConfig,
-      accountQueue: resolved.accountQueue,
-      currentAccountId: resolved.currentAccountId,
    };

    await this.processManager.spawnWorkerProcess(taskId, executorConfig, {}, 'qa-process', projectId);
@@ -261,49 +261,6 @@ export class AgentProcessManager {
    allOutput: string,
    processType: ProcessType
  ): boolean {
-    const source = processType === 'spec-creation' ? 'roadmap' : 'task';
-
-    // Fast-path: check for structured outcome sentinels emitted by WorkerBridge.
-    // These are prefixed with `__WORKER_OUTCOME__:<outcome>` so we can detect
-    // rate limits and auth failures without relying on text pattern matching.
-    if (allOutput.includes('__WORKER_OUTCOME__:rate_limited')) {
-      // Build a minimal detection result that matches RateLimitDetectionResult so
-      // we can reuse the existing auto-swap and notification flow.
-      const syntheticRateLimitDetection = {
-        isRateLimited: true,
-        resetTime: undefined as string | undefined,
-        limitType: undefined as 'session' | 'weekly' | undefined,
-        profileId: undefined as string | undefined,
-        suggestedProfile: undefined as { id: string; name: string } | undefined,
-      };
-      const wasHandled = this.handleRateLimitWithAutoSwap(taskId, syntheticRateLimitDetection, processType);
-      if (wasHandled) return true;
-
-      const rateLimitInfo = createSDKRateLimitInfo(source, syntheticRateLimitDetection, { taskId });
-      this.emitter.emit('sdk-rate-limit', rateLimitInfo);
-      return true;
-    }
-
-    if (allOutput.includes('__WORKER_OUTCOME__:auth_failure')) {
-      const syntheticAuthFailureDetection = {
-        isAuthFailure: true,
-        profileId: undefined as string | undefined,
-        failureType: 'unknown' as const,
-        message: 'Authentication failed (worker outcome)',
-        originalError: undefined as string | undefined,
-      };
-      const wasHandled = this.handleAuthFailureWithAutoSwap(taskId, syntheticAuthFailureDetection);
-      if (!wasHandled) {
-        this.emitter.emit('auth-failure', taskId, {
-          profileId: syntheticAuthFailureDetection.profileId,
-          failureType: syntheticAuthFailureDetection.failureType,
-          message: syntheticAuthFailureDetection.message,
-          originalError: syntheticAuthFailureDetection.originalError,
-        });
-      }
-      return true;
-    }
-
    console.log('[AgentProcess] Checking for rate limit in output (last 500 chars):', allOutput.slice(-500));

    const rateLimitDetection = detectRateLimit(allOutput);
@@ -323,7 +280,9 @@ export class AgentProcessManager {
      );
      if (wasHandled) return true;

+      const source = processType === 'spec-creation' ? 'roadmap' : 'task';
      const rateLimitInfo = createSDKRateLimitInfo(source, rateLimitDetection, { taskId });
+      console.log('[AgentProcess] Emitting sdk-rate-limit event (manual):', rateLimitInfo);
      this.emitter.emit('sdk-rate-limit', rateLimitInfo);
      return true;
    }
@@ -913,14 +872,7 @@ export class AgentProcessManager {
      }
    });

-    let workerErrorOutput = '';
-    const MAX_ERROR_OUTPUT_LENGTH = 10_000;
-
    bridge.on('error', (tId: string, error: string, pId?: string) => {
-      workerErrorOutput += error + '\n';
-      if (workerErrorOutput.length > MAX_ERROR_OUTPUT_LENGTH) {
-        workerErrorOutput = workerErrorOutput.slice(-MAX_ERROR_OUTPUT_LENGTH);
-      }
      this.emitter.emit('error', tId, error, pId);
    });

@@ -941,17 +893,16 @@ export class AgentProcessManager {
      }

      if (code !== 0) {
-        // Attempt rate limit / auth failure detection and auto-swap
-        const wasHandled = this.handleProcessFailure(tId, workerErrorOutput, processType);
-
-        if (!wasHandled) {
-          this.emitter.emit('execution-progress', tId, {
-            phase: 'failed',
-            phaseProgress: 0,
-            overallProgress: 0,
-            message: `Worker exited with code ${code}`,
-          }, pId);
-        }
+        // Collect any output for rate limit / auth failure detection
+        // For worker threads, error messages are emitted via 'error' events
+        // rather than stdout parsing. The handleProcessFailure method still works
+        // with accumulated output if needed.
+        this.emitter.emit('execution-progress', tId, {
+          phase: 'failed',
+          phaseProgress: 0,
+          overallProgress: 0,
+          message: `Worker exited with code ${code}`,
+        }, pId);
      }

      this.emitter.emit('exit', tId, code, pType, pId);
@@ -980,7 +931,7 @@ export class AgentProcessManager {

    // Emit initial progress
    this.emitter.emit('execution-progress', taskId, {
-      phase: 'planning',
+      phase: processType === 'spec-creation' ? 'planning' : 'planning',
      phaseProgress: 0,
      overallProgress: 0,
      message: 'Starting AI agent session...',
@@ -264,7 +264,7 @@ export class AgentQueueManager {
            abortSignal: abortController.signal,
          },
          (event: IdeationStreamEvent) => {
-            if (event.type === 'text-delta' || event.type === 'status') {
+            if (event.type === 'text-delta') {
              this.emitter.emit('ideation-log', projectId, event.text);
            }
          }
@@ -10,7 +10,6 @@
 import type { ExecutionProgressData, ProcessType } from '../../../main/agent/types';
 import type { SessionConfig, SessionResult, StreamEvent } from '../session/types';
 import type { RunnerOptions } from '../session/runner';
-import type { ProviderAccount } from '../../../shared/types/provider-account';

 // =============================================================================
 // Worker Configuration
@@ -29,10 +28,6 @@ export interface WorkerConfig {
  processType: ProcessType;
  /** Serializable session config (model resolved in worker from these params) */
  session: SerializableSessionConfig;
-  /** Account queue for auto-swap on rate limit (resolved in main thread, serializable) */
-  accountQueue?: ProviderAccount[];
-  /** Current account ID for the session (used to exclude on swap) */
-  currentAccountId?: string;
 }

 /**
@@ -194,8 +189,4 @@ export interface AgentExecutorConfig {
  session: SerializableSessionConfig;
  /** Optional auth refresh callback (runs in main thread) */
  onAuthRefresh?: RunnerOptions['onAuthRefresh'];
-  /** Account queue for auto-swap (resolved in main thread where settings are available) */
-  accountQueue?: ProviderAccount[];
-  /** Current account ID from queue resolution */
-  currentAccountId?: string;
 }
@@ -40,8 +40,8 @@ const __dirname = path.dirname(__filename);
 */
 function resolveWorkerPath(): string {
  if (app.isPackaged) {
-    // Production: worker is bundled alongside other main-process code
-    return path.join(process.resourcesPath, 'app', 'main', 'ai', 'agent', 'worker.js');
+    // Production: worker is inside app.asar at out/main/ai/agent/worker.js
+    return path.join(process.resourcesPath, 'app.asar', 'out', 'main', 'ai', 'agent', 'worker.js');
  }
  // Dev: electron-vite outputs worker at out/main/ai/agent/worker.js
  // because the Rollup input key is 'ai/agent/worker'.
@@ -92,8 +92,6 @@ export class WorkerBridge extends EventEmitter {
      projectId: config.projectId,
      processType: config.processType,
      session: config.session,
-      accountQueue: config.accountQueue,
-      currentAccountId: config.currentAccountId,
    };

    const workerPath = resolveWorkerPath();
@@ -214,11 +212,6 @@ export class WorkerBridge extends EventEmitter {
  /**
   * Handle the final session result from the worker.
   * Maps SessionResult.outcome to an exit code.
-   *
-   * For `rate_limited` and `auth_failure` outcomes, the error message is
-   * prefixed with a structured sentinel (`__WORKER_OUTCOME__:<outcome>`) so
-   * that AgentProcess can detect the failure type structurally instead of
-   * relying solely on text pattern matching.
   */
  private handleResult(taskId: string, result: SessionResult, projectId?: string): void {
    // Map outcome to exit code
@@ -229,18 +222,7 @@ export class WorkerBridge extends EventEmitter {
    this.emitTyped('log', taskId, summary, projectId);

    if (result.error) {
-      // For structured outcomes that AgentProcess needs to react to, prefix the
-      // error message with a sentinel so the consuming layer can detect the
-      // outcome type without pattern-matching on human-readable text.
-      const needsSentinel = result.outcome === 'rate_limited' || result.outcome === 'auth_failure';
-      const errorMessage = needsSentinel
-        ? `__WORKER_OUTCOME__:${result.outcome} ${result.error.message}`
-        : result.error.message;
-      this.emitTyped('error', taskId, errorMessage, projectId);
-    } else if (result.outcome === 'rate_limited' || result.outcome === 'auth_failure') {
-      // No error object but the outcome still indicates a structured failure —
-      // emit the sentinel alone so AgentProcess can trigger the swap flow.
-      this.emitTyped('error', taskId, `__WORKER_OUTCOME__:${result.outcome}`, projectId);
+      this.emitTyped('error', taskId, result.error.message, projectId);
    }

    // Emit exit and cleanup
@@ -34,9 +34,7 @@ import type {
  WorkerTaskEventMessage,
 } from './types';
 import type { Tool as AITool } from 'ai';
-import type { SessionConfig, StreamEvent, SessionResult, SessionError } from '../session/types';
-import type { QueueResolvedAuth } from '../auth/types';
-import type { ProviderAccount } from '../../../shared/types/provider-account';
+import type { SessionConfig, StreamEvent, SessionResult } from '../session/types';
 import { BuildOrchestrator } from '../orchestration/build-orchestrator';
 import { QALoop } from '../orchestration/qa-loop';
 import { SpecOrchestrator } from '../orchestration/spec-orchestrator';
@@ -124,24 +122,6 @@ parentPort.on('message', (msg: MainToWorkerMessage) => {
 // Shared Helpers
 // =============================================================================

-/**
- * Build the onAccountSwitch callback for runner options.
- * Extracted to avoid triplication across the three session-launch call sites.
- * The second parameter (error) is accepted for type correctness but not used yet.
- */
-function buildAccountSwitchCallback(
-  modelId: string,
-  accountQueue?: ProviderAccount[],
-): ((failedAccountId: string, error: SessionError) => Promise<QueueResolvedAuth | null>) | undefined {
-  if (!accountQueue?.length) return undefined;
-  return async (failedAccountId: string) => {
-    const { resolveAuthFromQueue } = await import('../auth/resolver');
-    return resolveAuthFromQueue(modelId, accountQueue, {
-      excludeAccountIds: [failedAccountId],
-    });
-  };
-}
-
 /**
 * Reconstruct the SecurityProfile from the serialized form in session config.
 * SecurityProfile uses Set objects that can't cross worker boundaries.
@@ -361,8 +341,6 @@ async function runSingleSession(
          modelId: phaseModelId,
        })
      : undefined,
-    onAccountSwitch: buildAccountSwitchCallback(baseSession.modelId, config.accountQueue),
-    currentAccountId: config.currentAccountId,
  };

  let sessionResult: SessionResult;
@@ -539,8 +517,6 @@ async function runDefaultSession(
            modelId: session.modelId,
          })
        : undefined,
-      onAccountSwitch: buildAccountSwitchCallback(session.modelId, config.accountQueue),
-      currentAccountId: config.currentAccountId,
    }, {
      contextWindowLimit,
      apiKey: session.apiKey,
@@ -1137,8 +1113,6 @@ async function runAgenticSpecOrchestrator(
            modelId: session.modelId,
          })
        : undefined,
-      onAccountSwitch: buildAccountSwitchCallback(session.modelId, config.accountQueue),
-      currentAccountId: config.currentAccountId,
    }, {
      contextWindowLimit,
      apiKey: session.apiKey,
@@ -0,0 +1,507 @@
+/**
+ * Tests for AI Auth Resolver
+ *
+ * Validates the multi-stage credential resolution fallback chain,
+ * provider account resolution, settings accessor registration,
+ * environment variable fallback, and Z.AI endpoint routing.
+ */
+
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+
+// Mock token-refresh before importing resolver
+// Path resolution from src/main/ai/auth/__tests__/:
+//   ../     = src/main/ai/auth/
+//   ../../  = src/main/ai/
+//   ../../../ = src/main/
+// So ../../../claude-profile/ = src/main/claude-profile/
+vi.mock('../../../claude-profile/token-refresh', () => ({
+  ensureValidToken: vi.fn(),
+  reactiveTokenRefresh: vi.fn(),
+}));
+
+// Mock profile-scorer
+vi.mock('../../../claude-profile/profile-scorer', () => ({
+  scoreProviderAccount: vi.fn(),
+}));
+
+// Mock model equivalence
+// ../../../../shared/ = src/shared/ (4 levels up from __tests__ = src/)
+vi.mock('../../../../shared/constants/models', () => ({
+  resolveModelEquivalent: vi.fn(),
+}));
+
+// Mock provider factory detection
+// ../../providers/ = src/main/ai/providers/
+vi.mock('../../providers/factory', () => ({
+  detectProviderFromModel: vi.fn(),
+}));
+
+import { ensureValidToken, reactiveTokenRefresh } from '../../../claude-profile/token-refresh';
+import { scoreProviderAccount } from '../../../claude-profile/profile-scorer';
+import { resolveModelEquivalent } from '../../../../shared/constants/models';
+import { detectProviderFromModel } from '../../providers/factory';
+import {
+  resolveAuth,
+  hasCredentials,
+  registerSettingsAccessor,
+  refreshOAuthTokenReactive,
+  resolveAuthFromQueue,
+  buildDefaultQueueConfig,
+} from '../resolver';
+
+const mockEnsureValidToken = vi.mocked(ensureValidToken);
+const mockReactiveTokenRefresh = vi.mocked(reactiveTokenRefresh);
+const mockScoreProviderAccount = vi.mocked(scoreProviderAccount);
+const mockResolveModelEquivalent = vi.mocked(resolveModelEquivalent);
+const _mockDetectProviderFromModel = vi.mocked(detectProviderFromModel);
+
+// Helper: reset the module-level settings accessor between tests
+function clearSettingsAccessor() {
+  registerSettingsAccessor(() => undefined);
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  clearSettingsAccessor();
+  // Clean up any environment variable side effects
+  delete process.env.ANTHROPIC_API_KEY;
+  delete process.env.OPENAI_API_KEY;
+  delete process.env.ANTHROPIC_BASE_URL;
+  delete process.env.OPENAI_BASE_URL;
+});
+
+afterEach(() => {
+  delete process.env.ANTHROPIC_API_KEY;
+  delete process.env.OPENAI_API_KEY;
+  delete process.env.ANTHROPIC_BASE_URL;
+  delete process.env.OPENAI_BASE_URL;
+});
+
+// =============================================================================
+// registerSettingsAccessor
+// =============================================================================
+
+describe('registerSettingsAccessor', () => {
+  it('wires up settings so subsequent calls read from the accessor', async () => {
+    registerSettingsAccessor((key) => (key === 'globalAnthropicApiKey' ? 'sk-from-settings' : undefined));
+
+    const auth = await resolveAuth({ provider: 'anthropic' });
+    expect(auth).not.toBeNull();
+    expect(auth?.apiKey).toBe('sk-from-settings');
+    expect(auth?.source).toBe('profile-api-key');
+  });
+});
+
+// =============================================================================
+// Stage 1: Profile OAuth Token
+// =============================================================================
+
+describe('resolveAuth — Stage 1: Profile OAuth', () => {
+  it('returns oauth token for anthropic when ensureValidToken resolves', async () => {
+    mockEnsureValidToken.mockResolvedValueOnce({ token: 'oauth-token-abc', wasRefreshed: false });
+
+    const auth = await resolveAuth({ provider: 'anthropic', configDir: '/home/.config/claude' });
+
+    expect(auth).not.toBeNull();
+    expect(auth?.apiKey).toBe('oauth-token-abc');
+    expect(auth?.source).toBe('profile-oauth');
+    expect(auth?.headers).toMatchObject({ 'anthropic-beta': expect.stringContaining('oauth') });
+  });
+
+  it('includes custom base URL when ANTHROPIC_BASE_URL is set', async () => {
+    process.env.ANTHROPIC_BASE_URL = 'https://proxy.example.com';
+    mockEnsureValidToken.mockResolvedValueOnce({ token: 'oauth-token-abc', wasRefreshed: false });
+
+    const auth = await resolveAuth({ provider: 'anthropic' });
+
+    expect(auth?.baseURL).toBe('https://proxy.example.com');
+  });
+
+  it('skips oauth stage for non-anthropic providers', async () => {
+    // openai has no oauth stage; should fall through to environment
+    process.env.OPENAI_API_KEY = 'sk-env-openai';
+
+    const auth = await resolveAuth({ provider: 'openai' });
+
+    expect(mockEnsureValidToken).not.toHaveBeenCalled();
+    expect(auth?.source).toBe('environment');
+  });
+
+  it('falls through when ensureValidToken throws', async () => {
+    mockEnsureValidToken.mockRejectedValueOnce(new Error('keychain locked'));
+    process.env.ANTHROPIC_API_KEY = 'sk-env-fallback';
+
+    const auth = await resolveAuth({ provider: 'anthropic' });
+
+    expect(auth?.apiKey).toBe('sk-env-fallback');
+    expect(auth?.source).toBe('environment');
+  });
+
+  it('falls through when ensureValidToken returns no token', async () => {
+    mockEnsureValidToken.mockResolvedValueOnce({ token: null, wasRefreshed: false });
+    process.env.ANTHROPIC_API_KEY = 'sk-env-fallback';
+
+    const auth = await resolveAuth({ provider: 'anthropic' });
+
+    expect(auth?.source).toBe('environment');
+  });
+});
+
+// =============================================================================
+// Stage 2: Profile API Key (from settings)
+// =============================================================================
+
+describe('resolveAuth — Stage 2: Profile API Key', () => {
+  it('returns api-key from settings when no oauth token available', async () => {
+    mockEnsureValidToken.mockResolvedValueOnce({ token: null, wasRefreshed: false });
+    registerSettingsAccessor((key) => (key === 'globalAnthropicApiKey' ? 'sk-settings-key' : undefined));
+
+    const auth = await resolveAuth({ provider: 'anthropic' });
+
+    expect(auth?.apiKey).toBe('sk-settings-key');
+    expect(auth?.source).toBe('profile-api-key');
+  });
+
+  it('includes base URL from environment even for settings-based keys', async () => {
+    process.env.ANTHROPIC_BASE_URL = 'https://custom.proxy.io';
+    mockEnsureValidToken.mockResolvedValueOnce({ token: null, wasRefreshed: false });
+    registerSettingsAccessor((key) => (key === 'globalAnthropicApiKey' ? 'sk-settings' : undefined));
+
+    const auth = await resolveAuth({ provider: 'anthropic' });
+
+    expect(auth?.baseURL).toBe('https://custom.proxy.io');
+  });
+
+  it('returns null from settings stage when accessor returns nothing', async () => {
+    mockEnsureValidToken.mockResolvedValueOnce({ token: null, wasRefreshed: false });
+    // settings accessor returns undefined for everything, env also not set
+    const auth = await resolveAuth({ provider: 'anthropic' });
+    expect(auth).toBeNull();
+  });
+});
+
+// =============================================================================
+// Stage 3: Environment Variable
+// =============================================================================
+
+describe('resolveAuth — Stage 3: Environment Variable', () => {
+  it('returns env key for openai', async () => {
+    process.env.OPENAI_API_KEY = 'sk-env-openai-123';
+
+    const auth = await resolveAuth({ provider: 'openai' });
+
+    expect(auth?.apiKey).toBe('sk-env-openai-123');
+    expect(auth?.source).toBe('environment');
+  });
+
+  it('includes base URL from env when OPENAI_BASE_URL is set', async () => {
+    process.env.OPENAI_API_KEY = 'sk-env-openai';
+    process.env.OPENAI_BASE_URL = 'https://openai-proxy.com';
+
+    const auth = await resolveAuth({ provider: 'openai' });
+
+    expect(auth?.baseURL).toBe('https://openai-proxy.com');
+  });
+
+  it('returns null for bedrock (no env var defined)', async () => {
+    const auth = await resolveAuth({ provider: 'bedrock' });
+    expect(auth).toBeNull();
+  });
+});
+
+// =============================================================================
+// Stage 4: Default Credentials (no-auth providers)
+// =============================================================================
+
+describe('resolveAuth — Stage 4: Default Credentials', () => {
+  it('returns empty api key for ollama', async () => {
+    const auth = await resolveAuth({ provider: 'ollama' });
+
+    expect(auth).not.toBeNull();
+    expect(auth?.apiKey).toBe('');
+    expect(auth?.source).toBe('default');
+  });
+
+  it('returns null for unknown provider with no credentials', async () => {
+    const auth = await resolveAuth({ provider: 'groq' });
+    expect(auth).toBeNull();
+  });
+});
+
+// =============================================================================
+// hasCredentials
+// =============================================================================
+
+describe('hasCredentials', () => {
+  it('returns true when credentials resolve', async () => {
+    process.env.OPENAI_API_KEY = 'sk-test';
+    expect(await hasCredentials({ provider: 'openai' })).toBe(true);
+  });
+
+  it('returns true for ollama (no-auth)', async () => {
+    expect(await hasCredentials({ provider: 'ollama' })).toBe(true);
+  });
+
+  it('returns false when no credentials available', async () => {
+    expect(await hasCredentials({ provider: 'groq' })).toBe(false);
+  });
+});
+
+// =============================================================================
+// refreshOAuthTokenReactive
+// =============================================================================
+
+describe('refreshOAuthTokenReactive', () => {
+  it('returns new token from reactiveTokenRefresh', async () => {
+    mockReactiveTokenRefresh.mockResolvedValueOnce({ token: 'refreshed-token-xyz', wasRefreshed: true });
+
+    const result = await refreshOAuthTokenReactive('/some/config/dir');
+
+    expect(result).toBe('refreshed-token-xyz');
+    expect(mockReactiveTokenRefresh).toHaveBeenCalledWith('/some/config/dir');
+  });
+
+  it('returns null when reactiveTokenRefresh returns no token', async () => {
+    mockReactiveTokenRefresh.mockResolvedValueOnce({ token: null, wasRefreshed: false });
+
+    const result = await refreshOAuthTokenReactive(undefined);
+
+    expect(result).toBeNull();
+  });
+
+  it('returns null when reactiveTokenRefresh throws', async () => {
+    mockReactiveTokenRefresh.mockRejectedValueOnce(new Error('network error'));
+
+    const result = await refreshOAuthTokenReactive('/config');
+
+    expect(result).toBeNull();
+  });
+});
+
+// =============================================================================
+// Provider Account Resolution (Stage 0)
+// =============================================================================
+
+describe('resolveAuth — Stage 0: Provider Account', () => {
+  it('returns api-key auth from providerAccounts setting', async () => {
+    const accounts = [
+      {
+        provider: 'openai',
+        isActive: true,
+        authType: 'api-key',
+        apiKey: 'sk-provider-account-key',
+      },
+    ];
+    registerSettingsAccessor((key) => {
+      if (key === 'providerAccounts') return JSON.stringify(accounts);
+      return undefined;
+    });
+
+    const auth = await resolveAuth({ provider: 'openai' });
+
+    expect(auth?.apiKey).toBe('sk-provider-account-key');
+    expect(auth?.source).toBe('profile-api-key');
+  });
+
+  it('routes z.ai subscription to coding API endpoint', async () => {
+    const accounts = [
+      {
+        provider: 'zai',
+        isActive: true,
+        authType: 'api-key',
+        apiKey: 'zhipu-key',
+        billingModel: 'subscription',
+      },
+    ];
+    registerSettingsAccessor((key) => {
+      if (key === 'providerAccounts') return JSON.stringify(accounts);
+      return undefined;
+    });
+
+    const auth = await resolveAuth({ provider: 'zai' });
+
+    expect(auth?.apiKey).toBe('zhipu-key');
+    expect(auth?.baseURL).toContain('/coding/paas/v4');
+  });
+
+  it('routes z.ai pay-per-use to general API endpoint', async () => {
+    const accounts = [
+      {
+        provider: 'zai',
+        isActive: true,
+        authType: 'api-key',
+        apiKey: 'zhipu-key',
+        billingModel: 'pay-per-use',
+      },
+    ];
+    registerSettingsAccessor((key) => {
+      if (key === 'providerAccounts') return JSON.stringify(accounts);
+      return undefined;
+    });
+
+    const auth = await resolveAuth({ provider: 'zai' });
+
+    expect(auth?.baseURL).toContain('/paas/v4');
+    expect(auth?.baseURL).not.toContain('/coding/');
+  });
+
+  it('skips inactive accounts and falls through', async () => {
+    const accounts = [
+      { provider: 'openai', isActive: false, authType: 'api-key', apiKey: 'sk-inactive' },
+    ];
+    registerSettingsAccessor((key) => {
+      if (key === 'providerAccounts') return JSON.stringify(accounts);
+      return undefined;
+    });
+    process.env.OPENAI_API_KEY = 'sk-env-fallback';
+
+    const auth = await resolveAuth({ provider: 'openai' });
+
+    expect(auth?.source).toBe('environment');
+  });
+
+  it('handles malformed providerAccounts JSON gracefully', async () => {
+    registerSettingsAccessor((key) => {
+      if (key === 'providerAccounts') return 'not-valid-json{{';
+      return undefined;
+    });
+    process.env.OPENAI_API_KEY = 'sk-fallback';
+
+    const auth = await resolveAuth({ provider: 'openai' });
+    expect(auth?.source).toBe('environment');
+  });
+});
+
+// =============================================================================
+// resolveAuthFromQueue
+// =============================================================================
+
+describe('resolveAuthFromQueue', () => {
+  const baseAccount = {
+    id: 'acc-1',
+    provider: 'anthropic' as const,
+    authType: 'api-key' as const,
+    apiKey: 'sk-queue-key',
+    isActive: true,
+    name: 'Primary Account',
+    billingModel: 'pay-per-use' as const,
+    createdAt: 0,
+    updatedAt: 0,
+  };
+
+  beforeEach(() => {
+    mockScoreProviderAccount.mockReturnValue({ available: true, score: 100 });
+    mockResolveModelEquivalent.mockReturnValue({
+      modelId: 'claude-sonnet-4-5-20250929',
+      reasoning: { type: 'none' },
+    });
+  });
+
+  it('resolves auth from the first available account in queue', async () => {
+    const result = await resolveAuthFromQueue('sonnet', [baseAccount]);
+
+    expect(result).not.toBeNull();
+    expect(result?.accountId).toBe('acc-1');
+    expect(result?.apiKey).toBe('sk-queue-key');
+    expect(result?.resolvedProvider).toBe('anthropic');
+  });
+
+  it('skips excluded account IDs', async () => {
+    const result = await resolveAuthFromQueue('sonnet', [baseAccount], {
+      excludeAccountIds: ['acc-1'],
+    });
+
+    expect(result).toBeNull();
+  });
+
+  it('skips unavailable accounts', async () => {
+    mockScoreProviderAccount.mockReturnValueOnce({ available: false, score: 0 });
+
+    const result = await resolveAuthFromQueue('sonnet', [baseAccount]);
+
+    expect(result).toBeNull();
+  });
+
+  it('returns null when queue is empty', async () => {
+    const result = await resolveAuthFromQueue('sonnet', []);
+    expect(result).toBeNull();
+  });
+
+  it('uses the resolved model ID from equivalence table', async () => {
+    mockResolveModelEquivalent.mockReturnValueOnce({
+      modelId: 'claude-haiku-4-5',
+      reasoning: { type: 'none' },
+    });
+
+    const result = await resolveAuthFromQueue('haiku', [baseAccount]);
+
+    expect(result?.resolvedModelId).toBe('claude-haiku-4-5');
+  });
+
+  it('falls through to next account when first has no credentials', async () => {
+    const noKeyAccount = { ...baseAccount, id: 'acc-no-key', apiKey: undefined, authType: 'api-key' as const };
+    const goodAccount = { ...baseAccount, id: 'acc-2' };
+
+    const result = await resolveAuthFromQueue('sonnet', [noKeyAccount, goodAccount]);
+
+    expect(result?.accountId).toBe('acc-2');
+  });
+});
+
+// =============================================================================
+// buildDefaultQueueConfig
+// =============================================================================
+
+describe('buildDefaultQueueConfig', () => {
+  it('returns undefined when no settings accessor is registered', () => {
+    // accessor returns undefined for everything
+    const result = buildDefaultQueueConfig('claude-sonnet-4-5-20250929');
+    expect(result).toBeUndefined();
+  });
+
+  it('returns sorted queue when providerAccounts are configured', () => {
+    const accounts = [
+      { id: 'b', provider: 'openai', isActive: true },
+      { id: 'a', provider: 'anthropic', isActive: true },
+    ];
+    const priorityOrder = ['a', 'b'];
+
+    registerSettingsAccessor((key) => {
+      if (key === 'providerAccounts') return JSON.stringify(accounts);
+      if (key === 'globalPriorityOrder') return JSON.stringify(priorityOrder);
+      return undefined;
+    });
+
+    const result = buildDefaultQueueConfig('claude-sonnet-4-5-20250929');
+
+    expect(result).not.toBeUndefined();
+    expect(result?.queue[0].id).toBe('a');
+    expect(result?.queue[1].id).toBe('b');
+  });
+
+  it('returns undefined when providerAccounts is empty array', () => {
+    registerSettingsAccessor((key) => {
+      if (key === 'providerAccounts') return JSON.stringify([]);
+      return undefined;
+    });
+
+    const result = buildDefaultQueueConfig('sonnet');
+    expect(result).toBeUndefined();
+  });
+
+  it('returns accounts in natural order when no priority order is set', () => {
+    const accounts = [
+      { id: 'x', provider: 'groq', isActive: true },
+      { id: 'y', provider: 'mistral', isActive: true },
+    ];
+    registerSettingsAccessor((key) => {
+      if (key === 'providerAccounts') return JSON.stringify(accounts);
+      return undefined;
+    });
+
+    const result = buildDefaultQueueConfig('some-model');
+
+    expect(result?.queue[0].id).toBe('x');
+    expect(result?.queue[1].id).toBe('y');
+  });
+});
@@ -0,0 +1,125 @@
+/**
+ * Tests for AI Auth Types
+ *
+ * Validates that exported constants have the correct mappings
+ * for environment variables, settings keys, and base URL env vars.
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  PROVIDER_ENV_VARS,
+  PROVIDER_SETTINGS_KEY,
+  PROVIDER_BASE_URL_ENV,
+} from '../types';
+
+describe('PROVIDER_ENV_VARS', () => {
+  it('maps anthropic to ANTHROPIC_API_KEY', () => {
+    expect(PROVIDER_ENV_VARS.anthropic).toBe('ANTHROPIC_API_KEY');
+  });
+
+  it('maps openai to OPENAI_API_KEY', () => {
+    expect(PROVIDER_ENV_VARS.openai).toBe('OPENAI_API_KEY');
+  });
+
+  it('maps google to GOOGLE_GENERATIVE_AI_API_KEY', () => {
+    expect(PROVIDER_ENV_VARS.google).toBe('GOOGLE_GENERATIVE_AI_API_KEY');
+  });
+
+  it('maps bedrock to undefined (uses AWS credential chain)', () => {
+    expect(PROVIDER_ENV_VARS.bedrock).toBeUndefined();
+  });
+
+  it('maps azure to AZURE_OPENAI_API_KEY', () => {
+    expect(PROVIDER_ENV_VARS.azure).toBe('AZURE_OPENAI_API_KEY');
+  });
+
+  it('maps mistral to MISTRAL_API_KEY', () => {
+    expect(PROVIDER_ENV_VARS.mistral).toBe('MISTRAL_API_KEY');
+  });
+
+  it('maps groq to GROQ_API_KEY', () => {
+    expect(PROVIDER_ENV_VARS.groq).toBe('GROQ_API_KEY');
+  });
+
+  it('maps xai to XAI_API_KEY', () => {
+    expect(PROVIDER_ENV_VARS.xai).toBe('XAI_API_KEY');
+  });
+
+  it('maps openrouter to OPENROUTER_API_KEY', () => {
+    expect(PROVIDER_ENV_VARS.openrouter).toBe('OPENROUTER_API_KEY');
+  });
+
+  it('maps zai to ZHIPU_API_KEY', () => {
+    expect(PROVIDER_ENV_VARS.zai).toBe('ZHIPU_API_KEY');
+  });
+
+  it('maps ollama to undefined (no auth required)', () => {
+    expect(PROVIDER_ENV_VARS.ollama).toBeUndefined();
+  });
+});
+
+describe('PROVIDER_SETTINGS_KEY', () => {
+  it('maps anthropic to globalAnthropicApiKey', () => {
+    expect(PROVIDER_SETTINGS_KEY.anthropic).toBe('globalAnthropicApiKey');
+  });
+
+  it('maps openai to globalOpenAIApiKey', () => {
+    expect(PROVIDER_SETTINGS_KEY.openai).toBe('globalOpenAIApiKey');
+  });
+
+  it('maps google to globalGoogleApiKey', () => {
+    expect(PROVIDER_SETTINGS_KEY.google).toBe('globalGoogleApiKey');
+  });
+
+  it('maps groq to globalGroqApiKey', () => {
+    expect(PROVIDER_SETTINGS_KEY.groq).toBe('globalGroqApiKey');
+  });
+
+  it('maps mistral to globalMistralApiKey', () => {
+    expect(PROVIDER_SETTINGS_KEY.mistral).toBe('globalMistralApiKey');
+  });
+
+  it('maps xai to globalXAIApiKey', () => {
+    expect(PROVIDER_SETTINGS_KEY.xai).toBe('globalXAIApiKey');
+  });
+
+  it('maps azure to globalAzureApiKey', () => {
+    expect(PROVIDER_SETTINGS_KEY.azure).toBe('globalAzureApiKey');
+  });
+
+  it('maps openrouter to globalOpenRouterApiKey', () => {
+    expect(PROVIDER_SETTINGS_KEY.openrouter).toBe('globalOpenRouterApiKey');
+  });
+
+  it('maps zai to globalZAIApiKey', () => {
+    expect(PROVIDER_SETTINGS_KEY.zai).toBe('globalZAIApiKey');
+  });
+
+  it('does not have a key for bedrock', () => {
+    expect(PROVIDER_SETTINGS_KEY.bedrock).toBeUndefined();
+  });
+
+  it('does not have a key for ollama', () => {
+    expect(PROVIDER_SETTINGS_KEY.ollama).toBeUndefined();
+  });
+});
+
+describe('PROVIDER_BASE_URL_ENV', () => {
+  it('maps anthropic to ANTHROPIC_BASE_URL', () => {
+    expect(PROVIDER_BASE_URL_ENV.anthropic).toBe('ANTHROPIC_BASE_URL');
+  });
+
+  it('maps openai to OPENAI_BASE_URL', () => {
+    expect(PROVIDER_BASE_URL_ENV.openai).toBe('OPENAI_BASE_URL');
+  });
+
+  it('maps azure to AZURE_OPENAI_ENDPOINT', () => {
+    expect(PROVIDER_BASE_URL_ENV.azure).toBe('AZURE_OPENAI_ENDPOINT');
+  });
+
+  it('does not define base URL env for other providers', () => {
+    expect(PROVIDER_BASE_URL_ENV.google).toBeUndefined();
+    expect(PROVIDER_BASE_URL_ENV.groq).toBeUndefined();
+    expect(PROVIDER_BASE_URL_ENV.mistral).toBeUndefined();
+  });
+});
@@ -253,7 +253,7 @@ export async function startCodexOAuthFlow(): Promise<CodexAuthResult> {
 <body style="font-family: system-ui, sans-serif; display: flex; align-items: center; justify-content: center; height: 100vh; margin: 0; background: #1a1a1a; color: #e0e0e0;">
  <div style="text-align: center;">
    <h2 style="color: #4ade80;">Authentication successful!</h2>
-    <p>You can close this tab and return to Auto Claude.</p>
+    <p>You can close this tab and return to Aperant.</p>
  </div>
 </body>
 </html>`;
@@ -0,0 +1,329 @@
+/**
+ * Tests for Client Factory
+ *
+ * Validates createSimpleClient() and createAgentClient() — model resolution,
+ * credential wiring, tool registry binding, queue-based auth, and cleanup.
+ */
+
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+
+// Mock auth resolver — inline to avoid hoisting issues
+vi.mock('../../auth/resolver', () => ({
+  resolveAuth: vi.fn().mockResolvedValue({ apiKey: 'sk-default', source: 'environment' }),
+  resolveAuthFromQueue: vi.fn().mockResolvedValue(null),
+  buildDefaultQueueConfig: vi.fn().mockReturnValue(undefined),
+}));
+
+// Mock provider factory — inline
+vi.mock('../../providers/factory', () => ({
+  createProvider: vi.fn().mockReturnValue({ type: 'language-model', modelId: 'mock-model-id' }),
+  detectProviderFromModel: vi.fn().mockReturnValue('anthropic'),
+}));
+
+// Mock phase config — inline
+vi.mock('../../config/phase-config', () => ({
+  resolveModelId: vi.fn().mockReturnValue('claude-haiku-4-5'),
+}));
+
+// Mock agent configs — inline
+vi.mock('../../config/agent-configs', () => ({
+  getDefaultThinkingLevel: vi.fn().mockReturnValue('medium'),
+  getRequiredMcpServers: vi.fn().mockReturnValue([]),
+}));
+
+// Mock MCP client module — inline
+vi.mock('../../mcp/client', () => ({
+  createMcpClientsForAgent: vi.fn().mockResolvedValue([]),
+  closeAllMcpClients: vi.fn().mockResolvedValue(undefined),
+  mergeMcpTools: vi.fn().mockReturnValue({}),
+}));
+
+// Mock tool registry — inline
+vi.mock('../../tools/build-registry', () => ({
+  buildToolRegistry: vi.fn().mockReturnValue({
+    getToolsForAgent: vi.fn().mockReturnValue({ Read: {}, Write: {} }),
+  }),
+}));
+
+// Mock config/types resolveReasoningParams — inline
+vi.mock('../../config/types', () => ({
+  resolveReasoningParams: vi.fn().mockReturnValue({}),
+}));
+
+import { resolveAuth, resolveAuthFromQueue, buildDefaultQueueConfig } from '../../auth/resolver';
+import { createProvider, detectProviderFromModel } from '../../providers/factory';
+import { resolveModelId } from '../../config/phase-config';
+import { getDefaultThinkingLevel, getRequiredMcpServers } from '../../config/agent-configs';
+import { createMcpClientsForAgent, closeAllMcpClients, mergeMcpTools } from '../../mcp/client';
+import { buildToolRegistry } from '../../tools/build-registry';
+import { createSimpleClient, createAgentClient } from '../factory';
+import type { LanguageModel, Tool } from 'ai';
+import type { ToolContext } from '../../tools/types';
+import type { AgentClientConfig } from '../types';
+import type { ProviderAccount } from '../../../../shared/types/provider-account';
+import type { McpClientResult } from '../../mcp/types';
+import type { ToolRegistry } from '../../tools/registry';
+
+const mockResolveAuth = vi.mocked(resolveAuth);
+const mockResolveAuthFromQueue = vi.mocked(resolveAuthFromQueue);
+const mockBuildDefaultQueueConfig = vi.mocked(buildDefaultQueueConfig);
+const mockCreateProvider = vi.mocked(createProvider);
+const mockDetectProviderFromModel = vi.mocked(detectProviderFromModel);
+const mockResolveModelId = vi.mocked(resolveModelId);
+const mockGetDefaultThinkingLevel = vi.mocked(getDefaultThinkingLevel);
+const mockGetRequiredMcpServers = vi.mocked(getRequiredMcpServers);
+const mockCreateMcpClientsForAgent = vi.mocked(createMcpClientsForAgent);
+const mockCloseAllMcpClients = vi.mocked(closeAllMcpClients);
+const mockMergeMcpTools = vi.mocked(mergeMcpTools);
+const mockBuildToolRegistry = vi.mocked(buildToolRegistry);
+
+const FAKE_MODEL = { type: 'language-model', modelId: 'mock-model-id' };
+
+const baseToolContext = {
+  cwd: '/project',
+  projectDir: '/project',
+  specDir: '/project/.auto-claude/specs/001',
+  securityProfile: 'standard' as const,
+} as unknown as ToolContext;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+
+  // Re-establish defaults after clearAllMocks
+  mockResolveAuth.mockResolvedValue({ apiKey: 'sk-default', source: 'environment' });
+  mockResolveAuthFromQueue.mockResolvedValue(null);
+  mockBuildDefaultQueueConfig.mockReturnValue(undefined);
+  mockCreateProvider.mockReturnValue(FAKE_MODEL as unknown as LanguageModel);
+  mockDetectProviderFromModel.mockReturnValue('anthropic');
+  mockResolveModelId.mockReturnValue('claude-haiku-4-5');
+  mockGetDefaultThinkingLevel.mockReturnValue('medium');
+  mockGetRequiredMcpServers.mockReturnValue([]);
+  mockCreateMcpClientsForAgent.mockResolvedValue([]);
+  mockCloseAllMcpClients.mockResolvedValue(undefined);
+  mockMergeMcpTools.mockReturnValue({});
+
+  // ToolRegistry mock: getToolsForAgent returns a basic tools map
+  const mockRegistry = { getToolsForAgent: vi.fn().mockReturnValue({ Read: {}, Write: {} }) };
+  mockBuildToolRegistry.mockReturnValue(mockRegistry as unknown as ToolRegistry);
+});
+
+// =============================================================================
+// createSimpleClient
+// =============================================================================
+
+describe('createSimpleClient', () => {
+  it('returns model, resolvedModelId, tools, systemPrompt, maxSteps, and thinkingLevel', async () => {
+    const result = await createSimpleClient({ systemPrompt: 'You are helpful.' });
+
+    expect(result.model).toBe(FAKE_MODEL);
+    expect(result.resolvedModelId).toBeDefined();
+    expect(result.tools).toBeDefined();
+    expect(result.systemPrompt).toBe('You are helpful.');
+    expect(result.maxSteps).toBe(1);
+    expect(result.thinkingLevel).toBe('low');
+  });
+
+  it('defaults modelShorthand to haiku when not specified', async () => {
+    await createSimpleClient({ systemPrompt: 'Test' });
+    expect(mockResolveModelId).toHaveBeenCalledWith('haiku');
+  });
+
+  it('uses the specified modelShorthand', async () => {
+    await createSimpleClient({ systemPrompt: 'Test', modelShorthand: 'sonnet' });
+    expect(mockResolveModelId).toHaveBeenCalledWith('sonnet');
+  });
+
+  it('uses the specified thinkingLevel', async () => {
+    const result = await createSimpleClient({ systemPrompt: 'Test', thinkingLevel: 'high' });
+    expect(result.thinkingLevel).toBe('high');
+  });
+
+  it('uses specified maxSteps', async () => {
+    const result = await createSimpleClient({ systemPrompt: 'Test', maxSteps: 5 });
+    expect(result.maxSteps).toBe(5);
+  });
+
+  it('wires resolved auth credentials into createProvider', async () => {
+    mockResolveAuth.mockResolvedValueOnce({
+      apiKey: 'sk-resolved',
+      source: 'environment',
+      baseURL: 'https://custom.api.com',
+    });
+
+    await createSimpleClient({ systemPrompt: 'Test' });
+
+    expect(mockCreateProvider).toHaveBeenCalledWith(
+      expect.objectContaining({
+        config: expect.objectContaining({
+          apiKey: 'sk-resolved',
+          baseURL: 'https://custom.api.com',
+        }),
+      }),
+    );
+  });
+
+  it('passes tools option through to result', async () => {
+    const customTools = { myTool: {} as unknown as Tool };
+    const result = await createSimpleClient({ systemPrompt: 'Test', tools: customTools });
+    expect(result.tools).toBe(customTools);
+  });
+
+  it('uses queue-based resolution when queueConfig is provided', async () => {
+    const queueAuth = {
+      apiKey: 'sk-queue',
+      source: 'profile-api-key' as const,
+      accountId: 'acc-1',
+      resolvedProvider: 'anthropic' as const,
+      resolvedModelId: 'claude-opus-4-6',
+      reasoningConfig: { type: 'none' as const },
+    };
+    mockResolveAuthFromQueue.mockResolvedValueOnce(queueAuth);
+
+    const queueConfig = {
+      queue: [{ id: 'acc-1' } as unknown as ProviderAccount],
+      requestedModel: 'claude-opus-4-6',
+    };
+
+    const result = await createSimpleClient({ systemPrompt: 'Test', queueConfig });
+
+    expect(mockResolveAuthFromQueue).toHaveBeenCalled();
+    expect(result.queueAuth).toBe(queueAuth);
+    expect(result.resolvedModelId).toBe('claude-opus-4-6');
+  });
+
+  it('throws when queueConfig is provided but no account is available', async () => {
+    mockResolveAuthFromQueue.mockResolvedValueOnce(null);
+
+    const queueConfig = { queue: [], requestedModel: 'sonnet' };
+
+    await expect(
+      createSimpleClient({ systemPrompt: 'Test', queueConfig }),
+    ).rejects.toThrow('No available account in priority queue');
+  });
+});
+
+// =============================================================================
+// createAgentClient
+// =============================================================================
+
+describe('createAgentClient', () => {
+  const baseConfig = {
+    agentType: 'coder' as const,
+    systemPrompt: 'You are a coder.',
+    toolContext: baseToolContext,
+    phase: 'coding' as const,
+  };
+
+  it('returns model, tools, mcpClients, systemPrompt, maxSteps, thinkingLevel, and cleanup', async () => {
+    const result = await createAgentClient(baseConfig);
+
+    expect(result.model).toBe(FAKE_MODEL);
+    expect(result.tools).toBeDefined();
+    expect(result.mcpClients).toEqual([]);
+    expect(result.systemPrompt).toBe('You are a coder.');
+    expect(result.maxSteps).toBe(200);
+    expect(result.thinkingLevel).toBeDefined();
+    expect(typeof result.cleanup).toBe('function');
+  });
+
+  it('uses agent-config default thinking level', async () => {
+    mockGetDefaultThinkingLevel.mockReturnValueOnce('high');
+
+    const result = await createAgentClient(baseConfig);
+
+    expect(result.thinkingLevel).toBe('high');
+    expect(mockGetDefaultThinkingLevel).toHaveBeenCalledWith('coder');
+  });
+
+  it('overrides thinking level when thinkingLevel is specified', async () => {
+    const result = await createAgentClient({ ...baseConfig, thinkingLevel: 'low' });
+    expect(result.thinkingLevel).toBe('low');
+  });
+
+  it('uses specified maxSteps', async () => {
+    const result = await createAgentClient({ ...baseConfig, maxSteps: 50 });
+    expect(result.maxSteps).toBe(50);
+  });
+
+  it('calls getToolsForAgent with agentType and toolContext', async () => {
+    const mockRegistry = { getToolsForAgent: vi.fn().mockReturnValue({ Read: {}, Write: {} }) };
+    mockBuildToolRegistry.mockReturnValueOnce(mockRegistry as unknown as ToolRegistry);
+
+    await createAgentClient(baseConfig);
+
+    expect(mockRegistry.getToolsForAgent).toHaveBeenCalledWith('coder', baseToolContext);
+  });
+
+  it('creates MCP clients when agent requires servers', async () => {
+    const mockMcpClient = { serverId: 'context7', tools: { ctx7_tool: {} }, close: vi.fn() };
+    mockGetRequiredMcpServers.mockReturnValueOnce(['context7']);
+    mockCreateMcpClientsForAgent.mockResolvedValueOnce([mockMcpClient] as unknown as McpClientResult[]);
+    mockMergeMcpTools.mockReturnValueOnce({ ctx7_tool: {} });
+
+    const result = await createAgentClient(baseConfig);
+
+    expect(mockCreateMcpClientsForAgent).toHaveBeenCalledWith('coder', expect.any(Object));
+    expect(result.mcpClients).toHaveLength(1);
+    expect(result.tools).toHaveProperty('ctx7_tool');
+  });
+
+  it('cleanup calls closeAllMcpClients with the client list', async () => {
+    const result = await createAgentClient(baseConfig);
+    await result.cleanup();
+    expect(mockCloseAllMcpClients).toHaveBeenCalledWith(result.mcpClients);
+  });
+
+  it('uses queue-based auth when queueConfig is provided', async () => {
+    const queueAuth = {
+      apiKey: 'sk-queue-coder',
+      source: 'profile-api-key' as const,
+      accountId: 'acc-coder',
+      resolvedProvider: 'anthropic' as const,
+      resolvedModelId: 'claude-sonnet-4-5-20250929',
+      reasoningConfig: { type: 'none' as const },
+    };
+    mockResolveAuthFromQueue.mockResolvedValueOnce(queueAuth);
+
+    const result = await createAgentClient({
+      ...baseConfig,
+      queueConfig: {
+        queue: [{ id: 'acc-coder' } as unknown as ProviderAccount],
+        requestedModel: 'claude-sonnet-4-5-20250929',
+      },
+    });
+
+    expect(result.queueAuth).toBe(queueAuth);
+    expect(mockCreateProvider).toHaveBeenCalledWith(
+      expect.objectContaining({
+        config: expect.objectContaining({
+          provider: 'anthropic',
+          apiKey: 'sk-queue-coder',
+        }),
+        modelId: 'claude-sonnet-4-5-20250929',
+      }),
+    );
+  });
+
+  it('throws when queueConfig provided but no account available', async () => {
+    mockResolveAuthFromQueue.mockResolvedValueOnce(null);
+
+    await expect(
+      createAgentClient({
+        ...baseConfig,
+        queueConfig: { queue: [], requestedModel: 'sonnet' },
+      }),
+    ).rejects.toThrow('No available account in priority queue');
+  });
+
+  it('merges additionalMcpServers into the required servers list', async () => {
+    mockGetRequiredMcpServers.mockReturnValueOnce(['context7']);
+
+    await createAgentClient({
+      ...baseConfig,
+      additionalMcpServers: ['custom-server'],
+    });
+
+    // createMcpClientsForAgent is called because the combined server list is non-empty
+    expect(mockCreateMcpClientsForAgent).toHaveBeenCalled();
+  });
+});
@@ -28,8 +28,6 @@ import type { McpClientResult } from '../mcp/types';
 import { createProvider, detectProviderFromModel } from '../providers/factory';
 import { buildToolRegistry } from '../tools/build-registry';
 import type { QueueResolvedAuth } from '../auth/types';
-import { wrapWithAutoSwap } from '../providers/auto-swap-middleware';
-import { notifyRendererOfSwap } from './swap-notifier';
 import type {
  AgentClientConfig,
  AgentClientResult,
@@ -182,14 +180,8 @@ export async function createAgentClient(
    await closeAllMcpClients(mcpClients);
  };

-  // Wrap model with auto-swap middleware for transparent rate-limit failover
-  console.log('[AutoSwap] createAgentClient for', agentType, '| account:', queueAuth?.accountId ?? 'legacy', '| queue:', queueConfig ? queueConfig.queue.length + ' accounts' : 'none');
-  const wrappedModel = queueConfig
-    ? wrapWithAutoSwap(model, queueAuth, queueConfig.queue, queueConfig.requestedModel, notifyRendererOfSwap)
-    : model;
-
  return {
-    model: wrappedModel,
+    model,
    tools,
    mcpClients,
    systemPrompt,
@@ -293,14 +285,8 @@ export async function createSimpleClient(
    });
  }

-  // Wrap model with auto-swap middleware for transparent rate-limit failover
-  console.log('[AutoSwap] createSimpleClient | account:', queueAuth?.accountId ?? 'legacy', '| model:', resolvedModelId, '| queue:', queueConfig ? queueConfig.queue.length + ' accounts' : 'none');
-  const wrappedModel = queueConfig
-    ? wrapWithAutoSwap(model, queueAuth, queueConfig.queue, queueConfig.requestedModel, notifyRendererOfSwap)
-    : model;
-
  return {
-    model: wrappedModel,
+    model,
    resolvedModelId,
    tools,
    systemPrompt,
@@ -1,33 +0,0 @@
-/**
- * Swap Notifier
- * =============
- *
- * Sends a UI notification when the auto-swap middleware switches accounts.
- * Bridges the AI middleware layer (no IPC access) to the renderer via
- * Electron's BrowserWindow.
- */
-
-import { BrowserWindow } from 'electron';
-import { IPC_CHANNELS } from '../../../shared/constants/ipc';
-import type { AutoSwapEvent } from '../providers/auto-swap-middleware';
-
-/**
- * Notify the renderer that the middleware swapped to a different account.
- * Uses the existing PROACTIVE_SWAP_NOTIFICATION channel so the
- * ProactiveSwapListener component shows the swap toast.
- */
-export function notifyRendererOfSwap(event: AutoSwapEvent): void {
-  console.log('[AutoSwap] Sending UI notification:', event.fromAccountName, '→', event.toAccountName);
-  const mainWindow = BrowserWindow.getAllWindows()[0];
-  if (!mainWindow) {
-    console.log('[AutoSwap] No BrowserWindow found — UI notification skipped');
-    return;
-  }
-
-  mainWindow.webContents.send(IPC_CHANNELS.PROACTIVE_SWAP_NOTIFICATION, {
-    fromProfile: { id: event.fromAccountId, name: event.fromAccountName },
-    toProfile: { id: event.toAccountId, name: event.toAccountName },
-    reason: 'reactive-middleware',
-  });
-  console.log('[AutoSwap] UI notification sent via PROACTIVE_SWAP_NOTIFICATION channel');
-}
@@ -89,6 +89,10 @@ describe('resolveModelId', () => {

  beforeEach(() => {
    process.env = { ...originalEnv };
+    // Clear model override env vars to ensure consistent test results
+    delete process.env.ANTHROPIC_DEFAULT_OPUS_MODEL;
+    delete process.env.ANTHROPIC_DEFAULT_SONNET_MODEL;
+    delete process.env.ANTHROPIC_DEFAULT_HAIKU_MODEL;
  });

  afterEach(() => {
@@ -0,0 +1,316 @@
+/**
+ * Tests for MCP Client
+ *
+ * Validates transport creation, client initialization, parallel agent setup,
+ * tool merging, and cleanup behavior.
+ */
+
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+
+// Mock @ai-sdk/mcp using inline factory to avoid vi.mock hoisting issues
+vi.mock('@ai-sdk/mcp', () => ({
+  createMCPClient: vi.fn(),
+}));
+
+// Mock StdioClientTransport constructor using a proper constructor function
+vi.mock('@modelcontextprotocol/sdk/client/stdio.js', () => ({
+  // biome-ignore lint/suspicious/noExplicitAny: test mock constructor
+  StdioClientTransport: vi.fn().mockImplementation(function (this: any) {
+    Object.assign(this, { __kind: 'stdio-transport' });
+  }),
+}));
+
+// Mock registry to control which servers get resolved
+vi.mock('../registry', () => ({
+  resolveMcpServers: vi.fn(),
+}));
+
+// Mock agent-configs to control required servers
+vi.mock('../../config/agent-configs', () => ({
+  getRequiredMcpServers: vi.fn().mockReturnValue([]),
+}));
+
+import { createMCPClient } from '@ai-sdk/mcp';
+import type { MCPClient } from '@ai-sdk/mcp';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { resolveMcpServers } from '../registry';
+import { getRequiredMcpServers } from '../../config/agent-configs';
+import type { McpServerResolveOptions } from '../../config/agent-configs';
+import {
+  createMcpClient,
+  createMcpClientsForAgent,
+  closeAllMcpClients,
+  mergeMcpTools,
+} from '../client';
+import type { McpServerConfig } from '../types';
+
+const mockCreateMCPClient = vi.mocked(createMCPClient);
+const mockStdioClientTransport = vi.mocked(StdioClientTransport);
+const mockResolveMcpServers = vi.mocked(resolveMcpServers);
+const mockGetRequiredMcpServers = vi.mocked(getRequiredMcpServers);
+
+// Sentinel: what StdioClientTransport instances look like after construction
+const FAKE_STDIO_TRANSPORT_PROPS = { __kind: 'stdio-transport' };
+
+// Helper: build a mock MCP client instance
+function makeMockMcpInstance(tools = { tool_a: {}, tool_b: {} }) {
+  return {
+    tools: vi.fn().mockResolvedValue(tools),
+    close: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+// Helpers: server configs
+const stdioConfig: McpServerConfig = {
+  id: 'test-stdio',
+  name: 'Test Stdio Server',
+  description: 'A test stdio server',
+  enabledByDefault: true,
+  transport: {
+    type: 'stdio',
+    command: 'npx',
+    args: ['-y', 'some-mcp-server'],
+    env: { MY_VAR: 'value' },
+  },
+};
+
+const httpConfig: McpServerConfig = {
+  id: 'test-http',
+  name: 'Test HTTP Server',
+  description: 'A test streamable-http server',
+  enabledByDefault: true,
+  transport: {
+    type: 'streamable-http',
+    url: 'https://mcp.example.com/sse',
+    headers: { Authorization: 'Bearer token123' },
+  },
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  // Default: StdioClientTransport constructor sets __kind on instance
+  // biome-ignore lint/suspicious/noExplicitAny: test mock constructor
+  mockStdioClientTransport.mockImplementation(function (this: any) {
+    Object.assign(this, FAKE_STDIO_TRANSPORT_PROPS);
+  } as unknown as typeof StdioClientTransport);
+  // Default: createMCPClient returns a standard mock instance
+  mockCreateMCPClient.mockResolvedValue(makeMockMcpInstance() as unknown as MCPClient);
+  mockGetRequiredMcpServers.mockReturnValue([]);
+  mockResolveMcpServers.mockReturnValue([]);
+});
+
+// =============================================================================
+// createMcpClient — transport creation
+// =============================================================================
+
+describe('createMcpClient', () => {
+  it('creates a StdioClientTransport for stdio server config', async () => {
+    await createMcpClient(stdioConfig);
+
+    expect(mockStdioClientTransport).toHaveBeenCalledWith({
+      command: 'npx',
+      args: ['-y', 'some-mcp-server'],
+      env: expect.objectContaining({ MY_VAR: 'value' }),
+      cwd: undefined,
+    });
+    // The transport passed to createMCPClient is an instance of the mocked StdioClientTransport
+    expect(mockCreateMCPClient).toHaveBeenCalledWith({
+      transport: expect.objectContaining(FAKE_STDIO_TRANSPORT_PROPS),
+    });
+  });
+
+  it('creates an SSE transport object for streamable-http config', async () => {
+    await createMcpClient(httpConfig);
+
+    expect(mockCreateMCPClient).toHaveBeenCalledWith({
+      transport: {
+        type: 'sse',
+        url: 'https://mcp.example.com/sse',
+        headers: { Authorization: 'Bearer token123' },
+      },
+    });
+    // StdioClientTransport should NOT be called for HTTP config
+    expect(mockStdioClientTransport).not.toHaveBeenCalled();
+  });
+
+  it('returns a result with serverId, tools, and close function', async () => {
+    const result = await createMcpClient(stdioConfig);
+
+    expect(result.serverId).toBe('test-stdio');
+    expect(result.tools).toEqual({ tool_a: {}, tool_b: {} });
+    expect(typeof result.close).toBe('function');
+  });
+
+  it('merges process.env with server env for stdio transport', async () => {
+    const originalPath = process.env.PATH;
+    process.env.PATH = '/usr/bin';
+
+    await createMcpClient(stdioConfig);
+
+    expect(mockStdioClientTransport).toHaveBeenCalledWith(
+      expect.objectContaining({
+        env: expect.objectContaining({ PATH: '/usr/bin', MY_VAR: 'value' }),
+      }),
+    );
+
+    process.env.PATH = originalPath;
+  });
+
+  it('passes undefined env to StdioClientTransport when no env in config', async () => {
+    const noEnvConfig: McpServerConfig = {
+      ...stdioConfig,
+      transport: { type: 'stdio', command: 'node', args: ['server.js'] },
+    };
+
+    await createMcpClient(noEnvConfig);
+
+    expect(mockStdioClientTransport).toHaveBeenCalledWith(
+      expect.objectContaining({ env: undefined }),
+    );
+  });
+
+  it('close() delegates to the underlying MCP client close method', async () => {
+    const mockInstance = makeMockMcpInstance();
+    mockCreateMCPClient.mockResolvedValueOnce(mockInstance as unknown as MCPClient);
+
+    const result = await createMcpClient(stdioConfig);
+    await result.close();
+
+    expect(mockInstance.close).toHaveBeenCalled();
+  });
+});
+
+// =============================================================================
+// createMcpClientsForAgent
+// =============================================================================
+
+describe('createMcpClientsForAgent', () => {
+  it('returns empty array when agent requires no MCP servers', async () => {
+    mockGetRequiredMcpServers.mockReturnValueOnce([]);
+    mockResolveMcpServers.mockReturnValueOnce([]);
+
+    const clients = await createMcpClientsForAgent('commit_message');
+
+    expect(clients).toEqual([]);
+  });
+
+  it('creates clients for each resolved server config', async () => {
+    mockGetRequiredMcpServers.mockReturnValueOnce(['context7', 'auto-claude']);
+    mockResolveMcpServers.mockReturnValueOnce([
+      { ...stdioConfig, id: 'context7' },
+      { ...stdioConfig, id: 'auto-claude' },
+    ]);
+    // Two separate mock instances for the two servers
+    mockCreateMCPClient
+      .mockResolvedValueOnce(makeMockMcpInstance() as unknown as MCPClient)
+      .mockResolvedValueOnce(makeMockMcpInstance() as unknown as MCPClient);
+
+    const clients = await createMcpClientsForAgent('coder');
+
+    expect(clients).toHaveLength(2);
+    expect(clients[0].serverId).toBe('context7');
+    expect(clients[1].serverId).toBe('auto-claude');
+  });
+
+  it('skips failed connections without throwing', async () => {
+    mockGetRequiredMcpServers.mockReturnValueOnce(['context7', 'broken-server']);
+    mockResolveMcpServers.mockReturnValueOnce([
+      { ...stdioConfig, id: 'context7' },
+      { ...stdioConfig, id: 'broken-server' },
+    ]);
+
+    // First call succeeds, second call fails
+    mockCreateMCPClient
+      .mockResolvedValueOnce(makeMockMcpInstance() as unknown as MCPClient)
+      .mockRejectedValueOnce(new Error('connection refused'));
+
+    const clients = await createMcpClientsForAgent('coder');
+
+    // Only the successful client should be returned
+    expect(clients).toHaveLength(1);
+    expect(clients[0].serverId).toBe('context7');
+  });
+
+  it('passes resolveOptions to getRequiredMcpServers', async () => {
+    mockGetRequiredMcpServers.mockReturnValueOnce([]);
+    mockResolveMcpServers.mockReturnValueOnce([]);
+
+    const resolveOptions = { electronMcpEnabled: true };
+    await createMcpClientsForAgent('qa_reviewer', resolveOptions as unknown as McpServerResolveOptions);
+
+    expect(mockGetRequiredMcpServers).toHaveBeenCalledWith('qa_reviewer', resolveOptions);
+  });
+});
+
+// =============================================================================
+// mergeMcpTools
+// =============================================================================
+
+describe('mergeMcpTools', () => {
+  it('merges tools from multiple clients into a single object', () => {
+    const clients = [
+      { serverId: 'a', tools: { tool1: {}, tool2: {} }, close: vi.fn() },
+      { serverId: 'b', tools: { tool3: {}, tool4: {} }, close: vi.fn() },
+    ];
+
+    const merged = mergeMcpTools(clients);
+
+    expect(Object.keys(merged)).toHaveLength(4);
+    expect(merged).toHaveProperty('tool1');
+    expect(merged).toHaveProperty('tool3');
+  });
+
+  it('returns empty object for empty clients array', () => {
+    expect(mergeMcpTools([])).toEqual({});
+  });
+
+  it('later client tools overwrite earlier ones on key collision', () => {
+    const clients = [
+      { serverId: 'a', tools: { shared_tool: { version: 1 } }, close: vi.fn() },
+      { serverId: 'b', tools: { shared_tool: { version: 2 } }, close: vi.fn() },
+    ];
+
+    const merged = mergeMcpTools(clients);
+
+    // biome-ignore lint/suspicious/noExplicitAny: test mock property access
+    expect((merged.shared_tool as any).version).toBe(2);
+  });
+});
+
+// =============================================================================
+// closeAllMcpClients
+// =============================================================================
+
+describe('closeAllMcpClients', () => {
+  it('calls close on all clients', async () => {
+    const close1 = vi.fn().mockResolvedValue(undefined);
+    const close2 = vi.fn().mockResolvedValue(undefined);
+    const clients = [
+      { serverId: 'a', tools: {}, close: close1 },
+      { serverId: 'b', tools: {}, close: close2 },
+    ];
+
+    await closeAllMcpClients(clients);
+
+    expect(close1).toHaveBeenCalled();
+    expect(close2).toHaveBeenCalled();
+  });
+
+  it('resolves even when one client fails to close', async () => {
+    const close1 = vi.fn().mockResolvedValue(undefined);
+    const close2 = vi.fn().mockRejectedValue(new Error('close failed'));
+    const clients = [
+      { serverId: 'a', tools: {}, close: close1 },
+      { serverId: 'b', tools: {}, close: close2 },
+    ];
+
+    // Should not throw
+    await expect(closeAllMcpClients(clients)).resolves.toBeUndefined();
+    expect(close1).toHaveBeenCalled();
+    expect(close2).toHaveBeenCalled();
+  });
+
+  it('resolves immediately for empty clients array', async () => {
+    await expect(closeAllMcpClients([])).resolves.toBeUndefined();
+  });
+});
@@ -0,0 +1,185 @@
+/**
+ * Tests for MCP Server Registry
+ *
+ * Validates server configuration resolution, required server lookup,
+ * and option-based server filtering.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { getMcpServerConfig, resolveMcpServers } from '../registry';
+
+// =============================================================================
+// getMcpServerConfig
+// =============================================================================
+
+describe('getMcpServerConfig', () => {
+  describe('context7', () => {
+    it('returns the context7 server config', () => {
+      const config = getMcpServerConfig('context7');
+      expect(config).not.toBeNull();
+      expect(config?.id).toBe('context7');
+      expect(config?.enabledByDefault).toBe(true);
+    });
+
+    it('uses stdio transport with npx', () => {
+      const config = getMcpServerConfig('context7');
+      expect(config?.transport.type).toBe('stdio');
+      if (config?.transport.type === 'stdio') {
+        expect(config.transport.command).toBe('npx');
+      }
+    });
+  });
+
+  describe('linear', () => {
+    it('returns null when no API key provided', () => {
+      const config = getMcpServerConfig('linear', {});
+      expect(config).toBeNull();
+    });
+
+    it('returns config when linearApiKey is provided', () => {
+      const config = getMcpServerConfig('linear', { linearApiKey: 'lin_api_123' });
+      expect(config).not.toBeNull();
+      expect(config?.id).toBe('linear');
+    });
+
+    it('returns config when LINEAR_API_KEY is in env option', () => {
+      const config = getMcpServerConfig('linear', { env: { LINEAR_API_KEY: 'lin_env_456' } });
+      expect(config).not.toBeNull();
+    });
+
+    it('injects LINEAR_API_KEY into the transport env', () => {
+      const config = getMcpServerConfig('linear', { linearApiKey: 'lin_inject' });
+      expect(config?.transport.type).toBe('stdio');
+      if (config?.transport.type === 'stdio') {
+        expect(config.transport.env?.LINEAR_API_KEY).toBe('lin_inject');
+      }
+    });
+  });
+
+  describe('memory', () => {
+    it('returns null when no memory URL provided', () => {
+      const config = getMcpServerConfig('memory', {});
+      expect(config).toBeNull();
+    });
+
+    it('returns config with streamable-http transport when URL is provided', () => {
+      const config = getMcpServerConfig('memory', { memoryMcpUrl: 'http://localhost:8080/mcp' });
+      expect(config).not.toBeNull();
+      expect(config?.transport.type).toBe('streamable-http');
+      if (config?.transport.type === 'streamable-http') {
+        expect(config.transport.url).toBe('http://localhost:8080/mcp');
+      }
+    });
+
+    it('reads URL from env.GRAPHITI_MCP_URL option', () => {
+      const config = getMcpServerConfig('memory', { env: { GRAPHITI_MCP_URL: 'http://graphiti.local' } });
+      expect(config?.transport.type).toBe('streamable-http');
+    });
+  });
+
+  describe('electron', () => {
+    it('returns the electron server config', () => {
+      const config = getMcpServerConfig('electron');
+      expect(config).not.toBeNull();
+      expect(config?.id).toBe('electron');
+      expect(config?.enabledByDefault).toBe(false);
+    });
+
+    it('uses stdio transport', () => {
+      const config = getMcpServerConfig('electron');
+      expect(config?.transport.type).toBe('stdio');
+    });
+  });
+
+  describe('puppeteer', () => {
+    it('returns the puppeteer server config', () => {
+      const config = getMcpServerConfig('puppeteer');
+      expect(config).not.toBeNull();
+      expect(config?.id).toBe('puppeteer');
+    });
+
+    it('uses stdio transport', () => {
+      const config = getMcpServerConfig('puppeteer');
+      expect(config?.transport.type).toBe('stdio');
+    });
+  });
+
+  describe('auto-claude', () => {
+    it('returns auto-claude config with empty specDir as default', () => {
+      const config = getMcpServerConfig('auto-claude', {});
+      expect(config).not.toBeNull();
+      expect(config?.id).toBe('auto-claude');
+    });
+
+    it('injects SPEC_DIR into transport env', () => {
+      const config = getMcpServerConfig('auto-claude', { specDir: '/project/.auto-claude/specs/001-feature' });
+      expect(config?.transport.type).toBe('stdio');
+      if (config?.transport.type === 'stdio') {
+        expect(config.transport.env?.SPEC_DIR).toBe('/project/.auto-claude/specs/001-feature');
+      }
+    });
+
+    it('uses node command', () => {
+      const config = getMcpServerConfig('auto-claude', {});
+      if (config?.transport.type === 'stdio') {
+        expect(config.transport.command).toBe('node');
+      }
+    });
+  });
+
+  describe('unknown server', () => {
+    it('returns null for unrecognized server ID', () => {
+      const config = getMcpServerConfig('nonexistent-server');
+      expect(config).toBeNull();
+    });
+  });
+});
+
+// =============================================================================
+// resolveMcpServers
+// =============================================================================
+
+describe('resolveMcpServers', () => {
+  it('returns configs for all recognized server IDs', () => {
+    const configs = resolveMcpServers(['context7', 'electron', 'puppeteer']);
+    expect(configs).toHaveLength(3);
+    expect(configs.map((c) => c.id)).toEqual(['context7', 'electron', 'puppeteer']);
+  });
+
+  it('filters out servers that cannot be configured (e.g. linear without API key)', () => {
+    const configs = resolveMcpServers(['context7', 'linear'], {});
+    expect(configs).toHaveLength(1);
+    expect(configs[0].id).toBe('context7');
+  });
+
+  it('includes linear when API key option is provided', () => {
+    const configs = resolveMcpServers(['context7', 'linear'], { linearApiKey: 'lin_test' });
+    expect(configs).toHaveLength(2);
+  });
+
+  it('returns empty array for empty input', () => {
+    const configs = resolveMcpServers([]);
+    expect(configs).toEqual([]);
+  });
+
+  it('skips unrecognized server IDs silently', () => {
+    const configs = resolveMcpServers(['context7', 'bogus-server-id']);
+    expect(configs).toHaveLength(1);
+    expect(configs[0].id).toBe('context7');
+  });
+
+  it('includes memory server when memoryMcpUrl is provided', () => {
+    const configs = resolveMcpServers(['memory'], { memoryMcpUrl: 'http://memory.local' });
+    expect(configs).toHaveLength(1);
+    expect(configs[0].id).toBe('memory');
+  });
+
+  it('passes specDir through to auto-claude config', () => {
+    const specDir = '/my-project/.auto-claude/specs/042-auth';
+    const configs = resolveMcpServers(['auto-claude'], { specDir });
+    expect(configs).toHaveLength(1);
+    if (configs[0].transport.type === 'stdio') {
+      expect(configs[0].transport.env?.SPEC_DIR).toBe(specDir);
+    }
+  });
+});
@@ -99,6 +99,25 @@ const PUPPETEER_SERVER: McpServerConfig = {
  },
 };

+/**
+ * Auto-Claude MCP server - custom build management tools.
+ * Used by planner, coder, and QA agents for build progress tracking.
+ */
+function createAutoClaudeServer(specDir: string): McpServerConfig {
+  return {
+    id: 'auto-claude',
+    name: 'Aperant',
+    description: 'Build management tools (progress tracking, session context)',
+    enabledByDefault: true,
+    transport: {
+      type: 'stdio',
+      command: 'node',
+      args: ['auto-claude-mcp-server.js'],
+      env: { SPEC_DIR: specDir },
+    },
+  };
+}
+
 // =============================================================================
 // Registry
 // =============================================================================
@@ -157,11 +176,8 @@ export function getMcpServerConfig(
      return PUPPETEER_SERVER;

    case 'auto-claude': {
-      // Tools are implemented as builtin TypeScript tools in tools/auto-claude/ and
-      // injected directly into agent sessions. The external Node.js subprocess is
-      // obsolete since the migration from Python to the Vercel AI SDK.
-      // resolveMcpServers() filters out null results automatically.
-      return null;
+      const specDir = options.specDir ?? '';
+      return createAutoClaudeServer(specDir);
    }

    default:
@@ -7,11 +7,51 @@
 * 3. Web app (Next.js SaaS) — pure cloud libSQL
 */

-import { createClient } from '@libsql/client';
-import type { Client } from '@libsql/client';
+import type { Client, Config } from '@libsql/client/sqlite3';
+import { createRequire } from 'module';
 import { join } from 'path';
 import { MEMORY_SCHEMA_SQL, MEMORY_PRAGMA_SQL } from './schema';

+/**
+ * Lazy-load @libsql/client via CJS require().
+ *
+ * @libsql/client depends on native platform-specific modules (@libsql/darwin-arm64,
+ * @libsql/linux-x64-gnu, etc.). In packaged Electron apps these live in
+ * Resources/node_modules/ (via extraResources). ESM import() can't resolve them
+ * from within app.asar, but CJS require() works because Module.globalPaths is
+ * patched at startup in index.ts to include Resources/node_modules/.
+ *
+ * Using a lazy getter avoids a static import that would crash at startup before
+ * the globalPaths patch runs.
+ */
+let _createClient: ((config: Config) => Client) | null = null;
+
+function loadCreateClient(): (config: Config) => Client {
+  if (!_createClient) {
+    // In Electron: globalThis.require is set up in index.ts with Module.globalPaths
+    // patched to include Resources/node_modules/ for extraResources packages.
+    // In tests/dev: fall back to createRequire (deps are in normal node_modules).
+    const req = globalThis.require ?? createRequire(import.meta.url);
+    let mod: Record<string, unknown>;
+    try {
+      mod = req('@libsql/client/sqlite3');
+    } catch (err) {
+      throw new Error(
+        `Failed to load @libsql/client/sqlite3: ${(err as Error).message}. ` +
+        `Ensure native modules are available in Resources/node_modules/`
+      );
+    }
+    if (typeof mod.createClient !== 'function') {
+      throw new Error(
+        `@libsql/client/sqlite3 did not export createClient (got ${typeof mod.createClient}). ` +
+        `Check that native modules are available in Resources/node_modules/`
+      );
+    }
+    _createClient = mod.createClient as (config: Config) => Client;
+  }
+  return _createClient!;
+}
+
 let _client: Client | null = null;

 /**
@@ -31,7 +71,7 @@ export async function getMemoryClient(
  const { app } = await import('electron');
  const localPath = join(app.getPath('userData'), 'memory.db');

-  _client = createClient({
+  _client = loadCreateClient()({
    url: `file:${localPath}`,
    ...(tursoSyncUrl && authToken
      ? { syncUrl: tursoSyncUrl, authToken, syncInterval: 60 }
@@ -78,7 +118,7 @@ export async function getWebMemoryClient(
  tursoUrl: string,
  authToken: string,
 ): Promise<Client> {
-  const client = createClient({ url: tursoUrl, authToken });
+  const client = loadCreateClient()({ url: tursoUrl, authToken });

  // Apply PRAGMAs
  for (const pragma of MEMORY_PRAGMA_SQL.split('\n').filter(l => l.trim())) {
@@ -97,7 +137,7 @@ export async function getWebMemoryClient(
 * Create an in-memory client (for tests — no Electron dependency).
 */
 export async function getInMemoryClient(): Promise<Client> {
-  const client = createClient({ url: ':memory:' });
+  const client = loadCreateClient()({ url: ':memory:' });
  await client.executeMultiple(MEMORY_SCHEMA_SQL);
  return client;
 }
@@ -251,7 +251,7 @@ export interface MemoryMethodologyPlugin {

 export const nativePlugin: MemoryMethodologyPlugin = {
  id: 'native',
-  displayName: 'Auto Claude (Subtasks)',
+  displayName: 'Aperant (Subtasks)',
  mapPhase: (p: string): UniversalPhase => {
    const map: Record<string, UniversalPhase> = {
      planning: 'define',
@@ -0,0 +1,334 @@
+import { describe, it, expect, vi } from 'vitest';
+
+import { executeParallel } from '../parallel-executor';
+import type { ParallelExecutorConfig, SubtaskSessionRunner } from '../parallel-executor';
+import type { SubtaskInfo } from '../build-orchestrator';
+import type { SessionResult } from '../../session/types';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeSubtask(id: string): SubtaskInfo {
+  return {
+    id,
+    description: `Subtask ${id}`,
+    status: 'pending',
+  };
+}
+
+function makeResult(outcome: SessionResult['outcome']): SessionResult {
+  return {
+    outcome,
+    error: outcome === 'error' ? new Error('session error') : undefined,
+    totalSteps: 1,
+    lastMessage: '',
+  } as unknown as SessionResult;
+}
+
+// ---------------------------------------------------------------------------
+// Helper: run executeParallel with fake timers advanced automatically
+// ---------------------------------------------------------------------------
+
+async function runWithFakeTimers<T>(fn: () => Promise<T>): Promise<T> {
+  vi.useFakeTimers();
+  try {
+    const promise = fn();
+    await vi.runAllTimersAsync();
+    return await promise;
+  } finally {
+    vi.useRealTimers();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('executeParallel', () => {
+  // -------------------------------------------------------------------------
+  // Empty task list
+  // -------------------------------------------------------------------------
+
+  it('returns empty results for an empty subtask list', async () => {
+    const runner = vi.fn() as unknown as SubtaskSessionRunner;
+    const result = await executeParallel([], runner);
+
+    expect(result.results).toHaveLength(0);
+    expect(result.successCount).toBe(0);
+    expect(result.failureCount).toBe(0);
+    expect(result.rateLimitedCount).toBe(0);
+    expect(result.cancelled).toBe(false);
+    expect(runner).not.toHaveBeenCalled();
+  });
+
+  // -------------------------------------------------------------------------
+  // All succeed
+  // -------------------------------------------------------------------------
+
+  it('returns successCount equal to number of subtasks when all succeed', async () => {
+    const subtasks = [makeSubtask('t1'), makeSubtask('t2'), makeSubtask('t3')];
+    const runner = vi.fn().mockResolvedValue(makeResult('completed')) as SubtaskSessionRunner;
+
+    const result = await runWithFakeTimers(() =>
+      executeParallel(subtasks, runner, { maxConcurrency: 10 }),
+    );
+
+    expect(result.successCount).toBe(3);
+    expect(result.failureCount).toBe(0);
+    expect(result.rateLimitedCount).toBe(0);
+    expect(result.cancelled).toBe(false);
+    expect(result.results).toHaveLength(3);
+    for (const r of result.results) {
+      expect(r.success).toBe(true);
+      expect(r.rateLimited).toBe(false);
+    }
+  });
+
+  it('maps subtaskIds correctly in results', async () => {
+    const subtasks = [makeSubtask('alpha'), makeSubtask('beta')];
+    const runner = vi.fn().mockResolvedValue(makeResult('completed')) as SubtaskSessionRunner;
+
+    const result = await runWithFakeTimers(() =>
+      executeParallel(subtasks, runner, { maxConcurrency: 10 }),
+    );
+    const ids = result.results.map((r) => r.subtaskId);
+
+    expect(ids).toContain('alpha');
+    expect(ids).toContain('beta');
+  });
+
+  // -------------------------------------------------------------------------
+  // Partial failure
+  // -------------------------------------------------------------------------
+
+  it('handles partial failure — some succeed, some fail', async () => {
+    const subtasks = [makeSubtask('s1'), makeSubtask('s2'), makeSubtask('s3')];
+
+    const runner = vi.fn()
+      .mockResolvedValueOnce(makeResult('completed'))
+      .mockResolvedValueOnce(makeResult('error'))
+      .mockResolvedValueOnce(makeResult('completed')) as SubtaskSessionRunner;
+
+    const result = await runWithFakeTimers(() =>
+      executeParallel(subtasks, runner, { maxConcurrency: 10 }),
+    );
+
+    expect(result.successCount).toBe(2);
+    expect(result.failureCount).toBe(1);
+    expect(result.rateLimitedCount).toBe(0);
+  });
+
+  // -------------------------------------------------------------------------
+  // All fail
+  // -------------------------------------------------------------------------
+
+  it('handles all-fail scenario gracefully', async () => {
+    const subtasks = [makeSubtask('f1'), makeSubtask('f2')];
+    const runner = vi.fn().mockResolvedValue(makeResult('error')) as SubtaskSessionRunner;
+
+    const result = await runWithFakeTimers(() =>
+      executeParallel(subtasks, runner, { maxConcurrency: 10 }),
+    );
+
+    expect(result.successCount).toBe(0);
+    expect(result.failureCount).toBe(2);
+    expect(result.cancelled).toBe(false);
+  });
+
+  // -------------------------------------------------------------------------
+  // Rate limiting
+  // -------------------------------------------------------------------------
+
+  it('tracks rate-limited subtasks separately', async () => {
+    const subtasks = [makeSubtask('r1'), makeSubtask('r2')];
+
+    const runner = vi.fn()
+      .mockResolvedValueOnce(makeResult('rate_limited'))
+      .mockResolvedValueOnce(makeResult('completed')) as SubtaskSessionRunner;
+
+    const result = await runWithFakeTimers(() =>
+      executeParallel(subtasks, runner, { maxConcurrency: 10 }),
+    );
+
+    expect(result.rateLimitedCount).toBe(1);
+    expect(result.successCount).toBe(1);
+  });
+
+  it('calls onRateLimited callback when rate-limited result is detected in first batch', async () => {
+    // Single-item batches (maxConcurrency=1) so back-off delay fires between batches
+    const subtasks = [makeSubtask('rl1'), makeSubtask('rl2')];
+
+    const runner = vi.fn()
+      .mockResolvedValueOnce(makeResult('rate_limited'))
+      .mockResolvedValueOnce(makeResult('completed')) as SubtaskSessionRunner;
+
+    const onRateLimited = vi.fn();
+    const config: ParallelExecutorConfig = { maxConcurrency: 1, onRateLimited };
+
+    await runWithFakeTimers(() => executeParallel(subtasks, runner, config));
+
+    expect(onRateLimited).toHaveBeenCalledWith(expect.any(Number));
+  });
+
+  // -------------------------------------------------------------------------
+  // Concurrency limit batching
+  // -------------------------------------------------------------------------
+
+  it('respects maxConcurrency and processes all tasks in batches', async () => {
+    const subtasks = [
+      makeSubtask('b1'), makeSubtask('b2'), makeSubtask('b3'),
+      makeSubtask('b4'), makeSubtask('b5'),
+    ];
+    const runner = vi.fn().mockResolvedValue(makeResult('completed')) as SubtaskSessionRunner;
+
+    const result = await runWithFakeTimers(() =>
+      executeParallel(subtasks, runner, { maxConcurrency: 3 }),
+    );
+
+    expect(result.successCount).toBe(5);
+    expect(result.results).toHaveLength(5);
+    expect(runner).toHaveBeenCalledTimes(5);
+  });
+
+  // -------------------------------------------------------------------------
+  // Callbacks — onSubtaskStart / onSubtaskComplete / onSubtaskFailed
+  // -------------------------------------------------------------------------
+
+  it('calls onSubtaskStart for each subtask', async () => {
+    const subtasks = [makeSubtask('c1'), makeSubtask('c2')];
+    const runner = vi.fn().mockResolvedValue(makeResult('completed')) as SubtaskSessionRunner;
+    const onSubtaskStart = vi.fn();
+
+    await runWithFakeTimers(() =>
+      executeParallel(subtasks, runner, { maxConcurrency: 10, onSubtaskStart }),
+    );
+
+    expect(onSubtaskStart).toHaveBeenCalledTimes(2);
+    expect(onSubtaskStart).toHaveBeenCalledWith(expect.objectContaining({ id: 'c1' }));
+    expect(onSubtaskStart).toHaveBeenCalledWith(expect.objectContaining({ id: 'c2' }));
+  });
+
+  it('calls onSubtaskComplete for successful subtasks — single task (no stagger)', async () => {
+    const subtasks = [makeSubtask('ok1')];
+    const runner = vi.fn().mockResolvedValue(makeResult('completed')) as SubtaskSessionRunner;
+    const onSubtaskComplete = vi.fn();
+
+    // Single item at index 0 → stagger = 0ms → no fake timers needed
+    const result = await executeParallel(subtasks, runner, { maxConcurrency: 1, onSubtaskComplete });
+
+    expect(onSubtaskComplete).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'ok1' }),
+      expect.objectContaining({ outcome: 'completed' }),
+    );
+    expect(result.successCount).toBe(1);
+  });
+
+  it('calls onSubtaskFailed for error outcomes — single task', async () => {
+    const subtasks = [makeSubtask('fail1')];
+    const runner = vi.fn().mockResolvedValue(makeResult('error')) as SubtaskSessionRunner;
+    const onSubtaskFailed = vi.fn();
+
+    const result = await executeParallel(subtasks, runner, { maxConcurrency: 1, onSubtaskFailed });
+
+    expect(onSubtaskFailed).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'fail1' }),
+      expect.any(Error),
+    );
+    expect(result.failureCount).toBe(1);
+  });
+
+  it('calls onSubtaskFailed when runner throws — single task', async () => {
+    const subtasks = [makeSubtask('throw1')];
+    const runner = vi.fn().mockRejectedValue(new Error('Unexpected crash')) as SubtaskSessionRunner;
+    const onSubtaskFailed = vi.fn();
+
+    const result = await executeParallel(subtasks, runner, { maxConcurrency: 1, onSubtaskFailed });
+
+    expect(result.failureCount).toBe(1);
+    expect(onSubtaskFailed).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'throw1' }),
+      expect.any(Error),
+    );
+  });
+
+  // -------------------------------------------------------------------------
+  // Cancellation via AbortSignal
+  // -------------------------------------------------------------------------
+
+  it('marks cancelled=true when aborted before execution starts', async () => {
+    const controller = new AbortController();
+    controller.abort();
+
+    const subtasks = [makeSubtask('x1'), makeSubtask('x2')];
+    const runner = vi.fn().mockResolvedValue(makeResult('completed')) as SubtaskSessionRunner;
+
+    const result = await runWithFakeTimers(() =>
+      executeParallel(subtasks, runner, {
+        maxConcurrency: 10,
+        abortSignal: controller.signal,
+      }),
+    );
+
+    expect(result.cancelled).toBe(true);
+  });
+
+  it('returns cancelled=true when aborted after first batch completes', async () => {
+    const controller = new AbortController();
+    const subtasks = [makeSubtask('a1'), makeSubtask('a2')];
+
+    const runner = vi.fn().mockImplementation(async (subtask: SubtaskInfo) => {
+      if (subtask.id === 'a1') {
+        controller.abort();
+      }
+      return makeResult('completed');
+    }) as SubtaskSessionRunner;
+
+    const result = await runWithFakeTimers(() =>
+      executeParallel(subtasks, runner, {
+        maxConcurrency: 1,
+        abortSignal: controller.signal,
+      }),
+    );
+
+    expect(result.cancelled).toBe(true);
+  });
+
+  // -------------------------------------------------------------------------
+  // Rate-limited error from thrown exception — single task, no stagger
+  // -------------------------------------------------------------------------
+
+  it('marks rateLimited=true when thrown error contains 429', async () => {
+    const subtasks = [makeSubtask('rl-throw')];
+    const runner = vi.fn().mockRejectedValue(new Error('HTTP 429 too many requests')) as SubtaskSessionRunner;
+
+    const result = await executeParallel(subtasks, runner, { maxConcurrency: 1 });
+
+    expect(result.results[0].rateLimited).toBe(true);
+  });
+
+  // -------------------------------------------------------------------------
+  // Result structure — single task, no stagger
+  // -------------------------------------------------------------------------
+
+  it('includes session result in ParallelSubtaskResult when session ran', async () => {
+    const subtasks = [makeSubtask('struct1')];
+    const sessionResult = makeResult('completed');
+    const runner = vi.fn().mockResolvedValue(sessionResult) as SubtaskSessionRunner;
+
+    const result = await executeParallel(subtasks, runner);
+
+    expect(result.results[0].result).toBeDefined();
+    expect(result.results[0].result?.outcome).toBe('completed');
+  });
+
+  it('includes error string when runner throws', async () => {
+    const subtasks = [makeSubtask('err-str')];
+    const runner = vi.fn().mockRejectedValue(new Error('crash detail')) as SubtaskSessionRunner;
+
+    const result = await executeParallel(subtasks, runner);
+
+    expect(result.results[0].error).toContain('crash detail');
+    expect(result.results[0].success).toBe(false);
+  });
+});
@@ -0,0 +1,451 @@
+import path from 'node:path';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+const mockReadFile = vi.fn();
+const mockWriteFile = vi.fn();
+const mockUnlink = vi.fn();
+
+vi.mock('node:fs/promises', () => ({
+  readFile: (...args: unknown[]) => mockReadFile(...args),
+  writeFile: (...args: unknown[]) => mockWriteFile(...args),
+  unlink: (...args: unknown[]) => mockUnlink(...args),
+}));
+
+vi.mock('../../utils/json-repair', () => ({
+  safeParseJson: (raw: string) => {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  },
+}));
+
+vi.mock('../qa-reports', () => ({
+  generateQAReport: vi.fn(() => '# QA Report'),
+  generateEscalationReport: vi.fn(() => '# Escalation Report'),
+  generateManualTestPlan: vi.fn().mockResolvedValue('# Manual Test Plan'),
+}));
+
+// qa-loop.ts imports from '../schema' (relative to orchestration/)
+// which resolves to src/main/ai/schema/index.ts
+vi.mock('../../schema', () => ({
+  QASignoffSchema: {},
+  validateStructuredOutput: vi.fn((_data: unknown, _schema: unknown) => ({
+    valid: true,
+    data: _data,
+  })),
+}));
+
+import { QALoop } from '../qa-loop';
+import type { QALoopConfig, QASessionRunConfig } from '../qa-loop';
+import type { SessionResult } from '../../session/types';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const SPEC_DIR = '/project/.auto-claude/specs/001-feature';
+const PROJECT_DIR = '/project';
+
+function completedPlan(qaStatus?: 'approved' | 'rejected' | 'unknown') {
+  const plan: Record<string, unknown> = {
+    phases: [
+      { subtasks: [{ status: 'completed' }, { status: 'completed' }] },
+    ],
+  };
+
+  if (qaStatus === 'approved') {
+    plan.qa_signoff = { status: 'approved', issues_found: [] };
+  } else if (qaStatus === 'rejected') {
+    plan.qa_signoff = { status: 'rejected', issues_found: [{ title: 'Test failure', type: 'critical' }] };
+  }
+  // qaStatus === 'unknown' → no qa_signoff key
+
+  return JSON.stringify(plan);
+}
+
+function makeSessionResult(outcome: SessionResult['outcome']): SessionResult {
+  return {
+    outcome,
+    error: outcome === 'error' ? new Error('session error') : undefined,
+    totalSteps: 1,
+    lastMessage: '',
+  } as unknown as SessionResult;
+}
+
+function makeConfig(overrides: Partial<QALoopConfig> = {}): QALoopConfig {
+  return {
+    specDir: SPEC_DIR,
+    projectDir: PROJECT_DIR,
+    maxIterations: 5,
+    generatePrompt: vi.fn().mockResolvedValue('system prompt'),
+    runSession: vi.fn().mockResolvedValue(makeSessionResult('completed')),
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('QALoop', () => {
+  beforeEach(() => {
+    mockReadFile.mockReset();
+    mockWriteFile.mockReset().mockResolvedValue(undefined);
+    mockUnlink.mockReset().mockResolvedValue(undefined);
+  });
+
+  // -------------------------------------------------------------------------
+  // Build completeness guard
+  // -------------------------------------------------------------------------
+
+  it('returns error outcome when build is not complete', async () => {
+    // Plan with a non-completed subtask
+    const plan = JSON.stringify({
+      phases: [{ subtasks: [{ status: 'pending' }] }],
+    });
+
+    // No QA_FIX_REQUEST.md either
+    mockReadFile.mockImplementation((path: string) => {
+      if (path.endsWith('implementation_plan.json')) return Promise.resolve(plan);
+      return Promise.reject(new Error('ENOENT'));
+    });
+
+    const config = makeConfig();
+    const loop = new QALoop(config);
+    const outcome = await loop.run();
+
+    expect(outcome.approved).toBe(false);
+    expect(outcome.reason).toBe('error');
+  });
+
+  // -------------------------------------------------------------------------
+  // Already approved
+  // -------------------------------------------------------------------------
+
+  it('returns approved immediately when QA signoff is already "approved"', async () => {
+    const plan = completedPlan('approved');
+
+    mockReadFile.mockImplementation((path: string) => {
+      if (path.endsWith('implementation_plan.json')) return Promise.resolve(plan);
+      // QA_FIX_REQUEST.md does not exist
+      return Promise.reject(new Error('ENOENT'));
+    });
+
+    const config = makeConfig();
+    const loop = new QALoop(config);
+    const outcome = await loop.run();
+
+    expect(outcome.approved).toBe(true);
+    expect(outcome.totalIterations).toBe(0);
+    // runSession should NOT have been called (short-circuit)
+    expect(config.runSession).not.toHaveBeenCalled();
+  });
+
+  // -------------------------------------------------------------------------
+  // QA approved on first iteration
+  // -------------------------------------------------------------------------
+
+  it('approves on the first iteration when reviewer returns approved', async () => {
+    // Let the reviewer run session set the approved state, then all subsequent reads return approved
+    let sessionCallCount = 0;
+    let _planReadCount = 0;
+
+    const runSession = vi.fn().mockImplementation(async () => {
+      sessionCallCount++;
+      return makeSessionResult('completed');
+    });
+
+    mockReadFile.mockImplementation((path: string) => {
+      if (path.endsWith('implementation_plan.json')) {
+        _planReadCount++;
+        // Before the reviewer has run, return no signoff (build complete, no qa yet)
+        if (sessionCallCount === 0) return Promise.resolve(completedPlan());
+        // After the reviewer ran, return approved
+        return Promise.resolve(completedPlan('approved'));
+      }
+      return Promise.reject(new Error('ENOENT'));
+    });
+
+    const config = makeConfig({ runSession, maxIterations: 5 });
+    const loop = new QALoop(config);
+    const outcome = await loop.run();
+
+    expect(outcome.approved).toBe(true);
+    // Should have approved within the first few iterations
+    expect(outcome.totalIterations).toBeGreaterThanOrEqual(1);
+    // Only the reviewer should have been called (no fixer needed)
+    const calls = runSession.mock.calls as Array<[QASessionRunConfig]>;
+    expect(calls.every((c) => c[0].agentType === 'qa_reviewer')).toBe(true);
+  });
+
+  // -------------------------------------------------------------------------
+  // Rejected then approved on retry
+  // -------------------------------------------------------------------------
+
+  it('runs fixer then approves on second iteration', async () => {
+    // Track how many times runSession has been called so we know which "phase" we're in
+    let sessionCallCount = 0;
+    let planReadCount = 0;
+
+    const runSession = vi.fn().mockImplementation(async () => {
+      sessionCallCount++;
+      return makeSessionResult('completed');
+    });
+
+    mockReadFile.mockImplementation((path: string) => {
+      if (path.endsWith('implementation_plan.json')) {
+        planReadCount++;
+        if (planReadCount === 1) return Promise.resolve(completedPlan()); // isBuildComplete
+        // Reviewer on iteration 1 ran when sessionCallCount >= 1
+        // Serve rejected until fixer has run (sessionCallCount >= 2), then approved
+        if (sessionCallCount < 2) {
+          return Promise.resolve(completedPlan('rejected'));
+        }
+        return Promise.resolve(completedPlan('approved'));
+      }
+      return Promise.reject(new Error('ENOENT'));
+    });
+
+    const config = makeConfig({ runSession, maxIterations: 5 });
+    const loop = new QALoop(config);
+    const outcome = await loop.run();
+
+    expect(outcome.approved).toBe(true);
+    // At minimum: reviewer (iter 1) + fixer + reviewer (iter 2) = 3
+    expect(sessionCallCount).toBeGreaterThanOrEqual(3);
+    const calls = runSession.mock.calls as Array<[QASessionRunConfig]>;
+    const agentTypes = calls.map((c) => c[0].agentType);
+    expect(agentTypes).toContain('qa_reviewer');
+    expect(agentTypes).toContain('qa_fixer');
+  });
+
+  // -------------------------------------------------------------------------
+  // Max iterations reached
+  // -------------------------------------------------------------------------
+
+  it('returns max_iterations when approval is never reached', async () => {
+    // Always return "rejected" status with a unique issue each time
+    // so recurring_issues threshold is never reached within maxIterations=2
+    let planReadCount = 0;
+
+    mockReadFile.mockImplementation((path: string) => {
+      if (path.endsWith('implementation_plan.json')) {
+        planReadCount++;
+        if (planReadCount === 1) return Promise.resolve(completedPlan()); // build complete check
+
+        // Return distinct issues each time to avoid recurring_issues escalation
+        const plan = JSON.stringify({
+          phases: [{ subtasks: [{ status: 'completed' }] }],
+          qa_signoff: {
+            status: 'rejected',
+            issues_found: [{ title: `Unique issue ${planReadCount}`, type: 'warning' }],
+          },
+        });
+        return Promise.resolve(plan);
+      }
+      return Promise.reject(new Error('ENOENT'));
+    });
+
+    const config = makeConfig({ maxIterations: 2 });
+    const loop = new QALoop(config);
+    const outcome = await loop.run();
+
+    expect(outcome.approved).toBe(false);
+    expect(outcome.reason).toBe('max_iterations');
+  });
+
+  // -------------------------------------------------------------------------
+  // Consecutive error escalation
+  // -------------------------------------------------------------------------
+
+  it('escalates after MAX_CONSECUTIVE_ERRORS (3) consecutive unknown status responses', async () => {
+    let planReadCount = 0;
+
+    mockReadFile.mockImplementation((path: string) => {
+      if (path.endsWith('implementation_plan.json')) {
+        planReadCount++;
+        if (planReadCount === 1) return Promise.resolve(completedPlan()); // build complete
+        // Return a plan with no qa_signoff — "unknown" status
+        const planWithNoSignoff = JSON.stringify({
+          phases: [{ subtasks: [{ status: 'completed' }] }],
+        });
+        return Promise.resolve(planWithNoSignoff);
+      }
+      return Promise.reject(new Error('ENOENT'));
+    });
+
+    const config = makeConfig({ maxIterations: 10 });
+    const loop = new QALoop(config);
+    const outcome = await loop.run();
+
+    expect(outcome.approved).toBe(false);
+    expect(outcome.reason).toBe('consecutive_errors');
+  });
+
+  // -------------------------------------------------------------------------
+  // Recurring issue detection
+  // -------------------------------------------------------------------------
+
+  it('escalates when the same issue recurs 3 or more times', async () => {
+    const recurringIssue = { title: 'Null pointer exception', type: 'critical' as const };
+    const rejectedPlan = JSON.stringify({
+      phases: [{ subtasks: [{ status: 'completed' }] }],
+      qa_signoff: { status: 'rejected', issues_found: [recurringIssue] },
+    });
+
+    let planReadCount = 0;
+
+    mockReadFile.mockImplementation((path: string) => {
+      if (path.endsWith('implementation_plan.json')) {
+        planReadCount++;
+        if (planReadCount === 1) return Promise.resolve(completedPlan()); // build complete
+        return Promise.resolve(rejectedPlan);
+      }
+      return Promise.reject(new Error('ENOENT'));
+    });
+
+    const config = makeConfig({ maxIterations: 10 });
+    const loop = new QALoop(config);
+    const outcome = await loop.run();
+
+    expect(outcome.approved).toBe(false);
+    expect(outcome.reason).toBe('recurring_issues');
+  });
+
+  // -------------------------------------------------------------------------
+  // Cancellation via AbortSignal
+  // -------------------------------------------------------------------------
+
+  it('returns cancelled outcome when aborted before first iteration runs', async () => {
+    const controller = new AbortController();
+
+    mockReadFile.mockImplementation((path: string) => {
+      if (path.endsWith('implementation_plan.json')) return Promise.resolve(completedPlan());
+      return Promise.reject(new Error('ENOENT'));
+    });
+
+    const config = makeConfig({ abortSignal: controller.signal, maxIterations: 5 });
+    const loop = new QALoop(config);
+
+    // Abort after construction so the event listener fires
+    controller.abort();
+
+    const outcome = await loop.run();
+
+    expect(outcome.approved).toBe(false);
+    expect(outcome.reason).toBe('cancelled');
+  });
+
+  // -------------------------------------------------------------------------
+  // Fixer error handling
+  // -------------------------------------------------------------------------
+
+  it('returns error outcome when fixer session fails', async () => {
+    let planReadCount = 0;
+
+    mockReadFile.mockImplementation((path: string) => {
+      if (path.endsWith('implementation_plan.json')) {
+        planReadCount++;
+        if (planReadCount === 1) return Promise.resolve(completedPlan());
+        return Promise.resolve(completedPlan('rejected'));
+      }
+      return Promise.reject(new Error('ENOENT'));
+    });
+
+    const runSession = vi.fn()
+      .mockResolvedValueOnce(makeSessionResult('completed')) // reviewer iteration 1
+      .mockResolvedValueOnce(makeSessionResult('error'));     // fixer fails
+
+    const config = makeConfig({ runSession, maxIterations: 5 });
+    const loop = new QALoop(config);
+    const outcome = await loop.run();
+
+    expect(outcome.approved).toBe(false);
+    expect(outcome.reason).toBe('error');
+  });
+
+  // -------------------------------------------------------------------------
+  // Reviewer cancelled mid-loop
+  // -------------------------------------------------------------------------
+
+  it('returns cancelled when reviewer session is cancelled', async () => {
+    let planReadCount = 0;
+
+    mockReadFile.mockImplementation((path: string) => {
+      if (path.endsWith('implementation_plan.json')) {
+        planReadCount++;
+        if (planReadCount === 1) return Promise.resolve(completedPlan());
+        return Promise.resolve(completedPlan());
+      }
+      return Promise.reject(new Error('ENOENT'));
+    });
+
+    const runSession = vi.fn().mockResolvedValueOnce(makeSessionResult('cancelled'));
+
+    const config = makeConfig({ runSession, maxIterations: 5 });
+    const loop = new QALoop(config);
+    const outcome = await loop.run();
+
+    expect(outcome.approved).toBe(false);
+    expect(outcome.reason).toBe('cancelled');
+  });
+
+  // -------------------------------------------------------------------------
+  // Human feedback processing
+  // -------------------------------------------------------------------------
+
+  it('processes QA_FIX_REQUEST.md before running the review loop', async () => {
+    // QA_FIX_REQUEST.md exists
+    mockReadFile.mockImplementation((path: string) => {
+      if (path.endsWith('QA_FIX_REQUEST.md')) return Promise.resolve('Fix this please');
+      if (path.endsWith('implementation_plan.json')) return Promise.resolve(completedPlan('approved'));
+      return Promise.reject(new Error('ENOENT'));
+    });
+
+    const runSession = vi.fn().mockResolvedValue(makeSessionResult('completed'));
+    const config = makeConfig({ runSession, maxIterations: 5 });
+    const loop = new QALoop(config);
+    const outcome = await loop.run();
+
+    // Fixer should have been invoked for human feedback
+    const calls = runSession.mock.calls as Array<[QASessionRunConfig]>;
+    expect(calls.some((c) => c[0].agentType === 'qa_fixer')).toBe(true);
+    // Fix request file should be deleted
+    expect(mockUnlink).toHaveBeenCalledWith(path.join(SPEC_DIR, 'QA_FIX_REQUEST.md'));
+    // Overall outcome should still reflect the QA result
+    expect(outcome.approved).toBe(true);
+  });
+
+  // -------------------------------------------------------------------------
+  // Events
+  // -------------------------------------------------------------------------
+
+  it('emits qa-complete event with the final outcome', async () => {
+    let planReadCount = 0;
+    mockReadFile.mockImplementation((path: string) => {
+      if (path.endsWith('implementation_plan.json')) {
+        planReadCount++;
+        if (planReadCount === 1) return Promise.resolve(completedPlan());
+        return Promise.resolve(completedPlan('approved'));
+      }
+      return Promise.reject(new Error('ENOENT'));
+    });
+
+    const config = makeConfig();
+    const loop = new QALoop(config);
+
+    const completedEvents: unknown[] = [];
+    loop.on('qa-complete', (outcome) => completedEvents.push(outcome));
+
+    await loop.run();
+
+    expect(completedEvents).toHaveLength(1);
+    expect((completedEvents[0] as { approved: boolean }).approved).toBe(true);
+  });
+});
@@ -0,0 +1,364 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+const mockReadFile = vi.fn();
+const mockExistsSync = vi.fn();
+const mockReaddirSync = vi.fn();
+
+vi.mock('node:fs/promises', () => ({
+  readFile: (...args: unknown[]) => mockReadFile(...args),
+}));
+
+vi.mock('node:fs', () => ({
+  existsSync: (...args: unknown[]) => mockExistsSync(...args),
+  readdirSync: (...args: unknown[]) => mockReaddirSync(...args),
+}));
+
+import {
+  generateQAReport,
+  generateEscalationReport,
+  generateManualTestPlan,
+  issuesSimilar,
+  isNoTestProject,
+} from '../qa-reports';
+import type { QAIterationRecord, QAIssue } from '../qa-loop';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeRecord(
+  iteration: number,
+  status: 'approved' | 'rejected' | 'error',
+  issues: QAIssue[] = [],
+  durationMs = 1000,
+): QAIterationRecord {
+  return {
+    iteration,
+    status,
+    issues,
+    durationMs,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+function makeIssue(title: string, opts: Partial<QAIssue> = {}): QAIssue {
+  return { title, ...opts };
+}
+
+// ---------------------------------------------------------------------------
+// generateQAReport
+// ---------------------------------------------------------------------------
+
+describe('generateQAReport', () => {
+  it('produces a report with APPROVED status label', () => {
+    const iterations: QAIterationRecord[] = [
+      makeRecord(1, 'rejected', [makeIssue('Missing test')], 2000),
+      makeRecord(2, 'approved', [], 1500),
+    ];
+
+    const report = generateQAReport(iterations, 'approved');
+
+    expect(report).toContain('APPROVED');
+    expect(report).toContain('PASSED');
+    expect(report).toContain('Total Iterations');
+    expect(report).toContain('2');
+  });
+
+  it('produces a report with ESCALATED status label', () => {
+    const iterations: QAIterationRecord[] = [
+      makeRecord(1, 'rejected', [makeIssue('Null pointer')], 500),
+    ];
+
+    const report = generateQAReport(iterations, 'escalated');
+
+    expect(report).toContain('ESCALATED');
+    expect(report).toContain('FAILED');
+    expect(report).toContain('escalated to human review');
+  });
+
+  it('produces a report with MAX ITERATIONS REACHED label', () => {
+    const iterations: QAIterationRecord[] = [
+      makeRecord(1, 'rejected', [], 800),
+      makeRecord(2, 'rejected', [], 800),
+    ];
+
+    const report = generateQAReport(iterations, 'max_iterations');
+
+    expect(report).toContain('MAX ITERATIONS REACHED');
+    expect(report).toContain('FAILED');
+    expect(report).toContain('maximum');
+  });
+
+  it('handles empty iteration history gracefully', () => {
+    const report = generateQAReport([], 'approved');
+
+    expect(report).toContain('No iterations recorded');
+    expect(report).toContain('Total Iterations');
+  });
+
+  it('includes issue details in iteration history section', () => {
+    const issue = makeIssue('Type error in auth.ts', {
+      type: 'critical',
+      location: 'src/auth.ts:42',
+      description: 'Property does not exist',
+      fix_required: 'Add null check',
+    });
+
+    const report = generateQAReport([makeRecord(1, 'rejected', [issue])], 'escalated');
+
+    expect(report).toContain('Type error in auth.ts');
+    expect(report).toContain('[CRITICAL]');
+    expect(report).toContain('src/auth.ts:42');
+    expect(report).toContain('Property does not exist');
+    expect(report).toContain('Add null check');
+  });
+
+  it('calculates summary counts correctly', () => {
+    const iterations: QAIterationRecord[] = [
+      makeRecord(1, 'rejected', [makeIssue('A'), makeIssue('B')]),
+      makeRecord(2, 'error', [makeIssue('C')]),
+      makeRecord(3, 'approved', []),
+    ];
+
+    const report = generateQAReport(iterations, 'approved');
+
+    expect(report).toContain('Approved Iterations');
+    expect(report).toContain('Rejected Iterations');
+    expect(report).toContain('Error Iterations');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// generateEscalationReport
+// ---------------------------------------------------------------------------
+
+describe('generateEscalationReport', () => {
+  it('lists recurring issues by title', () => {
+    const recurringIssues: QAIssue[] = [
+      makeIssue('Database connection leak', {
+        type: 'critical',
+        location: 'src/db.ts',
+        description: 'Connection is never closed',
+        fix_required: 'Use try-finally block',
+      }),
+    ];
+
+    const iterations: QAIterationRecord[] = [
+      makeRecord(1, 'rejected', recurringIssues),
+      makeRecord(2, 'rejected', recurringIssues),
+      makeRecord(3, 'rejected', recurringIssues),
+    ];
+
+    const report = generateEscalationReport(iterations, recurringIssues);
+
+    expect(report).toContain('Human Intervention Required');
+    expect(report).toContain('Database connection leak');
+    expect(report).toContain('src/db.ts');
+    expect(report).toContain('Connection is never closed');
+    expect(report).toContain('Use try-finally block');
+  });
+
+  it('includes summary statistics', () => {
+    const issue = makeIssue('Error X');
+    const iterations = [
+      makeRecord(1, 'rejected', [issue]),
+      makeRecord(2, 'rejected', [issue]),
+      makeRecord(3, 'rejected', [issue]),
+    ];
+
+    const report = generateEscalationReport(iterations, [issue]);
+
+    expect(report).toContain('Total QA Iterations');
+    expect(report).toContain('Total Issues Found');
+    expect(report).toContain('Unique Issues');
+    expect(report).toContain('Fix Success Rate');
+  });
+
+  it('includes recommended actions section', () => {
+    const report = generateEscalationReport([], []);
+
+    expect(report).toContain('Recommended Actions');
+    expect(report).toContain('QA_FIX_REQUEST.md');
+  });
+
+  it('includes most common issues when present', () => {
+    const issue1 = makeIssue('Common bug');
+    const issue2 = makeIssue('Rare bug');
+
+    const iterations = [
+      makeRecord(1, 'rejected', [issue1, issue2]),
+      makeRecord(2, 'rejected', [issue1]),
+      makeRecord(3, 'rejected', [issue1]),
+    ];
+
+    const report = generateEscalationReport(iterations, [issue1]);
+
+    expect(report).toContain('Most Common Issues');
+    expect(report).toContain('common bug');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// generateManualTestPlan
+// ---------------------------------------------------------------------------
+
+describe('generateManualTestPlan', () => {
+  const SPEC_DIR = '/project/.auto-claude/specs/001-feature';
+  const PROJECT_DIR = '/project';
+
+  beforeEach(() => {
+    mockReadFile.mockReset();
+    mockExistsSync.mockReset().mockReturnValue(false);
+    mockReaddirSync.mockReset().mockReturnValue([]);
+  });
+
+  it('generates a basic test plan when spec.md is missing', async () => {
+    mockReadFile.mockRejectedValue(new Error('ENOENT'));
+
+    const plan = await generateManualTestPlan(SPEC_DIR, PROJECT_DIR);
+
+    expect(plan).toContain('Manual Test Plan');
+    expect(plan).toContain('Pre-Test Setup');
+    expect(plan).toContain('Functional Tests');
+    expect(plan).toContain('Sign-off');
+  });
+
+  it('extracts acceptance criteria from spec.md when available', async () => {
+    const specContent = `# Feature Spec
+
+## Overview
+Some description.
+
+## Acceptance Criteria
+- User can log in
+- User sees dashboard after login
+- Invalid credentials show error
+
+## Technical Details
+Not relevant here.
+`;
+
+    mockReadFile.mockResolvedValue(specContent);
+
+    const plan = await generateManualTestPlan(SPEC_DIR, PROJECT_DIR);
+
+    expect(plan).toContain('User can log in');
+    expect(plan).toContain('User sees dashboard after login');
+    expect(plan).toContain('Invalid credentials show error');
+  });
+
+  it('notes "no automated test framework" when none is detected', async () => {
+    mockReadFile.mockRejectedValue(new Error('ENOENT'));
+    // existsSync returns false → no test config found
+
+    const plan = await generateManualTestPlan(SPEC_DIR, PROJECT_DIR);
+
+    expect(plan).toContain('No automated test framework detected');
+  });
+
+  it('notes "supplemental manual verification" when a test framework is present', async () => {
+    mockReadFile.mockRejectedValue(new Error('ENOENT'));
+    // Simulate vitest.config.ts existing
+    mockExistsSync.mockImplementation((p: string) => p.endsWith('vitest.config.ts'));
+
+    const plan = await generateManualTestPlan(SPEC_DIR, PROJECT_DIR);
+
+    expect(plan).toContain('supplement to automated tests');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// issuesSimilar
+// ---------------------------------------------------------------------------
+
+describe('issuesSimilar', () => {
+  it('returns true for identical issues', () => {
+    const issue = makeIssue('Null pointer exception', { description: 'Null reference in auth module' });
+    expect(issuesSimilar(issue, issue)).toBe(true);
+  });
+
+  it('returns true for issues with high token overlap', () => {
+    const a = makeIssue('null pointer exception in auth module');
+    const b = makeIssue('null pointer exception in auth module');
+    expect(issuesSimilar(a, b)).toBe(true);
+  });
+
+  it('returns false for completely different issues', () => {
+    const a = makeIssue('Database connection timeout', { description: 'MySQL connection drops after 30s' });
+    const b = makeIssue('UI button not rendering', { description: 'Submit button disappears on mobile' });
+    expect(issuesSimilar(a, b)).toBe(false);
+  });
+
+  it('strips common prefixes before comparing', () => {
+    const a = makeIssue('error: null pointer exception');
+    const b = makeIssue('bug: null pointer exception');
+    // Both strip to "null pointer exception" — should be considered similar
+    expect(issuesSimilar(a, b)).toBe(true);
+  });
+
+  it('uses custom threshold when provided', () => {
+    const a = makeIssue('Some issue here', { description: 'partial match description' });
+    const b = makeIssue('Some issue here', { description: 'completely different thing' });
+    // At very low threshold, should match on title alone
+    expect(issuesSimilar(a, b, 0.1)).toBe(true);
+    // At very high threshold, partial description overlap may fail
+    expect(issuesSimilar(a, b, 0.99)).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isNoTestProject
+// ---------------------------------------------------------------------------
+
+describe('isNoTestProject', () => {
+  const PROJECT_DIR = '/my-project';
+
+  beforeEach(() => {
+    mockExistsSync.mockReset().mockReturnValue(false);
+    mockReaddirSync.mockReset().mockReturnValue([]);
+  });
+
+  it('returns false when vitest.config.ts exists', () => {
+    mockExistsSync.mockImplementation((p: string) => p.endsWith('vitest.config.ts'));
+    expect(isNoTestProject('/spec', PROJECT_DIR)).toBe(false);
+  });
+
+  it('returns false when jest.config.js exists', () => {
+    mockExistsSync.mockImplementation((p: string) => p.endsWith('jest.config.js'));
+    expect(isNoTestProject('/spec', PROJECT_DIR)).toBe(false);
+  });
+
+  it('returns false when pytest.ini exists', () => {
+    mockExistsSync.mockImplementation((p: string) => p.endsWith('pytest.ini'));
+    expect(isNoTestProject('/spec', PROJECT_DIR)).toBe(false);
+  });
+
+  it('returns false when test files are found in __tests__ directory', () => {
+    mockExistsSync.mockImplementation((p: string) => p.endsWith('__tests__'));
+    mockReaddirSync.mockReturnValue(['auth.test.ts', 'utils.test.ts']);
+    expect(isNoTestProject('/spec', PROJECT_DIR)).toBe(false);
+  });
+
+  it('returns true when no test config files and no test directories exist', () => {
+    mockExistsSync.mockReturnValue(false);
+    expect(isNoTestProject('/spec', PROJECT_DIR)).toBe(true);
+  });
+
+  it('returns true when test directories exist but contain no test files', () => {
+    mockExistsSync.mockImplementation((p: string) => p.endsWith('tests'));
+    mockReaddirSync.mockReturnValue(['README.md', 'fixtures.json']);
+    expect(isNoTestProject('/spec', PROJECT_DIR)).toBe(true);
+  });
+
+  it('handles readdir errors gracefully and returns true', () => {
+    mockExistsSync.mockImplementation((p: string) => p.endsWith('tests'));
+    mockReaddirSync.mockImplementation(() => {
+      throw new Error('Permission denied');
+    });
+    expect(isNoTestProject('/spec', PROJECT_DIR)).toBe(true);
+  });
+});
@@ -0,0 +1,500 @@
+import path from 'node:path';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// ---------------------------------------------------------------------------
+// Mocks — declared before any imports that pull in the mocked modules
+// ---------------------------------------------------------------------------
+
+const mockReadFile = vi.fn();
+const mockWriteFile = vi.fn();
+const mockMkdir = vi.fn();
+
+vi.mock('node:fs/promises', () => ({
+  readFile: (...args: unknown[]) => mockReadFile(...args),
+  writeFile: (...args: unknown[]) => mockWriteFile(...args),
+  mkdir: (...args: unknown[]) => mockMkdir(...args),
+}));
+
+vi.mock('../../utils/json-repair', () => ({
+  safeParseJson: (raw: string) => {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  },
+}));
+
+import { RecoveryManager } from '../recovery-manager';
+import type { BuildCheckpoint, FailureType } from '../recovery-manager';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const PROJECT_DIR = path.join(path.sep, 'project');
+const SPEC_DIR = path.join(PROJECT_DIR, '.auto-claude', 'specs', '001-feature');
+const MEMORY_DIR = path.join(SPEC_DIR, 'memory');
+const ATTEMPT_HISTORY_PATH = path.join(MEMORY_DIR, 'attempt_history.json');
+
+function makeHistory(
+  subtasks: Record<string, Array<{ timestamp: string; error: string; failureType: FailureType; errorHash: string }>>,
+  stuckSubtasks: string[] = [],
+) {
+  return JSON.stringify({
+    subtasks,
+    stuckSubtasks,
+    metadata: { createdAt: new Date().toISOString(), lastUpdated: new Date().toISOString() },
+  });
+}
+
+function recentTimestamp() {
+  return new Date().toISOString();
+}
+
+function oldTimestamp() {
+  // 3 hours ago — outside the 2-hour window
+  return new Date(Date.now() - 3 * 60 * 60 * 1_000).toISOString();
+}
+
+function createManager() {
+  return new RecoveryManager(SPEC_DIR, PROJECT_DIR);
+}
+
+// ---------------------------------------------------------------------------
+// classifyFailure
+// ---------------------------------------------------------------------------
+
+describe('RecoveryManager.classifyFailure', () => {
+  let manager: RecoveryManager;
+
+  beforeEach(() => {
+    manager = createManager();
+  });
+
+  const cases: Array<[string, FailureType]> = [
+    ['SyntaxError: Unexpected token', 'broken_build'],
+    ['Module not found: react', 'broken_build'],
+    ['compilation error in main.ts', 'broken_build'],
+    ['cannot find module lodash', 'broken_build'],
+    // 'IndentationError' is not in the source's buildErrors list — removed
+    ['parse error in config.js', 'broken_build'],
+
+    ['verification failed: response mismatch', 'verification_failed'],
+    ['AssertionError: expected 1 to equal 2', 'verification_failed'],
+    ['test failed: missing element', 'verification_failed'],
+    ['status code 404 received', 'verification_failed'],
+
+    ['context window exceeded', 'context_exhausted'],
+    ['token limit reached', 'context_exhausted'],
+    ['maximum length of response reached', 'context_exhausted'],
+
+    ['429 too many requests', 'rate_limited'],
+    ['rate limit exceeded', 'rate_limited'],
+    ['too many requests from your IP', 'rate_limited'],
+
+    ['401 unauthorized access', 'auth_failure'],
+    ['auth token expired', 'auth_failure'],
+
+    ['a totally random and obscure crash', 'unknown'],
+    ['', 'unknown'],
+  ];
+
+  it.each(cases)('classifies "%s" as %s', (error, expected) => {
+    expect(manager.classifyFailure(error, 'subtask-1')).toBe(expected);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Checkpoint save / load round-trip
+// ---------------------------------------------------------------------------
+
+describe('RecoveryManager checkpoint round-trip', () => {
+  let manager: RecoveryManager;
+
+  beforeEach(() => {
+    mockWriteFile.mockReset().mockResolvedValue(undefined);
+    mockReadFile.mockReset();
+    manager = createManager();
+  });
+
+  it('writes a parseable checkpoint and loads it back', async () => {
+    const checkpoint: BuildCheckpoint = {
+      specId: '001',
+      phase: 'coding',
+      lastCompletedSubtaskId: 'subtask-3',
+      totalSubtasks: 5,
+      completedSubtasks: 3,
+      stuckSubtasks: [],
+      timestamp: new Date().toISOString(),
+      isComplete: false,
+    };
+
+    // Save captures what was written
+    let writtenContent = '';
+    mockWriteFile.mockImplementation((_path: string, content: string) => {
+      writtenContent = content;
+      return Promise.resolve();
+    });
+
+    await manager.saveCheckpoint(checkpoint);
+
+    // Verify writeFile was called with the progress file path
+    expect(mockWriteFile).toHaveBeenCalledWith(
+      path.join(SPEC_DIR, 'build-progress.txt'),
+      expect.stringContaining('spec_id: 001'),
+      'utf-8',
+    );
+
+    // Now load the checkpoint from what was written
+    mockReadFile.mockResolvedValueOnce(writtenContent);
+    const loaded = await manager.loadCheckpoint();
+
+    expect(loaded).not.toBeNull();
+    expect(loaded?.specId).toBe('001');
+    expect(loaded?.phase).toBe('coding');
+    expect(loaded?.lastCompletedSubtaskId).toBe('subtask-3');
+    expect(loaded?.totalSubtasks).toBe(5);
+    expect(loaded?.completedSubtasks).toBe(3);
+    expect(loaded?.isComplete).toBe(false);
+  });
+
+  it('saves lastCompletedSubtaskId=null as "none" and reloads as null', async () => {
+    const checkpoint: BuildCheckpoint = {
+      specId: '002',
+      phase: 'planning',
+      lastCompletedSubtaskId: null,
+      totalSubtasks: 3,
+      completedSubtasks: 0,
+      stuckSubtasks: [],
+      timestamp: new Date().toISOString(),
+      isComplete: false,
+    };
+
+    let writtenContent = '';
+    mockWriteFile.mockImplementation((_path: string, content: string) => {
+      writtenContent = content;
+      return Promise.resolve();
+    });
+
+    await manager.saveCheckpoint(checkpoint);
+    expect(writtenContent).toContain('last_completed_subtask: none');
+
+    mockReadFile.mockResolvedValueOnce(writtenContent);
+    const loaded = await manager.loadCheckpoint();
+    expect(loaded?.lastCompletedSubtaskId).toBeNull();
+  });
+
+  it('returns null when no checkpoint file exists', async () => {
+    mockReadFile.mockRejectedValueOnce(new Error('ENOENT'));
+    const loaded = await manager.loadCheckpoint();
+    expect(loaded).toBeNull();
+  });
+
+  it('saves stuckSubtasks correctly', async () => {
+    const checkpoint: BuildCheckpoint = {
+      specId: '003',
+      phase: 'coding',
+      lastCompletedSubtaskId: null,
+      totalSubtasks: 4,
+      completedSubtasks: 1,
+      stuckSubtasks: ['subtask-1', 'subtask-2'],
+      timestamp: new Date().toISOString(),
+      isComplete: false,
+    };
+
+    let writtenContent = '';
+    mockWriteFile.mockImplementation((_path: string, content: string) => {
+      writtenContent = content;
+      return Promise.resolve();
+    });
+
+    await manager.saveCheckpoint(checkpoint);
+
+    mockReadFile.mockResolvedValueOnce(writtenContent);
+    const loaded = await manager.loadCheckpoint();
+    expect(loaded?.stuckSubtasks).toEqual(['subtask-1', 'subtask-2']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Circular fix detection
+// ---------------------------------------------------------------------------
+
+describe('RecoveryManager.isCircularFix', () => {
+  let manager: RecoveryManager;
+
+  beforeEach(() => {
+    mockReadFile.mockReset();
+    mockWriteFile.mockReset().mockResolvedValue(undefined);
+    manager = createManager();
+  });
+
+  it('returns false when fewer than 3 identical errors exist', async () => {
+    // Produce a real hash by calling classifyFailure indirectly
+    // We need the same hash that simpleHash("same error") would produce.
+    // We'll record 2 attempts with the same error, then check.
+    const sameError = 'same error message';
+
+    // Build a history with 2 records that share the same errorHash
+    // We compute the hash the same way the source does: via recordAttempt
+    // Here we mock the file system to return a pre-built history.
+    // For simplicity, we simulate 2 identical hashes manually.
+    const history = {
+      subtasks: {
+        'task-1': [
+          { timestamp: recentTimestamp(), error: sameError, failureType: 'unknown', errorHash: 'aaa' },
+          { timestamp: recentTimestamp(), error: sameError, failureType: 'unknown', errorHash: 'aaa' },
+        ],
+      },
+      stuckSubtasks: [],
+      metadata: { createdAt: new Date().toISOString(), lastUpdated: new Date().toISOString() },
+    };
+
+    mockReadFile.mockResolvedValue(JSON.stringify(history));
+    const result = await manager.isCircularFix('task-1');
+    expect(result).toBe(false);
+  });
+
+  it('returns true when 3 or more identical error hashes exist within the window', async () => {
+    const history = {
+      subtasks: {
+        'task-1': [
+          { timestamp: recentTimestamp(), error: 'err', failureType: 'unknown', errorHash: 'bbb' },
+          { timestamp: recentTimestamp(), error: 'err', failureType: 'unknown', errorHash: 'bbb' },
+          { timestamp: recentTimestamp(), error: 'err', failureType: 'unknown', errorHash: 'bbb' },
+        ],
+      },
+      stuckSubtasks: [],
+      metadata: { createdAt: new Date().toISOString(), lastUpdated: new Date().toISOString() },
+    };
+
+    mockReadFile.mockResolvedValue(JSON.stringify(history));
+    const result = await manager.isCircularFix('task-1');
+    expect(result).toBe(true);
+  });
+
+  it('ignores attempts outside the 2-hour window', async () => {
+    const history = {
+      subtasks: {
+        'task-1': [
+          // Two old entries — outside window
+          { timestamp: oldTimestamp(), error: 'err', failureType: 'unknown', errorHash: 'ccc' },
+          { timestamp: oldTimestamp(), error: 'err', failureType: 'unknown', errorHash: 'ccc' },
+          { timestamp: oldTimestamp(), error: 'err', failureType: 'unknown', errorHash: 'ccc' },
+          // One recent entry
+          { timestamp: recentTimestamp(), error: 'err', failureType: 'unknown', errorHash: 'ccc' },
+        ],
+      },
+      stuckSubtasks: [],
+      metadata: { createdAt: new Date().toISOString(), lastUpdated: new Date().toISOString() },
+    };
+
+    mockReadFile.mockResolvedValue(JSON.stringify(history));
+    const result = await manager.isCircularFix('task-1');
+    // Only 1 recent entry → not circular
+    expect(result).toBe(false);
+  });
+
+  it('returns false for a subtask with no attempt history', async () => {
+    mockReadFile.mockResolvedValue(makeHistory({}));
+    const result = await manager.isCircularFix('no-such-task');
+    expect(result).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Attempt window filtering via getAttemptCount
+// ---------------------------------------------------------------------------
+
+describe('RecoveryManager.getAttemptCount', () => {
+  let manager: RecoveryManager;
+
+  beforeEach(() => {
+    mockReadFile.mockReset();
+    mockWriteFile.mockReset().mockResolvedValue(undefined);
+    manager = createManager();
+  });
+
+  it('counts only recent attempts within the 2-hour window', async () => {
+    const history = {
+      subtasks: {
+        'task-x': [
+          { timestamp: oldTimestamp(), error: 'old error', failureType: 'unknown', errorHash: 'h1' },
+          { timestamp: recentTimestamp(), error: 'new error 1', failureType: 'unknown', errorHash: 'h2' },
+          { timestamp: recentTimestamp(), error: 'new error 2', failureType: 'unknown', errorHash: 'h3' },
+        ],
+      },
+      stuckSubtasks: [],
+      metadata: { createdAt: new Date().toISOString(), lastUpdated: new Date().toISOString() },
+    };
+
+    mockReadFile.mockResolvedValue(JSON.stringify(history));
+    const count = await manager.getAttemptCount('task-x');
+    expect(count).toBe(2);
+  });
+
+  it('returns 0 for unknown subtask', async () => {
+    mockReadFile.mockResolvedValue(makeHistory({}));
+    const count = await manager.getAttemptCount('ghost-task');
+    expect(count).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// determineRecoveryAction
+// ---------------------------------------------------------------------------
+
+describe('RecoveryManager.determineRecoveryAction', () => {
+  let manager: RecoveryManager;
+
+  beforeEach(() => {
+    mockReadFile.mockReset();
+    mockWriteFile.mockReset().mockResolvedValue(undefined);
+    manager = createManager();
+  });
+
+  it('escalates immediately when circular fix detected', async () => {
+    // 3 identical error hashes → circular
+    const history = {
+      subtasks: {
+        'task-circ': [
+          { timestamp: recentTimestamp(), error: 'err', failureType: 'unknown', errorHash: 'xyz' },
+          { timestamp: recentTimestamp(), error: 'err', failureType: 'unknown', errorHash: 'xyz' },
+          { timestamp: recentTimestamp(), error: 'err', failureType: 'unknown', errorHash: 'xyz' },
+        ],
+      },
+      stuckSubtasks: [],
+      metadata: { createdAt: new Date().toISOString(), lastUpdated: new Date().toISOString() },
+    };
+    mockReadFile.mockResolvedValue(JSON.stringify(history));
+
+    const action = await manager.determineRecoveryAction('task-circ', 'err', 5);
+    expect(action.action).toBe('escalate');
+    expect(action.reason).toMatch(/circular/i);
+  });
+
+  it('skips when attempt count >= maxRetries', async () => {
+    const history = {
+      subtasks: {
+        'task-skip': [
+          { timestamp: recentTimestamp(), error: 'fail', failureType: 'unknown', errorHash: 'a1' },
+          { timestamp: recentTimestamp(), error: 'fail', failureType: 'unknown', errorHash: 'a2' },
+          { timestamp: recentTimestamp(), error: 'fail', failureType: 'unknown', errorHash: 'a3' },
+        ],
+      },
+      stuckSubtasks: [],
+      metadata: { createdAt: new Date().toISOString(), lastUpdated: new Date().toISOString() },
+    };
+    mockReadFile.mockResolvedValue(JSON.stringify(history));
+
+    const action = await manager.determineRecoveryAction('task-skip', 'fail', 3);
+    expect(action.action).toBe('skip');
+    expect(action.reason).toMatch(/max retries/i);
+  });
+
+  it('escalates on auth failure', async () => {
+    mockReadFile.mockResolvedValue(makeHistory({ 'task-auth': [] }));
+    const action = await manager.determineRecoveryAction('task-auth', '401 unauthorized', 5);
+    expect(action.action).toBe('escalate');
+    expect(action.reason).toMatch(/auth/i);
+  });
+
+  it('retries on rate limit', async () => {
+    mockReadFile.mockResolvedValue(makeHistory({ 'task-rl': [] }));
+    const action = await manager.determineRecoveryAction('task-rl', '429 rate limit exceeded', 5);
+    expect(action.action).toBe('retry');
+    expect(action.reason).toMatch(/rate limit/i);
+  });
+
+  it('retries on context exhaustion', async () => {
+    mockReadFile.mockResolvedValue(makeHistory({ 'task-ctx': [] }));
+    const action = await manager.determineRecoveryAction('task-ctx', 'context window exceeded', 5);
+    expect(action.action).toBe('retry');
+    expect(action.reason).toMatch(/context/i);
+  });
+
+  it('defaults to retry for unknown failure types', async () => {
+    mockReadFile.mockResolvedValue(makeHistory({ 'task-unk': [] }));
+    const action = await manager.determineRecoveryAction('task-unk', 'something weird', 5);
+    expect(action.action).toBe('retry');
+    expect(action.target).toBe('task-unk');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// init — directory creation and history bootstrap
+// ---------------------------------------------------------------------------
+
+describe('RecoveryManager.init', () => {
+  let manager: RecoveryManager;
+
+  beforeEach(() => {
+    mockMkdir.mockReset().mockResolvedValue(undefined);
+    mockReadFile.mockReset();
+    mockWriteFile.mockReset().mockResolvedValue(undefined);
+    manager = createManager();
+  });
+
+  it('creates memory directory with recursive flag', async () => {
+    // Simulate history file already existing
+    mockReadFile.mockResolvedValueOnce(makeHistory({}));
+    await manager.init();
+    expect(mockMkdir).toHaveBeenCalledWith(MEMORY_DIR, { recursive: true });
+  });
+
+  it('writes an empty history when no history file exists', async () => {
+    mockReadFile.mockRejectedValueOnce(new Error('ENOENT'));
+    await manager.init();
+    expect(mockWriteFile).toHaveBeenCalledWith(
+      ATTEMPT_HISTORY_PATH,
+      expect.stringContaining('"subtasks"'),
+      'utf-8',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// markStuck / isStuck
+// ---------------------------------------------------------------------------
+
+describe('RecoveryManager stuck tracking', () => {
+  let manager: RecoveryManager;
+
+  beforeEach(() => {
+    mockReadFile.mockReset();
+    mockWriteFile.mockReset().mockResolvedValue(undefined);
+    manager = createManager();
+  });
+
+  it('marks a subtask as stuck and detects it', async () => {
+    let storedHistory = makeHistory({}, []);
+
+    mockReadFile.mockImplementation(() => Promise.resolve(storedHistory));
+    mockWriteFile.mockImplementation((_path: string, content: string) => {
+      storedHistory = content;
+      return Promise.resolve();
+    });
+
+    await manager.markStuck('task-stuck');
+
+    expect(await manager.isStuck('task-stuck')).toBe(true);
+    expect(await manager.isStuck('task-fine')).toBe(false);
+  });
+
+  it('does not duplicate a subtask when marked stuck twice', async () => {
+    let storedHistory = makeHistory({}, []);
+
+    mockReadFile.mockImplementation(() => Promise.resolve(storedHistory));
+    mockWriteFile.mockImplementation((_path: string, content: string) => {
+      storedHistory = content;
+      return Promise.resolve();
+    });
+
+    await manager.markStuck('task-dup');
+    await manager.markStuck('task-dup');
+
+    const parsed = JSON.parse(storedHistory) as { stuckSubtasks: string[] };
+    expect(parsed.stuckSubtasks.filter((id) => id === 'task-dup')).toHaveLength(1);
+  });
+});
@@ -272,36 +272,16 @@ export class BuildOrchestrator extends EventEmitter {
          `Implementation plan is invalid and cannot be executed: ${errorDetail}`);
      }

-      // Guard: if all subtasks appear "completed" but no coding has actually happened,
-      // the spec pipeline or planner marked them erroneously. Reset to "pending".
-      // This catches the case where the spec orchestrator created the plan (isFirstRun=false)
-      // but the planner LLM set all subtasks to "completed" during planning.
-      let buildComplete = await this.isBuildComplete();
-      if (buildComplete) {
-        const hasCodedBefore = await this.hasCodingEvidence();
-        if (!hasCodedBefore) {
-          this.emitTyped('log', 'All subtasks marked completed but no coding evidence found — resetting to pending');
-          await this.resetSubtaskStatuses();
-          buildComplete = false; // We just reset, so it's no longer complete
-        } else {
-          // Coding happened — check if QA already passed before declaring complete.
-          // This handles the restart-after-QA-failure case: skip coding, re-run QA.
-          const qaStatus = await this.readQAStatus();
-          if (qaStatus === 'passed') {
-            this.transitionPhase('complete', 'Build already complete');
-            return this.buildOutcome(true, Date.now() - startTime);
-          }
-          // QA failed or never ran — skip coding, fall through to QA
-          this.emitTyped('log', `Coding complete but QA status is "${qaStatus}" — skipping to QA`);
-        }
+      // Check if build is already complete
+      if (await this.isBuildComplete()) {
+        this.transitionPhase('complete', 'Build already complete');
+        return this.buildOutcome(true, Date.now() - startTime);
      }

-      // Coding phase (skip if all subtasks already completed with coding evidence)
-      if (!buildComplete) {
-        const codingResult = await this.runCodingPhase();
-        if (!codingResult.success) {
-          return this.buildOutcome(false, Date.now() - startTime, codingResult.error);
-        }
+      // Coding phase
+      const codingResult = await this.runCodingPhase();
+      if (!codingResult.success) {
+        return this.buildOutcome(false, Date.now() - startTime, codingResult.error);
      }

      // QA review phase
@@ -546,10 +526,6 @@ export class BuildOrchestrator extends EventEmitter {
        return { success: false, error: 'Build cancelled' };
      }

-      if (reviewResult.outcome === 'error' || reviewResult.outcome === 'auth_failure' || reviewResult.outcome === 'rate_limited') {
-        return { success: false, error: reviewResult.error?.message ?? 'QA review session failed' };
-      }
-
      // Check QA result
      const qaStatus = await this.readQAStatus();

@@ -586,15 +562,6 @@ export class BuildOrchestrator extends EventEmitter {
        });

        this.emitTyped('session-complete', fixResult, 'qa_fixing');
-
-        if (fixResult.outcome === 'cancelled') {
-          return { success: false, error: 'Build cancelled' };
-        }
-
-        if (fixResult.outcome === 'error' || fixResult.outcome === 'auth_failure' || fixResult.outcome === 'rate_limited') {
-          return { success: false, error: fixResult.error?.message ?? 'QA fix session failed' };
-        }
-
        this.markPhaseCompleted('qa_fixing');

        // Delete qa_report.md before re-review so the reviewer writes a clean verdict.
@@ -717,26 +684,6 @@ export class BuildOrchestrator extends EventEmitter {
    }
  }

-  /**
-   * Check if any coding work has actually been performed.
-   * Uses task_logs.json as evidence — if the coding phase has entries,
-   * real work was done. If not, the subtask statuses are from the planner.
-   */
-  private async hasCodingEvidence(): Promise<boolean> {
-    const taskLogsPath = join(this.config.specDir, 'task_logs.json');
-    try {
-      const raw = await readFile(taskLogsPath, 'utf-8');
-      const logs = JSON.parse(raw);
-      // Check if coding phase has any entries
-      if (logs?.phases?.coding?.entries?.length > 0) return true;
-      if (logs?.phases?.coding?.status === 'completed') return true;
-      return false;
-    } catch {
-      // No task_logs.json or invalid — no coding evidence
-      return false;
-    }
-  }
-
  /**
   * Check if all subtasks in the implementation plan are completed.
   */
@@ -255,10 +255,6 @@ export class QALoop extends EventEmitter {
          return this.outcome(false, iteration, Date.now() - startTime, 'cancelled');
        }

-        if (reviewResult.outcome === 'rate_limited') {
-          return this.outcome(false, iteration, Date.now() - startTime, 'error', reviewResult.error?.message ?? 'Rate limited during QA review');
-        }
-
        // Read QA signoff from implementation_plan.json
        const signoff = await this.readQASignoff();
        const status = this.resolveQAStatus(signoff);
@@ -322,7 +318,7 @@ export class QALoop extends EventEmitter {
            return this.outcome(false, iteration, Date.now() - startTime, 'cancelled');
          }

-          if (fixResult.outcome === 'error' || fixResult.outcome === 'auth_failure' || fixResult.outcome === 'rate_limited') {
+          if (fixResult.outcome === 'error' || fixResult.outcome === 'auth_failure') {
            this.emitTyped('log', `Fixer error: ${fixResult.error?.message ?? 'unknown'}`);
            await this.writeReports('max_iterations');
            return this.outcome(false, iteration, Date.now() - startTime, 'error', fixResult.error?.message);
@@ -553,7 +553,7 @@ export class SpecOrchestrator extends EventEmitter {
      errors.push(errorMsg);

      // Non-retryable errors
-      if (result.outcome === 'auth_failure' || result.outcome === 'rate_limited') {
+      if (result.outcome === 'auth_failure') {
        return { phase, success: false, errors, retries: attempt };
      }

@@ -1,166 +0,0 @@
-/**
- * Auto-Swap Middleware
- * ====================
- *
- * AI SDK LanguageModel middleware that intercepts rate limit errors (429)
- * and automatically retries with the next available account from the
- * global priority queue.
- *
- * Applied via wrapLanguageModel() in createSimpleClient() and createAgentClient(),
- * giving auto-swap to ALL runners without per-runner changes.
- */
-
-import { wrapLanguageModel } from 'ai';
-import type { LanguageModelMiddleware, LanguageModel } from 'ai';
-import type { LanguageModelV3 } from '@ai-sdk/provider';
-import { resolveAuthFromQueue } from '../auth/resolver';
-import { createProvider } from './factory';
-import type { QueueResolvedAuth } from '../auth/types';
-import type { ProviderAccount } from '../../../shared/types/provider-account';
-import { isRateLimitError } from '../session/error-classifier';
-import { extractWaitDuration, formatWaitDuration, sleepWithAbort } from '../session/rate-limit-wait';
-
-/** Details emitted when the middleware swaps to a different account. */
-export interface AutoSwapEvent {
-  fromAccountId: string;
-  fromAccountName: string;
-  toAccountId: string;
-  toAccountName: string;
-}
-
-interface AutoSwapContext {
-  queueAuth: QueueResolvedAuth;
-  queue: ProviderAccount[];
-  requestedModel: string;
-  /** Called after a successful swap so the UI can reflect the change. */
-  onSwap?: (event: AutoSwapEvent) => void;
-}
-
-/**
- * Shared rate-limit recovery logic for wrapGenerate and wrapStream.
- *
- * On a 429 error:
- * 1. Try swapping to another account in the queue.
- * 2. If no swap target, wait for the session rate limit to reset (null = weekly limit, rethrow).
- * 3. Retry with `retry` (original model) or `retryOnNew` (new model, needs params).
- */
-async function handleRateLimit<T>(
-  error: unknown,
-  ctx: AutoSwapContext,
-  swappedRef: { value: boolean },
-  retry: () => PromiseLike<T>,
-  retryOnNew: (newModel: LanguageModelV3) => PromiseLike<T>,
-  signal?: AbortSignal,
-): Promise<T> {
-  if (swappedRef.value) {
-    console.log('[AutoSwap] Already swapped once this call — not retrying again (prevents A→B→A loop)');
-    throw error;
-  }
-  if (!isRateLimitError(error)) {
-    console.log('[AutoSwap] Error is not a rate limit — passing through:', error instanceof Error ? error.message : String(error));
-    throw error;
-  }
-
-  swappedRef.value = true;
-  console.log('[AutoSwap] 🔴 Rate limit hit on account:', ctx.queueAuth.accountId, '| model:', ctx.requestedModel);
-  console.log('[AutoSwap] Queue has', ctx.queue.length, 'accounts. Excluding current, looking for swap target...');
-
-  const newAuth = await resolveAuthFromQueue(ctx.requestedModel, ctx.queue, {
-    excludeAccountIds: [ctx.queueAuth.accountId],
-  });
-
-  if (!newAuth) {
-    // No swap target — wait for session rate limit reset
-    console.log('[AutoSwap] No swap target available — all other accounts excluded or unavailable');
-    const waitInfo = extractWaitDuration(error);
-    if (!waitInfo) {
-      console.log('[AutoSwap] Cannot extract wait duration (weekly limit?) — giving up');
-      throw error;
-    }
-    console.log('[AutoSwap] Waiting', formatWaitDuration(waitInfo.waitMs), 'for rate limit reset (type:', waitInfo.limitType + ')');
-    await sleepWithAbort(waitInfo.waitMs, signal);
-    console.log('[AutoSwap] Wait complete — retrying with original account');
-    return retry();
-  }
-
-  // Notify the UI about the swap
-  const fromAccount = ctx.queue.find((a) => a.id === ctx.queueAuth.accountId);
-  const toAccount = ctx.queue.find((a) => a.id === newAuth.accountId);
-  const fromName = fromAccount?.name ?? ctx.queueAuth.accountId;
-  const toName = toAccount?.name ?? newAuth.accountId;
-  console.log('[AutoSwap] ✅ SWAPPING:', fromName, '→', toName, '| provider:', newAuth.resolvedProvider, '| model:', newAuth.resolvedModelId);
-
-  ctx.onSwap?.({
-    fromAccountId: ctx.queueAuth.accountId,
-    fromAccountName: fromName,
-    toAccountId: newAuth.accountId,
-    toAccountName: toName,
-  });
-
-  const newModel = createProvider({
-    config: {
-      provider: newAuth.resolvedProvider,
-      apiKey: newAuth.apiKey,
-      baseURL: newAuth.baseURL,
-      headers: newAuth.headers,
-      oauthTokenFilePath: newAuth.oauthTokenFilePath,
-    },
-    modelId: newAuth.resolvedModelId,
-  }) as LanguageModelV3;
-
-  console.log('[AutoSwap] New model created — retrying request on', toName);
-  return retryOnNew(newModel);
-}
-
-function createAutoSwapMiddleware(ctx: AutoSwapContext): LanguageModelMiddleware {
-  const swapped = { value: false }; // Only swap once per model instance
-
-  return {
-    specificationVersion: 'v3' as const,
-    wrapGenerate: async ({ doGenerate, params }) => {
-      // Reset per-call so each generateText() gets its own swap opportunity.
-      // The flag only prevents infinite A→B→A loops within a single call.
-      swapped.value = false;
-      try {
-        return await doGenerate();
-      } catch (error) {
-        console.log('[AutoSwap] wrapGenerate caught error — entering handleRateLimit');
-        return handleRateLimit(error, ctx, swapped, doGenerate, (m) => m.doGenerate(params), params.abortSignal);
-      }
-    },
-    wrapStream: async ({ doStream, params }) => {
-      swapped.value = false;
-      try {
-        return await doStream();
-      } catch (error) {
-        console.log('[AutoSwap] wrapStream caught error — entering handleRateLimit');
-        return handleRateLimit(error, ctx, swapped, doStream, (m) => m.doStream(params), params.abortSignal);
-      }
-    },
-  };
-}
-
-/**
- * Wrap a model with auto-swap middleware if queue context is available.
- * When a 429 error occurs, the middleware resolves the next available
- * account and retries with a new model — transparent to the caller.
- *
- * No-op if queue has fewer than 2 accounts (nothing to swap to).
- */
-export function wrapWithAutoSwap(
-  model: LanguageModel,
-  queueAuth: QueueResolvedAuth | null,
-  queue: ProviderAccount[],
-  requestedModel: string,
-  onSwap?: (event: AutoSwapEvent) => void,
-): LanguageModel {
-  if (!queueAuth || queue.length < 2) {
-    console.log('[AutoSwap] Middleware NOT applied — queue has', queue.length, 'account(s) (need ≥2 for swap)');
-    return model;
-  }
-  console.log('[AutoSwap] Middleware applied — account:', queueAuth.accountId, '| model:', requestedModel, '| queue size:', queue.length);
-  return wrapLanguageModel({
-    model: model as LanguageModelV3,
-    middleware: createAutoSwapMiddleware({ queueAuth, queue, requestedModel, onSwap }),
-  });
-}
@@ -0,0 +1,231 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// =============================================================================
+// Mocks — must be declared before any imports that use them
+// =============================================================================
+
+const mockGenerateText = vi.fn();
+
+vi.mock('ai', () => ({
+  generateText: (...args: unknown[]) => mockGenerateText(...args),
+}));
+
+const mockCreateSimpleClient = vi.fn();
+
+vi.mock('../../client/factory', () => ({
+  createSimpleClient: (...args: unknown[]) => mockCreateSimpleClient(...args),
+}));
+
+// =============================================================================
+// Import after mocking
+// =============================================================================
+
+import { generateChangelog } from '../changelog';
+import type { ChangelogConfig } from '../changelog';
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/** A fake model object used by the mock client */
+const fakeModel = { modelId: 'claude-haiku-test' };
+
+function makeMockClient(systemPrompt = 'You are a technical writer.') {
+  return { model: fakeModel, systemPrompt };
+}
+
+function baseConfig(overrides: Partial<ChangelogConfig> = {}): ChangelogConfig {
+  return {
+    projectName: 'TestProject',
+    version: '1.0.0',
+    sourceMode: 'tasks',
+    tasks: [
+      { title: 'Add dark mode', description: 'Implemented dark mode toggle', category: 'feature' },
+    ],
+    ...overrides,
+  };
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe('generateChangelog', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCreateSimpleClient.mockResolvedValue(makeMockClient());
+  });
+
+  // ---------------------------------------------------------------------------
+  // Successful generation
+  // ---------------------------------------------------------------------------
+
+  it('returns success with trimmed text when LLM responds', async () => {
+    mockGenerateText.mockResolvedValue({ text: '  ## [1.0.0]\n\n### Added\n- Dark mode\n  ' });
+
+    const result = await generateChangelog(baseConfig());
+
+    expect(result.success).toBe(true);
+    expect(result.text).toBe('## [1.0.0]\n\n### Added\n- Dark mode');
+    expect(result.error).toBeUndefined();
+  });
+
+  it('passes project name and version in the prompt to createSimpleClient', async () => {
+    mockGenerateText.mockResolvedValue({ text: '## [2.0.0]' });
+
+    await generateChangelog(baseConfig({ projectName: 'MyApp', version: '2.0.0' }));
+
+    // createSimpleClient receives system-level configuration
+    expect(mockCreateSimpleClient).toHaveBeenCalledOnce();
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs).toHaveProperty('modelShorthand');
+    expect(clientArgs).toHaveProperty('thinkingLevel');
+  });
+
+  it('passes model and systemPrompt from client to generateText', async () => {
+    mockGenerateText.mockResolvedValue({ text: '## [1.0.0]' });
+
+    await generateChangelog(baseConfig());
+
+    expect(mockGenerateText).toHaveBeenCalledOnce();
+    const callArgs = mockGenerateText.mock.calls[0][0];
+    expect(callArgs.model).toBe(fakeModel);
+    expect(callArgs.system).toBe('You are a technical writer.');
+    expect(callArgs.prompt).toContain('TestProject');
+    expect(callArgs.prompt).toContain('1.0.0');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Task mode — prompt content
+  // ---------------------------------------------------------------------------
+
+  it('includes task titles and categories in prompt for tasks mode', async () => {
+    mockGenerateText.mockResolvedValue({ text: '## [1.0.0]' });
+
+    const config = baseConfig({
+      tasks: [
+        { title: 'My feature', description: 'desc', category: 'feature', issueNumber: 42 },
+      ],
+    });
+    await generateChangelog(config);
+
+    const prompt = mockGenerateText.mock.calls[0][0].prompt as string;
+    expect(prompt).toContain('My feature');
+    expect(prompt).toContain('feature');
+    expect(prompt).toContain('#42');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Git history / branch-diff modes
+  // ---------------------------------------------------------------------------
+
+  it('includes commit messages in prompt for git-history mode', async () => {
+    mockGenerateText.mockResolvedValue({ text: '## [1.0.0]' });
+
+    await generateChangelog(
+      baseConfig({ sourceMode: 'git-history', commits: 'feat: add login\nfix: bug #5' }),
+    );
+
+    const prompt = mockGenerateText.mock.calls[0][0].prompt as string;
+    expect(prompt).toContain('feat: add login');
+  });
+
+  it('truncates commits to 5000 chars', async () => {
+    mockGenerateText.mockResolvedValue({ text: '## [1.0.0]' });
+    const longCommits = 'x'.repeat(10_000);
+
+    await generateChangelog(baseConfig({ sourceMode: 'branch-diff', commits: longCommits }));
+
+    const prompt = mockGenerateText.mock.calls[0][0].prompt as string;
+    // The 'x'.repeat(10000) block should be truncated — prompt must not exceed
+    // 5000 'x' chars plus surrounding text
+    const xCount = (prompt.match(/x/g) ?? []).length;
+    expect(xCount).toBeLessThanOrEqual(5000);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Previous changelog style reference
+  // ---------------------------------------------------------------------------
+
+  it('includes previousChangelog when provided', async () => {
+    mockGenerateText.mockResolvedValue({ text: '## [1.0.0]' });
+
+    await generateChangelog(
+      baseConfig({ previousChangelog: '## [0.9.0]\n\n### Added\n- Old feature' }),
+    );
+
+    const prompt = mockGenerateText.mock.calls[0][0].prompt as string;
+    expect(prompt).toContain('Previous Changelog');
+    expect(prompt).toContain('0.9.0');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Default model / thinking level
+  // ---------------------------------------------------------------------------
+
+  it('uses sonnet model and low thinking level by default', async () => {
+    mockGenerateText.mockResolvedValue({ text: '## [1.0.0]' });
+
+    await generateChangelog(baseConfig());
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.modelShorthand).toBe('sonnet');
+    expect(clientArgs.thinkingLevel).toBe('low');
+  });
+
+  it('accepts custom modelShorthand and thinkingLevel', async () => {
+    mockGenerateText.mockResolvedValue({ text: '## [1.0.0]' });
+
+    await generateChangelog(baseConfig({ modelShorthand: 'haiku', thinkingLevel: 'high' }));
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.modelShorthand).toBe('haiku');
+    expect(clientArgs.thinkingLevel).toBe('high');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Empty response handling
+  // ---------------------------------------------------------------------------
+
+  it('returns failure when LLM returns empty text', async () => {
+    mockGenerateText.mockResolvedValue({ text: '   ' });
+
+    const result = await generateChangelog(baseConfig());
+
+    expect(result.success).toBe(false);
+    expect(result.text).toBe('');
+    expect(result.error).toBe('Empty response from AI');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Error handling
+  // ---------------------------------------------------------------------------
+
+  it('returns failure with error message when generateText throws', async () => {
+    mockGenerateText.mockRejectedValue(new Error('Rate limit exceeded'));
+
+    const result = await generateChangelog(baseConfig());
+
+    expect(result.success).toBe(false);
+    expect(result.text).toBe('');
+    expect(result.error).toBe('Rate limit exceeded');
+  });
+
+  it('returns failure with string coercion when non-Error is thrown', async () => {
+    mockGenerateText.mockRejectedValue('timeout');
+
+    const result = await generateChangelog(baseConfig());
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('timeout');
+  });
+
+  it('returns failure when createSimpleClient throws', async () => {
+    mockCreateSimpleClient.mockRejectedValue(new Error('No auth available'));
+
+    const result = await generateChangelog(baseConfig());
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('No auth available');
+  });
+});
@@ -0,0 +1,230 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// =============================================================================
+// Mocks — must be declared before any imports that use them
+// =============================================================================
+
+const mockGenerateText = vi.fn();
+
+vi.mock('ai', () => ({
+  generateText: (...args: unknown[]) => mockGenerateText(...args),
+}));
+
+const mockCreateSimpleClient = vi.fn();
+
+vi.mock('../../client/factory', () => ({
+  createSimpleClient: (...args: unknown[]) => mockCreateSimpleClient(...args),
+}));
+
+// Mock filesystem access so tests are hermetic
+const mockExistsSync = vi.fn();
+const mockReadFileSync = vi.fn();
+
+vi.mock('node:fs', () => ({
+  existsSync: (...args: unknown[]) => mockExistsSync(...args),
+  readFileSync: (...args: unknown[]) => mockReadFileSync(...args),
+}));
+
+// json-repair is used by the commit-message runner for safeParseJson
+vi.mock('../../../utils/json-repair', () => ({
+  safeParseJson: (text: string) => {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  },
+}));
+
+// =============================================================================
+// Import after mocking
+// =============================================================================
+
+import { generateCommitMessage } from '../commit-message';
+import type { CommitMessageConfig } from '../commit-message';
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+const fakeModel = { modelId: 'claude-haiku-test' };
+
+function makeMockClient(systemPrompt = 'You are a Git expert.') {
+  return { model: fakeModel, systemPrompt };
+}
+
+function baseConfig(overrides: Partial<CommitMessageConfig> = {}): CommitMessageConfig {
+  return {
+    projectDir: '/project',
+    specName: '001-add-feature',
+    diffSummary: '+5 -2 src/app.ts',
+    filesChanged: ['src/app.ts', 'src/utils.ts'],
+    ...overrides,
+  };
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe('generateCommitMessage', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCreateSimpleClient.mockResolvedValue(makeMockClient());
+    // By default, spec directory does not exist
+    mockExistsSync.mockReturnValue(false);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Successful generation
+  // ---------------------------------------------------------------------------
+
+  it('returns trimmed AI-generated commit message on success', async () => {
+    mockGenerateText.mockResolvedValue({
+      text: '  feat(app): add authentication flow\n\nImplemented OAuth2.\n  ',
+    });
+
+    const result = await generateCommitMessage(baseConfig());
+
+    expect(result).toBe('feat(app): add authentication flow\n\nImplemented OAuth2.');
+  });
+
+  it('passes model and systemPrompt from client to generateText', async () => {
+    mockGenerateText.mockResolvedValue({ text: 'feat: something' });
+
+    await generateCommitMessage(baseConfig());
+
+    expect(mockGenerateText).toHaveBeenCalledOnce();
+    const callArgs = mockGenerateText.mock.calls[0][0];
+    expect(callArgs.model).toBe(fakeModel);
+    expect(callArgs.system).toBe('You are a Git expert.');
+  });
+
+  it('includes diffSummary in the prompt sent to generateText', async () => {
+    mockGenerateText.mockResolvedValue({ text: 'fix: resolve bug' });
+
+    await generateCommitMessage(baseConfig({ diffSummary: 'removed null check in auth.ts' }));
+
+    const prompt = mockGenerateText.mock.calls[0][0].prompt as string;
+    expect(prompt).toContain('removed null check in auth.ts');
+  });
+
+  it('includes filesChanged in the prompt', async () => {
+    mockGenerateText.mockResolvedValue({ text: 'refactor: split utilities' });
+
+    await generateCommitMessage(
+      baseConfig({ filesChanged: ['src/auth.ts', 'src/utils.ts', 'src/index.ts'] }),
+    );
+
+    const prompt = mockGenerateText.mock.calls[0][0].prompt as string;
+    expect(prompt).toContain('src/auth.ts');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Default model / thinking level
+  // ---------------------------------------------------------------------------
+
+  it('uses haiku model and low thinking level by default', async () => {
+    mockGenerateText.mockResolvedValue({ text: 'chore: update deps' });
+
+    await generateCommitMessage(baseConfig());
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.modelShorthand).toBe('haiku');
+    expect(clientArgs.thinkingLevel).toBe('low');
+  });
+
+  it('accepts custom modelShorthand and thinkingLevel', async () => {
+    mockGenerateText.mockResolvedValue({ text: 'feat: new endpoint' });
+
+    await generateCommitMessage(baseConfig({ modelShorthand: 'sonnet', thinkingLevel: 'medium' }));
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.modelShorthand).toBe('sonnet');
+    expect(clientArgs.thinkingLevel).toBe('medium');
+  });
+
+  // ---------------------------------------------------------------------------
+  // GitHub issue handling
+  // ---------------------------------------------------------------------------
+
+  it('includes Fixes reference when githubIssue is provided', async () => {
+    mockGenerateText.mockResolvedValue({ text: 'fix: null pointer\n\nFixes #99' });
+
+    const result = await generateCommitMessage(baseConfig({ githubIssue: 99 }));
+
+    expect(result).toContain('Fixes #99');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Spec file context
+  // ---------------------------------------------------------------------------
+
+  it('reads spec.md for title when spec directory exists', async () => {
+    // Spec directory at .auto-claude/specs/001-add-feature
+    mockExistsSync.mockImplementation((p: string) => {
+      const normalized = p.replace(/\\/g, '/');
+      if (normalized.includes('specs/001-add-feature')) return true;
+      return false;
+    });
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p.includes('spec.md')) return '# Add OAuth Feature\n\n## Overview\nFull OAuth2 support.';
+      return '{}';
+    });
+    mockGenerateText.mockResolvedValue({ text: 'feat(auth): add OAuth2' });
+
+    const result = await generateCommitMessage(baseConfig());
+
+    // Result should come from LLM (title from spec was available for context)
+    expect(result).toBe('feat(auth): add OAuth2');
+    const prompt = mockGenerateText.mock.calls[0][0].prompt as string;
+    expect(prompt).toContain('Add OAuth Feature');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Fallback message
+  // ---------------------------------------------------------------------------
+
+  it('returns fallback message when generateText throws', async () => {
+    mockGenerateText.mockRejectedValue(new Error('Network error'));
+
+    const result = await generateCommitMessage(baseConfig({ specName: '001-add-feature' }));
+
+    // Fallback format: "<type>: <title or specName>"
+    expect(result).toMatch(/^(feat|fix|refactor|docs|test|perf|chore|style|ci|build):/);
+    expect(typeof result).toBe('string');
+    expect(result.length).toBeGreaterThan(0);
+  });
+
+  it('includes Fixes in fallback when githubIssue provided and LLM fails', async () => {
+    mockGenerateText.mockRejectedValue(new Error('Timeout'));
+
+    const result = await generateCommitMessage(baseConfig({ githubIssue: 77 }));
+
+    expect(result).toContain('Fixes #77');
+  });
+
+  it('returns fallback when LLM returns empty text', async () => {
+    mockGenerateText.mockResolvedValue({ text: '   ' });
+
+    const result = await generateCommitMessage(baseConfig());
+
+    // Should fall through to fallback
+    expect(typeof result).toBe('string');
+    expect(result.length).toBeGreaterThan(0);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Large filesChanged list
+  // ---------------------------------------------------------------------------
+
+  it('truncates filesChanged list when more than 20 files', async () => {
+    mockGenerateText.mockResolvedValue({ text: 'refactor: big cleanup' });
+
+    const manyFiles = Array.from({ length: 30 }, (_, i) => `src/file${i}.ts`);
+    await generateCommitMessage(baseConfig({ filesChanged: manyFiles }));
+
+    const prompt = mockGenerateText.mock.calls[0][0].prompt as string;
+    expect(prompt).toContain('and 10 more files');
+  });
+});
@@ -0,0 +1,306 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// =============================================================================
+// Mocks — must be declared before any imports that use them
+// =============================================================================
+
+const mockStreamText = vi.fn();
+
+vi.mock('ai', () => ({
+  streamText: (...args: unknown[]) => mockStreamText(...args),
+  stepCountIs: (n: number) => ({ type: 'stepCount', count: n }),
+}));
+
+const mockCreateSimpleClient = vi.fn();
+
+vi.mock('../../client/factory', () => ({
+  createSimpleClient: (...args: unknown[]) => mockCreateSimpleClient(...args),
+}));
+
+// Mock filesystem: prompt files exist by default
+const mockExistsSync = vi.fn();
+const mockReadFileSync = vi.fn();
+
+vi.mock('node:fs', () => ({
+  existsSync: (...args: unknown[]) => mockExistsSync(...args),
+  readFileSync: (...args: unknown[]) => mockReadFileSync(...args),
+}));
+
+// Mock the tool registry so we don't need real tool initialization
+vi.mock('../../tools/build-registry', () => ({
+  buildToolRegistry: () => ({
+    getToolsForAgent: vi.fn().mockReturnValue({}),
+  }),
+}));
+
+// =============================================================================
+// Import after mocking
+// =============================================================================
+
+import { runIdeation, IDEATION_TYPES, IDEATION_TYPE_LABELS } from '../ideation';
+import type { IdeationConfig, IdeationStreamEvent } from '../ideation';
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+const fakeModel = { modelId: 'claude-sonnet-test' };
+
+function makeMockClient() {
+  return {
+    model: fakeModel,
+    systemPrompt: '',
+    tools: {},
+    maxSteps: 30,
+  };
+}
+
+/**
+ * Build an async generator that yields stream parts and then ends.
+ */
+function makeStream(parts: Array<Record<string, unknown>>) {
+  return {
+    fullStream: (async function* () {
+      for (const part of parts) {
+        yield part;
+      }
+    })(),
+  };
+}
+
+function baseConfig(overrides: Partial<IdeationConfig> = {}): IdeationConfig {
+  return {
+    projectDir: '/project',
+    outputDir: '/project/.auto-claude/ideation',
+    promptsDir: '/app/prompts',
+    ideationType: 'code_improvements',
+    ...overrides,
+  };
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe('runIdeation', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCreateSimpleClient.mockResolvedValue(makeMockClient());
+    // Prompt file exists and has content by default
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockReturnValue('Analyze the codebase for improvements.');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Constants
+  // ---------------------------------------------------------------------------
+
+  it('exports all expected IDEATION_TYPES', () => {
+    expect(IDEATION_TYPES).toContain('code_improvements');
+    expect(IDEATION_TYPES).toContain('ui_ux_improvements');
+    expect(IDEATION_TYPES).toContain('documentation_gaps');
+    expect(IDEATION_TYPES).toContain('security_hardening');
+    expect(IDEATION_TYPES).toContain('performance_optimizations');
+    expect(IDEATION_TYPES).toContain('code_quality');
+    expect(IDEATION_TYPES).toHaveLength(6);
+  });
+
+  it('exports human-readable labels for all ideation types', () => {
+    for (const type of IDEATION_TYPES) {
+      expect(IDEATION_TYPE_LABELS[type]).toBeTruthy();
+    }
+  });
+
+  // ---------------------------------------------------------------------------
+  // Successful run
+  // ---------------------------------------------------------------------------
+
+  it('returns success with accumulated text from stream', async () => {
+    mockStreamText.mockReturnValue(
+      makeStream([
+        { type: 'text-delta', text: 'Found ' },
+        { type: 'text-delta', text: '3 improvements.' },
+      ]),
+    );
+
+    const result = await runIdeation(baseConfig());
+
+    expect(result.success).toBe(true);
+    expect(result.text).toBe('Found 3 improvements.');
+    expect(result.error).toBeUndefined();
+  });
+
+  it('calls createSimpleClient with sonnet and medium thinking by default', async () => {
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    await runIdeation(baseConfig());
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.modelShorthand).toBe('sonnet');
+    expect(clientArgs.thinkingLevel).toBe('medium');
+  });
+
+  it('accepts custom modelShorthand and thinkingLevel', async () => {
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    await runIdeation(baseConfig({ modelShorthand: 'haiku', thinkingLevel: 'low' }));
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.modelShorthand).toBe('haiku');
+    expect(clientArgs.thinkingLevel).toBe('low');
+  });
+
+  it('passes tools from client to streamText', async () => {
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    await runIdeation(baseConfig());
+
+    const streamArgs = mockStreamText.mock.calls[0][0];
+    expect(streamArgs).toHaveProperty('tools');
+    expect(streamArgs).toHaveProperty('model');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Stream callbacks
+  // ---------------------------------------------------------------------------
+
+  it('forwards text-delta events to onStream callback', async () => {
+    mockStreamText.mockReturnValue(
+      makeStream([
+        { type: 'text-delta', text: 'hello' },
+        { type: 'text-delta', text: ' world' },
+      ]),
+    );
+
+    const events: IdeationStreamEvent[] = [];
+    await runIdeation(baseConfig(), (e) => events.push(e));
+
+    const textEvents = events.filter((e) => e.type === 'text-delta');
+    expect(textEvents).toHaveLength(2);
+    expect((textEvents[0] as { type: 'text-delta'; text: string }).text).toBe('hello');
+  });
+
+  it('forwards tool-use events from tool-call stream parts', async () => {
+    mockStreamText.mockReturnValue(
+      makeStream([{ type: 'tool-call', toolName: 'Glob', toolCallId: 'c1', input: {} }]),
+    );
+
+    const events: IdeationStreamEvent[] = [];
+    await runIdeation(baseConfig(), (e) => events.push(e));
+
+    const toolEvents = events.filter((e) => e.type === 'tool-use');
+    expect(toolEvents).toHaveLength(1);
+    expect((toolEvents[0] as { type: 'tool-use'; name: string }).name).toBe('Glob');
+  });
+
+  it('forwards error events from stream error parts', async () => {
+    mockStreamText.mockReturnValue(
+      makeStream([{ type: 'error', error: new Error('stream error') }]),
+    );
+
+    const events: IdeationStreamEvent[] = [];
+    await runIdeation(baseConfig(), (e) => events.push(e));
+
+    const errorEvents = events.filter((e) => e.type === 'error');
+    expect(errorEvents).toHaveLength(1);
+    expect((errorEvents[0] as { type: 'error'; error: string }).error).toBe('stream error');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Prompt file not found
+  // ---------------------------------------------------------------------------
+
+  it('returns failure when prompt file does not exist', async () => {
+    mockExistsSync.mockReturnValue(false);
+
+    const result = await runIdeation(baseConfig());
+
+    expect(result.success).toBe(false);
+    expect(result.text).toBe('');
+    expect(result.error).toContain('Prompt not found');
+  });
+
+  it('returns failure when prompt file cannot be read', async () => {
+    mockExistsSync.mockReturnValue(true);
+    mockReadFileSync.mockImplementation(() => {
+      throw new Error('Permission denied');
+    });
+
+    const result = await runIdeation(baseConfig());
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('Permission denied');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Error handling — streamText throws
+  // ---------------------------------------------------------------------------
+
+  it('returns failure when streamText iteration throws', async () => {
+    mockStreamText.mockReturnValue({
+      // biome-ignore lint/correctness/useYield: intentionally throwing before yield to test error path
+      fullStream: (async function* () {
+        throw new Error('API error');
+      })(),
+    });
+
+    const result = await runIdeation(baseConfig());
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('API error');
+  });
+
+  it('emits error event to callback when streamText throws', async () => {
+    mockStreamText.mockReturnValue({
+      // biome-ignore lint/correctness/useYield: intentionally throwing before yield to test error path
+      fullStream: (async function* () {
+        throw new Error('network failure');
+      })(),
+    });
+
+    const events: IdeationStreamEvent[] = [];
+    await runIdeation(baseConfig(), (e) => events.push(e));
+
+    expect(events.some((e) => e.type === 'error')).toBe(true);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Ideation type routing — checks the correct prompt file is loaded
+  // ---------------------------------------------------------------------------
+
+  it.each(IDEATION_TYPES)('loads the correct prompt file for ideation type: %s', async (type) => {
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    await runIdeation(baseConfig({ ideationType: type }));
+
+    // The prompt file for each type should have been checked for existence
+    expect(mockExistsSync).toHaveBeenCalledWith(expect.stringContaining('.md'));
+  });
+
+  // ---------------------------------------------------------------------------
+  // Context injection
+  // ---------------------------------------------------------------------------
+
+  it('includes projectDir and outputDir in the prompt passed to streamText', async () => {
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    await runIdeation(
+      baseConfig({ projectDir: '/my/project', outputDir: '/my/project/.auto-claude/ideation' }),
+    );
+
+    // The system prompt passed to streamText should contain the project dir
+    const streamArgs = mockStreamText.mock.calls[0][0];
+    const systemPrompt = streamArgs.system as string;
+    expect(systemPrompt).toContain('/my/project');
+  });
+
+  it('injects maxIdeasPerType into the context', async () => {
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    await runIdeation(baseConfig({ maxIdeasPerType: 10 }));
+
+    const streamArgs = mockStreamText.mock.calls[0][0];
+    const systemPrompt = streamArgs.system as string;
+    expect(systemPrompt).toContain('10');
+  });
+});
@@ -0,0 +1,300 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// =============================================================================
+// Mocks — must be declared before any imports that use them
+// =============================================================================
+
+const mockGenerateText = vi.fn();
+
+vi.mock('ai', () => ({
+  generateText: (...args: unknown[]) => mockGenerateText(...args),
+  Output: {
+    object: ({ schema }: { schema: unknown }) => ({ type: 'object', schema }),
+  },
+}));
+
+const mockCreateSimpleClient = vi.fn();
+
+vi.mock('../../client/factory', () => ({
+  createSimpleClient: (...args: unknown[]) => mockCreateSimpleClient(...args),
+}));
+
+// Mock schema/structured-output so we don't need the actual implementation
+vi.mock('../../schema/structured-output', () => ({
+  parseLLMJson: vi.fn().mockReturnValue(null),
+}));
+
+// Mock the Zod schemas used by the runner
+vi.mock('../../schema/insight-extractor', () => ({
+  ExtractedInsightsSchema: {},
+}));
+
+vi.mock('../../schema/output', () => ({
+  ExtractedInsightsOutputSchema: {},
+}));
+
+// =============================================================================
+// Import after mocking
+// =============================================================================
+
+import { extractSessionInsights } from '../insight-extractor';
+import type { InsightExtractionConfig } from '../insight-extractor';
+import { parseLLMJson } from '../../schema/structured-output';
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+const fakeModel = { modelId: 'claude-haiku-test' };
+
+function makeMockClient() {
+  return { model: fakeModel, systemPrompt: 'You are an expert code analyst.' };
+}
+
+function makeValidOutput() {
+  return {
+    file_insights: [{ file: 'src/app.ts', insight: 'Uses singleton pattern', category: 'pattern' }],
+    patterns_discovered: ['Singleton pattern used'],
+    gotchas_discovered: ['Must call init() before use'],
+    approach_outcome: {
+      success: true,
+      approach_used: 'Direct refactor',
+      why_it_worked: 'Simplified the module',
+      why_it_failed: null,
+      alternatives_tried: [],
+    },
+    recommendations: ['Add unit tests for singleton'],
+  };
+}
+
+function baseConfig(overrides: Partial<InsightExtractionConfig> = {}): InsightExtractionConfig {
+  return {
+    subtaskId: 'sub-001',
+    subtaskDescription: 'Refactor authentication module',
+    sessionNum: 1,
+    success: true,
+    diff: 'diff --git a/src/auth.ts b/src/auth.ts\n+  return token;',
+    changedFiles: ['src/auth.ts'],
+    commitMessages: 'refactor: simplify auth module',
+    attemptHistory: [],
+    ...overrides,
+  };
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe('extractSessionInsights', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCreateSimpleClient.mockResolvedValue(makeMockClient());
+    // By default, result.output contains the structured data (constrained decoding path)
+    mockGenerateText.mockResolvedValue({
+      output: makeValidOutput(),
+      text: '',
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // Successful extraction via result.output (constrained decoding)
+  // ---------------------------------------------------------------------------
+
+  it('returns extracted insights from result.output when available', async () => {
+    const result = await extractSessionInsights(baseConfig());
+
+    expect(result.subtask_id).toBe('sub-001');
+    expect(result.session_num).toBe(1);
+    expect(result.success).toBe(true);
+    expect(result.changed_files).toEqual(['src/auth.ts']);
+    expect(result.file_insights).toHaveLength(1);
+    expect(result.file_insights[0].file).toBe('src/app.ts');
+    expect(result.patterns_discovered).toContain('Singleton pattern used');
+    expect(result.gotchas_discovered).toContain('Must call init() before use');
+    expect(result.recommendations).toContain('Add unit tests for singleton');
+  });
+
+  it('populates approach_outcome from result.output', async () => {
+    const result = await extractSessionInsights(baseConfig());
+
+    expect(result.approach_outcome.success).toBe(true);
+    expect(result.approach_outcome.approach_used).toBe('Direct refactor');
+    expect(result.approach_outcome.why_it_worked).toBe('Simplified the module');
+    expect(result.approach_outcome.why_it_failed).toBeNull();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Fallback to parseLLMJson when result.output is absent
+  // ---------------------------------------------------------------------------
+
+  it('falls back to parseLLMJson when result.output is null/undefined', async () => {
+    mockGenerateText.mockResolvedValue({
+      output: null,
+      text: JSON.stringify({
+        file_insights: [{ file: 'src/login.ts', insight: 'Heavy coupling' }],
+        patterns_discovered: ['MVC'],
+        gotchas_discovered: [],
+        approach_outcome: {
+          success: false,
+          approach_used: 'monkey-patch',
+          why_it_worked: null,
+          why_it_failed: 'Too hacky',
+          alternatives_tried: [],
+        },
+        recommendations: [],
+      }),
+    });
+
+    const parsedData = {
+      file_insights: [{ file: 'src/login.ts', insight: 'Heavy coupling' }],
+      patterns_discovered: ['MVC'],
+      gotchas_discovered: [],
+      approach_outcome: {
+        success: false,
+        approach_used: 'monkey-patch',
+        why_it_worked: null,
+        why_it_failed: 'Too hacky',
+        alternatives_tried: [],
+      },
+      recommendations: [],
+    };
+
+    vi.mocked(parseLLMJson).mockReturnValueOnce(parsedData as unknown as ReturnType<typeof parseLLMJson>);
+
+    const result = await extractSessionInsights(baseConfig({ success: false }));
+
+    expect(result.file_insights[0].file).toBe('src/login.ts');
+    expect(result.patterns_discovered).toContain('MVC');
+    expect(result.approach_outcome.why_it_failed).toBe('Too hacky');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Generic fallback when both paths fail
+  // ---------------------------------------------------------------------------
+
+  it('returns generic insights when result.output is null and parseLLMJson returns null', async () => {
+    mockGenerateText.mockResolvedValue({ output: null, text: 'not valid json' });
+    vi.mocked(parseLLMJson).mockReturnValueOnce(null);
+
+    const result = await extractSessionInsights(baseConfig({ subtaskId: 'sub-fallback', success: false }));
+
+    expect(result.subtask_id).toBe('sub-fallback');
+    expect(result.success).toBe(false);
+    expect(result.file_insights).toEqual([]);
+    expect(result.patterns_discovered).toEqual([]);
+    expect(result.gotchas_discovered).toEqual([]);
+    expect(result.recommendations).toEqual([]);
+    expect(result.approach_outcome.approach_used).toContain('sub-fallback');
+  });
+
+  it('returns generic insights when generateText throws', async () => {
+    mockGenerateText.mockRejectedValue(new Error('API unavailable'));
+
+    const result = await extractSessionInsights(baseConfig({ subtaskId: 'sub-error', success: true }));
+
+    expect(result.subtask_id).toBe('sub-error');
+    expect(result.success).toBe(true);
+    expect(result.file_insights).toEqual([]);
+  });
+
+  it('returns generic insights when createSimpleClient throws', async () => {
+    mockCreateSimpleClient.mockRejectedValue(new Error('No credentials'));
+
+    const result = await extractSessionInsights(baseConfig());
+
+    expect(result.subtask_id).toBe('sub-001');
+    expect(result.file_insights).toEqual([]);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Never throws
+  // ---------------------------------------------------------------------------
+
+  it('never throws — always returns a valid InsightResult', async () => {
+    mockGenerateText.mockRejectedValue(new Error('catastrophic failure'));
+
+    await expect(extractSessionInsights(baseConfig())).resolves.toBeDefined();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Client configuration
+  // ---------------------------------------------------------------------------
+
+  it('uses haiku model and low thinking level by default', async () => {
+    await extractSessionInsights(baseConfig());
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.modelShorthand).toBe('haiku');
+    expect(clientArgs.thinkingLevel).toBe('low');
+  });
+
+  it('accepts custom modelShorthand and thinkingLevel', async () => {
+    await extractSessionInsights(
+      baseConfig({ modelShorthand: 'sonnet', thinkingLevel: 'medium' }),
+    );
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.modelShorthand).toBe('sonnet');
+    expect(clientArgs.thinkingLevel).toBe('medium');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Prompt content validation
+  // ---------------------------------------------------------------------------
+
+  it('includes subtaskId and description in the prompt', async () => {
+    await extractSessionInsights(
+      baseConfig({
+        subtaskId: 'my-task-42',
+        subtaskDescription: 'Fix login regression',
+      }),
+    );
+
+    const callArgs = mockGenerateText.mock.calls[0][0];
+    expect(callArgs.prompt).toContain('my-task-42');
+    expect(callArgs.prompt).toContain('Fix login regression');
+  });
+
+  it('truncates diff when it exceeds 15000 chars', async () => {
+    const longDiff = '+' + 'a'.repeat(20_000);
+
+    await extractSessionInsights(baseConfig({ diff: longDiff }));
+
+    const callArgs = mockGenerateText.mock.calls[0][0];
+    const prompt = callArgs.prompt as string;
+    // The prompt must mention truncation and not contain all 20k chars of diff
+    expect(prompt).toContain('truncated');
+  });
+
+  it('includes changed files in the prompt', async () => {
+    await extractSessionInsights(
+      baseConfig({ changedFiles: ['src/login.ts', 'src/session.ts'] }),
+    );
+
+    const callArgs = mockGenerateText.mock.calls[0][0];
+    expect(callArgs.prompt).toContain('src/login.ts');
+  });
+
+  it('includes attempt history in the prompt when provided', async () => {
+    await extractSessionInsights(
+      baseConfig({
+        attemptHistory: [
+          { success: false, approach: 'patch method', error: 'type mismatch' },
+          { success: true, approach: 'full rewrite' },
+        ],
+      }),
+    );
+
+    const callArgs = mockGenerateText.mock.calls[0][0];
+    expect(callArgs.prompt).toContain('patch method');
+    expect(callArgs.prompt).toContain('full rewrite');
+  });
+
+  it('passes output schema configuration to generateText', async () => {
+    await extractSessionInsights(baseConfig());
+
+    const callArgs = mockGenerateText.mock.calls[0][0];
+    // The output key should be set (from Output.object())
+    expect(callArgs).toHaveProperty('output');
+  });
+});
@@ -0,0 +1,382 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// =============================================================================
+// Mocks — must be declared before any imports that use them
+// =============================================================================
+
+const mockStreamText = vi.fn();
+
+vi.mock('ai', () => ({
+  streamText: (...args: unknown[]) => mockStreamText(...args),
+  stepCountIs: (n: number) => ({ type: 'stepCount', count: n }),
+}));
+
+const mockCreateSimpleClient = vi.fn();
+
+vi.mock('../../client/factory', () => ({
+  createSimpleClient: (...args: unknown[]) => mockCreateSimpleClient(...args),
+}));
+
+// Filesystem mocks — project context files are absent by default
+const mockExistsSync = vi.fn().mockReturnValue(false);
+const mockReadFileSync = vi.fn();
+const mockReaddirSync = vi.fn().mockReturnValue([]);
+
+vi.mock('node:fs', () => ({
+  existsSync: (...args: unknown[]) => mockExistsSync(...args),
+  readFileSync: (...args: unknown[]) => mockReadFileSync(...args),
+  readdirSync: (...args: unknown[]) => mockReaddirSync(...args),
+}));
+
+// Mock tool registry
+vi.mock('../../tools/build-registry', () => ({
+  buildToolRegistry: () => ({
+    getToolsForAgent: vi.fn().mockReturnValue({}),
+  }),
+}));
+
+// json-repair is used for safeParseJson in the insights runner
+vi.mock('../../../utils/json-repair', () => ({
+  safeParseJson: (text: string) => {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  },
+}));
+
+// parseLLMJson is used for task suggestion extraction
+vi.mock('../../schema/structured-output', () => ({
+  parseLLMJson: vi.fn().mockReturnValue(null),
+}));
+
+vi.mock('../../schema/insight-extractor', () => ({
+  TaskSuggestionSchema: {},
+}));
+
+// =============================================================================
+// Import after mocking
+// =============================================================================
+
+import { runInsightsQuery } from '../insights';
+import type { InsightsConfig, InsightsStreamEvent } from '../insights';
+import { parseLLMJson } from '../../schema/structured-output';
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+const fakeModel = { modelId: 'claude-sonnet-test' };
+
+function makeMockClient(systemPrompt = 'You are an AI assistant.') {
+  return {
+    model: fakeModel,
+    systemPrompt,
+    tools: {},
+    maxSteps: 30,
+  };
+}
+
+function makeStream(parts: Array<Record<string, unknown>>) {
+  return {
+    fullStream: (async function* () {
+      for (const part of parts) {
+        yield part;
+      }
+    })(),
+  };
+}
+
+function baseConfig(overrides: Partial<InsightsConfig> = {}): InsightsConfig {
+  return {
+    projectDir: '/project',
+    message: 'How does authentication work?',
+    ...overrides,
+  };
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe('runInsightsQuery', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCreateSimpleClient.mockResolvedValue(makeMockClient());
+    mockExistsSync.mockReturnValue(false);
+    mockReaddirSync.mockReturnValue([]);
+    vi.mocked(parseLLMJson).mockReturnValue(null);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Successful run — no streaming events needed from caller
+  // ---------------------------------------------------------------------------
+
+  it('returns response text accumulated from stream', async () => {
+    mockStreamText.mockReturnValue(
+      makeStream([
+        { type: 'text-delta', text: 'Authentication uses JWT tokens.' },
+        { type: 'text-delta', text: ' Tokens expire after 1 hour.' },
+      ]),
+    );
+
+    const result = await runInsightsQuery(baseConfig());
+
+    expect(result.text).toBe('Authentication uses JWT tokens. Tokens expire after 1 hour.');
+    expect(result.taskSuggestion).toBeNull();
+    expect(result.toolCalls).toEqual([]);
+  });
+
+  it('returns empty text and no task suggestion when stream is empty', async () => {
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    const result = await runInsightsQuery(baseConfig());
+
+    expect(result.text).toBe('');
+    expect(result.taskSuggestion).toBeNull();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Task suggestion extraction
+  // ---------------------------------------------------------------------------
+
+  it('extracts task suggestion from response text when marker present', async () => {
+    const suggestion = {
+      title: 'Add rate limiting',
+      description: 'Implement per-user rate limiting on auth endpoints',
+      metadata: { category: 'security', complexity: 'medium', impact: 'high' },
+    };
+
+    mockStreamText.mockReturnValue(
+      makeStream([
+        {
+          type: 'text-delta',
+          text: `Here is my suggestion.\n__TASK_SUGGESTION__:${JSON.stringify(suggestion)}\n`,
+        },
+      ]),
+    );
+
+    vi.mocked(parseLLMJson).mockReturnValueOnce(suggestion as unknown as ReturnType<typeof parseLLMJson>);
+
+    const result = await runInsightsQuery(baseConfig());
+
+    expect(result.taskSuggestion).not.toBeNull();
+    expect(result.taskSuggestion?.title).toBe('Add rate limiting');
+    expect(result.taskSuggestion?.metadata.category).toBe('security');
+  });
+
+  it('returns null taskSuggestion when no marker in response', async () => {
+    mockStreamText.mockReturnValue(
+      makeStream([{ type: 'text-delta', text: 'No suggestions here.' }]),
+    );
+
+    const result = await runInsightsQuery(baseConfig());
+
+    expect(result.taskSuggestion).toBeNull();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Tool call tracking
+  // ---------------------------------------------------------------------------
+
+  it('tracks tool calls in result.toolCalls', async () => {
+    mockStreamText.mockReturnValue(
+      makeStream([
+        { type: 'tool-call', toolName: 'Read', toolCallId: 'c1', input: { file_path: 'src/auth.ts' } },
+        { type: 'tool-result', toolCallId: 'c1', toolName: 'Read', output: 'file content' },
+        { type: 'tool-call', toolName: 'Glob', toolCallId: 'c2', input: { pattern: '**/*.ts' } },
+        { type: 'tool-result', toolCallId: 'c2', toolName: 'Glob', output: 'src/auth.ts' },
+      ]),
+    );
+
+    const result = await runInsightsQuery(baseConfig());
+
+    expect(result.toolCalls).toHaveLength(2);
+    expect(result.toolCalls[0].name).toBe('Read');
+    expect(result.toolCalls[1].name).toBe('Glob');
+  });
+
+  it('extracts file_path from Read tool call input', async () => {
+    mockStreamText.mockReturnValue(
+      makeStream([
+        {
+          type: 'tool-call',
+          toolName: 'Read',
+          toolCallId: 'c1',
+          input: { file_path: 'src/auth.ts' },
+        },
+      ]),
+    );
+
+    const result = await runInsightsQuery(baseConfig());
+
+    expect(result.toolCalls[0].input).toBe('src/auth.ts');
+  });
+
+  it('extracts pattern from Grep/Glob tool call input', async () => {
+    mockStreamText.mockReturnValue(
+      makeStream([
+        {
+          type: 'tool-call',
+          toolName: 'Grep',
+          toolCallId: 'c1',
+          input: { pattern: 'useAuth' },
+        },
+      ]),
+    );
+
+    const result = await runInsightsQuery(baseConfig());
+
+    expect(result.toolCalls[0].input).toBe('pattern: useAuth');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Stream callbacks
+  // ---------------------------------------------------------------------------
+
+  it('forwards text-delta events to onStream callback', async () => {
+    mockStreamText.mockReturnValue(
+      makeStream([
+        { type: 'text-delta', text: 'chunk1' },
+        { type: 'text-delta', text: 'chunk2' },
+      ]),
+    );
+
+    const events: InsightsStreamEvent[] = [];
+    await runInsightsQuery(baseConfig(), (e) => events.push(e));
+
+    const textEvents = events.filter((e) => e.type === 'text-delta');
+    expect(textEvents).toHaveLength(2);
+  });
+
+  it('forwards tool-start events for tool-call stream parts', async () => {
+    mockStreamText.mockReturnValue(
+      makeStream([
+        { type: 'tool-call', toolName: 'Grep', toolCallId: 'c1', input: { pattern: 'login' } },
+      ]),
+    );
+
+    const events: InsightsStreamEvent[] = [];
+    await runInsightsQuery(baseConfig(), (e) => events.push(e));
+
+    const toolStartEvents = events.filter((e) => e.type === 'tool-start');
+    expect(toolStartEvents).toHaveLength(1);
+    expect((toolStartEvents[0] as { type: 'tool-start'; name: string }).name).toBe('Grep');
+  });
+
+  it('forwards tool-end events for tool-result stream parts', async () => {
+    mockStreamText.mockReturnValue(
+      makeStream([
+        { type: 'tool-result', toolCallId: 'c1', toolName: 'Read', output: 'content' },
+      ]),
+    );
+
+    const events: InsightsStreamEvent[] = [];
+    await runInsightsQuery(baseConfig(), (e) => events.push(e));
+
+    const toolEndEvents = events.filter((e) => e.type === 'tool-end');
+    expect(toolEndEvents).toHaveLength(1);
+  });
+
+  it('forwards error events for error stream parts', async () => {
+    mockStreamText.mockReturnValue(
+      makeStream([{ type: 'error', error: new Error('tool failed') }]),
+    );
+
+    const events: InsightsStreamEvent[] = [];
+    await runInsightsQuery(baseConfig(), (e) => events.push(e));
+
+    const errorEvents = events.filter((e) => e.type === 'error');
+    expect(errorEvents).toHaveLength(1);
+    expect((errorEvents[0] as { type: 'error'; error: string }).error).toBe('tool failed');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Error propagation
+  // ---------------------------------------------------------------------------
+
+  it('rethrows when streamText iteration throws', async () => {
+    mockStreamText.mockReturnValue({
+      // biome-ignore lint/correctness/useYield: intentionally throwing before yield to test error path
+      fullStream: (async function* () {
+        throw new Error('API timeout');
+      })(),
+    });
+
+    await expect(runInsightsQuery(baseConfig())).rejects.toThrow('API timeout');
+  });
+
+  it('emits error event to callback before rethrowing', async () => {
+    mockStreamText.mockReturnValue({
+      // biome-ignore lint/correctness/useYield: intentionally throwing before yield to test error path
+      fullStream: (async function* () {
+        throw new Error('rate limited');
+      })(),
+    });
+
+    const events: InsightsStreamEvent[] = [];
+    await expect(runInsightsQuery(baseConfig(), (e) => events.push(e))).rejects.toThrow(
+      'rate limited',
+    );
+
+    expect(events.some((e) => e.type === 'error')).toBe(true);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Client configuration
+  // ---------------------------------------------------------------------------
+
+  it('uses sonnet model and medium thinking level by default', async () => {
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    await runInsightsQuery(baseConfig());
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.modelShorthand).toBe('sonnet');
+    expect(clientArgs.thinkingLevel).toBe('medium');
+  });
+
+  it('accepts custom modelShorthand and thinkingLevel', async () => {
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    await runInsightsQuery(baseConfig({ modelShorthand: 'haiku', thinkingLevel: 'low' }));
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.modelShorthand).toBe('haiku');
+    expect(clientArgs.thinkingLevel).toBe('low');
+  });
+
+  // ---------------------------------------------------------------------------
+  // History handling
+  // ---------------------------------------------------------------------------
+
+  it('includes conversation history in the prompt when provided', async () => {
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    await runInsightsQuery(
+      baseConfig({
+        message: 'What about refresh tokens?',
+        history: [
+          { role: 'user', content: 'How does auth work?' },
+          { role: 'assistant', content: 'It uses JWT.' },
+        ],
+      }),
+    );
+
+    const callArgs = mockStreamText.mock.calls[0][0];
+    const prompt = callArgs.prompt as string;
+    expect(prompt).toContain('How does auth work?');
+    expect(prompt).toContain('It uses JWT.');
+    expect(prompt).toContain('What about refresh tokens?');
+  });
+
+  it('uses message directly as prompt when history is empty', async () => {
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    await runInsightsQuery(baseConfig({ message: 'What is the entry point?' }));
+
+    const callArgs = mockStreamText.mock.calls[0][0];
+    expect(callArgs.prompt).toBe('What is the entry point?');
+  });
+});
@@ -0,0 +1,247 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// =============================================================================
+// Mocks — must be declared before any imports that use them
+// =============================================================================
+
+const mockGenerateText = vi.fn();
+
+vi.mock('ai', () => ({
+  generateText: (...args: unknown[]) => mockGenerateText(...args),
+}));
+
+const mockCreateSimpleClient = vi.fn();
+
+vi.mock('../../client/factory', () => ({
+  createSimpleClient: (...args: unknown[]) => mockCreateSimpleClient(...args),
+}));
+
+// =============================================================================
+// Import after mocking
+// =============================================================================
+
+import { resolveMergeConflict, createMergeResolverFn } from '../merge-resolver';
+import type { MergeResolverConfig } from '../merge-resolver';
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+const fakeModel = { modelId: 'claude-haiku-test' };
+
+function makeMockClient(systemPrompt = 'Resolve merge conflicts.') {
+  return { model: fakeModel, systemPrompt };
+}
+
+function baseConfig(overrides: Partial<MergeResolverConfig> = {}): MergeResolverConfig {
+  return {
+    systemPrompt: 'You are a merge conflict resolver.',
+    userPrompt: '<<<\nHEAD version\n===\nIncoming version\n>>>',
+    ...overrides,
+  };
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe('resolveMergeConflict', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCreateSimpleClient.mockResolvedValue(makeMockClient());
+  });
+
+  // ---------------------------------------------------------------------------
+  // Successful resolution
+  // ---------------------------------------------------------------------------
+
+  it('returns success with trimmed resolved text', async () => {
+    mockGenerateText.mockResolvedValue({ text: '  Resolved: use incoming version.  ' });
+
+    const result = await resolveMergeConflict(baseConfig());
+
+    expect(result.success).toBe(true);
+    expect(result.text).toBe('Resolved: use incoming version.');
+    expect(result.error).toBeUndefined();
+  });
+
+  it('passes model and systemPrompt from client to generateText', async () => {
+    mockGenerateText.mockResolvedValue({ text: 'merged code here' });
+
+    await resolveMergeConflict(baseConfig());
+
+    expect(mockGenerateText).toHaveBeenCalledOnce();
+    const callArgs = mockGenerateText.mock.calls[0][0];
+    expect(callArgs.model).toBe(fakeModel);
+    expect(callArgs.system).toBe('Resolve merge conflicts.');
+  });
+
+  it('passes userPrompt as the prompt parameter to generateText', async () => {
+    mockGenerateText.mockResolvedValue({ text: 'resolved' });
+
+    const conflict = '<<<\nmy change\n===\ntheir change\n>>>';
+    await resolveMergeConflict(baseConfig({ userPrompt: conflict }));
+
+    const callArgs = mockGenerateText.mock.calls[0][0];
+    expect(callArgs.prompt).toBe(conflict);
+  });
+
+  it('passes systemPrompt config to createSimpleClient', async () => {
+    mockGenerateText.mockResolvedValue({ text: 'resolved' });
+
+    const customSystem = 'Custom system prompt.';
+    await resolveMergeConflict(baseConfig({ systemPrompt: customSystem }));
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.systemPrompt).toBe(customSystem);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Default model / thinking level
+  // ---------------------------------------------------------------------------
+
+  it('uses haiku model and low thinking level by default', async () => {
+    mockGenerateText.mockResolvedValue({ text: 'resolved' });
+
+    await resolveMergeConflict(baseConfig());
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.modelShorthand).toBe('haiku');
+    expect(clientArgs.thinkingLevel).toBe('low');
+  });
+
+  it('accepts custom modelShorthand and thinkingLevel', async () => {
+    mockGenerateText.mockResolvedValue({ text: 'resolved' });
+
+    await resolveMergeConflict(
+      baseConfig({ modelShorthand: 'sonnet', thinkingLevel: 'medium' }),
+    );
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.modelShorthand).toBe('sonnet');
+    expect(clientArgs.thinkingLevel).toBe('medium');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Empty response handling
+  // ---------------------------------------------------------------------------
+
+  it('returns failure when LLM returns empty text', async () => {
+    mockGenerateText.mockResolvedValue({ text: '   ' });
+
+    const result = await resolveMergeConflict(baseConfig());
+
+    expect(result.success).toBe(false);
+    expect(result.text).toBe('');
+    expect(result.error).toBe('Empty response from AI');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Error handling
+  // ---------------------------------------------------------------------------
+
+  it('returns failure with error message when generateText throws Error', async () => {
+    mockGenerateText.mockRejectedValue(new Error('API rate limit'));
+
+    const result = await resolveMergeConflict(baseConfig());
+
+    expect(result.success).toBe(false);
+    expect(result.text).toBe('');
+    expect(result.error).toBe('API rate limit');
+  });
+
+  it('returns failure with string coercion when non-Error is thrown', async () => {
+    mockGenerateText.mockRejectedValue('connection refused');
+
+    const result = await resolveMergeConflict(baseConfig());
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('connection refused');
+  });
+
+  it('returns failure when createSimpleClient throws', async () => {
+    mockCreateSimpleClient.mockRejectedValue(new Error('No auth token'));
+
+    const result = await resolveMergeConflict(baseConfig());
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('No auth token');
+  });
+});
+
+// =============================================================================
+// createMergeResolverFn
+// =============================================================================
+
+describe('createMergeResolverFn', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCreateSimpleClient.mockResolvedValue(makeMockClient());
+  });
+
+  it('returns an async function', () => {
+    const fn = createMergeResolverFn();
+    expect(typeof fn).toBe('function');
+  });
+
+  it('returned function resolves to the resolved text on success', async () => {
+    mockGenerateText.mockResolvedValue({ text: 'merged content' });
+
+    const fn = createMergeResolverFn();
+    const result = await fn('system context', 'conflict block');
+
+    expect(result).toBe('merged content');
+  });
+
+  it('returned function resolves to empty string when LLM returns empty', async () => {
+    mockGenerateText.mockResolvedValue({ text: '   ' });
+
+    const fn = createMergeResolverFn();
+    const result = await fn('system', 'conflict');
+
+    expect(result).toBe('');
+  });
+
+  it('returned function resolves to empty string on error (does not throw)', async () => {
+    mockGenerateText.mockRejectedValue(new Error('timeout'));
+
+    const fn = createMergeResolverFn();
+    const result = await fn('system', 'conflict');
+
+    expect(result).toBe('');
+  });
+
+  it('uses provided modelShorthand and thinkingLevel', async () => {
+    mockGenerateText.mockResolvedValue({ text: 'resolved' });
+
+    const fn = createMergeResolverFn('sonnet', 'medium');
+    await fn('sys', 'user');
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.modelShorthand).toBe('sonnet');
+    expect(clientArgs.thinkingLevel).toBe('medium');
+  });
+
+  it('defaults to haiku and low when no arguments given', async () => {
+    mockGenerateText.mockResolvedValue({ text: 'resolved' });
+
+    const fn = createMergeResolverFn();
+    await fn('sys', 'user');
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.modelShorthand).toBe('haiku');
+    expect(clientArgs.thinkingLevel).toBe('low');
+  });
+
+  it('passes system and user arguments as systemPrompt and userPrompt', async () => {
+    mockGenerateText.mockResolvedValue({ text: 'resolved' });
+
+    const fn = createMergeResolverFn();
+    await fn('the system prompt', 'the conflict text');
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.systemPrompt).toBe('the system prompt');
+    const generateArgs = mockGenerateText.mock.calls[0][0];
+    expect(generateArgs.prompt).toBe('the conflict text');
+  });
+});
@@ -0,0 +1,420 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// =============================================================================
+// Mocks — must be declared before any imports that use them
+// =============================================================================
+
+const mockStreamText = vi.fn();
+
+vi.mock('ai', () => ({
+  streamText: (...args: unknown[]) => mockStreamText(...args),
+  stepCountIs: (n: number) => ({ type: 'stepCount', count: n }),
+}));
+
+const mockCreateSimpleClient = vi.fn();
+
+vi.mock('../../client/factory', () => ({
+  createSimpleClient: (...args: unknown[]) => mockCreateSimpleClient(...args),
+}));
+
+// Filesystem mocks
+const mockExistsSync = vi.fn();
+const mockReadFileSync = vi.fn();
+const mockWriteFileSync = vi.fn();
+const mockMkdirSync = vi.fn();
+const mockRenameSync = vi.fn();
+
+vi.mock('node:fs', () => ({
+  existsSync: (...args: unknown[]) => mockExistsSync(...args),
+  readFileSync: (...args: unknown[]) => mockReadFileSync(...args),
+  writeFileSync: (...args: unknown[]) => mockWriteFileSync(...args),
+  mkdirSync: (...args: unknown[]) => mockMkdirSync(...args),
+  renameSync: (...args: unknown[]) => mockRenameSync(...args),
+}));
+
+// Tool registry mock
+vi.mock('../../tools/build-registry', () => ({
+  buildToolRegistry: () => ({
+    getToolsForAgent: vi.fn().mockReturnValue({}),
+  }),
+}));
+
+// json-repair used for safeParseJson
+vi.mock('../../../utils/json-repair', () => ({
+  safeParseJson: (text: string) => {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  },
+}));
+
+// tryLoadPrompt — return null so inline prompts are used
+vi.mock('../../prompts/prompt-loader', () => ({
+  tryLoadPrompt: vi.fn().mockReturnValue(null),
+}));
+
+// =============================================================================
+// Import after mocking
+// =============================================================================
+
+import { runRoadmapGeneration } from '../roadmap';
+import type { RoadmapConfig, RoadmapStreamEvent } from '../roadmap';
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+const fakeModel = { modelId: 'claude-sonnet-test' };
+
+function makeMockClient() {
+  return {
+    model: fakeModel,
+    systemPrompt: '',
+    tools: {},
+    maxSteps: 30,
+  };
+}
+
+function makeStream(parts: Array<Record<string, unknown>>) {
+  return {
+    fullStream: (async function* () {
+      for (const part of parts) {
+        yield part;
+      }
+    })(),
+  };
+}
+
+/** Valid discovery JSON that passes schema validation */
+const VALID_DISCOVERY_JSON = JSON.stringify({
+  project_name: 'TestProject',
+  target_audience: 'Developers',
+  product_vision: 'Make coding easier',
+  key_features: ['Auth', 'Dashboard'],
+  technical_stack: { language: 'TypeScript' },
+  constraints: [],
+});
+
+/** Valid roadmap JSON that passes schema validation (>=3 features, all required keys) */
+const VALID_ROADMAP_JSON = JSON.stringify({
+  vision: 'Automate everything',
+  target_audience: { primary: 'Developers', secondary: 'QA' },
+  phases: [{ id: 'p1', name: 'MVP' }],
+  features: [
+    {
+      id: 'f1', title: 'Feature A', description: 'Desc A', priority: 'high',
+      complexity: 'medium', impact: 'high', phase_id: 'p1', status: 'planned',
+      acceptance_criteria: [], user_stories: [],
+    },
+    {
+      id: 'f2', title: 'Feature B', description: 'Desc B', priority: 'medium',
+      complexity: 'low', impact: 'medium', phase_id: 'p1', status: 'planned',
+      acceptance_criteria: [], user_stories: [],
+    },
+    {
+      id: 'f3', title: 'Feature C', description: 'Desc C', priority: 'low',
+      complexity: 'high', impact: 'low', phase_id: 'p1', status: 'planned',
+      acceptance_criteria: [], user_stories: [],
+    },
+  ],
+});
+
+function baseConfig(overrides: Partial<RoadmapConfig> = {}): RoadmapConfig {
+  return {
+    projectDir: '/project',
+    outputDir: '/project/.auto-claude/roadmap',
+    ...overrides,
+  };
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe('runRoadmapGeneration', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCreateSimpleClient.mockResolvedValue(makeMockClient());
+    // Output dir exists by default (created by mkdirSync is a no-op)
+    mockExistsSync.mockReturnValue(false);
+    mockMkdirSync.mockReturnValue(undefined);
+    mockStreamText.mockReturnValue(makeStream([]));
+  });
+
+  // ---------------------------------------------------------------------------
+  // Successful full pipeline
+  // ---------------------------------------------------------------------------
+
+  it('returns success with roadmapPath when both phases succeed', async () => {
+    // existsSync: outputDir does not exist initially; discovery file created after phase 1
+    let discoveryCreated = false;
+
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p.endsWith('roadmap')) return true; // outputDir exists
+      if (p.endsWith('roadmap_discovery.json') && discoveryCreated) return true;
+      if (p.endsWith('roadmap.json') && discoveryCreated) return false; // not yet
+      return false;
+    });
+
+    // streamText yields nothing — validation happens from file reads
+    mockStreamText.mockImplementation(() => {
+      discoveryCreated = true; // simulate file being written during stream
+      return makeStream([]);
+    });
+
+    // readFileSync returns valid JSON for each file
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p.endsWith('roadmap_discovery.json')) return VALID_DISCOVERY_JSON;
+      if (p.endsWith('roadmap.json')) return VALID_ROADMAP_JSON;
+      return '{}';
+    });
+
+    // After agent runs, both files exist
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p.endsWith('roadmap_discovery.json')) return true;
+      if (p.endsWith('roadmap.json')) return true;
+      return true; // outputDir, etc.
+    });
+
+    const result = await runRoadmapGeneration(baseConfig());
+
+    expect(result.success).toBe(true);
+    expect(result.roadmapPath).toContain('roadmap.json');
+    expect(result.phases).toHaveLength(2);
+    expect(result.phases[0].phase).toBe('discovery');
+    expect(result.phases[1].phase).toBe('features');
+  });
+
+  // ---------------------------------------------------------------------------
+  // Discovery phase failure
+  // ---------------------------------------------------------------------------
+
+  it('returns failure when discovery phase fails after all retries', async () => {
+    // Discovery file is never created
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p.endsWith('roadmap')) return true; // outputDir exists
+      return false; // discovery file never appears
+    });
+
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    const result = await runRoadmapGeneration(baseConfig());
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('Discovery failed');
+    expect(result.phases).toHaveLength(1);
+    expect(result.phases[0].phase).toBe('discovery');
+    expect(result.phases[0].success).toBe(false);
+  });
+
+  it('does not run features phase when discovery fails', async () => {
+    mockExistsSync.mockReturnValue(false);
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    const result = await runRoadmapGeneration(baseConfig());
+
+    // Only 1 phase in result — features was never attempted
+    expect(result.phases).toHaveLength(1);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Features phase failure
+  // ---------------------------------------------------------------------------
+
+  it('returns failure when features phase fails (no roadmap.json created)', async () => {
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p.endsWith('roadmap')) return true;
+      if (p.endsWith('roadmap_discovery.json')) return true; // discovery succeeded
+      if (p.endsWith('project_index.json')) return false;
+      return false; // roadmap.json never created
+    });
+
+    mockReadFileSync.mockImplementation((p: string) => {
+      if (p.endsWith('roadmap_discovery.json')) return VALID_DISCOVERY_JSON;
+      return '{}';
+    });
+
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    const result = await runRoadmapGeneration(baseConfig());
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('Feature generation failed');
+    expect(result.phases).toHaveLength(2);
+    expect(result.phases[1].phase).toBe('features');
+    expect(result.phases[1].success).toBe(false);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Cache (refresh=false) — skip phases when files already exist
+  // ---------------------------------------------------------------------------
+
+  it('skips discovery phase when discovery file already exists and refresh=false', async () => {
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p.endsWith('roadmap')) return true;
+      if (p.endsWith('roadmap_discovery.json')) return true; // already exists
+      if (p.endsWith('roadmap.json')) return true; // also exists
+      return false;
+    });
+
+    const result = await runRoadmapGeneration(baseConfig({ refresh: false }));
+
+    // streamText should not have been called since both files exist
+    expect(mockStreamText).not.toHaveBeenCalled();
+    expect(result.success).toBe(true);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Output directory creation
+  // ---------------------------------------------------------------------------
+
+  it('creates output directory when it does not exist', async () => {
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p.endsWith('roadmap') && !p.includes('.json')) return false; // dir does not exist
+      return false;
+    });
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    await runRoadmapGeneration(baseConfig({ outputDir: '/project/.auto-claude/roadmap' }));
+
+    expect(mockMkdirSync).toHaveBeenCalledWith(
+      expect.stringContaining('roadmap'),
+      expect.objectContaining({ recursive: true }),
+    );
+  });
+
+  // ---------------------------------------------------------------------------
+  // Streaming events
+  // ---------------------------------------------------------------------------
+
+  it('emits phase-start and phase-complete events for both phases', async () => {
+    // Make discovery succeed via cached file
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p.endsWith('roadmap')) return true;
+      if (p.endsWith('roadmap_discovery.json')) return true;
+      if (p.endsWith('roadmap.json')) return true;
+      return false;
+    });
+
+    const events: RoadmapStreamEvent[] = [];
+    await runRoadmapGeneration(baseConfig({ refresh: false }), (e) => events.push(e));
+
+    const phaseStartEvents = events.filter((e) => e.type === 'phase-start');
+    const phaseCompleteEvents = events.filter((e) => e.type === 'phase-complete');
+
+    expect(phaseStartEvents).toHaveLength(2);
+    expect(phaseCompleteEvents).toHaveLength(2);
+    expect((phaseStartEvents[0] as { type: string; phase: string }).phase).toBe('discovery');
+    expect((phaseStartEvents[1] as { type: string; phase: string }).phase).toBe('features');
+  });
+
+  it('forwards text-delta events from stream to callback', async () => {
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p.endsWith('roadmap_discovery.json')) return true;
+      if (p.endsWith('roadmap.json')) return true;
+      return true;
+    });
+
+    const events: RoadmapStreamEvent[] = [];
+    await runRoadmapGeneration(baseConfig({ refresh: false }), (e) => events.push(e));
+
+    // Since files exist and refresh=false, streamText is never called and no text-delta fires
+    // This confirms the caching path works correctly
+    const textEvents = events.filter((e) => e.type === 'text-delta');
+    expect(textEvents).toHaveLength(0);
+  });
+
+  it('forwards text-delta from active streamText run when discovery must be generated', async () => {
+    // outputDir exists, but discovery file does not (first attempt)
+    // After first streamText run, discovery file appears
+    let callCount = 0;
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p.endsWith('roadmap') && !p.includes('.json')) return true;
+      if (p.endsWith('roadmap_discovery.json')) return callCount > 0;
+      return false;
+    });
+
+    mockReadFileSync.mockReturnValue(VALID_DISCOVERY_JSON);
+
+    mockStreamText.mockImplementation(() => {
+      callCount++;
+      return {
+        fullStream: (async function* () {
+          yield { type: 'text-delta', text: 'Analyzing project...' };
+        })(),
+      };
+    });
+
+    const events: RoadmapStreamEvent[] = [];
+    await runRoadmapGeneration(baseConfig(), (e) => events.push(e));
+
+    const textEvents = events.filter((e) => e.type === 'text-delta');
+    expect(textEvents.length).toBeGreaterThan(0);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Client configuration
+  // ---------------------------------------------------------------------------
+
+  it('uses sonnet and medium thinking level by default', async () => {
+    mockExistsSync.mockReturnValue(false);
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    await runRoadmapGeneration(baseConfig());
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.modelShorthand).toBe('sonnet');
+    expect(clientArgs.thinkingLevel).toBe('medium');
+  });
+
+  it('accepts custom modelShorthand and thinkingLevel', async () => {
+    mockExistsSync.mockReturnValue(false);
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    await runRoadmapGeneration(baseConfig({ modelShorthand: 'haiku', thinkingLevel: 'low' }));
+
+    const clientArgs = mockCreateSimpleClient.mock.calls[0][0];
+    expect(clientArgs.modelShorthand).toBe('haiku');
+    expect(clientArgs.thinkingLevel).toBe('low');
+  });
+
+  it('uses default outputDir when not provided', async () => {
+    mockExistsSync.mockReturnValue(false);
+    mockStreamText.mockReturnValue(makeStream([]));
+
+    await runRoadmapGeneration({ projectDir: '/my/project' });
+
+    // mkdirSync should have been called with the default path
+    expect(mockMkdirSync).toHaveBeenCalledWith(
+      expect.stringContaining('.auto-claude'),
+      expect.anything(),
+    );
+  });
+
+  // ---------------------------------------------------------------------------
+  // Error handling — streamText throws
+  // ---------------------------------------------------------------------------
+
+  it('records error in phase when streamText throws during discovery', async () => {
+    mockExistsSync.mockImplementation((p: string) => {
+      if (p.endsWith('roadmap') && !p.includes('.json')) return true;
+      return false;
+    });
+
+    mockStreamText.mockImplementation(() => {
+      return {
+        // biome-ignore lint/correctness/useYield: intentionally throwing before yield to test error path
+        fullStream: (async function* () {
+          throw new Error('network failure');
+        })(),
+      };
+    });
+
+    const result = await runRoadmapGeneration(baseConfig());
+
+    expect(result.success).toBe(false);
+    expect(result.phases[0].errors.length).toBeGreaterThan(0);
+  });
+});
@@ -15,7 +15,6 @@ import { generateText } from 'ai';

 import { createSimpleClient } from '../client/factory';
 import type { ModelShorthand, ThinkingLevel } from '../config/types';
-import { withRateLimitRetry } from '../session/rate-limit-retry';

 // =============================================================================
 // Types
@@ -138,11 +137,11 @@ export async function generateChangelog(
      thinkingLevel,
    });

-    const result = await withRateLimitRetry(() => generateText({
+    const result = await generateText({
      model: client.model,
      system: client.systemPrompt,
      prompt,
-    }));
+    });

    if (result.text.trim()) {
      return { success: true, text: result.text.trim() };
@@ -23,8 +23,6 @@ import type { Tool as AITool } from 'ai';
 import * as crypto from 'node:crypto';

 import { createSimpleClient } from '../../client/factory';
-import { withRateLimitRetry } from '../../session/rate-limit-retry';
-import { formatWaitDuration } from '../../session/rate-limit-wait';
 import type { SimpleClientResult } from '../../client/types';
 import type { ModelShorthand, ThinkingLevel } from '../../config/types';
 import { buildThinkingProviderOptions } from '../../config/types';
@@ -559,58 +557,43 @@ export class ParallelOrchestratorReviewer {
      let stepCount = 0;
      let toolCallCount = 0;
      const toolsUsed = new Set<string>();
-      const { structuredOutput, textOutput } = await withRateLimitRetry(async () => {
-        // Reset counters on each retry attempt
-        stepCount = 0;
-        toolCallCount = 0;
-        toolsUsed.clear();

-        // Use streamText instead of generateText — Codex endpoint only supports streaming.
-        // Output.object() generates structured output as a final step after all tool calls.
-        const stream = streamText({
-          model: client.model,
-          system: genOptions.system,
-          messages: [{ role: 'user' as const, content: userMessage }],
-          tools,
-          stopWhen: stepCountIs(100),
-          output: Output.object({ schema: SpecialistOutputOutputSchema }),
-          abortSignal,
-          ...(genOptions.providerOptions ? { providerOptions: genOptions.providerOptions } : {}),
-          onStepFinish: ({ toolCalls }) => {
-            stepCount++;
-            if (toolCalls && toolCalls.length > 0) {
-              for (const tc of toolCalls) {
-                toolCallCount++;
-                toolsUsed.add(tc.toolName);
-              }
-              this.reportProgress({
-                phase: config.name,
-                progress: 40,
-                message: `[Specialist:${config.name}] Step ${stepCount}: ${toolCalls.length} tool call(s) — ${toolCalls.map((tc) => tc.toolName).join(', ')}`,
-                prNumber: context.prNumber,
-              });
+      // Use streamText instead of generateText — Codex endpoint only supports streaming.
+      // Output.object() generates structured output as a final step after all tool calls.
+      const stream = streamText({
+        model: client.model,
+        system: genOptions.system,
+        messages: [{ role: 'user' as const, content: userMessage }],
+        tools,
+        stopWhen: stepCountIs(100),
+        output: Output.object({ schema: SpecialistOutputOutputSchema }),
+        abortSignal,
+        ...(genOptions.providerOptions ? { providerOptions: genOptions.providerOptions } : {}),
+        onStepFinish: ({ toolCalls }) => {
+          stepCount++;
+          if (toolCalls && toolCalls.length > 0) {
+            for (const tc of toolCalls) {
+              toolCallCount++;
+              toolsUsed.add(tc.toolName);
            }
-          },
-        });
-
-        // Consume the stream (required before accessing output/text)
-        for await (const _part of stream.fullStream) { /* consume */ }
-
-        return { structuredOutput: await stream.output, textOutput: await stream.text };
-      }, {
-        signal: abortSignal,
-        onWaiting: (waitMs) => this.reportProgress({
-          phase: config.name,
-          progress: 38,
-          message: `[Specialist:${config.name}] Rate limited. Waiting ${formatWaitDuration(waitMs)}...`,
-          prNumber: context.prNumber,
-        }),
+            this.reportProgress({
+              phase: config.name,
+              progress: 40,
+              message: `[Specialist:${config.name}] Step ${stepCount}: ${toolCalls.length} tool call(s) — ${toolCalls.map((tc) => tc.toolName).join(', ')}`,
+              prNumber: context.prNumber,
+            });
+          }
+        },
      });

+      // Consume the stream (required before accessing output/text)
+      for await (const _part of stream.fullStream) { /* consume */ }
+
      // Use structured output if available, fall back to text parsing
+      const structuredOutput = await stream.output;
      const findings = structuredOutput
        ? parseSpecialistOutput(config.name, structuredOutput)
-        : parseSpecialistOutput(config.name, textOutput);
+        : parseSpecialistOutput(config.name, await stream.text);

      const toolSummary = toolCallCount > 0
        ? ` (${toolCallCount} tool calls: ${Array.from(toolsUsed).join(', ')})`
@@ -772,53 +755,41 @@ Validate each finding by reading the actual code at the specified file and line.
    try {
      let validatorToolCalls = 0;

-      const { structuredOutput: valOutput, textOutput: valText } = await withRateLimitRetry(async () => {
-        validatorToolCalls = 0;
-
-        // Use streamText — Codex endpoint only supports streaming.
-        // Output.object() generates the validation array (wrapped in { validations: [...] }) as a final step.
-        const stream = streamText({
-          model: client.model,
-          system: genOptions.system,
-          messages: [{ role: 'user' as const, content: userMessage }],
-          tools,
-          stopWhen: stepCountIs(150),
-          output: Output.object({ schema: FindingValidationsOutputSchema }),
-          abortSignal,
-          ...(genOptions.providerOptions ? { providerOptions: genOptions.providerOptions } : {}),
-          onStepFinish: ({ toolCalls }) => {
-            if (toolCalls && toolCalls.length > 0) {
-              validatorToolCalls += toolCalls.length;
-              this.reportProgress({
-                phase: 'validation',
-                progress: 75,
-                message: `[FindingValidator] Examining code: ${toolCalls.map((tc) => tc.toolName).join(', ')}`,
-                prNumber: context.prNumber,
-              });
-            }
-          },
-        });
-
-        // Consume stream before reading output
-        for await (const _part of stream.fullStream) { /* consume */ }
-
-        return { structuredOutput: await stream.output, textOutput: await stream.text };
-      }, {
-        signal: abortSignal,
-        onWaiting: (waitMs) => this.reportProgress({
-          phase: 'validation',
-          progress: 72,
-          message: `[FindingValidator] Rate limited. Waiting ${formatWaitDuration(waitMs)}...`,
-          prNumber: context.prNumber,
-        }),
+      // Use streamText — Codex endpoint only supports streaming.
+      // Output.object() generates the validation array (wrapped in { validations: [...] }) as a final step.
+      const stream = streamText({
+        model: client.model,
+        system: genOptions.system,
+        messages: [{ role: 'user' as const, content: userMessage }],
+        tools,
+        stopWhen: stepCountIs(150),
+        output: Output.object({ schema: FindingValidationsOutputSchema }),
+        abortSignal,
+        ...(genOptions.providerOptions ? { providerOptions: genOptions.providerOptions } : {}),
+        onStepFinish: ({ toolCalls }) => {
+          if (toolCalls && toolCalls.length > 0) {
+            validatorToolCalls += toolCalls.length;
+            this.reportProgress({
+              phase: 'validation',
+              progress: 75,
+              message: `[FindingValidator] Examining code: ${toolCalls.map((tc) => tc.toolName).join(', ')}`,
+              prNumber: context.prNumber,
+            });
+          }
+        },
      });

+      // Consume stream before reading output
+      for await (const _part of stream.fullStream) { /* consume */ }
+
      // Use structured output if available, fall back to text parsing
+      const structuredOutput = await stream.output;
      let rawValidations: Array<{ findingId: string; validationStatus: string; explanation: string }>;
-      if (valOutput) {
-        rawValidations = valOutput.validations;
+      if (structuredOutput) {
+        rawValidations = structuredOutput.validations;
      } else {
-        const parsed = parseLLMJson(valText, FindingValidationArraySchema);
+        const text = await stream.text;
+        const parsed = parseLLMJson(text, FindingValidationArraySchema);
        if (!parsed || !Array.isArray(parsed) || parsed.length === 0) {
          return findings; // Fail-safe: keep all findings
        }
@@ -942,38 +913,28 @@ Validate each finding by reading the actual code at the specified file and line.
    };

    try {
-      const { structuredOutput: synthOutput, textOutput: synthText } = await withRateLimitRetry(async () => {
-        // Use streamText — Codex endpoint only supports streaming.
-        // Output.object() generates the structured verdict as a final step.
-        const stream = streamText({
-          model: client.model,
-          system: genOptions.system,
-          prompt,
-          output: Output.object({ schema: SynthesisResultOutputSchema }),
-          abortSignal,
-          ...(genOptions.providerOptions ? { providerOptions: genOptions.providerOptions } : {}),
-        });
-
-        // Consume stream before reading output
-        for await (const _part of stream.fullStream) { /* consume */ }
-
-        return { structuredOutput: await stream.output, textOutput: await stream.text };
-      }, {
-        signal: abortSignal,
-        onWaiting: (waitMs) => this.reportProgress({
-          phase: 'synthesizing',
-          progress: 62,
-          message: `[ParallelOrchestrator] Rate limited during synthesis. Waiting ${formatWaitDuration(waitMs)}...`,
-          prNumber: context.prNumber,
-        }),
+      // Use streamText — Codex endpoint only supports streaming.
+      // Output.object() generates the structured verdict as a final step.
+      const stream = streamText({
+        model: client.model,
+        system: genOptions.system,
+        prompt,
+        output: Output.object({ schema: SynthesisResultOutputSchema }),
+        abortSignal,
+        ...(genOptions.providerOptions ? { providerOptions: genOptions.providerOptions } : {}),
      });

+      // Consume stream before reading output
+      for await (const _part of stream.fullStream) { /* consume */ }
+
      // Use structured output if available, fall back to text parsing
+      const structuredOutput = await stream.output;
      let data: { verdict: string; verdictReasoning: string; removedFindingIds: string[] } | null;
-      if (synthOutput) {
-        data = synthOutput;
+      if (structuredOutput) {
+        data = structuredOutput;
      } else {
-        data = parseLLMJson(synthText, SynthesisResultSchema);
+        const text = await stream.text;
+        data = parseLLMJson(text, SynthesisResultSchema);
      }

      if (!data) {
@@ -14,7 +14,6 @@ import { z } from 'zod';

 import { createSimpleClient } from '../../client/factory';
 import type { ModelShorthand, ThinkingLevel } from '../../config/types';
-import { withRateLimitRetry } from '../../session/rate-limit-retry';
 import { parseLLMJson } from '../../schema/structured-output';
 import {
  ScanResultSchema,
@@ -519,24 +518,24 @@ ${diff}
  });

  if (reviewPass === ReviewPass.QUICK_SCAN) {
-    const result = await withRateLimitRetry(() => generateText({
+    const result = await generateText({
      model: client.model,
      system: client.systemPrompt,
      prompt: fullPrompt,
      output: Output.object({ schema: ScanResultOutputSchema }),
-    }));
+    });
    if (result.output) {
      return result.output as ScanResult;
    }
    return parseScanResult(result.text);
  }

-  const result = await withRateLimitRetry(() => generateText({
+  const result = await generateText({
    model: client.model,
    system: client.systemPrompt,
    prompt: fullPrompt,
    output: Output.object({ schema: ReviewFindingsOutputSchema }),
-  }));
+  });
  if (result.output) {
    return result.output.findings as PRReviewFinding[];
  }
@@ -561,12 +560,12 @@ async function runStructuralPass(
  });

  try {
-    const result = await withRateLimitRetry(() => generateText({
+    const result = await generateText({
      model: client.model,
      system: client.systemPrompt,
      prompt: fullPrompt,
      output: Output.object({ schema: StructuralIssuesOutputSchema }),
-    }));
+    });
    if (result.output) {
      return result.output.issues as StructuralIssue[];
    }
@@ -597,12 +596,12 @@ async function runAITriagePass(
  });

  try {
-    const result = await withRateLimitRetry(() => generateText({
+    const result = await generateText({
      model: client.model,
      system: client.systemPrompt,
      prompt: fullPrompt,
      output: Output.object({ schema: AICommentTriagesOutputSchema }),
-    }));
+    });
    if (result.output) {
      return result.output.triages as AICommentTriage[];
    }
@@ -382,7 +382,7 @@ ${diffContent}
    }

    lines.push('---');
-    lines.push('_Generated by Auto Claude MR Review_');
+    lines.push('_Generated by Aperant MR Review_');

    return lines.join('\n');
  }
@@ -19,8 +19,6 @@ import { buildToolRegistry } from '../tools/build-registry';
 import type { ToolContext } from '../tools/types';
 import type { ModelShorthand, ThinkingLevel } from '../config/types';
 import type { SecurityProfile } from '../security/bash-validator';
-import { withRateLimitRetry } from '../session/rate-limit-retry';
-import { formatWaitDuration } from '../session/rate-limit-wait';

 // =============================================================================
 // Constants
@@ -99,7 +97,6 @@ export type IdeationStreamCallback = (event: IdeationStreamEvent) => void;
 export type IdeationStreamEvent =
  | { type: 'text-delta'; text: string }
  | { type: 'tool-use'; name: string }
-  | { type: 'status'; text: string }
  | { type: 'error'; error: string };

 // =============================================================================
@@ -189,48 +186,42 @@ export async function runIdeation(
  const userPrompt = `Analyze the project at ${projectDir} and generate up to ${maxIdeasPerType} ${ideationType.replace(/_/g, ' ')} ideas. Use the available tools to explore the codebase, then write your findings as a JSON file to the output directory.`;

  try {
-    await withRateLimitRetry(async () => {
-      responseText = '';
-      const result = streamText({
-        model: client.model,
-        system: isCodex ? undefined : prompt,
-        prompt: userPrompt,
-        tools: client.tools,
-        stopWhen: stepCountIs(client.maxSteps),
-        abortSignal,
-        ...(isCodex ? {
-          providerOptions: {
-            openai: {
-              instructions: prompt,
-              store: false,
-            },
+    const result = streamText({
+      model: client.model,
+      system: isCodex ? undefined : prompt,
+      prompt: userPrompt,
+      tools: client.tools,
+      stopWhen: stepCountIs(client.maxSteps),
+      abortSignal,
+      ...(isCodex ? {
+        providerOptions: {
+          openai: {
+            instructions: prompt,
+            store: false,
          },
-        } : {}),
-      });
+        },
+      } : {}),
+    });

-      for await (const part of result.fullStream) {
-        switch (part.type) {
-          case 'text-delta': {
-            responseText += part.text;
-            onStream?.({ type: 'text-delta', text: part.text });
-            break;
-          }
-          case 'tool-call': {
-            onStream?.({ type: 'tool-use', name: part.toolName });
-            break;
-          }
-          case 'error': {
-            const errorMsg =
-              part.error instanceof Error ? part.error.message : String(part.error);
-            onStream?.({ type: 'error', error: errorMsg });
-            break;
-          }
+    for await (const part of result.fullStream) {
+      switch (part.type) {
+        case 'text-delta': {
+          responseText += part.text;
+          onStream?.({ type: 'text-delta', text: part.text });
+          break;
+        }
+        case 'tool-call': {
+          onStream?.({ type: 'tool-use', name: part.toolName });
+          break;
+        }
+        case 'error': {
+          const errorMsg =
+            part.error instanceof Error ? part.error.message : String(part.error);
+          onStream?.({ type: 'error', error: errorMsg });
+          break;
        }
      }
-    }, {
-      signal: abortSignal,
-      onWaiting: (waitMs) => onStream?.({ type: 'status', text: `Rate limited. Waiting ${formatWaitDuration(waitMs)}...` }),
-    });
+    }

    return {
      success: true,
@@ -15,9 +15,6 @@ import { streamText, stepCountIs } from 'ai';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';

-import { withRateLimitRetry } from '../session/rate-limit-retry';
-import { formatWaitDuration } from '../session/rate-limit-wait';
-
 import { createSimpleClient } from '../client/factory';
 import { buildToolRegistry } from '../tools/build-registry';
 import type { ToolContext } from '../tools/types';
@@ -88,7 +85,6 @@ export type InsightsStreamEvent =
  | { type: 'text-delta'; text: string }
  | { type: 'tool-start'; name: string; input: string }
  | { type: 'tool-end'; name: string }
-  | { type: 'status'; text: string }
  | { type: 'error'; error: string };

 // =============================================================================
@@ -276,59 +272,48 @@ export async function runInsightsQuery(
  const isCodexInsights = insightsModelId?.includes('codex') ?? false;

  try {
-    await withRateLimitRetry(
-      async () => {
-        responseText = '';
-        toolCalls.length = 0;
-        const result = streamText({
-          model: client.model,
-          system: isCodexInsights ? undefined : client.systemPrompt,
-          prompt: fullPrompt,
-          tools: client.tools,
-          stopWhen: stepCountIs(client.maxSteps),
-          abortSignal,
-          ...(isCodexInsights ? {
-            providerOptions: {
-              openai: {
-                instructions: client.systemPrompt,
-                store: false,
-              },
-            },
-          } : {}),
-        });
+    const result = streamText({
+      model: client.model,
+      system: isCodexInsights ? undefined : client.systemPrompt,
+      prompt: fullPrompt,
+      tools: client.tools,
+      stopWhen: stepCountIs(client.maxSteps),
+      abortSignal,
+      ...(isCodexInsights ? {
+        providerOptions: {
+          openai: {
+            instructions: client.systemPrompt,
+            store: false,
+          },
+        },
+      } : {}),
+    });

-        for await (const part of result.fullStream) {
-          switch (part.type) {
-            case 'text-delta': {
-              responseText += part.text;
-              onStream?.({ type: 'text-delta', text: part.text });
-              break;
-            }
-            case 'tool-call': {
-              const args = 'input' in part ? (part.input as Record<string, unknown>) : {};
-              const input = extractToolInput(args);
-              toolCalls.push({ name: part.toolName, input });
-              onStream?.({ type: 'tool-start', name: part.toolName, input });
-              break;
-            }
-            case 'tool-result': {
-              onStream?.({ type: 'tool-end', name: part.toolName });
-              break;
-            }
-            case 'error': {
-              const errorMsg = part.error instanceof Error ? part.error.message : String(part.error);
-              onStream?.({ type: 'error', error: errorMsg });
-              break;
-            }
-          }
+    for await (const part of result.fullStream) {
+      switch (part.type) {
+        case 'text-delta': {
+          responseText += part.text;
+          onStream?.({ type: 'text-delta', text: part.text });
+          break;
        }
-      },
-      {
-        signal: abortSignal,
-        onWaiting: (waitMs) =>
-          onStream?.({ type: 'status', text: `Rate limited. Waiting ${formatWaitDuration(waitMs)}...` }),
-      },
-    );
+        case 'tool-call': {
+          const args = 'input' in part ? (part.input as Record<string, unknown>) : {};
+          const input = extractToolInput(args);
+          toolCalls.push({ name: part.toolName, input });
+          onStream?.({ type: 'tool-start', name: part.toolName, input });
+          break;
+        }
+        case 'tool-result': {
+          onStream?.({ type: 'tool-end', name: part.toolName });
+          break;
+        }
+        case 'error': {
+          const errorMsg = part.error instanceof Error ? part.error.message : String(part.error);
+          onStream?.({ type: 'error', error: errorMsg });
+          break;
+        }
+      }
+    }
  } catch (error) {
    const errorMsg = error instanceof Error ? error.message : String(error);
    onStream?.({ type: 'error', error: errorMsg });
@@ -21,8 +21,6 @@ import type { ModelShorthand, ThinkingLevel } from '../config/types';
 import type { SecurityProfile } from '../security/bash-validator';
 import { safeParseJson } from '../../utils/json-repair';
 import { tryLoadPrompt } from '../prompts/prompt-loader';
-import { withRateLimitRetry } from '../session/rate-limit-retry';
-import { formatWaitDuration } from '../session/rate-limit-wait';

 // =============================================================================
 // Constants
@@ -88,7 +86,6 @@ export type RoadmapStreamEvent =
  | { type: 'phase-complete'; phase: string; success: boolean }
  | { type: 'text-delta'; text: string }
  | { type: 'tool-use'; name: string }
-  | { type: 'status'; text: string }
  | { type: 'error'; error: string };

 // =============================================================================
@@ -148,43 +145,38 @@ Do NOT ask questions. Make educated inferences and create the file.`;
    const discoveryUserPrompt = 'Analyze the project and create the discovery document. Use the available tools to explore the codebase, then write your findings as JSON to the output file specified in the context above.';

    try {
-      await withRateLimitRetry(async () => {
-        const result = streamText({
-          model: client.model,
-          system: isCodexDiscovery ? undefined : prompt,
-          prompt: discoveryUserPrompt,
-          tools: client.tools,
-          stopWhen: stepCountIs(client.maxSteps),
-          abortSignal,
-          ...(isCodexDiscovery ? {
-            providerOptions: {
-              openai: {
-                instructions: prompt,
-                store: false,
-              },
+      const result = streamText({
+        model: client.model,
+        system: isCodexDiscovery ? undefined : prompt,
+        prompt: discoveryUserPrompt,
+        tools: client.tools,
+        stopWhen: stepCountIs(client.maxSteps),
+        abortSignal,
+        ...(isCodexDiscovery ? {
+          providerOptions: {
+            openai: {
+              instructions: prompt,
+              store: false,
            },
-          } : {}),
-        });
+          },
+        } : {}),
+      });

-        for await (const part of result.fullStream) {
-          switch (part.type) {
-            case 'text-delta':
-              onStream?.({ type: 'text-delta', text: part.text });
-              break;
-            case 'tool-call':
-              onStream?.({ type: 'tool-use', name: part.toolName });
-              break;
-            case 'error': {
-              const errorMsg = part.error instanceof Error ? part.error.message : String(part.error);
-              onStream?.({ type: 'error', error: errorMsg });
-              break;
-            }
+      for await (const part of result.fullStream) {
+        switch (part.type) {
+          case 'text-delta':
+            onStream?.({ type: 'text-delta', text: part.text });
+            break;
+          case 'tool-call':
+            onStream?.({ type: 'tool-use', name: part.toolName });
+            break;
+          case 'error': {
+            const errorMsg = part.error instanceof Error ? part.error.message : String(part.error);
+            onStream?.({ type: 'error', error: errorMsg });
+            break;
          }
        }
-      }, {
-        signal: abortSignal,
-        onWaiting: (waitMs) => onStream?.({ type: 'status', text: `Rate limited. Waiting ${formatWaitDuration(waitMs)}...` }),
-      });
+      }

      // Validate output
      if (existsSync(discoveryFile)) {
@@ -285,43 +277,38 @@ The JSON must contain: vision, target_audience (object with "primary" key), phas
    const featuresUserPrompt = 'Read the discovery data and generate a complete roadmap with prioritized features. Write the roadmap JSON to the output file specified in the context above.';

    try {
-      await withRateLimitRetry(async () => {
-        const result = streamText({
-          model: client.model,
-          system: isCodexFeatures ? undefined : prompt,
-          prompt: featuresUserPrompt,
-          tools: client.tools,
-          stopWhen: stepCountIs(client.maxSteps),
-          abortSignal,
-          ...(isCodexFeatures ? {
-            providerOptions: {
-              openai: {
-                instructions: prompt,
-                store: false,
-              },
+      const result = streamText({
+        model: client.model,
+        system: isCodexFeatures ? undefined : prompt,
+        prompt: featuresUserPrompt,
+        tools: client.tools,
+        stopWhen: stepCountIs(client.maxSteps),
+        abortSignal,
+        ...(isCodexFeatures ? {
+          providerOptions: {
+            openai: {
+              instructions: prompt,
+              store: false,
            },
-          } : {}),
-        });
+          },
+        } : {}),
+      });

-        for await (const part of result.fullStream) {
-          switch (part.type) {
-            case 'text-delta':
-              onStream?.({ type: 'text-delta', text: part.text });
-              break;
-            case 'tool-call':
-              onStream?.({ type: 'tool-use', name: part.toolName });
-              break;
-            case 'error': {
-              const errorMsg = part.error instanceof Error ? part.error.message : String(part.error);
-              onStream?.({ type: 'error', error: errorMsg });
-              break;
-            }
+      for await (const part of result.fullStream) {
+        switch (part.type) {
+          case 'text-delta':
+            onStream?.({ type: 'text-delta', text: part.text });
+            break;
+          case 'tool-call':
+            onStream?.({ type: 'tool-use', name: part.toolName });
+            break;
+          case 'error': {
+            const errorMsg = part.error instanceof Error ? part.error.message : String(part.error);
+            onStream?.({ type: 'error', error: errorMsg });
+            break;
          }
        }
-      }, {
-        signal: abortSignal,
-        onWaiting: (waitMs) => onStream?.({ type: 'status', text: `Rate limited. Waiting ${formatWaitDuration(waitMs)}...` }),
-      });
+      }

      // Validate and merge — read/write through fd to avoid TOCTOU
      let roadmapRaw: string | null = null;
@@ -87,7 +87,7 @@ const BLOCKED_PROCESS_NAMES = new Set([
  'electron',
  'Electron',
  'auto-claude',
-  'Auto Claude',
+  'Aperant',
 ]);

 // ---------------------------------------------------------------------------
@@ -13,8 +13,6 @@
 * - generic: Everything else
 */

-import { APICallError } from '@ai-sdk/provider';
-
 import type { SessionError, SessionOutcome } from './types';

 // =============================================================================
@@ -98,7 +96,6 @@ export function isBillingError(error: unknown): boolean {
 */
 export function isRateLimitError(error: unknown): boolean {
  if (isBillingError(error)) return false;
-  if (APICallError.isInstance(error) && error.statusCode === 429) return true;
  const errorStr = errorToString(error);
  if (WORD_BOUNDARY_429.test(errorStr)) return true;
  return RATE_LIMIT_PATTERNS.some((p) => errorStr.includes(p));
@@ -108,7 +105,6 @@ export function isRateLimitError(error: unknown): boolean {
 * Check if an error is an authentication error (401 or similar).
 */
 export function isAuthenticationError(error: unknown): boolean {
-  if (APICallError.isInstance(error) && error.statusCode === 401) return true;
  const errorStr = errorToString(error);
  if (WORD_BOUNDARY_401.test(errorStr)) return true;
  return AUTH_PATTERNS.some((p) => errorStr.includes(p));
@@ -118,14 +114,6 @@ export function isAuthenticationError(error: unknown): boolean {
 * Check if an error is a 400 tool concurrency error from Claude API.
 */
 export function isToolConcurrencyError(error: unknown): boolean {
-  if (APICallError.isInstance(error) && error.statusCode === 400) {
-    const errorStr = errorToString(error);
-    return (
-      (errorStr.includes('tool') && errorStr.includes('concurrency')) ||
-      errorStr.includes('too many tools') ||
-      errorStr.includes('concurrent tool')
-    );
-  }
  const errorStr = errorToString(error);
  return (
    /\b400\b/.test(errorStr) &&
@@ -1,81 +0,0 @@
-/**
- * Rate Limit Retry Wrapper
- * ========================
- *
- * Wraps AI calls (streamText, generateText) with rate-limit-aware retry logic.
- * When all accounts are exhausted and the auto-swap middleware can't recover,
- * this utility waits for the rate limit to reset and retries the operation.
- *
- * Usage:
- * ```ts
- * const result = await withRateLimitRetry(
- *   () => generateText({ model, prompt, ... }),
- *   { signal: abortSignal, onWaiting: (ms) => onStream?.({ type: 'status', text: `Rate limited, waiting...` }) }
- * );
- * ```
- */
-
-import { isRateLimitError } from './error-classifier';
-import { extractWaitDuration, formatWaitDuration, sleepWithAbort } from './rate-limit-wait';
-
-/** Maximum retries after rate limit waits */
-const MAX_RATE_LIMIT_RETRIES = 3;
-
-export interface RateLimitRetryOptions {
-  /** Abort signal to cancel the wait */
-  signal?: AbortSignal;
-  /** Maximum retries (default: 3) */
-  maxRetries?: number;
-  /** Called when entering a rate-limit wait, with the wait duration in ms */
-  onWaiting?: (waitMs: number, retryCount: number) => void;
-  /** Called when a wait completes and the operation is being retried */
-  onRetry?: (retryCount: number) => void;
-}
-
-/**
- * Execute an async operation with rate-limit-aware retry.
- *
- * If the operation throws a rate limit error (after the auto-swap middleware
- * has already exhausted its options), this waits for the reset and retries.
- * Weekly limits (too long to wait) are NOT retried — they throw immediately.
- */
-export async function withRateLimitRetry<T>(
-  fn: () => Promise<T>,
-  options?: RateLimitRetryOptions,
-): Promise<T> {
-  const maxRetries = options?.maxRetries ?? MAX_RATE_LIMIT_RETRIES;
-
-  for (let attempt = 0; ; attempt++) {
-    try {
-      return await fn();
-    } catch (error) {
-      if (!isRateLimitError(error)) {
-        console.log('[AutoSwap:Retry] Non-rate-limit error — not retrying:', error instanceof Error ? error.message : String(error));
-        throw error;
-      }
-      if (attempt >= maxRetries) {
-        console.log('[AutoSwap:Retry] Max retries reached (' + maxRetries + ') — giving up');
-        throw error;
-      }
-
-      const waitInfo = extractWaitDuration(error);
-      // Weekly limits or unextractable — don't wait
-      if (!waitInfo) {
-        console.log('[AutoSwap:Retry] Cannot extract wait duration — not retrying (weekly limit?)');
-        throw error;
-      }
-
-      console.log('[AutoSwap:Retry] Rate limit hit (attempt', attempt + 1 + '/' + maxRetries + '). Waiting', formatWaitDuration(waitInfo.waitMs), '(type:', waitInfo.limitType + ')');
-      options?.onWaiting?.(waitInfo.waitMs, attempt + 1);
-
-      const completed = await sleepWithAbort(waitInfo.waitMs, options?.signal);
-      if (!completed) {
-        console.log('[AutoSwap:Retry] Wait aborted — not retrying');
-        throw error;
-      }
-
-      console.log('[AutoSwap:Retry] Wait complete — retrying (attempt', attempt + 2 + ')');
-      options?.onRetry?.(attempt + 1);
-    }
-  }
-}
@@ -1,187 +0,0 @@
-/**
- * Rate Limit Wait-and-Retry
- * =========================
- *
- * Shared utility for extracting wait duration from rate limit errors
- * and sleeping with cancellation support.
- *
- * Used by both:
- * - Session runner (task pipeline: planner, coder, QA)
- * - Auto-swap middleware (standalone runners: insights, roadmap, PR review, etc.)
- *
- * When a 429 occurs and no swap target is available, this module extracts
- * how long to wait from the error and sleeps until the rate limit resets.
- */
-
-import { APICallError } from '@ai-sdk/provider';
-import { parseResetTime, classifyRateLimitType } from '../../claude-profile/usage-parser';
-
-// =============================================================================
-// Constants
-// =============================================================================
-
-/** Maximum time to auto-wait for a rate limit reset (30 minutes) */
-const MAX_RATE_LIMIT_WAIT_MS = 30 * 60 * 1000;
-
-/** Default wait time when no reset info is available (5 minutes) */
-const DEFAULT_WAIT_MS = 5 * 60 * 1000;
-
-/** Minimum wait time to avoid tight retry loops (30 seconds) */
-const MIN_WAIT_MS = 30 * 1000;
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface WaitDurationInfo {
-  /** How long to wait in milliseconds */
-  waitMs: number;
-  /** When the rate limit resets (if known) */
-  resetAt: Date | null;
-  /** Whether this is a session or weekly limit */
-  limitType: 'session' | 'weekly';
-}
-
-// =============================================================================
-// Wait Duration Extraction
-// =============================================================================
-
-/**
- * Extract wait duration from a rate limit error.
- *
- * Priority order:
- * 1. `Retry-After` header (seconds or HTTP-date)
- * 2. Reset time string from error message (e.g., "resets Dec 17 at 6am")
- * 3. Fallback: 5 minutes (only when no extraction attempted — i.e., no reset info found)
- *
- * Returns null for weekly limits (too long to auto-wait) or when message extraction
- * explicitly detected a weekly limit and declined to provide a wait time.
- */
-export function extractWaitDuration(error: unknown): WaitDurationInfo | null {
-  // Try Retry-After header from APICallError
-  const headerWait = extractFromRetryAfterHeader(error);
-  if (headerWait) return headerWait;
-
-  // Try reset time from error message
-  // extractFromErrorMessage returns null for weekly limits — don't fall back in that case
-  const message = error instanceof Error ? error.message : String(error);
-  const hasResetPattern = /resets?\s+/i.test(message);
-  if (hasResetPattern) {
-    // Extraction was attempted; trust its result (null = weekly limit, don't wait)
-    return extractFromErrorMessage(error);
-  }
-
-  // No reset info found at all — fall back to 5 minutes (safe default for session limits)
-  return {
-    waitMs: DEFAULT_WAIT_MS,
-    resetAt: new Date(Date.now() + DEFAULT_WAIT_MS),
-    limitType: 'session',
-  };
-}
-
-/**
- * Extract wait duration from Retry-After response header.
- * Supports both seconds (e.g., "120") and HTTP-date (e.g., "Thu, 01 Dec 2025 16:00:00 GMT").
- */
-function extractFromRetryAfterHeader(error: unknown): WaitDurationInfo | null {
-  if (!APICallError.isInstance(error)) return null;
-  const retryAfter = error.responseHeaders?.['retry-after'];
-  if (!retryAfter) return null;
-
-  // Try as seconds
-  const seconds = Number(retryAfter);
-  if (!Number.isNaN(seconds) && seconds > 0) {
-    const waitMs = clampWaitMs(seconds * 1000);
-    return {
-      waitMs,
-      resetAt: new Date(Date.now() + waitMs),
-      limitType: 'session',
-    };
-  }
-
-  // Try as HTTP-date
-  const date = new Date(retryAfter);
-  if (!Number.isNaN(date.getTime())) {
-    const waitMs = clampWaitMs(date.getTime() - Date.now());
-    return {
-      waitMs,
-      resetAt: date,
-      limitType: 'session',
-    };
-  }
-
-  return null;
-}
-
-/**
- * Extract wait duration from error message patterns.
- * Looks for reset time strings like "resets Dec 17 at 6am (Europe/Oslo)".
- */
-function extractFromErrorMessage(error: unknown): WaitDurationInfo | null {
-  const message = error instanceof Error ? error.message : String(error);
-
-  // Look for reset time pattern: "resets <datetime>" or "Resets <datetime>"
-  const resetMatch = message.match(/resets?\s+(.+?)(?:\s*\.|$|\n)/i);
-  if (!resetMatch) return null;
-
-  const resetTimeStr = resetMatch[1].trim();
-  const limitType = classifyRateLimitType(resetTimeStr);
-
-  // Don't auto-wait for weekly limits — too long
-  if (limitType === 'weekly') return null;
-
-  const resetAt = parseResetTime(resetTimeStr);
-  const waitMs = clampWaitMs(resetAt.getTime() - Date.now());
-
-  return { waitMs, resetAt, limitType };
-}
-
-// =============================================================================
-// Sleep with Abort
-// =============================================================================
-
-/**
- * Sleep for the given duration, but cancel early if the abort signal fires.
- * Returns true if sleep completed normally, false if aborted.
- */
-export function sleepWithAbort(ms: number, signal?: AbortSignal): Promise<boolean> {
-  if (signal?.aborted) return Promise.resolve(false);
-
-  return new Promise<boolean>((resolve) => {
-    const timer = setTimeout(() => {
-      signal?.removeEventListener('abort', onAbort);
-      resolve(true);
-    }, ms);
-
-    function onAbort() {
-      clearTimeout(timer);
-      resolve(false);
-    }
-
-    signal?.addEventListener('abort', onAbort, { once: true });
-  });
-}
-
-// =============================================================================
-// Formatting
-// =============================================================================
-
-/**
- * Format a duration in milliseconds to a human-readable string.
- */
-export function formatWaitDuration(ms: number): string {
-  const totalSeconds = Math.ceil(ms / 1000);
-  if (totalSeconds < 60) return `${totalSeconds}s`;
-  const minutes = Math.floor(totalSeconds / 60);
-  const seconds = totalSeconds % 60;
-  if (seconds === 0) return `${minutes}m`;
-  return `${minutes}m ${seconds}s`;
-}
-
-// =============================================================================
-// Helpers
-// =============================================================================
-
-function clampWaitMs(ms: number): number {
-  return Math.max(MIN_WAIT_MS, Math.min(ms, MAX_RATE_LIMIT_WAIT_MS));
-}
@@ -27,7 +27,6 @@ import { buildThinkingProviderOptions } from '../config/types';
 import { createStreamHandler } from './stream-handler';
 import type { FullStreamPart } from './stream-handler';
 import { classifyError, isAuthenticationError, isRateLimitError } from './error-classifier';
-import { extractWaitDuration, sleepWithAbort, formatWaitDuration } from './rate-limit-wait';
 import { ProgressTracker } from './progress-tracker';
 import type {
  SessionConfig,
@@ -197,19 +196,7 @@ export async function runAgentSession(
          activeAccountId = newAuth.accountId;
          continue;
        }
-        // No more accounts available — try wait-and-retry for session limits
-        if (isRateLimitError(error)) {
-          const waitInfo = extractWaitDuration(error);
-          if (waitInfo) {
-            onEvent?.({
-              type: 'status',
-              text: `Rate limited. Waiting ${formatWaitDuration(waitInfo.waitMs)} for reset...`,
-            });
-            const completed = await sleepWithAbort(waitInfo.waitMs, activeConfig.abortSignal);
-            if (completed) continue; // Retry after wait
-            // Aborted during wait — fall through to error
-          }
-        }
+        // No more accounts available — fall through to legacy retry
      }

      // Legacy auth refresh (single-provider token refresh)
@@ -376,7 +363,6 @@ async function executeStream(

  const result = streamText({
    model: config.model,
-    maxRetries: 0, // Prevent AI SDK from retrying against same rate-limited account — our catch block handles retry with account switching
    system: isCodex ? undefined : config.systemPrompt,
    messages: aiMessages,
    tools: tools ?? {},
@@ -170,8 +170,7 @@ export type StreamEvent =
  | ToolResultEvent
  | StepFinishEvent
  | ErrorEvent
-  | UsageUpdateEvent
-  | StatusEvent;
+  | UsageUpdateEvent;

 /** Incremental text output from the model */
 export interface TextDeltaEvent {
@@ -222,12 +221,6 @@ export interface UsageUpdateEvent {
  usage: TokenUsage;
 }

-/** Status update (e.g., waiting for rate limit reset) */
-export interface StatusEvent {
-  type: 'status';
-  text: string;
-}
-
 // =============================================================================
 // Progress State
 // =============================================================================
@@ -0,0 +1,249 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import { bashTool } from '../bash';
+import type { ToolContext } from '../../types';
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+const mockExecFile = vi.fn();
+vi.mock('node:child_process', () => ({
+  execFile: (...args: unknown[]) => mockExecFile(...args),
+}));
+
+const mockIsWindows = vi.fn(() => false);
+const mockFindExecutable = vi.fn(() => null);
+const mockKillProcessGracefully = vi.fn();
+
+vi.mock('../../../../platform/index', () => ({
+  isWindows: () => mockIsWindows(),
+  findExecutable: (_name: string, _additionalPaths?: string[]) => mockFindExecutable(),
+  killProcessGracefully: (_childProcess: unknown, _options?: unknown) => mockKillProcessGracefully(),
+}));
+
+const mockBashSecurityHook = vi.fn(() => ({}));
+vi.mock('../../../security/bash-validator', () => ({
+  bashSecurityHook: (_input: unknown, _profile?: unknown) => mockBashSecurityHook(),
+}));
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const baseContext: ToolContext = {
+  cwd: '/test/project',
+  projectDir: '/test/project',
+  specDir: '/test/specs/001',
+  securityProfile: {
+    baseCommands: new Set(),
+    stackCommands: new Set(),
+    scriptCommands: new Set(),
+    customCommands: new Set(),
+    customScripts: { shellScripts: [] },
+    getAllAllowedCommands: () => new Set(),
+  },
+} as unknown as ToolContext;
+
+/**
+ * Set up mockExecFile to invoke the callback with the provided values.
+ */
+function setupExecFile(stdout: string, stderr: string, exitCode: number) {
+  mockExecFile.mockImplementation(
+    (_shell: unknown, _args: unknown, _opts: unknown, callback: (err: Error | null, stdout: string, stderr: string) => void) => {
+      const err = exitCode !== 0 ? Object.assign(new Error('exit'), { code: exitCode }) : null;
+      callback(err, stdout, stderr);
+      return { pid: 1234 };
+    },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('Bash Tool', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockIsWindows.mockReturnValue(false);
+    mockBashSecurityHook.mockReturnValue({});
+  });
+
+  it('should have correct metadata', () => {
+    expect(bashTool.metadata.name).toBe('Bash');
+    expect(bashTool.metadata.permission).toBe('requires_approval');
+  });
+
+  it('should return stdout from successful command', async () => {
+    setupExecFile('hello from bash\n', '', 0);
+
+    const result = await bashTool.config.execute(
+      { command: 'echo hello from bash' },
+      baseContext,
+    );
+
+    expect(result).toContain('hello from bash');
+  });
+
+  it('should include stderr in output when present', async () => {
+    setupExecFile('', 'some warning\n', 0);
+
+    const result = await bashTool.config.execute(
+      { command: 'cmd-with-stderr' },
+      baseContext,
+    );
+
+    expect(result).toContain('STDERR:');
+    expect(result).toContain('some warning');
+  });
+
+  it('should include exit code in output when non-zero', async () => {
+    setupExecFile('', '', 1);
+
+    const result = await bashTool.config.execute(
+      { command: 'failing-command' },
+      baseContext,
+    );
+
+    expect(result).toContain('Exit code: 1');
+  });
+
+  it('should return (no output) when stdout and stderr are empty and exit code is 0', async () => {
+    setupExecFile('', '', 0);
+
+    const result = await bashTool.config.execute(
+      { command: 'silent-command' },
+      baseContext,
+    );
+
+    expect(result).toBe('(no output)');
+  });
+
+  it('should truncate output exceeding MAX_OUTPUT_LENGTH', async () => {
+    const longOutput = 'x'.repeat(31_000);
+    setupExecFile(longOutput, '', 0);
+
+    const result = await bashTool.config.execute(
+      { command: 'long-output-cmd' },
+      baseContext,
+    );
+
+    expect(result).toContain('[Output truncated');
+    expect(result.length).toBeLessThan(longOutput.length);
+  });
+
+  it('should return error message when security hook rejects command', async () => {
+    mockBashSecurityHook.mockReturnValue({
+      hookSpecificOutput: {
+        permissionDecisionReason: 'command is blocked for safety',
+      },
+    });
+
+    const result = await bashTool.config.execute(
+      { command: 'rm -rf /' },
+      baseContext,
+    );
+
+    expect(result).toContain('Error: Command not allowed');
+    expect(result).toContain('command is blocked for safety');
+    expect(mockExecFile).not.toHaveBeenCalled();
+  });
+
+  it('should start command in background and return immediately', async () => {
+    // In background mode the execute call is fire-and-forget, so mockExecFile
+    // may or may not be called synchronously. The return value is what matters.
+    mockExecFile.mockImplementation(
+      (_shell: unknown, _args: unknown, _opts: unknown, _callback: unknown) => {
+        return { pid: 5678 };
+      },
+    );
+
+    const result = await bashTool.config.execute(
+      { command: 'sleep 100', run_in_background: true },
+      baseContext,
+    );
+
+    expect(result).toContain('Command started in background');
+    expect(result).toContain('sleep 100');
+  });
+
+  it('should pass cwd from context to execFile', async () => {
+    setupExecFile('output', '', 0);
+
+    await bashTool.config.execute(
+      { command: 'pwd' },
+      baseContext,
+    );
+
+    expect(mockExecFile).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.any(Array),
+      expect.objectContaining({ cwd: '/test/project' }),
+      expect.any(Function),
+    );
+  });
+
+  it('should cap timeout to MAX_TIMEOUT_MS (600000)', async () => {
+    setupExecFile('output', '', 0);
+
+    await bashTool.config.execute(
+      { command: 'cmd', timeout: 9_000_000 },
+      baseContext,
+    );
+
+    expect(mockExecFile).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.any(Array),
+      expect.objectContaining({ timeout: 600_000 }),
+      expect.any(Function),
+    );
+  });
+
+  it('should use /bin/bash as shell on non-Windows', async () => {
+    mockIsWindows.mockReturnValue(false);
+    setupExecFile('output', '', 0);
+
+    await bashTool.config.execute(
+      { command: 'echo hi' },
+      baseContext,
+    );
+
+    expect(mockExecFile).toHaveBeenCalledWith(
+      '/bin/bash',
+      ['-c', 'echo hi'],
+      expect.any(Object),
+      expect.any(Function),
+    );
+  });
+
+  it('should use cmd.exe args (/c) on Windows when bash not found', async () => {
+    // The Windows branch uses /c rather than -c for cmd.exe.
+    // We verify the logic by checking that bash uses -c on non-Windows (already tested
+    // above) and that the findExecutable mock would select the right executable.
+    // This test validates the cmd.exe ComSpec fallback resolution path.
+    mockIsWindows.mockReturnValue(true);
+    mockFindExecutable.mockReturnValue(null);
+
+    const origComSpec = process.env.ComSpec;
+    process.env.ComSpec = 'C:\\Windows\\System32\\cmd.exe';
+
+    setupExecFile('output', '', 0);
+
+    await bashTool.config.execute(
+      { command: 'dir' },
+      baseContext,
+    );
+
+    // Verify that on Windows with no bash found, cmd.exe with /c flag is used
+    const callArgs = mockExecFile.mock.calls[0];
+    const shell = callArgs[0] as string;
+    const args = callArgs[1] as string[];
+
+    // The shell should be cmd.exe (via ComSpec) and arg should be /c
+    expect(shell).toBe('C:\\Windows\\System32\\cmd.exe');
+    expect(args[0]).toBe('/c');
+    expect(args[1]).toBe('dir');
+
+    process.env.ComSpec = origComSpec;
+  });
+});
@@ -0,0 +1,220 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import { editTool } from '../edit';
+import type { ToolContext } from '../../types';
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+vi.mock('node:fs');
+vi.mock('../../../security/path-containment', () => ({
+  assertPathContained: vi.fn((_filePath: string, _projectDir: string) => ({
+    contained: true,
+    resolvedPath: _filePath,
+  })),
+}));
+
+import * as fs from 'node:fs';
+import { assertPathContained } from '../../../security/path-containment';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const baseContext: ToolContext = {
+  cwd: '/test/project',
+  projectDir: '/test/project',
+  specDir: '/test/specs/001',
+  securityProfile: {
+    baseCommands: new Set(),
+    stackCommands: new Set(),
+    scriptCommands: new Set(),
+    customCommands: new Set(),
+    customScripts: { shellScripts: [] },
+    getAllAllowedCommands: () => new Set(),
+  },
+} as unknown as ToolContext;
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('Edit Tool', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(assertPathContained).mockImplementation((_filePath: string, _projectDir: string) => ({
+      contained: true,
+      resolvedPath: _filePath,
+    }));
+  });
+
+  it('should have correct metadata', () => {
+    expect(editTool.metadata.name).toBe('Edit');
+    expect(editTool.metadata.permission).toBe('requires_approval');
+  });
+
+  it('should successfully replace a single occurrence', async () => {
+    vi.mocked(fs.readFileSync).mockReturnValue('hello world foo bar');
+    vi.mocked(fs.writeFileSync).mockImplementation(() => undefined);
+
+    const result = await editTool.config.execute(
+      {
+        file_path: '/test/project/file.ts',
+        old_string: 'hello world',
+        new_string: 'goodbye world',
+        replace_all: false,
+      },
+      baseContext,
+    );
+
+    expect(result).toContain('Successfully edited');
+    expect(fs.writeFileSync).toHaveBeenCalledWith(
+      '/test/project/file.ts',
+      'goodbye world foo bar',
+      'utf-8',
+    );
+  });
+
+  it('should replace all occurrences when replace_all is true', async () => {
+    vi.mocked(fs.readFileSync).mockReturnValue('foo bar foo baz foo');
+    vi.mocked(fs.writeFileSync).mockImplementation(() => undefined);
+
+    const result = await editTool.config.execute(
+      {
+        file_path: '/test/project/file.ts',
+        old_string: 'foo',
+        new_string: 'qux',
+        replace_all: true,
+      },
+      baseContext,
+    );
+
+    expect(result).toContain('Successfully replaced 3 occurrence(s)');
+    expect(fs.writeFileSync).toHaveBeenCalledWith(
+      '/test/project/file.ts',
+      'qux bar qux baz qux',
+      'utf-8',
+    );
+  });
+
+  it('should return error when old_string not found in file', async () => {
+    vi.mocked(fs.readFileSync).mockReturnValue('some other content');
+
+    const result = await editTool.config.execute(
+      {
+        file_path: '/test/project/file.ts',
+        old_string: 'nonexistent text',
+        new_string: 'replacement',
+        replace_all: false,
+      },
+      baseContext,
+    );
+
+    expect(result).toContain('Error: old_string not found');
+    expect(fs.writeFileSync).not.toHaveBeenCalled();
+  });
+
+  it('should return error when old_string matches multiple locations without replace_all', async () => {
+    vi.mocked(fs.readFileSync).mockReturnValue('foo foo foo');
+
+    const result = await editTool.config.execute(
+      {
+        file_path: '/test/project/file.ts',
+        old_string: 'foo',
+        new_string: 'bar',
+        replace_all: false,
+      },
+      baseContext,
+    );
+
+    expect(result).toContain('Error: old_string appears 3 times');
+    expect(result).toContain('replace_all: true');
+    expect(fs.writeFileSync).not.toHaveBeenCalled();
+  });
+
+  it('should return error when old_string equals new_string', async () => {
+    const result = await editTool.config.execute(
+      {
+        file_path: '/test/project/file.ts',
+        old_string: 'same text',
+        new_string: 'same text',
+        replace_all: false,
+      },
+      baseContext,
+    );
+
+    expect(result).toContain('Error: old_string and new_string are identical');
+    expect(fs.readFileSync).not.toHaveBeenCalled();
+    expect(fs.writeFileSync).not.toHaveBeenCalled();
+  });
+
+  it('should return error when file not found', async () => {
+    const enoentError = Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+    vi.mocked(fs.readFileSync).mockImplementation(() => { throw enoentError; });
+
+    const result = await editTool.config.execute(
+      {
+        file_path: '/test/project/missing.ts',
+        old_string: 'old',
+        new_string: 'new',
+        replace_all: false,
+      },
+      baseContext,
+    );
+
+    expect(result).toContain('Error: File not found');
+  });
+
+  it('should throw non-ENOENT filesystem errors', async () => {
+    const permError = Object.assign(new Error('EACCES'), { code: 'EACCES' });
+    vi.mocked(fs.readFileSync).mockImplementation(() => { throw permError; });
+
+    await expect(
+      editTool.config.execute(
+        {
+          file_path: '/test/project/file.ts',
+          old_string: 'old',
+          new_string: 'new',
+          replace_all: false,
+        },
+        baseContext,
+      ),
+    ).rejects.toThrow('EACCES');
+  });
+
+  it('should call assertPathContained for path security', async () => {
+    vi.mocked(fs.readFileSync).mockReturnValue('hello world');
+    vi.mocked(fs.writeFileSync).mockImplementation(() => undefined);
+
+    await editTool.config.execute(
+      {
+        file_path: '/test/project/file.ts',
+        old_string: 'hello world',
+        new_string: 'goodbye world',
+        replace_all: false,
+      },
+      baseContext,
+    );
+
+    expect(assertPathContained).toHaveBeenCalledWith('/test/project/file.ts', '/test/project');
+  });
+
+  it('should throw when path is outside project boundary', async () => {
+    vi.mocked(assertPathContained).mockImplementation(() => {
+      throw new Error("Path '/etc/passwd' is outside the project directory");
+    });
+
+    await expect(
+      editTool.config.execute(
+        {
+          file_path: '/etc/passwd',
+          old_string: 'root',
+          new_string: 'hacked',
+          replace_all: false,
+        },
+        baseContext,
+      ),
+    ).rejects.toThrow('outside the project directory');
+  });
+});
@@ -0,0 +1,221 @@
+import path from 'node:path';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import { globTool } from '../glob';
+import type { ToolContext } from '../../types';
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+vi.mock('node:fs');
+vi.mock('../../../security/path-containment', () => ({
+  assertPathContained: vi.fn((_filePath: string, _projectDir: string) => ({
+    contained: true,
+    resolvedPath: _filePath,
+  })),
+}));
+vi.mock('../../truncation', () => ({
+  truncateToolOutput: vi.fn((output: string) => ({
+    content: output,
+    wasTruncated: false,
+    originalSize: Buffer.byteLength(output, 'utf-8'),
+  })),
+}));
+
+import * as fs from 'node:fs';
+import { assertPathContained } from '../../../security/path-containment';
+import { truncateToolOutput } from '../../truncation';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const baseContext: ToolContext = {
+  cwd: '/test/project',
+  projectDir: '/test/project',
+  specDir: '/test/specs/001',
+  securityProfile: {
+    baseCommands: new Set(),
+    stackCommands: new Set(),
+    scriptCommands: new Set(),
+    customCommands: new Set(),
+    customScripts: { shellScripts: [] },
+    getAllAllowedCommands: () => new Set(),
+  },
+} as unknown as ToolContext;
+
+/**
+ * Configure fs mocks for a glob run that returns the given absolute paths.
+ * Each path gets a fake mtime so sorting can be tested.
+ */
+function setupGlobMatches(absolutePaths: string[], mtimes?: number[]) {
+  // existsSync for the search dir
+  vi.mocked(fs.existsSync).mockReturnValue(true);
+
+  // globSync returns relative filenames that the tool will resolve
+  const relPaths = absolutePaths.map((p) => p.replace('/test/project/', ''));
+  vi.mocked(fs.globSync).mockReturnValue(relPaths);
+
+  // statSync used twice: once to check isFile, once to get mtime
+  let callIdx = 0;
+  vi.mocked(fs.statSync).mockImplementation((_p) => {
+    const mtime = mtimes ? mtimes[callIdx % mtimes.length] : 1000;
+    callIdx++;
+    return {
+      isFile: () => true,
+      mtimeMs: mtime,
+    } as unknown as fs.Stats;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('Glob Tool', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(assertPathContained).mockImplementation((_filePath: string, _projectDir: string) => ({
+      contained: true,
+      resolvedPath: _filePath,
+    }));
+    vi.mocked(truncateToolOutput).mockImplementation((output: string) => ({
+      content: output,
+      wasTruncated: false,
+      originalSize: Buffer.byteLength(output, 'utf-8'),
+    }));
+  });
+
+  it('should have correct metadata', () => {
+    expect(globTool.metadata.name).toBe('Glob');
+    expect(globTool.metadata.permission).toBe('read_only');
+  });
+
+  it('should return matching file paths', async () => {
+    setupGlobMatches([
+      '/test/project/src/index.ts',
+      '/test/project/src/utils.ts',
+    ]);
+
+    const result = await globTool.config.execute(
+      { pattern: '**/*.ts' },
+      baseContext,
+    ) as string;
+
+    expect(result).toContain('index.ts');
+    expect(result).toContain('utils.ts');
+  });
+
+  it('should return "No files found" when pattern matches nothing', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.globSync).mockReturnValue([]);
+
+    const result = await globTool.config.execute(
+      { pattern: '**/*.nonexistent' },
+      baseContext,
+    );
+
+    expect(result).toBe('No files found');
+  });
+
+  it('should return error when search directory does not exist', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+
+    const result = await globTool.config.execute(
+      { pattern: '*.ts', path: '/test/project/missing-dir' },
+      baseContext,
+    );
+
+    expect(result).toContain('Error: Directory not found');
+  });
+
+  it('should sort results by mtime (most recent first)', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.globSync).mockReturnValue(['old.ts', 'new.ts', 'middle.ts']);
+
+    // Return different mtimes for isFile check vs mtime check
+    // statSync is called once per file for isFile and once per file for mtime
+    const mtimes: Record<string, number> = {
+      [path.resolve('/test/project', 'old.ts')]: 1000,
+      [path.resolve('/test/project', 'new.ts')]: 3000,
+      [path.resolve('/test/project', 'middle.ts')]: 2000,
+    };
+
+    vi.mocked(fs.statSync).mockImplementation((p) => ({
+      isFile: () => true,
+      mtimeMs: mtimes[p as string] ?? 1000,
+    } as unknown as fs.Stats));
+
+    const result = await globTool.config.execute(
+      { pattern: '*.ts' },
+      baseContext,
+    ) as string;
+
+    const lines = result.split('\n');
+    const newIdx = lines.findIndex((l) => l.includes('new.ts'));
+    const middleIdx = lines.findIndex((l) => l.includes('middle.ts'));
+    const oldIdx = lines.findIndex((l) => l.includes('old.ts'));
+
+    expect(newIdx).toBeLessThan(middleIdx);
+    expect(middleIdx).toBeLessThan(oldIdx);
+  });
+
+  it('should use provided path instead of cwd when given', async () => {
+    setupGlobMatches(['/test/project/sub/file.ts']);
+
+    await globTool.config.execute(
+      { pattern: '*.ts', path: '/test/project/sub' },
+      baseContext,
+    );
+
+    expect(fs.globSync).toHaveBeenCalledWith('*.ts', expect.objectContaining({
+      cwd: '/test/project/sub',
+    }));
+  });
+
+  it('should exclude node_modules and .git from results', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.globSync).mockReturnValue(['src/index.ts']);
+    vi.mocked(fs.statSync).mockReturnValue({
+      isFile: () => true,
+      mtimeMs: 1000,
+    } as unknown as fs.Stats);
+
+    await globTool.config.execute(
+      { pattern: '**/*.ts' },
+      baseContext,
+    );
+
+    // The exclude function passed to globSync should exclude node_modules/.git
+    const globSyncCall = vi.mocked(fs.globSync).mock.calls[0];
+    const opts = globSyncCall[1] as { exclude?: (name: string) => boolean };
+    expect(opts.exclude).toBeDefined();
+    expect(opts.exclude?.('node_modules')).toBe(true);
+    expect(opts.exclude?.('.git')).toBe(true);
+    expect(opts.exclude?.('src')).toBe(false);
+  });
+
+  it('should call assertPathContained for path security', async () => {
+    setupGlobMatches([]);
+    vi.mocked(fs.globSync).mockReturnValue([]);
+
+    await globTool.config.execute(
+      { pattern: '*.ts' },
+      baseContext,
+    );
+
+    expect(assertPathContained).toHaveBeenCalledWith('/test/project', '/test/project');
+  });
+
+  it('should pass output through truncateToolOutput', async () => {
+    setupGlobMatches(['/test/project/a.ts']);
+
+    await globTool.config.execute(
+      { pattern: '*.ts' },
+      baseContext,
+    );
+
+    expect(truncateToolOutput).toHaveBeenCalled();
+  });
+});
@@ -0,0 +1,269 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import { grepTool } from '../grep';
+import type { ToolContext } from '../../types';
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+const mockExecFile = vi.fn();
+vi.mock('node:child_process', () => ({
+  execFile: (...args: unknown[]) => mockExecFile(...args),
+}));
+
+const mockFindExecutable = vi.fn(() => '/usr/bin/rg');
+
+vi.mock('../../../../platform/index', () => ({
+  findExecutable: (_name: string, _additionalPaths?: string[]) => mockFindExecutable(),
+}));
+
+vi.mock('../../../security/path-containment', () => ({
+  assertPathContained: vi.fn((_filePath: string, _projectDir: string) => ({
+    contained: true,
+    resolvedPath: _filePath,
+  })),
+}));
+
+import { assertPathContained } from '../../../security/path-containment';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const baseContext: ToolContext = {
+  cwd: '/test/project',
+  projectDir: '/test/project',
+  specDir: '/test/specs/001',
+  securityProfile: {
+    baseCommands: new Set(),
+    stackCommands: new Set(),
+    scriptCommands: new Set(),
+    customCommands: new Set(),
+    customScripts: { shellScripts: [] },
+    getAllAllowedCommands: () => new Set(),
+  },
+} as unknown as ToolContext;
+
+/**
+ * Set up mockExecFile to invoke the callback with the provided rg output values.
+ */
+function setupRg(stdout: string, stderr: string, exitCode: number) {
+  mockExecFile.mockImplementation(
+    (
+      _rgPath: unknown,
+      _args: unknown,
+      _opts: unknown,
+      callback: (err: Error | null, stdout: string, stderr: string) => void,
+    ) => {
+      const err = exitCode !== 0 ? Object.assign(new Error('exit'), { code: exitCode }) : null;
+      callback(err, stdout, stderr);
+    },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('Grep Tool', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Re-set after clearAllMocks wipes the return value
+    mockFindExecutable.mockReturnValue('/usr/bin/rg');
+    vi.mocked(assertPathContained).mockImplementation((_filePath: string, _projectDir: string) => ({
+      contained: true,
+      resolvedPath: _filePath,
+    }));
+  });
+
+  it('should have correct metadata', () => {
+    expect(grepTool.metadata.name).toBe('Grep');
+    expect(grepTool.metadata.permission).toBe('read_only');
+  });
+
+  it('should return matching files in files_with_matches mode (default)', async () => {
+    setupRg('/test/project/src/index.ts\n/test/project/src/utils.ts\n', '', 0);
+
+    const result = await grepTool.config.execute(
+      { pattern: 'myFunction' },
+      baseContext,
+    ) as string;
+
+    expect(result).toContain('/test/project/src/index.ts');
+    expect(result).toContain('/test/project/src/utils.ts');
+  });
+
+  it('should return "No matches found" when rg exits with code 1 and no stderr', async () => {
+    setupRg('', '', 1);
+
+    const result = await grepTool.config.execute(
+      { pattern: 'nonexistent_pattern_xyz' },
+      baseContext,
+    );
+
+    expect(result).toBe('No matches found');
+  });
+
+  it('should return "No matches found" when stdout is empty', async () => {
+    setupRg('   \n', '', 0);
+
+    const result = await grepTool.config.execute(
+      { pattern: 'something' },
+      baseContext,
+    );
+
+    expect(result).toBe('No matches found');
+  });
+
+  it('should return error message when rg exits with code > 1 and stderr', async () => {
+    setupRg('', 'rg: error: unknown file type\n', 2);
+
+    const result = await grepTool.config.execute(
+      { pattern: 'test', type: 'unknowntype' },
+      baseContext,
+    ) as string;
+
+    expect(result).toContain('Error:');
+    expect(result).toContain('unknown file type');
+  });
+
+  it('should return error when ripgrep is not installed', async () => {
+    mockFindExecutable.mockReturnValue(null as unknown as string);
+
+    const result = await grepTool.config.execute(
+      { pattern: 'test' },
+      baseContext,
+    ) as string;
+
+    expect(result).toContain('Error:');
+    expect(result).toContain('ripgrep');
+  });
+
+  it('should include --files-with-matches flag in default mode', async () => {
+    setupRg('/test/project/a.ts\n', '', 0);
+
+    await grepTool.config.execute(
+      { pattern: 'hello' },
+      baseContext,
+    );
+
+    const args = mockExecFile.mock.calls[0][1] as string[];
+    expect(args).toContain('--files-with-matches');
+  });
+
+  it('should include --line-number flag in content mode', async () => {
+    setupRg('src/a.ts:10:const hello = 1;\n', '', 0);
+
+    await grepTool.config.execute(
+      { pattern: 'hello', output_mode: 'content' },
+      baseContext,
+    );
+
+    const args = mockExecFile.mock.calls[0][1] as string[];
+    expect(args).toContain('--line-number');
+    expect(args).not.toContain('--files-with-matches');
+    expect(args).not.toContain('--count');
+  });
+
+  it('should include --count flag in count mode', async () => {
+    setupRg('src/a.ts:5\n', '', 0);
+
+    await grepTool.config.execute(
+      { pattern: 'hello', output_mode: 'count' },
+      baseContext,
+    );
+
+    const args = mockExecFile.mock.calls[0][1] as string[];
+    expect(args).toContain('--count');
+  });
+
+  it('should add -C flag when context lines are specified in content mode', async () => {
+    setupRg('match output\n', '', 0);
+
+    await grepTool.config.execute(
+      { pattern: 'hello', output_mode: 'content', context: 3 },
+      baseContext,
+    );
+
+    const args = mockExecFile.mock.calls[0][1] as string[];
+    expect(args).toContain('-C');
+    expect(args).toContain('3');
+  });
+
+  it('should add --type flag when type is specified', async () => {
+    setupRg('/test/project/a.ts\n', '', 0);
+
+    await grepTool.config.execute(
+      { pattern: 'hello', type: 'ts' },
+      baseContext,
+    );
+
+    const args = mockExecFile.mock.calls[0][1] as string[];
+    expect(args).toContain('--type');
+    expect(args).toContain('ts');
+  });
+
+  it('should add --glob flag when glob is specified', async () => {
+    setupRg('/test/project/src/a.ts\n', '', 0);
+
+    await grepTool.config.execute(
+      { pattern: 'hello', glob: '*.{ts,tsx}' },
+      baseContext,
+    );
+
+    const args = mockExecFile.mock.calls[0][1] as string[];
+    expect(args).toContain('--glob');
+    expect(args).toContain('*.{ts,tsx}');
+  });
+
+  it('should truncate output exceeding MAX_OUTPUT_LENGTH', async () => {
+    const longOutput = '/test/project/file.ts\n'.repeat(2000);
+    setupRg(longOutput, '', 0);
+
+    const result = await grepTool.config.execute(
+      { pattern: 'test' },
+      baseContext,
+    ) as string;
+
+    expect(result).toContain('[Output truncated');
+    expect(result.length).toBeLessThan(longOutput.length);
+  });
+
+  it('should call assertPathContained for path security', async () => {
+    setupRg('/test/project/a.ts\n', '', 0);
+
+    await grepTool.config.execute(
+      { pattern: 'hello' },
+      baseContext,
+    );
+
+    expect(assertPathContained).toHaveBeenCalledWith('/test/project', '/test/project');
+  });
+
+  it('should throw when search path is outside project boundary', async () => {
+    vi.mocked(assertPathContained).mockImplementation(() => {
+      throw new Error("Path '/etc' is outside the project directory");
+    });
+
+    await expect(
+      grepTool.config.execute(
+        { pattern: 'root', path: '/etc' },
+        baseContext,
+      ),
+    ).rejects.toThrow('outside the project directory');
+  });
+
+  it('should use provided path for search instead of cwd', async () => {
+    setupRg('/test/project/sub/a.ts\n', '', 0);
+
+    await grepTool.config.execute(
+      { pattern: 'hello', path: '/test/project/sub' },
+      baseContext,
+    );
+
+    const args = mockExecFile.mock.calls[0][1] as string[];
+    // The resolved search path should be the last argument before the pattern
+    expect(args).toContain('/test/project/sub');
+  });
+});
@@ -0,0 +1,227 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import { readTool } from '../read';
+import type { ToolContext } from '../../types';
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+vi.mock('node:fs');
+vi.mock('../../../security/path-containment', () => ({
+  assertPathContained: vi.fn((_filePath: string, _projectDir: string) => ({
+    contained: true,
+    resolvedPath: _filePath,
+  })),
+}));
+
+import * as fs from 'node:fs';
+import { assertPathContained } from '../../../security/path-containment';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const baseContext: ToolContext = {
+  cwd: '/test/project',
+  projectDir: '/test/project',
+  specDir: '/test/specs/001',
+  securityProfile: {
+    baseCommands: new Set(),
+    stackCommands: new Set(),
+    scriptCommands: new Set(),
+    customCommands: new Set(),
+    customScripts: { shellScripts: [] },
+    getAllAllowedCommands: () => new Set(),
+  },
+} as unknown as ToolContext;
+
+/**
+ * Set up the fs mock sequence for a successful text file read.
+ *
+ * openSync → fd, fstatSync → stat object, readFileSync → content, closeSync → void
+ */
+function setupTextFile(content: string, isDir = false) {
+  const fakeFd = 42;
+  vi.mocked(fs.openSync).mockReturnValue(fakeFd as unknown as number);
+  vi.mocked(fs.fstatSync).mockReturnValue({
+    isDirectory: () => isDir,
+    size: Buffer.byteLength(content),
+  } as unknown as fs.Stats);
+  vi.mocked(fs.readFileSync).mockReturnValue(content);
+  vi.mocked(fs.closeSync).mockImplementation(() => undefined);
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('Read Tool', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(assertPathContained).mockImplementation((_filePath: string, _projectDir: string) => ({
+      contained: true,
+      resolvedPath: _filePath,
+    }));
+  });
+
+  it('should have correct metadata', () => {
+    expect(readTool.metadata.name).toBe('Read');
+    expect(readTool.metadata.permission).toBe('read_only');
+  });
+
+  it('should read an entire file with line numbers', async () => {
+    setupTextFile('line one\nline two\nline three');
+
+    const result = await readTool.config.execute(
+      { file_path: '/test/project/file.ts' },
+      baseContext,
+    );
+
+    expect(result).toContain('line one');
+    expect(result).toContain('line two');
+    expect(result).toContain('line three');
+    // Line numbers should be present (cat -n style)
+    expect(result).toMatch(/\d+\t/);
+  });
+
+  it('should format output with correct line numbers', async () => {
+    setupTextFile('alpha\nbeta\ngamma');
+
+    const result = await readTool.config.execute(
+      { file_path: '/test/project/file.ts' },
+      baseContext,
+    ) as string;
+
+    const lines = result.split('\n');
+    expect(lines[0]).toMatch(/^\s*1\talpha/);
+    expect(lines[1]).toMatch(/^\s*2\tbeta/);
+    expect(lines[2]).toMatch(/^\s*3\tgamma/);
+  });
+
+  it('should respect offset and limit parameters', async () => {
+    const content = 'line1\nline2\nline3\nline4\nline5';
+    setupTextFile(content);
+
+    const result = await readTool.config.execute(
+      { file_path: '/test/project/file.ts', offset: 1, limit: 2 },
+      baseContext,
+    ) as string;
+
+    // offset=1 means start from line index 1 (line2), limit=2 means two lines
+    expect(result).toContain('line2');
+    expect(result).toContain('line3');
+    expect(result).not.toContain('line1');
+    expect(result).not.toContain('line4');
+  });
+
+  it('should show truncation notice when there are more lines beyond limit', async () => {
+    const lines = Array.from({ length: 10 }, (_, i) => `line${i + 1}`);
+    setupTextFile(lines.join('\n'));
+
+    const result = await readTool.config.execute(
+      { file_path: '/test/project/file.ts', offset: 0, limit: 3 },
+      baseContext,
+    ) as string;
+
+    expect(result).toContain('Showing lines 1-3 of 10 total lines');
+  });
+
+  it('should return error when file not found', async () => {
+    const enoentError = Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+    vi.mocked(fs.openSync).mockImplementation(() => { throw enoentError; });
+
+    const result = await readTool.config.execute(
+      { file_path: '/test/project/missing.ts' },
+      baseContext,
+    );
+
+    expect(result).toContain('Error: File not found');
+  });
+
+  it('should return error when path is a directory (EISDIR)', async () => {
+    const eisdirError = Object.assign(new Error('EISDIR'), { code: 'EISDIR' });
+    vi.mocked(fs.openSync).mockImplementation(() => { throw eisdirError; });
+
+    const result = await readTool.config.execute(
+      { file_path: '/test/project/somedir' },
+      baseContext,
+    );
+
+    expect(result).toContain('is a directory');
+  });
+
+  it('should return empty file message when file has no content', async () => {
+    setupTextFile('');
+
+    const result = await readTool.config.execute(
+      { file_path: '/test/project/empty.ts' },
+      baseContext,
+    );
+
+    expect(result).toContain('File exists but is empty');
+  });
+
+  it('should return image file as base64 data URI', async () => {
+    const fakeFd = 42;
+    const imageBuffer = Buffer.from('fake-png-data');
+    vi.mocked(fs.openSync).mockReturnValue(fakeFd as unknown as number);
+    vi.mocked(fs.fstatSync).mockReturnValue({
+      isDirectory: () => false,
+      size: imageBuffer.length,
+    } as unknown as fs.Stats);
+    // readFileSync returns Buffer for image files
+    vi.mocked(fs.readFileSync).mockReturnValue(imageBuffer);
+    vi.mocked(fs.closeSync).mockImplementation(() => undefined);
+
+    const result = await readTool.config.execute(
+      { file_path: '/test/project/image.png' },
+      baseContext,
+    ) as string;
+
+    expect(result).toContain('[Image file:');
+    expect(result).toContain('data:image/png;base64,');
+  });
+
+  it('should return PDF info without pages parameter', async () => {
+    const fakeFd = 42;
+    vi.mocked(fs.openSync).mockReturnValue(fakeFd as unknown as number);
+    vi.mocked(fs.fstatSync).mockReturnValue({
+      isDirectory: () => false,
+      size: 102400,
+    } as unknown as fs.Stats);
+    vi.mocked(fs.closeSync).mockImplementation(() => undefined);
+
+    const result = await readTool.config.execute(
+      { file_path: '/test/project/doc.pdf' },
+      baseContext,
+    ) as string;
+
+    expect(result).toContain('[PDF file:');
+    expect(result).toContain('pages');
+  });
+
+  it('should call assertPathContained for path security', async () => {
+    setupTextFile('content');
+
+    await readTool.config.execute(
+      { file_path: '/test/project/file.ts' },
+      baseContext,
+    );
+
+    expect(assertPathContained).toHaveBeenCalledWith('/test/project/file.ts', '/test/project');
+  });
+
+  it('should throw when path is outside project boundary', async () => {
+    vi.mocked(assertPathContained).mockImplementation(() => {
+      throw new Error("Path '/etc/passwd' is outside the project directory");
+    });
+
+    await expect(
+      readTool.config.execute(
+        { file_path: '/etc/passwd' },
+        baseContext,
+      ),
+    ).rejects.toThrow('outside the project directory');
+  });
+});
@@ -0,0 +1,164 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import { writeTool } from '../write';
+import type { ToolContext } from '../../types';
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+vi.mock('node:fs');
+vi.mock('../../../security/path-containment', () => ({
+  assertPathContained: vi.fn((_filePath: string, _projectDir: string) => ({
+    contained: true,
+    resolvedPath: _filePath,
+  })),
+}));
+
+import * as fs from 'node:fs';
+import { assertPathContained } from '../../../security/path-containment';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const baseContext: ToolContext = {
+  cwd: '/test/project',
+  projectDir: '/test/project',
+  specDir: '/test/specs/001',
+  securityProfile: {
+    baseCommands: new Set(),
+    stackCommands: new Set(),
+    scriptCommands: new Set(),
+    customCommands: new Set(),
+    customScripts: { shellScripts: [] },
+    getAllAllowedCommands: () => new Set(),
+  },
+} as unknown as ToolContext;
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('Write Tool', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(assertPathContained).mockImplementation((_filePath: string, _projectDir: string) => ({
+      contained: true,
+      resolvedPath: _filePath,
+    }));
+    // Parent directory exists by default
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.writeFileSync).mockImplementation(() => undefined);
+  });
+
+  it('should have correct metadata', () => {
+    expect(writeTool.metadata.name).toBe('Write');
+    expect(writeTool.metadata.permission).toBe('requires_approval');
+  });
+
+  it('should write a new file and report line count', async () => {
+    const content = 'line one\nline two\nline three';
+
+    const result = await writeTool.config.execute(
+      { file_path: '/test/project/new-file.ts', content },
+      baseContext,
+    );
+
+    expect(result).toContain('Successfully wrote 3 lines');
+    expect(result).toContain('/test/project/new-file.ts');
+    expect(fs.writeFileSync).toHaveBeenCalledWith(
+      '/test/project/new-file.ts',
+      content,
+      'utf-8',
+    );
+  });
+
+  it('should overwrite an existing file', async () => {
+    const content = 'updated content';
+
+    const result = await writeTool.config.execute(
+      { file_path: '/test/project/existing.ts', content },
+      baseContext,
+    );
+
+    expect(result).toContain('Successfully wrote');
+    expect(fs.writeFileSync).toHaveBeenCalledWith(
+      '/test/project/existing.ts',
+      content,
+      'utf-8',
+    );
+  });
+
+  it('should create parent directories when they do not exist', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(false);
+    vi.mocked(fs.mkdirSync).mockImplementation(() => undefined);
+
+    await writeTool.config.execute(
+      { file_path: '/test/project/new/deep/file.ts', content: 'content' },
+      baseContext,
+    );
+
+    expect(fs.mkdirSync).toHaveBeenCalledWith(
+      '/test/project/new/deep',
+      { recursive: true },
+    );
+    expect(fs.writeFileSync).toHaveBeenCalled();
+  });
+
+  it('should not create directories when parent already exists', async () => {
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+
+    await writeTool.config.execute(
+      { file_path: '/test/project/file.ts', content: 'content' },
+      baseContext,
+    );
+
+    expect(fs.mkdirSync).not.toHaveBeenCalled();
+  });
+
+  it('should count lines correctly for single-line content', async () => {
+    const result = await writeTool.config.execute(
+      { file_path: '/test/project/file.ts', content: 'single line' },
+      baseContext,
+    );
+
+    expect(result).toContain('Successfully wrote 1 lines');
+  });
+
+  it('should count CRLF lines correctly', async () => {
+    const content = 'line1\r\nline2\r\nline3';
+
+    const result = await writeTool.config.execute(
+      { file_path: '/test/project/file.ts', content },
+      baseContext,
+    );
+
+    // split(/\r?\n/) yields 3 parts
+    expect(result).toContain('Successfully wrote 3 lines');
+  });
+
+  it('should call assertPathContained for path security', async () => {
+    await writeTool.config.execute(
+      { file_path: '/test/project/file.ts', content: 'hello' },
+      baseContext,
+    );
+
+    expect(assertPathContained).toHaveBeenCalledWith('/test/project/file.ts', '/test/project');
+  });
+
+  it('should throw when path is outside project boundary', async () => {
+    vi.mocked(assertPathContained).mockImplementation(() => {
+      throw new Error("Path '/etc/hosts' is outside the project directory");
+    });
+
+    await expect(
+      writeTool.config.execute(
+        { file_path: '/etc/hosts', content: 'malicious' },
+        baseContext,
+      ),
+    ).rejects.toThrow('outside the project directory');
+
+    expect(fs.writeFileSync).not.toHaveBeenCalled();
+  });
+});
@@ -149,7 +149,7 @@ export function generateDebugReport(): string {
  const recentErrors = getRecentErrors(10);

  const lines = [
-    '=== Auto Claude Debug Report ===',
+    '=== Aperant Debug Report ===',
    `Generated: ${new Date().toISOString()}`,
    '',
    '--- System Information ---',
@@ -30,7 +30,7 @@ import { isMacOS } from './platform';

 // GitHub repo info for API calls
 const GITHUB_OWNER = 'AndyMik90';
-const GITHUB_REPO = 'Auto-Claude';
+const GITHUB_REPO = 'Aperant';

 // Debug mode - DEBUG_UPDATER=true or development mode
 const DEBUG_UPDATER = process.env.DEBUG_UPDATER === 'true' || process.env.NODE_ENV === 'development';
@@ -488,7 +488,7 @@ async function fetchLatestStableRelease(): Promise<AppUpdateInfo | null> {
    });

    request.setHeader('Accept', 'application/vnd.github.v3+json');
-    request.setHeader('User-Agent', `Auto-Claude/${getCurrentVersion()}`);
+    request.setHeader('User-Agent', `Aperant/${getCurrentVersion()}`);

    let data = '';

@@ -499,7 +499,6 @@ export class ChangelogService extends EventEmitter {
      this.debug('Error in AI version suggestion, falling back to patch bump', error);
      // Fallback to patch bump if AI fails
      // currentVersion is guaranteed non-empty: the try block returns early if falsy or invalid
-      // biome-ignore lint/style/noNonNullAssertion: guarded by early returns in try block
      const [major, minor, patch] = currentVersion!.split('.').map(Number);
      return {
        version: `${major}.${minor}.${patch + 1}`,
@@ -214,7 +214,6 @@ export class UsageMonitor extends EventEmitter {
  private currentUsage: ClaudeUsageSnapshot | null = null;
  private currentUsageProfileId: string | null = null; // Track which profile's usage is in currentUsage
  private isChecking = false;
-  private pendingCheckAfterCurrent = false;

  // Per-profile API failure tracking with cooldown-based retry
  // Map<profileId, lastFailureTimestamp> - stores when API last failed for this profile
@@ -232,7 +231,7 @@ export class UsageMonitor extends EventEmitter {
  // Cache for all profiles' usage data
  // Map<profileId, { usage: ProfileUsageSummary, fetchedAt: number }>
  private allProfilesUsageCache: Map<string, { usage: ProfileUsageSummary; fetchedAt: number }> = new Map();
-  private static PROFILE_USAGE_CACHE_TTL_MS = 10 * 60 * 1000; // 10 minutes cache for inactive profiles (endpoint is fragile, reduce load)
+  private static PROFILE_USAGE_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes cache for inactive profiles

  // Request coalescing: track in-flight getAllProfilesUsage() promise to avoid parallel duplicate fetches
  private allProfilesUsageInflight: Promise<AllProfilesUsage | null> | null = null;
@@ -242,7 +241,7 @@ export class UsageMonitor extends EventEmitter {

  // Rate-limit (429) tracking: separate from general API failures, uses longer cooldown
  private rateLimitedProfiles: Map<string, number> = new Map(); // profileId -> 429 timestamp
-  private static RATE_LIMIT_COOLDOWN_MS = 15 * 60 * 1000; // 15 minutes cooldown for 429s (endpoint may not recover quickly)
+  private static RATE_LIMIT_COOLDOWN_MS = 10 * 60 * 1000; // 10 minutes cooldown for 429s

  // Debug flag for verbose logging
  private readonly isDebug = process.env.DEBUG === 'true';
@@ -293,11 +292,7 @@ export class UsageMonitor extends EventEmitter {
   * Note: Usage monitoring always runs to display the usage badge.
   * Proactive account swapping only occurs if enabled in settings.
   *
-   * Update interval: 5 minutes (300000ms) for active profile; inactive profiles every 10 minutes (adaptive: 2min when usage is high)
-   *
-   * Note: The /api/oauth/usage endpoint is fragile and undocumented. 60s polling triggers 429s
-   * (see anthropics/claude-code issues #30930, #31021, #31055, #31637, #32503).
-   * 5-minute intervals align with practical safe limits for this endpoint.
+   * Update interval: 60 seconds (60000ms) for active profile; inactive profiles every 5 minutes (adaptive: 60s when usage is high)
   */
  start(): void {
    if (this.intervalId) {
@@ -307,16 +302,11 @@ export class UsageMonitor extends EventEmitter {

    const profileManager = getClaudeProfileManager();
    const settings = profileManager.getAutoSwitchSettings();
-    const interval = settings.usageCheckInterval || 300000; // 5 minutes for active profile polling (endpoint is fragile)
+    const interval = settings.usageCheckInterval || 60000; // 60 seconds for active profile polling

-    this.debugLog('[UsageMonitor] Starting with interval: ' + interval + ' ms (5-minute updates for active profile usage stats)');
+    this.debugLog('[UsageMonitor] Starting with interval: ' + interval + ' ms (60-second updates for active profile usage stats)');

-    // Fetch all profiles usage immediately on startup so the UI shows real data.
-    // This runs independently of checkUsageAndSwap — even if the active profile's
-    // fetch fails (e.g., 429), inactive profiles still get fetched and displayed.
-    this.fetchAllProfilesOnStartup();
-
-    // Check immediately (handles proactive swap for active profile)
+    // Check immediately
    this.checkUsageAndSwap();

    // Then check periodically
@@ -336,43 +326,6 @@ export class UsageMonitor extends EventEmitter {
    }
  }

-  /**
-   * Fetch all profiles' usage on startup so the UI shows real data immediately.
-   * Runs asynchronously — doesn't block app startup. Errors are non-fatal.
-   *
-   * We wait briefly for checkUsageAndSwap() to populate currentUsage (active profile),
-   * then call getAllProfilesUsage() which fetches inactive profiles and combines everything.
-   * If the active profile fetch fails (e.g., 429), we still call _doGetAllProfilesUsage
-   * directly to populate inactive profile data for the UI.
-   */
-  private async fetchAllProfilesOnStartup(): Promise<void> {
-    try {
-      // Wait for checkUsageAndSwap() to have a chance to populate currentUsage.
-      // 5s is enough for most API responses; if it fails, we proceed with partial data.
-      await new Promise(resolve => setTimeout(resolve, 5000));
-
-      console.log('[UsageMonitor] Startup: fetching all profiles usage for UI...');
-
-      let allProfilesUsage: AllProfilesUsage | null;
-      if (this.currentUsage) {
-        // Active profile data is available — use the normal path
-        allProfilesUsage = await this.getAllProfilesUsage(true);
-      } else {
-        // Active profile fetch failed (429, etc.) — fetch inactive profiles directly
-        console.log('[UsageMonitor] Startup: active profile usage unavailable, fetching inactive profiles directly');
-        allProfilesUsage = await this._doGetAllProfilesUsage(true);
-      }
-
-      if (allProfilesUsage) {
-        this.emit('all-profiles-usage-updated', allProfilesUsage);
-        console.log('[UsageMonitor] Startup: all profiles usage emitted to UI (' + allProfilesUsage.allProfiles.length + ' profiles)');
-      }
-    } catch (error) {
-      // Non-fatal — the regular polling will pick it up
-      console.log('[UsageMonitor] Startup: failed to fetch all profiles usage (non-fatal):', error instanceof Error ? error.message : String(error));
-    }
-  }
-
  /**
   * Get current usage snapshot (for UI indicator)
   */
@@ -490,7 +443,6 @@ export class UsageMonitor extends EventEmitter {
      await this.appendZAIAccounts(allProfiles);

      // Return minimal data with auth status - don't return null!
-      console.log('[UsageMonitor] getAllProfilesUsage fast-path (no currentUsage):', allProfiles.map(p => ({ id: p.profileId, name: p.profileName, email: p.profileEmail, active: p.isActive })));
      return {
        activeProfile: {
          profileId: activeProfileId || '',
@@ -534,14 +486,13 @@ export class UsageMonitor extends EventEmitter {
    const profileResults: (ProfileUsageSummary | null)[] = new Array(settings.profiles.length).fill(null);

    // Adaptive cache TTL: when active profile usage is high, refresh inactive profiles more
-    // frequently (every 2min instead of 10min) because we may need to swap soon.
-    // Note: even in swap-ready mode, we avoid <2min to respect the fragile endpoint.
+    // frequently (every 60s instead of 5min) because we may need to swap soon
    const activeUsageHigh = this.currentUsage
      ? (this.currentUsage.sessionPercent > 80 || this.currentUsage.weeklyPercent > 90)
      : false;
    const effectiveCacheTtl = activeUsageHigh
-      ? 2 * 60 * 1000 // 2min when usage is high (swap-ready mode)
-      : UsageMonitor.PROFILE_USAGE_CACHE_TTL_MS; // 10 min normally
+      ? 60 * 1000 // 60s when usage is high (swap-ready mode)
+      : UsageMonitor.PROFILE_USAGE_CACHE_TTL_MS; // 5 min normally

    for (let i = 0; i < settings.profiles.length; i++) {
      const profile = settings.profiles[i];
@@ -804,18 +755,9 @@ export class UsageMonitor extends EventEmitter {
    // Sort by availability score (highest first = most available)
    allProfiles.sort((a, b) => b.availabilityScore - a.availabilityScore);

-    // Build active profile data — may be null on startup if the active profile's fetch failed
-    const activeProfile = this.currentUsage ?? {
-      profileId: settings.activeProfileId || '',
-      profileName: settings.profiles.find(p => p.id === settings.activeProfileId)?.name || '',
-      sessionPercent: 0,
-      weeklyPercent: 0,
-      fetchedAt: new Date(),
-    };
-
-    console.log('[UsageMonitor] _doGetAllProfilesUsage complete:', allProfiles.map(p => ({ id: p.profileId, name: p.profileName, session: p.sessionPercent, weekly: p.weeklyPercent, active: p.isActive })));
    return {
-      activeProfile,
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      activeProfile: this.currentUsage!, // Non-null: _doGetAllProfilesUsage is only called when currentUsage is set
      allProfiles,
      fetchedAt: new Date()
    };
@@ -1369,8 +1311,7 @@ export class UsageMonitor extends EventEmitter {
   */
  private async checkUsageAndSwap(): Promise<void> {
    if (this.isChecking) {
-      this.pendingCheckAfterCurrent = true; // Re-run after current check completes
-      return;
+      return; // Prevent concurrent checks
    }

    this.isChecking = true;
@@ -1463,23 +1404,7 @@ export class UsageMonitor extends EventEmitter {
        this.traceLog('[UsageMonitor:TRACE] Skipping proactive swap for API profile (only supported for OAuth profiles)');
      }
    } catch (error) {
-      // Step 5a: Handle usage API 429 — trigger proactive swap
-      // A 429 from the usage endpoint means the account is at/near its rate limit.
-      // Instead of sitting idle for 10 minutes, proactively swap to an available account.
-      if (isHttpError(error) && (error as any).isUsageApi429 && profileId && !isAPIProfile) {
-        const profileManager = getClaudeProfileManager();
-        const settings = profileManager.getAutoSwitchSettings();
-
-        if (settings.enabled && settings.proactiveSwapEnabled) {
-          console.log('[UsageMonitor] Usage API returned 429 — treating as threshold exceeded, triggering proactive swap for profile:', profileId);
-          await this.performProactiveSwap(profileId, 'session');
-          return;
-        }
-        console.log('[UsageMonitor] Usage API returned 429 but proactive swap is disabled — backing off silently');
-        return;
-      }
-
-      // Step 5b: Handle auth failures
+      // Step 5: Handle auth failures
      if (isHttpError(error) && (error.statusCode === 401 || error.statusCode === 403)) {
        if (profileId) {
          await this.handleAuthFailure(profileId, isAPIProfile);
@@ -1490,13 +1415,6 @@ export class UsageMonitor extends EventEmitter {
      console.error('[UsageMonitor] Check failed:', error);
    } finally {
      this.isChecking = false;
-      // If a check was requested while we were busy, run it now
-      if (this.pendingCheckAfterCurrent) {
-        this.pendingCheckAfterCurrent = false;
-        this.checkUsageAndSwap().catch(error => {
-          console.error('[UsageMonitor] Pending check failed:', error);
-        });
-      }
    }
  }

@@ -2285,7 +2203,7 @@ export class UsageMonitor extends EventEmitter {
        if (response.status === 429) {
          const now = Date.now();
          const siblingIds = this.getProfileIdFamily(profileId);
-          console.warn('[UsageMonitor] Rate limited (429) by provider, backing off for 15 minutes:', {
+          console.warn('[UsageMonitor] Rate limited (429) by provider, backing off for 10 minutes:', {
            provider,
            endpoint: usageEndpoint,
            cooldownMs: UsageMonitor.RATE_LIMIT_COOLDOWN_MS,
@@ -2294,13 +2212,7 @@ export class UsageMonitor extends EventEmitter {
          for (const id of siblingIds) {
            this.rateLimitedProfiles.set(id, now);
          }
-          // Signal to checkUsageAndSwap that the usage API was 429'd.
-          // A 429 on the usage endpoint is strong evidence the account is at/near
-          // its rate limit — we should proactively swap rather than sit idle for 10 min.
-          const error = new Error('Usage API rate limited (429)');
-          (error as any).statusCode = 429;
-          (error as any).isUsageApi429 = true;
-          throw error;
+          return null;
        }

        // Check for auth failures via status code (works for all providers)
@@ -2442,11 +2354,6 @@ export class UsageMonitor extends EventEmitter {
        throw error;
      }

-      // Re-throw usage API 429 so checkUsageAndSwap can trigger proactive swap
-      if (error?.isUsageApi429) {
-        throw error;
-      }
-
      console.error('[UsageMonitor] API fetch failed:', error);
      // Record failure timestamp for cooldown retry (network/other errors)
      this.apiFailureTimestamps.set(profileId, Date.now());
@@ -2746,60 +2653,6 @@ export class UsageMonitor extends EventEmitter {
    const profileManager = getClaudeProfileManager();
    const excludeIds = new Set([currentProfileId, ...additionalExclusions]);

-    // Also exclude the currently active profile — the swap target must differ from
-    // what the app is already running on, not just from what triggered the swap.
-    const activeProfileId = profileManager.getActiveProfile()?.id;
-    if (activeProfileId) {
-      excludeIds.add(activeProfileId);
-    }
-
-    // Also exclude the linked claudeProfileId when currentProfileId is a provider account ID.
-    // Provider accounts (pa_*) and OAuth profiles (msup, etc.) use different ID formats
-    // but refer to the same underlying account. Without this, the same account would be
-    // picked as the swap target — resulting in a no-op swap.
-    try {
-      const settings = await readSettingsFileAsync();
-      const providerAccounts = (settings?.providerAccounts as ProviderAccount[] | undefined) ?? [];
-      const currentAccount = providerAccounts.find(a => a.id === currentProfileId);
-      if (currentAccount?.claudeProfileId) {
-        excludeIds.add(currentAccount.claudeProfileId);
-      }
-      // Also handle the reverse: if currentProfileId is a claudeProfileId, exclude matching provider accounts
-      for (const account of providerAccounts) {
-        if (account.claudeProfileId === currentProfileId) {
-          excludeIds.add(account.id);
-        }
-      }
-
-      // Exclude all provider accounts that share the same configDir as the current one.
-      // Multiple profiles on the same Anthropic account share the same rate limit —
-      // swapping between them is pointless.
-      const resolvedAccount = currentAccount ?? providerAccounts.find(a => a.claudeProfileId === currentProfileId);
-      if (resolvedAccount) {
-        const currentConfigDir = resolvedAccount.claudeProfileId
-          ? profileManager.getProfile(resolvedAccount.claudeProfileId)?.configDir
-          : undefined;
-        if (currentConfigDir) {
-          const allOAuthProfiles = profileManager.getProfilesSortedByAvailability();
-          for (const profile of allOAuthProfiles) {
-            if (profile.configDir === currentConfigDir && !excludeIds.has(profile.id)) {
-              excludeIds.add(profile.id);
-            }
-          }
-          // Also exclude provider accounts linked to those same profiles
-          for (const account of providerAccounts) {
-            if (account.claudeProfileId && excludeIds.has(account.claudeProfileId)) {
-              excludeIds.add(account.id);
-            }
-          }
-        }
-      }
-    } catch {
-      // Non-critical — proceed with partial exclusion set
-    }
-
-    console.log('[UsageMonitor] PROACTIVE-SWAP: Exclude set:', Array.from(excludeIds));
-
    // Get priority order for unified account system
    const priorityOrder = profileManager.getAccountPriorityOrder();

@@ -2814,38 +2667,20 @@ export class UsageMonitor extends EventEmitter {

    const unifiedAccounts: UnifiedSwapTarget[] = [];

-    // Add OAuth profiles (sorted by availability), filtering out those above threshold
-    const swapSettings = profileManager.getAutoSwitchSettings();
-    const sessionThreshold = swapSettings.sessionThreshold ?? 95;
-    const weeklyThreshold = swapSettings.weeklyThreshold ?? 99;
+    // Add OAuth profiles (sorted by availability)
    const oauthProfiles = profileManager.getProfilesSortedByAvailability();
    for (const profile of oauthProfiles) {
-      if (excludeIds.has(profile.id)) continue;
-
-      // Skip profiles that are themselves above the swap threshold
-      const sessionPct = profile.usage?.sessionUsagePercent ?? 0;
-      const weeklyPct = profile.usage?.weeklyUsagePercent ?? 0;
-      if (sessionPct >= sessionThreshold || weeklyPct >= weeklyThreshold) {
-        console.log('[UsageMonitor] PROACTIVE-SWAP: Skipping', profile.name, '— above threshold (session:', sessionPct + '%, weekly:', weeklyPct + '%)');
-        continue;
+      if (!excludeIds.has(profile.id)) {
+        const unifiedId = `oauth-${profile.id}`;
+        const priorityIndex = priorityOrder.indexOf(unifiedId);
+        unifiedAccounts.push({
+          id: profile.id,
+          unifiedId,
+          name: profile.name,
+          type: 'oauth',
+          priorityIndex: priorityIndex === -1 ? Infinity : priorityIndex
+        });
      }
-
-      // Skip rate-limited profiles
-      const rateLimitStatus = isProfileRateLimited(profile);
-      if (rateLimitStatus.limited) {
-        console.log('[UsageMonitor] PROACTIVE-SWAP: Skipping', profile.name, '— rate limited (type:', rateLimitStatus.type + ')');
-        continue;
-      }
-
-      const unifiedId = `oauth-${profile.id}`;
-      const priorityIndex = priorityOrder.indexOf(unifiedId);
-      unifiedAccounts.push({
-        id: profile.id,
-        unifiedId,
-        name: profile.name,
-        type: 'oauth',
-        priorityIndex: priorityIndex === -1 ? Infinity : priorityIndex
-      });
    }

    // Add API profiles (always considered available since they have unlimited usage)
@@ -2924,30 +2759,6 @@ export class UsageMonitor extends EventEmitter {
      }
    }

-    // Update globalPriorityOrder so the UI reflects the new active account.
-    // The UI's "Active Account" is determined by the first entry in globalPriorityOrder.
-    try {
-      const currentSettings = await readSettingsFileAsync();
-      if (currentSettings) {
-        const providerAccounts = (currentSettings.providerAccounts as ProviderAccount[] | undefined) ?? [];
-        const queue = (currentSettings.globalPriorityOrder as string[] | undefined) ?? [];
-
-        // Find the provider account linked to the target OAuth profile
-        const targetProviderAccount = providerAccounts.find(a => a.claudeProfileId === rawProfileId);
-        if (targetProviderAccount && queue.includes(targetProviderAccount.id)) {
-          // Move target to front of queue
-          const newQueue = [targetProviderAccount.id, ...queue.filter(id => id !== targetProviderAccount.id)];
-          currentSettings.globalPriorityOrder = newQueue;
-          await writeSettingsFile(currentSettings);
-          console.log('[UsageMonitor] PROACTIVE-SWAP: Updated globalPriorityOrder — new active:', targetProviderAccount.name, '(' + targetProviderAccount.id + ')');
-        } else {
-          console.log('[UsageMonitor] PROACTIVE-SWAP: Could not find provider account for OAuth profile:', rawProfileId);
-        }
-      }
-    } catch (error) {
-      console.error('[UsageMonitor] PROACTIVE-SWAP: Failed to update globalPriorityOrder:', error);
-    }
-
    // Get the "from" profile name
    let fromProfileName: string | undefined;
    const fromOAuthProfile = profileManager.getProfile(currentProfileId);
@@ -2974,11 +2785,10 @@ export class UsageMonitor extends EventEmitter {
      timestamp: new Date()
    });

-    // Notify UI — shape must match what ProactiveSwapListener expects:
-    // data.fromProfile.name and data.toProfile.name
+    // Notify UI
    this.emit('show-swap-notification', {
-      fromProfile: { id: currentProfileId, name: fromProfileName ?? currentProfileId },
-      toProfile: { id: bestAccount.id, name: bestAccount.name },
+      fromProfile: fromProfileName,
+      toProfile: bestAccount.name,
      reason: 'proactive',
      limitType
    });
@@ -3,11 +3,24 @@
 // require-in-the-middle hooks. Sentry's hooks expect require.cache to exist,
 // which is only available in CommonJS. Without this, node-pty native module
 // loading fails with "ReferenceError: require is not defined".
-import { createRequire } from 'module';
+import Module, { createRequire } from 'module';
 const require = createRequire(import.meta.url);
 // Make require globally available for Sentry's require-in-the-middle hooks
 globalThis.require = require;

+// In packaged Electron apps, native modules (e.g. @libsql/client) are placed in
+// Resources/node_modules/ via extraResources. Add that path to CJS resolution so
+// globalThis.require() can find them at runtime.
+if (process.resourcesPath) {
+  const nativeModulesPath = require('path').join(process.resourcesPath, 'node_modules');
+  // Module.globalPaths is an undocumented but stable Node.js internal used for
+  // CJS module resolution. It's not in @types/node, hence the cast.
+  const globalPaths = (Module as unknown as { globalPaths: string[] }).globalPaths;
+  if (!globalPaths.includes(nativeModulesPath)) {
+    globalPaths.push(nativeModulesPath);
+  }
+}
+
 // Load .env file FIRST before any other imports that might use process.env
 import { config } from 'dotenv';
 import { resolve, dirname } from 'path';
@@ -37,7 +50,7 @@ for (const envPath of possibleEnvPaths) {

 import { app, BrowserWindow, shell, nativeImage, session, screen, Menu, MenuItem } from 'electron';
 import { join } from 'path';
-import { accessSync, readFileSync, writeFileSync, rmSync } from 'fs';
+import { accessSync, readFileSync, writeFileSync, rmSync, cpSync } from 'fs';
 import { electronApp, optimizer, is } from '@electron-toolkit/utils';
 import { setupIpcHandlers } from './ipc-setup';
 import { AgentManager } from './agent';
@@ -58,6 +71,26 @@ import { isMacOS, isWindows } from './platform';
 import { ptyDaemonClient } from './terminal/pty-daemon-client';
 import type { AppSettings, AuthFailureInfo } from '../shared/types';

+// ─────────────────────────────────────────────────────────────────────────────
+// Migrate userData from old app name (auto-claude-ui → aperant)
+// Must run before any code accesses app.getPath('userData')
+// ─────────────────────────────────────────────────────────────────────────────
+{
+  const newUserData = app.getPath('userData');
+  const oldUserData = join(dirname(newUserData), 'auto-claude-ui');
+  if (existsSync(oldUserData) && !existsSync(join(newUserData, '.migrated'))) {
+    try {
+      // Copy all files from old location to new (don't move — keeps old as backup)
+      cpSync(oldUserData, newUserData, { recursive: true, force: false, errorOnExist: false });
+      // Mark as migrated so we don't repeat
+      writeFileSync(join(newUserData, '.migrated'), new Date().toISOString());
+      console.warn('[main] Migrated userData from auto-claude-ui to aperant');
+    } catch (err) {
+      console.warn('[main] userData migration failed (non-fatal):', err);
+    }
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Window sizing constants
 // ─────────────────────────────────────────────────────────────────────────────
@@ -352,6 +385,16 @@ function createWindow(): void {
    agentManager?.killAll?.()?.catch((err: unknown) => {
      console.warn('[main] Error killing agents on window close:', err);
    });
+    // Clear GitLab MR polling intervals for all projects
+    import('./ipc-handlers/gitlab/mr-review-handlers').then(({ clearPollingForProject }) => {
+      const { projectStore } = require('./project-store');
+      const projects = projectStore.getProjects();
+      for (const project of projects) {
+        clearPollingForProject(project.id);
+      }
+    }).catch((err: unknown) => {
+      console.warn('[main] Error clearing GitLab polling on window close:', err);
+    });
    mainWindow = null;
  });
 }
@@ -373,7 +416,7 @@ if (isWindows()) {
 // Initialize the application
 app.whenReady().then(() => {
  // Set app user model id for Windows
-  electronApp.setAppUserModelId('com.autoclaude.ui');
+  electronApp.setAppUserModelId('com.aperant.app');

  // Clear cache on Windows to prevent permission errors from stale cache
  if (isWindows()) {
@@ -135,13 +135,6 @@ export class InsightsExecutor extends EventEmitter {
              } as InsightsStreamChunk);
              break;
            }
-            case 'status': {
-              this.emit('stream-chunk', projectId, {
-                type: 'text',
-                content: event.text,
-              } as InsightsStreamChunk);
-              break;
-            }
            case 'error': {
              allOutput = (allOutput + event.error).slice(-10000);
              this.emit('stream-chunk', projectId, {
@@ -129,7 +129,7 @@ async function githubGraphQL<T>(
    headers: {
      "Authorization": `Bearer ${safeToken}`,
      "Content-Type": "application/json",
-      "User-Agent": "Auto-Claude-UI",
+      "User-Agent": "Aperant",
    },
    body: JSON.stringify({ query, variables }),
  });
@@ -2275,7 +2275,7 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v

          if (options?.forceApprove) {
            // Auto-approve format: clean approval message with optional suggestions
-            body = `## ✅ Auto Claude Review - APPROVED\n\n`;
+            body = `## ✅ Aperant Review - APPROVED\n\n`;
            body += `**Status:** Ready to Merge\n\n`;
            body += `**Summary:** ${result.summary}\n\n`;

@@ -2298,10 +2298,10 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v
            }

            body += `---\n*This automated review found no blocking issues. The PR can be safely merged.*\n\n`;
-            body += `*Generated by Auto Claude*`;
+            body += `*Generated by Aperant*`;
          } else {
            // Standard review format
-            body = `## 🤖 Auto Claude PR Review\n\n${result.summary}\n\n`;
+            body = `## 🤖 Aperant PR Review\n\n${result.summary}\n\n`;

            if (findings.length > 0) {
              // Show selected count vs total if filtered
@@ -2326,7 +2326,7 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v
              body += `*No findings selected for this review.*\n\n`;
            }

-            body += `---\n*This review was generated by Auto Claude.*`;
+            body += `---\n*This review was generated by Aperant.*`;
          }

          // Determine review status based on selected findings (or force approve)
@@ -165,7 +165,6 @@ export async function createSpecForIssue(
      githubIssueNumber: issueNumber,
      githubUrl: safeGithubUrl,
      category,
-      userDescription: safeDescription,
      // Store baseBranch for worktree creation and QA comparison
      // This comes from project.settings.mainBranch or task-level override
      ...(baseBranch && { baseBranch })
@@ -267,7 +267,7 @@ export async function githubFetch(
    headers: {
      'Accept': 'application/vnd.github+json',
      'Authorization': `Bearer ${safeToken}`,
-      'User-Agent': 'Auto-Claude-UI',
+      'User-Agent': 'Aperant',
      ...options.headers
    }
  });
@@ -298,7 +298,7 @@ export async function githubFetchWithETag(
  const headers: Record<string, string> = {
    'Accept': 'application/vnd.github+json',
    'Authorization': `Bearer ${token}`,
-    'User-Agent': 'Auto-Claude-UI'
+    'User-Agent': 'Aperant'
  };

  // Add If-None-Match header if we have a cached ETag
@@ -108,7 +108,7 @@ function formatReviewBody(result: MRReviewResult, selectedFindingIds?: string[])
    ? result.findings.filter(f => selectedSet.has(f.id))
    : result.findings;

-  let body = `## Auto Claude MR Review\n\n${result.summary}\n\n`;
+  let body = `## Aperant MR Review\n\n${result.summary}\n\n`;

  if (findings.length > 0) {
    const countText = selectedSet
@@ -130,7 +130,7 @@ function formatReviewBody(result: MRReviewResult, selectedFindingIds?: string[])
    body += `*No findings selected for this review.*\n\n`;
  }

-  body += `---\n*This review was generated by Auto Claude.*`;
+  body += `---\n*This review was generated by Aperant.*`;

  return body;
 }
@@ -335,7 +335,7 @@ describe('GitLab MR Review Handlers', () => {
    it('should format review header', () => {
      const body = formatReviewBody(baseResult);

-      expect(body).toContain('## Auto Claude MR Review');
+      expect(body).toContain('## Aperant MR Review');
      expect(body).toContain('Found 2 issues that need attention');
    });

@@ -410,7 +410,7 @@ describe('GitLab MR Review Handlers', () => {
      const body = formatReviewBody(baseResult);

      expect(body).toContain('---');
-      expect(body).toContain('*This review was generated by Auto Claude.*');
+      expect(body).toContain('*This review was generated by Aperant.*');
    });

    it('should format finding descriptions', () => {
@@ -304,9 +304,10 @@ function sendProgress(
 function sendError(
  mainWindow: BrowserWindow,
  projectId: string,
+  issueIid: number,
  error: string
 ): void {
-  mainWindow.webContents.send(IPC_CHANNELS.GITLAB_AUTOFIX_ERROR, projectId, error);
+  mainWindow.webContents.send(IPC_CHANNELS.GITLAB_AUTOFIX_ERROR, projectId, issueIid, error);
 }

 /**
@@ -498,7 +499,7 @@ export function registerAutoFixHandlers(
        });
      } catch (error) {
        debugLog('Auto-fix failed', { issueIid, error: error instanceof Error ? error.message : error });
-        sendError(mainWindow, projectId, error instanceof Error ? error.message : 'Failed to start auto-fix');
+        sendError(mainWindow, projectId, issueIid, error instanceof Error ? error.message : 'Failed to start auto-fix');
      }
    }
  );
@@ -10,15 +10,14 @@
 * 6. Approve MR
 */

-import { ipcMain } from 'electron';
-import type { BrowserWindow } from 'electron';
+import { ipcMain, BrowserWindow } from 'electron';
 import path from 'path';
 import fs from 'fs';
 import { randomUUID } from 'crypto';
 import { IPC_CHANNELS, MODEL_ID_MAP, DEFAULT_FEATURE_MODELS, DEFAULT_FEATURE_THINKING } from '../../../shared/constants';
 import { getGitLabConfig, gitlabFetch, encodeProjectPath } from './utils';
 import { readSettingsFile } from '../../settings-utils';
-import type { Project, AppSettings } from '../../../shared/types';
+import type { Project, AppSettings, IPCResult, GitLabMergeRequest } from '../../../shared/types';
 import type {
  MRReviewResult,
  MRReviewProgress,
@@ -26,6 +25,7 @@ import type {
 } from './types';
 import { createContextLogger } from '../github/utils/logger';
 import { withProjectOrNull } from '../github/utils/project-middleware';
+import { projectStore } from '../../project-store';
 import { createIPCCommunicators } from '../github/utils/ipc-communicator';
 import {
  MRReviewEngine,
@@ -47,6 +47,27 @@ const REBASE_POLL_INTERVAL_MS = 1000;
 // Default rebase timeout (60 seconds). Can be overridden via GITLAB_REBASE_TIMEOUT_MS env var
 const REBASE_TIMEOUT_MS = parseInt(process.env.GITLAB_REBASE_TIMEOUT_MS || '60000', 10);

+/**
+ * Registry of status polling intervals for MR updates
+ * Key format: `${projectId}:${mrIid}`
+ */
+const statusPollingIntervals = new Map<string, NodeJS.Timeout>();
+const pollingInProgress = new Set<string>();
+
+/**
+ * Clear all polling intervals for a specific project
+ * Called when a project is deleted to prevent memory leaks
+ */
+function clearPollingForProject(projectId: string): void {
+  const keysToDelete = Array.from(statusPollingIntervals.keys())
+    .filter(key => key.startsWith(`${projectId}:`));
+  keysToDelete.forEach(key => {
+    clearInterval(statusPollingIntervals.get(key)!);
+    statusPollingIntervals.delete(key);
+    pollingInProgress.delete(key);
+  });
+}
+
 /**
 * Get the registry key for an MR review
 */
@@ -520,7 +541,7 @@ export function registerMRReviewHandlers(
          debugLog('Posting findings', { total: result.findings.length, selected: findings.length });

          // Build note body
-          let body = `## Auto Claude MR Review\n\n${result.summary}\n\n`;
+          let body = `## Aperant MR Review\n\n${result.summary}\n\n`;

          if (findings.length > 0) {
            const countText = selectedSet
@@ -542,7 +563,7 @@ export function registerMRReviewHandlers(
            body += `*No findings selected for this review.*\n\n`;
          }

-          body += `---\n*This review was generated by Auto Claude.*`;
+          body += `---\n*This review was generated by Aperant.*`;

          const encodedProject = encodeProjectPath(config.project);

@@ -790,6 +811,7 @@ export function registerMRReviewHandlers(
        }

        const reviewedCommitSha = review.reviewedCommitSha || (review as any).reviewed_commit_sha;
+        const reviewedAt = review.reviewedAt || (review as any).reviewed_at;
        if (!reviewedCommitSha) {
          debugLog('No reviewedCommitSha in review', { mrIid });
          return { hasNewCommits: false };
@@ -813,27 +835,40 @@ export function registerMRReviewHandlers(
          if (reviewedCommitSha === currentHeadSha) {
            return {
              hasNewCommits: false,
+              hasCommitsAfterPosting: false,
              currentSha: currentHeadSha,
              reviewedSha: reviewedCommitSha,
            };
          }

-          // Get commits to count new ones
+          // Get commits to count new ones and check for commits after review posting
          const commits = await gitlabFetch(
            config.token,
            config.instanceUrl,
            `/projects/${encodedProject}/merge_requests/${mrIid}/commits`
-          ) as Array<{ id: string }>;
+          ) as Array<{ id: string; created_at: string }>;

          // Find how many commits are after the reviewed one
          let newCommitCount = 0;
+          // Check if any commits were added AFTER the review was posted
+          let hasCommitsAfterPosting = false;
+          const reviewTime = reviewedAt ? new Date(reviewedAt).getTime() : 0;
+
          for (const commit of commits) {
            if (commit.id === reviewedCommitSha) break;
            newCommitCount++;
+            // If commit was created after the review was posted, it's a true follow-up commit
+            if (reviewTime > 0 && commit.created_at) {
+              const commitTime = new Date(commit.created_at).getTime();
+              if (commitTime > reviewTime) {
+                hasCommitsAfterPosting = true;
+              }
+            }
          }

          return {
            hasNewCommits: true,
+            hasCommitsAfterPosting,
            currentSha: currentHeadSha,
            reviewedSha: reviewedCommitSha,
            newCommitCount: newCommitCount || 1,
@@ -973,4 +1008,431 @@ export function registerMRReviewHandlers(
  );

  debugLog('MR review handlers registered');
+
+  // ============================================
+  // NEW: Additional handlers for feature parity
+  // ============================================
+
+  /**
+   * Delete a posted MR review (note)
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.GITLAB_MR_DELETE_REVIEW,
+    async (_event, projectId: string, mrIid: number, noteId: number): Promise<IPCResult<{ deleted: boolean }>> => {
+      debugLog('deleteReview handler called', { projectId, mrIid, noteId });
+
+      const result = await withProjectOrNull(projectId, async (project) => {
+        const config = await getGitLabConfig(project);
+        if (!config) return { success: false, error: 'GitLab not configured' };
+
+        const { token, instanceUrl } = config;
+        const encodedProject = encodeProjectPath(config.project);
+
+        try {
+          await gitlabFetch(
+            token,
+            instanceUrl,
+            `/projects/${encodedProject}/merge_requests/${mrIid}/notes/${noteId}`,
+            { method: 'DELETE' }
+          );
+
+          // Clear the posted findings cache since the review note was deleted
+          const reviewPath = path.join(getGitLabDir(project), 'mr', `review_${mrIid}.json`);
+          const tempPath = `${reviewPath}.tmp.${randomUUID()}`;
+          try {
+            const data = JSON.parse(fs.readFileSync(reviewPath, 'utf-8'));
+            data.has_posted_findings = false;
+            data.posted_finding_ids = [];
+            // Write to temp file first, then rename atomically
+            fs.writeFileSync(tempPath, JSON.stringify(data, null, 2), 'utf-8');
+            fs.renameSync(tempPath, reviewPath);
+            debugLog('Cleared posted findings cache after note deletion', { mrIid, noteId });
+          } catch (cacheError) {
+            // Clean up temp file if it exists
+            try { fs.unlinkSync(tempPath); } catch { /* ignore cleanup errors */ }
+            debugLog('Failed to clear posted findings cache', { error: cacheError instanceof Error ? cacheError.message : cacheError });
+            // Continue anyway - the deletion succeeded even if cache update failed
+          }
+
+          return { success: true, data: { deleted: true } };
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          debugLog('Failed to delete review note', { mrIid, noteId, error: errorMessage });
+          return { success: false, error: errorMessage };
+        }
+      });
+
+      if (result === null) {
+        return { success: false, error: 'Project not found' };
+      }
+      return result;
+    }
+  );
+
+  /**
+   * Check MR merge readiness
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.GITLAB_MR_CHECK_MERGE_READINESS,
+    async (_event, projectId: string, mrIid: number): Promise<IPCResult<{
+      canMerge: boolean;
+      hasConflicts: boolean;
+      needsDiscussion: boolean;
+      pipelineStatus?: string;
+    }>> => {
+      debugLog('checkMergeReadiness handler called', { projectId, mrIid });
+
+      const result = await withProjectOrNull(projectId, async (project) => {
+        const config = await getGitLabConfig(project);
+        if (!config) return { success: false, error: 'GitLab not configured' };
+
+        const { token, instanceUrl } = config;
+        const encodedProject = encodeProjectPath(config.project);
+
+        try {
+          const mrData = await gitlabFetch(
+            token,
+            instanceUrl,
+            `/projects/${encodedProject}/merge_requests/${mrIid}`
+          ) as {
+            merge_status?: string;
+            detailed_merge_status?: string;
+            has_conflicts?: boolean;
+            blocking_discussions_resolved?: boolean;
+            pipeline?: { status?: string };
+          };
+
+          const detailedStatus = mrData.detailed_merge_status || mrData.merge_status || 'cannot_be_merged';
+          const canMerge = detailedStatus === 'can_be_merged' || detailedStatus === 'mergeable';
+          const hasConflicts = mrData.has_conflicts || false;
+          const needsDiscussion = detailedStatus === 'discussions_not_resolved' || mrData.blocking_discussions_resolved === false;
+          const pipelineStatus = mrData.pipeline?.status;
+
+          return {
+            success: true,
+            data: {
+              canMerge,
+              hasConflicts,
+              needsDiscussion,
+              pipelineStatus
+            }
+          };
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          debugLog('Failed to check merge readiness', { mrIid, error: errorMessage });
+          return { success: false, error: errorMessage };
+        }
+      });
+
+      if (result === null) {
+        return { success: false, error: 'Project not found' };
+      }
+      return result;
+    }
+  );
+
+  /**
+   * Get AI review logs for an MR
+   * TODO: Return structured PRLogs type instead of string[] to match MRLogs component expectations
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.GITLAB_MR_GET_LOGS,
+    async (_event, projectId: string, mrIid: number): Promise<IPCResult<string[]>> => {
+      debugLog('getLogs handler called', { projectId, mrIid });
+
+      const result = await withProjectOrNull(projectId, async (project) => {
+        const reviewPath = path.join(getGitLabDir(project), 'mr', `review_${mrIid}.json`);
+        const logsPath = path.join(getGitLabDir(project), 'mr', `logs_${mrIid}.json`);
+
+        try {
+          let logs: string[] = [];
+
+          if (fs.existsSync(logsPath)) {
+            const logsData = JSON.parse(fs.readFileSync(logsPath, 'utf-8'));
+            logs = logsData.entries || [];
+          } else if (fs.existsSync(reviewPath)) {
+            // If no separate log file, return basic info from review
+            const reviewData = JSON.parse(fs.readFileSync(reviewPath, 'utf-8'));
+            logs = [`Review completed at ${reviewData.reviewed_at || 'unknown'}`];
+          }
+
+          return { success: true, data: logs };
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          debugLog('Failed to get logs', { mrIid, error: errorMessage });
+          return { success: false, error: errorMessage };
+        }
+      });
+
+      if (result === null) {
+        return { success: false, error: 'Project not found' };
+      }
+      return result;
+    }
+  );
+
+  /**
+   * Start status polling for MR updates
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.GITLAB_MR_STATUS_POLL_START,
+    async (event, projectId: string, mrIid: number, intervalMs: number = 5000): Promise<IPCResult<{ polling: boolean }>> => {
+      debugLog('statusPollStart handler called', { projectId, mrIid, intervalMs });
+
+      const result = await withProjectOrNull(projectId, async (_project) => {
+        const pollKey = `${projectId}:${mrIid}`;
+
+        // Clear existing interval if any
+        if (statusPollingIntervals.has(pollKey)) {
+          clearInterval(statusPollingIntervals.get(pollKey)!);
+        }
+
+        // Get the window that initiated this polling - more robust than getAllWindows()[0]
+        const callingWindow = BrowserWindow.fromWebContents(event.sender);
+        if (!callingWindow) {
+          return { success: false, error: 'Could not identify calling window' };
+        }
+
+        // Clamp interval to safe range (1s to 60s)
+        const safeIntervalMs = Number.isFinite(intervalMs)
+          ? Math.min(60_000, Math.max(1_000, intervalMs))
+          : 5_000;
+
+        // Start new polling interval
+        const interval = setInterval(async () => {
+          const pollKey = `${projectId}:${mrIid}`;
+
+          // Stop polling if window is destroyed
+          if (!callingWindow || callingWindow.isDestroyed()) {
+            clearInterval(interval);
+            statusPollingIntervals.delete(pollKey);
+            pollingInProgress.delete(pollKey);
+            return;
+          }
+
+          // Prevent concurrent polls
+          if (pollingInProgress.has(pollKey)) {
+            return;
+          }
+
+          pollingInProgress.add(pollKey);
+
+          try {
+            // Fetch current project to avoid stale config from closure
+            const currentProject = projectStore.getProject(projectId);
+            if (!currentProject) {
+              debugLog('Project not found during poll - stopping poller', { projectId });
+              clearInterval(interval);
+              statusPollingIntervals.delete(pollKey);
+              pollingInProgress.delete(pollKey);
+              return;
+            }
+
+            // Emit status update to renderer
+            if (callingWindow && !callingWindow.isDestroyed()) {
+
+              const config = await getGitLabConfig(currentProject);
+              if (!config) return;
+
+              const { token, instanceUrl } = config;
+              const encodedProject = encodeProjectPath(config.project);
+
+              const mrData = await gitlabFetch(
+                token,
+                instanceUrl,
+                `/projects/${encodedProject}/merge_requests/${mrIid}`
+              ) as {
+                state?: string;
+                merge_status?: string;
+                updated_at?: string;
+              };
+
+              callingWindow.webContents.send(IPC_CHANNELS.GITLAB_MR_STATUS_UPDATE, {
+                projectId,
+                mrIid,
+                state: mrData.state,
+                mergeStatus: mrData.merge_status,
+                updatedAt: mrData.updated_at
+              });
+            }
+          } catch (error) {
+            debugLog('Status poll error', { mrIid, error });
+          } finally {
+            pollingInProgress.delete(pollKey);
+          }
+        }, safeIntervalMs);
+
+        statusPollingIntervals.set(pollKey, interval);
+
+        return { success: true, data: { polling: true } };
+      });
+
+      if (result === null) {
+        return { success: false, error: 'Project not found' };
+      }
+      return result;
+    }
+  );
+
+  ipcMain.handle(
+    IPC_CHANNELS.GITLAB_MR_STATUS_POLL_STOP,
+    async (_event, projectId: string, mrIid: number): Promise<IPCResult<{ stopped: boolean }>> => {
+      debugLog('statusPollStop handler called', { projectId, mrIid });
+
+      const pollKey = `${projectId}:${mrIid}`;
+
+      if (statusPollingIntervals.has(pollKey)) {
+        clearInterval(statusPollingIntervals.get(pollKey)!);
+        statusPollingIntervals.delete(pollKey);
+        pollingInProgress.delete(pollKey);
+        return { success: true, data: { stopped: true } };
+      }
+
+      return { success: true, data: { stopped: false } };
+    }
+  );
+
+  /**
+   * Get MR review memories
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.GITLAB_MR_MEMORY_GET,
+    async (_event, projectId: string, mrIid: number): Promise<IPCResult<unknown[]>> => {
+      debugLog('memoryGet handler called', { projectId, mrIid });
+
+      // TODO: Implement memory retrieval from Graphiti memory system
+      return {
+        success: false,
+        error: 'Memory feature not yet implemented',
+        code: 'NOT_IMPLEMENTED'
+      } as IPCResult<unknown[]>;
+    }
+  );
+
+  /**
+   * Search MR review memories
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.GITLAB_MR_MEMORY_SEARCH,
+    async (_event, projectId: string, query: string): Promise<IPCResult<unknown[]>> => {
+      debugLog('memorySearch handler called', { projectId, query });
+
+      // TODO: Implement memory search from Graphiti memory system
+      return {
+        success: false,
+        error: 'Memory feature not yet implemented',
+        code: 'NOT_IMPLEMENTED'
+      } as IPCResult<unknown[]>;
+    }
+  );
+
+  /**
+   * Auto-fix issues in MR
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.GITLAB_MR_FIX,
+    async (_event, projectId: string, mrIid: number, findings: string[]): Promise<IPCResult<{ fixed: number }>> => {
+      debugLog('autoFix handler called', { projectId, mrIid, findingsCount: findings.length });
+
+      // TODO: Implement auto-fix functionality
+      // This will integrate with the existing autofix handlers
+      return {
+        success: false,
+        error: 'Auto-fix not yet implemented - use GITLAB_AUTOFIX_START instead'
+      };
+    }
+  );
+
+  /**
+   * Batch load reviews for multiple MRs
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.GITLAB_MR_GET_REVIEWS_BATCH,
+    async (_event, projectId: string, mrIids: number[]): Promise<IPCResult<Record<number, MRReviewResult | null>>> => {
+      debugLog('getReviewsBatch handler called', { projectId, mrIids });
+
+      const result = await withProjectOrNull(projectId, async (project) => {
+        const results: Record<number, MRReviewResult | null> = {};
+
+        for (const mrIid of mrIids) {
+          const review = getReviewResult(project, mrIid);
+          results[mrIid] = review;
+        }
+
+        return { success: true, data: results };
+      });
+
+      if (result === null) {
+        return { success: false, error: 'Project not found' };
+      }
+      return result;
+    }
+  );
+
+  /**
+   * Load more MRs (pagination)
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.GITLAB_MR_LIST_MORE,
+    async (
+      _event,
+      projectId: string,
+      state?: 'opened' | 'closed' | 'merged' | 'all',
+      page: number = 2
+    ): Promise<IPCResult<{ mrs: GitLabMergeRequest[]; hasMore: boolean }>> => {
+      debugLog('listMore handler called', { projectId, state, page });
+
+      const result = await withProjectOrNull(projectId, async (project) => {
+        const config = await getGitLabConfig(project);
+        if (!config) {
+          return { success: false, error: 'GitLab not configured' };
+        }
+
+        const { token, instanceUrl } = config;
+        const encodedProject = encodeProjectPath(config.project);
+
+        try {
+          const stateParam = state === 'all' ? undefined : state;
+          // Over-fetch by 1 to reliably determine if there are more pages
+          const queryParams = new URLSearchParams({
+            per_page: '21',
+            page: String(page),
+            ...(stateParam && { state: stateParam })
+          });
+
+          const mrs = await gitlabFetch(
+            token,
+            instanceUrl,
+            `/projects/${encodedProject}/merge_requests?${queryParams.toString()}`
+          ) as GitLabMergeRequest[];
+
+          // If we got 21 items, there's definitely more. Otherwise we're at the end.
+          const hasMore = mrs.length > 20;
+          // Only return the requested page size (20 items)
+          const returnMrs = hasMore ? mrs.slice(0, 20) : mrs;
+
+          return {
+            success: true,
+            data: {
+            mrs: returnMrs,
+            hasMore
+            }
+          };
+        } catch (error) {
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          debugLog('Failed to load more MRs', { projectId, page, error: errorMessage });
+          return { success: false, error: errorMessage };
+        }
+      });
+
+      if (result === null) {
+        return { success: false, error: 'Project not found' };
+      }
+      return result;
+    }
+  );
+
+  debugLog('Additional MR handlers registered');
 }
+
+export { clearPollingForProject };
@@ -5,7 +5,7 @@

 import { mkdir, writeFile, readFile, stat } from 'fs/promises';
 import path from 'path';
-import type { Project, TaskMetadata } from '../../../shared/types';
+import type { Project } from '../../../shared/types';
 import type { GitLabAPIIssue, GitLabAPINoteBasic, GitLabConfig } from './types';
 import { labelMatchesWholeWord } from '../shared/label-utils';
 import { sanitizeText, sanitizeStringArray } from '../shared/sanitize';
@@ -460,12 +460,11 @@ export async function createSpecForIssue(
    await writeFile(metadataPath, JSON.stringify(metadata, null, 2), 'utf-8');

    // Create task_metadata.json (consistent with GitHub format for backend compatibility)
-    const taskMetadata: TaskMetadata = {
+    const taskMetadata = {
      sourceType: 'gitlab' as const,
      gitlabIssueIid: safeIssue.iid,
      gitlabUrl: safeIssue.web_url,
      category: determineCategoryFromLabels(safeIssue.labels || []),
-      userDescription: safeIssue.description || '',
      // Store baseBranch for worktree creation and QA comparison
      ...(baseBranch && { baseBranch })
    };
@@ -244,7 +244,6 @@ export async function convertIdeaToTask(
      // Build task description and metadata
      const taskDescription = buildTaskDescription(idea);
      const metadata = buildTaskMetadata(idea);
-      metadata.userDescription = taskDescription;

      // Create spec files (inside lock to ensure atomicity)
      createSpecFiles(specDir, idea, taskDescription);
@@ -133,7 +133,7 @@ export function registerInsightsHandlers(getMainWindow: () => BrowserWindow | nu
      }

      if (!project.autoBuildPath) {
-        return { success: false, error: "Auto Claude not initialized for this project" };
+        return { success: false, error: "Aperant not initialized for this project" };
      }

      try {
@@ -524,8 +524,7 @@ ${safeDescription || 'No description provided.'}
              linearIssueId: sanitizeText(issue.id, 100),
              linearIdentifier: safeIdentifier,
              linearUrl: safeUrl,
-              category: 'feature',
-              userDescription: description,
+              category: 'feature'
            };
            // lgtm[js/http-to-file-access] - specDir is controlled, Linear data sanitized
            writeFileSync(path.join(specDir, 'task_metadata.json'), JSON.stringify(metadata, null, 2), 'utf-8');
@@ -12,8 +12,12 @@ import { getOllamaExecutablePaths, getOllamaInstallCommand as getPlatformOllamaI
 import { IPC_CHANNELS } from '../../shared/constants';
 import type {
  IPCResult,
+  InfrastructureStatus,
+  MemoryValidationResult,
 } from '../../shared/types';
 import { openTerminalWithCommand } from './claude-code-handlers';
+import { getEmbeddingProvider } from './context/memory-service-factory';
+const { join } = path;

 /**
 * Ollama Service Status
@@ -547,6 +551,154 @@ export function registerMemoryHandlers(): void {
    }
  );

+  // ============================================
+  // Memory Infrastructure Handlers (LadybugDB - libSQL)
+  // ============================================
+
+  /**
+   * Get memory infrastructure status.
+   * Checks if the local libSQL database is available and returns status.
+   *
+   * @async
+   * @param {string} [dbPath] - Optional custom database path (for testing)
+   * @returns {Promise<IPCResult<InfrastructureStatus>>} Status with memory database info
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.INFRASTRUCTURE_GET_STATUS,
+    async (_, dbPath?: string): Promise<IPCResult<InfrastructureStatus>> => {
+      try {
+        const { getMemoryClient } = await import('../ai/memory/db');
+        const { existsSync } = await import('fs');
+
+        // Get default memory.db path from userData
+        const { app } = await import('electron');
+        const defaultPath = join(app.getPath('userData'), 'memory.db');
+        const checkPath = dbPath || defaultPath;
+
+        // Check if database file exists
+        const dbExists = existsSync(checkPath);
+
+        // Try to initialize the client to verify it's functional
+        await getMemoryClient();
+        const embeddingProvider = getEmbeddingProvider();
+
+        return {
+          success: true,
+          data: {
+            memory: {
+              kuzuInstalled: false, // Kuzu is no longer used, libSQL only
+              databasePath: checkPath,
+              databaseExists: dbExists,
+              databases: dbExists ? ['memory'] : [],
+              error: dbExists ? undefined : 'Database file not found',
+            },
+            ready: dbExists && embeddingProvider !== null,
+          },
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Failed to get infrastructure status',
+        };
+      }
+    }
+  );
+
+  /**
+   * List available memory databases.
+   * Returns a list of database names available in the system.
+   *
+   * @async
+   * @param {string} [dbPath] - Optional custom database path (for testing)
+   * @returns {Promise<IPCResult<string[]>>} Array of database names
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.INFRASTRUCTURE_LIST_DATABASES,
+    async (_, dbPath?: string): Promise<IPCResult<string[]>> => {
+      try {
+        const { existsSync } = await import('fs');
+        const { app } = await import('electron');
+        const { join } = await import('path');
+
+        const defaultPath = join(app.getPath('userData'), 'memory.db');
+        const checkPath = dbPath || defaultPath;
+
+        const databases: string[] = [];
+        if (existsSync(checkPath)) {
+          databases.push('memory');
+        }
+
+        return { success: true, data: databases };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Failed to list databases',
+        };
+      }
+    }
+  );
+
+  /**
+   * Test memory database connection.
+   * Verifies that a specific database can be connected to and queried.
+   *
+   * @async
+   * @param {string} [dbPath] - Optional custom database path
+   * @param {string} [database] - Database name to test (default: 'memory')
+   * @returns {Promise<IPCResult<MemoryValidationResult>>} Connection test result
+   */
+  ipcMain.handle(
+    IPC_CHANNELS.INFRASTRUCTURE_TEST_CONNECTION,
+    async (_, dbPath?: string, database?: string): Promise<IPCResult<MemoryValidationResult>> => {
+      try {
+        const { getMemoryClient } = await import('../ai/memory/db');
+        const { existsSync } = await import('fs');
+        const { app } = await import('electron');
+        const { join } = await import('path');
+
+        const defaultPath = join(app.getPath('userData'), 'memory.db');
+        const checkPath = dbPath || defaultPath;
+        const dbName = database || 'memory';
+
+        // Check if database file exists
+        if (!existsSync(checkPath)) {
+          return {
+            success: true,
+            data: {
+              success: false,
+              message: `Database '${dbName}' not found at ${checkPath}`,
+            },
+          };
+        }
+
+        // Try to connect and run a simple query
+        const client = await getMemoryClient();
+        await client.execute('SELECT 1');
+
+        const embeddingProvider = getEmbeddingProvider();
+
+        return {
+          success: true,
+          data: {
+            success: true,
+            message: `Successfully connected to ${dbName} database`,
+            details: {
+              provider: embeddingProvider || 'none',
+            },
+          },
+        };
+      } catch (error) {
+        return {
+          success: true, // Return success with failure details in data
+          data: {
+            success: false,
+            message: error instanceof Error ? error.message : 'Connection test failed',
+          },
+        };
+      }
+    }
+  );
+
  // ============================================
  // Memory System (libSQL-backed) Handlers
  // ============================================
@@ -266,6 +266,9 @@ export function registerProjectHandlers(
  ipcMain.handle(
    IPC_CHANNELS.PROJECT_REMOVE,
    async (_, projectId: string): Promise<IPCResult> => {
+      // Clear GitLab MR polling for this project to prevent memory leaks
+      const { clearPollingForProject } = await import('./gitlab/mr-review-handlers');
+      clearPollingForProject(projectId);
      const success = projectStore.removeProject(projectId);
      return { success };
    }
@@ -585,7 +585,6 @@ ${(feature.acceptance_criteria || []).map((c: string) => `- [ ] ${c}`).join("\n"
          sourceType: "roadmap",
          featureId: feature.id,
          category: "feature",
-          userDescription: taskDescription,
        };
        await writeFileWithRetry(path.join(specDir, "task_metadata.json"), JSON.stringify(metadata, null, 2), { encoding: 'utf-8' });

@@ -264,7 +264,7 @@ const detectAutoBuildSourcePath = (): string | null => {
    }
  }

-  console.warn('[detectAutoBuildSourcePath] Could not auto-detect Auto Claude prompts path. Please configure manually in settings.');
+  console.warn('[detectAutoBuildSourcePath] Could not auto-detect Aperant prompts path. Please configure manually in settings.');
  console.warn('[detectAutoBuildSourcePath] Set DEBUG=1 environment variable for detailed path checking.');
  return null;
 };
@@ -933,6 +933,20 @@ export function registerSettingsHandlers(
      try {
        const settings = readSettingsFile() ?? {};
        const accounts: ProviderAccount[] = (settings.providerAccounts as ProviderAccount[] | undefined) ?? [];
+
+        // Prevent duplicate: same email + provider already registered
+        if (account.email) {
+          const duplicate = accounts.find(
+            (a) => a.provider === account.provider && a.email?.toLowerCase() === account.email!.toLowerCase()
+          );
+          if (duplicate) {
+            return {
+              success: false,
+              error: `DUPLICATE_EMAIL:${duplicate.name}`,
+            };
+          }
+        }
+
        const now = Date.now();
        const newAccount: ProviderAccount = {
          ...account,
@@ -1039,16 +1053,6 @@ export function registerSettingsHandlers(
          // Non-fatal: usage-monitor may use stale order until next app restart
        }

-        // Trigger immediate usage check so the new active profile's data is fetched
-        // Without this, the UI shows "Usage data unavailable" until the next polling cycle
-        try {
-          const { getUsageMonitor } = await import('../claude-profile/usage-monitor');
-          const monitor = getUsageMonitor();
-          monitor.checkNow();
-        } catch {
-          // Non-fatal: usage will be fetched on next poll
-        }
-
        console.warn('[PROVIDER_ACCOUNTS_SET_QUEUE_ORDER] Queue order updated:', order.length, 'accounts');
        return { success: true };
      } catch (error) {
@@ -207,11 +207,10 @@ export function registerTaskCRUDHandlers(agentManager: AgentManager): void {
      const specDir = path.join(specsDir, specId);
      mkdirSync(specDir, { recursive: true });

-      // Build metadata with source type and preserve original user description
+      // Build metadata with source type
      const taskMetadata: TaskMetadata = {
        sourceType: 'manual',
-        ...metadata,
-        userDescription: description,
+        ...metadata
      };

      // Process and save attached images
@@ -593,11 +592,6 @@ export function registerTaskCRUDHandlers(agentManager: AgentManager): void {
            updatedMetadata.attachedImages = savedImages;
          }

-          // Keep userDescription in sync when description is edited
-          if (updates.description !== undefined) {
-            updatedMetadata.userDescription = updates.description;
-          }
-
          // Sanitize thinking levels and update task_metadata.json
          sanitizeThinkingLevels(updatedMetadata);
          const metadataPath = path.join(specDir, 'task_metadata.json');
@@ -177,7 +177,7 @@ export function registerTaskExecutionHandlers(
        mainWindow.webContents.send(
          IPC_CHANNELS.TASK_ERROR,
          taskId,
-          'Git repository required. Please run "git init" in your project directory. Auto Claude uses git worktrees for isolated builds.'
+          'Git repository required. Please run "git init" in your project directory. Aperant uses git worktrees for isolated builds.'
        );
        return;
      }
@@ -12,6 +12,7 @@ import { debugLog, } from '../../shared/utils/debug-logger';
 import { migrateSession } from '../claude-profile/session-utils';
 import { createProfileDirectory } from '../claude-profile/profile-utils';
 import { isValidConfigDir } from '../utils/config-path-validator';
+import { sessionPersistence } from '../terminal/session-persistence';


 /**
@@ -115,6 +116,22 @@ export function registerTerminalHandlers(
    }
  );

+  // Save terminal buffer (serialized xterm.js content)
+  ipcMain.handle(
+    IPC_CHANNELS.TERMINAL_SAVE_BUFFER,
+    async (_, terminalId: string, serializedBuffer: string): Promise<IPCResult> => {
+      try {
+        sessionPersistence.saveBuffer(terminalId, serializedBuffer);
+        return { success: true };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : 'Failed to save terminal buffer',
+        };
+      }
+    }
+  );
+
  // Claude profile management (multi-account support)
  ipcMain.handle(
    IPC_CHANNELS.CLAUDE_PROFILES_GET,
@@ -205,14 +205,14 @@ function ensureGitignoreEntries(projectPath: string, entries: string[]): void {
      appendContent += '\n';
    }

-    appendContent += '\n# Auto Claude data directory\n';
+    appendContent += '\n# Aperant data directory\n';
    for (const entry of entriesToAdd) {
      appendContent += entry + '\n';
    }

    appendFileSync(gitignorePath, appendContent);
  } else {
-    writeFileSync(gitignorePath, '# Auto Claude data directory\n' + entriesToAdd.join('\n') + '\n', 'utf-8');
+    writeFileSync(gitignorePath, '# Aperant data directory\n' + entriesToAdd.join('\n') + '\n', 'utf-8');
  }

  debug('Added entries to .gitignore', { entries: entriesToAdd });
@@ -288,13 +288,13 @@ export function initializeProject(projectPath: string): InitializationResult {
    };
  }

-  // Check git status - Auto Claude requires git for worktree-based builds
+  // Check git status - Aperant requires git for worktree-based builds
  const gitStatus = checkGitStatus(projectPath);
  if (!gitStatus.isGitRepo || !gitStatus.hasCommits) {
    debug('Git check failed', { gitStatus });
    return {
      success: false,
-      error: gitStatus.error || 'Git repository required. Auto Claude uses git worktrees for isolated builds.'
+      error: gitStatus.error || 'Git repository required. Aperant uses git worktrees for isolated builds.'
    };
  }

@@ -375,7 +375,7 @@ export function ensureDataDirectories(projectPath: string): InitializationResult
 *
 * IMPORTANT: Only .auto-claude/ is considered a valid "installed" auto-claude.
 * The auto-claude/ folder (if it exists) is the SOURCE CODE being developed,
- * not an installation. This allows Auto Claude to be used to develop itself.
+ * not an installation. This allows Aperant to be used to develop itself.
 */
 export function getAutoBuildPath(projectPath: string): string | null {
  const dotAutoBuildPath = path.join(projectPath, '.auto-claude');
--- a/Show More
+++ b/Show More