ai-control-center 1.15.2

package/lib/utils/runner.js

@@ -0,0 +1,1809 @@
+import { spawn } from 'child_process';
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
+import { homedir, tmpdir } from 'os';
+import { resolve } from 'path';
+import { env, getPipelineStage, getOllamaConfig } from '../config.js';
+import { bus } from '../shared/event-bus.js';
+import { logActivityLine, logRawBlock } from './activity-log.js';
+import { trackUsage } from './cost-tracker.js';
+import { AITimeoutError, CircuitOpenError, ErrorCodes, ResponseValidationError } from './errors.js';
+import { atomicWriteSync, getRootDir, getWorkflowDir } from './pipeline.js';
+import { compressForStage } from './context-compressor.js';
+import { statusBar } from './status-bar.js';
+
+// ─── Default Timeouts Per Provider ────────────────────────────────────────────
+
+const DEFAULT_TIMEOUTS = {
+  gemini:  180_000,  // 180s
+  claude:  300_000,  // 300s
+  copilot: 600_000,  // 600s
+  ollama:  120_000,  // 120s
+};
+
+// ─── Token Limits Per Stage ───────────────────────────────────────────────────
+
+const TOKEN_LIMITS = {
+  pm:      4000,
+  explore: 2000,
+  arch:    6000,
+  impl:    8000,
+  review:  4000,
+  chat:    1000,
+};
+
+function getTokenLimit(stage) {
+  try {
+    const config = _modelsConfig();
+    if (config?.tokenLimits?.[stage]) return config.tokenLimits[stage];
+  } catch { /* */ }
+  return TOKEN_LIMITS[stage] || 8000;
+}
+
+// ─── Subprocess Timeout Wrapper ───────────────────────────────────────────────
+
+/**
+ * Run a command with an independent timeout watchdog.
+ * If timeout fires: SIGTERM → wait 5s → SIGKILL.
+ * Throws AITimeoutError on timeout.
+ *
+ * @param {string}   cmd        - Command to run
+ * @param {string[]} args       - Command arguments
+ * @param {object}   opts       - spawn options (cwd, env, shell, etc.)
+ * @param {number}   timeoutMs  - Timeout in milliseconds
+ * @param {string}   agent      - Agent label for logging (e.g. 'GEMINI')
+ * @returns {Promise<{stdout: string, stderr: string, code: number}>}
+ */
+export function runWithTimeout(cmd, args, opts, timeoutMs, agent = 'UNKNOWN') {
+  return new Promise((resolvePromise, reject) => {
+    const proc = spawn(cmd, args, {
+      cwd: opts.cwd || getRootDir(),
+      shell: opts.shell !== false,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: opts.env || process.env,
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let lastOutputTime = Date.now();
+
+    if (proc.stdout) proc.stdout.on('data', d => { stdout += d.toString(); lastOutputTime = Date.now(); });
+    if (proc.stderr) proc.stderr.on('data', d => { stderr += d.toString(); lastOutputTime = Date.now(); });
+
+    // Write stdin if provided
+    if (opts.stdin && proc.stdin) {
+      proc.stdin.write(opts.stdin);
+      proc.stdin.end();
+    } else if (proc.stdin) {
+      proc.stdin.end();
+    }
+
+    const settle = (fn, val) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        if (outputWatchdog) clearInterval(outputWatchdog);
+        fn(val);
+      }
+    };
+
+    // Main timeout watchdog
+    const timer = setTimeout(() => {
+      if (settled) return;
+      logActivityLine(agent, `TIMEOUT after ${Math.round(timeoutMs / 1000)}s — killing process`);
+      try { proc.kill('SIGTERM'); } catch { /* */ }
+      // Escalate to SIGKILL after 5s
+      setTimeout(() => {
+        try { proc.kill('SIGKILL'); } catch { /* already dead */ }
+      }, 5000);
+      settle(reject, new AITimeoutError(agent, timeoutMs, cmd));
+    }, timeoutMs);
+
+    // Gemini-specific output watchdog: kill if no output for 60s
+    const outputTimeoutMs = (agent === 'GEMINI')
+      ? (() => { try { return _modelsConfig()?.gemini?.outputTimeout || 60000; } catch { return 60000; } })()
+      : 0;
+    const outputWatchdog = outputTimeoutMs > 0
+      ? setInterval(() => {
+          if (settled) return;
+          if (Date.now() - lastOutputTime > outputTimeoutMs) {
+            logActivityLine(agent, `No output for ${Math.round(outputTimeoutMs / 1000)}s — process appears hung, killing`);
+            try { proc.kill('SIGTERM'); } catch { /* */ }
+            setTimeout(() => { try { proc.kill('SIGKILL'); } catch { /* */ } }, 5000);
+            settle(reject, new AITimeoutError(agent, timeoutMs, `${cmd} (output watchdog)`));
+          }
+        }, 5000)
+      : null;
+
+    proc.on('close', code => {
+      settle(resolvePromise, { stdout: stdout.trim(), stderr: stderr.trim(), code: code ?? 0 });
+    });
+    proc.on('error', err => settle(reject, err));
+  });
+}
+
+// ─── Circuit Breaker Per Provider ─────────────────────────────────────────────
+
+const CIRCUIT_STATES = { CLOSED: 'CLOSED', OPEN: 'OPEN', HALF_OPEN: 'HALF_OPEN' };
+const CIRCUIT_FAILURE_THRESHOLD = 3;
+const CIRCUIT_WINDOW_MS = 10 * 60 * 1000;  // 10 minutes
+const CIRCUIT_OPEN_DURATION_MS = 5 * 60 * 1000;  // 5 minutes
+const CIRCUIT_REOPEN_DURATION_MS = 10 * 60 * 1000;  // 10 minutes on second open
+
+class CircuitBreaker {
+  constructor() {
+    this._breakers = new Map();
+    this._loaded = false;
+  }
+
+  _filePath() {
+    try { return resolve(getWorkflowDir(), 'circuit-breakers.json'); }
+    catch { return null; }
+  }
+
+  _load() {
+    if (this._loaded) return;
+    this._loaded = true;
+    const fp = this._filePath();
+    if (!fp || !existsSync(fp)) return;
+    try {
+      const data = JSON.parse(readFileSync(fp, 'utf8'));
+      for (const [provider, state] of Object.entries(data)) {
+        this._breakers.set(provider, state);
+      }
+    } catch { /* non-fatal */ }
+  }
+
+  _persist() {
+    const fp = this._filePath();
+    if (!fp) return;
+    try {
+      const data = {};
+      for (const [provider, state] of this._breakers) data[provider] = state;
+      atomicWriteSync(fp, JSON.stringify(data, null, 2));
+    } catch { /* non-fatal */ }
+  }
+
+  _getState(provider) {
+    this._load();
+    if (!this._breakers.has(provider)) {
+      this._breakers.set(provider, {
+        state: CIRCUIT_STATES.CLOSED,
+        failures: [],
+        openedAt: null,
+        openDurationMs: CIRCUIT_OPEN_DURATION_MS,
+      });
+    }
+    return this._breakers.get(provider);
+  }
+
+  canExecute(provider) {
+    const cb = this._getState(provider);
+    if (cb.state === CIRCUIT_STATES.CLOSED) return true;
+    if (cb.state === CIRCUIT_STATES.OPEN) {
+      const elapsed = Date.now() - cb.openedAt;
+      if (elapsed >= cb.openDurationMs) {
+        cb.state = CIRCUIT_STATES.HALF_OPEN;
+        logActivityLine('SYSTEM', `Circuit breaker HALF_OPEN for ${provider} — testing with one request`);
+        this._persist();
+        return true;
+      }
+      return false;
+    }
+    // HALF_OPEN — allow one request
+    return true;
+  }
+
+  recordSuccess(provider) {
+    const cb = this._getState(provider);
+    cb.state = CIRCUIT_STATES.CLOSED;
+    cb.failures = [];
+    cb.openedAt = null;
+    cb.openDurationMs = CIRCUIT_OPEN_DURATION_MS;
+    this._persist();
+  }
+
+  recordFailure(provider) {
+    const cb = this._getState(provider);
+    const now = Date.now();
+
+    if (cb.state === CIRCUIT_STATES.HALF_OPEN) {
+      cb.state = CIRCUIT_STATES.OPEN;
+      cb.openedAt = now;
+      cb.openDurationMs = CIRCUIT_REOPEN_DURATION_MS;
+      logActivityLine('SYSTEM', `Circuit breaker re-OPEN for ${provider} (half-open test failed) — ${CIRCUIT_REOPEN_DURATION_MS / 60000}min cooldown`);
+      this._persist();
+      return;
+    }
+
+    // Prune old failures outside window
+    cb.failures = cb.failures.filter(t => now - t < CIRCUIT_WINDOW_MS);
+    cb.failures.push(now);
+
+    if (cb.failures.length >= CIRCUIT_FAILURE_THRESHOLD) {
+      cb.state = CIRCUIT_STATES.OPEN;
+      cb.openedAt = now;
+      cb.openDurationMs = CIRCUIT_OPEN_DURATION_MS;
+      logActivityLine('SYSTEM', `Circuit breaker OPEN for ${provider} — ${cb.failures.length} failures in ${CIRCUIT_WINDOW_MS / 60000}min — skipping for ${CIRCUIT_OPEN_DURATION_MS / 60000}min`);
+      this._persist();
+    }
+  }
+
+  getState(provider) {
+    const cb = this._getState(provider);
+    // Check if open circuit has expired
+    if (cb.state === CIRCUIT_STATES.OPEN && cb.openedAt) {
+      if (Date.now() - cb.openedAt >= cb.openDurationMs) {
+        cb.state = CIRCUIT_STATES.HALF_OPEN;
+      }
+    }
+    return {
+      state: cb.state,
+      failures: cb.failures.length,
+      openedAt: cb.openedAt ? new Date(cb.openedAt).toISOString() : null,
+    };
+  }
+}
+
+export const circuitBreaker = new CircuitBreaker();
+
+// ─── Response Validation ──────────────────────────────────────────────────────
+
+/**
+ * Validate an AI response for completeness and quality.
+ * Returns { valid: boolean, reason: string }
+ */
+export function validateResponse(stage, response) {
+  if (!response || response.trim().length < 100) {
+    return { valid: false, reason: 'Response too short (< 100 chars) — likely empty or error-only' };
+  }
+
+  if (stage === 'pm' || stage === 'spec') {
+    const hasUserStories = /user stor(y|ies)/i.test(response);
+    const hasAcceptance = /acceptance criteria/i.test(response);
+    if (!hasUserStories && !hasAcceptance) {
+      return { valid: false, reason: 'Missing expected PM sections (User Stories, Acceptance Criteria)' };
+    }
+  }
+
+  if (stage === 'review') {
+    const hasVerdict = /\b(PASS|FAIL|NEEDS.?CHANGES|APPROVED|REJECTED)\b/i.test(response);
+    if (!hasVerdict) {
+      return { valid: false, reason: 'Missing verdict section (PASS/FAIL/NEEDS_CHANGES)' };
+    }
+  }
+
+  return { valid: true, reason: 'ok' };
+}
+
+// ─── AI Usage Limit Detection ─────────────────────────────────────────────────
+//
+// Two distinct error classes require different responses:
+//
+//  RATELIMIT  — temporary (seconds/minutes). Fix: wait ~65 s, retry SAME model.
+//               Examples: HTTP 429, gRPC RESOURCE_EXHAUSTED, overloaded.
+//
+//  CAPACITY   — daily quota exhausted (hours). Fix: downgrade model immediately.
+//               Examples: "You have exhausted your capacity... reset after 20h53m"
+//
+// The system always starts with the best model in the chain and automatically
+// falls back to the next model when capacity is exhausted.
+
+// Patterns for TEMPORARY rate limits — wait + retry same model
+const RATELIMIT_PATTERNS = [
+  /(?<![\w:/])429(?!:\d)/,            // HTTP 429 — NOT :429:18 line numbers in stack traces
+  /too many requests/i,
+  /rate.{0,5}limit.{0,10}exceeded/i,
+  /rate_limit_error/i,                // Claude API error name
+  /overloaded_error/i,                // Claude API error name
+  /model.{0,15}overloaded/i,
+];
+
+// Patterns for CAPACITY EXHAUSTION — skip wait, downgrade model immediately
+const CAPACITY_PATTERNS = [
+  /no capacity available for model/i,  // Gemini: "No capacity available for model X on the server"
+  /MODEL_CAPACITY_EXHAUSTED/i,         // Gemini gRPC reason code
+  /RESOURCE_EXHAUSTED/i,               // Gemini/gRPC: model capacity or quota exhausted
+  /retryablequotaerror/i,              // Gemini CLI error class after internal retries exhausted
+  /max attempts reached/i,             // Gemini CLI: gave up internally — no point retrying ourselves
+  /exhausted your capacity/i,
+  /quota will reset after \d+h/i,      // "reset after 20h53m" — multi-hour reset
+  /quota[_ ]exceeded/i,
+  /quota has been exceeded/i,
+  /you.{0,10}(ve|have) exceeded/i,     // "You've exceeded your quota"
+  /usage limit reached/i,
+  /usage limit exceeded/i,
+  /daily (usage |quota )?limit/i,
+  /model.{0,15}capacity/i,             // "model capacity exhausted"
+  /you have no quota/i,                // Copilot: "402 You have no quota"
+  /402 .{0,20}no quota/i,              // Copilot: HTTP 402 no quota
+];
+
+/**
+ * Scan output for limit errors. Returns { type, line } or { type: null }.
+ *
+ * type = 'capacity'  → daily quota hit, downgrade model immediately
+ * type = 'ratelimit' → temporary rate limit, wait and retry same model
+ * type = null        → no limit error found
+ */
+function detectLimit(output) {
+  const lines = output.split('\n');
+  for (const line of lines) {
+    // Check capacity FIRST — it's the more specific / severe case
+    if (CAPACITY_PATTERNS.some(p => p.test(line))) return { type: 'capacity',   line: line.trim() };
+    if (RATELIMIT_PATTERNS.some(p => p.test(line))) return { type: 'ratelimit', line: line.trim() };
+  }
+  return { type: null, line: '' };
+}
+
+// ─── Model Availability Cache ────────────────────────────────────────────────
+//
+// In-memory cache of models that are known to be unavailable.
+// Populated when a run fails with a detected limit error.
+// Pre-flight check: isModelAvailable() is called BEFORE running any AI.
+//
+// TTLs:
+//   capacity  → 4 hours  (daily quota reset takes hours; skip completely)
+//   ratelimit → 90 seconds (short burst; by next attempt, usually clear)
+//
+// Persistence: bans are written to .ai-workflow/model-bans.json so a bot restart
+// doesn't immediately retry an exhausted model (e.g. Gemini 4h quota ban).
+//
+const _modelBans = new Map(); // model → { type, bannedAt, ttlMs }
+const CAPACITY_BAN_TTL  = 4 * 60 * 60 * 1000;  // 4 hours
+const RATELIMIT_BAN_TTL = 90 * 1000;             // 90 seconds
+
+// Lazy-load flag — bans are read from disk on the first call to banModel/isModelAvailable
+let _bansLoaded = false;
+
+function _getBansFilePath() {
+  try { return resolve(getWorkflowDir(), 'model-bans.json'); }
+  catch { return null; }
+}
+
+function _loadBansFromDisk() {
+  if (_bansLoaded) return;
+  _bansLoaded = true;
+  const filePath = _getBansFilePath();
+  if (!filePath || !existsSync(filePath)) return;
+  try {
+    const saved = JSON.parse(readFileSync(filePath, 'utf8'));
+    const now   = Date.now();
+    let   n     = 0;
+    for (const [model, ban] of Object.entries(saved)) {
+      if (now - ban.bannedAt < ban.ttlMs) { // skip expired
+        _modelBans.set(model, ban);
+        n++;
+      }
+    }
+    if (n > 0) logActivityLine('RUNNER', `Loaded ${n} persisted model ban(s) from disk`);
+  } catch { /* non-fatal — corrupt file */ }
+}
+
+function _persistBansToDisk() {
+  const filePath = _getBansFilePath();
+  if (!filePath) return;
+  try {
+    const plain = {};
+    for (const [model, ban] of _modelBans) plain[model] = ban;
+    atomicWriteSync(filePath, JSON.stringify(plain, null, 2));
+  } catch { /* non-fatal */ }
+}
+
+/**
+ * Mark a model as temporarily unavailable after a detected limit error.
+ * type = 'capacity' | 'ratelimit'
+ */
+export function banModel(model, type) {
+  _loadBansFromDisk(); // merge any persisted bans from previous session before writing
+  const ttlMs = type === 'capacity' ? CAPACITY_BAN_TTL : RATELIMIT_BAN_TTL;
+  _modelBans.set(model, { type, bannedAt: Date.now(), ttlMs });
+  const ttlLabel = type === 'capacity' ? '4h' : '90s';
+  logActivityLine('RUNNER', `Model ${model} marked unavailable (${type}) for ${ttlLabel}`);
+  _persistBansToDisk(); // write to disk so the ban survives a bot restart
+}
+
+/**
+ * Check if a model is currently available (not banned).
+ * Returns { available: true } or { available: false, reason, type }
+ */
+export function isModelAvailable(model) {
+  _loadBansFromDisk(); // ensure persisted bans from previous session are respected
+  const ban = _modelBans.get(model);
+  if (!ban) return { available: true };
+  if (Date.now() - ban.bannedAt >= ban.ttlMs) {
+    _modelBans.delete(model);
+    return { available: true };
+  }
+  const remaining = Math.ceil((ban.ttlMs - (Date.now() - ban.bannedAt)) / 1000);
+  const label = remaining >= 60 ? `${Math.ceil(remaining / 60)}m` : `${remaining}s`;
+  return {
+    available: false,
+    type: ban.type,
+    reason: `${model} is ${ban.type === 'capacity' ? 'quota-exhausted' : 'rate-limited'} (clears in ~${label})`,
+  };
+}
+
+/**
+ * Get a summary of all currently banned models (useful for /status or diagnostics).
+ */
+export function getBannedModels() {
+  const result = [];
+  for (const [model, ban] of _modelBans) {
+    const remaining = Math.ceil((ban.ttlMs - (Date.now() - ban.bannedAt)) / 1000);
+    if (remaining > 0) {
+      const label = remaining >= 60 ? `${Math.ceil(remaining / 60)}m` : `${remaining}s`;
+      result.push({ model, type: ban.type, clearsIn: label });
+    } else {
+      _modelBans.delete(model);
+    }
+  }
+  return result;
+}
+
+export class AILimitError extends Error {
+  constructor(agent, rawMessage) {
+    // Show the line that actually matched a pattern — not just the first line.
+    // Gemini CLI prefixes output with startup messages ("Loaded cached credentials.")
+    // that are unrelated to the actual error.
+    const { line } = detectLimit(rawMessage);
+    const display  = line
+      || rawMessage.split('\n').map(l => l.trim()).filter(Boolean)[0]
+      || rawMessage;
+    super(display.slice(0, 200));
+    this.name  = 'AILimitError';
+    this.agent = agent; // 'GEMINI' | 'CLAUDE' | 'COPILOT'
+  }
+}
+
+// ─── AI Model Configuration ────────────────────────────────────────────────────
+//
+// ─── Model Configuration ──────────────────────────────────────────────────────
+// Model chains are read from aicc.config.js → models section at runtime.
+// These defaults are used as fallbacks when config is not yet loaded
+// (e.g. during `aicc init` before a config file exists).
+//
+// ─── Pipeline-Driven Model Resolution ────────────────────────────────────────
+// All model selection is driven by the `pipeline[]` array in config.
+// Each stage has { provider, model, fallbacks }.
+// Env var overrides: GEMINI_MODEL, CLAUDE_MODEL, COPILOT_MODEL, OLLAMA_MODEL
+//
+// The internal model chain for each provider is built from all pipeline entries
+// that use that provider, so retry/fallback within a provider still works.
+
+const _DEFAULT_MODEL_CHAINS = {
+  gemini:  ['gemini-2.5-pro', 'gemini-2.5-flash'],
+  claude:  ['claude-sonnet-4-6', 'claude-haiku-4-5-20251001'],
+  copilot: ['claude-sonnet-4.6', 'claude-haiku-4.5'],
+};
+
+/** Read the pipeline array from config. */
+function _pipelineConfig() {
+  try { return getConfig().pipeline; } catch { return null; }
+}
+
+/** Backward compat: read old models config if pipeline not available. */
+function _modelsConfig() {
+  try { return getConfig().models; } catch { return null; }
+}
+
+/**
+ * Get the pipeline entry for a stage — the single source of truth.
+ * Returns { stage, provider, model, fallbacks }.
+ */
+function _getPipelineEntry(stage) {
+  try { return getPipelineStage(stage); }
+  catch { return { stage, provider: 'copilot', model: 'claude-sonnet-4.6', fallbacks: ['gemini:gemini-2.5-pro', 'ollama'] }; }
+}
+
+/**
+ * Build model chains per provider from pipeline entries.
+ * Collects all unique models used by each provider across all stages.
+ */
+function getConfiguredChains() {
+  const pipeline = _pipelineConfig();
+  if (pipeline) {
+    const chains = { gemini: [], claude: [], copilot: [] };
+    for (const entry of pipeline) {
+      if (chains[entry.provider] && !chains[entry.provider].includes(entry.model)) {
+        chains[entry.provider].push(entry.model);
+      }
+      // Also collect models from fallback entries
+      for (const fb of (entry.fallbacks || [])) {
+        const [prov, mod] = fb.includes(':') ? fb.split(':', 2) : [fb, null];
+        if (mod && chains[prov] && !chains[prov].includes(mod)) {
+          chains[prov].push(mod);
+        }
+      }
+    }
+    // Ensure at least one model per provider
+    return {
+      gemini:  chains.gemini.length  ? chains.gemini  : _DEFAULT_MODEL_CHAINS.gemini,
+      claude:  chains.claude.length  ? chains.claude  : _DEFAULT_MODEL_CHAINS.claude,
+      copilot: chains.copilot.length ? chains.copilot : _DEFAULT_MODEL_CHAINS.copilot,
+    };
+  }
+  // Backward compat: old models config
+  const m = _modelsConfig();
+  return {
+    gemini:  m?.geminiChain  || _DEFAULT_MODEL_CHAINS.gemini,
+    claude:  m?.claudeChain  || _DEFAULT_MODEL_CHAINS.claude,
+    copilot: m?.copilotChain || _DEFAULT_MODEL_CHAINS.copilot,
+  };
+}
+
+/** Get starting model for each provider: env var > pipeline primary > default. */
+function getStartModels() {
+  const chains = getConfiguredChains();
+  const ollamaCfg = (() => { try { return getOllamaConfig(); } catch { return { model: 'llama3.1' }; } })();
+  return {
+    gemini:  process.env.GEMINI_MODEL  || chains.gemini[0],
+    claude:  process.env.CLAUDE_MODEL  || chains.claude[0],
+    copilot: process.env.COPILOT_MODEL || chains.copilot[0],
+    ollama:  process.env.OLLAMA_MODEL  || ollamaCfg.model || 'llama3.1',
+  };
+}
+
+/** Get Ollama base URL: env var > config > default. */
+function getOllamaUrl() {
+  const ollamaCfg = (() => { try { return getOllamaConfig(); } catch { return {}; } })();
+  return process.env.OLLAMA_BASE_URL || ollamaCfg.baseUrl || 'http://localhost:11434';
+}
+
+/** Get the Copilot model for a given stage (from pipeline entry). */
+function getCrossAiCopilotModel() {
+  // Find the first non-implement, non-chat copilot entry
+  const pipeline = _pipelineConfig();
+  if (pipeline) {
+    const entry = pipeline.find(e => e.provider === 'copilot' && e.stage !== 'chat' && e.stage !== 'implement');
+    if (entry) return entry.model;
+  }
+  return _modelsConfig()?.copilotCrossAiModel || 'claude-sonnet-4.6';
+}
+const AI_MODE         = env('AI_MODE') || 'hybrid'; // hybrid | cloud | local
+
+// ─── OpenClaw Session Cache ───────────────────────────────────────────────────
+// Reuse a single session ID per process lifetime (~3.7s warm vs ~6.5s cold).
+// Also cache the isAvailable result so we don't spawn `which openclaw` per message.
+let _openclawSessionId = null;
+let _openclawAvailable = null;  // null = unchecked, true/false = cached
+
+function getOpenclawSessionId() {
+  if (!_openclawSessionId) _openclawSessionId = `aicc-chat-${Date.now()}`;
+  return _openclawSessionId;
+}
+
+// ─── Per-provider cooldown ──────────────────────────────────────────────────
+// Prevents rapid-fire calls to the same provider (e.g. review→fix→review in seconds).
+// Minimum gap between consecutive calls to the same provider.
+const PROVIDER_COOLDOWN_MS = 30_000; // 30 seconds between calls to same provider
+const _lastCallTime = new Map(); // provider → timestamp
+
+async function enforceProviderCooldown(provider) {
+  const last = _lastCallTime.get(provider);
+  if (last) {
+    const elapsed = Date.now() - last;
+    if (elapsed < PROVIDER_COOLDOWN_MS) {
+      const waitMs = PROVIDER_COOLDOWN_MS - elapsed;
+      logActivityLine(provider.toUpperCase(), `Cooldown: waiting ${(waitMs / 1000).toFixed(0)}s before next call...`);
+      await new Promise(r => setTimeout(r, waitMs));
+    }
+  }
+  _lastCallTime.set(provider, Date.now());
+}
+
+/**
+ * Return the model chain for `agent`, starting from the currently configured model.
+ * If the configured model is not in the chain (e.g. a custom env-var model),
+ * it is prepended so the chain always begins at the right point.
+ *
+ * Example: GEMINI_MODEL=gemini-2.5-pro → chain is ['gemini-2.5-pro', 'gemini-2.5-flash']
+ */
+function getModelChain(agent) {
+  const models = getStartModels();
+  const chains = getConfiguredChains();
+  const configured = models[agent];
+  const chain      = chains[agent] || [configured];
+  const startIdx   = chain.indexOf(configured);
+  return startIdx >= 0 ? chain.slice(startIdx) : [configured, ...chain];
+}
+
+/**
+ * Run a shell command streaming output to terminal.
+ * Pass options.label = 'CLAUDE'|'GEMINI'|'COPILOT' to prefix each output line.
+ */
+export function run(command, args = [], options = {}) {
+  return new Promise((resolvePromise, reject) => {
+    const useLabel = !!options.label;
+    const proc = spawn(command, args, {
+      cwd: options.cwd || getRootDir(),
+      shell: options.shell !== false,
+      stdio: useLabel ? ['inherit', 'pipe', 'pipe'] : 'inherit',
+      env: { ...process.env, ...options.env },
+    });
+
+    let settled = false;
+    const settle = (fn, val) => { if (!settled) { settled = true; fn(val); } };
+
+    // Timeout support — kills the process if it exceeds the limit
+    if (options.timeout) {
+      setTimeout(() => {
+        if (!settled) {
+          try { proc.kill('SIGTERM'); } catch { /* */ }
+          settle(reject, new Error(`Command timed out after ${options.timeout}ms`));
+        }
+      }, options.timeout);
+    }
+
+    if (useLabel) {
+      let buffer = '';
+      const flush = (chunk) => {
+        buffer += chunk;
+        const lines = buffer.split('\n');
+        buffer = lines.pop();
+        lines.forEach(line => logActivityLine(options.label, line));
+      };
+      if (proc.stdout) proc.stdout.on('data', d => flush(d.toString()));
+      if (proc.stderr) proc.stderr.on('data', d => flush(d.toString()));
+      proc.on('close', () => { if (buffer.trim()) logActivityLine(options.label, buffer); });
+    }
+
+    proc.on('close', code => {
+      if (code === 0 || options.ignoreExitCode) settle(resolvePromise, code);
+      else settle(reject, new Error(`Command failed with exit code ${code}`));
+    });
+    proc.on('error', e => settle(reject, e));
+  });
+}
+
+/**
+ * Run a shell command and capture output silently.
+ */
+export function capture(command, args = [], options = {}) {
+  return new Promise((resolvePromise) => {
+    const proc = spawn(command, args, {
+      cwd: options.cwd || getRootDir(),
+      shell: options.shell !== false,
+      env: { ...process.env, ...options.env },
+    });
+
+    let settled = false;
+    let stdout = '';
+    let stderr = '';
+    if (proc.stdout) proc.stdout.on('data', d => { stdout += d.toString(); });
+    if (proc.stderr) proc.stderr.on('data', d => { stderr += d.toString(); });
+
+    // Timeout support — kills the process and resolves with code -1
+    let timer;
+    if (options.timeout) {
+      timer = setTimeout(() => {
+        if (!settled) {
+          settled = true;
+          try { proc.kill('SIGTERM'); } catch { /* */ }
+          resolvePromise({ stdout: stdout.trim(), stderr: 'Timed out', code: -1 });
+        }
+      }, options.timeout);
+    }
+
+    proc.on('close', code => {
+      if (!settled) {
+        settled = true;
+        if (timer) clearTimeout(timer);
+        resolvePromise({ stdout: stdout.trim(), stderr: stderr.trim(), code });
+      }
+    });
+    proc.on('error', err => {
+      if (!settled) {
+        settled = true;
+        if (timer) clearTimeout(timer);
+        resolvePromise({ stdout: '', stderr: err.message, code: 1 });
+      }
+    });
+  });
+}
+
+/**
+ * Check if a CLI tool is installed.
+ * For 'ollama', checks HTTP availability instead of CLI binary.
+ */
+export async function isAvailable(tool) {
+  if (tool === 'ollama') {
+    const { available } = await isOllamaAvailable();
+    return available;
+  }
+  const result = await capture(`which ${tool}`);
+  return result.code === 0;
+}
+
+/**
+ * Run Claude Code in non-interactive (--print) mode.
+ *
+ * Auto-downgrade: on capacity exhaustion, tries the next model in MODEL_CHAINS.claude.
+ * On temporary 429 rate limits, throws AILimitError immediately (Claude sessions are
+ * stateful — retrying mid-session risks corrupting context).
+ *
+ * Session tracking modes — pick ONE:
+ *   featureId {string}       Per-feature conversation via --resume <sessionId>.
+ *   continueSession {bool}   Legacy: --continue (resumes whatever was last active).
+ */
+export async function runClaude(prompt, options = {}) {
+  // Circuit breaker check
+  if (!circuitBreaker.canExecute('claude')) {
+    logActivityLine('SYSTEM', `Circuit breaker OPEN for Claude — skipping to fallback`);
+    throw new AILimitError('CLAUDE', 'Circuit breaker OPEN for Claude');
+  }
+
+  await enforceProviderCooldown('claude');
+  const estimatedTokens = Math.ceil(prompt.length / 4);
+  const shortTask = prompt.replace(/\n/g, ' ').trim().slice(0, 55);
+
+  const sessionsDir = resolve(getWorkflowDir(), 'sessions');
+  if (!existsSync(sessionsDir)) mkdirSync(sessionsDir, { recursive: true });
+
+  // Compress context if stage info is available
+  let processedPrompt = prompt;
+  if (options.stage && options.featureId) {
+    try {
+      processedPrompt = compressForStage(options.stage, options.featureId, prompt);
+      const originalLen = prompt.length;
+      const compressedLen = processedPrompt.length;
+      if (compressedLen < originalLen) {
+        const reduction = Math.round((1 - compressedLen / originalLen) * 100);
+        logActivityLine('SYSTEM', `Context compressed: ${originalLen} → ${compressedLen} chars (${reduction}% reduction)`);
+      }
+    } catch (e) {
+      processedPrompt = prompt;
+    }
+  }
+
+  const tmpFile = resolve(tmpdir(), `aicc-claude-${Date.now()}.txt`);
+  writeFileSync(tmpFile, processedPrompt, 'utf8');
+
+  // failFast: try primary model once with a 60s timeout — caller falls back immediately on failure
+  const fullChain  = getModelChain('claude');
+  const modelChain = options.failFast ? fullChain.slice(0, 1) : fullChain;
+  const claudeTimeout = options.failFast ? 60000 : undefined;
+  const exhaustedMsgs = [];
+  const _costStart = Date.now();
+
+  for (const model of modelChain) {
+    // ── Pre-flight: skip models known to be unavailable ────────────────────────
+    const avail = isModelAvailable(model);
+    if (!avail.available) {
+      logActivityLine('CLAUDE', `Skipping ${model} — ${avail.reason}`);
+      exhaustedMsgs.push(avail.reason);
+      continue;
+    }
+
+    statusBar.set('CLAUDE', shortTask, estimatedTokens);
+    if (model !== modelChain[0]) {
+      logActivityLine('CLAUDE', `Trying fallback model: ${model}`);
+    }
+
+    // ── Feature-ID session: --resume keeps Claude in the same conversation ────
+    if (options.featureId) {
+      const sessionFile = resolve(sessionsDir, `CLAUDE-${options.featureId}.json`);
+      const flags = ['--model', model, '--print', '--output-format', 'json', '--dangerously-skip-permissions'];
+
+      if (existsSync(sessionFile)) {
+        try {
+          const { sessionId } = JSON.parse(readFileSync(sessionFile, 'utf8'));
+          if (sessionId) flags.push('--resume', sessionId);
+        } catch { /* corrupt session file — start fresh */ }
+      }
+
+      try {
+        const result = await capture(
+          `cat "${tmpFile}" | claude ${flags.join(' ')}`,
+          [], { shell: true, timeout: claudeTimeout }
+        );
+
+        // Treat timeout (code -1) as a hard failure when failFast
+        if (result.code === -1 && options.failFast) {
+          logActivityLine('CLAUDE', `Claude timed out (60s) — falling back to Copilot`);
+          throw new Error('Claude timed out');
+        }
+
+        const combinedOutput = result.stdout + '\n' + result.stderr;
+        const { type, line } = detectLimit(combinedOutput);
+
+        if (type === 'capacity') {
+          banModel(model, 'capacity');
+          exhaustedMsgs.push(`${model}: ${line}`);
+          logActivityLine('CLAUDE', `Model ${model} quota exhausted — trying next model`);
+          continue; // try next model
+        }
+        if (type === 'ratelimit') {
+          banModel(model, 'ratelimit');
+          throw new AILimitError('CLAUDE', combinedOutput); // surface immediately
+        }
+
+        try {
+          const json = JSON.parse(result.stdout);
+          if (json.session_id) {
+            writeFileSync(sessionFile,
+              JSON.stringify({ sessionId: json.session_id, featureId: options.featureId }, null, 2)
+            );
+          }
+          const text = json.result || json.content || '';
+          text.split('\n').forEach(l => logActivityLine('CLAUDE', l));
+        } catch (e) {
+          if (e instanceof AILimitError) throw e;
+          result.stdout.split('\n').forEach(l => logActivityLine('CLAUDE', l));
+        }
+
+        if (model !== getStartModels().claude) {
+          logActivityLine('CLAUDE', `Task completed using fallback model: ${model}`);
+        }
+        circuitBreaker.recordSuccess('claude');
+        trackUsage({ provider: 'claude', model, stage: options.stage, featureId: options.featureId, promptText: prompt, responseText: result.stdout || '', durationMs: Date.now() - _costStart });
+        return result.code;
+      } finally {
+        statusBar.clear();
+      }
+    }
+
+    // ── Legacy: no featureId → stream output, optional --continue ─────────────
+    const flags = ['--model', model, '--print', '--output-format', 'text', '--dangerously-skip-permissions'];
+    if (options.continueSession) flags.push('--continue');
+
+    try {
+      const code = await run(
+        `cat "${tmpFile}" | claude ${flags.join(' ')}`,
+        [], { shell: true, label: 'CLAUDE', ignoreExitCode: options.ignoreExitCode, timeout: claudeTimeout }
+      );
+      if (model !== getStartModels().claude) {
+        logActivityLine('CLAUDE', `Task completed using fallback model: ${model}`);
+      }
+      circuitBreaker.recordSuccess('claude');
+      trackUsage({ provider: 'claude', model, stage: options.stage, featureId: options.featureId, promptText: prompt, durationMs: Date.now() - _costStart });
+      return code;
+    } catch (e) {
+      // run() rejects on non-zero exit — re-throw non-limit errors
+      throw e;
+    } finally {
+      statusBar.clear();
+    }
+  }
+
+  // All models exhausted
+  const detail = exhaustedMsgs.map(m => `\n    ${m}`).join('');
+  throw new AILimitError('CLAUDE', `All models exhausted:${detail}`);
+}
+
+/**
+ * Run Gemini CLI with a prompt string. Writes the response to outputFile.
+ *
+ * Model auto-downgrade strategy:
+ *  - Capacity exhausted ("reset after 20h") → try next model in chain immediately
+ *  - Rate limit 429 → wait RETRY_WAIT_S seconds, retry SAME model (up to MAX_RETRIES)
+ *  - After MAX_RETRIES on same model with 429 → try next model in chain
+ *  - All models exhausted → throw AILimitError
+ *
+ * @param {string} prompt     - Full task description (may reference file paths)
+ * @param {string} outputFile - Path where Gemini's response will be written
+ */
+export async function runGemini(prompt, outputFile, options = {}) {
+  // Circuit breaker check
+  if (!circuitBreaker.canExecute('gemini')) {
+    logActivityLine('SYSTEM', `Circuit breaker OPEN for Gemini — skipping to fallback`);
+    throw new AILimitError('GEMINI', 'Circuit breaker OPEN for Gemini');
+  }
+
+  await enforceProviderCooldown('gemini');
+  // failFast: try once with primary model only — caller handles fallback immediately
+  const MAX_RETRIES  = options.failFast ? 1 : 2;
+  const RETRY_WAIT_S = 30;
+
+  // Compress context if stage info is available
+  let processedPrompt = prompt;
+  if (options.stage && options.featureId) {
+    try {
+      processedPrompt = compressForStage(options.stage, options.featureId, prompt);
+      const originalLen = prompt.length;
+      const compressedLen = processedPrompt.length;
+      if (compressedLen < originalLen) {
+        const reduction = Math.round((1 - compressedLen / originalLen) * 100);
+        logActivityLine('SYSTEM', `Context compressed: ${originalLen} → ${compressedLen} chars (${reduction}% reduction)`);
+      }
+    } catch (e) {
+      processedPrompt = prompt;
+    }
+  }
+
+  const promptFile = resolve(tmpdir(), `aicc-gemini-${Date.now()}.txt`);
+  writeFileSync(promptFile, processedPrompt, 'utf8');
+
+  const estimatedTokens = Math.ceil(processedPrompt.length / 4);
+  const shortTask = prompt.split('\n').find(l => l.trim())?.trim().slice(0, 55) || 'Gemini task';
+  const stderrFile = `${outputFile}.stderr`;
+
+  // failFast: only try primary model; otherwise try full chain
+  // options.modelChain: stage-specific override (e.g. PM uses flash-lite, review uses pro first)
+  const fullChain  = options.modelChain || getModelChain('gemini');
+  const modelChain = options.failFast ? fullChain.slice(0, 1) : fullChain;
+  const exhaustedMsgs = [];
+  const _costStart = Date.now();
+
+  for (const model of modelChain) {
+    // ── Pre-flight: skip models known to be unavailable ────────────────────────
+    const avail = isModelAvailable(model);
+    if (!avail.available) {
+      logActivityLine('GEMINI', `Skipping ${model} — ${avail.reason}`);
+      exhaustedMsgs.push(avail.reason);
+      continue;
+    }
+
+    if (model !== modelChain[0]) {
+      logActivityLine('GEMINI', `Trying fallback model: ${model}`);
+    }
+
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+      statusBar.set('GEMINI', `[${model}] ${shortTask}`, estimatedTokens);
+
+      try {
+        // Strip ALL IDE-related env vars so Gemini CLI never tries to connect to VS Code.
+        // Fixes: "[IDEClient] Directory mismatch" when running from a different project
+        // than the one open in the IDE (e.g. PickleBall bot triggering review while
+        // VS Code has XConnector open).
+        const IDE_PREFIXES = ['GEMINI_CLI_IDE_', 'VSCODE_', 'GIT_ASKPASS', 'GIT_TERMINAL_PROMPT'];
+        const IDE_EXACT    = new Set(['TERM_PROGRAM', 'TERM_PROGRAM_VERSION']);
+        const cleanEnv = {};
+        for (const [k, v] of Object.entries(process.env)) {
+          if (IDE_PREFIXES.some(p => k.startsWith(p))) continue;
+          if (IDE_EXACT.has(k)) continue;
+          cleanEnv[k] = v;
+        }
+
+        // --yolo: auto-approve all tool calls (file reads, git commands) so Gemini
+        // doesn't block waiting for confirmations in non-interactive mode.
+        // cwd: run from the git repo root so Gemini's built-in git tools see the
+        // correct repository (config root is often a monorepo parent with no .git).
+        const runCwd = options.cwd || getRootDir();
+        const maxTokens = getTokenLimit(options.stage || 'impl');
+        await run(
+          `cat "${promptFile}" | gemini --yolo -m ${model} > "${outputFile}" 2> "${stderrFile}"`,
+          [], { shell: true, label: 'GEMINI', ignoreExitCode: true,
+                timeout: options.failFast ? 60000 : DEFAULT_TIMEOUTS.gemini, env: cleanEnv, cwd: runCwd }
+        );
+
+        // Check stderr for limit errors
+        if (existsSync(stderrFile)) {
+          try {
+            const errText = readFileSync(stderrFile, 'utf8').trim();
+            if (errText) {
+              logRawBlock('GEMINI', 'Gemini CLI stderr', errText);
+              const { type, line } = detectLimit(errText);
+
+              if (type === 'capacity') {
+                // Daily quota hit — ban this model, skip remaining retries, try next model
+                banModel(model, 'capacity');
+                exhaustedMsgs.push(`${model}: ${line}`);
+                logActivityLine('GEMINI', `Model ${model} quota exhausted (may reset in hours) — trying next model`);
+                try { if (existsSync(outputFile)) unlinkSync(outputFile); } catch { /* non-fatal */ }
+                break; // exit attempt loop → outer model loop continues
+              }
+
+              if (type === 'ratelimit') {
+                if (attempt < MAX_RETRIES) {
+                  // Temporary rate limit — wait and retry same model
+                  banModel(model, 'ratelimit');
+                  logActivityLine('GEMINI', `Rate limit hit (attempt ${attempt}/${MAX_RETRIES}) — waiting ${RETRY_WAIT_S}s...`);
+                  statusBar.set('GEMINI', `Rate limited — retry ${attempt + 1}/${MAX_RETRIES} in ${RETRY_WAIT_S}s`, 0);
+                  await new Promise(r => setTimeout(r, RETRY_WAIT_S * 1000));
+                  try { if (existsSync(outputFile)) unlinkSync(outputFile); } catch { /* non-fatal */ }
+                  try { if (existsSync(stderrFile)) unlinkSync(stderrFile); } catch { /* non-fatal */ }
+                  continue; // next attempt, same model
+                }
+                // MAX_RETRIES exhausted on this model — try next model
+                banModel(model, 'ratelimit');
+                exhaustedMsgs.push(`${model}: ${line} (after ${MAX_RETRIES} retries)`);
+                logActivityLine('GEMINI', `Max retries reached for ${model} — trying next model`);
+                try { if (existsSync(outputFile)) unlinkSync(outputFile); } catch { /* non-fatal */ }
+                break; // exit attempt loop → outer model loop continues
+              }
+            }
+          } catch (e) {
+            if (e instanceof AILimitError) throw e;
+            /* other read errors are non-fatal */
+          }
+        }
+
+        // No limit error — validate and log the response
+        // NOTE: Do NOT run detectLimit() on outputFile content — review text may
+        // legitimately mention "rate_limit", "quota_exceeded", etc. when reviewing
+        // code that handles those topics (e.g. XConn_RateLimiter).
+        if (existsSync(outputFile)) {
+          try {
+            const out = readFileSync(outputFile, 'utf8');
+            if (out.trim()) logRawBlock('GEMINI', 'Full Gemini Response', out);
+
+            // Validate response quality
+            const validation = validateResponse(options.stage, out);
+            if (!validation.valid) {
+              logActivityLine('GEMINI', `Response validation failed: ${validation.reason} — falling back to next model`);
+              circuitBreaker.recordFailure('gemini');
+              try { unlinkSync(outputFile); } catch { /* */ }
+              break; // exit attempt loop, try next model
+            }
+          } catch { /* non-fatal */ }
+        }
+
+        if (model !== getStartModels().gemini) {
+          logActivityLine('GEMINI', `Task completed using fallback model: ${model}`);
+        }
+
+        // Clean up temp files
+        circuitBreaker.recordSuccess('gemini');
+        try { if (existsSync(stderrFile))  unlinkSync(stderrFile);  } catch { /* non-fatal */ }
+        try { if (existsSync(promptFile))  unlinkSync(promptFile);  } catch { /* non-fatal */ }
+        try { trackUsage({ provider: 'gemini', model, stage: options.stage, featureId: options.featureId, promptText: prompt, responseText: existsSync(outputFile) ? readFileSync(outputFile, 'utf8') : '', durationMs: Date.now() - _costStart, maxTokens: getTokenLimit(options.stage || 'impl') }); } catch { /* non-fatal */ }
+        statusBar.clear();
+        return; // success
+
+      } finally {
+        statusBar.clear();
+      }
+    } // end attempt loop
+  } // end model loop
+
+  // All models in chain exhausted
+  try { if (existsSync(promptFile)) unlinkSync(promptFile); } catch { /* non-fatal */ }
+
+  const detail = exhaustedMsgs.map(m => `\n    ${m}`).join('');
+  const hint   = `\nSet GEMINI_MODEL=gemini-2.5-flash to skip Pro models.`;
+  throw new AILimitError('GEMINI', `All models exhausted:${detail}${hint}`);
+}
+
+/**
+ * Sync ~/.copilot/config.json model to match the given model name.
+ * Copilot CLI rejects non-interactive calls if --model differs from the saved config model.
+ */
+function syncCopilotConfigModel(model) {
+  const configPath = resolve(homedir(), '.copilot', 'config.json');
+  if (!existsSync(configPath)) return;
+  try {
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    if (config.model !== model) {
+      config.model = model;
+      writeFileSync(configPath, JSON.stringify(config, null, 4), 'utf8');
+      logActivityLine('COPILOT', `Config model updated → ${model}`);
+    }
+  } catch { /* non-fatal — Copilot will fall back to its default */ }
+}
+
+/**
+ * Run GitHub Copilot CLI in non-interactive (-p) mode.
+ *
+ * Auto-downgrade: on capacity exhaustion, tries the next model in MODEL_CHAINS.copilot.
+ * Session tracking: each featureId maps to a deterministic UUID via MD5 hash.
+ *
+ * @param {string} prompt       - Full task description for Copilot
+ * @param {object} options
+ *   featureId       {string}  - Feature ID for session tracking
+ *   ignoreExitCode  {bool}    - Don't reject on non-zero exit
+ */
+export async function runCopilot(prompt, options = {}) {
+  // Circuit breaker check
+  if (!circuitBreaker.canExecute('copilot')) {
+    logActivityLine('SYSTEM', `Circuit breaker OPEN for Copilot — skipping to fallback`);
+    throw new AILimitError('COPILOT', 'Circuit breaker OPEN for Copilot');
+  }
+
+  await enforceProviderCooldown('copilot');
+  const estimatedTokens = Math.ceil(prompt.length / 4);
+  const shortTask = prompt.replace(/\n/g, ' ').trim().slice(0, 55);
+
+  // Compress context if stage info is available
+  let processedPrompt = prompt;
+  if (options.stage && options.featureId) {
+    try {
+      processedPrompt = compressForStage(options.stage, options.featureId, prompt);
+      const originalLen = prompt.length;
+      const compressedLen = processedPrompt.length;
+      if (compressedLen < originalLen) {
+        const reduction = Math.round((1 - compressedLen / originalLen) * 100);
+        logActivityLine('SYSTEM', `Context compressed: ${originalLen} → ${compressedLen} chars (${reduction}% reduction)`);
+      }
+    } catch (e) {
+      processedPrompt = prompt;
+    }
+  }
+
+  const tmpFile = resolve(tmpdir(), `aicc-copilot-${Date.now()}.txt`);
+  writeFileSync(tmpFile, processedPrompt, 'utf8');
+
+  // Build session UUID once (same for all model attempts — same conversation)
+  let sessionUUID = null;
+  if (options.featureId) {
+    const sessionsDir = resolve(getWorkflowDir(), 'sessions');
+    if (!existsSync(sessionsDir)) mkdirSync(sessionsDir, { recursive: true });
+
+    const sessionFile = resolve(sessionsDir, `COPILOT-${options.featureId}.json`);
+    if (existsSync(sessionFile)) {
+      try {
+        const saved = JSON.parse(readFileSync(sessionFile, 'utf8'));
+        sessionUUID = saved.sessionId;
+      } catch { /* corrupt file — regenerate */ }
+    }
+    if (!sessionUUID) {
+      sessionUUID = featureToSessionUUID(options.featureId);
+      writeFileSync(sessionFile, JSON.stringify({
+        sessionId: sessionUUID, featureId: options.featureId, createdAt: new Date().toISOString(),
+      }, null, 2));
+      logActivityLine('COPILOT', `New session → sessions/COPILOT-${options.featureId}.json`);
+    } else {
+      logActivityLine('COPILOT', `Resuming session ${sessionUUID}`);
+    }
+  }
+
+  const modelChain    = options._forceModel ? [options._forceModel] : getModelChain('copilot');
+  const exhaustedMsgs = [];
+  const _costStart = Date.now();
+
+  for (const model of modelChain) {
+    // ── Pre-flight: skip models known to be unavailable ────────────────────────
+    const avail = isModelAvailable(model);
+    if (!avail.available) {
+      logActivityLine('COPILOT', `Skipping ${model} — ${avail.reason}`);
+      exhaustedMsgs.push(avail.reason);
+      continue;
+    }
+
+    syncCopilotConfigModel(model);
+    statusBar.set('COPILOT', shortTask, estimatedTokens);
+
+    if (model !== modelChain[0]) {
+      logActivityLine('COPILOT', `Trying fallback model: ${model}`);
+    }
+
+    const flags = ['--model', model, '--yolo'];
+    if (sessionUUID) flags.push('--resume', sessionUUID);
+
+    try {
+      const result = await new Promise((resolvePromise, reject) => {
+        const args = ['-p', processedPrompt, ...flags];
+        const proc = spawn('copilot', args, {
+          cwd:   getRootDir(),
+          shell: false,
+          stdio: ['ignore', 'pipe', 'pipe'],
+          env:   { ...process.env },
+        });
+
+        let buffer = '';
+        let allOutput = '';
+        const flush = (chunk) => {
+          buffer += chunk;
+          allOutput += chunk;
+          const lines = buffer.split('\n');
+          buffer = lines.pop();
+          lines.forEach(line => logActivityLine('COPILOT', line));
+        };
+        if (proc.stdout) proc.stdout.on('data', d => flush(d.toString()));
+        if (proc.stderr) proc.stderr.on('data', d => flush(d.toString()));
+        proc.on('close', (code) => {
+          if (buffer.trim()) logActivityLine('COPILOT', buffer);
+          if (allOutput.trim()) logRawBlock('COPILOT', `Full Copilot Output  (exit ${code ?? '?'})`, allOutput);
+
+          if (allOutput.includes('in interactive mode to enable this model')) {
+            logActivityLine('COPILOT', `Model '${model}' is locked. Run: copilot --model ${model}`);
+            logActivityLine('COPILOT', '  Then type a message and Ctrl+C to unlock it.');
+          }
+
+          resolvePromise({ code: code ?? 0, allOutput });
+        });
+        proc.on('error', reject);
+      });
+
+      // Check for limit errors in output
+      const { type, line } = detectLimit(result.allOutput);
+      if (type === 'capacity') {
+        banModel(model, 'capacity');
+        exhaustedMsgs.push(`${model}: ${line}`);
+        logActivityLine('COPILOT', `Model ${model} quota exhausted — trying next model`);
+        continue; // try next model
+      }
+      if (type === 'ratelimit') {
+        banModel(model, 'ratelimit');
+        throw new AILimitError('COPILOT', result.allOutput);
+      }
+
+      if (model !== getStartModels().copilot) {
+        logActivityLine('COPILOT', `Task completed using fallback model: ${model}`);
+      }
+      circuitBreaker.recordSuccess('copilot');
+      trackUsage({ provider: 'copilot', model, stage: options.stage, featureId: options.featureId, promptText: prompt, responseText: result.allOutput || '', durationMs: Date.now() - _costStart });
+      return result.code;
+
+    } finally {
+      statusBar.clear();
+    }
+  }
+
+  // All models exhausted
+  const detail = exhaustedMsgs.map(m => `\n    ${m}`).join('');
+  throw new AILimitError('COPILOT', `All models exhausted:${detail}`);
+}
+
+/**
+ * Generate a deterministic UUID from a featureId for Copilot session tracking.
+ * Same featureId always maps to the same UUID → same Copilot conversation.
+ * UUID v4 format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+ */
+function featureToSessionUUID(featureId) {
+  const hash = createHash('md5').update(`aicc-copilot-${featureId}`).digest('hex');
+  return `${hash.slice(0,8)}-${hash.slice(8,12)}-4${hash.slice(13,16)}-8${hash.slice(17,20)}-${hash.slice(20,32)}`;
+}
+
+/**
+ * Run Copilot with a SPECIFIC model (e.g. claude-opus-4.6), bypassing the model chain.
+ * Use this when the user has explicitly confirmed a premium model.
+ */
+export async function runCopilotWithModel(model, prompt, options = {}) {
+  syncCopilotConfigModel(model);
+  return runCopilot(prompt, { ...options, _forceModel: model });
+}
+
+// ─── Ollama Local AI ─────────────────────────────────────────────────────────
+//
+// Ollama exposes an OpenAI-compatible API at localhost:11434/v1.
+// Used for lightweight tasks: summaries, explanations, quick Q&A.
+// No CLI tool needed — pure HTTP calls.
+
+/**
+ * Check if Ollama is running and reachable.
+ * Returns { available, models } where models is the list of installed model names.
+ */
+export async function isOllamaAvailable() {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+    const res = await fetch(`${getOllamaUrl()}/api/tags`, { signal: controller.signal });
+    clearTimeout(timeout);
+    if (!res.ok) return { available: false, models: [] };
+    const data = await res.json();
+    const models = (data.models || []).map(m => m.name);
+    return { available: true, models };
+  } catch {
+    return { available: false, models: [] };
+  }
+}
+
+/**
+ * Run a prompt through Ollama's local AI.
+ *
+ * Lightweight — no session management, no file output, no model chains.
+ * Returns the response text directly. Throws on error.
+ *
+ * @param {string} prompt   - The question or task
+ * @param {object} options
+ *   model    {string}  - Override model (default: configured ollama model)
+ *   timeout  {number}  - Timeout in ms (default: 60000 — first call may load the model)
+ *   system   {string}  - Optional system prompt for context
+ */
+export async function runOllama(prompt, options = {}) {
+  const model   = options.model || getStartModels().ollama;
+  const timeout = options.timeout || 60000;
+  const _costStart = Date.now();
+
+  logActivityLine('OLLAMA', `[${model}] ${prompt.slice(0, 60).replace(/\n/g, ' ')}...`);
+
+  const messages = [];
+  if (options.system) {
+    messages.push({ role: 'system', content: options.system });
+  }
+  messages.push({ role: 'user', content: prompt });
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const res = await fetch(`${getOllamaUrl()}/v1/chat/completions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ model, messages, stream: false }),
+      signal: controller.signal,
+    });
+    clearTimeout(timer);
+
+    if (!res.ok) {
+      const body = await res.text();
+      if (body.includes('model') && body.includes('not found')) {
+        throw new Error(`Model "${model}" not found. Run: ollama pull ${model}`);
+      }
+      throw new Error(`Ollama API error ${res.status}: ${body.slice(0, 200)}`);
+    }
+
+    const data = await res.json();
+    const text = data.choices?.[0]?.message?.content || '';
+    logActivityLine('OLLAMA', `Response: ${text.length} chars`);
+    trackUsage({ provider: 'ollama', model, stage: options.stage, featureId: options.featureId, promptText: prompt, responseText: text, inputTokens: data.usage?.prompt_tokens, outputTokens: data.usage?.completion_tokens, durationMs: Date.now() - _costStart });
+    return text;
+  } catch (err) {
+    clearTimeout(timer);
+    if (err.name === 'AbortError') {
+      throw new Error(`Ollama timed out after ${timeout / 1000}s — model may still be loading. Try again.`);
+    }
+    if (err.cause?.code === 'ECONNREFUSED') {
+      throw new Error('Ollama is not running. Start it with: ollama serve');
+    }
+    throw err;
+  }
+}
+
+/**
+ * Smart AI router — picks local (Ollama) or cloud based on task weight and config.
+ *
+ * @param {string} prompt    - The question or task
+ * @param {object} options
+ *   weight    {'light'|'heavy'}  - Task complexity (default: 'light')
+ *   fallback  {boolean}          - Fall back to cloud if Ollama unavailable (default: true)
+ *   system    {string}           - Optional system prompt
+ *   model     {string}           - Override Ollama model
+ *   outputFile {string}          - For heavy tasks routed to Gemini
+ *
+ * @returns {string} AI response text
+ */
+export async function runAI(prompt, options = {}) {
+  const { weight = 'light', fallback = true } = options;
+  const mode = AI_MODE; // hybrid | cloud | local
+  const _costStartAI = Date.now();
+
+  // Heavy tasks always go to cloud (unless mode is 'local')
+  if (weight === 'heavy' && mode !== 'local') {
+    if (options.outputFile) {
+      await runGemini(prompt, options.outputFile);
+      return readFileSync(options.outputFile, 'utf8');
+    }
+    throw new Error('Heavy tasks require an outputFile for Gemini.');
+  }
+
+  // Local mode — Ollama only
+  if (mode === 'local') {
+    const ollamaStatus = await isOllamaAvailable();
+    if (!ollamaStatus.available) {
+      throw new Error('Ollama is not running and AI_MODE=local. Start Ollama or switch to hybrid mode.');
+    }
+    return await runOllama(prompt, { system: options.system, model: options.model });
+  }
+
+  // Cloud or hybrid mode — use pipeline 'chat' entry with fallbacks
+  // The chat pipeline entry defines: primary provider + model + fallbacks
+  // e.g. { stage: 'chat', provider: 'openclaw', model: 'auto', fallbacks: ['copilot:claude-haiku-4.5'] }
+  const chatEntry = _getPipelineEntry('chat');
+  const chatProviders = [
+    { provider: chatEntry.provider, model: chatEntry.model },
+    ...(chatEntry.fallbacks || []).map(fb => {
+      if (fb.includes(':')) {
+        const [p, m] = fb.split(':', 2);
+        return { provider: p, model: m };
+      }
+      return { provider: fb, model: null };
+    }),
+  ];
+
+  for (const { provider: chatProvider, model: chatProviderModel } of chatProviders) {
+    try {
+      if (chatProvider === 'openclaw') {
+        if (_openclawAvailable === null) _openclawAvailable = await isAvailable('openclaw');
+        if (!_openclawAvailable) continue;
+        const fullPrompt = options.system ? `${options.system}\n\n${prompt}` : prompt;
+        const sessionId = getOpenclawSessionId();
+        const result = await capture(
+          'openclaw', ['agent', '--session-id', sessionId, '-m', fullPrompt, '--json'],
+          { timeout: 60000, shell: false }
+        );
+        if (result.code === 0 && result.stdout) {
+          const jsonStart = result.stdout.indexOf('{');
+          if (jsonStart >= 0) {
+            const parsed = JSON.parse(result.stdout.slice(jsonStart));
+            const text = parsed?.result?.payloads?.[0]?.text?.trim();
+            const aiModel = parsed?.result?.meta?.agentMeta?.model || 'unknown';
+            if (text) {
+              logActivityLine('OPENCLAW', `Response via ${aiModel}: ${text.length} chars`);
+              trackUsage({ provider: 'openclaw', model: aiModel, featureId: options.featureId, promptText: prompt, responseText: text, durationMs: Date.now() - _costStartAI });
+              return text;
+            }
+          }
+        }
+        logActivityLine('OPENCLAW', `Exit ${result.code} — trying next provider...`);
+      } else if (chatProvider === 'copilot') {
+        const copilotAvailable = await isAvailable('copilot');
+        if (!copilotAvailable) continue;
+        const tmpOut = resolve(tmpdir(), `aicc-ai-copilot-${Date.now()}.txt`);
+        const fullPrompt = options.system ? `${options.system}\n\n${prompt}` : prompt;
+        writeFileSync(tmpOut, fullPrompt, 'utf8');
+        const copilotModel = options.model || chatProviderModel || 'claude-haiku-4.5';
+        const result = await capture(
+          `copilot --model ${copilotModel} -p "$(cat '${tmpOut}')"`, [],
+          { timeout: 60000 }
+        );
+        try { unlinkSync(tmpOut); } catch { /* */ }
+        const output = (result.stdout || '').trim();
+        if (output && result.code === 0) {
+          const { type } = detectLimit(output + '\n' + (result.stderr || ''));
+          if (!type) {
+            logActivityLine('COPILOT', `Response: ${output.length} chars`);
+            trackUsage({ provider: 'copilot', model: copilotModel, featureId: options.featureId, promptText: prompt, responseText: output, durationMs: Date.now() - _costStartAI });
+            return output;
+          }
+          logActivityLine('COPILOT', 'Rate limited — trying next provider...');
+        } else if (result.code !== 0) {
+          logActivityLine('COPILOT', `Exit code ${result.code} — trying next provider...`);
+        }
+      } else if (chatProvider === 'gemini') {
+        const geminiAvailable = await isAvailable('gemini');
+        if (!geminiAvailable) continue;
+        const tmpOut = resolve(tmpdir(), `aicc-ai-gemini-${Date.now()}.md`);
+        await runGemini(options.system ? `${options.system}\n\n${prompt}` : prompt, tmpOut);
+        const text = readFileSync(tmpOut, 'utf8');
+        try { unlinkSync(tmpOut); } catch { /* */ }
+        return text;
+      } else if (chatProvider === 'claude') {
+        const claudeAvailable = await isAvailable('claude');
+        if (!claudeAvailable) continue;
+        const claudeModel = options.model || chatProviderModel || 'claude-sonnet-4-6';
+
+        // Build flags — use --resume for session continuity so AI remembers context
+        const flags = ['--model', claudeModel, '--print', '--output-format', 'json', '--dangerously-skip-permissions'];
+
+        // Chat session: persist conversation across messages
+        const sessionsDir = resolve(getWorkflowDir(), 'sessions');
+        if (!existsSync(sessionsDir)) mkdirSync(sessionsDir, { recursive: true });
+        const chatSessionFile = resolve(sessionsDir, 'CLAUDE-chat.json');
+        let hasSession = false;
+        if (existsSync(chatSessionFile)) {
+          try {
+            const { sessionId } = JSON.parse(readFileSync(chatSessionFile, 'utf8'));
+            if (sessionId) {
+              flags.push('--resume', sessionId);
+              hasSession = true;
+            }
+          } catch { /* corrupt — start fresh */ }
+        }
+
+        // Always include system prompt — resumed sessions lose the original system context,
+        // causing AI to forget _action JSON instructions and respond conversationally instead.
+        const fullPrompt = options.system
+          ? `${options.system}\n\n${prompt}`
+          : prompt;
+        const tmpOut = resolve(tmpdir(), `aicc-ai-claude-${Date.now()}.txt`);
+        writeFileSync(tmpOut, fullPrompt, 'utf8');
+
+        // System prompt is always included now, so allow full timeout for all calls
+        const chatTimeout = 120000;
+        const result = await capture(
+          `cat "${tmpOut}" | claude ${flags.join(' ')}`,
+          [], { shell: true, timeout: chatTimeout }
+        );
+        try { unlinkSync(tmpOut); } catch { /* */ }
+
+        const stdout = (result.stdout || '').trim();
+        if (stdout && result.code === 0) {
+          // Parse JSON output to extract text and session_id
+          let output = stdout;
+          try {
+            const jsonStart = stdout.indexOf('{');
+            if (jsonStart >= 0) {
+              const parsed = JSON.parse(stdout.slice(jsonStart));
+              // Save session ID for conversation continuity
+              if (parsed.session_id) {
+                writeFileSync(chatSessionFile, JSON.stringify({ sessionId: parsed.session_id }));
+              }
+              // Extract text from JSON result
+              if (parsed.result) {
+                output = parsed.result;
+              }
+            }
+          } catch { /* not valid JSON — use raw stdout */ }
+
+          const { type } = detectLimit(output + '\n' + (result.stderr || ''));
+          if (!type) {
+            logActivityLine('CLAUDE', `Chat response via ${claudeModel}: ${output.length} chars`);
+            trackUsage({ provider: 'claude', model: claudeModel, featureId: options.featureId, promptText: prompt, responseText: output, durationMs: Date.now() - _costStartAI });
+            return output;
+          }
+          logActivityLine('CLAUDE', 'Rate limited — trying next provider...');
+        } else if (result.code !== 0) {
+          // Session might be expired — clear it and let next attempt start fresh
+          try { unlinkSync(chatSessionFile); } catch { /* */ }
+          logActivityLine('CLAUDE', `Exit code ${result.code} — trying next provider...`);
+        }
+      } else if (chatProvider === 'ollama') {
+        const ollamaStatus = await isOllamaAvailable();
+        if (!ollamaStatus.available) continue;
+        return await runOllama(prompt, { system: options.system, model: options.model || chatProviderModel });
+      }
+    } catch (err) {
+      logActivityLine(chatProvider.toUpperCase(), `Error: ${err.message} — trying next provider...`);
+    }
+  }
+
+  // Final fallback: try Ollama if not already tried
+  if (!fallback) throw new Error('Cloud AIs unavailable and fallback=false.');
+  const ollamaStatus = await isOllamaAvailable();
+  if (ollamaStatus.available) {
+    return await runOllama(prompt, { system: options.system, model: options.model });
+  }
+
+  throw new Error('All AI providers unavailable. Check your setup or pipeline config.');
+}
+
+/** Get the current AI mode setting. */
+export function getAIMode() { return AI_MODE; }
+
+/** Get the configured Ollama model. */
+export function getOllamaModel() { return getStartModels().ollama; }
+
+// ─── Cross-AI Fallback Pipeline ───────────────────────────────────────────────
+//
+// Provider order per stage is driven by `models.stageProviders` in config:
+//
+//  Stage: pm / architect / review / deploy (Copilot's job)
+//    Copilot (sonnet-4.6) → Gemini (3.1 Flash Lite → 2.5 Pro) → Ollama
+//
+//  Stage: implement (Claude Code's job)
+//    Claude → Copilot → Ollama
+//
+//  Chat / user conversations:
+//    Copilot (haiku-4.5 — cheap & fast) → Gemini → Ollama
+//
+// At each fallback transition, a bus event is emitted so the Telegram bot can
+// notify the user in real time.
+
+// Copilot model for cross-AI fallback (read from config at call time)
+// Configure via aicc.config.js → models.copilotCrossAiModel
+
+// Opus 4.6 model identifier (used when user explicitly confirms premium usage)
+export const OPUS_MODEL = 'claude-opus-4.6';
+
+/**
+ * Emit a rate-limit event so Telegram + web dashboard can notify the user.
+ */
+function emitLimitEvent(agent, limitType, model, fallbackAgent) {
+  const data = { agent, limitType, model, fallbackAgent, timestamp: new Date().toISOString() };
+  logActivityLine('PIPELINE', `${agent} ${limitType} on ${model} → falling back to ${fallbackAgent}`);
+  bus.emitEvent('ai_rate_limit', data);
+}
+
+/**
+ * Run a pipeline stage with full cross-AI fallback.
+ *
+ * This is the top-level function that new-feature.js and review.js should call
+ * instead of runGemini / runClaude / runCopilot directly, for stages where
+ * rate limits are expected.
+ *
+ * @param {string} stage       - 'architect' | 'pm' | 'review' | 'implement'
+ * @param {string} prompt      - Full prompt text
+ * @param {object} options
+ *   outputFile  {string}  - Required for Gemini-primary tasks (pm, review)
+ *   featureId   {string}  - For session tracking (Claude, Copilot)
+ *
+ * @returns {*} Result from whichever AI succeeded
+ */
+export async function runPipelineStage(stage, prompt, options = {}) {
+  const fallbackChain = buildFallbackChain(stage);
+  const requiresDocument = ['pm', 'review'].includes(stage) && options.outputFile;
+
+  for (let i = 0; i < fallbackChain.length; i++) {
+    const { agent, runner, label } = fallbackChain[i];
+    const isLast = i === fallbackChain.length - 1;
+
+    try {
+      if (i > 0) {
+        const prevAgent = fallbackChain[i - 1].label;
+        emitLimitEvent(prevAgent, 'exhausted', 'all models', label);
+      }
+
+      logActivityLine('PIPELINE', `Running ${stage} stage with ${label}...`);
+      const result = await runner(prompt, options);
+
+      // ── Document verification — NEVER skip document creation ──────────────
+      if (requiresDocument) {
+        const docExists = existsSync(options.outputFile);
+        const docContent = docExists ? readFileSync(options.outputFile, 'utf8').trim() : '';
+        const MIN_DOC_LENGTH = 100;
+
+        if (!docExists || docContent.length < MIN_DOC_LENGTH) {
+          logActivityLine('PIPELINE', `${label} completed but document is missing or too short (${docContent.length} chars)`);
+          logActivityLine('PIPELINE', `Document verification FAILED — every stage MUST produce its document`);
+
+          if (isLast) {
+            bus.emitEvent('ai_all_exhausted', {
+              stage,
+              agents: fallbackChain.map(f => f.label).join(' → '),
+              error: `All AIs completed but none produced a valid ${stage} document. Pipeline STOPPED — documents are required.`,
+            });
+            throw new Error(
+              `Pipeline STOPPED: ${stage} stage requires a document but none was created.\n` +
+              `Tried: ${fallbackChain.map(f => f.label).join(' → ')}\n` +
+              `Documents are the audit trail — the pipeline cannot proceed without them.`
+            );
+          }
+          continue;
+        }
+
+        logActivityLine('PIPELINE', `Document verified: ${options.outputFile.split('/').pop()} (${docContent.length} chars)`);
+      }
+
+      return result;
+    } catch (err) {
+      if (err instanceof AILimitError || err.name === 'AILimitError') {
+        logActivityLine(agent, `All models exhausted: ${err.message}`);
+        if (isLast) {
+          bus.emitEvent('ai_all_exhausted', {
+            stage,
+            agents: fallbackChain.map(f => f.label).join(' → '),
+            error: err.message,
+          });
+          throw err;
+        }
+        continue;
+      }
+      throw err;
+    }
+  }
+}
+
+/**
+ * Build the ordered fallback chain for a pipeline stage.
+ * Each entry has: { agent, runner, label }
+ *
+ * Driven by the `pipeline[]` array in config. Each stage entry specifies
+ * the primary provider + model and an optional fallbacks array:
+ *
+ *   pipeline: [
+ *     { stage: 'pm', provider: 'copilot', model: 'claude-sonnet-4.6', fallbacks: ['gemini:gemini-2.5-pro', 'ollama'] },
+ *     ...
+ *   ]
+ */
+function buildFallbackChain(stage) {
+  const entry = _getPipelineEntry(stage);
+  const chain = [];
+
+  // Helper: create a chain entry for a given provider + model
+  function addProviderEntry(provider, model) {
+    switch (provider) {
+      case 'copilot': {
+        if (stage === 'implement') {
+          chain.push({
+            agent: 'COPILOT', label: `Copilot (${model})`,
+            runner: (prompt, opts) => runCopilot(prompt, opts),
+          });
+        } else {
+          chain.push({
+            agent: 'COPILOT', label: `Copilot (${model})`,
+            runner: async (prompt, opts) => {
+              syncCopilotConfigModel(model);
+              const tmpFile = resolve(tmpdir(), `aicc-fallback-${Date.now()}.txt`);
+              writeFileSync(tmpFile, prompt, 'utf8');
+              const result = await capture(
+                `cat "${tmpFile}" | copilot -p --model ${model} --yolo`,
+                [], { shell: true, timeout: DEFAULT_TIMEOUTS.copilot }
+              );
+              try { unlinkSync(tmpFile); } catch { /* */ }
+              if (opts.outputFile && result.stdout.trim()) {
+                writeFileSync(opts.outputFile, result.stdout);
+              }
+              const { type } = detectLimit(result.stdout + '\n' + result.stderr);
+              if (type) throw new AILimitError('COPILOT', result.stdout + '\n' + result.stderr);
+              return result.code;
+            },
+          });
+        }
+        break;
+      }
+      case 'claude':
+        chain.push({
+          agent: 'CLAUDE', label: `Claude (${model})`,
+          runner: (prompt, opts) => runClaude(prompt, opts),
+        });
+        break;
+      case 'gemini':
+        chain.push({
+          agent: 'GEMINI', label: `Gemini (${model})`,
+          runner: (prompt, opts) => runGemini(prompt, opts.outputFile, { modelChain: [model, ...getConfiguredChains().gemini.filter(m => m !== model)] }),
+        });
+        break;
+      case 'openclaw':
+        chain.push({
+          agent: 'OPENCLAW', label: `OpenClaw (${model})`,
+          runner: async (prompt, opts) => {
+            if (_openclawAvailable === null) _openclawAvailable = await isAvailable('openclaw');
+            if (!_openclawAvailable) throw new AILimitError('OPENCLAW', 'OpenClaw CLI not available');
+            const sessionId = getOpenclawSessionId();
+            const fullPrompt = opts.system ? `${opts.system}\n\n${prompt}` : prompt;
+            const result = await capture(
+              'openclaw', ['agent', '--session-id', sessionId, '-m', fullPrompt, '--json'],
+              { timeout: 60000, shell: false }
+            );
+            if (result.code === 0 && result.stdout) {
+              const jsonStart = result.stdout.indexOf('{');
+              if (jsonStart >= 0) {
+                const parsed = JSON.parse(result.stdout.slice(jsonStart));
+                const text = parsed?.result?.payloads?.[0]?.text?.trim();
+                if (text) {
+                  logActivityLine('OPENCLAW', `Response: ${text.length} chars`);
+                  trackUsage({ provider: 'openclaw', model: parsed?.result?.meta?.agentMeta?.model || model, featureId: opts.featureId, promptText: prompt, responseText: text, durationMs: 0 });
+                  if (opts.outputFile) writeFileSync(opts.outputFile, text);
+                  return text;
+                }
+              }
+            }
+            throw new AILimitError('OPENCLAW', 'OpenClaw returned empty response');
+          },
+        });
+        break;
+      case 'ollama':
+        chain.push(ollamaFallbackEntry(stage));
+        break;
+      default:
+        logActivityLine('SYSTEM', `Unknown provider "${provider}" in pipeline — skipped`);
+        break;
+    }
+  }
+
+  // Primary provider + model from pipeline entry
+  addProviderEntry(entry.provider, entry.model);
+
+  // Fallback entries
+  for (const fb of (entry.fallbacks || [])) {
+    if (fb.includes(':')) {
+      const [prov, mod] = fb.split(':', 2);
+      addProviderEntry(prov, mod);
+    } else {
+      // Just provider name, no model — use defaults
+      const defaultModel = getStartModels()[fb] || fb;
+      addProviderEntry(fb, defaultModel);
+    }
+  }
+
+  return chain;
+}
+
+/**
+ * Ollama last-resort fallback.
+ * 3-second timeout — if it can't respond in 3s, just return an error message.
+ */
+function ollamaFallbackEntry(stage) {
+  return {
+    agent: 'OLLAMA', label: 'Ollama (last resort)',
+    runner: async (prompt, opts) => {
+      const ollamaStatus = await isOllamaAvailable();
+      if (!ollamaStatus.available) {
+        const errorMsg = `All cloud AIs are rate-limited for the "${stage}" stage. ` +
+          `Ollama is not running. Please wait and retry, or switch AI models.`;
+        logActivityLine('OLLAMA', errorMsg);
+        if (opts.outputFile) writeFileSync(opts.outputFile, `# Error\n\n${errorMsg}\n`);
+        bus.emitEvent('ai_all_exhausted', { stage, error: errorMsg });
+        throw new AILimitError('OLLAMA', errorMsg);
+      }
+
+      try {
+        const response = await runOllama(
+          `You are a fallback AI. The primary AIs (Gemini, Claude, Copilot) are all rate-limited.\n\n` +
+          `Summarize what was requested and inform the user to retry later:\n\n` +
+          prompt.slice(0, 2000),
+          { timeout: 3000 }
+        );
+
+        if (opts.outputFile) {
+          writeFileSync(opts.outputFile,
+            `# Fallback Response (Ollama)\n\n` +
+            `> All cloud AIs were rate-limited. This is a local AI fallback summary.\n\n` +
+            response
+          );
+        }
+        return 0;
+      } catch (err) {
+        const errorMsg = `All AIs exhausted for "${stage}" stage. Ollama timed out (3s limit). ` +
+          `Please wait for rate limits to reset and retry.`;
+        logActivityLine('OLLAMA', errorMsg);
+        if (opts.outputFile) writeFileSync(opts.outputFile, `# Error\n\n${errorMsg}\n`);
+        bus.emitEvent('ai_all_exhausted', { stage, error: errorMsg });
+        throw new AILimitError('OLLAMA', errorMsg);
+      }
+    },
+  };
+}