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

package/src/main.js

@@ -1,7 +1,7 @@
 // Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
 const fs = require('fs');
-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 { loadConfig, getConfigDir, getGitHubToken, resolveHostBinding, showWelcomeMessage, resolveDbName, resolveRepoOptions, resolvePoolConfig, getRepoResetScript, resolveLoadSkills, buildCouncilProviderOverrides } = require('./config');
+const { initializeDatabase, run, queryOne, query, migrateExistingWorktrees, WorktreeRepository, ReviewRepository, RepoSettingsRepository, GitHubReviewRepository, WorktreePoolRepository, CouncilRepository } = require('./database');
 const { PRArgumentParser } = require('./github/parser');
 const { GitHubClient } = require('./github/client');
 const { GitWorktreeManager } = require('./git/worktree');
@@ -11,6 +11,9 @@ const { startServer } = require('./server');
 const Analyzer = require('./ai/analyzer');
 const { applyConfigOverrides } = require('./ai');
 const { handleLocalReview, findMainGitRoot } = require('./local-review');
+const { resolveCouncilHandle, getCouncilLastUsedRepos, shortId } = require('./councils/resolve-council');
+const { runHeadlessCouncilAnalysis } = require('./councils/headless-council');
+const { normalizeCouncilConfig, validateCouncilConfig } = require('./routes/councils');
 const { storePRData, registerRepositoryLocation, findRepositoryPath } = require('./setup/pr-setup');
 const { fireReviewStartedHook } = require('./hooks/payloads');
 const { normalizeRepository, resolveRenamedFile, resolveRenamedFileOld } = require('./utils/paths');
@@ -164,6 +167,9 @@ OPTIONS:
                                   opus-4.6-high, opus-4.6-1m, sonnet-4.6
                             (opus is Opus 4.7 XHigh, the default)
                             or use provider-specific models with Gemini/Codex
+    --council <handle>      Run analysis with a saved council (multi-voice). Handle is a
+                            council name, name-slug, or id (prefix). See --list-councils.
+    --list-councils         List saved councils (handles to use with --council) and exit
     --use-checkout          Use current directory instead of creating worktree
                             (automatic in GitHub Actions)
     --yolo                  Allow AI providers full system access (skip read-only
@@ -179,6 +185,8 @@ EXAMPLES:
     pair-review --local                # Review uncommitted local changes
     pair-review 123 --ai               # Auto-run AI analysis
     pair-review --ai-review            # CI mode: auto-detect PR, submit review
+    pair-review 123 --ai-draft --council security-review  # Headless council draft
+    pair-review --list-councils        # List saved councils and their handles
     pair-review --register                     # Register URL scheme handler
     pair-review --register --command "node bin/pair-review.js"  # Custom command
 
@@ -207,6 +215,74 @@ MORE INFO:
 `);
 }
 
+/**
+ * Print the list of saved councils (handles, names, types, and "last used"
+ * metadata) as an aligned table, then exit guidance. Used by --list-councils.
+ *
+ * @param {Object} db - Database instance
+ */
+async function printCouncilList(db) {
+  const councils = await new CouncilRepository(db).list();
+
+  if (!councils || councils.length === 0) {
+    console.log('No councils found. Create one in the web UI under Analysis settings.');
+    return;
+  }
+
+  const repoMap = await getCouncilLastUsedRepos(db);
+
+  const rows = councils.map(c => {
+    const entry = repoMap.get(c.id);
+    const lastTs = entry?.last_started || c.last_used_at;
+    const lastUsed = lastTs ? String(lastTs).slice(0, 10) : 'never';
+    let lastUsedWith = '—';
+    if (entry) {
+      lastUsedWith = `${entry.repository}${entry.pr_number ? `#${entry.pr_number}` : ''}`;
+    }
+    return {
+      handle: shortId(c.id),
+      name: c.name || '',
+      type: c.type || '',
+      lastUsed,
+      lastUsedWith
+    };
+  });
+
+  const headers = {
+    handle: 'HANDLE',
+    name: 'NAME',
+    type: 'TYPE',
+    lastUsed: 'LAST USED',
+    lastUsedWith: 'LAST USED WITH'
+  };
+
+  const widths = {};
+  for (const key of Object.keys(headers)) {
+    widths[key] = Math.max(
+      headers[key].length,
+      ...rows.map(r => String(r[key]).length)
+    );
+  }
+
+  const formatRow = r =>
+    [
+      String(r.handle).padEnd(widths.handle),
+      String(r.name).padEnd(widths.name),
+      String(r.type).padEnd(widths.type),
+      String(r.lastUsed).padEnd(widths.lastUsed),
+      String(r.lastUsedWith).padEnd(widths.lastUsedWith)
+    ].join('  ');
+
+  console.log(formatRow(headers));
+  for (const r of rows) {
+    console.log(formatRow(r));
+  }
+
+  console.log('');
+  console.log('Pass a handle with --council, e.g.:');
+  console.log('  pair-review <pr> --ai-draft --council ' + shortId(councils[0].id));
+}
+
 /**
  * Print version and exit
  */
@@ -279,6 +355,8 @@ const KNOWN_FLAGS = new Set([
   '-l', '--local',
   '--mcp',
   '--model',
+  '--council',
+  '--list-councils',
   '--register',
   '--unregister',
   '--command',
@@ -328,6 +406,16 @@ function parseArgs(args) {
       } else {
         throw new Error('--model flag requires a model name (e.g., --model sonnet)');
       }
+    } else if (arg === '--council') {
+      // Next argument is the council handle (name, name-slug, or id prefix)
+      if (i + 1 < args.length && !args[i + 1].startsWith('-')) {
+        flags.council = args[i + 1];
+        i++; // Skip next argument since we consumed it
+      } else {
+        throw new Error('--council flag requires a council handle (e.g., --council my-council)');
+      }
+    } else if (arg === '--list-councils') {
+      flags.listCouncils = true;
     } else if (arg === '-l' || arg === '--local') {
       // -l/--local flag is always a boolean
       flags.local = true;
@@ -497,26 +585,84 @@ AI PROVIDERS:
       process.env.PAIR_REVIEW_YOLO = 'true';
     }
 
+    // --model is ignored when --council is set: council voices use their own
+    // per-voice models, so a top-level --model has no effect on the analysis.
+    if (flags.council && flags.model) {
+      console.warn('Warning: --model is ignored when --council is set; council voices use their own per-voice models.');
+    }
+
     // Apply provider config overrides (including yolo) for all code paths
     // (interactive, headless, local). server.js calls this independently on
     // startup, but headless paths (--ai-draft, --ai-review) never start the
     // server, so we must also apply here.
     applyConfigOverrides(config);
 
+    // --list-councils: print the saved councils and exit. Needs the database
+    // but no server, no PR/local context, and no single-port delegation.
+    if (flags.listCouncils) {
+      const listDb = await initializeDatabase(resolveDbName(config));
+      try {
+        await printCouncilList(listDb);
+      } finally {
+        try { listDb.close(); } catch { /* ignore */ }
+      }
+      process.exit(0);
+    }
+
+    // --council requires something to analyze: a PR identifier or --local.
+    // Reject early (before single-port delegation) so a contextless `--council`
+    // fails fast with a clear message instead of silently delegating to — or
+    // starting — the generic landing page with the council ignored.
+    //
+    // Exception: in GitHub Actions, `--ai-review --council <handle>` is a
+    // documented headless flow where the PR is auto-detected from the
+    // environment further below (detectPRFromGitHubEnvironment). At this point
+    // prArgs is still empty, so guarding on it alone would reject that valid CI
+    // invocation. Defer to the later `--ai-review` PR check, which reports a
+    // clear error if no PR can be detected.
+    if (
+      flags.council &&
+      prArgs.length === 0 &&
+      !flags.local &&
+      !(flags.aiReview && process.env.GITHUB_ACTIONS === 'true')
+    ) {
+      throw new Error('--council flag requires a pull request number/URL or --local to run analysis');
+    }
+
+    // Resolve the council handle FAIL-FAST, before single-port delegation, so
+    // that (a) a bad handle errors out for every mode (interactive, headless,
+    // and delegated) rather than only on a cold start, and (b) the resolved id
+    // can be threaded into the delegated URL — the browser-side council
+    // auto-analysis is keyed on the `council` query param. Resolution needs the
+    // DB, so when --council is set we open the shared connection now and the
+    // downstream handlers reuse it (they re-resolve for their own purposes;
+    // that is a cheap in-memory match against the same connection).
+    let cliCouncil = null;
+    if (flags.council) {
+      db = await initializeDatabase(resolveDbName(config));
+      cliCouncil = await resolveCouncilHandle(db, flags.council);
+    }
+
     // Single-port delegation: if a pair-review server is already running on the
     // configured port, delegate to it (open browser URL) and exit immediately.
     // Skipped for: headless modes (no browser), single_port: false (dev mode).
     if (config.single_port !== false && !flags.aiReview && !flags.aiDraft) {
-      const delegated = await attemptDelegation(config, flags, prArgs);
+      const delegated = await attemptDelegation(config, flags, prArgs, undefined, {
+        councilId: cliCouncil?.id || null
+      });
       if (delegated) {
+        if (db) { try { db.close(); } catch { /* ignore */ } }
         process.exit(0);
       }
       // Not delegated — no server running, proceed to start one
     }
 
-    // Initialize database
-    console.log('Initializing database...');
-    db = await initializeDatabase(resolveDbName(config));
+    // Initialize database (reuse the connection already opened for council
+    // resolution above, if any).
+    if (!db) {
+      console.log('Initializing database...');
+      db = await initializeDatabase(resolveDbName(config));
+    }
 
     // Migrate existing worktrees to database (if any)
     const path = require('path');
@@ -649,11 +795,20 @@ async function handlePullRequest(args, config, db, flags = {}, poolLifecycle = n
       await registerRepositoryLocation(db, currentDir, prInfo.owner, prInfo.repo);
     }
 
-    // Set model override if provided via CLI flag
-    if (flags.model) {
+    // Set model override if provided via CLI flag. Skipped when --council is
+    // set: council voices carry their own per-voice models.
+    if (flags.model && !flags.council) {
       process.env.PAIR_REVIEW_MODEL = flags.model;
     }
 
+    // Resolve the council handle FAIL-FAST before starting the server, so a bad
+    // handle surfaces as a clean error (caught below) instead of after the
+    // browser has opened.
+    let councilSelection = null;
+    if (flags.council) {
+      councilSelection = await resolveCouncilHandle(db, flags.council);
+    }
+
     // Start server and open browser to setup page
     const port = await startServer(db, poolLifecycle);
 
@@ -663,9 +818,9 @@ async function handlePullRequest(args, config, db, flags = {}, poolLifecycle = n
     startPoolBackgroundFetches(db, config);
 
     let url = `http://localhost:${port}/pr/${prInfo.owner}/${prInfo.repo}/${prInfo.number}`;
-    if (flags.ai) {
-      url += '?analyze=true';
-    }
+    const shouldAnalyze = flags.ai || flags.council;
+    if (shouldAnalyze) url += '?analyze=true';
+    if (councilSelection) url += `&council=${councilSelection.id}`;
 
     console.log(`Opening browser to: ${url}`);
     await open(url);
@@ -742,6 +897,21 @@ async function performHeadlessReview(args, config, db, flags, options, externalP
     const parser = new PRArgumentParser(config);
     prInfo = await parser.parsePRArguments(args);
 
+    // Resolve + validate the council FAIL-FAST, before any worktree/network
+    // work, so a bad handle or invalid config surfaces immediately.
+    let councilSelection = null;
+    if (flags.council) {
+      const council = await resolveCouncilHandle(db, flags.council);
+      const configType = council.type || 'advanced';
+      const councilConfig = normalizeCouncilConfig(council.config, configType);
+      // validateCouncilConfig returns an error string, or null when valid.
+      const validationError = validateCouncilConfig(councilConfig, configType);
+      if (validationError) {
+        throw new Error(`Invalid council "${council.name}": ${validationError}`);
+      }
+      councilSelection = { council, configType, councilConfig };
+    }
+
     // 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
@@ -972,13 +1142,11 @@ async function performHeadlessReview(args, config, db, flags, options, externalP
     const globalInstructions = config.globalInstructions || null;
 
     // Run AI analysis
-    console.log('Running AI analysis (all 3 levels)...');
     const cliProvider = repoSettings?.default_provider || config.default_provider || config.provider || 'claude';
     const model = flags.model || process.env.PAIR_REVIEW_MODEL || repoSettings?.default_model || config.default_model || config.model || 'opus';
     const providerLoadSkills = config.providers?.[cliProvider]?.load_skills;
     const loadSkills = resolveLoadSkills(config, repository, repoSettings, providerLoadSkills);
     const providerOverrides = { load_skills: loadSkills };
-    const analyzer = new Analyzer(db, model, cliProvider, providerOverrides);
 
     let analysisSummary = null;
     try {
@@ -986,7 +1154,33 @@ async function performHeadlessReview(args, config, db, flags, options, externalP
       // 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 });
+      let analysisResult;
+      if (councilSelection) {
+        console.log(`Running council analysis: ${councilSelection.council.name} (${councilSelection.configType})...`);
+        // Council voices can span multiple providers, so resolve a per-provider
+        // load_skills map (tier-3 resolution per provider) the same way every
+        // other council invoker does (pr.js / local.js / stack-analysis.js).
+        // Passing only the shared `providerOverrides` would collapse every voice
+        // onto the default provider's load_skills — see buildVoiceContext.
+        const { providerOverrides: councilProviderOverrides, providerOverridesMap: councilProviderOverridesMap } =
+          buildCouncilProviderOverrides(config, repository, repoSettings);
+        const analyzer = new Analyzer(db, 'council', 'council', councilProviderOverrides, councilProviderOverridesMap);
+        analysisResult = await runHeadlessCouncilAnalysis(db, {
+          analyzer,
+          reviewId: review.id,
+          council: councilSelection.council,
+          configType: councilSelection.configType,
+          councilConfig: councilSelection.councilConfig,
+          worktreePath,
+          prMetadata: storedPRData,
+          instructions: { globalInstructions, repoInstructions, requestInstructions: null },
+          githubClient
+        });
+      } else {
+        console.log('Running AI analysis (all 3 levels)...');
+        const analyzer = new Analyzer(db, model, cliProvider, providerOverrides);
+        analysisResult = await analyzer.analyzeAllLevels(review.id, worktreePath, storedPRData, null, { globalInstructions, repoInstructions }, null, { githubClient });
+      }
       analysisSummary = analysisResult.summary;
       console.log('AI analysis completed successfully');
     } catch (analysisError) {
@@ -1402,4 +1596,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { main, parseArgs, detectPRFromGitHubEnvironment };
+module.exports = { main, parseArgs, detectPRFromGitHubEnvironment, printCouncilList };

package/src/routes/stack-analysis.js

@@ -19,7 +19,7 @@ const { normalizeRepository } = require('../utils/paths');
 const { mergeInstructions } = require('../utils/instructions');
 const { GitWorktreeManager } = require('../git/worktree');
 const { GitHubClient } = require('../github/client');
-const { getGitHubToken, resolveHostBinding, resolveBindingRepositoryFromPR, resolveLoadSkills, buildCouncilProviderOverrides } = require('../config');
+const { getGitHubToken, resolveHostBinding, resolveBindingRepositoryFromPR, resolveRepoOptions, resolveLoadSkills, buildCouncilProviderOverrides } = require('../config');
 const { setupStackPR } = require('../setup/stack-setup');
 const Analyzer = require('../ai/analyzer');
 const { getProviderClass, createProvider } = require('../ai/provider');
@@ -166,6 +166,7 @@ const defaults = {
   getGitHubToken,
   resolveHostBinding,
   resolveBindingRepositoryFromPR,
+  resolveRepoOptions,
   setupStackPR,
   Analyzer,
   getProviderClass,
@@ -205,8 +206,23 @@ async function executeStackAnalysis(params) {
   if (!state) return;
 
   try {
+    // 0. Resolve the config-binding key once. It drives both the per-repo
+    //    worktree config (just below) and the host binding (step 3). For
+    //    monorepo-style `url_pattern` configs this differs from the PR
+    //    identity `${owner}/${repo}`.
+    const bindingRepository = deps.resolveBindingRepositoryFromPR(owner, repo, config);
+    // Honor the repo's configured worktree options so stack worktrees match the
+    // non-stack path. This carries through:
+    //  - worktreeConfig (worktree_name_template / worktree_directory) so they
+    //    don't fall back to pair-review's default naming and location, and
+    //  - the checkout script + timeout and sparse-checkout inheritance used
+    //    during per-PR worktree creation (forwarded to createWorktreeForPR).
+    // These derive purely from file config, so DB repo_settings (pool config)
+    // are not needed here.
+    const { worktreeConfig, checkoutScript, checkoutTimeout } = deps.resolveRepoOptions(config, bindingRepository);
+
     // 1. Resolve repositoryPath from trigger worktree
-    const worktreeManager = new deps.GitWorktreeManager(db);
+    const worktreeManager = new deps.GitWorktreeManager(db, worktreeConfig || {});
     let repositoryPath;
     try {
       const owningRepoGit = await worktreeManager.resolveOwningRepo(triggerWorktreePath);
@@ -230,13 +246,13 @@ async function executeStackAnalysis(params) {
       logger.warn(`Bulk git fetch failed, will fetch per-PR: ${fetchError.message}`);
     }
 
-    // 3. Fetch all PR data from GitHub in parallel
-    // Use the per-repo binding so alt-host stack analyses target the right host.
-    // The PR identity (`${owner}/${repo}`) is used for DB rows and worktree
-    // identity. For host-binding lookups we MUST use the config-binding key,
-    // which differs from the PR identity for monorepo-style `url_pattern`
-    // configs (one `repos[...]` entry serves many captured owner/repo pairs).
-    const bindingRepository = deps.resolveBindingRepositoryFromPR(owner, repo, config);
+    // 3. Fetch all PR data from GitHub in parallel.
+    // `bindingRepository` (resolved in step 0) is the config-binding key. We use
+    // it — not the PR identity `${owner}/${repo}` — for host-binding lookups so
+    // alt-host stack analyses target the right host. The two differ for
+    // monorepo-style `url_pattern` configs (one `repos[...]` entry serves many
+    // captured owner/repo pairs). The PR identity is still used for DB rows and
+    // worktree identity.
     const stackBinding = deps.resolveHostBinding(bindingRepository, config);
     const githubToken = stackBinding.token;
     const prDataMap = new Map();
@@ -275,7 +291,16 @@ async function executeStackAnalysis(params) {
 
         const prInfo = { owner, repo, number: prNum };
         const { path: perPRWorktreePath } = await worktreeManager.createWorktreeForPR(
-          prInfo, prData, repositoryPath
+          prInfo, prData, repositoryPath,
+          {
+            checkoutScript,
+            checkoutTimeout,
+            // No checkout script → inherit the trigger worktree's sparse-checkout
+            // layout instead of a full checkout from the repo root. When a script is
+            // configured it sets up sparse-checkout itself, so worktreeSourcePath is
+            // unused (and omitted) in that case.
+            ...(checkoutScript ? {} : { worktreeSourcePath: triggerWorktreePath }),
+          }
         );
         worktreePathMap.set(prNum, perPRWorktreePath);
       } catch (wtError) {
@@ -307,6 +332,7 @@ async function executeStackAnalysis(params) {
           worktreePath: worktreePathMap.get(prNum),
           analysisConfig, stackAnalysisId, state,
           githubToken, binding: stackBinding, prData: prDataMap.get(prNum),
+          worktreeConfig, checkoutScript,
           onAnalysisIdReady
         }).then(result => {
           state.prStatuses.set(prNum, {
@@ -346,6 +372,7 @@ async function executeStackAnalysis(params) {
 async function analyzeStackPR(deps, db, config, {
   owner, repo, repository, bindingRepository, prNum, worktreePath,
   analysisConfig, stackAnalysisId, state, githubToken, binding, prData,
+  worktreeConfig, checkoutScript,
   onAnalysisIdReady
 }) {
   // Build a GitHubClient for analyzer-side dedup pre-fetch. The stack
@@ -357,12 +384,17 @@ async function analyzeStackPR(deps, db, config, {
   if (stackGithubClient) {
     logger.debug(`analyzer githubClient wired for ${owner}/${repo}#${prNum} (stack)`);
   }
-  // 1. Setup PR (generates diff, stores metadata)
-  const worktreeManager = new deps.GitWorktreeManager(db);
+  // 1. Setup PR (expands sparse-checkout, generates diff, stores metadata)
+  // Construct with the repo's resolved worktreeConfig for consistency with the
+  // creation manager. setupStackPR operates against the explicit worktreePath
+  // (diff generation + sparse-cone expansion), so the worktreeConfig naming /
+  // directory options are not exercised today — threading them through guards
+  // against silent latent regressions if that changes.
+  const worktreeManager = new deps.GitWorktreeManager(db, worktreeConfig || {});
   await deps.setupStackPR({
     db, owner, repo, prNumber: prNum,
     githubToken, binding, bindingRepository,
-    worktreePath, worktreeManager, prData
+    worktreePath, worktreeManager, prData, checkoutScript
   });
 
   // 2. Fetch prMetadata from DB

package/src/setup/stack-setup.js

@@ -32,9 +32,12 @@ const logger = require('../utils/logger');
  * @param {string} params.worktreePath - Path to the per-PR worktree
  * @param {import('../git/worktree').GitWorktreeManager} params.worktreeManager - Worktree manager instance
  * @param {Object} [params.prData] - Pre-fetched PR data from GitHub (skips API call when provided)
+ * @param {string|null} [params.checkoutScript] - Repo's configured checkout script, if any. When set,
+ *   the script owns all sparse-checkout setup, so built-in sparse-cone expansion is skipped (mirrors
+ *   the non-stack `pr-setup.js` contract).
  * @returns {Promise<{ reviewId: number, prMetadata: Object, prData: Object, isNew: boolean }>}
  */
-async function setupStackPR({ db, owner, repo, prNumber, githubToken, binding, bindingRepository, worktreePath, worktreeManager, prData: prefetchedPRData }) {
+async function setupStackPR({ db, owner, repo, prNumber, githubToken, binding, bindingRepository, worktreePath, worktreeManager, prData: prefetchedPRData, checkoutScript }) {
   // `bindingRepository` is accepted so callers (e.g. `executeStackAnalysis`)
   // can thread the resolved config-binding key through to any downstream
   // per-repo lookups added in this function. Currently unused inside this
@@ -56,13 +59,38 @@ async function setupStackPR({ db, owner, repo, prNumber, githubToken, binding, b
   const prFiles = await githubClient.fetchPullRequestFiles(owner, repo, prNumber);
   logger.info(`PR #${prNumber} has ${prFiles.length} changed files`);
 
-  // 3. Generate diff in the worktree (SHA-based, works after checkout)
+  // 3. Expand sparse-checkout for PR-changed directories (mirrors pr-setup.js).
+  // Stack worktrees inherit the trigger worktree's sparse-checkout layout, which
+  // may omit directories a sibling PR touches. The SHA-based diff below reads
+  // commit objects (not the working tree) so it is unaffected, but the later
+  // file-context and codebase-context analysis steps DO read files from disk —
+  // an unexpanded cone would silently under-review those files. Expanding here
+  // ensures every PR-changed directory is present on disk.
+  //
+  // IMPORTANT: when a checkout_script is configured the script owns all
+  // sparse-checkout setup, so we must NOT auto-expand — doing so would override
+  // the cone the script just configured. This matches the pr-setup.js contract.
+  if (!checkoutScript && prFiles.length > 0) {
+    const isSparse = await worktreeManager.isSparseCheckoutEnabled(worktreePath);
+    if (isSparse) {
+      try {
+        const addedDirs = await worktreeManager.ensurePRDirectoriesInSparseCheckout(worktreePath, prFiles);
+        if (addedDirs.length > 0) {
+          logger.info(`Stack PR #${prNumber}: expanded sparse-checkout for: ${addedDirs.join(', ')}`);
+        }
+      } catch (sparseError) {
+        logger.warn(`Stack PR #${prNumber}: sparse-checkout expansion failed (non-fatal): ${sparseError.message}`);
+      }
+    }
+  }
+
+  // 4. Generate diff in the worktree (SHA-based, works after checkout)
   const diff = await worktreeManager.generateUnifiedDiff(worktreePath, prData);
 
-  // 4. Get changed files with stats
+  // 5. Get changed files with stats
   const changedFiles = await worktreeManager.getChangedFiles(worktreePath, prData);
 
-  // 5. Store via storePRData (creates/updates pr_metadata, reviews, worktrees records)
+  // 6. Store via storePRData (creates/updates pr_metadata, reviews, worktrees records)
   const prInfo = { owner, repo, number: prNumber };
   const { isNewReview, reviewId } = await storePRData(db, prInfo, prData, diff, changedFiles, worktreePath);
 

package/src/single-port.js

@@ -95,18 +95,24 @@ function notifyVersion(port, currentVersion, _deps) {
  * @param {number} [context.number]
  * @param {string} [context.localPath]
  * @param {boolean} [context.analyze] - Whether to trigger auto-analysis
+ * @param {string} [context.councilId] - Resolved council id for council auto-analysis
  * @returns {string} Full URL
  */
 function buildDelegationUrl(port, mode, context = {}) {
   const base = `http://localhost:${port}`;
   if (mode === 'pr') {
     let url = `${base}/pr/${context.owner}/${context.repo}/${context.number}`;
-    if (context.analyze) url += '?analyze=true';
+    const query = [];
+    if (context.analyze) query.push('analyze=true');
+    if (context.councilId) query.push(`council=${encodeURIComponent(context.councilId)}`);
+    if (query.length) url += `?${query.join('&')}`;
     return url;
   }
   if (mode === 'local') {
+    // The `?path=` segment is always present, so analyze/council append with `&`.
     let url = `${base}/local?path=${encodeURIComponent(context.localPath)}`;
     if (context.analyze) url += '&analyze=true';
+    if (context.councilId) url += `&council=${encodeURIComponent(context.councilId)}`;
     return url;
   }
   return `${base}/`;
@@ -137,11 +143,21 @@ async function parsePRArgsForDelegation(prArgs, config = null, _deps) {
  * @param {object} flags - Parsed CLI flags
  * @param {string[]} prArgs - PR arguments from CLI
  * @param {object} [_deps] - Dependency overrides for testing
+ * @param {object} [options] - Pre-resolved values from the caller
+ * @param {string|null} [options.councilId] - Resolved council id (the caller
+ *   resolves `flags.council` against the DB before delegation, since this
+ *   module has no DB access). When set, the delegated URL carries
+ *   `&council=<id>` and auto-analysis is forced on.
  * @returns {Promise<boolean>} true if delegated, false if should start fresh
  */
-async function attemptDelegation(config, flags, prArgs, _deps) {
+async function attemptDelegation(config, flags, prArgs, _deps, options = {}) {
   const deps = { ...defaults, ..._deps };
   const port = config.port;
+  const councilId = options.councilId || null;
+  // A council selection implies analysis: the browser-side council
+  // auto-analysis is gated on the `council` param + `analyze=true`, mirroring
+  // the cold-start URL built in handlePullRequest/handleLocalReview.
+  const analyze = !!(flags.ai || flags.council);
 
   const result = await detectRunningServer(port, _deps);
 
@@ -164,10 +180,10 @@ async function attemptDelegation(config, flags, prArgs, _deps) {
   if (flags.local) {
     rejectUrlLikeLocalReviewPath(flags.localPath);
     const targetPath = path.resolve(flags.localPath || process.cwd());
-    url = buildDelegationUrl(port, 'local', { localPath: targetPath, analyze: flags.ai });
+    url = buildDelegationUrl(port, 'local', { localPath: targetPath, analyze, councilId });
   } else if (prArgs.length > 0) {
     const prInfo = await parsePRArgsForDelegation(prArgs, config, _deps);
-    url = buildDelegationUrl(port, 'pr', { ...prInfo, analyze: flags.ai });
+    url = buildDelegationUrl(port, 'pr', { ...prInfo, analyze, councilId });
   } else {
     url = buildDelegationUrl(port, 'server');
   }