opencode-swarm 7.18.0 → 7.18.2

package/README.md

@@ -24,7 +24,7 @@ bunx opencode-swarm install
 
 > This single command installs the package, registers it as an OpenCode plugin, disables conflicting default agents, and creates a ready-to-edit config at `~/.config/opencode/opencode-swarm.json`. Requires [Bun](https://bun.sh) (`bun --version` to check). If you must use npm: `npm install -g opencode-swarm && opencode-swarm install`.
 
-> ⚠️ **On first run, Swarm auto-selects the architect and shows a welcome message.** The default OpenCode `Build` and `Plan` modes **bypass this plugin entirely** — none of the gates, reviewers, or test agents below run. If you ever need to switch architect manually, open the OpenCode mode/agent picker and choose the Swarm architect; it then coordinates every other agent automatically. If you ever see Swarm "do nothing," this is almost always the cause.
+> ⚠️ **Select a Swarm architect before starting work.** The installer registers Swarm architect agents as primary choices, but the default OpenCode `Build` and `Plan` modes **bypass this plugin entirely** — none of the gates, reviewers, or test agents below run. Open the OpenCode mode/agent picker and choose `architect` or a `*_architect`; it then coordinates every other agent automatically. If you ever see Swarm "do nothing," this is almost always the cause.
 
 ### Why Swarm?
 
@@ -41,7 +41,7 @@ Most AI coding tools let one model write code and ask that same model whether th
 - 🆓 **Free tier** — works with OpenCode Zen's free model roster
 - ⚙️ **Fully configurable** — override any agent's model, disable agents, tune guardrails
 
-> **The Swarm architect is auto-selected on first run and coordinates all other agents automatically.** You never manually switch between internal roles. If you use the default OpenCode `Build` / `Plan` modes, the plugin is bypassed entirely (see the install warning above).
+> **The Swarm architect coordinates all other agents automatically after you select it.** You never manually switch between internal roles. If you use the default OpenCode `Build` / `Plan` modes, the plugin is bypassed entirely (see the install warning above).
 
 ---
 
@@ -126,9 +126,9 @@ The 15-minute guide covers:
 - Troubleshooting common issues
 
 On first run, Swarm automatically:
-- Creates project config at `.opencode/opencode-swarm.json` with all agents enabled
-- Selects the Swarm architect as the default
-- Shows a welcome message with next steps
+- Creates project config at `.opencode/opencode-swarm.json` if missing
+- Registers Swarm architect agents as primary choices in OpenCode
+- Shows a welcome message with next steps the first time you run `/swarm`
 
 ---
 
@@ -142,8 +142,7 @@ No animated GIF is shipped in the repo — instead, here is the exact terminal s
 # 1. Install the plugin (5s)
 bunx opencode-swarm install
 
-# 2. Open opencode — Swarm auto-selects architect on first run
-#    (the architect is auto-selected; manual selection is only needed to override)
+# 2. Open opencode and select the Swarm architect in the agent/mode picker
 opencode
 
 # 3. Inside the OpenCode session, verify Swarm is live (5s)
@@ -167,7 +166,7 @@ Build me a JWT auth helper with tests.
 │ ✓ created .opencode/opencode-swarm.json                     │
 │                                                              │
 │ $ opencode                                                   │
-│ [Swarm] Welcome! Architect auto-selected. Type /swarm help  │
+│ [Swarm] Welcome! Run /swarm diagnose, then /swarm agents    │
 │                                                              │
 │ > /swarm help                                                │
 │ Available commands: status, plan, agents, help, diagnose... │
@@ -218,7 +217,7 @@ in your `opencode-swarm.json`.
 
 ## Commands
 
-All 43 subcommands at a glance:
+Core subcommands at a glance:
 
 ```bash
 /swarm help [command]      # List all commands or get detailed help for a specific command
@@ -234,7 +233,7 @@ Use `/swarm help` to see all available commands categorized by function. Use `/s
 
 Nine commands display a ⚠️ warning in help output because they share names with Claude Code built-in slash commands (e.g., `/plan`, `/reset`, `/status`). The warning reminds you to always use `/swarm <command>` — the bare CC command does something different and sometimes destructive. See [docs/commands.md#claude-code-command-conflicts](docs/commands.md#claude-code-command-conflicts) for the full conflict registry.
 
-See [docs/commands.md](docs/commands.md) for the full reference (43 commands).
+See [docs/commands.md](docs/commands.md) for the full command reference.
 
 ## Command Aliases
 
@@ -368,11 +367,14 @@ No API key required. Excellent starting point:
   "agents": {
     "coder": { "model": "opencode/minimax-m2.5-free" },
     "reviewer": { "model": "opencode/big-pickle" },
+    "critic": { "model": "opencode/big-pickle" },
     "explorer": { "model": "opencode/big-pickle" }
   }
 }
 ```
 
+Zen's roster changes. Always confirm current IDs with `/models` in OpenCode or `https://opencode.ai/zen/v1/models` before pasting a model into config. Do not copy private workspace providers such as `grove-openai/*` unless that provider appears in your own OpenCode model list.
+
 ### Paid Providers
 
 For production, mix providers by role:
@@ -381,11 +383,14 @@ For production, mix providers by role:
 |---|---|---|
 | architect | OpenCode UI selection | Needs strongest reasoning |
 | coder | minimax-coding-plan/MiniMax-M2.5 | Fast, accurate code generation |
-| reviewer | zai-coding-plan/glm-5 | Different training from coder |
-| test_engineer | minimax-coding-plan/MiniMax-M2.5 | Same strengths as coder |
+| critic | opencode/gpt-5.5 or your strongest reasoning model | Challenges the architect before coding |
+| reviewer | zai-coding-plan/glm-5 or a different strong model | Different training from coder |
+| test_engineer | opencode/big-pickle or another model distinct from coder | Catches test blind spots |
 | explorer | google/gemini-2.5-flash | Fast read-heavy analysis |
 | sme | kimi-for-coding/k2p5 | Strong domain expertise |
 
+Model assignment rule of thumb: architect and critic should be your strongest pair, and they should not be the same blind spot. Coder/test_engineer can be faster coding models; explorer/docs/curator can be cheaper readers. Do not put a premium model on `designer` while leaving `critic` on a weaker model.
+
 ### Provider Formats
 
 | Provider | Format | Example |
@@ -406,7 +411,7 @@ Automatic fallback to a secondary model on transient errors:
   "agents": {
     "coder": {
       "model": "anthropic/claude-sonnet-4-20250514",
-      "fallback_models": ["opencode/gpt-5-nano"]
+      "fallback_models": ["opencode/big-pickle"]
     }
   }
 }
@@ -1144,15 +1149,15 @@ Config file location: `~/.config/opencode/opencode-swarm.json` (global) or `.ope
 ```json
 {
   "agents": {
-    "architect": { "model": "anthropic/claude-opus-4-6" },
-    "coder": { "model": "minimax-coding-plan/MiniMax-M2.5", "fallback_models": ["minimax-coding-plan/MiniMax-M2.1"] },
-    "explorer": { "model": "minimax-coding-plan/MiniMax-M2.1" },
-    "sme": { "model": "kimi-for-coding/k2p5" },
-    "critic": { "model": "zai-coding-plan/glm-5" },
+    "architect": { "model": "opencode/claude-opus-4-6" },
+    "coder": { "model": "opencode/minimax-m2.5", "fallback_models": ["opencode/big-pickle"] },
+    "explorer": { "model": "opencode/big-pickle" },
+    "sme": { "model": "opencode/kimi-k2.6" },
+    "critic": { "model": "opencode/gpt-5.5" },
     "reviewer": { "model": "zai-coding-plan/glm-5", "fallback_models": ["opencode/big-pickle"] },
-    "test_engineer": { "model": "minimax-coding-plan/MiniMax-M2.5" },
-    "docs": { "model": "zai-coding-plan/glm-4.7-flash" },
-    "designer": { "model": "kimi-for-coding/k2p5" }
+    "test_engineer": { "model": "opencode/minimax-m2.5" },
+    "docs": { "model": "opencode/big-pickle" },
+    "designer": { "model": "opencode/kimi-k2.6" }
   },
   "guardrails": {
     "max_tool_calls": 200,
@@ -1401,7 +1406,7 @@ bun test
 - [Installation Guide](docs/installation.md) — comprehensive reference
 - [Architecture Deep Dive](docs/architecture.md) — control model, pipeline, tools
 - [Design Rationale](docs/design-rationale.md) — why every major decision
-- [Commands Reference](docs/commands.md) — all 41 `/swarm` subcommands
+- [Commands Reference](docs/commands.md) — full `/swarm` command reference
 - [Modes Guide](docs/modes.md) — session modes (Turbo, Full-Auto) and project modes (strict/balanced/fast)
 - [Configuration](docs/configuration.md) — all config keys and examples
 - [Planning Guide](docs/planning.md) — task format, phase structure, sizing

package/dist/cli/index.js

@@ -34,7 +34,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "opencode-swarm",
-    version: "7.18.0",
+    version: "7.18.2",
     description: "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
     main: "dist/index.js",
     types: "dist/index.d.ts",
@@ -16501,8 +16501,7 @@ var init_constants = __esm(() => {
       "skill_improve",
       "search",
       "doc_scan",
-      "doc_extract",
-      "web_search"
+      "doc_extract"
     ],
     spec_writer: [
       "search",
@@ -16602,67 +16601,67 @@ var init_constants = __esm(() => {
   DEFAULT_AGENT_CONFIGS = {
     coder: {
       model: "opencode/minimax-m2.5-free",
-      fallback_models: ["opencode/gpt-5-nano", "opencode/big-pickle"]
+      fallback_models: ["opencode/big-pickle"]
     },
     reviewer: {
       model: "opencode/big-pickle",
-      fallback_models: ["opencode/gpt-5-nano", "opencode/big-pickle"]
+      fallback_models: ["opencode/minimax-m2.5-free"]
     },
     test_engineer: {
-      model: "opencode/gpt-5-nano",
-      fallback_models: ["opencode/big-pickle"]
+      model: "opencode/big-pickle",
+      fallback_models: ["opencode/minimax-m2.5-free"]
     },
     explorer: {
       model: "opencode/big-pickle",
-      fallback_models: ["opencode/gpt-5-nano", "opencode/big-pickle"]
+      fallback_models: ["opencode/minimax-m2.5-free"]
     },
     sme: {
       model: "opencode/big-pickle",
-      fallback_models: ["opencode/gpt-5-nano", "opencode/big-pickle"]
+      fallback_models: ["opencode/minimax-m2.5-free"]
     },
     critic: {
       model: "opencode/big-pickle",
-      fallback_models: ["opencode/gpt-5-nano", "opencode/big-pickle"]
+      fallback_models: ["opencode/minimax-m2.5-free"]
     },
     docs: {
       model: "opencode/big-pickle",
-      fallback_models: ["opencode/gpt-5-nano", "opencode/big-pickle"]
+      fallback_models: ["opencode/minimax-m2.5-free"]
     },
     designer: {
       model: "opencode/big-pickle",
-      fallback_models: ["opencode/gpt-5-nano", "opencode/big-pickle"]
+      fallback_models: ["opencode/minimax-m2.5-free"]
     },
     critic_sounding_board: {
-      model: "opencode/gpt-5-nano",
-      fallback_models: ["opencode/big-pickle"]
+      model: "opencode/big-pickle",
+      fallback_models: ["opencode/minimax-m2.5-free"]
     },
     critic_drift_verifier: {
-      model: "opencode/gpt-5-nano",
-      fallback_models: ["opencode/big-pickle"]
+      model: "opencode/big-pickle",
+      fallback_models: ["opencode/minimax-m2.5-free"]
     },
     critic_hallucination_verifier: {
-      model: "opencode/gpt-5-nano",
-      fallback_models: ["opencode/big-pickle"]
+      model: "opencode/big-pickle",
+      fallback_models: ["opencode/minimax-m2.5-free"]
     },
     critic_oversight: {
-      model: "opencode/gpt-5-nano",
-      fallback_models: ["opencode/big-pickle"]
+      model: "opencode/big-pickle",
+      fallback_models: ["opencode/minimax-m2.5-free"]
     },
     curator_init: {
-      model: "opencode/gpt-5-nano",
-      fallback_models: ["opencode/big-pickle"]
+      model: "opencode/big-pickle",
+      fallback_models: ["opencode/minimax-m2.5-free"]
     },
     curator_phase: {
-      model: "opencode/gpt-5-nano",
-      fallback_models: ["opencode/big-pickle"]
+      model: "opencode/big-pickle",
+      fallback_models: ["opencode/minimax-m2.5-free"]
     },
     skill_improver: {
       model: "opencode/big-pickle",
-      fallback_models: ["opencode/gpt-5-nano"]
+      fallback_models: ["opencode/minimax-m2.5-free"]
     },
     spec_writer: {
       model: "opencode/big-pickle",
-      fallback_models: ["opencode/gpt-5-nano"]
+      fallback_models: ["opencode/minimax-m2.5-free"]
     }
   };
 });
@@ -17545,7 +17544,8 @@ function handleAgentsCommand(agents, guardrails) {
   if (hasUnregistered) {
     lines.push("", "### Unregistered Subagents");
     for (const name of unregistered) {
-      lines.push(`- **${name}** (requires configuration)`);
+      const hint = UNREGISTERED_AGENT_HINTS[name] ?? "requires configuration";
+      lines.push(`- **${name}** (${hint})`);
     }
   }
   if (guardrails?.profiles && Object.keys(guardrails.profiles).length > 0) {
@@ -17574,9 +17574,18 @@ function handleAgentsCommand(agents, guardrails) {
   return lines.join(`
 `);
 }
+var UNREGISTERED_AGENT_HINTS;
 var init_agents = __esm(() => {
   init_constants();
   init_schema();
+  UNREGISTERED_AGENT_HINTS = {
+    designer: "enable ui_review.enabled",
+    council_generalist: "enable council.general.enabled",
+    council_skeptic: "enable council.general.enabled",
+    council_domain_expert: "enable council.general.enabled",
+    skill_improver: "registered by default unless agents.skill_improver.disabled is true",
+    spec_writer: "registered by default unless agents.spec_writer.disabled is true"
+  };
 });
 
 // src/commands/analyze.ts
@@ -38247,12 +38256,31 @@ function parseArgs(args) {
   }
   return out;
 }
-async function handleCouncilCommand(_directory, args) {
+async function handleCouncilCommand(directory, args) {
   const parsed = parseArgs(args);
   const question = sanitizeQuestion(parsed.rest.join(" "));
   if (!question) {
     return USAGE;
   }
+  const config3 = loadPluginConfig(directory);
+  if (config3.council?.general?.enabled !== true) {
+    return [
+      "General Council is not enabled for this project.",
+      "",
+      "Enable it in `.opencode/opencode-swarm.json` or `~/.config/opencode/opencode-swarm.json`:",
+      "",
+      "```json",
+      "{",
+      '  "council": {',
+      '    "general": { "enabled": true }',
+      "  }",
+      "}",
+      "```",
+      "",
+      "Then restart OpenCode and run `/swarm config doctor` before trying `/swarm council` again."
+    ].join(`
+`);
+  }
   const tokens = ["MODE: COUNCIL"];
   if (parsed.preset) {
     tokens.push(`preset=${parsed.preset}`);
@@ -38264,6 +38292,7 @@ async function handleCouncilCommand(_directory, args) {
 }
 var MAX_QUESTION_LEN = 2000, USAGE;
 var init_council = __esm(() => {
+  init_loader();
   USAGE = [
     "Usage: /swarm council <question> [--preset <name>] [--spec-review]",
     "",
@@ -39740,6 +39769,7 @@ __export(exports_config_doctor, {
   restoreFromBackup: () => restoreFromBackup,
   getConfigPaths: () => getConfigPaths,
   createConfigBackup: () => createConfigBackup,
+  collectConfiguredModelRefs: () => collectConfiguredModelRefs,
   applySafeAutoFixes: () => applySafeAutoFixes
 });
 import * as crypto3 from "crypto";
@@ -40133,6 +40163,129 @@ function validateConfigKey(path24, value, _config) {
   }
   return findings;
 }
+function addConfiguredModel(refs, model, configPath) {
+  if (typeof model !== "string")
+    return;
+  const trimmed = model.trim();
+  if (!trimmed)
+    return;
+  const paths = refs.get(trimmed) ?? new Set;
+  paths.add(configPath);
+  refs.set(trimmed, paths);
+}
+function addConfiguredAgentModels(refs, agents, prefix) {
+  if (!agents || typeof agents !== "object" || Array.isArray(agents))
+    return;
+  for (const [agentName, value] of Object.entries(agents)) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+      continue;
+    const agent = value;
+    addConfiguredModel(refs, agent.model, `${prefix}.${agentName}.model`);
+    if (Array.isArray(agent.fallback_models)) {
+      agent.fallback_models.forEach((model, index) => {
+        addConfiguredModel(refs, model, `${prefix}.${agentName}.fallback_models[${index}]`);
+      });
+    }
+  }
+}
+function collectConfiguredModelRefs(config3) {
+  const refs = new Map;
+  const rawConfig = config3;
+  addConfiguredAgentModels(refs, rawConfig.agents, "agents");
+  if (rawConfig.swarms && typeof rawConfig.swarms === "object" && !Array.isArray(rawConfig.swarms)) {
+    for (const [swarmId, value] of Object.entries(rawConfig.swarms)) {
+      if (!value || typeof value !== "object" || Array.isArray(value))
+        continue;
+      addConfiguredAgentModels(refs, value.agents, `swarms.${swarmId}.agents`);
+    }
+  }
+  if (rawConfig.full_auto && typeof rawConfig.full_auto === "object" && !Array.isArray(rawConfig.full_auto)) {
+    addConfiguredModel(refs, rawConfig.full_auto.critic_model, "full_auto.critic_model");
+  }
+  if (rawConfig.skill_improver && typeof rawConfig.skill_improver === "object" && !Array.isArray(rawConfig.skill_improver)) {
+    const skillImprover = rawConfig.skill_improver;
+    addConfiguredModel(refs, skillImprover.model, "skill_improver.model");
+    if (Array.isArray(skillImprover.fallback_models)) {
+      skillImprover.fallback_models.forEach((model, index) => {
+        addConfiguredModel(refs, model, `skill_improver.fallback_models[${index}]`);
+      });
+    }
+  }
+  if (rawConfig.spec_writer && typeof rawConfig.spec_writer === "object" && !Array.isArray(rawConfig.spec_writer)) {
+    const specWriter = rawConfig.spec_writer;
+    addConfiguredModel(refs, specWriter.model, "spec_writer.model");
+    if (Array.isArray(specWriter.fallback_models)) {
+      specWriter.fallback_models.forEach((model, index) => {
+        addConfiguredModel(refs, model, `spec_writer.fallback_models[${index}]`);
+      });
+    }
+  }
+  const council = rawConfig.council;
+  const general = council && typeof council === "object" && !Array.isArray(council) ? council.general : undefined;
+  if (general && typeof general === "object" && !Array.isArray(general)) {
+    addConfiguredModel(refs, general.moderatorModel, "council.general.moderatorModel");
+    if (Array.isArray(general.members)) {
+      general.members.forEach((member, index) => {
+        if (!member || typeof member !== "object" || Array.isArray(member)) {
+          return;
+        }
+        addConfiguredModel(refs, member.model, `council.general.members[${index}].model`);
+      });
+    }
+    if (general.presets && typeof general.presets === "object" && !Array.isArray(general.presets)) {
+      for (const [presetName, members] of Object.entries(general.presets)) {
+        if (!Array.isArray(members))
+          continue;
+        members.forEach((member, index) => {
+          if (!member || typeof member !== "object" || Array.isArray(member)) {
+            return;
+          }
+          addConfiguredModel(refs, member.model, `council.general.presets.${presetName}[${index}].model`);
+        });
+      }
+    }
+  }
+  return refs;
+}
+function validateConfiguredModels(config3, modelAvailability) {
+  const refs = collectConfiguredModelRefs(config3);
+  const findings = [];
+  if (modelAvailability.error) {
+    findings.push({
+      id: "model-availability-unchecked",
+      title: "Model availability check skipped",
+      description: `Could not load OpenCode provider models from ${modelAvailability.source}: ` + modelAvailability.error,
+      severity: "info",
+      path: "agents",
+      autoFixable: false
+    });
+    return findings;
+  }
+  if (refs.size === 0)
+    return findings;
+  for (const [modelId, paths] of refs.entries()) {
+    if (modelAvailability.availableModelIds.has(modelId))
+      continue;
+    findings.push({
+      id: "configured-model-unavailable",
+      title: "Configured model is unavailable",
+      description: `Configured model ${formatModelIdForDoctor(modelId)} was not found in the active OpenCode provider model registry. ` + "Run `/models` to choose a currently available model, then update opencode-swarm.json.",
+      severity: "error",
+      path: [...paths].sort().join(", "),
+      currentValue: modelId,
+      autoFixable: false
+    });
+  }
+  return findings;
+}
+function formatModelIdForDoctor(modelId) {
+  const json3 = JSON.stringify(modelId);
+  if (!json3)
+    return '"<invalid model id>"';
+  if (json3.length <= 160)
+    return json3;
+  return `${json3.slice(0, 157)}..."`;
+}
 function walkConfigAndValidate(obj, path24, config3, findings) {
   if (obj === null || obj === undefined) {
     return;
@@ -40157,9 +40310,12 @@ function walkConfigAndValidate(obj, path24, config3, findings) {
     walkConfigAndValidate(value, newPath, config3, findings);
   }
 }
-function runConfigDoctor(config3, directory) {
+function runConfigDoctor(config3, directory, options = {}) {
   const findings = [];
   walkConfigAndValidate(config3, "", config3, findings);
+  if (options.modelAvailability) {
+    findings.push(...validateConfiguredModels(config3, options.modelAvailability));
+  }
   const summary = {
     info: findings.filter((f) => f.severity === "info").length,
     warn: findings.filter((f) => f.severity === "warn").length,
@@ -40321,8 +40477,8 @@ function shouldRunOnStartup(automationConfig) {
   }
   return automationConfig.capabilities?.config_doctor_on_startup === true;
 }
-async function runConfigDoctorWithFixes(directory, config3, autoFix = false) {
-  const result = runConfigDoctor(config3, directory);
+async function runConfigDoctorWithFixes(directory, config3, autoFix = false, options = {}) {
+  const result = runConfigDoctor(config3, directory, options);
   const artifactPath = writeDoctorArtifact(directory, result);
   if (!autoFix) {
     return {
@@ -40342,7 +40498,7 @@ async function runConfigDoctorWithFixes(directory, config3, autoFix = false) {
   if (appliedFixes.length > 0) {
     const freshConfig = readConfigFromFile(directory);
     if (freshConfig) {
-      const newResult = runConfigDoctor(freshConfig.config, directory);
+      const newResult = runConfigDoctor(freshConfig.config, directory, options);
       writeDoctorArtifact(directory, newResult);
     }
   }
@@ -41964,6 +42120,23 @@ var init_tool_doctor = __esm(() => {
   ];
 });
 
+// src/utils/timeout.ts
+async function withTimeout(promise3, ms, timeoutError) {
+  let timer;
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(timeoutError), ms);
+    if (typeof timer.unref === "function") {
+      timer.unref();
+    }
+  });
+  try {
+    return await Promise.race([promise3, timeoutPromise]);
+  } finally {
+    if (timer !== undefined)
+      clearTimeout(timer);
+  }
+}
+
 // src/commands/doctor.ts
 function formatToolDoctorMarkdown(result) {
   const lines = [
@@ -42037,13 +42210,67 @@ function formatDoctorMarkdown(result) {
   return lines.join(`
 `);
 }
-async function handleDoctorCommand(directory, args) {
+function extractAvailableModelIds(response) {
+  const available = new Set;
+  if (response?.providers !== undefined && !Array.isArray(response.providers)) {
+    throw new Error("provider registry returned malformed provider list");
+  }
+  for (const provider of response?.providers ?? []) {
+    if (!provider || typeof provider !== "object" || !provider.id || !provider.models || typeof provider.models !== "object" || Array.isArray(provider.models)) {
+      continue;
+    }
+    for (const [modelKey, modelInfo] of Object.entries(provider.models)) {
+      available.add(`${provider.id}/${modelKey}`);
+      if (modelInfo && typeof modelInfo === "object" && modelInfo.id) {
+        available.add(`${provider.id}/${modelInfo.id}`);
+      }
+    }
+  }
+  return available;
+}
+async function loadModelAvailability(directory, client, options = {}) {
+  const providerClient = client;
+  const providers = providerClient?.config?.providers;
+  if (typeof providers !== "function") {
+    return;
+  }
+  try {
+    const response = await withTimeout(providers({ directory }), options.timeoutMs ?? MODEL_REGISTRY_TIMEOUT_MS, new Error(`OpenCode provider model registry lookup exceeded ${options.timeoutMs ?? MODEL_REGISTRY_TIMEOUT_MS}ms`));
+    if (response.error) {
+      return {
+        availableModelIds: new Set,
+        source: MODEL_REGISTRY_SOURCE,
+        error: typeof response.error === "string" ? response.error : JSON.stringify(response.error)
+      };
+    }
+    if (!response.data) {
+      return {
+        availableModelIds: new Set,
+        source: MODEL_REGISTRY_SOURCE,
+        error: "provider registry returned no data"
+      };
+    }
+    return {
+      availableModelIds: extractAvailableModelIds(response.data),
+      source: MODEL_REGISTRY_SOURCE
+    };
+  } catch (error93) {
+    return {
+      availableModelIds: new Set,
+      source: MODEL_REGISTRY_SOURCE,
+      error: error93 instanceof Error ? error93.message : String(error93)
+    };
+  }
+}
+async function handleDoctorCommand(directory, args, options = {}) {
   const enableAutoFix = args.includes("--fix") || args.includes("-f");
   const config3 = loadPluginConfig(directory);
-  const result = runConfigDoctor(config3, directory);
+  const modelAvailability = await loadModelAvailability(directory, options.client);
+  const doctorOptions = { modelAvailability };
+  const result = runConfigDoctor(config3, directory, doctorOptions);
   if (enableAutoFix && result.hasAutoFixableIssues) {
     const { runConfigDoctorWithFixes: runConfigDoctorWithFixes2 } = await Promise.resolve().then(() => (init_config_doctor(), exports_config_doctor));
-    const fixResult = await runConfigDoctorWithFixes2(directory, config3, true);
+    const fixResult = await runConfigDoctorWithFixes2(directory, config3, true, doctorOptions);
     return formatDoctorMarkdown(fixResult.result);
   }
   return formatDoctorMarkdown(result);
@@ -42052,6 +42279,7 @@ async function handleDoctorToolsCommand(directory, _args) {
   const result = runToolDoctor(directory);
   return formatToolDoctorMarkdown(result);
 }
+var MODEL_REGISTRY_TIMEOUT_MS = 3000, MODEL_REGISTRY_SOURCE = "OpenCode config.providers";
 var init_doctor = __esm(() => {
   init_loader();
   init_config_doctor();
@@ -51783,7 +52011,7 @@ function buildHelpText() {
   return lines.join(`
 `);
 }
-function createSwarmCommandHandler(directory, agents) {
+function createSwarmCommandHandler(directory, agents, client) {
   return async (input, output) => {
     if (input.command !== "swarm" && !input.command.startsWith("swarm-")) {
       return;
@@ -51830,7 +52058,8 @@ ${similar.map((cmd) => `  \u2022 /swarm ${cmd}`).join(`
           directory,
           args: resolved.remainingArgs,
           sessionID: input.sessionID,
-          agents
+          agents,
+          client
         });
       } catch (_err) {
         const cmdName = tokens[0] || "unknown";
@@ -51846,7 +52075,10 @@ ${text}`;
     if (isFirstRun) {
       const welcomeMessage = `Welcome to OpenCode Swarm! \uD83D\uDC1D
 ` + `
-` + `Run \`/swarm help\` to see all available commands, or \`/swarm config\` to review your configuration.
+` + `Start here: run \`/swarm diagnose\`, then \`/swarm agents\` to confirm the plugin loaded and see the exact models in use.
+` + `If a model is unavailable, edit \`.opencode/opencode-swarm.json\` or \`~/.config/opencode/opencode-swarm.json\` and run \`/swarm config doctor\`.
+` + `Useful next steps: \`/swarm brainstorm <task>\` for guided planning, \`/swarm full-auto on\` for autonomous runs after enabling it in config, and \`/swarm council <question>\` after enabling council.general.
+
 `;
       text = welcomeMessage + text;
     }
@@ -52163,13 +52395,13 @@ var init_registry = __esm(() => {
       clashesWithNativeCcCommand: "/config"
     },
     "config doctor": {
-      handler: (ctx) => handleDoctorCommand(ctx.directory, ctx.args),
+      handler: (ctx) => handleDoctorCommand(ctx.directory, ctx.args, { client: ctx.client }),
       description: "Run config doctor checks",
       subcommandOf: "config",
       category: "diagnostics"
     },
     "config-doctor": {
-      handler: (ctx) => handleDoctorCommand(ctx.directory, ctx.args),
+      handler: (ctx) => handleDoctorCommand(ctx.directory, ctx.args, { client: ctx.client }),
       description: "Run config doctor checks",
       subcommandOf: "config",
       category: "diagnostics",
@@ -52244,7 +52476,7 @@ var init_registry = __esm(() => {
       deprecated: true
     },
     doctor: {
-      handler: (ctx) => handleDoctorCommand(ctx.directory, ctx.args),
+      handler: (ctx) => handleDoctorCommand(ctx.directory, ctx.args, { client: ctx.client }),
       description: "Run config doctor checks",
       category: "diagnostics",
       aliasOf: "config doctor",

package/dist/commands/council.d.ts

@@ -14,4 +14,4 @@
  * Sanitizes the question to prevent prompt injection of rival MODE: headers
  * or control sequences (mirrors brainstorm.ts).
  */
-export declare function handleCouncilCommand(_directory: string, args: string[]): Promise<string>;
+export declare function handleCouncilCommand(directory: string, args: string[]): Promise<string>;