@in-the-loop-labs/pair-review 2.6.3 → 2.7.0

package/src/database.js

@@ -20,7 +20,7 @@ function getDbPath() {
 /**
  * Current schema version - increment this when adding new migrations
  */
-const CURRENT_SCHEMA_VERSION = 27;
+const CURRENT_SCHEMA_VERSION = 33;
 
 /**
  * Database schema SQL statements
@@ -42,7 +42,12 @@ const SCHEMA_SQL = {
       local_path TEXT,
       local_head_sha TEXT,
       summary TEXT,
-      name TEXT
+      name TEXT,
+      local_mode TEXT DEFAULT 'uncommitted',
+      local_base_branch TEXT,
+      local_head_branch TEXT,
+      local_scope_start TEXT DEFAULT 'unstaged',
+      local_scope_end TEXT DEFAULT 'untracked'
     )
   `,
 
@@ -94,6 +99,7 @@ const SCHEMA_SQL = {
       created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
       updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
 
+      FOREIGN KEY (review_id) REFERENCES reviews(id) ON DELETE CASCADE,
       FOREIGN KEY (adopted_as_id) REFERENCES comments(id),
       FOREIGN KEY (parent_id) REFERENCES comments(id)
     )
@@ -113,6 +119,7 @@ const SCHEMA_SQL = {
       updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
       pr_data TEXT,
       last_ai_run_id TEXT,
+      last_accessed_at TEXT,
       UNIQUE(pr_number, repository)
     )
   `,
@@ -141,6 +148,7 @@ const SCHEMA_SQL = {
       default_tab TEXT,
       default_chat_instructions TEXT,
       local_path TEXT,
+      auto_branch_review INTEGER DEFAULT 0,
       created_at TEXT DEFAULT CURRENT_TIMESTAMP,
       updated_at TEXT DEFAULT CURRENT_TIMESTAMP
     )
@@ -167,6 +175,8 @@ const SCHEMA_SQL = {
       parent_run_id TEXT,
       config_type TEXT DEFAULT 'single',
       levels_config TEXT,
+      scope_start TEXT,
+      scope_end TEXT,
       FOREIGN KEY (review_id) REFERENCES reviews(id) ON DELETE CASCADE
     )
   `,
@@ -220,8 +230,8 @@ const SCHEMA_SQL = {
       status TEXT DEFAULT 'active' CHECK(status IN ('active', 'closed', 'error')),
       created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
       updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-      FOREIGN KEY (review_id) REFERENCES reviews(id),
-      FOREIGN KEY (context_comment_id) REFERENCES comments(id)
+      FOREIGN KEY (review_id) REFERENCES reviews(id) ON DELETE CASCADE,
+      FOREIGN KEY (context_comment_id) REFERENCES comments(id) ON DELETE SET NULL
     )
   `,
 
@@ -277,10 +287,11 @@ const INDEX_SQL = [
   'CREATE INDEX IF NOT EXISTS idx_comments_status ON comments(status)',
   'CREATE INDEX IF NOT EXISTS idx_comments_file_level ON comments(review_id, file, is_file_level)',
   'CREATE UNIQUE INDEX IF NOT EXISTS idx_pr_metadata_unique ON pr_metadata(pr_number, repository)',
+  '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_reviews_local ON reviews(local_path, local_head_sha) WHERE review_type = \'local\'',
+  '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\'',
   // Analysis runs indexes
@@ -1230,6 +1241,329 @@ const MIGRATIONS = {
     }
 
     console.log('Migration to schema version 27 complete');
+  },
+
+  28: (db) => {
+    console.log('Migrating to schema version 28: Add branch review columns');
+
+    // Add local_mode to reviews
+    if (!columnExists(db, 'reviews', 'local_mode')) {
+      try {
+        db.prepare("ALTER TABLE reviews ADD COLUMN local_mode TEXT DEFAULT 'uncommitted'").run();
+        console.log('  Added local_mode column to reviews');
+      } catch (error) {
+        if (!error.message.includes('duplicate column name')) throw error;
+        console.log('  Column local_mode already exists (race condition)');
+      }
+    } else {
+      console.log('  Column local_mode already exists');
+    }
+
+    // Add local_base_branch to reviews
+    if (!columnExists(db, 'reviews', 'local_base_branch')) {
+      try {
+        db.prepare('ALTER TABLE reviews ADD COLUMN local_base_branch TEXT').run();
+        console.log('  Added local_base_branch column to reviews');
+      } catch (error) {
+        if (!error.message.includes('duplicate column name')) throw error;
+        console.log('  Column local_base_branch already exists (race condition)');
+      }
+    } else {
+      console.log('  Column local_base_branch already exists');
+    }
+
+    // Add auto_branch_review to repo_settings
+    if (!columnExists(db, 'repo_settings', 'auto_branch_review')) {
+      try {
+        db.prepare('ALTER TABLE repo_settings ADD COLUMN auto_branch_review INTEGER DEFAULT 0').run();
+        console.log('  Added auto_branch_review column to repo_settings');
+      } catch (error) {
+        if (!error.message.includes('duplicate column name')) throw error;
+        console.log('  Column auto_branch_review already exists (race condition)');
+      }
+    } else {
+      console.log('  Column auto_branch_review already exists');
+    }
+
+    console.log('Migration to schema version 28 complete');
+  },
+
+  // Migration to version 29: adds scope columns for flexible diff range selection
+  29: (db) => {
+    console.log('Migrating to schema version 29: Add scope columns to reviews and analysis_runs');
+
+    // Add local_scope_start to reviews
+    if (!columnExists(db, 'reviews', 'local_scope_start')) {
+      try {
+        db.prepare("ALTER TABLE reviews ADD COLUMN local_scope_start TEXT DEFAULT 'unstaged'").run();
+        console.log('  Added local_scope_start column to reviews');
+      } catch (error) {
+        if (!error.message.includes('duplicate column name')) throw error;
+        console.log('  Column local_scope_start already exists (race condition)');
+      }
+    } else {
+      console.log('  Column local_scope_start already exists');
+    }
+
+    // Add local_scope_end to reviews
+    if (!columnExists(db, 'reviews', 'local_scope_end')) {
+      try {
+        db.prepare("ALTER TABLE reviews ADD COLUMN local_scope_end TEXT DEFAULT 'untracked'").run();
+        console.log('  Added local_scope_end column to reviews');
+      } catch (error) {
+        if (!error.message.includes('duplicate column name')) throw error;
+        console.log('  Column local_scope_end already exists (race condition)');
+      }
+    } else {
+      console.log('  Column local_scope_end already exists');
+    }
+
+    // Migrate existing data from local_mode to new scope columns
+    // uncommitted → start='unstaged', end='untracked'
+    db.prepare(`
+      UPDATE reviews SET local_scope_start = 'unstaged', local_scope_end = 'untracked'
+      WHERE local_mode = 'uncommitted' OR local_mode IS NULL
+    `).run();
+    console.log('  Migrated uncommitted reviews to scope columns');
+
+    // branch → start='branch', end='branch'
+    db.prepare(`
+      UPDATE reviews SET local_scope_start = 'branch', local_scope_end = 'branch'
+      WHERE local_mode = 'branch'
+    `).run();
+    console.log('  Migrated branch reviews to scope columns');
+
+    // Add scope_start to analysis_runs
+    if (!columnExists(db, 'analysis_runs', 'scope_start')) {
+      try {
+        db.prepare('ALTER TABLE analysis_runs ADD COLUMN scope_start TEXT').run();
+        console.log('  Added scope_start column to analysis_runs');
+      } catch (error) {
+        if (!error.message.includes('duplicate column name')) throw error;
+        console.log('  Column scope_start already exists (race condition)');
+      }
+    } else {
+      console.log('  Column scope_start already exists');
+    }
+
+    // Add scope_end to analysis_runs
+    if (!columnExists(db, 'analysis_runs', 'scope_end')) {
+      try {
+        db.prepare('ALTER TABLE analysis_runs ADD COLUMN scope_end TEXT').run();
+        console.log('  Added scope_end column to analysis_runs');
+      } catch (error) {
+        if (!error.message.includes('duplicate column name')) throw error;
+        console.log('  Column scope_end already exists (race condition)');
+      }
+    } else {
+      console.log('  Column scope_end already exists');
+    }
+
+    console.log('Migration to schema version 29 complete');
+  },
+
+  // Migration to version 30: adds head branch tracking for branch-aware session identity
+  30: (db) => {
+    console.log('Migrating to schema version 30: Add local_head_branch to reviews');
+
+    if (!columnExists(db, 'reviews', 'local_head_branch')) {
+      try {
+        db.prepare('ALTER TABLE reviews ADD COLUMN local_head_branch TEXT').run();
+        console.log('  Added local_head_branch column to reviews');
+      } catch (error) {
+        if (!error.message.includes('duplicate column name')) throw error;
+        console.log('  Column local_head_branch already exists (race condition)');
+      }
+    } else {
+      console.log('  Column local_head_branch already exists');
+    }
+
+    // Recreate unique index to include local_head_branch in session identity
+    db.prepare('DROP INDEX IF EXISTS idx_reviews_local').run();
+    db.prepare("CREATE UNIQUE INDEX IF NOT EXISTS idx_reviews_local ON reviews(local_path, local_head_sha, local_head_branch) WHERE review_type = 'local'").run();
+    console.log('  Recreated idx_reviews_local with local_head_branch');
+
+    console.log('Migration to schema version 30 complete');
+  },
+
+  // Migration to version 31: Add last_accessed_at to pr_metadata and backfill from worktrees
+  31: (db) => {
+    console.log('Migrating to schema version 31: Add last_accessed_at to pr_metadata');
+
+    const hasCol = columnExists(db, 'pr_metadata', 'last_accessed_at');
+    if (!hasCol) {
+      try {
+        db.prepare('ALTER TABLE pr_metadata ADD COLUMN last_accessed_at TEXT').run();
+        console.log('  Added last_accessed_at column to pr_metadata');
+      } catch (error) {
+        if (!error.message.includes('duplicate column name')) {
+          throw error;
+        }
+        console.log('  Column last_accessed_at already exists (race condition)');
+      }
+    } else {
+      console.log('  Column last_accessed_at already exists');
+    }
+
+    // Backfill from worktrees table (best available access timestamp)
+    const backfilled = db.prepare(`
+      UPDATE pr_metadata
+      SET last_accessed_at = (
+        SELECT MAX(w.last_accessed_at) FROM worktrees w
+        WHERE w.pr_number = pr_metadata.pr_number
+          AND w.repository = pr_metadata.repository COLLATE NOCASE
+      )
+      WHERE last_accessed_at IS NULL
+    `).run();
+    console.log(`  Backfilled ${backfilled.changes} pr_metadata rows from worktrees`);
+
+    // For any remaining rows without a worktree, use updated_at as fallback
+    const fallback = db.prepare(`
+      UPDATE pr_metadata
+      SET last_accessed_at = updated_at
+      WHERE last_accessed_at IS NULL
+    `).run();
+    if (fallback.changes > 0) {
+      console.log(`  Used updated_at fallback for ${fallback.changes} pr_metadata rows`);
+    }
+
+    console.log('Migration to schema version 31 complete');
+  },
+
+  // Migration to version 32: Add ON DELETE CASCADE/SET NULL to chat_sessions FKs
+  // SQLite doesn't support ALTER CONSTRAINT, so we recreate the table.
+  32: (db) => {
+    console.log('Migrating to schema version 32: Add cascade deletes to chat_sessions FKs');
+
+    if (!tableExists(db, 'chat_sessions')) {
+      console.log('  chat_sessions table does not exist, skipping');
+      console.log('Migration to schema version 32 complete');
+      return;
+    }
+
+    db.prepare(`CREATE TABLE IF NOT EXISTS chat_sessions_new (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      review_id INTEGER NOT NULL,
+      context_comment_id INTEGER,
+      agent_session_id TEXT,
+      provider TEXT NOT NULL,
+      model TEXT,
+      status TEXT DEFAULT 'active' CHECK(status IN ('active', 'closed', 'error')),
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+      updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+      FOREIGN KEY (review_id) REFERENCES reviews(id) ON DELETE CASCADE,
+      FOREIGN KEY (context_comment_id) REFERENCES comments(id) ON DELETE SET NULL
+    )`).run();
+
+    db.prepare(`INSERT INTO chat_sessions_new
+      SELECT * FROM chat_sessions`).run();
+
+    db.prepare('DROP TABLE chat_sessions').run();
+    db.prepare('ALTER TABLE chat_sessions_new RENAME TO chat_sessions').run();
+
+    console.log('  Recreated chat_sessions with ON DELETE CASCADE/SET NULL');
+    console.log('Migration to schema version 32 complete');
+  },
+
+  // Migration to version 33: Add ON DELETE CASCADE to comments FK for review_id
+  // SQLite doesn't support ALTER CONSTRAINT, so we recreate the table.
+  33: (db) => {
+    console.log('Migrating to schema version 33: Add cascade delete to comments.review_id FK');
+
+    if (!tableExists(db, 'comments')) {
+      console.log('  comments table does not exist, skipping');
+      console.log('Migration to schema version 33 complete');
+      return;
+    }
+
+    // Disable FK checks for the rebuild — old databases may have orphaned
+    // comments (review_id pointing to deleted reviews) because FK enforcement
+    // wasn't always active or CASCADE wasn't defined.
+    db.pragma('foreign_keys = OFF');
+
+    // Clean up orphaned comments before rebuild
+    if (tableExists(db, 'reviews')) {
+      const orphaned = db.prepare(
+        'DELETE FROM comments WHERE review_id IS NOT NULL AND review_id NOT IN (SELECT id FROM reviews)'
+      ).run();
+      if (orphaned.changes > 0) {
+        console.log(`  Cleaned up ${orphaned.changes} orphaned comments`);
+      }
+    }
+
+    db.prepare(`CREATE TABLE IF NOT EXISTS comments_rebuild (
+      id INTEGER PRIMARY KEY,
+      review_id INTEGER,
+      source TEXT,
+      author TEXT,
+
+      ai_run_id TEXT,
+      ai_level INTEGER,
+      ai_confidence REAL,
+
+      file TEXT,
+      line_start INTEGER,
+      line_end INTEGER,
+      diff_position INTEGER,
+      side TEXT DEFAULT 'RIGHT' CHECK(side IN ('LEFT', 'RIGHT')),
+      commit_sha TEXT,
+      type TEXT,
+      title TEXT,
+      body TEXT,
+      suggestion_text TEXT,
+      reasoning TEXT,
+
+      status TEXT DEFAULT 'active' CHECK(status IN ('active', 'dismissed', 'adopted', 'submitted', 'draft', 'inactive')),
+      adopted_as_id INTEGER,
+      parent_id INTEGER,
+      is_file_level INTEGER DEFAULT 0,
+
+      voice_id TEXT,
+      is_raw INTEGER DEFAULT 0,
+
+      created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+      updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+      FOREIGN KEY (review_id) REFERENCES reviews(id) ON DELETE CASCADE,
+      FOREIGN KEY (adopted_as_id) REFERENCES comments(id),
+      FOREIGN KEY (parent_id) REFERENCES comments(id)
+    )`).run();
+
+    // Use explicit column names — SELECT * would break if column order differs
+    // (e.g., columns added via ALTER TABLE ADD COLUMN are appended to the end)
+    const cols = [
+      'id', 'review_id', 'source', 'author',
+      'ai_run_id', 'ai_level', 'ai_confidence',
+      'file', 'line_start', 'line_end', 'diff_position',
+      'side', 'commit_sha', 'type', 'title', 'body',
+      'suggestion_text', 'reasoning',
+      'status', 'adopted_as_id', 'parent_id', 'is_file_level',
+      'voice_id', 'is_raw',
+      'created_at', 'updated_at'
+    ].join(', ');
+    // Wrap in transaction so a crash between DROP and RENAME can't strand
+    // data in comments_rebuild. PRAGMA foreign_keys = OFF must stay outside
+    // the transaction (SQLite requirement).
+    const rebuild = db.transaction(() => {
+      db.prepare(`INSERT INTO comments_rebuild (${cols}) SELECT ${cols} FROM comments`).run();
+      db.prepare('DROP TABLE comments').run();
+      db.prepare('ALTER TABLE comments_rebuild RENAME TO comments').run();
+    });
+    rebuild();
+
+    // Re-enable FK checks
+    db.pragma('foreign_keys = ON');
+
+    // Recreate all indexes on the new table
+    db.prepare('CREATE INDEX IF NOT EXISTS idx_comments_review_file ON comments(review_id, file, line_start)').run();
+    db.prepare('CREATE INDEX IF NOT EXISTS idx_comments_ai_run ON comments(ai_run_id)').run();
+    db.prepare('CREATE INDEX IF NOT EXISTS idx_comments_status ON comments(status)').run();
+    db.prepare('CREATE INDEX IF NOT EXISTS idx_comments_file_level ON comments(review_id, file, is_file_level)').run();
+    db.prepare('CREATE INDEX IF NOT EXISTS idx_comments_voice ON comments(voice_id)').run();
+    db.prepare('CREATE INDEX IF NOT EXISTS idx_comments_is_raw ON comments(is_raw)').run();
+
+    console.log('  Recreated comments with ON DELETE CASCADE for review_id');
+    console.log('Migration to schema version 33 complete');
   }
 };
 
@@ -1729,7 +2063,7 @@ 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, 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, created_at, updated_at
       FROM repo_settings
       WHERE repository = ? COLLATE NOCASE
     `, [repository]);
@@ -2420,6 +2754,11 @@ class ReviewRepository {
       params.push(updates.name);
     }
 
+    if (updates.local_head_branch !== undefined) {
+      setClauses.push('local_head_branch = ?');
+      params.push(updates.local_head_branch);
+    }
+
     if (updates.submittedAt !== undefined) {
       setClauses.push('submitted_at = ?');
       const submittedAt = updates.submittedAt instanceof Date
@@ -2500,16 +2839,17 @@ class ReviewRepository {
    * @param {string} reviewInfo.repository - Repository in owner/repo format
    * @param {Object} [reviewInfo.reviewData] - Additional review data
    * @param {string} [reviewInfo.customInstructions] - Custom instructions
-   * @returns {Promise<Object>} Review record (existing or newly created)
+   * @returns {Promise<{review: Object, created: boolean}>} Tuple with review record and creation flag
    */
   async getOrCreate({ prNumber, repository, reviewData = null, customInstructions = null }) {
     const existing = await this.getReviewByPR(prNumber, repository);
 
     if (existing) {
-      return existing;
+      return { review: existing, created: false };
     }
 
-    return this.createReview({ prNumber, repository, reviewData, customInstructions });
+    const review = await this.createReview({ prNumber, repository, reviewData, customInstructions });
+    return { review, created: true };
   }
 
   /**
@@ -2572,19 +2912,6 @@ class ReviewRepository {
     }
   }
 
-  /**
-   * Delete a review record by ID
-   * @param {number} id - Review ID
-   * @returns {Promise<boolean>} True if record was deleted
-   */
-  async deleteReview(id) {
-    const result = await run(this.db, `
-      DELETE FROM reviews WHERE id = ?
-    `, [id]);
-
-    return result.changes > 0;
-  }
-
   /**
    * List reviews for a repository
    * @param {string} repository - Repository in owner/repo format
@@ -2617,42 +2944,106 @@ class ReviewRepository {
    * @param {string} context.repository - Repository identifier (can be derived from path)
    * @returns {Promise<number>} The review ID
    */
-  async upsertLocalReview({ localPath, localHeadSha, repository }) {
-    // Try to find existing local review by path and SHA
-    const existing = await this.getLocalReview(localPath, localHeadSha);
+  async upsertLocalReview({ localPath, localHeadSha, repository, scopeStart, scopeEnd, localMode, localBaseBranch, localHeadBranch }) {
+    // Try to find existing local review by path, SHA, and branch
+    const existing = await this.getLocalReview(localPath, localHeadSha, localHeadBranch);
 
     if (existing) {
-      // Update the updated_at timestamp
+      // Update the updated_at timestamp (and scope/base if provided)
+      const updates = ['updated_at = CURRENT_TIMESTAMP'];
+      const params = [];
+      if (scopeStart !== undefined) {
+        updates.push('local_scope_start = ?');
+        params.push(scopeStart);
+        // Also write local_mode for backward compat during transition
+        updates.push('local_mode = ?');
+        params.push(scopeStart === 'branch' ? 'branch' : 'uncommitted');
+      } else if (localMode !== undefined) {
+        updates.push('local_mode = ?');
+        params.push(localMode);
+      }
+      if (scopeEnd !== undefined) {
+        updates.push('local_scope_end = ?');
+        params.push(scopeEnd);
+      }
+      if (localBaseBranch !== undefined) {
+        updates.push('local_base_branch = ?');
+        params.push(localBaseBranch);
+      }
+      if (localHeadBranch !== undefined) {
+        updates.push('local_head_branch = ?');
+        params.push(localHeadBranch);
+      }
+      params.push(existing.id);
       await run(this.db, `
         UPDATE reviews
-        SET updated_at = CURRENT_TIMESTAMP
+        SET ${updates.join(', ')}
         WHERE id = ?
-      `, [existing.id]);
+      `, params);
       return existing.id;
     }
 
+    // Derive local_mode from scopeStart for backward compat
+    const effectiveMode = scopeStart === 'branch' ? 'branch' : (localMode || 'uncommitted');
+    const effectiveScopeStart = scopeStart || 'unstaged';
+    const effectiveScopeEnd = scopeEnd || 'untracked';
+
     // Create new local review
     const result = await run(this.db, `
-      INSERT INTO reviews (pr_number, repository, status, review_type, local_path, local_head_sha)
-      VALUES (NULL, ?, 'draft', 'local', ?, ?)
-    `, [repository, localPath, localHeadSha]);
+      INSERT INTO reviews (pr_number, repository, status, review_type, local_path, local_head_sha, local_mode, local_base_branch, local_head_branch, local_scope_start, local_scope_end)
+      VALUES (NULL, ?, 'draft', 'local', ?, ?, ?, ?, ?, ?, ?)
+    `, [repository, localPath, localHeadSha, effectiveMode, localBaseBranch || null, localHeadBranch || null, effectiveScopeStart, effectiveScopeEnd]);
 
     return result.lastID;
   }
 
   /**
-   * Get a local review by path and HEAD SHA
+   * Get a local review by path, HEAD SHA, and branch.
    * @param {string} localPath - Absolute path to the local repository
    * @param {string} localHeadSha - Current HEAD SHA of the repository
+   * @param {string} [headBranch] - Branch name; when falsy, matches only NULL-branch sessions
    * @returns {Promise<Object|null>} Review record or null if not found
    */
-  async getLocalReview(localPath, localHeadSha) {
+  async getLocalReview(localPath, localHeadSha, headBranch) {
+    const branchClause = headBranch
+      ? 'AND local_head_branch = ?'
+      : 'AND local_head_branch IS NULL';
+    const params = [localPath, localHeadSha];
+    if (headBranch) params.push(headBranch);
     const row = await queryOne(this.db, `
       SELECT id, pr_number, repository, status, review_id,
              created_at, updated_at, submitted_at, review_data, custom_instructions,
-             review_type, local_path, local_head_sha, summary, name
+             review_type, local_path, local_head_sha, summary, name,
+             local_mode, local_base_branch, local_head_branch, local_scope_start, local_scope_end
+      FROM reviews
+      WHERE review_type = 'local' AND local_path = ? AND local_head_sha = ? ${branchClause}
+    `, params);
+
+    if (!row) return null;
+
+    return {
+      ...row,
+      review_data: row.review_data ? JSON.parse(row.review_data) : null
+    };
+  }
+
+  /**
+   * Get a local review by path and HEAD SHA only (ignoring branch).
+   * Used by external callers (MCP, analysis results) that may not have branch context.
+   * @param {string} localPath - Absolute path to the local repository
+   * @param {string} localHeadSha - Current HEAD SHA of the repository
+   * @returns {Promise<Object|null>} Review record or null if not found
+   */
+  async getLocalReviewByPathAndSha(localPath, localHeadSha) {
+    const row = await queryOne(this.db, `
+      SELECT id, pr_number, repository, status, review_id,
+             created_at, updated_at, submitted_at, review_data, custom_instructions,
+             review_type, local_path, local_head_sha, summary, name,
+             local_mode, local_base_branch, local_head_branch, local_scope_start, local_scope_end
       FROM reviews
       WHERE review_type = 'local' AND local_path = ? AND local_head_sha = ?
+      ORDER BY updated_at DESC
+      LIMIT 1
     `, [localPath, localHeadSha]);
 
     if (!row) return null;
@@ -2663,6 +3054,102 @@ class ReviewRepository {
     };
   }
 
+  /**
+   * Find a local review by path and SHA, trying branch-exact match first,
+   * then falling back to branch-agnostic lookup.
+   * @param {string} localPath - Absolute path to the local repository
+   * @param {string} localHeadSha - Current HEAD SHA of the repository
+   * @param {string} [headBranch] - Branch name for exact match
+   * @returns {Promise<Object|null>} Review record or null if not found
+   */
+  async findLocalReview(localPath, localHeadSha, headBranch) {
+    const review = await this.getLocalReview(localPath, localHeadSha, headBranch);
+    if (review) return review;
+    // Only adopt sessions that predate branch tracking (NULL branch)
+    const fallback = await this.getLocalReviewByPathAndSha(localPath, localHeadSha);
+    if (fallback && fallback.local_head_branch === null) return fallback;
+    return null;
+  }
+
+  /**
+   * Get an existing branch-mode local review by path (ignoring HEAD SHA).
+   * Branch-mode sessions persist across HEAD changes — only the path matters.
+   * @param {string} localPath - Absolute path to the local repository
+   * @returns {Promise<Object|null>} Most recent branch-mode review or null
+   */
+  async getLocalBranchReview(localPath, headBranch) {
+    return this.getLocalBranchScopeReview(localPath, headBranch);
+  }
+
+  /**
+   * Get an existing branch-scope local review by path and head branch.
+   * Branch-scope sessions persist across HEAD changes but are scoped to a specific branch.
+   * @param {string} localPath - Absolute path to the local repository
+   * @param {string} headBranch - Current branch name
+   * @returns {Promise<Object|null>} Most recent branch-scope review or null
+   */
+  async getLocalBranchScopeReview(localPath, headBranch) {
+    const row = await queryOne(this.db, `
+      SELECT id, pr_number, repository, status, review_id,
+             created_at, updated_at, submitted_at, review_data, custom_instructions,
+             review_type, local_path, local_head_sha, summary, name,
+             local_mode, local_base_branch, local_head_branch, local_scope_start, local_scope_end
+      FROM reviews
+      WHERE review_type = 'local' AND local_path = ? AND local_scope_start = 'branch' AND local_head_branch = ?
+      ORDER BY updated_at DESC
+      LIMIT 1
+    `, [localPath, headBranch]);
+    if (!row) return null;
+    return { ...row, review_data: row.review_data ? JSON.parse(row.review_data) : null };
+  }
+
+  /**
+   * Update the HEAD SHA for a local review.
+   * Used when branch-mode sessions persist across commits — the unique index
+   * on (local_path, local_head_sha) requires careful handling.
+   * @param {number} id - Review ID
+   * @param {string} newHeadSha - New HEAD SHA to set
+   * @returns {Promise<boolean>} True if record was updated
+   */
+  async updateLocalHeadSha(id, newHeadSha) {
+    const result = await run(this.db, `
+      UPDATE reviews
+      SET local_head_sha = ?, updated_at = CURRENT_TIMESTAMP
+      WHERE id = ?
+    `, [newHeadSha, id]);
+    return result.changes > 0;
+  }
+
+  /**
+   * Update the scope range and optionally the base branch for a local review.
+   * @param {number} id - Review ID
+   * @param {string} scopeStart - Scope start value (e.g. 'unstaged', 'staged', 'branch')
+   * @param {string} scopeEnd - Scope end value (e.g. 'staged', 'untracked', 'branch')
+   * @param {string} [baseBranch] - Base branch name (only relevant for branch scope)
+   * @returns {Promise<boolean>} True if record was updated
+   */
+  async updateLocalScope(id, scopeStart, scopeEnd, baseBranch, headBranch) {
+    const updates = ['local_scope_start = ?', 'local_scope_end = ?', 'updated_at = CURRENT_TIMESTAMP'];
+    const params = [scopeStart, scopeEnd];
+    // Also write local_mode for backward compat
+    updates.push('local_mode = ?');
+    params.push(scopeStart === 'branch' ? 'branch' : 'uncommitted');
+    if (baseBranch !== undefined) {
+      updates.push('local_base_branch = ?');
+      params.push(baseBranch);
+    }
+    // Store head branch when entering branch scope, clear when leaving
+    updates.push('local_head_branch = ?');
+    params.push(scopeStart === 'branch' ? (headBranch || null) : null);
+    params.push(id);
+    const result = await run(this.db, `
+      UPDATE reviews
+      SET ${updates.join(', ')}
+      WHERE id = ?
+    `, params);
+    return result.changes > 0;
+  }
+
   /**
    * Get a local review by its database ID
    * @param {number} id - Review ID
@@ -2672,7 +3159,8 @@ class ReviewRepository {
     const row = await queryOne(this.db, `
       SELECT id, pr_number, repository, status, review_id,
              created_at, updated_at, submitted_at, review_data, custom_instructions,
-             review_type, local_path, local_head_sha, summary, name
+             review_type, local_path, local_head_sha, summary, name,
+             local_mode, local_base_branch, local_head_branch, local_scope_start, local_scope_end
       FROM reviews
       WHERE id = ? AND review_type = 'local'
     `, [id]);
@@ -2798,6 +3286,69 @@ class ReviewRepository {
     `, [reviewId]);
     return result.changes > 0;
   }
+
+  /**
+   * Find reviews older than the given cutoff date (based on updated_at).
+   * @param {string} cutoffDate - ISO 8601 date string
+   * @returns {Promise<Array<{id: number, pr_number: number|null, repository: string, review_type: string}>>}
+   */
+  async findStale(cutoffDate) {
+    return query(this.db, `
+      SELECT id, pr_number, repository, review_type
+      FROM reviews
+      WHERE updated_at < ?
+    `, [cutoffDate]);
+  }
+
+  /**
+   * Delete a review and all associated data in a single transaction.
+   *
+   * Cascade-deleted by FK constraints: analysis_runs, local_diffs, github_reviews,
+   * chat_sessions (→ chat_messages), context_files, comments.
+   *
+   * Orphan-cleaned explicitly: pr_metadata, github_pr_cache (only when no other
+   * reviews reference the same PR).
+   *
+   * @param {number} reviewId - Review ID to delete
+   * @param {Object} [opts] - Options
+   * @param {number|null} [opts.prNumber] - PR number (skips orphan cleanup if null)
+   * @param {string|null} [opts.repository] - Repository in owner/repo format
+   * @returns {Promise<boolean>} True if review was deleted
+   */
+  async deleteWithRelatedData(reviewId, { prNumber = null, repository = null } = {}) {
+    return withTransaction(this.db, async () => {
+      // Delete the review row — FK cascades handle related tables
+      const result = await run(this.db, 'DELETE FROM reviews WHERE id = ?', [reviewId]);
+
+      if (result.changes === 0) return false;
+
+      // Clean up orphaned pr_metadata and github_pr_cache if this was a PR review
+      if (prNumber != null && repository) {
+        const remaining = await queryOne(this.db, `
+          SELECT COUNT(*) as cnt FROM reviews
+          WHERE pr_number = ? AND repository = ? COLLATE NOCASE
+        `, [prNumber, repository]);
+
+        if (remaining.cnt === 0) {
+          await run(this.db, `
+            DELETE FROM pr_metadata
+            WHERE pr_number = ? AND repository = ? COLLATE NOCASE
+          `, [prNumber, repository]);
+
+          // Parse owner/repo for github_pr_cache
+          const parts = repository.split('/');
+          if (parts.length === 2) {
+            await run(this.db, `
+              DELETE FROM github_pr_cache
+              WHERE owner = ? AND repo = ? AND number = ?
+            `, [parts[0], parts[1], prNumber]);
+          }
+        }
+      }
+
+      return true;
+    });
+  }
 }
 
 /**
@@ -2927,14 +3478,14 @@ class AnalysisRunRepository {
    * @param {string} [runInfo.status='running'] - Initial status (default 'running'; pass 'completed' for externally-produced results)
    * @returns {Promise<Object>} Created analysis run record
    */
-  async create({ id, reviewId, provider = null, model = null, tier = null, customInstructions = null, repoInstructions = null, requestInstructions = null, headSha = null, diff = null, status = 'running', parentRunId = null, configType = 'single', levelsConfig = null }) {
+  async create({ id, reviewId, provider = null, model = null, tier = null, customInstructions = null, repoInstructions = null, requestInstructions = null, headSha = null, diff = null, status = 'running', parentRunId = null, configType = 'single', levelsConfig = null, scopeStart = null, scopeEnd = null }) {
     const isTerminal = ['completed', 'failed', 'cancelled'].includes(status);
     const completedAt = isTerminal ? 'CURRENT_TIMESTAMP' : 'NULL';
     const levelsConfigJson = levelsConfig ? JSON.stringify(levelsConfig) : null;
     await run(this.db, `
-      INSERT INTO analysis_runs (id, review_id, provider, model, tier, custom_instructions, repo_instructions, request_instructions, head_sha, diff, status, completed_at, parent_run_id, config_type, levels_config)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ${completedAt}, ?, ?, ?)
-    `, [id, reviewId, provider, model, tier, customInstructions, repoInstructions, requestInstructions, headSha, diff, status, parentRunId, configType, levelsConfigJson]);
+      INSERT INTO analysis_runs (id, review_id, provider, model, tier, custom_instructions, repo_instructions, request_instructions, head_sha, diff, status, completed_at, parent_run_id, config_type, levels_config, scope_start, scope_end)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ${completedAt}, ?, ?, ?, ?, ?)
+    `, [id, reviewId, provider, model, tier, customInstructions, repoInstructions, requestInstructions, headSha, diff, status, parentRunId, configType, levelsConfigJson, scopeStart, scopeEnd]);
 
     // Query back the inserted row to return actual database values (including timestamps)
     return await this.getById(id);