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

package/README.md

@@ -192,6 +192,8 @@ pair-review --local [path]
 | `<PR-URL>` | Full GitHub PR URL (e.g., `https://github.com/owner/repo/pull/123`) |
 | `--ai` | Automatically run AI analysis when the review loads |
 | `--ai-draft` | Run AI analysis and save suggestions as a draft review on GitHub |
+| `--council <handle>` | Run analysis with a saved multi-voice council. Implies analysis. The handle resolves by council name, name-slug, id (prefix), or a partial name fragment (resolving when it matches a single council, otherwise listing the candidates). When set, `--model` is ignored (council voices use their own per-voice models). Works in headless PR (`--ai-draft`/`--ai-review`), interactive PR (`--ai`), and local (`--local --ai`) modes. |
+| `--list-councils` | List saved councils with their handles, names, types, and last-used repo, then exit. Use a printed handle with `--council`. |
 | `--configure` | Show setup instructions and configuration options |
 | `-d`, `--debug` | Enable verbose debug logging for troubleshooting |
 | `-h`, `--help` | Show help message with full CLI documentation |
@@ -209,10 +211,20 @@ pair-review 123                        # Review PR #123 in current repo
 pair-review https://github.com/owner/repo/pull/456
 pair-review --local                    # Review uncommitted local changes
 pair-review 123 --ai                   # Auto-run AI analysis
+pair-review --list-councils            # List saved councils and their handles
+pair-review 123 --ai-draft --council security-review  # Headless draft with a council
+pair-review --local --ai --council security-review    # Local review with a council
 pair-review --register                 # Register pair-review:// URL scheme (macOS)
 pair-review --register --command "node bin/pair-review.js"  # Custom command
 ```
 
+> **Councils** are saved multi-voice review configurations created and managed
+> in the web UI (under Analysis settings). `--council <handle>` selects one from
+> the CLI; the handle can be the council's name, its name-slug, an id prefix, or
+> a partial name fragment (which resolves when it uniquely identifies a council,
+> otherwise lists the candidates). Run `pair-review --list-councils` to discover
+> available handles.
+
 ## Configuration
 
 On first run, pair-review will prompt you to configure the application.
@@ -395,6 +407,8 @@ You can override provider settings and define custom models in your config file.
 | `extra_args` | Additional arguments to pass to the CLI |
 | `env` | Environment variables to set when running the CLI |
 | `installInstructions` | Custom installation instructions shown in UI |
+| `availability_timeout_seconds` | Seconds to allow for the startup availability probe before the provider is reported unavailable (default `10`). Raise it for providers whose check runs a slow build/compile step. Also supported per chat provider under `chat_providers.<id>`. |
+| `availability_command` | Command run to decide availability. Executable providers default to always-available when omitted; chat providers fall back to `<command> --version` (or, for the built-in Pi, the cached AI-provider status). Pair with `availability_timeout_seconds` when the probe runs a slow build. |
 | `models` | Array of model definitions (see below) |
 
 #### Model Configuration Fields

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@in-the-loop-labs/pair-review",
-  "version": "3.7.2",
+  "version": "3.8.0",
   "description": "Your AI-powered code review partner - Close the feedback loop with AI coding agents",
   "main": "src/server.js",
   "bin": {

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pair-review",
-  "version": "3.7.2",
+  "version": "3.8.0",
   "description": "pair-review app integration — Open PRs and local changes in the pair-review web UI, run server-side AI analysis, and address review feedback. Requires the pair-review MCP server.",
   "author": {
     "name": "in-the-loop-labs",

package/plugin-code-critic/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "code-critic",
-  "version": "3.7.2",
+  "version": "3.8.0",
   "description": "AI-powered code review analysis — Run three-level AI analysis and implement-review-fix loops directly in your coding agent. Works standalone, no server required.",
   "author": {
     "name": "in-the-loop-labs",

package/public/js/local.js

@@ -86,6 +86,7 @@ class LocalManager {
       } finally {
         const cleanUrl = new URL(window.location);
         cleanUrl.searchParams.delete('analyze');
+        cleanUrl.searchParams.delete('council');
         history.replaceState(null, '', cleanUrl);
       }
     }

package/public/js/pr.js

@@ -638,6 +638,44 @@ class PRManager {
     const defaultTab = repoSettings?.default_tab || 'single';
     const councilId = repoSettings?.default_council_id || reviewSettings?.last_council_id || null;
 
+    // A `?council=<id>` URL param (set by the CLI when opening the browser) takes
+    // highest priority for council selection. When present we force the council
+    // branch regardless of default_tab/settings, and derive configType from the
+    // council's own type ('council' or 'advanced') rather than the repo default.
+    const urlSearch = (typeof window !== 'undefined' && window.location && window.location.search) || '';
+    const urlCouncilId = new URLSearchParams(urlSearch).get('council');
+    if (urlCouncilId) {
+      let councilConfig = null;
+      let councilName = null;
+      let councilType = null;
+      try {
+        const resp = await fetch(`/api/councils/${urlCouncilId}`);
+        if (resp.ok) {
+          const data = await resp.json();
+          councilConfig = data.council?.config || null;
+          councilName = data.council?.name || null;
+          councilType = data.council?.type || null;
+        } else {
+          console.warn(`Failed to fetch council "${urlCouncilId}" from URL param (status ${resp.status}); falling back to default analysis config`);
+        }
+      } catch (e) {
+        console.warn('Failed to fetch council config for URL council param:', e);
+      }
+
+      // Only honor the URL council if we successfully fetched its config.
+      // Otherwise fall through to the existing default-selection logic.
+      if (councilConfig) {
+        return {
+          isCouncil: true,
+          councilId: urlCouncilId,
+          councilConfig,
+          councilName,
+          configType: councilType || 'advanced',
+          customInstructions: null
+        };
+      }
+    }
+
     if ((defaultTab === 'council' || defaultTab === 'advanced') && councilId) {
       // Fetch the full council config so the progress modal can render correctly
       let councilConfig = null;
@@ -763,6 +801,7 @@ class PRManager {
           const cleanUrl = new URL(window.location);
           cleanUrl.searchParams.delete('analyze');
           cleanUrl.searchParams.delete('analysisConfigId');
+          cleanUrl.searchParams.delete('council');
           history.replaceState(null, '', cleanUrl);
         }
       }
@@ -3706,7 +3745,13 @@ class PRManager {
       // /file-content fetches) entirely when this body has none. The selector
       // mirrors the one validatePendingEofGaps scans for.
       if (entry.fileBody.querySelector('tr.context-expand-row[data-pending-eof-validation="true"]')) {
-        this.validatePendingEofGaps(entry.fileBody);
+        // Keep the in-flight promise on the entry. Until it resolves, the
+        // trailing EOF gap still carries EOF_SENTINEL coords, which makes
+        // findMatchingGap()'s overlap test unmatchable for a real target line.
+        // Line-anchoring callers (expandForSuggestion) await this so a
+        // suggestion/comment on a trailing unchanged line doesn't silently fail
+        // to expand. Fire-and-forget for everyone else.
+        entry.eofValidationPromise = this.validatePendingEofGaps(entry.fileBody);
       }
     }
 
@@ -4626,6 +4671,26 @@ class PRManager {
     // lazy body has rendered. Without this the gap query below returns nothing.
     await this.ensureFileBodyRendered(file);
 
+    // The trailing end-of-file gap is created with EOF_SENTINEL (-1) coords and
+    // resolved to real line numbers asynchronously by validatePendingEofGaps(),
+    // which _renderFileBodyNow fires fire-and-forget as the body renders. Until
+    // it settles the gap's NEW/OLD end is negative, so findMatchingGap()'s
+    // overlap test can never match a real target line — a suggestion (or
+    // comment, via ensureLinesVisible) on a trailing unchanged line silently
+    // fails to expand and never anchors. Pre-lazy-render this validation ran at
+    // renderDiff time, long before any suggestion was placed; lazy rendering
+    // collapsed that head start to nothing, which is the regression. Await the
+    // same in-flight promise (not a second /file-content fetch) so the EOF gap
+    // carries real coordinates before we match below.
+    const lazyEntry = this._lazyFileBodies?.get(fileElement.dataset?.fileName || file);
+    if (lazyEntry?.eofValidationPromise) {
+      try {
+        await lazyEntry.eofValidationPromise;
+      } catch {
+        // Validation removes the gap on fetch failure; matching simply misses.
+      }
+    }
+
     // Check if file is collapsed (generated files)
     if (fileElement.classList.contains('collapsed')) {
       debugLog?.('expandForSuggestion', 'File is collapsed, expanding first');
@@ -7069,22 +7134,42 @@ class PRManager {
   }
 
   /**
-   * Show an error when the worktree is not found during analysis.
-   * Displays a helpful message with a reload link. If the user arrived
-   * via auto-analyze (?analyze=true), the reload link preserves that
-   * parameter so analysis re-triggers after setup.
+   * Build the worktree-not-found recovery URL. When the user arrived via
+   * auto-analyze (?analyze=true), the reload link preserves the auto-analyze
+   * state so analysis re-triggers after worktree setup. Both the
+   * `analysisConfigId` and `council` params are carried through, since
+   * `_buildDefaultAnalysisConfig()` treats `?council=<id>` as the
+   * highest-priority analysis source — dropping it would silently fall back to
+   * the repo/default analysis configuration on retry.
    * @param {string} owner - Repository owner
    * @param {string} repo - Repository name
    * @param {number} number - PR number
+   * @returns {string} The recovery URL (unescaped)
    */
-  showWorktreeNotFoundError(owner, repo, number) {
+  _buildWorktreeRecoveryUrl(owner, repo, number) {
     let setupUrl = `/pr/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/${encodeURIComponent(number)}`;
     if (this._autoAnalyzeRequested) {
+      const currentParams = new URLSearchParams(window.location.search);
       const params = new URLSearchParams({ analyze: 'true' });
-      const analysisConfigId = new URLSearchParams(window.location.search).get('analysisConfigId');
+      const analysisConfigId = currentParams.get('analysisConfigId');
+      const councilId = currentParams.get('council');
       if (analysisConfigId) params.set('analysisConfigId', analysisConfigId);
+      if (councilId) params.set('council', councilId);
       setupUrl += `?${params.toString()}`;
     }
+    return setupUrl;
+  }
+
+  /**
+   * Show an error when the worktree is not found during analysis.
+   * Displays a helpful message with a reload link that preserves any
+   * auto-analyze state (see _buildWorktreeRecoveryUrl).
+   * @param {string} owner - Repository owner
+   * @param {string} repo - Repository name
+   * @param {number} number - PR number
+   */
+  showWorktreeNotFoundError(owner, repo, number) {
+    const setupUrl = this._buildWorktreeRecoveryUrl(owner, repo, number);
     const container = document.getElementById('pr-container');
     if (container) {
       container.innerHTML = `

package/public/setup.html

@@ -770,6 +770,10 @@
                         var qs = new URLSearchParams(window.location.search);
                         if (qs.get('analyze') === 'true') targetUrl.searchParams.set('analyze', qs.get('analyze'));
                         if (qs.get('analysisConfigId')) targetUrl.searchParams.set('analysisConfigId', qs.get('analysisConfigId'));
+                        // Forward the CLI-supplied council selection (PR & local cold-start
+                        // and delegated paths route through here); the review page keys
+                        // council auto-analysis on this param.
+                        if (qs.get('council')) targetUrl.searchParams.set('council', qs.get('council'));
                         window.location.href = targetUrl.toString();
                         return;
                     }
@@ -831,6 +835,10 @@
                                     var qs = new URLSearchParams(window.location.search);
                                     if (qs.get('analyze') === 'true') targetUrl.searchParams.set('analyze', qs.get('analyze'));
                                     if (qs.get('analysisConfigId')) targetUrl.searchParams.set('analysisConfigId', qs.get('analysisConfigId'));
+                                    // Forward the CLI-supplied council selection (PR & local cold-start
+                                    // and delegated paths route through here); the review page keys
+                                    // council auto-analysis on this param.
+                                    if (qs.get('council')) targetUrl.searchParams.set('council', qs.get('council'));
                                     window.location.href = targetUrl.toString();
                                 }
                             }, 400);

package/src/ai/claude-provider.js

@@ -858,9 +858,10 @@ class ClaudeProvider extends AIProvider {
    * Test if Claude CLI is available
    * Uses fast `--version` check instead of running a prompt.
    * Uses the command configured in the instance (respects ENV > config > default precedence)
+   * @param {number} [timeoutMs=10000] - Timeout in milliseconds for the probe
    * @returns {Promise<boolean>}
    */
-  async testAvailability() {
+  async testAvailability(timeoutMs = 10000) {
     return new Promise((resolve) => {
       // For availability test, we just need to check --version
       // Use the already-resolved command from the constructor (this.claudeCmd)
@@ -889,10 +890,10 @@ class ClaudeProvider extends AIProvider {
       const availabilityTimeout = setTimeout(() => {
         if (settled) return;
         settled = true;
-        logger.warn('Claude CLI availability check timed out after 10s');
+        logger.warn(`Claude CLI availability check timed out after ${Math.round(timeoutMs / 1000)}s`);
         try { claude.kill(); } catch { /* ignore */ }
         resolve(false);
-      }, 10000);
+      }, timeoutMs);
 
       claude.stdout.on('data', (data) => {
         stdout += data.toString();

package/src/ai/codex-provider.js

@@ -763,9 +763,10 @@ class CodexProvider extends AIProvider {
    * Test if Codex CLI is available
    * Uses fast `--version` check instead of running a prompt.
    * Uses the command configured in the instance (respects ENV > config > default precedence)
+   * @param {number} [timeoutMs=10000] - Timeout in milliseconds for the probe
    * @returns {Promise<boolean>}
    */
-  async testAvailability() {
+  async testAvailability(timeoutMs = 10000) {
     return new Promise((resolve) => {
       // For availability test, we just need to check --version
       // Use the already-resolved command from the constructor (this.codexCmd)
@@ -794,10 +795,10 @@ class CodexProvider extends AIProvider {
       const availabilityTimeout = setTimeout(() => {
         if (settled) return;
         settled = true;
-        logger.warn('Codex CLI availability check timed out after 10s');
+        logger.warn(`Codex CLI availability check timed out after ${Math.round(timeoutMs / 1000)}s`);
         try { codex.kill(); } catch { /* ignore */ }
         resolve(false);
-      }, 10000);
+      }, timeoutMs);
 
       codex.stdout.on('data', (data) => {
         stdout += data.toString();

package/src/ai/copilot-provider.js

@@ -439,9 +439,11 @@ class CopilotProvider extends AIProvider {
   /**
    * Test if Copilot CLI is available
    * Uses the command configured in the instance (respects ENV > config > default precedence)
+   * @param {number} [timeoutMs=10000] - Timeout in milliseconds for the probe.
+   *   Production passes the per-provider resolved value; the default is only hit by tests.
    * @returns {Promise<boolean>}
    */
-  async testAvailability() {
+  async testAvailability(timeoutMs = 10000) {
     return new Promise((resolve) => {
       // For availability test, check --version
       // Use the already-resolved command from the constructor (this.copilotCmd)
@@ -465,6 +467,16 @@ class CopilotProvider extends AIProvider {
       let stdout = '';
       let settled = false;
 
+      // Timeout guard: if the CLI hangs, kill it and resolve false so the probe
+      // does not leak a child process.
+      const availabilityTimeout = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        logger.warn(`Copilot CLI availability check timed out after ${Math.round(timeoutMs / 1000)}s`);
+        try { copilot.kill(); } catch { /* ignore */ }
+        resolve(false);
+      }, timeoutMs);
+
       copilot.stdout.on('data', (data) => {
         stdout += data.toString();
       });
@@ -472,6 +484,7 @@ class CopilotProvider extends AIProvider {
       copilot.on('close', (code) => {
         if (settled) return;
         settled = true;
+        clearTimeout(availabilityTimeout);
         // Copilot CLI typically outputs version info on success
         if (code === 0) {
           logger.info(`Copilot CLI available: ${stdout.trim()}`);
@@ -485,6 +498,7 @@ class CopilotProvider extends AIProvider {
       copilot.on('error', (error) => {
         if (settled) return;
         settled = true;
+        clearTimeout(availabilityTimeout);
         logger.warn(`Copilot CLI not available: ${error.message}`);
         resolve(false);
       });

package/src/ai/cursor-agent-provider.js

@@ -783,9 +783,10 @@ class CursorAgentProvider extends AIProvider {
   /**
    * Test if Cursor Agent CLI is available
    * Uses the command configured in the instance (respects ENV > config > default precedence)
+   * @param {number} [timeoutMs=10000] - Timeout in milliseconds for the probe
    * @returns {Promise<boolean>}
    */
-  async testAvailability() {
+  async testAvailability(timeoutMs = 10000) {
     return new Promise((resolve) => {
       // For availability test, we just need to check --version
       // Use the already-resolved command from the constructor (this.agentCmd)
@@ -813,10 +814,10 @@ class CursorAgentProvider extends AIProvider {
       const availabilityTimeout = setTimeout(() => {
         if (settled) return;
         settled = true;
-        logger.warn('Cursor Agent CLI availability check timed out after 10s');
+        logger.warn(`Cursor Agent CLI availability check timed out after ${Math.round(timeoutMs / 1000)}s`);
         try { agent.kill(); } catch { /* ignore */ }
         resolve(false);
-      }, 10000);
+      }, timeoutMs);
 
       agent.stdout.on('data', (data) => {
         stdout += data.toString();

package/src/ai/executable-provider.js

@@ -12,7 +12,7 @@
  */
 
 const providerModule = require('./provider');
-const { AIProvider, resolveDefaultModel, inferModelDefaults } = providerModule;
+const { AIProvider, resolveDefaultModel, inferModelDefaults, secondsToTimeoutMs } = providerModule;
 const { spawn } = require('child_process');
 const { glob } = require('glob');
 const fs = require('fs').promises;
@@ -136,6 +136,10 @@ function createExecutableProviderClass(id, config) {
       this.mappingInstructions = config.mapping_instructions || '';
       this.timeout = config.timeout || 600000; // Default 10 minutes
       this.availabilityCommand = config.availability_command || 'true';
+      // Availability-probe timeout. Configured in seconds (mirrors
+      // checkout_timeout_seconds); falls back to the shared default when
+      // unset/invalid.
+      this.availabilityTimeoutMs = secondsToTimeoutMs(config.availability_timeout_seconds);
       this.extraEnv = {
         ...(config.env || {}),
         ...(configOverrides.env || {}),
@@ -454,9 +458,13 @@ function createExecutableProviderClass(id, config) {
      * Test if the external tool is available.
      * Runs the configured availability_command (defaults to 'true', i.e. always available).
      *
+     * @param {number} [timeoutMs] - Timeout in milliseconds for the probe.
+     *   Defaults to the provider's configured availability_timeout_seconds
+     *   (or 10s). Tools with slow build-based availability commands can raise
+     *   this via `availability_timeout_seconds` in their provider config.
      * @returns {Promise<boolean>}
      */
-    async testAvailability() {
+    async testAvailability(timeoutMs = this.availabilityTimeoutMs) {
       return new Promise((resolve) => {
         const command = this.availabilityCommand;
         logger.debug(`${id} availability check: ${command}`);
@@ -471,10 +479,10 @@ function createExecutableProviderClass(id, config) {
         const availabilityTimeout = setTimeout(() => {
           if (settled) return;
           settled = true;
-          logger.warn(`${id} availability check timed out after 10s`);
+          logger.warn(`${id} availability check timed out after ${Math.round(timeoutMs / 1000)}s`);
           try { child.kill(); } catch { /* ignore */ }
           resolve(false);
-        }, 10000);
+        }, timeoutMs);
 
         child.on('close', (code) => {
           if (settled) return;

package/src/ai/gemini-provider.js

@@ -659,9 +659,11 @@ class GeminiProvider extends AIProvider {
   /**
    * Test if Gemini CLI is available
    * Uses the command configured in the instance (respects ENV > config > default precedence)
+   * @param {number} [timeoutMs=10000] - Timeout in milliseconds for the probe.
+   *   Production passes the per-provider resolved value; the default is only hit by tests.
    * @returns {Promise<boolean>}
    */
-  async testAvailability() {
+  async testAvailability(timeoutMs = 10000) {
     return new Promise((resolve) => {
       // For availability test, we just need to check --version
       // Use the already-resolved command from the constructor (this.geminiCmd)
@@ -685,6 +687,16 @@ class GeminiProvider extends AIProvider {
       let stdout = '';
       let settled = false;
 
+      // Timeout guard: if the CLI hangs, kill it and resolve false so the probe
+      // does not leak a child process.
+      const availabilityTimeout = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        logger.warn(`Gemini CLI availability check timed out after ${Math.round(timeoutMs / 1000)}s`);
+        try { gemini.kill(); } catch { /* ignore */ }
+        resolve(false);
+      }, timeoutMs);
+
       gemini.stdout.on('data', (data) => {
         stdout += data.toString();
       });
@@ -692,6 +704,7 @@ class GeminiProvider extends AIProvider {
       gemini.on('close', (code) => {
         if (settled) return;
         settled = true;
+        clearTimeout(availabilityTimeout);
         if (code === 0 && stdout.includes('.')) {
           logger.info(`Gemini CLI available: ${stdout.trim()}`);
           resolve(true);
@@ -704,6 +717,7 @@ class GeminiProvider extends AIProvider {
       gemini.on('error', (error) => {
         if (settled) return;
         settled = true;
+        clearTimeout(availabilityTimeout);
         logger.warn(`Gemini CLI not available: ${error.message}`);
         resolve(false);
       });

package/src/ai/index.js

@@ -17,6 +17,9 @@ const {
   getAllProvidersInfo,
   createProvider,
   testProviderAvailability,
+  resolveAvailabilityTimeoutMs,
+  secondsToTimeoutMs,
+  DEFAULT_AVAILABILITY_TIMEOUT_MS,
   applyConfigOverrides,
   getProviderConfigOverrides,
   inferModelDefaults,
@@ -69,6 +72,9 @@ module.exports = {
 
   // Utilities
   testProviderAvailability,
+  resolveAvailabilityTimeoutMs,
+  secondsToTimeoutMs,
+  DEFAULT_AVAILABILITY_TIMEOUT_MS,
 
   // Config override support
   applyConfigOverrides,

package/src/ai/opencode-provider.js

@@ -587,9 +587,11 @@ class OpenCodeProvider extends AIProvider {
   /**
    * Test if OpenCode CLI is available
    * Uses the command configured in the instance (respects ENV > config > default precedence)
+   * @param {number} [timeoutMs=10000] - Timeout in milliseconds for the probe.
+   *   Production passes the per-provider resolved value; the default is only hit by tests.
    * @returns {Promise<boolean>}
    */
-  async testAvailability() {
+  async testAvailability(timeoutMs = 10000) {
     return new Promise((resolve) => {
       // For availability test, we just need to check --version
       // Use the already-resolved command from the constructor (this.opencodeCmd)
@@ -613,6 +615,16 @@ class OpenCodeProvider extends AIProvider {
       let stdout = '';
       let settled = false;
 
+      // Timeout guard: if the CLI hangs, kill it and resolve false so the probe
+      // does not leak a child process.
+      const availabilityTimeout = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        logger.warn(`OpenCode CLI availability check timed out after ${Math.round(timeoutMs / 1000)}s`);
+        try { opencode.kill(); } catch { /* ignore */ }
+        resolve(false);
+      }, timeoutMs);
+
       opencode.stdout.on('data', (data) => {
         stdout += data.toString();
       });
@@ -620,6 +632,7 @@ class OpenCodeProvider extends AIProvider {
       opencode.on('close', (code) => {
         if (settled) return;
         settled = true;
+        clearTimeout(availabilityTimeout);
         if (code === 0) {
           logger.info(`OpenCode CLI available: ${stdout.trim()}`);
           resolve(true);
@@ -632,6 +645,7 @@ class OpenCodeProvider extends AIProvider {
       opencode.on('error', (error) => {
         if (settled) return;
         settled = true;
+        clearTimeout(availabilityTimeout);
         logger.warn(`OpenCode CLI not available: ${error.message}`);
         resolve(false);
       });

package/src/ai/pi-provider.js

@@ -1103,9 +1103,10 @@ class PiProvider extends AIProvider {
   /**
    * Test if Pi CLI is available
    * Uses the command configured in the instance (respects ENV > config > default precedence)
+   * @param {number} [timeoutMs=10000] - Timeout in milliseconds for the probe
    * @returns {Promise<boolean>}
    */
-  async testAvailability() {
+  async testAvailability(timeoutMs = 10000) {
     return new Promise((resolve) => {
       // For availability test, we just need to check --version
       // Use the already-resolved command from the constructor (this.piCmd)
@@ -1135,10 +1136,10 @@ class PiProvider extends AIProvider {
       const availabilityTimeout = setTimeout(() => {
         if (settled) return;
         settled = true;
-        logger.warn(`${name} CLI availability check timed out after 10s`);
+        logger.warn(`${name} CLI availability check timed out after ${Math.round(timeoutMs / 1000)}s`);
         try { pi.kill(); } catch { /* ignore */ }
         resolve(false);
-      }, 10000);
+      }, timeoutMs);
 
       pi.stdout.on('data', (data) => {
         stdout += data.toString();