@in-the-loop-labs/pair-review 3.5.2 → 3.7.0

package/src/main.js

@@ -1,6 +1,6 @@
 // Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
 const fs = require('fs');
-const { loadConfig, getConfigDir, getGitHubToken, showWelcomeMessage, resolveDbName, resolveRepoOptions, resolvePoolConfig, getRepoResetScript, resolveLoadSkills } = require('./config');
+const { loadConfig, getConfigDir, getGitHubToken, resolveHostBinding, showWelcomeMessage, resolveDbName, resolveRepoOptions, resolvePoolConfig, getRepoResetScript, resolveLoadSkills } = require('./config');
 const { initializeDatabase, run, queryOne, query, migrateExistingWorktrees, WorktreeRepository, ReviewRepository, RepoSettingsRepository, GitHubReviewRepository, WorktreePoolRepository } = require('./database');
 const { PRArgumentParser } = require('./github/parser');
 const { GitHubClient } = require('./github/client');
@@ -26,6 +26,47 @@ const { attemptDelegation } = require('./single-port');
 
 let db = null;
 
+/**
+ * Build a user-facing "missing token" error message tailored to the
+ * resolved host binding.
+ *
+ * For github.com bindings (`apiHost === null`), suggest the legacy
+ * options: `GITHUB_TOKEN` env var, `config.github_token`, or
+ * `config.github_token_command`. For alt-host bindings, suppress those
+ * suggestions (the github.com top-level credentials are intentionally
+ * not used for alt-hosts) and point exclusively at the per-repo
+ * `token` / `token_command` keys under the resolved bindingRepository.
+ *
+ * @param {Object} params
+ * @param {string} params.owner
+ * @param {string} params.repo
+ * @param {string} params.bindingRepository - The `repos[...]` config key
+ *   that the binding lookup was performed against. May differ from
+ *   `<owner>/<repo>` for monorepo-style configs (see Fix #8).
+ * @param {string|null} params.apiHost - Resolved api_host (null = github.com)
+ * @returns {string}
+ */
+function buildMissingTokenError({ owner, repo, bindingRepository, apiHost }) {
+  if (apiHost) {
+    return (
+      `GitHub token not found for alt-host repo ${owner}/${repo} (${apiHost}). ` +
+      `GITHUB_TOKEN and top-level github_token/github_token_command are github.com-only ` +
+      `and are not used for alt-hosts. Configure ` +
+      `\`config.repos["${bindingRepository}"].token\` or ` +
+      `\`config.repos["${bindingRepository}"].token_command\` ` +
+      `(e.g., "althost-cli auth token"). Run: npx pair-review --configure`
+    );
+  }
+  return (
+    `GitHub token not found for ${owner}/${repo}. ` +
+    `Set GITHUB_TOKEN env var, or configure a token at ` +
+    `\`config.repos["${bindingRepository}"].token\` or ` +
+    `\`config.repos["${bindingRepository}"].token_command\`, or set ` +
+    `top-level \`github_token\` / \`github_token_command\` ` +
+    `(e.g., "gh auth token"). Run: npx pair-review --configure`
+  );
+}
+
 /**
  * Detect PR information from GitHub Actions environment variables.
  * Returns null if not in GitHub Actions or PR info cannot be determined.
@@ -573,16 +614,33 @@ AI PROVIDERS:
  */
 async function handlePullRequest(args, config, db, flags = {}, poolLifecycle = null) {
   try {
-    // Get GitHub token (env var takes precedence over config)
-    const githubToken = getGitHubToken(config);
-    if (!githubToken) {
-      throw new Error('GitHub token not found. Set GITHUB_TOKEN env var, add github_token to config, or set github_token_command (e.g., "gh auth token"). Run: npx pair-review --configure');
-    }
-
-    // Parse PR arguments
-    const parser = new PRArgumentParser();
+    // Parse PR arguments FIRST — pass config so url_pattern matching for
+    // alternate hosts can resolve pasted URLs to the canonical
+    // owner/repo before falling back to GitHub/Graphite parsers.
+    // We must know the target repo before resolving its token, so that
+    // repo-scoped tokens, repo-scoped token_command entries, and alt-host
+    // configurations are honored. A no-repository token preflight only
+    // sees env + top-level credentials and would reject valid configs.
+    const parser = new PRArgumentParser(config);
     const prInfo = await parser.parsePRArguments(args);
 
+    // Resolve token via repo-aware host binding so alt-host and
+    // repo-scoped credentials are respected. When a per-repo
+    // `url_pattern` matched, prefer its `bindingRepository` — that's the
+    // matched `repos[...]` config key, which may differ from the
+    // captured `${owner}/${repo}` for monorepo-style patterns.
+    const repositoryForBinding = prInfo.bindingRepository
+      || normalizeRepository(prInfo.owner, prInfo.repo);
+    const binding = resolveHostBinding(repositoryForBinding, config);
+    if (!binding.token) {
+      throw new Error(buildMissingTokenError({
+        owner: prInfo.owner,
+        repo: prInfo.repo,
+        bindingRepository: repositoryForBinding,
+        apiHost: binding.apiHost
+      }));
+    }
+
     // Register cwd as known repo path if it matches the target repo
     const currentDir = parser.getCurrentDirectory();
     const isMatchingRepo = await parser.isMatchingRepository(currentDir, prInfo.owner, prInfo.repo);
@@ -677,20 +735,33 @@ async function performHeadlessReview(args, config, db, flags, options, externalP
   let poolLifecycle = null;
 
   try {
-    // Get GitHub token (env var takes precedence over config)
-    const githubToken = getGitHubToken(config);
-    if (!githubToken) {
-      throw new Error('GitHub token not found. Set GITHUB_TOKEN env var, add github_token to config, or set github_token_command (e.g., "gh auth token"). Run: npx pair-review --configure');
-    }
-
-    // Parse PR arguments
-    const parser = new PRArgumentParser();
+    // Parse PR arguments — pass config so url_pattern matching for
+    // alternate hosts can resolve pasted URLs to the canonical
+    // owner/repo before falling back to GitHub/Graphite parsers.
+    const parser = new PRArgumentParser(config);
     prInfo = await parser.parsePRArguments(args);
 
+    // Resolve host binding for the target repo (handles alt-host).
+    // Prefer `bindingRepository` (from url_pattern match) over the raw
+    // `${owner}/${repo}` since they can differ when one config entry
+    // serves many monorepo-shaped URLs.
+    const repositoryForBinding = prInfo.bindingRepository
+      || normalizeRepository(prInfo.owner, prInfo.repo);
+    const headlessBinding = resolveHostBinding(repositoryForBinding, config);
+    if (!headlessBinding.token) {
+      throw new Error(buildMissingTokenError({
+        owner: prInfo.owner,
+        repo: prInfo.repo,
+        bindingRepository: repositoryForBinding,
+        apiHost: headlessBinding.apiHost
+      }));
+    }
+    const githubToken = headlessBinding.token;
+
     console.log(`Processing pull request #${prInfo.number} from ${prInfo.owner}/${prInfo.repo} in ${options.modeLabel}`);
 
     // Create GitHub client and verify repository access
-    const githubClient = new GitHubClient(githubToken);
+    const githubClient = new GitHubClient(headlessBinding);
     const repoExists = await githubClient.repositoryExists(prInfo.owner, prInfo.repo);
     if (!repoExists) {
       throw new Error(`Repository ${prInfo.owner}/${prInfo.repo} not found or not accessible`);
@@ -786,9 +857,10 @@ async function performHeadlessReview(args, config, db, flags, options, externalP
 
         // Resolve monorepo config options (checkout_script, worktree_directory, worktree_name_template)
         // even when running from inside the target repo, so they are not silently ignored.
+        // Config lookups must use the binding key (matched `repos[...]` entry), not the PR identity.
         const repoSettingsRepo = new RepoSettingsRepository(db);
         const repoSettings = await repoSettingsRepo.getRepoSettings(repository);
-        const resolved = resolveRepoOptions(config, repository, repoSettings);
+        const resolved = resolveRepoOptions(config, repositoryForBinding, repoSettings);
         checkoutScript = resolved.checkoutScript;
         checkoutTimeout = resolved.checkoutTimeout;
         worktreeConfig = resolved.worktreeConfig;
@@ -802,8 +874,10 @@ async function performHeadlessReview(args, config, db, flags, options, externalP
           owner: prInfo.owner,
           repo: prInfo.repo,
           repository,
+          bindingRepository: repositoryForBinding,
           prNumber: prInfo.number,
           config,
+          cloneUrl: prData?.repository?.clone_url,
           onProgress: (progress) => {
             if (progress.message) {
               console.log(progress.message);
@@ -816,11 +890,12 @@ async function performHeadlessReview(args, config, db, flags, options, externalP
         checkoutTimeout = result.checkoutTimeout;
         worktreeConfig = result.worktreeConfig;
         // findRepositoryPath doesn't return pool config; resolve from DB + file config
+        // (binding key, not PR identity).
         const repoSettingsRepo = new RepoSettingsRepository(db);
         const repoSettings = await repoSettingsRepo.getRepoSettings(repository);
-        const { poolSize: resolvedPoolSize, poolFetchIntervalMinutes: _resolvedFetchInterval } = resolvePoolConfig(config, repository, repoSettings);
+        const { poolSize: resolvedPoolSize, poolFetchIntervalMinutes: _resolvedFetchInterval } = resolvePoolConfig(config, repositoryForBinding, repoSettings);
         poolSize = resolvedPoolSize || 0;
-        resetScript = config ? getRepoResetScript(config, repository) : null;
+        resetScript = config ? getRepoResetScript(config, repositoryForBinding) : null;
       }
 
       const worktreeManager = new GitWorktreeManager(db, worktreeConfig || {});
@@ -906,8 +981,11 @@ async function performHeadlessReview(args, config, db, flags, options, externalP
 
     let analysisSummary = null;
     try {
-      // Pass all instruction levels to ensure they're captured in the analysis run
-      const analysisResult = await analyzer.analyzeAllLevels(review.id, worktreePath, storedPRData, null, { globalInstructions, repoInstructions });
+      // Pass all instruction levels to ensure they're captured in the analysis run.
+      // githubClient is forwarded so the analyzer can pre-fetch existing PR review
+      // comments when callers opt in via excludePrevious.github.
+      logger.debug(`analyzer githubClient wired for ${prInfo.owner}/${prInfo.repo}#${prInfo.number}`);
+      const analysisResult = await analyzer.analyzeAllLevels(review.id, worktreePath, storedPRData, null, { globalInstructions, repoInstructions }, null, { githubClient });
       analysisSummary = analysisResult.summary;
       console.log('AI analysis completed successfully');
     } catch (analysisError) {
@@ -992,24 +1070,49 @@ Found ${validSuggestions.length} suggestion${validSuggestions.length === 1 ? ''
     // Submit review to GitHub via GraphQL (same path as web UI)
     console.log(`Submitting review with ${githubComments.length} comments...`);
 
-    const prNodeId = storedPRData.node_id;
-    if (!prNodeId) {
-      throw new Error(`PR node_id not available for ${prInfo.owner}/${prInfo.repo}#${prInfo.number}. Cannot submit review without GraphQL node ID.`);
-    }
-
     // Check for existing pending draft (GitHub only allows one per user per PR)
     const existingDraft = await githubClient.getPendingReviewForUser(
       prInfo.owner, prInfo.repo, prInfo.number
     );
 
+    // GraphQL PR node id is only required when we'll be creating a NEW
+    // GraphQL review (no existing draft to reuse) OR adding GraphQL
+    // review comments. REST and host-impl configurations address the
+    // PR by (owner, repo, prNumber) + numeric review id and ignore
+    // prNodeId; reusing an existing GraphQL draft also doesn't need
+    // the PR node id because the review node id is sufficient.
+    const willCreateNewGraphQLReview =
+      headlessBinding.features.review_lifecycle === 'graphql' && !existingDraft;
+    const willAddGraphQLComments =
+      githubComments.length > 0 && headlessBinding.features.pending_review_comments === 'graphql';
+    const needsGraphQLNodeId = willCreateNewGraphQLReview || willAddGraphQLComments;
+
+    if (needsGraphQLNodeId && !storedPRData.node_id) {
+      throw new Error(
+        `GraphQL PR node id required for ${prInfo.owner}/${prInfo.repo}#${prInfo.number} ` +
+        `(features.review_lifecycle = "${headlessBinding.features.review_lifecycle}", ` +
+        `pending_review_comments = "${headlessBinding.features.pending_review_comments}"). ` +
+        `PR record is missing node_id — refresh the PR data and try again.`
+      );
+    }
+
+    const prNodeId = storedPRData.node_id ?? null;
+
+    const submitPrContext = {
+      owner: prInfo.owner,
+      repo: prInfo.repo,
+      prNumber: prInfo.number,
+      reviewId: existingDraft?.databaseId
+    };
+
     let githubReview;
     if (options.reviewEvent === 'DRAFT') {
       githubReview = await githubClient.createDraftReviewGraphQL(
-        prNodeId, reviewBody, githubComments, existingDraft?.id
+        prNodeId, reviewBody, githubComments, existingDraft?.id, submitPrContext
       );
     } else {
       githubReview = await githubClient.createReviewGraphQL(
-        prNodeId, options.reviewEvent, reviewBody, githubComments, existingDraft?.id
+        prNodeId, options.reviewEvent, reviewBody, githubComments, existingDraft?.id, submitPrContext
       );
     }
 

package/src/routes/analyses.js

@@ -33,7 +33,8 @@ const {
   killProcesses,
   createProgressCallback
 } = require('./shared');
-const { generateLocalDiff, computeLocalDiffDigest, getCurrentBranch } = require('../local-review');
+const { generateScopedDiff, computeScopedDigest, getCurrentBranch } = require('../local-review');
+const { reviewScope } = require('../local-scope');
 const { validateCouncilConfig, normalizeCouncilConfig } = require('./councils');
 const { TIERS, TIER_ALIASES, VALID_TIERS, resolveTier } = require('../ai/prompts/config');
 
@@ -229,13 +230,34 @@ router.post('/api/analyses/results', async (req, res) => {
         });
       }
 
-      // Generate and store diff so the web UI can display it
+      // Generate and store diff so the web UI can display it. Persist to the
+      // `local_diffs` table as well as the in-memory cache so the diff survives
+      // a restart and the manual tour/summary buttons never falsely report
+      // "no-diff" for a review created via this analysis-push path.
+      //
+      // Use the review's recorded scope (mirroring the council path) — NOT the
+      // default-scope `generateLocalDiff` wrapper — so that re-using an existing
+      // review whose scope is `staged` or `branch` does not clobber its durable
+      // `local_diffs` row with a narrower default-scope patch. For brand-new
+      // reviews the upsert above created a default-scope row, so either lookup
+      // yields the correct scope; reviewScope() falls back to the default scope
+      // when the columns are unset.
+      const reviewForScope = existingReview || await reviewRepo.getLocalReviewById(reviewId);
+      const { start: scopeStart, end: scopeEnd } = reviewScope(reviewForScope);
       try {
-        const diffResult = await generateLocalDiff(localPath);
-        const digest = await computeLocalDiffDigest(localPath);
+        const diffResult = await generateScopedDiff(
+          localPath,
+          scopeStart,
+          scopeEnd,
+          reviewForScope.local_base_branch || null
+        );
+        const digest = await computeScopedDigest(localPath, scopeStart, scopeEnd);
         localReviewDiffs.set(reviewId, { diff: diffResult.diff, stats: diffResult.stats, digest });
+        await reviewRepo.saveLocalDiff(reviewId, { diff: diffResult.diff, stats: diffResult.stats, digest });
       } catch (diffError) {
-        logger.warn(`Could not generate diff for local review ${reviewId}: ${diffError.message}`);
+        // Covers both diff generation AND the durable saveLocalDiff write, so the
+        // message names both failure modes rather than only generation.
+        logger.warn(`Could not generate or persist diff for local review ${reviewId}: ${diffError.message}`);
       }
     } else {
       const repoParts = repo.split('/');
@@ -495,6 +517,7 @@ async function launchCouncilAnalysis(db, modeContext, councilConfig, councilId,
     config: modeConfig,
     excludePrevious,
     serverPort,
+    githubClient,
     providerOverrides = {},
     providerOverridesMap = null,
     hookContext = {},
@@ -606,8 +629,8 @@ async function launchCouncilAnalysis(db, modeContext, councilConfig, councilId,
     };
 
     analysisPromise = isVoiceCentric
-      ? analyzer.runReviewerCentricCouncil(reviewContext, councilConfig, { analysisId, runId, progressCallback, excludePrevious, serverPort })
-      : analyzer.runCouncilAnalysis(reviewContext, councilConfig, { analysisId, runId, progressCallback, excludePrevious, serverPort });
+      ? analyzer.runReviewerCentricCouncil(reviewContext, councilConfig, { analysisId, runId, progressCallback, excludePrevious, serverPort, githubClient })
+      : analyzer.runCouncilAnalysis(reviewContext, councilConfig, { analysisId, runId, progressCallback, excludePrevious, serverPort, githubClient });
   } catch (setupError) {
     // Synchronous setup failure — clean up the analysis hold immediately
     reviewToAnalysisId.delete(reviewId);

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

@@ -0,0 +1,295 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+/**
+ * Bulk analysis configuration routes.
+ *
+ * The index page can open many PR tabs at once. Rather than placing a large
+ * analysis configuration in every PR URL, the browser stores it here and passes
+ * a short ID through the setup/review URL. Each PR tab then resolves the ID
+ * before starting auto-analysis.
+ */
+
+const crypto = require('crypto');
+const express = require('express');
+const logger = require('../utils/logger');
+const { VALID_TIERS } = require('../ai/prompts/config');
+const { getAllProvidersInfo } = require('../ai');
+const { normalizeCouncilConfig, validateCouncilConfig } = require('./councils');
+
+const router = express.Router();
+
+const configs = new Map();
+const CONFIG_TTL_MS = 30 * 60 * 1000;
+const MAX_CONFIGS = 1000;
+const MAX_INSTRUCTIONS_LENGTH = 5000;
+const VALID_TIER_SET = new Set(VALID_TIERS);
+const VALID_CONFIG_TYPES = new Set(['council', 'advanced']);
+const FORBIDDEN_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
+
+function pruneExpired(now = Date.now()) {
+  for (const [id, entry] of configs.entries()) {
+    if (entry.expiresAt <= now) {
+      configs.delete(id);
+    }
+  }
+}
+
+function enforceMaxConfigs() {
+  while (configs.size > MAX_CONFIGS) {
+    const oldestId = configs.keys().next().value;
+    if (!oldestId) return;
+    configs.delete(oldestId);
+  }
+}
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validateString(value, field, { required = false, max = 200 } = {}) {
+  if (value == null) {
+    return required ? `${field} is required` : null;
+  }
+  if (typeof value !== 'string' || value.trim().length === 0 || value.length > max) {
+    return `${field} must be a non-empty string up to ${max} characters`;
+  }
+  return null;
+}
+
+function validateCustomInstructions(value) {
+  if (value == null) return null;
+  if (typeof value !== 'string') return 'customInstructions must be a string';
+  if (value.length > MAX_INSTRUCTIONS_LENGTH) {
+    return `customInstructions exceed maximum length of ${MAX_INSTRUCTIONS_LENGTH} characters`;
+  }
+  return null;
+}
+
+function validateJsonShape(value, path = 'analysisConfig', depth = 0) {
+  if (depth > 20) return `${path} is too deeply nested`;
+  if (value == null || typeof value === 'boolean' || typeof value === 'number' || typeof value === 'string') {
+    return null;
+  }
+  if (Array.isArray(value)) {
+    if (value.length > 200) return `${path} has too many items`;
+    for (let i = 0; i < value.length; i++) {
+      const error = validateJsonShape(value[i], `${path}[${i}]`, depth + 1);
+      if (error) return error;
+    }
+    return null;
+  }
+  if (!isPlainObject(value)) return `${path} must contain only JSON values`;
+
+  const entries = Object.entries(value);
+  if (entries.length > 200) return `${path} has too many keys`;
+  for (const [key, child] of entries) {
+    if (FORBIDDEN_KEYS.has(key)) return `${path} contains forbidden key ${key}`;
+    const error = validateJsonShape(child, `${path}.${key}`, depth + 1);
+    if (error) return error;
+  }
+  return null;
+}
+
+function sanitizeExcludePrevious(value) {
+  if (value == null) return { error: null, value: undefined };
+  if (!isPlainObject(value)) return { error: 'excludePrevious must be an object' };
+  return {
+    error: null,
+    value: {
+      github: value.github === true,
+      feedback: value.feedback === true
+    }
+  };
+}
+
+function sanitizeEnabledLevels(value) {
+  if (value == null) return { error: null, value: undefined };
+  if (!Array.isArray(value)) return { error: 'enabledLevels must be an array' };
+
+  const levels = [];
+  for (const level of value) {
+    const number = Number(level);
+    if (![1, 2, 3].includes(number)) {
+      return { error: 'enabledLevels may only include levels 1, 2, and 3' };
+    }
+    if (!levels.includes(number)) levels.push(number);
+  }
+
+  if (levels.length === 0) return { error: 'enabledLevels must include at least one level' };
+  return { error: null, value: levels };
+}
+
+function sanitizeSingleConfig(config) {
+  let error = validateString(config.provider, 'provider', { required: true });
+  if (error) return { error };
+
+  error = validateString(config.model, 'model', { required: true });
+  if (error) return { error };
+
+  if (config.tier != null && (!VALID_TIER_SET.has(config.tier))) {
+    return { error: `tier must be one of ${VALID_TIERS.join(', ')}` };
+  }
+
+  // The modal builds two related fields: `instructions` carries the *effective*
+  // prompt (selected preset chips concatenated with the textarea) while
+  // `customInstructions` is the raw textarea only. Persist the effective prompt
+  // so bulk-launched analyses see the same prompt the modal showed the user —
+  // otherwise any chosen preset chips are silently dropped.
+  const effectiveInstructions = config.instructions || config.customInstructions;
+
+  error = validateCustomInstructions(effectiveInstructions);
+  if (error) return { error };
+
+  const enabledLevels = sanitizeEnabledLevels(config.enabledLevels);
+  if (enabledLevels.error) return { error: enabledLevels.error };
+
+  const excludePrevious = sanitizeExcludePrevious(config.excludePrevious);
+  if (excludePrevious.error) return { error: excludePrevious.error };
+
+  // Defense in depth: the bulk replay path forwards this stored pair straight to
+  // analysis with no client-side guard. If the model does not belong to the
+  // 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.
+  let normalizedModel = config.model;
+  const providerInfo = getAllProvidersInfo().find(p => p.id === config.provider);
+  if (providerInfo && !providerInfo.models.some(m => m.id === config.model)) {
+    normalizedModel = providerInfo.defaultModel || config.model;
+  }
+
+  return {
+    error: null,
+    config: {
+      provider: config.provider,
+      model: normalizedModel,
+      tier: config.tier,
+      customInstructions: effectiveInstructions || null,
+      enabledLevels: enabledLevels.value,
+      skipLevel3: config.skipLevel3 === true,
+      noLevels: config.noLevels === true,
+      excludePrevious: excludePrevious.value
+    }
+  };
+}
+
+function sanitizeCouncilConfig(config) {
+  // configType selects which downstream validator runs, so reject unrecognized
+  // values rather than silently coercing them (which could route councilConfig
+  // through the wrong validator).
+  if (config.configType != null && !VALID_CONFIG_TYPES.has(config.configType)) {
+    return { error: `configType must be one of ${[...VALID_CONFIG_TYPES].join(', ')}` };
+  }
+  const configType = config.configType || 'advanced';
+
+  let error = validateString(config.councilId, 'councilId', { max: 128 });
+  if (error) return { error };
+
+  if (config.councilName != null) {
+    error = validateString(config.councilName, 'councilName', { max: 200 });
+    if (error) return { error };
+  }
+
+  error = validateCustomInstructions(config.customInstructions);
+  if (error) return { error };
+
+  const excludePrevious = sanitizeExcludePrevious(config.excludePrevious);
+  if (excludePrevious.error) return { error: excludePrevious.error };
+
+  if (!config.councilId && !config.councilConfig) {
+    return { error: 'Either councilId or councilConfig is required' };
+  }
+
+  let councilConfig;
+  if (config.councilConfig != null) {
+    const shapeError = validateJsonShape(config.councilConfig, 'councilConfig');
+    if (shapeError) return { error: shapeError };
+
+    councilConfig = normalizeCouncilConfig(config.councilConfig, configType);
+    const councilError = validateCouncilConfig(councilConfig, configType);
+    if (councilError) return { error: `Invalid council config: ${councilError}` };
+  }
+
+  return {
+    error: null,
+    config: {
+      isCouncil: true,
+      configType,
+      // When an inline snapshot is stored, drop councilId so the downstream
+      // analysis route is forced to use the exact modal-selected councilConfig
+      // rather than re-fetching (and possibly diverging from) the DB record.
+      councilId: councilConfig ? undefined : (config.councilId || undefined),
+      councilName: config.councilName || null,
+      councilConfig,
+      customInstructions: config.customInstructions || null,
+      excludePrevious: excludePrevious.value
+    }
+  };
+}
+
+function sanitizeAnalysisConfig(config) {
+  if (!isPlainObject(config)) {
+    return { error: 'analysisConfig object required' };
+  }
+
+  const shapeError = validateJsonShape(config);
+  if (shapeError) return { error: shapeError };
+
+  if (config.isCouncil === true) {
+    return sanitizeCouncilConfig(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 });
+    }
+
+    pruneExpired();
+
+    const id = crypto.randomUUID();
+    configs.set(id, {
+      analysisConfig: result.config,
+      expiresAt: Date.now() + CONFIG_TTL_MS
+    });
+    enforceMaxConfigs();
+
+    res.json({ success: true, id, expiresInMs: CONFIG_TTL_MS });
+  } catch (error) {
+    logger.error('Failed to store bulk analysis config:', error);
+    res.status(500).json({ error: 'Failed to store bulk analysis config' });
+  }
+});
+
+router.get('/api/bulk-analysis-configs/:id', (req, res) => {
+  const { id } = req.params;
+  pruneExpired();
+
+  const entry = configs.get(id);
+  if (!entry) {
+    return res.status(404).json({ error: 'Bulk analysis config not found' });
+  }
+
+  res.json({
+    success: true,
+    analysisConfig: entry.analysisConfig
+  });
+});
+
+function _resetBulkAnalysisConfigs() {
+  configs.clear();
+}
+
+function _getBulkAnalysisConfig(id) {
+  const entry = configs.get(id);
+  return entry ? entry.analysisConfig : null;
+}
+
+module.exports = router;
+module.exports._resetBulkAnalysisConfigs = _resetBulkAnalysisConfigs;
+module.exports._getBulkAnalysisConfig = _getBulkAnalysisConfig;
+module.exports._pruneExpired = pruneExpired;
+module.exports._CONFIG_TTL_MS = CONFIG_TTL_MS;
+module.exports._MAX_CONFIGS = MAX_CONFIGS;
+module.exports._sanitizeAnalysisConfig = sanitizeAnalysisConfig;