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

package/public/setup.html

@@ -528,6 +528,7 @@
 
     <!-- WebSocket client -->
     <script src="/js/ws-client.js"></script>
+    <script src="/js/utils/notification-sounds.js"></script>
 
     <script>
         // Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
@@ -818,6 +819,9 @@
                             updateProgressBar();
                             showRedirect();
 
+                            // Play notification sound for PR setup completion
+                            if (window.notificationSounds && mode !== 'local') window.notificationSounds.playIfEnabled('setup');
+
                             // Small delay so the user sees the completed state
                             setTimeout(function() {
                                 if (msg.reviewUrl) {

package/src/ai/claude-provider.js

@@ -22,23 +22,13 @@ const BIN_DIR = path.join(__dirname, '..', '..', 'bin');
 const CLAUDE_MODELS = [
   {
     id: 'haiku',
-    name: 'Haiku 4.5',
+    name: 'Haiku 4.6',
     tier: 'fast',
     tagline: 'Lightning Fast',
     description: 'Quick analysis for simple changes',
     badge: 'Fastest',
     badgeClass: 'badge-speed'
   },
-  {
-    id: 'sonnet-4.5',
-    cli_model: 'claude-sonnet-4.5',
-    name: 'Sonnet 4.5',
-    tier: 'balanced',
-    tagline: 'Previous Gen',
-    description: 'Sonnet 4.5 — previous generation balanced model',
-    badge: 'Previous Gen',
-    badgeClass: 'badge-balanced'
-  },
   {
     id: 'sonnet-4.6',
     cli_model: 'claude-sonnet-4-6',

package/src/ai/codex-provider.js

@@ -21,27 +21,29 @@ const BIN_DIR = path.join(__dirname, '..', '..', 'bin');
  * Codex model definitions with tier mappings
  *
  * Based on OpenAI Codex Models guide (developers.openai.com/codex/models)
- * - gpt-5.1-codex-mini: Smaller, cost-effective variant for quick scans
- * - gpt-5.2-codex: Advanced coding model for everyday reviews, good reasoning/cost balance
- * - gpt-5.3-codex: Capable agentic coding model with frontier performance and reasoning
- * - gpt-5.4: Latest generation with enhanced reasoning depth
+ * - gpt-5.4-nano: Cheapest model ($0.20/$1.25 per MTok), good for surface scans
+ * - gpt-5.4-mini: Fast with 400k context ($0.75/$4.50 per MTok)
+ * - gpt-5.4: Flagship model combining coding, reasoning, and agentic workflows
+ * - gpt-5.3-codex: Industry-leading coding model for complex engineering tasks
+ *
+ * Deprecated (April 2026): gpt-5.1-codex-mini, gpt-5.1-codex-max, gpt-5.1-codex
  */
 const CODEX_MODELS = [
   {
-    id: 'gpt-5.1-codex-mini',
-    name: 'GPT-5.1 Mini',
+    id: 'gpt-5.4-nano',
+    name: 'GPT-5.4 Nano',
     tier: 'fast',
-    tagline: 'Blazing Fast',
-    description: 'Quick, low-cost reviews for style issues, obvious bugs, and lint-level feedback.',
-    badge: 'Fastest',
+    tagline: 'Cheapest',
+    description: 'Ultra-low-cost surface scans for style issues, obvious bugs, and lint-level feedback.',
+    badge: 'Cheapest',
     badgeClass: 'badge-speed'
   },
   {
-    id: 'gpt-5.2-codex',
-    name: 'GPT-5.2 Codex',
+    id: 'gpt-5.4-mini',
+    name: 'GPT-5.4 Mini',
     tier: 'balanced',
     tagline: 'Best Balance',
-    description: 'Strong everyday reviewer—good reasoning and code understanding for PR-sized changes without top-tier cost.',
+    description: 'Fast reviews with 400k context—good balance of speed and capability for everyday PR review.',
     badge: 'Recommended',
     badgeClass: 'badge-recommended',
     default: true
@@ -51,7 +53,7 @@ const CODEX_MODELS = [
     name: 'GPT-5.3 Codex',
     tier: 'thorough',
     tagline: 'Deep Review',
-    description: 'Capable agentic coding model—combines frontier coding performance with strong reasoning for cross-file analysis.',
+    description: 'Industry-leading coding model—frontier performance with strong reasoning for cross-file analysis.',
     badge: 'Thorough',
     badgeClass: 'badge-power'
   },
@@ -60,7 +62,7 @@ const CODEX_MODELS = [
     name: 'GPT-5.4',
     tier: 'thorough',
     tagline: 'Latest Gen',
-    description: 'Latest generation model with enhanced reasoning depth for complex architectural reviews.',
+    description: 'Flagship model combining coding, reasoning, and agentic workflows for complex architectural reviews.',
     badge: 'Most Thorough',
     badgeClass: 'badge-power'
   }
@@ -76,7 +78,7 @@ class CodexProvider extends AIProvider {
    * @param {Object} configOverrides.env - Additional environment variables
    * @param {Object[]} configOverrides.models - Custom model definitions
    */
-  constructor(model = 'gpt-5.2-codex', configOverrides = {}) {
+  constructor(model = 'gpt-5.4-mini', configOverrides = {}) {
     super(model);
 
     // Command precedence: ENV > config > default
@@ -698,7 +700,7 @@ class CodexProvider extends AIProvider {
   }
 
   static getDefaultModel() {
-    return 'gpt-5.2-codex';
+    return 'gpt-5.4-mini';
   }
 
   static getInstallInstructions() {

package/src/ai/copilot-provider.js

@@ -21,21 +21,30 @@ const BIN_DIR = path.join(__dirname, '..', '..', 'bin');
  *
  * GitHub Copilot CLI supports multiple AI models including OpenAI,
  * Anthropic, and Google models via the --model flag.
- * Available models (as of Feb 2026): claude-haiku-4.5, claude-sonnet-4.6,
- * claude-sonnet-4.5, gpt-5.2-codex, gpt-5.3-codex,
+ * Available models (as of April 2026): claude-haiku-4.6, claude-sonnet-4.6,
+ * claude-sonnet-4.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex,
  * claude-opus-4.5, claude-opus-4.6, claude-opus-4.6-fast.
  * Default is claude-sonnet-4.6.
  */
 const COPILOT_MODELS = [
   {
-    id: 'claude-haiku-4.5',
-    name: 'Claude Haiku 4.5',
+    id: 'claude-haiku-4.6',
+    name: 'Claude Haiku 4.6',
     tier: 'fast',
     tagline: 'Quick Scan',
     description: 'Rapid feedback for obvious issues, style checks, and simple logic errors',
     badge: 'Speedy',
     badgeClass: 'badge-speed'
   },
+  {
+    id: 'gpt-5.4-mini',
+    name: 'GPT-5.4 Mini',
+    tier: 'fast',
+    tagline: 'Fast & Cheap',
+    description: 'Low-cost fast reviews with solid reasoning—included at no premium cost',
+    badge: 'Fast',
+    badgeClass: 'badge-speed'
+  },
   {
     id: 'claude-sonnet-4.6',
     name: 'Claude Sonnet 4.6',
@@ -47,29 +56,20 @@ const COPILOT_MODELS = [
     default: true
   },
   {
-    id: 'claude-sonnet-4.5',
-    name: 'Claude Sonnet 4.5',
-    tier: 'balanced',
-    tagline: 'Previous Gen',
-    description: 'Previous generation Sonnet—strong code understanding with excellent quality-to-cost ratio',
-    badge: 'Previous Gen',
-    badgeClass: 'badge-balanced'
-  },
-  {
-    id: 'gpt-5.2-codex',
-    name: 'GPT-5.2 Codex',
-    tier: 'balanced',
-    tagline: 'Alternative View',
-    description: 'OpenAI code-specialized model—different perspective for cross-file analysis',
-    badge: 'Balanced',
-    badgeClass: 'badge-balanced'
+    id: 'gpt-5.4',
+    name: 'GPT-5.4',
+    tier: 'thorough',
+    tagline: 'Latest OpenAI',
+    description: 'Flagship OpenAI model combining coding, reasoning, and agentic workflows',
+    badge: 'Latest',
+    badgeClass: 'badge-power'
   },
   {
     id: 'gpt-5.3-codex',
     name: 'GPT-5.3 Codex',
     tier: 'thorough',
     tagline: 'Deep Code Analysis',
-    description: 'Most capable OpenAI coding model—frontier performance for complex multi-file reviews',
+    description: 'Industry-leading coding model—frontier performance for complex multi-file reviews',
     badge: 'Thorough',
     badgeClass: 'badge-power'
   },

package/src/ai/gemini-provider.js

@@ -20,6 +20,16 @@ const BIN_DIR = path.join(__dirname, '..', '..', 'bin');
  * Gemini model definitions with tier mappings
  */
 const GEMINI_MODELS = [
+  {
+    id: 'gemini-3.1-flash-lite-preview',
+    aliases: ['gemini-3.1-flash-lite'],
+    name: '3.1 Flash Lite',
+    tier: 'fast',
+    tagline: 'Cheapest',
+    description: 'Ultra-efficient model for high-volume cost-conscious scans',
+    badge: 'Cheapest',
+    badgeClass: 'badge-speed'
+  },
   {
     id: 'gemini-3-flash-preview',
     aliases: ['gemini-3-flash'],

package/src/ai/pi-provider.js

@@ -16,7 +16,10 @@
  * for cross-provider switching, which translates to `--provider <provider> --model <model>`.
  */
 
+const crypto = require('crypto');
 const path = require('path');
+const os = require('os');
+const fs = require('fs');
 const { spawn } = require('child_process');
 const { AIProvider, registerProvider, quoteShellArgs } = require('./provider');
 const logger = require('../utils/logger');
@@ -244,19 +247,23 @@ class PiProvider extends AIProvider {
 
       const levelPrefix = logPrefix || `[Level ${level}]`;
       logger.info(`${levelPrefix} Executing Pi CLI...`);
-      logger.info(`${levelPrefix} Writing prompt via stdin: ${prompt.length} bytes`);
+      logger.info(`${levelPrefix} Prompt: ${prompt.length} bytes`);
+
+      // Write prompt to a temp file and use Pi's @file syntax as a positional arg.
+      // This bypasses devx stdin interference that breaks --mode json output.
+      const tmpFile = path.join(os.tmpdir(), `pair-review-prompt-${Date.now()}-${process.pid}-${crypto.randomUUID()}.txt`);
+      fs.writeFileSync(tmpFile, prompt);
+      const cleanupTmpFile = () => { try { fs.unlinkSync(tmpFile); } catch { /* ignore */ } };
 
-      // Use stdin for prompt instead of CLI argument (avoids shell escaping issues)
-      // Pi reads from stdin when using -p with no positional message arguments
       let fullCommand;
       let fullArgs;
 
       if (this.useShell) {
-        fullCommand = `${this.piCmd} ${quoteShellArgs(this.baseArgs).join(' ')}`;
+        fullCommand = `${this.piCmd} ${quoteShellArgs([...this.baseArgs, `@${tmpFile}`]).join(' ')}`;
         fullArgs = [];
       } else {
         fullCommand = this.piCmd;
-        fullArgs = [...this.baseArgs];
+        fullArgs = [...this.baseArgs, `@${tmpFile}`];
       }
 
       const pi = spawn(fullCommand, fullArgs, {
@@ -269,6 +276,10 @@ class PiProvider extends AIProvider {
         shell: this.useShell
       });
 
+      // Close stdin immediately — prompt is delivered via @file, but some
+      // wrappers (e.g., devx) keep the process alive until stdin is closed.
+      pi.stdin.end();
+
       const pid = pi.pid;
       logger.debug(`${levelPrefix} Pi CLI command: ${fullCommand} ${fullArgs.join(' ')}`);
       logger.info(`${levelPrefix} Spawned Pi CLI process: PID ${pid}`);
@@ -340,6 +351,7 @@ class PiProvider extends AIProvider {
 
       // Handle completion
       pi.on('close', (code) => {
+        cleanupTmpFile();
         if (settled) return;  // Already settled by timeout or error
 
         // Flush any remaining stream parser buffer
@@ -413,7 +425,7 @@ class PiProvider extends AIProvider {
 
           // Use async IIFE to handle the async LLM extraction
           (async () => {
-            // Guard: if already settled (by timeout, stdin error, or cancellation),
+            // Guard: if already settled (by timeout, process error, or cancellation),
             // skip the LLM extraction entirely to avoid misleading log output
             if (settled) return;
 
@@ -437,6 +449,7 @@ class PiProvider extends AIProvider {
 
       // Handle errors
       pi.on('error', (error) => {
+        cleanupTmpFile();
         if (error.code === 'ENOENT') {
           logger.error(`${levelPrefix} Pi CLI not found. Please ensure Pi CLI is installed.`);
           settle(reject, new Error(`${levelPrefix} Pi CLI not found. ${PiProvider.getInstallInstructions()}`));
@@ -445,21 +458,6 @@ class PiProvider extends AIProvider {
           settle(reject, error);
         }
       });
-
-      // Handle stdin errors (e.g., EPIPE if process exits before write completes)
-      pi.stdin.on('error', (err) => {
-        logger.error(`${levelPrefix} stdin error: ${err.message}`);
-      });
-
-      // Send the prompt to stdin (Pi reads from stdin when using -p with no args)
-      pi.stdin.write(prompt, (err) => {
-        if (err) {
-          logger.error(`${levelPrefix} Failed to write prompt to stdin: ${err}`);
-          pi.kill('SIGTERM');
-          settle(reject, new Error(`${levelPrefix} Failed to write prompt to stdin: ${err}`));
-        }
-      });
-      pi.stdin.end();
     });
   }
 
@@ -740,14 +738,13 @@ class PiProvider extends AIProvider {
     // Build args consistently using the shared method, applying provider and model extra_args
     const args = this.buildArgsForModel(model);
 
-    // For extraction, we pass the prompt via stdin
-    // Pi reads from stdin when using -p with no positional message arguments
+    // Use @file syntax for prompt delivery (bypasses devx stdin interference)
     if (useShell) {
       return {
         command: `${piCmd} ${quoteShellArgs(args).join(' ')}`,
         args: [],
         useShell: true,
-        promptViaStdin: true,
+        promptViaFile: true,
         env: this.extraEnv
       };
     }
@@ -755,7 +752,7 @@ class PiProvider extends AIProvider {
       command: piCmd,
       args,
       useShell: false,
-      promptViaStdin: true,
+      promptViaFile: true,
       env: this.extraEnv
     };
   }

package/src/ai/provider.js

@@ -6,7 +6,10 @@
  * and provides a factory function to create provider instances.
  */
 
+const crypto = require('crypto');
 const path = require('path');
+const os = require('os');
+const fs = require('fs');
 const { spawn } = require('child_process');
 const logger = require('../utils/logger');
 const { extractJSON } = require('../utils/json-extractor');
@@ -181,6 +184,7 @@ class AIProvider {
    * @property {string[]} args - Arguments (prompt will be appended if promptViaStdin is false)
    * @property {boolean} useShell - Whether to use shell mode
    * @property {boolean} promptViaStdin - If true, send prompt to stdin; if false, append to args
+   * @property {boolean} promptViaFile - If true, write prompt to a temp file and pass @filepath as a positional arg (Pi-specific @file syntax; currently only used by PiProvider)
    */
   getExtractionConfig(model) {
     // Default: extraction not supported
@@ -213,7 +217,7 @@ class AIProvider {
       };
     }
 
-    const { command, args, useShell, promptViaStdin, env: configEnv } = config;
+    const { command, args, useShell, promptViaStdin, promptViaFile, env: configEnv } = config;
     const prompt = `Extract the JSON object from the following text. Return ONLY the valid JSON, nothing else. Do not include any explanation, markdown formatting, or code blocks - just the raw JSON.
 
 === BEGIN INPUT TEXT ===
@@ -222,7 +226,21 @@ ${rawResponse}
 
     return new Promise((resolve) => {
       // Build final command and args based on prompt delivery method
-      const finalArgs = promptViaStdin ? args : [...args, prompt];
+      // promptViaFile: write to temp file, pass @filepath as positional arg (Pi @file syntax)
+      // promptViaStdin: write to process stdin after spawn
+      // default: pass prompt as positional CLI arg
+      let tmpFile = null;
+      let cleanupTmpFile = () => {};
+      let finalArgs;
+
+      if (promptViaFile) {
+        tmpFile = path.join(os.tmpdir(), `pair-review-extract-${Date.now()}-${process.pid}-${crypto.randomUUID()}.txt`);
+        fs.writeFileSync(tmpFile, prompt);
+        cleanupTmpFile = () => { try { fs.unlinkSync(tmpFile); } catch { /* ignore */ } };
+        finalArgs = [...args, `@${tmpFile}`];
+      } else {
+        finalArgs = promptViaStdin ? args : [...args, prompt];
+      }
 
       logger.info(`${levelPrefix} Attempting LLM-based JSON extraction with ${extractionModel}...`);
 
@@ -269,6 +287,7 @@ ${rawResponse}
       });
 
       proc.on('close', (code) => {
+        cleanupTmpFile();
         if (settled) return;
 
         if (code !== 0) {
@@ -295,11 +314,12 @@ ${rawResponse}
       });
 
       proc.on('error', (error) => {
+        cleanupTmpFile();
         logger.warn(`${levelPrefix} LLM extraction process error: ${error.message}`);
         settle({ success: false, error: error.message });
       });
 
-      // Send prompt via stdin if configured
+      // Deliver prompt based on config method
       if (promptViaStdin) {
         // Handle stdin errors (e.g., EPIPE if process exits before write completes)
         proc.stdin.on('error', (err) => {
@@ -314,6 +334,9 @@ ${rawResponse}
           }
         });
         proc.stdin.end();
+      } else if (promptViaFile) {
+        // Prompt delivered via @file arg — close stdin so wrappers (e.g., devx) don't hang
+        proc.stdin.end();
       }
     });
   }

package/src/chat/pi-bridge.js

@@ -35,6 +35,7 @@ class PiBridge extends EventEmitter {
    * @param {boolean} [options.useShell] - Use shell mode for multi-word commands
    * @param {string[]} [options.skills] - Array of skill file paths to load via --skill
    * @param {string[]} [options.extensions] - Array of extension directory paths to load via -e
+   * @param {string[]} [options.extraArgs] - Extra CLI args to append (e.g., from config extra_args)
    * @param {string} [options.sessionPath] - Path to a session file for resumption
    */
   constructor(options = {}) {
@@ -49,6 +50,7 @@ class PiBridge extends EventEmitter {
     this.useShell = options.useShell || false;
     this.skills = options.skills || [];
     this.extensions = options.extensions || [];
+    this.extraArgs = options.extraArgs || [];
     this.sessionPath = options.sessionPath || null;
 
     this._process = null;
@@ -288,6 +290,12 @@ class PiBridge extends EventEmitter {
       args.push('-e', ext);
     }
 
+    // Append extra args from provider config (e.g., extra_args in chat_providers).
+    // These go last so they can override earlier flags if needed.
+    if (this.extraArgs.length > 0) {
+      args.push(...this.extraArgs);
+    }
+
     return args;
   }
 

package/src/chat/session-manager.js

@@ -580,6 +580,7 @@ class ChatSessionManager {
       provider: def?.provider || null,
       model: options.model || def?.model,
       piCommand: def?.command,
+      extraArgs: def?.args,
       env: def?.env,
       useShell: def?.useShell,
       tools: CHAT_TOOLS,

package/src/git/base-branch.js

@@ -1,12 +1,9 @@
 // Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
 const { execSync } = require('child_process');
-const { readFileSync } = require('fs');
-const path = require('path');
 const logger = require('../utils/logger');
 
 const defaults = {
   execSync,
-  readFileSync,
   // Callers should pass a resolved token via _deps.getGitHubToken.
   // This default returns empty so GitHub lookup is silently skipped
   // when no token is provided — never re-resolve config internally.
@@ -135,53 +132,6 @@ function buildStack(state, currentBranch, trunk) {
   return entries;
 }
 
-/**
- * Read Graphite PR info from the `.graphite_pr_info` file in the git dir.
- *
- * @param {string} repoPath - Absolute path to the repository
- * @param {Object} deps - Dependencies (execSync, readFileSync)
- * @returns {Object|null} Parsed PR info object with `prInfos` array, or null
- */
-function readGraphitePRInfo(repoPath, deps) {
-  try {
-    const gitCommonDir = deps.execSync('git rev-parse --git-common-dir', {
-      cwd: repoPath,
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe']
-    }).trim();
-
-    const prInfoPath = path.resolve(repoPath, gitCommonDir, '.graphite_pr_info');
-    const raw = deps.readFileSync(prInfoPath, 'utf8');
-    return JSON.parse(raw);
-  } catch (error) {
-    logger.debug(`Graphite PR info read failed: ${error.message}`);
-    return null;
-  }
-}
-
-/**
- * Enrich stack entries with PR numbers from Graphite PR info.
- *
- * @param {Array} stack - Stack entries from buildStack
- * @param {Array} prInfos - Array of PR info objects with headRefName and prNumber
- * @returns {Array} New array of stack entries, each with optional prNumber
- */
-function enrichStackWithPRInfo(stack, prInfos) {
-  if (!prInfos || !Array.isArray(prInfos)) return stack;
-
-  const prMap = new Map();
-  for (const info of prInfos) {
-    if (info.headRefName) {
-      prMap.set(info.headRefName, info.prNumber);
-    }
-  }
-
-  return stack.map(entry => {
-    const prNumber = prMap.get(entry.branch);
-    return prNumber != null ? { ...entry, prNumber } : { ...entry };
-  });
-}
-
 /**
  * Try GitHub API to find an open PR for this branch.
  */
@@ -302,4 +252,4 @@ function getDefaultBranch(localPath, _deps) {
   return null;
 }
 
-module.exports = { detectBaseBranch, getDefaultBranch, tryGraphiteState, buildStack, readGraphitePRInfo, enrichStackWithPRInfo };
+module.exports = { detectBaseBranch, getDefaultBranch, tryGraphiteState, buildStack };

package/src/git/worktree-lock.js

@@ -0,0 +1,88 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+/**
+ * In-memory worktree lock manager.
+ *
+ * Prevents concurrent git operations on the same worktree during
+ * stack analysis. Non-blocking — callers check and fail fast.
+ */
+
+const logger = require('../utils/logger');
+
+class WorktreeLockManager {
+  constructor() {
+    /** @type {Map<string, { holderId: string, lockedAt: Date }>} */
+    this._locks = new Map();
+  }
+
+  /**
+   * Acquire a lock on a worktree path.
+   *
+   * @param {string} worktreePath - Absolute path to the worktree
+   * @param {string} holderId - Unique identifier for the lock holder (e.g. stackAnalysisId)
+   * @returns {boolean} true if acquired (or re-acquired by same holder), false if held by another
+   */
+  acquire(worktreePath, holderId) {
+    const existing = this._locks.get(worktreePath);
+
+    if (existing) {
+      if (existing.holderId === holderId) {
+        // Re-acquire by same holder — update timestamp
+        existing.lockedAt = new Date();
+        logger.debug(`Worktree lock re-acquired: ${worktreePath} by ${holderId}`);
+        return true;
+      }
+      logger.debug(`Worktree lock denied: ${worktreePath} held by ${existing.holderId}, requested by ${holderId}`);
+      return false;
+    }
+
+    this._locks.set(worktreePath, { holderId, lockedAt: new Date() });
+    logger.info(`Worktree lock acquired: ${worktreePath} by ${holderId}`);
+    return true;
+  }
+
+  /**
+   * Release a lock on a worktree path.
+   *
+   * @param {string} worktreePath - Absolute path to the worktree
+   * @param {string} holderId - Must match the holder that acquired the lock
+   * @returns {boolean} true if released, false if not held or held by a different holder
+   */
+  release(worktreePath, holderId) {
+    const existing = this._locks.get(worktreePath);
+
+    if (!existing) {
+      logger.debug(`Worktree lock release: no lock found for ${worktreePath}`);
+      return false;
+    }
+
+    if (existing.holderId !== holderId) {
+      logger.debug(`Worktree lock release denied: ${worktreePath} held by ${existing.holderId}, release requested by ${holderId}`);
+      return false;
+    }
+
+    this._locks.delete(worktreePath);
+    logger.info(`Worktree lock released: ${worktreePath} by ${holderId}`);
+    return true;
+  }
+
+  /**
+   * Check whether a worktree is currently locked.
+   *
+   * @param {string} worktreePath - Absolute path to the worktree
+   * @returns {{ locked: boolean, holderId?: string }}
+   */
+  isLocked(worktreePath) {
+    const existing = this._locks.get(worktreePath);
+
+    if (!existing) {
+      return { locked: false };
+    }
+
+    return { locked: true, holderId: existing.holderId };
+  }
+}
+
+// Singleton instance for application-wide use
+const worktreeLock = new WorktreeLockManager();
+
+module.exports = { worktreeLock, WorktreeLockManager };