@in-the-loop-labs/pair-review 3.8.0 → 3.9.0

package/src/mcp-stdio.js

@@ -15,12 +15,47 @@ const logger = require('./utils/logger');
 /**
  * Redirect all console output and logger writes to stderr.
  * Must be called before any other module logs to stdout.
+ *
+ * Also sets `PAIR_REVIEW_QUIET_STDOUT=1` so that code which writes directly to
+ * `process.stdout` (bypassing console/logger) can detect that stdout is reserved
+ * and route its output to stderr instead. The only such path today is the child
+ * stdout of a configured checkout script (`executeCheckoutScript`,
+ * src/git/worktree.js). In both modes that call this function — MCP stdio (stdout
+ * is JSON-RPC) and headless `--json` (stdout is the JSON document) — keeping that
+ * child output off stdout is the correct, desired behavior.
+ *
+ * @param {Object} [opts]
+ * @param {boolean} [opts.quiet=false] - When true (headless `--json` without
+ *   `--debug`), *drop* progress narration entirely rather than relocating it to
+ *   stderr. A coding agent's shell tool captures stderr into its context window,
+ *   so relocated narration still costs tokens; quiet mode no-ops the ungated
+ *   `console.log/info` narration and puts the logger into quiet mode
+ *   (suppressing info/success/log/section). `console.warn`, `console.error`,
+ *   `logger.warn`, and `logger.error` still emit to stderr — quiet drops only
+ *   progress narration and never swallows warnings/errors.
  */
-function redirectConsoleToStderr() {
-  console.log = console.error;
-  console.info = console.error;
-  console.warn = console.error;
-  logger.setOutputStream(process.stderr);
+function redirectConsoleToStderr({ quiet = false } = {}) {
+  if (quiet) {
+    // Drop ungated narration; keep console.error real (→ stderr).
+    const noop = () => {};
+    console.log = noop;
+    console.info = noop;
+    // console.warn carries genuine diagnostics agents need (e.g. the
+    // --council/--model advisory, worktree-migration warnings) — route it to
+    // stderr rather than swallowing it. Quiet drops progress narration only.
+    console.warn = console.error;
+    // logger.warn writes to _stdout — point it at stderr so a warning during a
+    // run never corrupts the JSON document on real stdout.
+    logger.setOutputStream(process.stderr);
+    logger.setQuietEnabled(true);
+  } else {
+    console.log = console.error;
+    console.info = console.error;
+    console.warn = console.error;
+    logger.setOutputStream(process.stderr);
+  }
+  // Process-level signal for raw process.stdout.write paths (see JSDoc above).
+  process.env.PAIR_REVIEW_QUIET_STDOUT = '1';
 }
 
 /**

package/src/review-config.js

@@ -0,0 +1,164 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+/**
+ * Repo-default review-configuration resolver.
+ *
+ * A single helper that decides whether a review run should use a council or a
+ * single provider/model, honoring (in order of precedence): explicit CLI/request
+ * picks, the repo's saved defaults (`repo_settings.default_council_id` /
+ * `default_provider` / `default_model`), and finally the global config defaults.
+ *
+ * Both the headless CLI path and the interactive web analyze routes use this so
+ * that a repo's `default_council_id` — previously stored but never consulted —
+ * is honored consistently everywhere.
+ *
+ * The council-selection object returned here is intentionally drop-in compatible
+ * with what `runHeadlessCouncilAnalysis` (src/councils/headless-council.js) and
+ * the existing `performHeadlessReview` council path (src/main.js) consume:
+ *   `{ council, configType, councilConfig }`.
+ * The derivation of `configType`/`councilConfig` mirrors that code exactly
+ * (`council.type || 'advanced'` + `normalizeCouncilConfig`).
+ */
+
+const { RepoSettingsRepository, CouncilRepository } = require('./database');
+const { resolveCouncilHandle } = require('./councils/resolve-council');
+const { normalizeCouncilConfig, validateCouncilConfig } = require('./routes/councils');
+const logger = require('./utils/logger');
+
+/**
+ * Derive the `{ council, configType, councilConfig }` selection object from a
+ * resolved council row, applying the same normalization + validation as the
+ * existing headless council path (`performHeadlessReview`, src/main.js).
+ *
+ * @param {Object} council - Full council row (parsed config), as returned by
+ *   `resolveCouncilHandle` or `CouncilRepository.getById`.
+ * @returns {{ council: Object, configType: string, councilConfig: Object }}
+ * @throws {Error} If the council's config is invalid for its type.
+ * @private
+ */
+function _buildCouncilSelection(council) {
+  const configType = council.type || 'advanced';
+  const councilConfig = normalizeCouncilConfig(council.config, configType);
+  // validateCouncilConfig returns an error string, or null when valid.
+  const validationError = validateCouncilConfig(councilConfig, configType);
+  if (validationError) {
+    throw new Error(`Invalid council "${council.name}": ${validationError}`);
+  }
+  return { council, configType, councilConfig };
+}
+
+/**
+ * Resolve the single-provider/model pair from the per-field precedence ladders.
+ *
+ * Mirrors the canonical (pre-refactor) headless derivation in
+ * `performHeadlessReview` and the MCP ladder (`src/routes/mcp.js`), which both
+ * let a deliberate per-invocation environment override win over a sticky,
+ * persisted repo default:
+ *   provider: explicit › PAIR_REVIEW_PROVIDER › repo default › config.default_provider › config.provider › 'claude'
+ *   model:    explicit › PAIR_REVIEW_MODEL › repo default › config.default_model › config.model › 'opus'
+ *
+ * The environment variables sit ABOVE the repo defaults on purpose: `--ai-draft`
+ * / `--ai-review` (which route through this resolver via `performHeadlessReview`)
+ * historically resolved env-first, and CI/agent callers set `PAIR_REVIEW_MODEL` /
+ * `PAIR_REVIEW_PROVIDER` as one-shot overrides that should beat a repo's saved
+ * `default_model` / `default_provider`. (The interactive web "Analyze" route keeps
+ * its own repo-before-env single ladder in `src/routes/{pr,local}.js`; this
+ * resolver is consulted there only to detect council mode, not to pick the model.)
+ *
+ * Each field falls through independently, so supplying only `explicit.model`
+ * still resolves the provider from env/repo/config defaults (and vice versa).
+ *
+ * @param {Object} explicit - { provider, model } (either may be undefined)
+ * @param {Object|null} repoSettings - Row from RepoSettingsRepository.getRepoSettings
+ * @param {Object} config - Global config object
+ * @returns {{ type: 'single', provider: string, model: string }}
+ * @private
+ */
+function _buildSingleSelection(explicit, repoSettings, config) {
+  const cfg = config || {};
+  const provider = explicit.provider
+    || process.env.PAIR_REVIEW_PROVIDER
+    || repoSettings?.default_provider
+    || cfg.default_provider
+    || cfg.provider
+    || 'claude';
+  const model = explicit.model
+    || process.env.PAIR_REVIEW_MODEL
+    || repoSettings?.default_model
+    || cfg.default_model
+    || cfg.model
+    || 'opus';
+  return { type: 'single', provider, model };
+}
+
+/**
+ * Resolve the review configuration (council vs single provider/model) for a run.
+ *
+ * Precedence (highest first):
+ *   1. `explicit.council` — a `--council` handle (id / id-prefix / name). Resolved
+ *      via `resolveCouncilHandle`. A bad handle throws (fail-fast for CLI/UI).
+ *   2. `explicit.provider` / `explicit.model` — an explicit single-model pick
+ *      (e.g. `--model`). Returns a single selection; any missing field falls
+ *      through to env/repo/config defaults.
+ *   3. `repo_settings.default_council_id` — looked up directly by id via
+ *      `CouncilRepository.getById` (we already hold the UUID, so no handle
+ *      matching is needed). If the id points to a council that no longer exists,
+ *      a warning is logged and resolution falls through to the single default.
+ *   4. `PAIR_REVIEW_PROVIDER` / `PAIR_REVIEW_MODEL` — one-shot env overrides
+ *      (deliberately above repo defaults — see `_buildSingleSelection`).
+ *   5. `repo_settings.default_provider` / `default_model` — single selection.
+ *   6. Global `config` defaults — single selection (final hardcoded fallbacks
+ *      'claude' / 'opus').
+ *
+ * @param {Object} db - Database instance.
+ * @param {string} repository - Repository in `owner/repo` form (may be null/undefined
+ *   for repos with no saved settings; treated as "no repo defaults").
+ * @param {Object} [explicit] - Explicit picks: `{ council, provider, model }`.
+ *   `council` is a CLI handle string (id-prefix/name) or a pre-resolved id.
+ *   Any field may be undefined.
+ * @param {Object} [config] - Global config object (default provider/model, etc.).
+ * @returns {Promise<{ type: 'council', council: Object, configType: string, councilConfig: Object }
+ *   | { type: 'single', provider: string, model: string }>}
+ * @throws {Error} If `explicit.council` cannot be resolved or its config is invalid.
+ */
+async function resolveReviewConfig(db, repository, explicit = {}, config = {}) {
+  const { council: explicitCouncil, provider: explicitProvider, model: explicitModel } = explicit || {};
+
+  // 1. Explicit --council handle wins over everything.
+  if (explicitCouncil) {
+    const council = await resolveCouncilHandle(db, explicitCouncil);
+    return { type: 'council', ..._buildCouncilSelection(council) };
+  }
+
+  // 2. Explicit single-model pick (--provider / --model). Returns single; any
+  //    missing field still resolves from repo/config defaults via the ladder.
+  if (explicitProvider || explicitModel) {
+    const repoSettings = repository
+      ? await new RepoSettingsRepository(db).getRepoSettings(repository)
+      : null;
+    return _buildSingleSelection({ provider: explicitProvider, model: explicitModel }, repoSettings, config);
+  }
+
+  // No explicit pick — consult the repo's saved defaults.
+  const repoSettings = repository
+    ? await new RepoSettingsRepository(db).getRepoSettings(repository)
+    : null;
+
+  // 3. Repo default council (resolve directly by id — we already hold the UUID).
+  if (repoSettings?.default_council_id) {
+    const council = await new CouncilRepository(db).getById(repoSettings.default_council_id);
+    if (council) {
+      return { type: 'council', ..._buildCouncilSelection(council) };
+    }
+    // The configured default council no longer exists. Don't fail the run —
+    // fall through to the single-provider default so analysis still proceeds.
+    logger.warn(
+      `Repo default council "${repoSettings.default_council_id}" for ${repository} ` +
+      `was not found; falling back to default provider/model.`
+    );
+  }
+
+  // 4 & 5. Single selection from repo defaults, then global config, then hardcoded.
+  return _buildSingleSelection({}, repoSettings, config);
+}
+
+module.exports = { resolveReviewConfig };

package/src/routes/bulk-analysis-configs.js

@@ -13,6 +13,7 @@ const express = require('express');
 const logger = require('../utils/logger');
 const { VALID_TIERS } = require('../ai/prompts/config');
 const { getAllProvidersInfo } = require('../ai');
+const { modelMatches } = require('../ai/provider');
 const { normalizeCouncilConfig, validateCouncilConfig } = require('./councils');
 
 const router = express.Router();
@@ -150,9 +151,16 @@ function sanitizeSingleConfig(config) {
   // provider (a mismatched pair that slipped past the client resolver), fall back
   // to the provider's own default rather than forwarding an invalid pair. Unknown
   // providers (custom/unavailable, not in the registry) pass through unchanged.
+  // A model "belongs" to the provider if config.model matches a model id OR one of
+  // its aliases (e.g. 'opus' is an alias of the canonical 'opus-4.8-xhigh'). Matching
+  // id-only would wrongly treat a valid alias as a mismatched pair and silently coerce
+  // it to the provider default.
   let normalizedModel = config.model;
   const providerInfo = getAllProvidersInfo().find(p => p.id === config.provider);
-  if (providerInfo && !providerInfo.models.some(m => m.id === config.model)) {
+  const modelBelongsToProvider = providerInfo && providerInfo.models.some(
+    m => modelMatches(m, config.model)
+  );
+  if (providerInfo && !modelBelongsToProvider) {
     normalizedModel = providerInfo.defaultModel || config.model;
   }
 
@@ -239,24 +247,45 @@ function sanitizeAnalysisConfig(config) {
   return sanitizeSingleConfig(config);
 }
 
-router.post('/api/bulk-analysis-configs', (req, res) => {
-  try {
-    const result = sanitizeAnalysisConfig(req.body?.analysisConfig);
-    if (result.error) {
-      return res.status(400).json({ error: result.error });
-    }
+/**
+ * Validate + store an analysis config, returning its short id. Single source of
+ * truth for the in-memory store, shared by the HTTP POST handler (index-page bulk
+ * launcher) and the CLI interactive `--instructions` flow, which stashes the
+ * resolved config so the browser-side auto-analyze can pick it up via the
+ * `analysisConfigId` URL param (same in-process Map the GET handler reads).
+ *
+ * @param {Object} analysisConfig - Raw analysis config (single or council shape)
+ * @returns {{ id: string, expiresInMs: number }}
+ * @throws {Error} with `.statusCode = 400` when the config fails validation
+ */
+function createBulkAnalysisConfig(analysisConfig) {
+  const result = sanitizeAnalysisConfig(analysisConfig);
+  if (result.error) {
+    const err = new Error(result.error);
+    err.statusCode = 400;
+    throw err;
+  }
 
-    pruneExpired();
+  pruneExpired();
+
+  const id = crypto.randomUUID();
+  configs.set(id, {
+    analysisConfig: result.config,
+    expiresAt: Date.now() + CONFIG_TTL_MS
+  });
+  enforceMaxConfigs();
 
-    const id = crypto.randomUUID();
-    configs.set(id, {
-      analysisConfig: result.config,
-      expiresAt: Date.now() + CONFIG_TTL_MS
-    });
-    enforceMaxConfigs();
+  return { id, expiresInMs: CONFIG_TTL_MS };
+}
 
-    res.json({ success: true, id, expiresInMs: CONFIG_TTL_MS });
+router.post('/api/bulk-analysis-configs', (req, res) => {
+  try {
+    const { id, expiresInMs } = createBulkAnalysisConfig(req.body?.analysisConfig);
+    res.json({ success: true, id, expiresInMs });
   } catch (error) {
+    if (error.statusCode === 400) {
+      return res.status(400).json({ error: error.message });
+    }
     logger.error('Failed to store bulk analysis config:', error);
     res.status(500).json({ error: 'Failed to store bulk analysis config' });
   }
@@ -287,6 +316,7 @@ function _getBulkAnalysisConfig(id) {
 }
 
 module.exports = router;
+module.exports.createBulkAnalysisConfig = createBulkAnalysisConfig;
 module.exports._resetBulkAnalysisConfigs = _resetBulkAnalysisConfigs;
 module.exports._getBulkAnalysisConfig = _getBulkAnalysisConfig;
 module.exports._pruneExpired = pruneExpired;

package/src/routes/config.js

@@ -17,7 +17,8 @@ const {
   getCachedAvailability,
   getAllCachedAvailability,
   checkAllProviders,
-  isCheckInProgress
+  isCheckInProgress,
+  modelMatches
 } = require('../ai');
 const { normalizeRepository } = require('../utils/paths');
 const {
@@ -113,9 +114,13 @@ function resolveDefaultProviderModel(config) {
   // provider-only override like `default_provider: 'gemini'` would otherwise inherit
   // a foreign Anthropic model and return a mismatched pair. When the model does not
   // belong to the provider, derive a coherent default from the provider itself.
-  const modelBelongs = explicitModel && providerInfo?.models?.some(m => m.id === explicitModel);
-  if (modelBelongs) {
-    return { provider, model: explicitModel };
+  // Match by canonical id OR alias so a config naming an alias (e.g. 'opus') is
+  // recognized — but return the canonical id, because the frontend matches model
+  // cards by canonical id only; returning the raw alias would fail to match and
+  // silently fall back to the provider default.
+  const matchedModel = explicitModel && providerInfo?.models?.find(m => modelMatches(m, explicitModel));
+  if (matchedModel) {
+    return { provider, model: matchedModel.id };
   }
   return { provider, model: providerInfo?.defaultModel || getDefaultModel(config) };
 }

package/src/routes/executable-analysis.js

@@ -96,9 +96,15 @@ async function generateDiffForExecutable(cwd, context, diffArgs, outputPath) {
  * (branch, staged, unstaged, untracked) that were included in the diff.
  * @param {string} cwd - Working directory
  * @param {Object} context - Executable context with baseSha/headSha or scope fields
+ * @param {Object} [options]
+ * @param {boolean} [options.throwOnError=false] - When true, a git failure rethrows
+ *   instead of being logged-and-swallowed to `[]`. Callers that have already
+ *   established the scope is non-empty (e.g. headless local, which checks the
+ *   session diff first) use this so an operational git error becomes a non-zero
+ *   exit rather than masquerading as an empty changed-file set / "no changes".
  * @returns {Promise<string[]>} Changed file paths
  */
-async function getChangedFiles(cwd, context) {
+async function getChangedFiles(cwd, context, { throwOnError = false } = {}) {
   try {
     if (context.baseSha && context.headSha) {
       const { stdout } = await execPromise(
@@ -154,6 +160,9 @@ async function getChangedFiles(cwd, context) {
       .filter(f => f.length > 0);
     return [...new Set(all)];
   } catch (error) {
+    if (throwOnError) {
+      throw new Error(`Failed to enumerate changed files in ${cwd}: ${error.message}`);
+    }
     logger.warn(`Could not get changed files list: ${error.message}`);
     return [];
   }

package/src/routes/local.js

@@ -32,6 +32,7 @@ const { STOPS, isValidScope, normalizeScope, reviewScope, includesBranch, DEFAUL
 const { getGeneratedFilePatterns } = require('../git/gitattributes');
 const { getShaAbbrevLength } = require('../git/sha-abbrev');
 const { validateCouncilConfig, normalizeCouncilConfig } = require('./councils');
+const { resolveReviewConfig } = require('../review-config');
 const { TIERS, TIER_ALIASES, VALID_TIERS, resolveTier } = require('../ai/prompts/config');
 const { getProviderClass, createProvider } = require('../ai/provider');
 const { getDefaultBranch, tryGraphiteState } = require('../git/base-branch');
@@ -1219,6 +1220,137 @@ async function handleExecutableAnalysis(req, res, {
   });
 }
 
+/**
+ * Launch a local-mode council analysis.
+ *
+ * Shared by the explicit council endpoint (`POST .../analyses/council`) and the
+ * plain-analyze default path (`POST .../analyses`) when a repo's
+ * `default_council_id` resolves to a council and the request made no explicit
+ * single-model pick. Both entry points build the same modeContext and call
+ * `analysesRouter.launchCouncilAnalysis`, so council dispatch is not duplicated.
+ *
+ * The caller is responsible for resolving + validating `councilConfig`/`configType`
+ * and for the empty-scope guard (`rejectIfEmptyScope`) before invoking this.
+ *
+ * @returns {{ analysisId: string, runId: string }}
+ */
+async function launchLocalCouncilAnalysis(req, {
+  reviewId, review, localPath, councilConfig, councilId, configType,
+  requestInstructions, excludePrevious
+}) {
+  const db = req.app.get('db');
+
+  const { start: councilScopeStart, end: councilScopeEnd } = reviewScope(review);
+  const councilHasBranch = includesBranch(councilScopeStart);
+
+  // Compute merge-base when branch is in scope
+  let analysisBaseSha = review.local_head_sha;
+  if (councilHasBranch && review.local_base_branch) {
+    try {
+      analysisBaseSha = await findMergeBase(localPath, review.local_base_branch);
+    } catch {
+      // Fall back to HEAD
+    }
+  }
+
+  const prMetadata = {
+    reviewType: 'local',
+    repository: review.repository,
+    title: null,
+    description: null,
+    base_sha: analysisBaseSha,
+    head_sha: review.local_head_sha,
+    base_branch: review.local_base_branch || null,
+    head_branch: review.local_head_branch || null,
+    scopeStart: councilScopeStart,
+    scopeEnd: councilScopeEnd,
+  };
+
+  // Use the scope-aware helper so the file list matches the generated diff
+  // (covers branch, staged, unstaged, and untracked stops as appropriate).
+  const changedFiles = await getChangedFiles(localPath, {
+    scopeStart: councilScopeStart,
+    scopeEnd: councilScopeEnd,
+    baseBranch: review.local_base_branch || null,
+  });
+
+  // Generate and cache diff. Hoist the result out of the try so we can also
+  // persist it to `local_diffs` below (after reviewRepo is constructed) — the
+  // council path previously cached the diff in-memory only, which left the
+  // manual tour/summary buttons reporting a false "no-diff" after a restart.
+  let councilDiff = null;
+  let councilStats = null;
+  let councilDigest = null;
+  try {
+    const diffResult = await generateScopedDiff(localPath, councilScopeStart, councilScopeEnd, review.local_base_branch);
+    councilDigest = await computeScopedDigest(localPath, councilScopeStart, councilScopeEnd);
+    councilDiff = diffResult.diff;
+    councilStats = diffResult.stats;
+    setLocalReviewDiff(reviewId, { diff: councilDiff, stats: councilStats, digest: councilDigest });
+  } catch (diffError) {
+    logger.warn(`Could not generate diff for local council review ${reviewId}: ${diffError.message}`);
+  }
+
+  // Resolve instructions
+  const repoSettingsRepo = new RepoSettingsRepository(db);
+  const reviewRepo = new ReviewRepository(db);
+
+  // Durably persist the diff so it survives a restart and the manual
+  // tour/summary buttons can find it (parity with the analysis-push path).
+  if (councilDiff) {
+    try {
+      await reviewRepo.saveLocalDiff(reviewId, { diff: councilDiff, stats: councilStats, digest: councilDigest });
+    } catch (saveError) {
+      logger.warn(`Could not persist diff for local council review ${reviewId}: ${saveError.message}`);
+    }
+  }
+  const repoSettings = await repoSettingsRepo.getRepoSettings(review.repository);
+  const repoInstructions = repoSettings?.default_instructions || null;
+
+  if (requestInstructions) {
+    await reviewRepo.updateReview(reviewId, {
+      customInstructions: requestInstructions
+    });
+  }
+
+  // Import launchCouncilAnalysis from analyses.js
+  const analysesRouter = require('./analyses');
+  const localCouncilConfig = req.app.get('config') || {};
+
+  const { providerOverrides: councilProviderOverrides, providerOverridesMap: councilProviderOverridesMap } =
+    buildCouncilProviderOverrides(localCouncilConfig, review.repository, repoSettings);
+
+  // Local mode has no associated GitHub PR, so we do not pass a githubClient.
+  // The analyzer drops the GitHub dedup section when no client is supplied.
+  return analysesRouter.launchCouncilAnalysis(
+    db,
+    {
+      reviewId,
+      worktreePath: localPath,
+      prMetadata,
+      changedFiles,
+      repository: review.repository,
+      headSha: review.local_head_sha,
+      logLabel: `local review #${reviewId}`,
+      initialStatusExtra: { reviewId, reviewType: 'local' },
+      config: localCouncilConfig,
+      excludePrevious,
+      serverPort: req.socket.localPort,
+      providerOverrides: councilProviderOverrides,
+      providerOverridesMap: councilProviderOverridesMap,
+      hookContext: {
+        mode: 'local',
+        localContext: { path: localPath, branch: review.local_head_branch, headSha: review.local_head_sha },
+      },
+      runUpdateExtra: { filesAnalyzed: changedFiles ? changedFiles.length : 0 }
+    },
+    councilConfig,
+    councilId,
+    { globalInstructions: localCouncilConfig.globalInstructions || null, repoInstructions, requestInstructions },
+    configType
+  );
+}
+
 /**
  * Start Level 1 AI analysis for local review
  */
@@ -1273,6 +1405,40 @@ router.post('/api/local/:reviewId/analyses', async (req, res) => {
 
     const appConfig = req.app.get('config') || {};
 
+    // Repo default-council parity: when the request makes NO explicit single-model
+    // pick (no provider/model in the body), honor the repo's saved
+    // default_council_id by dispatching to the same council path the explicit
+    // council endpoint uses. An explicit provider/model in the request always
+    // wins and falls through to the single-provider path unchanged below.
+    // For repos with no default_council_id the resolver returns type:'single' and
+    // we fall through, so single-provider behavior is byte-identical to before.
+    if (!requestProvider && !requestModel) {
+      const reviewConfig = await resolveReviewConfig(
+        db,
+        repository,
+        { provider: requestProvider, model: requestModel },
+        appConfig
+      );
+      if (reviewConfig.type === 'council') {
+        logger.log('API', `Honoring repo default council for ${repository}: ${reviewConfig.council.name}`, 'cyan');
+        const { analysisId: councilAnalysisId, runId: councilRunId } = await launchLocalCouncilAnalysis(req, {
+          reviewId, review, localPath,
+          councilConfig: reviewConfig.councilConfig,
+          councilId: reviewConfig.council.id,
+          configType: reviewConfig.configType,
+          requestInstructions,
+          excludePrevious
+        });
+        return res.json({
+          analysisId: councilAnalysisId,
+          runId: councilRunId,
+          status: 'started',
+          message: 'Council analysis started in background',
+          isCouncil: true
+        });
+      }
+    }
+
     // Determine provider: request body > repo settings > config > default ('claude')
     let selectedProvider;
     if (requestProvider) {
@@ -2238,117 +2404,12 @@ router.post('/api/local/:reviewId/analyses/council', async (req, res) => {
     // Guard: reject if scope resolves to zero changed files
     if (await rejectIfEmptyScope(res, review, localPath)) return;
 
-    const { start: councilScopeStart, end: councilScopeEnd } = reviewScope(review);
-    const councilHasBranch = includesBranch(councilScopeStart);
-
-    // Compute merge-base when branch is in scope
-    let analysisBaseSha = review.local_head_sha;
-    if (councilHasBranch && review.local_base_branch) {
-      try {
-        analysisBaseSha = await findMergeBase(localPath, review.local_base_branch);
-      } catch {
-        // Fall back to HEAD
-      }
-    }
-
-    const prMetadata = {
-      reviewType: 'local',
-      repository: review.repository,
-      title: null,
-      description: null,
-      base_sha: analysisBaseSha,
-      head_sha: review.local_head_sha,
-      base_branch: review.local_base_branch || null,
-      head_branch: review.local_head_branch || null,
-      scopeStart: councilScopeStart,
-      scopeEnd: councilScopeEnd,
-    };
-
-    // Use the scope-aware helper so the file list matches the generated diff
-    // (covers branch, staged, unstaged, and untracked stops as appropriate).
-    const changedFiles = await getChangedFiles(localPath, {
-      scopeStart: councilScopeStart,
-      scopeEnd: councilScopeEnd,
-      baseBranch: review.local_base_branch || null,
+    const { analysisId, runId } = await launchLocalCouncilAnalysis(req, {
+      reviewId, review, localPath, councilConfig, councilId, configType,
+      requestInstructions: rawInstructions?.trim() || null,
+      excludePrevious
     });
 
-    // Generate and cache diff. Hoist the result out of the try so we can also
-    // persist it to `local_diffs` below (after reviewRepo is constructed) — the
-    // council path previously cached the diff in-memory only, which left the
-    // manual tour/summary buttons reporting a false "no-diff" after a restart.
-    let councilDiff = null;
-    let councilStats = null;
-    let councilDigest = null;
-    try {
-      const diffResult = await generateScopedDiff(localPath, councilScopeStart, councilScopeEnd, review.local_base_branch);
-      councilDigest = await computeScopedDigest(localPath, councilScopeStart, councilScopeEnd);
-      councilDiff = diffResult.diff;
-      councilStats = diffResult.stats;
-      setLocalReviewDiff(reviewId, { diff: councilDiff, stats: councilStats, digest: councilDigest });
-    } catch (diffError) {
-      logger.warn(`Could not generate diff for local council review ${reviewId}: ${diffError.message}`);
-    }
-
-    // Resolve instructions
-    const repoSettingsRepo = new RepoSettingsRepository(db);
-    const reviewRepo = new ReviewRepository(db);
-
-    // Durably persist the diff so it survives a restart and the manual
-    // tour/summary buttons can find it (parity with the analysis-push path).
-    if (councilDiff) {
-      try {
-        await reviewRepo.saveLocalDiff(reviewId, { diff: councilDiff, stats: councilStats, digest: councilDigest });
-      } catch (saveError) {
-        logger.warn(`Could not persist diff for local council review ${reviewId}: ${saveError.message}`);
-      }
-    }
-    const repoSettings = await repoSettingsRepo.getRepoSettings(review.repository);
-    const repoInstructions = repoSettings?.default_instructions || null;
-    const requestInstructions = rawInstructions?.trim() || null;
-
-    if (requestInstructions) {
-      await reviewRepo.updateReview(reviewId, {
-        customInstructions: requestInstructions
-      });
-    }
-
-    // Import launchCouncilAnalysis from analyses.js
-    const analysesRouter = require('./analyses');
-    const localCouncilConfig = req.app.get('config') || {};
-
-    const { providerOverrides: councilProviderOverrides, providerOverridesMap: councilProviderOverridesMap } =
-      buildCouncilProviderOverrides(localCouncilConfig, review.repository, repoSettings);
-
-    // Local mode has no associated GitHub PR, so we do not pass a githubClient.
-    // The analyzer drops the GitHub dedup section when no client is supplied.
-    const { analysisId, runId } = await analysesRouter.launchCouncilAnalysis(
-      db,
-      {
-        reviewId,
-        worktreePath: localPath,
-        prMetadata,
-        changedFiles,
-        repository: review.repository,
-        headSha: review.local_head_sha,
-        logLabel: `local review #${reviewId}`,
-        initialStatusExtra: { reviewId, reviewType: 'local' },
-        config: localCouncilConfig,
-        excludePrevious,
-        serverPort: req.socket.localPort,
-        providerOverrides: councilProviderOverrides,
-        providerOverridesMap: councilProviderOverridesMap,
-        hookContext: {
-          mode: 'local',
-          localContext: { path: localPath, branch: review.local_head_branch, headSha: review.local_head_sha },
-        },
-        runUpdateExtra: { filesAnalyzed: changedFiles ? changedFiles.length : 0 }
-      },
-      councilConfig,
-      councilId,
-      { globalInstructions: localCouncilConfig.globalInstructions || null, repoInstructions, requestInstructions },
-      configType
-    );
-
     res.json({
       analysisId,
       runId,