@link-assistant/hive-mind 2.18.0 → 2.19.1

package/src/formal-ai-runtime.lib.mjs

@@ -53,7 +53,7 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { promisify } from 'node:util';
 
-import { assertSupportedFormalAiVersion, FORMAL_AI_MINIMUM_VERSION, readFormalAiBinaryVersion } from './formal-ai-version.lib.mjs';
+import { assertSupportedFormalAiVersion, FORMAL_AI_MINIMUM_VERSION, isFormalAiVersionAtLeast, readFormalAiBinaryVersion } from './formal-ai-version.lib.mjs';
 
 const execFileAsync = promisify(execFile);
 
@@ -65,6 +65,26 @@ export const FORMAL_AI_MODEL_NAME = 'formal-ai';
 export const FORMAL_AI_DEFAULT_HOST = '127.0.0.1';
 export const FORMAL_AI_SERVER_READY_TIMEOUT_MS = 90_000;
 
+/** Where a Formal AI server reports its own version and memory compatibility. */
+export const FORMAL_AI_HEALTH_PATH = '/health';
+
+/**
+ * Bounded budget for the backend probe (issue #2208).
+ *
+ * Deliberately short: this runs immediately before the client executes, so a
+ * hanging endpoint must surface as a refusal rather than as a task that appears
+ * to be thinking. The server-start path has its own, much longer budget.
+ */
+export const FORMAL_AI_BACKEND_PROBE_TIMEOUT_MS = 15_000;
+
+/** Environment carrying the Hive-Mind-managed sidecar's identity into the task container (issue #2207/#2208). */
+export const FORMAL_AI_SIDECAR_PROVENANCE_ENV = Object.freeze({
+  image: 'HIVE_MIND_FORMAL_AI_SIDECAR_IMAGE',
+  imageDigest: 'HIVE_MIND_FORMAL_AI_SIDECAR_DIGEST',
+  version: 'HIVE_MIND_FORMAL_AI_SIDECAR_VERSION',
+  imageSource: 'HIVE_MIND_FORMAL_AI_SIDECAR_SOURCE',
+});
+
 export const resolveFormalAiApiKey = (env = process.env) => env.FORMAL_AI_API_KEY?.trim() || FORMAL_AI_DEFAULT_API_KEY;
 
 /**
@@ -164,6 +184,109 @@ export const waitForFormalAiServerReady = async ({ baseUrl, probePath = '/api/op
   return { ready: false, error: lastError || 'timed out' };
 };
 
+/**
+ * Ask the endpoint that will actually answer the model requests who it is
+ * (issue #2208).
+ *
+ * Until this existed, `prepareFormalAiRuntime` read `formal-ai --version` from
+ * the *local* executable and logged the answer as "the Formal AI version" even
+ * when `HIVE_MIND_FORMAL_AI_BASE_URL` pointed at a container running a
+ * completely different release. Every provenance record therefore named a binary
+ * that never saw the request.
+ *
+ * Properties that matter:
+ *
+ *  - **Bounded.** The whole probe shares one deadline, and each request carries
+ *    its own abort signal, so an endpoint that accepts the connection and then
+ *    goes quiet cannot stall the task.
+ *  - **Authenticated.** The configured key is presented the way the served API
+ *    expects it. A 401/403 is reported as an authentication problem and is *not*
+ *    retried — retrying a rejected credential only delays the failure.
+ *  - **Honest about malformed answers.** A body that is not JSON, or that
+ *    carries no version, is a distinct outcome from "unreachable"; guessing a
+ *    version here would recreate the defect this function exists to fix.
+ *
+ * @returns {Promise<{ok: boolean, kind: string, status: number|null, version: string|null, memory: object|null, health: object|null, error: string|null}>}
+ */
+export const probeFormalAiBackend = async ({ baseUrl, apiKey = null, path = FORMAL_AI_HEALTH_PATH, timeoutMs = FORMAL_AI_BACKEND_PROBE_TIMEOUT_MS, fetchImpl = globalThis.fetch, intervalMs = 500, now = () => Date.now(), sleepImpl = delay } = {}) => {
+  if (!baseUrl) return { ok: false, kind: 'unreachable', status: null, version: null, memory: null, health: null, error: 'no base URL to probe' };
+  const url = `${String(baseUrl).replace(/\/+$/, '')}${path}`;
+  const headers = apiKey ? { Authorization: `Bearer ${apiKey}`, 'X-Api-Key': apiKey } : {};
+  const deadline = now() + timeoutMs;
+  let last = { ok: false, kind: 'unreachable', status: null, version: null, memory: null, health: null, error: 'not probed' };
+
+  for (;;) {
+    const remaining = deadline - now();
+    if (remaining <= 0) break;
+    try {
+      const response = await fetchImpl(url, { headers, signal: AbortSignal.timeout(Math.min(remaining, timeoutMs)) });
+      const status = response?.status ?? null;
+      if (status === 401 || status === 403) {
+        // Not retried: the credential is wrong, and it will still be wrong in 500ms.
+        return { ok: false, kind: 'unauthorized', status, version: null, memory: null, health: null, error: `the Formal AI endpoint rejected the configured credentials (HTTP ${status})` };
+      }
+      if (!response?.ok) {
+        last = { ok: false, kind: 'http-error', status, version: null, memory: null, health: null, error: `HTTP ${status}` };
+      } else {
+        const text = await response.text();
+        let health;
+        try {
+          health = JSON.parse(text);
+        } catch {
+          return { ok: false, kind: 'malformed', status, version: null, memory: null, health: null, error: `${path} did not return JSON: ${text.slice(0, 200)}` };
+        }
+        const version = typeof health?.version === 'string' ? health.version.trim() || null : null;
+        if (!version) return { ok: false, kind: 'no-version', status, version: null, memory: health?.memory ?? null, health, error: `${path} answered without a version field` };
+        return { ok: true, kind: 'ok', status, version, memory: health?.memory ?? null, health, error: null };
+      }
+    } catch (error) {
+      last = { ok: false, kind: 'unreachable', status: null, version: null, memory: null, health: null, error: error?.message || String(error) };
+    }
+    if (deadline - now() <= intervalMs) break;
+    await sleepImpl(intervalMs);
+  }
+  return last;
+};
+
+/**
+ * Turn a probe result into either the accepted backend description or an
+ * actionable refusal.
+ *
+ * Fail-closed (issue #2146) applies here too: a Formal AI task that cannot prove
+ * which release is serving it must stop, not proceed and record a guess.
+ *
+ * @param {object} probe - Output of {@link probeFormalAiBackend}.
+ * @param {object} context
+ * @param {string} context.baseUrl
+ * @param {string} [context.minimumVersion]
+ * @param {string|null} [context.expectedVersion] - Version the leased sidecar image was verified at.
+ * @returns {{version: string, memory: object|null}}
+ */
+export const assertSupportedFormalAiBackend = (probe, { baseUrl, minimumVersion = FORMAL_AI_MINIMUM_VERSION, expectedVersion = null } = {}) => {
+  const where = `the Formal AI endpoint ${baseUrl}`;
+  if (!probe?.ok) {
+    const detail = probe?.error ? `: ${probe.error}` : '';
+    if (probe?.kind === 'unauthorized') throw new Error(`${where} refused the configured credentials${detail}. Set FORMAL_AI_API_KEY to a key the server accepts.`);
+    if (probe?.kind === 'malformed') throw new Error(`${where} answered ${FORMAL_AI_HEALTH_PATH} with something other than JSON${detail}. Hive Mind will not guess which Formal AI release is serving this task.`);
+    if (probe?.kind === 'no-version') throw new Error(`${where} answered ${FORMAL_AI_HEALTH_PATH} without a version${detail}. Hive Mind requires a serving backend that reports its version (Formal AI >= ${minimumVersion}).`);
+    if (probe?.kind === 'http-error') throw new Error(`${where} did not serve ${FORMAL_AI_HEALTH_PATH}${detail}. Check that HIVE_MIND_FORMAL_AI_BASE_URL points at a Formal AI server >= ${minimumVersion}.`);
+    throw new Error(`${where} could not be reached${detail}. Check HIVE_MIND_FORMAL_AI_BASE_URL and that the Formal AI server is running.`);
+  }
+  if (!isFormalAiVersionAtLeast(probe.version, minimumVersion)) {
+    throw new Error(`${where} serves Formal AI ${probe.version}, but Hive Mind requires >= ${minimumVersion}. Upgrade the server; the local wrapper's version does not change what answers the requests.`);
+  }
+  if (probe.memory?.compatible === false) {
+    throw new Error(`${where} reports incompatible persisted memory (migration_state=${probe.memory?.migration_state ?? 'unknown'}). Refusing to run a task against memory the serving release cannot read.`);
+  }
+  if (expectedVersion && expectedVersion !== probe.version) {
+    // A lease pins the sidecar's image for the whole task, so the endpoint
+    // answering with a different release means it is not the container Hive
+    // Mind verified and leased.
+    throw new Error(`${where} serves Formal AI ${probe.version}, but the leased Hive Mind sidecar image was verified as ${expectedVersion}. Refusing to record provenance for a backend that is not the accepted release.`);
+  }
+  return { version: probe.version, memory: probe.memory ?? null };
+};
+
 /** Read the machine-readable client registry (`formal-ai clients --format json`). */
 export const loadFormalAiClientRegistry = async ({ formalAiPath = 'formal-ai', run = execFileAsync, env = process.env, timeoutMs = 30_000 } = {}) => {
   const result = await run(formalAiPath, ['clients', '--format', 'json'], { encoding: 'utf8', env: { ...process.env, ...env }, timeout: timeoutMs, maxBuffer: 32 * 1024 * 1024 });
@@ -321,6 +444,69 @@ export const startFormalAiServer = async ({ cwd, host = FORMAL_AI_DEFAULT_HOST,
   };
 };
 
+/**
+ * The provenance Hive Mind's sidecar lifecycle publishes for the container it
+ * leased to this task (issues #2207, #2208).
+ *
+ * The lease pins one verified image for the whole task, so these values say
+ * which release *should* be answering. They are a cross-check, never a
+ * substitute for asking the endpoint itself.
+ */
+export const readFormalAiSidecarProvenance = (env = process.env) => {
+  const read = name => String(env[name] || '').trim() || null;
+  const image = read(FORMAL_AI_SIDECAR_PROVENANCE_ENV.image);
+  const imageDigest = read(FORMAL_AI_SIDECAR_PROVENANCE_ENV.imageDigest);
+  const version = read(FORMAL_AI_SIDECAR_PROVENANCE_ENV.version);
+  const imageSource = read(FORMAL_AI_SIDECAR_PROVENANCE_ENV.imageSource);
+  if (!image && !imageDigest && !version) return null;
+  return { image, imageDigest, version, imageSource };
+};
+
+/**
+ * Publish the leased sidecar's identity into a task's environment so the runtime
+ * inside the container can cross-check the endpoint it is pointed at.
+ *
+ * @param {object|null} sidecar - An `acquireFormalAiSidecar` result.
+ * @returns {object} Environment entries (empty when nothing is known).
+ */
+export const buildFormalAiSidecarProvenanceEnv = (sidecar = null) => {
+  if (!sidecar) return {};
+  const entries = {
+    [FORMAL_AI_SIDECAR_PROVENANCE_ENV.image]: sidecar.imageReference || sidecar.image || null,
+    [FORMAL_AI_SIDECAR_PROVENANCE_ENV.imageDigest]: sidecar.imageDigest || null,
+    [FORMAL_AI_SIDECAR_PROVENANCE_ENV.version]: sidecar.servingVersion || sidecar.health?.version || null,
+    [FORMAL_AI_SIDECAR_PROVENANCE_ENV.imageSource]: sidecar.imageSource || null,
+  };
+  return Object.fromEntries(Object.entries(entries).filter(([, value]) => value));
+};
+
+/** One-line description of the backend for logs and session provenance. */
+const describeFormalAiBackend = backend => [`${backend.version} at ${backend.baseUrl}`, backend.image ? `image ${backend.image}` : null, backend.imageDigest ? `digest ${backend.imageDigest}` : null].filter(Boolean).join(', ');
+
+/**
+ * Query the endpoint that will serve this task and build its provenance record.
+ *
+ * @returns {Promise<object>} `{ baseUrl, version, memory, image, imageDigest, imageSource, leased, startedLocally, probedAt }`
+ */
+const resolveFormalAiBackend = async ({ baseUrl, apiKey, env, deps, startedLocally }) => {
+  const sidecar = readFormalAiSidecarProvenance(env);
+  const probe = await (deps.probeBackendImpl || probeFormalAiBackend)({ baseUrl, apiKey, env });
+  const { version, memory } = assertSupportedFormalAiBackend(probe, { baseUrl, expectedVersion: sidecar?.version ?? null });
+  return {
+    baseUrl,
+    version,
+    memory,
+    image: sidecar?.image ?? null,
+    imageDigest: sidecar?.imageDigest ?? null,
+    imageSource: sidecar?.imageSource ?? null,
+    /** True when Hive Mind leased this endpoint from its own sidecar. */
+    leased: !!sidecar,
+    /** True when this process started the server it is now talking to. */
+    startedLocally,
+    probedAt: new Date().toISOString(),
+  };
+};
+
 const runtimeCache = new Map();
 let exitHookInstalled = false;
 
@@ -357,16 +543,32 @@ export const prepareFormalAiRuntime = async ({ tool, workdir, log = async () =>
   const resolvedFormalAiPath = formalAiPath || env.HIVE_MIND_FORMAL_AI_PATH?.trim() || 'formal-ai';
   const cacheKey = `${tool}::${workdir}::${env.HIVE_MIND_FORMAL_AI_BASE_URL || ''}`;
   const cached = runtimeCache.get(cacheKey);
-  if (cached) return cached.runtime;
+  if (cached) {
+    // Issue #2208: the cache key is the endpoint, not the release behind it. An
+    // external base URL can be re-pointed at a different container between
+    // tasks, so the cached provenance is re-checked instead of replayed.
+    const backend = await resolveFormalAiBackend({ baseUrl: cached.runtime.baseUrl, apiKey: resolveFormalAiApiKey(env), env, deps, startedLocally: cached.runtime.serverStarted });
+    if (backend.version !== cached.runtime.backend?.version || backend.imageDigest !== cached.runtime.backend?.imageDigest) {
+      await log(`🧠 Formal AI: serving backend changed to ${describeFormalAiBackend(backend)}`);
+    }
+    cached.runtime.backend = backend;
+    cached.runtime.formalAiVersion = backend.version;
+    return cached.runtime;
+  }
 
   installExitHook();
 
   // Issue #2146: `--no-tool-check` skipped the only version probe, allowing an
   // old Formal AI build to return the same unexecuted plan through all five
   // Claude/Codex restarts. Runtime safety cannot depend on preflight options.
-  const formalAiVersion = await (deps.readVersionImpl || readFormalAiBinaryVersion)({ formalAiPath: resolvedFormalAiPath, env });
-  assertSupportedFormalAiVersion(formalAiVersion);
-  await log(`🧠 Formal AI: version ${formalAiVersion} (minimum ${FORMAL_AI_MINIMUM_VERSION})`);
+  //
+  // This is the *local wrapper*: the executable that starts the server and
+  // writes the client configuration. Issue #2208: it is not necessarily the
+  // release that answers the model requests, so it keeps its own name and its
+  // own compatibility check, and it is never reported as the serving version.
+  const formalAiWrapperVersion = await (deps.readVersionImpl || readFormalAiBinaryVersion)({ formalAiPath: resolvedFormalAiPath, env });
+  assertSupportedFormalAiVersion(formalAiWrapperVersion);
+  await log(`🧠 Formal AI: local wrapper version ${formalAiWrapperVersion} (minimum ${FORMAL_AI_MINIMUM_VERSION})`);
 
   const apiKey = resolveFormalAiApiKey(env);
   const externalBaseUrl = env.HIVE_MIND_FORMAL_AI_BASE_URL?.trim() || null;
@@ -386,6 +588,13 @@ export const prepareFormalAiRuntime = async ({ tool, workdir, log = async () =>
       await log(`🧠 Formal AI: using the configured server ${baseUrl}`, { verbose: true });
     }
 
+    // Before any client configuration is written, ask the endpoint who it is.
+    const backend = await resolveFormalAiBackend({ baseUrl, apiKey, env, deps, startedLocally: !!server });
+    await log(`🧠 Formal AI: serving backend ${describeFormalAiBackend(backend)}`);
+    if (backend.version !== formalAiWrapperVersion) {
+      await log(`🧠 Formal AI: local wrapper ${formalAiWrapperVersion} differs from the serving backend ${backend.version}; provenance records the backend`, { verbose: true });
+    }
+
     const clients = await (deps.loadRegistryImpl || loadFormalAiClientRegistry)({ formalAiPath: resolvedFormalAiPath, env });
     const client = findFormalAiClient(clients, tool);
     if (!client) throw new Error(`Formal AI does not list a client configuration for "${tool}"`);
@@ -429,7 +638,11 @@ export const prepareFormalAiRuntime = async ({ tool, workdir, log = async () =>
       client,
       notes,
       serverStarted: !!server,
-      formalAiVersion,
+      /** The release that actually answers this task's model requests. */
+      formalAiVersion: backend.version,
+      /** The local executable that started the server and wrote the config. */
+      formalAiWrapperVersion,
+      backend,
       stop: async () => {
         runtimeCache.delete(cacheKey);
         await server?.stop?.();

package/src/formal-ai-sidecar.lib.mjs

@@ -46,7 +46,7 @@ import fs from 'node:fs';
 import { promisify } from 'node:util';
 
 import { FORMAL_AI_MINIMUM_VERSION, isFormalAiVersionAtLeast } from './formal-ai-version.lib.mjs';
-import { ensureFormalAiSidecarImage, resolveFormalAiSidecarImage } from './formal-ai-image.lib.mjs';
+import { ensureFormalAiSidecarImage, readAcceptedFormalAiImage, resolveFormalAiSidecarImage } from './formal-ai-image.lib.mjs';
 import { isFormalAiModel } from './formal-ai-model.lib.mjs';
 import { getModelFromArgs } from './model-args.lib.mjs';
 import { withStateLock } from './state-lock.lib.mjs';
@@ -90,7 +90,7 @@ export const FORMAL_AI_MEMORY_PATH = `${FORMAL_AI_MEMORY_MOUNT}/memory.lino`;
  * issue #2154 taught us that "which image" and "is it actually pullable" are the
  * same question.
  */
-export { FORMAL_AI_IMAGE_REPOSITORY, resolveFormalAiSidecarImage, resolveFormalAiSidecarImageCandidates } from './formal-ai-image.lib.mjs';
+export { FORMAL_AI_IMAGE_REPOSITORY, readAcceptedFormalAiImage, resolveAcceptedFormalAiImageCandidates, resolveFormalAiSidecarImage, resolveFormalAiSidecarImageCandidates } from './formal-ai-image.lib.mjs';
 
 /** Applied to the sidecar, its network and its volume so reconciliation can find them. */
 export const FORMAL_AI_SIDECAR_LABEL = 'com.link-assistant.hive-mind.formal-ai';
@@ -102,7 +102,13 @@ const SIDECAR_LOCK_NAME = 'formal-ai-sidecar';
 const DEFAULT_HEALTH_ATTEMPTS = 60;
 const DEFAULT_HEALTH_DELAY_MS = 1000;
 
-const EMPTY_STATE = Object.freeze({ version: 1, image: null, imageDigest: null, startedAt: null, leases: [], lastUpdate: null });
+/**
+ * `lastUpdate` is the accepted-release record (issue #2207) and `serving` is the
+ * provenance of the container that last answered a lease (issue #2208). Neither
+ * is derivable from `image`/`imageDigest`, which are only a cache of whatever is
+ * running right now.
+ */
+const EMPTY_STATE = Object.freeze({ version: 1, image: null, imageReference: null, imageDigest: null, startedAt: null, leases: [], lastUpdate: null, serving: null });
 
 /**
  * True when a task will be driven by Formal AI.
@@ -350,14 +356,21 @@ export const acquireFormalAiSidecar = async ({ sessionId, tool = null, model = n
       // #2154 the reference went straight into `docker run`, so a registry that
       // refused the pull surfaced as an unreadable `Command failed: docker run …`
       // dump and the task died even though a usable image sat on the host.
-      const resolved = container.exists && container.image ? { image: container.image, source: 'running-sidecar', pulled: false } : await ensureFormalAiSidecarImage({ env, run, timeoutMs: imageTimeoutMs, log, verbose });
+      //
+      // `accepted` is what issue #2207 was missing: without it the candidate
+      // list was rebuilt from the bootstrap pin on every cold start, so an
+      // update that had already been pulled, migrated and verified was silently
+      // discarded by the very next task.
+      const accepted = readAcceptedFormalAiImage(state);
+      const resolved = container.exists && container.image ? { image: container.image, reference: container.image, source: 'running-sidecar', pulled: false } : await ensureFormalAiSidecarImage({ env, accepted, run, timeoutMs: imageTimeoutMs, log, verbose });
       const image = resolved.image;
+      const imageReference = resolved.reference || image;
 
       await ensureFormalAiNetwork({ run, timeoutMs, log, verbose });
       await ensureFormalAiMemoryVolume({ image, run, timeoutMs, log, verbose });
 
       if (!container.exists) {
-        if (log) await log(`🧠 Starting the Formal AI sidecar (${image}, ${resolved.source}) on the internal network '${FORMAL_AI_SIDECAR_NETWORK_NAME}'`);
+        if (log) await log(`🧠 Starting the Formal AI sidecar (${imageReference}${imageReference === image ? '' : ` @ ${image}`}, ${resolved.source}) on the internal network '${FORMAL_AI_SIDECAR_NETWORK_NAME}'`);
         await dockerText(run, buildFormalAiSidecarRunArgs({ image, env }), { timeoutMs });
         container = await inspectDockerContainer(FORMAL_AI_SIDECAR_CONTAINER_NAME, { run, timeoutMs });
       }
@@ -375,15 +388,27 @@ export const acquireFormalAiSidecar = async ({ sessionId, tool = null, model = n
       // and then fail on the agent-mode API the tasks depend on.
       const reportedVersion = health.health?.version ?? null;
       if (reportedVersion && !isFormalAiVersionAtLeast(reportedVersion, FORMAL_AI_MINIMUM_VERSION)) {
-        throw new Error(`Formal AI sidecar image ${image} (${resolved.source}) runs formal-ai ${reportedVersion}, but Hive Mind requires >= ${FORMAL_AI_MINIMUM_VERSION}. Rebuild or repin the image (HIVE_MIND_FORMAL_AI_IMAGE) before running Formal AI tasks.`);
+        throw new Error(`Formal AI sidecar image ${imageReference} (${resolved.source}) runs formal-ai ${reportedVersion}, but Hive Mind requires >= ${FORMAL_AI_MINIMUM_VERSION}. Rebuild or repin the image (HIVE_MIND_FORMAL_AI_IMAGE) before running Formal AI tasks.`);
       }
 
       const address = await readFormalAiSidecarAddress({ run, timeoutMs });
       const acquiredAt = now().toISOString();
       const nextLeases = [...leases.filter(lease => lease.sessionId !== sessionId), { sessionId, tool, model, acquiredAt }];
-      writeFormalAiSidecarState({ ...state, image: container.image || image, imageDigest: container.imageDigest, startedAt: state.startedAt || acquiredAt, leases: nextLeases }, { env, fsImpl });
+      // The provenance of what is *actually serving* this lease, so a task's
+      // evidence can name the release that answered its requests rather than
+      // whatever binary happens to sit next to the wrapper (issue #2208).
+      const serving = {
+        image: imageReference,
+        imageDigest: container.imageDigest ?? resolved.digest ?? null,
+        imageSource: resolved.source,
+        version: reportedVersion,
+        memorySchemaVersion: health.health?.memory?.schema_version ?? null,
+        acceptedAt: accepted?.updatedAt ?? null,
+        observedAt: acquiredAt,
+      };
+      writeFormalAiSidecarState({ ...state, image: container.image || image, imageReference, imageDigest: container.imageDigest, startedAt: state.startedAt || acquiredAt, leases: nextLeases, serving }, { env, fsImpl });
 
-      if (verbose && log) await log(`[VERBOSE] formal-ai-sidecar: lease '${sessionId}' acquired (${nextLeases.length} active), image=${container.image || image} (${resolved.source}), digest=${container.imageDigest ?? 'unknown'}, address=${address ?? 'unknown'}, formal-ai=${health.health?.version ?? 'unknown'}, memory schema=${health.health?.memory?.schema_version ?? 'unknown'}`);
+      if (verbose && log) await log(`[VERBOSE] formal-ai-sidecar: lease '${sessionId}' acquired (${nextLeases.length} active), image=${imageReference} (${resolved.source}), digest=${container.imageDigest ?? 'unknown'}, address=${address ?? 'unknown'}, formal-ai=${reportedVersion ?? 'unknown'}, memory schema=${serving.memorySchemaVersion ?? 'unknown'}`);
 
       return {
         address,
@@ -394,8 +419,14 @@ export const acquireFormalAiSidecar = async ({ sessionId, tool = null, model = n
         containerName: FORMAL_AI_SIDECAR_CONTAINER_NAME,
         memoryVolume: FORMAL_AI_MEMORY_VOLUME_NAME,
         image: container.image || image,
+        imageReference,
         imageSource: resolved.source,
-        imageDigest: container.imageDigest,
+        imageDigest: serving.imageDigest,
+        acceptedImage: accepted?.image ?? null,
+        acceptedDigest: accepted?.digest ?? null,
+        acceptedVersion: accepted?.version ?? null,
+        servingVersion: reportedVersion,
+        memorySchemaVersion: serving.memorySchemaVersion,
         health: health.health,
         leaseCount: nextLeases.length,
       };
@@ -453,6 +484,7 @@ export default {
   inspectDockerContainer,
   isFormalAiSidecarEnabled,
   isFormalAiTask,
+  readAcceptedFormalAiImage,
   readDockerImageDigest,
   readFormalAiSidecarAddress,
   readFormalAiSidecarState,

package/src/formal-ai.lib.mjs

@@ -92,6 +92,11 @@ export const resolveFormalAiToolExecution = async ({ tool, model, toolPath, work
     env: runtime.env,
     home: runtime.home,
     client: runtime.client,
+    // Issue #2208: provenance names the backend that answered, and the local
+    // wrapper under its own name — the two are not interchangeable.
+    backend: runtime.backend,
+    formalAiVersion: runtime.formalAiVersion,
+    formalAiWrapperVersion: runtime.formalAiWrapperVersion,
     stop: runtime.stop,
   };
 };

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/isolation-runner.lib.mjs

@@ -19,7 +19,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { isExecutingSessionStatus, isTerminalSessionStatus } from './session-status.lib.mjs';
-import { acquireFormalAiSidecarForTask, attachFormalAiTaskContainer, releaseFormalAiSidecarForTask } from './formal-ai-isolation.lib.mjs';
+import { acquireFormalAiSidecarForTask, attachFormalAiTaskContainer, buildFormalAiTaskEnv, releaseFormalAiSidecarForTask } from './formal-ai-isolation.lib.mjs';
 // The image references live in their own module so the Formal AI sidecar can
 // resolve the locally present Hive Mind image (which bakes `formal-ai`) without
 // importing this runner and creating a cycle. Re-exported here because callers
@@ -399,7 +399,7 @@ export async function executeWithIsolation(command, args, options = {}) {
     await releaseFormalAiSidecarForTask({ sidecar, sessionId, env: hostEnv, verbose });
     return failLaunch(formalAiRoutingError);
   }
-  const taskEnv = sidecar ? { ...hostEnv, HIVE_MIND_FORMAL_AI_BASE_URL: sidecar.baseUrl } : hostEnv;
+  const taskEnv = buildFormalAiTaskEnv({ sidecar, env: hostEnv });
   const effectiveOptions =
     backend === 'docker'
       ? {

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