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

package/src/ai/provider.js

@@ -170,7 +170,8 @@ class AIProvider {
    * @returns {string} Model ID for extraction
    */
   getFastTierModel() {
-    const models = this.constructor.getModels();
+    const overrides = providerConfigOverrides.get(this.constructor.getProviderId());
+    const models = applyModelOverrides(this.constructor.getModels(), overrides);
     const fastModel = models.find(m => m.tier === 'fast');
     if (fastModel) {
       return fastModel.id;
@@ -446,17 +447,53 @@ function inferModelDefaults(model) {
 }
 
 /**
- * Resolve the default model from an array of model definitions
- * Priority: model with default:true > first balanced tier model > first model
- * @param {Array<Object>} models - Array of model definitions
+ * Match a model definition against a selector that may be the model's canonical
+ * id OR one of its aliases. Used by config-driven selectors (`default_model`,
+ * `disabled_models`, `models` overrides) so legacy config naming an alias (e.g.
+ * `opus`, an alias of the canonical `opus-4.8-xhigh`) keeps working.
+ *
+ * Optional-chaining is intentional: a model with no `aliases` short-circuits to
+ * undefined/falsy, so no Array.isArray guard is needed.
+ *
+ * @param {Object} model - Model definition (must have an `id`; may have `aliases`)
+ * @param {string} selector - Selector to match against id or aliases
+ * @returns {boolean}
+ */
+function modelMatches(model, selector) {
+  return model.id === selector || model.aliases?.includes(selector);
+}
+
+/**
+ * Resolve the default model from an array of model definitions.
+ * Priority: provider-level `default_model` (preferredId) > legacy model with
+ * `default:true` > first balanced tier model > first model.
+ *
+ * `preferredId` is the provider-level `default_model` config value. It is the
+ * preferred way to pick a default; the per-model `default:true` flag is the
+ * deprecated legacy mechanism, kept for backward compatibility. When
+ * `preferredId` names a model that isn't present (e.g. it was disabled or
+ * mistyped), resolution falls through to the legacy/automatic logic — the
+ * mismatch is warned about once at config-apply time, not here.
+ *
+ * @param {Array<Object>} models - Array of model definitions (already filtered)
+ * @param {string|null} [preferredId] - Provider-level `default_model` id
  * @returns {string|null} - Default model ID or null if no models
  */
-function resolveDefaultModel(models) {
+function resolveDefaultModel(models, preferredId = null) {
   if (!models || models.length === 0) {
     return null;
   }
 
-  // First, look for a model explicitly marked as default
+  // Provider-level `default_model` wins when it names an available model
+  // (by canonical id or alias). Returns the canonical id either way.
+  if (preferredId) {
+    const preferred = models.find(m => modelMatches(m, preferredId));
+    if (preferred) {
+      return preferred.id;
+    }
+  }
+
+  // Legacy: model explicitly marked default:true (deprecated in favor of default_model)
   const explicitDefault = models.find(m => m.default === true);
   if (explicitDefault) {
     return explicitDefault.id;
@@ -493,7 +530,7 @@ function createAliasedProviderClass(aliasId, BaseClass, aliasConfig) {
   AliasedProvider.getProviderId = () => aliasId;
   if (processedModels) {
     AliasedProvider.getModels = () => processedModels;
-    AliasedProvider.getDefaultModel = () => resolveDefaultModel(processedModels);
+    AliasedProvider.getDefaultModel = () => resolveDefaultModel(processedModels, aliasConfig.default_model || null);
   }
   if (aliasConfig.installInstructions) {
     AliasedProvider.getInstallInstructions = () => aliasConfig.installInstructions;
@@ -539,7 +576,15 @@ function applyConfigOverrides(config) {
       const { createExecutableProviderClass } = require('./executable-provider');
       const ExecClass = createExecutableProviderClass(providerId, providerConfig);
       registerProvider(providerId, ExecClass);
-      providerConfigOverrides.set(providerId, { ...providerConfig, models: ExecClass.getModels() });
+      const execDisabled = normalizeDisabledModels(providerId, providerConfig.disabled_models);
+      const execDefault = providerConfig.default_model || null;
+      validateModelSelectors(providerId, ExecClass.getModels(), null, execDisabled, execDefault);
+      providerConfigOverrides.set(providerId, {
+        ...providerConfig,
+        models: ExecClass.getModels(),
+        disabled_models: execDisabled,
+        default_model: execDefault
+      });
       logger.debug(`Registered executable provider: ${providerId}`);
       continue;
     }
@@ -550,6 +595,10 @@ function applyConfigOverrides(config) {
       const AliasClass = createAliasedProviderClass(providerId, BaseClass, providerConfig);
       registerProvider(providerId, AliasClass);
 
+      const aliasDisabled = normalizeDisabledModels(providerId, providerConfig.disabled_models);
+      const aliasDefault = providerConfig.default_model || null;
+      validateModelSelectors(providerId, AliasClass.getModels(), null, aliasDisabled, aliasDefault);
+
       // Aliases reuse the base provider's implementation class, not its config.
       // Only universal override fields are forwarded; provider-specific fields
       // (e.g. codex args) must be explicitly set in the alias config.
@@ -561,7 +610,9 @@ function applyConfigOverrides(config) {
         load_skills: providerConfig.load_skills,
         app_extensions: providerConfig.app_extensions,
         availability_timeout_seconds: providerConfig.availability_timeout_seconds,
-        models: AliasClass.getModels() !== BaseClass.getModels() ? AliasClass.getModels() : null
+        models: AliasClass.getModels() !== BaseClass.getModels() ? AliasClass.getModels() : null,
+        disabled_models: aliasDisabled,
+        default_model: aliasDefault
       });
       logger.debug(`Registered aliased provider: ${providerId} (base: ${providerConfig.type})`);
       continue;
@@ -578,8 +629,36 @@ function applyConfigOverrides(config) {
     if (Array.isArray(providerConfig.models) && providerConfig.models.length > 0) {
       processedModels = providerConfig.models.map(inferModelDefaults);
       logger.debug(`Configured ${processedModels.length} models for ${providerId}`);
+      // Deprecation: per-model `default: true` is superseded by provider-level `default_model`.
+      // Only warn when the user didn't already adopt the new field.
+      if (providerConfig.default_model == null && processedModels.some(m => m.default === true)) {
+        logger.warn(`Provider "${providerId}": per-model "default: true" is deprecated. Set provider-level "default_model": "<id>" instead.`);
+      }
     }
 
+    const builtInModels = providerRegistry.get(providerId)?.getModels();
+
+    // Canonicalize alias-keyed override ids to their built-in canonical id.
+    // A config entry may key a model by a short alias (e.g. `opus` for the
+    // canonical `opus-4.8-xhigh`). mergeModels() already resolves aliases for the
+    // display/metadata path, but the runtime path forwards this raw `models` array
+    // to the provider instance, where per-model config is looked up by EXACT id
+    // (e.g. `configOverrides.models.find(m => m.id === model)`). The frontend
+    // submits the canonical id, so an alias-keyed entry would never match and its
+    // cli_model/env/extra_args would be silently dropped. Rewriting the id here —
+    // the single point where the override is stored — keeps metadata and runtime
+    // execution in agreement.
+    if (processedModels && builtInModels) {
+      processedModels = processedModels.map(cm => {
+        const builtIn = builtInModels.find(bm => modelMatches(bm, cm.id));
+        return builtIn && builtIn.id !== cm.id ? { ...cm, id: builtIn.id } : cm;
+      });
+    }
+
+    const disabledModels = normalizeDisabledModels(providerId, providerConfig.disabled_models);
+    const defaultModel = providerConfig.default_model || null;
+    validateModelSelectors(providerId, builtInModels, processedModels, disabledModels, defaultModel);
+
     // Store the overrides
     providerConfigOverrides.set(providerId, {
       command: providerConfig.command,
@@ -589,7 +668,9 @@ function applyConfigOverrides(config) {
       load_skills: providerConfig.load_skills,
       app_extensions: providerConfig.app_extensions,
       availability_timeout_seconds: providerConfig.availability_timeout_seconds,
-      models: processedModels
+      models: processedModels,
+      disabled_models: disabledModels,
+      default_model: defaultModel
     });
   }
 
@@ -653,8 +734,12 @@ function resolveNonExecutableProviderId(preferredId) {
 
 /**
  * Merge config-override models with a provider's built-in models.
- * Config models with matching IDs replace built-ins; config models with new IDs
- * are appended. If no config models exist, returns built-ins unchanged.
+ * A config model whose id matches a built-in's canonical id OR one of its
+ * aliases replaces that built-in in place (preserving display order). The
+ * canonical built-in id is preserved as the internal source of truth, and the
+ * built-in's aliases are kept unless the override supplies its own. Config
+ * models that match no built-in are appended. If no config models exist,
+ * returns built-ins unchanged.
  *
  * @param {Array<Object>} builtInModels - Models from ProviderClass.getModels()
  * @param {Array<Object>|undefined} configModels - Models from config overrides
@@ -664,13 +749,114 @@ function mergeModels(builtInModels, configModels) {
   if (!configModels || configModels.length === 0) {
     return builtInModels;
   }
-  const configById = new Map(configModels.map(m => [m.id, m]));
-  // Replace overridden built-ins in-place to preserve display order
-  const merged = builtInModels.map(m => configById.get(m.id) || m);
-  // Append config models with new IDs not present in built-ins
-  const builtInIds = new Set(builtInModels.map(m => m.id));
-  const newModels = configModels.filter(m => !builtInIds.has(m.id));
-  return [...merged, ...newModels];
+  // Replace overridden built-ins in-place to preserve display order. An override
+  // matched by alias (e.g. config `{ id: 'opus' }` against built-in
+  // `opus-4.8-xhigh`) still replaces, but keeps the canonical built-in id.
+  const matched = new Set();
+  const merged = builtInModels.map(bm => {
+    const override = configModels.find(cm => modelMatches(bm, cm.id));
+    if (override) {
+      matched.add(override);
+      return { ...override, id: bm.id, aliases: override.aliases ?? bm.aliases };
+    }
+    return bm;
+  });
+  // Append config models that matched no built-in (genuinely new ids)
+  for (const cm of configModels) {
+    if (!matched.has(cm)) {
+      merged.push(cm);
+    }
+  }
+  return merged;
+}
+
+/**
+ * Compute the effective model list for a provider: built-in models merged with
+ * config-override models, then with any `disabled_models` IDs removed.
+ *
+ * This is the single source of truth for "which models does this provider
+ * actually expose" — every call site that surfaces or selects a model should go
+ * through here so a disabled model is hidden consistently (UI, default
+ * resolution, instance creation).
+ *
+ * If `disabled_models` would remove every model, the filter is ignored (a
+ * provider with zero models is unusable). Unknown/empty-list validation and
+ * warnings happen once at config-apply time in {@link applyConfigOverrides};
+ * this function is intentionally silent so it can run on every request.
+ *
+ * @param {Array<Object>} builtInModels - Models from ProviderClass.getModels()
+ * @param {Object} [overrides] - Stored config overrides for the provider
+ * @returns {Array<Object>} Effective model list
+ */
+function applyModelOverrides(builtInModels, overrides) {
+  const merged = mergeModels(builtInModels, overrides?.models);
+  const disabled = overrides?.disabled_models;
+  if (!Array.isArray(disabled) || disabled.length === 0) {
+    return merged;
+  }
+  // Drop a model if ANY disabled selector matches it by canonical id or alias.
+  const filtered = merged.filter(m => !disabled.some(d => modelMatches(m, d)));
+  // Never strip a provider down to zero models — fall back to the unfiltered set.
+  return filtered.length > 0 ? filtered : merged;
+}
+
+/**
+ * Normalize a `disabled_models` config value into a clean array of string IDs
+ * (or null when absent/empty). Warns on malformed input.
+ * @param {string} providerId - Provider ID (for log messages)
+ * @param {*} raw - Raw config value
+ * @returns {string[]|null}
+ */
+function normalizeDisabledModels(providerId, raw) {
+  if (raw == null) {
+    return null;
+  }
+  if (!Array.isArray(raw)) {
+    logger.warn(`Provider "${providerId}": "disabled_models" must be an array of model IDs; ignoring.`);
+    return null;
+  }
+  const ids = raw.filter(id => typeof id === 'string' && id.length > 0);
+  if (ids.length !== raw.length) {
+    logger.warn(`Provider "${providerId}": "disabled_models" contained non-string entries which were ignored.`);
+  }
+  return ids.length > 0 ? ids : null;
+}
+
+/**
+ * Validate provider-level model selectors against the effective model set and
+ * warn about mistakes. Never throws — bad selectors degrade gracefully at
+ * resolution time (a disabled-everything list is ignored, an unknown
+ * default_model falls back to automatic selection).
+ * @param {string} providerId - Provider ID (for log messages)
+ * @param {Array<Object>} builtInModels - Provider's built-in models
+ * @param {Array<Object>|null} configModels - Processed config-override models
+ * @param {string[]|null} disabledModels - Normalized disabled list
+ * @param {string|null} defaultModel - Provider-level default_model id
+ */
+function validateModelSelectors(providerId, builtInModels, configModels, disabledModels, defaultModel) {
+  const merged = mergeModels(builtInModels || [], configModels);
+  // A selector is "known" if it matches some model by canonical id OR alias.
+  const isKnown = (sel) => merged.some(m => modelMatches(m, sel));
+
+  if (disabledModels) {
+    for (const id of disabledModels) {
+      if (!isKnown(id)) {
+        logger.warn(`Provider "${providerId}": disabled_models references unknown model "${id}".`);
+      }
+    }
+    const remaining = merged.filter(m => !disabledModels.some(d => modelMatches(m, d)));
+    if (merged.length > 0 && remaining.length === 0) {
+      logger.warn(`Provider "${providerId}": disabled_models removes every model; the filter will be ignored.`);
+    }
+  }
+
+  if (defaultModel != null) {
+    if (!isKnown(defaultModel)) {
+      logger.warn(`Provider "${providerId}": default_model "${defaultModel}" is not a known model; falling back to automatic default.`);
+    } else if (disabledModels && disabledModels.includes(defaultModel)) {
+      logger.warn(`Provider "${providerId}": default_model "${defaultModel}" is also listed in disabled_models; falling back to automatic default.`);
+    }
+  }
 }
 
 /**
@@ -683,11 +869,17 @@ function getAllProvidersInfo() {
   for (const [id, ProviderClass] of providerRegistry) {
     const overrides = providerConfigOverrides.get(id);
 
-    // Merge config models with built-in models (config wins on ID collision)
-    const models = mergeModels(ProviderClass.getModels(), overrides?.models);
+    // Effective models: config merged with built-ins, minus disabled_models
+    const effectiveModels = applyModelOverrides(ProviderClass.getModels(), overrides);
+
+    // Resolve default model: provider-level default_model wins, then legacy/auto
+    const defaultModel = resolveDefaultModel(effectiveModels, overrides?.default_model) || ProviderClass.getDefaultModel();
 
-    // Resolve default model from merged models array
-    const defaultModel = resolveDefaultModel(models) || ProviderClass.getDefaultModel();
+    // Normalize per-model `default` flags to agree with the resolved defaultModel.
+    // Many frontend consumers derive the default via models.find(m => m.default),
+    // so the payload's flags must reflect the new source of truth (default_model).
+    // Produce NEW objects — never mutate the shared built-in model objects.
+    const models = effectiveModels.map(m => ({ ...m, default: m.id === defaultModel }));
 
     // Use overridden install instructions if available
     const installInstructions = overrides?.installInstructions || ProviderClass.getInstallInstructions();
@@ -736,11 +928,13 @@ function createProvider(providerId, model = null, overrides = {}) {
   // Determine the actual model to use
   let actualModel = model;
   if (!actualModel) {
-    // Resolve default from merged models (config + built-in).
+    // Resolve default from effective models (config + built-in, minus disabled).
     // Checks both sources because some providers (e.g., Pi) define built-in
-    // modes with default:true that aren't in config overrides.
+    // modes with default:true that aren't in config overrides. Honors the
+    // provider-level `default_model` selector.
     if (configOverrides?.models || ProviderClass.getModels().length > 0) {
-      actualModel = resolveDefaultModel(mergeModels(ProviderClass.getModels(), configOverrides?.models));
+      const effectiveModels = applyModelOverrides(ProviderClass.getModels(), configOverrides);
+      actualModel = resolveDefaultModel(effectiveModels, configOverrides?.default_model);
     }
     // Fall back to provider's built-in default
     if (!actualModel) {
@@ -831,7 +1025,7 @@ function getTierForModel(providerId, modelId) {
   const overrides = providerConfigOverrides.get(providerId);
   const models = mergeModels(ProviderClass.getModels(), overrides?.models);
 
-  const model = models.find(m => m.id === modelId || m.aliases?.includes(modelId));
+  const model = models.find(m => modelMatches(m, modelId));
   return model?.tier || null;
 }
 
@@ -855,6 +1049,10 @@ module.exports = {
   getProviderConfigOverrides,
   inferModelDefaults,
   resolveDefaultModel,
+  modelMatches,
+  mergeModels,
+  applyModelOverrides,
+  normalizeDisabledModels,
   prettifyModelId,
   getTierForModel
 };

package/src/councils/headless-council.js

@@ -36,10 +36,17 @@ const logger = require('../utils/logger');
  * @param {Object} params.councilConfig - The council's parsed config object
  * @param {string} params.worktreePath - Path to the checked-out worktree
  * @param {Object} [params.prMetadata] - PR metadata (head_sha used for the run row)
+ * @param {Array<Object|string>|null} [params.changedFiles] - Precomputed scope-aware
+ *   changed-file list (local mode) so council validation uses the same file set as
+ *   the generated diff; `null` in PR mode (the analyzer derives it from Git). Mirrors
+ *   the route contract (`src/routes/local.js` passes the list, `src/routes/pr.js`
+ *   passes `null`).
  * @param {Object} params.instructions - { globalInstructions, repoInstructions, requestInstructions }
  *   (requestInstructions may be null)
  * @param {Object} [params.githubClient] - GitHub client passed through to the analyzer
- * @returns {Promise<Object>} The analyzer result ({ suggestions, summary, levelOutcomes, ... })
+ * @returns {Promise<Object>} `{ runId, ...result }` — the parent run id created
+ *   here, spread together with the analyzer result
+ *   ({ suggestions, summary, levelOutcomes, ... }).
  */
 async function runHeadlessCouncilAnalysis(db, params) {
   const {
@@ -50,6 +57,7 @@ async function runHeadlessCouncilAnalysis(db, params) {
     councilConfig,
     worktreePath,
     prMetadata,
+    changedFiles,
     instructions,
     githubClient,
   } = params;
@@ -90,7 +98,9 @@ async function runHeadlessCouncilAnalysis(db, params) {
     reviewId,
     worktreePath,
     prMetadata,
-    changedFiles: null,
+    // Local headless runs forward a scope-aware list; PR mode passes null and
+    // the analyzer derives the file set from Git (matches src/routes/pr.js).
+    changedFiles: changedFiles || null,
     instructions
   };
 
@@ -108,7 +118,7 @@ async function runHeadlessCouncilAnalysis(db, params) {
       logger.warn(`Failed to update analysis_run: ${err.message}`);
     });
 
-    return result;
+    return { runId, ...result };
   } catch (error) {
     await runRepo.update(runId, { status: 'failed' }).catch(() => {});
     throw error;

package/src/database.js

@@ -3679,6 +3679,58 @@ class CommentRepository {
     `, [reviewId]);
   }
 
+  /**
+   * Get the consolidated final AI suggestions for a single analysis run.
+   *
+   * This returns the run-scoped, orchestrated (consolidated) layer: the final
+   * suggestions the app shows by default for a run — `source='ai'`,
+   * `ai_level IS NULL` (not per-level), non-raw, and (by default) not dismissed.
+   * It is the shared retrieval used by both the MCP `get_ai_suggestions` tool
+   * and the CLI JSON output for agents.
+   *
+   * INTENTIONALLY DISTINCT from the review-scoped submit query in
+   * `performHeadlessReview` (src/main.js ~1195-1207), which must NOT be migrated
+   * to this method. That query has different semantics on purpose:
+   *   - review-scoped (latest-review-wide), not single-run-scoped;
+   *   - `status = 'active'` only (no adopted);
+   *   - thin columns tailored for GitHub submission.
+   * Keep the two queries separate.
+   *
+   * @param {string} runId - Analysis run ID (`ai_run_id`)
+   * @param {Object} [options] - Query options
+   * @param {string[]} [options.statuses=['active','adopted']] - Statuses to include
+   * @param {string|null} [options.file=null] - Restrict to a single file path
+   * @returns {Promise<Array<Object>>} Consolidated final suggestion rows
+   */
+  async getFinalSuggestionsByRunId(runId, { statuses = ['active', 'adopted'], file = null } = {}) {
+    const params = [runId];
+    const conditions = [
+      'ai_run_id = ?',
+      "source = 'ai'",
+      'ai_level IS NULL',
+      '(is_raw = 0 OR is_raw IS NULL)'
+    ];
+
+    const placeholders = statuses.map(() => '?').join(', ');
+    conditions.push(`status IN (${placeholders})`);
+    params.push(...statuses);
+
+    if (file) {
+      conditions.push('file = ?');
+      params.push(file);
+    }
+
+    return await query(this.db, `
+      SELECT
+        id, ai_run_id, ai_level, ai_confidence,
+        file, line_start, line_end, type, title, body,
+        reasoning, status, is_file_level, severity, created_at
+      FROM comments
+      WHERE ${conditions.join('\n          AND ')}
+      ORDER BY file, line_start
+    `, params);
+  }
+
   /**
    * Restore a soft-deleted user comment (set status from 'inactive' back to 'active')
    * @param {number} id - Comment ID

package/src/git/worktree.js

@@ -423,7 +423,13 @@ class GitWorktreeManager {
       child.stdout.on('data', (data) => {
         const chunk = data.toString();
         stdout += chunk;
-        process.stdout.write(chunk);
+        // When PAIR_REVIEW_QUIET_STDOUT is set (headless --json or MCP stdio
+        // mode, via redirectConsoleToStderr in src/mcp-stdio.js), stdout is
+        // reserved for a machine-readable document (JSON / JSON-RPC). Mirror the
+        // child's stdout to stderr in that case so it doesn't corrupt the
+        // reserved stream; otherwise mirror it to stdout as before.
+        const sink = process.env.PAIR_REVIEW_QUIET_STDOUT ? process.stderr : process.stdout;
+        sink.write(chunk);
       });
       child.stderr.on('data', (data) => {
         const chunk = data.toString();

package/src/interactive-analysis-config.js

@@ -0,0 +1,152 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+/**
+ * Shared helpers for threading per-run CLI instructions into analysis.
+ *
+ * `resolveCliInstructions` reads `--instructions` / `--instructions-file`.
+ *
+ * `buildInteractiveAnalysisConfig` / `prepareInteractiveAnalysisConfig` bridge the
+ * CLI to the browser-side auto-analyze: interactive `--ai` / `--council` runs open
+ * the web UI and trigger analysis via the `?analyze=true` URL, which has no slot
+ * for custom instructions. To honor `--instructions` there too (instead of
+ * silently dropping it), the CLI resolves the full review config + instructions
+ * and threads a short id through the URL as `analysisConfigId`. The PR/local
+ * browser code already resolves that id before starting analysis (see
+ * `_fetchAutoAnalysisConfigFromUrl` in public/js/pr.js and the local auto-analyze
+ * in public/js/local.js).
+ *
+ * The resolution is split so the same config object serves two storage targets:
+ *   - `buildInteractiveAnalysisConfig` — PURE, returns the resolved config object
+ *     (no storage). Reused by the delegation path, which POSTs it to a server
+ *     running in ANOTHER process (the in-memory store below is per-process).
+ *   - `prepareInteractiveAnalysisConfig` — the cold-start wrapper that stashes the
+ *     built config in the in-memory bulk-analysis-config store (same process that
+ *     then starts the server) and returns the id.
+ *
+ * Living in its own module keeps both CLI entry points — `handlePullRequest`
+ * (src/main.js) and `handleLocalReview` (src/local-review.js) — able to import
+ * it without a require cycle through main.js.
+ */
+
+const fs = require('fs');
+const { resolveReviewConfig } = require('./review-config');
+const { createBulkAnalysisConfig } = require('./routes/bulk-analysis-configs');
+
+const MAX_INSTRUCTIONS_CHARS = 5000;
+
+/**
+ * Resolve per-run custom instructions ("requestInstructions") from CLI flags.
+ *
+ * Precedence: `--instructions <text>` is used directly; otherwise
+ * `--instructions-file <path>` is read from disk. The result is trimmed and
+ * capped at 5000 chars (parity with the web analyze routes). Returns `null`
+ * when neither flag is supplied.
+ *
+ * @param {Object} flags - Parsed CLI flags
+ * @returns {Promise<string|null>}
+ * @throws {Error} On unreadable instructions file or when the text exceeds the cap.
+ */
+async function resolveCliInstructions(flags) {
+  let text = null;
+
+  if (typeof flags.instructions === 'string') {
+    text = flags.instructions;
+  } else if (typeof flags.instructionsFile === 'string') {
+    try {
+      text = await fs.promises.readFile(flags.instructionsFile, 'utf8');
+    } catch (err) {
+      throw new Error(`Failed to read --instructions-file "${flags.instructionsFile}": ${err.message}`);
+    }
+  }
+
+  if (text == null) return null;
+
+  text = text.trim();
+  if (text.length === 0) return null;
+
+  if (text.length > MAX_INSTRUCTIONS_CHARS) {
+    throw new Error(
+      `Custom instructions exceed the ${MAX_INSTRUCTIONS_CHARS}-character limit (got ${text.length}).`
+    );
+  }
+
+  return text;
+}
+
+/**
+ * For an interactive `--ai` / `--council` run that ALSO carries
+ * `--instructions[-file]`, resolve the full review config (single provider/model
+ * or council) plus the instruction text into the analysis-config object the
+ * browser-side analyze code consumes. PURE: it performs no storage, so it serves
+ * both the in-process cold-start path (via `prepareInteractiveAnalysisConfig`)
+ * and the cross-process delegation path (which POSTs the object to the running
+ * server — see `storeAnalysisConfigRemote` in src/single-port.js).
+ *
+ * Returns `null` when no instructions were supplied, so callers keep their prior
+ * URL shape (bare `?analyze=true` + optional `&council=`) unchanged.
+ *
+ * The returned config is shape-compatible with what the browser-side analyze code
+ * consumes: a single pick becomes `{ provider, model, customInstructions }`; a
+ * council becomes an inline snapshot `{ isCouncil, configType, councilConfig,
+ * councilName, customInstructions }` (the snapshot forces the analysis route to
+ * use the exact resolved council rather than re-fetching by id).
+ *
+ * @param {Object} params
+ * @param {Object} params.db - Database instance
+ * @param {Object} params.config - Loaded global config
+ * @param {Object} params.flags - Parsed CLI flags (council/model/instructions)
+ * @param {string} params.repository - owner/repo (for repo-default resolution)
+ * @returns {Promise<Object|null>} The analysisConfig object, or null when no instructions.
+ */
+async function buildInteractiveAnalysisConfig({ db, config, flags, repository }) {
+  const requestInstructions = await resolveCliInstructions(flags);
+  if (!requestInstructions) return null;
+
+  const reviewConfig = await resolveReviewConfig(
+    db,
+    repository,
+    { council: flags.council, model: flags.model },
+    config
+  );
+
+  return reviewConfig.type === 'council'
+    ? {
+        isCouncil: true,
+        configType: reviewConfig.configType,
+        councilConfig: reviewConfig.councilConfig,
+        councilName: reviewConfig.council.name || null,
+        customInstructions: requestInstructions
+      }
+    : {
+        provider: reviewConfig.provider,
+        model: reviewConfig.model,
+        customInstructions: requestInstructions
+      };
+}
+
+/**
+ * Thin in-process wrapper around `buildInteractiveAnalysisConfig`: resolve the
+ * analysis config and, when present, stash it in the in-memory
+ * bulk-analysis-config store, returning the id to thread through the browser URL
+ * as `analysisConfigId`. Used by the cold-start handlers (`handlePullRequest`,
+ * `handleLocalReview`) that go on to start the server in THIS process, so the
+ * in-process store is the one the browser tab will read from.
+ *
+ * Returns `null` when no instructions were supplied (callers keep their prior URL
+ * shape unchanged).
+ *
+ * @param {Object} params - See `buildInteractiveAnalysisConfig`.
+ * @returns {Promise<string|null>} The analysisConfigId, or null when no instructions.
+ */
+async function prepareInteractiveAnalysisConfig({ db, config, flags, repository }) {
+  const analysisConfig = await buildInteractiveAnalysisConfig({ db, config, flags, repository });
+  if (!analysisConfig) return null;
+
+  const { id } = createBulkAnalysisConfig(analysisConfig);
+  return id;
+}
+
+module.exports = {
+  resolveCliInstructions,
+  buildInteractiveAnalysisConfig,
+  prepareInteractiveAnalysisConfig
+};