@link-assistant/hive-mind 2.0.13 → 2.0.15

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @link-assistant/hive-mind
 
+## 2.0.15
+
+### Patch Changes
+
+- 0d2f2bb: Fix "Cannot read properties of null (reading 'type')" crash that aborted Codex (and other agent) runs when the tool echoed a stream line that parsed to a bare `null` or non-object JSON primitive. All NDJSON stream parsers (Codex, Claude, Agent, OpenCode) now ignore non-object lines instead of dereferencing them.
+
+## 2.0.14
+
+### Patch Changes
+
+- 03954a9: Show fuzzy suggestions for mistyped CLI and Telegram command options, including the closest match plus up to four additional alternatives.
+
 ## 2.0.13
 
 ### Patch Changes

package/package.json

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

package/src/agent.lib.mjs

@@ -542,6 +542,9 @@ export const executeAgentCommand = async params => {
             if (!line.trim()) continue;
             try {
               const data = sanitizeObjectStrings(JSON.parse(line));
+              // Issue #1968: a bare `null`/primitive NDJSON line must not abort
+              // event processing (any data.X access would throw on null).
+              if (data === null || typeof data !== 'object') continue;
               // Output formatted JSON
               await log(JSON.stringify(data, null, 2));
               // Capture session ID from the first message
@@ -616,6 +619,8 @@ export const executeAgentCommand = async params => {
               if (!stderrLine.trim()) continue;
               try {
                 const stderrData = sanitizeObjectStrings(JSON.parse(stderrLine));
+                // Issue #1968: skip bare `null`/primitive lines (see stdout handler above).
+                if (stderrData === null || typeof stderrData !== 'object') continue;
                 // Output formatted JSON (same formatting as stdout)
                 await log(JSON.stringify(stderrData, null, 2));
                 // Capture session ID from stderr too (agent sends it via stderr)
@@ -695,6 +700,9 @@ export const executeAgentCommand = async params => {
           try {
             const msg = sanitizeObjectStrings(JSON.parse(line));
 
+            // Issue #1968: ignore bare `null`/primitive lines (msg.type would throw on null).
+            if (msg === null || typeof msg !== 'object') continue;
+
             // Check for explicit error message types from agent
             if (msg.type === 'error' || msg.type === 'step_error') {
               return { detected: true, type: 'AgentError', match: msg.message || msg.error || line.substring(0, 100) };

package/src/claude.lib.mjs

@@ -872,6 +872,7 @@ export const executeClaudeCommand = async params => {
             if (!line.trim()) continue;
             try {
               const data = sanitizeObjectStrings(JSON.parse(line));
+              if (data === null || typeof data !== 'object') continue; // Issue #1968: skip bare null/primitive NDJSON lines
               // Issue #1510: Track last event time for all modes (not just interactive)
               // so activity timeout can report accurate idle duration
               lastEventTime = Date.now();
@@ -1110,11 +1111,10 @@ export const executeClaudeCommand = async params => {
         try {
           const data = sanitizeObjectStrings(JSON.parse(stdoutLineBuffer));
           await log(JSON.stringify(data, null, 2));
-          if (data.type === 'result' && data.subtype === 'success' && data.total_cost_usd != null) {
+          if (data?.type === 'result' && data.subtype === 'success' && data.total_cost_usd != null) {
             anthropicTotalCostUSD = data.total_cost_usd;
-          } else if (data.type === 'result' && data.total_cost_usd != null) {
-            // Issue #1886: keep a non-success terminal result's cost as a fallback
-            // for accumulation (see the streaming branch above).
+          } else if (data?.type === 'result' && data.total_cost_usd != null) {
+            // Issue #1886: keep a non-success terminal result's cost as a fallback (see streaming branch above).
             anthropicCostFromAnyResult = data.total_cost_usd;
           }
           // Issue #1472: Forward remaining buffer event to interactive handler (was previously missed)

package/src/cli-arguments.lib.mjs

@@ -1,5 +1,7 @@
 import { getenv, makeConfig, yargs as linoYargs } from 'lino-arguments';
 
+import { enhanceUnknownArgumentError } from './option-suggestions.lib.mjs';
+
 export { getenv };
 
 export const hideBin = argv => argv.slice(2);
@@ -52,17 +54,24 @@ export function addCliCompatibilityAliases(parsed, { positionalAliases = [] } =
 
 export function parseCliArgumentsWithLino({ argv = process.argv, commandName = 'cli', createYargsConfig, positionalAliases = [], lenv = { enabled: true }, env = { enabled: false }, getenv: getenvOptions = { enabled: true } } = {}) {
   const fullArgv = ensureFullArgv(argv, commandName);
-  const parsed = makeConfig({
-    argv: fullArgv,
-    lenv,
-    env,
-    getenv: getenvOptions,
-    yargs: ({ yargs, getenv: getenvHelper }) => {
-      const parser = yargs.exitProcess(false);
-      const configured = createYargsConfig ? createYargsConfig(parser, getenvHelper) : parser;
-      return configured.exitProcess(false);
-    },
-  });
+  let configuredParser = null;
+  let parsed;
+
+  try {
+    parsed = makeConfig({
+      argv: fullArgv,
+      lenv,
+      env,
+      getenv: getenvOptions,
+      yargs: ({ yargs, getenv: getenvHelper }) => {
+        const parser = yargs.exitProcess(false);
+        configuredParser = createYargsConfig ? createYargsConfig(parser, getenvHelper) : parser;
+        return configuredParser.exitProcess(false);
+      },
+    });
+  } catch (error) {
+    throw enhanceUnknownArgumentError(error, configuredParser);
+  }
 
   return addCliCompatibilityAliases(parsed, { positionalAliases });
 }

package/src/codex.lib.mjs

@@ -470,6 +470,16 @@ export const parseCodexExecJsonOutput = (output, state = {}, requestedModelId =
       continue;
     }
 
+    // Issue #1968: a stream line that parses to a bare `null` (or any non-object
+    // JSON primitive such as a number/string/boolean) must not crash the parser.
+    // Codex echoes the stdout of every command it runs back into its own NDJSON
+    // stream (see issue #1955), so a target repo that prints a standalone `null`
+    // line surfaces here as `JSON.parse('null') === null`. Accessing `data.type`
+    // on that null threw "Cannot read properties of null (reading 'type')" and
+    // aborted the entire solve. Real Codex events are always JSON objects, so any
+    // non-object line is safely ignored.
+    if (data === null || typeof data !== 'object') continue;
+
     const eventType = typeof data.type === 'string' ? data.type : 'unknown';
     nextState.eventCounts[eventType] = (nextState.eventCounts[eventType] || 0) + 1;
 
@@ -1044,6 +1054,9 @@ export const executeCodexCommand = async params => {
               if (!line) continue;
               try {
                 const data = sanitizeObjectStrings(JSON.parse(line));
+                // Issue #1968: skip bare `null`/primitive lines so the handlers
+                // below never receive a non-object event (see parseCodexExecJsonOutput).
+                if (data === null || typeof data !== 'object') continue;
                 if (interactiveHandler) await interactiveHandler.processEvent(data);
                 if (progressMonitor) await progressMonitor.processStreamEvent(data);
               } catch {

package/src/opencode.lib.mjs

@@ -342,6 +342,9 @@ export const executeOpenCodeCommand = async params => {
             for (const line of lines) {
               if (!line.trim()) continue;
               const data = sanitizeObjectStrings(JSON.parse(line));
+              // Issue #1968: a bare `null`/primitive NDJSON line must not abort the
+              // rest of the chunk (data.type access would throw on null).
+              if (data === null || typeof data !== 'object') continue;
               accumulateAgentStepFinishUsage(streamingTokenUsage, data);
               // Track text content for result summary
               // OpenCode outputs text via 'text', 'assistant', 'message', or 'result' type events
@@ -385,6 +388,8 @@ export const executeOpenCodeCommand = async params => {
               for (const line of lines) {
                 if (!line.trim()) continue;
                 const data = sanitizeObjectStrings(JSON.parse(line));
+                // Issue #1968: skip bare `null`/primitive lines (see stdout handler above).
+                if (data === null || typeof data !== 'object') continue;
                 accumulateAgentStepFinishUsage(streamingTokenUsage, data);
                 if (data.type === 'text' && data.text) {
                   lastTextContent = data.text;

package/src/option-suggestions.lib.mjs

@@ -44,79 +44,97 @@ export function calculateLevenshteinDistance(a, b) {
   return matrix[b.length][a.length];
 }
 
-/**
- * Find similar option names based on Levenshtein distance
- *
- * @param {string} unknownOption - The option name that was not recognized (e.g., "branch")
- * @param {Object} yargsInstance - The yargs instance with defined options
- * @param {number} maxSuggestions - Maximum number of suggestions to return (default: 3)
- * @param {number} distanceThreshold - Maximum distance to consider for suggestions (default: 5)
- * @returns {string[]} - Array of suggested option names, sorted by similarity
- */
-export function findSimilarOptions(unknownOption, yargsInstance, maxSuggestions = 3, distanceThreshold = 5) {
-  // Remove leading dashes from the unknown option
-  const cleanUnknown = unknownOption.replace(/^-+/, '');
+const normalizeOptionName = option =>
+  String(option || '')
+    .trim()
+    .replace(/^-+/, '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/[_\s]+/g, '-')
+    .toLowerCase();
 
-  // Get all available options from yargs
+const compactOptionName = option => normalizeOptionName(option).replace(/-/g, '');
+
+function getAvailableOptionNames(yargsInstance, includeShortAliases) {
   const availableOptions = yargsInstance.getOptions();
   const allOptions = new Set();
+  const rawHiddenOptions = availableOptions.hiddenOptions || [];
+  const hiddenOptionNames = Array.isArray(rawHiddenOptions) ? rawHiddenOptions : Object.keys(rawHiddenOptions);
+  const hiddenOptions = new Set(hiddenOptionNames.map(normalizeOptionName));
+
+  const addOption = option => {
+    const normalized = normalizeOptionName(option);
+    if (!normalized || hiddenOptions.has(normalized)) return;
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(normalized)) return;
+    if (!includeShortAliases && normalized.length === 1) return;
+    allOptions.add(normalized);
+  };
 
-  // Collect all option names (both long form and aliases)
   if (availableOptions.key) {
-    // Ensure it's an array before iterating
     const keys = Array.isArray(availableOptions.key) ? availableOptions.key : Object.keys(availableOptions.key || {});
-    keys.forEach(opt => {
-      allOptions.add(opt);
-    });
+    keys.forEach(addOption);
   }
 
-  // Collect aliases
   if (availableOptions.alias) {
     Object.entries(availableOptions.alias).forEach(([key, aliases]) => {
-      allOptions.add(key);
+      addOption(key);
       if (Array.isArray(aliases)) {
-        aliases.forEach(alias => allOptions.add(alias));
+        aliases.forEach(addOption);
       } else if (aliases) {
-        // If it's not an array but exists, add it as a single alias
-        allOptions.add(String(aliases));
+        addOption(aliases);
       }
     });
   }
 
-  // Calculate distance for each option
+  return allOptions;
+}
+
+/**
+ * Find similar option names based on Levenshtein distance
+ *
+ * @param {string} unknownOption - The option name that was not recognized (e.g., "branch")
+ * @param {Object} yargsInstance - The yargs instance with defined options
+ * @param {number} maxSuggestions - Maximum number of suggestions to return (default: 5)
+ * @param {number} distanceThreshold - Maximum distance to consider for suggestions (default: 5)
+ * @returns {string[]} - Array of suggested option names, sorted by similarity
+ */
+export function findSimilarOptions(unknownOption, yargsInstance, maxSuggestions = 5, distanceThreshold = 5) {
+  const cleanUnknown = normalizeOptionName(unknownOption);
+  const compactUnknown = compactOptionName(unknownOption);
+  const includeShortAliases = cleanUnknown.length === 1;
+  const allOptions = getAvailableOptionNames(yargsInstance, includeShortAliases);
+
   const distances = [];
   allOptions.forEach(option => {
-    const distance = calculateLevenshteinDistance(cleanUnknown, option);
-    if (distance <= distanceThreshold) {
-      // Calculate bonus score for substring matches
-      // If the unknown option is a substring of the valid option, it's likely what the user meant
-      // Check both directions: is unknown a substring of option, or is option a substring of unknown
-      const unknownInOption = option.includes(cleanUnknown);
-      const optionInUnknown = cleanUnknown.includes(option);
-
-      // Strong bonus for when user typed a word that appears in the option name
-      // e.g., "branch" appears in "base-branch"
-      const substringBonus = unknownInOption ? -10 : optionInUnknown ? -5 : 0;
+    const distance = Math.min(calculateLevenshteinDistance(cleanUnknown, option), calculateLevenshteinDistance(compactUnknown, compactOptionName(option)));
+    const unknownInOption = option.includes(cleanUnknown) || compactOptionName(option).includes(compactUnknown);
+    const optionInUnknown = cleanUnknown.includes(option) || compactUnknown.includes(compactOptionName(option));
 
-      // Also prioritize options with similar length (user likely tried to type the full name)
+    if (distance <= distanceThreshold || unknownInOption || optionInUnknown) {
+      const substringBonus = unknownInOption ? -10 : optionInUnknown ? -5 : 0;
       const lengthDiff = Math.abs(option.length - cleanUnknown.length);
       const lengthBonus = lengthDiff < 3 ? -1 : 0;
 
       distances.push({
         option,
         distance,
+        lengthDiff,
         effectiveDistance: distance + substringBonus + lengthBonus,
       });
     }
   });
 
-  // Sort by effective distance (closest first), then by actual distance
   return distances
     .sort((a, b) => {
       if (a.effectiveDistance !== b.effectiveDistance) {
         return a.effectiveDistance - b.effectiveDistance;
       }
-      return a.distance - b.distance;
+      if (a.distance !== b.distance) {
+        return a.distance - b.distance;
+      }
+      if (a.lengthDiff !== b.lengthDiff) {
+        return a.lengthDiff - b.lengthDiff;
+      }
+      return a.option.localeCompare(b.option);
     })
     .slice(0, maxSuggestions)
     .map(item => item.option);
@@ -133,17 +151,17 @@ export function formatSuggestions(suggestions) {
     return '';
   }
 
-  if (suggestions.length === 1) {
-    return `\n\nDid you mean --${suggestions[0]}?`;
-  }
-
-  // For multiple suggestions, format them nicely
   const formattedOptions = suggestions.map(opt => {
     // If it's a single character, show as -x, otherwise --option-name
     return opt.length === 1 ? `-${opt}` : `--${opt}`;
   });
+  const [primarySuggestion, ...alternatives] = formattedOptions;
 
-  return `\n\nDid you mean one of these?\n${formattedOptions.map(opt => `  • ${opt}`).join('\n')}`;
+  if (alternatives.length === 0) {
+    return `\n\nDid you mean \`${primarySuggestion}\` option?`;
+  }
+
+  return `\n\nDid you mean \`${primarySuggestion}\` option?\n\nOther close matches:\n${alternatives.map(opt => `  • \`${opt}\``).join('\n')}`;
 }
 
 /**
@@ -300,9 +318,13 @@ export function detectMalformedFlags(args) {
  * @returns {string} - Enhanced error message with suggestions
  */
 export function enhanceErrorMessage(originalError, yargsInstance) {
+  if (/Did you mean/i.test(originalError)) {
+    return originalError;
+  }
+
   // Extract the unknown option name from the error message
   // Typical format: "Unknown argument: branch" or "Unknown arguments: branch, test"
-  const unknownMatch = originalError.match(/Unknown arguments?:\s*(.+?)(?:\s|$)/i);
+  const unknownMatch = originalError.match(/Unknown arguments?:\s*([^\n]+)/i);
 
   if (!unknownMatch) {
     return originalError;
@@ -324,3 +346,23 @@ export function enhanceErrorMessage(originalError, yargsInstance) {
 
   return enhancedMessage;
 }
+
+export function enhanceUnknownArgumentError(error, yargsInstance) {
+  if (!error || error._enhanced || !yargsInstance || !/Unknown arguments?/i.test(error.message || '')) {
+    return error;
+  }
+
+  const enhancedMessage = enhanceErrorMessage(error.message, yargsInstance);
+  if (enhancedMessage === error.message) {
+    return error;
+  }
+
+  const enhancedError = new Error(enhancedMessage);
+  enhancedError.name = error.name;
+  enhancedError.cause = error;
+  for (const key of Object.keys(error)) {
+    enhancedError[key] = error[key];
+  }
+  enhancedError._enhanced = true;
+  return enhancedError;
+}

package/src/telegram-bot.mjs

@@ -25,6 +25,7 @@ await loadLenvConfig({ override: true, quiet: true });
 const yargs = getLinoYargsFactory();
 const { createYargsConfig: createSolveYargsConfig, detectMalformedFlags } = await import('./solve.config.lib.mjs');
 const { createYargsConfig: createHiveYargsConfig } = await import('./hive.config.lib.mjs');
+const { enhanceUnknownArgumentError } = await import('./option-suggestions.lib.mjs');
 const { validateBranchInArgs } = await import('./solve.branch.lib.mjs');
 const { extractIsolationFromArgs, isValidPerCommandIsolation } = await import('./telegram-isolation.lib.mjs');
 
@@ -229,7 +230,8 @@ if (solveEnabled && solveOverrides.length > 0) {
       process.stderr.write = originalStderrWrite;
     }
   } catch (error) {
-    console.error(`❌ Invalid solve-overrides: ${error.message || String(error)}`);
+    const enhancedError = enhanceUnknownArgumentError(error, createSolveYargsConfig(yargs()));
+    console.error(`❌ Invalid solve-overrides: ${enhancedError.message || String(enhancedError)}`);
     console.error(`   Overrides: ${solveOverrides.join(' ')}`);
     process.exit(1);
   }
@@ -275,7 +277,8 @@ if (hiveEnabled && hiveOverrides.length > 0) {
       process.stderr.write = originalStderrWrite;
     }
   } catch (error) {
-    console.error(`❌ Invalid hive-overrides: ${error.message || String(error)}`);
+    const enhancedError = enhanceUnknownArgumentError(error, createHiveYargsConfig(yargs()));
+    console.error(`❌ Invalid hive-overrides: ${enhancedError.message || String(enhancedError)}`);
     console.error(`   Overrides: ${hiveOverrides.join(' ')}`);
     process.exit(1);
   }

package/src/telegram-solve-command.lib.mjs

@@ -8,6 +8,8 @@
  * @see https://github.com/link-assistant/hive-mind/issues/1618
  */
 
+import { enhanceUnknownArgumentError } from './option-suggestions.lib.mjs';
+
 export const TOOL_SOLVE_COMMAND_ALIASES = Object.freeze({
   claude: 'claude',
   codex: 'codex',
@@ -89,8 +91,9 @@ export async function parseArgsWithYargs(args, yargsFactory, createYargsConfig)
     else if (typeof callback === 'function') callback();
     return true;
   };
+  let parser = null;
   try {
-    const parser = createYargsConfig(yargsFactory());
+    parser = createYargsConfig(yargsFactory());
     parser
       .exitProcess(false)
       .showHelpOnFail(false)
@@ -98,6 +101,8 @@ export async function parseArgsWithYargs(args, yargsFactory, createYargsConfig)
         throw err || new Error(msg || 'Invalid arguments');
       });
     return await parser.parse(args);
+  } catch (error) {
+    throw enhanceUnknownArgumentError(error, parser);
   } finally {
     process.stderr.write = originalStderrWrite;
   }

package/src/telegram-task-command.lib.mjs

@@ -1,10 +1,12 @@
 import { buildUserMention } from './buildUserMention.lib.mjs';
 import { validateModelName } from './models/index.mjs';
+import { getLinoYargsFactory } from './cli-arguments.lib.mjs';
+import { createYargsConfig as createTaskYargsConfig } from './task.config.lib.mjs';
 import { createTaskIssue, parseTaskIssueCreationInput, resolveTaskIssueCreationInput } from './task.issue-creation.lib.mjs';
 import { parseTaskIssueUrl } from './task.split.lib.mjs';
 import { escapeMarkdown } from './telegram-markdown.lib.mjs';
 import { extractIsolationFromArgs, isValidPerCommandIsolation } from './telegram-isolation.lib.mjs';
-import { moveArgumentToFront, parseCommandArgs } from './telegram-solve-command.lib.mjs';
+import { moveArgumentToFront, parseArgsWithYargs, parseCommandArgs } from './telegram-solve-command.lib.mjs';
 import { formatStartingWorkSessionMessage } from './work-session-formatting.lib.mjs';
 
 export const TASK_COMMAND_NAMES = Object.freeze(['task', 'split']);
@@ -187,6 +189,13 @@ export function registerTaskCommands(bot, options) {
       return;
     }
 
+    try {
+      await parseArgsWithYargs(filteredArgs, getLinoYargsFactory(), createTaskYargsConfig);
+    } catch (error) {
+      await safeReply(ctx, `❌ Invalid options: ${escapeMarkdown(error.message || String(error))}\n\nUse /help to see available options`, { reply_to_message_id: ctx.message.message_id });
+      return;
+    }
+
     const modelError = validateTaskModel(filteredArgs);
     if (modelError) {
       await safeReply(ctx, `❌ ${escapeMarkdown(modelError)}`, { reply_to_message_id: ctx.message.message_id });