@link-assistant/hive-mind 2.5.4 → 2.5.6

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @link-assistant/hive-mind
 
+## 2.5.6
+
+### Patch Changes
+
+- e501237: Warn when malformed or safety-clamped numeric environment settings fall back to a different effective value.
+- 10ddbca: Document same-session live input support and the Codex app-server integration plan for issue #2057.
+
+## 2.5.5
+
+### Patch Changes
+
+- e6ccdc1: Allow operators to lower the queue startup interval safety floor with `HIVE_MIND_MIN_START_INTERVAL_FLOOR_MS` while preserving the 10-minute default.
+
 ## 2.5.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "2.5.4",
+  "version": "2.5.6",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/config.lib.mjs

@@ -30,23 +30,13 @@ const getenv = typeof getenvModule === 'function' ? getenvModule : getenvModule.
 // Use semver package for version comparison (see issue #1146)
 import semver from 'semver';
 import { buildClaudeQuietEnv } from './claude-quiet-config.lib.mjs';
+import { clampEnvValue, parseIntegerEnv, parseNumberEnv } from './env-config.lib.mjs';
 
 // Import lino for parsing Links Notation format
 const { lino } = await import('./lino.lib.mjs');
 
-// Helper function to safely parse integers with fallback
-const parseIntWithDefault = (envVar, defaultValue) => {
-  const value = getenv(envVar, defaultValue.toString());
-  const parsed = parseInt(value);
-  return isNaN(parsed) ? defaultValue : parsed;
-};
-
-// Helper function to safely parse floats with fallback
-const parseFloatWithDefault = (envVar, defaultValue) => {
-  const value = getenv(envVar, defaultValue.toString());
-  const parsed = parseFloat(value);
-  return isNaN(parsed) ? defaultValue : parsed;
-};
+const parseIntWithDefault = (envVar, defaultValue) => parseIntegerEnv(envVar, defaultValue);
+const parseFloatWithDefault = (envVar, defaultValue) => parseNumberEnv(envVar, defaultValue);
 
 // Timeout configurations (in milliseconds)
 export const timeouts = {
@@ -737,7 +727,7 @@ export const cacheTtl = {
   usageApi: parseIntWithDefault('HIVE_MIND_USAGE_API_CACHE_TTL_MS', 13 * 60 * 1000), // 13 minutes
   // System metrics cache TTL (RAM, CPU, disk). Issue #2015 caps this at
   // 1 minute so queue decisions do not use stale host pressure data.
-  system: Math.min(parseIntWithDefault('HIVE_MIND_SYSTEM_CACHE_TTL_MS', 60 * 1000), 60 * 1000), // max 1 minute
+  system: clampEnvValue('HIVE_MIND_SYSTEM_CACHE_TTL_MS', parseIntWithDefault('HIVE_MIND_SYSTEM_CACHE_TTL_MS', 60 * 1000), { maximum: 60 * 1000 }), // max 1 minute
 };
 
 // File and path configurations

package/src/env-config.lib.mjs

@@ -0,0 +1,98 @@
+/**
+ * Parse numeric environment configuration without silently accepting malformed
+ * suffixes or discarding explicit operator input.
+ */
+
+const emittedWarnings = new Set();
+
+function warnOnce(key, message) {
+  if (emittedWarnings.has(key)) return;
+  emittedWarnings.add(key);
+  console.warn(message);
+}
+
+function readExplicitEnv(envVar) {
+  const rawValue = process.env[envVar];
+  return rawValue === undefined ? null : rawValue;
+}
+
+function warnInvalid(envVar, rawValue, type, defaultValue, scope) {
+  warnOnce(`invalid:${envVar}`, `[${scope}] ${envVar}=${JSON.stringify(rawValue)} is not a valid ${type}; using default ${defaultValue}.`);
+}
+
+/**
+ * Read a base-10 integer environment variable.
+ *
+ * @param {string} envVar
+ * @param {number} defaultValue
+ * @param {{scope?: string}} [options]
+ * @returns {number}
+ */
+export function parseIntegerEnv(envVar, defaultValue, { scope = 'config' } = {}) {
+  const rawValue = readExplicitEnv(envVar);
+  if (rawValue === null) return defaultValue;
+
+  const normalized = rawValue.trim();
+  if (!/^[+-]?\d+$/.test(normalized)) {
+    warnInvalid(envVar, rawValue, 'integer', defaultValue, scope);
+    return defaultValue;
+  }
+
+  const parsed = Number(normalized);
+  if (!Number.isSafeInteger(parsed)) {
+    warnInvalid(envVar, rawValue, 'integer', defaultValue, scope);
+    return defaultValue;
+  }
+
+  return parsed;
+}
+
+/**
+ * Read a finite decimal environment variable.
+ *
+ * @param {string} envVar
+ * @param {number} defaultValue
+ * @param {{scope?: string}} [options]
+ * @returns {number}
+ */
+export function parseNumberEnv(envVar, defaultValue, { scope = 'config' } = {}) {
+  const rawValue = readExplicitEnv(envVar);
+  if (rawValue === null) return defaultValue;
+
+  const normalized = rawValue.trim();
+  const isDecimal = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/.test(normalized);
+  const parsed = Number(normalized);
+  if (!isDecimal || !Number.isFinite(parsed)) {
+    warnInvalid(envVar, rawValue, 'number', defaultValue, scope);
+    return defaultValue;
+  }
+
+  return parsed;
+}
+
+/**
+ * Apply a safety bound and explain when it changes an explicitly configured
+ * environment value.
+ *
+ * @param {string} envVar
+ * @param {number} value
+ * @param {{minimum?: number, maximum?: number, scope?: string, hint?: string}} options
+ * @returns {number}
+ */
+export function clampEnvValue(envVar, value, { minimum, maximum, scope = 'config', hint = '' }) {
+  if (minimum !== undefined && value < minimum) {
+    if (readExplicitEnv(envVar) !== null) {
+      warnOnce(`minimum:${envVar}`, `[${scope}] ${envVar}=${value} is below the minimum (${minimum}); using ${minimum}.${hint ? ` ${hint}` : ''}`);
+    }
+    return minimum;
+  }
+
+  if (maximum !== undefined && value > maximum) {
+    if (readExplicitEnv(envVar) !== null) {
+      warnOnce(`maximum:${envVar}`, `[${scope}] ${envVar}=${value} exceeds the maximum (${maximum}); using ${maximum}.${hint ? ` ${hint}` : ''}`);
+    }
+    return maximum;
+  }
+
+  return value;
+}

package/src/queue-config.lib.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { ensureUseM } from './use-m-bootstrap.lib.mjs';
+import { clampEnvValue, parseIntegerEnv, parseNumberEnv } from './env-config.lib.mjs';
 
 /**
  * Queue Configuration Module
@@ -178,21 +179,11 @@ export function parseQueueConfig(linoConfig) {
   }
 }
 
-// Helper function to safely parse floats with fallback
-const parseFloatWithDefault = (envVar, defaultValue) => {
-  const value = getenv(envVar, defaultValue.toString());
-  const parsed = parseFloat(value);
-  return isNaN(parsed) ? defaultValue : parsed;
-};
-
-// Helper function to safely parse integers with fallback
-const parseIntWithDefault = (envVar, defaultValue) => {
-  const value = getenv(envVar, defaultValue.toString());
-  const parsed = parseInt(value);
-  return isNaN(parsed) ? defaultValue : parsed;
-};
+const parseFloatWithDefault = (envVar, defaultValue) => parseNumberEnv(envVar, defaultValue, { scope: 'queue-config' });
+const parseIntWithDefault = (envVar, defaultValue) => parseIntegerEnv(envVar, defaultValue, { scope: 'queue-config' });
 
-const MINIMUM_START_INTERVAL_MS = 10 * 60 * 1000;
+const DEFAULT_MINIMUM_START_INTERVAL_MS = 10 * 60 * 1000;
+const minimumStartIntervalMs = parseIntWithDefault('HIVE_MIND_MIN_START_INTERVAL_FLOOR_MS', DEFAULT_MINIMUM_START_INTERVAL_MS);
 
 // Parse links notation config from environment variable (if provided)
 const linoConfig = parseQueueConfig(getenv('HIVE_MIND_QUEUE_CONFIG', ''));
@@ -276,7 +267,13 @@ export const QUEUE_CONFIG = {
   // MIN_START_INTERVAL_MS: Minimum global spacing between task startups.
   // Issue #2015: after resource thresholds clear, starting a backlog in a burst
   // can kill the next batch before host metrics have time to settle.
-  MIN_START_INTERVAL_MS: Math.max(parseIntWithDefault('HIVE_MIND_MIN_START_INTERVAL_MS', MINIMUM_START_INTERVAL_MS), MINIMUM_START_INTERVAL_MS), // at least 10 minutes between starts
+  // Issue #2053: operators can explicitly lower the safety floor on hosts where
+  // resource metrics settle sooner. The default remains 10 minutes.
+  MIN_START_INTERVAL_MS: clampEnvValue('HIVE_MIND_MIN_START_INTERVAL_MS', parseIntWithDefault('HIVE_MIND_MIN_START_INTERVAL_MS', DEFAULT_MINIMUM_START_INTERVAL_MS), {
+    minimum: minimumStartIntervalMs,
+    scope: 'queue-config',
+    hint: 'Set HIVE_MIND_MIN_START_INTERVAL_FLOOR_MS to lower the minimum.',
+  }),
   CONSUMER_POLL_INTERVAL_MS: parseIntWithDefault('HIVE_MIND_CONSUMER_POLL_INTERVAL_MS', 60000), // 1 minute between queue checks
   MESSAGE_UPDATE_INTERVAL_MS: parseIntWithDefault('HIVE_MIND_MESSAGE_UPDATE_INTERVAL_MS', 60000), // 1 minute between status message updates