@link-assistant/hive-mind 1.50.8 → 1.50.9

package/src/solve.bootstrap.lib.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+/**
+ * Handle lightweight early-exit paths before solve loads its full dependency graph.
+ *
+ * @param {string[]} earlyArgs - Raw CLI args without the node/script prefix
+ * @returns {Promise<void>}
+ */
+export async function handleSolveEarlyExit(earlyArgs) {
+  if (earlyArgs.includes('--version')) {
+    const { getVersion } = await import('./version.lib.mjs');
+    try {
+      console.log(await getVersion());
+    } catch {
+      console.error('Error: Unable to determine version');
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  if (earlyArgs.includes('--help') || earlyArgs.includes('-h')) {
+    // Load minimal modules needed for help output.
+    const { use } = eval(await (await fetch('https://unpkg.com/use-m/use.js')).text());
+    globalThis.use = use;
+    const { initializeConfig, createYargsConfig } = await import('./solve.config.lib.mjs');
+    const { yargs, hideBin } = await initializeConfig(use);
+    const rawArgs = hideBin(process.argv);
+    const argsWithoutHelp = rawArgs.filter(arg => arg !== '--help' && arg !== '-h');
+    createYargsConfig(yargs(argsWithoutHelp)).showHelp();
+    process.exit(0);
+  }
+
+  if (earlyArgs.length === 0) {
+    console.error('Usage: solve.mjs <issue-url> [options]');
+    console.error('\nError: Missing required github issue or pull request URL');
+    console.error('\nRun "solve.mjs --help" for more information');
+    process.exit(1);
+  }
+}

package/src/solve.config.lib.mjs

@@ -229,13 +229,13 @@ export const SOLVE_OPTION_DEFINITIONS = {
   },
   think: {
     type: 'string',
-    description: 'Thinking level for Claude. Translated to --thinking-budget for Claude Code >= 2.1.12 (off=0, low=~8000, medium=~16000, high=~24000, max=31999). For older versions, uses thinking keywords.',
+    description: 'Thinking level hint. For Claude, translated to --thinking-budget for Claude Code >= 2.1.12 (off=0, low=~8000, medium=~16000, high=~24000, max=31999). For Codex, mapped to reasoning effort (off=none, low=low, medium=medium, high=high, max=xhigh).',
     choices: ['off', 'low', 'medium', 'high', 'max'],
     default: undefined,
   },
   'thinking-budget': {
     type: 'number',
-    description: 'Thinking token budget for Claude Code (0-31999). Controls MAX_THINKING_TOKENS. Default: 0 (thinking disabled). For older Claude Code versions, translated back to --think level.',
+    description: 'Thinking token budget. For Claude Code, controls MAX_THINKING_TOKENS (0-31999 by default). For Codex, enables finer reasoning-effort mapping including minimal/low/medium/high/xhigh.',
     default: undefined,
   },
   'thinking-budget-claude-minimum-version': {
@@ -250,7 +250,7 @@ export const SOLVE_OPTION_DEFINITIONS = {
   },
   'prompt-plan-sub-agent': {
     type: 'boolean',
-    description: 'Encourage AI to use Plan sub-agent for initial planning (only works with --tool claude)',
+    description: 'Encourage AI to use a planning sub-agent or planning workflow for initial planning. Supported for --tool claude and --tool codex.',
     default: false,
   },
   'base-branch': {
@@ -326,27 +326,27 @@ export const SOLVE_OPTION_DEFINITIONS = {
   },
   'interactive-mode': {
     type: 'boolean',
-    description: '[EXPERIMENTAL] Post Claude output as PR comments in real-time. Only supported for --tool claude.',
+    description: '[EXPERIMENTAL] Post tool output as PR comments in real-time. Supported for --tool claude and --tool codex.',
     default: false,
   },
   'prompt-explore-sub-agent': {
     type: 'boolean',
-    description: 'Encourage Claude to use Explore sub-agent for codebase exploration. Only supported for --tool claude.',
+    description: 'Encourage AI to use Explore-style sub-agent workflow for codebase exploration. Supported for --tool claude and --tool codex.',
     default: false,
   },
   'prompt-general-purpose-sub-agent': {
     type: 'boolean',
-    description: 'Prompt AI to use general-purpose sub agents for processing large tasks with multiple files/folders. Only supported for --tool claude.',
+    description: 'Prompt AI to use general-purpose sub agents for processing large tasks with multiple files/folders. Supported for --tool claude and --tool codex.',
     default: false,
   },
   'tokens-budget-stats': {
     type: 'boolean',
-    description: '[EXPERIMENTAL] Show detailed token budget statistics including context window usage and ratios. Only supported for --tool claude.',
+    description: '[EXPERIMENTAL] Show detailed token budget statistics including context window usage and ratios. Supported for --tool claude, --tool codex, and any tool that returns detailed token usage.',
     default: false,
   },
   'prompt-issue-reporting': {
     type: 'boolean',
-    description: 'Enable automatic issue creation for spotted bugs/errors not related to main task. Issues will include reproducible examples, workarounds, and fix suggestions. Works for both current and third-party repositories. Only supported for --tool claude.',
+    description: 'Enable automatic issue creation for spotted bugs/errors not related to main task. Issues will include reproducible examples, workarounds, and fix suggestions. Works for both current and third-party repositories. Supported for --tool claude and --tool codex.',
     default: false,
   },
   'prompt-architecture-care': {
@@ -356,12 +356,12 @@ export const SOLVE_OPTION_DEFINITIONS = {
   },
   'prompt-case-studies': {
     type: 'boolean',
-    description: 'Create comprehensive case study documentation for the issue including logs, analysis, timeline, root cause investigation, and proposed solutions. Organizes findings into ./docs/case-studies/issue-{id}/ directory. Only supported for --tool claude.',
+    description: 'Create comprehensive case study documentation for the issue including logs, analysis, timeline, root cause investigation, and proposed solutions. Organizes findings into ./docs/case-studies/issue-{id}/ directory. Supported for --tool claude and --tool codex.',
     default: false,
   },
   'prompt-playwright-mcp': {
     type: 'boolean',
-    description: 'Enable Playwright MCP browser automation hints in system prompt (enabled by default, only takes effect if Playwright MCP is installed). Use --no-prompt-playwright-mcp to disable. Only supported for --tool claude.',
+    description: 'Enable Playwright MCP browser automation hints in system prompt (enabled by default, only takes effect if Playwright MCP is installed). Use --no-prompt-playwright-mcp to disable. Supported for --tool claude and --tool codex.',
     default: true,
   },
   'prompt-check-sibling-pull-requests': {
@@ -391,7 +391,7 @@ export const SOLVE_OPTION_DEFINITIONS = {
   },
   'prompt-subagents-via-agent-commander': {
     type: 'boolean',
-    description: 'Guide Claude to use agent-commander CLI (start-agent) instead of native Task tool for subagent delegation. Allows using any supported agent type (claude, opencode, codex, agent) with unified API. Only works with --tool claude and requires agent-commander to be installed.',
+    description: 'Guide AI to use agent-commander CLI (start-agent) instead of native tool-specific delegation for subagent work. Allows using any supported agent type (claude, opencode, codex, agent) with a unified API. Supported for --tool claude and --tool codex and requires agent-commander to be installed.',
     default: false,
   },
   'auto-init-repository': {

package/src/solve.mjs

@@ -1,39 +1,10 @@
 #!/usr/bin/env node
 // Import Sentry instrumentation first (must be before other imports)
 import './instrument.mjs';
-// Early exit paths - handle these before loading all modules to speed up testing
 const earlyArgs = process.argv.slice(2);
-if (earlyArgs.includes('--version')) {
-  const { getVersion } = await import('./version.lib.mjs');
-  try {
-    const version = await getVersion();
-    console.log(version);
-  } catch {
-    console.error('Error: Unable to determine version');
-    process.exit(1);
-  }
-  process.exit(0);
-}
-if (earlyArgs.includes('--help') || earlyArgs.includes('-h')) {
-  // Load minimal modules needed for help
-  const { use } = eval(await (await fetch('https://unpkg.com/use-m/use.js')).text());
-  globalThis.use = use;
-  const config = await import('./solve.config.lib.mjs');
-  const { initializeConfig, createYargsConfig } = config;
-  const { yargs, hideBin } = await initializeConfig(use);
-  const rawArgs = hideBin(process.argv);
-  // Filter out help flags to avoid duplicate display
-  const argsWithoutHelp = rawArgs.filter(arg => arg !== '--help' && arg !== '-h');
-  createYargsConfig(yargs(argsWithoutHelp)).showHelp();
-  process.exit(0);
-}
-if (earlyArgs.length === 0) {
-  console.error('Usage: solve.mjs <issue-url> [options]');
-  console.error('\nError: Missing required github issue or pull request URL');
-  console.error('\nRun "solve.mjs --help" for more information');
-  process.exit(1);
-}
-// Now load all modules for normal operation
+const { handleSolveEarlyExit } = await import('./solve.bootstrap.lib.mjs');
+await handleSolveEarlyExit(earlyArgs);
+
 const { use } = eval(await (await fetch('https://unpkg.com/use-m/use.js')).text());
 globalThis.use = use;
 const { $ } = await use('command-stream');
@@ -58,9 +29,9 @@ const { processAutoContinueForIssue } = autoContinue;
 const repository = await import('./solve.repository.lib.mjs');
 const { setupTempDirectory, cleanupTempDirectory } = repository;
 const results = await import('./solve.results.lib.mjs');
-const { cleanupClaudeFile, showSessionSummary, verifyResults, buildClaudeResumeCommand, checkForAiCreatedComments, attachSolutionSummary } = results;
+const { cleanupClaudeFile, showSessionSummary, verifyResults, buildClaudeResumeCommand, buildSolveResumeCommand, checkForAiCreatedComments, attachSolutionSummary } = results;
 const claudeLib = await import('./claude.lib.mjs');
-const { executeClaude } = claudeLib;
+const { executeClaude, checkPlaywrightMcpAvailability } = claudeLib;
 
 const githubLinking = await import('./github-linking.lib.mjs');
 const { extractLinkedIssueNumber } = githubLinking;
@@ -769,9 +740,21 @@ try {
     });
   } else if (argv.tool === 'codex') {
     const codexLib = await import('./codex.lib.mjs');
-    const { executeCodex } = codexLib;
+    const { executeCodex, checkPlaywrightMcpAvailability } = codexLib;
     const codexPath = process.env.CODEX_PATH || 'codex';
 
+    if (argv.promptPlaywrightMcp) {
+      const playwrightMcpAvailable = await checkPlaywrightMcpAvailability();
+      if (playwrightMcpAvailable) {
+        await log('🎭 Playwright MCP detected - enabling browser automation hints', { verbose: true });
+      } else {
+        await log('ℹ️  Playwright MCP not detected - browser automation hints will be disabled', { verbose: true });
+        argv.promptPlaywrightMcp = false;
+      }
+    } else {
+      await log('ℹ️  Playwright MCP explicitly disabled via --no-prompt-playwright-mcp', { verbose: true });
+    }
+
     toolResult = await executeCodex({
       issueUrl,
       issueNumber,
@@ -831,7 +814,6 @@ try {
     if (argv.tool === 'claude' || !argv.tool) {
       // If flag is true (default), check if Playwright MCP is actually available
       if (argv.promptPlaywrightMcp) {
-        const { checkPlaywrightMcpAvailability } = claudeLib;
         const playwrightMcpAvailable = await checkPlaywrightMcpAvailability();
         if (playwrightMcpAvailable) {
           await log('🎭 Playwright MCP detected - enabling browser automation hints', { verbose: true });
@@ -927,6 +909,12 @@ try {
           await log('');
           await log(`   ${claudeResumeCmd}`);
           await log('');
+        } else if (argv.url) {
+          const solveResumeCmd = buildSolveResumeCommand({ issueUrl: argv.url, sessionId, tool: toolForResume, model: argv.model, tempDir });
+          await log(`💡 To continue this ${toolForResume} session with solve:`);
+          await log('');
+          await log(`   ${solveResumeCmd}`);
+          await log('');
         }
       }
 
@@ -936,7 +924,7 @@ try {
         try {
           // Build Claude CLI resume command
           const tool = argv.tool || 'claude';
-          const resumeCommand = tool === 'claude' ? buildClaudeResumeCommand({ tempDir, sessionId, model: argv.model }) : null;
+          const resumeCommand = tool === 'claude' ? buildClaudeResumeCommand({ tempDir, sessionId, model: argv.model }) : sessionId ? buildSolveResumeCommand({ issueUrl: argv.url, sessionId, tool, model: argv.model, tempDir }) : null;
           const logUploadSuccess = await attachLogToGitHub({
             logFile: getLogFile(),
             targetType: 'pr',
@@ -974,7 +962,7 @@ try {
           const resetTime = global.limitResetTime;
           // Build Claude CLI resume command
           const tool = argv.tool || 'claude';
-          const resumeCmd = tool === 'claude' ? buildClaudeResumeCommand({ tempDir, sessionId, model: argv.model }) : null;
+          const resumeCmd = tool === 'claude' ? buildClaudeResumeCommand({ tempDir, sessionId, model: argv.model }) : sessionId ? buildSolveResumeCommand({ issueUrl: argv.url, sessionId, tool, model: argv.model, tempDir }) : null;
           const resumeSection = resumeCmd ? `To resume after the limit resets, use:\n\`\`\`bash\n${resumeCmd}\n\`\`\`` : `Session ID: \`${sessionId}\``;
           // Format the reset time with relative time and UTC conversion if available
           const timezone = global.limitTimezone || null;
@@ -1002,7 +990,7 @@ try {
           try {
             // Build Claude CLI resume command (only for logging, not shown to users when auto-resume is enabled)
             const tool = argv.tool || 'claude';
-            const resumeCommand = tool === 'claude' ? buildClaudeResumeCommand({ tempDir, sessionId, model: argv.model }) : null;
+            const resumeCommand = tool === 'claude' ? buildClaudeResumeCommand({ tempDir, sessionId, model: argv.model }) : sessionId ? buildSolveResumeCommand({ issueUrl: argv.url, sessionId, tool, model: argv.model, tempDir }) : null;
             const logUploadSuccess = await attachLogToGitHub({
               logFile: getLogFile(),
               targetType: 'pr',
@@ -1090,6 +1078,13 @@ try {
       await log('');
       await log(`   ${claudeResumeCmd}`);
       await log('');
+    } else if (sessionId && argv.url) {
+      const solveResumeCmd = buildSolveResumeCommand({ issueUrl: argv.url, sessionId, tool: toolForFailure, model: argv.model, tempDir });
+      await log('');
+      await log(`💡 To continue this ${toolForFailure} session with solve:`);
+      await log('');
+      await log(`   ${solveResumeCmd}`);
+      await log('');
     }
 
     // Attach failure logs before exiting (Issues #1212, #1462: fall back to issue if no PR)
@@ -1104,7 +1099,7 @@ try {
       try {
         // Build Claude CLI resume command
         const tool = argv.tool || 'claude';
-        const resumeCommand = sessionId && tool === 'claude' ? buildClaudeResumeCommand({ tempDir, sessionId, model: argv.model }) : null;
+        const resumeCommand = sessionId ? (tool === 'claude' ? buildClaudeResumeCommand({ tempDir, sessionId, model: argv.model }) : buildSolveResumeCommand({ issueUrl: argv.url, sessionId, tool, model: argv.model, tempDir })) : null;
         const logUploadSuccess = await attachLogToGitHub({
           logFile: getLogFile(),
           targetType: logTargetType,

package/src/solve.progress-monitoring.lib.mjs

@@ -358,8 +358,8 @@ export const createProgressMonitor = ({ owner, repo, prNumber, $, log, verbose =
   };
 
   /**
-   * Process a Claude CLI stream event, detecting TodoWrite tool calls
-   * and updating progress automatically. Call this for each parsed NDJSON event.
+   * Process a tool stream event, detecting Claude TodoWrite or Codex todo_list
+   * updates and updating progress automatically.
    *
    * @param {Object} data - Parsed JSON event from Claude CLI stream
    * @param {boolean} force - Force update even if within rate limit interval
@@ -381,6 +381,14 @@ export const createProgressMonitor = ({ owner, repo, prNumber, $, log, verbose =
     if (data.type === 'user' && data.tool_use_result?.newTodos) {
       updated = await updateProgress(data.tool_use_result.newTodos, force);
     }
+    // Pattern 3: Codex item event with todo_list payload
+    if ((data.type === 'item.started' || data.type === 'item.updated' || data.type === 'item.completed') && data.item?.type === 'todo_list' && Array.isArray(data.item.items)) {
+      const todos = data.item.items.map(todo => ({
+        status: todo?.completed ? 'completed' : 'pending',
+        content: todo?.text || '',
+      }));
+      updated = await updateProgress(todos, force);
+    }
     return updated;
   };
 

package/src/solve.restart-shared.lib.mjs

@@ -208,9 +208,21 @@ export const executeToolIteration = async params => {
   } else if (argv.tool === 'codex') {
     // Use Codex
     const codexExecLib = await import('./codex.lib.mjs');
-    const { executeCodex } = codexExecLib;
+    const { executeCodex, checkPlaywrightMcpAvailability } = codexExecLib;
     const codexPath = argv.codexPath || 'codex';
 
+    if (argv.promptPlaywrightMcp) {
+      const playwrightMcpAvailable = await checkPlaywrightMcpAvailability();
+      if (playwrightMcpAvailable) {
+        await log('🎭 Playwright MCP detected - enabling browser automation hints', { verbose: true });
+      } else {
+        await log('ℹ️  Playwright MCP not detected - browser automation hints will be disabled', { verbose: true });
+        argv.promptPlaywrightMcp = false;
+      }
+    } else {
+      await log('ℹ️  Playwright MCP explicitly disabled via --no-prompt-playwright-mcp', { verbose: true });
+    }
+
     toolResult = await executeCodex({
       issueUrl,
       issueNumber,

package/src/solve.results.lib.mjs

@@ -37,6 +37,41 @@ const { autoContinueWhenLimitResets } = autoContinue;
 const claudeCommandBuilder = await import('./claude.command-builder.lib.mjs');
 export const { buildClaudeResumeCommand, buildClaudeInitialCommand } = claudeCommandBuilder;
 
+/**
+ * Build a solve.mjs resume command for tools that do not have a first-party interactive
+ * resume CLI flow like Claude Code. This keeps the invocation within hive-mind so the
+ * original tool selection and working directory can be preserved.
+ *
+ * @param {Object} options
+ * @param {string} options.issueUrl - The issue URL passed to solve.mjs
+ * @param {string} options.sessionId - The session ID to resume
+ * @param {string|null} [options.tool] - Tool name (codex, opencode, agent)
+ * @param {string|null} [options.model] - Model name to preserve
+ * @param {string|null} [options.tempDir] - Working directory to preserve
+ * @param {string} [options.nodePath] - Node binary path
+ * @param {string} [options.scriptPath] - solve.mjs path
+ * @returns {string}
+ */
+export const buildSolveResumeCommand = ({ issueUrl, sessionId, tool = null, model = null, tempDir = null, nodePath = process.argv[0], scriptPath = process.argv[1] }) => {
+  const shellQuote = value => `"${String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+
+  const args = [shellQuote(scriptPath), shellQuote(issueUrl), '--resume', shellQuote(sessionId)];
+
+  if (tool && tool !== 'claude') {
+    args.push('--tool', shellQuote(tool));
+  }
+
+  if (model) {
+    args.push('--model', shellQuote(model));
+  }
+
+  if (tempDir) {
+    args.push('--working-directory', shellQuote(tempDir));
+  }
+
+  return `${shellQuote(nodePath)} ${args.join(' ')}`;
+};
+
 // Import error handling functions
 // const errorHandlers = await import('./solve.error-handlers.lib.mjs'); // Not currently used
 // Import Sentry integration
@@ -444,12 +479,8 @@ export const showSessionSummary = async (sessionId, limitReached, argv, issueUrl
     const absoluteLogPath = path.resolve(getLogFile());
     await log(`✅ Complete log file: ${absoluteLogPath}`);
 
-    // Show claude resume command only for --tool claude (or default)
-    // This allows users to investigate, resume, see context, and more
-    // Uses the (cd ... && claude --resume ...) pattern for a fully copyable, executable command
     const tool = argv.tool || 'claude';
     if (tool === 'claude') {
-      // Build the Claude CLI resume command using the command builder
       const claudeResumeCmd = buildClaudeResumeCommand({ tempDir, sessionId, model: argv.model });
 
       await log('');
@@ -457,6 +488,13 @@ export const showSessionSummary = async (sessionId, limitReached, argv, issueUrl
       await log('');
       await log(`   ${claudeResumeCmd}`);
       await log('');
+    } else if (issueUrl) {
+      const solveResumeCmd = buildSolveResumeCommand({ issueUrl, sessionId, tool, model: argv.model, tempDir });
+      await log('');
+      await log(`💡 To continue this ${tool} session with solve:`);
+      await log('');
+      await log(`   ${solveResumeCmd}`);
+      await log('');
     }
 
     if (limitReached) {
@@ -472,7 +510,7 @@ export const showSessionSummary = async (sessionId, limitReached, argv, issueUrl
           await log(`\n⏰ Limit resets at: ${global.limitResetTime}`);
         }
 
-        await log('\n💡 After the limit resets, resume using the Claude command above.');
+        await log('\n💡 After the limit resets, resume using the command above.');
 
         if (argv.autoCleanup !== false) {
           await log('');

package/src/solve.validation.lib.mjs

@@ -306,7 +306,7 @@ export const performSystemChecks = async (minDiskSpace = 2048, skipToolConnectio
     } else if (argv.tool === 'codex') {
       // Validate Codex connection
       const codexLib = await import('./codex.lib.mjs');
-      isToolConnected = await codexLib.validateCodexConnection(model);
+      isToolConnected = await codexLib.validateCodexConnection(model, argv.verbose);
       if (!isToolConnected) {
         await log('❌ Cannot proceed without Codex connection', { level: 'error' });
         return false;

package/src/telegram-bot.mjs

@@ -41,7 +41,7 @@ const { parseGitHubUrl, validateGitHubEntityExistence } = await import('./github
 const { validateModelName, buildModelOptionDescription } = await import('./models/index.mjs');
 const { validateBranchInArgs } = await import('./solve.branch.lib.mjs');
 const { extractIsolationFromArgs, isValidPerCommandIsolation, resolveIsolation, createIsolationAwareQueueCallback } = await import('./telegram-isolation.lib.mjs');
-const { formatUsageMessage, getAllCachedLimits } = await import('./limits.lib.mjs');
+const { formatUsageMessage, formatCodexLimitsSection, getAllCachedLimits } = await import('./limits.lib.mjs');
 const { getVersionInfo, formatVersionMessage } = await import('./version-info.lib.mjs');
 const { escapeMarkdown, escapeMarkdownV2, cleanNonPrintableChars, makeSpecialCharsVisible } = await import('./telegram-markdown.lib.mjs');
 const { getSolveQueue, createQueueExecuteCallback } = await import('./telegram-solve-queue.lib.mjs');
@@ -758,9 +758,11 @@ bot.command('limits', async ctx => {
 
   // Format message with usage limits and queue status (issues #1343, #1267)
   const claudeError = limits.claude.success ? null : limits.claude.error;
+  const codexError = limits.codex.success ? null : limits.codex.error;
   const solveQueue = getSolveQueue({ verbose: VERBOSE });
   const queueStatus = await solveQueue.formatStatus();
-  const message = '📊 *Usage Limits*\n\n' + formatUsageMessage(limits.claude.success ? limits.claude.usage : null, limits.disk.success ? limits.disk.diskSpace : null, limits.github.success ? limits.github.githubRateLimit : null, limits.cpu.success ? limits.cpu.cpuLoad : null, limits.memory.success ? limits.memory.memory : null, claudeError, [queueStatus]);
+  const codexSection = formatCodexLimitsSection(limits.codex.success ? limits.codex : null, codexError);
+  const message = '📊 *Usage Limits*\n\n' + formatUsageMessage(limits.claude.success ? limits.claude.usage : null, limits.disk.success ? limits.disk.diskSpace : null, limits.github.success ? limits.github.githubRateLimit : null, limits.cpu.success ? limits.cpu.cpuLoad : null, limits.memory.success ? limits.memory.memory : null, claudeError, [codexSection, queueStatus]);
   await ctx.telegram.editMessageText(fetchingMessage.chat.id, fetchingMessage.message_id, undefined, message, { parse_mode: 'Markdown' });
 });
 bot.command('version', async ctx => {

package/src/telegram-solve-queue.helpers.lib.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execAsync = promisify(exec);
+
+/**
+ * Count running processes by name.
+ * @param {string} processName - Process name to search for (e.g., 'claude', 'agent')
+ * @param {boolean} verbose - Whether to log verbose output
+ * @returns {Promise<{count: number, processes: string[]}>}
+ */
+export async function getRunningProcesses(processName, verbose = false) {
+  try {
+    const { stdout } = await execAsync(`pgrep -l -x ${processName} 2>/dev/null || true`);
+    const lines = stdout
+      .trim()
+      .split('\n')
+      .filter(line => line.trim());
+
+    const processes = lines
+      .map(line => {
+        const parts = line.trim().split(/\s+/);
+        return {
+          pid: parts[0],
+          name: parts.slice(1).join(' ') || processName,
+        };
+      })
+      .filter(p => p.pid);
+
+    if (verbose) {
+      console.log(`[VERBOSE] /solve_queue found ${processes.length} running ${processName} processes`);
+      if (processes.length > 0) {
+        console.log(`[VERBOSE] /solve_queue processes: ${JSON.stringify(processes)}`);
+      }
+    }
+
+    return {
+      count: processes.length,
+      processes: processes.map(p => `${p.pid}:${p.name}`),
+    };
+  } catch (error) {
+    if (verbose) {
+      console.error(`[VERBOSE] /solve_queue error counting ${processName} processes:`, error.message);
+    }
+    return { count: 0, processes: [] };
+  }
+}
+
+/**
+ * Count running claude processes.
+ * @param {boolean} verbose - Whether to log verbose output
+ * @returns {Promise<{count: number, processes: string[]}>}
+ */
+export async function getRunningClaudeProcesses(verbose = false) {
+  return getRunningProcesses('claude', verbose);
+}
+
+/**
+ * Count running agent processes.
+ * @param {boolean} verbose - Whether to log verbose output
+ * @returns {Promise<{count: number, processes: string[]}>}
+ */
+export async function getRunningAgentProcesses(verbose = false) {
+  return getRunningProcesses('agent', verbose);
+}
+
+/**
+ * Count running codex processes.
+ * @param {boolean} verbose - Whether to log verbose output
+ * @returns {Promise<{count: number, processes: string[]}>}
+ */
+export async function getRunningCodexProcesses(verbose = false) {
+  return getRunningProcesses('codex', verbose);
+}
+
+/**
+ * Format a threshold as percentage for display.
+ * @param {number} ratio - Ratio (0.0 - 1.0)
+ * @returns {string} Formatted percentage
+ */
+export function formatThresholdPercent(ratio) {
+  return `${Math.round(ratio * 100)}%`;
+}
+
+/**
+ * Format milliseconds into human-readable duration.
+ * Shows days, hours, minutes, and seconds as appropriate.
+ * Examples: "5h 43m 23s", "2m 15s", "45s", "1d 3h 12m 5s"
+ *
+ * @param {number} ms - Duration in milliseconds
+ * @returns {string} Human-readable duration
+ * @see https://github.com/link-assistant/hive-mind/issues/1267
+ */
+export function formatDuration(ms) {
+  if (ms < 0) ms = 0;
+
+  const totalSeconds = Math.floor(ms / 1000);
+  const days = Math.floor(totalSeconds / 86400);
+  const hours = Math.floor((totalSeconds % 86400) / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+
+  const parts = [];
+  if (days > 0) parts.push(`${days}d`);
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+  if (seconds > 0 || parts.length === 0) parts.push(`${seconds}s`);
+
+  return parts.join(' ');
+}
+
+/**
+ * Generate human-readable waiting reason based on threshold violation.
+ * @param {string} metric - The metric name (ram, cpu, disk, etc.)
+ * @param {number} currentValue - Current value (as percentage 0-100)
+ * @param {number} threshold - Threshold ratio (0.0 - 1.0)
+ * @returns {string} Human-readable reason
+ */
+export function formatWaitingReason(metric, currentValue, threshold) {
+  const thresholdPercent = formatThresholdPercent(threshold);
+  const currentPercent = Math.round(currentValue);
+
+  switch (metric) {
+    case 'ram':
+      return `RAM usage is ${currentPercent}% (threshold: ${thresholdPercent})`;
+    case 'cpu':
+      return `CPU usage is ${currentPercent}% (threshold: ${thresholdPercent})`;
+    case 'disk':
+      return `Disk usage is ${currentPercent}% (threshold: ${thresholdPercent})`;
+    case 'claude_5_hour_session':
+      return `Claude 5 hour session limit is ${currentPercent}% (threshold: ${thresholdPercent})`;
+    case 'claude_weekly':
+      return `Claude weekly limit is ${currentPercent}% (threshold: ${thresholdPercent})`;
+    case 'codex_5_hour_session':
+      return `Codex 5 hour session limit is ${currentPercent}% (threshold: ${thresholdPercent})`;
+    case 'codex_weekly':
+      return `Codex weekly limit is ${currentPercent}% (threshold: ${thresholdPercent})`;
+    case 'github':
+      return `GitHub API usage is ${currentPercent}% (threshold: ${thresholdPercent})`;
+    case 'min_interval':
+      return 'Minimum interval between commands not reached';
+    case 'claude_running':
+      return 'Claude process is already running';
+    case 'codex_running':
+      return 'Codex process is already running';
+    default:
+      return `${metric} threshold exceeded`;
+  }
+}