@link-assistant/hive-mind 2.17.0 → 2.19.0

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/solve.validation.lib.mjs

@@ -35,6 +35,9 @@ const {
 } = githubLib;
 
 // Import git-related functions for identity validation and repair
+// Issue #2194: recovery diagnostics for URLs that had to be repaired before parsing.
+const { formatUrlRepairs, hasNotableRepair, revealHiddenCharacters } = await import('./github-url-recovery.lib.mjs');
+
 const gitLib = await import('./git.lib.mjs');
 const { checkGitIdentity, repairGitIdentity } = gitLib;
 
@@ -83,6 +86,16 @@ export const validateGitHubUrl = issueUrl => {
     return { isValid: false, isIssueUrl: null, isPrUrl: null };
   }
 
+  // Issue #2194: the URL needed repair before it could be understood. Say so up
+  // front, so a wrong guess is visible before a whole session runs against the
+  // wrong entity.
+  if (hasNotableRepair(parsedUrl.repairs)) {
+    console.error('ℹ️  Repaired the GitHub URL before solving:');
+    console.error(`     You typed: ${revealHiddenCharacters(issueUrl)}`);
+    console.error(`     Using:     ${parsedUrl.canonical || parsedUrl.normalized}`);
+    console.error(`     Repaired:  ${formatUrlRepairs(parsedUrl.repairs, { notableOnly: true })}`);
+  }
+
   // Check if it's an issue or pull request
   const isIssueUrl = parsedUrl.type === 'issue';
   const isPrUrl = parsedUrl.type === 'pull';
@@ -102,9 +115,12 @@ export const validateGitHubUrl = issueUrl => {
     isIssueUrl,
     isPrUrl,
     normalizedUrl: parsedUrl.normalized,
+    canonicalUrl: parsedUrl.canonical || parsedUrl.normalized,
     owner: parsedUrl.owner,
     repo: parsedUrl.repo,
     number: parsedUrl.number,
+    repairs: parsedUrl.repairs || [],
+    recovered: Boolean(parsedUrl.recovered),
   };
 };
 

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

@@ -169,6 +169,8 @@ const { formatUsageMessage, formatCodexLimitsSection, getAllCachedLimits } = lim
 const { handleShowLimitsFlag, captureStartSnapshotAndAppend } = await import('./telegram-show-limits.lib.mjs'); // #594
 const { getVersionInfo, formatVersionMessage } = await import('./version-info.lib.mjs');
 const { escapeMarkdown, escapeMarkdownV2, cleanNonPrintableChars, makeSpecialCharsVisible } = await import('./telegram-markdown.lib.mjs');
+const { formatUrlRepairs, hasNotableRepair, namesGitHubHost, revealHiddenCharacters } = await import('./github-url-recovery.lib.mjs'); // #2194
+
 const { getSolveQueue, createQueueExecuteCallback } = await import('./telegram-solve-queue.lib.mjs');
 const { applySolveToolAlias, getFirstParsedPositionalArg, getSolveCommandNameFromText, getSolveToolAliasFromText, moveArgumentToFront, parseArgsWithYargs, parseCommandArgs, SOLVE_COMMAND_NAMES } = await import('./telegram-solve-command.lib.mjs');
 const { executeStartScreen: executeStartScreenCommand, buildExecuteAndUpdateMessage } = await import('./telegram-command-execution.lib.mjs');
@@ -315,22 +317,28 @@ async function validateGitHubUrl(args, options = {}) {
   if (!rawUrl) return { valid: false, error: t('telegram.missing_github_url', { commandName }, { locale }) };
   // Issue #1102: Clean non-printable chars (Zero-Width Space, BOM, etc.) from URLs
   const url = cleanNonPrintableChars(rawUrl);
-  if (!url.includes('github.com')) return { valid: false, error: t('telegram.first_arg_must_be_github_url', {}, { locale }) };
+  // Issue #2194: the host may be typed in any case (GITHUB.COM) or hidden behind
+  // look-alike punctuation, and "github.com" in the path of another host is not a
+  // GitHub URL at all — so the recovery layer's host check makes the call, not a
+  // substring test that both misses the first case and accepts the second.
+  if (!namesGitHubHost(url)) return { valid: false, error: t('telegram.first_arg_must_be_github_url', {}, { locale }) };
   const parsed = parseGitHubUrl(url);
   if (!parsed.valid) return { valid: false, error: parsed.error || 'Invalid GitHub URL', suggestion: parsed.suggestion };
+  // Issue #2194: tell the user which URL we actually understood when we had to repair theirs.
+  const recoveryNotice = hasNotableRepair(parsed.repairs) ? t('telegram.url_recovered', { original: escapeMarkdown(makeSpecialCharsVisible(rawUrl)), used: escapeMarkdown(parsed.canonical), repairs: escapeMarkdown(formatUrlRepairs(parsed.repairs, { notableOnly: true })) }, { locale }) : null;
   if (!allowedTypes.includes(parsed.type)) {
     const allowedTypesStr = allowedTypes.map(t => (t === 'pull' ? 'pull request' : t)).join(', ');
     const baseUrl = `https://github.com/${parsed.owner}/${parsed.repo}`;
     const escapedUrl = escapeMarkdown(url),
       escapedBaseUrl = escapeMarkdown(baseUrl); // Issue #1102: escape for Markdown
     let error;
-    if (parsed.type === 'issues_list') error = t('telegram.url_issues_list_error', { url: escapedUrl, example: `${escapedBaseUrl}/issues/1` }, { locale });
-    else if (parsed.type === 'pulls_list') error = t('telegram.url_pulls_list_error', { url: escapedUrl, example: `${escapedBaseUrl}/pull/1` }, { locale });
+    if (parsed.type === 'issues_list') error = t('telegram.url_issues_list_error', { url: escapedBaseUrl, example: `${escapedBaseUrl}/issues/1` }, { locale });
+    else if (parsed.type === 'pulls_list') error = t('telegram.url_pulls_list_error', { url: escapedBaseUrl, example: `${escapedBaseUrl}/pull/1` }, { locale });
     else if (parsed.type === 'repo') error = t('telegram.url_repo_error', { allowedTypes: allowedTypesStr, url: escapedUrl, example: `${escapedBaseUrl}/issues/1` }, { locale });
     else error = t('telegram.url_must_be_type', { allowedTypes: allowedTypesStr, type: parsed.type.replace('_', ' ') }, { locale });
     return { valid: false, error };
   }
-  return { valid: true, parsed, normalizedUrl: url };
+  return { valid: true, parsed, normalizedUrl: url, recoveryNotice };
 }
 
 const executeAndUpdateMessage = buildExecuteAndUpdateMessage({ resolveIsolation, ISOLATION_BACKEND, isolationRunner, VERBOSE, executeStartScreen, trackSession, untrackSession, AUTO_WATCH_MESSAGE, startAutoTerminalWatchForSession, bot, formatExecutingWorkSessionMessage, formatStartingWorkSessionMessage });
@@ -463,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');
@@ -539,6 +550,10 @@ async function handleSolveCommand(ctx) {
   }
 
   VERBOSE && console.log(`[VERBOSE] ${solveCommandDisplay} passed all checks, executing...`);
+  // Issue #2194: the incoming text is the only record of what the user actually
+  // typed, and the log for that issue did not contain it — so an invisible
+  // character in the URL was invisible in the log too. Reveal it here.
+  VERBOSE && console.log(`[VERBOSE] ${solveCommandDisplay} raw text: ${revealHiddenCharacters(ctx.message.text)}`);
   const solveToolAlias = getSolveToolAliasFromText(ctx.message.text);
   let userArgs = parseCommandArgs(ctx.message.text);
 
@@ -607,6 +622,8 @@ async function handleSolveCommand(ctx) {
     await safeReply(ctx, errorMsg, { reply_to_message_id: ctx.message.message_id });
     return;
   }
+  // Issue #2194: the link needed repair, so show what we understood before we act on it.
+  if (validation.recoveryNotice) await safeReply(ctx, validation.recoveryNotice, { reply_to_message_id: ctx.message.message_id });
   userArgs = moveArgumentToFront(userArgs, validation.normalizedUrl, cleanNonPrintableChars);
   // Issue #2166: hand the spawned session the same canonical URL that is shown
   // in the chat, so the echo and the actual work can never disagree.
@@ -826,6 +843,8 @@ async function handleHiveCommand(ctx) {
     await safeReply(ctx, errorMsg, { reply_to_message_id: ctx.message.message_id });
     return;
   }
+  // Issue #2194: the link needed repair, so show what we understood before we act on it.
+  if (validation.recoveryNotice) await safeReply(ctx, validation.recoveryNotice, { reply_to_message_id: ctx.message.message_id });
   // Normalize issues_list/pulls_list to base repo URL, or use cleaned URL
   let normalizedArgs = moveArgumentToFront(userArgs, validation.normalizedUrl, cleanNonPrintableChars);
   const p = validation.parsed;
@@ -1011,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();