@link-assistant/hive-mind 2.11.13 → 2.12.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @link-assistant/hive-mind
 
+## 2.12.1
+
+### Patch Changes
+
+- d606c77: Restore Node 24 command execution, make runtime-loaded dependencies reproducible,
+  and strengthen CI status, security, warning, and smoke-test enforcement.
+- 098b01a: Report auto-resumed limit-reset sessions with their start marker, summary, and execution log.
+
+## 2.12.0
+
+### Minor Changes
+
+- 93c54bd: Make Formal AI the only model a Formal AI task can reach, and run it on demand. Formal AI Agent flags stay separate argv values, a Formal AI task refuses to start on an Agent CLI older than 0.25.8 (earlier releases answer with their default model when they cannot parse `--model`), the supported Formal AI runtime is pinned and enforced, Agent provider drift fails closed, and structured Formal AI output is preserved in GitHub comments.
+
+  Formal AI now runs as an on-demand sidecar: it starts for the first Formal AI task, is reachable only over an internal Docker network, stops after the last lease is released, and keeps its memory volume across restarts. While idle, the sidecar image is refreshed through the Formal AI persisted-memory upgrade contract (preflight, backup, receipt, health check, rollback), and the installed agentic CLIs are refreshed too.
+
+  The distributed images bootstrap Formal AI 0.339.1 and pin start-command 0.32.1. The Docker builder stages install `pkg-config` and the OpenSSL headers and link OpenSSL statically as defense in depth: Formal AI 0.333.0–0.338.0 reached OpenSSL through `web-capture` and failed to build without them; 0.339.0 removed the dependency, but the root causes remain open upstream.
+
 ## 2.11.13
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "2.11.13",
+  "version": "2.12.1",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",
@@ -88,5 +88,8 @@
     "*.{js,mjs,json,md}": [
       "prettier --write"
     ]
+  },
+  "allowScripts": {
+    "@sentry/node-cpu-profiler@2.4.2": true
   }
 }

package/src/agent-command.lib.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+/**
+ * Pure Agent command/event policy helpers.
+ *
+ * Keeping argv construction out of agent.lib.mjs makes it possible to test the
+ * exact process shape without loading use-m or starting an Agent process.
+ */
+
+const SAFE_SHELL_WORD = /^[a-zA-Z0-9_\-./=,+@:]+$/;
+
+const shellQuote = value => {
+  const stringValue = String(value);
+  if (SAFE_SHELL_WORD.test(stringValue)) return stringValue;
+  return `'${stringValue.replaceAll("'", "'\\''")}'`;
+};
+
+/** Build Agent's arguments as individual process.argv atoms. */
+export const buildAgentArgs = ({ model, verbose = false, resume = null, streamingInput = false } = {}) => {
+  if (!model) throw new Error('Agent model is required');
+
+  const args = ['--model', String(model)];
+  if (verbose) args.push('--verbose');
+  if (resume) args.push('--resume', String(resume), '--no-fork');
+  if (streamingInput) args.push('--input-format', 'stream-json', '--output-format', 'stream-json');
+  return args;
+};
+
+/** Render argv for logs/dry-run output without changing the execution shape. */
+export const formatAgentArgsForDisplay = args => (args || []).map(shellQuote).join(' ');
+
+/**
+ * Agent emits idle/disposal records after terminal errors too. Only these
+ * explicit records prove that a preceding error was recovered.
+ */
+export const isAgentStrongCompletionEvent = data => {
+  if (!data || typeof data !== 'object') return false;
+  if (data.type === 'step_finish' && data.part?.reason === 'stop') return true;
+  return data.type === 'result' && (data.status === 'success' || data.subtype === 'success');
+};
+
+/** Events that mean the CLI is currently waiting, used only by live input. */
+export const isAgentIdleEvent = data => {
+  if (!data || typeof data !== 'object') return false;
+  if (['session.idle', 'session_idle', 'idle'].includes(data.type)) return true;
+  if (data.type === 'log' && ['exiting loop', 'Agent exiting'].includes(data.message)) return true;
+  return isAgentStrongCompletionEvent(data);
+};
+
+/**
+ * Fail closed when Agent resolves a Formal AI request to any other provider.
+ * The critical parser record is handled before the provider can make a request;
+ * the resolved-provider record is a second, independent guard.
+ */
+export const detectFormalAiAgentRoutingMismatch = (record, expectedModel) => {
+  if (expectedModel !== 'formalai/formal-ai' || !record || typeof record !== 'object' || record.type !== 'log') return null;
+
+  const message = String(record.message || '');
+  if (/CRITICAL: --model flag detected/i.test(message) && /default model will be used instead/i.test(message)) {
+    return `Agent could not parse the requested ${expectedModel} model and announced that its default model would be used instead`;
+  }
+
+  if (message !== 'using explicit provider/model' || !record.providerID || !record.modelID) return null;
+  const actualModel = `${record.providerID}/${record.modelID}`;
+  return actualModel === expectedModel ? null : `Agent requested ${expectedModel} but selected ${actualModel}; stopping before another provider can be used`;
+};
+
+export default {
+  buildAgentArgs,
+  detectFormalAiAgentRoutingMismatch,
+  formatAgentArgsForDisplay,
+  isAgentIdleEvent,
+  isAgentStrongCompletionEvent,
+};

package/src/agent.lib.mjs

@@ -31,6 +31,7 @@ import { firstErrorText, stringifyErrorValue } from './error-text.lib.mjs';
 import { classifyRetryableError, prepareRetryAfterError, waitWithCountdown } from './tool-retry.lib.mjs';
 import { attachStreamingInput, finalizeBidirectionalHandler, setupBidirectionalHandler } from './bidirectional-interactive.lib.mjs';
 import { ensureAiToolScratchIgnored, filterAiToolScratchFromStatus } from './ai-tool-scratch.lib.mjs';
+import { buildAgentArgs, detectFormalAiAgentRoutingMismatch, formatAgentArgsForDisplay, isAgentIdleEvent, isAgentStrongCompletionEvent } from './agent-command.lib.mjs';
 
 export { createAgentTokenUsage, accumulateAgentStepFinishUsage, parseAgentTokenUsage };
 
@@ -355,6 +356,22 @@ export const agentCliSupportsLiveInput = versionOutput => {
   return !!version && semver.gte(version, MIN_AGENT_LIVE_INPUT_VERSION);
 };
 
+/**
+ * Agent only fails closed on a `--model` argv it cannot parse from js-0.25.8
+ * onwards (link-assistant/agent#293, fixed by PR #294): earlier releases logged
+ * a CRITICAL record and then answered with their *default* model. Issue #2146
+ * requires Formal AI to be the only model a task can reach, and a guard that
+ * reads the CRITICAL record can only stop the run after Agent has already
+ * decided, so a Formal AI task refuses to start below this release.
+ */
+export const MIN_AGENT_FORMAL_AI_VERSION = '0.25.8';
+
+/** True when this Agent CLI aborts instead of silently picking another model. */
+export const agentCliFailsClosedOnModelMismatch = versionOutput => {
+  const version = getAgentCliVersion(versionOutput);
+  return !!version && semver.gte(version, MIN_AGENT_FORMAL_AI_VERSION);
+};
+
 // Function to validate Agent connection
 export const validateAgentConnection = async (model = defaultModels.agent, options = {}) => {
   // Map model alias to full ID
@@ -401,6 +418,19 @@ export const validateAgentConnection = async (model = defaultModels.agent, optio
         return false;
       }
 
+      if (isFormalAiModel(model) && !(agentVersion && semver.gte(agentVersion, MIN_AGENT_FORMAL_AI_VERSION))) {
+        await log(`❌ Formal AI tasks require @link-assistant/agent >= ${MIN_AGENT_FORMAL_AI_VERSION}`, { level: 'error' });
+        await log('   Older releases answer with their default model when they cannot parse the requested one', { level: 'error' });
+        await log('   (link-assistant/agent#293), and issue #2146 forbids any model other than Formal AI.', { level: 'error' });
+        if (agentVersion) {
+          await log(`   Installed Agent CLI version: ${agentVersion}`, { level: 'error' });
+        } else {
+          await log('   Could not determine the installed Agent CLI version.', { level: 'error' });
+        }
+        await log('   Update with: bun install -g @link-assistant/agent@latest', { level: 'error' });
+        return false;
+      }
+
       // Test basic Agent functionality with a simple "hi" message
       // Agent uses the same JSON interface as OpenCode
       const testResult = await $`printf "hi" | timeout ${Math.floor(timeouts.opencodeCli / 1000)} agent --model ${mappedModel}`;
@@ -600,17 +630,8 @@ export const executeAgentCommand = async params => {
     const toolInvocation = await resolveFormalAiToolExecution({ tool: 'agent', model: argv.model, toolPath: agentPath, workdir: tempDir, log, verbose: argv.verbose, prepareOnly: isPrepareOnly(argv), env: agentEnv });
     Object.assign(agentEnv, toolInvocation.env);
 
-    // Build agent command arguments
-    let agentArgs = `--model ${mappedModel}`;
-
-    // Propagate verbose flag to agent for detailed debugging output
-    if (argv.verbose) {
-      agentArgs += ' --verbose';
-    }
-
     if (argv.resume) {
       await log(`🔄 Resuming from session: ${argv.resume}`);
-      agentArgs += ` --resume ${argv.resume} --no-fork`;
     }
 
     // Agent supports stdin in both plain text and JSON format
@@ -631,9 +652,11 @@ export const executeAgentCommand = async params => {
         });
       }
       const streamingInput = !!bidirectionalHandler;
-      if (streamingInput) {
-        agentArgs += ' --input-format stream-json --output-format stream-json';
-      }
+      // Issue #2146: command-stream treats an interpolated string as one argv
+      // atom. The old `--model formalai/formal-ai --verbose` string made Agent
+      // ignore the requested model and contact its default provider.
+      const agentArgs = buildAgentArgs({ model: mappedModel, verbose: argv.verbose, resume: argv.resume, streamingInput });
+      const displayedAgentArgs = formatAgentArgsForDisplay(agentArgs);
 
       let promptFile = null;
       if (!streamingInput) {
@@ -643,7 +666,7 @@ export const executeAgentCommand = async params => {
         await fs.writeFile(promptFile, combinedPrompt);
       }
 
-      const fullCommand = streamingInput ? `(cd "${tempDir}" && ${toolInvocation.displayCommand} ${agentArgs})` : `(cd "${tempDir}" && cat "${promptFile}" | ${toolInvocation.displayCommand} ${agentArgs})`;
+      const fullCommand = streamingInput ? `(cd "${tempDir}" && ${toolInvocation.displayCommand} ${displayedAgentArgs})` : `(cd "${tempDir}" && cat "${promptFile}" | ${toolInvocation.displayCommand} ${displayedAgentArgs})`;
 
       const preparedResult = await logPreparedToolCommand({ argv, fullCommand, log, formatAligned });
       if (preparedResult) return preparedResult;
@@ -691,26 +714,21 @@ export const executeAgentCommand = async params => {
       // Post-hoc detection on fullOutput can miss errors if NDJSON lines get concatenated without newlines
       let streamingErrorDetected = false;
       let streamingErrorMessage = null;
-      // Issue #1276: Track successful completion events to clear error flags
-      // When agent emits session.idle or disposal events, it means it recovered and completed successfully
+      // Only a strong terminal success record may clear a preceding error.
+      // `session.idle` is also emitted after terminal API failures (#2146).
       let agentCompletedSuccessfully = false;
       // Issue #2141: a fatal startup log record (e.g. ProviderModelNotFoundError)
       // that the agent CLI reports without any `{"type":"error"}` event.
       let fatalLogErrorMessage = null;
+      // A Formal AI run must never continue after Agent resolves another model.
+      let formalAiRoutingErrorMessage = null;
       // Issue #1250: Accumulate token usage during streaming instead of parsing fullOutput later
       // This fixes the issue where NDJSON lines get concatenated without newlines, breaking JSON.parse
       const streamingTokenUsage = createAgentTokenUsage();
       const accumulateTokenUsage = data => accumulateAgentStepFinishUsage(streamingTokenUsage, data);
-      const isAgentSuccessfulCompletionEvent = data => {
-        if (data.type === 'session.idle' || data.type === 'session_idle' || data.type === 'idle') return true;
-        if (data.type === 'log' && data.message === 'exiting loop') return true;
-        if (data.type === 'step_finish' && data.part?.reason === 'stop') return true;
-        if (data.type === 'result' && (data.status === 'success' || data.subtype === 'success')) return true;
-        return false;
-      };
       const markBidirectionalStateFromAgentEvent = async data => {
         if (!bidirectionalHandler) return;
-        if (isAgentSuccessfulCompletionEvent(data)) {
+        if (isAgentIdleEvent(data)) {
           if (typeof bidirectionalHandler.markAiIdle === 'function') {
             try {
               await bidirectionalHandler.markAiIdle();
@@ -754,6 +772,17 @@ export const executeAgentCommand = async params => {
         // Issue #1250: Accumulate token usage during streaming
         accumulateTokenUsage(data);
         await markBidirectionalStateFromAgentEvent(data);
+        if (!formalAiRoutingErrorMessage) {
+          const routingMismatch = detectFormalAiAgentRoutingMismatch(data, mappedModel);
+          if (routingMismatch) {
+            formalAiRoutingErrorMessage = routingMismatch;
+            await log(`🛑 ${routingMismatch}`, { level: 'error' });
+            // Agent emits its parser warning and selected provider before its
+            // first HTTP request. Stop immediately instead of trusting a later
+            // error or cost report to reveal that the wrong LLM was used.
+            execCommand?.kill?.('SIGTERM');
+          }
+        }
         // Issue #1201: Detect error events during streaming for reliable detection
         if (data.type === 'error' || data.type === 'step_error') {
           streamingErrorDetected = true;
@@ -807,17 +836,7 @@ export const executeAgentCommand = async params => {
           // Explicit result message (like Claude outputs)
           lastTextContent = data.result;
         }
-        // Issue #1276: Detect successful completion events
-        // When agent emits session.idle or log with "exiting loop" message, it completed successfully
-        // This means any previous error events were recovered from (e.g., timeout then retry)
-        if (isAgentSuccessfulCompletionEvent(data)) {
-          agentCompletedSuccessfully = true;
-        }
-        // Issue #1296: Detect step_finish with reason "stop" as successful completion
-        // This is a clear marker of success - agent finished normally, not due to error or limit
-        // When this event appears, we should ignore any error events that appeared earlier in the stream
-        // (e.g., timeout errors that were recovered from via retry logic)
-        if (data.type === 'step_finish' && data.part?.reason === 'stop') agentCompletedSuccessfully = true;
+        if (isAgentStrongCompletionEvent(data)) agentCompletedSuccessfully = true;
       };
 
       const handleAgentStreamEvents = async events => {
@@ -867,6 +886,12 @@ export const executeAgentCommand = async params => {
       // Issue #2141: the detection now renders structured payloads as text.
       const outputError = detectAgentErrorsInOutput(fullOutput);
 
+      if (formalAiRoutingErrorMessage) {
+        outputError.detected = true;
+        outputError.type = 'AgentModelRoutingMismatch';
+        outputError.match = formalAiRoutingErrorMessage;
+      }
+
       // Issue #1276: Clear streaming error detection if agent completed successfully
       // When an error occurs during execution (e.g., timeout) but the agent recovers and completes,
       // we should NOT treat it as a failure. The exit code is the authoritative success indicator.

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

@@ -0,0 +1,241 @@
+/**
+ * Idle-only refresh of the agentic CLIs (issue #2146, PR #2147 review).
+ *
+ * The maintainer's review closed with:
+ *
+ *   "Do same auto update for claude, codex, agent and other agentic CLIs (when
+ *    no tasks are active and new version is available) or support update inside
+ *    each separate task's docker."
+ *
+ * This module implements the first option: while the host has no active task,
+ * compare each CLI's installed version against the registry and reinstall only
+ * the ones that moved. The second option is deliberately not taken — updating
+ * inside a task's container would change the toolchain mid-run and make the
+ * task's own logs unreproducible.
+ *
+ * Two packages are excluded on purpose:
+ *
+ *   - `@link-assistant/hive-mind` — replacing the package that owns the running
+ *     process mid-flight is how you get a half-swapped bot. Hive Mind is updated
+ *     by redeploying its image.
+ *   - `start-command` — pinned by exact version in the Dockerfile because each
+ *     bump encodes a behavioural fix Hive Mind depends on (see the pin comment
+ *     in `Dockerfile`). Bumping it is a reviewed change, not a background one.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2146
+ */
+
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+import { resolveBotStateDir } from './session-store.lib.mjs';
+import { withStateLock } from './state-lock.lib.mjs';
+
+const execFileAsync = promisify(execFile);
+
+const STATE_FILE_NAME = 'agentic-cli-updates.json';
+const CLI_UPDATE_LOCK_NAME = 'agentic-cli-update';
+const DEFAULT_COMMAND_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_INSTALL_TIMEOUT_MS = 15 * 60 * 1000;
+
+/** Default minimum gap between registry checks, so a busy bot does not poll npm continuously. */
+export const DEFAULT_CLI_UPDATE_INTERVAL_MS = 6 * 60 * 60 * 1000;
+
+/**
+ * The CLIs Hive Mind drives, in the same order the Dockerfile installs them.
+ *
+ * `installer: 'self'` is for Claude Code, which ships a native binary through
+ * its own installer script; `claude update` is the supported refresh path and
+ * `bun install -g` would fight the postinstall link (issue #1633).
+ */
+export const AGENTIC_CLI_TARGETS = Object.freeze([
+  { id: 'claude', package: '@anthropic-ai/claude-code', binary: 'claude', installer: 'self', updateArgs: ['update'] },
+  { id: 'codex', package: '@openai/codex', binary: 'codex', installer: 'bun' },
+  { id: 'agent', package: '@link-assistant/agent', binary: 'agent', installer: 'bun' },
+  { id: 'gemini', package: '@google/gemini-cli', binary: 'gemini', installer: 'bun' },
+  { id: 'qwen', package: '@qwen-code/qwen-code', binary: 'qwen', installer: 'bun' },
+  { id: 'copilot', package: '@github/copilot', binary: 'copilot', installer: 'bun' },
+  { id: 'opencode', package: 'opencode-ai', binary: 'opencode', installer: 'bun' },
+]);
+
+/** Auto-update is on by default; operators can disable it or narrow it to a subset. */
+export const isAgenticCliAutoUpdateEnabled = (env = process.env) => {
+  const raw = String(env.HIVE_MIND_AGENTIC_CLI_AUTO_UPDATE ?? '')
+    .trim()
+    .toLowerCase();
+  if (!raw) return true;
+  return !['0', 'false', 'no', 'off'].includes(raw);
+};
+
+const parseIdList = value =>
+  String(value ?? '')
+    .split(',')
+    .map(entry => entry.trim().toLowerCase())
+    .filter(Boolean);
+
+/**
+ * Resolve which CLIs this host should refresh.
+ *
+ * `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) => {
+  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));
+};
+
+/** First semantic version in a CLI's `--version` output, which is rarely bare. */
+export const parseCliVersion = text => String(text ?? '').match(/\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/)?.[0] ?? null;
+
+export const resolveAgenticCliStatePath = (env = process.env) => path.join(resolveBotStateDir(env), STATE_FILE_NAME);
+
+/** Read the refresh journal. A missing or corrupt file is an empty journal, never a throw. */
+export const readAgenticCliState = ({ env = process.env, fsImpl = fs } = {}) => {
+  try {
+    const parsed = JSON.parse(fsImpl.readFileSync(resolveAgenticCliStatePath(env), 'utf8'));
+    return { version: 1, lastCheckedAt: null, tools: {}, ...parsed };
+  } catch {
+    return { version: 1, lastCheckedAt: null, tools: {} };
+  }
+};
+
+/** Persist the refresh journal atomically. */
+export const writeAgenticCliState = (state, { env = process.env, fsImpl = fs } = {}) => {
+  const target = resolveAgenticCliStatePath(env);
+  fsImpl.mkdirSync(path.dirname(target), { recursive: true });
+  const temporary = `${target}.tmp`;
+  fsImpl.writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+  fsImpl.renameSync(temporary, target);
+  return state;
+};
+
+/** Installed version of one CLI, or null when the binary is absent or mute. */
+export const readInstalledCliVersion = async (target, { run = execFileAsync, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS } = {}) => {
+  try {
+    const result = await run(target.binary, ['--version'], { encoding: 'utf8', timeout: timeoutMs });
+    return parseCliVersion(`${result?.stdout ?? ''}${result?.stderr ?? ''}`);
+  } catch {
+    return null;
+  }
+};
+
+/** Latest version the npm registry publishes for one CLI, or null when unreachable. */
+export const readLatestPublishedVersion = async (target, { run = execFileAsync, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS } = {}) => {
+  try {
+    const result = await run('npm', ['view', target.package, 'version'], { encoding: 'utf8', timeout: timeoutMs });
+    return parseCliVersion(result?.stdout);
+  } catch {
+    return null;
+  }
+};
+
+/** Reinstall one CLI at the latest published version. */
+export const installAgenticCli = async (target, { run = execFileAsync, timeoutMs = DEFAULT_INSTALL_TIMEOUT_MS } = {}) => {
+  if (target.installer === 'self') return run(target.binary, target.updateArgs ?? ['update'], { encoding: 'utf8', timeout: timeoutMs });
+  return run('bun', ['install', '-g', `${target.package}@latest`], { encoding: 'utf8', timeout: timeoutMs });
+};
+
+/**
+ * Refresh every configured agentic CLI, but only while the host is idle.
+ *
+ * Idleness is the same signal `hive cleanup` trusts: a task is active when it
+ * holds a process or a non-terminal start-command session. Replacing a CLI
+ * binary under a running task would swap the toolchain mid-run.
+ *
+ * @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 = {} } = {}) => {
+  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: [] };
+  }
+
+  return withStateLock(
+    CLI_UPDATE_LOCK_NAME,
+    async () => {
+      const state = readAgenticCliState({ env, fsImpl });
+      const nowMs = now().getTime();
+      const lastCheckedMs = Date.parse(state.lastCheckedAt ?? '') || 0;
+      if (!force && lastCheckedMs && nowMs - lastCheckedMs < minIntervalMs) {
+        if (verbose && log) await log(`[VERBOSE] agentic-cli-updater: last checked ${Math.round((nowMs - lastCheckedMs) / 60000)} min ago; throttled`);
+        return { status: 'throttled', updated: [], upToDate: [], failed: [] };
+      }
+
+      const getActiveTasks = getActiveTasksImpl ?? (await import('./cleanup.os.lib.mjs')).getActiveTasks;
+      const activeTasks = await getActiveTasks({ resolveBranches: false });
+      if (activeTasks.length > 0) {
+        if (verbose && log) await log(`[VERBOSE] agentic-cli-updater: ${activeTasks.length} active task(s); deferring the CLI refresh`);
+        return { status: 'busy', activeTaskCount: activeTasks.length, updated: [], upToDate: [], failed: [] };
+      }
+
+      const updated = [];
+      const upToDate = [];
+      const failed = [];
+      const tools = { ...state.tools };
+
+      for (const target of listAgenticCliUpdateTargets(env)) {
+        const installed = await readInstalledCliVersion(target, { run });
+        if (!installed) {
+          // Not installed on this host (image variants differ); nothing to refresh.
+          if (verbose && log) await log(`[VERBOSE] agentic-cli-updater: ${target.id} is not installed here; skipping`);
+          continue;
+        }
+
+        const latest = await readLatestPublishedVersion(target, { run });
+        if (!latest) {
+          failed.push({ id: target.id, installed, error: `could not read the published version of ${target.package}` });
+          continue;
+        }
+        if (latest === installed) {
+          upToDate.push({ id: target.id, version: installed });
+          tools[target.id] = { ...tools[target.id], version: installed, checkedAt: now().toISOString() };
+          continue;
+        }
+
+        if (log) await log(`⬆️ Updating ${target.id} ${installed} → ${latest}`);
+        try {
+          await installAgenticCli(target, { run });
+        } catch (error) {
+          const message = error?.stderr?.toString?.().trim() || error?.message || String(error);
+          if (log) await log(`⚠️ Could not update ${target.id}: ${message}`);
+          failed.push({ id: target.id, installed, latest, error: message });
+          continue;
+        }
+
+        // Trust the binary, not the installer's exit code: a package can install
+        // and still fail to link its bin.
+        const after = await readInstalledCliVersion(target, { run });
+        if (after === latest) {
+          updated.push({ id: target.id, from: installed, to: after });
+          tools[target.id] = { version: after, previousVersion: installed, updatedAt: now().toISOString(), checkedAt: now().toISOString() };
+        } else {
+          failed.push({ id: target.id, installed, latest, error: `after install the binary reports ${after ?? 'nothing'}` });
+        }
+      }
+
+      writeAgenticCliState({ ...state, lastCheckedAt: now().toISOString(), tools }, { env, fsImpl });
+      if (log && updated.length > 0) await log(`✅ Agentic CLIs updated while idle: ${updated.map(entry => `${entry.id} ${entry.from}→${entry.to}`).join(', ')}`);
+      if (verbose && log) await log(`[VERBOSE] agentic-cli-updater: ${updated.length} updated, ${upToDate.length} current, ${failed.length} failed`);
+      return { status: 'checked', updated, upToDate, failed };
+    },
+    { env, fsImpl, log, ...lockOptions }
+  );
+};
+
+export default {
+  AGENTIC_CLI_TARGETS,
+  DEFAULT_CLI_UPDATE_INTERVAL_MS,
+  installAgenticCli,
+  isAgenticCliAutoUpdateEnabled,
+  listAgenticCliUpdateTargets,
+  parseCliVersion,
+  readAgenticCliState,
+  readInstalledCliVersion,
+  readLatestPublishedVersion,
+  resolveAgenticCliStatePath,
+  updateAgenticClisWhenIdle,
+  writeAgenticCliState,
+};