@link-assistant/hive-mind 2.18.0 → 2.19.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @link-assistant/hive-mind
 
+## 2.19.0
+
+### Minor Changes
+
+- ac07514: Stop the model list from ageing with the release: add the models that shipped since 2.17.0, hot-load the live catalogue from every source that costs nothing to read, expose it as `/models` and `hive-models`, teach `--use-router` both of the router's route dialects, and check the agentic CLI for a newer version before a task starts (issue #2202).
+
+  A provider can ship a model on a Tuesday, and until now Hive Mind could not name it until the next release: `src/models/index.mjs` was a static table and `--model` validated against nothing else. Six changes close that gap, none of which can spend a token or fail a run.
+
+  - **The new models are in the bundled table.** Fable 5.1, Mythos 5.1, GPT-6 Astra and GPT-5.6 Cyber, with their aliases, context windows and fallback chains. The additions pushed `src/models/index.mjs` past the 1350-line early warning of `scripts/check-file-line-limits.sh`, so the catalogue itself moved to `src/models/catalog.mjs` and is re-exported — the public surface is unchanged.
+  - **The catalogue hot-loads.** `src/model-catalogue.lib.mjs` merges six sources in a fixed precedence: the Link.Assistant Router's live catalogue, `codex debug models`, Anthropic's and OpenAI's `GET /v1/models`, models.dev for specifications, and the bundled table as the offline floor. models.dev only annotates; it never adds a model to the available list. Answers are cached per source and per tool for at least an hour, and `HIVE_MIND_MODEL_CATALOGUE_TTL_MINUTES` can only raise that floor.
+  - **Listing models cannot cost a token, structurally.** `assertTokenFreeSource` rejects any source that has not explicitly declared `billable: false`, so a source cannot become billable by omission, and `assertTokenFreeUrl` rejects any URL whose path is a completion endpoint no matter which descriptor carried it — a typo turning `/v1/models` into `/v1/messages` throws instead of spending. The four extraction methods that were considered and rejected, including driving either CLI's `/model` picker through its TUI, are recorded with their reasons so a future contributor does not re-derive them.
+  - **`/models` and `hive-models` show the whole spectrum.** Models are grouped as bundled-and-live, hot-loaded (a live source has it, this installation does not ship it), and bundled-only (shipped, unconfirmed), with `--tool`, `--details`, `--refresh`, `--json`, and `--all`. A footer names every source actually consulted, its outcome, and the age of the cache, so "why don't I see X" is answerable from the output — and a source that failed is described from its stderr, never by quoting the command line, so the router's leased token cannot ride a failure message into the footer. In Telegram the same flags are accepted the way a chat writes them: `/models codex`, `/models --tool codex` and `/models --tool=codex` are one command.
+  - **`--use-router` speaks both route dialects.** Router 1.0 removed every root, `/v1/*` and overlapping `/api/*` alias and moved each service under `/api/services/<service>/…` — measured, not assumed: on `1.2.0` every path that answers on `0.119.0` is a 404 and vice versa. `src/router-routes.lib.mjs` derives every base URL, the health probe and the catalogue path from the pinned image, so the pin can move in one line. It stays on `0.x` today, at `0.125.4`, because router `1.x` has no `gh`-reachable REST base and `gh` exposes no path-prefix option; the trade is reported by `describeRouterCoverageGaps` rather than discovered at runtime, and the upstream issues are filed.
+  - **A stale CLI is refreshed before the run needs it.** `/solve`, `/hive`, `/task`, `/fix`, `/models` and `hive-models` check the agentic CLI they are about to drive, because an outdated binary is the usual reason a brand-new model name is rejected. The check is throttled to once every six hours, narrowed to the one CLI in play, deferred entirely while other tasks are running, skipped for `--dry-run` and `--only-prepare-command`, and never fatal. Each run excludes its own task from the idle gate — otherwise a `/solve` asking for an update would find itself in the process table and defer forever. Opt out with `--no-tool-update` or `HIVE_MIND_AGENTIC_CLI_AUTO_UPDATE=0`.
+
+  Documentation is in `docs/MODELS.md` and its `zh`/`hi`/`ru` siblings; the full analysis — the requirement-by-requirement plan, the router route measurement, and what shipped differently from the plan — is in `docs/case-studies/issue-2202/`.
+
 ## 2.18.0
 
 ### Minor Changes

package/README.hi.md

@@ -515,6 +515,8 @@ Free Models via Kilo Gateway (with --tool agent):
 
 > **📖 मुफ्त मॉडल गाइड**: OpenCode Zen और Kilo Gateway प्रदाताओं सहित सभी मुफ्त मॉडलों के बारे में व्यापक जानकारी के लिए [docs/FREE_MODELS.hi.md](./docs/FREE_MODELS.hi.md) देखें।
 
+> **📖 लाइव मॉडल सूची**: यह देखने के लिए कि इस समय कौन-से मॉडल उपलब्ध हैं — उनमें वे भी जो इस installation के प्रकाशित होने के बाद जारी हुए — `hive-models` चलाएँ (या Telegram में `/models`)। देखें [docs/MODELS.hi.md](./docs/MODELS.hi.md)।
+
 #### `/hive` - Hive ऑर्केस्ट्रेशन चलाएँ
 
 ```

package/README.md

@@ -533,6 +533,8 @@ See [docs/CONFIGURATION.md](./docs/CONFIGURATION.md) for the full per-tool defau
 
 > **📖 Free Models Guide**: See [docs/FREE_MODELS.md](./docs/FREE_MODELS.md) for comprehensive information about all free models including OpenCode Zen and Kilo Gateway providers.
 
+> **📖 Live model list**: run `hive-models` (or `/models` in Telegram) to see which models are reachable right now, including ones released after this installation was published. See [docs/MODELS.md](./docs/MODELS.md).
+
 #### `/hive` - Run Hive Orchestration
 
 ```

package/README.ru.md

@@ -516,6 +516,8 @@ Free Models via Kilo Gateway (with --tool agent):
 
 > **📖 Руководство по бесплатным моделям**: см. [docs/FREE_MODELS.ru.md](./docs/FREE_MODELS.ru.md) для получения полной информации обо всех бесплатных моделях, включая провайдеры OpenCode Zen и Kilo Gateway.
 
+> **📖 Живой список моделей**: запустите `hive-models` (или `/models` в Telegram), чтобы увидеть, какие модели доступны прямо сейчас, включая вышедшие уже после публикации этой установки. См. [docs/MODELS.ru.md](./docs/MODELS.ru.md).
+
 #### `/hive` — Запуск оркестрации Hive
 
 ```

package/README.zh.md

@@ -512,6 +512,8 @@ Free Models via Kilo Gateway (with --tool agent):
 
 > **📖 免费模型指南**：有关所有免费模型（包括 OpenCode Zen 和 Kilo Gateway 提供商）的全面信息，请参见 [docs/FREE_MODELS.zh.md](./docs/FREE_MODELS.zh.md)。
 
+> **📖 实时模型列表**：运行 `hive-models`（或在 Telegram 中使用 `/models`）即可查看当前可用的模型，包括本次安装发布之后才推出的模型。参见 [docs/MODELS.zh.md](./docs/MODELS.zh.md)。
+
 #### `/hive` - 运行蜂群编排
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",
@@ -14,6 +14,7 @@
     "configure-claude": "./src/configure-claude.mjs",
     "start-screen": "./src/start-screen.mjs",
     "hive-screens": "./src/hive-screens.mjs",
+    "hive-models": "./src/hive-models.mjs",
     "hive-telegram-bot": "./src/telegram-bot.mjs"
   },
   "scripts": {
@@ -30,7 +31,7 @@
     "changeset": "changeset",
     "changeset:version": "changeset version",
     "changeset:publish": "npm run build:pre && changeset publish",
-    "build:pre": "chmod +x src/hive.mjs && chmod +x src/solve.mjs && chmod +x src/task.mjs && chmod +x src/fix.mjs && chmod +x src/cleanup.mjs && chmod +x src/review.mjs && chmod +x src/configure-claude.mjs && chmod +x src/start-screen.mjs && chmod +x src/hive-screens.mjs && chmod +x src/telegram-bot.mjs",
+    "build:pre": "chmod +x src/hive.mjs && chmod +x src/solve.mjs && chmod +x src/task.mjs && chmod +x src/fix.mjs && chmod +x src/cleanup.mjs && chmod +x src/review.mjs && chmod +x src/configure-claude.mjs && chmod +x src/start-screen.mjs && chmod +x src/hive-screens.mjs && chmod +x src/hive-models.mjs && chmod +x src/telegram-bot.mjs",
     "prepare": "husky"
   },
   "repository": {

package/src/agentic-cli-freshness.lib.mjs

@@ -0,0 +1,118 @@
+/**
+ * Pre-flight CLI freshness check (issue #2202, R6).
+ *
+ * R6: "/models and each /solve and other commands that relevant for
+ * claude/codex tools should check if new version available, and before
+ * starting task execution or before providing new models list - we should
+ * update them."
+ *
+ * `updateAgenticClisWhenIdle` already knows how to do the refresh safely — it
+ * throttles registry reads, takes a state lock, and refuses to swap a binary
+ * out from under a running task. What it lacked was a caller other than the
+ * Telegram maintenance tick, and two things a command entry point needs:
+ *
+ *  1. **Narrowing.** `hive-models --tool codex` should not reinstall Gemini.
+ *  2. **Not counting itself as busy.** The idle gate scans `/proc` for running
+ *     solve/task processes by issue reference. A solve run that checks for
+ *     updates after it has started would find *itself* and defer forever, so
+ *     the caller passes its own task reference to be ignored.
+ *
+ * Everything here is best-effort: a refresh failure must never stop the command
+ * the operator actually asked for.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2202
+ */
+
+import { AGENTIC_CLI_TARGETS, isAgenticCliAutoUpdateEnabled, updateAgenticClisWhenIdle } from './agentic-cli-updater.lib.mjs';
+
+const KNOWN_TOOL_IDS = new Set(AGENTIC_CLI_TARGETS.map(target => target.id));
+
+/** Tool aliases Hive Mind commands use that are not the updater's target id. */
+export const FRESHNESS_TOOL_ALIASES = Object.freeze({
+  'claude-code': 'claude',
+  'gemini-cli': 'gemini',
+  'qwen-code': 'qwen',
+  'github-copilot': 'copilot',
+  'opencode-ai': 'opencode',
+});
+
+/** Normalize whatever a command calls its tool into updater target ids. */
+export const resolveFreshnessTools = tools => {
+  const requested = (Array.isArray(tools) ? tools : [tools])
+    .flatMap(entry =>
+      String(entry ?? '')
+        .split(',')
+        .map(part => part.trim().toLowerCase())
+    )
+    .filter(Boolean);
+  const resolved = [];
+  for (const entry of requested) {
+    const id = FRESHNESS_TOOL_ALIASES[entry] ?? entry;
+    if (KNOWN_TOOL_IDS.has(id) && !resolved.includes(id)) resolved.push(id);
+  }
+  return resolved;
+};
+
+/** `https://github.com/o/r/issues/7` → `{owner:'o', repo:'r', number:7}`. */
+export const parseTaskRef = value => {
+  if (!value) return null;
+  if (typeof value === 'object') {
+    const number = Number(value.number);
+    if (!value.owner || !value.repo || !Number.isFinite(number)) return null;
+    return { owner: String(value.owner), repo: String(value.repo), number };
+  }
+  const match = String(value).match(/github\.com\/([^/\s]+)\/([^/\s]+)\/(?:issues|pull)\/(\d+)/i);
+  if (!match) return null;
+  return { owner: match[1], repo: match[2], number: Number(match[3]) };
+};
+
+const sameRef = (a, b) => a.owner.toLowerCase() === b.owner.toLowerCase() && a.repo.toLowerCase() === b.repo.toLowerCase() && a.number === b.number;
+
+/**
+ * Refresh the agentic CLIs a command is about to drive.
+ *
+ * Never throws: every failure path returns a status the caller can log and
+ * ignore. Statuses come from `updateAgenticClisWhenIdle`
+ * (`checked`/`throttled`/`busy`/`disabled`) plus `skipped` for a caller opt-out
+ * and `error` when the refresh itself blew up.
+ *
+ * @param {object} options
+ * @param {string|string[]} options.tools tool ids/aliases the command needs
+ * @param {boolean} options.enabled false for `--no-update`
+ * @param {Array} options.ignoreTasks task refs or GitHub URLs that are *this* run
+ */
+export const ensureAgenticCliFreshness = async ({ tools = [], env = process.env, log = null, verbose = false, force = false, enabled = true, ignoreTasks = [], getActiveTasksImpl = null, updateImpl = updateAgenticClisWhenIdle, minIntervalMs = undefined } = {}) => {
+  const only = resolveFreshnessTools(tools);
+  if (!enabled) return { status: 'skipped', reason: 'the caller disabled the update check (--no-update)', tools: only, updated: [], upToDate: [], failed: [] };
+  if (!isAgenticCliAutoUpdateEnabled(env)) return { status: 'disabled', reason: 'HIVE_MIND_AGENTIC_CLI_AUTO_UPDATE is off', tools: only, updated: [], upToDate: [], failed: [] };
+
+  const ignored = ignoreTasks.map(parseTaskRef).filter(Boolean);
+  let activeTasks = getActiveTasksImpl;
+  if (ignored.length > 0) {
+    const inner = getActiveTasksImpl ?? (await import('./cleanup.os.lib.mjs')).getActiveTasks;
+    activeTasks = async options => {
+      const tasks = await inner(options);
+      return tasks.filter(task => !ignored.some(ref => sameRef(ref, { owner: task.owner, repo: task.repo, number: Number(task.number) })));
+    };
+  }
+
+  try {
+    const result = await updateImpl({ env, log, verbose, force, only, ...(activeTasks ? { getActiveTasksImpl: activeTasks } : {}), ...(minIntervalMs === undefined ? {} : { minIntervalMs }) });
+    return { tools: only, updated: [], upToDate: [], failed: [], ...result };
+  } catch (error) {
+    const message = String(error?.message ?? error);
+    if (verbose && log) await log(`[VERBOSE] agentic-cli-freshness: refresh failed — ${message}`);
+    return { status: 'error', reason: message, tools: only, updated: [], upToDate: [], failed: [] };
+  }
+};
+
+/** One human-readable line summarising a freshness result, or null when there is nothing to say. */
+export const describeFreshnessResult = result => {
+  if (!result) return null;
+  if (result.updated?.length > 0) return `⬆️ Updated ${result.updated.map(entry => `${entry.id} ${entry.from} → ${entry.to}`).join(', ')}`;
+  if (result.failed?.length > 0) return `⚠️ Could not update ${result.failed.map(entry => entry.id).join(', ')}`;
+  if (result.status === 'busy') return 'Skipped the CLI update check: other tasks are running.';
+  return null;
+};
+
+export default { FRESHNESS_TOOL_ALIASES, describeFreshnessResult, ensureAgenticCliFreshness, parseTaskRef, resolveFreshnessTools };

package/src/agentic-cli-updater.lib.mjs

@@ -81,10 +81,14 @@ const parseIdList = value =>
  * `HIVE_MIND_AGENTIC_CLI_UPDATE_ONLY` is an allow-list and
  * `HIVE_MIND_AGENTIC_CLI_UPDATE_EXCLUDE` a deny-list, both by target id.
  */
-export const listAgenticCliUpdateTargets = (env = process.env) => {
+export const listAgenticCliUpdateTargets = (env = process.env, { only: requested = [] } = {}) => {
   const only = parseIdList(env.HIVE_MIND_AGENTIC_CLI_UPDATE_ONLY);
   const excluded = new Set(parseIdList(env.HIVE_MIND_AGENTIC_CLI_UPDATE_EXCLUDE));
-  return AGENTIC_CLI_TARGETS.filter(target => (only.length === 0 || only.includes(target.id)) && !excluded.has(target.id));
+  // A caller-supplied narrowing (issue #2202, R6: refresh the CLIs a command is
+  // about to drive) intersects with the operator's allow-list rather than
+  // overriding it — an operator who excluded a CLI still gets it excluded.
+  const caller = parseIdList(Array.isArray(requested) ? requested.join(',') : requested);
+  return AGENTIC_CLI_TARGETS.filter(target => (only.length === 0 || only.includes(target.id)) && (caller.length === 0 || caller.includes(target.id)) && !excluded.has(target.id));
 };
 
 /** First semantic version in a CLI's `--version` output, which is rarely bare. */
@@ -147,7 +151,7 @@ export const installAgenticCli = async (target, { run = execFileAsync, timeoutMs
  *
  * @returns {Promise<{status: 'disabled'|'busy'|'throttled'|'checked', updated: object[], upToDate: object[], failed: object[]}>}
  */
-export const updateAgenticClisWhenIdle = async ({ env = process.env, fsImpl = fs, run = execFileAsync, log = null, verbose = false, getActiveTasksImpl = null, now = () => new Date(), minIntervalMs = DEFAULT_CLI_UPDATE_INTERVAL_MS, force = false, lockOptions = {} } = {}) => {
+export const updateAgenticClisWhenIdle = async ({ env = process.env, fsImpl = fs, run = execFileAsync, log = null, verbose = false, getActiveTasksImpl = null, now = () => new Date(), minIntervalMs = DEFAULT_CLI_UPDATE_INTERVAL_MS, force = false, only = [], lockOptions = {} } = {}) => {
   if (!isAgenticCliAutoUpdateEnabled(env)) {
     if (verbose && log) await log('[VERBOSE] agentic-cli-updater: disabled by HIVE_MIND_AGENTIC_CLI_AUTO_UPDATE');
     return { status: 'disabled', updated: [], upToDate: [], failed: [] };
@@ -176,7 +180,7 @@ export const updateAgenticClisWhenIdle = async ({ env = process.env, fsImpl = fs
       const failed = [];
       const tools = { ...state.tools };
 
-      for (const target of listAgenticCliUpdateTargets(env)) {
+      for (const target of listAgenticCliUpdateTargets(env, { only })) {
         const installed = await readInstalledCliVersion(target, { run });
         if (!installed) {
           // Not installed on this host (image variants differ); nothing to refresh.

package/src/docker-sidecar.lib.mjs

@@ -49,8 +49,24 @@ export const dockerOk = async (run, args, options) => {
   }
 };
 
+/**
+ * Mask the secrets a `docker` argv carries.
+ *
+ * `execFile` builds a failed command's message as "Command failed: <argv…>",
+ * and the argvs assembled here carry real secrets: the router's
+ * `--env TOKEN_SECRET=…`, a leased `--env ROUTER_CATALOGUE_TOKEN=…`, a
+ * provider's `--api-key …`. stderr is preferred over that message precisely
+ * because it describes the failure without the command line, but stderr is
+ * empty when the process is killed on a timeout — so whatever survives is
+ * masked before anyone reads it.
+ */
+const maskDockerArgvSecrets = text =>
+  String(text ?? '')
+    .replace(/(--env[= ])([A-Za-z_][A-Za-z0-9_]*)=(\S+)/g, '$1$2=***')
+    .replace(/(--(?:api-key|token|secret|password)[= ])(\S+)/g, '$1***');
+
 /** The message a failed `docker` invocation should be reported with. */
-export const dockerErrorMessage = error => error?.stderr?.toString?.().trim() || error?.message || String(error);
+export const dockerErrorMessage = error => maskDockerArgvSecrets(error?.stderr?.toString?.().trim() || error?.message || String(error));
 
 /**
  * Inspect a container without treating "absent" as an error.

package/src/hive-models.lib.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+
+/**
+ * Shared runner for the `hive-models` bin command (issue #2202, R5).
+ *
+ * R5 asks for a listing that merges what this installation ships with what the
+ * providers are serving right now, "from fully supported, to hot loaded", per
+ * tool. This module is the CLI half of that; `telegram-models-command.lib.mjs`
+ * is the `/models` half, and both render through
+ * `model-catalogue-render.lib.mjs` so the two can never disagree.
+ *
+ * R6 is honoured here too: before printing a catalogue the runner gives the
+ * agentic CLIs a chance to update, because a stale `codex` binary is exactly
+ * what makes a new model look unavailable.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2202
+ */
+
+import { ensureAgenticCliFreshness, describeFreshnessResult } from './agentic-cli-freshness.lib.mjs';
+import { parseCliArgumentsWithLino } from './cli-arguments.lib.mjs';
+import { MODEL_CATALOGUE_TOOLS, getMergedModelCatalogue } from './model-catalogue.lib.mjs';
+import { formatModelCatalogueText } from './model-catalogue-render.lib.mjs';
+
+export const HIVE_MODELS_HELP = `Usage: hive-models [--tool <name>...] [--refresh] [--details] [--json] [--no-update] [--verbose]
+
+List the models Hive Mind can drive, merged from every source that can be read
+without spending a token — the router's live catalogue, the provider listing
+endpoints, the codex CLI's own catalogue, models.dev metadata, and the models
+bundled with this installation.
+
+Models are grouped so it is obvious what each one is:
+  Bundled and live   shipped here and confirmed reachable now
+  Hot loaded         a live source has it, this installation does not ship it
+  Bundled only       shipped here, no live source confirmed it
+
+Options:
+  -t, --tool <name>    Restrict to one tool (${MODEL_CATALOGUE_TOOLS.join(', ')}).
+                       Repeatable; defaults to every tool.
+      --refresh        Ignore the cached answer and re-read every live source
+      --details        Show context window, pricing, and which source had it
+      --json           Print machine-readable JSON instead of text
+      --no-update      Do not check the agentic CLIs for a newer version first
+                       (also spelled --no-tool-update, as in /solve and /task)
+  -v, --verbose        Print diagnostics to stderr
+  -h, --help           Show this help and exit
+
+Environment:
+  HIVE_MIND_MODELS_HOT_LOAD=0            Only list the bundled catalogue
+  HIVE_MIND_MODELS_ROUTER=0              Skip the router source specifically
+  HIVE_MIND_MODEL_CATALOGUE_TTL_MINUTES  Raise the 60 minute cache lifetime
+  HIVE_MIND_AGENTIC_CLI_AUTO_UPDATE=0    Never update the CLIs
+
+Examples:
+  hive-models                      # every tool, cached answers
+  hive-models --tool codex         # just codex
+  hive-models --tool claude --details --refresh
+  hive-models --json | jq '.tools.claude.liveOnly'
+
+Reference:
+  https://github.com/link-assistant/hive-mind/issues/2202
+`;
+
+const VALUE_FLAGS = new Set(['--tool', '-t']);
+const BOOLEAN_FLAGS = new Set(['--refresh', '--details', '--json', '--no-update', '--no-tool-update', '--verbose', '-v', '--help', '-h']);
+
+// `/solve`, `/hive` and `/task` spell the opt-out `--no-tool-update` (it lives in
+// their `tool-*` namespace). Accept that spelling here too, so the flag an
+// operator already knows works everywhere it makes sense (issue #2202, R6).
+const normaliseUpdateFlag = arg => (arg === '--no-tool-update' ? '--no-update' : arg);
+
+const createHiveModelsYargsConfig = yargsInstance => yargsInstance.usage('Usage: hive-models [--tool <name>...] [--refresh] [--details] [--json] [--no-update] [--verbose]').option('tool', { type: 'array', alias: 't', default: [] }).option('refresh', { type: 'boolean', default: false }).option('details', { type: 'boolean', default: false }).option('json', { type: 'boolean', default: false }).option('update', { type: 'boolean', default: true }).option('verbose', { type: 'boolean', alias: 'v', default: false }).option('help', { type: 'boolean', alias: 'h', default: false }).help(false).version(false).strict(false);
+
+/**
+ * Parse argv for `hive-models`. Returns `error` as a string rather than
+ * throwing, so the bin can print it and exit non-zero.
+ */
+export const parseHiveModelsArgs = argv => {
+  const result = { tools: [], refresh: false, details: false, json: false, update: true, verbose: false, help: false, error: null };
+  const help = argv.includes('--help') || argv.includes('-h');
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    const [name] = arg.split('=');
+    if (VALUE_FLAGS.has(name)) {
+      if (!arg.includes('=')) index += 1;
+      continue;
+    }
+    if (!BOOLEAN_FLAGS.has(arg)) {
+      result.error = `Unknown option: ${arg}`;
+      return result;
+    }
+  }
+
+  let parsed;
+  try {
+    parsed = parseCliArgumentsWithLino({
+      argv: argv.filter(arg => arg !== '--help' && arg !== '-h').map(normaliseUpdateFlag),
+      commandName: 'hive-models',
+      createYargsConfig: createHiveModelsYargsConfig,
+      lenv: { enabled: false },
+      getenv: { enabled: false },
+    });
+  } catch (err) {
+    result.error = err.message || String(err);
+    return result;
+  }
+
+  result.help = help;
+  result.refresh = parsed.refresh === true;
+  result.details = parsed.details === true;
+  result.json = parsed.json === true;
+  result.update = parsed.update !== false;
+  result.verbose = parsed.verbose === true || parsed.v === true;
+
+  const requested = []
+    .concat(parsed.tool ?? [])
+    .flatMap(entry =>
+      String(entry)
+        .split(',')
+        .map(part => part.trim().toLowerCase())
+    )
+    .filter(Boolean);
+  for (const tool of requested) {
+    if (!MODEL_CATALOGUE_TOOLS.includes(tool)) {
+      result.error = `Unknown tool: ${tool}. Known tools: ${MODEL_CATALOGUE_TOOLS.join(', ')}`;
+      return result;
+    }
+    if (!result.tools.includes(tool)) result.tools.push(tool);
+  }
+  if (result.tools.length === 0) result.tools = [...MODEL_CATALOGUE_TOOLS];
+  return result;
+};
+
+/**
+ * Top-level orchestrator used by the bin. `deps` is injected so tests can run
+ * the whole command without a network, a router, or a package registry.
+ */
+export const runHiveModels = async (argv, deps = {}) => {
+  const { env = process.env, log = (...args) => console.log(...args), error = (...args) => console.error(...args), loadCatalogue = getMergedModelCatalogue, freshness = ensureAgenticCliFreshness } = deps;
+
+  const args = parseHiveModelsArgs(argv);
+  if (args.help) {
+    log(HIVE_MODELS_HELP);
+    return 0;
+  }
+  if (args.error) {
+    error(args.error);
+    return 1;
+  }
+
+  const debug = args.verbose ? (...parts) => error('[hive-models]', ...parts) : () => {};
+
+  // R6: refresh the CLIs before answering, so the list describes the binaries
+  // the next run will actually use. Best-effort — never fatal.
+  const refreshed = await freshness({ tools: args.tools, env, verbose: args.verbose, enabled: args.update, log: async message => debug(message) });
+  debug(`cli freshness: ${refreshed.status}${refreshed.reason ? ` (${refreshed.reason})` : ''}`);
+  const freshnessLine = describeFreshnessResult(refreshed);
+
+  const results = {};
+  let failures = 0;
+  for (const tool of args.tools) {
+    try {
+      results[tool] = await loadCatalogue({ tool, env, refresh: args.refresh, log: async message => debug(message) });
+    } catch (err) {
+      failures += 1;
+      error(`Could not build the ${tool} catalogue: ${err?.message ?? err}`);
+    }
+  }
+
+  if (args.json) {
+    log(JSON.stringify({ generatedAt: new Date().toISOString(), cliUpdate: refreshed, tools: results }, null, 2));
+    return failures > 0 && Object.keys(results).length === 0 ? 1 : 0;
+  }
+
+  if (freshnessLine) log(freshnessLine);
+  const sections = Object.values(results).map(merged => formatModelCatalogueText(merged, { details: args.details, defaultModel: merged.default }));
+  log(sections.join('\n\n'));
+  return failures > 0 && sections.length === 0 ? 1 : 0;
+};
+
+export default { HIVE_MODELS_HELP, parseHiveModelsArgs, runHiveModels };

package/src/hive-models.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+/**
+ * `hive-models` — list every model Hive Mind can drive, merging the models
+ * bundled with this installation with the ones the providers are serving right
+ * now (issue #2202, R5).
+ *
+ * Live sources are read only through endpoints that cannot bill a token, and
+ * the merged answer is cached for an hour, so running this repeatedly is free.
+ *
+ * See issue #2202.
+ */
+
+import { runHiveModels } from './hive-models.lib.mjs';
+import { setupStdioLogInterceptor } from './lib.mjs';
+
+setupStdioLogInterceptor();
+
+const exitCode = await runHiveModels(process.argv.slice(2));
+process.exit(exitCode);

package/src/locales/en.lino

@@ -590,6 +590,7 @@ en
         usage "Usage: `/hive <github-url> [options]`"
         example "Example: `/hive https://github.com/owner/repo`"
         disabled "*/hive* - ❌ Disabled"
+      models "*/models* - List available models, merged from this installation and every live source. Usage: `/models [--tool claude|codex|...] [--details] [--refresh] [--all]`"
       limits "*/limits* - Show usage limits"
       version "*/version* - Show bot and runtime versions"
       language "*/language* `[en|ru|zh|hi]` - Set or show your preferred reply language (in-memory only, per-user)"
@@ -611,7 +612,7 @@ en
       isolation
         mode "🔒 *Isolation Mode:* `{{isolationBackend}}` (experimental)"
       group
-        note "⚠️ *Note:* /solve, /do, /continue, /claude, /codex, /opencode, /agent, /gemini, /qwen, /task, /split, /fix, /hive, /queue, /limits, /version, /accept\\_invites, /merge, /stop and /start commands only work in group chats. /terminal\\_watch, /watch, /subscribe and /unsubscribe work in private and group chats."
+        note "⚠️ *Note:* /solve, /do, /continue, /claude, /codex, /opencode, /agent, /gemini, /qwen, /task, /split, /fix, /hive, /queue, /models, /limits, /version, /accept\\_invites, /merge, /stop and /start commands only work in group chats. /terminal\\_watch, /watch, /subscribe and /unsubscribe work in private and group chats."
       common
         options "🔧 *Common Options:*"
       model

package/src/locales/hi.lino

@@ -590,6 +590,7 @@ hi
         usage "उपयोग: `/hive <github-url> [options]`"
         example "उदाहरण: `/hive https://github.com/owner/repo`"
         disabled "*/hive* - ❌ अक्षम"
+      models "*/models* - उपलब्ध models दिखाएँ, जो इस installation और सभी live sources से मिलाकर बनाई गई हैं। उपयोग: `/models [--tool claude|codex|...] [--details] [--refresh] [--all]`"
       limits "*/limits* - उपयोग सीमाएँ दिखाएँ"
       version "*/version* - bot और runtime versions दिखाएँ"
       language "*/language* `[en|ru|zh|hi]` - अपनी पसंदीदा reply language सेट या दिखाएँ (in-memory, per-user)"
@@ -611,7 +612,7 @@ hi
       isolation
         mode "🔒 *Isolation Mode:* `{{isolationBackend}}` (experimental)"
       group
-        note "⚠️ *नोट:* /solve, /do, /continue, /claude, /codex, /opencode, /agent, /gemini, /qwen, /task, /split, /fix, /hive, /queue, /limits, /version, /accept\\_invites, /merge, /stop और /start commands केवल group chats में काम करती हैं। /terminal\\_watch, /watch, /subscribe और /unsubscribe private और group chats में काम करती हैं।"
+        note "⚠️ *नोट:* /solve, /do, /continue, /claude, /codex, /opencode, /agent, /gemini, /qwen, /task, /split, /fix, /hive, /queue, /models, /limits, /version, /accept\\_invites, /merge, /stop और /start commands केवल group chats में काम करती हैं। /terminal\\_watch, /watch, /subscribe और /unsubscribe private और group chats में काम करती हैं।"
       common
         options "🔧 *Common Options:*"
       model

package/src/locales/ru.lino

@@ -590,6 +590,7 @@ ru
         usage "Использование: `/hive <github-url> [options]`"
         example "Пример: `/hive https://github.com/owner/repo`"
         disabled "*/hive* - ❌ Отключено"
+      models "*/models* - Показать доступные модели, объединённые из этой установки и всех живых источников. Использование: `/models [--tool claude|codex|...] [--details] [--refresh] [--all]`"
       limits "*/limits* - Показать лимиты использования"
       version "*/version* - Показать версии бота и среды выполнения"
       language "*/language* `[en|ru|zh|hi]` - Установить или показать предпочитаемый язык ответов (в памяти, для пользователя)"
@@ -611,7 +612,7 @@ ru
       isolation
         mode "🔒 *Режим изоляции:* `{{isolationBackend}}` (экспериментально)"
       group
-        note "⚠️ *Замечание:* команды /solve, /do, /continue, /claude, /codex, /opencode, /agent, /gemini, /qwen, /task, /split, /fix, /hive, /queue, /limits, /version, /accept\\_invites, /merge, /stop и /start работают только в групповых чатах. /terminal\\_watch, /watch, /subscribe и /unsubscribe работают в личных и групповых чатах."
+        note "⚠️ *Замечание:* команды /solve, /do, /continue, /claude, /codex, /opencode, /agent, /gemini, /qwen, /task, /split, /fix, /hive, /queue, /models, /limits, /version, /accept\\_invites, /merge, /stop и /start работают только в групповых чатах. /terminal\\_watch, /watch, /subscribe и /unsubscribe работают в личных и групповых чатах."
       common
         options "🔧 *Общие опции:*"
       model

package/src/locales/zh.lino

@@ -590,6 +590,7 @@ zh
         usage "用法：`/hive <github-url> [options]`"
         example "示例：`/hive https://github.com/owner/repo`"
         disabled "*/hive* - ❌ 已禁用"
+      models "*/models* - 列出可用模型，合并本次安装自带的模型与所有实时来源的模型。用法：`/models [--tool claude|codex|...] [--details] [--refresh] [--all]`"
       limits "*/limits* - 显示使用限额"
       version "*/version* - 显示机器人和运行时版本"
       language "*/language* `[en|ru|zh|hi]` - 设置或显示首选回复语言（内存中，按用户）"
@@ -611,7 +612,7 @@ zh
       isolation
         mode "🔒 *隔离模式：* `{{isolationBackend}}`（实验性）"
       group
-        note "⚠️ *注意：* /solve、/do、/continue、/claude、/codex、/opencode、/agent、/gemini、/qwen、/task、/split、/fix、/hive、/queue、/limits、/version、/accept\\_invites、/merge、/stop 和 /start 仅在群聊中有效。/terminal\\_watch、/watch、/subscribe 和 /unsubscribe 在私聊和群聊中有效。"
+        note "⚠️ *注意：* /solve、/do、/continue、/claude、/codex、/opencode、/agent、/gemini、/qwen、/task、/split、/fix、/hive、/queue、/models、/limits、/version、/accept\\_invites、/merge、/stop 和 /start 仅在群聊中有效。/terminal\\_watch、/watch、/subscribe 和 /unsubscribe 在私聊和群聊中有效。"
       common
         options "🔧 *常用选项：*"
       model