@link-assistant/hive-mind 2.18.0 → 2.19.1

package/src/router-routes.lib.mjs

@@ -0,0 +1,250 @@
+/**
+ * Router route dialects (issue #2202).
+ *
+ * Router 1.0.0 replaced every public route with one classified namespace —
+ * `/api/health`, `/api/management/*`, `/api/services/*` — and removed all the
+ * legacy root, `/v1/*` and overlapping `/api/*` aliases (upstream router#391).
+ * The two surfaces are **disjoint**: probing `0.119.0` and `1.2.0` side by side
+ * with Hive Mind's own `serve` arguments, every path that answers on one is a
+ * 404 on the other (`docs/case-studies/issue-2202/data/measurements/
+ * router-route-comparison-2026-09-04.md`, reproducible with
+ * `experiments/issue-2202/compare-router-routes.sh`).
+ *
+ * So `--use-router` cannot hard-code either shape. It has to know which router
+ * it is talking to and spell the paths accordingly, which is what this module
+ * is: two frozen tables plus the resolution rule, and nothing else. Keeping it
+ * a leaf module means `router-isolation.lib.mjs`, `router-sidecar.lib.mjs` and
+ * the model catalogue can all derive their URLs from one place, and a future
+ * dialect is a table entry rather than a grep.
+ *
+ * Why both are supported rather than just the newest: on `1.x` the GitHub proxy
+ * moved under `/api/services/github/api/v3`, and `gh` builds a custom host's
+ * REST base as `https://<host>/api/v3/` with no path-prefix setting — a
+ * limitation the router's own release notes state twice. There is therefore no
+ * client-side configuration that lets an unmodified `gh` reach the new prefix,
+ * and moving the pin unconditionally would delete the `gh` mediation issue
+ * #2164 shipped. Until upstream lands a `gh`-reachable base, the default pin
+ * stays on the legacy dialect and `1.x` is opt-in via `HIVE_MIND_ROUTER_IMAGE`,
+ * with the trade-off reported rather than discovered.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2202
+ * @see https://github.com/link-assistant/hive-mind/issues/2164
+ */
+
+/**
+ * Pre-1.0 routes. Everything hangs off the origin: Anthropic at `/v1/messages`,
+ * the OpenAI-compatible surface at `/v1`, GitHub at `/api/v3` and `/api/graphql`,
+ * git at `/git`. One `/v1/models` serves every provider the router has adopted,
+ * so there is a single catalogue endpoint rather than one per service.
+ */
+const LEGACY_DIALECT = Object.freeze({
+  id: 'legacy',
+  description: 'router < 1.0 (root, /v1/*, /api/v3)',
+  health: '/health',
+  // Pre-1.0 has no management namespace: token commands are CLI-only.
+  management: null,
+  services: Object.freeze({
+    anthropic: '',
+    openai: '/v1',
+    codex: '/v1',
+    qwen: '/v1',
+    // Never served on this dialect; callers must treat null as "not wired".
+    gemini: null,
+  }),
+  github: Object.freeze({
+    rest: '/api/v3',
+    graphql: '/api/graphql',
+    git: '/git',
+  }),
+  catalogues: Object.freeze([Object.freeze({ service: 'openai', path: '/v1/models', shape: 'openai' })]),
+  // An unmodified `gh` reaches the REST proxy, because its own base — /api/v3/ — is where the router serves it.
+  ghReachable: true,
+});
+
+/**
+ * Router >= 1.0. Three namespaces, one per route class, and one catalogue per
+ * adopted service. `/api/services/models` does not exist yet — the merged
+ * envelope is asked for upstream in link-assistant/router#417, but until it
+ * lands a client fans out.
+ *
+ * The catalogue routes answer a *superset* of the OpenAI envelope: `data` and
+ * `object` sit where OpenAI puts them, alongside `using_fallback`,
+ * `degraded_providers`, `degraded_reasons` and `catalog_conflicts`. The router
+ * keeps its own per-provider catalogue and retains the last known one when a
+ * refresh fails, so those fields are the difference between "this is live" and
+ * "this is what we last saw" — a reader that takes only `data[].id` discards
+ * the one signal that distinguishes them. Measured in
+ * `docs/case-studies/issue-2202/data/measurements/router-credentials-and-tokens-2026-09-04.md`.
+ */
+const CANONICAL_DIALECT = Object.freeze({
+  id: 'canonical',
+  description: 'router >= 1.0 (/api/health, /api/management/*, /api/services/*)',
+  health: '/api/health',
+  management: '/api/management',
+  services: Object.freeze({
+    anthropic: '/api/services/anthropic',
+    openai: '/api/services/openai/v1',
+    codex: '/api/services/codex/v1',
+    qwen: '/api/services/qwen/v1',
+    gemini: '/api/services/gemini',
+  }),
+  github: Object.freeze({
+    rest: '/api/services/github/api/v3',
+    graphql: '/api/services/github/api/graphql',
+    git: '/api/services/github/git',
+  }),
+  catalogues: Object.freeze([Object.freeze({ service: 'anthropic', path: '/api/services/anthropic/v1/models', shape: 'anthropic' }), Object.freeze({ service: 'openai', path: '/api/services/openai/v1/models', shape: 'openai' }), Object.freeze({ service: 'codex', path: '/api/services/codex/v1/models', shape: 'openai' }), Object.freeze({ service: 'qwen', path: '/api/services/qwen/v1/models', shape: 'openai' }), Object.freeze({ service: 'gemini', path: '/api/services/gemini/v1beta/models', shape: 'gemini' })]),
+  // `gh` has no path-prefix setting, so it cannot prepend /api/services/github.
+  ghReachable: false,
+});
+
+export const ROUTER_ROUTE_DIALECTS = Object.freeze({
+  legacy: LEGACY_DIALECT,
+  canonical: CANONICAL_DIALECT,
+});
+
+/** The dialect assumed when the router's version cannot be determined. */
+export const ROUTER_DEFAULT_UNKNOWN_DIALECT = 'canonical';
+
+/**
+ * Which router service each tool speaks to.
+ *
+ * `agent` is grouped with Claude because it is Anthropic-shaped, and `opencode`
+ * with plain OpenAI because it uses chat completions rather than the Codex
+ * `responses` wire API.
+ */
+export const ROUTER_TOOL_SERVICE = Object.freeze({
+  claude: 'anthropic',
+  agent: 'anthropic',
+  codex: 'codex',
+  opencode: 'openai',
+  qwen: 'qwen',
+  gemini: 'gemini',
+});
+
+/**
+ * Major version of a pinned router image reference.
+ *
+ * Handles `repo:1.2.0`, `repo:v1.2.0-rc.1` and a bare `1.2.0`. Returns null for
+ * a digest pin, a moving tag like `latest`, or anything else without a leading
+ * numeric component — the caller decides what an unknown version means.
+ *
+ * @param {string} image e.g. `ghcr.io/link-assistant/router:1.2.0`
+ * @returns {number|null}
+ */
+export function parseRouterImageMajor(image) {
+  const raw = String(image || '').trim();
+  if (!raw) return null;
+  // Strip a digest pin first: it carries no version information at all.
+  const withoutDigest = raw.split('@')[0];
+  const lastColon = withoutDigest.lastIndexOf(':');
+  const lastSlash = withoutDigest.lastIndexOf('/');
+  // A colon before the last slash is a registry port, not a tag separator.
+  const tag = lastColon > lastSlash ? withoutDigest.slice(lastColon + 1) : withoutDigest;
+  const match = /^v?(\d+)\./.exec(tag.trim());
+  if (!match) return null;
+  return Number(match[1]);
+}
+
+/**
+ * Decide which route dialect a router speaks.
+ *
+ * Resolution order, most explicit first:
+ *
+ * 1. `HIVE_MIND_ROUTER_ROUTES` — an escape hatch for an operator running a
+ *    build whose tag does not describe it (a fork, a digest pin, `latest`).
+ * 2. The pinned image tag, which is what Hive Mind itself starts.
+ * 3. {@link ROUTER_DEFAULT_UNKNOWN_DIALECT}, because an untagged or moving
+ *    reference is far more likely to be a recent build than a pre-1.0 one.
+ *
+ * @returns {{dialect: object, source: 'env'|'image'|'default', error: string|null}}
+ */
+export function resolveRouterRouteDialect({ image = null, env = process.env } = {}) {
+  const explicit = String(env?.HIVE_MIND_ROUTER_ROUTES || '')
+    .trim()
+    .toLowerCase();
+  if (explicit) {
+    const chosen = ROUTER_ROUTE_DIALECTS[explicit];
+    if (chosen) return { dialect: chosen, source: 'env', error: null };
+    return {
+      dialect: ROUTER_ROUTE_DIALECTS[ROUTER_DEFAULT_UNKNOWN_DIALECT],
+      source: 'default',
+      error: `HIVE_MIND_ROUTER_ROUTES must be one of ${Object.keys(ROUTER_ROUTE_DIALECTS).join(', ')}: ${explicit}`,
+    };
+  }
+  const major = parseRouterImageMajor(image);
+  if (major === null) {
+    return { dialect: ROUTER_ROUTE_DIALECTS[ROUTER_DEFAULT_UNKNOWN_DIALECT], source: 'default', error: null };
+  }
+  return { dialect: major >= 1 ? CANONICAL_DIALECT : LEGACY_DIALECT, source: 'image', error: null };
+}
+
+const trimOrigin = baseUrl => String(baseUrl || '').replace(/\/+$/, '');
+
+/**
+ * Join an origin and a dialect path into a base URL a client can be handed.
+ *
+ * @returns {string|null} null when either side is missing, so "not served on
+ *   this dialect" stays distinguishable from "served at the origin" (the
+ *   Anthropic case on the legacy dialect, where the path is an empty string).
+ */
+export function buildRouterRouteUrl(baseUrl, path) {
+  const origin = trimOrigin(baseUrl);
+  if (!origin || path === null || path === undefined) return null;
+  return `${origin}${path}`;
+}
+
+/**
+ * Base URL for one router service, e.g. `anthropic` or `codex`.
+ *
+ * @returns {string|null} null when the dialect does not serve it.
+ */
+export function buildRouterServiceUrl({ baseUrl, dialect, service } = {}) {
+  if (!dialect || !service) return null;
+  const path = dialect.services?.[service];
+  if (path === null || path === undefined) return null;
+  return buildRouterRouteUrl(baseUrl, path);
+}
+
+/**
+ * Base URL for the service a given tool talks to.
+ *
+ * @returns {string|null}
+ */
+export function buildRouterToolServiceUrl({ baseUrl, dialect, tool } = {}) {
+  const service = ROUTER_TOOL_SERVICE[String(tool || '').toLowerCase()];
+  if (!service) return null;
+  return buildRouterServiceUrl({ baseUrl, dialect, service });
+}
+
+/** Absolute URL of the router's unauthenticated health endpoint. */
+export function buildRouterHealthUrl({ baseUrl, dialect } = {}) {
+  return buildRouterRouteUrl(baseUrl, dialect?.health);
+}
+
+/**
+ * Absolute model-catalogue endpoints for a dialect, with the response shape each
+ * one returns so a caller can normalise without sniffing.
+ *
+ * @returns {Array<{service: string, url: string, shape: 'anthropic'|'openai'|'gemini'}>}
+ */
+export function buildRouterCatalogueEndpoints({ baseUrl, dialect } = {}) {
+  if (!dialect) return [];
+  const endpoints = [];
+  for (const entry of dialect.catalogues || []) {
+    const url = buildRouterRouteUrl(baseUrl, entry.path);
+    if (url) endpoints.push({ service: entry.service, url, shape: entry.shape });
+  }
+  return endpoints;
+}
+
+/**
+ * Git URL prefix that replaces `https://github.com/`.
+ *
+ * Always trailing-slashed: git matches `url.<prefix>.insteadOf` textually, and a
+ * missing slash silently produces `…/gitowner/repo`.
+ */
+export function buildRouterGitUrlPrefix({ baseUrl, dialect } = {}) {
+  const url = buildRouterRouteUrl(baseUrl, dialect?.github?.git);
+  return url ? `${url}/` : null;
+}

package/src/router-sidecar.lib.mjs

@@ -30,9 +30,9 @@ import os from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
 
-import { attachDockerNetwork, DEFAULT_IMAGE_TIMEOUT_MS, dockerOk, dockerText, ensureDockerVolume, ensureInternalDockerNetwork, inspectDockerContainer, readDockerImageDigest, readSidecarState, reconcileSidecarLeases, resolveSidecarStatePath, sleep, writeSidecarState } from './docker-sidecar.lib.mjs';
+import { attachDockerNetwork, DEFAULT_IMAGE_TIMEOUT_MS, dockerErrorMessage, dockerOk, dockerText, ensureDockerVolume, ensureInternalDockerNetwork, inspectDockerContainer, readDockerImageDigest, readSidecarState, reconcileSidecarLeases, resolveSidecarStatePath, sleep, writeSidecarState } from './docker-sidecar.lib.mjs';
 import { drainTaskSessionData } from './router-session-drain.lib.mjs';
-import { buildRouterTaskWiringScript, getInternalRouterBaseUrl, ROUTER_CREDENTIAL_MOUNTS, ROUTER_DATA_MOUNT, ROUTER_DATA_VOLUME_NAME, ROUTER_GH_CONFIG_MOUNT, ROUTER_SIDECAR_CONTAINER_NAME, ROUTER_SIDECAR_IMAGE, ROUTER_SIDECAR_LABEL, ROUTER_SIDECAR_NETWORK_ALIAS, ROUTER_SIDECAR_NETWORK_NAME, ROUTER_SIDECAR_PORT, ROUTER_TLS_DNS_NAMES, resolveRouterBaseUrl } from './router-isolation.lib.mjs';
+import { buildRouterTaskWiringScript, getInternalRouterBaseUrl, resolveRouterBaseUrl, resolveRouterDialect, resolveRouterSidecarImage, ROUTER_CREDENTIAL_MOUNTS, ROUTER_DATA_MOUNT, ROUTER_DATA_VOLUME_NAME, ROUTER_GH_CONFIG_MOUNT, ROUTER_SIDECAR_CONTAINER_NAME, ROUTER_SIDECAR_LABEL, ROUTER_SIDECAR_NETWORK_ALIAS, ROUTER_SIDECAR_NETWORK_NAME, ROUTER_SIDECAR_PORT, ROUTER_TLS_DNS_NAMES } from './router-isolation.lib.mjs';
 import { withStateLock } from './state-lock.lib.mjs';
 
 const execFileAsync = promisify(execFile);
@@ -65,8 +65,10 @@ export const isRouterSidecarEnabled = (env = process.env) => {
   return raw !== '0' && raw !== 'false' && raw !== 'no';
 };
 
-/** Image the sidecar runs, overridable for pinning or a local build. */
-export const resolveRouterSidecarImage = (env = process.env) => String(env?.HIVE_MIND_ROUTER_IMAGE || '').trim() || ROUTER_SIDECAR_IMAGE;
+// Image resolution and the route dialect derived from it now live in
+// router-isolation.lib.mjs, the leaf both this module and the task wiring
+// import (issue #2202). Re-exported so callers keep their import site.
+export { resolveRouterDialect, resolveRouterSidecarImage };
 
 export const resolveRouterSidecarStatePath = (env = process.env) => resolveSidecarStatePath(STATE_FILE_NAME, env);
 
@@ -135,6 +137,17 @@ export const buildRouterSidecarRunArgs = ({ image, tokenSecret, credentialMounts
     args.push('--env', `${mount.envVar}=${mount.target}`, '--volume', `${mount.source}:${mount.target}${mount.readOnly ? ':ro' : ''}`);
   }
 
+  // The ChatGPT backend gates its newest models behind a recent client version,
+  // and answers `Model not found` for them when the header is absent — which is
+  // why the pin is at or above 0.120.0, where the router started sending one.
+  // Its bundled default tracks a recent Codex CLI, so it is deliberately left
+  // alone by default: forwarding whatever `codex` happens to be installed here
+  // could send an *older* version than the router already claims and re-gate the
+  // models this pin exists to reach. An operator who needs a specific one sets
+  // CODEX_CLIENT_VERSION and it is passed straight through.
+  const codexClientVersion = String(env?.CODEX_CLIENT_VERSION || '').trim();
+  if (codexClientVersion) args.push('--env', `CODEX_CLIENT_VERSION=${codexClientVersion}`);
+
   const extraArgs = String(env?.HIVE_MIND_ROUTER_EXTRA_ARGS || '').trim();
   if (extraArgs) args.push(...extraArgs.split(/\s+/));
 
@@ -151,8 +164,12 @@ export const buildRouterSidecarRunArgs = ({ image, tokenSecret, credentialMounts
  * `bun`, which is used here as the HTTP client instead of adding a dependency to
  * an image Hive Mind does not own.
  */
-export const checkRouterSidecarHealth = async ({ containerName = ROUTER_SIDECAR_CONTAINER_NAME, run = execFileAsync, timeoutMs = 30_000 } = {}) => {
-  const probe = `fetch("https://127.0.0.1:${ROUTER_SIDECAR_PORT}/health").then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))`;
+export const checkRouterSidecarHealth = async ({ containerName = ROUTER_SIDECAR_CONTAINER_NAME, run = execFileAsync, timeoutMs = 30_000, env = process.env, dialect = null } = {}) => {
+  // /health on router 0.x, /api/health on 1.x — and a 404 either way if the
+  // wrong one is asked for, which would read as "unhealthy" and stall the
+  // acquire loop until it gave up (issue #2202).
+  const healthPath = (dialect || resolveRouterDialect({ env }).dialect).health;
+  const probe = `fetch("https://127.0.0.1:${ROUTER_SIDECAR_PORT}${healthPath}").then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))`;
   // The certificate names the alias, not 127.0.0.1, and this probe is a
   // liveness check on a loopback socket inside the container — there is no
   // network for anyone to sit in the middle of. Verification is disabled for
@@ -160,9 +177,12 @@ export const checkRouterSidecarHealth = async ({ containerName = ROUTER_SIDECAR_
   return dockerOk(run, ['exec', '--env', 'NODE_TLS_REJECT_UNAUTHORIZED=0', containerName, 'bun', '-e', probe], { timeoutMs });
 };
 
-export const waitForRouterSidecarHealth = async ({ containerName = ROUTER_SIDECAR_CONTAINER_NAME, run = execFileAsync, attempts = DEFAULT_HEALTH_ATTEMPTS, delayMs = DEFAULT_HEALTH_DELAY_MS, sleepImpl = sleep, log = null, verbose = false } = {}) => {
+export const waitForRouterSidecarHealth = async ({ containerName = ROUTER_SIDECAR_CONTAINER_NAME, run = execFileAsync, attempts = DEFAULT_HEALTH_ATTEMPTS, delayMs = DEFAULT_HEALTH_DELAY_MS, sleepImpl = sleep, log = null, verbose = false, env = process.env, dialect = null } = {}) => {
+  // Resolved once rather than per attempt: the answer cannot change between
+  // them, and probing the wrong path would fail every attempt identically.
+  const routes = dialect || resolveRouterDialect({ env }).dialect;
   for (let attempt = 1; attempt <= attempts; attempt += 1) {
-    if (await checkRouterSidecarHealth({ containerName, run })) {
+    if (await checkRouterSidecarHealth({ containerName, run, env, dialect: routes })) {
       if (verbose && log) await log(`[VERBOSE] ${LOG_PREFIX}: healthy after ${attempt} attempt(s)`);
       return { healthy: true, attempts: attempt };
     }
@@ -220,7 +240,7 @@ export const issueRouterTaskToken = async ({ sessionId, containerName = ROUTER_S
     if (verbose && log) await log(`[VERBOSE] ${LOG_PREFIX}: issued token ${tokenId || '(id unknown)'} for '${sessionId}'`);
     return { token, tokenId, error: null };
   } catch (error) {
-    return { token: null, tokenId: null, error: error?.stderr?.toString?.().trim() || error?.message || String(error) };
+    return { token: null, tokenId: null, error: dockerErrorMessage(error) };
   }
 };
 
@@ -355,7 +375,7 @@ export const acquireRouterSidecar = async ({ sessionId, githubRepo = null, env =
       try {
         await dockerText(run, buildRouterSidecarRunArgs({ image, tokenSecret, credentialMounts, env }), { timeoutMs });
       } catch (error) {
-        return { baseUrl: null, token: null, tokenId: null, leaseCount: state.leases.length, external: false, error: error?.stderr?.toString?.().trim() || error?.message || String(error) };
+        return { baseUrl: null, token: null, tokenId: null, leaseCount: state.leases.length, external: false, error: dockerErrorMessage(error) };
       }
       startedAt = now().toISOString();
       if (log) await log(`🔀 Router sidecar started with ${credentialMounts.length} credential mount(s); tasks will not receive vendor credentials directly`);
@@ -365,7 +385,7 @@ export const acquireRouterSidecar = async ({ sessionId, githubRepo = null, env =
     // acquire, including the ones that reuse a running container.
     await attachDockerNetwork({ network: ROUTER_SIDECAR_NETWORK_NAME, container: ROUTER_SIDECAR_CONTAINER_NAME, alias: ROUTER_SIDECAR_NETWORK_ALIAS, run, timeoutMs, log, verbose, logPrefix: LOG_PREFIX });
 
-    const health = await waitForRouterSidecarHealth({ run, attempts: healthAttempts, delayMs: healthDelayMs, sleepImpl, log, verbose });
+    const health = await waitForRouterSidecarHealth({ run, attempts: healthAttempts, delayMs: healthDelayMs, sleepImpl, log, verbose, env });
     if (!health.healthy) {
       return { baseUrl: null, token: null, tokenId: null, leaseCount: state.leases.length, external: false, error: 'router sidecar did not become healthy' };
     }
@@ -432,7 +452,7 @@ export const registerRouterProvider = async ({ providerArgs, containerName = ROU
     // `docker exec` bypasses the image entrypoint, so the binary is named again.
     await dockerText(run, ['exec', containerName, 'router', ...providerArgs], { timeoutMs });
   } catch (error) {
-    return { registered: false, error: error?.stderr?.toString?.().trim() || error?.message || String(error) };
+    return { registered: false, error: dockerErrorMessage(error) };
   }
   if (verbose && log) await log(`[VERBOSE] ${LOG_PREFIX}: registered provider '${providerArgs[providerArgs.indexOf('--name') + 1]}'`);
   return { registered: true, error: null };
@@ -479,7 +499,7 @@ export const wireRouterTaskContainer = async ({ sessionId, tool = 'claude', base
   try {
     await dockerText(run, ['exec', '--user', '0', sessionId, 'sh', '-c', script], { timeoutMs });
   } catch (error) {
-    return { wired: false, error: error?.stderr?.toString?.().trim() || error?.message || String(error) };
+    return { wired: false, error: dockerErrorMessage(error) };
   }
   if (verbose && log) await log(`[VERBOSE] ${LOG_PREFIX}: wired '${sessionId}' (CA installed, github=${githubMode}${routerIp ? ` via ${routerIp}` : ''})`);
   return { wired: true, error: null };

package/src/solve.config.lib.mjs

@@ -65,6 +65,11 @@ export const SOLVE_OPTION_DEFINITIONS = {
     default: false,
     hidden: true,
   },
+  'tool-update': {
+    type: 'boolean',
+    description: 'Check for a newer version of the agentic CLI before starting the task (issue #2202). Use --no-tool-update to skip.',
+    default: true,
+  },
   'tool-connection-check': {
     type: 'boolean',
     description: 'Perform tool connection check (enabled by default, use --no-tool-connection-check to skip). Does NOT affect model validation.',

package/src/solve.escalate.lib.mjs

@@ -90,6 +90,9 @@ const TIER_ALIASES = {
   fable: 'fable',
   'fable-5': 'fable',
   'claude-fable-5': 'fable',
+  // Fable 5.1 is the same escalation tier as Fable 5 (Issue #2202).
+  'fable-5-1': 'fable',
+  'claude-fable-5-1': 'fable',
 };
 
 /**

package/src/solve.mjs

@@ -220,6 +220,18 @@ if (argv.subAgentModel) await validateAndExitOnInvalidClaudeSubAgentModel(argv.s
 // Perform all system checks (skip tool connection check in dry-run or when --skip-tool-connection-check; model validation always runs)
 const prepareOnly = argv.dryRun || argv.onlyPrepareCommand;
 const skipToolConnectionCheck = prepareOnly || argv.skipToolConnectionCheck || argv.toolConnectionCheck === false;
+// Issue #2202 (R6): before we start driving the agentic CLI, make sure it is the
+// version the task needs — a stale binary is the usual reason a brand-new model
+// name is rejected. Best effort by design: `ensureAgenticCliFreshness` never
+// throws, and the updater underneath refuses to swap a binary while other tasks
+// are running. This run's own issue is excluded, because the idle gate detects
+// tasks by scanning process command lines and would otherwise find us.
+if (!prepareOnly && argv.toolUpdate !== false) {
+  const { describeFreshnessResult, ensureAgenticCliFreshness } = await import('./agentic-cli-freshness.lib.mjs');
+  const freshness = await ensureAgenticCliFreshness({ tools: [tool], verbose: argv.verbose, log: message => log(message, { verbose: true }), ignoreTasks: [issueUrl] });
+  const freshnessLine = describeFreshnessResult(freshness);
+  if (freshnessLine) await log(`🔄 ${freshnessLine}`);
+}
 const { cascadePlaywrightMcpDisable, ensureSolvePlaywrightMcpReady } = await import('./playwright-mcp.lib.mjs');
 await cascadePlaywrightMcpDisable(argv, log);
 if (!(await performSystemChecks(argv.minDiskSpace || 10240, skipToolConnectionCheck, argv.model, argv))) {

package/src/task.config.lib.mjs

@@ -68,6 +68,11 @@ export const createYargsConfig = yargsInstance =>
       description: '[EXPERIMENTAL] Route model traffic through the hive-mind-router sidecar instead of mounting AI credentials into the task container (issue #2164)',
       default: false,
     })
+    .option('tool-update', {
+      type: 'boolean',
+      description: 'Check for a newer version of the agentic CLI before starting the task (issue #2202). Use --no-tool-update to skip.',
+      default: true,
+    })
     .option('screen-name', {
       type: 'string',
       description: 'Screen session name when --isolation screen is used',

package/src/task.mjs

@@ -43,6 +43,7 @@ if (earlyArgs.length === 0 || earlyArgs.includes('--help') || earlyArgs.includes
   console.log('  --model, -m        Model to use');
   console.log('  --isolation        agent-commander isolation mode [default: docker]');
   console.log('  --use-router       [EXPERIMENTAL] Route model traffic through the hive-mind-router sidecar (issue #2164)');
+  console.log('  --no-tool-update   Skip the agentic CLI version check before starting');
   console.log('  --dry-run          Print split output without creating GitHub issues');
   console.log('  --verbose, -v      Enable verbose logging');
   console.log('  --output-format    Output format (text or json) [default: text]');
@@ -293,6 +294,17 @@ try {
   await log(formatAligned('🔒', 'Isolation:', argv.isolation));
   await log(formatAligned('✂️', 'Split mode:', argv.split ? `enabled (count: ${argv.splitCount})` : 'disabled'));
 
+  // Issue #2202 (R6): refresh the agentic CLI before the run drives it, for the
+  // same reason /solve does — and, for the same reason, not on a dry run, which
+  // drives no CLI at all. Never fatal: a registry outage must not cost the
+  // operator their task.
+  if (!argv.dryRun && argv.toolUpdate !== false) {
+    const { describeFreshnessResult, ensureAgenticCliFreshness } = await import('./agentic-cli-freshness.lib.mjs');
+    const freshness = await ensureAgenticCliFreshness({ tools: [argv.tool], verbose: argv.verbose, log: message => log(message, { verbose: true }), ignoreTasks: argv.split ? [taskInput] : [] });
+    const freshnessLine = describeFreshnessResult(freshness);
+    if (freshnessLine) await log(`🔄 ${freshnessLine}`);
+  }
+
   const result = argv.split ? await runSplitMode() : await runClarifyOrDecomposeMode();
 
   if (argv.outputFormat === 'json') {

package/src/telegram-bot.mjs

@@ -471,6 +471,9 @@ const { registerMergeCommand } = await import('./telegram-merge-command.lib.mjs'
 registerMergeCommand(bot, sharedCommandOpts);
 const { registerSolveQueueCommand } = await import('./telegram-solve-queue-command.lib.mjs');
 const { handleSolveQueueCommand } = registerSolveQueueCommand(bot, { ...sharedCommandOpts, getSolveQueue, safeReply, resolveLocale: resolveLocaleFromTelegramCtx });
+// Issue #2202 (R5): /models lists the merged model catalogue per tool.
+const { registerModelsCommand } = await import('./telegram-models-command.lib.mjs');
+const { handleModelsCommand } = registerModelsCommand(bot, { ...sharedCommandOpts, safeReply });
 const { registerSubscribeCommands } = await import('./telegram-subscribers.lib.mjs'); // #1688
 registerSubscribeCommands(bot, sharedCommandOpts);
 const { registerTaskCommands } = await import('./telegram-task-command.lib.mjs');
@@ -1027,7 +1030,7 @@ bot.on('message', async (ctx, next) => {
   const solveHandlers = Object.fromEntries(SOLVE_COMMAND_NAMES.map(command => [command, handleSolveCommand]));
   const taskHandlers = Object.fromEntries(TASK_COMMAND_NAMES.map(command => [command, handleTaskCommand]));
   const fixHandlers = Object.fromEntries(FIX_COMMAND_NAMES.map(command => [command, handleFixCommand]));
-  const handlers = { ...solveHandlers, ...taskHandlers, ...fixHandlers, auth: handleAuthCommand, hive: handleHiveCommand, queue: handleSolveQueueCommand };
+  const handlers = { ...solveHandlers, ...taskHandlers, ...fixHandlers, auth: handleAuthCommand, hive: handleHiveCommand, queue: handleSolveQueueCommand, models: handleModelsCommand };
 
   const handler = handlers[extracted.command];
   if (!handler) return next();

package/src/telegram-models-command.lib.mjs

@@ -0,0 +1,157 @@
+/**
+ * Telegram /models command implementation (issue #2202, R5).
+ *
+ * Shows the merged model catalogue for a tool: what this installation ships,
+ * what the live sources are serving right now, and which of the two a given
+ * model is in. Every source it reads is a listing endpoint that cannot bill a
+ * token (R7), and the answer is cached for an hour (R9), so asking often is
+ * free.
+ *
+ * Usage in chat:
+ *   /models                       -> the default tool (claude)
+ *   /models --tool codex          -> one specific tool
+ *   /models --all                 -> every tool, one message each
+ *   /models --details             -> add context window and pricing (R8)
+ *   /models --refresh             -> ignore the cache and re-read the sources
+ *   /models --no-update           -> skip the CLI version check (R6)
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2202
+ */
+
+import { ensureAgenticCliFreshness, describeFreshnessResult } from './agentic-cli-freshness.lib.mjs';
+import { MODEL_CATALOGUE_TOOLS, getMergedModelCatalogue } from './model-catalogue.lib.mjs';
+import { formatModelCatalogueTelegram } from './model-catalogue-render.lib.mjs';
+import { safeReply as defaultSafeReply } from './telegram-safe-reply.lib.mjs';
+
+const GROUP_ONLY_MESSAGE = '❌ The /models command only works in group chats. Please add this bot to a group and make it an admin.';
+
+/** The tool answered when the operator names none — the one Hive Mind drives by default. */
+export const DEFAULT_MODELS_COMMAND_TOOL = 'claude';
+
+/**
+ * Parse the argument tail of a `/models` message.
+ *
+ * Deliberately forgiving: a chat is not a shell, so `--tool codex`,
+ * `--tool=codex`, and a bare `codex` all mean the same thing. Anything it
+ * cannot make sense of comes back as `error` so the handler can say so instead
+ * of silently answering a different question.
+ */
+export const parseModelsCommandArgs = (text = '') => {
+  const result = { tools: [], all: false, refresh: false, details: false, update: true, error: null };
+  const tokens = String(text).trim().split(/\s+/).slice(1).filter(Boolean);
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    const lower = token.toLowerCase();
+    if (lower === '--all' || lower === 'all') {
+      result.all = true;
+      continue;
+    }
+    if (lower === '--refresh' || lower === 'refresh') {
+      result.refresh = true;
+      continue;
+    }
+    if (lower === '--details' || lower === '--detail' || lower === 'details') {
+      result.details = true;
+      continue;
+    }
+    if (lower === '--no-update' || lower === '--no-tool-update') {
+      result.update = false;
+      continue;
+    }
+    let value;
+    if (lower.startsWith('--tool=')) value = lower.slice('--tool='.length);
+    else if (lower === '--tool' || lower === '-t') value = (tokens[++index] ?? '').toLowerCase();
+    else if (!lower.startsWith('-')) value = lower;
+    else {
+      result.error = `Unknown option: ${token}`;
+      return result;
+    }
+
+    for (const entry of value.split(',').filter(Boolean)) {
+      if (!MODEL_CATALOGUE_TOOLS.includes(entry)) {
+        result.error = `Unknown tool: ${entry}. Known tools: ${MODEL_CATALOGUE_TOOLS.join(', ')}`;
+        return result;
+      }
+      if (!result.tools.includes(entry)) result.tools.push(entry);
+    }
+  }
+
+  if (result.all) result.tools = [...MODEL_CATALOGUE_TOOLS];
+  if (result.tools.length === 0) result.tools = [DEFAULT_MODELS_COMMAND_TOOL];
+  return result;
+};
+
+/**
+ * Registers the /models command handler with the bot.
+ *
+ * @param {Object} bot Telegraf bot instance
+ * @param {Object} options the shared command options every telegram command takes
+ * @returns {{ handleModelsCommand: Function }} the handler, for the text fallback
+ */
+export function registerModelsCommand(bot, options = {}) {
+  const { VERBOSE = false, isOldMessage, isForwardedOrReply, isGroupChat, isChatAuthorized, isTopicAuthorized, buildAuthErrorMessage, addBreadcrumb, safeReply, loadCatalogue = getMergedModelCatalogue, freshness = ensureAgenticCliFreshness, env = process.env } = options;
+
+  async function handleModelsCommand(ctx) {
+    VERBOSE && console.log('[VERBOSE] /models command received');
+
+    if (addBreadcrumb) {
+      await addBreadcrumb({
+        category: 'telegram.command',
+        message: '/models command received',
+        level: 'info',
+        data: { chatId: ctx.chat?.id, chatType: ctx.chat?.type, userId: ctx.from?.id, username: ctx.from?.username },
+      });
+    }
+
+    const reply = (text, replyOptions = {}) => (safeReply || defaultSafeReply)(ctx, text, { reply_to_message_id: ctx.message?.message_id, ...replyOptions });
+
+    if (isOldMessage?.(ctx)) {
+      VERBOSE && console.log('[VERBOSE] /models ignored: old message');
+      return;
+    }
+    if (isForwardedOrReply?.(ctx)) {
+      VERBOSE && console.log('[VERBOSE] /models ignored: forwarded or reply');
+      return;
+    }
+    if (isGroupChat && !isGroupChat(ctx)) {
+      VERBOSE && console.log('[VERBOSE] /models ignored: not a group chat');
+      await reply(GROUP_ONLY_MESSAGE);
+      return;
+    }
+    const authorize = isTopicAuthorized || (isChatAuthorized ? context => isChatAuthorized(context.chat.id) : () => true);
+    if (!authorize(ctx)) {
+      VERBOSE && console.log('[VERBOSE] /models ignored: not authorized');
+      await reply(buildAuthErrorMessage ? buildAuthErrorMessage(ctx) : `❌ This chat (ID: ${ctx.chat.id}) is not authorized.`);
+      return;
+    }
+
+    const args = parseModelsCommandArgs(ctx.message?.text ?? '');
+    if (args.error) {
+      await reply(`❌ ${args.error}`);
+      return;
+    }
+
+    // R6: give the agentic CLIs a chance to update before we describe what they
+    // can run. Best-effort — a failed refresh must not cost the operator their
+    // answer, so the outcome is reported and then ignored.
+    const refreshed = await freshness({ tools: args.tools, env, enabled: args.update, verbose: VERBOSE, log: async message => VERBOSE && console.log(`[VERBOSE] /models ${message}`) });
+    const freshnessLine = describeFreshnessResult(refreshed);
+    if (freshnessLine) await reply(freshnessLine);
+
+    for (const tool of args.tools) {
+      try {
+        const merged = await loadCatalogue({ tool, env, refresh: args.refresh });
+        await reply(formatModelCatalogueTelegram(merged, { details: args.details }));
+      } catch (error) {
+        await reply(`⚠️ Could not build the ${tool} catalogue: ${error?.message ?? error}`);
+      }
+    }
+  }
+
+  bot.command(/^models$/i, handleModelsCommand);
+
+  return { handleModelsCommand };
+}
+
+export default { DEFAULT_MODELS_COMMAND_TOOL, parseModelsCommandArgs, registerModelsCommand };

package/src/telegram-ui-messages.lib.mjs

@@ -92,7 +92,7 @@ export function buildTelegramHelpMessage({ locale = null, chatId, chatType = '',
     message.push('');
   }
 
-  const simpleCommandKeys = ['telegram.help_solve_queue', 'telegram.help_limits', 'telegram.help_version', 'telegram.help_language', 'telegram.help_accept_invites', 'telegram.help_merge', 'telegram.help_merge_usage', 'telegram.help_merge_description', 'telegram.help_subscribe', 'telegram.help_help', 'telegram.help_stop_start', 'telegram.help_stop_uuid', 'telegram.help_log', 'telegram.help_terminal_watch'];
+  const simpleCommandKeys = ['telegram.help_solve_queue', 'telegram.help_models', 'telegram.help_limits', 'telegram.help_version', 'telegram.help_language', 'telegram.help_accept_invites', 'telegram.help_merge', 'telegram.help_merge_usage', 'telegram.help_merge_description', 'telegram.help_subscribe', 'telegram.help_help', 'telegram.help_stop_start', 'telegram.help_stop_uuid', 'telegram.help_log', 'telegram.help_terminal_watch'];
   for (const key of simpleCommandKeys) addLine(message, key, {}, locale);
   message.push('');
   addLine(message, 'telegram.help_notifications', {}, locale);