@in-the-loop-labs/pair-review 3.2.2 → 3.3.0

package/src/database.js

@@ -2,6 +2,7 @@
 const Database = require('better-sqlite3');
 const path = require('path');
 const fs = require('fs').promises;
+const fsSync = require('fs');
 const { getConfigDir } = require('./config');
 
 let dbPath = null;
@@ -20,7 +21,7 @@ function getDbPath() {
 /**
  * Current schema version - increment this when adding new migrations
  */
-const CURRENT_SCHEMA_VERSION = 36;
+const CURRENT_SCHEMA_VERSION = 43;
 
 /**
  * Database schema SQL statements
@@ -142,7 +143,7 @@ const SCHEMA_SQL = {
   repo_settings: `
     CREATE TABLE IF NOT EXISTS repo_settings (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
-      repository TEXT NOT NULL UNIQUE,
+      repository TEXT NOT NULL UNIQUE COLLATE NOCASE,
       default_instructions TEXT,
       default_provider TEXT,
       default_model TEXT,
@@ -151,6 +152,11 @@ const SCHEMA_SQL = {
       default_chat_instructions TEXT,
       local_path TEXT,
       auto_branch_review INTEGER DEFAULT 0,
+      pool_size INTEGER,
+      pool_fetch_interval_minutes INTEGER,
+      pool_fetch_started_at TEXT,
+      pool_fetch_finished_at TEXT,
+      load_skills INTEGER,
       created_at TEXT DEFAULT CURRENT_TIMESTAMP,
       updated_at TEXT DEFAULT CURRENT_TIMESTAMP
     )
@@ -277,6 +283,21 @@ const SCHEMA_SQL = {
       collection TEXT NOT NULL,
       fetched_at DATETIME DEFAULT CURRENT_TIMESTAMP
     )
+  `,
+
+  worktree_pool: `
+    CREATE TABLE IF NOT EXISTS worktree_pool (
+      id TEXT PRIMARY KEY,
+      repository TEXT NOT NULL,
+      path TEXT NOT NULL UNIQUE,
+      status TEXT NOT NULL DEFAULT 'available'
+        CHECK(status IN ('available', 'in_use', 'switching', 'creating')),
+      current_pr_number INTEGER,
+      current_review_id INTEGER,
+      last_switched_at TEXT,
+      last_fetched_at TEXT,
+      created_at TEXT NOT NULL
+    )
   `
 };
 
@@ -293,7 +314,7 @@ const INDEX_SQL = [
   'CREATE INDEX IF NOT EXISTS idx_pr_metadata_last_accessed ON pr_metadata(last_accessed_at)',
   'CREATE INDEX IF NOT EXISTS idx_worktrees_last_accessed ON worktrees(last_accessed_at)',
   'CREATE INDEX IF NOT EXISTS idx_worktrees_repo ON worktrees(repository)',
-  'CREATE UNIQUE INDEX IF NOT EXISTS idx_repo_settings_repository ON repo_settings(repository)',
+  'CREATE UNIQUE INDEX IF NOT EXISTS idx_repo_settings_repository ON repo_settings(repository COLLATE NOCASE)',
   'CREATE UNIQUE INDEX IF NOT EXISTS idx_reviews_local ON reviews(local_path, local_head_sha, local_head_branch) WHERE review_type = \'local\'',
   // Partial unique index for PR reviews only (NULL pr_number values for local reviews should not conflict)
   'CREATE UNIQUE INDEX IF NOT EXISTS idx_reviews_pr_unique ON reviews(pr_number, repository) WHERE review_type = \'pr\'',
@@ -315,7 +336,11 @@ const INDEX_SQL = [
   // Context files indexes
   'CREATE INDEX IF NOT EXISTS idx_context_files_review ON context_files(review_id)',
   // GitHub PR cache indexes
-  'CREATE UNIQUE INDEX IF NOT EXISTS idx_github_pr_cache_unique ON github_pr_cache(collection, owner, repo, number)'
+  'CREATE UNIQUE INDEX IF NOT EXISTS idx_github_pr_cache_unique ON github_pr_cache(collection, owner, repo, number)',
+  // Worktree pool indexes
+  'CREATE INDEX IF NOT EXISTS idx_worktree_pool_repo ON worktree_pool(repository)',
+  'CREATE INDEX IF NOT EXISTS idx_worktree_pool_status ON worktree_pool(repository, status)',
+  'CREATE INDEX IF NOT EXISTS idx_worktree_pool_lru ON worktree_pool(repository, status, last_switched_at)'
 ];
 
 /**
@@ -1635,6 +1660,212 @@ const MIGRATIONS = {
     }
 
     console.log('Migration to schema version 36 complete');
+  },
+
+  37: (db) => {
+    console.log('Running migration to schema version 37...');
+
+    if (!tableExists(db, 'worktree_pool')) {
+      db.exec(SCHEMA_SQL.worktree_pool);
+      console.log('  Created worktree_pool table');
+    }
+
+    db.exec('CREATE INDEX IF NOT EXISTS idx_worktree_pool_repo ON worktree_pool(repository)');
+    db.exec('CREATE INDEX IF NOT EXISTS idx_worktree_pool_status ON worktree_pool(repository, status)');
+    db.exec('CREATE INDEX IF NOT EXISTS idx_worktree_pool_lru ON worktree_pool(repository, status, last_switched_at)');
+
+    console.log('Migration to schema version 37 complete');
+  },
+
+  // Migration to version 38: Add current_review_id to worktree_pool for persistent ownership
+  38: (db) => {
+    console.log('Running migration to schema version 38...');
+
+    if (tableExists(db, 'worktree_pool') && !columnExists(db, 'worktree_pool', 'current_review_id')) {
+      db.prepare('ALTER TABLE worktree_pool ADD COLUMN current_review_id INTEGER').run();
+      console.log('  Added column current_review_id to worktree_pool');
+    }
+
+    console.log('Migration to schema version 38 complete');
+  },
+
+  39: (db) => {
+    console.log('Running migration to schema version 39: Add creating status to worktree_pool...');
+
+    if (!tableExists(db, 'worktree_pool')) {
+      console.log('  worktree_pool table does not exist, skipping');
+      console.log('Migration to schema version 39 complete');
+      return;
+    }
+
+    // SQLite does not support ALTER TABLE to modify CHECK constraints.
+    // Rebuild the table with the updated constraint.
+    db.pragma('foreign_keys = OFF');
+
+    db.prepare(`CREATE TABLE IF NOT EXISTS worktree_pool_rebuild (
+      id TEXT PRIMARY KEY,
+      repository TEXT NOT NULL,
+      path TEXT NOT NULL UNIQUE,
+      status TEXT NOT NULL DEFAULT 'available'
+        CHECK(status IN ('available', 'in_use', 'switching', 'creating')),
+      current_pr_number INTEGER,
+      current_review_id INTEGER,
+      last_switched_at TEXT,
+      last_fetched_at TEXT,
+      created_at TEXT NOT NULL
+    )`).run();
+
+    const cols = [
+      'id', 'repository', 'path', 'status',
+      'current_pr_number', 'current_review_id',
+      'last_switched_at', 'last_fetched_at', 'created_at'
+    ].join(', ');
+
+    const rebuild = db.transaction(() => {
+      db.prepare(`INSERT INTO worktree_pool_rebuild (${cols}) SELECT ${cols} FROM worktree_pool`).run();
+      db.prepare('DROP TABLE worktree_pool').run();
+      db.prepare('ALTER TABLE worktree_pool_rebuild RENAME TO worktree_pool').run();
+    });
+    rebuild();
+
+    db.pragma('foreign_keys = ON');
+
+    // Recreate indexes on the rebuilt table (must match INDEX_SQL definitions)
+    db.prepare('CREATE INDEX IF NOT EXISTS idx_worktree_pool_repo ON worktree_pool(repository)').run();
+    db.prepare('CREATE INDEX IF NOT EXISTS idx_worktree_pool_status ON worktree_pool(repository, status)').run();
+    db.prepare('CREATE INDEX IF NOT EXISTS idx_worktree_pool_lru ON worktree_pool(repository, status, last_switched_at)').run();
+
+    console.log('  Rebuilt worktree_pool with creating status in CHECK constraint');
+    console.log('Migration to schema version 39 complete');
+  },
+  40: (db) => {
+    console.log('Running migration to schema version 40: Add pool settings to repo_settings...');
+    const addColumnIfNotExists = (table, column, definition) => {
+      const tableInfo = db.prepare(`PRAGMA table_info(${table})`).all();
+      const columnExists = tableInfo.some(col => col.name === column);
+      if (!columnExists) {
+        db.prepare(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`).run();
+        console.log(`  Added column ${column} to ${table}`);
+      }
+    };
+    addColumnIfNotExists('repo_settings', 'pool_size', 'INTEGER');
+    addColumnIfNotExists('repo_settings', 'pool_fetch_interval_minutes', 'INTEGER');
+    console.log('Migration to schema version 40 complete');
+  },
+
+  41: (db) => {
+    console.log('Running migration to schema version 41: Add pool fetch coordination columns to repo_settings...');
+    const addColumnIfNotExists = (table, column, definition) => {
+      const tableInfo = db.prepare(`PRAGMA table_info(${table})`).all();
+      const columnExists = tableInfo.some(col => col.name === column);
+      if (!columnExists) {
+        db.prepare(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`).run();
+        console.log(`  Added column ${column} to ${table}`);
+      }
+    };
+    addColumnIfNotExists('repo_settings', 'pool_fetch_started_at', 'TEXT');
+    addColumnIfNotExists('repo_settings', 'pool_fetch_finished_at', 'TEXT');
+    console.log('Migration to schema version 41 complete');
+  },
+
+  42: (db) => {
+    console.log('Running migration to schema version 42: Add COLLATE NOCASE to repo_settings.repository...');
+
+    if (!tableExists(db, 'repo_settings')) {
+      console.log('  repo_settings table does not exist, skipping');
+      console.log('Migration to schema version 42 complete');
+      return;
+    }
+
+    // SQLite does not support ALTER TABLE to modify column collation.
+    // Rebuild the table with the updated column definition.
+    db.pragma('foreign_keys = OFF');
+    try {
+      db.prepare('DROP TABLE IF EXISTS repo_settings_rebuild').run();
+
+      db.prepare(`CREATE TABLE IF NOT EXISTS repo_settings_rebuild (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        repository TEXT NOT NULL UNIQUE COLLATE NOCASE,
+        default_instructions TEXT,
+        default_provider TEXT,
+        default_model TEXT,
+        default_council_id TEXT,
+        default_tab TEXT,
+        default_chat_instructions TEXT,
+        local_path TEXT,
+        auto_branch_review INTEGER DEFAULT 0,
+        pool_size INTEGER,
+        pool_fetch_interval_minutes INTEGER,
+        pool_fetch_started_at TEXT,
+        pool_fetch_finished_at TEXT,
+        created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+        updated_at TEXT DEFAULT CURRENT_TIMESTAMP
+      )`).run();
+
+      // Auto-merge case-duplicate repositories, keeping the most recently updated row.
+      const dupes = db.prepare(`SELECT LOWER(repository) as repo, COUNT(*) as cnt FROM repo_settings GROUP BY LOWER(repository) HAVING cnt > 1`).all();
+      if (dupes.length > 0) {
+        const removedRows = [];
+        for (const { repo } of dupes) {
+          const rows = db.prepare(`SELECT * FROM repo_settings WHERE LOWER(repository) = ? ORDER BY julianday(updated_at) DESC, id DESC`).all(repo);
+          const kept = rows[0];
+          const discarded = rows.slice(1);
+          for (const row of discarded) {
+            removedRows.push(row);
+            db.prepare('DELETE FROM repo_settings WHERE id = ?').run(row.id);
+          }
+          console.warn(`  [migration 42] Case-duplicate repo "${repo}": kept id=${kept.id} (updated ${kept.updated_at}), removed ${discarded.length} older row(s)`);
+        }
+
+        // Write backup of removed rows to ~/.pair-review/ so no data is truly lost
+        try {
+          const backupPath = path.join(getConfigDir(), `migration-42-backup-${new Date().toISOString().replace(/[:.]/g, '-')}.json`);
+          fsSync.writeFileSync(backupPath, JSON.stringify(removedRows, null, 2));
+          console.warn(`  [migration 42] Backup of ${removedRows.length} removed row(s) written to ${backupPath}`);
+        } catch (backupErr) {
+          console.warn(`  [migration 42] Warning: could not write backup file: ${backupErr.message}`);
+          console.warn(`  [migration 42] Removed row data: ${JSON.stringify(removedRows)}`);
+        }
+      }
+
+      const cols = [
+        'id', 'repository', 'default_instructions', 'default_provider',
+        'default_model', 'default_council_id', 'default_tab',
+        'default_chat_instructions', 'local_path', 'auto_branch_review',
+        'pool_size', 'pool_fetch_interval_minutes',
+        'pool_fetch_started_at', 'pool_fetch_finished_at',
+        'created_at', 'updated_at'
+      ].join(', ');
+
+      const rebuild = db.transaction(() => {
+        db.prepare(`INSERT INTO repo_settings_rebuild (${cols}) SELECT ${cols} FROM repo_settings`).run();
+        db.prepare('DROP TABLE repo_settings').run();
+        db.prepare('ALTER TABLE repo_settings_rebuild RENAME TO repo_settings').run();
+      });
+      rebuild();
+
+      // Recreate the index with COLLATE NOCASE (must match INDEX_SQL definition)
+      db.prepare('CREATE UNIQUE INDEX IF NOT EXISTS idx_repo_settings_repository ON repo_settings(repository COLLATE NOCASE)').run();
+
+      console.log('  Rebuilt repo_settings with COLLATE NOCASE on repository column');
+      console.log('Migration to schema version 42 complete');
+    } finally {
+      db.pragma('foreign_keys = ON');
+    }
+  },
+
+  43: (db) => {
+    console.log('Running migration to schema version 43: Add load_skills to repo_settings...');
+    const addColumnIfNotExists = (table, column, definition) => {
+      const tableInfo = db.prepare(`PRAGMA table_info(${table})`).all();
+      const columnExists = tableInfo.some(col => col.name === column);
+      if (!columnExists) {
+        db.prepare(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`).run();
+        console.log(`  Added column ${column} to ${table}`);
+      }
+    };
+    addColumnIfNotExists('repo_settings', 'load_skills', 'INTEGER');
+    console.log('Migration to schema version 43 complete');
   }
 };
 
@@ -1903,6 +2134,7 @@ function generateWorktreeId(length = 3) {
   return `pair-review--${randomPart}`;
 }
 
+
 /**
  * WorktreeRepository class for managing worktree database records
  */
@@ -1917,29 +2149,34 @@ class WorktreeRepository {
 
   /**
    * Create a new worktree record
-   * @param {Object} prInfo - PR information { prNumber, repository, branch, path }
+   * @param {Object} prInfo - PR information { prNumber, repository, branch, path, explicitId }
    * @returns {Promise<Object>} Created worktree record
    */
   async create(prInfo) {
-    const { prNumber, repository, branch, path: worktreePath } = prInfo;
+    const { prNumber, repository, branch, path: worktreePath, explicitId } = prInfo;
 
-    // Generate unique ID (retry if collision)
     let id;
-    let attempts = 0;
-    const maxAttempts = 10;
-
-    while (attempts < maxAttempts) {
-      id = generateWorktreeId();
-      const existing = await queryOne(this.db,
-        'SELECT id FROM worktrees WHERE id = ?',
-        [id]
-      );
-      if (!existing) break;
-      attempts++;
-    }
+    if (explicitId) {
+      // Use the caller-supplied ID (e.g. pool worktree ID)
+      id = explicitId;
+    } else {
+      // Generate unique ID (retry if collision)
+      let attempts = 0;
+      const maxAttempts = 10;
+
+      while (attempts < maxAttempts) {
+        id = generateWorktreeId();
+        const existing = await queryOne(this.db,
+          'SELECT id FROM worktrees WHERE id = ?',
+          [id]
+        );
+        if (!existing) break;
+        attempts++;
+      }
 
-    if (attempts >= maxAttempts) {
-      throw new Error('Failed to generate unique worktree ID after maximum attempts');
+      if (attempts >= maxAttempts) {
+        throw new Error('Failed to generate unique worktree ID after maximum attempts');
+      }
     }
 
     const now = new Date().toISOString();
@@ -2016,10 +2253,11 @@ class WorktreeRepository {
     const dateStr = olderThan instanceof Date ? olderThan.toISOString() : olderThan;
 
     const rows = await query(this.db, `
-      SELECT id, pr_number, repository, branch, path, created_at, last_accessed_at
-      FROM worktrees
-      WHERE last_accessed_at < ?
-      ORDER BY last_accessed_at ASC
+      SELECT w.id, w.pr_number, w.repository, w.branch, w.path, w.created_at, w.last_accessed_at
+      FROM worktrees w
+      LEFT JOIN worktree_pool wp ON w.id = wp.id
+      WHERE w.last_accessed_at < ? AND wp.id IS NULL
+      ORDER BY w.last_accessed_at ASC
     `, [dateStr]);
 
     return rows;
@@ -2054,6 +2292,20 @@ class WorktreeRepository {
     return rows;
   }
 
+  /**
+   * Find all worktrees for a given repository.
+   * @param {string} repository - Repository in "owner/repo" format
+   * @returns {Promise<Array<Object>>} Array of worktree records ordered by last_accessed_at DESC
+   */
+  async findAllByRepository(repository) {
+    return await query(this.db, `
+      SELECT id, pr_number, repository, branch, path, created_at, last_accessed_at
+      FROM worktrees
+      WHERE repository = ? COLLATE NOCASE
+      ORDER BY last_accessed_at DESC
+    `, [repository]);
+  }
+
   /**
    * Update the path of an existing worktree record
    * @param {string} id - Worktree ID
@@ -2075,16 +2327,47 @@ class WorktreeRepository {
    * Get or create a worktree record (upsert-like behavior)
    * If a worktree exists for the PR, update its last_accessed_at and return it
    * Otherwise, create a new record
-   * @param {Object} prInfo - PR information { prNumber, repository, branch, path }
+   * @param {Object} prInfo - PR information { prNumber, repository, branch, path, explicitId }
    * @returns {Promise<Object>} Worktree record (existing or newly created)
    */
   async getOrCreate(prInfo) {
-    const { prNumber, repository } = prInfo;
+    const { prNumber, repository, explicitId } = prInfo;
 
     // Check if worktree already exists
     const existing = await this.findByPR(prNumber, repository);
 
     if (existing) {
+      // If explicitId is provided and differs from the existing record's ID,
+      // migrate the record to use the new ID. This happens when pool mode is
+      // enabled for a repo that already has legacy (non-pool) worktree records:
+      // the pool slot has its own ID that the worktrees row must match.
+      if (explicitId && existing.id !== explicitId) {
+        const now = new Date().toISOString();
+        await run(this.db, 'BEGIN IMMEDIATE');
+        try {
+          // Delete the old record and create a new one with the pool ID.
+          // We can't UPDATE the primary key directly in SQLite.
+          await run(this.db, `DELETE FROM worktrees WHERE id = ?`, [existing.id]);
+          await run(this.db, `
+            INSERT INTO worktrees (id, pr_number, repository, branch, path, created_at, last_accessed_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+          `, [explicitId, prNumber, repository, prInfo.branch, prInfo.path, existing.created_at, now]);
+          await run(this.db, 'COMMIT');
+        } catch (err) {
+          await run(this.db, 'ROLLBACK');
+          throw err;
+        }
+        return {
+          id: explicitId,
+          pr_number: prNumber,
+          repository,
+          branch: prInfo.branch,
+          path: prInfo.path,
+          created_at: existing.created_at,
+          last_accessed_at: now
+        };
+      }
+
       // Update last_accessed_at and potentially the path
       const now = new Date().toISOString();
       await run(this.db, `
@@ -2105,6 +2388,63 @@ class WorktreeRepository {
     return this.create(prInfo);
   }
 
+  /**
+   * Switch a worktree's PR assignment (for pool worktree switching).
+   * Unlike getOrCreate, this updates an existing record by ID rather than by PR number.
+   * Removes any conflicting non-pool worktree record for the target PR to avoid
+   * UNIQUE(pr_number, repository) violations when transitioning from non-pool to pool mode.
+   * @param {string} id - Worktree ID
+   * @param {number} prNumber - New PR number
+   * @param {string} branch - New branch name
+   * @returns {Promise<string[]>} Paths of deleted non-pool worktree records (for filesystem cleanup)
+   */
+  async switchPR(id, prNumber, branch) {
+    const now = new Date().toISOString();
+    let deletedPaths = [];
+    // Look up this worktree's repository so we can check for conflicts
+    const self = await queryOne(this.db, `SELECT repository FROM worktrees WHERE id = ?`, [id]);
+    if (self && self.repository) {
+      // Wrap SELECT + DELETE + UPDATE in a transaction to avoid partial state
+      await run(this.db, 'BEGIN IMMEDIATE');
+      try {
+        // Collect paths of conflicting non-pool worktree records before deleting
+        // (the caller needs these to clean up the actual git worktree directories on disk)
+        const conflicting = this.db.prepare(`
+          SELECT path FROM worktrees
+          WHERE pr_number = ? AND repository = ? COLLATE NOCASE AND id != ?
+            AND id NOT IN (SELECT id FROM worktree_pool)
+        `).all(prNumber, self.repository, id);
+        deletedPaths = conflicting.map(row => row.path).filter(Boolean);
+
+        // Remove any conflicting non-pool worktree record for the target PR
+        // (can exist when transitioning a repo from non-pool to pool mode)
+        await run(this.db, `
+          DELETE FROM worktrees
+          WHERE pr_number = ? AND repository = ? COLLATE NOCASE AND id != ?
+            AND id NOT IN (SELECT id FROM worktree_pool)
+        `, [prNumber, self.repository, id]);
+        await run(this.db, `UPDATE worktrees SET pr_number = ?, branch = ?, last_accessed_at = ? WHERE id = ?`, [prNumber, branch, now, id]);
+        await run(this.db, 'COMMIT');
+      } catch (err) {
+        await run(this.db, 'ROLLBACK');
+        throw err;
+      }
+    } else {
+      await run(this.db, `UPDATE worktrees SET pr_number = ?, branch = ?, last_accessed_at = ? WHERE id = ?`, [prNumber, branch, now, id]);
+    }
+    return deletedPaths;
+  }
+
+
+  /**
+   * Find a worktree record by its filesystem path.
+   * @param {string} worktreePath - Absolute path to the worktree
+   * @returns {Promise<Object|null>} Worktree record or null
+   */
+  async findByPath(worktreePath) {
+    return queryOne(this.db, `SELECT * FROM worktrees WHERE path = ?`, [worktreePath]);
+  }
+
   /**
    * Count total worktrees in the database
    * @returns {Promise<number>} Total count
@@ -2115,6 +2455,333 @@ class WorktreeRepository {
   }
 }
 
+/**
+ * WorktreePoolRepository class for managing pool worktree database records
+ */
+class WorktreePoolRepository {
+  constructor(db) {
+    this.db = db;
+  }
+
+  /**
+   * Create a pool entry for a worktree.
+   * @param {object} params
+   * @param {string} params.id - Pool worktree ID (e.g., 'pool-abc')
+   * @param {string} params.repository - owner/repo
+   * @param {string} params.path - Absolute filesystem path
+   * @param {number} [params.prNumber] - If provided, insert as 'in_use' for this PR (avoids race with claimAvailable)
+   */
+  async create({ id, repository, path, prNumber }) {
+    const now = new Date().toISOString();
+    if (prNumber != null) {
+      await run(this.db, `INSERT INTO worktree_pool (id, repository, path, status, current_pr_number, last_switched_at, created_at) VALUES (?, ?, ?, 'in_use', ?, ?, ?)`, [id, repository, path, prNumber, now, now]);
+    } else {
+      await run(this.db, `INSERT INTO worktree_pool (id, repository, path, status, created_at) VALUES (?, ?, ?, 'available', ?)`, [id, repository, path, now]);
+    }
+  }
+
+  /**
+   * Find an available (evictable) pool worktree for a repository,
+   * ordered by LRU (oldest last_switched_at first, NULLs first).
+   */
+  async findAvailable(repository) {
+    return await queryOne(this.db, `
+      SELECT id, repository, path, status, current_pr_number, last_switched_at, last_fetched_at, created_at
+      FROM worktree_pool
+      WHERE repository = ? COLLATE NOCASE AND status = 'available'
+      ORDER BY last_switched_at ASC NULLS FIRST
+      LIMIT 1
+    `, [repository]);
+  }
+
+  /**
+   * Find a pool worktree currently assigned to a PR.
+   */
+  async findByPR(prNumber, repository) {
+    return await queryOne(this.db, `
+      SELECT id, repository, path, status, current_pr_number, last_switched_at, last_fetched_at, created_at
+      FROM worktree_pool
+      WHERE current_pr_number = ? AND repository = ? COLLATE NOCASE
+    `, [prNumber, repository]);
+  }
+
+  /**
+   * Count pool worktrees for a repository.
+   */
+  async countForRepo(repository) {
+    const row = await queryOne(this.db, `SELECT COUNT(*) as count FROM worktree_pool WHERE repository = ? COLLATE NOCASE`, [repository]);
+    return row ? row.count : 0;
+  }
+
+  /**
+   * Find worktrees for a repository that are NOT in the pool.
+   * Joins reviews to get the review ID in one query (avoids N+1).
+   *
+   * @param {string} repository - Repository in "owner/repo" format
+   * @returns {Promise<Array<{id: string, path: string, pr_number: number, repository: string, reviewId: number|null}>>}
+   */
+  async findOrphanWorktrees(repository) {
+    return await query(this.db, `
+      SELECT w.id, w.path, w.pr_number, w.repository,
+             r.id AS reviewId
+      FROM worktrees w
+      LEFT JOIN worktree_pool wp ON w.id = wp.id
+      LEFT JOIN reviews r ON r.pr_number = w.pr_number AND r.repository = w.repository COLLATE NOCASE
+      WHERE w.repository = ? COLLATE NOCASE AND wp.id IS NULL
+    `, [repository]);
+  }
+
+  /**
+   * Mark a pool worktree as in_use.
+   */
+  async markInUse(id, prNumber) {
+    const now = new Date().toISOString();
+    await run(this.db, `UPDATE worktree_pool SET status = 'in_use', current_pr_number = ?, last_switched_at = ?, current_review_id = NULL WHERE id = ?`, [prNumber, now, id]);
+  }
+
+  /**
+   * Mark a pool worktree as available (evictable).
+   * Clears current_review_id to release ownership.
+   */
+  async markAvailable(id) {
+    await run(this.db, `UPDATE worktree_pool SET status = 'available', current_review_id = NULL WHERE id = ?`, [id]);
+  }
+
+  /**
+   * Mark a pool worktree as switching (transitional state during PR switch).
+   */
+  async markSwitching(id) {
+    await run(this.db, `UPDATE worktree_pool SET status = 'switching' WHERE id = ?`, [id]);
+  }
+
+  /**
+   * Update last_fetched_at timestamp.
+   */
+  async updateLastFetched(id) {
+    const now = new Date().toISOString();
+    await run(this.db, `UPDATE worktree_pool SET last_fetched_at = ? WHERE id = ?`, [now, id]);
+  }
+
+  /**
+   * Find idle pool worktrees for a repository (status = 'available').
+   */
+  async findIdleForRepo(repository) {
+    return await query(this.db, `
+      SELECT id, repository, path, status, current_pr_number, last_switched_at, last_fetched_at, created_at
+      FROM worktree_pool
+      WHERE repository = ? COLLATE NOCASE AND status = 'available'
+      ORDER BY last_switched_at ASC NULLS FIRST
+    `, [repository]);
+  }
+
+  /**
+   * Find all pool worktrees for a repository.
+   */
+  async findAllForRepo(repository) {
+    return await query(this.db, `
+      SELECT id, repository, path, status, current_pr_number, last_switched_at, last_fetched_at, created_at
+      FROM worktree_pool
+      WHERE repository = ? COLLATE NOCASE
+    `, [repository]);
+  }
+
+  /**
+   * Find all pool worktrees for background fetch (excludes 'switching' status).
+   * Ordered by last_fetched_at ASC NULLS FIRST (coldest first).
+   */
+  async findAllForFetch(repository) {
+    return await query(this.db, `
+      SELECT id, path, last_fetched_at, status
+      FROM worktree_pool
+      WHERE repository = ? COLLATE NOCASE AND status != 'switching'
+      ORDER BY last_fetched_at ASC NULLS FIRST
+    `, [repository]);
+  }
+
+  /**
+   * Check if a worktree ID belongs to the pool.
+   */
+  async isPoolWorktree(id) {
+    const row = await queryOne(this.db, `SELECT id FROM worktree_pool WHERE id = ?`, [id]);
+    return !!row;
+  }
+
+  /**
+   * Get a pool entry by worktree ID, returning the full row including status.
+   * @param {string} id - Pool worktree ID
+   * @returns {Promise<Object|undefined>} Pool entry or undefined if not found
+   */
+  async getPoolEntry(id) {
+    return await queryOne(this.db, `
+      SELECT id, repository, path, status, current_pr_number, last_switched_at, last_fetched_at, created_at
+      FROM worktree_pool WHERE id = ?
+    `, [id]);
+  }
+
+  /**
+   * Delete a pool entry.
+   */
+  async delete(id) {
+    await run(this.db, `DELETE FROM worktree_pool WHERE id = ?`, [id]);
+  }
+
+  /**
+   * Find a pool worktree currently assigned to a review.
+   * @param {number} reviewId - The review ID
+   * @returns {Promise<{id: string}|undefined>} Pool entry with worktree ID, or undefined
+   */
+  async findByReviewId(reviewId) {
+    return await queryOne(this.db, `SELECT id FROM worktree_pool WHERE current_review_id = ? AND status = 'in_use'`, [reviewId]);
+  }
+
+  /**
+   * Set the current review ID for a pool worktree (persistent ownership).
+   * @param {string} id - Pool worktree ID
+   * @param {number|null} reviewId - Review ID that owns the worktree
+   */
+  async setCurrentReviewId(id, reviewId) {
+    await run(this.db, `UPDATE worktree_pool SET current_review_id = ? WHERE id = ?`, [reviewId, id]);
+  }
+
+  /**
+   * Atomically reserve a new pool slot if capacity allows.
+   * Uses BEGIN IMMEDIATE to serialize against concurrent callers, preventing
+   * two requests from both observing spare capacity and both creating slots.
+   *
+   * Inserts a placeholder row with status 'creating'. The caller must:
+   * - On success: call markInUse() to transition to 'in_use'
+   * - On failure: call deleteReservation() to remove the placeholder
+   *
+   * @param {string} id - Pool worktree ID (e.g., 'pool-abc')
+   * @param {string} repository - Repository in "owner/repo" format
+   * @param {number} poolSize - Maximum pool slots for this repository
+   * @returns {Promise<boolean>} true if the slot was reserved, false if at capacity
+   */
+  async reserveSlot(id, repository, poolSize) {
+    const reserveTx = this.db.transaction(() => {
+      const row = this.db.prepare(
+        `SELECT COUNT(*) as count FROM worktree_pool WHERE repository = ? COLLATE NOCASE`
+      ).get(repository);
+      const currentCount = row ? row.count : 0;
+      if (currentCount >= poolSize) {
+        return false;
+      }
+      const now = new Date().toISOString();
+      // Use a unique placeholder path to satisfy the UNIQUE constraint.
+      // finalizeReservation will replace it with the real path.
+      const placeholderPath = `__creating__${id}`;
+      this.db.prepare(
+        `INSERT INTO worktree_pool (id, repository, path, status, created_at) VALUES (?, ?, ?, 'creating', ?)`
+      ).run(id, repository, placeholderPath, now);
+      return true;
+    });
+    return reserveTx.immediate();
+  }
+
+  /**
+   * Finalize a reserved pool slot after successful worktree creation.
+   * Updates the placeholder row with the actual path and marks it in_use.
+   *
+   * @param {string} id - Pool worktree ID
+   * @param {string} path - Absolute filesystem path to the created worktree
+   * @param {number} prNumber - PR number to assign
+   */
+  async finalizeReservation(id, path, prNumber) {
+    const now = new Date().toISOString();
+    await run(this.db, `UPDATE worktree_pool SET path = ?, status = 'in_use', current_pr_number = ?, last_switched_at = ? WHERE id = ? AND status = 'creating'`, [path, prNumber, now, id]);
+  }
+
+  /**
+   * Delete a reserved pool slot placeholder (cleanup on creation failure).
+   *
+   * @param {string} id - Pool worktree ID to remove
+   */
+  async deleteReservation(id) {
+    await run(this.db, `DELETE FROM worktree_pool WHERE id = ? AND status = 'creating'`, [id]);
+  }
+
+  /**
+   * Atomically find and claim a pool worktree already assigned to a PR.
+   * Uses BEGIN IMMEDIATE to serialize against concurrent callers.
+   *
+   * @param {number} prNumber - PR number to find
+   * @param {string} repository - Repository in "owner/repo" format
+   * @returns {Promise<Object|null>} Claimed pool entry or null if not found
+   */
+  async claimByPR(prNumber, repository) {
+    const claimTx = this.db.transaction(() => {
+      const entry = this.db.prepare(`
+        SELECT id, repository, path, status, current_pr_number, last_switched_at, last_fetched_at, created_at
+        FROM worktree_pool
+        WHERE current_pr_number = ? AND repository = ? COLLATE NOCASE
+          AND status IN ('in_use', 'available')
+      `).get(prNumber, repository);
+      if (entry) {
+        const now = new Date().toISOString();
+        this.db.prepare(
+          `UPDATE worktree_pool SET status = 'in_use', current_pr_number = ?, last_switched_at = ?, current_review_id = NULL WHERE id = ?`
+        ).run(prNumber, now, entry.id);
+      }
+      return entry || null;
+    });
+    return claimTx.immediate();
+  }
+
+  /**
+   * Atomically find and claim the LRU available pool worktree for a repository.
+   * Uses BEGIN IMMEDIATE to serialize against concurrent callers.
+   * Marks the claimed entry as 'switching' so no other caller can grab it.
+   *
+   * @param {string} repository - Repository in "owner/repo" format
+   * @returns {Promise<Object|null>} Claimed pool entry or null if none available
+   */
+  async claimAvailable(repository) {
+    const claimTx = this.db.transaction(() => {
+      const entry = this.db.prepare(`
+        SELECT id, repository, path, status, current_pr_number, last_switched_at, last_fetched_at, created_at
+        FROM worktree_pool
+        WHERE repository = ? COLLATE NOCASE AND status = 'available'
+        ORDER BY last_switched_at ASC NULLS FIRST
+        LIMIT 1
+      `).get(repository);
+      if (entry) {
+        this.db.prepare(
+          `UPDATE worktree_pool SET status = 'switching' WHERE id = ?`
+        ).run(entry.id);
+      }
+      return entry || null;
+    });
+    return claimTx.immediate();
+  }
+
+  /**
+   * Reset stale pool entries on startup while preserving valid ownership.
+   * Entries are considered stale if: no review owner, interrupted switching,
+   * or the owning review has been deleted.
+   * @returns {Array<{id: string, current_review_id: number}>} Preserved entries for in-memory rehydration
+   */
+  async resetStaleAndPreserve() {
+    // Delete placeholder entries that were mid-creation when the server stopped.
+    // These have no valid path or worktree on disk — they cannot be recovered.
+    await run(this.db, `DELETE FROM worktree_pool WHERE status = 'creating'`);
+
+    // Reset entries that are stale: no review owner, interrupted switching, or review deleted
+    await run(this.db, `
+      UPDATE worktree_pool SET status = 'available', current_review_id = NULL
+      WHERE status != 'available' AND (
+        current_review_id IS NULL
+        OR status = 'switching'
+        OR current_review_id NOT IN (SELECT id FROM reviews)
+      )
+    `);
+    // Return preserved entries for in-memory rehydration
+    return await query(this.db, `
+      SELECT id, current_review_id FROM worktree_pool
+      WHERE status = 'in_use' AND current_review_id IS NOT NULL
+    `);
+  }
+}
+
 /**
  * RepoSettingsRepository class for managing per-repository AI settings
  */
@@ -2134,9 +2801,9 @@ class RepoSettingsRepository {
    */
   async getRepoSettings(repository) {
     const row = await queryOne(this.db, `
-      SELECT id, repository, default_instructions, default_provider, default_model, default_council_id, default_tab, default_chat_instructions, local_path, auto_branch_review, created_at, updated_at
+      SELECT id, repository, default_instructions, default_provider, default_model, default_council_id, default_tab, default_chat_instructions, local_path, auto_branch_review, pool_size, pool_fetch_interval_minutes, load_skills, created_at, updated_at
       FROM repo_settings
-      WHERE repository = ? COLLATE NOCASE
+      WHERE repository = ?
     `, [repository]);
 
     return row || null;
@@ -2149,7 +2816,7 @@ class RepoSettingsRepository {
    */
   async getLocalPath(repository) {
     const row = await queryOne(this.db, `
-      SELECT local_path FROM repo_settings WHERE repository = ? COLLATE NOCASE
+      SELECT local_path FROM repo_settings WHERE repository = ?
     `, [repository]);
 
     return row ? row.local_path : null;
@@ -2173,7 +2840,7 @@ class RepoSettingsRepository {
       await run(this.db, `
         UPDATE repo_settings
         SET local_path = ?, updated_at = ?
-        WHERE repository = ? COLLATE NOCASE
+        WHERE repository = ?
       `, [localPath, now, repository]);
     } else {
       // Insert new settings with just local_path
@@ -2191,7 +2858,7 @@ class RepoSettingsRepository {
    * @returns {Promise<Object>} Saved settings object
    */
   async saveRepoSettings(repository, settings) {
-    const { default_instructions, default_provider, default_model, default_council_id, default_tab, default_chat_instructions, local_path } = settings;
+    const { default_instructions, default_provider, default_model, default_council_id, default_tab, default_chat_instructions, local_path, pool_size, pool_fetch_interval_minutes, load_skills } = settings;
     const now = new Date().toISOString();
 
     // Check if settings already exist
@@ -2208,8 +2875,11 @@ class RepoSettingsRepository {
             default_tab = ?,
             default_chat_instructions = ?,
             local_path = ?,
+            pool_size = ?,
+            pool_fetch_interval_minutes = ?,
+            load_skills = ?,
             updated_at = ?
-        WHERE repository = ? COLLATE NOCASE
+        WHERE repository = ?
       `, [
         default_instructions !== undefined ? default_instructions : existing.default_instructions,
         default_provider !== undefined ? default_provider : existing.default_provider,
@@ -2218,6 +2888,9 @@ class RepoSettingsRepository {
         default_tab !== undefined ? default_tab : existing.default_tab,
         default_chat_instructions !== undefined ? default_chat_instructions : existing.default_chat_instructions,
         local_path !== undefined ? local_path : existing.local_path,
+        pool_size !== undefined ? pool_size : existing.pool_size,
+        pool_fetch_interval_minutes !== undefined ? pool_fetch_interval_minutes : existing.pool_fetch_interval_minutes,
+        load_skills !== undefined ? load_skills : existing.load_skills,
         now,
         repository
       ]);
@@ -2231,14 +2904,17 @@ class RepoSettingsRepository {
         default_tab: default_tab !== undefined ? default_tab : existing.default_tab,
         default_chat_instructions: default_chat_instructions !== undefined ? default_chat_instructions : existing.default_chat_instructions,
         local_path: local_path !== undefined ? local_path : existing.local_path,
+        pool_size: pool_size !== undefined ? pool_size : existing.pool_size,
+        pool_fetch_interval_minutes: pool_fetch_interval_minutes !== undefined ? pool_fetch_interval_minutes : existing.pool_fetch_interval_minutes,
+        load_skills: load_skills !== undefined ? load_skills : existing.load_skills,
         updated_at: now
       };
     } else {
       // Insert new settings
       const result = await run(this.db, `
-        INSERT INTO repo_settings (repository, default_instructions, default_provider, default_model, default_council_id, default_tab, default_chat_instructions, local_path, created_at, updated_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `, [repository, default_instructions || null, default_provider || null, default_model || null, default_council_id || null, default_tab || null, default_chat_instructions || null, local_path || null, now, now]);
+        INSERT INTO repo_settings (repository, default_instructions, default_provider, default_model, default_council_id, default_tab, default_chat_instructions, local_path, pool_size, pool_fetch_interval_minutes, load_skills, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `, [repository, default_instructions || null, default_provider || null, default_model || null, default_council_id || null, default_tab || null, default_chat_instructions || null, local_path || null, pool_size ?? null, pool_fetch_interval_minutes ?? null, load_skills ?? null, now, now]);
 
       return {
         id: result.lastID,
@@ -2250,12 +2926,61 @@ class RepoSettingsRepository {
         default_tab: default_tab || null,
         default_chat_instructions: default_chat_instructions || null,
         local_path: local_path || null,
+        pool_size: pool_size ?? null,
+        pool_fetch_interval_minutes: pool_fetch_interval_minutes ?? null,
+        load_skills: load_skills ?? null,
         created_at: now,
         updated_at: now
       };
     }
   }
 
+  /**
+   * Atomically attempt to claim the background fetch lease for a repository.
+   * Uses SQLite UPSERT with a conditional WHERE clause to avoid TOCTOU races
+   * between instances sharing the same database. Creates a repo_settings row
+   * if one doesn't exist yet (config-only repos).
+   * @param {string} repository - Repository in owner/repo format
+   * @param {number} [staleGuardMs=600000] - Consider a fetch stale after this many ms (default 10 min)
+   * @returns {Promise<boolean>} true if the lease was successfully claimed
+   */
+  async tryClaimFetch(repository, staleGuardMs = 600000) {
+    const now = new Date().toISOString();
+    const staleThreshold = new Date(Date.now() - staleGuardMs).toISOString();
+    const result = await run(this.db,
+      `INSERT INTO repo_settings (repository, pool_fetch_started_at, created_at, updated_at)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(repository) DO UPDATE SET pool_fetch_started_at = excluded.pool_fetch_started_at,
+         pool_fetch_finished_at = NULL
+       WHERE pool_fetch_started_at IS NULL
+         OR pool_fetch_finished_at >= pool_fetch_started_at
+         OR pool_fetch_started_at < ?`,
+      [repository, now, now, now, staleThreshold]
+    );
+    return result.changes > 0;
+  }
+
+  /**
+   * Refresh the fetch lease timestamp for a repository.
+   * Called after each successful worktree fetch to extend the stale guard window
+   * so the 10-minute default only needs to outlive a single stalled fetch rather
+   * than the entire serial loop across all worktrees.
+   * @param {string} repository - Repository in owner/repo format
+   */
+  async refreshFetchLease(repository) {
+    const now = new Date().toISOString();
+    await run(this.db, `UPDATE repo_settings SET pool_fetch_started_at = ? WHERE repository = ?`, [now, repository]);
+  }
+
+  /**
+   * Mark a repo-level background fetch as finished.
+   * @param {string} repository - Repository in owner/repo format
+   */
+  async markFetchFinished(repository) {
+    const now = new Date().toISOString();
+    await run(this.db, `UPDATE repo_settings SET pool_fetch_finished_at = ? WHERE repository = ?`, [now, repository]);
+  }
+
   /**
    * Delete settings for a repository
    * @param {string} repository - Repository in owner/repo format
@@ -2263,7 +2988,7 @@ class RepoSettingsRepository {
    */
   async deleteRepoSettings(repository) {
     const result = await run(this.db, `
-      DELETE FROM repo_settings WHERE repository = ? COLLATE NOCASE
+      DELETE FROM repo_settings WHERE repository = ?
     `, [repository]);
 
     return result.changes > 0;
@@ -4234,6 +4959,7 @@ module.exports = {
   CURRENT_SCHEMA_VERSION,
   getDbPath,
   WorktreeRepository,
+  WorktreePoolRepository,
   RepoSettingsRepository,
   ReviewRepository,
   CommentRepository,
@@ -4243,5 +4969,7 @@ module.exports = {
   CouncilRepository,
   ContextFileRepository,
   generateWorktreeId,
-  migrateExistingWorktrees
+  migrateExistingWorktrees,
+  // Exported for testing only
+  _MIGRATIONS: MIGRATIONS
 };