@in-the-loop-labs/pair-review 3.3.6 → 3.4.0

package/src/config.js

@@ -19,6 +19,7 @@ const DEFAULT_CONFIG = {
   github_token: "",
   github_token_command: "gh auth token",  // Shell command whose stdout is used as the GitHub token
   port: 7247,
+  single_port: true,  // When true, reuse a single server on the configured port; new invocations delegate to the running server
   theme: "light",
   default_provider: "claude",  // AI provider: 'claude', 'gemini', 'codex', 'copilot', 'opencode', 'cursor-agent', 'pi'
   default_model: "opus",       // Model within the provider (e.g., 'opus' for Claude, 'gemini-2.5-pro' for Gemini)
@@ -128,7 +129,7 @@ async function copyExampleConfig() {
   try {
     await fs.access(sourceExample);
     await fs.copyFile(sourceExample, CONFIG_EXAMPLE_FILE);
-    console.log(`Copied config.example.json to: ${CONFIG_EXAMPLE_FILE}`);
+    logger.info(`Copied config.example.json to: ${CONFIG_EXAMPLE_FILE}`);
     return true;
   } catch (error) {
     if (error.code === 'ENOENT') {
@@ -154,13 +155,13 @@ async function ensureConfigDir() {
     if (error.code === 'ENOENT') {
       try {
         await fs.mkdir(CONFIG_DIR, { recursive: true });
-        console.log(`Created config directory: ${CONFIG_DIR}`);
+        logger.info(`Created config directory: ${CONFIG_DIR}`);
         // Copy example config to new directory
         await copyExampleConfig();
         return true; // Directory was newly created
       } catch (mkdirError) {
         if (mkdirError.code === 'EACCES' || mkdirError.code === 'EPERM') {
-          console.error(`Cannot create configuration directory at ~/.pair-review/`);
+          logger.error(`Cannot create configuration directory at ~/.pair-review/`);
           process.exit(1);
         }
         throw mkdirError;
@@ -211,7 +212,7 @@ async function loadConfig() {
         // Optional files or managed-config-present: skip silently
       } else if (error instanceof SyntaxError) {
         if (source.required) {
-          console.error(`Invalid configuration file at ~/.pair-review/config.json`);
+          logger.error(`Invalid configuration file at ~/.pair-review/config.json`);
           process.exit(1);
         }
         logger.warn(`Malformed config at ${source.label}, skipping`);
@@ -235,9 +236,19 @@ async function loadConfig() {
     mergedConfig.repos = normalized;
   }
 
+  // PORT env var overrides all config layers (used by Preview and similar harnesses)
+  if (process.env.PORT) {
+    const envPort = Number(process.env.PORT);
+    if (!validatePort(envPort)) {
+      logger.error(`Invalid PORT env var "${process.env.PORT}" (must be an integer between 1024 and 65535)`);
+      process.exit(1);
+    }
+    mergedConfig.port = envPort;
+  }
+
   // Validate port
   if (!validatePort(mergedConfig.port)) {
-    console.error(`Invalid port number ${mergedConfig.port}`);
+    logger.error(`Invalid port number ${mergedConfig.port}`);
     process.exit(1);
   }
 
@@ -269,7 +280,7 @@ async function saveConfig(config) {
     await fs.writeFile(CONFIG_FILE, JSON.stringify(config, null, 2));
   } catch (error) {
     if (error.code === 'EACCES' || error.code === 'EPERM') {
-      console.error(`Cannot create configuration directory at ~/.pair-review/`);
+      logger.error(`Cannot create configuration directory at ~/.pair-review/`);
       process.exit(1);
     }
     throw error;
@@ -517,6 +528,17 @@ function getRepoResetScript(config, repository) {
   return repoConfig?.reset_script || null;
 }
 
+/**
+ * Gets whether updateWorktree should skip the bulk `git fetch <remote> --prune`
+ * @param {Object} config - Configuration object from loadConfig()
+ * @param {string} repository - Repository in "owner/repo" format
+ * @returns {boolean} - true if the bulk fetch should be skipped (default: false)
+ */
+function getRepoSkipBulkFetch(config, repository) {
+  const repoConfig = getRepoConfig(config, repository);
+  return repoConfig?.skip_bulk_fetch === true;
+}
+
 /**
  * Gets the configured pool size for a repository from file config only.
  * Prefer resolvePoolConfig() when DB repo_settings are available.
@@ -750,6 +772,7 @@ module.exports = {
   getRepoCheckoutTimeout,
   resolveRepoOptions,
   getRepoResetScript,
+  getRepoSkipBulkFetch,
   getRepoPoolSize,
   getRepoPoolFetchInterval,
   getRepoLoadSkills,

package/src/git/diff-flags.js

@@ -30,12 +30,16 @@ const GIT_DIFF_FLAGS_ARRAY = [
 
 /**
  * Array form for simple-git .diffSummary() calls.
+ * Use --numstat so simple-git parses machine-readable output with exact file paths.
+ * The default --stat output is display-oriented and may abbreviate long paths,
+ * which breaks downstream matching for generated route files and similar cases.
  * Omits --src-prefix/--dst-prefix since diffSummary doesn't output file content with prefixes.
  */
 const GIT_DIFF_SUMMARY_FLAGS_ARRAY = [
   '--no-color',
   '--no-ext-diff',
-  '--no-relative'
+  '--no-relative',
+  '--numstat'
 ];
 
 module.exports = {

package/src/git/worktree.js

@@ -733,9 +733,11 @@ class GitWorktreeManager {
    * @param {string} repo - Repository name
    * @param {number} number - PR number
    * @param {Object} prData - PR data from GitHub API (for remote resolution)
+   * @param {Object} [options]
+   * @param {boolean} [options.skipBulkFetch=false] - Skip the bulk `git fetch <remote> --prune`; targeted base-SHA and PR-head fetches still run
    * @returns {Promise<string>} Path to updated worktree
    */
-  async updateWorktree(owner, repo, number, prData) {
+  async updateWorktree(owner, repo, number, prData, options = {}) {
     const prInfo = { owner, repo, number };
     const headSha = this.getPRHeadSha(prData);
     const worktreePath = await this.getWorktreePath(prInfo);
@@ -756,9 +758,26 @@ class GitWorktreeManager {
       const remote = await this.resolveRemoteForPR(worktreeGit, prData, prInfo);
 
       // Fetch the latest from the resolved remote (--prune removes stale
-      // tracking refs that would otherwise block fetch on ref hierarchy conflicts)
-      console.log(`Fetching latest changes from ${remote}...`);
-      await worktreeGit.fetch([remote, '--prune']);
+      // tracking refs that would otherwise block fetch on ref hierarchy conflicts).
+      // Opt out via skip_bulk_fetch on very large monorepos where this is too slow;
+      // the targeted base-SHA and PR-head ref fetches below still run.
+      if (options.skipBulkFetch) {
+        console.log(`Skipping bulk fetch from ${remote} (skip_bulk_fetch enabled)`);
+        // Still fetch only the PR's base branch so ensureBaseShaAvailable does not
+        // have to fall back to `git fetch <remote> <sha>`, which some Git servers
+        // and mirrors reject (they require uploadpack.allowReachableSHA1InWant).
+        // This mirrors the targeted fetch used in createWorktreeForPR.
+        if (prData?.base_branch) {
+          try {
+            await worktreeGit.fetch([remote, `+refs/heads/${prData.base_branch}:refs/remotes/${remote}/${prData.base_branch}`]);
+          } catch (fetchError) {
+            console.warn(`Targeted base-branch fetch failed, will rely on existing refs: ${fetchError.message}`);
+          }
+        }
+      } else {
+        console.log(`Fetching latest changes from ${remote}...`);
+        await worktreeGit.fetch([remote, '--prune']);
+      }
 
       await this.ensureBaseShaAvailable(worktreeGit, prData, remote);
 

package/src/local-review.js

@@ -1,5 +1,5 @@
 // Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
-const { execSync, exec } = require('child_process');
+const { execSync, exec, execFileSync } = require('child_process');
 const { promisify } = require('util');
 const crypto = require('crypto');
 const path = require('path');
@@ -15,7 +15,7 @@ const { initializeDatabase, ReviewRepository, RepoSettingsRepository } = require
 const { startServer } = require('./server');
 const { localReviewDiffs } = require('./routes/shared');
 const { getShaAbbrevLength } = require('./git/sha-abbrev');
-const { GIT_DIFF_FLAGS } = require('./git/diff-flags');
+const { GIT_DIFF_FLAGS, GIT_DIFF_FLAGS_ARRAY } = require('./git/diff-flags');
 const open = (...args) => process.env.PAIR_REVIEW_NO_OPEN ? Promise.resolve() : import('open').then(({ default: open }) => open(...args));
 
 // Design note: This module uses execSync for git commands despite async function signatures.
@@ -393,12 +393,23 @@ async function findMergeBase(repoPath, baseBranch) {
  * Generate diff output for untracked files using git diff --no-index.
  * @param {string} repoPath - Path to the git repository
  * @param {Array} untrackedFiles - Array from getUntrackedFiles()
- * @param {string} wFlag - Whitespace flag (e.g. ' -w' or '')
- * @param {string} [contextFlag=''] - Unified context flag (e.g. ' --unified=3')
- * @param {string} [extraArgsStr=''] - Additional git diff flags (e.g. ' --patience')
+ * @param {Object} [options]
+ * @param {boolean} [options.hideWhitespace=false] - Whether to pass -w
+ * @param {number} [options.contextLines=25] - Number of unified context lines
+ * @param {string[]} [options.extraArgs=[]] - Additional git diff flags
  * @returns {string} Combined diff text for untracked files
  */
-function generateUntrackedDiffs(repoPath, untrackedFiles, wFlag, contextFlag = '', extraArgsStr = '') {
+function generateUntrackedDiffs(repoPath, untrackedFiles, options = {}) {
+  const diffArgs = [
+    'diff',
+    '--no-index',
+    ...GIT_DIFF_FLAGS_ARRAY,
+    `--unified=${options.contextLines ?? 25}`,
+    ...(options.extraArgs || []),
+    ...(options.hideWhitespace ? ['-w'] : []),
+    '--',
+    '/dev/null'
+  ];
   let diff = '';
   for (const untracked of untrackedFiles) {
     if (!untracked.skipped) {
@@ -406,16 +417,21 @@ function generateUntrackedDiffs(repoPath, untrackedFiles, wFlag, contextFlag = '
         const filePath = path.join(repoPath, untracked.file);
         let fileDiff;
         try {
-          fileDiff = execSync(`git diff --no-index ${GIT_DIFF_FLAGS}${contextFlag}${extraArgsStr}${wFlag} -- /dev/null "${filePath}"`, {
+          fileDiff = execFileSync('git', [...diffArgs, filePath], {
             cwd: repoPath,
             encoding: 'utf8',
             stdio: ['pipe', 'pipe', 'pipe'],
             maxBuffer: 10 * 1024 * 1024
           });
         } catch (diffError) {
+          const diffStdout = typeof diffError?.stdout === 'string'
+            ? diffError.stdout
+            : Buffer.isBuffer(diffError?.stdout)
+              ? diffError.stdout.toString('utf8')
+              : null;
           if (diffError && typeof diffError === 'object' &&
-              diffError.status === GIT_DIFF_HAS_DIFFERENCES && typeof diffError.stdout === 'string') {
-            fileDiff = diffError.stdout;
+              diffError.status === GIT_DIFF_HAS_DIFFERENCES && diffStdout !== null) {
+            fileDiff = diffStdout;
           } else {
             throw diffError;
           }
@@ -552,7 +568,7 @@ async function generateScopedDiff(repoPath, scopeStart, scopeEnd, baseBranch, op
     const untrackedFiles = await getUntrackedFiles(repoPath);
     stats.untrackedFiles = untrackedFiles.length;
 
-    const untrackedDiff = generateUntrackedDiffs(repoPath, untrackedFiles, wFlag, contextFlag, extraArgsStr);
+    const untrackedDiff = generateUntrackedDiffs(repoPath, untrackedFiles, options);
     if (untrackedDiff) {
       if (diff) diff += '\n';
       diff += untrackedDiff;

package/src/main.js

@@ -20,6 +20,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;
 
@@ -432,26 +433,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 +457,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

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/pr.js

@@ -25,7 +25,7 @@ const Analyzer = require('../ai/analyzer');
 const { v4: uuidv4 } = require('uuid');
 const fs = require('fs').promises;
 const path = require('path');
-const { getGitHubToken, getWorktreeDisplayName, resolveLoadSkills, buildCouncilProviderOverrides } = require('../config');
+const { getGitHubToken, getWorktreeDisplayName, resolveLoadSkills, buildCouncilProviderOverrides, getRepoSkipBulkFetch } = require('../config');
 const logger = require('../utils/logger');
 const { buildDiffLineSet } = require('../utils/diff-annotator');
 const { broadcastReviewEvent } = require('../events/review-events');
@@ -45,6 +45,7 @@ const {
   registerProcess: registerProcessForCancellation
 } = require('./shared');
 const { safeParseJson } = require('../utils/safe-parse-json');
+const { mergeChangedFilesWithDiff } = require('../utils/diff-file-list');
 const { resolveOriginalFileContentSpecs } = require('../utils/diff-file-content');
 const { validateCouncilConfig, normalizeCouncilConfig } = require('./councils');
 const { TIERS, TIER_ALIASES, VALID_TIERS, resolveTier } = require('../ai/prompts/config');
@@ -254,6 +255,8 @@ router.get('/api/pr/:owner/:repo/:number', async (req, res) => {
     }
 
     // Prepare response
+    const changedFiles = mergeChangedFilesWithDiff(extendedData.changed_files || [], extendedData.diff || '');
+
     // Use review.id instead of prMetadata.id to avoid ID collision with local mode
     const response = {
       success: true,
@@ -274,8 +277,8 @@ router.get('/api/pr/:owner/:repo/:number', async (req, res) => {
         shaAbbrevLength,
         created_at: prMetadata.created_at,
         updated_at: prMetadata.updated_at,
-        file_changes: extendedData.changed_files ? extendedData.changed_files.length : 0,
-        changed_files: extendedData.changed_files || [],
+        file_changes: changedFiles.length,
+        changed_files: changedFiles,
         additions: extendedData.additions || 0,
         deletions: extendedData.deletions || 0,
         diff_content: extendedData.diff || '',
@@ -375,7 +378,13 @@ router.post('/api/pr/:owner/:repo/:number/refresh', async (req, res) => {
 
     // Update worktree with latest changes
     const worktreeManager = new GitWorktreeManager(db);
-    const worktreePath = await worktreeManager.updateWorktree(owner, repo, prNumber, prData);
+    const worktreePath = await worktreeManager.updateWorktree(
+      owner,
+      repo,
+      prNumber,
+      prData,
+      { skipBulkFetch: getRepoSkipBulkFetch(config, repository) }
+    );
 
     // Generate fresh diff and get changed files
     const diffPrData = {
@@ -759,6 +768,8 @@ router.get('/api/pr/:owner/:repo/:number/diff', async (req, res) => {
     let diffContent = prData.diff || '';
     let changedFiles = prData.changed_files || [];
 
+    let gitattributes = null;
+
     if (hideWhitespace && worktreeRecord && worktreeRecord.path) {
       try {
         const worktreePath = worktreeRecord.path;
@@ -774,7 +785,7 @@ router.get('/api/pr/:owner/:repo/:number/diff', async (req, res) => {
 
           const summaryArgs = [`${baseSha}...${headSha}`, ...GIT_DIFF_SUMMARY_FLAGS_ARRAY, '-w'];
           const diffSummary = await git.diffSummary(summaryArgs);
-          const gitattributes = await getGeneratedFilePatterns(worktreePath);
+          gitattributes = await getGeneratedFilePatterns(worktreePath);
           changedFiles = diffSummary.files.map(file => {
             const resolvedFile = resolveRenamedFile(file.file);
             const isRenamed = resolvedFile !== file.file;
@@ -799,17 +810,22 @@ router.get('/api/pr/:owner/:repo/:number/diff', async (req, res) => {
     } else if (worktreeRecord && worktreeRecord.path) {
       // Add generated flag to changed files based on .gitattributes
       try {
-        const gitattributes = await getGeneratedFilePatterns(worktreeRecord.path);
-        changedFiles = changedFiles.map(file => ({
-          ...file,
-          generated: gitattributes.isGenerated(file.file)
-        }));
+        gitattributes = await getGeneratedFilePatterns(worktreeRecord.path);
       } catch (error) {
         logger.warn(`Could not load .gitattributes: ${error.message}`);
         // Continue without generated flags
       }
     }
 
+    changedFiles = mergeChangedFilesWithDiff(changedFiles, diffContent);
+
+    if (gitattributes) {
+      changedFiles = changedFiles.map(file => ({
+        ...file,
+        generated: gitattributes.isGenerated(file.file)
+      }));
+    }
+
     // When diff was regenerated (whitespace), compute aggregate stats from
     // the regenerated changedFiles instead of using stale cached values from prData.
     const additions = hideWhitespace

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 };