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

package/src/routes/local.js

@@ -1,4 +1,4 @@
-// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
 /**
  * Local Review Routes
  *
@@ -13,6 +13,7 @@
  */
 
 const express = require('express');
+const { execSync } = require('child_process');
 const path = require('path');
 const fs = require('fs').promises;
 const { queryOne, run, ReviewRepository, RepoSettingsRepository, AnalysisRunRepository, CouncilRepository } = require('../database');
@@ -20,9 +21,14 @@ const Analyzer = require('../ai/analyzer');
 const { v4: uuidv4 } = require('uuid');
 const logger = require('../utils/logger');
 const { broadcastReviewEvent } = require('../events/review-events');
+const { fireHooks, hasHooks } = require('../hooks/hook-runner');
+const { buildReviewStartedPayload, buildReviewLoadedPayload, buildAnalysisStartedPayload, buildAnalysisCompletedPayload, getCachedUser } = require('../hooks/payloads');
 const { mergeInstructions } = require('../utils/instructions');
-const { generateLocalDiff, computeLocalDiffDigest } = require('../local-review');
+const { getGitHubToken } = require('../config');
+const { generateScopedDiff, computeScopedDigest, getBranchCommitCount, getFirstCommitSubject, detectAndBuildBranchInfo, findMergeBase, getCurrentBranch, getRepositoryName } = require('../local-review');
+const { STOPS, isValidScope, scopeIncludes, includesBranch, DEFAULT_SCOPE } = require('../local-scope');
 const { getGeneratedFilePatterns } = require('../git/gitattributes');
+const { getShaAbbrevLength } = require('../git/sha-abbrev');
 const { validateCouncilConfig, normalizeCouncilConfig } = require('./councils');
 const { TIERS, TIER_ALIASES, VALID_TIERS, resolveTier } = require('../ai/prompts/config');
 const {
@@ -60,6 +66,22 @@ function deleteLocalReviewDiff(reviewId) {
   localReviewDiffs.delete(toIntKey(reviewId));
 }
 
+/**
+ * Delete a local review session and its in-memory diff cache.
+ * Shared by both single-delete and bulk-delete routes.
+ *
+ * @param {ReviewRepository} reviewRepo - Repository instance
+ * @param {number} id - Review ID
+ * @returns {boolean} true if deleted, false if not found
+ */
+async function deleteLocalReviewFull(reviewRepo, id) {
+  const deleted = await reviewRepo.deleteLocalSession(id);
+  if (deleted) {
+    deleteLocalReviewDiff(id);
+  }
+  return deleted;
+}
+
 /**
  * Open native OS directory picker dialog and return the selected path.
  * Uses osascript on macOS, zenity/kdialog on Linux, PowerShell on Windows.
@@ -165,9 +187,19 @@ router.get('/api/local/sessions', async (req, res) => {
     const reviewRepo = new ReviewRepository(db);
     const { sessions, hasMore } = await reviewRepo.listLocalSessions({ limit, before });
 
+    // Compute SHA abbreviation length per unique repo path
+    const abbrevCache = new Map();
+    const enrichedSessions = sessions.map(session => {
+      if (!session.local_path) return session;
+      if (!abbrevCache.has(session.local_path)) {
+        abbrevCache.set(session.local_path, getShaAbbrevLength(session.local_path));
+      }
+      return { ...session, sha_abbrev_length: abbrevCache.get(session.local_path) };
+    });
+
     res.json({
       success: true,
-      sessions,
+      sessions: enrichedSessions,
       hasMore
     });
 
@@ -179,6 +211,74 @@ router.get('/api/local/sessions', async (req, res) => {
   }
 });
 
+/**
+ * Bulk delete local review sessions.
+ * Accepts { ids: number[] } in request body. Max 50 IDs per request.
+ * Must be registered BEFORE /:reviewId param routes.
+ * Only deletes DB records — does NOT remove files on disk.
+ */
+router.post('/api/local/sessions/bulk-delete', async (req, res) => {
+  try {
+    const { ids } = req.body || {};
+
+    if (!Array.isArray(ids) || ids.length === 0) {
+      return res.status(400).json({
+        success: false,
+        error: 'Request body must contain a non-empty "ids" array'
+      });
+    }
+
+    if (ids.length > 50) {
+      return res.status(400).json({
+        success: false,
+        error: 'Maximum 50 IDs per request'
+      });
+    }
+
+    const parsedIds = ids.map(id => parseInt(id, 10));
+    if (parsedIds.some(id => isNaN(id) || id <= 0)) {
+      return res.status(400).json({
+        success: false,
+        error: 'All IDs must be positive integers'
+      });
+    }
+
+    const db = req.app.get('db');
+    const reviewRepo = new ReviewRepository(db);
+    let deleted = 0;
+    const errors = [];
+
+    for (const id of parsedIds) {
+      try {
+        const result = await deleteLocalReviewFull(reviewRepo, id);
+        if (result) {
+          deleted++;
+        } else {
+          errors.push({ id, error: `Local review #${id} not found` });
+        }
+      } catch (err) {
+        errors.push({ id, error: err.message });
+      }
+    }
+
+    if (deleted > 0) logger.success(`Bulk deleted ${deleted} local review session(s)`);
+
+    res.json({
+      success: deleted > 0 || errors.length === 0,
+      deleted,
+      failed: errors.length,
+      errors
+    });
+
+  } catch (error) {
+    logger.error(`Error in bulk delete local sessions: ${error.message}`);
+    res.status(500).json({
+      success: false,
+      error: 'Failed to process bulk delete'
+    });
+  }
+});
+
 /**
  * Delete a local review session
  * Must be registered BEFORE /:reviewId param routes
@@ -196,7 +296,7 @@ router.delete('/api/local/sessions/:reviewId', async (req, res) => {
 
     const db = req.app.get('db');
     const reviewRepo = new ReviewRepository(db);
-    const deleted = await reviewRepo.deleteLocalSession(reviewId);
+    const deleted = await deleteLocalReviewFull(reviewRepo, reviewId);
 
     if (!deleted) {
       return res.status(404).json({
@@ -204,9 +304,6 @@ router.delete('/api/local/sessions/:reviewId', async (req, res) => {
       });
     }
 
-    // Clean up in-memory diff cache to avoid stale data
-    deleteLocalReviewDiff(reviewId);
-
     logger.success(`Deleted local review session #${reviewId}`);
 
     res.json({
@@ -275,21 +372,79 @@ router.post('/api/local/start', async (req, res) => {
     // Create or resume session
     const db = req.app.get('db');
     const reviewRepo = new ReviewRepository(db);
-    const sessionId = await reviewRepo.upsertLocalReview({
-      localPath: repoPath,
-      localHeadSha: headSha,
-      repository
-    });
 
-    // Generate diff
+    let sessionId;
+    // Try exact match (path + sha + branch)
+    let existing = await reviewRepo.getLocalReview(repoPath, headSha, branch);
+
+    // Adopt legacy sessions that predate branch tracking
+    if (!existing) {
+      const legacy = await reviewRepo.getLocalReviewByPathAndSha(repoPath, headSha);
+      if (legacy && legacy.local_head_branch === null) {
+        existing = legacy;
+      }
+    }
+
+    // Check for branch-scope session (persists across HEAD changes)
+    if (!existing) {
+      const branchSession = await reviewRepo.getLocalBranchScopeReview(repoPath, branch);
+      if (branchSession) existing = branchSession;
+    }
+
+    if (existing) {
+      sessionId = existing.id;
+      if (existing.local_head_sha !== headSha) {
+        await reviewRepo.updateLocalHeadSha(sessionId, headSha);
+      }
+      if (existing.local_head_branch === null) {
+        await reviewRepo.updateReview(sessionId, { local_head_branch: branch });
+      }
+    } else {
+      sessionId = await reviewRepo.upsertLocalReview({
+        localPath: repoPath,
+        localHeadSha: headSha,
+        repository,
+        scopeStart: DEFAULT_SCOPE.start,
+        scopeEnd: DEFAULT_SCOPE.end,
+        localHeadBranch: branch
+      });
+    }
+
+    // Fire review hook (non-blocking)
+    const config = req.app.get('config') || {};
+    // Generate diff using default scope
     logger.log('API', `Starting local review for ${repoPath}`, 'cyan');
-    const { diff, stats } = await generateLocalDiff(repoPath);
+    const scopeStart = existing?.local_scope_start || DEFAULT_SCOPE.start;
+    const scopeEnd = existing?.local_scope_end || DEFAULT_SCOPE.end;
+
+    // Fire review hook (non-blocking, after scope is resolved)
+    const hookEvent = existing ? 'review.loaded' : 'review.started';
+    if (hasHooks(hookEvent, config)) {
+      getCachedUser(config).then(user => {
+        const builder = existing ? buildReviewLoadedPayload : buildReviewStartedPayload;
+        const si = STOPS.indexOf(scopeStart);
+        const ei = STOPS.indexOf(scopeEnd);
+        const scope = STOPS.slice(si, ei + 1);
+        const payload = builder({ reviewId: sessionId, mode: 'local', localContext: { path: repoPath, branch, headSha, scope }, user });
+        fireHooks(hookEvent, payload, config);
+      }).catch(err => { logger.warn(`Review hook failed: ${err.message}`); });
+    }
+    const baseBranch = existing?.local_base_branch || null;
+    const { diff, stats } = await generateScopedDiff(repoPath, scopeStart, scopeEnd, baseBranch);
 
     // Compute digest for staleness detection
-    const digest = await computeLocalDiffDigest(repoPath);
+    const digest = await computeScopedDigest(repoPath, scopeStart, scopeEnd);
+
+    // Branch detection: when no uncommitted changes, check if branch has commits ahead
+    const branchInfo = await detectAndBuildBranchInfo(repoPath, branch, {
+      repository,
+      diff,
+      githubToken: getGitHubToken(config),
+      enableGraphite: config.enable_graphite === true
+    });
 
     // Persist to in-memory Map
-    setLocalReviewDiff(sessionId, { diff, stats, digest });
+    setLocalReviewDiff(sessionId, { diff, stats, digest, branchInfo });
 
     // Persist to database
     await reviewRepo.saveLocalDiff(sessionId, { diff, stats, digest });
@@ -302,6 +457,7 @@ router.post('/api/local/start', async (req, res) => {
       sessionId,
       repository,
       branch,
+      branchInfo,
       stats: {
         trackedChanges: stats.trackedChanges || 0,
         untrackedFiles: stats.untrackedFiles || 0,
@@ -376,6 +532,73 @@ router.get('/api/local/:reviewId', async (req, res) => {
       }
     }
 
+    // Build scope info for the response
+    const scopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
+    const scopeEnd = review.local_scope_end || DEFAULT_SCOPE.end;
+    const baseBranch = review.local_base_branch || null;
+
+    // When scope does NOT include branch, check for branch detection info
+    // Frontend uses this to suggest expanding scope to include branch
+    let branchInfo = null;
+    const cachedDiff = getLocalReviewDiff(reviewId);
+    if (!includesBranch(scopeStart) && cachedDiff?.branchInfo) {
+      branchInfo = cachedDiff.branchInfo;
+    } else if (!includesBranch(scopeStart) && !cachedDiff && review.local_path) {
+      // No cache (web UI started session) — run detection on-demand
+      const config = req.app.get('config') || {};
+      branchInfo = await detectAndBuildBranchInfo(review.local_path, branchName, {
+        repository: repositoryName,
+        githubToken: getGitHubToken(config),
+        enableGraphite: config.enable_graphite === true
+      });
+    }
+
+    // Check repo settings for auto_branch_review preference
+    let autoBranchReview = 0;
+    if (branchInfo && repositoryName && repositoryName.includes('/')) {
+      try {
+        const repoSettingsRepo = new RepoSettingsRepository(db);
+        const repoSettings = await repoSettingsRepo.getRepoSettings(repositoryName);
+        if (repoSettings) {
+          autoBranchReview = repoSettings.auto_branch_review || 0;
+        }
+      } catch {
+        // Non-fatal
+      }
+    }
+
+    // If auto_branch_review is -1 (never), suppress branchInfo
+    if (autoBranchReview === -1) {
+      branchInfo = null;
+    }
+
+    // Determine if Branch stop should be selectable in the scope range selector.
+    // This is independent of branchInfo (which guards on no uncommitted changes).
+    // Branch is available when: not detached HEAD, not on default branch, and has commits ahead.
+    let branchAvailable = includesBranch(scopeStart) || Boolean(branchInfo);
+    if (!branchAvailable && branchName && branchName !== 'HEAD' && branchName !== 'unknown' && review.local_path) {
+      try {
+        const { getBranchCommitCount } = require('../local-review');
+        const { detectBaseBranch } = require('../git/base-branch');
+        const config = req.app.get('config') || {};
+        const depsOverride = getGitHubToken(config) ? { getGitHubToken: () => getGitHubToken(config) } : undefined;
+        const detection = await detectBaseBranch(review.local_path, branchName, {
+          repository: repositoryName,
+          enableGraphite: config.enable_graphite === true,
+          _deps: depsOverride
+        });
+        if (detection) {
+          const commitCount = await getBranchCommitCount(review.local_path, detection.baseBranch);
+          branchAvailable = commitCount > 0;
+        }
+      } catch {
+        // Non-fatal — branch stop stays disabled
+      }
+    }
+
+    // Compute SHA abbreviation length from the repo's git config
+    const shaAbbrevLength = getShaAbbrevLength(review.local_path);
+
     res.json({
       id: review.id,
       localPath: review.local_path,
@@ -385,10 +608,35 @@ router.get('/api/local/:reviewId', async (req, res) => {
       reviewType: 'local',
       status: review.status,
       name: review.name || null,
+      localMode: review.local_mode || 'uncommitted',
+      scopeStart,
+      scopeEnd,
+      baseBranch,
+      branchInfo,
+      branchAvailable,
+      shaAbbrevLength,
       createdAt: review.created_at,
       updatedAt: review.updated_at
     });
 
+    // Fire review.loaded hook (session already exists to be fetched by ID)
+    const hookConfig = req.app.get('config') || {};
+    if (hasHooks('review.loaded', hookConfig)) {
+      getCachedUser(hookConfig).then(user => {
+        const hookScopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
+        const hookScopeEnd = review.local_scope_end || DEFAULT_SCOPE.end;
+        const si = STOPS.indexOf(hookScopeStart);
+        const ei = STOPS.indexOf(hookScopeEnd);
+        const scope = STOPS.slice(si, ei + 1);
+        const payload = buildReviewLoadedPayload({
+          reviewId: review.id, mode: 'local',
+          localContext: { path: review.local_path, branch: branchName, headSha: review.local_head_sha, scope },
+          user,
+        });
+        fireHooks('review.loaded', payload, hookConfig);
+      }).catch(err => { logger.warn(`Review hook failed: ${err.message}`); });
+    }
+
   } catch (error) {
     logger.error('Error fetching local review:', error.stack || error.message);
     res.status(500).json({
@@ -467,11 +715,13 @@ router.get('/api/local/:reviewId/diff', async (req, res) => {
 
     // When ?w=1, regenerate the diff with whitespace changes hidden (transient view, not cached)
     const hideWhitespace = req.query.w === '1';
+    const scopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
+    const scopeEnd = review.local_scope_end || DEFAULT_SCOPE.end;
     let diffData;
 
     if (hideWhitespace && review.local_path) {
       try {
-        const wsResult = await generateLocalDiff(review.local_path, { hideWhitespace: true });
+        const wsResult = await generateScopedDiff(review.local_path, scopeStart, scopeEnd, review.local_base_branch, { hideWhitespace: true });
         diffData = { diff: wsResult.diff, stats: wsResult.stats };
       } catch (wsError) {
         logger.warn(`Could not generate whitespace-filtered diff for review #${reviewId}: ${wsError.message}`);
@@ -572,6 +822,42 @@ router.get('/api/local/:reviewId/check-stale', async (req, res) => {
       });
     }
 
+    const scopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
+    const scopeEnd = review.local_scope_end || DEFAULT_SCOPE.end;
+
+    // Always check HEAD SHA for supplementary fields
+    let headShaChanged = false;
+    let previousHeadSha = review.local_head_sha || null;
+    let currentHeadSha = null;
+
+    try {
+      const { getHeadSha } = require('../local-review');
+      currentHeadSha = await getHeadSha(localPath);
+      headShaChanged = !!(previousHeadSha && currentHeadSha && currentHeadSha !== previousHeadSha);
+    } catch (error) {
+      // If branch is in scope, HEAD SHA failure is fatal (existing behavior)
+      if (includesBranch(scopeStart)) {
+        return res.json({
+          isStale: true,
+          headShaChanged,
+          previousHeadSha,
+          currentHeadSha: null,
+          error: `Could not check HEAD SHA: ${error.message}`
+        });
+      }
+      // Otherwise, just continue with digest check
+    }
+
+    // When branch is in scope and HEAD changed, early return (existing behavior)
+    if (includesBranch(scopeStart) && headShaChanged) {
+      return res.json({
+        isStale: true,
+        headShaChanged,
+        previousHeadSha,
+        currentHeadSha
+      });
+    }
+
     // Get stored diff data (in-memory first, then fall back to DB)
     let storedDiffData = getLocalReviewDiff(reviewId);
     if (!storedDiffData) {
@@ -584,6 +870,9 @@ router.get('/api/local/:reviewId/check-stale', async (req, res) => {
       } else {
         return res.json({
           isStale: null,
+          headShaChanged,
+          previousHeadSha,
+          currentHeadSha,
           error: 'No stored diff data found'
         });
       }
@@ -595,17 +884,23 @@ router.get('/api/local/:reviewId/check-stale', async (req, res) => {
       // Assume stale to be safe and prompt user to refresh
       return res.json({
         isStale: true,
+        headShaChanged,
+        previousHeadSha,
+        currentHeadSha,
         error: 'No baseline digest - please refresh to enable staleness detection'
       });
     }
 
     // Compute current digest to compare against baseline
-    const currentDigest = await computeLocalDiffDigest(localPath);
+    const currentDigest = await computeScopedDigest(localPath, scopeStart, scopeEnd);
 
     // If current digest computation failed, assume stale to be safe
     if (!currentDigest) {
       return res.json({
         isStale: true,
+        headShaChanged,
+        previousHeadSha,
+        currentHeadSha,
         error: 'Could not compute current digest - refresh recommended'
       });
     }
@@ -615,13 +910,19 @@ router.get('/api/local/:reviewId/check-stale', async (req, res) => {
     res.json({
       isStale,
       storedDigest: storedDiffData.digest,
-      currentDigest
+      currentDigest,
+      headShaChanged,
+      previousHeadSha,
+      currentHeadSha
     });
 
   } catch (error) {
     logger.warn(`Error checking local review staleness: ${error.message}`);
     res.json({
       isStale: null,
+      headShaChanged: false,
+      previousHeadSha: null,
+      currentHeadSha: null,
       error: error.message
     });
   }
@@ -715,6 +1016,10 @@ router.post('/api/local/:reviewId/analyses', async (req, res) => {
     const runId = uuidv4();
     const analysisId = runId;
 
+    // Extract scope early — needed for both analysis run creation and diff generation
+    const scopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
+    const scopeEnd = review.local_scope_end || DEFAULT_SCOPE.end;
+
     // Create DB analysis_runs record immediately so it's queryable for polling
     const analysisRunRepo = new AnalysisRunRepository(db);
     const levelsConfig = parseEnabledLevels(requestEnabledLevels, requestSkipLevel3);
@@ -730,7 +1035,9 @@ router.post('/api/local/:reviewId/analyses', async (req, res) => {
         requestInstructions,
         headSha: review.local_head_sha || null,
         configType: 'single',
-        levelsConfig
+        levelsConfig,
+        scopeStart,
+        scopeEnd
       });
     } catch (error) {
       logger.error('Failed to create analysis run record:', error);
@@ -764,26 +1071,54 @@ router.post('/api/local/:reviewId/analyses', async (req, res) => {
     // Broadcast initial status
     broadcastProgress(analysisId, initialStatus);
     broadcastReviewEvent(reviewId, { type: 'review:analysis_started', analysisId });
+    const analysisHookConfig = req.app.get('config') || {};
+    if (hasHooks('analysis.started', analysisHookConfig)) {
+      getCachedUser(analysisHookConfig).then(user => {
+        fireHooks('analysis.started', buildAnalysisStartedPayload({
+          reviewId, analysisId, provider: selectedProvider, model: selectedModel,
+          mode: 'local',
+          localContext: { path: localPath, branch: review.local_head_branch, headSha: review.local_head_sha },
+          user,
+        }), analysisHookConfig);
+      }).catch(() => {});
+    }
 
     // Create analyzer instance with provider and model
     const analyzer = new Analyzer(db, selectedModel, selectedProvider);
 
     // Build local review metadata for the analyzer
     // The analyzer uses base_sha and head_sha for git diff commands
-    // For local review, we use HEAD as both since we're diffing working directory
+    // When branch is in scope, base_sha is the merge-base; otherwise, HEAD
+    const hasBranch = includesBranch(scopeStart);
+    let analysisBaseSha = review.local_head_sha;
+    if (hasBranch && review.local_base_branch) {
+      try {
+        analysisBaseSha = await findMergeBase(localPath, review.local_base_branch);
+      } catch {
+        // Fall back to HEAD
+      }
+    }
     const localMetadata = {
       id: reviewId,
-      repository: review.repository,  // Include repository for context display
-      title: `Local changes in ${repository}`,
-      description: `Reviewing uncommitted changes in ${localPath}`,
-      base_sha: review.local_head_sha,  // HEAD commit
-      head_sha: review.local_head_sha,  // HEAD commit (diff is against working directory)
+      repository: review.repository,
+      title: hasBranch
+        ? `Branch changes: ${review.local_base_branch}..HEAD`
+        : `Local changes in ${repository}`,
+      description: hasBranch
+        ? `Reviewing committed changes on branch against ${review.local_base_branch}`
+        : `Reviewing uncommitted changes in ${localPath}`,
+      base_sha: analysisBaseSha,
+      head_sha: review.local_head_sha,
       reviewType: 'local'
     };
 
     // Get changed files for local mode path validation
-    // This is critical for local mode since git diff HEAD...HEAD returns nothing
-    const changedFiles = await analyzer.getLocalChangedFiles(localPath);
+    // When branch is in scope, pass null so analyzer falls through to getChangedFilesList
+    // which correctly uses git diff base_sha...head_sha --name-only
+    const hasStaged = scopeIncludes(scopeStart, scopeEnd, 'staged');
+    const changedFiles = hasBranch
+      ? null
+      : await analyzer.getLocalChangedFiles(localPath, { includeStaged: hasStaged });
 
     // Log analysis start
     logger.section(`Local AI Analysis Request - Review #${reviewId}`);
@@ -793,7 +1128,7 @@ router.post('/api/local/:reviewId/analyses', async (req, res) => {
     logger.log('API', `Provider: ${selectedProvider}`, 'cyan');
     logger.log('API', `Model: ${selectedModel}`, 'cyan');
     logger.log('API', `Tier: ${tier}`, 'cyan');
-    logger.log('API', `Changed files: ${changedFiles.length}`, 'cyan');
+    logger.log('API', `Changed files: ${changedFiles ? changedFiles.length : '(branch mode)'}`, 'cyan');
     if (combinedInstructions) {
       logger.log('API', `Custom instructions: ${combinedInstructions.length} chars`, 'cyan');
     }
@@ -865,6 +1200,21 @@ router.post('/api/local/:reviewId/analyses', async (req, res) => {
         // Broadcast completion status
         broadcastProgress(analysisId, completedStatus);
         broadcastReviewEvent(reviewId, { type: 'review:analysis_completed' });
+
+        // Fire analysis.completed hook
+        const hookConfig = req.app.get('config') || {};
+        if (hasHooks('analysis.completed', hookConfig)) {
+          getCachedUser(hookConfig).then(user => {
+            fireHooks('analysis.completed', buildAnalysisCompletedPayload({
+              reviewId, analysisId, provider: selectedProvider, model: selectedModel,
+              status: 'success',
+              totalSuggestions: completionInfo.totalSuggestions,
+              mode: 'local',
+              localContext: { path: localPath, branch: review.local_head_branch, headSha: review.local_head_sha },
+              user,
+            }), hookConfig);
+          }).catch(() => {});
+        }
       })
       .catch(error => {
         const currentStatus = activeAnalyses.get(analysisId);
@@ -877,6 +1227,18 @@ router.post('/api/local/:reviewId/analyses', async (req, res) => {
         if (error.isCancellation) {
           logger.info(`Local analysis cancelled for review #${reviewId}`);
           // Status is already set to 'cancelled' by the cancel endpoint
+          const cancelConfig = req.app.get('config') || {};
+          if (hasHooks('analysis.completed', cancelConfig)) {
+            getCachedUser(cancelConfig).then(user => {
+              fireHooks('analysis.completed', buildAnalysisCompletedPayload({
+                reviewId, analysisId, provider: selectedProvider, model: selectedModel,
+                status: 'cancelled', totalSuggestions: 0,
+                mode: 'local',
+                localContext: { path: localPath, branch: review.local_head_branch, headSha: review.local_head_sha },
+                user,
+              }), cancelConfig);
+            }).catch(() => {});
+          }
           return;
         }
 
@@ -902,6 +1264,19 @@ router.post('/api/local/:reviewId/analyses', async (req, res) => {
 
         // Broadcast failure status
         broadcastProgress(analysisId, failedStatus);
+
+        const failConfig = req.app.get('config') || {};
+        if (hasHooks('analysis.completed', failConfig)) {
+          getCachedUser(failConfig).then(user => {
+            fireHooks('analysis.completed', buildAnalysisCompletedPayload({
+              reviewId, analysisId, provider: selectedProvider, model: selectedModel,
+              status: 'failed', totalSuggestions: 0,
+              mode: 'local',
+              localContext: { path: localPath, branch: review.local_head_branch, headSha: review.local_head_sha },
+              user,
+            }), failConfig);
+          }).catch(() => {});
+        }
       })
       .finally(() => {
         // Clean up review to analysis ID mapping (unified map)
@@ -964,64 +1339,66 @@ router.post('/api/local/:reviewId/refresh', async (req, res) => {
 
     // Check if HEAD has changed
     const { getHeadSha } = require('../local-review');
+    const scopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
+    const scopeEnd = review.local_scope_end || DEFAULT_SCOPE.end;
+    const hasBranch = includesBranch(scopeStart);
     let currentHeadSha;
-    let sessionChanged = false;
-    let newSessionId = null;
+    let headShaChanged = false;
 
     try {
       currentHeadSha = await getHeadSha(localPath);
 
       if (originalHeadSha && currentHeadSha !== originalHeadSha) {
-        sessionChanged = true;
-        logger.log('API', `HEAD changed: ${originalHeadSha.substring(0, 7)} -> ${currentHeadSha.substring(0, 7)}`, 'yellow');
-
-        // Check if a session already exists for the new HEAD
-        const existingSession = await reviewRepo.getLocalReview(localPath, currentHeadSha);
-        if (existingSession) {
-          newSessionId = existingSession.id;
-          logger.log('API', `Existing session found for new HEAD: ${newSessionId}`, 'cyan');
-        } else {
-          // Create a new session for the new HEAD
-          const { getRepositoryName } = require('../local-review');
-          const repository = await getRepositoryName(localPath);
-          newSessionId = await reviewRepo.upsertLocalReview({
-            localPath: localPath,
-            localHeadSha: currentHeadSha,
-            repository
-          });
-          logger.log('API', `Created new session for new HEAD: ${newSessionId}`, 'cyan');
+        headShaChanged = true;
+        const abbrevLen = getShaAbbrevLength(localPath);
+        logger.log('API', `HEAD changed: ${originalHeadSha.substring(0, abbrevLen)} -> ${currentHeadSha.substring(0, abbrevLen)}`, 'yellow');
+
+        if (hasBranch) {
+          // Branch scope: session persists across HEAD changes — just update the SHA
+          await reviewRepo.updateLocalHeadSha(reviewId, currentHeadSha);
+          logger.log('API', `Updated HEAD SHA on branch-scope session ${reviewId}`, 'cyan');
         }
+        // Non-branch scope: defer decision to frontend via resolve-head-change endpoint
       }
     } catch (headError) {
       logger.warn(`Could not check HEAD SHA: ${headError.message}`);
     }
 
-    // Regenerate the diff from the working directory
-    const { diff, stats } = await generateLocalDiff(localPath);
-
-    // Compute fresh digest for the new diff
-    const digest = await computeLocalDiffDigest(localPath);
+    // Non-branch HEAD change: skip diff computation entirely — the old diff is
+    // preserved until the user decides (via resolve-head-change) what to do.
+    // The resolve-head-change endpoint will recompute the diff for whichever
+    // action the user picks (update or new-session).
+    if (headShaChanged && !hasBranch) {
+      return res.json({
+        success: true,
+        message: 'HEAD changed — awaiting user decision',
+        headShaChanged,
+        previousHeadSha: originalHeadSha,
+        currentHeadSha: currentHeadSha || null,
+        stats: {}
+      });
+    }
 
-    // Update the stored diff data for the appropriate session
-    const targetSessionId = sessionChanged ? newSessionId : reviewId;
-    setLocalReviewDiff(targetSessionId, { diff, stats, digest });
+    const scopedResult = await generateScopedDiff(localPath, scopeStart, scopeEnd, review.local_base_branch);
+    const diff = scopedResult.diff;
+    const stats = scopedResult.stats;
+    const digest = await computeScopedDigest(localPath, scopeStart, scopeEnd);
 
-    // Persist diff to database for future session recovery
+    setLocalReviewDiff(reviewId, { diff, stats, digest });
     try {
-      await reviewRepo.saveLocalDiff(targetSessionId, { diff, stats, digest });
+      await reviewRepo.saveLocalDiff(reviewId, { diff, stats, digest });
     } catch (persistError) {
       logger.warn(`Could not persist diff to database: ${persistError.message}`);
     }
 
-    logger.success(`Diff refreshed: ${stats.unstagedChanges} unstaged, ${stats.untrackedFiles} untracked${stats.stagedChanges > 0 ? ` (${stats.stagedChanges} staged excluded)` : ''}`);
+    logger.success(`Diff refreshed (scope ${scopeStart}–${scopeEnd}): ${stats.trackedChanges || 0} file(s)`);
 
     res.json({
       success: true,
       message: 'Diff refreshed successfully',
-      sessionChanged,
-      newSessionId: sessionChanged ? newSessionId : null,
-      newHeadSha: sessionChanged ? currentHeadSha : null,
-      originalHeadSha: originalHeadSha,
+      headShaChanged,
+      previousHeadSha: originalHeadSha,
+      currentHeadSha: currentHeadSha || null,
       stats: {
         trackedChanges: stats.trackedChanges || 0,
         untrackedFiles: stats.untrackedFiles || 0,
@@ -1038,6 +1415,272 @@ router.post('/api/local/:reviewId/refresh', async (req, res) => {
   }
 });
 
+/**
+ * Resolve a HEAD SHA change on a non-branch-scoped review.
+ * Called by the frontend after the user chooses how to handle a detected HEAD change.
+ *
+ * action: 'update'      — keep the current session, update its SHA, recompute diff
+ * action: 'new-session'  — create a fresh session for the new HEAD, return its ID
+ */
+router.post('/api/local/:reviewId/resolve-head-change', async (req, res) => {
+  try {
+    const reviewId = parseInt(req.params.reviewId);
+    if (isNaN(reviewId) || reviewId <= 0) {
+      return res.status(400).json({ error: 'Invalid review ID' });
+    }
+
+    const { action, newHeadSha } = req.body || {};
+    if (!action || !['update', 'new-session'].includes(action)) {
+      return res.status(400).json({ error: 'action must be "update" or "new-session"' });
+    }
+    if (!newHeadSha || typeof newHeadSha !== 'string') {
+      return res.status(400).json({ error: 'newHeadSha is required' });
+    }
+
+    const db = req.app.get('db');
+    const reviewRepo = new ReviewRepository(db);
+    const review = await reviewRepo.getLocalReviewById(reviewId);
+    if (!review) {
+      return res.status(404).json({ error: `Local review #${reviewId} not found` });
+    }
+
+    const localPath = review.local_path;
+    if (!localPath) {
+      return res.status(400).json({ error: 'Local review is missing path information' });
+    }
+
+    const scopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
+    const scopeEnd = review.local_scope_end || DEFAULT_SCOPE.end;
+
+    if (action === 'update') {
+      // Check for UNIQUE conflict before updating
+      const headBranch = review.local_head_branch || null;
+      const conflict = await reviewRepo.getLocalReview(localPath, newHeadSha, headBranch);
+      if (conflict && conflict.id !== reviewId) {
+        logger.log('API', `UNIQUE conflict: session #${conflict.id} already exists for this HEAD`, 'yellow');
+        return res.json({ success: true, action: 'redirect', sessionId: conflict.id });
+      }
+
+      // Update SHA
+      await reviewRepo.updateLocalHeadSha(reviewId, newHeadSha);
+      logger.log('API', `Updated HEAD SHA on session ${reviewId}`, 'cyan');
+
+      // Recompute and persist diff
+      const scopedResult = await generateScopedDiff(localPath, scopeStart, scopeEnd, review.local_base_branch);
+      const digest = await computeScopedDigest(localPath, scopeStart, scopeEnd);
+      setLocalReviewDiff(reviewId, { diff: scopedResult.diff, stats: scopedResult.stats, digest });
+      try {
+        await reviewRepo.saveLocalDiff(reviewId, { diff: scopedResult.diff, stats: scopedResult.stats, digest });
+      } catch (persistError) {
+        logger.warn(`Could not persist diff to database: ${persistError.message}`);
+      }
+
+      return res.json({ success: true, action: 'updated' });
+    }
+
+    // action === 'new-session'
+    let branch;
+    try { branch = await getCurrentBranch(localPath); } catch (_) { /* non-fatal */ }
+    const repository = await getRepositoryName(localPath);
+
+    // Check for an existing session at the new HEAD
+    const existing = await reviewRepo.findLocalReview(localPath, newHeadSha, branch);
+    if (existing) {
+      logger.log('API', `Existing session found for new HEAD: ${existing.id}`, 'cyan');
+      return res.json({ success: true, action: 'new-session', newSessionId: existing.id });
+    }
+
+    const newSessionId = await reviewRepo.upsertLocalReview({
+      localPath,
+      localHeadSha: newHeadSha,
+      repository,
+      scopeStart,
+      scopeEnd,
+      localHeadBranch: branch
+    });
+    logger.log('API', `Created new session for new HEAD: ${newSessionId}`, 'cyan');
+
+    // Compute and persist diff so the new session is immediately usable
+    const newScopeResult = await generateScopedDiff(localPath, scopeStart, scopeEnd, review.local_base_branch);
+    const newDigest = await computeScopedDigest(localPath, scopeStart, scopeEnd);
+    setLocalReviewDiff(newSessionId, { diff: newScopeResult.diff, stats: newScopeResult.stats, digest: newDigest });
+    try {
+      await reviewRepo.saveLocalDiff(newSessionId, { diff: newScopeResult.diff, stats: newScopeResult.stats, digest: newDigest });
+    } catch (persistError) {
+      logger.warn(`Could not persist diff for new session: ${persistError.message}`);
+    }
+
+    return res.json({ success: true, action: 'new-session', newSessionId });
+
+  } catch (error) {
+    logger.error('Error resolving head change:', error);
+    res.status(500).json({ error: 'Failed to resolve head change: ' + error.message });
+  }
+});
+
+/**
+ * Set the scope range for a local review.
+ * Validates scope, detects baseBranch if needed, regenerates diff.
+ */
+router.post('/api/local/:reviewId/set-scope', async (req, res) => {
+  try {
+    const reviewId = parseInt(req.params.reviewId);
+
+    if (isNaN(reviewId) || reviewId <= 0) {
+      return res.status(400).json({ error: 'Invalid review ID' });
+    }
+
+    const { scopeStart, scopeEnd, baseBranch: requestBaseBranch } = req.body || {};
+
+    if (!scopeStart || !scopeEnd) {
+      return res.status(400).json({ error: 'scopeStart and scopeEnd are required' });
+    }
+
+    if (!isValidScope(scopeStart, scopeEnd)) {
+      return res.status(400).json({ error: `Invalid scope range: ${scopeStart}–${scopeEnd}` });
+    }
+
+    const db = req.app.get('db');
+    const reviewRepo = new ReviewRepository(db);
+    const review = await reviewRepo.getLocalReviewById(reviewId);
+
+    if (!review) {
+      return res.status(404).json({ error: `Local review #${reviewId} not found` });
+    }
+
+    const localPath = review.local_path;
+    if (!localPath) {
+      return res.status(400).json({ error: 'Local review is missing path information' });
+    }
+
+    // When branch is in scope, resolve baseBranch and current branch
+    let baseBranch = requestBaseBranch || null;
+    let currentBranch = null;
+    if (includesBranch(scopeStart)) {
+      currentBranch = await getCurrentBranch(localPath);
+      if (!baseBranch) {
+        const { detectBaseBranch } = require('../git/base-branch');
+        const config = req.app.get('config') || {};
+        const token = getGitHubToken(config);
+        const detection = await detectBaseBranch(localPath, currentBranch, {
+          repository: review.repository,
+          enableGraphite: config.enable_graphite === true,
+          _deps: token ? { getGitHubToken: () => token } : undefined
+        });
+        if (!detection) {
+          return res.status(400).json({ error: 'Could not detect base branch' });
+        }
+        baseBranch = detection.baseBranch;
+      }
+
+      // Validate branch name to prevent shell injection
+      if (!/^[\w.\-/]+$/.test(baseBranch)) {
+        return res.status(400).json({ error: 'Invalid branch name' });
+      }
+    }
+
+    logger.log('API', `Setting scope on review #${reviewId}: ${scopeStart}–${scopeEnd}${baseBranch ? ` (base: ${baseBranch})` : ''}`, 'cyan');
+
+    // Generate diff for the new scope
+    const { diff, stats, mergeBaseSha } = await generateScopedDiff(localPath, scopeStart, scopeEnd, baseBranch);
+
+    // Get the HEAD SHA for staleness tracking
+    const { getHeadSha } = require('../local-review');
+    const headSha = await getHeadSha(localPath);
+
+    // Update the review record with new scope (headBranch stored on branch scope, cleared otherwise)
+    await reviewRepo.updateLocalScope(reviewId, scopeStart, scopeEnd, baseBranch, currentBranch);
+    await reviewRepo.updateLocalHeadSha(reviewId, headSha);
+
+    // Auto-name review from first commit subject when branch is newly in scope
+    const oldScopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
+    if (!review.name && includesBranch(scopeStart) && !includesBranch(oldScopeStart) && baseBranch) {
+      const firstSubject = await getFirstCommitSubject(localPath, baseBranch);
+      if (firstSubject) {
+        await reviewRepo.updateReview(reviewId, { name: firstSubject.slice(0, 200) });
+      }
+    }
+
+    // Compute digest
+    const digest = await computeScopedDigest(localPath, scopeStart, scopeEnd);
+
+    // Store diff in cache and DB
+    setLocalReviewDiff(reviewId, { diff, stats, digest });
+    await reviewRepo.saveLocalDiff(reviewId, { diff, stats, digest });
+
+    logger.success(`Review #${reviewId} scope set to ${scopeStart}–${scopeEnd}: ${stats.trackedChanges || 0} file(s) changed`);
+
+    res.json({
+      success: true,
+      scopeStart,
+      scopeEnd,
+      localMode: includesBranch(scopeStart) ? 'branch' : 'uncommitted',
+      baseBranch,
+      mergeBaseSha,
+      stats: {
+        trackedChanges: stats.trackedChanges || 0,
+        untrackedFiles: stats.untrackedFiles || 0,
+        stagedChanges: stats.stagedChanges || 0,
+        unstagedChanges: stats.unstagedChanges || 0
+      }
+    });
+
+  } catch (error) {
+    logger.error(`Error setting scope: ${error.message}`);
+    res.status(500).json({ error: 'Failed to set scope: ' + error.message });
+  }
+});
+
+/**
+ * Save "don't ask again" preference for branch review
+ */
+router.post('/api/local/:reviewId/branch-review-preference', async (req, res) => {
+  try {
+    const reviewId = parseInt(req.params.reviewId);
+
+    if (isNaN(reviewId) || reviewId <= 0) {
+      return res.status(400).json({ error: 'Invalid review ID' });
+    }
+
+    const { preference } = req.body || {};
+    if (![0, 1, -1].includes(preference)) {
+      return res.status(400).json({ error: 'Invalid preference value. Must be 0, 1, or -1.' });
+    }
+
+    const db = req.app.get('db');
+    const reviewRepo = new ReviewRepository(db);
+    const review = await reviewRepo.getLocalReviewById(reviewId);
+
+    if (!review) {
+      return res.status(404).json({ error: `Local review #${reviewId} not found` });
+    }
+
+    const repository = review.repository;
+    if (!repository || !repository.includes('/')) {
+      return res.status(400).json({ error: 'Cannot save preference: no repository identified' });
+    }
+
+    const repoSettingsRepo = new RepoSettingsRepository(db);
+    const existing = await repoSettingsRepo.getRepoSettings(repository);
+
+    if (existing) {
+      await run(db, `
+        UPDATE repo_settings SET auto_branch_review = ?, updated_at = ? WHERE repository = ? COLLATE NOCASE
+      `, [preference, new Date().toISOString(), repository]);
+    } else {
+      await run(db, `
+        INSERT INTO repo_settings (repository, auto_branch_review, created_at, updated_at) VALUES (?, ?, ?, ?)
+      `, [repository, preference, new Date().toISOString(), new Date().toISOString()]);
+    }
+
+    res.json({ success: true, preference });
+
+  } catch (error) {
+    logger.error(`Error saving branch review preference: ${error.message}`);
+    res.status(500).json({ error: 'Failed to save preference' });
+  }
+});
+
 /**
  * Get review settings for a local review
  * Returns the custom_instructions from the review record
@@ -1180,21 +1823,39 @@ router.post('/api/local/:reviewId/analyses/council', async (req, res) => {
 
     const localPath = review.local_path;
 
+    const councilScopeStart = review.local_scope_start || DEFAULT_SCOPE.start;
+    const councilScopeEnd = review.local_scope_end || DEFAULT_SCOPE.end;
+    const councilHasBranch = includesBranch(councilScopeStart);
+
+    // Compute merge-base when branch is in scope
+    let analysisBaseSha = review.local_head_sha;
+    if (councilHasBranch && review.local_base_branch) {
+      try {
+        analysisBaseSha = await findMergeBase(localPath, review.local_base_branch);
+      } catch {
+        // Fall back to HEAD
+      }
+    }
+
     const prMetadata = {
       reviewType: 'local',
       repository: review.repository,
-      title: review.name || 'Local changes',
+      title: review.name || (councilHasBranch ? `Branch changes: ${review.local_base_branch}..HEAD` : 'Local changes'),
       description: '',
+      base_sha: analysisBaseSha,
       head_sha: review.local_head_sha
     };
 
     const analyzer = new Analyzer(db, 'council', 'council');
-    const changedFiles = await analyzer.getLocalChangedFiles(localPath);
+    const councilHasStaged = scopeIncludes(councilScopeStart, councilScopeEnd, 'staged');
+    const changedFiles = councilHasBranch
+      ? null
+      : await analyzer.getLocalChangedFiles(localPath, { includeStaged: councilHasStaged });
 
     // Generate and cache diff
     try {
-      const diffResult = await generateLocalDiff(localPath);
-      const digest = await computeLocalDiffDigest(localPath);
+      const diffResult = await generateScopedDiff(localPath, councilScopeStart, councilScopeEnd, review.local_base_branch);
+      const digest = await computeScopedDigest(localPath, councilScopeStart, councilScopeEnd);
       setLocalReviewDiff(reviewId, { diff: diffResult.diff, stats: diffResult.stats, digest });
     } catch (diffError) {
       logger.warn(`Could not generate diff for local council review ${reviewId}: ${diffError.message}`);
@@ -1226,7 +1887,12 @@ router.post('/api/local/:reviewId/analyses/council', async (req, res) => {
         headSha: review.local_head_sha,
         logLabel: `local review #${reviewId}`,
         initialStatusExtra: { reviewId, reviewType: 'local' },
-        runUpdateExtra: { filesAnalyzed: changedFiles.length }
+        config: req.app.get('config') || {},
+        hookContext: {
+          mode: 'local',
+          localContext: { path: localPath, branch: review.local_head_branch, headSha: review.local_head_sha },
+        },
+        runUpdateExtra: { filesAnalyzed: changedFiles ? changedFiles.length : 0 }
       },
       councilConfig,
       councilId,