omo-recommend-models 1.0.0

package/bin/omo-recommend-models

@@ -0,0 +1,3948 @@
+#!/usr/bin/env node
+/**
+ * omo-recommend-models — Consolidated AI-powered model recommendation for
+ *                       oh-my-openagent.jsonc.
+ *
+ * Makes a SINGLE AI recommendation pass with FULL context: cloud model
+ * inventory AND local Ollama models AND GPU/hardware info. The AI sees
+ * everything at once, so it never makes blind placements.
+ *
+ * Usage:
+ *   omo-recommend-models                      # AI-powered (cloud + local)
+ *   omo-recommend-models -y                   # auto-accept all
+ *   omo-recommend-models --rebalance          # algorithmic tier-chain only
+ *   omo-recommend-models --dry-run            # preview without writing
+ *   omo-recommend-models --cloud-only         # skip local model discovery
+ *   omo-recommend-models --local-only         # skip cloud model discovery
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { execFileSync, execSync, spawn } from "node:child_process";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+import { dirname } from "node:path";
+import mri from "mri";
+import pc from "picocolors";
+import {
+  CONFIG_PATH,
+  BACKUP_PATH,
+  confirm as plainConfirm,
+  promptUser as plainPromptUser,
+  pickFreeModel,
+  discoverFreeModels,
+  callOpencodeChat,
+  parseAiJson,
+  loadConfig,
+  loadProviderModels,
+  buildProviderAliases,
+  resolveProvider,
+  normalizeLocalModelName,
+  formatModelRef,
+  buildRichModelLookup,
+} from "../lib/omo-shared.js";
+import {
+  backupConfig,
+  writeConfigWithValidation,
+} from "../lib/recommend/apply.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const VERSION = "1.0.0";
+
+const activeChildren = new Set();
+let clack = null;
+let useClackPrompts = false;
+let debugMode = false;
+
+function usage() {
+  return [
+    "Usage: omo-recommend-models [options]",
+    "",
+    "Recommend OpenCode OMO model placements for oh-my-openagent.jsonc.",
+    "",
+    "Options:",
+    "  -y, --yes          Apply recommendations without interactive confirmation",
+    "      --rebalance    Perform algorithmic tier-chain restructuring",
+    "      --dry-run      Preview recommendations without writing config",
+    "      --cloud-only   Skip GPU, Ollama, and local model discovery",
+    "      --local-only   Skip cloud model discovery and API checks",
+    "      --model <ref>  Use an explicit AI panel model; may be repeated",
+    "      --interactive  Force interactive prompts in non-TTY environments",
+    "      --debug        Print stack traces for errors",
+    "  -h, --help         Show this help",
+    "  -v, --version      Show version",
+  ].join("\n");
+}
+
+function registerChild(child) {
+  activeChildren.add(child);
+  child.once("exit", () => activeChildren.delete(child));
+  child.once("error", () => activeChildren.delete(child));
+  return child;
+}
+
+function spawnTracked(command, args, options) {
+  return registerChild(spawn(command, args, options));
+}
+
+function terminateActiveChildren() {
+  const children = [...activeChildren].filter(
+    (child) => child.exitCode === null && child.signalCode === null,
+  );
+  for (const child of children) {
+    try {
+      child.kill("SIGTERM");
+    } catch {}
+  }
+  setTimeout(() => {
+    for (const child of children) {
+      if (child.exitCode === null && child.signalCode === null) {
+        try {
+          child.kill("SIGKILL");
+        } catch {}
+      }
+    }
+    process.exit(1);
+  }, 2000).unref();
+}
+
+function installSignalHandlers() {
+  let handlingSignal = false;
+  const handler = (signal) => {
+    if (handlingSignal) return;
+    handlingSignal = true;
+    process.stderr.write(`\n${signal} received; terminating subprocesses...\n`);
+    terminateActiveChildren();
+  };
+  process.once("SIGINT", handler);
+  process.once("SIGTERM", handler);
+}
+
+async function configureTerminalUi(enabled) {
+  useClackPrompts = Boolean(enabled);
+  if (!useClackPrompts) return;
+  try {
+    clack = await import("@clack/prompts");
+  } catch {
+    clack = null;
+  }
+}
+
+async function confirm(question) {
+  if (useClackPrompts && clack?.confirm) {
+    const answer = await clack.confirm({
+      message: question.replace(/\s*\([^)]+\)\s*$/, "").trim(),
+      initialValue: false,
+    });
+    return answer === true;
+  }
+  return plainConfirm(question);
+}
+
+async function promptUser(question) {
+  if (useClackPrompts && clack?.text) {
+    const answer = await clack.text({ message: question.trim() });
+    return typeof answer === "string" ? answer.trim() : "";
+  }
+  return plainPromptUser(question);
+}
+
+function commandExists(binary) {
+  if (!binary || binary.includes(path.sep)) return "";
+  for (const dir of String(process.env.PATH || "").split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, binary);
+    try {
+      const stat = fs.statSync(candidate);
+      if (!stat.isFile()) continue;
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return candidate;
+    } catch {}
+  }
+  return "";
+}
+
+// =========================================================================
+// Model scoring constants (from omo-recommend-cloud)
+// =========================================================================
+
+const FAMILY_TIERS = {
+  "claude-opus": 35,
+  "claude-sonnet": 28,
+  "gemini-pro": 25,
+  "gpt-pro": 25,
+  gpt: 22,
+  "gpt-codex": 18,
+  "gpt-codex-spark": 16,
+  "gemini-flash": 12,
+  "nemotron-free": 10,
+  "deepseek-flash-free": 8,
+  "claude-haiku": 8,
+  "gpt-mini": 5,
+  "mimo-v2.5-free": 3,
+  "north-free": 0,
+  "big-pickle": 0,
+};
+
+const PROVIDER_PRESTIGE = {
+  openai: 5,
+  "github-copilot": 5,
+  anthropic: 5,
+  opencode: 5,
+};
+const VARIANT_BONUS = { xhigh: 10, max: 8, high: 5, medium: 0, low: -5 };
+const LOCAL_PROVIDER = "local";
+const FREE_PROVIDERS = ["opencode", LOCAL_PROVIDER];
+const QUALITY_TIERS = ["reasoning", "balanced", "fast"];
+const quotaExceededProviders = new Set();
+const providerAvailability = new Map();
+let opencodeOnlyMode = false;
+const providerProbePromises = new Map();
+
+// =========================================================================
+// Local model constants (from omo-recommend-local)
+// =========================================================================
+
+const MODEL_CACHE_FILE = path.join(
+  os.homedir(),
+  ".cache",
+  "oh-my-opencode",
+  "ollama-models.json",
+);
+
+const PANEL_CACHE_FILE = path.join(
+  os.homedir(),
+  ".cache",
+  "oh-my-opencode",
+  "panel-cache.json",
+);
+
+function loadPanelCache() {
+  try {
+    if (!fs.existsSync(PANEL_CACHE_FILE)) return null;
+    const raw = fs.readFileSync(PANEL_CACHE_FILE, "utf-8");
+    const data = JSON.parse(raw);
+    if (!data || !data.timestamp || !data.result) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+function savePanelCache(result, panelModels, gpuInfo) {
+  try {
+    const dir = path.dirname(PANEL_CACHE_FILE);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const gpu = gpuInfo
+      ? {
+          hasGpu: !!gpuInfo.hasGpu,
+          name: gpuInfo.name || "",
+          label: gpuInfo.label || "",
+          vramGb: gpuInfo.vramGb || 0,
+        }
+      : null;
+    fs.writeFileSync(
+      PANEL_CACHE_FILE,
+      JSON.stringify(
+        {
+          timestamp: Date.now(),
+          models: panelModels || null,
+          gpu,
+          result,
+        },
+        null,
+        2,
+      ),
+      "utf-8",
+    );
+  } catch {
+    /* cache write failure is non-fatal */
+  }
+}
+
+function modelListEquals(a, b) {
+  if (!a || !b) return false;
+  if (a.length !== b.length) return false;
+  const sa = [...a].sort();
+  const sb = [...b].sort();
+  return sa.every((v, i) => v === sb[i]);
+}
+
+function isSubsetList(superset, subset) {
+  if (!superset || !subset) return false;
+  const ss = new Set(superset);
+  return subset.every((m) => ss.has(m));
+}
+
+const KNOWN_MODELS = [
+  { name: "llama3.2", tags: ["1b", "3b"] },
+  { name: "llama3.1", tags: ["8b", "70b", "405b"] },
+  { name: "llama3", tags: ["8b", "70b", "405b"] },
+  { name: "qwen2.5-coder", tags: ["1.5b", "7b", "14b", "32b"] },
+  { name: "qwen2.5", tags: ["7b", "14b", "32b", "72b"] },
+  { name: "deepseek-coder-v2", tags: ["16b"] },
+  { name: "codegemma", tags: ["2b", "7b"] },
+  { name: "codellama", tags: ["7b", "13b", "34b", "70b"] },
+  { name: "mistral", tags: ["7b"] },
+  { name: "mixtral", tags: ["8x7b", "8x22b"] },
+  { name: "phi3", tags: ["3.8b", "7b", "14b"] },
+  { name: "gemma2", tags: ["2b", "9b", "27b"] },
+  { name: "nomic-embed-text", tags: ["v1.5"] },
+  { name: "mxbai-embed-large", tags: ["v1"] },
+  { name: "llama3.2-vision", tags: ["11b", "90b"] },
+  { name: "llava", tags: ["7b", "13b", "34b"] },
+  { name: "bakllava", tags: ["7b"] },
+  { name: "starcoder2", tags: ["3b", "7b", "15b"] },
+  { name: "dolphin-mixtral", tags: ["8x7b"] },
+  { name: "neural-chat", tags: ["7b"] },
+  { name: "orca-mini", tags: ["3b", "7b"] },
+  { name: "tinyllama", tags: ["1.1b"] },
+  { name: "falcon3", tags: ["1b", "3b", "7b", "10b"] },
+  {
+    name: "command-r",
+    tags: ["7b", "7b-08-2024", "v01", "35b-08-2024", "104b"],
+  },
+  { name: "llama-guard3", tags: ["1b", "8b"] },
+  { name: "nemotron", tags: ["mini-4b-instruct"] },
+  {
+    name: "deepseek-r1",
+    tags: ["1.5b", "7b", "8b", "14b", "32b", "70b", "671b"],
+  },
+  { name: "qwq", tags: ["32b"] },
+];
+
+const MODEL_SCORES = {
+  "deepseek-coder-v2": 95,
+  "qwen2.5-coder": 92,
+  "llama3.1": 88,
+  llama3: 86,
+  codellama: 82,
+  codegemma: 78,
+  mixtral: 76,
+  "deepseek-r1": 74,
+  qwq: 72,
+  "qwen2.5": 70,
+  mistral: 68,
+  starcoder2: 66,
+  falcon3: 64,
+  "llama3.2": 62,
+  gemma2: 60,
+  "command-r": 58,
+  phi3: 55,
+  "dolphin-mixtral": 52,
+  "neural-chat": 48,
+  "orca-mini": 42,
+  nemotron: 40,
+  "llama-guard3": 35,
+  tinyllama: 30,
+  "mxbai-embed-large": 20,
+  "nomic-embed-text": 18,
+  "llama3.2-vision": 70,
+  llava: 62,
+  bakllava: 55,
+};
+
+const BASE_VRAM = {
+  "deepseek-coder-v2": 16,
+  "qwen2.5-coder": 7,
+  "llama3.1": 8,
+  llama3: 8,
+  codellama: 7,
+  codegemma: 7,
+  mixtral: 47,
+  "deepseek-r1": 7,
+  qwq: 32,
+  "qwen2.5": 7,
+  mistral: 7,
+  starcoder2: 7,
+  falcon3: 7,
+  "llama3.2": 3,
+  gemma2: 9,
+  "command-r": 7,
+  phi3: 4,
+  "dolphin-mixtral": 47,
+  "neural-chat": 7,
+  "orca-mini": 3,
+  nemotron: 4,
+  "llama-guard3": 8,
+  tinyllama: 1,
+  "mxbai-embed-large": 1,
+  "nomic-embed-text": 1,
+  "llama3.2-vision": 11,
+  llava: 7,
+  bakllava: 7,
+};
+
+// =========================================================================
+// Cloud model scoring
+// =========================================================================
+
+function scoreFromCache(model, variant, entry) {
+  let score = 0;
+  if (entry.release_date) {
+    const d = new Date(entry.release_date);
+    const epochDays = Math.floor(d.getTime() / 86400000);
+    if (!isNaN(epochDays)) {
+      score += Math.max(0, epochDays - 20000) * 2;
+    }
+  }
+  const family = entry.family || "";
+  for (const [key, val] of Object.entries(FAMILY_TIERS)) {
+    if (family.includes(key) || family === key) {
+      score += val;
+      break;
+    }
+  }
+  const caps = entry.capabilities || [];
+  if (
+    Array.isArray(caps) &&
+    caps.some((c) => c.toLowerCase().includes("reasoning"))
+  ) {
+    score += 15;
+  }
+  const ctx = entry.context_length || entry.context_window || 0;
+  if (ctx > 200000) score += 8;
+  else if (ctx > 100000) score += 5;
+  else if (ctx > 32000) score += 3;
+  if (variant && VARIANT_BONUS[variant] !== undefined)
+    score += VARIANT_BONUS[variant];
+  const cost = entry.cost || entry.input_price || 0;
+  if (typeof cost === "number" && !isNaN(cost)) score -= Math.min(cost * 10, 5);
+  const provider = model.split("/")[0];
+  score += PROVIDER_PRESTIGE[provider] || 0;
+  return isNaN(score) ? 0 : score;
+}
+
+function scoreFromHeuristics(model, variant) {
+  const parts = model.split("/");
+  const modelPart = parts[parts.length - 1] || "";
+  let score = 0;
+  const verMatch = modelPart.match(/(\d+)\.(\d+)/);
+  if (verMatch) score += parseInt(verMatch[1]) * 3 + parseInt(verMatch[2]);
+  const lower = modelPart.toLowerCase();
+  if (
+    lower.includes("opus") ||
+    lower.includes("pro") ||
+    lower.includes("ultra")
+  )
+    score += 14;
+  if (
+    lower.includes("sonnet") ||
+    lower.includes("flash") ||
+    lower.includes("codex")
+  )
+    score += 8;
+  if (
+    lower.includes("haiku") ||
+    lower.includes("mini") ||
+    lower.includes("nano")
+  )
+    score += 3;
+  if (lower.includes("reasoning")) score += 10;
+  if (lower.includes("max") || lower.includes("large") || lower.includes("big"))
+    score += 5;
+  if (variant && VARIANT_BONUS[variant] !== undefined)
+    score += VARIANT_BONUS[variant];
+  const sizeMatch = modelPart.match(/(\d+)b/i);
+  if (sizeMatch) {
+    const size = parseInt(sizeMatch[1]);
+    if (size >= 70) score += 20;
+    else if (size >= 30) score += 15;
+    else if (size >= 13) score += 10;
+    else if (size >= 7) score += 5;
+  }
+  const provider = model.split("/")[0];
+  score += PROVIDER_PRESTIGE[provider] || 0;
+  return score;
+}
+
+function scoreModel(model, variant, cacheEntry) {
+  return cacheEntry
+    ? scoreFromCache(model, variant, cacheEntry)
+    : scoreFromHeuristics(model, variant);
+}
+
+function panelModelOrder(config) {
+  return String(config?.omo?.panel_model_order || "opencode-first").trim();
+}
+
+function sortPanelModelRefs(refs, config) {
+  const order = panelModelOrder(config);
+  const scored = refs.map((ref, index) => ({
+    ref,
+    index,
+    provider: ref.split("/")[0],
+    score: scoreModel(ref, null, null),
+  }));
+
+  if (order === "score") {
+    scored.sort((a, b) => (b.score - a.score) || (a.index - b.index));
+  } else {
+    scored.sort((a, b) => {
+      const opencodeDiff = Number(b.provider === "opencode") - Number(a.provider === "opencode");
+      if (opencodeDiff !== 0) return opencodeDiff;
+      return (b.score - a.score) || (a.index - b.index);
+    });
+  }
+
+  return scored.map((s) => s.ref);
+}
+
+function panelModelFamilyLabel(modelName) {
+  const model = String(modelName || "").toLowerCase();
+  if (model.includes("claude-opus")) return "claude-opus";
+  if (model.includes("claude-sonnet")) return "claude-sonnet";
+  if (model.includes("claude-haiku")) return "claude-haiku";
+  if (model.includes("gemini")) return "gemini";
+  if (model.includes("gpt")) return "gpt";
+  if (model.includes("codex")) return "codex";
+  if (model.includes("nemotron")) return "nemotron";
+  if (model.includes("deepseek")) return "deepseek";
+  if (model.includes("mimo")) return "mimo";
+  if (model.includes("north")) return "north";
+  if (model.includes("pickle")) return "big-pickle";
+  return "";
+}
+
+function groupPanelModelRefs(models) {
+  const groupOrder = [];
+  const byGroup = new Map();
+  for (const ref of models || []) {
+    const trimmed = String(ref || "").trim();
+    if (!trimmed) continue;
+    const slash = trimmed.indexOf("/");
+    const provider = slash === -1 ? "unknown" : trimmed.slice(0, slash);
+    const model = slash === -1 ? trimmed : trimmed.slice(slash + 1);
+    const family = provider === "cli" ? "agents" : panelModelFamilyLabel(model);
+    const label = provider === "cli"
+      ? "CLI agents"
+      : provider === "opencode"
+        ? "opencode"
+        : family
+          ? `${provider}/${family}`
+          : provider;
+    if (!byGroup.has(label)) {
+      byGroup.set(label, []);
+      groupOrder.push(label);
+    }
+    byGroup.get(label).push({ ref: trimmed, model });
+  }
+  return groupOrder.map((label) => ({ label, models: byGroup.get(label) }));
+}
+
+function printNumberedPanelModelGroups(models, indent = "  ") {
+  const groups = groupPanelModelRefs(models);
+  const width = String(groups.length).length;
+  groups.forEach((group, index) => {
+    const prefix = `${indent}${String(index + 1).padStart(width, " ")}. ${group.label}: `;
+    group.models.forEach((entry, modelIdx) => {
+      if (modelIdx === 0) {
+        console.log(`${prefix}${entry.model}`);
+      } else {
+        console.log(`${" ".repeat(prefix.length)}${entry.model}`);
+      }
+    });
+  });
+  return groups.length;
+}
+
+function printSelectablePanelModelGroups(models, indent = "  ") {
+  const groups = groupPanelModelRefs(models);
+  const width = String(groups.length).length;
+  groups.forEach((group, index) => {
+    const prefix = `${indent}[${String(index + 1).padStart(width, " ")}] ${group.label}: `;
+    group.models.forEach((entry, modelIdx) => {
+      if (modelIdx === 0) {
+        console.log(`${prefix}${entry.model}`);
+      } else {
+        console.log(`${" ".repeat(prefix.length)}${entry.model}`);
+      }
+    });
+  });
+  return groups;
+}
+
+function configuredPanelModels(config) {
+  const models = config?.omo?.panel_models;
+  if (!Array.isArray(models)) return [];
+  return models
+    .map((model) => String(model || "").trim())
+    .filter(Boolean);
+}
+
+function panelModelsRequireOpencode(models) {
+  if (!Array.isArray(models) || models.length === 0) return true;
+  return models.some((model) => !String(model || "").startsWith("cli/"));
+}
+
+function selectedPanelRequiresOpencode(config, explicitModels) {
+  if (explicitModels.length > 0) return panelModelsRequireOpencode(explicitModels);
+  const configured = configuredPanelModels(config);
+  if (configured.length > 0) return panelModelsRequireOpencode(configured);
+  return true;
+}
+
+function defaultPanelModels(config) {
+  const allFree = sortPanelModelRefs(discoverFreeModels(), config);
+  const MAX_PANEL = 5;
+  return allFree.length > MAX_PANEL ? allFree.slice(0, MAX_PANEL) : allFree;
+}
+
+function plannedPanelModels(config, panelModels) {
+  if (panelModels && panelModels.length > 0) return panelModels;
+  const configured = configuredPanelModels(config);
+  return configured.length > 0 ? configured : defaultPanelModels(config);
+}
+
+function createProgress(label) {
+  if (useClackPrompts && clack?.spinner) {
+    const spinner = clack.spinner();
+    spinner.start(label);
+    return {
+      update(message) {
+        spinner.message(`${label}: ${message}`);
+      },
+      done(message = "done") {
+        spinner.stop(`${label}: ${message}`);
+      },
+      skip(message) {
+        spinner.stop(`${label}: ${message}`);
+      },
+    };
+  }
+  const start = Date.now();
+  process.stdout.write(`  ⏳ ${label}...`);
+  return {
+    update(message) {
+      process.stdout.write(`\r  ⏳ ${label}: ${message}\x1b[K`);
+    },
+    done(message = "done") {
+      const elapsed = Math.max(0, Math.round((Date.now() - start) / 1000));
+      process.stdout.write(`\r  ✓ ${label}: ${message} (${elapsed}s)\x1b[K\n`);
+    },
+    skip(message) {
+      process.stdout.write(`\r  • ${label}: ${message}\x1b[K\n`);
+    },
+  };
+}
+
+function usableLocalVramGb(gpu) {
+  const gpuVram = Number(gpu?.vramGb);
+  if (!gpu?.hasGpu || !Number.isFinite(gpuVram)) return 0;
+  return Math.max(0, gpuVram - 1.5);
+}
+
+function buildFittingModels(allLocalModels, gpu) {
+  const usableVramGb = usableLocalVramGb(gpu);
+  return (allLocalModels || [])
+    .filter((model) => {
+      const modelVram = Number(model?.vram);
+      return Boolean(
+        model &&
+        normalizeLocalModelName(model.name) &&
+        Number.isFinite(modelVram) &&
+        modelVram >= 0 &&
+        modelVram <= usableVramGb,
+      );
+    })
+    .map((model) => ({ ...model, name: normalizeLocalModelName(model.name) }));
+}
+
+function buildFittingModelMap(allLocalModels, gpu) {
+  const byName = new Map();
+  for (const model of buildFittingModels(allLocalModels, gpu)) {
+    if (!byName.has(model.name)) byName.set(model.name, model);
+  }
+  return byName;
+}
+
+function resolveFittingLocalName(modelName, fittingByName) {
+  const name = normalizeLocalModelName(modelName);
+  return name && fittingByName.has(name) ? name : "";
+}
+
+function normalizeLocalRecommendation(rec, fittingByName, allowLocal) {
+  const normalized = normalizeRecommendation(rec);
+  if (!normalized) {
+    const provider = String(rec?.provider || "").trim();
+    const localName =
+      allowLocal && !provider
+        ? resolveFittingLocalName(rec?.model, fittingByName)
+        : "";
+    return localName
+      ? { ...rec, provider: LOCAL_PROVIDER, model: localName }
+      : null;
+  }
+  if (normalized.provider !== LOCAL_PROVIDER) return normalized;
+  if (!allowLocal) return null;
+  const localName = resolveFittingLocalName(normalized.model, fittingByName);
+  return localName
+    ? { ...normalized, provider: LOCAL_PROVIDER, model: localName }
+    : null;
+}
+
+function resultHasRejectedLocal(aiResult, fittingByName) {
+  const hasRejected = (rec, allowLocal) => {
+    const normalized = normalizeRecommendation(rec);
+    if (!normalized) {
+      const provider = String(rec?.provider || "").trim();
+      const rawModel = String(rec?.model || "").trim();
+      return Boolean(
+        rawModel &&
+        !provider &&
+        (!allowLocal || !resolveFittingLocalName(rawModel, fittingByName)),
+      );
+    }
+    if (normalized.provider !== LOCAL_PROVIDER) return false;
+    if (!allowLocal) return true;
+    return !resolveFittingLocalName(normalized.model, fittingByName);
+  };
+
+  for (const rec of Array.isArray(aiResult?.cloudRecommendations)
+    ? aiResult.cloudRecommendations
+    : []) {
+    const norm = normalizeAgentRec({ ...rec });
+    if (hasRejected(norm.model, true)) return true;
+    if ((norm.routing || []).some((r) => hasRejected(r, false))) return true;
+    if ((norm.fallback_models || []).some((r) => hasRejected(r, true)))
+      return true;
+  }
+  for (const decision of aiResult?.localModels?.decisions || []) {
+    if (!resolveFittingLocalName(decision?.name, fittingByName)) return true;
+  }
+  for (const placement of aiResult?.localModels?.placements || []) {
+    if (!resolveFittingLocalName(placement?.modelName, fittingByName))
+      return true;
+  }
+  return false;
+}
+
+/**
+ * Normalize per-agent recommendation from either the old format (flat `recommendations` array)
+ * or the new format (separate `model`, `routing`, `fallback_models` fields).
+ * Always produces the new shape with model/routing/fallback_models.
+ */
+function normalizeAgentRec(rec) {
+  if (!rec || typeof rec !== "object") return rec;
+  // Already has new shape — ensure arrays exist
+  if (rec.model && !rec.recommendations) return rec;
+  // Old shape: flatten recommendations[0] -> model, rest -> fallback_models
+  if (rec.recommendations && Array.isArray(rec.recommendations)) {
+    const r = rec.recommendations.filter((x) => x && x.provider && x.model);
+    if (r.length > 0) {
+      rec.model = r[0];
+      rec.routing = [];
+      rec.fallback_models = r.slice(1);
+    }
+    delete rec.recommendations;
+  }
+  // Ensure fields exist
+  if (!rec.model) rec.model = null;
+  if (!rec.routing) rec.routing = [];
+  if (!rec.fallback_models) rec.fallback_models = [];
+  return rec;
+}
+
+function normalizeRecommendation(rec) {
+  if (!rec || typeof rec !== "object") return null;
+  const provider = String(rec.provider || "").trim();
+  const rawModel = String(rec.model || "").trim();
+  if (!provider && !rawModel) return null;
+
+  const isLocal =
+    provider === "ollama" ||
+    provider === LOCAL_PROVIDER ||
+    rawModel.startsWith("ollama/") ||
+    rawModel.startsWith("local/");
+  let normalizedProvider = provider;
+  let normalizedModel = rawModel;
+
+  if (isLocal) {
+    const localName = normalizeLocalModelName(rawModel);
+    if (!localName) return null;
+    normalizedProvider = LOCAL_PROVIDER;
+    normalizedModel = localName;
+  } else if (provider && rawModel) {
+    const prefix = `${provider}/`;
+    normalizedModel = rawModel.startsWith(prefix)
+      ? rawModel.slice(prefix.length)
+      : rawModel;
+  }
+
+  if (!isLocal) {
+    if (!normalizedProvider) return null;
+    if (!normalizedModel) return null;
+  }
+
+  return { ...rec, provider: normalizedProvider, model: normalizedModel };
+}
+
+function modelRef(provider, modelName) {
+  return formatModelRef(provider, modelName);
+}
+
+function providerState(provider) {
+  if (!providerAvailability.has(provider)) {
+    providerAvailability.set(provider, {
+      creditExhausted: false,
+      rateLimitedUntil: 0,
+      reason: null,
+    });
+  }
+  return providerAvailability.get(provider);
+}
+
+function isProviderAvailable(provider, now = Date.now()) {
+  if (!provider || provider === LOCAL_PROVIDER || provider.startsWith("cli/"))
+    return true;
+  if (opencodeOnlyMode && provider !== "opencode")
+    return false;
+  if (quotaExceededProviders.has(provider)) return false;
+  const state = providerAvailability.get(provider);
+  if (!state) return true;
+  if (state.creditExhausted) return false;
+  return !(state.rateLimitedUntil && state.rateLimitedUntil > now);
+}
+
+function markProviderCreditExhausted(provider, reason) {
+  if (!provider) return;
+  quotaExceededProviders.add(provider);
+  const state = providerState(provider);
+  state.creditExhausted = true;
+  state.reason = reason || "credit-exhausted";
+}
+
+function markProviderRateLimited(provider, retryAfterSeconds, reason) {
+  if (!provider) return;
+  const state = providerState(provider);
+  const delayMs = Math.max(1, Number(retryAfterSeconds) || 15) * 1000;
+  state.rateLimitedUntil = Math.max(
+    state.rateLimitedUntil || 0,
+    Date.now() + delayMs,
+  );
+  state.reason = reason || "rate-limited";
+}
+function probeModel(modelRef) {
+  const slash = modelRef.indexOf("/");
+  const provider = slash === -1 ? "" : modelRef.slice(0, slash);
+  if (!provider || provider === LOCAL_PROVIDER || provider === "opencode" || provider.startsWith("cli/")) {
+    return Promise.resolve({ ok: true });
+  }
+
+  if (!isProviderAvailable(provider)) {
+    return Promise.resolve({ ok: false, reason: "provider-unavailable" });
+  }
+
+  if (providerProbePromises.has(provider)) {
+    return providerProbePromises.get(provider);
+  }
+
+  const promise = new Promise((resolve) => {
+    const tempDir = os.tmpdir();
+    const child = spawnTracked(
+      "opencode",
+      [
+        "run",
+        "--pure",
+        "--agent",
+        "summary",
+        "--dir",
+        tempDir,
+        "--format",
+        "json",
+        "--model",
+        modelRef,
+        "--dangerously-skip-permissions",
+        "say 1",
+      ],
+      {
+        cwd: tempDir,
+        env: {
+          ...process.env,
+          PWD: tempDir,
+          INIT_CWD: tempDir,
+          TERM: "dumb",
+        },
+        stdio: ["ignore", "pipe", "pipe"],
+      }
+    );
+
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        child.kill("SIGKILL");
+      } catch (e) {}
+    }, 30000);
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({ ok: false, reason: `spawn-error: ${err.message}` });
+    });
+
+    child.stdout.on("data", (d) => {
+      stdout += d.toString();
+    });
+    child.stderr.on("data", (d) => {
+      stderr += d.toString();
+    });
+
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (timedOut) {
+        markProviderRateLimited(provider, 30, "rate-limited");
+        resolve({ ok: false, reason: "timeout", errorOutput: "Request timed out after 30s" });
+        return;
+      }
+
+      const rawError = (stderr + "\n" + stdout).trim();
+      const lower = rawError.toLowerCase();
+
+      if (
+        code === 402 ||
+        lower.includes("402") ||
+        lower.includes("payment required") ||
+        lower.includes("payment_required") ||
+        lower.includes("quota exceeded") ||
+        lower.includes("quota_exceeded") ||
+        lower.includes("billing limit") ||
+        lower.includes("billing_limit") ||
+        lower.includes("credit limit") ||
+        lower.includes("credit_limit") ||
+        lower.includes("insufficient funds") ||
+        lower.includes("insufficient_funds") ||
+        lower.includes("usage limit") ||
+        lower.includes("budget exceeded") ||
+        lower.includes("budget exhausted") ||
+        lower.includes("quota restricted") ||
+        lower.includes("credit expired") ||
+        lower.includes("credits expired") ||
+        lower.includes("unauthorized") ||
+        lower.includes("forbidden") ||
+        lower.includes("invalid api key") ||
+        lower.includes("invalid_api_key") ||
+        lower.includes("key invalid") ||
+        lower.includes("access denied") ||
+        lower.includes("exhausted") ||
+        lower.includes("restricted") ||
+        lower.includes("limit exceeded") ||
+        lower.includes("limit_exceeded")
+      ) {
+        markProviderCreditExhausted(provider, "quota-exceeded");
+        resolve({ ok: false, reason: "quota-exceeded", errorOutput: rawError });
+        return;
+      }
+
+      if (
+        lower.includes("429") ||
+        lower.includes("rate limit") ||
+        lower.includes("rate_limit") ||
+        lower.includes("too many requests") ||
+        lower.includes("too_many_requests")
+      ) {
+        const delay = parseRetryAfterSeconds(rawError) || 15;
+        markProviderRateLimited(provider, delay, "rate-limited");
+        resolve({ ok: false, reason: "rate-limited", errorOutput: rawError });
+        return;
+      }
+
+      if (code !== 0 && code !== null) {
+        resolve({ ok: false, reason: `exit-code-${code}`, errorOutput: rawError });
+        return;
+      }
+
+      if (code === null) {
+        resolve({ ok: false, reason: "terminated-by-signal", errorOutput: "Process terminated by system signal" });
+        return;
+      }
+
+      resolve({ ok: true });
+    });
+  });
+
+  providerProbePromises.set(provider, promise);
+  return promise;
+}
+
+
+function allConfigEntries(config) {
+  return [
+    ...Object.entries(config.agents || {}).map(([name, section]) => ({
+      name,
+      type: "agent",
+      section,
+    })),
+    ...Object.entries(config.categories || {}).map(([name, section]) => ({
+      name,
+      type: "category",
+      section,
+    })),
+  ];
+}
+
+function uniqueByModelRef(recommendations) {
+  const seen = new Set();
+  const out = [];
+  for (const rec of recommendations) {
+    const normalized = normalizeRecommendation(rec);
+    if (!normalized) continue;
+    const key = modelRef(normalized.provider, normalized.model);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(normalized);
+  }
+  return out;
+}
+
+function finalizeFallbackModels(primary, fallbackModels) {
+  const primaryKey =
+    primary && primary.provider && primary.model
+      ? modelRef(primary.provider, primary.model)
+      : null;
+  return uniqueByModelRef(fallbackModels || []).filter(
+    (rec) => modelRef(rec.provider, rec.model) !== primaryKey,
+  );
+}
+
+// =========================================================================
+// Local model discovery (Ollama registry catalog)
+// =========================================================================
+
+function execCurl(url, accept) {
+  try {
+    const args = ["-s", "--max-time", "8"];
+    if (accept) args.push("-H", accept);
+    args.push(url);
+    return execFileSync("curl", args, {
+      encoding: "utf-8",
+      timeout: 15000,
+      env: { ...process.env, TERM: "dumb" },
+    });
+  } catch (_) {
+    return "";
+  }
+}
+
+function registryModelSizeGb(name, tag) {
+  const url = `https://registry.ollama.ai/v2/library/${encodeURIComponent(name)}/manifests/${encodeURIComponent(tag)}`;
+  const json = execCurl(
+    url,
+    "application/vnd.docker.distribution.manifest.v2+json",
+  );
+  if (!json) return null;
+  try {
+    const manifest = JSON.parse(json);
+    for (const layer of manifest.layers || []) {
+      if (layer.mediaType === "application/vnd.ollama.image.model")
+        return layer.size / 1e9;
+    }
+    return null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function loadCachedModels() {
+  try {
+    if (fs.existsSync(MODEL_CACHE_FILE))
+      return JSON.parse(fs.readFileSync(MODEL_CACHE_FILE, "utf-8"));
+  } catch (_) {}
+  return null;
+}
+
+function saveCachedModels(models) {
+  try {
+    const dir = path.dirname(MODEL_CACHE_FILE);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(
+      MODEL_CACHE_FILE,
+      JSON.stringify(models, null, 2),
+      "utf-8",
+    );
+  } catch (_) {}
+}
+
+function discoverModels(forceRefresh = false, progress = null) {
+  const cached = forceRefresh ? null : loadCachedModels();
+  if (Array.isArray(cached)) {
+    if (progress) progress.done(`${cached.length} cached models`);
+    return cached;
+  }
+  const models = [];
+  const total = KNOWN_MODELS.reduce(
+    (count, entry) => count + entry.tags.length,
+    0,
+  );
+  for (const entry of KNOWN_MODELS) {
+    for (const tag of entry.tags) {
+      const name = `${entry.name}:${tag}`;
+      if (progress) progress.update(`${models.length + 1}/${total} ${name}`);
+      const sizeGb = registryModelSizeGb(entry.name, tag);
+      const bMatch = tag.match(/(\d+(?:\.\d+)?)b/i);
+      const bSize = bMatch ? parseFloat(bMatch[1]) : null;
+      const baseVram = BASE_VRAM[entry.name] || 3;
+      const vram = bSize ? (baseVram / 7) * bSize : baseVram;
+      const score = MODEL_SCORES[entry.name] || 30;
+      models.push({
+        name,
+        size: sizeGb != null ? `${sizeGb.toFixed(1)} GB` : "unknown",
+        vram: Math.round(vram * 10) / 10,
+        score,
+        baseModel: entry.name,
+        tag,
+      });
+    }
+  }
+  if (!forceRefresh) saveCachedModels(models);
+  if (progress) progress.done(`${models.length} models cataloged`);
+  return models;
+}
+
+// =========================================================================
+// GPU / Ollama detection
+// =========================================================================
+
+function detectGPU() {
+  const dumbEnv = { ...process.env, TERM: "dumb" };
+  try {
+    const out = execFileSync(
+      "nvidia-smi",
+      [
+        "--query-gpu=name,memory.total",
+        "--format=csv,noheader,nounits",
+      ],
+      {
+        encoding: "utf-8",
+        timeout: 5000,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: dumbEnv,
+      },
+    );
+    const [name, memStr] = out.trim().split(", ");
+    const memGB = Math.round(parseInt(memStr) / 1024);
+    return {
+      hasGpu: true,
+      name: name.trim(),
+      label: `${name.trim()} (${memGB} GB VRAM)`,
+      vramGb: memGB,
+    };
+  } catch (_) {}
+  try {
+    const out = execFileSync("ollama", ["list"], {
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: dumbEnv,
+    });
+    if (out.includes("NAME"))
+      return {
+        hasGpu: true,
+        name: "unknown GPU",
+        label: "GPU detected (no nvidia-smi)",
+        vramGb: 8,
+      };
+  } catch (_) {}
+  return { hasGpu: false, name: "", label: "No GPU detected", vramGb: 0 };
+}
+
+function detectOllama() {
+  let installed = false,
+    running = false,
+    version = null,
+    models = [];
+  const dumbEnv = { ...process.env, TERM: "dumb" };
+  installed = commandExists("ollama").length > 0;
+  if (installed) {
+    try {
+      version = (
+        execFileSync("ollama", ["--version"], {
+          encoding: "utf-8",
+          timeout: 3000,
+          stdio: ["ignore", "pipe", "pipe"],
+          env: dumbEnv,
+        }) || ""
+      ).trim();
+    } catch (_) {}
+    try {
+      const list = execFileSync("ollama", ["list"], {
+        encoding: "utf-8",
+        timeout: 5000,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: dumbEnv,
+      });
+      running = list.includes("NAME");
+      if (running) {
+        const lines = list.trim().split("\n").slice(1);
+        for (const line of lines) {
+          const parts = line.trim().split(/\s+/);
+          if (parts.length >= 2) {
+            const rawName = parts[0];
+            models.push({
+              name: rawName.includes(":") ? rawName : `${rawName}:latest`,
+              size: parts[1] || "unknown",
+            });
+          }
+        }
+      }
+    } catch (_) {}
+  }
+  return { installed, running, version, models };
+}
+
+// =========================================================================
+// Tier chain construction + rebalance (algorithmic path)
+// =========================================================================
+
+function buildTierChains(modelCache, providerAliases) {
+  const chains = { reasoning: [], balanced: [], fast: [] };
+  for (const [provider, modelMap] of Object.entries(modelCache.byId || {})) {
+    if (!modelMap || modelMap.size === 0) continue;
+    if (provider === "local") continue;
+    const scored = [];
+    for (const [id, meta] of modelMap) {
+      scored.push({
+        model: `${provider}/${id}`,
+        score: scoreModel(`${provider}/${id}`, null, meta),
+        variant: null,
+      });
+    }
+    if (scored.length === 0) continue;
+    scored.sort((a, b) => b.score - a.score);
+    const n = scored.length;
+    chains.reasoning.push(scored[0]);
+    chains.balanced.push(scored[n <= 2 ? 0 : Math.floor((n - 1) / 2)]);
+    chains.fast.push(scored[n - 1]);
+  }
+  for (const tier of QUALITY_TIERS)
+    chains[tier].sort((a, b) => b.score - a.score);
+  return chains;
+}
+
+function fbToString(fb) {
+  return typeof fb === "string"
+    ? fb
+    : fb.model + (fb.variant ? ":" + fb.variant : "");
+}
+
+function applyTierChain(entry, tierChain) {
+  if (!tierChain || tierChain.length === 0) return { changed: false };
+  const newModel = tierChain[0].model;
+  const newVariant = tierChain[0].variant || null;
+  const newFallbacks = tierChain.slice(1).map((c) => {
+    const fb = { model: c.model };
+    if (c.variant) fb.variant = c.variant;
+    return fb;
+  });
+  const oldModelStr = entry.model + (entry.variant ? ":" + entry.variant : "");
+  const newModelStr = newModel + (newVariant ? ":" + newVariant : "");
+  const oldFbStr = (entry.fallback_models || []).map(fbToString).join(",");
+  const newFbStr = newFallbacks.map(fbToString).join(",");
+  if (oldModelStr === newModelStr && oldFbStr === newFbStr)
+    return { changed: false };
+  entry.model = newModel;
+  if (newVariant) entry.variant = newVariant;
+  else delete entry.variant;
+  if (newFallbacks.length > 0) entry.fallback_models = newFallbacks;
+  else delete entry.fallback_models;
+  return { changed: true };
+}
+
+function findModelInCache(providerKey, modelID, aliases, lookup) {
+  const realProvider = resolveProvider(providerKey, aliases);
+  const modelMap = lookup.byId[realProvider];
+  if (!modelMap) return null;
+  return (
+    modelMap.get(modelID) ||
+    modelMap.get(`${providerKey}/${modelID}`) ||
+    modelMap.get(`${realProvider}/${modelID}`) ||
+    null
+  );
+}
+
+function rebalanceEntry(entry, options) {
+  if (!entry || typeof entry !== "object") return { changed: false };
+  const {
+    tierChains,
+    withoutFree,
+    unavailableModels,
+    providerAliases,
+    modelCache,
+  } = options;
+  if (tierChains) {
+    const quality = entry.model_quality || "balanced";
+    const tier = tierChains[quality];
+    if (tier && tier.length > 0) {
+      let chain = tier;
+      if (withoutFree)
+        chain = tier.filter(
+          (c) => !FREE_PROVIDERS.includes(c.model.split("/")[0]),
+        );
+      if (chain.length === 0) return { changed: false };
+      const r = applyTierChain(entry, chain);
+      if (r.changed) return { changed: true, reason: `tier: ${quality}` };
+      return r;
+    }
+  }
+  const refs = [];
+  if (entry.model)
+    refs.push({ model: entry.model, variant: entry.variant || null });
+  if (entry.fallback_models) {
+    for (const fb of entry.fallback_models)
+      refs.push({ model: fb.model, variant: fb.variant || null });
+  }
+  if (refs.length === 0) return { changed: false };
+  if (unavailableModels && unavailableModels.size > 0) {
+    const filtered = refs.filter((r) => !unavailableModels.has(r.model));
+    if (filtered.length === 0) {
+      delete entry.model;
+      delete entry.variant;
+      delete entry.fallback_models;
+      return { changed: true, reason: "all models unavailable" };
+    }
+    refs.length = 0;
+    refs.push(...filtered);
+  }
+  const bestPerProvider = {};
+  for (const ref of refs) {
+    const providerKey = ref.model.split("/")[0];
+    const modelPart = ref.model.slice(ref.model.indexOf("/") + 1);
+    const realProvider = resolveProvider(providerKey, aliases);
+    const cacheEntry = findModelInCache(
+      providerKey,
+      modelPart,
+      aliases,
+      modelCache,
+    );
+    const rank = scoreModel(ref.model, ref.variant, cacheEntry);
+    if (
+      !bestPerProvider[realProvider] ||
+      rank > bestPerProvider[realProvider].rank
+    ) {
+      bestPerProvider[realProvider] = { ...ref, provider: providerKey, rank };
+    }
+  }
+  let candidates = Object.values(bestPerProvider);
+  if (withoutFree)
+    candidates = candidates.filter((c) => !FREE_PROVIDERS.includes(c.provider));
+  if (candidates.length === 0) return { changed: false };
+  candidates.sort((a, b) => b.rank - a.rank);
+  const newModel = candidates[0].model;
+  const newVariant = candidates[0].variant;
+  const newFallbacks = candidates.slice(1).map((c) => {
+    const fb = { model: c.model };
+    if (c.variant) fb.variant = c.variant;
+    return fb;
+  });
+  const oldModelStr = entry.model + (entry.variant ? ":" + entry.variant : "");
+  const newModelStr = newModel + (newVariant ? ":" + newVariant : "");
+  const oldFbStr = (entry.fallback_models || []).map(fbToString).join(",");
+  const newFbStr = newFallbacks.map(fbToString).join(",");
+  if (oldModelStr === newModelStr && oldFbStr === newFbStr)
+    return { changed: false };
+  entry.model = newModel;
+  if (newVariant) entry.variant = newVariant;
+  else delete entry.variant;
+  if (newFallbacks.length > 0) entry.fallback_models = newFallbacks;
+  else delete entry.fallback_models;
+  return { changed: true };
+}
+
+function rebalanceConfig(config, options) {
+  const changes = [];
+  for (const [name, agent] of Object.entries(config.agents || {})) {
+    if (agent.model || agent.fallback_models) {
+      const r = rebalanceEntry(agent, options);
+      if (r.changed)
+        changes.push(`agents.${name}${r.reason ? ` — ${r.reason}` : ""}`);
+    }
+  }
+  for (const [name, cat] of Object.entries(config.categories || {})) {
+    if (cat.model || cat.fallback_models) {
+      const r = rebalanceEntry(cat, options);
+      if (r.changed)
+        changes.push(`categories.${name}${r.reason ? ` — ${r.reason}` : ""}`);
+    }
+  }
+  return changes;
+}
+
+// =========================================================================
+// Display functions
+// =========================================================================
+
+function showCloudRecommendations(aiResult, config) {
+  if (
+    !aiResult.cloudRecommendations ||
+    aiResult.cloudRecommendations.length === 0
+  )
+    return [];
+  const changes = [];
+  for (const rec of aiResult.cloudRecommendations) {
+    const section = config.agents?.[rec.name] || config.categories?.[rec.name];
+    if (!section) continue;
+
+    const pathPrefix = rec.type === "category" ? "categories" : "agents";
+
+    // Current config values
+    const prevModel = section.model;
+    let prevModelAvailable = false;
+    if (prevModel) {
+      const parts = prevModel.split("/");
+      const prevProv = parts[0];
+      if (isProviderAvailable(prevProv)) {
+        prevModelAvailable = true;
+      }
+    }
+
+    // New recommendations (already normalized to rec.model / rec.fallback_models)
+    const newModel =
+      rec.model && rec.model.provider && rec.model.model
+        ? `${rec.model.provider}/${rec.model.model}`
+        : (prevModelAvailable ? prevModel : null);
+    const newFallbacks = (rec.fallback_models || [])
+      .filter((r) => r.provider && r.model)
+      .map((r) => `${r.provider}/${r.model}`);
+    const newRouting = (rec.routing || [])
+      .filter((r) => r.provider && r.model)
+      .map((r) => `${r.provider}/${r.model}`);
+
+    const modelChanged = (prevModel || null) !== newModel;
+    const hasPrevConfig =
+      prevModel ||
+      (section.fallback_models && section.fallback_models.length > 0);
+    const anyChanged =
+      modelChanged || newFallbacks.length > 0 || newRouting.length > 0;
+
+    // Skip agents with no current config AND no recommendation — pure noise
+    if (!anyChanged && !hasPrevConfig) continue;
+
+    if (anyChanged) changes.push({ section, name: rec.name });
+
+    // Bulleted preview block
+    console.log(`  \u2022 ${pathPrefix}.${rec.name}`);
+    console.log(`    model: ${newModel || ""}`);
+    if (newRouting.length > 0)
+      console.log(`    routing: ${newRouting.join(", ")}`);
+    if (newFallbacks.length > 0)
+      console.log(`    fallback_models: ${newFallbacks.join(", ")}`);
+    console.log();
+  }
+  return changes;
+}
+
+function showLocalDecisions(aiResult, allLocalModels, ollama) {
+  if (!aiResult.localModels) return;
+  const { decisions, placements } = aiResult.localModels;
+
+  if (decisions && decisions.length > 0) {
+    const installs = decisions.filter((d) => d.action === "install");
+    const keeps = decisions.filter((d) => d.action === "keep");
+    const uninstalls = decisions.filter((d) => d.action === "uninstall");
+    const skips = decisions.filter((d) => d.action === "skip");
+
+    // Placements first
+    if (placements && placements.length > 0) {
+      console.log(
+        `\n── AI: Local config placements (${placements.length}) ────────`,
+      );
+      for (const p of placements) {
+        console.log(
+          `  \u2022 ${p.modelName} \u2192 ${p.agentName} (${p.role})`,
+        );
+        if (p.justification)
+          console.log(`    Justification: ${p.justification}`);
+      }
+    }
+
+    if (installs.length > 0) {
+      console.log(
+        `\n── AI: Install (${installs.length}) ────────────────────────`,
+      );
+      for (const d of installs) {
+        const m = allLocalModels.find((x) => x.name === d.name);
+        const extra = m
+          ? `  (${m.size}, ${m.vram} GB VRAM, score ${m.score})`
+          : "";
+        console.log(`  \u2022 ${d.name}${extra}`);
+        console.log(`    ${d.rationale}`);
+      }
+    }
+    if (keeps.length > 0) {
+      console.log(`\n── AI: Keep (${keeps.length}) ──────────────────────────`);
+      for (const d of keeps) {
+        const m = allLocalModels.find((x) => x.name === d.name);
+        const extra = m
+          ? `  (${m.size}, ${m.vram} GB VRAM, score ${m.score})`
+          : "";
+        console.log(`  \u2022 ${d.name}${extra}`);
+        console.log(`    ${d.rationale}`);
+      }
+    }
+    if (uninstalls.length > 0) {
+      console.log(
+        `\n── AI: Uninstall (${uninstalls.length}) ────────────────────`,
+      );
+      for (const d of uninstalls) {
+        const m = allLocalModels.find((x) => x.name === d.name);
+        const extra = m
+          ? `  (${m.size}, ${m.vram} GB VRAM, score ${m.score})`
+          : "";
+        const isInstalled = ollama.models.some((x) => x.name === d.name);
+        console.log(`  \u2022 ${d.name}${extra}`);
+        console.log(`    ${d.rationale}`);
+        if (!isInstalled) console.log(`    (not installed, nothing to remove)`);
+      }
+    }
+    if (skips.length > 0) {
+      console.log(`\n── AI: Skip (${skips.length}) ──────────────────────────`);
+      for (const d of skips) {
+        const m = allLocalModels.find((x) => x.name === d.name);
+        const extra = m
+          ? `  (${m.size}, ${m.vram} GB VRAM, score ${m.score})`
+          : "";
+        console.log(`  \u2022 ${d.name}${extra}`);
+        console.log(`    ${d.rationale}`);
+      }
+    }
+  }
+}
+
+// =========================================================================
+// CLI agent discovery — optional panel members
+// =========================================================================
+
+/**
+ * Discover AI CLI agents available on PATH that can be queried for
+ * recommendations alongside panel models. Returns an array of
+ * { ref, call } where ref is like "cli/codex" and call is
+ * an async function(prompt) => parsed JSON or null.
+ */
+function discoverCliModels(config = {}) {
+  const agents = [];
+
+  function parseCliJson(raw) {
+    const jsonMatch = String(raw || "").match(/\{[\s\S]*\}/);
+    if (!jsonMatch) return null;
+    return JSON.parse(jsonMatch[0]);
+  }
+
+  function renderCliCommand(command, prompt) {
+    if (Array.isArray(command)) {
+      const rendered = command.map((part) =>
+        String(part).replaceAll("{prompt}", prompt),
+      );
+      if (!rendered.some((part) => part.includes(prompt))) rendered.push(prompt);
+      return rendered;
+    }
+    const promptArg = JSON.stringify(prompt);
+    const raw = String(command || "").trim();
+    if (!raw) return "";
+    return raw.includes("{prompt}")
+      ? raw.replaceAll("{prompt}", promptArg)
+      : `${raw} ${promptArg}`;
+  }
+
+  function inferCliBinary(entry, id) {
+    if (entry?.binary) return String(entry.binary).trim();
+    const command = entry?.command;
+    if (Array.isArray(command)) return String(command[0] || id).trim();
+    return String(command || id).trim().split(/\s+/)[0];
+  }
+
+  const cliAdapters = [
+    {
+      binary: "codex",
+      ref: "cli/codex",
+      command: (prompt) =>
+        [
+          "codex",
+          "run",
+          "--model",
+          "opencode/big-pickle",
+          "--preset",
+          "json",
+          "--dangerously-skip-permissions",
+          prompt,
+        ],
+    },
+    {
+      binary: "agy",
+      ref: "cli/agy",
+      command: (prompt) =>
+        ["agy", "--print", "--dangerously-skip-permissions", prompt],
+    },
+  ];
+
+  const configuredAgents = config?.omo?.panel_cli_agents;
+  if (configuredAgents && typeof configuredAgents === "object") {
+    for (const [name, entry] of Object.entries(configuredAgents)) {
+      const id = String(entry?.id || name || "").trim();
+      const command = entry?.command;
+      if (!id || !command) continue;
+      cliAdapters.push({
+        binary: inferCliBinary(entry, id),
+        ref: `cli/${id.replace(/^cli\//, "")}`,
+        command: (prompt) => renderCliCommand(command, prompt),
+      });
+    }
+  }
+
+  // CLI agents on PATH can participate alongside provider-backed models.
+  for (const adapter of cliAdapters) {
+    try {
+      const which = commandExists(adapter.binary);
+      if (which) {
+        agents.push({
+          ref: adapter.ref,
+          call: async (prompt) => {
+            try {
+              const cmd = adapter.command(prompt);
+              if (!cmd) return null;
+              const options = {
+                encoding: "utf-8",
+                timeout: 120000,
+                maxBuffer: 1024 * 1024,
+                stdio: ["ignore", "pipe", "pipe"],
+                env: { ...process.env, TERM: "dumb" },
+              };
+              const raw = Array.isArray(cmd)
+                ? execFileSync(cmd[0], cmd.slice(1), options)
+                : execSync(cmd, { ...options, shell: "/bin/sh" });
+              return parseCliJson(raw);
+            } catch {}
+            return null;
+          },
+        });
+      }
+    } catch {
+      /* not found */
+    }
+  }
+
+  // Try workshop discovery script if available
+  try {
+    const workshop = commandExists("tools/workshop-shell");
+    if (workshop) {
+      // Discovery would parse the script output and add more agents
+    }
+  } catch {
+    /* not available */
+  }
+
+  return agents;
+}
+
+// =========================================================================
+// AI Panel — multi-model consensus & debate
+// =========================================================================
+const PANEL_MODEL_TIMEOUT_SECONDS = Math.max(
+  120,
+  Number.parseInt(process.env.OMO_PANEL_MODEL_TIMEOUT_SECONDS || "180", 10) ||
+    180,
+);
+
+const PANEL_FIRST_BYTE_TIMEOUT_SECONDS = Math.max(
+  60,
+  Number.parseInt(
+    process.env.OMO_PANEL_FIRST_BYTE_TIMEOUT_SECONDS ||
+      String(PANEL_MODEL_TIMEOUT_SECONDS),
+    10,
+  ) || PANEL_MODEL_TIMEOUT_SECONDS,
+);
+
+function killChild(child) {
+  if (child.exitCode === null && child.signalCode === null)
+    child.kill("SIGTERM");
+  setTimeout(() => {
+    if (child.exitCode === null && child.signalCode === null)
+      child.kill("SIGKILL");
+  }, 5000);
+}
+
+function compactErrorText(text) {
+  return (text || "")
+    .replace(/\x1b\[[0-9;]*m/g, "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .slice(-3)
+    .join(" ");
+}
+
+function parseRetryAfterSeconds(text) {
+  const raw = String(text || "");
+  const numericPatterns = [
+    /retry-after["']?\s*[:=]\s*["']?(\d+)/i,
+    /retry_after["']?\s*[:=]\s*["']?(\d+)/i,
+    /retryAfter["']?\s*[:=]\s*["']?(\d+)/i,
+    /x-ratelimit-reset["']?\s*[:=]\s*["']?(\d+)/i,
+    /x-rate-limit-reset["']?\s*[:=]\s*["']?(\d+)/i,
+  ];
+  for (const pattern of numericPatterns) {
+    const match = raw.match(pattern);
+    if (!match) continue;
+    const value = Number.parseInt(match[1], 10);
+    if (!Number.isFinite(value)) continue;
+    if (pattern.source.includes("reset") && value > 1000000000) {
+      return Math.max(1, value - Math.floor(Date.now() / 1000));
+    }
+    return Math.max(1, value);
+  }
+
+  const dateMatch = raw.match(/retry-after["']?\s*[:=]\s*["']?([^"'\r\n]+)/i);
+  if (dateMatch) {
+    const ts = Date.parse(dateMatch[1].trim());
+    if (Number.isFinite(ts))
+      return Math.max(1, Math.ceil((ts - Date.now()) / 1000));
+  }
+  return null;
+}
+
+function extractOpencodeText(stdout) {
+  const texts = [];
+  for (const line of stdout.trim().split("\n")) {
+    try {
+      const evt = JSON.parse(line);
+      if (evt.type === "text" && evt.part && evt.part.text) {
+        texts.push(evt.part.text);
+      }
+    } catch (_) {}
+  }
+  return texts.join("") || null;
+}
+
+function callPanelModelAsync(model, prompt, signal, statusRef) {
+  return new Promise((resolve) => {
+    const tempDir = os.tmpdir();
+    const child = spawnTracked(
+      "opencode",
+      [
+        "run",
+        "--pure",
+        "--agent",
+        "summary",
+        "--dir",
+        tempDir,
+        "--format",
+        "json",
+        "--model",
+        model,
+        "--dangerously-skip-permissions",
+        prompt,
+      ],
+      {
+        cwd: tempDir,
+        env: {
+          ...process.env,
+          PWD: tempDir,
+          INIT_CWD: tempDir,
+          TERM: "dumb",
+        },
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    );
+
+    let stdout = "";
+    let stderr = "";
+    let timersCleaned = false;
+    const cleanupTimers = () => {
+      if (timersCleaned) return;
+      timersCleaned = true;
+      clearTimeout(firstByteTimer);
+      clearTimeout(totalTimer);
+    };
+
+    const firstByteTimer = setTimeout(() => {
+      if (statusRef) statusRef.failReason = "first-byte-timeout";
+      killChild(child);
+    }, PANEL_FIRST_BYTE_TIMEOUT_SECONDS * 1000);
+
+    const totalTimer = setTimeout(() => {
+      if (statusRef) statusRef.failReason = "total-timeout";
+      killChild(child);
+    }, PANEL_MODEL_TIMEOUT_SECONDS * 1000);
+
+    let firstByteReceived = false;
+    child.stdout.on("data", (data) => {
+      if (!firstByteReceived) {
+        firstByteReceived = true;
+        clearTimeout(firstByteTimer);
+      }
+      stdout += data.toString();
+      if (statusRef) {
+        statusRef.phase = "receiving";
+        statusRef.bytes = stdout.length;
+      }
+    });
+
+    child.stderr.on("data", (data) => {
+      stderr += data.toString();
+      if (statusRef) statusRef.stderr = compactErrorText(stderr);
+    });
+
+    child.on("error", (err) => {
+      cleanupTimers();
+      if (statusRef) {
+        statusRef.failReason = "spawn-error";
+        statusRef.stderr = err.message;
+      }
+      resolve(null);
+    });
+
+    child.on("close", (code) => {
+      cleanupTimers();
+      if (signal && signal.aborted) {
+        if (statusRef) statusRef.failReason = "aborted";
+        return resolve(null);
+      }
+
+      // Detect quota / billing errors from stdout/stderr or exit code
+      if (statusRef) {
+        const rawError = stderr + "\n" + stdout;
+        const lower = rawError.toLowerCase();
+        if (
+          code === 402 ||
+          lower.includes("402") ||
+          lower.includes("payment required") ||
+          lower.includes("payment_required") ||
+          lower.includes("quota exceeded") ||
+          lower.includes("quota_exceeded") ||
+          lower.includes("billing limit") ||
+          lower.includes("billing_limit") ||
+          lower.includes("credit limit") ||
+          lower.includes("credit_limit") ||
+          lower.includes("insufficient funds") ||
+          lower.includes("insufficient_funds") ||
+          lower.includes("usage limit") ||
+          lower.includes("budget exceeded")
+        ) {
+          statusRef.quotaExceeded = true;
+          statusRef.creditExhausted = true;
+          if (!statusRef.failReason) statusRef.failReason = "quota-exceeded";
+          statusRef.stderr = compactErrorText(stderr || stdout);
+        }
+      }
+
+      // Detect rate limiting from stdout/stderr text
+      if (statusRef) {
+        const rawError = stderr + "\n" + stdout;
+        const lower = rawError.toLowerCase();
+        if (
+          lower.includes("429") ||
+          lower.includes("rate limit") ||
+          lower.includes("too many requests")
+        ) {
+          statusRef.rateLimited = true;
+          statusRef.retryAfter =
+            parseRetryAfterSeconds(rawError) || statusRef.retryAfter || 15;
+          if (!statusRef.failReason) statusRef.failReason = "rate-limited";
+          statusRef.stderr = compactErrorText(stderr || stdout);
+        }
+      }
+
+      if (!stdout) {
+        if (statusRef) {
+          if (!statusRef.failReason)
+            statusRef.failReason = code ? "process-error" : "empty-response";
+          if (!statusRef.stderr) statusRef.stderr = compactErrorText(stderr);
+        }
+        return resolve(null);
+      }
+      const text = extractOpencodeText(stdout);
+      if (!text && statusRef) {
+        statusRef.failReason = "empty-text";
+        statusRef.stderr = compactErrorText(stderr);
+      }
+      resolve(text);
+    });
+
+    if (signal) {
+      signal.addEventListener(
+        "abort",
+        () => {
+          cleanupTimers();
+          if (statusRef) statusRef.failReason = "aborted";
+          killChild(child);
+        },
+        { once: true },
+      );
+    }
+  });
+}
+
+/**
+ * Try to parse AI text as JSON with the expected schema.
+ * Strips markdown fences and attempts JSON.parse.
+ * Returns null on failure (no throw).
+ */
+/**
+ * When raw AI output isn't valid JSON, ask another model to clean it.
+ * Returns the cleaned text or null.
+ */
+async function cleanAiResponse(raw) {
+  const models = discoverFreeModels();
+  if (models.length === 0) return null;
+  const model = models[0];
+  const prompt = [
+    "Extract ONLY the JSON object from the text below.",
+    "If there are multiple JSON objects return the LARGEST one.",
+    "Return valid JSON and nothing else. No markdown fences. No explanation.",
+    "",
+    raw,
+  ].join("\n");
+  try {
+    const result = await callPanelModelAsync(model, prompt, null, {});
+    return result || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Call one free model for a per-agent prompt, returning a single
+ * recommendation entry or null on failure. Retries on 429 rate-limit
+ * with exponential backoff respecting Retry-After headers.
+ */
+async function callModelForAgent(
+  model,
+  prompt,
+  signal,
+  statusRef,
+  cliModels,
+  agentName,
+  maxRetries = 3,
+) {
+  // CLI agents use a different dispatch path
+  if (model.startsWith("cli/")) {
+    const cliAgent = (cliModels || []).find((a) => a.ref === model);
+    if (cliAgent) {
+      const parsed = await cliAgent.call(prompt);
+      if (!parsed) return null;
+      if (parsed && !parsed.name && agentName) {
+        parsed.name = agentName;
+      }
+      const rec = normalizeAgentRec(parsed);
+      if (!rec || !rec.name || (rec.model !== null && (!rec.model.provider || !rec.model.model))) return null;
+      return rec;
+    }
+    return null;
+  }
+
+  const provider = model.split("/")[0];
+  if (!isProviderAvailable(provider)) {
+    if (statusRef) {
+      const state = providerAvailability.get(provider);
+      statusRef.failReason = state?.creditExhausted
+        ? "quota-exceeded"
+        : "rate-limited";
+      statusRef.stderr = `Skipped: provider unavailable (${statusRef.failReason})`;
+    }
+    return null;
+  }
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    const raw = await callPanelModelAsync(model, prompt, signal, statusRef);
+    if (raw) {
+      // Got a response — parse and return
+      let parsed = null;
+      try {
+        parsed = parseAiJson(raw);
+      } catch (_) {}
+      if (parsed && !parsed.name && agentName) {
+        parsed.name = agentName;
+      }
+      if (!parsed || !parsed.name || (parsed.model !== null && parsed.model !== undefined && (!parsed.model.provider || !parsed.model.model))) {
+        const cleaned = await cleanAiResponse(raw);
+        if (cleaned) {
+          try {
+            parsed = parseAiJson(cleaned);
+          } catch (_) {}
+        }
+      }
+      if (parsed && !parsed.name && agentName) {
+        parsed.name = agentName;
+      }
+      if (!parsed) return null;
+      const rec = normalizeAgentRec(parsed);
+      if (!rec || !rec.name || (rec.model !== null && (!rec.model.provider || !rec.model.model))) return null;
+      return rec;
+    }
+
+    if (statusRef?.quotaExceeded) {
+      markProviderCreditExhausted(provider, statusRef.failReason);
+      return null;
+    }
+
+    // Non-rate-limit failure — don't retry
+    if (!statusRef?.rateLimited) return null;
+
+    // Rate-limited — use Retry-After if the server specified one, else a fixed interval
+    const delay = statusRef.retryAfter || 15;
+    markProviderRateLimited(provider, delay, statusRef.failReason);
+
+    if (statusRef) {
+      statusRef.failReason = `rate-limited retry ${attempt}/${maxRetries} (${delay}s)`;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, delay * 1000));
+
+    // Reset rate-limit flags for next attempt (each retry is a fresh request)
+    if (statusRef) {
+      statusRef.rateLimited = false;
+      statusRef.retryAfter = null;
+      statusRef.failReason = null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Build a compact per-agent prompt showing the entry, available cloud
+ * models (pre-deduplicated by family), and VRAM-fitting local models.
+ */
+function buildAgentPrompt(entry, cloudLookup, allLocalModels, gpu, ollama) {
+  const vramAvail = usableLocalVramGb(gpu);
+  const quality = entry.section.model_quality || "balanced";
+  const desc = entry.section.description || "";
+  const currentModel = entry.section.model || "";
+
+  // Helper to check if a model is free (by ref string naming or metadata cost === 0)
+  const isModelFree = (ref, meta) => {
+    const lowerRef = ref.toLowerCase();
+    if (
+      lowerRef.includes("-free") ||
+      lowerRef.endsWith(":free") ||
+      lowerRef.includes("/free-") ||
+      lowerRef.includes("-free-") ||
+      lowerRef.endsWith("/free")
+    ) {
+      return true;
+    }
+    if (meta) {
+      const cost = meta.cost !== undefined ? meta.cost : (meta.input_price !== undefined ? meta.input_price : null);
+      if (cost !== null && cost !== undefined && cost !== "" && Number(cost) === 0) {
+        return true;
+      }
+    }
+    return false;
+  };
+
+  // 1. Get all available providers (not credit exhausted, not rate limited)
+  const availableProviders = Object.keys(cloudLookup.byId || {}).filter(
+    (provider) => provider !== "local" && isProviderAvailable(provider)
+  );
+
+  // 2. Get the top 10 models for each available provider, plus any free models
+  const candidateModels = [];
+  for (const provider of availableProviders) {
+    const modelMap = cloudLookup.byId[provider] || new Map();
+    const scored = [];
+    for (const [id, meta] of modelMap.entries()) {
+      const ref = `${provider}/${id}`;
+      const score = Math.round(scoreModel(ref, null, meta));
+      const free = isModelFree(ref, meta);
+      scored.push({
+        ref,
+        provider,
+        modelId: id,
+        score,
+        free,
+      });
+    }
+    // Sort by score descending
+    scored.sort((a, b) => b.score - a.score);
+
+    // Take top 10
+    const top10 = scored.slice(0, 10);
+    const top10Refs = new Set(top10.map((m) => m.ref));
+
+    const providerCandidates = [...top10];
+    for (const m of scored) {
+      if (m.free && !top10Refs.has(m.ref)) {
+        providerCandidates.push(m);
+      }
+    }
+    candidateModels.push(...providerCandidates);
+  }
+
+  // Sort all candidate models globally by score descending
+  candidateModels.sort((a, b) => b.score - a.score);
+
+  const FAMILY_LIMITS = {
+    "claude-opus": 1,
+    "claude-sonnet": 1,
+    "claude-haiku": 1,
+    "gpt-pro": 1,
+    "gpt-mini": 1,
+    codex: 1,
+    "gemini-pro": 1,
+    "gemini-flash": 1,
+    "google-gemma": 1,
+    "groq-llama": 1,
+    "groq-gpt-oss": 1,
+    "groq-qwen": 1,
+    "deepseek-chat": 1,
+    "deepseek-reasoner": 1,
+    "deepseek-pro": 1,
+    "opencode-mimo": 1,
+    "opencode-nemotron": 1,
+    "opencode-deepseek": 1,
+    "opencode-north": 1,
+    "opencode-big-pickle": 1,
+  };
+
+  const familyKey = (ref) => {
+    const lower = ref.toLowerCase();
+    
+    // Free opencode models
+    if (lower.startsWith("opencode/")) {
+      if (lower.includes("mimo")) return "opencode-mimo";
+      if (lower.includes("nemotron")) return "opencode-nemotron";
+      if (lower.includes("deepseek")) return "opencode-deepseek";
+      if (lower.includes("north")) return "opencode-north";
+      if (lower.includes("big-pickle")) return "opencode-big-pickle";
+    }
+
+    // Claude
+    if (lower.includes("claude-opus")) return "claude-opus";
+    if (lower.includes("claude-sonnet")) return "claude-sonnet";
+    if (lower.includes("claude-haiku")) return "claude-haiku";
+
+    // GPT
+    if (lower.includes("gpt-5.5-pro") || lower.includes("gpt-5.5") || lower.includes("gpt-5.4")) {
+      return "gpt-pro";
+    }
+    if (lower.includes("gpt-mini") || lower.includes("gpt-5-mini") || lower.includes("gpt-5.4-mini")) {
+      return "gpt-mini";
+    }
+    if (lower.includes("gpt-5.3-codex") || lower.includes("codex")) {
+      return "codex";
+    }
+
+    // Gemini
+    if (lower.includes("gemini-3.5-flash") || lower.includes("gemini-3-flash") || lower.includes("gemini-flash") || lower.includes("gemini-2.5-flash")) {
+      return "gemini-flash";
+    }
+    if (lower.includes("gemini-2.5-pro") || lower.includes("gemini-3.1-pro") || lower.includes("gemini-3-pro") || lower.includes("gemini-pro")) {
+      return "gemini-pro";
+    }
+
+    // Gemma
+    if (lower.includes("gemma")) return "google-gemma";
+
+    // Llama
+    if (lower.includes("llama")) return "groq-llama";
+
+    // GPT OSS
+    if (lower.includes("gpt-oss")) return "groq-gpt-oss";
+
+    // Qwen
+    if (lower.includes("qwen")) return "groq-qwen";
+
+    // Deepseek paid
+    if (lower.startsWith("deepseek/")) {
+      if (lower.includes("reasoner")) return "deepseek-reasoner";
+      if (lower.includes("pro")) return "deepseek-pro";
+      if (lower.includes("chat") || lower.includes("flash")) return "deepseek-chat";
+    }
+
+    return null;
+  };
+
+  const seenModelIds = new Set();
+  const counts = {};
+  const deduped = [];
+  for (const m of candidateModels) {
+    const fam = familyKey(m.ref);
+    if (!fam) continue;
+
+    // Deduplicate same models across multiple providers by model ID (e.g. gemini-2.5-pro)
+    const normModelId = m.modelId.toLowerCase();
+    if (seenModelIds.has(normModelId)) {
+      continue;
+    }
+
+    const limit = FAMILY_LIMITS[fam] || 1;
+    const n = counts[fam] || 0;
+    if (n < limit) {
+      counts[fam] = n + 1;
+      seenModelIds.add(normModelId);
+      deduped.push(m);
+    }
+  }
+  const providersTable = deduped.map((m) => `${m.ref} ${m.score}`).join("\n");
+
+  // Local models — fit VRAM, show install status
+  const installedNames = installedLocalNameSet(ollama);
+  const fitting = buildFittingModels(allLocalModels, gpu);
+  const localTable = fitting
+    .map(
+      (m) =>
+        `${m.name}  v=${m.vram}GB s=${m.score} ${installedNames.has(m.name) ? "inst" : ""}`,
+    )
+    .join("\n");
+
+  return [
+    "OUTPUT: valid JSON only. No markdown.",
+    "",
+    "SCHEMA:",
+    "{",
+    '  "name": str,',
+    '  "type": "agent|category",',
+    '  "profile": str,',
+    '  "model": {"provider": str, "model": str, "reason": str},',
+    '  "routing": [{"provider": str, "model": str, "reason": str}],',
+    '  "fallback_models": [{"provider": str, "model": str, "reason": str}]',
+    "}",
+    "",
+    `AGENT: ${entry.name} | ${entry.type} | ${quality} | cur=${currentModel || "-"} | ${desc}`,
+    "",
+    `HW: GPU=${gpu.label} VRAM=${gpu.vramGb}GB usable=${Math.round(vramAvail * 10) / 10}GB`,
+    "",
+    `CLOUD (${deduped.length}):`,
+    providersTable || "-",
+    "",
+    `LOCAL (${fitting.length} fit VRAM):`,
+    localTable || "-",
+    "",
+    "FIELDS:  model=primary  routing=delegation_pool  fallback_models=retry_pool",
+    "RULES:",
+    "- Sort routing and fallback_models by score descending.",
+    "- Paid/cloud as primary for reasoning/code agents.",
+    "- Free model as fallback unless utility agent (explore/librarian/quick).",
+    "- Prefer highest-scored cloud model for primary unless GPU requirements force local.",
+    "- For utility agents (explore/librarian/quick), use highest-scored FREE cloud as primary.",
+    "- For other agents, prioritize highest-scored paid/cloud model.",
+    "- Place minimum 1 routing entry with highest-scored cloud (or local if only fit).",
+    "- Fill routing pool with next highest-scored cloud models (paid > free).",
+    "- The fallback_models pool must have 3 agents set, ordered by capability:",
+    "  * Slot 1 most closely matches the `model` key, in intelligence and token window.",
+    "  * Slot 2 is a highly available, fast mid-tier model.",
+    "  * Slot 3 is the cheapest, highest-rate-limit model.",
+    "- Remove duplicate entries across model, routing, and fallback_models.",
+    "",
+    "SPECIFIC EXAMPLES:",
+    "",
+    "Case 1 - Reasoning agent (paid/cloud required as primary):",
+    "{",
+    '  "name": "metis",',
+    '  "type": "agent",',
+    '  "profile": "Pre-planning consultant for ambiguous requirements",',
+    '  "model": {"provider": "github-copilot", "model": "claude-opus-4.8", "reason": "Paid cloud model as primary for reasoning/code agent per placement rules"},',
+    '  "routing": [{"provider": "opencode", "model": "nemotron-3-ultra-free", "reason": "Highest-scored cloud free model for delegation pool"},',
+    '           {"provider": "opencode", "model": "north-mini-code-free", "reason": "Second highest-scored cloud free model for delegation pool"}],',
+    '  "fallback_models": [',
+    '    {"provider": "opencode", "model": "gemini-2.5-flash", "reason": "Slot 1: Closely matches primary model in capability/context"},',
+    '    {"provider": "opencode", "model": "mimo-v2.5-free", "reason": "Slot 2: Highly available, fast mid-tier model"},',
+    '    {"provider": "opencode", "model": "north-mini-code-free", "reason": "Slot 3: Cheapest, highest-rate-limit model"}',
+    '  ]',
+    "}",
+    "",
+    "Case 2 - Utility agent (free cloud as primary):",
+    "{",
+    '  "name": "explore",',
+    '  "type": "agent",',
+    '  "profile": "Fast codebase exploration and pattern matching - very lightweight utility work",',
+    '  "model": {"provider": "opencode", "model": "mimo-v2.5-free", "reason": "Free model suitable for lightweight exploration"},',
+    '  "routing": [],',
+    '  "fallback_models": []',
+    "}",
+    "",
+    "Case 3 - Category (free cloud as primary):",
+    "{",
+    '  "name": "visual-engineering",',
+    '  "type": "category",',
+    '  "profile": "Frontend, UI/UX, design, styling, animation",',
+    '  "model": {"provider": "opencode", "model": "nemotron-3-ultra-free", "reason": "Balanced performance for design and visual tasks"},',
+    '  "routing": [],',
+    '  "fallback_models": []',
+    "}",
+    "",
+    "VALIDATION RULES:",
+    "- All providers in routing and fallback_models must be 'opencode' (free) for free agents",
+    "- No local models in routing arrays (only in fallback_models for local fallback)",
+    'Check the "FIELDS" section carefully: model=primary, routing=delegation_pool, fallback_models=retry_pool',
+  ].join("\n");
+}
+
+/**
+ * Run async tasks with a concurrency limit. Each task is a zero-arg async
+ * function. Resolves when all tasks complete.
+ */
+async function runPool(tasks, concurrency) {
+  const results = new Array(tasks.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < tasks.length) {
+      const idx = next++;
+      results[idx] = await tasks[idx]();
+    }
+  };
+  const pool = Array.from({ length: Math.min(concurrency, tasks.length) }, () =>
+    worker(),
+  );
+  await Promise.all(pool);
+  return results;
+}
+
+/**
+ * Interactive model picker: show all available opencode models and let the
+ * user select which ones to include in the panel. Returns the selected
+ * model refs, or null if the user wants the default selection.
+ */
+async function pickPanelModels(config, availablePaid = []) {
+  const free = discoverFreeModels();
+  const combined = [...new Set([...(availablePaid || []), ...free])];
+  const all = sortPanelModelRefs(combined, config);
+  if (all.length === 0) return null;
+
+  console.log(`\nEvaluate these models for opencode OMO agent roles:`);
+  const selectableGroups = printSelectablePanelModelGroups(all, "  ");
+  console.log(`  [a] All (default)`);
+
+  const answer = await promptUser(
+    "Select model families by number (e.g. 1,3,5) or press Enter for all: ",
+  );
+  if (!answer || answer.trim().toLowerCase() === "a" || answer.trim() === "")
+    return null;
+
+  const indices = answer
+    .split(",")
+    .map((s) => parseInt(s.trim(), 10))
+    .filter((n) => !isNaN(n) && n >= 1 && n <= selectableGroups.length);
+  if (indices.length === 0) return null;
+
+  const selected = indices.flatMap((i) => selectableGroups[i - 1].models.map((entry) => entry.ref));
+  return selected;
+}
+
+/**
+ * Per-agent panel: for each agent/category, all panel models vote in
+ * parallel (concurrency-limited). Consensus is determined per-agent by
+ * majority vote on the model field. Shows a compact single-line progress
+ * bar that never corrupts the terminal.
+ */
+async function runPanelAndSelect(
+  config,
+  cloudLookup,
+  allLocalModels,
+  gpu,
+  ollama,
+  cloudOnly,
+  panelModels,
+) {
+  const cliAgents = discoverCliModels(config);
+  let models;
+  if (panelModels && panelModels.length > 0) {
+    models = panelModels;
+  } else {
+    models = defaultPanelModels(config);
+    if (models.length === 0) throw new Error("No free models available");
+  }
+
+  // Pre-flight check the models we are going to use in the panel
+  let availableModels = [];
+  const progress = createProgress("Verifying panel models availability");
+  let probeResults = [];
+  try {
+    probeResults = await Promise.all(models.map((m) => probeModel(m)));
+    availableModels = models.filter((m, i) => probeResults[i].ok);
+    progress.done(`${availableModels.length} of ${models.length} model(s) available`);
+  } catch (err) {
+    progress.done(`error verifying availability: ${err.message}`);
+    availableModels = models;
+  }
+
+  if (availableModels.length === 0) {
+    console.log("\n\u26A0 No panel models are available (all are quota-restricted or rate-limited). Limiting analysis and recommendations to opencode AI models exclusively.");
+    opencodeOnlyMode = true;
+    
+    console.log("\nFailed model details / errors:");
+    for (let i = 0; i < models.length; i++) {
+      const m = models[i];
+      const res = probeResults[i] || { ok: false, reason: "unknown error", errorOutput: "No output" };
+      const errSnippet = res.errorOutput ? res.errorOutput.split("\n")[0] : "unknown error";
+      console.log(`  • ${m}: ${res.reason} (${errSnippet})`);
+    }
+
+    console.log("\nFalling back to free opencode models...");
+    const freeModels = defaultPanelModels(config);
+    if (freeModels.length === 0) {
+      throw new Error("No free models available");
+    }
+    const progress2 = createProgress("Verifying free models availability");
+    try {
+      const probeResults2 = await Promise.all(freeModels.map((m) => probeModel(m)));
+      availableModels = freeModels.filter((m, i) => probeResults2[i].ok);
+      progress2.done(`${availableModels.length} of ${freeModels.length} model(s) available`);
+    } catch (err) {
+      progress2.done(`error verifying availability: ${err.message}`);
+      availableModels = freeModels;
+    }
+    if (availableModels.length === 0) {
+      throw new Error("No available free models found");
+    }
+  }
+
+  models = availableModels;
+
+  const agents = allConfigEntries(config);
+  if (agents.length === 0) throw new Error("No agents or categories in config");
+
+  // Per-agent state
+  const state = agents.map((entry) => ({
+    name: entry.name,
+    type: entry.type,
+    results: [],
+    done: false,
+    consensus: null,
+  }));
+
+  // ── Header (printed once, scrolls naturally) ──
+  console.log();
+  console.log(
+    `== AI Panel: ${agents.length} agents, ${models.length} panel models ==`,
+  );
+  console.log("   Models:");
+
+  // ── Compact single-line status bar (updates via \r) ──
+  const totalTasks = agents.length * models.length;
+  let tasksDone = 0;
+  let agentsDone = 0;
+  let currentAgent = "";
+  const modelSuccessCounts = new Map(models.map((model) => [model, 0]));
+  const countWidth = String(totalTasks).length;
+  const formatCount = (value, total) =>
+    `${String(value).padStart(countWidth, " ")}/${total}`;
+
+  const maxLabelWidth = Math.max(
+    "tasks".length,
+    "agents".length,
+    ...models.map((m) => m.length),
+  );
+  const formatLinePrefix = (label) =>
+    `   \u2022 ${(label + ":").padEnd(maxLabelWidth + 1)} `;
+
+  const statusLineCount = 3;
+  const updateStatus = () => {
+    if (process.stdout.isTTY) {
+      process.stdout.write(`\x1b[${models.length + statusLineCount}F`);
+      for (const model of models) {
+        const count = modelSuccessCounts.get(model) || 0;
+        process.stdout.write(
+          `\x1b[2K${formatLinePrefix(model)}${formatCount(count, agents.length)} successful responses\n`,
+        );
+      }
+      process.stdout.write(`\x1b[2Kevaluating ${currentAgent || "-"}\n`);
+      process.stdout.write(`\x1b[2K${formatLinePrefix("tasks")}${formatCount(tasksDone, totalTasks)}\n`);
+      process.stdout.write(`\x1b[2K${formatLinePrefix("agents")}${formatCount(agentsDone, agents.length)}\n`);
+    }
+  };
+  for (const model of models) {
+    console.log(
+      `${formatLinePrefix(model)}${formatCount(modelSuccessCounts.get(model), agents.length)} successful responses`,
+    );
+  }
+  console.log("evaluating -");
+  console.log(`${formatLinePrefix("tasks")}${formatCount(tasksDone, totalTasks)}`);
+  console.log(`${formatLinePrefix("agents")}${formatCount(agentsDone, agents.length)}`);
+  updateStatus();
+
+  // ── Build task functions ──
+  const taskFns = [];
+  for (let ai = 0; ai < agents.length; ai++) {
+    const entry = agents[ai];
+    const st = state[ai];
+
+    for (const m of models) {
+      taskFns.push(async () => {
+        currentAgent = entry.name;
+        const statusRef = {};
+        const prompt = buildAgentPrompt(
+          entry,
+          cloudLookup,
+          allLocalModels,
+          gpu,
+          ollama,
+        );
+        const rec = await callModelForAgent(m, prompt, null, statusRef, cliAgents, entry.name);
+        if (rec) modelSuccessCounts.set(m, (modelSuccessCounts.get(m) || 0) + 1);
+        st.results.push(rec ? { model: m, recommendation: rec } : null);
+        tasksDone++;
+        if (st.results.length === models.length) agentsDone++;
+        updateStatus();
+      });
+    }
+  }
+
+  // ── Run with concurrency limit ──
+  const concurrency = Math.max(1, os.cpus().length);
+  await runPool(taskFns, concurrency);
+
+  // ── Mark all agents done ──
+  for (const st of state) st.done = true;
+
+  // Final status update
+  currentAgent = "";
+  updateStatus();
+  process.stdout.write("\n"); // new line after the status bar
+
+  // ── Tally votes for all agents ──
+  const cloudRecommendations = [];
+  for (let ai = 0; ai < agents.length; ai++) {
+    const entry = agents[ai];
+    const st = state[ai];
+
+    const validResults = st.results.filter(
+      (r) =>
+        r &&
+        r.recommendation &&
+        r.recommendation.model &&
+        r.recommendation.model.provider,
+    );
+    if (validResults.length === 0) continue;
+
+    const modelVotes = {};
+    const modelReasons = {};
+    const routingVotes = {};
+    const fbVotes = {};
+    for (const { recommendation: rec } of validResults) {
+      if (
+        rec.model &&
+        rec.model.provider &&
+        rec.model.model &&
+        isProviderAvailable(rec.model.provider)
+      ) {
+        const key = `${rec.model.provider}/${rec.model.model}`;
+        modelVotes[key] = (modelVotes[key] || 0) + 1;
+        if (rec.model.reason) modelReasons[key] = rec.model.reason;
+      }
+      for (const r of rec.routing || []) {
+        if (r.provider && r.model && isProviderAvailable(r.provider)) {
+          const key = `${r.provider}/${r.model}`;
+          routingVotes[key] = (routingVotes[key] || 0) + 1;
+        }
+      }
+      for (const r of rec.fallback_models || []) {
+        if (r.provider && r.model && isProviderAvailable(r.provider)) {
+          const key = `${r.provider}/${r.model}`;
+          fbVotes[key] = (fbVotes[key] || 0) + 1;
+        }
+      }
+    }
+
+    const total = validResults.length;
+    const majority = total / 2;
+    const sortedModels = Object.entries(modelVotes).sort((a, b) => b[1] - a[1]);
+
+    let consensusRec = null;
+    if (sortedModels.length > 0) {
+      const [winnerKey, winnerCount] = sortedModels[0];
+      const [provider, ...modelParts] = winnerKey.split("/");
+      consensusRec = {
+        name: entry.name,
+        type: entry.type,
+        profile: entry.section.description || entry.section.model_quality || "",
+        model: {
+          provider,
+          model: modelParts.join("/"),
+          reason: `${winnerCount}/${total} models${modelReasons[winnerKey] ? " \u2014 " + modelReasons[winnerKey] : ""}`,
+        },
+        routing: [],
+        fallback_models: [],
+      };
+
+      // Routing: majority support
+      for (const [key, count] of Object.entries(routingVotes).sort(
+        (a, b) => b[1] - a[1],
+      )) {
+        if (count > majority) {
+          const [rp, ...rm] = key.split("/");
+          consensusRec.routing.push({
+            provider: rp,
+            model: rm.join("/"),
+            reason: `${count}/${total} models`,
+          });
+        }
+      }
+
+      // Fallback: majority support
+      for (const [key, count] of Object.entries(fbVotes).sort(
+        (a, b) => b[1] - a[1],
+      )) {
+        if (count > majority) {
+          const [fp, ...fm] = key.split("/");
+          consensusRec.fallback_models.push({
+            provider: fp,
+            model: fm.join("/"),
+            reason: `${count}/${total} models`,
+          });
+        }
+      }
+
+      // Note if no majority
+      if (winnerCount <= majority) {
+        consensusRec.model.reason = `Plurality (${winnerCount}/${total} models) \u2014 no majority`;
+      }
+    }
+
+    st.consensus = consensusRec;
+    if (consensusRec) cloudRecommendations.push(consensusRec);
+  }
+
+  // Build final result (completeAiRecommendations will fill localModels)
+  const result = {
+    recommender: `panel(${models.map((m) => m.split("/").pop()).join("+")})`,
+    analysis: `Per-agent consensus across ${models.length} panel models for ${agents.length} agent(s)`,
+    cloudRecommendations,
+    localModels: { decisions: [], placements: [] },
+  };
+
+  return { selected: result, panel: { state, models } };
+}
+
+function installedLocalNameSet(ollama) {
+  return new Set(
+    (ollama.models || [])
+      .map((m) => normalizeLocalModelName(m.name))
+      .filter(Boolean),
+  );
+}
+
+function bestCloudRecommendationForProvider(provider, modelMap) {
+  let best = null;
+  for (const [id, meta] of modelMap || []) {
+    const ref = modelRef(provider, id);
+    const score = scoreModel(ref, null, meta);
+    if (!best || score > best.score) {
+      best = {
+        provider,
+        model: id,
+        reason: `Best available ${provider} fallback`,
+        score,
+      };
+    }
+  }
+  if (!best) return null;
+  const { score: _score, ...rec } = best;
+  return rec;
+}
+
+function bestLocalModel(allLocalModels, gpu, ollama) {
+  const installed = installedLocalNameSet(ollama);
+  const candidates = buildFittingModels(allLocalModels, gpu);
+  candidates.sort((a, b) => {
+    const scoreDiff = (b.score || 0) - (a.score || 0);
+    if (scoreDiff !== 0) return scoreDiff;
+    return (
+      Number(installed.has(normalizeLocalModelName(b.name))) -
+      Number(installed.has(normalizeLocalModelName(a.name)))
+    );
+  });
+  return candidates[0] || null;
+}
+
+function localModelForEntry(aiResult, entryName, allLocalModels, gpu, ollama) {
+  const fittingByName = buildFittingModelMap(allLocalModels, gpu);
+  const placements = aiResult.localModels?.placements || [];
+  const placement = placements.find(
+    (p) => p.agentName === entryName && p.modelName,
+  );
+  if (placement) {
+    const name = resolveFittingLocalName(placement.modelName, fittingByName);
+    if (name) return { name, role: placement.role || "fallback" };
+  }
+
+  const usable = (aiResult.localModels?.decisions || [])
+    .filter((d) => d.action === "install" || d.action === "keep")
+    .map((d) => normalizeLocalModelName(d.name))
+    .filter((name) => resolveFittingLocalName(name, fittingByName));
+  if (usable.length > 0) return { name: usable[0], role: "fallback" };
+
+  const fallback = bestLocalModel(allLocalModels, gpu, ollama);
+  return fallback
+    ? { name: normalizeLocalModelName(fallback.name), role: "fallback" }
+    : null;
+}
+
+function ensureLocalDecision(aiResult, modelName, allLocalModels, gpu, ollama) {
+  const name = resolveFittingLocalName(
+    modelName,
+    buildFittingModelMap(allLocalModels, gpu),
+  );
+  if (!name) return;
+  const installed = installedLocalNameSet(ollama);
+  const action = installed.has(name) ? "keep" : "install";
+  const decisions = aiResult.localModels.decisions;
+  const existing = decisions.find(
+    (d) => normalizeLocalModelName(d.name) === name,
+  );
+  if (existing) {
+    existing.name = name;
+    if (existing.action !== "keep" && existing.action !== "install")
+      existing.action = action;
+    if (!existing.rationale)
+      existing.rationale = "Required as the local fallback model.";
+    return;
+  }
+  decisions.push({
+    name,
+    action,
+    rationale: "Required as the local fallback model.",
+  });
+}
+
+function completeAiRecommendations(
+  aiResult,
+  config,
+  cloudLookup,
+  allLocalModels,
+  gpu,
+  ollama,
+) {
+  const completed = aiResult || {};
+  const fittingByName = buildFittingModelMap(allLocalModels, gpu);
+  completed.localModels = completed.localModels || {
+    decisions: [],
+    placements: [],
+  };
+  completed.localModels.decisions = Array.isArray(
+    completed.localModels.decisions,
+  )
+    ? completed.localModels.decisions
+        .map((d) => ({
+          ...d,
+          name: resolveFittingLocalName(d.name, fittingByName),
+        }))
+        .filter((d) => d.name)
+    : [];
+  completed.localModels.placements = Array.isArray(
+    completed.localModels.placements,
+  )
+    ? completed.localModels.placements
+        .map((p) => ({
+          ...p,
+          modelName: resolveFittingLocalName(p.modelName, fittingByName),
+        }))
+        .filter((p) => p.modelName && p.agentName)
+    : [];
+
+  // Normalize all cloud recommendations to the new shape
+  const entries = allConfigEntries(config);
+  const recByName = new Map();
+  for (const rec of Array.isArray(completed.cloudRecommendations)
+    ? completed.cloudRecommendations
+    : []) {
+    if (!rec || !rec.name) continue;
+    const norm =
+      rec.model || rec.recommendations ? normalizeAgentRec({ ...rec }) : rec;
+    norm.model = normalizeLocalRecommendation(norm.model, fittingByName, true);
+    if (norm.model && !isProviderAvailable(norm.model.provider)) {
+      norm.model = null;
+    }
+    norm.routing = (norm.routing || [])
+      .map((r) => normalizeLocalRecommendation(r, fittingByName, false))
+      .filter((r) => r && isProviderAvailable(r.provider));
+    norm.fallback_models = (norm.fallback_models || [])
+      .map((r) => normalizeLocalRecommendation(r, fittingByName, true))
+      .filter((r) => r && isProviderAvailable(r.provider));
+    recByName.set(norm.name, norm);
+  }
+
+  const cloudProviders = Object.entries(cloudLookup.byId || {}).filter(
+    ([provider, modelMap]) =>
+      provider !== LOCAL_PROVIDER &&
+      modelMap &&
+      modelMap.size > 0 &&
+      isProviderAvailable(provider),
+  );
+
+  for (const entry of entries) {
+    let rec = recByName.get(entry.name);
+    if (!rec) {
+      rec = {
+        name: entry.name,
+        type: entry.type,
+        profile: entry.section.description || entry.section.model_quality || "",
+        model: null,
+        routing: [],
+        fallback_models: [],
+      };
+    }
+    rec.type = rec.type || entry.type;
+    rec.profile =
+      rec.profile ||
+      entry.section.description ||
+      entry.section.model_quality ||
+      "";
+    rec.model = normalizeLocalRecommendation(rec.model, fittingByName, true);
+    if (rec.model && !isProviderAvailable(rec.model.provider)) {
+      rec.model = null;
+    }
+    rec.routing = (rec.routing || [])
+      .map((r) => normalizeLocalRecommendation(r, fittingByName, false))
+      .filter((r) => r && isProviderAvailable(r.provider));
+    rec.fallback_models = (rec.fallback_models || [])
+      .map((r) => normalizeLocalRecommendation(r, fittingByName, true))
+      .filter((r) => r && isProviderAvailable(r.provider));
+
+    // Collect present providers across model + routing + fallback_models
+    const presentProviders = new Set();
+    if (rec.model && rec.model.provider)
+      presentProviders.add(rec.model.provider);
+    for (const r of rec.routing) {
+      if (r.provider) presentProviders.add(r.provider);
+    }
+    for (const r of rec.fallback_models) {
+      if (r.provider) presentProviders.add(r.provider);
+    }
+
+    // Fill in missing cloud providers as fallback_models
+    for (const [provider, modelMap] of cloudProviders) {
+      if (presentProviders.has(provider)) continue;
+      const fallback = bestCloudRecommendationForProvider(provider, modelMap);
+      if (fallback) {
+        rec.fallback_models.push(fallback);
+        presentProviders.add(provider);
+      }
+    }
+
+    // Add local model if missing
+    const localPick = localModelForEntry(
+      completed,
+      entry.name,
+      allLocalModels,
+      gpu,
+      ollama,
+    );
+    if (localPick && !presentProviders.has(LOCAL_PROVIDER)) {
+      const localRec = {
+        provider: LOCAL_PROVIDER,
+        model: localPick.name,
+        reason:
+          localPick.role === "primary"
+            ? "Local primary selected for this role"
+            : "Local fallback for offline or quota-limited operation",
+      };
+      if (localPick.role === "primary") {
+        // Move current model to fallback, promote local to model
+        if (rec.model) rec.fallback_models.unshift(rec.model);
+        rec.model = localRec;
+      } else {
+        rec.fallback_models.push(localRec);
+      }
+      presentProviders.add(LOCAL_PROVIDER);
+    }
+
+    if (localPick) {
+      ensureLocalDecision(
+        completed,
+        localPick.name,
+        allLocalModels,
+        gpu,
+        ollama,
+      );
+      if (
+        !completed.localModels.placements.some(
+          (p) => p.agentName === entry.name,
+        )
+      ) {
+        completed.localModels.placements.push({
+          modelName: localPick.name,
+          agentName: entry.name,
+          role: localPick.role || "fallback",
+          justification: "Required as the local fallback model.",
+        });
+      }
+    }
+
+    // Deduplicate and order runtime fallbacks after all sources have contributed.
+    rec.fallback_models = finalizeFallbackModels(
+      rec.model,
+      rec.fallback_models,
+    );
+    if (!rec.model && rec.fallback_models.length > 0) {
+      rec.model = rec.fallback_models.shift();
+    }
+    rec.routing = uniqueByModelRef(rec.routing);
+    recByName.set(entry.name, rec);
+  }
+
+  const seenDecisionNames = new Set();
+  completed.localModels.decisions = completed.localModels.decisions.filter(
+    (d) => {
+      const name = resolveFittingLocalName(d.name, fittingByName);
+      if (!name || seenDecisionNames.has(name)) return false;
+      seenDecisionNames.add(name);
+      d.name = name;
+      return true;
+    },
+  );
+  completed.cloudRecommendations = entries
+    .map((entry) => recByName.get(entry.name))
+    .filter(Boolean);
+  return completed;
+}
+
+// =========================================================================
+// Apply functions
+// =========================================================================
+
+async function applyCloudChanges(aiResult, config, autoYes) {
+  if (
+    !aiResult.cloudRecommendations ||
+    aiResult.cloudRecommendations.length === 0
+  )
+    return 0;
+  let count = 0;
+  for (const rec of aiResult.cloudRecommendations) {
+    const section = config.agents?.[rec.name] || config.categories?.[rec.name];
+    if (!section) continue;
+    if (rec.model) {
+      section.model = `${rec.model.provider}/${rec.model.model}`;
+      if (rec.routing && rec.routing.length > 0) {
+        section.routing = rec.routing.map((r) => `${r.provider}/${r.model}`);
+      } else if (section.routing) {
+        delete section.routing;
+      }
+      if (rec.fallback_models && rec.fallback_models.length > 0) {
+        section.fallback_models = rec.fallback_models.map(
+          (r) => `${r.provider}/${r.model}`,
+        );
+      } else if (section.fallback_models) {
+        delete section.fallback_models;
+      }
+      count++;
+    }
+  }
+  return count;
+}
+
+async function applyLocalPlacements(
+  placements,
+  config,
+  autoYes,
+  allLocalModels,
+) {
+  if (!placements || placements.length === 0) return 0;
+  const byAgent = {};
+  for (const p of placements) {
+    const section =
+      config.agents?.[p.agentName] || config.categories?.[p.agentName];
+    if (!section) {
+      console.log(
+        `  \u26A0 Agent/category "${p.agentName}" not found in config \u2014 skipping`,
+      );
+      continue;
+    }
+    if (!byAgent[p.agentName]) byAgent[p.agentName] = [];
+    byAgent[p.agentName].push({
+      section,
+      modelName: normalizeLocalModelName(p.modelName),
+      role: p.role,
+    });
+  }
+  if (Object.keys(byAgent).length === 0) return 0;
+
+  let changed = 0;
+  for (const [agentName, entries] of Object.entries(byAgent)) {
+    const section = entries[0].section;
+
+    // Only keep the highest-scored local model per agent
+    let bestEntry = entries[0];
+    let bestScore = -1;
+    for (const e of entries) {
+      const m = allLocalModels.find((x) => x.name === e.modelName);
+      const s = m ? m.score : 0;
+      if (s > bestScore) {
+        bestScore = s;
+        bestEntry = e;
+      }
+    }
+
+    const localRef = modelRef(LOCAL_PROVIDER, bestEntry.modelName);
+    const existingFbs = Array.isArray(section.fallback_models)
+      ? section.fallback_models
+          .map((fb) => (typeof fb === "string" ? fb : fb.model))
+          .filter(Boolean)
+      : [];
+    const cleaned = existingFbs.filter(
+      (fb) => !fb.startsWith("local/") && !fb.startsWith("ollama/"),
+    );
+
+    if (bestEntry.role === "primary") {
+      const previousPrimary =
+        section.model &&
+        !section.model.startsWith("local/") &&
+        !section.model.startsWith("ollama/")
+          ? section.model
+          : null;
+      section.model = localRef;
+      const fallbacks = previousPrimary
+        ? [previousPrimary, ...cleaned]
+        : cleaned;
+      section.fallback_models = [...new Set(fallbacks)];
+      if (section.fallback_models.length === 0) delete section.fallback_models;
+      changed++;
+      console.log(`  \u2713 ${agentName}: local primary set to ${localRef}`);
+    } else if (
+      section.model &&
+      !section.model.startsWith("local/") &&
+      !section.model.startsWith("ollama/")
+    ) {
+      // Has cloud primary — add only the best local model as a fallback
+      section.fallback_models = [...new Set([...cleaned, localRef])];
+      changed++;
+      console.log(`  \u2713 ${agentName}: local fallback set to ${localRef}`);
+    } else {
+      // No existing cloud model, or already local — set the best model as primary
+      section.model = `local/${normalizeLocalModelName(bestEntry.modelName)}`;
+      if (section.fallback_models) delete section.fallback_models;
+      if (section.routing) delete section.routing;
+      changed++;
+      console.log(
+        `  \u2713 ${agentName}: placed local/${normalizeLocalModelName(bestEntry.modelName)}`,
+      );
+    }
+  }
+  return changed;
+}
+
+/**
+ * Pull an Ollama model, with curl-based fallback when the `ollama` CLI fails.
+ * 1. Attempts `ollama pull <name>` (shows native progress bars).
+ * 2. On failure, retries via POST http://localhost:11434/api/pull (streams JSON progress).
+ * Returns true if the model was successfully pulled, false otherwise.
+ */
+function pullModel(modelName) {
+  // Primary: ollama CLI
+  try {
+    execFileSync("ollama", ["pull", modelName], {
+      stdio: "inherit",
+      timeout: 600000,
+    });
+    return true;
+  } catch (e) {
+    console.error(`  \u2716 Failed to pull ${modelName}: ${e.message}`);
+  }
+
+  // Fallback: curl-based Ollama API pull
+  try {
+    console.log(
+      `  \u2192 Retrying via curl API at http://localhost:11434/api/pull ...`,
+    );
+    const body = JSON.stringify({ name: modelName });
+    execFileSync(
+      "curl",
+      [
+        "-N",
+        "-X",
+        "POST",
+        "http://localhost:11434/api/pull",
+        "-d",
+        body,
+        "--max-time",
+        "600",
+      ],
+      { stdio: "inherit", timeout: 610000 },
+    );
+    console.log(`  \u2713 ${modelName} pulled via curl`);
+    return true;
+  } catch (e2) {
+    console.error(`  \u2716 Also failed via curl: ${e2.message}`);
+    return false;
+  }
+}
+
+async function installAndUninstallModels(decisions, ollama, autoYes) {
+  if (!decisions) return new Set();
+  const normalizedDecisions = decisions
+    .map((d) => ({ ...d, name: normalizeLocalModelName(d.name) }))
+    .filter((d) => d.name);
+  const installedNames = installedLocalNameSet(ollama);
+  const toInstall = normalizedDecisions.filter((d) => d.action === "install");
+  const toRemove = normalizedDecisions.filter((d) => d.action === "uninstall");
+  const toKeep = normalizedDecisions.filter((d) => d.action === "keep");
+
+  // Return set of model names confirmed present after install phase
+  const confirmed = new Set(
+    toKeep.filter((d) => installedNames.has(d.name)).map((d) => d.name),
+  );
+
+  for (const d of toInstall) {
+    const alreadyInstalled = installedNames.has(d.name);
+    if (alreadyInstalled) {
+      console.log(`  \u2713 ${d.name} already installed`);
+      confirmed.add(d.name);
+      continue;
+    }
+    if (autoYes) {
+      console.log(`  \u2192 Pulling ${d.name}...`);
+      if (pullModel(d.name)) {
+        console.log(`  \u2713 ${d.name} pulled`);
+        confirmed.add(d.name);
+      } else {
+        console.log(
+          `  \u2192 Config will NOT include placement for ${d.name}\n`,
+        );
+      }
+    } else {
+      const ok = await confirm(`  Install ${d.name}? [y/N] `);
+      if (ok) {
+        console.log(`  \u2192 Pulling ${d.name}...`);
+        if (pullModel(d.name)) {
+          console.log(`  \u2713 ${d.name} pulled`);
+          confirmed.add(d.name);
+        } else {
+          console.log(
+            `  \u2192 Config will NOT include placement for ${d.name}\n`,
+          );
+        }
+      } else {
+        console.log(`  \u2192 Skipped`);
+      }
+    }
+  }
+
+  for (const d of toRemove) {
+    const isInstalled = installedNames.has(d.name);
+    if (!isInstalled) {
+      continue;
+    }
+    if (autoYes) {
+      try {
+        execFileSync("ollama", ["rm", d.name], {
+          stdio: "inherit",
+          timeout: 60000,
+        });
+        console.log(`  \u2713 ${d.name} removed`);
+      } catch (e) {
+        console.error(`  \u2716 Failed to remove ${d.name}: ${e.message}`);
+      }
+    } else {
+      const ok = await confirm(`  Uninstall ${d.name}? [y/N] `);
+      if (ok) {
+        try {
+          execFileSync("ollama", ["rm", d.name], {
+            stdio: "inherit",
+            timeout: 60000,
+          });
+          console.log(`  \u2713 ${d.name} removed`);
+        } catch (e) {
+          console.error(`  \u2716 Failed to remove ${d.name}: ${e.message}`);
+        }
+      } else {
+        console.log(`  \u2192 Skipped`);
+      }
+    }
+  }
+
+  return confirmed;
+}
+
+async function offerUninstallOrphans(decisions, ollama, autoYes) {
+  // Models the AI evaluated (any decision = considered)
+  const considered = new Set((decisions || []).map((d) => d.name));
+  // Installed models the AI never mentioned
+  const orphans = ollama.models.filter((m) => !considered.has(m.name));
+
+  if (orphans.length === 0) return;
+
+  console.log(
+    `\n\u2500\u2500 Unnecessary models (${orphans.length}) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`,
+  );
+  console.log(`  Installed but AI never recommended keeping:`);
+  for (const m of orphans) {
+    console.log(`  \u2022 ${m.name}  (${m.size})`);
+  }
+  console.log("");
+
+  if (autoYes) {
+    for (const m of orphans) {
+      try {
+        execFileSync("ollama", ["rm", m.name], {
+          stdio: "inherit",
+          timeout: 60000,
+        });
+        console.log(`  \u2713 ${m.name} removed`);
+      } catch (e) {
+        console.error(`  \u2716 Failed to remove ${m.name}: ${e.message}`);
+      }
+    }
+    return;
+  }
+
+  const ok = await confirm(
+    `Remove these ${orphans.length} model(s) to free disk space? (y/N) `,
+  );
+  if (!ok) {
+    console.log("  \u2192 Skipped\n");
+    return;
+  }
+  for (const m of orphans) {
+    try {
+      execFileSync("ollama", ["rm", m.name], {
+        stdio: "inherit",
+        timeout: 60000,
+      });
+      console.log(`  \u2713 ${m.name} removed`);
+    } catch (e) {
+      console.error(`  \u2716 Failed to remove ${m.name}: ${e.message}`);
+    }
+  }
+}
+
+// =========================================================================
+// Rebalance display (algorithmic)
+// =========================================================================
+
+function showRebalance(config, richLookup, aliases, localModelNames) {
+  const tierChains = buildTierChains(richLookup, aliases);
+  console.log(`\n\uD83D\uDD2E Algorithmic tier chains for ${CONFIG_PATH}\n`);
+  if (localModelNames.length > 0) {
+    console.log(
+      `\u2500\u2500 Local \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`,
+    );
+    console.log(`  Ollama models: ${localModelNames.join(", ")}\n`);
+  }
+  for (const tier of QUALITY_TIERS) {
+    const chain = tierChains[tier];
+    if (chain && chain.length > 0) {
+      console.log(
+        `\u2500\u2500 ${tier} chain \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`,
+      );
+      chain.forEach((c, i) => {
+        const prefix = i === 0 ? "\u2192 primary" : `  fallback ${i}`;
+        console.log(`  ${prefix}: ${c.model} (${Math.round(c.score)})`);
+      });
+      console.log();
+    }
+  }
+  console.log(
+    `\u2500\u2500 Agents / Categories \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`,
+  );
+  const allEntries = [];
+  for (const [name, agent] of Object.entries(config.agents || {})) {
+    if (agent.model) allEntries.push({ name, type: "agent", entry: agent });
+  }
+  for (const [name, cat] of Object.entries(config.categories || {})) {
+    if (cat.model) allEntries.push({ name, type: "category", entry: cat });
+  }
+  if (allEntries.length === 0) {
+    console.log("  No model references found in config.");
+  } else {
+    console.log(`  ${allEntries.length} section(s) with model references:\n`);
+    for (const { name, type, entry } of allEntries) {
+      const quality = entry.model_quality || "balanced";
+      const current = entry.model || "(none)";
+      const chain = tierChains[quality];
+      const recommended = chain && chain.length > 0 ? chain[0].model : "(none)";
+      const changed =
+        current !== recommended ? " \u26A1 would change" : " \u2713";
+      console.log(`  ${name} (${type})`);
+      console.log(`    quality:    ${quality}`);
+      console.log(`    current:    ${current}`);
+      console.log(`    recommend:  ${recommended}${changed}`);
+      if (chain && chain.length > 1) {
+        console.log(
+          `    fallbacks:  ${chain
+            .slice(1)
+            .map((c) => c.model)
+            .join(", ")}`,
+        );
+      }
+      console.log();
+    }
+  }
+}
+
+// =========================================================================
+// Main
+// =========================================================================
+
+async function main() {
+  installSignalHandlers();
+  const parsedArgs = mri(process.argv.slice(2), {
+    boolean: [
+      "yes",
+      "rebalance",
+      "dry-run",
+      "cloud-only",
+      "local-only",
+      "debug",
+      "interactive",
+      "help",
+      "version",
+    ],
+    string: ["model"],
+    alias: { h: "help", v: "version", y: "yes" },
+    default: {
+      yes: false,
+      rebalance: false,
+      "dry-run": false,
+      "cloud-only": false,
+      "local-only": false,
+      debug: false,
+      interactive: false,
+      help: false,
+      version: false,
+    },
+  });
+  if (parsedArgs.help) {
+    console.log(usage());
+    return;
+  }
+  if (parsedArgs.version) {
+    console.log(VERSION);
+    return;
+  }
+  const doRebalance = parsedArgs.rebalance;
+  debugMode = parsedArgs.debug;
+  const realTty =
+    Boolean(process.stdout.isTTY) &&
+    process.env.TERM !== "dumb" &&
+    process.env.CI !== "true";
+  const interactive = parsedArgs.interactive || realTty;
+  const dryRunFallback = !interactive && !parsedArgs.yes;
+  const dryRun = parsedArgs["dry-run"] || dryRunFallback;
+  const autoYes = !dryRun && (parsedArgs.yes || (!parsedArgs.interactive && realTty));
+  const cloudOnly = parsedArgs["cloud-only"];
+  const localOnly = parsedArgs["local-only"];
+  const explicitModels = [parsedArgs.model]
+    .flat()
+    .filter((model) => typeof model === "string" && model.trim())
+    .map((model) => model.trim());
+
+  await configureTerminalUi(realTty);
+  if (dryRunFallback) {
+    console.log(
+      "  • Non-interactive environment detected; previewing changes only. Pass --yes to apply.",
+    );
+  }
+
+  const config = loadConfig();
+
+  if (
+    !doRebalance &&
+    selectedPanelRequiresOpencode(config, explicitModels) &&
+    !commandExists("opencode")
+  ) {
+    console.error(
+      [
+        "Error: OpenCode CLI (`opencode`) is required to query AI panel models, but it was not found on PATH.",
+        "Install OpenCode, add `opencode` to PATH, or configure `omo.panel_models` with only `cli/...` agents.",
+        "No config changes were made.",
+      ].join("\n"),
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const needPrompt = !doRebalance && explicitModels.length === 0 && !autoYes && !dryRun && !localOnly;
+
+  // Start probing paid models in the background if we're not in local-only mode
+  let paidProbesPromise = Promise.resolve([]);
+  let paidProbesDetails = [];
+  let initialCache = null;
+  let initialAliases = {};
+  let initialCloudLookup = { byId: {}, sets: {} };
+
+  let probesAwaited = false;
+  async function ensureProbesAwaited() {
+    if (probesAwaited) return;
+    probesAwaited = true;
+    if (!localOnly && paidProbesPromise) {
+      const progress = createProgress("Verifying paid models availability");
+      await paidProbesPromise;
+      progress.done();
+    }
+  }
+
+  if (!localOnly) {
+    initialCache = loadProviderModels();
+    initialAliases = buildProviderAliases(config);
+    initialCloudLookup = buildRichModelLookup(initialCache);
+
+    const paidRefs = [];
+    for (const [provider, modelMap] of Object.entries(initialCloudLookup.byId || {})) {
+      if (provider === LOCAL_PROVIDER || provider === "opencode") continue;
+      for (const modelId of modelMap.keys()) {
+        paidRefs.push(`${provider}/${modelId}`);
+      }
+    }
+    const sortedPaid = sortPanelModelRefs(paidRefs, config);
+
+    // Group by provider to avoid being dominated by a single provider with exhausted quota
+    const byProvider = {};
+    for (const ref of sortedPaid) {
+      const provider = ref.split("/")[0];
+      if (!byProvider[provider]) byProvider[provider] = [];
+      byProvider[provider].push(ref);
+    }
+
+    const candidates = [];
+    const providerKeys = Object.keys(byProvider);
+    // Take top 1 from each provider to check provider health without redundant queries
+    for (const prov of providerKeys) {
+      if (byProvider[prov] && byProvider[prov][0]) {
+        candidates.push(byProvider[prov][0]);
+      }
+    }
+    const topPaid = candidates;
+
+    paidProbesPromise = Promise.all(
+      topPaid.map(async (modelRef) => {
+        const res = await probeModel(modelRef);
+        return { modelRef, ok: res.ok, reason: res.reason, errorOutput: res.errorOutput };
+      })
+    ).then((results) => {
+      paidProbesDetails = results;
+      return sortedPaid.filter((m) => {
+        const provider = m.split("/")[0];
+        return isProviderAvailable(provider);
+      });
+    });
+  }
+
+  // GPU / Ollama detection is local integration and is skipped in cloud-only mode.
+  let gpu;
+  let ollama;
+  if (cloudOnly) {
+    createProgress("Checking GPU").skip("skipped by --cloud-only");
+    createProgress("Checking Ollama").skip("skipped by --cloud-only");
+    gpu = {
+      hasGpu: false,
+      name: "",
+      label: "Not checked (--cloud-only)",
+      vramGb: 0,
+    };
+    ollama = { installed: false, running: false, version: null, models: [] };
+  } else {
+    const gpuProgress = createProgress("Checking GPU");
+    gpu = detectGPU();
+    gpuProgress.done(gpu.label);
+
+    const ollamaProgress = createProgress("Checking Ollama");
+    ollama = detectOllama();
+    ollamaProgress.done(
+      ollama.running
+        ? `${ollama.models.length} installed model(s)`
+        : ollama.installed
+          ? "installed, not running"
+          : "not installed",
+    );
+  }
+
+  // Local model catalog (skip if cloud-only, or if Ollama not installed)
+  let allLocalModels = [];
+  let localModelNames = [];
+  if (!cloudOnly && ollama.installed) {
+    const localProgress = createProgress("Discovering local model catalog");
+    allLocalModels = discoverModels(false, localProgress);
+    localModelNames = ollama.models.map((m) => m.name);
+  } else {
+    createProgress("Discovering local model catalog").skip(
+      cloudOnly ? "skipped by --cloud-only" : "Ollama not installed",
+    );
+  }
+
+  // ── Algorithmic --rebalance path ──
+  if (doRebalance) {
+    const cache = loadProviderModels();
+    const aliases = buildProviderAliases(config);
+    const richLookup = buildRichModelLookup(cache);
+    // Include local models in lookup for scoring
+    if (localModelNames.length > 0) {
+      if (!richLookup.sets.local) richLookup.sets.local = new Set();
+      localModelNames.forEach((m) => richLookup.sets.local.add(m));
+      if (!richLookup.byId.local) richLookup.byId.local = new Map();
+      localModelNames.forEach((m) => {
+        if (!richLookup.byId.local.has(m)) richLookup.byId.local.set(m, null);
+      });
+    }
+    showRebalance(config, richLookup, aliases, localModelNames);
+
+    const tierChains = buildTierChains(richLookup, aliases);
+    const rebalanceOptions = {
+      unavailableModels: new Set(),
+      providerAliases: aliases,
+      modelCache: richLookup,
+      tierChains,
+    };
+    const rebalanceChanges = rebalanceConfig(config, rebalanceOptions);
+
+    if (rebalanceChanges.length === 0) {
+      console.log("\n\u2705 No restructuring needed.\n");
+      return;
+    }
+    console.log(
+      `\n\uD83D\uDCCB ${rebalanceChanges.length} section(s) would be restructured:\n`,
+    );
+    for (const c of rebalanceChanges) console.log(`  ${c}`);
+    if (dryRun) {
+      console.log(`\n   \u2192 Apply: omo-recommend-models --rebalance\n`);
+      return;
+    }
+    if (!autoYes) {
+      const ok = await confirm(
+        `Apply ${rebalanceChanges.length} changes? (y/N) `,
+      );
+      if (!ok) {
+        console.log("  Skipped.\n");
+        return;
+      }
+    }
+    if (backupConfig(CONFIG_PATH, BACKUP_PATH)) {
+      console.log(`  \u2713 Backup saved to ${BACKUP_PATH}`);
+    }
+    console.log(`  Backup: ${BACKUP_PATH}`);
+    try {
+      writeConfigWithValidation({
+        config,
+        configPath: CONFIG_PATH,
+        backupPath: BACKUP_PATH,
+        validatorPath: path.join(__dirname, "omo-validate-config"),
+        validateStdio: "inherit",
+      });
+      console.log(`\u2705 ${rebalanceChanges.length} section(s) restructured.\n`);
+    } catch (validationErr) {
+      console.error(`\n\u2716 Validation FAILED.`);
+      if (fs.existsSync(BACKUP_PATH)) {
+        console.log(
+          `  \u2713 Reverted to previous config (backup at ${BACKUP_PATH})`,
+        );
+      } else {
+        console.log(
+          `  \u26A0 No backup found at ${BACKUP_PATH} \u2014 config on disk may be invalid.`,
+        );
+      }
+      throw validationErr;
+    }
+    return;
+  }
+
+  const skipCloud = localOnly;
+  let cache = null;
+  if (skipCloud) {
+    createProgress("Loading cloud provider cache").skip(
+      "skipped by --local-only",
+    );
+  } else {
+    const cloudProgress = createProgress("Loading cloud provider cache");
+    cache = needPrompt ? initialCache : loadProviderModels();
+    cloudProgress.done(
+      cache?.models
+        ? `${Object.keys(cache.models).length} provider(s)`
+        : "not found",
+    );
+  }
+  const aliases = skipCloud
+    ? {}
+    : needPrompt
+      ? initialAliases
+      : buildProviderAliases(config);
+  const cloudLookup = skipCloud
+    ? { byId: {}, sets: {} }
+    : needPrompt
+      ? initialCloudLookup
+      : buildRichModelLookup(cache);
+  // Inject local models into cloud lookup for scoring context
+  if (!cloudOnly && localModelNames.length > 0) {
+    if (!cloudLookup.sets.local) cloudLookup.sets.local = new Set();
+    localModelNames.forEach((m) => cloudLookup.sets.local.add(m));
+    if (!cloudLookup.byId.local) cloudLookup.byId.local = new Map();
+    localModelNames.forEach((m) => {
+      if (!cloudLookup.byId.local.has(m)) cloudLookup.byId.local.set(m, null);
+    });
+  }
+
+  const cloudProviderCount = Object.entries(cloudLookup.byId || {}).filter(
+    ([provider, modelMap]) =>
+      provider !== LOCAL_PROVIDER && modelMap && modelMap.size > 0,
+  ).length;
+  console.log(
+    `  \u2713 Model picture: ${cloudProviderCount} cloud provider(s), ${localModelNames.length} installed local model(s)\n`,
+  );
+
+  // Determine which panel models to use
+  // Priority: 1) --model CLI flags, 2) interactive picker, 3) omo.panel_models,
+  // 4) default top 5 ordered by `omo.panel_model_order` ("opencode-first"
+  // unless set to "score").
+  let aiResult;
+  let panel = null;
+  const localCtx = cloudOnly ? [] : allLocalModels;
+  const gpuCtx = cloudOnly
+    ? {
+        hasGpu: false,
+        name: "",
+        label: "Not checked (--cloud-only)",
+        vramGb: 0,
+      }
+    : gpu;
+  const ollamaCtx = cloudOnly
+    ? { installed: false, running: false, version: null, models: [] }
+    : ollama;
+
+  // Check for cached panel result first (early cache prompt while background queries are running)
+  if (!autoYes && !dryRun) {
+    const cached = loadPanelCache();
+    if (cached) {
+      const age = Date.now() - cached.timestamp;
+      const ageStr =
+        age > 86400000
+          ? `${(age / 86400000).toFixed(1)}d`
+          : age > 3600000
+            ? `${(age / 3600000).toFixed(1)}h`
+            : `${Math.round(age / 60000)}m`;
+      const ts = new Date(cached.timestamp)
+        .toISOString()
+        .replace("T", " ")
+        .slice(0, 19);
+
+      const cachedModelList =
+        cached.models || cached.result?.panel?.models || [];
+
+      console.log(`\nCached panel result:`);
+      if (cachedModelList.length > 0) {
+        console.log(`  \u2022 Surveyed AI models:`);
+        printNumberedPanelModelGroups(cachedModelList, "    ");
+      }
+      if (cached.gpu && cached.gpu.label) {
+        const gpuLine = `  \u2022 Hardware: ${cached.gpu.label}`;
+        console.log(
+          cached.gpu.vramGb
+            ? `${gpuLine} (${cached.gpu.vramGb} GB VRAM)`
+            : gpuLine,
+        );
+      }
+      console.log(`  \u2022 Recorded: ${ts} (${ageStr} ago)`);
+
+      const useCached = await confirm(`\nUse cached? (y/N) `);
+      if (useCached) {
+        await ensureProbesAwaited();
+        const fittingByName = buildFittingModelMap(localCtx, gpuCtx);
+        if (resultHasRejectedLocal(cached.result, fittingByName)) {
+          console.log(
+            `  \u2022 Cached result references unavailable local models; running fresh.\n`,
+          );
+        } else {
+          aiResult = completeAiRecommendations(
+            cached.result,
+            config,
+            cloudLookup,
+            localCtx,
+            gpuCtx,
+            ollamaCtx,
+          );
+          panel = cached.result.panel || null;
+          console.log(`  \u2713 Loaded cached panel result.\n`);
+        }
+      }
+    }
+  }
+
+  // Determine which panel models to use
+  // Priority: 1) --model CLI flags, 2) interactive picker, 3) omo.panel_models,
+  // 4) default top 5 ordered by `omo.panel_model_order` ("opencode-first"
+  // unless set to "score").
+  let panelModels = null;
+  if (!aiResult) {
+    if (explicitModels.length > 0) {
+      panelModels = explicitModels;
+      console.log(
+        `  \u2713 Using ${panelModels.length} explicitly selected model(s): ${panelModels.join(", ")}\n`,
+      );
+    } else if (!autoYes && !dryRun && !localOnly) {
+      await ensureProbesAwaited();
+      const availablePaid = await paidProbesPromise;
+      const picked = await pickPanelModels(config, availablePaid);
+      if (picked && picked.length > 0) {
+        panelModels = picked;
+        console.log(`  \u2713 Using ${panelModels.length} selected model(s)\n`);
+      }
+    }
+
+    if (!panelModels) {
+      const configuredModels = configuredPanelModels(config);
+      if (configuredModels.length > 0) {
+        panelModels = configuredModels;
+        console.log(
+          `  \u2713 Using ${panelModels.length} configured panel model(s): ${panelModels.join(", ")}\n`,
+        );
+      }
+    }
+
+    // Ask Free vs Paid prompt if we still don't have models and prompting is allowed
+    if (!panelModels && !autoYes && !dryRun && !localOnly) {
+      await ensureProbesAwaited();
+      const availablePaid = await paidProbesPromise;
+      if (availablePaid.length > 0) {
+        console.log(`\nAvailable paid models:`);
+        printNumberedPanelModelGroups(availablePaid, "  ");
+        console.log();
+
+        const answer = await promptUser(
+          `Use best paid models or free opencode models (slow) for the analysis? (P/f): `,
+        );
+        const usePaid = answer.trim().toLowerCase() !== "f";
+        if (usePaid) {
+          panelModels = availablePaid.slice(0, 5);
+        } else {
+          panelModels = defaultPanelModels(config);
+          opencodeOnlyMode = true;
+        }
+      } else {
+        console.log("\n\u26A0 No paid models are currently verified as available.");
+        console.log("  Please check that your API keys are set and exported in your environment");
+        console.log("  (e.g., GITHUB_TOKEN, OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY).");
+        if (paidProbesDetails && paidProbesDetails.length > 0) {
+          console.log("\n  Probe details / errors:");
+          for (const res of paidProbesDetails) {
+            if (!res.ok) {
+              const errSnippet = res.errorOutput ? res.errorOutput.split("\n")[0] : "unknown error";
+              console.log(`    • ${res.modelRef}: ${res.reason} (${errSnippet})`);
+            }
+          }
+        }
+        console.log("\n  Falling back to free opencode models.\n");
+        panelModels = defaultPanelModels(config);
+        opencodeOnlyMode = true;
+      }
+    }
+
+    // Fallback to default if still not set (e.g., if autoYes, dryRun, or localOnly skipped prompt)
+    if (!panelModels) {
+      await ensureProbesAwaited();
+      const availablePaid = await paidProbesPromise;
+      if (availablePaid.length > 0 && !localOnly) {
+        panelModels = availablePaid.slice(0, 5);
+      } else {
+        panelModels = defaultPanelModels(config);
+        opencodeOnlyMode = true;
+      }
+    }
+  }
+  // (Old cache checking block removed)
+
+  try {
+    if (!aiResult) {
+      console.log(`\nThis run would query:`);
+      printNumberedPanelModelGroups(panelModels, "  ");
+      console.log();
+
+      // Ensure background probes of paid models have completed so quotaExceededProviders is fully populated
+      await ensureProbesAwaited();
+
+      // Multi-model panel: all free models recommend in parallel, debate, user picks
+      const panelResult = await runPanelAndSelect(
+        config,
+        cloudLookup,
+        localCtx,
+        gpuCtx,
+        ollamaCtx,
+        cloudOnly,
+        panelModels,
+      );
+      aiResult = completeAiRecommendations(
+        panelResult.selected,
+        config,
+        cloudLookup,
+        localCtx,
+        gpuCtx,
+        ollamaCtx,
+      );
+      panel = panelResult.panel;
+      // Save cache for future runs (include model list and GPU info for invalidation)
+      savePanelCache(
+        {
+          ...panelResult.selected,
+          panel: { models: panelResult.panel?.models },
+        },
+        panelModels,
+        gpuCtx,
+      );
+    }
+  } catch (e) {
+    console.error(`\n\u2716 AI recommendation failed: ${e.message}`);
+    if (fs.existsSync(CONFIG_PATH)) {
+      console.log("  Config unchanged.\n");
+    } else {
+      console.log(
+        "\n  Writing a minimal valid config skeleton. Re-run when models are available.\n",
+      );
+      const rewritten = JSON.stringify(config, null, 2) + "\n";
+      fs.writeFileSync(CONFIG_PATH, rewritten, "utf-8");
+      console.log(`  \u2713 Config written to ${CONFIG_PATH}`);
+      console.log(`  No backup (new config — no previous file to preserve)\n`);
+    }
+    return;
+  }
+
+  console.log(`\n\uD83D\uDCCA AI Analysis (via ${aiResult.recommender}):`);
+  console.log(`   ${aiResult.analysis}\n`);
+
+  // Display cloud recommendations
+  const cloudChanges = showCloudRecommendations(aiResult, config);
+
+  // Display local decisions (always show if they exist, regardless of placements)
+  if (aiResult.localModels) {
+    showLocalDecisions(aiResult, allLocalModels, ollama);
+  }
+
+  const hasLocalChanges =
+    aiResult.localModels &&
+    ((aiResult.localModels.placements &&
+      aiResult.localModels.placements.length > 0) ||
+      (aiResult.localModels.decisions &&
+        aiResult.localModels.decisions.some(
+          (d) => d.action === "install" || d.action === "uninstall",
+        )));
+  const hasChanges = cloudChanges.length > 0 || hasLocalChanges;
+
+  if (!hasChanges) {
+    console.log("\u2705 No changes needed.\n");
+    return;
+  }
+
+  if (dryRun) {
+    console.log(`\n   \u2192 Apply: omo-recommend-models\n`);
+    return;
+  }
+
+  if (!autoYes) {
+    const ok = await confirm("Apply all recommendations above? (y/N) ");
+    if (!ok) {
+      console.log("  Skipped.\n");
+      return;
+    }
+  }
+
+  // Backup
+  if (backupConfig(CONFIG_PATH, BACKUP_PATH)) {
+    console.log(`  \u2713 Backup saved to ${BACKUP_PATH}`);
+  }
+
+  // Local models must be installed/confirmed before config refs are written.
+  const confirmedModels = await installAndUninstallModels(
+    aiResult.localModels?.decisions,
+    ollama,
+    autoYes,
+  );
+
+  // Apply model assignments after filtering out unconfirmed local refs.
+  let totalCloud = 0;
+  if (aiResult.cloudRecommendations) {
+    for (const rec of aiResult.cloudRecommendations) {
+      const section =
+        config.agents?.[rec.name] || config.categories?.[rec.name];
+      if (!section) continue;
+
+      // Filter unconfirmed local models from all three fields
+      const localOk = (r) =>
+        r.provider !== LOCAL_PROVIDER ||
+        (confirmedModels &&
+          confirmedModels.has(normalizeLocalModelName(r.model)));
+
+      const modelOk = rec.model && localOk(rec.model);
+      const routingOk = (rec.routing || []).filter(localOk);
+      const fbOk = (rec.fallback_models || []).filter(localOk);
+
+      if (!modelOk && routingOk.length === 0 && fbOk.length === 0) continue;
+
+      if (modelOk) section.model = `${rec.model.provider}/${rec.model.model}`;
+      section.routing =
+        routingOk.length > 0
+          ? routingOk.map((r) => `${r.provider}/${r.model}`)
+          : undefined;
+      section.fallback_models =
+        fbOk.length > 0
+          ? fbOk.map((r) => `${r.provider}/${r.model}`)
+          : undefined;
+      // Clean up undefined keys
+      if (!section.routing) delete section.routing;
+      if (!section.fallback_models) delete section.fallback_models;
+      totalCloud++;
+    }
+  }
+
+  let totalLocal = 0;
+  if (aiResult.localModels && aiResult.localModels.placements) {
+    const confirmedPlacements = aiResult.localModels.placements.filter((p) =>
+      confirmedModels.has(normalizeLocalModelName(p.modelName)),
+    );
+    if (confirmedPlacements.length > 0) {
+      totalLocal = await applyLocalPlacements(
+        confirmedPlacements,
+        config,
+        autoYes,
+        allLocalModels,
+      );
+    }
+  }
+
+  console.log(`  Backup: ${BACKUP_PATH}`);
+  const totalChanges = totalCloud + totalLocal;
+
+  // Validate — roll back on failure
+  console.log("\u2192 Validating changes...");
+  try {
+    writeConfigWithValidation({
+      config,
+      configPath: CONFIG_PATH,
+      backupPath: BACKUP_PATH,
+      validatorPath: path.join(__dirname, "omo-validate-config"),
+      validateStdio: ["inherit", "inherit", "pipe"],
+    });
+    console.log(`\u2705 ${totalChanges} section(s) updated.\n`);
+  } catch (validationErr) {
+    const stderr = validationErr.stderr ? validationErr.stderr.toString() : "";
+    console.error(`\n\u2716 Validation FAILED.`);
+    if (stderr) {
+      for (const line of stderr.trim().split("\n")) {
+        console.error(`  ${line}`);
+      }
+    }
+    // Restore from the backup taken before applying
+    if (fs.existsSync(BACKUP_PATH)) {
+      console.log(
+        `  \u2713 Reverted to previous config (backup at ${BACKUP_PATH})`,
+      );
+    } else {
+      console.log(
+        `  \u26A0 No backup found at ${BACKUP_PATH} \u2014 config on disk may be invalid.`,
+      );
+    }
+    console.log(
+      `  Recommendations were NOT applied. Fix the issues above and re-run.`,
+    );
+    throw new Error(
+      `Validation failed after applying recommendations. Config was reverted to backup.`,
+    );
+  }
+
+  // Step 4: Offer to remove models the AI never considered
+  await offerUninstallOrphans(aiResult.localModels?.decisions, ollama, autoYes);
+
+  console.log("\n\u2705 Done.");
+}
+
+main()
+  .catch((e) => {
+    console.error(`\n${pc.red("\u2716 " + (e.message || String(e)))}`);
+    if (debugMode && e.stack) {
+      console.error(e.stack);
+    }
+    // Show execSync stderr if available (validation failures, subprocess errors, etc.)
+    if (e.stderr) {
+      const stderrText =
+        typeof e.stderr === "string" ? e.stderr : e.stderr.toString();
+      for (const line of stderrText.trim().split("\n")) {
+        console.error(`  ${line}`);
+      }
+    }
+    process.exitCode = 1;
+  });