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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@in-the-loop-labs/pair-review",
-  "version": "3.3.7",
+  "version": "3.4.0",
   "description": "Your AI-powered code review partner - Close the feedback loop with AI coding agents",
   "main": "src/server.js",
   "bin": {
@@ -68,6 +68,7 @@
     "glob": "^13.0.6",
     "markdown-it": "^13.0.2",
     "open": "^9.1.0",
+    "semver": "^7.7.4",
     "simple-git": "^3.19.1",
     "update-notifier": "^5.1.0",
     "uuid": "^11.1.0",

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

@@ -1,6 +1,6 @@
 {
   "name": "pair-review",
-  "version": "3.3.7",
+  "version": "3.4.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": "3.3.7",
+  "version": "3.4.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/public/css/styles.css

@@ -31,7 +31,13 @@
     --color-warning-bg: #fffae6;
     --color-warning-border: #ffc552;
     --color-warning-text: #7d4e00;
-    
+
+    --color-info-bg: #eff6ff;
+    --color-info-border: #bfdbfe;
+    --color-info-accent: #3b82f6;
+    --color-info-text: #1e3a8a;
+    --color-info-text-muted: #3b5998;
+
     --color-selection: #fff5b1;
     --color-selection-num: #ffeb3b;
     
@@ -72,7 +78,13 @@
     --color-warning-bg: #3d2e00;
     --color-warning-border: #9e6a03;
     --color-warning-text: #e3b341;
-    
+
+    --color-info-bg: #152033;
+    --color-info-border: #2d4a7a;
+    --color-info-accent: #4a90e2;
+    --color-info-text: #cfe0f5;
+    --color-info-text-muted: #8aa9cf;
+
     --color-selection: #3d3300;
     --color-selection-num: #4d4000;
     

package/public/index.html

@@ -1488,6 +1488,7 @@
 
     <script src="/js/ws-client.js"></script>
     <script src="/js/components/Toast.js"></script>
+    <script src="/js/components/UpdateBanner.js"></script>
     <script src="/js/index.js"></script>
 </body>
 </html>

package/public/js/components/UpdateBanner.js

@@ -0,0 +1,143 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+/**
+ * UpdateBanner Component
+ * Shows a persistent, dismissible corner-card notification when a newer
+ * version of pair-review is available. Single delivery path: on construction,
+ * fetch /api/config and show the banner if a pending_update exists.
+ */
+
+const DISMISS_KEY = 'update-banner-dismissed';
+
+class UpdateBanner {
+  constructor() {
+    this._banner = null;
+    this._dismissBtn = null;
+    this._version = null;
+
+    // Single path: fetch current config at construction; show banner if a
+    // pending update exists. No event listener, no WebSocket coupling.
+    // `fetch()` returns a Promise; `.then()` chains async steps; the final
+    // `.catch()` swallows network errors because the banner is non-critical.
+    fetch('/api/config')
+      .then(r => (r.ok ? r.json() : null))
+      .then(config => {
+        if (config && config.pending_update) this.show(config.pending_update);
+      })
+      .catch(() => { /* non-critical */ });
+  }
+
+  /**
+   * Show the update banner for the given version.
+   * No-op if already showing or dismissed for this version.
+   * @param {string} version
+   */
+  show(version) {
+    if (!version) return;
+
+    // Already dismissed for this version in this session
+    if (sessionStorage.getItem(DISMISS_KEY) === version) return;
+
+    // Already showing this version
+    if (this._banner && this._version === version) return;
+
+    // Remove any existing banner (e.g., for an older version)
+    this._remove();
+
+    this._version = version;
+
+    // Theme-aware colors come from CSS custom properties (set in styles.css
+    // under :root and [data-theme="dark"]). The inline `var(..., fallback)`
+    // form keeps the banner readable even if the stylesheet hasn't loaded
+    // yet. No MutationObserver needed — CSS handles the theme switch.
+    const banner = document.createElement('div');
+    banner.setAttribute('data-update-banner', '');
+    Object.assign(banner.style, {
+      position: 'fixed',
+      top: '16px',
+      left: '16px',
+      zIndex: '1000',
+      maxWidth: '360px',
+      background: 'var(--color-info-bg, #eff6ff)',
+      border: '1px solid var(--color-info-border, #bfdbfe)',
+      borderLeft: '4px solid var(--color-info-accent, #3b82f6)',
+      borderRadius: '8px',
+      boxShadow: '0 4px 12px rgba(0, 0, 0, 0.15)',
+      padding: '12px 14px',
+      fontSize: '13px',
+      lineHeight: '1.4',
+      color: 'var(--color-info-text, #1e3a8a)',
+      display: 'flex',
+      alignItems: 'flex-start',
+      gap: '10px'
+    });
+
+    // Two-line layout: headline + restart instruction on its own line.
+    const text = document.createElement('div');
+    text.style.flex = '1';
+
+    const headline = document.createElement('div');
+    headline.textContent = `pair-review v${version} is available.`;
+
+    const instruction = document.createElement('div');
+    instruction.textContent = 'Restart the server to update.';
+    instruction.style.marginTop = '2px';
+
+    text.appendChild(headline);
+    text.appendChild(instruction);
+
+    const dismissBtn = document.createElement('button');
+    dismissBtn.textContent = '\u00d7';
+    dismissBtn.setAttribute('aria-label', 'Dismiss');
+    Object.assign(dismissBtn.style, {
+      background: 'none',
+      border: 'none',
+      color: 'var(--color-info-text-muted, #3b5998)',
+      cursor: 'pointer',
+      fontSize: '18px',
+      padding: '0',
+      lineHeight: '1',
+      flexShrink: '0',
+      opacity: '0.8'
+    });
+    dismissBtn.addEventListener('click', () => this.dismiss());
+
+    banner.appendChild(text);
+    banner.appendChild(dismissBtn);
+    document.body.appendChild(banner);
+    this._banner = banner;
+    this._dismissBtn = dismissBtn;
+  }
+
+  /** Dismiss the banner and remember the choice for this session. */
+  dismiss() {
+    if (this._version) {
+      sessionStorage.setItem(DISMISS_KEY, this._version);
+    }
+    this._remove();
+  }
+
+  /** @private */
+  _remove() {
+    if (this._banner && this._banner.parentNode) {
+      this._banner.parentNode.removeChild(this._banner);
+    }
+    this._banner = null;
+    this._dismissBtn = null;
+  }
+}
+
+// Singleton init (browser only)
+if (typeof window !== 'undefined' && !window.updateBanner) {
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => {
+      window.updateBanner = new UpdateBanner();
+    });
+  } else {
+    window.updateBanner = new UpdateBanner();
+  }
+}
+
+// CommonJS export for unit tests
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { UpdateBanner };
+}

package/public/js/modules/diff-renderer.js

@@ -64,6 +64,9 @@ class DiffRenderer {
     // Ruby
     'rb': 'ruby',
     'erb': 'erb',
+    // Elixir
+    'ex': 'elixir',
+    'exs': 'elixir',
     // PHP
     'php': 'php',
     // Java/Kotlin/Scala

package/public/local.html

@@ -562,6 +562,7 @@
 
     <!-- Highlight.js for syntax highlighting -->
     <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/elixir.min.js"></script>
 
     <!-- Markdown-it Library for rendering markdown in comments -->
     <script src="https://cdn.jsdelivr.net/npm/markdown-it@13.0.2/dist/markdown-it.min.js"></script>
@@ -591,6 +592,7 @@
     <!-- Components -->
     <script src="/js/components/TabTitle.js"></script>
     <script src="/js/components/Toast.js"></script>
+    <script src="/js/components/UpdateBanner.js"></script>
     <script src="/js/components/ConfirmDialog.js"></script>
     <script src="/js/components/TextInputDialog.js"></script>
     <script src="/js/components/AnalysisConfigModal.js"></script>

package/public/pr.html

@@ -358,6 +358,7 @@
 
     <!-- Highlight.js for syntax highlighting -->
     <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/elixir.min.js"></script>
 
     <!-- Markdown-it Library for rendering markdown in comments -->
     <script src="https://cdn.jsdelivr.net/npm/markdown-it@13.0.2/dist/markdown-it.min.js"></script>
@@ -387,6 +388,7 @@
     <!-- Components -->
     <script src="/js/components/TabTitle.js"></script>
     <script src="/js/components/Toast.js"></script>
+    <script src="/js/components/UpdateBanner.js"></script>
     <script src="/js/components/ConfirmDialog.js"></script>
     <script src="/js/components/TextInputDialog.js"></script>
     <script src="/js/components/AnalysisConfigModal.js"></script>

package/public/setup.html

@@ -528,6 +528,7 @@
 
     <!-- WebSocket client -->
     <script src="/js/ws-client.js"></script>
+    <script src="/js/components/UpdateBanner.js"></script>
     <script src="/js/utils/notification-sounds.js"></script>
 
     <script>

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;

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/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/single-port.js

@@ -0,0 +1,191 @@
+// 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 { 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) {
+    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
+};