@in-the-loop-labs/pair-review 3.3.7 → 3.4.1

package/src/main.js

@@ -5,6 +5,7 @@ const { initializeDatabase, run, queryOne, query, migrateExistingWorktrees, Work
 const { PRArgumentParser } = require('./github/parser');
 const { GitHubClient } = require('./github/client');
 const { GitWorktreeManager } = require('./git/worktree');
+const { fetchNoTags } = require('./git/fetch-helpers');
 const { WorktreePoolLifecycle } = require('./git/worktree-pool-lifecycle');
 const { startServer } = require('./server');
 const Analyzer = require('./ai/analyzer');
@@ -13,6 +14,7 @@ const { handleLocalReview, findMainGitRoot } = require('./local-review');
 const { storePRData, registerRepositoryLocation, findRepositoryPath } = require('./setup/pr-setup');
 const { fireReviewStartedHook } = require('./hooks/payloads');
 const { normalizeRepository, resolveRenamedFile, resolveRenamedFileOld } = require('./utils/paths');
+const { rejectUrlLikeLocalReviewPath } = require('./utils/local-path-input');
 const logger = require('./utils/logger');
 const simpleGit = require('simple-git');
 const { getGeneratedFilePatterns } = require('./git/gitattributes');
@@ -20,6 +22,7 @@ const { GIT_DIFF_FLAGS_ARRAY, GIT_DIFF_SUMMARY_FLAGS_ARRAY } = require('./git/di
 const { getEmoji: getCategoryEmoji } = require('./utils/category-emoji');
 const open = (...args) => process.env.PAIR_REVIEW_NO_OPEN ? Promise.resolve() : import('open').then(({default: open}) => open(...args));
 const { registerProtocolHandler, unregisterProtocolHandler } = require('./protocol-handler');
+const { attemptDelegation } = require('./single-port');
 
 let db = null;
 
@@ -287,6 +290,7 @@ function parseArgs(args) {
       flags.local = true;
       // Next argument is optional path (if not starting with -)
       if (i + 1 < args.length && !args[i + 1].startsWith('-')) {
+        rejectUrlLikeLocalReviewPath(args[i + 1]);
         flags.localPath = args[i + 1];
         i++; // Skip next argument since we consumed it
       }
@@ -432,26 +436,8 @@ AI PROVIDERS:
       showWelcomeMessage();
     }
 
-    // Initialize database
-    console.log('Initializing database...');
-    db = await initializeDatabase(resolveDbName(config));
-
-    // Migrate existing worktrees to database (if any)
-    const path = require('path');
-    const worktreeBaseDir = path.join(getConfigDir(), 'worktrees');
-    const migrationResult = await migrateExistingWorktrees(db, worktreeBaseDir);
-    if (migrationResult.migrated > 0) {
-      console.log(`Migrated ${migrationResult.migrated} existing worktrees to database`);
-    }
-    if (migrationResult.errors.length > 0) {
-      console.warn('Some worktrees could not be migrated:', migrationResult.errors);
-    }
-
-    // Reset stale pool entries, wire idle callbacks, and rehydrate preserved entries
-    const poolLifecycle = new WorktreePoolLifecycle(db, config);
-    await poolLifecycle.resetAndRehydrate();
-
-    // Parse command line arguments including flags
+    // Parse command line arguments including flags (before DB init so
+    // single-port delegation can skip DB entirely)
     const { prArgs, flags } = parseArgs(args);
 
     // Apply debug_stream from config if not already enabled by CLI flag
@@ -474,6 +460,36 @@ AI PROVIDERS:
     // server, so we must also apply here.
     applyConfigOverrides(config);
 
+    // Single-port delegation: if a pair-review server is already running on the
+    // configured port, delegate to it (open browser URL) and exit immediately.
+    // Skipped for: headless modes (no browser), single_port: false (dev mode).
+    if (config.single_port !== false && !flags.aiReview && !flags.aiDraft) {
+      const delegated = await attemptDelegation(config, flags, prArgs);
+      if (delegated) {
+        process.exit(0);
+      }
+      // Not delegated — no server running, proceed to start one
+    }
+
+    // Initialize database
+    console.log('Initializing database...');
+    db = await initializeDatabase(resolveDbName(config));
+
+    // Migrate existing worktrees to database (if any)
+    const path = require('path');
+    const worktreeBaseDir = path.join(getConfigDir(), 'worktrees');
+    const migrationResult = await migrateExistingWorktrees(db, worktreeBaseDir);
+    if (migrationResult.migrated > 0) {
+      console.log(`Migrated ${migrationResult.migrated} existing worktrees to database`);
+    }
+    if (migrationResult.errors.length > 0) {
+      console.warn('Some worktrees could not be migrated:', migrationResult.errors);
+    }
+
+    // Reset stale pool entries, wire idle callbacks, and rehydrate preserved entries
+    const poolLifecycle = new WorktreePoolLifecycle(db, config);
+    await poolLifecycle.resetAndRehydrate();
+
     // Check for local mode (review uncommitted local changes)
     if (flags.local) {
       // Resolve localPath, defaulting to cwd if not provided
@@ -710,7 +726,7 @@ async function performHeadlessReview(args, config, db, flags, options, externalP
 
       // Ensure we have the base SHA available (fetch if needed)
       try {
-        await git.fetch(['origin', prData.base_sha]);
+        await fetchNoTags(git, ['origin', prData.base_sha]);
       } catch (fetchError) {
         // Fetch by SHA may fail (not all servers support it); verify SHA is available locally
         try {
@@ -1212,7 +1228,7 @@ function startPoolBackgroundFetches(db, config) {
               const git = simpleGit(entry.path, { timeout: { block: 300000 } });
               const remotes = await git.getRemotes();
               const remote = remotes.find(r => r.name === 'origin') || remotes[0];
-              if (remote) await git.fetch([remote.name, '--prune']);
+              if (remote) await fetchNoTags(git, ['--prune', remote.name]);
               await poolRepo.updateLastFetched(entry.id);
               // Refresh the lease so the stale guard only needs to outlive
               // a single stalled fetch, not the entire serial loop.
@@ -1281,4 +1297,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { main, parseArgs, detectPRFromGitHubEnvironment };
+module.exports = { main, parseArgs, detectPRFromGitHubEnvironment };

package/src/mcp-stdio.js

@@ -45,6 +45,13 @@ async function startMCPStdio() {
     console.error(`[MCP] Warning: failed to load config, using defaults: ${err.message}`);
   }
 
+  // MCP mode needs its own Express server for stdio↔HTTP bridging and cannot
+  // delegate to a running pair-review instance (the stdio transport owns this
+  // process). Force auto-port selection to avoid EADDRINUSE when a regular
+  // pair-review server is already running on config.port.
+  // startServer (src/server.js) reads this env var and flips config.single_port.
+  process.env.PAIR_REVIEW_SINGLE_PORT = 'false';
+
   const db = await initializeDatabase(resolveDbName(config));
   const port = await startServer(db);
 

package/src/routes/config.js

@@ -22,11 +22,19 @@ const {
 const { normalizeRepository } = require('../utils/paths');
 const { isRunningViaNpx, getGitHubToken } = require('../config');
 const { version } = require('../../package.json');
+const semver = require('semver');
 const { getAllChatProviders, getAllCachedChatAvailability } = require('../chat/chat-providers');
 const logger = require('../utils/logger');
 
 const router = express.Router();
 
+// Module-level state: the most recent version we've been told about that's
+// newer than the running server. Plain string, not an object. `null` means
+// nothing is pending. Reset on process restart — which is fine because a
+// restart either IS the update (running version is now newer) or loses no
+// information (the next notifier will re-populate it).
+let pendingUpdateVersion = null;
+
 /**
  * Get user configuration (for frontend use)
  * Returns safe-to-expose configuration values
@@ -71,10 +79,46 @@ router.get('/api/config', (req, res) => {
       icon: config.share.icon || null,
       label: config.share.label || null,
       description: config.share.description || null
-    } : null
+    } : null,
+    pending_update: pendingUpdateVersion
   });
 });
 
+/**
+ * Notify the running server that a newer version is available.
+ * Called by a newer CLI invocation delegating to this server.
+ * Stores state so browser tabs can pick it up via GET /api/config.
+ *
+ * Suppression is version-based, not time-based: a POST is accepted only
+ * when the incoming version is strictly newer than both the running version
+ * and any currently-pending version. This means `pendingUpdateVersion`
+ * monotonically increases for the life of the process.
+ */
+router.post('/api/notify-update', (req, res) => {
+  const incomingVersion = req.body?.version;
+  if (!incomingVersion || !semver.valid(incomingVersion)) {
+    return res.status(400).json({ error: 'Invalid version' });
+  }
+
+  if (!semver.gt(incomingVersion, version)) {
+    return res.json({ ok: true, notified: false, reason: 'not_newer' });
+  }
+
+  // Suppress unless the incoming version is STRICTLY newer than what's
+  // already pending. Handles three cases at once:
+  //   - incoming == pending  → suppressed (nothing new)
+  //   - incoming  > pending  → accepted (genuinely newer, falls through)
+  //   - incoming  < pending  → suppressed (downgrade — user already knows)
+  if (pendingUpdateVersion && !semver.gt(incomingVersion, pendingUpdateVersion)) {
+    return res.json({ ok: true, notified: false, reason: 'not_newer_than_pending' });
+  }
+
+  pendingUpdateVersion = incomingVersion;
+  logger.info(`New version available: ${incomingVersion} (running ${version})`);
+
+  res.json({ ok: true, notified: true });
+});
+
 /**
  * Get repository-specific settings
  * Returns default_instructions, default_provider, and default_model for the repository
@@ -328,4 +372,14 @@ router.post('/api/providers/refresh-availability', async (req, res) => {
   }
 });
 
+/**
+ * Test-only helper: reset the in-memory pending-update state.
+ * Not exported from index — intended for use by integration tests that
+ * share the same module instance and need isolation between cases.
+ */
+function _resetPendingUpdate() {
+  pendingUpdateVersion = null;
+}
+
 module.exports = router;
+module.exports._resetPendingUpdate = _resetPendingUpdate;

package/src/routes/local.js

@@ -35,6 +35,7 @@ const { getProviderClass, createProvider } = require('../ai/provider');
 const { getDefaultBranch, tryGraphiteState } = require('../git/base-branch');
 const { CommentRepository } = require('../database');
 const { runExecutableAnalysis, getChangedFiles } = require('./executable-analysis');
+const { rejectUrlLikeLocalReviewPath } = require('../utils/local-path-input');
 const {
   activeAnalyses,
   localReviewDiffs,
@@ -380,6 +381,12 @@ router.post('/api/local/start', async (req, res) => {
       });
     }
 
+    try {
+      rejectUrlLikeLocalReviewPath(inputPath);
+    } catch (err) {
+      return res.status(400).json({ error: err.message });
+    }
+
     // Required inline (not reusing top-level import) so that vi.spyOn()
     // replacements on the module exports are visible at call time in integration tests.
     const { findGitRoot, getHeadSha, getRepositoryName, getCurrentBranch } = require('../local-review');

package/src/routes/setup.js

@@ -18,6 +18,7 @@ const { setupLocalReview } = require('../setup/local-setup');
 const { getGitHubToken, expandPath } = require('../config');
 const { queryOne, ReviewRepository } = require('../database');
 const { normalizeRepository } = require('../utils/paths');
+const { rejectUrlLikeLocalReviewPath } = require('../utils/local-path-input');
 const logger = require('../utils/logger');
 
 const router = express.Router();
@@ -186,6 +187,12 @@ router.post('/api/setup/local', async (req, res) => {
       return res.status(400).json({ error: 'Missing required field: path' });
     }
 
+    try {
+      rejectUrlLikeLocalReviewPath(rawPath);
+    } catch (err) {
+      return res.status(400).json({ error: err.message });
+    }
+
     const targetPath = expandPath(rawPath);
     const db = req.app.get('db');
 

package/src/routes/stack-analysis.js

@@ -220,7 +220,7 @@ async function executeStackAnalysis(params) {
     // 2. Bulk fetch all PR refs (runs against trigger worktree)
     const refspecs = prNumbers.map(n => `+refs/pull/${n}/head:refs/remotes/origin/pr-${n}`);
     try {
-      deps.execSync(`git fetch origin ${refspecs.join(' ')}`, {
+      deps.execSync(`git fetch --no-tags origin ${refspecs.join(' ')}`, {
         cwd: triggerWorktreePath, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
         timeout: 60000
       });

package/src/server.js

@@ -14,6 +14,19 @@ let db = null;
 let server = null;
 let chatSessionManager = null;
 
+/**
+ * Apply env var overrides to config after loadConfig().
+ * Currently handles PAIR_REVIEW_SINGLE_PORT — a bridge for callers that
+ * need to force multi-port mode (e.g. mcp-stdio.js). Matches the
+ * PAIR_REVIEW_YOLO bridge pattern.
+ */
+function applyEnvOverrides(config) {
+  if (process.env.PAIR_REVIEW_SINGLE_PORT === 'false') {
+    config.single_port = false;
+  }
+  return config;
+}
+
 /**
  * Request logging middleware (disabled for cleaner output)
  */
@@ -93,6 +106,7 @@ async function startServer(sharedDb = null, sharedPoolLifecycle = null) {
   try {
     // Load configuration
     const { config } = await loadConfig();
+    applyEnvOverrides(config);
 
     // Apply provider configuration overrides (custom models, commands, etc.)
     applyConfigOverrides(config);
@@ -294,9 +308,14 @@ async function startServer(sharedDb = null, sharedPoolLifecycle = null) {
       res.sendFile(path.join(__dirname, '..', 'public', 'local.html'));
     });
 
-    // Health check endpoint
+    // Health check endpoint (also used by single-port detection)
     app.get('/health', (req, res) => {
-      res.json({ status: 'ok', timestamp: new Date().toISOString() });
+      res.json({
+        status: 'ok',
+        service: 'pair-review',
+        version: require('../package.json').version,
+        timestamp: new Date().toISOString()
+      });
     });
     
     // Store database instance, GitHub token, and config for routes
@@ -365,7 +384,9 @@ async function startServer(sharedDb = null, sharedPoolLifecycle = null) {
     });
     
     // Find available port and start server
-    const port = await findAvailablePort(app, config.port);
+    const port = config.single_port !== false
+      ? config.port  // single-port mode: use exact port, fail if unavailable
+      : await findAvailablePort(app, config.port);
 
     // Check provider availability before accepting requests so /api/config
     // returns accurate pi_available on the very first request (avoids race
@@ -381,14 +402,35 @@ async function startServer(sharedDb = null, sharedPoolLifecycle = null) {
       console.warn('Provider availability check failed:', err.message);
     }
 
-    server = app.listen(port, () => {
-      console.log(`Server running on http://localhost:${port}`);
-      attachWebSocket(server, db, poolLifecycle);
+    await new Promise((resolve, reject) => {
+      server = app.listen(port, () => {
+        console.log(`Server running on http://localhost:${port}`);
+        attachWebSocket(server, db, poolLifecycle);
+        resolve();
+      });
+
+      // .once instead of .on: this handler detaches after firing exactly once,
+      // so the post-startup handler below doesn't double-handle EADDRINUSE/EACCES
+      // during the initial bind.
+      server.once('error', (error) => {
+        if (error.code === 'EADDRINUSE' && config.single_port !== false) {
+          reject(new Error(
+            `Port ${port} is already in use. A pair-review server may already be running, ` +
+            `or another service is using this port. ` +
+            `Set "single_port": false in ~/.pair-review/config.json to use automatic port selection.`
+          ));
+        } else {
+          reject(error);
+        }
+      });
     });
 
+    // Post-startup error handler. Express middleware handles request-level errors,
+    // so this only fires for lower-level issues like accept-loop failures (EMFILE,
+    // ENFILE from file descriptor exhaustion). Log but do NOT process.exit — the
+    // old code did that and it was too aggressive for transient errors.
     server.on('error', (error) => {
-      console.error('Server error:', error);
-      process.exit(1);
+      console.error('Server error after startup:', error);
     });
 
     // Return the actual port the server started on
@@ -468,4 +510,4 @@ if (require.main === module) {
   startServer();
 }
 
-module.exports = { startServer };
+module.exports = { startServer, applyEnvOverrides };

package/src/setup/local-setup.js

@@ -6,6 +6,7 @@ const { fireHooks, hasHooks } = require('../hooks/hook-runner');
 const { buildReviewStartedPayload, buildReviewLoadedPayload, getCachedUser } = require('../hooks/payloads');
 const { STOPS, DEFAULT_SCOPE, reviewScope } = require('../local-scope');
 const logger = require('../utils/logger');
+const { LOCAL_REVIEW_PATH_URL_ERROR, rejectUrlLikeLocalReviewPath } = require('../utils/local-path-input');
 const path = require('path');
 const fs = require('fs').promises;
 
@@ -31,11 +32,14 @@ async function setupLocalReview({ db, targetPath, onProgress, config }) {
   let resolvedPath;
   try {
     progress({ step: 'validate', status: 'running', message: 'Validating target path...' });
+    rejectUrlLikeLocalReviewPath(targetPath);
     resolvedPath = path.resolve(targetPath);
     await fs.access(resolvedPath);
     progress({ step: 'validate', status: 'completed', message: `Path resolved to ${resolvedPath}` });
   } catch (err) {
-    const message = `Path does not exist: ${path.resolve(targetPath)}`;
+    const message = err.message === LOCAL_REVIEW_PATH_URL_ERROR
+      ? err.message
+      : `Path does not exist: ${path.resolve(targetPath)}`;
     progress({ step: 'validate', status: 'error', message });
     throw new Error(message);
   }

package/src/setup/pr-setup.js

@@ -17,7 +17,7 @@ const { WorktreePoolLifecycle } = require('../git/worktree-pool-lifecycle');
 const { GitHubClient } = require('../github/client');
 const { normalizeRepository } = require('../utils/paths');
 const { findMainGitRoot } = require('../local-review');
-const { getConfigDir, getRepoPath, resolveRepoOptions, getRepoPoolSize, getRepoResetScript, DEFAULT_CHECKOUT_TIMEOUT_MS } = require('../config');
+const { getConfigDir, getRepoPath, resolveRepoOptions, resolvePoolConfig, getRepoResetScript, DEFAULT_CHECKOUT_TIMEOUT_MS } = require('../config');
 const logger = require('../utils/logger');
 const { fireReviewStartedHook } = require('../hooks/payloads');
 const simpleGit = require('simple-git');
@@ -229,6 +229,7 @@ async function findRepositoryPath({ db, owner, repo, repository, prNumber, confi
   const worktreeManager = new GitWorktreeManager(db);
   const repoSettingsRepo = new RepoSettingsRepository(db);
   const worktreeRepo = new WorktreeRepository(db);
+  const repoSettings = await repoSettingsRepo.getRepoSettings(repository);
 
   let repositoryPath = null;
   let worktreeSourcePath = null;  // Path to use as cwd for `git worktree add` (may differ from repositoryPath)
@@ -288,7 +289,7 @@ async function findRepositoryPath({ db, owner, repo, repository, prNumber, confi
   // ------------------------------------------------------------------
   // Resolve monorepo worktree options (checkout_script, worktree_directory, worktree_name_template)
   // ------------------------------------------------------------------
-  const resolved = config ? resolveRepoOptions(config, repository) : { checkoutScript: null, checkoutTimeout: DEFAULT_CHECKOUT_TIMEOUT_MS, worktreeConfig: null };
+  const resolved = config ? resolveRepoOptions(config, repository, repoSettings) : { checkoutScript: null, checkoutTimeout: DEFAULT_CHECKOUT_TIMEOUT_MS, worktreeConfig: null };
   const { checkoutScript, checkoutTimeout, worktreeConfig } = resolved;
 
   // When a checkout script is configured, null out worktreeSourcePath —
@@ -301,7 +302,7 @@ async function findRepositoryPath({ db, owner, repo, repository, prNumber, confi
   // ------------------------------------------------------------------
   // Tier 0: Check known local path from repo_settings
   // ------------------------------------------------------------------
-  const knownPath = await repoSettingsRepo.getLocalPath(repository);
+  const knownPath = repoSettings?.local_path || null;
 
   if (!repositoryPath && knownPath && await worktreeManager.pathExists(knownPath)) {
     try {
@@ -464,7 +465,9 @@ async function setupPRReview({ db, owner, repo, prNumber, githubToken, config, o
   // Step: worktree - Create git worktree for the PR
   // ------------------------------------------------------------------
   const prInfo = { owner, repo, number: prNumber };
-  const poolSize = config ? getRepoPoolSize(config, repository) : 0;
+  const repoSettingsRepo = new RepoSettingsRepository(db);
+  const repoSettings = await repoSettingsRepo.getRepoSettings(repository);
+  const { poolSize } = resolvePoolConfig(config || {}, repository, repoSettings);
   const resetScript = config ? getRepoResetScript(config, repository) : null;
 
   let worktreePath;

package/src/single-port.js

@@ -0,0 +1,193 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+const http = require('http');
+const path = require('path');
+const semver = require('semver');
+const { PRArgumentParser } = require('./github/parser');
+const logger = require('./utils/logger');
+const { rejectUrlLikeLocalReviewPath } = require('./utils/local-path-input');
+const { version: packageVersion } = require('../package.json');
+
+const HEALTH_TIMEOUT_MS = 2000;
+
+// Default dependencies (overridable for testing)
+const defaults = {
+  httpGet: http.get,
+  httpRequest: http.request,
+  logger,
+  open: (...args) => process.env.PAIR_REVIEW_NO_OPEN
+    ? Promise.resolve()
+    : import('open').then(({ default: open }) => open(...args)),
+  PRArgumentParser
+};
+
+/**
+ * Check if a pair-review server is already running on the given port.
+ * @param {number} port
+ * @param {object} [_deps] - Dependency overrides for testing
+ * @returns {Promise<{running: boolean, isPairReview?: boolean, version?: string}>}
+ */
+function detectRunningServer(port, _deps) {
+  const deps = { ...defaults, ..._deps };
+  return new Promise((resolve) => {
+    const req = deps.httpGet(`http://localhost:${port}/health`, { timeout: HEALTH_TIMEOUT_MS }, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        try {
+          const body = JSON.parse(data);
+          if (body.service === 'pair-review') {
+            resolve({ running: true, isPairReview: true, version: body.version || null });
+          } else {
+            resolve({ running: true, isPairReview: false });
+          }
+        } catch {
+          resolve({ running: true, isPairReview: false });
+        }
+      });
+    });
+
+    req.on('error', () => {
+      resolve({ running: false });
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      resolve({ running: false });
+    });
+  });
+}
+
+/**
+ * Notify the running server that a newer version is available.
+ * Fire-and-forget — does not block on response.
+ * @param {number} port
+ * @param {string} currentVersion - Version of the current CLI invocation
+ * @param {object} [_deps] - Dependency overrides for testing
+ */
+function notifyVersion(port, currentVersion, _deps) {
+  const deps = { ...defaults, ..._deps };
+  const payload = JSON.stringify({ version: currentVersion });
+  const req = deps.httpRequest({
+    hostname: 'localhost',
+    port,
+    path: '/api/notify-update',
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Content-Length': Buffer.byteLength(payload)
+    },
+    timeout: HEALTH_TIMEOUT_MS
+  }, () => { /* ignore response */ });
+
+  req.on('error', () => { /* fire and forget */ });
+  req.on('timeout', () => { req.destroy(); });
+  req.write(payload);
+  req.end();
+}
+
+/**
+ * Build the URL to delegate to an existing server.
+ * @param {number} port
+ * @param {'pr'|'local'|'server'} mode
+ * @param {object} context
+ * @param {string} [context.owner]
+ * @param {string} [context.repo]
+ * @param {number} [context.number]
+ * @param {string} [context.localPath]
+ * @param {boolean} [context.analyze] - Whether to trigger auto-analysis
+ * @returns {string} Full URL
+ */
+function buildDelegationUrl(port, mode, context = {}) {
+  const base = `http://localhost:${port}`;
+  if (mode === 'pr') {
+    let url = `${base}/pr/${context.owner}/${context.repo}/${context.number}`;
+    if (context.analyze) url += '?analyze=true';
+    return url;
+  }
+  if (mode === 'local') {
+    let url = `${base}/local?path=${encodeURIComponent(context.localPath)}`;
+    if (context.analyze) url += '&analyze=true';
+    return url;
+  }
+  return `${base}/`;
+}
+
+/**
+ * Parse PR arguments for URL construction without starting a server.
+ * Reuses PRArgumentParser — synchronous for URLs, async for bare numbers.
+ * @param {string[]} prArgs - Raw CLI PR arguments
+ * @param {object} [_deps] - Dependency overrides for testing
+ * @returns {Promise<{owner: string, repo: string, number: number}>}
+ */
+async function parsePRArgsForDelegation(prArgs, _deps) {
+  const deps = { ...defaults, ..._deps };
+  const parser = new deps.PRArgumentParser();
+  return parser.parsePRArguments(prArgs);
+}
+
+/**
+ * Attempt single-port delegation. Returns true if delegation happened (caller should exit).
+ * Returns false if no running server was found (caller should start normally).
+ * Throws if port is occupied by a non-pair-review service.
+ *
+ * @param {object} config - Loaded config
+ * @param {object} flags - Parsed CLI flags
+ * @param {string[]} prArgs - PR arguments from CLI
+ * @param {object} [_deps] - Dependency overrides for testing
+ * @returns {Promise<boolean>} true if delegated, false if should start fresh
+ */
+async function attemptDelegation(config, flags, prArgs, _deps) {
+  const deps = { ...defaults, ..._deps };
+  const port = config.port;
+
+  const result = await detectRunningServer(port, _deps);
+
+  if (result.running && !result.isPairReview) {
+    throw new Error(
+      `Port ${port} is in use by another service. ` +
+      `Either stop that service, or set a different port in ~/.pair-review/config.json`
+    );
+  }
+
+  if (!result.running) {
+    return false;
+  }
+
+  // Server is running — delegate to it
+  deps.logger.info(`Existing pair-review server detected on port ${port} (v${result.version})`);
+
+  // Determine mode and build URL
+  let url;
+  if (flags.local) {
+    rejectUrlLikeLocalReviewPath(flags.localPath);
+    const targetPath = path.resolve(flags.localPath || process.cwd());
+    url = buildDelegationUrl(port, 'local', { localPath: targetPath, analyze: flags.ai });
+  } else if (prArgs.length > 0) {
+    const prInfo = await parsePRArgsForDelegation(prArgs, _deps);
+    url = buildDelegationUrl(port, 'pr', { ...prInfo, analyze: flags.ai });
+  } else {
+    url = buildDelegationUrl(port, 'server');
+  }
+
+  // Notify running server of newer version if applicable
+  if (result.version && semver.valid(packageVersion) && semver.valid(result.version)) {
+    if (semver.gt(packageVersion, result.version)) {
+      deps.logger.info(`Notifying server of newer version: ${packageVersion} > ${result.version}`);
+      notifyVersion(port, packageVersion, _deps);
+    }
+  }
+
+  // Open browser and exit
+  deps.logger.info(`Delegating to running server: ${url}`);
+  await deps.open(url);
+  return true;
+}
+
+module.exports = {
+  detectRunningServer,
+  notifyVersion,
+  buildDelegationUrl,
+  parsePRArgsForDelegation,
+  attemptDelegation,
+  HEALTH_TIMEOUT_MS
+};