@in-the-loop-labs/pair-review 4.0.0 → 4.1.0

package/src/routes/shared.js

@@ -68,6 +68,89 @@ function getModel(req) {
   return 'opus';
 }
 
+/**
+ * Get the provider to use for AI analysis
+ * Priority: CLI flag (PAIR_REVIEW_PROVIDER env var) > config.default_provider
+ *           > config.provider (legacy) > 'claude' default
+ * Mirrors getModel() so the --provider CLI flag / PAIR_REVIEW_PROVIDER env var
+ * is honored by the web/UI analysis paths the same way --model is.
+ * @param {Object} req - Express request object
+ * @returns {string} Provider id to use
+ */
+function getProvider(req) {
+  // CLI flag takes priority (passed via environment variable)
+  if (process.env.PAIR_REVIEW_PROVIDER) {
+    return process.env.PAIR_REVIEW_PROVIDER;
+  }
+
+  // Config file setting (default_provider preferred, provider for backwards compatibility)
+  const config = req.app.get('config');
+  if (config) {
+    if (config.default_provider) {
+      return config.default_provider;
+    }
+    // Backwards compatibility with old config key
+    if (config.provider) {
+      return config.provider;
+    }
+  }
+
+  // Default fallback
+  return 'claude';
+}
+
+/**
+ * Resolve the provider/model pair for a web/UI-triggered analysis.
+ *
+ * Precedence (highest first):
+ *   1. request body (requestProvider / requestModel)
+ *   2. env/CLI override (PAIR_REVIEW_PROVIDER / PAIR_REVIEW_MODEL, via getProvider/getModel)
+ *   3. saved repo settings (default_provider / default_model)
+ *   4. config/legacy defaults (via getProvider/getModel, ending at 'claude'/'opus')
+ *
+ * The env/CLI override intentionally outranks saved repo settings to match the
+ * documented `CLI/env > repo settings` contract already honored by the
+ * headless/stack/MCP paths. Because getProvider()/getModel() read the env var
+ * first, calling them in the env branch returns the override; the final branch
+ * (reached only when the env var is unset) returns config/legacy/default.
+ *
+ * Both the PR route (src/routes/pr.js) and the local route (src/routes/local.js)
+ * MUST use this helper so the two paths resolve the same pair — keeping the
+ * resolution logic in one place prevents the paths from silently diverging.
+ *
+ * @param {Object} req - Express request (source of config + env-backed helpers)
+ * @param {Object} [opts]
+ * @param {string} [opts.requestProvider] - provider from the request body
+ * @param {string} [opts.requestModel] - model from the request body
+ * @param {Object} [opts.repoSettings] - saved repo settings row (may be null)
+ * @returns {{ provider: string, model: string }}
+ */
+function resolveProviderModel(req, { requestProvider, requestModel, repoSettings } = {}) {
+  let provider;
+  if (requestProvider) {
+    provider = requestProvider;
+  } else if (process.env.PAIR_REVIEW_PROVIDER) {
+    provider = getProvider(req); // env/CLI override
+  } else if (repoSettings && repoSettings.default_provider) {
+    provider = repoSettings.default_provider;
+  } else {
+    provider = getProvider(req); // config/legacy/'claude'
+  }
+
+  let model;
+  if (requestModel) {
+    model = requestModel;
+  } else if (process.env.PAIR_REVIEW_MODEL) {
+    model = getModel(req); // env/CLI override
+  } else if (repoSettings && repoSettings.default_model) {
+    model = repoSettings.default_model;
+  } else {
+    model = getModel(req); // config/legacy/'opus'
+  }
+
+  return { provider, model };
+}
+
 /**
  * Determine completion level and suggestion counts from analysis result
  * @param {Object} result - Analysis result object
@@ -474,6 +557,8 @@ module.exports = {
   activeProcesses,
   activeSetups,
   getModel,
+  getProvider,
+  resolveProviderModel,
   determineCompletionInfo,
   broadcastProgress,
   broadcastIndexAnalysisEvent,

package/src/routes/stack-analysis.js

@@ -20,6 +20,7 @@ const { mergeInstructions } = require('../utils/instructions');
 const { GitWorktreeManager } = require('../git/worktree');
 const { GitHubClient } = require('../github/client');
 const { getGitHubToken, resolveHostBinding, resolveBindingRepositoryFromPR, resolveRepoOptions, resolveLoadSkills, buildCouncilProviderOverrides } = require('../config');
+const { storedHostToOption } = require('../utils/host-resolution');
 const { setupStackPR } = require('../setup/stack-setup');
 const Analyzer = require('../ai/analyzer');
 const { getProviderClass, createProvider } = require('../ai/provider');
@@ -253,7 +254,14 @@ async function executeStackAnalysis(params) {
     // monorepo-style `url_pattern` configs (one `repos[...]` entry serves many
     // captured owner/repo pairs). The PR identity is still used for DB rows and
     // worktree identity.
-    const stackBinding = deps.resolveHostBinding(bindingRepository, config);
+    // Resolve the stack binding from the MAIN (trigger) PR's stored host so every
+    // sibling is fetched from — and later stamped with — the same host. Stacks
+    // don't span systems, so a dual repo's alt-hosted stack must not fall back to
+    // github via the two-arg ambiguity rule. `storedHostToOption` applies the
+    // legacy-NULL convention; `undefined` (no row) preserves the ambiguity rule.
+    const mainStoredHost = await new PRMetadataRepository(db).getPRHost(repository, triggerPRNumber);
+    const stackHostOption = storedHostToOption(config, bindingRepository, mainStoredHost);
+    const stackBinding = deps.resolveHostBinding(bindingRepository, config, stackHostOption || {});
     const githubToken = stackBinding.token;
     const prDataMap = new Map();
     if (githubToken) {
@@ -365,6 +373,32 @@ async function executeStackAnalysis(params) {
   }
 }
 
+/**
+ * Resolve the provider/model pair for a single/executable stack analysis.
+ *
+ * Precedence (highest first): request body > env/CLI override
+ * (PAIR_REVIEW_PROVIDER / PAIR_REVIEW_MODEL) > saved repo settings >
+ * config default > legacy config key > hard default ('claude' / 'opus').
+ *
+ * Both env vars are read together so a CLI invocation like
+ * `pair-review 123 --provider codex --model gpt-5.5` (which mirrors BOTH flags
+ * into the environment) resolves the requested pair, rather than pairing a
+ * non-default provider with a default Claude model.
+ *
+ * @param {Object} [args]
+ * @param {string} [args.reqProvider] - provider from the analysis request body
+ * @param {string} [args.reqModel] - model from the analysis request body
+ * @param {Object} [args.repoSettings] - saved repo settings row (may be null)
+ * @param {Object} [args.config] - loaded app config
+ * @returns {{ provider: string, model: string }}
+ */
+function _resolveStackProviderModel({ reqProvider, reqModel, repoSettings, config } = {}) {
+  const cfg = config || {};
+  const provider = reqProvider || process.env.PAIR_REVIEW_PROVIDER || repoSettings?.default_provider || cfg.default_provider || cfg.provider || 'claude';
+  const model = reqModel || process.env.PAIR_REVIEW_MODEL || repoSettings?.default_model || cfg.default_model || cfg.model || 'opus';
+  return { provider, model };
+}
+
 /**
  * Run setup + analysis for a single PR in the stack.
  * Called in parallel for all PRs.
@@ -437,8 +471,9 @@ async function analyzeStackPR(deps, db, config, {
       providerOverridesMap: councilProviderOverridesMap
     });
   } else {
-    let selectedProvider = reqProvider || repoSettings?.default_provider || config.default_provider || config.provider || 'claude';
-    let selectedModel = reqModel || repoSettings?.default_model || config.default_model || config.model || 'opus';
+    const { provider: selectedProvider, model: selectedModel } = _resolveStackProviderModel({
+      reqProvider, reqModel, repoSettings, config
+    });
 
     // Resolve load_skills across all config tiers
     const providerLoadSkills = config.providers?.[selectedProvider]?.load_skills;
@@ -959,3 +994,4 @@ module.exports.activeStackAnalyses = activeStackAnalyses;
 module.exports.executeStackAnalysis = executeStackAnalysis;
 module.exports.waitForAnalysisCompletion = waitForAnalysisCompletion;
 module.exports.estimateCouncilTimeout = estimateCouncilTimeout;
+module.exports._resolveStackProviderModel = _resolveStackProviderModel;

package/src/server.js

@@ -1,8 +1,8 @@
 // Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
 const express = require('express');
 const path = require('path');
-const { loadConfig, getGitHubToken, resolveDbName, warnIfDevModeWithoutDbName } = require('./config');
-const { initializeDatabase, getDatabaseStatus, queryOne, run } = require('./database');
+const { loadConfig, getGitHubToken, resolveDbName, warnIfDevModeWithoutDbName, getRepoConfig, resolveBindingRepositoryFromPR, isExclusiveAltHost } = require('./config');
+const { initializeDatabase, getDatabaseStatus, queryOne, run, PRMetadataRepository } = require('./database');
 const { normalizeRepository } = require('./utils/paths');
 const { applyConfigOverrides, checkAllProviders } = require('./ai');
 const { checkAllChatProviders } = require('./chat/chat-providers');
@@ -27,6 +27,69 @@ function applyEnvOverrides(config) {
   return config;
 }
 
+/**
+ * Apply an explicit `?host` correction from the /pr fast path.
+ *
+ * Dashboard clicks and pasted URLs can carry `?host` to say which system a PR
+ * lives on. When the PR already has metadata + a worktree, the route serves
+ * pr.html directly (no setup), so this is the only place that consumes the
+ * hint on the fast path. It is a LABEL correction only — the no-collision
+ * assumption means a same-numbered PR is the same logical PR, so no re-fetch.
+ *
+ * Sentinel mapping mirrors setup.html: `'github'` → null (github.com), any
+ * other non-empty string → an alt `api_host` URL, absent/empty → no-op. The
+ * target is validated against config so a stale link can't stamp a host the
+ * repo isn't configured for (which `resolveHostBinding` would later reject);
+ * on any mismatch we warn and ignore rather than break the page load.
+ *
+ * @param {Object} db - Database handle
+ * @param {Object} config - Loaded config
+ * @param {string} owner - URL owner segment
+ * @param {string} repo - URL repo segment
+ * @param {string} repository - Normalized `owner/repo` used as the pr_metadata key
+ * @param {number} prNumber - PR number
+ * @param {*} rawHost - `req.query.host` (already URL-decoded by Express)
+ * @returns {Promise<void>}
+ */
+async function applyHostQueryCorrection(db, config, owner, repo, repository, prNumber, rawHost) {
+  if (rawHost === undefined || rawHost === null || rawHost === '') return;
+  if (typeof rawHost !== 'string') return;
+
+  const targetHost = rawHost === 'github' ? null : rawHost;
+
+  // Resolve the repo's config entry (handles monorepo-style keys matched via
+  // url_pattern) to learn its configured api_host.
+  const bindingRepo = resolveBindingRepositoryFromPR(owner, repo, config);
+  const repoConfig = getRepoConfig(config, bindingRepo);
+  const configuredApiHost = (repoConfig && typeof repoConfig.api_host === 'string' && repoConfig.api_host)
+    ? repoConfig.api_host
+    : null;
+
+  if (targetHost !== null) {
+    // A string host must match this repo's configured api_host exactly.
+    if (targetHost !== configuredApiHost) {
+      logger.warn(`Ignoring ?host correction for ${repository} #${prNumber}: "${targetHost}" does not match configured api_host (${configuredApiHost || 'none'})`);
+      return;
+    }
+  } else if (isExclusiveAltHost(repoConfig)) {
+    // The github sentinel is meaningless for an exclusive alt-host repo (it has
+    // no github.com presence); stamping null would break binding resolution.
+    logger.warn(`Ignoring ?host=github correction for ${repository} #${prNumber}: repo is an exclusive alt-host repo with no github.com presence`);
+    return;
+  }
+
+  const prMetadataRepo = new PRMetadataRepository(db);
+  const stored = await prMetadataRepo.getPRHost(repository, prNumber);
+  // Fast path only runs when a row exists, so `stored` is null or a string.
+  // Skip the write when it already matches (avoids a needless updated_at bump).
+  if (stored === targetHost) return;
+
+  const changed = await prMetadataRepo.updatePRHost(repository, prNumber, targetHost);
+  if (changed) {
+    logger.info(`Corrected stored host for ${repository} #${prNumber} to ${targetHost === null ? 'github.com' : targetHost} via ?host`);
+  }
+}
+
 /**
  * Request logging middleware (disabled for cleaner output)
  */
@@ -276,6 +339,14 @@ async function startServer(sharedDb = null, sharedPoolLifecycle = null) {
           if (worktree) {
             // Update last_accessed_at so the recent reviews list reflects actual access
             run(db, 'UPDATE pr_metadata SET last_accessed_at = ? WHERE id = ?', [new Date().toISOString(), existing.id]).catch(err => logger.warn(`Failed to update last_accessed_at: ${err.message}`));
+            // Persist an explicit ?host correction BEFORE serving so pr.html's
+            // first data fetch resolves the binding against the corrected host.
+            // Never let a bad hint break the page — the helper swallows and warns.
+            try {
+              await applyHostQueryCorrection(db, config, owner, repo, repository, prNumber, req.query.host);
+            } catch (err) {
+              logger.warn(`Failed to apply ?host correction for ${repository} #${prNumber}: ${err.message}`);
+            }
             res.sendFile(path.join(__dirname, '..', 'public', 'pr.html'));
           } else {
             logger.info(`PR metadata exists but no worktree for ${repository} #${prNumber}, serving setup page`);
@@ -521,4 +592,4 @@ if (require.main === module) {
   startServer();
 }
 
-module.exports = { startServer, applyEnvOverrides };
+module.exports = { startServer, applyEnvOverrides, applyHostQueryCorrection };

package/src/setup/local-setup.js

@@ -1,10 +1,10 @@
 // Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
-const { findGitRoot, getHeadSha, getCurrentBranch, getRepositoryName, generateScopedDiff, generateLocalReviewId, computeScopedDigest, findMainGitRoot } = require('../local-review');
+const { findGitRoot, getHeadSha, getCurrentBranch, getRepositoryName, generateScopedDiff, generateLocalReviewId, computeScopedDigest, findMainGitRoot, resolveScopeAndBase, persistScopeSelection } = require('../local-review');
 const { ReviewRepository, RepoSettingsRepository } = require('../database');
 const { localReviewDiffs } = require('../routes/shared');
 const { fireHooks, hasHooks } = require('../hooks/hook-runner');
 const { buildReviewStartedPayload, buildReviewLoadedPayload, getCachedUser } = require('../hooks/payloads');
-const { STOPS, DEFAULT_SCOPE, reviewScope } = require('../local-scope');
+const { STOPS } = require('../local-scope');
 const logger = require('../utils/logger');
 const { LOCAL_REVIEW_PATH_URL_ERROR, rejectUrlLikeLocalReviewPath } = require('../utils/local-path-input');
 const path = require('path');
@@ -21,9 +21,12 @@ const fs = require('fs').promises;
  * @param {string} options.targetPath - Path to review (file or directory)
  * @param {Function} [options.onProgress] - Progress callback ({ step, status, message })
  * @param {Object} [options.config] - App config (for hooks)
+ * @param {Object} [options.flags] - Scope override { scope?, base? } forwarded from
+ *   a delegated `--scope`/`--base` launch. The route MUST have validated these
+ *   first. Absent flags leave scope resolution at persisted/default (unchanged).
  * @returns {Promise<Object>} Review session info
  */
-async function setupLocalReview({ db, targetPath, onProgress, config }) {
+async function setupLocalReview({ db, targetPath, onProgress, config, flags = {} }) {
   const progress = typeof onProgress === 'function'
     ? onProgress
     : () => {};
@@ -104,10 +107,14 @@ async function setupLocalReview({ db, targetPath, onProgress, config }) {
   }
 
   // ── Step: diff ──────────────────────────────────────────────────────
-  let diff, stats, digest;
+  // Resolve scope + base via the shared helper so a delegated --scope/--base
+  // launch is honored identically to the cold-start CLI path. With no override
+  // (flags absent) this yields the persisted/default scope — unchanged behavior.
+  let diff, stats, digest, scopeStart, scopeEnd, baseBranch, scopeOverridden;
   try {
-    const { start: scopeStart, end: scopeEnd } = existingReview ? reviewScope(existingReview) : DEFAULT_SCOPE;
-    const baseBranch = existingReview?.local_base_branch || null;
+    ({ scopeStart, scopeEnd, baseBranch, scopeOverridden } = await resolveScopeAndBase({
+      existingReview, flags, repoPath, branch, repository, config
+    }));
 
     progress({ step: 'diff', status: 'running', message: 'Generating diff for local changes...' });
 
@@ -146,6 +153,15 @@ async function setupLocalReview({ db, targetPath, onProgress, config }) {
       });
     }
 
+    // Persist an explicitly-overridden scope (and its resolved base) so the web
+    // UI opens this delegated session at the requested scope — only after the
+    // diff above succeeded. No-op when no override was supplied.
+    if (scopeOverridden) {
+      await persistScopeSelection({
+        reviewRepo: storeRepo, sessionId, existingReview, scopeStart, scopeEnd, baseBranch, branch, repoPath
+      });
+    }
+
     localReviewDiffs.set(sessionId, { diff, stats, digest });
 
     progress({ step: 'store', status: 'completed', message: `Review session ${sessionId} stored` });
@@ -159,7 +175,7 @@ async function setupLocalReview({ db, targetPath, onProgress, config }) {
   if (config && hasHooks(hookEvent, config)) {
     getCachedUser(config).then(user => {
       const builder = existingReview ? buildReviewLoadedPayload : buildReviewStartedPayload;
-      const { start: scopeStart, end: scopeEnd } = existingReview ? reviewScope(existingReview) : DEFAULT_SCOPE;
+      // Reflect the resolved (possibly overridden) scope, not just the persisted one.
       const si = STOPS.indexOf(scopeStart);
       const ei = STOPS.indexOf(scopeEnd);
       const scope = STOPS.slice(si, ei + 1);