@in-the-loop-labs/pair-review 3.0.5 → 3.1.0

package/src/ai/analyzer.js

@@ -1,5 +1,6 @@
 // Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
-const { createProvider } = require('./index');
+const { createProvider, getProviderClass } = require('./index');
+const os = require('os');
 const { v4: uuidv4 } = require('uuid');
 const path = require('path');
 const fs = require('fs').promises;
@@ -24,9 +25,8 @@ const { AnalysisRunRepository, CommentRepository } = require('../database');
 const { mergeInstructions } = require('../utils/instructions');
 const { GitWorktreeManager } = require('../git/worktree');
 const { buildSparseCheckoutGuidance } = require('./prompts/sparse-checkout-guidance');
+const { generateDiffForExecutable } = require('../routes/executable-analysis');
 
-/** Minimum total suggestion count across all voices before consolidation is applied */
-const COUNCIL_CONSOLIDATION_THRESHOLD = 8;
 
 // GIT_DIFF_FLAGS imported from ../git/diff-flags
 
@@ -87,7 +87,14 @@ function buildVoiceContext(voice, idx, instructions, progressCallback, db) {
       : voice.customInstructions;
   }
 
-  const voiceAnalyzer = new Analyzer(db, voice.model, voice.provider);
+  const ProviderClass = getProviderClass(voice.provider);
+  const isExecutable = ProviderClass?.isExecutable || false;
+
+  // Only create Analyzer for native voices
+  const voiceAnalyzer = isExecutable ? null : new Analyzer(db, voice.model, voice.provider);
+  // Create provider instance for executable voices (used directly)
+  const voiceProvider = isExecutable ? createProvider(voice.provider, voice.model) : null;
+
   const voiceTier = voice.tier || 'balanced';
   const voiceTimeout = voice.timeout || 600000;
 
@@ -100,7 +107,159 @@ function buildVoiceContext(voice, idx, instructions, progressCallback, db) {
     });
   } : null;
 
-  return { voiceAnalyzer, voiceKey, reviewerLabel, voiceRequestInstructions, voiceProgressCallback, voiceTier, voiceTimeout };
+  return { voiceAnalyzer, voiceProvider, isExecutable, voiceKey, reviewerLabel, voiceRequestInstructions, voiceProgressCallback, voiceTier, voiceTimeout };
+}
+
+/**
+ * Run an executable provider as a council voice.
+ * Mirrors the pattern in src/routes/executable-analysis.js but without Express/HTTP concerns.
+ *
+ * @param {Object} voiceProvider - Provider instance from createProvider()
+ * @param {number|string} reviewId - Review ID
+ * @param {string} worktreePath - Path to the git worktree
+ * @param {Object} prMetadata - PR metadata
+ * @param {Object} options - { analysisId, timeout, requestInstructions, progressCallback, logPrefix }
+ * @returns {Promise<Object>} { suggestions, summary }
+ */
+async function runExecutableVoice(voiceProvider, reviewId, worktreePath, prMetadata, options) {
+  const { analysisId, timeout, requestInstructions, progressCallback, logPrefix } = options;
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'pair-review-exec-'));
+  try {
+    const executableContext = {
+      title: prMetadata.title || '',
+      description: prMetadata.description || '',
+      cwd: worktreePath,
+      outputDir: tmpDir,
+      model: voiceProvider.resolvedModel !== undefined ? voiceProvider.resolvedModel : (voiceProvider.model || null),
+      baseSha: prMetadata.base_sha || null,
+      headSha: prMetadata.head_sha || null,
+      baseBranch: prMetadata.base_branch || null,
+      headBranch: prMetadata.head_branch || null,
+      scopeStart: prMetadata.scopeStart || null,
+      scopeEnd: prMetadata.scopeEnd || null,
+      customInstructions: requestInstructions || null,
+    };
+
+    // Generate scoped diff file when provider expects diff_path
+    if (voiceProvider.contextArgs?.diff_path) {
+      const diffPath = path.join(tmpDir, 'review.diff');
+      try {
+        await generateDiffForExecutable(
+          worktreePath,
+          executableContext,
+          voiceProvider.diffArgs || [],
+          diffPath
+        );
+        executableContext.diffPath = diffPath;
+      } catch (diffError) {
+        logger.warn(
+          `${logPrefix || ''}Failed to generate diff for executable voice: ${diffError.message} — continuing without diff`
+        );
+      }
+    }
+
+    // Emit initial running status (non-stream) so the progress modal
+    // populates exec.voices[voiceId] and transitions from Pending to Running
+    if (progressCallback) {
+      progressCallback({ level: 'exec', status: 'running', progress: 'Starting external tool...' });
+    }
+
+    const result = await voiceProvider.execute(null, {
+      executableContext,
+      cwd: worktreePath,
+      timeout: timeout || voiceProvider.timeout || 600000,
+      analysisId,
+      registerProcess,
+      onStreamEvent: progressCallback ? (event) => {
+        progressCallback({ level: 'exec', status: 'running', streamEvent: event });
+      } : null
+    });
+
+    if (!result?.success || !result?.data) {
+      throw new Error(`${logPrefix || ''}Executable provider returned no data`);
+    }
+
+    return {
+      suggestions: result.data.suggestions || [],
+      summary: result.data.summary || ''
+    };
+  } finally {
+    if (logger.isStreamDebugEnabled()) {
+      logger.info(`[ExecutableVoice] Keeping output dir for debug: ${tmpDir}`);
+    } else {
+      try { await fs.rm(tmpDir, { recursive: true, force: true }); } catch (_) {}
+    }
+  }
+}
+
+/**
+ * Build the dedup context object from PR metadata and run identifiers.
+ *
+ * @param {Object} prMetadata - PR metadata with repository and pr_number
+ * @param {Object} ids - { reviewId, serverPort, runId, excludeRunIds }
+ * @param {string} [ids.runId] - Single run ID to exclude (backward compat)
+ * @param {string[]} [ids.excludeRunIds] - Array of run IDs to exclude (takes precedence over runId)
+ * @returns {Object} { owner, repo, pullNumber, reviewId, serverPort, runId, excludeRunIds }
+ */
+function buildDedupContext(prMetadata, { reviewId, serverPort, runId, excludeRunIds }) {
+  const [owner, repo] = prMetadata.repository?.split('/') || [];
+  return { owner, repo, pullNumber: prMetadata.pr_number, reviewId, serverPort, runId, excludeRunIds };
+}
+
+/**
+ * Build dedup instructions text for excluding previously identified issues.
+ *
+ * @param {Object|null} excludePrevious - { github: bool, feedback: bool } (or falsy if disabled)
+ * @param {Object} context - { owner, repo, pullNumber, reviewId, serverPort, runId, excludeRunIds }
+ * @param {string} [context.runId] - Single run ID to exclude (backward compat)
+ * @param {string[]} [context.excludeRunIds] - Array of run IDs to exclude (takes precedence over runId)
+ * @returns {string} Instruction text for the dedup-instructions prompt section, or empty string
+ */
+function buildDedupInstructions(excludePrevious, context) {
+  if (!excludePrevious || (!excludePrevious.github && !excludePrevious.feedback)) {
+    return '';
+  }
+  context = context || {};
+
+  const sections = [];
+
+  sections.push(`## Exclude Previously Identified Issues
+
+After consolidating suggestions, check your results against previously identified issues and remove any that are duplicates or substantially similar. If you have zero suggestions after consolidation, skip this step entirely.`);
+
+  if (excludePrevious.github && context.owner && context.repo && context.pullNumber) {
+    sections.push(`### GitHub PR Review Comments
+Fetch inline review comments:
+\`\`\`
+gh api repos/${context.owner}/${context.repo}/pulls/${context.pullNumber}/comments --paginate
+\`\`\`
+Each comment has \`path\` (file), \`line\`/\`original_line\` (line number), and \`body\` (content).
+A suggestion is a duplicate if it matches on **all three** of: (1) same file, (2) overlapping or adjacent line range (within 5 lines), and (3) substantially similar issue — i.e., the same category of issue (error handling, validation, naming, etc.) applied to the same code. If a previous comment partially overlaps your suggestion — e.g., it flags missing error handling while your suggestion flags missing error handling *and* input validation — keep only the novel portion that the previous comment does not address. If there is no novel portion, exclude it entirely.`);
+  }
+
+  if (excludePrevious.feedback && context.reviewId && context.serverPort) {
+    const excludeRunIds = context.excludeRunIds?.length ? context.excludeRunIds : (context.runId ? [context.runId] : []);
+    const excludeParam = excludeRunIds.length ? `&excludeRunId=${excludeRunIds.join(',')}` : '';
+    sections.push(`### Existing Pair-Review Feedback
+Fetch previous AI suggestions:
+\`\`\`
+curl -s "http://localhost:${context.serverPort}/api/reviews/${context.reviewId}/suggestions?allRuns=true&levels=final${excludeParam}"
+\`\`\`
+Fetch previous user comments:
+\`\`\`
+curl -s "http://localhost:${context.serverPort}/api/reviews/${context.reviewId}/comments?includeDismissed=true"
+\`\`\`
+A suggestion is a duplicate if it targets the same file and overlapping lines and raises the same category of issue as a previous suggestion or comment. For partial overlaps — where your suggestion covers a superset of what was previously flagged — narrow your suggestion to address only the novel aspect. If nothing novel remains, exclude it.`);
+  }
+
+  if (sections.length <= 1) {
+    // Only the header was added, no actual sources — return empty
+    return '';
+  }
+
+  sections.push('Report how many suggestions were excluded in your summary.');
+
+  return sections.join('\n\n');
 }
 
 class Analyzer {
@@ -136,6 +295,7 @@ class Analyzer {
    * @param {Object} prMetadata - PR metadata with base branch info
    * @param {Function} progressCallback - Callback for progress updates
    * @param {Object|string} instructions - Instructions object or legacy string for backward compatibility
+   * @param {string} [instructions.globalInstructions] - Global instructions from ~/.pair-review/global-instructions.md
    * @param {string} [instructions.repoInstructions] - Repository-level instructions from repo_settings
    * @param {string} [instructions.requestInstructions] - Request-level instructions from the analyze request
    * @param {Array<string>} changedFiles - Optional list of changed files for local mode validation
@@ -146,11 +306,13 @@ class Analyzer {
    * @param {boolean} [options.skipLevel3] - Skip Level 3 codebase context analysis (deprecated: use enabledLevels)
    * @param {Object} [options.enabledLevels] - Which levels to run, e.g. {1: true, 2: true, 3: false}
    * @param {string} [options.tier='balanced'] - Analysis tier (fast, balanced, thorough)
+   * @param {Object} [options.excludePrevious] - { github: bool, feedback: bool } for dedup
+   * @param {number} [options.serverPort] - Server port for dedup API calls
    * @returns {Promise<Object>} Analysis results
    */
   async analyzeAllLevels(prId, worktreePath, prMetadata, progressCallback = null, instructions = null, changedFiles = null, options = {}) {
     const runId = options.runId || uuidv4();
-    const { analysisId, skipRunCreation, skipLevel3, reviewerNum } = options;
+    const { analysisId, skipRunCreation, skipLevel3, reviewerNum, excludePrevious, serverPort } = options;
     const logPrefix = options.logPrefix || '';
     const executionTimeout = options.timeout || 600000; // Default 10 minutes
 
@@ -163,6 +325,7 @@ class Analyzer {
     }
 
     // Handle both new object format and legacy string format for backward compatibility
+    let globalInstructions = null;
     let repoInstructions = null;
     let requestInstructions = null;
     let mergedInstructions = null;
@@ -172,9 +335,10 @@ class Analyzer {
       mergedInstructions = instructions;
     } else if (instructions && typeof instructions === 'object') {
       // New format: object with separate instruction fields
+      globalInstructions = instructions.globalInstructions || null;
       repoInstructions = instructions.repoInstructions || null;
       requestInstructions = instructions.requestInstructions || null;
-      mergedInstructions = mergeInstructions(repoInstructions, requestInstructions);
+      mergedInstructions = mergeInstructions({ globalInstructions, repoInstructions, requestInstructions });
     }
 
     logger.section('Multi-Level AI Analysis Starting (Parallel Execution)');
@@ -207,7 +371,8 @@ class Analyzer {
           provider: this.provider,
           model: this.model,
           tier: options.tier ? resolveTier(options.tier) : 'balanced',
-          customInstructions: mergedInstructions,  // Keep for backward compat
+          customInstructions: requestInstructions,  // Only request-level; global/repo stored in their own columns
+          globalInstructions,
           repoInstructions,
           requestInstructions,
           headSha,
@@ -342,7 +507,10 @@ class Analyzer {
           level3: levelResults.level3.suggestions
         };
 
-        const orchestrationResult = await this.orchestrateWithAI(allSuggestions, prMetadata, mergedInstructions, worktreePath, { analysisId, tier, progressCallback, timeout: executionTimeout, logPrefix, reviewerNum });
+        // Build dedup context from prMetadata and options
+        const dedupContext = buildDedupContext(prMetadata, { reviewId: prId, serverPort, runId });
+
+        const orchestrationResult = await this.orchestrateWithAI(allSuggestions, prMetadata, mergedInstructions, worktreePath, { analysisId, tier, progressCallback, timeout: executionTimeout, logPrefix, reviewerNum, excludePrevious, dedupContext });
 
         // Report orchestration step as completed
         if (progressCallback) {
@@ -798,6 +966,7 @@ Or simply ignore any changes to files matching these patterns in your analysis.
    * @param {Object} prMetadata - PR metadata with base branch info
    * @param {Function} progressCallback - Callback for progress updates
    * @param {Object|string} instructions - Instructions object or legacy string for backward compatibility
+   * @param {string} [instructions.globalInstructions] - Global instructions from ~/.pair-review/global-instructions.md
    * @param {string} [instructions.repoInstructions] - Repository-level instructions from repo_settings
    * @param {string} [instructions.requestInstructions] - Request-level instructions from the analyze request
    * @param {Array<string>} changedFiles - Optional list of changed files for local mode validation
@@ -2454,10 +2623,12 @@ File-level suggestions should NOT have a line number. They apply to the entire f
    * @param {string} worktreePath - Path to the git worktree
    * @param {Object} options - Additional options
    * @param {string} options.analysisId - Analysis ID for process tracking (enables cancellation)
+   * @param {Object} [options.excludePrevious] - { github: bool, feedback: bool } for dedup
+   * @param {Object} [options.dedupContext] - { owner, repo, pullNumber, reviewId, serverPort }
    * @returns {Promise<Array>} Curated suggestions array
    */
   async orchestrateWithAI(allSuggestions, prMetadata, customInstructions = null, worktreePath = null, options = {}) {
-    const { analysisId, tier = 'balanced', progressCallback, providerOverride, modelOverride, timeout = 600000, logPrefix: lp = '', reviewerNum } = options;
+    const { analysisId, tier = 'balanced', progressCallback, providerOverride, modelOverride, timeout = 600000, logPrefix: lp = '', reviewerNum, excludePrevious, dedupContext } = options;
     // Build adapter-level log prefix: when reviewerNum is set (council mode),
     // use compact format like [R1 Orch] so concurrent reviewers are disambiguated
     const adapterLogPrefix = reviewerNum ? `[R${reviewerNum} Orch]` : '';
@@ -2479,7 +2650,7 @@ File-level suggestions should NOT have a line number. They apply to the entire f
       const aiProvider = createProvider(providerOverride || this.provider, modelOverride || this.model);
 
       // Build the consolidation prompt
-      const prompt = this.buildOrchestrationPrompt(allSuggestions, prMetadata, customInstructions, worktreePath, tier, lp);
+      const prompt = this.buildOrchestrationPrompt(allSuggestions, prMetadata, customInstructions, worktreePath, tier, lp, { excludePrevious, dedupContext });
 
       // Execute AI for cross-level consolidation
       logger.info(`${lp}[Consolidation] Running AI consolidation to curate and merge suggestions...`);
@@ -2590,9 +2761,12 @@ File-level suggestions should NOT have a line number. They apply to the entire f
    * @param {string} worktreePath - Path to the git worktree
    * @param {string} tier - Capability tier: 'fast', 'balanced', or 'thorough' (default: 'balanced')
    * @param {string} logPrefix - Optional log prefix for reviewer identification in council mode
+   * @param {Object} [dedupOptions] - Dedup options
+   * @param {Object} [dedupOptions.excludePrevious] - { github: bool, feedback: bool }
+   * @param {Object} [dedupOptions.dedupContext] - { owner, repo, pullNumber, reviewId, serverPort }
    * @returns {string} Orchestration prompt
    */
-  buildOrchestrationPrompt(allSuggestions, prMetadata, customInstructions = null, worktreePath = null, tier = 'balanced', logPrefix = '') {
+  buildOrchestrationPrompt(allSuggestions, prMetadata, customInstructions = null, worktreePath = null, tier = 'balanced', logPrefix = '', dedupOptions = {}) {
     logger.debug(`${logPrefix}[Consolidation] Building consolidation prompt with tier: ${tier}`);
     const promptBuilder = getPromptBuilder('orchestration', tier, this.provider);
 
@@ -2606,6 +2780,7 @@ File-level suggestions should NOT have a line number. They apply to the entire f
       reviewIntro: `You are orchestrating AI-powered code review suggestions for ${reviewDescription}.`,
       customInstructions: customInstructions ? this.buildCustomInstructionsSection(customInstructions) : '',
       lineNumberGuidance: this.buildOrchestrationLineNumberGuidance(worktreePath),
+      dedupInstructions: buildDedupInstructions(dedupOptions.excludePrevious, dedupOptions.dedupContext || {}),
       level1Count: allSuggestions.level1?.length || 0,
       level2Count: allSuggestions.level2?.length || 0,
       level3Count: allSuggestions.level3?.length || 0,
@@ -2627,7 +2802,7 @@ File-level suggestions should NOT have a line number. They apply to the entire f
    * @param {string} reviewContext.worktreePath - Path to the git worktree
    * @param {Object} reviewContext.prMetadata - PR/review metadata
    * @param {Array<string>} [reviewContext.changedFiles] - Changed files list
-   * @param {Object} reviewContext.instructions - Instructions { repoInstructions, requestInstructions }
+   * @param {Object} reviewContext.instructions - Instructions { globalInstructions, repoInstructions, requestInstructions }
    * @param {Object} councilConfig - Reviewer-centric council configuration
    * @param {Array<Object>} councilConfig.voices - Reviewer configurations (provider, model, tier, customInstructions, timeout)
    * @param {Object} councilConfig.levels - Which levels to enable, e.g. {1: true, 2: true, 3: false}
@@ -2636,11 +2811,13 @@ File-level suggestions should NOT have a line number. They apply to the entire f
    * @param {string} options.analysisId - Analysis ID for process tracking
    * @param {string} [options.runId] - Pre-generated parent run ID
    * @param {Function} [options.progressCallback] - Progress callback
+   * @param {Object} [options.excludePrevious] - { github: bool, feedback: bool } for dedup
+   * @param {number} [options.serverPort] - Server port for dedup API calls
    * @returns {Promise<Object>} Analysis results { runId, suggestions, summary }
    */
   async runReviewerCentricCouncil(reviewContext, councilConfig, options = {}) {
     const { reviewId, worktreePath, prMetadata, changedFiles, instructions } = reviewContext;
-    const { analysisId, progressCallback } = options;
+    const { analysisId, progressCallback, excludePrevious, serverPort } = options;
     const parentRunId = options.runId || uuidv4();
 
     logger.section('Review Council Analysis Starting (Reviewer-Centric)');
@@ -2677,7 +2854,7 @@ File-level suggestions should NOT have a line number. They apply to the entire f
     // Merge instructions
     let mergedInstructions = null;
     if (instructions && typeof instructions === 'object') {
-      mergedInstructions = mergeInstructions(instructions.repoInstructions, instructions.requestInstructions);
+      mergedInstructions = mergeInstructions({ globalInstructions: instructions.globalInstructions, repoInstructions: instructions.repoInstructions, requestInstructions: instructions.requestInstructions });
     }
 
     // Resolve enabledLevels from council config
@@ -2715,7 +2892,8 @@ File-level suggestions should NOT have a line number. They apply to the entire f
           provider: 'council',
           model: 'voice-centric',
           tier: null,
-          customInstructions: mergedInstructions,
+          customInstructions: instructions?.requestInstructions || null,  // Only request-level; global/repo stored in their own columns
+          globalInstructions: instructions?.globalInstructions || null,
           repoInstructions: instructions?.repoInstructions || null,
           requestInstructions: instructions?.requestInstructions || null,
           headSha,
@@ -2745,7 +2923,7 @@ File-level suggestions should NOT have a line number. They apply to the entire f
     // Single voice: skip child run entirely, run analysis directly on parent run
     if (voices.length === 1) {
       const voice = voices[0];
-      const { voiceAnalyzer, voiceKey, reviewerLabel, voiceRequestInstructions, voiceProgressCallback, voiceTier, voiceTimeout } =
+      const { voiceAnalyzer, voiceProvider, isExecutable, voiceKey, reviewerLabel, voiceRequestInstructions, voiceProgressCallback, voiceTier, voiceTimeout } =
         buildVoiceContext(voice, 0, instructions, progressCallback, this.db);
       logger.info(`[ReviewerCouncil] Single reviewer (${reviewerLabel}) — running directly on parent run, no child run`);
 
@@ -2755,10 +2933,39 @@ File-level suggestions should NOT have a line number. They apply to the entire f
           voiceCentric: true,
           level: 'voice-init',
           status: 'running',
-          voices: { [voiceKey]: { status: 'pending', provider: voice.provider, model: voice.model, tier: voiceTier } }
+          voices: { [voiceKey]: { status: 'pending', provider: voice.provider, model: voice.model, tier: voiceTier, isExecutable } }
         });
       }
 
+      if (isExecutable) {
+        const result = await runExecutableVoice(voiceProvider, reviewId, worktreePath, prMetadata, {
+          analysisId, timeout: voiceTimeout,
+          requestInstructions: voiceRequestInstructions,
+          progressCallback: voiceProgressCallback,
+          logPrefix: `[${reviewerLabel}] `
+        });
+
+        const finalSuggestions = this.validateAndFinalizeSuggestions(result.suggestions, fileLineCountMap, validFiles);
+        await this.storeSuggestions(reviewId, parentRunId, finalSuggestions, null, validFiles);
+
+        try {
+          await analysisRunRepo.update(parentRunId, {
+            status: 'completed',
+            summary: result.summary,
+            totalSuggestions: finalSuggestions.length,
+            filesAnalyzed: validFiles.length
+          });
+        } catch (err) {
+          logger.warn(`[ReviewerCouncil] Failed to update parent run: ${err.message}`);
+        }
+
+        return {
+          runId: parentRunId,
+          suggestions: finalSuggestions,
+          summary: result.summary || `Review council complete: ${finalSuggestions.length} suggestions`
+        };
+      }
+
       // analyzeAllLevels handles validation, storage, and run status updates internally
       // (including error/cancellation status), so no error handling needed here
       const result = await voiceAnalyzer.analyzeAllLevels(
@@ -2766,7 +2973,7 @@ File-level suggestions should NOT have a line number. They apply to the entire f
         worktreePath,
         prMetadata,
         voiceProgressCallback,
-        { repoInstructions: instructions?.repoInstructions, requestInstructions: voiceRequestInstructions },
+        { globalInstructions: instructions?.globalInstructions, repoInstructions: instructions?.repoInstructions, requestInstructions: voiceRequestInstructions },
         changedFiles,
         {
           analysisId,
@@ -2776,7 +2983,9 @@ File-level suggestions should NOT have a line number. They apply to the entire f
           tier: voiceTier,
           timeout: voiceTimeout,
           logPrefix: `[${reviewerLabel}] `,
-          reviewerNum: 1
+          reviewerNum: 1,
+          excludePrevious,
+          serverPort
         }
       );
 
@@ -2796,20 +3005,23 @@ File-level suggestions should NOT have a line number. They apply to the entire f
         level: 'voice-init',
         status: 'running',
         voices: Object.fromEntries(voices.map((v, idx) => {
-          const voiceKey = `${v.provider}-${v.model}${idx > 0 ? `-${idx}` : ''}`;
-          return [voiceKey, {
+          const vKey = `${v.provider}-${v.model}${idx > 0 ? `-${idx}` : ''}`;
+          const VoiceProviderClass = getProviderClass(v.provider);
+          return [vKey, {
             status: 'pending',
             provider: v.provider,
             model: v.model,
-            tier: v.tier || 'balanced'
+            tier: v.tier || 'balanced',
+            isExecutable: VoiceProviderClass?.isExecutable || false
           }];
         }))
       });
     }
 
-    // For each voice, create a child run and launch analyzeAllLevels
+    // For each voice, create a child run and launch analysis
+    const commentRepo = new CommentRepository(this.db);
     const voicePromises = voices.map(async (voice, idx) => {
-      const { voiceAnalyzer, voiceKey, reviewerLabel, voiceRequestInstructions, voiceProgressCallback, voiceTier, voiceTimeout } =
+      const { voiceAnalyzer, voiceProvider, isExecutable, voiceKey, reviewerLabel, voiceRequestInstructions, voiceProgressCallback, voiceTier, voiceTimeout } =
         buildVoiceContext(voice, idx, instructions, progressCallback, this.db);
       const childRunId = uuidv4();
 
@@ -2821,7 +3033,8 @@ File-level suggestions should NOT have a line number. They apply to the entire f
           provider: voice.provider,
           model: voice.model,
           tier: voiceTier,
-          customInstructions: mergedInstructions,
+          customInstructions: instructions?.requestInstructions || null,  // Only request-level; global/repo stored in their own columns
+          globalInstructions: instructions?.globalInstructions || null,
           repoInstructions: instructions?.repoInstructions || null,
           requestInstructions: instructions?.requestInstructions || null,
           headSha,
@@ -2836,12 +3049,43 @@ File-level suggestions should NOT have a line number. They apply to the entire f
       }
 
       try {
+        if (isExecutable) {
+          const result = await runExecutableVoice(voiceProvider, reviewId, worktreePath, prMetadata, {
+            analysisId, timeout: voiceTimeout,
+            requestInstructions: voiceRequestInstructions,
+            progressCallback: voiceProgressCallback,
+            logPrefix: `[${reviewerLabel}] `
+          });
+
+          // Validate suggestions before storage (matches single-voice path)
+          const validatedSuggestions = this.validateAndFinalizeSuggestions(result.suggestions, fileLineCountMap, validFiles);
+
+          // Update child run
+          try {
+            await analysisRunRepo.update(childRunId, {
+              status: 'completed',
+              summary: result.summary,
+              totalSuggestions: validatedSuggestions.length
+            });
+          } catch (err) {
+            logger.warn(`[ReviewerCouncil] Failed to update child run ${childRunId}: ${err.message}`);
+          }
+
+          // Store validated voice suggestions
+          await commentRepo.bulkInsertAISuggestions(reviewId, childRunId, validatedSuggestions, null);
+
+          const validatedResult = { ...result, suggestions: validatedSuggestions };
+          return { voiceKey, reviewerLabel, childRunId, result: validatedResult, provider: voice.provider, model: voice.model, isExecutable: true, customInstructions: voice.customInstructions || null };
+        }
+
+        // Note: excludePrevious/serverPort omitted intentionally — dedup runs once
+        // during cross-voice consolidation, not per-voice.
         const result = await voiceAnalyzer.analyzeAllLevels(
           reviewId,
           worktreePath,
           prMetadata,
           voiceProgressCallback,
-          { repoInstructions: instructions?.repoInstructions, requestInstructions: voiceRequestInstructions },
+          { globalInstructions: instructions?.globalInstructions, repoInstructions: instructions?.repoInstructions, requestInstructions: voiceRequestInstructions },
           changedFiles,
           {
             analysisId,
@@ -2867,7 +3111,7 @@ File-level suggestions should NOT have a line number. They apply to the entire f
           logger.warn(`[ReviewerCouncil] Failed to update child run ${childRunId}: ${err.message}`);
         }
 
-        return { voiceKey, reviewerLabel, childRunId, result, provider: voice.provider, model: voice.model };
+        return { voiceKey, reviewerLabel, childRunId, result, provider: voice.provider, model: voice.model, isExecutable: false, customInstructions: voice.customInstructions || null };
       } catch (error) {
         // Update child run to failed/cancelled
         try {
@@ -2899,15 +3143,15 @@ File-level suggestions should NOT have a line number. They apply to the entire f
     // Collect successful results
     const successfulVoices = [];
     const allVoiceSuggestions = [];
-    const voiceSummaries = [];
+    const allVoiceFileLevelSuggestions = [];
 
     for (let i = 0; i < voiceResults.length; i++) {
       const settled = voiceResults[i];
       if (settled.status === 'fulfilled' && settled.value.result?.suggestions) {
         successfulVoices.push(settled.value);
         allVoiceSuggestions.push(...settled.value.result.suggestions);
-        if (settled.value.result.summary) {
-          voiceSummaries.push(settled.value.result.summary);
+        if (settled.value.result.fileLevelSuggestions) {
+          allVoiceFileLevelSuggestions.push(...settled.value.result.fileLevelSuggestions);
         }
         logger.success(`[ReviewerCouncil] ${settled.value.reviewerLabel}: ${settled.value.result.suggestions.length} suggestions`);
       } else {
@@ -2927,7 +3171,10 @@ File-level suggestions should NOT have a line number. They apply to the entire f
     }
 
     // Single voice: use directly, no consolidation
-    if (successfulVoices.length === 1) {
+    // But if dedup (exclude-previous) is enabled, we must go through consolidation
+    // so that previous suggestions are filtered out.
+    const hasExcludePrevious = excludePrevious && (excludePrevious.github || excludePrevious.feedback);
+    if (successfulVoices.length === 1 && !hasExcludePrevious) {
       logger.info('[ReviewerCouncil] Single reviewer result — skipping consolidation');
       const singleResult = successfulVoices[0].result;
 
@@ -2957,34 +3204,6 @@ File-level suggestions should NOT have a line number. They apply to the entire f
     // Multiple voices: cross-voice consolidation
     const totalSuggestionCount = allVoiceSuggestions.length;
 
-    // If below consolidation threshold, skip
-    if (totalSuggestionCount < COUNCIL_CONSOLIDATION_THRESHOLD) {
-      logger.info(`[ReviewerCouncil] ${totalSuggestionCount} total suggestions below threshold (${COUNCIL_CONSOLIDATION_THRESHOLD}) — skipping consolidation`);
-      const summary = voiceSummaries.length > 1 ? voiceSummaries.join('\n\n') : voiceSummaries[0];
-
-      const finalSuggestions = this.validateAndFinalizeSuggestions(
-        allVoiceSuggestions, fileLineCountMap, validFiles
-      );
-      await this.storeSuggestions(reviewId, parentRunId, finalSuggestions, null, validFiles);
-
-      try {
-        await analysisRunRepo.update(parentRunId, {
-          status: 'completed',
-          summary: summary || `Review council complete: ${finalSuggestions.length} suggestions`,
-          totalSuggestions: finalSuggestions.length,
-          filesAnalyzed: validFiles.length
-        });
-      } catch (err) {
-        logger.warn(`[ReviewerCouncil] Failed to update parent run: ${err.message}`);
-      }
-
-      return {
-        runId: parentRunId,
-        suggestions: finalSuggestions,
-        summary: summary || `Reviewer-centric council complete: ${finalSuggestions.length} suggestions`
-      };
-    }
-
     // Run cross-reviewer consolidation
     logger.info(`[ReviewerCouncil] Starting cross-reviewer consolidation of ${successfulVoices.length} reviewers (${totalSuggestionCount} total suggestions)`);
 
@@ -3016,15 +3235,22 @@ File-level suggestions should NOT have a line number. They apply to the entire f
         voiceKey: v.voiceKey,
         provider: v.provider,
         model: v.model,
+        isExecutable: v.isExecutable || false,
+        customInstructions: v.customInstructions || null,
         suggestionCount: v.result.suggestions.length + (v.result.fileLevelSuggestions?.length || 0),
         suggestions: v.result.suggestions,
         fileLevelSuggestions: v.result.fileLevelSuggestions || [],
         summary: v.result.summary
       }));
 
+      // Build dedup context for cross-voice consolidation
+      // Exclude both parent and child run IDs so the dedup fetch doesn't include the current run's results
+      const childRunIds = successfulVoices.map(v => v.childRunId).filter(Boolean);
+      const dedupContext = buildDedupContext(prMetadata, { reviewId, serverPort, runId: parentRunId, excludeRunIds: [parentRunId, ...childRunIds] });
+
       const consolidated = await this._crossVoiceConsolidate(
         voiceReviews, prMetadata, consolInstructions, worktreePath,
-        { provider: consolProvider, model: consolModel, tier: consolTier, timeout: consolConfig.timeout, analysisId, progressCallback }
+        { provider: consolProvider, model: consolModel, tier: consolTier, timeout: consolConfig.timeout, analysisId, progressCallback, excludePrevious, dedupContext }
       );
 
       const finalSuggestions = this.validateAndFinalizeSuggestions(
@@ -3058,7 +3284,7 @@ File-level suggestions should NOT have a line number. They apply to the entire f
 
       // Fallback: use all voice suggestions combined
       const fallbackSuggestions = this.validateAndFinalizeSuggestions(
-        allVoiceSuggestions, fileLineCountMap, validFiles
+        [...allVoiceSuggestions, ...allVoiceFileLevelSuggestions], fileLineCountMap, validFiles
       );
       await this.storeSuggestions(reviewId, parentRunId, fallbackSuggestions, null, validFiles);
 
@@ -3092,7 +3318,7 @@ File-level suggestions should NOT have a line number. They apply to the entire f
    * @param {string} reviewContext.worktreePath - Path to the git worktree
    * @param {Object} reviewContext.prMetadata - PR/review metadata
    * @param {Array<string>} [reviewContext.changedFiles] - Changed files list
-   * @param {Object} reviewContext.instructions - Instructions object { repoInstructions, requestInstructions }
+   * @param {Object} reviewContext.instructions - Instructions object { globalInstructions, repoInstructions, requestInstructions }
    * @param {Object} councilConfig - Council configuration
    * @param {Object} councilConfig.levels - Level configurations keyed by '1', '2', '3'
    * @param {Object} [councilConfig.consolidation] - Consolidation provider/model/tier
@@ -3100,11 +3326,13 @@ File-level suggestions should NOT have a line number. They apply to the entire f
    * @param {string} options.analysisId - Analysis ID for process tracking
    * @param {string} [options.runId] - Pre-generated run ID
    * @param {Function} [options.progressCallback] - Progress callback
+   * @param {Object} [options.excludePrevious] - { github: bool, feedback: bool } for dedup
+   * @param {number} [options.serverPort] - Server port for dedup API calls
    * @returns {Promise<Object>} Analysis results
    */
   async runCouncilAnalysis(reviewContext, councilConfig, options = {}) {
     const { reviewId, worktreePath, prMetadata, changedFiles, instructions } = reviewContext;
-    const { analysisId, progressCallback } = options;
+    const { analysisId, progressCallback, excludePrevious, serverPort } = options;
     const runId = options.runId || uuidv4();
 
     logger.section('Review Council Analysis Starting');
@@ -3114,7 +3342,7 @@ File-level suggestions should NOT have a line number. They apply to the entire f
     const { mergeInstructions } = require('../utils/instructions');
     let mergedInstructions = null;
     if (instructions && typeof instructions === 'object') {
-      mergedInstructions = mergeInstructions(instructions.repoInstructions, instructions.requestInstructions);
+      mergedInstructions = mergeInstructions({ globalInstructions: instructions.globalInstructions, repoInstructions: instructions.repoInstructions, requestInstructions: instructions.requestInstructions });
     }
 
     // Load generated file patterns
@@ -3159,7 +3387,8 @@ File-level suggestions should NOT have a line number. They apply to the entire f
           model: voice.model,
           tier,
           timeout: voice.timeout || 600000,
-          customInstructions: voiceInstructions
+          customInstructions: voiceInstructions,
+          voiceCustomInstructions: voice.customInstructions || null
         });
       }
     }
@@ -3249,7 +3478,8 @@ File-level suggestions should NOT have a line number. They apply to the entire f
       }
     }
 
-    if (voiceSuccessCount === 1 && successfulVoiceLevels.size === 1) {
+    const hasExcludePrevious = excludePrevious && (excludePrevious.github || excludePrevious.feedback);
+    if (voiceSuccessCount === 1 && successfulVoiceLevels.size === 1 && !hasExcludePrevious) {
       // Single voice, single level — skip all consolidation
       logger.info('[Council] Single reviewer result — skipping consolidation');
       const singleLevel = [...successfulVoiceLevels][0];
@@ -3266,30 +3496,7 @@ File-level suggestions should NOT have a line number. They apply to the entire f
       };
     }
 
-    // Check if total suggestion count is below consolidation threshold
-    const totalSuggestionCount = Object.values(levelSuggestions).reduce((sum, arr) => sum + arr.length, 0);
-    if (totalSuggestionCount < COUNCIL_CONSOLIDATION_THRESHOLD) {
-      logger.info(`[Council] ${totalSuggestionCount} total suggestions below threshold (${COUNCIL_CONSOLIDATION_THRESHOLD}) — skipping consolidation`);
-      const allSuggestions = Object.values(levelSuggestions).flat();
-      const finalSuggestions = this.validateAndFinalizeSuggestions(
-        allSuggestions, fileLineCountMap, validFiles
-      );
-      await this.storeSuggestions(reviewId, runId, finalSuggestions, null, validFiles);
-
-      // Prefer voice summaries over generic placeholders. When multiple voices
-      // produced summaries, join them so no insight is lost.
-      const thresholdSummary = voiceSummaries.length > 1
-        ? voiceSummaries.join('\n\n')
-        : bestVoiceSummary;
-
-      return {
-        runId,
-        suggestions: finalSuggestions,
-        summary: thresholdSummary || `Council analysis complete: ${finalSuggestions.length} suggestions (consolidation skipped — below threshold)`
-      };
-    }
-
-    // Store raw per-reviewer suggestions (only when consolidation will occur)
+    // Store raw per-reviewer suggestions before consolidation
     logger.info(`[Council] Storing ${rawSuggestions.length} raw reviewer suggestions`);
     await this._storeCouncilSuggestions(reviewId, runId, rawSuggestions, validFiles);
 
@@ -3336,8 +3543,16 @@ File-level suggestions should NOT have a line number. They apply to the entire f
         // Multiple reviewers — run intra-level consolidation
         logger.info(`[Council] Pass 1: Consolidating ${successfulVoicesForLevel.length} reviewers for Level ${level}`);
         try {
+          const voiceGroups = successfulVoicesForLevel.map(({ t: task, idx }) => ({
+            voiceId: task.voiceId,
+            provider: task.provider,
+            model: task.model,
+            customInstructions: task.voiceCustomInstructions,
+            summary: voiceResults[idx].value.summary,
+            suggestions: voiceResults[idx].value.suggestions
+          }));
           const consolidated = await this._intraLevelConsolidate(
-            level, suggestions, prMetadata, orchInstructions, worktreePath,
+            level, voiceGroups, prMetadata, orchInstructions, worktreePath,
             { provider: orchProvider, model: orchModel, tier: orchTier, timeout: orchConfig.timeout, analysisId, progressCallback, reviewerCount: successfulVoicesForLevel.length }
           );
           consolidatedPerLevel[level] = consolidated;
@@ -3365,9 +3580,12 @@ File-level suggestions should NOT have a line number. They apply to the entire f
         level3: consolidatedPerLevel[3] || []
       };
 
+      // Build dedup context for cross-level orchestration
+      const dedupContext = buildDedupContext(prMetadata, { reviewId, serverPort, runId });
+
       const orchestrationResult = await this.orchestrateWithAI(
         allSuggestions, prMetadata, orchInstructions, worktreePath,
-        { analysisId, tier: orchTier, progressCallback, providerOverride: orchProvider, modelOverride: orchModel, timeout: orchConfig.timeout || 600000 }
+        { analysisId, tier: orchTier, progressCallback, providerOverride: orchProvider, modelOverride: orchModel, timeout: orchConfig.timeout || 600000, excludePrevious, dedupContext }
       );
 
       // Report cross-level orchestration step as completed
@@ -3499,7 +3717,7 @@ File-level suggestions should NOT have a line number. They apply to the entire f
   /**
    * Run intra-level consolidation for a level with multiple voices
    * @param {number} level - Analysis level
-   * @param {Array} suggestions - Combined suggestions from all voices at this level
+   * @param {Array<Object>} voiceGroups - Per-reviewer groups: { voiceId, provider, model, customInstructions, suggestions }
    * @param {Object} prMetadata - PR metadata
    * @param {string} customInstructions - Custom instructions
    * @param {string} worktreePath - Worktree path
@@ -3507,7 +3725,7 @@ File-level suggestions should NOT have a line number. They apply to the entire f
    * @returns {Promise<Array>} Consolidated suggestions
    * @private
    */
-  async _intraLevelConsolidate(level, suggestions, prMetadata, customInstructions, worktreePath, orchConfig) {
+  async _intraLevelConsolidate(level, voiceGroups, prMetadata, customInstructions, worktreePath, orchConfig) {
     const { provider, model, tier, timeout, analysisId, progressCallback, reviewerCount } = orchConfig;
 
     const aiProvider = createProvider(provider, model);
@@ -3517,13 +3735,26 @@ File-level suggestions should NOT have a line number. They apply to the entire f
       ? `local changes (review #${prMetadata.pr_number || 'local'})`
       : `pull request #${prMetadata.pr_number}`;
 
+    const reviewerSuggestions = voiceGroups.map(g => {
+      let desc = `### Reviewer: ${g.voiceId} (${g.provider}/${g.model})\n`;
+      if (g.customInstructions) {
+        desc += `\n**Review Focus:**\n${g.customInstructions}\n`;
+      }
+      if (g.summary) desc += `\n**Summary:** ${g.summary}\n`;
+      desc += `\n**Suggestions:**\n${JSON.stringify(g.suggestions, null, 2)}`;
+      return desc;
+    }).join('\n\n---\n\n');
+
+    const suggestionCount = voiceGroups.reduce((sum, g) => sum + g.suggestions.length, 0);
+
     const promptBuilder = getPromptBuilder('consolidation', tier || 'balanced', provider);
     const prompt = promptBuilder.build({
       reviewIntro: `You are consolidating Level ${level} code review suggestions from multiple independent AI reviewers for ${reviewDescription}.`,
       customInstructions: customInstructions ? this.buildCustomInstructionsSection(customInstructions) : '',
+      dedupInstructions: '',
       lineNumberGuidance: this.buildOrchestrationLineNumberGuidance(worktreePath),
-      reviewerSuggestions: JSON.stringify(suggestions, null, 2),
-      suggestionCount: suggestions.length,
+      reviewerSuggestions,
+      suggestionCount,
       reviewerCount: reviewerCount || 'multiple'
     });
 
@@ -3635,15 +3866,17 @@ File-level suggestions should NOT have a line number. They apply to the entire f
    * @private
    */
   _defaultConsolidation(councilConfig) {
-    // Use the first voice as consolidation model
     const voices = councilConfig.voices || [];
-    if (voices.length > 0) {
+    // Prefer first non-executable voice for consolidation
+    const nativeVoice = voices.find(v => !getProviderClass(v.provider)?.isExecutable);
+    if (nativeVoice) {
       return {
-        provider: voices[0].provider,
-        model: voices[0].model,
-        tier: voices[0].tier || 'balanced'
+        provider: nativeVoice.provider,
+        model: nativeVoice.model,
+        tier: nativeVoice.tier || 'balanced'
       };
     }
+    // All-executable council: fall back to claude/sonnet-4.6
     return { provider: 'claude', model: 'sonnet-4.6', tier: 'balanced' };
   }
 
@@ -3656,24 +3889,29 @@ File-level suggestions should NOT have a line number. They apply to the entire f
    * @param {Object} prMetadata - PR metadata
    * @param {string} customInstructions - Merged custom instructions
    * @param {string} worktreePath - Worktree path
-   * @param {Object} config - { provider, model, tier, timeout, analysisId, progressCallback }
+   * @param {Object} config - { provider, model, tier, timeout, analysisId, progressCallback, excludePrevious, dedupContext }
    * @returns {Promise<Object>} { suggestions, summary }
    * @private
    */
   async _crossVoiceConsolidate(voiceReviews, prMetadata, customInstructions, worktreePath, config) {
-    const { provider, model, tier, timeout, analysisId, progressCallback } = config;
+    const { provider, model, tier, timeout, analysisId, progressCallback, excludePrevious, dedupContext } = config;
 
     const aiProvider = createProvider(provider, model);
 
     const voiceDescriptions = voiceReviews.map(v => {
-      let desc = `### Reviewer: ${v.voiceKey} (${v.provider}/${v.model}) — ${v.suggestionCount} suggestions\n`;
-      if (v.summary) desc += `Summary: ${v.summary}\n`;
-      desc += `Suggestions:\n${JSON.stringify(v.suggestions, null, 2)}`;
+      let desc = `### Reviewer: ${v.voiceKey}`;
+      if (v.isExecutable) desc += ' [external tool]';
+      desc += ` (${v.provider}/${v.model}) — ${v.suggestionCount} suggestions\n`;
+      if (v.customInstructions) {
+        desc += `\n**Review Focus:**\n${v.customInstructions}\n`;
+      }
+      if (v.summary) desc += `\n**Summary:** ${v.summary}\n`;
+      desc += `\n**Suggestions:**\n${JSON.stringify(v.suggestions, null, 2)}`;
       if (v.fileLevelSuggestions?.length > 0) {
-        desc += `\nFile-Level Suggestions:\n${JSON.stringify(v.fileLevelSuggestions, null, 2)}`;
+        desc += `\n**File-Level Suggestions:**\n${JSON.stringify(v.fileLevelSuggestions, null, 2)}`;
       }
       return desc;
-    }).join('\n\n');
+    }).join('\n\n---\n\n');
 
     const isLocal = prMetadata.reviewType === 'local';
     const reviewDescription = isLocal
@@ -3685,6 +3923,7 @@ File-level suggestions should NOT have a line number. They apply to the entire f
       reviewIntro: `You are consolidating code review results from ${voiceReviews.length} independent AI reviewers for ${reviewDescription}. Each reviewer independently analyzed the same code changes and produced a complete review.`,
       customInstructions: customInstructions ? this.buildCustomInstructionsSection(customInstructions) : '',
       lineNumberGuidance: this.buildOrchestrationLineNumberGuidance(worktreePath),
+      dedupInstructions: buildDedupInstructions(excludePrevious, dedupContext || {}),
       reviewerSuggestions: voiceDescriptions,
       suggestionCount: voiceReviews.reduce((sum, v) => sum + v.suggestionCount, 0),
       reviewerCount: voiceReviews.length
@@ -3702,7 +3941,26 @@ File-level suggestions should NOT have a line number. They apply to the entire f
     });
 
     const suggestions = this.parseResponse(response, 'consolidation');
-    const summary = response.summary || `Consolidated ${voiceReviews.length} reviewer outputs into ${suggestions.length} suggestions`;
+
+    // Extract summary from response, falling back to raw JSON extraction (same pattern as orchestrateWithAI)
+    let summary;
+    if (response.summary) {
+      summary = response.summary;
+    } else if (response.raw) {
+      const extracted = extractJSON(response.raw, 'consolidation');
+      if (extracted.success && extracted.data.summary) {
+        summary = extracted.data.summary;
+      }
+    }
+    if (!summary) {
+      // Fall back to individual reviewer summaries rather than generic consolidation text
+      const reviewerSummaries = voiceReviews
+        .filter(v => v.summary)
+        .map(v => v.summary);
+      summary = reviewerSummaries.length > 0
+        ? reviewerSummaries.join('\n\n')
+        : `Review complete: ${suggestions.length} suggestions`;
+    }
 
     return { suggestions, summary };
   }
@@ -3728,4 +3986,6 @@ File-level suggestions should NOT have a line number. They apply to the entire f
   }
 }
 
-module.exports = Analyzer;
+module.exports = Analyzer;
+module.exports.buildDedupContext = buildDedupContext;
+module.exports.buildDedupInstructions = buildDedupInstructions;