@link-assistant/hive-mind 2.18.0 → 2.19.1

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @link-assistant/hive-mind
 
+## 2.19.1
+
+### Patch Changes
+
+- 6cdf9e2: Keep the Formal AI release a verified update accepted, and record the backend that actually served each task rather than the local wrapper (issues #2207, #2208, delivered together for #2209).
+
+  Two defects sat on either side of the same handoff, and each one hid the other. The updater verified a new Formal AI image against the persisted memory volume, accepted it, and wrote it into `formal-ai-sidecar.json` — and then the next cold task threw it away, because `acquireFormalAiSidecar` resolved its image from the environment alone and re-selected the bootstrap release. Meanwhile the task's provenance reported `formal-ai --version` from the local wrapper, a binary that answers no requests, so the log could not have revealed the downgrade even when it happened.
+
+  - **The accepted image is what the next task boots.** `readAcceptedFormalAiImage` reads the acceptance back out of state and acquire passes it into image resolution. Precedence is an operator pin (exact and exclusive), then the accepted image (also exclusive), then the published bootstrap image only when nothing has been accepted yet, then the local Hive Mind image. The accepted candidates lead with the **immutable digest** and fall back to the tag only with `expectDigest` attached, so a tag that moved after acceptance is refused instead of booted — which is not hypothetical: `ghcr.io/link-assistant/formal-ai:latest` pointed at 0.346.0 when this was reported and points at 0.347.0 now. An accepted image that is no longer on the host is a refusal with the pin named in the message, never a silent downgrade onto memory that has already been migrated.
+  - **The serving backend is asked, not assumed.** `probeFormalAiBackend` queries `/health` on the configured endpoint before any client runs, within a bounded deadline, presenting the configured API key and returning immediately on 401/403 instead of retrying a credential that will still be wrong. `assertSupportedFormalAiBackend` gives each answer its own refusal — unreachable, unauthorized, non-JSON, JSON without a version, below `FORMAL_AI_MINIMUM_VERSION`, incompatible persisted memory — and never guesses a version.
+  - **The two versions have two names.** `runtime.formalAiVersion` is the release that answers the requests and is what the logs and provenance report; `runtime.formalAiWrapperVersion` is the local executable that started the server and wrote the config, keeping its own floor check and its own log line. `validateFormalAiToolConnection` is unchanged.
+  - **The halves are joined.** When Hive Mind manages the sidecar, the leased image, digest, source and verified version are published into the task environment, read back by the runtime, and required to agree with what `/health` reports; an endpoint serving something other than the accepted release is refused rather than recorded. The runtime cache is keyed by endpoint, not by the release behind it, so a cache hit re-probes and says so when the backend changed underneath a reused URL.
+
+  Three regression suites cover it: `tests/test-issue-2207-accepted-image-persistence.mjs` (candidate selection, update → stopped sidecar → acquire → release → acquire including a process restart against persisted state, a moved tag, a rollback, a pruned accepted image, an operator pin with a busy lease), `tests/test-issue-2208-serving-backend-provenance.mjs` (ten cases against real loopback HTTP backends), and `tests/test-issue-2209-verified-release-serving-provenance.mjs`, which runs the Docker simulator and a real serving process together so neither half can look correct while the pair fails. The same transition was then run against a real Docker daemon and the real published images; the evidence is in `docs/case-studies/issue-2209/`.
+
+## 2.19.0
+
+### Minor Changes
+
+- ac07514: Stop the model list from ageing with the release: add the models that shipped since 2.17.0, hot-load the live catalogue from every source that costs nothing to read, expose it as `/models` and `hive-models`, teach `--use-router` both of the router's route dialects, and check the agentic CLI for a newer version before a task starts (issue #2202).
+
+  A provider can ship a model on a Tuesday, and until now Hive Mind could not name it until the next release: `src/models/index.mjs` was a static table and `--model` validated against nothing else. Six changes close that gap, none of which can spend a token or fail a run.
+
+  - **The new models are in the bundled table.** Fable 5.1, Mythos 5.1, GPT-6 Astra and GPT-5.6 Cyber, with their aliases, context windows and fallback chains. The additions pushed `src/models/index.mjs` past the 1350-line early warning of `scripts/check-file-line-limits.sh`, so the catalogue itself moved to `src/models/catalog.mjs` and is re-exported — the public surface is unchanged.
+  - **The catalogue hot-loads.** `src/model-catalogue.lib.mjs` merges six sources in a fixed precedence: the Link.Assistant Router's live catalogue, `codex debug models`, Anthropic's and OpenAI's `GET /v1/models`, models.dev for specifications, and the bundled table as the offline floor. models.dev only annotates; it never adds a model to the available list. Answers are cached per source and per tool for at least an hour, and `HIVE_MIND_MODEL_CATALOGUE_TTL_MINUTES` can only raise that floor.
+  - **Listing models cannot cost a token, structurally.** `assertTokenFreeSource` rejects any source that has not explicitly declared `billable: false`, so a source cannot become billable by omission, and `assertTokenFreeUrl` rejects any URL whose path is a completion endpoint no matter which descriptor carried it — a typo turning `/v1/models` into `/v1/messages` throws instead of spending. The four extraction methods that were considered and rejected, including driving either CLI's `/model` picker through its TUI, are recorded with their reasons so a future contributor does not re-derive them.
+  - **`/models` and `hive-models` show the whole spectrum.** Models are grouped as bundled-and-live, hot-loaded (a live source has it, this installation does not ship it), and bundled-only (shipped, unconfirmed), with `--tool`, `--details`, `--refresh`, `--json`, and `--all`. A footer names every source actually consulted, its outcome, and the age of the cache, so "why don't I see X" is answerable from the output — and a source that failed is described from its stderr, never by quoting the command line, so the router's leased token cannot ride a failure message into the footer. In Telegram the same flags are accepted the way a chat writes them: `/models codex`, `/models --tool codex` and `/models --tool=codex` are one command.
+  - **`--use-router` speaks both route dialects.** Router 1.0 removed every root, `/v1/*` and overlapping `/api/*` alias and moved each service under `/api/services/<service>/…` — measured, not assumed: on `1.2.0` every path that answers on `0.119.0` is a 404 and vice versa. `src/router-routes.lib.mjs` derives every base URL, the health probe and the catalogue path from the pinned image, so the pin can move in one line. It stays on `0.x` today, at `0.125.4`, because router `1.x` has no `gh`-reachable REST base and `gh` exposes no path-prefix option; the trade is reported by `describeRouterCoverageGaps` rather than discovered at runtime, and the upstream issues are filed.
+  - **A stale CLI is refreshed before the run needs it.** `/solve`, `/hive`, `/task`, `/fix`, `/models` and `hive-models` check the agentic CLI they are about to drive, because an outdated binary is the usual reason a brand-new model name is rejected. The check is throttled to once every six hours, narrowed to the one CLI in play, deferred entirely while other tasks are running, skipped for `--dry-run` and `--only-prepare-command`, and never fatal. Each run excludes its own task from the idle gate — otherwise a `/solve` asking for an update would find itself in the process table and defer forever. Opt out with `--no-tool-update` or `HIVE_MIND_AGENTIC_CLI_AUTO_UPDATE=0`.
+
+  Documentation is in `docs/MODELS.md` and its `zh`/`hi`/`ru` siblings; the full analysis — the requirement-by-requirement plan, the router route measurement, and what shipped differently from the plan — is in `docs/case-studies/issue-2202/`.
+
 ## 2.18.0
 
 ### Minor Changes

package/README.hi.md

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

package/README.md

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

package/README.ru.md

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

package/README.zh.md

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

package/package.json

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

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

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

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

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

package/src/docker-sidecar.lib.mjs

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

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

@@ -35,15 +35,20 @@
  * - `HIVE_MIND_FORMAL_AI_IMAGE` is an **exact** operator pin: it is the only
  *   candidate, and if it cannot be resolved the acquire fails. An operator who
  *   names an image means that image.
- * - Otherwise the published image is preferred, and the local Hive Mind image is
- *   the fallback. The fallback is only *used*; it is never pulled, because its
- *   whole point is that it is already on the host.
+ * - Otherwise the image accepted by the last verified idle update wins, by its
+ *   immutable digest (issue #2207). Before that rule the bootstrap version was
+ *   re-selected on every cold start, so an accepted update was discarded by the
+ *   next task and the sidecar returned to the release Hive Mind ships with.
+ * - Otherwise the published bootstrap image is preferred, and the local Hive
+ *   Mind image is the fallback. The fallback is only *used*; it is never pulled,
+ *   because its whole point is that it is already on the host.
  * - Nothing here downgrades a Formal AI task to another model. Issue #2146's
  *   fail-closed rule still holds: when no candidate resolves, the task is
  *   refused with an actionable message.
  *
  * @see https://github.com/link-assistant/hive-mind/issues/2154
  * @see https://github.com/link-assistant/hive-mind/issues/2146
+ * @see https://github.com/link-assistant/hive-mind/issues/2207
  */
 
 import { execFile } from 'node:child_process';
@@ -62,6 +67,7 @@ const DEFAULT_DOCKER_TIMEOUT_MS = 600_000;
 /** Where each candidate came from, so logs and errors can explain themselves. */
 export const FORMAL_AI_IMAGE_SOURCES = Object.freeze({
   PINNED: 'operator-pin',
+  ACCEPTED: 'accepted-update',
   PUBLISHED: 'published-image',
   HIVE_MIND: 'hive-mind-image',
 });
@@ -114,15 +120,82 @@ export const classifyDockerRegistryError = message => {
  */
 export const resolveFormalAiFallbackImage = (env = process.env) => String(env.HIVE_MIND_FORMAL_AI_FALLBACK_IMAGE || '').trim() || getDockerIsolationImage({ env });
 
+/**
+ * The last image an idle update actually accepted, read out of the durable
+ * sidecar record (issue #2207).
+ *
+ * `state.image`/`state.imageDigest` are a *cache of what is running* — every
+ * acquire overwrites them with the container it found — so they cannot answer
+ * "which image did we verify?". `state.lastUpdate` can: it is written only by
+ * `updateFormalAiSidecarWhenIdle` after the pull, the side-effect-free memory
+ * preflight, the backed-up migration and the `/health` memory-compatibility
+ * check have all succeeded, and it is left untouched by a rollback.
+ *
+ * @param {object|null} state - A `formal-ai-sidecar.json` record.
+ * @returns {{image: string|null, digest: string|null, version: string|null, memorySchemaVersion: (number|string|null), updatedAt: string|null}|null}
+ */
+export const readAcceptedFormalAiImage = state => {
+  const update = state?.lastUpdate;
+  if (!update || typeof update !== 'object') return null;
+  const image = String(update.image || '').trim() || null;
+  const digest = String(update.digest || '').trim() || null;
+  if (!image && !digest) return null;
+  return { image, digest, version: update.version ?? null, memorySchemaVersion: update.memorySchemaVersion ?? null, updatedAt: update.updatedAt ?? null };
+};
+
+/**
+ * Candidates that reproduce an accepted update, most trustworthy first.
+ *
+ * Two rules make this safe:
+ *
+ *  - **The digest wins.** `docker image inspect --format {{.Id}}` returns the
+ *    local content address, which Docker also accepts as a run reference. Using
+ *    it means a tag that moved after acceptance (`:latest` is the update tag)
+ *    cannot smuggle an unverified image past the memory verification that
+ *    earned the acceptance.
+ *  - **The tag is only a recovery path.** If the accepted image ID has been
+ *    pruned, the recorded reference may be pulled again, but the result is
+ *    accepted only when its digest still matches; otherwise the candidate is
+ *    refused rather than booted.
+ *
+ * @param {object|null} accepted - Output of {@link readAcceptedFormalAiImage}.
+ * @returns {Array<object>}
+ */
+export const resolveAcceptedFormalAiImageCandidates = (accepted = null) => {
+  if (!accepted) return [];
+  const candidates = [];
+  if (accepted.digest) candidates.push({ image: accepted.digest, reference: accepted.image || accepted.digest, source: FORMAL_AI_IMAGE_SOURCES.ACCEPTED, pullable: false, accepted: true });
+  if (accepted.image && accepted.digest) candidates.push({ image: accepted.image, reference: accepted.image, source: FORMAL_AI_IMAGE_SOURCES.ACCEPTED, pullable: true, accepted: true, expectDigest: accepted.digest });
+  // An acceptance recorded before digests were captured: the reference is all
+  // there is, so it may be used but never re-pulled behind a moving tag.
+  if (accepted.image && !accepted.digest) candidates.push({ image: accepted.image, reference: accepted.image, source: FORMAL_AI_IMAGE_SOURCES.ACCEPTED, pullable: false, accepted: true });
+  return candidates;
+};
+
 /**
  * Ordered list of images to try, most preferred first.
  *
+ * Precedence, and why:
+ *
+ *  1. `HIVE_MIND_FORMAL_AI_IMAGE` — an operator who names an image means that
+ *     image; the pin is exact and exclusive.
+ *  2. The last accepted, verified update (issue #2207). Also exclusive: once an
+ *     image has been verified against the migrated persisted memory, quietly
+ *     booting the older bootstrap release against that memory is exactly the
+ *     silent downgrade the fail-closed rule forbids.
+ *  3. The bootstrap release, then the local Hive Mind image — the cold-start
+ *     path for a host that has never completed an update.
+ *
  * @param {object} [env]
+ * @param {object} [options]
+ * @param {object|null} [options.accepted] - Output of {@link readAcceptedFormalAiImage}.
  * @returns {Array<{image: string, source: string, pullable: boolean}>}
  */
-export const resolveFormalAiSidecarImageCandidates = (env = process.env) => {
+export const resolveFormalAiSidecarImageCandidates = (env = process.env, { accepted = null } = {}) => {
   const pinned = String(env.HIVE_MIND_FORMAL_AI_IMAGE || '').trim();
   if (pinned) return [{ image: pinned, source: FORMAL_AI_IMAGE_SOURCES.PINNED, pullable: true }];
+  const acceptedCandidates = resolveAcceptedFormalAiImageCandidates(accepted);
+  if (acceptedCandidates.length > 0) return acceptedCandidates;
   const candidates = [{ image: `${FORMAL_AI_IMAGE_REPOSITORY}:${FORMAL_AI_BOOTSTRAP_VERSION}`, source: FORMAL_AI_IMAGE_SOURCES.PUBLISHED, pullable: true }];
   const fallback = resolveFormalAiFallbackImage(env);
   // Never pulled: the fallback's value is that it is already on the host. A
@@ -132,7 +205,7 @@ export const resolveFormalAiSidecarImageCandidates = (env = process.env) => {
 };
 
 /** The preferred image, kept for callers and logs that only need the headline reference. */
-export const resolveFormalAiSidecarImage = (env = process.env) => resolveFormalAiSidecarImageCandidates(env)[0].image;
+export const resolveFormalAiSidecarImage = (env = process.env, options = {}) => resolveFormalAiSidecarImageCandidates(env, options)[0].image;
 
 const inspectLocalImage = async (image, { run, timeoutMs }) => {
   try {
@@ -148,7 +221,8 @@ const inspectLocalImage = async (image, { run, timeoutMs }) => {
  * bot log knows the cause and the fix without opening a shell.
  */
 const describeFailure = attempts => {
-  const lines = ['No Formal AI image could be resolved, so the sidecar was not started.'];
+  const accepted = attempts.some(attempt => attempt.source === FORMAL_AI_IMAGE_SOURCES.ACCEPTED);
+  const lines = [accepted ? 'The Formal AI image accepted by the last verified update could not be resolved, so the sidecar was not started.' : 'No Formal AI image could be resolved, so the sidecar was not started.'];
   for (const attempt of attempts) {
     if (attempt.source === FORMAL_AI_IMAGE_SOURCES.HIVE_MIND && attempt.kind === 'absent') {
       lines.push(`• ${attempt.image} (local Hive Mind image, fallback): not present on this host — Docker-isolated tasks would have to pull it too.`);
@@ -157,6 +231,13 @@ const describeFailure = attempts => {
     lines.push(`• ${attempt.image} (${attempt.source}): ${attempt.reason}${attempt.error ? ` — ${attempt.error}` : ''}`);
     for (const step of attempt.remediation ?? []) lines.push(`    → ${step}`);
   }
+  if (accepted) {
+    // Falling back to the bootstrap release here would run an *older* binary
+    // against memory that the accepted release already migrated (issue #2207).
+    lines.push('Hive Mind will not fall back to an older Formal AI release against memory an accepted update already migrated.');
+    lines.push('    → restore the accepted image on this host (`docker pull` it, or copy it back), or');
+    lines.push('    → set HIVE_MIND_FORMAL_AI_IMAGE to the image you want this host to run, which overrides the accepted update.');
+  }
   lines.push('Formal AI tasks fail closed by design (issue #2146): Hive Mind will not silently run them on another model.');
   return lines.join('\n');
 };
@@ -172,17 +253,27 @@ const describeFailure = attempts => {
  * @param {Function|null} [params.log]
  * @param {boolean} [params.verbose]
  * @param {boolean} [params.pull] - Set false to accept only images already on the host.
- * @returns {Promise<{image: string, source: string, digest: string|null, pulled: boolean, attempts: object[]}>}
+ * @param {object|null} [params.accepted] - Output of {@link readAcceptedFormalAiImage}, used to build the default candidates.
+ * @returns {Promise<{image: string, reference: string, source: string, digest: string|null, pulled: boolean, attempts: object[]}>}
  * @throws {Error} When no candidate resolves; the message names every attempt and its fix.
  */
-export const ensureFormalAiSidecarImage = async ({ env = process.env, run = execFileAsync, timeoutMs = DEFAULT_DOCKER_TIMEOUT_MS, log = null, verbose = false, pull = true, candidates = resolveFormalAiSidecarImageCandidates(env) } = {}) => {
+export const ensureFormalAiSidecarImage = async ({ env = process.env, run = execFileAsync, timeoutMs = DEFAULT_DOCKER_TIMEOUT_MS, log = null, verbose = false, pull = true, accepted = null, candidates = resolveFormalAiSidecarImageCandidates(env, { accepted }) } = {}) => {
   const attempts = [];
+  const reference = candidate => candidate.reference || candidate.image;
+  // A candidate that names an expected digest is a *recovery* path for an
+  // accepted update whose image ID was pruned: the reference may be re-fetched,
+  // but only the recorded content address is allowed to run (issue #2207).
+  const mismatch = (candidate, digest) => ({ ...candidate, kind: 'digest-mismatch', reason: `resolved to ${digest ?? 'no digest'} instead of the accepted ${candidate.expectDigest}`, error: null, remediation: ['the tag moved after the update was accepted; restore the accepted image or repin with HIVE_MIND_FORMAL_AI_IMAGE'] });
 
   for (const candidate of candidates) {
     const localDigest = await inspectLocalImage(candidate.image, { run, timeoutMs });
+    if (localDigest && candidate.expectDigest && localDigest !== candidate.expectDigest) {
+      attempts.push(mismatch(candidate, localDigest));
+      continue;
+    }
     if (localDigest) {
       if (verbose && log) await log(`[VERBOSE] formal-ai-image: using '${candidate.image}' (${candidate.source}) already present locally, digest=${localDigest}`);
-      return { image: candidate.image, source: candidate.source, digest: localDigest, pulled: false, attempts };
+      return { image: candidate.image, reference: reference(candidate), source: candidate.source, digest: localDigest, pulled: false, attempts };
     }
 
     if (!candidate.pullable || !pull) {
@@ -202,8 +293,13 @@ export const ensureFormalAiSidecarImage = async ({ env = process.env, run = exec
     }
 
     const digest = await inspectLocalImage(candidate.image, { run, timeoutMs });
+    if (candidate.expectDigest && digest !== candidate.expectDigest) {
+      attempts.push(mismatch(candidate, digest));
+      if (log) await log(`⚠️ ${candidate.image} no longer resolves to the accepted digest ${candidate.expectDigest}; refusing to boot it.`);
+      continue;
+    }
     if (verbose && log) await log(`[VERBOSE] formal-ai-image: pulled '${candidate.image}' (${candidate.source}), digest=${digest ?? 'unknown'}`);
-    return { image: candidate.image, source: candidate.source, digest, pulled: true, attempts };
+    return { image: candidate.image, reference: reference(candidate), source: candidate.source, digest, pulled: true, attempts };
   }
 
   const error = new Error(describeFailure(attempts));
@@ -216,6 +312,8 @@ export default {
   FORMAL_AI_IMAGE_SOURCES,
   classifyDockerRegistryError,
   ensureFormalAiSidecarImage,
+  readAcceptedFormalAiImage,
+  resolveAcceptedFormalAiImageCandidates,
   resolveFormalAiFallbackImage,
   resolveFormalAiSidecarImage,
   resolveFormalAiSidecarImageCandidates,

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

@@ -16,6 +16,7 @@
  * @see https://github.com/link-assistant/hive-mind/issues/2146
  */
 
+import { buildFormalAiSidecarProvenanceEnv } from './formal-ai-runtime.lib.mjs';
 import { acquireFormalAiSidecar, attachTaskToFormalAiNetwork, isFormalAiSidecarEnabled, isFormalAiTask, releaseFormalAiSidecar } from './formal-ai-sidecar.lib.mjs';
 
 const logToConsole = message => console.log(message);
@@ -43,6 +44,19 @@ export const acquireFormalAiSidecarForTask = async ({ backend, args = [], model
   }
 };
 
+/**
+ * The environment a Formal AI task is launched with.
+ *
+ * Besides the endpoint, this carries the identity of the image the lease pinned
+ * (issue #2208). The runtime inside the container still asks the endpoint which
+ * release is answering; these values let it refuse when the answer is not the
+ * accepted image Hive Mind leased, and let the task record the digest rather
+ * than a mutable tag.
+ *
+ * @returns {object} The task environment (`env` itself when Formal AI is not involved).
+ */
+export const buildFormalAiTaskEnv = ({ sidecar, env = process.env } = {}) => (sidecar ? { ...env, HIVE_MIND_FORMAL_AI_BASE_URL: sidecar.baseUrl, ...buildFormalAiSidecarProvenanceEnv(sidecar) } : env);
+
 /**
  * Add the internal Formal AI network to the freshly-created task container.
  *
@@ -66,4 +80,4 @@ export const releaseFormalAiSidecarForTask = async ({ sidecar, sessionId, env =
   }
 };
 
-export default { acquireFormalAiSidecarForTask, attachFormalAiTaskContainer, releaseFormalAiSidecarForTask };
+export default { acquireFormalAiSidecarForTask, attachFormalAiTaskContainer, buildFormalAiTaskEnv, releaseFormalAiSidecarForTask };