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

package/src/councils/headless-council.js

@@ -0,0 +1,128 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+
+const { v4: uuidv4 } = require('uuid');
+const { AnalysisRunRepository, CouncilRepository } = require('../database');
+const logger = require('../utils/logger');
+
+/**
+ * Run a council analysis without any server infrastructure.
+ *
+ * This is the server-free twin of `launchCouncilAnalysis` in
+ * `src/routes/analyses.js`. It exists for the CLI headless path, where the
+ * SSE broadcast helpers (`broadcastProgress`/`broadcastReviewEvent`), the
+ * `activeAnalyses` map, the worktree pool lifecycle, and the hook firing of
+ * the route are all absent. It reuses the SAME analyzer methods
+ * (`runReviewerCentricCouncil` / `runCouncilAnalysis`) and the SAME
+ * run-record semantics as the route.
+ *
+ * IMPORTANT: The two functions MUST stay in parity for run-record fields and
+ * completion semantics. Specifically:
+ *   - The parent `analysis_runs` row is PRE-CREATED here with
+ *     `model = council.id` and `runId` is passed into the analyzer. This is
+ *     what attributes the run to the council. The analyzer methods do not
+ *     create the parent row when a `runId` is supplied.
+ *   - The analyzer methods do NOT mark the parent run completed/failed; this
+ *     helper does it (mirroring the route's `.then()` / `.catch()`).
+ * Any change to run-record fields or completion handling must be applied to
+ * BOTH this function and `launchCouncilAnalysis`.
+ *
+ * @param {Object} db - Database instance
+ * @param {Object} params - Analysis parameters
+ * @param {Object} params.analyzer - Analyzer instance exposing
+ *   `runReviewerCentricCouncil` and `runCouncilAnalysis`
+ * @param {number} params.reviewId - Review ID (PR or local)
+ * @param {Object} params.council - Full council row (must have `.id`)
+ * @param {string} params.configType - 'council' (voice-centric) or 'advanced'
+ * @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>} `{ runId, ...result }` — the parent run id created
+ *   here, spread together with the analyzer result
+ *   ({ suggestions, summary, levelOutcomes, ... }).
+ */
+async function runHeadlessCouncilAnalysis(db, params) {
+  const {
+    analyzer,
+    reviewId,
+    council,
+    configType,
+    councilConfig,
+    worktreePath,
+    prMetadata,
+    changedFiles,
+    instructions,
+    githubClient,
+  } = params;
+
+  const runId = uuidv4();
+
+  // Compute levelsConfig the same way launchCouncilAnalysis (analyses.js:533-541) does.
+  let levelsConfig = null;
+  if (configType === 'council') {
+    levelsConfig = councilConfig.levels || null;
+  } else if (councilConfig.levels) {
+    levelsConfig = {};
+    for (const [key, val] of Object.entries(councilConfig.levels)) {
+      levelsConfig[key] = val?.enabled !== false;
+    }
+  }
+
+  const runRepo = new AnalysisRunRepository(db);
+  await runRepo.create({
+    id: runId,
+    reviewId,
+    provider: 'council',
+    model: council.id,
+    tier: null,
+    globalInstructions: instructions.globalInstructions || null,
+    repoInstructions: instructions.repoInstructions || null,
+    requestInstructions: instructions.requestInstructions || null,
+    headSha: prMetadata?.head_sha || null,
+    configType,
+    levelsConfig
+  });
+
+  new CouncilRepository(db).touchLastUsedAt(council.id).catch(err => {
+    logger.warn(`Failed to update council last_used_at: ${err.message}`);
+  });
+
+  const reviewContext = {
+    reviewId,
+    worktreePath,
+    prMetadata,
+    // 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
+  };
+
+  try {
+    const result = configType === 'council'
+      ? await analyzer.runReviewerCentricCouncil(reviewContext, councilConfig, { runId, progressCallback: null, githubClient })
+      : await analyzer.runCouncilAnalysis(reviewContext, councilConfig, { runId, progressCallback: null, githubClient });
+
+    await runRepo.update(runId, {
+      status: 'completed',
+      summary: result.summary,
+      totalSuggestions: result.suggestions.length,
+      ...(result.levelOutcomes ? { levelOutcomes: result.levelOutcomes } : {})
+    }).catch(err => {
+      logger.warn(`Failed to update analysis_run: ${err.message}`);
+    });
+
+    return { runId, ...result };
+  } catch (error) {
+    await runRepo.update(runId, { status: 'failed' }).catch(() => {});
+    throw error;
+  }
+}
+
+module.exports = { runHeadlessCouncilAnalysis };

package/src/councils/resolve-council.js

@@ -0,0 +1,167 @@
+// Copyright 2026 Tim Perkins (tjwp) | SPDX-License-Identifier: Apache-2.0
+/**
+ * Council handle resolution helpers.
+ *
+ * Resolves user-supplied CLI handles (id, id-prefix, name, normalized name) to a
+ * saved council row, and gathers "Last Used With" metadata for the council list.
+ */
+
+const { query, CouncilRepository } = require('../database');
+
+/**
+ * Normalize a string for fuzzy name matching: lowercase, trim, collapse any run
+ * of non-alphanumeric characters to a single dash, and strip leading/trailing dashes.
+ * @param {string} s - Input string
+ * @returns {string} Normalized slug-like string
+ */
+function normalizeForMatch(s) {
+  return String(s || '').toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Truncate an id to its first 8 characters for display.
+ * @param {string} id - Full council id (UUID)
+ * @returns {string} Short id
+ */
+function shortId(id) {
+  return String(id || '').slice(0, 8);
+}
+
+/**
+ * Build a clear, multi-line ambiguity error for a handle that matched several councils.
+ * @param {string} handle - The user-supplied handle
+ * @param {Array<Object>} matches - The matching council rows
+ * @returns {Error} Error with a readable, aligned candidate list
+ * @private
+ */
+function _ambiguityError(handle, matches) {
+  const padTo = Math.max(...matches.map(c => String(c.name || '').length));
+  const lines = matches.map(c => {
+    const name = String(c.name || '').padEnd(padTo);
+    // Show the FULL id, not shortId: when the collision is on the 8-char prefix,
+    // every shortId would be identical and could not disambiguate.
+    return `  ${name}  (${c.id})`;
+  });
+  return new Error(
+    `Ambiguous council "${handle}" matches ${matches.length} councils. Disambiguate with the id:\n` +
+    lines.join('\n')
+  );
+}
+
+/**
+ * Resolve a user-supplied council handle to a full council row.
+ *
+ * Matching order (first unambiguous match wins):
+ *   1. Exact id
+ *   2. UUID-prefix (only for hex-ish handles of length >= 4)
+ *   3. Exact name (case-insensitive)
+ *   4. Normalized name
+ *   5. Partial (substring) name fragment (last resort, never shadows the above)
+ *
+ * @param {Database} db - Database instance
+ * @param {string} handle - The handle to resolve (id, id-prefix, or name)
+ * @returns {Promise<Object>} The matching council row
+ * @throws {Error} If the handle is missing, ambiguous, or matches nothing
+ */
+async function resolveCouncilHandle(db, handle) {
+  const all = await new CouncilRepository(db).list();
+
+  if (!handle) {
+    throw new Error('A council handle is required.');
+  }
+
+  // 1. Exact id
+  const exactId = all.find(c => c.id === handle);
+  if (exactId) return exactId;
+
+  // 2. UUID-prefix match (only for hex-ish handles of meaningful length)
+  if (handle.length >= 4 && /^[0-9a-f-]+$/i.test(handle)) {
+    const m = all.filter(c => c.id.toLowerCase().startsWith(handle.toLowerCase()));
+    if (m.length === 1) return m[0];
+    if (m.length > 1) throw _ambiguityError(handle, m);
+  }
+
+  // 3. Exact name (case-insensitive)
+  {
+    const m = all.filter(c => c.name.toLowerCase() === handle.toLowerCase());
+    if (m.length === 1) return m[0];
+    if (m.length > 1) throw _ambiguityError(handle, m);
+  }
+
+  // 4. Normalized name
+  {
+    const hn = normalizeForMatch(handle);
+    const m = all.filter(c => normalizeForMatch(c.name) === hn);
+    if (m.length === 1) return m[0];
+    if (m.length > 1) throw _ambiguityError(handle, m);
+  }
+
+  // 5. Partial (substring) name fragment — last resort. A council matches if its
+  // name contains the handle (case-insensitive) OR its normalized name contains
+  // the normalized handle. Union both, de-duplicated by id so a council matched
+  // both ways isn't double-counted.
+  {
+    const hl = handle.toLowerCase();
+    const hn = normalizeForMatch(handle);
+    const seen = new Set();
+    const m = [];
+    for (const c of all) {
+      const byName = String(c.name || '').toLowerCase().includes(hl);
+      const byNorm = hn !== '' && normalizeForMatch(c.name).includes(hn);
+      if ((byName || byNorm) && !seen.has(c.id)) {
+        seen.add(c.id);
+        m.push(c);
+      }
+    }
+    if (m.length === 1) return m[0];
+    if (m.length > 1) throw _ambiguityError(handle, m);
+  }
+
+  // No match
+  throw new Error(
+    `No council matches "${handle}". Run \`pair-review --list-councils\` to see available councils.`
+  );
+}
+
+/**
+ * Build a map of the most recent council RUN per saved council, for the
+ * "Last Used With" column in the council list.
+ *
+ * Only counts true council runs (provider = 'council', model != 'inline-config').
+ * Councils with no council run simply won't appear in the map.
+ *
+ * @param {Database} db - Database instance
+ * @returns {Promise<Map<string, {repository: string, review_type: string, pr_number: number, last_started: string}>>}
+ *   Map keyed by council id.
+ */
+async function getCouncilLastUsedRepos(db) {
+  const rows = await query(db, `
+    SELECT ar.model AS council_id,
+           r.repository AS repository,
+           r.review_type AS review_type,
+           r.pr_number AS pr_number,
+           MAX(ar.started_at) AS last_started
+    FROM analysis_runs ar
+    JOIN reviews r ON r.id = ar.review_id
+    WHERE ar.provider = 'council' AND ar.model != 'inline-config'
+    GROUP BY ar.model
+  `);
+
+  const map = new Map();
+  for (const row of rows) {
+    map.set(row.council_id, {
+      repository: row.repository,
+      review_type: row.review_type,
+      pr_number: row.pr_number,
+      last_started: row.last_started
+    });
+  }
+  return map;
+}
+
+module.exports = {
+  normalizeForMatch,
+  shortId,
+  resolveCouncilHandle,
+  getCouncilLastUsedRepos
+};

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
+};

package/src/local-review.js

@@ -13,6 +13,8 @@ const { buildReviewStartedPayload, buildReviewLoadedPayload, getCachedUser } = r
 const execAsync = promisify(exec);
 const { STOPS, scopeIncludes, includesBranch, DEFAULT_SCOPE, scopeLabel, reviewScope } = require('./local-scope');
 const { initializeDatabase, ReviewRepository, RepoSettingsRepository } = require('./database');
+const { resolveCouncilHandle } = require('./councils/resolve-council');
+const { prepareInteractiveAnalysisConfig } = require('./interactive-analysis-config');
 const { startServer } = require('./server');
 const { localReviewDiffs } = require('./routes/shared');
 const summaryGenerator = require('./ai/summary-generator');
@@ -702,9 +704,14 @@ async function generateLocalDiff(repoPath, options = {}) {
  * @param {Object} params.config - Loaded config
  * @param {string} params.repoPath - Path to the working tree (already validated)
  * @param {Object} [params.flags] - CLI flags / options
+ * @param {boolean} [params.startBackgroundJobs=true] - When false, skip the
+ *   fire-and-forget summary/tour generation jobs. The interactive UI wants them
+ *   (they populate the review while the human reads the diff), but a one-shot
+ *   headless run does not: they would spend provider budget after the JSON
+ *   result is already printed and keep the event loop alive (CLI hang).
  * @returns {Promise<{sessionId: number, repoPath: string, branch: string, repository: string, headSha: string, diff: string, stats: Object, digest: string|null, branchInfo: Object|null, scopeStart: string, scopeEnd: string, baseBranch: string|null}>}
  */
-async function setupLocalReviewSession({ db, config, repoPath, flags = {} }) {
+async function setupLocalReviewSession({ db, config, repoPath, flags = {}, startBackgroundJobs = true }) {
   const headSha = await module.exports.getHeadSha(repoPath);
   console.log(`HEAD SHA: ${headSha}`);
 
@@ -836,25 +843,30 @@ async function setupLocalReviewSession({ db, config, repoPath, flags = {} }) {
     logger.warn(`Could not persist diff to database: ${persistError.message}`);
   }
 
-  summaryGenerator.kickOffSummaryJob({
-    db,
-    config,
-    reviewId: sessionId,
-    diffText: diff,
-    worktreePath: repoPath,
-    reviewContext: { prTitle: branch },
-    trigger: 'auto'
-  })?.catch((err) => logger.warn(`Hunk summary job failed for review ${sessionId}: ${err.message}`));
-
-  tourGenerator.kickOffTourJob({
-    db,
-    config,
-    reviewId: sessionId,
-    diffText: diff,
-    worktreePath: repoPath,
-    reviewContext: { prTitle: branch },
-    trigger: 'auto'
-  })?.catch((err) => logger.warn(`Tour job failed for review ${sessionId}: ${err.message}`));
+  // Fire-and-forget summary/tour generation. Skipped for headless one-shot runs
+  // (startBackgroundJobs:false) — they would spend provider budget after the
+  // result is reported and keep the event loop alive, hanging the CLI.
+  if (startBackgroundJobs) {
+    summaryGenerator.kickOffSummaryJob({
+      db,
+      config,
+      reviewId: sessionId,
+      diffText: diff,
+      worktreePath: repoPath,
+      reviewContext: { prTitle: branch },
+      trigger: 'auto'
+    })?.catch((err) => logger.warn(`Hunk summary job failed for review ${sessionId}: ${err.message}`));
+
+    tourGenerator.kickOffTourJob({
+      db,
+      config,
+      reviewId: sessionId,
+      diffText: diff,
+      worktreePath: repoPath,
+      reviewContext: { prTitle: branch },
+      trigger: 'auto'
+    })?.catch((err) => logger.warn(`Tour job failed for review ${sessionId}: ${err.message}`));
+  }
 
   return {
     sessionId,
@@ -906,10 +918,18 @@ async function handleLocalReview(targetPath, flags = {}) {
     console.log('Initializing database...');
     db = await initializeDatabase(resolveDbName(config));
 
+    // Resolve the council handle FAIL-FAST before any further setup, so a bad
+    // handle surfaces as a clean error instead of after the browser opens.
+    let councilSelection = null;
+    if (flags.council) {
+      councilSelection = await resolveCouncilHandle(db, flags.council);
+    }
+
     const session = await setupLocalReviewSession({ db, config, repoPath, flags });
     setupComplete = true;
 
-    if (flags.model) {
+    // 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;
     }
 
@@ -917,8 +937,19 @@ async function handleLocalReview(targetPath, flags = {}) {
     const port = await startServer(db);
 
     let url = `http://localhost:${port}/local/${session.sessionId}`;
-    if (flags.ai) {
-      url += '?analyze=true';
+    const shouldAnalyze = flags.ai || flags.council;
+    if (shouldAnalyze) url += '?analyze=true';
+    // When the run carries --instructions, stash the resolved analysis config and
+    // thread its id so the browser-side auto-analyze honors the instructions
+    // instead of silently dropping them (mirrors handlePullRequest). The id
+    // encodes the council selection, so prefer it over the bare &council= param.
+    const analysisConfigId = shouldAnalyze
+      ? await prepareInteractiveAnalysisConfig({ db, config, flags, repository: session.repository })
+      : null;
+    if (analysisConfigId) {
+      url += `&analysisConfigId=${analysisConfigId}`;
+    } else if (councilSelection) {
+      url += `&council=${councilSelection.id}`;
     }
     console.log(`\nOpening browser to: ${url}`);
     await open(url);