@in-the-loop-labs/pair-review 3.7.2 → 3.9.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');
   }
 
@@ -166,7 +170,8 @@ class AIProvider {
    * @returns {string} Model ID for extraction
    */
   getFastTierModel() {
-    const models = this.constructor.getModels();
+    const overrides = providerConfigOverrides.get(this.constructor.getProviderId());
+    const models = applyModelOverrides(this.constructor.getModels(), overrides);
     const fastModel = models.find(m => m.tier === 'fast');
     if (fastModel) {
       return fastModel.id;
@@ -353,6 +358,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)
  */
@@ -420,17 +447,53 @@ function inferModelDefaults(model) {
 }
 
 /**
- * Resolve the default model from an array of model definitions
- * Priority: model with default:true > first balanced tier model > first model
- * @param {Array<Object>} models - Array of model definitions
+ * Match a model definition against a selector that may be the model's canonical
+ * id OR one of its aliases. Used by config-driven selectors (`default_model`,
+ * `disabled_models`, `models` overrides) so legacy config naming an alias (e.g.
+ * `opus`, an alias of the canonical `opus-4.8-xhigh`) keeps working.
+ *
+ * Optional-chaining is intentional: a model with no `aliases` short-circuits to
+ * undefined/falsy, so no Array.isArray guard is needed.
+ *
+ * @param {Object} model - Model definition (must have an `id`; may have `aliases`)
+ * @param {string} selector - Selector to match against id or aliases
+ * @returns {boolean}
+ */
+function modelMatches(model, selector) {
+  return model.id === selector || model.aliases?.includes(selector);
+}
+
+/**
+ * Resolve the default model from an array of model definitions.
+ * Priority: provider-level `default_model` (preferredId) > legacy model with
+ * `default:true` > first balanced tier model > first model.
+ *
+ * `preferredId` is the provider-level `default_model` config value. It is the
+ * preferred way to pick a default; the per-model `default:true` flag is the
+ * deprecated legacy mechanism, kept for backward compatibility. When
+ * `preferredId` names a model that isn't present (e.g. it was disabled or
+ * mistyped), resolution falls through to the legacy/automatic logic — the
+ * mismatch is warned about once at config-apply time, not here.
+ *
+ * @param {Array<Object>} models - Array of model definitions (already filtered)
+ * @param {string|null} [preferredId] - Provider-level `default_model` id
  * @returns {string|null} - Default model ID or null if no models
  */
-function resolveDefaultModel(models) {
+function resolveDefaultModel(models, preferredId = null) {
   if (!models || models.length === 0) {
     return null;
   }
 
-  // First, look for a model explicitly marked as default
+  // Provider-level `default_model` wins when it names an available model
+  // (by canonical id or alias). Returns the canonical id either way.
+  if (preferredId) {
+    const preferred = models.find(m => modelMatches(m, preferredId));
+    if (preferred) {
+      return preferred.id;
+    }
+  }
+
+  // Legacy: model explicitly marked default:true (deprecated in favor of default_model)
   const explicitDefault = models.find(m => m.default === true);
   if (explicitDefault) {
     return explicitDefault.id;
@@ -467,7 +530,7 @@ function createAliasedProviderClass(aliasId, BaseClass, aliasConfig) {
   AliasedProvider.getProviderId = () => aliasId;
   if (processedModels) {
     AliasedProvider.getModels = () => processedModels;
-    AliasedProvider.getDefaultModel = () => resolveDefaultModel(processedModels);
+    AliasedProvider.getDefaultModel = () => resolveDefaultModel(processedModels, aliasConfig.default_model || null);
   }
   if (aliasConfig.installInstructions) {
     AliasedProvider.getInstallInstructions = () => aliasConfig.installInstructions;
@@ -513,7 +576,15 @@ function applyConfigOverrides(config) {
       const { createExecutableProviderClass } = require('./executable-provider');
       const ExecClass = createExecutableProviderClass(providerId, providerConfig);
       registerProvider(providerId, ExecClass);
-      providerConfigOverrides.set(providerId, { ...providerConfig, models: ExecClass.getModels() });
+      const execDisabled = normalizeDisabledModels(providerId, providerConfig.disabled_models);
+      const execDefault = providerConfig.default_model || null;
+      validateModelSelectors(providerId, ExecClass.getModels(), null, execDisabled, execDefault);
+      providerConfigOverrides.set(providerId, {
+        ...providerConfig,
+        models: ExecClass.getModels(),
+        disabled_models: execDisabled,
+        default_model: execDefault
+      });
       logger.debug(`Registered executable provider: ${providerId}`);
       continue;
     }
@@ -524,6 +595,10 @@ function applyConfigOverrides(config) {
       const AliasClass = createAliasedProviderClass(providerId, BaseClass, providerConfig);
       registerProvider(providerId, AliasClass);
 
+      const aliasDisabled = normalizeDisabledModels(providerId, providerConfig.disabled_models);
+      const aliasDefault = providerConfig.default_model || null;
+      validateModelSelectors(providerId, AliasClass.getModels(), null, aliasDisabled, aliasDefault);
+
       // Aliases reuse the base provider's implementation class, not its config.
       // Only universal override fields are forwarded; provider-specific fields
       // (e.g. codex args) must be explicitly set in the alias config.
@@ -534,7 +609,10 @@ function applyConfigOverrides(config) {
         env: providerConfig.env,
         load_skills: providerConfig.load_skills,
         app_extensions: providerConfig.app_extensions,
-        models: AliasClass.getModels() !== BaseClass.getModels() ? AliasClass.getModels() : null
+        availability_timeout_seconds: providerConfig.availability_timeout_seconds,
+        models: AliasClass.getModels() !== BaseClass.getModels() ? AliasClass.getModels() : null,
+        disabled_models: aliasDisabled,
+        default_model: aliasDefault
       });
       logger.debug(`Registered aliased provider: ${providerId} (base: ${providerConfig.type})`);
       continue;
@@ -551,8 +629,36 @@ function applyConfigOverrides(config) {
     if (Array.isArray(providerConfig.models) && providerConfig.models.length > 0) {
       processedModels = providerConfig.models.map(inferModelDefaults);
       logger.debug(`Configured ${processedModels.length} models for ${providerId}`);
+      // Deprecation: per-model `default: true` is superseded by provider-level `default_model`.
+      // Only warn when the user didn't already adopt the new field.
+      if (providerConfig.default_model == null && processedModels.some(m => m.default === true)) {
+        logger.warn(`Provider "${providerId}": per-model "default: true" is deprecated. Set provider-level "default_model": "<id>" instead.`);
+      }
+    }
+
+    const builtInModels = providerRegistry.get(providerId)?.getModels();
+
+    // Canonicalize alias-keyed override ids to their built-in canonical id.
+    // A config entry may key a model by a short alias (e.g. `opus` for the
+    // canonical `opus-4.8-xhigh`). mergeModels() already resolves aliases for the
+    // display/metadata path, but the runtime path forwards this raw `models` array
+    // to the provider instance, where per-model config is looked up by EXACT id
+    // (e.g. `configOverrides.models.find(m => m.id === model)`). The frontend
+    // submits the canonical id, so an alias-keyed entry would never match and its
+    // cli_model/env/extra_args would be silently dropped. Rewriting the id here —
+    // the single point where the override is stored — keeps metadata and runtime
+    // execution in agreement.
+    if (processedModels && builtInModels) {
+      processedModels = processedModels.map(cm => {
+        const builtIn = builtInModels.find(bm => modelMatches(bm, cm.id));
+        return builtIn && builtIn.id !== cm.id ? { ...cm, id: builtIn.id } : cm;
+      });
     }
 
+    const disabledModels = normalizeDisabledModels(providerId, providerConfig.disabled_models);
+    const defaultModel = providerConfig.default_model || null;
+    validateModelSelectors(providerId, builtInModels, processedModels, disabledModels, defaultModel);
+
     // Store the overrides
     providerConfigOverrides.set(providerId, {
       command: providerConfig.command,
@@ -561,7 +667,10 @@ function applyConfigOverrides(config) {
       env: providerConfig.env,
       load_skills: providerConfig.load_skills,
       app_extensions: providerConfig.app_extensions,
-      models: processedModels
+      availability_timeout_seconds: providerConfig.availability_timeout_seconds,
+      models: processedModels,
+      disabled_models: disabledModels,
+      default_model: defaultModel
     });
   }
 
@@ -625,8 +734,12 @@ function resolveNonExecutableProviderId(preferredId) {
 
 /**
  * Merge config-override models with a provider's built-in models.
- * Config models with matching IDs replace built-ins; config models with new IDs
- * are appended. If no config models exist, returns built-ins unchanged.
+ * A config model whose id matches a built-in's canonical id OR one of its
+ * aliases replaces that built-in in place (preserving display order). The
+ * canonical built-in id is preserved as the internal source of truth, and the
+ * built-in's aliases are kept unless the override supplies its own. Config
+ * models that match no built-in are appended. If no config models exist,
+ * returns built-ins unchanged.
  *
  * @param {Array<Object>} builtInModels - Models from ProviderClass.getModels()
  * @param {Array<Object>|undefined} configModels - Models from config overrides
@@ -636,13 +749,114 @@ function mergeModels(builtInModels, configModels) {
   if (!configModels || configModels.length === 0) {
     return builtInModels;
   }
-  const configById = new Map(configModels.map(m => [m.id, m]));
-  // Replace overridden built-ins in-place to preserve display order
-  const merged = builtInModels.map(m => configById.get(m.id) || m);
-  // Append config models with new IDs not present in built-ins
-  const builtInIds = new Set(builtInModels.map(m => m.id));
-  const newModels = configModels.filter(m => !builtInIds.has(m.id));
-  return [...merged, ...newModels];
+  // Replace overridden built-ins in-place to preserve display order. An override
+  // matched by alias (e.g. config `{ id: 'opus' }` against built-in
+  // `opus-4.8-xhigh`) still replaces, but keeps the canonical built-in id.
+  const matched = new Set();
+  const merged = builtInModels.map(bm => {
+    const override = configModels.find(cm => modelMatches(bm, cm.id));
+    if (override) {
+      matched.add(override);
+      return { ...override, id: bm.id, aliases: override.aliases ?? bm.aliases };
+    }
+    return bm;
+  });
+  // Append config models that matched no built-in (genuinely new ids)
+  for (const cm of configModels) {
+    if (!matched.has(cm)) {
+      merged.push(cm);
+    }
+  }
+  return merged;
+}
+
+/**
+ * Compute the effective model list for a provider: built-in models merged with
+ * config-override models, then with any `disabled_models` IDs removed.
+ *
+ * This is the single source of truth for "which models does this provider
+ * actually expose" — every call site that surfaces or selects a model should go
+ * through here so a disabled model is hidden consistently (UI, default
+ * resolution, instance creation).
+ *
+ * If `disabled_models` would remove every model, the filter is ignored (a
+ * provider with zero models is unusable). Unknown/empty-list validation and
+ * warnings happen once at config-apply time in {@link applyConfigOverrides};
+ * this function is intentionally silent so it can run on every request.
+ *
+ * @param {Array<Object>} builtInModels - Models from ProviderClass.getModels()
+ * @param {Object} [overrides] - Stored config overrides for the provider
+ * @returns {Array<Object>} Effective model list
+ */
+function applyModelOverrides(builtInModels, overrides) {
+  const merged = mergeModels(builtInModels, overrides?.models);
+  const disabled = overrides?.disabled_models;
+  if (!Array.isArray(disabled) || disabled.length === 0) {
+    return merged;
+  }
+  // Drop a model if ANY disabled selector matches it by canonical id or alias.
+  const filtered = merged.filter(m => !disabled.some(d => modelMatches(m, d)));
+  // Never strip a provider down to zero models — fall back to the unfiltered set.
+  return filtered.length > 0 ? filtered : merged;
+}
+
+/**
+ * Normalize a `disabled_models` config value into a clean array of string IDs
+ * (or null when absent/empty). Warns on malformed input.
+ * @param {string} providerId - Provider ID (for log messages)
+ * @param {*} raw - Raw config value
+ * @returns {string[]|null}
+ */
+function normalizeDisabledModels(providerId, raw) {
+  if (raw == null) {
+    return null;
+  }
+  if (!Array.isArray(raw)) {
+    logger.warn(`Provider "${providerId}": "disabled_models" must be an array of model IDs; ignoring.`);
+    return null;
+  }
+  const ids = raw.filter(id => typeof id === 'string' && id.length > 0);
+  if (ids.length !== raw.length) {
+    logger.warn(`Provider "${providerId}": "disabled_models" contained non-string entries which were ignored.`);
+  }
+  return ids.length > 0 ? ids : null;
+}
+
+/**
+ * Validate provider-level model selectors against the effective model set and
+ * warn about mistakes. Never throws — bad selectors degrade gracefully at
+ * resolution time (a disabled-everything list is ignored, an unknown
+ * default_model falls back to automatic selection).
+ * @param {string} providerId - Provider ID (for log messages)
+ * @param {Array<Object>} builtInModels - Provider's built-in models
+ * @param {Array<Object>|null} configModels - Processed config-override models
+ * @param {string[]|null} disabledModels - Normalized disabled list
+ * @param {string|null} defaultModel - Provider-level default_model id
+ */
+function validateModelSelectors(providerId, builtInModels, configModels, disabledModels, defaultModel) {
+  const merged = mergeModels(builtInModels || [], configModels);
+  // A selector is "known" if it matches some model by canonical id OR alias.
+  const isKnown = (sel) => merged.some(m => modelMatches(m, sel));
+
+  if (disabledModels) {
+    for (const id of disabledModels) {
+      if (!isKnown(id)) {
+        logger.warn(`Provider "${providerId}": disabled_models references unknown model "${id}".`);
+      }
+    }
+    const remaining = merged.filter(m => !disabledModels.some(d => modelMatches(m, d)));
+    if (merged.length > 0 && remaining.length === 0) {
+      logger.warn(`Provider "${providerId}": disabled_models removes every model; the filter will be ignored.`);
+    }
+  }
+
+  if (defaultModel != null) {
+    if (!isKnown(defaultModel)) {
+      logger.warn(`Provider "${providerId}": default_model "${defaultModel}" is not a known model; falling back to automatic default.`);
+    } else if (disabledModels && disabledModels.includes(defaultModel)) {
+      logger.warn(`Provider "${providerId}": default_model "${defaultModel}" is also listed in disabled_models; falling back to automatic default.`);
+    }
+  }
 }
 
 /**
@@ -655,11 +869,17 @@ function getAllProvidersInfo() {
   for (const [id, ProviderClass] of providerRegistry) {
     const overrides = providerConfigOverrides.get(id);
 
-    // Merge config models with built-in models (config wins on ID collision)
-    const models = mergeModels(ProviderClass.getModels(), overrides?.models);
+    // Effective models: config merged with built-ins, minus disabled_models
+    const effectiveModels = applyModelOverrides(ProviderClass.getModels(), overrides);
 
-    // Resolve default model from merged models array
-    const defaultModel = resolveDefaultModel(models) || ProviderClass.getDefaultModel();
+    // Resolve default model: provider-level default_model wins, then legacy/auto
+    const defaultModel = resolveDefaultModel(effectiveModels, overrides?.default_model) || ProviderClass.getDefaultModel();
+
+    // Normalize per-model `default` flags to agree with the resolved defaultModel.
+    // Many frontend consumers derive the default via models.find(m => m.default),
+    // so the payload's flags must reflect the new source of truth (default_model).
+    // Produce NEW objects — never mutate the shared built-in model objects.
+    const models = effectiveModels.map(m => ({ ...m, default: m.id === defaultModel }));
 
     // Use overridden install instructions if available
     const installInstructions = overrides?.installInstructions || ProviderClass.getInstallInstructions();
@@ -708,11 +928,13 @@ function createProvider(providerId, model = null, overrides = {}) {
   // Determine the actual model to use
   let actualModel = model;
   if (!actualModel) {
-    // Resolve default from merged models (config + built-in).
+    // Resolve default from effective models (config + built-in, minus disabled).
     // Checks both sources because some providers (e.g., Pi) define built-in
-    // modes with default:true that aren't in config overrides.
+    // modes with default:true that aren't in config overrides. Honors the
+    // provider-level `default_model` selector.
     if (configOverrides?.models || ProviderClass.getModels().length > 0) {
-      actualModel = resolveDefaultModel(mergeModels(ProviderClass.getModels(), configOverrides?.models));
+      const effectiveModels = applyModelOverrides(ProviderClass.getModels(), configOverrides);
+      actualModel = resolveDefaultModel(effectiveModels, configOverrides?.default_model);
     }
     // Fall back to provider's built-in default
     if (!actualModel) {
@@ -724,27 +946,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.';
@@ -776,7 +1025,7 @@ function getTierForModel(providerId, modelId) {
   const overrides = providerConfigOverrides.get(providerId);
   const models = mergeModels(ProviderClass.getModels(), overrides?.models);
 
-  const model = models.find(m => m.id === modelId || m.aliases?.includes(modelId));
+  const model = models.find(m => modelMatches(m, modelId));
   return model?.tier || null;
 }
 
@@ -791,12 +1040,19 @@ module.exports = {
   getAllProvidersInfo,
   createProvider,
   testProviderAvailability,
+  resolveAvailabilityTimeoutMs,
+  secondsToTimeoutMs,
+  DEFAULT_AVAILABILITY_TIMEOUT_MS,
   // Config override support
   applyConfigOverrides,
   createAliasedProviderClass,
   getProviderConfigOverrides,
   inferModelDefaults,
   resolveDefaultModel,
+  modelMatches,
+  mergeModels,
+  applyModelOverrides,
+  normalizeDisabledModels,
   prettifyModelId,
   getTierForModel
 };

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 || {}) },
       });