@in-the-loop-labs/pair-review 2.0.3 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@in-the-loop-labs/pair-review",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "Your AI-powered code review partner - Close the feedback loop with AI coding agents",
   "main": "src/server.js",
   "bin": {

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pair-review",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "pair-review app integration — Open PRs and local changes in the pair-review web UI, run server-side AI analysis, and address review feedback. Requires the pair-review MCP server.",
   "author": {
     "name": "in-the-loop-labs",

package/plugin-code-critic/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "code-critic",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "AI-powered code review analysis — Run three-level AI analysis and implement-review-fix loops directly in your coding agent. Works standalone, no server required.",
   "author": {
     "name": "in-the-loop-labs",

package/src/config.js

@@ -5,6 +5,7 @@ const os = require('os');
 const logger = require('./utils/logger');
 
 const CONFIG_DIR = path.join(os.homedir(), '.pair-review');
+const DEFAULT_CHECKOUT_TIMEOUT_MS = 300000;
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
 const CONFIG_EXAMPLE_FILE = path.join(CONFIG_DIR, 'config.example.json');
 const PACKAGE_ROOT = path.join(__dirname, '..');
@@ -316,6 +317,81 @@ function getMonorepoPath(config, repository) {
   return null;
 }
 
+/**
+ * Gets the configured checkout script for a monorepo repository
+ * @param {Object} config - Configuration object from loadConfig()
+ * @param {string} repository - Repository in "owner/repo" format
+ * @returns {string|null} - Checkout script path or null if not configured
+ */
+function getMonorepoCheckoutScript(config, repository) {
+  const monorepoConfig = config.monorepos?.[repository];
+  return monorepoConfig?.checkout_script || null;
+}
+
+/**
+ * Gets the configured worktree directory for a monorepo repository
+ * @param {Object} config - Configuration object from loadConfig()
+ * @param {string} repository - Repository in "owner/repo" format
+ * @returns {string|null} - Expanded worktree directory path or null if not configured
+ */
+function getMonorepoWorktreeDirectory(config, repository) {
+  const monorepoConfig = config.monorepos?.[repository];
+  if (monorepoConfig?.worktree_directory) {
+    return expandPath(monorepoConfig.worktree_directory);
+  }
+  return null;
+}
+
+/**
+ * Gets the configured worktree name template for a monorepo repository
+ * @param {Object} config - Configuration object from loadConfig()
+ * @param {string} repository - Repository in "owner/repo" format
+ * @returns {string|null} - Template string or null if not configured
+ */
+function getMonorepoWorktreeNameTemplate(config, repository) {
+  const monorepoConfig = config.monorepos?.[repository];
+  return monorepoConfig?.worktree_name_template || null;
+}
+
+/**
+ * Gets the configured checkout script timeout for a monorepo repository
+ * @param {Object} config - Configuration object from loadConfig()
+ * @param {string} repository - Repository in "owner/repo" format
+ * @returns {number} - Timeout in milliseconds (default: 300000 = 5 minutes)
+ */
+function getMonorepoCheckoutTimeout(config, repository) {
+  const monorepoConfig = config.monorepos?.[repository];
+  if (monorepoConfig?.checkout_timeout_seconds > 0) {
+    return monorepoConfig.checkout_timeout_seconds * 1000;
+  }
+  return DEFAULT_CHECKOUT_TIMEOUT_MS; // 5 minutes default
+}
+
+/**
+ * Resolves all monorepo worktree options for a repository into a single object.
+ * Composite helper that combines the individual getters into the shape expected
+ * by GitWorktreeManager and createWorktreeForPR.
+ *
+ * @param {Object} config - Configuration object from loadConfig()
+ * @param {string} repository - Repository in "owner/repo" format
+ * @returns {{ checkoutScript: string|null, checkoutTimeout: number, worktreeConfig: Object|null }}
+ */
+function resolveMonorepoOptions(config, repository) {
+  const checkoutScript = getMonorepoCheckoutScript(config, repository);
+  const checkoutTimeout = getMonorepoCheckoutTimeout(config, repository);
+  const worktreeDirectory = getMonorepoWorktreeDirectory(config, repository);
+  const nameTemplate = getMonorepoWorktreeNameTemplate(config, repository);
+
+  let worktreeConfig = null;
+  if (worktreeDirectory || nameTemplate) {
+    worktreeConfig = {};
+    if (worktreeDirectory) worktreeConfig.worktreeBaseDir = worktreeDirectory;
+    if (nameTemplate) worktreeConfig.nameTemplate = nameTemplate;
+  }
+
+  return { checkoutScript, checkoutTimeout, worktreeConfig };
+}
+
 /**
  * Resolves the database filename to use.
  * Priority:
@@ -358,6 +434,12 @@ module.exports = {
   showWelcomeMessage,
   expandPath,
   getMonorepoPath,
+  getMonorepoCheckoutScript,
+  getMonorepoWorktreeDirectory,
+  getMonorepoWorktreeNameTemplate,
+  getMonorepoCheckoutTimeout,
+  resolveMonorepoOptions,
   resolveDbName,
-  warnIfDevModeWithoutDbName
+  warnIfDevModeWithoutDbName,
+  DEFAULT_CHECKOUT_TIMEOUT_MS
 };

package/src/git/worktree.js

@@ -3,10 +3,11 @@ const simpleGit = require('simple-git');
 const path = require('path');
 const fs = require('fs').promises;
 const os = require('os');
-const { getConfigDir } = require('../config');
+const { getConfigDir, DEFAULT_CHECKOUT_TIMEOUT_MS } = require('../config');
 const { WorktreeRepository, generateWorktreeId } = require('../database');
 const { getGeneratedFilePatterns } = require('./gitattributes');
 const { normalizeRepository, resolveRenamedFile, resolveRenamedFileOld } = require('../utils/paths');
+const { spawn, execSync } = require('child_process');
 
 /**
  * Git worktree manager for handling PR branch checkouts and diffs
@@ -15,13 +16,43 @@ class GitWorktreeManager {
   /**
    * Create a new GitWorktreeManager instance
    * @param {sqlite3.Database} [db] - Optional database instance for worktree tracking
+   * @param {Object} [options] - Optional settings
+   * @param {string} [options.worktreeBaseDir] - Custom base directory for worktrees
+   * @param {string} [options.nameTemplate] - Template for worktree directory names
+   *   Supported variables: {id}, {pr_number}, {repo}, {owner}
+   *   Default: '{id}' (preserves current behavior)
    */
-  constructor(db = null) {
-    this.worktreeBaseDir = path.join(getConfigDir(), 'worktrees');
+  constructor(db = null, options = {}) {
+    this.worktreeBaseDir = options.worktreeBaseDir || path.join(getConfigDir(), 'worktrees');
+    this.nameTemplate = options.nameTemplate || '{id}';
     this.db = db;
     this.worktreeRepo = db ? new WorktreeRepository(db) : null;
   }
 
+  /**
+   * Apply the name template to generate a worktree directory name
+   * @param {Object} context - Template context variables
+   * @param {string} context.id - Random worktree ID
+   * @param {number} [context.prNumber] - PR number
+   * @param {string} [context.repo] - Repository name
+   * @param {string} [context.owner] - Repository owner
+   * @returns {string} Resolved directory name
+   */
+  applyNameTemplate(context) {
+    let name = this.nameTemplate;
+    name = name.replace(/\{id\}/g, context.id);
+    if (context.prNumber !== undefined) {
+      name = name.replace(/\{pr_number\}/g, String(context.prNumber));
+    }
+    if (context.repo) {
+      name = name.replace(/\{repo\}/g, context.repo);
+    }
+    if (context.owner) {
+      name = name.replace(/\{owner\}/g, context.owner);
+    }
+    return name;
+  }
+
   /**
    * Resolve which git remote points to the given repository URLs.
    * Compares normalized URLs against all configured remotes. If no match is
@@ -129,6 +160,65 @@ class GitWorktreeManager {
     return this.resolveRemoteForRepo(git, cloneUrl, sshUrl);
   }
 
+  /**
+   * Execute a user-provided checkout script in the worktree.
+   * The script receives PR context as environment variables and is responsible
+   * for configuring sparse-checkout (or any other worktree setup).
+   *
+   * @param {string} script - Script path or command to execute
+   * @param {string} worktreePath - Path to the worktree (used as cwd)
+   * @param {Object} env - Environment variables to pass (BASE_BRANCH, HEAD_BRANCH, etc.)
+   * @param {number} [timeout=DEFAULT_CHECKOUT_TIMEOUT_MS] - Timeout in milliseconds (default: 5 minutes)
+   * @returns {Promise<{stdout: string, stderr: string}>} Script output
+   */
+  async executeCheckoutScript(script, worktreePath, env, timeout = DEFAULT_CHECKOUT_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+      const child = spawn(script, [], {
+        cwd: worktreePath,
+        shell: true,
+        env: { ...process.env, ...env },
+        stdio: ['ignore', 'pipe', 'pipe']
+      });
+
+      let stdout = '';
+      let stderr = '';
+
+      child.stdout.on('data', (data) => {
+        const chunk = data.toString();
+        stdout += chunk;
+        process.stdout.write(chunk);
+      });
+      child.stderr.on('data', (data) => {
+        const chunk = data.toString();
+        stderr += chunk;
+        process.stderr.write(chunk);
+      });
+
+      const timer = setTimeout(() => {
+        child.kill('SIGTERM');
+        reject(new Error(`Checkout script timed out after ${timeout}ms.\nstdout: ${stdout}\nstderr: ${stderr}`));
+      }, timeout);
+
+      child.on('error', (err) => {
+        clearTimeout(timer);
+        if (err.code === 'ENOENT') {
+          reject(new Error(`Checkout script not found: ${script}`));
+        } else {
+          reject(new Error(`Checkout script failed to start: ${err.message}`));
+        }
+      });
+
+      child.on('close', (code) => {
+        clearTimeout(timer);
+        if (code === 0) {
+          resolve({ stdout, stderr });
+        } else {
+          reject(new Error(`Checkout script exited with code ${code}.\nstdout: ${stdout}\nstderr: ${stderr}`));
+        }
+      });
+    });
+  }
+
   /**
    * Create a git worktree for a PR and checkout to the PR head commit
    * @param {Object} prInfo - PR information { owner, repo, number }
@@ -137,10 +227,14 @@ class GitWorktreeManager {
    * @param {Object} [options] - Optional settings
    * @param {string} [options.worktreeSourcePath] - Path to use as cwd for git worktree add
    *   (to inherit sparse-checkout from an existing worktree). Falls back to repositoryPath.
+   * @param {string} [options.checkoutScript] - Path to a script that configures sparse-checkout in the worktree.
+   *   When set, worktree is created with --no-checkout from the main git root (no sparse-checkout inheritance),
+   *   and the script is executed before checkout with PR context as environment variables.
+   * @param {number} [options.checkoutTimeout] - Timeout in ms for checkout script (default: 300000 = 5 minutes)
    * @returns {Promise<string>} Path to created worktree
    */
   async createWorktreeForPR(prInfo, prData, repositoryPath, options = {}) {
-    const { worktreeSourcePath } = options;
+    const { worktreeSourcePath, checkoutScript, checkoutTimeout } = options;
     // Check if worktree already exists in DB
     const repository = normalizeRepository(prInfo.owner, prInfo.repo);
     let worktreePath;
@@ -157,7 +251,7 @@ class GitWorktreeManager {
       // Check if the directory still exists on disk
       const directoryExists = await this.pathExists(worktreePath);
 
-      if (directoryExists) {
+      if (directoryExists && await this.isValidGitWorktree(worktreePath)) {
         // Try to reuse existing worktree by refreshing it
         console.log(`Found existing worktree for PR #${prInfo.number} at ${worktreePath}`);
         try {
@@ -170,6 +264,8 @@ class GitWorktreeManager {
           // For other errors, log and fall through to recreate
           console.log(`Could not refresh existing worktree, will recreate: ${refreshError.message}`);
         }
+      } else if (directoryExists) {
+        console.log(`Worktree directory at ${worktreePath} is not a valid git worktree, will recreate`);
       } else {
         console.log(`Worktree directory no longer exists at ${worktreePath}, will recreate`);
       }
@@ -207,9 +303,15 @@ class GitWorktreeManager {
         }
       }
 
-      // Generate new random ID for worktree directory
+      // Generate new random ID for worktree directory and apply name template
       const worktreeId = generateWorktreeId();
-      worktreePath = path.join(this.worktreeBaseDir, worktreeId);
+      const worktreeDirName = this.applyNameTemplate({
+        id: worktreeId,
+        prNumber: prInfo.number,
+        repo: prInfo.repo,
+        owner: prInfo.owner
+      });
+      worktreePath = path.join(this.worktreeBaseDir, worktreeDirName);
     }
 
     try {
@@ -243,23 +345,39 @@ class GitWorktreeManager {
         }
       }
       
-      // Create worktree and checkout to base branch
-      // Use worktreeSourcePath as cwd if provided (to inherit sparse-checkout from existing worktree)
-      const worktreeAddGit = worktreeSourcePath ? simpleGit(worktreeSourcePath) : git;
-      if (worktreeSourcePath) {
-        console.log(`Creating worktree at ${worktreePath} from ${prData.base_branch} (inheriting sparse-checkout from ${worktreeSourcePath})...`);
+      // Create worktree — strategy depends on whether a checkout script is configured
+      if (checkoutScript) {
+        // With checkout_script: create worktree with --no-checkout from main git root.
+        // The script will configure sparse-checkout before files are populated.
+        console.log(`Creating worktree at ${worktreePath} from ${prData.base_branch} (--no-checkout, script will configure sparse-checkout)...`);
+        try {
+          await git.raw(['worktree', 'add', '--no-checkout', worktreePath, `${remote}/${prData.base_branch}`]);
+        } catch (worktreeError) {
+          if (worktreeError.message.includes('already registered')) {
+            console.log('Worktree already registered, trying with --force...');
+            await git.raw(['worktree', 'add', '--force', '--no-checkout', worktreePath, `${remote}/${prData.base_branch}`]);
+          } else {
+            throw worktreeError;
+          }
+        }
       } else {
-        console.log(`Creating worktree at ${worktreePath} from ${prData.base_branch}...`);
-      }
-      try {
-        await worktreeAddGit.raw(['worktree', 'add', worktreePath, `${remote}/${prData.base_branch}`]);
-      } catch (worktreeError) {
-        // If worktree creation fails due to existing registration, try with --force
-        if (worktreeError.message.includes('already registered')) {
-          console.log('Worktree already registered, trying with --force...');
-          await worktreeAddGit.raw(['worktree', 'add', '--force', worktreePath, `${remote}/${prData.base_branch}`]);
+        // Without checkout_script: use worktreeSourcePath as cwd if provided
+        // (to inherit sparse-checkout from existing worktree)
+        const worktreeAddGit = worktreeSourcePath ? simpleGit(worktreeSourcePath) : git;
+        if (worktreeSourcePath) {
+          console.log(`Creating worktree at ${worktreePath} from ${prData.base_branch} (inheriting sparse-checkout from ${worktreeSourcePath})...`);
         } else {
-          throw worktreeError;
+          console.log(`Creating worktree at ${worktreePath} from ${prData.base_branch}...`);
+        }
+        try {
+          await worktreeAddGit.raw(['worktree', 'add', worktreePath, `${remote}/${prData.base_branch}`]);
+        } catch (worktreeError) {
+          if (worktreeError.message.includes('already registered')) {
+            console.log('Worktree already registered, trying with --force...');
+            await worktreeAddGit.raw(['worktree', 'add', '--force', worktreePath, `${remote}/${prData.base_branch}`]);
+          } else {
+            throw worktreeError;
+          }
         }
       }
       
@@ -280,6 +398,35 @@ class GitWorktreeManager {
       console.log(`Fetching PR #${prInfo.number} head...`);
       await worktreeGit.fetch([remote, `+refs/pull/${prInfo.number}/head:refs/remotes/${remote}/pr-${prInfo.number}`]);
 
+      // Execute checkout script if configured (before checkout so sparse-checkout is set up)
+      if (checkoutScript) {
+        // Fetch the actual head branch by name (for checkout scripts that expect branch refs)
+        // This may fail for fork PRs where the branch is in a different repo - that's okay
+        if (prData.head_branch) {
+          try {
+            console.log(`Fetching head branch ${prData.head_branch}...`);
+            await worktreeGit.fetch([remote, `+refs/heads/${prData.head_branch}:refs/remotes/${remote}/${prData.head_branch}`]);
+            // Create/update a local branch pointing to the fetched ref so tooling can reference it by name
+            await worktreeGit.branch(['-f', prData.head_branch, `${remote}/${prData.head_branch}`]);
+          } catch (branchFetchError) {
+            // Expected for fork PRs - the branch exists in the fork, not the base repo
+            console.log(`Could not fetch head branch (may be from a fork): ${branchFetchError.message}`);
+          }
+        }
+
+        console.log(`Executing checkout script: ${checkoutScript}`);
+        const scriptEnv = {
+          BASE_BRANCH: prData.base_branch,
+          HEAD_BRANCH: prData.head_branch,
+          BASE_SHA: prData.base_sha,
+          HEAD_SHA: prData.head_sha,
+          PR_NUMBER: String(prInfo.number),
+          WORKTREE_PATH: worktreePath
+        };
+        await this.executeCheckoutScript(checkoutScript, worktreePath, scriptEnv, checkoutTimeout);
+        console.log('Checkout script completed successfully');
+      }
+
       // Checkout to PR head commit
       console.log(`Checking out to PR head commit ${prData.head_sha}...`);
       await worktreeGit.checkout([`${remote}/pr-${prInfo.number}`]);
@@ -596,7 +743,6 @@ class GitWorktreeManager {
       await fs.rm(dirPath, { recursive: true, force: true });
     } catch (error) {
       // Fallback for older Node.js versions
-      const { execSync } = require('child_process');
       if (process.platform === 'win32') {
         execSync(`rmdir /s /q "${dirPath}"`, { stdio: 'ignore' });
       } else {

package/src/main.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: GPL-3.0-or-later
 const fs = require('fs');
-const { loadConfig, getConfigDir, getGitHubToken, showWelcomeMessage, resolveDbName } = require('./config');
+const { loadConfig, getConfigDir, getGitHubToken, showWelcomeMessage, resolveDbName, resolveMonorepoOptions } = require('./config');
 const { initializeDatabase, run, queryOne, query, migrateExistingWorktrees, WorktreeRepository, ReviewRepository, RepoSettingsRepository, GitHubReviewRepository } = require('./database');
 const { PRArgumentParser } = require('./github/parser');
 const { GitHubClient } = require('./github/client');
@@ -495,23 +495,35 @@ async function handlePullRequest(args, config, db, flags = {}) {
     // Determine repository path: only use cwd if it matches the target repo
     const currentDir = parser.getCurrentDirectory();
     const isMatchingRepo = await parser.isMatchingRepository(currentDir, prInfo.owner, prInfo.repo);
+    const repository = normalizeRepository(prInfo.owner, prInfo.repo);
 
     let repositoryPath;
+    let worktreeSourcePath;
+    let checkoutScript;
+    let checkoutTimeout;
+    let worktreeConfig = null;
     if (isMatchingRepo) {
       // Current directory is a checkout of the target repository
       repositoryPath = currentDir;
       // Register the known repository location for future web UI usage
       await registerRepositoryLocation(db, currentDir, prInfo.owner, prInfo.repo);
+
+      // Resolve monorepo config options (checkout_script, worktree_directory, worktree_name_template)
+      // even when running from inside the target repo, so they are not silently ignored.
+      const resolved = resolveMonorepoOptions(config, repository);
+      checkoutScript = resolved.checkoutScript;
+      checkoutTimeout = resolved.checkoutTimeout;
+      worktreeConfig = resolved.worktreeConfig;
     } else {
       // Current directory is not the target repository - find or clone it
       console.log(`Current directory is not a checkout of ${prInfo.owner}/${prInfo.repo}, locating repository...`);
-      const repository = normalizeRepository(prInfo.owner, prInfo.repo);
       const result = await findRepositoryPath({
         db,
         owner: prInfo.owner,
         repo: prInfo.repo,
         repository,
         prNumber: prInfo.number,
+        config,
         onProgress: (progress) => {
           if (progress.message) {
             console.log(progress.message);
@@ -519,12 +531,20 @@ async function handlePullRequest(args, config, db, flags = {}) {
         }
       });
       repositoryPath = result.repositoryPath;
+      worktreeSourcePath = result.worktreeSourcePath;
+      checkoutScript = result.checkoutScript;
+      checkoutTimeout = result.checkoutTimeout;
+      worktreeConfig = result.worktreeConfig;
     }
 
     // Setup git worktree
     console.log('Setting up git worktree...');
-    const worktreeManager = new GitWorktreeManager(db);
-    const worktreePath = await worktreeManager.createWorktreeForPR(prInfo, prData, repositoryPath);
+    const worktreeManager = new GitWorktreeManager(db, worktreeConfig || {});
+    const worktreePath = await worktreeManager.createWorktreeForPR(prInfo, prData, repositoryPath, {
+      worktreeSourcePath,
+      checkoutScript,
+      checkoutTimeout
+    });
 
     // Generate unified diff
     console.log('Generating unified diff...');
@@ -784,10 +804,21 @@ async function performHeadlessReview(args, config, db, flags, options) {
       const isMatchingRepo = await parser.isMatchingRepository(currentDir, prInfo.owner, prInfo.repo);
 
       let repositoryPath;
+      let worktreeSourcePath;
+      let checkoutScript;
+      let checkoutTimeout;
+      let worktreeConfig = null;
       if (isMatchingRepo) {
         // Current directory is a checkout of the target repository
         repositoryPath = currentDir;
         await registerRepositoryLocation(db, currentDir, prInfo.owner, prInfo.repo);
+
+        // Resolve monorepo config options (checkout_script, worktree_directory, worktree_name_template)
+        // even when running from inside the target repo, so they are not silently ignored.
+        const resolved = resolveMonorepoOptions(config, repository);
+        checkoutScript = resolved.checkoutScript;
+        checkoutTimeout = resolved.checkoutTimeout;
+        worktreeConfig = resolved.worktreeConfig;
       } else {
         // Current directory is not the target repository - find or clone it
         console.log(`Current directory is not a checkout of ${prInfo.owner}/${prInfo.repo}, locating repository...`);
@@ -797,6 +828,7 @@ async function performHeadlessReview(args, config, db, flags, options) {
           repo: prInfo.repo,
           repository,
           prNumber: prInfo.number,
+          config,
           onProgress: (progress) => {
             if (progress.message) {
               console.log(progress.message);
@@ -804,11 +836,19 @@ async function performHeadlessReview(args, config, db, flags, options) {
           }
         });
         repositoryPath = result.repositoryPath;
+        worktreeSourcePath = result.worktreeSourcePath;
+        checkoutScript = result.checkoutScript;
+        checkoutTimeout = result.checkoutTimeout;
+        worktreeConfig = result.worktreeConfig;
       }
 
       console.log('Setting up git worktree...');
-      const worktreeManager = new GitWorktreeManager(db);
-      worktreePath = await worktreeManager.createWorktreeForPR(prInfo, prData, repositoryPath);
+      const worktreeManager = new GitWorktreeManager(db, worktreeConfig || {});
+      worktreePath = await worktreeManager.createWorktreeForPR(prInfo, prData, repositoryPath, {
+        worktreeSourcePath,
+        checkoutScript,
+        checkoutTimeout
+      });
 
       console.log('Generating unified diff...');
       diff = await worktreeManager.generateUnifiedDiff(worktreePath, prData);

package/src/setup/pr-setup.js

@@ -16,7 +16,7 @@ const { GitWorktreeManager } = require('../git/worktree');
 const { GitHubClient } = require('../github/client');
 const { normalizeRepository } = require('../utils/paths');
 const { findMainGitRoot } = require('../local-review');
-const { getConfigDir, getMonorepoPath } = require('../config');
+const { getConfigDir, getMonorepoPath, resolveMonorepoOptions, DEFAULT_CHECKOUT_TIMEOUT_MS } = require('../config');
 const logger = require('../utils/logger');
 const simpleGit = require('simple-git');
 const fs = require('fs').promises;
@@ -202,10 +202,13 @@ async function registerRepositoryLocation(db, currentDir, owner, repo) {
  * @param {number} params.prNumber - PR number (used for worktree lookup)
  * @param {Object} [params.config] - Application config (used for monorepo path lookup)
  * @param {Function} [params.onProgress] - Optional progress callback
- * @returns {Promise<{ repositoryPath: string, knownPath: string|null, worktreeSourcePath: string|null }>}
+ * @returns {Promise<{ repositoryPath: string, knownPath: string|null, worktreeSourcePath: string|null, checkoutScript: string|null, checkoutTimeout: number, worktreeConfig: Object|null }>}
  *   - repositoryPath: the main git root (bare repo or .git parent)
  *   - knownPath: the known path from database (if any)
  *   - worktreeSourcePath: path to use as cwd for `git worktree add` (may be a worktree with sparse-checkout)
+ *   - checkoutScript: path to the checkout script (if configured)
+ *   - checkoutTimeout: timeout in ms for checkout script (default: 300000 = 5 minutes)
+ *   - worktreeConfig: { worktreeBaseDir, nameTemplate } if configured, null otherwise
  */
 async function findRepositoryPath({ db, owner, repo, repository, prNumber, config, onProgress }) {
   const worktreeManager = new GitWorktreeManager(db);
@@ -267,6 +270,19 @@ async function findRepositoryPath({ db, owner, repo, repository, prNumber, confi
     }
   }
 
+  // ------------------------------------------------------------------
+  // Resolve monorepo worktree options (checkout_script, worktree_directory, worktree_name_template)
+  // ------------------------------------------------------------------
+  const resolved = config ? resolveMonorepoOptions(config, repository) : { checkoutScript: null, checkoutTimeout: DEFAULT_CHECKOUT_TIMEOUT_MS, worktreeConfig: null };
+  const { checkoutScript, checkoutTimeout, worktreeConfig } = resolved;
+
+  // When a checkout script is configured, null out worktreeSourcePath —
+  // the script handles all sparse-checkout setup, so we don't want to
+  // inherit from an existing worktree.
+  if (checkoutScript) {
+    worktreeSourcePath = null;
+  }
+
   // ------------------------------------------------------------------
   // Tier 0: Check known local path from repo_settings
   // ------------------------------------------------------------------
@@ -335,7 +351,7 @@ async function findRepositoryPath({ db, owner, repo, repository, prNumber, confi
     }
   }
 
-  return { repositoryPath, knownPath, worktreeSourcePath };
+  return { repositoryPath, knownPath, worktreeSourcePath, checkoutScript, checkoutTimeout, worktreeConfig };
 }
 
 /**
@@ -381,7 +397,7 @@ async function setupPRReview({ db, owner, repo, prNumber, githubToken, config, o
   // Step: repo - Find (or clone) a local repository
   // ------------------------------------------------------------------
   progress({ step: 'repo', status: 'running', message: 'Locating repository...' });
-  const { repositoryPath, knownPath, worktreeSourcePath } = await findRepositoryPath({
+  const { repositoryPath, knownPath, worktreeSourcePath, checkoutScript, checkoutTimeout, worktreeConfig } = await findRepositoryPath({
     db,
     owner,
     repo,
@@ -396,10 +412,10 @@ async function setupPRReview({ db, owner, repo, prNumber, githubToken, config, o
   // Step: worktree - Create git worktree for the PR
   // ------------------------------------------------------------------
   progress({ step: 'worktree', status: 'running', message: 'Setting up git worktree...' });
-  const worktreeManager = new GitWorktreeManager(db);
+  const worktreeManager = new GitWorktreeManager(db, worktreeConfig || {});
   const prInfo = { owner, repo, number: prNumber };
   // Use worktreeSourcePath as cwd for git worktree add (if available) to inherit sparse-checkout
-  const worktreePath = await worktreeManager.createWorktreeForPR(prInfo, prData, repositoryPath, { worktreeSourcePath });
+  const worktreePath = await worktreeManager.createWorktreeForPR(prInfo, prData, repositoryPath, { worktreeSourcePath, checkoutScript, checkoutTimeout });
   progress({ step: 'worktree', status: 'completed', message: `Worktree created at ${worktreePath}` });
 
   // ------------------------------------------------------------------
@@ -415,7 +431,11 @@ async function setupPRReview({ db, owner, repo, prNumber, githubToken, config, o
   //
   // NOTE: prData.changed_files is an INTEGER (count) from the GitHub pulls.get
   // API, not an array. We must fetch the actual file list via pulls.listFiles.
-  if (prData.changed_files > 0) {
+  if (checkoutScript) {
+    // checkout_script handles all sparse-checkout setup — skip built-in expansion
+    logger.info('Skipping built-in sparse-checkout expansion (checkout_script configured)');
+    progress({ step: 'sparse', status: 'completed', message: 'Sparse-checkout managed by checkout_script' });
+  } else if (prData.changed_files > 0) {
     const isSparse = await worktreeManager.isSparseCheckoutEnabled(worktreePath);
     if (isSparse) {
       progress({ step: 'sparse', status: 'running', message: 'Expanding sparse-checkout for PR directories...' });