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

package/src/ai/provider.js

@@ -113,9 +113,13 @@ class AIProvider {
 
   /**
    * Test if the provider's CLI is available
+   * @param {number} [timeoutMs] - Optional timeout in milliseconds for the
+   *   availability probe. Subclasses that spawn a child process should use this
+   *   to bound the check (the value is resolved per-provider by
+   *   testProviderAvailability). Defaults to DEFAULT_AVAILABILITY_TIMEOUT_MS.
    * @returns {Promise<boolean>}
    */
-  async testAvailability() {
+  async testAvailability(timeoutMs) {
     throw new Error('testAvailability() must be implemented by subclass');
   }
 
@@ -353,6 +357,28 @@ const providerRegistry = new Map();
  */
 const providerConfigOverrides = new Map();
 
+/**
+ * Default timeout (ms) for a provider availability probe when no
+ * per-provider `availability_timeout_seconds` is configured.
+ */
+const DEFAULT_AVAILABILITY_TIMEOUT_MS = 10000;
+
+/**
+ * Convert a configured `availability_timeout_seconds` value to milliseconds.
+ * Single source of truth for the "valid positive seconds" predicate shared by
+ * every availability-probe timeout (AI providers, executable providers, and
+ * chat providers); falls back to `defaultMs` when the value is unset,
+ * non-numeric, non-finite, or <= 0.
+ * @param {*} seconds - Raw config value, expected to be a number of seconds
+ * @param {number} [defaultMs=DEFAULT_AVAILABILITY_TIMEOUT_MS] - Fallback in ms
+ * @returns {number} Timeout in milliseconds
+ */
+function secondsToTimeoutMs(seconds, defaultMs = DEFAULT_AVAILABILITY_TIMEOUT_MS) {
+  return (typeof seconds === 'number' && Number.isFinite(seconds) && seconds > 0)
+    ? seconds * 1000
+    : defaultMs;
+}
+
 /**
  * Whether yolo mode is enabled (skips fine-grained provider permissions)
  */
@@ -534,6 +560,7 @@ function applyConfigOverrides(config) {
         env: providerConfig.env,
         load_skills: providerConfig.load_skills,
         app_extensions: providerConfig.app_extensions,
+        availability_timeout_seconds: providerConfig.availability_timeout_seconds,
         models: AliasClass.getModels() !== BaseClass.getModels() ? AliasClass.getModels() : null
       });
       logger.debug(`Registered aliased provider: ${providerId} (base: ${providerConfig.type})`);
@@ -561,6 +588,7 @@ function applyConfigOverrides(config) {
       env: providerConfig.env,
       load_skills: providerConfig.load_skills,
       app_extensions: providerConfig.app_extensions,
+      availability_timeout_seconds: providerConfig.availability_timeout_seconds,
       models: processedModels
     });
   }
@@ -724,27 +752,54 @@ function createProvider(providerId, model = null, overrides = {}) {
   return new ProviderClass(actualModel, { ...(configOverrides || {}), ...overrides, yolo: yoloMode });
 }
 
+/**
+ * Resolve the availability-probe timeout (ms) for a provider.
+ * Reads the per-provider `availability_timeout_seconds` config override
+ * (in seconds, mirroring `checkout_timeout_seconds`); falls back to
+ * DEFAULT_AVAILABILITY_TIMEOUT_MS when unset, non-numeric, or <= 0.
+ * @param {string} providerId - Provider ID
+ * @returns {number} Timeout in milliseconds
+ */
+function resolveAvailabilityTimeoutMs(providerId) {
+  const seconds = providerConfigOverrides.get(providerId)?.availability_timeout_seconds;
+  return secondsToTimeoutMs(seconds);
+}
+
 /**
  * Test availability of a provider with timeout
  * @param {string} providerId - Provider ID
- * @param {number} timeout - Timeout in milliseconds (default 10 seconds)
+ * @param {number} [timeoutMs] - Timeout in milliseconds. When omitted, resolved
+ *   per-provider from `availability_timeout_seconds` (default 10 seconds).
  * @returns {Promise<{available: boolean, error?: string}>}
  */
-async function testProviderAvailability(providerId, timeout = 10000) {
+async function testProviderAvailability(providerId, timeoutMs) {
+  const effectiveTimeoutMs = timeoutMs != null ? timeoutMs : resolveAvailabilityTimeoutMs(providerId);
   try {
     const provider = createProvider(providerId);
 
-    // Race between availability test and timeout
+    // Race between availability test and timeout. The provider's own probe
+    // receives the same timeout so it can kill its child process on expiry;
+    // this race is the only guard for providers without an internal timeout.
+    // Capture the timer handle so we can clear it once the race settles —
+    // otherwise a fast probe with a large configured timeout would keep the
+    // Node event loop alive (and its rejection unobserved) until the timer fires.
+    let timeoutId;
     const timeoutPromise = new Promise((_, reject) => {
-      setTimeout(() => reject(new Error('Provider test timed out')), timeout);
+      timeoutId = setTimeout(
+        () => reject(new Error(`Provider test timed out after ${Math.round(effectiveTimeoutMs / 1000)}s`)),
+        effectiveTimeoutMs
+      );
     });
 
-    const available = await Promise.race([
-      provider.testAvailability(),
-      timeoutPromise
-    ]);
-
-    return { available };
+    try {
+      const available = await Promise.race([
+        provider.testAvailability(effectiveTimeoutMs),
+        timeoutPromise
+      ]);
+      return { available };
+    } finally {
+      clearTimeout(timeoutId);
+    }
   } catch (error) {
     const ProviderClass = providerRegistry.get(providerId);
     const installInstructions = ProviderClass?.getInstallInstructions() || 'Check the provider documentation.';
@@ -791,6 +846,9 @@ module.exports = {
   getAllProvidersInfo,
   createProvider,
   testProviderAvailability,
+  resolveAvailabilityTimeoutMs,
+  secondsToTimeoutMs,
+  DEFAULT_AVAILABILITY_TIMEOUT_MS,
   // Config override support
   applyConfigOverrides,
   createAliasedProviderClass,

package/src/chat/chat-providers.js

@@ -7,7 +7,7 @@
  */
 
 const { spawn } = require('child_process');
-const { getCachedAvailability } = require('../ai');
+const { getCachedAvailability, secondsToTimeoutMs, DEFAULT_AVAILABILITY_TIMEOUT_MS } = require('../ai');
 const logger = require('../utils/logger');
 
 // Default dependencies (overridable for testing)
@@ -123,6 +123,9 @@ function getChatProvider(id) {
     if (overrides.availability_command !== undefined) {
       provider.availability_command = overrides.availability_command;
     }
+    if (overrides.availability_timeout_seconds !== undefined) {
+      provider.availability_timeout_seconds = overrides.availability_timeout_seconds;
+    }
     if (overrides.extra_args && Array.isArray(overrides.extra_args)) {
       provider.args = [...provider.args, ...overrides.extra_args];
     }
@@ -147,6 +150,9 @@ function getChatProvider(id) {
   if (overrides.availability_command !== undefined) {
     merged.availability_command = overrides.availability_command;
   }
+  if (overrides.availability_timeout_seconds !== undefined) {
+    merged.availability_timeout_seconds = overrides.availability_timeout_seconds;
+  }
   if (overrides.env) merged.env = { ...merged.env, ...overrides.env };
   if (overrides.args) {
     merged.args = overrides.args;
@@ -230,9 +236,10 @@ function isCodexProvider(id) {
 /**
  * Check availability of a single chat provider.
  * Providers with `availability_command` run that command first.
- * Without an availability command, Pi delegates to the existing AI provider
- * availability cache and other providers spawn `<command> --version` to verify
- * the binary exists.
+ * Without an availability command, the built-in Pi provider (no `command`
+ * override) delegates to the existing AI provider availability cache; every
+ * other provider — including custom `type: 'pi'` providers and built-in Pi with
+ * a `command` override — spawns `<command> --version` to verify the binary exists.
  * @param {string} id - Provider ID
  * @param {Object} [_deps] - Dependency overrides for testing
  * @returns {Promise<{available: boolean, error?: string}>}
@@ -245,6 +252,12 @@ async function checkChatProviderAvailability(id, _deps) {
 
   const deps = { ...defaults, ..._deps };
 
+  // Per-provider availability-probe timeout. Configured in seconds (mirrors
+  // checkout_timeout_seconds); falls back to the shared default when
+  // unset/invalid. Build-based availability commands can raise this via
+  // `availability_timeout_seconds`.
+  const timeout = secondsToTimeoutMs(provider.availability_timeout_seconds);
+
   if (provider.availability_command) {
     return runCommandAvailabilityCheck({
       deps,
@@ -253,11 +266,18 @@ async function checkChatProviderAvailability(id, _deps) {
       displayCommand: 'availability command',
       shell: true,
       env: provider.env,
+      timeout,
     });
   }
 
-  // Pi delegates to existing AI provider availability
-  if (provider.type === 'pi') {
+  // Delegate to the AI provider's cached availability only for the built-in Pi
+  // chat provider with no command override — i.e. the same binary the AI
+  // provider already probed. The built-in `pi` definition intentionally omits
+  // `command` (PiBridge resolves its own default at runtime), so `!provider.command`
+  // cleanly distinguishes it. Custom `type: 'pi'` providers and built-in Pi
+  // overridden with a different `command` point at a different binary, so they
+  // fall through to the `<command> --version` probe below (which honors `timeout`).
+  if (provider.type === 'pi' && !provider.command) {
     const cached = getCachedAvailability('pi');
     return { available: cached?.available || false, error: cached?.error };
   }
@@ -278,6 +298,7 @@ async function checkChatProviderAvailability(id, _deps) {
     displayCommand: `${command} --version`,
     shell: useShell,
     env: provider.env,
+    timeout,
   });
 }
 
@@ -296,15 +317,15 @@ async function checkChatProviderAvailability(id, _deps) {
  * - `displayCommand` is used in error messages so user-configured shell strings
  *   do not need to be printed verbatim.
  *
- * @param {{deps: {spawn: Function}, command: string, args: string[], displayCommand: string, shell: boolean, env?: Object}} opts
+ * @param {{deps: {spawn: Function}, command: string, args: string[], displayCommand: string, shell: boolean, env?: Object, timeout?: number}} opts
  * @returns {Promise<{available: boolean, error?: string}>}
  */
-function runCommandAvailabilityCheck({ deps, command, args, displayCommand, shell, env }) {
+function runCommandAvailabilityCheck({ deps, command, args, displayCommand, shell, env, timeout = DEFAULT_AVAILABILITY_TIMEOUT_MS }) {
   return new Promise((resolve) => {
     try {
       const proc = deps.spawn(command, args, {
         stdio: ['ignore', 'ignore', 'ignore'],
-        timeout: 10000,
+        timeout,
         shell,
         env: { ...process.env, ...(env || {}) },
       });

package/src/councils/headless-council.js

@@ -0,0 +1,118 @@
+// 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 {Object} params.instructions - { globalInstructions, repoInstructions, requestInstructions }
+ *   (requestInstructions may be null)
+ * @param {Object} [params.githubClient] - GitHub client passed through to the analyzer
+ * @returns {Promise<Object>} The analyzer result ({ suggestions, summary, levelOutcomes, ... })
+ */
+async function runHeadlessCouncilAnalysis(db, params) {
+  const {
+    analyzer,
+    reviewId,
+    council,
+    configType,
+    councilConfig,
+    worktreePath,
+    prMetadata,
+    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,
+    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 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/local-review.js

@@ -13,6 +13,7 @@ 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 { startServer } = require('./server');
 const { localReviewDiffs } = require('./routes/shared');
 const summaryGenerator = require('./ai/summary-generator');
@@ -906,10 +907,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,9 +926,9 @@ 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';
+    if (councilSelection) url += `&council=${councilSelection.id}`;
     console.log(`\nOpening browser to: ${url}`);
     await open(url);