@in-the-loop-labs/pair-review 3.1.3 → 3.2.0

package/src/git/worktree.js

@@ -30,6 +30,15 @@ class GitWorktreeManager {
     this.worktreeRepo = db ? new WorktreeRepository(db) : null;
   }
 
+  /**
+   * Create a simple-git instance for a path. Extracted for testability.
+   * @param {string} dirPath
+   * @returns {import('simple-git').SimpleGit}
+   */
+  _gitFor(dirPath) {
+    return simpleGit(dirPath);
+  }
+
   /**
    * Apply the name template to generate a worktree directory name
    * @param {Object} context - Template context variables
@@ -902,6 +911,61 @@ class GitWorktreeManager {
     }
   }
 
+  /**
+   * Checkout a different PR branch in an existing worktree.
+   *
+   * Used by stack analysis to switch the shared worktree between PRs.
+   * Stores a persistent ref (refs/remotes/<remote>/pr-<N>) instead of
+   * overwriting FETCH_HEAD, so multiple PR heads can coexist.
+   *
+   * @param {string} worktreePath - Absolute path to the worktree
+   * @param {number} prNumber - PR number to checkout
+   * @param {Object} [options={}]
+   * @param {string} [options.remote='origin'] - Git remote name (overridden by resolveRemoteForPR if prData provided)
+   * @param {Object} [options.prData=null] - PR data from GitHub API (for fork remote resolution)
+   * @param {Object} [options.prInfo=null] - PR info { owner, repo, number } (for fork remote resolution)
+   * @returns {Promise<string>} The HEAD SHA after checkout
+   * @throws {Error} If the worktree has uncommitted changes
+   */
+  async checkoutBranch(worktreePath, prNumber, options = {}) {
+    const { remote: defaultRemote = 'origin', prData = null, prInfo = null } = options;
+
+    try {
+      // 1. Reject if worktree has uncommitted changes
+      const hasChanges = await this.hasLocalChanges(worktreePath);
+      if (hasChanges) {
+        throw new Error(`Worktree has uncommitted changes. Cannot checkout PR #${prNumber} at: ${worktreePath}`);
+      }
+
+      const git = this._gitFor(worktreePath);
+
+      // 2. Resolve the correct remote (handles fork PRs)
+      const remote = (prData || prInfo)
+        ? await this.resolveRemoteForPR(git, prData, prInfo)
+        : defaultRemote;
+
+      // 3. Fetch PR head into a persistent ref
+      console.log(`Fetching PR #${prNumber} head from ${remote} into refs/remotes/${remote}/pr-${prNumber}...`);
+      await git.fetch([remote, `+refs/pull/${prNumber}/head:refs/remotes/${remote}/pr-${prNumber}`]);
+
+      // 4. Reset worktree to the fetched ref
+      console.log(`Resetting worktree to refs/remotes/${remote}/pr-${prNumber}...`);
+      await git.raw(['reset', '--hard', `refs/remotes/${remote}/pr-${prNumber}`]);
+
+      // 5. Return the new HEAD SHA
+      const headSha = (await git.revparse(['HEAD'])).trim();
+      console.log(`Worktree checked out PR #${prNumber} at ${headSha}`);
+      return headSha;
+
+    } catch (error) {
+      if (error.message.includes('uncommitted changes')) {
+        throw error;
+      }
+      console.error(`Error checking out PR #${prNumber}:`, error);
+      throw new Error(`Failed to checkout PR #${prNumber}: ${error.message}`);
+    }
+  }
+
   /**
    * Cleanup stale worktrees that haven't been accessed within the retention period
    * @param {number} retentionDays - Number of days to retain worktrees (default: 7)

package/src/github/stack-walker.js

@@ -0,0 +1,196 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+const logger = require('../utils/logger');
+
+const DEFAULT_TRUNK_BRANCHES = ['main', 'master', 'develop'];
+const MAX_WALK_DEPTH = 20;
+
+const FETCH_PR_QUERY = `
+  query($owner: String!, $repo: String!, $number: Int!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequest(number: $number) {
+        number title baseRefName headRefName headRefOid state url
+      }
+    }
+  }
+`;
+
+const FIND_PRS_BY_HEAD_QUERY = `
+  query($owner: String!, $repo: String!, $branch: String!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequests(headRefName: $branch, states: [OPEN, MERGED], first: 5, orderBy: {field: UPDATED_AT, direction: DESC}) {
+        nodes { number title baseRefName headRefName headRefOid state url }
+      }
+    }
+  }
+`;
+
+const FIND_PRS_BY_BASE_QUERY = `
+  query($owner: String!, $repo: String!, $branch: String!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequests(baseRefName: $branch, states: [OPEN], first: 5, orderBy: {field: UPDATED_AT, direction: DESC}) {
+        nodes { number title baseRefName headRefName headRefOid state url }
+      }
+    }
+  }
+`;
+
+/**
+ * Select the best PR from a list of candidates for the same branch.
+ * Prefers OPEN over MERGED.
+ *
+ * @param {Array} prs - Array of PR nodes from GraphQL
+ * @returns {Object|null} The best candidate or null
+ */
+function pickBestPR(prs) {
+  if (!prs || prs.length === 0) return null;
+  const open = prs.find(pr => pr.state === 'OPEN');
+  if (open) return open;
+  return prs[0];
+}
+
+/**
+ * Walk a GitHub PR stack by following the branch chain via GraphQL.
+ *
+ * Starting from a given PR, walks up toward trunk (following baseRefName)
+ * and down toward the tip (following headRefName) to discover the full stack.
+ *
+ * @param {Object} client - GitHubClient instance (uses client.octokit.graphql)
+ * @param {string} owner - Repository owner
+ * @param {string} repo - Repository name
+ * @param {number} prNumber - Starting PR number
+ * @param {Object} [_deps] - Optional dependency overrides for testing
+ * @param {string[]} [_deps.defaultBranches] - Branch names considered trunk
+ * @returns {Promise<Array>} Ordered stack from trunk to tip
+ */
+async function walkPRStack(client, owner, repo, prNumber, _deps) {
+  const deps = { defaultBranches: DEFAULT_TRUNK_BRANCHES, ..._deps };
+  const graphql = client.octokit.graphql.bind(client.octokit);
+  const visited = new Set();
+
+  // Step 1: Fetch the starting PR
+  const startResult = await graphql(FETCH_PR_QUERY, { owner, repo, number: prNumber });
+  const startPR = startResult.repository?.pullRequest;
+  if (!startPR) {
+    throw new Error(`PR #${prNumber} not found in ${owner}/${repo}`);
+  }
+
+  logger.debug(`Stack walker: starting from PR #${startPR.number} (${startPR.headRefName} -> ${startPR.baseRefName})`);
+  visited.add(startPR.headRefName);
+
+  // Step 2: Walk UP toward trunk
+  const parents = []; // will be reversed at the end
+  let currentBase = startPR.baseRefName;
+  let walkUpDepth = 0;
+
+  while (walkUpDepth < MAX_WALK_DEPTH) {
+    if (deps.defaultBranches.includes(currentBase)) {
+      // Reached trunk
+      break;
+    }
+    if (visited.has(currentBase)) {
+      logger.warn(`Stack walker: cycle detected at branch "${currentBase}", stopping upward walk`);
+      break;
+    }
+    visited.add(currentBase);
+
+    let parentPR;
+    try {
+      const result = await graphql(FIND_PRS_BY_HEAD_QUERY, { owner, repo, branch: currentBase });
+      const candidates = result.repository?.pullRequests?.nodes || [];
+      parentPR = pickBestPR(candidates);
+    } catch (err) {
+      logger.warn(`Stack walker: GraphQL error walking up at branch "${currentBase}": ${err.message}`);
+      break;
+    }
+
+    if (!parentPR) {
+      // No parent PR found — currentBase is effectively trunk for this stack
+      break;
+    }
+
+    parents.push({
+      branch: parentPR.headRefName,
+      isTrunk: false,
+      prNumber: parentPR.number,
+      title: parentPR.title,
+      state: parentPR.state,
+      url: parentPR.url,
+      headSha: parentPR.headRefOid,
+    });
+
+    currentBase = parentPR.baseRefName;
+    walkUpDepth++;
+  }
+
+  if (walkUpDepth >= MAX_WALK_DEPTH) {
+    logger.warn(`Stack walker: upward walk reached max depth of ${MAX_WALK_DEPTH}`);
+  }
+
+  // The trunk entry is whatever branch the topmost PR targets
+  const trunkBranch = currentBase;
+
+  // Step 3: Walk DOWN toward tip
+  const children = [];
+  let currentHead = startPR.headRefName;
+  let walkDownDepth = 0;
+
+  while (walkDownDepth < MAX_WALK_DEPTH) {
+    let childPR;
+    try {
+      const result = await graphql(FIND_PRS_BY_BASE_QUERY, { owner, repo, branch: currentHead });
+      const candidates = result.repository?.pullRequests?.nodes || [];
+      childPR = pickBestPR(candidates);
+    } catch (err) {
+      logger.warn(`Stack walker: GraphQL error walking down at branch "${currentHead}": ${err.message}`);
+      break;
+    }
+
+    if (!childPR) {
+      break;
+    }
+
+    if (visited.has(childPR.headRefName)) {
+      logger.warn(`Stack walker: cycle detected at branch "${childPR.headRefName}", stopping downward walk`);
+      break;
+    }
+    visited.add(childPR.headRefName);
+
+    children.push({
+      branch: childPR.headRefName,
+      isTrunk: false,
+      prNumber: childPR.number,
+      title: childPR.title,
+      state: childPR.state,
+      url: childPR.url,
+      headSha: childPR.headRefOid,
+    });
+
+    currentHead = childPR.headRefName;
+    walkDownDepth++;
+  }
+
+  if (walkDownDepth >= MAX_WALK_DEPTH) {
+    logger.warn(`Stack walker: downward walk reached max depth of ${MAX_WALK_DEPTH}`);
+  }
+
+  // Step 4: Assemble the ordered stack (trunk -> ... -> parents -> start -> children -> ... -> tip)
+  const stack = [
+    { branch: trunkBranch, isTrunk: true },
+    ...parents.reverse(),
+    {
+      branch: startPR.headRefName,
+      isTrunk: false,
+      prNumber: startPR.number,
+      title: startPR.title,
+      state: startPR.state,
+      url: startPR.url,
+      headSha: startPR.headRefOid,
+    },
+    ...children,
+  ];
+
+  logger.debug(`Stack walker: found ${stack.length} entries (${stack.filter(e => !e.isTrunk).length} PRs)`);
+  return stack;
+}
+
+module.exports = { walkPRStack, DEFAULT_TRUNK_BRANCHES };

package/src/routes/local.js

@@ -16,7 +16,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');
+const { query, queryOne, run, ReviewRepository, RepoSettingsRepository, AnalysisRunRepository, CouncilRepository } = require('../database');
 const Analyzer = require('../ai/analyzer');
 const { v4: uuidv4 } = require('uuid');
 const logger = require('../utils/logger');
@@ -32,8 +32,7 @@ const { getShaAbbrevLength } = require('../git/sha-abbrev');
 const { validateCouncilConfig, normalizeCouncilConfig } = require('./councils');
 const { TIERS, TIER_ALIASES, VALID_TIERS, resolveTier } = require('../ai/prompts/config');
 const { getProviderClass, createProvider } = require('../ai/provider');
-const { readFileSync } = require('fs');
-const { getDefaultBranch, tryGraphiteState, readGraphitePRInfo, enrichStackWithPRInfo } = require('../git/base-branch');
+const { getDefaultBranch, tryGraphiteState } = require('../git/base-branch');
 const { CommentRepository } = require('../database');
 const { runExecutableAnalysis, getChangedFiles } = require('./executable-analysis');
 const {
@@ -630,12 +629,17 @@ router.get('/api/local/:reviewId', async (req, res) => {
     const localConfig = req.app.get('config') || {};
     if (localConfig.enable_graphite === true && review.local_path && branchName && branchName !== 'unknown' && branchName !== 'HEAD') {
       try {
-        const graphiteResult = tryGraphiteState(review.local_path, branchName, { execSync, readFileSync });
+        const graphiteResult = tryGraphiteState(review.local_path, branchName, { execSync });
         if (graphiteResult?.stack) {
-          const prInfo = readGraphitePRInfo(review.local_path, { execSync, readFileSync });
-          stackData = prInfo?.prInfos
-            ? enrichStackWithPRInfo(graphiteResult.stack, prInfo.prInfos)
-            : graphiteResult.stack;
+          // Enrich with PR numbers from pr_metadata DB
+          const allPRs = repositoryName
+            ? await query(db, 'SELECT pr_number, head_branch FROM pr_metadata WHERE repository = ? COLLATE NOCASE', [repositoryName])
+            : [];
+          const prMap = new Map(allPRs.filter(p => p.head_branch).map(p => [p.head_branch, p.pr_number]));
+          stackData = graphiteResult.stack.map(entry => {
+            const prNumber = prMap.get(entry.branch);
+            return prNumber != null ? { ...entry, prNumber } : entry;
+          });
         }
       } catch {
         // Non-fatal — stack detection is an enhancement

package/src/routes/pr.js

@@ -32,10 +32,8 @@ const { broadcastReviewEvent } = require('../events/review-events');
 const { fireHooks, hasHooks } = require('../hooks/hook-runner');
 const { buildReviewStartedPayload, buildReviewLoadedPayload, buildAnalysisStartedPayload, buildAnalysisCompletedPayload, getCachedUser } = require('../hooks/payloads');
 const simpleGit = require('simple-git');
-const { execSync } = require('child_process');
-const { readFileSync } = require('fs');
 const { GIT_DIFF_FLAGS_ARRAY, GIT_DIFF_SUMMARY_FLAGS_ARRAY } = require('../git/diff-flags');
-const { tryGraphiteState, readGraphitePRInfo, enrichStackWithPRInfo } = require('../git/base-branch');
+const { walkPRStack, DEFAULT_TRUNK_BRANCHES } = require('../github/stack-walker');
 const {
   activeAnalyses,
   reviewToAnalysisId,
@@ -53,7 +51,7 @@ const { getProviderClass, createProvider } = require('../ai/provider');
 const { CommentRepository } = require('../database');
 const { runExecutableAnalysis } = require('./executable-analysis');
 const analysesRouter = require('./analyses');
-
+const { worktreeLock } = require('../git/worktree-lock');
 const router = express.Router();
 
 /**
@@ -236,21 +234,20 @@ router.get('/api/pr/:owner/:repo/:number', async (req, res) => {
       ? getShaAbbrevLength(extendedData.worktree_path)
       : DEFAULT_SHA_ABBREV_LENGTH;
 
-    // Detect Graphite stack if enabled
+    // Detect PR stack via GitHub GraphQL chain-walking
     let stackData = null;
     {
       const stackConfig = req.app.get('config') || {};
-      if (stackConfig.enable_graphite === true && extendedData.worktree_path && prMetadata.head_branch) {
+      const githubToken = getGitHubToken(stackConfig) || req.app.get('githubToken');
+      if (githubToken) {
         try {
-          const graphiteResult = tryGraphiteState(extendedData.worktree_path, prMetadata.head_branch, { execSync, readFileSync });
-          if (graphiteResult?.stack) {
-            const prInfo = readGraphitePRInfo(extendedData.worktree_path, { execSync, readFileSync });
-            stackData = prInfo?.prInfos
-              ? enrichStackWithPRInfo(graphiteResult.stack, prInfo.prInfos)
-              : graphiteResult.stack;
-          }
-        } catch {
-          // Non-fatal — stack detection is an enhancement
+          const ghClient = new GitHubClient(githubToken);
+          const defaultBranch = extendedData.repository?.default_branch;
+          stackData = await walkPRStack(ghClient, repoOwner, repoName, prNumber, {
+            defaultBranches: [defaultBranch, ...DEFAULT_TRUNK_BRANCHES].filter(Boolean)
+          });
+        } catch (stackError) {
+          logger.debug('Failed to walk PR stack:', stackError.message);
         }
       }
     }
@@ -356,6 +353,20 @@ router.post('/api/pr/:owner/:repo/:number/refresh', async (req, res) => {
     if (!githubToken) {
       return res.status(401).json({ error: 'GitHub token not configured' });
     }
+
+    // Check if worktree is locked before modifying it
+    const worktreeManagerForLock = new GitWorktreeManager(db);
+    const existingWorktreePath = await worktreeManagerForLock.getWorktreePath({ owner, repo, number: prNumber });
+    if (existingWorktreePath) {
+      const lockState = worktreeLock.isLocked(existingWorktreePath);
+      if (lockState.locked) {
+        return res.status(409).json({
+          error: 'Worktree is in use by stack analysis',
+          holderId: lockState.holderId
+        });
+      }
+    }
+
     const githubClient = new GitHubClient(githubToken);
     const prData = await githubClient.fetchPullRequest(owner, repo, prNumber);
 
@@ -433,19 +444,20 @@ router.post('/api/pr/:owner/:repo/:number/refresh', async (req, res) => {
     const parsedData = prMetadata.pr_data ? JSON.parse(prMetadata.pr_data) : {};
     const [repoOwner, repoName] = repository.split('/');
 
-    // Detect Graphite stack if enabled
+    // Refresh stack data via GitHub GraphQL
     let stackData = null;
-    if (config.enable_graphite === true && worktreePath && prData.head_branch) {
-      try {
-        const graphiteResult = tryGraphiteState(worktreePath, prData.head_branch, { execSync, readFileSync });
-        if (graphiteResult?.stack) {
-          const prInfo = readGraphitePRInfo(worktreePath, { execSync, readFileSync });
-          stackData = prInfo?.prInfos
-            ? enrichStackWithPRInfo(graphiteResult.stack, prInfo.prInfos)
-            : graphiteResult.stack;
+    {
+      const githubToken = getGitHubToken(config) || req.app.get('githubToken');
+      if (githubToken) {
+        try {
+          const ghClient = new GitHubClient(githubToken);
+          const defaultBranch = prData.repository?.default_branch;
+          stackData = await walkPRStack(ghClient, ...repository.split('/'), prNumber, {
+            defaultBranches: [defaultBranch, ...DEFAULT_TRUNK_BRANCHES].filter(Boolean)
+          });
+        } catch (stackError) {
+          logger.debug('Failed to walk PR stack on refresh:', stackError.message);
         }
-      } catch {
-        // Non-fatal — stack detection is an enhancement
       }
     }
 
@@ -1619,6 +1631,17 @@ router.post('/api/pr/:owner/:repo/:number/analyses', async (req, res) => {
       });
     }
 
+    // Reject if worktree is locked by another operation (e.g. stack analysis)
+    if (worktreePath) {
+      const lockState = worktreeLock.isLocked(worktreePath);
+      if (lockState.locked) {
+        return res.status(409).json({
+          error: 'Worktree is in use by stack analysis',
+          holderId: lockState.holderId
+        });
+      }
+    }
+
     const appConfig = req.app.get('config') || {};
     const globalInstructions = appConfig.globalInstructions || null;
 
@@ -2210,4 +2233,94 @@ router.get('/api/pr/:owner/:repo/:number/share', async (req, res) => {
   }
 });
 
+/**
+ * Get enriched stack info for a PR stack via GitHub GraphQL chain-walking.
+ * Returns all branches in the stack with PR numbers, titles, analysis status,
+ * and worktree ownership — used by the stack selection dialog.
+ */
+router.get('/api/pr/:owner/:repo/:number/stack-info', async (req, res) => {
+  try {
+    const { owner, repo, number } = req.params;
+    const prNumber = parseInt(number);
+
+    if (isNaN(prNumber) || prNumber <= 0) {
+      return res.status(400).json({ error: 'Invalid pull request number' });
+    }
+
+    const repository = normalizeRepository(owner, repo);
+    const db = req.app.get('db');
+    const config = req.app.get('config') || {};
+
+    const githubToken = getGitHubToken(config) || req.app.get('githubToken');
+    if (!githubToken) {
+      return res.json({ stack: [] });
+    }
+
+    // Look up pr_data to extract default_branch for stack walking
+    const prMetadataRow = await queryOne(db, `
+      SELECT pr_data FROM pr_metadata
+      WHERE pr_number = ? AND repository = ? COLLATE NOCASE
+    `, [prNumber, repository]);
+    const parsedPrData = prMetadataRow?.pr_data ? JSON.parse(prMetadataRow.pr_data) : {};
+    const defaultBranch = parsedPrData.repository?.default_branch;
+
+    const ghClient = new GitHubClient(githubToken);
+    let stack;
+    try {
+      stack = await walkPRStack(ghClient, ...repository.split('/'), prNumber, {
+        defaultBranches: [defaultBranch, ...DEFAULT_TRUNK_BRANCHES].filter(Boolean)
+      });
+    } catch (walkError) {
+      logger.debug('Failed to walk PR stack for stack-info:', walkError.message);
+      return res.json({ stack: [] });
+    }
+    if (!stack) {
+      return res.json({ stack: [] });
+    }
+
+    // For each non-trunk entry with a PR number, look up analysis status and worktree
+    const enrichedStack = [];
+    const worktreeRepo = new WorktreeRepository(db);
+    const analysisRunRepo = new AnalysisRunRepository(db);
+    const reviewRepo = new ReviewRepository(db);
+
+    for (const entry of stack) {
+      if (entry.isTrunk) {
+        enrichedStack.push(entry);
+        continue;
+      }
+
+      const enriched = { ...entry };
+
+      if (entry.prNumber) {
+        enriched.title = entry.title || null;
+
+        // Check if there's an analysis run matching the current head SHA
+        const review = await reviewRepo.getReviewByPR(entry.prNumber, repository);
+        if (review) {
+          const latestRun = await analysisRunRepo.getLatestCompletedByReviewId(review.id);
+          enriched.hasAnalysis = latestRun?.head_sha === enriched.headSha;
+        } else {
+          enriched.hasAnalysis = false;
+        }
+
+        // Check if it has its own worktree
+        const wt = await worktreeRepo.findByPR(entry.prNumber, repository);
+        enriched.hasOwnWorktree = wt != null;
+      } else {
+        enriched.title = null;
+        enriched.hasAnalysis = false;
+        enriched.hasOwnWorktree = false;
+      }
+
+      enrichedStack.push(enriched);
+    }
+
+    res.json({ stack: enrichedStack });
+  } catch (error) {
+    logger.error('Error fetching stack info:', error);
+    res.status(500).json({ error: 'Failed to fetch stack info' });
+  }
+});
+
 module.exports = router;

package/src/routes/sound.js

@@ -0,0 +1,49 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+const express = require('express');
+const { execFile } = require('child_process');
+const logger = require('../utils/logger');
+
+// Default dependencies (overridable for testing)
+const defaults = {
+  execFile,
+  logger,
+  platform: process.platform,
+};
+
+/**
+ * Create a Router for the sound playback endpoint.
+ *
+ * Plays a system notification sound on the host machine via a platform-specific
+ * CLI command.  Fire-and-forget: the response is sent immediately and any
+ * playback errors are logged at warn level (sound failure is non-critical).
+ *
+ * @param {object} [_deps] - Dependency overrides for testing
+ * @returns {import('express').Router}
+ */
+function createSoundRouter(_deps = {}) {
+  const { execFile, logger, platform } = { ...defaults, ..._deps };
+  const router = express.Router();
+
+  router.post('/api/play-sound', (req, res) => {
+    if (platform === 'darwin') {
+      execFile('afplay', ['/System/Library/Sounds/Glass.aiff'], (err) => {
+        if (err) logger.warn(`Sound playback failed: ${err.message}`);
+      });
+    } else if (platform === 'linux') {
+      execFile('paplay', ['/usr/share/sounds/freedesktop/stereo/complete.oga'], (err) => {
+        if (err) logger.warn(`Sound playback failed: ${err.message}`);
+      });
+    } else if (platform === 'win32') {
+      execFile('powershell', ['-Command', '[System.Media.SystemSounds]::Asterisk.Play()'], (err) => {
+        if (err) logger.warn(`Sound playback failed: ${err.message}`);
+      });
+    }
+    // Unsupported platforms: silent degradation — no execFile call, still 204.
+
+    res.sendStatus(204);
+  });
+
+  return router;
+}
+
+module.exports = { createSoundRouter };