@link-assistant/hive-mind 2.11.13 → 2.12.0

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

@@ -0,0 +1,106 @@
+/**
+ * Background maintenance for the Formal AI sidecar and the agentic CLIs
+ * (issue #2146, PR #2147 review).
+ *
+ * One periodic tick performs the three idle-only duties the review asked for,
+ * in the only order that is safe:
+ *
+ *   1. **Reconcile and stop.** Drop leases whose task container is gone and, if
+ *      nothing is left, stop the sidecar. Must run first — the update and the
+ *      CLI refresh both require an idle host, and a crashed task would
+ *      otherwise keep the sidecar alive forever.
+ *   2. **Update the Formal AI image**, including the non-destructive memory
+ *      migration, while the sidecar is stopped.
+ *   3. **Refresh the agentic CLIs**, which is throttled independently because
+ *      it queries the npm registry.
+ *
+ * Every step is best-effort: maintenance must never take the bot down, and a
+ * failure is reported and retried on the next tick rather than thrown.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2146
+ */
+
+import { updateAgenticClisWhenIdle } from './agentic-cli-updater.lib.mjs';
+import { reconcileFormalAiSidecar, stopFormalAiSidecar, withFormalAiSidecarLock } from './formal-ai-sidecar.lib.mjs';
+import { updateFormalAiSidecarWhenIdle } from './formal-ai-updater.lib.mjs';
+
+/** Default gap between maintenance ticks. */
+export const DEFAULT_FORMAL_AI_MAINTENANCE_INTERVAL_MS = 5 * 60 * 1000;
+
+/**
+ * Stop the sidecar when no Formal AI task holds a lease any more.
+ *
+ * This is what turns "the task finished" into "the container is gone" without
+ * having to hook every completion path: a lease is only live while its task
+ * container is, so a finished, killed or crashed task all converge here.
+ *
+ * @returns {Promise<{leaseCount: number, stopped: boolean}>}
+ */
+export const stopIdleFormalAiSidecar = async ({ env = process.env, run, log = null, verbose = false, lockOptions = {} } = {}) =>
+  withFormalAiSidecarLock(
+    async () => {
+      const { leaseCount, container } = await reconcileFormalAiSidecar({ env, run, log, verbose });
+      if (leaseCount > 0 || !container.exists) return { leaseCount, stopped: false };
+      const { stopped } = await stopFormalAiSidecar({ env, run, log, verbose, reason: 'no Formal AI tasks running' });
+      return { leaseCount: 0, stopped };
+    },
+    { env, log, ...lockOptions }
+  );
+
+/**
+ * Run one maintenance tick.
+ *
+ * @returns {Promise<{idle: object, formalAi: object|null, agenticClis: object|null, errors: object[]}>}
+ */
+export const runFormalAiMaintenanceTick = async ({ env = process.env, run, log = null, verbose = false, updateFormalAi = updateFormalAiSidecarWhenIdle, updateClis = updateAgenticClisWhenIdle, stopIdle = stopIdleFormalAiSidecar } = {}) => {
+  const errors = [];
+
+  let idle = { leaseCount: null, stopped: false };
+  try {
+    idle = await stopIdle({ env, run, log, verbose });
+  } catch (error) {
+    errors.push({ stage: 'stop-idle', error: error?.message || String(error) });
+  }
+
+  let formalAi = null;
+  try {
+    formalAi = await updateFormalAi({ env, run, log, verbose });
+  } catch (error) {
+    errors.push({ stage: 'formal-ai-update', error: error?.message || String(error) });
+  }
+
+  let agenticClis = null;
+  try {
+    agenticClis = await updateClis({ env, run, log, verbose });
+  } catch (error) {
+    errors.push({ stage: 'agentic-cli-update', error: error?.message || String(error) });
+  }
+
+  if (log && errors.length > 0) await log(`⚠️ Formal AI maintenance tick had ${errors.length} problem(s): ${errors.map(entry => `${entry.stage}: ${entry.error}`).join('; ')}`);
+  if (verbose && log) await log(`[VERBOSE] formal-ai-maintenance: leases=${idle.leaseCount ?? 'unknown'} stopped=${idle.stopped} update=${formalAi?.status ?? 'skipped'} clis=${agenticClis?.status ?? 'skipped'}`);
+  return { idle, formalAi, agenticClis, errors };
+};
+
+/**
+ * Start the periodic maintenance timer.
+ *
+ * The timer is unref'd so it never keeps the process alive on shutdown.
+ *
+ * @returns {{stop: () => void}}
+ */
+export const startFormalAiMaintenance = ({ env = process.env, log = null, verbose = false, intervalMs = DEFAULT_FORMAL_AI_MAINTENANCE_INTERVAL_MS, setIntervalImpl = setInterval, clearIntervalImpl = clearInterval, runTick = runFormalAiMaintenanceTick } = {}) => {
+  const tick = () => {
+    runTick({ env, log, verbose }).catch(error => {
+      console.error(`[formal-ai-maintenance] tick failed: ${error?.message || error}`);
+    });
+  };
+
+  const timer = setIntervalImpl(tick, intervalMs);
+  timer?.unref?.();
+  tick();
+  return {
+    stop: () => clearIntervalImpl(timer),
+  };
+};
+
+export default { DEFAULT_FORMAL_AI_MAINTENANCE_INTERVAL_MS, runFormalAiMaintenanceTick, startFormalAiMaintenance, stopIdleFormalAiSidecar };

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

@@ -0,0 +1,25 @@
+/**
+ * Formal AI model identity — the smallest module that can answer "is this task
+ * driven by Formal AI?".
+ *
+ * These three symbols used to live in `src/models/index.mjs`, which bootstraps
+ * `use-m` at import time and therefore reaches the network. The Formal AI
+ * sidecar lifecycle (issue #2146) is imported by the isolation runner, whose
+ * own regression test asserts that importing it performs no network fetch, so
+ * the identity check has to be reachable without dragging the whole model
+ * catalogue in. `src/models/index.mjs` re-exports these so there is still a
+ * single definition.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2146
+ */
+
+/** The alias users type: `--model formal-ai`. */
+export const FORMAL_AI_MODEL_ALIAS = 'formal-ai';
+
+/** The provider-qualified id used when a tool routes through a provider. */
+export const FORMAL_AI_PROVIDER_MODEL_ID = 'formalai/formal-ai';
+
+/** True when a model string names Formal AI in either spelling. */
+export const isFormalAiModel = model => model === FORMAL_AI_MODEL_ALIAS || model === FORMAL_AI_PROVIDER_MODEL_ID;
+
+export default { FORMAL_AI_MODEL_ALIAS, FORMAL_AI_PROVIDER_MODEL_ID, isFormalAiModel };

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

@@ -53,6 +53,8 @@ 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';
+
 const execFileAsync = promisify(execFile);
 
 export const FORMAL_AI_DEFAULT_API_KEY = 'formal-ai';
@@ -359,6 +361,13 @@ export const prepareFormalAiRuntime = async ({ tool, workdir, log = async () =>
 
   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})`);
+
   const apiKey = resolveFormalAiApiKey(env);
   const externalBaseUrl = env.HIVE_MIND_FORMAL_AI_BASE_URL?.trim() || null;
   const homeRoot = resolveFormalAiHomeRoot(env);
@@ -420,6 +429,7 @@ export const prepareFormalAiRuntime = async ({ tool, workdir, log = async () =>
       client,
       notes,
       serverStarted: !!server,
+      formalAiVersion,
       stop: async () => {
         runtimeCache.delete(cacheKey);
         await server?.stop?.();